draftgo-cli 1.0.4

package/resources/skill/references/diagnostics.md

@@ -0,0 +1,50 @@
+---
+read_when: 运行失败、MCP/API 调用异常、远端状态不一致或需要查询运行日志时
+---
+
+# 运行诊断
+
+## 最短诊断链
+
+```bash
+draftgo status --output json
+draftgo mcp status
+draftgo mcp test
+draftgo map --type pages --summary --output json
+draftgo check --remote --output json
+```
+
+`draftgo status` 的 `connection.health` 报告 `healthy`、`unhealthy` 或 `not_configured`。只执行与故障层级有关的命令：连接失败看 `mcp test`；已知页面可用 `map --type pages --route <path>` 或 `--title <title>` 精确检查，未知资源先看 `map --summary`；checkout、哈希或版本异常看 `check --remote`。需要浏览时用 `--limit <1-100>`（默认 20）和单一类型的 `--cursor`，不运行默认全量 map。命令失败仍保留其非零退出码和脱敏输出。
+
+API 运行失败时，用原 operation 生成结构化诊断：
+
+```bash
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "AI run logs"
+```
+
+记录 `operation_id`、`status_code`、`server_code`、`request_id`，再通过实时日志 operation 查询对应 run。AI 调用按入口 Agent/模型和 request ID 定位；子 Agent 链路从 span 查，不把一次入口请求误算成多条主 run。页面运行时问题再读 `runtime.md`。
+
+## 权限诊断
+
+| 结果 | 最短定位 |
+|---|---|
+| 400 | 重新 `draftgo api describe <operation_id>`，核对当前 registry revision、`path/query/body/multipart` 容器和必填字段。不要靠修改字段名试探契约。 |
+| 401 | 运行 `draftgo status`；检查项目是否连接、当前用户 API Key 是否缺失、过期或已撤销。重新连接或轮换后再试一次，不把密钥放进输入、宿主配置或日志。 |
+| 403 | 从结构化错误读取 `error_code` 和 `permission`；核对 operation 所需权限、当前用户有效角色及 API Key 是否仍有效。页面显隐不是服务端授权证据。 |
+
+解释权限来源时先用实时契约，不从 UI 状态推测：
+
+```bash
+draftgo role list
+draftgo api search "effective permissions"
+draftgo api describe <explain_operation_id>
+draftgo api call <explain_operation_id> --input request.json --output json
+```
+
+按解释结果核对用户直接角色与用户组角色的并集、Role 中的精确 permission，以及用户、Role 和用户组状态。没有匹配来源时保持拒绝，不临时扩大权限来验证。
+
+不要在 issue、工作日志、命令参数或诊断文件中写 API Key、服务凭据、Authorization、完整请求头或上游服务地址。非幂等写入失败后先回读状态，不自动重试。
+
+完成条件：故障已定位到连接、契约、权限、资源版本或业务运行中的一层，并保留可关联的 request ID/run 证据；无法定位时明确缺少哪项服务端证据。

package/resources/skill/references/frontend.md

