user-usage-manual

name	user-usage-manual
description	BobanStaff（博办数字员工）客户端用户使用手册。当用户询问如何使用客户端进行聊天、与总管协作编排、招募员工、管理技能、查看任务排班、设置桌面宠物、管理扩展插件、切换工作空间、配置系统设置，或遇到使用中的问题（激活失败、登录失败、技能不加载、任务未执行、宠物不显示等）时使用。涵盖所有功能模块的操作步骤和常见问题解答。

用户使用手册

BobanStaff（产品包名 BobanStaffNext）数字员工客户端使用指南。本文档帮助你了解和使用客户端的全部功能。

一、快速入门

设备激活

首次在一台设备上使用时，可能需要先完成设备激活：

1. 启动后若进入激活页，输入授权码完成设备绑定
2. 激活成功后自动进入登录页
3. 激活信息与设备绑定，正常情况下只需完成一次

登录应用

1. 进入登录页面，输入用户名和密码
2. 可勾选记住密码持久化登录状态
3. 点击登录，加载成功后进入主界面
4. 需要注册时，点击登录页底部的去注册进入注册页
5. 支持飞书 SSO 登录，点击"飞书登录"按钮通过 OAuth 授权登录
6. 若提示密码已过期/需修改密码，会进入修改密码流程，改完后再登录
7. 登录页可配置服务器端地址（IP/端口），用于连接对应后端

主界面布局

┌──────────────┬──────────────────────────────────────┬─────────────┐
│  工具栏       │                                      │  右侧面板    │
│  ┌────────┐  │                                      │  ┌─────────┐ │
│  │总管     │  │          聊天主区域                     │  │通知/     │ │
│  │员工列表 │  │                                      │  │制品/     │ │
│  │工作空间 │  │                                      │  │工作台    │ │
│  └────────┘  │                                      │  └─────────┘ │
│              │                                      │              │
│  技能 | 日历 │                                      │              │
│  工作台      │                                      │              │
└──────────────┴──────────────────────────────────────┴─────────────┘

• 左侧工具栏：切换联系人/总管、技能管理、日历、工作台、工作空间
• 中间聊天区：对话列表 + 消息内容 + 输入框
• 右侧面板：通知中心、制品文件、工作台仪表盘

不熟悉客户端时，可直接向总管提问（如「怎么用工作台」「怎么下发任务」），总管会结合本手册逐步说明。

二、与总管协作 / 与员工聊天

选择对话对象

联系人面板中有两类对话对象：

类型	说明
总管（curator）	唯一的编排入口。理解你的需求后组队、派发任务、监控执行、汇总交付物，可调度所有员工
员工（employee）	单个 AI 员工，各有专长和技能，可直接单聊

没有"群聊"功能。需要多人协作时，直接告诉总管你的目标，由总管自动组队并在后台编排；或分别与各员工单聊。总管对话中可用 @ 指定优先处理的员工。

最近联系人列表可折叠为仅图标模式。

总管专属能力

与总管对话时，除普通聊天外还提供编排视图：

• 计划与子任务时间线：展示进行中的编排计划与各子任务状态
• 正在运行指示器：实时显示后台正在执行的任务
• 团队卡片：展示当前可用员工名册与能力
• 本轮交付物：本轮产出的文件/结果直接在对话中呈现
• 引导建议：根据上下文给出下一步操作建议

总管快捷指令（在输入框输入 / 触发，快捷指令在前、总管技能在后）：

指令	作用
查看进度	汇报进行中计划与各子任务状态
汇总交付物	列出已产出交付物与位置
团队复盘	复盘团队近期表现
团队与能力	查看团队名册与能力画像
质检返工	质检交付物并安排返工
缺口诊断	诊断人手/技能缺口并给建议
取消计划	取消进行中的编排计划

发送消息

1. 选中对话对象，在底部输入框输入文字
2. 按 Enter 发送
3. AI 回复以流式（SSE） 逐字展示

高级输入功能

功能	操作	说明
斜杠命令	输入 /	触发快捷指令 / 可用技能列表
@ 提及	输入 @	在总管对话中提及特定员工，优先处理
上传文件	点击附件按钮	上传文件到对话中供 AI 分析
停止生成	点击停止按钮	中断 AI 正在生成的回复

