pi_agent_rust

696 82 非常简单 1 次阅读今天NOASSERTIONAgent插件

AI 解读由 AI 自动生成，仅供参考

pi_agent_rust 是一款专为终端打造的高性能 AI 编程助手命令行工具。它由 Rust 语言从头重构，旨在解决现有 AI 辅助工具启动缓慢、内存占用高、运行不稳定以及难以扩展等痛点。相比基于 Node.js 或 Python 的传统方案，pi_agent_rust 实现了秒级即时启动，并在长时间会话中显著降低内存消耗，同时提供稳定可靠的流式输出体验。

这款工具特别适合追求高效开发流程的程序员、系统架构师以及对安全性和性能有严苛要求的技术团队。它不仅保留了原有 Pi Agent 的核心工作流，更在底层引擎上进行了全面升级。其独特的技术亮点包括：采用零不安全代码（zero unsafe code）编写，确保内存安全；内置结构化并发运行时与精美的终端渲染能力；以及构建了一套细粒度的安全模型，通过能力门控和策略执行，默认阻断危险的系统调用，为插件扩展提供企业级的安全防护。无论是日常代码重构、错误分析还是复杂的项目维护，pi_agent_rust 都能以单二进制文件的轻便形态，为用户提供极速且安全的智能编码支持。

使用场景

资深后端工程师李工正在终端中紧急重构一个遗留的异步消息处理模块，需要频繁调用 AI 助手进行代码分析和生成。

没有 pi_agent_rust 时

启动延迟明显：基于 Node.js 或 Python 的现有工具每次启动需等待 500ms 以上，打断高频交互的心流。
资源占用过高：Electron 架构或重型运行时长期驻留内存，占用数 GB 空间，导致本地 Docker 容器因资源不足而卡顿。
会话稳定性差：在处理长上下文代码流时，偶尔出现输出截断或会话意外崩溃，且错误原因难以追踪。
安全顾虑重重：缺乏细粒度的权限控制，担心 AI 插件无意中执行递归删除或写入系统盘等危险 Shell 命令。

使用 pi_agent_rust 后

即时响应体验：得益于 Rust 编译为单一二进制文件，pi_agent_rust 实现毫秒级瞬间启动，指令发出即刻得到反馈。
极致轻量运行：内存占用极低，即使在长时间复杂会话中也能保持轻盈，不再挤压其他开发工具的生存空间。
稳定可靠流式输出：内置的结构化并发运行时确保了长文本生成的稳定性，彻底消除了会话损坏和静默失败的问题。
原生安全防御：通过能力门控和两阶段执行强制机制，默认拦截高危命令（如反向 Shell），让李工在放心授权的同时拥有完整的审计日志。

pi_agent_rust 将终端 AI 助手从“资源负担”转变为“安全、极速的原生生产力组件”，完美契合高性能开发需求。

运行环境要求

操作系统

Linux
macOS
Windows

GPU

未说明

内存

最低 <50MB (空闲状态)

依赖

notes该工具是用 Rust 编写的独立二进制文件，无需 Python、Node.js 或 Bun 运行时。它通过提供的 install.sh 脚本安装，具有极快的启动速度（<100ms）和极低的内存占用。安全模型包含对危险 shell 命令的默认拦截机制。

python不需要

Rust 2024 Edition

asupersync

rich_rust

rustls

SQLite

快速开始

Pi Agent Rust

pi_agent_rust

pi_agent_rust - 用 Rust 编写的高性能 AI 编程助手 CLI

为什么你应该关注？ • 简而言之 • 方法论 • 快速入门 • 功能 • 安装 • 命令 • 配置

# 安装最新版本
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

问题所在

你希望在终端中使用一个 AI 编程助手，但现有的工具存在以下问题：

启动缓慢：Node.js/Python 运行时会在你开始输入前增加 500 毫秒以上的延迟。
内存占用高：Electron 应用程序或重型运行时会消耗数 GB 的内存。
不可靠：流式传输中断、会话损坏、工具静默失效。
难以扩展：封闭的生态系统或复杂的插件系统。

解决方案

pi_agent_rust 是由 Mario Zechner 的 Pi Agent 项目（经其许可）从头开始用 Rust 重写的版本。它是一个单二进制文件，可立即启动，提供稳定的流式传输，并内置了 8 种工具。

与逐行翻译不同，这个移植版本基于两个专门构建的 Rust 库：

asupersync：一个结构化的并发异步运行时，内置 HTTP、TLS 和 SQLite。
rich_rust：由 Will McGugan 开发的 Rich 的 Rust 版本，提供带有标记语法的精美终端输出。

# 启动一个会话
pi "帮我将这个函数重构为使用 async/await"

# 继续之前的会话
pi --continue

# 单次模式（无需会话）
pi -p "这个错误是什么意思？" < error.log

为什么你应该关注？

如果你已经在使用 Pi Agent，尤其是通过 OpenClaw，那么这个项目在保留核心工作流程的同时，升级了底层引擎：

在真实的端到端流程中显著更快（而非合成的微基准测试）。
长时间运行会话中的内存占用大幅降低。
更强的安全模型，用于扩展和工具执行，包括在命令级别阻止危险的扩展 shell 模式。

安全性在这里是设计的一等公民，而非事后添加的功能：

基于能力的宿主调用（tool/exec/http/session/ui/events）。
两阶段扩展 exec 执行强制机制：首先进行能力检查，然后通过命令中介默认阻止关键的 shell 类型（例如递归删除、磁盘/设备写入、反向 Shell 等），并在严格/安全策略下进一步收紧以阻止更高级别的操作。
在执行路径上实施策略、运行时风险和配额控制。
每个扩展的信任生命周期（pending -> acknowledged -> trusted -> killed），配备杀毒开关审计日志和明确的操作员来源证明。
宿主调用通道的紧急控制机制，可在需要立即遏制快速通道行为时，全局或针对某个特定扩展强制切换到兼容通道执行。
使用 asupersync 提供的结构化并发，使取消/生命周期行为更加可预测。
可审计的运行时信号/账本以及针对扩展行为的脱敏安全警报。

简而言之（Pi/OpenClaw 用户）

以下是最重要的实际安全路径数据（大型会话、端到端行为）：

场景	Rust 总耗时	Legacy Node 总耗时	Legacy Bun 总耗时	Rust 优势
真实的 1M 会话	250.29 ms	1,238.67 ms	700.52 ms	比 Node 快 4.95 倍，比 Bun 快 2.80 倍
真实的 5M 会话	1,382.12 ms	5,974.67 ms	2,959.42 ms	比 Node 快 4.32 倍，比 Bun 快 2.14 倍

场景	Rust RSS	Legacy Node RSS	Legacy Bun RSS	Rust 内存优势
真实的 1M 会话	67,572 KB	820,380 KB	875,092 KB	比 Node 低 12.14 倍，比 Bun 低 12.95 倍
真实的 5M 会话	268,844 KB	2,173,096 KB	3,057,908 KB	比 Node 低 8.08 倍，比 Bun 低 11.37 倍

大规模下的恢复/打开响应速度也更好：

场景	Rust 打开时间	Legacy Node 打开时间	Legacy Bun 打开时间	Rust 优势
1M 会话恢复	17.59 ms	119.76 ms	50.83 ms	比 Node 快 6.81 倍，比 Bun 快 2.89 倍
5M 会话恢复	58.68 ms	396.41 ms	155.63 ms	比 Node 快 6.76 倍，比 Bun 快 2.65 倍

扩展运行时的保障也非常具体：

扩展保障信号	为什么你应该关注
两阶段 `exec` 保护（`exec` 能力策略 + 命令级中介 + DCG/heredoc AST 信号）	危险的 shell 意图会在进程启动前被捕获，包括隐藏在多行包装器中的破坏性载荷。
信任生命周期 + 杀毒开关（`pending/acknowledged/trusted/killed`）	你可以立即隔离某个扩展，记录是谁触发了开关以及原因，并且在恢复访问权限之前需要明确的重新确认。
宿主调用通道的杀毒开关控制（`forced_compat_global_kill_switch`、`forced_compat_extension_kill_switch`）	快速通道的回归问题可以通过强制切换到兼容通道执行来立即遏制，而无需禁用整个扩展系统。
确定性的宿主调用反应堆网络（分片亲和性、有限的 SPSC 通道、背压遥测、可选的 NUMA 板块跟踪）	在竞争条件下，运行时行为仍然可预测；队列压力和路由决策是可见的，而不是黑箱操作。
JS 运行时的启动预热 + 温暖隔离复用	运行时创建过程与启动重叠，而温暖复用则使重复的扩展运行保持低延迟，无需像 Node/Bun 那样的进程模型。
防篡改的运行时风险账本（`verify` / `replay` / `calibrate`）	安全决策被哈希链接，并可根据真实的运行时轨迹进行回放或阈值调整。

总之，对于真正的 Pi/OpenClaw 使用场景，Rust 版本不仅更快、内存效率更高，而且在真实工作负载压力下的扩展运行时安全性也显著更强。

_{数据来源：BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md（最新的安全路径 + 完整编排器检查点，2026-02-19）。}

我们为何能如此迅速地完成开发

在本 README 中，“我们”指项目所有者以及协作的编码智能体。速度的提升源于运行时设计，而非单一技巧。

技术	我们如何实现	运行时效果
冷启动最小化	单一静态二进制文件，无需 Node.js 或 Bun 的运行时引导，无 JIT 热身，对扩展运行时路径进行启动预热	更快的首次交互时间
减少热点路径上的拷贝	使用 `Arc`/`Cow` 消息流，零拷贝处理宿主调用与工具负载，减少大量克隆操作的提供者和会话路径	降低 CPU 和内存分配压力
确定性调度核心	类型化的宿主调用操作码、快速通道/兼容通道路由，结合反应堆网格遥测的有界分片队列	在并发扩展负载下改善尾延迟
高效的长会话存储	SQLite 会话索引 + v2 辅助进程（分段日志 + 偏移量索引），具备 O(索引+尾部) 的重新打开路径	快速恢复大型历史记录
针对真实网络优化的流式解析器	SSE 解析器跟踪已扫描字节数，处理 UTF-8 尾部，规范化数据块边界，并对事件类型字符串进行驻留	降低流式传输开销，减少解析器阻塞
安全的快速路径控制	影子双重执行采样、在偏差或开销过高时自动退避、用于隔离的兼容通道紧急关闭开关	在不导致行为悄然漂移的情况下保持优化的高效性
CI 级别的性能治理	场景矩阵、严格的工件契约、失败即关闭的性能门控	在发布前捕捉回归问题

如需完整的实现清单，请参阅性能工程。

基准测试方法与声明的完整性

上述基准测试刻意设计为贴近实际、可复现且难以作弊。

我们测量的内容包括：

状态匹配的工作负载：恢复一个大型会话并追加相同的 10 条消息。
真实的端到端工作负载：恢复 + 追加 + 扩展活动 + 斜杠风格的状态变更 + 分支 + 导出 + 整理。
规模级别：从 10 万 到 500 万 个标记类会话状态。
启动/就绪状态：命令级别的就绪状态（--help、--version）与长会话工作流分开衡量。

我们如何确保比较公平：

基准报告中的两个范围：
- 苹果对苹果（pi_agent_rust 对比旧版 coding-agent）
- 苹果对橙子（在旧版行为被外包的情况下，纳入了旧版栈组件）
发布模式下的二进制文件，并对每个矩阵单元重复运行。
核心延迟/占用表中不含付费提供商的噪声（这些核心比较中排除了提供商调用的成本）。

我们如何保证声明的真实性：

安全控制始终开启，即使是在测量安全路径时也是如此（不会为了追求速度而绕过策略、风险或配额限制）。
原始工件被保留（JSON、追踪和时间输出），并在基准报告中明确指出。
明确披露阻碍因素：当由于缺少工作区依赖项而无法直接重跑旧版代码时，我们会说明这一点，并改用先前验证过的旧版工件进行对比，而不是假装重跑成功。
解释说明清晰明确：报告区分了基线部分与全新重跑的结果，以便读者能够清楚地了解哪些数值来自哪次运行。
重视可复现性胜过营销宣传：除了展示成果之外，还详细介绍了方法论、注意事项以及已知的局限性。

如需完整细节，请参阅：

BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md（方法论 + 结果 + 注意事项 + 原始工件路径）

为什么选择 Pi？

特性	Pi（Rust）	典型的 TS/Python CLI
启动时间	<100ms	500ms-2s
二进制大小	<22MB（CI 约束预算）	100MB+（含运行时）
空闲内存	<50MB	200MB+
流式处理	原生 SSE 解析器	依赖于第三方库
工具执行	进程树管理	基本子进程
会话管理	JSONL 格式，支持分支	各不相同
不安全代码	禁止	不适用

快速示例

# 1) 启动交互式会话
pi

# 2) 提问关于代码库的问题
pi "总结 src 目录下的架构"

# 3) 内联附加文件
pi @src/main.rs "解释启动流程"

# 4) 以单次模式运行脚本
pi -p "列出这个代码差异可能存在的回归风险"

# 5) 继续上次的项目会话
pi --continue

# 6) 查看可用模型和提供商
pi --list-models
pi --list-providers

基础库

asupersync

asupersync 是一种结构化并发异步运行时，专为需要可预测资源清理的应用程序设计。pi_agent_rust 使用的关键特性包括：

基于能力的上下文 (Cx)：异步函数接收一个明确的上下文，控制其可执行的操作（HTTP、文件系统、时间）。这使得测试具有确定性。
带 TLS 的 HTTP 客户端：内置 rustls 的 HTTP API，避免 OpenSSL 依赖地狱。
结构化取消机制：当父任务取消时，所有子任务都会干净地取消，不会留下孤立的未来值。

pi_agent_rust 当前端到端运行在 asupersync 上（运行时 + HTTP/TLS + 取消机制）。提供商的流式传输使用一个极简的 HTTP 客户端（src/http/client.rs），将数据输入自定义的 SSE 解析器（src/sse.rs）。

rich_rust

rich_rust 是 Will McGugan 的 Python 库 Rich 的 Rust 移植版本。它提供了：

标记语法：[bold red]error[/] 渲染为粗体红色文本。
表格：支持 ASCII 和 Unicode 表格渲染，带有对齐和边框。
面板：带标题的盒状内容。
进度条：动画进度指示器。
Markdown：终端渲染的 Markdown，带有语法高亮。
主题：跨组件的一致配色方案。

终端 UI 使用 rich_rust 进行所有输出格式化，从而提供与基于 Rich 的 Python 工具相同的视觉质量。

快速开始

1. 安装

# 安装最新发布的二进制文件
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

如果您已经安装了原始的 TypeScript 版本 pi，安装程序会询问是否将 Rust 版本设为默认的 pi，并自动创建 legacy-pi 以供旧命令使用。

2. 配置 API 密钥

export ANTHROPIC_API_KEY="sk-ant-..."

3. 运行

# 交互模式
pi

# 带初始消息
pi "解释这个代码库的结构"

# 将文件作为上下文读取
pi @src/main.rs "这段代码的作用是什么？"

功能

流式响应

实时逐 token 流式输出，并支持扩展思考过程：

pi "编写一个快速排序算法"

您将看到响应逐 token 出现，思考块也会内联显示。

7 内置工具

工具	描述	示例
`read`	读取文件内容，支持图片	读取 src/main.rs
`write`	创建或覆盖文件	写入一个新的配置文件
`edit`	精准的字符串替换	修复第42行的拼写错误
`bash`	执行带超时的 Shell 命令	运行测试套件
`grep`	在上下文中搜索文件内容	查找所有 TODO 注释
`find`	按模式查找文件	查找所有 *.rs 文件
`ls`	列出目录内容	src 目录下有什么？

所有工具均包含：

大型输出自动截断（2000 行 / 50KB）
响应中提供详细元数据
对于 bash 命令会清理进程树，避免产生孤儿进程

会话管理

会话以 JSONL 文件形式持久化，保存完整的对话历史：

# 继续最近的会话
pi --continue

# 打开特定会话
pi --session ~/.pi/agent/sessions/--home-user-project--/2024-01-15T10-30-00.jsonl

# 临时会话（不持久化）
pi --no-session

会话支持：

对话分支的树状结构
模型和思考层级变化的追踪
长时间对话的自动压缩

扩展思考模式

针对复杂问题启用深度推理：

pi --thinking high "设计一个分布式限流器"

思考层级：off、minimal、low、medium、high、xhigh

自定义（技能与提示模板）

技能：将 SKILL.md 放入 ~/.pi/agent/skills/ 或 .pi/skills/ 目录下，通过 /skill:name 调用。
提示模板：Markdown 文件放在 ~/.pi/agent/prompts/ 或 .pi/prompts/ 目录下，可通过 /<template> [args] 调用。
包：使用 pi install npm:@org/pi-packages 分享技能、提示模板、主题和扩展等。

自动补全

Pi 在交互式编辑器中提供上下文感知的自动补全功能：

@ 文件引用：输入 @ 后跟路径片段即可插入文件内容。补全引擎会通过 ignore crate 的 WalkBuilder 索引项目文件（遵循 .gitignore），上限为 5,000 条目。
/ 斜杠命令：内置命令（如 /help、/model、/tree、/clear、/compact、/exit）以及用户自定义的提示模板和技能都会作为补全选项出现。
模糊评分：前缀匹配优先于子串匹配。结果按匹配质量排序，再按类型排序（命令 > 模板 > 技能 > 文件 > 路径）。
后台刷新：后台线程每 30 秒重新索引一次项目文件树，确保补全内容始终最新，且不会阻塞输入循环。

三种执行模式

Pi 提供三种运行模式，分别适用于不同的工作流程：

模式	调用方式	使用场景
交互模式	`pi`（默认）	全功能 TUI，支持流式处理、工具调用、会话分支和自动补全
打印模式	`pi -p "..."`	单次响应输出到 stdout，无 TUI，可脚本化
RPC 模式	`pi --mode rpc`	通过 stdin/stdout 提供无头 JSON 协议，用于 IDE 集成

交互模式提供完整体验：多行文本编辑器带有历史记录，可滚动的对话视窗，模型选择器（Ctrl+L），作用域内模型循环切换（Ctrl+P/Ctrl+Shift+P），会话分支导航器（/tree），以及实时的 token 和成本跟踪。

打印模式发送一条消息，将响应流式输出到 stdout 并退出。适用于 shell 脚本和一次性查询。

RPC 模式暴露了一种以换行符分隔的 JSON 协议，用于程序化控制。客户端发送命令（prompt、steer、follow-up、abort、get-state、compact），并接收流式事件。IDE 扩展和自定义前端正是通过这种方式与 Pi 集成的。有关协议格式，请参阅 RPC 协议。

