From 5b0e45f395628b2002e84ebea4bc09b629abc3ce Mon Sep 17 00:00:00 2001 From: ssw Date: Mon, 22 Jun 2026 18:51:30 +0800 Subject: [PATCH] auto(09213057c521): session end @ 2026-06-22T18:51:30 (+3f) --- CLAUDE.md | 57 +++++++++++++++++++++++++------- skills/form-development/SKILL.md | 8 ++--- skills/troubleshooting/SKILL.md | 23 ++++++++++--- 3 files changed, 68 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8b732e6..b92d931 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,12 +41,24 @@ > > **嵌套类重构 (2026-06-05)**:所有父命令(form/role/datasource/org/dict/user/file/menu/workflow/di/dm/portal/report)的子命令合并为 `static nested class`,文件数大幅减少。详见 `docs/dacli/h5doc-plan.md` Phase 0。 > -> **dacli doc (v0.7+)**: HTML 文档扫描, **仅 1 子命令** `list` (TS 版无 get/scan/refresh/clear). AI 读取 plan.html 走 `Read` 工具直接读 HTML 文件, 或 `python3 -c "import re; print(re.sub('<[^>]+>',' ',open('docs/{app}/plan.html').read()))"`. 详见 `.claude/skills/dacli-ts/SKILL.md`. +> **dacli doc (v0.7+)**: HTML 文档扫描, 2 子命令 (`list` / `get`). `get` 支持 `--section` 按 sidebar nav id 切片 / `--from/--lines` 按行号切片 / 全文, mtime 感知 SQLite 缓存 (7 天 TTL), P0 上下文恢复核心. 详见 `.claude/skills/dacli-ts/SKILL.md`. > -> **dacli apis (v0.7+)**: JNPF Swagger/OpenAPI 查询, **仅 1 子命令** `list` (TS 版无 info/search/refresh/status). 写本地缓存 (PID 变化 + 12h TTL 自动失效). 详见 `.claude/skills/dacli-architecture/SKILL.md`. +> **dacli apis (v0.7+)**: JNPF Swagger/OpenAPI 查询, 4 子命令 (`list` / `info` / `refresh` / `status`). `info` 杀手特性: 拿单 endpoint 详情 + 递归解析 `$ref` 展开 schema + 自动展开 `ActionResult.data` 内层, AI 写后端必备. 写本地缓存 (PID 变化 + 12h TTL 自动失效). 详见 `.claude/skills/dacli-architecture/SKILL.md`. > > **架构演进 (2026-06-06)**:1) **Redis → SQLite 迁移**(`SqliteCacheService` 替代 `RedisCacheService`,缓存文件 `~/.dacli/cache.db`,无需外部 Redis 容器);2) **GraalVM Native 编译**(启动 800ms→100ms,输出 `target/dacli` 原生二进制);3) **dacli tool codegraph 新增**(基于 `codegraph.db` 静态分析 JNPF 源码,7 子命令:search/calls/trace/impact/contains/implements/route)。 > +> **dacli AI 防御体系 (2026-06-22 v0.10+)**:解决 AI 误用根因 G(舍近求远)+ B/C/D(盲猜参数/状态)+ E(长任务副作用): +> 1. **`dacli app context` 命令**(P0.1):AI 新会话必跑的环境快照(appCode/dbLinkId/token/existingEnCodes/草稿 vs 发布/表/菜单) +> 2. **三层防御体系**:L1 `_precheck.ts` 静态检查 + L2 `_blindspot_guards.ts` 22 条运行时 guard + L3 `client.diagnoseError()` 错误诊断 +> 3. **web/ 源码权威参照**:SKILL.md 顶部强制规则——参数/API 不确定时,**优先读 `web/.../views/onlineDev/` + `web/.../api/`,不读 dacli 文档** +> 4. **`web-source-map.md`**:dacli 命令 → web/ 源码精确定位速查表(149 行) +> 5. **`form-type-rules.json`**:7 个 type×webType 合法组合 + 6 类常见错误(从 web/ 源码提取,非凭空编写) +> 6. **`extract-web-schema.py`**:自动从 web/ Vue 源码提取 → `data/web-derived-schemas.json`(含 5 文件 defaults + 40+ API 端点) +> 7. **长任务自检脚本** `scripts/self-check.sh`:每 5 步强制 TS 编译 + form validate + 后端错误日志 +> 8. **`errors.md` 决策树**:26 段按错误关键词分类的修复步骤(v0.10+ 吸收了 troubleshooting.md 全部 36 条历史错误) +> +> 详见 `.claude/skills/dacli-ts/SKILL.md` (148 行) + `references/{errors,commands,patterns,web-source-map}.md`。 +> > **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)兜底。 @@ -60,15 +72,22 @@ alias dacli='npx tsx $ccWorkDir/dacli/src/cli.ts' ### 常用命令 ```bash +# ⭐ v0.10+ 新会话必跑第一步:环境快照(消除盲猜参数/状态) +dacli app context --json # AI 必看 dbLinkId/existingEnCodes/草稿 vs 发布 dacli app login --account=admin --password=123456 --appCode=developSystem dacli app status dacli form list dacli form info <表单ID> # 位置参数 (不是 --id=) -dacli form fix --baseline= --target= --enCode=X --fullName=Y --fieldsJson='[...]' --release dacli form validate # 校验 columnData __config__ 完整性 (v10.2) dacli form validate --fix # FAIL 时自动调 fix-columndata dacli form fixcolumndata # 修复老 form 缺 __config__ → 白屏 -dacli form create --fullName=X --enCode=Y --webType=4 # 数据视图 (无物理表) ← v0.7+ --name 改 --fullName + +# v0.10+ 推荐流程:dm→form 两步(避免盲点 38/39/44) +dacli dm create --table=X --tableName="中文名" --dbLinkId= --fields='[...]' # 1. 物理表 +dacli form create --fullName="X" --enCode=X --table=X --webType=2 --dbLinkId= \ + --fields='[...]' --autoRelease # 2. form (dm 已建好, 自动发布) + +dacli form create --fullName=X --enCode=Y --webType=4 # 数据视图 (无物理表, 兜底用) dacli form create --fullName=X --enCode=Y --enableFlow=1 --flowId= # 工作流表单 dacli form export --out=file.json # 导出表单 (备份/迁移) dacli form import --enCode=X --name=Y # 导入表单 (从备份恢复) @@ -79,20 +98,28 @@ dacli form import --enCode=X --name=Y # 导入表单 (从备份恢复) dacli menu list dacli tool logs --level=error --lines=50 dacli apis list --tag=visualdev # 查 JNPF API 列表 -dacli apis info "GET /api/visualdev/Base/list" # 查 API 中文字段 (v0.7+ ❌ TS 版无, 改用 list --keyword 过滤) +dacli apis info "GET /api/visualdev/Base/list" # 查 API 中文字段 (v0.7+ ✅ TS 版有, 递归展开 $ref) +dacli apis refresh # 强制重拉 OpenAPI (忽略 12h TTL) +dacli apis status # 看缓存状态 (pathCount/ageMs/loadedAt) dacli tool codegraph search "UserController" -k class # 查 JNPF 源码 dacli tool codegraph trace "X::Controller::a" "Y::Service::b" # 跟调用链 dacli app clear --app-code=tds --dry-run # 清除应用 (备份→history_bak 库; 实跑需 TTY+双重确认) + +# v0.10+ 长任务自检(每 5 步跑一次,强制 TS 编译 + form validate + 后端错误日志) +bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/scripts/self-check.sh [form_id] + dacli help ``` -### dacli doc 命令(HTML 文档扫描, v0.7+ 仅 1 子命令) +### dacli doc 命令(HTML 文档扫描, v0.7+ 2 子命令) ```bash -# 列文档索引(结构 + section 列表, v0.7+ 唯一子命令) +# 列文档索引(结构 + section 列表) dacli doc list --dir=docs/tds -# ❌ TS 版 v0.7+ 无 dacli doc get / scan / refresh / clear -# 真替代: 用 Read 工具直接读 HTML, 或 python3 抽纯文本 +# 切片读取(v0.7+ 新 P0 上下文恢复核心, mtime 感知 SQLite 缓存 7 天 TTL) +dacli doc get --file=docs/tds/plan.html --section=h2_1 # 按 sidebar nav id 切片 +dacli doc get --file=docs/tds/plan.html --from=200 --lines=50 # 按行号切片 +dacli doc get --file=docs/tds/plan.html --strip-mermaid # 全文去 Mermaid ``` **适用场景**:上下文恢复时读取 plan.html/design.html/testcase.html,替代直接 `Read` 整个 HTML。 @@ -103,11 +130,17 @@ dacli doc list --dir=docs/tds 从 JNPF `/v3/api-docs` 拉取全量 OpenAPI(含 1000+ API + 1159 个 schema),写本地缓存(PID 变化或 12h TTL 自动失效),AI 一次性掌握 JNPF 平台所有 API 拓扑。 ```bash -# 列出接口(按 tag/method/keyword 过滤, v0.7+ 唯一子命令) +# 列出接口(按 tag/method/keyword 过滤) dacli apis list --tag=visualdev dacli apis list --method=GET --keyword=用户 -# ❌ TS 版 v0.7+ 无 dacli apis info / search / refresh / status -# 真替代: 拿全列表后用 jq/python 过滤 + +# 杀手特性:拿单 endpoint 详情 + 递归展开 $ref + 自动展开 ActionResult.data +dacli apis info "GET /api/visualdev/Base/list" # 含中文字段 +dacli apis info "POST /api/permission/Users" --json + +# 强制刷新 / 看状态 +dacli apis refresh # 忽略 12h TTL 重拉 +dacli apis status # 看 pathCount/ageMs ``` **适用场景**:写后端 / 调 API / 排查接口字段时直接查,避免手敲 curl 试探。 diff --git a/skills/form-development/SKILL.md b/skills/form-development/SKILL.md index 5e9c82b..89c57ff 100644 --- a/skills/form-development/SKILL.md +++ b/skills/form-development/SKILL.md @@ -88,7 +88,7 @@ dacli menu purge --formId=<表单ID> --yes [--unrelease] - **TS 版 v0.7+ 的 `dacli menu create` 已自动设 7 必填字段**, 无需 `update --fixDisplay=true` 兜底 - 表单菜单 `propertyJson.moduleId` **必须是表单ID**, 不是菜单ID - 旧菜单或外部创建菜单缺 7 字段: 走 `dacli menu info --id=X` 校验, 缺则 `delete` + `create` 重建 -- **❌ TS 版不支持 `dacli menu update --fixDisplay=true` / `cleanup` / `move` / `clone` / `export` / `import`** (Java v10.6 历史命令) +- ✅ **TS v0.7+ menu 7 命令**:`list` / `info` / `create` / `delete` / `unrelease` / `releases` / `purge` 已全部实现。详见 `dacli-ts/references/commands.md` §2 ## 字段定义 @@ -208,9 +208,9 @@ dacli form create --fullName=<名称> --enCode=<编码> --type=1 --webType=3 \ ## 必读文档 -- `docs/aibridge/docs/control/01-quick-ref.md` — 全部 55+ 控件速查 -- `docs/aibridge/docs/control/06-popup-controls.md` — popup/relationForm 控件详情 -- `docs/aibridge/docs/troubleshooting.md` #18 — relationForm 完整解决方案 +- **`.claude/skills/dacli-ts/references/web-source-map.md`** — web/ 源码权威映射(v0.10+ 最高优先级,参数/API 不确定先查这里) +- **`.claude/skills/dacli-ts/references/errors.md`** — 错误决策树(v0.10+ 推荐入口) +- `.claude/skills/dacli-ts/references/troubleshooting.md` #23 — relationForm 完整解决方案 ## dacli 增强能力(表单开发) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index 28c45ba..ebf4c01 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -5,11 +5,19 @@ description: "JNPF 故障排查技能。根据症状快速定位问题。" # 故障排查技能(JNPF) +> 📦 **dacli AI 防御体系 (v0.10+, 2026-06-22)**:本技能已集成到 dacli 三层防御。AI 报错时优先看: +> - **错误决策树**: `.claude/skills/dacli-ts/references/errors.md`(26 段按错误关键词分类) +> - **三层防御**: `.claude/skills/dacli-ts/SKILL.md` §🛡️(pre-check + guards + diagnose 自动拦截 22 条高频盲点) +> - **历史归档**: `.claude/skills/dacli-ts/references/troubleshooting.md`(52 条盲点流水账,仅 debug 历史问题) +> > 📦 **dacli 已完成 Picocli 完整迁移 (2026-06-05)**:详见 `dacli-ts` 技能 (TS 版, v0.7+ 替代; 本段 Java v10.6 Picocli 注释仅历史参考)。命令语法完全兼容,内部架构已极简(DacliKit 静态工具类 + 100+ @Command 类,无 BaseCommand)。 ## dacli 排查 ```bash +# ⭐ v0.10+ 新会话必跑第一步:环境快照(消除盲猜参数/状态) +dacli app context --json + # 查看后端错误日志 dacli tool logs --level=error --lines=50 @@ -23,13 +31,19 @@ dacli app status |------|------|----------| | 菜单不显示 | 未设置 app_code / 未发布表单 | 检查 appCode,确认表单 state=1 | | API 返回 null | Token 过期 | 重新 dacli app login | -| create_model 失败 | 表单未发布 | 先 dacli form-release | +| create_model 失败 | 表单未发布 | 先 dacli form release | | relationForm 弹窗空白 | columnOptions 超过 5 列 | 精简 columnOptions | | "map is null" | data 格式错误 | 直接传 dict,不包装 | +| **`dacli form create` 报 "Database exception"** | dbLinkId='0' 或 enCode 重复 | 看 `.claude/skills/dacli-ts/references/errors.md` #2 + BS-48/49 guard | +| **`dacli menu create --formId` 报 "主表不存在"** | form schema 缺主表信息 | BS-50 guard: 走低级 `--type=3 --urlAddress=model/{enCode}` | +| **`/jnpf_app_X/model/X` 报 404** | vue-router 未注册(未挂菜单) | errors.md #14: `dacli menu create --formId=` 挂菜单 | +| **Playwright `page.goto` 超时 30s** | nginx / 后端 hang 死 | errors.md #18: `sleep 30` 后重试或切 developSystem 兜底 | ## 必读文档 -- `docs/aibridge/docs/troubleshooting.md` — 18 个通用问题及解决方案 +- **`.claude/skills/dacli-ts/references/errors.md`** — 错误决策树(v0.10+ 推荐入口) +- **`.claude/skills/dacli-ts/references/web-source-map.md`** — web/ 源码权威映射(参数/API 不确定先查这里) +- `.claude/skills/dacli-ts/references/troubleshooting.md` — 历史归档(52 条盲点流水账) ## 常见 JNPF 故障 (2026-06-03 打磨沉淀) ### 问题1: 菜单在数据库正确但侧边栏不显示 @@ -57,7 +71,8 @@ dacli menu info --id= # 2. 缺则删了重建 (dacli menu create v0.7+ 自动带 7 字段) dacli menu delete --id= --yes dacli menu create --fullName=... --enCode=... --parentId=... --formId=... -# ❌ TS 版不支持 dacli menu update --fixDisplay=true (Java v10.6 历史命令) +# ✅ TS v0.7+ menu info / delete / releases / purge 已实现(v0.7+ 新增 4 命令) +# 详见 dacli-ts/references/commands.md §2 ``` ### 问题2: PUT 菜单报 "System abnormality" @@ -83,7 +98,7 @@ dacli form list --keyword= # 2. 删了重建 (dacli menu create --formId 自动绑 moduleId) dacli menu delete --id= --yes dacli menu create --fullName=... --enCode=... --parentId=... --formId= -# ❌ TS 版不支持 dacli menu update --propertyJson=... (Java v10.6 历史命令) +# ✅ TS v0.7+ menu info / delete 已实现,menu update 仍用 delete+create 模式(v0.7+ 推荐) ``` ### 问题4: 表单渲染报 "Cannot read properties of undefined (reading 'map')"