draftgo-cli 2.0.9 → 3.0.1

package/resources/skill/SKILL.md

@@ -1,1408 +1,104 @@
----
+---
 name: draftgo
 description: Use this skill when the user is developing, maintaining, or debugging a DraftGo-based application. Activates for tasks involving DraftGo pages, navigation, API calls, roles, DB meta, or any DraftGo-specific development work. ALSO activates when user says "推送", "push", "同步", "sync", "推送到云端", "同步到云端", "push to server", "上传页面", "上传导航", "push pages", "push nav", "push db_meta" — route to /draftgo push skill immediately, do NOT attempt manual API calls.
-version: 1.0.0
+version: 2.0.0
 ---
 
 # DraftGo 开发助手
 
-> **【DraftGo 开发追求】**
-> 使用 DraftGo-CLI 开发的项目，默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。AI 应快速读懂现有资源，优先交付真实落地闭环、高可用的实现，并让后续修改者能继续迭代。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。
->
-> **【开发分级 — 最高优先级】**
-> 任何开发对话开始时，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 判断任务级别**，再执行对应流程：
-> - **小修** → 直接定位 → 改 → 轻量证据。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；changelog / check / push 按影响选择。
-> - **轻功能** → 范围复述 → 直接做 → 凭证据闭环。用于简单页面能力、单入口交互、小型数据联动，不强制 Task。
-> - **标准功能** → 轻量确认 → 内部短计划 → 执行闭环。若 `.draftgo/story.yaml` 存在则静默加载；不存在时不阻塞开发，但应在完成后提醒补 Story；只有跨资源、多页面协作、并行或高风险时才落 Task。
-> - **高风险** → 完整 Story / 计划 / 验证 / 人工确认。无 `.draftgo/story.yaml` 时必须先构建 Story。
->
-> **开发中发现请求与已有 Story 冲突时，必须显式提示开发者，不可静默执行。** 详见 `{{SKILL_DIR}}/story/SKILL.md` 冲突检测章节。
->
-> **【开发任务硬性流程】**
-> 任何"开发 / 修改 / 新建 / 修复 / 重构 / 完善 / 优化"指令，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做任务分级和用户意图翻译**。标准功能 / 高风险任务追问用户时必须带上 AI 自己的意图推测（推测 + 2-3 个选项 + 推荐项），不能空着问；能合理推断的轻功能不因模板追问拖慢。前端开发按任务规模读取 `{{SKILL_DIR}}/rules/frontend.md` 的相关规则。
->
-> **【真实可用默认原则】**
-> 除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都优先考虑真实落地闭环、高可用。禁止用前端假数据、静态卡片、无效按钮或伪交互充当功能完成。若平台能力、外部依赖或通用动态 DB 都无法支撑该功能，不要继续编写伪功能；向用户说明阻塞原因，并在确有复用价值时写入 `.draftgo/lessons/`。
->
-> **【更新日志记录】**
-> changelog 用于让后续 Agent 接手；影响可见功能、跨资源、已 push、已发布或用户明确要求记录时写入 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。纯小修、探索、未形成有效改动时可跳过。
->
-> **【任务标记】**
-> 只有已创建 Task 文档的任务需要维护标记。跨资源、多页面协作、并行开发或高风险任务完成一个阶段后，更新 `.draftgo/Task/<file>.md` 中的 ⬜ → ✅ 标记和证据摘要；小修、轻功能和普通标准功能可用内部短计划，不创建 Task。
->
-> **【双端覆盖提醒】**
-> 开发业务功能时，优先从完整用户路径链路思考：用户从官网 / 导航 / 首页入口进入，点击到目标页面，完成浏览 / 搜索 / 提交 / 管理等操作，再获得真实反馈。围绕真实落地闭环、高可用判断是否需要对应管理侧页面（后台 CRUD / 配置 / 审核）和同一份真实数据，避免只做静态展示页。
->
-> **【页面绑定提醒】**
-> 新增页面后必须处理入口绑定：导航栏、首页模块、后台菜单、相关页面按钮至少一处可点击进入；若用户明确要求隐藏页 / 草稿页，才可不绑定，但必须说明原因。只创建页面文件、不能从正常路径进入，不算完成。
->
-> **【CLI 辅助工具】**
-> 资源关系不清、进入陌生项目、多页面任务或用户描述模糊时，优先运行 `draftgo map` 快速读取页面 / 导航 / DB / 脚本 / AIHub / 外部 API / 文档 / 系统配置资源地图；目标文件清楚的小修可跳过。涉及页面、导航、DB 或脚本改动时，可用 `draftgo check` 辅助发现未绑定入口、缺文件、重复路由和疑似 mock 风险。验证优先用文件回读、静态检查、与改动匹配的轻量证据和必要的 push 输出闭环。
-
-## 命令路由
-
-**不要在此 Skill 中直接执行任何操作。** 根据用户意图路由到对应子命令：
-
-| 用户意图 | 执行 |
-|---|---|
-| 初始化项目 / 连接服务器 / `/draftgo init` | 调用 `/draftgo init` Skill |
-| 从云端拉取 / 刷新本地数据 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
-| 推送本地修改到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
-| 构建 / 查看 / 更新系统 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
-| 查看项目资源地图 / `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 文档时同步打 ✅。 |
+> 默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。优先交付真实落地闭环；禁止假数据/静态卡片/伪功能充当完成。若本地 Agent 存在前端 UI Skills，前端开发时优先调用。
 
 ## 开发前置检查
 
-进行任何开发任务前，先确认 `.draftgo/config.json` 存在：
-
-```
-!test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
-```
-
-存在后，从 `.draftgo/config.json` 读取服务器地址和 token。
-
-开发规范读取顺序（按任务规模渐进读取）：
-1. `{{SKILL_DIR}}/rules/dev-workflow.md` — 开发分级与执行流程（小修 / 轻功能 / 标准功能 / 高风险）
-2. `{{SKILL_DIR}}/rules/frontend.md` — 前端技术规范（前端任务按需读取；小修可先只读相关段落）
-3. `{{SKILL_DIR}}/rules/debugging-syntax.md` — 排错指南（页面静默失效、脚本复杂或 console 报错时读取）
-4. `{{SKILL_DIR}}/rules/parallel.md` — 并行开发协议（标准功能 / 高风险且任务数足够、资源互不冲突时读取）
-
-## 架构认知（必读）
-
-**DraftGo 不是传统 SPA，是"数据库驱动的页面资产运行时"：**
-- 壳层（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
-- 前端：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-*`。
-
-## 连接信息
-
-- 服务器地址与 Token：存储于 `.draftgo/config.json`（已加入 .gitignore）
-- 运行 `/draftgo init` 时写入
-
-## 开发规范
-
-→ 前端页面开发：读取 `{{SKILL_DIR}}/rules/frontend.md`
-→ 页面排错指南：读取 `{{SKILL_DIR}}/rules/debugging-syntax.md`（页面功能不执行时必读！）
-- 任何开发，必读！
-
-## 开发禁区（违反必报错）
-
-- ❌ 禁止境外 CDN（googleapis/jsdelivr/cdnjs/unpkg）→ ✅ 允许国内镜像（npmmirror.com/staticfile.net）
-- ❌ 禁止 `App()` 写法（App 是对象不是函数）→ ✅ 正确：`const App = window.parent?.App`
-- ❌ 禁止 `const App = () => window.parent?.App` → ✅ 去掉箭头函数
-- ❌ 禁止 `window.location.search` 读参数 → ✅ 用 `window.__DG_ROUTE_CONTEXT__.query`
-- ❌ 禁止 `App?.user?.role` 判断管理员 → `App.user` 不存在！✅ 用 `App.isAdmin` 或 `App.currentUser?.role_code`
-- ❌ 禁止 `navigate('/login')` 退出 → ✅ 用 `window.location.href = '/login'`
-- ❌ 禁止页面内 `window.location.href = ...` 跳转 → 页面运行在 iframe 中，直接赋值只跳 iframe 自身！✅ 所有导航跳转用 `window.parent.location.href = ...`
-- ❌ 禁止 `window.alert/confirm/prompt` → ✅ 用 `App.toast()` / `App.confirm()` / `App.showModal()`
-  - `App.showSuccess(msg)` 成功提示（绿色 3s）
-  - `App.showError(msg)` 错误提示（红色 4s）
-  - `App.showWarning(msg)` 警告提示（黄色 3s）
-  - `App.showInfo(msg)` 信息提示（蓝色 3s）
-  - `App.toast(msg, type)` 通用方法 — type: success/error/warning/info
-  - `App.confirm(msg, title?)` 确认弹窗 — 返回 Promise\<boolean\>
-  - `App.showModal(msg, title?)` 信息模态框 — 替代 alert()
-  - `App.showLoading()` / `App.hideLoading()` — 全局 loading
-  - `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 以适配主题切换
-
-## 主题切换适配
-
-DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
-
-**概念分层：**
-| 概念 | 存储键 | 取值 |
-|---|---|---|
-| 显示模式 | `dg_theme` | `'light'` \| `'dark'` \| `'system'` |
-| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'warm-retro'` \| `'mint-blue'` \| `'pine-green'` \| `'custom'` |
-
-**内置配色方案：**
-- `dark-gray-white`
-- `deep-blue-white`
-- `warm-retro`
-- `mint-blue`
-- `pine-green`
-
-**颜色 Token（优先使用）：**
-- `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
-- `--dg-text-primary` / `--dg-text-secondary` / `--dg-text-muted` — 文字层级
-- `--dg-accent` / `--dg-accent-hover` / `--dg-accent-subtle` — 主题色
-- `--dg-border` / `--dg-success` / `--dg-error` / `--dg-warning` — 功能色
-
-**App API 切换配色：**
-```javascript
-App.setColorScheme('deep-blue-white');              // 切换为预设方案
-App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
+```bash
+# 确认已初始化
+test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 ```
 
