draftgo-cli 4.0.24 → 4.0.26

package/README.md

@@ -1,18 +1,18 @@
 # DraftGo CLI 4
 
-面向 AI 编码工具的 DraftGo 工作台 CLI。它负责 Skill 安装、项目连接、MCP 发现、长正文 checkout/commit、自定义服务草稿、统一本地验收和 worklog 记录。
+面向 AI 编码工具的 DraftGo CLI。它负责 Skill 安装、项目连接、System MCP 发现、长正文 checkout/commit、组件开发、统一本地验收和 worklog 记录。
 
 ## 核心规则
 
 - 根 Skill 自动加载；Agent 只读取当前任务需要的 Reference。
-- pages、navigations、docs/articles 和 custom services 的完整正文使用 `checkout`、worktree、`diff`、`commit`；结构化资源使用 MCP/API。
+- pages、navigations 和 docs/articles 的完整正文使用 `checkout`、worktree、`diff`、`commit`；结构化资源使用 MCP/API。
 - MCP schema 是服务端实时契约。已知 operation 优先使用项目私有缓存；首次使用或 `registry_revision` 变化时 describe。schema 不写入 Skill 或聊天上下文。
 - 不同资源、operation 和 owner 的工作全部并发；同一资源的依赖步骤保持串行。
 - 每个任务开始记录到 `.draftgo/worklog.md`，验证和交付成功后再标记完成。
 - 已知页面使用 `draftgo map --type pages --route <path>` 或 `--title <title>` 精确定位；只需范围和状态时使用 `--summary`，浏览列表时使用 `--limit`（默认 20）/`--cursor`，不默认全量 map。
 - `--output json` 的 stdout 只包含 UTF-8 JSON；诊断和进度写入 stderr。大变更先用 `draftgo diff --stat` 或 `--summary`。
 
-跨板块任务先看[极简方法指南](resources/skill/references/methods.md)：它按 AIHub、知识库/记忆、页面/内容、动态数据、自定义服务、MCP、运行诊断和交付验收给出“适用场景 + 最短正确命令链 + 失败定位 + 完成条件”。动态 operation 不写死；未知契约统一用 `draftgo api search`、`draftgo api describe`、`draftgo api call` 实时发现。
+跨板块任务先看[极简方法指南](resources/skill/references/methods.md)：它按 AI 能力、知识库/记忆、页面/内容、动态数据、MCP、运行诊断和交付验收给出“适用场景 + 最短正确命令链 + 失败定位 + 完成条件”。动态 operation 不写死；未知契约统一用 `draftgo api search`、`draftgo api describe`、`draftgo api call` 实时发现。
 
 ## 验收策略
 
@@ -48,7 +48,7 @@ draftgo mcp setup
 draftgo mcp test
 ```
 
-`connect` 会验证当前用户的 DraftGo API Key、MCP initialize、tools/list 和关键工具调用，然后把连接写入项目私有的 `.draftgo/config.json`。宿主 MCP 配置只包含 `draftgo mcp serve`，不会保存 API Key。需要开发 space 资源时增加 `--scope-type space --space-id <id>`；平台组件和系统配置仍按 operation 契约使用 platform 上下文。
+`connect` 会验证当前用户的 DraftGo API Key、MCP initialize、tools/list、Registry search/describe，并通过 `api_call` 读取脱敏的当前 API Key 状态，然后才把连接写入项目私有的 `.draftgo/config.json`。该探测固定为无参数、低风险、非破坏的 GET，不创建或修改业务数据。宿主 MCP 配置只包含 `draftgo mcp serve`，不会保存 API Key。API Key 只代表真实用户，CLI 不附加契约之外的授权字段。
 
 本地底座：
 
@@ -73,14 +73,16 @@ draftgo list-targets
 draftgo connect [target...]
 ```
 
