通用手册

Familiars 完整操作手册（用户视角）—— 每个功能"在哪儿、点什么、按什么键、看到什么"。 ⚠️ 来源：仓库根 OPERATION.md（§1–§42）+ electron/renderer/src/components/ 全部 Vue 组件 + src/bridge/routes/ 全部路由。

快速导航

章节	核心组件	入口	一句话
§1 启动与运行模式	`electron/python.js` → bridge	`cd electron && npm run electron:dev`	前端 Electron + 后端 FastAPI bridge(127.0.0.1:18711)
§2 主窗口布局	`Desktop.vue` + `ResizeHandle.vue`	启动即见	四列布局：AgentRail / DialogList / ChatStage + 标题栏
§3 标题栏 TitleBar	`TitleBar.vue`	窗口最顶部	身份区（左）+ 窗口控件（右）：置顶/最小化/最大化/关闭
§4 管理员主页	`Desktop.vue`	选中 agent 0 且无对话	桌面 shell：壁纸 + 图标 + 浮动窗口 + 任务栏
§5 Agent 列表	`AgentRail.vue`	最左列	头像列表，+新建，🎁/⏰ 角标，右键操作
§6 新建 Agent	`CreateAgentModal.vue`	AgentRail 顶部 `+`	名称 + 职责 + 头像 → 异步生成资产
§7 Agent 设置	`AgentSettings.vue`	AgentRail 右键	模型/提示词/记忆/intense_mode/turbo_mode/审批等级
§8 对话列表	`DialogList.vue`	选中 agent 后	对话条目 + 新建 + 重命名/删除 + 工坊虚拟对话
§9 对话舞台	`ChatStage.vue`	选中对话	消息流 + 工具卡片 + 分屏 + 树视图 + CG 覆盖
§10 对话树视图	`TreeMini.vue` / `TreeFull.vue`	ChatStage 角落缩略图	节点拖拽/搜索/导出/跳转
§11 输入栏	`InputBar.vue`	ChatStage 底部	附件/文件夹/Skill/知识库/快捷输入/@模型/文本/语音/发送
§12 附件渲染	`AttachmentRenderer.vue`	消息气泡内	按 kind 自动选：image/video/audio/link/file
§13 快捷输入/模型/Skill	`InputBar.vue` 子面板	输入栏 ⚡/@/🧩/📚	短语拼接、临时切模型、引用 Skill/KB
§14 语音输入	`InputBar.vue` 🎙️	右下角麦克风	push-to-talk → faster-whisper 本地转写 → 追加到输入框
§16 数字人	`DigitalHuman.vue`	ChatStage 👤 切换	WebSocket `/ws/digital_human/<agent_id>` 驱动嘴形/表情
§18 汇报	`ReportApp.vue`	Desktop 汇报图标	所有 agent 日/周/月/年报告聚合视图
§19 技能锻造	`SkillForgeModal.vue`	ChatStage 多选 → 锻造	3 步向导：params → review → commit
§20 Skill 审批	`SkillApprovalsView.vue`	Desktop Skill改动审批图标	批准/拒绝/稍后审批队列
§21 待办/日程/Cron	`TodoScheduleModal.vue`	Desktop 待办图标 / 标题栏	Todo/Schedule/Cron 三标签
§22 全局快捷草稿	`DraftConfirmModal.vue`	`Ctrl+Shift+A/S/T`	剪贴板 → LLM 解析 → 待办/日程
§23 提醒 Toast	`ReminderToast.vue`	右上角浮卡	schedule/todo/desktop 提醒 + OS 通知
§24 隐私审批	`PrivacyApprovalCard.vue`	对话内卡片	gitleaks/Presidio/小模型 → ignore/mask/record
§25 AskUser 卡片	`AskUserCard.vue`	对话内卡片	agent 反问 → chip 预填 / 文本框回答
§26 CG 动画工坊	`CgWorkshop.vue`	Desktop CG动画工坊图标	为 agent+skill 生成片头 CG 视频
§27 Agent 工坊	`AgentWorkshop.vue`	Desktop Agent工坊图标	导入 OpenClaw/Hermes/自定义 agent
§28 消息监听	`MonitorApp.vue`	Desktop 消息监听图标	微信/QQ monitor 启停 + 联系人配置
§29 个人信息	`UserProfileModal.vue`	TitleBar 身份区点击	昵称 + 头像 + 自我介绍
§30 背景/主题/Chat设置	`ChatSettings.vue`	ChatStage 顶部 ⚙️	字体/字号/背景/置顶
§31 后台运行	`SettingsCenter.vue` 后台标签	TitleBar ⚙️ / 托盘	后台开关 + 开机自启 + PID + 退出
§32 系统托盘	Electron Tray	后台运行时	双击恢复 / 右键菜单 / tooltip
§33 状态浮窗	`StatusOverlay.vue`	`?view=overlay` URL	红/橙/紫/蓝颜色标识系统接管状态
§34 模型缺失提示	`ModelMissingModal.vue`	启动/切对话/触Skill	download / skip / never_prompt
§35 快捷键速查	—	—	Enter/Shift+Enter/Esc×3/Ctrl+Shift+A
§36 设置中心	`SettingsCenter.vue`	TitleBar ⚙️ / Desktop 设置图标	LLM连接/后台/通知/Skill管理/关于

