Sync: Labs-FinTecAI Core Entrypoint Refactor Plan

日期：2026-05-13
来源项目 / 材料：Batch 3 核心入口重构计划
提交人 / 责任人：Labs-FinTecAI Admin
当前状态：Draft

1. 目标

本计划定义 README.md、ACCESS_GUIDE.md、INDEX.md、CONTEXT-MAP.md 四个核心入口的重构顺序、编辑边界和读者测试。它承接 Batch 2 目标知识架构，但不把四份文档一次性重写。

本计划采用 doc-coauthoring 的三段式方法：

1. 上下文收集：使用 Batch 1 inventory 和 Batch 2 目标架构作为上下文边界；
2. 结构 refinement：先拆清四个入口的职责，再逐份编辑；
3. 读者测试：每轮编辑后用读者任务验证，而不是只看文风是否顺。

2. 当前问题

四个入口现在都能帮助读者进入仓库，但任务边界重叠：

入口	当前价值	主要风险
README.md	仓库定位、生态对象、边界、目录说明较完整	过长，承担了入口、索引、生态叙事和平台说明多种任务
ACCESS_GUIDE.md	低上下文接入协议清楚，适合 Agent 和 Controller	项目路线和角色路线较长，容易变成第二个索引
INDEX.md	当前文档清单和收束状态最完整	混合了正式目录、产品叙事、来源参考、后续计划
CONTEXT-MAP.md	Agent 路由短，适合任务到文件映射	与 ACCESS_GUIDE 和 INDEX 的进入顺序存在轻微重复

根因不是“写得不够详细”，而是入口之间缺少稳定分工。Batch 3 只修分工、阅读顺序和验收问题。

3. 目标职责

文件	目标读者	必须回答	不应承担
README.md	第一次进入仓库的人类和 Agent	这个仓库是什么、事实源是什么、五个生态对象是什么、下一步去哪	不做完整目录索引，不解释每个项目的详细阶段
ACCESS_GUIDE.md	人类参与者、个人域 Agent、团队域 Agent、Program Controller、外部协作者	不同任务意图应读哪 3 到 5 份材料、如何低上下文输出、何时 sync/escalation	不复制项目定义，不列完整文档目录
INDEX.md	需要查找正式文档和状态的人类 / Agent	哪些文档是 canonical、support、evidence、reference、sync、recovery	不写接入教程，不做项目长叙事
CONTEXT-MAP.md	需要快速路由的 Agent、Controller、新会话	某类任务的最小上下文是什么、冲突时回到哪个事实源	不做完整索引，不承载事实源正文

4. 编辑顺序

轮次	文件	原因	输出
3A	README.md + CONTEXT-MAP.md	先修仓库第一印象和最小路由，减少后续读者误入目录树	精简 README、强化 Context Map 的任务路由
3B	ACCESS_GUIDE.md	在 L0/L1 分工稳定后再修角色化接入协议	按任务意图压缩读取批次和输出要求
3C	INDEX.md	最后让索引承接重构后的状态标签和目录角色	明确 canonical/support/evidence/reference/sync/recovery
3D	docs-manifest.json、sidebars.js、llms.txt	文本职责稳定后再同步机器路由和门户导航	relink-audit 和导航调整

每轮最多处理 1 到 2 个核心入口。除非当前轮需要修正明显路由冲突，不同时改项目正文。

5. Reader Testing

5.1 README 测试

测试读者	任务	通过标准
新成员	3 分钟内判断仓库是什么	能说出这是生态治理知识库，不是工程仓库、聊天归档或任务系统
项目负责人	找到项目入口	能从 README 进入对应对象入口，而不是扫描目录树
Agent	判断事实源	能知道 Markdown 是事实源，portal/manifest/search 只是访问面

5.2 ACCESS_GUIDE 测试

测试读者	任务	通过标准
个人域 Agent	接入某个产品	能拿到 3 到 5 份首批材料和输出格式
Program Controller	恢复或启动项目控制台	能知道先读 registry/state/checkpoint，再发 sync 或 escalation
外部协作者	受限范围接入	能区分正式事实、参考、证据和待验证假设

5.3 INDEX 测试

测试读者	任务	通过标准
人类 reviewer	判断哪些是正式入口	能区分 canonical/support/evidence/reference/sync/recovery
Agent	查找文档状态	能找到目标文档并理解它的角色
Admin	判断是否要下架或降级	能看出哪些材料是 evidence 或 historical，不是主入口

5.4 CONTEXT-MAP 测试

