From 2b20762690f7b77d11764dabe79952259cc6c57f Mon Sep 17 00:00:00 2001 From: limityan Date: Wed, 22 Apr 2026 22:49:37 +0800 Subject: [PATCH 1/2] docs: add and refine agent guides --- AGENTS-CN.md | 203 ++++++++++++++++++++----------- AGENTS.md | 220 ++++++++++++++++++++-------------- BitFun-Installer/AGENTS-CN.md | 41 +++++++ BitFun-Installer/AGENTS.md | 41 +++++++ src/apps/desktop/AGENTS-CN.md | 58 +++++++++ src/apps/desktop/AGENTS.md | 58 +++++++++ src/crates/core/AGENTS-CN.md | 52 ++++++++ src/crates/core/AGENTS.md | 52 ++++++++ src/web-ui/AGENTS-CN.md | 43 +++++++ src/web-ui/AGENTS.md | 43 +++++++ tests/e2e/AGENTS-CN.md | 37 ++++++ tests/e2e/AGENTS.md | 37 ++++++ 12 files changed, 719 insertions(+), 166 deletions(-) create mode 100644 BitFun-Installer/AGENTS-CN.md create mode 100644 BitFun-Installer/AGENTS.md create mode 100644 src/apps/desktop/AGENTS-CN.md create mode 100644 src/apps/desktop/AGENTS.md create mode 100644 src/crates/core/AGENTS-CN.md create mode 100644 src/crates/core/AGENTS.md create mode 100644 src/web-ui/AGENTS-CN.md create mode 100644 src/web-ui/AGENTS.md create mode 100644 tests/e2e/AGENTS-CN.md create mode 100644 tests/e2e/AGENTS.md diff --git a/AGENTS-CN.md b/AGENTS-CN.md index b87de1169..7a638fa32 100644 --- a/AGENTS-CN.md +++ b/AGENTS-CN.md @@ -1,70 +1,120 @@ -# AGENTS.md +# AGENTS-CN.md -## 项目概述 +## 概览 -BitFun 是 AI 代理驱动的编程环境，使用 Rust 和 TypeScript 构建，采用多平台架构（桌面端/CLI/服务器）共享核心库。 +BitFun 是一个由 Rust workspace 与共享 React 前端组成的项目。 -### 架构 +仓库核心原则：**先保持产品逻辑平台无关，再通过平台适配层对外暴露能力**。 -- **src/crates/events** - 事件定义（平台无关） -- **src/crates/core** - 核心业务逻辑（95%+ 代码复用） - - `agentic/` - 代理系统（会话、工具、执行） - - `service/` - 工作区、配置、文件系统、终端、Git - - `infrastructure/` - AI 客户端、存储、日志、事件 -- **src/crates/transport** - 传输适配器（CLI、Tauri、WebSocket） -- **src/crates/api-layer** - 平台无关处理器 -- **src/apps/desktop** - Tauri 2.0 桌面应用 -- **src/apps/cli** - 终端 UI（WIP） -- **src/apps/server** - Web 服务器（Axum + WebSocket）（WIP） -- **src/web-ui** - React 前端 - - `infrastructure/` - 主题、国际化、配置、状态管理、API 适配器 - - `component-library/` - 共享 UI 组件 - - `tools/` - 功能模块（编辑器、Git、终端、Mermaid...） - - `flow_chat/` - 聊天界面 - - `locales/` - 翻译文件（en-US、zh-CN） +- `src/crates/core`：共享产品逻辑中心 +- `src/crates/transport`：Tauri / WebSocket / CLI 适配层 +- `src/crates/api-layer`：共享处理器与 DTO +- `src/apps/desktop`：Tauri 桌面宿主应用 +- `src/apps/server`：web 后端运行时 +- `src/apps/cli`：CLI 运行时 +- `src/web-ui`：桌面端与 server/web 共享前端 +- `BitFun-Installer`：独立安装器应用 +- `tests/e2e`：桌面端 E2E 测试 -### 核心设计原则 +## 3 步快速上手 -1. **依赖注入** - 服务通过构造函数接收依赖 -2. **EventEmitter 模式** - 使用 `Arc` 而非 `AppHandle` -3. **TransportAdapter 模式** - 跨平台抽象通信 -4. **平台无关核心** - Core 不包含平台特定依赖 +1. 在修改架构敏感代码前，先阅读 `README.md`、`CONTRIBUTING.md` 和本文件。 +2. 常规本地开发使用 `pnpm run desktop:dev`；仅前端改动使用 `pnpm run dev:web`。 +3. 改完后按下方最小验证集合执行检查。 -### 技术栈 +## 核心命令 -- **后端**: Rust 2021, Tokio, Tauri 2.0, Axum -- **前端**: React 18, TypeScript, Vite, Zustand +```bash +# 安装 +pnpm install +pnpm run e2e:install + +# 主要开发流程 +pnpm run desktop:dev +pnpm run dev:web +pnpm run cli:dev +pnpm run installer:dev + +# 前端 +pnpm run lint:web +pnpm run type-check:web +pnpm --dir src/web-ui run test:run +pnpm run build:web + +# Rust +cargo check --workspace +cargo test --workspace +cargo test -p bitfun-core -- --nocapture + +# Desktop / E2E +cargo build -p bitfun-desktop +pnpm run e2e:test:l0 +pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/.spec.ts" +``` -## 开发命令 +## 架构 -```bash -# 桌面端 -pnpm run desktop:dev # 开发模式 +### 后端链路 + +大多数功能建议按这个顺序追踪： + +1. `src/web-ui` 或应用入口 +2. `src/apps/desktop/src/api/*` 或 server routes +3. `src/crates/api-layer` +4. `src/crates/transport` +5. `src/crates/core` + +### `bitfun-core` -# E2E -pnpm run e2e:test +`src/crates/core` 是代码库中心。 + +重要区域： + +- `agentic/`：agents、prompts、tools、sessions、execution、persistence +- `service/`：config、filesystem、terminal、git、LSP、MCP、remote connect、project context、AI memory +- `infrastructure/`：AI clients、app paths、event system、storage、debug log server + +Agent 运行时心智模型： + +```text +SessionManager → Session → DialogTurn → ModelRound ``` -## 关键规则 +会话数据保存在 `.bitfun/sessions/{session_id}/`。 -### 日志规范 +### 前端与桌面端边界 -**规则：** 仅英文、禁止 emoji、结构化数据、避免冗余日志 +- `src/web-ui` 同时服务 Tauri 桌面端和 server/web +- 不要在 UI 组件里直接调用 Tauri API；应通过 adapter / infrastructure 层访问 +- 仅桌面端集成应放在 `src/apps/desktop`，再通过 transport / API layer 回流到共享逻辑 +- 在共享 core 中避免使用 `tauri::AppHandle` 等宿主 API；优先使用 `bitfun_events::EventEmitter` 等共享抽象 -- **前端**: `src/web-ui/LOGGING.md` - 使用 `createLogger('ModuleName')` -- **后端**: `src/crates/LOGGING.md` - 使用 `log::{info, debug, ...}` 宏 +## 仓库规则 -### 传输层 +### 日志 -**核心代码中禁止使用平台特定 API：** -- ❌ `use tauri::AppHandle` -- ✅ `use bitfun_events::EventEmitter` +日志必须只用英文，且不能使用 emoji。 -### Tauri 命令 +- 前端：`src/web-ui/LOGGING.md` +- 后端：`src/crates/LOGGING.md` -**命名规范：** 命令 `snake_case`，Rust `snake_case`，TypeScript `camelCase` +示例： -**始终使用结构化请求格式：** +```ts +const log = createLogger('ModuleName'); +log.info('Loaded items', { count }); +``` + +```rust +use log::{debug, error, info, trace, warn}; +info!("Registered adapter for session {}", session_id); +``` + +### Tauri command + +- command 名称：`snake_case` +- Rust 侧：`snake_case` +- TypeScript 可以用 `camelCase` 包装，但调用 Rust 时要传结构化 `request` ```rust #[tauri::command] @@ -74,44 +124,51 @@ pub async fn your_command( ) -> Result ``` -```typescript +```ts await api.invoke('your_command', { request: { ... } }); ``` -### 前端复用 +### 更细粒度规则 -开发前端功能时，复用现有基础设施： -- **主题**: `infrastructure/theme/` - useTheme, useThemeToggle -- **国际化**: `infrastructure/i18n/` + `locales/` - useI18n, t() -- **组件**: `component-library/` - 共享 UI 组件 -- **状态**: 各模块内的 Zustand Store +- 如果修改 `src/crates/ai-adapters`，需要运行 `src/crates/core/tests` 中的 stream integration tests +- 如果修改 `src/crates/core/src/agentic/execution/stream_processor.rs`，结束前需要运行 stream integration tests -## 核心组件 +## 先看哪里 -### 代理系统 +- Agent mode：`src/crates/core/src/agentic/agents/`、`src/crates/core/src/agentic/agents/prompts/`、`src/web-ui/src/locales/*/settings/modes.json` +- Tool：`src/crates/core/src/agentic/tools/implementations/`、`src/crates/core/src/agentic/tools/registry.rs` +- MCP / LSP / remote：`src/crates/core/src/service/mcp/`、`src/crates/core/src/service/lsp/`、`src/crates/core/src/service/remote_connect/`、`src/crates/core/src/service/remote_ssh/` +- 桌面端 API：`src/apps/desktop/src/api/`、`src/crates/api-layer/src/`、`src/crates/transport/src/adapters/tauri.rs` +- Web/server 通信：`src/web-ui/src/infrastructure/api/`、`src/crates/transport/src/adapters/websocket.rs`、`src/apps/server/src/routes/`、`src/apps/server/src/rpc_dispatcher.rs` -``` -SessionManager → Session → DialogTurn → ModelRound -``` +## 验证 + +| 改动类型 | 最低验证要求 | +| --- | --- | +| 前端 UI、状态、适配层或多语言文案 | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` | +| `core`、`transport`、`api-layer` 或共享服务中的 Rust 逻辑 | `cargo check --workspace && cargo test --workspace` | +| 桌面端集成、Tauri API、browser/computer-use 或桌面专属行为 | `cargo check -p bitfun-desktop && cargo test -p bitfun-desktop` | +| 被桌面端 smoke/functional 流覆盖的行为 | `cargo build -p bitfun-desktop` 后运行最接近的 E2E spec，或 `pnpm run e2e:test:l0` | +| `src/crates/ai-adapters` | 运行上面相关 Rust 检查，**并且**运行 `src/crates/core/tests` 中的 stream integration tests | +| 安装器应用 | `pnpm run installer:build` | -- `ConversationCoordinator` - 协调轮次 -- `ExecutionEngine` - 多轮循环 -- `ToolPipeline` - 工具并发执行 +## Agent 文档覆盖 -### 会话持久化 +这是仓库级总指南。 -位置：`.bitfun/sessions/{session_id}/` +规则优先级： -### 工具开发 +- 进入具体目录后，优先遵循离目标文件最近的 `AGENTS.md` / `AGENTS-CN.md` +- 如果局部文档与本文件冲突，以更具体、更近的文档为准 -在 `agentic/tools/registry.rs` 注册： -1. 实现 `Tool` trait -2. 定义输入/输出类型 -3. 处理流式传输（如适用） +进入具体模块后，优先看最近的 agent 文档： -### 添加代理 +- `src/web-ui/AGENTS.md` +- `src/crates/core/AGENTS.md` +- `src/apps/desktop/AGENTS.md` +- `tests/e2e/AGENTS.md` +- `BitFun-Installer/AGENTS.md` +- `src/crates/ai-adapters/AGENTS.md` +- `src/crates/core/src/agentic/execution/AGENTS.md` -在 `agentic/agents/`： -1. 创建代理文件 -2. 在 `prompts/` 定义提示词 -3. 在 `registry.rs` 注册 +更新时未发现顶层 `CLAUDE.md`、`.cursorrules`、`.cursor/rules/` 或 `.github/copilot-instructions.md`。 diff --git a/AGENTS.md b/AGENTS.md index 9fb1583cc..717d8ce69 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,70 +1,120 @@ # AGENTS.md -## Project Overview +## Overview -BitFun is an AI agent-driven programming environment built with Rust and TypeScript, using multi-platform architecture (Desktop/CLI/Server) sharing a common core library. +BitFun is a Rust workspace plus a shared React frontend. -### Architecture +Repository rule: **keep product logic platform-agnostic, then expose it through platform adapters**. -- **src/crates/events** - Event definitions (platform-agnostic) -- **src/crates/core** - Core business logic (95%+ code reuse) - - `agentic/` - Agent system (session, tools, execution) - - `service/` - Workspace, Config, FileSystem, Terminal, Git - - `infrastructure/` - AI client, storage, logging, events -- **src/crates/transport** - Transport adapters (CLI, Tauri, WebSocket) -- **src/crates/api-layer** - Platform-agnostic handlers -- **src/apps/desktop** - Tauri 2.0 desktop app -- **src/apps/cli** - Terminal UI（WIP） -- **src/apps/server** - Web server (Axum + WebSocket)（WIP） -- **src/web-ui** - React frontend - - `infrastructure/` - Theme, I18n, Config, State management, API adapters - - `component-library/` - Shared UI components - - `tools/` - Feature modules (editor, git, terminal, mermaid...) - - `flow_chat/` - Chat UI - - `locales/` - Translation files (en-US, zh-CN) +- `src/crates/core`: shared product logic center +- `src/crates/transport`: Tauri / WebSocket / CLI adapters +- `src/crates/api-layer`: shared handlers and DTOs +- `src/apps/desktop`: Tauri host app +- `src/apps/server`: web backend runtime +- `src/apps/cli`: CLI runtime +- `src/web-ui`: shared frontend for desktop and server/web +- `BitFun-Installer`: separate installer app +- `tests/e2e`: desktop E2E tests -### Key Design Principles +## 3-step onboarding -1. **Dependency Injection** - Services receive dependencies via constructors -2. **EventEmitter Pattern** - Use `Arc` not `AppHandle` -3. **TransportAdapter Pattern** - Abstract communication across platforms -4. **Platform Agnostic Core** - No platform-specific dependencies in core +1. Read `README.md`, `CONTRIBUTING.md`, and this file before architecture-sensitive changes. +2. Use `pnpm run desktop:dev` for normal local development, or `pnpm run dev:web` for frontend-only work. +3. After changes, run the smallest matching verification set below. -### Tech Stack +## Core commands -- **Backend**: Rust 2021, Tokio, Tauri 2.0, Axum -- **Frontend**: React 18, TypeScript, Vite, Zustand +```bash +# Install +pnpm install +pnpm run e2e:install + +# Main dev flows +pnpm run desktop:dev +pnpm run dev:web +pnpm run cli:dev +pnpm run installer:dev + +# Frontend +pnpm run lint:web +pnpm run type-check:web +pnpm --dir src/web-ui run test:run +pnpm run build:web + +# Rust +cargo check --workspace +cargo test --workspace +cargo test -p bitfun-core -- --nocapture + +# Desktop / E2E +cargo build -p bitfun-desktop +pnpm run e2e:test:l0 +pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/.spec.ts" +``` -## Development Commands +## Architecture -```bash -# Desktop -pnpm run desktop:dev # Dev mode +### Backend flow + +Trace most features in this order: + +1. `src/web-ui` or app entrypoint +2. `src/apps/desktop/src/api/*` or server routes +3. `src/crates/api-layer` +4. `src/crates/transport` +5. `src/crates/core` + +### `bitfun-core` + +`src/crates/core` is the center of the codebase. + +Important areas: -# E2E -pnpm run e2e:test +- `agentic/`: agents, prompts, tools, sessions, execution, persistence +- `service/`: config, filesystem, terminal, git, LSP, MCP, remote connect, project context, AI memory +- `infrastructure/`: AI clients, app paths, event system, storage, debug log server + +Agent runtime mental model: + +```text +SessionManager → Session → DialogTurn → ModelRound ``` -## Critical Rules +Session data is stored under `.bitfun/sessions/{session_id}/`. + +### Frontend and desktop boundaries + +- `src/web-ui` serves both Tauri desktop and server/web +- Do not call Tauri APIs directly from UI components; go through the adapter/infrastructure layer +- Desktop-only integrations belong in `src/apps/desktop`, then flow back through transport/API layers +- In shared core, avoid host-specific APIs such as `tauri::AppHandle`; use shared abstractions such as `bitfun_events::EventEmitter` + +## Repository-specific rules ### Logging -**Rules:** English only, no emojis, structured data, avoid verbose logging +Logs must be English-only, with no emojis. -- **Frontend**: `src/web-ui/LOGGING.md` - Use `createLogger('ModuleName')` -- **Backend**: `src/crates/LOGGING.md` - Use `log::{info, debug, ...}` macros +- Frontend: `src/web-ui/LOGGING.md` +- Backend: `src/crates/LOGGING.md` -### Transport Layer +Patterns: -**Never use platform-specific APIs in core code:** -- ❌ `use tauri::AppHandle` -- ✅ `use bitfun_events::EventEmitter` +```ts +const log = createLogger('ModuleName'); +log.info('Loaded items', { count }); +``` -### Tauri Commands +```rust +use log::{debug, error, info, trace, warn}; +info!("Registered adapter for session {}", session_id); +``` -**Naming:** Commands `snake_case`, Rust `snake_case`, TypeScript `camelCase` +### Tauri commands -**Always use structured request format:** +- command names: `snake_case` +- Rust side: `snake_case` +- TypeScript may wrap with `camelCase`, but invoke Rust with a structured `request` ```rust #[tauri::command] @@ -74,67 +124,51 @@ pub async fn your_command( ) -> Result ``` -```typescript +```ts await api.invoke('your_command', { request: { ... } }); ``` -### Frontend Reuse - -When developing frontend features, reuse existing infrastructure: -- **Theme**: `infrastructure/theme/` - useTheme, useThemeToggle -- **I18n**: `infrastructure/i18n/` + `locales/` - useI18n, t() -- **Components**: `component-library/` - shared UI components -- **State**: Zustand stores in each module - -## Key Components +### Extra narrow rules -### Agentic System - -``` -SessionManager → Session → DialogTurn → ModelRound -``` +- If you modify `src/crates/ai-adapters`, run the stream integration tests in `src/crates/core/tests` +- If you modify `src/crates/core/src/agentic/execution/stream_processor.rs`, run the stream integration tests before finishing -- `ConversationCoordinator` - Orchestrates turns -- `ExecutionEngine` - Multi-round loop -- `ToolPipeline` - Tool execution with concurrency +## Where to look first -### Session Persistence +- Agent modes: `src/crates/core/src/agentic/agents/`, `src/crates/core/src/agentic/agents/prompts/`, `src/web-ui/src/locales/*/settings/modes.json` +- Tools: `src/crates/core/src/agentic/tools/implementations/`, `src/crates/core/src/agentic/tools/registry.rs` +- MCP / LSP / remote: `src/crates/core/src/service/mcp/`, `src/crates/core/src/service/lsp/`, `src/crates/core/src/service/remote_connect/`, `src/crates/core/src/service/remote_ssh/` +- Desktop APIs: `src/apps/desktop/src/api/`, `src/crates/api-layer/src/`, `src/crates/transport/src/adapters/tauri.rs` +- Web/server communication: `src/web-ui/src/infrastructure/api/`, `src/crates/transport/src/adapters/websocket.rs`, `src/apps/server/src/routes/`, `src/apps/server/src/rpc_dispatcher.rs` -Location: `.bitfun/sessions/{session_id}/` +## Verification -### Tool Development +| Change type | Minimum verification | +| --- | --- | +| Frontend UI, state, adapters, or locales | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` | +| Shared Rust logic in `core`, `transport`, `api-layer`, or services | `cargo check --workspace && cargo test --workspace` | +| Desktop integration, Tauri APIs, browser/computer-use, or desktop-only behavior | `cargo check -p bitfun-desktop && cargo test -p bitfun-desktop` | +| Behavior covered by desktop smoke/functional flows | `cargo build -p bitfun-desktop` then the nearest E2E spec or `pnpm run e2e:test:l0` | +| `src/crates/ai-adapters` | Relevant Rust checks above **and** stream integration tests in `src/crates/core/tests` | +| Installer app | `pnpm run installer:build` | -Register in `agentic/tools/registry.rs`: -1. Implement `Tool` trait -2. Define input/output types -3. Handle streaming if applicable +## Agent-doc coverage -### Adding Agents +This is the repository-wide guide. -In `agentic/agents/`: -1. Create agent file -2. Define prompt in `prompts/` -3. Register in `registry.rs` +Rule priority: -## Frontend Debugging +- prefer the nearest matching `AGENTS.md` / `AGENTS-CN.md` for the directory you are changing +- if local guidance conflicts with this file, follow the more specific, nearer document -A local log receiver server is available at `scripts/debug-log-server.mjs`. +Prefer the nearest matching agent doc when present: -**Start the server:** -```bash -node scripts/debug-log-server.mjs -# Listens on http://127.0.0.1:7469, writes logs to debug-agent.log -``` - -**Instrument code (one-liner fetch):** -```typescript -fetch('http://127.0.0.1:7469/log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'file.ts:LINE',message:'desc',data:{k:v},timestamp:Date.now()})}).catch(()=>{}); -``` - -**Clear logs between runs:** -```bash -# Via HTTP -curl -X POST http://127.0.0.1:7469/clear -``` +- `src/web-ui/AGENTS.md` +- `src/crates/core/AGENTS.md` +- `src/apps/desktop/AGENTS.md` +- `tests/e2e/AGENTS.md` +- `BitFun-Installer/AGENTS.md` +- `src/crates/ai-adapters/AGENTS.md` +- `src/crates/core/src/agentic/execution/AGENTS.md` -Logs are written to `debug-agent.log` in project root as NDJSON. The agent reads this file directly — no copy-paste needed. +No top-level `CLAUDE.md`, `.cursorrules`, `.cursor/rules/`, or `.github/copilot-instructions.md` were found when this file was updated. diff --git a/BitFun-Installer/AGENTS-CN.md b/BitFun-Installer/AGENTS-CN.md new file mode 100644 index 000000000..25eeb5b47 --- /dev/null +++ b/BitFun-Installer/AGENTS-CN.md @@ -0,0 +1,41 @@ +# AGENTS-CN.md + +## 适用范围 + +本文件适用于 `BitFun-Installer`。仓库级规则请看顶层 `AGENTS.md`。 + +## 这里最重要的内容 + +`BitFun-Installer` 是独立的 Tauri + React 应用，不属于主 Cargo workspace。 + +模块 README 明确提到的重要区域： + +- `src-tauri/src/installer/commands.rs`：Tauri IPC 与卸载执行 +- `src-tauri/src/installer/registry.rs`：Windows 注册表集成 +- `src-tauri/src/installer/shortcut.rs`：快捷方式创建 +- `src-tauri/src/installer/extract.rs`：压缩包解压 +- `src/hooks/useInstaller.ts`：前端安装流程状态 + +安装流程： + +```text +Language Select → Options → Progress → Model Setup → Theme Setup +``` + +## 命令 + +```bash +pnpm --dir BitFun-Installer run installer:dev +pnpm --dir BitFun-Installer run tauri:dev +pnpm --dir BitFun-Installer run type-check +pnpm --dir BitFun-Installer run build +pnpm --dir BitFun-Installer run installer:build +``` + +## 验证 + +```bash +pnpm --dir BitFun-Installer run type-check && pnpm --dir BitFun-Installer run installer:build +``` + +如果修改了卸载流程，还需要验证 `BitFun-Installer/README.md` 中描述的卸载模式入口。 diff --git a/BitFun-Installer/AGENTS.md b/BitFun-Installer/AGENTS.md new file mode 100644 index 000000000..7f6531283 --- /dev/null +++ b/BitFun-Installer/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md + +## Scope + +This file applies to `BitFun-Installer`. Use the top-level `AGENTS.md` for repository-wide rules. + +## What matters here + +`BitFun-Installer` is a separate Tauri + React app, not part of the main Cargo workspace. + +Important areas called out by the module README: + +- `src-tauri/src/installer/commands.rs`: Tauri IPC and uninstall execution +- `src-tauri/src/installer/registry.rs`: Windows registry integration +- `src-tauri/src/installer/shortcut.rs`: shortcut creation +- `src-tauri/src/installer/extract.rs`: archive extraction +- `src/hooks/useInstaller.ts`: frontend installer state flow + +Install flow: + +```text +Language Select → Options → Progress → Model Setup → Theme Setup +``` + +## Commands + +```bash +pnpm --dir BitFun-Installer run installer:dev +pnpm --dir BitFun-Installer run tauri:dev +pnpm --dir BitFun-Installer run type-check +pnpm --dir BitFun-Installer run build +pnpm --dir BitFun-Installer run installer:build +``` + +## Verification + +```bash +pnpm --dir BitFun-Installer run type-check && pnpm --dir BitFun-Installer run installer:build +``` + +If you modify uninstall flow, also validate the uninstall mode entry points described in `BitFun-Installer/README.md`. diff --git a/src/apps/desktop/AGENTS-CN.md b/src/apps/desktop/AGENTS-CN.md new file mode 100644 index 000000000..443df0040 --- /dev/null +++ b/src/apps/desktop/AGENTS-CN.md @@ -0,0 +1,58 @@ +# AGENTS-CN.md + +## 适用范围 + +本文件适用于 `src/apps/desktop`。仓库级规则请看顶层 `AGENTS.md`。 + +## 这里最重要的内容 + +`src/apps/desktop` 是 Tauri 宿主 / 集成层。 + +主要区域： + +- `src/api/`：Tauri commands +- `src/lib.rs`、`src/main.rs`：应用启动与装配 +- `src/computer_use/`：操作系统相关自动化支持 + +如果改动影响多个运行时共享的产品行为，真正实现通常应放在 `src/crates/core`。 + +## 本模块规则 + +- 保持 Tauri command 一致：名称使用 `snake_case`，调用使用结构化 `request` +- 桌面端专属集成留在这里，不要下沉到共享 core + +推荐命令形状： + +```rust +#[tauri::command] +pub async fn your_command( + state: State<'_, AppState>, + request: YourRequest, +) -> Result +``` + +```ts +await api.invoke('your_command', { request: { ... } }); +``` + +## 命令 + +```bash +pnpm run desktop:dev +cargo check -p bitfun-desktop +cargo test -p bitfun-desktop +cargo build -p bitfun-desktop +pnpm run desktop:build:fast +``` + +## 验证 + +```bash +cargo check -p bitfun-desktop && cargo test -p bitfun-desktop +``` + +如果改动影响启动、WebDriver、browser/computer-use 或打包行为，还需要运行： + +```bash +cargo build -p bitfun-desktop +``` diff --git a/src/apps/desktop/AGENTS.md b/src/apps/desktop/AGENTS.md new file mode 100644 index 000000000..97c6ffced --- /dev/null +++ b/src/apps/desktop/AGENTS.md @@ -0,0 +1,58 @@ +# AGENTS.md + +## Scope + +This file applies to `src/apps/desktop`. Use the top-level `AGENTS.md` for repository-wide rules. + +## What matters here + +`src/apps/desktop` is the Tauri host / integration layer. + +Main areas: + +- `src/api/`: Tauri commands +- `src/lib.rs`, `src/main.rs`: app setup and wiring +- `src/computer_use/`: OS-specific automation support + +If a change affects shared product behavior across runtimes, the implementation likely belongs in `src/crates/core`. + +## Local rules + +- Keep Tauri commands consistent: `snake_case` names, structured `request` +- Keep desktop-only integrations here; do not move them into shared core + +Preferred command shape: + +```rust +#[tauri::command] +pub async fn your_command( + state: State<'_, AppState>, + request: YourRequest, +) -> Result +``` + +```ts +await api.invoke('your_command', { request: { ... } }); +``` + +## Commands + +```bash +pnpm run desktop:dev +cargo check -p bitfun-desktop +cargo test -p bitfun-desktop +cargo build -p bitfun-desktop +pnpm run desktop:build:fast +``` + +## Verification + +```bash +cargo check -p bitfun-desktop && cargo test -p bitfun-desktop +``` + +If the change affects startup, WebDriver, browser/computer-use, or packaged behavior, also run: + +```bash +cargo build -p bitfun-desktop +``` diff --git a/src/crates/core/AGENTS-CN.md b/src/crates/core/AGENTS-CN.md new file mode 100644 index 000000000..552006547 --- /dev/null +++ b/src/crates/core/AGENTS-CN.md @@ -0,0 +1,52 @@ +# AGENTS-CN.md + +## 适用范围 + +本文件适用于 `src/crates/core`。仓库级规则请看顶层 `AGENTS.md`。 + +## 这里最重要的内容 + +`bitfun-core` 是共享产品逻辑中心。 + +主要区域： + +- `src/agentic/`：agents、prompts、tools、sessions、execution、persistence +- `src/service/`：config、filesystem、terminal、git、LSP、MCP、remote connect、project context、AI memory +- `src/infrastructure/`：AI clients、app paths、event system、storage、debug log server + +Agent 运行时心智模型： + +```text +SessionManager → Session → DialogTurn → ModelRound +``` + +## 本模块规则 + +- 共享 core 必须保持平台无关 +- 避免引入 `tauri::AppHandle` 等宿主 API +- 使用 `bitfun_events::EventEmitter` 等共享抽象 +- 桌面端专属集成应放在 `src/apps/desktop`，再通过 transport / API layer 连接回来 + +这里已经有更细粒度规则： + +- `src/crates/ai-adapters/AGENTS.md` +- `src/agentic/execution/AGENTS.md` + +## 命令 + +```bash +cargo check --workspace +cargo test --workspace +cargo test -p bitfun-core -- --nocapture +``` + +## 验证 + +```bash +cargo check --workspace && cargo test --workspace +``` + +额外规则： + +- 如果修改 `src/crates/ai-adapters`，需要运行 `src/crates/core/tests` 中的 stream integration tests +- 如果修改 `src/agentic/execution/stream_processor.rs`，结束前需要运行 stream integration tests diff --git a/src/crates/core/AGENTS.md b/src/crates/core/AGENTS.md new file mode 100644 index 000000000..118391578 --- /dev/null +++ b/src/crates/core/AGENTS.md @@ -0,0 +1,52 @@ +# AGENTS.md + +## Scope + +This file applies to `src/crates/core`. Use the top-level `AGENTS.md` for repository-wide rules. + +## What matters here + +`bitfun-core` is the shared product-logic center. + +Main areas: + +- `src/agentic/`: agents, prompts, tools, sessions, execution, persistence +- `src/service/`: config, filesystem, terminal, git, LSP, MCP, remote connect, project context, AI memory +- `src/infrastructure/`: AI clients, app paths, event system, storage, debug log server + +Agent runtime mental model: + +```text +SessionManager → Session → DialogTurn → ModelRound +``` + +## Local rules + +- Keep shared core platform-agnostic +- Avoid host-specific APIs such as `tauri::AppHandle` +- Use shared abstractions such as `bitfun_events::EventEmitter` +- Desktop-only integrations belong in `src/apps/desktop`, then flow through transport/API layers + +Narrower rules already exist: + +- `src/crates/ai-adapters/AGENTS.md` +- `src/agentic/execution/AGENTS.md` + +## Commands + +```bash +cargo check --workspace +cargo test --workspace +cargo test -p bitfun-core -- --nocapture +``` + +## Verification + +```bash +cargo check --workspace && cargo test --workspace +``` + +Extra rules: + +- if you modify `src/crates/ai-adapters`, run the stream integration tests in `src/crates/core/tests` +- if you modify `src/agentic/execution/stream_processor.rs`, run the stream integration tests before finishing diff --git a/src/web-ui/AGENTS-CN.md b/src/web-ui/AGENTS-CN.md new file mode 100644 index 000000000..a6f7e40cd --- /dev/null +++ b/src/web-ui/AGENTS-CN.md @@ -0,0 +1,43 @@ +# AGENTS-CN.md + +## 适用范围 + +本文件适用于 `src/web-ui`。仓库级规则请看顶层 `AGENTS.md`。 + +## 这里最重要的内容 + +`src/web-ui` 是共享前端，对应两种运行时： + +- Tauri 桌面端 +- 通过 WebSocket / Fetch 适配层访问的 server/web + +大多数改动从这些位置开始： + +- `src/infrastructure/`：adapters、i18n、theme、providers、config +- `src/app/`：应用外壳与顶层装配 +- `src/flow_chat/`：聊天流 UI 与状态 +- `src/tools/`：editor、terminal、git、workspace、file explorer +- `src/shared/`：共享 services、stores、helpers、types +- `src/locales/`：多语言文案 + +## 本模块规则 + +- 不要在 UI 组件里直接调用 Tauri API；应通过 adapter / infrastructure 层访问 +- 新增前端基础设施前，先复用已有的 theme、i18n、component-library 和 Zustand stores +- 遵循 `src/web-ui/LOGGING.md`：仅英文、无 emoji、结构化日志 + +## 命令 + +```bash +pnpm --dir src/web-ui dev +pnpm --dir src/web-ui run lint +pnpm --dir src/web-ui run type-check +pnpm --dir src/web-ui run test:run +pnpm run build:web +``` + +## 验证 + +```bash +pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run +``` diff --git a/src/web-ui/AGENTS.md b/src/web-ui/AGENTS.md new file mode 100644 index 000000000..3f81ddee3 --- /dev/null +++ b/src/web-ui/AGENTS.md @@ -0,0 +1,43 @@ +# AGENTS.md + +## Scope + +This file applies to `src/web-ui`. Use the top-level `AGENTS.md` for repository-wide rules. + +## What matters here + +`src/web-ui` is the shared frontend for: + +- Tauri desktop +- server/web via WebSocket / Fetch adapters + +Most changes start in: + +- `src/infrastructure/`: adapters, i18n, theme, providers, config +- `src/app/`: shell layout and top-level composition +- `src/flow_chat/`: chat flow UI and state +- `src/tools/`: editor, terminal, git, workspace, file explorer +- `src/shared/`: shared services, stores, helpers, types +- `src/locales/`: localized strings + +## Local rules + +- Do not call Tauri APIs directly from UI components; go through the adapter / infrastructure layer +- Reuse existing theme, i18n, component-library, and Zustand stores before adding new frontend primitives +- Follow `src/web-ui/LOGGING.md`: English only, no emojis, structured logs + +## Commands + +```bash +pnpm --dir src/web-ui dev +pnpm --dir src/web-ui run lint +pnpm --dir src/web-ui run type-check +pnpm --dir src/web-ui run test:run +pnpm run build:web +``` + +## Verification + +```bash +pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run +``` diff --git a/tests/e2e/AGENTS-CN.md b/tests/e2e/AGENTS-CN.md new file mode 100644 index 000000000..512545ef2 --- /dev/null +++ b/tests/e2e/AGENTS-CN.md @@ -0,0 +1,37 @@ +# AGENTS-CN.md + +## 适用范围 + +本文件适用于 `tests/e2e`。仓库级规则请看顶层 `AGENTS.md`。 + +## 这里最重要的内容 + +这里是桌面端 E2E 测试，使用 WebDriverIO 和 BitFun 内置 WebDriver。 + +根据 `E2E-TESTING-GUIDE.md`： + +- L0：smoke tests +- L1：functional tests +- L2：已规划，但尚未实现 + +核心规则： + +1. 测试真实用户工作流 +2. 使用 `data-testid` 作为稳定选择器 +3. 遵循 Page Object Model +4. 保持测试独立且幂等 + +## 命令 + +```bash +cargo build -p bitfun-desktop +pnpm --dir tests/e2e install +pnpm --dir tests/e2e run test:l0 +pnpm --dir tests/e2e run test:l0:all +pnpm --dir tests/e2e run test:l1 +pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/.spec.ts" +``` + +## 验证 + +优先运行最窄的相关 spec，必要时再扩大范围。 diff --git a/tests/e2e/AGENTS.md b/tests/e2e/AGENTS.md new file mode 100644 index 000000000..ab713f72f --- /dev/null +++ b/tests/e2e/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +## Scope + +This file applies to `tests/e2e`. Use the top-level `AGENTS.md` for repository-wide rules. + +## What matters here + +Desktop E2E tests built with WebDriverIO plus BitFun's embedded WebDriver. + +Levels from `E2E-TESTING-GUIDE.md`: + +- L0: smoke tests +- L1: functional tests +- L2: planned, not implemented yet + +Core rules: + +1. Test real user workflows +2. Use `data-testid` for stable selectors +3. Follow the Page Object Model +4. Keep tests independent and idempotent + +## Commands + +```bash +cargo build -p bitfun-desktop +pnpm --dir tests/e2e install +pnpm --dir tests/e2e run test:l0 +pnpm --dir tests/e2e run test:l0:all +pnpm --dir tests/e2e run test:l1 +pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/.spec.ts" +``` + +## Verification + +Prefer the narrowest relevant spec first, then broaden only if needed. From cb10b6b090f6a56092c92f68833eb28903cf6fdf Mon Sep 17 00:00:00 2001 From: limityan Date: Wed, 22 Apr 2026 23:39:09 +0800 Subject: [PATCH 2/2] docs: clean up README and AGENTS links --- AGENTS-CN.md | 7 +- AGENTS.md | 7 +- BitFun-Installer/AGENTS-CN.md | 2 + BitFun-Installer/AGENTS.md | 2 + BitFun-Installer/README.md | 97 +++++---- README.md | 6 +- README.zh-CN.md | 6 +- src/apps/desktop/AGENTS-CN.md | 2 + src/apps/desktop/AGENTS.md | 2 + src/apps/relay-server/README.md | 191 ++++++------------ src/apps/server/README.md | 8 +- src/crates/core/AGENTS-CN.md | 2 + src/crates/core/AGENTS.md | 2 + src/web-ui/AGENTS-CN.md | 2 + src/web-ui/AGENTS.md | 2 + src/web-ui/README.md | 20 +- src/web-ui/README.zh-CN.md | 20 +- src/web-ui/public/fonts/README.md | 2 + src/web-ui/public/fonts/README.zh-CN.md | 2 + src/web-ui/src/component-library/README.md | 2 + .../src/component-library/README.zh-CN.md | 2 + .../components/FlowChatCards/README.md | 85 +++++--- .../components/FlowChatCards/README.zh-CN.md | 83 +++++--- .../component-library/components/README.md | 79 ++++---- .../components/README.zh-CN.md | 77 +++---- .../src/component-library/styles/README.md | 2 + .../component-library/styles/README.zh-CN.md | 2 + src/web-ui/src/infrastructure/i18n/README.md | 2 + .../src/infrastructure/i18n/README.zh-CN.md | 2 + src/web-ui/src/tools/lsp/README.md | 44 ++-- tests/e2e/AGENTS-CN.md | 2 + tests/e2e/AGENTS.md | 2 + tests/e2e/README.md | 14 +- tests/e2e/README.zh-CN.md | 14 +- 34 files changed, 410 insertions(+), 384 deletions(-) diff --git a/AGENTS-CN.md b/AGENTS-CN.md index 7a638fa32..0e8fa076f 100644 --- a/AGENTS-CN.md +++ b/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 概览 @@ -135,11 +137,11 @@ await api.invoke('your_command', { request: { ... } }); ## 先看哪里 -- Agent mode：`src/crates/core/src/agentic/agents/`、`src/crates/core/src/agentic/agents/prompts/`、`src/web-ui/src/locales/*/settings/modes.json` +- Agent mode：`src/crates/core/src/agentic/agents/`、`src/crates/core/src/agentic/agents/prompts/`、`src/web-ui/src/locales/*/scenes/agents.json` - Tool：`src/crates/core/src/agentic/tools/implementations/`、`src/crates/core/src/agentic/tools/registry.rs` - MCP / LSP / remote：`src/crates/core/src/service/mcp/`、`src/crates/core/src/service/lsp/`、`src/crates/core/src/service/remote_connect/`、`src/crates/core/src/service/remote_ssh/` - 桌面端 API：`src/apps/desktop/src/api/`、`src/crates/api-layer/src/`、`src/crates/transport/src/adapters/tauri.rs` -- Web/server 通信：`src/web-ui/src/infrastructure/api/`、`src/crates/transport/src/adapters/websocket.rs`、`src/apps/server/src/routes/`、`src/apps/server/src/rpc_dispatcher.rs` +- Web/server 通信：`src/web-ui/src/infrastructure/api/`、`src/crates/transport/src/adapters/websocket.rs`、`src/apps/server/src/routes/`、`src/apps/server/src/main.rs` ## 验证 @@ -171,4 +173,3 @@ await api.invoke('your_command', { request: { ... } }); - `src/crates/ai-adapters/AGENTS.md` - `src/crates/core/src/agentic/execution/AGENTS.md` -更新时未发现顶层 `CLAUDE.md`、`.cursorrules`、`.cursor/rules/` 或 `.github/copilot-instructions.md`。 diff --git a/AGENTS.md b/AGENTS.md index 717d8ce69..5da7b1dd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Overview @@ -135,11 +137,11 @@ await api.invoke('your_command', { request: { ... } }); ## Where to look first -- Agent modes: `src/crates/core/src/agentic/agents/`, `src/crates/core/src/agentic/agents/prompts/`, `src/web-ui/src/locales/*/settings/modes.json` +- Agent modes: `src/crates/core/src/agentic/agents/`, `src/crates/core/src/agentic/agents/prompts/`, `src/web-ui/src/locales/*/scenes/agents.json` - Tools: `src/crates/core/src/agentic/tools/implementations/`, `src/crates/core/src/agentic/tools/registry.rs` - MCP / LSP / remote: `src/crates/core/src/service/mcp/`, `src/crates/core/src/service/lsp/`, `src/crates/core/src/service/remote_connect/`, `src/crates/core/src/service/remote_ssh/` - Desktop APIs: `src/apps/desktop/src/api/`, `src/crates/api-layer/src/`, `src/crates/transport/src/adapters/tauri.rs` -- Web/server communication: `src/web-ui/src/infrastructure/api/`, `src/crates/transport/src/adapters/websocket.rs`, `src/apps/server/src/routes/`, `src/apps/server/src/rpc_dispatcher.rs` +- Web/server communication: `src/web-ui/src/infrastructure/api/`, `src/crates/transport/src/adapters/websocket.rs`, `src/apps/server/src/routes/`, `src/apps/server/src/main.rs` ## Verification @@ -171,4 +173,3 @@ Prefer the nearest matching agent doc when present: - `src/crates/ai-adapters/AGENTS.md` - `src/crates/core/src/agentic/execution/AGENTS.md` -No top-level `CLAUDE.md`, `.cursorrules`, `.cursor/rules/`, or `.github/copilot-instructions.md` were found when this file was updated. diff --git a/BitFun-Installer/AGENTS-CN.md b/BitFun-Installer/AGENTS-CN.md index 25eeb5b47..876efd38e 100644 --- a/BitFun-Installer/AGENTS-CN.md +++ b/BitFun-Installer/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 适用范围 diff --git a/BitFun-Installer/AGENTS.md b/BitFun-Installer/AGENTS.md index 7f6531283..471e4981d 100644 --- a/BitFun-Installer/AGENTS.md +++ b/BitFun-Installer/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Scope diff --git a/BitFun-Installer/README.md b/BitFun-Installer/README.md index b3ec24edf..d299a11ed 100644 --- a/BitFun-Installer/README.md +++ b/BitFun-Installer/README.md @@ -11,6 +11,38 @@ Instead of relying on the generic NSIS wizard UI from Tauri's built-in bundler, - **Full control** — Custom installation logic, right-click context menu, PATH integration - **Cross-platform potential** — Same codebase can target Windows, macOS, and Linux +## Common tasks + +### Install dependencies + +```bash +pnpm install +``` + +Production installer builds call workspace desktop build scripts, so root dependencies are required. + +### Run in dev mode + +```bash +pnpm run tauri:dev +``` + +### Build the full installer + +```bash +pnpm run installer:build +``` + +Use this as the release entrypoint. `pnpm run tauri:build` does not prepare validated payload assets for production. + +### Build installer only + +```bash +pnpm run installer:build:only +``` + +`installer:build:only` requires an existing valid desktop executable in the expected target output path. + ## Architecture ``` @@ -51,14 +83,14 @@ BitFun-Installer/ │ ├── App.tsx │ └── main.tsx ├── scripts/ -│ └── build-installer.cjs # End-to-end build script +│ └── build-installer.cjs # End-to-end build script ├── index.html ├── package.json ├── vite.config.ts └── tsconfig.json ``` -## Installation Flow +## Installation flow ``` Language Select → Options → Progress → Model Setup → Theme Setup @@ -77,19 +109,10 @@ Language Select → Options → Progress → Model Setup → Theme Setup ### Setup -```bash -cd .. -pnpm install -``` - -Or from repository root: - ```bash pnpm install ``` -Production installer builds call workspace desktop build scripts, so root dependencies are required. - ### Repository Hygiene Keep generated artifacts out of commits. This project ignores: @@ -112,8 +135,7 @@ pnpm run tauri:dev Key behavior: - Install phase creates `uninstall.exe` in the install directory. -- Windows uninstall registry entry points to: - `"\\uninstall.exe" --uninstall ""`. +- Windows uninstall registry entry points to `"\\uninstall.exe" --uninstall ""`. - Launching with `--uninstall` opens the dedicated uninstall UI flow. - Launching `uninstall.exe` directly also enters uninstall mode automatically. @@ -125,37 +147,36 @@ npx tauri dev -- -- --uninstall "D:\\tmp\\bitfun-uninstall-test" Core implementation: -- Launch arg parsing + uninstall execution: `src-tauri/src/installer/commands.rs` -- Uninstall registry command: `src-tauri/src/installer/registry.rs` -- Uninstall UI page: `src/pages/Uninstall.tsx` -- Frontend mode switching/state: `src/hooks/useInstaller.ts` +- Launch arg parsing + uninstall execution: [commands.rs](src-tauri/src/installer/commands.rs) +- Uninstall registry command: [registry.rs](src-tauri/src/installer/registry.rs) +- Uninstall UI page: [Uninstall.tsx](src/pages/Uninstall.tsx) +- Frontend mode switching and state: [useInstaller.ts](src/hooks/useInstaller.ts) -### Build +## Build -Build the complete installer in release mode (default, optimized): +### Full release build ```bash pnpm run installer:build ``` -Use this as the release entrypoint. `pnpm run tauri:build` does not prepare validated payload assets for production. Release artifacts embed payload files into the installer binary, so runtime installation does not depend on an external `payload` folder. -Build the complete installer in fast mode (faster compile, less optimization): +### Full fast build ```bash pnpm run installer:build:fast ``` -Build installer only (skip main app build): +### Installer-only build ```bash pnpm run installer:build:only ``` -`installer:build:only` now requires an existing valid desktop executable in target output paths. If payload validation fails, build exits with an error. +If payload validation fails, the build exits with an error. -Build installer only with fast mode: +### Installer-only fast build ```bash pnpm run installer:build:only:fast @@ -163,37 +184,37 @@ pnpm run installer:build:only:fast ### Output -The built executable will be at: +Default release output: -``` +```text src-tauri/target/release/bitfun-installer.exe ``` -Fast mode output path: +Fast build output: -``` +```text src-tauri/target/release-fast/bitfun-installer.exe ``` -## Customization Guide +## Customization guide ### Changing the UI Theme -Edit `src/styles/variables.css` — all colors, spacing, and animations are controlled by CSS custom properties. +Edit [variables.css](src/styles/variables.css). Colors, spacing, and animations are controlled by CSS custom properties. ### Adding Install Steps -1. Add a new step key to `InstallStep` type in `src/types/installer.ts` -2. Create a new page component in `src/pages/` -3. Add the step to the `STEPS` array in `src/hooks/useInstaller.ts` -4. Add the page render case in `src/App.tsx` +1. Add a new step key to `InstallStep` in [installer.ts](src/types/installer.ts) +2. Create a new page component in [src/pages](src/pages) +3. Add the step to the `STEPS` array in [useInstaller.ts](src/hooks/useInstaller.ts) +4. Add the page render case in [App.tsx](src/App.tsx) ### Modifying Install Logic -- **File extraction** → `src-tauri/src/installer/extract.rs` -- **Registry operations** → `src-tauri/src/installer/registry.rs` -- **Shortcuts** → `src-tauri/src/installer/shortcut.rs` -- **Tauri commands** → `src-tauri/src/installer/commands.rs` +- **File extraction** → [extract.rs](src-tauri/src/installer/extract.rs) +- **Registry operations** → [registry.rs](src-tauri/src/installer/registry.rs) +- **Shortcuts** → [shortcut.rs](src-tauri/src/installer/shortcut.rs) +- **Tauri commands** → [commands.rs](src-tauri/src/installer/commands.rs) ### Adding Installer Payload diff --git a/README.md b/README.md index 48bdeb944..b26ea1b7e 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ It will interact through phones, watches, desktop robots, and more. It is part o Pair by scanning a QR code, and your phone instantly becomes a remote command center for the desktop Agent. Send one message, and the AI on the desktop starts working right away. -Besides the mobile browser scan, BitFun also supports Telegram / Feishu bots / WeChat bots for remote commands, with real-time visibility into Agent progress. +Besides mobile browser pairing, BitFun also supports Telegram / Feishu bots / WeChat bots for remote commands, with real-time visibility into Agent progress. --- @@ -39,7 +39,7 @@ Besides the mobile browser scan, BitFun also supports Telegram / Feishu bots / W BitFun offers two modes for different scenarios: - **Assistant Mode**: warm, remembers your preferences, with long-term memory. Best for ongoing collaboration—maintaining a project, continuing your aesthetic and working habits. -- **Professional Mode**: saves tokens, execution-first, clean context. Best for immediate tasks—fixing a bug, tweaking a style. +- **Expert Mode**: saves tokens, execution-first, clean context. Best for immediate tasks—fixing a bug, tweaking a style. --- @@ -98,7 +98,7 @@ pnpm run desktop:dev pnpm run desktop:build ``` -For more details, see the [Contributing guide](./CONTRIBUTING_CN.md). +For more details, see the [Contributing guide](./CONTRIBUTING.md). --- diff --git a/README.zh-CN.md b/README.zh-CN.md index b634a15db..536444437 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -30,7 +30,7 @@ BitFun 是一个Agentic OS，更是你亲密无间的伙伴。 扫码配对，手机即刻变成桌面 Agent 的远程指挥中心。一条消息，桌面上的 AI 立刻开始工作。 -除手机浏览器扫码外，也支持接入 Telegram / 飞书 Bot/ 微信 Bot 远程下达指令，并实时查看 Agent 的执行进度。 +除手机浏览器扫码外，也支持接入 Telegram / 飞书 Bot / 微信 Bot 远程下达指令，并实时查看 Agent 的执行进度。 ## 双模式协同 @@ -56,13 +56,13 @@ BitFun 提供两种模式，适配不同场景需求： > 它会自己成长。 -支持 Skill、MCP（包含MCP App）、自定义Agent，此外还支持即用即生的Mini App（从一句需求生成可运行界面，并可一键打包成桌面应用） +支持 Skill、MCP（包含 MCP App）、自定义 Agent，此外还支持即用即生的 Mini App（从一句需求生成可运行界面，并可一键打包成桌面应用）。 --- ## 平台支持 -项目采用tauri，支持Windows、macOS、Linux，同时支持移动控制手机浏览器、Telegram、飞书、微信等。 +项目采用 Tauri，支持 Windows、macOS、Linux，同时支持通过手机浏览器、Telegram、飞书、微信等方式进行移动控制。 --- diff --git a/src/apps/desktop/AGENTS-CN.md b/src/apps/desktop/AGENTS-CN.md index 443df0040..41b450122 100644 --- a/src/apps/desktop/AGENTS-CN.md +++ b/src/apps/desktop/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 适用范围 diff --git a/src/apps/desktop/AGENTS.md b/src/apps/desktop/AGENTS.md index 97c6ffced..59d14526f 100644 --- a/src/apps/desktop/AGENTS.md +++ b/src/apps/desktop/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Scope diff --git a/src/apps/relay-server/README.md b/src/apps/relay-server/README.md index 2e4080804..8080bcb2f 100644 --- a/src/apps/relay-server/README.md +++ b/src/apps/relay-server/README.md @@ -1,48 +1,59 @@ # BitFun Relay Server -WebSocket relay server for BitFun Remote Connect. Bridges desktop (WebSocket) and mobile (HTTP) clients with E2E encryption support. +WebSocket relay server for BitFun Remote Connect. It bridges desktop (WebSocket) and mobile (HTTP) clients while forwarding end-to-end encrypted payloads. ## Features -- Desktop connects via WebSocket, mobile via HTTP — relay bridges between them -- End-to-end encrypted message passthrough (server cannot decrypt) +- Desktop connects via WebSocket, mobile via HTTP +- End-to-end encrypted passthrough (the server does not decrypt payloads) - Correlation-based HTTP-to-WebSocket request-response matching -- Per-room mobile-web static file upload & serving (content-addressable, incremental) +- Per-room mobile-web static file upload and serving - Heartbeat-based connection management with configurable room TTL -- Docker deployment ready with Caddy reverse proxy +- Docker deployment support with optional Caddy reverse proxy ## Quick Start -### Docker (Recommended) +### Recommended: Run on the target server ```bash -# SSH into your target server first, then clone the repo: +# Clone on the target server git clone https://github.com/GCWing/BitFun cd BitFun/src/apps/relay-server -# SSH into your target server first, then run: +# Deploy to the current machine bash deploy.sh ``` -`deploy.sh` must be run on the target server itself. It only deploys to the current machine and does not SSH to a remote host. +`deploy.sh` must run on the target server itself. It deploys to the current machine only and does not SSH to another host. -After deployment, you can manage the service with: +### Service Operations + +Run these commands on the target server inside this directory: ```bash bash start.sh bash stop.sh bash restart.sh +docker compose ps +docker compose logs -f relay-server ``` +Notes: + +- `start.sh` is idempotent and exits if the service is already running. +- `stop.sh` exits cleanly when the service is already stopped. +- `restart.sh` restarts the service when running, or starts it when stopped. +- The container uses `restart: unless-stopped`. + ### What URL should I fill in BitFun Desktop? In **Remote Connect → Self-Hosted → Server URL**, use one of: -- Direct relay port: `http://:9700` +- `http://:9700` -`/relay` is **not mandatory**. It is only needed when your reverse proxy is configured with that path prefix. +`/relay` is only needed when your reverse proxy is configured with that path prefix. -### Manual +### Manual Run ```bash # From project root @@ -52,6 +63,17 @@ cargo build --release -p bitfun-relay-server RELAY_PORT=9700 ./target/release/bitfun-relay-server ``` +## Deployment Checklist + +1. Open required ports: + - `9700` for direct relay access + - `80/443` when using Caddy or another reverse proxy +2. Verify the health endpoint: + - `http://:9700/health` +3. Decide the final URL strategy: + - direct port or reverse proxy domain +4. Fill the same URL into BitFun Desktop custom server settings + ## Environment Variables | Variable | Default | Description | @@ -67,23 +89,23 @@ RELAY_PORT=9700 ./target/release/bitfun-relay-server | Endpoint | Method | Description | |----------|--------|-------------| -| `/health` | GET | Health check (returns status, version, uptime, room/connection counts) | -| `/api/info` | GET | Server info (name, version, protocol_version) | +| `/health` | GET | Health check (returns status, version, uptime, room and connection counts) | +| `/api/info` | GET | Server info (name, version, protocol version) | ### Room Operations (Mobile HTTP → Desktop WS bridge) | Endpoint | Method | Description | |----------|--------|-------------| -| `/api/rooms/:room_id/pair` | POST | Mobile initiates pairing — relay forwards to desktop via WS, waits for response | -| `/api/rooms/:room_id/command` | POST | Mobile sends encrypted command — relay forwards to desktop, returns response | +| `/api/rooms/:room_id/pair` | POST | Mobile initiates pairing; relay forwards to desktop via WebSocket and waits for a response | +| `/api/rooms/:room_id/command` | POST | Mobile sends an encrypted command; relay forwards it to desktop and returns the response | ### Per-Room Mobile-Web File Management | Endpoint | Method | Description | |----------|--------|-------------| -| `/api/rooms/:room_id/upload-web` | POST | Full upload: base64-encoded files keyed by path (10MB body limit) | -| `/api/rooms/:room_id/check-web-files` | POST | Incremental: check which files the server already has by hash | -| `/api/rooms/:room_id/upload-web-files` | POST | Incremental: upload only the missing files (10MB body limit) | +| `/api/rooms/:room_id/upload-web` | POST | Full upload of base64-encoded files keyed by path (10 MB body limit) | +| `/api/rooms/:room_id/check-web-files` | POST | Incremental check for already uploaded files by hash | +| `/api/rooms/:room_id/upload-web-files` | POST | Incremental upload of only missing files (10 MB body limit) | | `/r/:room_id/*path` | GET | Serve uploaded mobile-web static files for a room | ### WebSocket @@ -128,131 +150,42 @@ Only desktop clients connect via WebSocket. Mobile clients use the HTTP endpoint { "type": "error", "message": "..." } ``` -## Self-Hosted Deployment - -### Option A: Deploy on the Server Itself - -If you have the repo cloned **on the server**: - -```bash -git clone https://github.com/GCWing/BitFun -cd BitFun/src/apps/relay-server/ -bash deploy.sh -``` - -Or, if the repo is already present on the server: +## Architecture -```bash -cd src/apps/relay-server/ -bash deploy.sh ``` - -This script must be executed in an SSH session on the target server. It builds the Docker image on that server and starts the container there. It will **automatically stop any previously running relay container** before restarting. - -### Service Operations - -Run these commands on the target server inside `src/apps/relay-server/`: - -```bash -# Start the service only when it is not already running -bash start.sh - -# Stop the running service -bash stop.sh - -# Restart the service, or start it if it is currently stopped -bash restart.sh - -# View current status -docker compose ps - -# View logs -docker compose logs -f relay-server -``` - -Behavior notes: - -- `start.sh` is idempotent. If the relay service is already running, it exits without starting it again. -- `stop.sh` exits cleanly when the service is already stopped. -- `restart.sh` restarts the service when it is running, and starts it when it is stopped. -- The container uses `restart: unless-stopped`, so it will automatically come back after a server reboot as long as the Docker service itself is enabled and running. - -### Option B: Remote Deploy (from your dev machine) - -Push code changes from your local dev machine to a remote server via SSH: - -```bash -cd src/apps/relay-server/ - -# First-time setup (creates /opt/bitfun-relay, copies static/) -bash remote-deploy.sh 116.204.120.240 --first - -# Subsequent updates (syncs src + rebuilds) -bash remote-deploy.sh 116.204.120.240 +Mobile Phone ──HTTP POST──► Relay Server ◄──WebSocket── Desktop Client + │ + E2E Encrypted + (server cannot + read messages) ``` -The script will: -1. Test SSH connectivity -2. **Stop the old container** if running -3. Sync source code (`src/`), `Cargo.toml`, `Dockerfile`, `docker-compose.yml` -4. Rebuild the Docker image on the server -5. Start the new container -6. Run a health check - -**Prerequisites:** -- SSH key-based auth to the server (configured in `~/.ssh/config`) -- Docker + Docker Compose installed on the server - -### Deployment Checklist +The relay server bridges HTTP and WebSocket: -1. Open required ports: - - `9700` (relay direct access, optional if only via reverse proxy) - - `80/443` (for Caddy reverse proxy) -2. Verify health endpoint: - - `http://:9700/health` -3. Configure your final URL strategy: - - root domain (`https://relay.example.com`) -4. Fill the same URL into BitFun Desktop "Custom Server" +- **Desktop** connects via WebSocket, creates a room, and stays connected. +- **Mobile** sends HTTP POST requests such as `/pair` and `/command`. +- The relay forwards requests to the desktop over WebSocket with correlation IDs, waits for the response, and returns it over HTTP. +- The relay only manages rooms and forwards opaque encrypted payloads. +- Per-room mobile-web static files can be uploaded and served at `/r/:room_id/`. -### Directory Structure +## Directory structure ``` relay-server/ ├── src/ # Rust source code ├── static/ # Mobile-web static files -├── Cargo.toml # Crate manifest (standalone, no workspace deps) -├── Dockerfile # Docker build (standalone single-crate build) +├── Cargo.toml # Crate manifest +├── Dockerfile # Docker build ├── docker-compose.yml # Docker Compose config -├── Caddyfile # Caddy reverse proxy config (optional) -├── deploy.sh # Deploy current machine (run on the target server itself) +├── Caddyfile # Optional reverse proxy config +├── deploy.sh # Deploy on the target server itself ├── start.sh # Start service if not already running ├── stop.sh # Stop running service ├── restart.sh # Restart service, or start if stopped -├── remote-deploy.sh # Remote deploy (run from dev machine via SSH) └── README.md ``` -Relay server is a **standalone crate** — one set of code, one Dockerfile, one docker-compose.yml. -Whether deployed as a public relay, LAN relay, or NAT traversal relay, the build and runtime are identical. - -### About `src/apps/server` vs `src/apps/relay-server` - -- Remote Connect self-hosted deployment uses **`src/apps/relay-server`**. -- `src/apps/server` is a different application and not the relay service used by mobile/desktop Remote Connect. - -## Architecture - -``` -Mobile Phone ──HTTP POST──► Relay Server ◄──WebSocket── Desktop Client - │ - E2E Encrypted - (server cannot - read messages) -``` - -The relay server bridges HTTP and WebSocket: +## About `src/apps/server` vs `src/apps/relay-server` -- **Desktop** connects via WebSocket, creates a room, and stays connected. -- **Mobile** sends HTTP POST requests (`/pair`, `/command`). The relay forwards them to the desktop over WS using correlation IDs, waits for the WS response, and returns it to mobile via HTTP. -- The relay only manages rooms and forwards opaque encrypted payloads. All encryption/decryption happens on the client side. -- Per-room mobile-web static files can be uploaded via the incremental upload API and served at `/r/:room_id/`. +- Remote Connect self-hosted deployment uses the relay server in this directory. +- `src/apps/server` is a different application and is not the relay service used by mobile and desktop Remote Connect. diff --git a/src/apps/server/README.md b/src/apps/server/README.md index 687ab94bb..332c5cbcc 100644 --- a/src/apps/server/README.md +++ b/src/apps/server/README.md @@ -1,10 +1,10 @@ # BitFun Server (Web App Backend) -This directory contains the `bitfun-server` application. +This directory contains the `bitfun-server` application, which serves the web backend runtime for BitFun. If you are looking for **Remote Connect self-hosted relay deployment**, use: -- `src/apps/relay-server/README.md` -- `src/apps/relay-server/deploy.sh` +- [Relay Server README](../relay-server/README.md) +- [deploy.sh](../relay-server/deploy.sh) -`src/apps/server` and `src/apps/relay-server` are different components. +`src/apps/server` and `src/apps/relay-server` are different components. `src/apps/server` is the main web app backend, while `src/apps/relay-server` is the relay service used by Remote Connect. diff --git a/src/crates/core/AGENTS-CN.md b/src/crates/core/AGENTS-CN.md index 552006547..c4d95190b 100644 --- a/src/crates/core/AGENTS-CN.md +++ b/src/crates/core/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 适用范围 diff --git a/src/crates/core/AGENTS.md b/src/crates/core/AGENTS.md index 118391578..685d0d504 100644 --- a/src/crates/core/AGENTS.md +++ b/src/crates/core/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Scope diff --git a/src/web-ui/AGENTS-CN.md b/src/web-ui/AGENTS-CN.md index a6f7e40cd..dac9ff60d 100644 --- a/src/web-ui/AGENTS-CN.md +++ b/src/web-ui/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 适用范围 diff --git a/src/web-ui/AGENTS.md b/src/web-ui/AGENTS.md index 3f81ddee3..189f74836 100644 --- a/src/web-ui/AGENTS.md +++ b/src/web-ui/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Scope diff --git a/src/web-ui/README.md b/src/web-ui/README.md index d951aa333..d34663fd2 100644 --- a/src/web-ui/README.md +++ b/src/web-ui/README.md @@ -11,7 +11,7 @@ This directory contains BitFun’s **Web UI** (React + TypeScript). The same fro ## Tech stack -- React 19 +- React 18.3 - TypeScript 5.8 - Vite 7 - SCSS @@ -59,7 +59,7 @@ One UI, two runtimes: - **Desktop**: Tauri API (`invoke`, `listen`) - **Server/Web**: WebSocket / Fetch API -### Adapter pattern (simplified) +### Adapter pattern (conceptual example) ```ts const adapter = IS_TAURI ? TauriAdapter : WebSocketAdapter; @@ -73,31 +73,29 @@ adapter.listen("agentic://text-chunk", callback); ### Start the dev server ```bash -cd src/web-ui - # Desktop -pnpm run dev +pnpm --dir src/web-ui run dev # Server/Web -VITE_BUILD_TARGET=web pnpm run dev +VITE_BUILD_TARGET=web pnpm --dir src/web-ui run dev ``` ### Build ```bash # Desktop -pnpm run build +pnpm --dir src/web-ui run build # Server/Web -VITE_BUILD_TARGET=web pnpm run build +VITE_BUILD_TARGET=web pnpm --dir src/web-ui run build # output: dist/ ``` ## Related docs (within this package) -- `LOGGING.md` -- `src/component-library/README.md` -- `src/infrastructure/i18n/README.md` +- [Logging guide](LOGGING.md) +- [Component library README](src/component-library/README.md) +- [i18n README](src/infrastructure/i18n/README.md) ## Notes diff --git a/src/web-ui/README.zh-CN.md b/src/web-ui/README.zh-CN.md index 3a55d1377..d2a3f36de 100644 --- a/src/web-ui/README.zh-CN.md +++ b/src/web-ui/README.zh-CN.md @@ -11,7 +11,7 @@ ## 技术栈 -- React 19 +- React 18.3 - TypeScript 5.8 - Vite 7 - SCSS @@ -59,7 +59,7 @@ src/web-ui/ - **Desktop**：Tauri API（`invoke`, `listen`） - **Server/Web**：WebSocket / Fetch API -### 适配器模式（简化示例） +### 适配器模式（概念示例） ```ts const adapter = IS_TAURI ? TauriAdapter : WebSocketAdapter; @@ -73,31 +73,29 @@ adapter.listen("agentic://text-chunk", callback); ### 启动开发服务器 ```bash -cd src/web-ui - # Desktop -pnpm run dev +pnpm --dir src/web-ui run dev # Server/Web -VITE_BUILD_TARGET=web pnpm run dev +VITE_BUILD_TARGET=web pnpm --dir src/web-ui run dev ``` ### 构建 ```bash # Desktop -pnpm run build +pnpm --dir src/web-ui run build # Server/Web -VITE_BUILD_TARGET=web pnpm run build +VITE_BUILD_TARGET=web pnpm --dir src/web-ui run build # 产物：dist/ ``` ## 相关文档（本包内） -- `LOGGING.md` -- `src/component-library/README.md` -- `src/infrastructure/i18n/README.md` +- [日志说明](LOGGING.md) +- [组件库 README](src/component-library/README.md) +- [i18n README](src/infrastructure/i18n/README.md) ## 注意事项 diff --git a/src/web-ui/public/fonts/README.md b/src/web-ui/public/fonts/README.md index c35ba934c..a20d1b7e5 100644 --- a/src/web-ui/public/fonts/README.md +++ b/src/web-ui/public/fonts/README.md @@ -1,3 +1,5 @@ +[中文](README.zh-CN.md) | **English** + # Fonts This directory contains font assets and configuration for the web UI. diff --git a/src/web-ui/public/fonts/README.zh-CN.md b/src/web-ui/public/fonts/README.zh-CN.md index 96f2b3127..b54252e4f 100644 --- a/src/web-ui/public/fonts/README.zh-CN.md +++ b/src/web-ui/public/fonts/README.zh-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](README.md) + # 字体说明 本目录提供 Web UI 的字体资源与配置说明。 diff --git a/src/web-ui/src/component-library/README.md b/src/web-ui/src/component-library/README.md index 14b693b84..8178b363f 100644 --- a/src/web-ui/src/component-library/README.md +++ b/src/web-ui/src/component-library/README.md @@ -1,3 +1,5 @@ +[中文](README.zh-CN.md) | **English** + # BitFun Component Library ## Overview diff --git a/src/web-ui/src/component-library/README.zh-CN.md b/src/web-ui/src/component-library/README.zh-CN.md index 14b4fa20f..0f41d5ba8 100644 --- a/src/web-ui/src/component-library/README.zh-CN.md +++ b/src/web-ui/src/component-library/README.zh-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](README.md) + # BitFun 组件库 ## 简介 diff --git a/src/web-ui/src/component-library/components/FlowChatCards/README.md b/src/web-ui/src/component-library/components/FlowChatCards/README.md index 577ff8958..15e52c6fc 100644 --- a/src/web-ui/src/component-library/components/FlowChatCards/README.md +++ b/src/web-ui/src/component-library/components/FlowChatCards/README.md @@ -1,26 +1,50 @@ +[中文](README.zh-CN.md) | **English** + # FlowChat Cards -A set of card components that render tool execution progress and results in FlowChat. All cards follow a unified dark theme and support multiple display modes. +FlowChat card components for rendering tool execution progress, summaries, and structured results in the chat stream. + +## Scope + +This directory contains: + +- shared card layout in `BaseToolCard` +- tool-specific cards such as `ReadFileCard`, `SearchCard`, and `TaskCard` +- shared registration and configuration in [index.ts](index.ts) +- shared styles in `_shared-styles.scss` + +## Current cards + +Current component folders in this directory: + +- `BaseToolCard`: shared layout, header, status, and result sections +- `ContextCompressionCard`: context compression summary and result display +- `ReadFileCard`: file read output and content preview +- `SearchCard`: grep/glob-style search results +- `SnapshotCard`: snapshot-style structured output +- `TaskCard`: delegated task execution and result summaries +- `TodoCard`: todo list progress and status display +- `WebSearchCard`: web search results and source summaries -## Components +## Tool Config -- BaseToolCard: base layout and status handling -- ReadFileCard: file read output -- FileOperationCard: write/edit/delete operations -- SearchCard: text and file search results -- TerminalCard: terminal command execution -- TaskCard: AI task execution -- TodoCard: task list and status -- WebSearchCard: web search and fetch results +[index.ts](index.ts) also maintains tool-level display configuration such as: + +- display name and icon +- default display mode +- result display type +- primary color + +The config currently covers cards and tool outputs for `Read`, `Write`, `Edit`, `Delete`, `Grep`, `Glob`, `WebSearch`, `WebFetch`, `Task`, `TodoWrite`, and `ContextCompression`. ## Usage ```tsx import { ReadFileCard, - FileOperationCard, - TerminalCard, - getFlowChatCardConfig + SearchCard, + TaskCard, + getFlowChatCardConfig, } from '@component-library/components/FlowChatCards'; const config = getFlowChatCardConfig('Read'); @@ -28,34 +52,29 @@ const config = getFlowChatCardConfig('Read'); ; ``` -## Display Modes - -- `compact`: quick view in chat stream -- `standard`: regular card layout -- `detailed`: full input and result view - -```tsx - -``` - -## Status +## Display modes -- `pending` | `running` | `streaming` | `completed` | `error` +- `compact`: quick view in the chat stream +- `standard`: default card layout +- `detailed`: expanded input and result view +- `terminal`: terminal-oriented display for tool configs that need it -## Design +## Status Values -- unified dark theme -- BEM naming -- tool-specific primary color from config +- `pending` +- `running` +- `streaming` +- `completed` +- `error` ## Extending -1. Add component folder and styles under `FlowChatCards/` -2. Export in `FlowChatCards/index.ts` -3. Register tool config +1. Add a component folder under `FlowChatCards/` +2. Export it in [index.ts](index.ts) +3. Register or update tool config in `FLOWCHAT_CARD_CONFIGS` +4. Keep README examples aligned with the exported cards and supported tool names ## Related - [Component library](../README.md) -- [Design tokens](../../DESIGN_TOKENS.md) - [Styles](../../styles/README.md) diff --git a/src/web-ui/src/component-library/components/FlowChatCards/README.zh-CN.md b/src/web-ui/src/component-library/components/FlowChatCards/README.zh-CN.md index 5c29f6b6d..490aae464 100644 --- a/src/web-ui/src/component-library/components/FlowChatCards/README.zh-CN.md +++ b/src/web-ui/src/component-library/components/FlowChatCards/README.zh-CN.md @@ -1,26 +1,50 @@ +**中文** | [English](README.md) + # FlowChat Cards -用于展示 FlowChat 中工具执行过程与结果的卡片组件集合，统一暗色风格并支持多种显示模式。 +用于在 FlowChat 聊天流中展示工具执行过程、摘要结果与结构化输出的卡片组件。 + +## 范围 + +本目录主要包含： + +- `BaseToolCard` 中的通用卡片骨架 +- `ReadFileCard`、`SearchCard`、`TaskCard` 等工具专用卡片 +- [index.ts](index.ts) 中的统一导出与配置注册 +- `_shared-styles.scss` 中的共享样式 + +## 当前卡片 + +本目录当前包含的组件有： + +- `BaseToolCard`：通用布局、头部、状态与结果区 +- `ContextCompressionCard`：上下文压缩结果展示 +- `ReadFileCard`：文件读取结果与内容预览 +- `SearchCard`：搜索类结果展示，适用于 grep/glob 风格输出 +- `SnapshotCard`：快照类结构化输出展示 +- `TaskCard`：任务委托执行与结果摘要展示 +- `TodoCard`：Todo 列表进度与状态展示 +- `WebSearchCard`：网页搜索结果与来源摘要展示 -## 组件 +## 工具配置 -- BaseToolCard: 通用布局与状态管理基础 -- ReadFileCard: 文件读取展示 -- FileOperationCard: 写入、编辑、删除等文件操作展示 -- SearchCard: 文本与文件搜索展示 -- TerminalCard: 终端命令执行展示 -- TaskCard: AI 任务执行展示 -- TodoCard: 任务列表与状态展示 -- WebSearchCard: 网页搜索与抓取展示 +[index.ts](index.ts) 同时维护工具级展示配置，包括： + +- 展示名称与图标 +- 默认显示模式 +- 结果展示类型 +- 主色 + +当前配置覆盖的工具输出包括 `Read`、`Write`、`Edit`、`Delete`、`Grep`、`Glob`、`WebSearch`、`WebFetch`、`Task`、`TodoWrite` 和 `ContextCompression`。 ## 使用方式 ```tsx import { ReadFileCard, - FileOperationCard, - TerminalCard, - getFlowChatCardConfig + SearchCard, + TaskCard, + getFlowChatCardConfig, } from '@component-library/components/FlowChatCards'; const config = getFlowChatCardConfig('Read'); @@ -30,32 +54,27 @@ const config = getFlowChatCardConfig('Read'); ## 显示模式 -- `compact`: 聊天流快速展示 -- `standard`: 常规卡片布局 -- `detailed`: 展示完整输入与结果 - -```tsx - -``` - -## 状态 - -- `pending` | `running` | `streaming` | `completed` | `error` +- `compact`：聊天流中的快速展示 +- `standard`：默认卡片布局 +- `detailed`：展开显示输入与结果 +- `terminal`：适用于终端类工具配置的展示模式 -## 设计约定 +## 状态值 -- 统一暗色主题 -- BEM 命名规范 -- 工具按配置提供主题色 +- `pending` +- `running` +- `streaming` +- `completed` +- `error` ## 扩展开发 -1. 在 `FlowChatCards/` 下新增组件目录与样式 -2. 导出到 `FlowChatCards/index.ts` -3. 在配置中注册工具信息 +1. 在 `FlowChatCards/` 下新增组件目录 +2. 在 [index.ts](index.ts) 中导出 +3. 在 `FLOWCHAT_CARD_CONFIGS` 中注册或更新工具配置 +4. 保持 README 示例与实际导出的卡片、支持的工具名称一致 ## 相关文档 - [组件库总览](../README.md) -- [设计系统](../../DESIGN_TOKENS.md) - [样式指南](../../styles/README.md) diff --git a/src/web-ui/src/component-library/components/README.md b/src/web-ui/src/component-library/components/README.md index 27f4ee8ca..347e302fb 100644 --- a/src/web-ui/src/component-library/components/README.md +++ b/src/web-ui/src/component-library/components/README.md @@ -1,60 +1,61 @@ +[中文](README.zh-CN.md) | **English** + # Component Library -BitFun component library built with SCSS and BEM naming, unified dark theme. +BitFun component library for reusable UI building blocks and previewable demos. + +## Scope + +This directory contains: + +- reusable components exported through [index.ts](index.ts) +- preview registrations in [registry.tsx](registry.tsx) +- component-specific docs such as [FlowChatCards README](FlowChatCards/README.md) + +## Component areas + +Current component folders include: + +- **Actions & window controls**: `Button`, `IconButton`, `WindowControls` +- **Dialogs & overlays**: `Modal`, `InputDialog`, `ConfirmDialog`, `Tooltip` +- **Form inputs**: `Input`, `NumberInput`, `Search`, `Select`, `Checkbox`, `Switch`, `Textarea` +- **Display & content**: `Alert`, `Badge`, `Tag`, `Avatar`, `Card`, `Empty`, `Markdown`, `Tabs` +- **Editors & text**: `CodeEditor`, `StreamText` +- **Visual utilities**: `CubeLoading`, `CubeLogo`, `DotMatrixLoader`, `TextStrokeEffect` +- **Feature-specific UI**: `ConfigPage`, `FilterPill`, `FlowChatCards` -## Components +## Exports and Previews -- Markdown: rendering with GFM and syntax highlighting; preview at `/markdown-preview.html` -- Button: variants, sizes, and loading state -- Card: container with variant/hoverable -- Loading: indicator with size/variant -- Modal: ESC/backdrop close and locks background scroll +- Add reusable exports in [index.ts](index.ts) +- Register preview entries in [registry.tsx](registry.tsx) +- Keep README examples aligned with actual exported components ## Usage ```tsx -import { Button, Card, Loading } from '@components'; +import { Button, Card, Input, Markdown } from '@components'; -function App() { +function Example() { return ( - - + + + # Preview ); } ``` -## Styling - -- BEM naming -- SCSS variables and mixins for theming -- Transition: `transition: all 0.2s ease;` - -## Structure - -``` -src/component-library/components/ -├── Button/ -│ ├── Button.tsx -│ ├── Button.scss -│ └── index.ts -├── Card/ -├── Loading/ -├── Modal/ -├── index.ts -└── registry.tsx -``` - ## Development -1. Create a folder under `components/` -2. Implement `.tsx` and `.scss` -3. Export via the component `index.ts` and `components/index.ts` -4. Register preview in `registry.tsx` +1. Create a component folder under `components/` +2. Implement the component and related styles +3. Export it through the component `index.ts` and `components/index.ts` +4. Add or update preview demos in `registry.tsx` +5. Update the nearest README when the public surface changes ## Notes -- Dark theme only -- Import via `@components` alias -- Components support standard HTML attributes +- Use existing SCSS patterns and naming conventions from nearby components +- Treat [registry.tsx](registry.tsx) as the source of truth for preview coverage +- If a component group grows large, add a local README in that subdirectory diff --git a/src/web-ui/src/component-library/components/README.zh-CN.md b/src/web-ui/src/component-library/components/README.zh-CN.md index 815abf9ac..e13c2272d 100644 --- a/src/web-ui/src/component-library/components/README.zh-CN.md +++ b/src/web-ui/src/component-library/components/README.zh-CN.md @@ -1,60 +1,61 @@ +**中文** | [English](README.md) + # 组件库 -BitFun 组件库，使用 SCSS 与 BEM 命名规范，统一暗色主题。 +BitFun 组件库目录，承载可复用 UI 组件与可预览的演示注册。 + +## 范围 + +本目录主要包含： + +- 通过 [index.ts](index.ts) 对外导出的可复用组件 +- 在 [registry.tsx](registry.tsx) 中注册的组件预览 +- 组件分组自己的说明文档，例如 [FlowChatCards README](FlowChatCards/README.md) + +## 组件分区 + +当前组件目录主要包括： + +- **操作与窗口控件**：`Button`、`IconButton`、`WindowControls` +- **弹窗与浮层**：`Modal`、`InputDialog`、`ConfirmDialog`、`Tooltip` +- **表单输入**：`Input`、`NumberInput`、`Search`、`Select`、`Checkbox`、`Switch`、`Textarea` +- **展示与内容**：`Alert`、`Badge`、`Tag`、`Avatar`、`Card`、`Empty`、`Markdown`、`Tabs` +- **编辑与文本**：`CodeEditor`、`StreamText` +- **视觉辅助**：`CubeLoading`、`CubeLogo`、`DotMatrixLoader`、`TextStrokeEffect` +- **业务型 UI**：`ConfigPage`、`FilterPill`、`FlowChatCards` -## 组件 +## 导出与预览 -- Markdown: Markdown 渲染与高亮，支持 GFM；预览页面 `/markdown-preview.html` -- Button: 按钮，支持多种 variant/size 与 loading -- Card: 卡片容器，支持 variant/hoverable -- Loading: 加载指示器，支持 size/variant -- Modal: 模态框，支持 ESC/遮罩关闭并禁止背景滚动 +- 在 [index.ts](index.ts) 中维护对外导出 +- 在 [registry.tsx](registry.tsx) 中注册预览入口 +- README 中的示例应与实际导出的组件保持一致 ## 使用方式 ```tsx -import { Button, Card, Loading } from '@components'; +import { Button, Card, Input, Markdown } from '@components'; -function App() { +function Example() { return ( - - + + + # 预览 ); } ``` -## 样式规范 - -- 使用 BEM 命名 -- 通过 SCSS 变量与混合控制主题 -- 交互过渡：`transition: all 0.2s ease;` - -## 目录结构 - -``` -src/component-library/components/ -├── Button/ -│ ├── Button.tsx -│ ├── Button.scss -│ └── index.ts -├── Card/ -├── Loading/ -├── Modal/ -├── index.ts -└── registry.tsx -``` - ## 开发指南 1. 在 `components/` 下创建组件目录 -2. 实现 `.tsx` 与 `.scss` -3. 在组件 `index.ts` 与 `components/index.ts` 导出 -4. 在 `registry.tsx` 注册预览 +2. 实现组件及相关样式 +3. 在组件 `index.ts` 与 `components/index.ts` 中导出 +4. 在 `registry.tsx` 中补充或更新预览演示 +5. 若公共接口发生变化，同步更新就近 README ## 注意事项 -- 仅提供暗色主题 -- 使用 `@components` 路径别名导入 -- 组件支持标准 HTML 属性 \ No newline at end of file +- 优先沿用相邻组件已有的 SCSS 组织方式与命名习惯 +- 组件预览覆盖情况以 [registry.tsx](registry.tsx) 为准 +- 当某个组件分组变复杂时，在该子目录补充本地 README diff --git a/src/web-ui/src/component-library/styles/README.md b/src/web-ui/src/component-library/styles/README.md index 8813e5f0a..43a945fc4 100644 --- a/src/web-ui/src/component-library/styles/README.md +++ b/src/web-ui/src/component-library/styles/README.md @@ -1,3 +1,5 @@ +[中文](README.zh-CN.md) | **English** + # Design Tokens This directory defines BitFun component design tokens to unify colors, typography, spacing, shadows, motion, and layering. diff --git a/src/web-ui/src/component-library/styles/README.zh-CN.md b/src/web-ui/src/component-library/styles/README.zh-CN.md index 22962dc0f..af2102a18 100644 --- a/src/web-ui/src/component-library/styles/README.zh-CN.md +++ b/src/web-ui/src/component-library/styles/README.zh-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](README.md) + # 设计令牌 该目录包含 BitFun 组件库的设计令牌，统一管理颜色、字体、间距、阴影、动效与层级。 diff --git a/src/web-ui/src/infrastructure/i18n/README.md b/src/web-ui/src/infrastructure/i18n/README.md index 3cdd0d73e..8548d4dc7 100644 --- a/src/web-ui/src/infrastructure/i18n/README.md +++ b/src/web-ui/src/infrastructure/i18n/README.md @@ -1,3 +1,5 @@ +[中文](README.zh-CN.md) | **English** + # Frontend i18n ## Quick Start diff --git a/src/web-ui/src/infrastructure/i18n/README.zh-CN.md b/src/web-ui/src/infrastructure/i18n/README.zh-CN.md index fd84547bc..c555e3bc4 100644 --- a/src/web-ui/src/infrastructure/i18n/README.zh-CN.md +++ b/src/web-ui/src/infrastructure/i18n/README.zh-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](README.md) + # 前端国际化（i18n） ## 快速使用 diff --git a/src/web-ui/src/tools/lsp/README.md b/src/web-ui/src/tools/lsp/README.md index cf9d9c359..742253234 100644 --- a/src/web-ui/src/tools/lsp/README.md +++ b/src/web-ui/src/tools/lsp/README.md @@ -1,6 +1,16 @@ # LSP (Language Server Protocol) -BitFun’s plugin-based LSP implementation: completions, hover, definition, references, formatting, diagnostics, etc. +BitFun’s plugin-based LSP implementation: completions, hover, definition, references, formatting, diagnostics, and related editor features. + +## Scope + +This frontend directory is responsible for: + +- Monaco-facing integration hooks and services +- plugin management UI +- shared frontend types and exports + +Backend lifecycle management, plugin loading, and JSON-RPC transport live outside this directory. ## Architecture (high level) @@ -9,7 +19,7 @@ BitFun’s plugin-based LSP implementation: completions, hover, definition, refe Frontend layout: -``` +```text src/tools/lsp/ ├── services/ # backend calls + Monaco integration ├── hooks/ # React-facing hooks @@ -29,10 +39,11 @@ useMonacoLsp(editor, languageId, filePath, true, workspacePath); ``` Notes: + - `workspacePath` is required to enable non-builtin Monaco languages. -- For builtin Monaco languages (`typescript`, `javascript`, `typescriptreact`, `javascriptreact`) LSP is handled elsewhere. +- Builtin Monaco languages such as `typescript`, `javascript`, `typescriptreact`, and `javascriptreact` use a different integration path. -### Plugin management (UI/hook) +### Plugin management (UI or hook) ```ts import { useLspPlugins } from '@/tools/lsp'; @@ -42,7 +53,7 @@ const { plugins, loading, error, installPlugin, uninstallPlugin, reload } = useL Or use the ready-made component: -```ts +```tsx import { LspPluginList } from '@/tools/lsp'; @@ -52,7 +63,7 @@ import { LspPluginList } from '@/tools/lsp'; Plugin packages are `.vcpkg` files (ZIP under the hood): -``` +```text my-language-lsp-1.0.0.vcpkg ├── manifest.json ├── bin/ @@ -62,7 +73,7 @@ my-language-lsp-1.0.0.vcpkg └── config/ (optional) ``` -`manifest.json` (example): +`manifest.json` example: ```json { @@ -94,19 +105,10 @@ my-language-lsp-1.0.0.vcpkg ## Debugging - `initializeLsp()` sets up the extension registry and workspace initializer. -- `window.LspDiag` is installed as a lightweight debugging helper (see `src/tools/lsp/index.ts`). - - - - - - - - - - - - - +- `window.LspDiag` is installed as a lightweight debugging helper (see [index.ts](index.ts)). +## Constraints and Notes +- Keep package format and manifest fields aligned with the backend plugin loader. +- When adding new frontend LSP capabilities, verify whether the backend protocol already supports them. +- Keep this README focused on the frontend surface; backend implementation details should be documented closer to the Rust side. diff --git a/tests/e2e/AGENTS-CN.md b/tests/e2e/AGENTS-CN.md index 512545ef2..498b04a44 100644 --- a/tests/e2e/AGENTS-CN.md +++ b/tests/e2e/AGENTS-CN.md @@ -1,3 +1,5 @@ +**中文** | [English](AGENTS.md) + # AGENTS-CN.md ## 适用范围 diff --git a/tests/e2e/AGENTS.md b/tests/e2e/AGENTS.md index ab713f72f..63164ff68 100644 --- a/tests/e2e/AGENTS.md +++ b/tests/e2e/AGENTS.md @@ -1,3 +1,5 @@ +[中文](AGENTS-CN.md) | **English** + # AGENTS.md ## Scope diff --git a/tests/e2e/README.md b/tests/e2e/README.md index a3eb95dd5..e37c9d5f0 100644 --- a/tests/e2e/README.md +++ b/tests/e2e/README.md @@ -15,23 +15,21 @@ E2E test framework using WebDriverIO + the embedded BitFun WebDriver. cargo build -p bitfun-desktop # Install test dependencies -cd tests/e2e && pnpm install +pnpm --dir tests/e2e install ``` ### 2. Run Tests ```bash -cd tests/e2e - # L0 smoke tests (fastest) -pnpm run test:l0 -pnpm run test:l0:all +pnpm --dir tests/e2e run test:l0 +pnpm --dir tests/e2e run test:l0:all # L1 functional tests -pnpm run test:l1 +pnpm --dir tests/e2e run test:l1 # Run all tests -pnpm test +pnpm --dir tests/e2e test ``` ## Test Levels @@ -40,7 +38,7 @@ pnpm test |-------|---------|----------|-------------| | L0 | Smoke tests - verify basic functionality | < 1 min | No | | L1 | Functional tests - validate features | 5-15 min | No (mocked) | -| L2 | Integration tests - full system validation | 15-60 min | Yes | +| L2 | Planned, not implemented yet | N/A | N/A | ## Directory Structure diff --git a/tests/e2e/README.zh-CN.md b/tests/e2e/README.zh-CN.md index 46825e6df..68b7bd08f 100644 --- a/tests/e2e/README.zh-CN.md +++ b/tests/e2e/README.zh-CN.md @@ -15,23 +15,21 @@ cargo build -p bitfun-desktop # 安装测试依赖 -cd tests/e2e && pnpm install +pnpm --dir tests/e2e install ``` ### 2. 运行测试 ```bash -cd tests/e2e - # L0 冒烟测试 (最快) -pnpm run test:l0 -pnpm run test:l0:all +pnpm --dir tests/e2e run test:l0 +pnpm --dir tests/e2e run test:l0:all # L1 功能测试 -pnpm run test:l1 +pnpm --dir tests/e2e run test:l1 # 运行所有测试 -pnpm test +pnpm --dir tests/e2e test ``` ## 测试级别 @@ -40,7 +38,7 @@ pnpm test |------|------|----------|--------| | L0 | 冒烟测试 - 验证基本功能 | < 1分钟 | 不需要 | | L1 | 功能测试 - 验证功能特性 | 5-15分钟 | 不需要(mock) | -| L2 | 集成测试 - 完整系统验证 | 15-60分钟 | 需要 | +| L2 | 规划中，暂未实现 | N/A | N/A | ## 目录结构