mirror of
https://github.com/instructkr/claude-code.git
synced 2026-05-26 23:46:45 +00:00
docs: personal assistant roadmap
Adds personal assistant roadmap and concept documentation.
This commit is contained in:
gismo212
GitHub
125
concept.md
Normal file
125
concept.md
Normal file
@@ -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).*
|
||||
131
docs/personal-assistant-roadmap.md
Normal file
131
docs/personal-assistant-roadmap.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user