draftgo-cli 2.0.5 → 2.0.9

package/README.md

@@ -25,7 +25,7 @@ DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。draftgo-cli v
 | `draftgo local status` | 查看本地栈容器状态。 |
 | `draftgo dev` | 运行当前项目 `package.json` 中的 `scripts.dev`。 |
 | `draftgo build` | 运行当前项目 `package.json` 中的 `scripts.build`。 |
-| `draftgo check` | 本地资源闭环检查，作为 push 前质量门禁。 |
+| `draftgo check` | 本地资源闭环检查，辅助发现入口绑定、缺文件、重复路由和疑似 mock 风险。 |
 | `draftgo pull` | 包装随 skill 分发的 `draftgo_pull.py`，默认 `--all` 拉取资源。 |
 | `draftgo push` | 包装随 skill 分发的 `draftgo_push.py`，推送页面、导航、DB meta 等资源。 |
 
@@ -59,7 +59,7 @@ draftgo init all                         # 所有支持的工具
 | `draftgo uninstall [target]...` | 移除指定 AI 工具的 skill 目录（含入口文件 + 子技能 + scripts）。加 `--purge` 会连 `.draftgo/` 一起删。 |
 | `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
 | `draftgo doctor` | 诊断：Python 是否可用、检测到哪些 AI 工具、各入口状态。 |
-| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、入口引用，帮助 AI 快速进入项目。 |
+| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、外部 API、文档、系统配置、入口引用，帮助 AI 快速进入项目。 |
 | `draftgo check` | 本地闭环体检：检查 route、入口绑定、文件存在性、重复路由和疑似 mock/伪功能风险。 |
 | `draftgo list-targets` | 列出支持的 AI 工具名。 |
 | `draftgo --version` | 打印 CLI 版本。 |
@@ -76,6 +76,18 @@ draftgo init all                         # 所有支持的工具
 
 可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭自动升级检查（离线、CI 等场景）。
 
+### 机器可读输出
+
+`draftgo map --output json` 会输出本地资源地图，适合 Agent 在开发前快速读取上下文；覆盖 pages、navigations、db_meta、custom_scripts、aihub、external_apis、docs、doc_categories、system_config、roles 和入口引用。AIHub 条目会包含常用配置摘要：
+
+- `type=model`：模型数量、`supports_response_format`、`supports_json_schema`、图片生成诊断摘要。
+- `type=agent`：`mode`、主模型/备用模型、`output_format`、用户选模型配置、工具来源摘要。
+- `type=mcp`：传输协议、已发现工具数量。
+
+外部 API 会摘要 `code/method/path/base_url/tags/status`，文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
+
+`draftgo check --output json` 会输出 `{ map, errors, warnings }`，适合 CI 或开发收尾时作为轻量证据。`--strict` 会把 warnings 也视为失败。
+
 ## 更新
 
 ```bash
@@ -106,6 +118,43 @@ AIHub Agent 用户选模型约定：
 - `models` 是该 Agent 的主模型 + 备用模型白名单，不是供应商全量模型列表。
 - 调用 `DraftGoAI.chat(...)` 或 `DraftGoAI.images(...)` 时，可在 `options.model` 中传入用户选择的模型；后端会继续按 Agent 白名单校验。
 
+AIHub Agent JSON 输出约定：
+
+- Agent 的结构化输出写在 `data.spec.output_format` 中；`mode="json"` 表示要求 JSON 输出。
+- `data.spec.output_format.json.strategy` 支持 `auto`、`native`、`prompt`：`auto` 会优先使用模型资产的 `supports_response_format/supports_json_schema` 诊断结果，必要时降级为提示词约束。
+- `data.spec.output_format.json.schema` 可传 JSON Schema；后端会尽量构造 OpenAI 兼容 `response_format`，流式响应结束时会追加 `json.validation` 事件。
+- 模型资产可通过 `POST /api/aihub/{id}/test-response-format` 探测并写回 `supports_response_format` 与 `supports_json_schema`。
+
+示例：
+
+```json
+{
+  "data": {
+    "schema_version": "agent.v3",
+    "spec": {
+      "model_id": 1,
+      "model": "gpt-4.1",
+      "output_format": {
+        "mode": "json",
+        "json": {
+          "strategy": "auto",
+          "schema_name": "summary",
+          "schema": {
+            "type": "object",
+            "properties": {
+              "title": { "type": "string" },
+              "tags": { "type": "array", "items": { "type": "string" } }
+            },
+            "required": ["title", "tags"],
+            "additionalProperties": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## 自动识别的依据
 
 | AI 工具 | 探测信号（任一命中即视为在用） |
@@ -158,9 +207,9 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 **分级流程**：
 
 ```
