super-engineer-workflow 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.7
+
+- 拆分 `/se:*` 协议到 `references/commands/*`，删除旧单体协议入口，AI 按命令读取最小协议上下文，降低固定 token 消耗。
+- 增加 `route-check` JSON 预检入口，统一返回命令、阶段、允许状态和阻塞原因。
+- OpenSpec bridge 记录 `tasks.md` hash；后续 plan/apply 发现 tasks 变化会拒绝继续并要求重新 bridge。
+- 增加 `discovery-summary.json`，plan 阶段优先读取轻量定位摘要，进一步减少完整 discovery 上下文读取。
+- `route-se` 增加 `--json` 摘要输出，并增加跨进程 workflow lock，降低并发或重复 `/se:apply` 的 session 风险。
+- OpenSpec 回写增加 `openspec_hashes` 和独立 `task-mapping.json`，archive-check 会检测 proposal/design/tasks/specs 的 hash 漂移。
+- 增强 `se doctor --fix`，可同步 skill 并补齐多平台命令模板。
+- 增加 `se commands install --target claude|codex|cursor|trae|kimi|all`，补齐主流 AI 编码工具快捷命令模板安装入口。
+- 初始化完成提示改为推荐流程，明确 propose -> bridge -> 审核 todo -> apply。
+- 新增跨平台支持矩阵文档，明确 macOS/Linux/Windows Git Bash/PowerShell 支持等级。
+
 ## 0.1.6
 
 - 修复计划生成失败或中断后重复 `/se:apply` 会创建多个空 session/output 目录的问题。

package/README.md

@@ -59,6 +59,9 @@
 
 OpenSpec 模式下，脚本会维护 `.super-engineer/se-state.json`。
 `/se:propose` 后只允许 `/se:bridge`，`/se:bridge` 后才允许审核后 `/se:apply`，非法跨阶段命令会被脚本拒绝。
+桥接时会记录 `tasks.md` hash；如果后续 OpenSpec tasks 发生变化，`/se:plan` 和 `/se:apply` 会要求重新 `/se:bridge`，避免规格和交付 todo 不一致。
+
+为降低 token 消耗，`/se:*` 协议已按命令拆分到 `super-engineer-workflow/references/commands/`。AI 收到某个命令时只读取公共协议和对应命令文件。
 
 标准工作流产物由脚本写入，AI 不应手工伪造 `.super-engineer` 状态文件、`verify.json`、`notification.json` 或 output 下的标准报告。飞书通知只以 `notification.json` 中由 `run-workflow.py verify` 生成的记录为准。
 
@@ -111,6 +114,8 @@ se init
 ```bash
 se init      # 交互式安装 skill 并初始化工作区
 se doctor    # 检查本机环境和 workspace.yml
+se doctor --fix # 同步 skill 并补齐工作区快捷命令
+se commands install --target all # 安装 Claude/Codex/Cursor/Trae/Kimi 快捷命令模板
 se templates # 查看内置 workspace.yml 模板
 se install   # 安装 skill 到 Codex / Claude
 se sync      # 强制同步最新 skill 到 Codex / Claude
@@ -127,6 +132,7 @@ se template copy openspec-auto --workspace /path/to/ai-workspace --demand-name 1
 ```
 
 模板说明见 [docs/模板使用指南.md](/Users/muke/Documents/personal/codex/super-engineer/docs/模板使用指南.md)。
+跨平台支持说明见 [docs/跨平台支持矩阵.md](/Users/muke/Documents/personal/codex/super-engineer/docs/跨平台支持矩阵.md)。
 
 本地源码开发时，也可以直接使用引导脚本。默认是一步一步的交互式向导：
 
@@ -161,34 +167,24 @@ npm 包入口由 `package.json` 的 `bin` 字段提供，`super-engineer` 和 `s
 
 ```text
 /se:apply
-使用当前工作空间。
-需求是：经销商用户列表接口增加手机号精确筛选，要求兼容旧查询行为，并补齐 controller / service 层测试。
-当前模式是 todo + auto。
-如果 workspace 未初始化，先初始化；如果没有硬阻塞，直接推进到实现、自查、审查和验证。
 ```
 
 `openspec` 模式常见起点：
 
 ```text
 /se:propose add-phone-filter
-请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
 ```
 
 然后：
 
 ```text
 /se:bridge
-针对当前 OpenSpec change 生成交付阶段的桥接 todo，并总结待审核项。
 ```
 
 人工确认后：
 
 ```text
 /se:apply
