draftgo-cli 3.0.56 → 4.0.22

package/resources/skill/references/mcp.md

@@ -4,62 +4,72 @@ read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约
 
 # DraftGo MCP
 
-> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明实时 MCP 的边界和调用顺序，不能替代页面、前端、运行时、安全或模块资料。
+根 `SKILL.md` 已负责任务路由。本文件只保留 MCP 的实时契约、调用优化和安全边界，不重复页面、前端或交付规则。
 
-## 边界
-
-DraftGo MCP 用于实时发现、结构化查询和普通 API 操作。完整 pages、navigations、docs/articles 正文不通过
-MCP tool result 或参数传输；需要全文时使用 `draftgo checkout`，提交时使用 `draftgo commit`。MCP 返回
-`artifact` / `omitted` 时保留该语义，不要尝试重新展开长内容。
-
-不要在 CLI 或 MCP 服务端增加聚合上下文工具。自然语言任务的语义筛选由已加载根 Skill 的 Agent 完成：先读取任务路由指定的最少必要 Reference，再调用下面的精确 MCP 工具，并根据结果逐步缩小范围。
-
-标准发现顺序：
+## 最短流程
 
-1. `draftgo_project_overview`
-2. `draftgo_resource_search` 或 `draftgo_resource_list`
-3. 按需调用 `draftgo_resource_get_metadata` 或 `draftgo_resource_read_fragment`
-4. 需要实时 API 契约时调用 `draftgo_api_search`、`draftgo_api_describe`
-5. 结构化资源读写使用 `draftgo_api_call`
+```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 space list
+draftgo grant create --input request.json
+draftgo data-range list
+draftgo api-key status
+
+# 领域快捷命令（仍使用实时 operation describe/cache）
+draftgo role list
+draftgo group list --input request.json
+draftgo grant list --input request.json
+draftgo api-key status
+```
 
-结构化资源包括 db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据。
-这些资源不 checkout，也不生成 `.draftgo/*/index.json` 镜像。
+已配置且连接正常时无需每次运行前两条；只在初次配置、配置变化或 MCP 失败时执行。完成标准是 initialize、tools/list 和关键 tools/call 可用，目标 operation 的 schema 已确认且调用结果可回读。401/403 查用户 API Key 或权限，session/uninitialized 查会话与服务重启，5xx 记录 request ID 后查服务日志；不要用重复写入测试连接。
 
-## API 发现与调用
+## 边界
 
-静态 API 路径表不是事实来源。每次调用都按 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 执行，不能从旧文档、经验或相似 operation 猜参数。
+MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigations、docs/articles、custom_services 的完整正文走 `draftgo checkout` / `draftgo commit`；工具返回 `artifact` 或 `omitted` 时保留该语义，不要求模型展开长内容。
 
-### 1. 搜索 operation
+不要增加聚合上下文工具或静态 API 路径表。按任务读取最少必要的 Reference，再调用精确工具：
 
-```json
-{
-  "query": "需要查找的能力或路径片段",
-  "module": "可选模块",
-  "resource_type": "可选资源类型",
-  "limit": 100,
-  "cursor": "下一页游标"
-}
-```
+| 需要 | 工具 |
+|---|---|
+| 项目能力、registry 覆盖和 checkout 类型 | `draftgo_project_overview` |
+| 定位资源 | `draftgo_resource_search` / `draftgo_resource_list` |
+| 元数据或短片段 | `draftgo_resource_get_metadata` / `draftgo_resource_read_fragment` |
+| 定位 API operation | `draftgo_api_search` |
+| 读取 operation schema | `draftgo_api_describe` |
+| 结构化读写 | `draftgo_api_call` |
 
-`query`、`module`、`resource_type` 可组合筛选。结果提供 `operation_id`、method、path、module、resource type、permission、risk、`destructive` 和 `idempotent`。需要完整候选集时持续读取 `next_cursor`，直到没有下一页；不要因首批搜索结果为空或同名 operation 较多就猜测端点。
+只在需要对应信息时调用工具，不把 `project_overview` 作为每个任务的固定前置步骤。独立资源或 operation 可并发调用；同一资源的依赖步骤保持顺序。非幂等写入失败后先读状态，不自动重试。
 