§1 启动与运行模式

开发态启动

bash

# 后端依赖（首次）
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 启动桌面端（前端 + 自动拉起后端 bridge）
cd electron
npm run electron:dev

数据流：Electron 主进程 (electron/electron/main.js) 创建 BrowserWindow → electron/electron/python.js spawn .venv\Scripts\python -m src.bridge.run → bridge 绑定 127.0.0.1:18711（hypercorn + HTTPS/2 + 自签证书 workspace/.bridge.crt） → 前端通过 https://127.0.0.1:18711 访问 REST API + WebSocket。

端口 fallback：如果 18711 被占用，python.js 调用 pickFreePort() 选空闲端口，写入 workspace/.bridge.port + workspace/.bridges.json。

鉴权：bridge 启动时生成 workspace/.bridge_token，BridgeTokenMiddleware 校验每个请求的 X-Bridge-Token header。WebSocket accept 也校验 token。

两种运行模式：

前台模式（默认）：关闭主窗口 → 退出整个进程。
后台模式：关闭主窗口 → bridge 进程仍在。定时任务、提醒、桌面通知、消息监听继续工作。

生产构建：cd electron && npm run electron:build → 产物在 electron/dist/。

CLI（免 UI 驱动 bridge）：python main.py --help → 覆盖全部 REST 端点的命令行。它不启动 bridge，只是给正在运行的 bridge 发请求。token 自动从 workspace/.bridge_token 读取。

§2 主窗口布局总览

┌─────────────────────────────────────────────────────────────┐
│ TitleBar (28px, 粉色背景)                                    │
├──────┬──────────┬───────────────────────────────────────────┤
│Agent │ Dialog   │ ChatStage (消息流 + 工具卡片)              │
│Rail  │ List     │                                           │
│(60px)│(240px)   │                                           │
│      │          │                                           │
│      │          ├───────────────────────────────────────────┤
│      │          │ InputBar (附件/Skill/快捷输入/文本/语音)   │
├──────┴──────────┴───────────────────────────────────────────┤
│ (可选) StatusOverlay — 右上角贴边浮窗                        │
└─────────────────────────────────────────────────────────────┘

组件映射：

标题栏 → TitleBar.vue（28px 高，var(--pink-frame) 背景）
AgentRail → AgentRail.vue（60px 宽，可折叠到 0）
DialogList → DialogList.vue（240px 宽，可折叠）
ChatStage → ChatStage.vue（弹性宽度）
InputBar → InputBar.vue（固定在 ChatStage 底部）

交互：

列间 ResizeHandle.vue 可拖动调整宽度，持久化到 localStorage
每列顶部有折叠按钮（小箭头图标），点击折叠/展开
三连 Esc（1.5 秒内 3 次）→ 依次关闭：树全屏 → 分屏 → 设置弹窗 → 中断生成 → 回到主页

§3 标题栏 TitleBar

组件：TitleBar.vue

布局：

左侧（身份区）：UserAvatar (18px) + 用户昵称（store.userProfile.nickname）。点击 → 打开 UserProfileModal（§29）
中间：-webkit-app-region: drag 拖拽区（整个标题栏可拖动窗口）
右侧（窗口控件）：
- 📌 置顶 (pin)：api.togglePin() → 窗口固定最上层。激活态 on class（蓝色高亮）
- — 最小化：api.minimize()
- □ 最大化/还原：api.maximizeToggle() → 图标动态切换 maximize/restore
- × 关闭：api.close() → 前台模式=退出，后台模式=隐藏窗口

数据流：TitleBar.vue 通过 window.electronAPI.window IPC 与 Electron 主进程通信。onMounted 时调用 api.state() 获取初始 pinned/maximized 状态，并订阅 api.onState 监听变化。

§4 管理员主页 Desktop

组件：Desktop.vue（替代旧版 ManagerLanding.vue）

入口：选中 AgentRail 顶部 Agent 管理员（id=0） 且未选具体对话时显示。

切换回旧版：localStorage.setItem('familiars:legacyLanding','1') → 刷新 → ManagerLanding.vue。

布局：壁纸 + 图标网格 + 底部任务栏

内置应用图标（BASE_APPS 数组，定义在 Desktop.vue 第 63-100 行）：

id	标题	图标来源	打开组件	窗口尺寸
`report`	汇报 report	`entry-image:report`	`ReportApp.vue`	900×620
`learn`	了解 Familiars	`entry-image:learn`	`LearnApp.vue`	940×640
`workshop`	创意工坊	`entry-image:lab_researcher`	`WorkshopApp.vue` → `CreativeWorkshop.vue`	1300×780
`demo`	复刻 DEMO	`entry-image:demo`	`DemoApp.vue` (comingSoon)	640×440
`tasks`	待办·日程·定时	`entry-image:flipping_desk_calendar`	`TodoScheduleModal.vue` (embedded)	960×640
`settings`	设置	`entry-image:workshop`	`SettingsCenter.vue` (embedded)	880×620
`monitor`	消息监听	`entry-image:checking_surveillance_camera`	`MonitorApp.vue`	520×620
`apps`	应用商场	`entry-image:figure_shopping_bag`	`AppsApp.vue`	1000×660
`cg-workshop`	CG 动画工坊	`local-image:/cg-workshop-cover.png`	`CgWorkshopApp.vue`	700×560
`agent-workshop`	Agent 工坊	`local-image:/agent-workshop-cover.png`	`AgentWorkshopApp.vue`	700×560
`skill-workshop`	技能调用工坊	`local-image:/skill-workshop-cover.png`	`SkillWorkshopApp.vue`	700×560
`skill-approvals`	Skill 改动审批	`local-image:/skill-approvals-cover.png`	`SkillApprovalsApp.vue`	700×560

