draftgo-cli 2.0.3 → 2.0.5

package/resources/skill/rules/dev-workflow.md

@@ -23,6 +23,33 @@ version: 1.0.0
 
 ---
 
+## 交付追求（强制但不模板化）
+
+DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快速交付高质量项目：
+
+- **开发的急速感**：先用 `draftgo map`、本地 index、现有资源和最小必要规则快速建立上下文；小修和轻功能不要被表格化流程拖慢。
+- **逻辑与实现的完整**：默认真实数据、真实入口、真实反馈、真实验证；页面、导航、DB、脚本、权限和后台维护按用户路径闭环推断。
+- **迭代性强**：文件命名、route、数据 schema、组件结构、changelog、Task/lessons 记录要让下一次 AI 或开发者能继续接手。
+- **前端 UI 交给 shadcn 能力**：平台壳层默认 React + shadcn/ui + Tailwind；数据库 HTML 页面中的 `dg-*` 必须理解为 shadcn 的 DraftGo HTML 协议表达。若本地 Agent 环境存在 shadcn / 前端 UI 相关 Skills，前端界面开发时优先调用；DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法。
+
+判断一版交付是否合格：用户能从正常入口走通主路径，数据或操作不是假的，后续继续改不用重猜结构。
+
+---
+
+## 真实可用默认原则（强制）
+
+除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都默认按真实可用、可验证、可闭环处理。
+
+- 不要把功能降级成只有前端展示的假页面；按钮、表单、搜索、筛选、分页、提交、保存、删除、发布、管理等交互默认要有真实效果。
+- 不要用写死数组、静态卡片、空点击事件、只弹 toast 的按钮伪装业务能力；演示数据只能用于加载态、空态或用户明确要求的原型/demo。
+- 如果需求涉及可维护内容或业务记录，优先判断是否可用 DraftGo 动态 DB、已有 db_meta、custom_scripts、外部 API 或 AIHub 资产完成真实数据闭环。
+- **数据存储选型：业务数据优先用动态 DB 通用库。**
+- 若平台能力、权限、外部依赖或通用动态 DB 都无法支撑该功能，不要继续开发伪功能；向用户说明具体阻塞点、可选替代方案，并在 `.draftgo/lessons/` 记录“无法闭环原因 / 已验证限制 / 后续建议”。
+
+一句话判断：用户没有明确要假，就按真的做；做不了真的，就停下来说明，不写假的。
+
+---
+
 ## 轻量任务识别与用户意图翻译
 
 不要把流程做成固定填表。开发前先用 AI 自身判断力做一次轻量识别：这次是小修、轻功能、标准功能，还是高风险系统改动。识别结果用于决定规划深度，不要求每次都输出模板。
@@ -34,11 +61,13 @@ version: 1.0.0
 3. 看使用角色：访客、普通用户、管理员、运营、审核员、客服、内部人员等决定是否需要前台 / 后台 / 权限。
 4. 看现有项目结构：已有导航、页面命名、db_meta、custom_scripts、角色体系和 Story 都是默认推断依据。
 
+进入陌生项目、标准功能、多页面任务或用户描述较模糊时，先运行 `draftgo map` 快速获得资源地图；小修且目标文件明确时可以跳过。`draftgo map --output json` 可用于机器读取，不替代具体文件阅读。
+
 默认策略：
 
 - 用户说“修改 / 调整 / 优化某个已存在页面” → 默认按单资源改动处理；范围清晰则小修，影响主流程则轻功能或标准功能。
-- 用户说“做 / 新建 / 增加一个页面” → 默认按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定。只有用户明确说“静态页 / 纯页面 / 视觉稿 / demo / 先做效果”时，才允许按静态页面处理。
-- 用户说“做一个功能 / 模块 / 系统能力” → 默认按功能闭环处理，不能自动降级为单个展示页。
+- 用户说“做 / 新建 / 增加一个页面” → 默认按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定。只有用户明确说“静态页 / 纯页面 / 静态稿 / demo / mock / 假数据 / 伪功能 / 先做效果”时，才允许按静态页面处理。
+- 用户说“做一个功能 / 模块 / 系统能力” → 默认按功能闭环处理，不能自动降级为单个展示页或前端假数据。
 - 用户说“管理 / 维护 / 发布 / 审核 / 上下架” → 默认需要后台管理能力和真实数据闭环。
 - 用户说“官网 / 官方 / 平台 / 系统” → 不要做孤立页面；至少考虑导航入口、访问路径和完整用户路径。
 