-**硬编码颜色的场景（允许但需注意）：**
-- 品牌色（如 Logo 固定色）
-- 数据可视化图表（需保证对比度）
-- 第三方组件库强制要求
-
-**硬编码时的要求：**
-- 同时提供亮色/暗色两套值，通过 `[data-theme="dark"]` 选择器切换
-- 确保对比度符合 WCAG AA 标准（文字至少 4.5:1）
-
-## 本地开发流程
-
-**原则：有功能修改就读本地数据，自主决策是否调用 API 完成高质量修改。**
+服务器地址和 Token 从 `.draftgo/config.json` 读取。
 
-1. **开发时**：读写 `.draftgo/` 本地文件
-   - 查元数据：读 `index.json`
-   - 查/改 HTML：按 `html_file` 字段路径读对应 `.html` 文件
-   - **新建资源**：在对应 `index.json` 追加一条**不带 `id`** 的记录 + 写好内容文件（html/md/代码），push 时自动 `POST` 创建并回写真实 id（见下方"新建资源"）
-2. **修改后**：运行推送脚本推送到服务器（见下方"推送规范"）
-3. **同步成功**：本地与服务器数据一致
-
-**本地数据目录（均在 `.draftgo/` 下）：**
+## 命令路由
 
-| 目录 | 内容 |
+| 用户意图 | 路由 |
 |---|---|
-| pages/ | index.json（无 html）+ 若干 .html |
-| navigations/ | index.json（无 html）+ 若干 .html |
-| roles/ | index.json |
-| users/ | index.json |
-| db_meta/ | index.json |
-| aihub/ | index.json |
-| external_apis/ | index.json（已注册的外部 API 元信息，`auth_config` 已脱敏） |
-| docs/articles/ | index.json（无 content）+ 若干 .md（文章正文） |
-| doc_categories/ | index.json（文档分类，含 parent_id 树关系） |
-| custom_scripts/ | index.json（无 code）+ 若干 .py / .js / .ts / .sh / .go（脚本代码，按 language 落到对应扩展名） |
-| system_config/ | index.json |
-| changelog.md | 更新日志（单文件，按日期分节） |
-| lessons/ | 开发经验与问题记录（按 `YYYY-MM-DD-主题.md` 命名） |
-| Task/ | YYYY-MM-DD-\<topic\>.md（每个开发任务一个文件，含需求纪要 / 设计 / 任务清单 / ⬜🟡✅❌⏸ 标记 / 完成回顾） |
+| 初始化项目 / `/draftgo init` | 调用 `/draftgo init` Skill |
+| 从云端拉取 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
+| 推送到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
+| 构建 / 查看 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
+| 查看资源地图 / `draftgo map` | 直接运行 CLI |
+| 闭环体检 / `draftgo check` | 直接运行 CLI |
+| 任何开发 / 修改 / 新建 / 修复 / 重构任务 | ↓ 见开发任务路由 |
 
-## 数据库 Schema（关键字段）
+## 开发任务路由（按任务规模读取）
 
