> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks 与插件

> 把五种宿主事件模型映射到一份已验证的领域契约，同时不虚构统一 HostAdapter SDK。

> [!WARNING]
>
> 共用一份契约，不代表五种宿主可以互换。事件时机、轮次标识、注入方式、对话记录行为、权限 UI 和激活仍由宿主决定。

可靠的适配器要防止过期上下文、避免凭证进入内容，在自动失败时保住宿主任务，并让显式修改操作失败对调用方可见。只在提示词前调一次 API 远远不够。

## 成熟度与安装状态

| 范围 | 状态 | 证据边界 |
| - | - | - |
| 共用领域契约与负向测试 测试向量 | **Supported** | 当前策略、辅助程序与测试覆盖可复用行为 |
| 统一的 `HostAdapter` SDK | **Unsupported** | 当前仓库没有这个抽象 |
| Codex、Claude Code 与 DSH 真实宿主端到端验证 | **Not validated** | 契约与服务链测试没有启动这些真实宿主 |
| OpenCode 真实 宿主进程准备/采集冒烟测试 | **Supported** | Version-gated 真实宿主测试会观察准备/采集请求 |
| OpenCode 完整宿主生命周期端到端验证 | **Not validated** | 该冒烟测试没有完整覆盖转换注入、权限 UI、Skill 加载、清理 与刷新 |
| Pi 完整召回宿主链路 | **Not validated** | 软件包加载另有覆盖 |

> [!NOTE]
>
> `doctor` 属于安装配置/激活验收层级。它不能替代真实启动宿主、发送提示词、观察注入、采集与权限行为。

安装一个适配器，并让 Server 单独运行：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext setup <host> \
  --source oceanbase/powercontext \
  --ref master

powercontext server run
powercontext doctor <host>
```

这些表格不是一套要照搬的统一实现。先从你选择的宿主事件出发，沿着 Scope 解析、临时注入、Source 采集和权限确认逐步实现；每完成一层，就用该层的失败用例证明它不会污染下一轮请求。五种宿主只在领域语义上对齐，事件载荷与返回通道必须服从各自的宿主 API。

## 最小适配器契约

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
PromptEvent
→ ScopeResolver
→ PreparedContextProvider
→ schema / size validation
→ TransientInjector
→ SourceCapture
→ optional FlushCoordinator
→ ToolSurface + PermissionGate
→ content-free Diagnostics
```

每个阶段都要定义输入、输出、失败策略与可观察断言，并标记它属于自动还是显式。

| 阶段 | 必须定义的契约 |
| - | - |
| `PromptEvent` | 稳定的事件 timing 与轮次/会话标识 |
| `ScopeResolver` | 已授权的工作区/项目映射与有界 `scope_id` |
| `PreparedContextProvider` | Schema、响应大小和截止时间上限，以及 fail-open 结果 |
| `TransientInjector` | 只作用当前轮次的通道，并拒绝过期轮次 |
| `SourceCapture` | 精确采集范围、敏感信息策略、字符/字节上限与失败行为 |
| `FlushCoordinator` | 有界游标目标，且不能虚报 Memory complete |
| `ToolSurface` | 经过裁剪的显式操作；Candidate 批准仍走受控面 |
| `PermissionGate` | 宿主自己的允许/ask/拒绝与无界面行为 |
| `Diagnostics` | 不含内容或凭证的有界状态 |
| `Installer / Doctor` | 版本、归属、回滚、激活与诚实的证据等级 |

把事件模型表当作时序图来读。准备事件决定哪一段用户输入成为查询；注入事件决定召回内容能存活多久；边界事件决定何时刷新已采集的 Source。宿主如果没有对应时机，就应把该行为标为不支持，而不是用过期状态模拟。

## 五种不同的事件模型

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Codex / Claude Code
UserPromptSubmit → prepare + prompt capture → transient context
explicit work → MCP + Skill

DSH
agent/pre-step → prepare + user-originated batch capture
→ await downstream decision → plugin message
explicit work → curated HTTP tools

OpenCode
chat.message → prepare + capture → cache by (sessionID,messageID)
experimental.chat.messages.transform → exact latest-turn match → inject
explicit mutation → context.ask