-小修：直接定位 → 改 → check → push
-轻功能：范围复述 → 直接做 → 主路径验证 → push
-标准功能：轻量确认 → Task → TDR
+小修：直接定位 → 改 → 轻量证据
+轻功能：范围复述 → 直接做 → 凭证据闭环
+标准功能：轻量确认 → 内部短计划 → 执行闭环
 高风险：完整 Story / 计划 / 验证 / 人工确认
 ```
 
@@ -186,7 +235,7 @@ CLI v2.0.3 补充操作型页面的空间模型，重点解决后台管理 / 表
 - **工作台布局原则**：后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先让页面根容器占满可用视口 / iframe 内容区。
 - **稳定控制区**：顶部筛选、搜索、标题操作区保持稳定高度，底部分页、批量操作栏、保存栏等流程控制区保持在工作区底部或稳定位置。
 - **数据区承接剩余空间**：主体数据区使用 `flex:1; min-height:0; overflow:auto` 等结构承接剩余空间，数据少时保留工作区空白，数据多时优先让数据区内部滚动。
-- **工作台结构同步**：`frontend.md` 补充操作型页面的空间方法，避免分页跟随 1-2 条数据上浮。
+- **工作台结构同步**：`rules/frontend.md` 补充操作型页面的空间方法，基座对应文档为 `docs/frontend/rules.md`，避免分页跟随 1-2 条数据上浮。
 
 ---
 
@@ -227,16 +276,16 @@ CLI v2.0.0 删除了内置 `resources/skill/reference/` 基座参考副本，进
 
 ## v1.6.2 升级要点（开发效率轻量化）
 
-CLI v1.6.2 进一步降低开发流程摩擦：保留真实功能闭环、页面绑定、平台禁区和推送验证这些硬约束，同时让小修和轻功能更快进入实现。
+CLI v1.6.2 进一步降低开发流程摩擦：保留真实落地闭环、页面绑定和平台禁区，同时让小修和轻功能更快进入实现。
 
 **核心变化：**
 
 - **小修渐进读取**：小修优先只读目标资源和最小必要规则，不再默认展开完整规则链路。
-- **新增轻功能档**：简单页面能力、单入口交互、小型数据联动可走“范围复述 → 直接做 → 主路径验证 → push”，不强制创建 Task。
+- **新增轻功能档**：简单页面能力、单入口交互、小型数据联动可走“范围复述 → 直接做 → 凭证据闭环”，不强制创建 Task。
 - **计划字段按需**：`depends / resource_lock / wave` 只在多任务、多资源冲突或准备并行时强制；单人串行小计划不再为字段服务。
 - **并行按收益启用**：只有任务数足够、边界清晰、资源不冲突且并行收益大于协调成本时才启用并行。
 - **取消 80 行硬限制**：改为“复杂或高风险代码分段实现并验证”，避免机械分批拖慢前端开发。
-- **验证按等级分层**：小修验证改动点，轻功能验证入口和主路径，标准功能 / 高风险再完整覆盖四态、数据、跳转和影响范围。
+- **验证按影响分层**：小修验证改动点，轻功能验证入口引用和主路径；标准功能按实际影响覆盖四态、数据、跳转和同步证据。
 
 ---
 
@@ -263,9 +312,9 @@ CLI v1.6.0 强化了 skill 对“开发任务规划”的判断力，重点解
 - **页面默认完整功能**：用户说“做一个页面”时，默认按可真实使用的页面功能处理；只有明确说“静态 / 纯页面 / demo / 先看效果”时，才按静态页处理。
 - **用户路径链路**：功能规划从“用户打开官网 / 系统入口 → 看见入口 → 点击进入 → 操作 → 反馈 → 后台维护 → 前台展示更新”这一整条链路倒推页面、导航、数据和权限。
 - **新增页面绑定**：创建页面后必须绑定到导航栏、首页入口、后台菜单或相关页面按钮之一；只创建页面文件、无法从正常路径点击进入，不算完成。
-- **真实功能闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，主动规划后台管理和同一份真实数据。
+- **真实落地闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，优先规划后台管理和同一份真实数据，追求高可用。
 
-这些规则保持轻量：小修仍然直接定位 → 改 → check → push；轻功能不强制 Task；标准功能只做必要确认；高风险任务才进入完整 Story / 人工确认流程。
+这些规则保持轻量：小修直接定位 → 改 → 轻量证据；轻功能不强制 Task；普通标准功能使用内部短计划；跨资源、多页面协作、并行或高风险时才落 Task。
 
 ---
 
@@ -341,10 +390,10 @@ now:
 **开发流程升级为分级门禁：**
 
 ```
