兔维斯（Tuvis）

你的桌面多 Agent 指挥台

一站式监控、通知、跳转、管理 Claude Code / Codex CLI / OpenCode / OpenClaw / Kimi Code / WorkBuddy / ZCode / dsh 的桌面应用

English · 中文

功能概览

会话监控看板

实时红绿灯状态看板，一目了然掌握所有 AI 编程工具的运行状态。

• 自动发现运行中的 Claude Code、Codex CLI/APP、OpenCode、OpenClaw、Kimi Code、WorkBuddy、ZCode、dsh 会话
• 区分 CLI 与桌面 APP 形态：APP 类支持会话级深度链接直达（workbuddy://chat/<id>、codex://threads/<id>，失败自动落 APP 前台保底）；ZCode（单窗口多标签）跳转直接聚焦其唯一窗口；dsh（web 宿主）跳转聚焦/打开浏览器中的 dsh 标签页（macOS）。APP 类均支持持久未读卡（转绿跨重启保留、宿主退出自动清理）
• 显示项目名称、Git 分支、最后消息预览、CPU 占用、运行时长
• 按优先级排序：等待中 → 运行中 → 空闲
• 标签栏下方「全部」+ 8 工具 chips 单选筛选（图标/配色与卡片徽章同源；选择记忆在本地，计数条保持全量，筛空时如实报出工具名）
• 系统托盘图标反映聚合状态（🔴/🟡/🟢）

远程接入与移动看板（局域网 / 临时隧道 / 自有域名 / 外部域名）

手机浏览器打开与桌面同源的八工具会话看板。设置 → 远程接入，四张通道卡按需开启（各自独立开关、可同时开）：

访问密码对本机同样生效：本机（回环）访问不再免密——从这台电脑自己的浏览器打开看板，与远程设备一视同仁（首次输入一次，之后 180 天免输入）。「本机」不再是通道卡：它只是"从本机访问"这一种访问方式，走「局域网连接」那张卡给出的地址。

上图为本分支之前的旧四卡界面（本机 / 局域网 / 临时隧道 / 命名隧道），图中「本机 · 无需密码」的说法已被「门禁零豁免」推翻；新四卡界面待补拍。

接入流程：开启「远程接入」总开关 → 打开对应通道 → 点卡片展开取地址 / 扫码（链接已含访问密码，扫码即自动填入）→ 手机浏览器打开对应地址（必须以 /m 结尾）。外部域名（免域名）首次使用走卡内向导：点「一键配置」后依次是检测 → 从官方源下载并校验安装包 → 安装（系统弹一次管理员确认）→ 登录 Tailscale（兔维斯 把授权链接做成按钮，在浏览器里完成）→ 关闭「阻止传入连接」→ 开通 Funnel → 可达性校验，全程不用碰命令行；macOS 另需在系统设置里批准一次 Tailscale 系统扩展，首次开通 Funnel 可能还需在浏览器里点一次批准（也可能不需要）。

地址只在从公网侧实测校验通过后才显示：校验中或尚未生效时，卡片如实显示「生效中」并按场景给出预期时长（首次开通约 5–6 分钟；此前开通过通常 1 分钟内，此时地址不会变；开机恢复约 1–2 分钟），不会把一个打不开的链接摆在界面上让用户干等；已生效后定期自动复验（约 1 分钟一次，空闲时更疏），异常时自动尝试恢复。地址永久不变、已配对设备免重配，每次开机 兔维斯 会自动恢复该通道（开机后先等 Tailscale 后端就绪再补开通，不会把正在恢复的完好配置清掉）。

访问密码对全部四条通道生效（本机访问同样需要）：新设备输入一次 180 天免输入，改密后所有设备需重新输入；「已接入设备」列表可重命名 / 踢下线，上限 10 台。

如实申报：向导内的平台标注与实现同源——Windows 侧的安装与登录流程尚未端到端实机跑过（只实测了其后半段：已安装 / 已登录之后的检测、开通、撤销与重启恢复），macOS 的写路径（开通 / 撤销 / 自愈）也尚未在本平台实机验证（只读探测已实测）；向导会在对应平台就地告知，不假装整条流程都验过。

实时看板：会话状态变化 2 秒级推送到手机（SSE 主通道）——横幅 + 提示音 + 振动三件套提醒，点横幅直接进对应会话；断流自动降级为 3 秒轮询，网络恢复后刷新页面即重连。状态跃迁的去重与桌面通知同一套服务端逻辑（手机端拿到的已是去重边沿）。

会话详情页（ZCode 式对话视图，八工具统一）：

