OpenPI 产品哲学：Build for Model Leverage

[tt-a1i]

OpenPI 的目标不是建设第二套 Agent OS，而是在 Pi 已有的 Session、Tool、Skill、Trust 和生命周期之上，提供一个薄、深、可组合、可验证的能力层。

这篇总纲用来讨论长期产品哲学和判断标准。具体实现、实验和缺陷仍由 Issue 跟踪；形成稳定结论后，再沉淀到版本化的 Decision / Design 文档。

基本立场

模型负责判断

• 理解用户意图并选择策略；
• 决定是否以及怎样委派；
• 根据证据调整方案并综合结果；
• 判断何时需要用户输入。

Runtime 负责可执行事实

• 权限、Trust、隔离和能力边界；
• 并发、调用、时间与资源上限；
• 生命周期、取消、清理、持久化与恢复；
• 原子性、幂等、重放安全与 fail-closed；
• 可观察状态和确切终态证据。

我们希望能力像“水面上的船”：模型能力提高时，工具的价值随之提高，而不是用固定 Workflow、关键词路由器或第二控制面限制模型。

需要持续回答的问题

1. 哪些 Pi primitive 已经拥有这个生命周期？
2. 这是模型判断，还是 Runtime 必须执行的不变量？
3. 能否提供一个正交机制，而不是规定一条 Workflow？
4. 更强的模型能否直接把它用得更好？
5. 什么证据能区分成功、失败、取消与不确定？
6. 权限如何被限定、检查、停止和清理？
7. 某项能力产生的价值，是否覆盖了它的 Schema、上下文、调用、结果和维护成本？

专题索引

1. Capability Shape and Harness Value #314：什么能力值得存在，应做成 Primitive、Skill、Tool、Subagent 还是 Workflow。
2. Capability Discovery and Authority #312：Explicit、Adaptive、自然语言发现与 Runtime 授权。
3. Tool Surface Economics #300：工具定义、缓存、常驻/渐进/native deferred 的完整成本。
4. Tool lifecycle across context epochs #311：动态能力如何跨越 Compaction、Resume 与 Provider 变化。
5. Evidence and Evaluation #313：怎样证明能力的净收益，怎样改变默认策略。

五个专题形成一条产品因果链：

什么能力值得存在、应是什么形态
→ 谁能发现和授权
→ 定义怎样进入模型上下文
→ 跨生命周期怎样重新投影
→ 什么证据足以保留、默认、重构或删除

Function Call 基础留在 #300；Provider 差异贯穿 #300/#311；竞品比较作为证据进入 #313，不单独拆成输赢帖。

已有记录

• #20 从 31 个常驻工具到零常驻表面
• #84 工具 Schema、角色披露与缓存稳定
• #156 逐 turn prompt-cache 失效诊断
• #191 Prompt Cache 所有权与生命周期边界
• #194 模型可见注入面、顺序、权限与证据

讨论如何进入产品

Discussion：形成问题、备选方案与权衡
→ Decision / Design：记录稳定结论与证据边界
→ Issue：承载明确的实验或实现
→ PR：交付并验证

欢迎挑战这里的假设，但请尽量区分事实、推断、建议、未知和已经验证的结果。

[somewan820]

补充说明：这些问题背后的共同判断框架

这组问题不是要求开发者执行一套固定流程，而是帮助项目在增加能力之前，明确它的必要性、所有者、边界、证据和完整成本。

OpenPI 最根本的思想是：让模型负责判断，让 Runtime 负责必须可靠成立的事实，并优先复用 Pi 已经提供的基础能力。

以下内容是对这一思想的通俗解释，不新增项目约束，也不代表任何候选方案已经被采纳。

一、先确认谁已经负责，再决定是否增加能力

“哪些 Pi primitive 已经拥有这个生命周期？”

每项能力都有完整生命周期，包括发现、加载、执行、持久化、恢复、取消和清理。

设计新能力之前，首先要确认 Pi 是否已经负责其中一部分。如果 Pi 已经拥有对应的 Session、Tool、Skill、Trust 或扩展生命周期，OpenPI 应优先复用或加强现有接口，而不是建立第二套平行实现。

同一项事实应尽量只有一个权威来源。重复保存状态、权限、历史或恢复信息，会让不同系统对“当前真实状态”产生不同判断。

只有在现有基础能力确实无法表达需求，并且新增层的所有权和生命周期能够被清楚说明时，才应该增加新的运行时能力。

“这是模型判断，还是 Runtime 必须执行的不变量？”

模型负责需要理解语境和权衡利弊的判断，包括理解意图、选择策略、决定是否委派、调整执行方式、综合证据，以及判断何时需要用户输入。

