第二十七节 — 代码仓位置映射

这一节回答：本架构文档的概念在 FinBayes 工程实施仓里的物理位置是什么？章节里的"子系统 / 工具 / 状态对象 / Prompt"具体落在哪个目录哪个模块？

工程实施仓与本仓的关系

仓	角色	内容
本仓（Labs-FinTecAI）	知识库 + 治理库	战略 / 架构 / ADR / 提案 / 调研
FinBayes 工程实施仓	工程代码 + 测试 + 运行配置	runtime / 工具实现 / 测试 / CI / 部署脚本

两仓严格分离（详见 CLAUDE.md "工程执行产物不进本仓"）。本架构文档（本仓）是契约事实源，工程实施仓的代码必须追溯到本架构文档某章节。

工程实施仓的物理路径由工作流维护者维护，不写入本仓（路径约束详见本仓 CLAUDE.md）。本章用抽象路径表达映射，工程实施仓内的实际目录名按 Python 项目惯例。

顶层目录约定

工程实施仓采用 Python 标准 src layout：

finbayes/                       # 工程实施仓根
├── src/finbayes/               # 主代码（包根）
├── tests/                      # 测试
├── evals/                      # 评估数据集 + 评估运行器
├── prompts/                    # Prompt 资产（YAML / 模板）
├── migrations/                 # State Store schema migration 脚本
├── configs/                    # 配置模板（用户实际 config 在 OS 用户目录）
├── scripts/                    # 工具脚本（备份 / 诊断 / 等）
├── docs/                       # 工程实施仓自己的运维文档（不重复本仓）
└── .github/ or .ci/            # CI 配置

关键约定：

业务代码全部在 src/finbayes/（不在仓根散落）
测试与代码 1:1 镜像（tests/test_<module>.py）
评估资产与测试分开目录（评估是独立的运行模式，详见 CHAP-21）

子系统映射（CHAP-09 6 子系统）

子系统	抽象路径	关键模块
Input / Output Pipeline	`src/finbayes/io/`	`entries/`（CLI/TUI/WebAPI/MCP/Channel 各子模块）/ `boundary.py`（边界 hook）/ `normalize.py`（输入归一化）/ `formatter.py`（输出格式化）/ `stream.py`（流式输出）
Task Orchestration	`src/finbayes/orchestration/`	`task.py`（task 对象 + 生命周期）/ `dispatcher.py`（任务分发）/ `function_calling.py`（LLM Function Calling 集成）/ `clarify.py`（clarify 工具）
Evidence + Synthesis	`src/finbayes/cognition/`	`evidence/`（证据归一化 + EvidencePacket）/ `synthesis/`（综合层）/ `self_consistency.py`（多采样）/ `schema.py`（输出契约）
State Management	`src/finbayes/state/`	`store.py`（State Store 抽象）/ `session.py` / `watchlist.py` / `judgment.py` / `profile.py` / `candidate.py`（两步写入）/ `audit.py`（审计 trail）
Capability Registry	`src/finbayes/capabilities/`	`registry.py`（工具注册 + 校验）/ `tools/`（各工具实现的子目录）/ `schema.py`（工具元数据）
Provider Adapter Pool	`src/finbayes/providers/`	`adapter.py`（统一接口）/ `llm/`（OpenAI compatible / Anthropic / DeepSeek / Ollama / 等）/ `data/`（外部数据 Provider）/ `readiness.py`（探测）/ `routing.py`（task_routing）

业务对象映射（CHAP-04 7 个 First-Class 概念）

概念	Pydantic 模型路径	持久化表
Session	`src/finbayes/state/session.py:Session`	`sessions`
Watchlist	`src/finbayes/state/watchlist.py:Watchlist`	`watchlist_objects`
Judgment Record	`src/finbayes/state/judgment.py:JudgmentRecord`	`judgment_records`
Dynamic Profile	`src/finbayes/state/profile.py:DynamicProfile`	`dynamic_profiles`
State Candidate	`src/finbayes/state/candidate.py:StateCandidate`	`state_candidates`
Fin Object	`src/finbayes/state/fin_object.py:FinObject`	`fin_objects`
Task	`src/finbayes/orchestration/task.py:Task`	（内存为主 + 审计 trail）

关键约束：

业务对象 schema 用 Pydantic v2（详见 ADR-008 待）
schema 字段变化必须走 CHAP-19 演化策略
业务对象互引用通过 ID（不直接嵌入对象，避免循环 ref）

状态机映射（CHAP-11 6 个状态机）

