aep/jira-agent
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity
jira-agent/ARCHITECTURE.md
Andrey Epifancev 4eaad42d15 docs(agent): fix round 1 — OpenSpec-раздел в CLAUDE.md, README (префикс лога, timeout/poll, 429), оговорка проверки 3.9 
- CLAUDE.md: восстановлен раздел «OpenSpec и superpowers» из шаблона; убрана фраза про задачу 7;
  тесты описаны по областям; оговорка про проверку 3.9 (ast не ловит API, только прогон на 3.9.6).
- README: пример вывода check с префиксом времени; timeout и poll_seconds в доставке;
  429/503 — не более 4 ожиданий, Retry-After в HTTP-date не разбирается.
- ARCHITECTURE.md: формулировка повторов 429/503.
- tests/test_py39.py: комментарий с ограничением проверки.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Typ5sXWNMFirr2va2uL8o
2026-10-12 00:15:08 +04:00

3.8 KiB
Raw Blame History

Архитектура

Агент — один файл 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 запросов, не более 4 ожиданий), хранит время последнего вызова 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).