feat(v0.11+): doc toc + doc search P0 新命令 (上下文恢复)

Phase 1 审计 (cmd-review/doc.md) 标记 P0 必补:
- 解决 plan.html 几百行时 AI 盲找 section 浪费 token
- 解决 AI 必须 get 全文再 grep 的 token 浪费 (节省 40-60%)

新增 2 子命令:
1. dacli doc toc --file=<f> [--json]
   - 列 HTML 文件所有 section (id + title + 行数)
   - 依赖 _parser.ts listSections(), 复用 mtime 缓存
   - AI 工作流: toc → get --section=<id> 精准切片

2. dacli doc search --file=<f> --keyword=<kw> [--context=N] [--strip-mermaid]
   - 按关键词全文搜索, 输出含关键词的 section + 上下文
   - 依赖 _parser.ts parseFile(), 复用 mtime 缓存
   - 支持正则, --context 上下文行数可调

测试: 跑 v0.11-next-steps-plan.md 验证, 25 处 webapi 匹配全捕获

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-06-25 15:02:27 +08:00
1 parent 90a8b4eecb
commit 5f663eb494
3 files changed
+174

No files matched your search

+5
View File
@@ -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
}
+114
View File
@@ -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 <f>', 'HTML 文件路径')
.requiredOption('--keyword <kw>', '搜索关键词 (支持正则)')
.option('--context <n>', '上下文行数 (默认 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
}
+55
View File
@@ -0,0 +1,55 @@
/**
* 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 文件的所有 section (id + title + 行数)')
.requiredOption('--file <f>', '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=<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
}