The desktop UI lives in src/ with React + TypeScript. Use src/app/ for bootstrap, routing, providers, and global styles; src/pages/ for route-level surfaces such as onboarding and workbench entry points; src/modules/ for domain areas such as workbench shell, onboarding, settings center, and extensions center; src/features/ for platform-facing features like terminal and system metadata; src/components/ for AI Elements such as messages, prompt input, code blocks, reasoning, plans, tools, and confirmations; src/shared/ for reusable UI, types, config, and helpers (including src/shared/constants/tool-names.ts for shared tool name classification); and src/services/ for bridge and streaming integrations. Static assets belong in public/. In src/modules/workbench-shell/ui/, keep large workbench surfaces as orchestrators and place extracted presentation helpers and small logic helpers beside them, such as runtime-thread-surface-*, runtime-thread-surface-state.ts, goal-status-bar.tsx, long-message-body.tsx, dashboard-sidebar.tsx, dashboard-overlays.tsx, dashboard-terminal-orchestrator.tsx, dashboard-workbench-logic.ts, and thread-rename-input.tsx. Tauri/Rust code lives in src-tauri/src/: extension host/runtime code is organized under src-tauri/src/extensions/ with mod.rs as the facade plus config_io.rs, plugins.rs, mcp.rs, skills.rs, marketplace.rs, and runtime_tools.rs; agent runtime orchestration stays under src-tauri/src/core/ with focused companion modules such as agent_session_execution.rs, agent_session_*, agent_run_compaction.rs, other agent_run_* modules, goal_manager.rs (persistent goal lifecycle), context_compression.rs (context compaction with LLM summarization), gateway_supervisor.rs (gateway subprocess lifecycle), index_manager.rs (workspace file tree cache and local full-text search), plan_checkpoint.rs (implementation plan artifacts), catalog_model_id_normalizer.rs (model ID normalization for provider matching), and agent_session_compression.rs; tool executors live under src-tauri/src/core/executors/ with mod.rs as the unified dispatch facade plus filesystem.rs, search.rs, web_search.rs, edit.rs, process.rs, git.rs, terminal.rs, output_sanitizer.rs, and truncation.rs; subagent delegation lives under src-tauri/src/core/subagent/ with mod.rs as the facade plus orchestrator.rs, parallel_contract.rs, review_contract.rs, and runtime_orchestration.rs; gateway code lives under src-tauri/src/gateway/ with mod.rs as the facade exposing the IM channel event pump, plus config.rs, traits.rs, command_router.rs, gateway_runner.rs, message_formatter.rs, approval_bridge.rs, user_session.rs, and platforms/ containing weixin.rs, weixin_auth.rs, weixin_media.rs, and wecom.rs; ACP server code lives under src-tauri/src/acp/ with mod.rs as the facade exposing run_stdio() / run_http(), plus transport.rs (stdio and HTTP/WebSocket transports), session_map.rs (ACP session ↔ thread bidirectional index), agent_handlers.rs (JSON-RPC method handlers), event_bridge.rs (internal ThreadStreamEvent → ACP SessionUpdate mapping), and permission_bridge.rs (tool approval delegation to ACP clients). Use src-tauri/src/ipc/ for frontend event/channel bridge code, keep bundled provider catalog snapshots in src-tauri/bundled-catalog/, migrations in src-tauri/migrations/, backend integration tests in src-tauri/tests/, and design references in docs/.
npm run dev— start the full Tauri desktop app.npm run dev:web— run the Vite frontend only.npm run build:web— type-check and bundle web assets.npm run build— produce desktop binaries.npm run typecheck— run TypeScript validation for UI changes.npm run test:unit— run Vitest unit tests for frontend utilities and model helpers.cargo test --locked --manifest-path src-tauri/Cargo.toml— run Rust integration tests with the committed lockfile.cargo fmt --check --manifest-path src-tauri/Cargo.toml— verify Rust formatting before opening a PR; usecargo fmt --manifest-path src-tauri/Cargo.tomlto apply formatting locally.
- Frontend — run
npm run test:unit -- --coverageto generate a Vitest +@vitest/coverage-v8report. The summary is printed to the terminal; detailed HTML reports are written tocoverage/. - Backend — run
cargo llvm-cov --manifest-path src-tauri/Cargo.toml(requirescargo-llvm-cov) to generate line/branch coverage for Rust integration tests. Add--htmlto open a detailed report, or--textfor a terminal summary.
Pull requests targeting master run .github/workflows/ci.yml, which validates commit messages, installs dependencies with npm ci, runs npm run typecheck, npm run test:unit, npm run build:web, checks Rust formatting with cargo fmt --check --manifest-path src-tauri/Cargo.toml, and runs cargo test --locked --manifest-path src-tauri/Cargo.toml. Keep local verification aligned with those commands when possible. .github/workflows/pr-review.yml optionally runs tiylabs/code-review-agent-action@v3 when LLM configuration is available; review configuration changes should preserve its include/exclude globs, allowlist, confidence threshold, and bounded round/model-call limits unless there is a deliberate reason to change them.
Use 2-space indentation in TypeScript/TSX. Prefer functional React components with named exports. File names should be kebab-case, for example workbench-top-bar.tsx; components use PascalCase; hooks use use.... Prefer the @/ alias over deep relative imports. Keep code close to the feature unless it is clearly reusable. Reuse design tokens from src/app/styles/globals.css and align UI work with docs/design-spec.md. In Rust, preserve the existing commands/, core/, model/, and persistence/ separation.
Frontend utility and model regressions can be covered with Vitest tests colocated under src/; UI changes should still pass npm run typecheck and receive manual verification. If project dependencies are missing, incomplete, or otherwise not installed in a clean/safe state for validation, install them with npm ci before running verification commands such as npm run typecheck, npm run test:unit, and any other relevant checks. Rust tests live in src-tauri/tests/*.rs; use module-oriented names such as agent_run.rs. Add or update backend integration tests whenever command, persistence, runtime, task-board, attachment, workspace/worktree, provider catalog, tool-gateway, ACP server, goal, gateway, subagent, or web-search behavior changes.
Follow Conventional Commits: type(scope): short summary, for example feat(agent-session): enhance workspace context. Common types include feat, fix, refactor, and chore. Keep scopes tied to the area changed. Pull requests should include a concise summary, linked issue or design doc when relevant, commands run, and screenshots or GIFs for visible UI changes. Call out migrations, capability updates, or setup steps explicitly.
The constant SETTINGS_STORAGE_SCHEMA_VERSION in src/modules/settings-center/model/defaults.ts now controls only the schema version of the frontend local UI storage key tiy-agent-local-ui-settings, which is read and written by src/modules/settings-center/model/settings-storage.ts. When the stored schema version is lower than this constant, the app discards that local UI payload and falls back to the code-defined defaults for the general and terminal sections.
You must increment this value whenever you change the shape or built-in defaults of the data stored in this local UI payload, including additions, removals, renames, or default-value changes under the general or terminal sections. Without the increment, existing users may keep stale localStorage data for those UI-only settings.
Do not use this version as a catch-all settings migration switch anymore. It no longer governs the full settings model, built-in slash command prompts, agent profiles, providers, workspaces, or other Rust/file/database-backed settings. Changes to those areas require their own migration or compatibility handling instead of bumping SETTINGS_STORAGE_SCHEMA_VERSION.
Because incrementing this value resets only the cached local UI settings payload, use it only when existing general or terminal local storage data must be invalidated or reshaped.
After completing a task, always run the relevant formatting and validation commands before committing: cargo fmt --check --manifest-path src-tauri/Cargo.toml for Rust formatting verification, cargo test --locked --manifest-path src-tauri/Cargo.toml for Rust behavior changes, npm run typecheck for TypeScript/TSX changes, and npm run test:unit when frontend utility or model tests were added or affected. Use cargo fmt --manifest-path src-tauri/Cargo.toml to apply Rust formatting before re-running the check. Fix all warnings and errors before finalizing the commit.
Address the user as Buddy in all collaborator-facing responses for this repository. Pay special attention to cross-platform differences when coding, and preserve cross-platform compatibility in implementation choices.