Hugging Face's logo

Spaces:
AZILS
/
claw-web-v2
Sleeping

App Files Community
claw-web-v2 / HANDOFF.md
Claw Web
Claw Web v1.0 — AI Agent Web Interface with MiMo-V2-Flash
7540aea
preview code
|
raw
history blame contribute delete
18.6 kB

🔥 HANDOFF: Claw Web — Полная документация для следующего агента

Что это за проект

Claw Web — это веб-версия Claude Code (claw-code), AI coding agent с полным набором инструментов, работающий в браузере. Оригинальный проект написан на Rust + TypeScript (CLI/TUI), мы портировали его в веб-приложение на React + Express + tRPC.

Оригинальный репо: /home/ubuntu/claw-code-original/ (14MB, полный клон с GitHub) Наш проект: /home/ubuntu/claw-web/ (webdev проект на Manus) Деплой: https://clawweb-sfvpumtx.manus.space

Архитектура проекта 

claw-web/
├── client/                          # React 19 + Tailwind 4 фронтенд
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Home.tsx             # Главная страница — чат интерфейс (973 строк)
│   │   │   ├── ComponentShowcase.tsx # Демо компонентов (1437 строк)
│   │   │   └── NotFound.tsx         # 404 страница
│   │   ├── components/
│   │   │   ├── Sidebar.tsx          # Боковая панель с сессиями (303 строк)
│   │   │   ├── ChatInput.tsx        # Поле ввода с / командами (191 строк)
│   │   │   ├── MessageBubble.tsx    # Рендер сообщений (219 строк)
│   │   │   ├── ToolCallCard.tsx     # Карточки tool calls (470 строк)
│   │   │   ├── ThinkingBlock.tsx    # Блок "думает..." (65 строк)
│   │   │   ├── SettingsPanel.tsx    # Панель настроек (615 строк)
│   │   │   ├── TerminalPanel.tsx    # Встроенный терминал (269 строк)
│   │   │   ├── FileManagerPanel.tsx # Файловый менеджер (604 строк)
│   │   │   ├── PluginMarketplace.tsx# Маркетплейс плагинов (190 строк)
│   │   │   ├── TaskManagerPanel.tsx # Менеджер задач (119 строк)
│   │   │   ├── CronManagerPanel.tsx # Менеджер cron задач (121 строк)
│   │   │   ├── BuddySprite.tsx      # Анимированный маскот (119 строк)
│   │   │   ├── ErrorBoundary.tsx    # Error boundary (62 строк)
│   │   │   └── ManusDialog.tsx      # Диалоговое окно (89 строк)
│   │   ├── hooks/
│   │   │   ├── useChat.ts           # SSE чат хук (531 строк) — КЛЮЧЕВОЙ
│   │   │   ├── useComposition.ts    # IME composition (81 строк)
│   │   │   └── usePersistFn.ts      # Persistent callback (20 строк)
│   │   ├── contexts/
│   │   │   └── ThemeContext.tsx      # Тема (dark/light)
│   │   ├── lib/
│   │   │   ├── trpc.ts              # tRPC клиент
│   │   │   └── utils.ts             # Утилиты
│   │   ├── App.tsx                  # Роутинг
│   │   ├── main.tsx                 # Entry point
│   │   └── index.css                # Глобальные стили (тёмная тема)
│   └── index.html
│
├── server/                          # Express + tRPC бэкенд
│   ├── runtime/                     # ← ЯДРО АГЕНТА
│   │   ├── agent.ts                 # Agentic loop — run_turn (658 строк)
│   │   ├── system-prompt.ts         # System prompt builder (1038 строк)
│   │   ├── chat-endpoint.ts         # SSE endpoint + 114 slash commands (2269 строк)
│   │   ├── compact.ts              # Context compaction (527 строк)
│   │   ├── config.ts               # RuntimeConfig + ConfigLoader (599 строк)
│   │   ├── mcp-client.ts           # MCP клиент + 6 транспортов (686 строк)
│   │   ├── plugins.ts              # PluginManager (932 строк)
│   │   ├── lsp-client.ts           # LSP клиент (616 строк)
│   │   ├── usage.ts                # UsageTracker + pricing (225 строк)
│   │   ├── session.ts              # Session serialization (191 строк)
│   │   └── bootstrap.ts            # Bootstrap phases (71 строк)
│   ├── tools/
│   │   └── executor.ts             # 41 tool handlers (1875 строк)
│   ├── db.ts                       # Database queries (242 строк)
│   ├── routers.ts                  # tRPC routers (262 строк)
│   ├── storage.ts                  # S3 storage (102 строк)
│   ├── agent-runtime.test.ts       # Agent tests (828 строк)
│   ├── compact-config.test.ts      # Compact/config tests (777 строк)
│   ├── routers.test.ts             # Router tests (258 строк)
│   ├── slash-commands.test.ts      # Command tests (155 строк)
│   └── auth.logout.test.ts         # Auth tests (62 строк)
│
├── shared/
│   ├── claw-types.ts               # Все типы + модели + команды (281 строк)
│   ├── const.ts                    # Константы
│   └── types.ts                    # Общие типы
│
├── drizzle/                         # Database schema + migrations
│   ├── schema.ts                   # Таблицы: users, sessions, messages, tasks, cron_jobs
│   └── *.sql                       # Миграции
│
├── todo.md                          # Полный трекер всех фич (596 строк)
├── PARITY_REPORT.md                 # Отчёт о паритете с оригиналом
└── critical-understanding.txt       # Заметки по архитектуре

