draftgo-cli 2.0.3 → 2.0.9

package/resources/skill/SKILL.md

@@ -6,11 +6,14 @@ version: 1.0.0
 
 # DraftGo 开发助手
 
+> **【DraftGo 开发追求】**
+> 使用 DraftGo-CLI 开发的项目，默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。AI 应快速读懂现有资源，优先交付真实落地闭环、高可用的实现，并让后续修改者能继续迭代。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。
+>
 > **【开发分级 — 最高优先级】**
 > 任何开发对话开始时，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 判断任务级别**，再执行对应流程：
-> - **小修** → 直接定位 → 改 → check → push。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；仍需写 changelog。
-> - **轻功能** → 范围复述 → 直接做 → 主路径验证 → push。用于简单页面能力、单入口交互、小型数据联动，不强制 Task。
-> - **标准功能** → 轻量确认 → Task → TDR。若 `.draftgo/story.yaml` 存在则静默加载；不存在时不阻塞开发，但应在完成后提醒补 Story。
+> - **小修** → 直接定位 → 改 → 轻量证据。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；changelog / check / push 按影响选择。
+> - **轻功能** → 范围复述 → 直接做 → 凭证据闭环。用于简单页面能力、单入口交互、小型数据联动，不强制 Task。
+> - **标准功能** → 轻量确认 → 内部短计划 → 执行闭环。若 `.draftgo/story.yaml` 存在则静默加载；不存在时不阻塞开发，但应在完成后提醒补 Story；只有跨资源、多页面协作、并行或高风险时才落 Task。
 > - **高风险** → 完整 Story / 计划 / 验证 / 人工确认。无 `.draftgo/story.yaml` 时必须先构建 Story。
 >
 > **开发中发现请求与已有 Story 冲突时，必须显式提示开发者，不可静默执行。** 详见 `{{SKILL_DIR}}/story/SKILL.md` 冲突检测章节。
@@ -18,17 +21,23 @@ version: 1.0.0
 > **【开发任务硬性流程】**
 > 任何"开发 / 修改 / 新建 / 修复 / 重构 / 完善 / 优化"指令，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做任务分级和用户意图翻译**。标准功能 / 高风险任务追问用户时必须带上 AI 自己的意图推测（推测 + 2-3 个选项 + 推荐项），不能空着问；能合理推断的轻功能不因模板追问拖慢。前端开发按任务规模读取 `{{SKILL_DIR}}/rules/frontend.md` 的相关规则。
 >
-> **【更新日志硬性步骤】**
-> 每次完成任何开发 / 修复 / 修改 / 完善 / 删除 / 重构操作后，必须立即写更新日志到 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。这是强制步骤，不得跳过。
+> **【真实可用默认原则】**
+> 除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都优先考虑真实落地闭环、高可用。禁止用前端假数据、静态卡片、无效按钮或伪交互充当功能完成。若平台能力、外部依赖或通用动态 DB 都无法支撑该功能，不要继续编写伪功能；向用户说明阻塞原因，并在确有复用价值时写入 `.draftgo/lessons/`。
+>
+> **【更新日志记录】**
+> changelog 用于让后续 Agent 接手；影响可见功能、跨资源、已 push、已发布或用户明确要求记录时写入 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。纯小修、探索、未形成有效改动时可跳过。
 >
-> **【任务标记硬性步骤】**
-> 只有标准功能 / 高风险任务需要 Task 文档。走完计划门后，每完成一个任务必须立即更新 `.draftgo/Task/<file>.md` 中的 ⬜ → ✅ 标记和证据摘要。小修和轻功能无需创建 Task。
+> **【任务标记】**
+> 只有已创建 Task 文档的任务需要维护标记。跨资源、多页面协作、并行开发或高风险任务完成一个阶段后，更新 `.draftgo/Task/<file>.md` 中的 ⬜ → ✅ 标记和证据摘要；小修、轻功能和普通标准功能可用内部短计划，不创建 Task。
 >
 > **【双端覆盖提醒】**
-> 开发任何业务功能时，必须从完整用户路径链路思考：用户从官网 / 导航 / 首页入口进入，点击到目标页面，完成浏览 / 搜索 / 提交 / 管理等操作，再获得真实反馈。必须主动判断是否需要对应管理侧页面（后台 CRUD / 配置 / 审核）和同一份真实数据，避免只做静态展示页。
+> 开发业务功能时，优先从完整用户路径链路思考：用户从官网 / 导航 / 首页入口进入，点击到目标页面，完成浏览 / 搜索 / 提交 / 管理等操作，再获得真实反馈。围绕真实落地闭环、高可用判断是否需要对应管理侧页面（后台 CRUD / 配置 / 审核）和同一份真实数据，避免只做静态展示页。
 >
 > **【页面绑定提醒】**
 > 新增页面后必须处理入口绑定：导航栏、首页模块、后台菜单、相关页面按钮至少一处可点击进入；若用户明确要求隐藏页 / 草稿页，才可不绑定，但必须说明原因。只创建页面文件、不能从正常路径进入，不算完成。
+>
+> **【CLI 辅助工具】**
+> 资源关系不清、进入陌生项目、多页面任务或用户描述模糊时，优先运行 `draftgo map` 快速读取页面 / 导航 / DB / 脚本 / AIHub / 外部 API / 文档 / 系统配置资源地图；目标文件清楚的小修可跳过。涉及页面、导航、DB 或脚本改动时，可用 `draftgo check` 辅助发现未绑定入口、缺文件、重复路由和疑似 mock 风险。验证优先用文件回读、静态检查、与改动匹配的轻量证据和必要的 push 输出闭环。
 
 ## 命令路由
 
@@ -40,7 +49,9 @@ version: 1.0.0
 | 从云端拉取 / 刷新本地数据 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
 | 推送本地修改到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
 | 构建 / 查看 / 更新系统 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
