draftgo-cli 3.0.1 → 3.0.29

package/resources/skill/quickref/app-api.md

@@ -22,9 +22,11 @@ const App = window.parent?.App;
 **响应格式**：`{ code: 200, data: <载荷>, message: "success" }`  
 **消费范式**：
 ```javascript
-const res = await App.get('pages', { page: 1, page_size: 20 });
+const res = await App.get('pages'); // 不传分页参数时全量返回
 if (res.code !== 200) { App.showError(res.message); return; }
-const items = res.data.items;  // 分页列表
+const items = res.data.items;
+
+const paged = await App.get('pages', { page: 1, page_size: 20 }); // 显式分页
 ```
 
 ## 反馈
@@ -80,18 +82,6 @@ App.setColorScheme('custom', customVarsObject);   // 自定义配色
 App.getColorScheme();                             // 获取方案详情
 ```
 
-## 外部 API
-
-```javascript
-App.listApis();                     // 列出可调用 API（含 code/name/schema）
-App.callApi('weather-now', {
-  path_params: { city: 'beijing' },
-  query_params: { unit: 'metric' },
-  // body: {...}                     // POST/PUT/PATCH 才生效
-});
-// 返回：{ status_code, headers, body, duration_ms, error }
-```
-
 ## 其他
 
 ```javascript

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

@@ -7,6 +7,7 @@ version: 1.0.0
 # DraftGo 开发流程规范
 
 > 这份规范不替换 [frontend.md](./frontend.md) 与 [debugging-syntax.md](./debugging-syntax.md)，它们仍然生效。这份规范先做任务分级，保证简单问题不被流程拖慢，复杂问题仍然有完整闭环。
+> 根 `SKILL.md` 是每次激活完整必读的核心规则源；本文件只展开执行细节。若表述冲突，以根 `SKILL.md` 为准，不叠加两套门禁。
 
 ---
 
@@ -16,7 +17,7 @@ version: 1.0.0
 小修       直接定位 → 改 → 轻量证据
 轻功能     范围复述 → 直接做 → 凭证据闭环
 标准功能   轻量确认 → 内部短计划 → 执行闭环
