draftgo-cli 3.0.44 → 3.0.49

package/README.md

@@ -2,7 +2,7 @@
 
 面向 AI 编码工具的 DraftGo 工作台 CLI：分发 DraftGo Skill，通过 MCP 发现和操作实时资源，并为页面、导航和文档提供可校验的 `checkout` / `commit` 工作流。
 
-DraftGo Next 前端基线为 React + Vite；数据库页面以标准 HTML + Tailwind CSS 为核心。CLI 仍提供 Docker 本地运行、项目检查和浏览器验证能力。
+DraftGo Next 壳层使用 React + Vite；数据库页面可按任务使用原生 Web 技术、Tailwind CSS 或平台内置组件库。CLI 仍提供 Docker 本地运行、项目检查和浏览器验证能力。
 
 支持安装 Skill 的宿主：Claude Code、Codex CLI、Cursor、Windsurf、Antigravity、GitHub Copilot、Gemini CLI、Kiro。
 
@@ -32,7 +32,7 @@ draftgo checkout/commit -> DraftGo 专用 HTTP 正文端点
 - `pages`、`navigations` 和 `docs/articles` 的完整正文使用 `checkout` / `commit`。
 - `db_meta`、AIHub、`system_config`、角色、用户、文档分类、自定义服务等结构化资源直接通过 MCP/API 操作，不生成本地索引。
 - `.draftgo/pages/`、`.draftgo/navigations/` 等旧 `index.json` 缓存只视为 legacy 数据；CLI 不删除它们，但 `map` 和 `check` 会忽略它们。
-- DraftGo Skill 继续提供资源关系、页面规范、数据和权限、安全规则、自定义服务经验以及验证流程；MCP 不替代 Skill。
+- DraftGo Skill 继续提供资源关系、前端运行能力与实践、数据和权限、安全规则、自定义服务经验以及验证流程；MCP 不替代 Skill。
 - CLI 不提供页面模板，也不替 Agent 选择页面结构或视觉风格。
 
 ## Agent 阅读顺序
@@ -170,6 +170,7 @@ draftgo context --task frontend --output json
 draftgo checkout pages 42 43
 # 独立资源可并行编辑；同一资源只由一个 Agent 修改
 draftgo check
+draftgo check --remote                  # 交付前按需对比远端版本/hash
 draftgo verify-ui http://localhost:5173       # UI 变更时
 draftgo diff pages 42
 draftgo diff pages 43
@@ -203,9 +204,10 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | `draftgo context --task <task> --output json` | 精确读取任务 Reference 章节，并复用一个 MCP 会话并行查询项目、资源、API 和数据结构；保留原始结果及来源。 |
 | `draftgo map` | 并行读取 pages、navigations、docs/articles 元数据，再叠加本地 checkout 状态；`--type` 可限制一种类型。 |
 | `draftgo checkout <pages|nav|docs> <id...>` | 下载完整正文和 base，校验 hash 后原子落盘；`--force` 可显式覆盖已修改的本地正文。 |
-| `draftgo check` | 只检查 checkout manifest、worktree 文件、base/hash、扩展名、HTML 结构和已 checkout 导航引用。 |
+| `draftgo check` | 默认只检查本地 checkout；`--remote` 额外对比 local/base/manifest/remote 的版本和 hash。 |
 | `draftgo diff <pages|nav|docs> <id>` | 显示 checkout base 与当前本地正文的差异。 |
 | `draftgo commit <pages|nav|docs> <id...>` | 本地校验后，通过专用 HTTP 上传完整正文并更新 base/manifest。 |
+| `draftgo reconcile <pages|nav|docs> <id...>` | 仅当 local 与经校验的 remote 字节一致时，安全修复落后的 base/manifest 元数据。 |
 | `draftgo conflicts` | 列出未解决冲突；存在冲突时返回非零。`--all` 包括已解决记录。 |
 | `draftgo conflict show <type> <id>` | 显示冲突的 base/local/remote/worktree 路径。 |
 | `draftgo conflict resolve <type> <id>` | 确认 worktree 已合并，把保留的 remote 设为新 base；随后重新 check、diff、commit。 |
@@ -220,6 +222,7 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | `draftgo api <query>` | 通过 MCP `api_search` 查询实时 API 契约。 |
 | `draftgo api search <query>` | `draftgo api <query>` 的显式搜索形式。 |
 | `draftgo api describe <operation_id>` | 通过 MCP `api_describe` 查看指定操作。 |
+| `draftgo api call <operation_id> --input <file>` | 描述后调用实时 operation；JSON 文件严格按 UTF-8 解码并输出状态码、服务端 code 和 request ID。 |
 | `draftgo delete <operation_id> [id]` | 描述并确认后调用实时 MCP `api_call`；支持 `--params JSON`、`--input file` 和 `--yes`。 |
 | `draftgo deploy [<type> <id...>]` | 先 `check`，再按 delivery 模式检查 diff 或 commit。仅 `--delivery local` 可省略 type/id。 |
 | `draftgo auto-push [<type> <id...>]` | `auto_push: true` 时检查并 commit 已 checkout 的变更；有冲突立即停止。 |
