Установка

Это руководство объясняет поддерживаемый путь локальной установки и почему ThreadCells устанавливается из проверенного кандидата. Если вам нужны только команды, используйте Быструю настройку.

Поддерживаемая базовая конфигурация

Текущая техническая предварительная версия поддерживает один хост Ubuntu/Debian Linux. ThreadCells ожидает доверенную учётную запись оператора и локальную копию Git. Другие дистрибутивы Linux могут работать, но не входят в поддерживаемую базовую конфигурацию; macOS и Windows могут удалённо открывать веб-интерфейс, но не поддерживаются как хосты ThreadCells.

Предварительные требования

Установите или проверьте:

• Python 3 и поддержку venv;
• Git;
• tmux;
• Node.js и npm для сборки упакованного веб-интерфейса;
• стандартные POSIX-утилиты, используемые скриптами релиза и службы;
• CLI хотя бы одного поддерживаемого провайдера, установленный и аутентифицированный для учётной записи, которая будет запускать ThreadCells.

Проверьте важные команды:

python3 --version
git --version
tmux -V
node --version
npm --version

ThreadCells может регистрировать адаптеры, CLI которых отсутствуют. Это не ошибка установки: готовы должны быть только провайдеры, которых вы собираетесь запускать. См. Провайдеры.

Где хранится состояние

По умолчанию операционное состояние находится в:

~/.aws/cli-agent-orchestrator/

Историческое имя каталога сохранено для совместимости. В нём могут храниться база данных SQLite, логи, управляемые worktree, контекст агентов, вложения, артефакты провайдеров и другие данные среды исполнения. Установите CAO_HOME_DIR до первого запуска, чтобы выбрать другое абсолютное расположение.

Установленное приложение и его состояние среды исполнения различаются:

• candidate/install содержит версионированный код и статические ресурсы веб-интерфейса;
• state root содержит базу данных, изменяемые данные оператора и необязательные секретные файлы с ограниченным доступом под управлением ThreadCells, например токен Telegram-бота;
• CLI провайдеров могут хранить собственные учётные данные и историю rollout в других местах.

Создайте резервную копию изменяемого состояния до замены установки. Никогда не коммитьте состояние среды исполнения или учётные данные провайдера.

Зачем нужен локальный кандидат?

Кандидат — это каталог в форме релиза, собранный из одной точной ревизии исходного кода. Его манифест и контрольные суммы позволяют проверить, что именно будет запущено, до изменения установки. Затем staging и promotion могут сохранить прежний кандидат для rollback.

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

Соберите кандидат

Из корня репозитория:

python3 scripts/build_local_candidate.py --output "$PWD/threadcells-candidate"
candidate="$PWD/threadcells-candidate/threadcells-0.3.4a0-local"
python3 scripts/verify_local_candidate.py --candidate "$candidate"

Ожидаемый результат: проверяющая программа принимает манифест, контрольные суммы, упакованную документацию и файлы приложения. Не устанавливайте кандидат, не прошедший проверку.

Просмотр и установка

Выберите абсолютный префикс установки, к которому у учётной записи среды исполнения есть доступ на выполнение. Приведённый ниже префикс внутри репозитория удобен для оценки:

"$candidate/scripts/install-threadcells.sh" --source "$candidate" --dry-run
"$candidate/scripts/install-threadcells.sh" --source "$candidate" --prefix "$PWD/.threadcells"

Предварительный запуск намеренно выполняется первым. Проверьте источник и цель, затем выполните реальную установку.

Проверьте установленный CLI

"$PWD/.threadcells/venv/bin/threadcells" info
"$PWD/.threadcells/venv/bin/threadcells" doctor
"$PWD/.threadcells/venv/bin/threadcells" providers list

doctor работает только на чтение. Устраните отсутствие обязательных системных утилит. Вывод провайдера должен отличать известный адаптер от установленного и пригодного к работе CLI.

Запустите локально

"$PWD/.threadcells/venv/bin/threadcells-server" --host 127.0.0.1 --port 9889

В другой оболочке:

curl -fsS http://127.0.0.1:9889/health

Откройте http://127.0.0.1:9889. Проверьте Settings → About и убедитесь, что версия и ревизия соответствуют проверенному кандидату.

Для постоянной установки используйте канонический механизм службы/deployment из репозитория, описанный в Развёртывании. Не придумывайте публичный адрес привязки.

Первые сбои

• python3 -m venv fails: установите пакет Python venv вашего дистрибутива.
• tmux is missing: установите его перед запуском агентов; от него зависит сохранность терминалов.
• Web assets fail to build: используйте поддерживаемую базовую версию Node/npm, установите зафиксированные зависимости и пересоберите кандидат.
• Провайдер сообщает, что CLI не установлен: установите каноническую команду этого провайдера для пользователя среды исполнения или выберите уже готовый провайдер.
• Провайдер установлен, но не аутентифицирован: завершите процедуру входа провайдера от имени пользователя среды исполнения, затем повторите предварительную проверку.
• Port 9889 is busy: остановите конфликтующий локальный процесс либо выберите другой порт loopback и используйте его везде одинаково.
• Browser on another machine cannot connect: это ожидаемо, когда listener доступен только через loopback. Используйте Удалённый доступ.

Границы удаления

Удаление префикса установки не удаляет безопасно операционное состояние, учётные данные провайдеров, Git-репозитории, Git worktree, резервные копии или определения служб. Остановите ThreadCells, создайте проверенную резервную копию и отдельно определите каждую из этих категорий. Используйте раздел «Обслуживание» для подходящих артефактов среды исполнения; не удаляйте корень состояния рекурсивно как упрощённый способ деинсталляции.

Далее пройдите Ваш первый проект и агент.