-高风险     完整 Story / 计划 / 验证 / 人工确认
+高风险     完整 Story / 计划 / 验证 / 回读证据
 ```
 
 例外：纯工具操作（`/draftgo init`、`/draftgo push`、`/draftgo status`、`/draftgo doctor`、`/draftgo story`、查 API、查页面元数据、读文件、回答问题）**不走开发流程**。
@@ -30,7 +31,7 @@ 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 提供运行时、资源、数据、路由、入口绑定和验证方法。
+- **前端 UI 能力**：平台壳层默认 React + Tailwind；数据库 HTML 页面默认普通 HTML + Tailwind。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用；DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法。
 
 判断一版交付是否合格：用户路径、数据和操作能真实落地，后续继续改不用重猜结构。
 
@@ -42,7 +43,7 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 - 不要把功能降级成只有前端展示的假页面；按钮、表单、搜索、筛选、分页、提交、保存、删除、发布、管理等交互默认要有真实效果。
 - 不要用写死数组、静态卡片、空点击事件、只弹 toast 的按钮伪装业务能力；演示数据只能用于加载态、空态或用户明确要求的原型/demo。
-- 如果需求涉及可维护内容或业务记录，优先判断是否可用 DraftGo 动态 DB、已有 db_meta、custom_scripts、外部 API 或 AIHub 资产完成真实数据闭环，并考虑后续维护、迭代和稳定性。
+- 如果需求涉及可维护内容或业务记录，优先判断是否可用 DraftGo 动态 DB、已有 db_meta、custom_scripts 或 AIHub 资产完成真实数据闭环，并考虑后续维护、迭代和稳定性。
 - **数据存储选型：业务数据优先用动态 DB 通用库。**
 - 若平台能力、权限、外部依赖或通用动态 DB 都无法支撑该功能，不要继续开发伪功能；向用户说明具体阻塞点和可选替代方案，确有复用价值时在 `.draftgo/lessons/` 记录“无法闭环原因 / 已验证限制 / 后续建议”。
 
@@ -50,6 +51,31 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 ---
 
+## 必经规则摘要（防漏读）
+
+以下规则来自高频、高代价的按需文档，已内联到主流程。执行开发任务时即使没有单独打开最佳实践，也必须经过这组检查：
+
+- **意图先于实现**：新页面、新模块、新功能先判断“解决谁的什么问题”，再决定页面、DB、后台、权限和入口；不要直接从用户一句“做个页面”跳到资源创建。
+- **入口先于完成**：新增页面必须绑定导航栏、首页、后台菜单或相关页面按钮至少一处；用户明确要求隐藏页/草稿页时，完成说明和记录里写清原因。
+- **导航先复用基座**：顶部导航和管理端侧边栏优先读取并复刻/改造现有内置导航资源；若现有结构不适配，再调整方案。管理端侧边栏中的系统内置路由通常保留。
+- **系统页谨慎修改**：登录、设置、系统配置、权限、用户等内置系统页非必要不动；首页不是系统页，可按业务需求改造。
+- **导航状态要完整**：导航通常同时考虑未登录 / 已登录 / 管理员，以及收起 / 展开两种状态；普通用户不显示管理后台入口，管理员可额外看到后台入口。
+- **业务优先考虑管理闭环**：涉及案例、新闻、产品、订单、预约、资料等可维护业务内容时，优先考虑前台展示 + 管理端维护 + 同一份真实数据；确认不需要管理端时写明理由即可。
+- **业务后台按域拆分**：运营日常使用的后台能力优先落到业务域专页并注册到后台侧边栏；`/admin/db` 只保留底层通用数据能力，不默认承接日常运营。
+- **首页默认是门面**：首页通常承担官网介绍、品牌展示和入口聚合；只有用户明确要求“进入即使用”时，才把首页当工作台。
+- **路径地图优先闭环**：标准功能优先明确不同角色的站点地图和访问路径：用户从哪里进入、管理员从哪里维护、数据如何回到前台。
+- **规则先于动手**：开发对应页面、导航、DB、custom_script 或 AIHub 前，优先读本任务触发的规则/spec；不要完全凭记忆写平台语法。
+- **真实数据先于静态展示**：可维护业务内容优先用动态 DB；写 DB 前先读 `.draftgo/db_meta/index.json`，不要硬编码 type、字段或权限。
+- **状态先于视觉完整**：异步页面必须有加载态、空态、错误态、成功态；初始渲染不能空白。
+- **信封先于取值**：调用 DraftGo API 时先判断 `res.code !== 200`，再从 `res.data` 取载荷；列表/后台/大数据场景显式传 `page` + `page_size`。
+- **平台能力先于绕路**：优先动态 DB → custom_script；第三方请求在服务端通过 `ctx.HTTP` 发起，不要在页面里硬编码 API Key、Bearer、业务数据或伪交互。
+- **主题适配先于硬编码颜色**：默认用 `var(--dg-*)` 语义 token；自主配色必须同时考虑浅色与深色。
+- **证据先于完成声明**：没做文件回读、结构检查、API 回读、`draftgo check` 或与任务影响匹配的运行证据，不允许说完成。前端浏览器证据按影响选择，不是所有页面的固定门禁。
+
+若任务触发更具体规则，再读对应文件；这组摘要是主流程硬门，不依赖额外阅读。
+
+---
+
 ## 轻量任务识别与用户意图翻译
 
 不要把流程做成固定填表。开发前先用 AI 自身判断力做一次轻量识别：这次是小修、轻功能、标准功能，还是高风险系统改动。识别结果用于决定规划深度，不要求每次都输出模板。
@@ -63,13 +89,29 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 进入陌生项目、资源关系不清、多页面任务或用户描述较模糊时，先运行 `draftgo map` 快速获得资源地图；目标文件明确的小修和局部改动可以跳过。`draftgo map --output json` 可用于机器读取，不替代具体文件阅读。
 
+### 新功能意图锚定
+
+当任务是新增页面、新模块、新后台能力或新业务流程时，先给出一句意图判断：
+
+```
+意图：给 <角色> 解决 <问题>，通过 <核心路径> 完成。
+```
+
+- 能从 Story、现有导航、页面命名、业务对象和用户措辞推断时，直接采用并记录。
+- 推断会明显改变页面数量、数据结构、后台能力或权限时，在轻量确认里前置追问。
+- 普通页面/轻功能不引入完整 PRD；只保留一句可执行的功能意图，作为后续设计和验收锚点。
+- 用户明确要“新系统 / 新板块 / 新模块 / 完整业务”时，进入下方“小 PRD 门”，把意图扩展为可执行页面清单和功能清单。
+
 默认策略：
 
 - 用户说“修改 / 调整 / 优化某个已存在页面” → 默认按单资源改动处理；范围清晰则小修，影响主流程则轻功能或标准功能。
-- 用户说“做 / 新建 / 增加一个页面” → 默认按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定，并优先考虑真实落地闭环、高可用。只有用户明确说“静态页 / 纯页面 / 静态稿 / demo / mock / 假数据 / 伪功能 / 先做效果”时，才允许按静态页面处理。
+- 用户说“做 / 新建 / 增加一个页面” → 通常按**完整页面功能**处理：页面可访问、交互有效、状态完整、必要数据真实读写、入口已绑定，并优先考虑真实落地闭环、高可用。只有用户明确说“静态页 / 纯页面 / 静态稿 / demo / mock / 假数据 / 伪功能 / 先做效果”时，才允许按静态页面处理。
 - 用户说“做一个功能 / 模块 / 系统能力” → 默认按功能闭环处理，不能自动降级为单个展示页或前端假数据。
-- 用户说“管理 / 维护 / 发布 / 审核 / 上下架” → 默认需要后台管理能力和真实数据闭环。
-- 用户说“官网 / 官方 / 平台 / 系统” → 不要做孤立页面；至少考虑导航入口、访问路径和完整用户路径。
+- 用户说“做一个新系统 / 新板块 / 新模块 / 完整业务” → 通常先产出一份轻量 PRD 到 `.draftgo/Task/`，清点页面、功能、数据、管理端和入口，再开始实现。
+- 用户说“管理 / 维护 / 发布 / 审核 / 上下架” → 通常需要后台管理能力和真实数据闭环。
+- 用户说“案例 / 新闻 / 产品 / 订单 / 预约 / 招聘 / 资料下载”等业务内容 → 通常不只是单页面，要同时判断前台展示、后台维护、数据结构和权限。
+- 用户说“官网 / 官方 / 平台 / 系统” → 通常不要做孤立页面；至少考虑导航入口、访问路径和完整用户路径。
+- 用户说“新导航 / 重新做导航栏” → 通常先复制一份现有导航再改，不直接破坏内置导航；同时要考虑登录态、管理员态和收起/展开。
 
 只有当不确定点会明显改变页面数量、数据结构、后台能力、权限或风险时，才向用户确认。确认最多 1-3 个问题，并给出推荐默认值；其余细节由 AI 自主推断，并按任务等级记录到范围复述、内部短计划或 Task 中。
 
@@ -91,6 +133,56 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 ---
 
+### 新系统 / 新板块：小 PRD 门
+
+当用户要求开发一个“新的系统”“新的板块”“新的模块”“完整业务能力”，或需求明显包含多页面、多角色、多数据对象时，默认按标准功能或高风险处理，并先在 `.draftgo/Task/` 创建一份轻量 PRD。用户明确说“先做一个静态入口 / 只要单页效果 / 不要规划”时可降级，但要在完成说明里写清。
+
+小 PRD 的目标不是写长文档，而是让开发闭环可执行。内容应包括：
+
+```markdown
+# <系统/板块名> PRD
+
+## 1. 需求理解
+- 用户原话：
+- AI 意图推测：给 <角色> 解决 <问题>，通过 <核心路径> 完成
+- 范围边界：本次做 / 暂不做
+
+## 2. 角色与路径地图
+| 角色 | 入口 | 核心动作 | 结果反馈 |
+|---|---|---|---|
+| 前台用户 | 导航/首页/按钮 | 浏览/搜索/提交 | 看到结果/收到反馈 |
+| 管理员/运营 | 管理端菜单 | 新增/编辑/发布/审核 | 前台同步更新 |
+
+## 3. 页面清单
+| 页面 | 路由 | 面向角色 | 主要功能 | 入口绑定 | 数据来源 |
+|---|---|---|---|---|---|
+| 前台列表页 | /xxx | 用户 | 浏览/搜索/筛选 | 顶部导航/首页 | db:xxx |
+| 前台详情页 | /xxx/detail | 用户 | 查看详情/提交动作 | 列表页 | db:xxx |
+| 管理列表页 | /admin/xxx | 管理员 | 查询/新增/编辑/删除/发布 | 管理侧边栏 | db:xxx |
+
+## 4. 功能清单
+| 功能 | 页面/资源 | 真实行为 | 状态反馈 | 验收证据 |
+|---|---|---|---|---|
+| 搜索筛选 | 前台列表/管理列表 | 调真实 DB/API | 加载/空/错误/成功 | 文件回读 + API/check |
+
+## 5. 数据与权限
+- 动态 DB type：
+- 字段草案：
+- 权限/可见性：
+- 是否需要 custom_script / AIHub：
+
+## 6. 实施任务
+- [ ] T1. 创建/更新 DB meta
+- [ ] T2. 开发前台页面
+- [ ] T3. 开发管理端页面
+- [ ] T4. 更新导航/入口
+- [ ] T5. 验证、push、changelog
+```
+
+生成 PRD 后，通常不要停在文档。除非用户要求先审 PRD，否则继续把 PRD 拆成执行任务并开始开发。若 PRD 中存在会明显改变数据结构、权限、安全或页面数量的关键分叉，再做一次轻量确认。
+
+---
+
 ## 任务分级（先判级，再执行）
 
 ### 小修
@@ -108,7 +200,7 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 1. 定位：读目标 index / 文件，确认 resource id 与文件路径
 2. 改：只做最小必要改动
 3. 证据：用与改动匹配的轻量方式确认命中（文件回读 / 语法检查 / diff / 必要的本地检查）
-4. 同步：需要云端生效或用户要求时再 push
+4. 交付：默认保留本地结果；用户明确要求 push/同步/部署，或必须上云才能完成真实闭环时再推送
 5. 记录：影响可见功能、已 push 或有接手价值时写 changelog
 ```
 
