draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/init/SKILL.md

@@ -1,77 +1,28 @@
 ---
 name: draftgo-init
-description: Use this skill when the user runs "/draftgo init", wants to initialize a DraftGo development project, connect to a DraftGo server, or set up DraftGo development context for the first time.
-version: 1.0.0
-allowed-tools: Bash(python:*), Bash(find:*), Read
+description: Install or refresh the DraftGo skill in a project, inspect supported AI-tool targets, and bind the project to an existing or local DraftGo base.
 ---
 
-# DraftGo 项目初始化
+# DraftGo 初始化
 
-## 第一步：收集连接信息
+使用公开 CLI 完成安装和连接，不直接调用 `scripts/` 下的内部脚本。
 
-检查是否已有配置：
+## 执行
 
-```
-!test -f .draftgo/config.json && cat .draftgo/config.json || echo "NOT_FOUND"
-```
+1. 运行 `draftgo status` 查看已安装目标和 Skill 版本。
+2. 需要查看支持的 AI 工具时，运行 `draftgo list-targets`。
+3. 尚未安装时运行 `draftgo init [target...]`；不指定 target 时由 CLI 自动识别。
+4. 已安装但需要刷新时运行 `draftgo update [target...]`，该命令同时完全更新全局 CLI 与已安装 Skill。
+5. 项目缺少 `.draftgo/config.json` 时选择基座：
+   - 已有 DraftGo 服务器：运行 `draftgo connect`。
+   - 需要本地 Docker 基座：运行 `draftgo local setup`。
+6. 连接完成后运行 `draftgo map`，确认页面、导航、数据、自定义服务和系统资源已进入本地上下文。
 
-- **已存在**：询问用户是否覆盖，确认后继续
-- **不存在**：向用户询问：
-  1. DraftGo 服务器地址（如 `https://your-server.com`）
-  2. 系统访问令牌（SAT，管理后台 → 系统设置 → API Token）
+`draftgo init` 负责安装 Skill；`draftgo connect` 负责写入服务器连接并拉取初始上下文。不要混用两者的职责。
 
----
-
-## 第二步：执行初始化脚本
-
-脚本位于 `{{SKILL_SCRIPTS}}/draftgo_init.py`，直接运行（**不要读取脚本内容**）：
-
-```
-# 默认：项目根由脚本自动推导（向上查找含 .draftgo/ 的目录）
-!DRAFTGO_TOKEN="<token>" python {{SKILL_SCRIPTS}}/draftgo_init.py --server "<server>"
-
-# 用户明确指定了项目路径时，作为位置参数传入
-!DRAFTGO_TOKEN="<token>" python {{SKILL_SCRIPTS}}/draftgo_init.py --server "<server>" "<project_path>"
-```
-
-脚本会自动完成所有工作并输出摘要，**不要读取任何中间 JSON 文件**。
-
----
-
-## 第三步：确认结果
-
-脚本执行完毕后，确认 `.draftgo/config.json` 生成成功：
-
-```
-!test -f .draftgo/config.json && echo "OK" || echo "FAIL"
-```
-
----
-
-## 初始化目录
-
-脚本执行完毕后，确保以下目录存在（不存在则创建）：
-
-```
-!mkdir -p .draftgo/lessons .draftgo/Task
-```
-
-- `.draftgo/changelog.md`：更新日志（单文件，按日期分节）
-- `.draftgo/lessons/`：开发经验与问题记录（按 `YYYY-MM-DD-主题.md` 命名）
-- `.draftgo/Task/`：每个开发任务一个 Markdown 文件，含需求纪要 / 设计 / 任务清单 / 进度标记
-
-> **注意：`.draftgo/story.yaml` 不在 init 流程中创建。** Story 文件由 AI 在首次开发对话时通过 Story 门禁流程自动构建（见 `{{SKILL_DIR}}/story/SKILL.md`），确保它是基于与开发者对话理解后生成的，而不是空模板。
-
-## 完成提示
-
-将脚本的输出摘要（页面数、导航数、文档数、自定义脚本数、外部 API 数、服务器地址）告知用户，并提示：
-- 下一步：描述要开发的功能，或运行 `/draftgo push` 推送修改
-- 如需刷新数据：运行 `/draftgo pull`（按类型增量拉取）或 `/draftgo pull --all`（全量刷新）
-- 已拉取的资源分布：
-  - `.draftgo/pages/`、`.draftgo/navigations/`：页面与导航 HTML
-  - `.draftgo/docs/articles/`：文档中心文章正文（Markdown），分类索引在 `.draftgo/doc_categories/index.json`
-  - `.draftgo/custom_scripts/`：自定义脚本代码（按 language 落到 `.py`/`.js` 等），meta 在同目录 `index.json`
-  - `.draftgo/external_apis/index.json`：外部 API 注册（`auth_config` 已脱敏）
-- 修改这些资源后通过 `/draftgo push <类型>` 推回云端，类型见根 SKILL.md。
+## 后续动作
 