-| 表 | 关键字段 | 说明 |
-|---|---|---|
-| `page` | `id`, `title`, `route`, `permission`, `value` (JSON: `{html: "..."}`) | value.html 存页面完整 HTML |
-| `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,...}}}`；`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 |
-| `custom_script` | `id`, `name`, `slug`, `code`, `mode`, `status`, `config` (JSON), `triggers` (JSON), `permission` (JSON: `{default, roles}`) | 自定义服务定义，支持 event/route/scheduled 三种模式 |
+**第一步：必读** → `{{SKILL_DIR}}/rules/dev-workflow.md`（分级：小修 / 轻功能 / 标准功能 / 高风险）
 
-## API 速查与示例
-
-| 模块 | 端点 |
+| 任务类型 | 读取 |
 |---|---|
-| 认证 | 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 · 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/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/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/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, /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} |
-
-### 统一响应信封
+| 所有开发任务 | `rules/dev-workflow.md` — 分级与执行流程 |
+| 前端页面开发 | `rules/frontend.md` — 前端规范（小修可只读相关段落） |
+| 页面功能不执行 / 报错 | `rules/debugging-syntax.md` — 排错指南（必读） |
+| 标准功能 / 高风险并行任务 | `rules/parallel.md` — 并行协议 |
+| 不了解项目结构 | 先运行 `draftgo map` |
+| 标准功能 / 高风险 · 意图模糊 | `practices/dev-declaration.md` — 开发声明协议 |
 
-所有 API 端点统一返回信封格式：
+## 快速决策树
 
-```json
-{"code": 200, "data": <实际载荷>, "message": "success"}
 ```
-
-**例外（不使用信封）：**
-- `POST /api/v1/chat/completions` — OpenAI 兼容格式（SSE 流或 OpenAI JSON）
-- `GET /api/v1/models` — OpenAI 兼容格式 `{"object":"list","data":[...]}`
-- `POST /api/external-apis/call/{code}` — 代理透传上游原始响应
-- `POST /api/external-apis/{id}/test` — 返回 `{ok, status_code, duration_ms, headers, body, error}`
-- `ANY /api/x/{slug}/{path}` — 自定义脚本运行时，响应格式由脚本决定
-
-**错误响应格式：**
-```json
-{"code": 400, "data": null, "message": "错误描述"}
+要开发什么？
+├── 页面 / 导航 / 交互      → 读 rules/frontend.md
+├── 数据结构 / 动态 DB      → 读 specs/data.md
+├── API 速查               → quickref/api-endpoints.md
+├── App 方法忘了            → quickref/app-api.md
+├── dg-* 组件用法           → quickref/dg-components.md
+├── 了解平台架构            → core/architecture.md
+├── 选择开发方案            → core/modules.md
+└── 查开发禁区             → specs/security.md
 ```
 
-**提取数据的通用逻辑（CLI pull 脚本已内置）：**
-1. 响应一定有 `.data` 字段 → 取 `data` 即为业务载荷
-2. 如果 `data` 为 dict 且含 `items` → 分页列表，取 `data.items`
-3. 如果 `data` 为 list → 直接使用
-
-**前端页面内的权威规则以 `{{SKILL_DIR}}/rules/frontend.md` 为准：`App.get/post/put/patch/delete` 原样返回后端信封，不做剥壳；页面代码必须检查 `res.code`，再从 `res.data` 取业务载荷。** SAT / CLI 脚本直接调 API 时也统一取响应信封里的 `.data`。
-
-### 高频 API 示例
-
-**创建页面（需 admin）：**
-```
-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` 从当前安装包内置模板覆盖重置。
-Response: { "code": 200, "data": { "id": 123, "title": "新页面", "route": "/new", ... }, "message": "success" }
-```
-
-**更新页面 HTML（需 admin）：**
-```
-PUT /api/pages/123
-Body: { "value": {"html": "<html>更新后...</html>"} }
-```
-
-**重置系统页面（需 admin）：**
-```
-POST /api/pages/123/reset-system
-Body: 空
-说明：从 backend/init/pages/ 重新加载该页面
-```
-
-**创建动态数据（普通用户自动绑定 userid）：**
-```
-POST /api/db/patient
-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。
-```
-
-**批量更新动态数据：**
-```
-PATCH /api/db/patient/batch
-Body: [
-  { "id": 456, "data": {"name": "张三", "age": 31} },
-  { "id": 457, "data": {"name": "李四", "age": 28}, "status": 1 }
-]
-Response: { "code": 200, "data": [{ "id": 456 }, { "id": 457 }], "message": "success" }
-说明：批量更新是一次事务；任意一条权限/schema/存在性校验失败，整批不提交。`data` 是完整业务 JSON 替换，不是字段级 merge。
-```
-
-**调用外部 API（页面里）：**
-```javascript
-// 在页面 HTML 里：壳层会自动注入认证、做参数校验、写日志
-const r = await App.callApi('weather-now', {
-  path_params: { city: 'beijing' },   // 替换 path 模板里的 {city}
-  query_params: { unit: 'metric' },   // ?unit=metric
-  // body: { ... },                    // POST/PUT/PATCH 才生效
-  // headers: { 'X-Trace': 't1' },     // 不会覆盖后端注入的认证头
-});
-if (r.status_code >= 200 && r.status_code < 300) {
-  console.log(r.body);  // JSON 自动解析
-} else {
-  App.showError(`上游返回 ${r.status_code}`);
-}
-```
-- 不要在页面里写 API Key / Bearer Token，由管理员在「外部 API」管理页注册即可
-- API code 不知道时先 `await App.listApis()` 查询
-- `r.error` 仅在代理层错误时（超时 / 网络 / 校验失败）非空；上游业务错误请看 `r.status_code` + `r.body`
-
-## 用自然语言注册/管理外部 API（SAT 直连管理端）
-
-> 当用户说"帮我接入和风天气"、"注册一个 OpenAI 兼容接口"、"把这个 API 加进来"等，**走管理端 API 注册**，不要让用户去后台手动配置。
-
-### 1. 先查本地缓存
-
-读 `.draftgo/external_apis/index.json` 确认是否已注册过相同 `code`。
-
-### 2. 调用管理端 API（用 SAT，需 admin）
-
-读 `.draftgo/config.json` 拿到 `server` + `token`，按下面字段构造 payload，调用 `POST /api/external-apis`：
-
-```json
-{
-  "code": "weather-now",
-  "name": "和风天气-实时",
-  "base_url": "https://devapi.qweather.com",
-  "method": "GET",
-  "path": "/v7/weather/now",
-  "headers": {},
-  "auth_type": "api_key_query",
-  "auth_config": { "name": "key", "value": "用户提供的 KEY" },
-  "timeout_ms": 30000,
-  "permission": { "default": "login", "roles": [] },
-  "param_schema": {
-    "query": {
-      "type": "object",
-      "properties": { "location": { "type": "string" } },
-      "required": ["location"]
-    }
-  },
-  "tags": ["weather"],
-  "description": "实时天气查询"
-}
-```
-
-**字段约定：**
-- `auth_type`：`none` / `api_key_header` / `api_key_query` / `bearer` / `basic`
-  - `api_key_header` / `api_key_query`：`auth_config = {name, value}`
-  - `bearer`：`auth_config = {token}`
-  - `basic`：`auth_config = {username, password}`
-- `permission.default`：`public`（匿名）/ `login`（登录用户）/ `deny`（仅指定角色）
-- `param_schema.{path,query,body}`：均为 JSON Schema Draft 2020-12，可省略
-- `path` 支持 `{var}` 模板，对应 `param_schema.path` 中字段
-- 认证字段由后端 AES-256-GCM 加密落库；后续 GET 详情会返回脱敏值
-
-### 3. 注册后立即测试 + 写更新日志
-
-```
-POST /api/external-apis/{id}/test
-Body: { "path_params": {...}, "query_params": {...}, "body": ... }
-返回: { ok, status_code, duration_ms, error }
-```
-
-测试通过后写更新日志：`[新增] 注册外部 API <code>`
-
-### 4. 常见管理操作
-
-| 用户意图 | API 调用 |
-|---|---|
-| 列出所有 API | `GET /api/external-apis?page=1&page_size=50` |
-| 改名/换地址/换 KEY | `PUT /api/external-apis/{id}`（仅传需要改的字段；不传 `auth_config` 则保留原 KEY） |
-| 启用/禁用 | `PATCH /api/external-apis/{id}/status` body `{status:"active|disabled"}` |
-| 删除 | `DELETE /api/external-apis/{id}` |
-| 查看调用日志 | `GET /api/external-apis/logs?api_code=<code>&page=1&page_size=50` |
-| 清理日志 | `POST /api/external-apis/logs/cleanup?retention_days=30` |
-| 列出已用标签 | `GET /api/external-apis/tags` |
-
-### 5. 用户场景对话样例
-
-- 用户："给我接一个查天气的 API，KEY 是 xxx"
-  → AI 询问：服务商？请求方法？需要哪些参数？  
-  → AI 调用 `POST /api/external-apis` 注册 → 调用 `/test` 验证 → 告知 code  
-  → 用户在页面里直接 `App.callApi('weather-now', { query_params: { location: 'beijing' } })`
-
-- 用户："禁用 weather-now 这个接口"  
-  → AI 先 `GET /api/external-apis?keyword=weather-now` 拿 id → `PATCH /{id}/status` → 写更新日志
-
-## URL 参数读取
-
-页面运行在 `iframe.srcdoc` 中，`window.location.search` 不可靠。框架通过 `<script data-dg-route-bridge>` 注入路由上下文。
+## 连接信息
 