@@ -123,15 +215,15 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 典型场景：
 - 给现有页面新增一个筛选、提交、跳转、下载、状态反馈等小能力
 - 新增一个简单可用页面，并绑定一个入口
-- 单页面接入一份已有 DB / 外部 API / AIHub 能力
+- 单页面接入一份已有 DB / 自定义服务 / AIHub 能力
 - 补齐一个局部用户路径，但不涉及权限、账号、生产脚本或复杂数据结构
 
 流程：
 ```
 1. 范围复述：一句话说明要做什么、入口在哪里、如何验证
 2. 直接做：读目标资源，按最小闭环实现
-3. 主路径验证：入口可达、核心交互有效、关键状态不空白
-4. 证据闭环：按影响选择 check / push / changelog
+3. 推送前只做本地静态/结构/资源检查
+4. 证据闭环：按影响补 check / changelog；用户明确要求云端生效时再 push
 ```
 
 轻功能不强制创建 Task 文档，不强制 depends/resource_lock/wave，也不启用并行。若执行中发现需要多个页面协作、后台管理、复杂权限或资源冲突，升级为「标准功能」。
@@ -142,20 +234,21 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 典型场景：
 - 新建页面 / 改造页面主流程
-- 页面联动 DB / 外部 API / AIHub
+- 页面联动 DB / 自定义服务 / AIHub
 - 新增导航入口并配套页面
 - 新增普通文档、普通 db_meta、非敏感配置
