← 提示词库 Meta/muse-agent/skills/box/SKILL.md 原文 md
🌐 中英双语对照

name: "box"
icon: "box"
description: "Search, read, upload, download, move, rename, delete, restore, and share Box content; manage comments and metadata."
metadata: { "includeInPrompt": false }

Box

Use /opt/hatch/bin/box-cli to access Box.

使用 /opt/hatch/bin/box-cli 访问 Box。

Connect / 连接

Run /opt/hatch/bin/box-cli status. If disconnected, run
/opt/hatch/bin/box-cli authorize-url and share the returned connect_url
as Connect Box. A fresh connection requests read-only access. Wait for
browser consent, then check status again.

运行 /opt/hatch/bin/box-cli status。如果已断开，运行
/opt/hatch/bin/box-cli authorize-url，并把返回的 connect_url 以 Connect Box 分享。新建立的连接只请求只读权限。等待浏览器授权完成，然后再次检查状态。

Before an operation that may need broader Box access, run
/opt/hatch/bin/box-cli status --for-command <command-or-method>. For a hosted
MCP operation, pass its exact tool name instead of call-tool. When
scope_status is not_granted, copy the returned scope_add_url exactly and
post it on its own line as
[Additional Box access](<scope_add_url>) so the client renders the native
access button. Wait for consent, then retry the original operation. Never
construct an authorization URL or substitute a raw Box scope. The operation
also fails closed with the same method-bound link if its required scope is
absent. OAuth access does not replace Muse approval.

在执行可能需要更广泛 Box 权限的操作之前，运行
/opt/hatch/bin/box-cli status --for-command <command-or-method>。对于托管 MCP 操作，传入其确切的工具名称而不是 call-tool。当 scope_status 为 not_granted 时，原样复制返回的 scope_add_url，并单独成行发布为
[Additional Box access](<scope_add_url>)，以便客户端渲染原生的授权按钮。等待授权完成，然后重试原操作。绝不自行构造授权 URL，也不要替换为原始的 Box scope。如果所需 scope 缺失，该操作也会以相同的方法绑定链接失败关闭（fail closed）。OAuth 授权不能替代 Muse 审批。

【评论】新连接默认只申请只读 scope、扩展权限需按操作单独申请，体现了最小权限原则；"OAuth 不替代 Muse 审批"则把服务授权与代理操作审批分成两层。

Use / 使用

Run list-tools for available MCP tools, their argument schemas, and Muse
permissions. Use those schemas and IDs returned by Box in call-tool.
get_file_content reads document text. Downloads and changes ask for Muse
approval by default.

运行 list-tools 查看可用的 MCP 工具、其参数模式（schema）和 Muse 权限。在 call-tool 中使用这些模式以及 Box 返回的 ID。get_file_content 读取文档文本。下载和更改默认需要 Muse 审批。

/opt/hatch/bin/box-cli list-tools
/opt/hatch/bin/box-cli call-tool --name who_am_i --arguments-json '{}'

# Browse the root folder.
/opt/hatch/bin/box-cli call-tool --name list_folder_content_by_folder_id \
  --arguments-json '{"folder_id":"0","limit":20}'

# Search for PDFs.
/opt/hatch/bin/box-cli call-tool --name search_files_keyword \
  --arguments-json '{"query":"project plan","file_extensions":["pdf"],"limit":10}'

# Inspect file metadata.
/opt/hatch/bin/box-cli call-tool --name get_file_details \
  --arguments-json '{"file_id":"<file_id>","fields":["name","size","permissions"]}'

# Read document text.
/opt/hatch/bin/box-cli call-tool --name get_file_content \
  --arguments-json '{"file_id":"<file_id>"}'

# Create a folder.
/opt/hatch/bin/box-cli call-tool --name create_folder \
  --arguments-json '{"name":"Project notes","parent_folder_id":"<folder_id>"}'

# Upload a text file.
/opt/hatch/bin/box-cli call-tool --name upload_file \
  --arguments-json '{"file_name":"notes.txt","file_content":"Meeting notes","parent_folder_id":"<folder_id>"}'

# Post a comment.
/opt/hatch/bin/box-cli call-tool --name create_file_comment \
  --arguments-json '{"file_id":"<file_id>","message":"Ready for review."}'

Use the file commands below for local-file uploads, full downloads, moves,
renames, and deletion. update-folder and delete-folder take --folder-id.
Use upload-version to replace an existing file's contents; its required
--name also renames the file. Run <command> --help for options.

本地文件上传、完整下载、移动、重命名和删除请使用下面的文件命令。update-folder 和 delete-folder 接受 --folder-id。使用 upload-version 替换已有文件的内容；其必需的 --name 同时会重命名该文件。运行 <command> --help 查看选项。

/opt/hatch/bin/box-cli download --file-id <file_id> --output workspace/report.pdf
/opt/hatch/bin/box-cli upload --input workspace/report.pdf --name report.pdf --parent-folder-id <folder_id>
/opt/hatch/bin/box-cli update-file --file-id <file_id> --name renamed.pdf --parent-folder-id <folder_id>
/opt/hatch/bin/box-cli delete-file --file-id <file_id>

Downloads overwrite the output file. Deletion is permanent when Box trash is
disabled; deleting a nonempty folder requires --recursive.
list-trash returns retained items; pass next_marker as --marker to page.
Use restore-file or restore-folder to recover them. Their
--fallback-parent-folder-id applies only if the original parent no longer exists.

下载会覆盖输出文件。当 Box 回收站被禁用时，删除是永久性的；删除非空文件夹需要 --recursive。
list-trash 返回保留的项目；把 next_marker 作为 --marker 传入以分页。
使用 restore-file 或 restore-folder 恢复它们。它们的
--fallback-parent-folder-id 仅在原始父级已不存在时生效。

Downloads report the saved path and byte count; other results appear under
result. ok: false means the operation failed. REST commands make one attempt:
retry a download later if Box returns HTTP 202 (file not ready), and run
refresh on HTTP 401 before retrying. Check whether a failed change was applied
before retrying it.
Do not retry an access-denied operation through another command.

下载会报告保存路径和字节数；其他结果显示在 result 之下。ok: false 表示操作失败。REST 命令只尝试一次：如果 Box 返回 HTTP 202（文件未就绪），稍后重试下载；遇到 HTTP 401 时先运行 refresh 再重试。在重试失败的更改之前，先检查它是否已被应用。
不要通过其他命令重试被拒绝访问的操作。

/opt/hatch/bin/box-cli refresh refreshes the connection.
/opt/hatch/bin/box-cli disconnect disconnects Box from Muse.

/opt/hatch/bin/box-cli refresh 刷新连接。
/opt/hatch/bin/box-cli disconnect 将 Box 与 Muse 断开。