dropbox

Dropbox

用于在 Dropbox 中操作文件和文件夹的工具：上传和写入文件、整理文件（移动／复制／删除／创建文件夹）、浏览和搜索、读取文件内容、创建和修改共享链接、管理共享文件夹成员，以及创建文件请求。封装了 Dropbox API v2（https://api.dropboxapi.com/2/<namespace>/<method>，上传和下载使用 https://content.dropboxapi.com）。只读工具均有明确标记；写入工具会返回简洁的文件／文件夹元数据，不会悄悄附加链接或内容。

Dropbox 的独立非官方连接器。与 Dropbox 无关联，也未获其认可或赞助。“Dropbox”是其所有者的商标，在此仅用于标识本连接器所连接的服务。

适用场景

• Agent 需要在 Dropbox 中保存、移动、复制、重命名或删除文件和文件夹。
• Agent 需要查找文件或文件夹（按名称或内容），或在操作前列出文件夹内容。
• Agent 需要以内联方式读取文本文件内容，或通过临时或长期有效的链接传递文件字节。
• Agent 需要共享文件／文件夹、更改链接设置，或管理有权访问共享文件夹的人员。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先运行 npx skills add zapier/connectors --skill dropbox 安装（或使用你所用框架自带的技能安装机制），然后继续操作。安装技能只会复制这些文件，不会安装依赖项。在运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。若要在自己的项目中将已发布的软件包作为依赖项导入？此时 npm install 已会解析所有依赖项——请参阅 references/use-as-sdk.md。

如果你想获取实际的仓库源代码，以便浏览 references/、运行此连接器的测试或修改代码，请参阅 README.md，了解如何进行范围限定的 git clone。

连接器需要 Node.js 22.18+。选择与你的运行方式相符的参考文档，并在进行任何操作之前先加载：

你拥有……	加载
支持 MCP 的客户端——工具可能已加载（例如 mcp__dropbox__<tool>），或者你可以自行注册本地服务（或引导用户注册）	references/use-as-mcp.md
终端／子进程访问权限（你可以运行 node）	references/use-as-cli.md
只有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法访问工具或终端，也无法导入此软件包——你需要自行编写代码，直接调用 Dropbox API（例如，在代码执行沙盒中）	references/use-as-recipe.md

脚本

全部 21 个脚本都使用同一个 dropbox 连接。每个脚本文件中的 inputSchema／outputSchema（Zod）是其接口约定的权威定义。

脚本	脚本名称	连接	描述
scripts/uploadFile.ts	uploadFile	单一（dropbox）	通过从 URL 获取文件字节来上传文件（大文件使用分块会话）。
scripts/createTextFile.ts	createTextFile	单一（dropbox）	根据纯文本内容创建或覆盖文件。
scripts/appendToTextFile.ts	appendToTextFile	单一（dropbox）	将文本追加到文本文件（如果文件不存在，则创建文件）。
scripts/createFolder.ts	createFolder	单一（dropbox）	在指定路径创建文件夹。
scripts/moveFile.ts	moveFile	单一（dropbox）	移动或重命名文件或文件夹。
scripts/copyFile.ts	copyFile	单一（dropbox）	将文件或文件夹复制到新路径。
scripts/deletePath.ts	deletePath	单一（dropbox）	删除文件或文件夹（可在有限时间内恢复）。
scripts/listFolder.ts	listFolder	单一（dropbox）	列出文件夹的直接内容（通过游标分页）。
scripts/searchFiles.ts	searchFiles	单一（dropbox）	按名称或内容搜索文件/文件夹（通过游标分页）。
scripts/getFileMetadata.ts	getFileMetadata	单一（dropbox）	根据路径或 ID 获取单个文件或文件夹的元数据。
scripts/getTemporaryLink.ts	getTemporaryLink	单一（dropbox）	获取文件约 4 小时有效的直接下载 URL。
scripts/getFileContents.ts	getFileContents	单一（dropbox）	读取文本文件的内嵌内容（UTF-8，大小有限制）。
scripts/createSharedLink.ts	createSharedLink	单一（dropbox）	创建长期有效的可分享链接（如果已存在，则返回现有链接）。
scripts/modifySharedLinkSettings.ts	modifySharedLinkSettings	单一（dropbox）	更改现有共享链接的设置。通过 listSharedLinks 解析 url。
scripts/listSharedLinks.ts	listSharedLinks	单一（dropbox）	列出现有共享链接，可选择指定路径。
scripts/listSharedFolders.ts	listSharedFolders	单一（dropbox）	列出账户所属的共享文件夹（用于解析 shared_folder_id）。
scripts/addFolderMember.ts	addFolderMember	单一（dropbox）	将成员（通过电子邮件地址指定）添加到共享文件夹。通过 listSharedFolders 解析 shared_folder_id。
scripts/removeFolderMember.ts	removeFolderMember	单一（dropbox）	从共享文件夹中移除成员（轮询直至完成）。
scripts/createFileRequest.ts	createFileRequest	单一（dropbox）	创建可向文件夹上传文件的公开页面。
scripts/listFileRequests.ts	listFileRequests	单一（dropbox）	列出账户的文件请求。
scripts/getCurrentAccount.ts	getCurrentAccount	单一（dropbox）	识别账户及其团队/个人命名空间 ID。
有些脚本需要使用 ID 或 URL，而这些值最好通过其他脚本解析——相应的解析提示位于字段描述中（例如，addFolderMember.shared_folder_id ← listSharedFolders；modifySharedLinkSettings.url ← listSharedLinks）。

