跳到主要内容

Knowledge Update Closure Protocol

状态：Active / 知识库协同更新闭环协议 最后更新：2026-05-13 用途：复盘并固化 Labs-FinTecAI-Gov 在多 Program Controller 并行更新后的对齐、校验、发布和恢复方式

1. 目标​

本协议解决的问题是：

当多个产品 / 系统的 Program Controller 同时更新各自范围内的文档时，如何让 Labs-FinTecAI-Gov 在不产生事实混乱、入口漂移、旧文档复活或发布滞后的情况下，完成一次可验证的知识库更新闭环。

它不是新的任务管理系统，也不是替代 sync、escalation、工程仓库或 open-cowork 的执行流程。

2. 本次协同更新暴露的问题​

本次 FinClaw、Data Horizon、AI Trading Matrix 三条线并行更新后，主要问题不是单个文档内容，而是闭环顺序不够清晰：

  • 各 Controller 能完成各自项目范围内的判断，但公共入口层需要统一复核；
  • sidebars.js、docs-manifest.json、llms.txt、INDEX.md、CONTEXT-MAP.md、registry/project-registry.md 等入口文件容易与项目文档发生轻微漂移；
  • 人类门户、Agent manifest、GitHub Markdown 和线上部署页面是不同消费面，不能只验证其中一个；
  • 发布后线上内容可能短时间滞后，需要把 GitHub Actions、Railway deployment、线上静态文件都纳入闭环；
  • 临时 handoff、sync、历史过程文档容易被误当成长期入口，需要在吸收后标记状态或从常规入口移出；
  • 会话上下文容易膨胀，必须把每批任务拆成可独立验收的公共入口修正，而不是让单一会话重新读取整个仓库。

3. 分层责任​

层级负责事项不负责事项
产品 Program Controller项目内事实、项目入口建议、需要回写的 sync / escalation、工程对齐输入直接修改其他项目事实、直接决定公共入口最终结构
Labs-FinTecAI Controller公共入口一致性、跨项目入口分层、索引 / manifest / 门户 / 发布闭环替代产品 Controller 做项目内容判断
工程仓库 / open-cowork具体实现、测试、运行证据、任务执行与验收替代治理仓库成为生态事实源
GitHub / Docusaurus / Pagefind / Railway分发和展示已发布知识库产生新的事实或替代 Markdown 源文件

核心原则：

  • 项目内容由对应 Controller 先判断；
  • 公共入口由 Labs-FinTecAI Controller 统一收束；
  • 发布面只展示和检索事实源，不创造事实源；
  • 所有稳定结论最终回到 Markdown 源文件、manifest、索引或 packet 状态。

4. 标准闭环​

4.1 Controller 回写输入​

每个产品 Controller 给 Labs-FinTecAI Controller 的输入应尽量短，并明确写成公共入口修正请求：

对象：
修改范围：
统一口径：
应保留入口：
应移除入口：
是否需要新增 support / reference / sync 字段：
验收命令：
禁止改动范围：

不要要求 Labs-FinTecAI Controller 重新理解整个项目，也不要让一个 Controller 的判断覆盖其他项目内容。

4.2 Labs-FinTecAI 分批处理​

Labs-FinTecAI Controller 每批只处理一类可验收问题：

  1. 单项目公共入口修正；
  2. 跨项目公共索引一致性修正；
  3. manifest / llms / sidebar / portal route 修正；
  4. sync 吸收状态修正；
  5. 发布验证和线上对齐。

一批完成后，应先做本地验证，再进入下一批。不要把三到五个项目的内容重写混在同一个不可分辨的大改动里。

4.3 公共入口必须同时更新​

凡是项目入口发生变化，至少检查以下文件：

  • INDEX.md
  • CONTEXT-MAP.md
  • registry/project-registry.md
  • sidebars.js
  • docs-manifest.json
  • llms.txt
  • ACCESS_GUIDE.md，仅当通用接入规则变化时修改
  • packets/sync/README.md，仅当 sync 状态、典型场景或真实 sync 列表变化时修改

