super-engineer-workflow 0.1.0

package/docs//344/270/255/346/226/207/344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -0,0 +1,707 @@
+# super-engineer 中文使用手册
+
+这份手册只做一件事：用一个真实需求，说明工作流怎么开始、怎么推进、用户该怎么向 AI 发指令。
+
+示例需求：
+
+> 经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
+
+这份手册按下面顺序组织：
+
+1. 工作空间结构
+2. `todo` 模式配置结构
+3. `todo` 模式 `auto` 怎么使用
+4. `todo` 模式 `manual` 怎么使用
+5. `openspec` 模式 `auto` 怎么使用
+6. `openspec` 模式 `manual` 怎么使用
+
+## 1. 前置条件
+
+需要满足：
+
+- 本地已经安装好 `super-engineer-workflow`
+- 目标代码仓库已经在本地
+- 本地可用 `python3`
+- 已存在 `~/.super-engineer/skill-config.yml`
+
+如果 `~/.super-engineer/skill-config.yml` 不存在，第一次初始化时会自动生成模板，并暂停流程，等你补全。
+
+## 2. 真实例子
+
+整个手册都使用同一个需求：
+
+> 经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
+
+把它拆成可交付目标，就是：
+
+- 修改 `item-user-service`
+- 用户列表接口支持手机号精确筛选
+- `phone` 为空时保持原有查询行为
+- 补齐 controller 测试
+- 补齐 service 测试
+
+## 3. 工作空间结构
+
+### 3.1 `todo` 模式
+
+```text
+your-workspace/
+├── workspace.yml
+├── todo.md
+└── output/
+
+your-project/
+├── docs/
+├── item-user-service/
+└── ...
+```
+
+这里的职责分工是：
+
+- `workspace.yml`：声明当前工作流配置
+- `todo.md`：交付阶段的真实输入
+- `output/`：输出给人看的报告
+- `your-project/`：实际代码目录
+
+### 3.2 `openspec` 模式
+
+```text
+your-workspace/
+├── workspace.yml
+└── output/
+
+your-spec-repo/
+└── openspec/
+    ├── specs/
+    └── changes/
+        └── add-user-phone-filter/
+            ├── proposal.md
+            ├── design.md
+            ├── tasks.md
+            └── specs/
+
+your-project/
+├── docs/
+├── item-user-service/
+└── ...
+```
+
+这里的职责分工是：
+
+- OpenSpec change：规格阶段输入
+- 桥接 todo：桥接后的交付输入
+- `your-project/`：实际代码目录
+
+桥接 todo 的实际文件路径由 `workspace.yml.todo_file` 决定。为了兼容既有 skill 习惯，推荐在需求目录中继续使用 `todo.md`。
+
+## 4. `todo` 模式配置结构
+
+### 4.1 `workspace.yml`
+
+`manual` 版本：
+
+```yaml
+version: 1
+mode: manual
+workflow_source: todo
+demand_file: ${demand_name}/需求.md
+todo_file: ${demand_name}/todo.md
+reference_files:
+  - ../docs/需求分析与实现指南.md
+code_path: ../../../code
+output_dir: ${demand_name}/output
+```
+
+`auto` 版本只改一处：
+
+```yaml
+mode: auto
+```
+
+如果同一个工作空间经常切换需求，可以用 `vars` 统一维护需求名：
+
+```yaml
+vars:
+  demand_name: 7-deamnd-addition-rate
+```
+
+然后路径里使用 `${demand_name}` 或 `${vars.demand_name}`。相对路径会按当前打开的工作空间根目录解析。
+OpenSpec change 名称不会从 `demand_name` 推导，必须在 `/se:propose <change-name>` 中显式指定。
+
+如果当前项目不是 Java，或者自动识别出的验证命令不符合团队要求，可以在 `workspace.yml` 中显式配置验证命令：
+
+```yaml
+verify_commands:
+  default: pnpm test && pnpm build
+  frontend-app: pnpm test && pnpm build
+  user-service: go test ./...
+  python-service: python -m pytest
+```
+
+key 可以写 `default`、目标仓库目录名或目标仓库绝对路径。工作流会优先使用这个配置，而不是自动推断命令。
+
+### 4.2 `todo.md`
+
+```md
+# 限制条件
+- 修改的服务是 item-user-service
+- 需要兼容旧的查询参数行为
+
+# 待办事项
+
+## 用户列表
+- [ ] 用户列表接口增加手机号精确筛选
+1. 仅支持管理员角色使用
+2. 前端为空时不传该参数
+3. 后端需要兼容旧参数
+
+## 测试
+- [ ] 补齐 controller 和 service 层测试
+```
+
+## 5. `todo` 模式 `auto` 怎么使用
+
+`todo + auto` 的含义是：
+
+- 用户已经准备好 `todo.md`
+- AI 不在计划、实现、审查之间反复停下来
+- 只要没有硬阻塞，就连续推进到验证阶段
+
+推荐起手提示词：
+
+```text
+/se:apply
+使用当前工作空间。
+需求是：经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
+当前模式是 todo + auto。
+如果 workspace 未初始化，先初始化。
+如果没有硬阻塞，自动推进到实现、自查、审查和验证。
+最后只向我汇报：
+1. 改了哪些仓库和文件
+2. review gate 结果
+3. verify 结果
+4. residual risks
+```
+
+更稳一点的两步法：
+
+第一步先看计划：
+
+```text
+/se:plan
+使用当前工作空间。
+基于 todo.md 生成本轮计划。
+先不要改代码，只总结目标仓库、影响范围、验收标准和主要风险。
+```
+
+第二步确认后再直接推进：
+
+```text
+/se:apply
+继续当前工作空间。
+按当前计划自动推进到实现、自查、审查和验证。
+如果没有硬阻塞，不要中途停下。
+```
+
+适用场景：
+
+- 需求局部
+- 目标服务明确
+- 用户更关心交付速度
+
+## 6. `todo` 模式 `manual` 怎么使用
+
+`todo + manual` 的含义是：
+
+- 用户已经准备好 `todo.md`
+- AI 每到关键门禁先停下来汇报
+- 适合高风险修改或你想逐步确认的场景
+
+推荐操作顺序：
+
+### 第一步：初始化并生成计划
+
+```text
+/se:plan
+使用当前工作空间。
+当前模式是 todo + manual。
+先完成初始化和计划生成，不要开始改代码。
+告诉我目标仓库、影响范围、验收标准和主要风险。
+```
+
+### 第二步：确认后开始实现
+
+```text
+/se:apply
+继续当前工作空间。
+当前计划已确认，可以开始实现。
+实现完成后先停在自查结果，不要直接进入后续阶段。
+```
+
+### 第三步：让 AI 做代码审查
+
+```text
+/se:review
+继续当前工作空间。
+对当前改动做代码审查。
+只告诉我 gate 结果、blocking findings、warning findings 和测试覆盖风险。
+```
+
+### 第四步：让 AI 做验证
+
+```text
+/se:verify
+继续当前工作空间。
+执行验证，并告诉我 workflow 是 done 还是 blocked。
+```
+
+适用场景：
+
+- 涉及共享模块
+- 需要逐步确认修改范围
+- 你希望在 review 前先人工看一遍
+
+## 7. `openspec` 模式 `auto` 怎么使用
+
+`openspec + auto` 应该分成三个阶段理解：
+
+1. 规格阶段
+2. 交付阶段
+3. 归档阶段
+
+这里最重要的一点是：  
+不要直接从自动实现开始。应该先从 OpenSpec change 开始，产出 `tasks.md`，再桥接成 `workspace.yml.todo_file` 指向的 `todo.md`，审核通过后再进入自动交付。
+
+### 7.1 `workspace.yml`
+
+```yaml
+version: 1
+mode: auto
+workflow_source: openspec
+vars:
+  demand_name: add-user-phone-filter
+demand_file: superengineer/${demand_name}/需求.md
+todo_file: superengineer/${demand_name}/todo.md
+reference_files: []
+code_path: ../../../code
+output_dir: superengineer/${demand_name}/output
+openspec:
+  changes_dir: ../openspec/changes
+```
+
+`demand_file` 也可以直接配置飞书/Lark 云文档 URL。云文档由官方 `lark-cli` 读取并转换为 Markdown；首次使用前需要安装并授权：
+
+```bash
+npx @larksuite/cli@latest install
+lark-cli config init --new
+lark-cli auth login --recommend
+```
+
+### 7.2 OpenSpec change 示例
+
+`proposal.md`
+
+```md
+# Proposal
+
+## Background
+客服需要通过手机号精确定位经销商用户。
+
+## Scope
+- 经销商用户列表接口
+- controller / service / query 链路
+- 对应测试
+```
+
+`design.md`
+
+```md
+# Design
+
+## Compatibility
+- 当 `phone` 为空时，保持旧查询行为不变
+- 不涉及数据库 schema 变更
+```
+
+`tasks.md`
+
+```md
+# Tasks
+
+## API
+- [ ] 为经销商用户列表接口增加手机号精确筛选
+- [ ] 当 phone 为空时保持旧行为
+
+## Testing
+- [ ] 补充 controller 测试
+- [ ] 补充 service 测试
+```
+
+### 7.3 阶段一：先产出 OpenSpec change
+
+```text
+/se:propose add-user-phone-filter
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+```
+
+### 7.4 阶段二：桥接为交付 todo
+
+```text
+/se:bridge
+针对当前 OpenSpec change 生成桥接 todo。
+请把 tasks.md 转成交付阶段可执行的 todo，并总结：
+1. 哪些任务会进入本轮交付
+2. 哪些约束需要在实现时严格遵守
+3. 有没有描述不清的地方
+```
+
+### 7.5 阶段三：审核桥接 todo
+
+这一步是人审，不建议跳过。
+
+如果审核时发现桥接 todo 和实际业务有偏差，不要进入 `/se:apply`。先判断偏差来自哪里。
+
+如果只是桥接表达不准确，例如 `tasks.md` 没问题，但 `todo.md` 拆分不合理、遗漏实现约束或描述不清，可以先修正 `todo.md`，然后让 AI 重新整理：
+
+```text
+/se:bridge
+当前桥接 todo 和业务理解有偏差，我已补充或修正。
+请基于当前 OpenSpec change 和 todo.md 重新整理交付 todo，并列出变化点。
+```
+
+如果 OpenSpec change 本身就有偏差，例如 `proposal.md`、`design.md` 或 `tasks.md` 对需求理解错误、遗漏业务规则，应回到规格阶段修正当前 change：
+
+```text
+/se:propose add-user-phone-filter
+当前 OpenSpec change 对业务理解有偏差：
+补充说明：这里写清楚偏差和正确业务规则。
+
+请修正当前 change，不要创建新的 change。
+先不要改代码。
+```
+
+然后重新桥接：
+
+```text
+/se:bridge
+针对修正后的 OpenSpec change 重新生成桥接 todo，并列出变化点和待审核项。
+```
+
+如果原始需求本身不完整，先补充 `demand_file` 或在提示词中说明补充信息，再重新执行 `/se:propose` 修正当前 change。
+
+判断规则：
+
+```text
+todo 偏差来自交付拆解 -> 重新 bridge
+todo 偏差来自规格理解 -> 重新 propose
+todo 偏差来自需求缺失 -> 补需求后重新 propose
+```
+
+### 7.6 阶段四：启动自动交付
+
+```text
+/se:apply
+使用当前工作空间。
+当前模式是 openspec + auto。
+当前桥接 todo 已审核通过。
+如果没有硬阻塞，自动推进到实现、自查、审查和验证。
+verify 通过后继续检查归档条件；如果结果为 safe_merge，状态进入 archive_ready，下一步再执行 /se:archive。
+```
+
+适用场景：
+
+- 需求已经先在 OpenSpec 里沉淀
+- 你希望交付前先审核执行清单
+- 你希望 verify 后自动进入归档检查
+
+## 8. `openspec` 模式 `manual` 怎么使用
+
+`openspec + manual` 和 `openspec + auto` 的差异不在前半段。  
+两者都应该先走：
+
+1. `/se:propose <change-name>`
+2. `/se:bridge`
+3. 人工审核桥接 todo
+4. `/se:apply`
+
+差异在交付阶段：
+
+- `auto`：审核通过后连续推进
+- `manual`：审核通过后仍按计划、实现、审查、验证分段停留
+
+### 第一步：规格阶段
+
+```text
+/se:propose add-user-phone-filter
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+```
+
+### 第二步：桥接阶段
+
+```text
+/se:bridge
+针对当前 OpenSpec change 生成桥接 todo，并列出待审核项。
+```
+
+### 第四步：先只生成计划
+
+```text
+/se:plan
+使用当前工作空间。
+当前模式是 openspec + manual。
+当前桥接 todo 已审核通过，基于已审核的桥接 todo 生成计划。
+先不要改代码，只总结目标仓库、影响范围、验收标准和主要风险。
+```
+
+### 第五步：确认后进入实现
+
+```text
+/se:apply
+继续当前工作空间。
+当前计划已确认，可以开始实现。
+实现完成后先停在自查结果。
+```
+
+### 第六步：继续代码审查
+
+```text
+/se:review
+继续当前工作空间。
+对当前改动做审查，并确认 execution-summary 已回写。
+```
+
+### 第七步：继续验证
+
+```text
+/se:verify
+继续当前工作空间。
+执行验证，并告诉我 workflow 是 done 还是 blocked。
+```
+
+### 第八步：检查归档条件
+
+```text
+/se:archive-check
+继续当前工作空间。
+检查当前 OpenSpec change 是否满足归档条件。
+告诉我 archive_ready、merge_mode、blockers 和 spec_conflicts。
+```
+
+### 第九步：确认后归档
+
+```text
+/se:archive
+仅在 archive_ready=true、merge_mode=safe_merge、spec_conflicts 为空时执行归档。
+归档后告诉我同步了哪些 spec，以及 change 被归档到了哪里。
+```
+
+适用场景：
+
+- 变更范围大
+- 需要明确的人工门禁
+- 希望规格、交付、归档三阶段都保留确认点
+
+## 9. 跑完后发现遗漏怎么办
+
+当前工作流不是一次性的。每次 `plan` 会创建一个新的 session，但同一个 session 在完成前可以继续返工。
+
+### 9.1 还没验证通过
+
+如果遗漏是在当前 session 的自查、审查或验证阶段发现的，推荐继续当前 session，不要重新开新计划。
+
+适用情况：
+
+- self-check 发现实现遗漏
+- review 发现 blocking finding
+- verify 失败
+- 你人工检查后发现当前实现不完整
+
+推荐提示词：
+
+```text
+/se:apply
+继续当前工作空间。
+基于当前 session 的 self-check、review 或 verify 结果修复遗漏。
+不要重新生成新计划，除非当前计划确实需要补充。
+修复后重新执行必要的自查、审查和验证。
+```
+
+如果遗漏明确来自 review：
+
+```text
+/se:apply
+继续当前工作空间。
+根据当前 review 的 blocking findings 修复代码。
+修复后重新执行 review 和 verify。
+```
+
+如果遗漏明确来自 verify：
+
+```text
+/se:apply
+继续当前工作空间。
+根据当前 verify 失败原因修复代码。
+修复后重新执行 verify。
+如果修复影响核心实现逻辑，也重新执行 review。
+```
+
+### 9.2 已经验证通过，但还没归档
+
+如果 workflow 已经 `done`，但 OpenSpec change 还没有归档，可以补当前 change，然后重新桥接、审核和交付。
+
+推荐提示词：
+
+```text
+/se:propose add-user-phone-filter
+当前 OpenSpec change 验证通过后发现遗漏：
+手机号筛选需要同时兼容脱敏手机号字段，否则部分历史用户无法被查到。
+请补充当前 OpenSpec change，不要创建新的 change。
+```
+
+然后重新桥接：
+
+```text
+/se:bridge
+针对更新后的 OpenSpec change 重新生成桥接 todo，并列出新增或变化的待审核项。
+```
+
+审核后：
+
+```text
+/se:apply
+我已审核更新后的桥接 todo，可以继续交付遗漏修复。
+继续当前工作空间。
+按已审核的桥接 todo 修复遗漏，并完成自查、审查和验证。
+```
+
+### 9.3 已经归档
+
+如果 OpenSpec change 已经归档，不建议再改旧 change。应该创建 follow-up change 或新一轮 todo。
+
+OpenSpec 模式推荐提示词：
+
+```text
+/se:propose add-user-phone-filter-follow-up
+已归档需求发现后续遗漏：
+手机号筛选需要同时兼容脱敏手机号字段，否则部分历史用户无法被查到。
+请创建一个 follow-up change。
+```
+
+todo 模式推荐提示词：
+
+```text
+/se:plan
+使用当前工作空间。
+基于新增遗漏点创建新一轮交付计划。
+遗漏点是：手机号筛选需要同时兼容脱敏手机号字段，否则部分历史用户无法被查到。
+先不要改代码，只总结影响范围、验收标准和风险。
+```
+
+### 9.4 判断规则
+
+简单判断：
+
+- 还没 `verify done`：继续当前 session 修
+- 已经 `verify done`，但还没归档：补当前 OpenSpec change，再重新 `/se:bridge`，人工审核 todo 后执行 `/se:apply`
+- 已经归档：创建 follow-up change 或新一轮 todo
+- 只是实现 bug，不改变需求：优先继续当前 session，已 done 则新开一轮
+- 改变验收标准或需求范围：新一轮计划，OpenSpec 模式下更新或新建 change
+
+## 10. `/se:*` 命令速查表
+
+这一节用于快速查阅命令顺序。`/se:*` 是发给 AI 的工作流指令，不是 shell 命令。
+
+### 10.1 OpenSpec 模式推荐顺序
+
+```text
+/se:init
+-> /se:propose <change-name>
+-> /se:bridge
+-> 人工审核 todo.md
+-> /se:plan    可选
+-> /se:apply
+-> /se:archive-check
+-> /se:archive 满足 safe_merge 时
+```
+
+| 顺序 | 命令 | 作用 | 完成后允许的下一步 |
+| --- | --- | --- | --- |
+| 1 | `/se:init` | 初始化工作空间，检查配置、目录和输入 | `/se:propose <change-name>` |
+| 2 | `/se:propose <change-name>` | 生成或完善指定 OpenSpec change，只处理规格，不改代码 | `/se:bridge` |
+| 3 | `/se:bridge` | 把 OpenSpec `tasks.md` 桥接成 `todo.md` | 人工审核 todo.md 后 `/se:apply` |
+| 4 | `/se:plan` | 生成交付计划，不改代码 | `/se:apply` |
+| 5 | `/se:apply` | 进入实现、自查、审查、验证 | `/se:archive-check` |
+| 6 | `/se:review` | 单独执行或重跑代码审查 | `/se:verify` 或 `/se:apply` 修复 |
+| 7 | `/se:verify` | 单独执行或重跑验证 | 通过后 `/se:archive-check` |
+| 8 | `/se:archive-check` | 检查是否满足 OpenSpec 归档条件 | 满足 safe_merge 后 `/se:archive` |
+| 9 | `/se:archive` | 执行 OpenSpec 归档 | 结束 |
+| - | `/se:status` | 查看当前工作流状态 | 按状态提示下一步 |
+
+关键门禁：
+
+- `/se:propose` 后不能直接 `/se:apply`
+- `/se:bridge` 后必须先人工审核 todo.md
+- 人工审核 todo.md 后直接用 `/se:apply` 进入交付
+- `/se:apply` 之前必须已经完成 `/se:bridge` 并审核 todo.md
+- `/se:archive` 之前必须先 `/se:archive-check`
+- 飞书通知必须通过 `/se:verify` 的标准模板发送，不能让 AI 手工拼 webhook
+
+OpenSpec 模式下还有脚本状态机：
+
+```text
+.super-engineer/se-state.json
+```
+
+脚本会记录 `phase` 和 `allowed_next`。例如 `/se:propose` 后 `phase=proposed`，只允许 `/se:bridge`；如果此时直接执行 `/se:apply`，脚本会拒绝。
+
+### 10.2 todo 模式推荐顺序
+
+```text
+/se:init
+-> /se:plan
+-> /se:apply
+-> /se:review
+-> /se:verify
+```
+
+| 顺序 | 命令 | 作用 |
+| --- | --- | --- |
+| 1 | `/se:init` | 初始化工作空间，检查 `workspace.yml` 和 `todo.md` |
+| 2 | `/se:plan` | 基于 `todo.md` 生成计划，不改代码 |
+| 3 | `/se:apply` | 按计划实现、自查、审查和验证 |
+| 4 | `/se:review` | 单独执行或重跑审查 |
+| 5 | `/se:verify` | 单独执行或重跑验证 |
+| - | `/se:status` | 查看当前状态 |
+
+`todo + auto` 可以从 `/se:apply` 开始，但前提是 `workspace.yml` 和 `todo.md` 都有效。
+
+### 10.3 最常用的几条命令
+
+如果你不想记全部命令，先记这几条就够了：
+
+- `/se:propose <change-name>`：生成或完善指定 OpenSpec change
+- `/se:bridge`：把 `tasks.md` 转成桥接 todo
+- `/se:plan`：只做计划
+- `/se:apply`：进入交付
+- `/se:archive-check`：检查是否满足归档条件
+- `/se:archive`：执行归档
+
+如果 AI 收到 `/se:*` 后没有进入工作流，而是回复“在吗”“有什么可以帮你”这类普通聊天内容，说明当前模型没有加载 `super-engineer-workflow` skill，或者没有识别 `/se:*` 协议。处理方式：
+
+```text
+请使用 super-engineer-workflow skill 处理下面的 /se:* 工作流命令。
+
+/se:propose demand-addition-rate
+
+使用当前工作空间：
+/Users/muke/Documents/work/desmart/project/ai-workspace
+
+请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+先不要改代码。
+```
+
+如果仍然没有触发，需要确认当前 AI 客户端已经安装并启用了 `super-engineer-workflow` skill。
+
+完整命令说明见：
+
+- [se命令协议.md](/Users/muke/Documents/personal/codex/super-engineer/docs/se命令协议.md)