-| 开发 / 修改 / 新建 / 修复 / 重构页面、导航、API、自定义脚本、AIHub 资产 | **先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做小修 / 轻功能 / 标准功能 / 高风险分级**。小修优先只读目标资源和最小必要规则；前端任务按需读 `{{SKILL_DIR}}/rules/frontend.md`；页面静默失效或脚本复杂时读 `{{SKILL_DIR}}/rules/debugging-syntax.md`；标准功能 / 高风险任务计划门结束后按需读 `{{SKILL_DIR}}/rules/parallel.md` 判断是否启用并行分发。完成后必须写 changelog、check、push；有 Task 文档时同步打 ✅。 |
+| 查看项目资源地图 / `draftgo map` | 直接运行 CLI，快速读取本地页面、导航、DB、脚本、AIHub、外部 API、文档、系统配置、入口引用 |
+| 闭环体检 / `draftgo check` | 直接运行 CLI，检查本地 route、入口绑定、文件存在性和疑似 mock 风险 |
+| 开发 / 修改 / 新建 / 修复 / 重构页面、导航、API、自定义脚本、AIHub 资产 | **先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做小修 / 轻功能 / 标准功能 / 高风险分级**。小修优先只读目标资源和最小必要规则；前端任务按需读 `{{SKILL_DIR}}/rules/frontend.md`；页面静默失效或脚本复杂时读 `{{SKILL_DIR}}/rules/debugging-syntax.md`；准备并行、多资源冲突或高风险计划时按需读 `{{SKILL_DIR}}/rules/parallel.md`。收尾按影响选择 changelog / check / push；有 Task 文档时同步打 ✅。 |
 
 ## 开发前置检查
 
@@ -55,21 +66,28 @@ version: 1.0.0
 开发规范读取顺序（按任务规模渐进读取）：
 1. `{{SKILL_DIR}}/rules/dev-workflow.md` — 开发分级与执行流程（小修 / 轻功能 / 标准功能 / 高风险）
 2. `{{SKILL_DIR}}/rules/frontend.md` — 前端技术规范（前端任务按需读取；小修可先只读相关段落）
-3. `{{SKILL_DIR}}/rules/data-table.md` — 数据列表/表格 UIUX 参考（涉及列表类页面且需要设计判断时读取）
-4. `{{SKILL_DIR}}/rules/debugging-syntax.md` — 排错指南（页面静默失效、脚本复杂或 console 报错时读取）
-5. `{{SKILL_DIR}}/rules/parallel.md` — 并行开发协议（标准功能 / 高风险且任务数足够、资源互不冲突时读取）
+3. `{{SKILL_DIR}}/rules/debugging-syntax.md` — 排错指南（页面静默失效、脚本复杂或 console 报错时读取）
+4. `{{SKILL_DIR}}/rules/parallel.md` — 并行开发协议（标准功能 / 高风险且任务数足够、资源互不冲突时读取）
 
 ## 架构认知（必读）
 
 **DraftGo 不是传统 SPA，是"数据库驱动的页面资产运行时"：**
-- 壳层（Vue 3 + Vite）只负责 runtime 编排，源码在 `frontend/src/core/`
+- 壳层（React + Vite）负责编译后的平台前端、runtime 编排和管理界面，源码在 `frontend/src/`
 - 业务页面 HTML 存在数据库 `page.value.html`，运行在 `iframe.srcdoc`
 - 导航栏 HTML 存在数据库 `navigation.html`，由壳层按需加载
 - 页面与壳层通过 `window.parent.App` API 通信
 
 **技术栈：**
 - 后端：FastAPI 0.115.0 + SQLAlchemy 2.0.36 + Pydantic 2.10.0 + MySQL + Redis
-- 前端：Vue 3 + Vite + Tailwind CSS（本地 `/assets/tailwindcss.js`）
+- 前端：React + Vite + shadcn/ui + Tailwind CSS（shadcn/Tailwind 已作为平台前端基线引入）
+- 数据库业务页面：仍可使用壳层注入的本地 `/assets/tailwindcss.js`、FontAwesome、GSAP 等静态资源，不需要进入 React 编译链
+
+**dg-* = shadcn（硬性认知）：**
+- 在 DraftGo 中，看到 `dg-*` 必须理解为 **shadcn/ui 的 DraftGo HTML 协议表达**。
+- `dg-*` 不是自研 UI 组件库，不是 daisyUI / Bootstrap / Ant Design / Element Plus 的别名，也不是任意相似样式的统称。
+- 平台壳层管理界面使用 React/TSX 版 shadcn 组件；数据库页面不能直接写 TSX，因此用 `dg-button`、`dg-card`、`dg-form`、`dg-table` 等 HTML 标签表达同一套 shadcn 组件能力。
+- 如果 shadcn 有对应组件，DraftGo 必须提供对应 `dg-*` 标签；当前 runtime 已按映射表提供基础协议覆盖，后续 shadcn 新组件也必须追加对应 `dg-*`。
+- AI 开发页面时，`dg-*` 只代表可用的 DraftGo HTML 组件协议，不代表视觉风格指令；需要按钮、卡片、表单、表格、弹窗、Tabs、Dropdown、Sheet、Tooltip、Toast、Skeleton 等协议能力时使用对应 `dg-*`。
 
 ## 连接信息
 
@@ -103,6 +121,9 @@ version: 1.0.0
   - `App.callApi(code, options?)` — 调用已注册的外部 API（Promise→`{status_code, headers, body, duration_ms, error}`）
   - `App.listApis()` — 列出当前用户可调用的外部 API（含 code / name / method / 各 JSON Schema）
   - 详见 `{{SKILL_DIR}}/rules/frontend.md` App API 章节
+- ❌ 禁止在业务页面内重复实现全局客服、全局反馈、全局浮窗、统计脚本等站点级能力 → ✅ 使用页面管理「全局」分类维护 `frontend_global_*` 固定槽位
+  - 全局层存储在 `sys_config.category=frontend_global`，不是 page 资产，不允许新增槽位
+  - Toast 可通过全局项二开样式/位置/默认时长，但页面调用仍使用 `App.toast()` / `App.showSuccess()` 等稳定 API
 - ⚠️ 尽量避免硬编码颜色 → 优先用 `var(--dg-accent)` 等 token 以适配主题切换
 
 ## 主题切换适配
@@ -113,12 +134,14 @@ DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
 | 概念 | 存储键 | 取值 |
 |---|---|---|
 | 显示模式 | `dg_theme` | `'light'` \| `'dark'` \| `'system'` |
-| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` |
+| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'warm-retro'` \| `'mint-blue'` \| `'pine-green'` \| `'custom'` |
 
 **内置配色方案：**
-- `dark-gray-white` 深灰白（默认）— 冷调深灰，干净利落
-- `deep-blue-white` 深蓝白 — 专业稳重，企业风
-- `orange-white` 橙白 — 温暖醒目，创意风
+- `dark-gray-white`
+- `deep-blue-white`
+- `warm-retro`
+- `mint-blue`
+- `pine-green`
 
 **颜色 Token（优先使用）：**
 - `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
@@ -179,7 +202,7 @@ App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
 | `navigation` | `id`, `code`, `name`, `html`, `order`, `status` | html 字段存导航栏完整 HTML |
 | `user` | `id`, `username`, `email`, `role_id`, `status` | role_id 关联 role 表 |
 | `role` | `id`, `code`, `name`, `permissions` (JSON) | admin 角色拥有所有权限 |
-| `db_meta` | `id`, `type`, `label`, `describe`, `schema` (JSON Schema: `{type:"object", properties:{字段名:{type,title,required,searchable,...}}}`), `permission` (JSON: `{public,login,admin,owner_field,roles}`，每项 `{read,create,update,delete}` 取值 `none/owner/all`，public 仅 `none/all`), `schema_validation` (0/1), `extra` (JSON) | 动态表结构定义 |
+| `db_meta` | `id`, `type`, `label`, `describe`, `schema` (JSON Schema: `{type:"object", properties:{字段名:{type,title,required,searchable,...}}}`；`searchable` 取 `false`/`"exact"`/`"fuzzy"`/`"range"`/`"contains"`，旧布尔 `true` 按类型推断), `permission` (JSON: `{public,login,admin,owner_field,roles}`，每项 `{read,create,update,delete}` 取值 `none/owner/all`，public 仅 `none/all`), `schema_validation` (0/1), `extra` (JSON) | 动态表结构定义 |
 | `db` | `id`, `type`, `data` (JSON), `userid`, `status`, `created_at`, `updated_at` | 动态数据存储（含自动时间戳） |
 | `aihub` | `id`, `name`, `type`, `config` (JSON), `status` | AI 服务配置 |
 | `sys_config` | `config_key`, `config_value`, `value_type`, `category`, `is_sensitive` | 系统配置 KV |
@@ -191,28 +214,29 @@ App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
 |---|---|
 | 认证 | POST /api/auth/login, /register, /logout, /refresh, /forgot-password, /reset-password |
 | 微信认证 | POST /api/auth/wechat/mp/oauth, /wechat/mini/login, /wechat/mp/qr/create · GET /wechat/mp/qr/poll |
-| 用户 | GET/PUT /api/users/me · GET/POST /api/users · GET/PUT/DELETE /users/{id} · POST /users/{id}/ban, /unban |
+| 用户 | GET/PUT /api/users/me · PUT /users/me/password · POST /users/me/contact-verifications, /confirm · POST /users/me/password/send-code/{channel}, /reset-by-phone, /reset-by-email · GET/POST /api/users · GET/PUT/DELETE /users/{id} · POST /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/pages/ · GET/PUT/DELETE /pages/{id} · POST /pages/{id}/reset-system · GET /pages/by-route · GET /pages/public/{route} |
+| 页面 | GET/POST /api/pages/ · GET/PUT/DELETE /pages/{id} · POST /pages/{id}/reset-system · GET /pages/trash · DELETE /pages/{id}/trash · GET /pages/by-route · GET /pages/public/{route} · POST /pages/check-permissions · GET /pages/{id}/versions · GET/DELETE /pages/{id}/versions/{vid} · POST /versions/{vid}/restore, /star · PATCH /versions/{vid}/note · GET /versions/{v1}/diff/{v2} · POST /versions/batch-delete |
 | 导航栏 | GET/POST /api/navigations · GET /navigations/{code} · PUT/DELETE /navigations/{id} · POST /navigations/{id}/reset-system |
-| 系统配置 | GET /api/system/config · GET /system/category/{category} · GET/PUT/DELETE /system/{key} · POST /system/ · POST /system/config/ensure |
-| 备份恢复（基础） | GET/POST /api/system/backup · POST /system/restore · POST /system/reset · POST /system/backup/selective · POST /system/restore/selective?mode=replace\|merge\|append · GET /system/backup/logs |
-| 备份恢复（增强） | GET /system/backup/package, POST /system/backup/selective/package（.dgbak）· POST /system/restore/package, /restore/package/inspect（上传 .dgbak）· POST /system/restore/inspect, /restore/dry-run（只读预览/预演）· GET /system/storage/health, POST /system/storage/cleanup-orphans（存储健康）· POST /system/backup/logs/{id}/restore, /undo（回溯/撤销） |
+| 系统配置 | GET /api/system/config · GET /system/category/{category} · GET/PUT/DELETE /system/{key} · POST /system/ · POST /system/config/ensure · GET/PATCH /system/config/sensitive-fields |
+| 备份恢复（基础） | GET/POST /api/system/backup · POST /system/restore · POST /system/reset · POST /system/backup/selective · POST /system/restore/selective?mode=replace\|merge\|append · POST /system/restore/selective/file?mode=replace\|merge\|append（上传 JSON 文件恢复）· GET /system/backup/logs |
+| 备份恢复（增强） | GET /system/backup/package, POST /system/backup/selective/package（.dgbak）· POST /system/restore/package, /restore/package/inspect（上传 .dgbak）· POST /system/restore/inspect, /restore/dry-run（JSON body 只读预览/预演）· POST /system/restore/inspect/file, /restore/dry-run/file（上传 JSON 文件只读预览/预演）· GET /system/storage/health, POST /system/storage/cleanup-orphans（存储健康）· POST /system/backup/logs/{id}/restore, /undo（回溯/撤销） |
 | ⚠️ 二次密码 | restore / reset / undo / cleanup-orphans / package restore 都需要先 POST `/auth/reauth { password, scope }` 拿一次性 `confirm_token`，在请求头加 `X-Confirm-Token: <token>` 才能调用。SAT 调用方自动豁免。 |
 | 通知公告 | GET/POST /api/notices · GET/PUT/DELETE /notices/{id} |
 | 反馈 | GET/POST /api/feedback · GET /feedback/updates · GET/PUT/DELETE /feedback/{id} · DELETE /feedback/batch |
 | 日志 | GET /api/logs · GET /logs/{id} |
-| 智能体 | GET /api/agents · GET /agents/logs · POST /agents/{id}/chat · POST /agents/{id}/images · POST /agents/{id}/preview-chat |
-| 动态DB | GET/POST /api/db/{type}（POST 支持对象或数组）· PATCH /db/{type}/batch · GET/PUT/DELETE /db/{type}/{id} |
-| DB Meta | GET/POST /api/db-meta（POST 支持对象或数组）· PATCH /db-meta/batch · GET /db-meta/{type} · PUT/DELETE /db-meta/{id} |
+| 智能体 | GET /api/agents · GET/DELETE /agents/logs · GET /agents/{id}/selectable-models · POST /agents/{id}/chat · POST /agents/{id}/images · POST /agents/{id}/preview-chat |
+| 动态DB | GET /api/db/{type}（支持 `filters`/`order_by`/`order` 结构化检索）· POST /db/{type}（对象或数组）· PATCH /db/{type}/batch · GET/PUT/DELETE /db/{type}/{id} |
+| DB Meta | GET/POST /api/db-meta（POST 支持对象或数组）· PATCH /db-meta/batch · GET /db-meta/{type} · POST /db-meta/{type}/reconcile-fields · POST /db-meta/reconcile-orphans · PUT/DELETE /db-meta/{id} |
 | ⚠️ DB Meta 查询 | GET /db-meta/{type} 用 **type**（如 `patient_profile`），不是 id。用 id 查会返回 "元数据不存在"。PUT/DELETE 才用 id。 |
-| AIHub | GET/POST /api/aihub（POST 支持对象或数组）· PATCH /aihub/batch · GET/PUT/DELETE /aihub/{id} · PATCH /aihub/{id}/basic · POST /aihub/{id}/sync · POST /aihub/{id}/test-image-generation · POST /aihub/discover · POST /aihub/mcp/discover-tools · GET /aihub/types |
+| AIHub | GET/POST /api/aihub（POST 支持对象或数组）· PATCH /aihub/batch · GET/PUT/DELETE /aihub/{id} · PATCH /aihub/{id}/basic · POST /aihub/{id}/sync · POST /aihub/{id}/test-image-generation, /test-response-format · POST /aihub/discover · POST /aihub/mcp/discover-tools · GET /aihub/types |
 | AI推理 | GET /api/v1/models · POST /v1/chat/completions · POST /api/images/generation |
 | 外部 API（页面调用端） | GET /api/external-apis/available · POST /api/external-apis/call/{code}<br>页面里**优先使用 `App.callApi(code, options)`**，不要直连这两个端点 |
 | 外部 API（管理端，需 admin） | GET/POST /api/external-apis · GET/PUT/DELETE /external-apis/{id} · PATCH /external-apis/{id}/status · POST /external-apis/{id}/test · GET /external-apis/tags · GET /external-apis/logs · POST /external-apis/logs/cleanup?retention_days=N |
 | 文件上传 | POST /api/upload |
 | 通知测试 | POST /api/system/notifications/test-email, /test-sms · GET /system/notifications/logs |
 | 自定义服务 | POST /api/scripts · GET /api/scripts · GET/PUT/DELETE /scripts/{id} · POST /scripts/{id}/enable, /disable, /execute · GET /scripts/{id}/versions · POST /scripts/{id}/versions/{vid}/restore · GET /scripts/{id}/executions · ANY /api/x/{slug}/{path} |
+| 文档中心 | GET/POST /api/docs/categories · GET /docs/articles, /docs/articles/{key}, /docs/search · GET /docs/admin/articles, /docs/admin/stats · POST /docs/articles · PUT/DELETE /docs/articles/{id} · PUT/DELETE /docs/categories/{id} |
 
 ### 统一响应信封
 
@@ -249,7 +273,7 @@ POST /api/pages/
 Body: { "title": "新页面", "route": "/new", "permission": {"default": "public"}, "value": {"html": "<html>...</html>"} }
 说明：permission 是对象，不是字符串。`default` 取值 `public`(任何人) / `login`(登录用户) / `admin`(管理员)；可选 `roles: {角色code: "public|login|admin"}` 做角色级覆盖。
 保留路由（不可被业务页面占用）：`/setup`（首次部署引导）。创建/更新时若 route 重复，后端返回 400 "route 已存在"。
-系统页：由后端从 `backend/init/pages/` 初始化，`tag == "系统"` 标识；改动后须 `POST /api/pages/{id}/reset-system` 才会从源文件重新加载。
+系统页：由后端从 `backend/init/pages/` 初始化，`tag == "系统"` 标识；不会在容器重启时自动对比或更新。官方版本提示页面模板有更新时，管理员需要在页面管理点击「重置系统页面」，或调用 `POST /api/pages/{id}/reset-system` 从当前安装包内置模板覆盖重置。
 Response: { "code": 200, "data": { "id": 123, "title": "新页面", "route": "/new", ... }, "message": "success" }
 ```
 
