Pi

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

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。

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。

​

执行流程

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 时：

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。