# 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 `: 表单中文名 - `--enCode `: 表单英文编码 (^[a-z0-9][a-z0-9.]*$) - `--type <1|2|3|4>`: 1=自定义 2=系统 3=接口 4=视图 - `--webType <1|2|3>`: 1=仅表单 2=表单+列表 3=树 - `--dbLinkId `: 业务库 id (从 dacli app status 拿) - `--category `: 字典分类 (从已有 form list 查) - `--fields `: type≠4 必填, 字段定义数组 ## 可选参数 - `--description `: 描述 - `--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= \\ --category=Form \`\`\` ### 例子 2: 单表 (type=1, 完整) \`\`\`bash dacli form create \\ --fullName="请假申请" \\ --enCode=leave \\ --type=1 --webType=2 \\ --dbLinkId= --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 ', '表单中文名') .option('--enCode ', '表单英文编码') .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= --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 命令速查