# Cadence

[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Español](README.es.md) · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md)

Cadence превращает [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) в постоянное рабочее пространство задач.
Спланируйте задачу по коду, позвольте субагентам работать над ней, запустите свои проверки и просмотрите результат в терминале Pi (`/cadence`) или в веб-интерфейсе браузера; оба подключаются к одной фоновой службе.

## Почему Cadence

- **Работа живёт дольше окна.**
  Задачи выполняются в фоновой службе: закрытие терминала, выход из Pi или уход со вкладки браузера лишь отключают подключение, и любой клиент может повторно подключиться к тому же запуску.
- **Ничего не редактируется до вашего одобрения.**
  Задача сначала анализирует в режиме только для чтения и предлагает читаемый план; файлы меняются только после того, как вы подтвердите именно этот план.
- **Результатам можно доверять.**
  Вывод субагентов, фактические запуски проверок и ваш собственный обзор остаются разделёнными: текст модели или «Done» никогда не считаются пройденной проверкой, а неудачные, отменённые и неизвестные исходы остаются различимыми.
- **Полная история.**
  Каждый запуск сохраняет свои сообщения, вызовы инструментов и выводы, с точным поиском и полным экспортом в Markdown/NDJSON; известные секреты скрываются.
- **Общая история с терминалом.**
  Разговоры в браузере — это сеансы Pi проекта: продолжайте сеанс терминала в браузере или сеанс браузера через `/resume` и просматривайте ветви Pi в обоих местах.
- **Одна ссылка на всё.**
  Веб-интерфейс (десктоп и телефон, английский и упрощённый китайский) также принимает обычные разговоры Pi и переключается между проектами, у каждого из которых свой owner и своя история.

Cadence — это доверенный ассистент, **а не песочница**: его агенты редактируют вашу рабочую копию напрямую инструментами хоста, поэтому используйте его только для кода, который вы можете просмотреть и восстановить.

## Установка

Нужен Node `>=22.19.0` с npm, и установленный Pi, вошедший в учётную запись провайдера моделей; Cadence переиспользует вход и настройки моделей Pi.

```sh
npm install -g @abelxiaoxing/cadence
pi install "$(npm root -g)/@abelxiaoxing/cadence"
```

`cadence server install` регистрирует и запускает фоновую службу (systemd на Linux, LaunchAgent на macOS, элемент автозагрузки на Windows) и печатает приватную ссылку, `http://127.0.0.1:17423/?token=…`.
Последняя команда позволяет Pi загрузить ту же копию для `/cadence`, так что одно обновление npm обновляет обе.
Порт и токен хранятся в `~/.pi/agent/cadence/.env`; любой, у кого есть токен, может использовать ваше рабочее пространство, поэтому держите ссылку в секрете.

## Использование

### В браузере

1. Откройте напечатанную ссылку один раз; затем браузер запомнит вас.
   Если вы её потеряете, `cadence token-link --reveal` печатает её снова.
2. Выберите папку проекта.
   При отправке используется сохранённая модель; если её нет, выберите модель один раз.
3. Один раз отправьте `/cadence [цель]`.
   Разговор остаётся в режиме Cadence; уточняйте требования обычными сообщениями.
4. Проверьте полный план и нажмите **Implement this plan**.
   Реализация, проверки, ограниченные исправления и согласованная локальная интеграция выполняются автоматически.
5. Следите за ходом работы в разговоре; записи субагентов открываются из панели **Subagents** слева внизу.
   Обновление страницы и завершение цели не выключают режим.
   **Exit Cadence** выходит из режима; **Cancel workflow — request stop** запрашивает отмену работы.

No live Pi terminal is required for the browser conversation workflow.

### В терминале

Введите `/cadence <цель>` один раз и продолжайте обычный диалог.
Cadence исследует проект, уточняет решения и составляет план.
После явного одобрения он автоматически выполняет реализацию, проверки, ограниченные исправления и согласованную локальную интеграцию.

Режим сохраняется на весь диалог, даже после завершения цели.
Команда `exit cadence` выходит из режима, но не отменяет принятую работу.
Настройки модели сохраняются между проектами в `~/.pi/agent/cadence/settings.json`.

Локальный владелец запускается по требованию; системная служба нужна только для дополнительного WebUI и автозапуска.

`/cadence-history [run-id]`: readonly run details and retained history; no service startup or task execution.
See [History and diagnostics](docs/history.md).
[Conversation mode](docs/conversation-mode.md): native/browser approval, limits and worktree setup.
Browser authentication is not execution consent.

### Другие проекты

```sh
cadence project open /absolute/project
cadence project open /absolute/new-project --create
```

Каждый проект получает своего owner, порт и историю, и команда печатает его приватную ссылку; выборщик папок веб-интерфейса открывает проекты тем же способом.
Открытие другого проекта никогда не останавливает работу в предыдущем.

### Проверки

Команды исходных и приёмочных проверок указываются в явно одобренном плане.
Их фактические результаты отделены от автоматической проверки агентом.

## Управление службой

```sh
cadence server status
cadence server restart     # после обновления или изменения .env / models.json
cadence server upgrade     # глобальная установка npm: загрузить, установить, перезапустить
cadence server stop        # остаётся зарегистрированной и снова запускается при следующей загрузке или входе
cadence server uninstall   # выполнить перед npm uninstall -g
```

Обновляйте с помощью `cadence server upgrade` или в диалоге службы Cadence в WebUI: новая версия загружается, пока Cadence продолжает работать, а если она не запускается, возвращается предыдущая.
Restart, stop и uninstall останавливают выполняемую работу по порядку, а не оставляют её отключённой.
Uninstall удаляет только определение службы; проекты, история и настройки Pi остаются.
Корневые и именованные службы Linux, удалённый HTTPS-доступ и восстановление описаны в [управлении службой](docs/service-management.md) и [удалённом доступе](docs/remote-access.md).

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

Pi также может загрузить локальный checkout или упакованный tarball: добавьте его абсолютный или относительный путь в `packages` Pi, или попробуйте `pi -e ./cadence`.
Cadence не налагает диапазон версий Pi; фиксированные версии разработки и протестированные среды выполнения не являются универсальными обещаниями совместимости.

```sh
bun install
bun run verify
```

Инженерные указания разделены по областям в [engineering/](engineering/).
Индекс проекта в [AGENTS.md](AGENTS.md) указывает, какой файл покрывает какой код.
`verify` — единственная проверка для разработки и публикации: только быстрые проверки, без браузера.
Нужны официальная сборка Node и приватный временный каталог; см.
[проверки](engineering/verification.md).

## Лицензия

Cadence распространяется по MIT.
Включённые адаптации, шрифты и поставщики сохраняют свои собственные лицензии, обратитесь к [повторное использование и распространение](docs/reuse-and-distribution.md) и [уведомления о сторонних компонентах](THIRD_PARTY_NOTICES.md).