界面导览

交互式走一遍 Familiars 的主界面。本文聚焦"哪块在哪、能干什么"，完整操作细节见 用户手册。

一、主窗口布局总览

┌────────────────────────────────────────────────────────────────┐
│ TitleBar（标题栏：身份芯片 / 拖拽区 / 置顶 / 最小化 / 最大化 / 关闭）│
├──────────┬─────────────┬───────────────────────────────────────┤
│ AgentRail│ DialogList  │ 主内容区（Desktop 桌面壳 / ChatStage）│
│ ·列表    │ ·对话列表    │ ┌──────────────────────────────────┐  │
│ ·+ 新建  │ ·+ 新对话    │ │ 桌面壳（Desktop.vue）           │  │
│ ·齿轮设置│ ·置顶对话    │ │ 或 聊天舞台（ChatStage.vue）    │  │
│          │ ·右键菜单    │ └──────────────────────────────────┘  │
│          │             │ 底部输入栏（InputBar）                 │
│          │             │ 右侧状态浮窗（StatusOverlay）          │
└──────────┴─────────────┴───────────────────────────────────────┘
│ 底部任务栏（Desktop 桌面壳模式下的 Taskbar）                       │
└────────────────────────────────────────────────────────────────┘

三栏结构

栏	组件	默认宽度	说明
AgentRail	`AgentRail.vue`	212px	Agent 列表，manager 固定置顶，其余按最近活跃排序
DialogList	`DialogList.vue`	212px	当前 agent 的对话列表，支持置顶、重命名、删除
主内容区	`Desktop.vue` / `ChatStage.vue`	自适应	桌面壳（manager 主页）或聊天舞台（agent 对话）

宽度可通过拖拽边缘调整（ResizeHandle），数值持久化到 localStorage。

二、标题栏（TitleBar）

文件：electron/renderer/src/components/TitleBar.vue

┌──────────────────────────────────────────────────────────┐
│ [我] (头像+昵称)    ←—— 可拖拽区 ——→    [📌][─][□][×] │
└──────────────────────────────────────────────────────────┘

元素	功能
身份芯片 `[我]`	点击打开 `UserProfileModal`，编辑用户画像（昵称、头像、偏好）
拖拽区	拖动窗口位置（`-webkit-app-region: drag`）
📌 置顶	窗口始终置顶（`setAlwaysOnTop`）
─ 最小化	最小化到任务栏
□ 最大化 / 还原	切换最大化状态
× 关闭	不退出应用——隐藏到系统托盘（`win.hide()`）；彻底退出用托盘菜单

关闭窗口 ≠ 退出。关闭后 Electron 进程仍运行，bridge 子进程保持活跃，托盘图标可见。右键托盘 → "退出后台 (彻底关闭)" 才真正退出。

三、Agent 列表（AgentRail）

文件：electron/renderer/src/components/AgentRail.vue

┌─────────────────┐
│ [manager]  ⚙   │  ← manager 固定置顶
│ [小助手]   ⚙   │
│ [客服]     ⚙   │
│ [分析师]   ⚙   │
│                 │
│      [+]        │  ← 新建 agent
└─────────────────┘

交互

操作	效果
点击 agent 行	进入该 agent 的聊天视图（`store.enterAgent`）
右键 agent 行	弹出菜单：设置 / 释放内存 / 删除
点击齿轮 ⚙	打开 `AgentSettings`（agent 专属配置）
点击 [+]	打开 `CreateAgentKindModal` → 新建 agent

Agent 行视觉

选中状态：theme_assets.selected 生成的渐变板 → vivid(theme_color) 饱和色 → 默认 CSS 高亮
创建中占位：PendingAgent 显示为半透明占位卡片，资产生成完成后替换为真实行
Demo 模式锁定：VITE_DEMO_MODE=1 时只剩 manager，新建按钮和齿轮禁用

Manager 特殊处理

Manager（agent 0/1）的齿轮不打开 AgentSettings，而是打开全局 SettingsCenter。

