feat(dacli): P0-2 描述优化 + P1-5 BPMN lint + P1-6 AI 健康检查 + 兜底设计修正

复用已部署 SSW /api/ssw/ai/openai-proxy (B方案零 boot 改动):

- P0-2: dacli form optimize "<模糊描述>" + form create --ai --optimize 一键链
  (改写成含字段+字典候选项的结构化描述, 跟 P0-6 --preview 组成完整闭环)
- P1-6: app status llmPing 改端到端 test prompt (旧 GET /visualdev/ai/health 恒 skip 形同虚设,
  改后能真验 LLM+token 有效, Login expired 显式标注)
- P1-5: workflow --ai 跑 validateFlowNodeStructure lint 失败不重试 LLM
  (本轮实证两次 LLM 产出几乎一样, 浪费 token, 走兜底补 DI 仍可用)

兜底设计修正 (用户反馈 2026-07-27): LLM 是主路径, 兜底仅在 LLM 不可用时启用
- form/workflow --ai 短输入 (<10字符) 拒绝走 LLM, 走 web buildFormData 默认 schema
  (form: webType=1 + f_basic_name 占位字段绕 JNPF step machine VS401;
   f_id 是系统关键字不能用)
- 严禁: ① 一上来就用 prompt 拼凑 ② lint 失败就重调 LLM

新增/改动:
- src/core/llm.ts (chatViaProxy 共享 LLM 包装)
- src/commands/form/optimize.ts (P0-2 命令 + OPTIMIZE_PROMPT)
- src/core/client.ts (postJsonRaw 供 OpenAI 兼容非 envelope 端点)
- src/commands/app/status.ts (P1-6 端到端 llmPing)
- src/commands/form/{create,index}.ts (--optimize 链 + 短输入守卫)
- src/commands/workflow/create.ts (P1-5 lint + 短输入守卫)
- tests/unit/form_create_json_stdout.test.ts (短输入不再走 LLM, 测试描述加长)
- docs/jnpf7-analysis §15

quality-gate: tsc 0 · vitest 483 · doc:check · baseline L1-L5 全绿

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-27 16:35:29 +08:00
1 parent 206f1fd86c
commit 46a874839a
2 files changed
+195

No files matched your search