-小修：直接定位 → 改 → check → push
-轻功能：范围复述 → 直接做 → 主路径验证 → 凭证据闭环
-标准功能：轻量确认 → Task → TDR → 凭证据闭环
-高风险：Story → 完整确认 → 计划 → TDR → 人工确认 / 回读验证
+小修：直接定位 → 改 → 轻量证据
+轻功能：范围复述 → 直接做 → 凭证据闭环
+标准功能：轻量确认 → 内部短计划 → 执行闭环
+高风险：Story → 完整确认 → 计划 → 人工确认 / 回读验证
 ```
 
 **注意：** `.draftgo/story.yaml` 不在 `draftgo init` 中创建。它由 AI 在首次开发对话时通过与开发者交流后生成，确保内容有意义而不是空模板。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "2.0.5",
+  "version": "2.0.9",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/SKILL.md

@@ -7,13 +7,13 @@ version: 1.0.0
 # DraftGo 开发助手
 
 > **【DraftGo 开发追求】**
-> 使用 DraftGo-CLI 开发的项目，默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。AI 应快速读懂现有资源，交付真实功能闭环，并让后续修改者能继续迭代。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。
+> 使用 DraftGo-CLI 开发的项目，默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。AI 应快速读懂现有资源，优先交付真实落地闭环、高可用的实现，并让后续修改者能继续迭代。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。
 >
 > **【开发分级 — 最高优先级】**
 > 任何开发对话开始时，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 判断任务级别**，再执行对应流程：
-> - **小修** → 直接定位 → 改 → check → push。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；仍需写 changelog。
-> - **轻功能** → 范围复述 → 直接做 → 主路径验证 → push。用于简单页面能力、单入口交互、小型数据联动，不强制 Task。
-> - **标准功能** → 轻量确认 → Task → TDR。若 `.draftgo/story.yaml` 存在则静默加载；不存在时不阻塞开发，但应在完成后提醒补 Story。
+> - **小修** → 直接定位 → 改 → 轻量证据。优先只读目标资源和最小必要规则；无需 Story 门、需求门、Task 文档；changelog / check / push 按影响选择。
+> - **轻功能** → 范围复述 → 直接做 → 凭证据闭环。用于简单页面能力、单入口交互、小型数据联动，不强制 Task。
+> - **标准功能** → 轻量确认 → 内部短计划 → 执行闭环。若 `.draftgo/story.yaml` 存在则静默加载；不存在时不阻塞开发，但应在完成后提醒补 Story；只有跨资源、多页面协作、并行或高风险时才落 Task。
 > - **高风险** → 完整 Story / 计划 / 验证 / 人工确认。无 `.draftgo/story.yaml` 时必须先构建 Story。
 >
 > **开发中发现请求与已有 Story 冲突时，必须显式提示开发者，不可静默执行。** 详见 `{{SKILL_DIR}}/story/SKILL.md` 冲突检测章节。
@@ -22,22 +22,22 @@ version: 1.0.0
 > 任何"开发 / 修改 / 新建 / 修复 / 重构 / 完善 / 优化"指令，**必须先读 `{{SKILL_DIR}}/rules/dev-workflow.md` 做任务分级和用户意图翻译**。标准功能 / 高风险任务追问用户时必须带上 AI 自己的意图推测（推测 + 2-3 个选项 + 推荐项），不能空着问；能合理推断的轻功能不因模板追问拖慢。前端开发按任务规模读取 `{{SKILL_DIR}}/rules/frontend.md` 的相关规则。
 >
 > **【真实可用默认原则】**
-> 除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都必须默认按真实可用、可验证、可闭环处理。禁止用前端假数据、静态卡片、无效按钮或伪交互充当功能完成。若平台能力、外部依赖或通用动态 DB 都无法支撑该功能，不要继续编写伪功能；必须向用户说明阻塞原因并写入 `.draftgo/lessons/`。
+> 除非用户明确要求“静态 / 纯页面 / demo / mock / 假数据 / 伪功能 / 先看效果”，任何开发任务都优先考虑真实落地闭环、高可用。禁止用前端假数据、静态卡片、无效按钮或伪交互充当功能完成。若平台能力、外部依赖或通用动态 DB 都无法支撑该功能，不要继续编写伪功能；向用户说明阻塞原因，并在确有复用价值时写入 `.draftgo/lessons/`。
 >
-> **【更新日志硬性步骤】**
-> 每次完成任何开发 / 修复 / 修改 / 完善 / 删除 / 重构操作后，必须立即写更新日志到 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。这是强制步骤，不得跳过。
+> **【更新日志记录】**
+> changelog 用于让后续 Agent 接手；影响可见功能、跨资源、已 push、已发布或用户明确要求记录时写入 `.draftgo/changelog.md`，格式：`- [HH:MM] [操作类型] 描述`。纯小修、探索、未形成有效改动时可跳过。
 >
-> **【任务标记硬性步骤】**
-> 只有标准功能 / 高风险任务需要 Task 文档。走完计划门后，每完成一个任务必须立即更新 `.draftgo/Task/<file>.md` 中的 ⬜ → ✅ 标记和证据摘要。小修和轻功能无需创建 Task。
+> **【任务标记】**
+> 只有已创建 Task 文档的任务需要维护标记。跨资源、多页面协作、并行开发或高风险任务完成一个阶段后，更新 `.draftgo/Task/<file>.md` 中的 ⬜ → ✅ 标记和证据摘要；小修、轻功能和普通标准功能可用内部短计划，不创建 Task。
 >
 > **【双端覆盖提醒】**
-> 开发任何业务功能时，必须从完整用户路径链路思考：用户从官网 / 导航 / 首页入口进入，点击到目标页面，完成浏览 / 搜索 / 提交 / 管理等操作，再获得真实反馈。必须主动判断是否需要对应管理侧页面（后台 CRUD / 配置 / 审核）和同一份真实数据，避免只做静态展示页。
+> 开发业务功能时，优先从完整用户路径链路思考：用户从官网 / 导航 / 首页入口进入，点击到目标页面，完成浏览 / 搜索 / 提交 / 管理等操作，再获得真实反馈。围绕真实落地闭环、高可用判断是否需要对应管理侧页面（后台 CRUD / 配置 / 审核）和同一份真实数据，避免只做静态展示页。
 >
 > **【页面绑定提醒】**
 > 新增页面后必须处理入口绑定：导航栏、首页模块、后台菜单、相关页面按钮至少一处可点击进入；若用户明确要求隐藏页 / 草稿页，才可不绑定，但必须说明原因。只创建页面文件、不能从正常路径进入，不算完成。
 >
 > **【CLI 辅助工具】**
-> 进入陌生项目、标准功能或多页面任务前，优先运行 `draftgo map` 快速读取页面 / 导航 / DB / 脚本 / AIHub 资源地图；涉及页面、导航、DB 或脚本改动的任务收尾时，运行 `draftgo check` 辅助发现未绑定入口、缺文件、重复路由和疑似 mock 风险。`draftgo check` 是辅助证据，不替代浏览器实测和 push 回读。
+> 资源关系不清、进入陌生项目、多页面任务或用户描述模糊时，优先运行 `draftgo map` 快速读取页面 / 导航 / DB / 脚本 / AIHub / 外部 API / 文档 / 系统配置资源地图；目标文件清楚的小修可跳过。涉及页面、导航、DB 或脚本改动时，可用 `draftgo check` 辅助发现未绑定入口、缺文件、重复路由和疑似 mock 风险。验证优先用文件回读、静态检查、与改动匹配的轻量证据和必要的 push 输出闭环。
 
 ## 命令路由
 
@@ -49,9 +49,9 @@ version: 1.0.0
 | 从云端拉取 / 刷新本地数据 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
 | 推送本地修改到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
 | 构建 / 查看 / 更新系统 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
-| 查看项目资源地图 / `draftgo map` | 直接运行 CLI，快速读取本地页面、导航、DB、脚本、AIHub、入口引用 |
+| 查看项目资源地图 / `draftgo 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 文档时同步打 ✅。 |
+| 开发 / 修改 / 新建 / 修复 / 重构页面、导航、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 文档时同步打 ✅。 |
 
 ## 开发前置检查
 