-> 注意：拉取 `external_apis` / `docs` (admin 列表) / `custom_scripts` 都需要 SAT 具备 admin 权限。若任一项返回 0 条但用户期望应有数据，提醒用户检查 token 角色。
+- 刷新云端资源：`draftgo pull [type] [id...]`
+- 管理本地基座：`draftgo local start|stop|logs|status`
+- 移除指定目标：`draftgo uninstall <target>`
+- 完整移除所有目标：仅在用户明确要求时运行 `draftgo uninstall all`；`--purge` 还会删除项目的 `.draftgo/` 数据。

package/resources/skill/manifest.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "id": "draftgo",
+  "name": "DraftGo 开发助手",
+  "version": "3.0.33",
+  "entry": "SKILL.md",
+  "description": "DraftGo 应用的开发、资源同步、验证与交付工作流。",
+  "license": "MIT",
+  "capabilities": [
+    "draftgo-development",
+    "custom-service-ai-sdk",
+    "resource-sync",
+    "project-validation",
+    "skill-installation"
+  ],
+  "permissions": [
+    "workspace:read",
+    "workspace:write",
+    "process:run",
+    "network:explicit"
+  ],
+  "resources": {
+    "references": ["references"],
+    "scripts": "scripts",
+    "subskills": ["init", "pull", "push", "story"]
+  }
+}

package/resources/skill/pull/SKILL.md

@@ -1,59 +1,33 @@
 ---
 name: draftgo-pull
-description: Use this skill when the user says "拉取页面", "拉取数据库", "拉取导航", "拉取全部", "pull pages", "pull db_meta", "pull nav", "pull all", "/draftgo pull", or wants to refresh local .draftgo files from the DraftGo server.
-version: 1.0.0
-allowed-tools: Bash(python:*), Read, Glob
+description: Pull all or selected DraftGo resources from the connected server into local .draftgo indexes and referenced files before inspection or modification.
 ---
 
-# DraftGo 拉取（云端 → 本地）
+# DraftGo 拉取
 
-> **STOP — 禁止用 curl、禁止自己写 Python 拉取逻辑。**
-> 唯一正确方式：运行下方 Python 脚本。
+使用 `draftgo pull`；内部 Python 脚本由 CLI 定位和执行。
 
-脚本位于：`{{SKILL_SCRIPTS}}/draftgo_pull.py`
-
-## 拉取全部（"拉取全部" / "pull all"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py --all
-```
-
-## 按类型拉取
+## 命令
 
+```bash
+draftgo pull
+draftgo pull <type> [id...]
 ```
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py pages          [page_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py nav            [nav_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py db_meta        [db_meta_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py aihub          [aihub_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py external_apis  [api_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py system_config  [config_key ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py docs           [article_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py doc_categories [category_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py custom_scripts [script_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py roles          [role_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py users          [user_id ...]
-```
-
-脚本会自动读取 `.draftgo/config.json` 获取 server 和 token。
 
-## 使用场景
+不带参数时拉取全部资源。支持的类型：
 