• 运行中展开明细（思考过程/工具调用可点击展开），执行完成后自动折叠只显最终总结
• markdown 渲染（标题/列表/表格/代码高亮），正文中出现的项目文件路径自动变可点链接
• 文件面板：把会话涉及的文件聚合为一份列表（按最近出现倒序），支持「文档 / 图片」类型过滤与 200 / 500 / 1000 条消息三档追溯范围；已改写的文件名为强调色、仅读过的为常规色（均可点击预览），点次行目录可弹出完整路径
• 文件预览：markdown / 代码高亮 / 图片直显；三种布局随时切换——左右分屏（左对话右文件）、上下分屏、全屏浮层，分屏比例可拖动调整；可读范围为会话项目目录与用户主目录（密钥等敏感目录一律拒绝）
• 传输进度与带宽如实告知：文件上传 / 下载都出进度条（已传字节 / 百分比 / 瞬时速率 / 预计剩余）；速率或总量不可知时只显示已传字节，不编假百分比。走带宽受限的隧道通道时，文件面板与附件区就地说明「这是通道限制，不是故障」，并按本通道实测速率给出耗时量级（20 MB 附件下载约 1.5 分钟、上传约 3.3 分钟）与满速升级路径（手机上装 Tailscale 走尾网直连，带宽高 1–2 个数量级）
• 消息书签：长会话里拖到某处觉得「待会回来看」，点书签条上的「+ 书签」选个颜色即可打标（最多 10 个，每色一个）；点色点跳回该处，点「管理」可删单个或清空全部。书签保存在浏览器本地：刷新页面不丢、切回看板再进同一会话仍在；关掉 兔维斯（重启）或关闭浏览器标签页后清空
• 字号档位：对话正文字号 50% / 75% / 100% / 125% 四档可调（只影响正文与文件内容，界面控件不变）
• 历史会话区：已结束或失联的会话不再霸屏——登记制归档（历史页按 1/3/7 天懒加载），点卡片进只读详情、可一键重新激活；看板卡片支持关闭/归档（CLI 会话停止进程入档，APP 会话真「叉」语义）
• 进入会话默认停在最新消息处；往上翻到顶有「加载更早消息」按钮，续读时视线停在原处不跳

远程操控 · 手机发消息与审批（试验性 · v0.5.0 起）

不止看，还能操作——手机端向 CLI 会话发消息、批准、答题、切权限，甚至直接新建会话（支持 Claude Code / Codex CLI / Kimi Code / OpenCode 四家，试验性）：

• 新建会话：手机端直接拉起一个新 CLI 会话——选候选项目或手填路径（路径黑名单校验）、可带首句自动注入；创建进度实时反馈、完成后自动跳转新会话。四家弹窗形态（信任框/更新框等）经实机 E2E 定案自动处置
• 发消息与排队：会话忙时消息自动排队不丢失；「立即发送」打断插队（各家按实测键序：claude = Esc 中断 + 队列整批取出、codex = Tab 原生队列 / Esc 插队 / Ctrl+C 撤回、kimi = 回合结束自动续发）；排队消息可撤回。每条消息走键序注入 + 屏读回执闭环（尾戳逐字校验），未投递如实告知，绝不谎报成功
• 远程审批：工具调用批准（允许/拒绝）、计划确认（计划正文 + 终端对话框选项屏读实时同步、数字直选）、claude 计划批准数字键直达 + 计划反馈条（批准后可对计划发文字反馈 / 一键清除）；审批卡使命完成后自动收起
• 远程问答：单选/多选/自由作答（含 Other 覆盖写入与清空——进编辑退格到底再打新文，空文本如实拒），多题逐题推进 + 答完确认卡；多选题点选只勾选、「切换题目」显式推进（opencode/kimi 支持 ◀/▶ 双向）——手机与终端永远同题不错位。确认卡摘要以终端 Review 页屏读为准：刷新/重开页面后逐题答案与终端汇总页完全一致，本地记录只是兜底
• 权限模式切换：kimi 三档（/permission / /yolo / /auto）两段式——开菜单后屏读确认高亮才回车，且底栏模式/权限双轴回读（切档回执与当前档都有屏读证据）；codex 走终端菜单单选题
• 守卫：对话框挂起时拦截普通消息注入（防误答默认项）、输入行残留检测防双发、Ctrl+C 等危险键黑名单（如 opencode 会整应用退出）
• codex 桌面 APP 会话的写动作在协议通道落地前一律拒绝：APP 形态没有控制台，按键通道对它无效。模式切换 / 权限菜单 / 问答作答 / 审批应答四类动作会在动终端之前返回「开发中」提示，引导回 APP 内操作（被拒操作留审计记录，可在设置页「注入审计」查到）。命令行形态不受影响，只能看不能改的功能照常

会话详情 · 消息查看	发消息 · 排队与插队
审批 · 计划确认	问答 · 多选题与确认卡

子 Agent 观察台（移动端已合入）

会话详情实时显示后台子 agent 的运行状态与执行过程：

• 运行 chip：会话消息区下方实时显示后台子 agent（名字 / 时长走字 / token 消耗），点击直达执行详情
• 子 Agent 看板：与文件面板平级的独立看板——单一清单按派发序排列，绿点活跃走字、
  灰点完成后冻结原位；点卡片进入执行过程详情
