draftgo-cli 3.0.29 → 3.0.33

package/resources/skill/push/SKILL.md

@@ -1,300 +1,48 @@
 ---
 name: draftgo-push
-description: Use this skill when the user says "推送页面", "推送导航", "推送数据库", "推送AI资产", "推送系统配置", "推送角色", "推送用户", "推送文档", "推送文档分类", "推送自定义脚本", "同步页面", "同步导航", "同步数据库", "同步AI资产", "同步系统配置", "同步角色", "同步用户", "同步文档", "同步文档分类", "同步自定义脚本", "push pages", "push nav", "push db_meta", "push aihub", "push system_config", "push roles", "push users", "push docs", "push doc_categories", "push custom_scripts", "sync pages", "sync nav", "sync db_meta", "sync aihub", "sync system_config", "sync roles", "sync users", "sync docs", "sync doc_categories", "sync custom_scripts", "/draftgo push", "/draftgo sync", or wants to push local changes to the DraftGo server.
-version: 1.5.0
-allowed-tools: Bash(python:*), Read, Glob
+description: Create or update DraftGo resources from local .draftgo indexes and referenced files, choose direct push, checked delivery, or configured automatic delivery, and verify the resulting server state.
 ---
 
-# DraftGo 推送（本地 → 云端）
+# DraftGo 推送与交付
 
-> **STOP — 禁止用 curl、禁止自己写 Python 上传逻辑。**
-> 唯一正确方式：运行下方 Python 脚本。脚本覆盖 init 拉取的全部类型（pages / nav / db_meta / aihub / system_config / roles / users / docs / doc_categories / custom_scripts），已处理字段结构、token 读取、错误处理。
+使用 `draftgo push`、`draftgo deploy` 或 `draftgo auto-push`；内部 Python 脚本由 CLI 定位和执行。
 
-脚本位于：`{{SKILL_SCRIPTS}}/draftgo_push.py`
+## 选择动作
 
-## 新建资源（本地无 id → 自动创建）
-
-> push 脚本同时承担「更新」与「创建」。判定依据是 index.json 条目里**有没有 `id` 字段**：
-> - **有 id** → `PUT /api/{type}/{id}` 更新（PUT 404 时自动转为创建）
-> - **无 id** → `POST /api/{type}` 创建，成功后**自动回写新 id 到 index.json**，并把对应 .html/.md/代码文件**重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`**
-
-支持创建的类型：**pages / nav / db_meta / aihub / docs / doc_categories / custom_scripts**。
-
-### 新建页面的标准流程
-
-1. 在 `.draftgo/pages/` 写好页面 HTML 文件（文件名随意，建议 `page_new_<slug>.html`）
-2. 在 `.draftgo/pages/index.json` **追加一条不带 `id` 的记录**：
-   ```json
-   {
-     "title": "关于我们",
-     "route": "/about",
-     "menu": null,
-     "tag": null,
-     "status": "active",
-     "permission": { "default": "public" },
-     "html_file": ".draftgo/pages/page_new_about.html"
-   }
-   ```
-   > `route` 不能与云端已有页面重复，否则后端返回 400。保留路由 `/setup` 不可占用。
-3. 运行 push（不带具体 id，会扫描整个 index）：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py pages
-   ```
-4. 脚本输出 `OK [关于我们] 已创建 page_id=42（已回写 index）`，此时 index.json 已填入 `id`，html 文件已重命名为 `page_42_about.html`。后续再改这个页面就是普通的按 id 更新。
-
-### 各类型新建的最小必填字段
-
-| 类型 | index 条目必填（除 html_file/content_file/code_file 外） | 说明 |
-|---|---|---|
-| 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 资产 |
-| docs | `title` | 其余字段有默认值 |
-| doc_categories | `name` | slug 可选；不填由后端生成/处理 |
-| custom_scripts | `name`, `slug`, `mode` | 服务使用 `mode=mixed`；触发器写在 `Register` 中，启停仍走 enable/disable |
-
-> **创建后必须以脚本回写的 index 为准**，不要手动猜 id。回写后建议 `git diff` 或重新读 index 确认 `id` 已落地。
-
-## 推送页面（"推送页面" / "push pages"）
-
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages <page_id>
-```
-
-## 推送数据库元数据（"推送数据库" / "push db_meta"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py db_meta
-!python {{SKILL_SCRIPTS}}/draftgo_push.py db_meta <db_meta_id>
-```
-
-## 推送导航栏（"推送导航" / "push nav"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py nav
-!python {{SKILL_SCRIPTS}}/draftgo_push.py nav <nav_id>
-```
-
-脚本会自动读取 `.draftgo/config.json`。
-
-## 推送 AI 资产（"推送AI资产" / "push aihub"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py aihub
-!python {{SKILL_SCRIPTS}}/draftgo_push.py aihub <aihub_id>
-```
-
-读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/aihub` 创建，成功后回写新 `id`。
-
-## 推送系统配置（"推送系统配置" / "push system_config"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py system_config
-!python {{SKILL_SCRIPTS}}/draftgo_push.py system_config <config_key>
-```
-
-读取 `.draftgo/system_config/index.json`，按 `config_key` 调用 `PUT /api/system/{config_key}`。脚本优先使用 `parsed_value`。
-
-前端全局层（`category = frontend_global` 或 `frontend_global_*`）属于系统默认配置，推送时只发送 `config_value`，不要发送 `description/category/value_type/status` 等元信息。其它系统配置若遇到“系统默认字段不允许修改字段描述/分类/状态”等错误，脚本会自动降级为只推送 `config_value`。
-
-Toast 全局配置常用键：
-
-| config_key | 说明 |
+| 意图 | 命令 |
 |---|---|
