Files
dacli/docs/cmd-review/doc.md
T
ssw b9b64dea90 feat: 重命名 ssw-h5dev-flow → ssw-loop (跨 2 仓库)
.claude 仓库:
- git mv skills/ssw-h5dev-flow → skills/ssw-loop (保留 history)
- 改 SKILL.md frontmatter (name + description 触发词)
- 改 5 个 references + 3 个子代理 prompt 模板 + learnings.md.tmpl
- 改 templates/html/style.css + script.js 注释
- 改 scripts/scaffold.sh + 4 个 check 脚本路径
- 改其他 skill 引用: dacli-ts/SKILL.md + anti-patterns.md, no-spa-page/SKILL.md, jnpf-browser-automation/SKILL.md
- 改 CLAUDE.md §技能索引 + §开发流程 + §问题处理
- 改 .claude/templates/flow-jxcj-rerun-process.md + .claude/settings.local.json (allow list)

dacli 仓库:
- 改 src/commands/doc/_parser.ts + list.ts 注释 (提及 ssw-loop plan/debug/research 走 MD)
- 改 tests/unit/doc-md-slice.test.ts 注释
- 改 docs/尚数网基本开发规范v3.0.md (7 处引用)
- git mv docs/skill-audit/ssw-h5dev-flow.md → ssw-loop.md (保留 history)
- 改 docs/cmd-review/doc.md

历史保留 (未改, 反映 v0.11 时代状态):
- dacli/docs/v0.11-*.md (4 个 plan 文件)
- docs/dacli/ssw-dacli/ (Java 版归档, 已废弃)
- docs/aibridge/.claude/ (Python 时代)

验证: 14/14 doc-md-slice 测试 PASS
2026-06-29 13:28:52 +08:00

2.7 KiB
Raw Blame History

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 <file> (P0)

  • 当前 doc get --section=<id> 需要 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 <file> --keyword=<kw> (P0)

  • AI 知道想找"BS-48 相关段落"但不知道 section id
  • 当前必须先 get 全文再用 grep,2 步变 1 步
  • 节省 40-60% token

[NEW-CMD] P1

dacli doc slice <file> --heading=<n> (P1)

  • 按 <h2> 标题文本模糊匹配切片
  • 当前降级逻辑生成 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-loop 集成

  • ✅ 已顺畅使用 (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 <file>:列文件 section 清单 (id + title + 行数)
  2. [NEW-CMD P0] dacli doc search --keyword=<kw>:按关键词全文搜索
  3. [OPTIMIZE] 补 dacli doc get --no-cache:mtime 缓存失效时跳过缓存