@house365/comate 0.5.0 → 0.7.0

package/README.md

@@ -2,30 +2,32 @@
 
 OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
 
-comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(hotfix / tweak 预设除外)。
+comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(fix 预设除外)。
 
 ## 五阶段
 
 ```
-[原始 PRD] ─→ /comate-intake ─┐  (阶段 0:门禁+拆分)
+[原始 PRD] ─→ /comate-gate ─┐  (阶段 0:门禁+拆分)
                               ▼
 /comate  ──自动探测阶段──────→ open → design → build → verify → archive
 ```
 
 | 阶段 | skill | 职责 |
 |------|-------|------|
-| intake | `/comate-intake` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
+| gate | `/comate-gate` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
 | open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
 | design | `/comate-design` | 技术设计与方案 brainstorming |
 | build | `/comate-build` | 按任务实现并提交 |
 | verify | `/comate-verify` | 验证、出报告、处理分支 |
 | archive | `/comate-archive` | 同步增量规约并归档 |
 
-预设路径:`/comate-hotfix`(热修)、`/comate-tweak`(文案/配置小调整)。
+预设路径:`/comate-fix`(快速小改动,覆盖 bug 修复与文案/配置小调整两种模式)。
 
-工具 skill:`/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-intake 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
+工具 skill:
+- `/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-gate 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
+- `/comate-kb-integration`(第三方对接档案生成)——从官方文档 URL 抓取并按 `docs/knowledge-base/integrations/_TEMPLATE/` 规范产出对接档案(`<service-id>/README.md` + `api-snapshot.md`),自动追加根索引一行。是知识库 integrations scaffold 的配套建档工具;遇 JS 动态渲染文档站自动降级 Playwright 无头抓取。
 
-**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-intake`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
+**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-gate`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
 
 ## 安装
 
@@ -40,7 +42,7 @@ cd your-project
 comate init
 ```
 
-`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-intake` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
+`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-gate` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
 
 skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
 
@@ -59,6 +61,21 @@ cd your-project && comate init
 
 输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。
 
+## Token 用量:`comate usage`
+
+查看**当前项目**的 token 消耗与估算成本(封装 [ccusage](https://github.com/ryoppippi/ccusage),随 comate 一起装):
+
+```bash
+comate usage            # 本项目按会话(session)统计
+comate usage daily      # 本项目按天
+comate usage --global   # 全部项目(不做项目隔离)
+comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
+```
+
+默认只统计当前工作目录这一个项目:Claude Code 数据按 `~/.claude/projects/<项目>/` 隔离,Codex 数据按会话记录里的 `cwd` 过滤,两者都不会混入其它项目的用量。加 `--global` 看全量,或用 `comate usage codex ...` 单看某个 agent。
+
+> 粒度到项目/会话级;不做 open/design/build 阶段级归因(那需要在状态机打时间戳,属后续增强)。
+
 ## 目录结构
 
 ```
@@ -68,9 +85,10 @@ skills/
     reference/       决策点、脏工作树协议、前置条件
     tests/           bats 测试
   comate-open/ design/ build/ verify/ archive/   各阶段 skill
-  comate-intake/                                  阶段 0:PRD 门禁与拆分
-  comate-hotfix/ tweak/                           预设路径 skill
+  comate-gate/                                    阶段 0:PRD 门禁与拆分
+  comate-fix/                                     预设路径 skill(bug + 小调整)
   comate-grill/                                   决策点穷追式澄清工具
+  comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
 docs/
   COMATE_MANUAL.md   完整操作手册
 ```

package/bin/cli.mjs

@@ -21,12 +21,18 @@ if (args[0] === 'doctor') {
   process.exit(doctor(args.slice(1)));
 }
 
+if (args[0] === 'usage') {
+  const { usage } = await import('./usage.mjs');
+  process.exit(await usage(args.slice(1), { pkgRoot }));
+}
+
 if (args[0] === '--help' || args[0] === '-h') {
   console.log(`comate — OpenSpec + Superpowers 规约驱动的开发编排器
 
 用法:
   comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/
   comate doctor    健康检查