-```javascript
-// 标准三阶回落（推荐）
-const routeContext =
-  window.__DG_ROUTE_CONTEXT__
-  || window.__DG_GET_ROUTE_CONTEXT__?.()
-  || window.parent?.App?.getCurrentRouteContext?.()
-  || { query: {} };
-const query = routeContext.query || {};
+- 存储于 `.draftgo/config.json`（已加入 .gitignore）
+- 运行 `/draftgo init` 时写入
 
-// 使用示例
-const patientId = query.patientId;  // "42"
-const visitId = query.visitId;      // "7"
-```
+## 核心原则（硬性）
 
-禁止：`new URLSearchParams(window.location.search)` — iframe 中取不到壳层 URL。
+- **开发分级**：任何任务先读 `rules/dev-workflow.md` 分级，再执行
+- **真实闭环**：不用假数据/伪交互充当完成；无法实现则停止并说明
+- **入口绑定**：新增页面必须绑定导航/首页/菜单至少一处
+- **dg-* = shadcn**：`dg-*` 是 shadcn 的 HTML 协议表达，不是其他 UI 库
+- **Story 冲突**：发现与 `.draftgo/story.yaml` 冲突必须显式提示，不可静默执行
+- **changelog**：影响可见功能/跨资源/已 push 时写入 `.draftgo/changelog.md`
 
-## 常见问题排查
+## 本地数据目录
 
-| 问题 | 排查步骤 |
+| 目录 | 内容 |
 |---|---|