扩展

Pi 支持两类扩展运行时，并通过能力门控机制连接宿主环境：

JS/TS 入口在嵌入式 QuickJS 运行时中运行，无需 Node.js 或 Bun。
*.native.json 描述文件则在原生 Rust 描述文件运行时中执行。
扩展入口会自动检测：
- .js/.ts/.mjs/.cjs/.tsx/.mts/.cts 文件直接在嵌入式 QuickJS 中运行（无需转换描述文件）。
- *.native.json 加载原生 Rust 描述文件运行时。
- 当前会话只能同时使用一种运行时体系（JS/TS 或原生描述文件）。
冷启动耗时低于 100ms（P95），热启动耗时低于 1ms（P99）。
提供 fs、path、os、crypto、child_process、url 等 Node.js API 的模拟层。
基于能力的安全机制：扩展通过明确的连接器调用（tool/exec/http/session/ui），并进行审计日志记录。
命令级执行中介：危险的 Shell 签名会被分类并阻止执行，在拒绝执行时会提供脱敏警告信息，并记录中介日志。
可信状态生命周期及紧急关闭控制，具有经过审计的状态转换（pending/acknowledged/trusted/killed）。
主机调用反应堆网络，具备确定性分片路由、有界队列背压，以及可选的 NUMA 感知遥测功能。
运行时预热路径，通过复用预热隔离区来减少扩展启动成本，使大部分启动费用在首次提示之前就已支付。

凭证感知的模型选择

/model（或 Ctrl+L）打开一个选择器，专注于当前凭证可用的模型。
Ctrl+P 和 Ctrl+Shift+P 可在限定范围内循环切换模型，而无需打开叠加层。
在模型选择和 /login 中，提供者 ID 和别名均不区分大小写匹配。
不需要配置凭证的模型可以无需密钥直接运行。

扩展可以注册工具、斜杠命令、事件钩子、标志位、提供者和快捷方式。完整的架构请参阅 EXTENSIONS.md，224 项扩展的目录及其合规状态和性能预算请见 docs/extension-catalog.json。

扩展验证流水线

该项目采用三轨验证流水线来确保扩展兼容性：

自有库（224 个）：确定性的合规性测试、兼容性矩阵和场景测试套件。
非自有库（777 个）：源代码获取和优先级排序。
发布版二进制文件与真实提供商的端到端测试：在未模拟的真实提供商/模型路径上运行 target/release/pi。

设立原因

检测 QuickJS 宿主模拟层和能力策略中的运行时/API 回归问题。
捕获危险的扩展 Shell 调用模式，通过发布版二进制文件上的实际命令中介机制。
验证扩展行为是否符合真实提供商的响应，而不仅仅是基于固定数据或模拟流程。
将扩展支持从经验性转变为可衡量的依据。
生成一个优先级队列，用于将非自有库中的候选扩展纳入自有库的合规范围。

管道组件

获取未打包的源语料库
- 二进制文件：ext_unvendored_fetch_run
- 典型命令：
  - cargo run --bin ext_unvendored_fetch_run -- run-all --workers 8 --no-probe
- 目的：
  - 克隆 GitHub 仓库并解压 npm tarball 文件到 .tmp-codex-unvendored-cache/ 目录中。
  - 为所有未打包候选生成机器可读的采集状态报告。
- 产出物：
  - tests/ext_conformance/reports/pipeline/unvendored_fetch_probe_report.json
  - tests/ext_conformance/reports/pipeline/unvendored_fetch_probe_events.jsonl
运行端到端验证编排
- 二进制文件：ext_full_validation
- 典型命令：
  - cargo run --bin ext_full_validation --
- 阶段（按顺序）：
  1. refresh_onboarding_queue（运行 ext_onboarding_queue）
  2. conformance_shard_0..N（运行分片矩阵 ext_conformance_generated）
  3. conformance_failure_dossiers
  4. provider_compat_matrix
  5. scenario_conformance_suite
  6. auto_repair_full_corpus
  7. differential_suite（可选，通过 --run-diff 启用；npm 差异比较通过 --run-npm-diff 启用）