-使用当前工作空间，当前模式是 openspec + auto。
-我已审核当前桥接 todo，可以进入交付阶段。
-如果没有硬阻塞，自动推进到 verify；verify 通过后继续检查归档条件。
-如果结果为 safe_merge，下一步再执行 /se:archive。
 ```
 
 ## 工作空间配置

package/docs/se/345/221/275/344/273/244/345/215/217/350/256/256.md

@@ -1,335 +1,80 @@
 # `se` 命令协议
 
-`se` 是 `super-engineer` 的专属命令前缀。
+`/se:*` 是用户发给 AI 的工作流指令，不是 shell 命令，也不是 OpenSpec `/opsx:*`。
 
-它的定位不是 shell 命令，而是用户发给 AI 的工作流指令。  
-AI 收到这些指令后，再根据当前工作空间、当前模式和当前阶段，调用内部 workflow。
+用户只需要输入命令；AI 会根据当前 `workspace.yml`、状态机和 skill 协议调用底层脚本。
 
-## 1. 设计原则
+## 命令顺序
 
-- 不复用 OpenSpec 官方 `/opsx:*`
-- `se` 只表达 `super-engineer` 的工作流意图
-- 用户只面向阶段说话，不需要关心底层脚本
-- `openspec` 模式下，桥接 todo 是桥接产物，不是规格源头
-- 桥接 todo 的实际路径由 `workspace.yml.todo_file` 决定，推荐继续使用 `todo.md`
-- OpenSpec change 名称必须在 `/se:propose <change-name>` 中显式指定，AI 不得根据需求标题或 `vars.demand_name` 自行推导
-
-## 2. 阶段模型
-
-推荐把整个流程分成三段：
-
-1. 规格阶段
-2. 交付阶段
-3. 归档阶段
-
-典型状态流转：
-
-```text
-draft
--> proposed
--> bridged
--> planned
--> implementing
--> self_checked
--> reviewed
--> verified
--> archive_ready
--> archived
-```
-
-如果出现阻塞，则进入：
+### todo 模式
 
 ```text
-blocked
+/se:init
+-> /se:plan 或 /se:apply
+-> /se:review
+-> /se:verify
 ```
 
-实际状态由 `<workspace>/.super-engineer/se-state.json` 维护，脚本会根据 `allowed_next` 拒绝非法跨阶段命令。
-
-## 3. 命令列表
-
-### `/se:init`
-
-作用：
-
-- 检查 `workspace.yml`
-- 检查 `~/.super-engineer/skill-config.yml`
-- 初始化工作流运行目录
-
-适用模式：
-
-- `todo`
-- `openspec`
+`todo + auto` 通常可以直接从 `/se:apply` 开始。
 
-典型提示词：
+### OpenSpec 模式
 
 ```text
-/se:init
-使用当前工作空间，检查 workspace 是否可用，并告诉我缺哪些配置。
+/se:propose <change-name>
+-> /se:bridge
+-> 人工审核 todo.md
+-> /se:apply
+-> /se:archive-check
+-> /se:archive
 ```
 
-### `/se:propose <change-name>`
-
-作用：
+`/se:propose` 后禁止直接 `/se:apply`；必须先 `/se:bridge`。
 
-- 为当前需求生成或完善 OpenSpec change
-- 产出或更新 `proposal.md`、`design.md`、`tasks.md`
-- 优先读取 `workspace.yml.demand_file` 作为原始需求输入
-- 读取 `workspace.yml.reference_files` 中真实存在的参考文件作为上下文
-- 优先使用 OpenSpec CLI 创建 change、读取 status 和 artifact instructions
+## 命令表
 
-适用模式：
+| 命令 | 作用 | 下一步 |
+| --- | --- | --- |
+| `/se:init` | 初始化或检查工作区 | todo 模式可 `/se:apply`，OpenSpec 模式可 `/se:propose <change-name>` |
+| `/se:propose <change-name>` | 生成或修正 OpenSpec change，不改代码 | `/se:bridge` |
+| `/se:bridge` | 将 `tasks.md` 桥接为待审核 `todo.md` | 审核后 `/se:apply` |
+| `/se:plan` | 只生成实施计划，不改代码 | `/se:apply` |
+| `/se:apply` | 进入交付，实现、自查，并在 auto 模式继续 review/verify | 失败则修复后重跑，通过后看状态 |
+| `/se:review` | 单独执行代码审查 | `/se:verify` 或 `/se:apply` 修复 |
+| `/se:verify` | 执行验证并由脚本发送通知 | OpenSpec 模式下一步 `/se:archive-check` |
+| `/se:archive-check` | 检查 OpenSpec 是否可安全归档 | safe_merge 后 `/se:archive` |
+| `/se:archive` | 归档 OpenSpec change 和相关 specs | 完成 |
+| `/se:status` | 查看当前状态和阻塞项 | 按 allowed_next 继续 |
 
-- `openspec`
+## 最短提示词
 
-典型提示词：
+OpenSpec 模式：
 
 ```text
 /se:propose add-user-phone-filter
