> ## 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 扩展

> 先发现宿主能力，再定义可验证的适配器契约，并在发布前取得真实宿主证据。

> [!WARNING]
>
> 当前没有统一的 `HostAdapter` SDK。本页的契约名称是设计 checklist，不是已有 class 或稳定公开 API。

## 从能力发现开始

不要先复制最相近的集成。先记录新宿主实际能提供什么：

* 稳定的提示词事件及其 顺序；
* 轮次、消息、会话、工作区和项目标识；
* 模型分派前的临时注入频道；
* 工具与命令 注册项；
* 权限请求、确认 UI 和 无界面 行为；
* 软件包、插件与内置 Skill 安装；
* end、压缩、切换、关闭与中断 events；
* CLI/版本探测和激活探测。

同时查询 `GET /v1/capabilities`。它会返回 `memory_extraction`、`experience_generation`、`managed_skill_generation`、`external_skill_registry`、Handoff 生成、搜索 modes 和上下文版本等 Server 能力。宿主能力发现与 Server 能力发现回答的问题不同，两者都需要。

如果宿主没有稳定提示词事件、pre-dispatch 注入 point 或权限范围，就直接写明。除非你实现了保证等价的另一套契约，否则该能力是 **Unsupported**。如果宿主看起来提供了入口，但没有真实宿主测试证明完整路径，则标为 **Not validated**。

## 编写适配器契约

用以下 vocabulary 把关键决策摆到台面上：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
PromptEvent
ScopeResolver
PreparedContextProvider
TransientInjector
SourceCapture
FlushCoordinator
ToolSurface
PermissionGate
Diagnostics
Installer / Doctor
```

这些是建议的角色。每项都要定义输入、输出、失败策略、安全性边界和可观察断言。

| Role | 需要明确的契约 |
| - | - |
| `PromptEvent` | 精确宿主事件、提示词规范化、生命周期 顺序 和稳定轮次标识。 |
| `ScopeResolver` | Authorized 覆盖值、Git 标识、项目后备路径、规范化与缓存 lifetime。 |
| `PreparedContextProvider` | `/v1/context/prepare`、接受的模式版本、响应大小预算与 fail-open 结果。 |
| `TransientInjector` | Context 从哪里进入、如何标记为不可信，以及注入不会持久化的证据。 |
| `SourceCapture` | 采集内容、确定性 Source 标识、元数据、敏感信息策略、UTF-8 字节上限与返回的 `position`。 |
| `FlushCoordinator` | 每个 Scope 的待处理状态、边界 events、重试/截止时间预算与 `current_cursor >= position` 清除规则。 |
| `ToolSurface` | 精确操作允许列表、生成的模式 source、工具结果结构和 unsupported 操作。 |
| `PermissionGate` | 读取与修改操作、批准 UX、拒绝、cancellation，以及无 UI 时的行为。 |
| `Diagnostics` | 激活、版本、软件包归属、Server 状态与不含内容的错误报告。 |
| `Installer / Doctor` | Idempotency、归属、回滚、激活探测与 partial-failure 状态。 |

自动召回、采集和可选刷新可以 fail-open。显式持久写入、Review、Handoff 提交与 Skill 导出必须报告失败。不能给两组操作套用同一策略。

## 最小用法

先只实现一条提示词路径、一条边界路径和一个显式修改操作。第一版不要带入任何 unsupported 能力。

## 执行流程

宿主 glue 要薄。它只负责解析标识、调用已验证辅助程序，并把结果转换成宿主的原生事件结构。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
onPrompt(event)
→ normalize PromptEvent
→ resolve Scope
→ prepare context and capture Source independently
→ retain returned position for bounded flush
→ inject PreparedContext through the host's transient channel

onBoundary(event)
→ flush pending position for the same Scope

onMutation(call)
→ validate Scope and payload
→ request host permission
→ execute only after approval
```

如果宿主无法实现其中某个箭头，就删掉对应声明。不要用一个泛化的适配器名称掩盖缺口。