Как работает агентский цикл 

Пользователь → ChatInput → POST /api/chat (SSE) → chat-endpoint.ts
                                                        ↓
                                                  runAgentLoop() в agent.ts
                                                        ↓
                                              ┌─── buildSystemPrompt()
                                              ├─── LLM API call (streaming)
                                              ├─── Parse tool_use blocks
                                              ├─── runPreToolHooks()
                                              ├─── executeTool() в executor.ts
                                              ├─── runPostToolHooks()
                                              ├─── compactMessagesIfNeeded()
                                              └─── Loop until done or max_iterations
                                                        ↓
                                              SSE events → useChat.ts → UI

Текущее состояние (на 2 апреля 2026)

Что работает на 85-100%:

  • 41 инструмент (Bash, FileRead, FileWrite, FileEdit, Grep, Glob, WebSearch, WebFetch, Agent sub-agent, TaskCreate, CronCreate, и т.д.)
  • 114 slash commands (/help, /model, /cost, /compact, /export, /resume, /config, /plugins, /mcp, /doctor, и т.д.)
  • System prompt — все секции из оригинала
  • Auto-compaction — compact_after_turns=12
  • Usage tracking — cost per model, format_usd
  • Session management — create/switch/delete/export/resume
  • Hooks — pre/post tool hooks с exit code 2=deny
  • Streaming SSE — real-time tool execution
  • Dark theme UI — sidebar, chat, terminal, file manager, settings

Что работает на 35-65% (НУЖНО ДОДЕЛАТЬ):

  • Plugins (35%) — класс есть, нет persistence и sandbox
  • MCP (40%) — типы есть, нет реального stdio spawn
  • Permissions (50%) — базовый, нет glob matching
  • Config (55%) — нет schema validation, file watcher
  • LSP (55%) — grep-fallback, нет реального LSP
  • Tools depth (55%) — happy path, нет edge cases
  • Session (60%) — нет file-based storage
  • File ops (65%) — нет apply_diff, detect_binary

Что полностью отсутствует:

  • sandbox.rs (364 строк) — container detection, Linux namespaces
  • remote.rs (401 строк) — upstream proxy, WebSocket bridge
  • oauth.rs (589 строк) — PKCE flow

ПЛАН ДЕЙСТВИЙ ДЛЯ СЛЕДУЮЩЕГО АГЕНТА

Приоритет 1: Plugins (35% → 95%) — ~2000 строк

Файл: server/runtime/plugins.ts (932 строк → ~2500 строк) Оригинал: rust/crates/plugins/src/lib.rs (2943 строк) + hooks.rs (395 строк)

