Appearance
完整操作手册
Familiars 完整操作手册（用户视角） —— 每个功能"在哪儿、点什么、按什么键、看到什么"。
🚀 启动与运行
启动方式
bash
# 开发态：Electron 前端 + 自动拉起后端 bridge
cd electron && npm run electron:dev
# 仅后端 bridge（测试用）
.venv/Scripts/python -m src.bridge.run启动后主窗口出现。Bridge 默认绑定 127.0.0.1:18711（HTTPS/2），端口被占时自动换端口并写入 workspace/.bridge.port。
两种运行模式
| 模式 | 关闭主窗口 |
|---|---|
| 前台模式 | 退出整个进程 |
| 后台模式 | 窗口隐藏，bridge 继续运行（定时任务/提醒/监听不中断） |
🖥️ 主窗口布局
┌──────────────────────────────────────────────────────────────┐
│ TitleBar（标题栏：用户信息 / 待办 / 日程 / 设置 / 窗口控件） │
├──────────┬────────────┬───────────────────────────────────────┤
│ AgentRail│ DialogList │ 主内容区 │
│ (头像列表)│ (对话列表) │ Desktop 桌面壳 / ChatStage 对话舞台 │
│ │ │ 底部 InputBar 输入栏 │
└──────────┴────────────┴───────────────────────────────────────┘- 列宽可拖动（
ResizeHandle），刷新后保留 - 三连按
Esc（1.5s 内）→ 依次关闭：树全屏 → 分屏 → 设置弹窗 → 中断生成 → 回到主页
👤 Agent 管理
Agent 列表（AgentRail）
最左侧的窄列，所有 agent 头像列表：
- + 新的 agent：顶部按钮，打开创建对话框
- 点击头像：切换到该 agent 的对话
- 折叠 / 展开：顶部箭头按钮
- 🎁 礼物徽章：agent 有未拆封礼物
- ⏰ 闹钟图标：agent 正在执行定时任务
- 置顶 manager：管理员 agent 永远在最顶部
新建 Agent
| 字段 | 说明 |
|---|---|
| 名称 | 必填，会作为 workspace/agents/agent_N/ 目录名 |
| 职责描述 | 自然语言描述 agent 的定位，系统基于此生成画像 |
| 头像 | 可选，同时作为数字人静态底图 |
创建后异步生成 voice / figure / 报告模板等资产。
Agent 设置
选中 agent 后打开，主要配置：
| 设置 | 说明 |
|---|---|
| 对话模型 | 覆盖全局 DEFAULT_MODEL，为特定 agent 配置专属模型 |
| 工作目录 | agent 优先在此目录生成文件，无需审批 |
| intense_mode | 🔴 无人监管：默认通过所有审批，不向用户求助，工作直到完成 |
| turbo_mode | 🟠 完全授权：默认通过审批，但仍可求助用户 |
| security_level | 三级审批等级，控制哪些工具需要用户确认 |
| verify_plan | 计划审批：agent 制定计划后先递交用户审阅 |
| need_initiative | 允许主动行为：设置监听任务 / 主动联系用户 |
💬 对话系统
对话列表（DialogList）
- 新的话题：列表顶部
+按钮 - 切换对话：点击条目
- 重命名：双击标题 → 回车保存，
Esc取消 - 删除：点击右侧删除图标
对话舞台（ChatStage）
主内容区的对话界面：
- 多轮对话：支持工具调用卡片（工作日志/审批卡/渲染器输出）
- 分屏：对话与工具视图并排
- 消息操作：悬浮显示复制/重试/删除
输入栏（InputBar）
| 功能 | 操作 |
|---|---|
| 发送 | 回车发送，Shift+回车换行 |
| 快捷输入 | / 触发命令面板 |
| 附件 | 拖拽或点击上传，按 kind 内联渲染 |
| 语音 | 按住小喇叭 push-to-talk |
| 技能引用 | @ 触发技能选择 |
对话树视图
每条消息在树里是一个节点：
- TreeMini：侧边小窗，快速浏览
- TreeFull：全屏树，可拖动/跳转/重放
- 右键节点：跳转重放 / 设为当前
🛠️ 工具与审批
隐私脱敏审批
高风险操作（写文件/执行命令/访问敏感数据）会弹出 PrivacyApprovalCard：
- 显示操作详情 + 风险等级
- 敏感数据自动脱敏（gitleaks → Presidio → LLM 三级检测）
- 点 允许 继续，拒绝 取消
AskUser 卡片
Agent 反问用户确认的交互卡片：
- 显示问题 + 选项
- 用户回答后 agent 继续执行
📋 待办与日程
TodoScheduleModal（三合一）
点击标题栏 📝 我的待办 / 📅 我的日程 / ⏰ 定时任务 打开：
| Tab | 功能 |
|---|---|
| 待办 | 创建/查看/完成 todo，状态流转（待办→进行中→已完成） |
| 日程 | 日历视图，创建/编辑日程 |
| Cron | 定时任务配置（cron 表达式） |
全局快捷草稿
系统级快捷键，剪贴板内容快速入库：
- 待办：
Ctrl+Shift+T（自定义） - 日程：
Ctrl+Shift+S（自定义）
📊 汇报
自动报告
| 类型 | 触发 |
|---|---|
| 日报 | 每日定时 / 手动触发 |
| 周报 | 每周日 / 手动触发 |
| 月报 | 每月 1 日 / 手动触发 |
| 年报 | 每年 1 月 1 日 / 手动触发 |
报告聚合所有 agent 的活动，manager 生成总结。在 Desktop 桌面壳的 汇报 图标查看。
🎭 数字人与语音
数字人（DigitalHuman）
- 需要本地 GPU + GPT-SoVITS 语音模型
- 配合 ASR 实现有声交互
- 在对话界面右侧面板显示
语音通话（CallOverlay）
- 语音/视频通话界面
- 支持 push-to-talk 和实时对话
🏪 工坊三兄弟
| 工坊 | 功能 | 入口 |
|---|---|---|
| 创意工坊 | Recipe / Chain 管理，技能自动化编排 | Desktop → 创意工坊 |
| 技能工坊 | Manager 长跑 skill 深表单 | Manager 对话列表 |
| 交换所工坊 | Broker 管理与市场 | Desktop → 应用 |
详见 → 工坊手册
📡 消息监听
监听微信 / QQ / 飞书消息：
- 启停面板：标题栏 🎥 或 Desktop → 消息监听
- Monitor：后台持续监听，收到消息触发 agent 响应
- Token 水印：每条 bot 回复带
[FAM<n>]token，防止重复处理
⚙️ 设置
设置中心（SettingsCenter）
标题栏 ⚙️ 打开，主要 tab：
| Tab | 内容 |
|---|---|
| 模型 | 全局模型配置、embedding/reranker |
| 主题 | 壁纸、背景图、聊天设置 |
| 账号 | 用户信息、个人信息 |
| 隐私 | 审批等级、脱敏配置 |
| 后台运行 | 开机自启、托盘行为 |
系统托盘
关闭窗口后：
- 右键托盘图标：打开/退出/设置
- 双击：恢复主窗口
⌨️ 快捷键速查
| 快捷键 | 功能 |
|---|---|
Esc × 3 | 逐级关闭（树全屏→分屏→设置→中断→主页） |
Ctrl+N | 新建对话 |
Ctrl+Shift+T | 快捷草稿 → 待办 |
Ctrl+Shift+S | 快捷草稿 → 日程 |
📖 更多
唯一权威：仓库根
OPERATION.md（§1–§42 完整）。