Imported from ice886/StockClaw (
AGENTS.md). Install upstream withnpx skills add ice886/StockClaw. Copyright stays with the author.
AGENTS.md
研究 Agent 系统的开发协作协议。配合 CLAUDE.md 使用：CLAUDE.md 是项目速览与硬约束，本文件是开发流程与文档协议。
需求处理流程协议
当用户提出具体开发需求时，先判定任务类型为 plan（方案/开发需求）或 fix（问题修复），并按对应流程执行。
项目知识缓存协议（Docs/guide + Docs/technical）
项目知识的缓存层分为两个目录，避免每次开发都重复扫描大量代码：
| 目录 | 定位 | 内容侧重 |
|---|---|---|
Docs/guide/ |
项目现状探索总结 | Agent 主动检索代码后沉淀的结构性知识：模块职责、核心链路、关键调用关系、现有实现梳理 |
Docs/technical/ |
深度技术设计文档 | Agent 针对具体需求主动设计的方案：详细架构、Schema/数据模型、算法说明、时序图、接口契约 |
执行流程：
- 接到需求后，优先查阅
Docs/guide/和Docs/technical/是否已有相关文档 - 若已有文档覆盖所需上下文，直接使用，不必扫描代码
- 若文档不存在或信息不足，再扫描代码获取上下文
- 扫描完成后，如有必要，将现状总结回写到
Docs/guide/，供后续 session 复用
文档规范：
- 文件命名：大写字母 +
&或_分隔的.MD（如BLACKBOARD&ARTIFACT.MD、SOLVER_ITERATION_LOOP.MD） - 内容范围：模块职责、核心链路、关键 Schema、调用关系、配置要点等不易频繁变动的结构性知识
- 不适合放入：临时调试记录、单次 fix 细节、频繁变动的业务逻辑快照
- 发现已有文档过时，应在本次开发中顺带更新，保持缓存有效
三类文档的关系：
Docs/guide/：项目现状探索总结（"现在是什么样的"）——agent 主动探索Docs/technical/：需求驱动的技术设计（"打算怎么做"）——agent 主动设计Docs/feature/：功能维度描述（"功能是什么"）——功能说明、使用方式、配置项
任务类型判定规则（Plan / Fix）
plan：以新需求实现、方案设计、功能优化为主，按计划流程执行。fix：以修复报错、回归问题、异常行为为主，按修复流程执行。- 若同时包含两类诉求，按当前主诉求优先；必要时拆分为两阶段（先 fix 后 plan，或反之）。
标准执行顺序（Plan）
- 给出计划（plan）
- 计划获同意后，将计划写入
Docs/plan/下的 Markdown 文档 - 完成 plan 文档更新后，再执行开发
- 开发完成后，先询问是否需要沉淀开发总结文档；同意后按文档协议更新
- 最后询问是否需要提交代码；需要则按 Git Commit 协议提交
标准执行顺序（Fix）
- 明确修复目标与影响范围，按需补充最小修复步骤（可不走完整 plan 审批）
- 先询问是否需要落盘 fix 文档到
Docs/issue/fix/ - 执行修复与验证
- 修复完成后，将结果同步写入 fix 文档（若已同意落盘）
- 最后询问是否需要提交代码；需要则按 Git Commit 协议提交
Plan 输出要求
- 先理解需求并拆解任务范围
- 输出 3-7 条可执行步骤（按顺序）
- 标注关键影响点（如 harness/workflow/agents/solver/sandbox/测试/文档）
- 如有风险或依赖，提前说明
编码前确认要求
- 明确询问用户是否同意当前 plan
- 仅在用户明确同意后，先更新
Docs/plan/文档，再开始代码修改 - 若用户要求调整 plan，先更新 plan 并再次确认
Fix 记录要求
- fix 场景需先询问是否落盘修复文档（
Docs/issue/fix/） - 若同意落盘，修复完成后必须同步记录（现象、根因、修复动作、验证结果）
- 一个 session 尽量维护一个 fix 文档，文件名稳定、可追踪
Plan 文档要求
- 一个 session 尽量维护一个 plan 文档（避免拆分为多个零散文档）
- 文件名稳定、可追踪，并在后续开发总结中复用同名文件名
Daily Log 记录要求
-
Docs/dailylog/下文档不应被其他功能文档引用（仅记录当天工作内容和影响范围）
例外情况
- 纯咨询类问题（无代码改动）可直接回答，无需 plan 确认
- 用户明确说"直接改/跳过 plan"时，可直接执行
- 用户明确说"跳过文档落盘"时，可跳过文档更新
- fix 场景下用户明确说"不落盘 fix 文档"时，可仅修复并在回复中说明未落盘
代码生成后协议
1. 文档更新协议
生成或修改代码后，必须检查和更新相关文档：
- 检查
README.md是否需要更新（新增功能、改变使用方式） - 按知识缓存协议更新相关
Docs/guide//Docs/technical//Docs/feature/文档 - 若新增/修改了工具（ToolRegistry）或制品 Schema（Blackboard models），更新对应技术文档
- 若新增环境变量，更新
.env.example与配置文档 - 记录当天工作内容与影响范围到
Docs/dailylog/ - fix 任务在用户同意落盘时，更新
Docs/issue/fix/下对应修复文档
文档更新优先级：
- 高：配置变更、对外接口/工具契约变更、运行方式变更
- 中：功能更新、使用方式变更
- 低：内部重构、实现优化（无外部影响）
2. Git Commit 协议
Commit Message 格式：
<type>(<scope>): <subject>
<body>
<footer>
Type：feat | fix | docs | style | refactor | test | chore
Scope：harness | workflow | agents | solver | sandbox | blackboard | config | docs
提交前检查清单：
- 运行测试：
pytest - 运行代码检查：
ruff check .（如配置了类型检查则一并mypy .） - 确认未提交敏感信息（API Keys、密码等）
- 确认
.env未被提交
提交流程：
- 用户要求提交时，先展示
git status与git diff --stat，确认变更范围 - 根据修改内容生成 commit message 建议
- 执行提交（默认不直接 push 到主分支，需要推送时新建分支并
-u）
3. 代码质量协议
提交前必须运行（本项目为 Python）：
-
ruff check . -
mypy .（若已配置） -
pytest
发现错误时：先修复 → 再次运行检查 → 通过后再提交。
4. 安全协议
- 不提交
.env或含密钥的文件；API Keys 一律走环境变量 - 不在日志、prompt、制品中写入密钥明文
- 沙箱执行 LLM 生成代码前不得放宽隔离约束（非 root / 断网 / 资源限额）
- 提交前扫描敏感信息：API Keys（
sk-*等）、密码、JWT secrets、私钥文件
执行检查点
完成每个任务后主动检查：
- 文档是否需要更新？ —— 看修改的文件类型，判断是否影响使用，更新相关文档
- 是否需要提交代码？ —— 询问用户，展示变更摘要，生成合适的 commit message
- 代码质量是否达标？ —— 运行 lint / 类型检查 / 测试
例外情况
以下情况可不严格遵循上述协议：
- 纯文本编辑（README、文档等）
- 临时调试代码（应明确标记为 WIP）
- 用户明确要求跳过某些检查
协议更新
本协议可随项目需求更新。更新时：修改此文件 → 在 commit message 注明"更新 AGENTS.md 协议" → 简要说明更新内容。