@doubao-dev/cli 1.0.0-rc.0 → 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.
- package/README.md +12 -5
- package/bin/run.js +1 -6
- package/dist/691.js +96 -0
- package/dist/691.js.LICENSE.txt +13 -0
- package/dist/build.js +1 -0
- package/dist/categories.js +1 -1
- package/dist/command.js +9 -2
- package/dist/command~1.js +4 -4
- package/dist/command~2.js +1 -1
- package/dist/command~3.js +2 -1
- package/dist/command~4.js +1 -1
- package/dist/command~5.js +6 -2
- package/dist/dist.js +1 -1
- package/dist/draft.js +2 -2
- package/dist/index.d.ts +892 -11
- package/dist/index.js +1 -1
- package/dist/main.d.ts +892 -11
- package/dist/main.js +1 -1
- package/dist/mcp-apps-inspector.js +1 -0
- package/dist/multipart-parser.js +2 -0
- package/dist/open.js +2 -0
- package/dist/plugin.js +3 -1
- package/dist/plugin.js.LICENSE.txt +58 -0
- package/dist/preview.js +9 -0
- package/dist/progress.js +1 -0
- package/dist/ratatui-ui.js +1 -1
- package/dist/rslib-runtime.js +1 -0
- package/dist/session.js +2 -1
- package/dist/session.js.LICENSE.txt +1 -0
- package/dist/skills/doubao-plugin-cli/SKILL.md +44 -40
- package/dist/skills/doubao-plugin-cli/references/cli/development.md +126 -0
- package/dist/skills/doubao-plugin-cli/references/cli/project.md +188 -0
- package/dist/skills/doubao-plugin-cli/references/cli/release.md +144 -0
- package/dist/skills/doubao-plugin-cli/references/examples/todo-example.md +88 -0
- package/dist/skills/doubao-plugin-cli/references/examples/workbench-example.md +130 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/business-skills.md +49 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/cli-connectors.md +56 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/managed-agents.md +46 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/integration.md +186 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/runtime.md +318 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/workbench.md +180 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-auth.md +73 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-config.md +145 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-events.md +260 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/plugin-json.md +95 -0
- package/dist/skills/doubao-plugin-cli/references/protocols/workbench.md +120 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/SOURCES.md +24 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.LICENSE +216 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.mdx +1768 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.LICENSE +216 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.md +1231 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.LICENSE +201 -0
- package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.md +349 -0
- package/dist/templates/standard/AGENTS.md +1 -1
- package/dist/templates/workbench/README.md.template +9 -0
- package/dist/templates/workbench/com.doubao/workbench/manifest.json +10 -0
- package/dist/uninstall.js +1 -1
- package/dist/versions.js +1 -1
- package/dist/versions~1.js +1 -0
- package/dist/web/index.html +1 -0
- package/dist/web/sandbox-proxy.html +101 -0
- package/dist/web/static/css/index.b3102f16b9.css +1 -0
- package/dist/web/static/js/155.747f5232dc.js +69 -0
- package/dist/web/static/js/async/970.86106314b5.js +1 -0
- package/dist/web/static/js/index.c1186260b9.js +4 -0
- package/dist/web/static/js/lib-react.00514652bf.js +2 -0
- package/dist/web/static/js/lib-react.00514652bf.js.LICENSE.txt +39 -0
- package/dist/workbench-search.js +1 -0
- package/dist/xdg-open +1267 -0
- package/package.json +17 -16
- package/dist/472.js +0 -9
- package/dist/schema.js +0 -1
- package/dist/skills/doubao-plugin-cli/references/cli-connectors.md +0 -29
- package/dist/skills/doubao-plugin-cli/references/development.md +0 -29
- package/dist/skills/doubao-plugin-cli/references/mcp-apps.md +0 -40
- package/dist/skills/doubao-plugin-cli/references/mcp-auth.md +0 -23
- package/dist/skills/doubao-plugin-cli/references/project-config.md +0 -139
- package/dist/skills/doubao-plugin-cli/references/upload.md +0 -71
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# 开发调试
|
|
2
|
+
|
|
3
|
+
## 选择调试目标
|
|
4
|
+
|
|
5
|
+
| 命令 | 行为 |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `dbx dev` | 工作台工程默认调试工作台,普通插件默认同步并个人安装 Skill / MCP 开发包。含 App 的项目在交互终端可切换到 App 调试 |
|
|
8
|
+
| `dbx dev --plugin` | 显式选择 Skill / MCP 调试,上传开发包并安装到当前登录账号 |
|
|
9
|
+
| `dbx dev --app` | App 本地编译和 Web 模拟器,不同步个人开发包;缺少插件 ID 时,会上传完整项目并保存平台草稿 |
|
|
10
|
+
| `dbx dev --workbench` | 上传工作台配置、资源及同工程的 MCP,并安装到当前登录账号 |
|
|
11
|
+
| `dbx dev --plugin --once` | 同步安装一次 Skill / MCP 开发包,成功退出 `0`,失败非零 |
|
|
12
|
+
| `dbx dev --workbench --once` | 同步安装一次工作台开发包,成功退出 `0`,失败非零 |
|
|
13
|
+
| `dbx inspect --mcp-server <endpoint>` | 直接调试 MCP Server 或 MCP Apps 的工具、资源和 HTML 界面,无需应用插件项目或开放平台登录 |
|
|
14
|
+
|
|
15
|
+
`--plugin`、`--app` 和 `--workbench` 互斥。非 TTY 运行 `dbx dev` 沿用默认目标,可按本次任务显式指定目标。
|
|
16
|
+
|
|
17
|
+
仅需同步安装一次时使用 `--once`,持续修改并自动同步时省略。`dbx dev --once` 按工程类型选择普通插件或工作台,不询问是否启动 App;`--once` 不支持 `--app`。
|
|
18
|
+
|
|
19
|
+
## 启动调试
|
|
20
|
+
|
|
21
|
+
`dbx dev` 需要有效登录态。交互终端未登录时会发起授权,非 TTY 环境按 [开放平台登录](../../SKILL.md#开放平台登录) 先核对身份。
|
|
22
|
+
|
|
23
|
+
普通插件已有 `id` 时,启动调试前会查询平台草稿并核对发布类型;定制工作台调试不执行这项查询。App 调试须允许上表所述的远端初始化;仅授权本地操作时,不执行所需的上传。初始化或草稿查询失败时,按实际错误核对平台记录。模拟器和设备操作见 `doubao-plugin-app` Skill 的 `references/app-development.md`。
|
|
24
|
+
|
|
25
|
+
新增或移除 App 后重启并选择调试目标。要保存版本或生成 App 预览,按 [版本交付与审核](release.md) 操作。
|
|
26
|
+
|
|
27
|
+
### 确认首次同步结果
|
|
28
|
+
|
|
29
|
+
单次模式等待命令结束并核对退出码;失败后按错误修复并重新执行。
|
|
30
|
+
|
|
31
|
+
持续模式收到「已同步」后即可继续验证,不等待进程退出。同步失败后,修复日志中提示的问题;修改监听范围内的文件可触发重试,仅恢复网络或登录时需重启命令。
|
|
32
|
+
|
|
33
|
+
直接读取执行会话输出,或完整保存 stdout/stderr 后单独读取日志文件。不要把持续模式接到 `head` 等截取命令:它可能等待更多输出或缓冲日志,空日志不能证明同步仍在进行。
|
|
34
|
+
|
|
35
|
+
读取实际同步日志,确认开发包上传及当前账号安装结果,记录可用的包标识或错误信息。进程存活或出现启动日志不等于已安装;无需为验证安装执行 `dbx upload` 保存版本。
|
|
36
|
+
|
|
37
|
+
分别记录开发包安装、MCP 工具调用、UI 资源读取和目标宿主交互结果。前一阶段成功不能代替后一阶段;Inspector 也不能证明账号安装成功。只报告已经观察到的阶段,未验证的宿主能力保留待验。
|
|
38
|
+
|
|
39
|
+
## 工作台体验
|
|
40
|
+
|
|
41
|
+
工作台日志显示「定制工作台:已同步」后,在豆包工作 PC 左上角点「豆包工作」→「更多工作台」,或从侧栏「插件 · 技能 · 工作台」进入「工作台」页签,选择对应工作台的开发版。入口名称以当前客户端实际显示为准,也可提供 [工作台列表](https://www.doubao.com/chat/skills/workbench)。具体业务检查见 [合同工作台示例](../examples/workbench-example.md#同步与试用)。
|
|
42
|
+
|
|
43
|
+
平台提示当前账号未开放工作台调试时,记录目标账号、环境和请求 LogID,核查调试权限。同步成功但列表没有对应工作台或开发版入口时,取得实际页面信息,核对同步账号和客户端状态。
|
|
44
|
+
|
|
45
|
+
## 配置变更的同步边界
|
|
46
|
+
|
|
47
|
+
| 调试目标 | 自动同步的文件 |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| `--plugin` | `skills/`、`mcp.json`、`plugin.json` |
|
|
50
|
+
| `--workbench` | `com.doubao/workbench/`、`mcp.json`、`plugin.json` |
|
|
51
|
+
|
|
52
|
+
修改范围以外的文件(如 `com.doubao/auth/` 或插件图标)后,重启对应会话并等待首次同步完成。
|
|
53
|
+
|
|
54
|
+
各能力按对应指引校验和调试:MCP 连接见 [MCP 配置](../protocols/mcp-config.md#修改与验证),工作伙伴见 [工作伙伴声明](../protocols/managed-agents.md#修改与验证)。授权交互和运行效果在支持对应能力的目标宿主验证。
|
|
55
|
+
|
|
56
|
+
## MCP 服务准备
|
|
57
|
+
|
|
58
|
+
已有服务或托管项目优先复用。只有业务 HTTP API、网页或名称包含 MCP 时,先核实协议与工具;认证失败按 [MCP 鉴权](../protocols/mcp-auth.md#按失败环节排查) 处理,不因此重建服务。
|
|
59
|
+
|
|
60
|
+
### 选择开发与部署路线
|
|
61
|
+
|
|
62
|
+
| 当前条件 | 处理方式 |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| 用户已选定服务或平台 | 沿用原项目与部署身份,使用该平台的文档和工具 |
|
|
65
|
+
| 需要新建或扩展服务,路线未定 | 比较现有受控服务器与当前可用托管工具;工具可用本身不构成选择依据 |
|
|
66
|
+
| 路线会改变成本、产物或部署范围 | 说明差异并确认;用户已授权选择时直接决定,常规可逆本地实现无需反复确认 |
|
|
67
|
+
| 用户接受仅本地交付 | 本地开发与验证,明确远程接入尚未完成 |
|
|
68
|
+
| 已选 App 且用户接受不交付 MCP | 可在原应用内实现受支持的能力或调用已有业务 API;不承担服务端秘密或后台常驻任务 |
|
|
69
|
+
|
|
70
|
+
派生新服务时保留原项目;原地扩展须符合本次目标。仅授权本地开发时可继续实现与验证,部署和远端创建仍按本次授权执行。业务身份由后端或宿主提供,不从操作系统用户、环境变量或开发者登录态推断安装用户。
|
|
71
|
+
|
|
72
|
+
### 部署条件与地址受阻
|
|
73
|
+
|
|
74
|
+
本地 Inspector 联调与账号远程接入的地址条件不同,发布地址按 [MCP 配置](../protocols/mcp-config.md#文件级与关联约束) 执行。地址被拒时保留本地成果,核对已有受控托管条件及数据、凭据允许迁移的范围。
|
|
75
|
+
|
|
76
|
+
不使用内网穿透、临时公网隧道或端口映射绕过部署要求,不改地址伪装合规,不关闭鉴权、TLS 校验和访问控制。没有安全可行路线时说明阻塞并继续本地准备;仅本地交付须符合用户目标。
|
|
77
|
+
|
|
78
|
+
### 委托生成与接入
|
|
79
|
+
|
|
80
|
+
委托平台或其他 Agent 时,传递本次业务需求、输入输出契约、资产、身份与持久化要求、原项目身份及交付范围。MCP Apps 按 [接通工具与界面](../protocols/mcp-apps/integration.md#接通工具与界面) 明确工具与 UI 目标;接收方无法读取本地资料时补充必要契约,不只提供本地路径。
|
|
81
|
+
|
|
82
|
+
按平台实际接口处理附件、鉴权、发布和源码回收。回收正式 MCP endpoint、传输与鉴权方式、服务与环境身份、部署结果及未验证项,再写入插件配置。只返回网页或缺少必要能力时,从原项目或本次委托结果补查,不重建项目。
|
|
83
|
+
|
|
84
|
+
MCP Apps 目标同时包含服务与宿主内 UI;已有应用插件继续使用原前端。普通网页、业务 API 或应用内 API 调用不等同于 MCP 交付。验证按下文与对应协议执行,平台生成或部署成功不能代替业务验收。
|
|
85
|
+
|
|
86
|
+
## 单独调试 MCP Server
|
|
87
|
+
|
|
88
|
+
`dbx inspect --mcp-server <endpoint>` 连接 Streamable HTTP 服务,本地地址也可用。运行 `dbx inspect --mcp-server` 可省略地址,沿用上次的连接,首次使用在界面填写。用 `-H "Key: Value"` 传服务需要的请求头,可重复使用。Inspector 不上传、不安装应用插件,也不改平台草稿。
|
|
89
|
+
|
|
90
|
+
服务仅监听本机,默认从 `6274` 起选择可用端口,可用 `--port <端口>` 指定。使用 `--no-open` 时,从日志取得调试 URL 并在本机浏览器打开。
|
|
91
|
+
|
|
92
|
+
HTML 界面的验证点见 [MCP Apps](../protocols/mcp-apps/integration.md#调试与验收)。
|
|
93
|
+
|
|
94
|
+
## 业务验证
|
|
95
|
+
|
|
96
|
+
按本次交付目标验证关键链路。先核对目标工程、账号、版本与实际调用组件的归属,开发助手已有的同名工具不能代替插件能力。各组件的检查方法分别维护在对应文档中:
|
|
97
|
+
|
|
98
|
+
| 组件 | 验证指引 |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| 业务 Skill、附件及包内脚本 | [业务 Skill](../protocols/business-skills.md#修改与验证) |
|
|
101
|
+
| MCP 连接与业务权限 | [MCP 配置](../protocols/mcp-config.md#修改与验证)、[鉴权排查](../protocols/mcp-auth.md#按失败环节排查) |
|
|
102
|
+
| MCP Apps 工具与界面 | [接入验收](../protocols/mcp-apps/integration.md#调试与验收) |
|
|
103
|
+
| 业务 CLI | [连接器验证](../protocols/cli-connectors.md#修改与验证) |
|
|
104
|
+
| App 页面、卡片与设备交互 | `doubao-plugin-app` Skill |
|
|
105
|
+
|
|
106
|
+
写入或持久化需求在授权范围内操作后读回;多人或跨会话需求用对应身份或新会话读回。必要环境不可用时标记具体未验证项,已有失败先修复或交接阻塞,不以等待用户试玩代替错误处理。
|
|
107
|
+
|
|
108
|
+
同一证据可以覆盖多个检查项,不为完成清单重复调用。工程、版本、身份和环境未变时复用有效证据;局部修改只复验受影响链路。分别记录已通过、已知失败和未验证的环节,写清实际输入、结果与目标版本;模拟结果和部署成功不能代替宿主业务证据。
|
|
109
|
+
|
|
110
|
+
## 续做与恢复
|
|
111
|
+
|
|
112
|
+
跨阶段续做时,在插件包外记录必要的项目路径与身份、目标与授权、版本或部署回执、验证结果、有效入口、进程句柄和下一步,不记录凭据、设备码或授权码。恢复先核实原文件、远端状态和存活会话,复用有效结果;只停止本任务启动且不再需要的进程。
|
|
113
|
+
|
|
114
|
+
按首个失败环节排查,每次重试应有对应修正或新证据。远端结果未知时先查询原任务或平台状态,不重复创建、上传或提审。恢复授权后回到原工程、服务和业务参数验证,不因失败改变产品目标。
|
|
115
|
+
|
|
116
|
+
## 运行、停止与卸载
|
|
117
|
+
|
|
118
|
+
未指定 `--once` 的 `dev` 和 `inspect` 都是常驻进程,持续调试时保持运行;用 Ctrl+C 或 SIGTERM 停止。
|
|
119
|
+
|
|
120
|
+
停止调试会保留当前账号已安装的开发包。需要卸载时,先停止同步会话,再运行 `dbx uninstall`,避免后续文件变更触发重装。卸载工作台开发包必须显式指定 `dbx uninstall --workbench`,省略该选项时按普通插件处理。
|
|
121
|
+
|
|
122
|
+
## 平台请求路由
|
|
123
|
+
|
|
124
|
+
仅在目标环境要求指定路由时设置 `DOUBAO_REQUEST_HEADERS_JSON`,值为 JSON 对象;兼容 `DBX_BUILD_REQUEST_HEADERS_JSON`,同时设置时警告并优先前者。仅保留不区分大小写的 `x-tt-env`、`x-use-ppe`、`x-schedule-vdc`,值须为字符串,其他字段忽略。非空 `X_TT_ENV` 覆盖 JSON 的 `x-tt-env` 并设置 `x-use-ppe: 1`,保留有效的 `x-schedule-vdc`。
|
|
125
|
+
|
|
126
|
+
未配置的路由字段不自动补值。记录实际配置来源,不用域名或请求头代替服务端环境验证;这些路由字段不用于传递 MCP 业务凭据。
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# 项目配置与目录结构
|
|
2
|
+
|
|
3
|
+
先确定工程形态,再按需要创建文件。`plugin.json` 是各类工程的根清单。
|
|
4
|
+
|
|
5
|
+
## 项目目录结构
|
|
6
|
+
|
|
7
|
+
### 通用插件与应用插件
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
my-plugin/
|
|
11
|
+
├── plugin.json # 必需:根清单
|
|
12
|
+
├── mcp.json # 可选:远程 MCP 连接
|
|
13
|
+
├── skills/ # 可选:业务 Skill
|
|
14
|
+
│ └── my-skill/
|
|
15
|
+
│ ├── SKILL.md # 声明该 Skill 时必需
|
|
16
|
+
│ ├── references/ # 可选:按需读取的资料
|
|
17
|
+
│ ├── scripts/ # 可选:执行脚本
|
|
18
|
+
│ └── assets/ # 可选:图标、模板等资源
|
|
19
|
+
├── com.doubao/ # 可选:豆包扩展
|
|
20
|
+
│ ├── assets/ # 推荐:Plugin、MCP 图标
|
|
21
|
+
│ ├── auth/
|
|
22
|
+
│ │ └── shopping.json # 同名 MCP 服务的静态凭据声明
|
|
23
|
+
│ ├── cli.json # CLI 连接器
|
|
24
|
+
│ ├── agents/
|
|
25
|
+
│ │ └── contract-review.json # 已有工作伙伴引用
|
|
26
|
+
│ └── app/ # 可选:豆包 App 前端工程
|
|
27
|
+
│ ├── manifest.yaml # 识别 App 的固定入口
|
|
28
|
+
│ ├── package.json # 前端依赖;随包提供包管理器锁文件
|
|
29
|
+
│ ├── tools.json # 使用端工具时提供
|
|
30
|
+
│ ├── business-templates.yaml # 可选:业务模板
|
|
31
|
+
│ └── src/
|
|
32
|
+
│ ├── app.config.ts # 页面、卡片和端工具入口
|
|
33
|
+
│ ├── pages/
|
|
34
|
+
│ ├── widgets/
|
|
35
|
+
│ └── tools/
|
|
36
|
+
├── .agents/skills/ # 本地开发指引,不上传
|
|
37
|
+
│ ├── doubao-plugin-cli/
|
|
38
|
+
│ └── doubao-plugin-app/ # 含 App 时提供
|
|
39
|
+
└── AGENTS.md # 本地开发入口,不上传
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
普通 MCP Apps 的界面由远端 MCP 资源或声明的 URL 提供,MCP Events 由服务运行时声明,两者均无需新增包内清单。
|
|
43
|
+
|
|
44
|
+
完整配置组合见 [TODO 示例](../examples/todo-example.md),展示根清单、MCP 连接与业务 Skill 的对应关系。
|
|
45
|
+
|
|
46
|
+
### 定制工作台
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
my-workbench/
|
|
50
|
+
├── plugin.json # 必需:根清单
|
|
51
|
+
├── mcp.json # 可选:工作台使用的远端 MCP 服务
|
|
52
|
+
└── com.doubao/
|
|
53
|
+
└── workbench/
|
|
54
|
+
├── manifest.json # 必需:工作台识别与界面配置
|
|
55
|
+
├── preinstall-resources.json # 可选:预装已有 Skill 或插件
|
|
56
|
+
├── assets/ # 可选:欢迎区、导航和菜单引用的资源
|
|
57
|
+
└── web/ # 接管首页时提供随包 HTML 和静态资源
|
|
58
|
+
└── home.html # 示例入口,文件名由 Manifest 声明
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
CLI 通过 `com.doubao/workbench/manifest.json` 识别工作台,初始化骨架使用 `overlay` 欢迎区。预装声明和资源目录按需添加。完整配置与试用见 [合同工作台示例](../examples/workbench-example.md)。
|
|
62
|
+
|
|
63
|
+
## 文件协议索引
|
|
64
|
+
|
|
65
|
+
| 配置位置 | 内容与指引 |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `plugin.json` | [身份、展示信息、商店可见平台、合规声明](../protocols/plugin-json.md) |
|
|
68
|
+
| `skills/<name>/SKILL.md` | [业务 Skill 与资源](../protocols/business-skills.md) |
|
|
69
|
+
| `mcp.json` | [MCP 连接、Profile 与资源搜索](../protocols/mcp-config.md);UI 扩展见 [MCP Apps](../protocols/mcp-apps/integration.md)、事件见 [MCP Events](../protocols/mcp-events.md) |
|
|
70
|
+
| `com.doubao/auth/<服务键>.json` | [MCP 静态凭据与 OAuth](../protocols/mcp-auth.md) |
|
|
71
|
+
| `com.doubao/cli.json` | [业务 CLI 连接器](../protocols/cli-connectors.md) |
|
|
72
|
+
| `com.doubao/agents/*.json` | [工作伙伴引用](../protocols/managed-agents.md) |
|
|
73
|
+
| `com.doubao/app/` | `doubao-plugin-app` Skill 的 `SKILL.md` |
|
|
74
|
+
| `com.doubao/workbench/manifest.json` | [工作台区域与入口](../protocols/workbench.md#工作台作者配置) |
|
|
75
|
+
| `com.doubao/workbench/preinstall-resources.json` | [预装资源声明](../protocols/workbench.md#预装资源声明)、[资源搜索与取值](#配置工作台预装资源) |
|
|
76
|
+
| `com.doubao/workbench/assets/` | [欢迎区、导航与菜单资源示例](../examples/workbench-example.md#工作台-manifest) |
|
|
77
|
+
| `com.doubao/workbench/web/` | [随包 HTML 首页与静态资源](../protocols/workbench.md#takeover-随包-html-首页) |
|
|
78
|
+
|
|
79
|
+
## 创建项目
|
|
80
|
+
|
|
81
|
+
| 命令 | 创建内容 |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `dbx init <name>` | 通用插件骨架:根配置与开发指引,不含 App,需补充实际业务能力 |
|
|
84
|
+
| `dbx init <name> --type enterprise` | 企业专属插件骨架,保存 ENTERPRISE 发布类型 |
|
|
85
|
+
| `dbx init <name> --workbench` | 定制工作台骨架,目录见 [定制工作台](#定制工作台) |
|
|
86
|
+
| `dbx init <name> --app` | 应用插件骨架:增加 App、本地商品搜索端工具、业务 Skill、页面和卡片 |
|
|
87
|
+
|
|
88
|
+
目标目录须不存在或为空。用 `--type public|enterprise` 明确发布类型;未指定时,`--app` 或非 TTY 默认使用 PUBLIC,其他交互场景按 CLI 提示选择。企业专属插件需要发布权限,暂不支持 App。交互模式可选择普通插件、含 App 的插件或定制工作台。`--app` 和 `--workbench` 互斥。
|
|
89
|
+
|
|
90
|
+
### 确定发布类型
|
|
91
|
+
|
|
92
|
+
沿用开发者已明确的发布类型;已有 ID 但缺少类型时,以平台记录为准。新建工作台且类型未定时,先用 `dbx auth status` 核对账号:
|
|
93
|
+
|
|
94
|
+
| 账号类型 | 处理方式 |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| 个人账号 | 使用 `--type public` |
|
|
97
|
+
| 企业账号 | 询问公开或企业专属,按答复创建 |
|
|
98
|
+
| 未知 | 核实身份或询问发布类型 |
|
|
99
|
+
|
|
100
|
+
通用插件与应用插件在首次创建平台草稿前确认尚未明确的类型;非交互初始化显式传 `--type public` 或 `--type enterprise`。同时要求 App 和企业专属时,确认改为公开插件还是移除 App。
|
|
101
|
+
|
|
102
|
+
企业专属创建失败时,按提示区分个人账号、企业管控限制和其他发布准入限制。显式指定 `--type enterprise` 时,先处理企业准入或由用户选择公开发布。
|
|
103
|
+
|
|
104
|
+
### 依赖与开发指引
|
|
105
|
+
|
|
106
|
+
App 模式准备 Kit 和前端依赖;`--no-install-deps` 跳过依赖安装。安装失败保留项目,在 `com.doubao/app/` 重试项目所用包管理器的依赖安装。
|
|
107
|
+
|
|
108
|
+
业务 Skill 放在 `skills/<name>/SKILL.md`,工程开发指引放在 `.agents/skills/`。需要维护开发指引且链接缺失时,用 `dbx skills` 补齐链接、Git 忽略规则和 `AGENTS.md` 引导。
|
|
109
|
+
|
|
110
|
+
## 配置工作台预装资源
|
|
111
|
+
|
|
112
|
+
用当前登录账号搜索已有插件或独立 Skill;未登录时先完成 [开放平台登录](../../SKILL.md#开放平台登录)。
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
# 公开工作台
|
|
116
|
+
dbx workbench search "合同" --source official store --json
|
|
117
|
+
# 企业专属工作台
|
|
118
|
+
dbx workbench search "合同" --source official store enterprise --json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
命令无需项目目录或插件 ID,参数如下。
|
|
122
|
+
|
|
123
|
+
| 参数 | 用法 |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| 关键词 | 可省略,用于匹配资源 |
|
|
126
|
+
| `--source` | 可省略,接受一项或多项 [资源来源](../protocols/workbench.md#资源来源枚举);预装资格由同一表定义 |
|
|
127
|
+
| `--json` | 输出 JSON 数组;非 TTY 默认使用此格式 |
|
|
128
|
+
|
|
129
|
+
最多返回 100 条,JSON 未命中结果为 `[]`。示例结果如下。
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
[
|
|
133
|
+
{ "name": "合同管理", "type": "plugin", "id": "example-resource-id", "source": "store" }
|
|
134
|
+
]
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
选中资源后按以下方式填写配置,完整文件见 [预装文件示例](../examples/workbench-example.md#声明预装资源)。
|
|
138
|
+
|
|
139
|
+
| 搜索结果 | 配置位置 |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| `type`、`id`、`source` | 原样写入 `preinstall-resources.json` 的 `preinstallResources` 数组 |
|
|
142
|
+
| 同一组 `type`、`id` | 要在首页推荐时,写入 Manifest 的 `suggestions[].target` |
|
|
143
|
+
| `name` | 仅用于识别搜索结果,无需写入配置 |
|
|
144
|
+
|
|
145
|
+
旧项目的 `com.doubao/references.json` 需迁移到 `com.doubao/workbench/preinstall-resources.json`,使用上述结构。
|
|
146
|
+
|
|
147
|
+
## 路径与打包
|
|
148
|
+
|
|
149
|
+
| 资源引用 | 路径基准与写法 |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| Plugin、MCP 图标 | 相对插件根目录,以 `./` 开头 |
|
|
152
|
+
| Skill 图标和正文资源 | 相对当前 Skill 目录;图标路径以 `./` 开头 |
|
|
153
|
+
| 工作台 Manifest 资源 | 见 [工作台包协议](../protocols/workbench.md#工作台作者配置)的资源路径规则 |
|
|
154
|
+
|
|
155
|
+
引用必须指向各自目录内随包交付的实际文件,CLI 不打包软链接。
|
|
156
|
+
|
|
157
|
+
CLI 自动过滤开发依赖、缓存和维护文件,无需手动清理本地构建依赖。Skill 运行文件放在自身 `references/`、`scripts/` 或 `assets/`,不要放在根目录开发文档、`node_modules`、生成目录或另一个独立 Plugin 中;个人开发包也不包含 App 目录。
|
|
158
|
+
|
|
159
|
+
工作台包通过根目录 `mcp.json` 接入 MCP,不支持在包内声明业务 Skill、App、CLI 或 Hooks。遇到不支持模块的报错时,先核对当前目录和工程类型;确需拆分时保留原工程,在独立工作台工程继续。需要使用已有 Skill 或插件时,按 [预装资源指引](#配置工作台预装资源) 关联。
|
|
160
|
+
|
|
161
|
+
维护记录和秘密凭据放在目标 Plugin 外,不依赖 `.gitignore` 过滤。上传限额见 [版本交付与审核](release.md#上传物料与图标)。
|
|
162
|
+
|
|
163
|
+
## 选择能力组合
|
|
164
|
+
|
|
165
|
+
| 需求 | 能力 |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| 规则、知识、模板或重复流程 | 业务 Skill,按需携带脚本与资料 |
|
|
168
|
+
| 数据查询、状态管理或服务操作 | 远程 MCP;服务开发与部署见 [服务准备](development.md#mcp-服务准备) |
|
|
169
|
+
| 已有业务命令,目标宿主可安装 | 业务 CLI 连接器与配套 Skill |
|
|
170
|
+
| 筛选、详情、表单、图表或其他交互 | 见 [界面能力](#选择界面能力) |
|
|
171
|
+
| 定制豆包工作 PC 自身的首页、导航或预装资源 | 定制工作台 |
|
|
172
|
+
|
|
173
|
+
主动提醒、订阅和后台通知需核实完整事件链路,见 [MCP Events](../protocols/mcp-events.md#主动触达能力边界)。
|
|
174
|
+
|
|
175
|
+
## 选择界面能力
|
|
176
|
+
|
|
177
|
+
- 普通 MCP:提供工具结果,业务 Skill 说明调用方式。
|
|
178
|
+
- MCP Apps:通过 `ui://` 资源或豆包 URL source 提供 HTML 界面,静态入口及运行时扩展见 [MCP Apps](../protocols/mcp-apps/integration.md#按任务读取)。
|
|
179
|
+
- 豆包 App:公开插件可使用页面、Widget 和 Manifest,由项目的 `doubao-plugin-app` Skill 指导。普通 MCP 与 MCP Apps 无需 App Manifest。
|
|
180
|
+
- 定制工作台:配置豆包工作首页、导航和头像菜单,见 [工作台作者配置](../protocols/workbench.md#工作台作者配置)。
|
|
181
|
+
|
|
182
|
+
MCP Apps 与豆包 App 可在同一项目共存,但不表示 Widget / Page 能嵌入 MCP Apps HTML。
|
|
183
|
+
|
|
184
|
+
MCP Apps 的权限与显示边界见 [接入协议](../protocols/mcp-apps/integration.md#资源安全与显示模式);App 的具体端能力按 `doubao-plugin-app` Skill 与对应 API 文档核实。
|
|
185
|
+
|
|
186
|
+
服务端管理状态、自有账号或 OAuth 本身不决定前端形态;应用插件可以调用 MCP 或业务后端。
|
|
187
|
+
|
|
188
|
+
远端 MCP 和通过 URL 提供的 HTML 服务须独立部署。工作台的随包首页及静态资源随插件包上传。工具、界面和平台上传分别验证。
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# 版本交付与审核
|
|
2
|
+
|
|
3
|
+
| 命令 | 行为 |
|
|
4
|
+
| --- | --- |
|
|
5
|
+
| `dbx upload` | 上传插件包、校验物料并保存草稿和版本。含 App 时等待该版本云构建并生成预览 |
|
|
6
|
+
| `dbx audit` | 提审平台当前草稿;含 App 时等待云构建成功 |
|
|
7
|
+
| `dbx versions` | 查询版本号、状态和审核摘要,输出 JSON |
|
|
8
|
+
| `dbx cancel-audit` | 撤回尚未处理的提审 |
|
|
9
|
+
|
|
10
|
+
本页操作需要有效登录或宿主授权,围绕平台草稿和版本记录进行。个人安装见 [开发调试](development.md)。账号开发包自用无需提审;公开发布或企业专属扩大到全租户时才按平台流程提审。草稿、ID 或预览版本不代表正式分发。
|
|
11
|
+
|
|
12
|
+
上述命令从当前工程识别工作台类型,无需额外传入工作台选项。
|
|
13
|
+
|
|
14
|
+
上传与提审分别执行。仅执行用户要求的上传、提审或撤回操作。只需检查版本状态时用 `dbx versions`。
|
|
15
|
+
|
|
16
|
+
## 上传与预览
|
|
17
|
+
|
|
18
|
+
本地内容改动后,先重新上传再提审。`dbx upload --version x.y.z` 可选,仅接受无前导零的三段数字;只覆盖包内版本,不修改本地文件。未提审阶段重复上传会更新当前可编辑版本,版本号以平台实际返回为准。保留 CLI 写回的插件身份;企业专属首次创建草稿默认仅本人,后续上传保留草稿范围。
|
|
19
|
+
|
|
20
|
+
已关联平台的旧工作台缺少 `publicationType` 时,草稿和版本操作按平台草稿的唯一匹配结果补回;无法确认时,按报错核对平台记录后补填。
|
|
21
|
+
|
|
22
|
+
从 CLI 输出取得实际版本号与平台链接。部分步骤失败可能已有草稿或版本保存,按错误说明和平台入口核实后恢复。
|
|
23
|
+
|
|
24
|
+
含 App 的工程在非 TTY 模式生成预览后输出文本二维码和预览链接。上传成功不能替代 App 构建或预览成功。内容未变且预览链接仍对应目标版本时复用;内容变更或链接失效后按已有授权重新上传。预览状态未知时先查询,不自行改写链接。
|
|
25
|
+
|
|
26
|
+
审核中服务端锁定当前草稿,`upload --version` 也受限制。等待审核结束后再上传,或在用户要求时撤回审核。
|
|
27
|
+
|
|
28
|
+
## 上传物料与图标
|
|
29
|
+
|
|
30
|
+
包目录与相对路径规则见 [项目配置](project.md#路径与打包)。基础上传限额如下;含 App 的差异要求以平台校验为准:
|
|
31
|
+
|
|
32
|
+
| 检查项 | 上限 |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| ZIP 文件大小、整包解压总量 | 各 80 MB |
|
|
35
|
+
| ZIP 条目数 | 10240 |
|
|
36
|
+
| Skill 数量、MCP 服务数量 | 各 10 个,分别计数 |
|
|
37
|
+
|
|
38
|
+
当前 CLI 在上传后调用服务端物料校验,不能以本地打包成功代替限额和字段检查。各字段定义从 [文件协议索引](project.md#文件协议索引) 按需读取。
|
|
39
|
+
|
|
40
|
+
| 图标 | 要求 |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| 普通 Plugin 主图标、`chatIcon`、Skill 和 MCP 图标 | 可选;PNG / JPEG,512×512,单张 ≤500 KB |
|
|
43
|
+
| 含 App 的 Plugin 主图标 | 首次创建关联 App 时必填;GIF / JPEG / PNG / WebP,512×512,≤10 MiB,四角像素均不能完全透明 |
|
|
44
|
+
|
|
45
|
+
新增或替换图标时按上表准备文件;已有有效配置无需重复检查。字段位置和回退规则见 [根清单](../protocols/plugin-json.md#展示字段)、[业务 Skill](../protocols/business-skills.md#frontmatter-字段);主图标和 `chatIcon` 可引用同一文件。
|
|
46
|
+
|
|
47
|
+
物料校验失败时,按返回的文件和字段修复后重试。
|
|
48
|
+
|
|
49
|
+
## 提审当前草稿
|
|
50
|
+
|
|
51
|
+
`dbx audit` 使用平台当前草稿,不读取未上传的本地改动,也不接收 `--version` 或本地包。已有待处理审核时复用原审核,本次指定的新可见范围不会生效。
|
|
52
|
+
|
|
53
|
+
按实际结果恢复:草稿不存在时先核对平台记录、本地插件 ID 和登录账号,不据此判断跨账号;无权限时按归属提示处理。构建失败或超时时,材料和版本可能已保存,先查看平台版本页。CLI 报版本冲突时,用 `dbx versions` 核实目标并确认没有并行上传,再重试。
|
|
54
|
+
|
|
55
|
+
普通插件按以下要求准备材料。已有材料会预填,脱敏凭据不修改则保留。
|
|
56
|
+
|
|
57
|
+
| 材料 | 要求 |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| 意向分类 | 填写一项;缺少有效分类时,用 `dbx categories` 查询并向开发者确认 |
|
|
60
|
+
| MCP / OAuth 测试凭据 | 按鉴权要求提供测试账号或 Key;OAuth 连接器缺少已保存的凭据时须补齐 |
|
|
61
|
+
| 每个业务 Skill、豆包 App | HTTP 或 HTTPS 评测报告地址,以及 5–10 条示例提示词 |
|
|
62
|
+
| 每个 CLI | 使用说明文档链接 |
|
|
63
|
+
|
|
64
|
+
### 工作台提审
|
|
65
|
+
|
|
66
|
+
工作台沿用本页的上传、提审、查询与撤回流程,审核材料有以下差异:
|
|
67
|
+
|
|
68
|
+
- 不填写意向分类,`--input` 中也不能包含 `category_id`。
|
|
69
|
+
- 含 MCP 时按鉴权要求补齐测试凭据,可在交互提示中填写或通过 `--input` 提供 MCP 模块材料。CLI 保存材料后检查连通性,检查失败会停止提审。
|
|
70
|
+
|
|
71
|
+
公开工作台按下文准备 [合规声明](#公开上架合规声明),企业专属工作台按开发者选择设置 [可见范围](#企业专属插件可见范围)。
|
|
72
|
+
|
|
73
|
+
### 公开上架合规声明
|
|
74
|
+
|
|
75
|
+
声明随插件包上传,字段定义与必填条件见 [根清单](../protocols/plugin-json.md#公开上架合规声明)。 缺少声明时,请开发者确认是否面向未成年人,并提供实际隐私政策及适用的行业资质链接,不代替开发者接受终端预选项。
|
|
76
|
+
|
|
77
|
+
交互模式按 CLI 提示补齐声明;确认重新上传会提交整个项目,包括其他尚未上传的本地改动。非交互模式取得实际声明和链接后修改 `plugin.json`,先执行已授权的 `dbx upload`,再执行 `dbx audit`。
|
|
78
|
+
|
|
79
|
+
### 企业专属插件可见范围
|
|
80
|
+
|
|
81
|
+
企业专属插件或工作台发起新提审前,确定本次可见范围:仅本人、全租户,或保留已核实的当前范围。沿用用户在本次请求中已明确的选择;范围未定、相互冲突或需要扩大授权时再询问,不从“同事”推导为全租户。历史材料和终端预选值不代表本次授权。指定对象名单在平台管理。
|
|
82
|
+
|
|
83
|
+
`dbx audit --visibility self|tenant` 显式指定范围,跳过范围询问。范围随分类和审核材料保存到草稿。该选项只适用于企业专属项目。确认保留当前范围后,交互模式选择当前范围;非交互模式省略 `--visibility`,并移除复用输入文件中的旧 `visibility_config`,避免覆盖平台值。
|
|
84
|
+
|
|
85
|
+
### 非交互审核
|
|
86
|
+
|
|
87
|
+
非 TTY 默认复用当前草稿的分类和有效材料,并显示本次提审版本;补充或修改时使用 `--input`。指定 `--input` 后不显示交互提示,无需提供版本号:
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
dbx audit --cwd ./my-plugin --input ../audit-input.json
|
|
91
|
+
dbx audit --visibility tenant
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`--input` 的相对路径以项目根目录为基准。含测试凭据的输入文件应放在项目目录外,避免随项目打包。
|
|
95
|
+
|
|
96
|
+
下面是普通插件的材料示例;工作台按 [工作台提审](#工作台提审) 选择适用字段。
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"category_id": "category-id",
|
|
101
|
+
"modules": [
|
|
102
|
+
{
|
|
103
|
+
"module_id": "mcp-module-id",
|
|
104
|
+
"mcp": { "test_credential": "test-account-or-key" }
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"module_id": "skill-module-id",
|
|
108
|
+
"skill": {
|
|
109
|
+
"evaluation_report_url": "https://example.com/report",
|
|
110
|
+
"example_prompts": ["核心场景一", "核心场景二", "核心场景三", "核心场景四", "核心场景五"]
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"module_id": "app-module-id",
|
|
115
|
+
"mini_app": {
|
|
116
|
+
"evaluation_report_url": "https://example.com/report",
|
|
117
|
+
"example_prompts": ["核心场景一", "核心场景二", "核心场景三", "核心场景四", "核心场景五"]
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"module_id": "cli-module-id",
|
|
122
|
+
"cli": { "instruction_document_url": "https://example.com/docs" }
|
|
123
|
+
}
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
MCP Apps 兼容使用 `mcp_app.mcp.test_credential`。
|
|
129
|
+
|
|
130
|
+
企业输入文件可增加 `"visibility_config": { "type": 1 }`(仅本人)或 `{ "type": 2 }`(全租户)。Devtool 写入使用独立范围类型,只接受 `type`,不接受 `entities`;`--visibility self` 对应 1,`tenant` 对应 2。草稿查询仍返回通用范围类型:2 为全租户、3 为指定对象、4 为仅自己,与写入类型分别处理。`--visibility` 与输入文件的 `visibility_config` 不能同时提供。省略范围时沿用草稿。
|
|
131
|
+
|
|
132
|
+
分类 ID 通过 `dbx categories` 查询公开插件分类,企业专属插件分类使用 `dbx categories --type enterprise`;`module_id` 使用服务端草稿返回值,不根据模块名称自行生成。当前 CLI 不提供草稿详情查询;拿不到模块 ID 时,在开放平台控制台完善草稿材料,再运行 `dbx audit` 复用。
|
|
133
|
+
|
|
134
|
+
未指定的材料沿用有效旧值,脱敏凭据不会作为新凭据上传。材料无效时在保存版本和提审前退出。评测报告地址使用用户提供或草稿已有的真实报告,不能用 MCP endpoint、首页、草稿页或示例 URL 代替;URL 格式通过不证明报告内容有效。
|
|
135
|
+
|
|
136
|
+
## 查询与撤回审核
|
|
137
|
+
|
|
138
|
+
用 `dbx versions --cwd <项目目录>` 查询版本与审核状态,依据实际返回的 `version`、`status`、`status_message`、`current_approval` 报告。
|
|
139
|
+
|
|
140
|
+
`dbx cancel-audit` 按平台返回顺序分页查找,撤回第一条尚未处理的审核。若有多条记录且目标不明确,先用 `dbx versions` 或平台核实,再执行已授权的撤回。
|
|
141
|
+
|
|
142
|
+
查询或撤回失败、远端结果未知时,先在平台核实原草稿、版本或审批状态,不反复提交。
|
|
143
|
+
|
|
144
|
+
CLI 没有 `publish` 命令。版本保存、提交审核、审核通过与正式发布是不同状态,发布按平台实际入口完成。
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# TODO 应用插件示例
|
|
2
|
+
|
|
3
|
+
假设已有提供查看、新增、完成待办三个工具的远程 MCP 服务,以下最小配置串起根清单、MCP 连接和业务 Skill。鉴权按服务要求补充;需要交互界面时再读取 [MCP Apps](../protocols/mcp-apps/integration.md)。
|
|
4
|
+
|
|
5
|
+
## 目录与完整配置
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
todo-demo/
|
|
9
|
+
├── plugin.json
|
|
10
|
+
├── mcp.json
|
|
11
|
+
└── skills/
|
|
12
|
+
└── todo-list/
|
|
13
|
+
└── SKILL.md
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
新项目可用 `dbx init <项目名>` 创建骨架,再按字段合并以下配置;已有项目保留身份和其他能力配置。命名、必填字段及路径约束分别见 [根清单](../protocols/plugin-json.md)、[MCP 配置](../protocols/mcp-config.md)、[业务 Skill](../protocols/business-skills.md)。
|
|
17
|
+
|
|
18
|
+
### plugin.json
|
|
19
|
+
|
|
20
|
+
按项目实际名称、发布类型和展示信息填写;下例以公开类型为例:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"name": "todo-demo",
|
|
25
|
+
"publicationType": "PUBLIC",
|
|
26
|
+
"description": "查看、新增和完成待办",
|
|
27
|
+
"extensions": {
|
|
28
|
+
"com.doubao": {
|
|
29
|
+
"displayName": { "zh": "待办清单" },
|
|
30
|
+
"mcpServers": {
|
|
31
|
+
"todo": {
|
|
32
|
+
"displayName": { "zh": "待办服务" },
|
|
33
|
+
"displayDescription": { "zh": "查看、新增和完成待办" }
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### mcp.json
|
|
42
|
+
|
|
43
|
+
将占位地址替换为已验证的实际 HTTPS MCP endpoint:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"mcpServers": {
|
|
48
|
+
"todo": {
|
|
49
|
+
"type": "streamable-http",
|
|
50
|
+
"url": "https://example.com/mcp"
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
两个 JSON 文件中的服务键统一为 `todo`:连接配置使用 `mcpServers.todo`,展示配置使用 `extensions["com.doubao"].mcpServers.todo`。Skill 正文中的三个工具名须与服务实际返回的 `tools/list` 一致。
|
|
57
|
+
|
|
58
|
+
### skills/todo-list/SKILL.md
|
|
59
|
+
|
|
60
|
+
按实际工具 schema 调整正文,并补充服务的数据保存与可见范围说明。正式发布前使用唯一的 Skill 名称,保持 `name` 与目录一致:
|
|
61
|
+
|
|
62
|
+
```markdown
|
|
63
|
+
---
|
|
64
|
+
name: todo-list
|
|
65
|
+
description: 当用户需要查看、新增或完成待办时使用。
|
|
66
|
+
metadata:
|
|
67
|
+
display_name: 待办清单
|
|
68
|
+
display_description: 查看、新增待办,并将已完成的任务标记为完成。
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
# 待办清单
|
|
72
|
+
|
|
73
|
+
- 查看待办:调用 `todo_list({})`,空列表为 `items: []`。
|
|
74
|
+
- 新增待办:调用 `todo_create({ "title": "用户提供的标题" })`,标题去除首尾空白后不能为空,ID 由服务生成。
|
|
75
|
+
- 完成待办:从 `todo_list` 的真实结果取得 ID,再调用 `todo_complete({ "id": "实际 ID" })`;同名多项且目标不明时先澄清,重复完成不改变状态。
|
|
76
|
+
|
|
77
|
+
成功结果包含可读 `content` 和 `structuredContent.items`,每项含 `id`、`title`、`completed`。只在返回成功后报告新增或完成,不虚构待办或 ID。
|
|
78
|
+
|
|
79
|
+
工具业务失败返回 `isError: true` 和原因;连接、协议或授权失败按实际报错处理。未知 ID 时重新读取列表;新增请求超时或断线时先读取并核对结果,不能直接重试造成重复。
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## 调试与验证
|
|
83
|
+
|
|
84
|
+
1. 替换占位地址,按实际服务配置 [鉴权](../protocols/mcp-auth.md)。Streamable HTTP 服务可用 `dbx inspect --mcp-server <实际地址>` 检查工具、输入 schema 和结果,并直接调用验证空标题、未知 ID 等错误边界。
|
|
85
|
+
2. 按 [开发调试](../cli/development.md) 登录并运行 `dbx dev --plugin`,确认首次同步和当前账号安装成功。
|
|
86
|
+
3. 在目标宿主依次请求“新增待办:整理本周计划”“查看待办”“完成整理本周计划”,核对同一 ID 的状态变化。
|
|
87
|
+
|
|
88
|
+
保存版本时按 [版本交付与审核](../cli/release.md) 执行。
|