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:
1 parent
90a8b4eecb
commit
5f663eb494
3 files changed
+174
No files matched your search
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
Reference in new issue
Block a user