• 执行过程详情：任务原文、思考过程（默认折叠）、工具调用与结果、输出正文；活跃时
  5s 一拍自动刷新贴底跟随，完成后定格快照
• 回报提醒开关：子 agent 完成回报唤醒主会话的提醒可独立静默（设置页，默认开）
• v1 覆盖 Claude 全量（经典任务通知 + teammate 空闲通告双机制自动识别）；其余工具清单
  照常、详情暂不支持

连不上？按这几条排查（均为实测踩过的坑）：

1. 路由器开了「终端隔离 / AP 隔离 / 访客网络」 —— 最隐蔽的一个：手机和电脑明明连着同一个 WiFi，路由器却禁止无线设备互访，怎么都连不通。到路由器后台关闭该设置（实测踩坑：其余全部排查正常，最后就是它）。
2. 临时隧道的地址每次开关都会变 —— 每次开启临时隧道都会重新生成公网地址（旧链接 / 二维码立刻失效），别把它当长期入口；要固定地址请用「自有域名」或「外部域名（免域名）」。切换其他设置不影响本通道。
3. 手机地址必须带 /m 后缀 —— 完整地址形如 http://192.168.x.x:9420/m；推荐直接扫二维码（链接已含访问密码，自动填入），手输漏掉 /m 会得到 404 空页。
4. 从本机访问也要访问密码 —— 「本机」已不是通道卡：本机浏览器访问与远程设备一视同仁（首次输入一次访问密码），地址用「局域网连接」卡给出的那个，且该开关必须打开（服务只在回环监听时这个地址不可达）；手机请用「局域网连接」或隧道通道的地址。
5. 防火墙放行 —— Windows 首次监听端口会弹「允许访问」，点过取消就会拦入站：Windows 安全中心 → 防火墙 → 允许应用通过防火墙 → 勾选 兔维斯（专用 + 公用都勾）。
6. TLS 确认框 —— 局域网直连是明文 HTTP，勾选表示「我知情/我已配 TLS 反代」；家庭局域网直接勾上即可，不需要真配反代。
7. 自有域名显示「运行中」但域名打不开 —— 检查 Cloudflare 侧是否配了 Public Hostname（子域 + 域名 + Service 填 HTTP://localhost:9420）——漏做这一步时隧道虽显示 Healthy，但域名无解析、地址打不开（设置页「使用教程」有逐步图文）。
8. 「外部域名（免域名）」卡一直显示「生效中」 —— 首次开通后公网 DNS 记录约需 5–6 分钟才发布：本机直连立刻就通，从外网则要等记录，此时卡片不给地址是如实而非故障；长时间不生效可点卡内「打开向导重试」，兔维斯 也会自动重置 Funnel 重开自愈。开机后若显示「恢复中」，那是 Tailscale 后端在重连（通常 1–2 分钟），配置与地址都不会变，无需任何操作。

Foxbell 桌宠

会说话的小狐狸常驻屏幕右下角，实时监控所有会话状态。

• 头顶状态卡片与看板同色同义：🔴 等待操作 / 🟡 运行中 / 🟢 已完成，点卡片直接跳转对应终端
• 语音提醒（内置 31 条语音）：等待操作撒娇催促、任务完成求夸、双击闲聊，字幕与语音时长自动对齐
• 拖拽物理：铆钉式跟手拖动、松手重力坠落、抛掷惯性、落地压扁回弹（可关）
• 单击挥手、双击说话、右键菜单：出声 / 字幕 / 物理 / 悬浮最前 / 大小三档 / 场景动作绑定 / 隐藏
• 与看板联动：桌宠开启时接管完成提示音、悬浮最前时抑制通知浮窗；看板 🦊 按钮、系统托盘、设置页多入口开关互通
• 悬停宠物约 0.5 秒出浮窗（迷你条 / 状态卡片）；移开后留 2 秒宽限再收起，
  够出从容点「详情 »」的时间（2026-10-07 由 200ms 放宽，此前会被判为「够不到」）
• 「启动时跟出」开关（设置页「通知与桌宠」块，默认开）：决定桌宠是否随兔维斯一起启动显示；关掉后它不再自动跟出，且该选择会被记住、不被启动兜底逻辑覆盖

外部桌宠

v0.3.0 起桌宠格式开放，不再只有 Foxbell：

• 导入自定义宠物：本地 zip / 目录导入，或从 Petdex 在线仓库下载；manifest 结构、帧率、尺寸、语音清单全量校验
• 管理面板：导入 / 描述编辑 / 重命名 / 删除 / 一键切换，宠物窗口热切换无需重启；删除或切换后活动宠物自动恢复
• 能力门控：无语音的宠物自动降级为纯动画（瞬态动作保留），语音能力双向同步

Token 用量看板（用量账本）

