draftgo-cli 4.0.23 → 4.0.25

package/README.md

@@ -75,6 +75,8 @@ draftgo connect [target...]
 
 `draftgo status` 会通过只读 MCP/API 诊断显示服务连接健康状态、服务版本和当前用户 API Key 的 `platform`/`space` 上下文；`--output json` 适合读取 `connection.health`、`workspace_id` 与 `space_id`。
 
+`draftgo update` 和 `draftgo update all` 只刷新项目中已经安装的 DraftGo Skill，不会因为检测到 `.cursor`、`AGENTS.md` 等工具痕迹而新增配置。显式指定 target 时（例如 `draftgo update cursor`），如果该 Skill 尚未安装，会按你的明确请求直接安装并更新它；首次接入也可以使用 `draftgo init <target>`。
+
 ### 发现与正文
 
 ```text
@@ -172,7 +174,7 @@ draftgo data-range list
 `role` 管理无作用域的 Role 模板；授权使用 `grant` 创建带 `platform` 或 `space` 范围的 AccessGrant。工作区成员关系不直接授予权限。资源归属由服务端持久化 ResourceOwnership 决定，DB 的 DataRange
 只在该范围内应用 `none`、`owner` 或 `all` 记录策略。交互式 CLI、MCP 和普通 HTTP API 均使用当前用户的
 API Key，并始终按该用户的 AccessGrant 授权；API Key 不能创建或伪造服务身份。CI、定时任务和共享服务等
-无人值守自动化使用平台提供的独立服务凭据通道及服务主体 AccessGrant，不复用个人 API Key。
+无人值守自动化由运行时使用 system 身份；定时和事件处理器没有调用者，必须在代码中显式使用 `ctx.Admin.*`，不创建服务主体 AccessGrant，也不复用个人 API Key。
 
 ### 交付与记录
 

package/bin/draftgo.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-'use strict';
-
-Promise.resolve(require('../src/index.js').run(process.argv.slice(2)))
-  .then((code) => { process.exitCode = Number(code) || 0; })
-  .catch((err) => {
-    console.error(err && err.stack ? err.stack : String(err));
-    process.exitCode = 1;
-  });
+'use strict';
+
+Promise.resolve(require('../src/index.js').run(process.argv.slice(2)))
+  .then((code) => { process.exitCode = Number(code) || 0; })
+  .catch((err) => {
+    console.error(err && err.stack ? err.stack : String(err));
+    process.exitCode = 1;
+  });

package/package.json

@@ -1,72 +1,72 @@
-{
-  "name": "draftgo-cli",
-  "version": "4.0.23",
-  "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro, Pi).",
-  "bin": {
-    "draftgo": "bin/draftgo.js"
-  },
-  "main": "src/index.js",
-  "engines": {
-    "node": ">=20.19"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "resources/",
-    "!resources/**/__pycache__/**",
-    "!resources/**/*.py[cod]",
-    "LICENSE",
-    "README.md"
-  ],
-  "keywords": [
-    "draftgo",
-    "skill",
-    "cli",
-    "claude-code",
-    "codex",
-    "cursor",
-    "windsurf",
-    "antigravity",
-    "copilot",
-    "gemini",
-    "kiro",
-    "pi"
-  ],
-  "author": "draftgo <cabinai@163.com> (https://github.com/draftgo)",
-  "license": "MIT",
-  "homepage": "https://github.com/draftgo/draftgo-cli#readme",
-  "bugs": {
-    "url": "https://github.com/draftgo/draftgo-cli/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/draftgo/draftgo-cli.git"
-  },
-  "scripts": {
-    "lint": "node scripts/check-syntax.js",
-    "validate:skill": "node scripts/validate-skill.js",
-    "sync:custom-service-sdk": "node scripts/sync-custom-service-sdk.js",
-    "build:release": "node scripts/build-release.js",
-    "verify:package": "node scripts/verify-package.js",
-    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:components && npm run test:capabilities && npm run test:workflow && npm run test:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && npm run test:local && npm run test:e2e",
-    "test:unit": "node tests/unit.js",
-    "test:components": "node --test tests/components.test.js",
-    "test:capabilities": "node --test tests/capabilities.test.js",
-    "test:workflow": "node tests/workflow.test.js",
-    "test:worklog": "node tests/worklog.test.js",
-    "test:mcp": "node tests/mcp.test.js",
-    "test:worktree": "node tests/worktree.test.js",
-    "test:integration": "node tests/integration.test.js",
-    "test:local": "node tests/local-runtime.js",
-    "test:e2e": "node tests/e2e.js"
-  },
-  "dependencies": {
-    "@grpc/grpc-js": "1.14.1",
-    "adm-zip": "0.5.16",
-    "parse5": "6.0.1",
-    "playwright-core": "1.61.1"
-  },
-  "directories": {
-    "test": "tests"
-  }
-}
+{
+  "name": "draftgo-cli",
+  "version": "4.0.25",
+  "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro, Pi).",
+  "bin": {
+    "draftgo": "bin/draftgo.js"
+  },
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "resources/",
+    "!resources/**/__pycache__/**",
+    "!resources/**/*.py[cod]",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "draftgo",
+    "skill",
+    "cli",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "antigravity",
+    "copilot",
+    "gemini",
+    "kiro",
+    "pi"
+  ],
+  "author": "draftgo <cabinai@163.com> (https://github.com/draftgo)",
+  "license": "MIT",
+  "homepage": "https://github.com/draftgo/draftgo-cli#readme",
+  "bugs": {
+    "url": "https://github.com/draftgo/draftgo-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/draftgo/draftgo-cli.git"
+  },
+  "scripts": {
+    "lint": "node scripts/check-syntax.js",
+    "validate:skill": "node scripts/validate-skill.js",
+    "sync:custom-service-sdk": "node scripts/sync-custom-service-sdk.js",
+    "build:release": "node scripts/build-release.js",
+    "verify:package": "node scripts/verify-package.js",
+    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:components && npm run test:capabilities && npm run test:workflow && npm run test:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && npm run test:local && npm run test:e2e",
+    "test:unit": "node tests/unit.js",
+    "test:components": "node --test tests/components.test.js",
+    "test:capabilities": "node --test tests/capabilities.test.js",
+    "test:workflow": "node tests/workflow.test.js",
+    "test:worklog": "node tests/worklog.test.js",
+    "test:mcp": "node tests/mcp.test.js",
+    "test:worktree": "node tests/worktree.test.js",
+    "test:integration": "node tests/integration.test.js",
+    "test:local": "node tests/local-runtime.js",
+    "test:e2e": "node tests/e2e.js"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "1.14.1",
+    "adm-zip": "0.5.16",
+    "parse5": "6.0.1",
+    "playwright-core": "1.61.1"
+  },
+  "directories": {
+    "test": "tests"
+  }
+}

package/resources/custom-service-sdk/auth_test.go

@@ -38,7 +38,7 @@ func TestAuthAssertionsUseHostAuthorization(t *testing.T) {
 	}
 
 	client.err = errors.New("denied by host")
-	if err := draftgo.Auth.RequireAdmin(); err == nil || err.Error() != "denied by host" {
+	if err := draftgo.Auth.RequireAdmin(); err == nil || err.Error() != "require_admin failed: denied by host" {
 		t.Fatalf("host denial was not returned: %v", err)
 	}
 }

package/resources/custom-service-sdk/manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "module": "draftgo/sdk",
-  "fingerprint": "94d0b5064c3d5c3d742ddf2856ed6e37196ff81bd16696aa88cd8267c3f57889",
+  "fingerprint": "4d0fc5d9b9dd8e0f3332fc1f61c544579d1d0bd1c96b39bc1a25006bb172bcc3",
   "files": [
     {
       "path": "ai.go",
@@ -15,8 +15,8 @@
     },
     {
       "path": "auth_test.go",
-      "sha256": "f0a02db739c8c5fa9d2856c59bd7ec823194cae50c1445f7b1340ce3dc0a616f",
-      "bytes": 1604
+      "sha256": "2905126322a678df82289ebf13c15f6595fb8def2f98cbd5bb53c406bf5ac31c",
+      "bytes": 1626
     },
     {
       "path": "billing.go",
@@ -35,8 +35,8 @@
     },
     {
       "path": "platform.go",
-      "sha256": "deb0ab4a91dbb9a1f07974982ffb218d89f719b3691cf5e9a955abcc86a6d2ba",
-      "bytes": 11923
+      "sha256": "cc696f69c3a8efe093968ea4f6bfea1f257944ebcd83591b5ffd75ae85a8b583",
+      "bytes": 12182
     },
     {
       "path": "platform_logger_test.go",
@@ -50,8 +50,8 @@
     },
     {
       "path": "resources.go",
-      "sha256": "e633aa1431beddd25b2c999370a770f77c3de7a2d7123687eca75c9ed0d3838f",
-      "bytes": 9708
+      "sha256": "78f465a598ace6dc2858fea4a448488d195a5d1a8dd3452465d73ce9727b6a72",
+      "bytes": 9761
     },
     {
       "path": "resources_billing_test.go",
@@ -65,13 +65,13 @@
     },
     {
       "path": "resources_scope_test.go",
-      "sha256": "bba3243f348e9418888f37ee2d5b487fc26a31e4a646e75bef46d5d807938cee",
-      "bytes": 3592
+      "sha256": "f9b19b592c0b2ddc0564715828fd840c974216f8e99e9690af43f2cf4a0d7fb5",
+      "bytes": 3870
     },
     {
       "path": "sdk.go",
-      "sha256": "b67db621642c389a2000e52b1640bacccf23a6d94f1fdcc1989e6a4244821924",
-      "bytes": 8224
+      "sha256": "18872d1f8535cdba53ddb3f487792cf74f10035f22a3023ec5cff3c3e597a8c0",
+      "bytes": 8342
     }
   ]
 }

package/resources/custom-service-sdk/platform.go

@@ -329,11 +329,11 @@ type authClient struct {
 func (a authClient) CurrentUser() map[string]any { return a.user }
 func (a authClient) RequireLogin() error {
 	_, err := a.call(a.context, "auth.require_login", map[string]any{})
-	return err
+	return authAssertionError("require_login", err)
 }
 func (a authClient) RequireAdmin() error {
 	_, err := a.call(a.context, "auth.require_admin", map[string]any{})
-	return err
+	return authAssertionError("require_admin", err)
 }
 func (a authClient) RequireRole(role string) error {
 	role = strings.TrimSpace(role)
@@ -341,5 +341,12 @@ func (a authClient) RequireRole(role string) error {
 		return errors.New("require_role failed: role is required")
 	}
 	_, err := a.call(a.context, "auth.require_role", map[string]any{"role": role})
-	return err
+	return authAssertionError("require_role", err)
+}
+
+func authAssertionError(assertion string, err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("%s failed: %w", assertion, err)
 }

package/resources/custom-service-sdk/resources.go

@@ -94,6 +94,7 @@ type ResourceContext struct {
 	ScopeType   string `json:"scope_type"`
 	WorkspaceID int64  `json:"workspace_id,omitempty"`
 	SpaceID     int64  `json:"space_id,omitempty"`
+	OwnerUserID int64  `json:"owner_user_id,omitempty"`
 }
 
 // ResourceOwnership identifies the persisted authorization boundary of a

package/resources/custom-service-sdk/resources_scope_test.go

@@ -16,7 +16,7 @@ func (client *scopeRecordingClient) Call(_ context.Context, operation string, ar
 	case "resource.context.current":
 		return map[string]any{"scope_type": ScopeSpace, "workspace_id": float64(2), "space_id": float64(8)}, nil
 	case "scope.principal.current":
-		return map[string]any{"subject_type": "service", "subject_id": "service:42", "username": "publisher", "is_admin": true}, nil
+		return map[string]any{"subject_type": "system", "subject_id": "0", "username": "System", "is_admin": true}, nil
 	default:
 		return map[string]any{"ok": true}, nil
 	}
@@ -38,7 +38,7 @@ func TestScopeClientUsesResourceAndPermissionOperations(t *testing.T) {
 	if err != nil || recorder.operation != "scope.principal.current" {
 		t.Fatalf("principal operation=%q err=%v", recorder.operation, err)
 	}
-	if principal.SubjectType != "service" || principal.SubjectID != "service:42" || principal.Username != "publisher" || !principal.IsAdmin {
+	if principal.SubjectType != "system" || principal.SubjectID != "0" || principal.Username != "System" || !principal.IsAdmin {
 		t.Fatalf("principal=%#v", principal)
 	}
 
@@ -75,13 +75,18 @@ func TestContextCarriesPersistedResourceAndPrincipal(t *testing.T) {
 	recorder := &scopeRecordingClient{}
 	ctx := NewContextWithResource(context.Background(), nil, nil, nil, recorder,
 		ResourceContext{ScopeType: ScopeSpace, WorkspaceID: 11, SpaceID: 13},
-		ScopePrincipal{SubjectType: "service", SubjectID: "custom-service:7", Username: "Service-Script"})
-	if ctx.Platform || ctx.WorkspaceID != 11 || ctx.SpaceID != 13 || ctx.Principal.SubjectID != "custom-service:7" {
+		ScopePrincipal{SubjectType: "system", SubjectID: "0", Username: "System"})
+	if ctx.Platform || ctx.WorkspaceID != 11 || ctx.SpaceID != 13 || ctx.Principal.SubjectID != "0" {
 		t.Fatalf("runtime context = %+v", ctx)
 	}
 	platform := NewContextWithResource(context.Background(), nil, nil, nil, recorder,
-		ResourceContext{ScopeType: ScopePlatform}, ScopePrincipal{SubjectType: "service", SubjectID: "custom-service:8"})
+		ResourceContext{ScopeType: ScopePlatform}, ScopePrincipal{SubjectType: "system", SubjectID: "0"})
 	if !platform.Platform || platform.WorkspaceID != 0 || platform.SpaceID != 0 {
 		t.Fatalf("platform runtime context = %+v", platform)
 	}
+	personal := NewContextWithResource(context.Background(), nil, nil, nil, recorder,
+		ResourceContext{ScopeType: "user", OwnerUserID: 17}, ScopePrincipal{SubjectType: "system", SubjectID: "0"})
+	if personal.Platform || personal.OwnerUserID != 17 || personal.WorkspaceID != 0 || personal.SpaceID != 0 {
+		t.Fatalf("personal runtime context = %+v", personal)
+	}
 }

package/resources/custom-service-sdk/sdk.go

@@ -106,6 +106,7 @@ type Context struct {
 	Platform    bool           `json:"platform"`
 	WorkspaceID int64          `json:"workspace_id,omitempty"`
 	SpaceID     int64          `json:"space_id,omitempty"`
+	OwnerUserID int64          `json:"owner_user_id,omitempty"`
 	Principal   ScopePrincipal `json:"principal"`
 
 	DB        Database   `json:"-"`
@@ -137,7 +138,7 @@ func NewContext(draftgo context.Context, input, user map[string]any, headers htt
 }
 
 // NewContextWithResource constructs a handler context with persisted resource
-// ownership and the service principal supplied by DraftGo. Custom services
+// ownership and the verified caller/system principal supplied by DraftGo. Custom services
 // cannot override these values through Input or request headers.
 func NewContextWithResource(draftgo context.Context, input, user map[string]any, headers http.Header, client Client, resource ResourceContext, principal ScopePrincipal) *Context {
 	if draftgo == nil {
@@ -150,7 +151,7 @@ func NewContextWithResource(draftgo context.Context, input, user map[string]any,
 	adminPlatform := platformClient{client: client, context: draftgo, admin: true}
 	return &Context{
 		Input: input, User: user, Headers: headers, context: draftgo,
-		Platform: resource.ScopeType == ScopePlatform, WorkspaceID: resource.WorkspaceID, SpaceID: resource.SpaceID, Principal: principal,
+		Platform: resource.ScopeType == ScopePlatform, WorkspaceID: resource.WorkspaceID, SpaceID: resource.SpaceID, OwnerUserID: resource.OwnerUserID, Principal: principal,
 		DB: dbClient{platform}, Users: usersClient{platform}, Auth: authClient{platformClient: platform, user: user}, Notify: notifierClient{platform},
 		HTTP: httpClient{platform}, Cache: cacheClient{platform}, Config: configClient{platform}, AIHub: aiHubClient{platform},
 		Knowledge: knowledgeClient{platform}, Memory: memoryClient{platform}, Files: fileStoreClient{platform}, Scope: scopeClient{platform}, Billing: billingClient{platform},
@@ -165,7 +166,7 @@ func NewContextWithResource(draftgo context.Context, input, user map[string]any,
 }
 
 // Admin exposes explicitly elevated platform capabilities to trusted custom
-// services. The runtime preserves the service subject, scopes elevation to one
+// services. The runtime uses a system principal (actor_id=0), scopes elevation to one
 // audited RPC call, and never exposes platform credentials.
 type Admin struct {
 	DB        Database

package/resources/skill/SKILL.md

@@ -47,7 +47,7 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 - 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；不同资源、operation 和 owner 不冲突的单元可以并发，不设置客户端并发上限；同一资源的依赖步骤保持串行。主 Agent 负责 owner 分配、汇总、验证、交付和 worklog 状态。
 - 用户 API Key 只保存在 `.draftgo/config.json`，不得进入宿主配置、命令参数、Skill、日志、manifest 或错误消息。宿主 MCP 配置只运行 `draftgo mcp serve`。
 - 页面优先使用可信本地资源；禁止境外 CDN。净化不可信 HTML，关键状态不能只靠颜色或动效表达。页面通过 `window.parent.App` 使用认证、权限、反馈和主题；详细规则见前端与运行时 Reference。
-- 普通自定义服务 SDK 调用继承调用者、服务归属和 AccessGrant；`ctx.Admin.*` 是仅供自定义服务显式选择的单次系统内部授权，按 `*:*:all` 全权限执行并进入审计，不会泄漏到后续调用。高风险 MCP operation 仅在用户意图明确且影响范围已核对时设置 `confirm=true`。
+- Route 普通自定义服务 SDK 调用继承真实调用者和服务归属；Event/Scheduled 没有调用者，普通 `ctx.xxx` 返回 403，必须显式使用 `ctx.Admin.*`。Admin RPC 使用 system actor_id=0，按 `*:*:all` 单次执行并进入审计，不创建服务主体 AccessGrant，也不会泄漏到后续调用。
 - `.draftgo/tmp/` 可清理；先运行 `draftgo clean --dry-run`，再在需要时使用 `--yes`。用户可查验的证据放入已注册的 `.draftgo/artifacts/`。
 
 ## 完成条件

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "4.0.23",
+  "version": "4.0.25",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/aihub.md

@@ -1,7 +1,7 @@
----
-read_when: 创建或调优 AI Agent 时 · 需要工具/子智能体/记忆/多轮/结构化输出/多模态时
----
-
+---
+read_when: 创建或调优 AI Agent 时 · 需要工具/子智能体/记忆/多轮/结构化输出/多模态时
+---
+
 # AIHub / Agent 资源
 
 ## 最短管理流程
@@ -24,86 +24,86 @@ AIHub 与知识库是独立权限域：Agent、模型和 AI 运行使用 `aihub:
 
 AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先使用 MCP `draftgo_resource_search`/`draftgo_resource_list`
 定位资产；未知 operation 才用 `draftgo_api_search`，首次使用或 registry revision 变化时 `draftgo_api_describe`，然后通过 `draftgo_api_call` 读写。
