04 审批模式与令牌服务

04 审批模式与令牌服务

本节摘要:这是第 4 章的收尾。除了鉴权与 scope,服务端还有两个治理机制:审批模式(敏感操作需人确认)和令牌服务(令牌的签发/校验/撤销)。本节讲清这两个机制,以及它们如何与 OpenCode 的权限询问(OpenCode 教程第 4 章)衔接。

一、审批模式:敏感操作需人确认

即使令牌 scope 允许某操作(如 collaborator 能写),有些操作还是希望「人来确认一下」——这就是审批模式。

OpenWork 的审批分两档:

Agent 要执行敏感操作
   │
   ▼ 审批模式?
   │
   ├─ manual ──► 创建审批请求,暂停等用户确认
   │    ├─ 用户允许 ──► 执行
   │    └─ 用户拒绝 / 超时 ──► 不执行
   │
   └─ auto ──► 直接执行
​

二、manual 模式的流程

manual 模式下,敏感操作的流程:

Agent 请求执行操作 X
   │
   ▼ 创建审批请求(含操作详情)
   │
   ▼ 暂停(创建 pending Promise + 超时定时器)
   │
   ▼ 通知用户(界面显示「Agent 想做 X,允许吗?」)
   │
   ▼ 等待用户响应
   │
   ├─ 用户「允许」 ──► resolve Promise,执行 X
   ├─ 用户「拒绝」 ──► reject,Agent 收到拒绝
   └─ 超时(超过 timeoutMs)──► 自动拒绝(reason: timeout)
​

注意超时——如果用户没及时响应(磨蹭或离开了),超时自动拒绝。这防止了「审批请求永远挂着」的资源泄漏。

三、审批与 OpenCode 权限询问的关系

这里要澄清一个易混点:OpenWork 的审批模式 vs OpenCode 的权限询问(OpenCode 教程第 4 章)。两者都「停下来问用户」,但层面不同:

二者协作:

Agent 要执行 bash(改文件)
   │
   ▼ OpenCode 引擎层:权限求解(第 4 章)
   │    └─ 规则 ask ──► 触发询问
   │
   ▼ 询问传到 OpenWork 服务端
   │
   ▼ OpenWork 审批模式:
   │    ├─ manual ──► 走审批流程(暂停等用户)
   │    └─ auto ──► 自动允许
​

OpenCode 的权限判定决定「这个工具要不要问」,OpenWork 的审批模式决定「问的时候要不要人确认」。前者是规则,后者是模式。

四、令牌服务

令牌服务管理令牌的全生命周期:

签发:create() ──► owt_abc123(明文)+ 存 hash(owt_abc123)
   │
校验:请求带 owt_abc123 ──► hash 比对 ──► 命中 ──► 有效,查 scope
   │
撤销:删 hash 记录 ──► 下次校验不命中 ──► 失效
​

五、令牌的存储

令牌存储在一个文件里(如 tokens.json),结构大致:

{
   schemaVersion: 1,
   tokens: [
      { id, hash, scope, createdAt, label? },
      ...
   ]
}
​

注意存的是 hash 不是明文——这是安全惯例。即使存储文件被泄露,攻击者也拿不到明文令牌(哈希不可逆)。校验时也是哈希比对。

💡 为什么存哈希:和密码存储同理——不存明文,防泄露。令牌明文只在签发时返回一次,用户必须自己保管好;丢了只能重新签发。

六、特殊令牌:配置令牌

有个特殊:配置里设的「配置令牌」会被识别为 collaborator scope(不是 owner)。这是一种「给配置一个降级权限」的机制——配置里硬编码的令牌,即使泄露,也只有 collaborator 权限,不能做管理操作,降低风险。

七、第 4 章收尾:治理的全貌

读完第 4 章四节,你掌握了 OpenWork 治理的全貌:

核心认知:OpenWork 的治理是多层叠加的——鉴权模式管入口、scope 管操作、反代层强制只读、审批管敏感操作、令牌服务管凭据。层层叠加,既灵活又安全。第 5 章我们看引擎托管——这套治理如何应用到被托管的引擎上。

本节要点回顾

1. 审批模式:manual(需人确认)/ auto(信任执行)。
2. manual 流程:创建请求→暂停→等用户→允许/拒绝/超时自动拒。
3. 超时自动拒:防审批请求永远挂着。
4. 审批 vs OpenCode 权限询问:前者平台级模式,后者引擎级规则,协作。
5. 令牌服务:签发(明文一次+存hash)/校验/查scope/撤销。
6. 存哈希不存明文:安全惯例,防泄露。
7. 配置令牌=collaborator:降级权限,降低硬编码泄露风险。
8. 第 4 章结束:治理多层叠加(鉴权+scope+反代+审批+令牌)。

第 4 章结束。下一章讲引擎托管——OpenWork 如何反向托管 OpenCode 引擎、注入配置。