@@ -236,7 +265,7 @@ C. <更完整方案>
 ☐ 2. 不做什么（边界）
 ☐ 3. 成功长什么样（验收）
 ☐ 4. 已知约束（用户角色 / 权限 / 数据结构 / 现有页面位置）
-☐ 5. 视觉 / 体验偏好（如果涉及前端 UI）
+☐ 5. 前端 UI 需求（如果用户明确提出）
 ```
 
 **追问优先用多选题**，开放题作为兜底。
@@ -316,7 +345,7 @@ related_changelog: YYYY-MM-DD
 - 不做：...
 - 验收：...
 - 约束：...
-- 视觉偏好：...
+- 前端 UI 需求：...
 
 ## 设计
 
@@ -442,6 +471,8 @@ Record   迭代记录 + 任务标记 + 同步
 
 ```
 1. 读 —— 读当前文件状态，理解现状（不读不改）
+        • 陌生项目 / 标准功能 / 多页面任务：先跑 `draftgo map`
+        • 涉及页面闭环：读取 pages/index.json、navigations/index.json 和相关 HTML
 2. 改 —— 做最小必要改动，不顺手改无关代码
 3. 演 —— 立即看效果：
         • 页面类：在浏览器里实测路径 / 四态 / 边界场景
@@ -471,10 +502,22 @@ Record   迭代记录 + 任务标记 + 同步
 
 1. **强制先读** `.draftgo/db_meta/index.json` 中对应 type 的 schema
 2. 字段名、字段类型、是否必填 **以 schema 为准**，不凭印象写
-3. 如果 `db_meta/index.json` 不存在或对应 type 缺失，先 `/draftgo pull db_meta` 刷新
+3. 要对某字段做检索/筛选（`filters`）或排序（`order_by`）前，先确认该字段在 schema 里标了 `searchable`，且操作符匹配其检索模式（`exact`→eq/in，`fuzzy`→eq/like/in，`range`→eq/gte/lte/gt/lt/in，`contains`→contains）；未标 searchable 或操作符不匹配后端返回 400
+4. 如果 `db_meta/index.json` 不存在或对应 type 缺失，先 `/draftgo pull db_meta` 刷新
 
 违反后果：字段名写错 → 数据静默丢失 → 排查成本极高。
 
+### custom_script 契约前置门（强制）
+
+当前端要对接某个 custom_script 的 route 端点（`App.callApi`、`fetch('/api/x/<slug>/...')`、DB 列表/表单页依赖某脚本的读写接口）时，**云端正在运行的脚本才是唯一契约真相，本地 `code_file` 不是**：
+
+1. **对接前强制确认"本地 = 云端"**：先 `python {{SKILL_SCRIPTS}}/draftgo_pull.py custom_scripts <id>` 拉云端运行版，或直接探测关键端点（如目标端点返回 404 即说明云端没有该 route）。两者一致才可按本地契约写前端。
+2. **本地领先时先推后接**：若本地脚本已演进但因 custom_scripts 推送的二次确认被跳过而未上云，必须先完成推送（push skill 的二次确认流程），不得对着"未上云的本地契约"写前端。
+3. **跳过推送必须留痕**：任何一次跳过 custom_scripts 推送，都要在 changelog 或 Task 里写明"本地脚本 vN 未上云"，避免后续 AI 误判已生效。
+4. **route 端点设计约束**：custom_script 的 route ctx 只有 `{body, query_params, headers, method, path, user}`，**没有 `path_params`**；基座不从 `/api/x/{slug}/{path}` 里提取 `{id}`/`{uid}` 这类路径模板。需要 id 的写操作（删除/编辑）一律走 `POST + body 带 id`，不要写 `@route("DELETE /xxx/{id}")` —— 这类 handler 取不到 path 参数，永远走异常分支，是死代码。
+
+违反后果：本地脚本 ≠ 云端运行版 → 前端对错契约 → 列表恒空 / 写读两套存储，排查极隐蔽。
+
 ### 执行禁区（继承现有规则）
 
 以下规则在根 [SKILL.md](../SKILL.md) "开发禁区"和 [frontend.md](./frontend.md) 中已有定义，执行时**全部生效**：