-动态 Go 自定义服务也在同一 registry：有效的 `app.Route` 会实时物化为实际 method 与 `/api/x/{slug}/{path}` operation，module 为 `scripts_dynamic`、resource type 为 `custom_scripts`。SDK、身份继承、精确匹配和运行限制仍以 `references/custom-services.md` 为准。
+## API 契约缓存
 
-### 2. 描述唯一 operation
+动态 schema 不写入 Skill。Skill 只保存下面的缓存规则：
 
-```json
-{ "operation_id": "search 返回的精确 operation_id" }
-```
+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 返回的 method、path、parameters、request body、responses、examples、permission、risk、`destructive`、`idempotent`、完整 `input_schema` 和 `response_policy`。路径参数放 `path`，查询参数放 `query`，JSON 请求体放 `body`，文件或表单字段放 `multipart`；只发送 schema 允许的字段。
+describe 缺少本次调用需要的 schema、权限、风险或响应契约时停止并报告，不猜字段、不拼路径、不绕过 MCP。多个 operation 仍可能匹配时继续缩小 search，而不是任选一个。
 
-describe 缺少与本次调用有关的参数、请求体、responses、permission、risk、`input_schema` 或 `response_policy` 时停止并报告契约不完整，不得自行补字段、改走猜测路径或绕过 MCP。若多个 operation 仍可能匹配，继续缩小搜索范围，而不是任选一个。
+动态 Go 自定义服务 Route 也在 registry 中：module 为 `scripts_dynamic`，resource type 为 `custom_scripts`。Route 的 SDK、身份和运行限制见 `custom-services.md`。
 
-### 3. 调用
+## 调用形状
 
 ```json
 {
   "operation_id": "精确 operation_id",
+  "registry_revision": "describe 返回的 revision",
   "path": {},
   "query": {},
   "body": null,
@@ -68,11 +78,11 @@ describe 缺少与本次调用有关的参数、请求体、responses、permissi
 }
 ```
 
-仅传需要的容器。`draftgo_api_call` 会按该 operation 的 `input_schema` 拒绝未知字段，并以当前 MCP principal 执行权限检查；不要传 tenant override、SAT、Authorization 或其他凭据。高风险 operation 只有在用户意图明确、影响范围已核对时才把 `confirm` 设为 `true`；`confirm` 是 MCP 的风险确认字段，不要自行拼接 `X-Confirm-Token` 或调用旧式 reauth 流程。
+只传 operation schema 需要的容器。路径参数放 `path`，查询参数放 `query`，JSON 放 `body`，文件或表单字段放 `multipart`。不得传 tenant override、API Key、Authorization 或其他凭据。
 
-按 describe 的 responses 与实际 `status_code` 解析结果。标准管理 API 通常使用 `{code, data, message}`，但 OpenAI 兼容流、模型列表和自定义 Route 等响应可不同；不得对所有 operation 强套统一信封。`response_policy.checkout_required=true` 或长正文资源的完整内容必须转用 `draftgo checkout` / `draftgo commit`，不能塞进 `body`、`multipart` 或工具结果。
+高风险 operation 仅在用户意图和影响范围明确时设置 `confirm=true`；不要拼 `X-Confirm-Token` 或调用旧 reauth 流程。按 describe 的 responses 与实际 `status_code` 解释结果，不对自定义 Route、OpenAI 兼容流等强套 `{code,data,message}`。`response_policy.checkout_required=true` 时改走 checkout/commit。
 
-## CLI
+## CLI 与宿主
 
 ```bash
 draftgo mcp setup [target...]
@@ -81,72 +91,26 @@ draftgo mcp test
 draftgo mcp serve
 ```
 