-- 通过 API / 后台管理界面直接创建了资源（如 db_meta），本地 index.json 没更新
-- 多人协作时需要同步其他人的修改
-- 本地文件损坏或过期，需要刷新
+`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
 
-## 与 init 的区别
+## 执行
 
-| 命令 | 功能 |
-|------|------|
-| `/draftgo init` | 首次配置（写 config.json + .gitignore）+ 全量拉取 |
-| `/draftgo pull` | 仅拉取，不改配置，支持按类型增量拉取 |
+1. 在本地资源缺失、过期、损坏，或用户明确要求同步云端版本时运行 pull。
+2. 只拉取当前工作需要的类型或 id；需要建立完整项目上下文时运行无参数的 `draftgo pull`。
+3. 拉取后重新读取对应 `index.json` 以及其中 `html_file`、`content_file`、`code_file` 指向的文件。
+4. 修改自定义服务前，确认 `code_file`、`go_mod`、`go_sum` 已同步，并读取 `../references/custom-services.md`。
+5. 运行 `draftgo map` 确认跨资源入口或依赖已更新。
 
 ## 失败处理
 
-如果报错 `未找到 .draftgo/config.json`，提示用户先运行 `/draftgo init`。
-
-如果报错 HTTP 401，提示：
-```
-⚠️ Token 无效，请重新运行 /draftgo init 更新 token。
-```
+- 缺少 `.draftgo/config.json`：运行 `draftgo connect`。
+- HTTP 401：连接令牌无效，重新运行 `draftgo connect`。
+- 返回空列表但预期存在资源：检查令牌是否具备对应读取权限，不把空结果直接当成资源不存在。

package/resources/skill/push/SKILL.md

@@ -1,265 +1,48 @@
 ---
 name: draftgo-push
-description: Use this skill when the user says "推送页面", "推送导航", "推送数据库", "推送AI资产", "推送外部API", "推送系统配置", "推送角色", "推送用户", "推送文档", "推送文档分类", "推送自定义脚本", "同步页面", "同步导航", "同步数据库", "同步AI资产", "同步外部API", "同步系统配置", "同步角色", "同步用户", "同步文档", "同步文档分类", "同步自定义脚本", "push pages", "push nav", "push db_meta", "push aihub", "push external_apis", "push system_config", "push roles", "push users", "push docs", "push doc_categories", "push custom_scripts", "sync pages", "sync nav", "sync db_meta", "sync aihub", "sync external_apis", "sync system_config", "sync roles", "sync users", "sync docs", "sync doc_categories", "sync custom_scripts", "/draftgo push", "/draftgo sync", or wants to push local changes to the DraftGo server.
-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 / external_apis / 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 / external_apis / 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 资产 |
-| external_apis | `code`, `name`, `base_url` | code 不可包含 `/` 或空格；创建时不发送 status |
-| docs | `title` | 其余字段有默认值 |
-| doc_categories | `name` | slug 可选；不填由后端生成/处理 |
-| custom_scripts | `name`, `slug`, `mode`, `triggers` | mode=route/event/scheduled；创建后默认覆盖代码，启停仍走 enable/disable |
-
-> **创建后必须以脚本回写的 index 为准**，不要手动猜 id。回写后建议 `git diff` 或重新读 index 确认 `id` 已落地。
-
-## 推送页面（"推送页面" / "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`。
-
-## 推送外部 API（"推送外部API" / "push external_apis"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis
-!python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis <api_id>
-```
-
-读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/external-apis` 创建，成功后回写新 `id`。创建最少需要 `code`、`name`、`base_url`。
-
-## 推送系统配置（"推送系统配置" / "push system_config"）
-
-```
-!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`。
-
-## 推送角色（"推送角色" / "push roles"）⚠️ 需二次确认
-
-roles 涉及权限安全，**强制要求人工确认**：
-
-1. 读取 `.draftgo/roles/index.json`
-2. **向用户展示即将推送的变更内容**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py roles
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py roles <role_id>
-   ```
-5. 用户拒绝则不推送
-
-## 推送用户（"推送用户" / "push users"）⚠️ 需二次确认
-
-users 涉及账号安全，**强制要求人工确认**：
-
-1. 读取 `.draftgo/users/index.json`
-2. **向用户展示即将推送的变更内容**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py users
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py users <user_id>
-   ```
-5. 脚本不会下发 password / role_ids；如需修改请走专用接口
-
-## 推送文档（"推送文档" / "push 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`（同目录 `.md` 文件）回填，按 `ArticleUpdate` schema 推送。修改文档时**直接改 `.md` 文件**即可，索引项保持稳定。
-
-## 推送文档分类（"推送文档分类" / "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"）⚠️ 需二次确认
-
-脚本代码会以**生效语义**直接覆盖云端运行的脚本，**强制要求人工确认**：
-
-1. 读取 `.draftgo/custom_scripts/index.json`，并读取每条 meta 中 `code_file` 指向的代码文件
-2. **向用户展示即将更新的脚本与摘要差异**
-3. **等待用户明确确认**
-4. 确认后运行：
-   ```
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts
-   !python {{SKILL_SCRIPTS}}/draftgo_push.py custom_scripts <script_id>
-   ```
-5. 脚本不会修改 `mode`/`slug`/`status`（避免误启停）；如需切换启停请走 `POST /api/scripts/{id}/enable|disable`
-
-### ⚠️ code_file 一致性（强制）
-
-> **推送脚本只读 `index.json` 中 `code_file` 字段指向的文件。如果你修改了代码但文件名与 `code_file` 不一致，推送的是旧代码。**
-
-修改自定义脚本前**必须**：
-1. 先读 `.draftgo/custom_scripts/index.json`，确认目标脚本的 `code_file` 值
-2. **直接修改 `code_file` 指向的那个文件**，不要新建同名/重命名文件
-3. 如果确实需要重命名代码文件，**必须同步更新 `index.json` 中的 `code_file` 字段**
-
-违反后果：推送静默成功但上传的是旧代码，云端脚本不更新，排查极其隐蔽。
-
-## 冲突检测（多窗口协作保护）
-
-> push 前会自动检测云端是否已被他人修改，防止静默覆盖。
-
-**工作原理**：pull 时 `index.json` 会记录每条资源的 `updated_at`。push 时先 GET 云端当前 `updated_at`，与本地基线比对：
-
-- **一致** → 正常推送
-- **不一致** → 跳过该条，打印警告，继续推下一条
-- **`--force`** → 跳过检测，直接覆盖
-
-**典型场景**：
-
-| 场景 | 行为 |
+| 意图 | 命令 |
 |---|---|
