Files
dacli/src/commands/doc/toc.ts
T

56 lines
2.1 KiB
TypeScript

/**
* commands/doc/toc.ts — 列 HTML 文档的 section 目录
*
* v0.11+ P0 新增: AI 上下文恢复时, 先 toc 看清单再精准 get --section=<id>
* 解决 "AI 必须 get 全文再 grep" 的 token 浪费问题
*/
import { Command } from 'commander'
import { resolve } from 'node:path'
import { existsSync } from 'node:fs'
import { installAiHelpHook } from '../../core/help.ts'
import { log, printJson } from '../../core/log.ts'
import { listSections } from './_parser.ts'
interface Opts { file: string; json?: boolean }
export function buildDocTocCommand(): Command {
const cmd = new Command('toc')
.description('列 HTML/MD 文件的所有 section (id + title + 行数)')
.requiredOption('--file <f>', 'HTML/MD 文件路径 (相对 docs/ 或绝对)')
.option('--json', '原始 JSON 输出', false)
.action(async (opts: Opts) => {
const target = resolve(process.cwd(), opts.file)
if (!existsSync(target)) {
log.error(`文件不存在: ${target}`)
process.exit(1)
}
const sections = listSections(target)
if (opts.json) {
printJson({ file: opts.file, sections })
return
}
log.info(`文件 ${opts.file} 共 ${sections.length} 个 section`)
console.log('ID'.padEnd(40) + 'TITLE'.padEnd(50) + 'LINES')
console.log('-'.repeat(95))
for (const s of sections) {
console.log(`${s.id.padEnd(40)}${(s.title || '').padEnd(50)}${s.lines}`)
}
log.info(`\n💡 用法: dacli doc get --file=${opts.file} --section=<id>`)
})
installAiHelpHook(cmd, {
purpose: '列 HTML 文件 section 清单 (P0 上下文恢复核心), AI 精准切片避免全文 Read',
required: { '--file': 'HTML 文件路径' },
optional: { '--json': '原始 JSON 输出' },
example: [
'dacli doc toc --file=docs/tds/plan.html',
'dacli doc toc --file=docs/tds/design.html --json',
],
notes: [
'v0.11+ 新增, 解决 plan.html > 300 行时 AI 盲找 section 浪费 token',
'依赖 _parser.ts 的 listSections(), 复用 mtime 缓存',
],
})
return cmd
}