# pi-agent

**Repository Path**: small-leaf999/open-source-pi-agent

## Basic Information

- **Project Name**: pi-agent
- **Description**: 开源的AI AGENT
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pi-agent

> 通用个人智能体：基于 `@earendil-works/pi-coding-agent` 宿主（0.84.1，锁版），
> `.pi/extensions/` 共 **276 个扩展目录 / 2699 个工具**（settings 启用集 171 个），
> 覆盖视觉操作、联网搜索、记忆/人设、工作流调度、音视频、桌面/手机自动化、知识库、办公与生活工具等。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%E2%89%A522-blue)](https://nodejs.org)
[![Extensions](https://img.shields.io/badge/extensions-276-brightgreen)](.pi/extensions)
[![Tools](https://img.shields.io/badge/tools-2699-brightgreen)](docs/tools-catalog.md)
[![Tests](https://img.shields.io/badge/tests-987%20pass-green)](tests/)

## 特性

- **视觉操作**（`uitars` / `desktop` / `phone`）：屏幕截图 + GUI 自动化，跨 Windows / macOS / Linux / Android / iOS
- **联网搜索 & 网页抓取**（`net` / `web-tools` / `playwright` / `edge-browser`）：网页搜索 / 学术 / 论文 / 知识图谱
- **记忆系统**（`mem`）：本地 SQLite（`.agent-data/mem.db`）+ 可选 bge-m3 向量检索；开工自动浮现 Top-5 相关记忆，收会话自动沉淀
- **人设块**（`persona`）：可编辑的 markdown + 用户画像（`persona_profile`），每次推理前注入系统提示
- **沙箱隔离**（`isolation`）：Windows Sandbox / Hyper-V / RDP 三后端；网络 ACL + 应急停止
- **视频/音频/图像**（`video-*` / `audio-*` / `image-*`）：ffmpeg 封装、字幕烧录、TTS/ASR、AI 生图
- **工作流 & 调度**（`workflow` / `schedule`）：任务模板 + cron / webhook 触发
- **任务规划**（`plan-tools`）：纯本地、零 LLM、零超时的计划/步骤/质量门
- **知识库 / RAG**（`kb` / `pdf-rag`）：本地向量 + 全文检索
- **桌面/手机速查**（`pc-tools` / `phone-tools`）：Windows 优化 / BIOS / 装机 / 故障排查 / 手机辅助
- **多 Provider**（`codex-parity`）：MiniMax / DeepSeek / Anthropic / OpenAI / 自定义
- **隐私优先**：记忆、persona、运行时数据默认本地存储，不上传任何用户数据

## 快速开始

### 环境要求

| 必需 | 可选（功能） |
|---|---|
| Node.js ≥ 22 | Python ≥ 3.11（仅 bge-m3 向量检索要） |
| Git | ffmpeg（仅视频/音频工具要） |
|  | WSL（Windows 上 `bash` 工具要） |

### 最小依赖路径

核心功能（聊天、工具调用、记忆 hash 模式、扩展框架）**只需要 Node.js**：

- **没 Python** → `mem_search` 自动用 hash embedding 兜底（精度低但能用）
- **没 ffmpeg** → 视频/音频工具会 fail，其余 2600+ 工具正常用
- **要 bge-m3** → 跑 `./scripts/install-bge-deps.ps1`（~600MB 模型 + Python 依赖）

### 6 步跑起来（Windows）

```bash
# 1. clone
git clone git@gitee.com:small-leaf999/open-source-pi-agent.git
cd open-source-pi-agent

# 2. 装依赖
npm install

# 3. 配置文件
cp .mcp.example.json .mcp.json
cp .pi/extensions/persona/persona.example.md .pi/extensions/persona/persona.md
# 编辑 .mcp.json：把 ${WORKSPACE_ROOT} 改成本机项目绝对路径

# 4. 项目根目录建 .env（启动脚本自动加载），最少一行：
#    MINIMAX_CN_API_KEY=...
# 常用可选键：VOLCENGINE_API_KEY（视觉工具）、DEEPSEEK_API_KEY、
#             GITEE_ACCESS_TOKEN、ZHIPU_API_KEY

# 5. 验证
npm run smoke       # 扩展加载 + 主工具最小执行（预期：154 用例全过）
npm run test:all    # 单元测试（988 用例）
npm run typecheck   # TS 类型检查（固定 typescript@5.5.4）

# 6. 启动
.\start-pi-agent.bat        # 或 .\start-pi-agent.ps1 / .\scripts\start-pi-cn.ps1
```

`start-pi-agent.bat` 会自动做这些事：加载 `.env`、检查/安装 Python 依赖（pyautogui/Pillow/uv）、
拉起 LightRAG（`:9621`）与飞书桥（单实例保护）、模型沿用上次 `/model` 切换（找不到才回退默认）。
用 `PI_SKIP_LIGHTRAG=1` / `PI_SKIP_FEISHU_BRIDGE=1` 可跳过自启。

### 默认模型

- 默认 `deepseek` / `deepseek-flash`（见 `.pi/settings.json` 与 `.agent-data/settings.json`，thinking=high）
- 启动脚本读取 `.agent-data` 记忆的最近一次 `/model` 切换，重启不丢
- 根目录 `models.json` 注册 `deepseek-flash`（默认）与 `deepseek-v4-flash-vision-exp`（DeepSeek，100 万上下文，支持图像输入），启动时自动复制进 `.agent-data`
- 视觉工具走豆包（需 `VOLCENGINE_API_KEY`）

## 项目结构

```
pi-agent/
├── .pi/
│   ├── extensions/         # 276 个扩展目录（.pi/settings.json 接线 171 个为启用集）
│   ├── skills/             # 内置技能（SKILL.md）
│   ├── tests/              # extension-smoke.ts（mock 全量加载 + 154 smoke 用例）
│   ├── config/             # tool-merges.json（隐藏重复/低价值工具）
│   └── audit/              # 历史审计/勘察文档（日期快照，非现状）
├── tests/                  # 单元测试（node:test，988 用例）
├── src/                    # 独立后端源码（db/http/net/security/taskqueue/test-runner...）
├── scripts/                # 启动脚本 / 维护脚本 / 桥接服务
├── docs/                   # 架构 / 工具目录 / 集成指南
├── pi-side/                # 移动端桥接（mobile-bridge）
├── backend-demo/           # 后端 auth demo
├── edge-browser/           # Edge 浏览器扩展 + 本地 host 桥
├── deploy/                 # 云端/远程部署脚本
├── pi-website/             # 文档站
└── tools/                  # 可选参考项目子模块（.gitmodules：LightRAG / gpt-researcher / autogen，默认未初始化）
```

## 配置

### 环境变量

| 变量 | 说明 | 必需 |
|---|---|---|
| `MINIMAX_CN_API_KEY` | 默认文本模型 MiniMax API Key | ✅ |
| `VOLCENGINE_API_KEY` | 豆包视觉（uitars/desktop 视觉工具依赖） | ⬜ |
| `DEEPSEEK_API_KEY` | DeepSeek 备选文本模型 | ⬜ |
| `GITEE_ACCESS_TOKEN` | Gitee MCP 个人令牌 | ⬜ |
| `ZHIPU_API_KEY` | 智谱（部分记忆/嵌入功能） | ⬜ |
| `FFMPEG_PATH` / `FFPROBE_PATH` | 自定义 ffmpeg / ffprobe 路径（默认从 `PATH` 找） | ⬜ |
| `PI_PYTHON` | 自定义 Python 可执行文件路径 | ⬜ |
| `PI_EXTRA_PATH` | 注入额外 PATH（ffmpeg / Python Scripts） | ⬜ |
| `PI_PERSONA_FILE` | 自定义 persona 文件路径（默认 `.pi/extensions/persona/persona.md`） | ⬜ |
| `PI_PERSONA_ENABLED=0` | 关闭 persona 注入 | ⬜ |
| `PI_SKIP_LIGHTRAG=1` | 启动时跳过 LightRAG 自启 | ⬜ |
| `PI_SKIP_FEISHU_BRIDGE=1` | 启动时跳过飞书桥自启 | ⬜ |

### MCP 服务

复制 `.mcp.example.json` 为 `.mcp.json`，把 `${WORKSPACE_ROOT}` 替换为本机绝对路径。详见 `.mcp.example.json` 内的 `_env_required` 段。

### `.gitignore` 兜底

以下路径不会被 git 追踪：

- `.pi/extensions/persona/persona.md`（个人人设）
- `.mcp.json`（本地 MCP 配置）、`.env`（密钥）
- `.agent-data/`（运行时数据 / 记忆数据库 / auth）
- `.pi/news/` 等用户生成内容目录

## 隐私

pi-agent 的所有记忆、persona、运行时数据**默认本地存储**：

- 记忆数据库 `.agent-data/mem.db` 是 SQLite，本机存储
- persona.md 与 .env 已在 `.gitignore`，不会被 git 追踪
- 唯一**可能**外发的接口是你显式调用的工具（如 `web_search` / `gitee` API）

## 开发

- **新增扩展**：
  `node scripts/gen-extension.mjs <ext-name> <tool1> <tool2>` 生成骨架
  → 写工具（宿主 API 走 `.pi/extensions/shared/host-adapter.ts` 适配层）
  → 在 `.pi/settings.json` 的 packages 注册
  → `.pi/tests/extension-smoke.ts` 加 smoke 用例 + `tests/` 加单测
- **质量门禁**：`npm run check`（= smoke + test:all + typecheck）全绿才提交；pre-commit 钩子自动拦截
- **工具治理**：单扩展工具数预算 12（`tool-budget` 告警）；重复工具用 `tool-merges.json` 隐藏；规范见 `MAINTENANCE.md`
- **commit 规范**：`<type>(<scope>): <subject>`，type 取 `feat` / `fix` / `refactor` / `chore` / `docs` / `test`

## 贡献

欢迎 PR / Issue！代码风格：TypeScript strict、原生 Node ESM、扩展用
`@earendil-works/pi-coding-agent` 的 ExtensionAPI。

## 桌面端 GUI

桌面 GUI 已迁移到独立仓库：

👉 **[small-leaf999/pi-agent-desktop](https://gitee.com/small-leaf999/pi-agent-desktop)**

该仓库是 Electron + React + TypeScript 客户端，通过 JSONL RPC 协议与本仓库的 CLI 通信（详见新仓库 `docs/protocol.md`）。
启动顺序：先安装本仓库，然后 `pi-agent-desktop` 会在首次启动时探测 PATH 中的 `pi-agent` 命令（也可在设置面板手动指定路径）。

## 支持作者

如果 pi-agent 帮助到了你，欢迎扫码支持作者继续开发。

> 你的支持会用于：服务器 / API 调用费、新扩展开发时间、Windows / Linux / macOS 三端适配测试。

<p align="center">
  <img src="assets/donate-alipay.jpg" alt="支付宝收款码" width="320">
</p>

---

## 许可证

本项目采用 [MIT 许可证](LICENSE)。