五分钟上手

目标：5 分钟内跑通「启动 → 第一个 Agent → 第一次对话 → 第一个 Todo → 看到记忆 → 用 CLI」。 假设已按安装指南完成环境配置。

一、启动应用

方式 A：Electron 全栈（推荐）

bash

cd electron
npm run electron:dev

启动流程：

Vite 开发服务器在 http://localhost:5173 启动
Electron 窗口打开，加载 Vite 页面
Electron 自动 spawn Python bridge 子进程（.venv/Scripts/python.exe -m src.bridge.run）
Bridge 监听 https://127.0.0.1:18711（hypercorn + HTTP/2 + 自签证书）
预热阶段：embedder（bge-m3）→ rembg → rewriter → 最近 agent 的数字人模型
桌面壳（Desktop.vue）渲染，显示应用图标网格

启动日志可在 workspace/.bridge.log 查看。GPU 探测结果缓存在 workspace/gpu_tier.json。

方式 B：仅 Bridge（后端测试 / 无 GUI）

bash

.venv/Scripts/python -m src.bridge.run

Bridge 启动后，可用 CLI 或浏览器访问 https://127.0.0.1:18711。

二、第一个 Agent

启动后默认有 agent 1（管理者 / manager） 已在工作。Manager 是特殊的 agent 0/1，负责：

全局摘要与 persona 进化
框架文档索引（每轮注入系统提示词）
跨 agent 路由与协调
调试工具（list_framework_docs / read_framework_doc / list_logs / read_log）

新建 Agent

在左侧 AgentRail 点击＋按钮，或：

弹出 CreateAgentKindModal — 选择 agent 类型（普通 / 特殊角色）
填写名称、选择角色模板（或留空让系统基于 USER.md 自动生成画像）
确认后，系统会：
- 创建 workspace/agents/agent_<id>/ 目录
- 初始化对话树（dialogue_0/）
- 生成头像资源（theme_assets/）
- 注册到 SQLite 数据库

新 agent 出现在 AgentRail 列表中，点击即可进入其聊天视图。

Agent 设置

点击 AgentRail 中 agent 行的齿轮图标，打开 AgentSettings：

修改名称、主题色
配置 theme_color（影响聊天气泡、标题栏高亮）
调整 agent 专属参数（intense_mode / turbo_mode / security_level 等）

三、第一次对话

发送消息

在底部 InputBar 输入框直接打字，按 Enter 发送：

说 「帮我安排一下今天的日程」 → agent 调用 Todo/Schedule 工具
说 「把刚才的话记住」 → 触发记忆写入（memorizer）
说 「读一下今天的 USER.md」 → 触发记忆检索（RAG）
说 「帮我写一个文件到桌面」 → 触发隐私审批卡片（PrivacyApprovalCard）

每条消息触发 agent 的 规划 → 工具调用 → 回答 管线：

Planner 分析意图，决定是否需要工具
ToolDispatcher 分发到具体工具（DailyTools / BrowserTools / MemoryTools 等 15 个默认实例）
合成器 整合工具结果生成最终回答

审批卡片

遇到需审批的操作（写文件 / 高权限 / 敏感信息），会弹出 PrivacyApprovalCard：

显示即将执行的操作 + 脱敏后的参数
点击「允许」继续，「拒绝」取消
审批阈值由 security_level 控制（high / medium / low）

开发环境可设置 FAMILIARS_APPROVAL_DISABLED=1 关闭所有审批（不推荐生产使用）。

语音输入

点击 InputBar 左侧的 🎤 喇叭图标，进入 push-to-talk 模式：

按住说话，松开自动识别（faster-whisper）
识别结果填入输入框，可编辑后发送

分屏模式

点击 ChatStage 顶部的 分屏按钮，可同时查看两个 agent 的对话：

左 pane：主 agent
右 pane：split agent
每个 pane 独立的消息流、输入栏、数字人面板

四、第一个 Todo / 日程

通过对话创建

直接对 agent 说：

每天早上 9 点帮我把今日天气同步到周会

Agent 会自动拆分为：

Todo：待办事项（标题 + 截止时间 + 优先级）
Schedule：日程安排（开始/结束时间 + 重复规则）
Cron Job：定时任务（APScheduler cron 表达式）