@@ -273,10 +297,13 @@ Body: { "data": {"name": "张三", "age": 30} }
 Response: { "code": 200, "data": [{ "id": 456 }], "message": "success" }
 ```
 
-**查询动态数据（带分页）：**
+**查询动态数据（分页 + 结构化检索）：**
 ```
 GET /api/db/patient?page=1&page_size=20
+GET /api/db/patient?filters=name:like:张&filters=age:gte:18&order_by=age&order=desc
 Response: { "code": 200, "data": { "items": [...], "total": 100, "page": 1, "page_size": 20 }, "message": "success" }
+说明：filters 每项为 "字段:操作符:值"，可多次传入（AND）。操作符 eq/like/gte/lte/gt/lt/in/contains，省略默认 like。
+     字段须在 db_meta schema 标 searchable，且操作符匹配其检索模式（exact/fuzzy/range/contains），否则 400。
 ```
 
 **批量更新动态数据：**
@@ -412,7 +439,7 @@ const visitId = query.visitId;      // "7"
 | 问题 | 排查步骤 |
 |---|---|
 | 同步失败 | 1. 检查 `.draftgo/config.json` token 是否有效<br>2. 检查服务器连接<br>3. 查看 `.draftgo/changelog.md` 最近操作记录 |
-| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 浏览器控制台查看 JS 错误 |
+| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 检查页面脚本错误、运行日志或最近改动 |
 | API 返回 401 | Token 过期，前端会自动用 refresh token 刷新，无需手动处理 |
 | API 返回 403 | 权限不足，检查当前用户角色是否有对应权限 |
 | DB Meta GET 返回"元数据不存在" | 你用了 id，应该用 **type**（如 `/api/db-meta/patient_profile`）。PUT/DELETE 才用 id。 |
@@ -424,7 +451,7 @@ const visitId = query.visitId;      // "7"
 
 ## 更新日志规范
 
-每次对系统进行开发/修复/修改/完善/删除/重构等操作后，**必须**写入 `.draftgo/changelog.md`。
+更新日志用于让后续 Agent 和开发者快速接手。影响可见功能、跨资源、已 push、已发布或用户明确要求记录时，写入 `.draftgo/changelog.md`；纯小修、探索、未形成有效改动时可跳过。
 
 ### 规则
 
@@ -450,7 +477,7 @@ const visitId = query.visitId;      // "7"
 
 ### 操作流程
 
-1. 完成任何系统操作后，获取当前日期和时间
+1. 判断本次改动是否需要记录
 2. 检查 `.draftgo/changelog.md` 是否存在
 3. 查找当天日期标题（`## YYYY-MM-DD`）
 4. 存在则在该日期段落末尾追加新条目；不存在则在文件顶部新增日期段落