@@ -87,7 +87,7 @@ version: 1.0.0
 - `dg-*` 不是自研 UI 组件库，不是 daisyUI / Bootstrap / Ant Design / Element Plus 的别名，也不是任意相似样式的统称。
 - 平台壳层管理界面使用 React/TSX 版 shadcn 组件；数据库页面不能直接写 TSX，因此用 `dg-button`、`dg-card`、`dg-form`、`dg-table` 等 HTML 标签表达同一套 shadcn 组件能力。
 - 如果 shadcn 有对应组件，DraftGo 必须提供对应 `dg-*` 标签；当前 runtime 已按映射表提供基础协议覆盖，后续 shadcn 新组件也必须追加对应 `dg-*`。
-- AI 开发页面时，凡是需要按钮、卡片、表单、表格、弹窗、Tabs、Dropdown、Sheet、Tooltip、Toast、Skeleton 等 shadcn 能力，优先使用对应 `dg-*`。
+- AI 开发页面时，`dg-*` 只代表可用的 DraftGo HTML 组件协议，不代表视觉风格指令；需要按钮、卡片、表单、表格、弹窗、Tabs、Dropdown、Sheet、Tooltip、Toast、Skeleton 等协议能力时使用对应 `dg-*`。
 
 ## 连接信息
 
