Files
dacli/doc/help-system.md
T

301 lines
7.3 KiB
Markdown

# 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`
**输出格式**:
```markdown
# 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
```
**实现**:
```ts
// 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`
**输出**:
```json
{
"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`
**输出**:
```json
{
"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. 子命令注册模板
```ts
// 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 扩展** (自定义):
```ts
// 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 调命令**
```bash
$ dacli form create --fullName="请假" --enCode=leave \
--type=4 --webType=1 --dbLinkId=<from status> --category=Form
✓ Created form id=xxx
```
**Step 4: AI 跑 baseline 验证**
```bash
$ npx playwright test tests/e2e/baseline/developSystem/leaveApply.spec.ts
✓ UI 0 视觉差
```
### 5.2 AI 接到任务: "迁移 5 张表单到 tds"
**Step 1: AI 读 list 看有哪些**
```bash
$ dacli form list --appCode=developSystem --pageSize=100
```
**Step 2: AI 调 --ai-help 看 export/import 怎么用**
```bash
$ dacli form export --ai-help
$ dacli form import --ai-help
```
**Step 3: AI 用 examples 套**
```bash
$ 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
$ bash examples/baseline/all.sh --skip-visual
✓ 5/5 API 0 错
```
## 6. 反向链接
- [architecture.md](architecture.md) — 设计
- [api.md](api.md) — API
- [plan.md](plan.md) — 6 周路线
- [extractors.md](extractors.md) — 提取工具
- [../.claude/skills/dacli-ts/SKILL.md](../.claude/skills/dacli-ts/SKILL.md) — AI 技能
- [../.claude/skills/dacli-ts/references/commands.md](../.claude/skills/dacli-ts/references/commands.md) — AI 命令速查