-- `setup` 写入项目级宿主配置，只替换 `draftgo` MCP 条目并保留其他配置。
-- `status` 检查配置是否存在、格式是否有效，以及是否误写了凭据或远端 URL。
-- `test` 从 `.draftgo/config.json` 读取连接，验证 initialize、tools/list、三类正文 resource_list，以及 db_meta 的 api_search、api_describe 和只读 api_call。
-- `serve` 启动 stdio bridge，把宿主请求代理到当前项目配置的远端 Streamable HTTP `/mcp`。远端重启或 session 过期后，bridge 会清除旧 `Mcp-Session-Id`、重新 initialize，并对被明确拒绝为 session 无效的当前请求重试一次；普通超时、服务端错误和工具错误不会自动重试。
+- `setup` 写项目级宿主配置，只替换 `draftgo` 条目。
+- `status` 检查配置与凭据泄漏风险。
+- `test` 建立独立新连接并验证关键工具；它不证明宿主持有的旧 session 仍有效。
+- `serve` 是 stdio bridge。远端 session 明确失效时重新 initialize 并重放当前请求一次；普通超时、服务错误和工具错误不重试。
 
-`draftgo mcp test` 每次使用独立的新连接，因此它证明当前 server、SAT 和协议可以建立新 session，不代表宿主已持有的旧 session 仍然有效。宿主工具报告 session 失效但 `mcp test` 成功时，bridge 应自动恢复；若恢复仍失败，再检查远端日志、代理头传递和服务可用性。
+支持项目级 setup：Codex、Claude Code、Cursor、Gemini CLI、Kiro、GitHub Copilot。Windsurf 和 Antigravity 没有可靠项目级 MCP 配置，CLI 应明确提示不支持。
 
-`draftgo connect` 保存并验证 server/SAT、探测 `/mcp` 和关键工具，并可提示宿主 setup；`--server` 表示基础地址，完整 MCP endpoint 使用 `--mcp-url` 显式传入。它不下载业务资源，
-也不创建 pages、navigation、docs、db_meta 等本地镜像。底座仍在开发或暂不可达时，报告诊断结果即可，
-不得回退到 `pull --all`。
-
-## 宿主配置
-
-| 宿主 | 项目配置 | MCP setup |
-|---|---|---|
-| Codex | `.codex/config.toml` | 支持 |
-| Claude Code | `.mcp.json` | 支持 |
-| Cursor | `.cursor/mcp.json` | 支持 |
-| Gemini CLI | `.gemini/settings.json` | 支持 |
-| Kiro | `.kiro/settings/mcp.json` | 支持 |
-| GitHub Copilot | `.vscode/mcp.json` | 支持 |
-| Windsurf | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
-| Antigravity | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
-
-Codex 配置：
-
-```toml
-[mcp_servers.draftgo]
-command = "draftgo"
-args = ["mcp", "serve"]
-```
-
-Claude Code、Cursor、Gemini CLI 和 Kiro 使用各自文件中的 `mcpServers`：
+宿主配置只运行：
 
 ```json
-{
-  "mcpServers": {
-    "draftgo": {
-      "command": "draftgo",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
+{"command":"draftgo","args":["mcp","serve"]}
 ```
 
