# pi-agent-java

**Repository Path**: harvey_danny/pi-agent-java

## Basic Information

- **Project Name**: pi-agent-java
- **Description**: pi-agent的java版本改造，并做了完整测试
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# pi-java

[pi](https://github.com/earendil-works/pi-mono) 编码代理核心子集的 Java 移植版。Java 21 + Maven 多模块,仅依赖 Jackson,HTTP/SSE 全部使用 JDK 内置 `java.net.http`。

原仓库约 12 万行 TypeScript(10 个包)。本工程采用分阶段移植策略,当前已完成**核心可运行链路**(统一流式模型 API → agent 循环(工具调用)→ 无头编码代理 CLI)与 **P5 周边包**(protocol、client/server、telemetry、session-backends、evals);TUI 仍在进行中,完整计划见 [PORTING-PLAN.md](PORTING-PLAN.md)。

## 模块与原包对应关系

| 模块 | 对应原包 | 移植内容 |
|---|---|---|
| `pi-ai` | `@earendil-works/pi-ai` | 消息/内容块类型、事件流协议、SSE 解码、Anthropic Messages 与 OpenAI Chat Completions 流式适配器、模型注册表、成本计算、token 估算、重试、工具参数校验、partial-JSON 解析 |
| `pi-agent` | `@earendil-works/pi-agent-core` | AgentLoop(顺序/并行工具执行、截断工具调用失败、before/after 钩子、shouldStopAfterTurn)、Agent 门面、AgentTool/AgentEvent |
| `pi-coding-agent` | `@earendil-works/pi-coding-agent` | 核心工具(read/write/edit/bash/glob/grep/ls)、系统提示词(含 AGENTS.md 项目上下文)、`-p` 无头 CLI、交互行模式 |
| `pi-protocol` | `@earendil-works/pi-protocol` | RPC 消息模型、`ProtocolValidator`、CBOR/JSON 编解码 |
| `pi-client` | `@earendil-works/pi-client` | `PiClient`/`Connection`/`Transport`、阻塞 HTTP 传输与错误类型 |
| `pi-server` | `@earendil-works/pi-server` | `PiServer`/`LiveSessions`/`SnapshotPublisher`/`ServerApi`,RPC 会话服务 |
| `pi-telemetry` | `@earendil-works/pi-telemetry` | `Telemetry` span 上下文、`NoopTelemetry`、`InMemoryTelemetryContext` |
| `pi-session-backends` | `@earendil-works/pi-session-backends` | SQLite 会话后端 |
| `pi-evals` | `@earendil-works/pi-evals` | `EvalSummaries`/`EvalArtifacts` 报告与产物工具 |
| `pi-plugins` | `@earendil-works/pi-plugins` | ServiceLoader 插件聚合(web-access、subagents、trace-viewer、web-ui) |

## 构建与运行

```bash
mvn package                     # 构建 + 测试
mvn -pl pi-coding-agent -am package -DskipTests   # 仅打包

java -jar pi-coding-agent/target/pi-coding-agent-0.1.0-SNAPSHOT.jar --list-models
java -jar pi-coding-agent/target/pi-coding-agent-0.1.0-SNAPSHOT.jar -p "解释这个目录" --model anthropic/claude-sonnet-4-5
```

环境变量:`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` 选择 provider;`PI_API_KEY` 兜底;
`PI_BASE_URL` + `PI_MODEL_ID`(+`PI_API_KEY`)接入任意 OpenAI 兼容端点(vLLM、OpenRouter、GLM 等)。

## 架构说明(TS → Java 映射)

- **可辨识联合 → sealed interface**:`Message`、`ContentPart`、`AssistantMessageEvent`、`AgentEvent` 均为 sealed 层级 + record,保持原 discriminated union 语义与 switch 穷尽性检查。
- **流式事件协议**:`EventStream<T, R>` 移植自原 `EventStream`(push/end/result,阻塞迭代);`AssistantMessageEventStream` 终止于 `done`/`error` 事件并携带最终 `AssistantMessage`。
- **部分消息可变性**:与原实现一致,适配器在流式过程中原地更新 `AssistantMessage`/`ToolCall`,向消费者发送快照拷贝。
- **wire 语义忠实移植**:Anthropic 停止原因映射(end_turn→stop、tool_use→toolUse、refusal→error 等)、连续 toolResult 合并为单条 user 消息、thinking 无签名时降级为 text 回放、cache_control 标记、1h 缓存写入 2 倍计费、`stream_options.include_usage`、截断输出(length)时整批工具调用判失败等行为均与原版一致。
- **partial-json**:以递归下降容忍解析器重写(保留完整前缀与部分叶子值),替代原 npm `partial-json` 依赖。

## 测试

`mvn test` 共 344 个用例:SSE 解码(分块/CRLF/多行 data)、partial-JSON、参数校验、成本分层计费、Anthropic/OpenAI 适配器(本地 HttpServer 模拟 SSE,覆盖请求体构造与事件流转)、保真回归(end 契约、错误编码进流、adaptive/budget thinking、cache 标记三处落点、上下文钳制、代理项清洗、usage 字段回退)、AgentLoop(工具循环/错误终止/截断失败/钩子拦截/steering/followUp/prepareNextTurn)、Agent 行为(忙时拒绝/steer 注入/跨轮转录)、七个文件工具(CRLF/BOM/旧参数/图片/截断)、端到端集成(模拟端点→工具调用→结果回传→最终回答)、protocol(CBOR/JSON 编解码与校验)、telemetry(span 生命周期)、session-backends(SQLite)、evals(汇总与产物)、server/client 集成。

## 未移植部分与推进计划

完整差距清单与分阶段计划见 **[PORTING-PLAN.md](PORTING-PLAN.md)**(P1 harness 会话层 → P2 协议广度 → P3 会话/扩展/MCP → P4 TUI → P5 周边包),已完成的 P0(核心链路 + 保真修复)在文档中逐项勾选。

## License

同原仓库 LICENSE。