draftgo-cli 4.0.1 → 4.0.23

package/resources/skill/references/custom-services.md

@@ -1,26 +1,40 @@
 ---
-read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
+read_when: 编写、修改、试运行、发布或评审自定义服务时；使用服务 SDK、Route、Event、Scheduled handler 或服务依赖时
 ---
 
 # Go 自定义服务契约
 
-自定义服务是完整的 Go `package main`。平台构建源码和 `go.mod`/`go.sum`，执行 `Register` 保存触发器清单，并在独立子进程中运行 handler。SDK 固定导入 `draftgo/sdk`；它由构建器注入，不写进 `require` 或 `replace`。
+自定义服务是完整的 Go `package main`。平台从源码生成并锁定依赖，执行 `Register` 保存触发器清单，并在独立子进程中运行 handler。SDK 固定导入 `draftgo/sdk`，由构建器注入。
 
-## 开发流程
+## 最短流程
 
-完整正文使用：
+先通过 MCP resource/API operation 定位或创建服务并取得 ID；operation schema 以实时 describe 为准。完整正文只走两文件 worktree：
 
 ```bash
 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> [--handler route:POST:/path]
+draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
 draftgo publish custom-services <id...>
 ```
 
-checkout 目录包含 `service.go`、`go.mod`、`go.sum`、`service.json` 及对应 base。commit 只保存共享 cloud draft；publish 才切换线上版本。定位、创建、权限和结构化元数据通过 MCP 实时 operation 完成，创建后取得 ID 再 checkout。
+`commit custom-services` 是一体化交付入口，会依次完成 commit、validate 和 publish，并在成功后启用线上版本。`publish custom-services` 仍保留为兼容入口；`validate` 和 `test` 仍会先 commit 当前 worktree。不同服务可并发，同一服务保持 edit -> diff -> commit 顺序。
 
-不同服务可并发处理；同一服务保持 commit -> validate -> test/publish 顺序。草稿 revision 是内容版本，`validated_revision` / `validated_hash` 是该版本的验证凭证。保存会清空凭证；测试和发布必须使用当前 revision。CLI 会复用有效凭证，不重复 commit、checkout 或 validate。
+`test` 默认执行 cloud draft；`--source published` 直接测试线上版本且不会提交本地改动，`--source auto` 按生命周期选择。草稿 revision 是内容版本，`validated_revision` / `validated_hash` 绑定源码、依赖、SDK 与 Runner 协议；保存会使旧凭证失效。Runner/SDK 变化导致 `validation_stale` 时，publish 只自动重新 validate 一次；revision 冲突直接停止。
+
+## Worktree
+
+| 文件 | 用法 |
+|---|---|
+| `service.go` | 完整 `package main`；在 `Register` 中声明 handler |
+| `service.json` | 服务元数据；以实时 checkout/API schema 标出的可编辑字段为准 |
+
+两个文件都必须保留。`service.json` 中的 `schema_version`、`id`、`revision`、`validation_status`、`validated_revision`、`validated_hash` 是服务端状态，不手工伪造；`Register` 是 Route/Event/Scheduled handler 的唯一事实来源，不在元数据中维护触发器或运行模式。
+
+CLI 只支持当前 schema v2 的 `service.go`/`service.json` worktree。旧四文件或 schema v1 会明确拒绝；删除旧 worktree 后重新执行 checkout 即可。
+
+SDK 固定导入 `draftgo/sdk`。第三方依赖在 `service.go` 顶部声明 `//draftgo:require github.com/google/uuid@v1.6.0`；必须固定显式版本，禁止 floating version、本地路径与自定义 replace。CLI 会从随包发布的 SDK 快照生成 `go.mod/go.sum`、`draftgo_local_main.go` 与 `.draftgo-sdk/`，仅供 gopls 和本地 `go build`；这些带托管标记的文件会自动刷新，不能手工维护，也不会上传。服务端仍独立生成并锁定实际运行依赖。
 
 ## 最小服务
 
@@ -31,19 +45,14 @@ import "draftgo/sdk"
 
 func Register(app *sdk.App) {
     app.Route("GET", "/health", health)
-    app.On("order.paid", afterPaid)
-    app.Schedule("0 9 * * 1-5", weekdayReport)
 }
 