@@ -321,15 +324,15 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 }
 ```
 
-`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。`check` 不访问远端，也不会读取旧全量资源索引。
+`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, remote, remote_error, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。默认 `check` 不访问远端；显式使用 `--remote` 时读取每个 checkout 的实时 metadata，并把 `committed_unrecorded` 等可恢复状态指向 `draftgo reconcile`。它始终不会读取旧全量资源索引。
 
 ## Skill 与领域约定
 
-安装到每个宿主的 DraftGo Skill 包含主 `SKILL.md`、`init` / `push` / `story` 子技能、references，以及 scripts 扩展约束。实时 API 契约以 MCP `api_search` / `api_describe` 为准；references 保留 API 无法表达的领域知识和实践约束。
+安装到每个宿主的 DraftGo Skill 包含主 `SKILL.md`、`init` / `story` 子技能和按需 references。实时 API 契约以 MCP `api_search` / `api_describe` 为准；references 只保留 API 无法表达的领域知识和实践约束。
 
 前端和自定义服务的关键约定仍然适用：
 
-- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航使用原生 HTML，不写入 TSX、ESM import 或 npm 构建产物。
+- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航以 HTML 文档运行，可加载平台内置组件库，但不进入壳层的 TSX、ESM 或 npm 构建链。
 - 内置 UI、图标、Chat SDK、AIHub 结构化输出以及前端运行、交互和验收规则见 `resources/skill/references/`；CLI 和 Skill 不提供页面模板。
 - 自定义服务使用 Go `draftgo/sdk`，通过 `Register(app *sdk.App)` 注册 Route、事件和定时任务；管理权限、调用权限、并发和出站请求约束见 `resources/skill/references/custom-services.md`。
 - 自定义服务、数据、AIHub、权限和系统配置通过实时 MCP/API 操作，不从 `.draftgo/*/index.json` 推断远端状态。
@@ -343,6 +346,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--task <task>`：选择 context 路由；支持 frontend、data、custom-service、aihub、content、project。
 - `--type <type>`：限制 `map` 查询一种正文资源类型；支持 pages、nav/navigations、docs/articles 及其别名。
 - `--strict`：check/deploy/auto-push 将 warnings 视为失败。
+- `--remote`：让 check 按需对比 checkout 的远端版本和 hash；默认仍为快速离线检查。
 - `--force`：init 覆盖已有 Skill；checkout 显式覆盖已修改的本地正文。update 始终刷新目标 Skill。
 - `--purge`：uninstall 时同时删除整个 `.draftgo/` 运行时目录。
 - `--skip-update-check`：update 不访问 npm，直接用当前 CLI 刷新 Skill。
@@ -353,6 +357,8 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
 - `--yes`：跳过支持该选项的交互确认。
 - `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行。
+- `--resource <type:id>`：verify-ui 打开 URL 前对比本地 checkout 与远端已提交版本，并明确报告实际验证来源。
+- `--browser-path <file>`：verify-ui 显式使用浏览器可执行文件；也可设置 `DRAFTGO_BROWSER_PATH`，否则自动查找系统浏览器和 Playwright 缓存。
 - `--token auto|never`：`verify-ui` 默认读取 `.draftgo/config.json`，对与 `server` 同源的地址自动附加 `token=<SAT>`；配置无 SAT、跨源地址或 `never` 模式均不附加。
 - `--screenshot on-failure|always|never`：控制 UI 截图。
 - `--delivery local|preview|deploy`：控制 deploy 行为。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.44",
+  "version": "3.0.49",
   "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

@@ -1,174 +1,101 @@
 ---
 name: draftgo
-description: Use this skill before inspecting, developing, maintaining, debugging, or delivering a DraftGo application. Start development tasks with draftgo context so exact local Reference sections are read before live MCP discovery; use checkout/commit for complete page/nav/docs bodies and write the changelog only after unified verification and delivery succeed.
+description: Use this skill to inspect, develop, debug, or deliver a DraftGo application. Use draftgo context for task-specific references and live MCP discovery, checkout/commit for complete page, navigation, and document bodies, and write the changelog only after all verification and delivery succeed.
 ---
 
 # DraftGo 开发助手
 
 ## 核心边界
 
-DraftGo CLI 是工作区工具，不是全量云端镜像器。
+- 本地 Skill / Reference 提供产品约束、运行机制和实践；MCP 提供当前项目、资源、API、权限与 schema。
+- pages、navigations、docs/articles 的完整正文只通过 `draftgo checkout`、本地 worktree 和 `draftgo commit` 处理，不放进 MCP 参数、结果、日志或聊天上下文。
+- db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据直接通过 MCP 读写，不建立本地索引。
+- `draftgo context` 是 CLI 的一次性编排入口，不是 MCP 工具；它加载相关 Reference 章节并复用一个 MCP 会话查询实时信息。MCP 不可用时报告连接、协议或 SAT 问题，不回退到旧索引或 `pull --all`。
+- CLI 不提供页面模板，不预设页面骨架、视觉风格、原生技术或组件库选择。Agent 根据任务、受众、现有产品语言和可用资源自主设计。
+- 本地 Docker、MySQL、Redis、Milvus 与 `draftgo local ...` 独立于 MCP 工作流，必须保留。
 
-- 规则：本地 Skill / Reference。
-- 实时数据：MCP。
-- 完整正文：checkout。
-- 聚合编排：`draftgo context`。
-- 用 DraftGo MCP 查询实时资源、API 契约、权限和结构化数据。
-- 只对 pages、nav/navigations 和 docs/articles 的长正文使用 checkout、本地编辑和 commit。
-- 完整 HTML、Markdown 或其他长正文不得作为 MCP 工具参数或 MCP 上下文传输；使用 CLI 的专用 HTTP 流式通道。
-- `draftgo context` 是确定性的 CLI 编排命令，不注册为 MCP 工具；它精确返回相关 Reference 原文及来源，并复用一个 MCP 会话并行查询实时状态。
-- CLI 不提供或生成页面模板，也不替 Agent 选择页面结构或视觉风格；Agent 根据任务、受众和现有资源自主设计。
-- MCP 不可用时报告连接、协议或 SAT 问题；不得自动回退到 pull --all 或旧索引镜像。
-- 本地 Docker、MySQL、Redis、Milvus 和 draftgo local ... 能力与 MCP 工作流相互独立，必须保留。
+## 任务路由
 
-## 强制预读：Reference 优先于 MCP
-
-根 `SKILL.md` 会在 Skill 触发时自动加载。开发、修改或交付任务默认先运行一次与领域匹配的 `draftgo context --task <task> --output json`；前端任务使用：
+开发、修改或交付先运行一次：
 
 ```bash
-draftgo context --task frontend --output json
+draftgo context --task <frontend|data|custom-service|aihub|content|project> --output json
 ```
 
-该命令先校验并逐字读取当前 CLI 随包的本地 Reference 章节，再在同一个 MCP 会话中并行查询项目、资源、API 和数据结构；输出保留原始结构化结果、实际工具名、参数和来源，不做有损总结。`reference_bundle` 同时报告 CLI bundle 版本、项目已安装 Skill 版本和同步状态；不同步时先运行 `draftgo update`。它不限制 Agent 后续继续直接调用 MCP。只回答无需实时状态的本地规则问题，或 context 未覆盖的专项章节时，按下表手工补读；context 失败时报告原始问题，不得跳过 Reference 直接猜测。
-
-不得仅凭 MCP 的元数据推断产品规则、模块归属或前端能力。前端任务的共同规则：任何页面或导航的分析、修改、交互和 UI 任务都先读 `references/frontend.md`；涉及路由、会话、`App` API、iframe/全局注入或运行时行为时加读 `references/runtime.md`；涉及外部资产/CDN、认证、用户输入或不可信内容、敏感数据或配置时加读 `references/security.md`。静态资源只是该规则的一种专门场景。
-
-| 用户问题或任务 | MCP 前必须读取的 Skill 材料 | 然后才可取得的实时证据 |
-|---|---|---|
-| 页面/导航清单、路由、业务页面与平台页面的区分 | `references/architecture.md`、`references/modules.md`；存在 `.draftgo/story.yaml` 时一并读取 | MCP `project_overview`、`resource_list`/`resource_search`、按需 metadata；仅在元数据或现有资源关系明确归属或系统标记时定性，否则报告“无法从可用证据确认”，不要以标题、路径或正文片段猜测业务属性 |
-| 页面或导航的分析、修改、交互和 UI | `references/architecture.md`、`references/frontend.md` 的相关页面/导航规则；按上述共同规则追加 `references/runtime.md` 或 `references/security.md` | MCP 定位后 checkout，再在 worktree 读取完整正文 |
-| 平台内置前端静态资源、组件库或可用资源目录 | `references/frontend.md` 的“前端底座与组件库清单”和“本地静态资源清单”章节；涉及外部资产/CDN 或安全要求时加读 `references/security.md` | 直接根据 reference 回答并标为 Skill 提供的能力；无需 MCP，不能声称这是服务器完整文件清单 |
-| 指定页面/导航的脚本、样式或资源依赖 | `references/architecture.md`、`references/frontend.md` 的相关资源规则、`references/checkout.md`；按上述共同规则追加 `references/runtime.md` 或 `references/security.md` | MCP 定位指定资源后 checkout，再在 worktree 本地搜索精确引用 |
-| 服务器实际全部静态文件清单 | `references/frontend.md` 的能力边界；只有平台明确暴露静态文件 API 时再读 `references/mcp.md` | 当前 Skill、MCP 元数据和 checkout 都不能证明完整服务器目录；明确说明证据不足，只有已暴露的实时 API 才可查询 |
-| 动态 DB、筛选、字段或数据关系 | `references/modules.md`、`references/data.md`；需要关系时加读 `references/db-relations.md` | MCP `api_describe`、`api_call` |
-| AIHub、聊天或图像能力 | `references/aihub.md` 与 `references/chat-sdk.md` | MCP 实时 API/语义工具 |
-| 自定义服务、权限或外部调用 | `references/custom-services.md` 与 `references/security.md` | MCP 实时 API；必要时真实健康检查 |
-| MCP 配置、连接或工具故障 | `references/mcp.md` | `draftgo mcp status`、`draftgo mcp test` |
-| pages/nav/docs 全文编辑或完整依赖分析 | `references/checkout.md`，以及上表相应领域资料 | MCP 元数据后 `draftgo checkout`；完整正文不通过 MCP 获取 |
-
-汇报时明确区分三类证据：Skill 给出的产品约束和内置能力、MCP 返回的当前远端状态、以及 checkout 正文中确认的精确页面依赖。不能把其中任一类冒充为另一类。例如，Skill 列出的 `/assets/` 能力不是当前服务器文件清单，MCP 的页面摘要也不是完整 HTML 依赖清单。最终答复列出具体已读取的 reference，不能只笼统声称“已读 Skill”。
-
-## 并行开发与所有权
+context 会校验本地 Reference，返回逐字章节、来源、实时项目/资源/API/数据结构和 bundle 同步状态；不同步时先运行 `draftgo update`。它不会限制后续 MCP 查询。只回答本地规则或需要 context 未加载的专题时，直接补读对应 Reference：
 
-- 无依赖且修改不同文件或 DraftGo 资源的任务并行开发。
-- 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；其他 Agent 只能只读分析并向唯一 owner 回传建议。
-- 分发实现前先确定共享的数据结构、接口、权限和路由，再并行开发消费者。
-- 主 Agent 负责执行一次 context、分配资源 owner、汇总回读、统一验证、commit，并仅在全部交付成功后写 changelog。
-- 单页面、强依赖任务或拆分后仍共享主要资源的任务不强行并行，避免协调成本拖慢开发。
-
-详细工作单元和 wave 规则见 `references/parallel.md`。
-
-## 标准工作流
-
-```text
-context 一次准备信息
-→ Agent 自主设计并批量 checkout
-→ 独立资源按需并行开发
-→ 主 Agent 一次统一验证
-→ commit
-→ draftgo changelog add "<完成结果>"
-```
+| 任务 | 专题资料与后续动作 |
+|---|---|
+| 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md`；MCP 定位后 checkout 完整正文 |
+| 动态 DB、筛选或关系 | `references/data.md`；需要关系完整示例时读 `db-relations.md`；API 调用遵循 `mcp.md` |
+| AIHub、聊天或图片 | `references/aihub.md`、`references/chat-sdk.md`；资产与 operation 以 MCP 为准 |
+| 自定义服务、权限、外部调用 | `references/custom-services.md`；管理和动态 Route operation 以 MCP 为准 |
+| MCP 配置、API 契约或故障 | `references/mcp.md`；配置变更或调用失败时运行 `draftgo mcp test` |
+| pages/nav/docs 全文、版本或冲突 | `references/checkout.md`；MCP 只定位和读取元数据 |
+| 架构、模块选型或陌生项目 | `references/architecture.md`、`references/modules.md`；存在 `.draftgo/story.yaml` 时一并读取 |
 
-### 项目清点与陌生项目
+不要用 MCP 摘要代替完整正文，也不要把 Skill 列出的 `/assets/` 能力声称为当前服务器全部文件。业务归属、系统资源或页面类型没有明确元数据时报告证据不足，不凭标题、路径或片段猜测。
 
-1. 运行匹配领域的 `draftgo context --task <task> --output json`，一次取得规则原文及实时基础信息。
-2. 根据 context 的来源和原始结果确认资源范围；按需继续调用 MCP search、describe 或 metadata，不把 context 当成后续查询限制。
-3. 需要叠加本地 checkout 状态时运行 `draftgo map`。
-4. `draftgo mcp test` 只用于 connect 后验证、配置变更或 MCP 调用失败后的诊断；普通资源查询不应先执行它。
+## 所有权与执行
 
-### 页面、导航和文档正文
+- 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；其他 Agent 只读分析并回传建议。
+- 先确定共享 schema、接口、权限和 route，再并行处理无依赖且 owner 不冲突的工作单元。
+- 单页面、强依赖或仍共享主要资源的任务不强行并行。
+- 主 Agent 负责一次 context、owner 分配、汇总回读、统一验证、交付和完成日志；子 Agent 不单独写 changelog。
+- 冲突 owner、接口依赖或验证失败会阻塞依赖项，不影响无关分支继续汇总。
 
-1. 运行 frontend 或 content context，并按需继续通过 MCP 定位资源、取得元数据。
-2. Agent 根据任务自主设计；页面开发优先考虑 Tailwind CSS 作为基础样式方案，并按任务需要搭配现有组件库；对已确定的 pages/nav/docs 批量 checkout。
-3. 按唯一资源 owner 读取、搜索和编辑 `.draftgo/worktree/` 正文；独立资源可并行。
-4. 主 Agent 汇总回读后统一运行一次 `draftgo check`，页面布局或交互变化时再统一运行 `draftgo verify-ui`。
-5. 用 `draftgo diff <type> <id>` 检查全部 base/local 差异，再运行对应的 `draftgo commit ...`。
-6. 全部验证和 commit 成功后执行一次 `draftgo changelog add "<完成结果>"`。任何验证失败、409/412 或交付失败都停止且不写 changelog。
+## 开发与交付
 
-详细 manifest、扩展名、哈希和冲突规则见 references/checkout.md。
+### 长正文
 
-### 只查询长内容
+1. MCP 定位 pages/nav/docs 并读取 metadata。
+2. 批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
+3. 主 Agent 回读全部修改，统一运行 `draftgo check`；交付前需要核对远端版本时运行 `draftgo check --remote`。
+4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。页面布局或交互变化时在 commit 后用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。
+5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。
 
-优先使用 MCP 的 search、fragment 或摘要工具。只有需要全文分析或编辑时才 checkout；不要要求 MCP 返回完整正文。
+完整 manifest、流式传输、哈希和冲突规则见 `references/checkout.md`。
 
 ### 结构化资源
 
-db_meta、AIHub、system_config、roles、users、doc_categories、普通配置和自定义服务元数据直接使用 MCP 的 api_search、api_describe、api_call 或语义化工具。
+严格按 `references/mcp.md` 的 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 流程执行。describe 不完整就停止，不猜参数、响应、权限或风险。按唯一资源 owner 写入，回读结果并验证副作用；结构化资源不 checkout。
 
-不要为这些资源创建全量本地镜像，也不要读取旧 .draftgo/*/index.json 作为事实来源。领域 schema、权限和实践约束仍可从本 Skill 的 references 读取。
-按唯一资源 owner 完成修改，主 Agent 回读并验证全部副作用；只有所有结构化资源交付成功后才执行一次 `draftgo changelog add`。
+### 完成日志
 
