OPC-Hub/agent-desktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
agent-desktop/README.md
T

11 KiB
Raw Permalink Blame History

PineAgents — 本地或云端部署的智能体工作台：多频道对话、Skills/插件扩展、定时任务与代码模式

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

目录

项目简介

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 服务层 → 运行时编排 → 智能体决策循环 → 输出，并由治理、沙箱、记忆、用量四类横向能力贯穿。

PineAgents 架构图：用户入口经 app 服务层、runtime 编排到 agents 决策循环，并由治理/沙箱/记忆/用量横向支撑

一次对话的简要流程：

  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 保留所有权利。

Reference in New Issue View Git Blame Copy Permalink