From 75d775b374eefe99463f87f64d7aef9ad762fb74 Mon Sep 17 00:00:00 2001 From: ssw Date: Mon, 20 Jul 2026 11:46:50 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20trim=20form-create.md.tmpl=20(208?= =?UTF-8?q?=E2=86=92~55=20lines)=20+=20inline=20prechecks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Template now: 4 steps (context→dm+form+release→menu→verify+learnings). Removed: historical notes, AI 4-limitations (dacli v2 auto_fix covers), Step 0 design doc preamble (belongs in design.md, not template), dacli skill reference (archived). ssw-loop SKILL.md: subagent prechecks now inlined into dispatch prompt, ensuring main agent passes them to subagent directly. Key design: template is short enough to be read fully by subagent. dacli v2 auto_fix handles corrections → template doesn't need to teach subagent about FK/datePicker/dictType rules. Co-Authored-By: Claude --- skills/ssw-loop/SKILL.md | 19 +- .../templates/subagent/form-create.md.tmpl | 220 ++++-------------- 2 files changed, 51 insertions(+), 188 deletions(-) diff --git a/skills/ssw-loop/SKILL.md b/skills/ssw-loop/SKILL.md index 68b21f9..c302479 100644 --- a/skills/ssw-loop/SKILL.md +++ b/skills/ssw-loop/SKILL.md @@ -44,17 +44,18 @@ description: JNPF + dacli 软件开发流程, 7阶段 (init→design→review→ ## 🤖 子代理 -**强制路径**: `templates/subagent/form-create.md.tmpl` +主代理派子代理时, 必须把以下前置注入 prompt: -**前置**: -1. `Read .claude/CLAUDE.md` -2. `dacli app context --json` -3. `dacli app status` +``` +前置: +1. dacli app context --json (拿 dbLinkId/existingEnCodes) +2. cat docs/{app_code}/learnings.md | tail -100 (前 N 个 form 踩坑) +3. dacli app status (确认登录) -**红线**: -- ❌ 禁止改 `dacli/`、`web/`、`uniapp/`、`jnpf/` -- ✅ 允许改 `docs/{app_code}/*.md` + `boot/ssw-{app_code}-biz/` -- ❌ 禁止 curl 绕 dacli +红线: 不读 learnings 不开工. 不改 dacli/web/uniapp/jnpf. 不 curl 绕 dacli. + +任务模板: templates/subagent/form-create.md.tmpl (~50 行, 4 步: 读→建→菜单→验证) +``` **learnings.md**: 每 form 必写 1 段 (试通命令+踩坑+关键决策), 不写=任务失败 (关卡 C). diff --git a/skills/ssw-loop/templates/subagent/form-create.md.tmpl b/skills/ssw-loop/templates/subagent/form-create.md.tmpl index a7dbcc2..d13f013 100644 --- a/skills/ssw-loop/templates/subagent/form-create.md.tmpl +++ b/skills/ssw-loop/templates/subagent/form-create.md.tmpl @@ -1,207 +1,69 @@ -# 任务: 在 app={app_code} 创建表单 {enCode} ({中文名}) +# 任务: 创建表单 {enCode} ({中文名}) @ {app_code} -> **零应用信息**: 本 prompt 中所有具体值 (dbLinkId/parentId/formId) 由你 (子代理) 通过 `dacli app context --json` 和 `dacli form info {enCode}` 动态获取. 不要硬编码. +> 主代理已跑 `dacli app context --json`。你从 Step 1 开始。 ---- +## 红线 (违反=失败) -## ⚠️ 前置 context (强制 4 步, 不读不工作) +- ❌ 不读 learnings.md 直接开工 +- ❌ 改 `dacli/`、`web/`、`uniapp/`、`jnpf/` +- ❌ curl 绕 dacli +- ❌ 不写 learnings.md 回执 -**未跑完 4 步, 禁止进入"任务" 段**. +## 执行 (4 步) -1. **Read `$ccWorkDir/.claude/CLAUDE.md`** (项目铁律, §2.6 必读, §dacli 完善优先) -2. **Run `cd $ccWorkDir/dacli && npx tsx src/cli.ts app context --json --appCode={app_code}`** (拿 dbLinkId/existingEnCodes/草稿 vs 发布) -3. **Read `$ccWorkDir/.claude/skills/dacli/SKILL.md`** (前 80 行, 权威命令源) -4. **Run `dacli app status`** (确认登录状态和 app_code) - ---- - -## ⚠️ Step 0 必读设计文档 (2026-07-16 jxcj M1 阶段 7 实战教训, 跨 app 通用强制) - -**漏读 = 任务失败, 派你来之前已设计好 AI 易错点, 你必须照单全收**. +### 1. 读上下文 (3 分钟) ```bash -# 0.1 找本模块的设计文档 -ls docs/{app_code}/drafts/m--design.html 2>/dev/null -# ↑ 例: docs/jxcj/drafts/m1-audit-design.html - -# 0.2 必读 §3 字段 + § AI 易错 段 -grep -B2 -A50 "AI 易错" docs/{app_code}/drafts/m--design.html | head -200 -# ↑ design.html §3.1.2/3.2.2 字段表 "AI 易错" 列标了每个字段的易错点 (11+ 处) -# ↑ 例: "f_team_id (BIGINT FK) ⚠️ AI 易错: 不会自动 relationForm, 必手动改 jnpfKey=relationForm; 列数 ≤ 5" -# ↑ 例: "f_status (INT 字典) ⚠️ AI 易错: int + dictType 不自动转 select, 必显式 fieldComponent=\"select\"" -# ↑ 例: "f_total_score (DECIMAL) ⚠️ AI 易错: readOnly 必填, 系统写; inputNumber precision=2" - -# 0.3 把"AI 易错"摘录写到你的 --ai 描述里 (避免重复踩坑) -# 例: --ai "...f_team_id (BIGINT FK 必填 relationForm 关联 team 表 显示字段 f_team_name 列数 ≤5)..." - -# 0.4 没设计文档? 读 `.claude/skills/dacli/references/form-create-ai-prompt-template.md` (5 段结构模板) +dacli app context --json # dbLinkId / existingEnCodes +cat docs/{app_code}/learnings.md | tail -100 # 前 N 个 form 的踩坑 ``` -**为什么必读** (jxcj M1 阶段 7 重建根因): -- M1 阶段 4 派子代理时**没强制**读 design.html "AI 易错" 段 → 11 form 全踩坑 (FK inputNumber / 时间无 format / 字典不转 select) -- 阶段 7 重建**也踩了** 9 个 relationForm 字段都要 form update + Python PUT 绕开 (form update 不同步物理表) -- 跨 app 通用: M2+ 派子代理, 必读 design.html "AI 易错" 段, 1 步避坑 - ---- - -## ⚠️ 禁止改 dacli (§2.6 铁律, 红线) - -- ❌ 禁止改 `$ccWorkDir/dacli/`、`web/`、`uniapp/`、`jnpf/` -- ✅ 允许改 `docs/{app_code}/learnings.md`、`$ccWorkDir/boot/ssw-{app_code}-biz/` -- ❌ dacli FAIL → **立即停, 派新子代理修 dacli** (4 步法: 读源码 → 复现 → 修 → 验证) -- ❌ 禁止用 curl 绕过 dacli -- ❌ 禁止在主任务打补丁绕过去 - -**为什么**: workaround 是 dacli 永远补不齐的债务. 不修复会让下一轮 AI 重新踩同样的坑. - ---- - -## ⚠️ 用法 (必须从 learnings 读最新成功案例) - -1. **Read `$ccWorkDir/docs/{app_code}/learnings.md`** (前 N 个 form 试通的踩坑) -2. **If empty** → Read `$ccWorkDir/.claude/skills/dacli/references/jnpf-design-rules.md` §13 -3. **Read `$ccWorkDir/.claude/skills/ssw-loop/references/subagent-must-do.md`** (子代理强制清单) - ---- - -## 🎯 任务 (5 步顺序) - -### Step 1: 查 dbLinkId 和 existingEnCodes +### 2. dm → form → release ```bash DBLINK=$(dacli app context --json | jq -r .dbLinkId) -EXISTING=$(dacli app context --json | jq -r '.existingEnCodes | join(",")') -echo "dbLinkId: $DBLINK" -echo "existingEnCodes: $EXISTING" + +# 建物理表 (如果还没建) +dacli dm create --table={enCode} --tableName={中文名} --dbLinkId=$DBLINK \ + --fields='[{...}]' + +# 建表单 (dacli v2.0+ auto_fix 自动修正常见问题) +dacli form create --ai "{中文名}: {字段描述}" \ + --fullName={中文名} --enCode={enCode} --autoRelease + +# 查看修正记录 +dacli log last ``` -**如果 `{enCode}` 已在 EXISTING**: ❌ 改名 (加 `_v2` 后缀) 或 派代理删旧 form (走 `dacli form delete`). 不要重复创建. - -### Step 2: dm create (物理表) +### 3. 挂菜单 ```bash -dacli dm create --table={enCode} \ - --tableName={中文名} \ - --dbLinkId=$DBLINK \ - --fields='[ - {"field": "f_name", "fieldName": "名称", "dataType": "varchar", "dataLength": "100", "allowNull": 0}, - ... (按 design.html 填) - ]' +PARENT=$(dacli menu list | jq -r '.data.list[] | select(.fullName | contains("{父菜单名}")) | .id' | head -1) +FORM_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="{enCode}") | .id') +dacli menu create --formId=$FORM_ID --fullName={中文名} --enCode={enCode} --parentId=${PARENT:--1} ``` -### Step 3: form create (web 表单, v0.13+ BS-新28) - -> **v0.13+ 强制**: `--ai <自然语言描述>` (NCPF backend AI + web buildFormData, 一条命令端到端). 旧 `--ai='[{...}]'` (JSON 字段列表) 已废弃. `--ai-json` 已删. `--fields` 简化版已废弃 (用 `--autoTable` 自动从 `--fields` 推 tables). -> -> **⚠️ AI 已知 4 限制** (2026-07-15 jxcj M1 实战, R16/R17 待修): -> 1. **控件类型选错**: `f_organizer` 被选 `depSelect` (应是 input), `f_start_time` 被选 `timePicker` (应是 datePicker). R16 FormRepair 修不了 (label 模糊) -> 2. **幻觉字段**: AI 凑足字段多生 `input_num001` / `inputNumber_num001` (业务外字段) -> 3. **required 误标**: 启发式兜底只标 1 字段 (`f_wechat_qrcode` 上传控件被误标), POST 失败 -> 4. **未生成 relationForm**: `f_*_id` 关联字段被生成为 input (BS-新117 未 wire up, R17 P0) -> -> **强制验证 (Step 5 必跑)**: 生成后立即 `dacli form info {enCode}` 读 schema, 检查 4 项: -> - 字段数匹配 design.html (无幻觉字段) -> - jnpfKey 正确 (无 depSelect/timePicker 等易错选) -> - `f_*_id` 字段 jnpfKey=relationForm (不是 input, 不满足则 `dacli form update` 修) -> - required 字段符合业务规则 (上传控件/富文本不应 required) -> -> **复杂表单推荐 (M2+ 决策树)**: -> - 简单表单 (≤5 字段, 无 `_id` 关联) → `--ai "<描述>"` (主推) -> - 复杂表单 (>5 字段 或 含 `_id` 关联) → **强制** `--table=<物理表>` 或 `--fields '<显式 JSON>'` 完全控制 +### 4. 验证 + 写 learnings ```bash -# 推荐 (v0.13+ 主推): 自然语言描述, 平台 LLM 生成完整 schema -dacli form create \ - --ai="{中文名}管理, 含名称 (必填 varchar 100) + 备注 (text) + 创建时间 (datetime)" \ - --webType=2 \ - --dbLinkId=$DBLINK \ - --fullName={中文名} \ - --enCode={enCode} \ - --autoRelease - -# 复杂表单备选 (M2+ 推荐, 避免 AI 4 限制): -dacli dm create --table={enCode} --tableName={中文名} --dbLinkId=$DBLINK --fields='[...]' # 先建物理表 -dacli form create --table={enCode} --fullName={中文名} --enCode={enCode} --autoRelease # 镜像 web schema -dacli form create \ - --fields='[{"field":"f_name","fieldTitle":"名称","dataType":"varchar","dataLength":"100","required":true}]' \ - --autoTable \ - --webType=2 \ - --dbLinkId=$DBLINK \ - --fullName={中文名} \ - --enCode={enCode} \ - --autoRelease +dacli test run --formId=$FORM_ID # TC-A: 数据层 CRUD +dacli test render --module=form --formId=$FORM_ID # TC-C: 源码渲染 +dacli form info {enCode} | jq '{enCode,id,state}' ``` -### Step 4: menu create (挂菜单) +写 1 段到 `docs/{app_code}/learnings.md` (试通命令 + 踩坑 + 关键决策)。 -```bash -# 4.1 查父菜单 (按用户给的中文名) -PARENT_ID=$(dacli menu list | jq -r '.data.list[] | select(.fullName | contains("{父菜单名}")) | .id' | head -1) -if [ -z "$PARENT_ID" ]; then PARENT_ID="-1"; fi - -# 4.2 拿 formId (从 step 3 输出解析) -FORM_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode == "{enCode}") | .id') - -# 4.3 创建菜单 -dacli menu create --formId=$FORM_ID --fullName={中文名} --enCode={enCode} --parentId=$PARENT_ID -``` - -### Step 5: 验证 + 写 learnings (强制) - -```bash -# 5.1 验证 form 已发布 -dacli form info {enCode} | jq '{enCode, id, state}' - -# 5.2 验证菜单 -dacli menu list | jq '.data.list[] | select(.enCode == "{enCode}") | {enCode, id, fullName}' - -# 5.3 写 1 段到 learnings.md (强制, 不写 = 任务失败) -# 模板: $ccWorkDir/.claude/skills/ssw-loop/templates/learnings.md.tmpl -``` - ---- - -## 📤 完成回执 (JSON, 主代理 parse 这段) - -输出严格 JSON (主代理会 parse): +## 回执 ```json -{ - "enCode": "{enCode}", - "formId": "<从 dacli form info 拿>", - "state": 1, - "menuId": "<从 dacli menu list 拿>", - "learnings_written": true, - "踩坑_count": , - "耗时_seconds": , - "next_step_hint": "<可选, 主代理下步提示>" -} +{"enCode":"{enCode}","formId":"","state":1,"menuId":"","learnings_written":true,"踩坑":} ``` -主代理 parse 后会写 1 行到 plan.html "已决事项" 表. +## 失败速查 ---- - -## ⚠️ 失败处理 (BS-XX 速查) - -| 错误 | 修复 | -|---|---| -| BS-49 enCode 重复 | 改名加 `_v2` 或 `dacli form delete` 重建 | -| BS-50 主表不存在 | 走低级模式 `dacli menu create --type=3 --urlAddress=model/{enCode}` | -| BS-48 dbLinkId 错 | 重跑 `dacli app context --json` 拿 | -| 数据库异常 | 必传 `--tables='[{table,tableName,fields}]'` 显式引用 | -| 菜单不显示 | 走高级模式 `--formId=` 走 Actions/Module, 或手动补 propertyJson.moduleId | - -详见 `.claude/skills/dacli/references/errors.md` 决策树. - ---- - -## 🚨 强约束 (漏任一 = 任务失败) - -- [ ] 跑完 4 步前置 -- [ ] 没改 dacli/web/uniapp/jnpf -- [ ] 没用 curl 绕 dacli -- [ ] 读 learnings.md -- [ ] 5 步任务顺序执行, 不跳步 -- [ ] **写 1 段到 learnings.md** (关卡 C 检测) -- [ ] 输出 JSON 回执 +| 症状 | 命令 | +|------|------| +| enCode 重复 | 改名 `_v2` 或 `dacli form delete ` | +| dbLinkId 错 | `dacli app context --json` 重拿 | +| 菜单不显示 | `dacli menu create --type=3 --urlAddress=model/{enCode} --parentId=-1` | +| 修正不对 | `dacli log last` 查回滚命令 |