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

211 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](./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 自己另写一份不完整的 |