draftgo-cli 3.0.33 → 3.0.38

package/resources/skill/SKILL.md

@@ -1,77 +1,136 @@
 ---
 name: draftgo
-description: Use this skill when developing, maintaining, debugging, synchronizing, or delivering a DraftGo-based application, including DraftGo pages, navigation, dynamic DB, base APIs, Go custom services, AIHub, knowledge bases, Skill/MCP assets, roles, and local resources.
+description: Use this skill before inspecting, developing, maintaining, debugging, or delivering a DraftGo application. It covers project/page/navigation inventories, business-page classification, frontend/static-asset questions, long-form docs, dynamic data, custom services, AIHub, MCP integrations, and local runtime. Read the relevant bundled reference before calling DraftGo MCP; use MCP for live state and checkout/commit for complete page/nav/docs bodies.
 ---
 
 # DraftGo 开发助手
 
-## 执行方法
+## 核心边界
 
-1. **建立资源图**：从用户路径列出角色、入口、页面、操作、数据、服务、运营维护和验证证据，并标记资源间的依赖。
-2. **确定共享契约**：从当前 `db_meta`、底座 API、自定义服务、权限、路由和导航中确认被多个资源共同依赖的契约，再展开依赖它们的实现。
-3. **并行独立资源**：按依赖关系划分 wave。独立页面、管理页、文档和服务并行处理；共享 schema、导航、HTML 文件或调用链按依赖顺序处理。每个工作单元携带资源范围和验证方式，交付动作由汇总阶段统一执行。具体字段见 `references/parallel.md`。
-4. **汇总接线**：连接入口、页面跳转、真实数据读写、角色可见性、加载/空/错误/成功状态和运营维护路径，随后回放关键用户路径。
-5. **验证与交付**：按资源类型取得证据。完成本地验证后，根据用户交付意图或项目自动同步配置执行 `push`、`deploy` 或 `auto-push`。
+DraftGo CLI 是工作区工具，不是全量云端镜像器。
 
-## CLI 与场景路由
+- 用 DraftGo MCP 查询实时资源、API 契约、权限和结构化数据。
+- 只对 pages、nav/navigations 和 docs/articles 的长正文使用 checkout、本地编辑和 commit。
+- 完整 HTML、Markdown 或其他长正文不得作为 MCP 工具参数或 MCP 上下文传输；使用 CLI 的专用 HTTP 流式通道。
+- MCP 不可用时报告连接、协议或 SAT 问题；不得自动回退到 pull --all 或旧索引镜像。
+- 本地 Docker、MySQL、Redis、Milvus 和 draftgo local ... 能力与 MCP 工作流相互独立，必须保留。
 
-调用 `draftgo` CLI 完成工具动作；`scripts/` 下的脚本是 CLI 内部实现，不作为 Agent 的调用入口。
+## 强制预读：Reference 优先于 MCP
 
