draftgo-cli 2.0.3 → 2.0.5

package/README.md

@@ -6,9 +6,29 @@
 
 ## 前置条件
 
-- Node.js 14+（运行 CLI）
+- Node.js >=20.19（运行 CLI）
 - Python 3.9+（运行 DraftGo init/sync 脚本；CLI 本身不需要）
 
+## DraftGo Next v3 基线
+
+DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
+
+数据库页面仍以 HTML 为核心，`dg-*` 标签是 shadcn/ui 在 DraftGo 页面运行时里的协议表达：AI 看到 `dg-button`、`dg-card`、`dg-form`、`dg-table` 等，必须理解为 shadcn 组件能力，而不是 daisyUI、Bootstrap 或自研组件库。CLI 分发的 skill 已把这条规则写入前端规范。
+
+已存在的 `draftgo init/update/status/doctor/map/check/connect/local-dev` 保持兼容；首批工作台命令如下：
+
+| 命令 | 说明 |
+|---|---|
+| `draftgo local up` | 启动 `draftgo local-dev` 生成的 `.draftgo/docker/docker-compose.yaml` 本地栈。 |
+| `draftgo local down` | 停止本地栈。 |
+| `draftgo local logs` | 查看本地栈日志，默认跟随 `app` 服务。 |
+| `draftgo local status` | 查看本地栈容器状态。 |
+| `draftgo dev` | 运行当前项目 `package.json` 中的 `scripts.dev`。 |
+| `draftgo build` | 运行当前项目 `package.json` 中的 `scripts.build`。 |
+| `draftgo check` | 本地资源闭环检查，作为 push 前质量门禁。 |
+| `draftgo pull` | 包装随 skill 分发的 `draftgo_pull.py`，默认 `--all` 拉取资源。 |
+| `draftgo push` | 包装随 skill 分发的 `draftgo_push.py`，推送页面、导航、DB meta 等资源。 |
+
 ## 安装
 
 ```bash
@@ -39,6 +59,8 @@ draftgo init all                         # 所有支持的工具
 | `draftgo uninstall [target]...` | 移除指定 AI 工具的 skill 目录（含入口文件 + 子技能 + scripts）。加 `--purge` 会连 `.draftgo/` 一起删。 |
 | `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
 | `draftgo doctor` | 诊断：Python 是否可用、检测到哪些 AI 工具、各入口状态。 |
+| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、入口引用，帮助 AI 快速进入项目。 |
+| `draftgo check` | 本地闭环体检：检查 route、入口绑定、文件存在性、重复路由和疑似 mock/伪功能风险。 |
 | `draftgo list-targets` | 列出支持的 AI 工具名。 |
 | `draftgo --version` | 打印 CLI 版本。 |
 | `draftgo --help` | 查看帮助。 |
@@ -49,6 +71,8 @@ draftgo init all                         # 所有支持的工具
 - `--force`：`init/update` 时强制覆盖已存在的 AI 工具 skill 目录。
 - `--skip-update-check`：`update` 时不去 npm 查最新版，直接用当前 CLI 执行。
 - `--purge`：`uninstall` 时连 `.draftgo/`（含 config / 日志 / 本地缓存）一起删。
+- `--output json`：`map/check` 输出机器可读 JSON。
+- `--strict`：`check` 将提醒项也视为失败。
 
 可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭自动升级检查（离线、CI 等场景）。
 
@@ -76,6 +100,12 @@ CLI 随包分发的 DraftGo skill 会同步基座 API 约定。集合写入统
 
 动态 DB SDK 也提供 `sdk.db.create_many(...)` 与 `sdk.db.update_many(...)`，用于脚本内批量写入。
 
+AIHub Agent 用户选模型约定：
+
+- 管理端在 Agent 的 `data.spec.model_selection.user_selectable=true` 后，页面可调用 `DraftGoAI.getSelectableModels(agentId)` 获取 `{ user_selectable, models }`。
+- `models` 是该 Agent 的主模型 + 备用模型白名单，不是供应商全量模型列表。
+- 调用 `DraftGoAI.chat(...)` 或 `DraftGoAI.images(...)` 时，可在 `options.model` 中传入用户选择的模型；后端会继续按 Agent 白名单校验。
+
 ## 自动识别的依据
 
 | AI 工具 | 探测信号（任一命中即视为在用） |
