draftgo-cli 1.0.5 → 1.0.6

package/README.md

@@ -15,7 +15,7 @@ UI 稿用于必要的视觉讨论；已有页面先准确定位元素，再修
 ## 核心规则
 
 - 根 Skill 自动加载；Agent 只读取当前任务需要的 Reference。
-- pages、navigations 和 docs/articles 的完整正文使用 `checkout`、worktree、`diff`、`commit`；结构化资源使用 MCP/API。
+- pages、navigations、docs/articles 与 Go 源码使用 `checkout`、worktree、`diff`、`commit`；结构化资源使用 MCP/API。
 - MCP schema 是服务端实时契约。已知 operation 优先使用项目私有缓存；首次使用或 `registry_revision` 变化时 describe。schema 不写入 Skill 或聊天上下文。
 - 独立资源按 owner 并行，CLI 请求使用有界并发；同一资源的依赖步骤保持串行。
 - 每个任务开始记录到 `.draftgo/worklog.md`，验证和交付成功后再标记完成。

package/package.json

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

package/resources/skill/SKILL.md

@@ -8,9 +8,9 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 ## 开始前
 
 - 任务开始即运行 `draftgo work start "<事项>"`；记录 CLI 返回的工作项引用。独立事项用 `draftgo work add`，仅在验证和交付成功后运行 `draftgo work complete <ref> --note "<证据>"`。
-- 根 Skill 会在触发时自动加载；先读取下表中最少必要的 Reference，再用 MCP 查询当前项目。不要预先读取所有 Reference，也不要把动态 operation schema 写入 Skill 或聊天上下文。
-- pages、navigations 与 docs/articles 的完整正文只能通过 `draftgo checkout`、worktree、`draftgo diff`、`draftgo verify` 和 `draftgo commit` 处理；MCP 只用于定位、元数据和结构化资源。不要把完整正文或响应快照写入聊天上下文或手工归档。
-- 已知页面 route 或标题时，用 `draftgo map --type pages --route <path>` 或 `--title <title>` 精确定位；两个筛选条件取交集。只需范围或状态时加 `--summary`；需要浏览时使用 `--limit`（默认 20）和后续 `--cursor`，绝不默认全量枚举。
+- 根 Skill 会在触发时自动加载；先读取下表中最少必要的 Reference，再用 MCP 查询当前项目。不要预先读取所有 Reference，也不要把动态 operation schema 写入 Skill 或聊天上下文。实时契约以 `draftgo api describe` 和 `.draftgo/api-contract-cache.json` 为准，不要把 OpenAPI 固化进 Skill。
+- pages、navigations、docs/articles 与 Go 服务源码只能通过 `draftgo checkout`、worktree、`draftgo diff`、`draftgo verify` 和 `draftgo commit` 处理；MCP 只用于定位、元数据和结构化资源。不要把完整正文或响应快照写入聊天上下文或手工归档。
+- 已知页面 route 或标题时，用 `draftgo map --type pages --route <path>` 或 `--title <title>` 精确定位，或在唯一命中时用 `draftgo checkout pages --route <path>` / `--title <title>`；两个筛选条件取交集。只需范围或状态时加 `--summary`；需要浏览时使用 `--limit`（默认 20）和后续 `--cursor`，绝不默认全量枚举。
 - `--output json` 的 stdout 是单一 UTF-8 JSON；诊断和进度走 stderr。不要依赖终端截断来控制上下文。
 - 正常交付只运行 `draftgo verify`。默认跳过 UI；用户要求视觉修改或视觉验收时才使用截图，要求交互或 DOM 验证时才使用 `--ui always`。
 
@@ -26,6 +26,7 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 | 任务 | 先读 |
 |---|---|