测试读者	任务	通过标准
新会话 Agent	用最小上下文接手任务	能按任务类型选择入口，不全仓库扫描
Controller	处理跨项目问题	能从任务类型路由到 packet、governance 或项目入口
Admin	判断冲突回退	能看到冲突时应回到 README、INDEX、baseline、registry 或项目事实源

6. 编辑约束

• 不把 Batch 3 变成全文润色项目；
• 不新增并列 canonical 入口；
• 不把 controllers/、packets/、evaluation/、references/ 直接提升为事实源；
• 不替项目 Controller 改项目级事实；
• 不删除旧材料，除非 Batch 1 inventory 已明确 demote 且有反链或替代入口；
• 每轮编辑后同步检查 docs-manifest.json、sidebars.js、llms.txt 是否需要最小更新；
• 每轮必须更新 checkpoint，说明哪些 reader test 已通过、哪些留到下一轮。

7. 3A 建议改法

7.1 README

建议将 README 收束为：

1. 仓库一句话定位；
2. 事实源与访问面；
3. 五个生态对象；
4. 四类读者的下一步；
5. 目录角色表；
6. 当前重构状态和不要做什么。

应下移或压缩：

• 过长的 FinClaw 展开；
• 具体发布链路细节；
• 项目后续计划；
• 与 INDEX.md 重复的文档清单。

7.2 CONTEXT-MAP

建议将 Context Map 收束为：

1. 冲突回退规则；
2. 任务路由表；
3. 对象路由表；
4. 变更写回路由；
5. 使用提醒。

应避免：

• 重新讲生态背景；
• 复制 ACCESS_GUIDE 的角色协议；
• 复制 INDEX 的目录清单。

8. 3B/3C 预留

Batch 3B 和 3C 在 3A 验证后执行，避免 README 与 Context Map 尚未稳定时重排 ACCESS_GUIDE 和 INDEX。

9. 验证命令

每轮至少运行：

node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"
git diff --check
DOC_CHANGE_SCOPE=ecosystem,controllers,packets,tooling npm run verify:change-scope
npm run build

如当轮修改正式入口，scope 应扩展为 ecosystem,public-entrypoints,controllers,packets,tooling 或对应更窄范围。

10. 下一步

若 FinTec AI admin 会话接受本计划，下一步执行 Batch 3A：编辑 README.md 和 CONTEXT-MAP.md，并用本计划中的 reader testing 表验证。

11. 执行状态

Batch 3A 已执行：

• README.md 已收束为仓库定位、事实源规则、生态对象、文档层级、目录角色和当前治理重构状态；
• CONTEXT-MAP.md 已收束为任务路由表、对象路由表、变更写回路由和使用提醒；
• 项目正文、设计包、PRD、评测和参考体验材料未修改；
• docs-manifest.json、sidebars.js、llms.txt 未在 3A 修改，留到 3D 统一 relink-audit。

Batch 3B 已执行：

• ACCESS_GUIDE.md 已收束为接入原则、任务意图入口、接入者工作方式、低上下文读取协议、Agent 指令模板、回写位置和非常规入口说明；
• 原有 Data Horizon / FinClaw 负责人长路径和长提示词已移出本入口职责，后续如需保留应由对应 Controller packet 承接；
• 项目正文、设计包、PRD、评测和参考体验材料未修改；
• docs-manifest.json、sidebars.js、llms.txt 未在 3B 修改，留到 3D 统一 relink-audit。

Batch 3C 已执行：

• INDEX.md 已收束为文档状态索引，明确 canonical、support、evidence、reference、sync、recovery、tooling 的使用规则；
• 原有优先阅读路径、项目长叙事和后续收束顺序已移出本入口职责；
• 项目正文、设计包、PRD、评测和参考体验材料未修改；
• docs-manifest.json、sidebars.js、llms.txt 未在 3C 修改，留到 3D 统一 relink-audit。

Batch 3D 已执行：

• docs-manifest.json 已补入 INDEX.md、evidence/reference 路由和 knowledge_refactor entrypoint；
• sidebars.js 已将 总览 收束为四个核心入口，并把治理协议、Controller recovery、sync 记录、source/reference/evidence 和平台支撑材料分层；
• llms.txt 已补入 INDEX.md、Controller / packet 非事实源边界和本轮 knowledge refactor control plane；
• 项目正文、设计包、PRD、评测和参考体验材料未修改；
• Batch 3D recovery checkpoint 已由正式 3D checkpoint 承接。