模型与账号接入

phi

pulseaiclub/phi · ★ 1,004

pulseaiclub

pi的编码代理 ∞ 提供者、子代理、hashline编辑和权限门

许可证
MIT
收录
2026-08-16
维护状态
active
安装方式
github
查看 manifest 检查详情
manifest 状态
未核验到
manifest 路径
-
manifest 检查
2026-08-19
生命周期脚本
未发现

manifest 静态检查只记录声明与安装脚本,不代表兼容性或安全审查。

安装

dsh plugin --profile web add github:pulseaiclub/phi

GitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试

安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗

项目说明

原始 README · 正文语言:中文 · 阅读英文 README

目录
  1. 赞助商
  2. 快速开始
  3. 资源占用
  4. 首帧时间
  5. 空闲内存 · 1 个会话
  6. 空闲内存 · 10 个会话
  7. 配置
  8. 工作区布局
  9. 交互模式
  10. 键盘快捷键
  11. Diff 审阅
  12. 代码查看器
  13. 切换分支
  14. 命令
  15. 会话
  16. 无头模式
  17. Skills(技能)
  18. Extensions(扩展)
  19. MCP
  20. 子代理
  21. 工具
  • 15 MB · ~31 ms · sub-agent · 锚点编辑 · 渐进式 MCP · PXB 插件 · 全屏审阅 & 代码选中 · OpenAI / Anthropic / Gemini

phi 欢迎界面

phi TUI

phi diff 审阅

你可以通过 Skills(技能)、Extensions(扩展) 和 MCP 扩展它——不必做成插件框架。

赞助商

想赞助 phi?联系 zhengel2022@163.com。

快速开始

