π 是一个运行在终端里的 AI 编程助手（coding agent）。它可以直接在你的项目目录里工作：读代码、改文件、跑命令，帮你完成从"解释一段代码"到"实现一个功能"的各种任务。
从 GitHub Releases 自动安装（自动探测操作系统/架构）：
curl -fsSL https://raw.githubusercontent.com/oouxx/pi-rs/main/install.sh | bash或手动安装：
./install.sh install # 安装
./install.sh update # 更新到最新版
./install.sh uninstall # 卸载# 直接问（默认交互模式）
pi-rs "帮我写一个 Rust 的斐波那契函数"
# 一次性提问，结果输出到终端（适合脚本/管道）
pi-rs -p "解释一下这个文件" < file.rs
# 引用文件一起提问
pi-rs -p "总结这个文档" @README.md
# 列出可用的模型
pi-rs --list-models首次使用前，配置你的模型和 API Key（环境变量，或 ~/.pi-rs/agent/auth.json，或 models.json 里的 provider 配置），然后 pi-rs --list-models 确认模型可用。
--list-models只列后端已实现的模型（anthropic-messages / openai-completions / openai-responses / pi-messages）。目录里属于 bedrock、vertex、mistral、azure-responses、codex 等尚未移植后端的模型会被隐藏，避免选中后必然请求失败。
在终端里启动一个对话会话，支持多轮对话、工具调用（读写文件、执行命令等）、会话历史保存与恢复。
pi-rs # 启动交互会话
pi-rs --continue # 继续最近一次会话
pi-rs --resume # 恢复最近一次会话
pi-rs --session <ID> # 按会话 ID 前缀（或 .jsonl 路径）恢复
pi-rs --fork <ID> # 从某个会话分叉出新会话适合快速提问、脚本调用、管道处理：
pi-rs -p "总结这个仓库的结构"
cat error.log | pi-rs -p "帮我分析这个报错"
pi-rs -p -m claude-sonnet-4-6 "用 Python 写一个快速排序"在 Zed 等支持 ACP（Agent Client Protocol）的编辑器里，把 π 配置为 ACP 代理，即可在编辑器内直接对话、查看工具执行过程：
pi-rs --acp编辑器会通过标准输入输出与 π 通信，你可以在编辑器里选择模型、调整思考强度、查看工具执行进度与输出。
pi-rs --mode json "..." # JSON 结构化输出，方便程序解析
pi-rs --mode rpc # RPC 模式（供外部工具调用）
pi-rs --export <会话文件.jsonl> # 导出会话为 HTML| 选项 | 说明 |
|---|---|
-m, --model |
指定模型（如 claude-sonnet-4-6） |
-P, --provider |
指定提供商 |
-k, --api-key |
直接指定 API Key |
--thinking |
思考强度：off / minimal / low / medium / high / xhigh |
--tools / --exclude-tools |
允许 / 排除特定工具（逗号分隔；短标志 -t / -xt）。内置工具：read、bash、edit、write、grep、find、ls（默认只激活前四个）；--tools read,grep,find,ls 即只读模式 |
--no-tools / --no-builtin-tools |
关闭全部工具 / 只关闭内置工具（扩展与 MCP 工具保留） |
--extension <PATH> |
加载扩展（可重复） |
--no-session |
不保存会话 |
--session-dir <DIR> |
自定义会话目录 |
--no-extensions / --no-skills |
禁用扩展 / skills 加载 |
--skills <PATH> |
追加 skill 目录或 .md 文件（可重复） |
--trust / --no-trust |
本会话信任 / 不信任项目（覆盖已存决策与默认策略） |
--default-trust <ask|always|never> |
覆盖本会话的 defaultProjectTrust 策略 |
--list-models [PATTERN] |
列出已配置凭据的可用模型（按 provider + id 模糊匹配；无命中时正常退出） |
-h, --help |
查看完整帮助 |
持久化初始工具集：在 ~/.pi-rs/agent/settings.json 或项目 .pi-rs/settings.json 里设置
"defaultTools"，普通名字整体替换默认集合（read/bash/edit/write），+name /
-name 在继承的集合上增减，例如 ["+grep", "+find", "+ls"]；/reload 会激活新加入的工具。
内置扩展默认关闭，用 "extensionsEnabled" 逐项开启（subagent / web_search）。
subagent 基于 agent 定义文件工作（默认只加载用户级 ~/.pi-rs/agent/agents/*.md）：
---
name: reviewer
description: Code review
tools: read, grep, find, bash
model: claude-sonnet-4-6 # 省略则继承当前会话的模型与 thinking level
---
You are a meticulous code reviewer...每个子 agent 跑在独立的 pi 进程里（隔离上下文），支持三种模式：single
（{agent, task}）、parallel（{tasks: [...]}，最多 8 个任务、4 路并发）、chain
（{chain: [...]}，顺序执行，{previous} 代入上一步输出）。项目级 agent 放
.pi-rs/agents/*.md，需显式传 agentScope: "both"（或 "project"），TUI 下还会先弹确认。
TUI 里工具块按 agent/模式渲染（agent 名 + 任务、tool call 列表、终稿 Markdown、
usage 统计），Ctrl+O 展开；运行中会跟着子 agent 的每条消息实时刷新，Ctrl+C
会立刻杀掉子进程。
web_search 的搜索/抓取后端在同一个 settings.json 里配置：
{
"extensionsEnabled": { "web_search": true },
"webSearch": {
"provider": "auto",
"deepseek": { "baseUrl": "https://api.deepseek.com", "apiKey": "${DEEPSEEK_API_KEY}" },
"ollama": { "host": "http://localhost:11434" }
}
}provider 取 auto（默认：有 DeepSeek 凭据就用 DeepSeek，否则用本地 Ollama）/ deepseek /
ollama。每一档都是「settings → 环境变量（PI_WEB_SEARCH_PROVIDER、DEEPSEEK_API_KEY、
DEEPSEEK_BASE_URL、OLLAMA_HOST/OLLAMA_BASE_URL）→ 内置默认」；apiKey 支持 ${ENV}
模板，/login deepseek 存的凭据也会被自动使用。
pi-rs update # 更新到最新 GitHub Release（--check/--force）
pi-rs update --models # 刷新模型目录（等价于 pi-rs refresh）
pi-rs config list # 查看当前生效的配置
pi-rs config <key> <value> # 写入配置（model/provider/theme/thinking_level，加 -l 写项目级）
pi-rs auth check # 检查认证状态
pi-rs auth print-api-key # 输出指定提供商的 API Key
pi-rs mcp list # 列出 MCP 服务器
pi-rs mcp add <name> -- <cmd> # 添加 stdio MCP 服务器（项目 .pi-rs/mcp.json）
pi-rs mcp add <name> --url <url> [--sse] [--header N:V] [--exposure direct|deferred|codemode|hidden]
pi-rs mcp enable|disable|remove <name>
pi-rs mcp login <name> # OAuth 登录（远程 MCP）
pi-rs mcp logout <name> # 删除已存 OAuth 凭据
# 会话内使用 /mcp 打开多级管理器（登录、重连、启停、Exposure、工具列表）在交互会话中，输入 / 开头的命令可以管理会话（Tab 可补全）：
/new— 开启新会话/name <name>— 设置会话名称/model <provider>/<id>— 切换模型/theme [dark|light]— 切换主题/compact [instructions]— 压缩上下文/copy— 复制最后一条回复/reload— 重新加载扩展/help— 查看命令列表/quit— 退出
扩展注册的命令和 skills 也会以斜杠命令的形式出现（如 /skill:xxx）。
默认按以下顺序发现 skill（同名先到者胜，顺序即系统提示中的顺序）：
- 项目
.pi-rs/skills/ - 项目各级
.agents/skills/（从当前目录向上直到 git 仓库根） - 用户
~/.pi-rs/agent/skills/ - 用户
~/.agents/skills/
.pi-rs/skills 与用户 skill 目录既可放 <name>/SKILL.md，也可直接放根级 <name>.md；
.agents/skills 不把根级 Markdown 当 skill，但会发现任意嵌套层级的 SKILL.md 或 .md。
frontmatter 中的 name / description 会被解析（disable-model-invocation: true
表示只允许 /skill:<name> 显式调用）。--skills <PATH> 使用当前项目目录作为相对路径基准，
并支持 ~ 展开；--no-skills 只关闭默认发现，不影响显式路径。
与 TS 原版的差异：
/login当前支持 API-key 登录，不支持 OAuth；/export支持基础 HTML 导出，但未复刻主题和自定义工具 renderer；部分 settings、selector 和 TUI 组件仍未完整移植。
-
会话记录保存在
~/.pi-rs/agent/sessions/ -
设置文件：
~/.pi-rs/agent/settings.json（默认模型/提供商、默认思考强度等参数） -
API Key：环境变量（如
ANTHROPIC_API_KEY）或~/.pi-rs/agent/auth.json -
模型列表：
~/.pi-rs/agent/models.json（可手动添加自定义 provider / 本地端点：baseUrl、apiKey、headers等） -
MCP 服务器：
~/.pi-rs/agent/mcp.json（全局）+{cwd}/.pi-rs/mcp.json（项目），使用通用mcpServers形状：{ "mcpServers": { "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "docs": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } }, "legacy": { "type": "sse", "url": "https://example.com/sse" } } }支持 stdio、streamable-HTTP 和 legacy SSE 三种传输；服务器工具会像内置工具一样注入所有模式。
enabled: false可临时禁用某条目。
项目信任默认策略为 always：未在 settings.json 配置 defaultProjectTrust 时，
项目一律视为受信任。需要收紧时在 settings 中设置 "defaultProjectTrust": "ask"
或 "never"，也可用 --default-trust 仅覆盖当前会话。项目资源加载门控本身仍按
已确认偏差不启用（见 DEVIATIONS.md）。
π 是 earendil-works/pi（TypeScript 版）的 Rust 移植。 原版由 Mario Zechner 开发，采用 MIT 许可证（Copyright (c) 2025 Mario Zechner）。 本项目以原版的设计与公开接口为基准，扩展系统与 TUI 组件层等模块改用了 Rust 生态的实现方式，有意保留的差异记录在 DEVIATIONS.md。感谢原作者的出色工作。