For people who want to read, modify or release the code. Regular users do not need this page.
Stack
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite |
| Desktop shell | Tauri 2 (decorations: false, custom title bar) |
| Backend | Rust, Tauri command system |
| HTTP / streaming | reqwest + futures-util (SSE) |
| Database | rusqlite (SQLite) |
| Serialization | serde / serde_json / serde_yaml |
| PDF → Markdown | pdf2md-rs (workspace member crate, in-process) |
| Knowledge graph client (library, not a tool) | neo4rs (Neo4j Bolt) |
| Packaging | Tauri bundler, MSIX (makeappx), GitHub Actions |
Crate/binary name: rabbit-chat-studio (src-tauri/Cargo.toml), library target rustgui_lib; the npm package and the app id stay rabbit-chat-studio.
Architecture
┌────────────────────────────── 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 command registration / AppState / workspace / menu / update│
│ llm_complete.rs Chat Completions (SSE), tool loop, compression, stop │
│ llm_complete/ turn loop, context compressor, stream, conclusion │
│ turn_guard.rs turn budget (rounds/tool calls) + tool-failure guard │
│ agents.rs sub-agents, planning, execution, mission state │
│ agents/cli.rs local CLI child processes │
│ agents/cloud.rs remote HTTP endpoints + polling │
│ agents/files.rs file-backed `llm` definitions (Markdown frontmatter) │
│ agents/exchange.rs `.data/deliver` deliverable exchange area │
│ agents/mbus.rs mission bus: pub/sub + live status registry │
│ agents/supervisor.rs planner supervisor (event-driven, mbus-only tools) │
│ instance.rs single instance / shadow windows on forked configs │
│ pdf_mentions.rs `@paper.pdf#pages` → Markdown via pdf2md-rs │
│ mcp.rs stdio / SSE / HTTP / Streamable HTTP │
│ skills.rs SKILL.md parsing, skill status │
│ workspace.rs <workspace>/.data layout │
│ backup.rs export / import zip │
│ model_metadata.rs merged model catalogue (models.dev + OpenRouter + llm-metadata)
│ update.rs update check / download │
│ logger.rs file / terminal logging │
│ process_guard.rs child registry and process-tree cleanup │
│ tools/ files, commands, patches, search, risk, memory, todos, │
│ timers, background tasks, self-built MCP (mcp_self) │
│ db.rs SQLite: history / api_requests / interaction_log / missions│
└──────────────────────────────────────┬──────────────────────────────────────┘
▼
<workspace>/.data/chat.db + file state
Lifecycle of a chat turn
- The frontend calls
invoke("chat_completion", …). - The backend installs a fresh
Arc<AtomicBool>cancel flag for this turn; the previous flag staystrueforever. - If orchestration is on and agents are enabled:
agents::orchestrateplans → executes sub-agents → injects the mission report into the main context. - Messages are assembled: system prompt, loaded skills, history, session summary, todos, mission report, last user message.
- Predictive compression may run first (see Prompts and Context).
POST {base_url}/chat/completionswithstream: true.- SSE is parsed; the backend emits
chat-token/chat-reasoning-token/chat-usage. - If the model returns
tool_calls, tools run; results are appended astoolmessages and the loop continues. - The goal loop may continue the turn while the todo list has open items (max 4 continuations), unless a pending timer or
[WAIT_EVT: …]suspends it. chat-doneon success;chat-erroron failure. Control markers are stripped before the row is stored.- Messages, tool calls and tokens are written to SQLite.
Stop
stop_chat_completionsets this turn's flag.- CLI agents poll every 250 ms and kill their process tree.
llmagents exit at loop boundaries.- Cloud requests stop waiting.
- Remaining tasks are marked skipped; the mission becomes
stopped. - Planning/execution check between steps; they do not cancel an in-flight LLM request.
- A new turn installs a new flag, so pressing Stop while idle cannot affect the next turn.
Main events
| Event | Direction | Purpose |
|---|---|---|
chat-token |
backend → frontend | Answer stream |
chat-reasoning-token |
backend → frontend | Reasoning stream |
chat-usage |
backend → frontend | Tokens (the turn cost chip is derived from these) |
chat-retry |
backend → frontend | A dropped stream is being retried |
chat-done / chat-error |
backend → frontend | End / error |
chat-injected |
backend → frontend | A mid-turn update or background result was attached to the assistant row |
chat-notice |
backend → frontend | Floating warning/error notice (budget exhausted, tool disabled, …) |
tool-call |
backend → frontend | Tool status text |
todo-state |
backend → frontend | Live todo updates |
skill-loaded |
backend → frontend | Skill loaded |
timer-state / timer-fired |
backend → frontend | Timers |
sleep-lock |
backend → frontend | System-awake lock state (badge above the input) |
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 |
backend → frontend | Orchestration progress — task rows own their status, planner decisions stream as feed rows |
confirm-required |
backend → frontend | Risk confirmation |
workspace-changed |
backend → frontend | Workspace switch |
update-download-progress |
backend → frontend | Update download |
Design principles
The core intent: reason from first principles, return freedom to the user (tools, LLM API, prompts), and keep the interface minimal and professional.
- Minimal dependency closure: all model calls go through OpenAI-compatible APIs.
- Capabilities decoupled from permissions: chat by default; tools opt-in; skills narrow them.
- Local-first observability: config, history and request logs stay local.
- Explicit boundaries: skill directory isolation, tool allowlists, workspace path constraints.
- Replaceable: frontend, command layer, model service and graph backend are modular.
In code:
get_all_tools(selected_tools)decides the tool list;execute_tool(..., allowed_commands, ...)is the single execution entry point;resolve_safe_path/ensure_mutation_target_allowedare path boundaries;process_guardis the process boundary;workspace.rsis the state boundary.
Project structure
ai-chat/
├─ src/ React frontend
│ ├─ App.tsx main UI shell
│ ├─ api.ts invoke/listen wrappers
│ ├─ types.ts shared TS types
│ ├─ fileMention.ts `@file` popup query/scoring (line ranges)
│ ├─ slashMention.ts `/skill` popup query/scoring
│ ├─ attachments.ts materializes `@path` mentions on send
│ ├─ components/ Chat/History/Settings/Skills/Tools/MCP/Agents/
│ │ Profile/Monitor/Update/TitleBar/FileMentionPopup/
│ │ SlashMentionPopup/BackgroundTaskGroup…
│ ├─ i18n/ en / zh-CN / zh-TW
│ └─ utils/ model catalogue matching (modelMetadata.ts), etc.
├─ src-tauri/
│ ├─ src/lib.rs entry, commands, AppState, menu
│ ├─ src/llm_complete.rs SSE chat, tool loop, compression, stop
│ ├─ src/llm_complete/ turn.rs / context.rs / stream.rs / conclusion.rs
│ ├─ src/agents.rs sub-agents, orchestration, missions
│ ├─ src/agents/cli.rs CLI backend
│ ├─ src/agents/cloud.rs cloud backend
│ ├─ src/agents/exchange.rs `.data/deliver` deliverable exchange area
│ ├─ src/agents/files.rs `llm` definitions (Markdown parse/serialize/scan)
│ ├─ src/agents/mbus.rs mission bus (pub/sub + status registry)
│ ├─ src/agents/supervisor.rs planner supervisor
│ ├─ src/instance.rs single instance / shadow windows
│ ├─ src/turn_guard.rs turn budget + tool-failure guard
│ ├─ src/pdf_mentions.rs `@paper.pdf#pages` conversion + cache
│ ├─ src/mcp.rs MCP client
│ ├─ src/skills.rs SKILL.md parsing, skill status
│ ├─ src/workspace_files.rs workspace file listing for `@` mentions
│ ├─ src/workspace.rs `.data` layout
│ ├─ src/backup.rs export/import
│ ├─ src/model_metadata.rs merged capability catalogue
│ ├─ src/update.rs update check/download
│ ├─ src/logger.rs file/terminal logging
│ ├─ src/process_guard.rs child cleanup
│ ├─ src/tools/ tool implementations
│ │ ├─ mod.rs dispatch/schema/tests
│ │ ├─ file_actions.rs
│ │ ├─ patch.rs
│ │ ├─ paths.rs
│ │ ├─ risk.rs
│ │ ├─ scripts.rs run_cmd script library (resolve, metadata, approvals)
│ │ ├─ search.rs
│ │ ├─ serve.rs
│ │ ├─ background.rs
│ │ ├─ memory.rs
│ │ ├─ todos.rs
│ │ ├─ timer.rs
│ │ └─ mcp_self.rs self-built MCP servers (self-evolution mode)
│ ├─ utils/pdf2md-rs/ PDF → Markdown library crate (workspace member)
│ ├─ utils/knowledge_graph/ knowledge graph client library (not wired into the tool set)
│ ├─ capabilities/default.json Tauri permissions
│ └─ tauri.conf.json
├─ scripts/
│ ├─ sync-version.cjs 3-way version sync
│ ├─ gen-changelog.cjs CHANGELOG.md from git tags/commits
│ ├─ gen-wiki.mjs docs/wiki/*.md → docs/site/wiki/**.html
│ ├─ build-msix.ps1 MSIX packaging
│ └─ capture-store-screenshots.ps1
├─ docs/
│ ├─ wiki/ wiki source: nav.json + en/ + zh/
│ ├─ site/ GitHub Pages (static, no build step)
│ ├─ gen.py generates site/architecture.html in CI
│ └─ store/ Store listing assets
├─ .github/workflows/ pages.yml / release.yml / store.yml / winget.yml
├─ DESIGN.md UI design spec
├─ AGENTS.md development conventions
└─ CHANGELOG.md generated, do not hand-edit
Database
<workspace>/.data/chat.db main tables:
| Table | Contents |
|---|---|
history |
Session messages, tool calls, attachments, reasoning |
session_meta |
Title, favorite, archived |
session_summaries |
Compressed session summaries |
api_requests |
Metrics for each LLM request |
interaction_log |
LLM/tool/MCP interaction details |
agent_missions |
Sub-agent missions |
agent_tasks |
Tasks inside a mission |
agent_bus_messages |
Mission-bus publish history (replay for the Mission panel) |
Development commands
# Install dependencies
npm install
cargo install tauri-cli --version "^2"
# Development (Vite :1420 + Tauri)
npm run tauri dev
# Frontend only
npm run dev
# Type check
npx tsc --noEmit
# Frontend build (no git tag needed)
npx vite build
# Rust check
cargo check --manifest-path src-tauri/Cargo.toml
# Rust unit tests
cargo test --manifest-path src-tauri/Cargo.toml
# Production build (requires the newest git tag)
npm run tauri build
Documentation and packaging:
python3 docs/gen.py # architecture.html into docs/site
node scripts/gen-wiki.mjs # docs/wiki → docs/site/wiki
node scripts/gen-changelog.cjs # regenerate CHANGELOG.md from git
pwsh scripts/build-msix.ps1 # MSIX bundle (Windows + makeappx)
Version sync:
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
Release flow
-
Merge into
main. -
Tag and push:
git tag v3.3.3 git push origin v3.3.3 -
.github/workflows/release.ymlbuilds on 4 runners. -
The first platform publishes the Release; the rest upload afterwards.
-
store.ymlbuilds the.msixworkflow artifact; it is not attached to the Release. -
winget.ymlis inactive for now: it submits only once the package is accepted intowinget-pkgsandWINGET_TOKENexists.
See Installation and Build and Updates.
Roadmap
From the README:
- add model-provider presets (OpenAI / Azure / local gateways);
- tool invocation auditing and replay;
- skill signing and publishing;
- end-to-end tests and security baseline scans.
Contributing
- Read
DESIGN.mdbefore changing UI: use only the tokens insrc/App.css; 4px radii, a single Electric Blue accent, no shadows, one motion curve. - Update the schema and tests when changing Rust tools.
- When adding a Tauri plugin, add the crate, register
.plugin(...), and add the permission tocapabilities/default.json(Tauri 2 denies by default). - Wiki pages live in
docs/wiki/{en,zh}/*.md; the HTML underdocs/site/wiki/is generated and must not be committed. Runnode scripts/gen-wiki.mjsafter editing. - Before committing, run
npx tsc --noEmitandcargo check; runcargo testfor tool logic. - Never commit real API keys or user data.
License
MIT. See LICENSE in the repository.
Related documents
README.md/README.zh.md: project introduction and quick startAGENTS.md: development conventions, architecture and commandsDESIGN.md: UI design specconfig.example.md: config field examplesCHANGELOG.md: generated release notes