FinClaw Engineering-Start Gap Analysis
本文分析治理库 V1 Design（已通过 Controller review）与工程仓库 /Users/mlabs/Programs/fin-claw 当前实现之间的 gap。目的是为 Engineering-start gate 提供工程方案拆解输入。
1. 工程仓库当前架构概述
fin-claw/server/
├── agent/
│ ├── runtime.py # AgentRuntime — ReAct 循环（611 行）
│ ├── llm_client.py # LLMClient 协议 + Anthropic/Gemini/OpenAI 适配器（729 行）
│ ├── skill_manager.py # Skill 发现/注册/按需读取（170 行）
│ ├── tool_registry.py # 工具注册中心（内置 + MCP）
│ ├── context_engine.py # System Prompt 构建 + Token 压缩
│ ├── session_store.py # 会话与轨迹持久化（JSONL）
│ ├── models.py # 数据模型（150 行）
│ ├── event_sink.py # SSE 事件发射协议
│ └── incremental_json.py # 流式 JSON 解析
├── tools/ # 内置工具（@builtin_tool 注册）
├── skills/ # Skill 定义（Markdown + YAML frontmatter）
├── api/ # FastAPI + TG Bot 适配器
├── config/ # MCP Server 声明
├── data/ # 运行时数据
└── tests/ # 测试
已实现能力：
- 3 个 LLM provider（Anthropic Claude / Google Gemini / OpenAI Compatible）
- ReAct 循环 + 工具调用 + 流式输出
- 三阶护栏（输入 / 过程 / 输出）
- Skill 发现与按需读取
- MCP 工具协议集成
- SSE 事件流（task_started / reasoning_step / partial_result / task_completed / task_failed）
- 会话持久化（JSONL）
- Token 预算管理与上下文压缩
2. 核心 Gap：数据模型
2.1 当前模型（旧架构）
工程仓库 models.py 定义的核心输出对象是 MarketIntelligence：
| 当前字段 | V1 Design 对应 | Gap |
|---|---|---|
ticker | cognition_object | 窄化为单一标的，V1 需要资产/主题/事件/叙事/问题 |
sentiment_score (0-100) | 无 | V1 不使用数值情绪评分作为正式输出 |
fact_score (0-100) | 无 | V1 用 EvidenceItem + DataQualityNote 替代 |
bull_case | main_thesis + supporting_reasons | 需拆分为结构化字段 |
bear_case | counter_thesis | 需拆分为数组 |
conclusion | execution_boundary | V1 禁止"操作性建议"作为 conclusion |
evidences (Evidence) | evidence_items (EvidenceItem) | 字段结构完全不同 |
action_suggestions (ActionSuggestion) | forbidden | V1 明确标记为 legacy，必须移除 |
reasoning_path | 保留在 trajectory，不进入产品对象 | 可保留为内部 trace |
2.2 V1 需要但不存在的模型
| V1 对象 | 工程仓库状态 | 优先级 |
|---|---|---|
MarketCognitionSnapshot (28 字段) | 不存在 | P0 |
MarketCognitionThread (16 字段 + 7 状态) | 不存在 | P0 |
PreExecutionCheckpoint (14 字段 + forbidden list) | 不存在 | P0 |
EvidenceItem (8 字段) | 部分存在（Evidence 模型，但字段不同） | P0 |
DataQualityNote (6 字段) | 不存在 | P0 |
AdvisorOutput (11 字段) | 不存在 | P1 |
UserContext (9 字段) | 不存在 | P1 |
ProfileConsent (8 字段) | 不存在 | P1 |
SensitiveInputHandling (7 字段) | 不存在（护栏存在但不生成记录对象） | P1 |
TrainingAssetCandidate (8 字段) | 不存在 | P2 |
2.3 必须移除的 legacy 模型
| 模型 | 原因 | 处置 |
|---|---|---|
ActionSuggestion | V1 明确标记为 legacy，不得作为正式对象 | 删除类定义；runtime 中所有引用改为 PreExecutionCheckpoint |
MarketIntelligence | 旧架构核心输出，字段与 V1 不兼容 | 重构为 MarketCognitionSnapshot |
3. 核心 Gap：Agent 编排
3.1 当前编排
工程仓库的 AgentRuntime 是单层 ReAct 循环：
用户输入 → 输入护栏 → 构建上下文 → LLM 循环（thought/action/observation）→ 输出护栏 → MarketIntelligence
没有：
- Task Router（任务类型识别）
- Advisor Planner（顾问选择）
- 多顾问协调
- Object Writer（对象化写入）
- Boundary Guard（作为独立层）
3.2 V1 设计的 8 层编排
| 层 | 当前状态 | Gap |
|---|---|---|
| Task Router | 不存在（LLM 自行判断） | 需要独立 task recognition 逻辑，映射 7 种路由 |
| Context Builder | 部分存在（context_engine.py） | 需要扩展支持 Thread 上下文装载、evidence state、profile consent |
| Advisor Planner | 不存在 | 需要实现顾问选择逻辑 |
| Skill Runtime | 部分存在（skill_manager + tool_registry） | 需要结构化输出约束 |
| Evidence / Quality Checker | 不存在 | 需要实现 |
| Object Writer | 不存在 | 需要实现 Snapshot/Thread/Checkpoint 写入层 |
| Boundary Guard | 部分存在（_input_guardrail + _post_run_validate） | 需要提升为独立层，增加 forbidden fields 检查 |
| Feedback Adapter | 不存在 | 需要实现 |
3.3 当前护栏 vs V1 Boundary Guard
当前护栏基于关键词匹配（_FORBIDDEN_PATTERNS），只拦截明确的交易指令。V1 要求：
- 检查输出中是否包含 forbidden execution fields（
order_side,quantity,leverage等 12 个字段） - 检查 action-adjacent 内容是否被正确降级为 PreExecutionCheckpoint
- 检查证据声明是否有对应 EvidenceItem
- 对 credential/private key 输入有结构化拒收记录
4. 核心 Gap：持久化与 Thread
4.1 当前持久化
- session_store.py：JSONL 格式存储消息和轨迹
- 按 user_id + session_id 索引
- 无 Thread 概念
4.2 V1 需要
- Thread 作为一等持久化对象（7 状态生命周期）
- Snapshot 不可被覆盖（历史保留）
- Refresh 变更记录（diff）
- Thread 关联多个 Snapshot
- Pause / Close / Merge / Split 操作
- Profile consent 状态持久化
5. 核心 Gap：API 层
5.1 当前 API
POST /api/tasks→ SSE stream →MarketIntelligence- TG Bot 适配器
TaskRequest使用AnalysisVectorenum
5.2 V1 需要
- Snapshot API（创建 / 查询 / 列表）
- Thread API（创建 / 刷新 / 暂停 / 关闭 / 合并 / 拆分 / 列表）
- Checkpoint API（查询 / 列表）
- Feedback API
- 用户画像与偏好 API
AnalysisVector→ Task Router 的 7 种路由
6. 可复用资产
以下现有实现可直接复用或小幅适配：
| 资产 | 复用度 | 说明 |
|---|---|---|
LLMClient 协议 + 3 个适配器 | 高 | 无需改动；V1 不改变 LLM provider 层 |
SkillManager | 高 | Skill 发现机制兼容 V1 FinSkills 设计 |
ToolRegistry + MCP 集成 | 高 | 无需改动 |
ContextEngine token 预算 | 中 | 需要扩展支持 V1 §10C context priority |
SessionStore JSONL 基础 | 中 | 需要扩展支持 Thread/Snapshot 持久化 |
| SSE 事件流架构 | 中 | 事件类型需要重新定义 |
| 三阶护栏框架 | 中 | 逻辑需要提升为 Boundary Guard |
| ReAct 循环框架 | 中 | 需要在循环内嵌入 Task Router / Advisor / Object Writer |
incremental_json.py | 高 | 流式解析可复用 |
7. 工程方案拆解建议
Phase 1：数据模型重构（P0，预计 3-5 天）
- 在
models.py中新增 V1 核心对象：MarketCognitionSnapshot、MarketCognitionThread、PreExecutionCheckpoint、EvidenceItem、DataQualityNote - 标记
ActionSuggestion和MarketIntelligence为 deprecated，保留兼容但不作为新输出 - 新增 SSE 事件类型适配新对象
- 新增 Thread 状态枚举和生命周期模型
Phase 2：编排层重构（P0，预计 5-8 天）
- 从
runtime.py中抽取 Task Router 层（独立模块） - 实现 Object Writer 层（Snapshot/Thread/Checkpoint 写入）
- 提升 Boundary Guard 为独立层，增加 forbidden fields 检查
- 实现 Advisor Planner 基础版（基于 task_type 选择顾问组合）
- 保持 ReAct 循环核心不变，在循环前后加入新层
Phase 3：Thread 持久化（P0，预计 3-5 天）
- 扩展
session_store.py或新建thread_store.py - 实现 Thread CRUD + 状态转换
- 实现 Snapshot 不可覆盖机制
- 实现 Refresh 变更记录
Phase 4：API 层重构（P1，预计 3-5 天）
- 新增 Snapshot / Thread / Checkpoint REST API
- 重构 SSE 事件流
- 保留 TG Bot 适配器，适配新对象
Phase 5：Evaluation Runner（P1，预计 2-3 天）
- 对接
evaluation/finclaw/cases/6 个 YAML case - 实现 field-level check 自动化
- 输出 run result 到
evaluation/finclaw/runs/
Phase 6：UI Shell（P1，预计 5-8 天）
- 按 V1 UI/UX Design 实现 Web 前端 shell
- Home / Snapshot View / Thread View / Checkpoint View / Evidence Drawer / Feedback
8. 风险与约束
- 不得在工程重构中恢复 ActionSuggestion：V1 设计明确标记为 legacy。
- 不得跳过 Thread 作为一等对象：Thread 是 V1 持续价值核心，不能用聊天历史替代。
- Boundary Guard 必须在对象写入前运行：不能只靠输出后处理。
- 工程仓库中的金融逻辑仍在 Skills 中：runtime.py 不硬编码金融逻辑（与 CLAUDE.md 规则一致）。
9. Engineering-start gate 前置条件
按 V1 Evaluation Review and Acceptance Plan §2，Engineering-start 需要同时满足：
- ✅ 所有核心路径能映射到 Snapshot、Thread 或 PreExecutionCheckpoint
- ⬜ UI 状态和 schema 状态一致（待工程实现后验证）
- ⬜ Agent write target 不绕过对象模型（待 Object Writer 实现）
- ⬜ EvidenceItem 和 DataQualityNote 能被 UI 展示、Agent 写入、evaluation 检查
- ⬜ Sensitive input handling 在 UI、schema 和 agent guard 中一致
- ⬜ Forbidden execution fields 不出现在 schema、UI CTA 或 agent outputs
- ⬜ Evaluation cases 至少覆盖六个第一批 YAML case
- ⬜ 工程实现范围、试运营范围和后续优化范围被分开
当前 1/8 满足。Phase 1-3 完成后预计可满足 6/8（2 和 4 需要 UI 联动）。