@house365/comate 0.9.18 → 0.9.20

package/bin/cli.mjs

@@ -44,6 +44,46 @@ async function checkForUpdates(currentVersion) {
   });
 }
 
+// comate 自身的子命令（在下方被先取处理，不会透传给 skills CLI）。
+const COMATE_COMMANDS = ['init', 'doctor', 'update', 'usage'];
+
+// 允许透传给 skills CLI 的子命令（含别名）。留在这里的都是 skills CLI 真实存在
+// 的命令，未列入的一律视为未知命令并命中 --help。init/update 已被 comate 先取，
+// 故不在此列。
+const SKILLS_PASSTHROUGH = new Set([
+  'add', 'a',
+  'use',
+  'remove', 'rm',
+  'list', 'ls',
+  'find',
+  'upgrade',
+  'experimental_install',
+  'experimental_sync',
+]);
+
+const HELP_TEXT = `comate — SDD (规约驱动开发) 的 AI 开发编排器
+
+用法:
+  comate                安装/更新本包全部 comate skill 到当前 agent
+  comate init           安装 comate 和依赖到用户级，并在当前项目创建 openspec/
+  comate doctor         健康检查
+  comate update         更新 comate 到最新版本
+  comate usage          查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
+  comate --help, -h     显示本帮助
+  comate --version, -v  显示版本号
+
+管理 skill（透传给 skills CLI）:
+  comate add <包>       添加 skill 包
+  comate remove [名]    移除已装 skill（别名 rm）
+  comate list           列出已装 skill（别名 ls）
+  comate find [关键词]  搜索 skill
+
+装好后在 agent 中输入 /comate 开始使用。`;
+
+function printHelp(stream = console.log) {
+  stream(HELP_TEXT);
+}
+
 const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const args = process.argv.slice(2);
 const packageVersion = JSON.parse(readFileSync(`${pkgRoot}/package.json`, 'utf8')).version;
@@ -77,22 +117,26 @@ if (args[0] === 'usage') {
   process.exit(await usage(args.slice(1), { pkgRoot }));
 }
 
-if (args[0] === '--help' || args[0] === '-h') {
-  console.log(`comate — SDD (规约驱动开发) 的 AI 开发编排器
-
-用法:
-  comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/
-  comate doctor    健康检查
-  comate update    更新 comate 到最新版本
-  comate usage     查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
-
-装好后在 agent 中输入 /comate 开始使用。`);
+if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+  printHelp();
   process.exit(0);
 }
 
+// A leading token that is neither a flag, a comate command, nor a known skills
+// passthrough command is an unknown command. Print help to stderr and exit 1 so
+// typos surface as usage guidance instead of an opaque skills CLI error.
+if (args.length && !args[0].startsWith('-')) {
+  const cmd = args[0];
+  if (!COMATE_COMMANDS.includes(cmd) && !SKILLS_PASSTHROUGH.has(cmd)) {
+    console.error(`comate: 未知命令 '${cmd}'\n`);
+    printHelp(console.error);
+    process.exit(1);
+  }
+}
+
 // No args, or only flags (-g, --list, …) = install every comate skill from this
-// package, forwarding the flags. A leading subcommand passes straight through,
-// so remove/list/update all still work.
+// package, forwarding the flags. A leading passthrough subcommand goes straight
+// through, so add/remove/list all still work.
 const argv =
   args.length && !args[0].startsWith('-') ? args : ['add', pkgRoot, '--skill', '*', ...args];
 

package/docs/COMATE_BEGINNER_GUIDE.md

@@ -1,45 +1,33 @@
-# comate 入门操作手册
+# comate 入门指南
 
-这是一份给第一次使用 comate 的同学看的操作手册。按“安装 → 初始化 → 输入 /comate”的顺序，就可以开始使用。
+这份指南覆盖 comate 的安装、初始化和日常使用。
 
 ## 1. comate 是什么
 