-| 同步失败 | 1. 检查 `.draftgo/config.json` token 是否有效<br>2. 检查服务器连接<br>3. 查看 `.draftgo/changelog.md` 最近操作记录 |
-| 页面加载空白 | 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。 |
-| 颜色不生效 | 检查是否用了 `var(--dg-*)` 而非硬编码 hex/rgb |
-| URL 参数读取失败 | 检查是否用了 `window.__DG_ROUTE_CONTEXT__.query` 而非 `window.location.search` |
-| 退出登录后导航栏未更新 | 检查是否用了 `window.location.href = '/login'` 而非 `navigate('/login')` |
-
----
-
-## 更新日志规范
-
-更新日志用于让后续 Agent 和开发者快速接手。影响可见功能、跨资源、已 push、已发布或用户明确要求记录时，写入 `.draftgo/changelog.md`；纯小修、探索、未形成有效改动时可跳过。
-
-### 规则
-
-- 单文件，用 `## YYYY-MM-DD` 做日期分节
-- 每条格式：`- [HH:MM] [操作类型] 描述`
-- 操作类型：`新增` / `修复` / `修改` / `完善` / `删除` / `重构`
-- 描述精简，一句话，不超过 30 字
-
-### 示例
-
-```markdown
-## 2026-05-18
-
-- [14:23] [新增] 用户登录页面表单验证逻辑
-- [15:10] [修复] 脉象输入组件在 Safari 下无法聚焦
-- [16:05] [修改] 问诊表单字段顺序，主诉移至首位
-
-## 2026-05-17
-
-- [09:30] [新增] 患者档案列表页面
-- [11:45] [完善] 导航栏权限控制逻辑
-```
-
-### 操作流程
-
-1. 判断本次改动是否需要记录
-2. 检查 `.draftgo/changelog.md` 是否存在
-3. 查找当天日期标题（`## YYYY-MM-DD`）
-4. 存在则在该日期段落末尾追加新条目；不存在则在文件顶部新增日期段落
-5. 无需告知用户（静默执行）
-
-## 经验记录规范（lessons）
-
-每次开发过程中遇到阻碍、踩坑、发现更好的范式时，写入 `.draftgo/lessons/` 目录。
-
-### 文件命名
-
-`YYYY-MM-DD-主题关键词.md`，例如：
-- `2026-05-18-sync中文路径编码.md`
-- `2026-05-18-iframe参数传递范式.md`
-
-### 文件结构
-
-```markdown
-# 主题
-
-## 现象
-
-基于 DraftGo 基座和 CLI 开发时遇到 xxxxxxx
-
-## 原因
-
-xxx
-
-## 解法
-
-可能有效的解决方案建议：xxxxx
-
-## 适用场景
-
-什么时候会再次遇到这个问题
-```
-
-### 什么时候写
-
-开发过程中只要遇到阻碍或获得经验就写入，没有则跳过（不强制）。典型场景：
-
-- CLI 引导错误或调用失败
-- API 返回非预期结果
-- 前端开发发现更好的范式
-- 框架运行时行为与预期不符
-- 任何花了 5 分钟以上才解决的问题
-- 发现了一个值得记录的开发技巧或最佳实践
-
-### 操作流程
-
-1. 开发完成后回顾：本次有没有遇到阻碍或获得新经验？
-2. 有 → 确定主题关键词，创建 `.draftgo/lessons/YYYY-MM-DD-主题.md`，按上述结构填写
-3. 没有 → 跳过，不需要写
-
----
-
-## 推送规范
-
-> 推送用于把本地资源同步到云端。用户明确要求推送、任务目标包含云端生效、资源已形成可交付结果、或修改涉及多资源联动时执行；探索性修改、未完成草稿和目标明确的小修可先保留本地。
-
-### 新建资源（无 id 自动创建）
-
-push 脚本按 index.json 条目**有无 `id`** 决定走更新还是创建：
-
-- **有 id** → `PUT` 更新（PUT 404 时自动转创建，兼容删了重建 / 跨环境）
-- **无 id** → `POST` 创建，成功后**自动回写新 id 到 index.json**；有独立内容文件的资源会同步重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`
-
-支持创建的类型：**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`「新建资源」节）。
-
-> ⚠️ 创建后以脚本回写的 index 为准，不要手动猜 id。route/slug/code 等唯一性字段冲突时后端返回 400。
-
-### 推送支持的类型
-
-推送脚本覆盖 init 拉取的全部 11 种类型：
-
-| 类型 | 命令 | 说明 |
-|---|---|---|
-| pages | `python {{SKILL_SCRIPTS}}/draftgo_push.py pages [page_id]` | 页面推送 |
-| nav | `python {{SKILL_SCRIPTS}}/draftgo_push.py nav [nav_id]` | 导航栏推送 |
-| db_meta | `python {{SKILL_SCRIPTS}}/draftgo_push.py db_meta [id]` | 数据库元数据推送 |
-| aihub | `python {{SKILL_SCRIPTS}}/draftgo_push.py aihub [id]` | AI 资产推送 |
-| external_apis | `python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis [id]` | 外部 API 注册推送 |
-| system_config | `python {{SKILL_SCRIPTS}}/draftgo_push.py system_config [config_key]` | 系统配置推送 |
-| docs | `python {{SKILL_SCRIPTS}}/draftgo_push.py docs [article_id]` | 文档中心文章推送（正文从 .md 文件读取） |
-| doc_categories | `python {{SKILL_SCRIPTS}}/draftgo_push.py doc_categories [id]` | 文档分类推送 |
-| custom_scripts | `python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts [id]` | ⚠️ 需向用户二次确认（覆盖云端脚本代码，不修改 mode/status） |
-| roles | `python {{SKILL_SCRIPTS}}/draftgo_push.py roles [id]` | ⚠️ 需向用户二次确认 |
-| users | `python {{SKILL_SCRIPTS}}/draftgo_push.py users [id]` | ⚠️ 需向用户二次确认（不下发 password / role_ids） |
-
-> `{{SKILL_SCRIPTS}}` 在 CLI 渲染时会替换为当前 AI 工具的脚本路径，例如 `.claude/skills/draftgo/scripts`、`.codex/skills/draftgo/scripts`、`.cursor/commands/draftgo/scripts` 等。
-
-### 推送规则
-
-- 修改了哪个页面的 HTML → 推送该页面：`python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>`
-- 修改了哪个导航栏的 HTML → 推送该导航：`python {{SKILL_SCRIPTS}}/draftgo_push.py nav <nav_id>`
-- 修改了 DB Meta / AI 资产 / 外部 API / 系统配置 / 文档 / 文档分类 → 用对应模式推送：`python {{SKILL_SCRIPTS}}/draftgo_push.py <mode> <id>`
-- 修改了 custom_scripts → **必须先向用户确认**（覆盖云端运行脚本），确认后再运行 `custom_scripts` 模式
-- 修改了 roles/users → **必须先向用户确认**，确认后再运行 `roles` / `users` 模式
-- 同时修改多个 → 使用批量推送：`python {{SKILL_SCRIPTS}}/draftgo_push.py --batch <mode1> <id1>,<id2> <mode2> <id3>`
-- 推送失败时告知用户，不得静默忽略
-
-### 批量推送（并行开发后使用）
-
-当并行执行产出多个资源修改时，使用 `--batch` 一次性推送：
-
-```bash
-python {{SKILL_SCRIPTS}}/draftgo_push.py --batch pages 1,2,3 nav 4 custom_scripts 7
-```
-
-等价于依次推送 pages 1、2、3 + nav 4 + custom_scripts 7，共享同一 config 加载。
-
-### ⚠️ roles / users 推送注意事项
-
-roles 和 users 涉及权限与账号安全，虽然脚本已支持，**仍必须人工确认后执行**：
-1. 告知用户即将推送的变更内容（角色名/权限变更 或 用户信息变更）
-2. **等待用户明确确认**后，再运行 `draftgo_push.py roles` / `users`
-3. 用户拒绝则不推送，仅保留本地修改
-
-### 收尾操作顺序（按影响选择）
-
-1. 判断是否需要写更新日志
-2. 写经验记录（有阻碍或新经验时写入 lessons/，没有则跳过）
-3. 需要云端生效时运行推送脚本 / 调用 API（roles/users 需二次确认）
-4. 告知用户本次证据与是否已推送
-
-> **Lessons 提醒机制**：当 `.draftgo/config.json` 中 `lessons_on_push` 为 `true` 时，push 脚本执行完毕会输出一段回顾提醒。此提醒仅为兜底安全网；是否写 lessons 仍按“有阻碍或新经验”判断。
-
----
-
-## 推送命令快捷入口
-
-- `/draftgo push pages` — 触发 push skill
-- `/draftgo push nav` — 触发 push skill
-- `/draftgo push db_meta` — 触发 push skill
-- `/draftgo push aihub` — 触发 push skill
-- `/draftgo push external_apis` — 触发 push skill
-- `/draftgo push system_config` — 触发 push skill
-- `/draftgo push docs` — 触发 push skill
-- `/draftgo push doc_categories` — 触发 push skill
-- `/draftgo push custom_scripts` — 触发 push skill（需人工确认）
-- `/draftgo push roles` — 触发 push skill（需人工确认）
-- `/draftgo push users` — 触发 push skill（需人工确认）
-- `/draftgo pull` — 触发 pull skill（从云端拉取，支持按类型）
-- `/draftgo pull --all` — 全量拉取
-- `/draftgo init` — 触发 init skill
-
----
-
-## 自定义服务（Custom Scripts）开发指南
-
-> 为用户编写或修改 `.draftgo/custom_scripts/` 下的脚本时，**必须遵循以下规范**。违反将导致脚本加载失败或运行时报错。
-
-### 核心机制
-
-DraftGo 脚本引擎使用 `exec()` 在受限沙箱中执行脚本代码。引擎在执行前自动注入 `on`、`route`、`scheduled` 三个装饰器到脚本命名空间。
-
-### 装饰器用法（不需要 import）
-
-```python
-# ✅ 直接使用——引擎已注入到命名空间
-@route("GET /hello")
-def hello(sdk, ctx):
-    return sdk.response({"message": "Hello!"})
-
-@on("user.registered")
-def on_user(sdk, ctx):
-    sdk.notify.send(ctx["payload"]["user_id"], "欢迎", "欢迎加入！")
-
-@scheduled("0 2 * * *")
-def cleanup(sdk, ctx):
-    sdk.log.info("每日清理")
-```
-
-```python
-# ❌ 这些写法都会报错
-from draftgo import route       # 没有 draftgo 这个内置模块
-from sdk import route           # 可以但多余，直接用就行
-import sdk                      # 可以但多余
-
-@route("/hello")                # ❌ 缺少 HTTP 方法
-@route("GET", "/hello")         # ❌ 不是逗号分隔
-def handler(request):           # ❌ 签名必须是 (sdk, ctx)
-    return {"data": 1}          # ❌ route 模式必须用 sdk.response()
-```
-
-### 装饰器格式
-
-| 模式 | 格式 | 示例 |
-|------|------|------|
-| Route | `@route("METHOD /path")` | `@route("POST /orders")` |
-| Event | `@on("domain.action")` | `@on("db.created")` |
-| Scheduled | `@scheduled("分 时 日 月 周")` | `@scheduled("30 8 * * 1-5")` |
-
-### Handler 签名
-
-所有模式统一 `(sdk, ctx)` 两个参数：
-
-- **sdk** — SDK 实例，提供 `sdk.db`、`sdk.users`、`sdk.notify`、`sdk.external_api`、`sdk.cache`、`sdk.log`、`sdk.auth`、`sdk.config`、`sdk.response()`、`sdk.now()`
-- **ctx** — 上下文，内容因模式而异：
-  - Route: `{body, query_params, headers, method, path, user}`
-  - Event: `{event, payload, timestamp}`
-  - Scheduled: `{trigger_type, trigger_name, payload, config}`
-
-### 可导入模块
-
-自定义脚本只允许管理员创建和编辑，因此脚本引擎**不再做 import 白名单限制**。脚本可以导入当前后端运行环境中已经安装的 Python 模块；如果目标环境没有安装该依赖，脚本加载或执行时会报 `ImportError`。
-
-建议优先使用标准库和 DraftGo SDK。需要新增第三方依赖时，要确认部署环境的 `requirements.txt` / 镜像中已经包含该包，避免本地可用、线上不可用。
-
-**推荐做法：**
-
-| 需求 | 推荐 |
-|------|------|
-| 调外部 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 速查表（与基座源码对齐）
-
-> 来源：`backend/app/engine/sdk/modules.py`。所有方法均为实例方法，签名以源码为准。
-
-#### `sdk.db` — 通用数据操作（7 个方法，无 `list`）
-
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `create` | `(type: str, data: dict, userid: int = None) -> dict` | 创建记录，返回完整 dict |
-| `create_many` | `(type: str, items: list[dict]) -> list[dict]` | 批量创建；每项可传裸业务字典，或 `{data, userid, status}` 包装对象 |
-| `get` | `(type: str, id: int) -> dict \| None` | 查不到返回 `None`（不抛异常） |
-| `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, order_by: str = None, order: str = "desc") -> dict` | 返回 `{items, total, page, page_size}` |
-
-**`filters` 语义（重要）**：结构化条件查询，直接对记录的 `data` JSON 字段做 WHERE，**支持** `eq` / `like` / `gte` / `lte` / `gt` / `lt` / `in` / `contains`。多字段是 AND 关系。字段必须在 db_meta schema 里标 `searchable`，且操作符要匹配字段的检索模式（exact/fuzzy/range/contains），否则后端报 400。
-
-**filters 写法**：
-| 形式 | 含义 | 示例 |
-|--------|------|------|
-| `{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)`，超出静默截断。
-
-#### `sdk.external_api` — 外部 HTTP 调用（仅 4 个方法，**只接受裸 URL**）
-
-| 方法 | 签名 |
-|------|------|
-| `get` | `(url, headers: dict = None, timeout: int = 10) -> dict` |
-| `post` | `(url, body=None, headers: dict = None, timeout: int = 10) -> dict` |
-| `put` | `(url, body=None, headers: dict = None, timeout: int = 10) -> dict` |
-| `delete` | `(url, headers: dict = None, timeout: int = 10) -> dict` |
-
-**返回结构统一**：
-
-```python
-# 正常
-{"status_code": int, "headers": dict, "data": json_or_text}
-# 异常（不抛异常，统一以 dict 返回）
-{"status_code": 0, "error": "请求超时 (30s)"}
-{"status_code": code, "error": "响应体超过最大限制 (5242880 bytes)"}
-```
-
-**硬上限（被静默截断）**：
-
-| 项 | 值 | 行为 |
-|---|---|---|
-| `timeout` | 1 ≤ t ≤ **30s** | 传 120 会被静默改成 30 |
-| 响应体 | **5MB** | 超出返回 `{status_code, error}`，无 `data` |
-
-**没有 `call()` 方法**：调用 `sdk.external_api.call(...)` 会抛 `AttributeError`。脚本里**没有**"按已注册 API code 走代理"的能力，只能裸 URL。
-
-#### 两套外部 API 调用路径（不共享配置！）
-
-| 路径 | 在哪里用 | 是否读「外部 API 接入」注册表 |
-|------|---------|-------------------------------|
-| `sdk.external_api.*(url, headers, timeout)` | **脚本内** | ❌ 不读。headers / auth_config / base_url 都不复用 |
-| `App.callApi(code, {...})` / `POST /api/external-apis/call/{code}` | 页面壳层 / 前端 | ✅ 走注册表，自动带 headers、auth、base_url |
-
-**结论**：在脚本里想"复用已注册 API"，必须**自己重写 headers**。`.draftgo/external_apis/index.json` 中的 `auth_config` 已脱敏，不要从那里拷敏感字段；建议把密钥写入系统配置后用 `sdk.config.get(key)` 读取。
-
-最小 helper（按需复制到脚本顶部）：
-
-```python
-def call_registered(sdk, base_url: str, path: str, method: str = "GET",
-                    body=None, extra_headers: dict = None, timeout: int = 15):
-    """脚本内复用已注册 API 的最小封装：自带通用头，密钥走 sdk.config。"""
-    headers = {
-        "User-Agent": "DraftGo-Script/1.0",
-        "Accept": "application/json",
-    }
-    token = sdk.config.get("MY_API_TOKEN")  # 在系统配置里事先写好
-    if token:
-        headers["Authorization"] = f"Bearer {token}"
-    if extra_headers:
-        headers.update(extra_headers)
-    url = base_url.rstrip("/") + "/" + path.lstrip("/")
-    fn = getattr(sdk.external_api, method.lower())
-    return fn(url, body=body, headers=headers, timeout=timeout) if method.upper() in ("POST","PUT") \
-        else fn(url, headers=headers, timeout=timeout)
-```
-
-#### `sdk.aihub` — 调用 AIHub Agent / 图片生成
-
-脚本里需要复用 AIHub 时，用 `sdk.aihub`，不要自己保存模型 API Key。必须在脚本 `config.aihub.enabled=true` 后才可用。
-
-**身份规则**：
-
-| 触发来源 | AIHub 身份 |
+| `.draftgo/pages/` | index.json + .html 文件 |
+| `.draftgo/navigations/` | index.json + .html 文件 |
+| `.draftgo/db_meta/` | index.json（含 schema/permission） |
+| `.draftgo/custom_scripts/` | index.json + 脚本文件 |
+| `.draftgo/external_apis/` | index.json（auth_config 已脱敏） |
+| `.draftgo/aihub/` | index.json |
+| `.draftgo/docs/articles/` | index.json + .md 文件 |
+| `.draftgo/system_config/` | index.json |
+| `.draftgo/changelog.md` | 更新日志 |
+| `.draftgo/lessons/` | 开发经验（YYYY-MM-DD-主题.md） |
+| `.draftgo/Task/` | 任务文档（仅跨资源/高风险任务） |
+
+## 文档索引
+
+| 文档 | 读取时机 |
 |---|---|