状态机	实现位置
Session 生命周期	`src/finbayes/state/session.py:SessionState`
Task 生命周期	`src/finbayes/orchestration/task.py:TaskState`
TaskGroup 生命周期	`src/finbayes/orchestration/task_group.py:TaskGroupState`
Judgment Record 生命周期	`src/finbayes/state/judgment.py:JudgmentState`
State Candidate 生命周期	`src/finbayes/state/candidate.py:CandidateState`
Provider Readiness	`src/finbayes/providers/readiness.py:ProviderReadinessState`

Fin Object 与 Watchlist 没有独立状态机（详见 CHAP-11 开篇说明）—— Watchlist 状态由 StateCandidate + watchlist_objects 表承载，Fin Object 仅 created/archived 标记。

数据存储映射（CHAP-15 5 类数据）

数据类别	物理位置	实现模块
State Store	OS 数据目录 SQLite 文件	`src/finbayes/state/store.py` + `migrations/`
Cache	Redis 或内存 LRU	`src/finbayes/cache/`
Config Store	OS 配置目录 YAML	`src/finbayes/config/`
Credential Store	OS Keychain	`src/finbayes/security/credentials.py`
Audit Trail	SQLite 同库不同表	`src/finbayes/state/audit.py`

关键约束：

用户实际数据不在工程实施仓 —— 仓内只有 schema 与代码，运行时数据在用户机器的 OS 标准目录（CHAP-14）
migrations/ 内的脚本编号严格递增（如 001_initial.sql / 002_add_audit_trail.sql）

通信协议映射（CHAP-16）

协议层	实现位置
进程内（Python 调用）	各子系统间直接 import
CLI 入口	`src/finbayes/io/entries/cli/`
TUI 入口	`src/finbayes/io/entries/tui/`
Web API + WebSocket	`src/finbayes/io/entries/web/`
MCP Server	`src/finbayes/io/entries/mcp/`
Channel Adapter	`src/finbayes/io/entries/channels/`（按平台分子目录）
LLM Provider HTTP	`src/finbayes/providers/llm/` 各 adapter

边界与安全映射（CHAP-17）

约束	实现位置
输入边界 hook	`src/finbayes/io/boundary.py`
凭证识别规则	`src/finbayes/security/credential_patterns.py`
输出端凭证样式扫描	`src/finbayes/io/output_filter.py`（ADR-010 决策后定）
执行类工具注册拒绝	`src/finbayes/capabilities/registry.py:register_tool`
用户数据隔离（user_id）	`src/finbayes/state/store.py` 查询层
TLS 强制	`src/finbayes/providers/http_client.py`

可观测性映射（CHAP-18）

资产	位置
审计 trail 写入器	`src/finbayes/state/audit.py`
Task trace ID 管理	`src/finbayes/orchestration/trace.py`
指标采集	`src/finbayes/observability/metrics.py`
用户视角 CLI 命令	`src/finbayes/io/entries/cli/commands/`（含 `status / trace / audit / cost / session`）
日志分级与脱敏	`src/finbayes/observability/logging.py`

Prompt 资产映射（CHAP-19 + ADR-009 待）

混合策略下的路径约定：

Prompt 类型	位置
System Prompt（策略 A 进代码仓）	`prompts/system/`
任务模板（策略 A）	`prompts/task_templates/`（按任务类型分）
输出契约 schema 关联 prompt（策略 A）	`prompts/synthesis/`
实验性 Prompt（策略 B）	`prompts/experimental/` + 自描述 `delivery_mode: data` 字段
Judge Prompt（评估专用）	`prompts/eval_judges/`

关键约束：

每个 Prompt 文件有 frontmatter：prompt_id / prompt_version / delivery_mode / author / activated_at
策略 A Prompt 进 Git diff + Review gate 覆盖
策略 B Prompt 在 runtime 启动时加载 + 进审计 trail

测试资产映射（CHAP-20）

测试类型	位置
单元测试	`tests/unit/`（与 `src/finbayes/` 镜像）
集成测试	`tests/integration/`
端到端测试（快档 Mock）	`tests/e2e/quick/`
端到端测试（真档真 LLM）	`tests/e2e/real/`
降级路径测试	`tests/degradation/`
边界与安全测试	`tests/boundary/`
LLM Mock fixture	`tests/fixtures/llm/`
测试用业务对象 fixture	`tests/fixtures/state/`

评估资产映射（CHAP-21）

评估资产	位置
评估数据集（冒烟 / 回归 / 场景 / 抗扰）	`evals/datasets/`（按层分子目录）
评估运行器	`evals/runner/`
Rubric 定义	`evals/rubrics/`
Judge Prompt	`prompts/eval_judges/`（与 prompts 共享）
评估结果库	（运行时，不在仓）`evals/results/`（gitignore）
评估报告模板	`evals/reports/`

