# Catui

![Catui — Ваш терминал. Ваш напарник по коду.](assets/readme/header.png)

Кодинг-агент для терминала с постоянной проектной памятью, переключаемыми персонами и расширяемыми инструментами. Написан на TypeScript и Node.js; публикуется как `catui-agent`.

[English](README.md) · [中文](README_CN.md) · [日本語](README_JA.md) · [SDK](docs/sdk.md)

## Начало работы

Требуется Node.js 20 или новее.

```bash
npm install -g catui-agent
catui
```

Провайдер настраивается через `/login`, модель — через `/model`, идентичность — через `/persona`. Учётные данные провайдера можно также передавать через переменные окружения (см. раздел «Настройка провайдера» ниже). Доступность моделей зависит от настроенного провайдера и аккаунта. Поддерживаются Anthropic, OpenAI, Google, Alibaba DashScope / Token Plan и локальный Ollama.

```bash
catui -c                                # Продолжить предыдущую сессию
catui -r                                # Выбрать сессию из истории
catui -p "Объясни этот репозиторий"    # Однократный запуск и выход
catui --mode rpc                        # Интеграция через stdio JSON-lines
catui --acp                             # Интеграция с редактором через ACP
catui --serve --host 127.0.0.1          # Удалённое управление по HTTP / WebSocket
catui --help                            # Все параметры CLI
```

Терминальный UI — основной интерфейс. В репозитории также есть удалённый сервер и отдельный мобильный web/Capacitor клиент; см. [удалённый режим](docs/remote.md). Корневая сборка не собирает мобильное приложение.

## Что входит в поставку

### Подключение Codex к текущей сессии

На macOS / Linux в Catui введите `/bridge start` и подтвердите установку плагина при первом использовании. Откройте новый чат в Codex и попросите его подключиться к вашей сессии Catui. Копировать пути расширений, ключи или номера портов не нужно. Состояние подключения — `/bridge status`, повтор установки — `/bridge setup`, отключение — `/bridge stop`. Требуется Codex с поддержкой плагинов. Codex может обнаружить актуальный каталог команд, направлять обычную работу, Grub и Goal, ревьюить Plan и отвечать на делегированные вопросы. Команды без удалённого адаптера и подтверждение повышенных прав остаются локальными. Catui исполняет, Codex проверяет получившееся состояние и доказательства до того, как принять завершение.
См. [руководство по подключению](extensions/optional/session-bridge/README.md).

### Возможности

- **Инструменты и сессии**: просмотр / правка файлов, выполнение команд shell, переключение моделей, потоковые ответы, история сессий, ветвление, уплотнение контекста и экспорт в HTML.
- **Память и персоны**: NanoMem хранит проектные знания и предпочтения; файлы персон задают идентичность и стиль работы. **NanoSoul приостановлен**: автоматическая инициализация, инъекция личности и обучение не выполняются. Существующие данные Soul не трогаются. Старые опции Soul в SDK игнорируются.
- **Расширяемость**: встроенные и пользовательские расширения регистрируют инструменты, команды и хуки жизненного цикла. MCP подключает внешние серверы инструментов; Browser Harness — opt-in.
- **Рабочие процессы**: инженерные навыки дисциплины, планирование, субагенты / команды, `/goal`, `/grub`, `/loop`, навыки исследования и письма. Список загруженных ресурсов — `/resources` (зависит от режима и конфигурации).
- **Управление во время выполнения**: политики инструментов, ограниченное восстановление, трассы выполнения и инструменты воспроизведения / оценки. См. [трассы выполнения](docs/run-trace-and-replay.md).

## Встроенные навыки принятия решений

Расширение `typesafe` по умолчанию содержит два навыка:

| Навык | Назначение |
| --- | --- |
| `agent-decision-loop` | Выбирать полезное следующее действие, опирать аргументы инструментов на доказательства, оценивать результаты и менять подход, когда прогресс останавливается |
| `typesafe-ai` | Собирать интеграции с TypeSafe System One на основе типизированных суждений и актуальной upstream-документации |

