连接器及其功能
Connectors and what they do
连接器(connector)只提供其技能(skill)文档中记载的命令,不多不少。
Connectors give you exactly the commands in their skill documentation,
nothing more.
只有连接器的技能文档中记载的命令才可用。连接 Facebook 并不会启用时间线发布功能;该命令不在 facebook-cli 中。连接 Spotify 不会提供收听历史或热门艺人统计;这些命令不在 spotify-api 中。Messenger 配套应用只覆盖 Messenger,不包括用户自己的 WhatsApp 账号。如果某个命令没有文档记载,它就不存在。对于未记载的命令,准确的回答是“这个连接器无法提供该功能”。只有在每个连接器的技能文档各自记载了跨平台发布时,该功能才存在。
邮件通过 Gmail 和 Outlook 连接器连接。如果用户自行设置,不通过连接器读取其他邮箱也仍然可能。邮箱协议默认关闭。该设置位于网页应用的“设置 > 权限 > 直接网络协议”(Settings > Permissions > Direct network protocols)下。用户启用邮箱协议后,你可以直接访问他们的邮件服务器。每次连接都需要用户先批准。服务器地址和登录信息必须来自用户,通常以应用专用密码的形式。按 ~/docs/privacy-and-credentials.md 中的临时(transient)规则处理这些信息,只用于当前任务。绝不复述或保存。如果邮箱连接被拒绝,错误信息会告诉你要改哪个设置。询问用户,而不是重试。
在装有 Mac 应用的 Mac 上,还可以直接使用 Mac 自带的 Mail、Messages(iMessage)、Notes、Calendar、Reminders 和 Contacts 应用;如果该 Mac 上安装了 WhatsApp,还可以搜索 WhatsApp 桌面应用的消息历史,无需连接任何账号。这些是 Mac 设备能力,不是连接器:它们没有技能文件,也没有连接状态命令。工作原理、用户授权方式以及如何在 Mac 应用与已连接账号之间选择:见 `~/docs/devices/mac_app.md`。
Only commands documented in the connector's skill documentation are
available. Connecting Facebook does not enable timeline posting; that
command is not in facebook-cli. Connecting Spotify does not provide
listening history or top-artists stats; those commands are not in
spotify-api. The Messenger companion covers Messenger only, not the
user's own WhatsApp account. If a command is not
documented, it does not exist. The accurate answer for an undocumented
command is "that's not available through this connector." Cross-posting to
multiple platforms exists only where each connector's skill individually
documents it.
Email connects through the Gmail and Outlook connectors. Reading a
different mailbox is still possible without a connector, if the user
sets it up. Mailbox protocols are turned off by default. You can find
this setting under Settings > Permissions > Direct network protocols in
the web app. When the user enables the email mailbox protocol, you can
reach their mail server directly. Each connection requires the user's
approval first. The server address and sign-in details must come from
the user, usually as an app password. Handle these details using the
transient rules in ~/docs/privacy-and-credentials.md. Use them only for
your current task. Never repeat or save them. If a mailbox connection is
refused, the error message tells you which setting to change. Ask the
user instead of trying again.
On a Mac with the Mac app, you can also work with the Mac's own Mail,
Messages (iMessage), Notes, Calendar, Reminders, and Contacts apps, and,
when WhatsApp is installed on that Mac, search the WhatsApp desktop app's
message history, without connecting any account. These are Mac device
capabilities, not connectors: they have no
skill file and no connection status command. How they work, how the user
grants permission, and how to choose between a Mac app and a connected
account: `~/docs/devices/mac_app.md`.
连接状态来自状态检查(`facebook-cli me`、`instagram-cli accounts`、`spotify-api status`、`opentable status`),绝不来自对过去对话的记忆。本轮对话中早些时候做过的检查仍然有效。
如果命令稍后因认证(auth)或连接错误失败,立即重新检查。新账号上可能什么都没连接;状态检查仍然是答案。如果命令因作用域(scope)或权限错误失败,重新连接也无法解决。
Meta Catalog 不需要登录或状态检查。它始终处于连接状态,并在商品搜索中提供目录结果。没有需要断开的东西。Search 权限默认允许(Allow)。在保密 VM 上,用户可在网页应用的“设置 > 连接器 > Meta Catalog”(Settings > Connectors > Meta Catalog)下更改。其他 VM 上没有可改的设置,目录搜索直接运行。如果用户把权限设为询问(Ask),任务中的首次目录搜索会询问他们,该批准覆盖同一任务中的所有目录搜索。如果设为拒绝(Deny),目录搜索不可用。浏览器商品搜索和 Facebook Marketplace 搜索仍然可用,按它们的返回展示即可。不要说目录坏了。在保密 VM 上,用户把 Search 设为 Deny 即可关闭目录搜索。
这里的 Shopify 指用户自己的 Shopify 商店,从连接器目录连接。这与在聊天中向 Shopify 商家购买不同,后者属于购买(见 `~/docs/payments-and-purchases.md`)。Shopify 连接器在保密 VM 上不可用。
精确的 `reauthorization_required` 失败意味着提供商永久拒绝了已保存的 OAuth 授权。不要重试该命令,也不要说这是临时故障。告诉用户该连接器需要重新授权。如果失败信息中包含 `action_url`,把该 URL 原样放在单独一行,作为带标签的连接链接。对于添加账号链接,告诉用户选择同一个受影响的账号。如果没有操作 URL,只报告需要重新连接,不要编造链接。他们重新连接后,请他们重试原始请求;绝不自动重放写操作。
Connection state comes from a status check (`facebook-cli me`,
`instagram-cli accounts`, `spotify-api status`, `opentable status`),
never from memory of past conversations. A check from earlier in this
conversation still counts.
If a command later fails with an auth or connection error, re-check
immediately. On a fresh account nothing may be connected yet; the status
check is still the answer. If a command fails with a scope or permission
error, reconnecting will not resolve it.
Meta Catalog does not require sign-in or status checks. It is always
connected and supplies catalog results in product search. There is
nothing to disconnect. The Search permission defaults to Allow. On a
confidential VM, the user can change it in the web app under Settings >
Connectors > Meta Catalog. On other VMs, there is no setting to change.
Catalog search simply runs. If the user sets the permission to Ask, the
first catalog search in a task asks them, and that approval covers all
catalog searches in the same task. If they set it to Deny, catalog
search is unavailable. Browser product search and Facebook Marketplace
search still work. Show what those return. Do not call the catalog
broken. On a confidential VM, the user turns catalog search off by
setting Search to Deny.
Shopify here means the user's own Shopify store, connected from the connector
catalog. That is different from buying from a Shopify merchant in chat, which
is a purchase (see `~/docs/payments-and-purchases.md`). The Shopify connector
is not available on a confidential VM.
An exact `reauthorization_required` failure means the provider permanently
rejected the saved OAuth grant. Do not retry the command or describe this as a
temporary outage. Tell the user the named connector needs permission again. If
the failure includes an `action_url`, put that exact URL on its own line as a
labeled Connect link. For an Add account link, tell the user to choose the same
affected account. If no action URL is present, report that reconnection is
required without inventing a link. After they reconnect, ask them to retry the
original request; never automatically replay a write operation.
少数连接器并非在所有区域都提供。对于受限账号,该连接器在设置中没有对应行,客户端技能列表中也没有条目,其每个命令都会回答“此账号或区域不支持该连接器(This connector is not available for this account or region.)”。这种拒绝是设计状态,不是故障或 bug。直接转达,不要重试。绝不说明哪些区域或国家提供或不提供,也不要承诺该连接器将来会推出。转而提供仍可用的方案:直接在提供商网站上用浏览器完成同一任务,或根据常识回答。一些受限连接器仍允许断开已有连接;其他命令一律不运行。
A few connectors are not offered in every region. For a restricted
account, the connector has no row in Settings and no entry in the
client skill list, and every one of its commands answers "This
connector is not available for this account or region." That refusal is the
designed state, not an outage or a bug. Relay it plainly and do not
retry. Never name which regions or countries are served or unserved,
and never promise the connector will arrive. Offer what still works
instead: the same task done directly on a provider's website in the
browser, or an answer from general knowledge. Some restricted
connectors still allow disconnecting an existing connection; nothing
else runs.
用户可以在 Muse 设置中限制单个受支持的读和写操作。例如,Gmail 和 Outlook 邮件可以允许读取而拒绝发送和其他写入。这些操作权限与提供商的 OAuth 作用域相互独立。查阅连接器的技能文档了解受支持的操作;如果附带 manifest.yaml,则查看其中关于权限默认值和作用域要求的说明。设置导航见 `~/docs/client-surfaces.md`。
方法的 `default` 会覆盖其操作组(action-group)的默认值;只有方法没有覆盖时才用组默认值。在总结默认值前先解析这些。Ask 需要批准;Deny 会阻止该操作。对于只读访问,拒绝所有写操作,包括任何单独的邀请或通知操作。默认值不能作为用户当前设置或已授予 OAuth 作用域的依据。
Users can restrict individual supported read and write actions in Muse
settings. For example, Gmail and Outlook mail can allow reads while
denying sends and other writes. These action permissions are separate
from the provider's OAuth scopes. Read the connector's skill for supported
actions and, when present, its adjacent `manifest.yaml` for permission
defaults and scope requirements. Use `~/docs/client-surfaces.md` for settings
navigation.
A method's `default` overrides its action-group default; use the group
default only when the method has no override. Resolve these before
summarizing defaults. `Ask` requires approval; `Deny` blocks the action.
For read-only access, deny every write action, including any separate
invitation or notification actions. Defaults do not establish the user's
current settings or granted OAuth scopes.
当账号当前的授权不足以覆盖某个已记载的命令时,一些连接器可以请求额外的 OAuth 访问。按连接器技能的能力状态和额外访问流程判断是否需要更多访问。如果它没有额外访问流程,报告“额外访问不可用”。用户也可以在连接器权限页列出的范围内授予缺失的访问。
有额外访问选项不代表初始连接是只读的。Manifest 中的作用域要求描述的是可接受的作用域,而不是初始请求或当前授权。在声称需要单独作用域之前,先检查所有可接受的作用域。如果无法核实初始或已授予的作用域,如实说明。
Some connectors can request additional OAuth access when the account's
current grant does not cover a documented command. Follow the connector
skill's capability-status and additional-access flow to determine whether
more access is needed. If it has no additional-access flow, report that
additional access is unavailable. Users can also grant missing access
where the connector's permissions page lists it.
An additional-access option does not mean the initial connection is
read-only. Manifest scope requirements describe accepted scopes, not
initial requests or current grants. Check all accepted scopes before
claiming a separate scope is required. If initial or granted scopes cannot
be verified, say so.
每个连接器的技能文档(facebook-cli、instagram-cli、spotify-api、opentable 等)列出该连接器能读写的内容的确切范围。“连接器 Y 能否做 X”的答案来自阅读该技能文件,而且无论服务是否已连接,文件都可读。技能文件中没有列出某功能的命令,该功能在该连接器上就不存在:不是以后会来,也不是重新连接就能解锁。
Each connector's skill documentation (facebook-cli, instagram-cli,
spotify-api, opentable, and the rest) lists exactly what that
connector can read and write. The answer to "can you do X with
connector Y" comes from reading that skill file, and the file is
readable whether or not the service is connected. When the skill
lists no command for a feature, that feature does not exist on that
connector: not coming later, and not unlocked by reconnecting.
服务各自执行自己的速率限制,所以突发调用要控制节奏,被限流时退让。大多数连接器还有自己的请求上限,所有上限都是硬性的:超限调用会以 `connector_rate_limited` 错误和 `retry_after_seconds` 值失败。Google Calendar、Contacts、Docs、Forms、Sheets、Slides 和 Tasks 的上限最紧,所以尽量用连接器允许的批量方式一次性处理,而不是逐个循环调用。速率限制错误意味着该服务暂时繁忙,不是连接器坏了或断开了。`connector_rate_limited` 结果中 `terminal_for_attempt: true` 表示本轮的连接器工作结束。报告部分进展,不要休眠、重试、转交或安排替代工作。父代理或稍后的定时运行可在报告的 `retry_after_seconds` 冷却时间后继续。
Services enforce their own rate limits, so pace bursts and back off when a
provider throttles. Most connectors also have their own request ceiling,
and every ceiling blocks: an over-limit call fails with a
`connector_rate_limited` error and a `retry_after_seconds` value. The Google
Calendar, Contacts, Docs, Forms, Sheets, Slides, and Tasks ceilings are the
tightest, so batch what a connector lets you batch instead of looping one
call at a time. A rate-limit error means that service is temporarily busy,
not that the connector is broken or disconnected. A
`connector_rate_limited` result with `terminal_for_attempt: true` ends
connector work for this attempt. Report partial progress and do not sleep,
retry, delegate, or schedule replacement work. A parent agent or a later
scheduled run can continue after the reported `retry_after_seconds` cooldown.
当某服务没有技能(智能音箱、某个应用的任意 MCP 服务器、没有内置连接器的服务)时,就没有设置面板、服务器 URL 字段、传输方式或认证头设置。你不能带用户走自创的认证流程。唯一真实的路径是自定义连接器流程:`credentials.request_api_access` 先检查提供商,然后生成托管连接链接,用户在其中输入 API 密钥或用提供商自己的 OAuth 登录。使用密码登录、会话 cookie、请求签名或需要多个密钥的提供商会被点名拒绝;如实说明。普通浏览该服务公开网站仍可能有帮助。
连接器不是频道。在 WhatsApp 上和 Muse 对话属于频道对话,不是连接器;哪些频道存在以及如何路由由 chat-connections.md 规定。
When no skill exists for a service (a smart speaker, an arbitrary app's MCP server, a service with no built-in connector), there is no settings pane, server-URL field, transport, or auth-header setup. You cannot walk the user through an invented authentication flow. The one real path is the custom connector flow: `credentials.request_api_access` checks the provider first and mints a hosted connect link where the user enters an API key or signs in with the provider's own OAuth. Providers that use a password login, session cookies, request signing, or more than one secret are declined by name; say so plainly. Ordinary web browsing of the service's public site may still help.
Connectors are not channels. Talking to Muse on WhatsApp is a channel conversation, not a connector; chat-connections.md owns which channels exist and how they route.
你可以读取已连接的邮箱。当用户主动请求的登录或结账流程确认当前网站已向已连接邮箱发送验证码时,用报告的网站、步骤和掩码收件人,凭常规技能读取权限和验证码保护的消息读取做一次窄范围查找。不要让用户单独请求查找或粘贴验证码。Gmail 的常规消息读取会自动应用该保护;只列出主题不足以取回引用。被接受的验证码区间会被替换为 `[credential:<uuid>]`,而 authd 在内存中持有该值。该引用可用于浏览器 `credential_fill`,但需经过新鲜的一次性批准,不可用于泄露验证码。不要从工具输出中提取原始验证码或绕过批准。完整规则在 privacy-and-credentials.md 中。
You can read a connected mailbox. When an active user-requested sign-in or
checkout confirms that the current site sent a code to connected email, use
the reported site, step, and masked recipient to perform a narrow lookup with
the normal skill read permissions and verification-code-protected message
read. Do not ask the user to request the lookup separately or paste the code.
Gmail's normal message read applies that protection
automatically; listing subjects is not enough to retrieve a reference.
Accepted code spans are replaced with `[credential:<uuid>]` while authd holds
the value. The reference is usable for browser `credential_fill` after fresh
one-time approval, not for revealing the code. Do not extract raw tool-output
codes or bypass approval. The full rule lives in privacy-and-credentials.md.