# PiAgentBridge

**Repository Path**: yangshunling/PiAgentBridge

## Basic Information

- **Project Name**: PiAgentBridge
- **Description**: 关于pi agent的java调用桥接 sdk
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://www.oschina.net/p/piagentbridge
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2021-07-05
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiAgentBridge

通过 Java 调用本地已安装的 pi coding agent（`pi` CLI）的 Spring Boot 桥接服务。

支持两种调用方式：

| 方式 | 对应 CLI | 说明 |
| --- | --- | --- |
| 阻塞式（Blocking） | `pi -p` | 进程结束后一次性返回文本结果 |
| 流式（Streaming） | `pi --mode json -p` | 逐行输出 NDJSON 事件，通过 SSE 推送给客户端 |

## 特性

- 分层架构：`web`（Controller/DTO）→ `application`（Service）→ `core`（领域模型/端口）→ `infra`（进程执行/解析）
- 进程管理：超时控制、空闲/总时长看门狗、客户端断开自动取消、后台线程持续消费 stdout/stderr 避免管道阻塞
- 可执行文件解析：自动识别 npm 全局安装的 `.cmd/.bat`、`.js`（node 运行）、`.ps1`（powershell 运行）、普通二进制
- 参数可配置：provider、model、会话、工具开关、环境变量、工作目录均可通过配置或请求覆盖
- 统一异常处理与结构化错误响应

## 快速开始

```bash
mvn clean package
java -jar target/pi-agent-bridge-1.0.0.jar
```

默认端口 `8080`，健康检查：`http://localhost:8080/actuator/health`。

## 接口

- `POST /api/pi/run` 阻塞式调用（JSON 请求体）
- `POST /api/pi/stream` 流式调用（JSON 请求体，SSE）
- `GET /api/pi/stream?prompt=xxx` 流式调用（Query 参数，SSE）

详见 [使用手册](./使用手册.md)。

## 配置

主要配置项（前缀 `pi-agent`）见 [部署手册](./部署手册.md) 与 `src/main/resources/application.yml`。

## 目录结构

```
src/main/java/com/piagent/bridge
├── PiAgentBridgeApplication.java     # 启动类
├── config                            # 配置项与线程池
├── core/model                        # 领域模型（请求/响应/事件）
├── core/exception                    # 业务异常
├── core/port                         # 应用端口（服务门面、事件接收器、取消句柄）
├── application                       # 服务实现
├── infra/process                     # 命令解析、进程启动、阻塞/流式执行器
├── infra/parser                      # NDJSON 事件解析
└── web                               # Controller、DTO、全局异常处理
```

## 技术栈

- Java 17 + Spring Boot 3.3.x + Maven
- spring-boot-starter-web（REST + SSE）
- spring-boot-starter-actuator（健康检查）
- Lombok