安装最新发布版本(macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/pulseaiclub/phi/main/scripts/install.sh | bash

Windows(PowerShell 5.1+):

irm https://raw.githubusercontent.com/pulseaiclub/phi/main/scripts/install.ps1 | iex

首次启动需要配置模型。使用下面这个命令打开配置编辑器(会创建 ~/.phi 目录结构并写入 ~/.phi/config.yaml):

phi config

也可以设置环境变量做一次性运行:

export PHI_MODEL=gpt-4o
export PHI_API_KEY=sk-...

然后启动 TUI:

phi

或者从源码构建(Go 1.26.3+,见 go.mod):

make build          # 生成 ./phi
make install        # 构建并安装到 $GOBIN

首次启动时,phi 会自动创建 ~/.phi/{bin,skills,extensions,session,jobs}。搜索工具 (fd、rg)缺失时会在后台下载到 ~/.phi/bin。

TUI 给模型提供四个核心工具——read、write、edit 和 bash——外加 grep、find、ls。模型用这些工具来完成你的请求。外部 HTTP 抓取在配置 MCP 后可用。

资源占用

精简只是底线——phi 还要启动即开、负载下仍省内存。phi 数字来自剥离的发布构建 (CGO_ENABLED=0,-ldflags="-s -w"),在 macOS arm64 上测得。其他 harness 用已公开的 Linux PSS / 交互式 PTY 数据。

首帧时间

空闲内存 · 1 个会话

空闲内存 · 10 个会话

指标 phi
发布二进制 约 15 MB
空闲 RSS(1 个会话) 约 21 MB
10 个空闲会话(RSS 总量) 约 221 MB
首帧时间 约 31 ms(26–49 ms)
冷 go build(空 GOCACHE) 约 5.5 s
热重建 约 0.7 s
Go 源码(不含测试) 约 22k 行 / 107 个文件
Go 包数量 32
直接模块依赖 6(共 15 个模块)
链接运行时 仅系统库(无 Node / Electron / Python)

配置

phi 读取 ~/.phi/config.yaml(标准 YAML)。环境变量可覆盖配置,用于一次性运行。 phi config 会在终端里打开全屏编辑器来编辑同一个文件;不保存就不落盘,保存前 的旧文件会留作 config.yaml.bak。

phi config 按键
  ↑↓ ←→      移动 / 切换取值            a   新增模型
  ⏎          编辑,或打开选择列表       d   删除当前行
  esc        收起列表 / 退出            f   从服务商拉取模型列表
  ^s         保存                       s   保存     q  退出

留空表示「未设置」,也就是交给加载器填默认值;占位符显示的就是那个值。

# ~/.phi/config.yaml
models:
  - name: gpt-4o
    api: OpenAI             # OpenAI | OpenAIResponses | Anthropic | Gemini(空则走 OpenAI 兼容)
    api_key: sk-...         # 或设置 PHI_API_KEY
    base_url: https://api.openai.com/v1   # 默认;PHI_BASE_URL 可覆盖
    context_window: 128000  # 可选
    default: true           # 启动时使用的模型;缺省时第一项生效
  - name: claude-sonnet-4-20250514
    api: Anthropic          # 必填 — 不再按名字/URL 猜测
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    context_window: 200000
  - name: deepseek-flash    # 内置 preset:自动补齐 base_url / context / thinking
    api_key: sk-...
  - name: gemini-2.5-flash  # 内置 preset(api: Gemini)
    api_key: ...
    think_level: high       # 可选:off | minimal | low | medium | high | …

skill_path: ~/.phi/skills # SKILL.md 文件的加载目录;`~/…` 会被展开

agents:
  enabled: true           # 默认;设为 false 可禁用 agent_* 子代理工具

内置 preset 与思考参数上线格式见 doc/models.md。

环境变量覆盖:

变量 覆盖项
PHI_API_KEY models[].api_key(默认模型)
PHI_MODEL 未配置模型时使用的降级模型名
PHI_BASE_URL models[].base_url(默认模型)
PHI_SKILL_PATH skill_path
PHI_THINK_LEVEL models[].think_level(默认模型;off 关闭思考)
PHI_PROMPT_HISTORY 输入框历史唤起(设为 on 开启;默认关闭,开启后会在项目会话目录写入 prompts.json)

提供商路由看显式 api 字段(OpenAI / Anthropic / Gemini)。详见 支持的模型。

工作区布局

~/.phi/
├── config.yaml   # 全局配置
├── bin/          # 下载的搜索工具(fd、ripgrep)
├── skills/       # SKILL.md 技能目录
├── extensions/   # PXB 二进制 + phi.yaml
├── jobs/         # 子代理任务产物(meta、logs、result.md)
└── session/      # 持久化会话,每个工作目录一个目录
    └── <encoded-cwd>/

交互模式

phi 启动 TUI:上方是对话记录,底部是编辑器,底部状态栏显示 当前活动。有新版发布时,状态栏会提示类似 0.2.0 available · phi update。

助手输出按 Markdown(CommonMark/GFM)渲染:标题、强调、删除线、链接、引用、 列表、任务复选框和表格都会按当前主题着色;围栏代码块上方有淡色语言标注,并按语言高亮。 结构标记(#、`、*)会被去除。

编辑器支持:

  • @ —— 模糊文件选择器(输入 @ 后开始输入路径)
  • / —— 斜杠命令选择器(/sessions、/branch、/skill、/new、/fork、/diff、/code)
  • ? —— 快捷键帮助选择器(列出 /、!、!!、@ 和按键绑定;Esc 关闭)
  • !command —— 在本地运行 shell 命令,并把输出流式写入对话记录 (见 命令)
  • Ctrl+K —— 命令面板:设置 → 模型 / 主题 / 代理(含各角色模型)/ 思考 / 调试,以及扩展管理(extensions)。用 /skill 选择技能。

键盘快捷键

按键 作用
Ctrl+C 退出 phi
Esc 取消正在运行的代理 / 关闭选择器
Ctrl+K 开关命令面板
Ctrl+A 光标跳到行首
Ctrl+E 光标跳到行尾
Ctrl+U 清空输入框(含图片和技能)
Ctrl+Shift+C 复制选中的对话文本

主题:Dark(默认)、Darcula、Pink 和 Terminal,可在面板的 设置 → 主题中切换。

Diff 审阅

/diff 是 TUI 里的全屏 git 审阅——看改动、写行级批注,再把批注交给代理, 全程不用离开终端。

命令 打开内容
/diff 工作区(git diff)
/diff staged 暂存区
/diff HEAD 最近一次提交(git show)

斜杠选择器里回车会把 /diff 连同一个空格填进输入框;再提交才打开。 审阅层内:j/k 移动,s 左右对照,i 添加/编辑批注,x 删除,a 发给代理, ? 帮助,q / Esc 关闭。批注只存在内存里,切 diff 就丢,不会落盘。

代码查看器

/code <path>[:line] 打开全屏源码查看器:语法高亮、支持 CJK 宽度的光标 (j/k、h/l、gg/G),v 选中行后按 a,把选中的行作为 path:12-18 引用交给聊天输入框,模型直接可读。查看器自己读文件;敏感路径 (~/.ssh、.env 等)、二进制文件和超过 8 MiB 的文件会拒绝并以 toast 提示。

Esc 关闭。阅读时状态栏显示路径、光标和行数;v 激活时显示已选中行数。

切换分支

/branch 打开当前目录的分支选择器,只有两列:分支名和它最近的一次提交。 ● 标记 HEAD 所在的分支。顺序是:你在哪、你从哪来(git reflog)、其余本地 分支、远程跟踪分支。

回车对选中行执行 git switch(不占用 UI 线程,慢仓库不会卡住输入框)。 选中远程行等同于检出跟踪它的本地分支——也就是 git switch feat 对 origin/feat 做的事。

Ctrl+X 确认删除选中的本地分支。确认后直接删除,不检查是否已合并, 删除成功后自动刷新列表。当前分支和被其他 worktree 使用的分支不能删除。

/branch <name> 跳过选择器:切到该分支;如果没有任何分支叫这个名字,就从 HEAD 新建一个。敲名字本身就是「新建分支」的全部流程,比填表单快。

未提交的改动不会被丢弃:git 会拒绝,原文提示以 toast 显示。代理正在回复或执行 命令时禁止切换;merge、rebase、cherry-pick、revert、bisect 未完成时同样禁止。

命令

命令 说明
phi 启动交互式 TUI
phi run -p "…" 以无头模式运行一个代理循环(见下文)
phi update 下载并安装最新的 GitHub 发布版本
phi update --check 只查询最新版本,不安装
phi sessions 列出当前目录的持久化会话
phi sessions fork <id> 在当前点复制会话并打印新 id
phi sessions remove <id> 删除当前目录的持久化会话(别名 rm;唯一 id 前缀即可)
/sessions 列出当前目录的会话(TUI 内)
/branch 切换工作分支 — 见 切换分支
/new 开启一个全新的空会话(TUI 内)
/fork 在当前点复制本会话为新会话并切换过去(TUI 内)
/diff 全屏 git 审阅 — 见 Diff 审阅
/code 全屏源码查看器 — 见 代码查看器
!command 在本地运行 shell 命令,把输出流式写入对话记录;Esc 取消

在 TUI 中,!command 通过 bash -c 在本地运行——在代理循环之外。它不计入 代理忙碌状态,运行中的命令可以用 Esc 取消,且不影响正在进行的代理回合。

会话

会话会按工作目录自动持久化到 ~/.phi/session/<encoded-cwd>/,以 JSONL 轨迹 记录。

  • phi sessions —— 列出当前目录的会话 id、修改时间和预览
  • TUI 内 /sessions —— 同上,在应用内查看
  • /new —— 开启全新会话(新 id、空对话记录)
  • /fork —— 在当前点复制本会话(新 id、相同对话记录)并切换过去;源会话 保持原样,仍可从列表恢复
  • phi sessions fork <id> —— 在当前点复制会话并打印新 id,用 phi run --session <新 id> 继续副本
  • phi run --session <id> / phi run --continue-last —— 无头模式恢复会话

无头模式

phi run -p "fix the failing test in internal/tools"

不启动 TUI,运行一个代理循环。人类可读的日志输出到 stderr;加上 --jsonl 后,机器可读事件输出到 stdout,每行一个 JSON 对象。

参数:

参数 说明
-p, --prompt STRING 要运行的提示词(必填)
--jsonl 向 stdout 输出 JSONL 事件
--timeout DURATION 限制 Agent 运行总时长(例如 10m,默认不限制)
--session ID 按 id 或唯一前缀恢复已持久化的会话
--continue-last 恢复当前目录最新的持久化会话
--session-dir DIR 覆盖会话存储目录
--tools LIST 仅启用逗号分隔的指定内置工具
--model NAME 本次运行使用已配置的命名模型

--tools 接受 read,ls,grep 之类的内置工具名称。已配置的 MCP 和 agent 工具仍会照常追加;该参数只限制内置工具集。

phi run 的模型优先级为 --model > 配置模型 > PHI_MODEL。--model 指定的名称不存在时会在循环开始前失败,退出码为 3。

退出码:0 成功 · 1 运行时/LLM 错误 · 3 配置/用法错误。

Skills(技能)

技能是包含 SKILL.md 文件的目录,文件带 YAML frontmatter 和 Markdown 正文。 它们从 ~/.phi/skills/(或 skill_path / PHI_SKILL_PATH)加载,注入到代理 上下文中,让你能给模型提供可复用的流程:

同时也会读取 Agent Skills 的 ~/.agents/skills/ 与 .agents/skills/,因此给 其他 agent 装好的技能包无需配置即可使用。项目级 .agents/skills/ 会从工作目录 逐级向上查找,遇到 git 仓库根目录即停止。搜索顺序为 skill_path → ~/.agents/skills → 各级项目目录,同名技能由靠前的目录胜出。skill_path 或 PHI_SKILL_PATH 里的前导 ~ 会展开为 home 目录。

**安全:**技能文件属于工作区内容,不是可信输入——项目里的 .agents/skills/ 会被直接加载、无需确认。像审查 AGENTS.md 一样先审查技能文件再信任一个 checkout。

---
name: My Skill
 description: What this skill does
license: MIT
compatibility: claude, openai
disable-model-invocation: false
---
Instructions the agent should follow when this skill is relevant.

disable-model-invocation: true 让技能不出现在 system prompt 的技能目录里, 适合那些只想在需要时手动点名的技能。它仍留在技能面板里,从面板选中后照常生效。 只有大小写不敏感的 true 判真,其它写法一律为 false。这只是目录过滤,不是 权限控制:模型仍能用 ls / find 找到文件。

在 TUI 中,可以从面板添加技能(技能 → 列表),然后在勾选所需技能后发送 消息。

Extensions(扩展)

扩展是讲 PXB 二进制协议的原生进程(作者 SDK:Go github.com/pulseaiclub/phi/ext/go/phi 和 Rust ext/rust phi-ext):订阅工具/会话事件、注册 LLM 工具、添加斜杠命令。

go get github.com/pulseaiclub/phi/ext/go@v0.25.6
package main

import (
	"github.com/pulseaiclub/phi/ext/go"
	"github.com/pulseaiclub/phi/ext/go/phi"
)

func main() {
	m := phi.New("hello", "0.1.0")
	m.OnToolCall(func(ev ext.ToolCallEvent) *ext.ToolCallResult {
		// return &ext.ToolCallResult{Block: true, Reason: "..."}
		return nil
	})
	_ = m.Run()
}

放到 ~/.phi/extensions/<name>/,附带 phi.yaml 指向二进制。 TUI:Ctrl+K → extensions。禁用:PHI_EXTENSIONS=off。完整指南见 doc/extensions.md。

Codec 吞吐(Apple Silicon,release,单线程):

实现 Hello encode+decode Frame write+read(内存) Allocs
Rust PXB (phi-ext) ~0.12 µs ~0.06 µs —
Go PXB (ext/go/pxb) ~0.11 µs ~0.05 µs 3 / op
Go JSON lines ~1.2 µs — 15 / op

相对 JSON lines 约 10× 来自协议本身(定长头 + tagged fields),不是语言——同套 codec 工作下 Rust / Go 在噪声内。扩展真实延迟仍由进程 spawn 和 pipe RTT 主导。 复测:在 ext/rust 里跑 cargo run --release --example bench。

MCP

配 100 个 MCP 服务器,开场 schema 仍接近 0 token。

多数 MCP Host 会在你提问前把全部 tools/list schema 塞进上下文——光浏览器类 工具就能烧掉 5 万+ token。phi 不这么干。

MCP 是挂在常规工具上的 URL 命名空间;系统提示里会列出已配置的 server 名(不含 schema):

动作 调用
列某个 server 上的工具 ls mcp://<server>/tools/
看单个工具的精简参数说明 read mcp://<server>/tools/<tool>
执行工具 write mcp://<server>/tools/<tool>,content 为 JSON 参数

流程:从提示词里的 server 名出发 → ls → read → write。子进程懒启动。 浏览列出可用工具;执行指定的 MCP 工具并将结果返回给模型。

phi mcp add browsermcp -- npx @browsermcp/mcp@latest
phi mcp doctor
# 在 TUI 里直接让模型用已配置的 server(不必先猜有没有 MCP)

配置:~/.phi/mcp.json(项目 <cwd>/.phi/mcp.json 可覆盖同名)。 PHI_MCP=off 关闭。首版支持 stdio 与 HTTP。

完整文档:doc/mcp.md。

子代理

子代理工具(agent_spawn、agent_wait 等)默认开启。如果想保持工具精简,可在 ~/.phi/config.yaml 中禁用:

agents:
  enabled: false

也可以在当前会话中通过面板切换:设置 → 代理。禁用后这些工具不会注册,模型无法派发任务给子代理。

子代理本身使用一种 role(explore 默认 | review | worker):

Role 工具 用途
explore 无 write/edit;bash 除硬拒绝外可用 多跳侦察 / 梳理结构
review 与 explore 相同 差异 / 检查;只出报告
worker 除嵌套外全部工具;bash 除硬拒绝外可用 范围明确的独立改动

默认保持 explore(不可编辑)。任务是在隔离上下文里落地一块改动时,再用 worker。

工具

模型可调用的内置工具(见 internal/tools/):

工具 用途
bash 在工作目录运行 shell 命令
read 读取文件
write 写入文件
edit 精准编辑文件的某一段
grep 跨文件正则搜索
find 文件模式匹配(fd)
ls 目录列表
agent_spawn 启动一个隔离的子代理任务(异步)
agent_wait 等待任务;只返回简短总结

子代理的完整记录存放在 ~/.phi/jobs/<id>/,子代理的上下文不会注入父代理上下文——只有 wait/task 的总结会注入。

快速搜索工具(fd、ripgrep)在首次启动缺失时,会下载到 ~/.phi/bin。

源码结构图见 项目结构。

开发环境搭建、代码风格与提交规范见 CONTRIBUTING.md。