fix(dacli): restore dual-path installHelpHook + preserve _aiMeta + update docs
This commit is contained in:
1 parent
38c6fe6ae2
commit
96fbbdf1c0
1 file changed
+40
-7
+40
-7
@@ -1,9 +1,15 @@
|
||||
/**
|
||||
* help.ts — AI 友好帮助体系
|
||||
* dacli --help system: 知识落地到 CLI 自己 (Phase 1 改造).
|
||||
*
|
||||
* 用法: 给 Commander.js 命令对象挂元数据 (cmd as any)._aiMeta = meta
|
||||
* 由 cli.ts 顶层在 parse 之前扫 argv 拦截 --ai-help / --example / --source
|
||||
* 打印后 process.exit, 避免命令真正执行 / 校验 requiredOption
|
||||
* 架构 (v0.22+):
|
||||
* - DacliHelp interface (Task 1.1): 含 4 新字段 pitfalls/bestPractices/decisionTree/relatedRefs
|
||||
* - renderDacliHelp() (Task 1.2): 把 DacliHelp 序列化为 addHelpText 文本
|
||||
* - installHelpHook() (Task 1.3): 双路径注入 — .description(purpose) + .addHelpText('after', ...)
|
||||
*
|
||||
* Legacy compat (Task 1.6 将清理):
|
||||
* - installAiHelpHook = installHelpHook (alias for source-compat during migration)
|
||||
* - _aiMeta 副作用保留到 Task 1.6 删 --ai-help flag 时
|
||||
* - AI_FLAGS / getMeta / maybeInterceptAiHelp / renderAiHelp 是遗留代码
|
||||
*/
|
||||
import type { Command } from 'commander'
|
||||
|
||||
@@ -117,11 +123,38 @@ export function renderDacliHelp(help: DacliHelp): string {
|
||||
|
||||
const AI_FLAGS = new Set(['--ai-help', '--example', '--source'])
|
||||
|
||||
/** 把元数据挂到 command 上, cli.ts 顶层会读 */
|
||||
export function installAiHelpHook(cmd: Command, meta: DacliHelp): void {
|
||||
;(cmd as unknown as { _aiMeta?: DacliHelp })._aiMeta = meta
|
||||
/**
|
||||
* 把 DacliHelp 注入 Commander 命令的 --help 输出.
|
||||
* 替换旧的 installAiHelpHook, 单 flag --help 包含所有信息.
|
||||
*
|
||||
* - `purpose` 走 Commander 的 `.description()`, 出现在 Usage 之后 Options 之前
|
||||
* (Commander `helpInformation()` 内置可见)
|
||||
* - 其他字段 (example/source/pitfalls/bestPractices/decisionTree/relatedRefs/notes)
|
||||
* 走 `addHelpText('after', ...)`, 出现在 Options 之后
|
||||
* (Commander `helpInformation()` 不内置, 仅 `outputHelp()` / `--help` 实际输出可见)
|
||||
*
|
||||
* Legacy compat transitional behavior (Task 1.6 将清理):
|
||||
* - 同时设置 `(cmd as any)._aiMeta = help`, 以保留 ~170 个旧 call site 的
|
||||
* `--ai-help` / `--example` / `--source` flag 拦截逻辑 (由 maybeInterceptAiHelp 读取).
|
||||
* - Task 1.6 删除 --ai-help 系列 flag 时, 可同步删此行.
|
||||
*/
|
||||
export function installHelpHook(command: Command, help: DacliHelp): void {
|
||||
// Primary path: dual-path Commander integration (purpose + addHelpText)
|
||||
command.description(help.purpose)
|
||||
|
||||
const rendered = renderDacliHelp(help)
|
||||
if (rendered.trim().length > 0) {
|
||||
command.addHelpText('after', `\n${rendered}`)
|
||||
}
|
||||
|
||||
// Legacy compat: preserve _aiMeta side effect for --ai-help/--example/--source
|
||||
// flag interception. Task 1.6 will delete this and the interceptor.
|
||||
;(command as unknown as { _aiMeta?: DacliHelp })._aiMeta = help
|
||||
}
|
||||
|
||||
/** Backward-compat alias during migration */
|
||||
export const installAiHelpHook = installHelpHook
|
||||
|
||||
function getMeta(cmd: Command): DacliHelp | undefined {
|
||||
return (cmd as unknown as { _aiMeta?: DacliHelp })._aiMeta
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user