-更新 AIHub 资产时只发送实时契约允许的字段；常见字段包括
-`type, name, data, priority, version, tags, describe, permission, status`。供应商和模型使用各自的实时接口，
-不要经旧 AIHub 资产接口写入。任何输出、工作区文件或调用参数都不得保存 API Key 或 header 值；只可处理
-“是否已配置”以及 header 名称等非秘密元数据。
-**Agent 的全部行为都在 `data`（尤其 `data.spec`）里**——本页就是 `data.spec` 的字段地图。
-
-## 条目骨架
-
-```jsonc
-{
-  "type": "agent",                 // AIHub 资产类型
-  "name": "产品顾问",
-  "describe": "面向用户的产品答疑助手",
-  "status": "active",
-  "data": {
-    "mode": "chat",                // chat | image_generation
-    "spec": { /* 见下表 */ }
-  }
-}
-```
-
-页面对话 UI 使用 `<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID">` 或 `DraftGoChat.create()`；
-旧代码/无 UI 文本调用可用 `DraftGoAI.chat(...)`，图片模式使用 `DraftGoAI.images(...)`。调用前都必须加载
+更新 AIHub 资产时只发送实时契约允许的字段；常见字段包括
+`type, name, data, priority, version, tags, describe, permission, status`。供应商和模型使用各自的实时接口，
+不要经旧 AIHub 资产接口写入。任何输出、工作区文件或调用参数都不得保存 API Key 或 header 值；只可处理
+“是否已配置”以及 header 名称等非秘密元数据。
+**Agent 的全部行为都在 `data`（尤其 `data.spec`）里**——本页就是 `data.spec` 的字段地图。
+
+## 条目骨架
+
+```jsonc
+{
+  "type": "agent",                 // AIHub 资产类型
+  "name": "产品顾问",
+  "describe": "面向用户的产品答疑助手",
+  "status": "active",
+  "data": {
+    "mode": "chat",                // chat | image_generation
+    "spec": { /* 见下表 */ }
+  }
+}
+```
+
+页面对话 UI 使用 `<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID">` 或 `DraftGoChat.create()`；
+旧代码/无 UI 文本调用可用 `DraftGoAI.chat(...)`，图片模式使用 `DraftGoAI.images(...)`。调用前都必须加载
 `/assets/draftgo-chat.js`，完整用法见 `references/chat-sdk.md`。后端 operation 与可调用 Agent 列表通过 MCP 实时确认；已知契约可复用项目缓存。
