draftgo-cli 1.0.4

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

@@ -0,0 +1,97 @@
+---
+read_when: 页面开发时需要查 App API · 忘记某个方法签名时
+---
+
+# App 对象速查表
+
+```javascript
+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.uploadFile` | `(file, onProgress?)` | 文件上传，返回标准信封 |
+
+**响应格式**：`{ code: 200, data: <载荷>, message: "success" }`  
+**消费范式**：
+```javascript
+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;
+
+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.toast` | `(msg, type?)` | 通用 Toast，type: success/error/warning/info |
+| `App.confirm` | `(msg, title?)` | 确认弹窗，返回 `Promise<boolean>` |
+| `App.showModal` | `(msg, title?)` | 信息模态框（替代 alert） |
+| `App.showLoading` | `()` | 全局 loading 蒙层 |
+| `App.hideLoading` | `()` | 关闭 loading |
+
+## 路由
+
+| 方法 | 说明 |
+|---|---|
+| `App.navigate(route)` | 路由跳转（pushState） |
+| `App.getCurrentRoute()` | 当前路径字符串 |
+| `App.getCurrentRouteContext()` | 完整路由上下文，含 `query` |
+
+**读取 URL 参数**（必须用此方式，不能用 `window.location.search`）：
+```javascript
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__
+  || window.__DG_GET_ROUTE_CONTEXT__?.()
+  || window.parent?.App?.getCurrentRouteContext?.()
+  || { query: {} };
+const { patientId, visitId } = routeContext.query;
+```
+
+## 状态
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `App.currentUser` | object \| null | 当前用户，未登录为 null |
+| `App.isAdmin` | boolean | 是否管理员 |
+| `App.permissions` | string[] | 当前用户有效权限的展示投影；仅用于页面显隐，不替代服务端授权 |
+| `App.isAuthenticated` | boolean | 是否已认证 |
+| `App.hasToken` | boolean | 是否有 token（含未验证） |
+| `App.config` | object | 系统配置 KV |
+| `App.theme` | `'light'` \| `'dark'` | 当前显示模式 |
+| `App.colorScheme` | string | 当前配色方案 |
+
+## 主题
+
+```javascript
+App.applyTheme('dark');                           // 切换显示模式
+App.setColorScheme('deep-blue-white');            // 切换预设配色
+App.setColorScheme('custom', customVarsObject);   // 自定义配色
+App.getColorScheme();                             // 获取方案详情
+```
+
+## 其他
+
+```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 静态文件。

package/resources/skill/references/architecture.md

@@ -0,0 +1,13 @@
+---
+read_when: 进入陌生项目或选择实现层时
+---
+
+# 架构与实现边界
+
+Go 后端承载业务模块和协议入口；React/Vite 前端负责浏览器壳层与 Page 运行时。业务页面是底座管理的完整 HTML，导航也是 HTML 资源，通过 CLI 定位、checkout、编辑和 commit。
+
+页面运行于 iframe.srcdoc，通过 window.parent.App 使用认证请求、路由、主题和反馈；签名见 `app-api.md`，生命周期见 `runtime.md`。访问与数据权限由后端执行，壳层显隐仅辅助交互。
+
+按需求选择现有模块、动态数据和组件；确需额外业务逻辑时读 `services.md`。组件目录来自当前实例，优先复用实际 props/slots。不同项目的数据隔离必须由实际部署与授权设计保证，不能从页面结构推断多租户隔离。
+
+用户产品目标从 Design/README.md 按模块读取；实际能力通过 Registry 查询，设计存在不代表已实现。模块入口见 `modules.md`，跨领域最短操作链见 `methods.md`。

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

@@ -0,0 +1,205 @@
+---
+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：
+
+```text
+draftgo components show draftgo/chat --output json
+```
+
+在 Page 中保存组件活引用；运行时仅在实际引用时返回完整组件，同页相同 revision 与 hash 只编译一次：
+
+```html
+<dg-chat
+  data-dg-use="draftgo/chat"
+  data-dg-instance="page-assistant"
+  data-dg-prop-agent-id="AGENT_ID"
+  data-dg-prop-view="conversation"
+  data-dg-prop-surface="inline"
+  data-dg-prop-enable-attachments="true">
+</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`；外部协议走服务端代理；页面离开时停止在途请求。
+
+## 移动端契约
+
+- `inline`、`floating`、`drawer`、`fullscreen` 四种 surface 均由 SDK 自适应窄屏；`threads`、`canvas` 和 Artifact 会按容器宽度自动收敛为单栏，不要复制 Shadow DOM 内部布局规则。
+- SDK 使用 `VisualViewport` 和 `safe-area-inset-*` 跟随软键盘、浏览器工具栏与横竖屏变化。触摸设备打开面板时不会主动弹出软键盘。
+- 触摸端按钮和行操作具有移动端点击尺寸，输入字号防止 iOS 自动缩放；所有内部滚动区隐藏滚动条，但仍保留触摸、滚轮和键盘滚动能力。

package/resources/skill/references/checkout.md

@@ -0,0 +1,140 @@
+---
+read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manifest 时 · 处理 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。
+
+## 命令
+
+```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>
+```
+
+`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"
+    }
+  }
+}
+```
+
+`server` 必须和当前连接一致。`local_path`、`base_path` 必须是项目内相对路径。manifest、worktree `.base`
+和冲突目录必须 gitignore；不要手工伪造版本或哈希。
+
+## Commit 流程
+
+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 不一致时不得推进基线。
+
+本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
+
+单个 commit 成功不自动完成 worklog 项。只有整个事项统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行 `draftgo work complete <编号> --note "<完成结果>"`。任何检查失败、409/412 或交付失败都不得标记为完成。
+
+## 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 verify`，再执行 `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/data.md

@@ -0,0 +1,49 @@
+---
+read_when: 动态数据建模、权限、筛选或记录读写
+---
+
+# 动态数据
+
+元数据定义类型、字段和访问规则，记录保存业务数据。两者使用结构化 API，不 checkout。先用 `draftgo api search "db meta"` 或记录相关关键词搜索能力，再 `draftgo api describe <operation_id>` 和 `draftgo api call <operation_id> --input request.json`；通用调用与缓存规则见 `mcp.md`。
+
+## 建模与权限
+
+- 先确定字段、关系和访问规则，再绑定页面。元数据按 type 读取，修改和删除使用元数据 ID；创建后 type 不可修改。
+- 字段通过 schema.properties 定义，按需求选择 type、required、default、searchable；不复制整份静态 schema 替代实时契约。
+- 当前权限使用 public、authenticated、roles 配置 CRUD 级别，角色项引用实际 role_id。公开仅允许读取，且必须明确 public_fields；writable_fields 约束可写字段。授权由服务端执行，页面显隐不替代授权。
+- 保存前读取元数据 version，更新和删除携带 expected_version。记录所有者在 API 中为 owner_user_id，不凭客户端提供的 ID 授权。
+- 保存后回读规范化的类型和权限。契约与响应不一致时报告具体差异，不混用旧权限模型。
+
+## 记录与并发
+
+页面使用 window.parent.App，管理任务使用 CLI 实时 operation。以下是页面操作模式，类型、字段和记录来自当前任务；每个示例是独立操作，更新或删除前读取目标记录：
+
+```javascript
+const result = await App.get('db/order', {
+  page: 1, page_size: 20,
+  filters: ['amount:gte:100'], order_by: 'created_at', order: 'desc',
+});
+const { items, total } = result.data;
+await App.post('db/order', { data: { amount: 200 } });
+await App.put(`db/order/${record.id}`, {
+  version: record.version, data: { ...record.data, amount: 250 },
+});
+await App.delete(`db/order/${record.id}`, { version: record.version });
+await App.patch('db/order/batch', records.map(item => ({
+  id: item.id, version: item.version, data: { ...item.data, paid: true },
+})));
+```
+
+修改后使用响应或回读的新 version，不复用旧版本。409 时保留修改意图、重新读取并处理冲突，不盲目重放。批量最多 100 条，任一失败整批回滚。测试写入使用授权的隔离数据。
+
+## 筛选与关系
+
+- 数据列表默认分页，page_size 上限 100；按 total 继续读取，不假定省略分页返回全部。
+- filters 必须使用 field:operator:value，多个条件为 AND，不能省略操作符。
+- searchable 使用 false、exact、fuzzy、range 或 contains；按模式选择 eq/in、like、gt/gte/lt/lte 或 contains，支持范围以实例校验为准。
+- 业务 status 与记录顶层 status 分开理解。日期、检索和排序字段按当前类型及契约确认。
+- 关系设计按需读 `db-relations.md`。默认删除策略 restrict，级联由服务端在事务与权限约束中完成。
+
+## 验收
+
+类型、字段和权限回读正确；目标角色读写与拒绝场景符合需求；筛选、分页可用。涉及并发和批量时验证版本冲突及原子性。400 检查容器、版本、筛选和 schema，403 检查角色和所有者，409 检查版本。其他模块参数以各自 describe 为准。

package/resources/skill/references/db-relations.md

@@ -0,0 +1,29 @@
+---
+read_when: 配置动态数据关联、populate 或关联删除
+---
+
+# 数据关联
+
+先读取相关类型和引用字段，明确哪一侧保存 ID。关系定义保存到元数据，使用当前 expected_version。
+
+| 关系 | 定义位置与用途 |
+|---|---|
+| many-to-one | 持有目标 ID 的字段，ref.type 指向目标类型 |
+| many-to-many | 持有目标 ID 数组的 array 字段 |
+| one-to-many | 虚拟反向字段，ref.inverse_field 指向对方真实引用字段；仅用于 populate，不能作为记录数据写入 |
+
+ref 使用 type、relation、onDelete，反向关系另需 inverse_field。具体字段类型和写入容器按实时契约确定。
+
+| onDelete | 行为 |
+|---|---|
+| restrict | 默认策略，有引用时拒绝删除 |
+| cascade | 删除引用目标的记录 |
+| set_null | 将引用字段置空 |
+| set_default | 使用字段自身的 default，必须定义该默认值 |
+| detach | 从多对多数组中移除目标 ID |
+
+策略放在实际持有引用的字段上。旧 no_action 规范化为 restrict，不代表忽略引用检查。级联继承调用者权限并在事务中执行，不在前端连续 DELETE 模拟。
+
+页面通过 App.get 的 populate 参数请求必要关系。只展开当前页面需要的字段；展开数量、深度和返回结构以实例为准，不默认递归抓取全部关系。
+
+验收：关联按目标权限读取；反向字段只读；删除符合所选策略；缺权限或版本冲突时保持一致状态并显示服务端结果。

package/resources/skill/references/delivery.md

@@ -0,0 +1,33 @@
+---
+read_when: 准备验证、提交、发布、交付或标记工作项完成时
+---
+
+# 交付验收
+
+先按资源类型选择唯一交付链，不把“本地验证通过”写成“已发布”。
+
+## 长正文
+
+```bash
+draftgo diff pages 42 --stat
+draftgo verify pages 42
+draftgo commit pages 42
+draftgo check --remote --output json
+```
+
+`nav`、`docs` 同理。先用 `--stat` 或 `--summary` 确认变更范围，只有需要审查正文时才展开完整 diff。`commit` 返回新版本与哈希后，再用远端检查确认基线一致。409/412、未解决冲突或远端状态不明时停止。
+
+## 结构化资源
+
+结构化资源按最新 describe 调用写 operation，再用 get/list operation 回读。
+
+## 统一收尾
+
+```bash
+draftgo verify
+draftgo work complete <ref> --note "<结果与证据>"
+```
+
+默认 `verify` 不启动浏览器。用户要求视觉修改或视觉验收时，才增加 `--url <url> --screenshot always`；需要 DOM 或交互验证时再用 `--ui always`。所有 commit、MCP 写入和回读都成功后才能 complete；失败项保持 active，并在 note 外记录可脱敏的 request ID。
+
+完成条件：本地检查通过，目标远端资源可回读，版本/哈希或结构化状态与预期一致，任务要求的运行或视觉证据齐全，且证据不含凭据。

package/resources/skill/references/development.md

@@ -0,0 +1,41 @@
+# 项目开发与恢复
+
+新系统、需求变化、任务恢复、UI 定位或多 Agent 协作时按需读取对应小节。
+
+## 设计与执行
+
+用户项目根目录 `Design/README.md` 是设计入口；Design 表达当前及未来的目标，worklog 表达实际任务状态。CLI 源码仓库的 Design 描述工具本身，不能复制为用户产品设计或开发阶段。
+
+新系统先根据用户描述形成最小产品概述和模块设计。模块使用编号文件夹，简单模块只需 README；复杂后拆分。记录流程、规则、验收条件，正向描述能力，不编写“不做什么”清单。已明确的未来能力可以保存，但不得扩大当前任务范围。Design 直接维护最新目标，不并列新旧稿。
+
+开始即 `draftgo work start "<事项>" --note "设计路径/需求编号；owner；范围和验收条件"`，保存完整日期引用。信息充分且已授权时继续执行，仅澄清影响产品结果的问题。功能变化同步相关设计；Bug 修复遵循正确设计；小修改不强制生成新文档。设计文件由宿主普通编辑工具维护。
+
+涉及数据时先确定字段、关系、权限和读写契约，再实现页面。正文走 checkout → diff → verify → commit；结构化写入使用实时 operation 并回读。结构化写入可能即时作用于实例，开发优先使用开发实例。验收按设计需求及实际写入结果执行，本地 verify 不证明全部业务已验证或已上线。
+
+## 上下文与恢复
+
+先读 Design 索引，再读相关模块、公共规则和领域 Reference，不加载全量文档或 Registry。具体编辑所需的完整正文和契约必须按需读取。
+
+恢复时使用 `draftgo work list --status active --limit 20 --output json`，必要时查询 waiting；结果有 `next_offset` 时用 `--offset` 继续。支持 `--date YYYY-MM-DD`。单项使用 `draftgo work show YYYY-MM-DD#N --output json`，读取设计引用、备注和目标资源当前状态，再 `work start-item` 恢复。
+
+进度或交接通过 `work start-item <ref> --note "已完成结果；阻塞；下一步；资源 ID"` 追加，等待外部条件使用 work wait。完成时 work complete 的备注包含版本、验证和必要回读证据。不要把完整正文、凭据或全部响应写进日志。complete 是状态更新，不会自动核实证据；Agent 必须先完成验证。
+
+## UI 定位与验收
+
+页面说明包括用途、路由、关键操作和加载/空数据/错误状态。独立 UI 稿只在视觉方向、复杂布局或用户要求时提供，实际产生资料才建立模块 `UI/`；说明目标稿、参考图或定位材料的用途，并保持目标稿与文字一致。
+
+已有页面直接定位实际页面、区域、按钮名称/功能及相对容器。用户描述“右上角那个按钮”时先读页面和组件；多个合理候选时只澄清关键目标。需要视觉辅助时使用实际页面截图标注候选，有 DOM 能力则对应真实元素，不凭坐标猜业务。截图不作为默认整页重建路径。
+
+用户要求视觉修改即包含检查该修改的渲染结果：环境可用时用 verify 的 --url 和 --screenshot always 检查并查看图片，交互验收按需用 --ui always；视口按任务选择。无法验证时报告范围，普通非视觉任务仍默认本地 verify。验收截图通过已登记的 .draftgo/artifacts/ 保存，不堆入 Design。
+
+## 多 Agent 与 Git
+
+宿主支持且任务适合并行时，主 Agent 按文件和实例资源分配唯一 owner，先稳定共享数据和权限契约，再并行独立模块。公共设计、导航、共享组件有明确 owner；只提交本任务目标，避免 auto-push 携带他人未完成资源。子 Agent 返回设计引用、资源、结果、证据和下一步，主 Agent 汇总验收。
+
+本地源码隔离使用原生 Git worktree；DraftGo worktree 是实例正文与基线的编辑区，checkout/commit/auto-push 均不是 Git 分支或提交。diff 依赖本机 Git。文档与源码可纳入 Git，凭据和 DraftGo worktree 保持忽略。
+
+CLI 命令锁不能覆盖 Agent 整轮编辑；不同目录的锁也不隔离同一远端资源。owner 约定贯穿任务全过程，同资源串行，冲突按正文工作树规则处理。真正独立实验使用独立开发实例。CLI 请求使用有界并发，不能把多个 Agent 等同于无限连接。
+
+## 旧 Story 迁移
+
+仅旧项目需要：检查 .draftgo/story.yaml，将仍有效的产品定位、模块目标和决策原因迁入 Design；与现有 Design 或最新用户要求冲突的内容先核实，不覆盖有效文档。历史进度留给 worklog，不转成设计流水账。迁移核对前保留原文件，核对后在 worklog 记录迁移结果并停止读取 Story；用户未要求时不删除原产品档案。新项目不创建 Story，不并行维护两套设计来源。