用户拍板 (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).
15 KiB
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: 2sysForm/Form.vue第 144-145 行:type: 2, webType: 1formDesign/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 改动:
-
加
dacli app context --json命令 — AI 每次开干第一步先跑这个,消灭 B/C/D 三类问题的 60%+ -
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/ 源码权威 |