-
-## `data.spec` 字段地图
-
-留空即维持默认/旧行为；除标注外都是可选。运行时统一在 `parseOrchestrationConfig` + 就地读取时带默认值与 clamp。
-
-| 字段 | 类型 / 取值 | 说明 |
-|---|---|---|
+
+## `data.spec` 字段地图
+
+留空即维持默认/旧行为；除标注外都是可选。运行时统一在 `parseOrchestrationConfig` + 就地读取时带默认值与 clamp。
+
+| 字段 | 类型 / 取值 | 说明 |
+|---|---|---|
 | `mode` | `chat` / `image_generation` | 决定主要交互形态；具体 Responses、Embedding、Rerank、TTS、ASR、Video operation 以 MCP 和模型 capability 为准 |
-| `model` | string | 主模型（逻辑模型名，映射到供应商路由） |
-| `fallback_models` | string[] | 主模型失败后按序回退（跨模型 failover） |
-| `model_selection.user_selectable` | bool | 是否允许调用方在请求里覆盖 `model`（配合 `selectable-models`） |
-| `ttft_timeout` | number（秒，1–600，空=不启用） | 首字超时 failover：首个 SSE data 事件超时即跨模型+跨供应商切换，推理模型不误杀 |
+| `model` | string | 主模型（逻辑模型名，映射到供应商路由） |
+| `fallback_models` | string[] | 主模型失败后按序回退（跨模型 failover） |
+| `model_selection.user_selectable` | bool | 是否允许调用方在请求里覆盖 `model`（配合 `selectable-models`） |
+| `ttft_timeout` | number（秒，1–600，空=不启用） | 首字超时 failover：首个 SSE data 事件超时即跨模型+跨供应商切换，推理模型不误杀 |
 | `sync_request_timeout` | number（秒，1–600，默认 100） | 非流式请求上限 |
 | `stream_ttl` | number（秒，1–3600，默认 600） | 流式请求上限 |
 | `max_tokens` | number / 空 | 最大输出 token；留空时不写入请求，即不由 Agent 额外限制 |
 | `reasoning_effort` | `off`/`minimal`/`low`/`medium`/`high` | `off`/留空均不透传；其它值仅 OpenAI 系模型生效 |