Pi
before_agent_start → prepare + prompt capture → immediate flush or pending position
→ augment systemPrompt
boundary events → retry pending flush within a bounded budget
explicit mutation → interactive confirmation; deny without UI
```

| 宿主 | 准备事件 | 注入通道 | Identity 与 stale-state 规则 |
| - | - | - | - |
| Codex | short-process `UserPromptSubmit` | Hook 标准输出 additional 上下文 | 每次处理一个 submitted 提示词；进程 lifetime 有界 |
| Claude Code | short-process `UserPromptSubmit` | JSON `hookSpecificOutput.additionalContext` | v1 没有 `Stop` 采集路径 |
| DSH | `agent/pre-step` 中间件 | 下游 `enter` 后才追加插件消息 | `next()` 只调用一次；non-enter 决定不注入 |
| OpenCode | `chat.message` 准备；`experimental.chat.messages.transform` 注入 | `(sessionID,messageID)` 精确轮次缓存 | 匹配最新版本用户轮次；会话删除时清状态 |
| Pi | `before_agent_start` | 返回的 `systemPrompt` 增强内容 | 边界事件按 Scope 重试最大待处理 Source 位置 |

不能把一种宿主的停止事件、对话记录、消息修改操作或权限 UI 假设复制到另一种。

## Scope 与注入

Scope 选择数据分区。它不是凭证，也不是授权信息决定。需要隔离时，应从已认证的租户/项目映射派生 Scope。

解析器的优先顺序链路要写清楚。Git/工作区标识的规范化不能带凭证，公开值必须有界，诊断信息不能泄漏 原始 Scope。还要加入跨 Scope 测试，确认相同提示词不会共享临时状态。

PreparedContext 是不可信的历史证据。先验证精确的 v1 模式与 UTF-8 `content_bytes`，再通过当前宿主的临时频道注入。当前系统/用户指令始终优先，召回的 文本 也不能授予工具权限。

OpenCode 的 过期轮次 处理最直观，因为准备与 注入 发生在不同事件。缓存键必须精确匹配最新版本用户轮次。ID 准入规则可以阻止 注入错误轮次，但 并发 乱序准备仍可能让较新的注入丢失；该竞态为 **Not validated**。每种宿主都要保证一个提示词的上下文不会进入后续提示词。

## 自动安全契约

自动召回、采集与可选刷新属于辅助路径。预期内的 Server 调用、校验、大小与截止时间失败通常采用 fail-open：省略本次 PowerContext 上下文，并保留宿主原任务或下游结果。

| 结果 | 必须执行的行为 |
| - | - |
| Server 不可用或超时 | 不注入并继续；实际耗时工作保持有界 |
| 401/403 | 返回有界认证/配置状态；不能称为空结果 Memory |
| 成功但空结果 | 不添加已注入内容块，正常继续 |
| 未知 PreparedContext 模式 | 拒绝该内容块并继续 |
| Oversized 响应 | 在配置边界停止并继续 |
| 重定向 | 实现承诺拒绝时才声明拒绝；绝不能转发授权信息 |
| Valid 召回后采集失败 | 路径分别保护规则时保留 valid 临时上下文 |
| Eligible 采集前召回失败 | 路径分别保护规则时采集仍可继续 |
| 过期轮次/会话标识 | 丢弃已准备内容块 |
| 刷新超时或游标落后 | 停止重试，不能声称 Memory 已存在 |

Claude Code、DSH、OpenCode 与 Pi 会分别保护规则召回和采集。Codex 对预期失败也这样处理，但意外召回异常可能跳过本次采集。这个较弱的边界必须保留在文档里。

五种实现都会解析精确的 `powercontext.prepared-context.v1` 结构、验证 UTF-8 字节数、把通用响应体限制在 1 MiB，并在传输层代码拒绝重定向。不过测试深度不同。Codex 有慢响应体截止时间回归测试，OpenCode 的直接响应大小测试最完整。并非每种宿主都有等价的响应体超限或完整共享预算测试，因此统一行为是 **Not validated**。

DSH 是传输层例外：当前配置没有执行另外四种集成使用的安全基础 URL 与 Bearer 请求头校验。不能从共同契约推导出 DSH 也有相同的 HTTPS 或本机回环地址保证。

诊断信息必须排除提示词、原始 Scope、PreparedContext、Source 内容、响应体与授权信息令牌。

## 采集不等于 Memory

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
prompt capture
→ Source position
→ optional flush / scheduler
→ extraction candidate
→ Memory commit or no-op
```

