## 更新日志
- **2026-07-15**：StaffDeck正式开源！欢迎大家使用反馈与Star支持。
# 💡 关于StaffDeck
StaffDeck是一套面向企业的数字员工构建与管理平台，帮助专业员工将工作经验、业务流程和判断标准固化为可以持续工作的数字员工，接手重复性任务，并将个人能力沉淀为可复用、可迭代、可追溯的组织资产。StaffDeck由[面壁智能](https://modelbest.cn/)，[东北大学-面壁智能数据智能联合实验室](https://neuir.github.io/)，[清华大学THUNLP实验室](https://nlp.csai.tsinghua.edu.cn/)，[OpenBMB](https://www.openbmb.cn/home)与[AI9Stars](https://github.com/AI9Stars)联合研发，面向希望将 AI 从个人效率工具升级为组织生产力的企业与机构。
## 核心亮点
- 🧑💼 **数字员工构建与管理**：将专业员工的经验、流程和判断标准固化为拥有岗位、工号、能力档案和工作记录的数字员工；支持能力成长、权限隔离及发布复用。
- 🧩 **状态机驱动的流程型技能**：通过自然语言生成结构化 SOP，以状态机保证复杂流程准确执行；支持多个流程实时切换、上下文保留、可视化编辑、版本管理和分支演化。
- 📚 **文档结构感知的知识检索**：基于文档、章节、页面和摘要等层级构建可导航索引，让数字员工先判断信息可能位于哪里，再逐层定位原文；支持知识分桶、定向检索、来源引用和检索调试。
- 🔌 **自主执行与持续迭代**：通过 HTTP API、MCP 和定时任务执行真实业务操作，并结合长期记忆、完整 Trace、真人接管、用户反馈和反馈分析形成持续迭代闭环。
## 客户端下载
访问 [StaffDeck 官方网站](https://staffdeck.openbmb.cn/)，或直接下载最新桌面客户端：
| 平台 | 架构 | 下载 |
| --- | --- | --- |
| macOS | Apple Silicon（arm64） | [下载 `.dmg`](https://github.com/OpenBMB/StaffDeck/releases/latest/download/StaffDeck-macos-arm64.dmg) |
| Windows | x64 | [下载安装程序 `.exe`](https://github.com/OpenBMB/StaffDeck/releases/latest/download/StaffDeck-windows-x64-setup.exe) |
| Linux | x86_64（Debian/Ubuntu） | [下载 `.deb`](https://github.com/OpenBMB/StaffDeck/releases/latest/download/StaffDeck-linux-x86_64.deb) |
## Agent 一键部署
将下面的 Prompt 粘贴给 Cursor、Claude Code 或 Codex：
```text
阅读 https://raw.githubusercontent.com/OpenBMB/StaffDeck/main/README.zh.md。
克隆 OpenBMB/StaffDeck 私有仓库，准备 Python 3.11 或更高版本和 Node.js 20，创建
backend/.venv，安装前后端依赖，将 backend/.env.example 复制为
backend/.env；缺少 OpenAI 兼容模型地址或 API Key 时向我询问，并严格使用当前
系统对应的文档命令。macOS/Linux/WSL 运行 scripts/dev_up.sh --detach，Windows
PowerShell 运行 .\scripts\dev_up.ps1 --detach；验证 /api/health 和
/workspace/gallery 后再报告完成。
```
## 目录
- [💡 关于StaffDeck](#-关于staffdeck)
- [核心亮点](#核心亮点)
- [客户端下载](#客户端下载)
- [Agent 一键部署](#agent-一键部署)
- [目录](#目录)
- [快速开始](#快速开始)
- [环境要求](#环境要求)
- [1. 克隆并安装](#1-克隆并安装)
- [2. 配置模型](#2-配置模型)
- [3. 启动 Web Demo](#3-启动-web-demo)
- [4. 验证安装](#4-验证安装)
- [常用命令](#常用命令)
- [统一 Python 入口](#统一-python-入口)
- [核心流程](#核心流程)
- [项目结构](#项目结构)
- [常见问题](#常见问题)
- [路线图](#路线图)
- [💬 联系我们](#-联系我们)
- [参与贡献](#参与贡献)
- [风险与限制](#风险与限制)
- [引用](#引用)
- [许可证](#许可证)
- [致谢](#致谢)
## 快速开始
### 环境要求
- 支持 macOS、Linux、WSL 或 Windows PowerShell
- Python **3.11+**
- Node.js **20+** 与 npm
- OpenAI Chat Completions 兼容的模型接口和 API Key
- 应用本身不要求 CUDA；硬件要求由所选择的模型服务决定
### 1. 克隆并安装
首先克隆仓库：
```bash
git clone https://github.com/OpenBMB/StaffDeck.git
cd StaffDeck
```
macOS、Linux 或 WSL：
```bash
python3 -m venv backend/.venv
backend/.venv/bin/python -m pip install -e "backend[dev]"
npm --prefix frontend-enterprise ci
cp backend/.env.example backend/.env
```
Windows PowerShell：
```powershell
py -3 -m venv backend\.venv
.\backend\.venv\Scripts\python.exe -m pip install -e "backend[dev]"
npm --prefix frontend-enterprise ci
Copy-Item backend\.env.example backend\.env
```
### 2. 配置模型
首次启动前编辑 `backend/.env`：
```dotenv
APP_SECRET="请替换为足够长的随机字符串"
DEMO_MODEL_BASE_URL="https://你的OpenAI兼容接口/v1"
DEMO_MODEL_NAME="你的模型名"
DEMO_MODEL_API_KEY="你的API-Key"
```
API Key 用于创建初始模型配置，存入数据库前会被加密。请勿提交 `backend/.env`。服务启动后也可以在**管理员 → 模型配置**中管理模型服务。
### 3. 启动 Web Demo
| 平台 | 推荐命令 |
| --- | --- |
| macOS、Linux 或 WSL | `scripts/dev_up.sh --detach` |
| Windows PowerShell | `.\scripts\dev_up.ps1 --detach` |
两套包装脚本最终都会调用同一个跨平台 Python 生命周期入口 `scripts/dev.py`。启动过程会构建 StaffDeck 前端，并由一个 FastAPI 进程在 `5173` 端口同时提供 UI、API 与 Swagger 文档。默认管理员账号为 `admin` / `admin`，请在首次登录后通过账号配置修改密码。
### 4. 验证安装
macOS、Linux 或 WSL：
```bash
curl http://127.0.0.1:5173/api/health
```
Windows PowerShell：
```powershell
curl.exe http://127.0.0.1:5173/api/health
```
预期输出：
```json
{"status":"ok"}
```
打开 [http://127.0.0.1:5173/workspace/gallery](http://127.0.0.1:5173/workspace/gallery)，选择一个数字员工并发送首条消息。回答和执行记录应该在同一个对话轮次中流式显示。
### 常用命令
| 操作 | macOS、Linux 或 WSL | Windows PowerShell |
| --- | --- | --- |
| 后台启动 | `scripts/dev_up.sh --detach` | `.\scripts\dev_up.ps1 --detach` |
| 前台启动 | `scripts/dev_up.sh` | `.\scripts\dev_up.ps1` |
| 查看服务状态 | `scripts/dev_status.sh` | `.\scripts\dev_status.ps1` |
| 停止本地服务 | `scripts/dev_down.sh` | `.\scripts\dev_down.ps1` |
#### 统一 Python 入口
上述包装脚本最终都会调用 `scripts/dev.py`。也可以直接使用第 1 步创建的项目虚拟环境，避免依赖 Shell 脚本执行能力或系统 Python Launcher：
| 平台 | 直接后台启动 |
| --- | --- |
| macOS、Linux 或 WSL | `backend/.venv/bin/python scripts/dev.py up --detach` |
| Windows PowerShell | `.\backend\.venv\Scripts\python.exe scripts\dev.py up --detach` |
需要执行其他操作时，将 `up --detach` 替换为对应的生命周期参数：
| 操作 | 参数 |
| --- | --- |
| 后台启动 | `up --detach` |
| 前台启动 | `up` |
| 查看服务状态 | `status` |
| 停止本地服务 | `down` |
> 完整说明 → [StaffDeck 使用教程](https://staffdeck.openbmb.cn/#/docs/introduce?lang=zh)
## 核心流程
1. **创建数字员工**：设置职位、岗位边界、服务风格、创建者与访问范围。
2. **配置员工能力**：从广场复制或自行创建知识库、通用技能、SOP 与工具，不修改广场原件。
3. **发起会话**：从数字员工广场或员工列表进入；发送首条消息后持久化正式 Session。
4. **执行并观测**：在执行记录中查看流式意图、检索、技能、工具、校验和回答事件。
5. **必要时介入**：继续排队请求、取消运行、转人工或处理待回答内容。
6. **持续运营**：利用记忆、反馈、对话日志和定时任务长期优化员工能力。
## 项目结构
```text
StaffDeck/
├── backend/ # FastAPI 接口、Agent 运行时、存储与任务 Worker
├── frontend-enterprise/ # React/TypeScript StaffDeck 工作台
├── docs/ # 教程、API、Schema 与示例流程
├── scripts/ # 单端口服务生命周期与校验脚本
├── packaging/ # macOS、Linux 与 Windows 打包资源
├── README.md # English
└── README.zh.md # 简体中文
```
## 常见问题
