Files
dacli/doc/ai-error-analysis.md
T
sswandClaude a5063bb115 fix(blindspot): BS-5 + BS-47 false-positive (jxcj 28 form 重跑实战)
- BS-5: 仅 ctx 完全缺失时阻塞, 不再因 existingEnCodes.length===0 误报
  (场景: 全删 form 后重建, AppContext 仍有但 list 空, 旧逻辑会无限循环阻断)
- BS-47: 仅 dict typeCreate 命令触发, 不再在 menu create 时误判
  (场景: menu enCode 与 form enCode 共享合法, 但 BS-47 把 form enCode 看作 dict 冲突)

Co-Authored-By: Claude <[email protected]>
2026-06-22 23:42:47 +08:00

10 KiB
Raw Blame History

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 是否过期?

典型错误链:

  1. AI 猜 enCode 没占用 → "Encoding cannot be repeated"(盲点 49)
  2. AI 猜 form 已 release → 绑 menu 失败
  3. 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,没有在命令执行时检查。

典型失败链:

  1. AI 直接 form create(DM 表不存在)
  2. JNPF 返回模糊报错
  3. AI 根据 troubleshooting 猜测原因,猜错方向
  4. 重复尝试其他参数组合
  5. 最终放弃或制造脏数据

实质: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/columnData JSON,每一步都可能出错

根因分析:为什么 AI 会"舍近求远"

  1. SKILL.md 没有指向 web/ 源码 — AI 不知道 web/ 存在,也不知道应该去看
  2. 文档优先级高于源码 — SKILL.md 说"读 commands.md",而非"去 web/src/api/ 对照 API 定义"
  3. dacli 命令封装隐藏了 API 路径 — dacli form create 是一层 CLI 封装,AI 不知道底层调用的是 /api/visualdev/Base POST,也就不会去源码找对应的前端实现
  4. 盲点积累模式 — 出错 → 记录到 troubleshooting → 下次读 troubleshooting → 但不读 web/ 源码验证 → 新的错误模式继续积累

对其他根因的影响

受影响的根因 舍近求远如何加剧
B 状态感知 web/ 有 getDataSourceSelector() 可查 dbLinkId 列表,dacli 完全没用
C 错误反馈 web/ 的 exist() 等校验逻辑是精确的"诊断规则",dacli 用模糊的自然语言替代
D 隐式依赖 web/ 的 onDbChange() 清空 tables 就是依赖链的强制逻辑,dacli 没有实现
F Schema 驱动 web/ 的 schemas 定义就是最精确的"决策规则 JSON",dacli 自己另写一份不完整的