Broker 应用图标：AppsApp.vue 列出的已安装 broker 也出现在桌面，每个 broker 的 cover.png 作为图标。双击 → BrokerAppWindow.vue（iframe 加载 /api/broker_app/<id>/ui/<entry>）。

操作：

双击图标 → 打开浮动窗口（WindowManager 管理，可拖动/最小化/最大化/关闭）
长按或右键图标 → 位置调整 / 卸载（仅第三方 broker 图标）
空白处右键 → 换壁纸、整理图标
底部任务栏 → 列出已打开/最小化的窗口，点击恢复

首次启动横幅：若后台自启注册失败，主页顶部出现"自启注册失败，点此重试"横幅 → 点重试或 不再提示。

§5 Agent 列表（AgentRail）

组件：AgentRail.vue

位置：最左列，60px 宽

操作：

+ 新的 agent：顶部按钮 → 打开 CreateAgentModal（§6）
点击头像：切换到该 agent 的对话（store.selectAgent(id)）
右键/长按：打开操作菜单（在 Agent 设置里完成）
折叠/展开：顶部箭头按钮。折叠后只剩头像（32px 宽）
创建中占位：半透明占位块 + LoadingSpinner.vue，鼠标悬浮可看错误详情

排序：管理员 agent（id=0）永远在最顶部，其余 agent 按最近活动时间排序。

角标：

🎁 礼物徽章：agent.gift_pending === true → 头像右上角金色角标（§17 GiftBox）
⏰ 闹钟图标：agent 正在执行定时任务
红色边框：intense_mode 开启（§7）
橙色边框：turbo_mode 开启（§7）

§6 新建 Agent（CreateAgentModal）

组件：CreateAgentModal.vue

入口：AgentRail 顶部 + 新的 agent 按钮

数据流：

用户填写表单 → 点创建
前端 POST /api/agents → 后端 src/bridge/routes/agents.py:create_agent
后端创建 workspace/agents/agent_<id>/ 目录 + config.json
异步任务：生成 voice.wav（parler TTS）/ figure.png / 报告模板
AgentRail 显示半透明占位块 → 完成后刷新为新头像

表单字段：

名称（必填）：展示名，也作为 workspace/agents/agent_N/ 的目录展示名
职责描述：自然语言描述 agent 定位
身份：写入 IDENTITY.md
头像（可选）：上传 ≤2MB 图片 → 作为 portrait 用于普通头像 + 数字人静态底图

变体：CreateAgentKindModal.vue 提供创建方式选择（空白 / 从模板 / 从外部导入）。

§7 Agent 设置（AgentSettings）

组件：AgentSettings.vue（右侧抽屉面板）

入口：AgentRail 上选中 agent 后 → 标题栏设置按钮或 agent 右键

功能分区：

字段	类型	默认值	说明
昵称	文本	—	agent 的名字
上下文窗口	数字	5	直接对话历史窗口大小（`SLIDE_WINDOW_SIZE`）
对话模型	文本	`DEFAULT_MODEL`	为此 agent 配置特定模型
工作目录	路径	`/workspace`	agent 处理该目录下文件不需审批
intense_mode	开关	关	无人监管模式：默认通过所有审批 + 不向用户求助。头像出现红色边框
turbo_mode	开关	关	完全授权模式：默认通过所有审批 + 仍可求助。头像出现橙色边框
security_level	下拉	—	三档审批等级，只有权限要求 ≥ 此等级的工具才需审批
verify_plan	开关	关	计划审批：agent 制定计划后先递交用户审阅
SKILL改动自动应用	开关	关	manager 修改 SKILL.md 不需用户同意
need_initiative	开关	关	允许 agent 主动设置监听任务/主动联系用户
头像底色	颜色选择	—	AgentRail 头像底色
对话列表文字颜色	颜色选择	—	DialogList 条目文字颜色
对话气泡文字颜色	颜色选择	—	ChatBubble 文字颜色
替换形象	文件上传	—	上传图片替换数字人资产
重新生成语音	按钮	—	基于 `IDENTITY.md` 声音描述，用 parler 重新合成 `voice.wav`（1-3 分钟）
替换声音	文件上传	—	上传音频替换 agent 声音
删除此 agent	按钮	—	删除 agent 目录下所有资产（数字人/聊天/记忆/知识库/SKILL）

数据流：修改后 PATCH /api/agents/<id> → src/bridge/routes/agents.py:patch_agent → 写入 config.json。删除走 DELETE /api/agents/<id> → 整个目录递归删除。

