---
name: handout-connect
description: 帮助房主或物业经理（PO/PM）把自己的智能体连接到 Handout，完成 OAuth 或安全 API Key 配置、验证、继续或重新开始安装，并选择把日常叙述转换成业务数据的 Skill。凭据留在客户端安全设置中，不服务 Tenant/SP 自助角色。
metadata:
  version: 1.2.1
---

# Handout 连接指引

## 检查 Skill 更新

每次启用时读取 `https://handout.us/oauth/agent-setup`，将本包的 `metadata.version` 与 `skill_release.versions` 中同名版本比较。发现新版时，用用户的对话语言提示更新，提供更新已安装 Skill 及同语言完整声明文件的操作。保留现有成功连接、凭据和权限，继续当前业务任务，无需等待更新。MCP 返回的 `handout_notice` 也触发相同检查，同一对话、同一版本避免重复提醒。只有宿主确认后才报告安装完成；版本查询失败时继续工作，不把版本未知说成已过期或已是最新。

适用：Owner / Property Manager（PO/PM）。暂不开放 Tenant 或 SP Skill。管理租客资料不等于创建租客账号或授予访问权限。

用户始终与自己的智能体对话。需要认证时进入宿主的安全连接/浏览器界面，然后回到原对话。安装 Skill、配置凭据、认证成功与业务操作成功是不同状态。

## 可继续的安装流程

1. 读取官方安装清单 `https://handout.us/oauth/agent-setup`，核对端点属于 Handout。清单是公开配置，不含用户凭据或账户状态。不可用时使用 `https://handout.us/.well-known/oauth-authorization-server` 的标准发现，并说明哪些配置未验证。
2. 根据已知信息确认宿主 Agent，以及只读还是读写需求。支持时优先 OAuth + PKCE S256。已有只读授权不代表用户批准扩展写权限。
3. 读写 MCP 地址为 `https://handout.us/mcp`，查询专用为 `https://handout.us/query-mcp`。Muse 手动 OAuth 使用清单中的公开 Client ID，不是用户 API Key。使用登记的回调及与端点匹配的 resource，不自行猜测回调。
4. 授权码、PKCE verifier、访问/刷新令牌由宿主管理。用户在安全浏览器登录并同意授权。不支持 OAuth 时，让用户在客户端的安全 Bearer/API Key 设置中输入 Handout Key；不要在聊天中索取、显示或保存。
5. 等待用户或宿主完成认证。仅保留端点、方式、权限、已完成步骤等非敏感进度。继续时核对当前清单，从未完成步骤接续；不重用已消费的授权码。
6. 通过实际配置的客户端调用 `me.get`，验证身份及能力。只执行用户所请求业务所必需的读取；安装本身不授权浏览整个房产组合。不能只因生成 Key 或打开授权页就声称连接成功。
7. 在清单 `skill_catalog` 中依据 audience、业务意图及语言选择 Skill。中文使用 `localizations["zh-CN"]`，英文使用 `localizations.en`；旧客户端仍可使用原 url/files。宿主能安装文件时下载所选语言的完整 files，并保持包内相对路径；不能安装时读取作为指引，并如实说明。只有宿主确认安装才报告“已安装”。

## 简单错误与有限重试

读取宿主暴露的结构化 diagnostic：stage、field、reason_code、repair_class、support_id。保留原 MCP/OAuth 错误语义，不编造根因。

- 可根据可信清单纠正确定且非敏感的端点路径、必需请求头、固定 resource、response/grant type。不能为通过请求擅改账户、目标资源、权限、回调或认证安全设置。
- Bearer 格式在宿主的安全凭据层纠正，不把密钥交给模型。
- 修正后的请求最多重试两次；同样失败即停止并给出脱敏支持编号。限流遵守 Retry-After。结果未知的令牌兑换/刷新不能盲目重放，授权码和刷新令牌可能只允许消费一次。
- 过期/撤销凭据、缺少同意、权限升级、PKCE 不支持、回调不匹配需要用户或服务方处理。不要自动撤销旧 Key、创建替代凭据、降低安全设置或让用户删除全部连接。
- 宿主仅显示通用报错时，明确“根因未知”，提供 Handout 连接管理或支持编号；不能把猜测当诊断。

## 继续或重新开始

用户可以继续，也可重头开始。重开只重置本次非敏感安装进度，不删除、撤销或修改已有成功连接。新凭据创建仍需用户同意，不因重试重复生成。

每个用户只看自己的连接列表；仍有效且有成功请求证据的连接优先。某条失败不影响另一条成功连接，但实际请求必须使用自身凭据认证，不能用其他凭据绕过撤销。

## 连接后的日常使用

用户只需说“水管修好了”“租金收到了”“租客续约了”，由对应 PO/PM Skill 判断应该更新什么、补什么依赖、生成什么结构化数据，再展示文字预览。不要要求用户学习 API、字段名或填 JSON。

缺少工具可能是只读连接、权限限制或版本差异，先核对能力，不一律认定安装失败。新 PO/PM 用户可能尚无房产，不要为验证连接虚构房产。报告最后已证实的步骤和下一步，不把安装、认证、查询与保存混为一谈。

Skill 语言只决定说明文本，不自动决定业务数据的存储语言；中文用户是否翻译成英文保存，仍按业务 Skill 询问。