@@ -0,0 +1,158 @@
+---
+name: draftgo-frontend-rules
+description: DraftGo frontend page development rules.
+version: 2.0.0
+---
+
+# DraftGo 前端开发规范
+
+本文件只保留 DraftGo 前端特有的运行契约和操作边界。架构见 `architecture.md`，iframe、认证和路由见 `runtime.md` / `app-api.md`，动态 DB 见 `data.md`。根 `SKILL.md` 的交付与验收规则优先，不在此重复增加浏览器动作。
+
+## DraftGo Components
+
+开发 Page 前先查询当前实例的组件目录：
+
+```text
+draftgo components search <query> --output json
+draftgo components show <library/component> --output json
+```
+
+有合适组件时优先使用 `data-dg-use="library/component"`、`data-dg-instance`、`data-dg-prop-*` 和 `data-dg-slot`。个性化优先改 props、slots、CSS 变量和 Page 局部 class；高度个性化时使用 `draftgo components expand --page <id> --instance <name>`，展开后就是普通 HTML/CSS/JavaScript，不再跟随组件库升级。展开后的 Page 仍必须经过 `draftgo diff`、`draftgo verify`、`draftgo commit`。
+
+开发组件库组件使用 `draftgo components checkout <library/component>`，直接编辑统一目录中的 `component.html`、`component.css`、`component.js` 和 `component.json`，然后依次执行 `components diff`、`components verify`、`components commit`。`component.json` 同时保存组件元数据和 Props、Slots、Events 等契约，不另设 `contract.json`。`commit` 只保存草稿；只有用户明确要求上线时才执行 `components publish`。库管理和组件创建、复制、删除、ZIP 导入导出均使用 `components libraries|create|copy|delete|import|export`，不要绕过 CLI 直接修改 DraftGo 数据库。
+
+### 页面身份与创建
+
+业务新页面默认是数据库中的完整 HTML 页面。先结合用户意图与 MCP 中的标题、route、用途和入口判断目标：
+
+- 用户指定页面、ID、已有 route，或现有页面职责明确一致：修改已有页面，确认唯一 ID 后 checkout。
+- 用户明确要求新增，或需求需要独立 route 且定向搜索无合适页面：通过实时 API 创建，取得 ID 后 checkout；完整 HTML 仍只走 checkout/commit。
+- “做一个功能页面”本身不等于新增，也不等于修改。证据足够时直接推进；多个候选会导致不同产品结果时再向用户澄清。
+
+搜索只需按标题、route 或用途逐步缩小范围。Checkout 应对应已确认的目标资源；新资源先创建并取得 ID。不要枚举无关页面。
+
+### 入口与导航
+
+- 新页面应从真实业务入口可达：公开页接导航、首页或相关操作；后台页接后台导航或管理菜单。隐藏页、回调页和链接直达页可按产品目的不绑定全局入口。
+- 多页面功能应让列表、详情、新建、编辑或管理流程互相走通。
+- 顶部导航先用 MCP 定位；需要完整 HTML 时 `draftgo checkout nav <id>`。新增业务入口优先局部调整现有导航，不破坏系统入口。
+- 导航按产品需要处理未登录、已登录、管理员及收起状态。普通用户不得看到管理入口。
+- 业务页面可有局部导航，但不要重复渲染外部全局导航。修改登录、设置、权限、用户、系统配置等内置页面前先核对影响和管理员能力。
+
+导航资源根元素使用：
+
+| 属性 | 含义 |
+|---|---|
+| `data-nav-position="top\|side"` | 必填位置 |
+| `data-nav-width="220px"` | 可选侧栏展开宽度，默认 260px |
+| `data-nav-collapsed-width="64px"` | 可选收起宽度，默认 72px |
+
+链接使用 `href` 与 `data-page-route`，避免用硬编码 `onclick` 模拟路由。
+
+### 首页特例
+
+`page_1_root.html` 若仍保留 DraftGo 默认文案、系统介绍和未定制品牌，可按用户目标改造；已经定制时只改需求范围。不要只凭文件名判断。
+
+## 体验结果
+
+任何前端页面的开发都应从用户体验出发。根据用户、核心任务、频率、数据规模和目标设备决定信息架构、组件、布局与视觉，不套固定页面骨架。
+
+- 按钮、表单、搜索、筛选、分页、提交和删除等已呈现交互应真实有效；主要流程必须闭环。
+- 异步流程覆盖相关加载、空数据、错误、成功、无权限和重试状态，不能因请求延迟或失败整页空白。
+- 数据型页面应让主要操作、分页、批量操作和保存控件在空、短、长列表下都可达；滚动边界明确，横向溢出不能隐藏核心操作。
+- 展示可维护内容时判断是否需要管理入口并复用同一份真实数据。列表、详情和编辑结构按任务差异设计，不复制大量同构工作台。
+- 按钮、标签、导航项、徽章等视觉整体内部使用 `white-space: nowrap`；整组可换行，但图标与文字不能被拆散。
+- 空态需有明确文案和下一步操作；已有固定主操作入口时使用紧凑说明和就近操作，自定义空态用 flex 对齐图标与文字。
+- 弹窗和抽屉把滚动放在内容区，避免双滚动条；flex 内容区使用 `min-height: 0` 保持滚动可用。
+- 官方页面和交付页面的选择器统一使用 DraftGo 内置 `draftgo/select`（多选使用 `draftgo/multi-select`）；不要使用原生 `<select>` 作为可见控件。组件运行时会把选项 slot 渲染为可访问的自绘面板，并处理键盘、焦点、禁用、空值和错误状态。
+- 运营表格可把排序和筛选放在对应表头的弹层中，保持数据列、条件和结果之间的直接关系；具体交互由数据规模与操作频率决定。
+
+### 响应式
+
+移动端是产品范围，不是固定验收门。公众页面、手机访问场景或已有响应式布局应处理窄屏；明确桌面工作台或仅改数据逻辑时不机械增加多端工作。
+
+在目标设备上保证：无整页横向溢出；阅读顺序和核心操作可达；表格/代码等宽内容有可访问滚动边界；弹窗完整可用；文字、导航和操作区不重叠。断点、堆叠和密度由真实内容及现有设计系统决定。
+
+### 动效
+
+动效仅用于解释层级、状态、空间关系或操作结果。可用 CSS、Web Animations、组件库或内置 GSAP，并为 `prefers-reduced-motion` 降级；不得阻塞操作、掩盖等待、引发布局跳动或成为唯一状态表达。
+
+GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外提供 `/assets/vendor/gsap/Draggable.min.js`，使用时显式 `gsap.registerPlugin(Draggable)`。不要假设存在其他 GSAP 插件。页面卸载时清理 timeline 和 Draggable 实例；同一属性不要同时由 CSS transition 与 GSAP 控制。
+
+## 运行形态
+
+- DraftGo 壳层位于 `frontend/`，使用 React 19 + Vite 8 + Tailwind CSS 4。只有用户明确要求修改壳层时才编辑该源码。
+- 业务页面与导航存储为数据库中的完整 HTML 文档，由壳层在 iframe 中运行。不得写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
+- 数据库 Page 使用普通 HTML + Tailwind CSS 4 + 原生 JavaScript；官方内置 Page 默认搭配 DraftGo 内置组件库，按需使用下方列出的本地资源。
+- 页面使用 `const App = window.parent?.App`。参数读取 `window.__DG_ROUTE_CONTEXT__.query`；页面跳转使用父窗口；登出调用 `await App.logout()`。
+
+## 实践建议
+
+- 提交完整 `<html><head><body>` 文档，静态资源使用下方本地路径。
+- DraftGo 是唯一官方 Page 组件库，使用 `draftgo/*` 组件名和 `data-dg-use` 引用。组件定义、props、slots、CSS 变量和 revision 以服务端实时组件目录为准；不要在 Skill 或页面中复制静态组件契约。第三方页面可以自带局部 HTML/CSS/JavaScript，但仍应遵守本地资源和无障碍规则。
+- 默认使用 `var(--dg-*)` 主题 token，并支持浅色/深色；用户输入或不可信 HTML 经 DOMPurify 净化。
+- 使用 `App.confirm()`、`App.toast()` 或对应反馈 API；关键状态不能只靠颜色或动画。
+- 建议调用全局 `App.formatDateTime(value, options)` 来适配系统时间显示；API 时间按 UTC 解析，页面不要直接按浏览器本地时区展示。
+- 初始渲染立即显示稳定的加载状态。
+- 页面文案使用页面级 `page_i18n`：静态 HTML 可用 `data-i18n-key` / `data-i18n-placeholder`，JavaScript 使用 `App.t(key, fallback, values)`；不要创建公共词条表或自定义 namespace。翻译输入必须保持原 messages key 集合和 ICU 占位符不变。
+- 选择器、Toast 等交互控件优先采用项目已有组件或统一封装，使视觉、状态和反馈与页面设计系统保持一致；提示就近呈现并说明下一步操作。
+- 外部资源优先使用项目内置文件；品牌图标的明确例外见资源章节。
+- 数据库 HTML 保持为可直接运行的页面文档，依赖和构建产物使用平台提供的本地资源。
+- 全局浮窗、客服、统计脚本或公共 Toast 统一使用 `frontend_global_*` 槽位和系统配置；组件库状态样式通过其公开 API 或局部作用域进行适配。
+
+## 组件与资源
+
+### 内置组件库
+
+| 名称 | 版本与形态 | 本地资源 |
+|---|---|---|
+| DraftGo 内置组件库 | 服务端实时目录；浏览器原生 Custom Elements/HTML 运行时 | `/assets/adapters/draftgo-components.js`、`/assets/adapters/draftgo-theme.css` |
+
+`/assets/adapters/draftgo-ui.js` 仅提供 `DraftGoUI.load('draftgo')` 的轻量入口和主题快照，不再加载第三方组件库。壳层会自动注入主题与组件运行时；页面通常直接声明 `data-dg-use="draftgo/<component>"`，复杂交互优先复用当前目录中的组件。
+
+确认、信息弹层和反馈优先使用 `App.confirm()`、`App.showModal()`、`App.showSuccess/showError/showInfo/showWarning()`，避免页面各自复制 Toast 或浏览器原生对话框。
+
+### 本地资源
+
+| 能力 | 路径 |
+|---|---|
+| Tailwind CSS 4.3.1 Browser Runtime | `/assets/tailwindcss.js` |
+| UI adapters | `/assets/adapters/draftgo-ui.js`、`/assets/adapters/draftgo-theme.css` |
+| DraftGo 内置组件 | `/assets/adapters/draftgo-components.js`、`/assets/adapters/draftgo-theme.css` |
+| Icons | `/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`、`/assets/icons/manifest.json` |
+| Provider brands | `/assets/providers/{provider}.svg`、`/assets/providers/provider-icons.js` |
+| Markdown/code | `/assets/vendor/marked/marked.min.js`、`/assets/vendor/highlightjs/highlight.min.js`、`/assets/vendor/highlightjs/styles/github.min.css` |
+| HTML security | `/assets/vendor/dompurify/purify.min.js` |
+| Chat runtime | 完整实现位于 `draftgo/chat` 的 `Definition.JS`，随组件按需解析与发布 |
+| Motion | `/assets/vendor/gsap/gsap.min.js`、`/assets/vendor/gsap/Draggable.min.js` |
+
+正文使用系统无衬线字体栈，代码使用系统等宽字体栈。通用图标优先使用项目内置 SVG，其他通用图标可使用 Font Awesome。模型/Provider 品牌标识使用本地 `/assets/providers/`；通过 `DraftGoProviderIcons.get(provider.kind)` 查找，未知或加载失败时回退通用图标，不访问 CDN。
+
+## 主题
+
+| Token | 用途 |
+|---|---|
+| `--dg-bg-base/page/surface` | 背景层级 |
+| `--dg-text-primary/secondary/muted` | 文字层级 |
+| `--dg-accent/hover/subtle` | 主题色 |
+| `--dg-border/success/error/warning` | 边框与状态 |
+
+壳层已把变量注入 `<head>`，直接使用即可。默认继承 `App.theme` 与 `App.colorScheme`。品牌或图表需要自主配色时，先定义页面局部变量并提供 light/dark 两套值；正文和交互文字保持 WCAG AA。不要把 hex/rgb 散落在组件样式中。
+
+## AI 页面 SDK
+
+DraftGo Page 的 AI 对话 UI 使用组件目录中的 `draftgo/chat`，不要手工加载 SDK 或自行实现流式状态：
+
+```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">
+</dg-chat>
+```
+
+完整 Chat 实现保存在 `draftgo/chat` 组件的 `Definition.JS`，与其他组件统一按需解析；同一 Page iframe 内相同 revision 与 hash 只编译一次。Page 使用 `<dg-chat data-dg-use="draftgo/chat">`，不手工加载第二套脚本。无 UI 的文本、图片或其他模型能力调用统一走服务端 AI Registry。完整组件边界见 `chat-sdk.md`，服务端 AI 能力见 `ai.md`。
+
+平台请求与反馈见 `app-api.md`；iframe 路由、认证与全局层见 `runtime.md`；动态 DB、筛选和关系见 `data.md`。DraftGo Page 的可序列化 Chat 配置以 `draftgo components show draftgo/chat` 返回的实时契约为准；函数型扩展只用于外部应用的直接 SDK 接入。