§8 对话列表（DialogList）

组件：DialogList.vue

位置：第二列，240px 宽

操作：

+ 新的话题：列表顶部 + 按钮 → POST /api/dialogues → 新建对话
切换对话：点击条目 → store.selectDialogue(id) → ChatStage 加载该对话
重命名：双击对话标题 → 进入编辑态 → 回车保存（PUT /api/dialogues/<id>）/ Esc 取消
删除：右侧悬浮 🗑 图标 → 确认 → DELETE /api/dialogues/<id>
折叠：顶部箭头折叠整列

manager 虚拟对话（仅 agent 0 的列表）：

名称	dialogue_id	打开组件
CG 动画工坊	-1001	`CgWorkshop.vue`
Agent 工坊	-1004	`AgentWorkshop.vue`
技能调用工坊	-1002	`SkillWorkshop.vue`
SKILL 改动审批	-1003	`SkillApprovalsView.vue`

这些虚拟对话不计入"真实对话"数。

§9 对话舞台 ChatStage

组件：ChatStage.vue

位置：最右侧大区域

顶部条

当前 agent 名 + 状态指示
局部搜索：在当前会话中模糊搜索关键词，高亮命中
多选：进入消息多选模式 → 顶部出现批量操作条 → 可触发 SkillForge（§19）或导出 HTML/Markdown/PDF
对话设置：打开 ChatSettings.vue（§30）
打开到新窗口：将当前对话拆分为独立 BrowserWindow
分屏：打开 SplitPane → 左右对比查看两处对话
删除对话：删除当前对话
回到主界面：返回 Desktop

消息流

用户气泡（右）：ChatBubble.vue 渲染
agent 气泡（左）：左侧带 Avatar.vue
每条消息可：
- 点复制 → 全量复制到剪贴板
- 点朗读 → 数字人朗读（/api/dh/speak）
- 点 重新生成 → 重新回答
- 点翻译 → 翻译为设置的语言
- 点编辑 → 直接编辑消息内容
- 点删除 → 删除该消息及其子树
- 点 @ → 选定某个模型回答（TODO）

特殊消息卡片

卡片	组件	触发条件
礼物	`GiftBox.vue`	agent 发 gift payload
隐私审批	`PrivacyApprovalCard.vue`	敏感内容被检测到
AskUser	`AskUserCard.vue`	agent 调 `ask_user` 工具
计划审批	`PlanApprovalCard.vue`	verify_plan 开启时
事件等待	`EventWaitCard.vue`	等待外部事件
工具调用	`ToolRendererCard.vue`	agent 调工具时
CG 视频	覆盖层	agent 进入特定 skill 时

§10 对话树视图

组件：TreeMini.vue（缩略图）+ TreeFull.vue（全屏）

入口：ChatStage 角落的小型树缩略图（TreeMini）。双击 → 全屏（TreeFull）。

数据模型：Familiars 把每次问答存为 DialogTree 上的 Node（src/utils/memory_tools.py）。每个 Node 有 embedding（BAAI/bge-m3），支持向量检索。

TreeFull 操作：

拖动节点到空白：改变布局位置（不改变父子连线）
拖动节点到其他节点：将被拖动节点的父节点设置为目标节点
右键 → 删除子树：删除该节点及其所有后代
清空节点位移：还原为默认布局
搜索框：高亮检索命中的节点
导出：导出整棵树为 HTML
退出：三连 Esc 或顶部 × 按钮
放大/缩小：调整全图缩放比例

§11 输入栏 InputBar

组件：InputBar.vue

位置：ChatStage 底部

元素（从左到右）：

按钮	功能	数据流
📎 附件	弹出菜单 → 选文件	文件读为 `attachments[]`，发送时作为消息附件
📂 文件夹	弹出菜单 → 选文件夹	整个文件夹路径作为附件
🧩 执行 Skill	打开 Skill 列表	选中后弹出参数表单 → `POST /api/skills/run`
📚 引用知识库	打开 KB 列表 + 预览	chip 添加到消息 → agent RAG 阶段感知
⚡ 快捷输入	打开快捷面板	见 §13
@ 选择模型	打开模型列表	临时为下条消息指定模型
📝 文本框	多行输入	`Enter` 发送，`Shift+Enter` 换行
🎙️ 麦克风	push-to-talk	见 §14
➤ 发送	发送消息	`POST /api/chat/send` → SSE 流式回复

附件 chip：每个附件显示文件名，悬浮看路径，点 × 移除。图片/视频/音频在气泡内直接渲染。

§12 附件与文件渲染

组件：AttachmentRenderer.vue

渲染规则（按 kind 字段）：

kind	渲染方式
`image`	内联缩略图 → 点击放大（lightbox）
`video`	内联 `<video controls>`
`audio`	内联 `<audio controls>`
`link`	超链接（外部浏览器打开）
`file`	文件卡片：📄 文件名 + 打开 + 在文件夹中显示

底层协议：app-file:// 自定义协议读取本机绝对路径（避免 file:// 被 webSecurity 阻止）。Electron 主进程注册 protocol.registerFileProtocol('app-file', ...)。