-`draftgo status` 会通过只读 MCP/API 诊断显示服务连接健康状态、服务版本和当前用户 API Key 的 `platform`/`space` 上下文；`--output json` 适合读取 `connection.health`、`workspace_id` 与 `space_id`。
+`draftgo status` 会通过只读 MCP 诊断显示服务连接健康状态、服务版本和 Registry revision；`--output json` 适合读取 `connection.health` 与 `connection.registry_revision`。
+
+`draftgo update` 和 `draftgo update all` 只刷新项目中已经安装的 DraftGo Skill，不会因为检测到 `.cursor`、`AGENTS.md` 等工具痕迹而新增配置。显式指定 target 时（例如 `draftgo update cursor`），如果该 Skill 尚未安装，会按你的明确请求直接安装并更新它；首次接入也可以使用 `draftgo init <target>`。
 
 ### 发现与正文
 
 ```text
-draftgo map [--type pages|nav|docs|custom-services] [--route <path>] [--title <title>] [--summary] [--limit <1-100>] [--cursor <opaque>] [--output json]
-draftgo checkout <pages|nav|docs|custom-services> <id...> [--force]
-draftgo check [custom-services <id...>] [--remote]
+draftgo map [--type pages|nav|docs] [--route <path>] [--title <title>] [--summary] [--limit <1-100>] [--cursor <opaque>] [--output json]
+draftgo checkout <pages|nav|docs> <id...> [--force]
+draftgo check [--remote]
 draftgo verify [<type> <id...>] [visual flags]
 draftgo diff <type> <id> [--stat|--summary] [--output json]
 draftgo commit <type> <id...>
@@ -118,26 +120,14 @@ draftgo components export <library> --file <archive.zip>
 
 `search` 和 `show` 始终读取当前 DraftGo 实例的组件目录，AI 不得按名称猜写 props/slots。Page 以真实根标签和 `data-dg-use="library/component"` 保存活引用，发布新 revision 后刷新自动升级。高度个性化时先 checkout Page，再用 `expand` 固化当前 props、slots、组件/库 CSS、公共资产和 mount 初始化；展开实例变成普通 HTML/CSS/JavaScript，不再随组件升级，仍需经过 `diff -> verify -> commit`。
 
-### Custom service
-
-最短开发闭环：
-
-```bash
-# 先用 MCP 定位或创建服务并取得 ID
-draftgo checkout custom-services <id...>
-draftgo diff custom-services <id> --stat
-draftgo commit custom-services <id...>
-draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
-```
+最终版服务端内置 `DraftGo` 组件库（slug 为 `draftgo`），当前包含 47 个组件，目录以实例实时返回为准。常用组件包括 `button`、`input`、`select`、`multi-select`、`switch`、`dialog`、`drawer`、`data-filter-bar`、`data-table`、`data-list`、`pagination`、`date-picker`、`number-input`、`file-upload`、`tabs`、`menu`、`popover`、`tooltip`、`empty-state`、`chat` 等。官方页面中的可见选择器必须使用 `draftgo/select` 或 `draftgo/multi-select`，不要写原生 `<select>`。
 
-每个 worktree 只有 `service.go` 与 `service.json` 是用户内容；Route/Event/Scheduled handler 仅由 `Register` 自动发现。CLI 另生成带 `DO NOT EDIT` 标记的 `go.mod/go.sum`、本地编译入口和 SDK 副本，供 gopls、`go build` 使用；它们会在 checkout 和 commit 时重建，且永不进入 diff、hash、归档、冲突材料或云端。第三方依赖只在源码顶部用 `//draftgo:require module@version` 固定。旧四文件 worktree 不受支持，请删除后用当前 CLI 重新 checkout。
-
-`commit custom-services` 会自动完成提交、验证和发布，并输出明确的 published 提示；`validate`、`test`、`publish` 仍可作为单独的兼容入口。`test` 只运行 cloud draft，不调用线上版本；发布后如需再试运行，先修改并提交形成新草稿。默认拒绝外部副作用；外部调用用 `--side-effect-policy mock` 模拟，只有明确需要真实副作用时才组合 `--side-effect-policy live --test-write`。数据库等写操作也必须显式加 `--test-write`。
-
-`--source` 支持 `draft`（默认）、`auto`、`published`。Selector 支持 `route:METHOD:/path`、`event:name`、`scheduled:name` 或 handler 名；`--input`、`--headers`、`--user` 都读取 UTF-8 JSON object。普通 SDK 调用继承已验证的 `platform` 或 `space` 上下文；自定义服务可对单次操作显式使用 `ctx.Admin.*`，该次调用按系统内置 `*:*:all` 全权限执行、进入审计且不会泄漏到后续调用。余额扣款、权益、支付和订阅使用 `ctx.Billing` / `ctx.Admin.Billing`，精确签名查看 checkout 后只读的 `.draftgo-sdk/billing.go`。完整字段与规则见[自定义服务方法指南](resources/skill/references/custom-services.md)。
+Page Runtime 的共享资源由最终版 `draftgo` 本地提供：`/assets/adapters/draftgo-components.js`、`/assets/adapters/draftgo-theme.css`、`/assets/tailwindcss.js`、`/assets/icons/`、`/assets/fontawesome/`、`/assets/vendor/{dompurify,marked,highlightjs}/`、`/assets/vendor/gsap/{gsap.min.js,Draggable.min.js}`。`draftgo/chat` 的完整实现直接存放在组件 `Definition.JS`，与其他组件走同一发布和按需解析流程，不存在独立 Chat SDK 静态文件。模型供应商品牌图标位于 `/assets/providers/`，通过 `DraftGoProviderIcons.get(kind)` 查找，未知供应商回退通用图标；不要引用 CDN。历史第三方组件资源不属于最终版契约。
 
 ### MCP/API
 
