测试中 开源 · MIT 与 Apache-2.0
一个可审计的编程智能体。
zycode 的智能体循环小而清晰，并有书面契约。每一轮对话、每一次工具调用，都是可以记录和测试的事件。你可以在终端里用它，也可以在任何支持 ACP 的编辑器里用它。
pip install pi-agent-cli-lc 目前项目以 zypi（终端界面）和 pi-agent-cli-lc（智能体）的名称发布。
› 结账测试在舍入处失败。找出原因并修复。
read tests/test_checkout.py 只读 · 不询问
grep "round(" src/ 只读 · 不询问
read src/checkout/totals.py 只读 · 不询问
总价用的是 float。round(2.675, 2) 的结果是 2.67，因为 2.675 没有精确的 float 表示。改用 Decimal 和 ROUND_HALF_UP。
edit src/checkout/totals.py 已询问 · 你已允许
bash pytest tests/test_checkout.py 已询问 · 你已允许
完成。结账测试已通过。
›
01 理念
为被检查而造，而不是要你盲信。
编程智能体会改你的文件、跑你的命令。zycode 让每一步都看得见、有界限、能测试。
-
书面的事件契约
每次运行都按相同的顺序发出相同的事件。测试把这个顺序固定下来。你可以记录这些事件，并在其上构建。
-
一个协议，任何客户端
智能体通过 stdio 使用 Agent Client Protocol（ACP），没有厂商私有调用。终端界面、Zed 和其他 ACP 客户端启动的是同一个进程。
-
界面里没有模型客户端
zypi没有模型客户端、工具执行器和 MCP 客户端，这些工作都由 Python 智能体完成。对一次真实对话轮次的审计，没有发现zypi连接机器以外的地址。 -
按声明授权
在
ask模式下，除非工具声明自己无害，否则智能体在调用前都会询问。没有任何声明的工具也会被询问。 -
先信任项目
项目可以自带扩展、工作流、提示词和技能。只有你信任该项目之后，智能体才会加载它们。这些文件一旦变化，智能体会再次询问。
-
任何模型，同一个循环
LangChain 只是通向模型的边界。循环、工具和事件都在我们自己的代码里。可以用 OpenAI、Anthropic、DeepSeek，或任何兼容 OpenAI 的网关。
02 契约
每次运行，同样的事件。
核心循环忠实移植自 pi 项目的智能体循环。它的事件协议就是契约，由测试强制执行。
一轮带工具调用的对话
-
agent_start运行开始。 -
turn_start一轮开始。 -
message_start · message_end用户消息。 -
message_start助手消息开始。 -
message_update重复出现。携带文本、思考和工具调用的增量。 -
message_end助手消息结束。 -
tool_execution_start每次工具调用一个事件。 -
tool_execution_end按完成顺序触发。 -
message_start · message_endtoolResult消息。按来源顺序保存。 -
turn_end这一轮结束。循环可以开始下一轮。 -
agent_end运行结束。
测试强制执行的四条规则
-
并行工具
tool_execution_end按完成顺序触发。toolResult消息按来源顺序保存。 -
终止
只有当所有已完成的工具结果都设置了
terminate=True时，循环才会跳过下一次模型调用。 -
不抛出异常
StreamFn（调用模型的流式函数）从不抛出异常。失败会变成error事件，stop_reason为error或aborted。 -
用量
令牌用量取各字段已报告快照的最大值，而不是求和。
03 架构
部件小，边界清楚。
每一层只做一件事。你可以替换界面、模型提供方或扩展，而不用改循环。
Python 包使用 MIT 许可。zypi 是 grok-build 的分支，已删除所有 x.ai 厂商扩展，保持 Apache-2.0 许可。
zypi
终端界面。负责绘制屏幕，并使用 ACP 通信。
Rust · Apache-2.0Zed 与其他 ACP 客户端
编辑器。启动的是同一个智能体进程。
pi_agent_cli
ACP 智能体。系统提示词引擎、权限、项目信任和无界面模式。
Python · MITpi_agent_harness
会话、压缩、技能、提示词模板和本地执行环境。
Python · MITpi_agent_core
智能体循环、事件协议、工具执行和编程工具。
Python · MITLangChain 流式适配层
OpenAI、Anthropic、DeepSeek，或任何兼容 OpenAI 的网关。
04 功能
今天就能用到的。
这份清单只写代码现在能做的事，不写计划。
-
七个编程工具
read、edit、write、bash、grep、find和ls。智能体截断输出时，会有提示告诉模型如何读取其余部分。 -
可以恢复的会话
在界面里用
/new和/resume，或在命令行用zypi --continue。压缩功能让长会话保持在上下文窗口之内。 -
无界面模式
在脚本和 CI 里运行
python -m pi_agent_cli -p "提示词"。模型调用失败时，它向 stderr 输出错误，并以状态码 1 退出。 -
技能与上下文文件
智能体会读取
AGENTS.md和CLAUDE.md上下文文件，并把你的技能列在系统提示词里。 -
用 Python 写扩展
联网搜索与抓取、目标规划、工作流和 MCP 都是独立的包。你也可以用扩展 API 自己写。
-
子进程里的工作流
工作流脚本在带操作系统限制的子进程里运行。边界是这些限制，审计钩子只是减速带。
-
可以设置的限制
可以设置
max_turns、每个工具的超时，以及首个令牌之前的重试。每次模型调用前后都会运行钩子。 -
思考与成本
推理参数会映射到各个提供方。思考内容以事件形式流出。智能体会统计每次运行的令牌用量和成本。
05 安装
装好，然后选一个模型。
先安装 Python 智能体，再添加终端界面，或连接你的编辑器。
终端界面（zypi）
# 1. 安装智能体，然后选择提供方、模型和密钥
pip install pi-agent-cli-lc
python -m pi_agent_cli --setup
# 2. 安装终端界面（Linux x86_64）
curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zypi-linux-x86_64
chmod +x zypi && sudo mv zypi /usr/local/bin/
# 3. 在你的项目目录里启动
zypi- Linux 二进制需要 glibc 2.39 或更高版本（Ubuntu 24.04 或更新）。
- 在 Apple 芯片的 macOS 上，使用文件
zypi-macos-arm64。它由 CI 构建，还没有人实际运行过，也没有签名。 - 在 Windows 上，请从源码构建
zypi并在 WSL2 中运行。Python 智能体可以直接在 Windows 上运行。
Zed（自定义智能体）
{
"agent_servers": {
"pi-python": {
"type": "custom",
"command": "uvx",
"args": [
"--from", "pi-agent-cli-lc",
"--with", "pi-agent-core-lc[deepseek]",
"pi-agent-cli"
],
"env": {}
}
}
}- 先安装 uv。智能体还不在 Zed 的 ACP 注册表里，所以要作为自定义智能体添加。
- 先在终端里运行一次
--setup，或把模型写进~/.pi-python/agent.toml。 - 使用 OpenAI 或 Anthropic 时，把
[deepseek]换成[openai]或[anthropic]。
无界面（脚本与 CI）
pip install pi-agent-cli-lc
# 一条提示词，没有界面
python -m pi_agent_cli -p "Explain this codebase" --cwd /path/to/project
# 不需要模型和密钥：脚本化的测试替身
PI_USE_MOCK=1 python -m pi_agent_cli -p "hello" --cwd .- 模型调用失败时，会向 stderr 输出
error: <原因>，并以状态码 1 退出。 - 无界面运行从不提问。它会使用你之前对项目信任问题给出的答案。
Python 库
import asyncio
from pi_agent_core import Agent, Model
from pi_agent_core.adapters import langchain_stream
async def main():
agent = Agent(
initial_state={
"system_prompt": "You are a helpful assistant.",
"model": Model(provider="openai", model_id="gpt-4o-mini"),
},
stream_fn=langchain_stream,
)
agent.subscribe(lambda event, signal: print(event.type))
await agent.prompt("Hello!")
await agent.wait_for_idle()
asyncio.run(main())- 用
pip install "pi-agent-core-lc[openai]"安装。其他提供方使用[anthropic]或[deepseek]。 - 整个测试套件不需要 API 密钥，因为它使用模拟的流。
06 状态
如实的状态。
zycode 处于测试阶段。下表说明哪些部分稳定，哪些还不稳定。
下一步：为 macOS x86_64 和 Windows 提供预编译的 zypi，并支持自动更新。
07 证据
我们公开测试方法，也公开出过的错。
我们运行一个 30 题的基准：21 道来自 Terminal-Bench，9 道来自 DeepSWE。报告列出了我们在自己的方法里发现的缺陷。
24 / 30
题通过
每题取最新的有效运行
如何理解这个数字
- 每题只跑一次。同一道题再跑一次，结果可能差别很大。
- DeepSWE 的题用了两种轮次上限：60 轮和 100 轮。
- 模型：DeepSeek-V4-Flash。DeepSWE 的重跑通过网关别名调用模型，我们无法核实别名背后的模型。
- 我们发现了两处会让智能体看到标准答案的泄露。第一处已修复，第二处作为已知问题公布。受影响的数字已更正。
- 这不是排行榜成绩，也不是与其他智能体的同口径对比。
08 开源
可读， 可运行， 可修改。
Python 包使用 MIT 许可。zypi 是 xai-org/grok-build 的分支，保持 Apache-2.0 许可。
zycode 基于 pi 项目的 pi-agent-core 移植而来。这是一个非官方项目，与 pi 项目及其维护者没有隶属关系，也没有得到他们的认可或维护。