-| `frontend_global_toast_position` | 位置，支持 `center` |
-| `frontend_global_toast_scale` | 大小比例，范围 `0.5-3` |
-| `frontend_global_toast_opacity` | 背景透明度，范围 `0-100` |
-| `frontend_global_toast_duration_success/error/warning/info` | 默认停留时间，存储单位为毫秒；页面管理以秒输入 |
-| `frontend_global_toast_css` | Toast 自定义 CSS |
-| `frontend_global_scrollbar_color_mode` | 滚动条颜色模式：`theme` / `custom` |
-| `frontend_global_scrollbar_color` | 自定义滚动条颜色，`#RRGGBB` |
-| `frontend_global_scrollbar_buttons` | 是否显示两端按钮 |
-| `frontend_global_scrollbar_opacity` | 滑块透明度，范围 `0-100` |
-| `frontend_global_scrollbar_radius` | 圆角 px |
-| `frontend_global_scrollbar_width` | 宽度 px |
-
-## 推送角色（"推送角色" / "push roles"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py roles
-!python {{SKILL_SCRIPTS}}/draftgo_push.py roles <role_id>
-```
-
-读取 `.draftgo/roles/index.json`，按 `RoleUpdateRequest` 字段推送。脚本不会修改未写入索引的权限绑定关系。
-
-## 推送用户（"推送用户" / "push users"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py users
-!python {{SKILL_SCRIPTS}}/draftgo_push.py users <user_id>
-```
-
-读取 `.draftgo/users/index.json`，按 `UserUpdateRequest` 字段子集推送。脚本不会下发 `password` / `role_ids`；如需修改请走专用接口。
-
-## 推送文档（"推送文档" / "push docs"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py docs
-!python {{SKILL_SCRIPTS}}/draftgo_push.py docs <article_id>
-```
-
-读取 `.draftgo/docs/articles/index.json`；正文从 meta 中的 `content_file`（同目录 `.html` 文件）回填，按 `ArticleUpdate` schema 推送（自动附带 `content_type: "html"`）。修改文档时**直接改 `.html` 文件**即可，索引项保持稳定。
-
-## 推送文档分类（"推送文档分类" / "push doc_categories"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py doc_categories
-!python {{SKILL_SCRIPTS}}/draftgo_push.py doc_categories <category_id>
-```
-
-读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/docs/categories` 创建，成功后回写新 `id`。
-
-## 推送自定义脚本（"推送自定义脚本" / "push custom_scripts"）
-
-> 编写或修改代码前必须先读 `{{SKILL_DIR}}/specs/custom-services.md`。新服务使用 Go `Register(app *sdk.App)`；该文档是 handler ctx、完整 SDK、权限和运行限制的权威契约。
+| 同步已确认的本地资源 | `draftgo push <type> [id...]` |
+| 先检查但不修改云端 | `draftgo deploy [type] [id...] --delivery local` |
+| 检查并预演请求 | `draftgo deploy [type] [id...] --delivery preview` |
+| 检查并正式推送 | `draftgo deploy [type] [id...] --delivery deploy` |
+| 按项目配置自动推送 | `draftgo auto-push [type] [id...]` |
+| 一次推送多个资源集合 | `draftgo auto-push --batch pages 1,2 nav 4 custom_scripts 7` |
 
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts
-!python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts <script_id>
-```
+`push` 不自动运行 `check`。`deploy` 始终先运行 `check`。`auto-push` 先检查，并且仅在 `.draftgo/config.json` 的 `auto_push` 为 `true` 时推送。
 
