> ## 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.

# 编程 Agent 总览

> 比较五种编程 Agent 宿主的成熟度、安装配置、事件、注入、采集、刷新、权限和验证边界。

> [!WARNING]
>
> 各宿主的验证深度不同。OpenCode 的真实宿主进程准备/采集端到端验证冒烟测试在该边界为 **Supported**，完整宿主生命周期仍为 **Not validated**。Codex、Claude Code 和 DSH 的真实宿主端到端验证均为 **Not validated**。Pi 只有 package-load 覆盖，完整召回宿主链路仍是 **Not validated**。

五种宿主都连接一份单独运行的 PowerContext Server。它们共用领域契约，但不共用一套 Hook API，仓库里也没有统一的 `HostAdapter` SDK。

## 成熟度与安装状态

| 宿主 | 自动路径 | 显式路径 | 安装/版本状态 | Real-host 验证 |
| - | - | - | - | - |
| Codex | `UserPromptSubmit` | MCP + Skill | 未声明正式最低宿主版本 | **Not validated** |
| Claude Code | `UserPromptSubmit` | MCP + Skill | v1；Claude Code 2.1.133 只是兼容性证据，不是最低版本 | **Not validated** |
| DSH | `agent/pre-step` | 精选 HTTP 工具 | 需要已构建的 `lib/index.js`；正式最低版本 **Not validated** | **Not validated** |
| OpenCode | two-stage 精确轮次缓存 + 转换 | 精选 HTTP 工具 | **Version-gated**：`>=1.18.21,<2` | 准备/采集冒烟测试 **Supported**；full 生命周期 **Not validated** |
| Pi | `before_agent_start` + 待处理刷新器 | 原生工具 + `/pc` | Node.js `>=22.19`；Pi 0.82.x 只是兼容性证据，不是最低版本 | 软件包加载 仅；完整链路 **Not validated** |

> [!NOTE]
>
> **Not validated** 不等于 **Unsupported**。Not validated 表示这条路径可能可用，但缺少这里声明的验证证据；Unsupported 表示集成没有提供该操作。

安装配置只安装宿主文件或软件包，不会启动 Server。`doctor` 检查有限的安装与激活边界，不证明真实提示词、召回、采集、权限 UI、跨会话行为或真实宿主端到端验证。

选择宿主时，先看你能否控制提示词前的事件和临时注入通道，再看采集与权限。不要因为某一行显示“有”就认定接入完成；真正的完成标志是新会话能在相同 Scope 中召回，而 Server 停止后普通任务仍能继续、显式写入明确失败。

## 最小用法

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

powercontext server run
powercontext doctor <host>
```

打开一轮新的宿主会话，发送一个普通编程提示词。只有在你确实要搜索或修改 Memory、创建 Handoff、执行 Review 或导出 Skill 时，才使用显式工具面。

共同流程最适合用来比较失败行为。准备失败只能移除本次召回贡献；采集失败不能抹掉已经校验通过的临时上下文。权限只属于显式操作，不能从自动 Hook 成功推导出来。

## 共同执行流

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
host event
→ resolve Scope
→ prepare bounded untrusted context
→ optionally capture prompt Source / immediate flush
→ inject through host-specific channel
→ run model
→ Pi only: retry pending flush at lifecycle boundaries
→ explicit tools under host permission
```

这套共同形状里实际包含五种事件模型：

```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
```

## 能力矩阵

先按生命周期选框架，再用矩阵确认该适配器是否具备你需要的精确行为。

| 能力 | Codex | Claude Code | DSH | OpenCode | Pi |
| - | - | - | - | - | - |
| 自动事件 | `UserPromptSubmit` | `UserPromptSubmit` | `agent/pre-step` | `chat.message` + 消息转换 | `before_agent_start` |
| 注入 | Hook 标准输出 additional 上下文 | JSON `additionalContext` | 下游 `enter` 后插件消息 | `(sessionID,messageID)` 精确轮次缓存 | 返回的 `systemPrompt` 增强内容 |
| 提示词采集 | 用户提示词；字符上限 | 用户提示词；字符上限 | 源自用户的批次；疑似敏感信息的过滤器 | 符合条件的提示词；疑似敏感信息的/字节 filters | 符合条件的提示词；敏感信息/字节 filters |
| Final 响应采集 | 无 | 无 | 无 | 无 | 无 |
| 显式接口 | MCP | MCP | 精选 HTTP 工具 | 精选 HTTP 工具 | 原生工具 + `/pc` |
| Handoff | MCP + Skill | MCP + Skill | 精选 HTTP 工具 | 精选 HTTP 工具 | 原生工具 |
| 权限 | **Host-gated** | **Host-gated** | pre-execute `ask` | `context.ask` | 交互式 确认；无 UI 拒绝 |
| 托管 Skill 导出 | **Supported** | **Supported** | **Unsupported** | **Unsupported** | **Unsupported** |
| 真实宿主端到端验证 | **Not validated** | **Not validated** | **Not validated** | 准备/采集冒烟测试 **Supported**；full 生命周期 **Not validated** | 软件包加载 仅；完整链路 **Not validated** |

五种集成都带有宿主 guidance，但内置 `project-context` Skill 不是托管 Skill 导出。托管导出是另一条 PowerContext 操作，需要投影与漂移契约；当前只支持 Codex 和 Claude Code。

## Scope、注入、采集与刷新