-## CLI 场景路由
+只有整个任务的检查、UI/API 验证和所有 commit/MCP 写入都成功后，主 Agent 执行一次：
 
-| 场景 | 动作 |
-|---|---|
-| 安装、更新、移除 Skill | draftgo init [target...]、draftgo update [target...]、draftgo uninstall <target\|all> |
-| 查看宿主和 MCP 状态 | draftgo status、draftgo list-targets、draftgo mcp status |
-| 配置或诊断 MCP | draftgo mcp setup [target...]、draftgo mcp test；细节见 references/mcp.md |
-| 连接基座 | draftgo connect；保存 server/SAT、验证 /mcp 和关键工具，不拉取业务资源 |
-| 本地基座 | draftgo local setup，然后 draftgo local start/stop/logs/status；兼容 local-dev、local up/down |
-| 一次准备任务上下文 | draftgo context --task frontend\|data\|custom-service\|aihub\|content\|project --output json |
-| 远端摘要或资源定位 | MCP project_overview、resource_search、resource_list、按需 metadata 工具 |
-| 页面、导航、文档正文 | context → 批量 checkout → 按资源 owner 编辑 → 统一 check/verify-ui → diff → commit |
-| 结构化资源读写 | MCP api_search、api_describe、api_call 或语义化工具 |
-| 完成结果日志 | 全部验证和交付成功后 draftgo changelog add "<完成结果>"；失败时禁止写入 |
-| 删除资源 | 使用实时 MCP/API 删除；不得从本地旧索引推断目标或清理正文 |
-| 兼容旧命令 | draftgo pull 只显示迁移提示并返回非零；draftgo push pages/nav/docs 显示弃用提示后转发到 commit。其他 push 类型引导使用 MCP。 |
-
-## DraftGo 契约
-
-- 响应信封：调用实时 API 时先检查 code === 200，再读取 data；MCP 的结构化错误原样保留。
-- 分页：需要完整候选集时省略 page 和 page_size；真实分页列表同时传入二者。
-- 时间：展示按用户/浏览器时区；存储、统计、定时和自然日边界按 system_timezone 计算。
-- 数据 schema：优先通过 MCP api_describe 获取字段、类型、必填、searchable、操作符和权限；详细关系见 references/data.md 与 references/db-relations.md。
-- 自定义服务：使用 package main、Register(app *sdk.App) 和 handler(draftgo *sdk.Context)；Route 权限与脚本管理权限是两层独立控制。完整 SDK 见 references/custom-services.md。
-- 系统资源：登录、设置、权限、用户和系统配置属于基座资源；修改前确认影响范围并保留原有系统能力。
+```bash
+draftgo changelog add "<完成结果>"
+```
+
+任何验证失败、409/412 或交付失败都不得写 changelog。日志只写完成结果，不写排查过程。
 
 ## 安全规则
 
