- resolve 10 merge conflicts across 4 files (app/init, dict/typecreate, form/create, webapi/_defhttp) - fix syntax errors in typecreate.ts (commented-out if block) - add ADR-0010: dacli v2 self-correcting CLI architecture design - add simulation test comparing v1 vs v2 behavior Co-Authored-By: Claude <[email protected]>
17 KiB
17 KiB
ADR-0010: dacli v2 — 自修正 CLI 架构
日期: 2026-07-20 状态: 草案 决策者: 基于 jxcj M1 实战复盘 + JNPF 源码分析 + ssw-loop 优化讨论
1. 问题陈述
1.1 当前 dacli 的核心问题
dacli v0.x-v1.x 积累了 46,923 行 TypeScript,但存在三个结构性问题:
| # | 问题 | 表现 | 根因 |
|---|---|---|---|
| 1 | 知识与工具分离 | 同一规则出现在 CLAUDE.md / ssw-loop references / anti_patterns.ts / blindspot_guards.ts / decisions/ / debug.md 共 7 处 | 知识存储位置错位,没有单一真值源 |
| 2 | 检测但不修正 | 22 个 blindspot guard 只 WARN 不修,AI 需要读懂 WARN → 翻译成操作 → 重试 | 防御层设计目标是"提醒"而非"修复" |
| 3 | 输出不分级 | step machine 校验、autoStrip 通知、API 调用日志全部混在 stdout,AI 被淹没 | 没有日志分离机制 |
1.2 dacli 的定位
dacli 的用户是 AI(Claude),而非人类。AI 通过 dacli 替代人类在 JNPF 低代码平台上的基础操作。目标不是"完美配置"(人类可后续精细调整),而是"可运行":
- 表单能创建成功(API 200)
- 页面能打开(前端不崩溃)
- 数据能保存(数据库不报错)
- 列表能显示(不白屏)
1.3 JNPF 平台自身的做法
JNPF 的 AI 建表单(VisualAiServiceImpl.form())只有 150 行,5 条后处理规则。每一条都是防崩溃的,不是"好看"的:
| JNPF 规则 | 防什么 |
|---|---|
字段名含中文 → 重命名 {jnpfKey}_num{001} |
SQL 不支持中文列名 |
jnpfKey 不在白名单 → fallback input |
组件不存在,前端渲染崩溃 |
子表 radio/checkbox → select |
子表不支持这些组件 |
子表 editor/barcode → input |
同上 |
_fk 结尾字段 → 丢弃 |
JNPF 自己管外键,重复创建冲突 |
JNPF 的哲学:AI 起头 + 人类完善。AI 生成的不完美部分,人类在表单设计器里手动调整。
dacli 的差异化价值:在 JNPF 的基线之上,多修一层高置信度的改进(如 FK→relationForm、datetime→datePicker+format),让开发人员体验更好,但修错了可以一键回滚。
2. 设计原则
- 可运行优先于正确:静默修正和 assertive 修正必须保证"不修会崩溃或体验极差",不确定的不修
- 修了就能回滚:每条 assertive 修正提供精确的一行回滚命令
- AI 看结果,人看日志:stdout 只输出结果摘要 + 下一步操作。详细信息写入结构化日志
- 单一知识源:所有规则定义在 registry.ts,自动生成 fix 函数 + --help + guide
- 跟随 JNPF 不超越:后处理规则优先镜像 JNPF 源码,不自己发明 JNPF 没有的规则
3. 三级修正策略
3.1 概述
Silent (100% 确定) Assertive (高置信) Suggest (不确定)
自动修 自动修 不修
一行日志 通知 + 回滚命令 给候选选项
3.2 Silent 级(静默修正)
| # | 规则 | 触发条件 | 修正 | 来源 |
|---|---|---|---|---|
| S1 | enCode strip | 含 - _ 空格 |
自动去特殊字符 | BS-新38 |
| S2 | fullName soften | 含 - — _ |
自动替换为 · |
BS-新52 |
| S3 | 字段名含中文 | [一-龥] |
重命名 {jnpfKey}_num{001} |
JNPF VisualAiServiceImpl |
| S4 | jnpfKey 不在白名单 | 不在 JnpfKeyConsts | fallback input |
JNPF VisualAiServiceImpl |
| S5 | 子表不支持组件 | radio/checkbox/editor/barcode 等 | radio/checkbox→select, 其余→input | JNPF VisualAiServiceImpl |
| S6 | dbLinkId 无效 | '0' / '' / 'default' |
从 app context 解析业务库 | BS-48 |
| S7 | buildFormData 缺关键字段 | formId/renderKey 为空 | UUID 补全 | BS-51/52 |
| S8 | sortCode 缺失 | undefined/null | 默认 0 | 平台默认值 |
| S9 | enabledMark 缺失 | undefined/null | 默认 1 | 平台默认值 |
| S10 | _fk 后缀字段 | fieldName.endsWith('_fk') | 丢弃 | JNPF VisualAiServiceImpl |
3.3 Assertive 级(自动修正 + 通知 + 回滚)
| # | 规则 | 触发条件 | 修正 | 回滚命令 | 可靠性 |
|---|---|---|---|---|---|
| A1 | FK→relationForm | /^f_(.+)_id$/ 且 jnpfKey≠relationForm |
jnpfKey=relationForm, 从 form list 查 modelId | dacli form update <id> --set='[{"field":"f_x_id","jnpfKey":"inputNumber"}]' |
高(能找到关联表单) |
| A2 | datetime→datePicker | dataType=datetime 且 jnpfKey≠datePicker | jnpfKey=datePicker, format=yyyy-MM-dd HH:mm:ss | dacli form update <id> --set='[{"field":"f_x","jnpfKey":"timePicker"}]' |
极高 |
| A3 | date→datePicker | dataType=date 且 jnpfKey≠datePicker | jnpfKey=datePicker, format=yyyy-MM-dd | dacli form update <id> --set='[{"field":"f_x","jnpfKey":"input"}]' |
极高 |
| A4 | int+dictType→select | dataType=int 且 dictType 存在 且 jnpfKey≠select | jnpfKey=select | dacli form update <id> --set='[{"field":"f_x","jnpfKey":"inputNumber"}]' |
高(dictType 已验证存在) |
| A5 | timePicker→datePicker | jnpfKey=timePicker 且 dataType=datetime | jnpfKey=datePicker | dacli form update <id> --set='[{"field":"f_x","jnpfKey":"timePicker"}]' |
极高 |
3.4 Suggest 级(不修,给候选)
| # | 场景 | 提示内容 |
|---|---|---|
| G1 | FK 关联表有多个候选 | 列出匹配的 form enCode,让 AI 选 |
| G2 | int 字段无 dictType 但有多个匹配字典 | 列出候选字典 enCode/fullName |
| G3 | relationForm 回显列可选 | 列出关联表的字段,当前默认回显第一个文本字段 |
| G4 | 本表是否建 FK 字段 | 提醒:可在 description 中加"本表不建FK字段" |
| G5 | 多个相似表名 | f_team_info_id 匹配到 team_info 和 team_info_v2 |
3.5 修正结果汇总
Silent Assertive Suggest ← 级别
自动修 自动修 不修
不通知 通知+回滚 给候选
现在 dacli: 2 条 0 条 20 条 ← 几乎全是 WARN,AI 自己修
改后 dacli: 10 条 5 条 5 条 ← 自动修为主,AI 只处理不确定的
4. 日志分离
4.1 设计
stdout (AI 看) ~/.dacli/logs/{appCode}/ (人查)
结果摘要 + 修正计数 完整修正详情含回滚命令
下一步操作提示 原始请求/响应
错误信息 堆栈跟踪
时间线
4.2 日志存储
~/.dacli/logs/{appCode}/
├── {timestamp}-{command}-{enCode}.json
├── tail # 符号链接指向最新日志
└── index.jsonl # 行式索引,快速查询
4.3 日志命令
dacli log --last # 最近一次命令摘要
dacli log --last --detail # 含回滚命令、堆栈
dacli log --form=<enCode> # 按表单查历史
dacli log --level=fix # 只看修正记录
dacli log --since=2026-07-20 # 时间范围
4.4 输出对比
现在 (AI 看到 ~40 行):
$ dacli form create --ai "报名表,含 f_user_id..."
loadVisualDev.create formId=...
[BS-新38] enCode 含 `-`, auto strip: registration-form → registrationform
[BS-新52] fullName 含特殊符号, auto soften...
[step 0 基础信息] enCode=registrationform ✓
[step 1 平台唯一性] enCode 不冲突 ✓
[step 2 字典项] 0 items, skip
✓ step machine 校验通过 (3/3)
[BS-54] f_user_id jnpfKey=inputNumber 建议改为 relationForm,
因 f_*_id 关联字段需 relationForm 组件
[BS-60] f_start_time 缺 format, 建议 datePicker + format="yyyy-MM-dd HH:mm:ss"
[BS-61] f_status int+dictType jxcjcompetitionstatus 但 jnpfKey 不是 select
... (20+ 行省略)
✓ 表单创建: id=8471... enCode=registrationform
改后 (AI 看到 ~6 行):
$ dacli form create --ai "报名表,含 f_user_id、f_start_time、f_status..."
✓ registration_form 已创建 (id=8471...) 修正 5 处 建议 1 项
测试: dacli test run --formId=8471...
详情: dacli log --last
5. 知识注册中心(单一真值源)
5.1 设计
registry.ts (唯一知识定义)
│
├──→ 自动生成: fix 函数(_auto_fix.ts)
├──→ 自动生成: --help 输出
├──→ 自动生成: dacli guide 输出
├──→ 自动生成: decisions/*.md 文档
└──→ 编译时检查: 与 JNPF 源码一致性
5.2 规则注册示例
// dacli/src/registry.ts
export interface FixRule {
id: string
level: 'silent' | 'assertive' | 'suggest'
category: 'form' | 'dict' | 'menu' | 'dm' | 'workflow' | 'universal'
trigger: TriggerFn
fix: FixFn | null // suggest 级为 null
rollback?: RollbackFn // assertive 级必填
source: string // JNPF 源码引用 或 BS 编号
}
const RULES: FixRule[] = [
{
id: 'A1-fk-relation-form',
level: 'assertive',
category: 'form',
trigger: (f: Field) => /^f_(.+)_id$/.test(f.field) && f.jnpfKey !== 'relationForm',
fix: async (f: Field, ctx: Ctx) => {
const target = f.field.match(/^f_(.+)_id$/)?.[1]
const forms = await ctx.formList()
const matched = forms.find(f => f.enCode === target)
if (!matched) return null // 降级为 suggest
return { ...f, jnpfKey: 'relationForm', modelId: matched.id, dictType: target }
},
rollback: (f: Field, formId: string) =>
`dacli form update ${formId} --set='[{"field":"${f.field}","jnpfKey":"inputNumber"}]'`,
source: 'decisions/0001-fk-relation-form-required.md, web/RelationForm.vue',
},
// ... 所有规则
]
5.3 合并当前防御文件
| 当前文件 | 行数 | 处理 |
|---|---|---|
_blindspot_guards.ts |
36K | 提取 fix 函数 → registry;删除 WARN-only guard |
_anti_patterns.ts |
10K | wrong/right 对 → registry 的 trigger/fix/rollback |
_error_codes.ts |
17K | 保留错误分类;enhanceFromBackend 独立 |
_selfcheck.ts |
21K | 删除(融入 test render) |
_precheck.ts |
10K | step machine 保留;WARN 降级 |
_encode_validator.ts |
7K | → registry S1/S2 silent rules |
_dirty_check.ts |
4K | 删除(未被使用) |
预计合并后: 7 文件 3,593 行 → 1 文件 registry.ts ~500 行 + _auto_fix.ts ~300 行。
6. 命令输出规范
6.1 stdout 输出格式(AI 看的)
$ dacli <command> [options]
{emoji} {enCode} {动作} (id={id}) 修正 {n} 处 建议 {m} 项 [{耗时}]
测试: dacli test run --formId={id}
详情: dacli log --last
emoji 含义:
✓成功✗失败⚠部分成功(创建成功但有关键警告)
6.2 失败输出
$ dacli <command> [options]
✗ {动作} 失败 [{耗时}]
{错误摘要}(1 行,人类可读)
详情: dacli log --last
重试: {修正建议,如果有}
6.3 日志文件结构
{
"command": "form create",
"timestamp": "2026-07-20T14:30:52.123Z",
"duration_ms": 3200,
"result": "success",
"summary": {
"enCode": "registration_form",
"id": "8471...",
"silent_fixes": 2,
"assertive_fixes": 3,
"suggestions": 1
},
"fixes": [
{
"id": "S1",
"level": "silent",
"field": "enCode",
"from": "registration-form",
"to": "registration_form"
},
{
"id": "A1",
"level": "assertive",
"field": "f_user_id",
"from": "inputNumber",
"to": "relationForm",
"rollback": "dacli form update 8471... --set='[{\"field\":\"f_user_id\",\"jnpfKey\":\"inputNumber\"}]'"
}
],
"suggestions": [
{
"id": "G2",
"field": "f_status",
"message": "int 字段有候选字典",
"candidates": ["jxcjcompetitionstatus", "jxcjauditstate"]
}
],
"raw": {
"request": { "...": "..." },
"response": { "...": "..." }
}
}
7. dacli guide 命令
7.1 定位
dacli guide 不执行任何操作,仅输出 AI 所需的场景化知识。数据来源:registry.ts。
dacli guide form-create # form create 的场景推荐 + 已知陷阱
dacli guide form-create --context='{...}' # 携带当前字段上下文,输出定制建议
dacli guide dict-create # dict 创建指南(BS-47 等)
dacli guide troubleshoot --error='...' # 根据错误消息匹配修复路径
7.2 guide 输出示例
$ dacli guide form-create --context='{"fields":["f_user_id","f_start_time"],"appCode":"testspace"}'
━━ 模式推荐:
含 FK 字段 (f_user_id) → 推荐 --fields 模式
--ai 模式可用但 FK 字段不会自动设为 relationForm,创建后需 form update 修正
━━ 字段检查:
f_user_id (FK): 将自动修正为 relationForm (关联 user 表)
f_start_time (datetime): 将自动修正为 datePicker (format=yyyy-MM-dd HH:mm:ss)
━━ 建议命令:
dacli form create \
--fields='[
{"field":"f_user_id","fieldName":"用户","dataType":"varchar","dataLength":"50"},
{"field":"f_start_time","fieldName":"开始时间","dataType":"datetime"}
]' \
--fullName="..." --enCode="..." --autoRelease
8. CLAUDE.md + ssw-loop 精简
8.1 CLAUDE.md 精简
| 段 | 现在 | 改后 | 理由 |
|---|---|---|---|
| §2 dacli 用法 | ~100 行 | 3 行: "所有操作走 dacli,查操作用 dacli guide" |
知识在 registry |
| §2.5-2.7 架构 | ~50 行 | 删除 | 入 dacli 文档 |
| §3 命名规范 | ~20 行 | 保留 | 环境常识 |
| §4-14 行为准则 | ~80 行 | ~20 行 | 精简为 5 条核心准则 |
| §已知盲点 | 嵌入文本 | 删除 | 入 registry |
| 总计 | 386 行 | ~50 行 |
8.2 ssw-loop 精简
| 文件 | 现在 | 改后 |
|---|---|---|
| SKILL.md | 203 行 | ~80 行(7 阶段流程 + 派发规则) |
| references/stages.md | 250 行 | 保留(阶段详细步骤) |
| references/anti-patterns.md | 228 行 | 删除(入 registry) |
| references/lessons-from-apps.md | 317 行 | 删除(入 registry) |
| references/subagent-must-do.md | 132 行 | ~40 行(前置步骤改为 dacli guide --precheck) |
9. 实施计划
Phase 1: 核心改造(1 周)
| # | 任务 | 产出 |
|---|---|---|
| 1 | 创建 dacli/src/registry.ts,迁移 Silent 级 10 条规则 |
registry.ts |
| 2 | 创建 dacli/src/commands/_auto_fix.ts,实现 fix pipeline |
_auto_fix.ts |
| 3 | 创建日志系统(dacli/src/core/logfile.ts + dacli log 命令) |
结构化日志 |
| 4 | 改 form create 输出格式(stdout 精简 + 日志写入) |
命令适配 |
Phase 2: Assertive + guide(1 周)
| # | 任务 | 产出 |
|---|---|---|
| 5 | 迁移 Assertive 级 5 条规则到 registry | 含 rollback |
| 6 | 迁移 Suggest 级 5 条规则到 registry | 候选逻辑 |
| 7 | 实现 dacli guide 命令 |
guide 命令 |
| 8 | 合并 7 防御文件 → registry 引用 | 删除旧文件 |
Phase 3: 文档 + CLAUDE.md(3 天)
| # | 任务 | 产出 |
|---|---|---|
| 9 | 精简 CLAUDE.md(386 → ~50 行) | CLAUDE.md v2 |
| 10 | 精简 ssw-loop(删除 3 个 reference,精简 SKILL.md) | ssw-loop v2 |
| 11 | 适配 form-create.md.tmpl 子代理模板 |
模板更新 |
Phase 4: 其他命令适配(1 周)
| # | 任务 | 产出 |
|---|---|---|
| 12 | dict/menu/dm/workflow 命令适配新输出格式 | 全命令统一 |
| 13 | 每类命令的 silent/assertive/suggest 规则注册 | registry 完整 |
| 14 | 旧 defense 文件删除 + import 清理 | 代码清理 |
10. 验证
10.1 回归测试
# 核心命令不受影响
dacli form create --fields='...' --autoRelease
dacli dict typeCreate --enCode=test_dict --fullName="测试字典"
dacli menu create --formId=xxx --fullName="测试菜单" --parentId=yyy
# 新功能
dacli log --last
dacli guide form-create
dacli guide dict-create
10.2 效果验证
用同一个输入"报名表单(含 f_user_id, f_start_time, f_status)"对比:
| 指标 | 现在 | 改后 |
|---|---|---|
| 命令成功率 | ~60%(AI 需读 WARN 后重试) | ~95%(自动修正) |
| AI 阅读行数 | ~40 行 | ~6 行 |
| 表单可运行 | 不一定(FK 未设 relationForm 时存数据报错) | 保证可运行 |
| 回滚能力 | 无(需手动重建) | 精确一行命令 |
| 防御代码维护点 | 7 文件 | 1 文件 |
| 同一规则出现次数 | 平均 4 处 | 1 处 |
11. 不在本方案范围
- 全自动完美配置:assertive 修正仅覆盖高置信场景,不确定的不修
- webapi 自动代码生成:
_loader.ts模式目前工作正常,后续单独评估 - 子代理断点续跑:ssw-loop 优化的一部分,不在 dacli v2 范围
- MCP server 模式:CLI 仍然是 AI 的主要接口,MCP 后续评估
- uniapp 移动端:同问题但独立处理
12. 参考
- ADR-0001: FK 字段必须 relationForm
- ADR-0002: form create --ai 4 限制
- ADR-0003: form update --fields 不同步物理表
- ADR-0009: 代码注释规范
- jxcj M1 实战复盘:
docs/jxcj/meta-issues-ssw-loop.md - ssw-loop 优化分析:
docs/jxcj/ssw-loop-optimization.md - JNPF 源码:
VisualAiServiceImpl.form()— AI 后处理基线 - JNPF 源码:
AiConstants.GEN_MODEL_QUETION— AI prompt 模板 - JNPF 源码:
JnpfKeyConsts— 组件白名单