-| 场景 | DraftGo 动作 |
+根 `SKILL.md` 会在 Skill 触发时自动加载。调用任何 DraftGo MCP 工具、`draftgo mcp test`、`draftgo map` 或 checkout 前，先按任务路由读取下表中相关的 `references/`；不得仅凭 MCP 的元数据推断产品规则、模块归属或前端能力。前端任务的共同规则：任何页面或导航的分析、修改、交互和 UI 任务都先读 `references/frontend.md`；涉及路由、会话、`App` API、iframe/全局注入或运行时行为时加读 `references/runtime.md`；涉及外部资产/CDN、认证、用户输入或不可信内容、敏感数据或配置时加读 `references/security.md`。静态资源只是该规则的一种专门场景。对于较长 reference，先用 `rg -n` 定位指定标题，再读取该节及其明确要求的安全或运行时约束；不要无目的地加载整份资料。
+
+| 用户问题或任务 | 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”。
+
+## 标准工作流
+
+### 项目清点与陌生项目
+
+1. 先按上表读取领域 reference。仅需判断页面、导航、业务模块或静态资产时，不要跳过此步。
+2. 若需要当前远端状态，通过 MCP 的 `project_overview`、`resource_search`/`resource_list` 获取摘要。
+3. 只按需调用 describe 或元数据工具；不要为了建立上下文下载所有正文。
+4. 运行 `draftgo map` 叠加本地 checkout 状态，再决定资源范围。
+5. `draftgo mcp test` 只用于 connect 后验证、配置变更或 MCP 调用失败后的诊断；普通资源查询不应先执行它。
+
+### 页面、导航和文档正文
+
+1. 通过 MCP 定位资源并取得元数据、content_type、版本和哈希。
+2. 运行 draftgo checkout pages <id...>、draftgo checkout nav <id...> 或 draftgo checkout docs <id...>。
+3. 读取、搜索和编辑 .draftgo/worktree/ 中的正式文件；保留原始内容类型和编码。
+4. 运行 draftgo check，页面布局或交互变化时再运行 draftgo verify-ui。
+5. 用 draftgo diff <type> <id> 检查 base 与 local 差异。
+6. 运行对应的 draftgo commit ...。提交遇到 409/412 时停止，保留冲突材料并等待 Agent 或用户解决。
+
+详细 manifest、扩展名、哈希和冲突规则见 references/checkout.md。
+
+### 只查询长内容
+
+优先使用 MCP 的 search、fragment 或摘要工具。只有需要全文分析或编辑时才 checkout；不要要求 MCP 返回完整正文。
+
+### 结构化资源
+
+db_meta、AIHub、system_config、roles、users、doc_categories、普通配置和自定义服务元数据直接使用 MCP 的 api_search、api_describe、api_call 或语义化工具。
+
+不要为这些资源创建全量本地镜像，也不要读取旧 .draftgo/*/index.json 作为事实来源。领域 schema、权限和实践约束仍可从本 Skill 的 references 读取。
+
+## CLI 场景路由
+
+| 场景 | 动作 |
 |---|---|
-| 查看 Skill 安装状态或支持目标 | 运行 `draftgo status`；需要目标列表时运行 `draftgo list-targets`。 |
-| 安装、完全更新或移除 Skill | 分别运行 `draftgo init [target...]`、`draftgo update [target...]`、`draftgo uninstall <target\|all>`。 |
-| 连接已有基座 | 运行 `draftgo connect`，写入项目连接并拉取初始上下文。 |
-| 首次建立本地 Docker 基座 | 运行 `draftgo local setup`；后续使用 `draftgo local start\|stop\|logs\|status` 管理。兼容命令：`draftgo local-dev`、`draftgo local up`、`draftgo local down`。 |
-| 陌生项目、跨资源或入口不清 | 运行 `draftgo map`，再读取相关 index 和资源文件。 |
-| 本地资源缺失、过期或需要云端版本 | 使用 `pull/SKILL.md`，运行 `draftgo pull [type] [id...]`。 |
-| 新建资源 | 在对应 index 中登记不带 `id` 的完整条目并创建其引用文件；运行 `draftgo check` 后，通过 `draftgo push <type>` 创建并回读写回的 `id` 和文件路径。 |
-| 删除资源 | 确认目标 `id` 和引用后运行 `draftgo delete <type> <id>`；该命令同时删除云端资源和本地登记，随后重新运行 `map` 与 `check`。 |
-| 页面、导航、交互或布局 | 读取 `references/frontend.md`；页面运行和布局证据使用 `draftgo verify-ui <url> --mobile-check auto`。 |
-| 页面或导航 HTML | 运行 `draftgo check`，验证入口、HTML 解析和资源登记；语法异常读取 `references/debugging-syntax.md`。 |
-| 动态 DB、filters 或 order_by | 先读对应 `db_meta` schema 和 `references/data.md`。 |
-| DraftGo 底座 API | 运行 `draftgo api <keyword>`，确认请求字段、响应结构和鉴权。 |
-| 自定义服务 | 读取 `references/custom-services.md`；其中包含 AIHub、知识库、Memory、Skill/MCP 的完整 Go SDK；端点从 `slug + app.Route` 推导为 `/api/x/<slug><route-path>`。 |
-| App 对象方法 | 读取 `references/app-api.md`。 |
-| AI Agent（配置、调用、工具/子智能体/记忆/持续对话、观测） | 读取 `references/aihub.md`；页面对话 UI、协议、事件与扩展读取 `references/chat-sdk.md`；App 与旧兼容门面见 `references/app-api.md`。 |
-| 平台架构、能力边界或安全限制 | 读取 `references/architecture.md`、`references/modules.md` 或 `references/security.md`。 |
-| 同步已确认的本地改动 | 使用 `push/SKILL.md`，运行 `draftgo push <type> [id...]`。 |
-| 交付前需要结构检查或预演 | 运行 `draftgo deploy [type] [id...] --delivery local\|preview\|deploy`。 |
-| 项目明确启用自动同步 | 运行 `draftgo auto-push [type] [id...]`；批量资源使用 `--batch`，未启用 `config.auto_push` 时命令只检查并跳过推送。 |
-| 项目已有 `.draftgo/story.yaml`，且请求可能改变产品定位或既有决定 | 读取并检查冲突；需要新建或维护 Story 时调用 `story/SKILL.md`。 |
+| 安装、更新、移除 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 |
+| 远端摘要或资源定位 | MCP project_overview、resource_search、resource_list、按需 metadata 工具 |
+| 页面、导航、文档正文 | checkout → 本地编辑 → check/verify-ui → diff → commit |
+| 结构化资源读写 | MCP api_search、api_describe、api_call 或语义化工具 |
+| 删除资源 | 使用实时 MCP/API 删除；不得从本地旧索引推断目标或清理正文 |
+| 兼容旧命令 | draftgo pull 只显示迁移提示并返回非零；draftgo push pages/nav/docs 显示弃用提示后转发到 commit。其他 push 类型引导使用 MCP。 |
 
 ## DraftGo 契约
 
-- **分页**：完整候选集、配置、资源或导出数据同时省略 `page` 和 `page_size`；真实分页列表同时传入 `page` 与 `page_size`。
-- **响应信封**：调用基座 API 时先检查 `res.code !== 200`，再读取 `res.data`。
-- **时间**：用户展示按用户/浏览器时区；存储、统计、定时和自然日边界按 `system_timezone` 计算。
-- **数据 schema**：字段名、类型、必填、searchable 和权限以 `.draftgo/db_meta/index.json` 为准；筛选和排序前确认字段与操作符兼容。
-- **自定义服务**：使用 `package main`、`Register(app *sdk.App)` 和 `func handler(draftgo *sdk.Context) (any, error)`；普通身份使用 `draftgo.Auth.CurrentUser()`，需要管理能力时逐次显式调用 `draftgo.Admin.*`。AI 能力使用 `draftgo.AIHub`、`draftgo.Knowledge`、`draftgo.Memory`；Route 权限和脚本管理权限是两层独立控制。
-- **系统资源**：登录、设置、权限、用户和系统配置属于基座资源；修改前确认影响范围并保留原有系统能力。
+- 响应信封：调用实时 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。
+- 系统资源：登录、设置、权限、用户和系统配置属于基座资源；修改前确认影响范围并保留原有系统能力。
 
-## 资源验证
+## 安全规则
+
+- 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。
+
+## 验证与交付
 
 | 资源 | 证据 |
 |---|---|
-| 页面、导航、新资源 | 运行 `draftgo check`，并确认入口引用。 |
-| 页面运行、交互或布局 | 运行 `draftgo verify-ui <url>`。 |
-| 基座 API、动态 DB | 真实请求或回读关键状态、字段和错误处理。 |
-| 自定义服务 | 调用目标 Route 或无副作用健康端点，确认状态码与响应；涉及管理员调用时确认审计。 |
-| 删除资源 | 重新运行 `draftgo map` 与 `draftgo check`，确认入口、引用和本地文件已闭合。 |
+| 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 测试 |
+
+draftgo deploy、auto-push 等旧交付入口必须遵循当前 CLI 的 commit 语义；不把它们当作旧全量 push 的回退路径。
+
+## 参考路由
 
-`draftgo check` 覆盖页面入口、页面/导航 HTML 解析和本地资源登记；运行证据由对应资源的验证动作提供。
+- 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/pages/` | 页面索引与 HTML |
-| `.draftgo/navigations/` | 导航索引与 HTML |
-| `.draftgo/db_meta/` | 数据 schema 与权限 |
-| `.draftgo/custom_scripts/` | 自定义服务元数据与 Go 代码 |
-| `.draftgo/aihub/` | AIHub 资源 |
-| `.draftgo/docs/articles/` | 文档元数据与 HTML |
-| `.draftgo/doc_categories/` | 文档分类 |
-| `.draftgo/system_config/` | 系统配置 |
-| `.draftgo/roles/`、`.draftgo/users/` | 角色与用户 |
-| `.draftgo/story.yaml` | 产品身份、设计和长期决策 |
+| .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/、changelog.md | 项目决策、任务和经验；按项目策略保留 |

package/resources/skill/init/SKILL.md

@@ -1,28 +1,42 @@
 ---
 name: draftgo-init
-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.
+description: Install or refresh the DraftGo skill, connect a project to a DraftGo base, and configure or diagnose its project-level MCP host integration.
 ---
 
 # DraftGo 初始化
 
-使用公开 CLI 完成安装和连接，不直接调用 `scripts/` 下的内部脚本。
+使用公开 CLI 完成安装和连接；不要直接调用已删除的同步脚本，也不要创建全量业务镜像。
 
 ## 执行
 
-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 status 查看已安装目标、Skill 版本和项目连接状态。
+2. 需要查看宿主能力时运行 draftgo list-targets；不要假设每个宿主都支持项目级 MCP。
+3. 尚未安装时运行 draftgo init [target...]；不指定 target 时由 CLI 自动识别。
+4. 已安装但需要刷新时运行 draftgo update [target...]。
+5. 项目缺少 .draftgo/config.json 时选择基座：
+   - 已有 DraftGo 服务器：运行 draftgo connect。
+   - 需要本地 Docker 基座：运行 draftgo local setup。
+6. 连接后运行 draftgo mcp setup（或指定目标），再运行 draftgo mcp test 验证 initialize、tools/list 和关键工具。
+7. 运行 draftgo map 获取远端摘要和本地 checkout 状态；MCP 不可用时报告原因，不回退到 pull --all。
 
-`draftgo init` 负责安装 Skill；`draftgo connect` 负责写入服务器连接并拉取初始上下文。不要混用两者的职责。
+draftgo init 只负责 Skill 安装；draftgo connect 负责保存并验证 server/SAT；draftgo mcp setup 负责宿主配置。不要混用职责。
+
+## SAT 与配置
+
+- 交互式连接应使用隐藏输入；不要把 SAT 写入宿主配置、Skill 文件、命令行示例或日志。
+- .draftgo/config.json、checkout manifest、base 和冲突目录必须加入项目 .gitignore。
+- bridge 从当前项目配置读取 SAT；宿主配置只引用 draftgo mcp serve。
+- 旧 .draftgo 缓存不自动删除。把它当作 legacy 数据，提示用户使用 MCP 或 checkout 重新建立上下文。
 
 ## 后续动作
 
-- 刷新云端资源：`draftgo pull [type] [id...]`
-- 管理本地基座：`draftgo local start|stop|logs|status`
-- 移除指定目标：`draftgo uninstall <target>`
-- 完整移除所有目标：仅在用户明确要求时运行 `draftgo uninstall all`；`--purge` 还会删除项目的 `.draftgo/` 数据。
+- 宿主配置和诊断：draftgo mcp setup/status/test，详见 ../references/mcp.md。
+- 远端资源摘要：MCP project_overview、resource_search、resource_list。
+- 正文编辑：draftgo checkout <pages|nav|docs> <id...>，本地修改后 draftgo check、draftgo diff、draftgo commit ...。
+- 结构化资源：直接使用 MCP 的 api_search、api_describe、api_call；不 checkout、不生成本地镜像。
+- 管理本地基座：draftgo local start|stop|logs|status；local-dev、local up/down 仍可用。
+- 移除指定目标：draftgo uninstall <target>；完整移除所有目标只在用户明确要求时运行 draftgo uninstall all，--purge 会删除 .draftgo/。
+
+## 迁移旧命令
+
+draftgo pull 不再执行同步。它只能给出迁移提示并返回非零，指导使用 MCP 定位资源或 checkout 长正文。不要悄悄恢复全量下载。

package/resources/skill/manifest.json

@@ -2,14 +2,16 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.33",
+  "version": "3.0.38",
   "entry": "SKILL.md",
-  "description": "DraftGo 应用的开发、资源同步、验证与交付工作流。",
+  "description": "以 Skill/reference 优先路由、MCP 实时发现、长正文 checkout/commit、验证、本地运行与 Skill 分发的 DraftGo 工作流。",
   "license": "MIT",
   "capabilities": [
     "draftgo-development",
     "custom-service-ai-sdk",
-    "resource-sync",
+    "mcp-bridge",
+    "content-checkout-commit",
+    "conflict-safe-delivery",
     "project-validation",
     "skill-installation"
   ],
@@ -20,8 +22,14 @@
     "network:explicit"
   ],
   "resources": {
-    "references": ["references"],
+    "references": [
+      "references"
+    ],
     "scripts": "scripts",
-    "subskills": ["init", "pull", "push", "story"]
+    "subskills": [
+      "init",
+      "push",
+      "story"
+    ]
   }
 }

package/resources/skill/push/SKILL.md

@@ -1,48 +1,60 @@
 ---
-name: draftgo-push
-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.
+name: draftgo-commit
+description: Commit checked-out DraftGo pages, navigation, and documentation content with base-version protection, local validation, and explicit conflict handling; route structured resources through MCP and explain the limited pages/nav/docs legacy push alias.
 ---
 
-# DraftGo 推送与交付
+# DraftGo Checkout / Commit
 
-使用 `draftgo push`、`draftgo deploy` 或 `draftgo auto-push`；内部 Python 脚本由 CLI 定位和执行。
+commit 是长正文的唯一正式交付动作。push pages/nav/docs 仅是兼容入口，应显示弃用提示后转发到对应的 commit；其他资源不从本地索引推送。
 
 ## 选择动作
 
 | 意图 | 命令 |
 |---|---|
-| 同步已确认的本地资源 | `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` |
+| 下载页面正文 | draftgo checkout pages <id...> |
+| 下载导航正文 | draftgo checkout nav <id...> |
+| 下载文档正文 | draftgo checkout docs <id...> |
+| 检查当前工作区 | draftgo check |
+| 查看 base/local 差异 | draftgo diff <type> <id> |
+| 提交页面、导航或文档 | draftgo commit pages|nav|docs <id...> |
+| 列出冲突 | draftgo conflicts |
+| 查看冲突材料 | draftgo conflict show <type> <id> |
+| 明确解决冲突 | draftgo conflict resolve <type> <id> |
+| 只查询正文片段 | MCP search/fragment 工具 |
+| 操作结构化资源 | MCP api_search/api_describe/api_call |
 
-`push` 不自动运行 `check`。`deploy` 始终先运行 `check`。`auto-push` 先检查，并且仅在 `.draftgo/config.json` 的 `auto_push` 为 `true` 时推送。
+## Checkout
 
-## 创建与更新
+1. 通过 MCP 取得元数据、content_type、base version/revision 和 base_hash。
+2. CLI 使用项目 SAT 通过专用 HTTP 流下载完整正文；正文不进入 MCP tool result。
+3. 直接流式写入同目录临时文件，完成后计算 SHA-256 并验证底座哈希。
+4. 校验成功后原子重命名到 .draftgo/worktree/ 正式路径，同时保存 .base/ 内容和 manifest。
+5. 不转换 HTML、Markdown 或原始编码；扩展名由 content_type 和底座安全扩展名决定。
 
-- 更新资源：修改 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` 更新或创建；角色与用户只更新已有记录。
+不得通过 MCP get、聊天上下文或 Python 旧脚本请求整篇正文。
 
-可推送类型：
+## Commit
 
-`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
+1. 读取 checkout manifest 指向的正文，计算 current_hash。
+2. 执行 draftgo check；页面改变时按需执行 draftgo verify-ui。
+3. 通过专用 HTTP 流上传正文，并携带 checkout 时的 base_version/revision 或 If-Match。
+4. 完整正文不作为 MCP tool 参数发送。
+5. 成功后原子更新 manifest、base、版本和哈希，并回读清晰的提交结果。
+6. 发生 409/412 时返回非零，停止重试和 auto-commit，保留 local/base 并生成 remote 及冲突 manifest。
 
-## 资源契约
+## 冲突
 
-- 页面、导航或新资源：推送前运行 `draftgo check`。
-- 自定义服务：修改前读取 `../references/custom-services.md`；推送后请求目标 `/api/x/<slug><route-path>`，不能只以推送成功作为完成证据。
-- 包含 `draftgo.Admin.*` 的服务：真实调用后回读执行详情，确认管理员 SDK 调用已进入审计。
-- 动态 DB：按 `../references/data.md` 和当前 `db_meta` schema 验证真实读写。
-- 系统配置、角色和用户：推送后回读关键字段，确认没有覆盖未登记的关系或敏感值。
+冲突目录必须包含可定位的 base、local、remote 三份材料。不要覆盖任一份，也不要手写不可靠的 HTML 合并器。Agent 或用户完成合并后，重新运行 check/verify-ui，确认最新 base，再执行 commit。
+
+## 结构化资源与兼容命令
+
+db_meta、AIHub、系统配置、角色、用户、分类和自定义服务元数据直接由 Agent 通过 MCP 操作。它们没有本地镜像、checkout manifest 或隐式 push 流程。
+
+draftgo push pages/nav/docs 可以保留为迁移兼容别名；draftgo push <other> 必须停止并提示使用 MCP。deploy 和 auto-push 若保留，只能调用当前 check + commit 语义，冲突时必须停止。
 
 ## 失败处理
 
-- 缺少 `.draftgo/config.json`：运行 `draftgo connect`。
-- HTTP 401：重新运行 `draftgo connect` 更新令牌。
-- 指定 id 未登记：重新读取对应 index 或先运行 `draftgo pull <type> [id...]`，不要猜测 id。
-- 推送返回非零状态：停止交付并处理错误，不把部分成功视为完整完成。
+- 缺少配置或 MCP 不可用：运行 draftgo mcp test，报告连接/SAT/底座问题；不要回退 pull。
+- 指定资源未 checkout：先通过 MCP 定位元数据，再运行 checkout；不要猜测 id。
+- 内容类型或编码未知：保留底座返回值并停止，不能强制改成 HTML/Markdown。
+- 提交返回 409/412：保留冲突状态，禁止自动覆盖、隐式 force 或自动重试。

package/resources/skill/references/aihub.md

@@ -1,19 +1,22 @@
 ---
-read_when: 创建或调优 AI Agent 时 · 编辑 .draftgo/aihub/ 时 · 需要工具/子智能体/记忆/多轮/结构化输出/多模态时
+read_when: 创建或调优 AI Agent 时 · 需要工具/子智能体/记忆/多轮/结构化输出/多模态时
 ---
 
 # AIHub / Agent 资源
 
-AIHub 资源既是「模型供应商」定义，也是「Agent」定义。本地登记在 `.draftgo/aihub/index.json`
-（`pull_simple`：只有 index，**没有独立内容文件**——整个 Agent 就是一条 JSON 行）。
-`push` 只发送这些字段：`type, name, data, priority, version, tags, describe, permission, status`。
+AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先使用 MCP `draftgo_resource_search`/`draftgo_resource_list`
+定位资产，再用 `draftgo_api_search`、`draftgo_api_describe` 获取实时契约，最后通过 `draftgo_api_call` 读写。
+更新 AIHub 资产时只发送实时契约允许的字段；常见字段包括
+`type, name, data, priority, version, tags, describe, permission, status`。供应商和模型使用各自的实时接口，
+不要经旧 AIHub 资产接口写入。任何输出、工作区文件或调用参数都不得保存 API Key 或 header 值；只可处理
+“是否已配置”以及 header 名称等非秘密元数据。
 **Agent 的全部行为都在 `data`（尤其 `data.spec`）里**——本页就是 `data.spec` 的字段地图。
 
 ## 条目骨架
 
 ```jsonc
 {
-  "type": "agent",                 // AIHub 条目类型（模型条目为供应商类型）
+  "type": "agent",                 // AIHub 资产类型
   "name": "产品顾问",
   "describe": "面向用户的产品答疑助手",
   "status": "active",

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

@@ -4,8 +4,10 @@ read_when: 需要查具体 API 端点时 · 构造请求时
 
 # 后端 API 速查
 
-> 优先运行 `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 验证。
+> 实时契约以 MCP `draftgo_api_search` / `draftgo_api_describe` 为准；CLI 中可用 `draftgo api <keyword>` 查询。
+> 本页只保留领域速查和 OpenAPI 无法表达的约束，不是静态完整契约。自定义服务的运行时路由由 `app.Route`
+> 动态注册，不会出现在底座 OpenAPI 中；按 `<METHOD> /api/x/<slug><route-path>` 推导，保存或发布后必须请求
+> 无副作用 GET Route 验证。
 > 统一响应信封：`{ code: 200, data: <载荷>, message: "success" }`
 > GET 列表端点通常在不传 `page` / `page_size` 时全量返回；自定义服务执行记录是固定分页特例（默认 20，最大 100）。
 > Go 自定义服务使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，筛选和分页见 `references/custom-services.md`。
@@ -90,7 +92,7 @@ ANY              /api/x/{slug}/{path}   ← 脚本运行时端点
 
 自定义服务要点：
 
-- 本地文件：`.draftgo/custom_scripts/index.json` + 每条记录的 `code_file`。
+- 自定义服务是结构化远端资源：通过 MCP 查询元数据和实时接口契约，通过 `draftgo_api_call` 创建或更新；不要依赖本地 `index.json` 镜像。
 - 新服务使用 Go `Register(app *sdk.App)`；用 `app.Route` / `app.On` / `app.Schedule` 自动注册。
 - 新服务使用 `mode=mixed`，可同时暴露 HTTP、响应事件和执行 cron。
 - route 注册来自 `app.Route("METHOD", "/path", handler)`；一个服务可声明多个 route，共用同一个 slug 命名空间。

package/resources/skill/references/architecture.md

@@ -22,7 +22,7 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 | 页面内容更新 | 需要重新编译部署 | 直接改数据库 HTML，秒级生效 |
 | 多租户/多项目 | 需要多套工程 | 一套壳层，数据库隔离内容 |
 | 权限控制 | 路由守卫 + 条件渲染 | `page.permission` 字段控制，壳层统一拦截 |
-| 导航定制 | 改代码重部署 | 改 navigation.html，推送即生效 |
+| 导航定制 | 改代码重部署 | MCP 定位后 checkout navigation.html，commit 即生效 |
 
 **核心推论**：在 DraftGo 里「修改页面」= 修改数据库里的 HTML 字符串，不是修改 `.tsx` 文件。
 

package/resources/skill/references/checkout.md

@@ -0,0 +1,116 @@
+---
+read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manifest 时 · 处理 409/412 冲突时
+---
+
+# Checkout / Commit
+
+> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明长正文的传输、版本和冲突规则，不能替代页面、前端、运行时或安全资料。
+
+## 适用范围
+
+只有长正文使用 worktree：
+
+| 输入类型 | 规范类型 | 本地目录 | 文件前缀 |
+|---|---|---|---|
+| `page` / `pages` | `pages` | `.draftgo/worktree/pages/` | `page_` |
+| `nav` / `navigation` / `navigations` | `navigations` | `.draftgo/worktree/navigations/` | `nav_` |
+| `doc` / `docs` / `article(s)` / `docs/articles` | `docs` | `.draftgo/worktree/docs/` | `article_` |
+
+db_meta、AIHub、system_config、roles、users、doc_categories 和普通配置使用 MCP 实时 API，不 checkout。
+
+## 命令
+
+```bash
+draftgo checkout <pages|nav|docs> <id...>
+draftgo commit <pages|nav|docs> <id...>
+draftgo diff <pages|nav|docs> <id>
+draftgo conflicts
+draftgo conflict show <pages|nav|docs> <id>
+draftgo conflict resolve <pages|nav|docs> <id>
+```
+
+`checkout --force` 只用于用户明确允许丢弃未提交本地修改的情况。默认 checkout 检测到 worktree 文件相对
+base 已变化时必须拒绝覆盖。
+
+## Checkout 流程
+
+1. CLI 通过 MCP `draftgo_resource_get_metadata` 取得规范类型、content_type、SHA-256、大小、版本/revision、
+   ETag 和受信任的下载/提交 URL。
+2. CLI 使用 `.draftgo/config.json` 中的 SAT 通过专用 HTTP 下载完整正文；SAT 不进入 MCP 参数或日志。
+3. 响应体直接流式写入同目录临时文件，校验 content_type、字节数和 SHA-256。
+4. 校验成功后原子重命名到 worktree 文件，并保存相同字节的 `.base` 文件。
+5. 最后原子更新 `.draftgo/worktree/manifest.json`。失败时不得留下半截正式文件或推进 manifest。
+
+正文不做 HTML/Markdown 转换，也不改变编码。扩展名规则：
+
+- `text/html`、`application/xhtml+xml` -> `.html`
+- `text/markdown`、`text/x-markdown` -> `.md`
+- `text/plain` -> `.txt`
+- 其他类型只接受底座返回的安全扩展名；缺失或不安全时拒绝 checkout
+
+## Manifest
+
+路径固定为 `.draftgo/worktree/manifest.json`，schema version 当前为 `1`。条目键使用规范类型和 id：
+
+```json
+{
+  "schema_version": 1,
+  "updated_at": "2026-07-30T12:00:00.000Z",
+  "entries": {
+    "pages:42": {
+      "server": "https://draftgo.example",
+      "resource_type": "pages",
+      "resource_id": "42",
+      "title": "Example",
+      "route": "/example",
+      "code": null,
+      "slug": null,
+      "local_path": ".draftgo/worktree/pages/page_42.html",
+      "content_type": "text/html",
+      "file_extension": ".html",
+      "content_size": 123,
+      "base_path": ".draftgo/worktree/.base/pages/page_42.html",
+      "base_version": "7",
+      "base_revision": null,
+      "base_etag": null,
+      "base_hash": "<sha256>",
+      "checked_out_at": "2026-07-30T12:00:00.000Z"
+    }
+  }
+}
+```
+
+`server` 必须和当前连接一致。`local_path`、`base_path` 必须是项目内相对路径。manifest、worktree `.base`
+和冲突目录必须 gitignore；不要手工伪造版本或哈希。
+
+## Commit 流程
+
+1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
+2. 按 content_type 执行本地结构检查；页面布局或交互有变化时另外运行 `draftgo verify-ui`。
+3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
+4. 完整正文不得作为 MCP tool 参数发送。
+5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
+
+推荐编辑顺序：完成相关 `references/` 的任务预读 -> MCP 定位 -> checkout -> 本地编辑 -> `draftgo check` -> 必要时 `draftgo verify-ui`
+-> `draftgo diff` -> commit。
+
+## 409 / 412 冲突
+
+版本冲突时 CLI 返回非零，不自动重试、不 force、不覆盖 worktree local，并写入：
+
+```text
+.draftgo/conflicts/<pages|navigations|docs>/<id>/
+├── conflict.json
+├── base.<ext>
+├── local.<ext>
+└── remote.<ext>
+```
+
+- `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
+- `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
+- Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
+- 合并完成后运行 `draftgo check`、必要时 `draftgo verify-ui`，再执行 `draftgo conflict resolve <type> <id>`。
+- resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
+  `draftgo diff` 并 `draftgo commit`。
+
+存在 unresolved conflict 时 commit、deploy 或 auto-commit 必须停止。

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

@@ -41,29 +41,28 @@ func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 
 `Register` 必须没有业务副作用。它只注册 handler；网络请求、写数据库、发通知等操作放在 handler 内。
 
-## 本地资源
+## 资源读写
 
-```text
-.draftgo/custom_scripts/
-├── index.json
-└── script_<id>_<slug>.go
-```
+自定义服务是结构化远端资源，不使用 checkout/commit，也没有约定的本地镜像目录。先用
+`draftgo_resource_search` 定位服务，再用 `draftgo_api_search` / `draftgo_api_describe` 获取当前管理接口契约，
+通过 `draftgo_api_call` 读取、创建或更新。Agent 可以在普通工作区文件中编写和检查 Go 源码，但不得把该文件
+误当作远端事实来源；写入时按实时契约显式发送代码和元数据。
 
-`index.json` 的 Go 服务字段：
+常见服务载荷字段如下，实际字段以 `draftgo_api_describe` 为准：
 
 ```json
 {
   "name": "order-service",
   "slug": "order-service",
 	"mode": "mixed",
-  "code_file": ".draftgo/custom_scripts/script_new_order-service.go",
+  "code": "package main\n\n// ...\n",
   "go_mod": "module example.com/order-service\n\ngo 1.26.0\n\nrequire github.com/google/uuid v1.6.0\n",
   "go_sum": ""
 }
 ```
 
 - 新服务使用 `mode=mixed`，允许同一个 `Register` 同时注册 route、event 和 scheduled。旧服务可继续使用单一 `route`、`event` 或 `scheduled` mode。
-- `go_mod` 和可选的 `go_sum` 随服务版本保存并由 `draftgo push custom_scripts` 推送。
+- `go_mod` 和可选的 `go_sum` 随服务版本保存，并和代码一起通过实时管理 API 提交。
 - 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
 
 ## 触发器
@@ -305,4 +304,4 @@ value, err := draftgo.AIHub.Request(draftgo.Context(), sdk.AIRequest{
 - [ ] 路由使用 `app.Route`，事件使用 `app.On`，定时任务使用 `app.Schedule`。
 - [ ] handler 返回 `(any, error)`，需要状态码时使用 `draftgo.Respond`。
 - [ ] Route 显式设置 `permission` 与 `route_security`。
-- [ ] 推送后请求无副作用 GET Route，必要时运行 `draftgo push custom_scripts --probe-routes`。
+- [ ] 保存或发布后请求无副作用 GET Route，并记录状态码和响应作为验收证据。