From d4cc3d09db7e31a5d8ae260ed8e1ee7e6d795ba0 Mon Sep 17 00:00:00 2001 From: ssw Date: Fri, 24 Jul 2026 11:45:30 +0800 Subject: [PATCH] =?UTF-8?q?feat(ssw-loop):=20P7=20=E2=80=94=20generate=20c?= =?UTF-8?q?ommand=20reference=20from=20commander=20tree=20(kill=20drift)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per DESIGN §6 / user catch: ssw-loop subagent templates hand-code dacli command syntax and drift (typ. missing --category). Command tree is now the single source. - src/program.ts: extract buildProgram() (assembles commander tree, no parse/side-effect) - src/cli.ts: slimmed to import buildProgram() + parse + top-level error handling - scripts/gen-command-reference.ts: walk tree → .claude/.../command-reference.generated.md (190 commands w/ all options + defaults, incl --category/--column-naming) Verified: tsc 0; cli entry smoke (form list) intact after refactor; generator emits 190 commands. (.claude side: generated ref + drift-check committed separately.) Co-Authored-By: Claude --- scripts/gen-command-reference.ts | 80 +++++++++++++++++++++++++++ src/cli.ts | 95 ++------------------------------ src/program.ts | 79 ++++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 91 deletions(-) create mode 100644 scripts/gen-command-reference.ts create mode 100644 src/program.ts diff --git a/scripts/gen-command-reference.ts b/scripts/gen-command-reference.ts new file mode 100644 index 0000000..d71d661 --- /dev/null +++ b/scripts/gen-command-reference.ts @@ -0,0 +1,80 @@ +/** + * 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}`) diff --git a/src/cli.ts b/src/cli.ts index 250f2ec..a28f52b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -4,102 +4,15 @@ * * 调用: `npx tsx src/cli.ts ` 或 `node --import tsx src/cli.ts ` * - * 设计: 嵌套子命令 (form/menu/dm/dict/workflow/doc/apis 父命令 + 子命令) - * AI 友好: 每个命令支持 --ai-help / --example / --source + * 设计: 命令树在 src/program.ts 组装 (buildProgram, 无副作用), + * 本文件只负责 parse + 顶层错误处理。 */ -import { Command } from 'commander' -import { buildFormCommand } from './commands/form/index.ts' -import { buildDmCommand } from './commands/dm/index.ts' -import { buildDictCommand } from './commands/dict/index.ts' -import { buildMenuCommand } from './commands/menu/index.ts' -import { buildDiCommand } from './commands/di/index.ts' -import { buildWorkflowCommand } from './commands/workflow/index.ts' -import { buildDocCommand } from './commands/doc/index.ts' -import { buildApisCommand } from './commands/apis/index.ts' -import { buildDatasourceCommand } from './commands/datasource/index.ts' -import { buildReportCommand } from './commands/report/index.ts' -import { buildPortalCommand } from './commands/portal/index.ts' -import { buildBigscreenCommand } from './commands/bigscreen/index.ts' -import { buildAppCommand } from './commands/app/index.ts' -import { buildPrintCommand } from './commands/print/index.ts' -import { buildRoleCommand } from './commands/role/index.ts' -import { buildUserCommand } from './commands/user/index.ts' -import { buildOrgCommand } from './commands/org/index.ts' -import { buildMsgCommand } from './commands/msg/index.ts' -import { buildScheduleCommand } from './commands/schedule/index.ts' -import { buildMonitorCommand } from './commands/monitor/index.ts' -import { buildLogCommand } from './commands/log/index.ts' -import { buildIntegrationCommand } from './commands/integration/index.ts' -import { buildStorageCommand } from './commands/storage/index.ts' -import { buildTestCommand } from './commands/test/index.ts' -import { buildSelfCheckCommand } from './commands/_selfcheck.ts' -import { buildDriftCheckCommand } from './commands/_drift_check.ts' -import { buildCoverageCommand } from './commands/_coverage.ts' -import { buildKbCommand } from './commands/kb/index.ts' +import { buildProgram } from './program.ts' import { log } from './core/log.ts' import { DacliError } from './core/types.ts' -const VERSION = '0.1.0' - -const program = new Command() - .name('dacli') - .description('dacli (TS 版) — AI 驱动的 JNPF CLI. ') - .version(VERSION) - .showHelpAfterError(true) - -// ----- 嵌套父命令 ----- -// v0.9 命名规范化: 顶层命令全部归入 app 命名空间 -// dacli login → dacli app login -// dacli status → dacli app status -// dacli switchapp → dacli app switch -// dacli initapp → dacli app init -program.addCommand(buildFormCommand()) -program.addCommand(buildDmCommand()) -program.addCommand(buildDictCommand()) -program.addCommand(buildMenuCommand()) -program.addCommand(buildDiCommand()) -program.addCommand(buildWorkflowCommand()) -program.addCommand(buildDocCommand()) -program.addCommand(buildApisCommand()) -// v0.8 W7-D3 新增 4 父命令 -program.addCommand(buildDatasourceCommand()) -program.addCommand(buildReportCommand()) -program.addCommand(buildPortalCommand()) -program.addCommand(buildBigscreenCommand()) -// v0.8 W9-D1 新增 1 父命令 -program.addCommand(buildAppCommand()) -// v0.8 W9-D3 新增 1 父命令 -program.addCommand(buildPrintCommand()) -// v0.8 W10-D1 新增 1 父命令 -program.addCommand(buildRoleCommand()) -// v0.8 W10-D2 新增 1 父命令 -program.addCommand(buildUserCommand()) -// v0.8 W10-D3 新增 1 父命令 -program.addCommand(buildOrgCommand()) -// v0.8 W11-D1 新增 1 父命令 -program.addCommand(buildMsgCommand()) -// v0.8 W11-D2 新增 1 父命令 -program.addCommand(buildScheduleCommand()) -// v0.8 W12 新增 3 P2 父命令 -program.addCommand(buildMonitorCommand()) -program.addCommand(buildLogCommand()) -program.addCommand(buildIntegrationCommand()) -program.addCommand(buildStorageCommand()) -// v0.11+ NEW: test (API 模拟录入 → 沉淀, 替代 tests/test-*.ts 散落脚本) -program.addCommand(buildTestCommand()) - -// v0.11d+ Phase 4.1: selfcheck (v0.11d+ 强制纪律自检, AI 场景补充) -program.addCommand(buildSelfCheckCommand()) - -// v0.11e+ Phase D2: drift-check + coverage (验证强化) -program.addCommand(buildDriftCheckCommand()) -program.addCommand(buildCoverageCommand()) - -// v0.16+ Phase KB: PostgreSQL-backed knowledge base (auto date/expiry/search filter) -program.addCommand(buildKbCommand()) - // ----- main ----- -program.parseAsync(process.argv).catch((err: unknown) => { +buildProgram().parseAsync(process.argv).catch((err: unknown) => { if (err instanceof DacliError) { log.error(`${err.message}`) if (err.raw && process.env.DACLI_DEBUG === '1') log.dim(err.raw) diff --git a/src/program.ts b/src/program.ts new file mode 100644 index 0000000..afdbdb1 --- /dev/null +++ b/src/program.ts @@ -0,0 +1,79 @@ +/** + * program.ts — 组装 commander 命令树 (与 CLI 入口解耦, P7 2026-07-24) + * + * cli.ts 从这里拿 buildProgram() 后 parseAsync; + * scripts/gen-command-reference.ts 也从这里拿, 遍历命令树生成 ssw-loop 模板参考 + * (模板从 --help 生成, 永不漂移 — DESIGN §6)。 + * 关键: 本文件只组装、不 parse, import 无副作用。 + */ +import { Command } from 'commander' +import { buildFormCommand } from './commands/form/index.ts' +import { buildDmCommand } from './commands/dm/index.ts' +import { buildDictCommand } from './commands/dict/index.ts' +import { buildMenuCommand } from './commands/menu/index.ts' +import { buildDiCommand } from './commands/di/index.ts' +import { buildWorkflowCommand } from './commands/workflow/index.ts' +import { buildDocCommand } from './commands/doc/index.ts' +import { buildApisCommand } from './commands/apis/index.ts' +import { buildDatasourceCommand } from './commands/datasource/index.ts' +import { buildReportCommand } from './commands/report/index.ts' +import { buildPortalCommand } from './commands/portal/index.ts' +import { buildBigscreenCommand } from './commands/bigscreen/index.ts' +import { buildAppCommand } from './commands/app/index.ts' +import { buildPrintCommand } from './commands/print/index.ts' +import { buildRoleCommand } from './commands/role/index.ts' +import { buildUserCommand } from './commands/user/index.ts' +import { buildOrgCommand } from './commands/org/index.ts' +import { buildMsgCommand } from './commands/msg/index.ts' +import { buildScheduleCommand } from './commands/schedule/index.ts' +import { buildMonitorCommand } from './commands/monitor/index.ts' +import { buildLogCommand } from './commands/log/index.ts' +import { buildIntegrationCommand } from './commands/integration/index.ts' +import { buildStorageCommand } from './commands/storage/index.ts' +import { buildTestCommand } from './commands/test/index.ts' +import { buildSelfCheckCommand } from './commands/_selfcheck.ts' +import { buildDriftCheckCommand } from './commands/_drift_check.ts' +import { buildCoverageCommand } from './commands/_coverage.ts' +import { buildKbCommand } from './commands/kb/index.ts' + +export const VERSION = '0.1.0' + +/** 组装完整 commander 命令树 (不 parse) */ +export function buildProgram(): Command { + const program = new Command() + .name('dacli') + .description('dacli (TS 版) — AI 驱动的 JNPF CLI. ') + .version(VERSION) + .showHelpAfterError(true) + + program.addCommand(buildFormCommand()) + program.addCommand(buildDmCommand()) + program.addCommand(buildDictCommand()) + program.addCommand(buildMenuCommand()) + program.addCommand(buildDiCommand()) + program.addCommand(buildWorkflowCommand()) + program.addCommand(buildDocCommand()) + program.addCommand(buildApisCommand()) + program.addCommand(buildDatasourceCommand()) + program.addCommand(buildReportCommand()) + program.addCommand(buildPortalCommand()) + program.addCommand(buildBigscreenCommand()) + program.addCommand(buildAppCommand()) + program.addCommand(buildPrintCommand()) + program.addCommand(buildRoleCommand()) + program.addCommand(buildUserCommand()) + program.addCommand(buildOrgCommand()) + program.addCommand(buildMsgCommand()) + program.addCommand(buildScheduleCommand()) + program.addCommand(buildMonitorCommand()) + program.addCommand(buildLogCommand()) + program.addCommand(buildIntegrationCommand()) + program.addCommand(buildStorageCommand()) + program.addCommand(buildTestCommand()) + program.addCommand(buildSelfCheckCommand()) + program.addCommand(buildDriftCheckCommand()) + program.addCommand(buildCoverageCommand()) + program.addCommand(buildKbCommand()) + + return program +}