@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,145 @@
1
+ # MCP 连接配置
2
+
3
+ 声明远程 MCP 服务的连接;工具定义由服务提供,服务展示信息在 [根清单](plugin-json.md#展示字段) 中维护。
4
+
5
+ ## 协议范围
6
+
7
+ 本文件定义豆包的远程 MCP 连接配置及 Host 发现约定。连接、工具调用和资源结果使用 MCP 标准;Profile 与资源搜索是在标准工具上的元数据约定,不增加 App Bridge RPC。
8
+
9
+ 配置文件负责服务连接;工具的输入、输出和权限由服务的真实契约决定。基础协议支持某种传输,不代表豆包发布渠道也支持该传输;本接入范围以下表为准。
10
+
11
+ ## 文件位置与最小示例
12
+
13
+ 固定为插件根目录的 `mcp.json`。以下 URL 为占位,接入时替换为实际地址:
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "shopping": {
19
+ "type": "streamable-http",
20
+ "url": "https://example.com/mcp"
21
+ }
22
+ }
23
+ }
24
+ ```
25
+
26
+ ## 字段定义
27
+
28
+ | 字段 | 类型 | 必填 | 约束与取值来源 |
29
+ | --- | --- | --- | --- |
30
+ | `mcpServers` | object | 是 | 以非空服务键索引的连接集合 |
31
+ | `mcpServers.<服务键>.type` | string | 是 | 豆包发布协议支持 `streamable-http` 或 `sse`,无默认值 |
32
+ | `mcpServers.<服务键>.url` | string | 是 | 服务提供者给出的 HTTPS 绝对地址 |
33
+ | `mcpServers.<服务键>.headers` | 字符串映射 | 否 | 固定、非敏感请求头,缺省不添加 |
34
+
35
+ ## 文件级与关联约束
36
+
37
+ - URL 不得指向 `localhost` 或回环 IP(含 `127.0.0.1`、`::1`),不得含用户名、密码或片段。
38
+ - Header 名称按大小写不敏感判重。真实 Token、API Key 不写入 URL 或 headers;不依赖 `${ENV}` 展开,凭据声明见 [MCP 鉴权](mcp-auth.md)。
39
+ - 服务键须与 `plugin.json.extensions["com.doubao"].mcpServers` 逐一对应;静态鉴权文件以同一服务键命名。
40
+ - 工具来自 `tools/list`,不复制到 `mcp.json`。仅用 App 端工具时无需远程 MCP 服务。
41
+ - 豆包发布协议仅支持远程服务,不能由通用 Agent Plugins 协议中的 `stdio` 能力推断豆包支持本地子进程。
42
+
43
+ ## Profile 与资源搜索
44
+
45
+ 两者由 Host 在当前账号、已安装且启用的插件、版本和 Connector 路由下执行。发现声明不授予跨账号或跨插件权限。
46
+
47
+ ### Profile 发现与调用
48
+
49
+ Host 从 `tools/list` 查找唯一的 `Tool._meta["openai/profile"] === true` 标记,以 `arguments: {}` 调用该工具。缺少标记表示不支持;多标记、重复工具名或失效路由必须拒绝。没有 `doubao/profile` 别名,也不按工具名猜测 Profile 能力。
50
+
51
+ 服务端工具定义示例:
52
+
53
+ ```json
54
+ {
55
+ "name": "get_profile",
56
+ "description": "读取当前已授权账号的基本资料。",
57
+ "inputSchema": { "type": "object", "properties": {} },
58
+ "_meta": { "openai/profile": true }
59
+ }
60
+ ```
61
+
62
+ Host 使用标准 `tools/call`,示例响应为:
63
+
64
+ ```json
65
+ {
66
+ "jsonrpc": "2.0",
67
+ "id": 30,
68
+ "result": {
69
+ "content": [{ "type": "text", "text": "当前账号:示例用户" }],
70
+ "structuredContent": { "id": "account-example", "name": "示例用户" }
71
+ }
72
+ }
73
+ ```
74
+
75
+ | structuredContent 字段 | 类型 | 语义 |
76
+ | --- | --- | --- |
77
+ | `id` | string | 服务内稳定的不透明身份标识,Host 投影为 accountId |
78
+ | `name` | string,可选 | 非空时保留用于展示 |
79
+ | `email` | string,可选 | 非空时保留用于展示 |
80
+
81
+ 服务必须依据已验证的请求凭据确定账号,不从 App 自带参数选择账号。上游允许的 nickname 当前不参与豆包投影;Profile 成功不代表已实现多账号选择或额外授权。
82
+
83
+ ### 资源搜索发现
84
+
85
+ 以下两种位置用于声明搜索工具:
86
+
87
+ | 位置 | 声明形状 |
88
+ | --- | --- |
89
+ | `Server.capabilities.extensions["doubao/mentions"]` 或 `openai/mentions` | `{searchTool: "真实工具名"}` |
90
+ | 唯一工具的 `Tool._meta["doubao/extensions"]` 或 `openai/extensions` | 包含 `"mentions/search"` 对象标记 |
91
+
92
+ 豆包命名空间优先;声明无效时必须报错,不能静默回退。没有声明时返回空候选,不猜工具名。
93
+
94
+ 例如,以下片段位于服务的 `capabilities` 对象中:
95
+
96
+ ```json
97
+ {
98
+ "extensions": {
99
+ "doubao/mentions": { "searchTool": "search_documents" }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ### 搜索请求与结果
105
+
106
+ 被声明的工具必须满足 `annotations.readOnlyHint === true`,且 `_meta.ui.visibility` 缺省或包含 `app`。Host 通过 `tools/call` 传入 `{query: string}`,结果为标准 CallToolResult。
107
+
108
+ ```json
109
+ {
110
+ "jsonrpc": "2.0",
111
+ "id": 31,
112
+ "method": "tools/call",
113
+ "params": { "name": "search_documents", "arguments": { "query": "项目计划" } }
114
+ }
115
+ ```
116
+
117
+ ```json
118
+ {
119
+ "jsonrpc": "2.0",
120
+ "id": 31,
121
+ "result": {
122
+ "content": [{ "type": "text", "text": "找到一份项目计划。" }],
123
+ "structuredContent": {
124
+ "items": [{
125
+ "type": "resource_link",
126
+ "uri": "resource://documents/plan-1",
127
+ "name": "项目计划",
128
+ "mimeType": "text/plain"
129
+ }]
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ `structuredContent.items` 最多 1000 项,每项为 MCP ResourceLink,uri/name 非空,按 URI 去重。兼容旧 `{type: "resource", resourceUri, title, subtitle?, icons?}` 资源描述并转换;新实现直接返回 ResourceLink。
136
+
137
+ ### 失败与失效
138
+
139
+ 工具 `isError`、非法候选和失效绑定必须保留为错误,不能伪造空成功结果。账号读取和搜索结果都以实际 `structuredContent` 为准;工具枚举成功不能代替业务调用成功。账号、插件启用状态或版本改变后,旧路由不能继续获得数据。
140
+
141
+ ## 修改与验证
142
+
143
+ 连接诊断见 [开发调试](../cli/development.md#单独调试-mcp-server)。App Web 模拟器只适配单个 `streamable-http` 服务,并使用 URL 和固定 headers;SSE、多服务及完整授权链路需在目标宿主验证。
144
+
145
+ 服务端 UI 与事件分别见 [MCP Apps](mcp-apps/integration.md)、[MCP Events](mcp-events.md)。
@@ -0,0 +1,260 @@
1
+ # MCP 事件
2
+
3
+ 为远程 MCP 服务接入事件发现、订阅与 Webhook 投递。
4
+
5
+ ## 协议基准
6
+
7
+ 接入使用下文的豆包约定与[请求和响应](#请求和响应)。通用部分参考 SEP-3415 固定快照 `f77a5fe`,需要报文细节时按下表读取对应章节。
8
+
9
+ | 待核对内容 | 协议章节 |
10
+ | --- | --- |
11
+ | 事件列表与业务 Schema | [Listing Available Events](../upstream/mcp-events.md#listing-available-events) |
12
+ | 订阅请求、续期及订阅身份 | [Subscribing](../upstream/mcp-events.md#subscribing-eventssubscribe)、[Subscription TTL](../upstream/mcp-events.md#subscription-ttl)、[Subscription identity](../upstream/mcp-events.md#subscription-identity) |
13
+ | 投递正文与请求头 | [Webhook event delivery](../upstream/mcp-events.md#webhook-event-delivery) |
14
+ | challenge、签名、密钥与回调安全 | [Webhook security](../upstream/mcp-events.md#webhook-security) |
15
+ | 取消订阅 | [Unsubscribing](../upstream/mcp-events.md#unsubscribing-eventsunsubscribe) |
16
+ | 错误语义 | [Error Handling](../upstream/mcp-events.md#error-handling),错误编号以本页[差异表](#错误码差异)为准 |
17
+
18
+ - JSON-RPC、公共元数据和版本字段见 [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/basic/index),HTTP 请求头见 [Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http)。
19
+ - Webhook 签名算法与编码见 [Signature scheme](../upstream/standard-webhooks.md#signature-scheme),验签见 [Verifying signatures](../upstream/standard-webhooks.md#verifying-signatures),采用 Events 的 `whsec_`、`v1,` HMAC-SHA256 约定。
20
+
21
+ 上游提交与许可证见[快照来源](../upstream/SOURCES.md)。本页定义豆包的能力声明、订阅语义与报文差异;签名算法和未修改的通用字段直接引用上游。目标宿主的可用性与返回结构另按[兼容边界](#兼容边界)核对。
22
+
23
+ ## 豆包支持范围与差异
24
+
25
+ - 服务为远程 `streamable-http`,使用 MCP 2026-07-28;旧 `initialize` 服务需先适配,不适用于本地子进程、Skill 或 CLI。
26
+ - 实现 `events/list`、`events/subscribe`、`events/unsubscribe`,投递方式见 [投递模式枚举](#投递模式枚举)。
27
+ - 能力声明、订阅身份、回调与取消报文见[请求和响应](#请求和响应);公共响应及提案可选能力的边界见[兼容边界](#兼容边界)。
28
+
29
+ ### 错误码差异
30
+
31
+ 错误语义及 `data.kind`、`data.limit`、`data.reason` 见所引提案的 Error Handling;豆包使用下列编号,不照搬提案编号:
32
+
33
+ | 错误 | 豆包 | 所引提案 |
34
+ | --- | --- | --- |
35
+ | `InvalidParams` | `-32602` | `-32602` |
36
+ | `NotFound` | `-32011` | `-32023` |
37
+ | `Forbidden` | `-32012` | `-32024` |
38
+ | `ResourceExhausted` | `-32013` | `-32025` |
39
+ | `Unsupported` | `-32014` | `-32026` |
40
+ | `CallbackEndpointError` | `-32015` | `-32027` |
41
+
42
+ 豆包 `NotFound` 用于事件不存在,`data.kind` 为 `event`;取消不存在的订阅按豆包约定返回成功。回调失败的 `data.reason` 使用 `challenge_failed`、`timeout`、`connection_refused`、`tls_error`、`http_4xx`、`http_5xx`。
43
+
44
+ ## 接入步骤
45
+
46
+ 1. **连接与授权**:事件由服务运行时声明,`plugin.json`、`mcp.json`、`com.doubao/` 无需增加事件文件。连接见 [MCP 配置](mcp-config.md),事件请求沿用同一服务的用户授权;平台登录不代表用户已有业务资源权限。
47
+ 2. **业务定义**:`inputSchema` 写明过滤参数的来源和查询工具,`payloadSchema` 写明资源 ID 对应的详情读取工具。服务端按 Schema 过滤,只推送必要 ID 和少量判断字段;详情通过工具按用户权限读取。业务字段和数量限制由该事件定义,事件内容不承载任务指令。
48
+ 3. **订阅与生命周期**:按[创建与续期](#创建与续期)、[回调验证与投递](#回调验证与投递)和[取消订阅](#取消订阅)实现。
49
+
50
+ ## 请求和响应
51
+
52
+ 以下以“主播小王开播时提醒我”为例。用户已确认任务,客户端通过查询工具取得 `anchor_id: "a_12345"`;服务端负责按此参数过滤事件。URL、密钥、ID 和时间均为示意,业务字段和过滤限制仅属于此事件。报文按豆包约定展示,公共 `resultType` 的兼容边界见文末。
53
+
54
+ ### 能力与事件发现
55
+
56
+ `server/discover.result.capabilities` 包含 `events: {}`,与已有工具能力并列。这个位置不同于固定提案中的 `extensions["io.modelcontextprotocol/events"]`;完整公共发现响应沿用选定的 MCP 版本:
57
+
58
+ ```json
59
+ {"tools": {}, "events": {}}
60
+ ```
61
+
62
+ 首次读取事件列表使用空参数;分页时将返回的 `nextCursor` 放入下一次请求的 `params.cursor`。这个列表分页游标与订阅、投递中固定为 null 的事件游标不同。
63
+
64
+ ```json
65
+ {"jsonrpc": "2.0", "id": 1, "method": "events/list", "params": {}}
66
+ ```
67
+
68
+ ```json
69
+ {
70
+ "jsonrpc": "2.0",
71
+ "id": 1,
72
+ "result": {
73
+ "events": [{
74
+ "name": "live.room.started",
75
+ "description": "订阅的主播开播时触发,每场直播触发一次。",
76
+ "delivery": ["webhook"],
77
+ "inputSchema": {
78
+ "type": "object",
79
+ "properties": {
80
+ "anchor_id": { "type": "string", "description": "通过 search_following 查询的主播 ID" }
81
+ },
82
+ "required": ["anchor_id"]
83
+ },
84
+ "payloadSchema": {
85
+ "type": "object",
86
+ "properties": {
87
+ "room_id": { "type": "string", "description": "通过 get_live_room 读取详情的直播间 ID" }
88
+ },
89
+ "required": ["room_id"]
90
+ }
91
+ }]
92
+ }
93
+ }
94
+ ```
95
+
96
+ 服务端只返回当前用户有权订阅的事件;`inputSchema` 定义订阅过滤参数,`payloadSchema` 定义事件数据,不把任务指令写进事件数据。
97
+
98
+ ### 投递模式枚举
99
+
100
+ 事件发现结果的 `delivery[]` 和订阅请求的 `delivery.mode` 共用以下枚举。
101
+
102
+ | 值 | 含义 |
103
+ | --- | --- |
104
+ | `webhook` | 通过 HTTP 回调投递,验证与安全要求见 [回调验证与投递](#回调验证与投递) |
105
+
106
+ ### 创建与续期
107
+
108
+ | 请求字段 | 豆包契约 |
109
+ | --- | --- |
110
+ | `name` | 发现结果中的事件名 |
111
+ | `arguments` | 符合该事件 inputSchema 的过滤参数;参数指向的资源须通过当前用户权限校验 |
112
+ | `delivery.mode` | 见 [投递模式枚举](#投递模式枚举),所选模式须由目标事件的 `delivery` 声明 |
113
+ | `delivery.url` | 客户端为本任务提供的公网 HTTPS 回调地址 |
114
+ | `delivery.secret` | `whsec_` 加 Base64,解码后 24~64 字节;签名密钥,不参与订阅身份 |
115
+ | `cursor` | 固定 null |
116
+ | `ttlMs` | 可省略的期望有效期,单位毫秒;豆包不请求 null 的永久订阅 |
117
+
118
+ 订阅请求示例:
119
+
120
+ ```json
121
+ {
122
+ "jsonrpc": "2.0",
123
+ "id": 2,
124
+ "method": "events/subscribe",
125
+ "params": {
126
+ "name": "live.room.started",
127
+ "arguments": { "anchor_id": "a_12345" },
128
+ "delivery": {
129
+ "mode": "webhook",
130
+ "url": "https://callback.example.com/mcp-events/task-1",
131
+ "secret": "whsec_<客户端生成的随机密钥的 Base64>"
132
+ },
133
+ "cursor": null,
134
+ "ttlMs": 3600000
135
+ }
136
+ }
137
+ ```
138
+
139
+ 服务端校验用户权限、参数和回调,完成签名 challenge 验证并持久保存订阅后返回;服务重启不得丢失有效期内的订阅:
140
+
141
+ ```json
142
+ {
143
+ "jsonrpc": "2.0",
144
+ "id": 2,
145
+ "result": {
146
+ "id": "sub_demo",
147
+ "refreshBefore": "2026-11-12T11:00:00Z",
148
+ "cursor": null,
149
+ "truncated": false
150
+ }
151
+ }
152
+ ```
153
+
154
+ 订阅结果的 `cursor` 固定为 null,`truncated` 固定为 false。外层 `id` 匹配这次 RPC;`result.id` 是订阅编号,后续通过 `X-MCP-Subscription-Id` 携带。`refreshBefore` 是实际授予的 ISO 8601 到期时间,不能仅用请求的 ttlMs 推算。
155
+
156
+ 同一用户、回调 URL、事件名和规范化 arguments 确定同一订阅。重复 subscribe 返回相同订阅 ID,更新有效期及密钥;参数对象的键顺序不改变身份。密钥和 ttlMs 不参与身份,同一用户的不同任务用不同回调 URL 区分。未提供 ttlMs 时使用服务端默认期限;授予期限不应超过请求值,但请求值小于服务端最低期限时可提高到最低期限。
157
+
158
+ ### 回调验证与投递
159
+
160
+ 回调仅接受公网 HTTPS;每次连接重新校验解析后的 IP,直连已校验 IP 并保留原主机名用于 TLS,不跟随重定向。每条正文不得超过 256 KiB。
161
+
162
+ 订阅成功前,服务端向回调 URL 发送签名的验证正文:
163
+
164
+ ```json
165
+ {"type": "verification", "challenge": "example-one-time-nonce"}
166
+ ```
167
+
168
+ 接收端按 [Webhook security](../upstream/mcp-events.md#webhook-security) 验签后,返回 2xx 与以下正文;服务端常量时间比较 challenge,单纯返回 2xx 不代表验证成功:
169
+
170
+ ```json
171
+ {"challenge": "example-one-time-nonce"}
172
+ ```
173
+
174
+ 同一用户、同一回调地址可短暂缓存验证成功的结果;URL 白名单不能代替 challenge 验证。
175
+
176
+ 验证消息的 `webhook-id` 为 `msg_verification_<随机串>`。业务消息的 `webhook-id` 则等于 eventId,且带上对应订阅编号,例如:
177
+
178
+ ```text
179
+ Content-Type: application/json
180
+ webhook-id: evt_live_room_98765
181
+ webhook-timestamp: <本次签名的 Unix 秒数>
182
+ webhook-signature: v1,<按原始正文计算的 Base64 签名>
183
+ X-MCP-Subscription-Id: sub_demo
184
+ ```
185
+
186
+ ```json
187
+ {
188
+ "eventId": "evt_live_room_98765",
189
+ "name": "live.room.started",
190
+ "timestamp": "2026-11-12T10:20:00Z",
191
+ "data": { "room_id": "room_98765" },
192
+ "cursor": null
193
+ }
194
+ ```
195
+
196
+ 复用 Standard Webhooks 签名库,签名和发送使用同一份原始正文字节,接收端验签并校验 5 分钟时间容差。固定提案将消息 ID 与事件 ID 分离;豆包使用 eventId 作为业务 webhook-id,因此须按订阅隔离去重,避免同一事件命中多个任务时被误丢弃。
197
+
198
+ 验签、去重并确认接收后返回 2xx,再异步处理任务,必要时调用 get_live_room 读取详情。2xx 不表示任务完成。重试保留事件 ID 和发生时间,更新签名时间;网络错误、超时和 5xx 有限退避重试,建议 3~5 次且总时长不超过 15 分钟,429 遵循 Retry-After,3xx 和其他 4xx 不重试当前事件,410 不取消整个订阅。
199
+
200
+ ### 取消订阅
201
+
202
+ ```json
203
+ {
204
+ "jsonrpc": "2.0",
205
+ "id": 4,
206
+ "method": "events/unsubscribe",
207
+ "params": {
208
+ "name": "live.room.started",
209
+ "arguments": { "anchor_id": "a_12345" },
210
+ "delivery": {
211
+ "mode": "webhook",
212
+ "url": "https://callback.example.com/mcp-events/task-1"
213
+ }
214
+ }
215
+ }
216
+ ```
217
+
218
+ 用户删除或暂停任务时取消,恢复任务时重新订阅;无法取消时停止续期。订阅取消、过期或用户失权后停止投递,每次重试前也重新检查。
219
+
220
+ 取消按原订阅身份匹配,用户由请求令牌确定,不传 secret 或订阅 ID。取消成功及订阅不存在时均返回以下结果:
221
+
222
+ ```json
223
+ {"jsonrpc": "2.0", "id": 4, "result": {}}
224
+ ```
225
+
226
+ ### 错误响应
227
+
228
+ 回调未正确回显 challenge 时,subscribe 失败且不启用投递。例如:
229
+
230
+ ```json
231
+ {
232
+ "jsonrpc": "2.0",
233
+ "id": 2,
234
+ "error": {
235
+ "code": -32015,
236
+ "message": "Callback verification failed",
237
+ "data": { "reason": "challenge_failed" }
238
+ }
239
+ }
240
+ ```
241
+
242
+ 其他错误见[错误码差异](#错误码差异)。客户端依赖编号和结构化 data,不匹配示例中的 message 文案。
243
+
244
+ ## 兼容边界
245
+
246
+ 本接入不提供历史回放及 `gap` / `terminated` 控制消息。
247
+
248
+ 豆包现有 Events 报文示例未声明提案要求的 `resultType`,本页保留该差异,不据此判定字段应永久省略。接入时需确认目标宿主采用的公共响应格式,不能宣称与固定提案完全兼容;提案中的 `deliveryStatus`、Server Card 签名公钥及出网地址声明也不表示豆包已支持。
249
+
250
+ 事件 Schema 可增加可选字段;删除、改名、改变字段类型或收紧过滤参数时使用新事件名,并为旧订阅保留迁移时间。能力发现成功不代表订阅、回调验证或业务投递已成功。
251
+
252
+ ## 主动触达能力边界
253
+
254
+ 安装插件包不会自动为安装用户建立后台调度或定时提醒。交付主动提醒前,需核实目标宿主、安装用户身份与授权、服务事件能力、回调和取消方式。开发助手账号里的定时任务、订阅或长期后台进程不能作为可分发插件的提醒能力。
255
+
256
+ 未核实完整链路时,明确尚未满足的主动触达需求,可提供用户主动调用的“检查 / 查询”工具。用户坚持主动触达时说明缺少的宿主或服务能力,不用开发助手账号的订阅代替。
257
+
258
+ ## 联调与验收
259
+
260
+ 当前 `dbx inspect` 没有事件订阅和回调验收入口。分别验证能力与事件发现、challenge 回显、一次业务投递、续期保持同一订阅 ID、取消后停止投递,并清理测试订阅。普通工具调用成功不能证明事件链路成功;接入检查本身不授权创建长期任务。
@@ -0,0 +1,95 @@
1
+ # 根清单:plugin.json
2
+
3
+ 维护应用插件身份、展示信息及插件级扩展。修改已有文件时按字段合并,保留已有身份和其他能力配置。
4
+
5
+ ## 文件位置与最小示例
6
+
7
+ 固定为插件根目录的 `plugin.json`,内容为 JSON 对象:
8
+
9
+ ```json
10
+ {
11
+ "name": "my-plugin",
12
+ "publicationType": "PUBLIC",
13
+ "description": "根据关键词搜索商品"
14
+ }
15
+ ```
16
+
17
+ 这是根清单的最小示例;业务能力由 [目录索引](../cli/project.md#文件协议索引) 中的对应文件声明。
18
+
19
+ ## 根字段
20
+
21
+ | 字段 | 类型 | 必填 | 约束与取值来源 |
22
+ | --- | --- | --- | --- |
23
+ | `$schema` | string | 否 | 可引用 `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`;该通用 schema 不包含全部平台字段 |
24
+ | `name` | string | 是 | 稳定包标识,1~64 字符;小写字母、数字、点号或连字符,首尾为字母或数字,不含连续 `--` 或 `..` |
25
+ | `id` | string | 否 | 开放平台 AbilityID,保存草稿后由 CLI 回填,不自行生成;与 ActionHub PluginID、App 的 `app_key` 分别维护 |
26
+ | `publicationType` | string | 否 | CLI 配置,`PUBLIC` 或 `ENTERPRISE`;由 `init --type` 保存,已有平台主体不可切换类型 |
27
+ | `version` | string | 否 | 作者包版本,提供时须与发布提交一致;CLI 覆盖方式见 [上传与预览](../cli/release.md#上传与预览) |
28
+ | `description` | string | 否 | 插件用途,最多 300 字符;与展示简介分开处理 |
29
+ | `extensions` | object | 按能力 | 每个扩展命名空间的值为对象;豆包字段放在 `extensions["com.doubao"]` |
30
+
31
+ 修改展示名称时保留 `name`。`id` 只用于 App 调试、上传、审核、版本等开放平台路径;Skill / MCP 的个人调试不查询能力草稿,也不要求存在 `ability_id`。以下身份与类型核对仅用于开放平台路径:有 `id` 时优先按 ID 定位,无 ID 时按名称和发布类型定位。缺少 ID 和类型的旧项目按 PUBLIC 处理;有 ID 而缺少类型时,CLI 查询平台后补回,查询失败或类型无效时停止。已有类型与平台主体不一致时应恢复配置,不能通过删除身份字段绕过。
32
+
33
+ 根清单不用于改写各能力的固定文件位置,也不自行增加协议未定义的顶层字段。
34
+
35
+ ## 展示字段
36
+
37
+ 以下字段均位于 `extensions["com.doubao"]`:
38
+
39
+ | 字段 | 类型 | 必填 | 约束与缺省行为 |
40
+ | --- | --- | --- | --- |
41
+ | `displayName` | 多语言对象 | 否 | 每值最多 128 字符;缺省使用根 `name` |
42
+ | `displayDescription` | 多语言对象 | 否 | 每值最多 1024 字符;缺省使用根 `description`,根简介也缺失时不展示 |
43
+ | `icon` | string | 含 App 时有条件必填 | 包内主图标路径;缺省使用客户端默认图标,规格见 [图标要求](../cli/release.md#上传物料与图标) |
44
+ | `chatIcon` | string | 否 | 对话图标路径;缺省复用 `icon`,无可用主图标时使用客户端默认图标 |
45
+ | `mcpServers.<服务键>.displayName` | 多语言对象 | 每个 MCP 必填 | 每值最多 128 字符;服务键来自 `mcp.json` |
46
+ | `mcpServers.<服务键>.displayDescription` | 多语言对象 | 每个 MCP 必填 | 每值最多 1024 字符,描述整个服务 |
47
+ | `mcpServers.<服务键>.icon` | string | 否 | 相对包根的图标;缺失或不可用时依次回退 Plugin 图标、客户端默认图标 |
48
+
49
+ 多语言对象的键为小写两字母语言代码,如 `zh`、`en`,不用 `zh-CN`;值为字符串,每个对象至少一个值非空,长度逐值检查,不能用 `null`。展示时优先选择非空 `zh`,其次非空 `en`。图标路径规则见 [路径与打包](../cli/project.md#路径与打包)。
50
+
51
+ 运行时读取缺少展示文案的导入包时,MCP 名称回退到 `mcp.json` 的服务键,缺少简介时不展示,不用某个工具的说明代替。
52
+
53
+ 运行时回退不改变服务键、工具定义或发布必填要求。Skill 的展示规则见 [业务 Skill](business-skills.md#frontmatter-字段)。
54
+
55
+ 例如,为 `mcp.json` 中的 `shopping` 服务添加展示信息:
56
+
57
+ ```json
58
+ {
59
+ "extensions": {
60
+ "com.doubao": {
61
+ "displayName": { "zh": "商品助手" },
62
+ "mcpServers": {
63
+ "shopping": {
64
+ "displayName": { "zh": "商品搜索" },
65
+ "displayDescription": { "zh": "按关键词搜索商品" }
66
+ }
67
+ }
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ 此处仅为合并片段,不能覆盖整个根清单。展示配置与 `mcp.json.mcpServers` 的键集合必须一致;`shopping` 是服务键,不是工具名 `search_products`。
74
+
75
+ ## 商店可见平台
76
+
77
+ `extensions["com.doubao"].pluginVisiblePlatforms` 为可选字符串数组,元素仅允许 `pc`、`web`、`mobile`,区分大小写。例如 `["pc", "web"]`。缺省或 `[]` 表示全平台可见;移动端统一用 `mobile`,不使用 `ios`、`android` 或 `vm`。
78
+
79
+ 该字段仅过滤整包在商店列表、搜索和精选中的展示,不影响已安装列表、按 ID 查询或运行能力。它与 `publicationType`、企业审核的 `--visibility self|tenant` 分别处理,不提供模块级覆盖。
80
+
81
+ CLI 可保留该字段上传,但不预览商店过滤效果;实际展示需在目标平台验证。
82
+
83
+ ## 公开上架合规声明
84
+
85
+ 以下字段也位于 `extensions["com.doubao"]`,使用开发者提供的实际声明和链接:
86
+
87
+ | 字段 | 类型 | 必填条件 | 约束与默认值 |
88
+ | --- | --- | --- | --- |
89
+ | `privacyPolicyUrl` | string | 商店提审必填 | 非空 HTTPS 绝对 URL,无默认值 |
90
+ | `isMinorIncluded` | string | 商店提审必填 | 仅 `"true"` 或 `"false"`,无默认值;不得替开发者推断 |
91
+ | `specialLicenseUrl` | string | 否 | 提供时为非空 HTTPS 绝对 URL |
92
+
93
+ 缺失声明不阻断上传、调试或创建版本;提审前须补齐。填写 `"true"` 时,隐私政策需说明未成年人个人信息处理规则。
94
+
95
+ 交互提审时核对表单中的声明选择,流程见 [版本交付与审核](../cli/release.md#公开上架合规声明)。
@@ -0,0 +1,120 @@
1
+ # 工作台包协议
2
+
3
+ 定义工作台包的静态配置,包括 `com.doubao/workbench/` 下的 Manifest、预装资源和随包 HTML。页面与宿主通信见 [Workbench 运行时协议](mcp-apps/workbench.md)。
4
+
5
+ 项目创建和资源搜索见 [项目配置](../cli/project.md),完整配置见 [合同工作台示例](../examples/workbench-example.md)。普通 MCP Apps 的工具与 UI Resource 声明见 [MCP Apps 接入](mcp-apps/integration.md)。
6
+
7
+ ## 工作台作者配置
8
+
9
+ `com.doubao/workbench/manifest.json` 声明豆包工作台的区域和页面来源。工作台的包版本由 `plugin.json.version` 声明。
10
+
11
+ | 字段 | 类型 | 必填 | 约束与缺省行为 |
12
+ | --- | --- | --- | --- |
13
+ | `schemaVersion` | string | 是 | 固定为 `"1.0"` |
14
+ | `additionalContext` | string | 否 | 工作台启用时供模型理解业务背景、术语和回答要求,缺省或空字符串时不提供 |
15
+ | `reconfig` | object | 否 | 按区域配置界面,缺省区域使用宿主界面 |
16
+
17
+ 工具调用仍按使用者授权及服务端规则校验。`additionalContext` 不得作为工具授权或业务校验的依据。
18
+
19
+ `reconfig` 的键决定界面区域;`nav.rail` 和 `settings.more-menu` 各是一个完整的 JSON 键。
20
+
21
+ Manifest 的 `entrypoint.type` 枚举:
22
+
23
+ | 值 | 含义 |
24
+ | --- | --- |
25
+ | `global` | 入口不绑定具体会话 |
26
+
27
+ 各区域的模式与目标如下。
28
+
29
+ | 区域 | 模式与目标 |
30
+ | --- | --- |
31
+ | `home` | `overlay` 配置欢迎区和推荐。`takeover` 使用 `entrypoint.target.type: "html"` 加载随包首页,两种模式的字段分开填写 |
32
+ | `nav.rail` | `overlay` 追加导航入口,入口目标为 `mcp-tool` |
33
+ | `settings.more-menu` | `overlay` 追加菜单项。每项通过 `entrypoint` 打开 `mcp-tool` 页面,或通过 `action` 的 `open-link` 动作打开 HTTPS 链接 |
34
+
35
+ 各区域的字段要求如下,完整配置见 [合同工作台示例](../examples/workbench-example.md#工作台-manifest)。
36
+
37
+ | 配置项 | 要求与缺省行为 |
38
+ | --- | --- |
39
+ | 欢迎区 `welcome` | 标题和图标可省略,分别回退到宿主问候语和工作台图标 |
40
+ | 推荐 `suggestions` | 同一 `type + id` 只声明一组;每个推荐项的 `text` 必须非空白,`prompt` 缺省或为空时用 `text` 预填输入框 |
41
+ | 导航项 | `text` 缺省时使用工具名,`icon` 缺省时使用宿主图标 |
42
+ | 菜单项 | `id` 在区域内唯一且稳定,`text` 必须非空白,`icon` 可省略 |
43
+
44
+ 各区域的图标路径相对 `com.doubao/workbench/`,例如 `assets/welcome.png`。插件列表图标另按 [根清单](plugin-json.md#展示字段) 配置。
45
+
46
+ `mcp-tool` 目标通过两个字段定位工具:
47
+
48
+ - `server`:当前包 `mcp.json` 中的服务键。
49
+ - `name`:该服务在 `tools/list` 中返回的工具名。
50
+
51
+ 目标工具接受 `{}`,声明 `global` 入口并关联支持 `fullscreen` 的 UI Resource,具体字段见 [MCP Apps 静态入口](mcp-apps/integration.md#静态入口与-ui-来源)。`html` 目标则由宿主直接加载随包页面,初始化后可按权限调用业务工具。
52
+
53
+ ## 预装资源声明
54
+
55
+ `com.doubao/workbench/preinstall-resources.json` 是独立于 Manifest 的可选文件。根字段 `preinstallResources` 是数组,每项引用一个已有 Skill 或插件。没有预装项时,可省略文件或填写空数组。字段值从 [CLI 的资源搜索结果](../cli/project.md#配置工作台预装资源)获取。
56
+
57
+ | 字段 | 类型 | 必填 | 约束 |
58
+ | --- | --- | --- | --- |
59
+ | `type` | string | 是 | `skill` 或 `plugin` |
60
+ | `id` | string | 是 | 来源下稳定的非空资源 ID,按搜索返回的字符串保存 |
61
+ | `source` | string | 是 | 见 [资源来源枚举](#资源来源枚举),区分大小写;按工作台发布类型选择可预装来源 |
62
+
63
+ ### 资源来源枚举
64
+
65
+ `dbx workbench search --source` 和预装声明的 `source` 共用以下枚举,预装资格按表中的发布类型判断。
66
+
67
+ | 值 | 含义 | 公开工作台预装 | 企业专属工作台预装 |
68
+ | --- | --- | --- | --- |
69
+ | `official` | 已发布的官方 Skill | 支持 | 支持 |
70
+ | `store` | 商店资源 | 支持 | 支持 |
71
+ | `enterprise` | 企业资源 | 不支持 | 本企业资源 |
72
+ | `personal` | 个人资源 | 不支持 | 不支持 |
73
+
74
+ 同一 `type + id` 必须唯一。首页 `suggestions[].target` 按这两个字段匹配预装声明,`source` 由预装声明提供。
75
+
76
+ 安装工作台时平台发起预装,关联入口取决于资源的安装及授权状态。单个资源不可用时工作台仍可使用;移除预装声明不会卸载已安装的资源。
77
+
78
+ ## Takeover 随包 HTML 首页
79
+
80
+ 下面的 Manifest 接管首页并请求一项启动数据。`web/home.html` 及其静态资源随工作台一起发布。
81
+
82
+ ```json
83
+ {
84
+ "schemaVersion": "1.0",
85
+ "reconfig": {
86
+ "home": {
87
+ "mode": "takeover",
88
+ "entrypoint": {
89
+ "type": "global",
90
+ "target": {
91
+ "type": "html",
92
+ "html": {
93
+ "path": "web/home.html",
94
+ "startupCalls": [
95
+ { "server": "legal", "name": "get_contract_summary", "arguments": {} }
96
+ ]
97
+ }
98
+ }
99
+ }
100
+ }
101
+ }
102
+ }
103
+ ```
104
+
105
+ `html` 对象的字段如下。
106
+
107
+ | 字段 | 约束 |
108
+ | --- | --- |
109
+ | `path` | 相对 `com.doubao/workbench/`,指向 `web/` 下实际存在的 HTML 文件;不得越出目录或包含查询参数、片段 |
110
+ | `startupCalls` | 可省略,最多 32 项;使用包内声明的服务和只读工具,`arguments` 符合工具输入 schema,省略时为 `{}` |
111
+ | `csp` | 按需声明 `connectDomains`、`resourceDomains`、`frameDomains`、`baseUriDomains` |
112
+ | `permissions` | 按需声明权限,键及对应取值见下表 |
113
+
114
+ `permissions` 的权限枚举:
115
+
116
+ | 权限键 | 值 | 用途 |
117
+ | --- | --- | --- |
118
+ | `clipboardWrite` | `{}` | 申请剪贴板写入权限 |
119
+
120
+ 页面内的相对引用以 HTML 所在目录为基准。静态首页可省略 `startupCalls`;全包无需访问 MCP 时可省略 `mcp.json`。通过宿主调用 MCP 无需把服务地址加入 `connectDomains`。
@@ -0,0 +1,24 @@
1
+ # 协议快照来源
2
+
3
+ 本目录保存上游协议原文与许可证,按接入指引选择需要的章节。原文中的背景资料与外部链接仅供补充查阅。
4
+
5
+ ## 上游标准快照
6
+
7
+ 快照日期:2026-11-13。固定到下列提交,更新时核对协议变化后再替换。文档仅在有相对链接时增加页首说明,并将相对链接解析为对应固定提交的上游地址;其余正文及许可证保持原样。
8
+
9
+ | 本地文件 | 上游原文 | 固定提交 | 许可证 |
10
+ | --- | --- | --- | --- |
11
+ | [mcp-events.md](mcp-events.md) | [modelcontextprotocol/modelcontextprotocol: seps/3415-events-extension.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/f77a5fe31b91c052dbfc2a37add98b9e84662b34/seps/3415-events-extension.md) | `f77a5fe31b91c052dbfc2a37add98b9e84662b34` | [上游 Apache-2.0 / MIT 过渡声明](mcp-events.LICENSE) |
12
+ | [standard-webhooks.md](standard-webhooks.md) | [standard-webhooks/standard-webhooks: spec/standard-webhooks.md](https://github.com/standard-webhooks/standard-webhooks/blob/f72db81617ce7c285e99d7734ff2480303328377/spec/standard-webhooks.md) | `f72db81617ce7c285e99d7734ff2480303328377` | [Apache-2.0](standard-webhooks.LICENSE) |
13
+ | [mcp-apps.mdx](mcp-apps.mdx) | [modelcontextprotocol/ext-apps: specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/ea3e9d0e624a20bc1c51310292f09d9b8ed17161/specification/2026-01-26/apps.mdx) | `ea3e9d0e624a20bc1c51310292f09d9b8ed17161` | [上游 Apache-2.0 / MIT 过渡声明](mcp-apps.LICENSE) |
14
+
15
+ ## SHA-256
16
+
17
+ | 文件 | 下载原文 | 随包副本 |
18
+ | --- | --- | --- |
19
+ | `mcp-events.md` | `03b454b6c877cd93dded5827c6b8bf315cde0e839bd2e51ce1b752bd5f04e87b` | `804f008c54f32a15434acfc5581ceffcb715e81a6158d611b0199a66681a1432` |
20
+ | `standard-webhooks.md` | `c9a80952a2a6a34fb456ae9614483b7d9b8563fe5eb8f328f3d138f1e765ac31` | `fc0f69754c9c09369edc08acfc3c52ae10094f2113f824cd49512e6862b16a60` |
21
+ | `mcp-apps.mdx` | `ee452a7d1b9b7fb900acfeb4d6932d3963375b0f3f37d196a4b93eb80312af0e` | `ee452a7d1b9b7fb900acfeb4d6932d3963375b0f3f37d196a4b93eb80312af0e` |
22
+ | `mcp-events.LICENSE` | `0382b0057770ca05e9c350a50aa3b1c1fea84da0bc81d723bf00b9aa841be58a` | `0382b0057770ca05e9c350a50aa3b1c1fea84da0bc81d723bf00b9aa841be58a` |
23
+ | `standard-webhooks.LICENSE` | `c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4` | `c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4` |
24
+ | `mcp-apps.LICENSE` | `0382b0057770ca05e9c350a50aa3b1c1fea84da0bc81d723bf00b9aa841be58a` | `0382b0057770ca05e9c350a50aa3b1c1fea84da0bc81d723bf00b9aa841be58a` |