-- SAT 只保存在项目 .draftgo/config.json 中；不要写入 AI 宿主配置、命令行参数、Skill 文本、日志、manifest 或错误消息。
-- MCP stdio bridge 从当前项目安全读取 server/SAT；宿主配置只写 draftgo mcp serve，不写远端 URL 或令牌。
-- 不要把完整 HTML/Markdown 放进 MCP tool result、tool 参数、聊天上下文、日志或冲突 JSON；长正文只在 CLI 专用 HTTP 流中处理。
-- 不要隐式 force、自动重试覆盖或自动合并冲突。draftgo conflict resolve 必须由 Agent/用户明确选择后执行。
-- 旧 .draftgo 缓存视为 legacy 数据，不自动删除，也不再作为事实来源；给出清晰迁移提示。
-- 资源权限、管理员 SDK 调用和自定义服务审计规则见 references/security.md 与 references/custom-services.md。
+- SAT 只保存在 `.draftgo/config.json`；不得进入宿主配置、命令行参数、Skill、日志、manifest 或错误消息。宿主只配置 `draftgo mcp serve`。
+- 页面优先使用可信本地资源；禁止境外 CDN。用户输入或不可信 HTML 在渲染前净化，关键状态不能只靠颜色或动效表达。
+- 页面通过 `window.parent.App` 使用认证、权限、反馈和主题；登出调用 `await App.logout()`，路由参数读取运行时注入对象。详细规则见 `frontend.md`、`runtime.md` 与 `app-api.md`。
+- 自定义服务普通 SDK 继承调用者权限；仅显式 `draftgo.Admin.*` 提升单次调用并进入审计。Route 权限、脚本管理权限、定时/事件身份和出站限制见 `custom-services.md`。
+- 高风险 MCP operation 仅在用户意图明确且影响范围已核对时设置 `confirm=true`。不要传 SAT、Authorization、tenant override 或自行实现旧式二次认证。
+- 旧 `.draftgo` 缓存不是事实来源；不自动删除。不要隐式 force、自动重试覆盖或自动合并冲突。
 
