Files
dacli/doc/help-system.md
T

7.3 KiB

help-system.md — 帮助体系设计

位置: $ccWorkDir/dacli/doc/help-system.md 目标: 比 Java 版更 AI 友好的帮助体系

1. 设计动机

Java 版 dacli 用 Picocli 自动生成 --help, 对人不友好, 对 AI 也不够友好:

  • ❌ --help 输出冗长, AI 难以解析
  • ❌ 无字段约束说明, AI 不知道哪些必填
  • ❌ 无 JSON 示例, AI 不知道 payload 形态
  • ❌ 无 web 源文件指引, debug 难定位

TS 版增强 5 个 flag, 让 AI 一次对话就能用对命令。

2. 5 个 flag 设计

Flag 输出 用途
--help Commander.js 自动 基础
--ai-help markdown 块, 可喂给 LLM AI prompt 友好
--example JSON 示例 直接抄
--source 指向 web 源文件:行号 debug
--json-schema JSON Schema 描述 API 文档自动生成

2.1 --ai-help

输出格式:

# dacli form create

## 用途
创建一张 JNPF 功能表单

## 必传参数
- `--fullName <string>`: 表单中文名
- `--enCode <string>`: 表单英文编码 (^[a-z0-9][a-z0-9.]*$)
- `--type <1|2|3|4>`: 1=自定义 2=系统 3=接口 4=视图
- `--webType <1|2|3>`: 1=仅表单 2=表单+列表 3=树
- `--dbLinkId <string>`: 业务库 id (从 dacli app status 拿)
- `--category <string>`: 字典分类 (从已有 form list 查)
- `--fields <json>`: type≠4 必填, 字段定义数组

## 可选参数
- `--description <string>`: 描述
- `--autoTable`: 自动建物理表 (type=1)
- `--autoRelease`: 自动发布 (state 0→1)

## 来源
- web 源码: `web/apps/.../formDesign/Form.vue:444-465`
- API: `POST /api/visualdev/Base`

## 例子

### 例子 1: 视图 (type=4, 最简单)
\`\`\`bash
dacli form create \\
  --fullName="请假申请" \\
  --enCode=leave \\
  --type=4 --webType=1 \\
  --dbLinkId=<id> \\
  --category=Form
\`\`\`

### 例子 2: 单表 (type=1, 完整)
\`\`\`bash
dacli form create \\
  --fullName="请假申请" \\
  --enCode=leave \\
  --type=1 --webType=2 \\
  --dbLinkId=<id> --category=Form \\
  --fields='[
    {"field":"f_name","fieldName":"姓名","jnpfKey":"input","required":1},
    {"field":"f_days","fieldName":"天数","jnpfKey":"inputNumber","required":1}
  ]' \\
  --autoTable --autoRelease
\`\`\`

## 常见错误
- "Database exception": dbLinkId 错 / tables 字段缺 / category 错
- "System abnormality" (release): type=4 视图不该 release
- 详见: references/troubleshooting.md

实现:

// src/core/help.ts
export function buildAiHelp(cmd: CommandSpec): string {
  return `
# dacli ${cmd.name}

## 用途
${cmd.description}

## 必传参数
${cmd.required.map(p => `- \`--${p.name} <${p.type}>\`: ${p.description}`).join('\n')}

## 可选参数
${cmd.optional.map(p => `- \`--${p.name} <${p.type}>\`: ${p.description}`).join('\n')}

## 来源
- web 源码: \`${cmd.webSource}\`
- API: \`${cmd.method} ${cmd.path}\`

## 例子
${cmd.examples.map((ex, i) => `### 例子 ${i + 1}: ${ex.title}
\`\`\`bash
${ex.code}
\`\`\`
`).join('\n')}

