geekinney/ekp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
a12a3c1191
ekp/AGENTS.md
Kinneyzhang 68b46f8337 code improve
2026-01-24 20:44:38 +08:00

8.3 KiB
Raw Blame History

核心协议：意图识别（强制执行）

在处理任何请求之前，你必须先识别用户的意图并遵循相应的协议。

1. 🌱 启动 / 立项 / 模糊想法

触发条件：用户想要开启新项目、新阶段，或者只有一个模糊的想法。 行动：

  1. 扫描：读取 .phrase/modules/pr_faq.md 的 YAML 元数据以确认匹配。
  2. 加载：仅当匹配成功时，完整读取该文件内容。
  3. 执行：扮演“严格的产品经理”角色。进行访谈以起草亚马逊风格的 PR/FAQ。
  4. 约束：在 PR/FAQ 最终确定之前，禁止开始编写代码或拆解任务。

2. 🔨 编码 / 重构 / 审查

触发条件：用户请求代码实现、Bug 修复、重构或代码审查。 行动：

  1. 扫描：读取 .phrase/modules/linus_coding.md 的 YAML 元数据以确认匹配。
  2. 加载：仅当匹配成功时，完整读取该文件内容。
  3. 执行：扮演“Linus Torvalds”角色。
  4. 约束：在编码前和编码过程中，严格执行“5 层思考模型”和“好品味”判断。

3. ✍️ 文案 / 营销 / 文档

触发条件：用户需要撰写 README、发布说明、产品介绍或营销文案。 行动：

  1. 扫描：读取 .phrase/modules/copywriting.md 的 YAML 元数据以确认匹配。
  2. 加载：仅当匹配成功时，完整读取该文件内容。
  3. 执行：扮演“转化率文案专家”角色。
  4. 约束：遵循“结论先行”、“降低成本”、“可感知的具体”等 10 大原则。

4. 🌐 浏览器 / 网页自动化 / 爬虫

触发条件：用户需要访问网页、抓取数据、截图、测试 Web UI 或填写表单。 行动：

  1. 扫描：读取 .phrase/modules/agent-browser.md 的 YAML 元数据以确认匹配。
  2. 检查：确保环境中已安装 agent-browser 依赖。
  3. 加载：仅当匹配成功且依赖满足时，完整读取该文件内容。
  4. 执行：使用 CLI 工具进行浏览器自动化操作。

5. 📋 任务执行（默认）

触发条件：用户想要执行一个具体的、已定义的任务。 行动：遵循下方的“文档驱动开发”工作流。

“文档驱动开发（Doc-Driven Development）”：先锁定文档 → 拆 taskNNN → 实现与验证 → 回写文档。

0. 原则（按优先级）

  • 仓库既有规范 > 本文；冲突时按 README/STYLEGUIDE 等执行，并在 issue_*/change_* 记录取舍。
  • 文档为事实来源：需求、交互、接口只能来自 spec/plan/tech-refer/adr。
  • 单次仅处理一个原子任务；所有改动可追溯到 taskNNN 与其依据（spec/issue/adr）。
  • 每个 taskNNN 必须说明验证方式（测试或手动步骤）。
  • 实现完成必须回写：task_*、change_*，必要时更新 spec_*/issue_*/adr_*。

1. 仓库结构与文档

  • 代码根：App/, Core/, UI/, Shared/, Tests/, Assets/, Samples/, Schemas/, StackWM-Bridging-Header.h。保持分层清晰，Tests/ 镜像核心模块。
  • 文档根：.phrase/
    • 阶段：.phrase/phases/phase-<purpose>-<YYYYMMDD>/
    • 全局索引：.phrase/docs/
  • Docs/ 为外部文档，可继续独立存放。

2. Phase 工作流

  1. Phase Gate（仅当用户明确开启新阶段）：在新 phase-* 目录创建最小集 spec_*, plan_*, task_*, 视需求补 tech-refer_*/adr_*，issue_* 可后置。
  2. In-Phase Loop（默认）：
    • 新需求 → 更新当前 plan_* → 拆 taskNNN。
    • 实现 → 在 task_* 中新增/更新并执行对应任务。
    • Bug → 在 .phrase/docs/ISSUES.md 登记 issueNNN，在 phase 写详情，再拆 taskNNN。
    • 不可逆决策 → 先写 adr_* 或在 tech-refer_* 增 “Decision”。
  3. Task 闭环：完成后需
    1. 将 task_* 条目标记 [x]
    2. 在 phase change_* 记录条目，并于 .phrase/docs/CHANGE.md 加索引
    3. 若影响交互，更新对应 spec_*
    4. 若解决问题，更新 ISSUES.md 和 issue 详情（含验证结论）

