第三方工具集成
回答：第三方治理 / 协同工具如何作为 enhancement 接入本仓库的最小协议，以及当前平台栈和 Agent 上下文层的定位。
1. 核心原则
- 可选不可缺：每一个第三方工具都是 enhancement，不接入也能让
change-protocol.md、alignment-protocol.md、escalation.md完整跑通； - 本仓库留证：任何工具产出的决定 / 评审 / 升级，最终都要在本仓库留下可追溯的 PR / commit / ADR；
- 不假设用户统一：参与生态的人和 Agent 可能各自只用其中一部分工具，本协议不能要求所有人用同一套；
- Markdown 是唯一事实源：站点、搜索、manifest 和动态上下文层都是接入层，不替代正式事实源。
2. 当前平台栈
| 组件 | 定位 | 当前状态 |
|---|---|---|
Markdown Git repo | 唯一正式事实源 | 主体 |
Docusaurus | 面向人类和团队协作者的静态知识门户 | 主入口 |
Pagefind | 静态全文检索（构建后索引，不调用外部搜索服务） | 主入口的一部分 |
llms.txt / docs-manifest.json | 面向个人域 Agent、团队域 Agent 和 Program Controller 的低上下文接入层 | 主入口 |
不在当前阶段引入：
- 重型 RAG 应用平台；
- 本地模型或 GPU 依赖；
- 图数据库运行时；
- issue / PR / 日常任务管理系统。
2.1 Docusaurus + Pagefind 的职责
Docusaurus 是当前团队门户生成器，负责：
- 把正式 Markdown 文档发布为网页；
- 提供稳定侧边栏、页内目录和源码编辑链接；
- 让团队成员通过线上门户进入生态层、项目层、评测层、来源层、参考层。
Pagefind 是静态全文检索层，负责：
- 在构建完成后索引已发布页面；
- 不调用外部搜索服务；
- 不引入运行时数据库；
- 不改变文档事实源。
3. Agent 上下文层
当前接入层分为三类：
| 层 | 工具 / 文件 | 主要对象 | 职责 |
|---|---|---|---|
| 人类门户 | Docusaurus + Pagefind | 人类参与者、产品负责人、外部协作者 | 阅读、导航、共享链接、全文检索 |
| Agent manifest | llms.txt、docs-manifest.json | 个人域 Agent、团队域 Agent、Program Controller | 低上下文接入、对象路由、批量读取建议 |
| 动态上下文预备 | Graphiti-ready contract | 个人域 Agent、团队域 Agent、Program Controller | 为后续动态上下文层定义稳定输入契约（当前不运行服务） |
3.1 Agent manifest 的职责
llms.txt 用于快速说明仓库定位、事实源、推荐入口和产品入口。
docs-manifest.json 用于机器读取：
- 当前生态入口；
- 产品 / 系统入口；
- 来源材料、参考分析、评测材料和 sync packet 的关系；
- Agent 读取规则。
任何个人域 Agent 或团队域 Agent 接入时，优先读取：
llms.txtdocs-manifest.json../ACCESS.md- 任务对象对应的 3 到 5 份正式文件
不要让 Agent 从目录树全量扫描开始。
3.2 Graphiti-ready 当前定位
Graphiti-ready 当前只定义未来动态上下文层的事件契约：
- 不运行 Graphiti 服务；
- 不保存图数据库；
- 不要求本地模型；
- 不作为事实源；
- 只消费稳定文档、packet、评测结论和 Program Controller handoff。
4. 当前已知 / 规划中的工具
| 工具 | 用途 | 接入状态 | 替代方案（如不接入） |
|---|---|---|---|
| Multica / Paperclipai | 议题协同、任务调度 | 规划中 | 用 ADR + PR 评审手动跑 |
| open-cowork（agent-os-core） | 团队 Agent 协同 | 重构中 | 用 task-packet + handoff-anchor 文件协议手动跑 |
| Cursor / Codex / Hermes / OpenClaw MCP | 多 Agent 调度 | 已配置（个人域） | Shell 直接调对应 CLI |
| Datadog / Sentry | 运行时观测 | 项目内自选 | 工程仓自带日志 |
详细路由表见个人域 personal-domain-admin/docs/03-routing-matrix.md。
5. 工具接入门槛
每接入一个工具，必须回答：
- 它代理治理流程的哪一步？
- 不接入这个工具，对应步骤如何手动跑？ （回答不出来，说明工具变成 dependency 了，违反核心原则）
- 工具产出如何回写本仓库？ （ADR / PR / commit message 中的引用）
- 撤销 / 切换工具的成本？
6. Agent 与工具的边界
- Agent 可以调用工具，但任何决定性产出必须经本仓库的
change-protocol.md落地； - Agent 不得依赖工具的 in-memory 状态做长程结论；长程结论必须落到本仓库或对应工程仓的文件；
docs-manifest.json只负责路由，不替代正式文档。稳定结论仍必须回写到ecosystem/、projects/、commons/、governance/中的合适位置。
7. 维护原则
- Markdown 是唯一正式事实源；
- 站点、搜索、manifest 和 Graphiti-ready 都是接入层；
- 不把来源材料或参考分析直接升级为产品定义；
- 不把工程仓库事实直接写成生态事实；
- 不重新引入自动静态图谱作为团队或 Agent 的正式入口；
- 每次更新知识库主入口后，必须构建站点并确认 Pagefind 索引生成。