-## 验证与交付
+## 验证证据
 
-| 资源 | 证据 |
+| 范围 | 最低证据 |
 |---|---|
-| MCP 连接 | draftgo mcp test 的 initialize、tools/list 和关键工具结果；SAT 不出现在输出 |
-| 页面、导航、文档 | checkout manifest、draftgo check、必要时 verify-ui、diff、commit 回读版本和哈希 |
-| 结构化资源 | MCP 请求与回读的字段、权限、错误和副作用证据 |
-| 自定义服务 | Route 或无副作用健康端点的状态码和响应；管理员调用确认审计 |
-| 冲突 | .draftgo/conflicts/ 中的 base/local/remote 和 manifest；解决后重新 check/verify-ui/commit |
-| 本地底座 | draftgo local status、日志和既有 local-dev 测试 |
+| MCP 连接 | 失败时用 `draftgo mcp test` 核对 initialize、tools/list 和关键工具；输出不含 SAT |
+| 页面、导航、文档 | checkout manifest、`draftgo check`、必要的 `verify-ui`、diff、commit 返回版本与哈希 |
+| 结构化资源 | search/describe 契约、call 结果与回读的权限、字段、错误和副作用 |
+| 自定义服务 | 动态 Route describe、无副作用健康请求或目标行为结果，以及管理员调用审计 |
+| 冲突 | `.draftgo/conflicts/` 的 base/local/remote；解决后重新 check、必要的 verify-ui 和 commit |
+| 本地底座 | `draftgo local status`、日志和相关 local 测试 |
 
