cf7c7bde8c
- CLAUDE.md: `jira-hub agent publish --module wiki src/agent.py`, порог `wiki_min_agent_version`. - README: `wiki_min_agent_version` вместо `min_agent_version`; `eva.base_url` — только origin; агент только для macOS (fcntl), пример launchd `ru.aepif.eva-agent`; строка про проверку SSO на первой живой синхронизации (M-5). - ARCHITECTURE: строки Eva и Executor по реализованному, строки ссылок (`_LinkParser`, `classify_links`) и дерева (`build_children`, `walk`). - design.md: решения 36–43, в том числе почему M-5 отложен до живой проверки. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
85 lines
6.0 KiB
Markdown
85 lines
6.0 KiB
Markdown
# 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» из `jira-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
|
||
<?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 ../jira-hub jira-hub agent publish --module wiki src/agent.py
|
||
|
||
Агент подтянет её сам (`auto_update`); настройку хаба `wiki_min_agent_version` (не `min_agent_version` — та у агента
|
||
jira) поднимать после того, как `agent_status` покажет новую версию агента wiki.
|
||
|
||
## Разработка
|
||
|
||
Настройки — `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 мин). Хаб берётся из
|
||
`../../../jira-hub/.wt/wiki` (переменная `HUB_SRC`), запускается на свободном порту с временным `JIRA_HUB_HOME`;
|
||
живой хаб не затрагивается. Проверяет: проект с `wiki_root`, `wiki_sync` на 5 страниц, Markdown со ссылкой
|
||
`attachment:<id>`, `wiki_fetch` вложения и его содержимое.
|