@@ -507,18 +534,18 @@ xxx
 
 ---
 
-## 自动推送规范
+## 推送规范
 
-> **每次修改页面或导航栏 HTML 后，必须立即自动推送到服务器。这是强制步骤，不得跳过，不得等用户提醒。**
+> 推送用于把本地资源同步到云端。用户明确要求推送、任务目标包含云端生效、资源已形成可交付结果、或修改涉及多资源联动时执行；探索性修改、未完成草稿和目标明确的小修可先保留本地。
 
 ### 新建资源（无 id 自动创建）
 
 push 脚本按 index.json 条目**有无 `id`** 决定走更新还是创建：
 
 - **有 id** → `PUT` 更新（PUT 404 时自动转创建，兼容删了重建 / 跨环境）
-- **无 id** → `POST` 创建，成功后**自动回写新 id 到 index.json**，并把内容文件重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`
+- **无 id** → `POST` 创建，成功后**自动回写新 id 到 index.json**；有独立内容文件的资源会同步重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`
 
-支持创建的类型：**pages / nav / db_meta / docs / custom_scripts**。
+支持创建的类型：**pages / nav / db_meta / aihub / external_apis / docs / doc_categories / custom_scripts**。
 
 **新建页面 = 写 html 文件 + 在 `pages/index.json` 加一条不带 id 的记录 + `push pages`**。脚本回写 id 后即与普通更新无异，无需手动调 `POST /api/pages/`、无需手动维护 id。各类型创建必填字段见 push skill（`{{SKILL_DIR}}/push/SKILL.md`「新建资源」节）。
 
@@ -571,14 +598,14 @@ roles 和 users 涉及权限与账号安全，虽然脚本已支持，**仍必
 2. **等待用户明确确认**后，再运行 `draftgo_push.py roles` / `users`
 3. 用户拒绝则不推送，仅保留本地修改
 
-### 完整操作顺序（每次开发任务结束时）
+### 收尾操作顺序（按影响选择）
 
-1. 写更新日志（静默，强制）
+1. 判断是否需要写更新日志
 2. 写经验记录（有阻碍或新经验时写入 lessons/，没有则跳过）
-3. 运行推送脚本 / 调用 API（必须执行，roles/users 需二次确认）
-4. 告知用户推送结果
+3. 需要云端生效时运行推送脚本 / 调用 API（roles/users 需二次确认）
+4. 告知用户本次证据与是否已推送
 
-> **Lessons 提醒机制**：当 `.draftgo/config.json` 中 `lessons_on_push` 为 `true` 时，push 脚本执行完毕会输出一段回顾提醒。此提醒仅为兜底安全网——无论是否看到提醒，步骤 2 的 lessons 回顾义务始终生效。
+> **Lessons 提醒机制**：当 `.draftgo/config.json` 中 `lessons_on_push` 为 `true` 时，push 脚本执行完毕会输出一段回顾提醒。此提醒仅为兜底安全网；是否写 lessons 仍按“有阻碍或新经验”判断。
 
 ---
 