+- 新系统 / 新板块 / 新模块的轻量 PRD + 页面与功能清单 + 多资源开发
 
 流程：
 ```
 1. 若 .draftgo/story.yaml 存在，静默加载；不存在时不阻塞开发，完成后提醒补 Story
 2. 轻量确认：意图翻译 + 必要追问 + 范围复述
-3. 内部短计划：列清资源、入口、数据、关键交互和证据形式；跨资源、多页面协作、并行或高风险时再创建 Task
+3. 内部短计划：列清资源、入口、数据、关键交互和证据形式；新系统/新板块或跨资源、多页面协作、并行、高风险时创建 Task，并写入轻量 PRD
 4. 执行门：按短计划逐项实现
-5. 闭环门：证据 + 按影响选择 changelog / check / push；有 Task 时同步标记
+5. 闭环门：证据 + 按影响选择 changelog / check；需要云端生效时显式 push；有 Task 时同步标记
 ```
 
-标准功能任务最低规划要求：写清楚用户路径链路、页面入口/导航绑定、前台与后台是否需要同一份数据、哪些交互必须真实有效。不要把“页面看起来存在”当成“功能完成”。
+标准功能任务最低规划要求：写清楚用户路径链路、页面入口/导航绑定、前台与后台是否需要同一份数据、哪些交互必须真实有效。业务模块通常优先列清关键角色路径（前台用户、管理员/运营，必要时再补审核员/客服），避免只做一个入口不闭环。不要把“页面看起来存在”当成“功能完成”。
 
 ### 高风险
 
@@ -172,9 +265,9 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 ```
 1. Story 门：无 .draftgo/story.yaml 必须先构建；有则静默加载并做冲突检测
 2. 完整确认：挖透关键风险、边界和验收，复述确认后才动手
-3. 计划门：Task 文档 + 风险点 + 回滚/验证方案 + 人工确认点
-4. 执行门：轻量闭环执行；涉及 roles/users/custom_scripts 等按 push skill 要求二次确认
-5. 闭环门：真实验证证据 + push 输出 + 回读结果 + 影响范围说明
+3. 计划门：Task 文档 + 风险点 + 回滚/验证方案
+4. 执行门：轻量闭环执行；涉及 roles/users/custom_scripts 等资源时先完成本地结构和影响检查，需要云端生效时再按对应脚本推送
+5. 闭环门：真实验证证据 + 回读结果 + 影响范围说明；需要云端生效时补 push 输出
 ```
 
 ---
@@ -215,7 +308,7 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 
 - 高风险任务中 Story 门不可跳过、不可拖延
 - 标准功能任务允许先开发后提醒补 Story；小修和轻功能不需要 Story
-- Story 加载失败（yaml 格式损坏）时提示用户修复，不可忽略继续开发
+- Story 加载失败（yaml 格式损坏）时，尝试自动修复格式错误后继续；无法自动修复时提示用户并继续开发
 
 ---
 
