65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
 
|
# Agent 上下文清单
|
||
|
|
|
||
|
|
> [`agent-context.json`](agent-context.json) 是机器可读的文档路由,[`agent-context.schema.json`](agent-context.schema.json) 定义结构契约;本文解释 agent 应如何使用它。清单只保存路径和刷新规则,不复制文档正文。
|
||
|
|
|
||
|
|
## 解决什么问题
|
||
|
|
|
||
|
|
上下文清单解决的是"本轮该读什么":
|
||
|
|
|
||
|
|
1. 先读 `bootstrap.always_read`,建立最小安全与状态上下文。
|
||
|
|
2. 根据任务类型选择一个或多个 `routes`(本仓库:`documentation` 文档类、`protocol` 协议/签名类、`data` 数据模型类、`deploy` 构建部署类)。
|
||
|
|
3. 只读取这些路径和本轮任务文件。
|
||
|
|
4. 用默认分支头提交 SHA 作为 `context_ref`,用单文件 SHA 作为缓存键。
|
||
|
|
|
||
|
|
## 首次接入与日常会话
|
||
|
|
|
||
|
|
首次接入、清单缺失或清单校验失败时,执行 `00-ai-start-here.md` 中的完整阅读顺序,先修复清单再做功能任务。
|
||
|
|
|
||
|
|
日常会话执行:
|
||
|
|
|
||
|
|
```text
|
||
|
|
AGENTS.md
|
||
|
|
-> agent-context.json
|
||
|
|
-> bootstrap.always_read
|
||
|
|
-> 本轮任务文件(docs/tasks/W-<编号>.md)
|
||
|
|
-> routes.<任务类型>
|
||
|
|
-> 修改与验证
|
||
|
|
```
|
||
|
|
|
||
|
|
一个任务可以命中多个路由,重复路径只加载一次。
|
||
|
|
|
||
|
|
## 提交 SHA 与缓存
|
||
|
|
|
||
|
|
- `context_ref`:领取任务时默认分支的头提交 SHA。
|
||
|
|
- 同一会话内文件 SHA 未变化时复用已读内容;默认分支头变化时重新读取清单及变化文件。
|
||
|
|
- 本地有未提交改动:本地内容仅对当前 worktree 有效;回复和任务记录中要说明差异。
|
||
|
|
|
||
|
|
缓存只用于减少重复读取,不能跨提交假定内容不变,也不能代替 Git 历史。
|
||
|
|
|
||
|
|
## 权威来源
|
||
|
|
|
||
|
|
| 信息 | 权威来源 |
|
||
|
|
| --- | --- |
|
||
|
|
| 仓库级硬规则 | 最近作用域的 `AGENTS.md` |
|
||
|
|
| 协议(清单/包/许可证/签名域) | 客户端仓库 `soft_quay`(api.md、schemas、corpus);本仓库 `docs/api.md` 仅为摘要 |
|
||
|
|
| 需求、架构、编码纪律 | 本仓库版本化文档 |
|
||
|
|
| 任务规格与长期执行证据 | `docs/tasks/W-<编号>.md` |
|
||
|
|
| 当前代码行为 | 代码与真实验证结果 |
|
||
|
|
|
||
|
|
## 断连 / 客户端仓库不可用降级
|
||
|
|
|
||
|
|
同级客户端仓库(`../soft_quay`)不可读时:
|
||
|
|
|
||
|
|
- 可以基于本仓库已引用的 Schema/corpus 副本(W-001 落实后)继续当前任务。
|
||
|
|
- 不得凭记忆修改协议相关实现;涉及协议疑义先恢复对权威源的访问。
|
||
|
|
|
||
|
|
## 清单维护
|
||
|
|
|
||
|
|
新增、移动或删除清单引用的文件时,同步修改 `agent-context.json`,并运行:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 scripts/validate_agent_context.py
|
||
|
|
```
|
||
|
|
|
||
|
|
校验必须确认:必需分区存在、路径为仓库相对路径、引用文件真实存在、最小启动文件齐全。
|