命令路径 9 文件 throw new Error(改 DacliError (提升 L2 catch 一致性):
- datasource/test.ts (2 throws) — wrapCommand 内 throw
- integration/{emailtest,smstest,webhooktest}.ts (8 throws) — input validation
- report/{info,list}.ts (2 throws) — input failure
- storage/info.ts:38 (1 throw) — platform 不存在错误
- user/{auth-list,batch-state}.ts (2 throws) — 用户管理
跳过:
- test/{run,render,generate} (10 处) — 单元测试 intentional throws
- form/_*.ts SDK helper (_ai/_browser_verify/_buildformdata 等) — 内部 SDK 边界
- _ssw_retry, apis/_cache — 网络重试/缓存 helper
- menu/_helpers.ts — utility
为什么 DacliError 而不是 plain Error:
- DacliError.code 字段 (-1 默认) 让 L2 catch 可分类 (wrapCommand 自动 catch)
- DacliError.raw 字段保留后端原响应
- DacliError extends Error, 现有 (e as Error).message 写法仍兼容
验证:
- TS compile 56 baseline 不变
- 端到端抽样: storage info nonexistent / datasource test --help / integration
webhooktest --help 都正常
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— 数据模型 APIweb/.../FlowProcess/src/helper/config.ts— 工作流 globalFormMap / flowNodes 默认值
2. 不写 LLM prompt (跟 NCPF backend 透传)
dacli/src/commands/form/_ai.ts:3-9:
"dacli 设计上不写 LLM prompt (跟 NCPF backend 透传)。自写 prompt 必与后端漂移 (两个 prompt 源, 升级时一方动一方不动)。"
--ai "<描述>" 走 NCPF backend /api/visualdev/ai/form,prompt 在后端,不在 dacli。
字段名错误处理: 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/ |
| 历史决策 | dacli/docs/decisions/ (0001-0015 系列, 决策记录; ADR 0014 app clear + ADR 0015 源码遗留清单 + P0 wrapCommand 收口) |
| 历史漂移分析 | dacli/docs/drift/ (round7/10 等修复记录) |
| 跨项目教训 | dacli/docs/尚数网基本开发规范v3.0.md (公司规范) |
| 反模式 | dacli/docs/anti-patterns.md (Web 组件 / 后端约束踩坑) |
🏗️ 架构核心
v0.13+ 镜像架构 (2026-07-01 大改)
dacli form create --ai "..."
↓
[1] callAiForm → POST /api/visualdev/ai/form (NCPF backend, 走 JNPF 配置的 LLM)
↓ 返回 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 项检查
- ✅ 读过 web/ 源码? 至少读 1 个相关
web/.../api/*文件 + 1 个web/.../views/*文件 - ✅ 查过
dacli/docs/decisions/? 看相关历史决策避免重蹈覆辙 - ✅ TS 编译 0 错误?
npx tsc --noEmit --project dacli/tsconfig.json - ✅ 跑过端到端?
npx tsx dacli/src/cli.ts <cmd>真实创建 1 个 form/menu 验证 - ✅ 跑过 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 |
推荐: 建表单 (NCPF AI + web buildFormData + 自动发布) |
dacli form update --fields='[...]' |
改 schema (修正 AI 4 限制: 控件选错/幻觉字段/required 误标/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, NCPF 后端强制) — 例:
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