@@ -487,8 +530,12 @@ Record   迭代记录 + 任务标记 + 同步
 - ❌ `navigate('/login')` 退出（用 `window.location.href = '/login'`）
 - ❌ `window.alert / confirm / prompt`（用 `App.toast / confirm / showModal`）
 - ❌ 硬编码颜色（用 `var(--dg-*)` token）
+- ❌ 把 `dg-*` 当成自研 UI、daisyUI、Bootstrap、Ant Design 或 Element Plus（`dg-*` 只能表示 shadcn 的 HTML 协议形态）
+- ❌ 在数据库 HTML 页面直接写 React/TSX 版 shadcn 组件（应写对应 `dg-*` 标签，或补齐缺失映射）
 - ❌ `App.confirm` 不 `await`（详见 [debugging-syntax.md](./debugging-syntax.md) 第 3 条）
 - ❌ `await` 用在非 `async` 函数里（详见 [debugging-syntax.md](./debugging-syntax.md) 第 2 条）
+- ❌ custom_script 里写 `@route("DELETE /x/{id}")` 取 `ctx.path_params`（route ctx 无 path_params，需 id 的写操作走 POST+body）
+- ❌ 对着未上云的本地 custom_script 契约写前端（先 pull/探测确认本地=云端，见上「custom_script 契约前置门」）
 
 ### 调试方法论（升级 debugging-syntax.md 的清单为方法论）
 
@@ -519,8 +566,8 @@ Record   迭代记录 + 任务标记 + 同步
 按任务等级选择验证强度：
 
 - 小修：验证改动点命中、无明显报错、对应资源 push 成功。
-- 轻功能：验证真实入口可达、主路径交互有效、关键状态不空白、对应资源 push 成功。
-- 标准功能：验证入口、主流程、关键四态、数据读写 / 回读、关联页面跳转和 push 输出。
+- 轻功能：验证真实入口可达、主路径交互有效、关键状态不空白、`draftgo check` 无错误、对应资源 push 成功。
+- 标准功能：验证入口、主流程、关键四态、数据读写 / 回读、关联页面跳转、`draftgo check` 和 push 输出。
 - 高风险：在标准功能基础上增加人工确认、回读验证、影响范围说明和回滚 / 兜底方案。
 
 | 资源类型 | 完成证据 |
@@ -544,6 +591,20 @@ Record   迭代记录 + 任务标记 + 同步
 
 如果新页面只能靠手动输入 route 访问，且用户正常路径里看不到入口，视为未完成。若任务明确要求“只创建未公开页面”，必须在完成声明中说明该页面暂不绑定导航的原因。
 
+### CLI 闭环体检
+
+涉及页面、导航、DB、脚本或 AIHub 的轻功能 / 标准功能 / 高风险任务，push 前运行：
+
+```bash
+draftgo check
+```
+
+- 有 `错误`：先修复，不得声明完成。
+- 有 `提醒`：结合任务判断。若是未绑定入口、疑似 mock 数据、缺少真实调用，优先补齐；若是用户明确要求隐藏页 / demo，需在 changelog、Task 或完成说明中写明原因。
+- 需要把提醒也作为失败处理时运行 `draftgo check --strict`。
+
+`draftgo check` 只做本地启发式检查；浏览器点击、console、API 回读、push 输出仍然是最终证据。
+
 ### 禁用措辞
 
 - "应该 / 可能 / 看起来 / 大概 / Perfect / Done / 搞定 / 好了 / OK 了"
@@ -570,40 +631,6 @@ Record   迭代记录 + 任务标记 + 同步
 
 ---
 