-读取 `.draftgo/custom_scripts/index.json`，并读取每条 meta 中 `code_file` 指向的代码文件后推送。脚本不会修改 `mode`/`slug`/`status`（避免误启停）；如需切换启停请走 `POST /api/scripts/{id}/enable|disable`。
+## 创建与更新
 
-### ⚠️ code_file 一致性（强制）
+- 更新资源：修改 index 条目及其引用文件，再运行 `draftgo push <type> [id...]`。
+- 创建资源：在对应 index 中加入不带 `id` 的完整条目并创建引用文件，再运行 `draftgo push <type>`。
+- 创建成功后重新读取 index。CLI 会回写服务端 `id`，并可能把引用文件重命名为服务端约定名称。
+- 修改已有页面、导航、文档或服务时，直接编辑 index 中 `html_file`、`content_file`、`code_file` 指向的文件；重命名文件时同步修改该字段。
+- 不带 id 的创建支持 `pages`、`nav`、`db_meta`、`aihub`、`docs`、`doc_categories`、`custom_scripts`。系统配置按 `config_key` 更新或创建；角色与用户只更新已有记录。
 
-> **推送脚本只读 `index.json` 中 `code_file` 字段指向的文件。如果你修改了代码但文件名与 `code_file` 不一致，推送的是旧代码。**
+可推送类型：
 
