draftgo-cli 3.0.55 → 4.0.1

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

@@ -1,19 +1,26 @@
 ---
-
 read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
 ---
 
 # Go 自定义服务契约
 
-DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`，可以使用标准库和 `go.mod` 中声明的第三方库。平台在保存或发布时编译服务、运行 `Register` 并保存触发器清单；执行时在独立子进程中调用选定 handler。
+自定义服务是完整的 Go `package main`。平台构建源码和 `go.mod`/`go.sum`，执行 `Register` 保存触发器清单，并在独立子进程中运行 handler。SDK 固定导入 `draftgo/sdk`；它由构建器注入，不写进 `require` 或 `replace`。
+
+## 开发流程
+
+完整正文使用：
 
-平台 SDK 的固定导入路径是 `draftgo/sdk`。它是 DraftGo 构建器注入的本地 module，不从 GitHub 或其他网络仓库下载，也不要在服务的 `go.mod` 中自行添加或 `replace` 此依赖。
+```bash
+draftgo checkout custom-services <id...>
+draftgo commit custom-services <id...>
+draftgo validate custom-services <id>
+draftgo test custom-services <id> [--handler route:POST:/path]
+draftgo publish custom-services <id...>
+```
 
-## 索引
+checkout 目录包含 `service.go`、`go.mod`、`go.sum`、`service.json` 及对应 base。commit 只保存共享 cloud draft；publish 才切换线上版本。定位、创建、权限和结构化元数据通过 MCP 实时 operation 完成，创建后取得 ID 再 checkout。
 
-- [最小服务](#最小服务)、[本地资源](#本地资源)、[触发器](#触发器)
-- [平台 SDK](#平台-sdk)、[AI 平台 SDK](#ai-平台-sdk)
-- [权限与运行限制](#权限与运行限制)、[实时 API](#实时-api)、[验收清单](#验收清单)
+不同服务可并发处理；同一服务保持 commit -> validate -> test/publish 顺序。草稿 revision 是内容版本，`validated_revision` / `validated_hash` 是该版本的验证凭证。保存会清空凭证；测试和发布必须使用当前 revision。CLI 会复用有效凭证，不重复 commit、checkout 或 validate。
 
 ## 最小服务
 
@@ -23,275 +30,107 @@ package main
 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)
+    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 afterPaid(draftgo *sdk.Context) (any, error) {
-	draftgo.Log.Info("order paid event received")
-	return nil, nil
+    return draftgo.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；网络请求、写数据库、发通知等操作放在 handler 内。
-
-## 资源读写
-
-自定义服务是结构化远端资源，不使用 checkout/commit，也没有约定的本地镜像目录。先用
-`draftgo_resource_search` 定位服务，再用 `draftgo_api_search` / `draftgo_api_describe` 获取当前管理接口契约，
-通过 `draftgo_api_call` 读取、创建或更新。Agent 可以在普通工作区文件中编写和检查 Go 源码，但不得把该文件
-误当作远端事实来源；写入时按实时契约显式发送代码和元数据。
-
-常见服务载荷字段如下，实际字段以 `draftgo_api_describe` 为准：
-
-```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": ""
-}
-```
-
-- 新服务使用 `mode=mixed`，允许同一个 `Register` 同时注册 route、event 和 scheduled。旧服务可继续使用单一 `route`、`event` 或 `scheduled` mode。
-- `go_mod` 和可选的 `go_sum` 随服务版本保存，并和代码一起通过实时管理 API 提交。
-- 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
+`Register` 只注册 handler，不访问网络、数据库或通知系统。新服务使用 `mode=mixed`；第三方依赖锁定明确版本并写入 `go.mod`，可选校验和写入 `go.sum`。
 
 ## 触发器
 
 ### Route
 
-```go
-func Register(app *sdk.App) {
-	app.Route("POST", "/orders", createOrder)
-}
-
-func createOrder(draftgo *sdk.Context) (any, error) {
-	body, _ := draftgo.Input["body"].(map[string]any)
-	return draftgo.Respond(body, 201, nil), nil
-}
-```
-
-`slug=commerce` 时地址为 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
+`app.Route("POST", "/orders", createOrder)` 在 `slug=commerce` 时对应 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
 
-`draftgo.Input` 的 Route 字段：`method`、`headers`、`body`、`query_params`、`path_params`。当前身份通过 `draftgo.Auth.CurrentUser()` 获取，入站请求头通过 `draftgo.Headers.Get("Authorization")` 等读取。
+输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `draftgo.Auth.CurrentUser()` 获取。普通 `draftgo.DB`、`Users` 等调用继承请求调用者权限；管理员创建服务、持有 SAT 或 `RequireAdmin` 都不会自动提升 SDK 调用。
 
-Route 默认以请求调用者身份访问 `draftgo.DB`、`draftgo.Users` 和其他平台能力。服务由管理员创建、拥有 `scripts:*` 管理权限，或在请求中收到 SAT，都不会让普通 SDK 调用自动提升；`draftgo.Auth.RequireAdmin()` 也只检查当前调用者。
-
-可信服务需要管理员权限时，逐次显式使用 `draftgo.Admin.*`。这不是服务配置项，也不需要 `admin_access` 开关：调用 `Admin` 就是管理员调用声明。运行时为**这一次**平台 SDK 调用注入管理员身份，并把服务、版本、真实调用者、操作、资源和结果写进该次执行的审计日志；SAT、数据库连接和管理员凭据不会暴露给服务代码。
-
-```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)
-}
-```
-
-`draftgo.Admin` 提供与普通 SDK 对齐的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub`、`Knowledge`、`Memory` 能力。它等价于管理员在平台拥有的权限，不做资源级白名单；因此只能授予可信服务编辑者，并且 Route 返回值仍必须由代码负责脱敏。
+可信服务需要管理员能力时逐次显式调用 `draftgo.Admin.*`。它只提升该次 RPC，并审计服务、版本、真实调用者、操作、资源和结果；服务代码拿不到 SAT、数据库连接或管理员凭据。Route 返回值仍需自行脱敏。
 
 ### 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` 为空对象。