四、对话列表（DialogList）

文件：electron/renderer/src/components/DialogList.vue

┌─────────────────┐
│ 📌 周会准备  📌 │  ← 置顶对话
│ 📌 周报汇总     │
│ 日常闲聊        │
│ 数据分析任务     │
│                 │
│   [+ 新对话]    │
└─────────────────┘

交互

操作	效果
点击对话行	切换到该对话（`store.selectDialogue`）
双击对话行	重命名对话（`PromptModal`）
右键对话行	菜单：置顶 / 重命名 / 导出 / 删除
点击 [+ 新对话]	创建新对话（`dialogue_<n+1>/`）

置顶

前端置顶（localStorage 按 agent 存储：dlgpin:<agentId>）
置顶对话排在列表顶部，其余按最近消息排序
后端无 pinned 列，纯前端行为

过滤

自动过滤掉 manager 的合成工坊对话（cg_workshop / agent_workshop / skill_workshop / skill_approvals），这些对话已迁移到桌面壳的独立窗口。

五、桌面壳（Desktop.vue）

文件：electron/renderer/src/components/Desktop.vue

Desktop 是 manager 的默认主页（替代旧版 ManagerLanding），类似 OS 桌面：

┌──────────────────────────────────────────────────────────┐
│ 🖼 壁纸背景                                                │
│                                                           │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐               │
│  │汇报  │ │了解  │ │创意  │ │复刻  │ │待办  │               │
│  │report│ │Familiars│ │工坊  │ │DEMO │ │日程  │               │
│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘               │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐               │
│  │设置  │ │消息  │ │应用  │ │CG   │ │Agent │               │
│  │      │ │监听  │ │商场  │ │工坊  │ │工坊  │               │
│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘               │
│                                                           │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ [F] Familiars   [汇报] [了解] [创意工坊] [待办] ...   │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

内置应用（12 个）

图标	标题	组件	默认尺寸	说明
📊	汇报 report	`ReportApp.vue`	900×620	日报/周报/月报/年报管理
📖	了解 Familiars	`LearnApp.vue`	940×640	项目介绍与教程
🧪	创意工坊	`WorkshopApp.vue`	1300×780	Recipe / Flow 管理
🎮	复刻 DEMO	`DemoApp.vue`	640×440	即将推出（点击抖动）
📅	待办 · 日程 · 定时	`TodoScheduleModal.vue`	960×640	三合一 tab
⚙️	设置	`SettingsCenter.vue`	880×620	全局设置中心
📡	消息监听	`MonitorApp.vue`	520×620	WeChat/QQ/Feishu 监听状态
🛍	应用商场	`AppsApp.vue`	1000×660	Broker 市场 + 已安装应用
🎬	CG 动画工坊	`CgWorkshopApp.vue`	700×560	CG 动画生成
🤖	Agent 工坊	`AgentWorkshopApp.vue`	700×560	Agent 管理
🔧	技能调用工坊	`SkillWorkshopApp.vue`	700×560	Manager 长跑 skill 表单
✅	Skill 改动审批	`SkillApprovalsApp.vue`	700×560	Skill 提案审批队列

Broker 应用

每个已安装的 Broker（manifest.ui 块）自动成为桌面图标：

ID：broker:<broker_id>
图标：cover.png（broker 目录）
窗口：BrokerAppWindow.vue（iframe 加载 broker UI）
测试版标识：本地开发的 broker 显示金色「测试版」角标

窗口行为

双击图标：打开/恢复窗口
拖拽标题栏：移动窗口
双击标题栏：最大化/还原
拖拽右下角：调整大小
最小化：隐藏窗口但保留在任务栏
关闭：从桌面移除窗口（不退出应用）
任务栏点击：最小化 ↔ 恢复 ↔ 置顶

切换回旧版

设置 localStorage.familiars:legacyLanding = true 可切换回旧版 ManagerLanding.vue。

六、聊天舞台（ChatStage）

文件：electron/renderer/src/components/ChatStage.vue

