mirror of
https://github.com/instructkr/claude-code.git
synced 2026-05-26 15:36:46 +00:00
126 lines
11 KiB
Markdown
126 lines
11 KiB
Markdown
# Концепция проекта Claw Code
|
||
|
||
Документ фиксирует **цели**, **архитектуру** и **принципы** репозитория **Claw Code** — публичной Rust-реализации CLI-агента **`claw`** и сопутствующих инструментов. Источник правды по кодовой базе: workspace в каталоге [`rust/`](rust/README.md); операционные сценарии — [`USAGE.md`](USAGE.md), [`how_to_run.md`](how_to_run.md) (claw-analog), бэклог идеи — [`futute.md`](futute.md).
|
||
|
||
Отдельная продуктовая линия «из CLI → в личного помощника» (каналы/память/инструменты/проактивность/сессии) описана в [`docs/personal-assistant-roadmap.md`](docs/personal-assistant-roadmap.md).
|
||
|
||
---
|
||
|
||
## 1. Назначение продукта
|
||
|
||
**Claw Code** — это:
|
||
|
||
1. **Основной CLI `claw`** (`rusty-claude-cli`): полнофункциональный агент с REPL, OAuth, расширенным набором инструментов (включая bash, MCP, плагины и др.), стримингом и интеграцией с провайдерами **Anthropic**, **OpenAI-совместимыми** API и **xAI**.
|
||
2. **`claw-analog`** — облегчённая оболочка на **том же слое API** (`api` crate): узкий, предсказуемый набор инструментов только для работы с файловой системой воркспейса, явные режимы прав, пригодность для **CI**, **скриптов** и **внешних агентов** (NDJSON).
|
||
3. **`claw-rag-service`** — отдельный процесс: **индексация** репозитория (чанки + эмбеддинги в SQLite), **HTTP API** для семантического поиска и минимальный **веб-UI** для ручной проверки индекса.
|
||
|
||
Общая идея: дать **безопасный**, **аудируемый** и **воспроизводимый** способ вызова LLM над кодом и документацией, с путём эволюции от минимального harness до полного `claw`.
|
||
|
||
---
|
||
|
||
## 2. Целевая аудитория и сценарии
|
||
|
||
| Сегмент | Задача |
|
||
|---------|--------|
|
||
| Разработчик | Ежедневная работа с кодовой базой через полный `claw`: REPL, инструменты, сессии. |
|
||
| Автор автоматизации | Одноразовые промпты, пайплайны с `--output-format json`, встроенные агенты без bash. |
|
||
| Сопровождение / аудит | `claw-analog` в **read-only** + пресет **audit**; явные лимиты и политика. |
|
||
| Порт и parity | Сравнение поведения с эталоном (`PARITY.md`, mock-harness). |
|
||
| RAG над монорепо | Отдельный `ingest` + `serve`; агент подключает контекст через **`retrieve_context`** при заданном `RAG_BASE_URL`. |
|
||
|
||
---
|
||
|
||
## 3. Архитектура (логическая)
|
||
|
||
```text
|
||
┌─────────────────────────────────────┐
|
||
│ Провайдеры (Anthropic / OpenAI / …) │
|
||
└─────────────────┬───────────────────┘
|
||
│
|
||
┌──────────────────────────────┼──────────────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
|
||
│ rusty- │ │ claw-analog │ │ claw-rag-service │
|
||
│ claude-cli │ │ (lean loop) │ │ HTTP + SQLite │
|
||
│ («claw») │ │ │ │ ingest / query │
|
||
└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘
|
||
│ │ │
|
||
│ crates/api │ retrieve_context │
|
||
│ runtime, tools, … │ (POST /v1/query) │
|
||
└──────────────┬───────────────┴───────────────────────────────┘
|
||
│
|
||
▼
|
||
Файловая система / workspace (-w)
|
||
```
|
||
|
||
**Принцип разделения:** тяжёлая индексация и хранение эмбеддингов **не** зашиваются в `claw-analog`, а живут в **`claw-rag-service`**. Агент только вызывает retrieval по HTTP — проще масштабировать, менять векторное хранилище и секреты эмбеддингов.
|
||
|
||
---
|
||
|
||
## 4. Принципы проектирования
|
||
|
||
1. **Безопасность по умолчанию** — относительные пути, запрет `..`, проверка выхода за canonical workspace; режимы `PermissionMode` согласованы с полным CLI; в неинтерактивном режиме опасные режимы блокируются без явного флага.
|
||
2. **Явные лимиты** — размер чтения, число ходов, glob/grep caps, таймауты RAG; сбои предсказуемы, а не «OOM или вечный цикл».
|
||
3. **Наблюдаемость для агентов** — NDJSON с `schema` и `format_version` на `run_start`, структурированные `tool_result`.
|
||
4. **Модульность** — общий `api` для провайдеров; `claw-analog` не дублирует стек ключей RAG, только HTTP-клиент к сервису.
|
||
5. **Паритет и тесты** — mock Anthropic, сценарии harness, отдельные job’ы CI для критичных crate’ов.
|
||
6. **Документация рядом с кодом** — `how_to_run.md`, `docs/rag-web-ui.md`, `docs/container.md` и т.д.
|
||
|
||
---
|
||
|
||
## 5. Компоненты workspace (кратко)
|
||
|
||
- **`rusty-claude-cli`** — основной бинарь **`claw`**: пользовательский продукт полной мощности.
|
||
- **`api`** — клиенты провайдеров, стриминг, типы запросов/ответов.
|
||
- **`runtime`** — сессии, конфиг, **PermissionPolicy** / **PermissionEnforcer**, промпты, MCP и др.
|
||
- **`tools`** — встроенные инструменты полного CLI.
|
||
- **`claw-analog`** — минимальный цикл: инструменты чтения/поиска/записи (по режиму), стриминг и JSON, TOML-конфиг, сессии, doctor, config validate, **retrieve_context** при наличии `RAG_BASE_URL` / `rag_base_url`.
|
||
- **`claw-rag-service`** — `ingest`, `serve`, маршруты `/`, `/health`, `/v1/stats`, `/v1/query`; SQLite + OpenAI-совместимые эмбеддинги (или mock для тестов).
|
||
- **`mock-anthropic-service`**, **`compat-harness`** и др. — воспроизводимость и миграция.
|
||
|
||
Подробная раскладка: [`rust/README.md`](rust/README.md).
|
||
|
||
---
|
||
|
||
## 6. Claw-analog: роль и границы
|
||
|
||
**Задача:** дать «агента с инструментами» без разрастания поверхности атаки (нет произвольного shell в базовом сценарии).
|
||
|
||
**Инструменты (концептуально):** чтение и обход дерева (`read_file`, `list_dir`, `glob_workspace`), литеральный поиск (`grep_workspace` / `grep_search`), опционально `write_file`, опционально **`retrieve_context`** к RAG-сервису.
|
||
|
||
**Не входит в минимальный дизайн:** MCP, плагины, bash — это зона **полного `claw`**.
|
||
|
||
---
|
||
|
||
## 7. RAG-сервис: роль и эволюция
|
||
|
||
**Сейчас (MVP):** полный переиндекс при `ingest`, векторы в SQLite, поиск — линейный косинус по всем чанкам; подходит для умеренных объёмов кода.
|
||
|
||
**Направления роста (концепция):** инкрементальная индексация, ANN (sqlite-vec, Qdrant/Chroma в Docker), rate limits на эмбеддинги. Веб-UI на `GET /` — вспомогательный; продвинутый UI и авторизация — по мере необходимости.
|
||
|
||
Детали: [`docs/rag-web-ui.md`](docs/rag-web-ui.md).
|
||
|
||
---
|
||
|
||
## 8. Репозиторий вне основного runtime
|
||
|
||
- **`src/`**, **`tests/`** (Python и прочее) — вспомогательные/экспериментальные артефакты; **канонический runtime** — **`rust/`**.
|
||
- Документы **PHILOSOPHY.md**, **ROADMAP.md**, **PARITY.md** дополняют концепцию процессом и намерениями сообщества/мейнтейнеров.
|
||
|
||
---
|
||
|
||
## 9. Связанные концепции (не ядро Claw Code)
|
||
|
||
В **`docs/`** могут находиться переносимые заметки для **других** продуктов (например локальный vision для NestJS-приложений) — они **не** определяют обязательное поведение `claw`, но отражают смежный интерес contributors.
|
||
|
||
---
|
||
|
||
## 10. Итоговая формулировка
|
||
|
||
**Claw Code** — это экосистема **Rust** вокруг агента **`claw`**: полный CLI для разработчиков, **`claw-analog`** как управляемый минимальный агент для автоматизации и **отдельный RAG-сервис** для семантического поиска по коду. Проект опирается на **явные права**, **лимиты**, **тестируемость** и **чёткие HTTP-границы** между агентом и тяжёлой индексацией.
|
||
|
||
---
|
||
|
||
*Обновляйте этот файл при смене ключевых продуктовых решений; детальный чеклист фич и backlog — в [`futute.md`](futute.md).*
|