§13 快捷输入 / 模型选择 / 技能与知识库引用

快捷输入（quick inputs）

点 ⚡ 打开菜单
顶部输入框 → 回车保存新短语
点已有短语 → 拼接到输入框末尾（不替换）
每个短语右侧 × 删除
持久化到 workspace/.quick_inputs.json

@ 模型选择

点 @ 打开模型列表
选中后输入栏出现 @模型名 chip
仅作用于"下一条"消息（发送后自动清除）
旁边 × 清除选择

Skill / 知识库引用

🧩 打开 Skill 列表 → 选中 → 参数表单
📚 打开 KB 列表 → 选中 → chip 添加到消息
agent 在 RAG 阶段感知这些上下文锚点

§14 语音输入（push-to-talk）

入口：InputBar 右下角 🎙️ 麦克风按钮

数据流：

点一下 → 红色脉冲 → MediaRecorder API 开始录音
再点一下 → 停止录音 → 按钮变忙碌态 + 标题提示"正在识别…"
POST /api/asr/transcribe（multipart audio）→ 本地 faster-whisper 单例推理
返回文本 → 自动追加到输入框（不清空已有文字）

错误处理：

麦克风权限被拒绝 → 提示检查浏览器权限
当前浏览器不支持录音 → 提示浏览器版本
识别失败：… → 显示具体错误

隐私：音频仅在本机推理，不上传外部服务。转写文本可能随下一轮对话上行到云端 LLM。

§16 数字人 DigitalHuman

组件：DigitalHuman.vue

入口：ChatStage 顶部 👤 切换按钮

数据流：

启用 → WebSocket 连接 /ws/digital_human/<agent_id>
agent 说话时 → TTS 生成音频 → wav2lip 模型驱动嘴形
实时帧叠加在静态 figure.png 之上

三态渲染（依据资产情况）：

条件	渲染
有 `figure.png` + `bust_loop.webp`	正常显示动画 + 实时帧叠加
外部 agent 无形象	emoji 占位（🦞/🐎），layout 不变
本地 agent 无形象	默认 bot 形象占位

资产缺失：缺 voice.wav 或 voice_ref.txt → 按钮区红色提示 → 引导到 AgentSettings（§7）。

§18 汇报 Report

组件：ReportApp.vue（Desktop 桌面应用）

入口：Desktop → 汇报图标

功能：

聚合所有 agent 的日/周/月/年报告
按时间线展示
右上角 重新生成 按钮 → manager 重新总结

单个 agent 报告：在 AgentSettings（§7）内查看。

报告文件位置：workspace/agents/agent_<id>/reports/ 下按日期组织。

§19 技能锻造 SkillForge

组件：SkillForgeModal.vue

入口：ChatStage 多选消息（Shift/Ctrl）→ 顶部批量操作条 → 锻造 Skill

后端 API（`src/bridge/routes/skill_forge.py`）

端点	阶段	说明
`POST /api/skills/forge/from-dialogue/derive_io`	Phase 1	一次 LLM 调用推导 inputs/outputs/trigger
`POST /api/skills/forge/from-dialogue/propose`	Phase 1（完整版）	rewrite + tool_select + denoise + params + mock + summary
`POST /api/skills/forge/from-dialogue/repropose`	Phase 1 重提	用户锁定 I/O 后重新生成 summary
`POST /api/skills/forge/from-dialogue/build_and_preview`	Phase 2	完整链：denoise + tool_select + params + mock + summary + generate + validate + repair
`POST /api/skills/forge/preview`	Phase 2（旧）	生成 SKILL.md + 验证
`POST /api/skills/forge/revise`	修订	agent 模式：read/grep/edit/validate/finish 工具循环
`POST /api/skills/forge/commit`	提交	持久化 SKILL.md + 刷新 registry

3 步向导

Step 1 — params（参数确认）

前端 POST /derive_io → 后端一次 LLM rewrite → 解析 intent 的 INPUTS: / OUTPUTS: / TRIGGER: 行
显示三个可编辑区域：输入列表 / 输出列表 / 触发场景
每行 {name, type, description}，可增删改
用户改动后出现浮动按钮：
- ✕ 撤回：恢复 LLM 原稿
- ✓ 应用：POST /repropose → 后端用锁定的 I/O 重新生成 summary
确认 I/O 后进入下一步

Step 2 — review（审阅）

前端 POST /build_and_preview → 后端跑完整链 → 返回 skill_md + errors
显示完整 SKILL.md 预览（markdown 渲染）
可编辑 skill_id、scope（global/agent/recipe）、overwrite
若有 errors，红色列表展示（input_missing / output_missing / script_still_invalid）
可输入 user_guidance → POST /revise → agent 模式修订

Step 3 — commit（提交）

点提交 → POST /commit → 写入 workspace/skills/<skill_id>/SKILL.md（或 agent/recipe scope）
刷新 skill_registry.json
完成后 → 下次输入栏 🧩 菜单可见新 Skill

数据流：整个 forge 过程后端无状态（无 session map），每个 POST 自包含。前端持有所有中间状态。

§20 Skill 改动审批 SkillProposals

组件：SkillApprovalsView.vue