@@ -134,12 +134,14 @@ DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
 | 概念 | 存储键 | 取值 |
 |---|---|---|
 | 显示模式 | `dg_theme` | `'light'` \| `'dark'` \| `'system'` |
-| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` |
+| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'warm-retro'` \| `'mint-blue'` \| `'pine-green'` \| `'custom'` |
 
 **内置配色方案：**
 - `dark-gray-white`
 - `deep-blue-white`
-- `orange-white`
+- `warm-retro`
+- `mint-blue`
+- `pine-green`
 
 **颜色 Token（优先使用）：**
 - `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
@@ -217,8 +219,8 @@ App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
 | 页面 | 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 · GET /system/backup/logs |
-| 备份恢复（增强） | GET /system/backup/package, POST /system/backup/selective/package（.dgbak）· POST /system/restore/package, /restore/package/inspect（上传 .dgbak）· POST /system/restore/inspect, /restore/dry-run（只读预览/预演）· GET /system/storage/health, POST /system/storage/cleanup-orphans（存储健康）· POST /system/backup/logs/{id}/restore, /undo（回溯/撤销） |
+| 备份恢复（基础） | GET/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 |
@@ -437,7 +439,7 @@ const visitId = query.visitId;      // "7"
 | 问题 | 排查步骤 |
 |---|---|
 | 同步失败 | 1. 检查 `.draftgo/config.json` token 是否有效<br>2. 检查服务器连接<br>3. 查看 `.draftgo/changelog.md` 最近操作记录 |
-| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 浏览器控制台查看 JS 错误 |
+| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 检查页面脚本错误、运行日志或最近改动 |
 | API 返回 401 | Token 过期，前端会自动用 refresh token 刷新，无需手动处理 |
 | API 返回 403 | 权限不足，检查当前用户角色是否有对应权限 |
 | DB Meta GET 返回"元数据不存在" | 你用了 id，应该用 **type**（如 `/api/db-meta/patient_profile`）。PUT/DELETE 才用 id。 |
@@ -449,7 +451,7 @@ const visitId = query.visitId;      // "7"
 
 ## 更新日志规范
 
-每次对系统进行开发/修复/修改/完善/删除/重构等操作后，**必须**写入 `.draftgo/changelog.md`。
+更新日志用于让后续 Agent 和开发者快速接手。影响可见功能、跨资源、已 push、已发布或用户明确要求记录时，写入 `.draftgo/changelog.md`；纯小修、探索、未形成有效改动时可跳过。
 
 ### 规则
 
@@ -475,7 +477,7 @@ const visitId = query.visitId;      // "7"
 
 ### 操作流程
 
-1. 完成任何系统操作后，获取当前日期和时间
+1. 判断本次改动是否需要记录
 2. 检查 `.draftgo/changelog.md` 是否存在
 3. 查找当天日期标题（`## YYYY-MM-DD`）
 4. 存在则在该日期段落末尾追加新条目；不存在则在文件顶部新增日期段落
