diff --git a/concept.md b/concept.md new file mode 100644 index 00000000..5139ade9 --- /dev/null +++ b/concept.md @@ -0,0 +1,125 @@ +# Концепция проекта 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).* diff --git a/docs/personal-assistant-roadmap.md b/docs/personal-assistant-roadmap.md new file mode 100644 index 00000000..5948706c --- /dev/null +++ b/docs/personal-assistant-roadmap.md @@ -0,0 +1,131 @@ +# From Claw Code to a Personal AI Assistant (Life OS) + +This document turns the current “developer CLI agent” direction into a concrete path toward a **personal AI assistant**: a multi-channel interface (chat/voice), personal memory (RAG for life), tool/action integrations (MCP + plugins), proactivity (OmX-style loops), and long-lived identity (sessions + profile). + +It is intentionally pragmatic: each section has **MVP scope**, **next step**, and **evolution**. + +--- + +## 1) Interface: out of the terminal + +### Goal +Make `claw` usable without opening an IDE or terminal — from a phone, from chat, and eventually by voice. + +### MVP +- **Chat bridge**: a small service that relays messages from **Discord** (primary) or Telegram to `claw` / `claw-analog`. + - Treat the chat thread as the “front-end”, and `claw` as the execution runtime. + - Map a channel/thread to a **session id** (resume/append). +- **Basic UX**: slash-like commands in chat: + - `/prompt …`, `/resume latest`, `/status`, `/cost`, `/help` + - “safe mode” defaults (read-only) unless elevated explicitly. + +### Next step +- **Voice**: + - Speech-to-text input (e.g. Whisper-class STT) into the same chat bridge. + - Text-to-speech output for hands-free feedback. + +### Evolution +- Multi-modal: attachments (images/PDF) routed into ingest/personal memory. +- Presence and notifications: summaries pushed back into chat. + +--- + +## 2) Memory: from “RAG for code” to “RAG for life” + +### Goal +Let the assistant answer personal questions and make decisions using *your* long-term context, not only the current repo. + +### MVP +- Extend ingestion inputs beyond git workspaces: + - Notes (Markdown), exported chats, simple text logs. + - PDFs (initially text extraction outside Rust is OK; later: built-in pipeline). +- Keep a clear separation: + - **Work RAG** (code/workspaces) + - **Personal RAG** (notes, plans, history) + +### Next step +- Evolve `retrieve_context` into a **multi-source retrieval tool**: + - “where to search” selector (work/personal/both) + - metadata filters (source, date ranges, tags) + +### Evolution +- Incremental ingestion + event-based updates (watch folders, chat events). +- Better stores (ANN/Qdrant/etc) when scale demands it. + +--- + +## 3) Hands: tools, MCP, plugins + +### Goal +The assistant is valuable because it can **do** things, not only talk. + +### MVP +- Wire in external systems via **MCP servers**: + - Calendar, notes (Notion), email, task trackers, smart home (as available). +- Establish a convention for “personal skills”: + - a dedicated directory (e.g. `.claw/skills/`) for user-specific automations + - small, composable tools (digest, budgeting, reminders) rather than monoliths + +### Next step +- “Tool discovery” UX: list available MCP/tools/skills directly from chat. +- Permission boundaries per tool category (read vs write, destructive actions require explicit confirmation). + +### Evolution +- Plugin marketplace flows for reusing “skills”. +- Audit logging and replay of actions. + +--- + +## 4) Proactivity: OmX-style loops + +### Goal +Move from reactive “answer me” to proactive “notice + prepare + propose + execute”. + +### MVP +- A scheduled runner that periodically: + - checks inbox/notifications + - extracts actionable tasks + - drafts responses + - posts a short digest to chat + +### Next step +- Multi-agent patterns (Architect/Executor/Reviewer) for higher reliability: + - executor proposes actions + - reviewer validates safety and correctness + - only then does the bridge run the write/action tool + +### Evolution +- Event-driven triggers (webhooks) instead of only cron. +- “Autopilot” modes with bounded scopes (time, tools, spend limits). + +--- + +## 5) Long-lived identity: sessions + profile + +### Goal +Make the assistant feel continuous and personalized across days/weeks. + +### MVP +- Default to resuming the latest session (`--resume latest`-style behavior). +- Use a short, user-owned profile/system-prompt for tone and preferences. + +### Next step +- Separate: + - “personality” (style, preferences) + - “memory” (facts, history) + - “policies” (permissions, safety rules) + +### Evolution +- Multiple personas (work/personal) with explicit switching. +- Transparent memory controls (“forget this”, “store this”). + +--- + +## Suggested milestone sequence + +1. **Discord bridge + session mapping** (no new AI capabilities; just distribution). +2. **Personal ingest source #1** (notes folder) + retrieval selector (personal/work). +3. **One MCP integration** (calendar or notes) + a single “daily digest” skill. +4. **Scheduled digest loop** (cron) with bounded permissions. +5. **Voice input/output** on top of the same bridge. +