draftgo-cli 3.0.56 → 4.0.22

package/resources/skill/references/checkout.md

@@ -4,9 +4,21 @@ read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manif
 
 # Checkout / Commit
 
+## 页面与内容最短流程
+
+```bash
+draftgo map --type pages --route /admin/channel-ops --output json
+draftgo checkout pages 42
+draftgo diff pages 42 --stat
+draftgo verify pages 42
+draftgo commit pages 42
+```
+
+导航和文档分别替换为 `nav`、`docs`。route/title 为精确匹配，两个条件取交集；只需确认范围或 checkout 状态时使用 `map --summary`，必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用 `--cursor <opaque>` 翻页。新资源先用 `draftgo api search "create page"` 或对应内容类型定位创建 operation，describe/call 取得 ID 后再 checkout；不要用 checkout 创建资源。`verify` 通过不等于已交付，commit 返回新版本与哈希才算正文写入成功。发生 409/412 时保留冲突材料并停止提交。
+
 ## Workflow 2.0 scope
 
-The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_services`. A custom-service checkout is a directory containing exactly `service.go`, `go.mod`, `go.sum`, and `service.json`, plus one complete `.base` directory. `draftgo commit custom-services <id>` saves a cloud draft; it does not publish. Use `draftgo test custom-services <id>` for server Runner validation/execution and `draftgo publish custom-services <id>` for explicit publication. DB Meta remains a live MCP/API resource and is never checked out.
+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.
 
 `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.
 
@@ -32,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> <id>
+draftgo diff <pages|nav|docs|custom-services> <id> [--stat|--summary]
 draftgo conflicts
 draftgo conflict show <pages|nav|docs> <id>
 draftgo conflict resolve <pages|nav|docs> <id>
@@ -41,11 +53,13 @@ draftgo conflict resolve <pages|nav|docs> <id>
 `checkout --force` 只用于用户明确允许丢弃未提交本地修改的情况。默认 checkout 检测到 worktree 文件相对
 base 已变化时必须拒绝覆盖。
 
+`diff --stat` 只显示文件与增删行数；`diff --summary` 显示资源、基线版本和变化概要。两者均不输出正文 diff，先用它们确认范围，再按需展开完整 `diff`。`--output json` 时 stdout 只包含 UTF-8 JSON，诊断走 stderr。
+
 ## Checkout 流程
 
 1. CLI 通过 MCP `draftgo_resource_get_metadata` 取得规范类型、content_type、SHA-256、大小、版本/revision、
    ETag 和受信任的下载/提交 URL。
-2. CLI 使用 `.draftgo/config.json` 中的 SAT 通过专用 HTTP 下载完整正文；SAT 不进入 MCP 参数或日志。
+2. CLI 使用 `.draftgo/config.json` 中的用户 API Key 通过专用 HTTP 下载完整正文；API Key 不进入 MCP 参数或日志。
 3. 响应体直接流式写入同目录临时文件，校验 content_type、字节数和 SHA-256。
 4. 校验成功后原子重命名到 worktree 文件，并保存相同字节的 `.base` 文件。
 5. 最后原子更新 `.draftgo/worktree/manifest.json`。失败时不得留下半截正式文件或推进 manifest。
@@ -95,14 +109,14 @@ base 已变化时必须拒绝覆盖。
 ## Commit 流程
 
 1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
-2. 按 content_type 执行本地结构和内联脚本检查；页面布局或交互有变化时运行 `draftgo verify <type> <id> --url <url>`。
+2. 按 content_type 执行本地结构和内联脚本检查。
 3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
 4. 完整正文不得作为 MCP tool 参数发送。
 5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
 
-推荐编辑顺序：主 Agent 按任务读取相关 Reference -> MCP 精确定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify <type> <id> --remote --url <url>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
+本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
-单个 commit 成功不自动写 changelog。只有整个任务统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行一次 `draftgo changelog add "<完成结果>"`。任何检查失败、409/412 或交付失败都不得写入。
+单个 commit 成功不自动完成 worklog 项。只有整个事项统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行 `draftgo work complete <编号> --note "<完成结果>"`。任何检查失败、409/412 或交付失败都不得标记为完成。
 
 ## 409 / 412 冲突
 
