写给想读代码、改代码或发布版本的人。普通用户不需要这一页。
技术栈
| 层 | 技术 |
|---|---|
| 前端 | React 19、TypeScript、Vite |
| 桌面外壳 | Tauri 2(decorations: false,自绘标题栏) |
| 后端 | Rust,Tauri 命令系统 |
| HTTP / 流式 | reqwest + futures-util(SSE) |
| 数据库 | rusqlite(SQLite) |
| 序列化 | serde / serde_json / serde_yaml |
| PDF → Markdown | pdf2md-rs(工作区成员 crate,进程内) |
| 知识图谱客户端(库,非工具) | neo4rs(Neo4j Bolt) |
| 打包 | Tauri bundler、MSIX(makeappx)、GitHub Actions |
crate/二进制名:rabbit-chat-studio(src-tauri/Cargo.toml),库目标 rustgui_lib;npm 包名与应用 id 同为 rabbit-chat-studio。
架构
┌────────────────────────────── React 19 (src/) ──────────────────────────────┐
│ App.tsx ChatMessage HistoryPanel SettingsPanel SkillsPanel ToolsPanel │
│ McpPanel AgentsPanel MonitorPanel ProfilePanel UpdatePanel TitleBar │
└───────────────┬───────────────────────────────────────────────┬─────────────┘
│ invoke(command, args) │ listen(event)
▼ ▲
┌──────────────────────────── Tauri 2 (src-tauri/src/) ─────────┴─────────────┐
│ lib.rs 命令注册 / AppState / 工作区 / 菜单 / 更新 │
│ llm_complete.rs Chat Completions(SSE)、工具循环、压缩、停止 │
│ llm_complete/ 轮次循环、上下文压缩器、流式、结论蒸馏 │
│ turn_guard.rs 轮次预算(请求数/工具调用数)+ 工具失败守卫 │
│ agents.rs 子智能体、规划、执行、任务状态 │
│ agents/cli.rs 本地 CLI 子进程 │
│ agents/cloud.rs 远程 HTTP 端点 + 轮询 │
│ agents/files.rs 文件型 `llm` 定义(Markdown frontmatter) │
│ agents/exchange.rs `.data/deliver` 交付物交换区 │
│ agents/mbus.rs 任务总线:发布/订阅 + 实时状态登记 │
│ agents/supervisor.rs 规划器监督器(事件驱动,仅总线工具) │
│ instance.rs 单实例 / 影子窗口(配置分叉) │
│ pdf_mentions.rs `@paper.pdf#pages` → Markdown(经 pdf2md-rs) │
│ mcp.rs stdio / SSE / HTTP / Streamable HTTP │
│ skills.rs SKILL.md 解析、技能状态 │
│ workspace.rs <工作区>/.data 布局 │
│ backup.rs 导出/导入 zip │
│ model_metadata.rs 合并模型目录(models.dev + OpenRouter + llm-metadata) │
│ update.rs 更新检查/下载 │
│ logger.rs 文件/终端日志 │
│ process_guard.rs 子进程登记与进程树清理 │
│ tools/ 文件、命令、patch、搜索、风险、记忆、待办、 │
│ 定时器、后台任务、自建 MCP(mcp_self) │
│ db.rs SQLite:history / api_requests / interaction_log / missions│
└──────────────────────────────────────┬──────────────────────────────────────┘
▼
<工作区>/.data/chat.db + 文件状态
一次对话轮次的生命周期
- 前端调用
invoke("chat_completion", …)。 - 后端为本轮安装新的
Arc<AtomicBool>取消标志;上一个标志永久保持true。 - 若编排开启且有启用的智能体:
agents::orchestrate规划 → 执行子智能体 → 把任务报告注入主上下文。 - 组装消息:系统提示、已加载技能、历史、会话摘要、待办、任务报告、最后一条用户消息。
- 可能先跑预测式压缩(见 提示词与上下文)。
POST {base_url}/chat/completions,stream: true。- 解析 SSE;后端发出
chat-token/chat-reasoning-token/chat-usage。 - 模型返回
tool_calls就跑工具,结果以tool消息追加,循环继续。 - 目标循环在待办仍有开放条目时可能继续本轮(最多 4 次续跑),除非有待触发的定时器或
[WAIT_EVT: …]使其挂起。 - 成功发
chat-done,失败发chat-error。控制标记在落库前被剥离。 - 消息、工具调用与 token 写入 SQLite。
停止
stop_chat_completion置位本轮标志。- CLI 智能体每 250 ms 轮询并杀掉自己的进程树。
llm智能体在循环边界退出。- 云端请求停止等待。
- 剩余任务标为跳过;任务状态变
stopped。 - 规划/执行阶段在步骤之间检查,不会取消已在飞行中的 LLM 请求。
- 新轮次安装新标志,所以空闲时按 Stop 不会影响下一轮。
主要事件
| 事件 | 方向 | 用途 |
|---|---|---|
chat-token |
后端 → 前端 | 答复流 |
chat-reasoning-token |
后端 → 前端 | 推理流 |
chat-usage |
后端 → 前端 | token(本轮费用芯片由此推算) |
chat-retry |
后端 → 前端 | 断流后正在重试 |
chat-done / chat-error |
后端 → 前端 | 结束 / 错误 |
chat-injected |
后端 → 前端 | 中途更新或后台结果被附加到助手消息 |
chat-notice |
后端 → 前端 | 浮动警告/错误(预算耗尽、工具被禁用等) |
tool-call |
后端 → 前端 | 工具状态文本 |
todo-state |
后端 → 前端 | 待办实时更新 |
skill-loaded |
后端 → 前端 | 技能已加载 |
timer-state / timer-fired |
后端 → 前端 | 定时器 |
sleep-lock |
后端 → 前端 | 系统唤醒锁状态(输入框上方徽标) |
agent-plan-start / agent-task-start / agent-task-token / agent-task-reasoning / agent-task-tool / agent-task-done / agent-task-error / agent-planner-state / agent-planner-action / agent-aggregate-done |
后端 → 前端 | 编排进度——任务行自带状态,规划决策以广播行流式呈现 |
confirm-required |
后端 → 前端 | 风险确认 |
workspace-changed |
后端 → 前端 | 工作区切换 |
update-download-progress |
后端 → 前端 | 更新下载 |
设计原则
核心意图:从第一性原理出发推理,把自由还给用户(工具、LLM API、提示词),界面保持克制专业。
- 最小依赖闭包:所有模型调用都走 OpenAI 兼容 API。
- 能力与权限解耦:默认只是聊天;工具按需开启;技能进一步收窄。
- 本地优先可观测:配置、历史、请求日志都留在本地。
- 显式边界:技能目录隔离、工具白名单、工作区路径约束。
- 可替换:前端、命令层、模型服务与图后端都是模块化的。
落到代码:
get_all_tools(selected_tools)决定工具表;execute_tool(..., allowed_commands, ...)是唯一执行入口;resolve_safe_path/ensure_mutation_target_allowed是路径边界;process_guard是进程边界;workspace.rs是状态边界。
项目结构
ai-chat/
├─ src/ React 前端
│ ├─ App.tsx 主界面外壳
│ ├─ api.ts invoke/listen 封装
│ ├─ types.ts 共享 TS 类型
│ ├─ fileMention.ts `@文件` 弹窗查询/打分(行区间)
│ ├─ slashMention.ts `/技能` 弹窗查询/打分
│ ├─ attachments.ts 发送时把 `@路径` 提及落成附件
│ ├─ components/ Chat/History/Settings/Skills/Tools/MCP/Agents/
│ │ Profile/Monitor/Update/TitleBar/FileMentionPopup/
│ │ SlashMentionPopup/BackgroundTaskGroup…
│ ├─ i18n/ en / zh-CN / zh-TW
│ └─ utils/ 模型目录匹配(modelMetadata.ts)等
├─ src-tauri/
│ ├─ src/lib.rs 入口、命令、AppState、菜单
│ ├─ src/llm_complete.rs SSE 对话、工具循环、压缩、停止
│ ├─ src/llm_complete/ turn.rs / context.rs / stream.rs / conclusion.rs
│ ├─ src/agents.rs 子智能体、编排、任务
│ ├─ src/agents/cli.rs CLI 后端
│ ├─ src/agents/cloud.rs Cloud 后端
│ ├─ src/agents/exchange.rs `.data/deliver` 交付物交换区
│ ├─ src/agents/files.rs `llm` 定义(Markdown 解析/序列化/扫描)
│ ├─ src/agents/mbus.rs 任务总线(发布/订阅 + 状态登记)
│ ├─ src/agents/supervisor.rs 规划器监督器
│ ├─ src/instance.rs 单实例 / 影子窗口
│ ├─ src/turn_guard.rs 轮次预算 + 工具失败守卫
│ ├─ src/pdf_mentions.rs `@paper.pdf#pages` 转换 + 缓存
│ ├─ src/mcp.rs MCP 客户端
│ ├─ src/skills.rs SKILL.md 解析、技能状态
│ ├─ src/workspace_files.rs `@` 提及用的工作区文件列表
│ ├─ src/workspace.rs `.data` 布局
│ ├─ src/backup.rs 导出/导入
│ ├─ src/model_metadata.rs 合并能力目录
│ ├─ src/update.rs 更新检查/下载
│ ├─ src/logger.rs 文件/终端日志
│ ├─ src/process_guard.rs 子进程清理
│ ├─ src/tools/ 工具实现
│ │ ├─ mod.rs 派发/schema/测试
│ │ ├─ file_actions.rs
│ │ ├─ patch.rs
│ │ ├─ paths.rs
│ │ ├─ risk.rs
│ │ ├─ scripts.rs run_cmd 脚本库(解析、元数据、批准)
│ │ ├─ search.rs
│ │ ├─ serve.rs
│ │ ├─ background.rs
│ │ ├─ memory.rs
│ │ ├─ todos.rs
│ │ ├─ timer.rs
│ │ └─ mcp_self.rs 自建 MCP 服务器(自我进化模式)
│ ├─ utils/pdf2md-rs/ PDF → Markdown 库 crate(工作区成员)
│ ├─ utils/knowledge_graph/ 知识图谱客户端库(未接入工具集)
│ ├─ capabilities/default.json Tauri 权限
│ └─ tauri.conf.json
├─ scripts/
│ ├─ sync-version.cjs 三方版本同步
│ ├─ gen-changelog.cjs 由 git tag/提交生成 CHANGELOG.md
│ ├─ gen-wiki.mjs docs/wiki/*.md → docs/site/wiki/**.html
│ ├─ build-msix.ps1 MSIX 打包
│ └─ capture-store-screenshots.ps1
├─ docs/
│ ├─ wiki/ Wiki 源:nav.json + en/ + zh/
│ ├─ site/ GitHub Pages(纯静态,无构建步骤)
│ ├─ gen.py CI 里生成 site/architecture.html
│ └─ store/ 商店上架素材
├─ .github/workflows/ pages.yml / release.yml / store.yml / winget.yml
├─ DESIGN.md 界面设计规范
├─ AGENTS.md 开发约定
└─ CHANGELOG.md 自动生成,勿手改
数据库
<工作区>/.data/chat.db 主要表:
| 表 | 内容 |
|---|---|
history |
会话消息、工具调用、附件、推理 |
session_meta |
标题、收藏、归档 |
session_summaries |
压缩后的会话摘要 |
api_requests |
每次 LLM 请求的指标 |
interaction_log |
LLM/工具/MCP 交互明细 |
agent_missions |
子智能体任务 |
agent_tasks |
任务内的子任务 |
agent_bus_messages |
任务总线发布历史(任务面板回放用) |
开发命令
# 安装依赖
npm install
cargo install tauri-cli --version "^2"
# 开发(Vite :1420 + Tauri)
npm run tauri dev
# 仅前端
npm run dev
# 类型检查
npx tsc --noEmit
# 前端构建(不需要 git tag)
npx vite build
# Rust 检查
cargo check --manifest-path src-tauri/Cargo.toml
# Rust 单元测试
cargo test --manifest-path src-tauri/Cargo.toml
# 生产构建(需要最新 git tag)
npm run tauri build
文档与打包:
python3 docs/gen.py # 生成 docs/site/architecture.html
node scripts/gen-wiki.mjs # docs/wiki → docs/site/wiki
node scripts/gen-changelog.cjs # 由 git 重新生成 CHANGELOG.md
pwsh scripts/build-msix.ps1 # MSIX 包(Windows + makeappx)
版本同步:
node scripts/sync-version.cjs --from-git-tag
node scripts/sync-version.cjs --bump patch
npm run sync-version:git-tag
npm run sync-version:bump-patch
发布流程
-
合并进
main。 -
打 tag 并推送:
git tag v3.3.3 git push origin v3.3.3 -
.github/workflows/release.yml在 4 个 runner 上构建。 -
第一个平台完成即发布 Release,其余随后上传。
-
store.yml构建.msix工作流产物,不附在 Release 上。 -
winget.yml暂未启用:只有包被winget-pkgs接受且存在WINGET_TOKEN时才提交。
路线图
来自 README:
- 增加模型供应商预设(OpenAI / Azure / 本地网关);
- 工具调用审计与回放;
- 技能签名与发布;
- 端到端测试与安全基线扫描。
贡献
- 改界面前先读
DESIGN.md:只用src/App.css里的 token;4px 圆角、单一电光蓝强调色、无阴影、一条动效曲线。 - 改 Rust 工具时同步更新 schema 与测试。
- 新增 Tauri 插件时:加 crate、注册
.plugin(...)、把权限写进capabilities/default.json(Tauri 2 默认拒绝)。 - Wiki 页在
docs/wiki/{en,zh}/*.md;docs/site/wiki/下的 HTML 是生成产物,不要提交。改完跑node scripts/gen-wiki.mjs。 - 提交前跑
npx tsc --noEmit与cargo check;工具逻辑跑cargo test。 - 绝不提交真实 API 密钥或用户数据。
许可
MIT。见仓库中的 LICENSE。
相关文档
README.md/README.zh.md:项目介绍与快速开始AGENTS.md:开发约定、架构与命令DESIGN.md:界面设计规范config.example.md:配置字段示例CHANGELOG.md:自动生成的更新记录