七个工具（Claude Code / Codex / Kimi Code / OpenCode / ZCode / WorkBuddy / dsh）的 token 用量统一记账：
应用启动后延迟采集一次，并开放 usage_collect 供前端按需触发（单飞互斥 + 默认 10 分钟的最小间隔兜底）；
采集走独立按需路径，不进入 3 秒会话轮询。账本落在 ~/.tuvis/tuvis.db 的 4 张表（明细按小时桶、日聚合永久保留、
采集游标、会话维度），明细默认保留 90 天（可配），到期只保留日聚合。

界面已落地（阶段②）：设置页「用量统计」分区——总开关（关闭后零扫描）、迷你条时间档（当日 / 近 5 小时 /
近 7 天）、迷你条工具行数（1–7）、明细保留期、采集间隔等 8 项设置即时保存；另有「采集状态」分区
（采集状态自查 + 立即采集）。桌宠迷你条：浮窗常驻 5 行核心指标（请求+命中率 / 缓存命中+产出 /
四桶明细 / 报错 / 最长单 turn，行序钉死），时间档与工具行数随设置联动。

口径说明（务必先读）

• 四桶：未缓存输入 / 缓存读 / 缓存写 / 产出；请求输入与命中率由缓存语义三态
  （互斥 / 包含 / 仅总量）派生。各源语义不一致，同一工具不同记录也可能不同——
  Codex 逐条用 total_tokens 算术判定（本机实测：正确判据命中率 92.69%，一律按包含会得到
  >100% 的荒谬值）。拿不准时一律按「互斥」（算错的后果是命中率偏低，而不是静默多算）。
• 含子代理：token 总量包含子代理/侧链用量；会话数与 turn 数按父子分层（不把一次对话算成多次）。
• 子代理标记只在小时档有真值：分组行的子代理标记（isSubagent）在小时档给出 true / false；
  日档与记录页卡内行恒为空态 null（这两档的行维度不含会话，算不出）——空态不得当作
  false（「不含子代理」）读。
• turn 数不跨工具合计（各源判据语义不可比）；最长单 turn 逐工具给 p50 + 最长，
  且含挂机、未剔除 idle。
• 报错三层分列 + 用户主动打断单列（三层互不包含，相加没有意义）。
• 不可得的指标显示空态，不显示 0：用户输入(估) 只对 claude / codex / kimi 计算，
  其余源在小时档与日档都显示空态；WorkBuddy 无回合概念、无时长字段、供应商不可得；
  OpenCode 工具级错误不可得；kimi 的用户主动打断判据缺失；dsh 的报错与最长 turn
  只能从原始会话日志取（只有一部分会话仍留有原始日志——比例不写死：覆盖率随机器与
  会话清理策略变化，探测期的「19/99」已作废）。这类部分覆盖不在界面表达（2026-10-06 用户裁决）：
  取到的照常显示，取不到的位次是 —，界面不设「部分覆盖」档（详见 docs/superpowers/specs/2026-10-03-pet-token-usage-dashboard-design.md §9.5.1）。
• 总开关默认开：关闭后不采集、不落库（也不做保留期清理），看板 / 记录页查询走关闭态早退；
  但 CSV 导出目前不受总开关门控，关闭态仍可导出既有账本历史（该不对称是已登记的待裁口径）。
• 「按项目」按记录归属：一个会话文件可跨多个项目（同一条会话记录内的 cwd 才算它的项目），
  项目名与首页会话卡片同源（projectName）；Windows 上各源路径大小写形态不同，
  同一目录可能裂成两组；无 cwd 的记录落 Unknown。
• 隐私：账本查询与后续呈现面只出现结构化数字与静态文本（工具名、模型名、项目名、会话标题），
  不含任何 prompt 原文或代码内容；CSV 导出只含结构化账本列，会话标题与原始路径不进 CSV。
  CSV 导出为 UTF-8 with BOM（Excel 兼容）。

桌面通知与提示音

• 状态颜色变化时发送桌面通知（红↔黄↔绿），带去重机制
• Web Audio API 提示音，无需音频文件
• 设置中可开关
• 通知可点击，附带「查看会话」动作直接跳转终端

开机自动启动

• 设置页「通知与桌宠」块、以及系统托盘「显示窗口」项下方，两处均可开关——共用同一条读写路径、勾选态回环一致
• 开关显示的是系统里的真实状态（Windows 读注册表启动项，含任务管理器里的启用/禁用标记；macOS 读登录项），界面显示即实际状态，不落本地缓存、不会漂移；开关失败回滚并如实报错
• 自启拉起时主窗口静默进托盘、桌宠照常跟出（不会开机弹一屏）
• Windows 卸载时由安装器钩子清理该用户的启动项；macOS 无卸载钩子，需手动移除 ~/Library/LaunchAgents/ 下对应的 plist

快速跳转终端

点击会话卡片即可瞬间聚焦对应终端标签页：

