随着 AI Agent 使用时间增长，工作区中的规则、主机信息、操作手册、故障记录和长期记忆往往会不断积累。
一开始，所有内容可能只有几个 Markdown 文件。为了让 Agent 每次启动时都能理解环境，这些文件通常会被自动注入上下文。然而，当内容逐渐增加后，一个新的问题随之出现：
Agent 每处理一次普通任务，都要重新读取大量与当前任务无关的技术资料。
例如，处理一个简单文件操作时，模型可能同时接收到：
- 某台主机的完整硬件资料；
- 某个远程桌面环境的授权流程；
- 浏览器调试接口的启动和关闭手册；
- 网络故障的完整抓包分析；
- 邮件中继配置；
- 多台服务器的连接清单；
- 多年前的历史修复记录。
这些资料都很重要，不能删除，但也没有必要在每轮对话中全部注入。
解决这个问题的一种有效方法，是在工作区中建立一个独立的、按需读取的 context/ 资料库。
一、问题不只是某个文件太长
不少 Agent 工作区会包含类似文件：
AGENTS.md
TOOLS.md
MEMORY.md
USER.md
IDENTITY.md
SOUL.md
HEARTBEAT.md
这些文件通常承担不同职责：
AGENTS.md：行为规则和安全边界；TOOLS.md：工具、主机、路径和运行环境；MEMORY.md：长期记忆；USER.md：用户偏好；HEARTBEAT.md：周期任务；IDENTITY.md、SOUL.md：身份和行为风格。
问题在于，详细技术资料往往会逐渐混入这些启动文件。
例如，一个网络问题可能在排查后留下几千字内容，其中包括：
- 网络接口名称；
- 子网和网关；
- 防火墙区域；
- DHCP 报文；
- 故障分类；
- 修复命令；
- 验证步骤；
- 禁止操作；
- 回滚方法。
这些内容确实值得长期保存。如果全部留在 TOOLS.md 或 MEMORY.md 中，每次启动都会重复占用上下文。
仅仅把内容从 MEMORY.md 移到 TOOLS.md，并没有真正解决问题。它只是把负担从一个自动注入文件转移到了另一个自动注入文件。
真正需要优化的是：
所有启动文件的总注入量，而不是某一个文件的长度。
二、三层知识结构
更适合长期维护的结构，可以分为三个层级。
1. 启动层
每轮对话都应知道的内容，继续保存在自动注入文件中：
AGENTS.md
TOOLS.md
USER.md
MEMORY.md
IDENTITY.md
SOUL.md
这一层只保存：
- 必须始终遵守的安全规则；
- 当前最常用的环境入口；
- 用户长期偏好；
- 少量长期决策；
- Context 资料库的使用规则。
启动层应当短、小、稳定。
2. 按需资料层
详细技术资料进入：
context/
这一层保存：
- 完整主机资料；
- 服务部署基线；
- 操作手册；
- 排错流程；
- 恢复步骤；
- 跨主机参考表；
- 已确认的稳定技术状态。
这些文件不应每轮自动注入，而应在任务需要时由 Agent 主动读取。
3. 历史与证据层
历史过程继续保存在：
memory/YYYY-MM-DD.md
output/
其中：
- 日期记忆保存某天发生了什么；
output/保存报告、差异、迁移映射和验证证据。
这三个层级可以概括为：
每轮必须知道的规则 → 启动文件
当前完整技术资料 → context/
历史过程与证据 → memory/ 和 output/
三、Context 目录不能成为新的垃圾桶
简单建立一个目录并不难：
context/
真正困难的是防止它在半年后变成这样：
waydroid-guide.md
waydroid-network-notes.md
waydroid-final.md
waydroid-final-v2.md
new-waydroid-fix.md
full-waydroid-manual.md
如果允许 Agent 自由使用自然语言命名，重复文件几乎不可避免。
因此，context/ 必须被设计成一个有注册表、有永久编号、有唯一主题键的资料库，而不是普通文件夹。
四、推荐的目录结构
一个适合长期使用的结构如下：
context/
├── INDEX.md
├── active/
│ ├── ctx-0001-host-primary-server.md
│ ├── ctx-0002-host-workstation.md
│ ├── ctx-0003-service-agent-runtime.md
│ ├── ctx-0004-runbook-graphical-authorization.md
│ ├── ctx-0005-runbook-container-network.md
│ ├── ctx-0006-runbook-browser-debugging.md
│ ├── ctx-0007-reference-host-connections.md
│ └── ctx-0008-baseline-mail-relay.md
└── archive/
目录职责：
active/
存放当前有效、允许用于实际操作的资料。
archive/
存放已经被替代、但仍需要保留的旧版本。
归档文件不能继续作为当前操作依据。
INDEX.md
作为整个资料库的唯一注册表，负责：
- 永久编号；
- 文件路径；
- 文档类型；
- 唯一主题键；
- 别名；
- 当前状态；
- 更新时间；
- 实际验证时间；
- 继承和替代关系。
五、永久编号比自然语言文件名更可靠
推荐文件名格式：
ctx-NNNN-TYPE-SLUG.md
例如：
ctx-0001-host-primary-server.md
ctx-0002-host-workstation.md
ctx-0003-service-agent-runtime.md
ctx-0004-runbook-graphical-authorization.md
其中：
ctx-0001是永久身份；host、service、runbook是固定类型；- 后面的 slug 只是人类可读名称。
编号规则应当明确：
- 使用四位数字；
- 全局统一编号；
- 不按类别分别编号；
- 编号一旦分配，永久不变；
- 归档后也不能复用；
- 文件标题变化时，编号不变；
- 文件路径原则上保持稳定；
- 下一个编号只能由
INDEX.md分配。
这样即使标题后来发生变化，文档身份仍然稳定。
六、使用唯一的 Canonical Key
文件名只能解决名称重复，不能完全解决语义重复。
例如下面三个文件名不同：
waydroid-network.md
waydroid-firewall.md
waydroid0-recovery.md
但它们可能描述的是同一个问题。
因此，每个文件还需要一个全局唯一的主题键：
---
id: ctx-0005
canonical_key: runbook.workstation.container-network
---
其他例子：
host.primary-server
host.workstation
service.agent-runtime
runbook.workstation.graphical-authorization
runbook.workstation.container-network
runbook.workstation.browser-debugging
reference.host-connections
baseline.mail-relay
规则应当是：
一个 canonical key 只能对应一个 active 权威文件。
创建新文件前，Agent 必须搜索：
- ID；
- canonical key；
- 文件名；
-标题； - aliases；
- 现有正文。
如果已经存在相同主题，应更新原文档，而不是新建第二份。
七、别名用于防止自然语言重复
同一个技术主题可能有多种叫法。
例如：
container network
virtual interface
trusted firewall zone
android network
这些词可以登记为同一个 context 文件的 aliases。
但别名不能过于模糊。
不推荐：
network
gateway
server
browser
backup
更合适的是：
container network gateway
agent runtime gateway
workstation browser debugging
primary server backup
一个明确 alias 原则上只能指向一个 active 文档。
八、INDEX 是唯一注册表
INDEX.md 不只是目录说明，而应承担数据库注册表的角色。
示例：
# Context Library Index
## Governance
- INDEX.md is the only registry.
- Context IDs are permanent and must never be reused.
- One canonical key may have only one active document.
- Search IDs, keys, aliases and existing content before creating files.
- New document types or subdirectories require explicit approval.
- Archive documents must not be used as current operating procedures.
## Active Registry
| ID | Canonical key | File | Type | Status | Aliases | Last updated | Last verified |
|---|---|---|---|---|---|---|---|
| ctx-0001 | host.primary-server | active/ctx-0001-host-primary-server.md | host | active | main server | 2026-07-24 | 2026-07-24 |
| ctx-0002 | host.workstation | active/ctx-0002-host-workstation.md | host | active | desktop workstation | 2026-07-24 | unknown |
## Archived Registry
| ID | Canonical key | File | Superseded by | Archived |
|---|---|---|---|---|
## Next Available ID
ctx-0009
其中要区分：
last_updated：文档最后编辑时间；last_verified：资料最后经过真实环境验证的时间。
修改了文字，不代表重新验证了环境。
九、Context 文档只保存“现在应该怎么做”
Context 文档不应变成第二套时间日志。
不推荐在文末持续追加：
某日修改了什么
某日发现了什么
某日又失败了一次
某日重新测试成功
这些过程应进入日期记忆。
Context 文档只保留：
- 当前权威状态；
- 当前操作方法；
- 当前验证方法；
- 当前禁止事项；
- 回滚流程；
- 历史证据链接。
例如：
## Historical Evidence
- Initial root-cause investigation:
see `memory/2026-06-14.md`
- Permanent repair validation:
see `memory/2026-06-15.md`
这样可以避免 context 文件不断膨胀。
十、安全规则不能全部移出启动文件
详细操作流程可以放进 context/，但关键安全边界仍然必须保留在 AGENTS.md。
例如某个浏览器自动化手册可能有几十条详细步骤，但下面这些高风险规则应继续自动注入：
不得影响普通浏览器进程
不得使用模糊进程匹配
不得使用 killall
不得删除专用用户目录
不得把调试接口暴露到局域网
原因很简单：
Agent 在读取具体 runbook 之前，就必须已经知道哪些事情绝对不能做。
因此允许安全规则在两个地方重复：
AGENTS.md保存简短强制边界；- context runbook 保存完整解释和操作步骤。
这种重复属于有价值的安全冗余。
十一、迁移必须采用“复制、验证、再移除”
把长篇内容从启动文件迁到 context 时，不能直接剪切。
更安全的顺序是：
完整读取来源
→ 保存原始章节副本
→ 生成候选 context 文件
→ 验证候选内容
→ 写入正式 context 文件
→ 在启动文件中保留摘要和精确路径
→ 再移除详细原文
→ 检查 diff
修改重要文件前还应建立可验证的备份。
需要检查：
- SHA-256；
- 原始修改时间；
- 权限；
- 所有者；
- 备份路径；
- 回滚方法。
这样即使迁移中断，也能明确恢复到原始状态。
十二、不要一次迁移所有内容
第一批适合迁入 context 的资料通常包括：
- 主机完整基线；
- Agent 运行服务资料；
- 图形授权流程；
- 容器或虚拟环境网络手册；
- 浏览器调试接口手册；
- 主机连接清单；
- 邮件中继基线。
不适合一次性迁移的内容包括：
- 所有日期记忆；
- 所有历史日志；
- 所有零散备注；
- 尚未形成稳定结论的调查；
- 一次性任务输出。
每个 context 文件都应当具备相对清晰的独立职责。
十三、静态减负不等于运行时减负
文件整理完成后，不能只统计磁盘上的字符数。
必须区分三种数字：
1. 文件系统静态总量
所有候选启动文件在磁盘上的字符数。
2. 实际注入字符数
新会话中真正传给模型的 workspace 文件内容。
3. 完整上下文使用量
还包括：
- 系统提示词；
-技能描述； - 工具 schema；
- 会话历史；
-运行时开销。
因此，最终必须在一个全新会话里检查运行时上下文。
例如：
/context list
/context detail
这些是交互式会话中的 slash commands，不是普通 shell 子命令。
十四、一次真实的运行时验收结果
在完成迁移后，一次新会话的运行时检查显示：
Bootstrap max/file: 20,000 chars
Bootstrap max/total: 60,000 chars
主要文件的实际情况如下：
| 文件 | Raw | Injected |
|---|---|---|
| 行为规则 | 约 22,900 | 约 22,900 |
| 工具入口 | 约 7,200 | 约 7,200 |
| 身份定义 | 约 2,000 | 约 2,000 |
| 用户偏好 | 约 1,050 | 约 1,050 |
| 长期记忆 | 约 1,570 | 约 1,570 |
| 人格规则 | 约 1,800 | 约 1,800 |
| 周期任务文件 | 约 10,700 | 0 |
普通新会话实际注入的 workspace 文件总量约为：
36,500 字符
相比迁移前约 67,000 字符的核心静态文件规模，运行时负担明显下降。
更重要的是：
context/INDEX.md
context/active/*.md
没有被自动全部注入。
这说明按需资料库确实生效。
十五、为什么周期任务文件可能显示为 0
运行时检查中，某些文件可能显示：
raw 10,000+
injected 0
这不一定是错误。
有些文件只在特定运行模式中使用，而不会进入普通交互会话。
因此，不能单纯用所有磁盘文件相加来推断实际注入量。
真正可靠的判断依据是：
raw
injected
truncated
而不是静态文件大小。
十六、Context 资料库的主要失败模式
1. 变成新的杂物目录
表现：
new
latest
final
v2
notes
misc
防线：
- 永久 ID；
- canonical key；
- aliases；
- INDEX 注册；
- 创建前搜索。
2. 同一事实存在多个权威来源
例如 IP、端口或版本在多个文件中分别维护。
防线：
- 每类事实指定唯一权威来源；
- 其他文件只写精确指针；
- 更新时同步检查交叉引用。
3. INDEX 与文件不同步
表现：
- 文件存在但没有登记；
- INDEX 指向不存在文件；
- 两个文件使用相同 ID。
防线：
- 修改前记录 INDEX 哈希；
- 写入前重新确认没有并发变化；
- 完成后检查 orphan 文件和重复 ID。
4. 历史资料被误认为当前状态
防线：
active/
archive/
只允许 active 文件作为当前操作依据。
5. 过度碎片化
表现：
- 完成一个任务需要连续读取十几个小文件。
防线：
只有在内容具备独立用途、独立更新周期或独立权威范围时，才拆成新文档。
十七、长期可持续的核心纪律
一套 Context 资料库能否长期使用，最终取决于下面几条纪律：
没有登记，不得创建
所有文件必须先进入 INDEX。
一个主题只能有一个 active 权威文件
相同 canonical key 不允许并存。
安全规则留在启动层
完整方法可以按需读取，但关键禁止事项必须始终可见。
当前方法与历史过程分开
当前方法 → context/
历史过程 → memory/YYYY-MM-DD.md
证据报告 → output/
文件路径尽量稳定
标题可以演进，永久 ID 和路径不应频繁改变。
不默认读取整个 Context 目录
Agent 先查 INDEX，再只读取与当前任务有关的一份或少量文件。
十八、最终效果
建立独立 Context 资料库后，可以同时实现两件原本看似矛盾的目标：
- 完整保留详细技术资料；
- 降低每轮对话的启动上下文负担。
最终形成的结构是：
启动文件
保存短小、稳定、每轮必须知道的内容
context/active/
保存当前完整技术资料和操作手册
context/archive/
保存被替代但不能删除的旧资料
memory/YYYY-MM-DD.md
保存历史过程和当日证据
output/
保存报告、diff、迁移副本和验收结果
这种设计并不是简单地把大文件拆成小文件，而是在工作区中建立了明确的知识生命周期：
事件发生
→ 进入日期记忆
→ 形成稳定结论
→ 晋升为 context 文档
→ 在启动文件中留下简短入口
→ 旧版本进入 archive
当详细资料不再被每轮重复注入，Agent 的启动上下文会更加集中，规则也更容易被正确执行。
与此同时，所有技术细节仍然完整保存在工作区中，需要时可以通过 INDEX 精确找到。
这是一种兼顾信息完整性、运行效率和长期维护性的 AI Agent 知识管理方法。