| name | plan-init |
| description | 初始化 Agent 框架，完成需求分析和任务分解。当用户说 "/plan-init"、"初始化项目"、"开始新项目"、"创建任务列表"、"设置 Agent"、"初始化任务"、"init"、"初始化" 时触发。这是一个项目初始化 skill，不是创意或功能开发——不需要先 brainstorming。审批后只输出确认，不自动串联任何 skill。 |
Plan Init
完成需求分析、技术决策和任务分解，将技术方案直接写入 .plan/task.md 供审批。本 skill 只负责"想"，审批后输出确认信息并停止，串联逻辑由调用方决定。
核心产物
| 文件 | 用途 | 何时产生 |
|---|
.plan/task.md | 技术方案文档（含完整任务 JSON 数组，审批对象） | 本 skill 执行过程中渐进写入 |
.plan/features.json | 任务单一事实来源 | /plan-write 执行后 |
.plan/dev-YYYY-MM-DD.log | 统一开发日志 | /plan-write 执行后 |
.plan/test-cases.json | 用户提供的独立测试用例 | /plan-write 从 .plan/task.md 提取 |
关键事实：下游 /plan-write 从 .plan/task.md 读取，所以本 skill 必须保证 .plan/task.md 内容完整，含完整 JSON 任务列表。
门控分级
SKILL.md 内出现的标记：
- 🔴 HARD GATE：必须等用户输入，不等不能继续
- 🟡 CHECK：AI 内部自检，不满足则回到前面步骤补充
- 📄 WRITE：向
.plan/task.md 的指定章节写入/更新内容
三档自适应
根据输入清晰度自动选择工作深度：
| 输入 | 模式 | 流程 |
|---|
| 模糊需求（口头描述） | 深度模式 | 需求深挖 → 场景识别 → 代码探索 → 方案构建 → 任务分解 |
| 明确技术文档（task.md 无 JSON） | 标准模式 | 理解确认 → 技术决策 → 任务分解 |
| 已有 JSON 任务列表（task.md 含 JSON） | 极速模式 | 提取 JSON → 确认 → 组装 task.md |
告知用户当前采用的模式及原因，用户可要求切换。
设计原则
- 抗遗忘：通过读取任务日志恢复上下文
- 抗范围蔓延：JSON 定义范围，日志提供详细上下文
- 可演进：AI 可在执行前优化方案
- 精准执行：只改该改的，不碰不该碰的
- 资深开发视角：考虑复用性、扩展性、健壮性
- 架构师视角（深度模式）：深入代码库理解现状后给出专业方案
- 代码驱动（深度模式）：方案基于实际代码探索，而非凭空设计
协议
步骤 1：检查现有文件（所有模式都执行）
执行 mkdir -p .plan 确保目录存在。检查 .plan/features.json 和 .plan/dev-*.log。
.plan/features.json 存在 → 🔴 HARD GATE：
| 选项 | 行为 |
|---|
| 覆盖 | 备份到 .plan/features.backup.{timestamp}.json，创建新文件 |
| 追加 | 向现有数组添加新任务 |
| 合并 | 保留现有，仅添加非重复项 |
| 取消 | 中止初始化 |
.plan/dev-*.log 存在 → 告知用户："发现现有日志，将保留它们。"
步骤 2：获取需求 + 判断模式
读取 .plan/task.md（如存在）。
| task.md 状态 | 后续 |
|---|
| 存在且含完整 JSON 任务列表 | 走 极速模式分支（见 2A） |
| 存在但无 JSON | 走 标准模式：以文档为需求输入 → 跳到步骤 5 |
| 不存在 | 走 询问用户（见 2B） |
2A. 极速模式分支（task.md 已含 JSON）
用户可能是"要沿用这份 task.md"，也可能是"忘了删上次的 task.md，这次想重新分析"。必须先确认。
🔴 HARD GATE：向用户展示并选择：
📄 检测到已有 .plan/task.md，含 [N] 个任务：
• 任务 1: [description 前 60 字符]
• 任务 2: [description 前 60 字符]
...（最多展示 5 条，超出用「...」省略）
请选择处理方式：
① 沿用这份 task.md，进入极速模式
② 当作不存在，重新描述需求（将覆盖现有 task.md）
③ 取消本次初始化
- 用户选 ① → 提取任务 JSON（同步检查
## Test Cases 章节，有则一并提取，保持 task.md 不变）→ 跳到步骤 6
- 用户选 ② → 备份现有 task.md 到
.plan/task.backup.{timestamp}.md，按全新流程处理，走 2B
- 用户选 ③ → 中止 skill
2B. 询问用户目标（task.md 不存在）
🔴 HARD GATE：
请描述你要做的事情：
- 可以直接说需求
- 可以提供需求文档路径（我会读取并分析）
- 可以提供飞书/语雀文档链接
用户回答后判断：
- 含具体改动范围、实现思路、文件路径 → 标准模式 → 跳到步骤 5
- 只有笼统目标、一句话描述 → 深度模式 → 继续步骤 2.5
告知模式：🎯 模式：[深度/标准]，原因：[简述]。用户可要求切换。
步骤 2.5：测试用例检测（条件执行）
检测信号（命中任一即触发）：
- HTTP 方法 + 路径（如
POST /api/orders、curl -X GET）
- 请求/响应 JSON 配对
- 关键词：测试用例、test case、curl、Postman
- 引用测试文件（
.json、.yaml、.postman_collection）
- 用户明确说"用这些数据测试"
未命中 → 跳过此步骤。命中 → 执行以下子步骤。
2.5.1 提取
从用户输入中提取：
- API 调用：method、path、headers、body、预期状态码和响应
- 流程：步骤间依赖（如"先创建再查询"）
- 异常测试：边界条件和错误场景
- 动态值：用
saveAs + {{变量}} 表达
2.5.2 推断 serviceConfig
从项目代码推断：
- 用户给了启动命令/端口 → 直接使用
- 否则
framework 设为 "auto"（backend-test 运行时自动检测）
2.5.3 向用户确认
🔴 HARD GATE：
📋 检测到测试用例，提取结果：
测试套件 1: [套件名] (顺序/并行执行)
TC-1: POST /api/orders → 期望 200, body 含 orderId
TC-2: GET /api/orders/{id} → 期望 200 (依赖 TC-1)
TC-3: POST /api/orders (无效数据) → 期望 400
服务配置: framework=auto（执行时自动检测）
变量: token=test-token-12345
是否正确？需要添加/修改/删除测试用例吗？
确认后 📄 WRITE → .plan/task.md 的 ## Test Cases 章节（JSON 格式）：
{
"metadata": { "createdAt": "ISO 时间戳", "source": "plan-init", "description": "..." },
"serviceConfig": {
"app": "应用名（可选）",
"appPath": "应用路径（可选）",
"framework": "auto",
"startCommand": null,
"port": null,
"healthCheck": null,
"envVars": {},
"setupCommands": []
},
"testSuites": [
{
"id": "suite-1",
"name": "套件名称",
"sequential": true,
"tests": [
{
"id": "tc-1",
"type": "api",
"request": { "method": "POST", "path": "/api/orders", "headers": {}, "body": {} },
"expected": { "status": 200, "bodyContains": ["orderId"] },
"saveAs": { "orderId": "$.orderId" }
},
{
"id": "tc-2",
"type": "api",
"dependsOn": "tc-1",
"request": { "method": "GET", "path": "/api/orders/{{orderId}}" },
"expected": { "status": 200 }
}
]
}
],
"variables": {}
}
test-cases.json 关键字段说明见 references/compatibility.md。
步骤 3：需求深挖 + 代码探索（仅深度模式）
3.1 场景识别
识别需求所属场景（五选一），告知用户：
🎯 场景识别：[新功能 / 性能优化 / 线上问题修复 / 结构优化 / 中间件创建]
理由：[简述]
不确定时列出候选让用户选。
五大场景的关注点：
| 场景 | 核心关注点 | 探索重点 |
|---|
| 新功能开发 | 在哪加？怎么加？影响什么？ | 相关模块结构、现有抽象、扩展点 |
| 性能/逻辑优化 | 瓶颈在哪？怎么改？副作用？ | 热点代码路径、调用链、数据流 |
| 线上问题修复 | 根因是什么？修复方案？防复发？ | 问题代码、上下游依赖、异常链 |
| 项目结构优化 | 当前问题？目标结构？迁移路径？ | 模块划分、依赖关系、分层架构 |
| 中间件/工具创建 | 解决什么问题？边界？API 设计？ | 现有工具类、使用场景、接口契约 |
3.2 理解确认
🔴 HARD GATE：
📋 我的理解：
- 要做什么：[复述核心目标]
- 核心诉求：[用户最关心的点]
- 预期产出：[最终交付物]
❓ 不确定的地方：[列出理解模糊的点，主动追问]
请确认是否正确，或指出理解偏差。
3.3 场景提问
根据场景挑选 3-5 个对方案有实质影响的问题，跳过用户已明确回答的问题。
| 场景 | 必问（直接影响方案方向） | 按需（视情况补充） |
|---|
| 新功能开发 | ① 目标用户角色和核心使用场景？② 数据从哪来、到哪去、关键字段？③ 项目中有类似功能可参考吗？④ 与现有模块的交互边界？ | ⑤ 并发/性能有特殊要求吗？⑥ 需要向后兼容已有接口吗？⑦ 错误/异常怎么处理？ |
| 性能/逻辑优化 | ① 当前性能数据（QPS/耗时/内存）？瓶颈表现？② 目标性能指标？③ 可接受的改动范围？④ 需要降级/兜底吗？ | ⑤ 历史优化尝试？⑥ 读写比例？⑦ 缓存策略偏好？ |
| 线上问题修复 | ① 复现条件？② 影响范围和紧急程度？③ 临时方案还是直接根治？④ 回归测试怎么做？ | ⑤ 上下游影响？⑥ 现有日志能定位到哪？⑦ 历史类似问题？ |
| 项目结构优化 | ① 当前结构最痛的点？② 目标架构愿景？③ 能否分阶段迁移？④ 兼容性约束？ | ⑤ 影响团队协作吗？⑥ 构建/部署流程变吗？⑦ 保留旧路径过渡？ |
| 中间件/工具创建 | ① 核心问题？② 使用者和使用场景？③ API 风格偏好（Builder/链式/函数式）？④ 有参考实现吗？ | ⑤ 扩展点预留？⑥ 错误处理和日志约定？⑦ 需要配套文档？ |
🔴 HARD GATE：等待用户回答。
3.4 完备性检查
🟡 CHECK：
通用维度（必查）：
- □ 核心目标：一句话能说清楚
- □ 成功标准：怎样算"做完了"
- □ 改动边界：改什么、不改什么
- □ 验证方式：怎么验证做对了
场景专属维度：
- [新功能] □ 数据流向 □ 用户交互流程 □ 异常场景
- [优化] □ 性能基线 □ 目标指标 □ 可接受副作用
- [修复] □ 复现路径 □ 紧急度 □ 回归范围
- [重构] □ 目标结构 □ 迁移约束 □ 兼容性
- [中间件] □ API 设计 □ 使用场景 □ 扩展性
未覆盖且对方案有影响 → 回到 3.3 补问。
📄 WRITE → .plan/task.md 的 ## 背景 和 ## 目标 章节。
3.5 代码探索
根据场景做针对性探索。
通用动作：项目结构概览、相关模块阅读、依赖关系梳理、现有模式和约定识别。
按场景的专项：
| 场景 | 专项探索 |
|---|
| 新功能开发 | 扩展点、相似功能实现、可复用基础设施 |
| 性能优化 | 热点路径、调用链、潜在瓶颈 |
| 线上问题 | 问题代码路径、异常处理链、边界条件 |
| 结构优化 | 模块依赖图、循环依赖、不合理耦合 |
| 中间件创建 | 现有工具类、潜在使用场景、API 风格 |
探索产出：
🔍 代码探索发现：
- 项目技术栈：[语言/框架/构建工具]
- 相关模块：[关键文件和模块]
- 现有模式：[项目约定]
- 可复用资源：[现有工具类/基础设施/抽象层]
- 关键代码路径：[核心调用链和数据流]
- 潜在风险：[可能影响方案的因素]
🔴 HARD GATE：以下情况需暂停回到需求层面：
- 发现与用户描述不一致
- 发现用户未提及但会受影响的模块
- 发现需求中隐含的技术约束
- 发现多种实现路径，需要用户提供业务优先级
📄 WRITE → .plan/task.md 的 ## 现状分析 章节（含「关键代码路径」和「现有抽象层」子节）。
🔴 HARD GATE：等待用户确认代码探索发现无误。
步骤 4：协作式方案构建（仅深度模式）
4.1 方案概述
📐 方案概述：
- 整体思路：[一句话描述方案核心]
- 改动范围：[涉及哪些模块/文件]
- 不改什么：[明确排除项]
4.2 技术决策点
| 情况 | 处理方式 |
|---|
| 代码库中已有明确约定 | 遵循现有约定，告知用户 |
| 用户指定了方案 | 直接采用，无需讨论 |
| 有多个可选方案 | 列出选项 + ⭐推荐 + 理由 |
🔴 HARD GATE：用户确认技术决策。
📄 WRITE → .plan/task.md 的 ## 技术方案 章节（含「整体思路」「数据流图」「接口设计」「技术决策」「改动范围」子节）。
4.3 任务拆解预览
拆解为可执行任务。字段定义完整列表见 references/task-schema.md，这里只用简化摘要向用户展示：
📝 任务拆解：
任务 1: [任务标题] [domain: backend] [complexity: small]
- 做什么 / 为什么 / 改哪里 / 怎么改 / 参考实现 / 验收标准 / 依赖
dependsOn 核心原则：只有编译级依赖（import/引用对方新增的类、方法、接口）才设 dependsOn。运行时依赖（HTTP/RPC、不同 domain）不设，用 apiContracts 约定契约即可。详见 references/task-schema.md。
🔴 HARD GATE：用户确认任务拆解合理。
📄 WRITE → .plan/task.md 的 ## 任务列表 章节（完整 JSON 数组）。
→ 继续到步骤 6。
步骤 5：标准模式需求澄清 + 任务分解
5.1 理解确认
🔴 HARD GATE：
📋 我的理解：
- 要做什么：[复述]
- 要改什么：[精确到类/方法]
- 不改什么：[明确排除]
- 边界条件：[特殊情况处理]
❓ 不确定的地方：[主动追问]
5.2 需求澄清（资深开发视角）
| 类别 | 追问示例 |
|---|
| 复用性 | 有没有现成的原子能力/工具类可复用？ |
| 影响范围 | 这个改动会影响哪些模块？上下游依赖？ |
| 边界 | 只改 A 还是 A 和 B 都改？ |
| 兼容性 | 需要向后兼容吗？老接口怎么处理？ |
| 异常处理 | 失败场景怎么处理？ |
| 性能考量 | 性能要求？是否需要缓存？ |
| 测试策略 | 怎么验证改对了？ |
🔴 HARD GATE：关键问题未澄清前，不得开始任务分解。
5.3 技术实现决策点识别
在分解任务前识别实现时必然要确定的技术问题。
| 情况 | 处理方式 |
|---|
| 用户指定了参考方法/工具 | 按参考方法处理，无需询问 |
| 用户未指定 | 列出选项 + ⭐推荐 + 理由 |
识别方法：对每个任务问自己"写到这行代码时，我必须知道什么才能继续？"
🔴 HARD GATE：未指定参考方法时需用户确认技术决策。
5.4 提取参考资源和数据样例
从用户需求中识别：
- 参考方法/工具 →
references 字段
- 数据样例 →
dataSamples 字段
- 文档链接 →
references 字段
用户提供的参考和数据样例是硬约束，不可忽略或自行替代。
5.5 任务分解
按 references/task-schema.md 的 schema 生成任务 JSON 数组。
字段速查（完整定义见 task-schema.md）：
| 字段 | 说明 |
|---|
id | 字符串序号 "1" |
domain | backend/frontend（全栈项目必填） |
app / appPath | 多应用项目必填 |
dependsOn | 只设编译级依赖；跨应用用 app:id 格式 |
complexity | trivial/small/medium/large |
category | core/ui/feature/optimization/bugfix/refactor/middleware |
implementationGuide | 深度模式必填，标准模式可选 |
apiContracts | 涉及接口对接时必填 |
references / dataSamples | 硬约束 |
步骤 6：组装 .plan/task.md + 请求用户审批
所有模式汇合到这一步，不同模式在此做的工作不同：
| 模式 | 这一步的工作 |
|---|
| 深度模式 | 前面已渐进写入 .plan/task.md，这里只需补 ## 风险与注意事项 + 完整性自检 |
| 标准模式 | 一次性把「需求理解 + 技术决策 + 任务 JSON」写入 .plan/task.md，骨架遵循 references/task-template.md |
| 极速模式 | .plan/task.md 已是用户提供的内容，无需重写；若有 2.5 新增的 Test Cases，追加到 ## Test Cases 章节即可 |
🟡 CHECK 清单：
应用覆盖性检查（多应用/全栈项目必做）：
🔍 应用覆盖性检查：
需求涉及的应用：[列出需求中明确提到的所有应用]
任务列表覆盖的应用：[列出任务中所有 app 值]
未覆盖的应用：[列出差异] ← 需要补充任务
常见遗漏：
- 需求提到前端页面修改，但只分解了后端任务
- 需求涉及 share 包（公共接口定义），但只关注了业务服务
- 需求提到多个微服务，但只分解了部分任务
自检通过后，向用户输出审批请求：
✅ 技术方案已写入 .plan/task.md，含 [N] 个任务。
任务摘要：
• 任务 1: [description 前 60 字符] [domain] [complexity]
• 任务 2: [description 前 60 字符] [domain] [complexity]
...（最多展示 8 条，超出用「...还有 X 个任务」省略）
请审阅 .plan/task.md 后回复：
✓ 确认 / 通过 / OK → 进入下一步
✗ 调整：[说明改动点] → 我会更新方案后再次请你审阅
🔴 HARD GATE：等待用户审批。未收到明确确认前不得进入步骤 7。
步骤 7：审批后输出
用户审批通过后，.plan/task.md 已是最终方案，无需额外归档。
输出确认信息（根据是否含测试用例选择模板）：
无测试用例：
✅ 计划已审批！
已创建:
• .plan/task.md - 技术方案文档（含 [N] 个任务定义）
---
⛔ 任务到此结束。请选择下一步执行方式：
• 运行 /backend-single — 精简版编排（推荐）
• 运行 /backend-team — 完整团队编排
• 运行 /plan-write + /plan-next — 手动逐步执行
含测试用例：在上面基础上最后追加一行：
• 开发完成后运行 /backend-test 执行测试验证（含用户测试用例）
HARD STOP：输出上述内容后立即停止，不得调用任何其他 Skill、不得运行 Bash、不得读文件、不得输出额外内容。等待用户下一条消息。
特殊情况处理
用户提供需求文档
MD 文件路径、飞书链接、语雀链接：读取内容 → 提取要点 → 按正常流程进入理解确认。
用户要求写入飞书/语雀
在步骤 7 额外用对应 MCP 工具创建远程文档并写入。本地 .plan/task.md 仍作为权威来源。
需求变更
任何步骤中用户提出变更 → 确认变更 → 评估影响 → 从受影响步骤重新开始 → 更新 .plan/task.md 对应章节。
后续修改同步
初始化后若用户要求修改任务（增删改），必须同步更新 .plan/features.json：
| 操作 | 处理方式 |
|---|
| 新增任务 | 追加到数组末尾，分配新 ID |
| 修改任务 | 更新对应任务的字段 |
| 删除任务 | 从数组中移除 |
| 重排顺序 | 更新顺序和 ID |
⚠️ .plan/features.json 是任务的单一事实来源，任何修改必须立即同步到文件。
附录
文件冲突处理全景
| 文件 | 何时检查 | 冲突处理 |
|---|
.plan/features.json | 步骤 1（所有模式） | 覆盖（备份）/ 追加 / 合并 / 取消 |
.plan/dev-*.log | 步骤 1（所有模式） | 告知用户保留，不询问 |
.plan/task.md | 步骤 2A（极速模式分支） | 沿用 / 当作不存在（备份后覆盖）/ 取消 |
章节映射表（.plan/task.md 写入点）
| 步骤 | 写入/更新的章节 |
|---|
| 3.4 需求深挖完成 | ## 背景、## 目标 |
| 3.5 代码探索完成 | ## 现状分析（含「关键代码路径」「现有抽象层」子节） |
| 4.2 技术决策 | ## 技术方案（含「整体思路」「数据流图」「接口设计」「技术决策」「改动范围」） |
| 4.3 任务拆解 | ## 任务列表（JSON 数组） |
| 6 完善 | ## 风险与注意事项 |
| 2.5 测试用例确认 | ## Test Cases（JSON） |
骨架格式见 references/task-template.md。
与 /plan-write 的衔接
.plan/task.md 的 ## 任务列表 章节采用与 .plan/features.json 兼容的 JSON 格式。/plan-write 从 .plan/task.md 读取并提取该章节写入 .plan/features.json。字段处理规则详见 references/compatibility.md。