@@ -628,7 +655,7 @@ def cleanup(sdk, ctx):
 
 ```python
 # ❌ 这些写法都会报错
-from draftgo import route       # 'draftgo' 不在白名单
+from draftgo import route       # 没有 draftgo 这个内置模块
 from sdk import route           # 可以但多余，直接用就行
 import sdk                      # 可以但多余
 
@@ -656,24 +683,22 @@ def handler(request):           # ❌ 签名必须是 (sdk, ctx)
   - Event: `{event, payload, timestamp}`
   - Scheduled: `{trigger_type, trigger_name, payload, config}`
 
-### 可用模块（白名单）
+### 可导入模块
 
-只有以下模块可以 import：
+自定义脚本只允许管理员创建和编辑，因此脚本引擎**不再做 import 白名单限制**。脚本可以导入当前后端运行环境中已经安装的 Python 模块；如果目标环境没有安装该依赖，脚本加载或执行时会报 `ImportError`。
 
-```
-json, re, datetime, math, collections, itertools, functools,
-typing, dataclasses, enum, uuid, hashlib, base64, urllib.parse
-```
+建议优先使用标准库和 DraftGo SDK。需要新增第三方依赖时，要确认部署环境的 `requirements.txt` / 镜像中已经包含该包，避免本地可用、线上不可用。
 
-**不能用的 + 替代方案：**
+**推荐做法：**
 
-| 需求 | ❌ 禁止 | ✅ 替代 |
-|------|---------|---------|
-| HTTP 请求 | `import requests` | `sdk.external_api.get/post/put/delete(url, headers, timeout)` |
-| 缓存 | `import redis` | `sdk.cache.get/set/delete(key)` |
-| 日志 | `print()` / `import logging` | `sdk.log.info/warn/error/debug(msg)` |
-| 当前时间 | `import time` | `sdk.now()` 或 `import datetime` |
-| 文件操作 | `open()` / `import os` | 不支持（设计如此） |
+| 需求 | 推荐 |
+|------|------|
+| 调外部 HTTP | 优先 `sdk.external_api.get/post/put/delete(url, headers, timeout)`，也可在依赖可用时自行导入 HTTP 客户端 |
+| 缓存 | 优先 `sdk.cache.get/set/delete(key)`，自动按脚本隔离 key |
+| 日志 | 用 `sdk.log.info/warn/error/debug(msg)`，会进入执行记录 |
+| 当前时间 | 用 `sdk.now()` 获取平台时区时间；也可导入 `datetime` / `time` |
+| 系统配置和密钥 | 用 `sdk.config.get(key)`，不要把密钥硬编码在脚本里 |
+| 文件和系统命令 | 尽量避免；脚本与主进程同进程运行，误操作会影响后端服务 |
 
 ### SDK 速查表（与基座源码对齐）
 
@@ -689,18 +714,20 @@ typing, dataclasses, enum, uuid, hashlib, base64, urllib.parse
 | `update` | `(type: str, id: int, data: dict) -> dict` | 部分更新，`data` 传**裸业务字典**，SDK 内部自动包装 `{"data": data}` 提交，**禁止**手动再包一层 |
 | `update_many` | `(type: str, items: list[dict]) -> list[dict]` | 批量更新；每项传 `{id, data}`，或 `{id, 字段...}` 让 SDK 自动包装为 `data` |
 | `delete` | `(type: str, id: int) -> bool` | 失败返回 `False`，不抛异常 |
-| `query` | `(type: str, filters: dict = None, page: int = 1, page_size: int = 20) -> dict` | 返回 `{items, total, page, page_size}` |
+| `query` | `(type: str, filters: dict = None, page: int = 1, page_size: int = 20, order_by: str = None, order: str = "desc") -> dict` | 返回 `{items, total, page, page_size}` |
 
-**`filters` 语义（重要）**：内部转换为搜索词喂给 `DBService.get_db_list` 的 `search` 参数，是**字段包含式搜索**，**不是**结构化 WHERE。**不支持** `>=` `<` `in` `or` `between` 等操作符；多字段是 AND 关系。需要复杂条件请在脚本里二次过滤。
+**`filters` 语义（重要）**：结构化条件查询，直接对记录的 `data` JSON 字段做 WHERE，**支持** `eq` / `like` / `gte` / `lte` / `gt` / `lt` / `in` / `contains`。多字段是 AND 关系。字段必须在 db_meta schema 里标 `searchable`，且操作符要匹配字段的检索模式（exact/fuzzy/range/contains），否则后端报 400。
 
-**filters 类型处理规则**：
-| 值类型 | 行为 | 示例 |
+**filters 写法**：
+| 形式 | 含义 | 示例 |
 |--------|------|------|
-| `str` | 原样传递 | `{"title": "AI"}` → 搜索 `title:AI` |
-| `int` / `float` | 转字符串 | `{"score": 90}` → 搜索 `score:90` |
-| `bool` | 转小写字符串 | `{"distributed": False}` → 搜索 `distributed:false` |
-| `list` | 逗号拼接 | `{"tags": ["a","b"]}` → 搜索 `tags:a,b` |
-| `None` | **跳过**，不参与搜索 | `{"field": None}` → 该条件被忽略 |
+| `{field: 值}` | 精确等于（eq） | `{"status": "paid"}` |
+| `{field: {"op": 操作符, "value": 值}}` | 指定操作符 | `{"title": {"op": "like", "value": "公告"}}` |
+| `{field: [...]}` | 命中其一（in） | `{"status": ["paid", "pending"]}` |
+| `{field: bool}` | 精确等于（SDK 转 `"true"`/`"false"`） | `{"done": True}` |
+| `{field: None}` | **跳过**，不参与查询 | `{"field": None}` |
+
+范围/排序示例：`sdk.db.query("article", {"views": {"op": "gte", "value": 100}}, order_by="views", order="desc")`
 
 **上限**：`page_size` 内部 `min(page_size, 1000)`，超出静默截断。
 
@@ -957,10 +984,50 @@ def fetch_all(sdk, ctx):
 | `slug` | ✅ | URL 标识（route 模式的访问路径：`/api/x/{slug}/{path}`） |
 | `code` | ✅ | 完整 Python 代码 |
 | `mode` | ✅ | `event` / `route` / `scheduled` |
-| `triggers` | 否 | event 模式: `{"events": ["user.registered"]}`；scheduled 模式: `{"cron": "0 2 * * *"}` |
+| `triggers` | 否 | 当前主要作为 event/route 的管理端元数据保留。event 模式可写 `{"events": ["user.registered"]}`，route 模式可写路径/方法；scheduled 模式不需要写 `triggers`，cron 只读取代码中的 `@scheduled(...)` 装饰器，后端会清空 scheduled 的 trigger 元数据 |
 | `config` | 否 | `{"timeout": 30, "max_retries": 0}`；`timeout` 是**脚本整体超时**（默认 30s），与 `sdk.external_api` 的单次 HTTP timeout（默认 10s、硬上限 30s）是**两层独立机制**。多次外部调用串行场景务必上调到 120–300 |
 | `permission` | 否 | 仅 route 模式有效：`{"default": "public|login|admin", "roles": [...]}` |
 
+**Route 配置推荐写法：**
+
+```json
+{
+  "config": {
+    "timeout": 20,
+    "route_security": {
+      "auth_required": true,
+      "rate_limit_per_minute": 60,
+      "burst_limit": 10,
+      "max_body_size_kb": 256,
+      "timeout_ms": 15000,
+      "ip_allowlist": ["10.0.0.0/8"]
+    }
+  }
+}
+```
+
+当前后端兼容把这些字段直接写在 `config` 顶层，但为了避免混乱，文档统一按 `config.route_security` 说明。
+
+**Route 配置推荐写法：**
+
+```json
+{
+  "config": {
+    "timeout": 20,
+    "route_security": {
+      "auth_required": true,
+      "rate_limit_per_minute": 60,
+      "burst_limit": 10,
+      "max_body_size_kb": 256,
+      "timeout_ms": 15000,
+      "ip_allowlist": ["10.0.0.0/8"]
+    }
+  }
+}
+```
+
+当前后端兼容把这些字段直接写在 `config` 顶层，但为了避免混乱，文档统一按 `config.route_security` 说明。
+
 ### 权限配置（仅 route 模式）
 
 | 场景 | permission 值 |
@@ -984,17 +1051,48 @@ def fetch_all(sdk, ctx):
 | `page.updated` | `{page_id, changes}` |
 | `script.executed` | `{script_id, execution_id, status, duration_ms}` |
 
-### 访问路径
+### 访问路径与调度来源
 
 Route 模式脚本通过 `/api/x/{slug}/{path}` 访问：
 - slug 为 `order-api`，handler 为 `@route("GET /list")` → 访问 `GET /api/x/order-api/list`
 - slug 为 `health-check`，handler 为 `@route("GET /health")` → 访问 `GET /api/x/health-check/health`
 
+Scheduled 模式的 cron **写在代码装饰器里**：
+- `@scheduled("0 2 * * *")` → 每天凌晨 2 点执行
+- 当前引擎加载 scheduled handler 时直接读取装饰器里的 cron 表达式
+- scheduled 模式不需要触发器 cron 元数据；即使旧客户端传入也会被后端清空
+
+Event 模式同理：
+- `@on("user.registered")` 才是真正注册事件的来源
+- `triggers.events` 建议与代码保持一致，作为管理端元数据保存
+
+**Route 安全机制（必须考虑）**：
+
+所有 `/api/x/{slug}/{path}` 请求在进入脚本前会经过平台安全守卫：Route 总开关、HTTP method 白名单、IP 黑白名单、每分钟限流、10 秒突发限流、默认登录要求、请求体大小上限、执行超时上限。全局默认来自系统配置 `script_route_*`，单个脚本可在 `config.route_security` 覆盖。
+
+当前后端也兼容把 `auth_required`、`rate_limit_per_minute`、`burst_limit`、`max_body_size_kb`、`timeout_ms`、`ip_allowlist`、`ip_blocklist` 直接写在 `config` 顶层，但**推荐统一写在 `config.route_security` 下**：
+
+```json
+{
+  "timeout": 20,
+  "route_security": {
+    "auth_required": true,
+    "rate_limit_per_minute": 60,
+    "burst_limit": 10,
+    "max_body_size_kb": 256,
+    "timeout_ms": 15000,
+    "ip_allowlist": ["10.0.0.0/8"]
+  }
+}
+```
+
+公开 Route 接口不要关闭限流；涉及外部回调、支付、Webhook、AI 调用等高频/高成本接口时，必须显式设置请求体上限、限流和合理超时。
+
 ### 开发常见错误速查
 
 | 症状 | 原因 | 修复 |
 |------|------|------|
-| 脚本状态 error: "xxx 不在允许的模块列表" | import 了白名单之外的模块 | 只用白名单模块，HTTP 用 sdk.external_api |
+| 脚本状态 error: `ImportError` / `No module named ...` | 运行环境没有安装该依赖，或模块名写错 | 改用标准库 / SDK，或先把依赖加入后端运行环境 |
 | 脚本状态 error: "代码语法错误" | Python 语法问题 | 本地用 `python -c "import ast; ast.parse(open('x.py').read())"` 验证 |
 | 访问 /api/x/slug/path 返回 404 | slug 或 path 不匹配 | 确认 slug 和 @route 中的 path 拼写 |
 | 访问 /api/x/slug/path 返回 405 | HTTP 方法不匹配 | GET 请求但装饰器写了 POST |
@@ -1005,8 +1103,8 @@ Route 模式脚本通过 `/api/x/{slug}/{path}` 访问：
 | 拉取公开 HTTP 接口返回 403 | 注册表里配的 UA 不会被脚本复用 | 在脚本里显式 `headers={"User-Agent": "..."}` |
 | 多平台串行调用时脚本整体超时（但单次 HTTP 没报超时） | `config.timeout` 默认 30s，被先触发 | 提交脚本时把 `config.timeout` 调到 120–300 |
 | `AttributeError: 'DBModule' object has no attribute 'list'` | 文档老版本误写 `sdk.db.list` | 用 `sdk.db.query(type, filters, page, page_size)` |
-| `sdk.db.query` 加了 `>=` / `in` 等条件没生效 | filters 是字段包含搜索，不是结构化 WHERE | 在脚本中拉回数据后二次过滤 |
-| `sdk.db.query(filters={"done": True})` 返回 0 条 | boolean/list 类型需与索引格式对齐 | boolean 用 `True`/`False`（SDK 内部转 `"true"`/`"false"`），list 用实际列表；不要传字符串 `"true"` |
+| `sdk.db.query` 加了 `gte` / `in` 等条件报 400 | 该字段未标 searchable，或操作符与字段的检索模式不匹配 | 在 db_meta schema 给字段标对应 searchable 模式（range 才支持 gte/lte，exact/fuzzy 支持 eq/in） |
+| `sdk.db.query(filters={"done": True})` 返回 0 条 | 字段未标 searchable，或 boolean 字段未按 exact 模式配置 | 给字段标 `searchable`，boolean 传 `True`/`False`（SDK 内部转 `"true"`/`"false"`） |
 | `sdk.db.update` 报 schema 校验失败或字段丢失 | 第三个参数 `data` 已被 SDK 自动包装，禁止手动再包 `{"data": {...}}` | 直接传裸字典：`sdk.db.update("type", id, {"field": val})` |
 | `sdk.db.update_many` 后部分数据没更新 | 批量更新是一次事务，任意一条失败会整批回滚 | 先确认每项都有 `id`，且 `{id, data}` 中的 `data` 满足 schema |
 | `sdk.external_api.*(timeout=120)` 仍然 30s 超时 | 单次 HTTP timeout 硬上限 30s | 改造业务逻辑，把单次请求拆短；或改用分批拉取 |
@@ -1125,6 +1223,91 @@ Body:
 
 聊天型 Agent 默认 `spec.mode="chat"`，调用 `POST /api/agents/{id}/chat`。
 
+### Agent 用户自主选择模型
+
+Agent 支持把“主模型 + 备用模型”作为用户可选模型白名单暴露给页面。开启方式是在 Agent 的 `data.spec.model_selection` 中写入配置：
+
+```json
+{
+  "data": {
+    "schema_version": "agent.v3",
+    "spec": {
+      "model": "gpt-4.1",
+      "fallback_models": ["gpt-4.1-mini", "claude-3-5-sonnet"],
+      "model_selection": {
+        "user_selectable": true,
+        "on_invalid": "ignore"
+      }
+    }
+  }
+}
+```
+
+获取该 Agent 允许用户选择的模型列表：
+
+```
+GET /api/agents/{agent_id}/selectable-models
+```
+
+返回：
+
+```json
+{
+  "user_selectable": true,
+  "models": ["gpt-4.1", "gpt-4.1-mini", "claude-3-5-sonnet"]
+}
+```
+
+注意：
+
+- `models` 是 Agent 白名单，由 `spec.model` + `spec.fallback_models` 去重派生，不是供应商全量模型列表。
+- 未开启 `user_selectable` 时返回 `{ "user_selectable": false, "models": [] }`。
+- `on_invalid="ignore"` 表示传入非白名单模型时回落到主模型；`reject` 表示拒绝请求。
+- 页面端优先使用 `DraftGoAI.getSelectableModels(agentId)`，再把用户选中的模型作为 `options.model` 传给 `DraftGoAI.chat` 或 `DraftGoAI.images`。
+
+### Agent 结构化 JSON 输出
+
+Agent 需要稳定 JSON 返回时，不要只在提示词里口头要求；应配置 `data.spec.output_format`：
+
+```json
+{
+  "data": {
+    "schema_version": "agent.v3",
+    "spec": {
+      "model_id": 1,
+      "model": "gpt-4.1",
+      "output_format": {
+        "mode": "json",
+        "json": {
+          "strategy": "auto",
+          "schema_name": "agent_output",
+          "schema": {
+            "type": "object",
+            "properties": {
+              "answer": { "type": "string" },
+              "confidence": { "type": "number" }
+            },
+            "required": ["answer"],
+            "additionalProperties": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+字段规则：
+
+| 字段 | 说明 |
+|------|------|
+| `output_format.mode` | `native`（默认）或 `json` |
+| `output_format.json.strategy` | `auto` / `native` / `prompt`；推荐 `auto` |
+| `output_format.json.schema` | 可选 JSON Schema；有 schema 时优先尝试 `json_schema` |
+| `output_format.json.schema_name` | 传给 OpenAI 兼容 `response_format.json_schema.name` |
+
+模型资产可调用 `POST /api/aihub/{model_id}/test-response-format` 探测 `response_format` 支持情况，结果写回 `data.supports_response_format` 与 `data.supports_json_schema`。`strategy=auto` 会优先使用原生 `response_format`，遇到上游不支持时降级为提示词约束。流式 JSON 输出结束时会追加 `json.validation` SSE 事件，用于前端判断解析/Schema 校验是否通过。
+
 ### 创建图片生成型 Agent
 
 ```
@@ -1140,7 +1323,7 @@ Body:
       "mode": "image_generation",
       "model_id": 1,
       "model": "gpt-image-1",
-      "system_prompt_template": "统一生成商业海报风格，画面干净。",
+      "system_prompt_template": "统一生成商业海报，画面清晰。",
       "image_generation": {
         "n": 1,
         "size": "1024x1024",
@@ -1156,10 +1339,10 @@ Body:
 
 ```
 POST /api/agents/{agent_id}/images
-Body: {"prompt": "生成一张夏季饮品海报", "size": "1024x1024"}
+Body: {"prompt": "生成一张夏季饮品海报", "size": "1024x1024", "model": "gpt-image-1"}
 ```
 
-页面里使用 `DraftGoAI.images(agentId, prompt, options)`；不要把图片生成请求发到 `/chat`。
+页面里使用 `DraftGoAI.images(agentId, prompt, options)`；不要把图片生成请求发到 `/chat`。`options.model` 同样遵循 Agent 的用户选模型白名单。
 
 ### 给 Agent 绑定工具
 

package/resources/skill/push/SKILL.md

@@ -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 / docs / custom_scripts**（其余类型仍只更新）。
+支持创建的类型：**pages / nav / db_meta / aihub / external_apis / docs / doc_categories / custom_scripts**。
 
 ### 新建页面的标准流程
 
@@ -49,7 +49,10 @@ allowed-tools: Bash(python:*), Read, Glob
 | pages | `title`, `route` | route 不可重复 |
 | 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 |
 
 > **创建后必须以脚本回写的 index 为准**，不要手动猜 id。回写后建议 `git diff` 或重新读 index 确认 `id` 已落地。
@@ -85,7 +88,7 @@ allowed-tools: Bash(python:*), Read, Glob
 !python {{SKILL_SCRIPTS}}/draftgo_push.py aihub <aihub_id>
 ```
 
-读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送。
+读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/aihub` 创建，成功后回写新 `id`。
 
 ## 推送外部 API（"推送外部API" / "push external_apis"）
 
@@ -94,7 +97,7 @@ allowed-tools: Bash(python:*), Read, Glob
 !python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis <api_id>
 ```
 
-读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送。
+读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/external-apis` 创建，成功后回写新 `id`。创建最少需要 `code`、`name`、`base_url`。
 
 ## 推送系统配置（"推送系统配置" / "push system_config"）
 
@@ -149,7 +152,7 @@ users 涉及账号安全，**强制要求人工确认**：
 !python {{SKILL_SCRIPTS}}/draftgo_push.py doc_categories <category_id>
 ```
 
-读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送。
+读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/docs/categories` 创建，成功后回写新 `id`。
 
 ## 推送自定义脚本（"推送自定义脚本" / "push custom_scripts"）⚠️ 需二次确认