Skip to content

docs(research): define capability gateway boundary #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
seekskyworld wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(research): define capability gateway boundary #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/research/CAPABILITY_GATEWAY_BOUNDARY_2026-08-30.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# OpenPI Capability Gateway 边界研究

> 状态：validated（设计研究；不代表新增 runtime 实现）
>
> 创建日期：2026-08-30
>
> 最后核验：2026-08-30
>
> 关联 Issue：[#19](https://github.com/openpi-dev/openpi/issues/19)

## 研究结论

Issue #19 的核心问题是能力入口是否应常驻模型上下文。现有证据支持“普通 turn 零常驻 OpenPI surface，明确意图时加载稳定 capability group”的方向；它不支持增加第二套 provider、固定编排器或按模型名称路由。

## 已确认边界

- Pi 原生 `read`、`bash`、`edit`、`write` 仍是普通编码的基础执行面。
- Search、Delegate、Workflow、Background、Session 是可独立加载的能力组；组内 lifecycle 工具由各 owner 按资源状态管理。
- capability discovery 只改变模型可见 surface，不拥有 Subagent、Workflow 或 Background 的执行生命周期。
- 已加载组在 Session 内单调保持，避免频繁增删 schema 导致 cache churn。
- 第三方同名工具不能被 OpenPI 误隐藏；无法证明 source ownership 时必须保留并 fail open。
- child Session 不得通过 gateway 改变父会话工具面，工具仍需通过 child-safe drift guard。

## 设计选择

### Explicit

普通 turn 默认不暴露 OpenPI 工具。用户明确表达需要某类能力时，运行时加载对应组并附带最小 Skill 指针。该路径不做通用自然语言 planner，也不调用隐藏分类模型。

### Adaptive

用户显式选择 Adaptive 后，只保留紧凑的 gateway。主模型阅读完整任务后自行决定是否加载一个或多个能力组；gateway 不是执行器，也不代替模型判断。

@tt-a1i tt-a1i Aug 31, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 [P3，非阻塞] 为当前 Adaptive 行为补版本来源

Adaptive 的描述与当前源码一致，但来源段的 #19/#20 没有描述“用户可选 Adaptive”：#19 提议默认常驻网关，#20 才收敛为普通 turn 零常驻。作为 validated 研究，建议把历史提案、当前实现和后续建议分开标注，并补固定版本依据，例如 当前审查版本的 README 与 capabilities 实现。

另外，PR Approach 承诺的相关诊断记录链接和 Issue 回链目前还未补齐；诊断文档未合并时，链接对应 PR #307 即可。这里需要补可追溯性，不需要修改运行时或另造文档。


### Setup 例外

持久化配置继续只通过 `/openpi-setup` 用户入口开启。Setup 不应成为普通 capability group，也不能由 gateway 自动加载配置写工具。

## 证据与限制

零常驻工具面消除了可重复测量的静态 schema/Skill catalogue 成本，但独立模型采样仍可能造成动态轨迹差异。首请求一致或接近，不能证明后续质量或成本因果；任何 benchmark 都必须同时报告 adopted capability、turn、tool、usage、wall time 和失败分类。

## 非目标

- 不增加常驻的每能力请求工具。
- 不复制 OMP 的完整工具注册、全局 hub、memory 或 workflow runtime。
- 不按 provider/model 名称硬编码策略。
- 不把 gateway 变成关键词路由器、固定数量 planner 或第二 authority plane。
- 不因为一次小样本诊断改写默认产品行为。

## 后续门槛

先在隔离有效的配对任务上比较 Bare Pi、OpenPI Explicit、OpenPI Adaptive 和按需加载组。只有在能力实际被采用且对预注册主要结果产生净收益时，才考虑新增 runtime seam；否则保持当前 Pi-native 最小面。

## 来源

- [Issue #19](https://github.com/openpi-dev/openpi/issues/19)：工具面复盘与 gateway 提案。
- [Issue #20](https://github.com/openpi-dev/openpi/issues/20)：三臂诊断复盘。
- [`docs/README.md`](../README.md)：研究记录状态与证据边界。
1 change: 1 addition & 0 deletions docs/research/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,6 @@ The following records predate [`Decision 0001`](../decisions/0001-documentation-

- [`CLAUDE_CODE_WORKFLOW_FANOUT_POLICY_2026-08-23.md`](CLAUDE_CODE_WORKFLOW_FANOUT_POLICY_2026-08-23.md) — official-source research on dynamic fan-out and bounded execution.
- [`CLAUDE_CODE_WORKFLOW_RUNTIME_CONTRACT_2026-08-23.md`](CLAUDE_CODE_WORKFLOW_RUNTIME_CONTRACT_2026-08-23.md) — version-scoped Workflow contract interview and evidence boundary.
- [`CAPABILITY_GATEWAY_BOUNDARY_2026-08-30.md`](CAPABILITY_GATEWAY_BOUNDARY_2026-08-30.md) — Issue #19 的 Explicit/Adaptive gateway 边界研究。

@tt-a1i tt-a1i Aug 31, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [P2] 将新建研究移出 Legacy records

此列表上方明确写着记录早于 Decision 0001、尚未迁移到新 metadata 契约；但这份新记录标注创建于 2026-08-30，而 Decision 0001 已于 2026-08-29 生效。放在这里会把新文档误标成历史豁免记录，也与文件自身的 validated 状态说明不一致。

请将条目放到独立的当前研究小节，并按现有 docs/README.md 约定声明适用来源/版本、相关 PR 和替代关系。只需调整文档分类及必要信息，不需要引入新格式框架。


When research changes a project constraint, preserve the adopted choice in a Decision. Amend or supersede a historical record rather than silently rewriting its original conclusion.
Loading