@@ -141,7 +171,7 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 - `.draftgo/lessons/` 统一记录开发过程中的阻碍、踩坑、框架运行时问题、基座能力局限和可复用经验。
 - 文件按 `YYYY-MM-DD-主题关键词.md` 命名，便于后续回顾和沉淀为开发规范。
 
-**前端审美方向**：现代工艺 + 艺术风 + 用户体验三个方向，不立细则只立锚点（参考 Linear / Vercel / Apple HIG / Notion）。
+**前端 UI 能力调用**：DraftGo 平台前端默认采用 React + shadcn/ui + Tailwind CSS；数据库 HTML 页面使用 `dg-*` 表达 shadcn 组件能力，`dg-*` 不是自研 UI 协议。若本地 Agent 环境存在 shadcn / 前端 UI 相关 Skills，前端界面开发时优先调用。DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法，并在规范中声明 shadcn/Tailwind 已引入。
 
 完整规范见各 AI 工具自身 skill 目录下的 `rules/dev-workflow.md`，例如 `.claude/skills/draftgo/rules/dev-workflow.md`。
 
@@ -156,7 +186,7 @@ CLI v2.0.3 补充操作型页面的空间模型，重点解决后台管理 / 表
 - **工作台布局原则**：后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先让页面根容器占满可用视口 / iframe 内容区。
 - **稳定控制区**：顶部筛选、搜索、标题操作区保持稳定高度，底部分页、批量操作栏、保存栏等流程控制区保持在工作区底部或稳定位置。
 - **数据区承接剩余空间**：主体数据区使用 `flex:1; min-height:0; overflow:auto` 等结构承接剩余空间，数据少时保留工作区空白，数据多时优先让数据区内部滚动。
-- **数据表规则同步**：`data-table.md` 新增工作台空间模型和 CSS 骨架参考，避免分页跟随 1-2 条数据上浮。
+- **工作台结构同步**：`frontend.md` 补充操作型页面的空间方法，避免分页跟随 1-2 条数据上浮。
 
 ---
 
@@ -210,16 +240,16 @@ CLI v1.6.2 进一步降低开发流程摩擦：保留真实功能闭环、页面
 
 ---
 
-## v1.6.1 升级要点（前端规则去模板化）
+## v1.6.1 升级要点（前端规则收敛）
 
-CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，更主动地根据页面目标、业务复杂度和用户体验做设计判断。
+CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，根据页面目标和业务复杂度做实现判断。
 
 **核心变化：**
 
-- **GSAP 优先体验原则**：开发前端页面时优先考虑使用 GSAP 提升体验，不再用固定场景清单限制是否引入。
-- **数据表规则改为参考**：数据列表 / 表格规范从“必须按模板实现”调整为参考指南，避免无差别套搜索、高级筛选、列配置、分页。
-- **空态与圆角更灵活**：空态保留稳定布局要求，写法不再唯一；圆角默认保持系统一致，但允许按品牌感、卡片层级和营销视觉适度放开。
-- **审美方向更开放**：保留现代工艺、艺术风、用户体验三轴，但减少反例式限制，让 AI 可以根据项目气质探索更鲜明的视觉语言。
+- **前端规则收敛**：DraftGo 规则关注本地资源、运行时 API、入口绑定、真实数据和验证方法。
+- **GSAP 资源改为按需使用**：本地 GSAP 资源仍可用，但 CLI 不再给出使用场景判断。
+- **表格规则去模板化**：不再要求固定搜索、高级筛选、列配置、分页结构，具体界面由 Agent 和本地 UI Skills 判断。
+- **状态规则保留方法约束**：空态、加载态、错误态、成功态必须存在，但具体呈现不由 CLI 指定。
 
 ---
 
@@ -288,12 +318,6 @@ design:
   modules:
     - name: "模块名"
       role: "这个模块在系统里的定位（核心/辅助/基座）"
