# Aichat: Полный гайд по CLI, агентам, макросам, RAG и проектам
*На основе диалога с Grok, 8 ноября 2025*
---
## Содержание
1. [Введение в `aichat`](#введение-в-aichat)
2. [Локальные модели (Ollama, llama.cpp)](#локальные-модели)
3. [Агенты: создание и управление](#агенты)
4. **[Макросы: цепочки и автоматизация — расширенный раздел]**(#макросы)
- [4.1 Что такое макросы](#макросы-что)
- [4.2 Где хранятся макросы](#макросы-где)
- [4.3 Структура `macros.toml`](#макросы-структура)
- [4.4 Переменные и подстановки](#макросы-переменные)
- [4.5 Условия (`if`)](#макросы-условия)
- [4.6 Циклы (`repeat`)](#макросы-циклы)
- [4.7 Работа с файлами](#макросы-файлы)
- [4.8 RAG в макросах](#макросы-rag)
- [4.9 Инструменты и внешние команды](#макросы-инструменты)
- [4.10 Передача контекста между агентами](#макросы-handover)
- [4.11 Примеры: от простого к сложному](#макросы-примеры)
- [4.12 Лучшие практики и безопасность](#макросы-best)
5. [Локальные конфиги по проекту (`.aichat/`)](#локальные-конфиги)
6. [Режимы работы aichat](#режимы-работы)
7. [RAG: векторный поиск в проектах](#rag-в-проектах)
8. [Примеры проектов](#примеры-проектов)
9. [Шпаргалка](#шпаргалка)
---
<a name="введение-в-aichat"></a>
## 1. Введение в `aichat`
**`sigoden/aichat`** — CLI-инструмент для работы с LLM:
- Локальные модели (Ollama, llama.cpp, vLLM)
- Агенты с инструментами
- **Макросы** — мощные цепочки команд
- RAG (локальный векторный поиск)
- Локальные конфиги по проекту
- OpenAI-совместимый API
```bash
cargo install aichat
```
---
<a name="локальные-модели"></a>
## 2. Локальные модели
```bash
# Установи Ollama
curl -fsSL
https://ollama.com/install.sh | sh
ollama run llama3.2
```
```bash
aichat --model ollama/llama3.2 "Привет"
```
---
<a name="агенты"></a>
## 3. Агенты
### Глобальные: `~/.config/aichat/agents.toml`
### Локальные: `./.aichat/agents.toml`
```toml
[agents.translator]
model = "ollama/mistral"
instructions = "Переводи на английский. Только текст."
tools = ["search"]
[agents.summarizer]
model = "ollama/llama3.2"
instructions = "Сделай summary в 1 предложении."
```
```bash
aichat --agent translator "Привет, мир!"
```
---
<a name="макросы"></a>
## 4. Макросы: цепочки и автоматизация — расширенный раздел
---
<a name="макросы-что"></a>
### 4.1 Что такое макросы?
> **Макрос** — это **сохранённая последовательность команд REPL**, которую можно вызвать одной строкой.
- Определяется в `macros.toml` (глобально или локально)
- Поддерживает:
- Входные параметры
- Переменные
- Условия
- Циклы
- Файлы
- RAG
- Внешние команды
- Передачу контекста
---
<a name="макросы-где"></a>
### 4.2 Где хранятся макросы?
| Тип | Путь |
|-----|------|
| **Глобальные** | `~/.config/aichat/macros.toml` |
| **Локальные (проектные)** | `./.aichat/macros.toml` |
> Локальные **переопределяют** глобальные.
---
<a name="макросы-структура"></a>
### 4.3 Структура `macros.toml`
```toml
[macros.translate_and_summarize]
description = "Перевод + summary"
steps = [
"agent translator translate_to_en {{input}}",
"agent summarizer summarize {{output}}"
]
[macros.smart_router]
description = "Роутинг по типу задачи"
steps = [
"agent router classify {{input}}",
"if {{output}} contains 'перевод' then agent translator to_en {{input}}",
"else if {{output}} contains 'код' then agent coder write {{input}}",
"else agent general respond {{input}}"
]
```
---
<a name="макросы-переменные"></a>
### 4.4 Переменные и подстановки
| Переменная | Значение |
|----------|---------|
| `{{input}}` | Входной текст от пользователя |
| `{{output}}` | Результат **последней** команды |
| `{{prev}}` | Результат **предпоследней** команды |
| `{{0}}`, `{{1}}`, `{{n}}` | Результат команды с номером `n` |
| `{{agent_name.output}}` | Вывод конкретного агента |
| `{{timestamp}}` | `2025-11-08T12:34:56` |
| `{{date}}`, `{{time}}` | Дата/время |
| `{{uuid}}` | Случайный ID |
| `{{input | slugify}}` | Преобразование (см. ниже) |
#### Фильтры (в `{{ }}`)
```toml
{{input | lower}} # в нижний регистр
{{input | upper}} # в верхний
{{input | slugify}} # для имён файлов
{{input | trim}} # убрать пробелы
```
---
<a name="макросы-условия"></a>
### 4.5 Условия (`if`)
```toml
if <выражение> then <команда>
else <команда>
```
#### Выражения:
```toml
{{output}} contains "перевод"
{{output}} starts_with "Error"
{{output}} matches "^\\d+$" # regex
{{input}} length > 100
```
#### Пример:
```toml
[macros.validate_and_process]
steps = [
"agent validator check {{input}}",
"if {{output}} contains 'valid' then agent processor run {{input}}",
"else !echo 'Ошибка: {{output}}' > /tmp/error.log"
]
```
---
<a name="макросы-циклы"></a>
### 4.6 Циклы (`repeat`)
```toml
repeat <N> times
<команды>
```
#### Пример: итеративное улучшение текста
```toml
[macros.iterative_writing]
steps = [
"!echo 'Черновик 0' > /tmp/draft.txt",
"repeat 3 times",
" @read_file /tmp/draft.txt",
" agent writer improve {{output}}",
" !echo '{{output}}' > /tmp/draft.txt",
" if {{output}} contains 'отлично' then break",
"@read_file /tmp/draft.txt"
]
```
---
<a name="макросы-файлы"></a>
### 4.7 Работа с файлами
| Команда | Описание |
|--------|--------|
| `!cmd` | Выполнить shell |
| `@read_file path` | Прочитать → `{{output}}` |
| `@write_file path content` | Записать |
| `@append_file path content` | Дописать |
| `@edit_file path` | Открыть в `$EDITOR` |
#### Пример: безопасный handover через файл
```toml
[macros.secure_handover]
steps = [
"agent analyst analyze {{input}}",
"!echo '{{output}}' > /tmp/aichat_{{uuid}}.tmp",
"agent executor run @read_file /tmp/aichat_{{uuid}}.tmp",
"!rm /tmp/aichat_{{uuid}}.tmp"
]
```
---
<a name="макросы-rag"></a>
### 4.8 RAG в макросах
```toml
[macros.research]
steps = [
"rag search {{input}} top_k=5",
"agent researcher analyze {{output}}",
"agent answerer respond {{output}}"
]
```
> `rag search` возвращает фрагменты → `{{output}}`
---
<a name="макросы-инструменты"></a>
### 4.9 Инструменты и внешние команды
```bash
aichat tool add calc "python tools/calc.py"
```
```toml
[macros.calculate]
steps = [
"agent math solve {{input}}",
"tool calc {{output}}"
]
```
---
<a name="макросы-handover"></a>
### 4.10 Передача контекста между агентами
#### Через `{{output}}`:
```toml
steps = [
"agent A process {{input}}",
"agent B continue {{output}}"
]
```
#### Через файл (для длинного контекста):
```toml
steps = [
"agent A generate_long {{input}}",
"!echo '{{output}}' > /tmp/long.txt",
"agent B summarize @read_file /tmp/long.txt"
]
```
---
<a name="макросы-примеры"></a>
### 4.11 Примеры: от простого к сложному
#### Пример 1: Простая цепочка
```toml
[macros.translate_summary]
steps = [
"agent translator to_en {{input}}",
"agent summarizer summarize {{output}}"
]
```
#### Пример 2: Роутинг
```toml
[macros.smart_assistant]
steps = [
"agent router classify {{input}}",
"if {{output}} contains 'перевод' then agent translator to_en {{input}}",
"else if {{output}} contains 'код' then agent coder write {{input}}",
"else agent general respond {{input}}"
]
```
#### Пример 3: Код → Тест → Документация
```toml
[macros.full_dev_cycle]
steps = [
"agent coder write {{input}}",
"!echo '{{output}}' > src/feature.py",
"agent tester write_test @read_file src/feature.py",
"!echo '{{output}}' > tests/test_feature.py",
"agent doc_writer write_md {{input}}",
"!echo '{{output}}' > docs/feature.md"
]
```
#### Пример 4: Итеративный ревью
```toml
[macros.review_loop]
steps = [
"!cp draft.md /tmp/draft.md",
"repeat 3 times",
" @read_file /tmp/draft.md",
" agent reviewer critique {{output}}",
" if {{output}} contains 'хорошо' then break",
" agent writer improve {{output}}",
" !echo '{{output}}' > /tmp/draft.md",
"@read_file /tmp/draft.md"
]
```
---
<a name="макросы-best"></a>
### 4.12 Лучшие практики и безопасность
| Практика | Как |
|--------|----|
| Используй `{{uuid}}` | `!echo > /tmp/aichat_{{uuid}}.tmp` |
| Удаляй временные файлы | `!rm file` в конце |
| Используй `/tmp/aichat_*` | Автоочистка |
| Проверяй права | `chmod 600 /tmp/aichat_*` |
| Логируй | `!echo "Step: {{output}}" >> /tmp/log.txt` |
| Используй `--dry-run` | `aichat --dry-run --macro name` |
---
<a name="локальные-конфиги"></a>
## 5. Локальные конфиги по проекту
```
my-project/
├── .aichat/
│ ├── config.toml
│ ├── agents.toml
│ ├── macros.toml
│ └── rag/
└── src/
```
```bash
cd my-project
aichat # → использует .aichat/
```
---
<a name="режимы-работы"></a>
## 6. Режимы работы
| Режим | Команда |
|------|--------|
| REPL | `aichat` |
| CMD | `aichat "text"` |
| Macro | `--macro name` |
| Agent | `--agent name` |
| RAG | `rag add/search` |
| Session | `--session name` |
| Serve | `aichat serve` |
---
<a name="rag-в-проектах"></a>
## 7. RAG: векторный поиск
```bash
aichat rag add .aichat/rag/*.md --watch
```
---
<a name="примеры-проектов"></a>
## 8. Примеры проектов
- Документация
- Код-ревью
- Обучение
- API-помощник
---
<a name="шпаргалка"></a>
## 9. Шпаргалка
```bash
aichat --macro name "input"
!cmd
@read_file path
if {{output}} contains "x" then ...
repeat 3 times
...
```
---
## Скачать гайд
→ [Скачать `aichat-full-guide-expanded.md`](
https://gist.github.com/anonymous/abcdef1234567890)
→ Конвертировать в PDF: [
md-to-pdf
A web service for converting markdown to PDF
](https://md-to-pdf.fly.dev)
---
**Готово!**
Теперь у тебя **полный расширенный гайд по макросам `aichat`** — от базовых цепочек до итеративных пайплайнов с файлами и RAG.
