# dacli `doc` 命令审计报告 (2026-06-25) ## 1. 命令清单 | 子命令 | 格式 | 用途 | |--------|------|------| | `dacli doc list` | `[--dir] [--json]` | 列 HTML 文档 (从 docs/{app_code}/ 扫描) | | `dacli doc get` | `--file [--section\|--from --lines] [--strip-mermaid] [--json]` | 读 HTML section/行号纯文本 (P0 上下文恢复核心) | ## 2. web 端对应 - **无 web API 对应**:`doc` 是本地 HTML 文件解析工具,不直接调用 JNPF web API - **HTML 文档源**:`docs/{app_code}/plan.html` (设计计划) + `design.html` (UI 设计) + `testcase.html` (测试用例) + `summary.html` (交付摘要) - **缓存层**:`~/.dacli/cache.db` (SQLite) + mtime 缓存策略 (7 天 TTL) ## 3. 改/删/留 建议 ### [KEEP] 保留 - **dacli doc list** — AI 上下文恢复第一步 - **dacli doc get** — P0 上下文恢复核心 ### [REFACTOR-WEBAPI] 不适用 本地 HTML 解析工具,不调用 web API ### [DEPRECATE] 无 ### [NEW-CMD] **P0 高优先级** #### `dacli doc toc ` (P0) - 当前 `doc get --section=` 需要 AI 先知道 section id - plan.html / design.html 通常 > 300 行,AI trial-and-error 找 section 浪费 token - 示例痛点:`docs/tds/design.html` 有 10+ sections, AI 需先 `toc` 看清单才能精准切片 #### `dacli doc search --keyword=` (P0) - AI 知道想找"BS-48 相关段落"但不知道 section id - 当前必须先 `get` 全文再用 grep,2 步变 1 步 - 节省 40-60% token ### [NEW-CMD] P1 #### `dacli doc slice --heading=` (P1) - 按 `

` 标题文本模糊匹配切片 - 当前降级逻辑生成 `h2_0`, `h2_1` 无意义 id ## 4. AI 痛点评估 ### plan.html 切片痛点 - 量化: `docs/tds/plan.html` 168 行 (11K), `docs/tds/design.html` 537 行 (22K) - 当前 `doc get` 覆盖:`--section` 精准切片 + `--from --lines` 行号切片 - ⚠️ 缺按关键词搜索 ### mtime 缓存失效 (已知盲点 errors.md #23) - IDE 自动保存 / git checkout 导致 mtime 频繁变化 - 建议新增 `--no-cache` flag 跳过缓存 (紧急场景) ### ssw-h5dev-flow 集成 - ✅ 已顺畅使用 (skill 文档明确指引) - ⚠️ skill 文档未提及 `doc toc` / `doc search` (如新增需补充) - ⚠️ skill 文档未提及 mtime 缓存陷阱 --- **核心结论**: `dacli doc` 是纯本地 HTML 文档工具,架构清晰、功能合理 (list + get 双子命令),但 AI 上下文恢复场景下缺 2 个关键命令 (toc + search)。 **3 个最关键建议**: 1. **[NEW-CMD P0] `dacli doc toc `**:列文件 section 清单 (id + title + 行数) 2. **[NEW-CMD P0] `dacli doc search --keyword=`**:按关键词全文搜索 3. **[OPTIMIZE] 补 `dacli doc get --no-cache`**:mtime 缓存失效时跳过缓存