会话管理

• 与每个对象的对话按时间排列在中间面板
• 未读消息显示数字角标
• 自动滚动到最新消息，代码块高亮显示

三、招募新员工

入口

点击工具栏"招募"按钮，或在联系人面板点击"添加"。

操作步骤

1. 描述需求：输入对员工的要求，如"需要一个数据分析师，擅长 Python 和 SQL"
2. 选择模板：可点击热门岗位模板快速填充（数据分析师 / 运维工程师 / 测试工程师 / 内容运营 / HR 助手 / 财务助手 / 行政助理 等）
3. 设置推荐人数：通过"推荐人数"控件设置生成几名候选人
4. 查看候选人：每张卡片显示名称、能力描述、匹配度评分、拥有的 MCP 工具与技能
5. 录用配置：选择候选人后配置 MCP 工具、技能（可多选）、排班时间、定时任务（cron 调度）

管理员工

• 联系人面板点击员工查看详情，可编辑配置、查看技能和任务
• 可删除不再需要的员工

四、技能管理

入口

点击左侧工具栏的技能标签页。

查看已安装技能

• 网格展示所有已安装技能卡片
• 每张卡片显示英文名、中文名、来源（内置 / 本地 / 远程）
• 技能较多时支持展开/折叠，可搜索过滤

安装新技能

方式	操作
远程市场	浏览远程技能库，按分类筛选，点击"安装"（需登录远程账号 remote_login）
ZIP 导入	点击"导入 ZIP"，选择本地 .zip 技能包，自动解析 frontmatter，冲突时提示覆盖
从制品导入	在制品面板的技能草稿（skills_draft）上右键"导入到技能库"

查看与编辑技能详情

点击技能卡片查看 ID、中文名、描述、提示词、文件列表与 SKILL.md：

• 本地技能：可直接编辑保存（updateLocalSkill），删除仅限本地技能
• 内置技能：可"复制另存"为工作空间技能，或"覆盖保存"为全局覆盖
• 保存后会显示同步到的员工数量

五、工作台仪表盘

入口

点击左侧工具栏的工作台标签页。

功能概要

区域	内容
左侧面板	业绩指标（绩效系数 / 当月金额 / 排名，需 remote_performance）、排班月历、今日任务列表
主区域	可拖拽自定义的看板网格（HTML 看板区块）
右侧面板	员工监控面板（月历、任务总计、执行详情）

自定义工作台

工作台的区块来自总管生成的 HTML 看板：

1. 在右侧资源面板中，对总管生成的 HTML 制品点击**"钉到工作台"**
2. 在工作台主区域拖拽调整位置，拖拽边缘调整大小（最小 240×160）
3. 点击区块上的删除按钮移除

空状态提示："还没有看板，在右侧让总管生成一个 HTML 看板，然后在资源面板里「钉到工作台」"。

查看任务执行

• 今日任务列表：显示编排计划任务与员工执行任务，区分计划/执行
• 状态标记：运行中（蓝）/ 成功（绿）/ 失败（红）/ 超时（橙）/ 卡住（紫）/ 待处理（琥珀）
• 点击单条任务可联动到对应对话查看详情

六、排班与任务

入口

点击左侧工具栏的日历标签页（也可在工作台左侧打开排班）。

排班月历

• 月历视图，每日格子显示已排班员工
• 切换上/下月导航，点击日期查看排班详情

创建排班

通过排班编辑弹窗选择员工、日期范围、班次时段、备注，保存即生效。

定时任务

定时任务存储在 employee_tasks 表（唯一数据源）。创建/编辑员工时通过 TaskService.upsert_employee_tasks() 写入；GET /workspaces/{id}/tasks/sync 重算 next_run_at 并刷新 APScheduler。

• 调度器后台运行（APScheduler，CST 时区）
• 执行 dispatch_type 为 skill 或 mcp 的活跃任务
• 支持确认流程：从 SKILL.md 解析 confirm_url，执行后写入确认记录
• 通过 last_heartbeat_at 检测卡住的任务
• 修改员工任务后需等待调度器 reload（或触发 tasks/sync）