-## 前端审美方向（只立方向，不立细则）
-
-不强制设计 token、不强制栅格规格、不强制颜色清单。但给三个方向 + DraftGo 项目内的硬约束。
-
-### 三个方向
-
-| 方向 | 含义 | 锚点 |
-|-----|------|------|
-| **现代工艺** | 当下主流审美：克制留白、精细对齐、轻量阴影、合理动效、高质感字体与间距 | 参考 Linear / Vercel / Apple HIG / Notion；避免低质感套模板、无意义大色块和粗糙过渡 |
-| **艺术风** | 不止"能用"，要有视觉记忆点：节奏感、对比、层次、有调性的克制装饰 | 允许有调性的色彩组合、有质感的字体搭配（已有本地 Inter / Lexend / Plus Jakarta Sans / JetBrains Mono Nerd Font）、几何 / 微插画点缀；允许根据项目气质探索更鲜明的视觉语言 |
-| **用户体验** | 状态完整、操作可逆、反馈即时、信息层级清晰 | **四态必做**：空态 / 加载态 / 错误态 / 成功态。Toast 用 `App.showSuccess / Error / Warning / Info`，确认用 `App.confirm`，禁用 `window.alert` |
-
-### DraftGo 项目内的硬约束（继承 frontend.md）
-
-- 颜色：必须 `var(--dg-*)` token，禁止硬编码 hex / rgb
-- 圆角：默认 `rounded-md`（6px）；如需表达品牌感、卡片层级或营销视觉，可使用更大圆角，但需保持页面内节奏一致
-- 组件类名：`-dg` 结尾（`input-dg / btn-dg-primary / btn-dg-secondary / btn-dg-danger`）
-- 字体：用本地 `/assets/fonts/*.css`
-- 图标：用本地 `/assets/fontawesome/css/all.min.css`
-- 静态资源：禁止境外 CDN
-- 主题：必须适配 light / dark + 三套配色方案
-
-### 给 AI 的自由
-
-在"现代工艺 + 艺术风 + UX"三轴里**自由生长**。但**视觉变动必须可视化**：涉及布局 / 配色 / 风格选择时，主动产出 ASCII mockup 或 HTML 草图给用户看，而不是嘴上描述。
-
-### 唯一红线（敏感场景）
-
-登录 / 支付 / 删除确认 / 错误提示 / 权限拒绝：
-- 禁止抖机灵、禁止网络梗、禁止阴阳怪气
-- 文案保持清晰、中性、礼貌、可操作、低情绪浓度
-
----
-
 ## 与现有规则的关系
 
 | 现有规则 | 本规范如何对接 |
@@ -611,7 +638,7 @@ Record   迭代记录 + 任务标记 + 同步
 | 根 [SKILL.md](../SKILL.md) "开发分级" | 本规范提供小修 / 轻功能 / 标准功能 / 高风险分级与执行依据 |
 | 根 [SKILL.md](../SKILL.md) "命令路由" | 增加触发：开发任务前先进本规范做任务分级 |
 | 根 [SKILL.md](../SKILL.md) "开发禁区" / "App API" / "数据库 Schema" / "API 速查" | 继续生效，执行门第 6 步验证依赖它们 |
-| [frontend.md](./frontend.md) | 继续生效，本规范的"前端审美方向"与它互补 |
+| [frontend.md](./frontend.md) | 继续生效，提供 DraftGo 前端运行时、资源、数据、路由、入口绑定和验证方法 |
 | [debugging-syntax.md](./debugging-syntax.md) | 继续生效，本规范第 3 章"调试方法论"在其之上加方法论 |
 | 迭代记录规范（根 SKILL "迭代记录规范"段） | TDR 循环第 4 步复用 |
 | 错误日志规范（根 SKILL "错误日志规范"段） | 取证阶段复用 |
@@ -622,4 +649,4 @@ Record   迭代记录 + 任务标记 + 同步
 
 ## 一句话总结
 
-> **先分级：小修直接定位改完验证推送；轻功能范围复述后直接做；标准功能轻量确认后 Task + TDR；高风险走完整 Story / 计划 / 验证 / 人工确认。审美只立方向，质量靠证据。追问必带推测意图，新增页面必须绑定真实入口。**
+> **先分级：小修直接定位改完验证推送；轻功能范围复述后直接做；标准功能轻量确认后 Task + TDR；高风险走完整 Story / 计划 / 验证 / 人工确认。前端 UI 交给本地 Skills，DraftGo 质量靠真实链路和证据。追问必带推测意图，新增页面必须绑定真实入口。**