diff --git a/.agent/analysis-report.md b/.agent/analysis-report.md index 539b5da..fb93f1d 100644 --- a/.agent/analysis-report.md +++ b/.agent/analysis-report.md @@ -4,72 +4,75 @@ - **Session ID:** `metaagent-002` - **Target repo:** `S:\Git\nifodea` -- **Date:** 2026-07-12 +- **Date:** 2026-07-22 - **Project type:** `existing` ## 1. Общая информация -- **README:** CashFlow Forecast — личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом -- **Лицензия:** не указана +- **README:** Личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом. Python + JSON + Excel + AI. +- **Лицензия:** не выбрана - **CI/CD:** отсутствует -- **Точка входа:** `cli/main.py:app` (команда `cf`) +- **Точка входа:** `cli/main.py` (команда `cf`) - **Система сборки:** `pyproject.toml` (setuptools) ## 2. Стек технологий | Компонент | Значение | |---|---| -| Язык | Python 3.11+ (фактически 3.13) | -| Фреймворк | Typer (CLI), openpyxl (Excel) | +| Язык | Python >= 3.11 | +| Фреймворк | Typer (CLI) | | База данных | JSON-файлы | | Тестовый раннер | pytest | -| Пакетный менеджер | pip + venv | -| Линтер | ruff | +| Пакетный менеджер | pip (setuptools) | +| Линтер/форматтер | ruff | ## 3. Архитектура -**Паттерн:** Модульный монолит (Layered) - ``` -cli/ → sync/ ⇒ cashflow_model/ ⇔ engine/ → ai/ - (Excel) (Entity Model) (Forecast) (Prompts) +cashflow_model/ # Модели данных (dataclass + JSON) +engine/ # Вычислительное ядро (forecast + scenarios) +sync/ # Excel import/export +ai/ # AI-ассистент (заглушка) +cli/ # CLI (Typer) +tests/ # pytest +data/ # JSON-модели +exports/ # Экспортированные .xlsx ``` -**Модули:** -- `cashflow_model/` — сущности dataclass + JSON сериализация (Account, Transaction, RecurringCashflow, Asset, Liability, ForecastScenario, FinancialModel) -- `engine/` — ForecastService (прогноз), ScenarioService (сценарии + what-if) -- `sync/` — ExcelSync (импорт/экспорт .xlsx через openpyxl) -- `ai/` — AssistantService (промпты, заглушка), PromptsTemplate -- `cli/` — Typer CLI (init, forecast, scenario, whatif, compare, import, export, analyze) -- `tests/` — pytest тесты (26 tests) +**Паттерн:** Модульный монолит -**Внешние зависимости:** openpyxl, typer, rich +**Ключевые модули:** -## 4. Конвенции кода +| Модуль | Описание | +|---|---| +| cashflow_model | Модели данных: Account, Transaction, RecurringCashflow, Asset, Liability, ForecastScenario, FinancialModel | +| engine | Вычислительное ядро: ForecastService (прогноз), ScenarioService (сценарии + what-if) | +| sync | ExcelSync — импорт/экспорт .xlsx | +| ai | AssistantService — генерация промптов (заглушка) | +| cli | Typer CLI — 8 команд | -- **Стиль:** ruff (E, F, I, N, W), line-length=100 -- **Именование:** snake_case для функций/переменных, PascalCase для классов -- **Типизация:** аннотации типов -- **Обработка ошибок:** кастомные исключения (ModelError, SyncError, ForecastError) +## 4. Конвенции + +- **Стиль:** snake_case для функций/переменных, PascalCase для классов +- **Импорты:** стандартные, сгруппированные +- **Типизация:** используется (dataclass, type hints) +- **Обработка ошибок:** через исключения - **Логирование:** не используется ## 5. Тесты -- **Типы:** unit-тесты -- **Расположение:** `tests/` -- **Запуск:** `pytest` -- **Текущее состояние:** 26/26 passed (100%) -- **Покрытие:** не измеряется +- **Команда запуска:** `pytest` +- **Всего тестов:** 26 +- **Пройдено:** 26 +- **Упало:** 0 +- **Пропущено:** 0 ## 6. Базовая проверка -- **Сборка:** pip install -e . — success -- **Импорты:** все модули импортируются без ошибок -- **Линтер:** ruff check — All checks passed -- **Git status:** clean +- **Сборка:** OK (pip install -e .) +- **Линтер:** OK (ruff check . — all checks passed) +- **Git status:** есть незакоммиченные изменения (checkpoints.json, metaagent-request.md, AGENTS.md, data/model.json, .agent/rules/) -## 7. Примечания +## 8. Примечания -- Проект полностью реализован (MVP) -- AI-ассистент — заглушка, промпты готовы -- Лицензия не выбрана — требуется решение +Проект полностью функционален: 26 тестов проходят, линтер чист. Требуется только обновление MetaAgent-артефактов до v1.1.0. diff --git a/.agent/checkpoints.json b/.agent/checkpoints.json index 6d53035..c1ca7ff 100644 --- a/.agent/checkpoints.json +++ b/.agent/checkpoints.json @@ -1,5 +1,5 @@ { - "metaagent_version": "1.0.0", + "metaagent_version": "1.1.0", "session_id": "metaagent-002", "target_repo": "S:\\Git\\nifodea", "goal": "Обновление metaagent-артефактов до v1.0.0, валидация существующего кода и окружения", @@ -30,5 +30,5 @@ { "id": "T7", "title": "AI Assistant", "status": "completed", "depends_on": ["T3"], "acceptance_criteria": ["промпты с моделью и прогнозом", "заглушка ответа"] }, { "id": "T8", "title": "Тесты", "status": "completed", "depends_on": ["T2","T3","T4","T5","T6","T7"], "acceptance_criteria": ["pytest проходит", "покрытие всех модулей"] } ], - "last_updated": "2026-07-12T20:15:00Z" + "last_updated": "2026-07-22T12:00:00Z" } diff --git a/.agent/handoff-summary.md b/.agent/handoff-summary.md index 1edf015..1ac4387 100644 --- a/.agent/handoff-summary.md +++ b/.agent/handoff-summary.md @@ -4,66 +4,104 @@ - **Session ID:** `metaagent-002` - **Target Repo:** `S:\Git\nifodea` -- **Goal:** Обновление metaagent-артефактов до v1.0.0, валидация существующего кода и окружения -- **Date:** 2026-07-12 -- **Duration:** ~1 session - -## Configuration - +- **Goal:** Обновление metaagent-артефактов до v1.1.0, валидация существующего кода и окружения +- **Date:** 2026-07-22 - **Depth:** 4 (Light) -- **Design:** adr=no, alternative_arch=no -- **Red Team:** no -- **Risk Register:** no -- **Invariant Tests:** no -- **Layer Structure:** no +- **Config:** depth=4, design=skipped (existing), red_team=no, risk_register=no, invariant_tests=no, layer_structure=no ## Repo Summary -CashFlow Forecast — личная финансовая модель с прогнозом денежных потоков. Python 3.11+, JSON, Excel (openpyxl), CLI (Typer), AI-интерфейс (заглушка). MVP полностью реализован. +CashFlow Forecast — личная финансовая модель на Python. Модульный монолит: cashflow_model (dataclass), engine (forecast + scenarios), sync (Excel), ai (заглушка), cli (Typer). 26 тестов, ruff lint чист. + +## Project Type + +- **Type:** existing +- **Design report:** — ## Environment Status -- **Build:** OK (pip install -e . — success) -- **Lint:** ruff — All checks passed -- **Tests:** 26/26 passed (0.63s) -- **Git status:** clean - -## Design Summary - -- **Pattern:** Модульный монолит (Layered) -- **Modules:** cashflow_model, engine, sync, ai, cli -- **Entry point:** `cf` (cli.main:app) +- **Build:** OK +- **Tests:** 26/26 passed +- **Linter:** ruff — all checks passed +- **Dependencies:** установлены (openpyxl, typer, rich) ## Task Overview | Status | Count | |---|---| | Total | 8 | -| Completed | 8 | | Pending | 0 | +| In Progress | 0 | +| Completed | 8 | +| Failed/Skipped | 0 | -**Tasks by type:** -- config: 1 (completed) -- feature: 6 (completed) -- test: 1 (completed) +**Task by type:** +- config: 1 +- feature: 6 +- test: 1 + +## Tasks (ordered) + +### T1: Инициализация проекта и зависимостей +- Type: config +- Depends on: — +- Files: pyproject.toml, cashflow_model/__init__.py, sync/__init__.py, engine/__init__.py, ai/__init__.py, cli/__init__.py, data/.gitkeep, exports/.gitkeep +- Status: completed + +### T2: Модель данных (dataclass + JSON serialization) +- Type: feature +- Depends on: T1 +- Files: cashflow_model/__init__.py, cashflow_model/account.py, cashflow_model/transaction.py, cashflow_model/recurring.py, cashflow_model/asset.py, cashflow_model/liability.py, cashflow_model/scenario.py, cashflow_model/model.py +- Status: completed + +### T3: Forecast Engine (базовый прогноз) +- Type: feature +- Depends on: T2 +- Files: engine/__init__.py, engine/forecast.py +- Status: completed + +### T4: Scenario Analysis +- Type: feature +- Depends on: T3 +- Files: engine/__init__.py, engine/scenarios.py +- Status: completed + +### T5: Excel Sync (import/export) +- Type: feature +- Depends on: T2 +- Files: sync/__init__.py, sync/excel_sync.py +- Status: completed + +### T6: CLI (Typer) — все команды +- Type: feature +- Depends on: T2, T3, T4, T5, T7 +- Files: cli/__init__.py, cli/main.py, pyproject.toml +- Status: completed + +### T7: AI Assistant (промпты + интерфейс) +- Type: feature +- Depends on: T3 +- Files: ai/__init__.py, ai/prompts.py, ai/assistant.py +- Status: completed + +### T8: Тесты на все модули +- Type: test +- Depends on: T2, T3, T4, T5, T6, T7 +- Files: tests/test_model.py, tests/test_forecast.py, tests/test_scenarios.py, tests/test_excel_sync.py, tests/test_cli.py, tests/test_ai.py, tests/conftest.py +- Status: completed ## Next Steps -Все задачи реализованы. Проект готов к использованию: -- `cf init` — создать пустую модель -- `cf forecast --months 12` — прогноз -- `cf import/export` — работа с Excel -- `cf analyze` — AI-анализ (заглушка) +Все 8 задач выполнены. Проект готов к использованию. ## Caveats -- AI-ассистент — заглушка, промпты готовы, но не подключены к реальному API -- Лицензия не указана — требуется решение -- JSON-файлы — не подходит для многопользовательской работы +- AI-ассистент — заглушка (промпты готовы, API не подключено) +- База данных — JSON-файлы (не подходит для многопользовательской работы) +- Лицензия не выбрана - CI/CD не настроен ## Checkpoints Файл: `.agent/checkpoints.json` -MetaAgent версия: 1.0.0 -Все фазы: completed +Актуальное состояние чекпоинтов прилагается. diff --git a/.agent/metaagent-request.md b/.agent/metaagent-request.md index 2a53ba7..c3c8e9d 100644 --- a/.agent/metaagent-request.md +++ b/.agent/metaagent-request.md @@ -1,22 +1,22 @@ # MetaAgent Request -# Auto-generated from user interview on 2026-07-12 +# Auto-generated from existing checkpoints.json on 2026-07-22 ## Параметры сессии | Функция | Вкл | Аргументы | |---|---|---| | ANALYSIS | ✓ | — | -| DESIGN | ✓ | adr=false, alternative_arch=false | -| RED_TEAM | false | — | -| RISK_REGISTER | false | — | +| DESIGN | ✗ | project_type=existing | +| RED_TEAM | ✗ | — | +| RISK_REGISTER | ✗ | — | | DECOMPOSITION | ✓ | invariant_tests=false | | SETUP | ✓ | — | | HANDOFF | ✓ | layer_structure=false | ## Глубина проработки -**Значение:** 4 +**Значение:** 4 (Light) ## Цель -Обновление metaagent-артефактов до v1.0.0, валидация существующего кода и окружения. +Обновление metaagent-артефактов до v1.1.0, валидация существующего кода и окружения diff --git a/.agent/rules/project-rules.md b/.agent/rules/project-rules.md new file mode 100644 index 0000000..2c0f802 --- /dev/null +++ b/.agent/rules/project-rules.md @@ -0,0 +1,22 @@ +# Project Rules + +Правила, которым агент обязан следовать во всех фазах. +Добавляйте сюда условия, которые должны соблюдаться всегда — они будут прочитаны +перед началом каждой фазы и учтены при декомпозиции и реализации. + +## Обязательные правила + +- Всегда читать `.agent/rules/project-rules.md` перед каждой фазой +- Следовать протоколам MetaAgent строго последовательно + +## Запреты + +- Не писать production-код (это работа исполнительного агента) +- Не удалять файлы +- Не коммитить в main/master + +## Конвенции проекта + +- Python-проект: snake_case для функций/переменных, PascalCase для классов +- Использовать ruff для линтинга +- Тесты через pytest \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 191b7dc..44dc3db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` | `` | Сценарий baseline/optimistic/pessimistic | -| `whatif` | `--income 1.0 --expense 1.0 --growth 1.0` | What-if анализ | -| `compare` | `--months 12` | Сравнение сценариев | -| `import` | `` | Импорт из Excel | -| `export` | `` | Экспорт в 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 # запуск 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 до актуальной версии.