-GitHub Copilot 使用 `servers`，并声明 stdio：
-
-```json
-{
-  "servers": {
-    "draftgo": {
-      "type": "stdio",
-      "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。
 
-配置中不得出现 SAT、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据的命令行。
-bridge 必须从当前工作目录的 `.draftgo/config.json` 读取 server/SAT。
+`draftgo connect` 只保存并验证连接，不下载业务资源或创建本地镜像。MCP 不可用时运行 `draftgo mcp test` 收集证据。
 
-## 协议与安全
+## 安全
 
-- stdio 只输出 MCP JSON-RPC 帧；普通日志写入 stderr，且不得包含 SAT。
-- 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座 schema 或结构化错误。
-- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前对 SAT 和 Authorization 值做脱敏。
-- `.draftgo/config.json`、`.draftgo/worktree/` 和 `.draftgo/conflicts/` 必须加入 `.gitignore`。
-- 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。

package/resources/skill/references/methods.md

@@ -0,0 +1,189 @@
+---
+read_when: 不确定 DraftGo 任务应使用 API/MCP 还是 checkout；需要 AIHub、数据、内容、自定义服务、诊断或交付的最短正确命令链时
+---
+
+# 极简方法指南
+
+只使用本页列出的真实 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。先选择摘要、精确筛选或分页，避免用终端截断处理大结果。
+
+## AIHub
+
+适用场景：查询或管理 Agent、模型、供应商、路由、Skill、Prompt，或验证一次 AI 调用。
+
+```bash
+draftgo api search "AIHub <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"
+```
+
+关键约束与失败定位：AIHub 是结构化远端资源，不 checkout；只传 describe 允许的字段。不得把 API Key、Authorization、供应商 header 或上游地址写入文件和日志。401/403 查登录、`aihub:*` 权限和资源调用策略；503 查模型路由、适配器与凭据是否就绪。
+
+完成条件：写入后的目标 ID 可由 get/list operation 回读；任务涉及调用时，调用成功且 run 能按入口 Agent/模型或 request ID 定位。完整字段和编排规则再读 `aihub.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
+```
+
+关键约束与失败定位：知识库保存可检索资料，记忆保存运行时提炼结果，不能互相替代。知识库操作使用独立的 `knowledge:*`，不会继承 `aihub:*`。上传、检索、重建和记忆字段均以 describe 为准；没有专用 CLI 子命令。检索为空时依次核对文档状态、索引/重建结果、作用域和调用权限。
+
+完成条件：目标资源可回读；任务涉及检索或记忆召回时，最小验证调用能返回预期范围的数据，且运行日志可关联。
+
+## 统一权限与数据范围
+
+适用场景：设计角色、组织授权、动态 DB CRUD、知识库或自定义服务的资源归属。
+
+```text
+Role          = 无作用域的权限模板
+AccessGrant       = 主体在哪个 platform/space 范围获得 Role
+WorkspaceMember  = 加入根工作区的关系，本身不授权
+ResourceOwnership = 资源持久化归属，服务端最终判定边界
+DataRange     = 作用域内记录策略：none / own / all
+```
+
+platform AccessGrant 可跨空间，但只覆盖角色中显式列出的权限；space Grant 只能覆盖同根的 self/subtree。请求 header 只是候选上下文。
+创建、读取、更新、删除都必须由服务端同时校验动作权限、持久化 ResourceOwnership 和 DataRange。
+
+### 空间化最短流程
+
+开始前只运行一次 `draftgo status` 确认连接健康和 API Key 当前范围；需要选择空间时再运行 `draftgo space list`。目标 operation 仍须以实时 `describe` 的 `permission`、`supported_scopes` 和 `ownership_mode` 为准。
+
+| 场景 | 最短正确做法 |
+|---|---|
+| 单空间 | 固定使用该业务空间；调用输入传 `scope_type=space` 和目标 `space_id`。不为“方便”创建 platform Grant、子空间或用户组。 |
+| 多空间 | 每次先确定目标空间，再以该 `space_id` 调用；切换空间后重新读取目标资源。不要缓存一个空间的资源 ID 后在另一个空间复用。 |
+| 平台跨空间 | 仅当 operation 的实时契约支持 `platform`，且当前用户的 platform AccessGrant 明确包含所需 permission 时传 `scope_type=platform`。普通空间写入仍选择具体空间。 |
+| 超级管理员普通使用 | 与普通用户相同，选择当前业务空间并传 `scope_type=space`。管理员身份不把资源改成 platform 归属，也不绕过 Authorizer、DataRange 或持久化 ownership。 |
+
+空间调用输入只增加实时 MCP 支持的范围字段，其余容器仍按 `describe` 填写：
+
+```json
+{"scope_type":"space","space_id":120,"path":{},"query":{},"body":{}}
+```
+
+平台调用使用 `{"scope_type":"platform", ...}` 且不传 `space_id`。对已有资源的按 ID 操作，客户端选择的范围不能覆盖服务端已保存的 ResourceOwnership；403 时进入 `diagnostics.md`，不要改 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`。
+
+## 自定义服务
+
+适用场景：编写、保存、验证、试运行或发布 Go 自定义服务。
+
+```bash
+draftgo api search "custom service create"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+draftgo checkout custom-services <id>
+draftgo diff custom-services <id>
+draftgo commit custom-services <id>
+draftgo validate custom-services <id>
+draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
+draftgo publish custom-services <id>
+```
+
+关键约束与失败定位：自定义服务只有一种 Go `Register` 形态；后端从 `Register` 自动发现 Route/Event/Scheduled handler，不需要配置服务模式或 `triggers` 字段。worktree 只含 `service.go` 和 `service.json`，`go.mod/go.sum` 由 Runner 管理。`commit custom-services` 自动完成提交、验证和发布。余额、权益、支付和订阅使用 `ctx.Billing` / `ctx.Admin.Billing`，精确签名读 checkout 后的 `.draftgo-sdk/billing.go`，不要用动态 DB 自建账本。试运行默认拒绝副作用；真实写入必须显式使用 `--side-effect-policy live --test-write`。validate 失败查编译/Register/依赖；test 失败按 execution/request ID 查运行日志；revision 冲突停止重试。
+
+完成条件：`commit custom-services` 返回 published 且 validate passed；需要运行行为证据时再要求 test success。完整 SDK、handler selector 和依赖规则再读 `custom-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 和 grant；session/uninitialized 重新建立连接；operation 不唯一时继续缩小 search；describe 缺字段、风险或响应契约时停止。
+
+完成条件：initialize、tools/list、关键 tools/call 可用，目标 operation schema 已确认且可回读一次无副作用结果。完整缓存、风险和 multipart 规则再读 `mcp.md`。
+
+## 运行诊断
+
+适用场景：连接失败、API 调用失败、checkout 状态异常，或需要定位 AI/custom-service 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。
+
+完成条件：故障被定位到连接、契约、权限、资源版本、Runner 或业务运行中的一层，并有 request ID/run 等可关联证据。完整分流再读 `diagnostics.md`。
+
+## 交付验收
+
+适用场景：准备提交、发布、交付或关闭 worklog 项目。
+
+```bash
+draftgo verify
+draftgo check --remote --output json
+draftgo work complete <ref> --note "<结果与证据>"
+```
+
+正文资源在 complete 前还必须成功执行 `diff -> commit`；结构化资源必须 call 后回读；自定义服务按任务要求追加 validate/test/publish。默认不启动浏览器，只有用户明确要求视觉验收时才使用 `draftgo verify --url <url> --screenshot always`，需要 DOM/交互时再加 `--ui always`。
+
+关键约束与失败定位：本地验证通过不等于已提交或已发布。任何 verify、commit、MCP 写入、必要 test/publish、回读或视觉验收失败时，工作项保持 active。
+
+完成条件：全部目标远端状态可回读，正文版本/哈希或结构化状态符合预期，任务要求的运行/视觉证据齐全且不含凭据，然后才 complete。

package/resources/skill/references/modules.md

@@ -11,22 +11,43 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 | 页面 | 数据库 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` |
-| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | MCP 实时 API；不创建本地镜像 |
+| 文件资产 | 文件夹、文件元数据、绑定、下载、回收站和对象存储 | MCP 实时 API；文件字节不进入普通 tool result |
+| 自定义服务 | 单一 Go `Register` 服务；后端从注册代码自动发现 Route/Event/Scheduled handler | MCP 定位/创建；正文用 `checkout custom-services` / `commit custom-services` |
 | AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
 | 文档中心 | Markdown/HTML 文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
 | 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