-| `system_prompt_template` | string | 系统提示模板 |
-| `context.max_history` | number（默认 20） | 工作窗口：保留最近 N 条；关闭持续对话时即滑动窗口硬上限 |
-| `output_format.mode` | `text` / `json` | JSON 时按 `output_format.json.{schema,schema_name,strategy}` 约束/校验/降级 |
-| `capabilities.vision.{enabled,input,max_mb}` | 见值 | 图片/视觉输入（`image_url` part），`input`⊂{base64,url}，默认 5MB |
-| `capabilities.files.{enabled,allowed_ext,max_mb}` | 见值 | 文件附件抽取成文本注入；白名单 `.txt .md .docx .pdf .xlsx .json .csv`（pptx 不支持），默认 8MB |
-| `tools.max_iterations` | 1–50（默认 10） | ReAct 工具循环步数上限 |
-| `tools.sources[].{type,id}` | `mcp` / `custom_script` | 绑定 MCP 与「自定义服务作为工具」 |
-| `knowledge_base_ids` | int[] | 绑定知识库，生成检索工具 |
-| `skills` | 见运行时 | 绑定 Skill |
-| `sub_agent_ids` | int[] | 子智能体：为每个 id 生成 `agent_{id}` 委派工具（用法同 `knowledge_base_ids`） |
+| `system_prompt_template` | string | 系统提示模板 |
+| `context.max_history` | number（默认 20） | 工作窗口：保留最近 N 条；关闭持续对话时即滑动窗口硬上限 |
+| `output_format.mode` | `text` / `json` | JSON 时按 `output_format.json.{schema,schema_name,strategy}` 约束/校验/降级 |
+| `capabilities.vision.{enabled,input,max_mb}` | 见值 | 图片/视觉输入（`image_url` part），`input`⊂{base64,url}，默认 5MB |
+| `capabilities.files.{enabled,allowed_ext,max_mb}` | 见值 | 文件附件抽取成文本注入；白名单 `.txt .md .docx .pdf .xlsx .json .csv`（pptx 不支持），默认 8MB |
+| `tools.max_iterations` | 1–50（默认 10） | ReAct 工具循环步数上限 |
+| `tools.sources[].{type,id}` | `mcp` / `custom_script` | 绑定 MCP 与「自定义服务作为工具」 |
+| `knowledge_base_ids` | int[] | 绑定知识库，生成检索工具 |
+| `skills` | 见运行时 | 绑定 Skill |
+| `sub_agent_ids` | int[] | 子智能体：为每个 id 生成 `agent_{id}` 委派工具（用法同 `knowledge_base_ids`） |
 | `call_permissions` | 角色配置 | 哪些角色可以调用此 Agent；调用接口与筛选条件以 MCP 实时契约为准 |
 | `billing_mode` | `disabled` / `inherit_model` / `per_call` / `usage` | Agent 零售计费；公开 Agent 强制 `disabled`，订阅/会员额度由业务服务管理 |