+| 已知页面的小范围 UI 修改 | 先定位并 checkout；需要组件、运行时或新建页面时再读 `references/frontend.md` |
 | 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md` |
 | pages/nav/docs 正文、版本或冲突 | `references/checkout.md` |
 | 自定义 Go 服务、源码、SDK、草稿或策略 | `references/services.md` |

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/ai.md

@@ -34,7 +34,7 @@ draftgo api call <operation_id> --input request.json --output json
 - 模型是否支持 Chat、Responses、Embedding、Rerank、TTS、ASR、图片或视频，必须由当前模型声明、Provider readiness 和有效路由共同证明。
 - 知识库和长期记忆用途不同，不能互相替代；索引完成不等于检索质量达标。
 - 智能体调用失败时分层检查模型路由、提示词版本、插件可用性、知识检索、记忆配置和运行日志，不在客户端自动重放非幂等调用。
-- DraftGo Page 的 AI 对话使用组件目录中的 `draftgo/chat`；完整 Chat 实现由组件 `Definition.JS` 随同一 revision 发布并按需解析，不存在第二套静态 SDK。其他模型能力（包括图片、Embedding、Rerank、TTS、ASR 和 Video）通过服务端 AI Registry 调用。浏览器端不得持有 Provider 密钥，也不要复制一套客户端 Provider SDK。
+- DraftGo Page 的 AI 对话使用组件 `draftgo/chat`，见 `chat-sdk.md`。其他模型能力通过服务端 AI Registry 调用。浏览器端不得持有 Provider 密钥。
 
 ## 完成条件
 

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

@@ -12,17 +12,17 @@ const App = window.parent?.App;
 
 | 方法 | 签名 | 说明 |
 |---|---|---|
-| `App.get` | `(path, params?, headers?)` | GET，params 为 query 参数 |
-| `App.post` | `(path, body?, headers?)` | POST |
-| `App.put` | `(path, body?, headers?)` | PUT |
-| `App.patch` | `(path, body?, headers?)` | PATCH |
-| `App.delete` | `(path, params?, headers?)` | DELETE |
+| `App.get` | `(path, params?, headers?)` | GET，params 为 query 参数 |
+| `App.post` | `(path, body?, headers?)` | POST |
+| `App.put` | `(path, body?, headers?)` | PUT |
+| `App.patch` | `(path, body?, headers?)` | PATCH |
+| `App.delete` | `(path, params?, headers?)` | DELETE |
 | `App.uploadFile` | `(file, onProgress?)` | 文件上传，返回标准信封 |
 
 **响应格式**：`{ code: 200, data: <载荷>, message: "success" }`  
 **消费范式**：
 ```javascript
-const res = await App.get('pages', { page: 1, page_size: 20 }); // 按返回的分页信息继续读取
+const res = await App.get('pages', { page: 1, page_size: 20 }); // 按返回的分页信息继续读取
 if (res.code !== 200) { App.showError(res.message); return; }
 const items = res.data.items;
 
@@ -33,10 +33,10 @@ const paged = await App.get('pages', { page: 1, page_size: 20 }); // 显式分
 
 | 方法 | 签名 | 说明 |
 |---|---|---|
-| `App.showSuccess` | `(msg)` | 成功 Toast |
-| `App.showError` | `(msg)` | 错误 Toast |
-| `App.showWarning` | `(msg)` | 警告 Toast |
-| `App.showInfo` | `(msg)` | 信息 Toast |
+| `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） |
@@ -66,32 +66,34 @@ const { patientId, visitId } = routeContext.query;
 | 属性 | 类型 | 说明 |
 |---|---|---|
 | `App.currentUser` | object \| null | 当前用户，未登录为 null |
-| `App.isAdmin` | boolean | 是否管理员 |
-| `App.permissions` | string[] | 当前用户有效权限的展示投影；仅用于页面显隐，不替代服务端授权 |
-| `App.isAuthenticated` | boolean | 是否已认证 |
+| `App.isAdmin` | boolean | 是否管理员 |
+| `App.permissions` | string[] | 当前用户有效权限的展示投影；仅用于页面显隐，不替代服务端授权 |
+| `App.isAuthenticated` | boolean | 是否已认证 |
 | `App.hasToken` | boolean | 是否有 token（含未验证） |
 | `App.config` | object | 系统配置 KV |
 | `App.theme` | `'light'` \| `'dark'` | 当前显示模式 |
-| `App.colorScheme` | string | 当前配色方案 |
+| `App.colorScheme` | string | 当前配色方案 |
 
 ## 主题
 
 ```javascript
-App.applyTheme('dark');                           // 切换显示模式
-App.setColorScheme('deep-blue-white');            // 切换预设配色
-App.setColorScheme('custom', customVarsObject);   // 自定义配色
-App.getColorScheme();                             // 获取方案详情
+App.applyTheme('dark');
+App.toggleTheme();
+App.getColorScheme();
 ```
 
+页面不调用 `setColorScheme`。配色由壳层主题变量提供。
+
 ## 其他
 
 ```javascript
