.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
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# 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 缓存失效时跳过缓存
|