# xsyu-agent
**Repository Path**: renfei/xsyu-agent
## Basic Information
- **Project Name**: xsyu-agent
- **Description**: 私有云智能体助手 — 通过自然语言指令即可驱动云端应用完成办公自动化，一句指令即可完成文件整理、数据处理、文档生成等可交付成果，通过 Skills与插件扩展更可完成实际岗位工作，多频道交互更完美嵌入各类工作社交IM，同时具备多智能体协作和子智能体多线程协同，完美通过云主机隔离解决用户数据破坏等传统智能体问题。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# XsyuAgent
石大云端智能体助手
你可以用 XsyuAgent 做什么
- **自动化与定时任务**：设置定时任务 — 新闻摘要、报告生成、多频道广播 — 全部按你的时间表自动运行。
- **代码与开发**：通过通用文件工作区在项目中阅读、编辑、审查与测试代码。
- **文档处理**：读取、写入与转换 PDF、Word、Excel、PowerPoint 文件。
- **信息收集**：搜索网页、关注资讯订阅、总结视频内容，并从个人知识库中检索所需信息。
- **多频道运营**：向钉钉、飞书、Discord、Telegram 等推送告警、摘要或 AI 生成内容 — 可同时或按频道分发。
- **自定义工作流**：把内置能力、插件和定时任务组合起来，打造适合你的专属流程。
---
| 亮点 | 更新内容 |
|------|----------|
| **Agent OS — 工作区** | 每个智能体三大支柱：**资源**（透明落盘）、**治理**（allow/deny/ask/sandbox）、**沙箱**（macOS / Linux / Windows）。 |
| **Agent OS — 驱动** | 协议中立的 MCP / A2A / ACP 连接器层，带加密凭据与逐次调用策略门控。 |
| **Loop Engineering** | 高级智能体循环模板（Coding Mode、Mission Mode，更多模板持续推出），配合可组合审批门控。 |
| **Scroll 上下文** | 每一轮都持久化；滚出窗口的轮次带索引，按需回放——不摘要、不丢失。 |
| **[ReMe](https://github.com/agentscope-ai/ReMe) v0.4 自进化个人知识库** | 持续将对话与资料转化为可读、可编辑、可检索、相互链接的 Markdown 记忆。 |
| **终端界面（TUI）** | 全屏终端对话——与控制台和频道共享同一智能体、记忆与会话。 |
基于 Agent OS，我们将陆续推出开箱即用的 QwenPaw 应用小程序——如 **QwenPaw Creator**、**QwenPaw Insight** 等，敬请期待。 [v2.0.0 发布说明 →](https://qwenpaw.agentscope.io/release-notes#v2.0.0)
---
## 目录
- [快速开始](#快速开始)
- [API Key](#api-key)
- [本地模型](#本地模型)
- [安全特性](#安全特性)
- [文档](#文档)
- [常见问题](#常见问题)
- [路线图](#路线图)
- [参与贡献](#参与贡献)
- [从源码安装](#从源码安装)
---
## 快速开始
### 方式一：pip 安装
如果你习惯自行管理 Python 环境（需 Python >= 3.11, < 3.14）：
```bash
pip install qwenpaw
qwenpaw init --defaults
qwenpaw app
```
然后在浏览器中打开控制台 **http://127.0.0.1:8088/** 配置模型。若要在钉钉、飞书、微信等 app 内对话，请参考 [频道配置](https://qwenpaw.agentscope.io/docs/channels) 文档。
---
### 方式二：脚本安装
无需手动配置 Python，一行命令自动完成安装。脚本会自动下载 uv（Python 包管理器）、创建虚拟环境、安装 QwenPaw 及其依赖（含 Node.js 和前端资源）。注意：部分网络环境或企业权限管控下可能无法使用。
**macOS / Linux：**
```bash
curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash
```
**Windows (CMD):**
```CMD
curl -fsSL https://qwenpaw.agentscope.io/install.bat -o install.bat && install.bat
```
**Windows（PowerShell）：**
```powershell
irm https://qwenpaw.agentscope.io/install.ps1 | iex
```
> **注意**：安装程序将自动检查 uv 状态，若未安装则尝试自动下载配置。如遇自动安装失败，请遵循屏幕提示操作，或执行 `python -m pip install -U uv`，然后重新运行安装程序。
> **⚠️ Windows 企业版 LTSC 用户特别提示**
>
> 如果您使用的是 Windows LTSC 或受严格安全策略管控的企业环境，PowerShell 可能运行在 **受限语言模式** 下，可能会遇到以下问题：
> 1. **如果你使用的是 CMD（.bat）：脚本执行成功但无法写入 `Path`**
>
> 脚本已完成文件安装，由于 **受限语言模式**，脚本无法自动更新环境变量，此时只需手动配置：
> - **找到安装目录**：
> - 检查 `uv` 是否可用：在 CMD 中输入 `uv --version`，如果显示版本号，则**只需配置 QwenPaw 路径**；如果提示 `'uv' is not recognized as an internal or external command, operable program or batch file,`，则需同时配置两者。
> - uv 路径（任选其一，取决于安装位置，若 `uv` 不可用则填）：通常在 `%USERPROFILE%\.local\bin`、`%USERPROFILE%\AppData\Local\uv` 或 Python 安装目录下的 `Scripts` 文件夹
> - QwenPaw 路径：通常在 `%USERPROFILE%\.qwenpaw\bin`。
> - **手动添加到系统的 Path 环境变量**：
> - 按 `Win + R`，输入 `sysdm.cpl` 并回车，打开「系统属性」。
> - 点击「高级」→「环境变量」。
> - 在「系统变量」中找到并选中 `Path`，点击「编辑」。
> - 点击「新建」，依次填入上述两个目录路径，点击确定保存。
> 2. **如果你使用的是 PowerShell（.ps1）：脚本运行中断**
>
> 由于 **受限语言模式**，脚本可能无法自动下载 `uv`。
> - **手动安装 uv**：参考 [GitHub Release](https://github.com/astral-sh/uv/releases) 下载并将 `uv.exe` 放至 `%USERPROFILE%\.local\bin` 或 `%USERPROFILE%\AppData\Local\uv`；或者确保已安装 Python，然后运行 `python -m pip install -U uv`。
> - **配置 `uv` 环境变量**：将 `uv` 所在目录和 `%USERPROFILE%\.qwenpaw\bin` 添加到系统的 `Path` 变量中。
> - **重新运行**：打开新终端，再次执行安装脚本以完成 `QwenPaw` 安装。
> - **配置 `QwenPaw` 环境变量**：将 `%USERPROFILE%\.qwenpaw\bin` 添加到系统的 `Path` 变量中。
安装完成后，请打开新终端并运行：
```bash
qwenpaw init --defaults # 或：qwenpaw init（交互式）
qwenpaw app
```
安装选项
**macOS / Linux：**
```bash
# 安装指定版本
curl -fsSL ... | bash -s -- --version 1.1.0
# 从源码安装（开发/测试用）
curl -fsSL ... | bash -s -- --from-source
# 升级 — 重新运行安装命令即可
curl -fsSL ... | bash
# 卸载
qwenpaw uninstall # 保留配置和数据
qwenpaw uninstall --purge # 删除所有内容
```
**Windows（PowerShell）：**
```powershell
# 安装指定版本
irm ... | iex; .\install.ps1 -Version 1.1.12
# 从源码安装（开发/测试用）
.\install.ps1 -FromSource
# 升级 — 重新运行安装命令即可
irm ... | iex
# 卸载
qwenpaw uninstall # 保留配置和数据
qwenpaw uninstall --purge # 删除所有内容
```
---
### 方式三：使用 Docker
镜像在 **Docker Hub**（`agentscope/qwenpaw`）。镜像 tag：`latest`（稳定版）；`pre`（PyPI 预发布版）。
```bash
docker pull agentscope/qwenpaw:latest
docker run -p 127.0.0.1:8088:8088 \
-v qwenpaw-data:/app/working \
-v qwenpaw-secrets:/app/working.secret \
-v qwenpaw-backups:/app/working.backups \
agentscope/qwenpaw:latest
```
国内用户也可选用阿里云容器镜像服务 (ACR)：`agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw`（tag 相同）。
然后在浏览器中打开 **http://127.0.0.1:8088/** 进入控制台。配置、记忆与 Skills 保存在 `qwenpaw-data` 卷中；模型提供商设置与 API Key 保存在 `qwenpaw-secrets` 卷中；备份归档保存在 `qwenpaw-backups` 卷中。如需传入 API Key（如 `DASHSCOPE_API_KEY`），在 `docker run` 时添加 `-e VAR=value` 或 `--env-file .env`。
> **从容器内连接宿主机上的 Ollama 或其他模型服务**
>
> Docker 容器内的 `localhost` 指向容器自身，而非宿主机。如果 Ollama（或其他模型服务）运行在宿主机上，可通过以下方式让容器内的 QwenPaw 访问：
>
> **方式 A** — 显式绑定宿主机地址（全平台通用）：
> ```bash
> docker run -p 127.0.0.1:8088:8088 \
> --add-host=host.docker.internal:host-gateway \
> -v qwenpaw-data:/app/working \
> -v qwenpaw-secrets:/app/working.secret \
> -v qwenpaw-backups:/app/working.backups \
> agentscope/qwenpaw:latest
> ```
> 然后在 QwenPaw **设置 → 模型** 中，将 Base URL 改为 `http://host.docker.internal:<端口>` — 例如 Ollama 填 `http://host.docker.internal:11434`，LM Studio 填 `http://host.docker.internal:1234/v1`。
>
> **方式 B** — 使用宿主机网络（仅限 Linux）：
> ```bash
> docker run --network=host \
> -v qwenpaw-data:/app/working \
> -v qwenpaw-secrets:/app/working.secret \
> -v qwenpaw-backups:/app/working.backups \
> agentscope/qwenpaw:latest
> ```
> 无需端口映射（`-p`），容器直接共享宿主机网络。注意这会将容器的所有端口暴露在宿主机上，可能与已占用的端口产生冲突。
>
镜像从零构建。若需自行构建镜像，请参阅 `scripts/README.md` 中的 [Build Docker image](scripts/README.md#build-docker-image) 小节，构建后推送到你的镜像仓库。
---
### 方式四：部署到阿里云 ECS
若希望将 QwenPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 [QwenPaw 阿里云 ECS 部署链接](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) 按页面提示操作即可。详细步骤见 [阿里云开发者社区：3 分钟部署你的 AI 助理](https://developer.aliyun.com/article/1713682)。
---
### 方式五：AgentScope Platform 部署
[AgentScope Platform](https://platform.agentscope.io/) 提供一键云端 QwenPaw 部署、插件分享与 Skill 市场。完全免费，7/24 在线。
---
### 方式六：使用魔搭创空间
使用 [魔搭创空间](https://modelscope.cn/studios/fork?target=AgentScope/QwenPaw) 也可进行云端 QwenPaw 部署。注意：请将创空间设为 **非公开**，否则他人可能操纵你的 QwenPaw。
---
### 方式七：桌面应用（Beta）
> **Beta 版本说明**：桌面应用目前处于 Beta 测试阶段，存在以下已知限制：
> - **兼容性测试不完整**：未在所有系统版本和硬件配置上进行充分测试
> - **性能可能存在缺陷**：启动速度、内存占用等方面可能需要进一步优化
> - **功能持续完善中**：部分功能可能不稳定或缺失
如果你不习惯使用命令行，可以下载并使用 QwenPaw 的桌面应用版本，无需手动配置 Python 环境或执行命令。
#### 下载
从 [官方下载页](https://qwenpaw.agentscope.io/downloads) 下载桌面应用（Tauri 版）：
- **Windows**：`QwenPaw-Tauri--Windows-setup.exe`
- **macOS**：`QwenPaw-Tauri--macOS.zip`（推荐 Apple Silicon）
#### 特点
- ✅ **零配置**：下载后双击即可运行，无需安装 Python 或配置环境变量
- ✅ **跨平台**：支持 Windows 10+ 和 macOS 14+
- ✅ **可视化**：自动打开应用界面，无需手动输入地址
- ⚠️ **Beta 阶段**：功能持续完善中，欢迎反馈问题
#### 首次启动
**重要提示**：首次启动可能需要 10-60 秒（取决于您的系统配置）。应用需要初始化 Python 环境和加载依赖，请耐心等待窗口自动打开。
#### macOS：绕过系统安全限制
当你从 Releases 下载 QwenPaw macOS 应用时，macOS 可能显示：*"Apple 无法验证 'QwenPaw' 不包含恶意软件"*。这是因为应用未经过公证。你仍然可以通过以下方式打开：
- **右键打开（推荐）**
右键点击（或 Control + 点击）QwenPaw 应用 → **「打开」** → 在对话框中再次点击 **「打开」**。这会告诉 Gatekeeper 你信任该应用；之后可以像往常一样双击启动。
- **在系统设置中允许**
如果仍被阻止，进入 **系统设置 → 隐私与安全性**，向下滚动找到类似 *「已阻止 'QwenPaw'，因为无法验证开发者」* 的提示，点击 **「仍要打开」** 或 **「允许」**。
- **移除隔离属性（不推荐大多数用户）**
在终端运行：
`xattr -cr "/Applications/QwenPaw Desktop.app"`
（或使用解压后的 `.app` 路径）。这会清除「从互联网下载」的隔离标志，使警告通常不会出现，但不如使用 **右键 → 打开** 安全和可控。
详细使用说明、故障排除和常见问题，请参见 [桌面应用指南](https://qwenpaw.agentscope.io/docs/desktop)。
---
### 下一步？
安装完成后，在 **控制台 → 设置 → 模型** 中配置模型，然后探索：
- [添加 Skills](https://qwenpaw.agentscope.io/docs/skills) 扩展能力（PDF、Office、浏览器、新闻等）
- [配置频道](https://qwenpaw.agentscope.io/docs/channels) 连接钉钉、飞书、Discord 等
- [配置 Cron](https://qwenpaw.agentscope.io/docs/cron) 实现定时任务与自动化
- 查看完整 [快速开始指南](https://qwenpaw.agentscope.io/docs/quickstart) 了解所有选项与验证步骤
---
## 终端界面（TUI）
更喜欢待在终端里？运行 `qwenpaw` 即可打开一个全屏聊天 **TUI**，它驱动的是与控制台、IM 频道**完全相同**的智能体 — 同一份记忆、技能、MCP 工具与会话 — 无需离开键盘。
```bash
qwenpaw # 与当前激活的智能体开启对话
qwenpaw tui --resume # 恢复之前的某个会话
qwenpaw . # 在当前代码仓库中启动（Coding 模式）
```
支持流式回复、斜杠命令（`/help`、`/resume`、`/theme`，以及智能体自身的 `/model`、`/clear` 等）、把文件 / 长文本作为附件粘贴，以及行内工具授权提示。详见 [终端界面指南](https://qwenpaw.agentscope.io/docs/tui)。
---
## API Key
若使用**云端大模型 API**（如 DashScope / 通义千问、OpenAI、Anthropic、Google Gemini、DeepSeek、Kimi、OpenRouter 等），在开始对话前必须配置 API Key。未配置有效 Key 前，QwenPaw 无法正常工作。详情请参考 [官方文档](https://qwenpaw.agentscope.io/docs/models)。
**配置方式：**
1. **控制台（推荐）** — 运行 `qwenpaw app` 后，打开 **http://127.0.0.1:8088/** → **设置** → **模型**。选择提供商、填写 **API Key**，并启用该提供商与模型。
2. **`qwenpaw init`** — 运行 `qwenpaw init` 时，会引导你配置 LLM 提供商与 API Key。按提示选择提供商并填写 Key 即可。
3. **环境变量** — 使用 DashScope 时，可在终端或工作目录下的 `.env` 文件中设置 `DASHSCOPE_API_KEY`。
其他工具所需密钥（如网页搜索的 `TAVILY_API_KEY`）可在控制台 **设置 → 环境变量** 中配置，详见 [配置](https://qwenpaw.agentscope.io/docs/config)。
> **仅用本地模型？** 若使用 [本地模型](#本地模型)（QwenPaw Local / Ollama / LM Studio），则**无需**任何 API Key。
## 本地模型
QwenPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。详情请见 [官方文档](https://qwenpaw.agentscope.io/docs/models)。
QwenPaw 还提供 **QwenPaw-Flash** 系列 — 面向 Agent 场景专项训练的 2B / 4B / 9B 模型，提供 Q4 与 Q8 量化版本。可在 [ModelScope](https://www.modelscope.cn/organization/AgentScope?tab=model) 与 [Hugging Face](https://huggingface.co/agentscope-ai/models) 获取。
| 后端 | 适用场景 | 安装 |
| --------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
| **QwenPaw Local**（llama.cpp） | 跨平台（macOS / Linux / Windows） | 内置；在 Web 界面点击「Download」即可。支持 QwenPaw-Flash，并提供硬件感知推荐。 |
| **Ollama** | 跨平台（需要 Ollama 服务运行） | 安装并启动 Ollama；将上下文长度设为 ≥ 32k。 |
| **LM Studio** | 跨平台（需要 LM Studio 服务运行） | 安装并启动 LM Studio；启用 Local Server。 |
---
## 安全特性
QwenPaw 内置五层核心安全防护：
- **Sandbox** — 内核级执行隔离，macOS 使用 Seatbelt，Linux 使用 Bubblewrap / Landlock，Windows 使用 AppContainer。Shell 命令在受限文件系统视图中运行。
- **Tool Guard** — 带 `ShellEvasionGuardian` 的 YAML 规则引擎，在每次工具调用执行前进行检查，检测命令注入、路径遍历、反向 Shell 与混淆攻击。可配置审批级别：STRICT / SMART / AUTO / OFF。
- **File Guard** — 独立于 Tool Guard；阻止智能体访问敏感文件与目录（默认保护 `~/.qwenpaw.secret/`、`~/.ssh` 等）。
- **Skill Scanner** — 激活前扫描，支持 block / warn / off 模式与白名单。检测提示词注入、硬编码密钥、数据外泄等风险。
- **Access Policy** — 声明式访问策略，对每次能力调用裁定放行(allow)、拒绝(deny)或请求人工审批(ask)，支持工具级粒度和来源感知匹配。
详见 [安全文档](https://qwenpaw.agentscope.io/docs/security)。
---
## 路线图
| 方向 | 事项 | 状态 |
| ------------------------ | ----------------------------------------- | ------ |
| **横向拓展** | 更多频道、模型、技能、MCP | 征集中 |
| **已有功能扩展与完善** | 展示、下载与 Windows 兼容优化 | 征集中 |
| **模型** | 多模型切换 | 进行中 |
| **安全与审批** | 批量预览与批准 | 进行中 |
| **自动化** | 自动化任务 | 进行中 |
| **智能体交互** | 智能体任务交接 | 进行中 |
| | 运行中任务调整 | 进行中 |
| **工作区** | 多工作区 | 进行中 |
| **上下文** | 系统提示压缩 | 进行中 |
| **工具系统** | 多位置文件修改 | 进行中 |
| | 持久终端与后台任务 | 进行中 |
| **Computer-use** | 屏幕目标定位与操作 | 进行中 |
| **语音交互** | 实时语音任务 | 进行中 |
| **上下文管理与记忆** | 向量模型与存储热切换 | 进行中 |
| | 个人知识库 | 进行中 |
| **QwenPaw 应用** | QwenPaw Insight | 进行中 |
| | QwenPaw Mail | 进行中 |
_状态说明：**进行中** — 正在积极开发；**征集中** — 我们强烈鼓励社区参与。_
---
## 从源码安装
```bash
git clone https://github.com/agentscope-ai/QwenPaw.git
cd QwenPaw
# 先构建前端控制台（Web 界面必需）
cd console && npm ci && npm run build
cd ..
# 将控制台构建产物复制到包目录
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/
# 安装 Python 包
pip install -e .
```
- **开发**（测试、格式化）：`pip install -e ".[dev,test,full]"`
- **然后**：运行 `qwenpaw init --defaults`，再运行 `qwenpaw app`。
> **版本更新提示：** 当执行 `git pull` 更新到大版本后，请重新构建前端、重新安装 Python 包（`pip install -e .`）、重启 `qwenpaw app`，并清除浏览器缓存（`Ctrl+Shift+R` 或 macOS 上 `Cmd+Shift+R`）。