Hooks 与插件

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

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

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

​

成熟度与安装状态

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

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

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

powercontext setup <host> \
  --source oceanbase/powercontext \
  --ref master

powercontext server run
powercontext doctor <host>

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

​

最小适配器契约

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。宿主如果没有对应时机，就应把该行为标为不支持，而不是用过期状态模拟。

​

五种不同的事件模型

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

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 保持分开。

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

继续阅读 Codex、Claude Code、DSH、OpenCode 或 Pi。