-await App.logout();                 // 服务端登出、清理状态并跳转配置的登录页
-App.setAuthTokens({ access_token, refresh_token });  // 登录后写入 token
-App.reloadGlobalLayer();            // 重载全局层
-App.openGlobalWidget(name);         // 触发全局挂件打开
-App.t(key, fallback?, values?);      // 页面级国际化文本，values 保留 ICU 占位符
-App.formatDateTime(value, options?); // 按 system_timezone 格式化 API 返回的 UTC 时间
-```
-
-Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话组件契约见 `references/chat-sdk.md`，其他 AI 能力见 `references/ai.md`。Chat 与其他 DraftGo 组件使用同一组件库交付，不存在独立 SDK 静态文件。
+await App.logout();
+App.setAuthTokens({ access_token, refresh_token });
+App.reloadGlobalLayer();
+App.t(key, fallback?, values?);
+App.formatDateTime(value, options?);
+```
+
+没有 `openGlobalWidget`。全局层用 `App.reloadGlobalLayer()`。
+
+Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话组件契约见 `references/chat-sdk.md`，其他 AI 能力见 `references/ai.md`。Chat 与其他 DraftGo 组件使用同一组件库交付，不存在独立 SDK 静态文件。

package/resources/skill/references/chat-sdk.md

@@ -1,31 +1,15 @@
 ---
-read_when: DraftGo Page 需要 AI 对话组件时 · 开发或扩展 draftgo/chat 时
+read_when: DraftGo Page 需要 AI 对话组件时
 ---
 
-# DraftGo Chat 组件
+# draftgo/chat
 