入口：Desktop → Skill 改动审批 图标

后端：src/bridge/routes/skill_proposals.py

API 端点

端点	说明
`GET /api/skill_proposals`	列出所有待审批提案（不含 body，只发元数据）
`GET /api/skill_proposals/count`	待审批数量（用于 badge）
`GET /api/skill_proposals/<pid>`	完整提案（含 body，用于 diff 展示）
`POST /api/skill_proposals/<pid>/approve`	批准 → 写入 `workspace/skills/`
`POST /api/skill_proposals/<pid>/reject`	拒绝 → 归档到 `rejected/`

界面

每条提案显示：来源 agent、skill_id、target_path、created_at、trigger
展开后显示 diff（current_body vs proposed_body）
批准 → approve_proposal(pid) → 落地 SKILL.md
拒绝 → 可填 reason → reject_proposal(pid, reason)
稍后 → 留在列表

触发条件：agent 的 skill_auto_apply=False 时，agent 的 SKILL 修改进入审批队列（workspace/manager/skill_proposals/）。

§21 待办 / 日程 / 定时任务 TodoScheduleModal

组件：TodoScheduleModal.vue

入口：Desktop → 待办·日程·定时 图标 / 标题栏快捷入口

三个标签：

Todo 标签

列表展示所有未完成 + 已完成
每项：标题、内容、截止时间（可空）、紧急程度（1-5）、是否需要提醒
新建 todo：表单 → 点添加 → POST /api/todos
完成/取消：勾选框 → PATCH /api/todos/<id>
删除：行末 × → DELETE /api/todos/<id>
frequency：简单重复模式（daily/weekly/monthly）

Schedule 标签

周视图：横轴 7 天，纵轴时间，事件块按起止绘制
月视图：每个格子是当天事件标题清单
顶部箭头切换周/月
点空白格 → 新建日程
点事件块 → 编辑/删除/完成
同样支持紧急级、提醒、frequency

Cron 标签

显示所有 agent 的 cron：勾选后看其他 agent 的定时任务
新建/编辑/删除任务
cron 表达式格式：5 段标准（分时日月周）

§22 全局快捷草稿

组件：DraftConfirmModal.vue

入口：全局快捷键

快捷键	行为
`Ctrl+Shift+A`	自动判断（auto）：LLM 决定是 todo 还是 schedule
`Ctrl+Shift+S`	强制建为日程
`Ctrl+Shift+T`	强制建为待办

数据流：

用户 Ctrl+C 复制文本
按快捷键 → Electron 主进程读剪贴板 → POST /api/draft/parse
后端 LLM 解析为结构化待办/日程 → 返回 DraftConfirmModal
弹窗展示：标题/内容/时间/紧急程度 → 可改 → 确认入库 / 取消

空剪贴板：右上角提示 剪贴板为空,请先选中文本复制(Ctrl+C)再按快捷键。

§23 提醒 ReminderToast

组件：ReminderToast.vue

位置：右上角悬浮卡片

来源：

schedule 类：到点提醒
todo 类：截止前 N 分钟提醒
desktop 类：agent 主动派发的桌面提醒

每张卡片：

顶部图标 + agent 头像
标题 + 正文（支持 markdown）
按钮：完成（仅 todo/schedule）/ 稍后（5min/30min/1h/1d/自定义）/ 关闭
自动消失（默认数分钟）或点关闭

OS 通知：进入后台/窗口失焦时，提醒还以系统原生通知弹出：

Windows：WinRT ToastNotification（优先级 High 穿透勿扰模式）
macOS：osascript Notification Center
点系统通知 → 聚焦回主窗口

§24 隐私脱敏审批 PrivacyApprovalCard

组件：PrivacyApprovalCard.vue

触发：agent 工具产物或上传文件被识别出敏感内容 → 特殊气泡卡片插入对话

检测层：gitleaks → Presidio → 小模型（三_pass 流水线，src/tools/sensitive_detector.py）

每条 finding：

显示 kind（凭据/PII/自定义）、探测层、上下文片段、原文
三选一：
- ignore：放行原文
- mask：掩码替换（默认密文预览）
- record：原文落库但加密（src/base/crypto.py Fernet）
上方 显示密文预览 切换
全部选完 → 点确认一次性提交

§25 AskUser 卡片

组件：AskUserCard.vue

触发：agent 在 tool 阶段调用 ask_user 工具

界面：

主问题加粗居中
agent 给了候选项 → 按钮 chip：点 chip → 预填到下方文本框
文本框获焦 → 回车提交 / Esc 关闭

数据流：回答 → POST /api/communication/event_responses/<rid> → 作为下一轮 user 消息回到对话循环。超时默认 ASK_USER_TIMEOUT（可配）。

§26 CG 动画工坊 CgWorkshop

组件：CgWorkshop.vue

入口：Desktop → CG 动画工坊 图标

功能：为某个 agent 的某个 skill 生成片头 CG 视频

操作步骤：

左列选 agent（必须已生成 figure.png）
中列选该 agent 的某个 skill（已绑 CG 的有 ✅ 标记）
右列填 提示文本（可选 LLM 优化）
点 生成 CG → manager 运行 generate_cg skill → 工坊页面上方播放进度
完成后预览 mp4
不满意 → 重新生成 / 删除