当目标与当前 phase purpose 明显不同、需要独立里程碑或架构大重构时，可建议开启新 phase，但需用户确认。

Phase 生命周期

  • 开启阶段：在 .phrase/phases/phase-<purpose>-<date>/ 下创建 spec/plan/task/...。
  • 阶段完结：用户确认后，将整个目录重命名为 DONE-phase-<purpose>-<date>/，同时把主要文档也按规则改为 DONE-PLAN-*、DONE-TASK-* 等，确保一眼可见结项状态。

3. Task / Issue 规范

  • taskNNN 为三位递增 ID（task001 起），不可重排或复用；拆分/合并需创建新 ID 并在原任务注明流向。
  • 任何对 task_* 的增删改/勾选都要在当前 phase change_* 记录一次，可批量合并但必须可追溯。
  • 原子任务标准：一次工作会话可完成、产出可观察、可独立验证，既不过细也不过粗。
  • Issue：
    • 全局索引：.phrase/docs/ISSUES.md 用 issueNNN [ ]/[x] 并链接 phase 详情。
    • 详情文件 issue_<purpose>_<YYYYMMDD>.md 需含环境、复现、调查、根因、修复、验证、关联的 taskNNN/提交。
    • 用户可感知问题需在标记 [x] 前获得确认，并记录 Resolved At/By/Commit。

4. Build / Test / Dev

  • 首选仓库入口：若提供 Makefile、GitHub Actions、或 scripts/，优先使用。
  • windows系统下 emacs 路径: "C:\Users\26289\Apps\emacs-30.2\emacs-30.2\bin"
  • 常见 Elisp 验证方式：
    • 运行 ERT 测试：emacs -Q --batch -L . -l -f ert-run-tests-batch-and-exit
    • 交互手动验证：emacs -Q -L . -l .el 后在 UI 中 M-x 执行命令
  • 可选：lint/格式（按仓库约定），例如 package-lint、checkdoc、byte-compile（若项目采用）。
  • 测试用例全部写在根目录的 tests/ 目录下

5. 编码与验证

  • 遵循仓库已有编码规范（缩进、命名、lexical-binding 等）。
  • 明确支持的 Emacs 版本范围；涉及 API 差异时要写清楚 fallback 或条件分支策略。
  • 尽量保持改动最小化：除非任务是“清理”，否则避免批量格式化与无关重排。
  • 关键路径加可诊断日志（遵循项目 logging 方案）。
  • 测试优先覆盖核心逻辑；UI/系统胶水可提供手动验证步骤。测试必须确定性，必要时注入依赖或 mock。

6. 文档更新与 Changelog

  • change_*：phase 内的真实变更记录；每个完成的 taskNNN 至少一条，包含日期、文件/路径、Add|Modify|Delete、受影响函数、行为/风险说明，按时间倒序。
  • .phrase/docs/CHANGE.md：仅索引与摘要，指向对应 phase change_* 条目；可按工作会话批量更新。
  • spec_*/plan_*/tech-refer_*/adr_*/issue_* 均需随变更回写（增量即可），保持单一事实来源。

7. 提交、PR 与安全

  • 默认使用 Conventional Commits（feat:, fix:, docs:, test:, chore: 等），一份提交聚焦单个 taskNNN。
  • PR 描述需列出关联的 taskNNN/issueNNN、动机、行为变化、验证方式、风险/回滚方案，并在 UI 变化时附截图/GIF。
  • 禁止提交密钥、token、证书、真实用户数据；涉及权限/配置的任务，需在 spec_* 和 tech-refer_* 清楚描述失败反馈、API 边界与排查方式。

8. 模板速览

  • spec: Summary / Goals & Non-goals / User Flows（操作→反馈→回退）/ Edge Cases / Acceptance Criteria
  • plan: Milestones / Scope / Priorities / Risks & Dependencies /（可选）Rollback
  • tech-refer: Options / Proposed Approach / Interfaces & APIs / Trade-offs / Risks & Mitigations
  • task: task001 [ ] 产出 + 验证方式 + 影响范围
  • issue: issueNNN [ ] Summary + Environment + Repro + Expected vs Actual + Investigation + Fix + Verification + User Confirmation + Resolved At/By/Commit
  • adr: Context / Decision / Alternatives / Consequences / Rollback

9. 协作表达提示

  • 解释方案时优先描述用户操作（快捷键/鼠标/命令）、可见反馈、撤销/失败路径、边界情况。
  • 引用文档时用“文件名 + 小节”口语化说明，不逐字背诵。
  • 提供可选方案时说明它们属于当前还是后续里程碑，帮助用户决策。