@@ -119,7 +133,7 @@ base 已变化时必须拒绝覆盖。
 - `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
 - `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
 - Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
-- 合并完成后运行 `draftgo check`、必要时 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
+- 合并完成后运行 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
 - resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
   `draftgo diff` 并 `draftgo commit`。
 

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

@@ -1,299 +1,201 @@
 ---
-
-read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
+read_when: 编写、修改、试运行、发布或评审自定义服务时；使用服务 SDK、Route、Event、Scheduled handler 或服务依赖时
 ---
 
 # Go 自定义服务契约
 
-DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`，可以使用标准库和 `go.mod` 中声明的第三方库。平台在保存或发布时编译服务、运行 `Register` 并保存触发器清单；执行时在独立子进程中调用选定 handler。
-
-平台 SDK 的固定导入路径是 `draftgo/sdk`。它是 DraftGo 构建器注入的本地 module，不从 GitHub 或其他网络仓库下载，也不要在服务的 `go.mod` 中自行添加或 `replace` 此依赖。
-
-## 索引
-
-- [最小服务](#最小服务)、[本地资源](#本地资源)、[触发器](#触发器)
-- [平台 SDK](#平台-sdk)、[AI 平台 SDK](#ai-平台-sdk)
-- [权限与运行限制](#权限与运行限制)、[实时 API](#实时-api)、[验收清单](#验收清单)
-
-## 最小服务
-
-```go
-package main
-
-import "draftgo/sdk"
+自定义服务是完整的 Go `package main`。平台从源码生成并锁定依赖，执行 `Register` 保存触发器清单，并在独立子进程中运行 handler。SDK 固定导入 `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
-}
+先通过 MCP resource/API operation 定位或创建服务并取得 ID；operation schema 以实时 describe 为准。完整正文只走两文件 worktree：
 
-func afterPaid(draftgo *sdk.Context) (any, error) {
-	draftgo.Log.Info("order paid event received")
-	return nil, nil
-}
-
-func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
+```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> --source draft --handler route:POST:/path --input request.json
+draftgo publish custom-services <id...>
 ```
 
-`Register` 必须没有业务副作用。它只注册 handler；网络请求、写数据库、发通知等操作放在 handler 内。
+`commit custom-services` 是一体化交付入口，会依次完成 commit、validate 和 publish，并在成功后启用线上版本。`publish custom-services` 仍保留为兼容入口；`validate` 和 `test` 仍会先 commit 当前 worktree。不同服务可并发，同一服务保持 edit -> diff -> commit 顺序。
 
-## 资源读写
+`test` 默认执行 cloud draft；`--source published` 直接测试线上版本且不会提交本地改动，`--source auto` 按生命周期选择。草稿 revision 是内容版本，`validated_revision` / `validated_hash` 绑定源码、依赖、SDK 与 Runner 协议；保存会使旧凭证失效。Runner/SDK 变化导致 `validation_stale` 时，publish 只自动重新 validate 一次；revision 冲突直接停止。
 
-自定义服务是结构化远端资源，不使用 checkout/commit，也没有约定的本地镜像目录。先用
-`draftgo_resource_search` 定位服务，再用 `draftgo_api_search` / `draftgo_api_describe` 获取当前管理接口契约，
-通过 `draftgo_api_call` 读取、创建或更新。Agent 可以在普通工作区文件中编写和检查 Go 源码，但不得把该文件
-误当作远端事实来源；写入时按实时契约显式发送代码和元数据。
+## Worktree
 
-常见服务载荷字段如下，实际字段以 `draftgo_api_describe` 为准：
+| 文件 | 用法 |
+|---|---|
+| `service.go` | 完整 `package main`；在 `Register` 中声明 handler |
+| `service.json` | 服务元数据；以实时 checkout/API schema 标出的可编辑字段为准 |
 
-```json
-{
-  "name": "order-service",
-  "slug": "order-service",
-	"mode": "mixed",
-  "code": "package main\n\n// ...\n",
-  "go_mod": "module example.com/order-service\n\ngo 1.26.0\n\nrequire github.com/google/uuid v1.6.0\n",
-  "go_sum": ""
-}
-```
+两个文件都必须保留。`service.json` 中的 `schema_version`、`id`、`revision`、`validation_status`、`validated_revision`、`validated_hash` 是服务端状态，不手工伪造；`Register` 是 Route/Event/Scheduled handler 的唯一事实来源，不在元数据中维护触发器或运行模式。
 
-- 新服务使用 `mode=mixed`，允许同一个 `Register` 同时注册 route、event 和 scheduled。旧服务可继续使用单一 `route`、`event` 或 `scheduled` mode。
-- `go_mod` 和可选的 `go_sum` 随服务版本保存，并和代码一起通过实时管理 API 提交。
-- 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
+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`；这些带托管标记的文件会自动刷新，不能手工维护，也不会上传。服务端仍独立生成并锁定实际运行依赖。
 