-
-### `orchestration.*`（编排开关）
-
-| 字段 | 默认 | 说明 |
-|---|---|---|
-| `tool_concurrency` | 8（1–32） | 单步内并发执行工具数 |
-| `on_max_steps` | `error` | 达步数上限：`error` 报错 / `stop` 返回最后一条 |
-| `tool_disclosure.{mode,threshold_tools}` | `off` | 工具渐进披露：`off`/`auto`/`always`，首轮只给目录+`load_tools` |
-| `planning.{enabled,prompt}` | false | 规划层：执行前先让模型列步骤，提示折叠进 system |
-| `memory.{enabled,scope}` | false / `user_agent` | 长期记忆：对话后自动提炼、下轮召回注入；作用域 `agent`/`user`/`user_agent` |
-| `compaction.{enabled,keep_recent,trigger_messages,trigger_tokens,preset}` | 关闭 | **持续对话/上下文闭环**：见下 |
-| `checkpoint_input_mode` / `checkpoint_max_messages` / `checkpoint_ttl_seconds` | 全量 / 100 / 86400 | 会话历史持久化（配合请求 `session_id`） |
+
+### `orchestration.*`（编排开关）
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `tool_concurrency` | 8（1–32） | 单步内并发执行工具数 |
+| `on_max_steps` | `error` | 达步数上限：`error` 报错 / `stop` 返回最后一条 |
+| `tool_disclosure.{mode,threshold_tools}` | `off` | 工具渐进披露：`off`/`auto`/`always`，首轮只给目录+`load_tools` |
+| `planning.{enabled,prompt}` | false | 规划层：执行前先让模型列步骤，提示折叠进 system |
+| `memory.{enabled,scope}` | false / `user_agent` | 长期记忆：对话后自动提炼、下轮召回注入；作用域 `agent`/`user`/`user_agent` |
+| `compaction.{enabled,keep_recent,trigger_messages,trigger_tokens,preset}` | 关闭 | **持续对话/上下文闭环**：见下 |
+| `checkpoint_input_mode` / `checkpoint_max_messages` / `checkpoint_ttl_seconds` | 全量 / 100 / 86400 | 会话历史持久化（配合请求 `session_id`） |
 | `delegation.{max_depth,max_total_calls}` | 2 / 8 | 最大嵌套层数与整棵调用树共享的子 Agent 调用次数；并行分支也从同一预算扣减 |
 
 同一模型步骤返回多个子 Agent 工具调用时，运行时立即按 `tool_concurrency` 并发执行；不同步骤自然串行，由模型自行决定编排方式。委派成功后，子 Agent 的每个模型回合 token 会汇总到入口 run，总量也写入对应委派 span。一次入口请求只创建一条主 run，Agent 列归属入口 Agent，委派链路从 span 查看。