@@ -231,21 +324,23 @@ DraftGo-CLI 的目标不是只把页面写出来，而是让 AI 基于基座快
 > 先根据用户提示词、现有项目结构和用户路径链路推断合理实现范围；只有关键分叉会明显改变工作量或系统行为时才追问。
 
 必须主动推断：
+- 功能意图：解决谁的什么问题，是否面向前台用户、后台运营或内部人员
 - 这是改现有页面、新增单页面、新增多页面，还是完整功能模块
-- 用户从哪里进入：官网首页、导航栏、列表入口、按钮、后台菜单
+- 用户从哪里进入：官网首页、导航栏、列表入口、按钮、后台菜单；若是导航改造，还要区分未登录、已登录、管理员三种可见性
 - 新页面是否要绑定到导航栏 / 首页入口 / 后台菜单 / 相关页面按钮
 - 是否需要前台展示、后台维护、真实数据读写、搜索筛选、详情页、表单提交
 - 是否存在权限、状态流转、上下架、审核等隐含操作
 
 确认规则：
 - 不要为了填满维度而追问；能从上下文合理推断的，直接采用并记录。
-- 只问会改变页面数量、数据结构、权限、后台能力、外部 API、生产风险的问题。
+- 只问会改变页面数量、数据结构、权限、后台能力、生产风险的问题。
 - 一次最多 1-3 个问题，必须带推荐默认值。
 - 用户说“你看着办 / 按你理解来 / 直接做”时，按推荐默认值继续，不要反复卡住。
 
 轻量确认写法：
 ```
 我理解这是：<页面 / 多页面 / 功能模块>。
+意图是：给 <角色> 解决 <问题>。
 我会按 <推荐范围> 做：<前台入口 + 页面 + 数据 / 后台 / 绑定 / 验证摘要>。
 
 [如有关键分叉]有一个点会影响范围：
@@ -275,6 +370,7 @@ C. <更完整方案>
 ```
 我理解你要：
 - 目标：...
+- 意图：解决什么问题，给谁用
 - 范围：在 ... 做 ...
 - 用户路径：从 ... 进入 → ... → ... → 得到 ...
 - 页面 / 入口绑定：...
@@ -338,6 +434,7 @@ related_changelog: YYYY-MM-DD
 > 来自轻量确认 / 高风险确认的复述结果。**这段不再修改**。
 
 - 目标：...
+- 意图：解决什么问题，给谁用（一句话）
 - 范围：...
 - 用户路径：用户从 ... 进入 → 点击 ... → 完成 ... → 获得 ...
 - 页面 / 入口绑定：新增或修改的页面如何出现在导航栏、首页、后台菜单或相关页面按钮中
@@ -354,7 +451,7 @@ related_changelog: YYYY-MM-DD
 **涉及资源**：
 - 页面：`pages/<file>.html`（page_id=xx）
 - 导航：`navigations/<file>.html`（nav_id=xx）
-- 外部 API / db_meta / aihub / custom_scripts：...
+- db_meta / aihub / custom_scripts：...
 
 **链路流**：入口（官网 / 导航 / 后台菜单）→ 页面 → 操作 → 数据读写 → 反馈 → 后台维护 → 前台展示
 
@@ -377,10 +474,10 @@ related_changelog: YYYY-MM-DD
   - 步骤：
     1. 读取当前文件，定位 X
     2. 在 Y 位置插入 Z
-    3. 验证：文件回读 / draftgo check / 与改动匹配的轻量证据
-    4. 需要云端生效时调 push 脚本：`python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>`
+    3. 推送前只做本地静态/结构/资源检查：文件回读 / draftgo check
+    4. 用户要求同步/部署或必须云端生效时，调 push 脚本：`python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>`
     5. 需要接手记录时写更新日志
-  - 验证证据：文件回读 / check / push 输出（如已推送）
+  - 验证证据：文件回读 / check / 必要的运行证据；需要云端生效时补 push 输出
 
 - [ ] T2. ... ⬜
 
@@ -434,7 +531,7 @@ related_changelog: YYYY-MM-DD
 ### 计划门红线
 
 - 计划禁止占位符：TBD / TODO / "类似 T2" / "做适当处理" / "加错误处理"。
-- 每个任务必须给：精确文件路径、操作类型、可执行步骤、验证证据形式。
+- 每个任务必须给：精确文件路径、操作类型、可执行步骤、本地检查证据形式。
 - 多任务 / 多代理 / 多资源冲突时必须给：`depends` + `resource_lock` + `wave` 三个字段；单人串行小计划不强制。
 - 新增页面必须有绑定任务或明确说明为什么不需要入口；默认应绑定到导航栏、首页、后台菜单或相关页面按钮之一。
 - 计划写完跑一次自审：**需求纪要每一条、用户路径每一步、页面绑定每一处能不能指到某个任务？** 不能就补任务。
