From 0b937d63d22eb03147ec0ff01bb0b79d4ae36376 Mon Sep 17 00:00:00 2001 From: ssw Date: Fri, 12 Jun 2026 18:14:48 +0800 Subject: [PATCH] auto(6f177c177d02): session end @ 2026-06-12T18:14:48 (+17f) --- CLAUDE.md | 39 +- hooks/init.sh | 22 +- hooks/pre-tool-use.js | 1 - settings.local.json | 1 - skills/.DS_Store | Bin 10244 -> 10244 bytes skills/dacli-architecture/SKILL.md | 349 ---- .../references/dacli-conf-usage.md | 140 -- skills/dacli-codegraph/SKILL.md | 293 ---- skills/dacli-doc-cache/SKILL.md | 178 -- skills/design-jnpf-execute/SKILL.md | 1442 ----------------- .../references/c56-old-convention-tool.md | 85 - .../references/c57-p27-workaround.md | 85 - .../references/c58-v11-todo.md | 241 --- .../references/subagent-prompts.md | 268 --- .../polish-convention.cpython-312.pyc | Bin 20042 -> 0 bytes .../scripts/create_form.py | 245 --- .../scripts/create_subtable_form.py | 309 ---- .../scripts/create_workflow_form.py | 246 --- .../scripts/polish-convention.py | 396 ----- 19 files changed, 33 insertions(+), 4307 deletions(-) delete mode 100644 skills/dacli-architecture/SKILL.md delete mode 100644 skills/dacli-architecture/references/dacli-conf-usage.md delete mode 100644 skills/dacli-codegraph/SKILL.md delete mode 100644 skills/dacli-doc-cache/SKILL.md delete mode 100644 skills/design-jnpf-execute/SKILL.md delete mode 100644 skills/design-jnpf-execute/references/c56-old-convention-tool.md delete mode 100644 skills/design-jnpf-execute/references/c57-p27-workaround.md delete mode 100644 skills/design-jnpf-execute/references/c58-v11-todo.md delete mode 100644 skills/design-jnpf-execute/references/subagent-prompts.md delete mode 100644 skills/design-jnpf-execute/scripts/__pycache__/polish-convention.cpython-312.pyc delete mode 100644 skills/design-jnpf-execute/scripts/create_form.py delete mode 100644 skills/design-jnpf-execute/scripts/create_subtable_form.py delete mode 100644 skills/design-jnpf-execute/scripts/create_workflow_form.py delete mode 100755 skills/design-jnpf-execute/scripts/polish-convention.py diff --git a/CLAUDE.md b/CLAUDE.md index 8f976ca..297db81 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,11 +48,15 @@ > **架构演进 (2026-06-06)**:1) **Redis → SQLite 迁移**(`SqliteCacheService` 替代 `RedisCacheService`,缓存文件 `~/.dacli/cache.db`,无需外部 Redis 容器);2) **GraalVM Native 编译**(启动 800ms→100ms,输出 `target/dacli` 原生二进制);3) **dacli codegraph 新增**(基于 `codegraph.db` 静态分析 JNPF 源码,7 子命令:search/calls/trace/impact/contains/implements/route)。 > > **dacli form 高频能力内化 (2026-06-09)**:高频场景已直接做进 `dacli form create` 参数:`--webType=4`(视图,无物理表)/ `--enableFlow=1 --flowId=X`(工作流绑定)/ `--fields` JSON 加 `interfaceId`(数据接口字段)。**`form template` 子命令族已下线**——长尾场景(联动/JS增强/列表样式/套打/i18n)由 `form-development` 技能里的速查表指引:找 ID → `dacli form info ` 读结构 → 仿造。备份/迁移用 `form export/import`,结构修复用 `form fix`。 +> +> **dacli 迁移到 TS 版 (2026-06-12)**:Java 版(`boot/ssw-dacli/`,261 mvn test 已成熟)已**废弃**,源码归档到 `docs/dacli/ssw-dacli/` 备查(无 `target/`,需手动 `mvn package` 才能跑 jar)。**当前 CLI 改用 TS 版**(`$ccWorkDir/dacli/`,v0.7,8 父命令 / 26+ 子命令,启动 < 500ms)。TS 版功能对照见 `.claude/skills/dacli-ts/SKILL.md` v0.7 校准段。Java 版仅在 TS 版没实现的边缘场景(报表/门户/portal/codegen)兜底。 -### 别名配置 +### 别名配置(TS 版) ```bash -alias dacli='java -jar $ccWorkDir/boot/ssw-dacli/target/ssw-dacli-*.jar' +alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts' ``` +> 首次使用:`cd $ccWorkDir/dacli && npm install` +> 项目结构变更:原 `test/dacli/` 升级为 `$ccWorkDir/dacli/`(顶层独立项目)。 ### 常用命令 ```bash @@ -320,19 +324,26 @@ $ccWorkDir/ │ └── skills/ # 技能定义 ├── boot/ # 后端 Spring Boot │ ├── jnpf-admin/ # 主模块 -│ ├── ssw-dacli/ # CLI工具(独立JAR) │ └── ssw-{app_code}/ # 业务模块 +├── dacli/ # ✅ TS 版 dacli (v0.7, 0 差错 baseline) +│ ├── src/ # CLI 源码 (npx tsx src/cli.ts) +│ ├── tests/ # vitest + Playwright +│ ├── doc/ # 架构/plan/api/extractors 等文档 +│ ├── .claude/skills/dacli-ts/ # 教 AI 何时用哪个命令 +│ └── package.json ├── web/ # 前端 Vue3 ├── test/ # E2E测试 (Playwright) ├── jnpf/ # jnpf开发平台源代码 ├── docs/ # 文档 -│ └── {app_code}/ # 应用文档(HTML输出) -│ ├── assets/ # CSS/JS/Mermaid -│ ├── design.html # 详细设计方案 -│ ├── testcase.html # 测试用例 -│ ├── plan.html # 开发计划(上下文恢复用) -│ ├── debug.html # 问题记录 -│ └── summary.html # 总结报告 +│ ├── {app_code}/ # 应用文档(HTML输出) +│ │ ├── assets/ # CSS/JS/Mermaid +│ │ ├── design.html # 详细设计方案 +│ │ ├── testcase.html # 测试用例 +│ │ ├── plan.html # 开发计划(上下文恢复用) +│ │ ├── debug.html # 问题记录 +│ │ └── summary.html # 总结报告 +│ └── dacli/ +│ └── ssw-dacli/ # 📦 Java 版 dacli 归档(已废弃, 仅备查, 无 target/) ``` --- @@ -343,14 +354,12 @@ $ccWorkDir/ # 编译打包 cd $ccWorkDir/boot && mvn clean package -DskipTests -# 编译 dacli 独立工具 -cd $ccWorkDir/boot && mvn clean package -DskipTests -pl ssw-dacli -am - # 启动 JNPF(Web服务,端口30000) java -jar jnpf-admin/target/jnpf-admin-*.jar --spring.profiles.active=dev -# dacli 使用 -alias dacli='java -jar $ccWorkDir/boot/ssw-dacli/target/ssw-dacli-*.jar' +# dacli 使用(TS 版) +alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts' +cd $ccWorkDir/dacli && npm install # 首次需装依赖 dacli login --account=admin --password=123456 --appCode=developSystem # E2E测试(playwright-cli) diff --git a/hooks/init.sh b/hooks/init.sh index 8760454..1a2e47b 100755 --- a/hooks/init.sh +++ b/hooks/init.sh @@ -15,34 +15,30 @@ set -u # 不用 -e:单步失败要继续后续步骤 CCWORKDIR="/home/ubuntu/ccWorkDir" BASHRC="$HOME/.bashrc" -NATIVE_BIN="$CCWORKDIR/boot/ssw-dacli/target/dacli" +DACLI_SRC="$CCWORKDIR/dacli/src/cli.ts" PLAYWRIGHT_CLI_BIN="/usr/lib/node_modules/@playwright/cli/playwright-cli.js" PLAYWRIGHT_CLI_LINK="/usr/local/bin/playwright-cli" log() { echo "[init.sh] $*"; } -# ============ 1. dacli 命令(软链到 /usr/local/bin,PATH 自动命中) ============ -log "① 配置 dacli 命令" +# ============ 1. dacli 命令(TS 版 npx tsx wrapper,PATH 自动命中) ============ +log "① 配置 dacli 命令 (TS 版)" DACLI_LINK="/usr/local/bin/dacli" # 顺手清掉旧 alias(避免 .bashrc 残留干扰 type/which 输出) if [ -f "$BASHRC" ]; then sed -i '/^# dacli alias (JNPF CLI)/d; /^alias dacli=/d' "$BASHRC" fi -# native 比 jar 新就软链 native,否则写 jar wrapper:让 dacli 命令在两种产物下都能用 -DCLI_JAR=$(ls "$CCWORKDIR/boot/ssw-dacli/target"/ssw-dacli-*.jar 2>/dev/null | head -1) -if [ -f "$NATIVE_BIN" ] && { [ -z "$DCLI_JAR" ] || [ "$NATIVE_BIN" -nt "$DCLI_JAR" ]; }; then - ln -sf "$NATIVE_BIN" "$DACLI_LINK" - log " ✅ native: $DACLI_LINK → $NATIVE_BIN" -elif [ -n "$DCLI_JAR" ]; then +# TS 版:通过 npx tsx 调 cli.ts,写 wrapper 脚本到 /usr/local/bin +if [ -f "$DACLI_SRC" ]; then cat > "$DACLI_LINK" </dev/null || echo '(未在 PATH 中)')" diff --git a/hooks/pre-tool-use.js b/hooks/pre-tool-use.js index 433f34c..6c4dc9f 100644 --- a/hooks/pre-tool-use.js +++ b/hooks/pre-tool-use.js @@ -84,7 +84,6 @@ if (toolName === 'Write' || toolName === 'Edit') { 'web/apps/jnpf-web-apps-main/src/views/ssw/', 'web/apps/jnpf-web-apps-main/public/ssw', 'uniapp/pages/ssw/', - 'boot/ssw-dacli/src/main/java/com/jnpf/' // ssw-dacli module ]; for (const { path: denied } of deniedPaths) { diff --git a/settings.local.json b/settings.local.json index 5fdf1cd..84358e9 100644 --- a/settings.local.json +++ b/settings.local.json @@ -35,7 +35,6 @@ "Read(//home/ubuntu/**)", "Bash(bash -ic 'type dacli; dacli --version')", "Bash(rm -f *.json)", - "Bash(rmdir /home/ubuntu/ccWorkDir/boot/ssw-dacli/src/main/resources/dacli/templates)", "Bash(mkdir -p /home/ubuntu/ccWorkDir/.claude/skills/design-jnpf-execute/scripts)", "Bash(mkdir -p /home/ubuntu/ccWorkDir/.claude/skills/ssw-e2e-test/scripts)", "Bash(git mv *)", diff --git a/skills/.DS_Store b/skills/.DS_Store index 4ec614c70f96c2e1f13e57cb494b141c6523856c..d83577ec110a1f8759013ff92e70ce2464a36703 100644 GIT binary patch delta 42 ycmZn(XbG6$&*-=@U^hRb<77JlrOkQ*i7cDl#SU<8Y}moLnO)%*%jTV8%*+5d<_=Q; delta 773 zcmZn(XbG6$&*-@^U^hRb=VUtprOkQ*i7fR(3@HqW49N^R44DkNKvofuodIN*Fr)%m zB@CrNk<^@Y!{Frn+yVwLP<;lZh|-sv@8Xh_lb-}s&yjPSQ@ZZuaYt0W^|&p~%}*hq z8Moeo3}gozfSk>b;?Wd_e4zJq8S0b4zRy7Sql^qrEpQ#kzPr#j{Z<0Rci1gL(uMHW zg+2{pwQa5uxy-qlUEvo?J<)-Wun2qLlNWyV;FJOjK)An9(+Ca2&lD+L5FhNo@VmeW E0I#I3zW@LL diff --git a/skills/dacli-architecture/SKILL.md b/skills/dacli-architecture/SKILL.md deleted file mode 100644 index 80c831e..0000000 --- a/skills/dacli-architecture/SKILL.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -name: dacli-architecture -description: Use when modifying dacli, adding new commands, or integrating dacli with ssw-* business modules. Documents the post-Picocli + post-nested-class architecture (2026-06-05 refactor). ---- - -# dacli 架构 (Picocli + 嵌套类) - -## 适用场景 - -修改/扩展 dacli 工具、添加新命令、调试 dacli 与 ssw 业务模块的集成时必读。 - -## 演进历史 (2026-06-05 重构) - -| 阶段 | 状态 | 关键变更 | -|------|------|---------| -| 阶段 0 | ✅ 完成 | 提取 `DacliKit` 静态工具类;删除 `BaseCommand.java`;所有命令 `implements Callable` | -| 阶段 1 | ✅ 完成 | `DacliRoot` + 5 个无子命令命令(login/status/logs/initapp/codegen)迁移到 Picocli | -| 阶段 2 | ✅ 完成 | `form` 全套子命令迁移(list/info/create/release/delete)作为模式示例 | -| 阶段 3 | ✅ 完成 | role(8) + datasource(12) + org(12) + dict(14) + user(17) + file(22) + menu(10)/workflow/di/dm/portal/report 共 100+ 子命令迁移到 Picocli | -| 阶段 4 | ✅ 完成 | e2e(17 actions) + test(复杂路由) 通过 call() 包装原命令类 | -| 阶段 5 | ✅ 完成 | 删除 `Dacli.commands Map`、内部类、`printHelp()`、`help.txt`、`RedisCacheService.getHelp/setHelp`;`scripts/verify.sh --full` 34/34 通过 | -| **阶段 6** | ✅ **完成** | **嵌套类重构**:13 父命令的 109 个子命令合并为 `static nested class`;文件数 143→19(**-87%**) | -| **阶段 7** | ✅ **完成** | **新增 `dacli doc` 子命令**:HTML 文档缓存,AI 读取 token 降低 80%。详见 `.claude/skills/dacli-doc-cache/SKILL.md` | -| **阶段 8** | ✅ **完成** | **移除 curl/playwright-cli 包装**:删除 `dacli test` 和 `dacli e2e`,直接用系统原生 `curl` + `playwright-cli`(更标准、跨平台、无版本耦合) | -| **阶段 9** | ✅ **完成** | **新增 `dacli apis` 子命令**:从 `/v3/api-docs` 拉 JNPF 全量 OpenAPI 写入 SQLite(PID 变化 + 12h TTL 自动失效),提供 list/info/search/status 给 AI 快速查 JNPF 平台 API | -| **阶段 10** | ✅ **完成** | **架构演进**:1) GraalVM Native 编译(启动 800ms→100ms,输出 `target/dacli` 原生二进制);2) **Redis → SQLite 迁移**(`SqliteCacheService` 替代 `RedisCacheService`,缓存文件 `~/.dacli/cache.db`,无需外部 Redis 容器);3) 新增 `dacli codegraph` 子命令(基于 `codegraph.db` 静态分析,7 子命令:search/calls/trace/impact/contains/implements/route) | -| **阶段 11** | ✅ **完成** | **新增 `dacli form export/import` 子命令**:备份/迁移表单结构(完整 formData/columnData/tables/buttonData/flowTemplateJson)。**`form template` 子命令族已在 2026-06-09 重做时下线**——AI 应在 `form-development` 技能里查官方示例速查表,用 `dacli form info ` 读真实结构后仿造,比"一键 apply"更可控。 | - -完整计划:`docs/dacli/dacli-fix-plan.md`、`docs/dacli/h5doc-plan.md` - -## 当前架构(阶段 6+7 完成后) - -``` -src/main/java/com/jnpf/dacli/ -├── Dacli.java # 精简入口:直接 new CommandLine(new DacliRoot()).execute(args) -├── DacliRoot.java # Picocli 根命令 @Command(name="dacli"),注册 20 个子命令 -├── DacliKit.java # 静态工具类(替换原 BaseCommand) -├── DacliConfig.java # 配置加载(含 doc.cache.ttl) -├── SqliteCacheService.java # SQLite 缓存(替代原 RedisCacheService,文件 `~/.dacli/cache.db`;+ deleteByPattern 方法,dacli doc/apis 用) -├── SswCodeGenerator.java # ssw 业务包生成 -├── FormBuilder.java # 表单构造器 -│ -├── 顶级 @Command 类(共 20 个): -│ ├── 5 工具/包装命令: LoginCommand, StatusCommand, LogsCommand, -│ │ InitAppCommandWrapper, CodegenCommandWrapper -│ │ -│ └── 15 业务父命令(**含嵌套子命令**): -│ ├── FormCommand (5 nested: List/Info/Create/Release/Delete) -│ ├── RoleCommand (8 nested: List/Info/Create/Update/Delete/Selector/...) -│ ├── DatasourceCommand (12 nested: List/Selector/Create/Update/.../Sync/...) -│ ├── OrgCommand (12 nested: List/AsyncList/Info/Create/Update/.../Import/Export) -│ ├── DictCommand (14 nested: TypeList/TypeInfo/.../DataList/.../DataExport) -│ ├── UserCommand (17 nested: List/Info/Create/Update/.../Import/Export/...) -│ ├── FileCommand (22 nested: DownloadUrl/Preview/ChunkMerge/.../DocList/.../DocShare/...) -│ ├── MenuCommand (10 nested: List/Info/Create/Update/Delete/Cleanup/Move/Clone/Export/Import) -│ ├── WorkflowCommand (6 nested: List/Create/Launch/Approve/Reject/Pending) -│ ├── DiCommand (3 nested: List/Create/Preview) -│ ├── DmCommand (6 nested: List/Table/Query/Create/Update/Drop) -│ ├── PortalCommand (2 nested: List/Create) -│ ├── ReportCommand (2 nested: List/Create) -│ ├── DocCommand (5 nested: List/Get/Scan/Refresh/Clear) — HTML 文档缓存 -│ └── ApiCommand (5 nested: List/Info/Search/Refresh/Status) — OpenAPI/Swagger 查询(SQLite 缓存) -│ └── CodegraphCommand (7 nested: Search/Calls/Trace/Impact/Contains/Implements/Route) — JNPF 代码图谱查询(基于 codegraph.db) -│ └── FormCommand (10 nested: List/Info/Create/Release/Delete/Clone/Fix/MsRelation/Export/Import) — 阶段 11 新增 export/import(template 子命令族已下线) -│ -└── commands/ # 仅保留 1 个被 wrapper 引用的类 - └── InitAppCommand.java # v10.6.1 加 --restart 标志 + restartJnpf + isJnpfHealthy -└── DacliConf.java # v10.6.1 新增 - dacli.conf 配置文件读取器 (jar-pattern/port/health-url) -``` - -**结构变化**: -- 阶段 6:143 个独立 Command 文件 → 19 个 Command 文件(-87%) -- 阶段 8:移除 `TestCommand` / `E2eCommand`(curl/playwright-cli 包装),用系统原生命令替代 - -## 关键约束 - -### 1. 入口已极简化(阶段 5) - -```java -public class Dacli { - public static void main(String[] args) { - int exitCode = new CommandLine(new DacliRoot()).execute(args); - System.exit(exitCode); - } -} -``` - -所有命令通过 `DacliRoot` 的 `@Command` 注册后由 Picocli 路由。 - -### 2. DacliKit 静态方法 - -所有命令类调用的 HTTP/Token/JSON 工具方法都从 `BaseCommand` 移到 `DacliKit`: - -```java -import com.jnpf.dacli.DacliKit; - -// HTTP -DacliKit.doGet(path) -DacliKit.doPost(path, body) -DacliKit.doPut(path, body) -DacliKit.doDelete(path) - -// Token -DacliKit.loadToken() -> Map -DacliKit.getToken() -> String -DacliKit.getAppCode() -> String -DacliKit.tokenFile() -> String (路径) - -// 参数 -DacliKit.parseArgs(args) -> Map -DacliKit.getArgValue(args, key, pos) -> String -DacliKit.getDbLinkId(m, "dbLinkId") -> String -DacliKit.parseJson(json) -> Map - -// 密码 -DacliKit.encryptPassword(plain) -> String (md5 + AES) -DacliKit.isEncryptedPassword(p) -> boolean -``` - -### 3. 新增 Picocli 命令的模板(嵌套类模式) - -**当前推荐**:在父命令文件中用 `static class` 嵌套类。Picocli 自动发现嵌套子命令。 - -```java -@Command(name = "my", - description = "...", - mixinStandardHelpOptions = true, - subcommands = { - MyCommand.ListCommand.class, - MyCommand.GetCommand.class, - }) -public class MyCommand implements Callable { - - @Override - public Integer call() { - new CommandLine(this).usage(System.out); - return 0; - } - - // ──── 嵌套子命令 ──── - @Command(name = "list", description = "...", mixinStandardHelpOptions = true) - static class ListCommand implements Callable { - @Option(names = {"--foo"}, required = true, description = "...") - private String foo; - - @Override - public Integer call() throws Exception { - String result = DacliKit.doGet("/api/.../" + foo); - System.out.println(result); - return 0; - } - } - - @Command(name = "get", description = "...", mixinStandardHelpOptions = true) - static class GetCommand implements Callable { - // ... - } -} -``` - -**关键规则**: -- ✅ 嵌套类用 `static class`(**不是** inner class) -- ✅ 嵌套类默认 package-private 访问即可 -- ✅ 父命令的 `subcommands = {...}` 引用嵌套类 -- ✅ DacliRoot 注册父命令 `MyCommand.class`,Picocli 自动发现嵌套子命令 -- ❌ 不要为每个子命令单独建文件(旧模式,已废弃) -- ❌ 不要修改 DacliRoot(除非新增父命令) - -## Token 路径(2026-06-05 修正) - -**实际路径**:`$ccWorkDir/.dacli-token/token.json`(运行时由 `DacliKit.java:41` 写死) - -**不要**用 `~/.dacli/token.json`(CLAUDE.md 老路径,2026-06-05 已纠正) - -**覆盖**:用 `$DACLI_TOKEN_DIR` 环境变量。 - -**快速定位**:`dacli status` 输出 token 路径。 - -## JNPF API 行为备注(dacli 开发必读) - -### VisualDev 表单 API 端点差异 - -| 端点 | 返回范围 | 用途 | -|------|---------|------| -| `/api/visualdev/Base/list` | 仅已发布表单(state=1) | **不要用于 diff 检测** | -| `/api/visualdev/Base`(无 /list) | 全部表单(含未发布 state=0) | dacli form list 用此端点 | - -### Copy API 行为 - -- `POST /api/visualdev/Base/{id}/Actions/Copy` 返回 `{code:200, msg:"Replicating Success"}`,**不返回新表单 ID** -- 克隆后表单默认 state=0(未发布),需单独调 `/Actions/Release` 发布 -- dacli form clone 通过 diff 全量表单快照(before/after)检测新 ID - -### Form 仿造工作流(替代 template apply) - -`dacli form template` 子命令族在 2026-06-09 二次打磨时全部下线。AI 写新表单应: - -1. 在 `.claude/skills/form-development/SKILL.md` 里的「workSystem 官方示例速查」表里找一个最接近的示例(id/enCode/特色) -2. `dacli switch-app --appCode=workSystem && dacli form info <示例ID>` 拿完整 formData/columnData/tables -3. 照思路写自己的字段,再用 `dacli dm create` + `dacli form create` 建出来 - -需要"几乎照搬"时,用 `dacli form export ` + `dacli form import` 走备份/恢复路径(不预建表,纯 JSON 复制)。结构出问题再 `dacli form fix` 走内置 baseline。 - -**为什么删 template apply**:一键 apply 整段照搬 formData 看起来快,但子表 vModel 命名跟新表对不上、字段语义跟新需求不符、改起来要回头读完整 JSON,**总成本 ≥ 看示例后手写**。dacli 只保留"基础骨架内化"(`FormBuilder.buildCreatePayload` + `baseline-schema.json`),结构灵活度交给 AI。 - -### 其他注意 - -- 表单列表默认 pageSize=20,需传 `?pageSize=N` 获取更多 -- 中文 keyword 需 URL 编码(`URLEncoder.encode(keyword, "UTF-8")`) - -## 编译验证 - -```bash -cd $ccWorkDir/boot -mvn -pl ssw-dacli -am clean package -DskipTests - -# 自动验证(29 项 + --full 时 35 项) -bash ssw-dacli/scripts/verify.sh --full - -# 快速测试 -java -jar ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar --help -java -jar ssw-dacli/target/ssw-dacli-6.2.0-RELEASE.jar form list -``` - -## 不要做 - -- ❌ 不要新建 `BaseCommand` 兼容层(已彻底删除) -- ❌ 不要修改 `jnpf/` `web/` `uniapp/`(CLAUDE.md 禁止) -- ❌ 不要用 Java 11+ 特性(jnpf-admin 仅支持 Java 8,但 ssw-dacli 是 Java 21,**两者独立**) -- ❌ 不要在 `DacliRoot` 注册未实现的子命令(编译会失败) -- ❌ 不要为子命令单独建文件(用嵌套类,**阶段 6 之后的标准**) -- ❌ 不要在 `commands/` 包新增类(用顶级 @Command + 嵌套类更易管理) - -## 相关技能 - -- **`.claude/skills/dacli-doc-cache/SKILL.md`** — `dacli doc` 缓存读取 HTML 文档(阶段 7 新增) -- **`.claude/skills/dacli-codegraph/SKILL.md`** — `dacli codegraph` JNPF 平台代码图谱查询(阶段 10 新增) -- **`.claude/skills/dacli-architecture/SKILL.md`**(本文件)— dacli 整体架构 -- **`.claude/skills/api-test/SKILL.md`** — API 集成测试(用 curl + jq + dacli 业务命令,**不再用 `dacli test`**) -- **`.claude/skills/ssw-e2e-test/SKILL.md`** — E2E 测试(用原生 `playwright-cli -s=dacli`,**不再用 `dacli e2e`**) -- **`.claude/skills/ssw-e2e-test/scripts/test_dacli_e2e.sh`** — dacli API+CLI 套件(v10.3 = 26 项:P3-A/B + P4-B + P5 + P6 + P7 + P18 OLD 漂移 + P19 v10.2 columnData + P20 C.5.9 引用,可入 CI) - -## 引用 - -- 完整 Picocli 迁移计划:`docs/dacli/dacli-fix-plan.md` -- 嵌套类 + dacli doc 计划:`docs/dacli/h5doc-plan.md` -- DacliKit 源码:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/DacliKit.java` -- 嵌套类模式示例:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/FormCommand.java` -- dacli doc 服务实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/DocService.java` -- dacli apis 服务实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/ApiService.java`(阶段 9 新增) -- dacli codegraph 实现:`boot/ssw-dacli/src/main/java/com/jnpf/dacli/CodegraphCommand.java`(阶段 10 新增) -- GraalVM Native 实施记录:`docs/dacli/me.md`(仅维护者) -- **`references/dacli-conf-usage.md`** — `dacli.conf` 配置文件 + `dacli initapp --restart` 端到端配置 - ---- - -## 附录:阶段 10 实施细节(仅 dacli 维护者参考) - -> **AI 工作流用不到本节**,但接手 dacli 维护 / 重新生成 native binary 时需要。本节是从 `docs/dacli/me.md` 提取的关键操作指引。 - -### A. GraalVM 23 下载(Oracle CDN 加速) - -GitHub Releases 极慢(~12MB/min),用 Oracle CDN 替代: - -```bash -# 推荐:GraalVM 23(21 CE 有 HTTP 协议 bug) -wget https://download.oracle.com/graalvm/23/latest/graalvm-jdk-23_linux-x64_bin.tar.gz - -# 不推荐:GraalVM 21(有 bug) -# https://download.oracle.com/graalvm/21/archive/graalvm-jdk-21.0.2+13.1_linux-x64_bin.tar.gz - -tar -xzf graalvm-jdk-23_linux-x64_bin.tar.gz -C /usr/local/ -# 解压路径:/usr/local/graalvm-jdk-23.0.2+7.1/ -# native-image 工具已内置 -``` - -### B. Jar 编译(常规) - -```bash -export JAVA_HOME=/usr/local/graalvm-jdk-23.0.2+7.1 -export PATH=$JAVA_HOME/bin:$PATH -cd $ccWorkDir/boot/ssw-dacli -mvn package -q -# 输出:target/ssw-dacli-6.2.0-RELEASE.jar(~19MB fat-jar) -``` - -### C. Native 二进制编译 - -**⚠️ 坑:不要用 `native-maven-plugin` 自动编译** - -`mvn package` 默认会触发 `native:compile`,但生成的命令**缺少关键参数**(`--enable-url-protocols` / `--initialize-at-run-time`),导致编译成功但运行时报错。**必须手动执行 `native-image`**: - -`$ccWorkDir/boot/ssw-dacli/dacli-native-build.sh`(3002 字节,2026-06-06 验证可用): - -```bash -#!/bin/bash -set -e -export JAVA_HOME=/usr/local/graalvm-jdk-23.0.2+7.1 -export PATH=$JAVA_HOME/bin:$PATH -cd "$(dirname "$0")" - -# 1. 生成 fat-jar(不触发 native 编译) -mvn package -DskipTests -q -FAT_JAR="target/ssw-dacli-6.2.0-RELEASE.jar" -OUT="target/dacli" - -# 2. 手动 native-image -native-image \ - --no-fallback \ - --enable-url-protocols=http,https \ - --initialize-at-run-time=org.sqlite \ - -H:DeadlockWatchdogInterval=0 \ - -H:+ReportUnsupportedElementsAtRuntime \ - -jar "$FAT_JAR" \ - -o "$OUT" -``` - -执行:`./dacli-native-build.sh` → `target/dacli`(~50MB 原生二进制,启动 ~100ms) - -### D. 关键编译参数说明 - -| 参数 | 作用 | 必须? | -|------|------|--------| -| `--no-fallback` | 生成纯原生二进制,不依赖 JVM | 是 | -| `--enable-url-protocols=http,https` | 允许 `new URL("http://...")`(GraalVM 默认禁 HTTP) | 是 | -| `--initialize-at-run-time=org.sqlite` | SQLite JDBC 延迟初始化(避免构建时初始化报错) | 是(用 SQLite 时) | -| `-H:DeadlockWatchdogInterval=0` | 禁用死锁看门狗(避免被误杀) | 建议 | -| `-H:+ReportUnsupportedElementsAtRuntime` | 构建时不报错,运行时再报 | 建议 | - -### E. 验证产物 - -```bash -./target/dacli --version # 验证 native binary 可运行 -ldd target/dacli # 确认依赖(理想:纯静态或少量系统库) -``` - -### F. 已知坑 - -- **Jedis 兼容性差** → 阶段 10 已迁移到 SQLite,避开 reflect-config 维护 -- **GraalVM 21 HTTP 协议 bug** → 强制使用 GraalVM 23 -- **`native-maven-plugin` 自动编译缺参** → 必须手动 `native-image`(见 C 节) -- **构建时间长(5-10 分钟)** → `target/dacli` 不应频繁重建,CI 缓存或按需发布 - -### G. 维护者 CheckList - -- [ ] 新增子命令后必须 `mvn package` 验证 jar 启动 -- [ ] 重大依赖变更(加/减依赖)后必须 `./dacli-native-build.sh` 重新出 native binary -- [ ] 重新生成 `codegraph.db` 后 `dacli.conf` 的 `codegraph.dbPaths` 路径不变即可 -- [ ] 缓存格式变更(`SqliteCacheService` 表结构)需要考虑老 db 兼容,必要时加 version 字段 diff --git a/skills/dacli-architecture/references/dacli-conf-usage.md b/skills/dacli-architecture/references/dacli-conf-usage.md deleted file mode 100644 index df48e88..0000000 --- a/skills/dacli-architecture/references/dacli-conf-usage.md +++ /dev/null @@ -1,140 +0,0 @@ -# dacli.conf 配置文件使用文档 (v10.6.1) - -> **来源**: 从 `docs/dacli/2/dacli-conf-usage.md` 融合到本技能。 -> **何时读**: 用 `dacli initapp --restart` 需要配置 jar 匹配模式 / 端口 / 健康检查端点时。 - ---- - -## 0. 快速开始 - -```bash -# 1. 复制模板到项目根 -ls /home/ubuntu/ccWorkDir/dacli.conf -# 已存在则跳过 - -# 2. 编辑配置(按需) -vim /home/ubuntu/ccWorkDir/dacli.conf - -# 3. 一条命令完成 initapp + 自动重启 -dacli initapp -- --appCode=tds --appName="可信数据空间" --force-rebuild --restart -``` - ---- - -## 1. 查找顺序 - -`dacli` 按优先级找 dacli.conf: - -1. **`--dacliConf `** 命令行参数(最高优先) -2. **`$DACLI_CONF`** 环境变量 -3. **`$ccWorkDir/dacli.conf`** 项目根 -4. **`~/.dacli/dacli.conf`** 用户级 - -找不到时返内置默认值(jar-pattern=`jnpf-admin-.*-RELEASE\.jar`, port=30000, health-url=/, wait-seconds=90, poll-interval=5),不报错。 - ---- - -## 2. 配置项详解([jnpf] 段) - -| Key | 默认 | 说明 | -|-----|------|------| -| `jar-pattern` | `jnpf-admin-.*-RELEASE\.jar` | JNPF 进程匹配正则(pgrep -f 用,`\.` 要转义)| -| `port` | `30000` | HTTP 端口(lsof -ti + 健康检查)| -| `health-url` | `/` | 健康检查端点(GET )| -| `start-log` | `/tmp/jnpf-restart.log` | 启动日志路径(nohup `&> {start-log}`)| -| `wait-seconds` | `90` | 等待健康检查通过的最大秒数 | -| `poll-interval` | `5` | 健康检查轮询间隔(秒)| -| `start-cmd` | (空 = 默认)| 自定义启动命令模板,占位符 `{jar}` `{port}` `{log}` `{yml}` | - ---- - -## 3. 默认 start-cmd - -```bash -nohup java -Dfile.encoding=utf8 \ - -Djava.security.egd=file:/dev/./urandom \ - -jar {jar} \ - --spring.profiles.active=dev \ - &> {log} & -``` - -自动 `ls -t boot/jnpf-admin/target/ | grep 'jnpf-admin-.*\.jar$' | head -1` 找最新 jar。 - ---- - -## 4. 自定义 start-cmd 示例 - -```ini -[jnpf] -# 示例 1: 自定义 JVM 参数 + 指定端口 -start-cmd = nohup java -Xms1g -Xmx2g -jar {jar} --server.port={port} > {log} 2>&1 & - -# 示例 2: 启动多个服务 -start-cmd = nohup java -jar {jar} > {log} 2>&1 & nohup redis-server --port 6379 > /tmp/redis.log 2>&1 & - -# 示例 3: 自定义 yml 路径 -start-cmd = nohup java -jar {jar} --spring.config.additional-location=file:{yml} > {log} 2>&1 & -``` - ---- - -## 5. 端到端流程 - -`dacli initapp --restart` 触发: - -``` -1. 健康检查 (curl http://127.0.0.1:{port}{health-url}) - ↓ 不健康 -2. pgrep -f '{jar-pattern}' 找旧 PID - ↓ 有 PID -3. lsof -ti:{port} 二次确认端口占用 -4. kill + 等待退出(最多 10s) -5. ls -t boot/jnpf-admin/target/ | grep 找最新 jar -6. nohup & 启动 -7. 轮询 health-url(间隔 {poll-interval}s,最多 {wait-seconds}s) - ↓ 200 -8. 继续 initapp 7 步骤 + 自动重登 -``` - ---- - -## 6. 跨项目复用 - -复制 `dacli.conf` 到新项目根,改 `jar-pattern` 和 `port`: - -```bash -# 例如新项目用 jnpf-app-server-1.0.jar + 端口 31000 -cat > /path/to/new-project/dacli.conf <<'CONF' -[jnpf] -jar-pattern = jnpf-app-server-1\.0\.jar -port = 31000 -health-url = /actuator/health -start-log = /tmp/jnpf-app-restart.log -CONF - -cd /path/to/new-project -dacli initapp -- --appCode=newapp --appName="新应用" --restart -``` - ---- - -## 7. 故障排查 - -| 现象 | 可能根因 | 修复 | -|------|---------|------| -| `没找到匹配 的旧进程` | 进程名与正则不匹配 | 检查 `pgrep -f ''` | -| `没找到 jnpf-admin-*.jar` | 没 `mvn package` | `cd boot && mvn package -pl jnpf-admin -DskipTests` | -| `健康检查超时` | JVM 启动慢 / 端口被占 | 加大 `wait-seconds` 或 `tail -f {start-log}` 看启动日志 | -| `lsof 找不到 port` | 端口被其他进程占 | `lsof -i:{port}` 查 + 杀 | -| `--restart 预重启失败` | 启动 jar 缺失或路径错 | 检查 `boot/jnpf-admin/target/` 目录 | - ---- - -## 8. 相关文件 - -- `boot/ssw-dacli/src/main/java/ssw/dacli/DacliConf.java` (109 行配置读取器) -- `boot/ssw-dacli/src/main/java/ssw/dacli/commands/InitAppCommand.java` (restartJnpf + isJnpfHealthy 实现) -- `/home/ubuntu/ccWorkDir/dacli.conf` (项目根配置) -- `.claude/skills/design-jnpf-execute/SKILL.md` (C.7 场景 2.5 配套) -- `docs/tds/polish-changes-v10.6.md` (v10.6.1 修复闭环) -- MEMORY: `dacli-initapp-restart-fix.md` diff --git a/skills/dacli-codegraph/SKILL.md b/skills/dacli-codegraph/SKILL.md deleted file mode 100644 index cfde9c8..0000000 --- a/skills/dacli-codegraph/SKILL.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -name: dacli-codegraph -description: 通过 dacli codegraph 查询 JNPF 平台源码的代码图谱(基于 codegraph.db 静态分析结果)。能力:全文搜索、调用链追踪、跨模块路径、修改影响分析、API 反查 Controller。触发词:JNPF 源码、调用链、codegraph、controller 反查、影响分析 ---- - -# dacli codegraph — JNPF 平台代码图谱查询 - -> **⚠️ 仅适用于 JNPF 平台。** `codegraph.db` 是对 JNPF 低代码平台自身源码(后端 Java + 前端 Vue/TypeScript)的静态解析结果。所有查询结果均为 JNPF 平台的代码实体(Controller / Service / Mapper / 组件 / 路由等),不适用于其他项目。 - ---- - -## 1. 数据来源 - -| 表 | 行数级别 | 说明 | -|----|---------|------| -| `nodes` | ~15 万 | 代码实体(类/方法/字段/组件/路由) | -| `edges` | ~38 万 | 关系(calls/contains/references/imports/implements/instantiates) | -| `nodes_fts` | ~15 万 | FTS5 全文搜索索引(基于 name/qualified_name/docstring) | - -`codegraph.db` 实际大小约 400MB,存放在: -- `~/.dacli/codegraph.db`(默认用户级) -- `$ccWorkDir/jnpf/.codegraph/codegraph.db`(项目级,由 `project:jnpf` 简写解析) - ---- - -## 2. 7 个子命令 - -### 2.1 `search` — 全文搜索 - -```bash -dacli codegraph search [-k kind] [-l lang] [-n limit] -``` - -- `query`(必填):FTS5 搜索词,支持 `prefix*` 前缀匹配 -- `-k/--kind`:过滤节点类型,可选 `class` / `method` / `interface` / `field` / `component` / `route` -- `-l/--lang`:过滤语言,可选 `java` / `python` / `vue` / `typescript` / `javascript` -- `-n/--limit`:返回条数(默认 20) - -输出字段:`id, kind, name, qualified_name, file_path, start_line, end_line, signature, docstring, visibility, is_static, is_abstract, highlight` - -```bash -# 示例:搜 JNPF 用户管理 Controller -dacli codegraph search "UserController" -k class - -# 限定 java -dacli codegraph search "UserController" -k class -l java - -# 前缀匹配(所有 User 开头的方法) -dacli codegraph search "User*" -k method -l java -n 50 -``` - -### 2.2 `calls` — 单层调用链 - -```bash -dacli codegraph calls [-d in|out] [-n limit] -``` - -- `qualified_name`(必填):节点完整名,如 `jnpf.permission.controller::UserController` -- `-d/--direction`: - - `out`(默认):谁调用了它(incoming callers) - - `in`:它调用了谁(outgoing callees) - -> **注意**:方向命名是**从目标节点视角**看 — `out` = 反向追溯 callers,`in` = 正向展开 callees。 - -```bash -# 找谁调用了 UserController(反向) -dacli codegraph calls "jnpf.permission.controller::UserController" -d out - -# UserController 内部调用了哪些方法(正向) -dacli codegraph calls "jnpf.permission.controller::UserController" -d in -n 50 -``` - -### 2.3 `trace` — 多跳 BFS 路径追踪(最强能力) - -```bash -dacli codegraph trace [-d depth] [-e edge-types] -``` - -- `` ``(必填):起始 / 目标 qualified_name -- `-d/--depth`:最大搜索深度(默认 8) -- `-e/--edge-types`:遍历的边类型,逗号分隔(默认 `calls,references,imports,instantiates`) - -```bash -# 跨模块追踪:Controller → Service → ServiceImpl -dacli codegraph trace \ - "jnpf.permission.controller::UserController::getList" \ - "jnpf.permission.service.impl::UserServiceImpl::getList" - -# 限制深度为 3 -dacli codegraph trace "X::Controller::a" "Y::Service::b" -d 3 - -# 只走调用边 -dacli codegraph trace "X" "Y" -e calls -``` - -### 2.4 `impact` — 修改影响分析 - -```bash -dacli codegraph impact [-n limit] [-g] -``` - -- 找出**所有引用 / 调用 / 导入 / 继承 / 实现**该符号的节点 -- `-g/--group`:按文件分组(默认不分组,展开所有引用) - -**改动前必跑** — 一键列出所有受影响位置。 - -```bash -# 我要改 UserService,看看谁引用了它 -dacli codegraph impact "jnpf.permission.service::UserService" - -# 按文件分组(看改动涉及多少文件) -dacli codegraph impact "jnpf.permission.service::UserService" --group -``` - -### 2.5 `contains` — 类/文件成员 - -```bash -dacli codegraph contains [-k kind] -``` - -- 列出类或文件的成员(方法 / 字段 / 内部类 / import) -- `-k/--kind`:过滤成员类型,可选 `method` / `field` / `class` / `import` - -```bash -# 看 UserController 有哪些方法 -dacli codegraph contains "jnpf.permission.controller::UserController" -k method - -# 看 UserService 的字段 -dacli codegraph contains "jnpf.permission.service::UserService" -k field -``` - -### 2.6 `implements` — 接口实现类 - -```bash -dacli codegraph implements [-n limit] -``` - -```bash -# 找所有实现 UserService 接口的类 -dacli codegraph implements "jnpf.permission.service::UserService" -``` - -### 2.7 `route` — API 路径反查 Controller - -```bash -dacli codegraph route [-n limit] -``` - -- 通过 API 路径关键词反查是哪个 Controller 方法处理的 - -```bash -# /user/list 接口是哪个 Controller? -dacli codegraph route "/user/list" - -# 按方法名反查 -dacli codegraph route "getList" -``` - ---- - -## 3. DB 路径配置(`dacli.conf`) - -`dacli.conf` 中的 `codegraph.dbPaths` 控制查找路径,多路径用逗号分隔,**按顺序查找第一个存在的文件**: - -```properties -# 内置简写:project:<名> → $ccWorkDir/<名>/.codegraph/codegraph.db -codegraph.dbPaths=/home/ubuntu/.dacli/codegraph.db,project:jnpf -``` - -| 格式 | 示例 | 解析结果 | -|------|------|---------| -| 绝对路径 | `/home/ubuntu/.dacli/codegraph.db` | 直接使用 | -| `project:<名>` | `project:jnpf` | `$ccWorkDir/jnpf/.codegraph/codegraph.db` | - -**查找顺序**(从前往后,找第一个存在的): -1. `dacli -Dcodegraph.db=` 命令行临时覆盖 -2. `./config/dacli.conf`(当前目录) -3. `$ccWorkDir/config/dacli.conf`(项目级) -4. jar 内置默认 `dacli.conf`(包含 `project:jnpf`) - -```bash -# 临时指向其他 db -dacli -Dcodegraph.db=/tmp/test.db codegraph search "..." -``` - ---- - -## 4. qualified_name 命名规范 - -完整节点标识符格式:`::` 或 `::::` - -```bash -# 类级别 -jnpf.permission.controller::UserController - -# 方法级别 -jnpf.permission.controller::UserController::getList -jnpf.permission.service.impl::UserServiceImpl::save -``` - -**如何获取准确的 qualified_name**: -1. 先 `dacli codegraph search <关键词> -k class` 找到类,输出里 `qualified_name` 字段就是 -2. 再用 `dacli codegraph contains -k method` 拿方法级别 qname -3. 也可以从 JNPF 源码的 `package + class` 直接拼出(Java 包用 `.`,codegraph 用 `.`) - ---- - -## 5. AI 典型查询范式 - -### 范式 1:定位某 Controller 的所有方法 -```bash -dacli codegraph search "CommentController" -k class -# → 拿到 qname: jnpf.flowable.controller::CommentController - -dacli codegraph contains "jnpf.flowable.controller::CommentController" -k method -# → 列出所有方法及 qname -``` - -### 范式 2:跨模块调用链(最强) -```bash -dacli codegraph trace \ - "jnpf.flowable.controller::CommentController::list" \ - "jnpf.flowable.service.impl::CommentServiceImpl::list" -# 输出: Controller --calls--> Service --calls--> ServiceImpl 全链路 + 文件名+行号 -``` - -### 范式 3:改动前影响评估 -```bash -dacli codegraph impact "jnpf.permission.service::UserService" --group -# 输出:按文件分组的所有引用者 → 改动前风险一览 -``` - -### 范式 4:前端找后端实现 -```bash -dacli codegraph search "setPosition" -l vue -k component -# → 找到前端组件 - -dacli codegraph route "setPosition" -# → 找到后端 Controller 方法 -``` - -### 范式 5:架构理解 -```bash -dacli codegraph search "jnpf" -k interface -n 50 -# → 所有接口定义(理解 JNPF 平台抽象层) - -dacli codegraph search "jnpf" -k class -n 50 -# → 核心类清单 -``` - ---- - -## 6. 与 `dacli apis` 联动 - -> 联动仅适用于 JNPF 平台代码的查询场景。 - -``` -AI 提问:"JNPF 平台的流程评论怎么实现的?" - ↓ -① dacli apis info "/api/flowable/comment/list" - → 拿到 API 定义 + 中文字段(response/requestBody) -② dacli codegraph search "CommentController" -k class - → 定位 Controller 文件:行号 -③ dacli codegraph trace \ - "jnpf.flowable.controller::CommentController::list" \ - "jnpf.flowable.service.impl::CommentServiceImpl::list" - → Controller --calls--> Service --calls--> ServiceImpl 全链路 -④ 返回完整调用链 + 文件名 + 行号 + AI 即可读懂 JNPF 平台实现 -``` - -**快捷模式(改动前评估)**: -```bash -dacli codegraph impact "jnpf.flowable.service::CommentService" --group -→ 一键列出所有引用此 Service 的文件 → 改动风险评估 -``` - ---- - -## 7. 已知问题与局限 - -1. **静态分析 ≠ 运行时行为**:codegraph 不包含 Spring AOP / 动态代理 / 反射调用。Spring 注解生成的 Bean(如 `@Autowired` 注入)能看到声明,但运行时实际行为需结合其他手段验证。 -2. **生成的代码可能缺失**:MyBatis Generator / Lombok 生成的代码、Vue 编译产物等通常不在分析范围内。 -3. **db 文件较大(~400MB)**:首次 search 会有 100ms 量级 FTS 索引加载延迟;后续查询毫秒级。 -4. **db 需要单独构建**:codegraph.db 不是自动生成的,需通过 codegraph 工具对 JNPF 源码做静态分析。生成周期长,db 一般 1-2 周更新一次。 -5. **qualified_name 大小写敏感**:JNPF 后端类名严格匹配;前端组件名通常是 PascalCase,搜索时注意。 - ---- - -## 8. 相关技能 - -- **`.claude/skills/dacli-architecture/SKILL.md`** — dacli 整体架构(含 codegraph 在阶段 10 的引入) -- **`.claude/skills/dacli-doc-cache/SKILL.md`** — `dacli doc` 文档缓存(与 codegraph 配合:先查文档理解设计,再查 codegraph 看实现) -- **`.claude/skills/api-test/SKILL.md`** — API 集成测试(与 `dacli apis` 配合:apis 找 API 定义 → curl 验证实现) diff --git a/skills/dacli-doc-cache/SKILL.md b/skills/dacli-doc-cache/SKILL.md deleted file mode 100644 index 7c66ad6..0000000 --- a/skills/dacli-doc-cache/SKILL.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: dacli-doc-cache -description: 通过 dacli doc 缓存读取 HTML 文档(plan.html/design.html/testcase.html),避免直接 Read 整个 HTML 导致的 token 暴增。触发词:恢复上下文、读取文档、dacli doc、HTML 文档 ---- - -# dacli doc 缓存使用指南 - -## 适用场景 - -会话中断/上下文压缩后,需要快速恢复对 `docs/{app_code}/` 下 HTML 文档(plan.html / design.html / testcase.html / debug.html / summary.html)的阅读理解。**核心目标:把每个 HTML 文档读取的 token 用量从 ~25K 降到 ~5K(-80%)**。 - -直接用 `Read` 工具读 HTML 会被 `