用户拍板 (2026-06-25): dacli/doc/ 整个目录内容已废弃, 移到 dacli/docs/doc/deprecated/. 废弃原因: 1. v0.11+ webapi 镜像架构已替代所有 extract 脚本 + 静态 JSON 快照 (architecture.md api.md extractors.md 描述的方案过时) 2. 父 CLAUDE.md + dacli/CLAUDE.md 已合并, 不再需要独立 doc/ 维护 3. v0.11+ 30+ NEW-CMD + 18 webapi 模块, 旧 plan.md 描述的命令多数已废弃 22 文件全部 git mv (rename tracking 保留历史): - architecture.md / plan.md / api.md / extractors.md / baseline.md / help-system.md (架构 6) - ai-error-analysis.md / ai-optimization-plan.md (AI 分析 2) - audit-form-create-deviations.md / RESUME.md / verify-form-create-fix.mjs (实战 3) - v0.6 ~ v0.8.4-changelog.md (11 个版本变更日志) - v0.8-endpoints.md / v0.8-plan.md / v0.8-scan.md (v0.8 文档 3) 新增 docs/doc/deprecated/README.md 说明废弃原因 + 内容索引 + 下一步指引. 新文档统一写到 docs/ (cmd-review + skill-audit + web-patches + v0.11-next-steps-plan.md + source-analysis.md).
10 KiB
dacli AI 辅助开发桥 — 问题诊断报告
日期:2026-06-22 对象:dacli(TypeScript 版)+ JNPF 低代码平台 背景:AI 在使用 dacli 进行 JNPF 开发时频繁出错(误用参数、重复报错、跳步执行)
一、问题全景
经分析,AI 误用/重复出错并非单点问题,而是 6 类根因 交织导致的系统性故障:
| 类别 | 根因 | 表现 | 严重度 |
|---|---|---|---|
| A | 上下文爆炸 | 文档越写越长,AI 越用越懵 | 🟣 高 |
| B | 状态感知缺失 | AI 盲猜当前环境参数 | 🟠 高 |
| C | 错误反馈模糊 | 同一报错 10 种根因,AI 无法定位 | 🔴 极高 |
| D | 隐式依赖链 | 流程步骤只在文档里,没有工具强制 | 🟢 中 |
| E | 长任务副作用 | "不停下来问"变成"错了继续" | 🔵 中 |
| F | Schema 驱动不完整 | JSON 有了,决策逻辑仍是自然语言 | 🟢 中 |
二、逐类详细诊断
A 🟣 上下文爆炸 — 文档越写越长,AI 越用越懵
现状:
- SKILL.md: 597 行
- troubleshooting.md: 1063 行
- anti-patterns.md: 413 行
- commands.md: 568 行
- 总量 2600+ 行,每次新会话 AI 要么加载不全,要么不知道哪条校准最新
关键矛盾:
v0.9 关键校准覆盖了v0.8.4,但二者都在 SKILL.md 顶部,AI 没有明确信号知道"先读 v0.9"- CLAUDE.md
已知盲点表格到 52 条,每次新会话 AI 要把这 52 条全读进去 - troubleshooting.md 是历史问题流水账,不是决策树
实质:文档是给人看的历史记录,不是给 AI 用的决策系统。AI 需要的是"当前有效规则 + 精确触发条件",而非"所有曾经犯过的错排在一起"。
B 🟠 状态感知缺失 — AI 盲猜当前环境
现状:没有一个命令能告诉 AI 当前环境状态:
- 当前 tds 应用下,有哪些 enCode 已存在?
- 哪些 form 已发布、哪些未发布?
- dbLinkId 是什么?
- Token 是否过期?
典型错误链:
- AI 猜 enCode 没占用 → "Encoding cannot be repeated"(盲点 49)
- AI 猜 form 已 release → 绑 menu 失败
- AI 猜 dbLinkId=0 → "Database exception"(盲点 48)
实质:缺少 dacli app context(环境快照命令)。AI 每次靠"推理"而非"查询"来确定参数值,推理的前提信息不完整。
C 🔴 错误反馈模糊 — 同一个报错,10 种根因
现状: "Database exception" 在 JNPF 后端覆盖了所有 DB 层异常,实际对应:
- dbLinkId 错误
- tables 缺字段
- category 不匹配
- enCode 重复
- 字段类型不兼容
- ……等等
现有应对:
- troubleshooting.md 列出了所有可能原因(1063 行)
- 但它是离线文档,AI 报错后要翻 1063 行才能找到对应项
- AI 通常直接翻最近的几条,遗漏真正的根因
实质:dacli 应该在 catch 里做主动诊断,把 "Database exception" 翻译成 "可能原因:①dbLinkId ②tables ③enCode" 直接输出,而不是让 AI 去 2600 行文档里猜。
D 🟢 隐式依赖链 — 流程步骤文档描述,没有工具强制
现状:
form create 依赖已存在的 DM 表 → 但这个先决条件只写在 anti-patterns,没有在命令执行时检查。
典型失败链:
- AI 直接
form create(DM 表不存在) - JNPF 返回模糊报错
- AI 根据 troubleshooting 猜测原因,猜错方向
- 重复尝试其他参数组合
- 最终放弃或制造脏数据
实质:dacli form create 应该内置 --pre-check 逻辑,执行前验证依赖是否满足,不满足则明确报错并提示下一步。
E 🔵 长任务模式副作用 — "不停下来问"变成"错了继续"
现状:
prompt.md写着**"非必要不要中断,自己驱动完成"**- CLAUDE.md 同样鼓励长流程一次性完成
副作用:
- AI 假设某个 type 参数,跑失败了,写进"已知遗留"继续
- 52 条盲点中相当一部分是这样积累的
- 每次新会话 AI 要把这 52 条全读进去,消耗上下文
实质:长任务模式把"快速推进"和"错误积累"捆绑在一起,需要分离。应该是"自驱推进 + 定期自检",而非"自驱推进 + 错了也不停"。
F 🟢 Schema 黆动不完整 — JSON 有了,决策逻辑没有
现状:
field-schemas.json很好,解决了 53 个 FieldBuilder 的问题- 但
type × webType × enableFlow的合法组合矩阵仍是自然语言 - 哪种场景用 clone 哪种用 create,是文档描述而非代码枚举
- 报表/门户是否需要物理表,是常识而非规则
实质:决策规则应该机器可读(JSON 或代码内枚举),而不是文档可读。AI 靠读自然语言来猜参数组合,猜错率不可避免。
三、52 条盲点分布统计
| 严重度 | 数量 | 主要类别 |
|---|---|---|
| 🔴 必须修复 | ~15 | dbLinkId 错误、enCode 重复、form 未发布 |
| 🟠 经常触发 | ~20 | 参数组合错误、流程跳步、状态不一致 |
| 🟡 偶发 | ~17 | 边界情况、特定 type 特殊处理 |
高频盲点集中在前两类,与 B/C/D 三类根因高度重合。
四、总结
核心矛盾:dacli 当前是"工具 + 文档"架构,AI 需要的是"工具 + 状态 + 诊断"架构。
文档能告诉 AI "应该怎么做",但不能告诉 AI "现在是什么状态"和"为什么出错了"。缺少后两者,AI 只能靠猜测补充信息,猜测失误 = 误用 = 重复出错。
下一步:参见 ai-optimization-plan.md
五、G 类根因(新增) — 舍近求远:无视 web/ 源码中的"教科书"
G 🔴🔴 舍近求远 — AI 无视 JNPF 前端源码,凭空编造参数
这是最荒诞也最严重的根因,直接导致了 B/C/D/F 四类问题的存在。
问题本质
JNPF 是以人类操作为核心的低代码平台。人类用户怎么创建表单?打开浏览器 → 填字段 → 选下拉 → 点按钮提交。每一步的正确参数、默认值、校验规则、API 端点,都写在前端源码里。
但 dacli 的 skill 文档完全无视这些源码,试图用自然语言"翻译"一遍——翻译得不准确、不完整、不及时。AI 不看原著,看的是一份充满错误的译本。
web/ 源码里有什么(AI 看不见的"教科书")
| 内容 | 位置 | dacli 文档对应 | 差异 |
|---|---|---|---|
| 表单创建的完整字段定义 + 默认值 | views/onlineDev/formDesign/Form.vue schemas |
commands.md 逐条人肉描述 | web/ 默认值精确(type:1, webType:2, dbLinkId:'0');commands.md 只写了"必填"标签 |
| sysForm(报表/门户)的完整字段 | views/onlineDev/sysForm/Form.vue schemas |
commands.md 单独描述 | web/ 明确 type:2, webType:1;commands.md 遗漏了 type/webType 默认值关系 |
| 字段唯一性校验逻辑 | sysForm/FieldForm.vue exist() 函数 |
anti-patterns.md 盲点 49 | web/ 代码是可执行逻辑;anti-patterns 是事后补救文档 |
| dbLinkId 选择 + onChange 清空 tables | Form.vue onDbChange() |
troubleshooting.md 盲点 48 | web/ 明确逻辑:切换 dbLinkId → 清空已选表;dacli 完全没有这个机制 |
| 发布菜单的完整流程 | formDesign/components/CreateMenuModal.vue |
commands.md 简单描述 | web/ 有 getReleaseMenu → 验证 pcIsRelease/appIsRelease → createMenu;dacli 只写了 menu create |
| AI 建表的原生实现 | formDesign/components/AiCreateModal.vue |
完全缺失 | web/ 已有 getAiInfo({keyword}) → 返回完整表单配置;dacli 的 form create 从零拼接 JSON |
| 所有 API 端点路径 | api/onlineDev/visualDev.ts + api/systemData/dataModel.ts |
commands.md 列出部分 | web/ 有 40+ 个端点精确路径;commands.md 只覆盖了 dacli 已实现的 ~15 个 |
| 数据源选择器 API | api/systemData/dataSource.ts |
完全缺失 | web/ 有 getDataSourceSelector() 可直接拿 dbLinkId 选项列表 |
"舍近求远"的具体表现
场景 1:AI 猜 type/webType 参数
- web/
formDesign/Form.vue第 107-108 行:type: 1, webType: 2(普通表单默认值) - web/
sysForm/Form.vue第 144-145 行:type: 2, webType: 1(报表默认值) - dacli 文档:用自然语言描述"type 1=普通表单, type 2=报表, webType 1=纯表单, webType 2=表单+列表" → AI 仍需组合推理,且不知道默认值
场景 2:AI 猜 dbLinkId
- web/
Form.vue第 146 行:dbLinkId: '0'是默认值,第 81 行 schema 有onChange: onDbChange - web/
onDbChange(): 切换数据连接时清空已选表列表 - web/
getDbOptions(): 调用getDataSourceSelector()获取可用连接列表 - dacli:AI 根本不知道
getDataSourceSelector()API 存在,每次硬编码 dbLinkId 或盲猜
场景 3:AI 猜字段校验规则
- web/
FieldForm.vue第 46-56 行:exist()函数检查 fieldName 非空、fieldId 非空、fieldId 不重复 - dacli:盲点 49(enCode 重复)是事后发现的经验,不是从校验逻辑推导出来的
场景 4:AI 拼接 form create JSON
- web/
AiCreateModal.vue:JNPF 原生就有 AI 建表功能!getAiInfo({keyword: '项目'})→ 后端返回完整表单配置 - dacli:AI 从零开始拼
tables/formData/columnDataJSON,每一步都可能出错
根因分析:为什么 AI 会"舍近求远"
- SKILL.md 没有指向 web/ 源码 — AI 不知道 web/ 存在,也不知道应该去看
- 文档优先级高于源码 — SKILL.md 说"读 commands.md",而非"去 web/src/api/ 对照 API 定义"
- dacli 命令封装隐藏了 API 路径 —
dacli form create是一层 CLI 封装,AI 不知道底层调用的是/api/visualdev/BasePOST,也就不会去源码找对应的前端实现 - 盲点积累模式 — 出错 → 记录到 troubleshooting → 下次读 troubleshooting → 但不读 web/ 源码验证 → 新的错误模式继续积累
对其他根因的影响
| 受影响的根因 | 舍近求远如何加剧 |
|---|---|
| B 状态感知 | web/ 有 getDataSourceSelector() 可查 dbLinkId 列表,dacli 完全没用 |
| C 错误反馈 | web/ 的 exist() 等校验逻辑是精确的"诊断规则",dacli 用模糊的自然语言替代 |
| D 隐式依赖 | web/ 的 onDbChange() 清空 tables 就是依赖链的强制逻辑,dacli 没有实现 |
| F Schema 驱动 | web/ 的 schemas 定义就是最精确的"决策规则 JSON",dacli 自己另写一份不完整的 |