draftgo-cli 3.0.1 → 3.0.33

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

@@ -1,652 +0,0 @@
----
-name: draftgo-dev-workflow
-description: DraftGo 开发流程规范。所有"开发 / 修改 / 新建 / 重构 / 修复"类任务先分级：小修、轻功能、标准功能、高风险，再执行对应流程。
-version: 1.0.0
----
-
-# DraftGo 开发流程规范
-
-> 这份规范不替换 [frontend.md](./frontend.md) 与 [debugging-syntax.md](./debugging-syntax.md)，它们仍然生效。这份规范先做任务分级，保证简单问题不被流程拖慢，复杂问题仍然有完整闭环。
-
----
-
-## 总则：四档开发流程
-
-```
-小修       直接定位 → 改 → 轻量证据
-轻功能     范围复述 → 直接做 → 凭证据闭环
-标准功能   轻量确认 → 内部短计划 → 执行闭环
-高风险     完整 Story / 计划 / 验证 / 人工确认
-```
-
-例外：纯工具操作（`/draftgo init`、`/draftgo push`、`/draftgo status`、`/draftgo doctor`、`/draftgo story`、查 API、查页面元数据、读文件、回答问题）**不走开发流程**。
-
----
-
-## 交付追求（强制但不模板化）
-
-DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快速交付高质量项目：
-
-- **开发的急速感**：优先用本地 index、目标文件、现有资源和最小必要规则快速建立上下文；资源关系不清时再用 `draftgo map`。小修和轻功能不要被表格化流程拖慢。
-- **逻辑与实现的完整**：优先考虑真实落地闭环、高可用；默认真实数据、真实入口、真实反馈和必要证据。页面、导航、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 自身判断力做一次轻量识别：这次是小修、轻功能、标准功能，还是高风险系统改动。识别结果用于决定规划深度，不要求每次都输出模板。
-
-当用户用业务语言而不是开发术语描述需求时，先把它翻译成产品结果，再落到开发任务。判断顺序：
-
-1. 看业务对象：案例库、新闻中心、产品中心、服务体系、会员、订单、预约、招聘、资料下载等通常是模块或功能，不是一个孤立静态页。
-2. 看动作词：展示、查看、筛选、搜索、提交、预约、发布、管理、维护、新增、编辑、删除、审核、上下架等决定功能深度。
-3. 看使用角色：访客、普通用户、管理员、运营、审核员、客服、内部人员等决定是否需要前台 / 后台 / 权限。
-4. 看现有项目结构：已有导航、页面命名、db_meta、custom_scripts、角色体系和 Story 都是默认推断依据。
-
-进入陌生项目、资源关系不清、多页面任务或用户描述较模糊时，先运行 `draftgo map` 快速获得资源地图；目标文件明确的小修和局部改动可以跳过。`draftgo map --output json` 可用于机器读取，不替代具体文件阅读。
-
-默认策略：
-
-- 用户说“修改 / 调整 / 优化某个已存在页面” → 默认按单资源改动处理；范围清晰则小修，影响主流程则轻功能或标准功能。
-- 用户说“做 / 新建 / 增加一个页面” → 默认按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定，并优先考虑真实落地闭环、高可用。只有用户明确说“静态页 / 纯页面 / 静态稿 / demo / mock / 假数据 / 伪功能 / 先做效果”时，才允许按静态页面处理。
-- 用户说“做一个功能 / 模块 / 系统能力” → 默认按功能闭环处理，不能自动降级为单个展示页或前端假数据。
-- 用户说“管理 / 维护 / 发布 / 审核 / 上下架” → 默认需要后台管理能力和真实数据闭环。
-- 用户说“官网 / 官方 / 平台 / 系统” → 不要做孤立页面；至少考虑导航入口、访问路径和完整用户路径。
-
-只有当不确定点会明显改变页面数量、数据结构、后台能力、权限或风险时，才向用户确认。确认最多 1-3 个问题，并给出推荐默认值；其余细节由 AI 自主推断，并按任务等级记录到范围复述、内部短计划或 Task 中。
-
-### 用户路径链路（功能任务默认视角）
-
-规划功能时，不要只从“要创建几个页面”看问题，要从完整使用链路倒推资源：
-
-```
-用户打开官网 / 系统入口
-→ 在导航、首页模块、按钮或列表中看见入口
-→ 点击进入目标页面
-→ 浏览 / 搜索 / 筛选 / 查看详情 / 提交表单
-→ 获得成功、失败、空态、权限不足等反馈
-→ 管理员在后台维护同一份数据
-→ 前台再次读取到维护后的真实结果
-```
-
-按这条链路推断需要哪些页面、导航、数据、API、自定义脚本、权限和验证。链路里某一步走不通，就不能把功能声明为完成。
-
----
-
-## 任务分级（先判级，再执行）
-
-### 小修
-
-**定义：** 范围明确、影响面单一、可在一个资源内完成的小改动。
-
-典型场景：
-- 修一个文字、链接、图标、按钮位置、样式小问题
-- 修一个明确报错或禁区违规（如 `window.location.search`、`App.confirm` 忘 `await`）
-- 调整单个页面的一处文案、颜色 token、空态展示
-- 对单个已知资源执行小范围补丁
-
-流程：
-```
-1. 定位：读目标 index / 文件，确认 resource id 与文件路径
-2. 改：只做最小必要改动
-3. 证据：用与改动匹配的轻量方式确认命中（文件回读 / 语法检查 / diff / 必要的本地检查）
-4. 同步：需要云端生效或用户要求时再 push
-5. 记录：影响可见功能、已 push 或有接手价值时写 changelog
-```
-
-小修不需要 Story 门、需求门、Task 文档，也不需要并行分发。若执行中发现影响面扩大，立即升级为「轻功能」或「标准功能」。
-
-小修优先只读目标资源和最小必要规则；如果执行中发现命中平台禁区、需要新增入口、影响主流程或范围扩大，再补读对应规则并升级分级。
-
-### 轻功能
-
-**定义：** 有明确用户价值、需要真实交互或少量数据联动，但范围集中、资源少、风险低，不需要完整 Task 计划即可顺畅完成。
-
-典型场景：
-- 给现有页面新增一个筛选、提交、跳转、下载、状态反馈等小能力
-- 新增一个简单可用页面，并绑定一个入口
-- 单页面接入一份已有 DB / 外部 API / AIHub 能力
-- 补齐一个局部用户路径，但不涉及权限、账号、生产脚本或复杂数据结构
-
-流程：
-```
-1. 范围复述：一句话说明要做什么、入口在哪里、如何验证
-2. 直接做：读目标资源，按最小闭环实现
-3. 主路径验证：入口可达、核心交互有效、关键状态不空白
-4. 证据闭环：按影响选择 check / push / changelog
-```
-
-轻功能不强制创建 Task 文档，不强制 depends/resource_lock/wave，也不启用并行。若执行中发现需要多个页面协作、后台管理、复杂权限或资源冲突，升级为「标准功能」。
-
-### 标准功能
-
-**定义：** 新增或调整一个可感知的业务能力，需要多个步骤、多资源协作或较多用户体验判断，但不直接触碰权限、账号、生产脚本等高风险资源。
-
-典型场景：
-- 新建页面 / 改造页面主流程
-- 页面联动 DB / 外部 API / AIHub
-- 新增导航入口并配套页面
-- 新增普通文档、普通 db_meta、非敏感配置
-
-流程：
-```
-1. 若 .draftgo/story.yaml 存在，静默加载；不存在时不阻塞开发，完成后提醒补 Story
-2. 轻量确认：意图翻译 + 必要追问 + 范围复述
-3. 内部短计划：列清资源、入口、数据、关键交互和证据形式；跨资源、多页面协作、并行或高风险时再创建 Task
-4. 执行门：按短计划逐项实现
-5. 闭环门：证据 + 按影响选择 changelog / check / push；有 Task 时同步标记
-```
-
-标准功能任务最低规划要求：写清楚用户路径链路、页面入口/导航绑定、前台与后台是否需要同一份数据、哪些交互必须真实有效。不要把“页面看起来存在”当成“功能完成”。
-
-### 高风险
-
-**定义：** 可能影响权限、安全、账号、生产自动化、数据结构、已有关键业务流或系统定位的改动。
-
-典型场景：
-- roles / users / 权限策略 / 登录注册 / 支付 / 删除恢复
-- custom_scripts 启停、生产 route 脚本、scheduled 脚本
-- db_meta 结构性变更、批量数据修改、系统配置敏感项
-- 与 `.draftgo/story.yaml` 的 `identity.not` 或 active decision 冲突
-- 首页 `.draftgo/pages/page_1_root.html` 的整站门面重做（见 frontend.md 特例），或任何会改变产品第一印象的重设计
-
-流程：
-```
-1. Story 门：无 .draftgo/story.yaml 必须先构建；有则静默加载并做冲突检测
-2. 完整确认：挖透关键风险、边界和验收，复述确认后才动手
-3. 计划门：Task 文档 + 风险点 + 回滚/验证方案 + 人工确认点
-4. 执行门：轻量闭环执行；涉及 roles/users/custom_scripts 等按 push skill 要求二次确认
-5. 闭环门：真实验证证据 + push 输出 + 回读结果 + 影响范围说明
-```
-
----
-
-## Story 门（高风险必走，标准功能可加载）
-
-### 触发
-
-高风险任务必须静默检查 `.draftgo/story.yaml`。标准功能任务若文件存在则静默加载；不存在不阻塞开发。小修和轻功能不触发 Story 门。
-
-### 行为
-
-```
-├─ 文件存在 → 静默加载全文，Story 作为最高优先级上下文锚定 → 过门
-├─ 文件不存在且任务为高风险 → 暂存用户开发请求 → 进入 Story 构建流程
-│   ├─ 有页面/数据 → 路径 A（扫描推断 + 确认）
-│   └─ 空项目     → 路径 B（对话式采集）
-├─ 文件不存在且任务为标准功能 → 继续开发，收尾提醒补 Story
-└─ 构建完成后 → 回到用户原始请求 → 继续走轻量确认 / 完整确认
-```
-
-### Story 构建流程
-
-详见 `{{SKILL_DIR}}/story/SKILL.md`。
-
-### 运行时冲突检测
-
-整个对话过程中，Story 持续生效。当用户请求与 Story 的 `identity.not` 或 active 状态 `decisions` 冲突时：
-- 明确告知冲突点
-- 给出 A) 想法变了 / B) 双轨并行 / C) 只是特例 三个选项
-- 用户选择后更新或不更新 Story
-
-### 主动沉淀
-
-开发过程中检测到方向性决策（拒绝建议、方案选择、调性偏好），主动提议是否记入 `decisions`。
-
-### 红线
-
-- 高风险任务中 Story 门不可跳过、不可拖延
-- 标准功能任务允许先开发后提醒补 Story；小修和轻功能不需要 Story
-- Story 加载失败（yaml 格式损坏）时提示用户修复，不可忽略继续开发
-
----
-
-## 轻量确认（标准功能 / 高风险）
-
-### 触发
-
-任务分级为「标准功能」或「高风险」时进入确认。小修跳过确认，除非目标文件或验收条件不明确；轻功能只做简短范围复述，不进入完整确认门。
-
-### 标准功能任务：默认推断，少量确认
-
-> **标准功能任务的目标是让 AI 发挥判断力，而不是让用户填产品表。**
-> 先根据用户提示词、现有项目结构和用户路径链路推断合理实现范围；只有关键分叉会明显改变工作量或系统行为时才追问。
-
-必须主动推断：
-- 这是改现有页面、新增单页面、新增多页面，还是完整功能模块
-- 用户从哪里进入：官网首页、导航栏、列表入口、按钮、后台菜单
-- 新页面是否要绑定到导航栏 / 首页入口 / 后台菜单 / 相关页面按钮
-- 是否需要前台展示、后台维护、真实数据读写、搜索筛选、详情页、表单提交
-- 是否存在权限、状态流转、上下架、审核等隐含操作
-
-确认规则：
-- 不要为了填满维度而追问；能从上下文合理推断的，直接采用并记录。
-- 只问会改变页面数量、数据结构、权限、后台能力、外部 API、生产风险的问题。
-- 一次最多 1-3 个问题，必须带推荐默认值。
-- 用户说“你看着办 / 按你理解来 / 直接做”时，按推荐默认值继续，不要反复卡住。
-
-轻量确认写法：
-```
-我理解这是：<页面 / 多页面 / 功能模块>。
-我会按 <推荐范围> 做：<前台入口 + 页面 + 数据 / 后台 / 绑定 / 验证摘要>。
-
-[如有关键分叉]有一个点会影响范围：
-A. <推荐方案>
-B. <更轻方案>
-C. <更完整方案>
-
-你选哪个？或者我理解错了？
-```
-
-### 高风险任务：完整确认
-
-高风险任务仍需更完整确认。按需挖透五维度，但仍然避免机械填表：
-
-```
-☐ 1. 要做什么（目标）
-☐ 2. 不做什么（边界）
-☐ 3. 成功长什么样（验收）
-☐ 4. 已知约束（用户角色 / 权限 / 数据结构 / 现有页面位置）
-☐ 5. 前端 UI 需求（如果用户明确提出）
-```
-
-**追问优先用多选题**，开放题作为兜底。
-
-### 范围复述
-
-```
-我理解你要：
-- 目标：...
-- 范围：在 ... 做 ...
-- 用户路径：从 ... 进入 → ... → ... → 得到 ...
-- 页面 / 入口绑定：...
-- 数据 / 后台：...
-- 不做：...
-- 验收：...
-- 约束 / 风险：...
-
-对吗？
-```
-
-标准功能任务：用户明确点头，或用户授权“按你理解做”，都算过门。
-高风险任务：必须明确点头（"对 / 可以 / 就这样 / 行 / OK"）才算过门；模糊回应要再追一次。
-
-### 红线
-
-- 轻功能 / 标准功能都禁止把用户的“页面”默认当成静态页；除非用户明确说静态 / 纯页面 / demo。
-- 没带推测的追问 = 失职；向非技术用户索要 CRUD、API、路由等术语 = 失职。
-- 高风险任务没复述确认前禁止写代码、写文档、开 Task。
-- 复述完，**之后不再回头打扰用户**（除非执行中遇到真正阻塞）。
-
----
-
-## 计划门（按需 Task / 高风险，一次性产出，不打扰用户）
-
-轻量确认过了之后，AI 先做**内部短计划**并直接执行；只有跨资源、多页面协作、并行开发、需要长期接手或高风险任务，才把设计 + 任务清单落到 `.draftgo/Task/` 文件夹。小修、轻功能和普通标准功能不创建 Task 文档。
-
-### Task 文件位置
-
-```
-<项目根>/.draftgo/
-├── changelog.md                     # 更新日志（单文件，按日期分节）
-├── lessons/                         # 开发经验与问题记录
-└── Task/                            # 任务清单
-    └── YYYY-MM-DD-<topic-slug>.md   # 每个开发任务一个文件
-```
-
-`/draftgo init` 会自动创建 `Task/` 目录。
-
-### Task 文件命名
-
-`YYYY-MM-DD-<topic-slug>.md`
-
-- topic-slug：英文小写 + 短横线连接，描述任务主题
-- 例：`2026-05-16-admin-users-export-button.md`
-
-### Task 文档模板
-
-````markdown
----
-date: YYYY-MM-DD
-status: in_progress       # in_progress | done | aborted
-topic: <一句话主题>
-related_changelog: YYYY-MM-DD
----
-
-# <主题>
-
-## 需求纪要（确认版）
-
-> 来自轻量确认 / 高风险确认的复述结果。**这段不再修改**。
-
-- 目标：...
-- 范围：...
-- 用户路径：用户从 ... 进入 → 点击 ... → 完成 ... → 获得 ...
-- 页面 / 入口绑定：新增或修改的页面如何出现在导航栏、首页、后台菜单或相关页面按钮中
-- 数据 / 后台：前台展示与后台维护是否使用同一份真实数据
-- 不做：...
-- 验收：...
-- 约束：...
-- 前端 UI 需求：...
-
-## 设计
-
-**架构定位**：本次改动落在哪一层（壳层 / 页面 HTML / 导航栏 / 后端 API / 自定义脚本 / AIHub 资产 / 系统配置）。
-
-**涉及资源**：
-- 页面：`pages/<file>.html`（page_id=xx）
-- 导航：`navigations/<file>.html`（nav_id=xx）
-- 外部 API / db_meta / aihub / custom_scripts：...
-
-**链路流**：入口（官网 / 导航 / 后台菜单）→ 页面 → 操作 → 数据读写 → 反馈 → 后台维护 → 前台展示
-
-**绑定点**：
-- 导航栏 / 菜单：...
-- 首页 / 列表 / 详情 / 按钮入口：...
-- 路由与 page_id 对应：...
-
-**四态考虑**（前端任务必填，后端可省）：
-- 空态（无数据时）：...
-- 加载态（请求中）：...
-- 错误态（请求失败 / 权限不足 / 校验失败）：...
-- 成功态（成功反馈方式）：...
-
-## 任务清单
-
-- [ ] T1. <任务名>  ⬜
-  - 类型：本地改文件 / 调 API / push / 自定义脚本执行
-  - 文件：`.draftgo/pages/admin-users.html`
-  - 步骤：
-    1. 读取当前文件，定位 X
-    2. 在 Y 位置插入 Z
-    3. 验证：文件回读 / draftgo check / 与改动匹配的轻量证据
-    4. 需要云端生效时调 push 脚本：`python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>`
-    5. 需要接手记录时写更新日志
-  - 验证证据：文件回读 / check / push 输出（如已推送）
-
-- [ ] T2. ... ⬜
-
-## 进度总览
-
-| 任务 | 状态 | 完成时间 | 证据摘要 |
-|-----|------|---------|---------|
-| T1  | ⬜   |         |         |
-| T2  | ⬜   |         |         |
-
-## 完成回顾（全部 ✅ 后填）
-
-- 实际改动：...
-- 偏离计划的地方：...
-- 后续 TODO：...
-````
-
-### 标记五态
-
-```
-⬜ 未开始    🟡 进行中    ✅ 已完成    ❌ 失败    ⏸ 暂停
-```
-
-每完成一个任务**立即两处更新**：
-1. 任务行 `- [ ]` → `- [x]`，状态 ⬜ → ✅
-2. 进度总览表的"完成时间"和"证据摘要"
-
-### 依赖分析与并行规划（按需）
-
-当 Task 清单涉及 3 个及以上任务、多个资源可能并行修改，或准备启用子代理时，为相关任务标注 `depends`、`resource_lock` 和 `wave`：
-
-```markdown
-- [ ] T1. 描述  ⬜
-  - depends: []
-  - resource_lock: pages/admin-users.html
-  - wave: 1
-```
-
-**规则**：
-- `depends: []` = 无依赖，可与其他无依赖任务并行
-- `depends: [T1, T3]` = 必须等 T1、T3 完成后才能开始
-- `resource_lock` = 该任务要修改的文件，同一 resource_lock 的任务不可并行
-- `wave` = 并行批次编号，无依赖任务为 Wave 1，依赖 Wave 1 的为 Wave 2，以此类推
-
-**依赖判定**：同一文件 → 依赖；数据依赖（需要前序产出）→ 依赖；不同文件且无数据关联 → 独立。
-
-单人串行或 1-2 个任务的小计划，不强制填写这些字段；只需写清目标、文件、步骤和验证证据。
-
-详细分发协议见 `{{SKILL_DIR}}/rules/parallel.md`。
-
-### 计划门红线
-
-- 计划禁止占位符：TBD / TODO / "类似 T2" / "做适当处理" / "加错误处理"。
-- 每个任务必须给：精确文件路径、操作类型、可执行步骤、验证证据形式。
-- 多任务 / 多代理 / 多资源冲突时必须给：`depends` + `resource_lock` + `wave` 三个字段；单人串行小计划不强制。
-- 新增页面必须有绑定任务或明确说明为什么不需要入口；默认应绑定到导航栏、首页、后台菜单或相关页面按钮之一。
-- 计划写完跑一次自审：**需求纪要每一条、用户路径每一步、页面绑定每一处能不能指到某个任务？** 不能就补任务。
-- 不需要再让用户确认（确认阶段已经定范围）。
-
----
-
-## 执行节奏（轻量闭环）
-
-DraftGo 主要场景是**改 HTML 页面、改导航、调 App API、写 custom_script、注册外部 API**。执行时保持小步、可理解、有证据：
-
-```
-Small    小步实现，一次只动清楚的一件事
-Evidence 用文件回读 / check / 与改动匹配的轻量证据确认
-Record   按影响选择 changelog / Task 标记 / push
-```
-
-### 并行分发（Wave 模式）
-
-当任务数 ≥ 3、存在多个 Wave 1 任务（`depends: []` 且 resource_lock 不冲突）、任务边界清晰，且并行收益大于协调成本时，主代理可启用并行：
-
-1. **分发**：为每个 Wave 1 任务生成子代理，携带上下文包（task 定义 + 当前文件 + 禁区摘要）
-2. **子代理执行**：每个子代理独立完成小步实现和证据确认，产出修改文件 + 验证报告；需要接手记录时再产出 changelog 条目
-3. **收集**：主代理收集所有子代理产出，写入文件系统
-4. **批量推送**：需要云端生效时运行 `python {{SKILL_SCRIPTS}}/draftgo_push.py --batch <type1> <id1>,<id2> <type2> <id3>`
-5. **Wave 2**：依赖已完成的任务可以开始，重复上述流程
-6. **闭环**：主代理统一汇总证据；有 Task 文档时再更新标记
-
-**退化条件**：平台不支持子代理 / 任务数不足 / 边界不清 / 协调成本更高 / 用户明确说"串行" → 静默退化为逐任务串行。
-
-详细协议见 `{{SKILL_DIR}}/rules/parallel.md`。
-
-### 每个任务的轻量执行
-
-```
-1. 读 —— 读当前文件状态，理解现状（不读不改）
-        • 资源关系不清 / 陌生项目 / 多页面任务：先跑 `draftgo map`
-        • 涉及页面闭环：读取 pages/index.json、navigations/index.json 和相关 HTML
-2. 改 —— 做最小必要改动，不顺手改无关代码
-3. 证 —— 用与改动匹配的轻量证据确认：
-        • 页面类：文件回读、入口引用、状态结构、关键交互代码路径
-        • API 类：用 App.callApi / Python urllib / 管理端测试端点真实跑一次
-                  （Windows 环境下 curl 对中文/特殊字符编码易出错，建议优先用 Python urllib/requests）
-        • custom_script：用 POST /api/scripts/{id}/execute 跑一遍
-        • db_meta / aihub / 外部 API：注册或更新后用 GET 回读字段
-4. 录 —— 影响可见功能、跨资源、已 push 或需接手时写更新日志到 .draftgo/changelog.md
-        格式：- [HH:MM] [操作类型] 描述（不超过 30 字）
-5. 推 —— 需要云端生效时按资源类型调对应 push 脚本（pages / nav / db_meta / aihub / external_apis / system_config / docs / doc_categories / custom_scripts / roles / users）
-6. 标 —— 有 Task 文档时把对应任务勾掉并记录证据摘要；没有 Task 文档则不补建
-```
-
-### 分段实现原则
-
-复杂或高风险代码应分段实现并验证；不要一次性写入难以检查的大块代码。
-
-1. 按功能模块或逻辑段落拆分，优先保持每段可理解、可验证
-2. 大段 HTML/CSS/JS 写入后及时做语法、结构或静态检查
-3. 批次间保持上下文连贯（闭合标签、函数结尾等不可跨批断开）
-
-**原则**：分段是为了降低错误率，不是为了机械限制行数；清晰、完整、可验证优先。
-
-### DB 操作前置门（强制）
-
-当改动涉及动态数据库（`App.get('db/...')`、`App.post('db/...')`、DB 列表页、DB 表单页）时：
-
-1. **强制先读** `.draftgo/db_meta/index.json` 中对应 type 的 schema
-2. 字段名、字段类型、是否必填 **以 schema 为准**，不凭印象写
-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) 中已有定义，执行时**全部生效**：
-
-- ❌ 境外 CDN（googleapis / jsdelivr / cdnjs / unpkg）
-- ❌ `App()` 写法（App 是对象不是函数）
-- ❌ `const App = () => window.parent?.App`（去掉箭头函数）
-- ❌ `window.location.search` 读参数（用 `window.__DG_ROUTE_CONTEXT__.query`）
-- ❌ `App?.user?.role` 判断管理员（用 `App.isAdmin` 或 `App.currentUser?.role_code`）
-- ❌ `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 的清单为方法论）
-
-[debugging-syntax.md](./debugging-syntax.md) 是症状清单，本规范补方法论：
-
-```
-取证 → 模式 → 假设 → 修复
-```
-
-1. **取证**：先看文件回读、`.draftgo/changelog.md`、`draftgo check`、API 回读或 push 输出中最贴近问题的证据。**先取证再判断**，禁止靠猜。
-2. **模式**：对照 [debugging-syntax.md](./debugging-syntax.md) 10 大致命缺陷清单。九成"页面静默失效"都在里面。
-3. **假设**：一次只验证一个假设。在关键路径加 `console.log('=== A 点 ===')` 二分定位。
-4. **修复**：修根因，不修表面。改完用与改动匹配的轻量证据确认。
-5. **3 次修不好停手**：去 `.draftgo/lessons/` 写经验记录（基座 bug 或基座局限），与用户讨论是不是架构问题。
-
----
-
-## 闭环门（无证据不许说完）
-
-### 完成铁律
-
-```
-没看到证据 → 禁止说"完成 / 通过 / 应该 OK / 搞定 / Done / Perfect"。
-```
-
-### 各资源类型的"完成证据"
-
-按任务等级选择验证强度：
-
-- 小修：验证改动点命中、无明显报错；需要云端生效时再确认对应资源已推送成功。
-- 轻功能：验证入口引用存在、主路径交互有效、关键状态不空白；需要时补 `draftgo check` 或 push 输出。
-- 标准功能：验证入口、主流程、关键四态、数据读写 / 回读、关联页面跳转；按影响选择 `draftgo check`、changelog 和 push 输出。
-- 高风险：在标准功能基础上增加人工确认、回读验证、影响范围说明和回滚 / 兜底方案。
-
-| 资源类型 | 完成证据 |
-|---------|---------|
-| 页面 HTML | 按等级验证：小修看改动点；轻功能看入口引用 + 主路径 + 关键状态；标准功能 / 高风险覆盖四态和必要的同步证据 |
-| 新增页面 / 多页面功能 | ① 页面资源创建或更新成功 ② route 与 page_id 对应 ③ 导航栏 / 首页 / 后台菜单 / 相关页面按钮至少一个入口已绑定 ④ 文件回读或 `draftgo check` 可确认入口引用 ⑤ 关联页面互跳关系清楚 ⑥ 若已推送则有 push 输出 |
-| 导航栏 | ① 文件回读确认新链接存在 ② 链接含正确 `data-page-route` ③ 若已推送则有 push 输出 |
-| 外部 API 注册 | ① `POST /api/external-apis/{id}/test` 返回 2xx ② 若已推送则有 push 输出 ③ 页面里 `App.callApi` 能调通 |
-| custom_script | ① `POST /api/scripts/{id}/execute` 真跑一次 ② 返回值符合预期 ③ 若已推送则有 push 输出 |
-| db_meta / aihub / 系统配置 | ① GET 回读字段对得上 ② 若已推送则有 push 输出 |
-| roles / users | ① 用户二次确认 ② push 输出 PASS ③ 影响范围告知用户 |
-| 文档 / 文档分类 | ① push 输出 PASS ② GET 回读字段对得上 |
-
-### 用户路径回放（轻功能 / 标准功能 / 高风险）
-
-轻功能、标准功能和高风险任务完成前，按本次范围回放用户路径链路：
-
-```
-入口出现 → 点击进入 → 页面加载 → 操作有效 → 反馈明确 → 数据可回读 → 后台可维护（如需要）→ 前台展示更新
-```
-
-如果新页面没有任何导航栏、首页模块、后台菜单或相关页面按钮引用，视为未完成。若任务明确要求“只创建未公开页面”，必须在完成声明中说明该页面暂不绑定导航的原因。
-
-### CLI 闭环体检
-
-涉及页面、导航、DB、脚本或 AIHub 的任务，可按影响运行：
-
-```bash
-draftgo check
-```
-
-- 有 `错误`：与本次改动相关时先修复，不得声明完成。
-- 有 `提醒`：结合任务判断。若是未绑定入口、疑似 mock 数据、缺少真实调用，优先补齐；若是用户明确要求隐藏页 / demo，需在 changelog、Task 或完成说明中写明原因。
-- 需要把提醒也作为失败处理时运行 `draftgo check --strict`。
-
-`draftgo check` 只做本地启发式检查；结合文件回读、静态检查、API 回读和必要的 push 输出形成证据。
-
-### 禁用措辞
-
-- "应该 / 可能 / 看起来 / 大概 / Perfect / Done / 搞定 / 好了 / OK 了"
-- 任何隐含成功但没附证据的句子
-
-### 完成声明附证据
-
-- 命令 / 操作名（哪个文件回读 / 哪个 check / 哪个 push / 哪个 API）
-- 真实输出摘要（HTTP code、关键日志行、计数）
-- 有 Task 文档时说明更新到哪些 ✅；无 Task 文档时不需要补说明
-
-**示例（正确）**：
-> T2 完成。文件回读确认导出按钮绑定 `handleExport()`；`POST /api/scripts/7/execute` 返回 200，CSV 生成 89 行；已推送时 `python draftgo_push.py pages 123` 返回 `OK pages/123`。Task 文档 T2 已 ✅。
-
-**示例（错误）**：
-> 导出按钮做好了，应该没问题，push 也跑了，你试试看。
-
-### 收尾动作（有 Task 文档时）
-
-1. 把 Task 文档 frontmatter 的 `status` 改为 `done`
-2. 填写"完成回顾"段（实际改动、偏离计划处、后续 TODO）
-3. 需要接手记录时在 changelog.md 写一条总结：`- [HH:MM] [完成] <主题>，详见 Task/<file>.md`
-4. 文件原地归档，不要移动
-
----
-
-## 与现有规则的关系
-
-| 现有规则 | 本规范如何对接 |
-|---------|---------------|
-| 根 [SKILL.md](../SKILL.md) "开发分级" | 本规范提供小修 / 轻功能 / 标准功能 / 高风险分级与执行依据 |
-| 根 [SKILL.md](../SKILL.md) "命令路由" | 增加触发：开发任务前先进本规范做任务分级 |
-| 根 [SKILL.md](../SKILL.md) "开发禁区" / "App API" / "数据库 Schema" / "API 速查" | 继续生效，执行证据依赖它们 |
-| [frontend.md](./frontend.md) | 继续生效，提供 DraftGo 前端运行时、资源、数据、路由、入口绑定和验证方法 |
-| [debugging-syntax.md](./debugging-syntax.md) | 继续生效，本规范第 3 章"调试方法论"在其之上加方法论 |
-| 迭代记录规范（根 SKILL "迭代记录规范"段） | 按影响选择复用 |
-| 错误日志规范（根 SKILL "错误日志规范"段） | 取证阶段复用 |
-| 经验记录规范（根 SKILL "经验记录规范（lessons）"段） | 第 3 章"3 次修不好停手"写入 `.draftgo/lessons/`，含基座 bug 与基座局限场景 |
-| 同步规范（根 SKILL "推送规范"段） | 需要云端生效时复用 |
-
----
-
-## 一句话总结
-
-> **先分级：小修直接定位改完给轻量证据；轻功能范围复述后直接做；标准功能轻量确认后用内部短计划执行；高风险走完整 Story / 计划 / 验证 / 人工确认。前端 UI 交给本地 Skills，DraftGo 质量靠真实链路和轻量证据。追问必带推测意图，新增页面必须绑定真实入口。**