-draftgo deploy、auto-push 等旧交付入口必须遵循当前 CLI 的 commit 语义；不把它们当作旧全量 push 的回退路径。
-
-主 Agent 必须汇总全部修改和验证证据后再交付。只有任务统一验证并且所有 commit/MCP 写入成功时，才运行一次 `draftgo changelog add "<完成结果>"`；日志只写完成结果，不写排查过程。验证失败、冲突或任一交付失败时不得写入。
-
-## 参考路由
-
-- MCP、宿主配置和 bridge：references/mcp.md
-- checkout、commit、manifest 和冲突：references/checkout.md
-- 架构和模块边界：references/architecture.md、references/modules.md
-- 前端页面和组件：references/frontend.md、references/ui-protocol.md、references/debugging-syntax.md
-- App、运行时和数据：references/app-api.md、references/runtime.md、references/data.md、references/db-relations.md
-- AIHub、聊天和自定义服务：references/aihub.md、references/chat-sdk.md、references/custom-services.md
-- 安全和并行执行：references/security.md、references/parallel.md
-- 产品决策：story/SKILL.md
+`draftgo deploy`、`auto-push` 和兼容 `push pages|nav|docs` 只能沿用当前 check/commit 语义，不能恢复旧的全量 push。主 Agent 最终明确区分 Skill 约束、MCP 实时状态和 checkout 正文证据。
 
 ## 本地工作区
 
-| 路径 | 用途 |
-|---|---|
-| .draftgo/config.json | server、SAT 和 CLI 项目设置；必须 gitignore |
-| .draftgo/worktree/pages/ | 已 checkout 的页面正文 |
-| .draftgo/worktree/navigations/ | 已 checkout 的导航正文 |
-| .draftgo/worktree/docs/ | 已 checkout 的文档正文 |
-| .draftgo/worktree/.base/ | checkout 时保存的 base；必须 gitignore |
-| .draftgo/conflicts/ | 409/412 冲突材料；必须 gitignore |
-| .draftgo/worktree/manifest.json | checkout 的版本、路径、内容类型和哈希；必须 gitignore |
-| .draftgo/story.yaml、Task/、lessons/ | 项目决策、任务和经验；按项目策略保留 |
-| .draftgo/changelog.md | 完成结果日志；统一验证和全部交付成功后必须写入，失败时禁止写入 |
+- `.draftgo/config.json`：server、SAT 与 CLI 设置，必须 gitignore。
+- `.draftgo/worktree/`、`.base/`、`manifest.json`：checkout 正文及基线，必须 gitignore。
+- `.draftgo/conflicts/`：409/412 材料，必须 gitignore。
+- `.draftgo/story.yaml`、`Task/`、`lessons/`：项目决策、任务和经验。
+- `.draftgo/changelog.md`：仅在整个任务验证和交付成功后写入。

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.44",
+  "version": "3.0.49",
   "entry": "SKILL.md",
   "description": "以 context 聚合编排、Skill/reference 原文、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",
@@ -27,10 +27,8 @@
     "references": [
       "references"
     ],
-    "scripts": "scripts",
     "subskills": [
       "init",
-      "push",
       "story"
     ]
   }

package/resources/skill/references/aihub.md