+`api search` 和 `capabilities list/search` 默认 20 条，支持 `--module`、`--method`、`--limit`、`--cursor`。保留 `next_cursor`，需要更多时继续读取；只有显式 `capabilities audit` 才遍历全部能力。describe 保留完整契约，分页不裁剪接口能力。
+
 ```text
 draftgo mcp setup [target...]
 draftgo mcp status [target...]
@@ -148,31 +138,26 @@ draftgo api search <query>
 draftgo api describe <operation_id>
 draftgo api call <operation_id> --input <json-file>
 draftgo delete <operation_id> [id] [--params JSON]
-draftgo capabilities list [--module <name>] [--type <resource>] [--method <method>]
+draftgo capabilities list [--module <name>] [--type <module>] [--method <method>]
 draftgo capabilities search <query> [--risk <level>] [--permission <permission>]
 draftgo capabilities show <operation_id>
 draftgo capabilities audit --output json
 ```
 
-`api call` 对已缓存 operation 直接调用并携带 `registry_revision`。服务端返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次，危险 operation 自身契约变化时阻断调用并提示升级 CLI 后重新确认。调用输入必须是 UTF-8 JSON object；输出包含 HTTP status、服务端 code 和 request ID。
+`capabilities --type` 是 `--module` 的简写，用于 Registry module 筛选；它不表示 organization、space、scope 或 `resource_type`。
+
+`api call` 对已缓存 operation 直接调用并携带 `registry_revision`。服务端返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次，危险 operation 自身契约变化时阻断调用并提示升级 CLI 后重新确认。调用输入必须是 UTF-8 JSON object；输出包含 HTTP status、服务端 code 和 request ID。System MCP 是动态 API 的唯一契约来源，CLI 不固化业务 URL 或请求结构。
 
-权限快捷命令：
+RBAC 与 API Key 快捷命令：
 
 ```bash
 draftgo role list
-draftgo space list
-draftgo space members list --input request.json
 draftgo group members add --input request.json
-draftgo grant create --input request.json
 draftgo api-key status
 draftgo api-key rotate
-draftgo data-range list
 ```
 
-`role` 管理无作用域的 Role 模板；授权使用 `grant` 创建带 `platform` 或 `space` 范围的 AccessGrant。工作区成员关系不直接授予权限。资源归属由服务端持久化 ResourceOwnership 决定，DB 的 DataRange
-只在该范围内应用 `none`、`owner` 或 `all` 记录策略。交互式 CLI、MCP 和普通 HTTP API 均使用当前用户的
-API Key，并始终按该用户的 AccessGrant 授权；API Key 不能创建或伪造服务身份。CI、定时任务和共享服务等
-无人值守自动化由运行时使用 system 身份；定时和事件处理器没有调用者，必须在代码中显式使用 `ctx.Admin.*`，不创建服务主体 AccessGrant，也不复用个人 API Key。
+`role` 管理 Role 权限模板，`group` 管理用户组及其角色。交互式 CLI、MCP 和普通 HTTP API 均使用当前用户的 API Key，并按同一基础 RBAC 与业务守卫授权；API Key 不能创建或伪造服务身份。未知能力始终通过 `api search/describe/call` 使用实时 Registry，不依赖固化权限表。
 
 ### 交付与记录
 
@@ -182,6 +167,7 @@ draftgo auto-push [<type> <id...>]
 draftgo work start <item>
 draftgo work add <item>
 draftgo work start-item <number|date#number>
+draftgo work wait <number|date#number> [--note <reason>]
 draftgo work complete <number|date#number> [--note <evidence>]
 draftgo work show|list
 draftgo clean [--dry-run|--yes]