-### Route
+## 最小服务
 
 ```go
+package main
+
+import "draftgo/sdk"
+
 func Register(app *sdk.App) {
-	app.Route("POST", "/orders", createOrder)
+    app.Route("GET", "/health", health)
 }
 
-func createOrder(draftgo *sdk.Context) (any, error) {
-	body, _ := draftgo.Input["body"].(map[string]any)
-	return draftgo.Respond(body, 201, nil), nil
+func health(ctx *sdk.Context) (any, error) {
+    return ctx.Respond(map[string]any{"ok": true}, 200, nil), nil
 }
 ```
 
-`slug=commerce` 时地址为 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
+`Register` 只注册 handler，不访问网络、数据库或通知系统。平台在 validate 时执行它并自动记录 handler。
 
-`draftgo.Input` 的 Route 字段：`method`、`headers`、`body`、`query_params`、`path_params`。当前身份通过 `draftgo.Auth.CurrentUser()` 获取，入站请求头通过 `draftgo.Headers.Get("Authorization")` 等读取。
+## 触发器
 
-Route 默认以请求调用者身份访问 `draftgo.DB`、`draftgo.Users` 和其他平台能力。服务由管理员创建、拥有 `scripts:*` 管理权限，或在请求中收到 SAT，都不会让普通 SDK 调用自动提升；`draftgo.Auth.RequireAdmin()` 也只检查当前调用者。
+### Route
 
-可信服务需要管理员权限时，逐次显式使用 `draftgo.Admin.*`。这不是服务配置项，也不需要 `admin_access` 开关：调用 `Admin` 就是管理员调用声明。运行时为**这一次**平台 SDK 调用注入管理员身份，并把服务、版本、真实调用者、操作、资源和结果写进该次执行的审计日志；SAT、数据库连接和管理员凭据不会暴露给服务代码。
+`app.Route("POST", "/orders", createOrder)` 在 `slug=commerce` 时对应 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
 
-```go
-func catalog(draftgo *sdk.Context) (any, error) {
-	// 继承调用者权限
-	owned, err := draftgo.DB.Query("order", sdk.QueryOptions{})
-	if err != nil { return nil, err }
-
-	// 显式管理员权限；仅此调用提升
-	internal, err := draftgo.Admin.DB.Query("internal_catalog", sdk.QueryOptions{})
-	if err != nil { return nil, err }
-
-	return draftgo.Respond(map[string]any{
-		"orders": owned.Items,
-		"catalog": internal.Items, // 生产代码应再按客户端可见字段组装
-	}, 200, nil)
-}
-```
+输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `ctx.Auth.CurrentUser()` 获取。普通 `ctx.DB`、`ctx.Users`、`ctx.Billing` 等调用继承请求调用者权限；管理员创建服务、持有服务凭据或 `RequireAdmin` 都不会自动提升 SDK 调用。
 