-func health(draftgo *sdk.Context) (any, error) {
-    return draftgo.Respond(map[string]any{"ok": true}, 200, nil), nil
+func health(ctx *sdk.Context) (any, error) {
+    return ctx.Respond(map[string]any{"ok": true}, 200, nil), nil
 }
-
-func afterPaid(draftgo *sdk.Context) (any, error) { return nil, nil }
-func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 ```
 
-`Register` 只注册 handler，不访问网络、数据库或通知系统。新服务使用 `mode=mixed`；第三方依赖锁定明确版本并写入 `go.mod`，可选校验和写入 `go.sum`。
+`Register` 只注册 handler，不访问网络、数据库或通知系统。平台在 validate 时执行它并自动记录 handler。
 
 ## 触发器
 
@@ -51,9 +60,9 @@ func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 
 `app.Route("POST", "/orders", createOrder)` 在 `slug=commerce` 时对应 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
 
-输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `draftgo.Auth.CurrentUser()` 获取。普通 `draftgo.DB`、`Users` 等调用继承请求调用者权限；管理员创建服务、持有 SAT 或 `RequireAdmin` 都不会自动提升 SDK 调用。
+输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `ctx.Auth.CurrentUser()` 获取。普通 `ctx.DB`、`ctx.Users`、`ctx.Billing` 等调用继承请求调用者权限；管理员创建服务、持有服务凭据或 `RequireAdmin` 都不会自动提升 SDK 调用。
 
-可信服务需要管理员能力时逐次显式调用 `draftgo.Admin.*`。它只提升该次 RPC，并审计服务、版本、真实调用者、操作、资源和结果；服务代码拿不到 SAT、数据库连接或管理员凭据。Route 返回值仍需自行脱敏。
+`ctx.Admin.*` 是自定义服务显式选择的单次系统内部授权：该次 RPC 按 `*:*:all` 全权限执行，可跨用户/空间，不检查调用者或服务主体 AccessGrant；服务主体仅保留用于 ownership 与审计。每次调用都会进入审计，内部授权不会泄漏到后续普通调用。服务代码仍拿不到服务凭据、数据库连接或管理员凭据。公开 Route 不应无条件调用 Admin；先完成业务鉴权、参数校验和幂等设计，返回值仍需自行脱敏。
 
 ### Event
 
@@ -61,7 +70,21 @@ func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 
 ### Scheduled
 
-`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有调用者，以系统身份执行；仅可信编辑者可维护，并应限制写入范围、记录业务日志。
+`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有用户调用者；执行空间来自服务持久化的 ResourceOwnership，服务 principal 还必须有覆盖目标资源的 AccessGrant。运行时不会猜测用户或回退到 platform。
+
+## 试运行
+
+```bash
+# Route；request.json 是 handler input object
+draftgo test custom-services 12 --source draft --handler route:POST:/orders --input request.json
+
+# Event / Scheduled / 直接 handler 名
+draftgo test custom-services 12 --handler event:order.paid --input event.json
+draftgo test custom-services 12 --handler scheduled:weekday-report
+draftgo test custom-services 12 --handler health
+```
+
+`--source draft` 是默认值，会提交并验证当前工作树草稿；`--source published` 直接试运行已发布版本，不提交本地改动；`auto` 由服务生命周期决定。`--headers headers.json` 与 `--user user.json` 注入测试上下文，文件必须是 UTF-8 JSON object。默认 `--side-effect-policy deny`：外部 HTTP、通知和 AI 调用会失败；用 `mock` 返回模拟结果。只有用户明确要求真实副作用时才使用 `--side-effect-policy live --test-write`。数据库等 SDK 写操作同样必须显式 `--test-write`。试运行结果包含 execution ID、来源 revision、状态、输出、HTTP 状态/响应头、日志和 SDK operation 摘要。
 
 ## SDK
 
@@ -69,55 +92,96 @@ func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 
 | 入口 | 核心能力 |
 |---|---|
-| `draftgo.DB` | Create/CreateMany/Get/Update/UpdateMany/Delete/Query |
-| `draftgo.Users` | Get/List/Update |
-| `draftgo.Auth` | RequireLogin/RequireAdmin/RequireRole/CurrentUser |
-| `draftgo.Notify` | 站内通知 |
-| `draftgo.HTTP` | Get/Post/Put/Patch/Delete |
-| `draftgo.Cache` / `Config` | 缓存与系统配置 |
-| `draftgo.AIHub` | Agent/模型推理、图片、Embedding、AI 资产与运行记录 |
-| `draftgo.Knowledge` | 知识库、文档、Chunk、上传、检索和重建 |
-| `draftgo.Memory` | 长期记忆与全局检索配置 |
+| `ctx.DB` | Create/CreateMany/Get/Update/UpdateMany/Delete/Query |
+| `ctx.Users` | Get/List/Update |
+| `ctx.Auth` | RequireLogin/RequireAdmin/RequireRole/CurrentUser |
+| `ctx.Notify` | 站内通知 |
+| `ctx.HTTP` | Get/Post/Put/Patch/Delete |
+| `ctx.Cache` / `Config` | 缓存与系统配置 |
+| `ctx.AIHub` | Agent/模型推理、图片、Embedding、AI 资产与运行记录 |
+| `ctx.Knowledge` | 知识库、文档、Chunk、上传、检索和重建 |
+| `ctx.Memory` | 长期记忆与全局检索配置 |
+| `ctx.Files` | 文件夹、资产上传/下载、绑定、回收站和恢复 |
+| `ctx.Scope` | 当前 platform/space、principal 与 ResourceOwnership 授权检查 |
+| `ctx.Billing` | 账本、权益、支付、套餐、订阅和 AI 计费；所有写操作按实时权限与风险契约执行 |
 
 常用示例：
 
 ```go
-records, err := draftgo.DB.Query("order", sdk.QueryOptions{
+records, err := ctx.DB.Query("order", sdk.QueryOptions{
     Filters: map[string]any{"status": "paid"}, Page: 1, PageSize: 20,
 })
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
+reply, err := ctx.AIHub.Chat(ctx.Context(), sdk.AIChatRequest{
     AgentID: 12, Message: "总结订单",
 })
-response, err := draftgo.HTTP.Get(draftgo.Context(), "https://api.example.com/health", nil, 10*time.Second)
+response, err := ctx.HTTP.Get(ctx.Context(), "https://api.example.com/health", nil, 10*time.Second)
 ```
 
-HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒，响应体最大 5 MB。日志每次执行最多 500 条、单条 4096 字符，不记录 token、Cookie、密码或完整个人信息。
+精确签名以 checkout 后自动生成的 `.draftgo-sdk/billing.go` 为准；该文件由 CLI 同步当前 SDK，只读不改。不要猜方法名、字段或直接调用账务 HTTP API。
 
-### AI 权限
+### Billing 决策与用法
+
+需要余额、退款、权益、套餐或订阅时使用 `ctx.Billing` / `ctx.Admin.Billing`，不得用动态 DB、缓存或自行维护余额重建金钱状态。金额统一使用最小货币单位：人民币 `AmountMinor: 990` 表示 9.90 元。
 
-普通 AIHub/Knowledge/Memory 继承用户身份并经过 `aihub:*` 等权限。`draftgo.Admin.AIHub`、`Admin.Knowledge`、`Admin.Memory` 与普通入口同构，但逐次以管理员执行并审计。
+| 场景 | 方法 |
+|---|---|
+| 当前调用者操作服务归属内账务 | `ctx.Billing.*` |
+| 自定义服务执行系统级账务管理 | `ctx.Admin.Billing.*`；单次调用按系统全权限执行并审计 |
+| 金额已确定且应立即扣除 | `DebitAccount` |
+| 最终金额不确定或业务可能失败 | `HoldFunds` -> `SettleHold`；失败时 `ReleaseHold` |
+| 更正已入账流水 | `ReverseJournal`，不要用反向充值伪造冲正 |
+| 次数、额度或功能许可 | `ConsumeEntitlement`，不要混用钱包余额 |
+| 三方支付退款 | `RefundPaymentOrder` |
 
-普通推理还必须在服务配置中启用：
+直接扣款示例：
 
-```json
-{
-  "aihub": {
-    "enabled": true,
-    "allowed_agents": [12],
-    "allow_direct_model_call": true,
-    "allowed_models": ["gpt-4.1-mini"],
-    "allow_images": true
-  }
+```go
+result, err := ctx.Billing.DebitAccount(ctx.Context(), sdk.MoneyOperationRequest{
+    AmountMinor:    990,
+    Reference:      "order:20260829-001",
+    Reason:         "购买专业版功能",
+    IdempotencyKey: "order:20260829-001:debit",
+})
+if err != nil {
+    return ctx.Respond(map[string]any{"error": "扣款失败"}, 409, nil), nil
 }
+return ctx.Respond(map[string]any{
+    "journal_id": result.JournalID,
+    "balance_minor": result.BalanceMinor,
+}, 200, nil), nil
+```
+
+每个金额写操作都必须使用可持久复用、业务唯一的 `IdempotencyKey`，推荐 `{业务类型}:{业务ID}:{动作}`；不得使用时间戳或每次重试生成的新 UUID。相同 key 的相同请求安全重试；同一 key 改变目标或金额会发生幂等冲突。余额不足时操作失败且不会产生负余额。
+
+预授权流程必须为 `HoldFunds` -> `SettleHold` / `ReleaseHold`，三个动作分别使用稳定幂等键，并持久化返回的 `HoldID`。不确定远端调用是否已成功时，先按业务 ID 或流水回读，不自动换 key 重扣。日志只能记录业务引用、`JournalID` / `HoldID` 和脱敏错误，不记录完整用户资料或支付凭据。
+
+试运行真实账务写入必须显式执行：
+
+```bash
+draftgo test custom-services 12 --source draft --handler route:POST:/charge --input request.json --side-effect-policy live --test-write
 ```
 
-空白名单表示不额外限制，不会绕过用户权限、Agent 调用权限或模型外部调用策略。typed helper 未覆盖的新端点可使用 `AIHub.Request`，但 path 只能位于平台允许的 AI/Knowledge/Memory 前缀，不能传外部 URL、路径穿越或内嵌 query。
+只验证编译与路由时不要开启真实写入。涉及金额的测试使用专门测试账户、最小金额和唯一业务 ID，完成后回读余额与流水；禁止在生产用户账户上试扣。
+
+HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒，响应体最大 5 MB。日志每次执行最多 500 条、单条 4096 字符，不记录 token、Cookie、密码或完整个人信息。
+
+### AI 权限
+
+普通 AIHub、Knowledge、Memory 使用调用者与服务 Grant 的权限交集。AIHub 使用 `aihub:*`，Knowledge 独立使用 `knowledge:*`；两组权限互不包含。显式 `ctx.Admin.AIHub`、`ctx.Admin.Knowledge`、`ctx.Admin.Memory` 对单次可信服务调用启用管理提升并写入审计。
+
+服务不再配置 AI 启用开关、图片开关、直接模型调用开关、Agent 白名单或模型白名单；`config.aihub` 会被拒绝。Agent 与模型是否可调用直接跟随 AI 板块自身配置。普通调用按调用者与服务 Grant 的交集鉴权；只有源码中显式选择的 `ctx.Admin.*` 才启用单次可信管理提升。
+
+typed helper 未覆盖的新端点可使用 `ctx.AIHub.Request`，但 path 只能位于平台允许的 AI/Knowledge/Memory 前缀，不能传外部 URL、路径穿越或内嵌 query。
 
 ## 权限与运行
 
 - `scripts:read/create/update/delete/execute` 控制服务管理。
-- Route 仍受服务 `permission` 与 `config.route_security` 控制。
-- 只有显式 `draftgo.Admin.*`、定时任务和无可解析用户的事件是提升身份例外。
+- Role 不带作用域；服务必须通过覆盖持久化 ResourceOwnership 的有效 AccessGrant 授权。工作区成员关系不能单独授权。
+- platform Grant 可跨空间但只能使用显式权限；space Grant 不能跨根。请求中的范围不能覆盖服务已保存的归属。
+- 普通服务调用访问动态 DB 时仍受目标 DB 的 DataRange（`none` / `own` / `all`）限制；`ctx.Admin.*` 只应用于源码明确选择的单次可信管理操作，不能从请求参数隐式开启。
+- Route 不接受服务级 `permission`；入口由宿主认证、服务 ownership 和调用者 `scripts:execute` AccessGrant 控制，业务级公开/登录规则在 handler 内显式实现。
+- 定时任务和无可解析用户的事件默认使用服务主体及其持久化空间；需要平台级或跨归属管理时必须在对应单次调用显式使用 `ctx.Admin.*`。
+- 服务 principal 由平台运行时注入；不要在 `service.json`、源码、测试参数或日志中保存/模拟服务身份凭据。Route/Event 取调用者与服务 Grant 的权限交集，Scheduled 使用服务持久化 ownership，而不是假造用户 API Key。
 - `config.timeout`、`max_concurrency`、`queue_timeout_ms` 控制执行；Route 饱和返回 429。
 - 超时会终止独立子进程。运行器不是不可信多租户安全沙箱，只授予可信编辑者服务权限。
 - 构建键覆盖源码、依赖、SDK 和 Runner 协议；有效验证凭证绑定该键，任一部分变化都必须重新验证。
@@ -131,6 +195,7 @@ HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒
 ## 完成条件
 
 - `package main` 且实现无业务副作用的 `Register(app *sdk.App)`。
+- `service.go`、`service.json` 齐全，handler 仅在 `Register` 注册，服务端状态字段未被手工伪造。
 - trigger 与 handler 签名正确，第三方依赖已锁定。
 - Route 权限、管理员调用和返回脱敏符合真实调用者范围。
-- `draftgo validate` 通过；需要运行行为证据时执行相关 `draftgo test`。发布仅在用户任务包含发布时进行。
+- `draftgo commit custom-services` 成功并显示 published；需要运行行为证据时执行相关 `draftgo test`。

package/resources/skill/references/data.md

@@ -4,6 +4,21 @@ read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检
 
 # 动态 DB & 数据层
 
+## 最短管理流程
+
+结构和记录都走实时 API 契约，不 checkout：
+
+```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 后，先回读目标 `type`，再调用记录 operation 验证最小 CRUD；不要把管理端 `db_meta` operation 与页面运行时的 `App.get/post/put/delete('db/...')` 混用。失败时优先核对 describe 的字段容器、`searchable`、权限、记录 owner 和分页，而不是猜静态路径。
+
+完成条件：schema 可按 `type` 回读，目标角色的最小 CRUD 与筛选行为通过；批量写入还要验证失败时整批回滚。
+
 ## DB Meta 结构
 
 ```json
@@ -46,12 +61,12 @@ read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检
 
 ---
 
-## 自定义服务内的 draftgo.DB.Query
+## 自定义服务内的 ctx.DB.Query
 
-Go 自定义服务使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
+Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
 
 ```go
-result, err := draftgo.DB.Query("order", sdk.QueryOptions{
+result, err := ctx.DB.Query("order", sdk.QueryOptions{
     Filters: map[string]any{"status": "paid"},
     Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
 })
@@ -71,7 +86,7 @@ items := result.Items
 `filters` 操作符示例：
 
 ```go
-draftgo.DB.Query("order", sdk.QueryOptions{Filters: map[string]any{
+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},

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 回读。自定义服务执行 `diff -> commit`，其中 commit 自动完成 validate 和 publish；需要运行行为证据时再执行 test。
+
+## 统一收尾
+
+```bash
+draftgo verify
+draftgo work complete <ref> --note "<结果与证据>"
+```
+
+默认 `verify` 不启动浏览器。只有用户明确要求视觉验收时，才增加 `--url <url> --screenshot always`；需要 DOM 或交互验证时再用 `--ui always`。所有 commit、MCP 写入、必要 test/publish 和回读都成功后才能 complete；失败项保持 active，并在 note 外记录可脱敏的 request ID。
+
+完成条件：本地检查通过，目标远端资源可回读，版本/哈希或结构化状态与预期一致，任务要求的运行或视觉证据齐全，且证据不含凭据。

package/resources/skill/references/diagnostics.md

@@ -0,0 +1,51 @@
+---
+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`，并输出当前 `platform`/`space` TokenScope；space 上下文同时带 `workspace_id` 与 `space_id`。只执行与故障层级有关的命令：连接失败看 `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。自定义服务再按 `custom-services.md` 执行 validate/test，页面运行时再读 `runtime.md`。
+
+## 权限与范围诊断
+
+| 结果 | 最短定位 |
+|---|---|
+| 400 | 重新 `draftgo api describe <operation_id>`，核对当前 registry revision、`path/query/body/multipart` 容器、必填字段和 `scope_type/space_id` 组合。不要靠修改字段名试探契约。 |
+| 401 | 运行 `draftgo status`；检查项目是否连接、当前用户 API Key 是否缺失、过期或已撤销。重新连接或轮换后再试一次，不把密钥放进输入、宿主配置或日志。 |
+| 403 | 从结构化错误读取 `error_code`、`permission` 和 `scope_type`；核对 operation 所需 permission、API Key TokenScope、持久化 ResourceOwnership、有效 AccessGrant 和 DataRange。管理员身份与工作区成员关系都不是授权来源。 |
+| space 跨根拒绝 | 这是预期边界。确认目标资源保存的 workspace root 与 Grant 所属 root；改用同根 self/subtree Grant 或合法迁移流程。只有实时契约支持且明确需要跨空间管理时，才检查显式 permission 的 platform Grant。不要篡改 workspace/space ID 或 header 重试。 |
+
+解释 Grant 来源时先用实时契约，不从角色名或 UI 状态推测：
+
+```bash
+draftgo grant list --input request.json
+draftgo api search "access grant explain"
+draftgo api describe <explain_operation_id>
+draftgo api call <explain_operation_id> --input request.json --output json
+```
+
+按解释结果核对直接用户 Grant 与用户组 Grant 的并集、Role 中的精确 permission、space 的 self/subtree 覆盖、Grant/Role/成员/组的启用状态和有效期，以及最终 `matched_grant_ids` / DataRange。没有匹配来源时保持拒绝，不临时授予更大的 platform 权限来验证。
+
+不要在 issue、工作日志、命令参数或诊断文件中写 API Key、服务凭据、Authorization、完整请求头或上游服务地址。非幂等写入失败后先回读状态，不自动重试。
+
+完成条件：故障已定位到连接、契约、权限、资源版本、Runner 或业务运行中的一层，并保留可关联的 request ID/run 证据；无法定位时明确缺少哪项服务端证据。

package/resources/skill/references/frontend.md

@@ -10,6 +10,19 @@ version: 2.0.0
 
 ## 页面决策
 
+## 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/css/js`、`contract.json` 和 `component.json`，然后依次执行 `components diff`、`components verify`、`components commit`。`commit` 只保存草稿；只有用户明确要求上线时才执行 `components publish`。库管理和组件创建、复制、删除、ZIP 导入导出均使用 `components libraries|create|copy|delete|import|export`，不要绕过 CLI 直接修改 DraftGo 数据库。
+
 ### 页面身份与创建
 
 业务新页面默认是数据库中的完整 HTML 页面。先结合用户意图与 MCP 中的标题、route、用途和入口判断目标：
@@ -51,9 +64,10 @@ version: 2.0.0
 - 数据型页面应让主要操作、分页、批量操作和保存控件在空、短、长列表下都可达；滚动边界明确，横向溢出不能隐藏核心操作。
 - 展示可维护内容时判断是否需要管理入口并复用同一份真实数据。列表、详情和编辑结构按任务差异设计，不复制大量同构工作台。
 - 按钮、标签、导航项、徽章等视觉整体内部使用 `white-space: nowrap`；整组可换行，但图标与文字不能被拆散。
-- 空态需有明确文案和下一步操作；自定义空态用 flex 对齐图标与文字，不依赖 `text-align` 居中块级图标。
+- 空态需有明确文案和下一步操作；已有固定主操作入口时使用紧凑说明和就近操作，自定义空态用 flex 对齐图标与文字。
 - 弹窗和抽屉把滚动放在内容区，避免双滚动条；flex 内容区使用 `min-height: 0` 保持滚动可用。
-- 下拉选择使用组件库选择器或可访问的自定义弹层，不使用浏览器默认 `<select>`。
+- 官方内置页的复杂选择器优先使用 Basecoat 或可访问的自定义弹层；普通 Page 可按场景使用原生 `<select>`，并补齐主题、焦点、禁用、空值和错误状态。
+- 运营表格可把排序和筛选放在对应表头的弹层中，保持数据列、条件和结果之间的直接关系；具体交互由数据规模与操作频率决定。
 
 ### 响应式
 
@@ -71,25 +85,23 @@ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 先加载核心，再按需加载插
 
 - DraftGo 壳层位于 `frontend/`，使用 React 19 + Vite 8 + Tailwind CSS 4。只有用户明确要求修改壳层时才编辑该源码。
 - 业务页面与导航存储为数据库中的完整 HTML 文档，由壳层在 iframe 中运行。不得写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
-- 数据库页面需要 React 时，只能使用内置 React 18 UMD 的 `window.React` / `window.ReactDOM`；不要混入壳层 React 19 或其他版本。
+- 数据库 Page 使用普通 HTML + Tailwind CSS 4 + 原生 JavaScript；官方内置 Page 默认搭配 Basecoat UI，按需使用下方列出的本地资源。
 - 页面使用 `const App = window.parent?.App`。参数读取 `window.__DG_ROUTE_CONTEXT__.query`；页面跳转使用父窗口；登出调用 `await App.logout()`。
 
-## 必须与禁止
-
-必须：
+## 实践建议
 
 - 提交完整 `<html><head><body>` 文档，静态资源使用下方本地路径。
+- Basecoat 是默认 Page 组件库；Oat 是 Web Components 场景的可选组件库，版本处于 pre-1.0。每个 Page 按场景选择其中一套组件库。
 - 默认使用 `var(--dg-*)` 主题 token，并支持浅色/深色；用户输入或不可信 HTML 经 DOMPurify 净化。
 - 使用 `App.confirm()`、`App.toast()` 或对应反馈 API；关键状态不能只靠颜色或动画。
+- 建议调用全局 `App.formatDateTime(value, options)` 来适配系统时间显示；API 时间按 UTC 解析，页面不要直接按浏览器本地时区展示。
 - 初始渲染立即显示稳定的加载状态。
-
-禁止：
-
-- 境外 CDN（googleapis、jsdelivr、cdnjs、unpkg）；品牌图标的明确例外见资源章节。
-- `window.alert/confirm/prompt`、`App()`、`window.location.search`、页面内直接 `window.location.href=...`。
-- 把 TSX、ESM、npm 依赖或构建产物写进数据库 HTML。
-- 在业务页面实现全局浮窗、客服、统计脚本或重复 Toast；使用 `frontend_global_*` 槽位和系统配置。
-- 用无作用域 CSS 覆盖组件库内部 hover、focus、disabled、error 状态。
+- 空间业务页先读取有效的 `{ scope_type: 'space', space_id }` 再发送业务请求；上下文就绪期间保持稳定加载状态，没有可用工作空间时呈现紧凑的工作空间状态和重试入口。完整写法见 `app-api.md`。
+- 页面文案使用页面级 `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 或局部作用域进行适配。
 
 ## 组件与资源
 
@@ -97,52 +109,27 @@ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 先加载核心，再按需加载插
 
 | 名称 | 版本与形态 | 本地资源 |
 |---|---|---|
-| Ant Design | 5.29.3，React 18 UMD，`window.antd` | `/assets/antd/reset.css`、React、ReactDOM、dayjs、`/assets/antd/antd.min.js` |
 | Basecoat UI | 1.0.2，HTML/CSS/JS，`window.basecoat` | `/assets/vendor/basecoat/basecoat.min.css`、`basecoat.min.js` |
 | Oat UI | 0.7.0，Web Components，`window.ot` | `/assets/vendor/oat/oat.min.css`、`oat.min.js` |
 
-`/assets/adapters/draftgo-ui.js` 提供 `window.DraftGoUI` 与 `DraftGoUI.load('antd'|'basecoat'|'oat')`。Basecoat/Oat 的 `/assets/adapters/draftgo-theme.css` 必须位于对应组件 CSS 之后。组件选择取决于任务，不强制套用。
-
-### Ant Design 契约
-
-手工加载顺序不可变：
-
-```html
-<link href="/assets/antd/reset.css" rel="stylesheet">
-<script src="/assets/react/react.min.js"></script>
-<script src="/assets/react-dom/react-dom.min.js"></script>
-<script src="/assets/dayjs/dayjs.min.js"></script>
-<script src="/assets/antd/antd.min.js"></script>
-```
-
-不要加载 `antd.min.css`、ESM/CDN AntD 或其他版本。根组件使用 `antd.ConfigProvider`，根据 `App.theme` 选择 `antd.theme.darkAlgorithm/defaultAlgorithm`，并把 `--dg-accent` 传给 `token.colorPrimary`；监听根元素的 `style/class/data-theme` 变化以刷新主题。
-
-组件库是其内部状态样式的唯一所有者：优先用 ConfigProvider、design token 或公开 API。自建组件才由页面 CSS 管理状态，且规则限定在组件类或页面根内。
-
-| AntD | 平台反馈 |
-|---|---|
-| `Modal.confirm` | `await App.confirm(msg, title)` |
-| `Modal.info/warning` | `App.showModal(msg, title)` |
-| `message.success/error` | `App.showSuccess/showError(msg)` |
-| `message.info/warning` | `App.showInfo/showWarning(msg)` |
+`/assets/adapters/draftgo-ui.js` 提供 `window.DraftGoUI` 与 `DraftGoUI.load('basecoat'|'oat')`。壳层自动注入 `/assets/adapters/draftgo-theme.css` 与组件运行时，Page 可直接使用；第三方 Page 按产品需求自主选择技术与视觉方案。使用组件库时通过公开类名/API 和 DraftGo 语义 token 适配。
 
-Tooltip 可保留组件库原生实现。
+确认、信息弹层和反馈优先使用 `App.confirm()`、`App.showModal()`、`App.showSuccess/showError/showInfo/showWarning()`，避免页面各自复制 Toast 或浏览器原生对话框。
 
 ### 本地资源
 
 | 能力 | 路径 |
 |---|---|
-| Tailwind runtime | `/assets/tailwindcss.js` |
-| React/AntD | `/assets/react/react.min.js`、`/assets/react-dom/react-dom.min.js`、`/assets/dayjs/dayjs.min.js`、`/assets/antd/antd.min.js` |
+| Tailwind CSS 4.3.1 Browser Runtime | `/assets/tailwindcss.js` |
 | UI adapters | `/assets/adapters/draftgo-ui.js`、`/assets/adapters/draftgo-theme.css` |
 | Basecoat/Oat | `/assets/vendor/basecoat/*`、`/assets/vendor/oat/*` |
-| Icons/fonts | `/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`、`/assets/icons/manifest.json`、`/assets/fonts/*.css` |
-| Markdown/code | `/assets/vendor/marked/marked.min.js`、`/assets/vendor/highlightjs/highlight.min.js`、`/assets/vendor/prism/prism.min.js` |
-| HTML/security/export | `/assets/vendor/dompurify/purify.min.js`、`/assets/vendor/html2canvas/html2canvas.min.js` |
+| Icons | `/assets/fontawesome/css/all.min.css`、`/assets/icons/{name}.svg`、`/assets/icons/manifest.json` |
+| 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 | `/assets/draftgo-chat.js` |
 | Motion | `/assets/vendor/gsap/*.js` |
 
-通用图标优先使用本地图标或 FontAwesome。模型/Provider 品牌标识可用固定版本的 LobeHub `@lobehub/icons-static-svg` npmmirror URL；不得用 `latest`，也不得替代通用 UI 图标。
+正文使用系统无衬线字体栈，代码使用系统等宽字体栈。通用图标优先使用项目内置 SVG，其他通用图标可使用 Font Awesome。模型/Provider 品牌标识可用固定版本的 LobeHub `@lobehub/icons-static-svg` npmmirror URL。
 
 ## 主题
 
@@ -167,3 +154,4 @@ AI 对话 UI 使用：
 动态创建使用 `DraftGoChat.create()`；无 UI 文本或图片调用可用同一脚本的 `DraftGoAI` 兼容门面。完整事件、会话和安全契约见 `chat-sdk.md`，Agent `spec` 见 `aihub.md`。
 
 平台请求与反馈见 `app-api.md`；iframe 路由、认证与全局层见 `runtime.md`；动态 DB、`scope=mine`、筛选和关系见 `data.md`。
+Chat JSON 配置按 DraftGo 当前 `contracts/chat-sdk.schema.json` 校验，函数型扩展只在 JavaScript 注册。

package/resources/skill/references/mcp.md

@@ -6,6 +6,34 @@ read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约
 
 根 `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 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
+```
+
+已配置且连接正常时无需每次运行前两条；只在初次配置、配置变化或 MCP 失败时执行。完成标准是 initialize、tools/list 和关键 tools/call 可用，目标 operation 的 schema 已确认且调用结果可回读。401/403 查用户 API Key 或权限，session/uninitialized 查会话与服务重启，5xx 记录 request ID 后查服务日志；不要用重复写入测试连接。
+
 ## 边界
 
 MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigations、docs/articles、custom_services 的完整正文走 `draftgo checkout` / `draftgo commit`；工具返回 `artifact` 或 `omitted` 时保留该语义，不要求模型展开长内容。
@@ -30,7 +58,7 @@ MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigatio
 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 并重试一次；其他工具错误不触发自动重试。
+4. call 携带缓存的 `registry_revision`。服务返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次。危险 operation 自身契约变化或服务端明确报告 CLI/契约不兼容时停止调用，升级 CLI 后重新 describe 和确认；其他工具错误不触发自动重试。
 
 describe 缺少本次调用需要的 schema、权限、风险或响应契约时停止并报告，不猜字段、不拼路径、不绕过 MCP。多个 operation 仍可能匹配时继续缩小 search，而不是任选一个。
 
@@ -50,7 +78,7 @@ describe 缺少本次调用需要的 schema、权限、风险或响应契约时
 }
 ```
 
-只传 operation schema 需要的容器。路径参数放 `path`，查询参数放 `query`，JSON 放 `body`，文件或表单字段放 `multipart`。不得传 tenant override、SAT、Authorization 或其他凭据。
+只传 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。
 
@@ -76,13 +104,13 @@ draftgo mcp serve
 {"command":"draftgo","args":["mcp","serve"]}
 ```
 
-Codex 使用 `[mcp_servers.draftgo]`；GitHub Copilot 使用 `servers` 且声明 `type="stdio"`；其他支持宿主使用各自 `mcpServers`。配置不得包含 SAT、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据命令。bridge 从当前项目 `.draftgo/config.json` 读取 server/SAT。
+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，且不得包含 SAT。
+- stdio stdout 只输出 MCP JSON-RPC；日志写 stderr，且不得包含 API Key。
 - 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座结果。
-- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前脱敏 SAT 与 Authorization。
+- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前脱敏 API Key 与 Authorization。
 - `.draftgo/config.json`、`.draftgo/api-contract-cache.json`、worktree 和 conflicts 都是私有运行时状态并应 gitignore。