Andrey Epifancev 54f65d0333 docs(agent): README (доставка, запуск, launchd, prune), архитектура, проверка синтаксиса 3.9

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

2026-10-12 00:10:47 +04:00

4.5 KiB

Raw Blame History

jira-agent

Что это

Клиент моста Jira для виртуалки с доступом к Jira банка. Опрашивает хаб jira-hub (Mac mini), выполняет команды «желаемый результат» по правилу «проверь, потом сделай», ведёт журнал на диске и отдаёт хабу состояние задач. Главный сценарий: хаб ставит команду (например, создать задачу, перевести статус, перенести в спринт), агент читает задачу в Jira, записывает только разницу и возвращает результат; хаб синхронизирует зеркало через refresh. Спека: ../jira-hub/openspec/changes/bridge-core/ (specs/agent/spec.md, specs/commands/spec.md).

Стек и ограничения

Python 3.9.6 (как на виртуалке), только стандартная библиотека, без venv и зависимостей.
Запрещено: синтаксис 3.10+ (match, X | Y в аннотациях, dict | dict), сторонние импорты. Проверяет tests/test_py39.py (разбор с feature_version=(3, 9) и разрешённый список импортов).
agent.json содержит учётные данные Jira — не коммитить, не отправлять в хаб, не выносить с виртуалки. Шаблон без секретов — src/agent.example.json.

Архитектура

src/agent.py — весь агент, один файл. Разделы в порядке файла: HTTP-клиенты (Http, JiraClient, HubClient), Journal, Executor (по методу do_<тип> на каждый тип команды), Runner (цикл claim → пауза → журнал → выполнение → отчёт), CLI (cmd_check, cmd_run, main).
Границы: Executor знает Jira, но не знает хаб (кроме refresh, где хаб нужен для known_keys и state). Runner знает и хаб, и Jira, и журнал. Журнал не знает о Jira.
src/agent.example.json — шаблон настроек, README.md — эксплуатация.
Подробнее: ARCHITECTURE.md.

Команды

/usr/bin/python3 -m unittest discover -s tests -t . — весь набор тестов. Зелёным считается только весь набор.
/usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t . — то же с ошибками на незакрытые ресурсы (так проверяем перед коммитом).
/usr/bin/python3 src/agent.py check — доступность хаба и Jira, без записи в Jira.
/usr/bin/python3 src/agent.py — основной цикл (нужен agent.json рядом с agent.py).
/usr/bin/python3 src/agent.py prune — очистка журнала (не при работающем агенте).

Тесты

Тесты в tests/, запуск из корня worktree. Внешних сервисов нет: Jira и хаб заменяют фейки tests/fake_jira.py и tests/fake_hub.py.
tests/_common.py — общая настройка: путь к src, SETTINGS (как их отдаёт /agent/settings), jira_cfg(), no_sleep(). Паузы в тестах отключаются через ZERO_PACING и no_sleep.
Для каждого типа команды — свой набор: test_executor_fields.py, test_executor_links.py, test_refresh.py; цикл и восстановление — test_runner.py; журнал — test_journal.py; HTTP и 429 — test_clients.py.
Golden-фикстур пока нет: каждый тест строит сценарий в коде.

Первая подсистема

Исполнитель команд и цикл агента (спека agent/spec.md, commands/spec.md) — реализованы целиком: все типы команд, журнал, восстановление после перезапуска, CLI run|check|prune. Задача 7 плана — документация и проверка совместимости с 3.9. План и спека живут в jira-hub: openspec/changes/bridge-core/ и docs/superpowers/plans/2026-10-11-bridge-core-hub.md.

4.5 KiB Raw Blame History Unescape Escape