ssw 8762cd0121 BS-新147/153/154: workflow launch 镜像 web getFlowBeforeList + shim 补全
铁律 3 严格镜像 (P0 修复): 删自创 getFlowTaskOperatorList, 改 _loader.ts 镜像
web/api/workFlow/task.ts:71-73 getFlowBeforeList (0 漂移, web 升级时自动同步).

新增:
- src/webapi/operator.ts: loadOperator proxy 镜像 web task.ts (单进程缓存)
- src/webapi/_vben_stores_shim.ts: Pinia useUserStore stub (task.ts:3 import)
- src/webapi/_jnpf_utils_shim.ts: buildUUID + AesEncryption + buildBitUUID (task.ts:1 import)
- src/webapi/_loader.ts step 5.6: @vben/stores shim 规则
- src/webapi/_loader.ts step 4 改: @jnpf/utils → _jnpf_utils_shim
- tests/unit/webapi_operator.test.ts: 6 vitest (initWebapi + getFlowBeforeList 转发 + 边界)
- tests/unit/workflow_launch_regression.test.ts: 7 vitest (L1 + L2 fixture 防回归)
- tests/unit/relation_form_complete_regression.test.ts: 2 vitest (L4 同模式 BS-新146)
- tests/unit/app_context_version_regression.test.ts: 5 vitest (BS-新152 currentVersion)
- tests/unit/workflow_command_smoke.test.ts: 9 vitest (6 命令 0 测试覆盖补全)

launch.ts: 改用 loadOperator.getFlowBeforeList (L116), 加 audit 注释 (L110-113)
relation_form_complete.ts: L4 修 (--no-release 跟 BS-新146 L1 同模式)
app/context.ts: BS-新152 修 (readCliVersion 路径 cli.ts → program.ts)
quality-gate.sh + validate-baseline.sh: 删 L5 Prompt A/B (jnpf7 临时对照目录)

vitest: 584 → 613 (+29), tsc 0 错, 5 关全过
2026-07-29 11:18:13 +08:00

dacli — AI 驱动 JNPF CLI