+  comate usage     查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
 
 装好后在 agent 中输入 /comate 开始使用。`);
   process.exit(0);

package/bin/doctor.mjs

@@ -3,8 +3,12 @@
 // ponytail: comate.sh already implements every check. This only locates the
 // installed copy so the user doesn't have to remember the path.
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { atLeast, capture, npmInvocation } from './init.mjs';
 
 // Where the skills CLI puts things. `init` installs user-level, but a project
 // copy shadows it for the agent, so check cwd first and report on the same one
@@ -67,5 +71,85 @@ export function doctor(argv) {
     console.error(`无法执行 bash (${bash}) — comate 的脚本需要 bash。${error.message}`);
     return 1;
   }
+
+  // ccusage is a node dependency (for `comate usage`), not a bash-side tool, so
+  // it lives here rather than in comate.sh's doctor. A miss is a warning, never
+  // a failure: usage falls back to `npx ccusage@latest`, so it still works.
+  reportCcusage();
+
+  // Version check is the only place a user learns a newer comate exists: the
+  // npm package doesn't self-update and `~/.agents/skills` keeps the copied
+  // skills until `comate init` is re-run. Never blocks or fails doctor — a
+  // network miss / offline just skips the line (see checkForUpdate).
+  reportUpdate();
+
   return status ?? 1;
 }
+
+// resolvable = shipped as comate's pinned dependency; the common, happy case
+// after `npm i -g @house365/comate`. Otherwise point at the two ways out.
+export function ccusageResolvable(pkgRoot = defaultPkgRoot()) {
+  try {
+    createRequire(join(pkgRoot, 'package.json')).resolve('ccusage/package.json');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function reportCcusage() {
+  if (ccusageResolvable()) {
+    console.log('  ✓ ccusage present (comate usage 可用)');
+  } else {
+    console.log(
+      '  ⚠ ccusage not found — reinstall with  npm i -g @house365/comate  ' +
+        '(comate usage 会回退到 npx ccusage@latest)',
+    );
+  }
+}
+
+// Read {name, version} from the installed package.json. Both come from the same
+// file so the check keys off whatever package this binary actually belongs to —
+// no hardcoded name/version to drift when the package is renamed or bumped.
+export function localPackage(pkgRoot = defaultPkgRoot()) {
+  try {
+    const { name, version } = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'));
+    return name && version ? { name, version } : null;
+  } catch {
+    return null;
+  }
+}
+
+// Compare the installed version against npm's latest. Returns null (silent) on
+// anything uncertain — no package.json, no npm, offline, timeout, unparseable
+// output — because a *diagnostic* command must never hang or error on a network
+// miss. `fetchLatest` is injectable so this is unit-testable without the network.
+export function checkForUpdate({
+  pkg = localPackage(),
+  fetchLatest = defaultFetchLatest,
+} = {}) {
+  if (!pkg) return null;
+  const latest = fetchLatest(pkg.name);
+  if (!latest || !/^\d+\.\d+\.\d+/.test(latest)) return null;
+  // outdated when current is NOT at least latest (atLeast is >=).
+  return { name: pkg.name, current: pkg.version, latest, outdated: !atLeast(pkg.version, latest) };
+}
+
+// `npm view <pkg> version` — capture() already caps at 15s and returns null on
+// any non-zero exit, so offline/timeout falls through to a skipped check.
+function defaultFetchLatest(name) {
+  const { command, args, shell } = npmInvocation(['view', name, 'version']);
+  return capture(command, args, { shell: Boolean(shell) });
+}
+
+function reportUpdate(info = checkForUpdate()) {
+  if (!info || !info.outdated) return; // up to date or couldn't tell → say nothing
+  console.log(
+    `  ⬆ 有新版 comate：${info.current} → ${info.latest}。升级：` +
+      `npm i -g ${info.name}@latest 然后重跑 comate init`,
+  );
+}
+
+function defaultPkgRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}

package/bin/init-run.mjs

@@ -156,7 +156,7 @@ export async function init(pkgRoot) {
     results.push(['openspec/', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason, r2.output]);
   }
 
-  // 5. docs/ knowledge-base scaffold. /comate-intake reads PRDs from
+  // 5. docs/ knowledge-base scaffold. /comate-gate reads PRDs from
   // docs/knowledge-base/requirements/ (comate_kb_root is hardcoded there), so a
   // fresh project has nowhere to put a PRD. Idempotent — existing files are left
   // alone, only missing pieces are filled in, so re-running never clobbers a

package/bin/init.mjs

@@ -176,7 +176,7 @@ function superpowersInstalled(scope) {
 // (repo checkout) and after `skills add` copies the skill to ~/.agents/skills.
 // Locating it relative to pkgRoot means init reads the same tree it packed.
 function scaffoldSourceDir(pkgRoot) {
-  return join(pkgRoot, 'skills', 'comate-intake', 'scaffold', 'docs');
+  return join(pkgRoot, 'skills', 'comate-gate', 'scaffold', 'docs');
 }
 
 // copyTreeSkipExisting — recursively copy src→dst, never overwriting a file that
@@ -201,7 +201,7 @@ function copyTreeSkipExisting(src, dst, acc = { created: 0, skipped: 0 }) {
 }
 
 // scaffoldDocs — lay down docs/ (knowledge-base + architecture placeholder + PRD
-// template) so /comate-intake has somewhere to read PRDs from. comate_kb_root in
+// template) so /comate-gate has somewhere to read PRDs from. comate_kb_root in
 // comate-lib.sh is hardcoded to docs/knowledge-base, so this path is not
 // configurable — it must match. Idempotent: existing files are never clobbered.
 function scaffoldDocs(pkgRoot, cwd = process.cwd()) {

package/bin/usage.mjs

@@ -0,0 +1,252 @@
+// `comate usage` — show this project's Claude Code / Codex token usage by
+// wrapping ccusage.
+//
+// Why a wrapper and not just `npx ccusage`: ccusage aggregates every project
+// globally and there is no "just this repo" flag. Scoping has to be done per
+// agent, because the two store data differently:
+//
+//   Claude Code — one dir per project: ~/.claude/projects/<encoded-cwd>/*.jsonl.
+//                 Honours CLAUDE_CONFIG_DIR. So: a throwaway root whose
+//                 projects/ holds a single symlink to this project's dir.
+//   Codex       — flat by date: ~/.codex/sessions/YYYY/MM/DD/*.jsonl, project
+//                 identified only by a `cwd` inside each file's session_meta.
+//                 Honours CODEX_HOME. So: filter files by cwd, symlink the
+//                 matches into a throwaway sessions/ dir.
+//
+// Both env vars are set to the scoped roots even when a root is empty — an empty
+// scoped root reports zero for that agent, which is correct, whereas leaving the
+// var unset would let ccusage fall back to the global dir and leak every other
+// project's usage in. `--global` skips all scoping and forwards straight through.
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  closeSync,
+  readdirSync,
+  rmSync,
+  linkSync,
+  copyFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative } from 'node:path';
+
+// Claude Code encodes a project's cwd into a directory name by replacing every
+// path separator and the drive colon with a dash: D:\a\b -> D--a-b, /a/b -> -a-b.
+// Verified against a real ~/.claude/projects entry on Windows.
+export function encodeProjectDir(cwd) {
+  return cwd.replace(/[:\\/]/g, '-');
+}
+
+function home() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? '';
+}
+
+// Where Claude Code keeps this project's transcripts. CLAUDE_CONFIG_DIR wins if
+// the user has relocated the config dir, matching ccusage's own resolution.
+export function claudeDataDir(cwd = process.cwd(), env = process.env) {
+  const configRoot = env.CLAUDE_CONFIG_DIR || join(home(), '.claude');
+  return join(configRoot, 'projects', encodeProjectDir(cwd));
+}
+
+// Codex's sessions root. CODEX_HOME wins, else ~/.codex.
+export function codexSessionsDir(env = process.env) {
+  const root = env.CODEX_HOME || join(home(), '.codex');
+  return join(root, 'sessions');
+}
+
+// Read just the head of a file — enough to catch the session_meta record, which
+// Codex writes first. Avoids slurping multi-MB transcripts to read one cwd.
+function readHead(file, bytes = 8192) {
+  const fd = openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.toString('utf8', 0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// The cwd recorded in a Codex session file, or null. session_meta is the first
+// record; its payload.cwd (older: top-level cwd) is the project path.
+export function codexFileCwd(file, read = readHead) {
+  const head = read(file);
+  const line = head.split('\n').find((l) => l.includes('session_meta'));
+  if (!line) return null;
+  try {
+    const o = JSON.parse(line);
+    return o.payload?.cwd ?? o.cwd ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Every *.jsonl under a Codex sessions dir whose recorded cwd matches this
+// project. Bounded head-reads only; returns [] if the sessions dir is absent.
+export function codexFilesForCwd(sessionsDir, cwd, { read = readHead } = {}) {
+  if (!existsSync(sessionsDir)) return [];
+  const out = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.jsonl') && codexFileCwd(p, read) === cwd) out.push(p);
+    }
+  };
+  walk(sessionsDir);
+  return out;
+}
+
+// Prefer the pinned ccusage dependency (offline, version-locked); fall back to
+// npx when resolution fails (e.g. a hoisting layout we can't see). Mirrors
+// init.mjs's skillsInvocation so the two behave the same across install shapes.
+export function ccusageInvocation(pkgRoot, args) {
+  try {
+    const require = createRequire(join(pkgRoot, 'package.json'));
+    const manifest = require('ccusage/package.json');
+    const rel = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin.ccusage;
+    const entry = join(dirnameOf(require.resolve('ccusage/package.json')), rel);
+    return { command: process.execPath, args: [entry, ...args] };
+  } catch {
+    return {
+      command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+      args: ['--yes', 'ccusage@latest', ...args],
+      shell: process.platform === 'win32',
+    };
+  }
+}
+
+function dirnameOf(file) {
+  return file.slice(0, Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')));
+}
+
+// Materialise one source file into the scoped tree. Hardlink first — it is
+// instant, uses no extra disk, and (unlike a symlink or junction) is a real
+// directory entry that ccusage's globber traverses on Windows, where symlinked
+// and junctioned dirs are silently skipped. Copy is the cross-volume fallback
+// (hardlinks can't span drives). Creates parent dirs as needed.
+function linkFile(src, dst) {
+  mkdirSync(dirname(dst), { recursive: true });
+  try {
+    linkSync(src, dst);
+  } catch {
+    copyFileSync(src, dst);
+  }
+}
+
+// Every *.jsonl under a dir, as [absolutePath, relativePath] pairs so the scoped
+// copy can preserve Claude's per-project subdir layout.
+function jsonlFiles(dir, base = dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) jsonlFiles(p, base, out);
+    else if (e.name.endsWith('.jsonl')) out.push([p, relative(base, p)]);
+  }
+  return out;
+}
+
+// Build a throwaway config root scoped to this project, for both agents. Always
+// returns { root, env, cleanup }: env carries CLAUDE_CONFIG_DIR + CODEX_HOME
+// pointing at the scoped roots, so unset agents report zero rather than leaking
+// global data. `found` says whether any agent had data for this project.
+//
+// Files are hardlinked (see linkFile) rather than the dir symlinked, because
+// ccusage does not traverse symlinked/junctioned directories on Windows.
+export function buildScopedEnv(
+  { claudeDir, codexSessionsDir: codexDir, cwd },
+  { mkdtemp = defaultMkdtemp, linkFn = linkFile, codexFiles = codexFilesForCwd } = {},
+) {
+  const root = mkdtemp();
+
+  // Claude: hardlink this project's transcripts under projects/proj/, keeping
+  // any subdir structure so ccusage sees them exactly as it would in place.
+  const claudeConfig = join(root, 'claude');
+  const claudeProj = join(claudeConfig, 'projects', 'proj');
+  mkdirSync(claudeProj, { recursive: true });
+  let found = false;
+  if (claudeDir && existsSync(claudeDir)) {
+    for (const [abs, rel] of jsonlFiles(claudeDir)) {
+      linkFn(abs, join(claudeProj, rel));
+      found = true;
+    }
+  }
+
+  // Codex: hardlink only the session files whose cwd matches this project,
+  // flattened under sessions/ (ccusage globs recursively, so layout is moot).
+  const codexHome = join(root, 'codex');
+  const codexSessions = join(codexHome, 'sessions');
+  mkdirSync(codexSessions, { recursive: true });
+  const matches = codexDir ? codexFiles(codexDir, cwd) : [];
+  matches.forEach((f, i) => linkFn(f, join(codexSessions, `${i}-${basename(f)}`)));
+  if (matches.length > 0) found = true;
+
+  return {
+    root,
+    found,
+    env: { ...process.env, CLAUDE_CONFIG_DIR: claudeConfig, CODEX_HOME: codexHome },
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+function defaultMkdtemp() {
+  return mkdtempSync(join(tmpdir(), 'comate-usage-'));
+}
+
+// Split comate's own flags (--global) from everything else, which is forwarded
+// to ccusage untouched. Default subcommand is `session` — the per-conversation
+// view is what "how much did this project cost" usually means.
+export function parseArgs(argv) {
+  const global = argv.includes('--global');
+  const rest = argv.filter((a) => a !== '--global');
+  const hasCommand = rest.length > 0 && !rest[0].startsWith('-');
+  const forwarded = hasCommand ? rest : ['session', ...rest];
+  return { global, forwarded };
+}
+
+export async function usage(argv, { pkgRoot = defaultPkgRoot() } = {}) {
+  const { global, forwarded } = parseArgs(argv);
+
+  let scoped = null;
+  let env = process.env;
+  if (!global) {
+    const cwd = process.cwd();
+    scoped = buildScopedEnv({
+      claudeDir: claudeDataDir(cwd),
+      codexSessionsDir: codexSessionsDir(),
+      cwd,
+    });
+    if (!scoped.found) {
+      scoped.cleanup();
+      console.error(
+        '本项目暂无 Claude Code / Codex 会话记录。\n' +
+          '用  comate usage --global  查看全部项目的用量。',
+      );
+      return 1;
+    }
+    env = scoped.env;
+  }
+
+  try {
+    const { command, args, shell } = ccusageInvocation(pkgRoot, forwarded);
+    const { status, error } = spawnSync(command, args, {
+      stdio: 'inherit',
+      env,
+      ...(shell ? { shell: true } : {}),
+    });
+    if (error) {
+      console.error(`无法运行 ccusage：${error.message}\n试试  npx ccusage@latest`);
+      return 1;
+    }
+    return status ?? 1;
+  } finally {
+    scoped?.cleanup();
+  }
+}
+
+function defaultPkgRoot() {
+  return dirnameOf(dirnameOf(import.meta.url.replace(/^file:\/\/\/?/, '')));
+}