Files
dacli/docs/cmd-review/doc.md
T
sswandClaude b9c9e318af feat(v0.11+): Phase 1 - 23 个 dacli 父命令审计完成
派 25 个 Explore 子代理 (5 批 × 5) 审计 23 个父命令.
产出 cmd-review/{cmd}.md (24 文件) + _summary.md.

关键发现:
- webapi 镜像使用率 < 30% (12+ 父命令 100% 绕 webapi)
- 30+ P0 必补新命令 (form update, log exception, di CRUD, role authorize 等)
- 3 处 P0 端点错误 (假 PASS):
  * integration emailTest/smsTest
  * msg templateCreate
- 用户关键修正: bigscreen → jnpf-web-datascreen-vue3 (独立子项目)
- 用户关键修正: report → jnpf-web-datareport (独立子项目)

下一步: Phase 2 按 P0 优先级执行 (修端点 + 新命令 + webapi 化)

Co-Authored-By: Claude <[email protected]>
2026-06-25 14:58:32 +08:00

69 lines
2.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-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 <file>`**:列文件 section 清单 (id + title + 行数)
2. **[NEW-CMD P0] `dacli doc search --keyword=<kw>`**:按关键词全文搜索
3. **[OPTIMIZE] 补 `dacli doc get --no-cache`**:mtime 缓存失效时跳过缓存