ChatStage 是 agent 对话的主界面：

┌──────────────────────────────────────────────────────────┐
│ [← 返回]  小助手  [⚙ 设置]  [🔍 搜索]  [🌲 对话树]  [⫶ 分屏] │
├──────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [用户] 你好                                           │ │
│ │ [Agent] 你好！有什么可以帮你的吗？                     │ │
│ │ [工具调用] read_file(path="USER.md")                  │ │
│ │ [Agent] 我已经读取了你的用户画像...                   │ │
│ │ [隐私审批] 是否允许写入文件？ [允许] [拒绝]           │ │
│ └──────────────────────────────────────────────────────┘ │
│                                                           │
│ ┌──────────────────────┐ ┌────────────────────────────┐ │
│ │ [数字人面板]          │ │ [输入栏 InputBar]          │ │
│ │ (头像 / 表情 / 语音)  │ │ 文字 + 附件 + 语音 + 快捷 │ │
│ └──────────────────────┘ └────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

顶栏

按钮	功能
← 返回	回到桌面壳（manager 主页）
Agent 名称	显示当前 agent 名称 + 主题色
⚙ 设置	打开 `AgentSettings`
🔍 搜索	打开对话内搜索（`localSearchOpen`）
🌲 对话树	打开 `TreeMini` / `TreeFull`
⫶ 分屏	切换到分屏模式（左右双 pane）

消息区

ChatBubble：单条消息气泡（用户 / agent / 工具调用 / 审批卡）
工具调用卡片：展开显示工具名 + 参数 + 结果
PrivacyApprovalCard：隐私审批卡片（允许/拒绝）
PlanApprovalCard：计划审批卡片（确认/修改）
AskUserCard：agent 反问用户（ask_user_questions 工具）
EventWaitCard：等待外部事件（emit_event 工具）
CgWorkshop / AgentWorkshop / SkillWorkshop：合成工坊模式（替换消息区）

数字人面板

有 figure 的 agent：显示动画头像（DigitalHuman.vue）
外部导入 agent（openclaw / hermes / custom）：显示 emoji
本地 agent 无 figure：显示机器人吉祥物
分屏模式：隐藏两侧数字人面板

分屏模式

左 pane：主 agent（store.currentAgentId）
右 pane：split agent（store.splitAgentId）
每个 pane 独立的消息流、输入栏、数字人
AgentRail 点击在分屏聚焦模式下切换 split agent

导出

ChatStage 支持导出对话：

HTML：exportHTML()
Markdown：exportMarkdown()
PDF：exportPDF()

七、输入栏（InputBar）

文件：electron/renderer/src/components/InputBar.vue

┌──────────────────────────────────────────────────────────┐
│ 📎 [附件区]                                               │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ [🎤]  输入消息...                                     │ │
│ │                                                      │ │
│ │                              [快捷] [发送]            │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

输入模式

模式	触发	说明
普通文本	默认	直接打字，Enter 发送
附件模式	点击 📎	选择文件/文件夹（`pickFiles` IPC）
语音模式	点击 🎤	push-to-talk（faster-whisper ASR）
展开模式	技能表单 / 长文本	输入栏扩展为多行编辑器

Flow 绑定输入

当 agent 绑定 flow 模板（flow_template_id）时：

有自定义 renderer：整个输入区替换为 <CustomInputRenderer>
无 renderer 但有自定义字段：标准 textarea 下方追加 label+textbox 表单
保留字段（prompt / attachments）：始终使用内置控件

快捷输入

Ctrl+Shift+L：打开 QuickCreateModal（全局快捷）
Enter：发送消息
Shift+Enter：换行

八、对话树视图（TreeMini / TreeFull）

文件：

electron/renderer/src/components/TreeMini.vue
electron/renderer/src/components/TreeFull.vue

TreeMini（迷你视图）

显示在 ChatStage 右侧边栏
紧凑的树形结构，每条消息一个节点
点击节点跳转到该对话位置

TreeFull（全屏视图）