+`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有调用者，以系统身份执行；仅可信编辑者可维护，并应限制写入范围、记录业务日志。
 
-定时任务没有调用者，会以系统身份执行。因此它只能由可信编辑者维护，写入范围应限制在明确的数据类型，并在 handler 中记录可审计的业务日志。
+## SDK
 
-## 平台 SDK
+所有平台访问通过受控 RPC 返回主服务，不自行读取宿主环境变量、数据库连接或 token。
 
-所有资源访问经受控 RPC 返回 Go 主服务。不要自行读取数据库连接、服务 token 或宿主机环境变量。
+| 入口 | 核心能力 |
+|---|---|
+| `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` | 长期记忆与全局检索配置 |
+
+常用示例：
 
 ```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",
+    Filters: map[string]any{"status": "paid"}, Page: 1, PageSize: 20,
+})
+reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
+    AgentID: 12, Message: "总结订单",
 })
-
-user, err := draftgo.Users.Get(12)
-err = draftgo.Auth.RequireLogin()
-err = draftgo.Notify.Send(12, "完成", "订单已创建", "info")
-
-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)
-
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{AgentID: 12, Message: "总结订单"})
-draftgo.Log.Info("service completed")
 ```
 
-`draftgo.DB` 支持 `Create`、`CreateMany`、`Get`、`Update`、`UpdateMany`、`Delete`、`Query`。`Query` 返回 `sdk.QueryResult{Items, Total, Page, PageSize}`。
+HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒，响应体最大 5 MB。日志每次执行最多 500 条、单条 4096 字符，不记录 token、Cookie、密码或完整个人信息。
 
-`draftgo.Users` 支持 `Get`、`List`、`Update`。`draftgo.Auth` 支持 `RequireLogin`、`RequireAdmin`、`RequireRole`、`CurrentUser`。
+### AI 权限
 
-`draftgo.HTTP` 支持 `Get`、`Post`、`Put`、`Patch`、`Delete`；响应为 `sdk.HTTPResponse{StatusCode, Headers, Data}`。服务可使用 `config.http_allowed_hosts` 限制出站目标；HTTP timeout 最终限制为 1-30 秒，响应体最大 5 MB。
+普通 AIHub/Knowledge/Memory 继承用户身份并经过 `aihub:*` 等权限。`draftgo.Admin.AIHub`、`Admin.Knowledge`、`Admin.Memory` 与普通入口同构，但逐次以管理员执行并审计。
 
-## AI 平台 SDK
-
-| 入口 | 能力 |
-|---|---|
-| `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` 提供同构接口，每次调用以管理员身份执行并进入自定义服务执行审计。
-
-### 推理与配置
-
-```go
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
-	AgentID: 12,
-	Message: "总结订单",
-})
-
-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"},
-})
-```
-
-`GenerateImage` 支持 Agent 和直接模型两种调用。普通入口的推理必须在服务 `config.aihub` 中显式开启：
+普通推理还必须在服务配置中启用：
 
 ```json
 {
   "aihub": {
     "enabled": true,
-    "allowed_agents": [12, 18],
+    "allowed_agents": [12],
     "allow_direct_model_call": true,
-    "allowed_models": ["gpt-4.1-mini", "text-embedding-3-small"],
+    "allowed_models": ["gpt-4.1-mini"],
     "allow_images": true
   }
 }
 ```
 
-空白名单表示不额外限制，但用户权限、Agent 调用权限和模型外部调用策略仍然生效。Agent 预览与后续新增的 `/api/v1/*` 推理端点也使用同一组白名单策略。
-
-### AI 资产、Skill 与 MCP
-
-Agent、Prompt、Skill、MCP 使用统一资产 CRUD，通过 `type` 区分：
-
-```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",
-})
-```
-
-资产方法包括 `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`。
-
-### 知识库与记忆
-
-```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,
-})
-```
-
-`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`。
-
-### 扩展入口
-
-typed helper 尚未覆盖新端点时，使用 `AIHub.Request`：
-
-```go
-value, err := draftgo.AIHub.Request(draftgo.Context(), sdk.AIRequest{
-	Method: "GET",
-	Path: "/api/aihub/types",
-})
-```
-
-`Request` 只接受 `/api/aihub`、`/api/agents`、`/api/v1`、`/api/images`、`/api/knowledge-bases`、`/api/memories`、`/api/skills` 路径；禁止外部 URL、路径穿越和在 `Path` 中拼 query。身份、权限、推理开关与审计规则和 typed helper 相同。
-
-日志每次执行最多 500 条、单条最多 4096 字符。不要记录 token、Cookie、密码或完整个人信息。
+空白名单表示不额外限制，不会绕过用户权限、Agent 调用权限或模型外部调用策略。typed helper 未覆盖的新端点可使用 `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` 控制服务管理。
+- Route 仍受服务 `permission` 与 `config.route_security` 控制。
+- 只有显式 `draftgo.Admin.*`、定时任务和无可解析用户的事件是提升身份例外。
+- `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)`。
+- trigger 与 handler 签名正确，第三方依赖已锁定。
+- Route 权限、管理员调用和返回脱敏符合真实调用者范围。
+- `draftgo validate` 通过；需要运行行为证据时执行相关 `draftgo test`。发布仅在用户任务包含发布时进行。

package/resources/skill/references/data.md

@@ -152,8 +152,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