draftgo-cli 3.0.0 → 3.0.29

package/resources/skill/practices/best-practices.md

@@ -6,10 +6,11 @@ read_when: 开发过程中做决策时 · Code Review 时
 
 ## 服务设计
 
-- **优先用平台能力**：动态 DB → 自定义服务 → 外部 API，按复杂度递进，不要绕过平台直接硬编码
+- **优先用平台能力**：动态 DB → 自定义服务，按复杂度递进，不要绕过平台直接硬编码
 - **db_meta 先于代码**：操作动态 DB 前先读 `.draftgo/db_meta/index.json`，不要硬编码 type 值
 - **权限跟数据一起设计**：创建 db_meta 时同时设计 `permission` 字段，不要事后补
 - **schema_validation 开启**：动态 DB 数据写入时建议开启 `schema_validation: 1`，及早发现数据问题
+- **关联一致性放在 schema**：A 被 B 引用时，优先在 B 的真实引用字段配置 `ref.onDelete`，不要让前端连续请求多个删除接口来模拟级联
 
 ## 页面开发
 
@@ -17,25 +18,43 @@ read_when: 开发过程中做决策时 · Code Review 时
 - **四态必须都有**：加载态（dg-skeleton）/ 空态（明确文案 + 操作入口）/ 错误态（Toast + 重试）/ 成功态
 - **初始渲染不能空白**：先展示骨架屏，再异步填数据；不能因为网络延迟导致整页白屏
 - **新页面必须绑定入口**：导航栏 / 首页模块 / 后台菜单 / 相关页面按钮至少一个；只建文件不绑入口不算完成
+- **导航先复刻再改**：顶部导航和管理端侧边栏通常先基于现有内置导航资源复制/改造，再补业务路由和视觉优化
+- **导航状态要完整**：导航通常同时考虑未登录、已登录、管理员可见性，以及收起/展开状态；普通用户不显示管理后台入口
+- **业务先判断管理端**：案例、新闻、产品、订单、预约、资料等内容优先判断前台展示、管理端维护和同一份真实数据
+- **业务后台按域拆分**：运营日常使用的后台能力优先做业务域管理页并注册到后台侧边栏；`/admin/db` 保留给底层通用数据能力
+- **首页先定定位**：首页通常先按官网介绍、品牌门面和入口聚合设计，除非用户明确要“进入即使用”
+- **先补关键角色路径**：优先明确前台用户和管理员/运营从哪里进入、在哪里操作、怎么回到结果页；简单改动不必机械画全量地图
+- **新系统先落轻量 PRD**：新系统/新板块/新模块先在 `.draftgo/Task/` 写清页面清单、功能清单、数据、入口和验收证据，再开始实现
+- **功能先对齐意图**：新功能先确认“解决谁的什么问题”，再谈页面数、数据源和后台；不要直接跳到实现细节
+- **体验优先本地化**：弹窗/抽屉尽量去滚动条，涉及下拉选项样式时优先做自定义弹层菜单，避免系统默认下拉样式；动效可合理使用本地 GSAP，但不要抢可用性
+- **FilterPill + Popover 筛选胶囊**：列表页筛选推荐这个组合——胶囊按钮触发浮层，浮层内放筛选表单/选项；不阻塞操作，视觉轻量，适合多条件筛选；参考 admin-pages.html 的 `.filter-popover-wrapper` + `.filter-popover` 实现（胶囊按钮 + 独立浮层）
+- **FilterPill + Popove 展开式筛选行**：另一种常见模式——工具栏右侧放"展开筛选"按钮，点击后筛选条件直接展开在工具栏下方；适合筛选项少且固定场景；参考 admin-notices.html 的 `filterOpen && h('div', { className: 'pg-filter-row' }, ...)` 实现（Antd Select 下拉，展开行内横排）
 
 ## API 调用
 
 - **统一信封消费**：始终检查 `res.code !== 200`，再从 `res.data` 取载荷；不要假设 200
-- **分页参数显式传**：列表请求必须传 `page` + `page_size`，超 10000 条后端拒绝
-- **外部 API 用 App.callApi**：不要在页面里写 API Key / Bearer，认证由管理端注册、后端注入
+- **按场景选择分页**：列表请求不传 `page` / `page_size` 会全量返回且无上限；页面表格、管理后台和大数据量场景应显式传 `page` + `page_size`
+- **第三方调用走自定义服务**：不要在页面里写 API Key / Bearer；在 Go 服务端用 `ctx.HTTP` 请求并通过 route 暴露受控端点
 
 ## 资源路径
 
-- **静态资源用本地路径**：`/assets/tailwindcss.js`、`/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`
+- **静态资源用本地路径**：`/assets/tailwindcss.js`、`/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`、`/assets/vendor/html2canvas/html2canvas.min.js`
 - **图标用内置库**：先查 `/assets/icons/manifest.json`，已有的直接用，不要引外部图标
 
 ## 主题适配
 