-请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
 ```
 
-### `/se:bridge`
-
-作用：
-
-- 读取当前 OpenSpec change
-- 把 `tasks.md` 转成桥接 todo
-- 输出待审核执行清单
-
-适用模式：
-
-- `openspec`
-
-前置条件：
-
-- 当前 change 已存在 `tasks.md`
-
-典型提示词：
-
 ```text
 /se:bridge
-针对当前 OpenSpec change 生成桥接 todo，并总结待审核项。
-```
-
-### `/se:plan`
-
-作用：
-
-- 创建新的交付会话
-- 生成 `plan.json` 和 `plan.md`
-- 给出影响范围、验收标准和主要风险
-
-适用模式：
-
-- `todo`
-- `openspec`
-
-前置条件：
-
-- `todo` 模式：`todo.md` 已存在
-- `openspec` 模式：推荐在 `/se:bridge` 后人工审核 `todo.md`，再执行
-
-典型提示词：
-
-```text
-/se:plan
-使用当前工作空间。
-基于当前交付输入生成计划，先不要改代码。
 ```
 
-### `/se:apply`
-
-作用：
-
-- 启动交付阶段
-- 由脚本进入实现阶段，AI 按 `plan.json` 修改业务代码
-- 实现完成后由脚本推进自查、审查、验证
-- `openspec` 模式下 verify 后自动回写执行摘要
-
-适用模式：
-
-- `todo`
-- `openspec`
-
-前置条件：
-
-- `todo` 模式：`todo.md` 已存在
-- `openspec` 模式：当前桥接 todo 已审核通过
-
-典型提示词：
+审核 `todo.md` 后：
 
 ```text
 /se:apply
-使用当前工作空间。
-如果没有硬阻塞，继续推进当前交付阶段。
 ```
 
-### `/se:review`
-
-作用：
-
-- 对当前代码改动做审查
-- 给出 gate、blocking findings、warning findings
-
-适用模式：
-
-- `todo`
-- `openspec`
-
-典型提示词：
-
-```text
-/se:review
-继续当前工作空间，对当前改动做代码审查。
-```
-
-### `/se:verify`
-
-作用：
-
-- 执行验证
-- 汇总每个仓库的验证结果
-- 判断当前 workflow 是 `done` 还是 `blocked`
-
-适用模式：
-
-- `todo`
-- `openspec`
-
-典型提示词：
+todo 模式：
 
 ```text