七、制品与文件管理

入口

聊天界面右侧的制品/资源面板。

资源树结构

按用途分为多个根：

根目录	说明
制品（artifacts）	AI 生成的代码和文档
上传（uploads）	用户上传的附件
技能草稿（skills_draft）	待导入技能库的技能文件
工作空间（workspace）	该员工跨会话的全部产物
公共区（public）	跨员工共享的文件

支持搜索过滤、查看代码（高亮）、文本、图片、表格、文档、HTML、Markdown。大文件有流式加载指示。

文件操作

操作	说明
查看内容	点击文件自动渲染
下载	右键或下载按钮（downloadResource）
删除	右键或删除按钮（deleteResource）
复制路径	右键复制文件绝对/相对路径
导入为技能	对技能草稿点击"导入到技能库"
钉到工作台	对 HTML 制品"钉到工作台"，生成看板区块
在文件管理器中显示	仅 Electron 桌面版
刷新列表	点击刷新按钮

八、工作空间（多工作空间）

应用支持多工作空间，团队、对话、技能、排班任务都按工作空间隔离：

• 每个工作空间含 id、name、root_path，归属当前用户（user_id）
• 默认工作空间 ID 为 1，进入后自动加载
• 通过工作空间切换器在不同工作空间间切换；对话/任务等 API 均带 workspace_id 作用域
• 技能：工作空间内的本地技能私有，内置技能全局共享
• 可新建工作空间（指定名称与根目录）

九、通知中心

入口

工具栏的铃铛图标（有未读时呈高亮/动画）。

通知类型

类型	颜色
任务完成	绿
任务失败	红
任务超时	橙
任务卡住	紫
任务运行中	蓝
待处理	琥珀

操作

• 点击单条通知查看详情
• 标记已读 / 全部已读
• 勾选"不再自动弹出通知"可关闭弹窗
• 支持 OS 桌面通知；任务完成时托盘图标闪烁，点击窗口后停止

十、桌面宠物

入口

设置 → 宠物标签页。

功能

• 透明无框独立窗口，始终置顶，默认在桌面角落
• 角色动画状态：待机、跑步（含左/右）、挥手、跳跃、等待、复核、失败等
• 语音输入：点击宠物开始录音，再次点击停止并发送给总管
• 拖拽移动：按住宠物拖拽到任意位置
• 双击：从主窗口隐藏状态双击宠物可唤起/聚焦主窗口

设置选项

选项	说明
启用/禁用	开关宠物窗口
皮肤选择	内置皮肤（默认 "eve"）、已安装自定义皮肤、Codex 兼容皮肤
从 zip 安装	宠物设置页「从 zip 安装…」，解压到 ~/.boban-staff-next/pets/
显示策略	始终显示 / 主窗口隐藏时显示
置顶	是否始终保持在其他窗口之上

自定义皮肤目录：

来源	路径	说明
本应用安装	~/.boban-staff-next/pets/<文件夹>/	zip 安装或手动放置；可卸载
Codex 兼容	~/.codex/pets/<文件夹>/	Petdex / Codex 生态；只读扫描

每个宠物文件夹需含 pet.json + 雪碧图（spritesheet.webp 或 sprite.webp）。列表以文件夹名为标识；若 pet.json 的 id 与文件夹名不同，应用会自动匹配。支持 petdex:// 协议加载雪碧图。

语音气泡状态

场景	显示文字
待机	—
录音中	"录音中，再点结束"
识别中	"识别并发送给总管…"
提示	"点击说话，再点结束并发送"

十一、设置

入口

工具栏的齿轮图标，或系统托盘右键菜单"打开设置"。

设置标签

标签页	功能
账号与隐私	查看个人信息（头像/姓名/部门等）、上传头像、修改密码、退出登录
通用	主题（浅色/深色/跟随系统）、开机自启、自动更新、桌面通知、代理并发/运行参数
快捷键	查看键盘快捷键参考列表
模型	配置 AI 模型与已连接的模型供应商（模型名称、API Key、API 地址、最大输入 Token 等）
宠物	桌面宠物设置（见第十章）
插件	扩展插件管理（见第十二章）
关于	应用版本号、版权信息、检查更新