终端类工具（Claude Code / Codex CLI / OpenCode / Kimi Code）经进程树 + 窗口内容逐层消歧聚焦；同项目双开直达：Kimi / OpenCode 的窗口标题与会话标题（kimi state.json 标题 / OpenCode DB 标题）归一化比对，唯一命中即锁定，双开终端不再弹选择器。Windows 上消歧还会对目标终端贴一次性身份标记（ — 兔维斯:xxxxxxxxxxxx，聚焦成功后自动清除）正向锁定，且标记不会叠加残留；卡片↔终端配对存疑（同项目多开）时宁可弹选择器也不锁错窗，聚焦被系统拒绝时显式报错而非静默假成功。

桌面 APP 类工具（Codex APP、WorkBuddy）支持深度链接直达：codex://threads/<id>、workbuddy://chat/<id>（会话级），派发前校验协议 handler、派发后验证前台化，失败自动落 APP 级前台保底（macOS AppleScript / Windows 近祖聚焦），且不误标已读。ZCode 为单窗口多标签应用，跳转直接聚焦唯一窗口（卡片携带宿主 pid，零歧义锁定）。

扩展资源统一管理

Skill / MCP 服务器 / 插件的统一仓库，一键映射到各工具：

• Skill：符号链接（Unix）/ 交接点（Windows）映射到各工具的 skill 目录
• MCP 服务器：自动格式转换 —— JSON（Claude / Kimi / WorkBuddy）/ TOML（Codex）/ JSONC（OpenCode）/ JSON 嵌套子树（ZCode：mcp.servers，读-改-写只动该子树、未知键与原键序保留）
• 插件：文件/配置混合管理
• 首次启动自动导入已有 skill（从 ~/.claude/skills/、~/.codex/skills/、~/.config/opencode/skills/ 等各工具目录，以及共享目录 ~/.agents/skills/）
• ~/.agents/skills/ 为只读共享导入源（来源标签 agents-shared）：兔维斯 仅扫描入库（不归属工具、不建链），codex / zcode 等遵循开放标准的工具直接读取该目录
• 重新扫描按钮发现新安装的 skill

预设组一键切换

将 Skill + MCP + 插件打包为命名预设组，一键应用/取消：

• 一键应用到任意工具 —— 自动适配各工具的配置格式
• 部分成功处理：失败项报告错误，不回滚已成功项
• 冲突检测：跳过已存在的资源
• 系统托盘菜单集成，快速切换

子 Agent 级资源分配

为多 Agent 工具（OpenCode 等）的子角色分配资源子集：

• 子 Agent 分配受工具级启用范围约束
• 工具级禁用自动级联到所有子 Agent

工具勾选管理

设置页独立分区，按工具决定是否纳入 兔维斯 监控与管理：

• 行式开关列表：图标 + 名称 + 安装状态 badge，本地暂存、批量保存，保存前确认弹窗列出还原/回溯清单，未保存离开自动拦截
• 取消勾选 = 彻底还原：符号链接还原为真实文件、MCP 条目从工具配置移除、未读卡清空；SSOT 仓库与 DB 分配关系保留，重新勾选按原分配整体重建（失败自动回滚，重新保存即幂等重试）
• 未勾选工具彻底隐藏：会话扫描跳过、通知静音、资源/预设界面不出现，相关写命令返回明确错误（结构化错误码 + 中英文案）

信号健康度（Hook 信任门自查）

设置页独立分区，自查各工具的 Hook 通道是否真正在工作：

• 每个支持 Hook 的工具显示注册状态、最近事件时间与待办提示（数据来自既有 Hook 事件目录与会话扫描快照，打开分区/手动刷新时各拉一次，无后台轮询）
• 判据：已注册 + 该工具存在活跃会话 + 30 秒窗口内零事件 → 显示「需在工具终端输入 /hooks 并信任 兔维斯 条目（一次性）」，附一键复制 /hooks 命令
• codex 存在信任门：兔维斯 注册成功 ≠ 事件触发，需在 Codex TUI 内输入 /hooks 人工信任一次（信任后哈希落用户层配置）；首次注册完成 兔维斯 会发一条一次性桌面通知提醒

已知限制：判据基于 30 秒 TTL 事件窗口，活跃会话单次长操作静默超过 30 秒时会短暂误报待办——本分区是启发式自查面板，以工具终端实际状态为准。

技术栈

架构

