/** * gen-command-reference.ts — 从 commander 命令树生成 ssw-loop 参考 (P7, 2026-07-24) * * 跑: npx tsx scripts/gen-command-reference.ts * 产出: .claude/skills/ssw-loop/references/command-reference.generated.md * * 目的 (DESIGN §6): ssw-loop 子代理模板手写 dacli 命令语法会漂移 (典型: 缺 --category)。 * 命令树是唯一真相源 — 参考文件自动生成, CLI 一改重跑即同步, 永不漂移。 */ import { writeFileSync } from 'node:fs' import { join } from 'node:path' import type { Command } from 'commander' import { buildProgram, VERSION } from '../src/program.ts' import { getCcWorkDir } from '../src/core/paths.ts' interface CmdDoc { path: string desc: string args: Array<{ name: string; desc: string }> opts: Array<{ flags: string; desc: string; def?: unknown }> } function walk(cmd: Command, prefix: string, out: CmdDoc[]): void { const subs = cmd.commands as Command[] for (const c of subs) { const path = `${prefix} ${c.name()}`.trim() const args = ((c as any).registeredArguments ?? []).map((a: any) => ({ name: a.name?.() ?? a._name ?? '', desc: a.description ?? '', })) const opts = (c.options ?? []).map((o: any) => ({ flags: o.flags as string, desc: (o.description as string) ?? '', def: o.defaultValue, })) // 只收叶子命令 (有 action / 无子命令) 和有内容的父命令 if (c.commands.length === 0 || args.length || opts.length) { out.push({ path, desc: c.description() ?? '', args, opts }) } if (c.commands.length > 0) walk(c, path, out) } } const program = buildProgram() const docs: CmdDoc[] = [] walk(program, 'dacli', docs) const lines: string[] = [] lines.push('') lines.push(`# dacli 命令参考 (generated, dacli v${VERSION})`) lines.push('') lines.push('> ssw-loop 子代理引用本文件而非内联命令语法 (永不漂移)。') lines.push(`> 共 ${docs.length} 条命令。`) lines.push('') let group = '' for (const d of docs) { const top = d.path.split(' ')[1] ?? '' if (top !== group) { group = top lines.push(`\n## ${top}\n`) } lines.push(`### \`${d.path}\``) if (d.desc) lines.push(d.desc) if (d.args.length) { lines.push('- 参数: ' + d.args.map(a => `\`${a.name}\`${a.desc ? ' — ' + a.desc : ''}`).join('; ')) } if (d.opts.length) { lines.push('- 选项:') for (const o of d.opts) { const def = (o.def !== undefined && o.def !== false) ? ` (默认 ${JSON.stringify(o.def)})` : '' lines.push(` - \`${o.flags}\`${o.desc ? ' — ' + o.desc : ''}${def}`) } } lines.push('') } const outPath = join(getCcWorkDir(), '.claude/skills/ssw-loop/references/command-reference.generated.md') writeFileSync(outPath, lines.join('\n'), 'utf-8') console.log(`✓ 生成 ${docs.length} 条命令 → ${outPath}`)