@@ -444,12 +541,12 @@ related_changelog: YYYY-MM-DD
 
 ## 执行节奏（轻量闭环）
 
-DraftGo 主要场景是**改 HTML 页面、改导航、调 App API、写 custom_script、注册外部 API**。执行时保持小步、可理解、有证据：
+DraftGo 主要场景是**改 HTML 页面、改导航、调 App API、写 custom_script**。执行时保持小步、可理解、有证据：
 
 ```
 Small    小步实现，一次只动清楚的一件事
 Evidence 用文件回读 / check / 与改动匹配的轻量证据确认
-Record   按影响选择 changelog / Task 标记 / push
+Record   按影响选择 changelog / Task 标记，需要云端生效时显式 push
 ```
 
 ### 并行分发（Wave 模式）
@@ -459,7 +556,7 @@ Record   按影响选择 changelog / Task 标记 / push
 1. **分发**：为每个 Wave 1 任务生成子代理，携带上下文包（task 定义 + 当前文件 + 禁区摘要）
 2. **子代理执行**：每个子代理独立完成小步实现和证据确认，产出修改文件 + 验证报告；需要接手记录时再产出 changelog 条目
 3. **收集**：主代理收集所有子代理产出，写入文件系统
-4. **批量推送**：需要云端生效时运行 `python {{SKILL_SCRIPTS}}/draftgo_push.py --batch <type1> <id1>,<id2> <type2> <id3>`
+4. **批量推送**：用户要求同步/部署或任务必须云端生效时，验证通过后运行 `python {{SKILL_SCRIPTS}}/draftgo_push.py --batch <type1> <id1>,<id2> <type2> <id3>`
 5. **Wave 2**：依赖已完成的任务可以开始，重复上述流程
 6. **闭环**：主代理统一汇总证据；有 Task 文档时再更新标记
 
@@ -476,13 +573,13 @@ Record   按影响选择 changelog / Task 标记 / push
 2. 改 —— 做最小必要改动，不顺手改无关代码
 3. 证 —— 用与改动匹配的轻量证据确认：
         • 页面类：文件回读、入口引用、状态结构、关键交互代码路径
-        • API 类：用 App.callApi / Python urllib / 管理端测试端点真实跑一次
+        • API 类：用 `fetch('/api/x/<slug>/...')` / Python urllib / 服务 route 端点真实跑一次
                   （Windows 环境下 curl 对中文/特殊字符编码易出错，建议优先用 Python urllib/requests）
         • custom_script：用 POST /api/scripts/{id}/execute 跑一遍
-        • db_meta / aihub / 外部 API：注册或更新后用 GET 回读字段
+        • db_meta / aihub：注册或更新后用 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）
+5. 交付 —— 默认完成本地静态/结构/资源检查后，运行 `draftgo auto-push [type] [id...]`。该命令只在 `.draftgo/config.json` 的 `auto_push` 严格为 `true` 时执行 `check → push`；开关关闭或未设置时，返回“已验证、未推送”，不修改云端。用户明确要求 push/同步/部署，或资源必须上云才能完成真实闭环时，优先运行 `draftgo deploy`（自动执行 check → push，check 不通过则终止）；预演用 `draftgo deploy --delivery preview`，只做本地门禁用 `draftgo deploy --delivery local`。若只需推特定资源类型，再按资源类型调对应 push 脚本。
 6. 标 —— 有 Task 文档时把对应任务勾掉并记录证据摘要；没有 Task 文档则不补建
 ```
 
@@ -509,12 +606,15 @@ Record   按影响选择 changelog / Task 标记 / push
 
 ### custom_script 契约前置门（强制）
 
-当前端要对接某个 custom_script 的 route 端点（`App.callApi`、`fetch('/api/x/<slug>/...')`、DB 列表/表单页依赖某脚本的读写接口）时，**云端正在运行的脚本才是唯一契约真相，本地 `code_file` 不是**：
+当前端要对接某个 custom_script 的 route 端点（`fetch('/api/x/<slug>/...')`、DB 列表/表单页依赖某脚本的读写接口）时，优先以云端正在运行的脚本为准，本地 `code_file` 可能落后于云端：
 
 1. **对接前强制确认"本地 = 云端"**：先 `python {{SKILL_SCRIPTS}}/draftgo_pull.py custom_scripts <id>` 拉云端运行版，或直接探测关键端点（如目标端点返回 404 即说明云端没有该 route）。两者一致才可按本地契约写前端。
-2. **本地领先时先推后接**：若本地脚本已演进但因 custom_scripts 推送的二次确认被跳过而未上云，必须先完成推送（push skill 的二次确认流程），不得对着"未上云的本地契约"写前端。
+2. **本地领先时先推后接**：若本地脚本已演进但尚未上云，必须先完成推送，不得对着"未上云的本地契约"写前端。
 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 参数，永远走异常分支，是死代码。
+4. **Register 是唯一触发来源**：同一 Go custom service 可用 `app.Route` / `app.On` / `app.Schedule` 声明多个触发器；旧 `triggers` 元数据不参与注册，CLI 不创建也不推送。
+5. **route 端点设计约束**：Go custom service 的 Route 输入位于 `draftgo.Input`（`body`、`query_params`、`headers`、`method`、`path_params`）；`path_params` 只包含 catch-all 的 `{slug, path}`，不会从 route 字符串中解析 `{id}`/`{uid}`。普通身份用 `draftgo.Auth.CurrentUser()`；需要 id 的写操作通过 query/body 传入，不要写 `app.Route("DELETE", "/xxx/{id}", handler)`。
+6. **管理员 SDK 调用契约**：管理员服务要访问管理员资源时，代码逐次显式调用 `draftgo.Admin.*`，例如 `draftgo.Admin.DB.Query(...)`；不添加 `admin_access` 配置，不传 SAT。普通 `draftgo.DB` 调用不自动提权。推送后必须回读一次执行详情，确认 `Admin SDK call` 审计存在。
+6. **权限分层**：`scripts:*` 只控制谁能管理服务；Route 的 `permission` / `route_security` 仍单独控制谁能调用。管理角色不能据此绕过调用权限，也不要因调用范围受限就把代码编辑权授给不可信角色。
 
 违反后果：本地脚本 ≠ 云端运行版 → 前端对错契约 → 列表恒空 / 写读两套存储，排查极隐蔽。
 
@@ -529,12 +629,10 @@ Record   按影响选择 changelog / Task 标记 / push
 - ❌ `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-*` 标签，或补齐缺失映射）
+- ❌ 只按当前主题硬编码颜色（优先用系统 `var(--dg-*)` token；自主配色必须兼容浅色与深色）
 - ❌ `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）
