- 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]>
211 lines
10 KiB
Markdown
211 lines
10 KiB
Markdown
# 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 自己另写一份不完整的 |
|