-| 单窗口正常 push | 无变化，正常推 |
-| 窗口 A push 后，窗口 B push 同一资源 | B 检测到冲突 → 跳过 |
-| B 先 `draftgo pull` 再 push | pull 刷新基线 → 正常推 |
-| 确定要覆盖 → `draftgo push --force` | 跳过检测，强制覆盖 |
-
-**CLI 用法**：
-```bash
-draftgo push pages          # 带冲突检测
-draftgo push pages --force  # 跳过检测，强制覆盖
-```
-
-**脚本直接调用**：
-```
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages
-!python {{SKILL_SCRIPTS}}/draftgo_push.py pages --force
-```
-
-## 推送方式
-
-**所有类型必须用 Python 脚本推送，禁止用 curl。**
-
-curl 在 Windows/Git Bash 环境下传输大 HTML / JSON 时会报 `Argument list too long`（exit 126）。
-统一使用 `draftgo_push.py` 或临时 Python 脚本（`urllib.request`）进行推送。
+| 同步已确认的本地资源 | `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` |
 
-## 接口说明
+`push` 不自动运行 `check`。`deploy` 始终先运行 `check`。`auto-push` 先检查，并且仅在 `.draftgo/config.json` 的 `auto_push` 为 `true` 时推送。
 
-**页面推送**：`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，不是字符串。
+- 更新资源：修改 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` 更新或创建；角色与用户只更新已有记录。
 
-**导航栏推送**：`PUT /api/navigations/{id}`，payload 为 `{"html": "..."}` 字符串。
+可推送类型：
 
-**DB Meta 推送**：`PUT /api/db-meta/{id}`，payload 含 `type`, `label`, `describe`, `schema`, `permission`, `schema_validation`, `extra`。
+`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
 
-**AI 资产推送**：`PUT /api/aihub/{id}`，payload 子集：`type`, `name`, `data`, `priority`, `version`, `tags`, `describe`, `permission`, `status`。
+## 资源契约
 
-**外部 API 推送**：`PUT /api/external-apis/{id}`，payload 子集：`name`, `base_url`, `method`, `path`, `headers`, `auth_type`, `auth_config`, `timeout_ms`, `permission`, `param_schema`, `tags`, `description`, `status`。
-
-**系统配置推送**：`PUT /api/system/{config_key}`，payload：`config_value`(parsed), `value_type`, `category`, `description`, `is_sensitive`, `status`。
-
-**角色推送**：`PUT /api/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`(从语言对应的代码文件读取), `triggers`, `config`, `permission`。注意 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` 为准；本页是基座开发者视角的字段速查。