-修改自定义脚本前**必须**：
-1. 先读 `.draftgo/custom_scripts/index.json`，确认目标脚本的 `code_file` 值
-2. **直接修改 `code_file` 指向的那个文件**，不要新建同名/重命名文件
-3. 如果确实需要重命名代码文件，**必须同步更新 `index.json` 中的 `code_file` 字段**
+`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
 
-违反后果：推送静默成功但上传的是旧代码，云端脚本不更新，排查极其隐蔽。
+## 资源契约
 
-### Go 服务注册规则（强制）
-
-新服务必须使用 `package main` 与 `Register(app *sdk.App)`：
-
-```go
-func Register(app *sdk.App) {
-    app.Route("GET", "/doctors", doctors)
-    app.On("doctor.updated", refresh)
-}
-
-func doctors(draftgo *sdk.Context) (any, error) {
-    return draftgo.Respond(map[string]any{"ok": true}, 200, nil), nil
-}
-```
-
-路径换算：`slug=prescription` + `app.Route("GET", "/doctors", doctors)` = `GET /api/x/prescription/doctors`。一个服务可混合多个 route、event、scheduled handler；新服务使用 `mode=mixed`。旧 `triggers` 字段不是 Go 注册来源。
-
-route 脚本推送后的完成证据不能只看 `OK script_id=...`；至少还要真实请求目标端点，确认返回不是 404。需要鉴权时带管理员或允许角色 token 验证。
-
-### route handler 与 SDK 运行时（强制）
-
-handler 签名为 `func handler(draftgo *sdk.Context) (any, error)`。`draftgo` 是普通局部变量名，可自定义；本 skill 统一用它强调平台能力。Route 输入位于 `draftgo.Input`：`body`、`query_params`、`headers`、`method`、`path_params`；`path_params` 只含 `slug/path`，不解析 `{id}` 模板。身份用 `draftgo.Auth.CurrentUser()`，状态码和响应头用 `draftgo.Respond(...)`。
-
-### 显式管理员 SDK 调用（随代码同步）
-
-`draftgo.Admin.*` 是 Go 服务源码的一部分；它不对应 `admin_access`、`system_capabilities` 或其他 index 配置字段。pull/push 只同步 `code_file`、`go_mod`、`go_sum`，**绝不**在本地元数据、服务源码、页面或请求中写入 SAT。
-
-```go
-// 普通调用继承 Route 调用者权限。
-mine, err := draftgo.DB.Query("order", sdk.QueryOptions{})
-
-// 只有这一项调用以平台管理员身份执行，运行时自动记录审计。
-catalog, err := draftgo.Admin.DB.Query("internal_catalog", sdk.QueryOptions{})
-```
-
-`draftgo.Admin` 对齐普通 SDK 的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub`。管理员服务可使用完整平台权限；调用方返回前仍应显式组装允许暴露的字段。包含 `draftgo.Admin.` 的服务推送后，除 route 真实请求外，还必须回读 `/api/scripts/{id}/executions/{execution_id}`，确认 `logs` 有 `Admin SDK call` 审计项。
-
-### ctx.DB.Query 分页语义（强制）
-
-自定义服务里的 `ctx.DB.Query(type, sdk.QueryOptions{...})` 返回 `sdk.QueryResult`：
-
-```go
-result, err := ctx.DB.Query("order", sdk.QueryOptions{Page: 1, PageSize: 20})
-```
-
-- `sdk.QueryResult` 提供 `Items`、`Total`、`Page`、`PageSize`。
-- 使用 `Page` 与 `PageSize` 明确分页；需要完整数据时按 `Total` 逐页读取。
-- `filters` 默认是 `eq` 精确匹配；字段必须在 db_meta schema 中标记 `searchable`，操作符规则见 `specs/data.md`。
-
-### 权限与安全配置（强制区分）
-
-- `scripts:read/create/update/delete/execute` 是服务管理面的角色 RBAC；创建和编辑权限只授予可信代码编辑者。
-- `permission` 决定谁能调用 route 服务：`public` / `login` / `admin` / 指定 roles。
-- `config.route_security` 决定运行时护栏：`auth_required`、`rate_limit_per_minute`、`burst_limit`、`max_body_size_kb`、`timeout_ms`、`ip_allowlist`、`ip_blocklist`。
-- `permission` 为空时默认公开；如服务不应公开，必须显式设置 `permission.default` 或 `route_security.auth_required=true`。
-- 管理权限不自动获得 route 调用权限；推送时不要因调用者是管理员或编辑者而省略 `permission`。
-- 管理员 SDK 不是 Route 自动提权：只有代码显式调用 `draftgo.Admin.*` 的单次 SDK 操作提升为管理员身份；其余 `draftgo.DB` 等调用仍按 Route 调用者权限执行。
-- 高并发服务配置 `max_concurrency` / `queue_timeout_ms`，并让调用方处理 HTTP 429；不要依赖不存在的自动重试配置。
-
-## 推送语义
-
-`pull` 只负责从云端拉取到本地，`push` 只负责把本地文件推送到云端。push 不做云端 `updated_at` 对比，也不会因为云端时间更新而跳过资源；请在推送前自行确认本地文件就是要生效的版本。
-
-**CLI 用法**：
-```bash
-draftgo push pages
-```
-
-**脚本直接调用**：
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages
-```
-
-## 推送方式
-
-**所有类型必须用 Python 脚本推送，禁止用 curl。**
-
-curl 在 Windows/Git Bash 环境下传输大 HTML / JSON 时会报 `Argument list too long`（exit 126）。
-统一使用 `draftgo_push.py` 或临时 Python 脚本（`urllib.request`）进行推送。
-
-## 接口说明
-
-**页面推送**：`PUT /api/pages/{id}`
-
-payload 必须包含完整元数据（从 `pages/index.json` 读取）+ HTML：
-```json
-{
-  "title": "...",
-  "route": "...",
-  "tag": null,
-  "menu": "...",
-  "status": "active",
-  "permission": { "default": "login", "roles": [...] },
-  "value": { "html": "完整HTML字符串" }
-}
-```
-缺少任何字段会返回 422。`value` 是 `{"html": "..."}` 的 dict，不是字符串。
-
-**导航栏推送**：`PUT /api/navigations/{id}`，payload 为 `{"html": "..."}` 字符串。
-
-**DB Meta 推送**：`PUT /api/db-meta/{id}`，payload 含 `type`, `label`, `describe`, `schema`, `permission`, `schema_validation`, `extra`。
-
-**AI 资产推送**：`PUT /api/aihub/{id}`，payload 子集：`type`, `name`, `data`, `priority`, `version`, `tags`, `describe`, `permission`, `status`。
-
-**系统配置推送**：`PUT /api/system/{config_key}`。前端全局层和受保护系统默认配置只推 `config_value`(parsed)；自定义配置可推 `value_type`, `category`, `description`, `is_sensitive`, `status`，不存在时再 `POST /api/system/` 创建。
-
-**角色推送**：`PUT /api/roles/{id}`，payload 含 `name`, `description`, `status`, `sort_order`, `user_visible`。
-
-**用户推送**：`PUT /api/users/{id}`，payload 子集：`username`, `email`, `phone_number`, `nickname`, `avatar`, `status`, `notes`（不含 password / role_ids）。
-
-**文档推送**：`PUT /api/docs/articles/{id}`，payload 子集：`title`, `slug`, `category_id`, `summary`, `content`(从 `.md` 文件读取), `cover`, `tags`, `status`, `is_top`, `sort_order`, `seo_title`, `seo_description`, `permission`。
-
-**文档分类推送**：`PUT /api/docs/categories/{id}`，payload：`name`, `slug`, `description`, `icon`, `parent_id`, `sort_order`, `status`。
-
-**自定义脚本推送**：`PUT /api/scripts/{id}`，payload 子集：`name`, `description`, `code`(从语言对应的代码文件读取), `config`, `permission`。触发器只来自代码装饰器，不发送旧 `triggers` 字段。注意 schema 不接受 `mode`/`status`，启停请走 `POST /api/scripts/{id}/enable|disable`。
+- 页面、导航或新资源：推送前运行 `draftgo check`。
+- 自定义服务：修改前读取 `../references/custom-services.md`；推送后请求目标 `/api/x/<slug><route-path>`，不能只以推送成功作为完成证据。
+- 包含 `draftgo.Admin.*` 的服务：真实调用后回读执行详情，确认管理员 SDK 调用已进入审计。
+- 动态 DB：按 `../references/data.md` 和当前 `db_meta` schema 验证真实读写。
+- 系统配置、角色和用户：推送后回读关键字段，确认没有覆盖未登记的关系或敏感值。
 
 ## 失败处理
 
-如果报错 `未找到 .draftgo/config.json`，提示用户先运行 `/draftgo init`。
-
-如果报错 HTTP 401，提示：
-```
-⚠️ Token 无效，请重新运行 /draftgo init 更新 token。
-```
+- 缺少 `.draftgo/config.json`：运行 `draftgo connect`。
+- HTTP 401：重新运行 `draftgo connect` 更新令牌。
+- 指定 id 未登记：重新读取对应 index 或先运行 `draftgo pull <type> [id...]`，不要猜测 id。
+- 推送返回非零状态：停止交付并处理错误，不把部分成功视为完整完成。

package/resources/skill/references/aihub.md

@@ -0,0 +1,86 @@
+---
+read_when: 创建或调优 AI Agent 时 · 编辑 .draftgo/aihub/ 时 · 需要工具/子智能体/记忆/多轮/结构化输出/多模态时
+---
+
+# AIHub / Agent 资源
+
+AIHub 资源既是「模型供应商」定义，也是「Agent」定义。本地登记在 `.draftgo/aihub/index.json`
+（`pull_simple`：只有 index，**没有独立内容文件**——整个 Agent 就是一条 JSON 行）。
+`push` 只发送这些字段：`type, name, data, priority, version, tags, describe, permission, status`。
+**Agent 的全部行为都在 `data`（尤其 `data.spec`）里**——本页就是 `data.spec` 的字段地图。
+
+## 条目骨架
+
+```jsonc
+{
+  "type": "agent",                 // AIHub 条目类型（模型条目为供应商类型）
+  "name": "产品顾问",
+  "describe": "面向用户的产品答疑助手",
+  "status": "active",
+  "data": {
+    "mode": "chat",                // chat | image_generation
+    "spec": { /* 见下表 */ }
+  }
+}
+```
+
+页面对话 UI 使用 `<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID">` 或 `DraftGoChat.create()`；
+旧代码/无 UI 文本调用可用 `DraftGoAI.chat(...)`，图片模式使用 `DraftGoAI.images(...)`。调用前都必须加载
+`/assets/draftgo-chat.js`，完整用法见 `references/chat-sdk.md`。后端为 `POST /api/agents/{id}/chat|images`。
+可调用 Agent 列表 `GET /api/agents`，见 `references/api-endpoints.md`。
+
+## `data.spec` 字段地图
+
+留空即维持默认/旧行为；除标注外都是可选。运行时统一在 `parseOrchestrationConfig` + 就地读取时带默认值与 clamp。
+
+| 字段 | 类型 / 取值 | 说明 |
+|---|---|---|
+| `mode` | `chat` / `image_generation` | 决定走 `/chat` 还是 `/images`；调错接口会被后端拒绝 |
+| `model` | string | 主模型（逻辑模型名，映射到供应商路由） |
+| `fallback_models` | string[] | 主模型失败后按序回退（跨模型 failover） |
+| `model_selection.user_selectable` | bool | 是否允许调用方在请求里覆盖 `model`（配合 `selectable-models`） |
+| `ttft_timeout` | number（秒，1–600，空=不启用） | 首字超时 failover：首个 SSE data 事件超时即跨模型+跨供应商切换，推理模型不误杀 |
+| `sync_request_timeout` | number（秒，1–600，默认 100） | 非流式请求上限 |
+| `stream_ttl` | number（秒，1–3600，默认 600） | 流式请求上限 |
+| `reasoning_effort` | `minimal`/`low`/`medium`/`high` | 纯透传，仅 OpenAI 系模型生效 |
+| `system_prompt_template` | string | 系统提示模板 |
+| `context.max_history` | number（默认 20） | 工作窗口：保留最近 N 条；关闭持续对话时即滑动窗口硬上限 |
+| `output_format.mode` | `text` / `json` | JSON 时按 `output_format.json.{schema,schema_name,strategy}` 约束/校验/降级 |
+| `capabilities.vision.{enabled,input,max_mb}` | 见值 | 图片/视觉输入（`image_url` part），`input`⊂{base64,url}，默认 5MB |
+| `capabilities.files.{enabled,allowed_ext,max_mb}` | 见值 | 文件附件抽取成文本注入；白名单 `.txt .md .docx .pdf .xlsx .json .csv`（pptx 不支持），默认 8MB |
+| `tools.max_iterations` | 1–50（默认 10） | ReAct 工具循环步数上限 |
+| `tools.sources[].{type,id}` | `mcp` / `custom_script` | 绑定 MCP 与「自定义服务作为工具」 |
+| `knowledge_base_ids` | int[] | 绑定知识库，生成检索工具 |
+| `skills` | 见运行时 | 绑定 Skill |
+| `sub_agent_ids` | int[] | 子智能体：为每个 id 生成 `agent_{id}` 委派工具（用法同 `knowledge_base_ids`） |
+| `call_permissions` | 角色配置 | 谁能调用此 Agent（`GET /api/agents` 据此过滤） |
+
+### `orchestration.*`（编排开关）
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `tool_concurrency` | 8（1–32） | 单步内并发执行工具数 |
+| `on_max_steps` | `error` | 达步数上限：`error` 报错 / `stop` 返回最后一条 |
+| `tool_disclosure.{mode,threshold_tools}` | `off` | 工具渐进披露：`off`/`auto`/`always`，首轮只给目录+`load_tools` |
+| `planning.{enabled,prompt}` | false | 规划层：执行前先让模型列步骤，提示折叠进 system |
+| `memory.{enabled,scope}` | false / `user_agent` | 长期记忆：对话后自动提炼、下轮召回注入；作用域 `agent`/`user`/`user_agent` |
+| `compaction.{enabled,keep_recent,trigger_messages,trigger_tokens,preset}` | 关闭 | **持续对话/上下文闭环**：见下 |
+| `checkpoint_input_mode` / `checkpoint_max_messages` / `checkpoint_ttl_seconds` | 全量 / 100 / 86400 | 会话历史持久化（配合请求 `session_id`） |
+| `delegation.{max_depth,max_total_calls}` | 2 / 8 | 子智能体委派的深度与调用预算护栏 |
+
+### 持续对话（上下文闭环）
+
+- `compaction.enabled=true` = 闭环：填满工作窗口后把溢出旧消息**摘要成一条滚动 summary** 续接，
+  而非直接丢弃。此时后端**跳过 `context.max_history` 硬砍**，让完整 checkpoint 历史进入压缩器蒸馏。
+- 触发为双通道任一命中：`trigger_messages`（条数）或 `trigger_tokens`（估算 token，256–2000000）。
+- `keep_recent`：保留最近 N 条不压缩。`preset`（`aggressive`/`balanced`/`conservative`）是管理台档位回显，
+  后端只认 `keep_recent`/`trigger_messages`/`trigger_tokens` 三个底层字段。
+- 配合请求体 `session_id` 才会加载/续写会话历史；`<dg-chat>` 为每个 UI thread 自动维护该值，兼容门面可通过 `DraftGoAI.chat(..., {sessionId})` 显式传入。不传即无状态单轮。
+- 关闭时逐字回退为 `max_history` 滑动窗口（旧行为，零影响）。
+
+## 观测
+
+每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
+接口：`GET /api/aihub/runs`、`GET /api/aihub/runs/{trace_id}`、`DELETE /api/aihub/runs`。
+
+> 权威细节以 DraftGo 后端 `docs/backend/modules/agent-runtime.md` 为准；本页是基座开发者视角的字段速查。

