kurihada
da1773b950
- 添加 blessed 终端 UI 库 - 创建 ChatView 组件：支持消息列表和流式输出 - 创建 SessionList 组件：会话管理和快捷键 - 创建 StatusBar 组件：连接状态显示 - 创建 TUIApp 主应用整合所有组件 - 更新 attach 命令支持 --tui/--no-tui 选项 - 添加 CLAUDE.md 项目规范文件 - 修复 Web 前端 CSS prose 类缺失问题
129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Important Rules
|
|
|
|
- **No backward compatibility**: This is a new project. Do not add any backward-compatible code, deprecated APIs, migration shims, or legacy support. Remove old code entirely when refactoring instead of keeping it around "just in case".
|
|
- **Git commits**: When asked to commit, only create the commit (no push). Commit messages must not contain any Claude-related information (no "Co-Authored-By", no "Generated with Claude", etc.).
|
|
- **Documentation**: All documentation must be stored under `docs/`. When implementing features based on design documents, update the corresponding document after coding is complete to reflect the current implementation status.
|
|
|
|
## Project Overview
|
|
|
|
AI Terminal Assistant is a terminal-based AI coding assistant built with Claude API. It's structured as a **pnpm monorepo** with four packages:
|
|
|
|
- **@ai-assistant/core** - Agent engine, tools, LSP integration, checkpoint system
|
|
- **@ai-assistant/server** - HTTP Server (Hono + Bun) with REST API, WebSocket, SSE
|
|
- **@ai-assistant/cli** - Command-line interface with `serve` and `attach` commands
|
|
- **@ai-assistant/web** - React frontend (Vite + Tailwind CSS)
|
|
|
|
## Build & Development Commands
|
|
|
|
```bash
|
|
# Install dependencies (use pnpm, not npm)
|
|
pnpm install
|
|
|
|
# Build all packages
|
|
pnpm build
|
|
|
|
# Run tests
|
|
pnpm test # All packages
|
|
pnpm --filter @ai-assistant/core test # Single package
|
|
pnpm --filter @ai-assistant/core test:watch # Watch mode
|
|
|
|
# Start development
|
|
pnpm server:dev # Start HTTP server (port 3000)
|
|
cd packages/web && pnpm dev # Start web UI (port 5173)
|
|
|
|
# CLI commands
|
|
cd packages/cli && bun run src/index.ts serve --port 3000
|
|
cd packages/cli && bun run src/index.ts attach http://localhost:3000
|
|
|
|
# Type checking
|
|
cd packages/web && pnpm typecheck
|
|
cd packages/server && pnpm build
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Package Dependencies
|
|
|
|
```
|
|
web / cli
|
|
↓
|
|
server → REST API + WebSocket + SSE
|
|
↓
|
|
core → Agent / Tools / LSP / Checkpoint / Hooks / MCP
|
|
```
|
|
|
|
### Core Package (`packages/core/src/`)
|
|
|
|
Key modules:
|
|
- `core/agent.ts` - Main Agent class using AI SDK's `streamText`
|
|
- `tools/` - Tool registry with bash, file operations, search, etc.
|
|
- `editors/` - Unified edit mode system (whole/diff/search-replace)
|
|
- `lsp/` - Language Server Protocol integration
|
|
- `checkpoint/` - Shadow Git checkpoint system
|
|
- `hooks/` - Pre/post execution hooks
|
|
- `mcp/` - Model Context Protocol client
|
|
- `repomap/` - Repository map generation with tree-sitter
|
|
|
|
### Server Package (`packages/server/src/`)
|
|
|
|
- `index.ts` - Hono app setup with CORS, auth middleware
|
|
- `routes/` - REST endpoints (sessions, tools, config)
|
|
- `ws.ts` - WebSocket handler for real-time chat
|
|
- `sse.ts` - Server-Sent Events for status updates
|
|
- `agent/adapter.ts` - Bridges core Agent to server (dynamic import to avoid build dependency)
|
|
- `auth/token.ts` - Token-based authentication (auto-enabled for non-localhost)
|
|
|
|
### Communication Flow
|
|
|
|
1. Client connects via WebSocket to `/api/ws/:sessionId`
|
|
2. Client sends `{ type: 'message', payload: { content } }`
|
|
3. Server calls `processMessage()` → Agent.chat() with streaming callback
|
|
4. Server pushes `chunk` events back via WebSocket
|
|
5. On completion, server sends `done` event with full response
|
|
|
|
## Key Design Patterns
|
|
|
|
### Dynamic Core Module Loading
|
|
|
|
Server uses dynamic import to avoid build-time dependency on core:
|
|
```typescript
|
|
const corePath = '@ai-assistant/core';
|
|
const core = await import(corePath) as CoreModule;
|
|
```
|
|
|
|
### Tool Registration
|
|
|
|
Tools are registered in `toolRegistry` with Zod schemas:
|
|
```typescript
|
|
toolRegistry.register({
|
|
name: 'read_file',
|
|
description: '...',
|
|
parameters: z.object({ path: z.string() }),
|
|
execute: async (params) => { ... }
|
|
});
|
|
```
|
|
|
|
### Session Management
|
|
|
|
Each WebSocket connection binds to a session. Sessions hold:
|
|
- Message history
|
|
- Status (idle/busy)
|
|
- Agent instance (cached per session)
|
|
|
|
## Configuration
|
|
|
|
- **Environment**: `ANTHROPIC_API_KEY` required in `.env`
|
|
- **Default model**: `claude-sonnet-4-20250514`
|
|
- **Server auth**: Auto-generates token when host is not localhost
|
|
|
|
## Design Documentation
|
|
|
|
Architecture details are in `docs/design/architecture/gui-server-client.md`, including:
|
|
- Implementation roadmap with completion status
|
|
- API endpoint specifications
|
|
- Communication protocol definitions
|