- 产出物：
  - tests/ext_conformance/reports/pipeline/full_validation_report.json
  - tests/ext_conformance/reports/pipeline/full_validation_report.md
  - 以及位于 tests/ext_conformance/reports/** 下的各阶段特定报告。
运行开发优先集实时提供商准入测试（发布构建前必须通过）
- 二进制文件：ext_release_binary_e2e
- 典型命令：
  - cargo build --bin pi --bin ext_release_binary_e2e
  - PI_HTTP_REQUEST_TIMEOUT_SECS=0 target/debug/ext_release_binary_e2e --pi-bin target/debug/pi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced --out-json tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.json --out-md tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.md
- 目的：
  - 在支付发布构建成本之前，证明当前代码路径在具有代表性的首个集合上能够端到端正常工作。
  - 作为晋升到完整发布二进制验证的准入门槛。
- 准入条件：
  - 必须满足 pass=20 / total=20 且 fail=0。
- 产出物：
  - tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.json
  - tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.md
运行完整发布二进制实时提供商端到端测试（步骤 3 通过后）
- 二进制文件：ext_release_binary_e2e
- 典型命令：
  - cargo build --release --bin pi --bin ext_release_binary_e2e
  - PI_HTTP_REQUEST_TIMEOUT_SECS=0 target/release/ext_release_binary_e2e --pi-bin target/release/pi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --extension-policy balanced --out-json tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.json --out-md tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.md
- 目的：
  - 直接为每个选定的扩展案例执行 target/release/pi。
  - 使用实时提供商/模型路径（默认为 ollama + qwen2.5:0.5b），以测试非模拟的端到端行为。
  - 输出每个案例的 stdout/stderr 捕获数据，并生成汇总产物（pi.ext.release_binary_e2e.v1）。
- 产出物：
  - tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.json
  - tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.md
  - tests/ext_conformance/reports/release_binary_e2e/cases/*
聚合与分类处理
- full_validation_report.json 汇总了以下内容：
  - 各阶段的通过/失败情况（stageSummary, stageResults）
  - 语料库数量统计（corpus）
  - 打包一致性总计（conformance）
  - 提供商矩阵总计（providerCompat）
  - 场景总计（scenario）
  - 审核队列及判定分类（reviewQueue, verdictCounts）
- 重要解读规则：
  - not_tested_unvendored 表示尚未纳入打包一致性测试的未打包候选；这属于库存状态，而非打包回归问题。

安装

Curl 安装程序（推荐）

# 最新版本
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

# 非交互式 + 自动更新 PATH
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash -s -- --yes --easy-mode

# 固定某个发布标签
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash -s -- --version v0.1.0

# 从明确的产物 URL 和校验码 URL 安装
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | \
  bash -s -- \
    --artifact-url "https://github.com/Dicklesworthstone/pi_agent_rust/releases/download/v0.1.0/pi-linux-amd64.tar.xz" \
    --checksum-url "https://github.com/Dicklesworthstone/pi_agent_rust/releases/download/v0.1.0/SHA256SUMS"

# 跳过补全设置（CI/非交互式最小化安装）
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | \
  bash -s -- --yes --no-completions

该安装程序具有幂等性，并支持从 TypeScript Pi 的迁移路径：

检测现有的 TS pi 命令
提示将 Rust Pi 安装为标准的 pi
将旧 CLI 保留在 legacy-pi 后面
记录状态以便于干净卸载或恢复

值得注意的安装程序标志：

--offline [TARBALL]：强制离线模式；可选本地工件路径（.tar.gz、.tar.xz、.zip 或原始二进制文件）
--artifact-url：强制指定发布工件的 URL
--checksum / --checksum-url：覆盖显式工件的校验和来源
--sigstore-bundle-url：覆盖 cosign verify-blob 使用的 Sigstore 包 URL
--completions auto|off|bash|zsh|fish：强制指定 shell 补全的安装目标（off 等同于 --no-completions）
--no-completions：禁用补全安装
--no-agent-skills：跳过自动将 pi-agent-rust 技能安装到 ~/.claude/skills/ 和 ~/.codex/skills/
--no-verify：跳过校验和与签名验证（仅用于测试）
--artifact-url 如果没有 --version，则仅在发布模式下使用合成标签；如果工件下载失败，安装程序将退出，而不是尝试回退到源代码
安装程序会尊重 HTTPS_PROXY / HTTP_PROXY 进行所有网络获取操作

默认情况下，安装程序还会为 Claude Code 和 Codex CLI 安装一个 pi-agent-rust 技能：

Claude Code：~/.claude/skills/pi-agent-rust/SKILL.md
Codex CLI：~/.codex/skills/pi-agent-rust/SKILL.md（或者如果设置了 CODEX_HOME，则为 $CODEX_HOME/skills/pi-agent-rust/SKILL.md）
在升级过程中，如果存在先前的安装程序状态，安装程序管理的旧版本遗留条目会被自动移除（幂等、路径范围且无破坏性）。

安装程序回归测试套件（选项 + 校验和 + 签名 + 补全）：

bash tests/installer_regression.sh

分发兼容性契约（打包/调用范围）

为了实现即插即用式的采用，打包和调用兼容性遵循以下契约：

本节仅涵盖打包/调用行为；严格的功能性即插即用替换消息由 docs/dropin-certification-contract.json 中的发布认证门控来管理。
标准可执行文件名称在所有发布资产和安装程序管理的安装中均为 pi。
安装程序管理的安装还会创建一个 rpi 兼容启动器，前提是您的 PATH 上尚未存在冲突的 rpi 命令。
现有的 TypeScript pi 安装可以就地迁移；之前的命令会被保留为 legacy-pi。
如果您将 TypeScript pi 保留为标准命令（--keep-existing-pi），Rust Pi 将被安装为 pi-rust。
在 Apple Silicon 上，即使是从 Rosetta 翻译的 Shell 启动，安装程序也会优先选择原生 arm64 工件。
支持通过 install.sh --version vX.Y.Z 进行版本锁定安装，以实现确定性的部署。
每次 GitHub 发布都会提供平台二进制文件以及用于完整性验证的 SHA256SUMS。

代表性烟雾测试：

# 标准命令应存在并可执行
command -v pi
pi --version
pi --help >/dev/null

# 如果进行了 TS 迁移，旧命令仍然可用
command -v legacy-pi && legacy-pi --version

从源码编译

需要 Rust nightly（2024 年版特性）：

# 安装 Rust nightly
rustup install nightly
rustup default nightly

# 克隆并构建
git clone https://github.com/Dicklesworthstone/pi_agent_rust.git
cd pi_agent_rust
cargo build --release

# 二进制文件位于 target/release/pi
./target/release/pi --version

# 若要进行系统级安装（--locked 可确保可重复的依赖解析）
cargo install --path . --locked

依赖项

Pi 的运行时依赖项非常少：

fd：用于 find 工具（可通过 apt install fd-find 或 brew install fd 安装）
rg：用于 grep 工具（可通过 apt install ripgrep 或 brew install ripgrep 安装）

卸载

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/uninstall.sh" | bash

默认情况下，卸载会移除安装程序管理的 Rust 二进制文件/别名和技能目录，然后恢复之前保留的 TypeScript pi（如果有的话）。

命令

基本用法

pi [OPTIONS] [MESSAGE]...

# 示例
pi                              # 启动交互式会话
pi "Hello"                      # 带消息启动
pi @file.rs "Explain this"      # 将文件作为上下文加入
pi -p "Quick question"          # 打印模式（无会话）

交互式文件引用：

在编辑器中输入 @relative/path 可附加文件内容（自动补全会插入 @ 形式）。

选项

选项	描述
`-c, --continue`	继续最近的会话
`-r, --resume`	打开会话选择界面
`--session <PATH>`	打开特定的会话文件
`--session-dir <DIR>`	覆盖本次运行的会话存储目录
`--session-durability strict	balanced
`--no-session`	不保存对话
`-p, --print`	单一回复，无交互
`--mode text	json
`--provider <NAME>`	强制指定本次运行的提供商（支持别名）
`--model <MODEL>`	使用的模型（自动选择后备：`anthropic/claude-opus-4-5`，然后 `openai/gpt-5.1-codex`，再然后 `google/gemini-2.5-pro`）
`--thinking <LEVEL>`	思考级别：关闭/极简/低/中/高/超高
`--tools <TOOLS>`	逗号分隔的工具列表
`--api-key <KEY>`	API 密钥（或使用提供商特定的环境变量，如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等）
`--extension-policy safe	balanced
`--repair-policy off	suggest
`--list-models [PATTERN]`	列出可用模型（可选模糊筛选）
`--list-providers`	列出标准提供商 ID、别名和认证环境变量键
`--export <PATH>`	将会话文件导出为 HTML

其他高杠杆标志：

--no-migrations 用于跳过启动迁移检查
--explain-extension-policy 用于打印有效的功能决策并退出
--explain-repair-policy 用于打印有效的修复策略解析结果并退出

子命令

# 软件包管理
pi install <source> [-l|--local]    # 安装软件包源并添加到设置中
pi remove <source> [-l|--local]     # 从设置中移除软件包源
pi update [source]                 # 更新所有（或单个）未锁定的软件包
pi list                            # 列出设置中的用户和项目软件包

# 配置
pi config                          # 显示设置路径 + 优先级

更多实用子命令：


# 扩展目录索引 + 发现
pi update-index
pi search "git"
pi info pi-search-agent

# 环境与扩展诊断
pi doctor
pi doctor --only sessions --format json
pi doctor ./path/to/extension --policy safe --fix

# 会话存储迁移（JSONL -> v2 sidecar 存储）
pi migrate ~/.pi/agent/sessions --dry-run
pi migrate ~/.pi/agent/sessions

update-index 刷新 search 和 info 使用的扩展索引元数据。
search 和 info 允许你在不离开 CLI 的情况下发现和检查扩展元数据。
doctor 检查配置、目录、认证、Shell 设置、会话以及扩展兼容性。
migrate 验证或创建 v2 会话 sidecar 格式，以在更大历史记录上实现更快的恢复。

配置

Pi 从 ~/.pi/agent/settings.json 读取配置：

{
  "default_provider": "anthropic",
  "default_model": "claude-opus-4-5",
  "default_thinking_level": "medium",

  "compaction": {
    "enabled": true,
    "reserve_tokens": 8192,
    "keep_recent_tokens": 20000
  },

  "retry": {
    "enabled": true,
    "max_retries": 3,
    "base_delay_ms": 1000,
    "max_delay_ms": 30000
  },

  "images": {
    "auto_resize": true,
    "block_images": false
  },

  "terminal": {
    "show_images": true,
    "clear_on_shrink": false
  },

  "shell_path": "/bin/bash",
  "shell_command_prefix": "set -e"
}

配置优先级

设置按优先级顺序解析（第一个匹配的生效）：

CLI 标志（--model、--thinking、--provider 等）
环境变量（ANTHROPIC_API_KEY、PI_CONFIG_PATH 等）
项目设置（工作目录中的 .pi/settings.json）
全局设置（~/.pi/agent/settings.json）
内置默认值

这意味着 CLI 标志始终覆盖 settings.json 中的值，而项目级别的设置则覆盖全局设置。

资源解析

技能、提示模板、主题和扩展遵循相同的解析顺序：

CLI 指定的路径（--skill、--prompt-template、--theme、-e）
项目目录（.pi/skills/、.pi/prompts/、.pi/themes/、.pi/extensions/）
全局目录（~/.pi/agent/skills/、~/.pi/agent/prompts/ 等）
已安装的包（~/.pi/agent/packages/）

当多个资源具有相同名称时，第一个出现的资源将被使用。冲突会被记录为诊断信息。

提示模板展开 支持位置参数：$1、$2、$@（所有参数）以及切片语法 ${@:start}、${@:start:length}。例如，一个模板以 /review src/main.rs --strict 调用时，src/main.rs 将作为 $1，--strict 将作为 $2。

环境变量

变量	描述
`ANTHROPIC_API_KEY`	Anthropic API 密钥
`OPENAI_API_KEY`	OpenAI API 密钥
`GOOGLE_API_KEY`	Google Gemini API 密钥
`AZURE_OPENAI_API_KEY`	Azure OpenAI API 密钥
`COHERE_API_KEY`	Cohere API 密钥
`GROQ_API_KEY`	Groq API 密钥（与 OpenAI 兼容）
`DEEPINFRA_API_KEY`	DeepInfra API 密钥（与 OpenAI 兼容）
`CEREBRAS_API_KEY`	Cerebras API 密钥（与 OpenAI 兼容）
`OPENROUTER_API_KEY`	OpenRouter API 密钥（与 OpenAI 兼容）
`MISTRAL_API_KEY`	Mistral API 密钥（与 OpenAI 兼容）
`MOONSHOT_API_KEY`	Moonshot/Kimi API 密钥（与 OpenAI 兼容）
`DASHSCOPE_API_KEY`	DashScope/Qwen API 密钥（与 OpenAI 兼容）
`DEEPSEEK_API_KEY`	DeepSeek API 密钥（与 OpenAI 兼容）
`FIREWORKS_API_KEY`	Fireworks API 密钥（与 OpenAI 兼容）
`TOGETHER_API_KEY`	Together API 密钥（与 OpenAI 兼容）
`PERPLEXITY_API_KEY`	Perplexity API 密钥（与 OpenAI 兼容）
`XAI_API_KEY`	xAI API 密钥（与 OpenAI 兼容）
`PI_CONFIG_PATH`	自定义配置文件路径
`PI_CODING_AGENT_DIR`	覆盖全局配置目录
`PI_PACKAGE_DIR`	覆盖包目录
`PI_SESSIONS_DIR`	自定义会话目录

架构

┌─────────────────────────────────────────────────────────────────┐
│                           CLI (clap)                            │
│  • 参数解析    • @file 展开    • 子命令       │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────┐
│                          Agent Loop                             │
│  • 消息历史     • 工具迭代    • 事件回调    │
└────────┬──────────────────────┬──────────────────────┬──────────┘
         │                      │                      │
┌────────▼────────┐  ┌─────────▼──────────┐  ┌───────▼──────────┐
│ Provider Layer  │  │  Tool Registry     │  │  Extension Mgr     │
│ • Anthropic     │  │  • read  • bash    │  │  • QuickJS JS/TS   │
│ • OpenAI (Chat/ │  │  • write • grep    │  │  • Native descriptor│
│   Responses)    │  │  • edit  • find    │  │    runtime          │
│ • Gemini/Cohere │  │  • ls              │  │  • Capability policy│
│ • Azure/Bedrock │  │  • ext-registered  │  │  • Node shims       │
│ • Vertex/Copilot│  │                    │  │  • Event hooks      │
│ • GitLab/Ext    │  │                    │  │  • Runtime risk ctl │
└────────┬────────┘  └─────────┬──────────┘  └───────┬──────────┘
         │                     │                      │
┌────────▼─────────────────────▼──────────────────────▼──────────┐
│                     Session Persistence                         │
│  • JSONL 格式 (v3)   • 树形结构   • 会话索引/缓存  │
│  • 每个项目目录    • 可选 SQLite 后端                │
└─────────────────────────────────────────────────────────────────┘

当前 src/providers/ 中的原生提供商包括 anthropic、openai、openai_responses、gemini、cohere、azure、bedrock、vertex、copilot 和 gitlab，而通过扩展提供的 streamSimple 提供商则通过相同的代理循环进行路由。

关键设计决策

无不安全代码：项目范围内强制执行 #![forbid(unsafe_code)]
流式优先：自定义 SSE 解析器，不会阻塞响应
进程树管理：使用 sysinfo crate 确保没有孤儿进程
结构化错误：使用 thiserror 并为每个组件定义特定的错误类型
速度导向的发布配置：启用 LTO + 去除符号 + opt-level = 3 以提升运行时性能

asupersync 上下文与 TypeScript Pi (pi-mono)

这个 Rust 移植版本保留了 Pi 的用户体验，但有意改变了运行时底层。最初的 TypeScript Pi（pi-mono、packages/coding-agent）基于 Node.js 和包级别的抽象构建。而 pi_agent_rust 则将这些行为迁移到 asupersync 原语之上，使得生命周期保证在运行时模型中变得明确。

关注点	TypeScript Pi (pi-mono 基线)	pi_agent_rust + asupersync
运行时模型	Node 事件循环 + Promise/AbortSignal 约定	`RuntimeBuilder` + 显式的反应器和运行时句柄
异步所有权	由框架/库代码协调的任务生命周期	结构化的任务所有权以及显式的跨线程通道（用于 TUI/RPC 桥接）
取消语义	主要依赖 API 和工具层的约定	运行时感知的取消检查 + 工具中的有界超时处理
I/O 能力形态	环境化的 Node API + 扩展层策略	能力作用域的上下文（`AgentCx` 包含于 `asupersync::Cx` 中）以及显式的宿主调用策略
HTTP 流式传输	取决于提供者和客户端	专门构建的 asupersync HTTP/TLS 客户端，为自定义 SSE 解析器提供数据流
确定性测试钩子	传统的异步测试设置	广泛应用于单元/集成测试的 asupersync 测试/运行时钩子

为何这在实践中很有用：

在中止或超时时，失败行为更加可预测，因为取消会在明确的循环边界和工具运行器中被检查。
资源生命周期更清晰，因为运行时、定时器和 I/O 路径都共享同一个并发基础。
隐藏的耦合更少，因为主要不变量存在于 Rust 类型和算法中，而不是分散在框架约定之中。

运行时不变量（及其重要性）

以下是我们在此实现中所依赖的具体不变量：

回合作用域内的代理生命周期
- 主循环会以稳定的顺序发出 AgentStart、TurnStart、TurnEnd 和 AgentEnd 事件。
- 工具递归受到 max_tool_iterations（默认值为 50）的限制，以避免无界自调用循环。
- 优点：为 TUI/RPC 消费者提供稳定的事件顺序，并确保可预测的终止行为。
明确的中止和超时行为
- 代理的中止检查发生在回合边界处以及工具执行前后。
- bash 超时遵循清晰的升级路径：先终止进程树，再进入宽限期，最后强制杀死。
- 优点：减少“挂起”会话，并在激进使用工具时降低孤儿进程的风险。
会话写入具有崩溃恢复能力
- JSONL 先将写入保存到临时文件，然后以原子方式持久化。
- 会话索引使用 SQLite WAL 加锁文件协调机制，支持多实例并发操作。
- 优点：在多进程使用场景下，能更好地保证持久性和恢复可靠性。
压缩由阈值驱动且考虑边界
- 触发条件：估计的上下文 token 数超过 context_window - reserve_tokens。
- 截断逻辑优先选择用户回合边界，并保留最近的上下文预算。
- 优点：压缩可以在不破坏近期任务连续性的情况下回收上下文。
能力策略采用失败封闭和优先级定义
- 决策顺序：按扩展的拒绝 -> 全局拒绝 -> 按扩展的允许 -> 默认能力 -> 模式回退。
- 优点：策略结果可解释、确定且可审计。
流式解析器能够容忍真实的网络分块
- SSE 解析器可以处理 CR/LF 变体、多行 data: 字段、部分 UTF-8 尾部以及流结束时的刷新。
- 优点：无论服务提供商如何，也不论网络是否碎片化，增量渲染都能保持稳健。

从 asupersync 带入 Pi 的设计原则

以下 asupersync 原则直接体现在 pi_agent_rust 的架构中：

单一异步基础：运行时、定时器、文件系统以及 HTTP/TLS 都运行在同一套连贯的基础之上。
显式上下文传递：在子系统边界处（代理/工具/会话/RPC），AgentCx 包装了 asupersync::Cx。
有限操作优先于尽力清理：超时路径和压缩阈值都是参数化的，并且可强制执行。
用于测试的确定性钩子：定时器驱动的睡眠以及 asupersync 测试辅助函数，减少了非确定性的不稳定现象。

与最初的 TypeScript 实现相比，这种做法将更多的正确性责任转移到运行时和核心算法本身，而不是主要依赖于生态系统的约定。

其他主要差异（原始 pi-mono 与 Rust 移植版）

这是第二次对比，重点关注高影响的架构性差异及其背后的原因。

领域	原始 pi-mono (`packages/coding-agent`)	`pi_agent_rust`	为何存在这些差异
分发模型	npm 包 (`npm install -g @mariozechner/pi-coding-agent`)	单一 Rust 二进制文件 (`pi`)	移除 Node 运行时依赖，提升启动和部署的可移植性
执行界面	交互式 + 打印 + JSON 模式 + RPC + SDK	交互式 + 打印 + JSON 模式 + RPC (+ 在 `docs/sdk.md` 中记录的 Rust SDK)	严格的无缝替换仍需通过发布准入；JSON/RPC/SDK 的声明必须有认证文档支持
默认内置工具姿态	默认为 `read/write/edit/bash`（其他也可用）	将七个内置工具视为一等公民（`read/write/edit/bash/grep/find/ls`）	无需额外配置即可使用常见的代码导航和 Shell 工作流
扩展信任模型	扩展/包模型被描述为拥有完整系统访问权限	内嵌运行时，具备能力约束的宿主调用和策略配置文件	降低环境权限，使扩展行为可审计，并采用默认拒绝策略
会话架构侧重点	JSONL 树形会话模型及分支导航	JSONL v3 树 + 显式会话索引（SQLite 辅助数据库）+ 可选 SQLite 会话后端	更快的大规模恢复与查找，以及更安全的多实例协调
流式传输栈	Node 运行时网络栈	专用 HTTP/TLS 客户端 + asupersync 上的自定义 SSE 解析器	对长流中的分块、解析和错误处理拥有更强的控制力
取消/超时机制	平台/事件循环取消约定	显式中止信号、受限工具迭代次数、进程树终止	最大限度减少挂起或孤儿进程，并在负载下使停止行为具有确定性
运行时上下文模型	框架级约定和扩展 API	显式 `AgentCx`/`asupersync::Cx` 能力范围内的上下文线程化	将效应边界和可测试性作为首要的架构约束

这些差异的实际影响：

扩展/包工作流在两种实现中均兼容。
不可妥协的目标是在所有用例中实现对 pi-mono 的严格无缝替换。
严格无缝替换的语言由 docs/dropin-certification-contract.json 和 docs/dropin-parity-gap-ledger.json 中的未解决差距状态来决定。
docs/parity-certification.json 仅作为信息性快照，不取代关于严格替换声明的发布准入政策。

算法机制：pi-mono 基线与 Rust 实现

本节比较了实现等效高层行为的具体机制。

算法	pi-mono 基线机制	Rust 实现机制	为何存在 Rust 版本
压缩后会话上下文重建	`buildSessionContext()` 发出压缩摘要，随后发送来自 `firstKeptEntryId`（压缩前路径）的消息，最后是压缩后的条目	`to_messages_for_current_path()` 使用相同的顺序，并在缺失 `first_kept_entry_id` 时提供回退	避免当压缩锚点孤立或损坏时发生无声的上下文丢失
JSONL 持久化	增量追加 (`appendFileSync`) 加上完全重写 (`writeFileSync`) 用于迁移和重写	通过临时文件保存 + 原子性持久化/替换	使磁盘上的会话状态在保存操作期间具备崩溃容错能力
会话发现/恢复	目录/文件扫描及 JSONL 文件的修改时间排序	SQLite 会话索引辅助数据库 + WAL + 锁文件 + 因过期触发的全量重新索引	限制恢复查询成本，并协调并发进程
压缩标记计数	使用助手用量（`totalTokens` 或 `input+output+cacheRead+cacheWrite`）加上启发式尾部估算	使用助手用量（`total_tokens` 或 `input+output`）加上启发式尾部估算；固定图像标记估算	在各提供商缓存标记报告不一致的情况下保持会计稳定，同时保持保守态度
切断点 + 分割回合处理	有效切断点排除工具结果；分割回合以历史记录 + 回合前文上下文的形式总结	相同的切断点分类和分割回合策略，在 Rust 条目/消息模型中实现	在预算压力下保持工具调用与结果的邻接性，以及回合的一致性
Bash 超时/进程清理	超时/中止会杀死进程树（`killProcessTree`），并返回截断尾部的输出	超时升级（先 `TERM`，再宽限，最后 `KILL`）+ 进程树遍历 + Shell 退出陷阱 + 截断尾部	强制进行有限清理，减少后台作业产生的后代进程泄漏
流式事件解码	传输语义对外暴露（`sse`/`websocket`/`auto`）；解析细节为运行时内部实现	显式 SSE 解析器，具备 BOM 去除、CR/LF 规范化、UTF-8 尾部缓冲及结束时强制刷新功能	使字节到事件的行为具有确定性，且独立于提供商 SDK

功能超集亮点（超出 pi-mono 基线）

上述章节比较了各项机制。本节则重点列出此 Rust 移植版本中特有的功能，而这些功能并未包含在 pi-mono 的基准实现模型中。

Rust 移植版功能	为何有用/引人注目
`pi doctor` 诊断命令（文本/JSON/Markdown 格式、`--only`、`--fix`、扩展兼容性检查）	提供可操作的环境与兼容性诊断信息，支持 CI 阻断（失败时返回非零值），并能自动修复安全问题，如缺失目录或权限不足等
基于能力的扩展策略配置文件（`safe` / `balanced` / `permissive`），并支持按扩展覆盖	允许运维人员以明确的能力边界运行共享扩展，而非赋予其系统范围的完全访问权限
对敏感信息感知的扩展环境变量过滤（通过 `pi.env()` 块禁用特定键/令牌/密钥）	减少因扩展代码路径而导致凭据意外泄露的风险
按扩展的信任生命周期与紧急关闭审计追踪（`pending`/`acknowledged`/`trusted`/`killed` 状态，以及 `kill_switch` 和 `lift_kill_switch` 操作）	支持即时隔离、明确的运维人员操作记录，并在审查后受控地重新启用
宿主调用兼容模式下的应急控制（全局或按扩展强制切换兼容模式，并附带原因代码）	为运维人员提供确定性的回滚路径，以便在快速响应场景下处理突发事件，同时不中断扩展服务可用性
针对扩展宿主调用的运行时风险控制器（可配置，默认为故障封闭）	在静态策略之外增加一层额外的执行约束，用于检测扩展调用流程中的可疑运行时行为
针对 Shell 路径的参数感知型运行时风险评分（`dcg_rule_hit`、`dcg_heredoc_hit`，以及对 Bash/Python/JS/TS/Ruby 中 here document AST 的检查）	在宿主调用执行前，检测隐藏在多行脚本和封装命令中的破坏性意图
防篡改的运行时风险账本工具（`ext_runtime_risk_ledger verify	replay
统一的事件证据包导出（包括风险账本、安全告警、宿主调用遥测、执行中介日志、秘密代理事件等）	事件响应团队可直接从一套结构化归档中进行分类处理，无需再手动拼接临时日志
具有可选 NUMA 分片池的确定性宿主调用反应器网格（分片亲和性、全局有序排空、有界 SPSC 队列、遥测功能）	在高负载情况下仍能保持扩展调度的可预测性，并暴露队列与背压行为以便调优
预热隔离池 + 启动前预热交接	将 JS 运行时的初始化工作移至首次交互之前，并在多次运行之间安全地复用已预热的状态
扩展前置静态分析（导入模块扫描与禁止模式检测，并提供策略感知提示）	在运行时执行之前捕获潜在的风险模式
兼容 Node/Bun 的扩展运行时，且无需依赖 Node/Bun（内置 QuickJS 并提供适配层）	可以在单一原生二进制部署模式下运行遗留扩展工作流
扩展兼容性扫描器 + 符合性测试套件	使扩展支持情况可度量、可审计，而非仅凭经验之谈
SQLite 会话索引辅助组件（WAL 日志、锁机制以及过时索引重建路径）	实现大规模会话的快速恢复与列表操作，而无需每次查询都扫描所有 JSONL 文件
Session Store V2 回滚与迁移账本（分段日志、检查点及回滚事件）	长时间会话的恢复可以回退到已知检查点，并明确迁移或回滚的操作记录
可选的 SQLite 会话存储后端（`sqlite-sessions` 功能）	支持希望使用数据库持久化会话数据的同时，也保留 JSONL 存储方式的部署场景
抗崩溃的会话保存路径（临时文件 + 原子化持久化）	提升会话文件写入时的可靠性，减少部分写入失败的情况
统一的宿主调用分发器与类型化分类映射（`timeout` / `denied` / `io` / `invalid_request` / `internal`）	提供一致的扩展/运行时错误语义，便于客户端处理
故障封闭的证据溯源门控（`run_id`/`correlation_id` 以及跨产物的溯源检查）	在发布阶段拒绝陈旧或被挑选出来的符合性/性能相关产物
带有稳定机器码的结构化认证诊断信息	在不泄露敏感凭据信息的前提下，提升故障排除与运维可见性

深度解析：核心算法

基于数学的决策系统

Pi 有意在能够改善运行时行为或提升基准测试置信度的地方使用高级数学。其目标并非为了“在文档中堆砌华丽公式”，而是为了做出更安全的策略决策、更快地适应负载变化，以及提供更可信的性能归因。

切换状态检测（CUSUM + BOCPD）

在扩展调度器中，Pi 结合 CUSUM 方法与贝叶斯在线变点检测技术，以尽早发现负载状态的变化（例如当宿主调用流量突然激增或骤降时）。

$$ S_t^+ = \max\left(0,;S_{t-1}^+ + (-z_t - k)\right), \quad S_t^- = \max\left(0,;S_{t-1}^- + (z_t - k)\right) $$

$$ H(r)=\frac{1}{\lambda}, \quad P(r_t=0 \mid x_{1:t}) \propto \sum_r P(r_{t-1}=r),H(r),P(x_t \mid r) $$

直观理解：CUSUM 能够捕捉持续性的漂移；而 BOCPD 则能在不设置僵硬固定阈值的情况下，及时发现突发的状态切换。

一致性预测区间

Pi 会跟踪非一致性分数（即当前观测值与移动平均值之间的绝对残差），并将超出区间的行为视为异常。

$$ q = \text{score}_{\lceil (n+1)\cdot \text{confidence} \rceil - 1}, \quad \text{异常若 } |x_t - \mu_t| > q $$

直观理解：阈值会根据近期行为动态调整，而不是硬编码一个固定的延迟上限。

PAC-Bayes 安全边界

Pi 的安全防护机制包含基于 PAC-Bayes-kl 的扩展结果边界，并会在该边界过高时拒绝激进的优化策略。

$$ \mathrm{kl}(\hat q ,|, q_{\text{bound}});\le;\frac{\mathrm{KL}(Q|P)+\ln!\left(2\sqrt{n}/\delta\right)}{n} $$

直观理解：这为真实误差风险设定了一个明确的不确定性感知上限，在允许进一步激进的运行时行为之前加以限制。

策略外评估（IPS/WIS/DR + ESS + 遗憾门控）

在批准任何策略变更之前，Pi 会先根据历史轨迹数据评估候选行为：

$$ w_i=\frac{\pi(a_i\mid x_i)}{\mu(a_i\mid x_i)}, \quad \hat V_{\text{IPS}}=\frac{1}{n}\sum_i w_i r_i $$

$$ \hat V_{\text{WIS}}=\frac{\sum_i w_i r_i}{\sum_i w_i}, \quad \hat V_{\text{DR}}=\frac{1}{n}\sum_i\left(\hat r_i + w_i(r_i-\hat r_i)\right) $$

$$ N_{\text{eff}}=\frac{(\sum_i w_i)^2}{\sum_i w_i^2}, \quad \Delta_{\text{regret}}=\bar r_{\text{baseline}}-\hat V_{\text{DR}} $$

直观理解：如果样本支持不足、不确定性较高，或者估计的遗憾值超过阈值，Pi 将采取故障封闭策略。

基于VOI的实验选择

VOI规划器会在严格的开销预算下，优先选择能够带来最大预期学习收益的探测。

$$ \text{priority}_i \propto \frac{\text{utility}_i}{\text{overhead}_i} $$

直观理解：只运行那些很可能改变决策的实验；跳过过时或价值低的探测。

加权瓶颈归因（基准测试）

在阶段1的矩阵基准测试中，Pi会根据实际的工作负载大小（session_messages）计算各阶段的加权贡献，并报告置信区间。

$$ \text{weighted_contribution}_s

\frac{\sum_i w_i,m_{i,s}}{\sum_i w_i,t_i}\cdot 100, \quad w_i=\text{session_messages}_i $$

$$ n_{\text{eff}}=\frac{(\sum_i w_i)^2}{\sum_i w_i^2}, \quad \mathrm{CI}{95}=\mu \pm 1.96\sqrt{\frac{\sigma^2}{n{\text{eff}}}} $$

直观理解：优先关注对真实端到端延迟起主导作用的部分，而不仅仅是孤立的微基准热点。

在线凸优化控制 + 损失跟踪

Pi还包含一个用于批处理/时间片控制的在线调优路径，并具有明确的回滚行为：

$$ \tau_{t+1}

\mathrm{clip}!\left(\tau_t - \eta\nabla_{\tau}\mathcal{L}t,;\tau{\min},\tau_{\max}\right) $$

直观理解：系统会持续自适应调整，但如果瞬时损失超过回滚阈值，它会立即恢复到更安全的配置。

数学概览

技术	在Pi中的位置	为何有帮助
CUSUM + BOCPD	扩展调度器的流量模式检测器	早期且稳健地检测流量模式切换
合规性区间	安全保障	自适应异常检测，无需静态魔法数字
PAC-Bayes界	安全保障的否决路径	当不确定性/风险过高时，采取保守关闭策略
IPS/WIS/DR + ESS	离策略评估器	只有在充分证据支持时才批准策略变更
VOI规划	实验调度器	将开销预算用于最高价值的探测
加权归因 + 置信区间	阶段1性能矩阵报告	根据真实的用户影响对优化工作进行排序
OCO + 损失回滚	运行时控制器	在负载下自适应调整，同时限制不安全漂移

SSE流式解析器

SSE（服务器发送事件）解析器是针对Anthropic流式响应格式的自定义实现。与基于库的方法不同，该解析器以状态机的形式逐字节处理数据：

字节 → 行缓冲区 → 事件解析器 → 类型化StreamEvent

关键特性：

属性	实现方式
缓冲	尽可能零拷贝；仅在行不完整时才累积
事件类型	12种不同变体：MessageStart、ContentBlockStart、ContentBlockDelta、ContentBlockStop、MessageDelta、MessageStop、Ping、Error以及思考相关的特殊事件
错误恢复	格式错误的事件会被记录，但不会导致流中断
内存	固定大小的滚动缓冲区，防止内存无限制增长

解析器能够处理以下边缘情况：

多行data:字段（用换行符连接）
跨TCP包边界分割的事件
event:字段出现在data:之前或之后
CRLF和LF两种换行符可互换使用

截断算法

来自工具的大规模输出（如文件读取、命令输出、grep结果）必须被截断，以免耗尽LLM的上下文窗口。截断算法在保持有用性的前提下，确保内容不超过限制：

┌─────────────────────────────────────────┐
│           原始内容              │
│         （可能非常大）              │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  HEAD: 前N/2行                  │
│  ─────────────────────────              │
│  [... X行被截断 ...]            │
│  ─────────────────────────              │
│  TAIL: 后N/2行                   │
└─────────────────────────────────────────┘

常量：

限制	值	理由
`MAX_LINES`	2000	平衡上下文使用与内容完整性
`MAX_BYTES`	50KB	防止二进制文件意外占用过多资源
`GREP_MAX_LINE_LENGTH`	500字符	截断压缩后的代码

算法步骤如下：

将内容按行分割。
如果行数超过MAX_LINES，则保留前1000行和后1000行。
插入标记，说明有多少行被省略。
如果字节数仍然超过MAX_BYTES，则进行字节级截断。
返回元数据，指示是否进行了截断，以便LLM可以请求特定范围的内容。

进程树管理

bash工具必须能够处理失控进程、死循环和叉子炸弹，同时避免留下孤儿进程。实现中使用了sysinfo crate来遍历进程树：

// 进程清理伪代码
fn kill_process_tree(root_pid: Pid) {
    let system = System::new();
    let children = find_all_descendants(root_pid, &system);

    // 先杀死子进程（从最深的开始），再杀死父进程。
    for child in children.iter().rev() {
        kill(child, SIGKILL);
    }
    kill(root_pid, SIGKILL);
}

超时行为：

命令启动时设置可配置的超时时间（默认120秒）。
输出实时流向滚动缓冲区。
超时后：先发送SIGTERM信号，给予5秒宽限期，随后强制发送SIGKILL信号。
遍历进程树并杀死所有子进程。
设置退出码，以区分超时终止和正常终止。

为避免后台作业成为孤儿（例如cmd &），bash脚本会安装一个EXIT陷阱，等待所有剩余的子进程结束后再以原始命令的状态退出。这样可以防止常见的问题：杀死外壳进程后，其子进程仍继续运行。

会话树结构

会话采用树形结构而非扁平列表，从而支持对话分支（在探索不同方法时非常有用）：

                    ┌─────────┐
                    │ 消息    │ (根节点)
                    │   #1    │
                    └────┬────┘
                         │
                    ┌────▼────┐
                    │ 消息    │
                    │   #2    │
                    └────┬────┘
                         │
              ┌──────────┼──────────┐
              │                     │
         ┌────▼────┐          ┌────▼────┐
         │ 消息    │          │ 消息    │ (分支)
         │   #3    │          │   #3b   │
         └────┬────┘          └────┬────┘
              │                    │
         ┌────▼────┐          ┌────▼────┐
         │ 消息    │          │ 消息    │
         │   #4    │          │   #4b   │
         └─────────┘          └─────────┘

JSONL 格式（v3）：

每行都是一个自包含的 JSON 对象，带有 type 鉴别符：

{"type":"session","version":3,"cwd":"/project","created":"2024-01-15T10:30:00Z"}
{"type":"message","id":"a1b2c3d4","parent":"root","role":"user","content":[...]}
{"type":"message","id":"e5f6g7h8","parent":"a1b2c3d4","role":"assistant","content":[...]}
{"type":"model_change","id":"i9j0k1l2","parent":"e5f6g7h8","model":"claude-sonnet-4-20250514"}

parent 字段用于构建树状结构。重放会话时，程序会从根节点遍历到当前叶节点。当出现分支时，新消息的 parent 将不同于前一条延续消息。

提供者抽象

Provider 特性对不同的大模型后端进行了抽象：

#[async_trait]
pub trait Provider: Send + Sync {
    fn name(&self) -> &str;
    fn models(&self) -> &[Model];

    async fn stream(
        &self,
        context: &Context,
        options: &StreamOptions,
    ) -> Result<impl Stream<Item = Result<StreamEvent>>>;
}

上下文结构：

pub struct Context {
    pub system: Option<String>,      // 系统提示词
    pub messages: Vec<Message>,       // 对话历史
    pub tools: Vec<ToolDef>,          // 可用工具及其 JSON 模式
}

流选项：

pub struct StreamOptions {
    pub model: String,
    pub max_tokens: u32,
    pub temperature: Option<f32>,
    pub thinking: Option<ThinkingConfig>,  // 扩展思考设置
    pub stop_sequences: Vec<String>,
}

这种设计允许在不修改智能体循环的情况下添加新的提供者（如 OpenAI、Gemini）。每个提供者会将通用类型转换为其通信格式，并输出统一的 StreamEvent 流。

压缩算法

长时间的对话最终会超出模型的上下文窗口。Pi 的压缩算法通过总结较早的消息来释放空间，同时保留最近的上下文。

该算法会在每次智能体轮次结束后自动运行，当预计的令牌使用量超过 context_window - reserve_tokens 时：

┌──────────────────────────────────────────────────────────────┐
│                     完整对话                         │
│  msg1 → msg2 → msg3 → ... → msgN-5 → msgN-4 → ... → msgN   │
│  ├──── 较早的消息 ─────┤ ├─── 最近的消息 ──────────┤ │
│                                                              │
│  第一步：在有效的轮次边界处找到切割点             │
│  第二步：LLM 将 msgs 1..N-5 总结为一段简洁的文字  │
│  第三步：将压缩条目存储到会话 JSONL 中             │
│  第四步：下一次智能体调用将使用 [摘要] + msgs N-4..N       │
└──────────────────────────────────────────────────────────────┘

令牌估算采用保守的文本 chars ÷ 4 估算法，而每张图片则固定为 1,200 个令牌。当助手消息中包含来自 API 的 usage 字段时，该测量值将优先于估算法。

切割点选择倾向于完整的用户-助手轮次之间的边界。如果预算限制迫使其在轮次中间切割，则算法会包含分割轮次中的前缀消息，以便模型能够保留关于边界处正在讨论内容的上下文。

文件操作跟踪会从被总结的消息中提取 read、write 和 edit 工具调用。压缩提示中会包含这些路径，以确保摘要能够保留对哪些文件已被查看或修改的记忆：

<read-files>
src/main.rs
src/config.rs
</read-files>

<modified-files>
src/auth.rs
</modified-files>

可配置参数：

参数	默认值	用途
`reserve_tokens`	上下文窗口的 8%	用于响应生成的安全余量
`keep_recent_tokens`	上下文窗口的 10%	至少保留的最近上下文比例

在交互模式下，也可以通过 /compact 命令手动触发压缩；或者使用 compact RPC 命令来实现。

多提供商路由与模型注册表

Pi 通过提供商工厂路由模型请求，该工厂会根据 (provider, model, api) 元组解析出正确的后端实现。

解析流程：

用户指定 --provider openai --model gpt-4o
               │
               ▼
  ┌──────────────────────────┐
  │  提供商元数据表          │  将 "openai" 映射为规范 ID，
  │                           │  并确定 API 类型（Completions、Responses 或自定义）
  │                           │
  └────────────┬──────────────┘
               │
  ┌────────────▼──────────────┐
  │  URL 规范化              │  根据检测到的 API 类型追加 /chat/completions、
  │                            │  /responses 或 /chat 路径
  │                            │
  └────────────┬──────────────┘
               │
  ┌────────────▼──────────────┐
  │  兼容性配置              │  应用针对不同模型的覆盖设置：
  │                            │  system_role_name、max_tokens 字段名、功能标志等
  │                            │
  └────────────┬──────────────┘
               │
  ┌────────────▼──────────────┐
  │  提供商实例              │  Anthropic | OpenAI | Gemini
  │                            │  Cohere | Azure | Bedrock | ...
  └───────────────────────────┘

models.json 覆盖设置：用户可以在 ~/.pi/agent/models.json 或 .pi/models.json 中定义自定义提供商。每个条目需指定模型 ID、基础 URL、API 类型以及可选的兼容性标志，从而允许您将请求路由到自托管模型、代理服务，或 Pi 本身不原生支持的提供商。

兼容性配置用于处理与 OpenAI 兼容的各类 API 之间的差异：

覆盖项	示例	用途
`system_role_name`	`"developer"`	o1 模型使用 `"developer"` 而非 `"system"`
`max_tokens_field`	`"max_completion_tokens"`	部分模型需要使用不同的字段名
`supports_tools`	`false`	对不支持工具调用的模型禁用工具定义
`supports_streaming`	`false`	对不支持流式响应的端点回退至非流式响应
`custom_headers`	`{"X-Custom": "val"}`	针对特定提供商注入自定义 HTTP 头

模糊匹配：当提供的提供商名称与任何已知提供商都不匹配时，Pi 会计算其与所有已注册提供商名称之间的编辑距离，并在错误信息中建议最接近的匹配项。

扩展宿主调用协议

扩展程序运行在一个嵌入式的 QuickJS 运行时（rquickjs crate）中，并通过一个结构化的宿主调用协议与 Pi 通信。正是这一机制使得 JavaScript 代码能够在不直接访问操作系统的情况下，调用 Pi 的内置工具、发起 HTTP 请求以及与会话进行交互。

执行模型：

┌─────────────────── QuickJS VM ───────────────────┐
│                                                   │
│  extension.js 调用：                              │
│    pi.tool("read", {path: "src/main.rs"})         │
│      │                                            │
│      ▼                                            │
│    将 HostcallRequest 入队：                       │
│      call_id: "hc-0042",                          │
│      kind: Tool { name: "read" },                 │
│      payload: { path: "src/main.rs" },            │
│    }                                              │
│      │                                            │
│      ▼                                            │
│    返回 Promise（resolve/reject 存储在映射中）    │
│                                                   │
└────────────────────────┬──────────────────────────┘
                         │
    drain_hostcall_requests()
                         │
                         ▼
┌─────────────── ExtensionDispatcher ──────────────┐
│                                                   │
│  1. 检查能力策略：                                │
│     read 工具 → 需要 "read" 能力                  │
│     → 策略规定：允许 / 拒绝 / 提示               │
│                                                   │
│  2. 如果允许 → 分发到 ToolRegistry               │
│     → 执行 read 工具                             │
│     → 获取 ToolOutput                              │
│                                                   │
│  3. complete_hostcall("hc-0042", Ok(result))      │
│     → 解析 QuickJS 中的 Promise                   │
│                                                   │
│  4. runtime.tick()                                │
│     → 清空 Promise .then() 链                      │
│     → 扩展 JS 继续执行                            │
│                                                   │
└───────────────────────────────────────────────────┘

能力映射：每种宿主调用类型都对应一个所需的权限：

宿主调用	所需权限	是否危险？
`pi.tool("read", ...)`	`read`	否
`pi.tool("write", ...)`	`write`	否
`pi.tool("bash", ...)`	`exec`	是
`pi.http(request)`	`http`	否
`pi.exec(cmd, args)`	`exec`	是
`pi.env(key)`	`env`	是
`pi.session(op, ...)`	`session`	否
`pi.ui(op, ...)`	`ui`	否
`pi.log(entry)`	`log`	否（始终允许）

去重处理：每个宿主调用的参数都会被规范化（对象键排序、结构标准化），并计算 SHA-256 哈希值。在短时间内出现的相同请求可以被去重，以避免重复执行工具。

快速通道与兼容性通道：Pi 对宿主调用提供了两条执行路径：

快速通道：当调用形式符合已知的安全模式时使用（例如常见的 tool 和 session 操作）。这样可以避免额外的内存分配和解析工作。
兼容性通道：用于处理不常见或参数不完整的调用作为回退方案。
两条通道仍然执行相同的权限策略和检查。
运维人员可以全局或按扩展强制切换到兼容性通道，作为紧急控制手段。

为了便于观测，每次调用都会被打上一个稳定的通道标签（例如 tool|tool.read|filesystem 或 tool|fallback|filesystem），以便对延迟和失败趋势进行一致的分组。

内置一致性保障机制（影子双重执行）：Pi 可以随机抽取一小部分只读宿主调用，分别通过两条通道执行，并比较其规范化的输出指纹。如果差异超过预设阈值，Pi 会自动暂时禁用快速通道。这样既保证了性能优势，又不会悄悄改变行为。

负载下的自适应调度模式：Pi 可以在以下两种模式之间切换：

sequential_fast_path：适用于较简单或竞争较少的工作负载。
interleaved_batching：当竞争和队列压力增加时使用。

模式切换受到采样覆盖率和风险检查的限制，因此 Pi 不会基于少量或有选择性的证据进行切换。

运行时遥测数据用于调试和调优：Pi 会记录结构化的宿主调用遥测信息（pi.ext.hostcall_telemetry.v1），包括通道选择、回退原因、调度延迟占比、序列化路径以及优化命中/未命中等字段。这些数据可用于性能报告和可靠性诊断。

自动修复流水线：当扩展加载失败或运行时出现错误时，Pi 的修复系统可以自动解决常见问题：

修复模式	行为
`Off`	不进行修复
`Suggest`	记录建议，但不应用
`AutoSafe`（默认）	应用可证明安全的修复措施（如缺失的文件路径、资源引用）
`AutoStrict`	应用激进的启发式修复（基于模式的转换）

兼容性扫描器：在加载之前，Pi 会对扩展源代码进行静态分析，检查导入语句、require() 调用以及禁止使用的模式（eval、Function()、process.binding、dlopen）。扫描结果会生成一份能力证据清单，用于支持策略决策。

环境变量过滤：扩展程序调用 pi.env() 时，会经过一个黑名单过滤，拒绝访问 API 密钥、凭据、令牌和私钥。该过滤器会阻止完全匹配项（如 ANTHROPIC_API_KEY、AWS_SECRET_ACCESS_KEY）、后缀模式（如 *_API_KEY、*_SECRET、*_TOKEN）以及前缀模式（如 AWS_SECRET_*、AWS_SESSION_*）。只有 PI_* 变量会被无条件允许。

信任生命周期与紧急关闭开关：扩展的信任状态会被明确跟踪（pending、acknowledged、trusted、killed）。紧急关闭开关会将扩展降级为 killed 状态，将其隔离在运行时风险控制器中，发出严重告警，并记录审计日志。解除关闭开关需要运维人员的明确操作，且会将扩展重新置为 acknowledged 状态。

扩展运行时决策逻辑（通俗解释）

扩展运行时包含几个小型决策引擎，以确保在工作负载模式变化时行为保持稳定：

信息价值规划器 (VOI)：根据“每毫秒的预期学习量”对候选探针进行排序，并在严格的开销预算内选择最佳组合。过时或价值较低的候选会被跳过，并给出明确的理由。
分片负载控制器：根据队列压力、延迟和饥饿风险调整路由权重、批处理预算以及退避/帮助因子。通过阻尼和振荡保护机制防止过度反应。
策略安全性评估器：使用多种估计器重放历史样本，仅当样本支持充分、不确定性低且预测遗憾控制在限制范围内时，才会批准该策略。

这些组件的设计都较为保守：如果置信度不足，Pi 会保持当前状态，而不是贸然切换。

交互式 TUI 架构

交互模式采用 Elm 架构（模型-更新-视图），通过 charmed_rust 库族实现，它是 Go 语言 Bubble Tea 框架的 Rust 版本。

组件栈：

┌────────────────────────────────────────────────────┐
│                 终端 (crossterm)                │
│  原始模式 │ Alt 屏幕 │ 键盘/鼠标事件      │
└──────────────────────┬─────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────┐
│             bubbletea 程序循环                  │
│  Init() → Update(Msg) → View() → 渲染循环      │
└──────────────────────┬─────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────┐
│                  PiApp (模型)                      │
│                                                     │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐  │
│  │  文本区域    │ │  视口        │ │  加载动画     │  │
│  │  (编辑器)    │ │  (对话)     │ │  (状态)    │  │
│  └─────────────┘ └──────────────┘ └─────────────┘  │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │           覆盖层堆栈                      │    │
│  │  模型选择器 │ 会话选择器   │ /tree     │    │
│  │  设置界面    │ 主题选择器   │ 分支管理  │    │
│  │  功能提示（扩展 UI）                        │    │
│  └─────────────────────────────────────────────┘    │
└──────────────────────┬─────────────────────────────┘
                       │
              异步通道 (mpsc)
                       │
┌──────────────────────▼─────────────────────────────┐
│             代理异步任务                        │
│  在 asupersync 运行时上运行                         │
│  流式传输提供者响应                                 │
│  执行工具                                           │
│  将 PiMsg 事件发送回 TUI 线程                       │
└────────────────────────────────────────────────────┘

异步/同步桥接：代理在单独的线程中运行 asupersync 异步运行时，通过 mpsc 通道与 bubbletea UI 线程通信。每个流式事件（文本增量、工具开始、工具更新、代理完成）都会转化为一个 PiMsg 变体，传递给 PiApp::update()，从而在 API 流式传输和工具执行期间保持 UI 的响应性。

视口滚动：对话视口会跟踪用户是否位于底部。当新内容到达且用户未向上滚动时，视口会自动跟随流的末尾。一旦用户向上滚动，自动跟随功能将被禁用；按下 End 键或输入新消息后，该功能会重新启用。

覆盖系统：模态 UI（模型选择器、会话选择器、分支导航器、扩展功能提示）会叠加在主对话视图之上。每个覆盖层会捕获键盘输入，直到被关闭。只有最顶层的活动覆盖层才会接收事件。

交互式编辑器中的斜杠命令：

命令	功能
`/help`	显示可用命令和快捷键
`/model` 或 `Ctrl+L`	打开带有模糊搜索的模型选择器
`Ctrl+P` / `Ctrl+Shift+P`	循环切换作用域内的模型
`/tree`	浏览并分叉对话树
`/clear`	清除对话并重新开始
`/compact`	触发手动压缩
`/thinking <level>`	在对话过程中更改思考级别
`/share`	将会话导出到 GitHub Gist
`/exit` 或 `Ctrl+C`	退出 Pi

RPC 协议

RPC 模式（pi --mode rpc）通过标准输入/输出暴露了一个基于换行符分隔的 JSON 协议，用于程序化集成。每行都是一个独立的 JSON 对象。

客户端 → Pi（标准输入）：

{"type": "prompt", "message": "解释这个函数", "id": "req-001"}
{"type": "steer", "message": "专注于错误处理"}
{"type": "follow-up", "message": "现在添加测试"}
{"type": "abort"}
{"type": "get-state"}
{"type": "compact", "reserve": 8192, "keepRecent": 20000}

Pi → 客户端（标准输出）：

{"type": "event", "event": "agent_start", "data": {"session_id": "..."}}
{"type": "event", "event": "text_delta", "data": {"text": "这个函数"}}
{"type": "event", "event": "tool_start", "data": {"tool": "read", "input": {}}}
{"type": "event", "event": "tool_end", "data": {"tool": "read", "output": {}}}
{"type": "event", "event": "agent_done", "data": {"usage": {}}}
{"type": "response", "id": "req-001", "data": {"status": "ok"}}

I/O 架构：两个专用线程分别负责读取标准输入和写入标准输出，通过通道与异步代理运行时相连。标准输入线程会在出现短暂错误时重试，以防止输入丢失。标准输出线程则每行输出后立即刷新，避免缓冲延迟。

消息队列：当代理正在流式传输响应时，传入的消息会被路由到以下两个队列之一：

队列	行为	使用场景
引导队列	中断当前响应；在下一轮处理	修正方向
后续队列	排队等待当前响应完成	顺序指令

队列模式（“全部”或“一次一条”）决定了多个排队的消息是合并为一轮处理，还是逐个单独处理。

RPC 上的扩展 UI：当扩展请求用户输入（功能提示、选择对话框）时，Pi 会发出一个 extensionUiRequest 事件。客户端会在自己的 UI 中渲染提示，并以 extensionUiResponse 消息作出回应。IDE 扩展因此可以呈现原生 UI 来处理功能决策，而无需回退到终端提示。

会话索引

会话恢复（pi -c 或 pi -r）需要在不扫描磁盘上每个 JSONL 文件的情况下，找到当前项目的最新会话。Pi 维护一个 SQLite 索引（session-index.sqlite），该索引提供常数时间的查找。

模式：

CREATE TABLE sessions (
    path            TEXT PRIMARY KEY,
    id              TEXT NOT NULL,
    cwd             TEXT NOT NULL,
    timestamp       TEXT NOT NULL,
    message_count   INTEGER NOT NULL,
    last_modified   INTEGER NOT NULL,
    size_bytes      INTEGER NOT NULL,
    name            TEXT
);

更新生命周期：

保存会话 JSONL 文件后，Pi 会将其元数据插入或更新到索引中。
pi -c 查询 WHERE cwd = ? ORDER BY last_modified DESC LIMIT 1。
pi -r 查询同一张表，并按最近时间排序显示选择器。

并发性：基于文件的锁（session-index.lock）对来自并发 Pi 实例的写操作进行序列化。读取使用 WAL 模式以实现非阻塞访问。

基于过时的重新索引：如果索引比可配置的阈值更旧，Pi 会完全重新扫描会话目录，以捕获由其他实例或手动编辑创建的文件。这种重新扫描可以在没有集中式守护进程的情况下保持索引的准确性。

会话存储 V2 侧车（大型会话快速路径）

Pi 还支持在 JSONL 会话旁边使用 v2 侧车存储，以便更快地恢复会话，并对长期历史记录进行更强的损坏检查。

新增内容：

分段追加日志文件（而不是一个不断增长的 JSONL 文件）
偏移索引行，用于直接查找和快速读取尾部
定期检查点和清单快照
用于审计性的迁移账本条目
基于检查点的回滚路径，并带有明确的回滚事件日志记录

恢复工作原理：

如果存在且最新的 v2 侧车，Pi 将从侧车索引 + 分段打开。
如果侧车数据相对于源 JSONL 已过时，Pi 将回退到解析 JSONL。
如果索引数据丢失或损坏，但分段有效，Pi 将重建索引。

完整性策略：

分段帧携带有效载荷和链式哈希。
索引行存储字节偏移量以及 CRC32C 校验和。
在信任侧车之前，验证会执行偏移范围、校验和匹配以及帧与索引对齐的检查。
截断的尾部帧在重建过程中可以恢复；而非 EOF 帧的损坏则会失败关闭，而不是静默丢弃数据。

CLI 支持：

pi migrate <path> --dry-run 在不写入的情况下验证迁移。
pi migrate <path> 执行 JSONL 到 v2 的迁移，并验证一致性。

身份验证与凭据管理

除了简单的 API 密钥外，Pi 还支持 OAuth、AWS 凭证链、服务密钥交换以及承载令牌身份验证。凭据存储在 ~/.pi/agent/auth.json 中，并采用文件锁定访问方式，以防止来自并发实例的损坏。存储的 API 密钥可以是文字字符串、$ENV:VAR_NAME 引用，或 $CMD:shell command / $COMMAND:shell command 来源，在请求时解析修剪后的标准输出。

机制	提供商	详情
API 密钥	Anthropic、OpenAI、Gemini、Cohere 以及许多兼容 OpenAI 的提供商	通过环境变量或设置静态密钥
OAuth	Anthropic、OpenAI Codex、Google Gemini CLI、Google Antigravity、Kimi for Coding、GitHub Copilot、GitLab 以及扩展定义的 OAuth 提供商	带有 PKCE/状态验证流程并自动刷新；Kimi 使用设备流
AWS 凭证	Bedrock	访问密钥 + 秘密 + 可选会话令牌；区域感知
服务密钥	SAP AI Core	客户 ID/秘密交换以获取承载令牌
承载令牌	自定义提供商	静态令牌存储在认证存储中

OAuth 令牌生命周期：

用户运行配置了 OAuth 的 pi。
Pi 检查 auth.json 中是否存在现有令牌。
如果不存在：打开浏览器到授权 URL，用户进行身份验证，Pi 接收授权码，将其兑换为访问令牌和刷新令牌，并将两者连同到期时间一起存储。
如果已过期但刷新令牌有效：Pi 用刷新令牌兑换新的访问令牌，并更新 auth.json。
承载令牌附加到 API 请求中。

Google CLI 风格的 OAuth 提供商会在令牌负载中携带项目元数据。Pi 会保留并刷新该负载，并在需要时可以从 GOOGLE_CLOUD_PROJECT 或本地 gcloud 配置中解析项目 ID。

凭据状态报告：pi config 显示每个配置提供商的凭据状态：缺失、ApiKey、OAuth有效（附带到期时间）、OAuth过期（附带过期时间）、AwsCredentials 或 BearerToken。

诊断代码：身份验证失败会产生特定的诊断代码（MissingApiKey、InvalidApiKey、QuotaExceeded、OAuthTokenRefreshFailed、MissingAzureDeployment、MissingRegion 等），并提供上下文相关的错误提示，而不是通用消息。

工具详情

read

读取文件内容（可选图像）：

输入：{ "path": "src/main.rs", "offset": 10, "limit": 50 }

支持图像（jpg、png、gif、webp），并可选自动调整大小。
以块形式流式传输文件字节，设置严格的大小限制，以减少峰值内存使用。
应用防御性图像解码限制，以阻止解压缩炸弹/OOM 输入。
最多截断至 2000 行或 50KB。
如果被截断，则返回继续提示。

bash

执行带有超时和输出捕获的 shell 命令：

输入：{ "command": "cargo test", "timeout": 120 }

默认超时 120 秒，每次调用可配置。
设置 timeout: 0 可禁用默认超时。
超时时清理进程树（杀死子进程）。
使用滚动缓冲区实现实时输出。
如果输出被截断，则完整输出会保存到临时文件中。

edit

手术式的字符串替换：

输入：{ "path": "src/lib.rs", "old": "fn foo()", "new": "fn bar()" }

精确字符串匹配（无正则表达式）。
如果未找到旧字符串或存在歧义，则失败。
返回差异预览。

grep

搜索文件内容：

输入：{ "pattern": "TODO", "path": "src/", "context": 2, "limit": 100 }

支持正则表达式模式。
匹配前后显示上下文行。
忽略 .gitignore 文件。

find

按模式查找文件：

输入：{ "pattern": "*.rs", "path": "src/", "limit": 1000 }

使用 fd 进行 glob 模式匹配。
按修改时间排序。
忽略 .gitignore 文件。

ls

列出目录内容：

输入：{ "path": "src/", "limit": 500 }

按字母顺序排序。
目录以尾随 / 标记。
达到限制时截断。

性能工程

为什么 Rust 对于 CLI 工具至关重要

CLI 工具的性能要求与服务器或 GUI 应用程序不同。最关键的指标是“首次交互时间”：用户在调用命令后，多久才能开始输入？

阶段	TypeScript/Node.js	Rust
进程启动	~10ms	~10ms
运行时初始化	200–500ms	0ms（无运行时）
模块加载	100–300ms	0ms（静态链接）
JIT 热身	50–100ms	0ms（AOT 编译）
总计	360–910ms	~10ms

这种差异会随着使用频率的增加而不断放大，尤其是在短周期的迭代式终端工作流中。

极致优化指南

Pi 的优化方式更接近低延迟引擎，而非典型的 CLI 应用程序。我们并非简单地“使用 --release 编译并寄希望于它”，而是有意识地在多个层次上实施激进的优化。

速度的来源包括：

启动路径极简：无需 JS 运行时引导、无需加载模块依赖图、无需 JIT 热身。
高频宿主调用专用化：常见扩展的宿主调用采用类型化的快速路径；不常见的调用则回退到兼容性路径。
负载下的自适应调度：当竞争加剧时，宿主调用调度会切换模式，压力缓解后再恢复原状。
快速路径的安全保障：通过采样式的影子双重执行检查，确保优化不会悄然改变行为。
低分配渲染：TUI 渲染缓冲区和 Markdown 渲染结果会被缓存复用，而不是每帧都重新构建。
快速恢复机制：会话索引结合 v2 辅助进程布局，避免在恢复时进行昂贵的全历史扫描。
增长限制机制：通过压缩和截断，防止令牌/上下文以及工具输出数据量在长时间会话中持续膨胀，从而影响响应速度。
以度量为导向的文化：性能相关工件会在 CI 中经过模式验证并设置准入门槛，确保优化工作基于证据驱动，并能尽早发现回归问题。

正是这些设计，使得 Pi 即便在同时进行大量流式处理、频繁调用工具、拥有庞大的会话历史记录以及运行复杂扩展工作负载的情况下，依然能够保持流畅的响应。

优化目录（代码 + 提交历史）

本目录反映了运行时、存储、流式处理和 UI 各个领域的长期变更序列。

该代码库中的具体工程工作包括：

领域	我们构建的内容	为何重要
扩展调度核心	类型化宿主调用操作码快速路径、兼容性回退通道、零拷贝负载池、规范哈希快捷方式、内部化操作路径	在保留正确性回退路径的同时，降低最热点扩展操作的每次调用开销
注册表/策略查找	不可变策略快照，具备 O(1) 能力检查；以及基于 RCU 的元数据快照，用于扩展注册表和工具元数据	消除热点授权/调度路径中重复的动态查找开销
排队与并发	核心绑定的 SPSC 反应器网格、受 S3-FIFO 启发的准入控制及公平性保障、BRAVO 式回退行为	在竞争条件下改善尾延迟，而不仅仅是优化中位数延迟
批量执行	AMAC 式交错批量执行器，具备停顿感知切换机制	避免在大量独立宿主调用同时进行时出现队头阻塞
IO 特化	io_uring 通道策略 + 诊断监控与兼容性回退	在安全且有益的情况下，将 IO 密集型调用路由到专用通道
扩展的运行时启动	QuickJS 预热路径、预热隔离区/字节码缓存行为，以及启动流水线并行化	降低首次实际扩展工作负载之前的冷启动开销
JS 桥接/调度路径	热点扩展循环中待处理任务快速路径调优及桥接层调度清理	减少 JS 请求与 Rust 执行之间的开销
自适应控制环路	切换模式检测（CUSUM/BOCPD）、预算控制器、基于 VOI 的实验规划器、平均场负载控制器、离策略评估门控	使运行时行为能够适应工作负载变化，而无需盲目调优
快速路径安全性	影子双执行采样，发生分歧时自动回滚/退避	防止性能优化无意间改变语义
跟踪级优化	宿主调用超指令编译器 + 第二层跟踪 JIT 路径	融合重复的操作码跟踪，降低重复调度开销
工具执行策略	动态只读工具分类 + 并行工具执行路径	在多个工具调用可安全并行执行时提高吞吐量
会话写入路径	写后自动保存队列、持久性模式、增量追加、检查点重写策略、单缓冲追加序列化	在保持交互流畅的同时，仍能在需要时支持更强的持久性
会话索引路径	异步合并索引更新、待处理事务清空的热点路径调优，以及减少分配和装箱开销	将恢复/发现元数据更新从交互式热点路径上移开
会话恢复路径	会话存储 V2 辅助进程（分段日志 + 偏移索引）、O(索引+尾部) 打开路径、过时辅助进程检测、迁移/回滚工具	避免在大型历史记录中进行全文件扫描，并改善恢复行为
长期会话维护	具有配额的后台压缩/快照工作线程 + 懒加载路径	控制会话增长，保持长时间运行的工作空间响应迅速
压缩内部实现	二分查找切分点逻辑、序列化辅助函数提取，以及面向零分配的压缩路径清理	降低压缩开销，避免压缩成为暂停源
流式处理内部实现	SSE 解析器事件类型内部化、已扫描字节数跟踪 (`scanned_len`)、UTF-8 恢复加固	减少标记化流式传输过程中的重复扫描/分配，并提高容错能力
提供者/消息内存路径	零拷贝请求上下文迁移 (`Cow`)、基于 `Arc` 的消息/结果共享、流结束路径上的克隆消除	消除核心代理/提供者循环中的热点路径克隆和频繁分配
TUI 渲染路径	消息渲染缓存、对话前缀缓存、可复用渲染缓冲区、视口/渲染路径重构、Criterion 性能门控	在流式传输长输出时降低重绘成本和抖动
启动/资源加载	技能/提示/主题并行加载，以及预计算的工具定义和命令名称	将繁重的初始化工作从关键路径上移开，以提升用户交互时间
分配器/构建配置	对于内存密集型路径，默认使用 jemalloc；发布配置面向速度；严格验证性能声明的工件	提高运行时一致性，防止基准测试和报告结果漂移
性能治理	场景矩阵、声明完整性门控、严格的无数据失败行为、方差/置信区间工件、可重复的编排包	使性能声明可审计，并实现回归自动检测
宿主调用封送计划	`HostcallRewriteEngine` 使用小型成本模型，在明确更便宜且无歧义时才选择快速操作码融合；否则仍走规范路径并记录回退原因	在热点封送形状上提升速度，同时避免因模糊重写而导致无声语义漂移的风险
工具文本处理热点路径	`truncate_head`/`truncate_tail` 使用惰性行遍历和 `memchr` 行计数；规范化改为单次转换，而非链式字符串重写	大文件/工具输出避免不必要的中间分配，保持响应迅速
JS 桥接正则表达式和解析器微路径	扩展 JS 桥接中频繁的正则表达式检查采用 `OnceLock` 缓存；热点桥接调用避免重复设置	降低扩展密集型会话中每次调用的重复开销
CLI/自动补全进程创建减少	`fd`/`rg` 可用性检查被缓存，自动补全文档索引刷新在后台运行，且允许使用过时更新	即使在非常大的代码库中，也能保持补全和命令处理的快速响应
会话身份/索引微优化	O(1) 条目 ID 缓存、单次元数据定稿，以及追加路径清理取代多轮/高复制行为	当会话规模增大时，降低追加/保存/重建的开销
基于基准测试的回滚纪律	待选微优化都会经过基准测试，若在真实工作负载下导致性能下降，则可回滚（例如，SSE 中的新行扫描 `memchr` 替换就被回滚）	防止那些理论上速度快、但实际上会拖慢使用的“优化”

优化涵盖了算法、执行通道、内存管理、队列规则、存储布局和验证策略等多个方面，作为一个整体系统协同工作。

发布配置与二进制大小限制

正式发布的配置文件针对运行时速度进行了优化：

[profile.release]
opt-level = 3        # 最大化速度优化
lto = true           # 跨所有 crate 的链接时优化
codegen-units = 1    # 单一代码生成单元（编译较慢，但优化效果更好）
panic = "abort"      # 不启用异常取消机制
strip = true         # 移除符号表

在 CI 中，二进制大小仍然通过 binary_size_release 进行显式预算管理，当前的发布阈值设置为 22.0 MB。

基准测试证据与正式发布产物

Pi 将性能证据产物与可分发的发布产物区分开来：

基准测试证据产物（PERF-3X 和认证输入）由 scripts/perf/orchestrate.sh 和 scripts/bench_extension_workloads.sh 生成，必须包含运行溯源信息（correlation_id）以及配置标签（例如 build_profile=perf）。
正式发布产物（面向用户的二进制文件）使用 Cargo 的 release 配置构建，并通过 GitHub Releases 和安装程序路径分发。

政策含义：仅凭发布/大小相关的产物并不能作为全球性能声明的有效证据。性能声明必须引用具有可重复溯源性的基准测试证据包。有关规范性政策详情，请参阅 docs/testing-policy.md 和 docs/releasing.md。

最新的完整编排器检查点（2026-02-19）：

运行输出：/data/tmp/pi_agent_rust/codex/perf/full_local_skipbuild_retry_20260219T0650Z
关联 ID：fullbench-local-skipbuild-retry-20260219T0650Z
总结：共执行 11 个测试套件，其中 9 个通过，2 个失败（perf_budgets、perf_regression）。
失败原因：两次失败均为严格的证据/前提条件检查（缺少或过时的规范性产物路径，以及缺少严格的发布二进制路径），而非测量到的吞吐量或延迟崩溃。
同次运行中测得的启动保护指标仍处于绿色范围：--help P95 值为 3.8ms，--version P95 值为 3.6ms。

快速迭代循环与权威基准测试

在日常开发中，应使用针对性的检查以保持快速迭代。将权威的基准测试结论保留用于需要重新生成完整证据的集成边界。

快速迭代循环（非权威）： 文件作用域内的 cargo fmt --check 以及有针对性的测试重放（当编译较为复杂时，使用 rch exec -- cargo test --test ...）。
权威通过（权威）： 将耗时较长的运行交由严格的远程控制机制执行（使用 rch exec -- ... 或带有 --require-rch 参数的脚本封装），随后要求更新以下证据产物：
- tests/perf/reports/phase1_matrix_validation.json
- tests/full_suite_gate/full_suite_verdict.json
- tests/full_suite_gate/certification_verdict.json
- tests/full_suite_gate/extension_remediation_backlog.json

这样既能保证内部循环的响应速度，又能在发布时维持严格的声明完整性。

扩展工作负载热点分析

Pi 提供了一个专门用于分析扩展运行时瓶颈的工作负载框架：

cargo run --bin ext_workloads -- \
  --out artifacts/perf/ext_workloads.jsonl \
  --matrix-out artifacts/perf/ext_hostcall_hotspot_matrix.json \
  --trace-out artifacts/perf/ext_hostcall_bridge_trace.jsonl

该框架不仅进行简单的计时：

将宿主调用成本细分为六个阶段：marshal、queue、schedule、policy、execute、io；
生成热点矩阵（pi.ext.hostcall_hotspot_matrix.v1），以便快速排序瓶颈；
生成桥接跟踪事件（pi.ext.hostcall_trace.v1），用于逐调用调试；
测量各阶段之间的交互，并验证是否覆盖了所有阶段组合；
生成 VOI 调度计划（pi.ext.voi_scheduler.v1），以在固定开销预算下推荐下一步最具价值的实验。

简而言之，它通过数据而非猜测来回答“我们接下来应该优化什么？”这个问题。

性能报告的声明完整性约束

Pi 的性能流水线包含严格的证据检查，以确保全局速度声明不会基于不完整或过时的数据。

scripts/perf/orchestrate.sh 会生成与同一运行共享 correlation_id 的相关产物。
scripts/e2e/run_all.sh 在认定声明有效之前，会验证所需的模式、新鲜度以及 correlation_id 的一致性。
tests/release_evidence_gate.rs 会在合规性/性能产物缺失 run_id 或 correlation_id，或者关联产物间的 lineage 字段不一致时，直接判定为失败。
scripts/e2e/run_all.sh 会输出一份证据裁决矩阵，只有当新鲜度和 lineage 检查均通过时，才会将证据视为权威。
主要面向发布的产物包括：
- pi.perf.extension_benchmark_stratification.v1
- pi.perf.phase1_matrix_validation.v1
- pi.claim_integrity.evidence_adjudication_matrix.v1

如果证据集不完整或相互矛盾，声明完整性约束将保持关闭状态，并明确指出具体原因。

基准测试中的分配器策略

正式发布的构建默认使用平台分配器。对于分配器实验，Pi 支持在编译时显式选择 jemalloc：

# 系统分配器基线 + jemalloc 变体，在一次可重复的运行中同时测试
BENCH_ALLOCATORS_CSV=system,jemalloc \
  ./scripts/bench_extension_workloads.sh

基准测试框架会在其 JSONL 输出中记录请求的和实际使用的分配器元数据（allocator_requested、allocator_effective、allocator_fallback_reason），这些信息通过 PI_BENCH_ALLOCATOR 设置。

system：不启用分配器特性覆盖进行构建和运行；
jemalloc：使用 --features jemalloc 构建；
auto：优先使用 jemalloc，若构建失败则回退到 system。

如果请求使用 jemalloc 但当前构建无法启用，则运行将强制使用系统分配器，并在产物中注明回退原因。

内存使用情况

Rust 的所有权模型使得内存使用可预测，且无需垃圾回收停顿：

状态	内存
启动（空闲）	~15MB
活跃会话（小型）	~25MB
上下文中有大文件	~30-50MB
流式响应	+0MB（流式传输，不缓冲）

由于没有垃圾回收机制，流式输出过程中不会出现意外的延迟高峰。

流式架构

响应从 API 到终端以逐令牌的方式流式传输，几乎不进行缓冲：

API 服务器 → TCP → SSE 解析器 → 事件处理器 → 终端
     │                              │
     └──────── 无缓冲 ────────┘

每个令牌在离开 Anthropic 服务器后几毫秒内就会显示在屏幕上。SSE 解析器会实时处理到达的事件，而不会等待完整的响应。

TUI 渲染性能

交互式 TUI 的目标是实现 60 帧每秒的渲染，并采用了多层优化：

帧时间遥测：每个渲染周期都会被监控。耗时较长的帧（>16 毫秒）会被记录下来，并按阶段分类：视口同步、消息编码、Markdown 渲染。这些数据会输入到内部性能监控器中。

消息渲染缓存：Markdown 到 ANSI 的转换涉及语法高亮、表格布局和链接检测。Pi 会为每条消息缓存渲染结果，仅在主题更改或终端大小调整时才会失效。在流式传输过程中，只有正在变化的消息才会重新渲染；之前的所有消息都会命中缓存。

预分配的渲染缓冲区：RenderBuffers 结构会在各个渲染周期中重复使用。Pi 不会在每一帧都分配新的 String 缓冲区，而是将内容写入预先分配好的缓冲区，并在下次使用前清空它们，从而避免在流式传输过程中每秒产生数千次的小内存分配。

内存压力监控：MemoryMonitor 会采样进程堆大小，并将其分为三个等级：

等级	阈值	行动
正常	小于预算的 80%	无操作
压力	预算的 80%-95%	收起工具输出显示，隐藏思考提示框
严重	超过预算的 95%	截断旧消息，强制进行内存压缩

这种渐进式的降级策略能够在长时间会话且积累了大量工具输出时，保持 Pi 的响应速度。

故障排除

如需更完整的指南，请参阅 docs/troubleshooting.md。

“未找到 fd”

find 工具需要 fd：

# Ubuntu/Debian
apt install fd-find

# macOS
brew install fd

# 该二进制文件可能名为 fdfind
ln -s $(which fdfind) ~/.local/bin/fd

“未设置 API 密钥”

export ANTHROPIC_API_KEY="sk-ant-..."

# 或者在 settings.json 中
{ "apiKey": "sk-ant-..." }

# 或者针对单个命令
pi --api-key "sk-ant-..." "Hello"

“会话损坏”

会话是以追加方式写入的 JSONL 文件。如果发生损坏：

# 从头开始
pi --no-session

# 或者删除有问题的会话
rm ~/.pi/agent/sessions/--home-user-project--/corrupted-session.jsonl

“流式传输卡住”

请检查您的网络连接。Pi 使用 SSE 协议，需要稳定的连接：

# 使用 curl 测试
curl -N https://api.anthropic.com/v1/messages

“工具输出被截断”

这是为了防止上下文溢出而有意为之。您可以使用偏移量/限制参数：

# 在对话中
“读取那文件的第 2000 到 4000 行”

限制

Pi 对自身无法完成的功能坦诚相待：

限制	替代方案
并非支持所有提供商的 API	内置支持包括 Anthropic、OpenAI（Chat + Responses）、Gemini、Cohere、Azure OpenAI、Bedrock、Vertex AI、GitHub Copilot 和 GitLab Duo；一些特定生态系统的 API 仍在规划中
不支持网页浏览	可以使用 bash 结合 curl
无 GUI	设计上仅为终端界面
部分扩展需要 npm 存根	目前仍有 5 个 npm 包尚未适配；详情请参阅 EXTENSIONS.md 第 8.1 节
主要面向英语用户	虽然可以使用，但并未针对其他语言进行优化
需要 nightly Rust 版本	使用了 2024 年版的新特性

设计哲学

规范优先的移植

本次移植采用“规范提取”方法，而非逐行翻译：

提取行为：研究 TypeScript 实现，理解其“做什么”，而非“如何做”
记录规范：写下预期的行为、边界情况和不变量
根据规范实现：编写符合规范的 idiomatic Rust 代码
一致性测试：通过基于固定场景的测试验证行为是否一致

这种方法比机械翻译能产生更好的代码。TypeScript 的惯用模式（回调、Promise、类层次结构）与 Rust 的所有权模型、trait 和枚举并不完全对应。强行适应语言反而会降低代码质量，不如顺应语言特性来得更好。

一致性测试

测试套件包含基于固定场景的一致性测试，用于验证工具的行为：

{
  "version": "1.0",
  "tool": "edit",
  "cases": [
    {
      "name": "edit_simple_replace",
      "setup": [
        {"type": "create_file", "path": "test.txt", "content": "Hello, World!"}
      ],
      "input": {
        "path": "test.txt",
        "oldText": "World",
        "newText": "Rust"
      },
      "expected": {
        "content_contains": ["Successfully replaced"],
        "details": {"oldLength": 5, "newLength": 4}
      }
    }
  ]
}

每个场景指定了：

设置：测试前需要创建的文件或目录
输入：工具参数
期望结果：输出内容中的模式、字段精确匹配，或错误条件

这样就可以在不依赖具体实现细节的情况下，验证 Rust 实现是否与 TypeScript 原版一致。

扩展系统

Pi 通过嵌入的 QuickJS 运行时支持传统的 JS/TS 扩展。与传统的插件系统不同，扩展运行在一个 沙盒化、能力受限 的环境中，没有任何对操作系统的访问权限：

无需 Node/Bun：QuickJS 加上 Pi 提供的常见 Node API 适配层
基于能力的安全机制：每次调用主机连接器都会经过策略检查并记录日志
一致性测试：兼容性状态会在 docs/ext-compat.md 和 tests/ext_conformance/reports/pipeline/ 中跟踪
加载时间小于 100 毫秒：扩展加载时间通常低于 100 毫秒（P95），且无需 JIT 预热

遗留扩展的行为是自动化的：

现有的 .js/.ts 扩展可以直接运行（无需手动转换）。
*.native.json 描述文件是可选的，主要用于原生 Rust 运行时的工作流程。
当前一个会话只能使用一种运行时家族（JS/TS 或原生描述文件）。

政策预设快速入门：

# 查看当前生效的政策
pi --explain-extension-policy

# 为单个命令切换配置文件（safe | balanced | permissive）
pi --extension-policy balanced --explain-extension-policy

# 仍然接受旧的别名：
pi --extension-policy standard --explain-extension-policy

# 选择性启用危险能力（推荐优于 permissive）
PI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy

运营部署手册（以兼容性为主的本地默认设置 + 显式锁定）：

# 1) 基线：确认默认设置是兼容性优先（permissive）
pi --explain-extension-policy

# 2) 阶段性：使用 balanced 提示，危险能力仍默认拒绝
pi --extension-policy balanced --explain-extension-policy

# 3) 显式锁定，适用于严格的本地或 CI 环境
pi --extension-policy safe --explain-extension-policy

# 4) 选择性启用危险能力（推荐路径）
PI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy

# 5) 显式宽容模式，当你希望避免歧义时
pi --extension-policy permissive --explain-extension-policy

本地/开发环境的 settings.json 基线：

{
  "extensionPolicy": {
    "defaultPermissive": true
  }
}

使用以下配置可恢复更严格的默认行为，而无需命令行参数：

{
  "extensionPolicy": {
    "defaultPermissive": false
  }
}

交互式 TUI：打开 /settings 并切换 extensionPolicy.defaultPermissive。

CI 指导：

# CI 默认：保持危险能力禁用
pi --extension-policy safe --explain-extension-policy

# CI 可选任务（仅在必要时），保持明确且可审计
PI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy

回滚规则：移除 PI_EXTENSION_ALLOW_DANGEROUS，将 extensionPolicy.profile 恢复为 safe，或将 extensionPolicy.defaultPermissive 设置为 false，然后重新运行 pi --explain-extension-policy 以确认拒绝决策。

完整架构、运行时契约及合规性结果，请参阅 EXTENSIONS.md。

禁止不安全代码

#![forbid(unsafe_code)] 指令适用于整个项目，且不可更改。理由如下：

攻击面：Pi 会执行用户提供的 shell 命令并读取任意文件。
内存错误即安全漏洞：在此上下文中发生的缓冲区溢出或释放后使用等内存问题可能被利用。
性能无关紧要：瓶颈在于与 API 的网络延迟，而非 CPU 周期。
依赖项已审计：所有依赖项要么不使用不安全代码，要么经过充分审计（例如 rustls）。

安全的 Rust 子集提供了所有必要的功能，同时不会损害安全性。

常见问题解答

问：与原始 Pi Agent 有何关系？
答：这是由 Mario Zechner 授权的 Pi Agent 的 Rust 移植版，并得到了他的许可。其架构与 TypeScript 原版有显著不同：它使用 asupersync 实现结构化并发，并使用 rich_rust（Will McGugan 的 Rich 库的移植版）进行终端渲染。目标是在保留 Pi Agent 用户体验的同时，实现地道的 Rust 编程风格。

问：为什么要用 Rust 重写？
答：在终端中长时间工作时，启动时间至关重要。Rust 的启动时间不到 100 毫秒，而 Node.js 则需要 500 毫秒以上。此外，Rust 不需要管理运行时依赖。

问：除了 Anthropic 外，是否可以使用其他提供商（OpenAI/Gemini/Cohere/Azure/Bedrock/Vertex/Copilot/GitLab/Codex）？
答：是的。原生支持的提供商包括 Anthropic、OpenAI（Chat + Responses + Codex Responses）、Gemini（原生 + Gemini CLI + Antigravity 路由）、Cohere、Azure OpenAI、Amazon Bedrock、Vertex AI、GitHub Copilot 和 GitLab Duo。Pi 还支持许多与 OpenAI 兼容的预设模型（例如 Groq、OpenRouter、Mistral、Together、DeepSeek、Cerebras、DeepInfra、Alibaba/Qwen 以及 Moonshot/Kimi）。提供商 ID 和别名不区分大小写。通过 --provider/--model 设置凭据和选择模型；运行 pi --list-providers 查看规范 ID、别名和环境变量键。

问：会话是如何工作的？
答：每个会话是一个包含消息条目的 JSONL 文件。会话按项目划分（基于工作目录），并通过父引用支持分支。

问：为什么禁止不安全代码？
答：对于一个执行任意命令的工具来说，内存安全是不可妥协的。在这种场景下，性能开销可以忽略不计。

问：如何扩展 Pi？
答：Pi 拥有完整的扩展系统，包含两个运行时家族：JS/TS 入口点在嵌入式 QuickJS 中运行，而 *.native.json 描述符则在原生 Rust 描述符运行时中运行。两者都受到能力约束，并通过相同的策略系统进行审计。一次会话只能使用其中一个运行时家族。扩展可以注册工具、斜杠命令、事件钩子、标志以及自定义提供商。详细信息请参阅 EXTENSIONS.md。对于内置工具的修改，请在 src/tools.rs 中实现 Tool 特性。

问：为什么不包含 X 功能？
答：Pi 专注于核心编码辅助功能。诸如网页浏览、图像生成等功能不在其范围内。这些功能应使用专门的工具来完成。

问：压缩机制是如何工作的？
答：当对话超过模型的上下文窗口时，Pi 会使用 LLM 自身总结较早的消息，并将总结作为会话条目存储。最近的消息则原样保留。截断点会选择在一轮对话的边界处，总结中还会记录曾读取或修改过的文件，以便模型能够保持对这些信息的认知。压缩会在每次代理回复后自动触发（如需），也可以通过 /compact 手动触发。

问：能否添加 Pi 原生不支持的自定义提供商？
答：可以。在 ~/.pi/agent/ 或 .pi/ 目录下创建一个 models.json 文件，指定模型 ID、基础 URL 和 API 类型（通常为 openai-completions，用于与 OpenAI 兼容的端点）。Pi 的兼容性配置系统会处理字段名称差异和功能标志覆盖。扩展也可以注册完全自定义的提供商。

问：Pi 如何决定恢复哪个会话？
答：Pi 维护着一个 SQLite 索引，记录所有会话文件。当你运行 pi -c 时，它会查询索引，找到最近修改且工作目录与当前项目匹配的会话。这样可以避免每次恢复时扫描整个文件系统。

问：如果扩展尝试访问危险资源，会发生什么？
答：扩展发起的每个宿主调用在执行前都会根据当前的能力策略进行检查。在 safe 和 balanced 策略下，危险能力（如 exec、env）默认会被拒绝，除非显式启用（例如通过设置 PI_EXTENSION_ALLOW_DANGEROUS=1）。而在 permissive 策略下，则允许使用这些能力。对于 exec 调用，Pi 会在实际执行前进行命令中介：它会分类命令和参数签名，并默认阻止关键类别（例如递归删除、磁盘/设备写入、反向 Shell 等）。严格或安全策略还可以进一步阻止高级别的操作（例如关机、进程终止、修改凭证文件等）。被拒绝的调用会返回错误到扩展的 Promise 路径，拒绝事件也会记录在脱敏后的安全警报和命令中介审计日志中。敏感的环境变量（API 密钥、令牌、秘密）始终会被过滤。若行为升级，可以立即将该扩展隔离至“killed”状态，或强制将其路由到兼容通道，作为调查期间的遏制措施。

问：Pi 是否支持自托管或代理的 LLM？
答：是的。可以通过 models.json 将任何提供商指向自定义的基础 URL。Pi 会根据 API 类型规范化 URL 路径，并针对字段名称和功能差异应用兼容性覆盖。这适用于 vLLM、Ollama、LiteLLM 等与 OpenAI 兼容的服务器。

对比

特性	Pi	Claude Code	Aider	Cursor
语言	Rust	TypeScript	Python	Electron
启动时间	<100ms	~1s	~2s	~5s
内存占用	<50MB	~200MB	~150MB	~500MB
模型提供商	Anthropic + OpenAI/Responses + Gemini/Cohere + Azure/Bedrock/Vertex + Copilot/GitLab + 兼容OpenAI的预设	Anthropic	多家	多家
工具	8个内置	多种	文件优先	集成于IDE
会话管理	JSONL树	专有格式	基于Git	专有格式
开源	是	是	是	否

开发

构建

rch exec -- cargo build           # 调试构建（远程卸载）
rch exec -- cargo build --release # 发布构建（优化，远程卸载）
rch exec -- cargo test            # 运行测试（远程卸载）
# 静态检查（远程安全分割，避免rch clippy超时导致故障转移）
rch exec -- cargo clippy --lib --bins -- -D warnings
rch exec -- cargo clippy --tests -- -D warnings
rch exec -- cargo clippy --benches -- -D warnings
rch exec -- cargo clippy --examples -- -D warnings

测试

# 统一验证运行器（推荐用于生成确定性证据文件）
./scripts/e2e/run_all.sh --profile focused
./scripts/e2e/run_all.sh --profile ci
./scripts/e2e/run_all.sh --rerun-from tests/e2e_results/<timestamp>/summary.json --skip-unit

# 快速冒烟测试/扩展质量封装，并严格远程执行
./scripts/smoke.sh --require-rch
./scripts/ext_quality_pipeline.sh --require-rch

# 多智能体安全性：设置CODEX_THREAD_ID后，run_all默认将
# CARGO_TARGET_DIR指向target/agents/<CODEX_THREAD_ID>，除非被覆盖。若需自定义共享或隔离的目标目录，请显式设置CARGO_TARGET_DIR。

# 执行所有测试
rch exec -- cargo test

# 指定模块
rch exec -- cargo test tools::tests
rch exec -- cargo test sse::tests

# 符合性测试
rch exec -- cargo test conformance

专注验证工具：

# 发布构建前的开发阶段门控
rch exec -- cargo build --bin pi --bin ext_release_binary_e2e
PI_HTTP_REQUEST_TIMEOUT_SECS=0 rch exec -- \
  cargo run --bin ext_release_binary_e2e -- \
  --pi-bin target/debug/pi \
  --provider ollama --model qwen2.5:0.5b \
  --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced

# 门控通过后的完整优化发布二进制运行
rch exec -- cargo build --release --bin pi --bin ext_release_binary_e2e
PI_HTTP_REQUEST_TIMEOUT_SECS=0 target/release/ext_release_binary_e2e \
  --pi-bin target/release/pi \
  --provider ollama --model qwen2.5:0.5b \
  --jobs 10 --timeout-secs 600 --extension-policy balanced

# 运行时风险账本取证（验证、回放、校准）
rch exec -- cargo run --bin ext_runtime_risk_ledger -- verify --input path/to/runtime_risk_ledger.json
rch exec -- cargo run --bin ext_runtime_risk_ledger -- replay --input path/to/runtime_risk_ledger.json
rch exec -- cargo run --bin ext_runtime_risk_ledger -- calibrate --input path/to/runtime_risk_ledger.json --objective balanced_accuracy

ext_runtime_risk_ledger操作pi.ext.runtime_risk_ledger.v1工件（例如来自事件包导出）。

发布与发布

发布以标签驱动，必须与Cargo.toml版本一致。

标签格式：vX.Y.Z（允许预发布如vX.Y.Z-rc.N，但跳过crates.io发布）。
标签版本必须匹配Cargo.toml中的package.version。
依赖项发布顺序：asupersync → rich_rust → charmed-*（lipgloss、bubbletea、bubbles、glamour）→ pi_agent_rust。
.github/workflows/publish.yml在设置CARGO_REGISTRY_TOKEN时处理crates.io发布。

覆盖率

覆盖率使用cargo-llvm-cov：

# 一次性安装
cargo install cargo-llvm-cov --locked
rustup component add llvm-tools-preview

# 概要（最快）
cargo llvm-cov --all-targets --workspace --summary-only

# LCOV报告（用于CI/工件）
CI=true VCR_MODE=playback VCR_CASSETTE_DIR=tests/fixtures/vcr \
  cargo llvm-cov --all-targets --workspace --lcov --output-path lcov.info

# HTML报告（默认输出到target/llvm-cov/html）
cargo llvm-cov --all-targets --workspace --html

项目结构

精选核心模块（非详尽）：

src/
├── main.rs                # CLI入口点
├── lib.rs                 # 库导出
├── app.rs                 # 启动/模型选择辅助
├── agent.rs               # 智能体循环+事件编排
├── agent_cx.rs            # asupersync能力上下文连接
├── cli.rs                 # 参数解析
├── config.rs              # 配置
├── auth.rs                # API密钥/OAuth/AWS凭证存储
├── model.rs               # 消息/内容/流事件类型
├── provider.rs            # 提供者trait
├── provider_metadata.rs   # 规范提供者ID+路由默认值
├── models.rs              # 模型注册表+models.json覆盖
├── providers/
│   ├── anthropic.rs        # Anthropic Messages API
│   ├── openai.rs           # OpenAI Chat Completions
│   ├── openai_responses.rs # OpenAI Responses API
│   ├── gemini.rs           # Gemini API
│   ├── cohere.rs           # Cohere Chat API
│   ├── azure.rs            # Azure OpenAI
│   ├── bedrock.rs          # Amazon Bedrock Converse
│   ├── vertex.rs           # Google Vertex AI
│   ├── copilot.rs          # GitHub Copilot后端
│   ├── gitlab.rs           # GitLab Duo后端
│   └── mod.rs              # 提供者工厂+扩展桥接
├── tools.rs                # 内置工具实现
├── sse.rs                  # 流式SSE解析器
├── http/
│   ├── client.rs           # asupersync支持的HTTP客户端
│   ├── sse.rs              # HTTP SSE辅助
│   └── mod.rs
├── session.rs              # JSONL会话持久化/树操作
├── session_index.rs        # SQLite会话元数据索引/缓存
├── session_sqlite.rs       # 可选的sqlite会话后端
├── compaction.rs           # 上下文压缩算法
├── interactive.rs          # 交互式TUI应用循环/状态
├── interactive/            # Bubble Tea风格的TUI子模块
├── rpc.rs                  # RPC/stdio模式
├── extensions.rs           # 扩展协议+策略+安全
├── extensions_js.rs        # QuickJS运行时桥接+宿主调用
├── extension_dispatcher.rs # 宿主调用/工具调度管道
├── extension_preflight.rs  # 扩展兼容性扫描
├── extension_validation.rs # 扩展验证流水线衔接
├── resources.rs            # 技能/提示/主题/扩展加载
└── tui.rs                  # 终端UI渲染辅助

文档索引

以下每条记录包括文档名称、用途、核心要点及直接链接。

类别	涵盖内容	跳转
扩展生态系统	扩展架构、语料库、目录、一致性、兼容性	前往
核心运维与用户体验	治理、CI/QA 运维、快捷键、提示、打包、模型/配置用户体验、无缝迁移/认证	前往
提供商子系统	提供商审计、部署契约、对等性和修复工件	前往
质量保证、模式、安全与平台	发布/QA 运行手册、模式、安全基线、平台指南	前往

1. 扩展生态系统

docs/BRANCH_PROTECTION.md - 目的：定义分支保护策略和执行规则。核心要点：为确保主线完整性，CI 和评审门控是强制性的。链接：查看
docs/EXTENSION_CANDIDATES.md - 目的：列出待纳入和测试的候选扩展。核心要点：从这份长列表开始进行扩展的筛选工作。链接：查看
docs/EXTENSION_CAPTURE_SCENARIOS.md - 目的：定义扩展捕获与回放场景。核心要点：使用这些场景来实现扩展行为的确定性捕获。链接：查看
docs/EXTENSION_POPULARITY_CRITERIA.md - 目的：说明如何对扩展的受欢迎程度进行评分。核心要点：受欢迎程度的决策应遵循明确的排名标准。链接：查看
docs/EXTENSION_REFRESH_CHECKLIST.md - 目的：扩展语料库更新的操作检查清单。核心要点：按照此清单安全且可重复地更新语料库。链接：查看
docs/EXTENSION_SAMPLE.md - 目的：人类可读的示例扩展契约。核心要点：在编写新的扩展包时参考此文档。链接：查看
docs/EXTENSION_SAMPLING_MATRIX.md - 目的：定义扩展采样策略及分层。核心要点：测试覆盖率来源于此采样矩阵。链接：查看
docs/LEGACY_EXTENSION_RUNNER.md - 目的：解释旧版扩展运行时的行为与限制。核心要点：用于兼容性背景说明，而非新运行时设计。链接：查看
docs/PIJS_PROOF_REPORT.md - 目的：提供 PiJS 运行时属性的正式证明。核心要点：PiJS 在设计上消除了环境权限。链接：查看
docs/TEST_COVERAGE_MATRIX.md - 目的：将模块映射到测试套件及覆盖率状态。核心要点：这是覆盖率缺口仪表盘。链接：查看
docs/capability-prompts.md - 目的：记录能力提示的 UX 及政策语义。核心要点：提示是政策性产物，而非临时 UI。链接：查看
docs/ci-operator-runbook.md - 目的：面向维护者的 CI 操作手册。核心要点：在 CI 管道中发生故障时使用本手册进行响应。链接：查看
docs/conformance-operator-playbook.md - 目的：一致性测试活动的操作指南。核心要点：使用本 playbook 进行一致性测试，以获得可重复的结果。链接：查看
docs/coverage-baseline-map.json - 目的：机器可读的覆盖率基线映射。核心要点：自动化系统应以此作为覆盖率基线的事实来源。链接：查看
docs/development.md - 目的：面向贡献者的开发工作流程参考。核心要点：这是官方的本地开发设置指南。链接：查看
docs/e2e_scenario_matrix.json - 目的：机器可读的端到端场景矩阵。核心要点：端到端测试的范围及预期流程在此定义。链接：查看
docs/evidence-contract-schema.json - 目的：证据工件及日志的模式文件。核心要点：证据生产者必须符合此契约。链接：查看
docs/ext-compat.md - 目的：解释扩展兼容性态势及边界。核心要点：这是快速兼容性参考。链接：查看
docs/extension-api-matrix.json - 目的：扩展宿主与运行时调用的 API 表面矩阵。核心要点：通过此矩阵可一目了然地了解支持的扩展 API。链接：查看
docs/extension-architecture.md - 目的：深入探讨扩展运行时内部架构。核心要点：这是主要的扩展技术设计文档。链接：查看
docs/extension-artifact-provenance.json - 目的：扩展工件的溯源元数据。核心要点：此处跟踪工件的信任关系与 lineage。链接：查看
docs/extension-candidate-pool.json - 目的：机器可读的扩展候选池。核心要点：摄入/选择任务应从此池中读取。链接：查看
docs/extension-catalog.json - 目的：主扩展目录及其状态元数据。核心要点：这是官方的扩展清单。链接：查看
docs/extension-catalog.schema.json - 目的：验证扩展目录文档的模式文件。核心要点：目录更新必须通过此模式验证。链接：查看
docs/extension-code-search-inventory.json - 目的：跨扩展仓库的代码搜索结果清单。核心要点：将其用作原始搜索证据。链接：查看
docs/extension-code-search-summary.json - 目的：扩展代码搜索清单的汇总结果。核心要点：顶级代码搜索发现在此浓缩呈现。链接：查看
docs/extension-collections.json - 目的：按主题/范围对扩展集合进行分组。核心要点：集合级别的规划由此开始。链接：查看
docs/extension-compatibility-matrix.md - 目的：扩展运行时支持级别的兼容性矩阵。核心要点：在声称存在兼容性差距之前，请先查阅此矩阵。链接：查看
docs/extension-conformance-matrix.json - 目的：机器可读的扩展一致性测试结果。核心要点：这是自动化的一致性真值表。链接：查看
docs/extension-conformance-test-plan.json - 目的：扩展一致性测试的计划文件。核心要点：一致性测试的执行应遵循此计划。链接：查看
docs/extension-curated-list-summary.json - 目的：精选扩展子集的摘要。核心要点：用于快速做出精选语料库的决策。链接：查看
docs/extension-entry-scan.json - 目的：扩展入口点检测的扫描结果。核心要点：扩展入口假设在此得到验证。链接：查看
docs/extension-inclusion-list.json - 目的：扩展集合的明确纳入清单。核心要点：此清单控制哪些内容属于运行范围。链接：查看
docs/extension-individual-enumeration.json - 目的：每个扩展的详细枚举信息及元数据。核心要点：可在此深入查看单个扩展记录。链接：查看
docs/extension-license-report.json - 目的：扩展语料库的许可证审计结果。核心要点：许可证风险及状态在此被捕捉。链接：查看
docs/extension-master-catalog.json - 目的：权威上游扩展目录的快照。核心要点：这为全语料库同步及溯源检查提供了基准。链接：查看
docs/extension-npm-scan-summary.json - 目的：基于 npm 的扩展扫描输出摘要。核心要点：npm 扫描态势在此总结。链接：查看
docs/extension-onboarding-queue.json - 目的：扩展工作的机器可读入队列。核心要点：队列自动化应消费此文件。链接：查看
docs/extension-onboarding-queue.md - 目的：人类可读的扩展入队列及上下文。核心要点：这是操作员的队列看板。链接：查看
docs/extension-priority-summary.json - 目的：扩展优先级信号的汇总。核心要点：优先级汇总在此集中管理。链接：查看
docs/extension-priority.json - 目的：详细的扩展优先级评分数据。核心要点：每个扩展的优先级在此以机器可读的形式呈现。链接：查看
docs/extension-registry.md - 目的：记录扩展注册表模型及使用方式。核心要点：注册表的行为及期望在此定义。链接：查看
docs/extension-repo-search-summary.json - 目的：仓库级别扩展发现搜索的汇总。核心要点：仓库发现的结果在此整合。链接：查看
docs/extension-research-playbook.json - 目的：扩展研究工作流的机器可读 playbook。核心要点：研究的执行步骤及输出在此被形式化。链接：查看
docs/extension-runtime-threat-model.md - 目的：以运行时为中心的扩展威胁模型，包含控制措施和测试。核心要点：此模型将具体的运行时滥用路径与其缓解措施对应起来。链接：查看
docs/extension-sample.json - 目的：机器可读的扩展样本载荷/规范。核心要点：将其用作官方的样本 JSON 契约。链接：查看
docs/extension-tiered-corpus.json - 目的：用于扩展测试的分层语料库构成。核心要点：语料库的层级及成员资格在此定义。链接：查看
docs/extension-tiered-summary.json - 目的：分层语料库覆盖情况及数量的汇总。核心要点：语料库各层级的健康状况在此总结。链接：查看
docs/extension-troubleshooting.md - 目的：专门针对扩展运行时问题的故障排除指南。核心要点：遇到扩展失败或策略拒绝时，应从此处开始排查。链接：查看
docs/extension-validated-dedup.json - 目的：去重后的已验证扩展列表。核心要点：使用此列表可避免重复的扩展工件。链接：查看

2. 核心运维与用户体验

docs/flake-triage-policy.md - 目的：用于检测和分类处理测试不稳定性的策略。核心要点：所有不稳定性问题必须按照此标准进行分类和处理。链接：查看
docs/keybindings.md - 目的：交互式 TUI 的快捷键参考。核心要点：这是操作员的快捷键映射表。链接：查看
docs/models.md - 目的：模型目录的行为、选择及覆盖规则。核心要点：模型解析逻辑在此文档中详细说明。链接：查看
docs/non-mock-rubric.json - 目的：定义非模拟测试期望的标准。核心要点：使用此标准来确保真实行为证据的质量。链接：查看
docs/packages.md - 目的：软件包安装及内容规范。核心要点：软件包的使用方式和结构在此文档中定义。链接：查看
docs/asupersync-leverage-inventory.md - 目的：详细列出在 Pi 核心模块中，进一步利用 Asupersync 技术能够带来高价值的具体场景。核心要点：在引入继承的 AgentCx 或替换原始线程岛之前，请先从这里开始规划。链接：查看
docs/dropin-certification-contract.json - 目的：严格的即插即用认证合同及准入门槛。核心要点：严格意义上的替代性消息传递由该合同及其硬性门槛控制。链接：查看
docs/dropin-parity-gap-ledger.json - 目的：机器可读的已知即插即用兼容性差距及其严重程度记录。核心要点：未解决的严重或高危差距将阻止严格替代性消息的发布。链接：查看
docs/integrator-migration-playbook.md - 目的：从 TypeScript 版本的 Pi 迁移到 Rust 版本的 Pi 时，运营商/集成商的迁移与回滚操作指南。核心要点：使用此手册执行分阶段、基于证据的迁移流程。链接：查看
docs/parity-certification.json - 目的：机器可读的兼容性进度快照。核心要点：仅提供信息性状态；严格意义上的替代性发布声明仍由即插即用合同及兼容性差距的修复状态决定。链接：查看
docs/program-governance.md - 目的：关于路线图、准入条件及所有权的治理模式。核心要点：治理决策及其责任在此文档中明确界定。链接：查看
docs/prompt-templates.md - 目的：提示模板系统及使用指南。核心要点：可通过此文档管理可重用的提示行为。链接：查看
docs/sdk.md - 目的：SDK 使用指南及嵌入 Pi 程序的迁移手册。核心要点：使用此文档可以快速实现 TypeScript SDK 工作流到 Rust 等效代码的复制粘贴。链接：查看
docs/integrator-migration-playbook.md - 目的：面向下游集成商，从 TypeScript 版本的 Pi 迁移到 Rust 版本的 Pi 时的逐步迁移与兼容性验证操作手册。核心要点：遵循此手册可安全地执行并验证迁移决策是否可行。链接：查看

3. 提供者子系统

docs/provider-audit-evidence-index.json - 用途：提供商审计证据工件索引。核心要点：审计可追溯性由此索引开始。链接：查看
docs/provider-audit-reconciliation-ledger.json - 用途：提供商审计对账决策账本。核心要点：差异及解决方案均在此记录。链接：查看
docs/provider-auth-crosswalk.json - 用途：提供商身份验证别名/环境键对照表。核心要点：凭证解析映射集中于此。链接：查看
docs/provider-auth-failure-signatures.json - 用途：已知的提供商身份验证失败签名和指纹。核心要点：通过比对此目录可诊断身份验证失败原因。链接：查看
docs/provider-auth-playbook-validation.json - 用途：提供商身份验证 playbook 覆盖情况的验证结果。核心要点：此处衡量身份验证 playbook 的质量。链接：查看
docs/provider-auth-redaction-diagnostics.json - 用途：提供商身份验证脱敏行为的诊断信息。核心要点：脱敏的正确性及缺失部分在此记录。链接：查看
docs/provider-auth-troubleshooting.md - 用途：提供商身份验证问题故障排除指南。核心要点：遇到提供商密钥或身份验证问题时，应首先参考此文档。链接：查看
docs/provider-baseline-audit.json - 用途：机器可读的基础版提供商审计数据。核心要点：结构化的提供商基准证据存储于此。链接：查看
docs/provider-baseline-audit.md - 用途：叙述性的基础版提供商审计报告。核心要点：此处解释了提供商差距的高层次概况。链接：查看
docs/provider-canonical-id-policy.json - 用途：机器可读的规范提供商 ID 政策。核心要点：提供商 ID 规范化规则在此定义。链接：查看
docs/provider-canonical-id-policy.md - 用途：人类可读的规范提供商 ID 政策。核心要点：这是规范性的提供商命名政策。链接：查看
docs/provider-canonical-id-table.json - 用途：规范提供商 ID 查找表。核心要点：使用此表可进行确定性的提供商 ID 映射。链接：查看
docs/provider-cerebras-capability-profile.json - 用途：Cerebras 提供商能力简介。核心要点：Cerebras 的支持范围及约束条件在此列出。链接：查看
docs/provider-cerebras-setup.json - 用途：Cerebras 部署/配置契约。核心要点：使用此工件可配置 Cerebras。链接：查看
docs/provider-closure-truth-table.json - 用途：提供商审计状态的闭合真值表。核心要点：这是提供商闭合情况的记分牌。链接：查看
docs/provider-config-examples.json - 用途：机器可读的提供商配置示例。核心要点：自动化就绪的示例配置存储于此。链接：查看
docs/provider-config-examples.md - 用途：人类可读的提供商配置示例。核心要点：设置提供商时可从此处复制配置。链接：查看
docs/provider-discrepancy-classification.json - 用途：提供商差异类别的分类体系。核心要点：使用此模式可对提供商不匹配情况进行分类。链接：查看
docs/provider-discrepancy-ledger.json - 用途：具体的提供商差异账本。核心要点：差异的历史及状态在此追踪。链接：查看
docs/provider-gaps-audit-report.json - 用途：汇总的提供商差距审计报告。核心要点：提供商对等性差距在此量化。链接：查看
docs/provider-gaps-test-matrix.json - 用途：用于弥补提供商差距的测试矩阵。核心要点：缺少的提供商测试在此枚举。链接：查看
docs/provider-gate-compiler-report.json - 用途：编译器/构建检查生成的提供商门控报告。核心要点：此处显示编译时的提供商门控状态。链接：查看
docs/provider-gate-e2e-report.json - 用途：端到端测试生成的提供商门控报告。核心要点：提供商 E2E 门控结果在此记录。链接：查看
docs/provider-gate-tests-report.json - 用途：整合的提供商测试门控报告。核心要点：此处呈现提供商测试通过/失败的情况。链接：查看
docs/provider-gate-triage-matrix.json - 用途：提供商门控失败的分类与处理矩阵。核心要点：使用此矩阵可快速处理提供商门控失败问题。链接：查看
docs/provider-gate-ubs-report.json - 用途：UBS 扫描工具针对提供商门控运行的输出报告。核心要点：提供商中的漏洞扫描结果在此记录。链接：查看
docs/provider-groq-capability-profile.json - 用途：Groq 提供商能力简介。核心要点：Groq 的支持范围及限制在此定义。链接：查看
docs/provider-groq-setup.json - 用途：Groq 提供商部署契约。核心要点：按照此规范配置 Groq。链接：查看
docs/provider-implementation-modes.json - 用途：提供商实现模式分类。核心要点：通过此文件可了解哪些提供商是原生、桥接或模拟的。链接：查看
docs/provider-kimi-capability-profile.json - 用途：Kimi 提供商能力简介。核心要点：Kimi 的行为边界在此记录。链接：查看
docs/provider-kimi-setup.json - 用途：Kimi 提供商部署契约。核心要点：使用此契约可完成 Kimi 的集成部署。链接：查看
docs/provider-longtail-evidence.md - 用途：长尾提供商覆盖情况的证据报告。核心要点：长尾提供商的支持声明在此得到证实。链接：查看
docs/provider-migration-guide.md - 用途：提供商模型变更迁移指南。核心要点：迁移提供商集成时应遵循此指南。链接：查看
docs/provider-native-parity-report.json - 用途：原生提供商对等性状态报告。核心要点：原生对等性的进展在此衡量。链接：查看
docs/provider-onboarding-checklist.md - 用途：新增提供商的入驻检查清单。核心要点：所有新提供商的加入都必须通过此清单。链接：查看
docs/provider-onboarding-playbook.md - 用途：提供商入驻生命周期的操作手册。核心要点：这是端到端的入驻流程手册。链接：查看
docs/provider-openrouter-auth-contract.json - 用途：OpenRouter 身份验证行为契约。核心要点：OpenRouter 的身份验证解析必须符合此契约。链接：查看
docs/provider-openrouter-capability-profile.json - 用途：OpenRouter 能力简介。核心要点：OpenRouter 的功能边界在此记录。链接：查看
docs/provider-openrouter-dynamic-models-contract.json - 用途：OpenRouter 动态模型行为契约。核心要点：动态模型处理规则在此定义。链接：查看
docs/provider-openrouter-model-registry-contract.json - 用途：OpenRouter 模型注册表契约及期望。核心要点：注册表一致性要求在此规定。链接：查看
docs/provider-openrouter-setup.json - 用途：OpenRouter 部署/配置契约。核心要点：使用此工件可配置 OpenRouter。链接：查看
docs/provider-parity-checklist.json - 用途：提供商对等性关闭标准检查清单。核心要点：对等性完成的各个关卡在此编码。链接：查看
docs/provider-parity-reconciliation-report.json - 用途：提供商对等性对账报告。核心要点：对账结果及理由在此说明。链接：查看
docs/provider-parity-reconciliation.json - 用途：机器可读的对等性对账账本。核心要点：这是结构化的对等性对账记录。链接：查看
docs/provider-qwen-capability-profile.json - 用途：Qwen 提供商能力简介。核心要点：Qwen 的支持范围及约束条件在此记录。链接：查看
docs/provider-qwen-setup.json - 用途：Qwen 提供商部署契约。核心要点：使用此文件可配置 Qwen。链接：查看
docs/provider-remediation-manifest.json - 用途：提供商补救行动清单。核心要点：补救工作的积压及责任归属在此追踪。链接：查看
docs/provider-remediation-routing-validation.json - 用途：提供商补救路由逻辑的验证。核心要点：此处证明路由的正确性。链接：查看
docs/provider-support-baseline-audit.md - 用途：已声明的提供商支持情况的基础审计。核心要点：通过此次审计，支持声明得以证实。链接：查看
docs/provider-test-matrix-validation-report.json - 用途：提供商测试矩阵完整性的验证报告。核心要点：此处衡量提供商测试矩阵的健康状况。链接：查看
docs/provider-test-obligations.md - 用途：定义提供商特定的测试义务及门控条件。核心要点：这是提供商测试的契约。链接：查看
docs/provider-upstream-catalog-snapshot.json - 用途：上游提供商目录的机器可读快照。核心要点：从该快照开始检测上游变化。链接：查看
docs/provider-upstream-catalog-snapshot.md - 用途：上游提供商快照变化的叙述性摘要。核心要点：此处解释了上游提供商的变化。链接：查看
docs/provider_e2e_artifact_contract.json - 用途：提供商 E2E 证据的工件契约。核心要点：提供商 E2E 工件必须符合此规范。链接：查看
docs/providers.md - 用途：提供商架构、行为及使用参考。核心要点：这是主要的提供商子系统指南。链接：查看

4. 质量保证、模式、安全性和平台

docs/qa-runbook.md - 用途：跨套件和工件的 QA 操作手册。核心要点：用于可重复的 QA 执行。链接：查看
docs/releasing.md - 用途：发布流程及检查清单文档。核心要点：遵循此文档以实现一致、安全的发布。链接：查看
docs/rpc.md - 用途：RPC 模式协议及使用契约。核心要点：这是 RPC 的底层集成指南。链接：查看
docs/schema/extension_manifest.json - 用途：扩展清单的 JSON 模式。核心要点：扩展清单验证必须通过此模式。链接：查看
docs/schema/extension_protocol.json - 用途：扩展协议消息的 JSON 模式。核心要点：扩展消息契约在此处正式化。链接：查看
docs/schema/mock_spec.json - 用途：模拟/测试规范固定装置的模式。核心要点：模拟固定装置应符合此契约。链接：查看
docs/schema/runtime_hostcall_telemetry.json - 用途：运行时主机调用遥测事件的 JSON 模式。核心要点：主机调用遥测数据生产者必须符合此模式。链接：查看
docs/sec_traceability_matrix.json - 用途：机器可读的安全需求可追溯性矩阵。核心要点：此处跟踪安全覆盖和测试映射关系。链接：查看
docs/sec_traceability_matrix.md - 用途：包含需求与测试关联的叙述性安全可追溯性矩阵。核心要点：此处记录人类可读的安全覆盖状态。链接：查看
docs/security/baseline-audit.md - 用途：基于代码的安全基线审计及差距分析。核心要点：这是当前安全态势的快照。链接：查看
docs/security/incident-response-runbook.md - 用途：安全事件的应急响应流程。核心要点：在发生安全事件时遵循本手册。链接：查看
docs/security/incident-runbook.md - 用途：事件检测、分类和处理指南。核心要点：用于初始事件分诊和升级处理。链接：查看
docs/security/invariants.machine.json - 用途：可机器检查的安全不变量清单及测试映射。核心要点：不变量自动化应读取此文件。链接：查看
docs/security/invariants.md - 用途：规范性的安全不变量及优先级语义。核心要点：这是 SEC-1.2 政策/风险契约。链接：查看
docs/security/lockfile-format.md - 用途：用于验证扩展完整性的锁文件格式规范。核心要点：此处定义了锁文件结构及验证规则。链接：查看
docs/security/maintenance-playbook.md - 用途：安全维护程序及计划性操作。核心要点：用于日常安全维护和策略更新。链接：查看
docs/security/manifest-v2-migration.md - 用途：从旧版扩展清单迁移到 v2 安全字段的迁移指南。核心要点：使用此文档可在不丢失功能或策略意图的情况下升级清单。链接：查看
docs/security/operator-handbook.md - 用途：全面的安全运维手册。核心要点：这是日常工作的主要安全运维参考。链接：查看
docs/security/operator-quick-reference.md - 用途：安全运维人员快速参考卡。核心要点：在操作过程中使用此备忘录进行快速查询。链接：查看
docs/security/policy-tuning-guide.md - 用途：扩展安全策略及风险阈值的调整指南。核心要点：此处提供策略校准和调整流程。链接：查看
docs/security/runtime-hostcall-telemetry.md - 用途：运行时主机调用遥测设计及事件目录。核心要点：此处记录主机调用可观ability及事件语义。链接：查看
docs/security/security-slos.md - 用途：定量安全 SLO、风险预算以及发布/回滚门控。核心要点：安全发布的就绪状态在此处以数值形式进行门控。链接：查看
docs/security/threat-model.md - 用途：正式的扩展生态系统威胁模型。核心要点：这是 SEC-1.1 攻击者及控制基准。链接：查看
docs/session.md - 用途：会话模型、持久化及分支语义。核心要点：会话行为和存储契约在此处。链接：查看
docs/settings.md - 用途：设置模式、优先级及配置行为。核心要点：配置行为在此处被规范化。链接：查看
docs/skills.md - 用途：技能系统使用及打包指南。核心要点：通过已记录的技能契约扩展提示行为。链接：查看
docs/streaming-hostcalls.md - 用途：流式主机调用行为及生命周期细节。核心要点：可用于推断流式工具的执行情况。链接：查看
docs/terminal-setup.md - 用途：终端环境设置及人体工学指导。核心要点：推荐的终端配置在此处。链接：查看
docs/termux.md - 用途：针对 Termux 的特定设置及运行时指导。核心要点：Android/Termux 的使用在此处记录。链接：查看
docs/test_double_inventory.json - 用途：测试替身及模拟接口清单。核心要点：可通过此文件审计测试替身的使用情况。链接：查看
docs/testing-policy.md - 用途：测试政策、质量标准及测试套件期望。核心要点：这是规范性的测试治理文档。链接：查看
docs/themes.md - 用途：主题系统配置及自定义。核心要点：终端渲染主题在此处记录。链接：查看
docs/traceability_matrix.json - 用途：需求到测试的可追溯性矩阵。核心要点：需求证据的可追溯性信息保存于此。链接：查看
docs/tree.md - 用途：会话树导航及分支行为指南。核心要点：可用于理解对话树的操作。链接：查看
docs/troubleshooting.md - 用途：常见故障的一般故障排除指南。核心要点：非扩展相关的运维问题可从此处开始排查。链接：查看
docs/tui.md - 用途：TUI 行为、控件及渲染说明。核心要点：交互式 UI 语义在此处定义。链接：查看
docs/windows.md - 用途：Windows 特定的安装及运行时指导。核心要点：Windows 支持详情在此处集中。链接：查看
docs/wit/extension.wit - 用途：用于扩展宿主契约的 WIT 接口定义。核心要点：此处定义了类型化的扩展宿主 ABI。链接：查看

关于贡献

请不要误会，我目前不接受任何外部贡献。我真的没有精力去评审这些内容，而且项目上署的是我的名字，所以如果出现问题，责任也在我。从我的角度来看，这种风险与收益极不对等。此外，我还得考虑其他“利益相关方”，而对我这种主要为自己免费开发的工具来说，这样做并不明智。你仍然可以提交问题，甚至提出修复建议的拉取请求，但请理解，我不会直接合并它们。相反，我会让 Claude 或 Codex 通过 gh 工具来审查这些提交，并独立决定是否以及如何处理。尤其是漏洞报告，我们非常欢迎。如果这让你感到不适，我深表歉意，但我希望避免大家浪费时间或产生不必要的伤感。我也明白，这与当前倡导社区贡献的开源精神并不一致，但这是我能够保持现有开发速度并维持心理健康的方式。

许可证

MIT 许可证（附带 OpenAI/Anthropic 的附加条款）。详情请参阅 LICENSE 文件。

_{使用 Rust 构建，专为习惯在终端中工作的开发者打造。}

pi_agent_rust 快速上手指南

pi_agent_rust 是一个用 Rust 编写的高性能 AI 编程助手命令行工具。相比传统的 Node.js/Python 方案，它具有启动速度极快（<100ms）、内存占用极低（空闲时 <50MB）以及更强的安全扩展模型等优势。

环境准备

操作系统：支持 Linux、macOS 和 Windows (WSL)。
前置依赖：无需安装 Node.js、Python 或 Electron 运行时。该工具为单二进制文件，开箱即用。
网络要求：需要能够访问配置的 AI 模型提供商接口（如 OpenAI, Anthropic 等）。

安装步骤

推荐使用官方提供的一键安装脚本，自动下载最新发布的二进制文件并配置环境变量。

在终端中执行以下命令：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)" | bash

安装完成后，重启终端或运行 source ~/.bashrc (或 ~/.zshrc) 使 pi 命令生效。

注意：如果下载速度较慢，请检查本地网络环境或使用代理加速。目前项目暂未提供专门的国内镜像源，建议通过全局代理确保安装脚本顺利执行。

基本使用

安装成功后即可直接使用 pi 命令。以下是几种最常用的场景：

1. 启动交互式会话

直接输入 pi 进入交互模式，可以连续对话：

pi

2. 单次提问或任务

直接在命令后跟随提示词，获取结果后自动退出：

pi "Help me refactor this function to use async/await"

3. 结合文件上下文

使用 @ 符号引用本地文件，让 AI 基于具体代码进行分析：

pi @src/main.rs "Explain startup flow"

4. 管道输入模式

将其他命令的输出或日志文件传递给 AI 进行分析：

pi -p "What does this error mean?" < error.log

5. 继续之前的会话

自动加载上一次的项目会话记录，延续上下文：

pi --continue

6. 查看可用模型与提供商

列出当前配置支持的模型列表：

pi --list-models
pi --list-providers

版本历史

v0.1.102026/03/22

v0.1.92026/03/12

v0.1.82026/02/28

v0.1.62026/02/21

v0.1.42026/02/20

v0.1.32026/02/19

v0.1.22026/02/18

常见问题

如何在 macOS 上解决 Bash 进程卡死或变成僵尸进程（zombie mode）的问题？

该项目是否支持作为库（SDK）在其他 Rust 项目中以编程方式使用？

是否支持类似 oh-my-pi 的 hashline 编辑功能以提高大文件编辑的可靠性？

在执行 `/model` 命令后，模型选择列表溢出视口且滚动功能失效怎么办？

是否可以用 Rust 而不是 JavaScript 编写扩展插件？

项目是否提供 Nix flake 支持以便于在 Nix 环境中集成？

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|3天前

Agent开发框架图像

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|3天前

开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 146.8k|★★☆☆☆|今天

开发框架Agent语言模型

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 108.1k|★★☆☆☆|今天

开发框架图像Agent

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器

★ 93.4k|★★☆☆☆|2天前

插件开发框架

LLMs-from-scratch

LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。 LLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备

★ 90.1k|★★★☆☆|2天前

语言模型图像Agent

使用场景

没有 pi_agent_rust 时

使用 pi_agent_rust 后

运行环境要求

快速开始

pi_agent_rust

问题所在

解决方案

为什么你应该关注？

简而言之（Pi/OpenClaw 用户）

我们为何能如此迅速地完成开发

基准测试方法与声明的完整性

为什么选择 Pi？

快速示例

基础库

asupersync

rich_rust

快速开始

1. 安装

2. 配置 API 密钥

3. 运行

功能

流式响应

7 内置工具

会话管理

扩展思考模式

自定义（技能与提示模板）

自动补全

三种执行模式

扩展

凭证感知的模型选择

扩展验证流水线

设立原因

管道组件

推荐运行环境

最新运行快照（2026-02-19）

安装

Curl 安装程序（推荐）

分发兼容性契约（打包/调用范围）

从源码编译

依赖项

卸载

命令

基本用法

选项

子命令

配置

配置优先级

资源解析

环境变量

架构

关键设计决策

asupersync 上下文与 TypeScript Pi (pi-mono)

运行时不变量（及其重要性）

从 asupersync 带入 Pi 的设计原则

其他主要差异（原始 pi-mono 与 Rust 移植版）

算法机制：pi-mono 基线与 Rust 实现

功能超集亮点（超出 pi-mono 基线）

深度解析：核心算法

基于数学的决策系统

切换状态检测（CUSUM + BOCPD）

一致性预测区间

PAC-Bayes 安全边界

策略外评估（IPS/WIS/DR + ESS + 遗憾门控）

基于VOI的实验选择

加权瓶颈归因（基准测试）

$$ \text{weighted_contribution}_s

在线凸优化控制 + 损失跟踪

$$ \tau_{t+1}

数学概览

SSE流式解析器

截断算法

进程树管理

会话树结构

提供者抽象

压缩算法

多提供商路由与模型注册表

扩展宿主调用协议

扩展运行时决策逻辑（通俗解释）

交互式 TUI 架构