CI 集成映射

CI 阶段	实现
PR：单元 + 集成 + 端到端快档 + 边界 + verify-kb	`.ci/pr-pipeline.yml`
Nightly：含真 LLM + 评估	`.ci/nightly.yml`
Release：完整评估 + 性能基线	`.ci/release.yml`
战略保真度审计脚本	`scripts/audit_strategy_fidelity.py`
契约回归审计脚本	`scripts/audit_contract_regression.py`

配置文件映射（CHAP-14 + CHAP-15）

工程实施仓内只有模板 —— 用户实际配置在 OS 用户目录：

配置	模板位置（工程实施仓）	运行时位置（用户机）
`config.yaml`	`configs/templates/config.yaml`	OS 配置目录（按平台，CHAP-14）
`providers.yaml`	`configs/templates/providers.yaml`	同上
`task_routing.yaml`	`configs/templates/task_routing.yaml`	同上
`ui.yaml`	`configs/templates/ui.yaml`	同上

部署与运行脚本映射

脚本	位置
`finbayes` 入口（CLI）	`src/finbayes/__main__.py`
安装引导（首次初始化）	`src/finbayes/install/wizard.py`
备份与恢复	`scripts/backup.py` / `scripts/restore.py`
诊断打包	`scripts/diagnostic.py`
Schema migration runner	`migrations/runner.py`

章节到代码的反向追溯

工程实施仓的代码反向追溯到本架构文档：

机制	实现
每个 PR 的描述必须显式引用 CHAP-NN / ADR-NNN	OpenSpec 提案要求
每个 module 的 docstring 含章节引用	工程实施约定
每个 ADR 的"关联"段含反向 CHAP 列表	ADR 模板
章节追踪表（status.md）随实施进展更新	工作流维护者职责

工程实施仓的代码不进本仓

关键边界：

工程实施代码不进本仓（即使是示例代码段在文档里也只用伪代码 / schema）
运行时数据 / 用户配置 / Controller state / task packet 不进本仓
工程实施仓的本地路径不写入本仓的任何文档（详见本仓 CLAUDE.md）

工程实施仓的物理路径由工作流维护者在本地记录（用户级 memory），不进本仓。

与其他章节的关系

子系统职责定义 → CHAP-09 子系统组件
业务对象定义 → CHAP-04 业务对象与关系
状态机定义 → CHAP-11 状态对象生命周期
数据存储定义 → CHAP-15 数据存储划分
通信协议定义 → CHAP-16 通信协议
边界与安全约束 → CHAP-17 边界与安全
可观测性资产 → CHAP-18 可观测性
演化资产 → CHAP-19 演化与版本管理
测试资产 → CHAP-20 测试体系
评估资产 → CHAP-21 评估闭环
工程协作 → ADR-003 工程实施栈与协作
里程碑产出 → CHAP-25 与里程碑/任务的对应
审计点 → CHAP-26 审计点

工程实施仓与本仓的关系​

顶层目录约定​

子系统映射（CHAP-09 6 子系统）​

业务对象映射（CHAP-04 7 个 First-Class 概念）​

状态机映射（CHAP-11 6 个状态机）​

数据存储映射（CHAP-15 5 类数据）​

通信协议映射（CHAP-16）​

边界与安全映射（CHAP-17）​

可观测性映射（CHAP-18）​

Prompt 资产映射（CHAP-19 + ADR-009 待）​

测试资产映射（CHAP-20）​

评估资产映射（CHAP-21）​

CI 集成映射​

配置文件映射（CHAP-14 + CHAP-15）​

部署与运行脚本映射​

章节到代码的反向追溯​

工程实施仓的代码不进本仓​

与其他章节的关系​

工程实施仓与本仓的关系

顶层目录约定

子系统映射（CHAP-09 6 子系统）

业务对象映射（CHAP-04 7 个 First-Class 概念）

状态机映射（CHAP-11 6 个状态机）

数据存储映射（CHAP-15 5 类数据）

通信协议映射（CHAP-16）

边界与安全映射（CHAP-17）

可观测性映射（CHAP-18）

Prompt 资产映射（CHAP-19 + ADR-009 待）

测试资产映射（CHAP-20）

评估资产映射（CHAP-21）

CI 集成映射

配置文件映射（CHAP-14 + CHAP-15）

部署与运行脚本映射

章节到代码的反向追溯

工程实施仓的代码不进本仓

与其他章节的关系