package/resources/skill/{quickref → references}/api-endpoints.md

@@ -4,10 +4,11 @@ read_when: 需要查具体 API 端点时 · 构造请求时
 
 # 后端 API 速查
 
-> 优先运行 `draftgo api <keyword>` 做结构化查询；需要完整 OpenAPI 时见 [api.json]({{SKILL_SHARED}}/quickref/api.json)。
+> 优先运行 `draftgo api <keyword>` 做结构化查询；需要完整 OpenAPI 时见 [api.json]({{SKILL_SHARED}}/references/api.json)。
+> `draftgo api` 仅索引 DraftGo 底座 API。自定义服务的运行时路由由本地 `app.Route` 动态注册，不会出现在该 OpenAPI 中；按 `<METHOD> /api/x/<slug><route-path>` 推导，推送后必须请求无副作用 GET Route 验证。
 > 统一响应信封：`{ code: 200, data: <载荷>, message: "success" }`
 > GET 列表端点通常在不传 `page` / `page_size` 时全量返回；自定义服务执行记录是固定分页特例（默认 20，最大 100）。
-> Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，筛选和分页见 `specs/custom-services.md`。
+> Go 自定义服务使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，筛选和分页见 `references/custom-services.md`。
 
 ## 认证
 
@@ -54,9 +55,9 @@ PUT/DELETE    /api/navigations/{id}
 GET            /api/db/{type}
                支持 filters/order_by/order/page/page_size/populate/scope=mine
                scope=mine 仅 admin 用户的列表 GET 生效：非后台业务页用，后台管理页不用
