Files
dacli/docs/doc/deprecated/ai-optimization-plan.md
T
ssw 50ab7e2a2d chore(v0.11+): 归档 dacli/doc/ → dacli/docs/doc/deprecated/ (22 文件废弃)
用户拍板 (2026-06-25): dacli/doc/ 整个目录内容已废弃, 移到 dacli/docs/doc/deprecated/.

废弃原因:
1. v0.11+ webapi 镜像架构已替代所有 extract 脚本 + 静态 JSON 快照 (architecture.md api.md extractors.md 描述的方案过时)
2. 父 CLAUDE.md + dacli/CLAUDE.md 已合并, 不再需要独立 doc/ 维护
3. v0.11+ 30+ NEW-CMD + 18 webapi 模块, 旧 plan.md 描述的命令多数已废弃

22 文件全部 git mv (rename tracking 保留历史):
- architecture.md / plan.md / api.md / extractors.md / baseline.md / help-system.md (架构 6)
- ai-error-analysis.md / ai-optimization-plan.md (AI 分析 2)
- audit-form-create-deviations.md / RESUME.md / verify-form-create-fix.mjs (实战 3)
- v0.6 ~ v0.8.4-changelog.md (11 个版本变更日志)
- v0.8-endpoints.md / v0.8-plan.md / v0.8-scan.md (v0.8 文档 3)

新增 docs/doc/deprecated/README.md 说明废弃原因 + 内容索引 + 下一步指引.
新文档统一写到 docs/ (cmd-review + skill-audit + web-patches + v0.11-next-steps-plan.md + source-analysis.md).
2026-06-25 16:18:28 +08:00

15 KiB
Raw Blame History

dacli AI 辅助开发桥 — 优化方案

日期:2026-06-22 前置文档: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 命令

命令定义:

dacli app context [--json] [--app tds|tdc]

输出内容:

{
  "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 返回的模糊错误后,自动执行诊断检查,将模糊错误翻译为具体可能原因。

实现方案:

// 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

设计:在命令执行前自动验证依赖条件,不满足则明确报错。

// 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 应从这些源码事实推导,而非靠文档记忆拼凑。

{
  "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 顶部(优先级高于所有其他规则)加入:

## ⚠️ 权威参照规则 (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/ 源码位置:

| 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/ 源码的精确行号:

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 条,转化为运行时检查。

// 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/ 源码权威