Files
dacli/docs/decisions/0010-dacli-v2-self-correcting-cli.md
T
sswandClaude 61405e128d fix(dacli): resolve merge conflicts + add v2 architecture spec
- 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]>
2026-07-20 10:11:41 +08:00

17 KiB
Raw Blame History

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. 设计原则

  1. 可运行优先于正确:静默修正和 assertive 修正必须保证"不修会崩溃或体验极差",不确定的不修
  2. 修了就能回滚:每条 assertive 修正提供精确的一行回滚命令
  3. AI 看结果,人看日志:stdout 只输出结果摘要 + 下一步操作。详细信息写入结构化日志
  4. 单一知识源:所有规则定义在 registry.ts,自动生成 fix 函数 + --help + guide
  5. 跟随 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 — 组件白名单