配置AI Agent辅助开发能力

ECShopX已配置AI Agent辅助开发

商派ECShopX开源商城发布后，为了提高开发者的开发效率，商派进行了"系统AI友好性"的能力提升，针对Cursor 编码环境配置了Agent分层角色（规划/编排/执行）与TDD（tdd-guard）钩子，让协作过程有统一节奏：先产出带验收与测试用例的计划，再按红绿重构实现，减少「直接改代码却不可测」的漂移。

基于AI Agent规则与TDD（tdd-guard）的使用说明

1. 配置入口与优先级

2. Agent 体系（「技能」如何落地）

规则将能力拆成多层角色，通过 @角色名 或自然语言关键词切换意图；执行层任务在约定中应通过 mcp_task + subagent_type 委派，避免在当前会话里「一人分饰多角」。

3. 工作流程速览

3.1 规划阶段

1. 1Planner 访谈并研究代码库（通过委派 Explore/Librarian）。
2. 2强制 Advisor 评审后再写计划。
3. 3生成 .tasks/plans/{"{"}name{"}"}.md，其中必须包含 Acceptance & Test Cases：WHEN/THEN 验收场景 + 由场景推导的测试用例（含边界）。
4. 4可选：高精度模式下由 Reviewer 审查计划；[REJECT] 时 Planner 需改计划并再审直至 [OKAY]。
5. 5用户审核并通过计划中的测试用例清单后，才允许进入执行阶段。

3.2 执行阶段

1. 1Orchestrator 读取同一 name 的计划与 TODO，可维护 .tasks/boulder.json 与 .tasks/notepads/{"{"}plan-name{"}"}/（learnings.md、decisions.md、issues.md、problems.md 等，追加写入并带作者与时间戳）。
2. 2通过 mcp_task 按 TODO 委派；委派 Developer时 CONTEXT 须引用计划中 Acceptance & Test Cases 里与本任务相关的条目。
3. 3本项目验证 phpunit 零错误、全通过；必要时结合诊断读取变更文件人工核对。

3.3 委派用的 6-Section Prompt（Orchestrator → 执行层）

计划要求使用统一结构，便于落地与审计：

Developer 的 MUST DO 中应包含：遵循 TDD 与 tdd-guard.mdc；MUST NOT 中应包含：不得用脚本或让用户手动改代码来绕过 tdd-guard。

4. TDD 机制与 tdd-guard

4.1 目标

在 Edit / MultiEdit / Write 等写文件操作前拦截「跳过测试」或「一次改太多」等行为，引导 RED → GREEN → REFACTOR。

4.2 运行方式

• hooks.json 在 preToolUse（匹配Write|Edit|MultiEdit）、beforeSubmitPrompt、sessionStart 时执行：node .cursor/hooks/cursor-adapter.js。
• 适配器将 Cursor 的 payload 规范为 tdd-guard 所需字段，并在可能时把对已存在文件的 Write 转为 Edit/MultiEdit；最终调用 tdd-guard 可执行文件并将结果回传。
• 若返回 block（或 continue: false），适配器以退出码 2 表示拦截。

4.3 被拦截时 Agent 应怎么做

1. 1阅读返回的 reason（含违规说明与建议的下一步）。
2. 2在本会话内按建议继续：例如只加最小实现、先 stub、先建空类再跑测试等。
3. 3禁止用 sed/重定向等脚本批量改受检文件，或让用户手动粘贴代码以绕过拦截。

4.4 Hook 不可用时的自律

若 tdd-guard 未安装、超时或报错：Developer 仍应按同一套 TDD 纪律（一次一个失败测试、最小实现、全绿再重构）工作，只是没有自动拦截。

4.5 Developer 的 TDD 要点

5. 实例：给ECShopX添加"订单备注API"

1）规划（Planner）

• Planner 经 Advisor 审视范围与风险后，生成 .tasks/plans/order-note-api.md，其中 Acceptance & Test Cases 至少包含：

Planner 呈现测试用例清单，等待你确认后再进入执行。

2）可选高精度（Reviewer）

若开启高精度审查，Reviewer 对计划文档做 [OKAY] / [REJECT]；被拒则 Planner 改计划后再审。

3）执行（Orchestrator + Developer）

• 你说「开始执行」后，Orchestrator 读取同一计划中的 TODO，按依赖拆任务，并通过 mcp_task 委派 Developer，prompt 采用 6-Section，且在 CONTEXT 中引用计划里与本任务对应的验收场景与用例 ID。
• Developer 严格 TDD：例如先写一条「越权访问应失败」的测试（RED），再写最小控制器/服务逻辑使该测试通过（GREEN），再补「成功路径」测试并实现，最后在全部绿的前提下做小幅重构（REFACTOR）。
• 若 tdd-guard 拦截某次 Edit/Write，根据返回的 reason 在本会话内缩小改动（如只补一个方法、先通过当前单测），不要用脚本或让用户手动粘贴绕过。

4）收尾

运行 phpunit 全绿；Orchestrator/Developer 视需要在 .tasks/notepads/order-note-api/ 追加决策与问题记录。

6. 快速对照：你要做什么时该怎么做