资产位置：workspace/agents/agent_<id>/cg/<skill_id>.mp4

§27 Agent 工坊 AgentWorkshop

组件：AgentWorkshop.vue

入口：Desktop → Agent 工坊 图标

三种来源：

类型	说明	前置条件
🦞 OpenClaw	Node.js 个人助手（WhatsApp/飞书/微信）	Node ≥22
🐎 Hermes	Nous Research Python/uv runtime	uv
🧩 自定义	OpenAI 兼容协议 agent 项目	仓库地址 + 启动命令

向导流程：

选类型 → 显示前置条件
填模型/仓库/启动命令
SSE 实时显示安装日志（断网/换页再回来自动续上）
完成后 → 外部 agent 出现在 AgentRail，可像本地 agent 一样对话

§28 消息监听 Monitor

组件：MonitorApp.vue

入口：Desktop → 消息监听 图标

支持平台（同时只能启用一个）：

平台	实现
微信 monitor	3.9 走 UIA；4.0 走 vision `operate()`
QQ monitor	vision `operate()`

操作：

行末 开始/停止 按钮：启停 monitor
联系人：输入框填目标（QQ id / 微信 filehelper 名），回车保存（运行中不可改）

消息路由：监听到的消息 → manager/对应 agent 身份 → Familiars 内对应名称的对话。

特殊指令（在自己的聊天中发送）：

@管理员 → 查看 agent 列表及 id
@管理员 <task> → 管理员分配任务给最适合的 agent
@<id> <task> → 指定 agent 完成任务
#文件<number> → 附带文件发送

约束：agent 上一任务完成前不接受下一个任务。

§29 个人信息 UserProfileModal

组件：UserProfileModal.vue

入口：TitleBar 左上角身份区点击

字段：

昵称：编辑后失焦自动保存。为空 → 弹错并还原
头像：点头像 → 选本地 ≤2MB 图片上传
自我介绍整合：文本框 → 作为 agent 了解用户的依据（写入 workspace/USER.md）

§30 背景图 / 主题 / Chat 设置

ChatSettings：ChatStage 顶部 ⚙️ → 当前对话级设置

字体、字号、聊天背景、是否置顶
对话模型、温度

BackgroundSettingsModal：通过事件 open-background-settings 触发

配置 chat 区域的背景图、透明度、虚化等视觉效果

§31 后台运行与开机自启

组件：SettingsCenter.vue → 后台运行标签

入口：TitleBar ⚙️ / 系统托盘

功能：

后台运行开关：开启 → 关闭主窗口后 bridge 进程不退出
开机自启：Win: 启动文件夹快捷方式 / macOS: launchd plist
状态显示：当前是否运行、PID、已运行多久
退出后台：彻底退出（释放 GPU 显存 3-4GB）→ 二级确认防误点

§32 系统托盘 Tray

入口：后台运行时，托盘图标常驻

操作：

双击图标：显示主窗口
右键菜单：
- 显示主窗口
- 后台运行（勾选框，切换弹二级确认）
- 状态: 运行中 · PID xxx · 已运行 yyy（只读）
- 退出后台 (彻底关闭)（红色项，弹二级确认）

tooltip：实时显示后台状态（每 30s 刷新）

§33 状态浮窗 StatusOverlay

组件：StatusOverlay.vue

入口：URL ?view=overlay（主进程自动管理）

特性：独立窄窗口，右上角贴边，点击穿透，不抢焦点

状态级别（由 src/observability/status.py 广播到 /status/stream SSE）：

level	触发源	颜色	含义
`operate`	`base_tools.py:_set_status("operate",…)`	红	agent 正通过 `operate()` 接管鼠标/键盘/屏幕
`monitor`	`monitor.py` 预启动	橙	打开客户端、检测登录
`monitor_active`	monitor poll 循环	红	正在读屏/抢焦点
`monitor_dispatching`	monitor 暂停 poll	紫	正在为 `@` 触发跑 chat
`train`	尚未触发	紫	训练态占位
`info`	手动 `POST /status/dev/set`	蓝	调试/其他

交互：默认全程鼠标穿透。有 monitor 条时 → 可交互，⏹ 按钮可点击立即停止。

§34 模型缺失提示 ModelMissingModal

组件：ModelMissingModal.vue

触发：启动/切对话/触发 skill 时，所需本地模型未下载

界面：每条缺失模型一行，四个选择：

download：现在下载（弹出进度）
skip：跳过（功能降级 fallback）
never_prompt：以后都不再提示，永远 fallback
取消：保留 modal

提交后：自动重试当前操作。

§35 全局快捷键速查

键位	作用	范围
`Enter`	发送消息	InputBar 内
`Shift+Enter`	换行	InputBar 内
`Esc ×3`（1.5s 内）	中断/关闭分屏/关闭树/回主页	主窗口
`Ctrl+Shift+A`	剪贴板 → 自动建草稿	全局
`Ctrl+Shift+S`	剪贴板 → 建日程	全局
`Ctrl+Shift+T`	剪贴板 → 建待办	全局