+| 商业与计费 | 账本、余额、权益、支付订单、退款、套餐、订阅和 AI 计费 | 管理任务用 MCP 实时 API；自定义服务用 `ctx.Billing` / `ctx.Admin.Billing`；不要用动态 DB 重建金钱状态 |
 
 ## 平台内置模块（开箱即用，不需实现）
 
 | 模块 | 能力 | 调用方式 |
 |---|---|---|
 | 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
-| 角色权限 | 多角色 RBAC，页面/DB/API 均支持角色级权限 | `App.isAdmin` / `App.currentUser.role_code` |
+| 角色权限 | 无作用域 Role 模板 + 带 `platform` / `space` 范围的 AccessGrant | 页面可用 `App.permissions` 辅助显隐；服务端按资源授权 |
+| 工作区与空间 | 根工作区成员、用户组和递归 Space；成员关系本身不授权 | `App.scopeContext` + MCP space/group/grant operations；资源保存直接归属 |
+| 动态数据范围 | `DataRange=none|own|all`，限制空间内的记录级访问 | db_meta 的记录策略；不替代 ResourceOwnership 或 AccessGrant |
 | 通知公告 | 发布公告，支持类型/状态/分页 | MCP 实时 API |
 | 工单反馈 | 用户提交问题，支持类型/状态跟踪 | MCP 实时 API |
 | 备份恢复 | 完整/选择性备份，JSON/.dgbak 格式，支持 dry-run | MCP 实时 API |
 | 系统管理 | 系统配置 KV、存储健康、全局前端层、通知测试 | MCP 实时 API |
 