@@ -204,7 +190,7 @@ draftgo clean [--dry-run|--yes]
 // draftgo verify、commit 已通过
 ```
 
-空状态表示待开发，`●` 表示开发中，`√` 表示开发完成。任务开始就写入记录；验证、冲突或交付失败时不能标记为完成。
+`●` 表示进行中，`?` 表示待确认，`√` 表示已完成。旧空标记仍可读取，对外显示待确认；不自动重写历史。`work add` 新增待确认事项，`work wait` 暂停事项，`work start-item` 恢复。任务相关的验证、冲突或交付失败不能标记完成。
 
 ## 运行时目录
 
@@ -223,7 +209,7 @@ draftgo clean [--dry-run|--yes]
 
 ## Skill 与 Reference
 
-Skill 只放稳定的领域知识、项目边界和操作规则；动态 operation schema 由 MCP 提供并缓存在项目运行时。Reference 不拆成更小文件，保留按任务路由、前端运行时、安全、自定义服务、checkout 和 MCP 契约所需的完整上下文，避免过度拆分损失效果。
+Skill 只放稳定的领域知识、项目边界和操作规则；动态 operation schema 由 MCP 提供并缓存在项目运行时。Reference 不拆成更小文件，保留按任务路由、前端运行时、安全、checkout 和 MCP 契约所需的完整上下文，避免过度拆分损失效果。
 
 支持的 Skill target 包括 Claude Code、Cursor、Windsurf、Antigravity、Kiro、GitHub Copilot、Codex CLI、Gemini CLI 和 Pi。Pi 的项目级 Skill 安装到 `.agents/skills/draftgo/`，可被 Pi 按 Agent Skills 标准自动发现。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "4.0.24",
+  "version": "4.0.26",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro, Pi).",
   "bin": {
     "draftgo": "bin/draftgo.js"
@@ -45,16 +45,14 @@
   "scripts": {
     "lint": "node scripts/check-syntax.js",
     "validate:skill": "node scripts/validate-skill.js",
-    "sync:custom-service-sdk": "node scripts/sync-custom-service-sdk.js",
     "build:release": "node scripts/build-release.js",
     "verify:package": "node scripts/verify-package.js",
-    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:components && npm run test:capabilities && npm run test:workflow && npm run test:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && npm run test:local && npm run test:e2e",
+    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:components && npm run test:capabilities && npm run test:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && npm run test:local && npm run test:e2e",
     "test:unit": "node tests/unit.js",
     "test:components": "node --test tests/components.test.js",
     "test:capabilities": "node --test tests/capabilities.test.js",
-    "test:workflow": "node tests/workflow.test.js",
     "test:worklog": "node tests/worklog.test.js",
-    "test:mcp": "node tests/mcp.test.js",
+    "test:mcp": "node --test tests/mcp.test.js",
     "test:worktree": "node tests/worktree.test.js",
     "test:integration": "node tests/integration.test.js",
     "test:local": "node tests/local-runtime.js",

package/resources/skill/SKILL.md

@@ -9,7 +9,7 @@ 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 与 custom services 的完整正文只能通过 `draftgo checkout`、worktree、`draftgo diff`、`draftgo verify` 和 `draftgo commit` 处理；MCP 只用于定位、元数据和结构化资源。不要把完整正文、响应快照、临时 Go 模块、SDK 副本或构建目录写入聊天上下文或手工归档。
+- 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`，绝不默认全量枚举。
 - `--output json` 的 stdout 是单一 UTF-8 JSON；诊断和进度走 stderr。不要依赖终端截断来控制上下文。
 - 正常交付只运行 `draftgo verify`。默认跳过 UI；只有用户明确要求视觉验收时才使用截图，要求交互或 DOM 验证时才使用 `--ui always`。
@@ -18,13 +18,17 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 ## 任务路由
 