package/resources/skill/references/mcp.md

@@ -0,0 +1,110 @@
+---
+read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约时 · 判断宿主支持范围时
+---
+
+# DraftGo MCP
+
+根 `SKILL.md` 已负责任务路由。本文件只保留 MCP 的实时契约、调用优化和安全边界，不重复页面、前端或交付规则。
+
+## 最短流程
+
+```bash
+draftgo mcp status
+draftgo mcp test
+draftgo api search "<业务能力>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo capabilities search <query> --output json
+draftgo capabilities show <operation_id> --output json
+draftgo capabilities audit --output json
+
+# 领域快捷命令（仍使用实时 operation describe/cache）
+draftgo role list
+draftgo group list --input request.json
+draftgo api-key status
+```
+
+已配置且连接正常时无需每次运行前两条；只在初次配置、配置变化或 MCP 失败时执行。完成标准是 initialize、tools/list 和关键 tools/call 可用，目标 operation 的 schema 已确认且调用结果可回读。401/403 查用户 API Key 或权限，session/uninitialized 查会话与服务重启，5xx 记录 request ID 后查服务日志；不要用重复写入测试连接。
+
+## 边界
+
+MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigations、docs/articles 的完整正文走 `draftgo checkout` / `draftgo commit`；工具返回 `artifact` 或 `omitted` 时保留该语义，不要求模型展开长内容。
+
+不要增加聚合上下文工具或静态 API 路径表。按任务读取最少必要的 Reference，再调用精确工具：
+
+| 需要 | 工具 |
+|---|---|
+| 项目能力、registry 覆盖和 checkout 类型 | `draftgo_project_overview` |
+| 定位资源 | `draftgo_resource_search` / `draftgo_resource_list` |
+| 元数据或短片段 | `draftgo_resource_get_metadata` / `draftgo_resource_read_fragment` |
+| 定位 API operation | Registry `search`（兼容 `draftgo_api_search`） |
+| 读取 operation schema | Registry `describe`（兼容 `draftgo_api_describe`） |
+| 结构化读写 | Registry `invoke`（兼容 `draftgo_api_call`） |
+
+只在需要对应信息时调用工具，不把 `project_overview` 作为每个任务的固定前置步骤。独立资源或 operation 可并发调用；同一资源的依赖步骤保持顺序。非幂等写入失败后先读状态，不自动重试。
+
+## API 契约缓存
+
+动态 schema 不写入 Skill。Skill 只保存下面的缓存规则：
+
+1. operation 未知时才 search；已有精确 `operation_id` 时跳过 search。
+2. 第一次使用 operation 时 describe，检查 method、path、parameters、request body、responses、permission、risk、`destructive`、`idempotent`、`input_schema` 和 `response_policy`。
+3. 同一 server 的 operation 描述按 `registry_revision` 复用。CLI 将缓存写在私有 `.draftgo/api-contract-cache.json`，不把 schema 注入 Skill 或对话上下文。
+4. call 携带缓存的 `registry_revision`。服务返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次。危险 operation 自身契约变化或服务端明确报告 CLI/契约不兼容时停止调用，升级 CLI 后重新 describe 和确认；其他工具错误不触发自动重试。
+
+describe 缺少本次调用需要的 schema、权限、风险或响应契约时停止并报告，不猜字段、不拼路径、不绕过 MCP。多个 operation 仍可能匹配时继续缩小 search，而不是任选一个。
+
+## 调用形状
+
+```json
+{
+  "operation_id": "精确 operation_id",
+  "registry_revision": "describe 返回的 revision",
+  "path": {},
+  "query": {},
+  "body": null,
+  "multipart": {},
+  "confirm": false
+}
+```
+
+只传 operation schema 需要的容器。路径参数放 `path`，查询参数放 `query`，JSON 放 `body`，文件或表单字段放 `multipart`。不得传 tenant override、API Key、Authorization 或其他凭据。
+
+高风险 operation 仅在用户意图和影响范围明确时设置 `confirm=true`；不要拼 `X-Confirm-Token` 或调用旧 reauth 流程。按 describe 的 responses 与实际 `status_code` 解释结果，不对自定义 Route、OpenAI 兼容流等强套 `{code,data,message}`。`response_policy.checkout_required=true` 时改走 checkout/commit。
+
+## CLI 与宿主
+
+```bash
+draftgo mcp setup [target...]
+draftgo mcp status [target...]
+draftgo mcp test
+draftgo mcp serve
+```
+
+- `setup` 写项目级宿主配置，只替换 `draftgo` 条目。
+- `status` 检查配置与凭据泄漏风险。
+- `test` 建立独立新连接并验证关键工具；它不证明宿主持有的旧 session 仍有效。
+- `serve` 是 stdio bridge。远端 session 明确失效时重新 initialize 并重放当前请求一次；普通超时、服务错误和工具错误不重试。
+
+支持项目级 setup：Codex、Claude Code、Cursor、Gemini CLI、Kiro、GitHub Copilot。Windsurf 和 Antigravity 没有可靠项目级 MCP 配置，CLI 应明确提示不支持。
+
+宿主配置只运行：
+
+```json
+{"command":"draftgo","args":["mcp","serve"]}
+```
+
+Codex 使用 `[mcp_servers.draftgo]`；GitHub Copilot 使用 `servers` 且声明 `type="stdio"`；其他支持宿主使用各自 `mcpServers`。配置不得包含 API Key、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据命令。bridge 从当前项目 `.draftgo/config.json` 读取 server/API Key。
+
+`draftgo connect` 只保存并验证连接，不下载业务资源或创建本地镜像。MCP 不可用时运行 `draftgo mcp test` 收集证据。
+
+## 安全
+
+- stdio stdout 只输出 MCP JSON-RPC；日志写 stderr，且不得包含 API Key。
+- 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座结果。
+- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前脱敏 API Key 与 Authorization。
+- `.draftgo/config.json`、`.draftgo/api-contract-cache.json`、worktree 和 conflicts 都是私有运行时状态并应 gitignore。
+
+## 专用资源命令
+
+Agent 通过 components 子命令操作组件。当前这些命令封装底座固定组件 HTTP 协议，组件内容、props 和 slots 仍实时读取；不要声称所有 CLI 请求都经过 MCP。通用 api 命令以 Registry 为唯一契约来源。WORKFLOW_REQUIRED 表示操作未执行，只有匹配的专用 CLI 工作流可完成正文或文件传输。

