Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
Prev Previous commit
Next Next commit
rename
  • Loading branch information
Alanxtl committed Aug 26, 2026
commit 50d3fef29093c8a8efee7976b0eed9ceb6c58f17
46 changes: 23 additions & 23 deletions docs/en/development/plugin-contract.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
title: Host-visible diagnostics contract
description: Contract for the host-visible integration diagnostics RFC.
title: Plugin-visible diagnostics contract
description: Contract for the Plugin-visible integration diagnostics RFC.
---

# Host-visible diagnostics contract
# Plugin-visible diagnostics contract

This page records the contract introduced by the host-visible integration diagnostics RFC. It covers the diagnostic
This page records the contract introduced by the Plugin-visible integration diagnostics RFC. It covers the diagnostic
slice only; shared service state, service lifecycle, installation, and platform adapter contracts belong to their
respective RFCs and implementation slices.

The contract currently applies to Codex, Claude Code, DeepSeek Harness (DSH), OpenClaw, Pi, and Hermes. Bub is out of
scope until it has a host channel, implementation, tests, and support qualification.
scope until it has a Plugin channel, implementation, tests, and support qualification.

The words **MUST**, **SHOULD**, and **MAY** are normative requirements for plugin implementation and review.

Expand All @@ -19,7 +19,7 @@ The original [RFC PR #1299](https://github.com/oceanbase/powercontext/pull/1299)

## What a plugin must report

A plugin MUST report a PowerContext failure when a host-visible operation cannot complete because of one of the
A plugin MUST report a PowerContext failure when a Plugin-visible operation cannot complete because of one of the
classified backend failures. The operation may be context preparation, recall, capture, flush, a direct tool or slash
command, or a health/status check.

Expand All @@ -38,7 +38,7 @@ An empty but valid result is not a failure diagnostic. In particular, an empty m

## Diagnostic event format

Each diagnostic MUST be one JSON object written as one line through the host's supported channel:
Each diagnostic MUST be one JSON object written as one line through the Plugin's supported channel:

```json
{
Expand All @@ -53,7 +53,7 @@ Each diagnostic MUST be one JSON object written as one line through the host's s

| Field | Requirement |
| --- | --- |
| `component` | Stable host-qualified name, such as `powercontext.dsh` or `powercontext.claude_code.recall`. |
| `component` | Stable Plugin-qualified name, such as `powercontext.dsh` or `powercontext.claude_code.recall`. |
| `event` | Short lower-snake-case event, such as `context_prepare`, `capture_source`, `tool_call`, or `status`. It MUST NOT contain a prompt, query, URL, or identifier. |
| `outcome` | One of the four outcomes defined above. |
| `http_status` | Optional integer for an HTTP response. It MUST NOT be fabricated for a transport failure. |
Expand All @@ -71,31 +71,31 @@ event. For example, a numeric `content_bytes` or a bounded `context_status` is a
{"component":"powercontext.dsh","event":"capture_source","outcome":"invalid_response","http_status":500}
```

## Host presentation contract
## Plugin presentation contract

Each plugin MUST use the native host channel. Diagnostics MUST NOT be inserted into model content, recalled context,
Each plugin MUST use the native Plugin channel. Diagnostics MUST NOT be inserted into model content, recalled context,
or a successful tool result.

| Host | Channel | Component prefix |
| Plugin | Channel | Component prefix |
| --- | --- | --- |
| Codex | Hook `stderr` | `powercontext.codex.recall` |
| Claude Code | Hook `stderr` | `powercontext.claude_code.recall` |
Comment thread
This conversation was marked as resolved.
Resolved
| DSH | Host logger warning | `powercontext.dsh` |
| DSH | Plugin logger warning | `powercontext.dsh` |
| OpenClaw | Plugin API logger warning | `powercontext.openclaw` |
| Pi | Host terminal warning (`console.warn`) | `powercontext.pi` |
| Pi | Plugin terminal warning (`console.warn`) | `powercontext.pi` |
| Hermes | Plugin logger warning | `powercontext.hermes` |

The host-facing operation result MAY remain a generic error such as `PowerContext operation failed`. The structured
diagnostic is the recovery signal; the generic result is only for host/model control flow.
The Plugin-facing operation result MAY remain a generic error such as `PowerContext operation failed`. The structured
diagnostic is the recovery signal; the generic result is only for Plugin/model control flow.

## Fail-open, privacy, and presentation bounds

When a PowerContext operation fails:

- recall/context preparation MUST return no recalled context rather than partial or fabricated context;
- capture and flush MUST not terminate or block the host session indefinitely;
- capture and flush MUST not terminate or block the Plugin session indefinitely;
- direct tools and commands MUST return a generic failure result without exposing request details;
- diagnostic emission itself MUST be best effort and MUST NOT turn a backend failure into a host failure.
- diagnostic emission itself MUST be best effort and MUST NOT turn a backend failure into a Plugin failure.

Diagnostics MUST NOT contain endpoint URLs, authorization headers, tokens, cookies, filesystem paths, prompts, queries,
captured text, recalled text, response bodies, or stack traces.
Expand All @@ -112,11 +112,11 @@ Every plugin implementation in this RFC MUST:
2. Attach diagnostics to every relevant failure exit, including lifecycle callbacks and direct tool/command paths.
3. Use a stable component and event name; never put user or request data in either field.
4. Keep the diagnostic formatter independent from model-facing content formatting.
5. Preserve the host's normal behavior when PowerContext is unavailable.
5. Preserve the Plugin's normal behavior when PowerContext is unavailable.
6. Add or update documentation and tests in the same implementation slice.

The plugin MAY choose its language and internal helper shape. It MUST preserve the observable JSON contract and the
host channel listed above.
Plugin channel listed above.

## Required test matrix

Expand All @@ -128,11 +128,11 @@ Each plugin PR that implements this RFC MUST test the following observable behav
4. HTTP 404 produces `version_mismatch`.
5. Other HTTP failures and malformed responses produce `invalid_response`.
6. Repeated failures are deduplicated within the documented bound.
7. Recall, capture, flush, direct tool, slash command, and status paths remain fail-open where the host exposes them.
7. Recall, capture, flush, direct tool, slash command, and status paths remain fail-open where the Plugin exposes them.
8. The diagnostic contains no URL, token, prompt, query, response body, or stack trace.
9. The matching host runner, type checker, or smoke test passes.
9. The matching Plugin runner, type checker, or smoke test passes.

Tests SHOULD assert the parsed event and the host-visible channel. They SHOULD NOT freeze private call order or
Tests SHOULD assert the parsed event and the Plugin-visible channel. They SHOULD NOT freeze private call order or
internal helper names.

## Out of scope
Expand All @@ -141,7 +141,7 @@ This contract does not define:

- shared service state or native service lifecycle;
- service installation, ownership, restart policy, or platform support qualification;
- a common UI for every host;
- a common UI for every Plugin;
- the Bub integration.

Those decisions require their own implementation evidence and review boundary.
48 changes: 24 additions & 24 deletions docs/zh/development/plugin-contract.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
---
title: 宿主可见诊断契约
description: 宿主可见集成诊断 RFC 的契约。
title: 插件集成约定
description: 插件可见集成诊断 RFC 的约定。
---

# 宿主可见诊断契约
# 插件可见诊断约定

本文记录 Host-visible integration diagnostics RFC 引入的契约,只覆盖本次诊断切片。共享 service state、service lifecycle、安装方式和平台 adapter
契约属于各自的 RFC 与实现切片,不在本文定义。
本文记录 Host-visible integration diagnostics RFC 引入的约定,只覆盖本次诊断切片。共享 service state、service lifecycle、安装方式和平台 adapter
约定属于各自的 RFC 与实现切片,不在本文定义。

当前契约适用于 Codex、Claude Code、DeepSeek Harness(DSH)、OpenClaw、Pi 和 Hermes。Bub 尚未具备宿主通道、实现、测试和支持资格,暂不在范围内。
当前约定适用于 Codex、Claude Code、DeepSeek Harness(DSH)、OpenClaw、Pi 和 Hermes。Bub 尚未具备插件通道、实现、测试和支持资格,暂不在范围内。

文中的“必须(MUST)”“应该(SHOULD)”和“可以(MAY)”是插件实现与评审的规范性要求。

本契约来源于 [RFC 1299:Local Server availability and service installation](../rfcs/1299_local_server_availability_and_service_installation.md)。
本约定来源于 [RFC 1299:Local Server availability and service installation](../rfcs/1299_local_server_availability_and_service_installation.md)。
原始 [RFC PR #1299](https://github.com/oceanbase/powercontext/pull/1299) 对应的跟踪 issue 是 [#1298](https://github.com/oceanbase/powercontext/issues/1298)。

## 插件必须报告什么

当宿主可见操作因为下列已分类的 backend failure 无法完成时,插件必须报告 PowerContext failure。适用操作包括 context preparation、recall、capture、flush、
当插件可见操作因为下列已分类的 backend failure 无法完成时,插件必须报告 PowerContext failure。适用操作包括 context preparation、recall、capture、flush、
direct tool、slash command 以及 health/status check。

插件必须使用 typed client error 进行分类,不能通过匹配 exception message 文本来分类。
Expand All @@ -33,7 +33,7 @@ direct tool、slash command 以及 health/status check。

## 诊断事件格式

每条诊断必须通过宿主支持的通道写出一个单行 JSON object:
每条诊断必须通过插件支持的通道写出一个单行 JSON object:

```json
{
Expand All @@ -48,7 +48,7 @@ direct tool、slash command 以及 health/status check。

| 字段 | 要求 |
| --- | --- |
| `component` | 稳定且包含宿主名称,例如 `powercontext.dsh` 或 `powercontext.claude_code.recall`。 |
| `component` | 稳定且包含插件名称,例如 `powercontext.dsh` 或 `powercontext.claude_code.recall`。 |
| `event` | 简短的 lower-snake-case 事件,例如 `context_prepare`、`capture_source`、`tool_call` 或 `status`。不能包含 prompt、query、URL 或 identifier。 |
| `outcome` | 必须是上面定义的四种 outcome 之一。 |
| `http_status` | HTTP 响应可以携带的整数。传输失败不能伪造该字段。 |
Expand All @@ -65,29 +65,29 @@ direct tool、slash command 以及 health/status check。
{"component":"powercontext.dsh","event":"capture_source","outcome":"invalid_response","http_status":500}
```

## 宿主展示契约
## 插件展示约定

每个插件必须使用宿主原生通道。诊断不能插入 model content、recalled context 或成功的 tool result。
每个插件必须使用插件原生通道。诊断不能插入 model content、recalled context 或成功的 tool result。

| 宿主 | 通道 | Component 前缀 |
| 插件 | 通道 | Component 前缀 |
| --- | --- | --- |
| Codex | Hook `stderr` | `powercontext.codex.recall` |
| Claude Code | Hook `stderr` | `powercontext.claude_code.recall` |
| DSH | 宿主 logger warning | `powercontext.dsh` |
| DSH | 插件 logger warning | `powercontext.dsh` |
| OpenClaw | Plugin API logger warning | `powercontext.openclaw` |
| Pi | 宿主终端 warning(`console.warn`) | `powercontext.pi` |
| Pi | 插件终端 warning(`console.warn`) | `powercontext.pi` |
| Hermes | Plugin logger warning | `powercontext.hermes` |

宿主侧 operation result 可以继续返回 `PowerContext operation failed` 这类通用错误。结构化诊断是恢复信号,通用错误只服务于 host/model 控制流。
插件侧 operation result 可以继续返回 `PowerContext operation failed` 这类通用错误。结构化诊断是恢复信号,通用错误只服务于 host/model 控制流。

## Fail-open、隐私和展示边界

PowerContext operation 失败时:

- recall/context preparation 必须返回空的 recalled context,不能返回 partial 或伪造的 context;
- capture 和 flush 不能终止宿主 session,也不能无限期阻塞宿主;
- capture 和 flush 不能终止插件 session,也不能无限期阻塞插件;
- direct tool 和 command 必须返回不包含请求细节的通用 failure result;
- 诊断发送本身必须是 best effort,日志失败不能把 backend failure 变成宿主 failure。
- 诊断发送本身必须是 best effort,日志失败不能把 backend failure 变成插件 failure。

诊断不能包含 endpoint URL、authorization header、token、cookie、filesystem path、prompt、query、capture text、recall text、response body 或 stack trace。

Expand All @@ -102,10 +102,10 @@ PowerContext operation 失败时:
2. 在所有相关 failure exit 接入诊断,包括 lifecycle callback 和 direct tool/command path。
3. 使用稳定的 component 和 event name;不能把用户数据或请求数据放进字段。
4. 让 diagnostic formatter 与 model-facing content formatter 解耦。
5. PowerContext 不可用时保持宿主的正常行为。
5. PowerContext 不可用时保持插件的正常行为。
6. 在同一个 implementation slice 中同步更新文档和测试。

插件可以选择语言和内部 helper 结构,但必须保持可观察的 JSON 契约和上表中的宿主通道。
插件可以选择语言和内部 helper 结构,但必须保持可观察的 JSON 约定和上表中的插件通道。

## 必须覆盖的测试矩阵

Expand All @@ -117,19 +117,19 @@ PowerContext operation 失败时:
4. HTTP 404 产生 `version_mismatch`。
5. 其他 HTTP failure 和 malformed response 产生 `invalid_response`。
6. 重复失败在约定边界内去重。
7. 在宿主提供这些入口时,recall、capture、flush、direct tool、slash command 和 status path 都保持 fail-open。
7. 在插件提供这些入口时,recall、capture、flush、direct tool、slash command 和 status path 都保持 fail-open。
8. 诊断不包含 URL、token、prompt、query、response body 或 stack trace。
9. 对应的宿主 runner、type checker 或 smoke test 通过。
9. 对应的插件 runner、type checker 或 smoke test 通过。

测试应该断言解析后的 event 和宿主可见通道,不应该冻结 private call order 或内部 helper name。
测试应该断言解析后的 event 和插件可见通道,不应该冻结 private call order 或内部 helper name。

## 不在范围内

本文不定义:

- shared service state 或 native service lifecycle;
- service 安装、ownership、restart policy 或平台支持资格;
- 所有宿主共用的 UI;
- 所有插件共用的 UI;
- Bub 集成。

这些决定需要独立的实现证据和评审边界。
4 changes: 2 additions & 2 deletions zensical.toml
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ nav = [
] },
{ "Development" = [
{ "Core Protocol" = "en/development/core-protocol.md" },
{ "Host Integration Contract" = "en/development/plugin-contract.md" },
{ "Plugin Integration Contract" = "en/development/plugin-contract.md" },
{ "Memory Layer" = "en/development/memory-layer.md" },
{ "Pydantic AI Inference" = "en/development/pydantic-ai-inference.md" },
{ "Remote Access Implementation" = "en/development/remote-access-implementation.md" },
Expand Down Expand Up @@ -114,7 +114,7 @@ nav = [
] },
{ "开发" = [
{ "Core Protocol" = "zh/development/core-protocol.md" },
{ "宿主集成契约" = "zh/development/plugin-contract.md" },
{ "插件集成约定" = "zh/development/plugin-contract.md" },
{ "Memory Layer" = "zh/development/memory-layer.md" },
{ "Pydantic AI 推理" = "zh/development/pydantic-ai-inference.md" },
{ "远程访问实现" = "zh/development/remote-access-implementation.md" },
Expand Down
Loading