54f65d0333
README: доставка на виртуалку, check/запуск/launchd, журнал и prune, поведение с командами, известные ограничения (prune при работе агента, Ctrl-C во время паузы, https без CA, спринты закрытых спринтов, refresh, сравнение описания, 429/503 без потолка). CLAUDE.md и ARCHITECTURE.md заполнены по src/agent.py. tests/test_py39.py: разбор с feature_version=(3, 9) и разрешённый список импортов (только stdlib). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Typ5sXWNMFirr2va2uL8o
33 lines
3.7 KiB
Markdown
33 lines
3.7 KiB
Markdown
# Архитектура
|
||
|
||
Агент — один файл `src/agent.py` (Python 3.9, только стандартная библиотека). Тесты в `tests/` работают на фейках
|
||
Jira и хаба. Спека: `../jira-hub/openspec/changes/bridge-core/`, план: `../jira-hub/docs/superpowers/plans/2026-10-11-bridge-core-hub.md`.
|
||
|
||
## Разделы файла `src/agent.py`
|
||
|
||
| Раздел | Классы и функции | Ответственность | Что использует |
|
||
|---|---|---|---|
|
||
| Настройки | `load_config` | читает `agent.json`, проверяет обязательные поля | — |
|
||
| HTTP | `Http`, `HttpError`, `JiraClient`, `HubClient` | запросы; `JiraClient` считает вызовы, повторяет 429/503 по `Retry-After` (до 5 попыток), хранит время последнего вызова | `urllib` |
|
||
| Журнал | `Journal`, `_parse_at` | дозапись `journal.jsonl`: `started` → `finished` → `acked`; восстановление; `prune` | файловая система |
|
||
| Исполнитель | `Executor` и `do_<тип>` | по одному методу на тип команды: читает Jira, пишет только разницу; `refresh` читает и отправляет состояние в хаб | `JiraClient`, `HubClient` (только `refresh`), настройки хаба |
|
||
| Цикл | `Runner` | claim, пауза до команды, журнал, выполнение, отчёт до подтверждения, восстановление при старте | `HubClient`, `JiraClient`, `Journal`, `Executor` |
|
||
| CLI | `cmd_run`, `cmd_check`, `main` | команды `run`, `check`, `prune`; обработка сигналов | `Runner`, `Journal` |
|
||
|
||
## Границы
|
||
- Пароль и токен Jira — только в `agent.json`. В хаб, журнал и логи не попадают.
|
||
- Политика темпа не хранится в агенте: зазоры (`pacing`) и `pause_seconds` приходят от хаба. Агент досыпает паузу
|
||
до зазора от последнего вызова Jira (`JiraClient.last_call_at`).
|
||
- Одна команда в полёте: цикл берёт следующую только после выполнения и подтверждения отчёта.
|
||
- Отчёт до подтверждения: `send_result` повторяет каждые 10 с; 404/409/422 от хаба считаются закрытием.
|
||
- Журнал пишется трижды на команду вокруг выполнения: `started` — после паузы, перед первым обращением к Jira;
|
||
`finished` — после результата; `acked` — после подтверждения хаба. Восстановление опирается только на этот порядок.
|
||
- Каждый обработчик `Executor` возвращает `status`/`result`/`error` и счётчики. Исключение, которое не обработано
|
||
в обработчике, `Runner.execute` превращает в `failed` и не роняет цикл.
|
||
- Тесты не ходят во внешние сервисы; фейки — `tests/fake_jira.py` и `tests/fake_hub.py`.
|
||
|
||
## Открытые вопросы
|
||
- HTTPS хаба с корпоративным CA: `HubClient` не принимает `ca_bundle`/`verify_ssl` (ограничение README, пункт 3).
|
||
- Защита `prune` от параллельной записи: блокировки нет (ограничение README, пункт 1).
|
||
- Спринт задач закрытых спринтов: `sprint = null` (рулинг R-6).
|