# 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 自己另写一份不完整的 |