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

# Pi

> 安装原生软件包，在 before_agent_start 注入上下文，并在生命周期边界刷新已采集的 Source。

> [!NOTE]
>
> **Version-gated：** 软件包运行时要求 Node.js `>=22.19`。Development 声明 Pi `^0.82.0`；lockfile 与 real-CLI package-load 端到端验证使用 Pi `0.82.1`。这是兼容证据，不是正式 host-version range。软件包加载在该测试边界内为 **Supported**；完整真实宿主召回链路为 **Not validated**。

## 成熟度与安装

Pi 使用 source 软件包 `powercontext-pi` 版本 `0.0.2`，其中包含 扩展 和内置 `project-context` Skill。当前安装配置路径从指定 PowerContext Git 版本引用或本地检出安装；按已发布 npm 软件包 名称 安装目前为 **Unsupported**。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext setup pi --source oceanbase/powercontext --ref master
powercontext server run
powercontext doctor
powercontext doctor pi
pi
```

安装配置校验软件包 名称、扩展 和内置 `SKILL.md`，执行 `pi install <package-directory>`，只在成功后删除 superseded user-scoped PowerContext registrations，然后运行诊断。

远程检出 materialization 使用 暂存区；暂存区 swap 失败时会恢复 previous 检出。之后若 `pi install` 失败，没有事务式检出回滚。Source 凭证与 克隆 输出不会打印。

`powercontext doctor pi` 检查 Pi 可执行文件、`pi list`，以及名为 `powercontext-pi` 的已安装清单。它不检查 Server 就绪状态、扩展 激活、内置 Skill 发现、软件包/宿主版本或模型轮次。通用 `powercontext doctor` 单独覆盖 Server。

## 最小用法

安装或修改环境后，启动新的 Pi 进程。自动路径与显式路径要分开：

1. 提交普通 编码提示词。`before_agent_start` 可以召回临时上下文，并把 去除首尾空白的 提示词采集为 Source。
2. 需要精确读取或受支持的持久操作时，使用 13 个原生 Memory/Handoff 工具。
3. 用 `/pc`、`/pc doctor` 和 `/pc search <query>` 做诊断信息与显式检查。`/pc doctor` 调用配置 Server，与 `powercontext doctor pi` 不是同一检查。

Invalid 本地 Pi 配置不会让宿主退出，但不会注册工具或 `/pc`，Hook 也全部无变更。内置 Skill 说明工具用法；真实 Pi Skill 发现为 **Not validated**，因为 package-load 端到端验证使用 `--no-skills`。

## 执行流程

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
before_agent_start
→ trim prompt; skip an empty prompt
→ resolve and cache Scope by cwd
→ prepare and strictly validate context
→ capture eligible prompt Source and receive position
→ optionally flush through position, or retain it as pending
→ append ready untrusted context to systemPrompt

agent_end
→ start pending flush without waiting

session_before_compact / session_before_switch / session_shutdown
→ await pending flush within a bounded closing budget
```

准备与采集共用一个轮次 HTTP 预算 signal，但各自处理失败。召回失败通常不影响采集；采集失败也不会清除有效召回的上下文。自动失败都 fail-open，不会停止 Pi 轮次。

`agent_end` 只启动刷新后返回。没有回调采集助手响应或记录 Task Outcome。Pi 的 `session_shutdown` 事件不是 Claude Code `Stop` Hook。

## Scope

Pi 会先派生 Scope，再执行 scoped Server 操作：

1. 使用非空 `POWERCONTEXT_PI_SCOPE_ID`；超过 256 字符时哈希。
2. 否则解析 Git top-level，并把 `remote.origin.url` 规范化成 `git:` Scope。
3. 最后回退到 `local:sha256(<absolute-project-root>)`。

Git 规范化删除凭证和末尾 `.git` noise，接受常见 HTTP、HTTPS、SSH、Git 与 SCP-style remotes。Resolved 承诺按 cwd 缓存；失败的 解析结果 会被移除。工具调用方不能用自带值替换派生出的 `scope_id`。

Pi 没有 Codex/Claude 风格的 Workstream 选择器或 Git 私有 Scope 绑定，这条路径为 **Unsupported**。

## 注入

PreparedContext 只有满足以下条件才会接受：字段正好是 `schema`、`status`、`content`、`content_bytes`；模式为 `powercontext.prepared-context.v1`；符合空结果/就绪 规则；UTF-8 字节数完全一致；内容不超过配置上限。

Extension 把就绪内容追加到 Pi 现有 `systemPrompt`，并标成 host-supplied、不可信历史证据。Empty 或无效内容不注入。这是临时 增强内容，不是对话记录 synchronization，也不会直接创建 Source、Memory 或 Artifact。

## 采集

自动采集默认开启。Source 标识对 Scope、规范化的会话标识、派生的 轮次 number 和 去除首尾空白的 提示词做哈希。元数据只有 `origin`、事件、`cwd`、`session_id` 与 `turn_id`。轮次 number 来自当前分支的 user-message 计数；分支本身不会存储。