如果只是项目内文档内容变化，不一定修改所有公共入口；但必须确认 manifest 和门户不会把已删除或已降级的文档继续暴露为正式入口。

5. 入口分层规则​

公共入口不应只维护一个平铺列表。至少区分：

  • official entry：正式事实源、产品定义、当前主入口；
  • design support：设计支撑材料，不等同于主入口；
  • reference：第三方参考、竞品分析、来源材料；
  • evaluation：评测、case library、运行报告；
  • sync：跨项目协同信号、handoff、吸收记录；
  • deprecated / absorbed：已删除、已吸收或不再作为当前入口的材料。

如果 schema 暂时没有精确字段，宁可补字段，也不要把不同语义层的文档混进同一个 entry_paths 中。

6. 发布前验证​

提交前至少执行：

node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"
git diff --check
npm run build

对本批明确移除的旧入口，使用 rg 做反查。例如：

rg "projects/trading-matrix/CONTEXT" sidebars.js docs-manifest.json INDEX.md llms.txt

如果命令应该无结果，应在发布记录中说明“无结果”为验收证据。

7. 提交与发布​

一次知识库发布应满足：

  1. 本地工作区只包含本批意图内的改动；
  2. 本批改动通过 governance/document-change-scope-policy.md 中的 scope 校验，或明确记录为什么需要 Labs-FinTecAI Controller 越界收束；
  3. commit message 说明为什么更新入口或事实源，而不只是列文件；
  4. git push origin main 成功；
  5. GitHub Actions docs workflow 成功；
  6. Railway 或当前线上部署服务部署到同一 commit；
  7. 线上 docs-manifest.json、llms.txt 和关键页面通过 cache-busting URL 验证；
  8. 本地 HEAD 与 origin/main 一致。

线上验证示例：

curl -fsSL -H 'Cache-Control: no-cache' "https://fin-tec-ai.up.railway.app/docs-manifest.json?ts=$(date +%s)"
curl -fsSL -H 'Cache-Control: no-cache' "https://fin-tec-ai.up.railway.app/llms.txt?ts=$(date +%s)"

注意：Docusaurus 中 README.md 页面通常映射到目录根路径。例如 projects/data-horizon/README.md 的线上入口是 /projects/data-horizon/，不是 /projects/data-horizon/README。

8. 失败恢复​

如果发生上下文压缩失败、会话中断或部署滞后，恢复时只需要从以下状态点继续：

  • 当前 git status --short --branch
  • 当前 git rev-parse HEAD
  • 当前 git rev-parse origin/main
  • 最近一次 commit hash
  • GitHub Actions 最新 docs run 状态
  • 线上 docs-manifest.json 与 llms.txt 抽样结果
  • 本批 Controller 原始反馈和验收项

不要重新读取整个仓库；不要重跑已经验收过的项目内容分析；只恢复未完成的闭环环节。

9. 完成定义​

一次治理仓库协同更新只有在以下条件都满足时，才算完成：

  • 项目 Controller 的回写请求已被逐项处理或明确退回；
  • 公共入口没有旧文档、错误状态或语义层混用；
  • 人类入口、Agent 入口、GitHub Markdown 和线上门户指向同一事实源；
  • docs-manifest.json 可解析；
  • Docusaurus / Pagefind 构建成功；
  • 远端仓库和线上部署均指向最新提交；
  • 如有 sync 被吸收，原 sync 中能看到吸收状态或处理结果。

10. 后续优化方向​

后续可把本协议进一步工具化：

  • 增加 npm run verify:docs-manifest，检查入口路径存在、旧入口残留和字段语义；
  • 增加 npm run verify:published-site，自动检查线上 docs-manifest.json、llms.txt 和关键 route；
  • 为 Controller 回写输入增加轻量模板；
  • 将每次发布闭环结果写成短 sync 或 release note，只记录事实源变化、入口变化和验证证据；
  • 等 open-cowork 协作层稳定后，再把“更新请求 -> 分批执行 -> 审计 -> 验收”接入任务协作平台。