114 lines
3.6 KiB
TypeScript
114 lines
3.6 KiB
TypeScript
/**
|
|
* 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<string, string>
|
|
optional?: Record<string, string>
|
|
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(' ') || '<root>'})`)
|
|
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')
|
|
}
|