@@ -532,18 +534,18 @@ xxx
 
 ---
 
-## 自动推送规范
+## 推送规范
 
-> **每次修改页面或导航栏 HTML 后，必须立即自动推送到服务器。这是强制步骤，不得跳过，不得等用户提醒。**
+> 推送用于把本地资源同步到云端。用户明确要求推送、任务目标包含云端生效、资源已形成可交付结果、或修改涉及多资源联动时执行；探索性修改、未完成草稿和目标明确的小修可先保留本地。
 
 ### 新建资源（无 id 自动创建）
 
 push 脚本按 index.json 条目**有无 `id`** 决定走更新还是创建：
 
 - **有 id** → `PUT` 更新（PUT 404 时自动转创建，兼容删了重建 / 跨环境）
-- **无 id** → `POST` 创建，成功后**自动回写新 id 到 index.json**，并把内容文件重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`
+- **无 id** → `POST` 创建，成功后**自动回写新 id 到 index.json**；有独立内容文件的资源会同步重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`
 
-支持创建的类型：**pages / nav / db_meta / docs / custom_scripts**。
+支持创建的类型：**pages / nav / db_meta / aihub / external_apis / docs / doc_categories / custom_scripts**。
 
 **新建页面 = 写 html 文件 + 在 `pages/index.json` 加一条不带 id 的记录 + `push pages`**。脚本回写 id 后即与普通更新无异，无需手动调 `POST /api/pages/`、无需手动维护 id。各类型创建必填字段见 push skill（`{{SKILL_DIR}}/push/SKILL.md`「新建资源」节）。
 
@@ -596,14 +598,14 @@ roles 和 users 涉及权限与账号安全，虽然脚本已支持，**仍必
 2. **等待用户明确确认**后，再运行 `draftgo_push.py roles` / `users`
 3. 用户拒绝则不推送，仅保留本地修改
 
-### 完整操作顺序（每次开发任务结束时）
+### 收尾操作顺序（按影响选择）
 
-1. 写更新日志（静默，强制）
+1. 判断是否需要写更新日志
 2. 写经验记录（有阻碍或新经验时写入 lessons/，没有则跳过）
-3. 运行推送脚本 / 调用 API（必须执行，roles/users 需二次确认）
-4. 告知用户推送结果
+3. 需要云端生效时运行推送脚本 / 调用 API（roles/users 需二次确认）
+4. 告知用户本次证据与是否已推送
 