采集在以下情况跳过：功能关闭；提示词的 UTF-8 大小超过 200,000 字节；命中私有键、凭证 assignment、Bearer 值或已知令牌结构。Dedicated multibyte 边界 情况 为 **Not validated**，因为当前超限测试使用 ASCII。

只有采集响应包含 integer `position >= 1` 时，才会记为待处理。Source 验收、processing 位置、刷新完成、Candidate 生成、Review 与已提交 Memory 是不同阶段。

## 刷新

待处理刷新器按 Scope 保留尚未处理的最大位置，较小位置不能降低它。只有 `current_cursor >= position` 时才清除条目。并发 刷新 calls 共用一个 in-flight 承诺；刷新期间新出现的更大位置也不会被较早的完成清除。

默认值是：立即刷新关闭、最多四次调用、轮次 HTTP 预算为 4,000 ms、生命周期 关闭阶段 预算上限为 1,000 ms。设置 `POWERCONTEXT_PI_FLUSH_ON_CAPTURE=true` 后，采集会重试立即临时错误；重试耗尽后把位置留给后续边界。

生命周期 边界遇到 Server/传输层 throw 时，会停止该 Scope 的当前循环，但保留待处理，等待未来事件。Cursor-behind 响应会重试到调用上限。刷新器继续处理其他 Scopes，也不会声称 Memory 已存在。

Compaction 与 immediate-failure-to-compaction 重试有直接测试。Multiple Scopes、in-flight coalescing、永久落后的游标，以及刷新期间出现更高位置，都没有直接 Pi 测试，因此为 **Not validated**。

## 工具、命令与权限

Pi 精确注册 13 个模型工具。读取/non-durable 工具是 `pc_search`、`pc_memory_list`、`pc_memory_get`、`pc_prepare_context`、`pc_handoff_prepare`、`pc_handoff_finalize`、`pc_handoff_continue`。需要确认的 mutations 是 `pc_remember`、`pc_memory_revise`、`pc_memory_retire`、`pc_capture_source`、`pc_handoff_activate`、`pc_handoff_commit`。

`/pc` 支持无参数诊断信息，以及 `doctor`、`search`、`remember`、`flush`、`stats`。它没有通用操作、Candidate Review、Handoff 或 Task Outcome 命令。

Gated 修改操作只有在 交互式 确认通过后才执行。无 UI 返回稳定 `confirmation_required`；用户拒绝返回 `cancelled`；UI 失败返回 `unavailable`。这些路径都不发送写入请求。`/pc remember` 与 `/pc flush` 遵守同一边界。显式操作会替换调用方 Scope、拒绝含敏感信息的载荷，并返回稳定、模型可见的的错误。

无界面契约与辅助程序行为有单位测试。真实宿主如何显示、拒绝或缺失 UI，仍没有宿主进程测试，因此为 **Not validated**。

## 传输层

默认 Server 是 `http://127.0.0.1:8000`。Plain HTTP 只允许 localhost 与本机回环地址 address；远程 Server 必须使用 HTTPS。带凭证、查询、片段或非 HTTP scheme 的基础 URL 会被拒绝。

`POWERCONTEXT_PI_AUTHORIZATION` 会作为完整授权信息值发送。重定向使用手动处理并被拒绝，因此凭证不会转发。响应上限为 1 MiB；成功响应体必须是有效 JSON。单次请求超时与 shared 轮次预算是不同限制。

## Unsupported 与 Not validated

| 状态 | 能力 | Practical 并发 |
| - | - | - |
| **Version-gated** | Node.js 运行时 `>=22.19` | 不要在更旧运行时上安装软件包。 |
| **Unsupported** | 按已发布 npm 名称安装；导出托管 Skill 或扫描 Pi 外部 Skill 目标；自动采集助手响应/对话记录；自动 Task Outcome；Workstream 选择器和 Git 私有绑定；MCP 传输层；启动或嵌入 Server | 使用源码安装配置和原生 HTTP 工具，并单独运行 Server。 |
| **Pi 原生范围内 Unsupported** | 显式 Task Outcome、工作契约（Work Contract）、确认、Experience/Skill 生成、Candidate Review、外部 Skill、通用 API 与 Handoff 报告 | 生成的操作描述符不会自动成为 Pi 工具或命令；请改用其他受支持的接口，或扩展宿主。 |
| **Not validated** | Formal Pi 宿主 range or 兼容 beyond locked 0.82.1 | `^0.82.0` 只是开发 意图，不是支持承诺。 |
| **Not validated** | Full real-Pi 准备/注入/模型链路; 内置 Skill 发现; 真实宿主确认行为 | 软件包安装/加载与 `/pc` 注册项 不能证明这些路径。 |
| **Not validated** | 回调执行 for `agent_end`, 切换, 与 关闭; multibyte Source 边界; pending-flusher concurrency edges | 在直接测试出现前，只按实现证据描述。 |

Real 软件包端到端验证用 locked Pi 0.82.1 安装目录，在 no 会话/no Skills 的 offline RPC 中启动，并确认 `/pc` 已注册。它不创建会话，不调用模型或 Server，也不覆盖召回或内置 Skill 加载。