-comate 是一个 AI 编程流程编排器。它把一次需求变更拆成几个可以检查的阶段，让 AI 先理解需求和设计，再写代码，最后验证并归档。
-
-完整流程：
+comate 是一个面向 AI 编程工具的 SDD（规约驱动开发）编排器。它把一次需求变更按阶段推进：
 
 ```text
 原始 PRD（可选）
-    ↓
-/comate-gate   PRD 门禁和拆分
-    ↓
-/comate-open   开题，创建 change
-    ↓
-/comate-design 深度设计
-    ↓
-/comate-build  计划和编码
-    ↓
-/comate-verify 验证和收尾
-    ↓
-/comate-archive 归档规格
+    -> gate -> open -> design -> build -> verify -> archive
 ```
 
-- **OpenSpec** 负责“要做什么”：proposal、spec、tasks 和归档。
-- **Superpowers** 负责“怎么做好”：头脑风暴、技术设计、计划、执行和验证。
-- **comate** 负责识别当前阶段，并把这些能力串起来。
+通常只需要使用 `/comate`，它会根据当前项目状态自动进入下一阶段。
 
-## 2. 安装前准备
+- `/comate-gate`：审阅 PRD，并在需要时拆分变更。
+- `/comate-fix`：处理 Bug 或很小的文案、配置调整。
+- `/comate-grill`：逐个澄清 PRD、设计或计划中的关键决策。
+- `/comate-kb-integration`：根据第三方官方文档生成对接档案。
 
-### 2.1 必需软件
+## 2. 安装前准备
 
-| 软件 | 建议版本 | 用途 |
-| --- | --- | --- |
-| Node.js | 20 或更高 | 运行 comate 和 npm |
-| npm | 随 Node.js 安装 | 安装 comate、OpenSpec |
-| Git | 任意现代版本 | 管理代码和分支 |
-| Bash | 3.2 或更高 | 执行 comate 的状态机脚本 |
+需要以下环境：
 
