[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Dicklesworthstone--pi_agent_rust":3,"tool-Dicklesworthstone--pi_agent_rust":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",146793,2,"2026-04-08T23:32:35",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":120,"forks":121,"last_commit_at":122,"license":123,"difficulty_score":124,"env_os":125,"env_gpu":126,"env_ram":127,"env_deps":128,"category_tags":137,"github_topics":138,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":143,"updated_at":144,"faqs":145,"releases":175},5685,"Dicklesworthstone\u002Fpi_agent_rust","pi_agent_rust","High-performance AI coding agent CLI written in Rust with zero unsafe code","pi_agent_rust 是一款专为终端打造的高性能 AI 编程助手命令行工具。它由 Rust 语言从头重构，旨在解决现有 AI 辅助工具启动缓慢、内存占用高、运行不稳定以及难以扩展等痛点。相比基于 Node.js 或 Python 的传统方案，pi_agent_rust 实现了秒级即时启动，并在长时间会话中显著降低内存消耗，同时提供稳定可靠的流式输出体验。\n\n这款工具特别适合追求高效开发流程的程序员、系统架构师以及对安全性和性能有严苛要求的技术团队。它不仅保留了原有 Pi Agent 的核心工作流，更在底层引擎上进行了全面升级。其独特的技术亮点包括：采用零不安全代码（zero unsafe code）编写，确保内存安全；内置结构化并发运行时与精美的终端渲染能力；以及构建了一套细粒度的安全模型，通过能力门控和策略执行，默认阻断危险的系统调用，为插件扩展提供企业级的安全防护。无论是日常代码重构、错误分析还是复杂的项目维护，pi_agent_rust 都能以单二进制文件的轻便形态，为用户提供极速且安全的智能编码支持。","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_pi_agent_rust_readme_38bb3d84ad22.webp\" alt=\"Pi Agent Rust\" width=\"600\"\u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">pi_agent_rust\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>pi_agent_rust - High-performance AI coding agent CLI written in Rust\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#why-should-you-care\">Why Should You Care?\u003C\u002Fa> •\n  \u003Ca href=\"#tldr-piopenclaw-users\">TL;DR\u003C\u002Fa> •\n  \u003Ca href=\"#benchmark-methodology-and-claim-integrity\">Methodology\u003C\u002Fa> •\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa> •\n  \u003Ca href=\"#features\">Features\u003C\u002Fa> •\n  \u003Ca href=\"#installation\">Installation\u003C\u002Fa> •\n  \u003Ca href=\"#commands\">Commands\u003C\u002Fa> •\n  \u003Ca href=\"#configuration\">Configuration\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Frust-2024%20edition-orange?logo=rust\" alt=\"Rust 2024\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT%20%2B%20Rider-blue\" alt=\"License: MIT + Rider\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Funsafe-forbidden-brightgreen\" alt=\"No Unsafe Code\">\n\u003C\u002Fp>\n\n```bash\n# Install latest release\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n---\n\n## The Problem\n\nYou want an AI coding assistant in your terminal, but existing tools are:\n- **Slow to start**: Node.js\u002FPython runtimes add 500ms+ before you can type\n- **Memory hungry**: Electron apps or heavy runtimes eat gigabytes\n- **Unreliable**: Streaming breaks, sessions corrupt, tools fail silently\n- **Hard to extend**: Closed ecosystems or complex plugin systems\n\n## The Solution\n\n**pi_agent_rust** is a from-scratch Rust port of [Pi Agent](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi) by [Mario Zechner](https:\u002F\u002Fgithub.com\u002Fbadlogic) (made with his blessing!). Single binary, instant startup, stable streaming, and 8 built-in tools.\n\nRather than a direct line-by-line translation, this port builds on two purpose-built Rust libraries:\n- **[asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync)**: A structured concurrency async runtime with built-in HTTP, TLS, and SQLite\n- **[rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust)**: A Rust port of [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) by [Will McGugan](https:\u002F\u002Fgithub.com\u002Fwillmcgugan), providing beautiful terminal output with markup syntax\n\n```bash\n# Start a session\npi \"Help me refactor this function to use async\u002Fawait\"\n\n# Continue a previous session\npi --continue\n\n# Single-shot mode (no session)\npi -p \"What does this error mean?\" \u003C error.log\n```\n\n## Why Should You Care?\n\nIf you already use Pi Agent, especially through OpenClaw, this project keeps the core workflow while upgrading the engine under the hood:\n\n- **Substantially faster in realistic end-to-end flows** (not synthetic microbenchmarks)\n- **Dramatically smaller memory footprint** in long-running sessions\n- **Materially stronger security model** for extension\u002Ftool execution, including command-level blocking of dangerous extension shell patterns\n\nSecurity is a first-class design goal here, not a bolt-on:\n\n- Capability-gated hostcalls (`tool`\u002F`exec`\u002F`http`\u002F`session`\u002F`ui`\u002F`events`)\n- Two-stage extension `exec` enforcement: capability gate first, then command mediation that blocks critical shell classes by default (for example recursive delete, disk\u002Fdevice writes, reverse shell) and can tighten to block high-tier classes in strict\u002Fsafe policy\n- Policy + runtime risk + quota enforcement on the execution path\n- Per-extension trust lifecycle (`pending` -> `acknowledged` -> `trusted` -> `killed`) with kill-switch audit logs and explicit operator provenance\n- Hostcall-lane emergency controls that can force compatibility-lane execution globally or for one extension when fast-lane behavior needs immediate containment\n- Structured concurrency via `asupersync` for more predictable cancellation\u002Flifecycle behavior\n- Auditable runtime signals\u002Fledgers and redacted security alerts for extension behavior\n\n## TL;DR (Pi\u002FOpenClaw Users)\n\nThese are the realistic secure-path numbers that matter most (large-session, end-to-end behavior):\n\n| Scenario | Rust total | Legacy Node total | Legacy Bun total | Rust advantage |\n|---|---:|---:|---:|---:|\n| Realistic 1M session | 250.29 ms | 1,238.67 ms | 700.52 ms | `4.95x` faster than Node, `2.80x` faster than Bun |\n| Realistic 5M session | 1,382.12 ms | 5,974.67 ms | 2,959.42 ms | `4.32x` faster than Node, `2.14x` faster than Bun |\n\n| Scenario | Rust RSS | Legacy Node RSS | Legacy Bun RSS | Rust memory advantage |\n|---|---:|---:|---:|---:|\n| Realistic 1M session | 67,572 KB | 820,380 KB | 875,092 KB | `12.14x` lower than Node, `12.95x` lower than Bun |\n| Realistic 5M session | 268,844 KB | 2,173,096 KB | 3,057,908 KB | `8.08x` lower than Node, `11.37x` lower than Bun |\n\nResume\u002Fopen responsiveness is also much better at scale:\n\n| Scenario | Rust open | Legacy Node open | Legacy Bun open | Rust advantage |\n|---|---:|---:|---:|---:|\n| 1M session resume | 17.59 ms | 119.76 ms | 50.83 ms | `6.81x` faster than Node, `2.89x` faster than Bun |\n| 5M session resume | 58.68 ms | 396.41 ms | 155.63 ms | `6.76x` faster than Node, `2.65x` faster than Bun |\n\nExtension runtime guarantees are also concrete:\n\n| Extension assurance signal | Why you should care |\n|---|---|\n| Two-stage `exec` guard (`exec` capability policy + command-level mediation + DCG\u002Fheredoc AST signals) | Dangerous shell intent is caught before spawn, including destructive payloads hidden in multiline wrappers |\n| Trust lifecycle + kill switch (`pending\u002Facknowledged\u002Ftrusted\u002Fkilled`) | You can quarantine an extension instantly, log who pulled the switch and why, and require explicit re-acknowledgement before restoring access |\n| Hostcall lane kill-switch controls (`forced_compat_global_kill_switch`, `forced_compat_extension_kill_switch`) | Fast-path regressions can be contained immediately by forcing compatibility-lane execution without disabling the extension system |\n| Deterministic hostcall reactor mesh (shard affinity, bounded SPSC lanes, backpressure telemetry, optional NUMA slab tracking) | Runtime behavior stays predictable under contention; queue pressure and routing decisions are observable instead of opaque |\n| Startup prewarm + warm isolate reuse for JS runtimes | Runtime creation overlaps startup and warm reuse keeps repeated extension runs low-latency without a Node\u002FBun process model |\n| Tamper-evident runtime risk ledger (`verify` \u002F `replay` \u002F `calibrate`) | Security decisions are hash-linked and can be replayed or threshold-tuned from real runtime traces |\n\nBottom line: for real Pi\u002FOpenClaw usage, the Rust version is faster, far more memory-efficient, and materially stronger on extension runtime safety under real workload pressure.\n\n\u003Csub>Data source: `BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md` (latest secure-path + full orchestrator checkpoints, 2026-02-19).\u003C\u002Fsub>\n\n## How We Made It So Fast\n\nIn this README, `we` means the project owner and collaborating coding agents.  \nThe speed gains come from runtime design, not one trick.\n\n| Technique | What we do | Runtime effect |\n|---|---|---|\n| Cold-start minimization | Single static binary, no Node\u002FBun runtime bootstrap, no JIT warmup, startup prewarm for extension runtime paths | Faster time-to-first-interaction |\n| Less copying on hot paths | `Arc`\u002F`Cow` message flow, zero-copy hostcall\u002Ftool payload handling, reduced clone-heavy provider\u002Fsession paths | Lower CPU and allocation pressure |\n| Deterministic dispatch core | Typed hostcall opcodes, fast-lane\u002Fcompat-lane routing, bounded shard queues with reactor-mesh telemetry | Better tail latency under concurrent extension load |\n| Efficient long-session storage | SQLite session index + v2 sidecar (segmented log + offset index) with O(index+tail) reopen path | Fast resume on large histories |\n| Streaming parser tuned for real networks | SSE parser tracks scanned bytes, handles UTF-8 tails, normalizes chunk boundaries, interns event-type strings | Lower streaming overhead and fewer parser stalls |\n| Safe fast-path controls | Shadow dual execution sampling, automatic backoff on divergence\u002Foverhead, compatibility-lane kill switches for containment | Keeps optimizations fast without silent behavior drift |\n| CI-level performance governance | Scenario matrices, strict artifact contracts, fail-closed perf gates | Regressions are caught before release |\n\nIf you want the full implementation inventory, see [Performance Engineering](#performance-engineering).\n\n## Benchmark Methodology and Claim Integrity\n\nThe benchmarks cited above are intentionally designed to be realistic, reproducible, and hard to game.\n\nWhat we measured:\n\n- **Matched-state workloads**: resume a large session and append the same 10 messages.\n- **Realistic E2E workloads**: resume + append + extension activity + slash-style state changes + forks + exports + compactions.\n- **Scale levels**: from `100k` up to `5M` token-class session states.\n- **Startup\u002Freadiness**: command-level readiness (`--help`, `--version`) separately from long-session workflows.\n\nHow we kept comparisons fair:\n\n- **Two scopes** in the benchmark report:\n  - apples-to-apples (`pi_agent_rust` vs legacy `coding-agent`)\n  - apples-to-oranges (legacy stack components included where legacy behavior is outsourced)\n- **Release-mode binaries** and repeated runs per matrix cell.\n- **No paid-provider noise** in core latency\u002Ffootprint tables (provider-call costs are excluded from these core comparisons).\n\nHow we kept claims honest:\n\n- **Security controls stayed on** during secure-path measurements (no policy\u002Frisk\u002Fquota bypasses for speed claims).\n- **Raw artifacts are preserved** (JSON\u002Ftrace\u002Ftime outputs) and called out in the benchmark report.\n- **Blockers are explicitly disclosed**: when direct legacy reruns were blocked by missing workspace deps, we state that and compare against prior validated legacy artifacts instead of pretending reruns succeeded.\n- **Interpretation notes are explicit**: the report distinguishes baseline sections vs fresh reruns so readers can see exactly which values came from which run set.\n- **Reproducibility over marketing**: methodology, caveats, and known limits are included alongside wins.\n\nIf you want full details, see:\n\n- `BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md` (methodology + results + caveats + raw artifact paths)\n\n## Why Pi?\n\n| Feature | Pi (Rust) | Typical TS\u002FPython CLI |\n|---------|-----------|----------------------|\n| **Startup** | \u003C100ms | 500ms-2s |\n| **Binary size** | \u003C22MB (CI-gated budget) | 100MB+ (with runtime) |\n| **Memory (idle)** | \u003C50MB | 200MB+ |\n| **Streaming** | Native SSE parser | Library-dependent |\n| **Tool execution** | Process tree management | Basic subprocess |\n| **Sessions** | JSONL with branching | Varies |\n| **Unsafe code** | Forbidden | N\u002FA |\n\n## Quick Example\n\n```bash\n# 1) Start an interactive session\npi\n\n# 2) Ask a codebase question\npi \"Summarize the architecture in src\u002F\"\n\n# 3) Attach a file inline\npi @src\u002Fmain.rs \"Explain startup flow\"\n\n# 4) Run single-shot mode for scripting\npi -p \"List likely regression risks for this diff\"\n\n# 5) Continue your last project session\npi --continue\n\n# 6) Inspect available models\u002Fproviders\npi --list-models\npi --list-providers\n```\n\n---\n\n## Foundation Libraries\n\n### asupersync\n\n[asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync) is a structured concurrency async runtime designed for applications that need predictable resource cleanup. Key features used by pi_agent_rust:\n\n- **Capability-based context (`Cx`)**: Async functions receive an explicit context that controls what they can do (HTTP, filesystem, time). This makes testing deterministic.\n- **HTTP client with TLS**: Built-in HTTP API with rustls, avoiding OpenSSL dependency hell\n- **Structured cancellation**: When a parent task cancels, all child tasks cancel cleanly. No orphaned futures.\n\n`pi_agent_rust` runs on `asupersync` end-to-end today (runtime + HTTP\u002FTLS + cancellation). Provider streaming uses a minimal HTTP client (`src\u002Fhttp\u002Fclient.rs`) feeding a custom SSE parser (`src\u002Fsse.rs`).\n\n### rich_rust\n\n[rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust) is a Rust port of Will McGugan's [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) Python library. It provides:\n\n- **Markup syntax**: `[bold red]error[\u002F]` renders as bold red text\n- **Tables**: ASCII\u002FUnicode table rendering with alignment and borders\n- **Panels**: Boxed content with titles\n- **Progress bars**: Animated progress indicators\n- **Markdown**: Terminal-rendered markdown with syntax highlighting\n- **Themes**: Consistent color schemes across components\n\nThe terminal UI uses rich_rust for all output formatting, providing the same visual quality as Rich-based Python tools.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# Install latest release binary\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\nIf you already have the original TypeScript `pi` installed, the installer asks\nwhether to make Rust Pi canonical as `pi` and automatically create `legacy-pi`\nfor the old command.\n\n### 2. Configure API Key\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n### 3. Run\n\n```bash\n# Interactive mode\npi\n\n# With an initial message\npi \"Explain this codebase structure\"\n\n# Read files as context\npi @src\u002Fmain.rs \"What does this do?\"\n```\n\n---\n\n## Features\n\n### Streaming Responses\n\nReal-time token streaming with extended thinking support:\n\n```\npi \"Write a quicksort implementation\"\n```\n\nWatch the response appear token-by-token, with thinking blocks shown inline.\n\n### 7 Built-in Tools\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `read` | Read file contents, supports images | Read src\u002Fmain.rs |\n| `write` | Create or overwrite files | Write a new config file |\n| `edit` | Surgical string replacement | Fix the typo on line 42 |\n| `bash` | Execute shell commands with timeout | Run the test suite |\n| `grep` | Search file contents with context | Find all TODO comments |\n| `find` | Discover files by pattern | Find all *.rs files |\n| `ls` | List directory contents | What's in src\u002F? |\n\nAll tools include:\n- Automatic truncation for large outputs (2000 lines \u002F 50KB)\n- Detailed metadata in responses\n- Process tree cleanup for bash (no orphaned processes)\n\n### Session Management\n\nSessions persist as JSONL files with full conversation history:\n\n```bash\n# Continue most recent session\npi --continue\n\n# Open specific session\npi --session ~\u002F.pi\u002Fagent\u002Fsessions\u002F--home-user-project--\u002F2024-01-15T10-30-00.jsonl\n\n# Ephemeral (no persistence)\npi --no-session\n```\n\nSessions support:\n- Tree structure for conversation branching\n- Model\u002Fthinking level change tracking\n- Automatic compaction for long conversations\n\n### Extended Thinking\n\nEnable deep reasoning for complex problems:\n\n```bash\npi --thinking high \"Design a distributed rate limiter\"\n```\n\nThinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`\n\n### Customization (Skills & Prompt Templates)\n\n- **Skills**: Drop `SKILL.md` under `~\u002F.pi\u002Fagent\u002Fskills\u002F` or `.pi\u002Fskills\u002F` and invoke with `\u002Fskill:name`.\n- **Prompt templates**: Markdown files under `~\u002F.pi\u002Fagent\u002Fprompts\u002F` or `.pi\u002Fprompts\u002F`; invoke via `\u002F\u003Ctemplate> [args]`.\n- **Packages**: Share bundles with `pi install npm:@org\u002Fpi-packages` (skills, prompts, themes, extensions).\n\n### Autocomplete\n\nPi provides context-aware autocomplete in the interactive editor:\n\n- **`@` file references**: Type `@` followed by a path fragment to attach file contents. The completion engine indexes project files (respecting `.gitignore`) via the `ignore` crate's `WalkBuilder`, capping at 5,000 entries.\n- **`\u002F` slash commands**: Built-in commands (`\u002Fhelp`, `\u002Fmodel`, `\u002Ftree`, `\u002Fclear`, `\u002Fcompact`, `\u002Fexit`) and user-defined prompt templates and skills all appear as completions.\n- **Fuzzy scoring**: Prefix matches rank above substring matches. Results are sorted by match quality, then by kind (commands > templates > skills > files > paths).\n- **Background refresh**: A background thread re-indexes the project file tree every 30 seconds, so completions stay current without blocking the input loop.\n\n### Three Execution Modes\n\nPi runs in three modes, each suited to different workflows:\n\n| Mode | Invocation | Use Case |\n|------|-----------|----------|\n| **Interactive** | `pi` (default) | Full TUI with streaming, tools, session branching, autocomplete |\n| **Print** | `pi -p \"...\"` | Single response to stdout, no TUI, scriptable |\n| **RPC** | `pi --mode rpc` | Headless JSON protocol over stdin\u002Fstdout for IDE integrations |\n\n**Interactive mode** provides the full experience: a multi-line text editor with history, scrollable conversation viewport, model selector (`Ctrl+L`), scoped model cycling (`Ctrl+P`\u002F`Ctrl+Shift+P`), session branch navigator (`\u002Ftree`), and real-time token\u002Fcost tracking.\n\n**Print mode** sends one message, streams the response to stdout, and exits. Useful for shell scripts and one-off queries.\n\n**RPC mode** exposes a line-delimited JSON protocol for programmatic control. Clients send commands (`prompt`, `steer`, `follow-up`, `abort`, `get-state`, `compact`) and receive streaming events. This is how IDE extensions and custom frontends integrate with Pi. See [RPC Protocol](#rpc-protocol) for the wire format.\n\n### Extensions\n\nPi supports two extension runtime families with capability-gated host connectors:\n\n- JS\u002FTS entrypoints run **without Node or Bun** in an embedded QuickJS runtime.\n- `*.native.json` descriptors run in the native-rust descriptor runtime.\n\n- Extension entrypoints are auto-detected:\n  - `.js\u002F.ts\u002F.mjs\u002F.cjs\u002F.tsx\u002F.mts\u002F.cts` run directly in embedded QuickJS (no descriptor conversion).\n  - `*.native.json` loads the native-rust descriptor runtime.\n  - One session currently uses one runtime family at a time (JS\u002FTS or native descriptor).\n- **Sub-100ms cold load** (P95), **sub-1ms warm load** (P99)\n- Node API shims for `fs`, `path`, `os`, `crypto`, `child_process`, `url`, and more\n- Capability-based security: extensions call explicit connectors (`tool\u002Fexec\u002Fhttp\u002Fsession\u002Fui`) with audit logging\n- Command-level exec mediation: dangerous shell signatures are classified and blocked before spawn, with redacted denial alerts and mediation ledger entries\n- Trust-state lifecycle and kill-switch controls with audited state transitions (`pending`\u002F`acknowledged`\u002F`trusted`\u002F`killed`)\n- Hostcall reactor mesh with deterministic shard routing, bounded queue backpressure, and optional NUMA-aware telemetry\n- Runtime prewarm path with warm isolate reuse so extension startup cost is mostly paid before the first prompt\n\n### Credential-Aware Model Selection\n\n- `\u002Fmodel` (or `Ctrl+L`) opens a selector focused on models that are ready to run with current credentials.\n- `Ctrl+P` and `Ctrl+Shift+P` cycle through the scoped model set without opening the overlay.\n- Provider IDs and aliases are matched case-insensitively in model selection and `\u002Flogin`.\n- Models that do not require configured credentials can run keyless.\n\nExtensions can register tools, slash commands, event hooks, flags, providers,\nand shortcuts. See [EXTENSIONS.md](EXTENSIONS.md) for the full architecture\nand [docs\u002Fextension-catalog.json](docs\u002Fextension-catalog.json) for the\n224-entry catalog with per-extension conformance status and perf budgets.\n\n## Extension Validation Pipeline\n\nThis project validates extension compatibility with a three-track pipeline:\n\n- **Vendored corpus (224)**: deterministic conformance, compatibility matrix, and scenario suites.\n- **Unvendored corpus (777)**: source acquisition and onboarding prioritization.\n- **Release-binary live-provider E2E**: real `target\u002Frelease\u002Fpi` execution against a non-mocked provider\u002Fmodel path.\n\n### Why this exists\n\n- Catch runtime\u002FAPI regressions in QuickJS host shims and capability policy.\n- Catch dangerous extension shell call patterns with real command mediation on the release binary path.\n- Verify extension behavior against real provider responses, not just fixture\u002Fmocked flows.\n- Keep extension support measurable instead of anecdotal.\n- Produce a prioritized queue for onboarding unvendored candidates into vendored conformance.\n\n### Pipeline components\n\n1. **Fetch unvendored source corpus**\n   - Binary: `ext_unvendored_fetch_run`\n   - Typical command:\n     - `cargo run --bin ext_unvendored_fetch_run -- run-all --workers 8 --no-probe`\n   - Purpose:\n     - Clones GitHub repos and unpacks npm tarballs into `.tmp-codex-unvendored-cache\u002F`\n     - Produces machine-readable acquisition status for all unvendored candidates\n   - Artifacts:\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Funvendored_fetch_probe_report.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Funvendored_fetch_probe_events.jsonl`\n\n2. **Run end-to-end validation orchestration**\n   - Binary: `ext_full_validation`\n   - Typical command:\n     - `cargo run --bin ext_full_validation --`\n   - Stages (in order):\n     1. `refresh_onboarding_queue` (runs `ext_onboarding_queue`)\n     2. `conformance_shard_0..N` (runs `ext_conformance_generated` sharded matrix)\n     3. `conformance_failure_dossiers`\n     4. `provider_compat_matrix`\n     5. `scenario_conformance_suite`\n     6. `auto_repair_full_corpus`\n     7. `differential_suite` (optional, enabled via `--run-diff`; npm diff via `--run-npm-diff`)\n   - Artifacts:\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Ffull_validation_report.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Ffull_validation_report.md`\n     - Plus stage-specific reports under `tests\u002Fext_conformance\u002Freports\u002F**`\n\n3. **Run dev-firstset live-provider gate (must pass before release build)**\n   - Binary: `ext_release_binary_e2e`\n   - Typical command:\n     - `cargo build --bin pi --bin ext_release_binary_e2e`\n     - `PI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Fdebug\u002Fext_release_binary_e2e --pi-bin target\u002Fdebug\u002Fpi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced --out-json tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json --out-md tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.md`\n   - Purpose:\n     - Proves the current codepath works end-to-end on a representative first-set before paying release-build cost.\n     - Serves as the promotion gate to full release-binary validation.\n   - Gate:\n     - Require `pass=20 \u002F total=20` with `fail=0`.\n   - Artifacts:\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.md`\n\n4. **Run full release-binary live-provider E2E (after step 3 passes)**\n   - Binary: `ext_release_binary_e2e`\n   - Typical command:\n     - `cargo build --release --bin pi --bin ext_release_binary_e2e`\n     - `PI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Frelease\u002Fext_release_binary_e2e --pi-bin target\u002Frelease\u002Fpi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --extension-policy balanced --out-json tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json --out-md tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.md`\n   - Purpose:\n     - Executes `target\u002Frelease\u002Fpi` directly for each selected extension case.\n     - Uses a live provider\u002Fmodel path (default `ollama` + `qwen2.5:0.5b`) to exercise non-mocked end-to-end behavior.\n     - Emits per-case stdout\u002Fstderr captures plus summary artifacts (`pi.ext.release_binary_e2e.v1`).\n   - Artifacts:\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.md`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Fcases\u002F*`\n\n5. **Aggregate and triage**\n   - `full_validation_report.json` combines:\n     - Stage-level pass\u002Ffail (`stageSummary`, `stageResults`)\n     - Corpus counts (`corpus`)\n     - Vendored conformance totals (`conformance`)\n     - Provider matrix totals (`providerCompat`)\n     - Scenario totals (`scenario`)\n     - Review queue + verdict classification (`reviewQueue`, `verdictCounts`)\n   - Important interpretation rule:\n     - `not_tested_unvendored` indicates unvendored candidates not yet in vendored conformance; this is inventory status, not a vendored regression.\n\n### Recommended run environment\n\nThese runs compile many crates and can be disk-heavy. Point Cargo artifacts and temp files to a large volume:\n\n```bash\nexport CARGO_TARGET_DIR=\"\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002F${USER:-agent}\"\nexport TMPDIR=\"\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002F${USER:-agent}\u002Ftmp\"\nmkdir -p \"$CARGO_TARGET_DIR\" \"$TMPDIR\"\n```\n\nThen run:\n\n```bash\ncargo run --bin ext_unvendored_fetch_run -- run-all --workers 8 --no-probe\ncargo run --bin ext_full_validation --\n```\n\n### Latest run snapshot (2026-02-19)\n\nFrom:\n- `tests\u002Fext_conformance\u002Freports\u002Fsharded\u002Fshard_0_report.json` (generated `2026-02-18T23:43:48Z`)\n- `tests\u002Fext_conformance\u002Freports\u002Fscenario_conformance.json` (generated `2026-02-18T23:11:57Z`)\n- `tests\u002Fext_conformance\u002Freports\u002Fparity\u002Ftriage.json` (generated `2026-02-18T23:12:13Z`)\n- `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json` (run `release-e2e-20260219T032439Z`)\n- `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json` (run `release-e2e-20260219T033502Z`)\n\n- Vendored matrix conformance: `manifest_count=224`, `tested=224`, `passed=224`, `failed=0`, `skipped=0`\n- Scenario suite conformance: `25\u002F25` passed (`0` fail, `0` error, `0` skip)\n- Differential parity triage sample: `22` match, `0` mismatch, `3` skip (`total=25`)\n- Dev first-set live-provider gate (`max_cases=20`, debug binaries): `20\u002F20` passed (`0` fail, `0` timeout)\n- Release-binary live-provider full run (optimized binaries, `jobs=10`, `timeout=600s`, `ollama` + `qwen2.5:0.5b`): `224\u002F224` passed (`0` fail, `0` timeout)\n\n---\n\n## Installation\n\n### Curl Installer (Recommended)\n\n```bash\n# Latest release\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n\n# Non-interactive + auto PATH update\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --easy-mode\n\n# Pin a release tag\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --version v0.1.0\n\n# Install from explicit artifact URL + checksum URL\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | \\\n  bash -s -- \\\n    --artifact-url \"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Freleases\u002Fdownload\u002Fv0.1.0\u002Fpi-linux-amd64.tar.xz\" \\\n    --checksum-url \"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Freleases\u002Fdownload\u002Fv0.1.0\u002FSHA256SUMS\"\n\n# Skip completion setup (CI\u002Fnon-interactive minimal install)\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | \\\n  bash -s -- --yes --no-completions\n```\n\nThe installer is idempotent and supports a migration path from TypeScript Pi:\n- Detect existing TS `pi` command\n- Prompt to install Rust Pi as canonical `pi`\n- Preserve old CLI behind `legacy-pi`\n- Record state for clean uninstall\u002Frestore\n\nNotable installer flags:\n- `--offline [TARBALL]`: enforce offline mode; optional local artifact path (`.tar.gz`, `.tar.xz`, `.zip`, or raw binary)\n- `--artifact-url`: force a specific release artifact URL\n- `--checksum` \u002F `--checksum-url`: override checksum source for explicit artifacts\n- `--sigstore-bundle-url`: override Sigstore bundle URL used by `cosign verify-blob`\n- `--completions auto|off|bash|zsh|fish`: force shell completion install target (`off` is equivalent to `--no-completions`)\n- `--no-completions`: disable completion installation\n- `--no-agent-skills`: skip automatic installation of the `pi-agent-rust` skill into `~\u002F.claude\u002Fskills\u002F` and `~\u002F.codex\u002Fskills\u002F`\n- `--no-verify`: skip checksum + signature verification (testing only)\n- `--artifact-url` without `--version` uses a synthetic tag for release mode only; if artifact download fails, install exits instead of attempting source fallback\n- Installer honors `HTTPS_PROXY` \u002F `HTTP_PROXY` for all network fetches\n\nBy default, the installer also installs a `pi-agent-rust` skill for both Claude Code and Codex CLI:\n- Claude Code: `~\u002F.claude\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md`\n- Codex CLI: `~\u002F.codex\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md` (or `$CODEX_HOME\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md` if `CODEX_HOME` is set)\n- During upgrades, installer-managed legacy pre-tool entries from older versions are removed automatically (idempotent, path-scoped, and non-destructive) when prior installer state is present.\n\nInstaller regression harness (options + checksum + signature + completions):\n\n```bash\nbash tests\u002Finstaller_regression.sh\n```\n\n### Distribution Compatibility Contract (Packaging\u002FInvocation Scope)\n\nFor drop-in adoption, packaging and invocation compatibility follows this contract:\n\n- This section covers packaging\u002Finvocation behavior only; strict functional drop-in replacement messaging is governed by the release certification gates in `docs\u002Fdropin-certification-contract.json`.\n\n- Canonical executable name is `pi` across release assets and installer-managed installs.\n- Installer-managed installs also create an `rpi` compatibility launcher when no conflicting `rpi` command already exists on your PATH.\n- Existing TypeScript `pi` installs can be migrated in place; the prior command is preserved as `legacy-pi`.\n- If you keep TypeScript `pi` as canonical (`--keep-existing-pi`), Rust Pi is installed as `pi-rust`.\n- On Apple Silicon, the installer prefers the native arm64 artifact even when launched from a Rosetta-translated shell.\n- Version-pinned installs are supported via `install.sh --version vX.Y.Z` for deterministic rollouts.\n- Every GitHub release ships platform binaries plus `SHA256SUMS` for integrity validation.\n\nRepresentative smoke checks:\n\n```bash\n# Canonical command should exist and execute\ncommand -v pi\npi --version\npi --help >\u002Fdev\u002Fnull\n\n# If a TS migration was performed, legacy command remains available\ncommand -v legacy-pi && legacy-pi --version\n```\n\n### From Source\n\nRequires Rust nightly (2024 edition features):\n\n```bash\n# Install Rust nightly\nrustup install nightly\nrustup default nightly\n\n# Clone and build\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust.git\ncd pi_agent_rust\ncargo build --release\n\n# Binary is at target\u002Frelease\u002Fpi\n.\u002Ftarget\u002Frelease\u002Fpi --version\n\n# To install system-wide (--locked ensures reproducible dependency resolution)\ncargo install --path . --locked\n```\n\n### Dependencies\n\nPi has minimal runtime dependencies:\n- `fd`: Required for the `find` tool (install via `apt install fd-find` or `brew install fd`)\n- `rg`: Required for the `grep` tool (install via `apt install ripgrep` or `brew install ripgrep`)\n\n### Uninstall\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Funinstall.sh\" | bash\n```\n\nBy default, uninstall removes installer-managed Rust binaries\u002Faliases and skill directories,\nthen restores a migrated TypeScript `pi` if one was preserved.\n\n---\n\n## Commands\n\n### Basic Usage\n\n```bash\npi [OPTIONS] [MESSAGE]...\n\n# Examples\npi                              # Start interactive session\npi \"Hello\"                      # Start with message\npi @file.rs \"Explain this\"      # Include file as context\npi -p \"Quick question\"          # Print mode (no session)\n```\n\nInteractive file references:\n- Type `@relative\u002Fpath` in the editor to attach a file’s contents (autocomplete inserts the `@` form).\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-c, --continue` | Continue most recent session |\n| `-r, --resume` | Open session picker UI |\n| `--session \u003CPATH>` | Open specific session file |\n| `--session-dir \u003CDIR>` | Override session storage directory for this run |\n| `--session-durability strict|balanced|throughput` | Tune persistence durability mode |\n| `--no-session` | Don't persist conversation |\n| `-p, --print` | Single response, no interaction |\n| `--mode text|json|rpc` | Output\u002Fprotocol mode |\n| `--provider \u003CNAME>` | Force provider for this run (aliases supported) |\n| `--model \u003CMODEL>` | Model to use (auto-select fallback: `anthropic\u002Fclaude-opus-4-5`, then `openai\u002Fgpt-5.1-codex`, then `google\u002Fgemini-2.5-pro`) |\n| `--thinking \u003CLEVEL>` | Thinking level: off\u002Fminimal\u002Flow\u002Fmedium\u002Fhigh\u002Fxhigh |\n| `--tools \u003CTOOLS>` | Comma-separated tool list |\n| `--api-key \u003CKEY>` | API key (or use provider-specific env vars such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) |\n| `--extension-policy safe|balanced|permissive` | Extension capability profile |\n| `--repair-policy off|suggest|auto-safe|auto-strict` | Extension auto-repair policy |\n| `--list-models [PATTERN]` | List available models (optional fuzzy filter) |\n| `--list-providers` | List canonical provider IDs, aliases, and auth env keys |\n| `--export \u003CPATH>` | Export session file to HTML |\n\nAdditional high-leverage flags:\n\n- `--no-migrations` to skip startup migration checks\n- `--explain-extension-policy` to print effective capability decisions and exit\n- `--explain-repair-policy` to print effective repair-policy resolution and exit\n\n### Subcommands\n\n```bash\n# Package management\npi install \u003Csource> [-l|--local]    # Install a package source and add to settings\npi remove \u003Csource> [-l|--local]     # Remove a package source from settings\npi update [source]                 # Update all (or one) non-pinned packages\npi list                            # List user + project packages from settings\n\n# Configuration\npi config                          # Show settings paths + precedence\n```\n\nMore utility subcommands:\n\n```bash\n# Extension catalog index + discovery\npi update-index\npi search \"git\"\npi info pi-search-agent\n\n# Environment and extension diagnostics\npi doctor\npi doctor --only sessions --format json\npi doctor .\u002Fpath\u002Fto\u002Fextension --policy safe --fix\n\n# Session storage migration (JSONL -> v2 sidecar store)\npi migrate ~\u002F.pi\u002Fagent\u002Fsessions --dry-run\npi migrate ~\u002F.pi\u002Fagent\u002Fsessions\n```\n\n- `update-index` refreshes extension index metadata used by `search` and `info`.\n- `search` and `info` let you discover and inspect extension metadata without leaving the CLI.\n- `doctor` checks config, directories, auth, shell setup, sessions, and extension compatibility.\n- `migrate` validates or creates the v2 session sidecar format for faster resume on larger histories.\n\n---\n\n## Configuration\n\nPi reads configuration from `~\u002F.pi\u002Fagent\u002Fsettings.json`:\n\n```json\n{\n  \"default_provider\": \"anthropic\",\n  \"default_model\": \"claude-opus-4-5\",\n  \"default_thinking_level\": \"medium\",\n\n  \"compaction\": {\n    \"enabled\": true,\n    \"reserve_tokens\": 8192,\n    \"keep_recent_tokens\": 20000\n  },\n\n  \"retry\": {\n    \"enabled\": true,\n    \"max_retries\": 3,\n    \"base_delay_ms\": 1000,\n    \"max_delay_ms\": 30000\n  },\n\n  \"images\": {\n    \"auto_resize\": true,\n    \"block_images\": false\n  },\n\n  \"terminal\": {\n    \"show_images\": true,\n    \"clear_on_shrink\": false\n  },\n\n  \"shell_path\": \"\u002Fbin\u002Fbash\",\n  \"shell_command_prefix\": \"set -e\"\n}\n```\n\n### Configuration Precedence\n\nSettings are resolved in priority order (first match wins):\n\n1. **CLI flags** (`--model`, `--thinking`, `--provider`, etc.)\n2. **Environment variables** (`ANTHROPIC_API_KEY`, `PI_CONFIG_PATH`, etc.)\n3. **Project settings** (`.pi\u002Fsettings.json` in the working directory)\n4. **Global settings** (`~\u002F.pi\u002Fagent\u002Fsettings.json`)\n5. **Built-in defaults**\n\nThis means a CLI flag always overrides a `settings.json` value, and a project-level setting overrides the global one.\n\n### Resource Resolution\n\nSkills, prompt templates, themes, and extensions follow the same resolution order:\n\n1. CLI-specified paths (`--skill`, `--prompt-template`, `--theme`, `-e`)\n2. Project directory (`.pi\u002Fskills\u002F`, `.pi\u002Fprompts\u002F`, `.pi\u002Fthemes\u002F`, `.pi\u002Fextensions\u002F`)\n3. Global directory (`~\u002F.pi\u002Fagent\u002Fskills\u002F`, `~\u002F.pi\u002Fagent\u002Fprompts\u002F`, etc.)\n4. Installed packages (`~\u002F.pi\u002Fagent\u002Fpackages\u002F`)\n\nWhen multiple resources share the same name, the first occurrence wins. Collisions are logged as diagnostics.\n\n**Prompt template expansion** supports positional arguments: `$1`, `$2`, `$@` (all args), and slice syntax `${@:start}`, `${@:start:length}`. For example, a template invoked as `\u002Freview src\u002Fmain.rs --strict` receives `src\u002Fmain.rs` as `$1` and `--strict` as `$2`.\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `ANTHROPIC_API_KEY` | Anthropic API key |\n| `OPENAI_API_KEY` | OpenAI API key |\n| `GOOGLE_API_KEY` | Google Gemini API key |\n| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |\n| `COHERE_API_KEY` | Cohere API key |\n| `GROQ_API_KEY` | Groq API key (OpenAI-compatible) |\n| `DEEPINFRA_API_KEY` | DeepInfra API key (OpenAI-compatible) |\n| `CEREBRAS_API_KEY` | Cerebras API key (OpenAI-compatible) |\n| `OPENROUTER_API_KEY` | OpenRouter API key (OpenAI-compatible) |\n| `MISTRAL_API_KEY` | Mistral API key (OpenAI-compatible) |\n| `MOONSHOT_API_KEY` | Moonshot\u002FKimi API key (OpenAI-compatible) |\n| `DASHSCOPE_API_KEY` | DashScope\u002FQwen API key (OpenAI-compatible) |\n| `DEEPSEEK_API_KEY` | DeepSeek API key (OpenAI-compatible) |\n| `FIREWORKS_API_KEY` | Fireworks API key (OpenAI-compatible) |\n| `TOGETHER_API_KEY` | Together API key (OpenAI-compatible) |\n| `PERPLEXITY_API_KEY` | Perplexity API key (OpenAI-compatible) |\n| `XAI_API_KEY` | xAI API key (OpenAI-compatible) |\n| `PI_CONFIG_PATH` | Custom config file path |\n| `PI_CODING_AGENT_DIR` | Override the global config directory |\n| `PI_PACKAGE_DIR` | Override the packages directory |\n| `PI_SESSIONS_DIR` | Custom sessions directory |\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                           CLI (clap)                            │\n│  • Argument parsing    • @file expansion    • Subcommands       │\n└─────────────────────────────────┬───────────────────────────────┘\n                                  │\n┌─────────────────────────────────▼───────────────────────────────┐\n│                          Agent Loop                             │\n│  • Message history     • Tool iteration    • Event callbacks    │\n└────────┬──────────────────────┬──────────────────────┬──────────┘\n         │                      │                      │\n┌────────▼────────┐  ┌─────────▼──────────┐  ┌───────▼──────────┐\n│ Provider Layer  │  │  Tool Registry     │  │  Extension Mgr     │\n│ • Anthropic     │  │  • read  • bash    │  │  • QuickJS JS\u002FTS   │\n│ • OpenAI (Chat\u002F │  │  • write • grep    │  │  • Native descriptor│\n│   Responses)    │  │  • edit  • find    │  │    runtime          │\n│ • Gemini\u002FCohere │  │  • ls              │  │  • Capability policy│\n│ • Azure\u002FBedrock │  │  • ext-registered  │  │  • Node shims       │\n│ • Vertex\u002FCopilot│  │                    │  │  • Event hooks      │\n│ • GitLab\u002FExt    │  │                    │  │  • Runtime risk ctl │\n└────────┬────────┘  └─────────┬──────────┘  └───────┬──────────┘\n         │                     │                      │\n┌────────▼─────────────────────▼──────────────────────▼──────────┐\n│                     Session Persistence                         │\n│  • JSONL format (v3)   • Tree structure   • Session index\u002Fcache  │\n│  • Per-project dirs    • Optional SQLite backend                │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nCurrent native providers in `src\u002Fproviders\u002F` are `anthropic`, `openai`, `openai_responses`, `gemini`, `cohere`, `azure`, `bedrock`, `vertex`, `copilot`, and `gitlab`, with extension-provided `streamSimple` providers routed through the same agent loop.\n\n### Key Design Decisions\n\n1. **No unsafe code**: `#![forbid(unsafe_code)]` enforced project-wide\n2. **Streaming-first**: Custom SSE parser, no blocking on responses\n3. **Process tree management**: `sysinfo` crate ensures no orphaned processes\n4. **Structured errors**: `thiserror` with specific error types per component\n5. **Speed-oriented release profile**: LTO + strip + `opt-level = 3` for runtime performance\n\n### asupersync Context vs TypeScript Pi (pi-mono)\n\nThis Rust port preserves Pi's user experience, but intentionally changes the runtime substrate. The original TypeScript Pi (`pi-mono`, `packages\u002Fcoding-agent`) is built on Node.js + package-level abstractions. `pi_agent_rust` moves those same behaviors onto `asupersync` primitives so lifecycle guarantees are explicit in the runtime model.\n\n| Concern | TypeScript Pi (pi-mono baseline) | pi_agent_rust + asupersync |\n|---------|----------------------------------|----------------------------|\n| **Runtime model** | Node event loop + Promise\u002FAbortSignal conventions | `RuntimeBuilder` + explicit reactor and runtime handle |\n| **Async ownership** | Task lifetimes coordinated by framework\u002Flibrary code | Structured task ownership and explicit cross-thread channels (TUI\u002FRPC bridging) |\n| **Cancellation semantics** | Primarily API- and tool-layer conventions | Runtime-aware cancellation checks + bounded timeout handling in tools |\n| **I\u002FO capability shape** | Ambient Node APIs + extension layer policies | Capability-scoped context (`AgentCx` over `asupersync::Cx`) and explicit hostcall policy |\n| **HTTP streaming** | Provider\u002Fclient dependent | Purpose-built asupersync HTTP\u002FTLS client feeding custom SSE parser |\n| **Deterministic test hooks** | Conventional async test setup | asupersync test\u002Fruntime hooks used widely in unit\u002Fintegration tests |\n\nWhy this is useful in practice:\n- **More predictable failure behavior** during aborts\u002Ftimeouts because cancellation is checked in explicit loop boundaries and tool runners.\n- **Cleaner resource lifetimes** because the runtime, timers, and I\u002FO paths all share one concurrency substrate.\n- **Less hidden coupling** because the main invariants live in Rust types\u002Falgorithms rather than spread across framework conventions.\n\n### Runtime Invariants (and Why They Matter)\n\nThese are the concrete invariants we rely on in this implementation:\n\n1. **Turn-scoped agent lifecycle**\n   - The main loop emits `AgentStart`, `TurnStart`, `TurnEnd`, and `AgentEnd` in a stable order.\n   - Tool recursion is bounded by `max_tool_iterations` (default `50`) to avoid unbounded self-tool loops.\n   - Benefit: stable event ordering for TUI\u002FRPC consumers and predictable termination behavior.\n\n2. **Abort and timeout behavior is explicit**\n   - Agent abort checks happen at turn boundaries and around tool execution.\n   - `bash` timeout follows a clear escalation path: terminate process tree, grace period, then hard kill.\n   - Benefit: fewer \"hung\" sessions and reduced orphan-process risk during aggressive tool use.\n\n3. **Session writes are crash-resilient**\n   - JSONL saves write to a temp file and persist atomically.\n   - Session indexing uses SQLite WAL + lock file coordination for concurrent instances.\n   - Benefit: better durability and resume reliability under multi-process usage.\n\n4. **Compaction is threshold-driven and boundary-aware**\n   - Trigger: estimated context tokens exceed `context_window - reserve_tokens`.\n   - Cut-point logic prefers user-turn boundaries and preserves recent context budget.\n   - Benefit: compaction recovers context without collapsing near-term task continuity.\n\n5. **Capability policy is fail-closed and precedence-defined**\n   - Resolution order: per-extension deny -> global deny -> per-extension allow -> default caps -> mode fallback.\n   - Benefit: policy outcomes are explainable, deterministic, and auditable.\n\n6. **Streaming parser tolerates real network chunking**\n   - SSE parser handles CR\u002FLF variants, multi-line `data:` fields, partial UTF-8 tails, and end-of-stream flush.\n   - Benefit: incremental rendering remains robust across providers and network fragmentation.\n\n### Design Principles Carried From asupersync Into Pi\n\nThe following `asupersync` principles are reflected directly in `pi_agent_rust` architecture:\n\n- **Single async substrate**: runtime, timers, fs, and HTTP\u002FTLS all run on one coherent foundation.\n- **Explicit context threading**: `AgentCx` wraps `asupersync::Cx` at subsystem boundaries (agent\u002Ftools\u002Fsession\u002Frpc).\n- **Bounded operations over best-effort cleanup**: timeout paths and compaction thresholds are parameterized and enforceable.\n- **Determinism hooks for tests**: timer-driver aware sleeps and asupersync test helpers reduce nondeterministic flakiness.\n\nCompared to the original TypeScript implementation, this shifts more correctness responsibility into the runtime and core algorithms themselves, instead of relying primarily on ecosystem conventions.\n\n### Additional Major Deltas (Original pi-mono vs Rust Port)\n\nThis is a second comparison pass focused on high-impact architectural deltas and rationale.\n\n| Area | Original pi-mono (`packages\u002Fcoding-agent`) | `pi_agent_rust` | Why this divergence exists |\n|------|---------------------------------------------|------------------|----------------------------|\n| **Distribution model** | npm package (`npm install -g @mariozechner\u002Fpi-coding-agent`) | Single Rust binary (`pi`) | Remove Node runtime dependency and improve startup\u002Fdeployment portability |\n| **Execution surfaces** | Interactive + print + JSON mode + RPC + SDK | Interactive + print + JSON mode + RPC (+ Rust SDK documented in `docs\u002Fsdk.md`) | Strict drop-in parity remains release-gated; JSON\u002FRPC\u002FSDK claims must be backed by certification artifacts |\n| **Default built-in tool posture** | Defaults to `read\u002Fwrite\u002Fedit\u002Fbash` (others available) | Seven built-ins treated as first-class (`read\u002Fwrite\u002Fedit\u002Fbash\u002Fgrep\u002Ffind\u002Fls`) | Keep common code-navigation and shell workflows available without extra configuration |\n| **Extension trust model** | Extension\u002Fpackage model documented as full system access | Embedded runtime with capability-gated hostcalls and policy profiles | Reduce ambient authority and make extension behavior auditable\u002Fdeny-by-default |\n| **Session architecture emphasis** | JSONL tree session model and branch navigation | JSONL v3 tree + explicit session index (SQLite sidecar) + optional SQLite session backend | Faster resume\u002Flookups at scale and safer multi-instance coordination |\n| **Streaming transport stack** | Node runtime networking stack | Purpose-built HTTP\u002FTLS client + custom SSE parser on asupersync | Tighter control over chunking, parsing, and failure handling in long streams |\n| **Cancellation\u002Ftimeout mechanics** | Platform\u002Fevent-loop cancellation conventions | Explicit abort signaling, bounded tool iterations, process-tree termination | Minimize hangs\u002Forphans and make stop behavior deterministic under load |\n| **Runtime context model** | Framework-level conventions and extension APIs | Explicit `AgentCx`\u002F`asupersync::Cx` capability-scoped context threading | Make effect boundaries and testability first-class architectural constraints |\n\nPractical consequence of these deltas:\n- Extension\u002Fpackage workflows are compatible across both implementations.\n- The non-negotiable goal is strict drop-in replacement for pi-mono across all use cases.\n- Strict drop-in replacement language is release-gated by `docs\u002Fdropin-certification-contract.json` and open-gap status in `docs\u002Fdropin-parity-gap-ledger.json`.\n- `docs\u002Fparity-certification.json` is an informational snapshot and does not override release-gate policy for strict replacement claims.\n\n### Algorithmic Mechanics: pi-mono Baseline vs Rust Implementation\n\nThis section compares concrete implementation mechanics for equivalent high-level behavior.\n\n| Algorithm | pi-mono baseline mechanism | Rust implementation mechanism | Why the Rust variant exists |\n|-----------|-----------------------------|-------------------------------|-----------------------------|\n| **Session context rebuild after compaction** | `buildSessionContext()` emits compaction summary, then messages from `firstKeptEntryId` (pre-compaction path), then post-compaction entries | `to_messages_for_current_path()` uses the same ordering and adds a fallback if `first_kept_entry_id` is missing | Avoid silent context loss when compaction anchors are orphaned\u002Fcorrupted |\n| **JSONL persistence** | Incremental append (`appendFileSync`) plus full rewrite (`writeFileSync`) for migrations\u002Frewrites | Save via temp file + atomic persist\u002Freplace | Keep on-disk session state crash-resilient during save operations |\n| **Session discovery\u002Fresume** | Directory\u002Ffile scan and mtime sorting of JSONL files | SQLite session index sidecar + WAL + lock file + staleness-triggered full reindex | Bound resume lookup cost and coordinate concurrent processes |\n| **Compaction token accounting** | Uses assistant usage (`totalTokens` else `input+output+cacheRead+cacheWrite`) plus heuristic trailing estimates | Uses assistant usage (`total_tokens` else `input+output`) plus heuristic trailing estimates; fixed image token estimate | Keep accounting stable across providers with uneven cache-token reporting while staying conservative |\n| **Cut-point + split-turn handling** | Valid cut points exclude tool results; split turns are summarized as history + turn-prefix context | Same cut-point class and split-turn strategy, implemented in Rust entry\u002Fmessage model | Preserve tool-call\u002Fresult adjacency and turn coherence under budget pressure |\n| **Bash timeout\u002Fprocess cleanup** | Timeout\u002Fabort kills process tree (`killProcessTree`) and returns tail-truncated output | Timeout escalation (`TERM` then grace then `KILL`) + process-tree walk + shell exit trap + tail truncation | Enforce bounded cleanup and reduce descendant-process leaks from background jobs |\n| **Streaming event decoding** | Transport semantics are exposed (`sse`\u002F`websocket`\u002F`auto`); parser details are runtime-internal | Explicit SSE parser with BOM stripping, CR\u002FLF normalization, UTF-8 tail buffering, and flush-on-end | Make byte-to-event behavior deterministic and provider-SDK-independent |\n\n### Feature Superset Highlights (Beyond pi-mono Baseline)\n\nThe sections above compare mechanics. This section calls out concrete features present in this Rust port that are not part of the pi-mono baseline implementation model.\n\n| Rust-port feature | Why it is useful\u002Fcompelling |\n|-------------------|-----------------------------|\n| **`pi doctor` diagnostics command** (`text`\u002F`json`\u002F`markdown`, `--only`, `--fix`, extension compatibility checks) | Gives actionable environment + compatibility diagnostics, supports CI gating (non-zero on failures), and can auto-fix safe issues like missing dirs\u002Fpermissions |\n| **Capability-gated extension policy profiles** (`safe` \u002F `balanced` \u002F `permissive`) with per-extension overrides | Lets operators run shared extensions with explicit capability boundaries instead of ambient full-system access |\n| **Secret-aware extension env filtering** (`pi.env()` blocklist for keys\u002Ftokens\u002Fsecrets) | Reduces accidental credential exposure from extension code paths |\n| **Per-extension trust lifecycle + kill-switch audit trail** (`pending`\u002F`acknowledged`\u002F`trusted`\u002F`killed`, `kill_switch`, `lift_kill_switch`) | Supports immediate containment, explicit operator provenance, and controlled re-entry after review |\n| **Hostcall compatibility-lane emergency controls** (global\u002Fper-extension forced-compat switches + reason codes) | Gives operators a deterministic rollback path for fast-lane incidents without losing extension availability |\n| **Runtime risk controller for extension hostcalls** (configurable, fail-closed by default) | Adds another enforcement layer beyond static policy for suspicious runtime behavior in extension call flows |\n| **Argument-aware runtime risk scoring for shell paths** (`dcg_rule_hit`, `dcg_heredoc_hit`, heredoc AST inspection across Bash\u002FPython\u002FJS\u002FTS\u002FRuby) | Detects destructive intent hidden in multiline scripts and wrapper commands before hostcall execution |\n| **Tamper-evident runtime risk ledger tooling** (`ext_runtime_risk_ledger verify|replay|calibrate`) | Security decisions are hash-chained and can be verified, replayed, and threshold-calibrated from real traces |\n| **Unified incident evidence bundle export** (risk ledger, security alerts, hostcall telemetry, exec mediation, secret-broker events) | Incident response can triage from one structured artifact set instead of stitching ad-hoc logs |\n| **Deterministic hostcall reactor mesh with optional NUMA slab pool** (shard affinity, global-order drain, bounded SPSC lanes, telemetry) | Keeps extension dispatch predictable under load and surfaces queue\u002Fbackpressure behavior for tuning |\n| **Warm isolate pool + startup prewarm handoff** | Moves JS runtime preparation off the first interactive turn and reuses warmed state safely between runs |\n| **Extension preflight static analysis** (imports\u002Fforbidden-pattern scan with policy-aware hints) | Catches risky extension patterns before runtime execution |\n| **Node\u002FBun-compatible extension runtime without Node\u002FBun dependency** (embedded QuickJS + shims) | Runs legacy extension workflows in a single native binary deployment model |\n| **Extension compatibility scanner + conformance harness** | Makes extension support measurable and auditable instead of anecdotal |\n| **SQLite session index sidecar** (WAL + lock + stale reindex path) | Gives fast session resume\u002Flist operations at scale without scanning every JSONL file on each query |\n| **Session Store V2 rollback and migration ledger** (segmented log + checkpoints + rollback events) | Long-session recovery can unwind to a known checkpoint with explicit migration\u002Frollback provenance |\n| **Optional SQLite session storage backend** (`sqlite-sessions` feature) | Supports deployments that want database-backed session persistence in addition to JSONL |\n| **Crash-resilient session save path** (temp file + atomic persist) | Improves session-file durability during writes and reduces partial-write failure modes |\n| **Unified hostcall dispatcher with typed taxonomy mapping** (`timeout` \u002F `denied` \u002F `io` \u002F `invalid_request` \u002F `internal`) | Produces consistent extension\u002Fruntime error semantics and easier client handling |\n| **Fail-closed evidence-lineage gates** (`run_id`\u002F`correlation_id` + cross-artifact lineage checks) | Rejects stale or cherry-picked conformance\u002Fperf artifacts at release-gate time |\n| **Structured auth diagnostics with stable machine codes** | Improves troubleshooting and operational visibility without leaking sensitive credential material |\n\n---\n\n## Deep Dive: Core Algorithms\n\n### Math-Driven Decision Systems\n\nPi deliberately uses advanced math where it improves runtime behavior or benchmark confidence. The goal is not “fancy formulas in docs”; it is safer policy decisions, faster recovery from workload shifts, and more trustworthy performance attribution.\n\n### Regime-Shift Detection (CUSUM + BOCPD)\n\nIn the extension dispatcher, Pi combines CUSUM and Bayesian online change-point detection to detect load-regime changes early (for example when hostcall traffic suddenly spikes or stalls).\n\n$$\nS_t^+ = \\max\\left(0,\\;S_{t-1}^+ + (-z_t - k)\\right), \\quad\nS_t^- = \\max\\left(0,\\;S_{t-1}^- + (z_t - k)\\right)\n$$\n\n$$\nH(r)=\\frac{1}{\\lambda}, \\quad\nP(r_t=0 \\mid x_{1:t}) \\propto \\sum_r P(r_{t-1}=r)\\,H(r)\\,P(x_t \\mid r)\n$$\n\nIntuition: CUSUM catches persistent drift; BOCPD catches sudden regime changes without brittle fixed thresholds.\n\n### Conformal Prediction Envelope\n\nPi tracks nonconformity scores (absolute residuals from the running mean) and treats out-of-interval events as anomalies.\n\n$$\nq = \\text{score}_{\\lceil (n+1)\\cdot \\text{confidence} \\rceil - 1}, \\quad\n\\text{anomaly if } |x_t - \\mu_t| > q\n$$\n\nIntuition: thresholds adapt from recent behavior instead of hard-coding one static latency cutoff.\n\n### PAC-Bayes Safety Bound\n\nPi’s safety envelope includes a PAC-Bayes-kl bound over extension outcomes, and can veto aggressive optimization when the bound is too high.\n\n$$\n\\mathrm{kl}(\\hat q \\,\\|\\, q_{\\text{bound}})\\;\\le\\;\\frac{\\mathrm{KL}(Q\\|P)+\\ln\\!\\left(2\\sqrt{n}\u002F\\delta\\right)}{n}\n$$\n\nIntuition: this gives an explicit uncertainty-aware ceiling on true error risk before allowing more aggressive runtime behavior.\n\n### Off-Policy Evaluation (IPS\u002FWIS\u002FDR + ESS + Regret Gate)\n\nBefore approving policy moves, Pi evaluates candidate behavior from trace data:\n\n$$\nw_i=\\frac{\\pi(a_i\\mid x_i)}{\\mu(a_i\\mid x_i)}, \\quad\n\\hat V_{\\text{IPS}}=\\frac{1}{n}\\sum_i w_i r_i\n$$\n\n$$\n\\hat V_{\\text{WIS}}=\\frac{\\sum_i w_i r_i}{\\sum_i w_i}, \\quad\n\\hat V_{\\text{DR}}=\\frac{1}{n}\\sum_i\\left(\\hat r_i + w_i(r_i-\\hat r_i)\\right)\n$$\n\n$$\nN_{\\text{eff}}=\\frac{(\\sum_i w_i)^2}{\\sum_i w_i^2}, \\quad\n\\Delta_{\\text{regret}}=\\bar r_{\\text{baseline}}-\\hat V_{\\text{DR}}\n$$\n\nIntuition: Pi fails closed if sample support is weak, uncertainty is high, or estimated regret is above threshold.\n\n### VOI-Driven Experiment Selection\n\nThe VOI planner prioritizes probes that provide the most expected learning under a strict overhead budget.\n\n$$\n\\text{priority}_i \\propto \\frac{\\text{utility}_i}{\\text{overhead}_i}\n$$\n\nIntuition: run only the experiments that are likely to change decisions; skip stale or low-value probes.\n\n### Weighted Bottleneck Attribution (Benchmarking)\n\nFor phase-1 matrix benchmarking, Pi computes stage attribution weighted by realistic workload size (`session_messages`) and reports confidence intervals.\n\n$$\n\\text{weighted\\_contribution}_s\n=\n\\frac{\\sum_i w_i\\,m_{i,s}}{\\sum_i w_i\\,t_i}\\cdot 100,\n\\quad w_i=\\text{session\\_messages}_i\n$$\n\n$$\nn_{\\text{eff}}=\\frac{(\\sum_i w_i)^2}{\\sum_i w_i^2}, \\quad\n\\mathrm{CI}_{95}=\\mu \\pm 1.96\\sqrt{\\frac{\\sigma^2}{n_{\\text{eff}}}}\n$$\n\nIntuition: prioritize what dominates real end-to-end latency, not just isolated microbench hotspots.\n\n### Online Convex Control + Regret Tracking\n\nPi also includes an online tuner path for batch\u002Ftime-slice controls with explicit rollback behavior:\n\n$$\n\\tau_{t+1}\n=\n\\mathrm{clip}\\!\\left(\\tau_t - \\eta\\nabla_{\\tau}\\mathcal{L}_t,\\;\\tau_{\\min},\\tau_{\\max}\\right)\n$$\n\nIntuition: the system adapts continuously, but if instantaneous loss exceeds a rollback threshold it immediately returns to a safer profile.\n\n### Math At a Glance\n\n| Technique | Where in Pi | Why it helps |\n|----------|-------------|--------------|\n| CUSUM + BOCPD | Extension dispatcher regime detector | Detects traffic regime shifts early and robustly |\n| Conformal intervals | Safety envelope | Adaptive anomaly gating without static magic numbers |\n| PAC-Bayes bound | Safety envelope veto path | Fails closed when uncertainty\u002Frisk is too high |\n| IPS\u002FWIS\u002FDR + ESS | Off-policy evaluator | Approves policy changes only with adequate support |\n| VOI planning | Experiment scheduler | Uses overhead budget on highest-value probes |\n| Weighted attribution + CI | Phase-1 perf matrix reports | Ranks optimization work by realistic user impact |\n| OCO + regret rollback | Runtime controller | Adapts under load while bounding unsafe drift |\n\n### SSE Streaming Parser\n\nThe SSE (Server-Sent Events) parser is a custom implementation that handles Anthropic's streaming response format. Unlike library-based approaches, the parser operates as a state machine that processes bytes incrementally:\n\n```\nBytes → Line Accumulator → Event Parser → Typed StreamEvent\n```\n\n**Key characteristics:**\n\n| Property | Implementation |\n|----------|----------------|\n| **Buffering** | Zero-copy where possible; lines accumulated only when incomplete |\n| **Event types** | 12 distinct variants: MessageStart, ContentBlockStart, ContentBlockDelta, ContentBlockStop, MessageDelta, MessageStop, Ping, Error, and thinking-specific events |\n| **Error recovery** | Malformed events logged but don't crash the stream |\n| **Memory** | Fixed-size rolling buffer prevents unbounded growth |\n\nThe parser handles edge cases like:\n- Multi-line `data:` fields (concatenated with newlines)\n- Events split across TCP packet boundaries\n- The `event:` field appearing before or after `data:`\n- CRLF and LF line endings interchangeably\n\n### Truncation Algorithm\n\nLarge outputs from tools (file reads, command output, grep results) must be truncated to avoid exhausting the LLM's context window. The truncation algorithm preserves usefulness while staying within limits:\n\n```\n┌─────────────────────────────────────────┐\n│           Original Content              │\n│         (potentially huge)              │\n└─────────────────────────────────────────┘\n                    │\n                    ▼\n┌─────────────────────────────────────────┐\n│  HEAD: First N\u002F2 lines                  │\n│  ─────────────────────────              │\n│  [... X lines truncated ...]            │\n│  ─────────────────────────              │\n│  TAIL: Last N\u002F2 lines                   │\n└─────────────────────────────────────────┘\n```\n\n**Constants:**\n\n| Limit | Value | Rationale |\n|-------|-------|-----------|\n| `MAX_LINES` | 2000 | Balances context usage vs. completeness |\n| `MAX_BYTES` | 50KB | Prevents binary file accidents |\n| `GREP_MAX_LINE_LENGTH` | 500 chars | Truncates minified code |\n\nThe algorithm:\n1. Splits content into lines\n2. If line count exceeds `MAX_LINES`, takes first 1000 and last 1000\n3. Inserts a marker showing how many lines were omitted\n4. If byte count still exceeds `MAX_BYTES`, applies byte-level truncation\n5. Returns metadata indicating truncation occurred, enabling the LLM to request specific ranges\n\n### Process Tree Management\n\nThe `bash` tool must handle runaway processes, infinite loops, and fork bombs without leaving orphans. The implementation uses the `sysinfo` crate to walk the process tree:\n\n```rust\n\u002F\u002F Pseudocode for process cleanup\nfn kill_process_tree(root_pid: Pid) {\n    let system = System::new();\n    let children = find_all_descendants(root_pid, &system);\n\n    \u002F\u002F Kill children first (deepest first), then parent\n    for child in children.iter().rev() {\n        kill(child, SIGKILL);\n    }\n    kill(root_pid, SIGKILL);\n}\n```\n\n**Timeout behavior:**\n\n1. Command starts with configurable timeout (default 120s)\n2. Output streams to a rolling buffer in real-time\n3. On timeout: SIGTERM sent, 5s grace period, then SIGKILL\n4. Process tree walked and all descendants killed\n5. Exit code set to indicate timeout vs. normal termination\n\nTo avoid orphaned background jobs (e.g. `cmd &`), the bash script installs an `EXIT` trap that waits for any remaining child processes and then exits with the original command's status.\n\nThis prevents the common failure mode where killing a shell leaves its children running.\n\n### Session Tree Structure\n\nSessions use a tree structure rather than a flat list, enabling conversation branching (useful when exploring different approaches):\n\n```\n                    ┌─────────┐\n                    │ Message │ (root)\n                    │   #1    │\n                    └────┬────┘\n                         │\n                    ┌────▼────┐\n                    │ Message │\n                    │   #2    │\n                    └────┬────┘\n                         │\n              ┌──────────┼──────────┐\n              │                     │\n         ┌────▼────┐          ┌────▼────┐\n         │ Message │          │ Message │ (branch)\n         │   #3    │          │   #3b   │\n         └────┬────┘          └────┬────┘\n              │                    │\n         ┌────▼────┐          ┌────▼────┐\n         │ Message │          │ Message │\n         │   #4    │          │   #4b   │\n         └─────────┘          └─────────┘\n```\n\n**JSONL format (v3):**\n\nEach line is a self-contained JSON object with a `type` discriminator:\n\n```json\n{\"type\":\"session\",\"version\":3,\"cwd\":\"\u002Fproject\",\"created\":\"2024-01-15T10:30:00Z\"}\n{\"type\":\"message\",\"id\":\"a1b2c3d4\",\"parent\":\"root\",\"role\":\"user\",\"content\":[...]}\n{\"type\":\"message\",\"id\":\"e5f6g7h8\",\"parent\":\"a1b2c3d4\",\"role\":\"assistant\",\"content\":[...]}\n{\"type\":\"model_change\",\"id\":\"i9j0k1l2\",\"parent\":\"e5f6g7h8\",\"model\":\"claude-sonnet-4-20250514\"}\n```\n\nThe `parent` field creates the tree. Replaying a session walks the tree from root to the current leaf. Branching creates a new message with a different `parent` than the previous continuation.\n\n### Provider Abstraction\n\nThe `Provider` trait abstracts over different LLM backends:\n\n```rust\n#[async_trait]\npub trait Provider: Send + Sync {\n    fn name(&self) -> &str;\n    fn models(&self) -> &[Model];\n\n    async fn stream(\n        &self,\n        context: &Context,\n        options: &StreamOptions,\n    ) -> Result\u003Cimpl Stream\u003CItem = Result\u003CStreamEvent>>>;\n}\n```\n\n**Context structure:**\n\n```rust\npub struct Context {\n    pub system: Option\u003CString>,      \u002F\u002F System prompt\n    pub messages: Vec\u003CMessage>,       \u002F\u002F Conversation history\n    pub tools: Vec\u003CToolDef>,          \u002F\u002F Available tools with JSON schemas\n}\n```\n\n**StreamOptions:**\n\n```rust\npub struct StreamOptions {\n    pub model: String,\n    pub max_tokens: u32,\n    pub temperature: Option\u003Cf32>,\n    pub thinking: Option\u003CThinkingConfig>,  \u002F\u002F Extended thinking settings\n    pub stop_sequences: Vec\u003CString>,\n}\n```\n\nThis design allows adding new providers (OpenAI, Gemini) without modifying the agent loop. Each provider translates the common types to its wire format and emits a unified `StreamEvent` stream.\n\n### Compaction Algorithm\n\nLong conversations eventually exceed the model's context window. Pi's compaction algorithm reclaims space by summarizing older messages while preserving recent context.\n\nThe algorithm runs automatically after each agent turn when estimated token usage exceeds `context_window - reserve_tokens`:\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     Full Conversation                         │\n│  msg1 → msg2 → msg3 → ... → msgN-5 → msgN-4 → ... → msgN   │\n│  ├──── older messages ─────┤ ├─── recent messages ──────────┤ │\n│                                                              │\n│  Step 1: Find cut point at a valid turn boundary             │\n│  Step 2: LLM summarizes msgs 1..N-5 into compact paragraph  │\n│  Step 3: Store Compaction entry in session JSONL             │\n│  Step 4: Next agent call uses [summary] + msgs N-4..N       │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**Token estimation** uses a conservative `chars ÷ 4` heuristic for text and a flat 1,200 tokens per image. When an assistant message includes a `usage` field from the API, that measured value takes precedence over the heuristic.\n\n**Cut point selection** prefers boundaries between complete user-assistant turns. If the budget forces a mid-turn cut, the algorithm includes prefix messages from the split turn so the model retains context about what was being discussed at the boundary.\n\n**File operation tracking** extracts `read`, `write`, and `edit` tool calls from the messages being summarized. The compaction prompt includes these paths so the summary preserves awareness of which files were examined or modified:\n\n```\n\u003Cread-files>\nsrc\u002Fmain.rs\nsrc\u002Fconfig.rs\n\u003C\u002Fread-files>\n\n\u003Cmodified-files>\nsrc\u002Fauth.rs\n\u003C\u002Fmodified-files>\n```\n\n**Configurable parameters:**\n\n| Parameter | Default | Purpose |\n|-----------|---------|---------|\n| `reserve_tokens` | 8% of context window | Safety margin for response generation |\n| `keep_recent_tokens` | 10% of context window | Minimum recent context preserved |\n\nCompaction can also be triggered manually with `\u002Fcompact` in interactive mode or the `compact` RPC command.\n\n### Multi-Provider Routing & Model Registry\n\nPi routes model requests through a provider factory that resolves the correct backend implementation from a `(provider, model, api)` tuple.\n\n**Resolution flow:**\n\n```\nUser specifies --provider openai --model gpt-4o\n               │\n               ▼\n  ┌──────────────────────────┐\n  │  Provider Metadata Table  │  Maps \"openai\" → canonical ID,\n  │                           │  determines API type (Completions\n  │                           │  vs Responses vs custom)\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  URL Normalization         │  Appends \u002Fchat\u002Fcompletions,\n  │                            │  \u002Fresponses, or \u002Fchat depending\n  │                            │  on detected API type\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  Compat Config             │  Applies per-model overrides:\n  │                            │  system_role_name, max_tokens\n  │                            │  field name, feature flags\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  Provider Instance         │  Anthropic | OpenAI | Gemini\n  │                            │  Cohere | Azure | Bedrock | ...\n  └───────────────────────────┘\n```\n\n**`models.json` overrides**: Users can define custom providers in `~\u002F.pi\u002Fagent\u002Fmodels.json` or `.pi\u002Fmodels.json`. Each entry specifies a model ID, base URL, API type, and optional compat flags, letting you route to self-hosted models, proxies, or providers that Pi does not natively support.\n\n**Compat config** handles the differences between OpenAI-compatible APIs:\n\n| Override | Example | Purpose |\n|----------|---------|---------|\n| `system_role_name` | `\"developer\"` | o1 models use \"developer\" instead of \"system\" |\n| `max_tokens_field` | `\"max_completion_tokens\"` | Some models require a different field name |\n| `supports_tools` | `false` | Suppress tool definitions for models that reject them |\n| `supports_streaming` | `false` | Fall back to non-streaming for incompatible endpoints |\n| `custom_headers` | `{\"X-Custom\": \"val\"}` | Per-provider header injection |\n\n**Fuzzy matching**: When a provider name doesn't match any known provider, Pi computes edit distance against all registered names and suggests the closest match in the error message.\n\n### Extension Hostcall Protocol\n\nExtensions run in an embedded QuickJS runtime (`rquickjs` crate) and communicate with Pi through a structured hostcall protocol. This is the mechanism that lets JavaScript code invoke Pi's built-in tools, make HTTP requests, and interact with the session, all without direct OS access.\n\n**Execution model:**\n\n```\n┌─────────────────── QuickJS VM ───────────────────┐\n│                                                   │\n│  extension.js calls:                              │\n│    pi.tool(\"read\", {path: \"src\u002Fmain.rs\"})         │\n│      │                                            │\n│      ▼                                            │\n│    enqueue HostcallRequest {                      │\n│      call_id: \"hc-0042\",                          │\n│      kind: Tool { name: \"read\" },                 │\n│      payload: { path: \"src\u002Fmain.rs\" },            │\n│    }                                              │\n│      │                                            │\n│      ▼                                            │\n│    return Promise (resolve\u002Freject stored in map)  │\n│                                                   │\n└────────────────────────┬──────────────────────────┘\n                         │\n    drain_hostcall_requests()\n                         │\n                         ▼\n┌─────────────── ExtensionDispatcher ──────────────┐\n│                                                   │\n│  1. Check capability policy:                      │\n│     read tool → requires \"read\" capability        │\n│     → Policy says: Allow \u002F Deny \u002F Prompt          │\n│                                                   │\n│  2. If allowed → dispatch to ToolRegistry         │\n│     → Execute read tool                           │\n│     → Get ToolOutput                              │\n│                                                   │\n│  3. complete_hostcall(\"hc-0042\", Ok(result))      │\n│     → Resolves the Promise in QuickJS             │\n│                                                   │\n│  4. runtime.tick()                                │\n│     → Drains Promise .then() chains               │\n│     → Extension JS continues execution            │\n│                                                   │\n└───────────────────────────────────────────────────┘\n```\n\n**Capability mapping**: Each hostcall kind maps to a required capability:\n\n| Hostcall | Required Capability | Dangerous? |\n|----------|-------------------|------------|\n| `pi.tool(\"read\", ...)` | `read` | No |\n| `pi.tool(\"write\", ...)` | `write` | No |\n| `pi.tool(\"bash\", ...)` | `exec` | Yes |\n| `pi.http(request)` | `http` | No |\n| `pi.exec(cmd, args)` | `exec` | Yes |\n| `pi.env(key)` | `env` | Yes |\n| `pi.session(op, ...)` | `session` | No |\n| `pi.ui(op, ...)` | `ui` | No |\n| `pi.log(entry)` | `log` | No (always allowed) |\n\n**Deduplication**: Each hostcall's parameters are canonicalized (object keys sorted, structure normalized) and SHA-256 hashed. Identical requests within a short window can be deduplicated to avoid redundant tool executions.\n\n**Fast lane vs compatibility lane**: Pi has two execution lanes for hostcalls:\n\n- **Fast lane** is used when the call shape matches known safe patterns (for example common `tool` and `session` operations). This avoids extra allocation and parsing work.\n- **Compatibility lane** is the fallback for uncommon or partially-specified calls.\n- Both lanes still enforce the same capability policy and permission checks.\n- Operators can force compatibility-lane routing globally or per extension as an emergency control path.\n\nFor observability, each call is tagged with a stable lane key (for example `tool|tool.read|filesystem` or `tool|fallback|filesystem`) so latency and failure trends can be grouped consistently.\n\n**Built-in consistency guard (shadow dual execution)**: Pi can sample a small subset of read-only hostcalls, execute them through both lanes, and compare canonical output fingerprints. If divergence crosses a configured budget, Pi automatically backs off the fast lane for a period. This gives performance wins without silently changing behavior.\n\n**Adaptive dispatch mode under load**: Pi can switch between:\n\n- `sequential_fast_path` for simpler\u002Flow-contention workloads\n- `interleaved_batching` when contention and queue pressure rise\n\nMode changes are gated by sample coverage and risk checks, so Pi does not switch based on thin or cherry-picked evidence.\n\n**Runtime telemetry for debugging and tuning**: Pi records structured hostcall telemetry (`pi.ext.hostcall_telemetry.v1`) with lane choice, fallback reason, dispatch latency share, marshalling path, and optimization hit\u002Fmiss fields. This is used by perf reports and reliability diagnostics.\n\n**Auto-repair pipeline**: When an extension fails to load or produces runtime errors, Pi's repair system can automatically fix common issues:\n\n| Repair Mode | Behavior |\n|-------------|----------|\n| `Off` | No repairs |\n| `Suggest` | Log suggestions, don't apply |\n| `AutoSafe` (default) | Apply provably safe fixes (missing file paths, asset references) |\n| `AutoStrict` | Apply aggressive heuristic fixes (pattern-based transforms) |\n\n**Compatibility scanner**: Before loading, Pi statically analyzes extension source code for imports, `require()` calls, and forbidden patterns (`eval`, `Function()`, `process.binding`, `dlopen`). The scan produces a capability evidence ledger that informs policy decisions.\n\n**Environment variable filtering**: Extensions calling `pi.env()` hit a blocklist that denies access to API keys, credentials, tokens, and private keys. The filter blocks exact matches (`ANTHROPIC_API_KEY`, `AWS_SECRET_ACCESS_KEY`), suffix patterns (`*_API_KEY`, `*_SECRET`, `*_TOKEN`), and prefix patterns (`AWS_SECRET_*`, `AWS_SESSION_*`). Only `PI_*` variables are unconditionally allowed.\n\n**Trust lifecycle and kill switch**: Extension trust state is tracked explicitly (`pending`, `acknowledged`, `trusted`, `killed`). A kill switch demotes an extension to `killed`, quarantines it in the runtime risk controller, emits a critical alert, and writes an audit record. Lifting the switch requires an explicit operator action and moves the extension back to `acknowledged`.\n\n### Extension Runtime Decision Logic (Plain English)\n\nThe extension runtime includes a few small decision engines so behavior stays stable as workload patterns change:\n\n- **Value-of-information planner (VOI)**: Ranks candidate probes by \"expected learning per millisecond\" and picks the best set under a strict overhead budget. Stale or low-value candidates are skipped with explicit reasons.\n- **Shard load controller**: Adjusts routing weights, batch budgets, and backoff\u002Fhelp factors based on queue pressure, latency, and starvation risk. Damping and oscillation guards prevent overreaction.\n- **Policy safety evaluator**: Replays historical samples with multiple estimators and only approves a policy when sample support is strong, uncertainty is low, and predicted regret stays within limit.\n\nThese pieces are intentionally conservative: if confidence is weak, Pi holds steady instead of making an aggressive switch.\n\n### Interactive TUI Architecture\n\nThe interactive mode uses the **Elm Architecture** (Model-Update-View) via the `charmed_rust` library family, which is a Rust port of Go's [Bubble Tea](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) framework.\n\n**Component stack:**\n\n```\n┌────────────────────────────────────────────────────┐\n│                 Terminal (crossterm)                │\n│  Raw mode │ Alt screen │ Keyboard\u002FMouse events      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             bubbletea Program Loop                  │\n│  Init() → Update(Msg) → View() → render cycle      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│                  PiApp (Model)                      │\n│                                                     │\n│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐  │\n│  │  TextArea    │ │  Viewport    │ │  Spinner     │  │\n│  │  (editor)    │ │  (convo)     │ │  (status)    │  │\n│  └─────────────┘ └──────────────┘ └─────────────┘  │\n│                                                     │\n│  ┌─────────────────────────────────────────────┐    │\n│  │           Overlay Stack                      │    │\n│  │  Model Selector │ Session Picker │ \u002Ftree     │    │\n│  │  Settings UI    │ Theme Picker   │ Branches  │    │\n│  │  Capability Prompt (extension UI)            │    │\n│  └─────────────────────────────────────────────┘    │\n└──────────────────────┬─────────────────────────────┘\n                       │\n              async channels (mpsc)\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             Agent Async Task                        │\n│  Runs on asupersync runtime                         │\n│  Streams provider responses                         │\n│  Executes tools                                     │\n│  Sends PiMsg events back to TUI thread              │\n└────────────────────────────────────────────────────┘\n```\n\n**The async\u002Fsync bridge**: The agent runs on the `asupersync` async runtime in a separate thread. It communicates with the bubbletea UI thread through `mpsc` channels. Each streaming event (text delta, tool start, tool update, agent done) becomes a `PiMsg` variant delivered to `PiApp::update()`, keeping the UI responsive during API streaming and tool execution.\n\n**Viewport scrolling**: The conversation viewport tracks whether the user is at the bottom. When new content arrives and the user hasn't scrolled up, the viewport auto-follows the stream tail. Scrolling up disables auto-follow; pressing `End` or typing a new message re-enables it.\n\n**Overlay system**: Modal UIs (model selector, session picker, branch navigator, extension capability prompts) stack on top of the main conversation view. Each overlay captures keyboard input until dismissed. Only the topmost active overlay receives events.\n\n**Slash commands** available in the interactive editor:\n\n| Command | Action |\n|---------|--------|\n| `\u002Fhelp` | Show available commands and keybindings |\n| `\u002Fmodel` or `Ctrl+L` | Open model selector with fuzzy search |\n| `Ctrl+P` \u002F `Ctrl+Shift+P` | Cycle scoped models forward\u002Fbackward |\n| `\u002Ftree` | Browse and fork the conversation tree |\n| `\u002Fclear` | Clear conversation and start fresh |\n| `\u002Fcompact` | Trigger manual compaction |\n| `\u002Fthinking \u003Clevel>` | Change thinking level mid-conversation |\n| `\u002Fshare` | Export session to GitHub Gist |\n| `\u002Fexit` or `Ctrl+C` | Exit Pi |\n\n### RPC Protocol\n\nThe RPC mode (`pi --mode rpc`) exposes a line-delimited JSON protocol over stdin\u002Fstdout for programmatic integration. Each line is a self-contained JSON object.\n\n**Client → Pi (stdin):**\n\n```json\n{\"type\": \"prompt\", \"message\": \"Explain this function\", \"id\": \"req-001\"}\n{\"type\": \"steer\", \"message\": \"Focus on error handling\"}\n{\"type\": \"follow-up\", \"message\": \"Now add tests\"}\n{\"type\": \"abort\"}\n{\"type\": \"get-state\"}\n{\"type\": \"compact\", \"reserve\": 8192, \"keepRecent\": 20000}\n```\n\n**Pi → Client (stdout):**\n\n```json\n{\"type\": \"event\", \"event\": \"agent_start\", \"data\": {\"session_id\": \"...\"}}\n{\"type\": \"event\", \"event\": \"text_delta\", \"data\": {\"text\": \"The function\"}}\n{\"type\": \"event\", \"event\": \"tool_start\", \"data\": {\"tool\": \"read\", \"input\": {}}}\n{\"type\": \"event\", \"event\": \"tool_end\", \"data\": {\"tool\": \"read\", \"output\": {}}}\n{\"type\": \"event\", \"event\": \"agent_done\", \"data\": {\"usage\": {}}}\n{\"type\": \"response\", \"id\": \"req-001\", \"data\": {\"status\": \"ok\"}}\n```\n\n**I\u002FO architecture**: Two dedicated threads handle stdin reading and stdout writing, bridged to the async agent runtime via channels. The stdin thread retries on transient errors to prevent dropped input. The stdout thread flushes after every line to prevent buffering delays.\n\n**Message queuing**: While the agent is streaming a response, incoming messages are routed to one of two queues:\n\n| Queue | Behavior | Use Case |\n|-------|----------|----------|\n| **Steering** | Interrupts current response; processed on next turn | Course corrections |\n| **Follow-up** | Queued until current response completes | Sequential instructions |\n\nQueue modes (`All` or `OneAtATime`) control whether multiple queued messages are batched into a single turn or processed individually.\n\n**Extension UI over RPC**: When an extension requests user input (capability prompt, selection dialog), Pi emits an `extensionUiRequest` event. The client renders the prompt in its own UI and responds with an `extensionUiResponse` message. IDE extensions can then present native UI for capability decisions instead of falling back to terminal prompts.\n\n### Session Indexing\n\nSession resume (`pi -c` or `pi -r`) needs to find the most recent session for the current project without scanning every JSONL file on disk. Pi maintains a SQLite index (`session-index.sqlite`) that provides constant-time lookups.\n\n**Schema:**\n\n```sql\nCREATE TABLE sessions (\n    path            TEXT PRIMARY KEY,\n    id              TEXT NOT NULL,\n    cwd             TEXT NOT NULL,\n    timestamp       TEXT NOT NULL,\n    message_count   INTEGER NOT NULL,\n    last_modified   INTEGER NOT NULL,\n    size_bytes      INTEGER NOT NULL,\n    name            TEXT\n);\n```\n\n**Update lifecycle:**\n\n1. After saving a session JSONL file, Pi upserts its metadata into the index\n2. `pi -c` queries `WHERE cwd = ? ORDER BY last_modified DESC LIMIT 1`\n3. `pi -r` queries the same table and presents a picker sorted by recency\n\n**Concurrency**: A file-based lock (`session-index.lock`) serializes writes from concurrent Pi instances. Reads use WAL mode for non-blocking access.\n\n**Staleness-based reindexing**: If the index is older than a configurable threshold, Pi runs a full re-scan of the sessions directory to catch files created by other instances or manual edits. The re-scan keeps the index accurate without a centralized daemon.\n\n### Session Store V2 Sidecar (Large Session Fast-Path)\n\nPi also supports a v2 sidecar store next to JSONL sessions for faster resume and stronger corruption checks on long histories.\n\n**What it adds:**\n\n- Segmented append log files (instead of one ever-growing JSONL file)\n- Offset index rows for direct seeks and fast tail reads\n- Periodic checkpoints and a manifest snapshot\n- Migration ledger entries for auditability\n- Checkpoint-based rollback path with explicit rollback event logging\n\n**How resume works:**\n\n1. If a v2 sidecar exists and is fresh, Pi opens from the sidecar index + segments.\n2. If sidecar data is stale relative to the source JSONL, Pi falls back to JSONL parsing.\n3. If index data is missing\u002Fcorrupt but segments are valid, Pi rebuilds the index.\n\n**Integrity strategy:**\n\n- Segment frames carry payload and chain hashes.\n- Index rows store byte offsets plus CRC32C checksums.\n- Validation checks offset bounds, checksum matches, and frame\u002Findex alignment before trusting the sidecar.\n- Truncated trailing frames are recoverable during rebuild; non-EOF frame corruption fails closed instead of silently dropping data.\n\n**CLI support:**\n\n- `pi migrate \u003Cpath> --dry-run` validates migration without writing.\n- `pi migrate \u003Cpath>` performs JSONL-to-v2 migration and verifies parity.\n\n### Authentication & Credential Management\n\nBeyond simple API keys, Pi supports OAuth, AWS credential chains, service key exchange, and bearer-token auth. Credentials are stored in `~\u002F.pi\u002Fagent\u002Fauth.json` with file-locked access to prevent corruption from concurrent instances. Stored API keys can be literal strings, `$ENV:VAR_NAME` references, or `$CMD:shell command` \u002F `$COMMAND:shell command` sources that resolve trimmed stdout at request time.\n\n| Mechanism | Providers | Details |\n|-----------|-----------|---------|\n| **API Key** | Anthropic, OpenAI, Gemini, Cohere, and many OpenAI-compatible providers | Static key via env var or settings |\n| **OAuth** | Anthropic, OpenAI Codex, Google Gemini CLI, Google Antigravity, Kimi for Coding, GitHub Copilot, GitLab, and extension-defined OAuth providers | PKCE\u002Fstate-validated flow with automatic refresh; Kimi uses device flow |\n| **AWS Credentials** | Bedrock | Access key + secret + optional session token; region-aware |\n| **Service Key** | SAP AI Core | Client ID\u002Fsecret exchange for bearer token |\n| **Bearer Token** | Custom providers | Static token in auth storage |\n\n**OAuth token lifecycle:**\n\n1. User runs `pi` with an OAuth-configured provider\n2. Pi checks `auth.json` for an existing token\n3. If missing: opens browser to authorization URL, user authenticates, Pi receives authorization code, exchanges it for access + refresh tokens, stores both with expiry timestamp\n4. If expired but refresh token valid: exchanges refresh token for new access token, updates `auth.json`\n5. Bearer token attached to API requests\n\nGoogle CLI-style OAuth providers carry project metadata with the token payload. Pi preserves and refreshes that payload and can resolve project IDs from `GOOGLE_CLOUD_PROJECT` or local `gcloud` config when needed.\n\n**Credential status reporting**: `pi config` shows the status of each configured provider's credentials: `Missing`, `ApiKey`, `OAuthValid` (with time until expiry), `OAuthExpired` (with time since expiry), `AwsCredentials`, or `BearerToken`.\n\n**Diagnostic codes**: Auth failures produce specific diagnostic codes (`MissingApiKey`, `InvalidApiKey`, `QuotaExceeded`, `OAuthTokenRefreshFailed`, `MissingAzureDeployment`, `MissingRegion`, etc.) with context-specific error hints rather than generic messages.\n\n---\n\n## Tool Details\n\n### read\n\nRead file contents (optionally images):\n\n```\nInput: { \"path\": \"src\u002Fmain.rs\", \"offset\": 10, \"limit\": 50 }\n```\n\n- Supports images (jpg, png, gif, webp) with optional auto-resize\n- Streams file bytes in chunks with hard size limits to reduce peak memory usage\n- Applies defensive image decode limits to block decompression-bomb\u002FOOM inputs\n- Truncates at 2000 lines or 50KB\n- Returns continuation hint if truncated\n\n### bash\n\nExecute shell commands with timeout and output capture:\n\n```\nInput: { \"command\": \"cargo test\", \"timeout\": 120 }\n```\n\n- Default 120s timeout, configurable per-call\n- Set `timeout: 0` to disable the default timeout\n- Process tree cleanup on timeout (kills children)\n- Rolling buffer for real-time output\n- Full output saved to temp file if truncated\n\n### edit\n\nSurgical string replacement:\n\n```\nInput: { \"path\": \"src\u002Flib.rs\", \"old\": \"fn foo()\", \"new\": \"fn bar()\" }\n```\n\n- Exact string matching (no regex)\n- Fails if old string not found or ambiguous\n- Returns diff preview\n\n### grep\n\nSearch file contents:\n\n```\nInput: { \"pattern\": \"TODO\", \"path\": \"src\u002F\", \"context\": 2, \"limit\": 100 }\n```\n\n- Regex patterns supported\n- Context lines before\u002Fafter matches\n- Respects .gitignore\n\n### find\n\nDiscover files by pattern:\n\n```\nInput: { \"pattern\": \"*.rs\", \"path\": \"src\u002F\", \"limit\": 1000 }\n```\n\n- Glob patterns via `fd`\n- Sorted by modification time\n- Respects .gitignore\n\n### ls\n\nList directory contents:\n\n```\nInput: { \"path\": \"src\u002F\", \"limit\": 500 }\n```\n\n- Alphabetically sorted\n- Directories marked with trailing `\u002F`\n- Truncates at limit\n\n---\n\n## Performance Engineering\n\n### Why Rust Matters for CLI Tools\n\nCLI tools have different performance requirements than servers or GUI applications. The critical metric is **time-to-first-interaction**: how quickly can the user start typing after invoking the command?\n\n| Phase | TypeScript\u002FNode.js | Rust |\n|-------|-------------------|------|\n| Process spawn | ~10ms | ~10ms |\n| Runtime initialization | 200-500ms | 0ms (no runtime) |\n| Module loading | 100-300ms | 0ms (static linking) |\n| JIT warmup | 50-100ms | 0ms (AOT compiled) |\n| **Total** | **360-910ms** | **~10ms** |\n\nThis difference compounds with usage frequency, especially in short iterative terminal workflows.\n\n### Extreme Optimization Playbook\n\nPi is optimized more like a low-latency engine than a typical CLI app. We intentionally apply aggressive optimization at multiple layers, not just \"compile with `--release` and hope.\"\n\nWhere the speed comes from:\n\n- **Startup path kept minimal**: no JS runtime bootstrap, no module graph loading, no JIT warmup.\n- **Hot hostcall specialization**: common extension hostcalls use typed fast paths; uncommon shapes fall back to compatibility paths.\n- **Adaptive dispatch under load**: hostcall scheduling can switch modes when contention rises, then switch back when pressure drops.\n- **Fast-path safety guardrails**: sampled shadow dual-execution checks ensure optimizations do not silently change behavior.\n- **Low-allocation rendering**: TUI render buffers and markdown render results are cached\u002Freused instead of rebuilt every frame.\n- **Fast resume internals**: session indexing plus the v2 sidecar layout avoid expensive full-history scans on resume.\n- **Bounded growth controls**: compaction and truncation keep token\u002Fcontext growth and tool-output payload growth from degrading responsiveness over long sessions.\n- **Measurement-first culture**: perf artifacts are schema-validated and claim-gated in CI, so optimization work is driven by evidence and regressions are caught early.\n\nThis is why Pi can stay responsive even with heavy streaming, tool usage, large session histories, and extension workloads running at the same time.\n\n### Optimization Catalog (Code + Commit History)\n\nThis catalog reflects a long sequence of changes across runtime, storage, streaming, and UI.\n\nConcrete engineering work in this codebase includes:\n\n| Area | What we built | Why it matters |\n|------|---------------|----------------|\n| Extension dispatch core | Typed hostcall opcode fast paths, compatibility fallback lane, zero-copy payload arena, canonical-hash shortcuts, interned operation paths | Cuts per-call overhead on the hottest extension operations while preserving correctness fallback paths |\n| Registry\u002Fpolicy lookup | Immutable policy snapshots with O(1) capability checks, plus RCU-style metadata snapshots for extension registry\u002Ftool metadata | Removes repeated dynamic lookup overhead in hot authorization\u002Fdispatch paths |\n| Queueing + concurrency | Core-pinned SPSC reactor mesh, S3-FIFO-inspired admission with fairness guards, BRAVO-style fallback behavior | Improves tail latency under contention instead of only optimizing median latency |\n| Batched execution | AMAC-style interleaved batch executor with stall-aware toggling | Avoids head-of-line stalls when many independent hostcalls are in flight |\n| IO specialization | io_uring lane policy + telemetry and compatibility fallback | Routes IO-heavy calls to a specialized lane when safe and beneficial |\n| Runtime startup for extensions | QuickJS pre-warm path, warm isolate\u002Fbytecode cache behavior, and startup pipeline parallelization | Lowers cold-start overhead before the first real extension workload |\n| JS bridge\u002Fscheduler path | Pending-job fast-path tuning and bridge-level dispatch cleanup in hot extension loops | Reduces overhead between JS requests and Rust execution |\n| Adaptive control loops | Regime-shift detection (CUSUM\u002FBOCPD), budget controllers, VOI-based experiment planner, mean-field load controller, off-policy evaluation gates | Lets runtime behavior adapt to workload shifts without blind tuning |\n| Fast-path safety | Shadow dual-execution sampling with automatic rollback\u002Fbackoff on divergence | Prevents speed work from silently changing semantics |\n| Trace-level optimization | Hostcall superinstruction compiler + tier-2 trace-JIT path | Fuses repeated opcode traces and lowers repeated dispatch overhead |\n| Tool execution strategy | Dynamic read-only tool classification + parallel tool execution paths | Increases throughput when multiple tool calls can safely run together |\n| Session write path | Write-behind autosave queue, durability modes, incremental append, checkpointed rewrite strategy, single-buffer append serialization | Keeps interaction fast while still supporting stronger durability when needed |\n| Session index path | Async coalesced index updates, pending-drain hot-path tuning, and reduced allocation\u002Fboxing overhead | Keeps resume\u002Fdiscovery metadata updates off the interactive hot path |\n| Session resume path | Session Store V2 sidecar (segmented log + offset index), O(index+tail) open path, stale-sidecar detection, migration\u002Frollback tooling | Avoids full-file rescans on large histories and improves recovery behavior |\n| Long-session maintenance | Background compaction\u002Fsnapshot workers with quotas + lazy hydration paths | Controls session growth and keeps long-running workspaces responsive |\n| Compaction internals | Binary-search cut-point logic, serialization helper extraction, and zero-allocation-oriented cleanup on compaction paths | Lowers compaction overhead and keeps compaction from becoming a pause source |\n| Streaming internals | SSE parser event-type interning, scanned-byte tracking (`scanned_len`), UTF-8 recovery hardening | Reduces repeated scanning\u002Fallocation during token streaming and improves resilience |\n| Provider\u002Fmessage memory path | Zero-copy request context migration (`Cow`), `Arc`-based message\u002Fresult sharing, clone elimination in stream end paths | Removes hot-path cloning and allocation churn in core agent\u002Fprovider loops |\n| TUI rendering path | Message render cache, conversation-prefix cache, reusable render buffers, viewport\u002Frender-path refactors, Criterion perf gates | Reduces redraw cost and jitter while streaming long outputs |\n| Startup\u002Fresource loading | Parallelized skill\u002Fprompt\u002Ftheme loading plus precomputed tool definitions\u002Fcommand names | Moves heavy initialization off the critical path to improve time-to-interaction |\n| Allocator\u002Fbuild profile | jemalloc default for allocation-heavy paths, speed-oriented release profile, strict artifact validation for perf claims | Improves runtime consistency and prevents benchmark\u002Freporting drift |\n| Perf governance | Scenario matrix, claim-integrity gates, strict no-data fail behavior, variance\u002Fconfidence artifacts, reproducible orchestration bundles | Makes performance claims auditable and regression detection automatic |\n| Hostcall marshalling planner | `HostcallRewriteEngine` uses a small cost model to pick fast opcode fusion only when it is clearly cheaper and unambiguous; otherwise it stays on the canonical path and records fallback reason | Gains speed on hot marshalling shapes without risking silent semantic drift from ambiguous rewrites |\n| Tool text-processing hot path | `truncate_head`\u002F`truncate_tail` use lazy line traversal and `memchr` line counting; normalization switched to a single-pass transform instead of chained string rewrites | Large file\u002Ftool outputs avoid unnecessary intermediate allocations and stay responsive |\n| JS bridge regex and parser micro-paths | Frequent regex checks in the extension JS bridge are `OnceLock`-cached; hot bridge calls avoid repeated setup work | Cuts repeated per-call overhead in extension-heavy sessions |\n| CLI\u002Fautocomplete process-spawn reduction | `fd`\u002F`rg` availability checks are cached, and autocomplete file-index refresh runs in background with stale-update dropping | Keeps completion and command handling quick even in very large repositories |\n| Session identity\u002Findex micro-optimizations | O(1) entry-id cache, single-pass metadata finalization, and append-path cleanups replace multi-pass\u002Fcopy-heavy behavior | Reduces overhead on append\u002Fsave\u002Frebuild when sessions become large |\n| Benchmark-driven rollback discipline | Candidate micro-optimizations are benchmarked and can be reverted when real workloads regress (for example, a newline-scan `memchr` swap in SSE was rolled back) | Prevents \"optimizations\" that look fast in theory but slow down real usage |\n\nOptimization spans algorithms, execution lanes, memory movement, queue discipline, storage layout, and validation policy as one system.\n\n### Release Profile and Binary Size Gate\n\nThe shipping release profile is tuned for runtime speed:\n\n```toml\n[profile.release]\nopt-level = 3        # Maximum speed optimization\nlto = true           # Link-time optimization across all crates\ncodegen-units = 1    # Single codegen unit (slower compile, better optimization)\npanic = \"abort\"      # No unwinding machinery\nstrip = true         # Remove symbol tables\n```\n\nBinary size is still explicitly budgeted in CI via `binary_size_release`, with the current release threshold set to `22.0 MB`.\n\n### Benchmark Evidence vs Shipping Artifacts\n\nPi separates performance evidence artifacts from distributable release artifacts:\n\n- **Benchmark evidence artifacts** (PERF-3X and certification inputs) are produced by\n  `scripts\u002Fperf\u002Forchestrate.sh` and `scripts\u002Fbench_extension_workloads.sh`, and must carry\n  run provenance (`correlation_id`) plus profile labels (for example `build_profile=perf`).\n- **Shipping artifacts** (end-user binaries) are built with Cargo `release` profile and\n  distributed via GitHub Releases + installer paths.\n\nPolicy implication: release\u002Fsize artifacts alone are not valid evidence for global performance\nclaims. Performance claims must cite benchmark evidence bundles with reproducible provenance.\nSee `docs\u002Ftesting-policy.md` and `docs\u002Freleasing.md` for normative policy details.\n\nLatest full orchestrator checkpoint (`2026-02-19`):\n- Run output: `\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002Fcodex\u002Fperf\u002Ffull_local_skipbuild_retry_20260219T0650Z`\n- Correlation ID: `fullbench-local-skipbuild-retry-20260219T0650Z`\n- Summary: `11` suites total, `9` pass, `2` fail (`perf_budgets`, `perf_regression`)\n- Failure mode: both failures were strict evidence\u002Fprecondition checks (missing\u002Fstale canonical artifact paths and missing strict release-binary path), not a measured throughput\u002Flatency collapse.\n- Measured startup guards in the same run stayed green: `--help` P95 `3.8ms`, `--version` P95 `3.6ms`.\n\n### Fast Loop vs Definitive Benchmarks\n\nFor day-to-day implementation, use targeted checks to keep iteration fast. Reserve definitive\nbenchmark conclusions for integration boundaries where full evidence is regenerated.\n\n- **Fast loop (non-authoritative):** file-scoped `cargo fmt --check` and targeted test replays (`rch exec -- cargo test --test ...` when compilation is non-trivial).\n- **Definitive pass (authoritative):** offload heavy runs with strict remote gating (`rch exec -- ...` or script wrappers with `--require-rch`), then require\n  updated evidence artifacts:\n  - `tests\u002Fperf\u002Freports\u002Fphase1_matrix_validation.json`\n  - `tests\u002Ffull_suite_gate\u002Ffull_suite_verdict.json`\n  - `tests\u002Ffull_suite_gate\u002Fcertification_verdict.json`\n  - `tests\u002Ffull_suite_gate\u002Fextension_remediation_backlog.json`\n\nThis keeps inner loops responsive while preserving strict claim-integrity at release time.\n\n### Extension Workload Hotspot Profiling\n\nPi includes a dedicated workload harness for extension runtime bottlenecks:\n\n```bash\ncargo run --bin ext_workloads -- \\\n  --out artifacts\u002Fperf\u002Fext_workloads.jsonl \\\n  --matrix-out artifacts\u002Fperf\u002Fext_hostcall_hotspot_matrix.json \\\n  --trace-out artifacts\u002Fperf\u002Fext_hostcall_bridge_trace.jsonl\n```\n\nThis harness does more than raw timing:\n\n- Breaks hostcall cost into six stages: `marshal`, `queue`, `schedule`, `policy`, `execute`, `io`\n- Produces a hotspot matrix (`pi.ext.hostcall_hotspot_matrix.v1`) for quick bottleneck ranking\n- Produces bridge trace events (`pi.ext.hostcall_trace.v1`) for per-call debugging\n- Measures how stage pairs interact and verifies full stage-pair coverage\n- Generates a VOI scheduler plan (`pi.ext.voi_scheduler.v1`) to recommend the next highest-value experiments under a fixed overhead budget\n\nIn plain terms: it helps answer \"what should we optimize next?\" with data, not guesswork.\n\n### Claim-Integrity Gates for Performance Reporting\n\nPi's perf pipeline includes strict evidence checks so global speed claims cannot be based on partial or stale data.\n\n- `scripts\u002Fperf\u002Forchestrate.sh` generates artifacts tied to a shared `correlation_id` for the same run.\n- `scripts\u002Fe2e\u002Frun_all.sh` validates required schemas, freshness, and `correlation_id` alignment before considering claims valid.\n- `tests\u002Frelease_evidence_gate.rs` fails closed when conformance\u002Fperf artifacts are missing `run_id` or `correlation_id`, or when lineage fields disagree across linked artifacts.\n- `scripts\u002Fe2e\u002Frun_all.sh` emits an evidence-adjudication matrix and only treats evidence as canonical when freshness and lineage checks both pass.\n- Key release-facing artifacts include:\n  - `pi.perf.extension_benchmark_stratification.v1`\n  - `pi.perf.phase1_matrix_validation.v1`\n  - `pi.claim_integrity.evidence_adjudication_matrix.v1`\n\nIf the evidence set is incomplete or contradictory, the claim-integrity gate stays closed and reports exactly why.\n\n### Allocator Strategy for Benchmarks\n\nShipping builds default to the platform allocator. For allocator experiments, Pi\nsupports `jemalloc` as an explicit build-time option:\n\n```bash\n# System allocator baseline + jemalloc variant in one repeatable run\nBENCH_ALLOCATORS_CSV=system,jemalloc \\\n  .\u002Fscripts\u002Fbench_extension_workloads.sh\n```\n\nThe benchmark harness records both requested and effective allocator metadata in\nits JSONL output (`allocator_requested`, `allocator_effective`,\n`allocator_fallback_reason`) via `PI_BENCH_ALLOCATOR`.\n\n- `system`: build and run without allocator feature overrides\n- `jemalloc`: build with `--features jemalloc`\n- `auto`: prefer `jemalloc`, fall back to `system` if build fails\n\nIf `jemalloc` is requested but unavailable for the current build, the run fails\nclosed to the compiled allocator and includes a fallback reason in artifacts.\n\n### Memory Usage\n\nRust's ownership model enables predictable memory usage without garbage collection pauses:\n\n| State | Memory |\n|-------|--------|\n| Startup (idle) | ~15MB |\n| Active session (small) | ~25MB |\n| Large file in context | ~30-50MB |\n| Streaming response | +0MB (streamed, not buffered) |\n\nThe absence of a GC means no surprise latency spikes during streaming output.\n\n### Streaming Architecture\n\nResponses stream token-by-token from the API to the terminal with minimal buffering:\n\n```\nAPI Server → TCP → SSE Parser → Event Handler → Terminal\n     │                              │\n     └──────── no buffering ────────┘\n```\n\nEach token appears on screen within milliseconds of leaving Anthropic's servers. The SSE parser processes events as they arrive rather than waiting for complete responses.\n\n### TUI Rendering Performance\n\nThe interactive TUI targets 60fps rendering with several optimization layers:\n\n**Frame timing telemetry**: Every render cycle is instrumented. Slow frames (>16ms) are tracked and classifiable by phase: viewport sync, message encoding, markdown rendering. This data feeds the internal performance monitor.\n\n**Message render cache**: Markdown-to-ANSI conversion involves syntax highlighting, table layout, and link detection. Pi caches the rendered output per message and invalidates only on theme change or terminal resize. During streaming, only the actively-changing message is re-rendered; all prior messages hit the cache.\n\n**Pre-allocated render buffers**: The `RenderBuffers` struct is reused across render cycles. Rather than allocating new `String` buffers each frame, Pi writes into pre-sized buffers and clears them before reuse, eliminating thousands of small allocations per second during streaming.\n\n**Memory pressure monitoring**: A `MemoryMonitor` samples process heap size and classifies it into three tiers:\n\n| Tier | Threshold | Action |\n|------|-----------|--------|\n| **Normal** | \u003C80% of budget | No action |\n| **Pressure** | 80-95% of budget | Collapse tool output displays, hide thinking blocks |\n| **Critical** | >95% of budget | Truncate older messages, force compaction |\n\nProgressive degradation keeps Pi responsive during long sessions with accumulated tool output.\n\n---\n\n## Troubleshooting\n\nFor a more complete guide, see [docs\u002Ftroubleshooting.md](docs\u002Ftroubleshooting.md).\n\n### \"fd not found\"\n\nThe `find` tool requires `fd`:\n\n```bash\n# Ubuntu\u002FDebian\napt install fd-find\n\n# macOS\nbrew install fd\n\n# The binary might be named fdfind\nln -s $(which fdfind) ~\u002F.local\u002Fbin\u002Ffd\n```\n\n### \"API key not set\"\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Or in settings.json\n{ \"apiKey\": \"sk-ant-...\" }\n\n# Or per-command\npi --api-key \"sk-ant-...\" \"Hello\"\n```\n\n### \"Session corrupted\"\n\nSessions are append-only JSONL. If corruption occurs:\n\n```bash\n# Start fresh\npi --no-session\n\n# Or delete the problematic session\nrm ~\u002F.pi\u002Fagent\u002Fsessions\u002F--home-user-project--\u002Fcorrupted-session.jsonl\n```\n\n### \"Streaming hangs\"\n\nCheck your network connection. Pi uses SSE which requires stable connections:\n\n```bash\n# Test with curl\ncurl -N https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages\n```\n\n### \"Tool output truncated\"\n\nThis is intentional to prevent context overflow. Use offset\u002Flimit:\n\n```bash\n# In the conversation\n\"Read lines 2000-4000 of that file\"\n```\n\n---\n\n## Limitations\n\nPi is honest about what it doesn't do:\n\n| Limitation | Workaround |\n|------------|------------|\n| **Not all provider APIs** | Built-in support includes Anthropic, OpenAI (Chat + Responses), Gemini, Cohere, Azure OpenAI, Bedrock, Vertex AI, GitHub Copilot, and GitLab Duo; some ecosystem-specific APIs are still TBD |\n| **No web browsing** | Use bash with curl |\n| **No GUI** | Terminal-only by design |\n| **Some extensions need npm stubs** | 5 npm packages not yet shimmed; see EXTENSIONS.md §8.1 |\n| **English-centric** | Works but not optimized for other languages |\n| **Nightly Rust required** | Uses 2024 edition features |\n\n---\n\n## Design Philosophy\n\n### Specification-First Porting\n\nThis port follows a \"specification extraction\" methodology rather than line-by-line translation:\n\n1. **Extract behavior**: Study the TypeScript implementation to understand *what* it does, not *how*\n2. **Document the spec**: Write down expected behaviors, edge cases, and invariants\n3. **Implement from spec**: Write idiomatic Rust that satisfies the spec\n4. **Conformance testing**: Verify behavior matches via fixture-based tests\n\nThis approach yields better code than mechanical translation. TypeScript idioms (callbacks, promises, class hierarchies) don't map cleanly to Rust (ownership, traits, enums). Fighting the language produces worse results than embracing it.\n\n### Conformance Testing\n\nThe test suite includes fixture-based conformance tests that validate tool behavior:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"tool\": \"edit\",\n  \"cases\": [\n    {\n      \"name\": \"edit_simple_replace\",\n      \"setup\": [\n        {\"type\": \"create_file\", \"path\": \"test.txt\", \"content\": \"Hello, World!\"}\n      ],\n      \"input\": {\n        \"path\": \"test.txt\",\n        \"oldText\": \"World\",\n        \"newText\": \"Rust\"\n      },\n      \"expected\": {\n        \"content_contains\": [\"Successfully replaced\"],\n        \"details\": {\"oldLength\": 5, \"newLength\": 4}\n      }\n    }\n  ]\n}\n```\n\nEach fixture specifies:\n- **Setup**: Files\u002Fdirectories to create before the test\n- **Input**: Tool parameters\n- **Expected**: Output content patterns, exact field matches, or error conditions\n\nThe Rust implementation can be validated against the TypeScript original without coupling to implementation details.\n\n### Extension System\n\nPi supports legacy JS\u002FTS extensions via an embedded QuickJS runtime. Unlike\ntraditional plugin systems, extensions run in a **sandboxed, capability-gated**\nenvironment with no ambient OS access:\n\n1. **No Node\u002FBun required**: QuickJS + Pi-provided shims for common Node APIs\n2. **Capability-based security**: each host connector call is policy-checked and logged\n3. **Conformance-tested**: status is tracked in `docs\u002Fext-compat.md` and `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002F`\n4. **Sub-100ms load times**: extensions load in \u003C100ms (P95) with no JIT warmup\n\nLegacy extension behavior is automatic:\n- Existing `.js\u002F.ts` extensions run directly (no manual conversion step).\n- `*.native.json` descriptors are optional and mainly useful for native-rust runtime workflows.\n- One session currently uses one runtime family at a time (JS\u002FTS or native descriptor).\n\nPolicy preset quick-start:\n\n```bash\n# Inspect current effective policy\npi --explain-extension-policy\n\n# Switch profile for one command (safe | balanced | permissive)\npi --extension-policy balanced --explain-extension-policy\n\n# Legacy alias is still accepted:\npi --extension-policy standard --explain-extension-policy\n\n# Narrow dangerous-capability opt-in (preferred over permissive)\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n```\n\nOperator rollout playbook (compatibility-first local defaults + explicit lock-down):\n\n```bash\n# 1) Baseline: verify defaults are compatibility-first (`permissive`)\npi --explain-extension-policy\n\n# 2) Staging: use balanced prompting, dangerous caps still denied by default\npi --extension-policy balanced --explain-extension-policy\n\n# 3) Explicit lock-down for strict local\u002FCI runs\npi --extension-policy safe --explain-extension-policy\n\n# 4) Narrow opt-in for dangerous capabilities (preferred path)\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n\n# 5) Explicit permissive mode when you want to be unambiguous\npi --extension-policy permissive --explain-extension-policy\n```\n\n`settings.json` baseline for local\u002Fdev:\n\n```json\n{\n  \"extensionPolicy\": {\n    \"defaultPermissive\": true\n  }\n}\n```\n\nUse this to restore the stricter fallback without CLI flags:\n\n```json\n{\n  \"extensionPolicy\": {\n    \"defaultPermissive\": false\n  }\n}\n```\n\nInteractive TUI: open `\u002Fsettings` and toggle `extensionPolicy.defaultPermissive`.\n\nCI guidance:\n\n```bash\n# CI default: keep dangerous capabilities disabled\npi --extension-policy safe --explain-extension-policy\n\n# CI opt-in job (only where required), keep explicit and auditable\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n```\n\nRollback rule: remove `PI_EXTENSION_ALLOW_DANGEROUS`, set `extensionPolicy.profile`\nback to `safe` or set `extensionPolicy.defaultPermissive` to `false`, and re-run\n`pi --explain-extension-policy` to confirm deny decisions.\n\nSee [EXTENSIONS.md](EXTENSIONS.md) for the full architecture, runtime contract,\nand conformance results.\n\n### Unsafe Forbidden\n\nThe `#![forbid(unsafe_code)]` directive is project-wide and non-negotiable. Rationale:\n\n- **Attack surface**: Pi executes user-provided shell commands and reads arbitrary files\n- **Memory bugs = security bugs**: Buffer overflows or use-after-free in this context could be exploitable\n- **Performance irrelevant**: The bottleneck is network latency to the API, not CPU cycles\n- **Dependencies audited**: All dependencies either use no unsafe or are well-audited (e.g., `rustls`)\n\nThe safe Rust subset provides all necessary functionality without compromising security.\n\n---\n\n## FAQ\n\n**Q: What's the relationship to the original Pi Agent?**\nA: This is an authorized Rust port of [Pi Agent](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi) by [Mario Zechner](https:\u002F\u002Fgithub.com\u002Fbadlogic), created with his blessing. The architecture differs significantly from the TypeScript original: it uses [asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync) for structured concurrency and [rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust) (a port of Will McGugan's [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) library) for terminal rendering. The goal is idiomatic Rust while preserving Pi Agent's UX.\n\n**Q: Why rewrite in Rust?**\nA: Startup time matters when you're in a terminal all day. Rust gives us \u003C100ms startup vs 500ms+ for Node.js. Plus, no runtime dependencies to manage.\n\n**Q: Can I use providers beyond Anthropic (OpenAI\u002FGemini\u002FCohere\u002FAzure\u002FBedrock\u002FVertex\u002FCopilot\u002FGitLab\u002FCodex)?**\nA: Yes. Native providers include Anthropic, OpenAI (Chat + Responses + Codex Responses), Gemini (native + Gemini CLI + Antigravity routes), Cohere, Azure OpenAI, Amazon Bedrock, Vertex AI, GitHub Copilot, and GitLab Duo. Pi also supports many OpenAI-compatible presets (for example Groq, OpenRouter, Mistral, Together, DeepSeek, Cerebras, DeepInfra, Alibaba\u002FQwen, and Moonshot\u002FKimi). Provider IDs and aliases are case-insensitive. Set credentials and choose via `--provider`\u002F`--model`; run `pi --list-providers` to see canonical IDs, aliases, and env keys.\n\n**Q: How do sessions work?**\nA: Each session is a JSONL file with message entries. Sessions are per-project (based on working directory) and support branching via parent references.\n\n**Q: Why is unsafe forbidden?**\nA: Memory safety is non-negotiable for a tool that executes arbitrary commands. The performance cost is negligible for this use case.\n\n**Q: How do I extend Pi?**\nA: Pi has a full extension system with two runtime families: JS\u002FTS entrypoints run in embedded QuickJS, and `*.native.json` descriptors run in the native-rust descriptor runtime. Both are capability-gated and audited through the same policy system. One session uses one runtime family at a time. Extensions can register tools, slash commands, event hooks, flags, and custom providers. See [EXTENSIONS.md](EXTENSIONS.md) for details. For built-in tool changes, implement the `Tool` trait in `src\u002Ftools.rs`.\n\n**Q: Why isn't X feature included?**\nA: Pi focuses on core coding assistance. Features like web browsing, image generation, etc. are out of scope. Use specialized tools for those.\n\n**Q: How does compaction work?**\nA: When a conversation exceeds the model's context window, Pi summarizes older messages using the LLM itself, storing the summary as a session entry. Recent messages are kept verbatim. The cut point is chosen at a turn boundary, and the summary includes a record of which files were read or modified so the model retains that awareness. Compaction runs automatically after each agent turn when needed, or manually via `\u002Fcompact`.\n\n**Q: Can I add a custom provider that Pi doesn't support natively?**\nA: Yes. Create a `models.json` file in `~\u002F.pi\u002Fagent\u002F` or `.pi\u002F` with entries specifying the model ID, base URL, and API type (usually `openai-completions` for OpenAI-compatible endpoints). Pi's compat config system handles field name differences and feature flag overrides. Extensions can also register entirely custom providers.\n\n**Q: How does Pi decide which session to resume?**\nA: Pi maintains a SQLite index of all session files. When you run `pi -c`, it queries the index for the most recently modified session whose working directory matches your current project. This avoids scanning the filesystem on every resume.\n\n**Q: What happens if an extension tries to access something dangerous?**\nA: Every hostcall from an extension is checked against the active capability policy before execution. Dangerous capabilities (`exec`, `env`) are denied by default under `safe` and `balanced` unless explicitly opted in (for example via `PI_EXTENSION_ALLOW_DANGEROUS=1`), and are available under `permissive`. For `exec`, Pi then applies command mediation before spawn: it classifies command+arg signatures and blocks critical classes by default (for example recursive delete, disk\u002Fdevice write, reverse shell), with strict\u002Fsafe policy able to block high-tier classes as well (for example shutdown, process-kill, credential-file modification). Denied calls return errors to the extension Promise path, and denial events are recorded in redacted security-alert and exec-mediation audit artifacts. Sensitive env keys (API keys\u002Ftokens\u002Fsecrets) remain filtered. If behavior escalates, you can kill-switch that extension into quarantined `killed` state immediately or force compatibility-lane routing as a containment step while investigating.\n\n**Q: Does Pi work with self-hosted or proxied LLMs?**\nA: Yes. Point any provider at a custom base URL via `models.json`. Pi normalizes URL paths per API type and applies compatibility overrides for field-name and feature differences. This works with vLLM, Ollama, LiteLLM, and similar OpenAI-compatible servers.\n\n---\n\n## Comparison\n\n| Feature | Pi | Claude Code | Aider | Cursor |\n|---------|-----|-------------|-------|--------|\n| **Language** | Rust | TypeScript | Python | Electron |\n| **Startup** | \u003C100ms | ~1s | ~2s | ~5s |\n| **Memory** | \u003C50MB | ~200MB | ~150MB | ~500MB |\n| **Providers** | Anthropic + OpenAI\u002FResponses + Gemini\u002FCohere + Azure\u002FBedrock\u002FVertex + Copilot\u002FGitLab + OpenAI-compatible presets | Anthropic | Many | Many |\n| **Tools** | 8 built-in | Many | File-focused | IDE-integrated |\n| **Sessions** | JSONL tree | Proprietary | Git-based | Proprietary |\n| **Open source** | Yes | Yes | Yes | No |\n\n---\n\n## Development\n\n### Building\n\n```bash\nrch exec -- cargo build           # Debug build (remote offload)\nrch exec -- cargo build --release # Release build (optimized, remote offload)\nrch exec -- cargo test            # Run tests (remote offload)\n# Lint checks (remote-safe split to avoid rch clippy timeout fail-open)\nrch exec -- cargo clippy --lib --bins -- -D warnings\nrch exec -- cargo clippy --tests -- -D warnings\nrch exec -- cargo clippy --benches -- -D warnings\nrch exec -- cargo clippy --examples -- -D warnings\n```\n\n### Testing\n\n```bash\n# Unified verification runner (recommended for deterministic evidence artifacts)\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --profile focused\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --profile ci\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --rerun-from tests\u002Fe2e_results\u002F\u003Ctimestamp>\u002Fsummary.json --skip-unit\n\n# Fast smoke\u002Fextension quality wrappers with strict remote enforcement\n.\u002Fscripts\u002Fsmoke.sh --require-rch\n.\u002Fscripts\u002Fext_quality_pipeline.sh --require-rch\n\n# Multi-agent safety: with CODEX_THREAD_ID set, run_all defaults\n# CARGO_TARGET_DIR to target\u002Fagents\u002F\u003CCODEX_THREAD_ID> unless overridden.\n# Set CARGO_TARGET_DIR explicitly if you want a custom shared or isolated target.\n\n# All tests\nrch exec -- cargo test\n\n# Specific module\nrch exec -- cargo test tools::tests\nrch exec -- cargo test sse::tests\n\n# Conformance tests\nrch exec -- cargo test conformance\n```\n\nFocused validation tools:\n\n```bash\n# Dev-firstset gate before release build\nrch exec -- cargo build --bin pi --bin ext_release_binary_e2e\nPI_HTTP_REQUEST_TIMEOUT_SECS=0 rch exec -- \\\n  cargo run --bin ext_release_binary_e2e -- \\\n  --pi-bin target\u002Fdebug\u002Fpi \\\n  --provider ollama --model qwen2.5:0.5b \\\n  --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced\n\n# Full optimized release-binary run after gate passes\nrch exec -- cargo build --release --bin pi --bin ext_release_binary_e2e\nPI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Frelease\u002Fext_release_binary_e2e \\\n  --pi-bin target\u002Frelease\u002Fpi \\\n  --provider ollama --model qwen2.5:0.5b \\\n  --jobs 10 --timeout-secs 600 --extension-policy balanced\n\n# Runtime risk ledger forensics (verify, replay, calibrate)\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- verify --input path\u002Fto\u002Fruntime_risk_ledger.json\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- replay --input path\u002Fto\u002Fruntime_risk_ledger.json\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- calibrate --input path\u002Fto\u002Fruntime_risk_ledger.json --objective balanced_accuracy\n```\n\n- `ext_runtime_risk_ledger` operates on `pi.ext.runtime_risk_ledger.v1` artifacts (for example, from incident bundle exports).\n\n### Release & Publishing\n\nReleases are tag-driven and must align with `Cargo.toml` versions.\n\n- Tag format: `vX.Y.Z` (pre-releases like `vX.Y.Z-rc.N` are allowed but skip crates.io publish).\n- The tag version **must** match `package.version` in `Cargo.toml`.\n- Publish order for dependencies: `asupersync` → `rich_rust` → `charmed-*` (lipgloss, bubbletea, bubbles, glamour) → `pi_agent_rust`.\n- `.github\u002Fworkflows\u002Fpublish.yml` handles crates.io publish when `CARGO_REGISTRY_TOKEN` is set.\n\n### Coverage\n\nCoverage uses `cargo-llvm-cov`:\n\n```bash\n# One-time install\ncargo install cargo-llvm-cov --locked\nrustup component add llvm-tools-preview\n\n# Summary (fastest)\ncargo llvm-cov --all-targets --workspace --summary-only\n\n# LCOV report (for CI\u002Fartifacts)\nCI=true VCR_MODE=playback VCR_CASSETTE_DIR=tests\u002Ffixtures\u002Fvcr \\\n  cargo llvm-cov --all-targets --workspace --lcov --output-path lcov.info\n\n# HTML report (defaults to target\u002Fllvm-cov\u002Fhtml)\ncargo llvm-cov --all-targets --workspace --html\n```\n\n### Project Structure\n\nSelected core modules (non-exhaustive):\n\n```\nsrc\u002F\n├── main.rs                # CLI entry point\n├── lib.rs                 # Library exports\n├── app.rs                 # Startup\u002Fmodel selection helpers\n├── agent.rs               # Agent loop + event orchestration\n├── agent_cx.rs            # asupersync capability context wiring\n├── cli.rs                 # Argument parsing\n├── config.rs              # Configuration\n├── auth.rs                # API key\u002FOAuth\u002FAWS credential storage\n├── model.rs               # Message\u002Fcontent\u002Fstream event types\n├── provider.rs            # Provider trait\n├── provider_metadata.rs   # Canonical provider IDs + routing defaults\n├── models.rs              # Model registry + models.json overrides\n├── providers\u002F\n│   ├── anthropic.rs        # Anthropic Messages API\n│   ├── openai.rs           # OpenAI Chat Completions\n│   ├── openai_responses.rs # OpenAI Responses API\n│   ├── gemini.rs           # Gemini API\n│   ├── cohere.rs           # Cohere Chat API\n│   ├── azure.rs            # Azure OpenAI\n│   ├── bedrock.rs          # Amazon Bedrock Converse\n│   ├── vertex.rs           # Google Vertex AI\n│   ├── copilot.rs          # GitHub Copilot backend\n│   ├── gitlab.rs           # GitLab Duo backend\n│   └── mod.rs              # Provider factory + extension bridge\n├── tools.rs                # Built-in tool implementations\n├── sse.rs                  # Streaming SSE parser\n├── http\u002F\n│   ├── client.rs           # asupersync-backed HTTP client\n│   ├── sse.rs              # HTTP SSE helpers\n│   └── mod.rs\n├── session.rs              # JSONL session persistence\u002Ftree ops\n├── session_index.rs        # SQLite session metadata index\u002Fcache\n├── session_sqlite.rs       # Optional sqlite-sessions backend\n├── compaction.rs           # Context compaction algorithm\n├── interactive.rs          # Interactive TUI app loop\u002Fstate\n├── interactive\u002F            # Bubble Tea-style TUI submodules\n├── rpc.rs                  # RPC\u002Fstdio mode\n├── extensions.rs           # Extension protocol + policy + security\n├── extensions_js.rs        # QuickJS runtime bridge + hostcalls\n├── extension_dispatcher.rs # Hostcall\u002Ftool dispatch plumbing\n├── extension_preflight.rs  # Extension compatibility scanner\n├── extension_validation.rs # Extension validation pipeline glue\n├── resources.rs            # Skills\u002Fprompt\u002Ftheme\u002Fextension loading\n└── tui.rs                  # Terminal UI rendering helpers\n```\n\n---\n\n## Documentation Index\n\nEach entry below includes the document name, purpose, bottom-line takeaway, and direct link.\n\n| Category | What it covers | Jump |\n|---|---|---|\n| Extension Ecosystem | extension architecture, corpus, catalogs, conformance, compatibility | [Go](#1-extension-ecosystem) |\n| Core Ops and UX | governance, CI\u002FQA ops, keybindings, prompts, packaging, model\u002Fconfig UX, drop-in migration\u002Fcertification | [Go](#2-core-ops-and-ux) |\n| Provider Subsystem | provider audits, setup contracts, parity and remediation artifacts | [Go](#3-provider-subsystem) |\n| QA, Schemas, Security, Platform | release\u002FQA runbooks, schemas, security baselines, platform guides | [Go](#4-qa-schemas-security-and-platform) |\n\n### 1. Extension Ecosystem\n\n- `docs\u002FBRANCH_PROTECTION.md` - Purpose: define branch protection policy and enforcement rules. Bottom line: CI and review gates are mandatory for mainline integrity. Link: [View](docs\u002FBRANCH_PROTECTION.md)\n- `docs\u002FEXTENSION_CANDIDATES.md` - Purpose: catalog candidate extensions for inclusion\u002Ftesting. Bottom line: start extension triage from this longlist. Link: [View](docs\u002FEXTENSION_CANDIDATES.md)\n- `docs\u002FEXTENSION_CAPTURE_SCENARIOS.md` - Purpose: define extension capture and replay scenarios. Bottom line: use these scenarios for deterministic extension behavior capture. Link: [View](docs\u002FEXTENSION_CAPTURE_SCENARIOS.md)\n- `docs\u002FEXTENSION_POPULARITY_CRITERIA.md` - Purpose: specify how extension popularity is scored. Bottom line: popularity decisions follow explicit ranking criteria. Link: [View](docs\u002FEXTENSION_POPULARITY_CRITERIA.md)\n- `docs\u002FEXTENSION_REFRESH_CHECKLIST.md` - Purpose: operational checklist for extension corpus refreshes. Bottom line: follow this to update corpus safely and repeatably. Link: [View](docs\u002FEXTENSION_REFRESH_CHECKLIST.md)\n- `docs\u002FEXTENSION_SAMPLE.md` - Purpose: human-readable sample extension contract. Bottom line: reference this when authoring new extension packages. Link: [View](docs\u002FEXTENSION_SAMPLE.md)\n- `docs\u002FEXTENSION_SAMPLING_MATRIX.md` - Purpose: define extension sampling strategy and strata. Bottom line: test coverage comes from this sampling matrix. Link: [View](docs\u002FEXTENSION_SAMPLING_MATRIX.md)\n- `docs\u002FLEGACY_EXTENSION_RUNNER.md` - Purpose: explain legacy extension runner behavior and constraints. Bottom line: use for compatibility context, not new runtime design. Link: [View](docs\u002FLEGACY_EXTENSION_RUNNER.md)\n- `docs\u002FPIJS_PROOF_REPORT.md` - Purpose: provide formal evidence for PiJS runtime properties. Bottom line: PiJS eliminates ambient authority by design. Link: [View](docs\u002FPIJS_PROOF_REPORT.md)\n- `docs\u002FTEST_COVERAGE_MATRIX.md` - Purpose: map modules to test suites and coverage status. Bottom line: this is the coverage gap dashboard. Link: [View](docs\u002FTEST_COVERAGE_MATRIX.md)\n- `docs\u002Fcapability-prompts.md` - Purpose: document capability prompt UX and policy semantics. Bottom line: prompts are policy artifacts, not ad hoc UI. Link: [View](docs\u002Fcapability-prompts.md)\n- `docs\u002Fci-operator-runbook.md` - Purpose: CI operations runbook for maintainers. Bottom line: use this for incident response in CI pipelines. Link: [View](docs\u002Fci-operator-runbook.md)\n- `docs\u002Fconformance-operator-playbook.md` - Purpose: operating guide for conformance campaigns. Bottom line: run conformance with this playbook for reproducible results. Link: [View](docs\u002Fconformance-operator-playbook.md)\n- `docs\u002Fcoverage-baseline-map.json` - Purpose: machine-readable mapping of coverage baselines. Bottom line: automation should use this as baseline source of truth. Link: [View](docs\u002Fcoverage-baseline-map.json)\n- `docs\u002Fdevelopment.md` - Purpose: contributor-facing development workflow reference. Bottom line: this is the canonical local dev setup guide. Link: [View](docs\u002Fdevelopment.md)\n- `docs\u002Fe2e_scenario_matrix.json` - Purpose: machine-readable matrix of E2E scenarios. Bottom line: E2E scope and expected flows are defined here. Link: [View](docs\u002Fe2e_scenario_matrix.json)\n- `docs\u002Fevidence-contract-schema.json` - Purpose: schema for evidence artifacts and logs. Bottom line: evidence producers must conform to this contract. Link: [View](docs\u002Fevidence-contract-schema.json)\n- `docs\u002Fext-compat.md` - Purpose: explain extension compatibility posture and boundaries. Bottom line: this is the quick compatibility reference. Link: [View](docs\u002Fext-compat.md)\n- `docs\u002Fextension-api-matrix.json` - Purpose: API surface matrix for extension host\u002Fruntime calls. Bottom line: use this to see supported extension APIs at a glance. Link: [View](docs\u002Fextension-api-matrix.json)\n- `docs\u002Fextension-architecture.md` - Purpose: architecture deep dive for extension runtime internals. Bottom line: this is the primary extension technical design doc. Link: [View](docs\u002Fextension-architecture.md)\n- `docs\u002Fextension-artifact-provenance.json` - Purpose: provenance metadata for extension artifacts. Bottom line: artifact trust and lineage are tracked here. Link: [View](docs\u002Fextension-artifact-provenance.json)\n- `docs\u002Fextension-candidate-pool.json` - Purpose: machine-readable candidate pool for extension selection. Bottom line: ingestion\u002Fselection jobs should read from this pool. Link: [View](docs\u002Fextension-candidate-pool.json)\n- `docs\u002Fextension-catalog.json` - Purpose: master extension catalog and status metadata. Bottom line: this is the canonical extension inventory. Link: [View](docs\u002Fextension-catalog.json)\n- `docs\u002Fextension-catalog.schema.json` - Purpose: schema for validating extension catalog documents. Bottom line: catalog updates must pass this schema. Link: [View](docs\u002Fextension-catalog.schema.json)\n- `docs\u002Fextension-code-search-inventory.json` - Purpose: inventory of code-search findings across extension repos. Bottom line: use this as raw search evidence. Link: [View](docs\u002Fextension-code-search-inventory.json)\n- `docs\u002Fextension-code-search-summary.json` - Purpose: summarized results from extension code-search inventory. Bottom line: top code-search findings are condensed here. Link: [View](docs\u002Fextension-code-search-summary.json)\n- `docs\u002Fextension-collections.json` - Purpose: grouped extension collections by theme\u002Fscope. Bottom line: collection-level planning starts here. Link: [View](docs\u002Fextension-collections.json)\n- `docs\u002Fextension-compatibility-matrix.md` - Purpose: compatibility matrix for extension runtime support levels. Bottom line: check this before claiming compatibility gaps. Link: [View](docs\u002Fextension-compatibility-matrix.md)\n- `docs\u002Fextension-conformance-matrix.json` - Purpose: machine-readable extension conformance outcomes. Bottom line: this is the conformance truth table for automation. Link: [View](docs\u002Fextension-conformance-matrix.json)\n- `docs\u002Fextension-conformance-test-plan.json` - Purpose: test planning artifact for extension conformance. Bottom line: conformance execution should follow this plan. Link: [View](docs\u002Fextension-conformance-test-plan.json)\n- `docs\u002Fextension-curated-list-summary.json` - Purpose: summary of curated extension subsets. Bottom line: use for quick curated corpus decisions. Link: [View](docs\u002Fextension-curated-list-summary.json)\n- `docs\u002Fextension-entry-scan.json` - Purpose: scan results for extension entrypoint detection. Bottom line: extension entry assumptions are validated here. Link: [View](docs\u002Fextension-entry-scan.json)\n- `docs\u002Fextension-inclusion-list.json` - Purpose: explicit inclusion list for extension sets. Bottom line: this controls what is in-scope for runs. Link: [View](docs\u002Fextension-inclusion-list.json)\n- `docs\u002Fextension-individual-enumeration.json` - Purpose: per-extension enumeration details and metadata. Bottom line: drill into individual extension records here. Link: [View](docs\u002Fextension-individual-enumeration.json)\n- `docs\u002Fextension-license-report.json` - Purpose: license audit results for extension corpus. Bottom line: licensing risks and statuses are captured here. Link: [View](docs\u002Fextension-license-report.json)\n- `docs\u002Fextension-master-catalog.json` - Purpose: high-authority upstream extension catalog snapshot. Bottom line: this anchors full-corpus sync and provenance checks. Link: [View](docs\u002Fextension-master-catalog.json)\n- `docs\u002Fextension-npm-scan-summary.json` - Purpose: summary of npm-based extension scanning outputs. Bottom line: npm scan posture is summarized here. Link: [View](docs\u002Fextension-npm-scan-summary.json)\n- `docs\u002Fextension-onboarding-queue.json` - Purpose: machine-readable onboarding queue for extension work. Bottom line: queue automation should consume this file. Link: [View](docs\u002Fextension-onboarding-queue.json)\n- `docs\u002Fextension-onboarding-queue.md` - Purpose: human-readable extension onboarding queue and context. Bottom line: this is the operator queue board. Link: [View](docs\u002Fextension-onboarding-queue.md)\n- `docs\u002Fextension-priority-summary.json` - Purpose: summary of extension prioritization signals. Bottom line: priority rollups are centralized here. Link: [View](docs\u002Fextension-priority-summary.json)\n- `docs\u002Fextension-priority.json` - Purpose: detailed extension priority scoring data. Bottom line: per-extension prioritization is machine-readable here. Link: [View](docs\u002Fextension-priority.json)\n- `docs\u002Fextension-registry.md` - Purpose: document extension registry model and usage. Bottom line: registry behavior and expectations are defined here. Link: [View](docs\u002Fextension-registry.md)\n- `docs\u002Fextension-repo-search-summary.json` - Purpose: summary of repository-level extension discovery searches. Bottom line: repo discovery outcomes are consolidated here. Link: [View](docs\u002Fextension-repo-search-summary.json)\n- `docs\u002Fextension-research-playbook.json` - Purpose: machine-readable playbook for extension research workflow. Bottom line: research execution steps and outputs are formalized here. Link: [View](docs\u002Fextension-research-playbook.json)\n- `docs\u002Fextension-runtime-threat-model.md` - Purpose: runtime-focused extension threat model with controls\u002Ftests. Bottom line: this maps concrete runtime abuse paths to mitigations. Link: [View](docs\u002Fextension-runtime-threat-model.md)\n- `docs\u002Fextension-sample.json` - Purpose: machine-readable extension sample payload\u002Fspec. Bottom line: use this as canonical sample JSON contract. Link: [View](docs\u002Fextension-sample.json)\n- `docs\u002Fextension-tiered-corpus.json` - Purpose: tiered corpus composition for extension testing. Bottom line: corpus tiers and membership are defined here. Link: [View](docs\u002Fextension-tiered-corpus.json)\n- `docs\u002Fextension-tiered-summary.json` - Purpose: summary of tiered corpus coverage and counts. Bottom line: corpus tier health is summarized here. Link: [View](docs\u002Fextension-tiered-summary.json)\n- `docs\u002Fextension-troubleshooting.md` - Purpose: troubleshooting guide specific to extension runtime issues. Bottom line: start here for extension failures and policy denials. Link: [View](docs\u002Fextension-troubleshooting.md)\n- `docs\u002Fextension-validated-dedup.json` - Purpose: deduplicated validated extension list. Bottom line: use this to avoid duplicate extension artifacts. Link: [View](docs\u002Fextension-validated-dedup.json)\n\n### 2. Core Ops and UX\n\n- `docs\u002Fflake-triage-policy.md` - Purpose: policy for test flake detection and triage handling. Bottom line: flakes must be classified and handled via this rubric. Link: [View](docs\u002Fflake-triage-policy.md)\n- `docs\u002Fkeybindings.md` - Purpose: keybinding reference for interactive TUI usage. Bottom line: this is the operator shortcut map. Link: [View](docs\u002Fkeybindings.md)\n- `docs\u002Fmodels.md` - Purpose: model catalog behavior, selection, and overrides. Bottom line: model resolution logic is documented here. Link: [View](docs\u002Fmodels.md)\n- `docs\u002Fnon-mock-rubric.json` - Purpose: rubric defining non-mock testing expectations. Bottom line: use this to gate real-behavior evidence quality. Link: [View](docs\u002Fnon-mock-rubric.json)\n- `docs\u002Fpackages.md` - Purpose: package installation and package-content conventions. Bottom line: package usage and structure are defined here. Link: [View](docs\u002Fpackages.md)\n- `docs\u002Fasupersync-leverage-inventory.md` - Purpose: implementation-grade inventory of where additional Asupersync leverage is genuinely high-value in Pi core surfaces. Bottom line: start here before threading inherited `AgentCx` or replacing raw thread islands. Link: [View](docs\u002Fasupersync-leverage-inventory.md)\n- `docs\u002Fdropin-certification-contract.json` - Purpose: strict drop-in certification contract and gate thresholds. Bottom line: strict replacement messaging is controlled by this contract and its hard gates. Link: [View](docs\u002Fdropin-certification-contract.json)\n- `docs\u002Fdropin-parity-gap-ledger.json` - Purpose: machine-readable ledger of known drop-in parity gaps and severity. Bottom line: unresolved critical\u002Fhigh gaps block strict replacement messaging. Link: [View](docs\u002Fdropin-parity-gap-ledger.json)\n- `docs\u002Fintegrator-migration-playbook.md` - Purpose: operator\u002Fintegrator migration and rollback playbook for moving from TypeScript Pi to Rust Pi. Bottom line: use this to run staged, evidence-backed migrations. Link: [View](docs\u002Fintegrator-migration-playbook.md)\n- `docs\u002Fparity-certification.json` - Purpose: machine-readable parity progress snapshot. Bottom line: informational status only; strict replacement release claims remain controlled by the drop-in contract and parity-gap closure status. Link: [View](docs\u002Fparity-certification.json)\n- `docs\u002Fprogram-governance.md` - Purpose: governance model for roadmap, gates, and ownership. Bottom line: governance decisions and responsibilities are defined here. Link: [View](docs\u002Fprogram-governance.md)\n- `docs\u002Fprompt-templates.md` - Purpose: prompt template system and usage guide. Bottom line: reusable prompt behaviors are managed via this doc. Link: [View](docs\u002Fprompt-templates.md)\n- `docs\u002Fsdk.md` - Purpose: SDK cookbook and migration guide for embedding Pi programmatically. Bottom line: use this for copy\u002Fpaste Rust equivalents of TypeScript SDK workflows. Link: [View](docs\u002Fsdk.md)\n- `docs\u002Fintegrator-migration-playbook.md` - Purpose: step-by-step migration and compatibility validation runbook for downstream integrators moving from TypeScript Pi to Rust Pi. Bottom line: follow this to execute and evidence a go\u002Fno-go migration decision safely. Link: [View](docs\u002Fintegrator-migration-playbook.md)\n\n### 3. Provider Subsystem\n\n- `docs\u002Fprovider-audit-evidence-index.json` - Purpose: index of provider audit evidence artifacts. Bottom line: audit traceability begins with this index. Link: [View](docs\u002Fprovider-audit-evidence-index.json)\n- `docs\u002Fprovider-audit-reconciliation-ledger.json` - Purpose: ledger of provider audit reconciliation decisions. Bottom line: discrepancies and resolutions are recorded here. Link: [View](docs\u002Fprovider-audit-reconciliation-ledger.json)\n- `docs\u002Fprovider-auth-crosswalk.json` - Purpose: provider auth alias\u002Fenv-key crosswalk. Bottom line: credential resolution mapping is centralized here. Link: [View](docs\u002Fprovider-auth-crosswalk.json)\n- `docs\u002Fprovider-auth-failure-signatures.json` - Purpose: known provider auth failure signatures and fingerprints. Bottom line: diagnose auth failures by matching this catalog. Link: [View](docs\u002Fprovider-auth-failure-signatures.json)\n- `docs\u002Fprovider-auth-playbook-validation.json` - Purpose: validation outcomes for provider auth playbook coverage. Bottom line: auth playbook quality is measured here. Link: [View](docs\u002Fprovider-auth-playbook-validation.json)\n- `docs\u002Fprovider-auth-redaction-diagnostics.json` - Purpose: diagnostics for provider auth redaction behavior. Bottom line: redaction correctness and gaps are captured here. Link: [View](docs\u002Fprovider-auth-redaction-diagnostics.json)\n- `docs\u002Fprovider-auth-troubleshooting.md` - Purpose: troubleshooting guide for provider auth issues. Bottom line: use this first for provider key\u002Fauth problems. Link: [View](docs\u002Fprovider-auth-troubleshooting.md)\n- `docs\u002Fprovider-baseline-audit.json` - Purpose: machine-readable baseline provider audit data. Bottom line: structured provider baseline evidence lives here. Link: [View](docs\u002Fprovider-baseline-audit.json)\n- `docs\u002Fprovider-baseline-audit.md` - Purpose: narrative baseline provider audit report. Bottom line: high-level provider gap picture is explained here. Link: [View](docs\u002Fprovider-baseline-audit.md)\n- `docs\u002Fprovider-canonical-id-policy.json` - Purpose: machine-readable canonical provider ID policy. Bottom line: provider ID normalization rules are defined here. Link: [View](docs\u002Fprovider-canonical-id-policy.json)\n- `docs\u002Fprovider-canonical-id-policy.md` - Purpose: human-readable canonical provider ID policy. Bottom line: this is the normative provider naming policy. Link: [View](docs\u002Fprovider-canonical-id-policy.md)\n- `docs\u002Fprovider-canonical-id-table.json` - Purpose: canonical provider ID lookup table. Bottom line: use this for deterministic provider ID mapping. Link: [View](docs\u002Fprovider-canonical-id-table.json)\n- `docs\u002Fprovider-cerebras-capability-profile.json` - Purpose: Cerebras provider capability profile. Bottom line: Cerebras support envelope and constraints are here. Link: [View](docs\u002Fprovider-cerebras-capability-profile.json)\n- `docs\u002Fprovider-cerebras-setup.json` - Purpose: Cerebras setup\u002Fconfig contract. Bottom line: configure Cerebras using this artifact. Link: [View](docs\u002Fprovider-cerebras-setup.json)\n- `docs\u002Fprovider-closure-truth-table.json` - Purpose: closure truth table for provider audit status. Bottom line: this is the provider closure scoreboard. Link: [View](docs\u002Fprovider-closure-truth-table.json)\n- `docs\u002Fprovider-config-examples.json` - Purpose: machine-readable provider config examples. Bottom line: automation-ready sample configs live here. Link: [View](docs\u002Fprovider-config-examples.json)\n- `docs\u002Fprovider-config-examples.md` - Purpose: human-readable provider config examples. Bottom line: copy from here when setting up providers. Link: [View](docs\u002Fprovider-config-examples.md)\n- `docs\u002Fprovider-discrepancy-classification.json` - Purpose: taxonomy for provider discrepancy classes. Bottom line: classify provider mismatches with this schema. Link: [View](docs\u002Fprovider-discrepancy-classification.json)\n- `docs\u002Fprovider-discrepancy-ledger.json` - Purpose: ledger of concrete provider discrepancies. Bottom line: discrepancy history and status are tracked here. Link: [View](docs\u002Fprovider-discrepancy-ledger.json)\n- `docs\u002Fprovider-gaps-audit-report.json` - Purpose: aggregate provider gap audit report. Bottom line: provider parity gaps are quantified here. Link: [View](docs\u002Fprovider-gaps-audit-report.json)\n- `docs\u002Fprovider-gaps-test-matrix.json` - Purpose: test matrix for closing provider gaps. Bottom line: missing provider tests are enumerated here. Link: [View](docs\u002Fprovider-gaps-test-matrix.json)\n- `docs\u002Fprovider-gate-compiler-report.json` - Purpose: provider gate report from compiler\u002Fbuild checks. Bottom line: compile-time provider gate status is here. Link: [View](docs\u002Fprovider-gate-compiler-report.json)\n- `docs\u002Fprovider-gate-e2e-report.json` - Purpose: provider gate report from end-to-end tests. Bottom line: provider E2E gate results are captured here. Link: [View](docs\u002Fprovider-gate-e2e-report.json)\n- `docs\u002Fprovider-gate-tests-report.json` - Purpose: consolidated provider test gate report. Bottom line: provider test gate pass\u002Ffail view is here. Link: [View](docs\u002Fprovider-gate-tests-report.json)\n- `docs\u002Fprovider-gate-triage-matrix.json` - Purpose: triage matrix for provider gate failures. Bottom line: use this to route provider gate failures fast. Link: [View](docs\u002Fprovider-gate-triage-matrix.json)\n- `docs\u002Fprovider-gate-ubs-report.json` - Purpose: UBS scan output for provider gate runs. Bottom line: provider bug-scan findings are recorded here. Link: [View](docs\u002Fprovider-gate-ubs-report.json)\n- `docs\u002Fprovider-groq-capability-profile.json` - Purpose: Groq provider capability profile. Bottom line: Groq support\u002Flimits are defined here. Link: [View](docs\u002Fprovider-groq-capability-profile.json)\n- `docs\u002Fprovider-groq-setup.json` - Purpose: Groq provider setup contract. Bottom line: configure Groq following this spec. Link: [View](docs\u002Fprovider-groq-setup.json)\n- `docs\u002Fprovider-implementation-modes.json` - Purpose: provider implementation mode classification. Bottom line: know which providers are native\u002Fbridged\u002Fmock from this file. Link: [View](docs\u002Fprovider-implementation-modes.json)\n- `docs\u002Fprovider-kimi-capability-profile.json` - Purpose: Kimi provider capability profile. Bottom line: Kimi behavior envelope is documented here. Link: [View](docs\u002Fprovider-kimi-capability-profile.json)\n- `docs\u002Fprovider-kimi-setup.json` - Purpose: Kimi provider setup contract. Bottom line: use this for Kimi integration setup. Link: [View](docs\u002Fprovider-kimi-setup.json)\n- `docs\u002Fprovider-longtail-evidence.md` - Purpose: evidence report for longtail provider coverage. Bottom line: longtail provider support claims are justified here. Link: [View](docs\u002Fprovider-longtail-evidence.md)\n- `docs\u002Fprovider-migration-guide.md` - Purpose: migration guide for provider model changes. Bottom line: follow this when migrating provider integrations. Link: [View](docs\u002Fprovider-migration-guide.md)\n- `docs\u002Fprovider-native-parity-report.json` - Purpose: report on native provider parity status. Bottom line: native parity progress is measured here. Link: [View](docs\u002Fprovider-native-parity-report.json)\n- `docs\u002Fprovider-onboarding-checklist.md` - Purpose: onboarding checklist for adding new providers. Bottom line: provider additions must pass this checklist. Link: [View](docs\u002Fprovider-onboarding-checklist.md)\n- `docs\u002Fprovider-onboarding-playbook.md` - Purpose: operational playbook for provider onboarding lifecycle. Bottom line: this is the end-to-end onboarding runbook. Link: [View](docs\u002Fprovider-onboarding-playbook.md)\n- `docs\u002Fprovider-openrouter-auth-contract.json` - Purpose: OpenRouter auth behavior contract. Bottom line: OpenRouter auth resolution must match this contract. Link: [View](docs\u002Fprovider-openrouter-auth-contract.json)\n- `docs\u002Fprovider-openrouter-capability-profile.json` - Purpose: OpenRouter capability profile. Bottom line: OpenRouter feature boundaries are documented here. Link: [View](docs\u002Fprovider-openrouter-capability-profile.json)\n- `docs\u002Fprovider-openrouter-dynamic-models-contract.json` - Purpose: contract for OpenRouter dynamic model behavior. Bottom line: dynamic model handling rules are defined here. Link: [View](docs\u002Fprovider-openrouter-dynamic-models-contract.json)\n- `docs\u002Fprovider-openrouter-model-registry-contract.json` - Purpose: OpenRouter model registry contract and expectations. Bottom line: registry consistency requirements are here. Link: [View](docs\u002Fprovider-openrouter-model-registry-contract.json)\n- `docs\u002Fprovider-openrouter-setup.json` - Purpose: OpenRouter setup\u002Fconfig contract. Bottom line: configure OpenRouter from this artifact. Link: [View](docs\u002Fprovider-openrouter-setup.json)\n- `docs\u002Fprovider-parity-checklist.json` - Purpose: checklist for provider parity closure criteria. Bottom line: parity completion gates are encoded here. Link: [View](docs\u002Fprovider-parity-checklist.json)\n- `docs\u002Fprovider-parity-reconciliation-report.json` - Purpose: report on provider parity reconciliations. Bottom line: reconciliation outcomes and rationale are here. Link: [View](docs\u002Fprovider-parity-reconciliation-report.json)\n- `docs\u002Fprovider-parity-reconciliation.json` - Purpose: machine-readable parity reconciliation ledger. Bottom line: this is the structured parity reconciliation record. Link: [View](docs\u002Fprovider-parity-reconciliation.json)\n- `docs\u002Fprovider-qwen-capability-profile.json` - Purpose: Qwen provider capability profile. Bottom line: Qwen support\u002Fconstraints are captured here. Link: [View](docs\u002Fprovider-qwen-capability-profile.json)\n- `docs\u002Fprovider-qwen-setup.json` - Purpose: Qwen provider setup contract. Bottom line: configure Qwen using this file. Link: [View](docs\u002Fprovider-qwen-setup.json)\n- `docs\u002Fprovider-remediation-manifest.json` - Purpose: manifest of provider remediation actions. Bottom line: remediation backlog and ownership are tracked here. Link: [View](docs\u002Fprovider-remediation-manifest.json)\n- `docs\u002Fprovider-remediation-routing-validation.json` - Purpose: validation of provider remediation routing logic. Bottom line: routing correctness is evidenced here. Link: [View](docs\u002Fprovider-remediation-routing-validation.json)\n- `docs\u002Fprovider-support-baseline-audit.md` - Purpose: baseline audit of declared provider support. Bottom line: support claims are grounded by this audit. Link: [View](docs\u002Fprovider-support-baseline-audit.md)\n- `docs\u002Fprovider-test-matrix-validation-report.json` - Purpose: validation report for provider test matrix completeness. Bottom line: provider test matrix health is measured here. Link: [View](docs\u002Fprovider-test-matrix-validation-report.json)\n- `docs\u002Fprovider-test-obligations.md` - Purpose: define provider-specific test obligations and gates. Bottom line: this is the provider test contract. Link: [View](docs\u002Fprovider-test-obligations.md)\n- `docs\u002Fprovider-upstream-catalog-snapshot.json` - Purpose: machine-readable snapshot of upstream provider catalogs. Bottom line: upstream drift detection starts from this snapshot. Link: [View](docs\u002Fprovider-upstream-catalog-snapshot.json)\n- `docs\u002Fprovider-upstream-catalog-snapshot.md` - Purpose: narrative summary of upstream provider snapshot changes. Bottom line: upstream provider changes are explained here. Link: [View](docs\u002Fprovider-upstream-catalog-snapshot.md)\n- `docs\u002Fprovider_e2e_artifact_contract.json` - Purpose: artifact contract for provider E2E evidence. Bottom line: provider E2E artifacts must satisfy this schema. Link: [View](docs\u002Fprovider_e2e_artifact_contract.json)\n- `docs\u002Fproviders.md` - Purpose: provider architecture, behavior, and usage reference. Bottom line: this is the primary provider subsystem guide. Link: [View](docs\u002Fproviders.md)\n\n### 4. QA, Schemas, Security, and Platform\n\n- `docs\u002Fqa-runbook.md` - Purpose: QA operating runbook across suites and artifacts. Bottom line: use this for repeatable QA execution. Link: [View](docs\u002Fqa-runbook.md)\n- `docs\u002Freleasing.md` - Purpose: release process and checklist documentation. Bottom line: follow this for consistent, safe releases. Link: [View](docs\u002Freleasing.md)\n- `docs\u002Frpc.md` - Purpose: RPC mode protocol and usage contract. Bottom line: this is the wire-level RPC integration guide. Link: [View](docs\u002Frpc.md)\n- `docs\u002Fschema\u002Fextension_manifest.json` - Purpose: JSON schema for extension manifests. Bottom line: extension manifest validation must pass this schema. Link: [View](docs\u002Fschema\u002Fextension_manifest.json)\n- `docs\u002Fschema\u002Fextension_protocol.json` - Purpose: JSON schema for extension protocol messages. Bottom line: extension message contracts are formalized here. Link: [View](docs\u002Fschema\u002Fextension_protocol.json)\n- `docs\u002Fschema\u002Fmock_spec.json` - Purpose: schema for mock\u002Ftest spec fixtures. Bottom line: mock fixtures should conform to this contract. Link: [View](docs\u002Fschema\u002Fmock_spec.json)\n- `docs\u002Fschema\u002Fruntime_hostcall_telemetry.json` - Purpose: JSON schema for runtime hostcall telemetry events. Bottom line: hostcall telemetry producers must conform to this schema. Link: [View](docs\u002Fschema\u002Fruntime_hostcall_telemetry.json)\n- `docs\u002Fsec_traceability_matrix.json` - Purpose: machine-readable security requirement traceability matrix. Bottom line: security coverage and test mappings are tracked here. Link: [View](docs\u002Fsec_traceability_matrix.json)\n- `docs\u002Fsec_traceability_matrix.md` - Purpose: narrative security traceability matrix with requirement-to-test linkage. Bottom line: human-readable security coverage status is documented here. Link: [View](docs\u002Fsec_traceability_matrix.md)\n- `docs\u002Fsecurity\u002Fbaseline-audit.md` - Purpose: code-grounded security baseline audit and gap analysis. Bottom line: this is the current security posture snapshot. Link: [View](docs\u002Fsecurity\u002Fbaseline-audit.md)\n- `docs\u002Fsecurity\u002Fincident-response-runbook.md` - Purpose: incident response procedures for security events. Bottom line: follow this runbook during active security incidents. Link: [View](docs\u002Fsecurity\u002Fincident-response-runbook.md)\n- `docs\u002Fsecurity\u002Fincident-runbook.md` - Purpose: incident detection, classification, and handling guide. Bottom line: use this for initial incident triage and escalation. Link: [View](docs\u002Fsecurity\u002Fincident-runbook.md)\n- `docs\u002Fsecurity\u002Finvariants.machine.json` - Purpose: machine-checkable security invariant manifest with test mappings. Bottom line: invariant automation should read this file. Link: [View](docs\u002Fsecurity\u002Finvariants.machine.json)\n- `docs\u002Fsecurity\u002Finvariants.md` - Purpose: normative security invariants and precedence semantics. Bottom line: this is the SEC-1.2 policy\u002Frisk contract. Link: [View](docs\u002Fsecurity\u002Finvariants.md)\n- `docs\u002Fsecurity\u002Flockfile-format.md` - Purpose: lockfile format specification for extension integrity verification. Bottom line: lockfile structure and validation rules are defined here. Link: [View](docs\u002Fsecurity\u002Flockfile-format.md)\n- `docs\u002Fsecurity\u002Fmaintenance-playbook.md` - Purpose: security maintenance procedures and scheduled operations. Bottom line: use this for routine security upkeep and policy refresh. Link: [View](docs\u002Fsecurity\u002Fmaintenance-playbook.md)\n- `docs\u002Fsecurity\u002Fmanifest-v2-migration.md` - Purpose: migration guidance from legacy extension manifests to manifest v2 security fields. Bottom line: use this to upgrade manifests without losing capability\u002Fpolicy intent. Link: [View](docs\u002Fsecurity\u002Fmanifest-v2-migration.md)\n- `docs\u002Fsecurity\u002Foperator-handbook.md` - Purpose: comprehensive operator handbook for security operations. Bottom line: this is the primary security ops reference for day-to-day work. Link: [View](docs\u002Fsecurity\u002Foperator-handbook.md)\n- `docs\u002Fsecurity\u002Foperator-quick-reference.md` - Purpose: quick-reference card for security operators. Bottom line: use this cheat sheet for fast lookups during operations. Link: [View](docs\u002Fsecurity\u002Foperator-quick-reference.md)\n- `docs\u002Fsecurity\u002Fpolicy-tuning-guide.md` - Purpose: guide for tuning extension security policies and risk thresholds. Bottom line: policy calibration and adjustment procedures are here. Link: [View](docs\u002Fsecurity\u002Fpolicy-tuning-guide.md)\n- `docs\u002Fsecurity\u002Fruntime-hostcall-telemetry.md` - Purpose: runtime hostcall telemetry design and event catalog. Bottom line: hostcall observability and event semantics are documented here. Link: [View](docs\u002Fsecurity\u002Fruntime-hostcall-telemetry.md)\n- `docs\u002Fsecurity\u002Fsecurity-slos.md` - Purpose: quantitative security SLOs, risk budgets, and release\u002Frollback gates. Bottom line: security release readiness is numerically gated here. Link: [View](docs\u002Fsecurity\u002Fsecurity-slos.md)\n- `docs\u002Fsecurity\u002Fthreat-model.md` - Purpose: formal extension ecosystem threat model. Bottom line: this is the SEC-1.1 attacker and control baseline. Link: [View](docs\u002Fsecurity\u002Fthreat-model.md)\n- `docs\u002Fsession.md` - Purpose: session model, persistence, and branching semantics. Bottom line: session behavior and storage contracts are here. Link: [View](docs\u002Fsession.md)\n- `docs\u002Fsettings.md` - Purpose: settings schema, precedence, and config behavior. Bottom line: configuration behavior is canonicalized here. Link: [View](docs\u002Fsettings.md)\n- `docs\u002Fskills.md` - Purpose: skills system usage and packaging guidance. Bottom line: extend prompt behavior through documented skill contracts. Link: [View](docs\u002Fskills.md)\n- `docs\u002Fstreaming-hostcalls.md` - Purpose: streaming hostcall behavior and lifecycle details. Bottom line: use this to reason about streaming tool execution. Link: [View](docs\u002Fstreaming-hostcalls.md)\n- `docs\u002Fterminal-setup.md` - Purpose: terminal environment setup and ergonomics guidance. Bottom line: recommended terminal configuration is here. Link: [View](docs\u002Fterminal-setup.md)\n- `docs\u002Ftermux.md` - Purpose: Termux-specific setup and runtime guidance. Bottom line: Android\u002FTermux usage is documented here. Link: [View](docs\u002Ftermux.md)\n- `docs\u002Ftest_double_inventory.json` - Purpose: inventory of test doubles and mock surfaces. Bottom line: test double usage is auditable via this file. Link: [View](docs\u002Ftest_double_inventory.json)\n- `docs\u002Ftesting-policy.md` - Purpose: testing policy, quality bars, and suite expectations. Bottom line: this is the normative test governance doc. Link: [View](docs\u002Ftesting-policy.md)\n- `docs\u002Fthemes.md` - Purpose: theme system configuration and customization. Bottom line: terminal rendering themes are documented here. Link: [View](docs\u002Fthemes.md)\n- `docs\u002Ftraceability_matrix.json` - Purpose: requirement-to-test traceability matrix. Bottom line: evidence traceability across requirements lives here. Link: [View](docs\u002Ftraceability_matrix.json)\n- `docs\u002Ftree.md` - Purpose: session tree navigation and branching behavior guide. Bottom line: use this to understand conversation tree operations. Link: [View](docs\u002Ftree.md)\n- `docs\u002Ftroubleshooting.md` - Purpose: general troubleshooting guide for common failures. Bottom line: start here for non-extension operational issues. Link: [View](docs\u002Ftroubleshooting.md)\n- `docs\u002Ftui.md` - Purpose: TUI behavior, controls, and rendering notes. Bottom line: interactive UI semantics are defined here. Link: [View](docs\u002Ftui.md)\n- `docs\u002Fwindows.md` - Purpose: Windows-specific installation and runtime guidance. Bottom line: Windows support details are centralized here. Link: [View](docs\u002Fwindows.md)\n- `docs\u002Fwit\u002Fextension.wit` - Purpose: WIT interface definition for extension host contracts. Bottom line: typed extension host ABI is defined here. Link: [View](docs\u002Fwit\u002Fextension.wit)\n\n---\n\n## About Contributions\n\nPlease don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n\n---\n\n## License\n\nMIT License (with OpenAI\u002FAnthropic Rider). See [LICENSE](LICENSE) for details.\n\n---\n\n\u003Cp align=\"center\">\n  \u003Csub>Built with Rust, for developers who live in the terminal.\u003C\u002Fsub>\n\u003C\u002Fp>\n","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_pi_agent_rust_readme_38bb3d84ad22.webp\" alt=\"Pi Agent Rust\" width=\"600\"\u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">pi_agent_rust\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>pi_agent_rust - 用 Rust 编写的高性能 AI 编程助手 CLI\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#why-should-you-care\">为什么你应该关注？\u003C\u002Fa> •\n  \u003Ca href=\"#tldr-piopenclaw-users\">简而言之\u003C\u002Fa> •\n  \u003Ca href=\"#benchmark-methodology-and-claim-integrity\">方法论\u003C\u002Fa> •\n  \u003Ca href=\"#quick-start\">快速入门\u003C\u002Fa> •\n  \u003Ca href=\"#features\">功能\u003C\u002Fa> •\n  \u003Ca href=\"#installation\">安装\u003C\u002Fa> •\n  \u003Ca href=\"#commands\">命令\u003C\u002Fa> •\n  \u003Ca href=\"#configuration\">配置\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Frust-2024%20edition-orange?logo=rust\" alt=\"Rust 2024\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT%20%2B%20Rider-blue\" alt=\"许可证：MIT + Rider\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Funsafe-forbidden-brightgreen\" alt=\"无不安全代码\">\n\u003C\u002Fp>\n\n```bash\n# 安装最新版本\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n---\n\n## 问题所在\n\n你希望在终端中使用一个 AI 编程助手，但现有的工具存在以下问题：\n- **启动缓慢**：Node.js\u002FPython 运行时会在你开始输入前增加 500 毫秒以上的延迟。\n- **内存占用高**：Electron 应用程序或重型运行时会消耗数 GB 的内存。\n- **不可靠**：流式传输中断、会话损坏、工具静默失效。\n- **难以扩展**：封闭的生态系统或复杂的插件系统。\n\n## 解决方案\n\n**pi_agent_rust** 是由 [Mario Zechner](https:\u002F\u002Fgithub.com\u002Fbadlogic) 的 [Pi Agent](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi) 项目（经其许可）从头开始用 Rust 重写的版本。它是一个单二进制文件，可立即启动，提供稳定的流式传输，并内置了 8 种工具。\n\n与逐行翻译不同，这个移植版本基于两个专门构建的 Rust 库：\n- **[asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync)**：一个结构化的并发异步运行时，内置 HTTP、TLS 和 SQLite。\n- **[rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust)**：由 [Will McGugan](https:\u002F\u002Fgithub.com\u002Fwillmcgugan) 开发的 [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) 的 Rust 版本，提供带有标记语法的精美终端输出。\n\n```bash\n# 启动一个会话\npi \"帮我将这个函数重构为使用 async\u002Fawait\"\n\n# 继续之前的会话\npi --continue\n\n# 单次模式（无需会话）\npi -p \"这个错误是什么意思？\" \u003C error.log\n```\n\n## 为什么你应该关注？\n\n如果你已经在使用 Pi Agent，尤其是通过 OpenClaw，那么这个项目在保留核心工作流程的同时，升级了底层引擎：\n\n- **在真实的端到端流程中显著更快**（而非合成的微基准测试）。\n- **长时间运行会话中的内存占用大幅降低**。\n- **更强的安全模型**，用于扩展和工具执行，包括在命令级别阻止危险的扩展 shell 模式。\n\n安全性在这里是设计的一等公民，而非事后添加的功能：\n\n- 基于能力的宿主调用（`tool`\u002F`exec`\u002F`http`\u002F`session`\u002F`ui`\u002F`events`）。\n- 两阶段扩展 `exec` 执行强制机制：首先进行能力检查，然后通过命令中介默认阻止关键的 shell 类型（例如递归删除、磁盘\u002F设备写入、反向 Shell 等），并在严格\u002F安全策略下进一步收紧以阻止更高级别的操作。\n- 在执行路径上实施策略、运行时风险和配额控制。\n- 每个扩展的信任生命周期（`pending` -> `acknowledged` -> `trusted` -> `killed`），配备杀毒开关审计日志和明确的操作员来源证明。\n- 宿主调用通道的紧急控制机制，可在需要立即遏制快速通道行为时，全局或针对某个特定扩展强制切换到兼容通道执行。\n- 使用 `asupersync` 提供的结构化并发，使取消\u002F生命周期行为更加可预测。\n- 可审计的运行时信号\u002F账本以及针对扩展行为的脱敏安全警报。\n\n## 简而言之（Pi\u002FOpenClaw 用户）\n\n以下是最重要的实际安全路径数据（大型会话、端到端行为）：\n\n| 场景 | Rust 总耗时 | Legacy Node 总耗时 | Legacy Bun 总耗时 | Rust 优势 |\n|---|---:|---:|---:|---:|\n| 真实的 1M 会话 | 250.29 ms | 1,238.67 ms | 700.52 ms | 比 Node 快 4.95 倍，比 Bun 快 2.80 倍 |\n| 真实的 5M 会话 | 1,382.12 ms | 5,974.67 ms | 2,959.42 ms | 比 Node 快 4.32 倍，比 Bun 快 2.14 倍 |\n\n| 场景 | Rust RSS | Legacy Node RSS | Legacy Bun RSS | Rust 内存优势 |\n|---|---:|---:|---:|---:|\n| 真实的 1M 会话 | 67,572 KB | 820,380 KB | 875,092 KB | 比 Node 低 12.14 倍，比 Bun 低 12.95 倍 |\n| 真实的 5M 会话 | 268,844 KB | 2,173,096 KB | 3,057,908 KB | 比 Node 低 8.08 倍，比 Bun 低 11.37 倍 |\n\n大规模下的恢复\u002F打开响应速度也更好：\n\n| 场景 | Rust 打开时间 | Legacy Node 打开时间 | Legacy Bun 打开时间 | Rust 优势 |\n|---|---:|---:|---:|---:|\n| 1M 会话恢复 | 17.59 ms | 119.76 ms | 50.83 ms | 比 Node 快 6.81 倍，比 Bun 快 2.89 倍 |\n| 5M 会话恢复 | 58.68 ms | 396.41 ms | 155.63 ms | 比 Node 快 6.76 倍，比 Bun 快 2.65 倍 |\n\n扩展运行时的保障也非常具体：\n\n| 扩展保障信号 | 为什么你应该关注 |\n|---|---|\n| 两阶段 `exec` 保护（`exec` 能力策略 + 命令级中介 + DCG\u002Fheredoc AST 信号） | 危险的 shell 意图会在进程启动前被捕获，包括隐藏在多行包装器中的破坏性载荷。\n| 信任生命周期 + 杀毒开关（`pending\u002Facknowledged\u002Ftrusted\u002Fkilled`） | 你可以立即隔离某个扩展，记录是谁触发了开关以及原因，并且在恢复访问权限之前需要明确的重新确认。\n| 宿主调用通道的杀毒开关控制（`forced_compat_global_kill_switch`、`forced_compat_extension_kill_switch`） | 快速通道的回归问题可以通过强制切换到兼容通道执行来立即遏制，而无需禁用整个扩展系统。\n| 确定性的宿主调用反应堆网络（分片亲和性、有限的 SPSC 通道、背压遥测、可选的 NUMA 板块跟踪） | 在竞争条件下，运行时行为仍然可预测；队列压力和路由决策是可见的，而不是黑箱操作。\n| JS 运行时的启动预热 + 温暖隔离复用 | 运行时创建过程与启动重叠，而温暖复用则使重复的扩展运行保持低延迟，无需像 Node\u002FBun 那样的进程模型。\n| 防篡改的运行时风险账本（`verify` \u002F `replay` \u002F `calibrate`） | 安全决策被哈希链接，并可根据真实的运行时轨迹进行回放或阈值调整。\n\n总之，对于真正的 Pi\u002FOpenClaw 使用场景，Rust 版本不仅更快、内存效率更高，而且在真实工作负载压力下的扩展运行时安全性也显著更强。\n\n\u003Csub>数据来源：`BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md`（最新的安全路径 + 完整编排器检查点，2026-02-19）。\u003C\u002Fsub>\n\n## 我们为何能如此迅速地完成开发\n\n在本 README 中，“我们”指项目所有者以及协作的编码智能体。速度的提升源于运行时设计，而非单一技巧。\n\n| 技术 | 我们如何实现 | 运行时效果 |\n|---|---|---|\n| 冷启动最小化 | 单一静态二进制文件，无需 Node.js 或 Bun 的运行时引导，无 JIT 热身，对扩展运行时路径进行启动预热 | 更快的首次交互时间 |\n| 减少热点路径上的拷贝 | 使用 `Arc`\u002F`Cow` 消息流，零拷贝处理宿主调用与工具负载，减少大量克隆操作的提供者和会话路径 | 降低 CPU 和内存分配压力 |\n| 确定性调度核心 | 类型化的宿主调用操作码、快速通道\u002F兼容通道路由，结合反应堆网格遥测的有界分片队列 | 在并发扩展负载下改善尾延迟 |\n| 高效的长会话存储 | SQLite 会话索引 + v2 辅助进程（分段日志 + 偏移量索引），具备 O(索引+尾部) 的重新打开路径 | 快速恢复大型历史记录 |\n| 针对真实网络优化的流式解析器 | SSE 解析器跟踪已扫描字节数，处理 UTF-8 尾部，规范化数据块边界，并对事件类型字符串进行驻留 | 降低流式传输开销，减少解析器阻塞 |\n| 安全的快速路径控制 | 影子双重执行采样、在偏差或开销过高时自动退避、用于隔离的兼容通道紧急关闭开关 | 在不导致行为悄然漂移的情况下保持优化的高效性 |\n| CI 级别的性能治理 | 场景矩阵、严格的工件契约、失败即关闭的性能门控 | 在发布前捕捉回归问题 |\n\n如需完整的实现清单，请参阅 [性能工程](#performance-engineering)。\n\n## 基准测试方法与声明的完整性\n\n上述基准测试刻意设计为贴近实际、可复现且难以作弊。\n\n我们测量的内容包括：\n\n- **状态匹配的工作负载**：恢复一个大型会话并追加相同的 10 条消息。\n- **真实的端到端工作负载**：恢复 + 追加 + 扩展活动 + 斜杠风格的状态变更 + 分支 + 导出 + 整理。\n- **规模级别**：从 `10 万` 到 `500 万` 个标记类会话状态。\n- **启动\u002F就绪状态**：命令级别的就绪状态（`--help`、`--version`）与长会话工作流分开衡量。\n\n我们如何确保比较公平：\n\n- **基准报告中的两个范围**：\n  - 苹果对苹果（`pi_agent_rust` 对比旧版 `coding-agent`）\n  - 苹果对橙子（在旧版行为被外包的情况下，纳入了旧版栈组件）\n- **发布模式下的二进制文件**，并对每个矩阵单元重复运行。\n- **核心延迟\u002F占用表中不含付费提供商的噪声**（这些核心比较中排除了提供商调用的成本）。\n\n我们如何保证声明的真实性：\n\n- **安全控制始终开启**，即使是在测量安全路径时也是如此（不会为了追求速度而绕过策略、风险或配额限制）。\n- **原始工件被保留**（JSON、追踪和时间输出），并在基准报告中明确指出。\n- **明确披露阻碍因素**：当由于缺少工作区依赖项而无法直接重跑旧版代码时，我们会说明这一点，并改用先前验证过的旧版工件进行对比，而不是假装重跑成功。\n- **解释说明清晰明确**：报告区分了基线部分与全新重跑的结果，以便读者能够清楚地了解哪些数值来自哪次运行。\n- **重视可复现性胜过营销宣传**：除了展示成果之外，还详细介绍了方法论、注意事项以及已知的局限性。\n\n如需完整细节，请参阅：\n\n- `BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md`（方法论 + 结果 + 注意事项 + 原始工件路径）\n\n## 为什么选择 Pi？\n\n| 特性 | Pi（Rust） | 典型的 TS\u002FPython CLI |\n|---------|-----------|----------------------|\n| **启动时间** | \u003C100ms | 500ms-2s |\n| **二进制大小** | \u003C22MB（CI 约束预算） | 100MB+（含运行时） |\n| **空闲内存** | \u003C50MB | 200MB+ |\n| **流式处理** | 原生 SSE 解析器 | 依赖于第三方库 |\n| **工具执行** | 进程树管理 | 基本子进程 |\n| **会话管理** | JSONL 格式，支持分支 | 各不相同 |\n| **不安全代码** | 禁止 | 不适用 |\n\n## 快速示例\n\n```bash\n# 1) 启动交互式会话\npi\n\n# 2) 提问关于代码库的问题\npi \"总结 src 目录下的架构\"\n\n# 3) 内联附加文件\npi @src\u002Fmain.rs \"解释启动流程\"\n\n# 4) 以单次模式运行脚本\npi -p \"列出这个代码差异可能存在的回归风险\"\n\n# 5) 继续上次的项目会话\npi --continue\n\n# 6) 查看可用模型和提供商\npi --list-models\npi --list-providers\n```\n\n---\n\n## 基础库\n\n### asupersync\n\n[asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync) 是一种结构化并发异步运行时，专为需要可预测资源清理的应用程序设计。`pi_agent_rust` 使用的关键特性包括：\n\n- **基于能力的上下文 (`Cx`)**：异步函数接收一个明确的上下文，控制其可执行的操作（HTTP、文件系统、时间）。这使得测试具有确定性。\n- **带 TLS 的 HTTP 客户端**：内置 rustls 的 HTTP API，避免 OpenSSL 依赖地狱。\n- **结构化取消机制**：当父任务取消时，所有子任务都会干净地取消，不会留下孤立的未来值。\n\n`pi_agent_rust` 当前端到端运行在 `asupersync` 上（运行时 + HTTP\u002FTLS + 取消机制）。提供商的流式传输使用一个极简的 HTTP 客户端（`src\u002Fhttp\u002Fclient.rs`），将数据输入自定义的 SSE 解析器（`src\u002Fsse.rs`）。\n\n### rich_rust\n\n[rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust) 是 Will McGugan 的 Python 库 [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) 的 Rust 移植版本。它提供了：\n\n- **标记语法**：`[bold red]error[\u002F]` 渲染为粗体红色文本。\n- **表格**：支持 ASCII 和 Unicode 表格渲染，带有对齐和边框。\n- **面板**：带标题的盒状内容。\n- **进度条**：动画进度指示器。\n- **Markdown**：终端渲染的 Markdown，带有语法高亮。\n- **主题**：跨组件的一致配色方案。\n\n终端 UI 使用 `rich_rust` 进行所有输出格式化，从而提供与基于 Rich 的 Python 工具相同的视觉质量。\n\n---\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n# 安装最新发布的二进制文件\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n如果您已经安装了原始的 TypeScript 版本 `pi`，安装程序会询问是否将 Rust 版本设为默认的 `pi`，并自动创建 `legacy-pi` 以供旧命令使用。\n\n### 2. 配置 API 密钥\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n### 3. 运行\n\n```bash\n# 交互模式\npi\n\n# 带初始消息\npi \"解释这个代码库的结构\"\n\n# 将文件作为上下文读取\npi @src\u002Fmain.rs \"这段代码的作用是什么？\"\n```\n\n---\n\n## 功能\n\n### 流式响应\n\n实时逐 token 流式输出，并支持扩展思考过程：\n\n```\npi \"编写一个快速排序算法\"\n```\n\n您将看到响应逐 token 出现，思考块也会内联显示。\n\n### 7 内置工具\n\n| 工具 | 描述 | 示例 |\n|------|-------------|---------|\n| `read` | 读取文件内容，支持图片 | 读取 src\u002Fmain.rs |\n| `write` | 创建或覆盖文件 | 写入一个新的配置文件 |\n| `edit` | 精准的字符串替换 | 修复第42行的拼写错误 |\n| `bash` | 执行带超时的 Shell 命令 | 运行测试套件 |\n| `grep` | 在上下文中搜索文件内容 | 查找所有 TODO 注释 |\n| `find` | 按模式查找文件 | 查找所有 *.rs 文件 |\n| `ls` | 列出目录内容 | src 目录下有什么？ |\n\n所有工具均包含：\n- 大型输出自动截断（2000 行 \u002F 50KB）\n- 响应中提供详细元数据\n- 对于 bash 命令会清理进程树，避免产生孤儿进程\n\n### 会话管理\n\n会话以 JSONL 文件形式持久化，保存完整的对话历史：\n\n```bash\n# 继续最近的会话\npi --continue\n\n# 打开特定会话\npi --session ~\u002F.pi\u002Fagent\u002Fsessions\u002F--home-user-project--\u002F2024-01-15T10-30-00.jsonl\n\n# 临时会话（不持久化）\npi --no-session\n```\n\n会话支持：\n- 对话分支的树状结构\n- 模型和思考层级变化的追踪\n- 长时间对话的自动压缩\n\n### 扩展思考模式\n\n针对复杂问题启用深度推理：\n\n```bash\npi --thinking high \"设计一个分布式限流器\"\n```\n\n思考层级：`off`、`minimal`、`low`、`medium`、`high`、`xhigh`\n\n### 自定义（技能与提示模板）\n\n- **技能**：将 `SKILL.md` 放入 `~\u002F.pi\u002Fagent\u002Fskills\u002F` 或 `.pi\u002Fskills\u002F` 目录下，通过 `\u002Fskill:name` 调用。\n- **提示模板**：Markdown 文件放在 `~\u002F.pi\u002Fagent\u002Fprompts\u002F` 或 `.pi\u002Fprompts\u002F` 目录下，可通过 `\u002F\u003Ctemplate> [args]` 调用。\n- **包**：使用 `pi install npm:@org\u002Fpi-packages` 分享技能、提示模板、主题和扩展等。\n\n### 自动补全\n\nPi 在交互式编辑器中提供上下文感知的自动补全功能：\n\n- **`@` 文件引用**：输入 `@` 后跟路径片段即可插入文件内容。补全引擎会通过 `ignore` crate 的 `WalkBuilder` 索引项目文件（遵循 `.gitignore`），上限为 5,000 条目。\n- **`\u002F` 斜杠命令**：内置命令（如 `\u002Fhelp`、`\u002Fmodel`、`\u002Ftree`、`\u002Fclear`、`\u002Fcompact`、`\u002Fexit`）以及用户自定义的提示模板和技能都会作为补全选项出现。\n- **模糊评分**：前缀匹配优先于子串匹配。结果按匹配质量排序，再按类型排序（命令 > 模板 > 技能 > 文件 > 路径）。\n- **后台刷新**：后台线程每 30 秒重新索引一次项目文件树，确保补全内容始终最新，且不会阻塞输入循环。\n\n### 三种执行模式\n\nPi 提供三种运行模式，分别适用于不同的工作流程：\n\n| 模式 | 调用方式 | 使用场景 |\n|------|-----------|----------|\n| **交互模式** | `pi`（默认） | 全功能 TUI，支持流式处理、工具调用、会话分支和自动补全 |\n| **打印模式** | `pi -p \"...\"` | 单次响应输出到 stdout，无 TUI，可脚本化 |\n| **RPC 模式** | `pi --mode rpc` | 通过 stdin\u002Fstdout 提供无头 JSON 协议，用于 IDE 集成 |\n\n**交互模式**提供完整体验：多行文本编辑器带有历史记录，可滚动的对话视窗，模型选择器（`Ctrl+L`），作用域内模型循环切换（`Ctrl+P`\u002F`Ctrl+Shift+P`），会话分支导航器（`\u002Ftree`），以及实时的 token 和成本跟踪。\n\n**打印模式**发送一条消息，将响应流式输出到 stdout 并退出。适用于 shell 脚本和一次性查询。\n\n**RPC 模式**暴露了一种以换行符分隔的 JSON 协议，用于程序化控制。客户端发送命令（`prompt`、`steer`、`follow-up`、`abort`、`get-state`、`compact`），并接收流式事件。IDE 扩展和自定义前端正是通过这种方式与 Pi 集成的。有关协议格式，请参阅 [RPC 协议](#rpc-protocol)。\n\n### 扩展\n\nPi 支持两类扩展运行时，并通过能力门控机制连接宿主环境：\n\n- JS\u002FTS 入口在嵌入式 QuickJS 运行时中运行，**无需 Node.js 或 Bun**。\n- `*.native.json` 描述文件则在原生 Rust 描述文件运行时中执行。\n\n- 扩展入口会自动检测：\n  - `.js\u002F.ts\u002F.mjs\u002F.cjs\u002F.tsx\u002F.mts\u002F.cts` 文件直接在嵌入式 QuickJS 中运行（无需转换描述文件）。\n  - `*.native.json` 加载原生 Rust 描述文件运行时。\n  - 当前会话只能同时使用一种运行时体系（JS\u002FTS 或原生描述文件）。\n- **冷启动耗时低于 100ms**（P95），**热启动耗时低于 1ms**（P99）。\n- 提供 `fs`、`path`、`os`、`crypto`、`child_process`、`url` 等 Node.js API 的模拟层。\n- 基于能力的安全机制：扩展通过明确的连接器调用（`tool\u002Fexec\u002Fhttp\u002Fsession\u002Fui`），并进行审计日志记录。\n- 命令级执行中介：危险的 Shell 签名会被分类并阻止执行，在拒绝执行时会提供脱敏警告信息，并记录中介日志。\n- 可信状态生命周期及紧急关闭控制，具有经过审计的状态转换（`pending`\u002F`acknowledged`\u002F`trusted`\u002F`killed`）。\n- 主机调用反应堆网络，具备确定性分片路由、有界队列背压，以及可选的 NUMA 感知遥测功能。\n- 运行时预热路径，通过复用预热隔离区来减少扩展启动成本，使大部分启动费用在首次提示之前就已支付。\n\n### 凭证感知的模型选择\n\n- `\u002Fmodel`（或 `Ctrl+L`）打开一个选择器，专注于当前凭证可用的模型。\n- `Ctrl+P` 和 `Ctrl+Shift+P` 可在限定范围内循环切换模型，而无需打开叠加层。\n- 在模型选择和 `\u002Flogin` 中，提供者 ID 和别名均不区分大小写匹配。\n- 不需要配置凭证的模型可以无需密钥直接运行。\n\n扩展可以注册工具、斜杠命令、事件钩子、标志位、提供者和快捷方式。完整的架构请参阅 [EXTENSIONS.md](EXTENSIONS.md)，224 项扩展的目录及其合规状态和性能预算请见 [docs\u002Fextension-catalog.json](docs\u002Fextension-catalog.json)。\n\n## 扩展验证流水线\n\n该项目采用三轨验证流水线来确保扩展兼容性：\n\n- **自有库（224 个）**：确定性的合规性测试、兼容性矩阵和场景测试套件。\n- **非自有库（777 个）**：源代码获取和优先级排序。\n- **发布版二进制文件与真实提供商的端到端测试**：在未模拟的真实提供商\u002F模型路径上运行 `target\u002Frelease\u002Fpi`。\n\n### 设立原因\n\n- 检测 QuickJS 宿主模拟层和能力策略中的运行时\u002FAPI 回归问题。\n- 捕获危险的扩展 Shell 调用模式，通过发布版二进制文件上的实际命令中介机制。\n- 验证扩展行为是否符合真实提供商的响应，而不仅仅是基于固定数据或模拟流程。\n- 将扩展支持从经验性转变为可衡量的依据。\n- 生成一个优先级队列，用于将非自有库中的候选扩展纳入自有库的合规范围。\n\n### 管道组件\n\n1. **获取未打包的源语料库**\n   - 二进制文件：`ext_unvendored_fetch_run`\n   - 典型命令：\n     - `cargo run --bin ext_unvendored_fetch_run -- run-all --workers 8 --no-probe`\n   - 目的：\n     - 克隆 GitHub 仓库并解压 npm tarball 文件到 `.tmp-codex-unvendored-cache\u002F` 目录中。\n     - 为所有未打包候选生成机器可读的采集状态报告。\n   - 产出物：\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Funvendored_fetch_probe_report.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Funvendored_fetch_probe_events.jsonl`\n\n2. **运行端到端验证编排**\n   - 二进制文件：`ext_full_validation`\n   - 典型命令：\n     - `cargo run --bin ext_full_validation --`\n   - 阶段（按顺序）：\n     1. `refresh_onboarding_queue`（运行 `ext_onboarding_queue`）\n     2. `conformance_shard_0..N`（运行分片矩阵 `ext_conformance_generated`）\n     3. `conformance_failure_dossiers`\n     4. `provider_compat_matrix`\n     5. `scenario_conformance_suite`\n     6. `auto_repair_full_corpus`\n     7. `differential_suite`（可选，通过 `--run-diff` 启用；npm 差异比较通过 `--run-npm-diff` 启用）\n   - 产出物：\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Ffull_validation_report.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002Ffull_validation_report.md`\n     - 以及位于 `tests\u002Fext_conformance\u002Freports\u002F**` 下的各阶段特定报告。\n\n3. **运行开发优先集实时提供商准入测试（发布构建前必须通过）**\n   - 二进制文件：`ext_release_binary_e2e`\n   - 典型命令：\n     - `cargo build --bin pi --bin ext_release_binary_e2e`\n     - `PI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Fdebug\u002Fext_release_binary_e2e --pi-bin target\u002Fdebug\u002Fpi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced --out-json tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json --out-md tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.md`\n   - 目的：\n     - 在支付发布构建成本之前，证明当前代码路径在具有代表性的首个集合上能够端到端正常工作。\n     - 作为晋升到完整发布二进制验证的准入门槛。\n   - 准入条件：\n     - 必须满足 `pass=20 \u002F total=20` 且 `fail=0`。\n   - 产出物：\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.md`\n\n4. **运行完整发布二进制实时提供商端到端测试（步骤 3 通过后）**\n   - 二进制文件：`ext_release_binary_e2e`\n   - 典型命令：\n     - `cargo build --release --bin pi --bin ext_release_binary_e2e`\n     - `PI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Frelease\u002Fext_release_binary_e2e --pi-bin target\u002Frelease\u002Fpi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --extension-policy balanced --out-json tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json --out-md tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.md`\n   - 目的：\n     - 直接为每个选定的扩展案例执行 `target\u002Frelease\u002Fpi`。\n     - 使用实时提供商\u002F模型路径（默认为 `ollama` + `qwen2.5:0.5b`），以测试非模拟的端到端行为。\n     - 输出每个案例的 stdout\u002Fstderr 捕获数据，并生成汇总产物（`pi.ext.release_binary_e2e.v1`）。\n   - 产出物：\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.md`\n     - `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Fcases\u002F*`\n\n5. **聚合与分类处理**\n   - `full_validation_report.json` 汇总了以下内容：\n     - 各阶段的通过\u002F失败情况（`stageSummary`, `stageResults`）\n     - 语料库数量统计（`corpus`）\n     - 打包一致性总计（`conformance`）\n     - 提供商矩阵总计（`providerCompat`）\n     - 场景总计（`scenario`）\n     - 审核队列及判定分类（`reviewQueue`, `verdictCounts`）\n   - 重要解读规则：\n     - `not_tested_unvendored` 表示尚未纳入打包一致性测试的未打包候选；这属于库存状态，而非打包回归问题。\n\n### 推荐运行环境\n\n这些运行会编译大量 crate，并可能占用大量磁盘空间。请将 Cargo 的产物和临时文件指向一个大容量卷：\n\n```bash\nexport CARGO_TARGET_DIR=\"\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002F${USER:-agent}\"\nexport TMPDIR=\"\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002F${USER:-agent}\u002Ftmp\"\nmkdir -p \"$CARGO_TARGET_DIR\" \"$TMPDIR\"\n```\n\n然后运行：\n\n```bash\ncargo run --bin ext_unvendored_fetch_run -- run-all --workers 8 --no-probe\ncargo run --bin ext_full_validation --\n```\n\n### 最新运行快照（2026-02-19）\n\n来自：\n- `tests\u002Fext_conformance\u002Freports\u002Fsharded\u002Fshard_0_report.json`（生成于 `2026-02-18T23:43:48Z`）\n- `tests\u002Fext_conformance\u002Freports\u002Fscenario_conformance.json`（生成于 `2026-02-18T23:11:57Z`）\n- `tests\u002Fext_conformance\u002Freports\u002Fparity\u002Ftriage.json`（生成于 `2026-02-18T23:12:13Z`）\n- `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_firstset_dev_20260219_jobs10_timeout600.json`（于 `release-e2e-20260219T032439Z` 运行）\n- `tests\u002Fext_conformance\u002Freports\u002Frelease_binary_e2e\u002Follama_full_release_20260219_jobs10_timeout600.json`（于 `release-e2e-20260219T033502Z` 运行）\n\n- 打包矩阵一致性：`manifest_count=224`，`tested=224`，`passed=224`，`failed=0`，`skipped=0`\n- 场景套件一致性：`25\u002F25` 通过（`0` 失败，`0` 错误，`0` 跳过）\n- 差异一致性分类样本：`22` 匹配，`0` 不匹配，`3` 跳过（总计 `25`）\n- 开发优先集实时提供商准入测试（`max_cases=20`，调试版二进制）：`20\u002F20` 通过（`0` 失败，`0` 超时）\n- 发布二进制实时提供商完整运行（优化版二进制，`jobs=10`，`timeout=600s`，`ollama` + `qwen2.5:0.5b`）：`224\u002F224` 通过（`0` 失败，`0` 超时）\n\n---\n\n## 安装\n\n### Curl 安装程序（推荐）\n\n```bash\n# 最新版本\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n\n# 非交互式 + 自动更新 PATH\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --yes --easy-mode\n\n# 固定某个发布标签\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash -s -- --version v0.1.0\n\n# 从明确的产物 URL 和校验码 URL 安装\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | \\\n  bash -s -- \\\n    --artifact-url \"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Freleases\u002Fdownload\u002Fv0.1.0\u002Fpi-linux-amd64.tar.xz\" \\\n    --checksum-url \"https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Freleases\u002Fdownload\u002Fv0.1.0\u002FSHA256SUMS\"\n\n# 跳过补全设置（CI\u002F非交互式最小化安装）\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | \\\n  bash -s -- --yes --no-completions\n```\n\n该安装程序具有幂等性，并支持从 TypeScript Pi 的迁移路径：\n- 检测现有的 TS `pi` 命令\n- 提示将 Rust Pi 安装为标准的 `pi`\n- 将旧 CLI 保留在 `legacy-pi` 后面\n- 记录状态以便于干净卸载或恢复\n\n值得注意的安装程序标志：\n- `--offline [TARBALL]`：强制离线模式；可选本地工件路径（`.tar.gz`、`.tar.xz`、`.zip` 或原始二进制文件）\n- `--artifact-url`：强制指定发布工件的 URL\n- `--checksum` \u002F `--checksum-url`：覆盖显式工件的校验和来源\n- `--sigstore-bundle-url`：覆盖 `cosign verify-blob` 使用的 Sigstore 包 URL\n- `--completions auto|off|bash|zsh|fish`：强制指定 shell 补全的安装目标（`off` 等同于 `--no-completions`）\n- `--no-completions`：禁用补全安装\n- `--no-agent-skills`：跳过自动将 `pi-agent-rust` 技能安装到 `~\u002F.claude\u002Fskills\u002F` 和 `~\u002F.codex\u002Fskills\u002F`\n- `--no-verify`：跳过校验和与签名验证（仅用于测试）\n- `--artifact-url` 如果没有 `--version`，则仅在发布模式下使用合成标签；如果工件下载失败，安装程序将退出，而不是尝试回退到源代码\n- 安装程序会尊重 `HTTPS_PROXY` \u002F `HTTP_PROXY` 进行所有网络获取操作\n\n默认情况下，安装程序还会为 Claude Code 和 Codex CLI 安装一个 `pi-agent-rust` 技能：\n- Claude Code：`~\u002F.claude\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md`\n- Codex CLI：`~\u002F.codex\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md`（或者如果设置了 `CODEX_HOME`，则为 `$CODEX_HOME\u002Fskills\u002Fpi-agent-rust\u002FSKILL.md`）\n- 在升级过程中，如果存在先前的安装程序状态，安装程序管理的旧版本遗留条目会被自动移除（幂等、路径范围且无破坏性）。\n\n安装程序回归测试套件（选项 + 校验和 + 签名 + 补全）：\n\n```bash\nbash tests\u002Finstaller_regression.sh\n```\n\n### 分发兼容性契约（打包\u002F调用范围）\n\n为了实现即插即用式的采用，打包和调用兼容性遵循以下契约：\n\n- 本节仅涵盖打包\u002F调用行为；严格的功能性即插即用替换消息由 `docs\u002Fdropin-certification-contract.json` 中的发布认证门控来管理。\n- 标准可执行文件名称在所有发布资产和安装程序管理的安装中均为 `pi`。\n- 安装程序管理的安装还会创建一个 `rpi` 兼容启动器，前提是您的 PATH 上尚未存在冲突的 `rpi` 命令。\n- 现有的 TypeScript `pi` 安装可以就地迁移；之前的命令会被保留为 `legacy-pi`。\n- 如果您将 TypeScript `pi` 保留为标准命令（`--keep-existing-pi`），Rust Pi 将被安装为 `pi-rust`。\n- 在 Apple Silicon 上，即使是从 Rosetta 翻译的 Shell 启动，安装程序也会优先选择原生 arm64 工件。\n- 支持通过 `install.sh --version vX.Y.Z` 进行版本锁定安装，以实现确定性的部署。\n- 每次 GitHub 发布都会提供平台二进制文件以及用于完整性验证的 `SHA256SUMS`。\n\n代表性烟雾测试：\n\n```bash\n# 标准命令应存在并可执行\ncommand -v pi\npi --version\npi --help >\u002Fdev\u002Fnull\n\n# 如果进行了 TS 迁移，旧命令仍然可用\ncommand -v legacy-pi && legacy-pi --version\n```\n\n### 从源码编译\n\n需要 Rust nightly（2024 年版特性）：\n\n```bash\n# 安装 Rust nightly\nrustup install nightly\nrustup default nightly\n\n# 克隆并构建\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust.git\ncd pi_agent_rust\ncargo build --release\n\n# 二进制文件位于 target\u002Frelease\u002Fpi\n.\u002Ftarget\u002Frelease\u002Fpi --version\n\n# 若要进行系统级安装（--locked 可确保可重复的依赖解析）\ncargo install --path . --locked\n```\n\n### 依赖项\n\nPi 的运行时依赖项非常少：\n- `fd`：用于 `find` 工具（可通过 `apt install fd-find` 或 `brew install fd` 安装）\n- `rg`：用于 `grep` 工具（可通过 `apt install ripgrep` 或 `brew install ripgrep` 安装）\n\n### 卸载\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Funinstall.sh\" | bash\n```\n\n默认情况下，卸载会移除安装程序管理的 Rust 二进制文件\u002F别名和技能目录，\n然后恢复之前保留的 TypeScript `pi`（如果有的话）。\n\n---\n\n## 命令\n\n### 基本用法\n\n```bash\npi [OPTIONS] [MESSAGE]...\n\n# 示例\npi                              # 启动交互式会话\npi \"Hello\"                      # 带消息启动\npi @file.rs \"Explain this\"      # 将文件作为上下文加入\npi -p \"Quick question\"          # 打印模式（无会话）\n```\n\n交互式文件引用：\n- 在编辑器中输入 `@relative\u002Fpath` 可附加文件内容（自动补全会插入 `@` 形式）。\n\n### 选项\n\n| 选项 | 描述 |\n|--------|-------------|\n| `-c, --continue` | 继续最近的会话 |\n| `-r, --resume` | 打开会话选择界面 |\n| `--session \u003CPATH>` | 打开特定的会话文件 |\n| `--session-dir \u003CDIR>` | 覆盖本次运行的会话存储目录 |\n| `--session-durability strict|balanced|throughput` | 调整持久化耐用性模式 |\n| `--no-session` | 不保存对话 |\n| `-p, --print` | 单一回复，无交互 |\n| `--mode text|json|rpc` | 输出\u002F协议模式 |\n| `--provider \u003CNAME>` | 强制指定本次运行的提供商（支持别名） |\n| `--model \u003CMODEL>` | 使用的模型（自动选择后备：`anthropic\u002Fclaude-opus-4-5`，然后 `openai\u002Fgpt-5.1-codex`，再然后 `google\u002Fgemini-2.5-pro`） |\n| `--thinking \u003CLEVEL>` | 思考级别：关闭\u002F极简\u002F低\u002F中\u002F高\u002F超高 |\n| `--tools \u003CTOOLS>` | 逗号分隔的工具列表 |\n| `--api-key \u003CKEY>` | API 密钥（或使用提供商特定的环境变量，如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等） |\n| `--extension-policy safe|balanced|permissive` | 扩展能力配置文件 |\n| `--repair-policy off|suggest|auto-safe|auto-strict` | 扩展自动修复策略 |\n| `--list-models [PATTERN]` | 列出可用模型（可选模糊筛选） |\n| `--list-providers` | 列出标准提供商 ID、别名和认证环境变量键 |\n| `--export \u003CPATH>` | 将会话文件导出为 HTML |\n\n其他高杠杆标志：\n\n- `--no-migrations` 用于跳过启动迁移检查\n- `--explain-extension-policy` 用于打印有效的功能决策并退出\n- `--explain-repair-policy` 用于打印有效的修复策略解析结果并退出\n\n### 子命令\n\n```bash\n# 软件包管理\npi install \u003Csource> [-l|--local]    # 安装软件包源并添加到设置中\npi remove \u003Csource> [-l|--local]     # 从设置中移除软件包源\npi update [source]                 # 更新所有（或单个）未锁定的软件包\npi list                            # 列出设置中的用户和项目软件包\n\n# 配置\npi config                          # 显示设置路径 + 优先级\n```\n\n更多实用子命令：\n\n```bash\n\n# 扩展目录索引 + 发现\npi update-index\npi search \"git\"\npi info pi-search-agent\n\n# 环境与扩展诊断\npi doctor\npi doctor --only sessions --format json\npi doctor .\u002Fpath\u002Fto\u002Fextension --policy safe --fix\n\n# 会话存储迁移（JSONL -> v2 sidecar 存储）\npi migrate ~\u002F.pi\u002Fagent\u002Fsessions --dry-run\npi migrate ~\u002F.pi\u002Fagent\u002Fsessions\n```\n\n- `update-index` 刷新 `search` 和 `info` 使用的扩展索引元数据。\n- `search` 和 `info` 允许你在不离开 CLI 的情况下发现和检查扩展元数据。\n- `doctor` 检查配置、目录、认证、Shell 设置、会话以及扩展兼容性。\n- `migrate` 验证或创建 v2 会话 sidecar 格式，以在更大历史记录上实现更快的恢复。\n\n---\n\n## 配置\n\nPi 从 `~\u002F.pi\u002Fagent\u002Fsettings.json` 读取配置：\n\n```json\n{\n  \"default_provider\": \"anthropic\",\n  \"default_model\": \"claude-opus-4-5\",\n  \"default_thinking_level\": \"medium\",\n\n  \"compaction\": {\n    \"enabled\": true,\n    \"reserve_tokens\": 8192,\n    \"keep_recent_tokens\": 20000\n  },\n\n  \"retry\": {\n    \"enabled\": true,\n    \"max_retries\": 3,\n    \"base_delay_ms\": 1000,\n    \"max_delay_ms\": 30000\n  },\n\n  \"images\": {\n    \"auto_resize\": true,\n    \"block_images\": false\n  },\n\n  \"terminal\": {\n    \"show_images\": true,\n    \"clear_on_shrink\": false\n  },\n\n  \"shell_path\": \"\u002Fbin\u002Fbash\",\n  \"shell_command_prefix\": \"set -e\"\n}\n```\n\n### 配置优先级\n\n设置按优先级顺序解析（第一个匹配的生效）：\n\n1. **CLI 标志**（`--model`、`--thinking`、`--provider` 等）\n2. **环境变量**（`ANTHROPIC_API_KEY`、`PI_CONFIG_PATH` 等）\n3. **项目设置**（工作目录中的 `.pi\u002Fsettings.json`）\n4. **全局设置**（`~\u002F.pi\u002Fagent\u002Fsettings.json`）\n5. **内置默认值**\n\n这意味着 CLI 标志始终覆盖 `settings.json` 中的值，而项目级别的设置则覆盖全局设置。\n\n### 资源解析\n\n技能、提示模板、主题和扩展遵循相同的解析顺序：\n\n1. CLI 指定的路径（`--skill`、`--prompt-template`、`--theme`、`-e`）\n2. 项目目录（`.pi\u002Fskills\u002F`、`.pi\u002Fprompts\u002F`、`.pi\u002Fthemes\u002F`、`.pi\u002Fextensions\u002F`）\n3. 全局目录（`~\u002F.pi\u002Fagent\u002Fskills\u002F`、`~\u002F.pi\u002Fagent\u002Fprompts\u002F` 等）\n4. 已安装的包（`~\u002F.pi\u002Fagent\u002Fpackages\u002F`）\n\n当多个资源具有相同名称时，第一个出现的资源将被使用。冲突会被记录为诊断信息。\n\n**提示模板展开** 支持位置参数：`$1`、`$2`、`$@`（所有参数）以及切片语法 `${@:start}`、`${@:start:length}`。例如，一个模板以 `\u002Freview src\u002Fmain.rs --strict` 调用时，`src\u002Fmain.rs` 将作为 `$1`，`--strict` 将作为 `$2`。\n\n### 环境变量\n\n| 变量 | 描述 |\n|----------|-------------|\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥 |\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `GOOGLE_API_KEY` | Google Gemini API 密钥 |\n| `AZURE_OPENAI_API_KEY` | Azure OpenAI API 密钥 |\n| `COHERE_API_KEY` | Cohere API 密钥 |\n| `GROQ_API_KEY` | Groq API 密钥（与 OpenAI 兼容） |\n| `DEEPINFRA_API_KEY` | DeepInfra API 密钥（与 OpenAI 兼容） |\n| `CEREBRAS_API_KEY` | Cerebras API 密钥（与 OpenAI 兼容） |\n| `OPENROUTER_API_KEY` | OpenRouter API 密钥（与 OpenAI 兼容） |\n| `MISTRAL_API_KEY` | Mistral API 密钥（与 OpenAI 兼容） |\n| `MOONSHOT_API_KEY` | Moonshot\u002FKimi API 密钥（与 OpenAI 兼容） |\n| `DASHSCOPE_API_KEY` | DashScope\u002FQwen API 密钥（与 OpenAI 兼容） |\n| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（与 OpenAI 兼容） |\n| `FIREWORKS_API_KEY` | Fireworks API 密钥（与 OpenAI 兼容） |\n| `TOGETHER_API_KEY` | Together API 密钥（与 OpenAI 兼容） |\n| `PERPLEXITY_API_KEY` | Perplexity API 密钥（与 OpenAI 兼容） |\n| `XAI_API_KEY` | xAI API 密钥（与 OpenAI 兼容） |\n| `PI_CONFIG_PATH` | 自定义配置文件路径 |\n| `PI_CODING_AGENT_DIR` | 覆盖全局配置目录 |\n| `PI_PACKAGE_DIR` | 覆盖包目录 |\n| `PI_SESSIONS_DIR` | 自定义会话目录 |\n\n---\n\n## 架构\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                           CLI (clap)                            │\n│  • 参数解析    • @file 展开    • 子命令       │\n└─────────────────────────────────┬───────────────────────────────┘\n                                  │\n┌─────────────────────────────────▼───────────────────────────────┐\n│                          Agent Loop                             │\n│  • 消息历史     • 工具迭代    • 事件回调    │\n└────────┬──────────────────────┬──────────────────────┬──────────┘\n         │                      │                      │\n┌────────▼────────┐  ┌─────────▼──────────┐  ┌───────▼──────────┐\n│ Provider Layer  │  │  Tool Registry     │  │  Extension Mgr     │\n│ • Anthropic     │  │  • read  • bash    │  │  • QuickJS JS\u002FTS   │\n│ • OpenAI (Chat\u002F │  │  • write • grep    │  │  • Native descriptor│\n│   Responses)    │  │  • edit  • find    │  │    runtime          │\n│ • Gemini\u002FCohere │  │  • ls              │  │  • Capability policy│\n│ • Azure\u002FBedrock │  │  • ext-registered  │  │  • Node shims       │\n│ • Vertex\u002FCopilot│  │                    │  │  • Event hooks      │\n│ • GitLab\u002FExt    │  │                    │  │  • Runtime risk ctl │\n└────────┬────────┘  └─────────┬──────────┘  └───────┬──────────┘\n         │                     │                      │\n┌────────▼─────────────────────▼──────────────────────▼──────────┐\n│                     Session Persistence                         │\n│  • JSONL 格式 (v3)   • 树形结构   • 会话索引\u002F缓存  │\n│  • 每个项目目录    • 可选 SQLite 后端                │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n当前 `src\u002Fproviders\u002F` 中的原生提供商包括 `anthropic`、`openai`、`openai_responses`、`gemini`、`cohere`、`azure`、`bedrock`、`vertex`、`copilot` 和 `gitlab`，而通过扩展提供的 `streamSimple` 提供商则通过相同的代理循环进行路由。\n\n### 关键设计决策\n\n1. **无不安全代码**：项目范围内强制执行 `#![forbid(unsafe_code)]`\n2. **流式优先**：自定义 SSE 解析器，不会阻塞响应\n3. **进程树管理**：使用 `sysinfo` crate 确保没有孤儿进程\n4. **结构化错误**：使用 `thiserror` 并为每个组件定义特定的错误类型\n5. **速度导向的发布配置**：启用 LTO + 去除符号 + `opt-level = 3` 以提升运行时性能\n\n### asupersync 上下文与 TypeScript Pi (pi-mono)\n\n这个 Rust 移植版本保留了 Pi 的用户体验，但有意改变了运行时底层。最初的 TypeScript Pi（`pi-mono`、`packages\u002Fcoding-agent`）基于 Node.js 和包级别的抽象构建。而 `pi_agent_rust` 则将这些行为迁移到 `asupersync` 原语之上，使得生命周期保证在运行时模型中变得明确。\n\n| 关注点 | TypeScript Pi (pi-mono 基线) | pi_agent_rust + asupersync |\n|---------|----------------------------------|----------------------------|\n| **运行时模型** | Node 事件循环 + Promise\u002FAbortSignal 约定 | `RuntimeBuilder` + 显式的反应器和运行时句柄 |\n| **异步所有权** | 由框架\u002F库代码协调的任务生命周期 | 结构化的任务所有权以及显式的跨线程通道（用于 TUI\u002FRPC 桥接） |\n| **取消语义** | 主要依赖 API 和工具层的约定 | 运行时感知的取消检查 + 工具中的有界超时处理 |\n| **I\u002FO 能力形态** | 环境化的 Node API + 扩展层策略 | 能力作用域的上下文（`AgentCx` 包含于 `asupersync::Cx` 中）以及显式的宿主调用策略 |\n| **HTTP 流式传输** | 取决于提供者和客户端 | 专门构建的 asupersync HTTP\u002FTLS 客户端，为自定义 SSE 解析器提供数据流 |\n| **确定性测试钩子** | 传统的异步测试设置 | 广泛应用于单元\u002F集成测试的 asupersync 测试\u002F运行时钩子 |\n\n为何这在实践中很有用：\n- 在中止或超时时，失败行为更加可预测，因为取消会在明确的循环边界和工具运行器中被检查。\n- 资源生命周期更清晰，因为运行时、定时器和 I\u002FO 路径都共享同一个并发基础。\n- 隐藏的耦合更少，因为主要不变量存在于 Rust 类型和算法中，而不是分散在框架约定之中。\n\n### 运行时不变量（及其重要性）\n\n以下是我们在此实现中所依赖的具体不变量：\n\n1. **回合作用域内的代理生命周期**\n   - 主循环会以稳定的顺序发出 `AgentStart`、`TurnStart`、`TurnEnd` 和 `AgentEnd` 事件。\n   - 工具递归受到 `max_tool_iterations`（默认值为 50）的限制，以避免无界自调用循环。\n   - 优点：为 TUI\u002FRPC 消费者提供稳定的事件顺序，并确保可预测的终止行为。\n\n2. **明确的中止和超时行为**\n   - 代理的中止检查发生在回合边界处以及工具执行前后。\n   - `bash` 超时遵循清晰的升级路径：先终止进程树，再进入宽限期，最后强制杀死。\n   - 优点：减少“挂起”会话，并在激进使用工具时降低孤儿进程的风险。\n\n3. **会话写入具有崩溃恢复能力**\n   - JSONL 先将写入保存到临时文件，然后以原子方式持久化。\n   - 会话索引使用 SQLite WAL 加锁文件协调机制，支持多实例并发操作。\n   - 优点：在多进程使用场景下，能更好地保证持久性和恢复可靠性。\n\n4. **压缩由阈值驱动且考虑边界**\n   - 触发条件：估计的上下文 token 数超过 `context_window - reserve_tokens`。\n   - 截断逻辑优先选择用户回合边界，并保留最近的上下文预算。\n   - 优点：压缩可以在不破坏近期任务连续性的情况下回收上下文。\n\n5. **能力策略采用失败封闭和优先级定义**\n   - 决策顺序：按扩展的拒绝 -> 全局拒绝 -> 按扩展的允许 -> 默认能力 -> 模式回退。\n   - 优点：策略结果可解释、确定且可审计。\n\n6. **流式解析器能够容忍真实的网络分块**\n   - SSE 解析器可以处理 CR\u002FLF 变体、多行 `data:` 字段、部分 UTF-8 尾部以及流结束时的刷新。\n   - 优点：无论服务提供商如何，也不论网络是否碎片化，增量渲染都能保持稳健。\n\n### 从 asupersync 带入 Pi 的设计原则\n\n以下 `asupersync` 原则直接体现在 `pi_agent_rust` 的架构中：\n\n- **单一异步基础**：运行时、定时器、文件系统以及 HTTP\u002FTLS 都运行在同一套连贯的基础之上。\n- **显式上下文传递**：在子系统边界处（代理\u002F工具\u002F会话\u002FRPC），`AgentCx` 包装了 `asupersync::Cx`。\n- **有限操作优先于尽力清理**：超时路径和压缩阈值都是参数化的，并且可强制执行。\n- **用于测试的确定性钩子**：定时器驱动的睡眠以及 asupersync 测试辅助函数，减少了非确定性的不稳定现象。\n\n与最初的 TypeScript 实现相比，这种做法将更多的正确性责任转移到运行时和核心算法本身，而不是主要依赖于生态系统的约定。\n\n### 其他主要差异（原始 pi-mono 与 Rust 移植版）\n\n这是第二次对比，重点关注高影响的架构性差异及其背后的原因。\n\n| 领域 | 原始 pi-mono (`packages\u002Fcoding-agent`) | `pi_agent_rust` | 为何存在这些差异 |\n|------|---------------------------------------------|------------------|----------------------------|\n| **分发模型** | npm 包 (`npm install -g @mariozechner\u002Fpi-coding-agent`) | 单一 Rust 二进制文件 (`pi`) | 移除 Node 运行时依赖，提升启动和部署的可移植性 |\n| **执行界面** | 交互式 + 打印 + JSON 模式 + RPC + SDK | 交互式 + 打印 + JSON 模式 + RPC (+ 在 `docs\u002Fsdk.md` 中记录的 Rust SDK) | 严格的无缝替换仍需通过发布准入；JSON\u002FRPC\u002FSDK 的声明必须有认证文档支持 |\n| **默认内置工具姿态** | 默认为 `read\u002Fwrite\u002Fedit\u002Fbash`（其他也可用） | 将七个内置工具视为一等公民（`read\u002Fwrite\u002Fedit\u002Fbash\u002Fgrep\u002Ffind\u002Fls`） | 无需额外配置即可使用常见的代码导航和 Shell 工作流 |\n| **扩展信任模型** | 扩展\u002F包模型被描述为拥有完整系统访问权限 | 内嵌运行时，具备能力约束的宿主调用和策略配置文件 | 降低环境权限，使扩展行为可审计，并采用默认拒绝策略 |\n| **会话架构侧重点** | JSONL 树形会话模型及分支导航 | JSONL v3 树 + 显式会话索引（SQLite 辅助数据库）+ 可选 SQLite 会话后端 | 更快的大规模恢复与查找，以及更安全的多实例协调 |\n| **流式传输栈** | Node 运行时网络栈 | 专用 HTTP\u002FTLS 客户端 + asupersync 上的自定义 SSE 解析器 | 对长流中的分块、解析和错误处理拥有更强的控制力 |\n| **取消\u002F超时机制** | 平台\u002F事件循环取消约定 | 显式中止信号、受限工具迭代次数、进程树终止 | 最大限度减少挂起或孤儿进程，并在负载下使停止行为具有确定性 |\n| **运行时上下文模型** | 框架级约定和扩展 API | 显式 `AgentCx`\u002F`asupersync::Cx` 能力范围内的上下文线程化 | 将效应边界和可测试性作为首要的架构约束 |\n\n这些差异的实际影响：\n- 扩展\u002F包工作流在两种实现中均兼容。\n- 不可妥协的目标是在所有用例中实现对 pi-mono 的严格无缝替换。\n- 严格无缝替换的语言由 `docs\u002Fdropin-certification-contract.json` 和 `docs\u002Fdropin-parity-gap-ledger.json` 中的未解决差距状态来决定。\n- `docs\u002Fparity-certification.json` 仅作为信息性快照，不取代关于严格替换声明的发布准入政策。\n\n### 算法机制：pi-mono 基线与 Rust 实现\n\n本节比较了实现等效高层行为的具体机制。\n\n| 算法 | pi-mono 基线机制 | Rust 实现机制 | 为何存在 Rust 版本 |\n|-----------|-----------------------------|-------------------------------|-----------------------------|\n| **压缩后会话上下文重建** | `buildSessionContext()` 发出压缩摘要，随后发送来自 `firstKeptEntryId`（压缩前路径）的消息，最后是压缩后的条目 | `to_messages_for_current_path()` 使用相同的顺序，并在缺失 `first_kept_entry_id` 时提供回退 | 避免当压缩锚点孤立或损坏时发生无声的上下文丢失 |\n| **JSONL 持久化** | 增量追加 (`appendFileSync`) 加上完全重写 (`writeFileSync`) 用于迁移和重写 | 通过临时文件保存 + 原子性持久化\u002F替换 | 使磁盘上的会话状态在保存操作期间具备崩溃容错能力 |\n| **会话发现\u002F恢复** | 目录\u002F文件扫描及 JSONL 文件的修改时间排序 | SQLite 会话索引辅助数据库 + WAL + 锁文件 + 因过期触发的全量重新索引 | 限制恢复查询成本，并协调并发进程 |\n| **压缩标记计数** | 使用助手用量（`totalTokens` 或 `input+output+cacheRead+cacheWrite`）加上启发式尾部估算 | 使用助手用量（`total_tokens` 或 `input+output`）加上启发式尾部估算；固定图像标记估算 | 在各提供商缓存标记报告不一致的情况下保持会计稳定，同时保持保守态度 |\n| **切断点 + 分割回合处理** | 有效切断点排除工具结果；分割回合以历史记录 + 回合前文上下文的形式总结 | 相同的切断点分类和分割回合策略，在 Rust 条目\u002F消息模型中实现 | 在预算压力下保持工具调用与结果的邻接性，以及回合的一致性 |\n| **Bash 超时\u002F进程清理** | 超时\u002F中止会杀死进程树（`killProcessTree`），并返回截断尾部的输出 | 超时升级（先 `TERM`，再宽限，最后 `KILL`）+ 进程树遍历 + Shell 退出陷阱 + 截断尾部 | 强制进行有限清理，减少后台作业产生的后代进程泄漏 |\n| **流式事件解码** | 传输语义对外暴露（`sse`\u002F`websocket`\u002F`auto`）；解析细节为运行时内部实现 | 显式 SSE 解析器，具备 BOM 去除、CR\u002FLF 规范化、UTF-8 尾部缓冲及结束时强制刷新功能 | 使字节到事件的行为具有确定性，且独立于提供商 SDK |\n\n### 功能超集亮点（超出 pi-mono 基线）\n\n上述章节比较了各项机制。本节则重点列出此 Rust 移植版本中特有的功能，而这些功能并未包含在 pi-mono 的基准实现模型中。\n\n| Rust 移植版功能 | 为何有用\u002F引人注目 |\n|-------------------|-----------------------------|\n| **`pi doctor` 诊断命令**（文本\u002FJSON\u002FMarkdown 格式、`--only`、`--fix`、扩展兼容性检查） | 提供可操作的环境与兼容性诊断信息，支持 CI 阻断（失败时返回非零值），并能自动修复安全问题，如缺失目录或权限不足等 |\n| **基于能力的扩展策略配置文件**（`safe` \u002F `balanced` \u002F `permissive`），并支持按扩展覆盖 | 允许运维人员以明确的能力边界运行共享扩展，而非赋予其系统范围的完全访问权限 |\n| **对敏感信息感知的扩展环境变量过滤**（通过 `pi.env()` 块禁用特定键\u002F令牌\u002F密钥） | 减少因扩展代码路径而导致凭据意外泄露的风险 |\n| **按扩展的信任生命周期与紧急关闭审计追踪**（`pending`\u002F`acknowledged`\u002F`trusted`\u002F`killed` 状态，以及 `kill_switch` 和 `lift_kill_switch` 操作） | 支持即时隔离、明确的运维人员操作记录，并在审查后受控地重新启用 |\n| **宿主调用兼容模式下的应急控制**（全局或按扩展强制切换兼容模式，并附带原因代码） | 为运维人员提供确定性的回滚路径，以便在快速响应场景下处理突发事件，同时不中断扩展服务可用性 |\n| **针对扩展宿主调用的运行时风险控制器**（可配置，默认为故障封闭） | 在静态策略之外增加一层额外的执行约束，用于检测扩展调用流程中的可疑运行时行为 |\n| **针对 Shell 路径的参数感知型运行时风险评分**（`dcg_rule_hit`、`dcg_heredoc_hit`，以及对 Bash\u002FPython\u002FJS\u002FTS\u002FRuby 中 here document AST 的检查） | 在宿主调用执行前，检测隐藏在多行脚本和封装命令中的破坏性意图 |\n| **防篡改的运行时风险账本工具**（`ext_runtime_risk_ledger verify|replay|calibrate`） | 安全决策以哈希链形式串联，可从实际运行轨迹中进行验证、重放及阈值校准 |\n| **统一的事件证据包导出**（包括风险账本、安全告警、宿主调用遥测、执行中介日志、秘密代理事件等） | 事件响应团队可直接从一套结构化归档中进行分类处理，无需再手动拼接临时日志 |\n| **具有可选 NUMA 分片池的确定性宿主调用反应器网格**（分片亲和性、全局有序排空、有界 SPSC 队列、遥测功能） | 在高负载情况下仍能保持扩展调度的可预测性，并暴露队列与背压行为以便调优 |\n| **预热隔离池 + 启动前预热交接** | 将 JS 运行时的初始化工作移至首次交互之前，并在多次运行之间安全地复用已预热的状态 |\n| **扩展前置静态分析**（导入模块扫描与禁止模式检测，并提供策略感知提示） | 在运行时执行之前捕获潜在的风险模式 |\n| **兼容 Node\u002FBun 的扩展运行时，且无需依赖 Node\u002FBun**（内置 QuickJS 并提供适配层） | 可以在单一原生二进制部署模式下运行遗留扩展工作流 |\n| **扩展兼容性扫描器 + 符合性测试套件** | 使扩展支持情况可度量、可审计，而非仅凭经验之谈 |\n| **SQLite 会话索引辅助组件**（WAL 日志、锁机制以及过时索引重建路径） | 实现大规模会话的快速恢复与列表操作，而无需每次查询都扫描所有 JSONL 文件 |\n| **Session Store V2 回滚与迁移账本**（分段日志、检查点及回滚事件） | 长时间会话的恢复可以回退到已知检查点，并明确迁移或回滚的操作记录 |\n| **可选的 SQLite 会话存储后端**（`sqlite-sessions` 功能） | 支持希望使用数据库持久化会话数据的同时，也保留 JSONL 存储方式的部署场景 |\n| **抗崩溃的会话保存路径**（临时文件 + 原子化持久化） | 提升会话文件写入时的可靠性，减少部分写入失败的情况 |\n| **统一的宿主调用分发器与类型化分类映射**（`timeout` \u002F `denied` \u002F `io` \u002F `invalid_request` \u002F `internal`） | 提供一致的扩展\u002F运行时错误语义，便于客户端处理 |\n| **故障封闭的证据溯源门控**（`run_id`\u002F`correlation_id` 以及跨产物的溯源检查） | 在发布阶段拒绝陈旧或被挑选出来的符合性\u002F性能相关产物 |\n| **带有稳定机器码的结构化认证诊断信息** | 在不泄露敏感凭据信息的前提下，提升故障排除与运维可见性 |\n\n---\n\n## 深度解析：核心算法\n\n### 基于数学的决策系统\n\nPi 有意在能够改善运行时行为或提升基准测试置信度的地方使用高级数学。其目标并非为了“在文档中堆砌华丽公式”，而是为了做出更安全的策略决策、更快地适应负载变化，以及提供更可信的性能归因。\n\n### 切换状态检测（CUSUM + BOCPD）\n\n在扩展调度器中，Pi 结合 CUSUM 方法与贝叶斯在线变点检测技术，以尽早发现负载状态的变化（例如当宿主调用流量突然激增或骤降时）。\n\n$$\nS_t^+ = \\max\\left(0,\\;S_{t-1}^+ + (-z_t - k)\\right), \\quad\nS_t^- = \\max\\left(0,\\;S_{t-1}^- + (z_t - k)\\right)\n$$\n\n$$\nH(r)=\\frac{1}{\\lambda}, \\quad\nP(r_t=0 \\mid x_{1:t}) \\propto \\sum_r P(r_{t-1}=r)\\,H(r)\\,P(x_t \\mid r)\n$$\n\n直观理解：CUSUM 能够捕捉持续性的漂移；而 BOCPD 则能在不设置僵硬固定阈值的情况下，及时发现突发的状态切换。\n\n### 一致性预测区间\n\nPi 会跟踪非一致性分数（即当前观测值与移动平均值之间的绝对残差），并将超出区间的行为视为异常。\n\n$$\nq = \\text{score}_{\\lceil (n+1)\\cdot \\text{confidence} \\rceil - 1}, \\quad\n\\text{异常若 } |x_t - \\mu_t| > q\n$$\n\n直观理解：阈值会根据近期行为动态调整，而不是硬编码一个固定的延迟上限。\n\n### PAC-Bayes 安全边界\n\nPi 的安全防护机制包含基于 PAC-Bayes-kl 的扩展结果边界，并会在该边界过高时拒绝激进的优化策略。\n\n$$\n\\mathrm{kl}(\\hat q \\,\\|\\, q_{\\text{bound}})\\;\\le\\;\\frac{\\mathrm{KL}(Q\\|P)+\\ln\\!\\left(2\\sqrt{n}\u002F\\delta\\right)}{n}\n$$\n\n直观理解：这为真实误差风险设定了一个明确的不确定性感知上限，在允许进一步激进的运行时行为之前加以限制。\n\n### 策略外评估（IPS\u002FWIS\u002FDR + ESS + 遗憾门控）\n\n在批准任何策略变更之前，Pi 会先根据历史轨迹数据评估候选行为：\n\n$$\nw_i=\\frac{\\pi(a_i\\mid x_i)}{\\mu(a_i\\mid x_i)}, \\quad\n\\hat V_{\\text{IPS}}=\\frac{1}{n}\\sum_i w_i r_i\n$$\n\n$$\n\\hat V_{\\text{WIS}}=\\frac{\\sum_i w_i r_i}{\\sum_i w_i}, \\quad\n\\hat V_{\\text{DR}}=\\frac{1}{n}\\sum_i\\left(\\hat r_i + w_i(r_i-\\hat r_i)\\right)\n$$\n\n$$\nN_{\\text{eff}}=\\frac{(\\sum_i w_i)^2}{\\sum_i w_i^2}, \\quad\n\\Delta_{\\text{regret}}=\\bar r_{\\text{baseline}}-\\hat V_{\\text{DR}}\n$$\n\n直观理解：如果样本支持不足、不确定性较高，或者估计的遗憾值超过阈值，Pi 将采取故障封闭策略。\n\n### 基于VOI的实验选择\n\nVOI规划器会在严格的开销预算下，优先选择能够带来最大预期学习收益的探测。\n\n$$\n\\text{priority}_i \\propto \\frac{\\text{utility}_i}{\\text{overhead}_i}\n$$\n\n直观理解：只运行那些很可能改变决策的实验；跳过过时或价值低的探测。\n\n### 加权瓶颈归因（基准测试）\n\n在阶段1的矩阵基准测试中，Pi会根据实际的工作负载大小（`session_messages`）计算各阶段的加权贡献，并报告置信区间。\n\n$$\n\\text{weighted\\_contribution}_s\n=\n\\frac{\\sum_i w_i\\,m_{i,s}}{\\sum_i w_i\\,t_i}\\cdot 100,\n\\quad w_i=\\text{session\\_messages}_i\n$$\n\n$$\nn_{\\text{eff}}=\\frac{(\\sum_i w_i)^2}{\\sum_i w_i^2}, \\quad\n\\mathrm{CI}_{95}=\\mu \\pm 1.96\\sqrt{\\frac{\\sigma^2}{n_{\\text{eff}}}}\n$$\n\n直观理解：优先关注对真实端到端延迟起主导作用的部分，而不仅仅是孤立的微基准热点。\n\n### 在线凸优化控制 + 损失跟踪\n\nPi还包含一个用于批处理\u002F时间片控制的在线调优路径，并具有明确的回滚行为：\n\n$$\n\\tau_{t+1}\n=\n\\mathrm{clip}\\!\\left(\\tau_t - \\eta\\nabla_{\\tau}\\mathcal{L}_t,\\;\\tau_{\\min},\\tau_{\\max}\\right)\n$$\n\n直观理解：系统会持续自适应调整，但如果瞬时损失超过回滚阈值，它会立即恢复到更安全的配置。\n\n### 数学概览\n\n| 技术 | 在Pi中的位置 | 为何有帮助 |\n|----------|-------------|--------------|\n| CUSUM + BOCPD | 扩展调度器的流量模式检测器 | 早期且稳健地检测流量模式切换 |\n| 合规性区间 | 安全保障 | 自适应异常检测，无需静态魔法数字 |\n| PAC-Bayes界 | 安全保障的否决路径 | 当不确定性\u002F风险过高时，采取保守关闭策略 |\n| IPS\u002FWIS\u002FDR + ESS | 离策略评估器 | 只有在充分证据支持时才批准策略变更 |\n| VOI规划 | 实验调度器 | 将开销预算用于最高价值的探测 |\n| 加权归因 + 置信区间 | 阶段1性能矩阵报告 | 根据真实的用户影响对优化工作进行排序 |\n| OCO + 损失回滚 | 运行时控制器 | 在负载下自适应调整，同时限制不安全漂移 |\n\n### SSE流式解析器\n\nSSE（服务器发送事件）解析器是针对Anthropic流式响应格式的自定义实现。与基于库的方法不同，该解析器以状态机的形式逐字节处理数据：\n\n```\n字节 → 行缓冲区 → 事件解析器 → 类型化StreamEvent\n```\n\n**关键特性：**\n\n| 属性 | 实现方式 |\n|----------|----------------|\n| **缓冲** | 尽可能零拷贝；仅在行不完整时才累积 |\n| **事件类型** | 12种不同变体：MessageStart、ContentBlockStart、ContentBlockDelta、ContentBlockStop、MessageDelta、MessageStop、Ping、Error以及思考相关的特殊事件 |\n| **错误恢复** | 格式错误的事件会被记录，但不会导致流中断 |\n| **内存** | 固定大小的滚动缓冲区，防止内存无限制增长 |\n\n解析器能够处理以下边缘情况：\n- 多行`data:`字段（用换行符连接）\n- 跨TCP包边界分割的事件\n- `event:`字段出现在`data:`之前或之后\n- CRLF和LF两种换行符可互换使用\n\n### 截断算法\n\n来自工具的大规模输出（如文件读取、命令输出、grep结果）必须被截断，以免耗尽LLM的上下文窗口。截断算法在保持有用性的前提下，确保内容不超过限制：\n\n```\n┌─────────────────────────────────────────┐\n│           原始内容              │\n│         （可能非常大）              │\n└─────────────────────────────────────────┘\n                    │\n                    ▼\n┌─────────────────────────────────────────┐\n│  HEAD: 前N\u002F2行                  │\n│  ─────────────────────────              │\n│  [... X行被截断 ...]            │\n│  ─────────────────────────              │\n│  TAIL: 后N\u002F2行                   │\n└─────────────────────────────────────────┘\n```\n\n**常量：**\n\n| 限制 | 值 | 理由 |\n|-------|-------|-----------|\n| `MAX_LINES` | 2000 | 平衡上下文使用与内容完整性 |\n| `MAX_BYTES` | 50KB | 防止二进制文件意外占用过多资源 |\n| `GREP_MAX_LINE_LENGTH` | 500字符 | 截断压缩后的代码 |\n\n算法步骤如下：\n1. 将内容按行分割。\n2. 如果行数超过`MAX_LINES`，则保留前1000行和后1000行。\n3. 插入标记，说明有多少行被省略。\n4. 如果字节数仍然超过`MAX_BYTES`，则进行字节级截断。\n5. 返回元数据，指示是否进行了截断，以便LLM可以请求特定范围的内容。\n\n### 进程树管理\n\n`bash`工具必须能够处理失控进程、死循环和叉子炸弹，同时避免留下孤儿进程。实现中使用了`sysinfo` crate来遍历进程树：\n\n```rust\n\u002F\u002F 进程清理伪代码\nfn kill_process_tree(root_pid: Pid) {\n    let system = System::new();\n    let children = find_all_descendants(root_pid, &system);\n\n    \u002F\u002F 先杀死子进程（从最深的开始），再杀死父进程。\n    for child in children.iter().rev() {\n        kill(child, SIGKILL);\n    }\n    kill(root_pid, SIGKILL);\n}\n```\n\n**超时行为：**\n\n1. 命令启动时设置可配置的超时时间（默认120秒）。\n2. 输出实时流向滚动缓冲区。\n3. 超时后：先发送SIGTERM信号，给予5秒宽限期，随后强制发送SIGKILL信号。\n4. 遍历进程树并杀死所有子进程。\n5. 设置退出码，以区分超时终止和正常终止。\n\n为避免后台作业成为孤儿（例如`cmd &`），bash脚本会安装一个`EXIT`陷阱，等待所有剩余的子进程结束后再以原始命令的状态退出。这样可以防止常见的问题：杀死外壳进程后，其子进程仍继续运行。\n\n### 会话树结构\n\n会话采用树形结构而非扁平列表，从而支持对话分支（在探索不同方法时非常有用）：\n\n```\n                    ┌─────────┐\n                    │ 消息    │ (根节点)\n                    │   #1    │\n                    └────┬────┘\n                         │\n                    ┌────▼────┐\n                    │ 消息    │\n                    │   #2    │\n                    └────┬────┘\n                         │\n              ┌──────────┼──────────┐\n              │                     │\n         ┌────▼────┐          ┌────▼────┐\n         │ 消息    │          │ 消息    │ (分支)\n         │   #3    │          │   #3b   │\n         └────┬────┘          └────┬────┘\n              │                    │\n         ┌────▼────┐          ┌────▼────┐\n         │ 消息    │          │ 消息    │\n         │   #4    │          │   #4b   │\n         └─────────┘          └─────────┘\n```\n\n**JSONL 格式（v3）：**\n\n每行都是一个自包含的 JSON 对象，带有 `type` 鉴别符：\n\n```json\n{\"type\":\"session\",\"version\":3,\"cwd\":\"\u002Fproject\",\"created\":\"2024-01-15T10:30:00Z\"}\n{\"type\":\"message\",\"id\":\"a1b2c3d4\",\"parent\":\"root\",\"role\":\"user\",\"content\":[...]}\n{\"type\":\"message\",\"id\":\"e5f6g7h8\",\"parent\":\"a1b2c3d4\",\"role\":\"assistant\",\"content\":[...]}\n{\"type\":\"model_change\",\"id\":\"i9j0k1l2\",\"parent\":\"e5f6g7h8\",\"model\":\"claude-sonnet-4-20250514\"}\n```\n\n`parent` 字段用于构建树状结构。重放会话时，程序会从根节点遍历到当前叶节点。当出现分支时，新消息的 `parent` 将不同于前一条延续消息。\n\n### 提供者抽象\n\n`Provider` 特性对不同的大模型后端进行了抽象：\n\n```rust\n#[async_trait]\npub trait Provider: Send + Sync {\n    fn name(&self) -> &str;\n    fn models(&self) -> &[Model];\n\n    async fn stream(\n        &self,\n        context: &Context,\n        options: &StreamOptions,\n    ) -> Result\u003Cimpl Stream\u003CItem = Result\u003CStreamEvent>>>;\n}\n```\n\n**上下文结构：**\n\n```rust\npub struct Context {\n    pub system: Option\u003CString>,      \u002F\u002F 系统提示词\n    pub messages: Vec\u003CMessage>,       \u002F\u002F 对话历史\n    pub tools: Vec\u003CToolDef>,          \u002F\u002F 可用工具及其 JSON 模式\n}\n```\n\n**流选项：**\n\n```rust\npub struct StreamOptions {\n    pub model: String,\n    pub max_tokens: u32,\n    pub temperature: Option\u003Cf32>,\n    pub thinking: Option\u003CThinkingConfig>,  \u002F\u002F 扩展思考设置\n    pub stop_sequences: Vec\u003CString>,\n}\n```\n\n这种设计允许在不修改智能体循环的情况下添加新的提供者（如 OpenAI、Gemini）。每个提供者会将通用类型转换为其通信格式，并输出统一的 `StreamEvent` 流。\n\n### 压缩算法\n\n长时间的对话最终会超出模型的上下文窗口。Pi 的压缩算法通过总结较早的消息来释放空间，同时保留最近的上下文。\n\n该算法会在每次智能体轮次结束后自动运行，当预计的令牌使用量超过 `context_window - reserve_tokens` 时：\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     完整对话                         │\n│  msg1 → msg2 → msg3 → ... → msgN-5 → msgN-4 → ... → msgN   │\n│  ├──── 较早的消息 ─────┤ ├─── 最近的消息 ──────────┤ │\n│                                                              │\n│  第一步：在有效的轮次边界处找到切割点             │\n│  第二步：LLM 将 msgs 1..N-5 总结为一段简洁的文字  │\n│  第三步：将压缩条目存储到会话 JSONL 中             │\n│  第四步：下一次智能体调用将使用 [摘要] + msgs N-4..N       │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**令牌估算**采用保守的文本 `chars ÷ 4` 估算法，而每张图片则固定为 1,200 个令牌。当助手消息中包含来自 API 的 `usage` 字段时，该测量值将优先于估算法。\n\n**切割点选择**倾向于完整的用户-助手轮次之间的边界。如果预算限制迫使其在轮次中间切割，则算法会包含分割轮次中的前缀消息，以便模型能够保留关于边界处正在讨论内容的上下文。\n\n**文件操作跟踪**会从被总结的消息中提取 `read`、`write` 和 `edit` 工具调用。压缩提示中会包含这些路径，以确保摘要能够保留对哪些文件已被查看或修改的记忆：\n\n```\n\u003Cread-files>\nsrc\u002Fmain.rs\nsrc\u002Fconfig.rs\n\u003C\u002Fread-files>\n\n\u003Cmodified-files>\nsrc\u002Fauth.rs\n\u003C\u002Fmodified-files>\n```\n\n**可配置参数：**\n\n| 参数                | 默认值           | 用途                           |\n|---------------------|------------------|--------------------------------|\n| `reserve_tokens`    | 上下文窗口的 8%  | 用于响应生成的安全余量         |\n| `keep_recent_tokens`| 上下文窗口的 10% | 至少保留的最近上下文比例     |\n\n在交互模式下，也可以通过 `\u002Fcompact` 命令手动触发压缩；或者使用 `compact` RPC 命令来实现。\n\n### 多提供商路由与模型注册表\n\nPi 通过提供商工厂路由模型请求，该工厂会根据 `(provider, model, api)` 元组解析出正确的后端实现。\n\n**解析流程：**\n\n```\n用户指定 --provider openai --model gpt-4o\n               │\n               ▼\n  ┌──────────────────────────┐\n  │  提供商元数据表          │  将 \"openai\" 映射为规范 ID，\n  │                           │  并确定 API 类型（Completions、Responses 或自定义）\n  │                           │\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  URL 规范化              │  根据检测到的 API 类型追加 \u002Fchat\u002Fcompletions、\n  │                            │  \u002Fresponses 或 \u002Fchat 路径\n  │                            │\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  兼容性配置              │  应用针对不同模型的覆盖设置：\n  │                            │  system_role_name、max_tokens 字段名、功能标志等\n  │                            │\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  提供商实例              │  Anthropic | OpenAI | Gemini\n  │                            │  Cohere | Azure | Bedrock | ...\n  └───────────────────────────┘\n```\n\n**`models.json` 覆盖设置**：用户可以在 `~\u002F.pi\u002Fagent\u002Fmodels.json` 或 `.pi\u002Fmodels.json` 中定义自定义提供商。每个条目需指定模型 ID、基础 URL、API 类型以及可选的兼容性标志，从而允许您将请求路由到自托管模型、代理服务，或 Pi 本身不原生支持的提供商。\n\n**兼容性配置**用于处理与 OpenAI 兼容的各类 API 之间的差异：\n\n| 覆盖项            | 示例                | 用途                                                         |\n|-------------------|---------------------|--------------------------------------------------------------|\n| `system_role_name`  | `\"developer\"`       | o1 模型使用 `\"developer\"` 而非 `\"system\"`                   |\n| `max_tokens_field`  | `\"max_completion_tokens\"` | 部分模型需要使用不同的字段名                             |\n| `supports_tools`    | `false`             | 对不支持工具调用的模型禁用工具定义                         |\n| `supports_streaming`| `false`             | 对不支持流式响应的端点回退至非流式响应                     |\n| `custom_headers`    | `{\"X-Custom\": \"val\"}` | 针对特定提供商注入自定义 HTTP 头                           |\n\n**模糊匹配**：当提供的提供商名称与任何已知提供商都不匹配时，Pi 会计算其与所有已注册提供商名称之间的编辑距离，并在错误信息中建议最接近的匹配项。\n\n### 扩展宿主调用协议\n\n扩展程序运行在一个嵌入式的 QuickJS 运行时（`rquickjs` crate）中，并通过一个结构化的宿主调用协议与 Pi 通信。正是这一机制使得 JavaScript 代码能够在不直接访问操作系统的情况下，调用 Pi 的内置工具、发起 HTTP 请求以及与会话进行交互。\n\n**执行模型：**\n\n```\n┌─────────────────── QuickJS VM ───────────────────┐\n│                                                   │\n│  extension.js 调用：                              │\n│    pi.tool(\"read\", {path: \"src\u002Fmain.rs\"})         │\n│      │                                            │\n│      ▼                                            │\n│    将 HostcallRequest 入队：                       │\n│      call_id: \"hc-0042\",                          │\n│      kind: Tool { name: \"read\" },                 │\n│      payload: { path: \"src\u002Fmain.rs\" },            │\n│    }                                              │\n│      │                                            │\n│      ▼                                            │\n│    返回 Promise（resolve\u002Freject 存储在映射中）    │\n│                                                   │\n└────────────────────────┬──────────────────────────┘\n                         │\n    drain_hostcall_requests()\n                         │\n                         ▼\n┌─────────────── ExtensionDispatcher ──────────────┐\n│                                                   │\n│  1. 检查能力策略：                                │\n│     read 工具 → 需要 \"read\" 能力                  │\n│     → 策略规定：允许 \u002F 拒绝 \u002F 提示               │\n│                                                   │\n│  2. 如果允许 → 分发到 ToolRegistry               │\n│     → 执行 read 工具                             │\n│     → 获取 ToolOutput                              │\n│                                                   │\n│  3. complete_hostcall(\"hc-0042\", Ok(result))      │\n│     → 解析 QuickJS 中的 Promise                   │\n│                                                   │\n│  4. runtime.tick()                                │\n│     → 清空 Promise .then() 链                      │\n│     → 扩展 JS 继续执行                            │\n│                                                   │\n└───────────────────────────────────────────────────┘\n```\n\n**能力映射**：每种宿主调用类型都对应一个所需的权限：\n\n| 宿主调用                     | 所需权限   | 是否危险？ |\n|------------------------------|------------|------------|\n| `pi.tool(\"read\", ...)`       | `read`     | 否         |\n| `pi.tool(\"write\", ...)`      | `write`    | 否         |\n| `pi.tool(\"bash\", ...)`       | `exec`     | 是         |\n| `pi.http(request)`           | `http`     | 否         |\n| `pi.exec(cmd, args)`         | `exec`     | 是         |\n| `pi.env(key)`                | `env`      | 是         |\n| `pi.session(op, ...)`        | `session`  | 否         |\n| `pi.ui(op, ...)`             | `ui`       | 否         |\n| `pi.log(entry)`              | `log`      | 否（始终允许）|\n\n**去重处理**：每个宿主调用的参数都会被规范化（对象键排序、结构标准化），并计算 SHA-256 哈希值。在短时间内出现的相同请求可以被去重，以避免重复执行工具。\n\n**快速通道与兼容性通道**：Pi 对宿主调用提供了两条执行路径：\n\n- **快速通道**：当调用形式符合已知的安全模式时使用（例如常见的 `tool` 和 `session` 操作）。这样可以避免额外的内存分配和解析工作。\n- **兼容性通道**：用于处理不常见或参数不完整的调用作为回退方案。\n- 两条通道仍然执行相同的权限策略和检查。\n- 运维人员可以全局或按扩展强制切换到兼容性通道，作为紧急控制手段。\n\n为了便于观测，每次调用都会被打上一个稳定的通道标签（例如 `tool|tool.read|filesystem` 或 `tool|fallback|filesystem`），以便对延迟和失败趋势进行一致的分组。\n\n**内置一致性保障机制（影子双重执行）**：Pi 可以随机抽取一小部分只读宿主调用，分别通过两条通道执行，并比较其规范化的输出指纹。如果差异超过预设阈值，Pi 会自动暂时禁用快速通道。这样既保证了性能优势，又不会悄悄改变行为。\n\n**负载下的自适应调度模式**：Pi 可以在以下两种模式之间切换：\n\n- `sequential_fast_path`：适用于较简单或竞争较少的工作负载。\n- `interleaved_batching`：当竞争和队列压力增加时使用。\n\n模式切换受到采样覆盖率和风险检查的限制，因此 Pi 不会基于少量或有选择性的证据进行切换。\n\n**运行时遥测数据用于调试和调优**：Pi 会记录结构化的宿主调用遥测信息（`pi.ext.hostcall_telemetry.v1`），包括通道选择、回退原因、调度延迟占比、序列化路径以及优化命中\u002F未命中等字段。这些数据可用于性能报告和可靠性诊断。\n\n**自动修复流水线**：当扩展加载失败或运行时出现错误时，Pi 的修复系统可以自动解决常见问题：\n\n| 修复模式 | 行为 |\n|-----------|------|\n| `Off`     | 不进行修复 |\n| `Suggest` | 记录建议，但不应用 |\n| `AutoSafe`（默认） | 应用可证明安全的修复措施（如缺失的文件路径、资源引用） |\n| `AutoStrict` | 应用激进的启发式修复（基于模式的转换） |\n\n**兼容性扫描器**：在加载之前，Pi 会对扩展源代码进行静态分析，检查导入语句、`require()` 调用以及禁止使用的模式（`eval`、`Function()`、`process.binding`、`dlopen`）。扫描结果会生成一份能力证据清单，用于支持策略决策。\n\n**环境变量过滤**：扩展程序调用 `pi.env()` 时，会经过一个黑名单过滤，拒绝访问 API 密钥、凭据、令牌和私钥。该过滤器会阻止完全匹配项（如 `ANTHROPIC_API_KEY`、`AWS_SECRET_ACCESS_KEY`）、后缀模式（如 `*_API_KEY`、`*_SECRET`、`*_TOKEN`）以及前缀模式（如 `AWS_SECRET_*`、`AWS_SESSION_*`）。只有 `PI_*` 变量会被无条件允许。\n\n**信任生命周期与紧急关闭开关**：扩展的信任状态会被明确跟踪（`pending`、`acknowledged`、`trusted`、`killed`）。紧急关闭开关会将扩展降级为 `killed` 状态，将其隔离在运行时风险控制器中，发出严重告警，并记录审计日志。解除关闭开关需要运维人员的明确操作，且会将扩展重新置为 `acknowledged` 状态。\n\n### 扩展运行时决策逻辑（通俗解释）\n\n扩展运行时包含几个小型决策引擎，以确保在工作负载模式变化时行为保持稳定：\n\n- **信息价值规划器 (VOI)**：根据“每毫秒的预期学习量”对候选探针进行排序，并在严格的开销预算内选择最佳组合。过时或价值较低的候选会被跳过，并给出明确的理由。\n- **分片负载控制器**：根据队列压力、延迟和饥饿风险调整路由权重、批处理预算以及退避\u002F帮助因子。通过阻尼和振荡保护机制防止过度反应。\n- **策略安全性评估器**：使用多种估计器重放历史样本，仅当样本支持充分、不确定性低且预测遗憾控制在限制范围内时，才会批准该策略。\n\n这些组件的设计都较为保守：如果置信度不足，Pi 会保持当前状态，而不是贸然切换。\n\n### 交互式 TUI 架构\n\n交互模式采用 **Elm 架构**（模型-更新-视图），通过 `charmed_rust` 库族实现，它是 Go 语言 [Bubble Tea](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) 框架的 Rust 版本。\n\n**组件栈：**\n\n```\n┌────────────────────────────────────────────────────┐\n│                 终端 (crossterm)                │\n│  原始模式 │ Alt 屏幕 │ 键盘\u002F鼠标事件      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             bubbletea 程序循环                  │\n│  Init() → Update(Msg) → View() → 渲染循环      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│                  PiApp (模型)                      │\n│                                                     │\n│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐  │\n│  │  文本区域    │ │  视口        │ │  加载动画     │  │\n│  │  (编辑器)    │ │  (对话)     │ │  (状态)    │  │\n│  └─────────────┘ └──────────────┘ └─────────────┘  │\n│                                                     │\n│  ┌─────────────────────────────────────────────┐    │\n│  │           覆盖层堆栈                      │    │\n│  │  模型选择器 │ 会话选择器   │ \u002Ftree     │    │\n│  │  设置界面    │ 主题选择器   │ 分支管理  │    │\n│  │  功能提示（扩展 UI）                        │    │\n│  └─────────────────────────────────────────────┘    │\n└──────────────────────┬─────────────────────────────┘\n                       │\n              异步通道 (mpsc)\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             代理异步任务                        │\n│  在 asupersync 运行时上运行                         │\n│  流式传输提供者响应                                 │\n│  执行工具                                           │\n│  将 PiMsg 事件发送回 TUI 线程                       │\n└────────────────────────────────────────────────────┘\n```\n\n**异步\u002F同步桥接**：代理在单独的线程中运行 `asupersync` 异步运行时，通过 `mpsc` 通道与 bubbletea UI 线程通信。每个流式事件（文本增量、工具开始、工具更新、代理完成）都会转化为一个 `PiMsg` 变体，传递给 `PiApp::update()`，从而在 API 流式传输和工具执行期间保持 UI 的响应性。\n\n**视口滚动**：对话视口会跟踪用户是否位于底部。当新内容到达且用户未向上滚动时，视口会自动跟随流的末尾。一旦用户向上滚动，自动跟随功能将被禁用；按下 `End` 键或输入新消息后，该功能会重新启用。\n\n**覆盖系统**：模态 UI（模型选择器、会话选择器、分支导航器、扩展功能提示）会叠加在主对话视图之上。每个覆盖层会捕获键盘输入，直到被关闭。只有最顶层的活动覆盖层才会接收事件。\n\n**交互式编辑器中的斜杠命令**：\n\n| 命令       | 功能                     |\n|------------|--------------------------|\n| `\u002Fhelp`    | 显示可用命令和快捷键     |\n| `\u002Fmodel` 或 `Ctrl+L` | 打开带有模糊搜索的模型选择器 |\n| `Ctrl+P` \u002F `Ctrl+Shift+P` | 循环切换作用域内的模型   |\n| `\u002Ftree`    | 浏览并分叉对话树         |\n| `\u002Fclear`   | 清除对话并重新开始       |\n| `\u002Fcompact` | 触发手动压缩             |\n| `\u002Fthinking \u003Clevel>` | 在对话过程中更改思考级别 |\n| `\u002Fshare`   | 将会话导出到 GitHub Gist   |\n| `\u002Fexit` 或 `Ctrl+C` | 退出 Pi                  |\n\n### RPC 协议\n\nRPC 模式（`pi --mode rpc`）通过标准输入\u002F输出暴露了一个基于换行符分隔的 JSON 协议，用于程序化集成。每行都是一个独立的 JSON 对象。\n\n**客户端 → Pi（标准输入）：**\n\n```json\n{\"type\": \"prompt\", \"message\": \"解释这个函数\", \"id\": \"req-001\"}\n{\"type\": \"steer\", \"message\": \"专注于错误处理\"}\n{\"type\": \"follow-up\", \"message\": \"现在添加测试\"}\n{\"type\": \"abort\"}\n{\"type\": \"get-state\"}\n{\"type\": \"compact\", \"reserve\": 8192, \"keepRecent\": 20000}\n```\n\n**Pi → 客户端（标准输出）：**\n\n```json\n{\"type\": \"event\", \"event\": \"agent_start\", \"data\": {\"session_id\": \"...\"}}\n{\"type\": \"event\", \"event\": \"text_delta\", \"data\": {\"text\": \"这个函数\"}}\n{\"type\": \"event\", \"event\": \"tool_start\", \"data\": {\"tool\": \"read\", \"input\": {}}}\n{\"type\": \"event\", \"event\": \"tool_end\", \"data\": {\"tool\": \"read\", \"output\": {}}}\n{\"type\": \"event\", \"event\": \"agent_done\", \"data\": {\"usage\": {}}}\n{\"type\": \"response\", \"id\": \"req-001\", \"data\": {\"status\": \"ok\"}}\n```\n\n**I\u002FO 架构**：两个专用线程分别负责读取标准输入和写入标准输出，通过通道与异步代理运行时相连。标准输入线程会在出现短暂错误时重试，以防止输入丢失。标准输出线程则每行输出后立即刷新，避免缓冲延迟。\n\n**消息队列**：当代理正在流式传输响应时，传入的消息会被路由到以下两个队列之一：\n\n| 队列       | 行为                     | 使用场景               |\n|------------|--------------------------|------------------------|\n| **引导队列** | 中断当前响应；在下一轮处理 | 修正方向               |\n| **后续队列** | 排队等待当前响应完成     | 顺序指令               |\n\n队列模式（“全部”或“一次一条”）决定了多个排队的消息是合并为一轮处理，还是逐个单独处理。\n\n**RPC 上的扩展 UI**：当扩展请求用户输入（功能提示、选择对话框）时，Pi 会发出一个 `extensionUiRequest` 事件。客户端会在自己的 UI 中渲染提示，并以 `extensionUiResponse` 消息作出回应。IDE 扩展因此可以呈现原生 UI 来处理功能决策，而无需回退到终端提示。\n\n### 会话索引\n\n会话恢复（`pi -c` 或 `pi -r`）需要在不扫描磁盘上每个 JSONL 文件的情况下，找到当前项目的最新会话。Pi 维护一个 SQLite 索引（`session-index.sqlite`），该索引提供常数时间的查找。\n\n**模式：**\n\n```sql\nCREATE TABLE sessions (\n    path            TEXT PRIMARY KEY,\n    id              TEXT NOT NULL,\n    cwd             TEXT NOT NULL,\n    timestamp       TEXT NOT NULL,\n    message_count   INTEGER NOT NULL,\n    last_modified   INTEGER NOT NULL,\n    size_bytes      INTEGER NOT NULL,\n    name            TEXT\n);\n```\n\n**更新生命周期：**\n\n1. 保存会话 JSONL 文件后，Pi 会将其元数据插入或更新到索引中。\n2. `pi -c` 查询 `WHERE cwd = ? ORDER BY last_modified DESC LIMIT 1`。\n3. `pi -r` 查询同一张表，并按最近时间排序显示选择器。\n\n**并发性**：基于文件的锁（`session-index.lock`）对来自并发 Pi 实例的写操作进行序列化。读取使用 WAL 模式以实现非阻塞访问。\n\n**基于过时的重新索引**：如果索引比可配置的阈值更旧，Pi 会完全重新扫描会话目录，以捕获由其他实例或手动编辑创建的文件。这种重新扫描可以在没有集中式守护进程的情况下保持索引的准确性。\n\n### 会话存储 V2 侧车（大型会话快速路径）\n\nPi 还支持在 JSONL 会话旁边使用 v2 侧车存储，以便更快地恢复会话，并对长期历史记录进行更强的损坏检查。\n\n**新增内容：**\n\n- 分段追加日志文件（而不是一个不断增长的 JSONL 文件）\n- 偏移索引行，用于直接查找和快速读取尾部\n- 定期检查点和清单快照\n- 用于审计性的迁移账本条目\n- 基于检查点的回滚路径，并带有明确的回滚事件日志记录\n\n**恢复工作原理：**\n\n1. 如果存在且最新的 v2 侧车，Pi 将从侧车索引 + 分段打开。\n2. 如果侧车数据相对于源 JSONL 已过时，Pi 将回退到解析 JSONL。\n3. 如果索引数据丢失或损坏，但分段有效，Pi 将重建索引。\n\n**完整性策略：**\n\n- 分段帧携带有效载荷和链式哈希。\n- 索引行存储字节偏移量以及 CRC32C 校验和。\n- 在信任侧车之前，验证会执行偏移范围、校验和匹配以及帧与索引对齐的检查。\n- 截断的尾部帧在重建过程中可以恢复；而非 EOF 帧的损坏则会失败关闭，而不是静默丢弃数据。\n\n**CLI 支持：**\n\n- `pi migrate \u003Cpath> --dry-run` 在不写入的情况下验证迁移。\n- `pi migrate \u003Cpath>` 执行 JSONL 到 v2 的迁移，并验证一致性。\n\n### 身份验证与凭据管理\n\n除了简单的 API 密钥外，Pi 还支持 OAuth、AWS 凭证链、服务密钥交换以及承载令牌身份验证。凭据存储在 `~\u002F.pi\u002Fagent\u002Fauth.json` 中，并采用文件锁定访问方式，以防止来自并发实例的损坏。存储的 API 密钥可以是文字字符串、`$ENV:VAR_NAME` 引用，或 `$CMD:shell command` \u002F `$COMMAND:shell command` 来源，在请求时解析修剪后的标准输出。\n\n| 机制 | 提供商 | 详情 |\n|-----------|-----------|---------|\n| **API 密钥** | Anthropic、OpenAI、Gemini、Cohere 以及许多兼容 OpenAI 的提供商 | 通过环境变量或设置静态密钥 |\n| **OAuth** | Anthropic、OpenAI Codex、Google Gemini CLI、Google Antigravity、Kimi for Coding、GitHub Copilot、GitLab 以及扩展定义的 OAuth 提供商 | 带有 PKCE\u002F状态验证流程并自动刷新；Kimi 使用设备流 |\n| **AWS 凭证** | Bedrock | 访问密钥 + 秘密 + 可选会话令牌；区域感知 |\n| **服务密钥** | SAP AI Core | 客户 ID\u002F秘密交换以获取承载令牌 |\n| **承载令牌** | 自定义提供商 | 静态令牌存储在认证存储中 |\n\n**OAuth 令牌生命周期：**\n\n1. 用户运行配置了 OAuth 的 `pi`。\n2. Pi 检查 `auth.json` 中是否存在现有令牌。\n3. 如果不存在：打开浏览器到授权 URL，用户进行身份验证，Pi 接收授权码，将其兑换为访问令牌和刷新令牌，并将两者连同到期时间一起存储。\n4. 如果已过期但刷新令牌有效：Pi 用刷新令牌兑换新的访问令牌，并更新 `auth.json`。\n5. 承载令牌附加到 API 请求中。\n\nGoogle CLI 风格的 OAuth 提供商会在令牌负载中携带项目元数据。Pi 会保留并刷新该负载，并在需要时可以从 `GOOGLE_CLOUD_PROJECT` 或本地 `gcloud` 配置中解析项目 ID。\n\n**凭据状态报告**：`pi config` 显示每个配置提供商的凭据状态：`缺失`、`ApiKey`、`OAuth有效`（附带到期时间）、`OAuth过期`（附带过期时间）、`AwsCredentials` 或 `BearerToken`。\n\n**诊断代码**：身份验证失败会产生特定的诊断代码（`MissingApiKey`、`InvalidApiKey`、`QuotaExceeded`、`OAuthTokenRefreshFailed`、`MissingAzureDeployment`、`MissingRegion` 等），并提供上下文相关的错误提示，而不是通用消息。\n\n---\n\n## 工具详情\n\n### read\n\n读取文件内容（可选图像）：\n\n```\n输入：{ \"path\": \"src\u002Fmain.rs\", \"offset\": 10, \"limit\": 50 }\n```\n\n- 支持图像（jpg、png、gif、webp），并可选自动调整大小。\n- 以块形式流式传输文件字节，设置严格的大小限制，以减少峰值内存使用。\n- 应用防御性图像解码限制，以阻止解压缩炸弹\u002FOOM 输入。\n- 最多截断至 2000 行或 50KB。\n- 如果被截断，则返回继续提示。\n\n### bash\n\n执行带有超时和输出捕获的 shell 命令：\n\n```\n输入：{ \"command\": \"cargo test\", \"timeout\": 120 }\n```\n\n- 默认超时 120 秒，每次调用可配置。\n- 设置 `timeout: 0` 可禁用默认超时。\n- 超时时清理进程树（杀死子进程）。\n- 使用滚动缓冲区实现实时输出。\n- 如果输出被截断，则完整输出会保存到临时文件中。\n\n### edit\n\n手术式的字符串替换：\n\n```\n输入：{ \"path\": \"src\u002Flib.rs\", \"old\": \"fn foo()\", \"new\": \"fn bar()\" }\n```\n\n- 精确字符串匹配（无正则表达式）。\n- 如果未找到旧字符串或存在歧义，则失败。\n- 返回差异预览。\n\n### grep\n\n搜索文件内容：\n\n```\n输入：{ \"pattern\": \"TODO\", \"path\": \"src\u002F\", \"context\": 2, \"limit\": 100 }\n```\n\n- 支持正则表达式模式。\n- 匹配前后显示上下文行。\n- 忽略 .gitignore 文件。\n\n### find\n\n按模式查找文件：\n\n```\n输入：{ \"pattern\": \"*.rs\", \"path\": \"src\u002F\", \"limit\": 1000 }\n```\n\n- 使用 `fd` 进行 glob 模式匹配。\n- 按修改时间排序。\n- 忽略 .gitignore 文件。\n\n### ls\n\n列出目录内容：\n\n```\n输入：{ \"path\": \"src\u002F\", \"limit\": 500 }\n```\n\n- 按字母顺序排序。\n- 目录以尾随 `\u002F` 标记。\n- 达到限制时截断。\n\n---\n\n## 性能工程\n\n### 为什么 Rust 对于 CLI 工具至关重要\n\nCLI 工具的性能要求与服务器或 GUI 应用程序不同。最关键的指标是“首次交互时间”：用户在调用命令后，多久才能开始输入？\n\n| 阶段               | TypeScript\u002FNode.js       | Rust     |\n|--------------------|--------------------------|----------|\n| 进程启动           | ~10ms                   | ~10ms   |\n| 运行时初始化       | 200–500ms               | 0ms（无运行时） |\n| 模块加载           | 100–300ms               | 0ms（静态链接） |\n| JIT 热身           | 50–100ms                | 0ms（AOT 编译） |\n| **总计**           | **360–910ms**           | **~10ms** |\n\n这种差异会随着使用频率的增加而不断放大，尤其是在短周期的迭代式终端工作流中。\n\n### 极致优化指南\n\nPi 的优化方式更接近低延迟引擎，而非典型的 CLI 应用程序。我们并非简单地“使用 `--release` 编译并寄希望于它”，而是有意识地在多个层次上实施激进的优化。\n\n速度的来源包括：\n\n- **启动路径极简**：无需 JS 运行时引导、无需加载模块依赖图、无需 JIT 热身。\n- **高频宿主调用专用化**：常见扩展的宿主调用采用类型化的快速路径；不常见的调用则回退到兼容性路径。\n- **负载下的自适应调度**：当竞争加剧时，宿主调用调度会切换模式，压力缓解后再恢复原状。\n- **快速路径的安全保障**：通过采样式的影子双重执行检查，确保优化不会悄然改变行为。\n- **低分配渲染**：TUI 渲染缓冲区和 Markdown 渲染结果会被缓存复用，而不是每帧都重新构建。\n- **快速恢复机制**：会话索引结合 v2 辅助进程布局，避免在恢复时进行昂贵的全历史扫描。\n- **增长限制机制**：通过压缩和截断，防止令牌\u002F上下文以及工具输出数据量在长时间会话中持续膨胀，从而影响响应速度。\n- **以度量为导向的文化**：性能相关工件会在 CI 中经过模式验证并设置准入门槛，确保优化工作基于证据驱动，并能尽早发现回归问题。\n\n正是这些设计，使得 Pi 即便在同时进行大量流式处理、频繁调用工具、拥有庞大的会话历史记录以及运行复杂扩展工作负载的情况下，依然能够保持流畅的响应。\n\n### 优化目录（代码 + 提交历史）\n\n本目录反映了运行时、存储、流式处理和 UI 各个领域的长期变更序列。\n\n该代码库中的具体工程工作包括：\n\n| 领域 | 我们构建的内容 | 为何重要 |\n|------|---------------|----------------|\n| 扩展调度核心 | 类型化宿主调用操作码快速路径、兼容性回退通道、零拷贝负载池、规范哈希快捷方式、内部化操作路径 | 在保留正确性回退路径的同时，降低最热点扩展操作的每次调用开销 |\n| 注册表\u002F策略查找 | 不可变策略快照，具备 O(1) 能力检查；以及基于 RCU 的元数据快照，用于扩展注册表和工具元数据 | 消除热点授权\u002F调度路径中重复的动态查找开销 |\n| 排队与并发 | 核心绑定的 SPSC 反应器网格、受 S3-FIFO 启发的准入控制及公平性保障、BRAVO 式回退行为 | 在竞争条件下改善尾延迟，而不仅仅是优化中位数延迟 |\n| 批量执行 | AMAC 式交错批量执行器，具备停顿感知切换机制 | 避免在大量独立宿主调用同时进行时出现队头阻塞 |\n| IO 特化 | io_uring 通道策略 + 诊断监控与兼容性回退 | 在安全且有益的情况下，将 IO 密集型调用路由到专用通道 |\n| 扩展的运行时启动 | QuickJS 预热路径、预热隔离区\u002F字节码缓存行为，以及启动流水线并行化 | 降低首次实际扩展工作负载之前的冷启动开销 |\n| JS 桥接\u002F调度路径 | 热点扩展循环中待处理任务快速路径调优及桥接层调度清理 | 减少 JS 请求与 Rust 执行之间的开销 |\n| 自适应控制环路 | 切换模式检测（CUSUM\u002FBOCPD）、预算控制器、基于 VOI 的实验规划器、平均场负载控制器、离策略评估门控 | 使运行时行为能够适应工作负载变化，而无需盲目调优 |\n| 快速路径安全性 | 影子双执行采样，发生分歧时自动回滚\u002F退避 | 防止性能优化无意间改变语义 |\n| 跟踪级优化 | 宿主调用超指令编译器 + 第二层跟踪 JIT 路径 | 融合重复的操作码跟踪，降低重复调度开销 |\n| 工具执行策略 | 动态只读工具分类 + 并行工具执行路径 | 在多个工具调用可安全并行执行时提高吞吐量 |\n| 会话写入路径 | 写后自动保存队列、持久性模式、增量追加、检查点重写策略、单缓冲追加序列化 | 在保持交互流畅的同时，仍能在需要时支持更强的持久性 |\n| 会话索引路径 | 异步合并索引更新、待处理事务清空的热点路径调优，以及减少分配和装箱开销 | 将恢复\u002F发现元数据更新从交互式热点路径上移开 |\n| 会话恢复路径 | 会话存储 V2 辅助进程（分段日志 + 偏移索引）、O(索引+尾部) 打开路径、过时辅助进程检测、迁移\u002F回滚工具 | 避免在大型历史记录中进行全文件扫描，并改善恢复行为 |\n| 长期会话维护 | 具有配额的后台压缩\u002F快照工作线程 + 懒加载路径 | 控制会话增长，保持长时间运行的工作空间响应迅速 |\n| 压缩内部实现 | 二分查找切分点逻辑、序列化辅助函数提取，以及面向零分配的压缩路径清理 | 降低压缩开销，避免压缩成为暂停源 |\n| 流式处理内部实现 | SSE 解析器事件类型内部化、已扫描字节数跟踪 (`scanned_len`)、UTF-8 恢复加固 | 减少标记化流式传输过程中的重复扫描\u002F分配，并提高容错能力 |\n| 提供者\u002F消息内存路径 | 零拷贝请求上下文迁移 (`Cow`)、基于 `Arc` 的消息\u002F结果共享、流结束路径上的克隆消除 | 消除核心代理\u002F提供者循环中的热点路径克隆和频繁分配 |\n| TUI 渲染路径 | 消息渲染缓存、对话前缀缓存、可复用渲染缓冲区、视口\u002F渲染路径重构、Criterion 性能门控 | 在流式传输长输出时降低重绘成本和抖动 |\n| 启动\u002F资源加载 | 技能\u002F提示\u002F主题并行加载，以及预计算的工具定义和命令名称 | 将繁重的初始化工作从关键路径上移开，以提升用户交互时间 |\n| 分配器\u002F构建配置 | 对于内存密集型路径，默认使用 jemalloc；发布配置面向速度；严格验证性能声明的工件 | 提高运行时一致性，防止基准测试和报告结果漂移 |\n| 性能治理 | 场景矩阵、声明完整性门控、严格的无数据失败行为、方差\u002F置信区间工件、可重复的编排包 | 使性能声明可审计，并实现回归自动检测 |\n| 宿主调用封送计划 | `HostcallRewriteEngine` 使用小型成本模型，在明确更便宜且无歧义时才选择快速操作码融合；否则仍走规范路径并记录回退原因 | 在热点封送形状上提升速度，同时避免因模糊重写而导致无声语义漂移的风险 |\n| 工具文本处理热点路径 | `truncate_head`\u002F`truncate_tail` 使用惰性行遍历和 `memchr` 行计数；规范化改为单次转换，而非链式字符串重写 | 大文件\u002F工具输出避免不必要的中间分配，保持响应迅速 |\n| JS 桥接正则表达式和解析器微路径 | 扩展 JS 桥接中频繁的正则表达式检查采用 `OnceLock` 缓存；热点桥接调用避免重复设置 | 降低扩展密集型会话中每次调用的重复开销 |\n| CLI\u002F自动补全进程创建减少 | `fd`\u002F`rg` 可用性检查被缓存，自动补全文档索引刷新在后台运行，且允许使用过时更新 | 即使在非常大的代码库中，也能保持补全和命令处理的快速响应 |\n| 会话身份\u002F索引微优化 | O(1) 条目 ID 缓存、单次元数据定稿，以及追加路径清理取代多轮\u002F高复制行为 | 当会话规模增大时，降低追加\u002F保存\u002F重建的开销 |\n| 基于基准测试的回滚纪律 | 待选微优化都会经过基准测试，若在真实工作负载下导致性能下降，则可回滚（例如，SSE 中的新行扫描 `memchr` 替换就被回滚） | 防止那些理论上速度快、但实际上会拖慢使用的“优化” |\n\n优化涵盖了算法、执行通道、内存管理、队列规则、存储布局和验证策略等多个方面，作为一个整体系统协同工作。\n\n### 发布配置与二进制大小限制\n\n正式发布的配置文件针对运行时速度进行了优化：\n\n```toml\n[profile.release]\nopt-level = 3        # 最大化速度优化\nlto = true           # 跨所有 crate 的链接时优化\ncodegen-units = 1    # 单一代码生成单元（编译较慢，但优化效果更好）\npanic = \"abort\"      # 不启用异常取消机制\nstrip = true         # 移除符号表\n```\n\n在 CI 中，二进制大小仍然通过 `binary_size_release` 进行显式预算管理，当前的发布阈值设置为 `22.0 MB`。\n\n### 基准测试证据与正式发布产物\n\nPi 将性能证据产物与可分发的发布产物区分开来：\n\n- **基准测试证据产物**（PERF-3X 和认证输入）由 `scripts\u002Fperf\u002Forchestrate.sh` 和 `scripts\u002Fbench_extension_workloads.sh` 生成，必须包含运行溯源信息（`correlation_id`）以及配置标签（例如 `build_profile=perf`）。\n- **正式发布产物**（面向用户的二进制文件）使用 Cargo 的 `release` 配置构建，并通过 GitHub Releases 和安装程序路径分发。\n\n政策含义：仅凭发布\u002F大小相关的产物并不能作为全球性能声明的有效证据。性能声明必须引用具有可重复溯源性的基准测试证据包。有关规范性政策详情，请参阅 `docs\u002Ftesting-policy.md` 和 `docs\u002Freleasing.md`。\n\n最新的完整编排器检查点（`2026-02-19`）：\n- 运行输出：`\u002Fdata\u002Ftmp\u002Fpi_agent_rust\u002Fcodex\u002Fperf\u002Ffull_local_skipbuild_retry_20260219T0650Z`\n- 关联 ID：`fullbench-local-skipbuild-retry-20260219T0650Z`\n- 总结：共执行 11 个测试套件，其中 9 个通过，2 个失败（`perf_budgets`、`perf_regression`）。\n- 失败原因：两次失败均为严格的证据\u002F前提条件检查（缺少或过时的规范性产物路径，以及缺少严格的发布二进制路径），而非测量到的吞吐量或延迟崩溃。\n- 同次运行中测得的启动保护指标仍处于绿色范围：`--help` P95 值为 `3.8ms`，`--version` P95 值为 `3.6ms`。\n\n### 快速迭代循环与权威基准测试\n\n在日常开发中，应使用针对性的检查以保持快速迭代。将权威的基准测试结论保留用于需要重新生成完整证据的集成边界。\n\n- **快速迭代循环（非权威）：** 文件作用域内的 `cargo fmt --check` 以及有针对性的测试重放（当编译较为复杂时，使用 `rch exec -- cargo test --test ...`）。\n- **权威通过（权威）：** 将耗时较长的运行交由严格的远程控制机制执行（使用 `rch exec -- ...` 或带有 `--require-rch` 参数的脚本封装），随后要求更新以下证据产物：\n  - `tests\u002Fperf\u002Freports\u002Fphase1_matrix_validation.json`\n  - `tests\u002Ffull_suite_gate\u002Ffull_suite_verdict.json`\n  - `tests\u002Ffull_suite_gate\u002Fcertification_verdict.json`\n  - `tests\u002Ffull_suite_gate\u002Fextension_remediation_backlog.json`\n\n这样既能保证内部循环的响应速度，又能在发布时维持严格的声明完整性。\n\n### 扩展工作负载热点分析\n\nPi 提供了一个专门用于分析扩展运行时瓶颈的工作负载框架：\n\n```bash\ncargo run --bin ext_workloads -- \\\n  --out artifacts\u002Fperf\u002Fext_workloads.jsonl \\\n  --matrix-out artifacts\u002Fperf\u002Fext_hostcall_hotspot_matrix.json \\\n  --trace-out artifacts\u002Fperf\u002Fext_hostcall_bridge_trace.jsonl\n```\n\n该框架不仅进行简单的计时：\n\n- 将宿主调用成本细分为六个阶段：`marshal`、`queue`、`schedule`、`policy`、`execute`、`io`；\n- 生成热点矩阵（`pi.ext.hostcall_hotspot_matrix.v1`），以便快速排序瓶颈；\n- 生成桥接跟踪事件（`pi.ext.hostcall_trace.v1`），用于逐调用调试；\n- 测量各阶段之间的交互，并验证是否覆盖了所有阶段组合；\n- 生成 VOI 调度计划（`pi.ext.voi_scheduler.v1`），以在固定开销预算下推荐下一步最具价值的实验。\n\n简而言之，它通过数据而非猜测来回答“我们接下来应该优化什么？”这个问题。\n\n### 性能报告的声明完整性约束\n\nPi 的性能流水线包含严格的证据检查，以确保全局速度声明不会基于不完整或过时的数据。\n\n- `scripts\u002Fperf\u002Forchestrate.sh` 会生成与同一运行共享 `correlation_id` 的相关产物。\n- `scripts\u002Fe2e\u002Frun_all.sh` 在认定声明有效之前，会验证所需的模式、新鲜度以及 `correlation_id` 的一致性。\n- `tests\u002Frelease_evidence_gate.rs` 会在合规性\u002F性能产物缺失 `run_id` 或 `correlation_id`，或者关联产物间的 lineage 字段不一致时，直接判定为失败。\n- `scripts\u002Fe2e\u002Frun_all.sh` 会输出一份证据裁决矩阵，只有当新鲜度和 lineage 检查均通过时，才会将证据视为权威。\n- 主要面向发布的产物包括：\n  - `pi.perf.extension_benchmark_stratification.v1`\n  - `pi.perf.phase1_matrix_validation.v1`\n  - `pi.claim_integrity.evidence_adjudication_matrix.v1`\n\n如果证据集不完整或相互矛盾，声明完整性约束将保持关闭状态，并明确指出具体原因。\n\n### 基准测试中的分配器策略\n\n正式发布的构建默认使用平台分配器。对于分配器实验，Pi 支持在编译时显式选择 `jemalloc`：\n\n```bash\n# 系统分配器基线 + jemalloc 变体，在一次可重复的运行中同时测试\nBENCH_ALLOCATORS_CSV=system,jemalloc \\\n  .\u002Fscripts\u002Fbench_extension_workloads.sh\n```\n\n基准测试框架会在其 JSONL 输出中记录请求的和实际使用的分配器元数据（`allocator_requested`、`allocator_effective`、`allocator_fallback_reason`），这些信息通过 `PI_BENCH_ALLOCATOR` 设置。\n\n- `system`：不启用分配器特性覆盖进行构建和运行；\n- `jemalloc`：使用 `--features jemalloc` 构建；\n- `auto`：优先使用 `jemalloc`，若构建失败则回退到 `system`。\n\n如果请求使用 `jemalloc` 但当前构建无法启用，则运行将强制使用系统分配器，并在产物中注明回退原因。\n\n### 内存使用情况\n\nRust 的所有权模型使得内存使用可预测，且无需垃圾回收停顿：\n\n| 状态 | 内存 |\n|-------|--------|\n| 启动（空闲） | ~15MB |\n| 活跃会话（小型） | ~25MB |\n| 上下文中有大文件 | ~30-50MB |\n| 流式响应 | +0MB（流式传输，不缓冲） |\n\n由于没有垃圾回收机制，流式输出过程中不会出现意外的延迟高峰。\n\n### 流式架构\n\n响应从 API 到终端以逐令牌的方式流式传输，几乎不进行缓冲：\n\n```\nAPI 服务器 → TCP → SSE 解析器 → 事件处理器 → 终端\n     │                              │\n     └──────── 无缓冲 ────────┘\n```\n\n每个令牌在离开 Anthropic 服务器后几毫秒内就会显示在屏幕上。SSE 解析器会实时处理到达的事件，而不会等待完整的响应。\n\n### TUI 渲染性能\n\n交互式 TUI 的目标是实现 60 帧每秒的渲染，并采用了多层优化：\n\n**帧时间遥测**：每个渲染周期都会被监控。耗时较长的帧（>16 毫秒）会被记录下来，并按阶段分类：视口同步、消息编码、Markdown 渲染。这些数据会输入到内部性能监控器中。\n\n**消息渲染缓存**：Markdown 到 ANSI 的转换涉及语法高亮、表格布局和链接检测。Pi 会为每条消息缓存渲染结果，仅在主题更改或终端大小调整时才会失效。在流式传输过程中，只有正在变化的消息才会重新渲染；之前的所有消息都会命中缓存。\n\n**预分配的渲染缓冲区**：`RenderBuffers` 结构会在各个渲染周期中重复使用。Pi 不会在每一帧都分配新的 `String` 缓冲区，而是将内容写入预先分配好的缓冲区，并在下次使用前清空它们，从而避免在流式传输过程中每秒产生数千次的小内存分配。\n\n**内存压力监控**：`MemoryMonitor` 会采样进程堆大小，并将其分为三个等级：\n\n| 等级 | 阈值 | 行动 |\n|------|-----------|--------|\n| **正常** | 小于预算的 80% | 无操作 |\n| **压力** | 预算的 80%-95% | 收起工具输出显示，隐藏思考提示框 |\n| **严重** | 超过预算的 95% | 截断旧消息，强制进行内存压缩 |\n\n这种渐进式的降级策略能够在长时间会话且积累了大量工具输出时，保持 Pi 的响应速度。\n\n---\n\n## 故障排除\n\n如需更完整的指南，请参阅 [docs\u002Ftroubleshooting.md](docs\u002Ftroubleshooting.md)。\n\n### “未找到 fd”\n\n`find` 工具需要 `fd`：\n\n```bash\n# Ubuntu\u002FDebian\napt install fd-find\n\n# macOS\nbrew install fd\n\n# 该二进制文件可能名为 fdfind\nln -s $(which fdfind) ~\u002F.local\u002Fbin\u002Ffd\n```\n\n### “未设置 API 密钥”\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# 或者在 settings.json 中\n{ \"apiKey\": \"sk-ant-...\" }\n\n# 或者针对单个命令\npi --api-key \"sk-ant-...\" \"Hello\"\n```\n\n### “会话损坏”\n\n会话是以追加方式写入的 JSONL 文件。如果发生损坏：\n\n```bash\n# 从头开始\npi --no-session\n\n# 或者删除有问题的会话\nrm ~\u002F.pi\u002Fagent\u002Fsessions\u002F--home-user-project--\u002Fcorrupted-session.jsonl\n```\n\n### “流式传输卡住”\n\n请检查您的网络连接。Pi 使用 SSE 协议，需要稳定的连接：\n\n```bash\n# 使用 curl 测试\ncurl -N https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages\n```\n\n### “工具输出被截断”\n\n这是为了防止上下文溢出而有意为之。您可以使用偏移量\u002F限制参数：\n\n```bash\n# 在对话中\n“读取那文件的第 2000 到 4000 行”\n```\n\n---\n\n## 限制\n\nPi 对自身无法完成的功能坦诚相待：\n\n| 限制 | 替代方案 |\n|------------|------------|\n| **并非支持所有提供商的 API** | 内置支持包括 Anthropic、OpenAI（Chat + Responses）、Gemini、Cohere、Azure OpenAI、Bedrock、Vertex AI、GitHub Copilot 和 GitLab Duo；一些特定生态系统的 API 仍在规划中 |\n| **不支持网页浏览** | 可以使用 bash 结合 curl |\n| **无 GUI** | 设计上仅为终端界面 |\n| **部分扩展需要 npm 存根** | 目前仍有 5 个 npm 包尚未适配；详情请参阅 EXTENSIONS.md 第 8.1 节 |\n| **主要面向英语用户** | 虽然可以使用，但并未针对其他语言进行优化 |\n| **需要 nightly Rust 版本** | 使用了 2024 年版的新特性 |\n\n---\n\n## 设计哲学\n\n### 规范优先的移植\n\n本次移植采用“规范提取”方法，而非逐行翻译：\n\n1. **提取行为**：研究 TypeScript 实现，理解其“做什么”，而非“如何做”\n2. **记录规范**：写下预期的行为、边界情况和不变量\n3. **根据规范实现**：编写符合规范的 idiomatic Rust 代码\n4. **一致性测试**：通过基于固定场景的测试验证行为是否一致\n\n这种方法比机械翻译能产生更好的代码。TypeScript 的惯用模式（回调、Promise、类层次结构）与 Rust 的所有权模型、trait 和枚举并不完全对应。强行适应语言反而会降低代码质量，不如顺应语言特性来得更好。\n\n### 一致性测试\n\n测试套件包含基于固定场景的一致性测试，用于验证工具的行为：\n\n```json\n{\n  \"version\": \"1.0\",\n  \"tool\": \"edit\",\n  \"cases\": [\n    {\n      \"name\": \"edit_simple_replace\",\n      \"setup\": [\n        {\"type\": \"create_file\", \"path\": \"test.txt\", \"content\": \"Hello, World!\"}\n      ],\n      \"input\": {\n        \"path\": \"test.txt\",\n        \"oldText\": \"World\",\n        \"newText\": \"Rust\"\n      },\n      \"expected\": {\n        \"content_contains\": [\"Successfully replaced\"],\n        \"details\": {\"oldLength\": 5, \"newLength\": 4}\n      }\n    }\n  ]\n}\n```\n\n每个场景指定了：\n- **设置**：测试前需要创建的文件或目录\n- **输入**：工具参数\n- **期望结果**：输出内容中的模式、字段精确匹配，或错误条件\n\n这样就可以在不依赖具体实现细节的情况下，验证 Rust 实现是否与 TypeScript 原版一致。\n\n### 扩展系统\n\nPi 通过嵌入的 QuickJS 运行时支持传统的 JS\u002FTS 扩展。与传统的插件系统不同，扩展运行在一个 **沙盒化、能力受限** 的环境中，没有任何对操作系统的访问权限：\n\n1. **无需 Node\u002FBun**：QuickJS 加上 Pi 提供的常见 Node API 适配层\n2. **基于能力的安全机制**：每次调用主机连接器都会经过策略检查并记录日志\n3. **一致性测试**：兼容性状态会在 `docs\u002Fext-compat.md` 和 `tests\u002Fext_conformance\u002Freports\u002Fpipeline\u002F` 中跟踪\n4. **加载时间小于 100 毫秒**：扩展加载时间通常低于 100 毫秒（P95），且无需 JIT 预热\n\n遗留扩展的行为是自动化的：\n- 现有的 `.js\u002F.ts` 扩展可以直接运行（无需手动转换）。\n- `*.native.json` 描述文件是可选的，主要用于原生 Rust 运行时的工作流程。\n- 当前一个会话只能使用一种运行时家族（JS\u002FTS 或原生描述文件）。\n\n政策预设快速入门：\n\n```bash\n# 查看当前生效的政策\npi --explain-extension-policy\n\n# 为单个命令切换配置文件（safe | balanced | permissive）\npi --extension-policy balanced --explain-extension-policy\n\n# 仍然接受旧的别名：\npi --extension-policy standard --explain-extension-policy\n\n# 选择性启用危险能力（推荐优于 permissive）\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n```\n\n运营部署手册（以兼容性为主的本地默认设置 + 显式锁定）：\n\n```bash\n# 1) 基线：确认默认设置是兼容性优先（permissive）\npi --explain-extension-policy\n\n# 2) 阶段性：使用 balanced 提示，危险能力仍默认拒绝\npi --extension-policy balanced --explain-extension-policy\n\n# 3) 显式锁定，适用于严格的本地或 CI 环境\npi --extension-policy safe --explain-extension-policy\n\n# 4) 选择性启用危险能力（推荐路径）\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n\n# 5) 显式宽容模式，当你希望避免歧义时\npi --extension-policy permissive --explain-extension-policy\n```\n\n本地\u002F开发环境的 `settings.json` 基线：\n\n```json\n{\n  \"extensionPolicy\": {\n    \"defaultPermissive\": true\n  }\n}\n```\n\n使用以下配置可恢复更严格的默认行为，而无需命令行参数：\n\n```json\n{\n  \"extensionPolicy\": {\n    \"defaultPermissive\": false\n  }\n}\n```\n\n交互式 TUI：打开 `\u002Fsettings` 并切换 `extensionPolicy.defaultPermissive`。\n\nCI 指导：\n\n```bash\n# CI 默认：保持危险能力禁用\npi --extension-policy safe --explain-extension-policy\n\n# CI 可选任务（仅在必要时），保持明确且可审计\nPI_EXTENSION_ALLOW_DANGEROUS=1 pi --extension-policy balanced --explain-extension-policy\n```\n\n回滚规则：移除 `PI_EXTENSION_ALLOW_DANGEROUS`，将 `extensionPolicy.profile` 恢复为 `safe`，或将 `extensionPolicy.defaultPermissive` 设置为 `false`，然后重新运行 `pi --explain-extension-policy` 以确认拒绝决策。\n\n完整架构、运行时契约及合规性结果，请参阅 [EXTENSIONS.md](EXTENSIONS.md)。\n\n### 禁止不安全代码\n\n`#![forbid(unsafe_code)]` 指令适用于整个项目，且不可更改。理由如下：\n\n- **攻击面**：Pi 会执行用户提供的 shell 命令并读取任意文件。\n- **内存错误即安全漏洞**：在此上下文中发生的缓冲区溢出或释放后使用等内存问题可能被利用。\n- **性能无关紧要**：瓶颈在于与 API 的网络延迟，而非 CPU 周期。\n- **依赖项已审计**：所有依赖项要么不使用不安全代码，要么经过充分审计（例如 `rustls`）。\n\n安全的 Rust 子集提供了所有必要的功能，同时不会损害安全性。\n\n---\n\n## 常见问题解答\n\n**问：与原始 Pi Agent 有何关系？**  \n答：这是由 [Mario Zechner](https:\u002F\u002Fgithub.com\u002Fbadlogic) 授权的 [Pi Agent](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi) 的 Rust 移植版，并得到了他的许可。其架构与 TypeScript 原版有显著不同：它使用 [asupersync](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fasupersync) 实现结构化并发，并使用 [rich_rust](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Frich_rust)（Will McGugan 的 [Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich) 库的移植版）进行终端渲染。目标是在保留 Pi Agent 用户体验的同时，实现地道的 Rust 编程风格。\n\n**问：为什么要用 Rust 重写？**  \n答：在终端中长时间工作时，启动时间至关重要。Rust 的启动时间不到 100 毫秒，而 Node.js 则需要 500 毫秒以上。此外，Rust 不需要管理运行时依赖。\n\n**问：除了 Anthropic 外，是否可以使用其他提供商（OpenAI\u002FGemini\u002FCohere\u002FAzure\u002FBedrock\u002FVertex\u002FCopilot\u002FGitLab\u002FCodex）？**  \n答：是的。原生支持的提供商包括 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\u002FQwen 以及 Moonshot\u002FKimi）。提供商 ID 和别名不区分大小写。通过 `--provider`\u002F`--model` 设置凭据和选择模型；运行 `pi --list-providers` 查看规范 ID、别名和环境变量键。\n\n**问：会话是如何工作的？**  \n答：每个会话是一个包含消息条目的 JSONL 文件。会话按项目划分（基于工作目录），并通过父引用支持分支。\n\n**问：为什么禁止不安全代码？**  \n答：对于一个执行任意命令的工具来说，内存安全是不可妥协的。在这种场景下，性能开销可以忽略不计。\n\n**问：如何扩展 Pi？**  \n答：Pi 拥有完整的扩展系统，包含两个运行时家族：JS\u002FTS 入口点在嵌入式 QuickJS 中运行，而 `*.native.json` 描述符则在原生 Rust 描述符运行时中运行。两者都受到能力约束，并通过相同的策略系统进行审计。一次会话只能使用其中一个运行时家族。扩展可以注册工具、斜杠命令、事件钩子、标志以及自定义提供商。详细信息请参阅 [EXTENSIONS.md](EXTENSIONS.md)。对于内置工具的修改，请在 `src\u002Ftools.rs` 中实现 `Tool` 特性。\n\n**问：为什么不包含 X 功能？**  \n答：Pi 专注于核心编码辅助功能。诸如网页浏览、图像生成等功能不在其范围内。这些功能应使用专门的工具来完成。\n\n**问：压缩机制是如何工作的？**  \n答：当对话超过模型的上下文窗口时，Pi 会使用 LLM 自身总结较早的消息，并将总结作为会话条目存储。最近的消息则原样保留。截断点会选择在一轮对话的边界处，总结中还会记录曾读取或修改过的文件，以便模型能够保持对这些信息的认知。压缩会在每次代理回复后自动触发（如需），也可以通过 `\u002Fcompact` 手动触发。\n\n**问：能否添加 Pi 原生不支持的自定义提供商？**  \n答：可以。在 `~\u002F.pi\u002Fagent\u002F` 或 `.pi\u002F` 目录下创建一个 `models.json` 文件，指定模型 ID、基础 URL 和 API 类型（通常为 `openai-completions`，用于与 OpenAI 兼容的端点）。Pi 的兼容性配置系统会处理字段名称差异和功能标志覆盖。扩展也可以注册完全自定义的提供商。\n\n**问：Pi 如何决定恢复哪个会话？**  \n答：Pi 维护着一个 SQLite 索引，记录所有会话文件。当你运行 `pi -c` 时，它会查询索引，找到最近修改且工作目录与当前项目匹配的会话。这样可以避免每次恢复时扫描整个文件系统。\n\n**问：如果扩展尝试访问危险资源，会发生什么？**  \n答：扩展发起的每个宿主调用在执行前都会根据当前的能力策略进行检查。在 `safe` 和 `balanced` 策略下，危险能力（如 `exec`、`env`）默认会被拒绝，除非显式启用（例如通过设置 `PI_EXTENSION_ALLOW_DANGEROUS=1`）。而在 `permissive` 策略下，则允许使用这些能力。对于 `exec` 调用，Pi 会在实际执行前进行命令中介：它会分类命令和参数签名，并默认阻止关键类别（例如递归删除、磁盘\u002F设备写入、反向 Shell 等）。严格或安全策略还可以进一步阻止高级别的操作（例如关机、进程终止、修改凭证文件等）。被拒绝的调用会返回错误到扩展的 Promise 路径，拒绝事件也会记录在脱敏后的安全警报和命令中介审计日志中。敏感的环境变量（API 密钥、令牌、秘密）始终会被过滤。若行为升级，可以立即将该扩展隔离至“killed”状态，或强制将其路由到兼容通道，作为调查期间的遏制措施。\n\n**问：Pi 是否支持自托管或代理的 LLM？**  \n答：是的。可以通过 `models.json` 将任何提供商指向自定义的基础 URL。Pi 会根据 API 类型规范化 URL 路径，并针对字段名称和功能差异应用兼容性覆盖。这适用于 vLLM、Ollama、LiteLLM 等与 OpenAI 兼容的服务器。\n\n---\n\n## 对比\n\n| 特性 | Pi | Claude Code | Aider | Cursor |\n|---------|-----|-------------|-------|--------|\n| **语言** | Rust | TypeScript | Python | Electron |\n| **启动时间** | \u003C100ms | ~1s | ~2s | ~5s |\n| **内存占用** | \u003C50MB | ~200MB | ~150MB | ~500MB |\n| **模型提供商** | Anthropic + OpenAI\u002FResponses + Gemini\u002FCohere + Azure\u002FBedrock\u002FVertex + Copilot\u002FGitLab + 兼容OpenAI的预设 | Anthropic | 多家 | 多家 |\n| **工具** | 8个内置 | 多种 | 文件优先 | 集成于IDE |\n| **会话管理** | JSONL树 | 专有格式 | 基于Git | 专有格式 |\n| **开源** | 是 | 是 | 是 | 否 |\n\n---\n\n## 开发\n\n### 构建\n\n```bash\nrch exec -- cargo build           # 调试构建（远程卸载）\nrch exec -- cargo build --release # 发布构建（优化，远程卸载）\nrch exec -- cargo test            # 运行测试（远程卸载）\n# 静态检查（远程安全分割，避免rch clippy超时导致故障转移）\nrch exec -- cargo clippy --lib --bins -- -D warnings\nrch exec -- cargo clippy --tests -- -D warnings\nrch exec -- cargo clippy --benches -- -D warnings\nrch exec -- cargo clippy --examples -- -D warnings\n```\n\n### 测试\n\n```bash\n# 统一验证运行器（推荐用于生成确定性证据文件）\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --profile focused\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --profile ci\n.\u002Fscripts\u002Fe2e\u002Frun_all.sh --rerun-from tests\u002Fe2e_results\u002F\u003Ctimestamp>\u002Fsummary.json --skip-unit\n\n# 快速冒烟测试\u002F扩展质量封装，并严格远程执行\n.\u002Fscripts\u002Fsmoke.sh --require-rch\n.\u002Fscripts\u002Fext_quality_pipeline.sh --require-rch\n\n# 多智能体安全性：设置CODEX_THREAD_ID后，run_all默认将\n# CARGO_TARGET_DIR指向target\u002Fagents\u002F\u003CCODEX_THREAD_ID>，除非被覆盖。若需自定义共享或隔离的目标目录，请显式设置CARGO_TARGET_DIR。\n\n# 执行所有测试\nrch exec -- cargo test\n\n# 指定模块\nrch exec -- cargo test tools::tests\nrch exec -- cargo test sse::tests\n\n# 符合性测试\nrch exec -- cargo test conformance\n```\n\n专注验证工具：\n\n```bash\n# 发布构建前的开发阶段门控\nrch exec -- cargo build --bin pi --bin ext_release_binary_e2e\nPI_HTTP_REQUEST_TIMEOUT_SECS=0 rch exec -- \\\n  cargo run --bin ext_release_binary_e2e -- \\\n  --pi-bin target\u002Fdebug\u002Fpi \\\n  --provider ollama --model qwen2.5:0.5b \\\n  --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced\n\n# 门控通过后的完整优化发布二进制运行\nrch exec -- cargo build --release --bin pi --bin ext_release_binary_e2e\nPI_HTTP_REQUEST_TIMEOUT_SECS=0 target\u002Frelease\u002Fext_release_binary_e2e \\\n  --pi-bin target\u002Frelease\u002Fpi \\\n  --provider ollama --model qwen2.5:0.5b \\\n  --jobs 10 --timeout-secs 600 --extension-policy balanced\n\n# 运行时风险账本取证（验证、回放、校准）\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- verify --input path\u002Fto\u002Fruntime_risk_ledger.json\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- replay --input path\u002Fto\u002Fruntime_risk_ledger.json\nrch exec -- cargo run --bin ext_runtime_risk_ledger -- calibrate --input path\u002Fto\u002Fruntime_risk_ledger.json --objective balanced_accuracy\n```\n\n- `ext_runtime_risk_ledger`操作`pi.ext.runtime_risk_ledger.v1`工件（例如来自事件包导出）。\n\n### 发布与发布\n\n发布以标签驱动，必须与`Cargo.toml`版本一致。\n\n- 标签格式：`vX.Y.Z`（允许预发布如`vX.Y.Z-rc.N`，但跳过crates.io发布）。\n- 标签版本**必须**匹配`Cargo.toml`中的`package.version`。\n- 依赖项发布顺序：`asupersync` → `rich_rust` → `charmed-*`（lipgloss、bubbletea、bubbles、glamour）→ `pi_agent_rust`。\n- `.github\u002Fworkflows\u002Fpublish.yml`在设置`CARGO_REGISTRY_TOKEN`时处理crates.io发布。\n\n### 覆盖率\n\n覆盖率使用`cargo-llvm-cov`：\n\n```bash\n# 一次性安装\ncargo install cargo-llvm-cov --locked\nrustup component add llvm-tools-preview\n\n# 概要（最快）\ncargo llvm-cov --all-targets --workspace --summary-only\n\n# LCOV报告（用于CI\u002F工件）\nCI=true VCR_MODE=playback VCR_CASSETTE_DIR=tests\u002Ffixtures\u002Fvcr \\\n  cargo llvm-cov --all-targets --workspace --lcov --output-path lcov.info\n\n# HTML报告（默认输出到target\u002Fllvm-cov\u002Fhtml）\ncargo llvm-cov --all-targets --workspace --html\n```\n\n### 项目结构\n\n精选核心模块（非详尽）：\n\n```\nsrc\u002F\n├── main.rs                # CLI入口点\n├── lib.rs                 # 库导出\n├── app.rs                 # 启动\u002F模型选择辅助\n├── agent.rs               # 智能体循环+事件编排\n├── agent_cx.rs            # asupersync能力上下文连接\n├── cli.rs                 # 参数解析\n├── config.rs              # 配置\n├── auth.rs                # API密钥\u002FOAuth\u002FAWS凭证存储\n├── model.rs               # 消息\u002F内容\u002F流事件类型\n├── provider.rs            # 提供者trait\n├── provider_metadata.rs   # 规范提供者ID+路由默认值\n├── models.rs              # 模型注册表+models.json覆盖\n├── providers\u002F\n│   ├── anthropic.rs        # Anthropic Messages API\n│   ├── openai.rs           # OpenAI Chat Completions\n│   ├── openai_responses.rs # OpenAI Responses API\n│   ├── gemini.rs           # Gemini API\n│   ├── cohere.rs           # Cohere Chat API\n│   ├── azure.rs            # Azure OpenAI\n│   ├── bedrock.rs          # Amazon Bedrock Converse\n│   ├── vertex.rs           # Google Vertex AI\n│   ├── copilot.rs          # GitHub Copilot后端\n│   ├── gitlab.rs           # GitLab Duo后端\n│   └── mod.rs              # 提供者工厂+扩展桥接\n├── tools.rs                # 内置工具实现\n├── sse.rs                  # 流式SSE解析器\n├── http\u002F\n│   ├── client.rs           # asupersync支持的HTTP客户端\n│   ├── sse.rs              # HTTP SSE辅助\n│   └── mod.rs\n├── session.rs              # JSONL会话持久化\u002F树操作\n├── session_index.rs        # SQLite会话元数据索引\u002F缓存\n├── session_sqlite.rs       # 可选的sqlite会话后端\n├── compaction.rs           # 上下文压缩算法\n├── interactive.rs          # 交互式TUI应用循环\u002F状态\n├── interactive\u002F            # Bubble Tea风格的TUI子模块\n├── rpc.rs                  # RPC\u002Fstdio模式\n├── extensions.rs           # 扩展协议+策略+安全\n├── extensions_js.rs        # QuickJS运行时桥接+宿主调用\n├── extension_dispatcher.rs # 宿主调用\u002F工具调度管道\n├── extension_preflight.rs  # 扩展兼容性扫描\n├── extension_validation.rs # 扩展验证流水线衔接\n├── resources.rs            # 技能\u002F提示\u002F主题\u002F扩展加载\n└── tui.rs                  # 终端UI渲染辅助\n```\n\n---\n\n## 文档索引\n\n以下每条记录包括文档名称、用途、核心要点及直接链接。\n\n| 类别 | 涵盖内容 | 跳转 |\n|---|---|---|\n| 扩展生态系统 | 扩展架构、语料库、目录、一致性、兼容性 | [前往](#1-extension-ecosystem) |\n| 核心运维与用户体验 | 治理、CI\u002FQA 运维、快捷键、提示、打包、模型\u002F配置用户体验、无缝迁移\u002F认证 | [前往](#2-core-ops-and-ux) |\n| 提供商子系统 | 提供商审计、部署契约、对等性和修复工件 | [前往](#3-provider-subsystem) |\n| 质量保证、模式、安全与平台 | 发布\u002FQA 运行手册、模式、安全基线、平台指南 | [前往](#4-qa-schemas-security-and-platform) |\n\n### 1. 扩展生态系统\n\n- `docs\u002FBRANCH_PROTECTION.md` - 目的：定义分支保护策略和执行规则。核心要点：为确保主线完整性，CI 和评审门控是强制性的。链接：[查看](docs\u002FBRANCH_PROTECTION.md)\n- `docs\u002FEXTENSION_CANDIDATES.md` - 目的：列出待纳入和测试的候选扩展。核心要点：从这份长列表开始进行扩展的筛选工作。链接：[查看](docs\u002FEXTENSION_CANDIDATES.md)\n- `docs\u002FEXTENSION_CAPTURE_SCENARIOS.md` - 目的：定义扩展捕获与回放场景。核心要点：使用这些场景来实现扩展行为的确定性捕获。链接：[查看](docs\u002FEXTENSION_CAPTURE_SCENARIOS.md)\n- `docs\u002FEXTENSION_POPULARITY_CRITERIA.md` - 目的：说明如何对扩展的受欢迎程度进行评分。核心要点：受欢迎程度的决策应遵循明确的排名标准。链接：[查看](docs\u002FEXTENSION_POPULARITY_CRITERIA.md)\n- `docs\u002FEXTENSION_REFRESH_CHECKLIST.md` - 目的：扩展语料库更新的操作检查清单。核心要点：按照此清单安全且可重复地更新语料库。链接：[查看](docs\u002FEXTENSION_REFRESH_CHECKLIST.md)\n- `docs\u002FEXTENSION_SAMPLE.md` - 目的：人类可读的示例扩展契约。核心要点：在编写新的扩展包时参考此文档。链接：[查看](docs\u002FEXTENSION_SAMPLE.md)\n- `docs\u002FEXTENSION_SAMPLING_MATRIX.md` - 目的：定义扩展采样策略及分层。核心要点：测试覆盖率来源于此采样矩阵。链接：[查看](docs\u002FEXTENSION_SAMPLING_MATRIX.md)\n- `docs\u002FLEGACY_EXTENSION_RUNNER.md` - 目的：解释旧版扩展运行时的行为与限制。核心要点：用于兼容性背景说明，而非新运行时设计。链接：[查看](docs\u002FLEGACY_EXTENSION_RUNNER.md)\n- `docs\u002FPIJS_PROOF_REPORT.md` - 目的：提供 PiJS 运行时属性的正式证明。核心要点：PiJS 在设计上消除了环境权限。链接：[查看](docs\u002FPIJS_PROOF_REPORT.md)\n- `docs\u002FTEST_COVERAGE_MATRIX.md` - 目的：将模块映射到测试套件及覆盖率状态。核心要点：这是覆盖率缺口仪表盘。链接：[查看](docs\u002FTEST_COVERAGE_MATRIX.md)\n- `docs\u002Fcapability-prompts.md` - 目的：记录能力提示的 UX 及政策语义。核心要点：提示是政策性产物，而非临时 UI。链接：[查看](docs\u002Fcapability-prompts.md)\n- `docs\u002Fci-operator-runbook.md` - 目的：面向维护者的 CI 操作手册。核心要点：在 CI 管道中发生故障时使用本手册进行响应。链接：[查看](docs\u002Fci-operator-runbook.md)\n- `docs\u002Fconformance-operator-playbook.md` - 目的：一致性测试活动的操作指南。核心要点：使用本 playbook 进行一致性测试，以获得可重复的结果。链接：[查看](docs\u002Fconformance-operator-playbook.md)\n- `docs\u002Fcoverage-baseline-map.json` - 目的：机器可读的覆盖率基线映射。核心要点：自动化系统应以此作为覆盖率基线的事实来源。链接：[查看](docs\u002Fcoverage-baseline-map.json)\n- `docs\u002Fdevelopment.md` - 目的：面向贡献者的开发工作流程参考。核心要点：这是官方的本地开发设置指南。链接：[查看](docs\u002Fdevelopment.md)\n- `docs\u002Fe2e_scenario_matrix.json` - 目的：机器可读的端到端场景矩阵。核心要点：端到端测试的范围及预期流程在此定义。链接：[查看](docs\u002Fe2e_scenario_matrix.json)\n- `docs\u002Fevidence-contract-schema.json` - 目的：证据工件及日志的模式文件。核心要点：证据生产者必须符合此契约。链接：[查看](docs\u002Fevidence-contract-schema.json)\n- `docs\u002Fext-compat.md` - 目的：解释扩展兼容性态势及边界。核心要点：这是快速兼容性参考。链接：[查看](docs\u002Fext-compat.md)\n- `docs\u002Fextension-api-matrix.json` - 目的：扩展宿主与运行时调用的 API 表面矩阵。核心要点：通过此矩阵可一目了然地了解支持的扩展 API。链接：[查看](docs\u002Fextension-api-matrix.json)\n- `docs\u002Fextension-architecture.md` - 目的：深入探讨扩展运行时内部架构。核心要点：这是主要的扩展技术设计文档。链接：[查看](docs\u002Fextension-architecture.md)\n- `docs\u002Fextension-artifact-provenance.json` - 目的：扩展工件的溯源元数据。核心要点：此处跟踪工件的信任关系与 lineage。链接：[查看](docs\u002Fextension-artifact-provenance.json)\n- `docs\u002Fextension-candidate-pool.json` - 目的：机器可读的扩展候选池。核心要点：摄入\u002F选择任务应从此池中读取。链接：[查看](docs\u002Fextension-candidate-pool.json)\n- `docs\u002Fextension-catalog.json` - 目的：主扩展目录及其状态元数据。核心要点：这是官方的扩展清单。链接：[查看](docs\u002Fextension-catalog.json)\n- `docs\u002Fextension-catalog.schema.json` - 目的：验证扩展目录文档的模式文件。核心要点：目录更新必须通过此模式验证。链接：[查看](docs\u002Fextension-catalog.schema.json)\n- `docs\u002Fextension-code-search-inventory.json` - 目的：跨扩展仓库的代码搜索结果清单。核心要点：将其用作原始搜索证据。链接：[查看](docs\u002Fextension-code-search-inventory.json)\n- `docs\u002Fextension-code-search-summary.json` - 目的：扩展代码搜索清单的汇总结果。核心要点：顶级代码搜索发现在此浓缩呈现。链接：[查看](docs\u002Fextension-code-search-summary.json)\n- `docs\u002Fextension-collections.json` - 目的：按主题\u002F范围对扩展集合进行分组。核心要点：集合级别的规划由此开始。链接：[查看](docs\u002Fextension-collections.json)\n- `docs\u002Fextension-compatibility-matrix.md` - 目的：扩展运行时支持级别的兼容性矩阵。核心要点：在声称存在兼容性差距之前，请先查阅此矩阵。链接：[查看](docs\u002Fextension-compatibility-matrix.md)\n- `docs\u002Fextension-conformance-matrix.json` - 目的：机器可读的扩展一致性测试结果。核心要点：这是自动化的一致性真值表。链接：[查看](docs\u002Fextension-conformance-matrix.json)\n- `docs\u002Fextension-conformance-test-plan.json` - 目的：扩展一致性测试的计划文件。核心要点：一致性测试的执行应遵循此计划。链接：[查看](docs\u002Fextension-conformance-test-plan.json)\n- `docs\u002Fextension-curated-list-summary.json` - 目的：精选扩展子集的摘要。核心要点：用于快速做出精选语料库的决策。链接：[查看](docs\u002Fextension-curated-list-summary.json)\n- `docs\u002Fextension-entry-scan.json` - 目的：扩展入口点检测的扫描结果。核心要点：扩展入口假设在此得到验证。链接：[查看](docs\u002Fextension-entry-scan.json)\n- `docs\u002Fextension-inclusion-list.json` - 目的：扩展集合的明确纳入清单。核心要点：此清单控制哪些内容属于运行范围。链接：[查看](docs\u002Fextension-inclusion-list.json)\n- `docs\u002Fextension-individual-enumeration.json` - 目的：每个扩展的详细枚举信息及元数据。核心要点：可在此深入查看单个扩展记录。链接：[查看](docs\u002Fextension-individual-enumeration.json)\n- `docs\u002Fextension-license-report.json` - 目的：扩展语料库的许可证审计结果。核心要点：许可证风险及状态在此被捕捉。链接：[查看](docs\u002Fextension-license-report.json)\n- `docs\u002Fextension-master-catalog.json` - 目的：权威上游扩展目录的快照。核心要点：这为全语料库同步及溯源检查提供了基准。链接：[查看](docs\u002Fextension-master-catalog.json)\n- `docs\u002Fextension-npm-scan-summary.json` - 目的：基于 npm 的扩展扫描输出摘要。核心要点：npm 扫描态势在此总结。链接：[查看](docs\u002Fextension-npm-scan-summary.json)\n- `docs\u002Fextension-onboarding-queue.json` - 目的：扩展工作的机器可读入队列。核心要点：队列自动化应消费此文件。链接：[查看](docs\u002Fextension-onboarding-queue.json)\n- `docs\u002Fextension-onboarding-queue.md` - 目的：人类可读的扩展入队列及上下文。核心要点：这是操作员的队列看板。链接：[查看](docs\u002Fextension-onboarding-queue.md)\n- `docs\u002Fextension-priority-summary.json` - 目的：扩展优先级信号的汇总。核心要点：优先级汇总在此集中管理。链接：[查看](docs\u002Fextension-priority-summary.json)\n- `docs\u002Fextension-priority.json` - 目的：详细的扩展优先级评分数据。核心要点：每个扩展的优先级在此以机器可读的形式呈现。链接：[查看](docs\u002Fextension-priority.json)\n- `docs\u002Fextension-registry.md` - 目的：记录扩展注册表模型及使用方式。核心要点：注册表的行为及期望在此定义。链接：[查看](docs\u002Fextension-registry.md)\n- `docs\u002Fextension-repo-search-summary.json` - 目的：仓库级别扩展发现搜索的汇总。核心要点：仓库发现的结果在此整合。链接：[查看](docs\u002Fextension-repo-search-summary.json)\n- `docs\u002Fextension-research-playbook.json` - 目的：扩展研究工作流的机器可读 playbook。核心要点：研究的执行步骤及输出在此被形式化。链接：[查看](docs\u002Fextension-research-playbook.json)\n- `docs\u002Fextension-runtime-threat-model.md` - 目的：以运行时为中心的扩展威胁模型，包含控制措施和测试。核心要点：此模型将具体的运行时滥用路径与其缓解措施对应起来。链接：[查看](docs\u002Fextension-runtime-threat-model.md)\n- `docs\u002Fextension-sample.json` - 目的：机器可读的扩展样本载荷\u002F规范。核心要点：将其用作官方的样本 JSON 契约。链接：[查看](docs\u002Fextension-sample.json)\n- `docs\u002Fextension-tiered-corpus.json` - 目的：用于扩展测试的分层语料库构成。核心要点：语料库的层级及成员资格在此定义。链接：[查看](docs\u002Fextension-tiered-corpus.json)\n- `docs\u002Fextension-tiered-summary.json` - 目的：分层语料库覆盖情况及数量的汇总。核心要点：语料库各层级的健康状况在此总结。链接：[查看](docs\u002Fextension-tiered-summary.json)\n- `docs\u002Fextension-troubleshooting.md` - 目的：专门针对扩展运行时问题的故障排除指南。核心要点：遇到扩展失败或策略拒绝时，应从此处开始排查。链接：[查看](docs\u002Fextension-troubleshooting.md)\n- `docs\u002Fextension-validated-dedup.json` - 目的：去重后的已验证扩展列表。核心要点：使用此列表可避免重复的扩展工件。链接：[查看](docs\u002Fextension-validated-dedup.json)\n\n### 2. 核心运维与用户体验\n\n- `docs\u002Fflake-triage-policy.md` - 目的：用于检测和分类处理测试不稳定性的策略。核心要点：所有不稳定性问题必须按照此标准进行分类和处理。链接：[查看](docs\u002Fflake-triage-policy.md)\n- `docs\u002Fkeybindings.md` - 目的：交互式 TUI 的快捷键参考。核心要点：这是操作员的快捷键映射表。链接：[查看](docs\u002Fkeybindings.md)\n- `docs\u002Fmodels.md` - 目的：模型目录的行为、选择及覆盖规则。核心要点：模型解析逻辑在此文档中详细说明。链接：[查看](docs\u002Fmodels.md)\n- `docs\u002Fnon-mock-rubric.json` - 目的：定义非模拟测试期望的标准。核心要点：使用此标准来确保真实行为证据的质量。链接：[查看](docs\u002Fnon-mock-rubric.json)\n- `docs\u002Fpackages.md` - 目的：软件包安装及内容规范。核心要点：软件包的使用方式和结构在此文档中定义。链接：[查看](docs\u002Fpackages.md)\n- `docs\u002Fasupersync-leverage-inventory.md` - 目的：详细列出在 Pi 核心模块中，进一步利用 Asupersync 技术能够带来高价值的具体场景。核心要点：在引入继承的 `AgentCx` 或替换原始线程岛之前，请先从这里开始规划。链接：[查看](docs\u002Fasupersync-leverage-inventory.md)\n- `docs\u002Fdropin-certification-contract.json` - 目的：严格的即插即用认证合同及准入门槛。核心要点：严格意义上的替代性消息传递由该合同及其硬性门槛控制。链接：[查看](docs\u002Fdropin-certification-contract.json)\n- `docs\u002Fdropin-parity-gap-ledger.json` - 目的：机器可读的已知即插即用兼容性差距及其严重程度记录。核心要点：未解决的严重或高危差距将阻止严格替代性消息的发布。链接：[查看](docs\u002Fdropin-parity-gap-ledger.json)\n- `docs\u002Fintegrator-migration-playbook.md` - 目的：从 TypeScript 版本的 Pi 迁移到 Rust 版本的 Pi 时，运营商\u002F集成商的迁移与回滚操作指南。核心要点：使用此手册执行分阶段、基于证据的迁移流程。链接：[查看](docs\u002Fintegrator-migration-playbook.md)\n- `docs\u002Fparity-certification.json` - 目的：机器可读的兼容性进度快照。核心要点：仅提供信息性状态；严格意义上的替代性发布声明仍由即插即用合同及兼容性差距的修复状态决定。链接：[查看](docs\u002Fparity-certification.json)\n- `docs\u002Fprogram-governance.md` - 目的：关于路线图、准入条件及所有权的治理模式。核心要点：治理决策及其责任在此文档中明确界定。链接：[查看](docs\u002Fprogram-governance.md)\n- `docs\u002Fprompt-templates.md` - 目的：提示模板系统及使用指南。核心要点：可通过此文档管理可重用的提示行为。链接：[查看](docs\u002Fprompt-templates.md)\n- `docs\u002Fsdk.md` - 目的：SDK 使用指南及嵌入 Pi 程序的迁移手册。核心要点：使用此文档可以快速实现 TypeScript SDK 工作流到 Rust 等效代码的复制粘贴。链接：[查看](docs\u002Fsdk.md)\n- `docs\u002Fintegrator-migration-playbook.md` - 目的：面向下游集成商，从 TypeScript 版本的 Pi 迁移到 Rust 版本的 Pi 时的逐步迁移与兼容性验证操作手册。核心要点：遵循此手册可安全地执行并验证迁移决策是否可行。链接：[查看](docs\u002Fintegrator-migration-playbook.md)\n\n### 3. 提供者子系统\n\n- `docs\u002Fprovider-audit-evidence-index.json` - 用途：提供商审计证据工件索引。核心要点：审计可追溯性由此索引开始。链接：[查看](docs\u002Fprovider-audit-evidence-index.json)\n- `docs\u002Fprovider-audit-reconciliation-ledger.json` - 用途：提供商审计对账决策账本。核心要点：差异及解决方案均在此记录。链接：[查看](docs\u002Fprovider-audit-reconciliation-ledger.json)\n- `docs\u002Fprovider-auth-crosswalk.json` - 用途：提供商身份验证别名\u002F环境键对照表。核心要点：凭证解析映射集中于此。链接：[查看](docs\u002Fprovider-auth-crosswalk.json)\n- `docs\u002Fprovider-auth-failure-signatures.json` - 用途：已知的提供商身份验证失败签名和指纹。核心要点：通过比对此目录可诊断身份验证失败原因。链接：[查看](docs\u002Fprovider-auth-failure-signatures.json)\n- `docs\u002Fprovider-auth-playbook-validation.json` - 用途：提供商身份验证 playbook 覆盖情况的验证结果。核心要点：此处衡量身份验证 playbook 的质量。链接：[查看](docs\u002Fprovider-auth-playbook-validation.json)\n- `docs\u002Fprovider-auth-redaction-diagnostics.json` - 用途：提供商身份验证脱敏行为的诊断信息。核心要点：脱敏的正确性及缺失部分在此记录。链接：[查看](docs\u002Fprovider-auth-redaction-diagnostics.json)\n- `docs\u002Fprovider-auth-troubleshooting.md` - 用途：提供商身份验证问题故障排除指南。核心要点：遇到提供商密钥或身份验证问题时，应首先参考此文档。链接：[查看](docs\u002Fprovider-auth-troubleshooting.md)\n- `docs\u002Fprovider-baseline-audit.json` - 用途：机器可读的基础版提供商审计数据。核心要点：结构化的提供商基准证据存储于此。链接：[查看](docs\u002Fprovider-baseline-audit.json)\n- `docs\u002Fprovider-baseline-audit.md` - 用途：叙述性的基础版提供商审计报告。核心要点：此处解释了提供商差距的高层次概况。链接：[查看](docs\u002Fprovider-baseline-audit.md)\n- `docs\u002Fprovider-canonical-id-policy.json` - 用途：机器可读的规范提供商 ID 政策。核心要点：提供商 ID 规范化规则在此定义。链接：[查看](docs\u002Fprovider-canonical-id-policy.json)\n- `docs\u002Fprovider-canonical-id-policy.md` - 用途：人类可读的规范提供商 ID 政策。核心要点：这是规范性的提供商命名政策。链接：[查看](docs\u002Fprovider-canonical-id-policy.md)\n- `docs\u002Fprovider-canonical-id-table.json` - 用途：规范提供商 ID 查找表。核心要点：使用此表可进行确定性的提供商 ID 映射。链接：[查看](docs\u002Fprovider-canonical-id-table.json)\n- `docs\u002Fprovider-cerebras-capability-profile.json` - 用途：Cerebras 提供商能力简介。核心要点：Cerebras 的支持范围及约束条件在此列出。链接：[查看](docs\u002Fprovider-cerebras-capability-profile.json)\n- `docs\u002Fprovider-cerebras-setup.json` - 用途：Cerebras 部署\u002F配置契约。核心要点：使用此工件可配置 Cerebras。链接：[查看](docs\u002Fprovider-cerebras-setup.json)\n- `docs\u002Fprovider-closure-truth-table.json` - 用途：提供商审计状态的闭合真值表。核心要点：这是提供商闭合情况的记分牌。链接：[查看](docs\u002Fprovider-closure-truth-table.json)\n- `docs\u002Fprovider-config-examples.json` - 用途：机器可读的提供商配置示例。核心要点：自动化就绪的示例配置存储于此。链接：[查看](docs\u002Fprovider-config-examples.json)\n- `docs\u002Fprovider-config-examples.md` - 用途：人类可读的提供商配置示例。核心要点：设置提供商时可从此处复制配置。链接：[查看](docs\u002Fprovider-config-examples.md)\n- `docs\u002Fprovider-discrepancy-classification.json` - 用途：提供商差异类别的分类体系。核心要点：使用此模式可对提供商不匹配情况进行分类。链接：[查看](docs\u002Fprovider-discrepancy-classification.json)\n- `docs\u002Fprovider-discrepancy-ledger.json` - 用途：具体的提供商差异账本。核心要点：差异的历史及状态在此追踪。链接：[查看](docs\u002Fprovider-discrepancy-ledger.json)\n- `docs\u002Fprovider-gaps-audit-report.json` - 用途：汇总的提供商差距审计报告。核心要点：提供商对等性差距在此量化。链接：[查看](docs\u002Fprovider-gaps-audit-report.json)\n- `docs\u002Fprovider-gaps-test-matrix.json` - 用途：用于弥补提供商差距的测试矩阵。核心要点：缺少的提供商测试在此枚举。链接：[查看](docs\u002Fprovider-gaps-test-matrix.json)\n- `docs\u002Fprovider-gate-compiler-report.json` - 用途：编译器\u002F构建检查生成的提供商门控报告。核心要点：此处显示编译时的提供商门控状态。链接：[查看](docs\u002Fprovider-gate-compiler-report.json)\n- `docs\u002Fprovider-gate-e2e-report.json` - 用途：端到端测试生成的提供商门控报告。核心要点：提供商 E2E 门控结果在此记录。链接：[查看](docs\u002Fprovider-gate-e2e-report.json)\n- `docs\u002Fprovider-gate-tests-report.json` - 用途：整合的提供商测试门控报告。核心要点：此处呈现提供商测试通过\u002F失败的情况。链接：[查看](docs\u002Fprovider-gate-tests-report.json)\n- `docs\u002Fprovider-gate-triage-matrix.json` - 用途：提供商门控失败的分类与处理矩阵。核心要点：使用此矩阵可快速处理提供商门控失败问题。链接：[查看](docs\u002Fprovider-gate-triage-matrix.json)\n- `docs\u002Fprovider-gate-ubs-report.json` - 用途：UBS 扫描工具针对提供商门控运行的输出报告。核心要点：提供商中的漏洞扫描结果在此记录。链接：[查看](docs\u002Fprovider-gate-ubs-report.json)\n- `docs\u002Fprovider-groq-capability-profile.json` - 用途：Groq 提供商能力简介。核心要点：Groq 的支持范围及限制在此定义。链接：[查看](docs\u002Fprovider-groq-capability-profile.json)\n- `docs\u002Fprovider-groq-setup.json` - 用途：Groq 提供商部署契约。核心要点：按照此规范配置 Groq。链接：[查看](docs\u002Fprovider-groq-setup.json)\n- `docs\u002Fprovider-implementation-modes.json` - 用途：提供商实现模式分类。核心要点：通过此文件可了解哪些提供商是原生、桥接或模拟的。链接：[查看](docs\u002Fprovider-implementation-modes.json)\n- `docs\u002Fprovider-kimi-capability-profile.json` - 用途：Kimi 提供商能力简介。核心要点：Kimi 的行为边界在此记录。链接：[查看](docs\u002Fprovider-kimi-capability-profile.json)\n- `docs\u002Fprovider-kimi-setup.json` - 用途：Kimi 提供商部署契约。核心要点：使用此契约可完成 Kimi 的集成部署。链接：[查看](docs\u002Fprovider-kimi-setup.json)\n- `docs\u002Fprovider-longtail-evidence.md` - 用途：长尾提供商覆盖情况的证据报告。核心要点：长尾提供商的支持声明在此得到证实。链接：[查看](docs\u002Fprovider-longtail-evidence.md)\n- `docs\u002Fprovider-migration-guide.md` - 用途：提供商模型变更迁移指南。核心要点：迁移提供商集成时应遵循此指南。链接：[查看](docs\u002Fprovider-migration-guide.md)\n- `docs\u002Fprovider-native-parity-report.json` - 用途：原生提供商对等性状态报告。核心要点：原生对等性的进展在此衡量。链接：[查看](docs\u002Fprovider-native-parity-report.json)\n- `docs\u002Fprovider-onboarding-checklist.md` - 用途：新增提供商的入驻检查清单。核心要点：所有新提供商的加入都必须通过此清单。链接：[查看](docs\u002Fprovider-onboarding-checklist.md)\n- `docs\u002Fprovider-onboarding-playbook.md` - 用途：提供商入驻生命周期的操作手册。核心要点：这是端到端的入驻流程手册。链接：[查看](docs\u002Fprovider-onboarding-playbook.md)\n- `docs\u002Fprovider-openrouter-auth-contract.json` - 用途：OpenRouter 身份验证行为契约。核心要点：OpenRouter 的身份验证解析必须符合此契约。链接：[查看](docs\u002Fprovider-openrouter-auth-contract.json)\n- `docs\u002Fprovider-openrouter-capability-profile.json` - 用途：OpenRouter 能力简介。核心要点：OpenRouter 的功能边界在此记录。链接：[查看](docs\u002Fprovider-openrouter-capability-profile.json)\n- `docs\u002Fprovider-openrouter-dynamic-models-contract.json` - 用途：OpenRouter 动态模型行为契约。核心要点：动态模型处理规则在此定义。链接：[查看](docs\u002Fprovider-openrouter-dynamic-models-contract.json)\n- `docs\u002Fprovider-openrouter-model-registry-contract.json` - 用途：OpenRouter 模型注册表契约及期望。核心要点：注册表一致性要求在此规定。链接：[查看](docs\u002Fprovider-openrouter-model-registry-contract.json)\n- `docs\u002Fprovider-openrouter-setup.json` - 用途：OpenRouter 部署\u002F配置契约。核心要点：使用此工件可配置 OpenRouter。链接：[查看](docs\u002Fprovider-openrouter-setup.json)\n- `docs\u002Fprovider-parity-checklist.json` - 用途：提供商对等性关闭标准检查清单。核心要点：对等性完成的各个关卡在此编码。链接：[查看](docs\u002Fprovider-parity-checklist.json)\n- `docs\u002Fprovider-parity-reconciliation-report.json` - 用途：提供商对等性对账报告。核心要点：对账结果及理由在此说明。链接：[查看](docs\u002Fprovider-parity-reconciliation-report.json)\n- `docs\u002Fprovider-parity-reconciliation.json` - 用途：机器可读的对等性对账账本。核心要点：这是结构化的对等性对账记录。链接：[查看](docs\u002Fprovider-parity-reconciliation.json)\n- `docs\u002Fprovider-qwen-capability-profile.json` - 用途：Qwen 提供商能力简介。核心要点：Qwen 的支持范围及约束条件在此记录。链接：[查看](docs\u002Fprovider-qwen-capability-profile.json)\n- `docs\u002Fprovider-qwen-setup.json` - 用途：Qwen 提供商部署契约。核心要点：使用此文件可配置 Qwen。链接：[查看](docs\u002Fprovider-qwen-setup.json)\n- `docs\u002Fprovider-remediation-manifest.json` - 用途：提供商补救行动清单。核心要点：补救工作的积压及责任归属在此追踪。链接：[查看](docs\u002Fprovider-remediation-manifest.json)\n- `docs\u002Fprovider-remediation-routing-validation.json` - 用途：提供商补救路由逻辑的验证。核心要点：此处证明路由的正确性。链接：[查看](docs\u002Fprovider-remediation-routing-validation.json)\n- `docs\u002Fprovider-support-baseline-audit.md` - 用途：已声明的提供商支持情况的基础审计。核心要点：通过此次审计，支持声明得以证实。链接：[查看](docs\u002Fprovider-support-baseline-audit.md)\n- `docs\u002Fprovider-test-matrix-validation-report.json` - 用途：提供商测试矩阵完整性的验证报告。核心要点：此处衡量提供商测试矩阵的健康状况。链接：[查看](docs\u002Fprovider-test-matrix-validation-report.json)\n- `docs\u002Fprovider-test-obligations.md` - 用途：定义提供商特定的测试义务及门控条件。核心要点：这是提供商测试的契约。链接：[查看](docs\u002Fprovider-test-obligations.md)\n- `docs\u002Fprovider-upstream-catalog-snapshot.json` - 用途：上游提供商目录的机器可读快照。核心要点：从该快照开始检测上游变化。链接：[查看](docs\u002Fprovider-upstream-catalog-snapshot.json)\n- `docs\u002Fprovider-upstream-catalog-snapshot.md` - 用途：上游提供商快照变化的叙述性摘要。核心要点：此处解释了上游提供商的变化。链接：[查看](docs\u002Fprovider-upstream-catalog-snapshot.md)\n- `docs\u002Fprovider_e2e_artifact_contract.json` - 用途：提供商 E2E 证据的工件契约。核心要点：提供商 E2E 工件必须符合此规范。链接：[查看](docs\u002Fprovider_e2e_artifact_contract.json)\n- `docs\u002Fproviders.md` - 用途：提供商架构、行为及使用参考。核心要点：这是主要的提供商子系统指南。链接：[查看](docs\u002Fproviders.md)\n\n### 4. 质量保证、模式、安全性和平台\n\n- `docs\u002Fqa-runbook.md` - 用途：跨套件和工件的 QA 操作手册。核心要点：用于可重复的 QA 执行。链接：[查看](docs\u002Fqa-runbook.md)\n- `docs\u002Freleasing.md` - 用途：发布流程及检查清单文档。核心要点：遵循此文档以实现一致、安全的发布。链接：[查看](docs\u002Freleasing.md)\n- `docs\u002Frpc.md` - 用途：RPC 模式协议及使用契约。核心要点：这是 RPC 的底层集成指南。链接：[查看](docs\u002Frpc.md)\n- `docs\u002Fschema\u002Fextension_manifest.json` - 用途：扩展清单的 JSON 模式。核心要点：扩展清单验证必须通过此模式。链接：[查看](docs\u002Fschema\u002Fextension_manifest.json)\n- `docs\u002Fschema\u002Fextension_protocol.json` - 用途：扩展协议消息的 JSON 模式。核心要点：扩展消息契约在此处正式化。链接：[查看](docs\u002Fschema\u002Fextension_protocol.json)\n- `docs\u002Fschema\u002Fmock_spec.json` - 用途：模拟\u002F测试规范固定装置的模式。核心要点：模拟固定装置应符合此契约。链接：[查看](docs\u002Fschema\u002Fmock_spec.json)\n- `docs\u002Fschema\u002Fruntime_hostcall_telemetry.json` - 用途：运行时主机调用遥测事件的 JSON 模式。核心要点：主机调用遥测数据生产者必须符合此模式。链接：[查看](docs\u002Fschema\u002Fruntime_hostcall_telemetry.json)\n- `docs\u002Fsec_traceability_matrix.json` - 用途：机器可读的安全需求可追溯性矩阵。核心要点：此处跟踪安全覆盖和测试映射关系。链接：[查看](docs\u002Fsec_traceability_matrix.json)\n- `docs\u002Fsec_traceability_matrix.md` - 用途：包含需求与测试关联的叙述性安全可追溯性矩阵。核心要点：此处记录人类可读的安全覆盖状态。链接：[查看](docs\u002Fsec_traceability_matrix.md)\n- `docs\u002Fsecurity\u002Fbaseline-audit.md` - 用途：基于代码的安全基线审计及差距分析。核心要点：这是当前安全态势的快照。链接：[查看](docs\u002Fsecurity\u002Fbaseline-audit.md)\n- `docs\u002Fsecurity\u002Fincident-response-runbook.md` - 用途：安全事件的应急响应流程。核心要点：在发生安全事件时遵循本手册。链接：[查看](docs\u002Fsecurity\u002Fincident-response-runbook.md)\n- `docs\u002Fsecurity\u002Fincident-runbook.md` - 用途：事件检测、分类和处理指南。核心要点：用于初始事件分诊和升级处理。链接：[查看](docs\u002Fsecurity\u002Fincident-runbook.md)\n- `docs\u002Fsecurity\u002Finvariants.machine.json` - 用途：可机器检查的安全不变量清单及测试映射。核心要点：不变量自动化应读取此文件。链接：[查看](docs\u002Fsecurity\u002Finvariants.machine.json)\n- `docs\u002Fsecurity\u002Finvariants.md` - 用途：规范性的安全不变量及优先级语义。核心要点：这是 SEC-1.2 政策\u002F风险契约。链接：[查看](docs\u002Fsecurity\u002Finvariants.md)\n- `docs\u002Fsecurity\u002Flockfile-format.md` - 用途：用于验证扩展完整性的锁文件格式规范。核心要点：此处定义了锁文件结构及验证规则。链接：[查看](docs\u002Fsecurity\u002Flockfile-format.md)\n- `docs\u002Fsecurity\u002Fmaintenance-playbook.md` - 用途：安全维护程序及计划性操作。核心要点：用于日常安全维护和策略更新。链接：[查看](docs\u002Fsecurity\u002Fmaintenance-playbook.md)\n- `docs\u002Fsecurity\u002Fmanifest-v2-migration.md` - 用途：从旧版扩展清单迁移到 v2 安全字段的迁移指南。核心要点：使用此文档可在不丢失功能或策略意图的情况下升级清单。链接：[查看](docs\u002Fsecurity\u002Fmanifest-v2-migration.md)\n- `docs\u002Fsecurity\u002Foperator-handbook.md` - 用途：全面的安全运维手册。核心要点：这是日常工作的主要安全运维参考。链接：[查看](docs\u002Fsecurity\u002Foperator-handbook.md)\n- `docs\u002Fsecurity\u002Foperator-quick-reference.md` - 用途：安全运维人员快速参考卡。核心要点：在操作过程中使用此备忘录进行快速查询。链接：[查看](docs\u002Fsecurity\u002Foperator-quick-reference.md)\n- `docs\u002Fsecurity\u002Fpolicy-tuning-guide.md` - 用途：扩展安全策略及风险阈值的调整指南。核心要点：此处提供策略校准和调整流程。链接：[查看](docs\u002Fsecurity\u002Fpolicy-tuning-guide.md)\n- `docs\u002Fsecurity\u002Fruntime-hostcall-telemetry.md` - 用途：运行时主机调用遥测设计及事件目录。核心要点：此处记录主机调用可观ability及事件语义。链接：[查看](docs\u002Fsecurity\u002Fruntime-hostcall-telemetry.md)\n- `docs\u002Fsecurity\u002Fsecurity-slos.md` - 用途：定量安全 SLO、风险预算以及发布\u002F回滚门控。核心要点：安全发布的就绪状态在此处以数值形式进行门控。链接：[查看](docs\u002Fsecurity\u002Fsecurity-slos.md)\n- `docs\u002Fsecurity\u002Fthreat-model.md` - 用途：正式的扩展生态系统威胁模型。核心要点：这是 SEC-1.1 攻击者及控制基准。链接：[查看](docs\u002Fsecurity\u002Fthreat-model.md)\n- `docs\u002Fsession.md` - 用途：会话模型、持久化及分支语义。核心要点：会话行为和存储契约在此处。链接：[查看](docs\u002Fsession.md)\n- `docs\u002Fsettings.md` - 用途：设置模式、优先级及配置行为。核心要点：配置行为在此处被规范化。链接：[查看](docs\u002Fsettings.md)\n- `docs\u002Fskills.md` - 用途：技能系统使用及打包指南。核心要点：通过已记录的技能契约扩展提示行为。链接：[查看](docs\u002Fskills.md)\n- `docs\u002Fstreaming-hostcalls.md` - 用途：流式主机调用行为及生命周期细节。核心要点：可用于推断流式工具的执行情况。链接：[查看](docs\u002Fstreaming-hostcalls.md)\n- `docs\u002Fterminal-setup.md` - 用途：终端环境设置及人体工学指导。核心要点：推荐的终端配置在此处。链接：[查看](docs\u002Fterminal-setup.md)\n- `docs\u002Ftermux.md` - 用途：针对 Termux 的特定设置及运行时指导。核心要点：Android\u002FTermux 的使用在此处记录。链接：[查看](docs\u002Ftermux.md)\n- `docs\u002Ftest_double_inventory.json` - 用途：测试替身及模拟接口清单。核心要点：可通过此文件审计测试替身的使用情况。链接：[查看](docs\u002Ftest_double_inventory.json)\n- `docs\u002Ftesting-policy.md` - 用途：测试政策、质量标准及测试套件期望。核心要点：这是规范性的测试治理文档。链接：[查看](docs\u002Ftesting-policy.md)\n- `docs\u002Fthemes.md` - 用途：主题系统配置及自定义。核心要点：终端渲染主题在此处记录。链接：[查看](docs\u002Fthemes.md)\n- `docs\u002Ftraceability_matrix.json` - 用途：需求到测试的可追溯性矩阵。核心要点：需求证据的可追溯性信息保存于此。链接：[查看](docs\u002Ftraceability_matrix.json)\n- `docs\u002Ftree.md` - 用途：会话树导航及分支行为指南。核心要点：可用于理解对话树的操作。链接：[查看](docs\u002Ftree.md)\n- `docs\u002Ftroubleshooting.md` - 用途：常见故障的一般故障排除指南。核心要点：非扩展相关的运维问题可从此处开始排查。链接：[查看](docs\u002Ftroubleshooting.md)\n- `docs\u002Ftui.md` - 用途：TUI 行为、控件及渲染说明。核心要点：交互式 UI 语义在此处定义。链接：[查看](docs\u002Ftui.md)\n- `docs\u002Fwindows.md` - 用途：Windows 特定的安装及运行时指导。核心要点：Windows 支持详情在此处集中。链接：[查看](docs\u002Fwindows.md)\n- `docs\u002Fwit\u002Fextension.wit` - 用途：用于扩展宿主契约的 WIT 接口定义。核心要点：此处定义了类型化的扩展宿主 ABI。链接：[查看](docs\u002Fwit\u002Fextension.wit)\n\n---\n\n\n\n## 关于贡献\n\n请不要误会，我目前不接受任何外部贡献。我真的没有精力去评审这些内容，而且项目上署的是我的名字，所以如果出现问题，责任也在我。从我的角度来看，这种风险与收益极不对等。此外，我还得考虑其他“利益相关方”，而对我这种主要为自己免费开发的工具来说，这样做并不明智。你仍然可以提交问题，甚至提出修复建议的拉取请求，但请理解，我不会直接合并它们。相反，我会让 Claude 或 Codex 通过 `gh` 工具来审查这些提交，并独立决定是否以及如何处理。尤其是漏洞报告，我们非常欢迎。如果这让你感到不适，我深表歉意，但我希望避免大家浪费时间或产生不必要的伤感。我也明白，这与当前倡导社区贡献的开源精神并不一致，但这是我能够保持现有开发速度并维持心理健康的方式。\n\n---\n\n## 许可证\n\nMIT 许可证（附带 OpenAI\u002FAnthropic 的附加条款）。详情请参阅 [LICENSE](LICENSE) 文件。\n\n---\n\n\u003Cp align=\"center\">\n  \u003Csub>使用 Rust 构建，专为习惯在终端中工作的开发者打造。\u003C\u002Fsub>\n\u003C\u002Fp>","# pi_agent_rust 快速上手指南\n\n**pi_agent_rust** 是一个用 Rust 编写的高性能 AI 编程助手命令行工具。相比传统的 Node.js\u002FPython 方案，它具有启动速度极快（\u003C100ms）、内存占用极低（空闲时 \u003C50MB）以及更强的安全扩展模型等优势。\n\n## 环境准备\n\n*   **操作系统**：支持 Linux、macOS 和 Windows (WSL)。\n*   **前置依赖**：无需安装 Node.js、Python 或 Electron 运行时。该工具为单二进制文件，开箱即用。\n*   **网络要求**：需要能够访问配置的 AI 模型提供商接口（如 OpenAI, Anthropic 等）。\n\n## 安装步骤\n\n推荐使用官方提供的一键安装脚本，自动下载最新发布的二进制文件并配置环境变量。\n\n在终端中执行以下命令：\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n安装完成后，重启终端或运行 `source ~\u002F.bashrc` (或 `~\u002F.zshrc`) 使 `pi` 命令生效。\n\n> **注意**：如果下载速度较慢，请检查本地网络环境或使用代理加速。目前项目暂未提供专门的国内镜像源，建议通过全局代理确保安装脚本顺利执行。\n\n## 基本使用\n\n安装成功后即可直接使用 `pi` 命令。以下是几种最常用的场景：\n\n### 1. 启动交互式会话\n直接输入 `pi` 进入交互模式，可以连续对话：\n\n```bash\npi\n```\n\n### 2. 单次提问或任务\n直接在命令后跟随提示词，获取结果后自动退出：\n\n```bash\npi \"Help me refactor this function to use async\u002Fawait\"\n```\n\n### 3. 结合文件上下文\n使用 `@` 符号引用本地文件，让 AI 基于具体代码进行分析：\n\n```bash\npi @src\u002Fmain.rs \"Explain startup flow\"\n```\n\n### 4. 管道输入模式\n将其他命令的输出或日志文件传递给 AI 进行分析：\n\n```bash\npi -p \"What does this error mean?\" \u003C error.log\n```\n\n### 5. 继续之前的会话\n自动加载上一次的项目会话记录，延续上下文：\n\n```bash\npi --continue\n```\n\n### 6. 查看可用模型与提供商\n列出当前配置支持的模型列表：\n\n```bash\npi --list-models\npi --list-providers\n```","资深后端工程师李工正在终端中紧急重构一个遗留的异步消息处理模块，需要频繁调用 AI 助手进行代码分析和生成。\n\n### 没有 pi_agent_rust 时\n- **启动延迟明显**：基于 Node.js 或 Python 的现有工具每次启动需等待 500ms 以上，打断高频交互的心流。\n- **资源占用过高**：Electron 架构或重型运行时长期驻留内存，占用数 GB 空间，导致本地 Docker 容器因资源不足而卡顿。\n- **会话稳定性差**：在处理长上下文代码流时，偶尔出现输出截断或会话意外崩溃，且错误原因难以追踪。\n- **安全顾虑重重**：缺乏细粒度的权限控制，担心 AI 插件无意中执行递归删除或写入系统盘等危险 Shell 命令。\n\n### 使用 pi_agent_rust 后\n- **即时响应体验**：得益于 Rust 编译为单一二进制文件，pi_agent_rust 实现毫秒级瞬间启动，指令发出即刻得到反馈。\n- **极致轻量运行**：内存占用极低，即使在长时间复杂会话中也能保持轻盈，不再挤压其他开发工具的生存空间。\n- **稳定可靠流式输出**：内置的结构化并发运行时确保了长文本生成的稳定性，彻底消除了会话损坏和静默失败的问题。\n- **原生安全防御**：通过能力门控和两阶段执行强制机制，默认拦截高危命令（如反向 Shell），让李工在放心授权的同时拥有完整的审计日志。\n\npi_agent_rust 将终端 AI 助手从“资源负担”转变为“安全、极速的原生生产力组件”，完美契合高性能开发需求。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_pi_agent_rust_38bb3d84.webp","Dicklesworthstone","Jeff Emanuel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FDicklesworthstone_c96b6d22.jpg","Building in NY",null,"doodlestein","https:\u002F\u002Fwww.jeffreyemanuel.com\u002F","https:\u002F\u002Fgithub.com\u002FDicklesworthstone",[81,85,89,93,97,101,105,109,113,117],{"name":82,"color":83,"percentage":84},"Rust","#dea584",49,{"name":86,"color":87,"percentage":88},"Python","#3572A5",18.7,{"name":90,"color":91,"percentage":92},"TypeScript","#3178c6",15.8,{"name":94,"color":95,"percentage":96},"JavaScript","#f1e05a",5.7,{"name":98,"color":99,"percentage":100},"Shell","#89e051",4.8,{"name":102,"color":103,"percentage":104},"TeX","#3D6117",2.2,{"name":106,"color":107,"percentage":108},"HTML","#e34c26",1.8,{"name":110,"color":111,"percentage":112},"Go","#00ADD8",0.7,{"name":114,"color":115,"percentage":116},"CSS","#663399",0.4,{"name":118,"color":119,"percentage":116},"Jinja","#a52a22",696,82,"2026-04-08T13:57:01","NOASSERTION",1,"Linux, macOS, Windows","未说明","最低 \u003C50MB (空闲状态)",{"notes":129,"python":130,"dependencies":131},"该工具是用 Rust 编写的独立二进制文件，无需 Python、Node.js 或 Bun 运行时。它通过提供的 install.sh 脚本安装，具有极快的启动速度（\u003C100ms）和极低的内存占用。安全模型包含对危险 shell 命令的默认拦截机制。","不需要",[132,133,134,135,136],"Rust 2024 Edition","asupersync","rich_rust","rustls","SQLite",[13,52],[139,140,141,142],"ai-agents","cli","developer-tools","rust","2026-03-27T02:49:30.150509","2026-04-09T09:32:49.206241",[146,151,156,161,166,170],{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},25798,"如何在 macOS 上解决 Bash 进程卡死或变成僵尸进程（zombie mode）的问题？","该问题已在版本 e45da6fb 中修复。根本原因是之前的修复只处理了部分代码路径，在 macOS 上使用 `try_wait()` (WNOHANG) 时，如果子进程在自己的进程组中，可能无法完全回收子进程导致僵尸进程。\n\n修复方案是在两个被遗漏的非流式执行路径中显式添加了 `child.wait()` 调用以确保清理僵尸进程：\n1. `src\u002Fextension_dispatcher.rs` (约第 3014 行)：在基于通道的执行路径中 `drop(rx)` 之后。\n2. `src\u002Fextensions.rs` (约第 22709 行)：在 `dispatch_hostcall_exec_ref_with_limit` 的 `try_wait` 循环之后。\n\n此外，`extension_dispatcher.rs` 中的有界通道大小已从 128 增加到 1024，以减少大量输出下的管道死锁风险。请确保更新到包含此修复的最新版本。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fissues\u002F41",{"id":152,"question_zh":153,"answer_zh":154,"source_url":155},25799,"该项目是否支持作为库（SDK）在其他 Rust 项目中以编程方式使用？","是的，项目已经支持 SDK\u002F编程模式。该 crate 既可作为二进制文件 (`pi`) 运行，也可作为库 (`pi`) 使用，`Cargo.toml` 中包含明确的 `[lib]` 部分。\n\n稳定的 SDK 接口主要位于 `src\u002Fsdk.rs`（约 2400 行），这是面向库的官方 API。用户可以通过依赖该 crate 来初始化代理、以编程方式处理输出流，并在自己的 Rust 项目中构建自定义工具。具体的用法示例可以参考项目中的 `examples\u002F` 目录或直接查阅 `src\u002Fsdk.rs` 中的公开 API 定义。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fissues\u002F40",{"id":157,"question_zh":158,"answer_zh":159,"source_url":160},25800,"是否支持类似 oh-my-pi 的 hashline 编辑功能以提高大文件编辑的可靠性？","是的，hashline 编辑方法已完全实现并集成到 pi_agent_rust 中。主要功能包括：\n\n1. **`hashline_edit` 工具**（默认启用）：使用 `LINE#HASH` 标签应用精确的文件编辑，支持替换、前置、追加操作，并进行哈希验证。它采用自底向上的多编辑排序和原子文件写入，包含 18+ 个测试用例。\n2. **`read` 工具**：支持 `hashline=true` 参数，将行输出为 `N#AB:content` 格式，以便与 `hashline_edit` 配合使用。\n3. **`grep` 工具**：支持 `hashline=true` 参数，输出带有 `N#AB` 标签的匹配行。\n4. **系统提示集成**：当启用相关工具时，系统提示会动态建议对大文件使用 hashline 工作流。\n\n该实现独立使用了 xxhash32 算法和自定义的 2 字符编码字母表。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fissues\u002F13",{"id":162,"question_zh":163,"answer_zh":164,"source_url":165},25801,"在执行 `\u002Fmodel` 命令后，模型选择列表溢出视口且滚动功能失效怎么办？","该问题已在提交 bda35a46 中修复。修复内容包括：\n1. 修复了视口滚动裁剪问题，为覆盖层增加了 2 行的安全边距。\n2. 为所有选择器（pickers）添加了 PgUp\u002FPgDn 键盘导航支持。\n3. 切换到 `mouse_all_motion` 事件模式以确保滚动事件的可靠性。\n\n如果您仍遇到此问题，请确保您使用的是包含上述修复的最新版本。如果问题依旧存在，可能是特定环境下的回归，建议重新打开 Issue 并提供复现步骤。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fissues\u002F27",{"id":167,"question_zh":168,"answer_zh":169,"source_url":155},25802,"是否可以用 Rust 而不是 JavaScript 编写扩展插件？","根据社区讨论，用户曾提出是否可以用 Rust 编写扩展。虽然原始 Issue 主要关注 SDK 模式，但维护者确认了项目作为库（library）的能力。由于 `pi_agent_rust` 本身就是一个 Rust crate 并且暴露了 SDK (`src\u002Fsdk.rs`)，理论上开发者可以通过引用该库并在其 Rust 项目中实现自定义逻辑来扩展功能，而不仅仅局限于 JS 扩展。具体的扩展架构细节建议查阅 `src\u002Fsdk.rs` 中的 API 文档以了解如何以编程方式拦截或增强代理行为。",{"id":171,"question_zh":172,"answer_zh":173,"source_url":174},25803,"项目是否提供 Nix flake 支持以便于在 Nix 环境中集成？","截至当前讨论，仓库尚未官方提供 `flake.nix` 文件。虽然有用户请求添加 Nix flake 以便下游项目（如 Yazelix）更方便地集成，避免手动打包，但该功能尚未被合并。\n\n目前下游用户如果需要在使用 Nix 的环境中部署，可能需要手动编写 derivations 进行打包。维护者表示如果未来有更明确的小范围需求或具体的打包障碍报告，可能会考虑重新审视此问题。建议关注仓库更新或暂时自行维护本地的 flake 配置。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fissues\u002F32",[176,181,186,191,196,201,206],{"id":177,"version":178,"summary_zh":179,"released_at":180},163139,"v0.1.10","## v0.1.10\n\n\n---\n\n### 快速安装\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh | bash\n```\n\n或者下载指定版本：\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fpi_agent_rust\u002Fmain\u002Finstall.sh | bash -s -- --version 0.1.10\n```\n\n### 手动安装\n\n下载适用于您平台的压缩包，解压后将 `pi` 放置到您的 `PATH` 环境变量中：\n\n| 平台         | 压缩包                     |\n|--------------|----------------------------|\n| Linux x86_64 | `pi-linux-amd64.tar.xz`    |\n| Linux ARM64  | `pi-linux-arm64.tar.xz`    |\n| macOS x86_64 | `pi-darwin-amd64.tar.xz`   |\n| macOS ARM64（Apple Silicon） | `pi-darwin-arm64.tar.xz` |\n| Windows x86_64 | `pi-windows-amd64.zip` |\n\n所有压缩包均包含 `SHA256SUMS` 文件，内含 SHA256 校验和，用于验证文件完整性。","2026-03-22T20:09:22",{"id":182,"version":183,"summary_zh":184,"released_at":185},163140,"v0.1.9","## 自 v0.1.8 以来的变更\n\n81bf62d4 杂项：将版本号更新至 0.1.9 以进行发布\n6ebfef87 修复（providers）：保留装饰后的 URL 规范化 [bd-3b2oe]\nab3ac638 修复（interactive）：在背压情况下保留异步错误事件 [bd-1d32t]\ncc97fa51 修复（interactive）：用支持背压的入队操作替换 try_send，用于扩展主机操作事件\n6693d2ac 修复（tests）：修正 HTTP 客户端测试中的 Host 头断言，并增加超时余量\n89c92ccb 新特性（agent、auth、providers、tui）：扩展会话支持压缩状态、未知凭据变体、URL 源验证以及波浪号分隔符支持\n3dcbf0a5 修复（interactive）：系统性地防止在背压下静默丢弃消息\n8dcf9458 修复（http、tools）：在零字节重试时刷新 TLS 写缓冲区，并强化 Bash 临时文件溢出错误处理\ne48d2b00 杂项：刷新测试工件、一致性报告和珠子跟踪器\nae105be3 修复（migrations、compaction、cli）：强化对格式错误条目的认证迁移，添加零使用率压缩测试，并修复配置路径回退逻辑\n77a44af4 修复（compaction、extensions、interactive）：引入令牌回退机制、模块路径遍历防护，以及基于配置的队列模式\n7722a148 修复（http）：添加 write_all_with_retry 方法，以处理来自 TLS 传输层的短暂 Ok(0) 响应\n4dbd0d43 修复（http）：按照 RFC 9110 处理合并的 Content-Length 头，并优化 PiMsg 下转型模式\n66e2c89b 修复（interactive）：在树形导航和分支选择器中优雅地处理代理忙碌状态\nc25efc65 修复（http）：验证 Content-Length 头，并拒绝格式错误或冲突的值\n431fba84 杂项：在 .gitignore 中添加按代理划分的远程构建目录模式，并更新珠子问题跟踪器\nea50b08d 杂项（beads）：关闭 Asupersync 巨型任务 bd-xdcrh\n36640ec0 修复（interactive）：在分支导航 UI 中正确处理繁忙会话锁 [bd-1hujq]\nd2092093 杂项：更新珠子问题跟踪器\n6e8b817e 修复（session_picker）：跳过未更改会话文件的重新解析，并减少测试的不稳定性","2026-03-12T06:34:24",{"id":187,"version":188,"summary_zh":189,"released_at":190},163141,"v0.1.8","版本 0.1.8","2026-02-28T06:48:26",{"id":192,"version":193,"summary_zh":194,"released_at":195},163142,"v0.1.6","版本 0.1.6","2026-02-21T01:34:21",{"id":197,"version":198,"summary_zh":199,"released_at":200},163143,"v0.1.4","## v0.1.4\n\n### 安全加固\n- **路径遍历防护**：`safe_canonicalize()` 通过支持符号链接的祖先解析进行逻辑规范化来处理不存在的路径；模块解析在扩展根目录内强制执行作用域单调性。\n- **命令混淆归一化**：新增 `normalize_command_for_classification()` 函数，在危险命令分类前去除 shell 混淆技术（如 `${ifs}`、反斜杠转义的空白字符）。\n- **内存溢出防护**：递归 JSON 哈希的深度限制为 128 层，`MAX_MODULE_SOURCE_BYTES` 限制为 1GB，`MAX_JOBS_PER_TICK` 限制为 10,000 个，SSE 缓冲区总大小限制为 10MB，单条事件缓冲区限制为 100MB。\n- **快速通道策略执行**：扩展调度器的快速通道现在会在执行宿主调用之前先进行能力策略检查。\n- **原子文件权限**：认证存储和 Anthropic 设备 ID 文件使用 `OpenOptions::mode(0o600)`，而非事后通过 `chmod` 设置权限。\n\n### 提供商改进\n- **Zero-copy OpenAI 序列化**：请求类型改用带生命周期参数的引用，而非拥有型字符串。\n- **空基础 URL 处理**：所有 `normalize_*_base` 函数现在对空值或仅包含空白的输入返回规范化的默认值。\n- **Gemini\u002FVertex 稳健性**：对于未知的部分类型（如可执行代码等），将静默跳过而不导致反序列化失败；开放思考块现在会发出 ThinkingEnd 事件。\n\n### 代理循环与 RPC\n- **多源消息获取器**：引导和后续消息获取器现基于 `Vec` 实现，支持累加注册，使 RPC 和扩展都能向队列中添加消息。\n- **队列边界**：`MAX_RPC_PENDING_MESSAGES` 限制为 128 条，`MAX_UI_PENDING_REQUESTS` 限制为 64 条，以防止内存溢出。\n- **错误持久化修复**：`max_tool_iterations` 错误现已同步到内存中的对话记录中。\n\n### 会话持久化\n- **批量索引更新**：按 `sessions_root` 分组，以摊薄数据库访问开销。\n- **RawValue 帧**：会话存储 v2 使用 `Box\u003CRawValue>`，避免重复序列化负载。\n- **部分加载跟踪**：引入 `v2_message_count_offset`，用于尾部模式的会话加载。\n\n### 工具\n- **正确的截断语义**：尾随换行符不再增加行数（“a\\n”算作 1 行，而非 2 行）。\n- **拒绝服务防护**：`BASH_FILE_LIMIT_BYTES` 限制为 100MB，防止无限制读取输出。\n\n### 宿主调用系统\n- **日志下沉批处理计划器**：通过日志调用缓冲保持全局请求顺序。\n- **基于生成密钥的幽灵缓存**：将 O(n) 的 `VecDeque` 扫描替换为 O(log n) 的幽灵操作。\n- **FIFO 调度器**：用 `VecDeque` 替代 `BinaryHeap` 作为单调序列的宏任务队列。\n\n### 安装程序\n- **移除自动钩子安装**：Claude Code 和 Gemini CLI 的预工具钩子不再自动注入。\n- **遗留清理**：幂等移除先前版本中由安装程序管理的钩子条目。\n\n### 其他\n- 扩展事件采用驼峰式序列化，与 TypeScript 的通信协议格式一致。\n- 诊断工具会检查 `rg` 和 `fd\u002Ffdfind` 依赖项。\n- Gist URL 解析器会拒绝个人资料链接和非规范路径。\n- TUI 标记解析器已重写为显式状态机实现。\n- 新增 9 个回归测试，覆盖安全修复内容。","2026-02-20T05:59:57",{"id":202,"version":203,"summary_zh":204,"released_at":205},163144,"v0.1.3","发布 0.1.3","2026-02-19T07:54:42",{"id":207,"version":208,"summary_zh":209,"released_at":210},163145,"v0.1.2","## v0.1.2\n\n### 修复\n- **OpenAI Codex 提供者**：添加了所有必需的 API 字段（`instructions`、`store`、`tool_choice`、`parallel_tool_calls`、`text.verbosity`、`include`、`reasoning`）\n- **OpenAI Codex 提供者**：跳过 `max_output_tokens`（Codex API 不支持）\n- **OpenAI Codex 提供者**：将实际思考层级传递给 `reasoning.effort`\n- **OpenAI Codex 提供者**：容忍流式响应中缺少 Content-Type 头\n- **安装程序**：重新排序下载候选，屏蔽 404 错误噪音\n- **Anthropic 测试**：修复了头部捕获测试\n\n### 提供者改进\n- 不区分大小写的提供者匹配\n- 支持 Kimi Code OAuth，凭证解析全面重构\n- 为 Kimi、Vercel 和 Azure 提供者提供便捷别名","2026-02-18T23:26:04"]