Files
dacli/doc/ai-optimization-plan.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

398 lines
15 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
> 前置文档:[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/ 源码权威** |