@doubao-dev/cli 1.0.0-rc.1 → 1.0.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +12 -6
  2. package/dist/691.js +96 -0
  3. package/dist/build.js +1 -0
  4. package/dist/categories.js +1 -1
  5. package/dist/command.js +9 -3
  6. package/dist/command~1.js +4 -4
  7. package/dist/command~2.js +1 -1
  8. package/dist/command~3.js +2 -1
  9. package/dist/command~4.js +1 -1
  10. package/dist/command~5.js +6 -5
  11. package/dist/dist.js +1 -1
  12. package/dist/draft.js +2 -2
  13. package/dist/index.d.ts +886 -8
  14. package/dist/index.js +1 -1
  15. package/dist/main.d.ts +886 -8
  16. package/dist/main.js +1 -1
  17. package/dist/mcp-apps-inspector.js +1 -0
  18. package/dist/multipart-parser.js +1 -1
  19. package/dist/open.js +2 -0
  20. package/dist/plugin.js +2 -2
  21. package/dist/preview.js +5 -5
  22. package/dist/progress.js +1 -1
  23. package/dist/ratatui-ui.js +1 -1
  24. package/dist/session.js +1 -1
  25. package/dist/skills/doubao-plugin-cli/SKILL.md +44 -40
  26. package/dist/skills/doubao-plugin-cli/references/cli/development.md +126 -0
  27. package/dist/skills/doubao-plugin-cli/references/cli/project.md +188 -0
  28. package/dist/skills/doubao-plugin-cli/references/cli/release.md +144 -0
  29. package/dist/skills/doubao-plugin-cli/references/examples/todo-example.md +88 -0
  30. package/dist/skills/doubao-plugin-cli/references/examples/workbench-example.md +130 -0
  31. package/dist/skills/doubao-plugin-cli/references/protocols/business-skills.md +49 -0
  32. package/dist/skills/doubao-plugin-cli/references/protocols/cli-connectors.md +56 -0
  33. package/dist/skills/doubao-plugin-cli/references/protocols/managed-agents.md +46 -0
  34. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/integration.md +186 -0
  35. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/runtime.md +318 -0
  36. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/workbench.md +180 -0
  37. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-auth.md +73 -0
  38. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-config.md +145 -0
  39. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-events.md +260 -0
  40. package/dist/skills/doubao-plugin-cli/references/protocols/plugin-json.md +95 -0
  41. package/dist/skills/doubao-plugin-cli/references/protocols/workbench.md +120 -0
  42. package/dist/skills/doubao-plugin-cli/references/upstream/SOURCES.md +24 -0
  43. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.LICENSE +216 -0
  44. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.mdx +1768 -0
  45. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.LICENSE +216 -0
  46. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.md +1231 -0
  47. package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.LICENSE +201 -0
  48. package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.md +349 -0
  49. package/dist/templates/standard/AGENTS.md +1 -1
  50. package/dist/templates/workbench/README.md.template +9 -0
  51. package/dist/templates/workbench/com.doubao/workbench/manifest.json +10 -0
  52. package/dist/uninstall.js +1 -1
  53. package/dist/versions~1.js +1 -1
  54. package/dist/web/index.html +1 -0
  55. package/dist/web/sandbox-proxy.html +101 -0
  56. package/dist/web/static/css/index.b3102f16b9.css +1 -0
  57. package/dist/web/static/js/155.747f5232dc.js +69 -0
  58. package/dist/web/static/js/async/970.86106314b5.js +1 -0
  59. package/dist/web/static/js/index.c1186260b9.js +4 -0
  60. package/dist/web/static/js/lib-react.00514652bf.js +2 -0
  61. package/dist/web/static/js/lib-react.00514652bf.js.LICENSE.txt +39 -0
  62. package/dist/workbench-search.js +1 -0
  63. package/dist/xdg-open +1267 -0
  64. package/package.json +14 -15
  65. package/dist/21.js +0 -101
  66. package/dist/schema.js +0 -1
  67. package/dist/skills/doubao-plugin-cli/references/cli-connectors.md +0 -29
  68. package/dist/skills/doubao-plugin-cli/references/development.md +0 -29
  69. package/dist/skills/doubao-plugin-cli/references/mcp-apps.md +0 -40
  70. package/dist/skills/doubao-plugin-cli/references/mcp-auth.md +0 -23
  71. package/dist/skills/doubao-plugin-cli/references/project-config.md +0 -139
  72. package/dist/skills/doubao-plugin-cli/references/upload.md +0 -77
  73. /package/dist/{21.js.LICENSE.txt → 691.js.LICENSE.txt} +0 -0
