Files
dacli/src/core/help.ts
T

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')
}