全屏 Canvas（VueFlow）
节点可拖拽、缩放、连线
右键菜单：跳转重放 / 设为当前 / 导出
支持分支可视化（对话树的多条路径）

节点类型

用户节点：蓝色气泡
Agent 节点：主题色气泡
工具调用节点：灰色卡片（工具名 + 参数摘要）
审批节点：黄色卡片（审批状态）

九、状态浮窗（StatusOverlay）

文件：electron/renderer/src/components/StatusOverlay.vue

悬浮在右上角的状态指示器：

┌──────────────────────────────┐
│ 🟢 monitor: 微信监听中       │
│ 🔴 operate: 正在操控电脑     │
│ 🟣 train: 模型训练中         │
│ 🟡 monitor_active: 消息轮询  │
└──────────────────────────────┘

状态级别

级别	颜色	说明
`operate`	🔴 红	agent 正在操控电脑（pyautogui / uiautomation）
`monitor`	🟡 黄	监听器预检（启动 / 登录检查）
`monitor_active`	🔴 红	监听器轮询中（读取屏幕消息）
`monitor_dispatching`	🟣 紫	监听器暂停，`generate()` 运行中（处理用户 @触发）
`train`	🟣 紫	模型训练中
`info`	🔵 蓝	一般信息

交互

点击 ⏹ 停止：停止对应监控/操控任务（POST /api/monitor/{key}/stop）
三重 Esc 中止：operate / monitor 激活时，连按三次 Escape 紧急中止
点击穿透：默认 overlay 窗口点击穿透（不影响桌面操作）；有 monitor 状态时切换为可交互

十、全局快捷键

Electron 全局（后台也可触发）

快捷键	功能	说明
Ctrl+Shift+L	快速创建	打开 `QuickCreateModal`（待办/日程/定时任务）
Ctrl+Shift+Q	快速问 Manager	打开浮动窗口与 agent 0 对话（`QuickAskView`）
Ctrl+Shift+I	开发者工具	切换 DevTools（`F12` 同样有效）
F12	开发者工具	同上
Esc × 3	紧急中止	仅在 `operate` / `monitor` 激活时有效

应用内快捷键

快捷键	功能	作用范围
Enter	发送消息	InputBar
Shift+Enter	换行	InputBar
Escape	关闭弹窗 / 取消操作	全局

快捷创建流程

在任何应用中选中文本
按 Ctrl+Shift+L
Electron 合成 Ctrl+C 抓取选区（快照 + 恢复剪贴板）
QuickCreateModal 弹出，预填抓取文本
选择类型（待办/日程/定时任务）
手动确认或交给 LLM 提取（DraftConfirmModal）

十一、待办/日程/定时任务（TodoScheduleModal）

文件：electron/renderer/src/components/TodoScheduleModal.vue

三合一 tab 界面：

┌────────────────────────────────────────┐
│  [待办]  [日程]  [定时任务]             │
├────────────────────────────────────────┤
│  ┌──────────────────────────────────┐  │
│  │ □ 买牛奶        截止: 07-05 18:00│  │
│  │ ☑ 写周报        已完成            │  │
│  │ □ 准备会议材料  截止: 07-06 09:00│  │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ 新建待办]                          │
└────────────────────────────────────────┘

待办（Todo）

标题 + 截止时间 + 优先级 + 状态
状态流转：待办 → 进行中 → 已完成
支持重复（每天/每周/每月）

日程（Schedule）

标题 + 开始/结束时间 + 地点 + 提醒
日历视图
支持重复规则

定时任务（Cron）

APScheduler cron 表达式
绑定 agent + prompt
触发时自动调用 generate()

快速入库

剪贴板快速入库：Ctrl+Shift+L → 粘贴文本 → LLM 提取结构化数据
对话创建：直接对 agent 说「每天早上 9 点提醒我 XXX」

十二、设置中心（SettingsCenter）

文件：electron/renderer/src/components/SettingsCenter.vue

一站式设置：

