Appearance
Agent 执行基础设施变更：凭证卫生与人机交接点
第二部 · Agent 实践 · 第20章
撰写日期：2026-07-06
结论
让一个带浏览器操作能力的 Agent 去做一次真实的基础设施接入任务（接入外部代码托管平台、把定时同步改成实时、把登录凭证从个人账号迁移到组织账号），暴露出的问题很少是"Agent 会不会点错按钮"，而是权限模型、凭证归属和人机交接点有没有设计对。
这三者中任何一个错了，事故都不会立刻发生——它会在下一次人员变动、下一次排障，或者下一次凭证泄露复盘时才出现。基础设施接入类任务的验收标准，不该只是"跑通了"，而应该是"跑通之后这套凭证和权限结构经得起半年后的审计"。
1. 最小权限铸造：一个用途一把钥匙
手头有一把权限很大的凭证时，复用它去完成新任务是最省事的路径，但风险敞口是这把钥匙的全部权限范围，而不是这次任务实际需要的范围。这一点在凭证要被写进某个不受控位置时尤其致命——比如某些第三方回调配置只接受把凭证拼进 URL 查询参数，不支持自定义请求头，凭证等于以明文形式存进了对方平台的配置和日志里。
| 场景 | 复用大权限凭证的风险 | 铸造最小权限凭证的做法 |
|---|---|---|
| 日常调用一个 API 做多种操作 | 一把钥匙走天下，权限只会越攒越大 | 按"读/写""哪个资源类型"拆分成多把钥匙，各自最小化 |
| 凭证要嵌入第三方回调 URL | 明文权限敞口 = 这把钥匙的全部能力 | 单独铸造一把只覆盖"触发这一个操作"的钥匙 |
| 给临时任务临时授权 | 图省事直接给管理员级权限 | 任务结束后能直接吊销这一把，不影响其他用途 |
每次要把凭证交出去之前，先问一句：这次真正需要的最小权限集合是什么，就照这个集合单独铸造一把新钥匙，而不是把手头现成的、权限更大的那把复用过去。 多铸造一把钥匙的成本是几十秒，权限敞口收窄的价值会在出问题的那一天兑现。
2. 组织资产还是个人资产：第三方凭证该挂在谁名下
第三方集成凭证（OAuth 应用、API 密钥）默认应该挂在团队的组织账号下面，而不是某个具体成员的个人账号下面。这不是合规洁癖，是可用性问题：挂在个人账号下的凭证，一旦这个人离职、账号被封禁或者被移出组织，凭证会瞬间失效且可能没人有权限接手；挂在组织账号下，归属清晰，所有管理者都能共同维护，交接不依赖任何一个具体的人。
| 归属方式 | 谁能管理 | 人员变动时的风险 |
|---|---|---|
| 挂在个人账号下 | 只有这个人（以及能登进他账号的人） | 人一走，凭证悬空，轻则需要重新走一遍接入流程，重则直接失效 |
| 挂在组织账号下 | 组织内所有具备相应权限的管理者 | 人员变动不影响凭证本身，只是管理权限的转移 |
如果发现某个已经在跑的基础设施凭证挂在个人账号下，不用等到出问题才想起来迁移——发现的当下就应该主动提出，把"公司资产"和"个人资产"分开，是接入任务里最容易被忽略、但成本最低的一步修正。
3. "404" 不一定是"不存在"
一次批量操作里，同一个 API 调用在部分对象上成功、在另一部分对象上返回"资源不存在"，第一反应很容易是怀疑对方拼错了名字或者资源确实没建好。真正的原因往往是权限不足：不少平台在调用者对某个资源没有管理权限时，会返回"不存在"而不是"无权限"，以避免向未授权的调用者暴露资源是否存在。
| 现象 | 常见误判 | 更该做的排查 |
|---|---|---|
| 同一操作对 A 成功、对 B 报"未找到" | B 这个资源命名有误或者没创建 | 先对比调用者在 A、B 上的权限级别是否一致 |
| 批量任务里少数几个失败 | 随机抖动，重试就好 | 检查失败的那几个是不是恰好都缺少同一种权限 |
遇到"资源不存在"类报错，尤其是同类操作已经在别的对象上成功过的情况下，应该先怀疑权限而不是怀疑资源真的不存在。 这条经验和「UI 权限 ≠ API 权限」是同一类陷阱的两种表现：平台暴露给你的错误信息，不一定诚实地反映真正的原因。
4. 实时同步：先问"多久变一次"，再选"怎么做"
把一个定时同步任务改成"更实时"，最直觉的做法是把轮询间隔调短。这个方案本质没变——不管上游有没有变化，到点就做一次完整检查，只是把浪费的粒度调细了。另一种做法是让上游在真正发生变化时主动触发一次同步（事件驱动），空闲时零成本，变化发生后是秒级响应。
| 方案 | 触发条件 | 空闲时的成本 | 延迟 | 一次性设置成本 |
|---|---|---|---|---|
| 缩短轮询间隔 | 固定时间到点 | 每次都要做一次完整检查，不管有没有变化 | 最坏情况等于一个轮询周期 | 几乎为零 |
| 事件驱动触发 | 上游真实发生变化时 | 零 | 事件到达即触发，通常是秒级 | 需要为每个资源单独接一次事件源 |
问"要多快"这个问题时，更该先问的是"变化发生的频率有多低"——事件驱动方案的优势恰恰在变化稀疏、发生时间不可预测的场景里最大化。 如果上游变化本身就很频繁（接近连续），两种方案的差距会缩小，这时候多接一次事件源的设置成本可能就不划算了。选型之前先看清楚这个前提，而不是默认"事件驱动永远更好"。
5. Agent 该在哪里主动停下来
基础设施接入任务里有几类动作不该由 Agent 自主执行到底，而应该显式停下、说明当前状态、等人确认或补一个只有人能提供的输入：
| 交接点 | 为什么必须停 | 恢复方式 |
|---|---|---|
| 即将创建一个会长期存在的外部对象（新注册一个应用、新建一条生产配置） | 这类对象一旦建立就成为需要长期维护的资产，不是可以随手撤销的临时状态 | 说明将要创建的对象及其配置，等待确认后再提交 |
| 拿到一个只显示一次的密钥 | 密钥丢失后往往要走完整的吊销重建流程 | 立即用于下一步，不做无关的中间展示或缓存 |
| 平台要求人类完成二次验证 | 这一步本身就是平台特意设计成"必须是真人"的关卡 | 明确告知在等什么，验证完成后凭一句确认继续 |
| 把配置从草稿提交为立即生效，尤其影响他人登录或访问 | 生效瞬间影响的是别人，不只是操作者自己 | 复述即将生效的内容，拿到明确同意后再提交 |
把这些交接点显式列出来，价值不在"看起来更安全"这种空泛说法，而在于每一次交接都有清楚的输入和输出——人只需要确认"是"或者补一个具体值，不需要重新理解整个任务背景。 交接点设计得好，人机协作的摩擦成本会趋近于零；设计得不好，要么变成事事都要确认的低效，要么变成完全不确认的隐患。