Runtime 负责不能依赖模型自觉遵守的规则，包括权限、Trust、隔离、资源限制、并发限制、取消、清理、持久化、恢复、原子性、幂等性和失败关闭。

Prompt 可以指导模型，但不能代替 Runtime 强制执行安全和正确性规则。反过来，Runtime 也不应该把本应由模型完成的任务判断固化成关键词路由器或固定流程。

二、提供最小机制，不替模型规定思考过程

“能否提供一个正交机制，而不是规定一条 Workflow？”

正交机制是职责明确、可以独立使用、可以自由组合的小型能力。它只解决一个具体问题，不同时规定任务策略、执行顺序和最终结论。

设计时应从最小能力开始判断：优先使用 Pi primitive；知识和方法交给 Skill；需要校验的动作交给窄 Tool；必须持续成立的约束交给 Runtime policy；只有独立上下文、后台生命周期或多阶段恢复本身确实产生价值时，才使用 Child Session、Background capability 或 Workflow。

Workflow 的价值来自阶段依赖、持久状态、暂停恢复、重放、人工检查点和可审计证据。Workflow 不应只是把模型原本可以自由决定的步骤固定下来。

“更强的模型能否直接把它用得更好？”

一项能力应当允许更强的模型更准确地判断何时使用、怎样组合、需要多少资源，以及怎样验证结果，而不要求框架随模型升级反复重写。

如果能力依赖固定分类、固定拆分、固定调用数量或固定推理顺序，模型能力提升也无法改善它的使用方式。

同时，模型变强并不自动证明应该增加更多 Harness。更强的模型可能更会使用运行时能力，也可能更少需要额外抽象。是否保留或扩大一项能力，仍然需要实际证据。

模型能力可以变化，但 Runtime 对权限、安全、生命周期和终态事实的保证不能因此减弱。

三、先定义证据和权限，再讨论功能是否完成

“什么证据能区分成功、失败、取消与不确定？”

每项能力在实现之前，就应明确四种结果分别需要什么可验证证据。

成功必须有确切终态和结果凭据；失败必须保留失败原因；取消必须证明取消已经生效；缺少终态或无法确认外部影响时，必须保留为不确定。

模型生成的文字、界面标签和进度描述都不是执行事实。模型可以解释证据，但不能凭自己的判断把未知状态改成成功。

Runtime 应保存当时真正观察到的事实。后来获得的新证据应作为新的记录追加，而不是静默改写原始历史。面向用户的当前展示可以更新，但必须能够追溯到权威记录。

“权限如何被限定、检查、停止和清理？”

每项能力都必须说明谁可以启用、能够访问什么、当前正在做什么、怎样停止，以及结束后如何清理。

Child 的权限只能来自用户配置、Parent 权限、Child 边界、Trust 和当前资源限制的交集。任何 Prompt、模型输出、历史摘要或 Provider 引用都不能扩大这个交集。

能力必须可以被检查和停止。取消不能只改变界面状态，而要真正终止相关执行并完成有界清理。

恢复时必须重新核对当前权限和资源。旧状态可以作为历史证据，但不能自动恢复已经失效或被收回的权限。

四、最后判断完整价值，而不是只看功能是否可用

“某项能力产生的价值，是否覆盖了它的完整成本？”

一项能力的价值不能只看它是否被调用，也不能只看它是否在一次任务中产生了正确结果。

完整收益取决于任务是否适用、模型能否正确发现和使用能力，以及使用后是否真正改善质量、效率、安全性或可恢复性。

完整成本包括：

• 所有任务承担的 Schema 和固定上下文成本；
• 能力加载、模型调用和结果回放成本；
• 错误发现、错误调用和长执行轨迹的成本；
• 权限、资源、取消、恢复和清理风险；
• 实现、测试、文档、兼容和长期维护成本。

高使用率不等于高价值，低使用率也不等于没有价值。判断标准应当是净收益，而不是调用次数、工具数量或单次演示效果。

改变默认策略之前，需要分别验证普通任务是否承担了额外损失，以及真正需要该能力的任务是否获得了可独立验证的收益。

最根本的结论

OpenPI 不负责替模型设计一套固定思考方式。

OpenPI 应当提供小而清楚、可以自由组合的能力，让模型根据真实任务决定怎样使用；同时由 Runtime 保证权限不会扩大、资源不会失控、执行可以停止、历史可以恢复，成功、失败、取消和不确定都有确切证据。

一项新能力只有在现有 Pi primitive 无法满足需求、职责边界清楚、生命周期完整、权限可以强制、结果可以验证，并且完整收益覆盖完整成本时，才值得成为 OpenPI 的一部分。