通过 UI 创建

点击顶部 待办/日程 图标，或按 Ctrl+Shift+L（全局快捷）：

QuickCreateModal 弹出，选择类型（待办/日程/定时任务）
手动填写表单，或点击「LLM 帮忙提取」让模型从剪贴板文本提取结构化数据
确认后在 TodoScheduleModal 中查看

通过 CLI 创建

bash

# 创建待办
python main.py todos create --title "买牛奶" --deadline 2026-07-05T18:00

# 列出待办
python main.py todos list --pretty

# 完成待办
python main.py todos complete <todo-id>

# 创建日程
python main.py schedule create --title "周会" --start 2026-07-06T09:00 --end 2026-07-06T10:00

# 创建定时任务
python main.py cron create --expr "0 9 * * *" --prompt "同步今日天气"

五、查看记忆

对话树视图

点击 ChatStage 右侧的 对话树图标，打开 TreeMini（迷你视图）或 TreeFull（全屏视图）：

每条消息在树里是一个节点（Node），带嵌入向量（bge-m3）
Full 视图可拖动、缩放、跳转、重放
树上右键：跳转重放 / 设为当前 / 导出

记忆检索

在对话里说 「回顾一下上个月我关注的 X」 会触发 RAG 检索：

rewriter 改写查询（workspace/rewriter/prompt.md）
dense recall（bge-m3 嵌入 + hnswlib 索引）
sparse recall（BM25）
reciprocal rank fusion（RRF，k=60）
reranker（bge-reranker-v2-m3）重排
返回 top-K 结果注入上下文

记忆写入

对话中 agent 自动判断是否需要记忆：

ephemeral：单轮有效，结束时驱逐
dialogue：持久化到 workspace/agents/agent_<id>/dialogue_<n>/
agent：跨对话持久化到 workspace/agents/agent_<id>/
user / identity：全局持久化到 workspace/USER.md / IDENTITY.md

记忆类别：event / state / profile / procedure / directive，每类有独立衰减常数。

记忆管理

对话页右下/侧栏的 记忆入口：查看当前 agent 的对话树与长期记忆
Manager 可在设置/汇报页看到所有 agent 的记忆规模
右键 AgentRail 中的 agent → 释放内存 可手动释放不活跃的对话树（DialogueManager.release_memory）

六、CLI 常用命令

CLI 是 bridge 的命令行包装（main.py），覆盖所有 REST 端点（除 WebSocket 流）。

基础用法

bash

# 查看帮助
python main.py --help                    # 列出命令组
python main.py agents --help             # 列出 agents 组的动作
python main.py agents list               # 执行动作

Agent 管理

bash

# 列出所有 agent
python main.py agents list --pretty

# 创建 agent（SSE 流式）
python main.py agents create --name "小助手" --role "客服"

# 查看 agent 详情
python main.py agents get --id 1

# 释放 agent 内存
python main.py agents release-memory --id 1

对话

bash

# SSE 流式对话
python main.py chat stream --prompt "你好" --agent-id 1

# 同步对话（等待完整回答）
python main.py chat send --prompt "今天天气如何" --agent-id 1

# 查看对话历史
python main.py chat history --agent-id 1 --dialogue-id 0

待办 / 日程 / 定时任务

bash

# 待办
python main.py todos create --title "买牛奶" --deadline 2026-07-05T18:00
python main.py todos list --pretty
python main.py todos complete <id>

# 日程
python main.py schedule create --title "周会" --start 2026-07-06T09:00
python main.py schedule list

# 定时任务
python main.py cron create --expr "0 9 * * *" --prompt "同步天气"
python main.py cron list

技能 / Recipe / Flow

bash

# 技能
python main.py skills list
python main.py skills forge --description "自动生成周报"

# Recipe
python main.py recipes list
python main.py recipes compile --id <recipe-id>

# Flow
python main.py flows list
python main.py flows get --id <flow-id>

Broker / 市场

bash

# Broker
python main.py broker keys-list
python main.py broker pack --dir workspace/manager/brokers/my_broker
python main.py broker sign --file my_broker.broker.zip
python main.py broker install --file my_broker.broker.zip