-`draftgo.Admin` 提供与普通 SDK 对齐的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub`、`Knowledge`、`Memory` 能力。它等价于管理员在平台拥有的权限，不做资源级白名单；因此只能授予可信服务编辑者，并且 Route 返回值仍必须由代码负责脱敏。
+`ctx.Admin.*` 是可信服务显式选择的单次管理提升：保持服务主体与已验证执行上下文，但可执行平台级或跨用户/空间管理操作；每次调用都会进入审计，提升不会泄漏到后续普通调用。服务代码仍拿不到服务凭据、数据库连接或管理员凭据。公开 Route 不应无条件调用 Admin；先完成业务鉴权、参数校验和幂等设计，返回值仍需自行脱敏。
 
 ### Event
 
-```go
-app.On("user.registered", welcome)
-
-func welcome(draftgo *sdk.Context) (any, error) {
-	payload, _ := draftgo.Input["payload"].(map[string]any)
-	draftgo.Log.Info("registered user: " + fmt.Sprint(payload["user_id"]))
-	return nil, nil
-}
-```
-
-事件异步且不阻塞原请求。事件输入含 `event`、`timestamp`、`payload`。
-
-事件 `payload` 含 `user_id` 或 `actor_user_id` 且该用户仍存在时，handler 继承该用户身份；无法解析用户时才以系统身份执行。事件服务应把事件数据视为业务输入，而不是把它当成绕过资源权限的通道。
+`app.On("user.registered", welcome)` 异步执行，不阻塞原请求。输入含 `event`、`timestamp`、`payload`。payload 中可解析的 `user_id` / `actor_user_id` 会作为继承身份；无法解析时才使用系统身份。
 
 ### Scheduled
 
-```go
-app.Schedule("0 2 * * *", cleanup)
-```
-
-cron 使用五字段表达式，也支持 `interval:5m`。定时 handler 的 `draftgo.Input` 为空对象。
-
-定时任务没有调用者，会以系统身份执行。因此它只能由可信编辑者维护，写入范围应限制在明确的数据类型，并在 handler 中记录可审计的业务日志。
-
-## 平台 SDK
-
-所有资源访问经受控 RPC 返回 Go 主服务。不要自行读取数据库连接、服务 token 或宿主机环境变量。
-
-```go
-record, err := draftgo.DB.Create("order", map[string]any{"title": "DraftGo"})
-records, err := draftgo.DB.Query("order", sdk.QueryOptions{
-	Filters: map[string]any{"status": "paid"},
-	Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
-})
-
-user, err := draftgo.Users.Get(12)
-err = draftgo.Auth.RequireLogin()
-err = draftgo.Notify.Send(12, "完成", "订单已创建", "info")
+`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有用户调用者；执行空间来自服务持久化的 ResourceOwnership，服务 principal 还必须有覆盖目标资源的 AccessGrant。运行时不会猜测用户或回退到 platform。
 
-cached, err := draftgo.Cache.Get("daily-report")
-err = draftgo.Cache.Set("daily-report", map[string]any{"ok": true}, time.Hour)
+## 试运行
 
-value, err := draftgo.Config.Get("feature_flag", false)
-response, err := draftgo.HTTP.Get(draftgo.Context(), "https://api.example.com/health", nil, 10*time.Second)
+```bash
+# Route；request.json 是 handler input object
+draftgo test custom-services 12 --source draft --handler route:POST:/orders --input request.json
 
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{AgentID: 12, Message: "总结订单"})
-draftgo.Log.Info("service completed")
+# 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
 ```
 
-`draftgo.DB` 支持 `Create`、`CreateMany`、`Get`、`Update`、`UpdateMany`、`Delete`、`Query`。`Query` 返回 `sdk.QueryResult{Items, Total, Page, PageSize}`。
-
-`draftgo.Users` 支持 `Get`、`List`、`Update`。`draftgo.Auth` 支持 `RequireLogin`、`RequireAdmin`、`RequireRole`、`CurrentUser`。
+`--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 摘要。
 