-/se:verify
-继续当前工作空间，执行验证并汇报结果。
-```
-
-### `/se:archive-check`
-
-作用：
-
-- 检查当前 OpenSpec change 是否满足归档条件
-- 输出 `archive_ready`、`merge_mode`、`blockers`、`spec_conflicts`
-
-适用模式：
-
-- `openspec`
-
-前置条件：
-
-- 当前 change 已完成交付并已有执行摘要
-
-典型提示词：
-
-```text
-/se:archive-check
-检查当前 OpenSpec change 是否满足归档条件。
-```
-
-### `/se:archive`
-
-作用：
-
-- 在满足安全条件时执行归档
-- 同步 delta specs
-- 移动当前 change 到 archive 目录
-
-适用模式：
-
-- `openspec`
-
-前置条件：
-
-- `archive_ready=true`
-- `merge_mode=safe_merge`
-- `spec_conflicts` 为空
-
-典型提示词：
-
-```text
-/se:archive
-仅在当前 change 满足安全归档条件时执行归档。
-```
-
-### `/se:status`
-
-作用：
-
-- 查看当前阶段
-- 查看当前 session
-- 查看阻塞项和下一步建议
-
-适用模式：
-
-- `todo`
-- `openspec`
-
-典型提示词：
-
-```text
-/se:status
-告诉我当前工作流处在哪个阶段，还有哪些阻塞项。
-```
-
-## 4. 两种模式下怎么理解命令
-
-### `todo` 模式
-
-`todo` 模式通常从这里开始：
-
-- `/se:init`
-- `/se:plan`
-- `/se:apply`
-
-如果是 `auto`，通常直接 `/se:apply`。  
-如果是 `manual`，通常先 `/se:plan`，再逐步 `/se:apply`、`/se:review`、`/se:verify`。
-
-### `openspec` 模式
-
-`openspec` 模式通常从这里开始：
-
-- `/se:propose <change-name>`
-- `/se:bridge`
-- `/se:plan` 或 `/se:apply`
-- `/se:archive-check`
-- `/se:archive`
-
-核心区别是：
-
-- `todo` 模式的输入是用户直接维护的 `todo.md`
-- `openspec` 模式的输入先是 OpenSpec change，再桥接成桥接 todo
-
-## 5. 推荐使用约束
-
-- `openspec` 模式下，不建议跳过 `/se:bridge`
-- `openspec` 模式下，不建议跳过桥接 todo 的人工审核
-- `manual` 模式下，建议在 `/se:plan` 之后先看计划再进入实现
-- `auto` 模式下，只有出现硬阻塞才应该停下
-- 归档前一定先做 `/se:archive-check`
-
-## 6. 一个完整例子
-
-下面是一条比较完整的 `openspec + auto` 使用链路：
-
-```text
-/se:propose add-user-phone-filter
-请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。
+/se:apply
 ```
 
-```text
-/se:bridge
-针对当前 OpenSpec change 生成桥接 todo，并总结待审核项。
-```
+## 约束
 
-```text
-/se:apply
-我已审核当前桥接 todo，可以进入交付阶段。
-使用当前工作空间。
-当前模式是 openspec + auto。
-如果没有硬阻塞，自动推进到 verify。
-verify 通过后继续检查归档条件；如果结果为 safe_merge，状态进入 archive_ready，下一步再执行 /se:archive。
-```
+- `workspace.yml` 是用户维护的契约，AI 禁止修改。
+- 状态、报告、通知必须由脚本生成。
+- 飞书/PushPlus 通知只能由 verify 脚本发送。
+- OpenSpec `tasks.md` 在 bridge 后发生变化时，必须重新 `/se:bridge`。
+- 归档前必须先 `/se:archive-check`。
 
-```text
-/se:status
-告诉我当前交付是否完成，是否已经进入归档阶段。
-```
+AI 内部执行协议以 `super-engineer-workflow/references/commands/` 下的命令分片为准。

package/docs//350/267/250/345/271/263/345/217/260/346/224/257/346/214/201/347/237/251/351/230/265.md

@@ -0,0 +1,34 @@
+# 跨平台支持矩阵
+
+## 支持等级
+
+| 平台 | 支持等级 | 建议 |
+| --- | --- | --- |
+| macOS | 完整支持 | 推荐日常使用与发布验证 |
+| Linux | 完整支持 | 推荐 CI / 服务器环境 |
+| Windows Git Bash | Beta 支持 | 推荐 Windows 用户优先使用 |
+| Windows PowerShell | Beta 支持 | 需要重点验证路径、引号和验证命令 |
+
+## 依赖
+
+- Node.js >= 18
+- npm >= 9
+- Python 3
+- 可选：OpenSpec CLI
+- 可选：飞书/Lark CLI，用于云文档需求源
+
+## 检查命令
+
+```bash
+se doctor --workspace <workspace>
+se doctor --workspace <workspace> --fix
+```
+
+`--fix` 会同步本机 skill，并补齐 Claude、Codex、Cursor、Trae、Kimi 的 `/se:*` 快捷命令模板。
+
+## Windows 注意事项
+
+- 优先使用 Git Bash。
+- `workspace.yml` 中路径建议使用 `/`，例如 `../code/project-a`。
+- PowerShell 下自定义 `verify_commands` 时注意引号转义。
+- 路径包含空格时，建议先用 `se doctor` 检查解析结果。

package/docs//351/241/271/347/233/256/346/236/266/346/236/204/344/270/216/350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -146,6 +146,7 @@ super-engineer/
 ├── docs/
 │   ├── 中文使用手册.md
 │   ├── se命令协议.md
+│   ├── 跨平台支持矩阵.md
 │   └── 项目架构与设计说明.md
 └── super-engineer-workflow/
     ├── SKILL.md
@@ -173,7 +174,7 @@ AI 使用这个 skill 时，首先读取 `SKILL.md`，再按需读取 `reference
 
 `references/` 是 AI 行为协议和工程规则库：
 
-- `se-commands.md`：`/se:*` 专属命令协议
+- `commands/`：按命令拆分的 `/se:*` 专属协议，AI 只读取当前命令需要的分片
 - `workflow.md`：工作空间配置、运行目录、会话规则、阻塞规则
 - `contracts.md`：关键产物、可靠性边界、归档前置条件
 - `execution-modes.md`：`manual` 与 `auto` 行为差异
@@ -650,7 +651,7 @@ superengineer/7-add-phone-filter/需求.md
 4. 增强验证策略：支持项目级 verify profile，避免只靠自动识别。
 5. 增强 schema 校验：对 `workspace.yml`、`plan.json`、`status.json`、OpenSpec 回写产物执行更严格校验。
 6. 增强平台化接入：把 JSON 产物作为后端数据源，提供可视化运行状态、报告和归档记录。
-7. 增强模型兼容性：把命令协议、阶段门禁和脚本输出进一步结构化，降低不同 AI 模型理解差异。
+7. 增强模型兼容性：继续收紧命令分片、阶段门禁和脚本 JSON 输出，降低不同 AI 模型理解差异。
 
 ## 14. 一句话总结
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-engineer-workflow",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Super Engineer workflow skill and CLI for demand-driven AI delivery with OpenSpec bridge support.",
   "license": "MIT",
   "author": "Gary-Coding",