+需求理解和编排由宿主 Agent 完成，CLI 不提供 build/run/deliver Agent。简单修改直接处理；跨页面与数据任务先确定字段、关系和接口，再实现页面，只读取涉及资源。需要用户决定时执行 `draftgo work wait <ref> --note "<原因>"`，继续时用 `work start-item`。
+
+能力搜索默认 20 条，保留 `next_cursor`，结果不足时继续 `--cursor`；`api search` 支持 `--module`、`--method`。摘要仅用于定位，精确 operation 的完整 schema 和完整正文按需读取。不把全量 audit 作为每次任务的起点。
+
 | 任务 | 先读 |
 |---|---|
 | 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md` |
 | pages/nav/docs 正文、版本或冲突 | `references/checkout.md` |
 | 动态 DB、筛选或关系 | `references/data.md`；复杂关系再读 `db-relations.md` |
-| AIHub、知识库、记忆、聊天或图片 | `references/aihub.md`；页面调用再读 `chat-sdk.md` |
-| 自定义服务、权限、外部调用、余额扣款或订阅 | `references/custom-services.md` |
+| 模型、提示词、插件、知识库、记忆、智能体或 AI 页面调用 | `references/ai.md`；页面调用再读 `chat-sdk.md` |
+| 角色、用户组、API Key 或其他结构化管理能力 | `references/mcp.md`；业务细节以实时 operation 为准 |
 | MCP 配置、API 契约或故障 | `references/mcp.md`；连接或调用失败时运行 `draftgo mcp test` |
 | 运行失败、日志或请求链路 | `references/diagnostics.md` |
 | 验证、发布或交付验收 | `references/delivery.md` |
@@ -47,9 +51,9 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 - 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；不同资源、operation 和 owner 不冲突的单元可以并发，不设置客户端并发上限；同一资源的依赖步骤保持串行。主 Agent 负责 owner 分配、汇总、验证、交付和 worklog 状态。
 - 用户 API Key 只保存在 `.draftgo/config.json`，不得进入宿主配置、命令参数、Skill、日志、manifest 或错误消息。宿主 MCP 配置只运行 `draftgo mcp serve`。
 - 页面优先使用可信本地资源；禁止境外 CDN。净化不可信 HTML，关键状态不能只靠颜色或动效表达。页面通过 `window.parent.App` 使用认证、权限、反馈和主题；详细规则见前端与运行时 Reference。
-- Route 普通自定义服务 SDK 调用继承真实调用者和服务归属；Event/Scheduled 没有调用者，普通 `ctx.xxx` 返回 403，必须显式使用 `ctx.Admin.*`。Admin RPC 使用 system actor_id=0，按 `*:*:all` 单次执行并进入审计，不创建服务主体 AccessGrant，也不会泄漏到后续调用。
+- API Key 始终代表真实用户；CLI 不创建服务身份，不注入额外授权上下文，也不把 session token 用于 System MCP。未知权限和业务守卫以实时 describe 与服务端响应为准。
 - `.draftgo/tmp/` 可清理；先运行 `draftgo clean --dry-run`，再在需要时使用 `--yes`。用户可查验的证据放入已注册的 `.draftgo/artifacts/`。
 
 ## 完成条件
 
-每个目标均有与其类型相符的证据：正文有 checkout、验证、commit 返回的版本/哈希及必要远端回读；结构化资源有 describe、写入结果和回读；自定义服务的 `commit` 会完成 validate/publish，按需补充 test。任何验证失败、409/412 或交付失败都不得标记为完成；任何 verify、写入、回读或要求的视觉验收失败时，工作项保持 active。
+每个目标均有与其类型相符的证据：正文有 checkout、验证、commit 返回的版本/哈希及必要远端回读；结构化资源有 describe、写入结果和回读。任何验证失败、409/412 或交付失败都不得标记为完成；任何 verify、写入、回读或要求的视觉验收失败时，工作项保持 active。

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "4.0.24",
+  "version": "4.0.26",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",
@@ -10,9 +10,8 @@
     "draftgo-development",
     "reference-routing",
     "worklog-tracking",
-    "custom-service-ai-sdk",
     "minimal-method-guides",
-    "aihub-knowledge-memory",
+    "ai-knowledge-memory",
     "mcp-bridge",
     "content-checkout-commit",
     "runtime-diagnostics",
@@ -22,8 +21,6 @@
     "skill-installation"
   ],
   "permissions": [
-    "workspace:read",
-    "workspace:write",
     "process:run",
     "network:explicit"
   ],

package/resources/skill/references/ai.md

@@ -0,0 +1,41 @@
+---
+read_when: 管理模型、提示词、插件、知识库、记忆或智能体时 · 调试 AI 调用与运行记录时
+---
+
+# DraftGo AI 能力
+
+## 模块边界
+
+最终版 AI 板块由模型、提示词、插件、知识库、长期记忆和智能体组成。它们都是结构化远端资源，使用实时 Registry Operation 管理，不 checkout、不生成本地镜像，也不通过动态 DB 重建。
+
+- 模型负责 Provider、逻辑模型、路由和统一调用网关。
+- 提示词负责版本化内容和发布状态。
+- 插件负责 Skill 与外部 MCP 扩展。
+- 知识库负责资料导入、切分、索引、检索和重建。
+- 长期记忆负责智能体运行过程中提炼和召回的记忆。
+- 智能体组合模型、提示词、插件、知识库与记忆。
+
+模块之间通过明确 ID 和服务端规则组合。不要在客户端复制模型路由、插件执行、知识检索、记忆写入或智能体编排逻辑。
+
+## 最短流程
+
+```bash
+draftgo api search "<model|prompt|plugin|knowledge|memory|agent>"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+已有精确 `operation_id` 时跳过 search。首次使用或 Registry revision 变化时 describe；输入只包含 `input_schema` 声明的 `path`、`query` 和 `body`。写入后使用对应 get/list Operation 回读目标 ID；任务涉及运行行为时，再调用运行 Operation 并按 run ID 或 request ID 查询日志。
+
+## 开发规则
+
+- Provider 密钥、上游 Authorization、API Key 和原始敏感响应不得进入 Skill、请求示例、日志或项目文件。
+- 权限、风险、幂等性、能力名和状态枚举全部以实时 describe 为准，不使用历史权限前缀或字段表。
+- 模型是否支持 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。
+
+## 完成条件
+
+结构化配置任务必须有 describe、写入结果和回读证据。调用任务还必须证明运行成功，并能通过 run ID 或 request ID 关联日志；知识任务需要最小检索验证；任何输出均不得泄露凭据。

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

@@ -67,57 +67,12 @@ const { patientId, visitId } = routeContext.query;
 |---|---|---|
 | `App.currentUser` | object \| null | 当前用户，未登录为 null |
 | `App.isAdmin` | boolean | 是否管理员 |
-| `App.permissions` | string[] | 当前用户有效 permission grant 的展示投影；仅用于页面显隐，不替代服务端授权 |
+| `App.permissions` | string[] | 当前用户有效权限的展示投影；仅用于页面显隐，不替代服务端授权 |
 | `App.isAuthenticated` | boolean | 是否已认证 |
 | `App.hasToken` | boolean | 是否有 token（含未验证） |
 | `App.config` | object | 系统配置 KV |
 | `App.theme` | `'light'` \| `'dark'` | 当前显示模式 |
 | `App.colorScheme` | string | 当前配色方案 |