# 市场索引
python main.py broker marketplace-index

认证

CLI 自动从 workspace/.bridge_token 读取 X-Bridge-Token。覆盖方式：

bash

# 命令行参数
python main.py --token <token> agents list

# 环境变量
export BRIDGE_TOKEN=<token>
python main.py agents list

# 指定 token 文件
python main.py --token-file /path/to/token agents list

Bridge 端口

CLI 自动读取 workspace/.bridge.port（bridge 启动时写入）。如果 18711 被占，bridge 会选新端口并写入该文件，CLI 自动跟踪。

覆盖方式：

bash

python main.py --base-url https://127.0.0.1:18712 agents list

七、进阶玩法

装好了就想玩起来？下一步：

界面导览 — 走一遍所有主界面组件
创意工坊 — 管理 Recipe / Flow（用户手册·创意工坊）
技能锻造 — 描述需求自动生成 SKILL.md（用户手册·技能锻造）
Broker 市场 — 安装 Ventaris 等协作应用（生态开发教程）
数字人 — 本地渲染 AI 数字人（需 GPU，数字人章节）
语音通话 — push-to-talk + ASR + TTS（语音输入）

八、常见踩坑

现象	原因 / 处理
对话一直转圈	检查 `.env` 的 `BASE_URL`/`API_KEY`；没有模型返回就换 `DEFAULT_MODEL`
工具调用被审批卡住	这是隐私设计的正常行为；在审批卡片点允许即可，或用 `FAMILIARS_APPROVAL_DISABLED=1` 关掉（不推荐）
记忆写入要很久	首次需下载 `bge-m3` 模型，放行后正常
看不到数字人	需本地 GPU 与 GPT-SoVITS 模型，属高级功能，见数字人
Bridge 启动报端口冲突	正常——bridge 自动换端口并写入 `workspace/.bridge.port`；CLI 自动读取
Electron 窗口打不开	检查 `workspace/.bridge.log` 看 bridge 是否启动成功；检查 `.venv` 是否正确激活
CLI 报 401 Unauthorized	`X-Bridge-Token` 缺失或错误；检查 `workspace/.bridge_token` 是否存在
模型响应慢	检查 `MAX_TURNS`（默认 50）是否过大；检查网络到 `BASE_URL` 的延迟
记忆检索不准	调整 `RAG_DENSE_TOPK` / `RAG_RERANK_MIN_SCORE`；确保 `EMBEDDING_MODEL` 已下载

下一步：界面导览 →

五分钟上手 ​

一、启动应用 ​

方式 A：Electron 全栈（推荐） ​

方式 B：仅 Bridge（后端测试 / 无 GUI） ​

二、第一个 Agent ​

新建 Agent ​

Agent 设置 ​

三、第一次对话 ​

发送消息 ​

审批卡片 ​

语音输入 ​

分屏模式 ​

四、第一个 Todo / 日程 ​

通过对话创建 ​

通过 UI 创建 ​

通过 CLI 创建 ​

五、查看记忆 ​

对话树视图 ​

记忆检索 ​

记忆写入 ​

记忆管理 ​

六、CLI 常用命令 ​

基础用法 ​

Agent 管理 ​

对话 ​

待办 / 日程 / 定时任务 ​

技能 / Recipe / Flow ​

Broker / 市场 ​

认证 ​

Bridge 端口 ​

七、进阶玩法 ​

八、常见踩坑 ​

五分钟上手

一、启动应用

方式 A：Electron 全栈（推荐）

方式 B：仅 Bridge（后端测试 / 无 GUI）

二、第一个 Agent

新建 Agent

Agent 设置

三、第一次对话

发送消息

审批卡片

语音输入

分屏模式

四、第一个 Todo / 日程

通过对话创建

通过 UI 创建

通过 CLI 创建

五、查看记忆

对话树视图

记忆检索

记忆写入

记忆管理

六、CLI 常用命令

基础用法

Agent 管理

对话

待办 / 日程 / 定时任务

技能 / Recipe / Flow

Broker / 市场

认证

Bridge 端口

七、进阶玩法

八、常见踩坑