## 常见错误
${cmd.commonErrors.join('\n')}
  `.trim()
}

2.2 --example

输出:

{
  "fullName": "请假申请",
  "enCode": "leave",
  "type": 4,
  "webType": 1,
  "dbLinkId": "2065021772707475456",
  "category": "Form"
}

用途: AI 拿到 example, 直接替换字段值就能调。

2.3 --source

输出:

web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue:444-465
web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts:23

用途: debug 时知道这个命令的源头是 web 的哪个文件, 可以直接读。

2.4 --json-schema

输出:

{
  "type": "object",
  "required": ["fullName", "enCode", "type", "webType", "dbLinkId", "category"],
  "properties": {
    "fullName": { "type": "string", "description": "表单中文名" },
    "enCode": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.]*$" },
    "type": { "enum": [1, 2, 3, 4] },
    "webType": { "enum": [1, 2, 3] },
    ...
  }
}

用途: 自动化测试用, 验证 AI 生成的 JSON 符合 schema。

3. 全局 flags

Flag 行为
--json 全命令输出 JSON (默认人类可读)
--quiet 静默 (仅 error)
--verbose 详细 (含 raw 响应)
--no-color 关闭颜色
--version 版本

4. 子命令注册模板

// src/commands/form.ts
const formCmd = new Command('form')
  .description('表单管理')

// 标准子命令
formCmd
  .command('create')
  .description('创建表单')
  .addAiHelp(buildAiHelp(formCreateSpec))     // ← 新增
  .addExample(formCreateExample)              // ← 新增
  .addSource('Form.vue:444-465')              // ← 新增
  .option('--fullName <n>', '表单中文名')
  .option('--enCode <e>', '表单英文编码')
  .option('--type <1|2|3|4>', '...')
  ...
  .action(async (opts) => { /* ... */ })

Command 扩展 (自定义):

// src/core/command-ext.ts
declare module 'commander' {
  interface Command {
    addAiHelp(md: string): this
    addExample(obj: object): this
    addSource(file: string): this
  }
}

Command.prototype.addAiHelp = function(md: string) {
  this.option('--ai-help', '输出 AI 友好的 markdown 帮助')
  this._aiHelp = md
  return this
}

Command.prototype.addExample = function(obj: object) {
  this._example = obj
  return this
}

// ai-help flag 处理
const origAction = Command.prototype._actionHandler
Command.prototype._actionHandler = function(fn) {
  return async function(this: Command, ...args) {
    if (this.opts().aiHelp) {
      console.log(this._aiHelp)
      return
    }
    if (this.opts().example) {
      console.log(JSON.stringify(this._example, null, 2))
      return
    }
    if (this.opts().source) {
      console.log(this._source)
      return
    }
    return fn.apply(this, args)
  }
}

5. 实际 AI 使用示例

5.1 AI 接到任务: "建一个请假流程"

Step 1: AI 读 --ai-help

$ dacli form create --ai-help
[输出上面 markdown]

Step 2: AI 决定 type=4 (快速 POC)

看完帮助, AI 知道 type=4 不需要 fields, 不需要 release

Step 3: AI 调命令

$ dacli form create --fullName="请假" --enCode=leave \
    --type=4 --webType=1 --dbLinkId=<from status> --category=Form
✓ Created form id=xxx

Step 4: AI 跑 baseline 验证

$ npx playwright test tests/e2e/baseline/developSystem/leaveApply.spec.ts
✓ UI 0 视觉差

5.2 AI 接到任务: "迁移 5 张表单到 tds"

Step 1: AI 读 list 看有哪些

$ dacli form list --appCode=developSystem --pageSize=100

Step 2: AI 调 --ai-help 看 export/import 怎么用

$ dacli form export --ai-help
$ dacli form import --ai-help

Step 3: AI 用 examples 套

$ for id in 1 2 3 4 5; do
    dacli form export $id --out=/tmp/$id.json
    dacli form import /tmp/$id.json --enCode=$(dacli form info $id).enCode_migrated
  done

Step 4: AI 跑 baseline 验证

$ bash examples/baseline/all.sh --skip-visual
✓ 5/5 API 0 错

6. 反向链接