## 复用现有实现

只复用契约与宿主一致的代码：

* `powercontext.http` 下的生成的 HTTP 客户端与传输层模型；
* 规范形式 `PreparedContext` 和能力模型；
* Python 采集 rendering 与脱敏辅助程序；
* shared 本机回环地址传输层 测试向量；
* Codex 与 Claude Code 的 PreparedContext 校验 patterns；
* 宿主专用 Scope 规范化测试；
* Pi 的 pending-position 刷新器 pattern；
* DSH 等集成的生成的操作 tables；
* Codex 与 Claude Code 托管 Skill 投影；
* 一级支持的安装配置/诊断目录与通用 `诊断信息` 值模型。

目前仍有不少辅助程序是重复实现，而不是共享实现。Scope 解析结果、PreparedContext 校验、截止时间/重定向策略、敏感信息 detection、Source ID construction 和有界刷新 logic 仍分散在各宿主软件包中。文件名相似，不代表它们组成了 supported SDK。

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

新宿主必须一起定义这四个边界。

Scope 应来自稳定、授权后的项目数据。Git 远程要去除凭证。不要信任模型提供的 `scope_id`；除非宿主契约证明会话标识与仓库标识相同，也不要混用两者。

注入应在模型分派前使用宿主的原生临时频道，并把 `PreparedContext` 标为不可信的历史证据。只在系统 guide 里告诉模型搜索 Memory，不能证明召回已注入。

采集要明确记录轮次的哪一侧。传输层 前过滤 疑似敏感信息 内容，并按 UTF-8 字节执行上限。召回与采集要彼此独立，避免一个失败清掉另一个的有效结果。

刷新要按 Scope 保存 Source `position`，且仅在 `current_cursor >= position` 时清除。每个重试循环都要有调用上限和实际耗时预算。宿主没有可靠边界事件时，自动刷新为 **Unsupported**；事件存在但未在真实宿主中运行时，为 **Not validated**。

## 权限与显式写入

列出所有 mutating 操作。明确宿主在 交互式 和 无界面 模式下能否 ask、拒绝、取消 或 pause，再测试实际行为。

没有权限 API 的宿主不能继承 Pi 的 `confirmation_required` 契约，也不能继承 OpenCode 的 `context.ask()` 行为。可选方案只有三种：在 adapter-controlled code 中 fail closed、只提供只读操作，或把持久修改操作标为 **Unsupported**。“模型应该先问”不是权限边界。

诊断信息不得输出提示词内容、已准备上下文、可识别私有仓库的 Scope details、授权信息值或含敏感信息的载荷。

## 安装配置与诊断

Installation 与激活分开检查后，才能把宿主加入安装配置。

安装配置应保持 幂等，不覆盖外部 同名 文件，对自己管理的文件记录归属；远程 刷新 使用 暂存区，并在失败时恢复之前的状态。Multi-host 安装配置要隔离各宿主失败，并把每个选中项报告为已安装、失败或已跳过。

诊断有三项工作：

1. 找到宿主可执行文件，并报告版本证据；
2. 确认已安装软件包或配置属于 PowerContext；
3. 如果宿主提供安全且不调用模型的探测，通过宿主验证激活。

不要把 `powercontext doctor` 当作集成扫描。通用命令检查软件包与 Server；宿主检查属于 `powercontext doctor <host>` 和只读的 `powercontext doctor integrations` matrix。

## 验收层级

用以下 tier 描述证据。它们是本页的分类，不是当前测试框架中的名称。

1. **契约/单位：** 模式、Scope、大小、敏感信息、权限与 failure-policy 测试。
2. **软件包/加载：** 构建、安装、导入、清单、命令或插件 注册项。
3. **Service 链路：** 真实 PowerContext Server，加上直接 Hook/module 执行与 Source/Memory 证据链。
4. **真实宿主端到端验证：** 启动实际宿主，发送提示词，观察生命周期、注入、采集、刷新与权限行为。
5. **Live 模型提供方 journey：** 用实际宿主和模型提供方/模型运行，并保留验收证据。

