学习笔记 · Obsidian
Fleet：Channels、Slack、Teams、Schedules 与 Webhooks
Channels 接收外部事件，Schedules 接收时间事件，Fleet Webhooks 则把 Agent 配置发布给外部系统。三者方向不同：channel/schedule 是“触发 Agent 运行”，webhook 是“由人在 Fleet 里触发配置包外发”，不能混称触发器。
Channels 的共同语义
Channel 连接在 Agent 的 Channels drawer，可暂停/恢复全部 channels 而无需删除。Chat-only Agent 的新响应通常把 thread 标为 unread；channel-based Agent 的响应默认保持 read。手动 read/unread 只是 inbox 状态，不表示业务事件已处理。
Gmail channel 只监控 primary inbox，忽略 alias、mailing list、被 filter 跳过 inbox 的邮件以及 spam/trash。Slack 由 mention、DM 或 group DM 触发；Teams channel 内必须 @mention，DM/group chat 则对所有消息响应。
外部事件可能重复、乱序或重试。Agent 对发送、标签、工单和发布工具要使用外部 event ID/业务 key 做幂等，不能仅依赖 thread 看起来“只收到一次”。
Slack Cloud：每个 Agent 一个独立 app
Fleet Slack manager 首次连接后提供两类 scope：Agent 发消息/读历史的工具权限，以及代表 Fleet 创建专属 Slack app 的管理权限。随后从 Agent Channels 一键 Add to Slack；Fleet 以 Agent 的 name、description 和 icon 建立 app。
约束：一个 Agent 恰好最多关联一个 Slack app，一个 Slack app 也只能关联一个 Agent。若 workspace 要求每个 app 单独管理员审批，第一次 Finish setup 只生成 draft 并发起请求；管理员通过后必须回 Fleet 再次 Finish setup 才真正安装。
Agent 可：
- 在 channel mention、DM、group DM 启动 run；
- 在线程内回复并读取 thread/channel history；
- 读取接收到的附件；
- 在 Slack thread 内显示工具审批按钮；
- 运行出错时在原 thread 返回错误信息。
Allow bot triggers 会允许其他 bot 的消息触发，可能形成 bot-to-bot 循环或放大成本，默认关闭，开启时要限定 channel、事件类型和去重。
Slack Self-hosted：两层 OAuth 配置
自托管没有 Fleet Slack manager，需要：
- Helm
fleet.oauth.providerOrgId与fleet.oauth.slackOAuthProvider指向统一的 Slack OAuth provider； - 在 Slack 建 provider app，配置文档列出的 history/read/write/team/users scopes；
- 在对应 LangSmith organization 注册 client ID/secret、authorize/token URL；
- Slack redirect URL 为
https://<hostname>/host-oauth-callback/<provider-id>； - 每个 Agent 再从 Fleet 生成 manifest，建立其独立 custom Slack app，并录入 App ID、client ID/secret、signing secret。
必须从 Fleet 生成 manifest，手工建立 app 会缺 event subscription、interactivity、redirect 与 scopes，导致收不到事件。Draft 不保存 client/signing secret，管理员批准后恢复设置时要重新输入。
自托管 Add Slack App 置灰时先查 slackOAuthProvider，unknown provider 先查 provider 是否注册在 providerOrgId 指定的 organization。Secret 只显示/复制到受管 secret store，不记录到笔记、工单或日志。
Slack tools 和 Slack channel 是两回事。Tools 可从 Fleet UI、schedule、webhook 等任意来源发送/读 Slack；channel 只定义 Slack 消息如何启动 Agent。工具逐项设 Auto/Ask。
Teams：Bring Your Own Azure Bot
Teams 需要在 Azure 建 Multi Tenant Azure Bot 与 Microsoft App ID，立即保存只显示一次的 client secret。把 App ID/password（可选 tenant ID）注册到 Fleet 后，Fleet 返回 webhook URL；再回 Azure Bot Configuration 设置 Messaging endpoint，启用 Microsoft Teams channel，并安装引用 App ID 的 Teams manifest。
Bot 可从 Integrations 或 Agent sidebar 链到 Agent。连接后可添加：
teams_bot_send_proactive_message：使用 Bot Framework credential，无需另行 OAuth；- list teams/channels、post/read channel messages：使用 Microsoft Graph，可能要求用户 OAuth consent。
Channel conversation 只有 @mention 才触发；DM/group chat 全消息触发。Direct message 正常但 channel 失败时，先查 mention、bot 是否加入 team、channel 权限；完全不响应再查 Fleet approval/feed、paused 状态和 Azure messaging endpoint。Invalid credential 则查 App ID、secret value/expiry 与 Multi Tenant 类型。
Schedules：UTC 的主动运行
Schedule 用于 daily briefing、memory synthesis、weekly update、monitoring 等周期任务。配置执行时间时统一按 UTC；可添加自定义 prompt。它没有最终用户在场，因此要求 fixed Agent identity，且任何 Ask 审批或 memory-write approval 都可能让任务永久停住。
无人值守上线前要验证：时区与夏令时、重叠执行、失败重试、最大运行时、幂等、无数据分支、结果投递失败、预算限制以及人工接管。对于非幂等写操作，宁可先生成草稿或审批项，不要直接 Auto。
Fleet Webhooks：发布完整 Agent 配置
Webhook URL 必须 HTTPS；custom headers 加密存储；payload 带 publisher identity；Webhook 只对 Agent owner 可见。它发送的不只是通知，而是包含 Agent files 的完整包：
| 字段 | 内容 |
|---|---|
action | Webhook 名称 |
input | 自定义表单值 |
publisher | 触发者 user ID/email |
agent | name/description |
tool_auth_requirements | 每个工具的 none/api_key/oauth 需求 |
files | Base64 ZIP |
fields | 自定义输入 schema |
ZIP 包含 AGENTS.md、config.json、tools.json、可选 skills/*、subagents/*。tools.json 还含 MCP URL、server name 与 interrupt config。因此接收端必须把 Webhook 当高敏感供应链入口：验证来源、签名或强 bearer/mTLS、限制 body、避免 zip bomb/path traversal、恶意内容扫描、不可执行地解压、保留内容 hash 与 publisher 审计。
tool_auth_requirements 只描述部署需要的凭据，不应包含实际 secret：
none：无认证；api_key：required_env_vars；oauth：provider 与 scopes。
Custom form 支持 string、number、boolean、textarea、json、select。用于 environment、dry-run、发布说明等，但服务端必须再次做类型、枚举、权限和业务校验，不能信任 UI。
推荐事件流
flowchart TD
A["Slack / Teams / Gmail / Schedule"] --> B["触发 Fleet Run"]
B --> C["去重与授权"]
C --> D["只读分析"]
D --> E{"高风险工具?"}
E -- 是 --> F["Ask / 中央或渠道审批"]
E -- 否 --> G["Auto 执行"]
F --> G
G --> H["原渠道回执 + LangSmith Trace"]
I["Owner 手动 Run Webhook"] --> J["外部 CI/CD 验签、校验、解包"]生产检查
- 事件入口与发送工具分开授权；不因能收 Slack 就默认允许发所有 channel。
- 为 Slack/Teams/Gmail 记录 platform event ID，保证重复投递幂等。
- Bot-to-bot、proactive message 和 schedule 设置速率/递归保护。
- 自托管 Slack/Teams secret 放 secret manager，配置轮换和过期告警。
- Schedule 统一 UTC 并明确业务时区，模拟夏令时与长任务重叠。
- Webhook 接收端拒绝 HTTP、未知 publisher、超大 payload、危险 ZIP 路径和未授权 environment。
- 所有触发、审批、拒绝、执行与回执都能通过 trace 串起来。