Что нужно добавить:

  1. PluginRegistry persistence — сохранение/загрузка registry.json на диск (или в DB)
  2. PluginTool.execute() — реальное выполнение plugin tools с sandbox isolation
  3. validate_plugin_source() — валидация git URL, загрузка manifest
  4. builtin_plugins() — реальная загрузка 8 bundled плагинов из директории
  5. PluginSummary — полное форматирование с version, author, enabled status
  6. Plugin settings — per-plugin configuration persistence
  7. Plugin trust verification — проверка подписей и trusted sources
  8. aggregated_hooks() — реальная агрегация хуков из всех плагинов
  9. aggregated_tools() — реальная агрегация tools из всех плагинов

Как делать:

  • Читай rust/crates/plugins/src/lib.rs строка за строкой
  • Каждый pub fn → TypeScript метод
  • Каждый struct → TypeScript interface
  • Каждый enum → TypeScript enum

Приоритет 2: MCP Client (40% → 95%) — ~1500 строк

Файл: server/runtime/mcp-client.ts (686 строк → ~2000 строк) Оригинал: rust/crates/runtime/src/mcp_stdio.rs (1720 строк) + mcp.rs (300) + mcp_client.rs (234)

Что нужно добавить:

  1. Реальный stdio spawn — child_process.spawn() с pipe для stdin/stdout
  2. Frame-based protocol — encode_frame() / read_frame() для JSON-RPC over stdio
  3. Reconnection с backoff — exponential backoff при disconnect
  4. McpServerHealth — мониторинг здоровья каждого сервера
  5. discover_tools с кешированием — кеш tool definitions per server
  6. SSE transport — реальный EventSource клиент
  7. HTTP transport — реальный fetch-based JSON-RPC
  8. Resource templates — resources/templates/list MCP метод
  9. Prompts — prompts/list и prompts/get MCP методы
  10. Sampling — sampling/createMessage MCP метод

Как делать:

  • Используй @modelcontextprotocol/sdk npm пакет для MCP клиента
  • Или реализуй вручную JSON-RPC over stdio как в оригинале
  • Читай mcp_stdio.rs для frame protocol

Приоритет 3: Config System (55% → 95%) — ~700 строк

Файл: server/runtime/config.ts (599 строк → ~1200 строк) Оригинал: rust/crates/runtime/src/config.rs (1294 строк)

Что нужно добавить:

  1. JSON Schema validation — validate config against schema
  2. config_watch() — chokidar file watcher для auto-reload
  3. config_diff() — diff между двумя конфигами
  4. resolve_config_path() — XDG-compatible path resolution
  5. ~40 accessor методов — каждое поле конфига через getter
  6. Config migration — upgrade old config format to new
  7. Config templates — preset configurations

Приоритет 4: LSP Client (55% → 90%) — ~600 строк

Файл: server/runtime/lsp-client.ts (616 строк → ~1100 строк) Оригинал: rust/crates/lsp/src/ (1185 строк)

Что нужно добавить:

  1. Реальный LSP stdio клиент — spawn language server, JSON-RPC
  2. LspManager — multi-server management (TypeScript, Python, Go, etc.)
  3. initialize handshake — LSP protocol initialization
  4. textDocument/didOpen — file open notifications
  5. workspace/symbol — workspace-wide symbol search
  6. Fallback to grep — когда LSP недоступен (уже есть)

Приоритет 5: Tools Depth (55% → 85%) — ~1500 строк

Файл: server/tools/executor.ts (1875 строк → ~3500 строк) Оригинал: rust/crates/tools/src/lib.rs (4469 строк)

Что нужно добавить для каждого tool:

  1. Полная валидация входных параметров — type checking, bounds checking
  2. Structured error types — FileOperationError, BashError, etc.
  3. Edge case handling — binary files, symlinks, large files, encoding issues
  4. apply_diff() — для FileEdit tool
  5. detect_binary() — для FileRead tool
  6. resolve_symlinks() — для file operations
  7. validate_utf8() — для text operations
  8. Output truncation — consistent 30000 char limit with smart truncation

