metaagent updated
This commit is contained in:
@@ -1,186 +1,35 @@
|
||||
# AGENTS.md — контекст для AI-сессий
|
||||
# MetaAgent
|
||||
|
||||
## Project Overview
|
||||
Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v1.1.0 —
|
||||
набор инструкций для AI-агента.
|
||||
|
||||
**CashFlow Forecast** — личная финансовая модель с прогнозом денежных потоков. Python CLI-инструмент.
|
||||
## Контекст MetaAgent
|
||||
|
||||
**Цель:** отвечать на вопрос "что произойдет дальше?" (forecast), а не "что произошло?" (accounting).
|
||||
| Ресурс | Путь |
|
||||
|--------|------|
|
||||
| Главная инструкция | `.agent/src/META_AGENT_GUIDE.md` |
|
||||
| Протоколы фаз | `.agent/src/PROTOCOLS/` |
|
||||
| Шаблоны артефактов | `.agent/src/TEMPLATES/` |
|
||||
| Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` |
|
||||
| Правила проекта | `.agent/rules/project-rules.md` |
|
||||
| Примеры работы | `.agent/src/WORKFLOW.md` |
|
||||
| Версия | `.agent/src/VERSION` |
|
||||
|
||||
**Стек:** Python 3.11+, JSON (хранение), openpyxl (Excel), typer (CLI), rich (вывод), pytest (тесты), ruff (линтер).
|
||||
## Состояние сессии (если инициализировано)
|
||||
|
||||
**Тип проекта:** greenfield, MVP реализован.
|
||||
| Артефакт | Путь |
|
||||
|----------|------|
|
||||
| Чекпоинты сессии | `.agent/checkpoints.json` |
|
||||
| Манифест задач | `.agent/task-manifest.json` |
|
||||
| Сводка для exec-агента | `.agent/handoff-summary.md` |
|
||||
| Анализ репозитория | `.agent/analysis-report.md` |
|
||||
|
||||
---
|
||||
## Для исполнительного агента
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
cf init
|
||||
cf forecast --months 12
|
||||
pytest
|
||||
ruff check .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Архитектура
|
||||
|
||||
Модульный монолит (layered):
|
||||
|
||||
```
|
||||
[CLI / Excel File]
|
||||
|
|
||||
v
|
||||
sync/ --> cashflow_model/ --> engine/ --> ai/
|
||||
(Excel R/W) (Entity Model) (Forecast) (Prompts)
|
||||
| | |
|
||||
v v v
|
||||
data/model.json data/model.json data/model.json
|
||||
```
|
||||
|
||||
**Поток данных:**
|
||||
1. Excel -> sync (импорт) -> JSON
|
||||
2. JSON -> cashflow_model (dataclass)
|
||||
3. engine (forecast) читает модель
|
||||
4. ai (assistant) анализирует результаты
|
||||
5. Результаты -> sync (экспорт) -> Excel
|
||||
|
||||
---
|
||||
|
||||
## Модули
|
||||
|
||||
| Модуль | Ответственность | Ключевые файлы |
|
||||
|---|---|---|
|
||||
| `cashflow_model/` | dataclass-сущности + JSON serialization | `model.py`, `account.py`, `transaction.py`, `recurring.py`, `asset.py`, `liability.py`, `scenario.py` |
|
||||
| `engine/` | ForecastService, ScenarioService | `forecast.py`, `scenarios.py` |
|
||||
| `sync/` | Excel <-> JSON | `excel_sync.py` |
|
||||
| `ai/` | Промпты, AssistantService (заглушка) | `prompts.py`, `assistant.py` |
|
||||
| `cli/` | Typer CLI | `main.py` |
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Account
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| name | str |
|
||||
| currency | str (default USD) |
|
||||
| balance | float |
|
||||
|
||||
### Transaction
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| date | str (ISO) |
|
||||
| account | str (UUID счёта) |
|
||||
| category | str |
|
||||
| amount | float (positive=income, negative=expense) |
|
||||
| description | str |
|
||||
|
||||
### RecurringCashflow
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| start_date | str (ISO) |
|
||||
| end_date | str (ISO, optional) |
|
||||
| frequency | str (monthly/weekly/yearly) |
|
||||
| amount | float |
|
||||
| category | str |
|
||||
|
||||
### Asset
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| name | str |
|
||||
| value | float |
|
||||
| growth_rate | float (% годовых) |
|
||||
|
||||
### Liability
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| name | str |
|
||||
| balance | float |
|
||||
| interest | float (% годовых) |
|
||||
| payment | float (ежемесячный) |
|
||||
|
||||
### ForecastScenario
|
||||
| Поле | Тип |
|
||||
|---|---|
|
||||
| id | UUID |
|
||||
| name | str (baseline/optimistic/pessimistic) |
|
||||
| income_multiplier | float |
|
||||
| expense_multiplier | float |
|
||||
| growth_multiplier | float |
|
||||
|
||||
**FinancialModel** — корневой объект, содержит списки всех сущностей. Методы: `save(path)`, `load(path)`. JSON-файл в `data/model.json`.
|
||||
|
||||
---
|
||||
|
||||
## CLI Reference
|
||||
|
||||
Команда `cf` (entry point: `cli.main:app`):
|
||||
|
||||
| Команда | Аргументы | Описание |
|
||||
|---|---|---|
|
||||
| `init` | — | Создать пустую модель |
|
||||
| `forecast` | `--months 12` | Прогноз cashflow |
|
||||
| `scenario` | `<name>` | Сценарий baseline/optimistic/pessimistic |
|
||||
| `whatif` | `--income 1.0 --expense 1.0 --growth 1.0` | What-if анализ |
|
||||
| `compare` | `--months 12` | Сравнение сценариев |
|
||||
| `import` | `<path.xlsx>` | Импорт из Excel |
|
||||
| `export` | `<path.xlsx>` | Экспорт в Excel |
|
||||
| `analyze` | `--months 12` | AI-анализ (промпт + заглушка) |
|
||||
|
||||
---
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
- Python 3.11+, dataclass для моделей
|
||||
- from_dict/to_dict для JSON-сериализации
|
||||
- ruff (E, F, I, N, W), line-length=100
|
||||
- pytest для тестов
|
||||
- typer + rich для CLI
|
||||
- f-строки, без лишних комментариев
|
||||
- Имена: snake_case, классы PascalCase
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
pytest # запуск тестов (26 tests)
|
||||
ruff check . # линтер
|
||||
ruff format . # автоформат
|
||||
cf <command> # запуск CLI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known Issues / TODOs
|
||||
|
||||
- AI-ассистент — заглушка (`ai/assistant.py`). Промпты готовы, нужно подключить API (OpenAI и т.д.)
|
||||
- Нет лицензии — требуется выбрать
|
||||
- JSON-файлы — нет конкурентного доступа
|
||||
- Excel — только .xlsx (openpyxl), нет поддержки Google Sheets
|
||||
- Нет веб-интерфейса, только CLI
|
||||
- `engine/forecast.py` — упрощённый алгоритм (без Monte Carlo)
|
||||
|
||||
---
|
||||
|
||||
## .agent/ directory
|
||||
|
||||
Директория `.agent/` содержит артефакты MetaAgent — планирование, дизайн, декомпозицию задач. **Не удалять**. Там же `checkpoints.json` с состоянием задач.
|
||||
|
||||
---
|
||||
|
||||
## Границы (Boundaries)
|
||||
|
||||
**Что НЕ входит в задачу AI-агента:**
|
||||
- Изменение архитектуры без обсуждения с пользователем
|
||||
- Подключение внешних платных API без согласования
|
||||
- Массовый рефакторинг без acceptance criteria
|
||||
- Удаление `.agent/` или `README.arch.md`
|
||||
1. **Прочитай** `.agent/src/META_AGENT_GUIDE.md` — пойми жизненный цикл MetaAgent.
|
||||
2. **Прочитай** `.agent/src/BOUNDARIES.md` — соблюдай границы.
|
||||
3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила.
|
||||
4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии.
|
||||
5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку.
|
||||
6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для
|
||||
обновления исходников MetaAgent до актуальной версии.
|
||||
|
||||
Reference in New Issue
Block a user