-               📌 filters 语法 → specs/data.md#filters-操作符
-               📌 searchable 模式 → specs/data.md#searchable-字段标记
-               📌 ref/populate/onDelete → specs/data.md#关联关系ref
+               📌 filters 语法 → references/data.md#filters-操作符
+               📌 searchable 模式 → references/data.md#searchable-字段标记
+               📌 ref/populate/onDelete → references/data.md#关联关系ref
 POST           /api/db/{type}       body: { data: {...} } 或数组
 PATCH          /api/db/{type}/batch
 GET/PUT/DELETE /api/db/{type}/{id}
@@ -95,24 +96,49 @@ ANY              /api/x/{slug}/{path}   ← 脚本运行时端点
 - route 注册来自 `app.Route("METHOD", "/path", handler)`；一个服务可声明多个 route，共用同一个 slug 命名空间。
 - event 和 scheduled 分别来自 `app.On(...)` 与 `app.Schedule(...)`；均支持在一个服务内声明多个 handler。
 - 旧 `triggers` 字段不参与注册，CLI 不再创建或推送该字段。
-- route handler 签名：`func handler(ctx *sdk.Context) (any, error)`；实际字段位于 `ctx.Input`，用户身份用 `ctx.Auth.CurrentUser()`。
+- route handler 签名：`func handler(draftgo *sdk.Context) (any, error)`；实际字段位于 `draftgo.Input`，用户身份用 `draftgo.Auth.CurrentUser()`。
 - Route 的普通 SDK 调用继承当前调用者资源权限，管理员创建服务不自动提升；需要管理员权限时逐次显式调用 `draftgo.Admin.DB`、`draftgo.Admin.Users` 等。`Admin` 调用以管理员身份执行并自动写入执行审计，但不会向代码暴露 SAT。带 `user_id` / `actor_user_id` 的事件继承该用户，定时任务及无可解析用户的事件才是系统身份。
 - 路径换算：`slug=order` + `app.Route("POST", "/pay", handler)` → `POST /api/x/order/pay`。
 - route 是精确路径匹配，不支持 `/items/{id}` 参数模板；ID 使用 query/body。