Scope 选择数据分区，但不是认证。应从稳定且已授权的工作区/项目标识派生 Scope，并通过负向测试确认两个 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
```

Codex 与 Claude Code 各捕获一个用户提示词。DSH 可以用批次内全部 文本 帮助召回，但采集只保留源自用户的 文本。DSH、OpenCode 和 Pi 会跳过疑似敏感信息的采集；该过滤器不会阻止召回传输。Pi 与 OpenCode 使用 UTF-8 字节上限，Codex 与 Claude Code 使用 字符数 采集上限。五种宿主都不会自动捕获最终助手响应。

刷新只是推进已采集 Source 位置的处理进度。超时或游标落后时，不能证明 Memory 已存在。Codex、Claude Code、DSH 与 OpenCode 支持可选立即刷新。Pi 还会记录待处理位置，并在生命周期边界重试。只有 Pi 使用这套 deferred boundary-flush 模型。

## 自动与显式路径

自动召回、采集和可选刷新属于辅助路径。预期内的 Server、校验、大小、截止时间或采集失败通常 fail-open，让宿主任务继续。Claude Code、DSH、OpenCode 与 Pi 会分别保护规则召回和采集。Codex 对预期失败也保持独立，但意外召回异常可能让本次采集被跳过；文档不能承诺比代码更强的隔离。

显式持久操作不同。Memory 写入、Handoff 提交、Review 决定和 Skill 导出必须暴露失败，并经过宿主权限。Pi 的无界面拒绝已验证。Codex 与 Claude Code 在无 UI 时拒绝持久修改操作的行为是 **Not validated**，不要套用 Pi 的契约。

## 负向实验

按所选宿主执行适用的检查：

* 停止 Server，确认普通提示词仍会到达模型。
* 返回 401/403，确认它与成功但空结果的结果可以区分。
* 返回 未知 PreparedContext 模式，确认不会注入。
* 超出响应大小或截止时间预算，确认轮次仍有界。
* 重定向 已认证 请求；只有宿主实现明确 enforce 时，才能声称它会拒绝。
* 让召回失败而采集成功，再反过来测试；Codex 还要覆盖意外召回异常。
* 复用、乱序完成或删除轮次/会话键，确认过期上下文被拒绝，或竞态不会注入错误轮次。
* 拒绝显式修改操作；宿主定义 无界面/无界面行为时，也要覆盖该场景。
* 让刷新游标持续落后于 Source 位置，确认有界重试停止且不会声称 Memory 已存在。
* 检查诊断信息，确认不含提示词、Scope、PreparedContext、响应体或令牌。

## 当前不支持或未验证

| 项目 | 状态 |
| - | - |
| 自动路径的最终 assistant-response 或对话记录采集 | **Unsupported** |
| 自动 Task Outcome recording | **Unsupported** |
| DSH、OpenCode 或 Pi 的托管 Skill 导出 | **Unsupported** |
| Codex 真实 宿主进程端到端验证与正式最低宿主版本 | **Not validated** |
| Claude Code 真实 宿主进程端到端验证、正式最低版本和无界面修改操作拒绝 | **Not validated** |
| DSH 真实宿主端到端验证与正式最低宿主版本 | **Not validated** |
| OpenCode 乱序准备竞态行为 | **Not validated**；精确轮次 匹配 可阻止 注入错误轮次，但可能丢失较新的注入 |
| Pi 完整召回宿主链路、正式最低 Pi 版本和全部 lifecycle-flush 边界 | **Not validated** |
| 托管已导出 Skill 在 Codex 或 Claude Code 中的加载/执行 | **Not validated** |
| 统一的 `HostAdapter` SDK | 作为当前仓库抽象为 **Unsupported** |

## 选择宿主

选择刚好能完成任务的最小宿主能力面。集成越广，需要验证的行为越多，可能跨越 Server 边界的内容也越多。

| 需求 | 下一页 |
| - | - |
| short `UserPromptSubmit`、MCP 与项目 Skill | [Codex](https://powercontext.mintlify.site/zh/coding-agents/codex.md) 或 [Claude Code](https://powercontext.mintlify.site/zh/coding-agents/claude-code.md) |
| 步骤前 中间件与精选 HTTP 工具 | [DSH](https://powercontext.mintlify.site/zh/coding-agents/dsh.md) |
| two-stage 精确轮次缓存与 `context.ask` | [OpenCode](https://powercontext.mintlify.site/zh/coding-agents/opencode.md) |
| `before_agent_start`、待处理刷新器与无界面拒绝 | [Pi](https://powercontext.mintlify.site/zh/coding-agents/pi.md) |

## 完成检查

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

* Server 单独运行。
* 安装配置和 `doctor` 没有被写成端到端验证证据。
* 宿主版本或兼容性声明与成熟度表一致。
* 一个普通提示词已证明预期事件与临时注入路径。
* Scope 来自稳定的授权标识，并通过跨 Scope 负向测试。
* 采集内容、敏感信息策略和字符/字节上限已记录并实际观察。
* 刷新与 Memory 提交已按两个阶段验证。
* 自动失败只在当前代码与测试证明的范围内 fail-open。
* 权限与无界面行为只按所选宿主的契约测试。
* 内置 Skill 没有被写成托管 Skill 导出。
* 部署说明没有混淆 Unsupported 与 **Not validated**。

> [!TIP]
>
> 如果真实宿主还没有启动并处理过提示词，就只能报告已完成的契约、服务链或诊断 tier，不能称为真实宿主端到端验证。

选择具体宿主安装配置前，继续阅读 [Hooks 与插件](https://powercontext.mintlify.site/zh/coding-agents/hooks-and-plugins.md)。


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