diff --git a/src/commands/doc/index.ts b/src/commands/doc/index.ts index e339be8..6dce3a1 100644 --- a/src/commands/doc/index.ts +++ b/src/commands/doc/index.ts @@ -2,14 +2,19 @@ * commands/doc/index.ts — doc 父命令 (HTML 文档) * * v0.7+: 2 子命令 (list/get) + mtime 缓存 (_parser.ts) + * v0.11+: 4 子命令 (list/get/toc/search) — toc/search P0 上下文恢复 */ import { Command } from 'commander' import { buildDocListCommand } from './list.ts' import { buildDocGetCommand } from './get.ts' +import { buildDocTocCommand } from './toc.ts' +import { buildDocSearchCommand } from './search.ts' export function buildDocCommand(): Command { const cmd = new Command('doc').description('HTML 文档 (从 docs/{app}/ 扫描, mtime 缓存)') cmd.addCommand(buildDocListCommand()) cmd.addCommand(buildDocGetCommand()) + cmd.addCommand(buildDocTocCommand()) + cmd.addCommand(buildDocSearchCommand()) return cmd } diff --git a/src/commands/doc/search.ts b/src/commands/doc/search.ts new file mode 100644 index 0000000..b4da642 --- /dev/null +++ b/src/commands/doc/search.ts @@ -0,0 +1,114 @@ +/** + * commands/doc/search.ts — 按关键词全文搜索 HTML 文档 + * + * v0.11+ P0 新增: AI 知道想找"BS-48 相关段落"但不知道 section id + * 解决 "先 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 { parseFile } from './_parser.ts' + +interface Opts { + file: string + keyword: string + context?: string + json?: boolean + stripMermaid?: boolean +} + +interface Match { sectionId: string; sectionTitle: string; line: number; snippet: string } + +export function buildDocSearchCommand(): Command { + const cmd = new Command('search') + .description('按关键词全文搜索 HTML 文档 (输出含关键词的 section + 上下文)') + .requiredOption('--file ', 'HTML 文件路径') + .requiredOption('--keyword ', '搜索关键词 (支持正则)') + .option('--context ', '上下文行数 (默认 3)', '3') + .option('--strip-mermaid', '去除 Mermaid 代码块', false) + .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 ctx = parseInt(opts.context || '3', 10) + const { sections, fullText } = parseFile(target, opts.stripMermaid || false) + + let re: RegExp + try { + re = new RegExp(opts.keyword, 'i') + } catch (e) { + log.error(`--keyword 不是有效正则: ${(e as Error).message}`) + process.exit(2) + } + + const matches: Match[] = [] + for (const sec of sections.values()) { + const lines = sec.text.split('\n') + for (let i = 0; i < lines.length; i++) { + if (re.test(lines[i])) { + const from = Math.max(0, i - ctx) + const to = Math.min(lines.length, i + ctx + 1) + const snippet = lines + .slice(from, to) + .map((l, idx) => { + const lineNo = from + idx + 1 + const marker = from + idx === i ? '>' : ' ' + return `${marker} ${lineNo}: ${l}` + }) + .join('\n') + matches.push({ + sectionId: sec.id, + sectionTitle: sec.title, + line: i + 1, + snippet, + }) + } + } + } + + if (opts.json) { + printJson({ file: opts.file, keyword: opts.keyword, matchCount: matches.length, matches }) + return + } + + log.info(`文件 ${opts.file} 关键词 "${opts.keyword}" 匹配 ${matches.length} 处`) + if (matches.length === 0) { + log.warn('无匹配') + return + } + let currentSection = '' + for (const m of matches) { + if (m.sectionId !== currentSection) { + console.log(`\n[${m.sectionId}] ${m.sectionTitle}`) + console.log('-'.repeat(80)) + currentSection = m.sectionId + } + console.log(m.snippet) + console.log() + } + }) + + installAiHelpHook(cmd, { + purpose: '按关键词全文搜索 HTML 文档, 避免 get 全文再 grep 的 token 浪费', + required: { '--file': 'HTML 文件路径', '--keyword': '搜索关键词 (支持正则)' }, + optional: { + '--context': '上下文行数 (默认 3)', + '--strip-mermaid': '去除 Mermaid 代码块', + '--json': '原始 JSON 输出', + }, + example: [ + 'dacli doc search --file=docs/tds/plan.html --keyword="BS-48"', + 'dacli doc search --file=docs/tds/design.html --keyword="dbLinkId" --context=5', + ], + notes: [ + 'v0.11+ 新增, 解决 plan.html 几百行时 AI 盲找关键词浪费 token', + '依赖 _parser.ts 的 parseFile(), 复用 mtime 缓存', + ], + }) + return cmd +} diff --git a/src/commands/doc/toc.ts b/src/commands/doc/toc.ts new file mode 100644 index 0000000..dc8560a --- /dev/null +++ b/src/commands/doc/toc.ts @@ -0,0 +1,55 @@ +/** + * commands/doc/toc.ts — 列 HTML 文档的 section 目录 + * + * v0.11+ P0 新增: AI 上下文恢复时, 先 toc 看清单再精准 get --section= + * 解决 "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 文件的所有 section (id + title + 行数)') + .requiredOption('--file ', 'HTML 文件路径 (相对 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=`) + }) + + 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 +}