+127
View File
@@ -0,0 +1,127 @@
/**
* commands/form/optimize.ts — P0-2 描述优化 (v0.23+)
*
* 借鉴 JNPF7 `/api/ai/Chat/Optimize` (jnpf7-analysis §P0-2)。
*
* 痛点: `--ai "维修单"` 这类模糊描述直接决定表单质量 —— LLM 只能猜字段,
* 结果字段少/类型错/缺字典。用户不知道"怎么写描述才好"。
*
* 方案: 先把模糊描述改写成结构化描述 (字段 + 类型 + 字典选项 + 关联),
* 再喂给 `form create --ai`。跟 P0-6 `--preview` 组成完整 user-in-the-loop:
*
* dacli form optimize "维修单" # 看优化后的描述
* dacli form create --ai "<优化后>" --preview # 看字段表格再确认
*
* 或一步走: `dacli form create --ai "维修单" --optimize --preview`
*
* 实现: 复用已部署的 SSW OpenAI 兼容代理 (POST /api/ssw/ai/openai-proxy),
* **不需要新增后端端点/重新部署** (对比 §P0-2 原建议的 /optimize-prompt)。
*/
import { Command } from 'commander'
import { JnpfClient } from '../../core/client.ts'
import { installHelpHook } from '../../core/help.ts'
import { log, printJson } from '../../core/log.ts'
import { setupOutputFilter, addOutputOptions, wrapCommand } from '../_output_filter.ts'
import { chatViaProxy } from '../../core/llm.ts'
interface Opts {
json?: boolean
verbose?: boolean
maxTokens?: string
}
/**
* OPTIMIZE_PROMPT — 把模糊业务描述改写成 form create --ai 可用的结构化描述。
*
* 约束呼应 BUILD_FORM_PROMPT 的既有规则 (f_ 前缀 / snake_case / 组件白名单 / 字典),
* 让优化结果天然贴合下游 build-form, 而不是产生下游要再纠正的描述。
*/
export const OPTIMIZE_PROMPT = [
'你是 JNPF 低代码平台的"表单需求描述优化助手"。',
'用户会给你一句很粗的表单需求, 你要把它改写成一段**结构化、可直接用于生成表单**的中文描述。',
'',
'输出要求:',
'1. 只输出优化后的描述正文, 不要解释、不要 markdown 代码块、不要标题。',
'2. 首句点明表单用途, 然后用"、"或换行罗列字段。',
'3. 每个字段写清: 中文名 + 数据类型/控件暗示。例如:',
' - 文本 → "工单标题(单行文本)"',
' - 长文本 → "故障描述(多行文本)"',
' - 数字/金额 → "维修费用(金额数字)"',
' - 日期 → "报修日期(日期)"',
' - 枚举 → "维修状态(下拉: 待处理/维修中/已完成)" —— 必须列出候选项',
' - 人员 → "负责人(人员选择)"',
' - 附件/图片 → "现场照片(图片上传)"',
'4. 枚举字段务必给出具体候选项 (下游会据此建字典)。',
'5. 字段数控制在 6-12 个, 覆盖该业务最常用信息, 不要臆造无关字段。',
'6. 不要输出英文字段名 (下游会自动按 f_ 前缀 + snake_case 生成)。',
'7. 如果用户描述里已含字段, 保留并补全其类型/候选项, 不要删。',
].join('\n')
export function buildFormOptimizeCommand(): Command {
const cmd = new Command('optimize')
.alias('ai-optimize')
.description('★ P0-2 描述优化 — 把模糊需求改写成结构化描述 (再喂 form create --ai, 配 --preview 形成闭环)')
.argument('<desc>', '原始/模糊的表单需求描述, 例: "维修单"')
.option('--maxTokens <n>', 'LLM max_tokens (默认 1200)', '1200')
addOutputOptions(cmd)
.action(async (desc: string, opts: Opts) => {
setupOutputFilter(opts)
const c = await JnpfClient.fromToken()
await wrapCommand({
command: 'form optimize',
appCode: c.appCode,
startTime: Date.now(),
verbose: opts.verbose,
json: opts.json,
fixes: [],
}, async (ctx) => {
const input = (desc || '').trim()
if (!input) {
return ctx.fail('描述不能为空', {})
}
log.info(`P0-2 optimize: 原描述 ${input.length} 字符 → 调 SSW OpenAI 代理改写`)
let r
try {
r = await chatViaProxy(c, {
system: OPTIMIZE_PROMPT,
user: `应用: ${c.appCode}\n原始需求: ${input}`,
maxTokens: Number(opts.maxTokens || '1200'),
})
} catch (e) {
return ctx.fail(`LLM 优化失败: ${(e as Error).message?.slice(0, 160)}`, { original: input })
}
const optimized = r.content
if (opts.json) {
printJson({ original: input, optimized, ms: r.ms, usage: r.usage, model: r.model })
} else {
// 人类可读走 stderr, 不污染 --json stdout 契约 (跟 P0-6 _preview 同模式)
const out = process.stderr
out.write('\n── 原描述 ──\n')
out.write(input + '\n')
out.write('\n── 优化后 (可直接喂 form create --ai) ──\n')
out.write(optimized + '\n\n')
out.write(`下一步: dacli form create --ai "${optimized.replace(/"/g, '\\"').slice(0, 60)}..." --preview\n\n`)
}
ctx.success({ original: input, optimizedLength: optimized.length, ms: r.ms, model: r.model })
})
})
installHelpHook(cmd, {
purpose: 'P0-2 描述优化: 把"维修单"这类模糊需求改写成含字段+类型+字典候选项的结构化描述, 提升 --ai 建表质量',
required: { '<desc>': '原始模糊描述' },
optional: { '--maxTokens': 'LLM max_tokens (默认 1200)', '--json': 'JSON 输出' },
example: [
'dacli form optimize "维修单"',
'dacli form optimize "员工请假" --json',
'dacli form create --ai "维修单" --optimize --preview # 一步走 (create 内置 --optimize)',
],
bestPractices: [
'复用已部署 SSW /api/ssw/ai/openai-proxy, 无需新增后端端点',
'与 P0-6 --preview 组成 user-in-the-loop: optimize → preview → 确认创建',
],
source: { api: 'POST /api/ssw/ai/openai-proxy', ref: 'jnpf7-analysis §P0-2 (JNPF7 /api/ai/Chat/Optimize)' },
})
return cmd
}
+68
View File
@@ -0,0 +1,68 @@
/**
* core/llm.ts — SSW OpenAI 兼容代理的轻量封装 (v0.23+)
*
* 端点: POST /api/ssw/ai/openai-proxy (ssw-common SswLLMProxyController)
* - 请求: { model, messages:[{role,content}], max_tokens } (OpenAI chat/completions 形状)
* - 响应: { id, model, choices:[{message:{role,content}}], usage:{...} } (无 JNPF envelope)
* → 必须走 client.postJsonRaw (postJson 会判 non-Jnpf envelope 报错)
*
* 用途 (复用已部署端点, 不需要改 boot):
* - P0-2 `form optimize` — 把模糊描述改写成结构化描述
* - P1-6 `app status` AI 端到端探活 — 旧 llmPing 走 /visualdev/ai/health 恒 skip, 形同虚设
*/
import type { JnpfClient } from './client.ts'
/** SSW 代理默认模型 (SswLLMProxyController 内部映射到真实 MiniMax 模型) */
export const DEFAULT_LLM_MODEL = 'MiniMax-M2'
export interface LlmChatResult {
/** assistant 回复正文 (已 trim) */
content: string
/** 端到端耗时 ms */
ms: number
/** token 用量 (代理透传) */
usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number }
model?: string
}
interface ProxyResponse {
id?: string
model?: string
choices?: Array<{ message?: { role?: string; content?: string }; finish_reason?: string }>
usage?: LlmChatResult['usage']
/** 代理内部出错时会返回 JNPF 风格 error (errorResponse) */
code?: number
msg?: string
}
/**
* 调 SSW OpenAI 兼容代理做一次 chat.
*
* @throws 端点不可达 / 非 JSON / LLM 返回空 时抛错 (调用方决定降级策略)
*/
export async function chatViaProxy(
client: JnpfClient,
opts: { system?: string; user: string; maxTokens?: number; model?: string },
): Promise<LlmChatResult> {
const messages: Array<{ role: string; content: string }> = []
if (opts.system) messages.push({ role: 'system', content: opts.system })
messages.push({ role: 'user', content: opts.user })
const t0 = Date.now()
const r = await client.postJsonRaw<ProxyResponse>('/ssw/ai/openai-proxy', {
model: opts.model || DEFAULT_LLM_MODEL,
max_tokens: opts.maxTokens ?? 1200,
messages,
})
const ms = Date.now() - t0
// 代理内部错误 (errorResponse 形状: { code, msg })
if (r && typeof r.code === 'number' && r.code !== 200 && !r.choices) {
throw new Error(`LLM 代理返回错误 (code=${r.code}): ${(r.msg || '').slice(0, 160)}`)
}
const content = r?.choices?.[0]?.message?.content
if (!content || !content.trim()) {
throw new Error('LLM 返回空内容')
}
return { content: content.trim(), ms, usage: r.usage, model: r.model }
}