文档必须说明适配器捕获一个用户提示词、选定的源自用户的内容块、完整 visible 轮次，还是完全不采集。敏感信息 过滤 与字符/字节上限也要写明。

采集创建 Source 证据。刷新推进处理到某个 Source 位置。抽取可能产生 Candidate，也可能无变更。只有后续提交才会创建或更新 Memory。

* Codex 与 Claude Code 捕获 submitted 提示词，使用 200,000-character 上限，没有自动 secret-pattern 过滤器。
* DSH 用全部批次 文本 召回，但只捕获源自用户的内容块；疑似敏感信息的 文本 不采集。
* OpenCode 捕获符合条件的提示词，并执行疑似敏感信息的与 UTF-8 字节过滤器。
* Pi 执行敏感信息与 UTF-8 字节过滤器，然后立即刷新或记录待处理位置。
* DSH、OpenCode 和 Pi 的敏感信息过滤器只影响 持久化，不阻止召回传输。
* 五种宿主都不会捕获最终助手响应，也不会自动记录 Task Outcome。

## 刷新 coordination

刷新器需要目标 Source 位置、有界调用计数或截止时间，以及 `current_cursor >= position` 之类的完成检查。在比较前清除待处理状态会丢工作；无限重试则会阻塞宿主。

Codex、Claude Code、DSH 与 OpenCode 支持可选立即刷新。Pi 还会按 Scope 保留最大待处理位置，并在 `agent_end`、`session_before_compact`、`session_before_switch` 与 `session_shutdown` 重试。Pi 的 压缩 重试与 immediate-failure 保留策略有已提交测试；其他生命周期边界与 关闭阶段 截止时间的验证深度不同。

DSH 与 OpenCode 没有 Pi 的待处理刷新器。它们的立即刷新路径也没有相同深度的完成/失败测试，不能写成 boundary-flush 支持。

## 显式修改操作与权限

显式操作不继承自动 fail-open。Memory 写入、Handoff 提交、Review 决定、Task Outcome 或 Skill 导出都必须返回成功或可见失败。

| 宿主 | 权限边界 |
| - | - |
| Codex | **Host-gated** MCP/工具策略；没有 plugin-owned interceptor；无界面拒绝 **Not validated** |
| Claude Code | **Host-gated** MCP 策略；没有 hook-owned interceptor；无界面拒绝 **Not validated** |
| DSH | Named 修改操作返回 pre-execute `ask` |
| OpenCode | Mutating 生成的操作调用 `context.ask` |
| Pi | Interactive 确认；无 UI 时返回 `confirmation_required`，且不写入 |

Candidate 批准/拒绝/修订不应成为 silent 模型工具。DSH 与 OpenCode 会刻意把批准排除在模型范围外。MCP 工具 visibility 不是授权信息，允许尝试操作也不证明操作成功。

## 内置 Skill 与托管导出

五种集成都会随包提供或注册内置宿主 guidance。它可以告诉宿主何时使用 MCP/原生工具，但不能证明托管 Skill 导出。

托管导出会生成带来源信息和漂移检查的 versioned 投影。Codex 与 Claude Code 为 **Supported**；DSH、OpenCode 和 Pi 为 **Unsupported**。导出后的托管 Skill 在真实 Codex 或 Claude Code 会话中的加载/执行仍是 **Not validated**。

## 安装配置与诊断契约

一级支持的安装程序 应做到：

* 准入规则已知宿主版本，并如实标记兼容证据；
* 幂等安装，同时保留外部配置；
* 记录归属，拒绝同名外部文件；
* 回滚，或报告清楚的 partial-failure 状态；
* 区分已安装、activated、Server-ready 与真实宿主端到端验证；
* 提供有界 `doctor`，并另设真实宿主激活探测。

诊断深度也不同。Codex 与 Claude Code 检查已启用插件状态；DSH 从 导出的配置读取精确插件 ID；Pi 检查软件包清单/路径；OpenCode 还会启动短生命周期的 `opencode serve` 并验证激活 随机标识。这些检查都不能证明实时召回/采集/权限链路。