⚠️ 修改 dacli 前必读: 本文件是 dacli 基本原则速查 (10 分钟读完), 写代码前过一遍. 权威源: web 源码 (铁律 1) + 本文件速查 + dacli/src/webapi/* 镜像注释


🔒 5 大铁律 (违反任一 = 重做)

1. web/ 源码永远是权威 (绝对原则)

✅ DO:  看 web/apps/jnpf-web-apps-main/src/{api,views,components}/ 实际代码
❌ DON'T: 凭"经验"猜 API 路径/默认值/校验规则

如果 dacli 文档与 web/ 不一致 → 以 web 为准,直接读源码。

权威文件 (按使用频率):

  • web/.../views/onlineDev/formDesign/Form.vue — form 创建的精确字段默认值
  • web/.../api/onlineDev/visualDev.ts — 所有 visualdev API 端点
  • web/.../api/systemData/dataModel.ts — 数据模型 API
  • web/.../FlowProcess/src/helper/config.ts — 工作流 globalFormMap / flowNodes 默认值

2. 不写 LLM prompt (LLM prompt 在 ssw-common, 不在 dacli)

dacli/src/commands/form/_ai.ts:

"dacli 设计上不写 LLM prompt (prompt 在 ssw-common boot/ssw-common/, 不在 dacli)。dacli 仅消费 LLM 响应 + 构造 formData/workflow."

v0.22+ (2026-07-25) 路径:

  • dacli form create --ai "<描述>" 走 ssw-common /api/ssw/ai/build-form (form) + /api/ssw/ai/build-workflow (workflow)
  • ssw-common boot/ssw-common/.../AIRepairServiceImpl.java 含 BUILD_FORM_PROMPT + BUILD_WORKFLOW_PROMPT, 镜像 web 端 schema, prompt 我们写

注: "NCPF" 是 JNPF 后端 AI 端点的历史叫法, v0.22+ 已旁路 (SSW 直调 LLM, 无 NCPF 4+3 限制). 详见 docs/decisions/.

字段名错误处理: AI 路径默认 camelCase (无 f_ 前缀), 用 --column-naming=snake 后处理重命名 (默认开启, 见 create.ts:255)。

3. 镜像架构 0 复刻 0 漂移 (dacli/webapi)

✅ DO:  直接 import web 端源码到 dacli/src/webapi/* (用 _loader.ts 替换 import)
❌ DON'T: 抄 web 端代码自己写一遍 (历史教训: 6 周修 50+ 漂移问题)

已镜像 18 个 webapi 模块, 100+ 函数. 单进程缓存避免重复 load.

4. 新会话必跑 3 步 (避免凭印象猜)

dacli app context --json    # Step 1: 拿 dbLinkId / systemId / existingEnCodes
dacli form list              # Step 2: 看已有 form (避免重名)
dacli <cmd> --help            # Step 3: 标准 commander 帮助 (含选项 + 描述)

5. 不绕过 dacli 调 curl (CLAUDE.md 强制)

✅ DO:  所有 JNPF 操作走 dacli (form/dm/dict/menu/workflow/role/di/log/...)
❌ DON'T: 用 curl 直调 /api/* (绕过 schema 校验/auto_fix/日志)

📁 必读文档 (按场景)

策略: 优先读 web 源码 (铁律 1). dacli 端文档作辅助.

场景 权威源
控件类型映射 (jnpfKey/dataType) web/.../utils/src/helpers/formUtils.ts:14-77 + web/.../FormGenerator/src/componentMap.ts
Form schema 三件套 (formData/columnData/tables) web/.../views/onlineDev/formDesign/Form.vue + Generator.getData + ColumnDesign.getData
Workflow 节点 / globalFormMap web/.../FlowProcess/src/helper/config.ts + web/.../views/onlineDev/flowEngine/index.vue
30+ 错误码 (EXIST/VS/WF/SYS) 后端 jnpf/.../constant/MsgCode.java:50-783
命名规范 (snake/camelCase/f_ 前缀) dacli/docs/decisions/0001-fk-relation-form-required.md + 0002-form-create-ai-4-limitations.md
找 web 源码位置 用 IDE 全局搜索 (Cmd+Shift+F / grep -rn) 找 formData / flowNodes / columnList
命令评审历史 ⚠️ dacli/docs/cmd-review/ 整体已归档 (2026-07-23) → dacli/docs/archive/cmd-review-2026-07/ (25 文件历史快照)
历史决策 dacli/docs/decisions/ (0001-0016 系列, 决策记录; ADR 0014 app clear + ADR 0015 源码遗留清单 + ADR 0016 eventhub blocker 设计)
历史漂移分析 ⚠️ dacli/docs/drift/ round summary 整体已归档 (2026-07-23) → dacli/docs/archive/drift-rounds-2026-07/ (20 round 历史快照); 顶层 drift/ 保留 README/USAGE/fetch-baseline.sh 基础设施
跨项目教训 dacli/docs/尚数网基本开发规范v3.0.md (公司规范)
反模式 dacli/docs/anti-patterns.md (Web 组件 / 后端约束踩坑)

🏗️ 架构核心

v0.13+ 镜像架构 (2026-07-01 大改)

dacli form create --ai "..."
  ↓
[1] callAiForm → POST /api/ssw/ai/build-form  (v0.22+ SSW 直调 LLM, prompt 我们写)
  ↓ 返回 VisualAiModel
[2] web buildFormData (webapi 镜像) → 构造 50+ formConf 字段
  ↓
[3] loadVisualDev.create → POST /api/visualdev/Base
[4] loadVisualDev.release (默认 ON, type=1 真正发布) → POST /api/visualdev/Base/{id}/Actions/Release
  ↓
✅ form state=1, 可用

webapi 模块清单 (dacli/src/webapi/)

机制: 每个文件 export const loadXxx = new Proxy(...), 懒加载镜像 web 端全部函数 (dacli 端只需 init 一次, 之后 loadXxx.fn(args) 调 web 端原版). 因此函数数 = web 端全部导出, 不在 dacli 端 grep 数.

模块 镜像 web 文件 用途
visualDev.ts ★ web/.../api/onlineDev/visualDev.ts form / work CRUD
workflow.ts ★ web/.../api/workFlow/template.ts work CRUD
dict.ts ★ web/.../api/systemData/dict.ts 字典
dataModel.ts ★ web/.../api/systemData/dataModel.ts 数据模型
dataSource.ts web/.../api/systemData/dataSource.ts 数据源
menu.ts web/.../api/permission/menu.ts 菜单
role.ts web/.../api/permission/role.ts 角色
log.ts web/.../api/system/log.ts 系统日志
monitor.ts web/.../api/system/monitor.ts 监控
schedule.ts web/.../api/system/schedule.ts 定时任务
message.ts web/.../api/system/message.ts 消息/通知
report.ts web/.../api/system/report.ts 报表
onlineUser.ts web/.../api/permission/onlineUser.ts 在线用户
flowMonitor.ts web/.../api/workFlow/flowMonitor.ts 流程监控
user.ts web/.../api/permission/user.ts 用户
di.ts web/.../api/systemData/dataInterface.ts 数据接口
visualdata.ts 大屏 (独立子项目) 大屏
datascreen.ts 大屏 (visual.js 相对路径) shim 大屏备选

输出过滤模式 (v2.0+ quiet mode) — 第一层处理: stdout 流向

核心: dacli/src/core/log.ts:23-77 实现 setQuiet / flush / discard / printJson.

// form 命令模板 (dacli/src/commands/form/create.ts:248-262)
.option('--verbose', '完整输出 (含 step machine、API 调用等过程日志)', false)
.option('--json', '原始 JSON 输出', false)
.action(async (opts) => {
  log.setQuiet(!opts.verbose && !opts.json)
  // ... 业务逻辑 ...
  if (opts.verbose) log.flush()
  else log.discard()
  process.stdout.write(`  详情: dacli log last\n`)
})

3 种 stdout 模式:

模式 触发 行为 AI 用法
默认 quiet 不传 flag info/ok/warn/dim/raw → buffer → discard() (默认); error 永远即时 默认操作 (AI 不需要过程日志)
--verbose dacli form create --verbose 所有日志即时输出 (含 step machine/API 调用过程) 调试时开启, 看完整 trace
--json dacli form list --json 原始 JSON 直接 stdout (不受 quiet 影响) pipe 到 jq / grep 解析

stdout 详情查询: dacli log last (摘要) / --detail (含回滚命令+原始请求响应) / --level=fix (只看修正) / --raw (原始 JSON).

错误修正三重处理 — 第二层处理: 异常恢复策略

核心: dacli/src/core/logfile.ts:33-54 定义 CommandLog 的 3 种 fix 数组. 实现见 dacli/src/commands/_auto_fix.ts + _error_codes.ts.

// dacli/src/core/logfile.ts:33-54
export interface CommandLog {
  result: 'success' | 'failure' | 'partial'
  summary: {
    silent_fixes: number      // ← 自动处理 (用户无感知)
    assertive_fixes: number   // ← 警告级 (有回滚命令)
    suggestions: number       // ← 提示级 (AI 修复建议)
  }
  silent_fixes: FixEntry[]     // [{id, level: 'silent', summary, ...}]
  assertive_fixes: FixEntry[]  // [{id, level: 'assertive', summary, rollback, ...}]
  suggestions: FixEntry[]      // [{id, level: 'suggest', summary, ...}]
}

3 级 fix 策略:

级别 触发条件 行为 AI 感知 查询命令
silent (自动) 后端报 EXIST002 (重名) 等可自动恢复 自动改名 _v2 重试, 不报错 无感知 (默认成功) dacli log last --level=fix
assertive (警告) 后端报 VS401/VS402 等必须修正 强制改 schema + 输出回滚命令 看到警告 + 回滚命令 dacli log last --level=fix --detail
suggest (提示) 数据/配置有问题但可继续 输出 [step N name] field: CODE - message (suggestion) AI 根据 suggestion 自修复 dacli log last 摘要

典型输出样例 (AI 必须能解析这 3 种格式):

# silent (自动处理, 默认 stdout 无输出)
✓ formCreate 成功 (silent_fixes=1: 重名 _v2)

# assertive (警告级, stdout 显示 ⚠)
✗ [step 1 formData] relationForm.modelId: VS401 - 关联功能不能为空
✅ assertive fix: modelId 自动设置为 formId=848864086438446021
  回滚: dacli form update <id> --fields='[{"__vModel__":"f_team_id","jnpfKey":"input"}]'

# suggest (提示级, stdout 显示 💡)
💡 suggest: form update 时显式传 --fields='[...]' 包含 modelId (BS-新117)

AI 调用流程 (错误恢复):

# 1. 默认跑 (auto-fix 自动处理 silent)
dacli form create --enCode=X --fullName=X ...

# 2. 失败时查详情
dacli log last                  # 摘要: silent_fixes / assertive_fixes / suggestions 计数
dacli log last --level=fix      # 只看 fix (含 rollback 命令)
dacli log last --detail         # 含原始请求/响应

# 3. 按 suggestion 修复 (AI 自修复)
dacli form update <id> --fields='[...]'  # 按 suggestion 建议的修正

修改点 (AI 修改这三层时的入口):

想改什么 文件
新加 silent fix 策略 dacli/src/commands/_auto_fix.ts
新加 assertive fix + rollback dacli/src/commands/_auto_fix.ts (entry 加 rollback 字段)
改 G-X1 重名查的列表 (form/dict/menu/role/workflow) dacli/src/commands/_auto_fix.ts:fetchExistingLists (v2.1+ workflows 扩展)
改错误码分类 dacli/src/commands/_error_codes.ts (30+ 错误码 EXIST/VS/WF/SYS)
改 CommandLog 结构 dacli/src/core/logfile.ts:33-54

三层处理总结 (AI 速查)

第一层 (stdout 流向):   静默 (默认) | --verbose | --json
   ↓ 错误发生
第二层 (异常恢复):       silent (自动) | assertive (警告+回滚) | suggest (提示)
   ↓ 历史归档
第三层 (历史查询):       dacli log last | --level=fix | --detail | --raw

设计原则:

  • 不打扰 (默认静默 + 自动 silent fix)
  • 可观测 (--verbose + dacli log last)
  • 可回滚 (assertive 必有 rollback 命令)
  • 可学习 (suggestion 给 AI 修复方向)

✏️ 修改 dacli 前的 5 项检查

🔒 质量门自动强制 (P3, 2026-07-24): git config core.hooksPath scripts/githooks 后, pre-commit 自动跑 scripts/quality-gate.sh (tsc --noEmit + vitest unit + backend smoke), 编译或单测失败直接阻塞 commit — 第 3 项已从"靠自觉"变"门强制"。新 clone 先跑 sh scripts/install-hooks.sh 激活。仪式门 _gate_webapi 降级为 advisory (只报告 webapi 引用率, 不阻塞)。

  1. ✅ 读过 web/ 源码? 至少读 1 个相关 web/.../api/* 文件 + 1 个 web/.../views/* 文件
  2. ✅ 查过 dacli/docs/decisions/? 看相关历史决策避免重蹈覆辙
  3. ✅ TS 编译 0 错误? npx tsc --noEmit --project dacli/tsconfig.json — 质量门已自动强制
  4. ✅ 跑过端到端? npx tsx dacli/src/cli.ts <cmd> 真实创建 1 个 form/menu 验证
  5. ✅ 跑过 4 关卡? bash .claude/skills/ssw-loop/scripts/check_*.sh docs/<app>/

🚀 高频命令 (10 个)

命令 用途
dacli app login --account=admin --password=123456 --appCode=X 登录
dacli app context --json 新会话必跑, 拿 dbLinkId/systemId/existingEnCodes
dacli form list / dacli form info <enCode> 列/查表单
dacli form create --ai "<描述>" --autoRelease 推荐: 建表单 (v0.22+ 走 SSW /build-form, prompt 我们写)
dacli form update --fields='[...]' 改 schema (兜底补 7 字段 relationForm, 极少触发)
dacli menu create --formId=<id> --fullName=X --parentId=Y --type=3 绑 form 到 menu (sidebar 显示)
dacli dm list / dacli dm create --table=X --fields='[...]' 数据模型
dacli workflow create --ai "<描述>" --fullName=X --category=Y v0.13+: 走 6 步 webapi 路径 (AI → create → version → buildFlowNodes → save)
dacli log last 看最近命令详情 (含回滚命令+原始请求)
dacli log exception --lines=100 查后端异常 (AI 调试核心入口)

⚠️ AI 已知 4 限制 (2026-07-15 jxcj M1 实战)

限制 现象 修复
控件类型选错 f_organizer 被选 depSelect (应是 input) dacli form update 改 jnpfKey
幻觉字段 多生 input_num001 等业务外字段 dacli form update 删除
required 误标 上传控件被误标 required dacli form update 改 required
未生成 relationForm f_*_id 字段用 input 不用 relationForm dacli form update 改 jnpfKey=relationForm + 补 modelId

强制验证: 生成后立即 dacli form info <enCode> 检查 4 项全对才完成。


🆕 Step Machine 校验 (v0.11d+)

dacli form create 完整校验链 (镜像 web 端 handleNext + handleSubmit + Generator.getData + ColumnDesign.getData):

  • step0 基础信息 (fullName/enCode 必填 + 格式)
  • step1 formData 字段 (formFields ≥ 1, 关联控件 modelId/propsValue/relationField)
  • step2 columnData 列表 (webType≠1 && columnList ≥ 1)

校验失败 → exit 1 + 错误信息, 不发 API。


📋 修改 dacli 文件路径速查

想做什么 改哪个文件
加新 form 命令 dacli/src/commands/form/*.ts
加新 workflow 命令 dacli/src/commands/workflow/*.ts
加新 report 命令 dacli/src/commands/report/*.ts (8 文件, 已三层接入)
加新 datasource 命令 dacli/src/commands/datasource/*.ts (4 文件, v2.1+ 已接)
加新 storage 命令 dacli/src/commands/storage/*.ts (2 文件, v2.1+ 已接, yml 读)
加新 integration 命令 (email/sms/webhook test) dacli/src/commands/integration/*.ts (3 文件, v2.1+ 已接)
加 webapi 镜像 dacli/src/webapi/* + _loader.ts (动态 import 替换)
改输出过滤 dacli/src/core/log.ts
改命令输出 helper (含 saveCommandLog 集成) dacli/src/commands/_output_filter.ts (跨命令通用, v2.1+)
改命令级 auto-fix (enCode/fullName/BS-47) dacli/src/commands/_auto_fix.ts:runCommandAutoFix (跨命令通用, v2.1+)
改 G-X1 重名查的列表 (form/dict/menu/role + workflow) dacli/src/commands/_auto_fix.ts:fetchExistingLists (v2.1+ workflows 扩展 2026-07-21)
改 field-level auto-fix (jnpfKey/FK/datetime 等) dacli/src/commands/_auto_fix.ts:runAutoFix (form 专用)
改校验规则 dacli/src/commands/<module>/_validate.ts (per-module, 无公共 _validate.ts)
改公共 precheck dacli/src/commands/_precheck.ts
改错误码 dacli/src/commands/_error_codes.ts
改字典/字典数据 dacli/src/commands/dict/*.ts
改菜单 dacli/src/commands/menu/*.ts
改数据模型 dacli/src/commands/dm/*.ts (create/drop/list/fields 已接)
改报表 dacli/src/commands/report/*.ts (8 文件, BACKEND-7 已修 2026-07-21)
改 app clear --clean-docs 行为 dacli/src/commands/app/clear.ts (P1-2d 2026-07-21, docs/{app}/ 整体清理) + dacli/docs/decisions/0014-app-clear-docs-coverage.md
加新模块接入 (三层模式) 跟 report/create.ts 同样 4 步 pattern: imports → addOutputOptions → setupOutputFilter + runCommandAutoFix → printCommandEnd

📝 关键命名规范 (JNPF 6.x)

  • enCode: camelCase 无下划线 (BS-56, JNPF 全平台强制) — 例: auditrecord 不是 audit_record
  • 表名: = enCode (BS-55 同步规则) — 例: 表名 auditrecord 而不是 audit_record
  • 字典 enCode: camelCase + jxcj 前缀 — 例: jxcjcompetitionstatus
  • 字段名: 默认 snake_case (AI 路径下用 --column-naming=snake 默认加 f_ 前缀)
  • 类名: PascalCase (包名已带 appCode, 不重复)

避坑:

  • ❌ f_version (JNPF 关键字, 改名 f_revision / f_v)
  • ❌ f_description (JNPF 系统列, 改名 f_brief / f_summary / f_remark)
  • ❌ enCode 含 _ (BS-56) — audit_record 改成 auditrecord

v2.1+ 自动修正 (2026-07-21):

  • ✅ enCode 含 -/_ → 自动 strip (S-X1 silent) — 不要再 inline 调 autoStripEnCode
  • ✅ fullName 含 BS-56 禁字符 → 自动 soften (S-X2 silent) — 不要再 inline 调 autoStripFullName
  • ✅ enCode/fullName 与 existing{Forms,Dicts,Menus,Roles,Workflows} 冲突 → G-X1 suggest 含 <appCode> 前缀建议
  • 入口: commands/_auto_fix.ts:runCommandAutoFix(opts, ctx) — 跨命令通用 (form/dict/di/menu/role/workflow/bigscreen/portal/user/datasource/integration 等)
  • G-X1 workflow 扩展 (2026-07-21): fetchExistingLists 也拉 GET /workflow/template 走 web 端镜像, workflow enCode 重名也能触发 suggest
  • 详见 dacli/docs/decisions/0010-dacli-v2-self-correcting-cli.md §3 + §5

最后更新: 2026-07-21 版本: v0.13+ 镜像架构 + v2.0+ 输出过滤 + v2.1+ 跨命令 auto-fix + v2.2+ wrapCommand helper

S
Description
dacli CLI — JNPF 平台 AI 驱动开发工具 (TS 版 v0.7)
Readme
3.9 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 99.4%
Shell 0.4%
Python 0.2%