-| `App.scopeContext` | object | null | 当前候选范围；`scope_type` 为 `platform` / `space` |
-| `App.availableSpaces` | object[] | 当前用户可选择的工作区与递归空间 |
-
-### 空间上下文
-
-空间业务请求使用运行时当前上下文。页面先显示加载状态，再等待有效空间；返回 `null` 时呈现紧凑的工作空间状态和重试入口，本轮不发送业务请求。
-
-```javascript
-function currentSpace() {
-  const scope = App.getScopeContext?.() || App.scopeContext;
-  return scope?.scope_type === 'space' && scope.space_id ? scope : null;
-}
-
-async function waitForSpace(timeout = 4000) {
-  if (currentSpace()) return currentSpace();
-  return new Promise(resolve => {
-    const host = window.parent;
-    const done = value => {
-      clearTimeout(timer);
-      host?.removeEventListener('dg:scope-changed', check);
-      host?.removeEventListener('dg:scope-spaces-changed', check);
-      resolve(value);
-    };
-    const check = () => { if (currentSpace()) done(currentSpace()); };
-    const timer = setTimeout(() => done(null), timeout);
-    host?.addEventListener('dg:scope-changed', check);
-    host?.addEventListener('dg:scope-spaces-changed', check);
-    check();
-  });
-}
-
-const scope = await waitForSpace();
-if (!scope) {
-  renderWorkspaceState();
-  return;
-}
-await App.get('business-items', { page: 1 });
-```
-
-平台管理接口按接口契约显式传入平台范围：
-
-```javascript
-const platformHeaders = { 'X-DraftGo-Scope-Type': 'platform' };
-await App.get('roles', {}, platformHeaders);
-```
 
 ## 主题
 
@@ -135,11 +90,8 @@ await App.logout();                 // 服务端登出、清理状态并跳转
 App.setAuthTokens({ access_token, refresh_token });  // 登录后写入 token
 App.reloadGlobalLayer();            // 重载全局层
 App.openGlobalWidget(name);         // 触发全局挂件打开
-App.getScopeContext();              // 读取当前作用域
-App.setScopeContext({ scope_type: 'space', space_id: '120' });
-App.clearScopeContext();             // 清除手工选择，恢复服务端默认
 App.t(key, fallback?, values?);      // 页面级国际化文本，values 保留 ICU 占位符
 App.formatDateTime(value, options?); // 按 system_timezone 格式化 API 返回的 UTC 时间
 ```
 
-Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话、图片和兼容门面的完整契约见 `references/chat-sdk.md`，Agent 能力见 `references/aihub.md`。
+Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话组件契约见 `references/chat-sdk.md`，其他 AI 能力见 `references/ai.md`。Chat 与其他 DraftGo 组件使用同一组件库交付，不存在独立 SDK 静态文件。

package/resources/skill/references/architecture.md

@@ -40,7 +40,7 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 |---|---|
 | 后端 | Go 1.26 · 标准库 `net/http` · `database/sql`（go-sql-driver/mysql）· MySQL · Redis |
 | 壳层前端 | React · Vite |
-| 数据库页面 | HTML 文档运行时 · Tailwind CSS 4 · Basecoat UI（默认）· Oat UI（可选）· Font Awesome · GSAP · 内置 SVG 图标库 |
+| 数据库页面 | HTML 文档运行时 · Tailwind CSS 4 · DraftGo 内置组件库 · Font Awesome · GSAP · 内置 SVG 与 Provider 图标 |
 | CLI | Node.js（draftgo-cli） |
 
 数据库页面以完整 HTML 文档运行，直接加载平台提供的本地资源；壳层源码按 React + Vite 工程构建。开发时按目标所属层使用上表对应技术栈。

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

@@ -1,10 +1,10 @@
 ---
-read_when: 页面需要 AI 对话 UI 时 · 使用 dg-chat 或 DraftGoChat 时 · 接入 Agent/OpenAI/Anthropic/custom transport 时
+read_when: DraftGo Page 需要 AI 对话组件时 · 开发或扩展 draftgo/chat 时
 ---
 
-# DraftGo Chat SDK
+# DraftGo Chat 组件
 
-DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。SDK 统一提供消息状态机、流解析、停止、重试和历史逻辑。
+DraftGo Page 统一使用组件目录中的 `draftgo/chat`。完整实现保存在组件 `Definition.JS`，负责原生 `<dg-chat>`、消息状态机、流解析、停止、重试和历史逻辑，并与 HTML、CSS、Props 和事件使用同一草稿与发布版本。Page 不复制实现，也不手写流式请求。
 
 ## 目录
 
@@ -16,40 +16,32 @@ DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。S
 - [扩展](#扩展)
 - [鉴权与安全](#鉴权与安全)
 
-## 最小接入
+## DraftGo Page 最小接入
 
-脚本不是壳层默认全局注入。使用 `<dg-chat>` 或兼容门面 `DraftGoAI` 前必须先加载：
+先从当前实例读取组件契约，不按本文猜测 Props：
 
-```html
-<script src="/assets/draftgo-chat.js"></script>
-<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
+```text
+draftgo components show draftgo/chat --output json
 ```
 