## 负向实验

声称适配器完成前，执行这些检查：

1. Server 停止：原宿主任务继续。
2. 错误 认证：401/403 与空结果 Memory 保持可区分。
3. 未知模式：不注入。
4. Oversize 与截止时间：有界退出。
5. 重定向：授权信息不被转发。
6. 召回/采集 split：两个方向都测试，包括意外 Codex 召回失败。
7. 过期轮次：mismatched、已删除 或乱序标识不能注入错误上下文。
8. No UI 或权限 denied：不执行持久修改操作。
9. 刷新 lag：有界重试，不虚报完成。
10. 诊断信息：不含内容、Scope 或凭证。

真实宿主端到端验证是独立验收层级。必须启动真实宿主、发送提示词，并观察事件、注入、采集与权限行为。仅 HTTP 服务链路或 package-load 冒烟测试很有价值，但两者是不同证据。

## 复用当前实现

仓库已有可复用部分，但它们不是一个 SDK：

* 传输层策略与本机回环地址/重定向 测试向量；
* Codex 与 Claude Code PreparedContext parser；
* 各宿主 Scope 规范化测试；
* Pi 待处理 Source 刷新器；
* DSH 生成的操作 table；
* Codex 与 Claude Code Skill 投影；
* `cli/hosts.py` 内的安装配置与诊断目录。

扩展时复用契约、策略、辅助程序与测试向量。不要为了让文档看起来整齐，就虚构一个统一 `HostAdapter` class。

## 当前不支持或未验证

| 项目 | 状态 |
| - | - |
| 统一 `HostAdapter` SDK | 作为当前仓库抽象为 **Unsupported** |
| 自动 final-response/对话记录采集 | **Unsupported** |
| 自动 Task Outcome recording | **Unsupported** |
| DSH、OpenCode 与 Pi 的托管 Skill 导出 | **Unsupported** |
| Codex、Claude Code 与 DSH 真实宿主端到端验证 | **Not validated** |
| Pi 完整召回宿主链路 | **Not validated** |
| Codex 与 Claude Code 无界面 durable-mutation 拒绝 | **Not validated** |
| OpenCode 乱序准备竞态行为 | **Not validated** |
| 统一的 DSH secure base-URL/bearer 校验 | 当前 DSH 配置边界为 **Unsupported** |
| 每种宿主都有相同深度的模式/大小/截止时间/刷新 负向 测试 | **Not validated** |

## 完成检查

只有以下结果都能直接观察时，才算完成：

* 事件、标识、注入频道与过期状态规则符合所选宿主。
* Scope 来自稳定的授权标识，并有跨 Scope 负向测试。
* PreparedContext 保持有界、临时且不可信。
* 召回、采集、刷新、Candidate 抽取与 Memory 提交仍是独立观察。
* 自动 fail-open 声明与实际异常边界一致。
* 显式修改操作失败与权限拒绝保持可见。
* 重定向、模式、大小、截止时间、过期轮次、无界面与 flush-lag 测试覆盖所有承诺行为。
* 诊断信息不含提示词、Scope、上下文、Source 内容、响应体或令牌。
* 安装配置保留外部文件，并区分已安装、启用状态、Server-ready 与端到端验证。
* `doctor` 没有被写成真实宿主端到端验证。
* 内置 Skill 没有被写成托管 Skill 导出。
* Unsupported 与 **Not validated** 保持分开。

> [!TIP]
>
> 单元级契约测试、服务链路、安装配置/诊断、真实宿主端到端验证与 负向/安全性五层都有 observable 证据后，才能把第六种宿主加入一级支持的目录。

继续阅读 [Codex](https://powercontext.mintlify.site/zh/coding-agents/codex.md)、[Claude Code](https://powercontext.mintlify.site/zh/coding-agents/claude-code.md)、[DSH](https://powercontext.mintlify.site/zh/coding-agents/dsh.md)、[OpenCode](https://powercontext.mintlify.site/zh/coding-agents/opencode.md) 或 [Pi](https://powercontext.mintlify.site/zh/coding-agents/pi.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.