-  style:
-    personality: "系统说话像谁"
-    keywords: ["设计关键词"]
-    do: ["正面指引"]
-    dont: ["禁区"]
-
 decisions:
   - id: D001
     date: 2026-05-17

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "draftgo-cli",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"
   },
   "main": "src/index.js",
   "engines": {
-    "node": ">=14"
+    "node": ">=20.19"
   },
   "files": [
     "bin/",

package/resources/skill/SKILL.md

@@ -6,6 +6,9 @@ version: 1.0.0
 
 # DraftGo 开发助手
 
+> **【DraftGo 开发追求】**
+> 使用 DraftGo-CLI 开发的项目，默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。AI 应快速读懂现有资源，交付真实功能闭环，并让后续修改者能继续迭代。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。
+>
 > **【开发分级 — 最高优先级】**
 > 任何开发对话开始时，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 判断任务级别**，再执行对应流程：
 > - **小修** → 直接定位 → 改 → check → push。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；仍需写 changelog。
@@ -18,6 +21,9 @@ version: 1.0.0
 > **【开发任务硬性流程】**
 > 任何"开发 / 修改 / 新建 / 修复 / 重构 / 完善 / 优化"指令，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做任务分级和用户意图翻译**。标准功能 / 高风险任务追问用户时必须带上 AI 自己的意图推测（推测 + 2-3 个选项 + 推荐项），不能空着问；能合理推断的轻功能不因模板追问拖慢。前端开发按任务规模读取 `{{SKILL_DIR}}/rules/frontend.md` 的相关规则。
 >
+> **【真实可用默认原则】**
+> 除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都必须默认按真实可用、可验证、可闭环处理。禁止用前端假数据、静态卡片、无效按钮或伪交互充当功能完成。若平台能力、外部依赖或通用动态 DB 都无法支撑该功能，不要继续编写伪功能；必须向用户说明阻塞原因并写入 `.draftgo/lessons/`。
+>
 > **【更新日志硬性步骤】**
 > 每次完成任何开发 / 修复 / 修改 / 完善 / 删除 / 重构操作后，必须立即写更新日志到 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。这是强制步骤，不得跳过。
 >
@@ -29,6 +35,9 @@ version: 1.0.0
 >
 > **【页面绑定提醒】**
 > 新增页面后必须处理入口绑定：导航栏、首页模块、后台菜单、相关页面按钮至少一处可点击进入；若用户明确要求隐藏页 / 草稿页，才可不绑定，但必须说明原因。只创建页面文件、不能从正常路径进入，不算完成。
+>
+> **【CLI 辅助工具】**
+> 进入陌生项目、标准功能或多页面任务前，优先运行 `draftgo map` 快速读取页面 / 导航 / DB / 脚本 / AIHub 资源地图；涉及页面、导航、DB 或脚本改动的任务收尾时，运行 `draftgo check` 辅助发现未绑定入口、缺文件、重复路由和疑似 mock 风险。`draftgo check` 是辅助证据，不替代浏览器实测和 push 回读。
 
 ## 命令路由
 
@@ -40,6 +49,8 @@ version: 1.0.0
 | 从云端拉取 / 刷新本地数据 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
 | 推送本地修改到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
 | 构建 / 查看 / 更新系统 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
+| 查看项目资源地图 / `draftgo map` | 直接运行 CLI，快速读取本地页面、导航、DB、脚本、AIHub、入口引用 |
+| 闭环体检 / `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 开发页面时，凡是需要按钮、卡片、表单、表格、弹窗、Tabs、Dropdown、Sheet、Tooltip、Toast、Skeleton 等 shadcn 能力，优先使用对应 `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 以适配主题切换
 
 ## 主题切换适配
@@ -116,9 +137,9 @@ DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
 | 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` |
 
 **内置配色方案：**
-- `dark-gray-white` 深灰白（默认）— 冷调深灰，干净利落
-- `deep-blue-white` 深蓝白 — 专业稳重，企业风
-- `orange-white` 橙白 — 温暖醒目，创意风
+- `dark-gray-white`
+- `deep-blue-white`
+- `orange-white`
 
 **颜色 Token（优先使用）：**
 - `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
@@ -179,7 +200,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 +212,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 /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 · 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（回溯/撤销） |
 | ⚠️ 二次密码 | 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 +271,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 +295,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。
 ```
 
 **批量更新动态数据：**
@@ -628,7 +653,7 @@ def cleanup(sdk, ctx):
 
 ```python
 # ❌ 这些写法都会报错
-from draftgo import route       # 'draftgo' 不在白名单
+from draftgo import route       # 没有 draftgo 这个内置模块
 from sdk import route           # 可以但多余，直接用就行
 import sdk                      # 可以但多余
 
@@ -656,24 +681,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 +712,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 +982,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 +1049,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 +1101,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 +1221,48 @@ 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
 
 ```
@@ -1140,7 +1278,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 +1294,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 绑定工具