/** * help.ts — AI 友好帮助体系 * * 用法: 给 Commander.js 命令对象挂元数据 (cmd as any)._aiMeta = meta * 由 cli.ts 顶层在 parse 之前扫 argv 拦截 --ai-help / --example / --source * 打印后 process.exit, 避免命令真正执行 / 校验 requiredOption */ import type { Command } from 'commander' export interface AiHelp { purpose: string required?: Record optional?: Record example?: string | string[] source?: { web?: string; api?: string; ref?: string } notes?: string[] } const AI_FLAGS = new Set(['--ai-help', '--example', '--source']) /** 把元数据挂到 command 上, cli.ts 顶层会读 */ export function installAiHelpHook(cmd: Command, meta: AiHelp): void { ;(cmd as unknown as { _aiMeta?: AiHelp })._aiMeta = meta } function getMeta(cmd: Command): AiHelp | undefined { return (cmd as unknown as { _aiMeta?: AiHelp })._aiMeta } /** * 顶层在 parse 前调用. 命中 ai flag 则打印 + exit, 返回 true. */ export function maybeInterceptAiHelp(program: Command): boolean { const argv = process.argv.slice(2) const flagIdx = argv.findIndex((a) => AI_FLAGS.has(a)) if (flagIdx < 0) return false const flag = argv[flagIdx] // 把 flag 之前的非选项 token 当成命令路径 const path = argv.slice(0, flagIdx).filter((a) => !a.startsWith('-')) // 走命令树 let cur: Command = program for (const p of path) { const sub = cur.commands.find( (c) => c.name() === p || (c.aliases() as string[]).includes(p), ) if (!sub) break cur = sub } const meta = getMeta(cur) if (!meta) { console.error(`(no ai-help for: ${path.join(' ') || ''})`) process.exit(2) } if (flag === '--example') { const ex = Array.isArray(meta.example) ? meta.example.join('\n') : meta.example || '(no example)' console.log(ex) } else if (flag === '--source') { const lines: string[] = [] if (meta.source?.web) lines.push(`web: ${meta.source.web}`) if (meta.source?.api) lines.push(`api: ${meta.source.api}`) console.log(lines.join('\n') || '(no source)') } else { console.log(renderAiHelp(cur, meta)) } process.exit(0) } function renderAiHelp(cmd: Command, meta: AiHelp): string { const lines: string[] = [] // 拼出完整路径 const path: string[] = [cmd.name()] let p: Command | null = cmd.parent as Command | null while (p) { path.unshift(p.name()) p = p.parent as Command | null } // 去 root 名 const fullCmd = path.slice(1).join(' ') || path[0] lines.push(`# dacli ${fullCmd}`) lines.push('') lines.push('## 用途') lines.push(meta.purpose) if (meta.required && Object.keys(meta.required).length) { lines.push('') lines.push('## 必传参数') for (const [k, v] of Object.entries(meta.required)) lines.push(`- \`${k}\`: ${v}`) } if (meta.optional && Object.keys(meta.optional).length) { lines.push('') lines.push('## 可选参数') for (const [k, v] of Object.entries(meta.optional)) lines.push(`- \`${k}\`: ${v}`) } if (meta.source?.web || meta.source?.api) { lines.push('') lines.push('## 来源') if (meta.source.web) lines.push(`- web 源码: ${meta.source.web}`) if (meta.source.api) lines.push(`- API: ${meta.source.api}`) } if (meta.example) { lines.push('') lines.push('## 例子') lines.push('```bash') lines.push(Array.isArray(meta.example) ? meta.example.join('\n') : meta.example) lines.push('```') } if (meta.notes && meta.notes.length) { lines.push('') lines.push('## 注意') for (const n of meta.notes) lines.push(`- ${n}`) } return lines.join('\n') }