Sync: Labs-FinTecAI Target Knowledge Architecture
日期：2026-05-13
来源项目 / 材料：Batch 2 目标知识架构
提交人 / 责任人：Labs-FinTecAI Admin
当前状态：Draft
1. 目标
本同步包定义治理仓库和知识库重构后的目标信息架构。它用于约束后续 README.md、INDEX.md、ACCESS_GUIDE.md、CONTEXT-MAP.md、docs-manifest.json、sidebars.js、llms.txt 的重构顺序和职责边界。
本批不是正文重写，不替项目 Controller 判断项目内容，也不把所有文档重新分类为新的目录树。
2. 核心诊断
当前系统性问题的根因不是单份 FinClaw 文档质量，而是知识库的五类对象在入口和导航中缺少稳定分层：
| 对象类型 | 应承担职责 | 当前风险 |
|---|---|---|
| 正式事实源 | 定义生态、项目、产品、边界和当前有效判断 | 与 packet、checkpoint、参考材料混读后，读者无法判断权威性 |
| 接入与索引入口 | 帮读者选择最小阅读路径 | README.md、INDEX.md、ACCESS_GUIDE.md、CONTEXT-MAP.md 任务边界有重叠 |
| 证据、来源、参考、评测 | 支撑、启发、反例、复核和验证 | 容易被误读成正式产品定义或需求 |
| Controller 状态 | 恢复会话、lane、checkpoint 和任务队列 | 容易被误读成正式项目事实源 |
| Packet 层 | 同步、升级、handoff、变更和任务协同 | 容易被当成长期主入口或文档事实源 |
因此，本轮重构必须先修“角色和路由”，再修“正文表达”。否则逐份改写只会产生更多并列入口。
3. 目标层级
graph TD
A["L0: 接入面"] --> B["L1: 生态事实源"]
A --> C["L1: 机器路由面"]
B --> D["L2: 项目 / 系统事实源"]
B --> E["L2: 治理协议"]
D --> F["L3: 项目展开和设计支撑"]
D --> G["L3: 评测与证据"]
E --> H["L3: Controller 恢复"]
E --> I["L3: Packet 协同"]
G --> J["L4: 来源 / 参考 / 运行日志"]
I --> J
| 层级 | 名称 | 代表路径 | 读者任务 | 权威性 |
|---|---|---|---|---|
| L0 | 接入面 | README.md、ACCESS_GUIDE.md、INDEX.md、CONTEXT-MAP.md | 判断我是谁、我要做什么、先读什么 | 路由权威，不新增产品事实 |
| L1 | 生态事实源 | baseline/、contexts/ecosystem/CONTEXT.md、registry/project-registry.md | 理解生态对象、链路、边界和当前基线 | 生态级事实源 |
| L1M | 机器路由面 | docs-manifest.json、llms.txt、sidebars.js | 为 Agent、门户和检索提供低上下文路由 | 导航权威，不新增事实 |
| L2 | 项目 / 系统事实源 | projects/* 中的 official entry | 理解某个对象的定位、产品定义、MVP、当前阶段 | 项目级事实源，由项目 Controller 负责 |
| L2G | 治理协议 | governance/ | 判断材料、变更、Controller、同步、升级和发布闭环怎么走 | 治理流程权威 |
| L3 | 项目展开和设计支撑 | projects/*/design/、项目三件套、产品对象文档 | 承接具体设计、工程输入和任务包 | 继承项目事实源，不反向覆盖 |
| L3E | 评测与证据 | evaluation/、projects/*/reference-experience/ | 复核能力、用例、参考体验和证据 | 证据权威，不直接定义产品 |
| L3C | Controller 恢复 | controllers/ | 恢复角色、lane、checkpoint 和当前任务 | 执行状态权威，不是事实源 |
| L3P | Packet 协同 | packets/ | 发起 sync、escalation、handoff、任务和变更 | 协同状态权威，不是事实源 |
| L4 | 来源 / 参考 / 运行日志 | source/、references/、packet logs | 提供来源、参考、反例、竞品、复核和运行证据 | 支撑层，不是正式入口 |
4. 四个核心入口的目标职责
| 文档 | 目标职责 | 应保留 | 应移出或降级 |
|---|---|---|---|
README.md | 说明仓库是什么、事实源规则、生态对象、当前边界和最短入口 | 仓库定位、对象总览、权威性规则、读者分流 | 过长的项目展开、具体执行细节、过多历史说明 |
ACCESS_GUIDE.md | 按角色和任务意图给出低上下文读取协议 | 人类、个人域 Agent、团队域 Agent、Program Controller、外部协作者的读法 | 项目正文解释、完整文档索引、过细的项目阶段说明 |
INDEX.md | 当前正式目录和收束状态索引 | 哪些是 canonical、support、evidence、reference、sync、recovery | 接入教程、长段产品叙事 |
CONTEXT-MAP.md | 最小上下文路由图 | 任务到文件的最短路径、冲突时回到哪个事实源 | 索引大全、白皮书式背景、项目完整状态 |
后续 Batch 3 应使用 doc-coauthoring 重构这四份文档，但只按上述职责分离来改，不做文风型重写。
5. 导航面目标
5.1 Portal sidebar
sidebars.js 应服务人类浏览，目标分区为：
| 分区 | 目标内容 | 调整原则 |
|---|---|---|
| 起步 | README.md、ACCESS_GUIDE.md、INDEX.md、CONTEXT-MAP.md | 只放入口，不混入平台实现细节 |
| 生态基线 | baseline/、生态 context、注册表 | 保持可展开，但不塞入 packet |
| 项目 | 五个对象的项目入口和必要设计支撑 | 项目细节由 Controller 维护，Admin 只控制入口分层 |
| 治理与协同 | governance、packets README、sync/escalation README | 把协议与具体 sync 记录分开 |
| Controller 恢复 | controllers README、registry、各 state | 标注 recovery，不与正式事实源混放 |
| 评测与证据 | evaluation、reference-experience 索引 | 不把运行日志作为常规导航项 |
| 来源与参考 | source、references | 标注 evidence/reference，避免事实源误读 |
当前 sidebar 中 governance/knowledge-platform-integration、governance/agent-context-layer、agent-context/graphiti/README 放在“总览”过高，后续应下移到“平台与 Agent 接入辅助”或治理支撑区。
5.2 Agent manifest
docs-manifest.json 应按任务意图暴露 entrypoint，而不是按目录枚举所有材料：
| Entry ID | 用途 | 路由对象 |
|---|---|---|
repository_start | 首次进入 | L0 + 当前生态基线 |
ecosystem_strategy | 生态战略、对象关系、边界 | L1 |
product_object | 某个项目 / 系统正式事实源 | L2 |
coordination | sync、escalation、Controller、scope、publish | L2G + L3P |
controller_recovery | 会话恢复和 checkpoint 接手 | L3C |
evidence_reference | 来源、参考、评测、运行证据 | L3E + L4 |
knowledge_refactor | 本次知识库重构控制面 | operating plan + audit + inventory + target architecture |
5.3 llms.txt
llms.txt 应继续保持短，但要加入两条规则：
controllers/是 recovery surface，不是 product authority；packets/是 coordination surface，不是 canonical fact source。
6. 链接策略
| 链接类型 | 规则 |
|---|---|
| L0 到 L1 | 每个入口必须指向当前生态基线和注册表 |
| L0 到 L2 | 只通过对象入口或项目 Controller packet，不直接列出所有项目深层文档 |
| L2 到 L3 | 项目官方入口可链接设计支撑、评测和 evidence，但必须标明角色 |
| Governance 到 Controller | 协议链接 registry 和 state，不把 state 当事实源 |
| Packet 到 fact source | packet 必须写明 source_refs 和 target_refs，稳定结论需要回写正式事实源 |
| Evidence 到 fact source | 证据页必须说明已吸收、待吸收、反例、复核或保留原因 |
| Logs | 运行日志只从报告或 evidence index 反链，不进主导航 |
7. Batch 3 输入
Batch 3 不直接“美化文档”，而是对四个核心入口做读者任务测试：
| 文件 | 测试问题 |
|---|---|
README.md | 新成员 3 分钟内能否判断仓库是什么、什么是事实源、下一步去哪 |
ACCESS_GUIDE.md | 人类、Agent、Controller 能否按任务意图拿到 3 到 5 份最小读物 |
INDEX.md | 读者能否判断每类文档的 canonical/support/evidence/reference/sync/recovery 状态 |
CONTEXT-MAP.md | Agent 能否根据任务对象选择最小上下文，不全仓库扫描 |
8. Controller 分发策略
项目层级重构不在 Admin 会话逐份执行。Batch 5 应为每个活跃项目生成 Controller Refactor Packet：
| Controller | 分发重点 |
|---|---|
| FinClaw Controller | official entry、design support、evidence/reference-experience 的边界标注 |
| Data Horizon Controller | 当前三件套、practice profile、output inventory、reference-evaluation 前置状态 |
| Trading Matrix Controller | 执行边界、参考评估、工程事实层和生态接口 |
| RLE / FEFM Controller | dormant/readiness gated 状态的入口最小化和启动条件 |
| Labs-FinTecAI Admin | L0/L1/L1M/L2G/L3C/L3P 的公共入口和发布闭环 |
9. 不做事项
- 不把目录重排当作第一目标；
- 不把所有 sync packet 变成主导航；
- 不把 checkpoint 吸收到正式产品定义；
- 不把来源、参考、评测直接改写成需求；
- 不为风格统一改写已经能完成读者任务的文档；
- 不在 Admin 会话中替项目 Controller 深读和裁决项目正文。
10. 完成定义
Batch 2 完成后，应满足：
- 已有目标层级和入口职责；
- 已有 sidebar、manifest、llms 的调整原则；
- 已有 Batch 3 核心入口读者测试问题；
- 已有 Controller 分发边界；
- 未修改正式入口正文和项目正文。
11. 吸收状态
待 FinTec AI admin 会话复核。若复核通过，Batch 3 可基于本包启动核心入口重构计划。