跳到主要内容

Agent Context Layer

状态：Active / 接入与机器可读上下文层 最后更新：2026-05-11 用途：定义本仓库如何同时服务人类阅读、个人域 Agent、团队域 Agent 和后续动态上下文层接入

1. 结论​

本仓库的主事实源仍然是 Markdown 文件。门户、搜索、manifest 和未来动态上下文层都是接入层，不替代正式事实源。

当前接入层分为四类：

层工具 / 文件主要对象职责
人类门户Docusaurus人类参与者、产品负责人、外部协作者阅读、导航、检索、共享链接
全文检索Pagefind人类与 Agent对已发布页面做静态全文检索
Agent manifestllms.txt、docs-manifest.json个人域 Agent、团队域 Agent、Program Controller低上下文接入、对象路由、批量读取建议
Graphiti-readyagent-context/graphiti/后续上下文层或协作系统稳定事件契约，不在当前部署中运行

2. 为什么不保留自动静态图谱​

当前仓库不再保留自动静态图谱工具及其产物。原因是自动静态图谱容易把治理关系、产品关系、来源关系和代码关系混在一起，反而增加团队成员和个人域 Agent 的理解成本。

关系理解应回到两个稳定入口：

  • 正式关系：以 生态关系注册表 和对应事实源为准；
  • 任务路由：以 llms.txt、docs-manifest.json 和本指南为准。

3. Docusaurus + Pagefind 的职责​

Docusaurus 是当前团队门户生成器，负责：

  • 把 portal/ 暴露的正式 Markdown 文档发布为网页；
  • 提供稳定侧边栏、页内目录和源码编辑链接；
  • 让团队成员通过线上门户进入生态层、项目层、评测层、来源层、参考层和 packet 层。

Pagefind 是静态全文检索层，负责：

  • 在构建完成后索引 build/ 中的页面；
  • 不调用外部搜索服务；
  • 不引入运行时数据库；
  • 不改变文档事实源。

4. Agent manifest 的职责​

llms.txt 和 docs-manifest.json 是 Agent 接入层的第一批稳定文件。

llms.txt 用于快速说明仓库定位、事实源、推荐入口和产品入口。

docs-manifest.json 用于机器读取：

  • 当前生态入口；
  • 产品 / 系统入口；
  • 来源材料、参考分析、评测材料和 sync packet 的关系；
  • 后续 Graphiti-ready 上下文层的角色边界；
  • Agent 读取规则。

任何个人域 Agent 或团队域 Agent 接入时，优先读取：

  1. llms.txt
  2. docs-manifest.json
  3. ACCESS_GUIDE.md
  4. 任务对象对应的 3 到 5 份正式文件

不要让 Agent 从目录树全量扫描开始。

5. Graphiti-ready 当前定位​

Graphiti-ready 是后续动态上下文层的输入契约，不是当前运行时。

它适合后续承接：

  • Program Controller 的上下文记忆；
  • 产品对象、任务包、sync、escalation、决策、验收之间的时间化关系；
  • 人类成员、个人域 Agent、团队域 Agent 的协作轨迹；
  • 与后续协作平台的上下文查询。

当前不部署 Graphiti 服务，也不要求团队成员安装本地模型。先把文档侧的输入契约准备好，避免过早引入重型运行时。

6. Graphiti-ready 输入契约​

Graphiti-ready 层应只消费稳定事件，不消费临时聊天过程。候选输入包括：

  • 产品定义或基线文档的关键变更；
  • packet 创建、状态变化、验收结论；
  • Program Controller handoff；
  • source / reference 材料被吸收、搁置或标记为反例；
  • escalation 被提出、解决或关闭。

每条输入事件至少应包含：

字段含义
event_id稳定事件 ID
event_typedoc_update、packet_sync、escalation、reference_absorption 等
occurred_at事件发生时间
source_path对应 Markdown 文件路径
summary一句话事实摘要
entities涉及产品、系统、材料、团队角色或 Agent
evidence_paths可追溯证据文件
authority是否改变正式事实源

本仓库新增的 agent-context/graphiti/ 目录只保存这一输入契约和种子示例，不保存运行时数据库。

7. 维护原则​

  • Markdown 仍是唯一事实源；
  • Docusaurus / Pagefind 只发布和检索事实源；
  • docs-manifest.json 是 Agent 路由，不是事实源替代；
  • Graphiti-ready 是未来动态上下文层的输入契约，不代表当前已部署 Graphiti；
  • 不把 open-cowork 当前迭代状态写入本仓库的强依赖链路。