В конце каждого пользовательского хода добавляется короткое руководство по принятию решений / инструментам / оценке. Полные тела навыков подгружаются по требованию через Skill-инструмент или `/skill:agent-decision-loop` и `/skill:typesafe-ai`. Работает во всех режимах CLI и в headless-SDK.

Обычная работа Catui использует настроенную модель и существующие инструменты: аккаунт TypeSafe не требуется и вызовы TypeSafe API не добавляются. Для построения реальной интеграции с TypeSafe нужны учётные данные этого сервиса. Руководство навыка не является гарантией корректности во время выполнения и не измеряет снижение ошибок модели.

Upstream-навык взят из [typesafe-ai/skills](https://github.com/typesafe-ai/skills) на фиксированной ревизии с его MIT-лицензией; см. [provenance](extensions/builtin/typesafe/AGENT.md). Флаг `--no-extensions` отключает поиск в директориях. CLI подаёт встроенные расширения явно, поэтому они остаются загруженными — как и пути, явно указанные через `-e`.

## Конфигурация и хранение

По умолчанию конфигурация агента хранится в `~/.catui/agents/<id>/` (ID `default`):

| Файл / директория | Назначение |
| --- | --- |
| `auth.json` | Учётные данные провайдера |
| `models.json` | Пользовательские определения моделей |
| `settings.json` | Настройки и флаги функций |
| `sessions/` | Сохранённые диалоги |
| `extensions/` | Пользовательские расширения |

`--agent <id>` выбирает агента; `CATUI_CODING_AGENT_DIR` переопределяет корень конфигурации. Инлайн-настройка — `/model` и `/persona`; программное встраивание описано в `docs/sdk.md`.

Локальное хранение не означает полностью офлайн-работы: настроенные провайдеры, MCP-серверы и включённые внешние интеграции могут выполнять сетевые запросы.

## Разработка

```bash
npm ci
npm run build
npx tsx cli.ts
```

В репозитории используются npm workspaces для трёх приватных рантайм-библиотек и опубликованных protocol / memory интеграций. У `apps/mobile` собственный тулчейн. `packages/soul-core` хранится как приостановленный автономный исходник, вне корневого workspace и сборки приложения.

| Расположение | Ответственность |
| --- | --- |
| `cli.ts`, `main.ts` | Запуск CLI и выбор режима |
| `core/runtime/` | Общий фасад сессии и выделенные владельцы рантайма |
| `core/lib/{ai,agent-core,tui}/` | Приватные библиотеки моделей / цикла исполнения / терминала |
| `core/platform/` | Примитивы конфигурации, процессов и утилит |
| `modes/` | Интерактивный, print, RPC, ACP и удалённый интерфейсы |
| `extensions/` | Базовые и опциональные возможности продукта |
| `packages/{protocol,mem-core}/` | Опубликованные интеграции protocol и memory |
| `test/`, `tests/` | Регрессионные и характеризационные тесты |
| `.dev-docs/`, `llm-wiki/` | Архитектурные решения и автогенерируемая навигация по коду |

`AgentSession` сохраняет публичный фасад. У изменений моделей, жизненного цикла, уплотнения, очередей, порядка событий, сохранения трасс, статистики и поиска ресурсов есть именованные владельцы; начните с [карты рантайма](core/runtime/AGENT.md).

Перед изменением поведения следуйте [AGENTS.md](AGENTS.md) и [feature workflow](.dev-docs/feature-workflow.md). Обязательные проверки:

```bash
npm run verify:dip
npm run verify:quality
npm run verify:package-boundary
npm run build
npx tsc --noEmit
npm test
```

Фокусные скрипты перечислены в `package.json`. Дополнительные интеграционные проверки могут требовать учётных данных провайдера и дополнительных сервисов. Сборка и публикация — разные процессы; перед релизом см. [CONTRIBUTING.md](CONTRIBUTING.md).

## Лицензия

[GPL-3.0](LICENSE). Заимствованные компоненты сохраняют свои лицензионные уведомления.