-- **颜色全用语义 token**：`var(--dg-accent)`、`var(--dg-bg-surface)` 等，避免亮暗切换时颜色失效
-- **品牌色 / 图表色例外**：需要同时提供 `[data-theme="dark"]` 选择器覆盖，且确保对比度达 WCAG AA
+- **优先系统主题配色**：默认使用 `var(--dg-accent)`、`var(--dg-bg-surface)` 等语义 token，继承当前浅色 / 深色主题
+- **自主配色要双模式**：页面不搭配、品牌要求、用户明确指定或图表需要时可自定义，但必须提供浅色与深色两套变量或覆盖
+- **品牌色 / 图表色例外**：仍要确保两种模式下对比度达 WCAG AA，避免亮暗切换后颜色失效
 
 ## 推送收尾
 
 - **修改页面同时推导航**：如果页面新增了导航入口，导航 HTML 也要一起 push
 - **changelog 按影响写**：影响可见功能、跨资源、已发布时写 `.draftgo/changelog.md`，纯小修可跳过
 - **用 draftgo check 验收**：涉及路由、入口绑定的改动，用 `draftgo check` 确认没有悬空入口
+
+## 规则分层
+
+- **高频高代价规则**：优先内联到必经路径，不要只放在按需读文件里
+- **低频明确触发规则**：保留外链，但必须写出触发条件
+- **低频低代价规则**：保持外链即可

package/resources/skill/practices/dev-declaration.md

@@ -14,6 +14,7 @@ read_when: 开始任何标准功能/高风险开发任务之前 · 用户意图
 
 - 标准功能或高风险任务（按 `dev-workflow.md` 分级）
 - 涉及 2 个以上资源（页面 + 导航、多页面联动、DB + 页面等）
+- 新系统 / 新板块 / 新模块 / 完整业务能力，需要先产出轻量 PRD 与页面/功能清单
 - 用户描述包含模糊词（「做一个...」「帮我整一个...」「类似...的功能」）
 - 实现路径有分叉点（多种技术方案可选）
 - 用户意图与现有 Story 存在潜在冲突
@@ -31,6 +32,8 @@ read_when: 开始任何标准功能/高风险开发任务之前 · 用户意图
 | 功能目标（做什么） | 技术实现路径 | 数据来源（DB类型/字段） |
 | 目标页面/路由 | 权限配置 | 是否需要管理侧页面 |
 | 核心交互流程 | UI 风格偏好 | 与已有功能的关系 |
+| 入口位置/导航归属 | 角色路径地图 | 是否必须保留系统内置入口 |
+| 导航状态 | 登录态 / 管理员态 / 收起展开 | 是否需要区分未登录 / 已登录 / 管理员 |
 
 信息充分 → 直接输出声明  
 关键信息缺失 → 先追问（最多 3 个问题），再输出声明
@@ -44,17 +47,27 @@ read_when: 开始任何标准功能/高风险开发任务之前 · 用户意图
 ```
 我准备这样理解这个任务，请确认或调整：
 
+0. **功能意图**（我的推测：先对齐这个功能要解决谁的什么问题）
+   A. 解决明确业务问题，给明确角色使用（推荐）
+   B. 内部/运营工具，不直接面向前台用户
+   C. 先做 MVP，方向后续再收敛
+
 1. **数据来源**（我的推测：用动态 DB 新建 `order` 类型）
    A. 用动态 DB 新建（推荐）
    B. 复用已有 DB 类型：___
    C. 用系统配置 KV 存储
 
-2. **管理侧**（我的推测：需要一个后台管理页）
+2. **管理侧**（我的推测：通常需要一个后台管理页）
    A. 需要，用户提交 + 管理员审核
    B. 不需要，纯用户自助
    C. 后续再做
 
-3. **入口位置**（我的推测：加到顶部导航）
+3. **导航状态**（我的推测：通常需要区分登录态和管理员态）
+   A. 需要，未登录 / 已登录 / 管理员都要考虑
+   B. 只做已登录态
+   C. 仅单一静态入口
+
+4. **入口位置**（我的推测：通常加到顶部导航）
    A. 顶部导航
    B. 首页模块入口
    C. 仅通过链接/按钮访问，不加导航
@@ -73,9 +86,14 @@ read_when: 开始任何标准功能/高风险开发任务之前 · 用户意图
 - [ ] [资源 1]：[具体内容]
 - [ ] [资源 2]：[具体内容]
 - [ ] [入口绑定]：[绑定位置]
+- [ ] [PRD/Task]：在 `.draftgo/Task/` 记录页面清单、功能清单、数据、角色路径、导航状态和管理闭环
+
+**意图**：[解决什么问题，给谁用]
 
 **数据方案**：[DB类型 / 字段设计 / 权限配置]
 
+**角色路径 / 管理闭环**：[前台用户怎么进入，管理员/运营怎么维护，是否保留现有系统入口]
+
 **不做的事**：[明确排除的内容，避免范围蔓延]
 
 **风险点**：[如有，说明；无则省略]
@@ -83,12 +101,14 @@ read_when: 开始任何标准功能/高风险开发任务之前 · 用户意图
 确认后开始。
 ```
 
