agent-desktop/README.md

<p align="center">
  <img src="./assets/readme/hero.svg" width="100%"
       alt="PineAgents — 本地或云端部署的智能体工作台：多频道对话、Skills/插件扩展、定时任务与代码模式">
</p>

<p align="center">
  <b>闭源商业软件</b> · 自有许可见 <a href="LICENSE">LICENSE</a> · 上游 QwenPaw 许可见 <a href="LICENSE_QwenPaw">LICENSE_QwenPaw</a> · 修改记录见 <a href="NOTICE">NOTICE</a>
</p>

---

## 目录

- [项目简介](#项目简介)
- [目录结构](#目录结构)
- [架构与流程](#架构与流程)
- [环境要求](#环境要求)
- [安装（从源码）](#安装从源码)
- [启动](#启动)
- [构建与打包](#构建与打包)
- [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 服务层 → 运行时编排 → 智能体决策循环 → 输出**，并由治理、沙箱、记忆、用量四类横向能力贯穿。

<p align="center">
  <img src="./assets/readme/architecture.svg" width="100%"
       alt="PineAgents 架构图：用户入口经 app 服务层、runtime 编排到 agents 决策循环，并由治理/沙箱/记忆/用量横向支撑">
</p>

一次对话的简要流程：

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

---

## 启动

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