-`draftgo.HTTP` 支持 `Get`、`Post`、`Put`、`Patch`、`Delete`；响应为 `sdk.HTTPResponse{StatusCode, Headers, Data}`。服务可使用 `config.http_allowed_hosts` 限制出站目标；HTTP timeout 最终限制为 1-30 秒，响应体最大 5 MB。
+## SDK
 
-## AI 平台 SDK
+所有平台访问通过受控 RPC 返回主服务，不自行读取宿主环境变量、数据库连接或 token。
 
-| 入口 | 能力 |
+| 入口 | 核心能力 |
 |---|---|
-| `draftgo.AIHub` | Agent/模型推理、图片、Embedding、Agent/Prompt/Skill/MCP 资产 CRUD、供应商、模型路由、Skill 安装与版本、运行记录 |
-| `draftgo.Knowledge` | 知识库、文档、Chunk CRUD，文档上传、检索、重建索引 |
-| `draftgo.Memory` | 长期记忆 CRUD 与全局检索配置 |
-
-普通入口继承调用用户身份，继续经过 `aihub:read/create/update/delete/execute/invoke` 等平台权限检查。`draftgo.Admin.AIHub`、`draftgo.Admin.Knowledge`、`draftgo.Admin.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
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
-	AgentID: 12,
-	Message: "总结订单",
-	SessionID: "optional-conversation-id",
-	RunID: "optional-client-run-id",
+records, err := ctx.DB.Query("order", sdk.QueryOptions{
+    Filters: map[string]any{"status": "paid"}, Page: 1, PageSize: 20,
 })
-
-direct, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
-	Model: "gpt-4.1-mini",
-	Messages: []map[string]any{{"role": "user", "content": "hello"}},
-})
-
-vectors, err := draftgo.AIHub.Embeddings(draftgo.Context(), sdk.AIEmbeddingRequest{
-	Model: "text-embedding-3-small",
-	Input: []string{"first document", "second document"},
+reply, err := ctx.AIHub.Chat(ctx.Context(), sdk.AIChatRequest{
+    AgentID: 12, Message: "总结订单",
 })
+response, err := ctx.HTTP.Get(ctx.Context(), "https://api.example.com/health", nil, 10*time.Second)
 ```
 
-`GenerateImage` 支持 Agent 和直接模型两种调用。普通入口的推理必须在服务 `config.aihub` 中显式开启：
-
-```json
-{
-  "aihub": {
-    "enabled": true,
-    "allowed_agents": [12, 18],
-    "allow_direct_model_call": true,
-    "allowed_models": ["gpt-4.1-mini", "text-embedding-3-small"],
-    "allow_images": true
-  }
-}
-```
+精确签名以 checkout 后自动生成的 `.draftgo-sdk/billing.go` 为准；该文件由 CLI 同步当前 SDK，只读不改。不要猜方法名、字段或直接调用账务 HTTP API。
 
-空白名单表示不额外限制，但用户权限、Agent 调用权限和模型外部调用策略仍然生效。Agent 预览与后续新增的 `/api/v1/*` 推理端点也使用同一组白名单策略。
+### Billing 决策与用法
 
-### AI 资产、Skill 与 MCP
+需要余额、退款、权益、套餐或订阅时使用 `ctx.Billing` / `ctx.Admin.Billing`，不得用动态 DB、缓存或自行维护余额重建金钱状态。金额统一使用最小货币单位：人民币 `AmountMinor: 990` 表示 9.90 元。
 
