确认与人工接力

可运行示例在浏览器中运行本章示例

这里运行与本地夹具相同的 Vue 3 源码。模型请求由服务端网关转发，供应商密钥不会进入浏览器。

本地运行pnpm tutorial:dev v3-15 --locale zh源码examples/tutorials/v3-15-confirmation-and-human-handoff/

agent 能描述一项页面能力，不等于它可以直接执行。归档工作区、删除记录、发布版本可能需要用户批准；验证码、U 盾、法律确认等步骤则根本不能交给 agent，必须由使用页面的人完成。

Pling 把这两类事件分开：

确认回答“允许 agent 做吗？”
人工接力回答“用户现在能完成这一步吗？”

它们都不是提示词要求，而是执行流水线中的真实环节：模型选定动作后、业务操作完成前，由框架停下来处理。

先声明风险，再做有意覆盖

动作的 kind 决定默认风险：

`kind`	默认审批
`read`	不确认
`write`	不确认
`danger`	每次都确认，不提供“始终允许”

默认不合适时，用 confirm 覆盖：

const saveAction = {
  id: 'save_workspace_name',
  desc: '保存共享的工作区设置。这个写操作需要确认一次。',
  kind: 'write',
  confirm: true,
  run: saveName,
};

const resetAction = {
  id: 'reset_workspace',
  desc: '清空工作区设置。这个危险操作每次都需要确认。',
  kind: 'danger',
  confirm: 'always',
  run: resetWorkspace,
};

解析后的策略是：

声明	审批	本段会话可“始终允许”
`read` / `write`	`none`	不适用
`write` + `confirm: true`	`ask`	可以
`danger`（包括 `confirm: true`）	`ask-always`	永不提供
任意 `kind` + `confirm: "always"`	`ask-always`	永不提供

confirm: false 只用于确有独立安全机制的少数情况。它不会让动作变安全，只是移除了这道闸门。

确认发生在执行流水线里

模型提出动作后，执行器依次检查参数、作用域、可用性和审批。需要确认时，runtime 向用户询问。用户拒绝会产生 PERMISSION_DENIED，动作的 run 不会执行。

顺序很重要。只在界面上隐藏危险按钮不够，因为能力仍可能出现在快照中；只在提示词里写“不要删除”也不够，因为提示词不是策略边界。

agent runtime 通过界面提供待审批项。示例由 <AgentDock> 渲染审批面板。自定义宿主可以直接使用 runtime 的审批队列，但必须保留同一条规则：只有明确批准后才能执行。

不要先修改数据、再弹确认。审批是前置条件，不是事后通知。

人工接力意味着框架不会替用户点击

示例的发布动作声明了接力：

handoff: {
  reason: '发布前需要本人确认验证码。',
  steps: [
    { text: '在验证码输入框中填写 246810。', highlight: 'verification_code' },
    { text: '点击“发布变更”完成确认。', highlight: 'publish_changes' },
  ],
  expect: {
    desc: '工作区变更已经发布',
    check: () => published.value,
  },
}

模型调用 publish_changes 时，执行器跳过动作的 run，发出包含原因与步骤的接力请求，高亮当前目标，然后等待三种结果之一：

结果	错误码	含义
用户完成	无	`expect` 通过后才报告成功
用户取消	`HANDOFF_CANCELLED`	这一步没有发生
超时	`HANDOFF_TIMEOUT`	没有确认到完成

默认等待时间是五分钟；单个动作可以在自己的 handoff 声明中覆盖。超时不是“自动重试”的信号，模型应先询问用户接下来怎么办。

只要结果可以检查，就应写 expect。否则用户点“我已完成”只是一个说法。检查应读取真实业务状态，而不是短暂的 toast。