src-tauri/src/
├── adapter/           # Agent 适配器 trait + 各工具实现
│   ├── claude.rs      #   Claude Code（JSONL + Hook）
│   ├── codex.rs       #   Codex CLI/APP（JSONL + Hook）
│   ├── opencode.rs    #   OpenCode（SQLite）
│   ├── openclaw.rs    #   OpenClaw（state.json）
│   ├── kimi.rs        #   Kimi Code（session_index + wire.jsonl）
│   ├── workbuddy.rs   #   WorkBuddy（心跳驱动 + JSONL）
│   ├── zcode.rs       #   ZCode（宿主判定 + SQLite 会话聚合）
│   ├── dsh.rs         #   dsh（web 宿主 + zstd 多帧日志）
│   └── mod.rs         #   AgentAdapter trait + 工具注册表 + 会话发现调度器
├── monitor/
│   ├── process.rs     #   进程发现（sysinfo 扫描）
│   ├── claude_parser.rs   # Claude 解析器（message.role 协议）
│   ├── codex_parser.rs    # Codex 解析器（rollout JSONL 协议）
│   ├── opencode_parser.rs # OpenCode SQLite 解析器
│   ├── openclaw_parser.rs # OpenClaw state.json 解析器
│   ├── kimi_parser.rs     # Kimi Code 解析器（session_index + wire.jsonl）
│   ├── workbuddy_parser.rs # WorkBuddy 解析器（心跳 + JSONL 尾部推导）
│   ├── zcode_parser.rs    # ZCode 解析器（tasks-index + session/message/part 双 SQLite）
│   ├── dsh/           #   dsh 解析器（projcache + zstd 多帧日志 + 状态/预览五模块）
│   ├── jsonl.rs       #   JSONL 读取公共件（尾部读取、文件枚举）
│   ├── cwd.rs         #   cwd 归一化（进程 ↔ 会话匹配公共设施）
│   ├── git.rs         #   GitHub URL 查询（进程内缓存）
│   ├── path_codec.rs  #   Claude projects 目录名编解码
│   ├── project.rs     #   项目名提取与 cwd 形态校验
│   ├── status.rs      #   纯消息状态判定
│   └── hooks.rs       #   Hook 注册 + 事件文件读取
├── services/          #   业务服务（按功能域拆分）
│   ├── skill/         #   Skill 安装/启用/禁用 + 自动导入
│   ├── resource/      #   资源扫描、SSOT 导入、补链
│   ├── mcp/           #   MCP 配置写入（JSON/TOML/JSONC）
│   ├── preset/        #   预设应用/取消 + 兼容性检查
│   ├── plugin/        #   插件管理
│   └── manifest/      #   扩展清单校验与更新检查
├── linker/
│   ├── mod.rs         #   符号链接/交接点管理 + 安全检查
│   ├── detector.rs    #   工具安装检测
│   ├── layer2.rs      #   Layer 2 工具级激活目录
│   └── layer3.rs      #   Layer 3 子 Agent 级激活目录
├── commands/          #   按模块拆分的 Tauri IPC 命令
├── database/          #   SQLite 数据层（schema/migration/dao）
├── session/           #   会话模型 + 状态枚举
├── window/            #   终端聚焦（iTerm2/Terminal.app/tmux）
├── plugins/
│   └── system_tray.rs #   系统托盘（状态 + 预设菜单）
└── lib.rs             #   应用入口 + 插件注册

src/
├── pages/             #   首页 / 设置 / 关于
├── components/
│   ├── SessionCard.tsx #   带状态灯的会话卡片
│   ├── SessionGrid.tsx #   看板网格
│   ├── ExtensionList.tsx # 双视图（按分类/按工具）资源管理
│   ├── ResourceByKindView.tsx # Skill/MCP/Plugin 三栏视图
│   ├── ResourceByToolView.tsx # 四工具卡片视图
│   ├── ImportDialog.tsx  #   原生资源扫描与导入
│   ├── CompatibilityDialog.tsx # 预设兼容性检查
│   ├── PresetList.tsx  #   预设组增删改查
│   └── ui/            #   shadcn/ui 基础组件
├── hooks/             #   useSessions, useNotification, useUpdater
├── stores/            #   Zustand 会话存储
├── lib/               #   音频、快捷键、更新器、窗口工具
├── i18n/              #   中文 + 英文语言包
└── types/             #   TypeScript 类型定义

快速开始

环境要求

• Node.js ≥ 18
• pnpm ≥ 8
• Rust ≥ 1.77
• Tauri v2 CLI

安装与运行

# 克隆仓库
git clone https://github.com/jarvislee90s-dot/tuvis.git
cd tuvis

# 安装前端依赖
pnpm install

# 启动开发模式
pnpm tauri:dev

macOS 开发版提示：开发版（未签名打包）首次使用「一键恢复会话」开窗前，需在
系统设置 > 隐私与安全性 > 自动化 中手动允许 兔维斯 控制
Terminal / iTerm2 一次（TCC 不会自动弹窗）。未授权时 osascript 以 -1743 失败，
resume 会回执「macOS 自动化授权缺失」并给出该指引。

构建

# 构建发布版（Windows NSIS 安装包）
pnpm tauri:build