-Agent、Prompt、Skill、MCP 使用统一资产 CRUD，通过 `type` 区分：
+| 场景 | 方法 |
+|---|---|
+| 当前调用者操作服务归属内账务 | `ctx.Billing.*` |
+| 可信服务执行需要管理员权限的账务管理 | `ctx.Admin.Billing.*`；目标仍由服务端资源归属决定 |
+| 金额已确定且应立即扣除 | `DebitAccount` |
+| 最终金额不确定或业务可能失败 | `HoldFunds` -> `SettleHold`；失败时 `ReleaseHold` |
+| 更正已入账流水 | `ReverseJournal`，不要用反向充值伪造冲正 |
+| 次数、额度或功能许可 | `ConsumeEntitlement`，不要混用钱包余额 |
+| 三方支付退款 | `RefundPaymentOrder` |
 
-```go
-skills, err := draftgo.AIHub.ListAssets(draftgo.Context(), map[string]any{
-	"type": "skill", "page": 1, "page_size": 50,
-})
+直接扣款示例：
 
-mcp, err := draftgo.AIHub.CreateAsset(draftgo.Context(), map[string]any{
-	"type": "mcp", "name": "internal-tools",
-	"data": map[string]any{"transport": "http", "url": "https://mcp.example.com"},
-	"status": 1,
-})
-
-tools, err := draftgo.AIHub.DiscoverMCPTools(draftgo.Context(), map[string]any{
-	"transport": "http", "url": "https://mcp.example.com",
+```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
 ```
 
-资产方法包括 `ListAssets/GetAsset/CreateAsset/UpdateAsset/UpdateAssets/DeleteAsset`、`AgentReadiness/PublishAgent`、`DiscoverMCPTools`、`InstallSkill/InstallSkillArchive/ListSkillVersions/RollbackSkill`。供应商使用 `ListProviders/GetProvider/CreateProvider/UpdateProvider/DeleteProvider/DiscoverProvider/SyncProvider`；模型和路由使用 `ListModels/GetModel/CreateModel/UpdateModel/DeleteModel/ProbeModel/UpdateModelRoute/DeleteModelRoute`；运行记录使用 `ListRuns/GetRun/DeleteRuns`。
+每个金额写操作都必须使用可持久复用、业务唯一的 `IdempotencyKey`，推荐 `{业务类型}:{业务ID}:{动作}`；不得使用时间戳或每次重试生成的新 UUID。相同 key 的相同请求安全重试；同一 key 改变目标或金额会发生幂等冲突。余额不足时操作失败且不会产生负余额。
 
-### 知识库与记忆
+预授权流程必须为 `HoldFunds` -> `SettleHold` / `ReleaseHold`，三个动作分别使用稳定幂等键，并持久化返回的 `HoldID`。不确定远端调用是否已成功时，先按业务 ID 或流水回读，不自动换 key 重扣。日志只能记录业务引用、`JournalID` / `HoldID` 和脱敏错误，不记录完整用户资料或支付凭据。
 
-```go
-base, err := draftgo.Knowledge.Create(draftgo.Context(), map[string]any{
-	"name": "产品手册", "embedding_model_id": 7,
-})
-
-document, err := draftgo.Knowledge.UploadDocument(draftgo.Context(), baseID,
-	sdk.KnowledgeDocumentUpload{
-		Filename: "manual.pdf", MIMEType: "application/pdf", Content: pdfBytes,
-		Metadata: map[string]any{"product": "DraftGo"},
-	})
-
-matches, err := draftgo.Knowledge.Retrieve(draftgo.Context(), baseID, map[string]any{
-	"query": "如何配置模型供应商？", "mode": "hybrid", "top_k": 6,
-})
+试运行真实账务写入必须显式执行：
 
-memory, err := draftgo.Memory.Create(draftgo.Context(), map[string]any{
-	"scope": "user_agent", "user_id": 42, "agent_id": 12,
-	"content": "用户偏好简洁的中文回答", "importance": 0.8,
-})
+```bash
+draftgo test custom-services 12 --source draft --handler route:POST:/charge --input request.json --side-effect-policy live --test-write
 ```
 
