git:20260113.8fd50e4 to git:20260312.5c869f3

1 added, 189 removed. Audit B to B.

- # CLAUDE.md

- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

- ## Project Overview

- DeepChat is an open-source AI agent platform built with Electron + Vue 3 + TypeScript. It supports multiple cloud and local LLM providers, MCP (Model Context Protocol) tool calling, ACP (Agent Client Protocol) agent integration, and multi-window/multi-tab architecture.

- ## Development Commands

- ### Setup

- ```bash

- pnpm install # Install dependencies (Node.js >= 20.19.0, pnpm >= 10.11.0)

- pnpm run installRuntime # Install runtime binaries (uv, node, ripgrep)

- ```

- ### Development

- ```bash

- pnpm run dev # Start development server with HMR

- pnpm run dev:inspect # Start with debug inspector (port 9229)

- pnpm run dev:linux # Start on Linux (no sandbox)

- ```

- ### Code Quality

- ```bash

- pnpm run lint # Lint with OxLint

- pnpm run format # Format with Prettier

- pnpm run typecheck # Type check all code

- pnpm run typecheck:node # Type check main process only

- pnpm run typecheck:web # Type check renderer process only

- ```

- **After completing a feature, always run:**

- ```bash

- pnpm run format && pnpm run lint

- ```

- ### Testing

- ```bash

- pnpm test # Run all tests

- pnpm test path/to/file.test.ts # Run a single test file

- pnpm test:main # Main process tests only

- pnpm test:renderer # Renderer process tests only

- pnpm test:coverage # Generate coverage report

- pnpm test:watch # Watch mode

- ```

- ### Building

- ```bash

- pnpm run build # Build for production (includes typecheck)

- pnpm run build:win # Windows

- pnpm run build:mac # macOS

- pnpm run build:linux # Linux

- # Architecture-specific: build:win:x64, build:win:arm64, build:mac:x64, build:mac:arm64, etc.

- ```

- ### Internationalization

- ```bash

- pnpm run i18n # Check i18n completeness (source: zh-CN)

- pnpm run i18n:en # Check i18n completeness (source: en-US)

- pnpm run i18n:types # Generate TypeScript types for i18n keys

- ```

- ## Architecture Overview

- ```

- ┌─────────────────────────────────────────────────────────────┐

- │ Electron Main (TS) │

- │ Presenters: window/tab/thread/config/llm/mcp/knowledge/ │

- │ sync/oauth/deeplink/floating button │

- │ Storage: SQLite chat.db, ElectronStore settings, backups │

- └───────────────┬─────────────────────────────────────────────┘

- │ IPC (contextBridge + EventBus)

- ┌───────────────▼─────────────────────────────────────────────┐

- │ Preload (strict API) │

- └───────────────┬─────────────────────────────────────────────┘

- │ Typed presenters via `usePresenter`

- ┌───────────────▼─────────────────────────────────────────────┐

- │ Renderer (Vue 3 + Pinia + Tailwind + shadcn/ui) │

- │ Shell UI, chat flow, ACP workspace, MCP console, settings │

- └─────────────────────────────────────────────────────────────┘

- ```

- ### Core Patterns

- **Presenter Pattern**: All system capabilities are in main-process presenters (`src/main/presenter/`). The renderer calls them via the typed `usePresenter` hook through the preload bridge.

- **Multi-Window Multi-Tab**: WindowPresenter and TabPresenter manage Electron windows/BrowserViews with detach/move support. EventBus fans out cross-process events.

- **Data Boundaries**: Chat data in SQLite (`app_db/chat.db`), settings in Electron Store, knowledge bases in DuckDB. Renderer never touches filesystem directly.

- ### Key Presenters

- - **LLMProviderPresenter**: Streaming, rate limits, provider instances (cloud/local/ACP), model discovery, agent loop

- - **McpPresenter**: MCP server lifecycle, tool/prompt/resource management, supports StreamableHTTP/SSE/Stdio

- - **ThreadPresenter**: Conversation session management and LLM coordination

- - **ConfigPresenter**: Unified configuration management

- - **WindowPresenter/TabPresenter**: Window and tab lifecycle

- ### LLM Provider Architecture (Two Layers)

- 1. **Agent Loop Layer** (`llmProviderPresenter/index.ts`): Multi-turn tool calling, tool execution via McpPresenter, standardized frontend events

- 2. **Provider Layer** (`llmProviderPresenter/providers/*.ts`): Provider-specific API interactions, MCP tool conversion, streaming normalization

- ## Code Structure

- ```

- src/main/ # Main process

- presenter/ # Core business logic by domain

- eventbus.ts # Central event coordination

- src/preload/ # Context-isolated IPC bridge

- src/renderer/

- src/ # Main app UI (Vue 3 + Composition API)

- shell/ # Tab management shell UI

- floating/ # Floating button interface

- src/shared/ # Shared types/utilities and presenter contracts

- test/ # Vitest suites (main/, renderer/)

- docs/ # Design docs and guides

- ```

- ## Development Guidelines

- ### Code Standards

- - **Language**: English for all logs and comments

- - **TypeScript**: Strict type checking

- - **Vue 3**: Composition API with `<script setup>` syntax

- - **State Management**: Pinia stores

- - **Styling**: Tailwind CSS (v4) with shadcn/ui (reka-ui)

- - **i18n**: All user-facing strings must use i18n keys (supports 12 languages)

- ### IPC Communication

- ```typescript

- // Renderer → Main: Use usePresenter composable

- const presenter = usePresenter()

- await presenter.configPresenter.getSetting('key')

- // Main → Renderer: Use EventBus

- eventBus.sendToRenderer(CONFIG_EVENTS.SETTING_CHANGED, SendTarget.ALL_WINDOWS, payload)

- ```

- ### Git Hooks

- Pre-commit automatically runs:

- - `lint-staged` - Format and lint staged files

- - `typecheck` - TypeScript type checking

- - Commit message validation

- ### Specification-Driven Development

- For features, use lightweight spec artifacts under `docs/specs/<feature>/` (spec.md, plan.md, tasks.md). Resolve `[NEEDS CLARIFICATION]` markers before coding. See [docs/spec-driven-dev.md](docs/spec-driven-dev.md).

- ## Common Tasks

- ### Adding New LLM Provider

- 1. Create provider in `src/main/presenter/llmProviderPresenter/providers/`

- 2. Implement `coreStream` method following standardized event interface

- 3. Add provider config in `configPresenter/providers.ts`

- 4. Update renderer provider settings UI

- ### Adding New MCP Tool

- 1. Implement in `src/main/presenter/mcpPresenter/inMemoryServers/`

- 2. Register in `mcpPresenter/index.ts`

- ### UI Changes

- When making UI/layout changes, create ASCII diagrams showing BEFORE/AFTER layouts and seek approval before implementation.

- ## Platform Notes

- - **Windows**: Enable Developer Mode for symlink support; install Visual Studio Build Tools

- - **macOS**: Code signing in `scripts/notarize.js`

- - **Linux**: Use `pnpm run dev:linux` (no sandbox)

- ## Git Commit Guidelines

- - Do not include AI co-authoring information (e.g., "Co-Authored-By: Claude")

- - Follow conventional commit format

- - PRs should target the `dev` branch

+ AGENTS.md