-Windows 用户建议安装 [Git for Windows](https://git-scm.com/download/win)，它会提供 Git Bash。PowerShell 可以运行 `comate`，但流程脚本仍需要 Bash。
+| 软件 | 要求 |
+| --- | --- |
+| Node.js | 20 或更高版本 |
+| npm | 随 Node.js 安装 |
+| Git | 任意现代版本 |
+| Bash | 3.2 或更高版本 |
 
 检查环境：
 
@@ -50,380 +38,151 @@ git --version
 bash --version
 ```
 
-### 2.2 哪些步骤需要网络
+Windows 用户请安装 [Git for Windows](https://git-scm.com/download/win)，以提供 Git Bash。PowerShell 可以运行 `comate`，但 comate 的流程脚本仍需要 Bash。
 
-首次初始化时，`comate init` 可能需要访问 npm registry 安装 OpenSpec CLI，并访问 GitHub 安装 Superpowers。
+首次初始化会访问 npm registry 和 GitHub，用于安装 OpenSpec CLI 与 Superpowers。
 
-comate 自己的 npm 包会随包携带 comate skill。npm 安装钩子只会尽力同步 comate 自身 skill，不会安装 Superpowers，也不会创建项目的 `openspec/` 和 `docs/`；这些由项目目录中的 `comate init` 完成。
+## 3. 安装并初始化项目
 
-## 3. 安装 comate
-
-全局安装：
+先安装 comate：
 
 ```bash
 npm install -g @house365/comate
 ```
 
-确认命令可用：
-
-```bash
-comate --version
-comate --help
-```
-
-安装后，skill 通常会同步到用户级目录：
-
-- macOS/Linux：`~/.agents/skills/`
-- Windows：`%USERPROFILE%\.agents\skills\`
-
-用户级 skill 可以被多个项目共用。项目自己的规格文件放在项目目录下的 `openspec/`。
-
-## 4. 初始化项目：`comate init`
-
-进入项目根目录再运行：
+然后进入业务项目根目录初始化：
 
 ```bash
 cd path/to/your-project
 comate init
+comate doctor
 ```
 
-Windows PowerShell 示例：
-
-```powershell
-Set-Location D:\work\my-project
-comate init
-```
-
-请不要在用户主目录直接运行。comate 会检查当前目录是否有 `.git`、`package.json`、`pyproject.toml`、`Cargo.toml` 等项目标记；空目录会先询问是否确认初始化。
-
-### 4.1 `init` 会做什么
-
-1. 检查 Bash 版本。
-2. 检查 OpenSpec，不存在或版本过旧时执行 `npm install -g @fission-ai/openspec@latest`。
-3. 检查 Superpowers，不存在时执行 `skills add obra/superpowers -g -y`。
-4. 把 comate 自身 skill 同步到用户级 skill 目录。
-5. 创建项目级 `openspec/`（已经存在则保留）。
-6. 创建 `docs/` 知识库骨架（只补缺少的文件，不覆盖已有文件）。
-
-某一步失败时，修好网络或环境后重新运行 `comate init` 即可。它是幂等的，已完成的步骤会跳过。
-
-## 5. 初始化后的目录结构
-
-```text
-your-project/
-├─ openspec/
-│  ├─ changes/              # 每次需求变更的工作区
-│  └─ specs/                # 已沉淀的主规格
-├─ docs/
-│  ├─ README.md
-│  ├─ architecture/
-│  │  └─ README.md
-│  └─ knowledge-base/
-│     ├─ README.md
-│     ├─ requirements/
-│     │  └─ _templates/PRD.md
-│     └─ integrations/
-│        ├─ README.md
-│        └─ _TEMPLATE/
-└─ 你的业务代码...
-```
-
-### 5.1 `openspec/`：项目规格
-
-- `changes/<change-name>/`：正在进行的变更，包含 `proposal.md`、`design.md`、`tasks.md`、delta spec 和 `.comate.yaml`。
-- `specs/<capability>/spec.md`：归档后长期维护的能力规格。
-- `changes/archive/`：已经完成并归档的 change。
-
-`.comate.yaml` 是 comate 的状态真相源，记录当前阶段、构建模式、验证结果等。
-
-### 5.2 `docs/`：长期知识库
-
-- `docs/`：项目背景、架构约束、原始 PRD、第三方对接资料。
-- `openspec/`：某次变更的提案、设计、任务、能力规格和归档记录。
-
-### 5.3 用户级 skill 目录
-
-```text
-~/.agents/skills/                  # macOS/Linux
-%USERPROFILE%\.agents\skills\     # Windows
-```
-
-已有的 Superpowers 或其他 skill 不会因为 `comate init` 被覆盖。
-
-## 6. `docs/` 目录详解
-
-### 6.1 `docs/README.md`
-
-说明知识库整体规则、`architecture/` 与 `knowledge-base/` 的边界，以及它们和 `openspec/` 的关系。
-
-### 6.2 `docs/architecture/`
-
-放项目架构约束，例如前后端分层、API/数据库/错误码约定、命名规范和部署约束。`comate init` 只创建占位 README，真正的规则需要项目自己补充。这里是 `/comate-gate` 检查契约时的事实来源。
-
-### 6.3 `docs/knowledge-base/`
-
-放长期维护的需求和外部服务资料：
-
-- `requirements/`：原始 PRD；
-- `integrations/`：第三方服务对接档案；
-- `README.md`：命名、溯源和 PRD 到 change 的流程说明。
-
-### 6.4 `docs/knowledge-base/requirements/`
-
-这里是 PRD 的固定位置。模板位于：
-
-```text
-docs/knowledge-base/requirements/_templates/PRD.md
-```
-
-复制模板到功能目录，填写后运行 `/comate-gate`。
-
-### 6.5 `docs/knowledge-base/integrations/`
-
-每个第三方平台建立一个子目录，例如：
-
-```text
-docs/knowledge-base/integrations/alipay/README.md
-docs/knowledge-base/integrations/alipay/api-snapshot.md
-```
+`comate init` 会：
 
-需要从官方文档生成对接档案时，使用 `/comate-kb-integration`。
+1. 安装或检查 OpenSpec CLI、Superpowers 和 comate skills。
+2. 在用户级目录安装 skills（通常是 `~/.agents/skills/`；Windows 为 `%USERPROFILE%\.agents\skills\`）。
+3. 在当前项目创建 `openspec/` 和 `docs/` 知识库骨架。
 
-## 7. PRD 存放位置和命名规范
+已有文件不会被覆盖，初始化可以重复执行。请在项目目录运行，不要直接在用户主目录运行。
 
-推荐格式：
+初始化后，项目通常会多出：
 
 ```text
-docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-<三位序号>-<功能名>.md
+openspec/                          # 变更和长期规格
+docs/knowledge-base/requirements/ # PRD
+docs/architecture/                # 架构约束
 ```
 
-示例：
+## 4. 第一次使用
 
-```text
-docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
-```
-
-规则：
-
-1. 功能目录使用“日期 + 功能名”，日期格式为 `YYYYMMDD`。
-2. PRD 文件以 `PRD-001`、`PRD-002` 这样的三位序号开头。
-3. 文件名中的功能名应和目录功能名保持一致。
-4. 同一个功能目录中的序号不要重复。
-5. 不建议使用 `PRD-1.md` 或把 PRD 放到 `openspec/changes/`。
-
-`/comate-gate` 会在 PRD 同级自动生成：
+在 Claude Code、Codex、Cursor 等支持 Agent Skills 的工具中输入：
 
 ```text
-PRD-001.gate.yaml       # 机器读取的门禁状态
-PRD-001-REVIEW.md       # 人类可读的评审报告
+/comate 我想增加用户登录功能，支持邮箱和密码登录
 ```
 
-PRD 通过门禁后如果又被修改，哈希会变化，门禁会变成过期状态，需要重新运行 `/comate-gate`。
+comate 会创建并推进一个 change。过程中只在需要你决定时提问；确认设计、实现和验证结果后，流程会完成归档。
 
-## 8. 从需求到代码的 Skill 流程
+### 需求来自 PRD
 
-### 8.1 需求来自一份 PRD
-
-先把 PRD 放到 `docs/knowledge-base/requirements/`，然后直接指定 PRD 路径：
+复杂需求可以先把 PRD 放在 `docs/knowledge-base/requirements/`，然后直接指定文件：
 
 ```text
 /comate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
 ```
 
-`/comate` 会识别这是原始 PRD，自动进入 PRD 门禁和拆分流程；不需要先手动调用 `/comate-gate`。门禁通过后，它会继续处理拆分出来的 change。
-
-如果只想单独审阅或重新运行门禁，也可以直接输入：
+这会自动进入 PRD 门禁和拆分流程。只想单独审阅 PRD 时使用：
 
 ```text
-/comate-gate docs/knowledge-base/requirements/20260820-用户登录/PRD-001-用户登录.md
+/comate-gate path/to/PRD.md
 ```
 
-对已有 change 继续工作时，输入：
-
-```text
-/comate
-```
-
-comate 会自动从当前阶段继续：`open → design → build → verify → archive`。
-
-### 8.2 需求来自普通对话
-
-不需要先写 PRD，直接输入：
-
-```text
-/comate 我想增加用户登录功能，支持邮箱和密码登录
-```
-
-复杂需求仍建议先整理成 PRD，便于评审和追踪。
-
-### 8.3 Bug 或很小的调整
+### Bug 或小调整
 
 ```text
 /comate-fix 修复登录失败时页面没有提示的问题
 ```
 
-它走简化流程：`open → build → verify → archive`，跳过完整 brainstorming。涉及新能力、架构变化、数据库 schema 或多个模块时，应升级回完整 `/comate` 流程。
-
-## 9. Skill 介绍
-
-| Skill | 作用 |
-| --- | --- |
-| `/comate` | 总入口，自动检测当前 change 阶段并分派 |
-| `/comate-gate` | 审阅 PRD、评分、记录阻断问题并拆分 change |
-| `/comate-open` | 探索需求，创建 change 和 proposal/design/tasks 骨架 |
-| `/comate-design` | 技术设计和方案头脑风暴，形成 Design Doc 和 delta spec |
-| `/comate-build` | 制定实施计划、按任务编码并更新 tasks |
-| `/comate-verify` | 运行测试和检查，生成验证报告并处理分支收尾 |
-| `/comate-archive` | 同步 delta spec、标记设计文档并归档 change |
-| `/comate-fix` | Bug 或小调整的快速路径 |
-| `/comate-grill` | 对 PRD、计划或设计中的模糊决策逐个追问 |
-| `/comate-kb-integration` | 根据第三方官方文档生成 integrations 对接档案 |
-
-### 9.1 底层依赖分工
+如果改动涉及新能力、架构、数据库结构或多个模块，请改用完整的 `/comate` 流程。
 
-- **OpenSpec**：负责 `openspec/`、change 规格和归档。
-- **Superpowers**：由 `comate init` 通过 `skills` CLI 从 `obra/superpowers` 安装，负责设计、规划、执行和收尾。
-- **comate skill**：本项目提供的编排规则和状态机。
+### 中断后继续
 
-首次使用时，如果 Superpowers 安装失败，design/build/verify 相关流程不能完整运行。先修复网络或手工安装，再重跑 `comate init`。
+回到同一个项目目录，再输入：
 
-## 10. 常用命令
-
-### 10.1 安装和检查
-
-```bash
-comate --help
-comate --version
-comate init
-comate doctor
+```text
+/comate
 ```
 
-### 10.2 查看 token 用量
+comate 会读取 `openspec/changes/<change-name>/.comate.yaml`，从当前阶段继续。
 
-```bash
-comate usage
-comate usage daily
-comate usage --global
-comate usage --json
-```
-
-## 11. 配套 UI 查看器
+## 5. 配套 UI（可选）
 
-`comate-ui` 是 comate 的本地只读浏览器工作区，用来可视化查看项目中的变更状态、OpenSpec 规格、PRD、Superpowers 设计文档、计划和验证报告。它不会修改项目文件，也不需要数据库。
+Comate UI 是本地只读的可视化工作台，用于查看 change 状态、规格、PRD、实施计划和验证结果，不会修改项目文件。
 
-全局安装：
+安装：
 
 ```bash
 npm install -g @house365/comate-ui@latest
 ```
 
-安装后，在包含 `openspec/` 的项目根目录运行：
+在已经执行过 `comate init` 的项目根目录启动：
 
 ```bash
 comate-ui
 ```
 
-也可以指定项目路径、端口或禁止自动打开浏览器：
+启动后会自动打开浏览器。服务只监听本机 `127.0.0.1`，按 `Ctrl+C` 停止。也可以不安装直接运行，或指定项目和端口：
 
 ```bash
-comate-ui D:\work\my-project
-comate-ui D:\work\my-project --port 4300
-comate-ui --no-open
+npx @house365/comate-ui@latest
+comate-ui path/to/your-project --port 4300
+comate-ui --no-open # 不自动打开浏览器
+comate-ui --demo    # 查看内置示例
 ```
 
-查看内置示例：
+## 6. 常用命令
 
 ```bash
-comate-ui --demo
+comate --help         # 查看命令帮助
+comate --version      # 查看版本
+comate doctor         # 检查 Bash、OpenSpec 和 skills
+comate update         # 更新到 npm 最新版本
+comate usage          # 查看当前项目 token 用量
+comate usage daily    # 按天查看
+comate usage --global # 查看全部项目
 ```
 
-查看器只绑定本机 `127.0.0.1`。默认会自动打开浏览器；端口被占用时会自动选择下一个可用端口，按 `Ctrl+C` 停止。
-
-## 12. 更新 comate
+更新后建议在各项目根目录重新执行一次 `comate init`，把新版 skills 同步到用户级目录：
 
 ```bash
-npm install -g @house365/comate@latest
+comate update
 cd path/to/your-project
 comate init
 ```
 
-npm 更新 CLI 和包内文件；`comate init` 负责把新版 comate skill 同步到用户级目录，并补齐当前项目缺少的 `openspec/`、`docs/` 文件。
-
-更新是幂等的：已有 Superpowers 不覆盖，已有项目规格和 docs 文件不覆盖。若使用 `npm install --ignore-scripts`，请手动执行 `comate init`。
-
-## 13. 网络问题和手工补装
-
-### OpenSpec 安装失败
-
-```bash
-npm install -g @fission-ai/openspec@latest
-openspec --version
-```
-
-### Superpowers 安装失败
+## 7. 常见问题
 
-```bash
-skills add obra/superpowers -g -y
-```
+### `comate init` 失败
 
-GitHub 无法访问时，可以配置 npm/Git 代理、使用公司网络或 Git Bash/WSL，安装成功后再运行：
+先运行：
 
 ```bash
-comate init
 comate doctor
 ```
 
-当前 npm 包没有内置 Superpowers 离线快照；不要把“npm 安装成功”理解成 Superpowers 已安装完成。
-
-## 14. 常见问题
-
-### `comate init` 应该在哪运行？
-
-在业务项目根目录运行，也就是能看到 `.git` 或 `package.json` 的目录。不要在 `C:\Users\你的用户名` 或 `~` 直接运行。
-
-### npm 安装后为什么还要 `comate init`？
-
-npm 只安装 CLI 和包本身。`init` 才会准备 OpenSpec、Superpowers 与 comate skill，并创建当前项目的 `openspec/`、`docs/`。
-
-### 重跑 init 会不会覆盖我的文件？
-
-不会。已有 skill、`openspec/`、docs 文件会保留，只补缺少的内容。
-
-### 找不到 `openspec` 怎么办？
-
-重开终端让全局 npm PATH 生效，然后运行 `openspec --version`。仍找不到就执行 `npm install -g @fission-ai/openspec@latest`，再运行 `comate init`。
-
-### 找不到 Bash 怎么办？
-
-Windows 安装 Git for Windows；macOS 自带的 Bash 3.2 可以直接使用，不需要另外安装 Bash 4+。
-
-### 流程中断了怎么办？
-
-回到同一个项目目录，再输入 `/comate`。comate 会读取 `openspec/changes/<name>/.comate.yaml` 和已有产物，从当前阶段继续。先运行 `comate doctor` 可以排除环境问题。
-
-### 有多个 change 怎么办？
-
-在对话中明确 change 名称。不要同时修改多个 change 的 `tasks.md`。
-
-## 15. 新手最短上手路径
+如果是网络问题，确认 npm registry 和 GitHub 可访问，修复代理或网络后重新运行 `comate init`。也可以手动补装：
 
 ```bash
-npm install -g @house365/comate
-cd your-project
+npm install -g @fission-ai/openspec@latest
+skills add obra/superpowers -g -y
 comate init
-comate doctor
 ```
 
-然后在 Claude Code、Codex、Cursor 等支持 Agent Skills 的工具中输入：
-
-```text
-/comate 我想实现一个用户登录功能
-```
+### 找不到 `openspec` 或 Bash
 
-等待 AI 在需要你决定的地方提问，确认设计和构建选项后，让流程走到验证和归档。
+重开终端让全局 npm PATH 生效。Windows 请安装 Git for Windows，并确认 `bash --version` 不低于 3.2。
 
-## 16. 进一步阅读
+### 重跑 `init` 会覆盖项目文件吗？
 
-- [完整技术手册](COMATE_MANUAL.md)：状态字段、门禁规则、脚本接口和故障排查。
-- [项目 README](../README.md)：项目概览和快速安装。
-- 初始化后生成的 `docs/knowledge-base/README.md`：PRD 溯源和命名规则。
+不会。`init` 只补充缺少的 skills、`openspec/` 和 `docs/` 文件，已有内容会保留。