82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# Версионирование агентов
|
||
|
||
---
|
||
|
||
## Принцип
|
||
|
||
Каждый агент версионируется **независимо** от проекта и от других агентов по A.B.C (SemVer).
|
||
|
||
---
|
||
|
||
## Правила бампа
|
||
|
||
| Компонент | Когда | Кто |
|
||
|-----------|-------|-----|
|
||
| **A (major)** | Breaking change в публичном интерфейсе (сигнатура `run()`, публичные методы) | EvolutionAgent |
|
||
| **B (minor)** | Новая capability (новый метод, новый prompt, новая роль) | EvolutionAgent |
|
||
| **C (patch)** | Внутренние правки без изменения поведения | Сам агент (авто) |
|
||
|
||
---
|
||
|
||
## Механика
|
||
|
||
```
|
||
Каждый Agent.run()
|
||
→ compute_checksum() — SHA256 от __file__ агента
|
||
→ сравнивает с AgentConfig.checksum в БД
|
||
→ не совпал → bump_version("patch") → запись в changelog → обновление БД
|
||
→ совпал → ничего
|
||
|
||
EvolutionAgent
|
||
→ анализирует код агента
|
||
→ нашёл новую capability → bump_version("minor")
|
||
→ нашёл breaking change → bump_version("major")
|
||
```
|
||
|
||
---
|
||
|
||
## Хранение checksum
|
||
|
||
Checksum хранится в двух местах:
|
||
1. **В БД** (`AgentConfig.checksum`) — для быстрого сравнения
|
||
2. **В changelog файле** (`<!-- checksum: ... -->`) — для git history
|
||
|
||
---
|
||
|
||
## Changelog
|
||
|
||
Файл: `CHANGELOG/agents/<agent_name>.md`
|
||
|
||
```markdown
|
||
# audit_agent Changelog
|
||
<!-- checksum: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 -->
|
||
|
||
## 1.0.2 (2026-05-10)
|
||
- Fixed: ruff output parsing for Windows paths
|
||
|
||
## 1.0.1 (2026-05-09)
|
||
- Fixed: missing error handling in health_check
|
||
|
||
## 1.0.0 (2026-05-08)
|
||
- Initial version
|
||
```
|
||
|
||
---
|
||
|
||
## Разделение ответственности
|
||
|
||
| Аспект | Владелец | Где хранится |
|
||
|--------|----------|--------------|
|
||
| Версия проекта | SpecAgent / человек | `project.yaml`, `CHANGELOG/v*.md` |
|
||
| Версия агента | EvolutionAgent | `AgentConfig.version` (БД) |
|
||
| Changelog проекта | SpecAgent / человек | `CHANGELOG/v*.md` |
|
||
| Changelog агента | EvolutionAgent | `CHANGELOG/agents/<name>.md` |
|
||
|
||
---
|
||
|
||
## [ASK] Вопросы по версионированию
|
||
|
||
- Версионировать агентов с первого коммита? (да — привычка, потом не внедрить)
|
||
- Допустим ли ручной бамп версии? (да, EvolutionAgent — автоматизация, но человек может и вручную)
|
||
- Нужна ли блокировка бампа (если checksum не совпал — не запускать)? (нет, только предупреждение)
|