@@ -0,0 +1,318 @@
1
+ # MCP Apps 运行时
2
+
3
+ 定义 App 与 Host 之间的消息、模型上下文、资源及身份扩展。界面接入见 [MCP Apps](integration.md),导航、多服务调用与 Home 见 [Workbench](workbench.md#导航与-workbench)。
4
+
5
+ ## 基础协议与适用范围
6
+
7
+ 初始化、JSON-RPC、标准消息、模型上下文和 Host Context 通知沿用 [MCP Apps 基础规范](../../upstream/mcp-apps.mdx#communication-protocol),固定版本见[上游来源](../../upstream/SOURCES.md)。本页完整定义豆包接入中的增量字段及行为,不改变标准方法名。
8
+
9
+ `target` / `send`、`updateId` 和资源元数据属于 OpenAI 扩展兼容范围;`doubao/*` 别名、消息结果状态、业务上下文和身份申请属于豆包适配。别名及冲突规则统一见下节。文档中的能力、字段版本与 SDK 包版本分别判断,不能由 SDK 导出的方法推断 Host 已实现。
10
+
11
+ | 任务 | 本页章节 |
12
+ | --- | --- |
13
+ | 发消息、追加草稿或创建新会话 | [消息扩展](#消息扩展) |
14
+ | 更新模型上下文、读取确认结果 | [模型上下文扩展](#模型上下文扩展) |
15
+ | 读取文本、二进制资源及元数据 | [资源读取扩展](#资源读取扩展) |
16
+ | 获取当前实例、会话、文件及身份快照 | [应用上下文](#应用上下文)、[身份资料权限](#app-身份资料权限) |
17
+ | 处理失败、失效或不兼容 Host | [错误、限额与生命周期](#错误限额与生命周期) |
18
+
19
+ ## 运行时能力与命名空间
20
+
21
+ App 在连接前注册结果及 Host Context 监听,`connect()` 成功后检查能力并读取初始快照。后续变化通过 `ui/notifications/host-context-changed` 接收;只监听变化会漏掉初始化时已有的数据。
22
+
23
+ 以下能力由 `ui/initialize` 返回的 `hostCapabilities` 声明:标准键直接位于该对象;带命名空间的扩展键位于其 `experimental` 对象。它们不同于 `com.doubao/ui` 的 MCP Server 协商。
24
+
25
+ | 能力 | 发布条件与调用边界 |
26
+ | --- | --- |
27
+ | `serverTools` | 有工具处理器;标准 `tools/call` 仅访问绑定 Server |
28
+ | `serverResources` | 同时有资源列表、模板列表和读取处理器;标准资源接口及扩展只读 helper 据此启用 |
29
+ | `message` | 有消息处理器,并按返回的内容类型能力逐块判断;旧 Adapter 无类型表时仅支持文本 |
30
+ | `updateModelContext` | 有处理器;按实际内容类型能力提交,扩展语义另行协商 |
31
+ | `openLinks` / `downloadFile` | 分别存在对应处理器 |
32
+ | `openai/message` / `doubao/message` | 有相应消息处理器及扩展语义;部分 Adapter 只支持 draft 或 newConversation,不支持的语义必须拒绝 |
33
+ | `openai/modelContext` / `doubao/modelContext` | 有处理器及完整扩展语义,才可依赖确认 ID 和上下文回显 |
34
+ | `doubao/workbench` | 两个处理器均存在时发布 `{startupClaims:true,serverRouting:true}`;两个方法仍分别检查自己的布尔标记 |
35
+
36
+ `doubao/context`、`doubao/home` 和 deepLink 状态借用 Host Context 通道;当前没有独立 Home 或导航 capability marker。资源读取依据标准 `serverResources`,不存在必须等待的 `experimental["doubao/resource"]` 标记。
37
+
38
+ 调用扩展前检查所用命名空间的真实能力,不依据另一命名空间的能力发送请求。SDK 中存在方法或类型不构成 Host 支持证据。
39
+
40
+ `openai/*` 与 `doubao/*` 的别名只覆盖明确允许的键:`ui` 单独解析;`message`、`modelContext`、`resource`、`deepLink`、`group`、`title`、`thumbnail` 按各自契约处理。互补对象递归合并;同路径标量和数组必须等价,冲突直接拒绝,默认值在冲突检查后应用。不能靠 `doubao/*` 覆盖冲突值,也不能任意替换前缀。
41
+
42
+ `context`、`home`、`permissions`、消息结果 `status`、`input-content` 和 URL source 属于豆包专有字段。Profile 仅定义 `openai/profile`。资源搜索有独立的发现优先级,见[Profile 与资源搜索](../mcp-config.md#profile-与资源搜索)。
43
+
44
+ ## 消息与模型上下文
45
+
46
+ 标准方法分别为 `ui/message` 和 `ui/update-model-context`;前者操作聊天输入,后者更新供模型读取的 App 上下文。两者不是同一动作,消息扩展见下节,上下文确认见[模型上下文扩展](#模型上下文扩展)。
47
+
48
+ ## 消息扩展
49
+
50
+ ### 能力与请求
51
+
52
+ Host 必须提供标准 `message` 能力,并支持所使用命名空间的消息扩展语义。App 按 `hostCapabilities.message` 的内容类型逐块检查;部分 Adapter 仅支持草稿或新会话,不支持的操作必须拒绝,不能将草稿降级为发送。
53
+
54
+ 方法仍为 `ui/message`。`role: "user"` 和 `content: ContentBlock[]` 沿用标准;扩展对象位于 `params._meta["doubao/message"]`,也接受已协商的 `openai/message` 同义键。
55
+
56
+ | 字段 | 类型 | 必填 | 缺省语义 |
57
+ | --- | --- | --- | --- |
58
+ | `target` | `"active"` 或 `"new"` | 否 | `active`:使用当前绑定会话 |
59
+ | `send` | boolean | 否 | `true`:提交本次 App 内容 |
60
+
61
+ ### 执行语义
62
+
63
+ | target | send | Host 行为 |
64
+ | --- | --- | --- |
65
+ | active | true | 提交到当前绑定会话 |
66
+ | active | false | 追加到当前草稿,保留已有用户草稿 |
67
+ | new | true | 等待新会话就绪后提交 |
68
+ | new | false | 等待新会话就绪后追加草稿 |
69
+
70
+ 请求中的“当前”是调用方的可信会话绑定,不能自行替换为其他可见会话。Host 等待输入层完成后返回操作状态。
71
+
72
+ ### 响应
73
+
74
+ 结果对象位于 `result._meta["doubao/message"]`,没有对应的 `openai/message` 结果状态别名。
75
+
76
+ | 字段 | 类型 | 含义 |
77
+ | --- | --- | --- |
78
+ | `status` | `"drafted"` / `"submitted"` / `"cancelled"` | 草稿已追加、消息已提交或操作取消 |
79
+ | `conversationId` | string,可选 | 实际目标会话标识,可能是本地会话标识;不得自行生成或假定为服务端 ID |
80
+
81
+ `drafted` 不表示发送成功;`submitted` 不表示模型已回复或后续服务端持久化全部完成;`cancelled` 不作为成功提交,也不触发自动再次提交。
82
+
83
+ ### 完整交互示例
84
+
85
+ 向当前会话追加草稿:
86
+
87
+ ```json
88
+ {
89
+ "jsonrpc": "2.0",
90
+ "id": 1,
91
+ "method": "ui/message",
92
+ "params": {
93
+ "role": "user",
94
+ "content": [{ "type": "text", "text": "请分析这份计划的延期风险。" }],
95
+ "_meta": { "doubao/message": { "target": "active", "send": false } }
96
+ }
97
+ }
98
+ ```
99
+
100
+ 输入层完成后返回:
101
+
102
+ ```json
103
+ {
104
+ "jsonrpc": "2.0",
105
+ "id": 1,
106
+ "result": { "_meta": { "doubao/message": { "status": "drafted" } } }
107
+ }
108
+ ```
109
+
110
+ 使用新会话时将 `target` 改为 `new`;是否提交仍由 `send` 独立决定。调用限额与执行未知的恢复规则见[错误、限额与生命周期](#错误限额与生命周期),不能因超时直接重放消息。
111
+
112
+ `params._meta["doubao/input-content"]` 是 Host 业务桥接的归一化 DTO。普通 App 使用标准 content;内部 AttachmentItem、实体和渲染 DTO 由其拥有者维护,不在本协议中另建副本。
113
+
114
+ ## 模型上下文扩展
115
+
116
+ ### 请求与确认
117
+
118
+ 标准方法为 `ui/update-model-context`,参数为 `{content?: ContentBlock[], structuredContent?: object}`。App 必须具有标准 `updateModelContext` 能力,并使用其声明的内容类型;本接入不接受 audio。
119
+
120
+ Host 声明 `openai/modelContext` 或 `doubao/modelContext` 的完整扩展语义后,结果 `_meta` 中对应对象包含非空字符串 `updateId`,并投影到两个同义键。仅支持标准方法的 Host 不承诺确认 ID 或上下文回显。
121
+
122
+ ```json
123
+ {
124
+ "jsonrpc": "2.0",
125
+ "id": 2,
126
+ "method": "ui/update-model-context",
127
+ "params": {
128
+ "content": [{ "type": "text", "text": "当前选中的订单" }],
129
+ "structuredContent": { "selectedId": "order-1" }
130
+ }
131
+ }
132
+ ```
133
+
134
+ 支持扩展的 Host 返回:
135
+
136
+ ```json
137
+ {
138
+ "jsonrpc": "2.0",
139
+ "id": 2,
140
+ "result": {
141
+ "_meta": {
142
+ "openai/modelContext": { "updateId": "update-1" },
143
+ "doubao/modelContext": { "updateId": "update-1" }
144
+ }
145
+ }
146
+ }
147
+ ```
148
+
149
+ `update-1` 是 Host 返回的示例确认标识,不是调用方生成的幂等键。上下文更新不等于发送聊天消息。
150
+
151
+ ### 快照与清空
152
+
153
+ Host Context 的同名命名空间保存 `{content?, structuredContent?, updateId}` 或 `null`;后续通过标准 `ui/notifications/host-context-changed` 通知变化。
154
+
155
+ - namespace 缺省:Host 未提供此快照。
156
+ - namespace 为对象:读取当前有效快照及确认 ID。
157
+ - namespace 为 `null`:上下文已清空,App 必须清除旧显示。
158
+
159
+ 内容为空时 Host 将该快照清为 `null`。App 在连接后先读取初始 Host Context,再处理变化通知,避免只监听通知而漏掉首帧。频率与内容限制见[运行时限额](#运行时限额)。
160
+
161
+ ## 资源读取扩展
162
+
163
+ ### 请求与响应字段
164
+
165
+ 资源列表、模板和读取沿用标准 `serverResources` 能力。方法仍为 `resources/read`,不要求不存在的 `experimental["doubao/resource"]` 标记。
166
+
167
+ | 位置 | 字段 | 契约 |
168
+ | --- | --- | --- |
169
+ | `params` | `uri` | 标准资源 URI;Host 文件必须来自可信授权绑定 |
170
+ | `params._meta["doubao/resource"]` | `representation?` | `"text"` / `"blob"`;省略时由 reader 决定,接受 `openai/resource` 同义键 |
171
+ | `result.contents[i]._meta["doubao/resource"]` | `etag?` | string,reader 提供的资源版本元数据 |
172
+ | 同上 | `writable?` | boolean,资源属性;不承诺存在写接口 |
173
+
174
+ 响应元数据投影到 `openai/resource` 与 `doubao/resource` 同义键,资源主体仍按标准 `contents` 返回。
175
+
176
+ ```json
177
+ {
178
+ "jsonrpc": "2.0",
179
+ "id": 3,
180
+ "method": "resources/read",
181
+ "params": {
182
+ "uri": "resource://example/readme",
183
+ "_meta": { "doubao/resource": { "representation": "text" } }
184
+ }
185
+ }
186
+ ```
187
+
188
+ ```json
189
+ {
190
+ "jsonrpc": "2.0",
191
+ "id": 3,
192
+ "result": {
193
+ "contents": [{
194
+ "uri": "resource://example/readme",
195
+ "mimeType": "text/plain",
196
+ "text": "项目说明",
197
+ "_meta": {
198
+ "openai/resource": { "etag": "revision-1", "writable": false },
199
+ "doubao/resource": { "etag": "revision-1", "writable": false }
200
+ }
201
+ }]
202
+ }
203
+ }
204
+ ```
205
+
206
+ ### 权限与兼容性
207
+
208
+ 可信 Host 文件 URI 只能交给获授权的 Host reader;撤权、文件失效或 reader 不可用时失败,不能回退到 MCP Server。当前扩展只提供读取能力。
209
+
210
+ 消息与模型上下文中的 group/title/thumbnail 别名按[命名空间规则](#运行时能力与命名空间)归一化,不授予文件权限,也不保证所有输入面呈现相同。
211
+
212
+ ## 应用上下文
213
+
214
+ `hostContext["doubao/context"]` 是版本 1 的业务投影。namespace 不存在或无效时按未提供处理;字段存在不代表授权。
215
+
216
+ | 字段 | 契约 |
217
+ | --- | --- |
218
+ | `version` | 固定 1;未知版本不按 v1 解释 |
219
+ | `epoch` / `revision` | epoch 为字符串,标识投影生命周期;revision 为非负整数,同一 epoch 内才可比较。首次发布从 1 开始 |
220
+ | `pluginId?` | 可信绑定中的插件标识,可能省略 |
221
+ | `binding` | `{instanceRef,scope}`;scope 为 global/thread/file/tool-result/url。它不是 placement 或 displayMode |
222
+ | `identity` | 获准身份资料对象或 `null`;各 scope 对应字段见 [App 身份资料权限](#app-身份资料权限) |
223
+ | `permissions?.granted` | 当前有效身份读取 scope;是授权结果,不是申请入口 |
224
+ | `session` | `{conversationRef,agentRef?}` 或 `null`;conversationRef 可能从 clientSessionId 更新为后端 conversationId |
225
+ | `resource` | `{active?:FileRef,opened?:FileRef[]}` 或 `null`;FileRef 仅含 uri/name/mimeType?,来自可信绑定 |
226
+ | `access?` | `{plugin: "enabled"或"disabled"或"uninstalled", connector?: {readiness: "ready"或"authorization-required"或"unavailable"}}`;执行时 Host 仍重新检查 |
227
+
228
+ 以下是 Host Context 中的示例投影;标识来自 Host,业务代码不自行构造实例或授权状态:
229
+
230
+ ```json
231
+ {
232
+ "doubao/context": {
233
+ "version": 1,
234
+ "epoch": "projection-epoch",
235
+ "revision": 1,
236
+ "binding": { "instanceRef": "app-instance", "scope": "global" },
237
+ "identity": { "user": { "name": "示例用户" } },
238
+ "permissions": { "granted": ["identity.user.read"] },
239
+ "session": null,
240
+ "resource": null,
241
+ "access": { "plugin": "enabled", "connector": { "readiness": "ready" } }
242
+ }
243
+ }
244
+ ```
245
+
246
+ 身份字段的有效 scope、申请与授权交集见 [App 身份资料权限](#app-身份资料权限)。
247
+
248
+ ## App 身份资料权限
249
+
250
+ MCP App 读取豆包用户或企业资料时使用以下声明;它与 MCP 服务的 OAuth/静态凭据、iframe 浏览器权限分别授权,不新增 `com.doubao/auth/` 文件。运行时快照见 [应用上下文](#应用上下文)。
251
+
252
+ 入口工具的 `_meta["doubao/permissions"]` 是 string 数组,缺省 `[]`,不能写成 `{granted:[...]}`。scope 语法为 `^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$`,重复值去重。当前有效 scope 为 `identity.user.read` 和 `identity.enterprise.read`;未知但语法正确的值可以保留,不会自动授权。
253
+
254
+ 有效权限是入口申请、可信 Host 批准权限、Host 支持范围三者的交集。它与 iframe `ui.permissions` 的浏览器权限分开;没有自动的 `openai/permissions` 别名。停用或卸载后清空身份权限,晚到数据不能恢复旧资料;内部 userId、账号 authority key 和凭据不属于公开身份字段。
255
+
256
+ | 有效 scope | `hostContext["doubao/context"].identity` 中可用字段 |
257
+ | --- | --- |
258
+ | `identity.user.read` | `user.name`、`user.avatarUrl`、`user.runtimeStatus`,均为可选字符串 |
259
+ | `identity.enterprise.read` | `enterprise.organizationName`、`enterprise.department`、`enterprise.sequence`,均为可选字符串 |
260
+
261
+ ```json
262
+ {
263
+ "_meta": {
264
+ "ui": { "resourceUri": "ui://example/main" },
265
+ "doubao/permissions": ["identity.user.read", "identity.enterprise.read"]
266
+ }
267
+ }
268
+ ```
269
+
270
+ 授权变化通过应用上下文快照反映。没有有效资料时 `identity` 为 `null`,App 必须清除旧身份显示;旧请求的晚到结果不得恢复已经撤销的权限。
271
+
272
+ ## 错误、限额与生命周期
273
+
274
+ | 结果 | 调用方处理 |
275
+ | --- | --- |
276
+ | `-32601` | 方法未注册或旧 Host 不支持,按能力及实际结果降级 |
277
+ | `-32602` | 修正非法参数;不能据错误文本推断额外权限 |
278
+ | `-32000`,`data.code=unauthorized/blocked`,`execution=not_started` | 按 Host 的授权、连接或启用流程恢复,成功后再按策略重试 |
279
+ | `data.code=result_unknown`,`execution=unknown` | 可能已发生副作用,先核实原操作,不能盲目重放工具或消息 |
280
+ | 输入层拒绝,`-32603` | 可带 reason/detail/requestId/target/mode;按 not-ready、stale-scope、unsupported-content、attachment-limit、busy、send-failed 等实际原因处理 |
281
+ | `CallToolResult.isError:true` | 正常返回的业务错误结果,不作为成功数据,也不等同传输错误 |
282
+
283
+ 以下示例表示业务尚未开始;错误 message 是可读说明,恢复依据是 code 和 execution:
284
+
285
+ ```json
286
+ {
287
+ "jsonrpc": "2.0",
288
+ "id": 7,
289
+ "error": {
290
+ "code": -32000,
291
+ "message": "Extension access is unavailable",
292
+ "data": { "code": "unauthorized", "execution": "not_started" }
293
+ }
294
+ }
295
+ ```
296
+
297
+ `execution: "unknown"` 不提供重试安全保证;应核实原操作,不能把未知结果当作未执行。取消本地等待同样不能证明远端未发生副作用。
298
+
299
+ ### 运行时限额
300
+
301
+ 以下为豆包 Host 的实现限额,不是 MCP Apps 基础协议的通用限制;其他 Host 以各自能力为准:
302
+
303
+ | 对象 | 约束 |
304
+ | --- | --- |
305
+ | 消息与草稿 | 同一实例至少间隔 2 秒;最多 20 块,完整 params UTF-8 JSON ≤5 MiB,直接文本合计 ≤20,000 字符;旧无类型表 Adapter 仅文本、最多 16 块 |
306
+ | 模型上下文 | 1 秒滑动窗口最多 10 次;最多 16 块,直接文本 ≤20,000 字符;图片单张 ≤10 MiB,嵌入资源单项 ≤20 MiB,嵌入合计 ≤40 MiB;图片须非空有效 Base64,MIME 仅 PNG/JPEG/WebP/GIF,拒绝 audio |
307
+ | structuredContent 与工具 arguments | JSON 序列化字符串长度 ≤32,000,深度 ≤8,遍历键数 ≤256;拒绝 __proto__/prototype/constructor。长度不是 UTF-8 字节数 |
308
+ | 工具名与 arguments | 标准工具名 1~128 字符,仅字母、数字、下划线及 `. : / -`;arguments 为对象而非数组。Workbench 顶层 name 校验见 [导航与 Workbench](workbench.md#导航与-workbench),实际工具调用仍受下游校验 |
309
+ | 文件下载 | 每次 1~10 个,单文件 ≤25 MiB;resource_link 需要受授权 Gateway resolver,普通 fallback 不自动解析 |
310
+ | 外链 | Extension Adapter 接受 HTTPS/doubao:;普通非 Adapter MCP App 路径仅 HTTPS。应用导航使用专有 deepLink RPC |
311
+
312
+ ### 生命周期与兼容边界
313
+
314
+ 初始化、Host Context 更新和 teardown 沿用[上游生命周期](../../upstream/mcp-apps.mdx#lifecycle)。Host 当前资源销毁最多等待 1000ms;App 及时保存必要状态、释放监听和请求。绑定、账号、权限或实例变化后不能把旧异步结果回填到新目标,应按本次绑定及 epoch/revision 判断有效性。
315
+
316
+ iframe 保活是 Host 实现策略,不是持续后台执行承诺。隐藏实例即使计时器仍运行,也必须遵守 presentation 和访问门禁;不能据此承诺后台发消息、调用工具或浏览器永不节流。
317
+
318
+ 当前豆包扩展不提供文件打开、资源写入及订阅、Forms、Settings、Onboarding、WebMCP、quickAction 或 PiP 的接入能力,不因上游 SDK 存在相应类型而调用。
@@ -0,0 +1,180 @@
1
+ # Workbench 运行时协议
2
+
3
+ 定义页面与宿主的运行时通信,包括应用导航、启动结果领取、跨服务调用和 Home 上下文。包内配置见 [工作台包协议](../workbench.md)。
4
+
5
+ 入口工具声明见 [静态入口](integration.md#静态入口与-ui-来源),通用运行时规则见 [运行时能力与约束](runtime.md)。
6
+
7
+ | 任务 | 阅读位置 |
8
+ | --- | --- |
9
+ | 在页面中打开另一个应用 | [导航请求](#导航请求) |
10
+ | 领取启动数据或刷新业务数据 | [能力协商](#能力协商)、[Workbench 调用](#workbench-调用) |
11
+ | 读取首页推荐、加载随包资源 | [首页加载与上下文](#首页加载与上下文) |
12
+
13
+ ## 基础协议与适用范围
14
+
15
+ 本扩展基于 [MCP Apps 2026-01-26(SEP-1865)](../../upstream/mcp-apps.mdx),固定提交和许可证见[来源记录](../../upstream/SOURCES.md)。描述要求时,`MUST`、`MUST NOT` 和 `MAY` 按 [BCP 14](https://www.rfc-editor.org/info/bcp14) 解释。
16
+
17
+ | 层 | 沿用开源标准 | 豆包扩展 |
18
+ | --- | --- | --- |
19
+ | App 与宿主 | JSON-RPC 消息、`ui/initialize` 生命周期、Host Context 与 `CallToolResult` | 工作台能力、Home 上下文、应用导航、启动结果领取和跨服务调用 |
20
+
21
+ 工作台调用使用单独的 `doubao/*` 方法,标准 `tools/call` 的参数和结果沿用 [MCP Apps 标准消息](../../upstream/mcp-apps.mdx#standard-mcp-messages)。
22
+
23
+ ## 能力协商
24
+
25
+ 当页面由 MCP Server 提供时,宿主与服务器协商标准扩展 `io.modelcontextprotocol/ui`。App 与宿主通过 `ui/initialize` 交换各自能力,App 从返回的 `hostCapabilities.experimental` 读取 `doubao/workbench`,按方法检查能力。以下是同时支持启动结果领取和跨服务调用的 `hostCapabilities` 片段。
26
+
27
+ ```json
28
+ {
29
+ "experimental": {
30
+ "doubao/workbench": {
31
+ "startupClaims": true,
32
+ "serverRouting": true
33
+ }
34
+ }
35
+ }
36
+ ```
37
+
38
+ App `MUST` 在对应标记为 `true` 时才发起该方法。标记缺失或为 `false` 时,页面 `MAY` 继续使用已协商的标准能力,`MUST NOT` 用标准 `tools/call` 代替跨服务调用。
39
+
40
+ ## 导航与 Workbench
41
+
42
+ ### 导航请求
43
+
44
+ Host Context 的 `openai/deepLink` / `doubao/deepLink` 是 `{url:string}` 的应用内部路径状态;出站 `doubao/deepLink` RPC 用于打开目标应用,二者分开。
45
+
46
+ `doubao/deepLink` 是 App 发给宿主的 JSON-RPC 请求。`params` 为 `{url:string}`,URL 必须使用 `/chat/extension?...` 形式。当前宿主等待页面启动完成后返回实际结果,`result` 可含 `instanceId` 和 `placement`。遇到不支持该方法而返回 `-32601` 的宿主,App `MUST NOT` 静默改用 `ui/open-link`。
47
+
48
+ | 目标字段 | 约束 |
49
+ | --- | --- |
50
+ | `connectorId` / `toolName` | 必填;目标来自真实 Connector 和入口发现 |
51
+ | `pluginId` / `entryId` | 可选提示;Host 重新校验归属 |
52
+ | `entrypoint` | global/thread/file,缺省 global |
53
+ | `clientSessionId` | thread 专用;省略时只从调用方可信会话绑定补齐,无可信绑定则必填,不取当前可见会话 |
54
+ | `fileUri` / `fileId` | file 专用,fileUri 必填,fileId 可选;仍需文件授权 |
55
+ | `deepLink` | 应用内部单个 `/` 开头的路径,可含 query;禁止 `//`、fragment、反斜线、控制字符及非法百分号编码。缺省保持复用实例当前位置,显式 `/` 才回首页 |
56
+ | `placement` | global 为 page;thread/file 为 rightSidebar。缺省按入口选择;链接中的 fullscreen/sidebar 无效 |
57
+ | `preferredSidebarWidth` | 正安全整数,CSS px;Host 布局和用户尺寸记忆优先 |
58
+
59
+ 公开导航标识长度 1~4096,禁止首尾空白、控制字符和替换字符。未知、重复 query 字段以及 instance/instanceId/authority/accountKey/resourceUrl/proxyUrl 均不允许。链接不接受 URL source、tool-result、inline 作为新目标。路径变化更新 Host Context,不重放入口工具;来源失效或授权不足时失败。
60
+
61
+ 导航示例,URL 内标识均须来自真实入口发现:
62
+
63
+ ```json
64
+ {
65
+ "jsonrpc": "2.0",
66
+ "id": 10,
67
+ "method": "doubao/deepLink",
68
+ "params": {
69
+ "url": "/chat/extension?connectorId=connector-example&toolName=open_workspace&entrypoint=global&deepLink=%2Forders%2Forder-1"
70
+ }
71
+ }
72
+ ```
73
+
74
+ 支持该导航的 Host 等待启动完成后,可返回:
75
+
76
+ ```json
77
+ {
78
+ "jsonrpc": "2.0",
79
+ "id": 10,
80
+ "result": { "instanceId": "instance-example", "placement": "page" }
81
+ }
82
+ ```
83
+
84
+ `instanceId` 是返回信息,不能再作为导航请求的目标参数;App 内部路径快照通过 Host Context 的 deepLink 命名空间更新。
85
+
86
+ ### Workbench 调用
87
+
88
+ 以下请求由 App 发给宿主。两者共用 `params` 结构,分别要求对应的[工作台能力](#能力协商)。
89
+
90
+ | 方法 | 语义与条件 |
91
+ | --- | --- |
92
+ | `doubao/claimStartup` | 要求 `startupClaims`。按声明领取启动调用结果,重复领取复用同一次调用,包括失败。无匹配声明时失败 |
93
+ | `doubao/callServerTool` | 要求 `serverRouting`。发起一次新的工具执行,适用于用户主动刷新 |
94
+
95
+ 参数对象定义如下,拒绝未定义的顶层字段:
96
+
97
+ | 字段 | 类型 | 必填 | 契约 |
98
+ | --- | --- | --- | --- |
99
+ | `server` | string | 是 | 长度 1~256,包内已批准的 MCP 服务别名 |
100
+ | `name` | string | 是 | 长度 1~256,目标服务的真实工具名 |
101
+ | `arguments` | object | 否 | 可 JSON 序列化的工具参数,启动匹配时缺省等同 `{}` |
102
+
103
+ 方法结果为标准 CallToolResult,直接含 `content`、可选 `structuredContent`、`isError` 和 `_meta`。它位于 JSON-RPC 的 `result` 中,不再嵌套 `startup` 或第二层 `result`。
104
+
105
+ server 精确匹配包内 `mcp.json.mcpServers` 的已批准别名,由可信 Host 解析账号和 Connector;App 不能自行指定 endpoint。未知别名返回 `-32602`,`data.code=invalid_server_alias`。标准无 server 的工具和资源请求由包 Host 的 `standardServer` 选择一个可信别名,不能拿标准调用冒充多服务路由。
106
+
107
+ 假设 Host 已声明 workspace 服务的 get_dashboard 启动调用,App 领取其结果:
108
+
109
+ ```json
110
+ {
111
+ "jsonrpc": "2.0",
112
+ "id": 11,
113
+ "method": "doubao/claimStartup",
114
+ "params": { "server": "workspace", "name": "get_dashboard", "arguments": {} }
115
+ }
116
+ ```
117
+
118
+ ```json
119
+ {
120
+ "jsonrpc": "2.0",
121
+ "id": 11,
122
+ "result": {
123
+ "content": [{ "type": "text", "text": "当前有 3 个待办。" }],
124
+ "structuredContent": { "pendingCount": 3 }
125
+ }
126
+ }
127
+ ```
128
+
129
+ 用户主动刷新时,App 可以用相同的业务参数发送新的 `doubao/callServerTool` 请求。宿主重新执行工具并返回标准 `CallToolResult`。
130
+
131
+ ```json
132
+ {
133
+ "jsonrpc": "2.0",
134
+ "id": 12,
135
+ "method": "doubao/callServerTool",
136
+ "params": { "server": "workspace", "name": "get_dashboard", "arguments": {} }
137
+ }
138
+ ```
139
+
140
+ ### 启动、取消与错误
141
+
142
+ 同一逻辑启动按真实目标、工具名和 arguments 的规范 JSON 去重;对象键顺序不影响结果,省略 arguments 等同 `{}`。启动调用并行执行,HTML 不等待全部结果。取消某个 claim 只取消当前等待,作用域销毁才清理共享批次;账号、安装或版本失效后丢弃旧结果。
143
+
144
+ | 情况 | 结果与处理 |
145
+ | --- | --- |
146
+ | 方法未注册或旧 Host 不支持 | `-32601`,按缺失能力处理 |
147
+ | 参数或服务别名非法 | `-32602`;未知别名的 `data.code` 为 `invalid_server_alias` |
148
+ | 没有匹配的已声明启动调用 | claim 失败;只有确实需要新执行时才选择 callServerTool |
149
+ | 工具返回 `isError: true` | 保留业务错误,不视为 JSON-RPC 传输失败 |
150
+ | 作用域失效或执行结果未知 | 按[错误恢复](runtime.md#错误限额与生命周期)处理,不重放可能产生副作用的新调用 |
151
+
152
+ 未知服务别名通过 JSON-RPC 的 `error` 返回。以下是一个响应示例。
153
+
154
+ ```json
155
+ {
156
+ "jsonrpc": "2.0",
157
+ "id": 13,
158
+ "error": {
159
+ "code": -32602,
160
+ "message": "Unknown server alias",
161
+ "data": { "code": "invalid_server_alias" }
162
+ }
163
+ }
164
+ ```
165
+
166
+ ## 首页加载与上下文
167
+
168
+ 页面由 MCP Apps Host 承载,使用 MCP Apps SDK 完成初始化,再使用宿主声明的能力。启动结果和主动刷新按 [Workbench 调用](#workbench-调用)处理。
169
+
170
+ `hostContext["doubao/home"]` 的形状为 `{sug:NexPulseResponseData|null}`。无 namespace 表示未提供;已有 namespace 收到 `{sug:null}` 表示清空,界面必须停止显示旧推荐。
171
+
172
+ Sug 保留正式 DTO,包含可选 candidate_list、category_candidate_list、nexpulse_type、conf;叶子字段及枚举由正式接口拥有者维护。数据仅授予当前活跃、账号和包及入口匹配的 Home presentation;普通 Connector global App 不因此获得推荐。Home 是只读快照,没有点击、曝光、执行动作或任意写入推荐的 RPC。
173
+
174
+ 宿主按当前发布版本的可信部署元数据 `web.files` 解析资源。每项包含 `path`、`url`、`content_type`、`sha256` 和 `size`,入口必须存在且为 `text/html`。按逻辑路径使用完整签名 URL,不能从入口 URL 推导其他资源地址。部署 URL 为 HTTPS,本地调试 fixture 可用 HTTP。静态映射仍受运行时 CSP 和 CORS 约束。
175
+
176
+ 可信宿主可覆盖 `startupCalls`,未声明时按空数组处理。每个 `server` 仍须通过包内服务的可信绑定。启动与领取结果见 [Workbench 调用](#workbench-调用)。
177
+
178
+ ## 支持与兼容边界
179
+
180
+ [工作台包格式版本](../workbench.md#工作台作者配置)、应用上下文的 `version: 1` 与 MCP 协议版本互不替代。运行时契约不代表所有发布渠道已提供 Home 部署能力。开发 fixture 的手动映射不能证明生产路由可用;缺少可信部署映射或服务绑定时,不可用 App 自选地址补齐。
@@ -0,0 +1,73 @@
1
+ # MCP 鉴权配置
2
+
3
+ 连接配置见 [MCP 配置](mcp-config.md)。无需鉴权或使用标准 MCP OAuth 时,不需要额外鉴权文件;服务要求授权时由宿主进入 OAuth,不在包内重复声明授权地址或预注册客户端凭据。 App 身份资料授权见 [豆包 MCP Apps 扩展](mcp-apps/runtime.md#app-身份资料权限),与服务鉴权分别处理。
4
+
5
+ ## 文件位置与最小示例
6
+
7
+ 本文件是豆包的静态凭据声明扩展,由宿主管理凭据输入并按声明注入。标准 OAuth 的发现、授权与令牌流程沿用 [MCP Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。
8
+
9
+ 静态 API Key 或 Token 使用 `com.doubao/auth/<服务键>.json`。文件必须直接位于该目录,服务键来自 `mcp.json.mcpServers`,不得含 `/` 或 `\`。例如 `shopping` 对应 `com.doubao/auth/shopping.json`:
10
+
11
+ ```json
12
+ {
13
+ "credentials": [
14
+ { "id": "apiKey", "label": "API Key", "secret": true }
15
+ ],
16
+ "injections": [
17
+ { "target": "header", "name": "Authorization", "value": "Bearer ${apiKey}" }
18
+ ]
19
+ }
20
+ ```
21
+
22
+ 包内只声明输入项和模板;真实凭据由用户输入、宿主管理,不写入文件。
23
+
24
+ ## 字段定义
25
+
26
+ | 字段 | 类型 | 必填 | 约束与默认值 |
27
+ | --- | --- | --- | --- |
28
+ | `credentials` | object[] | 是 | 非空凭据列表 |
29
+ | `credentials[].id` | string | 是 | 同文件唯一;以字母开头,仅字母、数字、下划线 |
30
+ | `credentials[].label` | string | 是 | 非空,展示给用户的输入项名称 |
31
+ | `credentials[].description` | string | 否 | 获取或填写说明,最多 300 字符 |
32
+ | `credentials[].required` | boolean | 否 | 默认 `true` |
33
+ | `credentials[].secret` | boolean | 是 | 是否遮蔽输入并按敏感信息保存;密钥、Token 设为 `true` |
34
+ | `injections` | object[] | 是 | 非空注入规则列表 |
35
+ | `injections[].target` | string | 是 | 见 [注入位置枚举](#注入位置枚举) |
36
+ | `injections[].name` | string | 是 | 注入位置中的非空目标名称,含义见对应枚举项 |
37
+ | `injections[].value` | string | 是 | 至少引用一个同文件声明的 `${id}`,仅做一次原文替换 |
38
+
39
+ ### 注入位置枚举
40
+
41
+ | `target` | 含义 | `name` |
42
+ | --- | --- | --- |
43
+ | `header` | 将凭据注入 HTTP 请求头 | 请求头名称,如 `Authorization` |
44
+
45
+ ## 注入与失败语义
46
+
47
+ - Header 注入项名称按大小写不敏感判重,也不得与 `mcp.json.headers` 中的名称冲突。
48
+ - 可选凭据为空时,省略所有引用它的注入项;无凭据的固定请求头写入 `mcp.json`。
49
+ - Header 凭据只发送到配置的源站,跨源重定向不得携带。未知字段由宿主忽略,不据此增加自定义注入能力。
50
+ - 文件位置或服务关联错误会阻止提交;鉴权配置无效时,宿主停用对应 MCP 服务并说明原因,其他有效服务独立加载。
51
+
52
+ 例如,上述 `apiKey` 的示例输入为 `example-token` 时,发送到 shopping 配置源站的请求头为 `Authorization: Bearer example-token`。替换结果不再次解释为模板或执行代码;此值仅演示替换,实际凭据不随插件分发。凭据填写完成只满足注入条件,服务仍可因令牌无效或权限不足拒绝请求。
53
+
54
+ ## 修改与验证
55
+
56
+ 静态凭据按 [注入位置枚举](#注入位置枚举) 配置;MCP OAuth 与 App 身份权限各自遵循对应契约。
57
+
58
+ 配置变更的同步边界见 [开发调试](../cli/development.md#配置变更的同步边界)。App 模拟器和 Inspector 不会自动读取此文件并收集用户凭据;Inspector 的 `-H` 可用于单次连接诊断,完整授权和注入仍需在目标宿主验证。
59
+
60
+ ## 按失败环节排查
61
+
62
+ 先区分开发者的开放平台登录、MCP 服务鉴权和安装用户的业务权限;开发助手能读取数据,不代表目标宿主或安装用户也能读取。
63
+
64
+ | 失败环节 | 核对内容 |
65
+ | --- | --- |
66
+ | 服务连接与初始化 | 实际 endpoint、传输、网络可达性及服务是否就绪;网页可打开不能证明 MCP 可用 |
67
+ | OAuth 发现或授权 | 原响应的状态、授权挑战与元数据、客户端实际提供的授权入口、所需 scope;使用原服务的真实授权流程 |
68
+ | 静态凭据注入 | 服务键、声明文件、用户是否已填写、注入 Header 和源站;不在日志或回复中输出秘密 |
69
+ | 工具业务权限 | 当前业务身份、资源可见范围、scope 和工具返回的业务错误;OAuth 完成不代表所有业务操作获准 |
70
+
71
+ 单个 401 或 403 不足以确定认证方案;先看原响应和服务契约,不盲目添加 Bearer/API Key、不改成免鉴权,也不重建服务碰运气。需要用户操作时交接真实入口及缺少的权限,保留当前工程和任务目标。
72
+
73
+ 恢复后对同一 endpoint、同一工具和原参数回验,先做任务所需的最小读取;写操作仅在已授权范围内执行。不以登录页完成、平台登录成功或工具枚举成功代替业务请求成功。