+`App.currentUser.role_code` 是展示投影，不是用户表中的可写字段。真正的资源/API 授权由服务端根据 ResourceOwnership 与有效 AccessGrant 决定；platform Grant 也只能使用角色中显式声明的权限。
+
+用户 API Key 只是一种用户认证方式；它不改变 AccessGrant、ResourceOwnership、DataRange 或管理员边界。服务身份是平台运行时主体。
+
+## 新模块权限接入检查表
+
+AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺少任一项都不能用页面显隐、角色名或调用来源补洞：
+
+- [ ] 在统一 Permission Catalog 注册每个 `resource:action`，声明支持的 `platform` / `space` 范围以及是否使用 DataRange；不在模块内另建权限字符串或角色分支。
+- [ ] 顶层资源持久化 canonical ResourceOwnership：platform，或完整的 `ownership_type=space + workspace_id + space_id`；需要 own/all 时同时保存 `owner_user_id`。子资源只能通过不可变父键继承归属。
+- [ ] 创建和列表只接受服务端验证后的范围上下文；读取、更新、删除及其他按 ID 操作先加载持久化 ownership，忽略客户端提交的 workspace、space、owner 或调用者替代值。
+- [ ] 使用统一 Authorizer 校验真实 Principal、Catalog permission 和持久化 ResourceOwnership；执行记录级操作时继续应用返回的 DataRange，不能把 `all` 解释为跨工作区。
+- [ ] HTTP、MCP、SDK、Route、Event、Schedule 和 worker 等所有实际入口复用同一授权路径；TokenScope 只能对最终权限取交集并收窄。
+- [ ] 保留最小拒绝证据：无 Grant、space Grant 跨根、伪造归属；支持 own/all 时再覆盖他人记录拒绝。不要为同一规则复制一套测试框架。
+
+实现位置和具体 API 以目标 DraftGo 服务端仓库的现有 Catalog、ResourceOwnership 与 WorkspaceAuthorizer 模式为准；本 Skill 不复制服务端动态 schema。
+
 ## 模块选型决策
 
 ```
@@ -34,20 +55,27 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
   → 有固定结构 → 动态 DB（db_meta 定义 schema）
   → 仅需 KV → sys_config（category 自定义）
 
+要保存文件？
+  → 文件夹、上传、下载、回收站或业务绑定 → 文件资产模块；不要把文件字节塞进动态 DB
+
+要做余额、支付、会员或订阅？
+  → 管理操作走 money/payment/subscription/billing 的 MCP 实时契约；自定义服务读 `.draftgo-sdk/billing.go` 并使用 Billing SDK，不自行实现账本或扣费一致性
+
 要调用 AI？
   → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
   → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
   → 图片生成 → AIHub + DraftGoAI.images()
+  → Responses、Embedding、Rerank、TTS、ASR 或 Video → AIHub capability 与 provider readiness；先确认模型的 canonical capability 和 transport
   → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
 
 要调用第三方服务？
-  → 自定义服务（用 `draftgo.HTTP` 请求；需要时可用 route/event/scheduled 加工）
+  → 自定义服务（用 `ctx.HTTP` 请求；在同一 Go 服务中按需注册 Route/Event/Scheduled handler）
 
 要展示内容文档？
   → 文档中心（Markdown + 分类树）
 
 要做定时任务或事件响应？
-  → 自定义服务（mode: scheduled / event）
+  → 自定义服务（用 `app.Schedule` / `app.On` 注册；后端自动识别定时任务和事件 handler）
 
 要做后台管理页？
   → 业务页面 + 动态 DB + 角色权限
@@ -56,11 +84,11 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 ## 自定义服务边界
 
 - 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
-- `route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，保存或发布后要真实请求验证。
-- `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
-- `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
+- `Route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，草稿行为先用 `draftgo test custom-services` 验证。
+- `Event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
+- `Scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
 - 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
 - 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
 - Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
 - 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
-- 脚本内读动态 DB 用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。
+- 脚本内读动态 DB 用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。

package/resources/skill/references/runtime.md

@@ -35,7 +35,7 @@ read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问
 
 壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
 
-`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
+`app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题/作用域）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme/scopeContext）
 
 完整 API 见 `references/app-api.md`
 
@@ -94,11 +94,34 @@ const orderId = query.orderId;  // "42"
 
 ### 修改方法
 
-system_config 是结构化远端资源。修改前通过 MCP `draftgo_api_search` / `draftgo_api_describe` 获取实时契约，
-再用 `draftgo_api_call` 读取并更新目标键；不要 checkout、pull 或维护本地索引。
+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`。
+
+## 统一作用域
+
+DraftGo 的资源归属和授权范围只有 `platform`、`space`。`Role` 是无作用域权限模板；`AccessGrant`
+定义 user/group/service 主体在哪个范围拥有该角色。工作区成员与用户组成员关系本身不授予权限。
+
+`platform` Grant 可跨全部空间，但只能使用 Role 中显式列出的权限。`space` Grant 仅覆盖同一根工作区内的
+目标空间或 subtree；所有授权为 allow-only 并集，DataRange 使用 `all > own > none`。
+
+页面需要切换工作范围时使用 `App.getScopeContext()`、`App.setScopeContext(context)`，不要把
+space id 当作自定义权限判断。上下文只是请求意图，服务端仍以持久化 `ResourceOwnership` 和有效 AccessGrant 为准。
+API 请求只使用 `X-DraftGo-Scope-Type` 与 `X-DraftGo-Space-Id`；workspace_id 由服务端推导。
+
+动态 DB 的 `DataRange`（数据库元数据中的记录策略）是另一层：`none` 拒绝动作，`owner` 仅允许当前
+所有者记录，`all` 允许当前 ResourceOwnership 内全部记录。它不能扩大 `platform` / `space` 范围；
+不要把 `all` 解释成跨工作区。记录的 `userid` 是当前兼容实现的所有者字段，`created_by` / 独立
+`owner_user_id` 只有在服务端契约明确提供后才能使用。
+
+认证边界：交互式 CLI、MCP 和普通 HTTP API 使用当前用户的 API Key；该凭据始终代表该用户，权限来自
+用户及用户组的 AccessGrant，TokenScope 只能收窄，不能变成管理员或服务身份。CI、定时任务和共享服务等
+无人值守自动化使用平台的独立服务凭据通道；service principal 由平台内部注入，CLI 不生成、导出或伪造
+服务身份凭据。

package/resources/skill/story/SKILL.md

@@ -110,9 +110,8 @@ now:
    - MCP resource_search/get_metadata → 页面与导航元数据（跳过 tag="系统" 的内置页）
    - MCP api_search/api_describe/api_call → db_meta 与自定义服务结构
    - 只有必须分析完整 pages/nav/docs 正文时才 checkout；不要要求 MCP 返回全文
-   - .draftgo/changelog.md → 更新日志
+   - .draftgo/worklog.md → 工作进度与完成记录
    - .draftgo/lessons/ → 开发经验记录
-   - .draftgo/Task/ → 历史任务文档
    - 用户提供的设计文档（PRD / 原型说明 / 需求文档）→ 提取产品意图
 
 2. 从已有数据推断系统画像，生成推断版 Story（含 design.overview 和 modules）