+- ❌ Go custom service 里写 `app.Route("DELETE", "/x/{id}", handler)` 并期待 `ctx.Input["path_params"]["id"]`（`path_params` 只有 `slug/path`，ID 应走 query/body）
 - ❌ 对着未上云的本地 custom_script 契约写前端（先 pull/探测确认本地=云端，见上「custom_script 契约前置门」）
 
 ### 调试方法论（升级 debugging-syntax.md 的清单为方法论）
@@ -549,7 +647,7 @@ Record   按影响选择 changelog / Task 标记 / push
 2. **模式**：对照 [debugging-syntax.md](./debugging-syntax.md) 10 大致命缺陷清单。九成"页面静默失效"都在里面。
 3. **假设**：一次只验证一个假设。在关键路径加 `console.log('=== A 点 ===')` 二分定位。
 4. **修复**：修根因，不修表面。改完用与改动匹配的轻量证据确认。
-5. **3 次修不好停手**：去 `.draftgo/lessons/` 写经验记录（基座 bug 或基座局限），与用户讨论是不是架构问题。
+5. **修复卡住时**：判断是否为基座问题——**基座 bug / 基座局限**：写入 `.draftgo/lessons/`，用最小临时方案绕过，与用户说明；**非基座问题**：继续尝试修复，确实无法修复时再写经验记录并说明阻塞点。
 
 ---
 
@@ -563,23 +661,22 @@ Record   按影响选择 changelog / Task 标记 / push
 
 ### 各资源类型的"完成证据"
 
-按任务等级选择验证强度：
+先做本地静态/结构/资源检查；是否增加浏览器、API 或云端证据由改动影响决定。
 
-- 小修：验证改动点命中、无明显报错；需要云端生效时再确认对应资源已推送成功。
-- 轻功能：验证入口引用存在、主路径交互有效、关键状态不空白；需要时补 `draftgo check` 或 push 输出。
-- 标准功能：验证入口、主流程、关键四态、数据读写 / 回读、关联页面跳转；按影响选择 `draftgo check`、changelog 和 push 输出。
-- 高风险：在标准功能基础上增加人工确认、回读验证、影响范围说明和回滚 / 兜底方案。
+- 小修：文件回读确认改动点命中；需要云端生效时再补 push 输出。
+- 轻功能：文件回读、入口引用检查、`draftgo check`；需要云端生效时补 push 输出。
+- 标准功能：文件回读、入口/资源结构检查、`draftgo check`、必要的数据回读；按任务要求补 push 输出和 changelog。
+- 高风险：在标准功能基础上增加影响范围说明、回读验证和回滚 / 兜底方案。
 
 | 资源类型 | 完成证据 |
 |---------|---------|
