222 lines
9.2 KiB
Markdown
222 lines
9.2 KiB
Markdown
# AGENT_RULES
|
||
|
||
目的：为本仓库提供稳定的执行流程与行为规范。
|
||
|
||
## 优先级
|
||
|
||
1. 系统/开发者指令与安全约束
|
||
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
|
||
3. 仓库规则：`.agents/` 与 `AGENTS.md`
|
||
4. 本文件
|
||
|
||
## 安全红线
|
||
|
||
- 不得在代码/日志/注释中写入明文密钥、密码、Token
|
||
- 修改鉴权/权限逻辑必须说明动机与风险
|
||
- 不确定是否敏感时按敏感信息处理
|
||
- 执行修改文件系统的命令前，必须解释目的和潜在影响
|
||
|
||
## 行为准则
|
||
|
||
### 项目适应
|
||
|
||
- **模仿项目风格**：优先分析周围代码和配置，遵循现有约定
|
||
- **不假设可用性**：不假设库或框架可用，先验证再使用
|
||
- **完整完成请求**：不遗漏用户要求的任何部分
|
||
|
||
### 技术态度
|
||
|
||
- **准确性优先**：技术准确性优先于迎合用户
|
||
- **诚实纠正**：发现用户理解有误时，礼貌纠正
|
||
- **先查后答**：不确定时先调查再回答
|
||
|
||
### 避免过度工程
|
||
|
||
- **只做要求的**：不主动添加未要求的功能或重构
|
||
- **不过度抽象**：不为一次性操作创建工具函数
|
||
- **不为未来设计**：不为假设的未来需求设计
|
||
|
||
## 沟通原则
|
||
|
||
- **统一简体中文**：所有回复均使用简体中文
|
||
- **简洁直接**：专业、直接、简洁，避免对话填充词
|
||
- **拒绝时提供替代**：无法满足请求时，简洁说明并提供替代方案
|
||
- **不给时间估算**：专注任务本身，让用户自己判断时间
|
||
- **代码块标注语言**：输出代码时标注语言类型
|
||
- **不使用 emoji**：除非用户明确要求
|
||
|
||
## 上下文加载（每次会话开始）
|
||
|
||
**必读文档**（按顺序）：
|
||
|
||
1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
|
||
2. `.agents/index.md` - 语言规则入口（如存在）
|
||
3. `memory-bank/project-brief.md` - 项目定位、边界、约束
|
||
4. `memory-bank/tech-stack.md` - 技术栈、工具链
|
||
5. `memory-bank/architecture.md` - 架构设计、模块职责
|
||
6. `memory-bank/decisions.md` - 重要决策记录（如存在）
|
||
7. `memory-bank/progress.md` - 执行进度与状态（如存在）
|
||
8. `docs/plans/` - 最新实施计划（如存在）
|
||
|
||
**目的**：让 AI 快速理解项目全貌，避免重复解释。
|
||
|
||
## 规划与执行分工
|
||
|
||
| 阶段 | 工具 | 产出 | 留痕 |
|
||
| ------------ | ---------------------- | ----------------- | -------------------- |
|
||
| 头脑风暴 | `$brainstorming` skill | 设计思路 | 无 |
|
||
| 生成计划 | `$writing-plans` skill | `docs/plans/*.md` | 无 |
|
||
| **执行计划** | **主循环** | 代码/配置变更 | **plan_progress.py** |
|
||
|
||
> **重要**：第三方 skills 不记录操作状态，执行必须通过主循环完成。
|
||
|
||
## 主循环
|
||
|
||
**触发词**：
|
||
|
||
| 触发词 | 模式 | 说明 |
|
||
| --------------------------------------- | ---------- | ---------------------- |
|
||
| `执行主循环`、`继续执行`、`下一个 Plan` | 常规模式 | 遇确认场景可询问用户 |
|
||
| `自动执行所有 Plan` | 无交互模式 | 不询问，按规则自动处理 |
|
||
|
||
**Plan 状态**：
|
||
|
||
| 状态 | 含义 |
|
||
| ----------- | ------------------------- |
|
||
| pending | 待执行 |
|
||
| in-progress | 执行中（崩溃恢复用） |
|
||
| done | 已完成 |
|
||
| blocked | 阻塞（需人工介入） |
|
||
| skipped | 跳过（Plan 不再需要执行） |
|
||
|
||
> 说明：`skipped` 仅用于永久不再执行；如需恢复执行，需手动改回 `pending`。
|
||
|
||
**环境阻塞格式**：`blocked: env:<环境>:<Task列表>`
|
||
|
||
- 示例：`blocked: env:windows:Task2,Task4`
|
||
- 含义：需要在指定环境执行列出的 Task
|
||
- 约束：`Task` 列表使用英文逗号分隔，不要包含空格，便于解析
|
||
|
||
**流程**：
|
||
|
||
1. 检测环境：
|
||
- 由 `plan_progress.py` 自动识别当前环境（`windows` / `linux` / `darwin`）
|
||
2. 选择 Plan：
|
||
- 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
|
||
- 返回第一个可执行的 Plan：
|
||
- `pending` 或 `in-progress` 的 Plan
|
||
- `blocked: env:<当前环境>:...` 的 Plan（环境匹配时恢复执行）
|
||
- 如无可执行 Plan，跳到步骤 7
|
||
- **注意**：每次 select 会重新扫描 `docs/plans/` 目录，支持动态添加 Plan
|
||
3. 标记开始：
|
||
- 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md`
|
||
4. 阅读 Plan：
|
||
- 理解目标、子任务与验证标准
|
||
- 如果是从 `blocked: env:...` 恢复，只执行列出的 Task
|
||
5. 逐步执行：
|
||
- 按顺序执行 Task
|
||
- 每个 Task 完成后进行必要验证（测试/日志/diff）
|
||
- **Task 失败处理**：
|
||
- 环境不匹配（`command not found`、路径不存在）→ 记录该 Task 及所需环境，**继续下一个 Task**
|
||
- 其他阻塞 → 记录原因，跳到步骤 6 标记 Plan blocked
|
||
- **安全红线**（明文密钥等）→ 立即停止，不继续后续 Plan
|
||
- 遇到歧义/风险/决策点：
|
||
- 常规模式：记录到回复中，可询问用户
|
||
- 无交互模式：按「需要确认的场景」规则自动处理
|
||
6. 记录结果：
|
||
- 全部完成：`... -status done ...`
|
||
- 有 Task 因环境跳过：`... -status blocked ... -note "env:<所需环境>:<Task列表>"`
|
||
- 其他阻塞：`... -status blocked ... -note "<原因>"`
|
||
- 跳过整个 Plan：`... -status skipped ... -note "<原因>"`
|
||
- 回到步骤 2 继续下一个 Plan
|
||
7. 汇总报告（所有 Plan 处理完毕后）：
|
||
- 已完成的 Plan
|
||
- 阻塞/跳过的 Plan 及原因
|
||
- 需要在其他环境执行的 Plan（`blocked: env:...`）
|
||
- 待确认的歧义/风险/决策点
|
||
- 如需记录重要决策，写入 `memory-bank/decisions.md`
|
||
8. **结束**：主循环终止
|
||
|
||
## Plan 规则
|
||
|
||
- **Plan Meta 必填**：Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`，包含：
|
||
- `Plan Group`（归类任务）
|
||
- `Parent Plan`（上层/集成计划链接）
|
||
- `Verification Scope`（local 或 integration）
|
||
- `Verification Gate`（must-pass）
|
||
- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan
|
||
- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
|
||
- 不因等待确认而中断可执行步骤；待确认事项在回复中列出
|
||
- 每轮只处理一个 Plan
|
||
- **小步快跑**：每个 Plan 应该可快速完成
|
||
- **可验证**：每个 Plan 必须包含验证步骤
|
||
|
||
## 执行约束
|
||
|
||
### 代码修改
|
||
|
||
- **必须先读文件再修改**：不读文件就提议修改是禁止的
|
||
- **必须运行测试验证**：相关测试必须通过
|
||
- **遵循换行规则**：遵循 `.gitattributes` 规则
|
||
- **命名一致性**：遵循项目现有的命名风格
|
||
- **最小改动原则**：只修改必要的部分，不顺手重构
|
||
|
||
### 决策记录
|
||
|
||
- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
|
||
- **待确认事项**：在回复中列出并等待确认
|
||
- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
|
||
|
||
### Git 操作
|
||
|
||
- **不使用 --amend**：除非用户明确要求，总是创建新提交
|
||
- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险
|
||
- **不跳过 hooks**：不使用 `--no-verify`
|
||
|
||
## 工具使用
|
||
|
||
- **并行执行**：独立的工具调用尽可能并行执行
|
||
- **遵循 schema**：严格遵循工具参数定义
|
||
- **避免循环**：避免重复调用同一工具获取相同信息
|
||
- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob
|
||
|
||
## 需要确认的场景
|
||
|
||
**常规模式**（可交互）：
|
||
|
||
- 需求不明确或存在多种可行方案
|
||
- 需要行为/兼容性取舍
|
||
- 风险或约束冲突
|
||
- **架构变更**：影响多个模块的修改
|
||
- **性能权衡**：需要在性能和可维护性之间选择
|
||
- **兼容性问题**：可能破坏现有用户代码
|
||
|
||
**无交互模式**（自动处理）：
|
||
|
||
| 场景 | 处理方式 |
|
||
| -------------------------- | ---------------------------------- |
|
||
| 安全红线 | 立即停止，不继续后续 Plan |
|
||
| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan |
|
||
| 多种可行方案 | 选择最保守方案，记录选择理由到报告 |
|
||
| 歧义/风险/决策点 | 记录到报告，继续执行 |
|
||
|
||
**可以不确认**（两种模式通用）：
|
||
|
||
- 明显的 bug 修复
|
||
- 符合现有模式的小改动
|
||
- 测试用例补充
|
||
|
||
## 验证清单
|
||
|
||
每个 Plan 完成后，必须验证：
|
||
|
||
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
|
||
- [ ] 相关测试通过（如有测试且未被豁免）
|
||
- [ ] 换行符正确
|
||
- [ ] 无语法错误
|
||
- [ ] 已通过 `plan_progress.py` 记录 Plan 状态
|
||
|
||
---
|
||
|
||
**最后更新**：{{DATE}}
|