-| 登录用户调用 route | 当前登录用户 |
-| 匿名 public route | 默认禁止 |
-| scheduled | system |
-| event | payload 有 `user_id` / `actor_user_id` 则继承用户，否则 system |
-| 管理员手动 execute | 点击执行的管理员 |
-| Agent tool -> custom script | 发起 Agent 请求的用户 |
-
-**config 示例**：
-
-```json
-{
-  "timeout": 120,
-  "aihub": {
-    "enabled": true,
-    "allowed_agents": [12, 18],
-    "allowed_models": [],
-    "allow_direct_model_call": false,
-    "allow_images": true
-  }
-}
-```
-
-**代码示例**：
-
-```python
-@route("POST /summarize")
-def summarize(sdk, ctx):
-    body = ctx["body"] or {}
-    result = sdk.aihub.chat(agent_id=12, message=body.get("text", ""))
-    return sdk.response(result)
-
-@route("POST /poster")
-def poster(sdk, ctx):
-    body = ctx["body"] or {}
-    image = sdk.aihub.images.generate(
-        agent_id=18,
-        prompt=body.get("prompt", ""),
-        size="1024x1024",
-        response_format="url",
-    )
-    return sdk.response(image)
-```
-
-优先用 `agent_id`，让提示词、工具、图片默认参数和可选用户选模型都在 AIHub Agent 中统一管理。只有平台内部脚本确实需要裸模型时才开启 `allow_direct_model_call`。
-
-#### `sdk.cache` — Redis 缓存
-
-| 方法 | 签名 | 上限 |
-|------|------|------|
-| `set` | `(key, value, ttl: int = 3600)` | TTL 1–**86400s**（超出截断），value 序列化后 ≤ **1MB** |
-| `get` | `(key) -> Any \| None` | JSON 反序列化失败时回退原始字符串 |
-| `delete` | `(key) -> bool` | — |
-
-**Key 自动加前缀** `script:{script_id}:`，跨脚本不互相覆盖。
-
-#### `sdk.log` — 日志（持久化到 Execution_Record）
-
-| 方法 | 行为 |
-|------|------|
-| `info / warn / error / debug(message: str)` | 内存收集，handler 结束后落库 |
-
-**上限**：单条消息 **4096 字符**（超出截断），单次执行 **500 条**（超出**静默丢弃**，不报错）。日志爆掉调试需求时，自己合并/采样。
-
-**`POST /scripts/{id}/execute` 返回结构**：
-
-```json
-{
-  "code": 200,
-  "data": {
-    "status": "success | error | timeout",
-    "output": <handler 返回值>,
-    "error": "错误信息（成功时为 null）",
-    "error_detail": "完整错误堆栈（成功时为 null）",
-    "duration_ms": 123,
-    "logs": [{"level": "info", "message": "...", "timestamp": "..."}]
-  }
-}
-```
-
-`logs` 字段为 `sdk.log.*()` 收集的日志数组，handler 结束后随执行结果一起返回。`GET /scripts/{id}/executions` 历史记录中同样包含 `logs`（JSON 字符串形式，需 `JSON.parse`）。
-
-#### 双层超时模型（极易混淆）
-
-| 层 | 控制处 | 默认 | 上限 | 触发后 |
-|---|---|---|---|---|
-| **脚本整体超时** | `config.timeout`（脚本配置） | **30s** | 由后端调度器决定 | 状态变 `timeout`，提示 `执行超时 (Ns)` |
-| **单次 HTTP 超时** | `sdk.external_api.*(timeout=...)` | 10s | **30s（硬上限）** | 该次调用返回 `{status_code: 0, error: "请求超时 (30s)"}` |
-
-**铁律**：`config.timeout` 必须 **≥ 所有 HTTP 调用 timeout 之和 + 余量**。串行多次外部请求时务必显式调大 `config.timeout`（建议 120–300）。
-
-### 脚本模板（复制即用）
-
-**Route 模式：**
-```python
-import json
-import datetime
-import uuid
-
-@route("GET /health")
-def health(sdk, ctx):
-    return sdk.response({
-        "status": "ok",
-        "timestamp": sdk.now().isoformat(),
-        "request_id": str(uuid.uuid4())
-    })
-
-@route("POST /process")
-def process(sdk, ctx):
-    body = ctx["body"]
-    if not body:
-        return sdk.response({"error": "请求体为空"}, status_code=400)
-    sdk.log.info(f"收到数据: {json.dumps(body, ensure_ascii=False)[:200]}")
-    return sdk.response({"ok": True})
-```
-
-**Event 模式：**
-```python
-@on("user.registered")
-def welcome(sdk, ctx):
-    user_id = ctx["payload"]["user_id"]
-    sdk.notify.send(user_id, "欢迎", "欢迎加入平台！", type="info")
-    sdk.log.info(f"欢迎通知已发送: user_id={user_id}")
-```
-
-**Scheduled 模式（简单版）：**
-```python
-@scheduled("0 9 * * 1")
-def weekly_report(sdk, ctx):
-    result = sdk.users.list(page=1, page_size=1)
-    sdk.log.info(f"周报: 用户总数={result.get('total', 0)}")
-```
-
-**Scheduled 模式（多源串行抓取 — 完整最佳实践）：**
-
-> 演示要点：显式 UA、单次 timeout ≤ 30、用 `sdk.cache` 去重、用 `sdk.db.query`（不是 `list`）、按需配 `config.timeout=300`。
-
-```python
-import json, hashlib
-
-SOURCES = [
-    ("source_a", "https://example.com/api/a"),
-    ("source_b", "https://example.com/api/b"),
-]
-
-@scheduled("*/30 * * * *")
-def fetch_all(sdk, ctx):
-    headers = {"User-Agent": "Mozilla/5.0 (compatible; DraftGo-Script/1.0)"}
-    saved = 0
-    for name, url in SOURCES:
-        resp = sdk.external_api.get(url, headers=headers, timeout=20)
-        if resp.get("status_code") != 200:
-            sdk.log.warn(f"{name} 拉取失败: {resp.get('error') or resp.get('status_code')}")
-            continue
-        for item in (resp.get("data") or {}).get("items", []):
-            uniq = hashlib.md5(f"{name}:{item.get('id')}".encode()).hexdigest()
-            if sdk.cache.get(uniq):
-                continue
-            sdk.db.create("trend_item", {"source": name, "raw": item})
-            sdk.cache.set(uniq, 1, ttl=86400)
-            saved += 1
-    sdk.log.info(f"抓取完成，新增 {saved} 条")
-```
-
-> 同步该脚本时 `config` 必须给到：`{"timeout": 300, "max_retries": 0}`，否则脚本整体 30s 默认超时会先于循环结束。
-
-### 配置字段说明
-
-创建/更新脚本时的 JSON 字段：
-
-```json
-{
-  "name": "服务名称",
-  "slug": "url-safe-slug",
-  "code": "脚本代码（完整 Python）",
-  "mode": "route | event | scheduled",
-  "triggers": {},
-  "config": {"timeout": 30},
-  "permission": {"default": "public"}
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `name` | ✅ | 显示名称 |
-| `slug` | ✅ | URL 标识（route 模式的访问路径：`/api/x/{slug}/{path}`） |
-| `code` | ✅ | 完整 Python 代码 |
-| `mode` | ✅ | `event` / `route` / `scheduled` |
-| `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 值 |
-|------|--------------|
-| 任何人可访问 | `{"default": "public"}` |
-| 登录才能访问 | `{"default": "login"}` |
-| 指定角色 | `{"default": "login", "roles": ["vip"]}` |
-| 仅管理员 | `{"default": "admin"}` |
-
-### 可监听事件列表
-
-| 事件 | Payload |
-|------|---------|
-| `user.registered` | `{user_id, username, email}` |
-| `user.login` | `{user_id, login_at}` |
-| `user.updated` | `{user_id, changes}` |
-| `db.created` | `{type, record_id}` |
-| `db.updated` | `{type, record_id, changes}` |
-| `db.deleted` | `{type, record_id}` |
-| `page.created` | `{page_id, route, title}` |
-| `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: `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 |
-| handler 执行报错 "参数不匹配" | handler 签名不是 (sdk, ctx) | 修正签名 |
-| route handler 返回 None | 没有用 sdk.response() | 添加 return sdk.response(...) |
-| 500 Internal Server Error（FK constraint） | SAT 调用时 user_id=0 | Service 层需处理 id=0 → None |
-| `'ExternalAPIModule' object has no attribute 'call'` | 误以为脚本里能按 code 调注册过的 API | 用 `sdk.external_api.get/post/put/delete(url)`，注册表配置仅页面侧 `App.callApi` 复用 |
-| 拉取公开 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` 加了 `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 | 改造业务逻辑，把单次请求拆短；或改用分批拉取 |
-
----
-
-## AIHub 资产配置指南
-
-> 用户说"帮我配一个 MCP"、"给 Agent 加工具"、"配一个模型供应商"时，参照本节通过 API 操作。
-
-### 资产类型总览
-
-| type | 说明 | 创建后需要 |
-|------|------|-----------|
-| `model` | 模型供应商（OpenAI 兼容） | 同步模型列表 |
-| `prompt` | 提示词 | — |
-| `agent` | 智能体（用户对话入口） | 绑定模型 + 可选绑定工具 |
-| `mcp` | MCP Server（远程工具服务） | discover-tools 发现工具 → 绑定到 Agent |
-| `skill` | Skill（平台内置工具） | 绑定到 Agent |
-
-### 创建模型供应商
-
-```
-POST /api/aihub
-Body:
-{
-  "type": "model",
-  "name": "供应商名称",
-  "priority": 100,
-  "data": {
-    "provider": "openai-compatible",
-    "base_url": "https://api.example.com/v1",
-    "api_key": "sk-xxx",
-    "models": [],
-    "enabled": true,
-    "timeout": 120,
-    "image_generation_path": "/images/generations",
-    "headers": {}
-  }
-}
-```
-
-创建后同步模型列表：`POST /api/aihub/{id}/sync`
-
-图片生成能力不在模型资产上打标签。需要判断某模型是否支持生图时，可选调用：
-
-```
-POST /api/aihub/{id}/test-image-generation
-Body: {"model": "gpt-image-1", "prompt": "A simple red square", "size": "1024x1024", "response_format": "url"}
-```
-
-结果只写入 `data.image_generation_probe` 供配置人员参考，不作为后续调用门禁。真实调用仍以 `/api/images/generation` 或 `/api/agents/{id}/images` 的上游结果为准。
-
-### 创建 MCP 资产
-
-⚠️ **管理界面仅支持远程协议**：`sse` 和 `streamable_http`。stdio 后端保留兼容但前端已移除。
-
-```
-POST /api/aihub
-Body:
-{
-  "type": "mcp",
-  "name": "MCP Server 名称",
-  "data": {
-    "transport": "sse",
-    "url": "https://mcp-server.example.com/sse",
-    "headers": {},
-    "api_key": null,
-    "timeout_ms": 30000,
-    "tools": [],
-    "tool_filter": [],
-    "enabled": true
-  }
-}
-```
-
-**transport 选择**：
-- `sse`：服务端推送（Server-Sent Events），适合大多数远程 MCP Server
-- `streamable_http`：HTTP POST 请求 + 流式响应，适合新版 MCP 协议
-
-**创建后必须发现工具**：
-```
-POST /api/aihub/mcp/discover-tools
-Body: {"id": <mcp_asset_id>}
-返回: { "code": 200, "data": { "tools": [{"name": "search", "description": "...", "inputSchema": {...}}, ...], "count": N } }
-```
-
-发现的工具会写入该 MCP 资产的 `data.tools` 数组。
-
-### 创建 Agent（智能体）
-
-```
-POST /api/aihub
-Body:
-{
-  "type": "agent",
-  "name": "智能体名称",
-  "describe": "功能描述",
-  "data": {
-    "schema_version": "agent.v3",
-    "spec": {
-      "model_id": 1,
-      "system_prompt_template": "你是一个助手。",
-      "runtime": {
-        "temperature": 0.7,
-        "max_tokens": null,
-        "stream": true
-      },
-      "context": {
-        "max_history": 20
-      }
-    }
-  }
-}
-```
-
-聊天型 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
-
-```
-POST /api/aihub
-Body:
-{
-  "type": "agent",
-  "name": "海报生成智能体",
-  "describe": "根据提示词生成图片",
-  "data": {
-    "schema_version": "agent.v3",
-    "spec": {
-      "mode": "image_generation",
-      "model_id": 1,
-      "model": "gpt-image-1",
-      "system_prompt_template": "统一生成商业海报，画面清晰。",
-      "image_generation": {
-        "n": 1,
-        "size": "1024x1024",
-        "quality": "auto",
-        "response_format": "url"
-      }
-    }
-  }
-}
-```
-
-图片生成型 Agent 调用：
-
-```
-POST /api/agents/{agent_id}/images
-Body: {"prompt": "生成一张夏季饮品海报", "size": "1024x1024", "model": "gpt-image-1"}
-```
-
-页面里使用 `DraftGoAI.images(agentId, prompt, options)`；不要把图片生成请求发到 `/chat`。`options.model` 同样遵循 Agent 的用户选模型白名单。
-
-### 给 Agent 绑定工具
-
-通过 `PUT /api/aihub/{agent_id}` 更新 Agent 的 `data.spec.tools` 配置：
-
-```json
-{
-  "data": {
-    "spec": {
-      "tools": {
-        "enabled": true,
-        "max_iterations": 10,
-        "parallel_calls": true,
-        "sources": [
-          {"type": "mcp", "id": 10, "name": "GitHub MCP"},
-          {"type": "external_api", "id": 5, "name": "天气查询"},
-          {"type": "custom_script", "id": 3, "name": "数据查询"}
-        ]
-      }
-    }
-  }
-}
-```
-
-**sources 字段说明**：
-
-| type | id 含义 | 说明 |
-|------|---------|------|
-| `mcp` | MCP 资产 ID | 先 discover-tools 确保有工具 |
-| `external_api` | 外部 API 资产 ID | 已注册到「外部 API 接入」的 API |
-| `custom_script` | 自定义脚本 ID | 已创建的 route 模式脚本 |
-
-可选 `tool_filter: ["tool_a", "tool_b"]` 限制暴露哪些工具（空=全部暴露）。
-
-### 完整操作流程示例：配一个 MCP 并绑定到 Agent
-
-1. 创建 MCP 资产 → 得到 `mcp_id`
-2. `POST /api/aihub/mcp/discover-tools {"id": mcp_id}` → 确认工具列表
-3. 查找或创建 Agent → 得到 `agent_id`
-4. `PUT /api/aihub/{agent_id}` 更新 `data.spec.tools.sources` 添加 `{"type": "mcp", "id": mcp_id, "name": "xxx"}`
-5. 测试：`POST /api/agents/{agent_id}/chat {"message": "...", "stream": true}`
-
-### Agent 对话流式事件（前端对接参考）
-
-Agent 开启工具后，流式响应中除常规 SSE chunk 外会插入自定义事件：
-
-```
-data: {"object":"tool.executing","tool_call_id":"call_xxx","name":"mcp_10_search","source_type":"mcp"}
-data: {"object":"tool.result","tool_call_id":"call_xxx","name":"mcp_10_search","content":"...","success":true,"duration_ms":320,"source_type":"mcp"}
-```
-
-- `source_type`：`mcp` / `external_api` / `custom_script`
-- `tool.executing`：工具开始执行（前端可显示 loading 状态）
-- `tool.result`：工具执行完成（含结果和耗时）
-
-### 常见配置问题
-
-| 问题 | 排查 |
-|------|------|
-| discover-tools 超时 | 检查 MCP url 是否可达、timeout_ms 是否够长 |
-| Agent 对话不调工具 | 确认 `spec.tools.enabled=true` 且 `sources` 非空 |
-| 工具调用 404 | source id 对应的资产不存在或已禁用 |
-| MCP 连接失败 | 确认 transport 类型与服务端协议匹配（sse vs streamable_http） |
+| `core/architecture.md` | 进入陌生项目·理解平台机制（3分钟） |
+| `core/modules.md` | 评估功能可行性·选择开发路径 |
+| `specs/runtime.md` | 处理 token/路由/事件/全局层问题 |
+| `specs/data.md` | 动态 DB·filters·db_meta 操作 |
+| `specs/ui-protocol.md` | dg-* 完整映射表 |
+| `specs/security.md` | 开发禁区速查 |
+| `practices/dev-declaration.md` | 标准功能/高风险任务开始前 |
+| `practices/best-practices.md` | 开发决策·Code Review |
+| `practices/anti-patterns.md` | 检查反模式 |
+| `quickref/app-api.md` | App API 速查 |
+| `quickref/api-endpoints.md` | 后端端点速查 |
+| `quickref/dg-components.md` | dg-* 组件代码示例 |