FinClaw V1 Tech Stack and Architecture Design

状态：Accepted Initial Design / B-1 工程蓝图日期：2026-05-16 项目：FinClaw 文档级别：项目级工程蓝图（V1 落地新仓库的技术基线）上游文档：v1-prd.md、v1-engineering-kickoff-decisions.md（D-04 / D-10）、v1-model-and-provider-policy.md、v1-agent-orchestration-design.md 配套文档：v1-data-and-persistence-design.md（B-2）、v1-api-contract-design.md（B-3）

1. Purpose

本文是 FinClaw V1 新工程仓库 /Users/mlabs/Programs/CurvatureLabs/finclaw/（尚未创建，本文是其工程蓝图）的技术栈与服务架构基线。

回答 4 个工程问题：

后端用什么语言、框架、包管理、模型 SDK 抽象层？
前端用什么栈、构建工具、状态管理？
服务由哪些组件组成，组件之间如何通讯？
旧工程仓库 /Users/mlabs/Programs/fin-claw/ 的内容如何选择性迁移到新仓库？

本文不展开数据持久化字段细节（→ v1-data-and-persistence-design.md）、不展开 API endpoint 与 SSE 事件细节（→ v1-api-contract-design.md）、不重写 LLM provider 策略（已锁定在 v1-model-and-provider-policy.md）。

2. Goals and Non-Goals

2.1 Goals

Goal	落点
G-1	锁定后端 / 前端 / LLM SDK 主栈，让工程实施 sub-packet 不再讨论选型
G-2	给出新仓库的目录骨架，与 v1-engineering-kickoff-decisions.md D-10.a 迁移清单一一对齐
G-3	给出 V1 内测阶段（3 人）单机部署形态，且不预先固化生产级 Kubernetes / 多可用区方案
G-4	与 v1-agent-orchestration-design.md §2 Layers 的 8 层职责一一对应到具体模块
G-5	显式声明哪些旧仓库内容不迁移，避免「迁移漂移」

2.2 Non-Goals

Non-Goal	理由
不引入 Kubernetes / Service Mesh / 微服务拆分	V1 内测 3 人规模（v1-engineering-kickoff-decisions.md D-01），单进程足够
不引入消息队列（Kafka / Redis Streams）	V1 主路径同步生成；ReAct 内部步骤通过 SSE 推送即可
不引入数据仓库 / OLAP（ClickHouse / DuckDB）	商业信号 instrumentation 用 SQLite + 报表脚本即可（v1-commercial-signal-instrumentation-design.md §9）
不为移动端原生 app 引入 React Native / Capacitor	v1-engineering-kickoff-decisions.md D-03 Web + 响应式即可
不引入外部 channel adapter（Telegram / Discord）	v1-engineering-kickoff-decisions.md D-02 推迟到 V2
不与旧仓库共享 git history	v1-engineering-kickoff-decisions.md D-10 全新仓库

3. Backend Stack

维度	选型	锁定理由
语言	Python 3.11+	与旧仓库一致；Pydantic v2 / FastAPI 生态；与 evaluation 脚本同栈
Web 框架	FastAPI 0.110+	async-native；OpenAPI auto；SSE 友好；旧仓库已验证
ASGI server	Uvicorn（dev）/ Uvicorn + Gunicorn worker（prod-like）	单进程足够；prod-like 仅用于 trial 期 stress 测试
包管理	uv	旧仓库已采用；resolver 快；与 `pyproject.toml` 兼容
数据校验	Pydantic v2	V1 八对象（v1-product-object-and-schema-design.md §1）统一用 BaseModel；禁止用 dataclass 表达正式对象
配置	pydantic-settings v2 + YAML	secrets 走 macOS Keychain（v1-model-and-provider-policy.md §4）；不入仓
日志	structlog + JSON sink	与 evaluation runs / commercial signal events 兼容
测试	pytest + pytest-asyncio + httpx.AsyncClient	与 evaluation runner 复用 fixture
Lint / Format	ruff + mypy	旧仓库已采用
LLM SDK	openai Python SDK（统一 OpenAI-compatible 协议）	GPT-5.5 走 OpenAI；Kimi K2.6 走 Moonshot OpenAI-compatible endpoint
HTTP client	httpx	async；可复用作为 LLM provider transport
时间	datetime + zoneinfo（UTC 默认；输出转用户 tz）	不引入 pendulum / arrow 依赖

