67 lines
7.0 KiB
Markdown
67 lines
7.0 KiB
Markdown
## Why
|
||
|
||
Мост работает в ежедневном режиме с 13.10.2026 (агент на виртуалке за VPN «Континент», обмен через общую папку UTM).
|
||
Отложенные находки `bridge-core` (#1) и `folder-transport` (#5) содержат несколько мест, где живая работа может привести
|
||
к дублю задачи в Jira, к команде, зависшей в `claimed` без пути восстановления, или к лишним запросам к Jira банка:
|
||
|
||
- **M-2** — ответ на `claim` потерян (сбой папки, перезапуск агента во время долгого запроса): команда навсегда `claimed`,
|
||
в журнале агента её нет; очередь стоит 10 минут, затем команда требует force-cancel или повтора.
|
||
- **R-11 / O-9** — потерянный отчёт `ensure_issue` не закрывается подтверждением по состоянию (хаб не знает логин Jira
|
||
агента); каждый такой случай требует ручного действия.
|
||
- **M-5** — поздний отчёт по force-отменённой `ensure_issue` теряет ключ созданной задачи.
|
||
- **M-11** — отчёт по команде в `queued` принимается; две `ensure_issue` с одной темой в пакете дают одну задачу на два
|
||
временных ключа.
|
||
- **O-3** — связь симметричного типа («Связанные»), стоящая в Jira в обратную сторону, попадает в `missing_links` отчёта
|
||
импорта (13.10.2026 — 3 ложные тревоги).
|
||
- **M-9 / O-2** — после перезапуска агент забывает время последнего вызова Jira и сразу выполняет команду без паузы темпа;
|
||
при восстановлении по журналу пауза обнуляется явно.
|
||
- **FM-4** — восстановление по журналу повторно пишет `claimed`.
|
||
- Расхождение со спекой: `agent_status` отдаёт признак `online`, спека говорит `offline`.
|
||
|
||
Решения владельца 13.10.2026 (сессия brainstorming):
|
||
- пакет A follow-ups — первым;
|
||
- M-2, вариант A: хаб довыдаёт команду, выданную агенту и оставшуюся без отчёта (принцип «хаб не повторяет команды»
|
||
уточняется: новых команд хаб не создаёт, довыдача неподтверждённой выдачи — доставка, не повтор);
|
||
- после написания спеки, при планировании: довыдача закрывает и сценарий R-11 (потерянная `ensure_issue` выдаётся снова,
|
||
агент находит свою задачу по `reporter = currentUser()`), а подтверждение по состоянию при довыдаче почти недостижимо
|
||
(`refresh` не выдаётся, пока есть `claimed`). Поэтому передача логина агента и симметричных типов связей в `claim`
|
||
из change убрана; R-11 закрывается довыдачей; O-3 — отдельным списком связей «в обратную сторону» в отчёте импорта.
|
||
|
||
## What Changes
|
||
|
||
- **jira-hub**:
|
||
- повторная выдача: `claim` при наличии команды в `claimed` выдаёт её снова (самую старую), счётчик `deliveries`;
|
||
после 3 выдач без отчёта — `failed` «агент не отчитался после 3 выдач»; логика «свежей claimed» (10 минут простоя) и
|
||
обход пакета с зависшим определителем (R-13) удаляются;
|
||
- миграция схемы v1 → v2 (`command.deliveries`) с копией базы перед ней — первая миграция живой базы;
|
||
- отчёт по `queued` — 409; пакет с двумя `ensure_issue` одной темы — 422;
|
||
- поздний отчёт по отменённой `ensure_issue` с ключом сохраняет результат и переносит заметку `new:N` → ключ, статус
|
||
остаётся `cancelled`;
|
||
- отчёт импорта: связи из `links.csv`, которые в зеркале есть того же типа в обратную сторону, — в `reversed_links`,
|
||
а не в `missing_links`;
|
||
- заготовка настройки `reporter` удаляется; `agent_status` — `redelivered` вместо `stuck`; MCP показывает довыданные
|
||
команды; принцип повторов уточняется в `CLAUDE.md`, `ARCHITECTURE.md`, docstring `queue`.
|
||
- **jira-agent** (версия 3):
|
||
- время последнего вызова Jira восстанавливается при старте из журнала; при восстановлении пауза команды не обнуляется;
|
||
- при восстановлении `claimed` повторно не пишется.
|
||
- Спеки: `hub-api`, `data-model`, `commands`, `agent`, `mcp`, `migration` — MODIFIED; признак `online` закрепляется в
|
||
спеке вместо `offline`.
|
||
|
||
## Non-goals
|
||
|
||
- Передача логина Jira агента и симметричных типов связей в хаб (см. Why).
|
||
- Остальные находки follow-ups (`T-n`, `M-n` вне перечня, расхождения второго порядка) — пакеты C и D.
|
||
- Проверки поведения на реальной Jira банка (CRLF, Epic Link, постраничность комментариев, поле спринта) — пакет B.
|
||
- Подъём `min_agent_version` до 3: агент v2 продолжает работать.
|
||
- Дубли `ensure_issue` между разными пакетами: поиск дубля по теме за 7 дней уже сводит их к одной задаче.
|
||
|
||
## Impact
|
||
|
||
- `jira-hub`: `queue.py` (claim, report_result, agent_view, maybe_auto_refresh, reconcile), `commands.py` (validate,
|
||
check_confirmed), `importer.py`, `db.py` (миграция v2), `api.py` (409 на отчёт по queued), `mcp_server.py`;
|
||
`CLAUDE.md`, `ARCHITECTURE.md`.
|
||
- `jira-agent`: `src/agent.py` (Runner, recover, execute), `README.md`, версия 3.
|
||
- Контракт хаб ↔ агент: тела запросов не меняются; новый ответ 409 на отчёт по `queued` (агент уже трактует 409 как
|
||
«закрыто»).
|
||
- Issues: aep/jira-hub#9, aep/jira-agent#9.
|