package/resources/skill/references/methods.md

@@ -0,0 +1,143 @@
+---
+read_when: 不确定 DraftGo 任务应使用 API/MCP 还是 checkout；需要 AI、数据、内容、诊断或交付的最短正确命令链时
+---
+
+# 极简方法指南
+
+只使用本页列出的真实 CLI 命令。动态 operation、字段、权限和响应以当前服务器为准；不知道精确契约时统一执行：
+
+```bash
+draftgo api search "<能力或资源>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+已有准确 `operation_id` 且缓存 revision 未变化时可跳过 search；describe 不完整时停止，不猜字段、operation ID 或 URL。`request.json` 必须是 UTF-8 JSON object，并按 describe 使用 `path`、`query`、`body` 或 `multipart` 容器。
+
+所有 `--output json` 命令都将单一 UTF-8 JSON 写到 stdout，诊断写入 stderr。先选择摘要、精确筛选或分页，避免用终端截断处理大结果。
+
+## AI 能力
+
+适用场景：查询或管理 Agent、模型、供应商、路由、Skill、Prompt，或验证一次 AI 调用。
+
+```bash
+draftgo api search "<agent|model|provider|route>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "AI run logs"
+```
+
+关键约束与失败定位：AI 配置是结构化远端资源，不 checkout；只传 describe 允许的字段。不得把 API Key、Authorization、供应商 header 或上游地址写入文件和日志。401/403 查登录、实时 permission 和资源调用策略；503 查模型路由、适配器与凭据是否就绪。
+
+完成条件：写入后的目标 ID 可由 get/list operation 回读；任务涉及调用时，调用成功且 run 能按入口 Agent/模型或 request ID 定位。模块边界和验证规则再读 `ai.md`。
+
+## 知识库与记忆
+
+适用场景：知识库、文档、Chunk、检索/重建，以及 Agent 长期记忆配置。
+
+```bash
+draftgo api search "knowledge base"
+draftgo api search "agent memory"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+关键约束与失败定位：知识库保存可检索资料，记忆保存运行时提炼结果，不能互相替代。上传、检索、重建、权限和记忆字段均以 describe 为准；没有专用 CLI 子命令。检索为空时依次核对文档状态、索引/重建结果和调用权限。
+
+完成条件：目标资源可回读；任务涉及检索或记忆召回时，最小验证调用能返回预期范围的数据，且运行日志可关联。
+
+## 身份与权限
+
+CLI、MCP 与直接 HTTP API 使用同一个用户 API Key，并进入相同的基础 RBAC 和业务守卫。CLI 不创建服务主体或隐式管理员上下文，也不向 `invoke` 注入契约之外的授权字段。403 时检查目标 operation 的实时 `permission`、当前用户角色和资源所有者规则，不通过修改 ID 或请求字段反复试探。
+
+## 页面、导航与内容
+
+适用场景：修改已有 page/navigation/article 完整正文，或创建后继续编辑正文。
+
+```bash
+draftgo map --type pages --route /admin/channel-ops --output json
+draftgo checkout pages <id>
+draftgo diff pages <id> --stat
+draftgo verify pages <id>
+draftgo commit pages <id>
+```
+
+导航将 `pages` 换为 `nav`，文档文章换为 `docs`。`--route` 与 `--title` 均为精确匹配，同时给出时取交集；CLI 会先用资源搜索缩小候选，再在本地判定精确结果。只需确认范围、数量和 checkout 状态时使用 `map --summary`；必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用返回的 `--cursor <opaque>` 请求下一页。`map --summary` 不含 project overview、资源列表或 hash。`diff --stat` 显示文件与增删行数，`diff --summary` 显示资源、版本和变化概览；只有需要审查正文时才运行不带这两个参数的 `diff`。新资源先发现创建契约并取得 ID：
+
+```bash
+draftgo api search "create <page|navigation|article>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo checkout <pages|nav|docs> <id>
+```
+
+关键约束与失败定位：checkout 只处理已存在资源的完整正文，不负责创建。409/412 时停止提交，使用 `draftgo conflicts` 和 `draftgo conflict show <type> <id>` 检查保留的 base/local/remote；不要 force、覆盖或自动合并。
+
+完成条件：commit 返回新版本/哈希，随后 `draftgo check --remote --output json` 显示本地基线与远端一致。正文和冲突细节再读 `checkout.md`，页面运行规则再读 `frontend.md`。
+
+## 动态数据
+
+适用场景：管理 `db_meta` schema、权限、关系，或查询/写入动态 DB 记录。
+
+```bash
+draftgo api search "db meta"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo api search "dynamic db record"
+```
+
+关键约束与失败定位：schema 和记录都是结构化远端资源，不 checkout。创建或更新 schema 后先回读目标 `type`，再按实时记录 operation 做最小 CRUD。400 优先核对 searchable、filter 操作符和字段容器；403 核对 `db_meta` permission 与记录 owner；列表不完整先核对分页，不用超大 page size 假装全量。
+
+完成条件：schema 可按 `type` 回读，目标角色的最小 CRUD/筛选符合预期；批量写入还需验证失败时整批回滚。字段和关系规则再读 `data.md`。
+
+## 自定义服务
+
+需要额外业务逻辑时读 `services.md`：定位/创建服务 → 获取 SDK 与草稿 → 保存源码版本 → 验证和草稿试运行 → 按任务发布及回读。策略独立读取、按版本保存与预览。所有 operation 从实时 Registry 发现。当前 CLI 的源码/SDK workflow 传输尚未接通，先读 services.md 的能力边界；不能将接口可发现等同于开发闭环可执行。
+
+## MCP 与实时契约
+
+适用场景：首次连接、宿主配置变化、工具不可用，或不知道 operation/schema。
+
+```bash
+draftgo mcp status
+draftgo mcp test
+draftgo api search "<业务能力>"
+draftgo api describe <operation_id>
+```
+
+关键约束与失败定位：已配置且健康时不必每个任务重复 setup/status/test。宿主配置只运行 `draftgo mcp serve`，不得保存 API Key。401/403 查用户 API Key、角色和目标权限；session/uninitialized 重新建立连接；operation 不唯一时继续缩小 search；describe 缺字段、风险或响应契约时停止。
+
+完成条件：initialize、tools/list、关键 tools/call 可用，目标 operation schema 已确认且可回读一次无副作用结果。完整缓存、风险和 multipart 规则再读 `mcp.md`。
+
+## 运行诊断
+
+适用场景：连接失败、API 调用失败、checkout 状态异常，或需要定位 AI run。
+
+```bash
+draftgo mcp status
+draftgo mcp test
+draftgo map --type pages --summary --output json
+draftgo check --remote --output json
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+关键约束与失败定位：只运行与故障层级相关的命令。保留脱敏的 `operation_id`、`status_code`、`server_code`、`request_id`；非幂等写失败后先回读状态，不自动重试。连接问题看 mcp test，正文版本看 check/conflicts，AI 运行问题再 search 对应日志 operation。
+
+完成条件：故障被定位到连接、契约、权限、资源版本或业务运行中的一层，并有 request ID/run 等可关联证据。完整分流再读 `diagnostics.md`。
+
+## 交付验收
+
+适用场景：准备提交、发布、交付或关闭 worklog 项目。
+
+```bash
+draftgo verify
+draftgo check --remote --output json
+draftgo work complete <ref> --note "<结果与证据>"
+```
+
+正文资源在 complete 前还必须成功执行 `diff -> commit`；结构化资源必须 call 后回读。默认不启动浏览器，用户要求视觉修改或视觉验收时才使用 `draftgo verify --url <url> --screenshot always`，需要 DOM/交互时再加 `--ui always`。
+
+关键约束与失败定位：本地验证通过不等于已提交或已发布。任何 verify、commit、MCP 写入、回读或视觉验收失败时，工作项保持 active。
+
+完成条件：全部目标远端状态可回读，正文版本/哈希或结构化状态符合预期，任务要求的运行/视觉证据齐全且不含凭据，然后才 complete。

package/resources/skill/references/modules.md

@@ -0,0 +1,75 @@
+---
+read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
+---
+
+# DraftGo 模块地图
+
+## 可开发模块（开发者负责实现）
+
+| 模块 | 开发方式 | 入口 |
+|---|---|---|
+| 页面 | 数据库 HTML（`page.value.html`） | 已有页面由 MCP 定位后 `checkout pages` / `commit pages`；新页面先按实时 API 契约创建并取得 ID |
+| 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
+| 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
+| 文件资产 | 文件夹、文件元数据、绑定、下载、回收站和对象存储 | MCP 实时 API；文件字节不进入普通 tool result |
+| 自定义 Go 服务 | SDK、草稿、验证、试运行、独立策略与发布；按需读 `services.md` | MCP 实时契约与返回的专用传输工作流 |
+| AI 能力 | 配置模型、提示词、插件、知识库、记忆和智能体；DraftGo Page 对话使用 `draftgo/chat`；图片、Embedding、Rerank、TTS、ASR 和 Video 通过服务端 AI Registry 调用；见 `references/chat-sdk.md` 与 `references/ai.md` | MCP 实时 API；不创建本地镜像 |
+| 文档中心 | Markdown/HTML 系统文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
+| 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
+| 支付与余额 | 账单、支付、退款、余额和资金流水 | 管理任务用 MCP 实时 API；不要用动态 DB 重建金钱状态 |
+
+## 平台内置模块（开箱即用，不需实现）
+
+| 模块 | 能力 | 调用方式 |
+|---|---|---|
+| 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
+| 角色权限 | Role 权限模板、用户直接角色与用户组角色 | 页面可用 `App.permissions` 辅助显隐；服务端执行最终授权 |
+| 用户组 | 用户组成员与角色分配 | MCP 实时 API；CLI 提供 `group` 快捷命令 |
+| API Key | 当前用户的 System MCP 凭据 | CLI 提供 `api-key` 快捷命令；不把凭据写入请求文件或宿主配置 |
+| 通知公告 | 发布公告，支持类型/状态/分页 | MCP 实时 API |
+| 工单反馈 | 用户提交问题，支持类型/状态跟踪 | MCP 实时 API |
+| 备份恢复 | 完整/选择性备份，JSON/.dgbak 格式，支持 dry-run | MCP 实时 API |
+| 系统管理 | 系统配置 KV、存储健康、全局前端层、通知测试 | MCP 实时 API |
+
+`App.currentUser.role_code` 是展示投影，不是用户表中的可写字段。真正的资源/API 授权由服务端根据有效 Role、用户组角色、资源所有者规则和业务守卫决定。
+
+用户 API Key 只是一种用户认证方式；它始终代表当前用户，不能创建服务身份或绕过管理员边界。
+
+## 新模块权限接入检查表
+
+AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺少任一项都不能用页面显隐、角色名或调用来源补洞：
+
+- [ ] 在统一 Permission Catalog 注册每个 `resource:action`，不在模块内另建权限字符串或角色分支。
+- [ ] HTTP、MCP 和后台任务等所有实际入口复用同一授权路径。
+- [ ] 按 ID 操作先加载服务端真实资源；忽略客户端提交的 owner 或调用者替代值。
+- [ ] 保留最小拒绝证据：缺少权限、伪造 owner、越权访问他人资源。不要为同一规则复制一套测试框架。
+
+实现位置和具体 API 以目标 DraftGo 服务端仓库的现有 Permission Catalog 与 Authorizer 模式为准；本 Skill 不复制服务端动态 schema。
+
+## 模块选型决策
+
+```
+要存储业务数据？
+  → 轻量业务记录 → 动态 DB（db_meta 定义 schema）
+  → 强一致性领域 → 优先复用底座专用模块，确需额外逻辑时评估 Go 服务
+  → 仅需 KV → sys_config（category 自定义）
+
+要保存文件？
+  → 文件夹、上传、下载、回收站或业务绑定 → 文件资产模块；不要把文件字节塞进动态 DB
+
+要做余额、支付或退款？
+  → 走 payment/wallet 的 MCP 实时契约，不自行实现账本或扣费一致性
+
+要调用 AI？
+  → DraftGo Page 聊天/问答 UI → AI 能力 + `draftgo/chat`（组件定义按需解析，自动隔离 thread/session）
+  → 无 UI 的文本或媒体调用 → AI 能力 + MCP Registry operation（先 search/describe，再 call）
+  → 图片生成 → AI 能力的 image capability 与当前 Provider readiness
+  → Responses、Embedding、Rerank、TTS、ASR 或 Video → 模型 capability 与 provider readiness；先确认模型的 canonical capability 和 transport
+  → 需要工具、知识、记忆、结构化输出或多模态 → 先读 references/ai.md，再通过实时 Registry 确认当前契约
+
+要展示内容文档？
+  → 文档中心（Markdown + 分类树）
+
+要做后台管理页？
+  → 业务页面 + 动态 DB + 角色权限
+```

package/resources/skill/references/runtime.md

@@ -0,0 +1,109 @@
+---
+read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问题时
+---
+
+# 运行时机制（Runtime）
+
+## 壳层启动流程
+
+1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
+2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
+3. `loadSetupStatus()` — 检查系统是否已初始化
+4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
+
+---
+
+## iframe 注入机制
+
+壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
+
+- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数），冻结对象
+- `window.__DG_QUERY__` — `routeContext.query` 快捷方式
+- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
+- 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
+- 组件库主题适配器；Tailwind、FontAwesome、GSAP 等其他本地资源由页面按需加载
+
+页面以 `iframe.srcdoc` 渲染，**不是独立 URL**，因此：
+- `window.location` 指向壳层地址，**不可用于读取路由参数**
+- `window.parent.App` 是壳层暴露的能力对象
+- `window.location.href = '/path'` 只跳 iframe 自身！导航必须用 `window.parent.location.href`
+- 登出必须调用 `await window.parent.App.logout()`；它会请求服务端登出、清理认证状态、触发 `dg:auth-changed`，并跳转系统配置的登录页
+
+---
+
+## App 对象来源
+
+壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
+
+`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
+
+完整 API 见 `references/app-api.md`
+
+---
+
+## Token 存储
+
+| key | 说明 |
+|---|---|
+| `localStorage.dg_access_token` | 访问 token |
+| `localStorage.dg_refresh_token` | 刷新 token |
+
+登录后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。  
+401 时壳层自动用 refresh token 刷新，无需页面处理。
+
+---
+
+## URL 参数读取（标准三阶回落）
+
+```javascript
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__
+  || window.__DG_GET_ROUTE_CONTEXT__?.()
+  || window.parent?.App?.getCurrentRouteContext?.()
+  || { query: {} };
+const query = routeContext.query || {};
+
+// 路由 /orders?orderId=42
+const orderId = query.orderId;  // "42"
+```
+
+**禁止**：`new URLSearchParams(window.location.search)` / 直接读 `window.location.search`
+
+---
+
+## 全局事件
+
+| 事件名 | 触发时机 |
+|---|---|
+| `dg:auth-ready` | token 验证完成（成功或失败） |
+| `dg:auth-changed` | token 变更（登录/登出） |
+
+监听方式：`window.parent.addEventListener('dg:auth-ready', handler)`
+
+---
+
+## 前端全局层
+
+全局浮窗、客服入口、统计脚本等属于全局层，不属于单个业务页面。
+
+存储：`sys_config.category = frontend_global`
+
+固定槽位覆盖总开关与安全模式、壳层 head/body/CSS/JS、iframe head、全局挂件、Toast 和滚动条配置。不要凭静态文档猜测全部键名或枚举；修改前通过 MCP 查询当前 `system_config` 契约与目标键。
+
+规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
+
+### 修改方法
+
+system_config 是结构化远端资源。未知 operation 才通过 MCP `draftgo_api_search` 定位；首次使用或
+registry revision 变化时 `draftgo_api_describe`，再用 `draftgo_api_call` 读取并更新目标键；不要 checkout
+或维护本地索引。
+
+前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
+`value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。
+
+页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
+`错误 Toast 时长(s) = 4.5` 对应 `frontend_global_toast_duration_error.config_value = 4500`。
+
+## 认证与权限边界
+
+页面会话使用访问 token；CLI 与 System MCP 使用当前用户的 API Key。两者都按服务端 Role、用户组角色、资源所有者规则和业务守卫授权。页面中的 `App.permissions` 只适合辅助显隐，不能替代服务端检查；未知权限要求始终读取实时 operation describe。CLI 不创建、导出或伪造服务身份，也不附加契约之外的授权字段。