软件包/加载和服务链测试很有用，但不能证明宿主 API 兼容或事件 顺序。标为 Supported 的每项能力，都需要真实宿主端到端验证。模型提供方行为影响声明时，还需要第五层证据。

## 负向测试矩阵

至少测试以下情况：

| Area | Experiment | Required observation |
| - | - | - |
| Availability | Server 停止或请求超时 | 自动路径有界且 fail-open。 |
| 认证 | 错误 令牌 | 不泄露凭证、提示词、上下文或私有 Scope。 |
| 传输层 | 重定向或明文 非本机回环地址 端点 | 不跟随重定向；拒绝不安全传输层。 |
| Schema | 未知或 incomplete PreparedContext | 不注入任何内容。 |
| 大小 | Oversized 响应或提示词 | 在配置字节预算处停止。 |
| Identity | 缺失、过期或 caller-supplied Scope/轮次 ID | 不发生 cross-project 或 过期轮次 注入。 |
| 采集 | Disabled、疑似敏感信息 或失败请求 | 召回保持独立；不发送 forbidden Source。 |
| 刷新 | 游标 lag、临时失败或超时 | 待处理位置保留；重试在预算内结束。 |
| 权限 | Deny、取消 或 no UI | 除非 declared 宿主契约允许，否则修改操作不运行。 |
| 能力 | `memory_extraction=false` | 采集仍只是 Source 证据；不声称 unsupported 刷新/抽取。 |
| 生命周期 | Compact、切换、关闭、中断 | 只使用匹配的 Scope 与轮次状态。 |
| 安装配置 | 外部文件、失败 刷新 或失败激活 | Existing 状态保留，并报告 部分完成 失败。 |

宿主有私有/群组会话等概念时，再加入对应的 宿主专用 隐私 情况。

## 托管 Skill 导出

托管 Skill 导出当前只支持 Codex 和 Claude Code。其他插件安装内置 `project-context` Skill，不会改变这个 matrix。

新增导出目标时，需要实现投影契约、目标 enum 与 OpenAPI 范围、归属 规则、校验、回滚和漂移测试。在这些工作完成前，该宿主的托管导出为 **Unsupported**。如果实现已存在，但未运行 真实 安装/刷新 测试，则标为 **Not validated**。

## Unsupported 与 Not validated

| 状态 | 使用条件 | Example |
| - | - | - |
| **Unsupported** | Code 明确拒绝、排除，或无法安全实现能力。 | 没有宿主权限 API，也没有 adapter-controlled 失败时关闭修改操作路径。 |
| **Not validated** | 路径可能工作，但现有证据没有到达已声明 宿主/模型提供方边界。 | Hook 通过单位和服务链测试，但没有测试启动真实宿主。 |

不要把这两个 label 合并成“limited 支持”。一个是 product 边界，另一个是证据 gap。

## 完成 checklist

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

* 宿主与 Server 能力发现分开记录。
* 每个拟定的契约角色都有输入、输出、失败策略与可观察断言。
* 宿主版本准入规则或兼容证据，以及激活探测已存在。
* Scope 来自稳定、授权后的标识，并去除凭证。
* PreparedContext 已校验、临时注入，并标为不可信。
* 采集明确内容、Source 标识、UTF-8 大小上限与敏感信息策略。
* 刷新按 Scope 保存位置，只在 `current_cursor >= position` 时清除。
* 显式写入已测试允许、拒绝、取消 与无界面行为。
* 诊断信息不输出内容或凭证。
* 安装配置保留外部配置，并报告回滚或 部分完成 失败。
* 除非完整投影目标已存在，否则托管 Skill 导出为 **Unsupported**。
* 真实宿主端到端验证覆盖每项 Supported 生命周期与权限声明。
* **Unsupported** 与 **Not validated** 在 docs、测试和发布 备注 中保持区分。

完成这些，才把宿主加入一级支持的目录。


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