用途:指导实现 Gatekeeper——一个 Cloudflare Worker,作为 Gadget 与外部服务之间的唯一访问中介。它采用三层结构:Vendor(GatekeeperVendor,WorkerEntrypoint,每个服务一个)、User(GatekeeperUser,带 ctx.props 的 WorkerEntrypoint,代表已认证的人类用户连接)、Instance(Gatekeeper<Session>,Overseer 的 DO facet,按资源、按 Gadget 绑定并提供 Session API)。规范接口见 packages/workshop-shared/src/gatekeeper.ts。
七项职责:1) 认证管理,通过 OAuth 等代表用户管理连接账户(令牌存储、刷新、撤销,存于 UserAccount Durable Object);2) API 设计,提供兼容 Cap'n Web RPC 的 TypeScript 包装,按能力安全设计为面向对象、按逻辑资源划分接口;3) 细粒度资源授权,允许用户按具体文档或仓库等粒度授权,同时也可支持粗粒度;4) 日志与审批,所有动作经 ApprovalQueue,有外部可见副作用的操作须 submitAction() 且经 applyAction() 后才执行,只读观察须先 authorizeObservation();5) 缓存,将远端内容缓存到 DO 存储以提升性能并改善 API 形态;6) 模拟,已提交未应用的动作应尽量按已发生来模拟,便于批量审批;7) 观察者验证,通过 getVerifier()/addObserver()/removeObserver() 确保协作者能自行访问 Gadget 曾读取的数据。
实施分两阶段。阶段一只做职责 1-3,但观察者方法需保留最小实现以通过类型检查。步骤:理解外部服务(认证模型、资源与粒度、观察与动作划分);设计 Session 类型(src/types.d.ts,先读 capnweb README,一资源一接口,返回结构化数据,含 JSDoc);停下让操作者评审 API;按 SKELETON.md 实现包结构;注册(无需手动绑定,run-dev-server.ts 自动绑定 GATEKEEPER_<NAME>);添加资源选择 UI(可选用 @gadgets/configurator-ui,支持 initialValuesFromResourceUrl 预填);再次停下询问是否进入阶段二。阶段二实现职责 4-7。
限制:types.d.ts 是智能体唯一文档,须自包含、不得泄露审批队列或内部实现细节,仅允许 cloudflare:workers 导入,由 pnpm lint 的 gadgets/self-contained-agent-types 规则强制。资料未提供具体收费、价格或平台信息。