-`Knowledge` 还提供知识库 `List/Get/Update/Delete`、文档 `ListDocuments/GetDocument/UpdateDocument/DeleteDocument/ReindexDocument`、Chunk `ListChunks/UpdateChunk` 以及 `RebuildIndex`。文档上传受 8 MiB 限制。`Memory` 提供 `List/Get/Create/Update/Delete`，全局配置使用 `draftgo.Memory.GetConfig` 和 `draftgo.Memory.UpdateConfig`。
+只验证编译与路由时不要开启真实写入。涉及金额的测试使用专门测试账户、最小金额和唯一业务 ID，完成后回读余额与流水；禁止在生产用户账户上试扣。
 
-### 扩展入口
+HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒，响应体最大 5 MB。日志每次执行最多 500 条、单条 4096 字符，不记录 token、Cookie、密码或完整个人信息。
 
-typed helper 尚未覆盖新端点时，使用 `AIHub.Request`：
+### AI 权限
 
-```go
-value, err := draftgo.AIHub.Request(draftgo.Context(), sdk.AIRequest{
-	Method: "GET",
-	Path: "/api/aihub/types",
-})
-```
+普通 AIHub、Knowledge、Memory 使用调用者与服务 Grant 的权限交集。AIHub 使用 `aihub:*`，Knowledge 独立使用 `knowledge:*`；两组权限互不包含。显式 `ctx.Admin.AIHub`、`ctx.Admin.Knowledge`、`ctx.Admin.Memory` 对单次可信服务调用启用管理提升并写入审计。
 
-`Request` 只接受 `/api/aihub`、`/api/agents`、`/api/v1`、`/api/images`、`/api/knowledge-bases`、`/api/memories`、`/api/skills` 路径；禁止外部 URL、路径穿越和在 `Path` 中拼 query。身份、权限、推理开关与审计规则和 typed helper 相同。
+服务不再配置 AI 启用开关、图片开关、直接模型调用开关、Agent 白名单或模型白名单；`config.aihub` 会被拒绝。Agent 与模型是否可调用直接跟随 AI 板块自身配置。普通调用按调用者与服务 Grant 的交集鉴权；只有源码中显式选择的 `ctx.Admin.*` 才启用单次可信管理提升。
 
-日志每次执行最多 500 条、单条最多 4096 字符。不要记录 token、Cookie、密码或完整个人信息。
+typed helper 未覆盖的新端点可使用 `ctx.AIHub.Request`，但 path 只能位于平台允许的 AI/Knowledge/Memory 前缀，不能传外部 URL、路径穿越或内嵌 query。
 
-## 权限与运行限制
+## 权限与运行
 
-- `scripts:read/create/update/delete/execute` 控制可信人员管理服务。
-- Route 调用者仍由服务 `permission` 与 `config.route_security` 控制；管理权限不绕过 Route 调用权限。
-- Route 的普通 SDK 数据访问继承调用者权限；不要把“管理员创建服务”误写成自动提升。只有显式 `draftgo.Admin.*` 调用才以管理员执行并记录审计；定时任务和无可解析用户的事件是系统身份例外。
-- `config.timeout`、`max_concurrency`、`queue_timeout_ms` 适用于服务执行。Route 饱和时返回 HTTP 429。
-- Go 服务以独立进程运行，超时会终止该进程；它不是为不可信多租户代码准备的安全沙箱。只向可信编辑者授予服务编辑权限。
-- 每个保存版本按源码、依赖、SDK 和 Runner 协议生成不可变构建键。代码或依赖变更会生成新构建产物；旧版本可通过现有版本恢复接口重新激活。
+- `scripts:read/create/update/delete/execute` 控制服务管理。
+- Role 不带作用域；服务必须通过覆盖持久化 ResourceOwnership 的有效 AccessGrant 授权。工作区成员关系不能单独授权。
+- platform Grant 可跨空间但只能使用显式权限；space Grant 不能跨根。请求中的范围不能覆盖服务已保存的归属。
+- 普通服务调用访问动态 DB 时仍受目标 DB 的 DataRange（`none` / `own` / `all`）限制；`ctx.Admin.*` 只应用于源码明确选择的单次可信管理操作，不能从请求参数隐式开启。
+- Route 仍受服务 `permission` 与 `config.route_security` 控制。
+- 定时任务和无可解析用户的事件默认使用服务主体及其持久化空间；需要平台级或跨归属管理时必须在对应单次调用显式使用 `ctx.Admin.*`。
+- 服务 principal 由平台运行时注入；不要在 `service.json`、源码、测试参数或日志中保存/模拟服务身份凭据。Route/Event 取调用者与服务 Grant 的权限交集，Scheduled 使用服务持久化 ownership，而不是假造用户 API Key。
+- `config.timeout`、`max_concurrency`、`queue_timeout_ms` 控制执行；Route 饱和返回 429。
+- 超时会终止独立子进程。运行器不是不可信多租户安全沙箱，只授予可信编辑者服务权限。
+- 构建键覆盖源码、依赖、SDK 和 Runner 协议；有效验证凭证绑定该键，任一部分变化都必须重新验证。
 
 ## 实时 API
 