Приоритет 6: Permissions (50% → 90%) — ~200 строк

Файл: server/tools/executor.ts (permissions section) Оригинал: rust/crates/runtime/src/permissions.rs (232 строк)

Что нужно добавить:

  1. PermissionRule struct — glob patterns for tool matching
  2. PermissionEvaluator — evaluate rules against tool calls
  3. glob_match_tool_name() — wildcard matching
  4. permission_prompt_text() — human-readable permission descriptions
  5. Permission persistence — save/load permission decisions

Приоритет 7: Session (60% → 90%) — ~250 строк

Файл: server/runtime/session.ts (191 строк → ~400 строк) Оригинал: rust/crates/runtime/src/session.rs (436 строк)

Что нужно добавить:

  1. load_from_path() — загрузка сессии из файла
  2. save_to_path() — сохранение сессии в файл
  3. session_storage_dir() — директория для хранения сессий
  4. list_sessions() — список всех сохранённых сессий
  5. SessionMetadata — метаданные сессии (created_at, model, message_count)

Приоритет 8: Отсутствующие модули

sandbox.ts (~300 строк) — НИЗКИЙ ПРИОРИТЕТ

  • detect_container_environment()
  • resolve_sandbox_status()
  • build_linux_sandbox_command()
  • В веб-версии sandbox — это сам сервер, поэтому большая часть не нужна

remote.ts (~300 строк) — НИЗКИЙ ПРИОРИТЕТ

  • UpstreamProxyConfig
  • WebSocket bridge
  • subprocess_env
  • Специфично для CLI, в веб-версии не критично

Как запустить проект 

cd /home/ubuntu/claw-web
pnpm install
pnpm dev          # Dev server на порту 3000
pnpm test         # 173 теста
npx tsc --noEmit  # Type checking (0 ошибок)

Как запустить тесты 

cd /home/ubuntu/claw-web
pnpm test                    # Все 173 теста
pnpm test -- --grep "agent"  # Только agent тесты
pnpm test -- --grep "compact" # Только compact тесты

Как сравнивать с оригиналом 

# Оригинальный репо
ls /home/ubuntu/claw-code-original/rust/crates/

# Ключевые файлы оригинала:
cat /home/ubuntu/claw-code-original/rust/crates/runtime/src/conversation.rs  # → agent.ts
cat /home/ubuntu/claw-code-original/rust/crates/tools/src/lib.rs             # → executor.ts
cat /home/ubuntu/claw-code-original/rust/crates/commands/src/lib.rs          # → chat-endpoint.ts
cat /home/ubuntu/claw-code-original/rust/crates/plugins/src/lib.rs           # → plugins.ts
cat /home/ubuntu/claw-code-original/rust/crates/runtime/src/mcp_stdio.rs     # → mcp-client.ts
cat /home/ubuntu/claw-code-original/rust/crates/runtime/src/config.rs        # → config.ts
cat /home/ubuntu/claw-code-original/rust/crates/lsp/src/                     # → lsp-client.ts

Ключевые зависимости

  • LLM API: через server/_core/llm.ts (invokeLLM) — Manus built-in
  • Database: MySQL/TiDB через Drizzle ORM
  • Auth: Manus OAuth через server/_core/oauth.ts
  • Storage: S3 через server/storage.ts
  • Frontend: React 19 + Tailwind 4 + shadcn/ui + wouter (routing)

Важные замечания

  1. НЕ трогай файлы в server/_core/ — это фреймворк Manus
  2. Все статические файлы загружай через manus-upload-file --webdev
  3. Database миграции через pnpm drizzle-kit generate + webdev_execute_sql
  4. Тесты обязательны перед каждым checkpoint
  5. Оригинальный репо в /home/ubuntu/claw-code-original/ — используй для справки

Общая оценка паритета

Метрика Значение
Фичи (количество) ~88%
Глубина реализации ~62%
Строк кода (сервер) 10,191 vs 34,065 оригинал
Инструменты 41/41 (100%)
Команды 114/~101 (113%)
Тесты 173
TS ошибки 0

Цель: довести глубину реализации до 90%+