十二、扩展管理

入口

设置 → 插件标签页。

查看与操作

操作	说明
启用/禁用	开关切换，禁用后扩展服务停止
打开界面	有 UI 的扩展可打开独立窗口
安装 ZIP	点击"安装扩展"，选择本地 .zip 扩展包
卸载	确认后删除扩展文件
刷新列表	点击刷新按钮

扩展文件位置

手动安装的扩展位于 ~/.boban-staff-next/extensions/<扩展ID>/，每个扩展必须包含 digital-employee.extension.json 清单文件。

十三、系统托盘（Electron 桌面版）

右键菜单

菜单项	说明
显示窗口	将主窗口带到前台
打开设置	直接打开设置页面
重启应用	重启整个应用（含 Python 后端）
退出	完全退出应用

其他操作

• 双击托盘图标：快速恢复主窗口
• 通知闪烁：任务执行完成时托盘图标闪烁，点击窗口后停止
• 关闭主窗口：默认隐藏到托盘（并显示宠物窗口），不退出应用

十四、常见问题

无法激活 / 无法登录

可能原因	解决方法
授权码错误或过期	核对授权码，必要时联系管理员重新发放
账号密码错误	检查用户名和密码
后端未启动	确认后端服务是否运行
网络/服务器配置不通	检查登录页的服务器端地址（IP/端口）
密码过期	按提示修改密码后再登录

聊天没有回复

可能原因	解决方法
AI 模型未配置	前往"设置 → 模型"检查 API Key 和模型名称
员工没有技能	为该员工安装至少一个技能
后端服务异常	查看 ~/.boban-staff-next/logs/ 下日志

技能不显示或不工作

1. 检查技能是否已安装（技能标签页查看）
2. 远程安装的技能需已登录远程账号且来源可用
3. ZIP 导入的技能格式是否正确（需包含 SKILL.md）
4. 确认当前工作空间正确（技能按工作空间隔离）
5. 查看应用日志是否有错误提示

定时任务未执行

1. 检查员工排班是否已配置
2. 确认任务的 dispatch_type 为 skill 或 mcp
3. 检查 cron 表达式是否正确
4. 修改配置后等待调度器刷新，或触发 tasks/sync
5. 查看任务执行日志了解失败原因

桌面宠物不显示

1. 前往"设置 → 宠物"确认已启用
2. 检查显示策略设置
3. 第三方宠物需文件夹内含 pet.json 与雪碧图；若 id 与文件夹名不一致，重新在列表中选择对应项
4. 尝试重启应用

扩展插件不工作

1. 确认已启用（设置 → 插件 → 开关打开）
2. 检查 ZIP 包包含 digital-employee.extension.json
3. 查看是否有版本兼容问题，必要时重新安装

应用无法更新

1. 检查"设置 → 通用"中自动更新是否开启
2. 确认服务器端配置了正确的更新包地址
3. Windows 更新格式为 .exe，macOS 需同时包含 .dmg、.zip 与 latest-mac.yml

如何获取帮助

• 查看 ~/.boban-staff-next/logs/ 下的日志文件
• 直接告诉总管你的问题，由总管协助处理

十五、数据与存储

数据位置

用户数据根目录为 ~/.boban-staff-next/（与 Python 后端一致）：

数据	路径
用户数据根	~/.boban-staff-next/
日志文件	~/.boban-staff-next/logs/
扩展插件	~/.boban-staff-next/extensions/
自定义宠物皮肤（本应用）	~/.boban-staff-next/pets/
Codex 兼容宠物皮肤	~/.codex/pets/
内置员工技能（仓库内）	apps/server/local-employees/

工作空间与项目产物由后端按工作空间根目录（root_path）及项目目录管理；登录凭证由 Electron 安全存储（electron-store）保存，非明文 auth.json。

清除数据

删除上述路径即可重置对应数据。注意：清空数据库将清除所有员工、对话和任务数据。