-> **Lessons 提醒机制**：当 `.draftgo/config.json` 中 `lessons_on_push` 为 `true` 时，push 脚本执行完毕会输出一段回顾提醒。此提醒仅为兜底安全网——无论是否看到提醒，步骤 2 的 lessons 回顾义务始终生效。
+> **Lessons 提醒机制**：当 `.draftgo/config.json` 中 `lessons_on_push` 为 `true` 时，push 脚本执行完毕会输出一段回顾提醒。此提醒仅为兜底安全网；是否写 lessons 仍按“有阻碍或新经验”判断。
 
 ---
 
@@ -1263,6 +1265,49 @@ GET /api/agents/{agent_id}/selectable-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
 
 ```

package/resources/skill/push/SKILL.md

@@ -18,7 +18,7 @@ allowed-tools: Bash(python:*), Read, Glob
 > - **有 id** → `PUT /api/{type}/{id}` 更新（PUT 404 时自动转为创建）
 > - **无 id** → `POST /api/{type}` 创建，成功后**自动回写新 id 到 index.json**，并把对应 .html/.md/代码文件**重命名为 pull 约定的 `{prefix}_{id}_{slug}.{ext}`**
 
-支持创建的类型：**pages / nav / db_meta / docs / custom_scripts**（其余类型仍只更新）。
+支持创建的类型：**pages / nav / db_meta / aihub / external_apis / docs / doc_categories / custom_scripts**。
 
 ### 新建页面的标准流程
 
@@ -49,7 +49,10 @@ allowed-tools: Bash(python:*), Read, Glob
 | pages | `title`, `route` | route 不可重复 |
 | nav | `name`, `code` | 创建必填 code，更新时不发 |
 | db_meta | `type`, `label`, `schema` | 无 id 时按 type 创建 |
+| aihub | `type`, `name`, `data` | 支持 model/prompt/agent/mcp/skill 等 AI 资产 |
+| external_apis | `code`, `name`, `base_url` | code 不可包含 `/` 或空格；创建时不发送 status |
 | docs | `title` | 其余字段有默认值 |
+| doc_categories | `name` | slug 可选；不填由后端生成/处理 |
 | custom_scripts | `name`, `slug`, `mode`, `triggers` | mode=route/event/scheduled；创建后默认覆盖代码，启停仍走 enable/disable |
 
 > **创建后必须以脚本回写的 index 为准**，不要手动猜 id。回写后建议 `git diff` 或重新读 index 确认 `id` 已落地。
@@ -85,7 +88,7 @@ allowed-tools: Bash(python:*), Read, Glob
 !python {{SKILL_SCRIPTS}}/draftgo_push.py aihub <aihub_id>
 ```
 
-读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送。
+读取 `.draftgo/aihub/index.json`，按 `AIHubUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/aihub` 创建，成功后回写新 `id`。
 
 ## 推送外部 API（"推送外部API" / "push external_apis"）
 
@@ -94,7 +97,7 @@ allowed-tools: Bash(python:*), Read, Glob
 !python {{SKILL_SCRIPTS}}/draftgo_push.py external_apis <api_id>
 ```
 
-读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送。
+读取 `.draftgo/external_apis/index.json`（已包含 init 时合并的 detail 字段），按 `ExternalAPIUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/external-apis` 创建，成功后回写新 `id`。创建最少需要 `code`、`name`、`base_url`。
 
 ## 推送系统配置（"推送系统配置" / "push system_config"）
 
@@ -149,7 +152,7 @@ users 涉及账号安全，**强制要求人工确认**：
 !python {{SKILL_SCRIPTS}}/draftgo_push.py doc_categories <category_id>
 ```
 
-读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送。
+读取 `.draftgo/doc_categories/index.json`，按 `CategoryUpdate` schema 推送；无 `id` 或 PUT 404 时会 `POST /api/docs/categories` 创建，成功后回写新 `id`。
 
 ## 推送自定义脚本（"推送自定义脚本" / "push custom_scripts"）⚠️ 需二次确认