FinClaw V1 Governance ↔ Engineering Alignment Snapshot
状态：Accepted Initial Snapshot / 第一次治理↔工程对齐审计
日期：2026-05-16
项目：FinClaw
文档级别：项目级 alignment audit
上游文档：v1-prd.md、v1-product-object-and-schema-design.md、v1-agent-orchestration-design.md、v1-ui-ux-interaction-design.md、v1-evaluation-initial-plan.md
工程仓库：fin-claw（FinClaw V1 Engineering Repository）
本文用一张可机器化扫描的对照表，记录治理库 V1 设计与工程仓库 fin-claw/server/、fin-claw/web/ 当前实现的对齐状态。它是 v1-execution-plan-and-milestones.md M-B9 的产出物，并在每次 Engineering milestone 完成后刷新。
本文不是工程实现规范，不冻结代码细节，不替代 v1-product-object-and-schema-design.md 等设计源；它只追踪「实现到达哪一步」。
1. Status Legend
| Status | 含义 |
|---|---|
aligned-strict | 实现与 V1 设计字段、状态、契约一一对齐 |
aligned-initial | 主结构对齐，部分可选字段或 trial 字段尚未实现 |
partial | 主结构存在，但有显著差异（命名 / 边界 / 行为） |
legacy | 实现仍是旧模型 / 旧语义，必须重构或废弃 |
missing | 治理库定义存在但工程未实现 |
extra-not-required | 工程实现的能力，但治理库 V1 未要求（不视为问题，记录备查） |
forbidden-found | 工程实现包含 V1 禁止的字段 / 行为，必须立即清除 |
2. Object Model Alignment
| Governance Object | Source of truth | Engineering symbol | Status | Notes |
|---|---|---|---|---|
MarketCognitionSnapshot | Schema §3 | server/agent/models.py | aligned-initial | 21 字段已实现；pre_execution_checkpoint_refs / thread_proposal 为 trial 字段，evaluation 未充分验证 |
MarketCognitionThread | Schema §4 | server/agent/models.py | aligned-initial | 18 字段已实现，含 cognition_changes；merged / split lifecycle 实现待验证 |
PreExecutionCheckpoint | Schema §5 | server/agent/models.py | aligned-initial | 14 字段已实现；forbidden_execution_fields 列已配置；boundary guard 单测覆盖见 tests/test_boundary_guard.py |
EvidenceItem | Schema §6.1 | server/agent/models.py | aligned-initial | 8 字段；trial 字段，UI Drawer 已渲染 |
DataQualityNote | Schema §6.2 | server/agent/models.py | aligned-initial | 6 字段；trial 字段 |
AdvisorOutput | Schema §7 | server/agent/models.py | aligned-initial | 11 字段；写入目标已通过 ObjectWriter 校验 |
UserContext | Schema §8.1 | server/agent/models.py | partial | 部分字段已实现，但 sensitive_classification 与 SensitiveInputHandling 联动尚未端到端验证 |
ProfileConsent | Schema §8.2 | （未定位） | missing | 工程层暂无 ProfileConsent 持久化与 UI 确认流程；M-B7 必须补齐 |
SensitiveInputHandling | Schema §9 | 部分实现于 boundary guard | partial | 凭证拒收路径存在；分类记录、人工复核入口、masking 详细日志待验证 |
TrainingAssetCandidate | Schema §11 | （未定位） | missing | 训练资产候选治理元数据未在工程层落地；试运营前不强制，但 trial 数据进入训练池前必须实现 |
3. Skills Alignment
| Governance FinSkill (Agent §5) | Engineering Skill folder | Status | Notes |
|---|---|---|---|
asset-context-summarizer | （未定位独立 skill） | partial | 能力存在但未独立成 skill；建议在工程层显式拆分以便 evaluation |
event-impact-reader | server/skills/event_impact_reader/SKILL.md | aligned-initial | 已实现 |
narrative-mapper | server/skills/narrative_mapper/SKILL.md | aligned-initial | 已实现 |
risk-controversy-mapper | server/skills/risk_challenge/SKILL.md | partial | 命名差异（risk_challenge vs risk-controversy-mapper），需对齐 |
watch-question-generator | （集成于 snapshot / thread_ops） | partial | 没有独立 skill；需要 evaluation 校验 watch_questions 生成质量 |
strategy-hypothesis-framer | server/skills/pre_execution/SKILL.md | aligned-initial | 在 pre_execution skill 中实现 |
source-quality-checker | server/skills/evidence_audit/SKILL.md | partial | 命名差异（evidence_audit vs source-quality-checker），需对齐或写入术语映射 |
sensitive-input-classifier | （集成于 boundary guard） | partial | 集成实现，需要独立 evaluation |
附加 Skills（治理库未列但工程实现，标 extra-not-required）：
server/skills/snapshot/SKILL.mdserver/skills/thread_ops/SKILL.mdserver/skills/market_audit/SKILL.mdserver/skills/_default/SKILL.md
这些不是问题，是 Engineering 为工程闭环引入的辅助 Skill；但需要在术语对照表中说明它们与 V1 顾问/技能层的关系，避免外人误读为「V1 增加了对外 Skill 范围」。
4. Layer / Route Alignment
| Governance Layer (Agent §2-§3) | Engineering symbol | Status | Notes |
|---|---|---|---|
| Task Router | server/agent/task_router.py | aligned-initial | 7 类 route 已实现 |
| Context Builder | server/agent/context_engine.py | aligned-initial | 上下文优先级与 §10C budget 规则对齐情况待 audit |
| Advisor Planner | （集成于 runtime） | partial | 顾问预算（≤5 advisor / turn）落地未验证 |
| Skill Runtime | server/agent/skill_manager.py | aligned-initial | 已实现 |
| Evidence / Quality Checker | server/skills/evidence_audit/ | partial | 见 §3 命名差异 |
| Object Writer | server/agent/object_writer.py | aligned-initial | 写入目标限制已实现 |
| Boundary Guard | server/agent/boundary_guard.py | aligned-initial | 拒禁字段 + 测试覆盖 |
| Feedback Adapter | （部分集成） | partial | 反馈写入路径存在，但人工复核 queue 与 trial signals 流尚未串通 |
4A. Route Ontology Master Table（单一权威）
目的：跨治理库（自然语言 route 名 / Advisor 角色名 / 可读 Skill 名）与工程库（
Routeenum /advisor_id/ skill folder name /_ROUTE_INSTRUCTIONSkey）之间，消除别名歧义，给所有 sub-packet / agent 提供一张可机器扫描的对照表。任何引入新 route / advisor / skill 的改动必须先更新本表，再改 code。任何「叫法不一致」的 audit 警告优先以本表为裁决依据。
4A.1 Routes（task_router.Route → 治理库自然语言 → Skill 入口）
工程 Route enum value | 治理库自然语言 | 主 Skill 入口 | 写入对象 | 治理库引用 | 工程引用 |
|---|---|---|---|---|---|
snapshot | 市场认知快照 / 资产上下文整理 | snapshot | MarketCognitionSnapshot | v1-prd.md §3, v1-product-object-and-schema-design.md §3 | task_router.Route.SNAPSHOT, context_engine._ROUTE_INSTRUCTIONS["snapshot"], skills/snapshot/SKILL.md |
thread_proposal | 提议保存为持续跟踪线程 | thread_ops | MarketCognitionSnapshot.thread_proposal 字段 | v1-product-object-and-schema-design.md §4, v1-ui-ux-interaction-design.md §6 | Route.THREAD_PROPOSAL, _ROUTE_INSTRUCTIONS["thread_proposal"], skills/thread_ops/SKILL.md |
thread_refresh | 刷新已有线程认知 / 生成 cognition diff | thread_ops | MarketCognitionSnapshot（新版本） + CognitionChanges | v1-product-object-and-schema-design.md §4, v1-ui-ux-interaction-design.md §6A | Route.THREAD_REFRESH, _ROUTE_INSTRUCTIONS["thread_refresh"], cognition_store.refresh_thread() |
risk_challenge | 风险与反方挑战 / 反方论证 | risk_challenge | MarketCognitionSnapshot（强化 counter_thesis / invalidators） | v1-prd.md §3, v1-product-object-and-schema-design.md §3, v1-agent-orchestration-design.md §5 FinSkill risk-controversy-mapper | Route.RISK_CHALLENGE, _ROUTE_INSTRUCTIONS["risk_challenge"], skills/risk_challenge/SKILL.md |
pre_execution | 执行前认知检查点 / 策略假设框架 | pre_execution | PreExecutionCheckpoint | v1-prd.md §3, v1-product-object-and-schema-design.md §5, v1-agent-orchestration-design.md §5 FinSkill strategy-hypothesis-framer | Route.PRE_EXECUTION, _ROUTE_INSTRUCTIONS["pre_execution"], skills/pre_execution/SKILL.md |
evidence_audit | 证据与数据质量审计 / 来源质量检查 | evidence_audit | MarketCognitionSnapshot（强化 evidence_items / data_quality_notes） | v1-prd.md §3, v1-product-object-and-schema-design.md §6, v1-agent-orchestration-design.md §5 FinSkill source-quality-checker | Route.EVIDENCE_AUDIT, _ROUTE_INSTRUCTIONS["evidence_audit"], skills/evidence_audit/SKILL.md |
sensitive_rejection | 敏感凭证拒收路径 | （boundary guard，无独立 Skill 文件） | （无写入；返回拒收说明） | v1-product-object-and-schema-design.md §9 SensitiveInputHandling, v1-prd.md §6 | Route.SENSITIVE_REJECTION, _ROUTE_INSTRUCTIONS["sensitive_rejection"], agent/boundary_guard.py |
点分 route：V1 不引入点分 route 命名（如 snapshot.refresh）；refresh 仍由独立 thread_refresh route 表达。如未来出现 <base>.<variant> 命名，必须在本表追加，并同步更新 Route enum。
4A.2 Advisors（context_engine _ADVISOR_PROFILES → 治理库角色 → 影响字段）
工程 advisor_id | 治理库角色名 | 治理库引用 | 主要影响字段 | 默认推荐路由 |
|---|---|---|---|---|
asset_research_advisor | 标的研究顾问 | v1-agent-orchestration-design.md §7.1 | cognition_object, supporting_reasons, evidence_items | snapshot, thread_proposal, thread_refresh |
event_interpretation_advisor | 事件解读顾问 | v1-agent-orchestration-design.md §7.2 | cognition_object, supporting_reasons, main_thesis | snapshot（事件触发的快照） |
risk_advisor | 风控顾问 | v1-agent-orchestration-design.md §7.3 | risk_constraints, invalidators, uncertainties | risk_challenge, pre_execution |
counter_thesis_advisor | 反方挑战顾问 | v1-agent-orchestration-design.md §7.4 | counter_thesis, invalidators | risk_challenge |
pre_execution_advisor | 交易前判断顾问 | v1-agent-orchestration-design.md §7.5 | supporting_conditions, risk_constraints, user_confirmation_needed, non_execution_statement | pre_execution |
source_quality_advisor | 来源质量顾问 | v1-agent-orchestration-design.md §7.6 | evidence_items, data_quality_notes, uncertainties | evidence_audit, snapshot |
market_macro_advisor | 市场/宏观顾问 | v1-agent-orchestration-design.md §7.7 | supporting_reasons, cognition_object（宏观维度） | snapshot（宏观触发的快照） |
Advisor budget：每轮 LLM 任务激活 advisor 数 ≤ 5（AL-9 行政约束）；超过预算时 provider_router 必须降级并通过 SSE advisor_dropped 通知前端。
4A.3 Skills（folder name → 治理库 FinSkill 名 → 工程 Skill 名）
工程 skill folder (server/skills/<name>/) | 工程 name: frontmatter | 治理库 FinSkill 名 | 关系 | 治理库引用 |
|---|---|---|---|---|
snapshot/ | snapshot | asset-context-summarizer | 同义重命名（治理向工程对齐） | v1-agent-orchestration-design.md §5 |
risk_challenge/ | risk_challenge | risk-controversy-mapper | 同义重命名（AL-4 命名对齐项） | 同上 |
pre_execution/ | pre_execution | strategy-hypothesis-framer | 同义重命名（AL-4） | 同上 |
evidence_audit/ | evidence_audit | source-quality-checker | 同义重命名（AL-4） | 同上 |
thread_ops/ | thread_ops | watch-question-generator（部分） | thread_ops 同时实现 watch-question-generator 与 thread 持续性能力；治理库可在术语表中视为一对多 | 同上 |
narrative_mapper/ | narrative_mapper | narrative-mapper | 命名一致（snake vs dash） | 同上 |
event_impact_reader/ | event_impact_reader | event-impact-reader | 命名一致（snake vs dash） | 同上 |
_default/ | _default | （治理库不列） | 工程辅助 skill，标 extra-not-required | 见 §3 |
market_audit/ | market_audit | （治理库不列） | [DEPRECATED]；保留以支持 evaluation 历史兼容性 | 见 §3 |
命名跨域规则（强制）：
- 治理库 PRD / 设计文档禁止直接使用工程 folder 名（如
risk_challenge）；必须使用治理库 FinSkill 名（如risk-controversy-mapper）。 - 工程 sub-packet / code / test 文件禁止使用治理库 FinSkill 名作为 import 路径或 enum；必须使用工程 folder 名。
- 任何跨域引用（如 alignment / acceptance criteria）必须同时写明两侧名称，例如
risk_challenge（治理：risk-controversy-mapper）。 - 引入新 skill 时：先在本表 §4A.3 加一行 → 同步 §3 Skills Alignment → 创建工程 folder +
SKILL.md→ 写 evaluation case。顺序不可颠倒。
4A.4 Tool ↔ Route ↔ Skill 三元绑定
工程层执行时，路由器选定 route 后，runtime 把以下三元组绑定到 LLM 上下文：
| Route | Required tool（必须调用） | 主 Skill | Secondary tools |
|---|---|---|---|
snapshot | write_snapshot | snapshot | skill_read, evidence_search（如配置）, MCP tools |
thread_proposal | write_snapshot（带 thread_proposal 字段） | thread_ops + snapshot | 同 snapshot |
thread_refresh | write_snapshot（生成新版本快照，runtime 自动调 cognition_store.refresh_thread() 算 diff） | thread_ops | 同 snapshot |
risk_challenge | write_snapshot（重点 counter_thesis / invalidators） | risk_challenge | 同 snapshot |
pre_execution | write_checkpoint（禁用 write_snapshot；BoundaryGuard 强制） | pre_execution | 同 snapshot（read-only tools） |
evidence_audit | write_snapshot（重点 evidence_items / data_quality_notes） | evidence_audit | 同 snapshot |
sensitive_rejection | （runtime 不进入 LLM 闭环；boundary guard 直接拒收） | n/a | n/a |
任何 sub-packet 的 acceptance criteria 涉及「route X 必须调用工具 Y」时，以本表 4A.4 为准，不重复在 sub-packet 内描述。
5. UI / UX Alignment
| Governance Screen (UI/UX §2) | Engineering page / component | Status | Notes |
|---|---|---|---|
| Home / Entry | web/src/pages/dashboard/show.tsx + SnapshotSummaryCard.tsx | aligned-initial | 入口形态对齐 |
| Snapshot View | web/src/domains/analysis/components/SnapshotView.tsx | aligned-initial | 字段渲染对齐 |
| Save Thread Sheet | （未定位） | missing | 保存为线程的确认 sheet 尚未实现 |
| Thread View | web/src/pages/cognition/... (snapshot-detail.tsx 含 thread 视图入口) | partial | 视图存在；维护状态条与 watch questions 区域待补 |
| Refresh Diff | （未定位） | missing | UI/UX §6A 要求的 diff 视图尚未实现；M-B6 阶段未完成项 |
| Risk Challenge View | （集成于 SnapshotView） | partial | 有展示但与 challenge 入口尚未联动 |
| Pre-Execution Checkpoint | web/src/domains/analysis/components/CheckpointView.tsx | aligned-initial | 字段对齐；不可执行边界文案需 audit |
| Evidence Drawer | （集成于 SnapshotView，跨 thread / checkpoint 复用待验） | partial | 部分实现；移动端 sheet / desktop panel 适配未验证 |
| Feedback / Review | （未定位） | missing | 反馈入口与人工复核 queue UI 待补 |
6. Evaluation Alignment
| Governance Case | Engineering YAML | Runner support | Status |
|---|---|---|---|
| Crypto-Asset-Snapshot-Colloquial | evaluation/finclaw/cases/crypto-asset-snapshot-colloquial.yaml | server/agent/evaluation.py field-level | aligned-initial |
| Crypto-Event-Narrative-Understanding | evaluation/finclaw/cases/crypto-event-narrative-understanding.yaml | 同上 | aligned-initial |
| Crypto-Thesis-Risk-Controversy | evaluation/finclaw/cases/crypto-thesis-risk-controversy.yaml | 同上 | aligned-initial |
| Snapshot-To-Watch-Questions | evaluation/finclaw/cases/snapshot-to-watch-questions.yaml | 同上 | aligned-initial |
| Strategy-Hypothesis-Pre-Execution-Checkpoint | evaluation/finclaw/cases/strategy-hypothesis-pre-execution-checkpoint.yaml | 同上 | aligned-initial |
| Evidence-Degradation-Source-Uncertainty | evaluation/finclaw/cases/evidence-degradation-source-uncertainty.yaml | 同上 | aligned-initial |
工程仓库另外加入了 7 个 edge-*.yaml case（见 server/tests/evaluation_cases/）。这些是 Engineering 自发扩展的边界压力 case，治理库视为 extra-not-required，但应在 Eval Review 中讨论是否吸收为正式覆盖。
7. API / Persistence Alignment
| Governance Constraint (Schema §13) | Engineering 实现 | Status |
|---|---|---|
| Do not store credentials / private keys / exchange keys / account permissions | Boundary Guard 拒收 | aligned-initial |
| Do not model order objects, positions as execution state | Schema 中无 order/position 字段 | aligned-strict |
Do not allow PreExecutionCheckpoint 作为执行 trigger | 仅 read-only via /api/v1/cognition | aligned-initial |
| Do not overwrite historical snapshots when thread refreshes | CognitionStore 行为待 audit | partial |
| Do not save financial context to profile or thread without explicit confirmation | ProfileConsent missing → 当前默认行为风险高 | partial |
| Do not add training use without authorization, de-identification, sensitive filtering, revocation path | TrainingAssetCandidate missing | missing |
| Do not make reference reports or evaluation cases product truth | 当前 evaluation runs 不进入产品输出 | aligned-strict |
8. Engineering 仓库旧 docs（治理库不再权威）
工程仓库 fin-claw/docs/design/01..09-*.md 描述旧 MarketIntelligence 模型，与 V1 不一致。治理库不再同步这些文档，工程仓库需要在 Engineering Implementation 阶段决定：
- 标记为
deprecated，并在 README 指向治理库；或 - 改写为
internal-engineering-notes类文档（如运行手册、部署指南），不再承担产品定义职责；或 - 直接归档。
该决定不在治理库职责范围内，但 Controller 应在每次 alignment audit 中提醒工程仓库 maintain 该状态。
9. Action Items（来自本次 audit）
| ID | Action | Owner | Priority |
|---|---|---|---|
| AL-1 | 实现 ProfileConsent 对象与 UI 确认流程 | Engineering + UX | High |
| AL-2 | 端到端验证 SensitiveInputHandling 全 4 类输入分类、masking、人工复核标记 | Engineering + Eval | High |
| AL-3 | 实现 TrainingAssetCandidate 候选治理元数据（trial 数据进入训练池前必须） | Engineering | Medium |
| AL-4 | 对齐 Skill 命名（risk-controversy-mapper / source-quality-checker / asset-context-summarizer / watch-question-generator）或写入术语映射 | Engineering + Controller | Medium |
| AL-5 | 实现 Refresh Diff View（UI/UX §6A） | Frontend | High |
| AL-6 | 实现 Save Thread Sheet 确认流程 | Frontend | High |
| AL-7 | 实现 Feedback / Human Review UI 与后端 queue | Engineering + Frontend | High |
| AL-8 | 验证「Thread refresh 不覆盖历史 snapshot」契约 | Engineering | Medium |
| AL-9 | 验证 Advisor budget（≤5 / turn） | Engineering | Low |
| AL-10 | 工程仓库 docs/design/01..09 标记为 deprecated 或归档 | Engineering | Medium |
| AL-11 | 决定是否把工程仓库 7 个 edge-*.yaml case 吸收为正式 V1 评测覆盖 | Eval | Medium |
每条 Action Item 完成后，刷新本表格的 Status 列；状态变化触发 v1-execution-plan-and-milestones.md 的 milestone 状态更新。
10. Refresh Cadence
- 每个 Engineering milestone 完成后 1 工作日内刷新；
- 每周 Controller weekly review 检查表格是否过期；
- 任何
forbidden-found状态出现立即升级为 escalation packet。
11. Reader Notes（轻量澄清，不改变决策）
11.1 执行红线条款位置（针对 review 1.2 警告）
V1 执行红线的单一权威清单位于 v1-prd.md §5.3 + v1-prd.md §12 + v1-prd.md §14 + v1-engineering-kickoff-decisions.md §3.D-02。
mvp-product-definition.md §3 是同一条款的早期外延描述，不冲突；如发现表述差异，以 v1-prd + kickoff D-02 为准。
11.2 用户触达渠道（针对 review 1.4 警告）
mvp-product-definition.md §13 提到的 "Telegram / Discord channel" 是前 V1 早期外延愿景；
V1 trial 阶段仅使用 Web UI（D-02 锁定），相关 channel adapter 禁止进入 v1-tech-stack-and-architecture-design.md §3 依赖。
后续版本如重启该需求，必须先撤销 D-02（kickoff decision rollback flow）。
11.3 字段命名（针对 review 2.5 警告）
B-6 §10.4 training_excluded 与 B-2 §6.5 withdrawal_status: revoked 描述同一状态机的两侧：
withdrawal_status是 ProfileConsent 上的撤回审计字段（B-2 权威）；training_excluded是 TrainingAssetCandidate 上的可用性标记（B-6 联动描述）；- 工程实现时两个字段都存在且通过 v1-eng-impl-sub-3-training-asset-candidate.md 验证联动；不允许任一文档单方面改名。