-服务管理接口使用标准 `{code, data, message}` 信封并受 `scripts:*` 权限控制。具体 operation、参数、请求体、响应和风险必须通过 MCP `draftgo_api_search` → `draftgo_api_describe` 获取后再调用，不维护静态路径表。
+管理接口使用标准 `{code,data,message}` 信封。未知 operation 才 search，首次使用或 registry revision 变化时 describe；完整服务正文不进入 MCP 参数。
 
-有效 `app.Route` 会以实际 method、`/api/x/{slug}/{path}`、权限、风险和输入 schema 动态加入同一 MCP registry；搜索 `resource_type=custom_scripts` 或 `module=scripts_dynamic` 后描述并调用。运行时 Route 返回 handler 自定义响应，不强制使用管理 API 信封；精确匹配、调用身份和运行限制仍以本文件的 Route 与权限章节为准。
+有效 `app.Route` 会按实际 method 和 `/api/x/{slug}/{path}` 动态加入 MCP registry。运行时响应由 handler 决定，不强制管理 API 信封；精确匹配、身份继承和执行限制仍以本文件为准。
 
-## 验收清单
+## 完成条件
 
-- [ ] `package main` 且实现 `Register(app *sdk.App)`。
-- [ ] 服务使用 `mode=mixed`，第三方库写入 `go_mod`。
-- [ ] 路由使用 `app.Route`，事件使用 `app.On`，定时任务使用 `app.Schedule`。
-- [ ] handler 返回 `(any, error)`，需要状态码时使用 `draftgo.Respond`。
-- [ ] Route 显式设置 `permission` 与 `route_security`。
-- [ ] 保存或发布后请求无副作用 GET Route，并记录状态码和响应作为验收证据。
+- `package main` 且实现无业务副作用的 `Register(app *sdk.App)`。
+- `service.go`、`service.json` 齐全，handler 仅在 `Register` 注册，服务端状态字段未被手工伪造。
+- trigger 与 handler 签名正确，第三方依赖已锁定。
+- Route 权限、管理员调用和返回脱敏符合真实调用者范围。
+- `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},
@@ -152,8 +167,9 @@ await App.patch(`db/order/batch`, [
 
 ## db_meta 实时契约
 
-db_meta 是结构化远端资源，不 checkout，也不生成本地 `index.json`。开发前先通过 MCP
-`draftgo_api_search` / `draftgo_api_describe` 确认接口，再用 `draftgo_api_call` 查询目标 type 和 schema。
+db_meta 是结构化远端资源，不 checkout，也不生成本地索引。未知 operation 才通过 MCP
+`draftgo_api_search` 定位；首次使用或 registry revision 变化时 `draftgo_api_describe`，再用
+`draftgo_api_call` 查询目标 type 和 schema。
 典型返回条目如下：
 
 ```json

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。
+
+完成条件：本地检查通过，目标远端资源可回读，版本/哈希或结构化状态与预期一致，任务要求的运行或视觉证据齐全，且证据不含凭据。