-
-### 持续对话（上下文闭环）
-
-- `compaction.enabled=true` = 闭环：填满工作窗口后把溢出旧消息**摘要成一条滚动 summary** 续接，
-  而非直接丢弃。此时后端**跳过 `context.max_history` 硬砍**，让完整 checkpoint 历史进入压缩器蒸馏。
-- 触发为双通道任一命中：`trigger_messages`（条数）或 `trigger_tokens`（估算 token，256–2000000）。
-- `keep_recent`：保留最近 N 条不压缩。`preset`（`aggressive`/`balanced`/`conservative`）是管理台档位回显，
-  后端只认 `keep_recent`/`trigger_messages`/`trigger_tokens` 三个底层字段。
-- 配合请求体 `session_id` 才会加载/续写会话历史；`<dg-chat>` 为每个 UI thread 自动维护该值，兼容门面可通过 `DraftGoAI.chat(..., {sessionId})` 显式传入。不传即无状态单轮。
-- 关闭时逐字回退为 `max_history` 滑动窗口（旧行为，零影响）。
-
-## 观测
-
+
+### 持续对话（上下文闭环）
+
+- `compaction.enabled=true` = 闭环：填满工作窗口后把溢出旧消息**摘要成一条滚动 summary** 续接，
+  而非直接丢弃。此时后端**跳过 `context.max_history` 硬砍**，让完整 checkpoint 历史进入压缩器蒸馏。
+- 触发为双通道任一命中：`trigger_messages`（条数）或 `trigger_tokens`（估算 token，256–2000000）。
+- `keep_recent`：保留最近 N 条不压缩。`preset`（`aggressive`/`balanced`/`conservative`）是管理台档位回显，
+  后端只认 `keep_recent`/`trigger_messages`/`trigger_tokens` 三个底层字段。
+- 配合请求体 `session_id` 才会加载/续写会话历史；`<dg-chat>` 为每个 UI thread 自动维护该值，兼容门面可通过 `DraftGoAI.chat(..., {sessionId})` 显式传入。不传即无状态单轮。
+- 关闭时逐字回退为 `max_history` 滑动窗口（旧行为，零影响）。
+
+## 观测
+
 每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
 运行记录接口通过 MCP 实时发现，不维护静态路径表；已知 operation 复用 registry revision 未变化的契约缓存。
 
@@ -112,5 +112,5 @@ profile、transport readiness 和实际 route；不要只根据供应商名称
 能力名大小写敏感，使用实时 describe 返回的 canonical 值，不使用历史别名。
 
 Agent 对外响应（`/api/agents/{id}/chat`、图片接口、Go/Script SDK Agent 调用）不返回内部 `model`、`fallback_models` 或 `upstream_model`；错误也不暴露内部模型名、供应商名称、服务地址或运行时实现名。只有显式启用 `model_selection.user_selectable` 后，`/selectable-models` 才作为授权的模型选择目录返回可选逻辑模型名。运行日志仍在服务端保留真实模型、供应商与链路信息用于定位。
-
+
 > 权威细节以 DraftGo `docs/modules/ai-platform/agent-runtime.md` 和实时 MCP schema 为准；本页是基座开发者视角的字段速查。