Tab	内容
模型	`BASE_URL` / `API_KEY` / `DEFAULT_MODEL` / `MANAGER_MODEL` / `EMBEDDING_MODEL` / `RERANKER_MODEL`
主题	主题色 / 暗色模式 / 字体大小
账号	用户画像（`USER.md`）/ 昵称 / 头像
隐私	`security_level` / `FAMILIARS_APPROVAL_DISABLED` / 敏感信息检测开关
后台	开机自启 / 守护进程 / 托盘行为
监听	WeChat / QQ / Feishu 监听配置
关于	版本号 / 更新检查 / 日志查看

十三、创意工坊（CreativeWorkshop）

文件：electron/renderer/src/components/CreativeWorkshop.vue

Recipe / Flow 管理：

┌────────────────────────────────────────┐
│  [概览]  [chain_1]  [chain_2]  [知识]  │
├────────────────────────────────────────┤
│  Recipe 列表                            │
│  ┌──────────────────────────────────┐  │
│  │ medical_triage    [编译] [干] [e2e]│  │
│  │ reverse_text      [编译] [干] [e2e]│  │
│  │ generate_image    [编译] [干] [e2e]│  │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ 新建 Recipe]                       │
└────────────────────────────────────────┘

Tab 结构

概览：manifest 摘要 + 状态
chain_group：每个 chain 的 graph 编辑器（VueFlow）
知识：knowledge/ 目录管理（AGENTS.md / SKILL.md / 外部 KB）
工具/技能：tools.json + 自定义工具
Utils：工具函数（utils/ 目录）
Custom UI：.vue 渲染器源码

编辑器

Graph Editor：VueFlow 画布（节点 + 边 + 子模块容器）
Node Editor：右侧属性面板（NodePropertiesPanel）
Palette：左侧节点面板（拖拽添加）
Scope Breadcrumb：顶部作用域导航（for_each 嵌套）

验证按钮

每个 Recipe 行有：

编译：POST /api/recipe_dev/compile（结构校验）
干：POST /api/recipe_dev/dryrun（模拟执行）
e2e：POST /api/recipe_dev/e2e（端到端测试）

十四、技能锻造（SkillForge）

文件：electron/renderer/src/components/SkillForgeModal.vue

描述需求 → 自动生成 SKILL.md：

输入技能描述（自然语言）
LLM 生成 SKILL.md 蓝图（工具序列 + 输入/输出）
进入 审批队列（SkillApprovalsView）
人工确认后生效

Skill 改动审批

文件：electron/renderer/src/components/SkillApprovalsView.vue

显示待审批的 skill 提案
对比 diff（旧版 vs 新版）
允许 / 拒绝 / 修改后允许

十五、交换所工坊（BrokerWorkshop）

文件：electron/renderer/src/components/broker_workshop/

已安装 broker 管理 + 市场浏览：

┌────────────────────────────────────────┐
│  [已安装]  [市场]                       │
├────────────────────────────────────────┤
│  已安装 Broker                          │
│  ┌──────────────────────────────────┐  │
│  │ Ventaris    [打开] [卸载]        │  │
│  │ starter     [打开] [卸载]        │  │
│  └──────────────────────────────────┘  │
│                                        │
│  [+ 从 URL 安装]  [+ 从文件安装]       │
└────────────────────────────────────────┘

市场

市场索引：GET /api/broker_workshop/marketplace/index（代理远程 index.json）
安装：POST /api/broker_workshop/instances/install_from_url（下载 + sha256 + Ed25519 签名校验）
作者签名：~/.familiars/authors/<name>.key（Ed25519 seed）

十六、托盘与后台

关闭窗口后，Electron 隐藏到系统托盘：

[系统托盘]
  └─ Familiars 图标
      ├─ 恢复窗口
      ├─ 后台运行 (✓)
      ├─ ──────────
      └─ 退出后台 (彻底关闭)

托盘菜单

项	功能
恢复窗口	显示主窗口
后台运行	开机自启开关（`autorun.py`）
退出后台	完全退出 Electron + 终止 bridge 子进程