+新系统 / 新板块场景下，这份声明后续应沉淀到 `.draftgo/Task/YYYY-MM-DD-<topic>.md`，并扩展出轻量 PRD。PRD 不追求冗长，但必须清点页面、功能、数据、入口、管理端、导航状态和验收证据。
+
 ---
 
 ## 关键原则
 
 1. **声明是同步，不是审批**——输出后等用户一句确认（「可以」「没问题」「开始」均算确认），不必等用户逐条review。
 2. **推测要带自信**——「我推测」不是「我不确定」，是「我基于上下文的最优判断」；若用户不纠正则视为接受。
-3. **一次声明，不反复确认**——声明输出后开始执行，中途不再停下来二次确认细节，除非遇到破坏性操作。
+3. **一次声明，不反复打断**——声明输出后开始执行，中途不再停下来重复确认细节，除非遇到破坏性操作。
 4. **小修不触发**——小修直接定位改，拖慢节奏的声明反而是反模式。
 5. **声明后发现冲突**——若执行中发现与 Story 或现有资源冲突，停止并显式提示，不静默执行。

package/resources/skill/pull/SKILL.md

@@ -25,7 +25,6 @@ allowed-tools: Bash(python:*), Read, Glob
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py nav            [nav_id ...]
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py db_meta        [db_meta_id ...]
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py aihub          [aihub_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py external_apis  [api_id ...]
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py system_config  [config_key ...]
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py docs           [article_id ...]
 !python {{SKILL_SCRIPTS}}/draftgo_pull.py doc_categories [category_id ...]
@@ -42,6 +41,15 @@ allowed-tools: Bash(python:*), Read, Glob
 - 多人协作时需要同步其他人的修改
 - 本地文件损坏或过期，需要刷新
 
+## 拉取自定义服务后的身份契约检查
+
+`draftgo pull custom_scripts` 会把云端服务的 `code`、`go_mod`、`go_sum` 写回 `.draftgo/custom_scripts/`。其中 `draftgo.Admin.*` 只是 Go 源码中的显式管理员 SDK 调用：
+
+- 不会生成 `admin_access`、`system_capabilities` 或 SAT 配置；不要手动补这些字段。
+- `draftgo.DB` 等普通 SDK 调用仍继承 Route 调用者权限；只有 `draftgo.Admin.*` 的那一项调用以平台管理员身份执行并进入执行审计。
+- 拉取后如需修改含 `draftgo.Admin.*` 的服务，先阅读 `../specs/custom-services.md`，保留字段脱敏逻辑，再执行 `draftgo push custom_scripts <id>`。
+- 推送后回读服务执行详情，确认存在 `Admin SDK call` 审计日志；不要把 SAT、管理员 cookie 或数据库连接复制进 `code_file` / `go_mod`。
+
 ## 与 init 的区别
 
 | 命令 | 功能 |

package/resources/skill/push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draftgo-push
-description: Use this skill when the user says "推送页面", "推送导航", "推送数据库", "推送AI资产", "推送外部API", "推送系统配置", "推送角色", "推送用户", "推送文档", "推送文档分类", "推送自定义脚本", "同步页面", "同步导航", "同步数据库", "同步AI资产", "同步外部API", "同步系统配置", "同步角色", "同步用户", "同步文档", "同步文档分类", "同步自定义脚本", "push pages", "push nav", "push db_meta", "push aihub", "push external_apis", "push system_config", "push roles", "push users", "push docs", "push doc_categories", "push custom_scripts", "sync pages", "sync nav", "sync db_meta", "sync aihub", "sync external_apis", "sync system_config", "sync roles", "sync users", "sync docs", "sync doc_categories", "sync custom_scripts", "/draftgo push", "/draftgo sync", or wants to push local changes to the DraftGo server.
+description: Use this skill when the user says "推送页面", "推送导航", "推送数据库", "推送AI资产", "推送系统配置", "推送角色", "推送用户", "推送文档", "推送文档分类", "推送自定义脚本", "同步页面", "同步导航", "同步数据库", "同步AI资产", "同步系统配置", "同步角色", "同步用户", "同步文档", "同步文档分类", "同步自定义脚本", "push pages", "push nav", "push db_meta", "push aihub", "push system_config", "push roles", "push users", "push docs", "push doc_categories", "push custom_scripts", "sync pages", "sync nav", "sync db_meta", "sync aihub", "sync system_config", "sync roles", "sync users", "sync docs", "sync doc_categories", "sync custom_scripts", "/draftgo push", "/draftgo sync", or wants to push local changes to the DraftGo server.
 version: 1.5.0
 allowed-tools: Bash(python:*), Read, Glob
 ---
@@ -8,7 +8,7 @@ allowed-tools: Bash(python:*), Read, Glob
 # DraftGo 推送（本地 → 云端）
 
 > **STOP — 禁止用 curl、禁止自己写 Python 上传逻辑。**
-> 唯一正确方式：运行下方 Python 脚本。脚本覆盖 init 拉取的全部类型（pages / nav / db_meta / aihub / external_apis / system_config / roles / users / docs / doc_categories / custom_scripts），已处理字段结构、token 读取、错误处理。
+> 唯一正确方式：运行下方 Python 脚本。脚本覆盖 init 拉取的全部类型（pages / nav / db_meta / aihub / system_config / roles / users / docs / doc_categories / custom_scripts），已处理字段结构、token 读取、错误处理。
 
 脚本位于：`{{SKILL_SCRIPTS}}/draftgo_push.py`
 
@@ -18,7 +18,7 @@ allowed-tools: Bash(python:*), Read, Glob
 > - **有 id** → `PUT /api/{type}/{id}` 更新（PUT 404 时自动转为创建）
 > - **无 id** → `POST /api/{type}` 创建，成功后**自动回写新 id 到 index.json**，并把对应 .html/.md/代码文件**重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`**
 
-支持创建的类型：**pages / nav / db_meta / aihub / external_apis / docs / doc_categories / custom_scripts**。
+支持创建的类型：**pages / nav / db_meta / aihub / docs / doc_categories / custom_scripts**。
 
 ### 新建页面的标准流程
 
@@ -50,10 +50,9 @@ allowed-tools: Bash(python:*), Read, Glob
 | nav | `name`, `code` | 创建必填 code，更新时不发 |
 | db_meta | `type`, `label`, `schema` | 无 id 时按 type 创建 |
 | aihub | `type`, `name`, `data` | 支持 model/prompt/agent/mcp/skill 等 AI 资产 |
-| external_apis | `code`, `name`, `base_url` | code 不可包含 `/` 或空格；创建时不发送 status |
 | docs | `title` | 其余字段有默认值 |
 | doc_categories | `name` | slug 可选；不填由后端生成/处理 |
-| custom_scripts | `name`, `slug`, `mode`, `triggers` | mode=route/event/scheduled；创建后默认覆盖代码，启停仍走 enable/disable |
+| custom_scripts | `name`, `slug`, `mode` | 服务使用 `mode=mixed`；触发器写在 `Register` 中，启停仍走 enable/disable |
 
 > **创建后必须以脚本回写的 index 为准**，不要手动猜 id。回写后建议 `git diff` 或重新读 index 确认 `id` 已落地。
 
@@ -90,15 +89,6 @@ allowed-tools: Bash(python:*), Read, Glob
 
 读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/aihub` 创建，成功后回写新 `id`。
 
-## 推送外部 API（"推送外部API" / "push external_apis"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis
-!python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis <api_id>
-```
-
-读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/external-apis` 创建，成功后回写新 `id`。创建最少需要 `code`、`name`、`base_url`。
-
 ## 推送系统配置（"推送系统配置" / "push system_config"）
 
 ```
@@ -108,33 +98,41 @@ allowed-tools: Bash(python:*), Read, Glob
 
 读取 `.draftgo/system_config/index.json`，按 `config_key` 调用 `PUT /api/system/{config_key}`。脚本优先使用 `parsed_value`。
 
-## 推送角色（"推送角色" / "push roles"）⚠️ 需二次确认
+前端全局层（`category = frontend_global` 或 `frontend_global_*`）属于系统默认配置，推送时只发送 `config_value`，不要发送 `description/category/value_type/status` 等元信息。其它系统配置若遇到“系统默认字段不允许修改字段描述/分类/状态”等错误，脚本会自动降级为只推送 `config_value`。
 
-roles 涉及权限安全，**强制要求人工确认**：
+Toast 全局配置常用键：
 
-1. 读取 `.draftgo/roles/index.json`
-2. **向用户展示即将推送的变更内容**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py roles
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py roles <role_id>
-   ```
-5. 用户拒绝则不推送
+| config_key | 说明 |
+|---|---|
+| `frontend_global_toast_position` | 位置，支持 `center` |
+| `frontend_global_toast_scale` | 大小比例，范围 `0.5-3` |
+| `frontend_global_toast_opacity` | 背景透明度，范围 `0-100` |
+| `frontend_global_toast_duration_success/error/warning/info` | 默认停留时间，存储单位为毫秒；页面管理以秒输入 |
+| `frontend_global_toast_css` | Toast 自定义 CSS |
+| `frontend_global_scrollbar_color_mode` | 滚动条颜色模式：`theme` / `custom` |
+| `frontend_global_scrollbar_color` | 自定义滚动条颜色，`#RRGGBB` |
+| `frontend_global_scrollbar_buttons` | 是否显示两端按钮 |
+| `frontend_global_scrollbar_opacity` | 滑块透明度，范围 `0-100` |
+| `frontend_global_scrollbar_radius` | 圆角 px |
+| `frontend_global_scrollbar_width` | 宽度 px |
+
+## 推送角色（"推送角色" / "push roles"）
 
-## 推送用户（"推送用户" / "push users"）⚠️ 需二次确认
+```
+!python {{SKILL_SCRIPTS}}/draftgo_push.py roles
+!python {{SKILL_SCRIPTS}}/draftgo_push.py roles <role_id>
+```
 
-users 涉及账号安全，**强制要求人工确认**：
+读取 `.draftgo/roles/index.json`，按 `RoleUpdateRequest` 字段推送。脚本不会修改未写入索引的权限绑定关系。
 
-1. 读取 `.draftgo/users/index.json`
-2. **向用户展示即将推送的变更内容**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py users
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py users <user_id>
-   ```
-5. 脚本不会下发 password / role_ids；如需修改请走专用接口
+## 推送用户（"推送用户" / "push users"）
+
+```
+!python {{SKILL_SCRIPTS}}/draftgo_push.py users
+!python {{SKILL_SCRIPTS}}/draftgo_push.py users <user_id>
+```
+
+读取 `.draftgo/users/index.json`，按 `UserUpdateRequest` 字段子集推送。脚本不会下发 `password` / `role_ids`；如需修改请走专用接口。
 
 ## 推送文档（"推送文档" / "push docs"）
 
@@ -143,7 +141,7 @@ users 涉及账号安全，**强制要求人工确认**：
 !python {{SKILL_SCRIPTS}}/draftgo_push.py docs <article_id>
 ```
 
-读取 `.draftgo/docs/articles/index.json`；正文从 meta 中的 `content_file`（同目录 `.md` 文件）回填，按 `ArticleUpdate` schema 推送。修改文档时**直接改 `.md` 文件**即可，索引项保持稳定。
+读取 `.draftgo/docs/articles/index.json`；正文从 meta 中的 `content_file`（同目录 `.html` 文件）回填，按 `ArticleUpdate` schema 推送（自动附带 `content_type: "html"`）。修改文档时**直接改 `.html` 文件**即可，索引项保持稳定。
 
 ## 推送文档分类（"推送文档分类" / "push doc_categories"）
 
@@ -154,19 +152,16 @@ users 涉及账号安全，**强制要求人工确认**：
 
 读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/docs/categories` 创建，成功后回写新 `id`。
 
-## 推送自定义脚本（"推送自定义脚本" / "push custom_scripts"）⚠️ 需二次确认
+## 推送自定义脚本（"推送自定义脚本" / "push custom_scripts"）
 
-脚本代码会以**生效语义**直接覆盖云端运行的脚本，**强制要求人工确认**：
+> 编写或修改代码前必须先读 `{{SKILL_DIR}}/specs/custom-services.md`。新服务使用 Go `Register(app *sdk.App)`；该文档是 handler ctx、完整 SDK、权限和运行限制的权威契约。
 
-1. 读取 `.draftgo/custom_scripts/index.json`，并读取每条 meta 中 `code_file` 指向的代码文件
-2. **向用户展示即将更新的脚本与摘要差异**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts <script_id>
-   ```
-5. 脚本不会修改 `mode`/`slug`/`status`（避免误启停）；如需切换启停请走 `POST /api/scripts/{id}/enable|disable`
+```
+!python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts
+!python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts <script_id>
+```
+
+读取 `.draftgo/custom_scripts/index.json`，并读取每条 meta 中 `code_file` 指向的代码文件后推送。脚本不会修改 `mode`/`slug`/`status`（避免误启停）；如需切换启停请走 `POST /api/scripts/{id}/enable|disable`。
 
 ### ⚠️ code_file 一致性（强制）
 
@@ -179,35 +174,77 @@ users 涉及账号安全，**强制要求人工确认**：
 
 违反后果：推送静默成功但上传的是旧代码，云端脚本不更新，排查极其隐蔽。
 
-## 冲突检测（多窗口协作保护）
+### Go 服务注册规则（强制）
 
-> push 前会自动检测云端是否已被他人修改，防止静默覆盖。
+新服务必须使用 `package main` 与 `Register(app *sdk.App)`：
 
-**工作原理**：pull 时 `index.json` 会记录每条资源的 `updated_at`。push 时先 GET 云端当前 `updated_at`，与本地基线比对：
+```go
+func Register(app *sdk.App) {
+    app.Route("GET", "/doctors", doctors)
+    app.On("doctor.updated", refresh)
+}
 
-- **一致** → 正常推送
-- **不一致** → 跳过该条，打印警告，继续推下一条
-- **`--force`** → 跳过检测，直接覆盖
+func doctors(draftgo *sdk.Context) (any, error) {
+    return draftgo.Respond(map[string]any{"ok": true}, 200, nil), nil
+}
+```
 
-**典型场景**：
+路径换算：`slug=prescription` + `app.Route("GET", "/doctors", doctors)` = `GET /api/x/prescription/doctors`。一个服务可混合多个 route、event、scheduled handler；新服务使用 `mode=mixed`。旧 `triggers` 字段不是 Go 注册来源。
 
-| 场景 | 行为 |
-|---|---|
-| 单窗口正常 push | 无变化，正常推 |
-| 窗口 A push 后，窗口 B push 同一资源 | B 检测到冲突 → 跳过 |
-| B 先 `draftgo pull` 再 push | pull 刷新基线 → 正常推 |
-| 确定要覆盖 → `draftgo push --force` | 跳过检测，强制覆盖 |
+route 脚本推送后的完成证据不能只看 `OK script_id=...`；至少还要真实请求目标端点，确认返回不是 404。需要鉴权时带管理员或允许角色 token 验证。
+
+### route handler 与 SDK 运行时（强制）
+
+handler 签名为 `func handler(draftgo *sdk.Context) (any, error)`。`draftgo` 是普通局部变量名，可自定义；本 skill 统一用它强调平台能力。Route 输入位于 `draftgo.Input`：`body`、`query_params`、`headers`、`method`、`path_params`；`path_params` 只含 `slug/path`，不解析 `{id}` 模板。身份用 `draftgo.Auth.CurrentUser()`，状态码和响应头用 `draftgo.Respond(...)`。
+
+### 显式管理员 SDK 调用（随代码同步）
+
+`draftgo.Admin.*` 是 Go 服务源码的一部分；它不对应 `admin_access`、`system_capabilities` 或其他 index 配置字段。pull/push 只同步 `code_file`、`go_mod`、`go_sum`，**绝不**在本地元数据、服务源码、页面或请求中写入 SAT。
+
+```go
+// 普通调用继承 Route 调用者权限。
+mine, err := draftgo.DB.Query("order", sdk.QueryOptions{})
+
+// 只有这一项调用以平台管理员身份执行，运行时自动记录审计。
+catalog, err := draftgo.Admin.DB.Query("internal_catalog", sdk.QueryOptions{})
+```
+
+`draftgo.Admin` 对齐普通 SDK 的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub`。管理员服务可使用完整平台权限；调用方返回前仍应显式组装允许暴露的字段。包含 `draftgo.Admin.` 的服务推送后，除 route 真实请求外，还必须回读 `/api/scripts/{id}/executions/{execution_id}`，确认 `logs` 有 `Admin SDK call` 审计项。
+
+### ctx.DB.Query 分页语义（强制）
+
+自定义服务里的 `ctx.DB.Query(type, sdk.QueryOptions{...})` 返回 `sdk.QueryResult`：
+
+```go
+result, err := ctx.DB.Query("order", sdk.QueryOptions{Page: 1, PageSize: 20})
+```
+
+- `sdk.QueryResult` 提供 `Items`、`Total`、`Page`、`PageSize`。
+- 使用 `Page` 与 `PageSize` 明确分页；需要完整数据时按 `Total` 逐页读取。
+- `filters` 默认是 `eq` 精确匹配；字段必须在 db_meta schema 中标记 `searchable`，操作符规则见 `specs/data.md`。
+
+### 权限与安全配置（强制区分）
+
+- `scripts:read/create/update/delete/execute` 是服务管理面的角色 RBAC；创建和编辑权限只授予可信代码编辑者。
+- `permission` 决定谁能调用 route 服务：`public` / `login` / `admin` / 指定 roles。
+- `config.route_security` 决定运行时护栏：`auth_required`、`rate_limit_per_minute`、`burst_limit`、`max_body_size_kb`、`timeout_ms`、`ip_allowlist`、`ip_blocklist`。
+- `permission` 为空时默认公开；如服务不应公开，必须显式设置 `permission.default` 或 `route_security.auth_required=true`。
+- 管理权限不自动获得 route 调用权限；推送时不要因调用者是管理员或编辑者而省略 `permission`。
+- 管理员 SDK 不是 Route 自动提权：只有代码显式调用 `draftgo.Admin.*` 的单次 SDK 操作提升为管理员身份；其余 `draftgo.DB` 等调用仍按 Route 调用者权限执行。
+- 高并发服务配置 `max_concurrency` / `queue_timeout_ms`，并让调用方处理 HTTP 429；不要依赖不存在的自动重试配置。
+
+## 推送语义
+
+`pull` 只负责从云端拉取到本地，`push` 只负责把本地文件推送到云端。push 不做云端 `updated_at` 对比，也不会因为云端时间更新而跳过资源；请在推送前自行确认本地文件就是要生效的版本。
 
 **CLI 用法**：
 ```bash
-draftgo push pages          # 带冲突检测
-draftgo push pages --force  # 跳过检测，强制覆盖
+draftgo push pages
 ```
 
 **脚本直接调用**：
 ```
 !python {{SKILL_SCRIPTS}}/draftgo_push.py pages
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages --force
 ```
 
 ## 推送方式
@@ -241,9 +278,7 @@ payload 必须包含完整元数据（从 `pages/index.json` 读取）+ HTML：
 
 **AI 资产推送**：`PUT /api/aihub/{id}`，payload 子集：`type`, `name`, `data`, `priority`, `version`, `tags`, `describe`, `permission`, `status`。
 
-**外部 API 推送**：`PUT /api/external-apis/{id}`，payload 子集：`name`, `base_url`, `method`, `path`, `headers`, `auth_type`, `auth_config`, `timeout_ms`, `permission`, `param_schema`, `tags`, `description`, `status`。
-
-**系统配置推送**：`PUT /api/system/{config_key}`，payload：`config_value`(parsed), `value_type`, `category`, `description`, `is_sensitive`, `status`。
+**系统配置推送**：`PUT /api/system/{config_key}`。前端全局层和受保护系统默认配置只推 `config_value`(parsed)；自定义配置可推 `value_type`, `category`, `description`, `is_sensitive`, `status`，不存在时再 `POST /api/system/` 创建。
 
 **角色推送**：`PUT /api/roles/{id}`，payload 含 `name`, `description`, `status`, `sort_order`, `user_visible`。
 
@@ -253,7 +288,7 @@ payload 必须包含完整元数据（从 `pages/index.json` 读取）+ HTML：
 
 **文档分类推送**：`PUT /api/docs/categories/{id}`，payload：`name`, `slug`, `description`, `icon`, `parent_id`, `sort_order`, `status`。
 
-**自定义脚本推送**：`PUT /api/scripts/{id}`，payload 子集：`name`, `description`, `code`(从语言对应的代码文件读取), `triggers`, `config`, `permission`。注意 schema 不接受 `mode`/`status`，启停请走 `POST /api/scripts/{id}/enable|disable`。
+**自定义脚本推送**：`PUT /api/scripts/{id}`，payload 子集：`name`, `description`, `code`(从语言对应的代码文件读取), `config`, `permission`。触发器只来自代码装饰器，不发送旧 `triggers` 字段。注意 schema 不接受 `mode`/`status`，启停请走 `POST /api/scripts/{id}/enable|disable`。
 
 ## 失败处理
 

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

@@ -4,8 +4,10 @@ read_when: 需要查具体 API 端点时 · 构造请求时
 
 # 后端 API 速查
 
-> 完整 OpenAPI 规范见 [api.json](./api.json)  
+> 优先运行 `draftgo api <keyword>` 做结构化查询；需要完整 OpenAPI 时见 [api.json]({{SKILL_SHARED}}/quickref/api.json)。
 > 统一响应信封：`{ code: 200, data: <载荷>, message: "success" }`
+> GET 列表端点通常在不传 `page` / `page_size` 时全量返回；自定义服务执行记录是固定分页特例（默认 20，最大 100）。
+> Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，筛选和分页见 `specs/custom-services.md`。
 
 ## 认证
 
@@ -19,95 +21,116 @@ POST /api/auth/wechat/mp/qr/create  GET /wechat/mp/qr/poll
 ## 用户 & 角色
 
 ```
-GET/PUT  /api/users/me                PUT /users/me/password
-GET/POST /api/users                   GET/PUT/DELETE /users/{id}
-POST     /users/{id}/ban, /unban
+GET/PUT  /api/users/me                PUT /api/users/me/password
+GET/POST /api/users                   GET/PUT/DELETE /api/users/{id}
+POST     /api/users/{id}/ban, /unban
 
-GET/POST /api/roles                   GET/PUT/DELETE /roles/{id}
-POST     /roles/{id}/assign/{uid}     DELETE /roles/{id}/revoke/{uid}
+GET/POST /api/roles                   GET/PUT/DELETE /api/roles/{id}
+POST     /api/roles/{id}/assign/{uid} DELETE /api/roles/{id}/revoke/{uid}
 ```
 
 ## 页面
 
 ```
 GET/POST           /api/pages/
-GET/PUT/DELETE     /pages/{id}
-POST               /pages/{id}/reset-system
-GET                /pages/by-route?route=/xxx
-GET                /pages/{id}/versions
-POST               /versions/{vid}/restore, /star
+GET/PUT/DELETE     /api/pages/{id}
+POST               /api/pages/{id}/reset-system
+GET                /api/pages/by-route?route=/xxx
+GET                /api/pages/{id}/versions
+POST               /api/pages/{page_id}/versions/{version_id}/restore, /star
 ```
 
 ## 导航栏
 
 ```
 GET/POST      /api/navigations
-GET           /navigations/{code}
-PUT/DELETE    /navigations/{id}
+GET           /api/navigations/{code}
+PUT/DELETE    /api/navigations/{id}
 ```
 
 ## 动态 DB
 
 ```
-GET            /api/db/{type}   支持 filters/order_by/order
-POST           /db/{type}       body: { data: {...} } 或数组
-PATCH          /db/{type}/batch
-GET/PUT/DELETE /db/{type}/{id}
+GET            /api/db/{type}
+               支持 filters/order_by/order/page/page_size/populate/scope=mine
+               scope=mine 仅 admin 用户的列表 GET 生效：非后台业务页用，后台管理页不用
+               📌 filters 语法 → specs/data.md#filters-操作符
+               📌 searchable 模式 → specs/data.md#searchable-字段标记
+               📌 ref/populate/onDelete → specs/data.md#关联关系ref
+POST           /api/db/{type}       body: { data: {...} } 或数组
+PATCH          /api/db/{type}/batch
+GET/PUT/DELETE /api/db/{type}/{id}
+               DELETE 会按真实引用字段的 ref.onDelete 处理级联 / 置空 / 阻止 / 解除关联
 ```
 
 ## DB Meta ⚠️
 
 ```
 GET/POST         /api/db-meta
-GET              /db-meta/{type}   ← 必须用 type，不是 id！
-PUT/DELETE       /db-meta/{id}
-POST             /db-meta/{type}/reconcile-fields
+GET              /api/db-meta/{type}   ← 必须用 type，不是 id！
+PUT/DELETE       /api/db-meta/{id}
+POST             /api/db-meta/{type}/reconcile-fields
 ```
 
 ## 自定义服务
 
 ```
 GET/POST         /api/scripts
-GET/PUT/DELETE   /scripts/{id}
-POST             /scripts/{id}/enable, /disable, /execute
+GET              /api/scripts/options/roles
+GET/PUT/DELETE   /api/scripts/{id}
+GET              /api/scripts/{id}/routes
+POST             /api/scripts/{id}/enable, /disable, /execute
+GET              /api/scripts/{id}/versions
+POST             /api/scripts/{id}/versions/{version_id}/restore
+GET              /api/scripts/{id}/executions
+GET              /api/scripts/{id}/executions/{execution_id}
 ANY              /api/x/{slug}/{path}   ← 脚本运行时端点
 ```
 
-## 外部 API
-
-```
-GET    /api/external-apis/available        ← 页面可调用列表（优先用 App.callApi）
-GET/POST /api/external-apis               ← 管理端
-PATCH  /external-apis/{id}/status
-POST   /external-apis/{id}/test
-```
+自定义服务要点：
+
+- 本地文件：`.draftgo/custom_scripts/index.json` + 每条记录的 `code_file`。
+- 新服务使用 Go `Register(app *sdk.App)`；用 `app.Route` / `app.On` / `app.Schedule` 自动注册。
+- 新服务使用 `mode=mixed`，可同时暴露 HTTP、响应事件和执行 cron。
+- route 注册来自 `app.Route("METHOD", "/path", handler)`；一个服务可声明多个 route，共用同一个 slug 命名空间。
+- event 和 scheduled 分别来自 `app.On(...)` 与 `app.Schedule(...)`；均支持在一个服务内声明多个 handler。
+- 旧 `triggers` 字段不参与注册，CLI 不再创建或推送该字段。
+- route handler 签名：`func handler(ctx *sdk.Context) (any, error)`；实际字段位于 `ctx.Input`，用户身份用 `ctx.Auth.CurrentUser()`。
+- Route 的普通 SDK 调用继承当前调用者资源权限，管理员创建服务不自动提升；需要管理员权限时逐次显式调用 `draftgo.Admin.DB`、`draftgo.Admin.Users` 等。`Admin` 调用以管理员身份执行并自动写入执行审计，但不会向代码暴露 SAT。带 `user_id` / `actor_user_id` 的事件继承该用户，定时任务及无可解析用户的事件才是系统身份。
+- 路径换算：`slug=order` + `app.Route("POST", "/pay", handler)` → `POST /api/x/order/pay`。
+- route 是精确路径匹配，不支持 `/items/{id}` 参数模板；ID 使用 query/body。
+- 动态数据访问使用 `ctx.DB.Query("order", sdk.QueryOptions{...})`，结果为 `sdk.QueryResult`；筛选与分页见 `specs/custom-services.md`。
+- `permission` 控制调用权限；`config.route_security` 控制限流、IP、body 大小和超时。
+- `scripts:*` 控制服务管理权限，和 Route 的调用权限彼此独立；执行列表固定分页，详情日志按单条加载。
+- `config.max_concurrency` / `queue_timeout_ms` 控制服务级退避；Route 饱和返回 429。
+- 完整 SDK、ctx、AIHub、事件、配置与运行限制见 `specs/custom-services.md`。
 
 ## AIHub & AI推理
 
 ```
 GET/POST   /api/aihub
-POST       /aihub/{id}/sync
+POST       /api/aihub/{id}/sync
 GET        /api/v1/models
-POST       /v1/chat/completions      ← OpenAI 兼容格式
-POST       /api/agents/{id}/chat, /images
+POST       /api/v1/chat/completions      ← OpenAI 兼容格式
+POST       /api/agents/{id}/chat, /api/agents/{id}/images
 ```
 
 ## 文档中心
 
 ```
 GET/POST   /api/docs/categories
-GET        /docs/articles, /docs/articles/{key}, /docs/search
-POST       /docs/articles    PUT/DELETE /docs/articles/{id}
+GET        /api/docs/articles, /api/docs/articles/{key}, /api/docs/search
+POST       /api/docs/articles    PUT/DELETE /api/docs/articles/{id}
 ```
 
 ## 系统 & 备份
 
 ```
 GET          /api/system/config
-GET/PUT/DELETE /system/{key}
+GET/PUT/DELETE /api/system/{key}
 GET/POST     /api/system/backup
-POST         /system/restore, /reset
-POST         /system/restore/selective?mode=replace|merge|append
+POST         /api/system/restore, /api/system/reset
+POST         /api/system/restore/selective?mode=replace|merge|append
 POST         /api/upload
 GET          /api/logs
 ```
@@ -124,7 +147,6 @@ POST /api/auth/reauth  { password, scope }  → 返回 confirm_token
 
 | 端点 | 格式 |
 |---|---|
-| `POST /v1/chat/completions` | OpenAI SSE / JSON |
-| `GET /v1/models` | `{ object:"list", data:[...] }` |
-| `POST /external-apis/call/{code}` | 上游原始响应 |
+| `POST /api/v1/chat/completions` | OpenAI SSE / JSON |
+| `GET /api/v1/models` | `{ object:"list", data:[...] }` |
 | `ANY /api/x/{slug}/{path}` | 脚本自定义 |