§36 设置中心 SettingsCenter

组件：SettingsCenter.vue

入口：

TitleBar ⚙️ 按钮
Desktop → 设置图标
任何地方派发 open-settings-center 自定义事件

侧边栏分区：

分区	内容
LLM 连接	BASE_URL / API_KEY / DEFAULT_MODEL / FAST_MODEL / transport_mode(hybrid/streaming) / auto_fallback / 可选 per-model override (base_url/api_key)
后台运行	后台开关、开机自启、PID、已运行时长、退出后台（二级确认）
通知	占位（未来全局通知路由设置）
SKILL 管理	内联 `SkillManagerPanel.vue`（查看/编辑/删除/重写 SKILL）
关于	客户端版本、bridge host/port

LLM 连接数据流：

用户编辑 draft → 点保存
POST /api/settings/llm → 后端写入 .env
后端 probe 检测连接 → 返回 responses_api / transport / ping 结果
前端显示成功/失败 + 模型协议信息

与其他设置的区别：

SettingsCenter = 全局设置
AgentSettings（§7）= 单 agent 设置
ChatSettings（§30）= 单对话设置

演示视频约定

OPERATION 每节末尾都有 docs/videos/NN-<slug>.mp4 占位。录制后放到该路径即可，无需改文档（建议 ≥720p、≤90s）。

唯一权威：仓库根 OPERATION.md（§1–§42 完整）。工坊与管线章节见工坊手册 / 管线与流。

通用手册 ​

快速导航 ​

§1 启动与运行模式 ​

开发态启动 ​

§2 主窗口布局总览 ​

§3 标题栏 TitleBar ​

§4 管理员主页 Desktop ​

§5 Agent 列表（AgentRail） ​

§6 新建 Agent（CreateAgentModal） ​

§7 Agent 设置（AgentSettings） ​

§8 对话列表（DialogList） ​

§9 对话舞台 ChatStage ​

顶部条 ​

消息流 ​

特殊消息卡片 ​

§10 对话树视图 ​

§11 输入栏 InputBar ​

§12 附件与文件渲染 ​

§13 快捷输入 / 模型选择 / 技能与知识库引用 ​

快捷输入（quick inputs） ​

@ 模型选择 ​

Skill / 知识库引用 ​

§14 语音输入（push-to-talk） ​

§16 数字人 DigitalHuman ​

§18 汇报 Report ​

§19 技能锻造 SkillForge ​

后端 API（src/bridge/routes/skill_forge.py） ​

3 步向导 ​

§20 Skill 改动审批 SkillProposals ​

API 端点 ​

界面 ​

§21 待办 / 日程 / 定时任务 TodoScheduleModal ​

Todo 标签 ​

Schedule 标签 ​

Cron 标签 ​

§22 全局快捷草稿 ​

§23 提醒 ReminderToast ​

§24 隐私脱敏审批 PrivacyApprovalCard ​

§25 AskUser 卡片 ​

§26 CG 动画工坊 CgWorkshop ​

§27 Agent 工坊 AgentWorkshop ​

§28 消息监听 Monitor ​

§29 个人信息 UserProfileModal ​

§30 背景图 / 主题 / Chat 设置 ​

§31 后台运行与开机自启 ​

§32 系统托盘 Tray ​

§33 状态浮窗 StatusOverlay ​

§34 模型缺失提示 ModelMissingModal ​

§35 全局快捷键速查 ​

§36 设置中心 SettingsCenter ​

演示视频约定 ​

通用手册

快速导航

§1 启动与运行模式

开发态启动

§2 主窗口布局总览

§3 标题栏 TitleBar

§4 管理员主页 Desktop

§5 Agent 列表（AgentRail）

§6 新建 Agent（CreateAgentModal）

§7 Agent 设置（AgentSettings）

§8 对话列表（DialogList）

§9 对话舞台 ChatStage

顶部条

消息流

特殊消息卡片

§10 对话树视图

§11 输入栏 InputBar

§12 附件与文件渲染

§13 快捷输入 / 模型选择 / 技能与知识库引用

快捷输入（quick inputs）

@ 模型选择

Skill / 知识库引用

§14 语音输入（push-to-talk）

§16 数字人 DigitalHuman

§18 汇报 Report

§19 技能锻造 SkillForge

后端 API（`src/bridge/routes/skill_forge.py`）

3 步向导

§20 Skill 改动审批 SkillProposals

API 端点

界面

§21 待办 / 日程 / 定时任务 TodoScheduleModal

Todo 标签

Schedule 标签

Cron 标签

§22 全局快捷草稿

§23 提醒 ReminderToast

§24 隐私脱敏审批 PrivacyApprovalCard

§25 AskUser 卡片

§26 CG 动画工坊 CgWorkshop

§27 Agent 工坊 AgentWorkshop

§28 消息监听 Monitor

§29 个人信息 UserProfileModal

§30 背景图 / 主题 / Chat 设置

§31 后台运行与开机自启

§32 系统托盘 Tray

§33 状态浮窗 StatusOverlay

§34 模型缺失提示 ModelMissingModal

§35 全局快捷键速查

§36 设置中心 SettingsCenter

演示视频约定