消歧与拒绝

按名称消歧条目。 Dropbox 使用路径或ID定位条目，且路径不区分大小写——两个条目看起来可能同名。在对用户用文字而非精确路径指定的条目执行写入操作（移动／复制／删除／共享）之前，先使用 searchFiles 或 listFolder 解析：

• 恰好一个匹配项 → 执行操作；无需过度确认。
• 两个或更多匹配项难以区分（例如，不同文件夹中都有 report.pdf，或共享文件夹名称冲突）→ 停止，列出带有区分字段的候选项（文件夹使用完整的 path_display 或 shared_folder_id），并询问用户要选哪一个。绝不要默默自行选择。

这里最容易发生名称冲突的实体类型是文件／文件夹名称（使用 searchFiles／listFolder 解析，并按 path_display 区分）和共享文件夹名称（使用 listSharedFolders 解析，并按 shared_folder_id 区分）。

此连接器不执行的操作——明确说明，不要假装可以执行。 如果用户请求以下任一操作，请告知他们不受支持，不要改用其他工具并声称操作成功：

• 在一次调用中批量移动、复制或删除。 没有批量工具——你可以循环调用单项工具（moveFile／copyFile／deletePath），或者告知用户每个条目都需要单独调用一次。
• 将二进制文档（PDF／图像／Office 文件）作为文本读取、进行 OCR 或解析文档。 getFileContents 仅返回 UTF-8 文本；对于其他文件，它会返回 is_text:false，你必须通过 getTemporaryLink 转交字节数据。不要声称已读取 PDF 的内容。
• 获取或编辑单个文件请求，或将整个文件夹作为托管共享内容进行共享。 仅提供 createFileRequest + listFileRequests；没有获取／更新文件请求或 shareFolder 工具。

身份验证

每种形态都会通过一个连接选择器传递身份验证信息，而非密钥——格式为 [<resolver>:]<value>。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层进行路由）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请检查此连接器自身支持的解析器，不要想当然。<resolver>: 前缀是可选的；不带前缀的值会交给第一个认领它的解析器——UUID 格式的不带前缀值总会被 zapier: 认领。每个脚本都会声明所需的连接以及各连接接受的解析器。传递连接的确切语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考文档。

要先检查已配置的内容？不要为此导出环境变量值——env 或 env | grep <name> 会连同名称一起打印值，如果其中设有有效凭据，就会将其泄露到对话记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式，并按照相应参考文档中的流程获取连接；不要直接向用户索要连接 ID 或令牌，仿佛他们已经记住了一样：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接进行路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何检查你所用形状的确切脚本架构，请参阅上文加载的参考资料）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剔除：脚本从 API 返回的字段未在 outputSchema 中声明。如果需要这些字段，请跳过输出验证后重新运行。
  • { skipped: true } — 已绕过验证；data 是原始的、未经检查的脚本输出。

读取已剔除的字段 / skipOutputDataValidation。 如需接收未经验证的原始结果，请选择跳过输出验证（确切语法因形状而异；请参阅上文加载的参考资料）。输入验证始终不会跳过。

缩减结果 / filterOutputData。 若要将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（确切语法同样因形状而异）。jq 只会针对 data 运行，而不会针对 { data, meta } 信封运行，因此表达式应以 data 为根（运行脚本的 --help——或你所用形状的等效命令——以查看其输出架构）。转换后的值会替换 data，meta 保持不变，且结果不会再次根据输出架构进行验证。

参考资料

在相应领域操作前，先加载匹配的参考文件：

参考资料	涵盖内容	何时加载
references/dropbox-api-gotchas.md	Stone .tag 联合形状、error_summary 错误模型、读取与写入时「未找到」行为的不对称性、路径规则（根路径是 "" 而不是 "/"）、通过同级 /continue 端点进行游标分页、速率限制与命名空间写入锁定、上传会话流程、共享链接恢复、通过 namespace_id 定位团队空间	在直接调用 Dropbox API 或排查意外 API 错误前