闭源商业软件 · 自有许可见 LICENSE · 上游 QwenPaw 许可见 LICENSE_QwenPaw · 修改记录见 NOTICE

---

目录

• 项目简介
• 目录结构
• 架构与流程
• 环境要求
• 安装（从源码）
• 启动
• 构建与打包
• Docker 部署
• 测试
• 二次开发指引
• 许可证

---

项目简介

PineAgents 是一个可自主运行的智能体操作系统（Agent OS）：它通过多频道（钉钉、飞书、微信、QQ、Discord、Telegram 等）与用户对话，用 Skills 与插件扩展能力，支持定时任务（Cron）、多智能体编排、代码模式与三层记忆。

本项目是开源项目 QwenPaw（Apache 2.0）的闭源商业衍生，走「Fork + 上游同步」开发路线。所有基于上游的修改均登记在 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	仅容器化部署需要

---

安装（从源码）

git clone <PineAgents 仓库地址>
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 步。

---

启动

# 初始化（交互式；--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

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（一键，含最新前端）

# 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）

# 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/ 下）：

cd console
npm run build:tauri-bootstrap   # 先构建前端引导（dist-tauri）
npx tauri build                 # 再打包桌面应用

遗留的 conda-pack 打包脚本（scripts/pack/）已废弃，仅供回滚，见 scripts/pack/README.md。

网站

bash scripts/website_build.sh   # 输出 website/dist/

---

Docker 部署

构建镜像

deploy/Dockerfile 是多阶段构建：Stage 1 自动构建前端 Console，Stage 2 组装 Python 运行时（含 Chromium 与 Playwright 配置），无需在宿主机预装前端依赖。

# 一键脚本（推荐）
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（白名单）。

运行

# 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。

自定义端口与启用认证

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_* 并非有效变量，属待修正的历史注释。 不启用认证时，容器会打印安全提示：请确保服务仅暴露于可信网络，或对不可信访问者开启认证。

---

测试

make test                  # 全部测试
make test-unit             # 单元测试
make test-contract         # 契约测试
make test-integration      # 集成测试
make coverage-full         # 覆盖率（含 HTML 报告）
make quick                 # 快速反馈（单测，失败即停）

或用测试入口脚本：

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（模板，上线前请法务审核）。
• 上游 QwenPaw：Apache License 2.0，见 LICENSE_QwenPaw。
• 修改说明见 NOTICE。

Copyright © 2026 PineAgents 保留所有权利。