-`draftgo-agent` 默认请求 `/api/agents/{id}/chat`，并复用同源 DraftGo App 的 Bearer token 与刷新机制。
-
-需要 JavaScript 配置时：
+在 Page 中保存组件活引用；运行时仅在实际引用时返回完整组件，同页相同 revision 与 hash 只编译一次：
 
 ```html
-<div id="chat-host"></div>
-<script src="/assets/draftgo-chat.js"></script>
-<script>
-  const chat = DraftGoChat.create('#chat-host', {
-    protocol: 'draftgo-agent',
-    agentId: 'AGENT_ID',
-    surface: 'inline',
-    view: 'conversation',
-    stream: true,
-    features: {
-      attachments: true,
-      reasoning: true,
-      history: true,
-      artifacts: true
-    }
-  });
-</script>
+<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>
 ```
 
-新页面优先使用 `<dg-chat>` 或 `DraftGoChat.create()`。`DraftGoAI.chat()` 是同一脚本提供的旧代码兼容门面，内部创建隐藏 `<dg-chat>`，仅适合不需要对话 UI 的轻量文本调用。图片模式继续使用 `DraftGoAI.images()`。
+`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 密钥、路由和用量控制在服务端。
 
 ## 协议
 
@@ -71,11 +63,11 @@ DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。S
 
 这些 `/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` 等事件。配置 JSON 以 DraftGo 当前 `contracts/chat-sdk.schema.json` 为准；不要猜测字段或把函数、DOM、renderer、plugin、transport 写入 JSON。
+内置 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
@@ -97,7 +89,7 @@ DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。S
 | 配置 | 可选值 |
 |---|---|
 | `surface` | `inline`、`floating`、`drawer`、`fullscreen` |
-| `view` | `conversation`、`threads`、`compact`、`workspace` |
+| `view` | `conversation`、`threads`、`compact`、`canvas` |
 | `position` | `left`、`right` |
 | `theme` | `light`、`dark`；省略时跟随系统 |
 
@@ -109,7 +101,7 @@ DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。S
   "protocol": "draftgo-agent",
   "agentId": "AGENT_ID",
   "surface": "inline",
-  "view": "workspace",
+  "view": "canvas",
   "storageKey": "dg-chat:PAGE_KEY:INSTANCE_KEY",
   "features": {
     "reasoning": true,
@@ -148,7 +140,7 @@ chat.close();
 chat.toggle();
 ```
 
-全局 API：`DraftGoChat.create()`、`registerTransport()`、`registerRenderer()`、`registerComponent()`、`definePreset()`、`use()`。
+组件内部运行时保留 `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`。
 
@@ -204,10 +196,10 @@ chat.configure({ protocol: 'page-protocol' });
 - 后端始终负责 Agent 调用权限、模型白名单、附件能力和大小限制，前端开关不能越权。
 - Agent 协议响应不应包含 Agent 内部模型名。模型选择器只能读取 Agent 明确授权的 `/selectable-models` 目录。
 
-交付前确认：只加载一个完整版脚本；新页面以 `<dg-chat>` 为对话 UI；同页多实例隔离 `storageKey`；外部协议走服务端代理；页面离开时停止在途请求。
+交付前确认：DraftGo Page 使用 `draftgo/chat` 且不手工加载第二套脚本；同页多实例隔离 `storageKey`；外部协议走服务端代理；页面离开时停止在途请求。
 
 ## 移动端契约
 
-- `inline`、`floating`、`drawer`、`fullscreen` 四种 surface 均由 SDK 自适应窄屏；`threads`、`workspace` 和 Artifact 会按容器宽度自动收敛为单栏，不要复制 Shadow DOM 内部布局规则。
+- `inline`、`floating`、`drawer`、`fullscreen` 四种 surface 均由 SDK 自适应窄屏；`threads`、`canvas` 和 Artifact 会按容器宽度自动收敛为单栏，不要复制 Shadow DOM 内部布局规则。
 - SDK 使用 `VisualViewport` 和 `safe-area-inset-*` 跟随软键盘、浏览器工具栏与横竖屏变化。触摸设备打开面板时不会主动弹出软键盘。
 - 触摸端按钮和行操作具有移动端点击尺寸，输入字号防止 iOS 自动缩放；所有内部滚动区隐藏滚动条，但仍保留触摸、滚轮和键盘滚动能力。

package/resources/skill/references/checkout.md

@@ -16,9 +16,9 @@ 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 scope
+## Workflow 2.0 coverage
 
