mirror of https://github.com/instructkr/claude-code.git synced 2026-05-25 15:06:44 +00:00

Files

gismo212 52572d5883 docs: personal assistant roadmap

Adds personal assistant roadmap and concept documentation.

2026-05-25 11:24:55 +09:00

11 KiB

Raw Blame History

Концепция проекта Claw Code

Документ фиксирует цели, архитектуру и принципы репозитория Claw Code — публичной Rust-реализации CLI-агента claw и сопутствующих инструментов. Источник правды по кодовой базе: workspace в каталоге rust/; операционные сценарии — USAGE.md, how_to_run.md (claw-analog), бэклог идеи — futute.md.

Отдельная продуктовая линия «из CLI → в личного помощника» (каналы/память/инструменты/проактивность/сессии) описана в docs/personal-assistant-roadmap.md.

1. Назначение продукта

Claw Code — это:

Основной CLI claw (rusty-claude-cli): полнофункциональный агент с REPL, OAuth, расширенным набором инструментов (включая bash, MCP, плагины и др.), стримингом и интеграцией с провайдерами Anthropic, OpenAI-совместимыми API и xAI.
claw-analog — облегчённая оболочка на том же слое API (api crate): узкий, предсказуемый набор инструментов только для работы с файловой системой воркспейса, явные режимы прав, пригодность для CI, скриптов и внешних агентов (NDJSON).
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. Архитектура (логическая)

                    ┌─────────────────────────────────────┐
                    │  Провайдеры (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. Принципы проектирования

Безопасность по умолчанию — относительные пути, запрет .., проверка выхода за canonical workspace; режимы PermissionMode согласованы с полным CLI; в неинтерактивном режиме опасные режимы блокируются без явного флага.
Явные лимиты — размер чтения, число ходов, glob/grep caps, таймауты RAG; сбои предсказуемы, а не «OOM или вечный цикл».
Наблюдаемость для агентов — NDJSON с schema и format_version на run_start, структурированные tool_result.
Модульность — общий api для провайдеров; claw-analog не дублирует стек ключей RAG, только HTTP-клиент к сервису.
Паритет и тесты — mock Anthropic, сценарии harness, отдельные job’ы CI для критичных crate’ов.
Документация рядом с кодом — 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.

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.

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.

11 KiB Raw Blame History Unescape Escape