闭源商业软件 · 自有许可见 LICENSE · 上游 QwenPaw 许可见 LICENSE_QwenPaw · 修改记录见 NOTICE
---
## 目录
- [项目简介](#项目简介)
- [目录结构](#目录结构)
- [架构与流程](#架构与流程)
- [环境要求](#环境要求)
- [安装（从源码）](#安装从源码)
- [启动](#启动)
- [构建与打包](#构建与打包)
- [Docker 部署](#docker-部署)
- [测试](#测试)
- [二次开发指引](#二次开发指引)
- [许可证](#许可证)
---
## 项目简介
PineAgents 是一个可自主运行的**智能体操作系统（Agent OS）**：它通过多频道（钉钉、飞书、微信、QQ、Discord、Telegram 等）与用户对话，用 Skills 与插件扩展能力，支持定时任务（Cron）、多智能体编排、代码模式与三层记忆。
本项目是开源项目 [QwenPaw](https://github.com/agentscope-ai/QwenPaw)（Apache 2.0）的**闭源商业衍生**，走「Fork + 上游同步」开发路线。所有基于上游的修改均登记在 [`NOTICE`](NOTICE)。
---
## 目录结构
### 顶层
| 路径 | 作用 |
|------|------|
| `src/pineagents/` | **Python 后端运行时**（全部核心逻辑） |
| `console/` | **前端 Web 界面**（React + Vite），含 Tauri 桌面壳（`console/src-tauri/`） |
| `plugins/` | 独立插件包（channel / tool / app） |
| `deploy/` | Docker 部署（`Dockerfile`、`entrypoint.sh`、`config/`） |
| `scripts/` | 构建 / 安装 / 打包脚本 |
| `assets/readme/` | README 静态资源（本项目 SVG 图） |
| `tests/` | 测试（unit / contract / integration / e2e） |
| `docs/secondary-dev/` | **二次开发文档**（品牌盘点、抽离方案） |
| `old_docs/` | **原上游文档归档**（QwenPaw README/CONTRIBUTING/RELEASING 等） |
| `LICENSE` | PineAgents 闭源商业许可 |
| `LICENSE_QwenPaw` | 上游 QwenPaw（Apache 2.0）许可 |
| `NOTICE` | 所有基于上游的修改说明（必读） |
| `SECURITY.md` | 安全策略 |
### 后端核心（`src/pineagents/`）
| 模块 | 作用 |
|------|------|
| `constant.py` | 核心常量、路径、环境变量回退（品牌配置入口） |
| `branding.py` | **品牌单一事实源**（PineAgents 命名，改品牌改这里） |
| `agents/` | 智能体核心：`react_agent.py`（决策循环）、prompt 构建、**Skill 系统**、工具集、记忆 |
| `runtime/` | 运行时编排：循环执行、工具守卫、slash 命令、prompt 管理 |
| `app/` | **FastAPI 服务层**：路由、频道接入、多智能体管理、Cron、工作区 |
| `cli/` | 命令行入口（`pineagents` / `qwenpaw` / `copaw`），含 TUI |
| `providers/` | 模型供应商（云端 / 本地 Ollama / LM Studio） |
| `drivers/` | 协议连接器层（MCP / A2A / ACP） |
| `governance/` | 权限治理（allow / deny / ask / sandbox） |
| `sandbox/` | 内核级执行隔离（macOS Seatbelt / Linux Bubblewrap / Win AppContainer） |
| `security/` | Tool Guard / File Guard / Skill Scanner 安全规则 |
| `memory/` | 记忆（三层：工作上下文、逐字历史、ReMe 个人知识库） |
| `loop/` | 循环模板（Coding Mode / Mission Mode）与审批门控 |
| `token_usage/` | 每轮 token / 上下文用量统计 |
| `plugins/` | 插件加载与市场 |
| `pawapp/` | 小程序（App）平台 |
### 前端（`console/`）
| 路径 | 作用 |
|------|------|
| `src/pages/` | 页面：Chat、Settings（Agents/Models/Market…）、Agent 配置、Inbox、AppCenter |
| `src/layouts/` | 侧边栏 / 顶栏 / 菜单 / 路由注册 |
| `src/stores/` | 前端状态（agent、session、sidebar、message queue） |
| `src/api/` | 后端 REST 接口封装 |
| `src/plugins/` | 插件宿主 SDK（`window.PineAgents` 契约） |
| `src/locales/` | 多语言文案（zh/en/ja/ru/vi…） |
| `src/constants/branding.ts` | 前端品牌单一事实源 |
| `src-tauri/` | Tauri 桌面壳 |
---
## 架构与流程
一次对话的主链路：**用户入口 → FastAPI 服务层 → 运行时编排 → 智能体决策循环 → 输出**，并由治理、沙箱、记忆、用量四类横向能力贯穿。
一次对话的简要流程：
1. 用户从任意入口（Web / CLI / 频道）发送消息。
2. `app/` 接收并路由到对应 Agent 会话。
3. `runtime/` 组装 prompt（含 Persona、上下文、记忆检索），进入决策循环。
4. `agents/react_agent.py` 迭代：思考 → 调用工具（经 Tool Guard 与治理门控）→ 沙箱内执行。
5. 结果回流，模型生成最终回复，经频道分发返回用户。
6. 关键交互写入记忆与 token 用量。
---
## 环境要求
| 组件 | 要求 |
|------|------|
| Python | **≥ 3.11 且 < 3.14** |
| Node.js / npm | 前端构建必需 |
| uv | 可选（安装/虚拟环境加速） |
| Rust | 仅构建桌面端（Tauri）需要 |
| Docker | 仅容器化部署需要 |
---
## 安装（从源码）
```bash
git clone
cd PineAgents
# 1. 构建前端控制台（Web 界面必需）
cd console && npm ci && npm run build && cd ..
# 2. 将构建产物复制进 Python 包
mkdir -p src/pineagents/console
cp -R console/dist/. src/pineagents/console/
# 3. 安装 Python 包
pip install -e .
```
> 开发模式（含测试/格式化依赖）：`pip install -e ".[dev,test,full]"`
> 不想手工复制前端时，直接用 `bash scripts/wheel_build.sh`（见下文「构建与打包」），它自动完成第 1、2 步。
---
## 启动
```bash
# 初始化（交互式；--defaults 使用默认值）
pineagents init --defaults
# 启动 Web 控制台（默认 http://127.0.0.1:8088/）
pineagents app
# 终端界面（TUI）
pineagents
# 在当前代码仓库中启动（Coding 模式）
pineagents .
```
> 兼容命令：`qwenpaw` / `copaw` 仍可用（指向同一入口，供同步与迁移）。
> 端口覆盖：`pineagents app --port 3000`（默认 8088）。
> 首次启动需在控制台 **设置 → 模型** 配置模型（云端 API Key 或本地 Ollama / LM Studio）。
---
## 构建与打包
### 前端 Console
```bash
cd console
npm run dev # 开发热更新（http://localhost:5173）
npm run build # 生产构建（tsc -b && vite build）
npm run build:prod # 生产构建（production 模式）
npm run lint # ESLint
npm run test:run # 前端单测
npm run format:check # 格式化检查
```
### Python Wheel（一键，含最新前端）
```bash
# macOS / Linux
bash scripts/wheel_build.sh
# Windows（PowerShell）
pwsh -File scripts/wheel_build.ps1
```
自动完成：构建前端 → 复制 `console/dist` 到 `src/pineagents/console/` → 打包文档 → 生成 wheel 与 sdist。产物位于 `dist/`（`*.whl` / `*.tar.gz`）。
### 桌面应用（Tauri，PyInstaller 后端 sidecar）
```bash
# 1) 打包后端 sidecar（产物在 dist/ 下）
./scripts/pack-tauri/build_pyinstaller.sh # macOS / Linux
pwsh -File scripts/pack-tauri/build_pyinstaller.ps1 # Windows
# 2) 一键构建桌面 App
./scripts/pack-tauri/build_macos_pyinstaller.sh # macOS → dist/*.app
pwsh -File scripts/pack-tauri/build_win_pyinstaller.ps1 # Windows → 安装包
```
产物默认在 `dist/`：macOS 为 `.app`（可配合 `scripts/pack-tauri/sign_macos_bundle.sh` 签名），Windows 为 NSIS 安装包 / `win-unpacked`。
直接使用 Tauri CLI（在 `console/` 下）：
```bash
cd console
npm run build:tauri-bootstrap # 先构建前端引导（dist-tauri）
npx tauri build # 再打包桌面应用
```
> 遗留的 conda-pack 打包脚本（`scripts/pack/`）已废弃，仅供回滚，见 [`scripts/pack/README.md`](scripts/pack/README.md)。
### 网站
```bash
bash scripts/website_build.sh # 输出 website/dist/
```
---
## Docker 部署
### 构建镜像
`deploy/Dockerfile` 是多阶段构建：Stage 1 自动构建前端 Console，Stage 2 组装 Python 运行时（含 Chromium 与 Playwright 配置），无需在宿主机预装前端依赖。
```bash
# 一键脚本（推荐）
bash scripts/docker_build.sh pineagents:latest
# 等价原始命令
docker build -f deploy/Dockerfile -t pineagents:latest .
```
> 默认排除 `imessage`（macOS 专用）频道。可用环境变量覆盖：
> `QWENPAW_DISABLED_CHANNELS=imessage,voice`（排除）或 `QWENPAW_ENABLED_CHANNELS=discord,telegram`（白名单）。
### 运行
```bash
# docker compose（推荐，端口 8088）
docker compose up -d # 访问 http://127.0.0.1:8088/
# 或原始 docker run（挂载三个持久化卷）
docker run -d --name pineagents \
-p 127.0.0.1:8088:8088 \
-v pineagents-data:/app/working \
-v pineagents-secrets:/app/working.secret \
-v pineagents-backups:/app/working.backups \
pineagents:latest
```
容器启动时若工作区缺少 `config.json` 会自动执行 `pineagents init --defaults`。
### 自定义端口与启用认证
```bash
docker run -d --name pineagents \
-p 127.0.0.1:3000:3000 \
-e QWENPAW_PORT=3000 \
-e QWENPAW_AUTH_ENABLED=true \
-e QWENPAW_AUTH_USERNAME=admin \
-e QWENPAW_AUTH_PASSWORD=changeme \
pineagents:latest
```
> ⚠️ 认证变量为 `QWENPAW_AUTH_ENABLED` / `QWENPAW_AUTH_USERNAME` / `QWENPAW_AUTH_PASSWORD`（旧名 `COPAW_*` 兼容）。注意 `docker-compose.yml` 注释中的 `PINEAGENTS_AUTH_*` 并非有效变量，属待修正的历史注释。
> 不启用认证时，容器会打印安全提示：请确保服务仅暴露于可信网络，或对不可信访问者开启认证。
---
## 测试
```bash
make test # 全部测试
make test-unit # 单元测试
make test-contract # 契约测试
make test-integration # 集成测试
make coverage-full # 覆盖率（含 HTML 报告）
make quick # 快速反馈（单测，失败即停）
```
或用测试入口脚本：
```bash
python scripts/run_tests.py # 全部测试
python scripts/run_tests.py -u # 单元测试
python scripts/run_tests.py -i # 集成测试
python scripts/run_tests.py -a -c # 全部 + 覆盖率
python scripts/run_tests.py -p # 并行（需 pytest-xdist）
python scripts/run_tests.py -h # 帮助
```
---
## 二次开发指引
本项目基于 QwenPaw 二次开发，核心约定：
- **改品牌**：改后端 `src/pineagents/branding.py` + 前端 `console/src/constants/branding.ts`，不要改散落字面量。
- **改逻辑**：智能体决策见 `agents/react_agent.py`，编排见 `runtime/`，治理见 `governance/`。
- **必读**：`docs/secondary-dev/`（品牌盘点与抽离方案）、`NOTICE`（修改登记）、`SECURITY.md`。
- **铁律**：任何基于上游 QwenPaw 的改动，**必须登记到 `NOTICE`** 后再提交。
上游同步：从远端 `github` 拉取 QwenPaw，改动推送至远端 `infoepoch_lan`。
---
## 许可证
- **PineAgents**：闭源商业软件，见 [`LICENSE`](LICENSE)（模板，上线前请法务审核）。
- **上游 QwenPaw**：Apache License 2.0，见 [`LICENSE_QwenPaw`](LICENSE_QwenPaw)。
- 修改说明见 [`NOTICE`](NOTICE)。
**Copyright © 2026 PineAgents 保留所有权利。**