helper 构建门（批次丙 T2 固化）：tuvis-hook-listener（hook 事件监听 helper）
与 tuvis-marker（窗口标题标记）都挂在 Cargo required-features 门后——不带
feature 时根本不构建，应用启动的 ensure_hook_script 就找不到同目录 helper、
跳过安装，~/.tuvis/bin/ 里那份永远是旧构建（实测故障：事件缺 tool_name 载荷 →
问答卡通道 A 永不识别）。

• pnpm tauri:dev / pnpm tauri:build 已内置 feature（hook-listener 与
  marker-helper，后者蕴含前者），照常用即可；
• 单独构建 helper（如跑实机 #[ignore] 测试）必须显式带上：
  cd src-tauri && cargo build --bin tuvis-hook-listener --features hook-listener；
• 跑 bin 测试同理：cargo test --bin tuvis-hook-listener --features hook-listener；
• macOS 打包（release:macos / release.yml 的 macOS job）走的是裸
  pnpm tauri build 显式参数，不受上述 npm script 影响——额外 bin 会令
  universal 打包失败，故 macOS 侧有意不带 feature（helper 为 Windows 通道）。

代码检查与格式化

pnpm check        # format:check + lint + build
pnpm format       # Prettier 自动格式化
pnpm lint         # ESLint 检查
pnpm lint:fix     # ESLint 自动修复

配置

应用数据存储在 ~/.tuvis/：

各工具配置支持

注：~/.agents/skills/ 是 Agent Skills 开放标准的跨工具共享目录（codex / zcode 等直接读取）。兔维斯 对 codex 的 skill 激活目录为私有 ~/.codex/skills/；.agents 仅作只读共享导入源（来源标签 agents-shared）——兔维斯 扫描入库、不归属工具、不建链；除一次性迁移 兔维斯 自建遗留链接外，永不写入该目录。

Kimi Code 数据目录重定向

Kimi Code 支持 KIMI_CODE_HOME 环境变量重定向数据根（默认 ~/.kimi-code，早期版本为 ~/.kimi，应用会自动回退）。注意本应用读取的是自身 GUI 进程的环境变量：

• macOS 从 Dock / Spotlight 启动的应用不继承 shell 配置（.zshrc 等）中的 export KIMI_CODE_HOME=...；
• 需要 GUI 侧生效时，可执行 launchctl setenv KIMI_CODE_HOME <路径> 后重启本应用，或直接为用户设置全局级环境变量。

路线图

• US1 — 多工具会话监控看板
• US2 — 状态变更通知与提示音
• US3 — 终端快速跳转（iTerm2/Terminal.app/tmux）
• US4 — Skill/MCP/Plugin 统一仓库管理
• US5 — 预设组一键切换
• US6 — 子 Agent 级资源分配
• 资源看板重设计（双视图 + 导入 + 兼容性）
• OpenClaw 支持（第四工具）
• Kimi Code 支持（第五工具：会话监控 + MCP 管理 + KIMI_CODE_HOME 数据目录重定向）
• WorkBuddy 支持（第六工具：心跳驱动监控 + 深度链接跳转 + 资源管理）
• ZCode 支持（第七工具：SQLite 会话聚合监控 + 子代理活跃度仲裁 + 唯一窗口聚焦跳转 + Skill/MCP 资源管理）
• dsh 支持（第八工具：web 宿主监控 + zstd 多帧日志解析 + 三色状态 + 浏览器标签跳转 + Skill 只读接入）
• Foxbell 桌宠（状态卡片 + 语音提醒 + 拖拽物理）
• 外部桌宠开放（本地/Petdex 导入 + 管理面板热切换 + 能力门控）
• 工具勾选管理（批量保存 + 还原/重建 + 彻底隐藏）
• APP 类工具会话卡与深度链接跳转
• 插件管理（文件/配置混合）
• i18n（中文 + English）
• GitHub Releases 自动更新（v0.5.1 重做：prerelease 渠道 + 忽略本版本 + 标题栏升级徽标）
• 暗色/亮色主题跟随系统
• Windows 支持（NSIS 安装包 + 深度链接 + 近祖窗口聚焦）
• 远程操控二期（v0.5.0 · 试验性）——手机端发消息/排队插队/远程审批/问答/权限切换（Claude Code / Codex CLI / Kimi Code / OpenCode）
• 移动端历史会话区（登记制归档 + 重新激活闭环）
• 远程接入 · 外部域名（免域名）固定地址通道（Tailscale 一键引导开通 + 公网侧可达性校验 + 开机自动恢复；本机访问不再免密）
• 外部域名向导 Windows 实测收口（v0.5.1）——Tailscale CLI 自定义路径查找治本 + 登录步主动递授权链接（不代登录）
• Token 用量看板（阶段① 采集底座与账本 + 阶段② 设置分区 / 桌宠迷你条呈现；口径说明见「Token 用量看板」一节）
• 子 Agent 观察台（移动端：会话运行 chip + 子 Agent 看板 + 执行过程详情）
• 开机自动启动（设置页 + 托盘双入口；真值源 = 操作系统侧状态实时读，不落本地缓存）
• 看板按工具筛选（桌面端 8 工具 chips 单选 + 本地记忆，与移动端同口径）
• Linux 支持
• Kitty & WezTerm 终端跳转支持