@@ -29,8 +29,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 
 页面对话 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`。
+`/assets/draftgo-chat.js`，完整用法见 `references/chat-sdk.md`。后端 operation 与可调用 Agent 列表通过 MCP `draftgo_api_search` → `draftgo_api_describe` 实时确认。
 
 ## `data.spec` 字段地图
 
@@ -56,7 +55,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 | `knowledge_base_ids` | int[] | 绑定知识库，生成检索工具 |
 | `skills` | 见运行时 | 绑定 Skill |
 | `sub_agent_ids` | int[] | 子智能体：为每个 id 生成 `agent_{id}` 委派工具（用法同 `knowledge_base_ids`） |
-| `call_permissions` | 角色配置 | 谁能调用此 Agent（`GET /api/agents` 据此过滤） |
+| `call_permissions` | 角色配置 | 哪些角色可以调用此 Agent；调用接口与筛选条件以 MCP 实时契约为准 |
 
 ### `orchestration.*`（编排开关）
 
@@ -84,6 +83,6 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 ## 观测
 
 每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
-接口：`GET /api/aihub/runs`、`GET /api/aihub/runs/{trace_id}`、`DELETE /api/aihub/runs`。
+运行记录接口通过 MCP `draftgo_api_search` / `draftgo_api_describe` 实时发现，不维护静态路径表。
 
 > 权威细节以 DraftGo 后端 `docs/backend/modules/agent-runtime.md` 为准；本页是基座开发者视角的字段速查。

package/resources/skill/references/app-api.md

@@ -33,10 +33,10 @@ const paged = await App.get('pages', { page: 1, page_size: 20 }); // 显式分
 
 | 方法 | 签名 | 说明 |
 |---|---|---|
-| `App.showSuccess` | `(msg)` | 成功 Toast 3s |
-| `App.showError` | `(msg)` | 错误 Toast 4s |
-| `App.showWarning` | `(msg)` | 警告 Toast 3s |
-| `App.showInfo` | `(msg)` | 信息 Toast 3s |
+| `App.showSuccess` | `(msg)` | 成功 Toast |
+| `App.showError` | `(msg)` | 错误 Toast |
+| `App.showWarning` | `(msg)` | 警告 Toast |
+| `App.showInfo` | `(msg)` | 信息 Toast |
 | `App.toast` | `(msg, type?)` | 通用 Toast，type: success/error/warning/info |
 | `App.confirm` | `(msg, title?)` | 确认弹窗，返回 `Promise<boolean>` |
 | `App.showModal` | `(msg, title?)` | 信息模态框（替代 alert） |
@@ -85,56 +85,11 @@ App.getColorScheme();                             // 获取方案详情
 ## 其他
 
 ```javascript
-App.logout();                       // 登出并跳转登录页
+await App.logout();                 // 服务端登出、清理状态并跳转配置的登录页
 App.setAuthTokens({ access_token, refresh_token });  // 登录后写入 token
 App.reloadGlobalLayer();            // 重载全局层
 App.openGlobalWidget(name);         // 触发全局挂件打开
 App.t(key, fallback?);              // 国际化文本
 ```
 
-## Token 存储
-
-| key | 说明 |
-|---|---|
-| `localStorage.dg_access_token` | 访问 token |
-| `localStorage.dg_refresh_token` | 刷新 token |
-
-## AI 对话与兼容门面
-
-新页面的可见对话使用 `<dg-chat>` 或 `DraftGoChat.create()`。两者都由 `/assets/draftgo-chat.js` 注册，壳层不会默认注入：
-
-```html
-<script src="/assets/draftgo-chat.js"></script>
-<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
-```
-
-完整配置、协议、事件和安全约束见 `references/chat-sdk.md`。
-
-### `DraftGoAI` 旧兼容门面
-
-`window.DraftGoAI` 由同一完整版脚本注入，用 Agent id 而非直连模型。它适合旧代码、无 UI 的轻量文本调用和图片生成；新页面不要用它重建对话界面。
-
-| 方法 | 签名 | 说明 |
-|---|---|---|
-| `DraftGoAI.chat` | `(agentId, message, onDelta?, options?)` | 对话；**默认流式**，`onDelta(delta, full)` 每个增量触发一次，Promise resolve 完整文本 |
-| `DraftGoAI.images` | `(agentId, prompt, options?)` | 图片模式 Agent，`POST /api/agents/{id}/images`，返回标准信封 |
-| `DraftGoAI.getSelectableModels` | `(agentId)` | 返回 `{ user_selectable, models }` |
-
-```javascript
-// 流式对话
-const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
-
-// 多轮：传 sessionId（→ body.session_id）复用同一会话；Agent 开启“持续对话”后服务端续写历史
-await DraftGoAI.chat(agentId, '接着上一条', onDelta, { sessionId: threadKey });
-
-// 用户选模型 + 覆盖模型
-const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
-await DraftGoAI.chat(agentId, '你好', onDelta, { model: models[0]?.id, sessionId: threadKey });
-
-// 图片生成（不要用 chat）
-const res = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
-```
-
-**`options` 常用键**：`sessionId`（多轮会话键）、`model`（覆盖模型）、`stream`（默认 true）、`context`。
-不传 `sessionId` = 无状态单轮。富交互 UI（附件、模型选择器、推理展示、历史、重生成）用
-`<dg-chat>`，见 `references/chat-sdk.md`；Agent 能力全景见 `references/aihub.md`。
+Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话、图片和兼容门面的完整契约见 `references/chat-sdk.md`，Agent 能力见 `references/aihub.md`。

package/resources/skill/references/architecture.md

@@ -30,32 +30,7 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 
 ## App 对象是什么（1 分钟）
 
-壳层将能力对象赋值给 `window.App`，页面内通过 `window.parent.App` 访问：
-
-```javascript
-const App = window.parent?.App;
-
-// 请求（自动携带 token）
-await App.get('pages');                         // 全量列表
-await App.get('pages', { page: 1, page_size: 20 }); // 分页列表
-await App.post('db/order', { data: { name: '张三' } });
-
-// 反馈
-App.showSuccess('操作成功');
-App.showError('操作失败');
-await App.confirm('确认删除？', '删除确认');  // Promise<boolean>
-
-// 路由
-App.navigate('/dashboard');
-const query = App.getCurrentRouteContext().query;
-
-// 状态
-App.currentUser   // 当前用户（未登录为 null）
-App.isAdmin       // 是否管理员
-App.theme         // 'light' | 'dark'
-```
-
-完整 API 速查表见 `references/app-api.md`
+壳层将能力对象赋值给 `window.App`，数据库页面通过 `window.parent.App` 使用带认证的请求、反馈、路由、当前用户和主题能力。方法签名见 `references/app-api.md`；iframe 注入、认证事件和路由参数见 `references/runtime.md`。
 
 ---
 
@@ -65,7 +40,7 @@ App.theme         // 'light' | 'dark'
 |---|---|
 | 后端 | Go 1.26 · 标准库 `net/http` · `database/sql`（go-sql-driver/mysql）· MySQL · Redis |
 | 壳层前端 | React · Vite |
-| 数据库页面 | 原生 HTML · `/assets/tailwindcss.js`（运行时）· FontAwesome · GSAP · html2canvas · 内置 SVG 图标库 |
+| 数据库页面 | HTML 文档运行时 · 内置组件库 · Tailwind CSS · FontAwesome · GSAP · html2canvas · 内置 SVG 图标库 |
 | CLI | Node.js（draftgo-cli） |
 
-数据库页面**不需要** npm install，也**不进入** React 编译，直接写 HTML + 本地资源路径。
+数据库页面**不需要** npm install，也**不进入**壳层编译；页面可在 HTML 文档中按任务加载平台提供的浏览器组件库和本地资源。

package/resources/skill/references/checkout.md

@@ -23,6 +23,7 @@ db_meta、AIHub、system_config、roles、users、doc_categories 和普通配置
 ```bash
 draftgo checkout <pages|nav|docs> <id...>
 draftgo commit <pages|nav|docs> <id...>