-The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_services`. A custom-service checkout contains exactly `service.go` and `service.json`, plus one complete `.base` directory. Runner-managed `go.mod/go.sum` never participate in diff or commit. `draftgo commit custom-services <id>` performs the complete delivery (`commit -> validate -> publish`) and prints an explicit published confirmation. Use `draftgo test custom-services <id>` for server Runner validation/execution; `draftgo publish custom-services <id>` remains as a direct compatibility entry point. DB Meta remains a live MCP/API resource and is never checked out.
+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.
 
@@ -34,7 +34,7 @@ The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_s
 | `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。
+db_meta、AI 配置、system_config、roles、users、doc_categories 和普通配置使用 MCP 实时 API，不 checkout。
 
 Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，不创建页面、导航或文档。新增资源先按 MCP 实时 API 契约创建并取得 ID；需要编辑完整正文时再 checkout。只需元数据或正文片段即可完成判断时，不必 checkout。
 
@@ -44,7 +44,7 @@ Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，
 draftgo checkout <pages|nav|docs> <id...>
 draftgo commit <pages|nav|docs> <id...>
 draftgo reconcile <pages|nav|docs> <id...>
-draftgo diff <pages|nav|docs|custom-services> <id> [--stat|--summary]
+draftgo diff <pages|nav|docs> <id> [--stat|--summary]
 draftgo conflicts
 draftgo conflict show <pages|nav|docs> <id>
 draftgo conflict resolve <pages|nav|docs> <id>

package/resources/skill/references/data.md

@@ -61,43 +61,6 @@ draftgo api search "dynamic db record"
 
 ---
 
-## 自定义服务内的 ctx.DB.Query
-
-Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
-
-```go
-result, err := ctx.DB.Query("order", sdk.QueryOptions{
-    Filters: map[string]any{"status": "paid"},
-    Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
-})
-items := result.Items
-```
-
-| 参数 | 说明 |
-|---|---|
-| `filters` | 字典形式结构化过滤；默认 `{field: value}` 是 `eq` 精确匹配 |
-| `Page` / `PageSize` | 分页参数；零值交由平台使用默认列表行为 |
-| `order_by` / `order` | 按 searchable 字段排序，`order` 为 `asc` / `desc` |
-
-⚠️ 返回结构为 `sdk.QueryResult{Items, Total, Page, PageSize}`。需要完整数据时必须按 `Total` 分页读取，不能用超大 `PageSize` 假装全量。
-
-普通用户调用时只读 `status=1` 数据；系统身份/管理员脚本可读全部状态数据，但仍受 db_meta permission 约束。不要把“拿不到禁用数据”和分页截断混在一起排查。
-
-`filters` 操作符示例：
-
-```go
-ctx.DB.Query("order", sdk.QueryOptions{Filters: map[string]any{
-    "status": "paid",
-    "customer_name": map[string]any{"op": "like", "value": "张"},
-    "amount": map[string]any{"op": "gte", "value": 100},
-    "id": map[string]any{"op": "in", "value": []int{1, 2, 3}},
-}})
-```
-
-字段必须在 db_meta schema 中标记 `searchable`，系统字段 `id/userid/created_at/updated_at` 可直接检索和排序。`status` 若作为业务字段检索，仍需在 schema 中显式声明。
-
----
-
 ## 关联关系（ref）
 
 关系只在需要时读取 `references/db-relations.md`。核心不变量：`many-to-one` 与 `many-to-many` 在真实持有引用 ID 的字段上配置 `ref` 和 `onDelete`；`one-to-many` 是用于 `populate` 的虚拟反向关系。级联继承当前用户权限并在同一事务中执行，不要在前端用多次 DELETE 模拟。
@@ -115,14 +78,6 @@ const res = await App.get(`db/order`, {
 });
 const { items, total } = res.data;
 
-// 非后台管理页面读取业务列表时，如果当前用户含 admin 角色，带 scope=mine
-// 这只影响 GET /api/db/{type} 列表，让管理员业务视角只看自己的 owner 数据
-const ownOrders = await App.get(`db/order`, {
-  page: 1,
-  page_size: 20,
-  scope: 'mine',
-});
-
 // 系统字段检索和排序（无需在 schema 中定义）
 const res = await App.get(`db/order`, {
   filters: ['created_at:gte:2024-01-01', 'userid:eq:123'],
@@ -161,7 +116,6 @@ await App.patch(`db/order/batch`, [
 - 多个 filters 为 AND
 - 字段未标 searchable 或操作符不匹配 → 后端返回 400
 - **系统字段**（`id` / `userid` / `created_at` / `updated_at`）无需在 schema 中声明，可直接使用
-- `scope=mine` 只对拥有 admin 角色的用户在 `GET /api/db/{type}` 列表请求中生效；非后台管理页面若当前用户是管理员，读取动态 DB 业务列表时应带该参数；后台管理页不要带，详情和写操作也不要带
 
 ---