禁止依赖：

anthropic SDK（D-04 已锁定 GPT-5.5 + Kimi K2.6，不保留 Anthropic）；
google-generativeai（同上）；
python-telegram-bot、discord.py（D-02 不引入外部 channel）；
任何「订单 / 撮合 / 钱包 / 私钥」类 SDK（mvp-product-definition.md §3 边界硬约束）。

4. Frontend Stack

维度	选型	锁定理由
语言	TypeScript 5.4+	类型安全；与 zod schema 互推
构建	Vite 5+	旧仓库已采用；启动快；与 React 18 兼容
UI 框架	React 18	旧仓库已采用；SSE / Suspense 友好
路由	React Router 6.x	旧仓库已采用；不上 Next.js（V1 不需要 SSR；治理事实源是 Markdown，不是渲染服务）
状态	Zustand（domain stores） + React Query（server cache）	Zustand：轻量、与 React 18 friendly；React Query：SSE / refresh diff / thread refresh 自然适配
样式	Tailwind CSS 3.x + shadcn/ui	与 v1-ui-ux-interaction-design.md 的 Evidence Drawer / Refresh Diff / Checkpoint 阅读型 UI 匹配
Schema	zod	与 Pydantic 字段命名 1:1 对齐；前端守门
测试	Vitest + React Testing Library	单元 + 组件层
E2E（试运营前可选）	Playwright	trial 启动前用
Icons	lucide-react	与 shadcn/ui 默认搭配

为什么不选 Next.js App Router：