-DraftGo Page 统一使用组件目录中的 `draftgo/chat`。完整实现保存在组件 `Definition.JS`，负责原生 `<dg-chat>`、消息状态机、流解析、停止、重试和历史逻辑，并与 HTML、CSS、Props 和事件使用同一草稿与发布版本。Page 不复制实现，也不手写流式请求。
-
-## 目录
-
-- [最小接入](#最小接入)
-- [协议](#协议)
-- [配置与布局](#配置与布局)
-- [JavaScript API 与事件](#javascript-api-与事件)
-- [历史与会话](#历史与会话)
-- [扩展](#扩展)
-- [鉴权与安全](#鉴权与安全)
-
-## DraftGo Page 最小接入
-
-先从当前实例读取组件契约，不按本文猜测 Props：
+Page 对话 UI 是组件库组件 `draftgo/chat`，不是独立 SDK。先读实时契约：
 
 ```text
 draftgo components show draftgo/chat --output json
 ```
 
-在 Page 中保存组件活引用；运行时仅在实际引用时返回完整组件，同页相同 revision 与 hash 只编译一次：
-
 ```html
 <dg-chat
   data-dg-use="draftgo/chat"
@@ -37,169 +21,11 @@ draftgo components show draftgo/chat --output json
 </dg-chat>
 ```
 
-`draftgo-agent` 默认请求 `/api/agents/{id}/chat`，并复用同源 DraftGo App 的 Bearer token 与刷新机制。
-
-`draftgo/chat` 公开 Agent、视图、surface、主题、语言、附件、历史、流式开关、打开状态和超时等稳定 Props，并透传已声明的 `dg-chat:*` 事件。函数、DOM Node、自定义 transport、renderer 和 plugin 不进入 `data-dg-prop-*`。
-
-DraftGo 不维护独立 Chat SDK 静态文件或外部应用直连交付路径。无 UI 的文本、图片或其他模型能力调用统一使用服务端 AI Registry operation；这样可保持 Provider 密钥、路由和用量控制在服务端。
-
-## 协议
-
-| `protocol` | 必需配置 | 说明 |
-|---|---|---|
-| `draftgo-agent` | `agentId` | DraftGo Agent；默认端点 `/api/agents/{id}/chat` |
-| `openai-chat`（alias `openai`） | `endpoint` | OpenAI Chat Completions 兼容协议 |
-| `openai-responses` | `endpoint` | OpenAI Responses 协议 |
-| `anthropic-messages`（alias `anthropic`） | `endpoint` | Anthropic Messages 协议 |
-| `custom` 或注册名 | 已注册 transport | 页面提供 async generator transport |
-
-外部协议必须指向服务端代理：
-
-```html
-<dg-chat protocol="openai-chat" endpoint="/api/ai-proxy/openai" model="MODEL"></dg-chat>
-<dg-chat protocol="openai-responses" endpoint="/api/ai-proxy/responses" model="MODEL"></dg-chat>
-<dg-chat protocol="anthropic-messages" endpoint="/api/ai-proxy/anthropic" model="MODEL"></dg-chat>
-```
-
-这些 `/api/ai-proxy/*` 是接入方实现的占位路由，不是 DraftGo 自动提供的默认代理。不要将供应商密钥或长期 token 写入页面。
-
-内置 transport 支持 SSE、NDJSON 和普通 JSON，并把上游响应归一化为 `text.delta`、`reasoning.delta`、`tool.start`、`tool.delta`、`tool.finish`、`step.finish`、`artifact.complete`、`source`、`usage`、`message.finish`、`error` 等事件。DraftGo Page 只使用实时 `draftgo/chat` 组件契约，不要猜测字段或把函数、DOM、renderer、plugin、transport 写入 Props。
-
-## 组件配置与布局
-
-以下直接属性与 JSON 配置用于组件库高级扩展；普通 DraftGo Page 以实时 `draftgo/chat` Props 为准。
-
-```html
-<dg-chat
-  id="page-assistant"
-  protocol="draftgo-agent"
-  agent-id="AGENT_ID"
-  surface="drawer"
-  view="threads"
-  position="right"
-  title="AI Assistant"
-  placeholder="输入内容"
-  persist="true"
-  stream="true"
-  enable-attachments
-  show-reasoning
-></dg-chat>
-```
-
-| 配置 | 可选值 |
-|---|---|
-| `surface` | `inline`、`floating`、`drawer`、`fullscreen` |
-| `view` | `conversation`、`threads`、`compact`、`canvas` |
-| `position` | `left`、`right` |
-| `theme` | `light`、`dark`；省略时跟随系统 |
-
-复杂的纯数据配置使用 `config-ref`：
-
-```html
-<script type="application/json" id="page-chat-config">
-{
-  "protocol": "draftgo-agent",
-  "agentId": "AGENT_ID",
-  "surface": "inline",
-  "view": "canvas",
-  "storageKey": "dg-chat:PAGE_KEY:INSTANCE_KEY",
-  "features": {
-    "reasoning": true,
-    "attachments": true,
-    "history": true,
-    "feedback": false,
-    "artifacts": true
-  },
-  "suggestions": ["总结当前页面", "生成结构化结果"],
-  "context": { "page": "PAGE_KEY" }
-}
-</script>
-<dg-chat config-ref="page-chat-config"></dg-chat>
-```
-
-函数、DOM Node、renderer、plugin、upload 和 custom transport 只能通过 JavaScript 配置，不能写进 JSON。主题优先使用 `--dg-chat-*` CSS variables、公开 `::part()` 和 slots，不选择 Shadow DOM 内部 class。
-
-## JavaScript API 与事件
-
-```javascript
-const chat = document.querySelector('#page-assistant');
-
-chat.configure({ model: 'MODEL', context: { page: 'PAGE_KEY' } });
-await chat.send('处理当前输入');
-chat.stop();
-chat.regenerate();
-chat.newThread();
-chat.selectThread('THREAD_ID');
-chat.deleteThread('THREAD_ID');
-chat.renameThread('THREAD_ID', '新的会话名称');
-chat.clearThreads();
-chat.setMessages([]);
-chat.clear();
-chat.open();
-chat.close();
-chat.toggle();
-```
-
-组件内部运行时保留 `DraftGoChat.create()`、`registerTransport()`、`registerRenderer()`、`registerComponent()`、`definePreset()`、`use()` 等扩展接口，但它们不是独立静态 SDK 契约。
-
-常用事件：`dg-chat:ready`、`dg-chat:before-send`、`dg-chat:message`、`dg-chat:run-start`、`dg-chat:stream-event`、`dg-chat:run-finish`、`dg-chat:run-abort`、`dg-chat:error`、`dg-chat:message-action`、`dg-chat:session-change`、`dg-chat:model-change`、`dg-chat:open`、`dg-chat:close`。
-
-```javascript
-chat.addEventListener('dg-chat:run-finish', event => {
-  console.log(event.detail);
-});
-```
-
-页面销毁或离开路由时调用 `stop()`，取消上传、plugin 和在途 transport。
-
-`requestTimeoutMs` 和 `streamTimeoutMs` 分别控制客户端非流式/流式总时限，默认 120000/610000 毫秒，`0` 表示禁用。两者只处理客户端半开连接，不替代 Agent 的服务端超时。
-
-## 历史与会话
-
-- `persist` 默认开启，将 UI thread 历史写入 `localStorage`；敏感或临时页面设为 `false`。
-- 同一路由存在多个实例时，每个实例设置唯一 `storageKey`。
-- 每个 UI thread 自动维护独立 `sessionId`；`draftgo-agent` 将其作为 `session_id` 发送。
-- 切换会话只改变当前视图，不会停止其它 thread 的在途请求。会话列表标题左侧显示运行中状态；后台完成或失败后显示未读状态，进入该会话即视为已读并清除。
-- 每个请求使用独立 `run_id`。用户停止或 SDK 超时会调用 Agent 取消接口；普通会话切换不会发送取消。
-- 推理片段和工具调用按服务端事件的输出位置保留在消息内，不固定贴在消息底部；思考在正文、工具或结束事件到达后进入完成态，不再闪烁或滚动预览。
-- `newThread()` 创建新的后端会话边界；不要让不同用户共享固定 `storageKey` 或 `sessionId`。
-- `clear()` 和 `setMessages([])` 会重置当前 session，避免视觉清空后恢复旧 checkpoint。
-
-## 扩展
-
-自定义协议通过 async generator 产生统一事件：
-
-```javascript
-DraftGoChat.registerTransport('page-protocol', async function* (request, context) {
-  const response = await fetch('/api/x/page/chat', {
-    method: 'POST',
-    signal: context.signal,
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ messages: request.messages })
-  });
-  const data = await response.json();
-  yield { type: 'text.delta', delta: String(data.text || '') };
-  yield { type: 'message.finish' };
-});
-
-chat.configure({ protocol: 'page-protocol' });
-```
-
-局部定制优先级：属性/JSON → CSS variables、parts、slots → 实例 `components`/`renderers` → plugin/custom transport。全局注册会影响同一 window 的所有实例；页面特有行为优先放在实例配置中。
-
-## 鉴权与安全
-
-- 同源请求优先使用 iframe 可见的 `window.App.fetchAbsolute`，复用 DraftGo token 和刷新机制。
-- 供应商凭证不得自动或手工发送到外部 origin；OpenAI/Anthropic 使用服务端代理。
-- 页面 HTML、JSON config、`headers`、`context` 和 `localStorage` 中不得保存长期供应商密钥。
-- 不把模型输出直接赋给 `innerHTML`；使用 SDK 内置 Markdown/URL 安全渲染或显式净化。
-- 后端始终负责 Agent 调用权限、模型白名单、附件能力和大小限制，前端开关不能越权。
-- Agent 协议响应不应包含 Agent 内部模型名。模型选择器只能读取 Agent 明确授权的 `/selectable-models` 目录。
-
-交付前确认：DraftGo Page 使用 `draftgo/chat` 且不手工加载第二套脚本；同页多实例隔离 `storageKey`；外部协议走服务端代理；页面离开时停止在途请求。
-
-## 移动端契约
+- 只写 `data-dg-use`、`data-dg-instance`、`data-dg-prop-*`、`data-dg-slot`
+- 默认 `protocol=draftgo-agent`，请求 `/api/agents/{id}/chat`，复用 App Bearer
+- 函数、DOM、transport、renderer、plugin 不进 props
+- 不要手写流式、不要加载第二套脚本、不要把供应商密钥写入页面
+- 同页多实例用不同 `data-dg-instance`；敏感页设 `persist=false`
+- 无 UI 的模型调用走服务端 AI Registry，见 `ai.md`
 
-- `inline`、`floating`、`drawer`、`fullscreen` 四种 surface 均由 SDK 自适应窄屏；`threads`、`canvas` 和 Artifact 会按容器宽度自动收敛为单栏，不要复制 Shadow DOM 内部布局规则。
-- SDK 使用 `VisualViewport` 和 `safe-area-inset-*` 跟随软键盘、浏览器工具栏与横竖屏变化。触摸设备打开面板时不会主动弹出软键盘。
-- 触摸端按钮和行操作具有移动端点击尺寸，输入字号防止 iOS 自动缩放；所有内部滚动区隐藏滚动条，但仍保留触摸、滚轮和键盘滚动能力。
+Props 与事件以 `components show` 为准，不复制到页面或 Skill。

package/resources/skill/references/checkout.md

@@ -1,140 +1,65 @@
 ---
-read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manifest 时 · 处理 409/412 冲突时
+read_when: 编辑 pages、navigation、docs 或 Go 源码时 · 处理 409/412 冲突时
 ---
 
-# Checkout / Commit
-
-## 页面与内容最短流程
-
-```bash
-draftgo map --type pages --route /admin/channel-ops --output json
-draftgo checkout pages 42
-draftgo diff pages 42 --stat
-draftgo verify pages 42
-draftgo commit pages 42
-```
-
-导航和文档分别替换为 `nav`、`docs`。route/title 为精确匹配，两个条件取交集；只需确认范围或 checkout 状态时使用 `map --summary`，必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用 `--cursor <opaque>` 翻页。新资源先用 `draftgo api search "create page"` 或对应内容类型定位创建 operation，describe/call 取得 ID 后再 checkout；不要用 checkout 创建资源。`verify` 通过不等于已交付，commit 返回新版本与哈希才算正文写入成功。发生 409/412 时保留冲突材料并停止提交。
-
-## Workflow 2.0 coverage
-
-The checkout set includes `pages`, `navigations`, and `docs/articles`. DB Meta and all other structured resources remain live MCP/API resources and are never checked out.
-
-`draftgo refresh <type> <id...>` is a safe checkout shortcut. It updates only a clean local worktree; local changes stop it. A successful commit keeps current local files and one base only. Cloud version storage is the sole history source.
-
-> 根 `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、AI 配置、system_config、roles、users、doc_categories 和普通配置使用 MCP 实时 API，不 checkout。
-
-Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，不创建页面、导航或文档。新增资源先按 MCP 实时 API 契约创建并取得 ID；需要编辑完整正文时再 checkout。只需元数据或正文片段即可完成判断时，不必 checkout。
-
-## 命令
+# Checkout / Commit
 
 ```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> [--stat|--summary]
-draftgo conflicts
-draftgo conflict show <pages|nav|docs> <id>
-draftgo conflict resolve <pages|nav|docs> <id>
+draftgo map --type pages --route /admin/channel-ops --output json
+draftgo checkout pages 42
+draftgo diff pages 42 --stat
+draftgo verify pages 42
+draftgo commit pages 42
 ```
 
-`checkout --force` 只用于用户明确允许丢弃未提交本地修改的情况。默认 checkout 检测到 worktree 文件相对
-base 已变化时必须拒绝覆盖。
-
-`diff --stat` 只显示文件与增删行数；`diff --summary` 显示资源、基线版本和变化概要。两者均不输出正文 diff，先用它们确认范围，再按需展开完整 `diff`。`--output json` 时 stdout 只包含 UTF-8 JSON，诊断走 stderr。
-
-## Checkout 流程
-
-1. CLI 通过 MCP `draftgo_resource_get_metadata` 取得规范类型、content_type、SHA-256、大小、版本/revision、
-   ETag 和受信任的下载/提交 URL。
-2. CLI 使用 `.draftgo/config.json` 中的用户 API Key 通过专用 HTTP 下载完整正文；API Key 不进入 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"
-    }
-  }
-}
+`nav`、`docs` 同理。route/title 精确匹配，两条件取交集。已知唯一 route 或 title 时可直接：
+
+```bash
+draftgo checkout pages --route /admin/channel-ops
+draftgo checkout pages --title "渠道管理"
 ```
 
-`server` 必须和当前连接一致。`local_path`、`base_path` 必须是项目内相对路径。manifest、worktree `.base`
-和冲突目录必须 gitignore；不要手工伪造版本或哈希。
+必须指定资源类型，且不得再带 id。0 条匹配或超过 1 条都失败，不要猜测目标。`services` 不支持 `--route` / `--title`。
+
+范围确认用 `map --summary`；浏览用 `--limit`（默认 20）和单一类型的 `--cursor`。新资源先 `draftgo api search "create page"`（或对应类型）describe/call 取得 ID，再 checkout。checkout 不创建资源。
+
+`verify` 通过不等于已交付；commit 返回新版本与哈希才算正文写入成功。干净 worktree 可用 `draftgo refresh <type> <id>` 更新；有本地改动则停止。
+
+## 范围
 
-## Commit 流程
+| 输入 | 类型 | 本地目录 |
+|---|---|---|
+| page / pages | pages | `.draftgo/worktree/pages/` |
+| nav / navigation | navigations | `.draftgo/worktree/navigations/` |
+| doc / docs / article | docs | `.draftgo/worktree/docs/` |
+| service / services | services | `.draftgo/worktree/services/` |
 
-1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
-2. 按 content_type 执行本地结构和内联脚本检查。
-3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
-4. 完整正文不得作为 MCP tool 参数发送。
-5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
+Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，不创建页面、导航或文档。db_meta、AI、配置、角色等结构化资源走 MCP，不 checkout。Go 服务源码走 checkout/commit；创建、validate、试运行和 publish 仍用实时 API。
 
-本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
-
-单个 commit 成功不自动完成 worklog 项。只有整个事项统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行 `draftgo work complete <编号> --note "<完成结果>"`。任何检查失败、409/412 或交付失败都不得标记为完成。
+```bash
+draftgo checkout <pages|nav|docs|services> <id...>
+draftgo commit <pages|nav|docs|services> <id...>
+draftgo reconcile <pages|nav|docs|services> <id...>
+draftgo diff <pages|nav|docs|services> <id> [--stat|--summary]
+draftgo conflicts
+draftgo conflict show <pages|nav|docs|services> <id>
+draftgo conflict resolve <pages|nav|docs|services> <id>
+```
 
-## 409 / 412 冲突
+`--force` 仅在用户明确允许丢弃未提交本地修改时使用。`diff --stat` / `--summary` 不含正文；先确认范围再展开完整 diff。
 
-版本冲突时 CLI 返回非零，不自动重试、不 force、不覆盖 worktree local，并写入：
+本地已等于远端但 base/manifest 落后时：`draftgo check --remote` 确认 `committed_unrecorded`，再 `draftgo reconcile`。不要手改 manifest。
+
+## 409 / 412
+
+停止提交，不 force、不覆盖、不自动合并。材料在：
 
 ```text
-.draftgo/conflicts/<pages|navigations|docs>/<id>/
+.draftgo/conflicts/<pages|navigations|docs|services>/<id>/
 ├── conflict.json
 ├── base.<ext>
 ├── local.<ext>
 └── remote.<ext>
 ```
 
-- `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
-- `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
-- Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
-- 合并完成后运行 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
-- resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
-  `draftgo diff` 并 `draftgo commit`。
-
-存在 unresolved conflict 时 commit、deploy 或 auto-commit 必须停止。
+在 worktree local 合并 → `draftgo verify` → `draftgo conflict resolve <type> <id>` → `draftgo diff` → `draftgo commit`。有未解决冲突时不得 commit。任何检查失败、409/412 或交付失败都不得标记为完成。

package/resources/skill/references/development.md

@@ -36,6 +36,3 @@
 
 CLI 命令锁不能覆盖 Agent 整轮编辑；不同目录的锁也不隔离同一远端资源。owner 约定贯穿任务全过程，同资源串行，冲突按正文工作树规则处理。真正独立实验使用独立开发实例。CLI 请求使用有界并发，不能把多个 Agent 等同于无限连接。
 
-## 旧 Story 迁移
-
-仅旧项目需要：检查 .draftgo/story.yaml，将仍有效的产品定位、模块目标和决策原因迁入 Design；与现有 Design 或最新用户要求冲突的内容先核实，不覆盖有效文档。历史进度留给 worklog，不转成设计流水账。迁移核对前保留原文件，核对后在 worklog 记录迁移结果并停止读取 Story；用户未要求时不删除原产品档案。新项目不创建 Story，不并行维护两套设计来源。