+draftgo reconcile <pages|nav|docs> <id...>
 draftgo diff <pages|nav|docs> <id>
 draftgo conflicts
 draftgo conflict show <pages|nav|docs> <id>
@@ -91,7 +92,7 @@ base 已变化时必须拒绝覆盖。
 4. 完整正文不得作为 MCP tool 参数发送。
 5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
 
-推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` 和必要的 `draftgo verify-ui` -> `draftgo diff` -> commit。
+推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
 单个 commit 成功不自动写 changelog。只有整个任务统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行一次 `draftgo changelog add "<完成结果>"`。任何检查失败、409/412 或交付失败都不得写入。
 

package/resources/skill/references/custom-services.md

@@ -12,7 +12,7 @@ DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`
 
 - [最小服务](#最小服务)、[本地资源](#本地资源)、[触发器](#触发器)
 - [平台 SDK](#平台-sdk)、[AI 平台 SDK](#ai-平台-sdk)
-- [权限与运行限制](#权限与运行限制)、[管理 API](#管理-api)、[验收清单](#验收清单)
+- [权限与运行限制](#权限与运行限制)、[实时 API](#实时-api)、[验收清单](#验收清单)
 
 ## 最小服务
 
@@ -280,22 +280,11 @@ value, err := draftgo.AIHub.Request(draftgo.Context(), sdk.AIRequest{
 - Go 服务以独立进程运行，超时会终止该进程；它不是为不可信多租户代码准备的安全沙箱。只向可信编辑者授予服务编辑权限。
 - 每个保存版本按源码、依赖、SDK 和 Runner 协议生成不可变构建键。代码或依赖变更会生成新构建产物；旧版本可通过现有版本恢复接口重新激活。
 
-## 管理 API
+## 实时 API
 
-管理 API 使用 `{code, data, message}` 信封并受 `scripts:*` 权限控制：
+服务管理接口使用标准 `{code, data, message}` 信封并受 `scripts:*` 权限控制。具体 operation、参数、请求体、响应和风险必须通过 MCP `draftgo_api_search` → `draftgo_api_describe` 获取后再调用，不维护静态路径表。
 
-| 方法 | 路径 |
-|---|---|
-| `POST` / `GET` | `/api/scripts` |
-| `GET` | `/api/scripts/options/roles` |
-| `GET` / `PUT` / `DELETE` | `/api/scripts/{id}` |
-| `GET` | `/api/scripts/{id}/routes` |
-| `POST` | `/api/scripts/{id}/enable`、`/api/scripts/{id}/disable`、`/api/scripts/{id}/execute` |
-| `GET` | `/api/scripts/{id}/versions`、`/api/scripts/{id}/executions` |
-| `POST` | `/api/scripts/{id}/versions/{version_id}/restore` |
-| `GET` | `/api/scripts/{id}/executions/{execution_id}` |
-
-运行时 route 为 `ANY /api/x/{slug}/{path}`，不使用管理 API 信封。
+有效 `app.Route` 会以实际 method、`/api/x/{slug}/{path}`、权限、风险和输入 schema 动态加入同一 MCP registry；搜索 `resource_type=custom_scripts` 或 `module=scripts_dynamic` 后描述并调用。运行时 Route 返回 handler 自定义响应，不强制使用管理 API 信封；精确匹配、调用身份和运行限制仍以本文件的 Route 与权限章节为准。
 
 ## 验收清单