写在 v0.5.1

这仍然是一个比较早期的版本。远程操控的键序注入链路（注入 → 屏读 → 回执）已用四个工具逐键实测打磨；v0.5.1 又把外部域名（免域名）向导在 Windows 上从零端到端走了一遍，实测暴露的缺口（自定义安装路径查找、登录授权链接）全部修掉。但终端形态千变万化，边缘场景一定还有没踩到的坑。

希望更多朋友能体验「人离开桌面，Agent 不停工」——看板上的红绿灯在手机里跳动，批准一次计划只需一次点击。使用中遇到任何问题，欢迎直接提 Issue（附终端工具与版本号），我们会尽量远程响应大家的需求。

参与贡献

欢迎提交 Pull Request！

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

请阅读 AGENTS.md 了解项目架构与开发规范。

许可证

本项目采用 MIT 许可证 —— 详见 LICENSE 文件。

二次开发指引

欢迎 fork 与二次开发。按 MIT 许可证的要求，分发衍生版本时请保留原版权声明与许可证文本；在此基础上，欢迎（非强制）在项目说明中注明"基于兔维斯（Tuvis）二次开发"并回链本仓库，帮助用户识别上游。品牌名称与 Logo 的使用边界见 TRADEMARK.md。改进欢迎以 PR 形式回馈上游，让你的成果随主线一起演进。

商标与非官方声明

兔维斯 是一个独立的开源项目，与 Anthropic（Claude / Claude Code）、OpenAI（Codex / ChatGPT）、OpenCode、OpenClaw、月之暗面（Kimi Code）、WorkBuddy、ZCode、dsh 及本仓库提及的其他任何公司或产品均无关联、未获其背书或赞助。文中出现的名称与商标归其各自所有者所有，仅用于描述兼容性（名词性合理使用）。应用内图标为原创设计，部分配色仅用于辨识对应工具，不代表任何官方身份。

官方渠道

本项目唯一的官方发布渠道是本仓库的 GitHub Releases。任何其他网站或渠道提供的下载均为第三方分发，请自行甄别风险。品牌使用规范见 TRADEMARK.md。

多终端能力矩阵（总表，随版本随时更新）

12 行能力 × 8 个终端（✅ 支持 / ◐ 部分 / 🧪 试验性 / ❌ 不支持）——本表为能力总表，每次发版随功能增删更新（结构化源：docs/capabilities.json，与官网同源）：

手机操控：消息查看与文件预览覆盖 7 家（OpenClaw 为黑盒形态暂不支持远程查看）；发消息（注入）与新建会话处于试验阶段，目前支持 Claude Code / Codex CLI / OpenCode / Kimi Code 四家。OpenClaw / WorkBuddy 为黑盒形态（无外部写通道）、ZCode 预留无头通道、dsh 写通道另评——工具差异如实呈现，不假装统一。

四个可注入终端的现状与不足（如实呈报）：

• Claude Code：忙时消息排队不丢；「立即发送」= Esc 打断 + 队列整批取出开新回合；撤回窗口保护（输入行有残留时拒绝投递并如实回报）；计划批准卡（批准等待红灯 + 数字键直达 + 批准后计划反馈条）；问答多题 ←/→ 双向切题 + 多选自由作答（已写入后可编辑/覆盖写入/清空）；多选问题面板不再被误读为审批卡（复选框守卫 + 审批键禁用）。
• Codex CLI：Tab 进原生队列（不打断当前回合）、Esc 插队打断、Ctrl+C 撤回排队消息；问答支持备注栏（Tab 展开/清空，终端 note 行屏读同步回输入框）+ 多选自由作答；模式/权限远程切换——模式计划↔操作 chips 直选（当前档高亮）、权限四档直选（含 Full Access 二次确认），切换结果以终端屏读为准。不足：多题切页键未实测（多题切题引导终端完成）。
• Kimi Code：忙时排队回合结束自动续发；权限三档两段式切换（开菜单屏读确认高亮）+ 底栏模式/权限双轴回读；2.1.1 问卷全链——Other 自由作答（编辑/覆盖写入/清空）、多选勾选、单选自动推进 + 落点校验（n 题选完必落 n+1）、切题 ←/→、确认卡摘要以终端 Review 页屏读为准。不足：审批数字选择禁用（与菜单键冲突，改走导航）；Ctrl+S 立即引导未产品化。
• OpenCode：问答 enter / 数字切换选择 + 单选/多选自由作答（覆盖写入/清空、单选自愈送达）；◀/▶ 双向切题；Esc 打断插队；2.x 双 schema 会话发现。不足：Ctrl+C 全局禁用（会直接退出 opencode 应用）。