## 负向实验

把 Pi 部署视为完成前，运行这些实验：

* 破坏本地配置，确认 Pi 继续运行，但没有 PowerContext 工具、命令或 Hook effect。
* 停止 Server，确认轮次在没有已注入上下文时继续。
* 让准备失败而采集成功；再反向测试，并保留有效召回的上下文。
* 提交 blank、疑似敏感信息、disabled-capture 或 over-limit 提示词，确认对应无变更/no-capture 路径。
* 让立即刷新失败，再触发 压缩，确认待处理位置会重试。
* 刷新期间记录较小和较大位置；只有 `current_cursor >= highest-position` 才能清除条目。
* 让游标一直落后于位置，确认有界工作结束后不会声称 Memory 已存在。
* 无 UI 时执行修改操作，确认 `confirmation_required` 且没有 HTTP 写入；在 UI 中拒绝时应返回 `cancelled`。
* 向工具传入不同 `scope_id`，确认派生 Scope 会覆盖它。
* 返回重定向、超限或 non-JSON 响应，确认客户端拒绝。
* 对 非本机回环地址 宿主使用明文，确认配置拒绝；远程使用 HTTPS。
* 检查工具/命令，确认 Task Outcome、Candidate Review、Experience/Skill 生成和通用 API 范围都不存在。

## 配置默认值

| 键 | 默认值 | 含义 |
| - | - | - |
| `POWERCONTEXT_PI_BASE_URL` | `http://127.0.0.1:8000` | 正在运行的 Server |
| `POWERCONTEXT_PI_SCOPE_ID` | 未设置 | 显式 Scope；未设置则按 Git / 路径推导 |
| `POWERCONTEXT_PI_AUTHORIZATION` | 未设置 | 完整授权信息请求头 |
| `POWERCONTEXT_PI_CAPTURE_PROMPTS` | `true` | 采集当前用户提示词 |
| `POWERCONTEXT_PI_MAX_BYTES` | `8000` | 召回预算，限制在 `512–32768` |
| `POWERCONTEXT_PI_REQUEST_TIMEOUT_MS` | `1000` | 单次 HTTP 超时 |
| `POWERCONTEXT_PI_HTTP_BUDGET_MS` | `4000` | 一轮准备/采集总预算 |
| `POWERCONTEXT_PI_FLUSH_ON_CAPTURE` | `false` | 测试用：采集后等待刷新 |

不要把凭证写进 `POWERCONTEXT_PI_BASE_URL`。非本机回环地址必须用 HTTPS。当前工作不能落成 Source 时：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_PI_CAPTURE_PROMPTS=false
pi
```

## 在这个宿主上做完统一题

> 修改 OpenAPI 契约后，下一步应该做什么？

1. 在固定 Scope 里用 `pc_remember` 或 `/pc remember` 保存答案。有 UI 时先过 `ui.confirm`。
2. 开一个新会话，再问同一句。
3. 召回必须带 Citation，并且只出现在 `systemPrompt` 末尾、以 `PowerContext host-supplied context` 开头的那段。
4. 停掉 Server 后再问普通编码问题。召回 / 采集 / 刷新不得阻断 Agent。
5. Server 仍停着时再跑 `pc_remember`。有 UI 时失败必须可见；无 UI 时应收 `confirmation_required`，不得静默写入。

## 完成检查

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

* PowerContext 与 Pi 软件包来自同一经过审阅的 Git 版本引用。
* Node.js 为 `>=22.19`。
* Pi 0.82.1 只记录为兼容证据，不写成正式最低版本或完整 0.82.x 承诺。
* `powercontext doctor` 与 `powercontext doctor pi` 分别通过各自边界。
* `pi list` 指向清单 名称 为 `powercontext-pi` 的软件包，新 Pi 进程能看到 `/pc`。
* `/pc doctor` 能访问预期 Server。
* Scope 来自显式覆盖值、sanitized Git 标识或 本地根目录 哈希。
* 调用方 Scope 不能替换它。
* Valid PreparedContext 经过严格校验，并以不可信证据追加到现有 `systemPrompt`。
* 采集存储 去除首尾空白的 提示词、`cwd`、`session_id`、派生的 `turn_id`，不包含项目或分支字段。
* 敏感信息与超过 200,000-byte 的提示词不采集。
* 待处理工作仅在 `current_cursor >= position` 时清除，并遵守调用/关闭阶段 预算。
* 每个 受权限控制的 工具与 `/pc` 修改操作都会确认，或返回稳定的不写入错误。
* 远程传输层使用 HTTPS、拒绝重定向，并执行 JSON 与响应大小 bounds。
* Source、位置、刷新、Candidate、Review 与 Memory 保持为不同阶段。
* 软件包加载 证据与 内置 Skill 发现、完整真实宿主轮次保持区分。
* Pi 原生 Task Outcome 与其他 缺失能力 保持 **Unsupported**。
* 内置 Skill 存在 不代表托管 Skill 导出。

下一页是 [扩展 Hook](https://powercontext.mintlify.site/zh/coding-agents/extend-hooks.md)。


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