V1 不需要 SSR / SEO（内测产品，登录后访问）；
Vite + React Router 的开发与构建反馈循环更轻；
治理事实源是 Markdown，不需要 React Server Components 的边缘渲染能力；
后续若需要切到 Next.js，前端结构按 src/domains/* 分层，迁移成本可控。

禁止依赖：

任何「钱包连接 / Web3 wallet adapter / 链上签名」库；
任何「实时撮合行情图（K-line interactive trading widget）」库；这与 FinClaw 「认知不执行」边界冲突。

5. LLM Provider Layer

5.1 抽象接口（`server/agent/llm_client.py`）

LLM provider 抽象层是 V1 工程化的核心解耦点。所有 Skill / Advisor 调用 LLM 都必须经过 LLMClient 协议；不允许在 Skill 内部直接构造 openai.OpenAI(...)。

class LLMClient(Protocol):
    async def complete(
        self,
        messages: list[ChatMessage],
        tools: list[ToolSchema] | None = None,
        response_format: ResponseFormat | None = None,
        temperature: float = 0.2,
        max_output_tokens: int | None = None,
        request_id: str | None = None,
    ) -> LLMResponse: ...

    @property
    def provider_id(self) -> str: ...   # "gpt-5.5" / "kimi-k2.6" / "byom:<name>"

    @property
    def model_capabilities(self) -> ModelCapabilities: ...

5.2 Provider 实现矩阵

Provider	Adapter 类	Endpoint	Auth	说明
GPT-5.5	`OpenAIAdapter`	`https://api.openai.com/v1`	Keychain：`FINCLAW_OPENAI_API_KEY`	function calling / structured outputs；主结构化路径
Kimi K2.6	`MoonshotAdapter`（继承 `OpenAIAdapter`）	`https://api.moonshot.cn/v1`	Keychain：`FINCLAW_MOONSHOT_API_KEY`	OpenAI-compatible；中文叙事 / 长上下文
BYOM (OpenAI-compatible)	`OpenAIAdapter`（用户提供 base_url）	用户配置	Keychain：`FINCLAW_BYOM_<slug>_KEY`	v1-model-and-provider-policy.md §4；非默认

5.3 Provider Router（`server/agent/provider_router.py`）

按 v1-model-and-provider-policy.md §3 / §5 / §6：

输入：(skill_id_or_advisor_role, request_metadata)；
查表：config/agent_routing.yaml（v0 默认值见 v1-model-and-provider-policy.md §5）；
输出：LLMClient 实例（primary）+ ordered fallback chain；
Failover：按 v1-model-and-provider-policy.md §6 分类执行；
每次调用都通过 cost_telemetry 记录 prompt/completion/cost。

5.4 Capability Negotiation

Capability	GPT-5.5	Kimi K2.6	用途
OpenAI function calling	yes	yes（兼容）	Skill structured output
`response_format: json_schema`	yes	partial	严格 schema 输出；K2.6 不全支持时降级到 prompt-side schema
长上下文（≥ 128K）	yes	yes	Thread refresh / 长证据合并
中文领域质量	medium	high	加密叙事 / 链上信息解读
英文领域质量	high	medium	宏观 / 跨市场

ModelCapabilities 字段供 Provider Router 做能力降级（如 K2.6 不稳定支持 json_schema 时，自动切回 GPT-5.5 或 prompt-side schema）。

5.5 BYOM 边界

项	约束
启用	用户在 `~/.finclaw/config.yaml` 显式 `byom.enabled: true`（v1-model-and-provider-policy.md §4）
凭证	必须 macOS Keychain；禁止明文写配置
Fallback	失败不自动回退默认 provider
Training pipeline	BYOM 调用产物不进入 `TrainingAssetCandidate`
Telemetry	model_name 字段 `byom:<user-supplied-name>`

6. Service Components

V1 是单进程 FastAPI app + Web SPA。所有后端组件运行在同一 Python 进程内，通过函数 / 协议接口（不通过网络）交互。

6.1 组件清单（与 v1-agent-orchestration-design.md §2 Layers 对齐）

Component	Module path	职责	对应 Layer
FastAPI App	`server/api/app.py`	HTTP 入口、SSE streaming、依赖注入	（非 Agent Layer）
Auth Middleware	`server/api/auth.py`	Bearer token 校验（v1-api-contract-design.md §3）	（非 Agent Layer）
Cognition Routes	`server/api/cognition_routes.py`	Snapshot / Thread / Checkpoint REST endpoints	（非 Agent Layer）
AgentRuntime	`server/agent/runtime.py`	ReAct 循环调度，不含金融逻辑	Skill Runtime + Advisor Planner
Task Router	`server/agent/task_router.py`	7 类 route 识别（v1-agent-orchestration-design.md §3）	Task Router
Context Engine	`server/agent/context_engine.py`	system prompt 构建、token 估算、上下文压缩	Context Builder
Skill Manager	`server/agent/skill_manager.py`	加载 `skills/*/SKILL.md` + YAML frontmatter；按 router 选 skill	Skill Runtime
Tool Registry	`server/agent/tool_registry.py`	注册内置 tools（`@builtin_tool` 装饰器） + MCP tools	Skill Runtime
Advisor Planner	`server/agent/advisor_planner.py`	6 个 Advisor 选择 + 多 Advisor 协调（v1-agent-orchestration-design.md §10A）	Advisor Planner
Object Writer	`server/agent/object_writer.py`	写 Snapshot / Thread / Checkpoint；拒禁字段	Object Writer
Boundary Guard	`server/agent/boundary_guard.py`	行动邻近检测、forbidden field 拦截（v1-agent-orchestration-design.md §8）	Boundary Guard
Sensitive Input Classifier	`server/agent/sensitive_input.py`	4 类输入分类（v1-product-object-and-schema-design.md §9）	Boundary Guard 子组件
Evidence / Quality Checker	`server/agent/evidence_checker.py`	EvidenceItem / DataQualityNote 字段标注	Evidence / Quality Checker
Cognition Store	`server/agent/cognition_store.py`	Snapshot / Thread / Checkpoint / EvidenceItem 等持久化（v1-data-and-persistence-design.md）	（非 Agent Layer）
Event Sink	`server/agent/event_sink.py`	SSE event 推送 + commercial signal events	（横切）
LLM Client	`server/agent/llm_client.py`	§5.1 协议 + adapters	（横切）
Provider Router	`server/agent/provider_router.py`	§5.3 任务 → provider 映射 + failover	（横切）
Cost Telemetry	`server/agent/cost_telemetry.py`	每次 LLM 调用 token / cost 落盘（v1-model-and-provider-policy.md §7.3）	（横切）
Feedback Adapter	`server/api/feedback_routes.py`	试运营反馈与人工复核 queue	Feedback Adapter

6.2 数据流（一次 Snapshot 任务）

flowchart TD
  Browser[Web Client] -->|POST /api/tasks| FastAPI[FastAPI App]
  FastAPI -->|SSE stream| Browser
  FastAPI --> Auth[Auth Middleware]
  Auth --> Routes[Cognition Routes]
  Routes --> Runtime[AgentRuntime]
  Runtime --> Router[Task Router]
  Router --> Context[Context Engine]
  Context --> Sensitive[Sensitive Input Classifier]
  Sensitive --> Planner[Advisor Planner]
  Planner --> ProviderRouter[Provider Router]
  ProviderRouter --> LLM[LLM Client / GPT-5.5 or Kimi K2.6]
  Planner --> Skills[Skill Manager → SKILL.md]
  Skills --> Tools[Tool Registry]
  Tools -->|crypto_data, etc.| External[External APIs / MCP]
  Planner --> Evidence[Evidence Checker]
  Planner --> Writer[Object Writer]
  Writer --> Guard[Boundary Guard]
  Guard --> Store[Cognition Store → filesystem]
  Writer --> EventSink[Event Sink]
  EventSink -->|SSE events| FastAPI
  Writer --> Telemetry[Cost Telemetry]

6.3 进程模型

模式	用途	启动命令
dev	单进程 + auto-reload	`make run` → `uvicorn server.api.app:app --reload`
prod-like (trial)	单进程 + Uvicorn + 1 worker	`docker compose up`
eval	同 dev，但走 evaluation runner	`make eval` → `python -m server.scripts.run_evaluation`

V1 不为单 Snapshot 任务引入 worker pool / Celery / Redis。ReAct 循环在请求线程内执行；SSE 事件通过 EventSink 推送回浏览器。

7. Repository Skeleton

新工程仓库 /Users/mlabs/Programs/CurvatureLabs/finclaw/（待创建）目录骨架：

finclaw/
├── README.md                   ← 工程入口
├── AGENTS.md                   ← 项目规范（含与治理库的回链）
├── CLAUDE.md                   ← 同 AGENTS.md（兼容 Claude Code）
├── Makefile                    ← 顶层命令
├── docker-compose.yml          ← 单机部署（§8）
├── .env.example                ← 不入仓的 env 模板
├── .gitignore
├── pyproject.toml              ← uv workspace root（含 server / scripts）
├── uv.lock
│
├── docs/                       ← 工程仓库内的实施文档（不与治理库重复）
│   ├── architecture.md         ← 链回本文 + alignment snapshot
│   ├── runbooks/
│   │   ├── start-dev.md
│   │   ├── trial-deploy.md
│   │   └── kill-switch.md
│   └── adr/                    ← Architecture Decision Records (非治理决策)
│
├── server/                     ← Python 后端
│   ├── __init__.py
│   ├── main.py                 ← uvicorn entrypoint
│   ├── api/
│   │   ├── app.py              ← FastAPI app factory
│   │   ├── auth.py             ← Bearer token middleware
│   │   ├── cognition_routes.py ← Snapshot/Thread/Checkpoint endpoints
│   │   ├── consent_routes.py   ← ProfileConsent endpoints
│   │   ├── feedback_routes.py  ← Feedback / human review queue
│   │   ├── commercial_events.py← CS instrumentation routes
│   │   ├── sse.py              ← SSE helper
│   │   └── errors.py           ← Error schema
│   │
│   ├── agent/
│   │   ├── runtime.py          ← AgentRuntime (ReAct loop)
│   │   ├── task_router.py
│   │   ├── context_engine.py
│   │   ├── skill_manager.py
│   │   ├── tool_registry.py
│   │   ├── advisor_planner.py
│   │   ├── object_writer.py
│   │   ├── boundary_guard.py
│   │   ├── sensitive_input.py
│   │   ├── evidence_checker.py
│   │   ├── cognition_store.py
│   │   ├── event_sink.py
│   │   ├── llm_client.py       ← Protocol + adapters
│   │   ├── provider_router.py
│   │   ├── cost_telemetry.py
│   │   └── models.py           ← All Pydantic v2 models
│   │
│   ├── tools/                  ← @builtin_tool 注册的工具
│   │   ├── __init__.py
│   │   ├── crypto_data.py      ← 迁移自旧仓库 (D-10.a)
│   │   └── ...
│   │
│   ├── skills/                 ← Markdown SKILL.md + YAML frontmatter
│   │   ├── snapshot/
│   │   │   ├── SKILL.md
│   │   │   └── prompts/
│   │   ├── pre_execution/
│   │   ├── risk_challenge/
│   │   ├── evidence_audit/
│   │   ├── thread_ops/
│   │   ├── narrative_mapper/
│   │   ├── event_impact_reader/
│   │   └── _disabled/          ← D-07 停用 Skill 移到此处
│   │
│   ├── config/
│   │   ├── app.yaml            ← FastAPI / runtime config
│   │   ├── agent_routing.yaml  ← Skill/Advisor → Provider 映射
│   │   ├── provider_routing.yaml
│   │   ├── boundaries.yaml     ← forbidden execution fields
│   │   └── mcp_servers.yaml    ← MCP servers 声明
│   │
│   ├── scripts/
│   │   ├── run_evaluation.py
│   │   ├── seed_user.py        ← Labs 内测 3 用户初始化
│   │   ├── export_user_data.py ← Privacy / GDPR-friendly export
│   │   └── kill_switch.py      ← Stop trial
│   │
│   └── tests/
│       ├── conftest.py
│       ├── test_boundary_guard.py
│       ├── test_object_writer.py
│       ├── test_provider_router.py
│       ├── test_sensitive_input.py
│       ├── test_cognition_store.py
│       └── ...
│
├── web/                        ← React + TypeScript SPA
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── tailwind.config.ts
│   ├── index.html
│   └── src/
│       ├── main.tsx
│       ├── Root.tsx
│       ├── App.tsx
│       ├── api/
│       │   ├── client.ts        ← typed REST client (zod)
│       │   └── sse.ts           ← SSE event subscriber
│       ├── domains/             ← Domain-driven slice (与旧仓库一致)
│       │   ├── analysis/
│       │   ├── cognition/
│       │   ├── dashboard/
│       │   ├── onboarding/
│       │   ├── task/
│       │   └── feedback/
│       ├── pages/
│       │   ├── home/
│       │   ├── analysis/
│       │   ├── cognition/
│       │   └── dashboard/
│       ├── components/          ← shadcn/ui shell
│       ├── foundation/          ← shared UI primitives
│       └── lib/                 ← utils, hooks, zod schemas
│
├── data/                       ← 运行时数据（gitignored 除 README）
│   ├── README.md
│   ├── cognition/              ← Snapshot / Thread / Checkpoint JSONL
│   ├── consents/               ← ProfileConsent files
│   ├── traces/                 ← ReAct traces
│   ├── events/                 ← SSE / commercial signal events
│   └── eval/                   ← Local eval runs
│
├── evaluation/                 ← Eval cases + runners
│   ├── cases/                  ← 6 V1 cases + 7 edge cases (D-10.a)
│   ├── runner/                 ← Field-level grader
│   └── runs/                   ← <timestamp>/ archives
│
└── .github/                    ← CI（trial 启动前最少 lint + test）
    └── workflows/
        ├── ci.yml
        └── eval-smoke.yml

7.1 与旧仓库结构差异

维度	旧仓库 `/Users/mlabs/Programs/fin-claw/`	新仓库
Skills 位置	`server/skills/`	同（保留路径）
Anthropic SDK	`server/agent/llm_client.py` 含 Anthropic adapter	删除，仅 OpenAI-compatible
Telegram	`server/api/telegram*.py`	不存在（D-02）
Web 状态	已有 Zustand + React Query 雏形	沿用结构，UI 重写
设计文档	`docs/design/01-09-*.md`	不复制；`docs/` 改为 runbook + ADR + alignment snapshot
ProfileConsent / SensitiveInputHandling / TrainingAssetCandidate	部分实现	按 v1-product-object-and-schema-design.md §8/§9/§11 重写

8. Deployment Model

8.1 V1 部署形态

形态	用途	描述
local-dev	开发	`make run` 单进程；用 `~/.finclaw/config.yaml` 本地配置
docker-compose-trial	Labs 内测	单 host docker-compose；后端 + 前端 + nginx 反向代理
eval	评测	local-dev 模式下跑 `make eval`

不部署：

Kubernetes；
AWS / GCP managed services；
独立数据库实例（V1 文件持久化为主，v1-data-and-persistence-design.md §3）；
CDN / 边缘节点；
多 region。

8.2 docker-compose 拓扑

services:
  finclaw-server:
    build: ./server
    env_file: .env
    volumes:
      - ./data:/app/data
      - ./evaluation:/app/evaluation
    ports: ["18800:8000"]
    restart: unless-stopped

  finclaw-web:
    build: ./web
    ports: ["18801:80"]   # nginx serves built SPA
    depends_on: [finclaw-server]
    restart: unless-stopped

  finclaw-nginx:
    image: nginx:alpine
    volumes:
      - ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    ports: ["18810:80"]   # 唯一对外端口
    depends_on: [finclaw-server, finclaw-web]

8.3 Secret / Config

项	来源	存放位置
`FINCLAW_OPENAI_API_KEY`	macOS Keychain → docker `--env` 注入	不入仓
`FINCLAW_MOONSHOT_API_KEY`	同上	不入仓
`FINCLAW_BEARER_TOKEN`	启动时生成；分发给 3 名内测用户	不入仓
Provider routing 配置	`server/config/agent_routing.yaml`	入仓
业务边界 (forbidden fields)	`server/config/boundaries.yaml`	入仓（boundary guard 必须可被代码 review）

8.4 Observability（V1 最小集）

应用日志：structlog JSON → docker stdout；
LLM telemetry：data/eval/llm_telemetry.jsonl；
Commercial signal events：data/events/cs/*.jsonl（v1-commercial-signal-instrumentation-design.md §9）；
健康检查：GET /api/health（v1-api-contract-design.md §4）；
Trace 文件：data/traces/<task_id>.jsonl；
不接入 Datadog / Sentry / Grafana（V1 内测期手工 grep + tail 即可）。

8.5 Kill Switch

按 v1-engineering-kickoff-decisions.md D-06：

python -m server.scripts.kill_switch --reason "<RB-N>" → 写 data/.kill_switch 文件 → API 中间件读到后所有非健康请求返回 503 + 错误码 TRIAL_HALTED；
解除：python -m server.scripts.kill_switch --resume。

9. Migration from Legacy Repo

9.1 总策略

按 v1-engineering-kickoff-decisions.md D-10：

新仓库重建，旧仓库 /Users/mlabs/Programs/fin-claw/ 做对照参考；不共享 git history；逐组件 review-then-migrate，不做一次性 cp -r。

9.2 迁移工序（与 D-10.b 对齐 + 工程化补充）

步骤	描述	验收
W-1	新仓库 `git init`；创建 §7 骨架空目录 + `pyproject.toml` + `package.json`	`make install` 可运行
W-2	移植 `server/agent/models.py`（V1 八对象 Pydantic v2）	`pytest server/tests/test_models.py`
W-3	移植 `server/agent/cognition_store.py`（按 v1-data-and-persistence-design.md 重组路径）	CRUD 测试通过
W-4	移植 `server/agent/context_engine.py` + `boundary_guard.py` + `object_writer.py`	边界单元测试通过
W-5	新写 `server/agent/llm_client.py` + GPT-5.5 / Kimi K2.6 adapters（D-04）	对真实 endpoint 烟测 1 次
W-6	移植 7 个 V1 Skill（snapshot / pre_execution / risk_challenge / evidence_audit / thread_ops / narrative_mapper / event_impact_reader）	Skill manifest 加载测试
W-7	移植 `tools/crypto_data.py`	工具调用烟测
W-8	移植 evaluation cases（6 V1 + 7 edge）→ `evaluation/cases/`，并同步治理库 `evaluation/finclaw/cases/`	`make eval` 跑通
W-9	移植 web 前端基础架构（Vite + React + Tailwind + shadcn shell），UI 按 v1-ui-ux-interaction-design.md 重写	dev server 启动 + 主路径渲染
W-10	接入 SSE + REST API（v1-api-contract-design.md）	E2E：1 次 snapshot 生成
W-11	旧仓库 README 加 deprecation banner（指向新仓库）	banner 出现

9.3 显式不迁移清单

旧路径	不迁移理由
`server/api/telegram*.py`	D-02 不引入外部 channel
`server/agent/*` 中所有 Anthropic 引用	D-04 不保留 Anthropic
`docs/design/01-09-*.md`	旧设计文档；治理库已替代为 V1 设计包
`server/skills/_default/`、`server/skills/market_audit/`	D-10.a 不迁移
旧 500 个测试中与 Anthropic / Telegram / 旧模型 schema 相关的 ~30%	D-10.a 选择性迁移
旧仓库 `data/` 中 trial 期前的真实运行数据	不带历史 PII / 用户数据；新仓库 `data/` 从空开始

9.4 旧仓库的去向

团队成员仍可在旧仓库自由工作（不冻结主分支）；
旧仓库 README.md 增加 deprecation banner：「V1 工程化已迁移至 /Users/mlabs/Programs/CurvatureLabs/finclaw/，本仓库仅作历史参考」；
不删除、不归档；后续 6 个月内若发现旧仓库有未迁移的隐性资产，按本节工序补迁。

9.5 Migration 期间的双仓库期

时间区间	状态
W-1 ~ W-10	旧仓库继续可运行（团队对照）；新仓库逐渐成型
W-11 ~ Trial-start	新仓库唯一可运行；旧仓库进入对照参考状态
Trial 结束后	旧仓库可全部归档（视项目发起人决议）

迁移期间不双写 / 双读 / 数据同步：旧仓库的 data/ 不导入新仓库。

10. Constraints

10.1 边界硬约束（与 mvp-product-definition.md §3 / §15 对齐）

任何后端 / 前端 / LLM 层实现不得：

注入「订单 / 仓位 / 杠杆 / 钱包 / 私钥 / 助记词 / API key」字段到 Pydantic 模型；
调用任何「真实交易撮合 / 链上转账 / 钱包签名」API；
在 LLM Tool 列表中暴露「下单 / 调仓 / 自动执行」类工具；
在前端 UI 渲染「Buy / Sell / Long / Short button」、「leverage slider」、「auto execute toggle」、「wallet connect」；
把 Pre-Execution Checkpoint 字段直接 POST 到外部 trading 系统（Trading Matrix 集成需另外授权契约，v1-product-object-and-schema-design.md §5.2）。

如发现违例，立即触发 Boundary Guard 拒绝；CI lint 通过 evaluation/cases/edge-*.yaml 守门。

10.2 工程层约束

约束	描述
单进程	V1 不上多进程 / 多机；async 内并发足够
文件持久化	V1 默认文件系统（v1-data-and-persistence-design.md §3）；不预先引入 Postgres
同步 ReAct	不引入消息队列；ReAct loop 在请求线程内执行
单租户	V1 每个用户的数据物理隔离到 `data/cognition/<user_id>/`；不跨用户
无 cron	V1 不实现自动 thread refresh；refresh 由用户手动触发
无 webhook out	不主动推送给外部系统（D-02）

10.3 与既有设计的强对齐

§5 LLM Provider Layer 必须实现 v1-model-and-provider-policy.md §3 / §5 / §6 / §7 的全部能力（任务分流、failover、cost telemetry、BYOM）；
§6 Service Components 与 v1-agent-orchestration-design.md §2 Layers 8 层 1:1 对应；
§7 Repository Skeleton 与 v1-engineering-kickoff-decisions.md D-10.a 迁移清单一一对应；
§8 Deployment Model 与 v1-engineering-kickoff-decisions.md D-01 / D-06 内测 3 人 / Kill Switch 责任人对齐；
§10.1 边界硬约束反向锁定 mvp-product-definition.md §3 与 v1-product-object-and-schema-design.md §5.2 Forbidden Fields。

11. Open Items

O-1：CI 平台选型（GitHub Actions vs 其他）— Labs 内测期默认 GitHub Actions 最小集（lint + test + eval-smoke），trial 启动前再决定是否扩展；
O-2：是否在 docker-compose 中接入 SQLite 容器作为 commercial signal events sink — 待 Wave 2 的 telemetry 设计文档锁定；
O-3：BYOM 兼容性测试矩阵的具体 fixture provider — 与 v1-model-and-provider-policy.md §8 Open Items 同步；
O-4：Trial 期间 nginx 是否需要 HTTPS（即使局域网） — 待与项目发起人确认 trial 物理网络拓扑后定；
O-5：旧仓库 deprecation banner 的具体措辞与 PR 提交人 — 待迁移工序 W-11 临近时与项目发起人对齐。

1. Purpose​

2. Goals and Non-Goals​

2.1 Goals​

2.2 Non-Goals​

3. Backend Stack​

4. Frontend Stack​

5. LLM Provider Layer​

5.1 抽象接口（server/agent/llm_client.py）​

5.2 Provider 实现矩阵​

5.3 Provider Router（server/agent/provider_router.py）​

5.4 Capability Negotiation​

5.5 BYOM 边界​

6. Service Components​

6.1 组件清单（与 v1-agent-orchestration-design.md §2 Layers 对齐）​

6.2 数据流（一次 Snapshot 任务）​

6.3 进程模型​

7. Repository Skeleton​

7.1 与旧仓库结构差异​

8. Deployment Model​

8.1 V1 部署形态​

8.2 docker-compose 拓扑​

8.3 Secret / Config​

8.4 Observability（V1 最小集）​

8.5 Kill Switch​

9. Migration from Legacy Repo​

9.1 总策略​

9.2 迁移工序（与 D-10.b 对齐 + 工程化补充）​

9.3 显式不迁移清单​

9.4 旧仓库的去向​

9.5 Migration 期间的双仓库期​

10. Constraints​

10.1 边界硬约束（与 mvp-product-definition.md §3 / §15 对齐）​

10.2 工程层约束​

10.3 与既有设计的强对齐​

11. Open Items​