- 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]>
398 lines
15 KiB
Markdown
398 lines
15 KiB
Markdown
# dacli AI 辅助开发桥 — 优化方案
|
||
|
||
> 日期:2026-06-22
|
||
> 前置文档:[ai-error-analysis.md](./ai-error-analysis.md)
|
||
> 目标:消除 AI 误用/重复出错,提升 dacli 作为 AI 开发桥的可靠性
|
||
|
||
---
|
||
|
||
## 一、优化总览(按 ROI 排序)
|
||
|
||
| 优先级 | 方向 | 解决的问题 | 预估工作量 |
|
||
|--------|------|-----------|-----------|
|
||
| **P0** | 增加 `dacli app context` 命令 | B 状态感知 + C 错误反馈 + D 隐式依赖 | 2-3 天 |
|
||
| **P0** | client 层主动诊断 | C 错误反馈模糊 | 1-2 天 |
|
||
| **P0** | **web/ 源码参照机制** — SKILL.md 强制指向 web/ | G 舍近求远 + B/C/D/F 联合根因 | 1 天 |
|
||
| **P1** | SKILL.md 瘦身 + 分层加载 | A 上下文爆炸 | 1 天 |
|
||
| **P1** | `form create / dm create` 内置 pre-check | D 隐式依赖链 | 1 天 |
|
||
| **P1** | type 参数决策树 JSON 化(**从 web/ 源码提取**) | F Schema 驱动不完整 + G 舍近求远 | 1-2 天 |
|
||
| **P2** | 盲点提炼为代码内 guard(**对照 web/ 校验逻辑**) | A+D 文档→代码 + G 舍近求远 | 1 天 |
|
||
| **P2** | 长任务模式加"自检 checkpoint" | E 长任务副作用 | 半天 |
|
||
|
||
---
|
||
|
||
## 二、P0 方案详细设计
|
||
|
||
### 2.1 `dacli app context` 命令
|
||
|
||
**命令定义**:
|
||
```bash
|
||
dacli app context [--json] [--app tds|tdc]
|
||
```
|
||
|
||
**输出内容**:
|
||
```json
|
||
{
|
||
"appCode": "jnpf_app_tds",
|
||
"dbLinkId": "446561733648563553",
|
||
"tokenStatus": "valid",
|
||
"tokenExpiry": "2026-06-22T18:00:00",
|
||
"existingEnCodes": ["Prj001", "Prj002", "UserMgmt", ...],
|
||
"unreleasedForms": ["form_Prj003", ...],
|
||
"releasedForms": ["form_Prj001", "form_Prj002"],
|
||
"existingTables": ["Prj_Data", "User_Info", ...],
|
||
"menus": ["Prj001", "Prj002"],
|
||
"currentVersion": "0.9"
|
||
}
|
||
```
|
||
|
||
**实现要点**:
|
||
- 调用 `client.getAppInfo()` 获取 app 基本信息
|
||
- 调用 `form.list()` 拿所有 form,区分 published/unpublished
|
||
- 调用 `dm.list()` 拿已存在的表列表
|
||
- 调用 `menu.list()` 拿已有菜单 enCode
|
||
- 整合为单一 JSON 输出
|
||
|
||
**AI 使用方式**:
|
||
- SKILL.md 第一条规则改为:**"每次新会话,先执行 `dacli app context --json`,所有参数从此快照取"**
|
||
- 这一条替换当前 "先读 CLAUDE.md → 再读 SKILL.md → 再翻 troubleshooting" 的流程
|
||
|
||
**解决的盲点**:
|
||
- 盲点 48(dbLinkId=0)→ context 直接给出正确 dbLinkId
|
||
- 盲点 49(enCode 重复)→ context 列出已有 enCode,AI 不再猜
|
||
- form 发布状态盲点 → context 区分 published/unpublished
|
||
|
||
---
|
||
|
||
### 2.2 client 层主动诊断
|
||
|
||
**设计思路**:
|
||
在 `src/core/client.ts` 的错误处理中,catch 到 JNPF API 返回的模糊错误后,自动执行诊断检查,将模糊错误翻译为具体可能原因。
|
||
|
||
**实现方案**:
|
||
|
||
```typescript
|
||
// src/core/client.ts - 新增 diagnoseError 方法
|
||
async diagnoseError(errorMsg: string, context: AppContext): string[] {
|
||
if (errorMsg.includes('Database exception')) {
|
||
const possibleCauses: string[] = [];
|
||
// 检查 1: dbLinkId 是否匹配
|
||
if (!context.dbLinkId || context.dbLinkId === '0') {
|
||
possibleCauses.push(`dbLinkId 未设置或为 0,当前正确值: ${context.dbLinkId}`);
|
||
}
|
||
// 检查 2: enCode 是否重复
|
||
if (context.existingEnCodes.includes(this.lastRequestEnCode)) {
|
||
possibleCauses.push(`enCode "${this.lastRequestEnCode}" 已存在,请更换`);
|
||
}
|
||
// 检查 3: 目标表是否存在
|
||
if (!context.existingTables.includes(this.lastRequestTableName)) {
|
||
possibleCauses.push(`表 "${this.lastRequestTableName}" 不存在,需先 dm create`);
|
||
}
|
||
return possibleCauses;
|
||
}
|
||
|
||
if (errorMsg.includes('Encoding cannot be repeated')) {
|
||
return [`enCode "${this.lastRequestEnCode}" 已存在于: ${context.existingEnCodes.filter(e => e === this.lastRequestEnCode)}`];
|
||
}
|
||
|
||
// 其他已知模糊错误类似处理...
|
||
return [`未识别的模糊错误,建议执行 dacli app context 更新环境快照`];
|
||
}
|
||
```
|
||
|
||
**调用方式**:
|
||
- `dacli form create` 失败时,自动调用 `diagnoseError()` 输出诊断
|
||
- AI 看到的是:"Database exception → 可能原因:①enCode 'Prj001' 已存在 ②表 'Prj_Data' 不存在",而非原始模糊报错
|
||
|
||
**解决的盲点**:
|
||
- 几乎所有 "Database exception" 类盲点(约 15 条)都被覆盖
|
||
- enCode 重复类盲点直接定位
|
||
|
||
---
|
||
|
||
## 三、P1 方案详细设计
|
||
|
||
### 3.1 SKILL.md 瘦身 + 分层加载
|
||
|
||
**当前问题**:SKILL.md 597 行,AI 每次全量加载,信息密度低。
|
||
|
||
**目标结构**:
|
||
|
||
```
|
||
SKILL.md (≤80 行)
|
||
├── 版本号 v0.9
|
||
├── 最高频 10 条命令速查
|
||
├── 3 个跳转指针(按需加载)
|
||
│ ├── → dacli doc get commands (详细命令文档)
|
||
│ ├── → dacli doc get patterns (反模式与校准)
|
||
│ └── → dacli doc get errors (错误诊断)
|
||
└── 强制规则(≤10 条):先跑 context、不猜参数、失败先诊断
|
||
|
||
references/
|
||
├── commands.md (保持不变)
|
||
├── patterns.md (anti-patterns + v0.9 校准合并)
|
||
├── errors.md (troubleshooting 精简为决策树格式)
|
||
```
|
||
|
||
**新增命令**:`dacli doc get <topic>` — AI 按需拉取详细文档,而非一次性全加载。
|
||
|
||
**关键改动**:
|
||
- troubleshooting.md 从 1063 行流水账 → 精简为**决策树格式**(错误 → 检查项 → 可能原因 → 修复步骤)
|
||
- anti-patterns.md + v0.9 校准合并为 patterns.md,去掉历史覆盖关系
|
||
- 52 条盲点不放进 SKILL.md,转成代码内 guard(见 P2 方案)
|
||
|
||
---
|
||
|
||
### 3.2 `form create / dm create` 内置 pre-check
|
||
|
||
**设计**:在命令执行前自动验证依赖条件,不满足则明确报错。
|
||
|
||
```typescript
|
||
// src/commands/form/_precheck.ts
|
||
async preCheckFormCreate(options: FormCreateOptions, context: AppContext): PreCheckResult {
|
||
const errors: string[] = [];
|
||
|
||
// 检查 1: enCode 不重复
|
||
if (context.existingEnCodes.includes(options.enCode)) {
|
||
errors.push(`enCode "${options.enCode}" 已存在,请更换`);
|
||
}
|
||
|
||
// 检查 2: 目标表存在(form 依赖 DM 表)
|
||
if (options.tableName && !context.existingTables.includes(options.tableName)) {
|
||
errors.push(`表 "${options.tableName}" 不存在,需先执行 dacli dm create`);
|
||
}
|
||
|
||
// 检查 3: dbLinkId 有效
|
||
if (!context.dbLinkId || context.dbLinkId === '0') {
|
||
errors.push(`dbLinkId 未设置,请先执行 dacli app context`);
|
||
}
|
||
|
||
return { pass: errors.length === 0, errors };
|
||
}
|
||
```
|
||
|
||
**调用方式**:
|
||
- `dacli form create` 执行前先跑 pre-check
|
||
- pre-check 失败 → 打印具体原因 → 退出(不执行创建)
|
||
- pre-check 通过 → 正常执行
|
||
|
||
---
|
||
|
||
### 3.3 type 参数决策树 JSON 化
|
||
|
||
**目标文件**:`data/form-type-rules.json`
|
||
|
||
**⚠️ 核心原则:从 web/ 源码提取,而非凭空编写。**
|
||
|
||
web/ 源码中已包含所有 type/webType 的精确默认值:
|
||
- `formDesign/Form.vue` 第 107-108 行:`type: 1, webType: 2`
|
||
- `sysForm/Form.vue` 第 144-145 行:`type: 2, webType: 1`
|
||
- `formDesign/Form.vue` 第 178 行:`webType == 4 ? maxStep=1 : maxStep=2`
|
||
|
||
决策树 JSON 应从这些源码事实推导,而非靠文档记忆拼凑。
|
||
|
||
```json
|
||
{
|
||
"typeRules": [
|
||
{
|
||
"type": 1, "webType": 1, "name": "普通表单",
|
||
"needsPhysicalTable": true, "canRelease": true,
|
||
"clonePreferred": false, "enableFlowOptions": [false]
|
||
},
|
||
{
|
||
"type": 1, "webType": 2, "name": "流程表单",
|
||
"needsPhysicalTable": true, "canRelease": true,
|
||
"clonePreferred": false, "enableFlowOptions": [true]
|
||
},
|
||
{
|
||
"type": 2, "webType": 3, "name": "报表",
|
||
"needsPhysicalTable": false, "canRelease": true,
|
||
"clonePreferred": true, "enableFlowOptions": [false]
|
||
},
|
||
{
|
||
"type": 3, "webType": 4, "name": "门户",
|
||
"needsPhysicalTable": false, "canRelease": true,
|
||
"clonePreferred": true, "enableFlowOptions": [false]
|
||
}
|
||
],
|
||
"decisionRules": {
|
||
"ifNeedsPhysicalTable": "先 dm create,再 form create",
|
||
"ifNoPhysicalTable": "直接 form create,tables 填虚拟表名",
|
||
"ifClonePreferred": "优先用 form clone 已有模板,而非 create",
|
||
"ifEnableFlowTrue": "必须设置 enableFlow=true + flowTemplate"
|
||
}
|
||
}
|
||
```
|
||
|
||
**AI 使用方式**:
|
||
- AI 根据目标 type,查询决策树,直接取参数值
|
||
- 不再靠读自然语言来猜 `type × webType` 组合
|
||
|
||
---
|
||
|
||
## 四、P0 方案(新增) — web/ 源码参照机制
|
||
|
||
### 4.0 强制 AI 参照 web/ 源码(根因 G 对策)
|
||
|
||
**这是解决"舍近求远"的核心理念转变**:
|
||
|
||
当前 dacli skill 的信息来源是"自己写的文档" → 应该改为"web/ 源码是权威参考,文档只做导航"。
|
||
|
||
#### 4.0.1 SKILL.md 增加强制参照规则
|
||
|
||
在 SKILL.md 顶部(优先级高于所有其他规则)加入:
|
||
|
||
```markdown
|
||
## ⚠️ 权威参照规则 (v0.10+)
|
||
|
||
**任何 JNPF 相关参数、API 路径、默认值、校验逻辑,必须优先从 web/ 源码提取。**
|
||
|
||
参照顺序:
|
||
1. `web/apps/jnpf-web-apps-main/src/api/` — API 端点定义(权威)
|
||
2. `web/apps/jnpf-web-apps-main/src/views/onlineDev/` — 表单创建/编辑的完整逻辑(权威)
|
||
3. `dacli commands.md / patterns.md` — 仅作为导航索引,不是最终答案
|
||
4. 自己的推理 — 最后选择,必须与 web/ 源码对照验证
|
||
|
||
核心参照文件:
|
||
- `views/onlineDev/formDesign/Form.vue` → form 创建的精确字段默认值
|
||
- `views/onlineDev/sysForm/Form.vue` → 报表/门户创建的精确字段默认值
|
||
- `api/onlineDev/visualDev.ts` → 所有 visualdev API 端点
|
||
- `api/systemData/dataModel.ts` → 数据模型 API 端点
|
||
- `api/systemData/dataSource.ts` → 数据连接选择器(获取 dbLinkId 选项)
|
||
- `formDesign/components/CreateMenuModal.vue` → 发布菜单完整流程
|
||
- `formDesign/components/AiCreateModal.vue` → JNPF 原生 AI 建表功能
|
||
|
||
**如果 dacli commands.md 与 web/ 源码不一致,以 web/ 源码为准。**
|
||
```
|
||
|
||
#### 4.0.2 从 web/ 源码提取"教科书式"参考索引
|
||
|
||
生成一个精简的 `references/web-source-map.md`,列出每个 dacli 命令对应的 web/ 源码位置:
|
||
|
||
```markdown
|
||
| dacli 命令 | web/ 权威源码 | 关键提取内容 |
|
||
|-----------|-------------|-------------|
|
||
| form create | views/onlineDev/formDesign/Form.vue (line 103-114) | type=1, webType=2, dbLinkId='0', 完整 schema 定义 |
|
||
| form create (报表/门户) | views/onlineDev/sysForm/Form.vue (line 140-151) | type=2, webType=1, enableFlow 条件字段 |
|
||
| form release + menu create | formDesign/components/CreateMenuModal.vue | pcIsRelease/appIsRelease 验证逻辑, platformRelease JSON |
|
||
| dm create | api/systemData/dataModel.ts (line 20-24) | POST /api/system/DataModel/{linkId}/Table |
|
||
| form list | api/onlineDev/visualDev.ts (line 16) | GET /api/visualdev/Base |
|
||
| AI 建表 | formDesign/components/AiCreateModal.vue | getAiInfo({keyword}) → 完整表单配置 |
|
||
| dbLinkId 选择 | api/systemData/dataSource.ts (line 13) | getDataSourceSelector() → 可用连接列表 |
|
||
| 字段校验 | sysForm/FieldForm.vue (line 46-56) | exist() → fieldName/fieldId 非空 + fieldId 不重复 |
|
||
```
|
||
|
||
#### 4.0.3 dacli 命令增加 `--source` 精确定位
|
||
|
||
当前 `--source` 只输出"参考了哪些文档"。改为输出 web/ 源码的**精确行号**:
|
||
|
||
```bash
|
||
dacli form create --source
|
||
# 输出:
|
||
# form create 参数定义源自:
|
||
# web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:103-114
|
||
# 默认值: type=1, webType=2, dbLinkId='0'
|
||
# 校验规则源自: sysForm/FieldForm.vue:46-56
|
||
```
|
||
|
||
这样 AI 验证参数时可以直接对照源码,而非信任文档。
|
||
|
||
#### 4.0.4 从 web/ 源码自动生成参数定义 JSON
|
||
|
||
编写一个脚本 `scripts/extract-web-schema.py`,从 web/ Vue 源码中自动提取:
|
||
- 所有 form schema 的字段定义(field, label, component, defaultValue, rules)
|
||
- 所有 API 端点的路径和参数
|
||
- 所有校验函数的逻辑
|
||
|
||
输出为 `data/web-derived-schemas.json`,AI 和 dacli 命令直接读取这个 JSON 作为参数定义的权威来源。
|
||
|
||
**优势**:
|
||
- web/ 源码更新时,重新跑脚本即可同步,无需人工维护文档
|
||
- AI 不需要读 2600 行自然语言文档,直接读机器可读的 JSON
|
||
- 消除文档与源码不一致的根本原因
|
||
|
||
---
|
||
|
||
## 五、P2 方案
|
||
|
||
### 4.1 盲点提炼为代码内 guard
|
||
|
||
**设计**:从 52 条盲点中取高频 20 条,转化为运行时检查。
|
||
|
||
```typescript
|
||
// src/commands/_blindspots.ts
|
||
export const BLINDSPOT_GUARDS: BlindspotGuard[] = [
|
||
{
|
||
id: 48, trigger: 'dbLinkId=0 或未设置',
|
||
check: (ctx) => ctx.dbLinkId === '0' || !ctx.dbLinkId,
|
||
message: 'dbLinkId 必须为有效值,请从 dacli app context 获取'
|
||
},
|
||
{
|
||
id: 49, trigger: 'enCode 重复',
|
||
check: (ctx, opts) => ctx.existingEnCodes.includes(opts.enCode),
|
||
message: 'enCode 已存在,请更换唯一标识'
|
||
},
|
||
// ... 其余 18 条
|
||
];
|
||
```
|
||
|
||
**效果**:盲点从文档变为代码,AI 不需要"记住 52 条盲点",而是 dacli 自己在执行时检查。
|
||
|
||
### 4.2 长任务模式加自检 checkpoint
|
||
|
||
**设计**:在 SKILL.md 中增加规则:
|
||
|
||
```
|
||
长任务自检规则:
|
||
- 每 5 个命令执行后,强制跑 `dacli form validate` + `npx tsc --noEmit`
|
||
- 自检失败 → 暂停,输出诊断,等待确认再继续
|
||
- 自检通过 → 自动继续下一个命令组
|
||
```
|
||
|
||
**效果**:将"自驱推进"与"错误积累"解耦。AI 可以连续执行,但每 5 步强制验证一次,避免错误雪崩。
|
||
|
||
---
|
||
|
||
## 六、实施路线图
|
||
|
||
```
|
||
Phase 1 (4-5 天): P0 — 消灭最高频错误 + 建立源码参照
|
||
├── Day 1: 实现 dacli app context 命令
|
||
├── Day 2: 实现 client 层主动诊断
|
||
├── Day 3: SKILL.md 加入强制参照 web/ 规则 + web-source-map.md
|
||
├── Day 4: extract-web-schema.py 脚本 + web-derived-schemas.json 生成
|
||
└── Day 5: 集成测试,验证盲点 48/49 覆盖 + 对照 web/ 验证参数
|
||
|
||
Phase 2 (3-4 天): P1 — 减少上下文消耗与流程跳步
|
||
├── Day 1: SKILL.md 瘦身 + 分层加载重构
|
||
├── Day 2: form/dm create 内置 pre-check(逻辑对照 web/ 校验)
|
||
├── Day 3: form-type-rules.json(从 web/ 源码提取,非凭空编写)
|
||
└── Day 4: 全流程验证
|
||
|
||
Phase 3 (1-2 天): P2 — 长期健壮性
|
||
├── Day 1: 20 条高频盲点 → 代码 guard(对照 web/ 校验逻辑)
|
||
├── Day 2: 长任务自检规则写入 SKILL.md
|
||
```
|
||
|
||
---
|
||
|
||
## 七、最高价值的单点改动
|
||
|
||
**两个并列最高 ROI 改动:**
|
||
|
||
1. **加 `dacli app context --json` 命令** — AI 每次开干第一步先跑这个,消灭 B/C/D 三类问题的 60%+
|
||
|
||
2. **SKILL.md 加入强制参照 web/ 规则** — 一句话:"参数不确定时,去 web/src/views/ 和 web/src/api/ 找答案,不靠文档猜"。消灭 G 类"舍近求远"根因,同时使 A/C/F 的文档从"权威"降为"导航索引"
|
||
|
||
---
|
||
|
||
## 八、预期效果
|
||
|
||
| 指标 | 当前 | Phase 1 后 | Phase 2 后 |
|
||
|------|------|-----------|-----------|
|
||
| AI 首次成功率 | ~40% | ~70% | ~90% |
|
||
| 重复报错次数/会话 | 3-5 次 | 0-1 次 | 0 次 |
|
||
| 上下文消耗(token) | 2600 行文档 | 80 行 + 按需 + web/ 参照 | 80 行 + web-derived-schemas.json |
|
||
| 盲点数量(文档) | 52 条 | 52 条(但高频 15 条被代码覆盖) | 20 条 guard + web/ 参照替代其余 |
|
||
| 参数来源 | 文档猜测 | context 命令 + 文档 | context 命令 + **web/ 源码权威** |
|