PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Spec、Grant、Plan 与 Presentation

一句话

Host 先定义 capability 和 policy，再把它们封存成不可由 Guest 扩大的 Plan；Guest 看到的 schema 或 Python wrapper 只是这份 Plan 的 Presentation（使用界面）。

先看一个例子

假设一门课程允许助教程序读取成绩表，但每次任务最多读取两次，而且不能修改原文件。

老师需要分别写清四件事：

  1. “读取成绩表”接收什么参数、返回什么结果；
  2. 本次任务适用哪份访问 policy；
  3. 把能力、policy identity 和两次预算封进本次任务；
  4. 给程序展示一个按钮或 Python 函数，方便它发起请求。

第四步换成按钮、命令行或函数名，不会改变前三步。程序自己再画一个“修改成绩”按钮，也不会得到修改权限。

真实机制

Pysolate 把这四件事对应为：

  • Spec：capability 的规范。它描述名称、版本、effect class、输入输出 schema、handler identity，以及可选的 approval 和 Python projection。
  • Grant：Host policy 的身份绑定。当前实现保存 canonical policy 的 digest；raw policy 留在 Host，不交给 Guest。
  • Plan：Host 将注册过的 Spec、Grant identity 和调用预算一次性封存后的执行计划。Plan identity 来自 canonical plan document 的 digest。
  • Presentation：从同一 Plan 投影给 Guest 的使用表面。

Presentation 有 direct、programmatic 和 both 三种模式。direct 暴露工具 schema，programmatic 生成带 parent call identity 的 Python prelude，both 同时提供两者。它们最终都回到同一 Plan 和 Broker authority seam；不同 physical attempt 可以拥有不同 Broker instance，但不是三套权限系统。

Spec + Grant + budget
        ↓ Host seals
       Plan
        ↓ projects
Presentation: direct / programmatic / both
        ↓ Guest requests
Broker enforces the original Plan

Plan 封存后，Guest 不能通过改 wrapper、伪造 schema 或猜测 capability 名称来扩大它。Broker 按 Plan identity、call identity、预算和 schema 重新检查请求。

为什么重要

技术上： “怎样调用”与“是否有权调用”被分开。开发者可以改变 Python API 的名字或展示模式，而不必复制 handler 和 policy，也不会让界面层成为新的 enforcement point。

产品和业务上： 同一项受控能力可以服务不同 Agent 入口，同时仍有一份清楚的权限和预算定义。审查某次任务时，团队可以指向具体 Plan，而不是猜测当时某个 Python 环境里出现过哪些函数。

不能推出什么

  • Presentation 不是 enforcement；wrapper 和 schema 方便使用，但不能单独授权。
  • Plan digest 证明的是 canonical bytes identity，不证明作者身份、handler 二进制真实性或 policy 的业务正确性。
  • 当前 Plan 只覆盖已注册的 capability；它不是任意 Python 操作的通用权限证明。

术语卡

  • Spec：一项 capability 的 Host-owned 规范。
  • Grant：把 Host policy identity 绑定到 capability 的对象。
  • Plan：封存后的 capability、Grant identity 和预算集合。
  • Presentation：Plan 投影给 Guest 的调用界面。
  • Enforcement：Broker 验证 Plan/Grant identity、预算、schema 和 approval；capability-specific Host adapter/handler 负责解释并执行具体 policy 语义。

继续阅读