-| 页面 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 回读字段对得上 |
+| 页面 HTML | 文件回读、入口引用、`draftgo check`；涉及真实运行或布局时再补 `draftgo verify-ui`，需要云端生效时补 push 输出 |
+| 新增页面 / 多页面功能 | ① 页面资源创建或更新成功 ② route 与 page_id 对应 ③ 导航栏 / 首页 / 后台菜单 / 相关页面按钮至少一个入口已绑定 ④ 文件回读或 `draftgo check` 可确认入口引用 ⑤ 关联页面互跳关系清楚 ⑥ 按交付要求决定是否 push |
+| 导航栏 | ① 文件回读确认新链接存在 ② 链接含正确 `data-page-route` ③ 按交付要求决定是否 push |
+| custom_script | ① 在可用环境执行目标 route/execute ② 返回值符合预期 ③ 使用 `draftgo.Admin.*` 时回读执行详情并确认 `Admin SDK call` 审计 ④ 需要云端生效时补 push 输出 |
+| db_meta / aihub / 系统配置 | ① 本地结构或 GET 回读字段对得上 ② 需要云端生效时补 push 输出 |
+| roles / users | ① 影响范围告知用户 ② 用户要求同步时补 push 输出 |
+| 文档 / 文档分类 | ① 文件与元数据回读字段对得上 ② 用户要求同步时补 push 输出 |
 
 ### 用户路径回放（轻功能 / 标准功能 / 高风险）
 
@@ -603,7 +700,7 @@ draftgo check
 - 有 `提醒`：结合任务判断。若是未绑定入口、疑似 mock 数据、缺少真实调用，优先补齐；若是用户明确要求隐藏页 / demo，需在 changelog、Task 或完成说明中写明原因。
 - 需要把提醒也作为失败处理时运行 `draftgo check --strict`。
 
-`draftgo check` 只做本地启发式检查；结合文件回读、静态检查、API 回读和必要的 push 输出形成证据。
+`draftgo check` 只做本地启发式检查；结合文件回读、静态检查和必要的 API/运行证据形成证据。浏览器验证优先用 `draftgo verify-ui`，不要默认使用 computer use；截图默认只在失败时生成。
 
 ### 禁用措辞
 
@@ -617,7 +714,7 @@ draftgo check
 - 有 Task 文档时说明更新到哪些 ✅；无 Task 文档时不需要补说明
 
 **示例（正确）**：
-> T2 完成。文件回读确认导出按钮绑定 `handleExport()`；`POST /api/scripts/7/execute` 返回 200，CSV 生成 89 行；已推送时 `python draftgo_push.py pages 123` 返回 `OK pages/123`。Task 文档 T2 已 ✅。
+> T2 完成。文件回读确认导出按钮绑定 `handleExport()`；`POST /api/scripts/7/execute` 返回 200，CSV 生成 89 行；`python draftgo_push.py pages 123` 返回 `OK pages/123`。Task 文档 T2 已 ✅。
 
 **示例（错误）**：
 > 导出按钮做好了，应该没问题，push 也跑了，你试试看。
@@ -642,11 +739,11 @@ draftgo check
 | [debugging-syntax.md](./debugging-syntax.md) | 继续生效，本规范第 3 章"调试方法论"在其之上加方法论 |
 | 迭代记录规范（根 SKILL "迭代记录规范"段） | 按影响选择复用 |
 | 错误日志规范（根 SKILL "错误日志规范"段） | 取证阶段复用 |
-| 经验记录规范（根 SKILL "经验记录规范（lessons）"段） | 第 3 章"3 次修不好停手"写入 `.draftgo/lessons/`，含基座 bug 与基座局限场景 |
-| 同步规范（根 SKILL "推送规范"段） | 需要云端生效时复用 |
+| 经验记录规范（根 SKILL "经验记录规范（lessons）"段） | 第 3 章"修复卡住时"逻辑写入 `.draftgo/lessons/`，含基座 bug 与基座局限场景 |
+| 同步规范（根 SKILL "推送规范"段） | 开发任务收尾默认复用 |
 
 ---
 
 ## 一句话总结
 
-> **先分级：小修直接定位改完给轻量证据；轻功能范围复述后直接做；标准功能轻量确认后用内部短计划执行；高风险走完整 Story / 计划 / 验证 / 人工确认。前端 UI 交给本地 Skills，DraftGo 质量靠真实链路和轻量证据。追问必带推测意图，新增页面必须绑定真实入口。**
+> **先分级：小修直接定位改完给轻量证据；轻功能范围复述后直接做；标准功能轻量确认后用内部短计划执行；高风险走完整 Story / 计划 / 验证 / 回读证据。前端 UI 交给本地 Skills，DraftGo 质量靠真实链路和轻量证据。追问必带推测意图，新增页面必须绑定真实入口。**