-- 动态数据访问使用 `ctx.DB.Query("order", sdk.QueryOptions{...})`，结果为 `sdk.QueryResult`；筛选与分页见 `specs/custom-services.md`。
+- 动态数据访问使用 `draftgo.DB.Query("order", sdk.QueryOptions{...})`，结果为 `sdk.QueryResult`；筛选与分页见 `references/custom-services.md`。
 - `permission` 控制调用权限；`config.route_security` 控制限流、IP、body 大小和超时。
 - `scripts:*` 控制服务管理权限，和 Route 的调用权限彼此独立；执行列表固定分页，详情日志按单条加载。
 - `config.max_concurrency` / `queue_timeout_ms` 控制服务级退避；Route 饱和返回 429。
-- 完整 SDK、ctx、AIHub、事件、配置与运行限制见 `specs/custom-services.md`。
+- 完整 SDK、`draftgo`、AIHub、事件、配置与运行限制见 `references/custom-services.md`。
 
 ## AIHub & AI推理
 
 ```
-GET/POST   /api/aihub
-POST       /api/aihub/{id}/sync
+GET/POST   /api/aihub                     ← AIHub 资源（模型/Agent 定义）CRUD
+POST       /api/aihub/{id}/sync           ← 同步供应商模型目录
 GET        /api/v1/models
-POST       /api/v1/chat/completions      ← OpenAI 兼容格式
-POST       /api/agents/{id}/chat, /api/agents/{id}/images
+POST       /api/v1/chat/completions       ← OpenAI 兼容格式（直连模型）
+POST       /api/v1/embeddings             ← 向量嵌入（OpenAI 兼容）
+POST       /api/v1/images/generations     ← 图片生成（OpenAI 兼容）
+```
+
+Agent 调用面（页面/调用方用 agent id 调用，不是直连模型）：
+```
+GET        /api/agents                    ← 列出当前用户可调用的 Agent（拿 id/name/describe）
+GET        /api/agents/{id}/selectable-models  ← { user_selectable, models }
+POST       /api/agents/{id}/chat          ← 对话，见下方 body；stream=true 返回 SSE
+POST       /api/agents/{id}/images        ← 图片模式 Agent（body.prompt 必填）
+POST       /api/agents/{id}/preview-chat  ← 只解析不执行：回 { model, fallback_models, candidate_provider_ids, messages }，用于调试路由
+```
+
+`/api/agents/{id}/chat` 请求体：
+```
+{ messages:[{role,content}] | message:"简写字符串", stream?:bool,
+  model?:"覆盖模型", session_id?:"多轮会话键", context?:{} }
+```
+- `stream:true` → `text/event-stream`，逐帧 `data: {...}`，以 `data: [DONE]` 结束；否则返回 OpenAI 风格完整结果。
+- 传 `session_id` 且 Agent 开启持续对话（checkpoint）时，服务端加载并续写该会话历史；不传即无状态单轮。
+
+AI 运行观测（`/admin/ai-runs` 页数据源）：
+```
+GET        /api/aihub/runs                ← 运行列表，支持 status/model/trace_id/agent_id/event_type/time_start/time_end + 分页
+GET        /api/aihub/runs/{trace_id}     ← 单次运行详情（含 spans / tokens / ttft_ms / 延迟）
+DELETE     /api/aihub/runs                ← 按 trace_ids 或时间范围批量清理
 ```
 
 ## 文档中心
@@ -132,7 +158,7 @@ GET/POST     /api/system/backup
 POST         /api/system/restore, /api/system/reset
 POST         /api/system/restore/selective?mode=replace|merge|append
 POST         /api/upload
-GET          /api/logs
+GET          /api/system/logs
 ```
 
 ## 二次认证（高危操作前必须）