首次隐藏提示

首次关闭窗口时，系统通知提示：

"Familiars 已隐藏到系统托盘。点击右下角托盘图标恢复窗口。彻底退出请用托盘菜单的'退出后台'。"

标记文件：app.getPath('userData')/.tray-hint-shown（仅提示一次）。

十七、强烈推荐的初始操作

吃一次审批卡：对 agent 说「帮我写一个文件到桌面」→ 观察隐私脱敏审批如何拦截
建一个 Todo 并设为每日重复：体验待办/日程/定时任务的完整流程
打开创意工坊：查看内置 Recipe（medical_triage / reverse_text），点击「编译」「干」「e2e」感受验证流程
找一个已装的市场 Broker（如 Ventaris）：发第一条公会任务，体验协作玩法
试一次全局快捷：选中文本 → Ctrl+Shift+L → 快速创建待办

下一步：常见问题 → 或用户手册

界面导览 ​

一、主窗口布局总览 ​

三栏结构 ​

二、标题栏（TitleBar） ​

三、Agent 列表（AgentRail） ​

交互 ​

Agent 行视觉 ​

Manager 特殊处理 ​

四、对话列表（DialogList） ​

交互 ​

置顶 ​

过滤 ​

五、桌面壳（Desktop.vue） ​

内置应用（12 个） ​

Broker 应用 ​

窗口行为 ​

切换回旧版 ​

六、聊天舞台（ChatStage） ​

顶栏 ​

消息区 ​

数字人面板 ​

分屏模式 ​

导出 ​

七、输入栏（InputBar） ​

输入模式 ​

Flow 绑定输入 ​

快捷输入 ​

八、对话树视图（TreeMini / TreeFull） ​

TreeMini（迷你视图） ​

TreeFull（全屏视图） ​

节点类型 ​

九、状态浮窗（StatusOverlay） ​

状态级别 ​

交互 ​

十、全局快捷键 ​

Electron 全局（后台也可触发） ​

应用内快捷键 ​

快捷创建流程 ​

十一、待办/日程/定时任务（TodoScheduleModal） ​

待办（Todo） ​

日程（Schedule） ​

定时任务（Cron） ​

快速入库 ​

十二、设置中心（SettingsCenter） ​

十三、创意工坊（CreativeWorkshop） ​

Tab 结构 ​

编辑器 ​

验证按钮 ​

十四、技能锻造（SkillForge） ​

Skill 改动审批 ​

十五、交换所工坊（BrokerWorkshop） ​

市场 ​

十六、托盘与后台 ​

托盘菜单 ​

首次隐藏提示 ​

十七、强烈推荐的初始操作 ​

界面导览

一、主窗口布局总览

三栏结构

二、标题栏（TitleBar）

三、Agent 列表（AgentRail）

交互

Agent 行视觉

Manager 特殊处理

四、对话列表（DialogList）

交互

置顶

过滤

五、桌面壳（Desktop.vue）

内置应用（12 个）

Broker 应用

窗口行为

切换回旧版

六、聊天舞台（ChatStage）

顶栏

消息区

数字人面板

分屏模式

导出

七、输入栏（InputBar）

输入模式

Flow 绑定输入

快捷输入

八、对话树视图（TreeMini / TreeFull）

TreeMini（迷你视图）

TreeFull（全屏视图）

节点类型

九、状态浮窗（StatusOverlay）

状态级别

交互

十、全局快捷键

Electron 全局（后台也可触发）

应用内快捷键

快捷创建流程

十一、待办/日程/定时任务（TodoScheduleModal）

待办（Todo）

日程（Schedule）

定时任务（Cron）

快速入库

十二、设置中心（SettingsCenter）

十三、创意工坊（CreativeWorkshop）

Tab 结构

编辑器

验证按钮

十四、技能锻造（SkillForge）

Skill 改动审批

十五、交换所工坊（BrokerWorkshop）

市场

十六、托盘与后台

托盘菜单

首次隐藏提示

十七、强烈推荐的初始操作