301 lines
7.3 KiB
Markdown
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 命令速查
|