eva-agent/README.md

eva-agent

Агент модуля wiki хаба (sdlc-hub) для виртуалки банка с доступом к Eva. Опрашивает хаб, выгружает поддерево страниц Eva (wiki_sync, вместе с опубликованными версиями страниц для истории правок хаба) и скачивает вложения (wiki_fetch); в Eva только читает. Python 3.9, только стандартная библиотека, один файл src/agent.py и запускатель src/run.py.

Агент работает на macOS (виртуалка банка, как jira-agent): блокировка журнала — через fcntl, Windows не поддерживается.

Установка на виртуалку

1. Локальный каталог рядом с jira-agent, например ~/eva-agent/ (запускать из него, не из общей папки).
2. Положить в него agent.py и run.py (из src/) и agent.json (из agent.example.json):
   • hub_url — тот же folder:<путь>, что у jira-agent (общая папка с хабом; при VPN виртуалка не видит Mac mini по сети), либо http://<хост>:8790;
   • hub_token — строка «агент wiki» из sdlc-hub tokens (токен именно агента wiki, не jira и не клиентский);
   • eva.base_url — адрес Eva только origin: схема, хост и порт, без пути и без / в конце, например https://eva.example.ru. Агент сам добавляет к нему /api/ (JSON-RPC), /files/… (вложения) и /project/Document/<код> (ссылка на страницу); «свой» адрес вложения сравнивается с ним же, поэтому путь в base_url (https://eva.example.ru/eva) ломает и вызовы, и проверку хоста;
   • eva.token — токен из профиля Eva (Безопасность);
   • verify_ssl, ca_bundle — при корпоративном сертификате. agent.json содержит токены: не коммитить, не выносить с виртуалки.
3. Проверка: python3 agent.py check — печатает «хаб: доступен…» и «eva: ok»; код 0, при недоступности хаба или Eva — 3.
4. Запуск: python3 run.py (запускатель следит за версиями и самообновлением). python3 agent.py run — без запускателя.
5. Автозапуск — launchd, как у jira-agent, со своей меткой (см. ниже); запускатель сам перезапускает агента.

Другие команды: python3 agent.py run --once (выполнить выданное и выйти при первом пустом claim), selftest (версия + check, код 0 или 3), prune (чистка журнала).

Проверить при первой живой синхронизации: как Eva отвечает на протухший токен — перенаправлением на SSO (агент не идёт на чужой адрес и пишет «перенаправление … отклонено»), страницей входа с кодом 200 («ответ не JSON») или 401.

Автозапуск через launchd

Пример ~/Library/LaunchAgents/ru.aepif.eva-agent.plist (метка своя, не ru.aepif.jira-agent: агенты запускаются и останавливаются независимо):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>ru.aepif.eva-agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>-u</string>
        <string>/Users/USER/eva-agent/run.py</string>
    </array>
    <key>WorkingDirectory</key><string>/Users/USER/eva-agent</string>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
    <key>StandardOutPath</key><string>/Users/USER/eva-agent/agent.log</string>
    <key>StandardErrorPath</key><string>/Users/USER/eva-agent/agent.log</string>
</dict>
</plist>

Подставить свой путь вместо USER. Запуск и остановка:

launchctl load ~/Library/LaunchAgents/ru.aepif.eva-agent.plist
launchctl unload ~/Library/LaunchAgents/ru.aepif.eva-agent.plist

WorkingDirectory нужен, чтобы agent.json и journal.jsonl лежали рядом с agent.py.

Выкатка новых версий

Из основного checkout репозитория (не из worktree), при поднятой версии AGENT_VERSION в src/agent.py:

uv run --project ../sdlc-hub sdlc-hub agent publish --module wiki src/agent.py

Агент подтянет её сам (auto_update); настройку хаба wiki_min_agent_version (не min_agent_version — та у агента jira) поднимать после того, как agent_status покажет новую версию агента wiki. Для v2 (версии страниц): после выкатки хаба с change wiki-history и v2 поднять wiki_min_agent_version до 2 (Migration Plan хаба, п. 3). До этого — проверить в логе агента первой синхронизации v2 строку «N из M версий без автора»: если она есть, cmf_author у версий Eva не раскрывает, и авторы в истории будут пустыми (их не исправит повторная синхронизация).

Разработка

Настройки — src/agent.example.json. Тесты: /usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t .

Сквозной прогон с настоящим хабом и фейковой Eva: bash scripts/e2e-hub.sh (печатает «e2e: ok», ~1 мин). Хаб берётся из основного checkout sdlc-hub workspace (переменная HUB_SRC), запускается на свободном порту с временным SDLC_HUB_HOME; живой хаб не затрагивается. Проверяет: проект с wiki_root, wiki_sync на 5 страниц, Markdown со ссылкой attachment:<id>, wiki_fetch вложения и его содержимое; если тестовый хаб знает историю правок (history_at в GET /wiki/status), — ещё первую загрузку версий и догрузку новой версии DOCH-14.