Explore

Версия

# Проводник — Правила разработки

## Ядро проекта (core.txt)

### Миссия и замысел

- **Миссия**: Превращение случайного ученика в проактивного через 5 ступеней квалификации

- **И

И-проводник** учитывает цифровой двойник и персонализирует маршрут

- **Гипотеза**: Ускорение переходов по ступеням, рост артефактов, вклад в комьюнити

- **Ступени**: Случайный → Практикующий → Систематический → Дисциплинированный → Проактивный

### Вектор развития Ученика (КРИТИЧНО для Methodist!)

Принципы для выбора методов и генерации ежедневных заданий:

- **Компиляция**: Хаос → компиляция знаний в мировоззрение/навыки → стиль жизни

- **Время**: Систематичность → инвестированное время (до 10ч/неделю) → учтенное время (до 50ч/неделю)

- **Состояние**: Внимание на сон → продуктивное состояние в течение дня → рабочие продукты

- **Практики**: Простые практики (Инвестирование времени, Медленное чтение) → Все практики (легко) → Все практики (навык)

### Механизм "разрыв → задания"

1. **Диагностика**: разрыв между текущим и целевым состоянием (по метрикам характеристик)

2. **Генерация задания**: из разрыва + общее описание ступеней + вектор развития + принципы + доступное время + контекст + энергия + цифровой двойник + примеры методов

3. **Верификация**: критерии "готово" через Evidence

4. **Публикация**: запись в расписание

### Цифровой двойник — Характеристики (CHR)

- **Агентность**: регулярность саморазвития, рефлексии, стратегирование

- **Мастерство**: инвестированное/учтенное время, освоенные методы, пройденные руководства

- **Ресурсность**: продуктивное состояние (энергия, внимание, мотивация), поддерживающие методы

- **Адаптивность**: скорость восстановления после срывов, частота откатов

Обновление двойника: опросник, вечерний отчёт, поведение на платформе, артефакты, календарь

---

## Стек

- **Backend**: TypeScript + Node.js

- **Telegram Bot**: grammy

- **Graph DB**: Graphiti + Neo4j

- **AI Agents**: LangChain.js + OpenRouter (Grok 4 Fast)

- **API**: HTTP REST, версионирование `/v1`

## Инфраструктура Graphiti

**Расположение**: `/home/cehovoy/graphiti`

- **Neo4j**: `http://localhost:17474` (UI), `bolt://localhost:17687` (Bolt)

- **Worker API**: `http://localhost:8080`

- **Типы**: `/home/cehovoy/graphiti/data/graphiti_types.yaml` (26 узлов, 30+ связей)

- **Схемы данных**: `docs/schemas/` (18 JSON-схем)

- **Режимы записи**: `mode=fact` (детерминированная), `mode=auto` (гибкая с прямыми ветками)

### Режимы записи в Graphiti

1. **mode=fact**: детерминированная запись (без LLM)

- Используй для структурированных данных от системы

- Создаёт связи с явными UUID и атрибутами

2. **mode=auto**: гибкая запись с прямыми ветками (без LLM для известных событий)

- Используй для DailyReport, ForumPost

- Автоматически создаёт узел Student с детерминированным UUID

### Аутентификация

- Заголовок: `X-API-Key: <token>` или `Authorization: Bearer <token>`

- Токен из env: `WORKER_TOKEN` или `WORKER_API_KEYS`

## Архитектура агентов (роли из ядра)

### Orchestrator (Оркестратор)

**Статус**: Пока робот с жесткой логикой по расписанию

**Будущее**: ИИ-ассистент → ИИ-агент

**Роль**: Запуск утренних заданий, вечерних отчётов, недельной статистики (по TimePreference)

### Navigator (Навигатор) — `services/agents/navigator.ts`

**Роль**: Координатор сборки DailyAssignment из 4 блоков

**НЕ генерирует** задания сам, только координирует агентов

**Последовательность**:

1. Загрузить контекст → `GraphitiWorkerClient.loadStudentContext(studentId)`

2. Запросить Evaluator → `generateRecommendation(taskHistory, lastReports)` для разрыва

3. Запросить Methodist → `selectMethods(context, gap, daysFromRegistration)` для практик

4. Запросить Motivator → `generateMotivation(context)` для мотивации

5. Собрать DailyAssignment (greeting + analytics + task + motivation)

### Methodist (Методист) — `services/agents/methodist.ts`

**Роль из ядра**: Подбор методов через LLM на основе вектора развития и принципов

**Входы**: qualificationLevel, context (метрики, разрыв), gap, daysFromRegistration

**Выходы**: 1-2-3 практики (прогрессивно) + reasoning

**База данных**:

- Таблица 10 (`data/idea/table.csv`): принципы выбора методов для каждой ступени

- Таблица 9 (`data/idea/table.csv`): примеры методов (лестница методов)

- Вектор развития (из ядра): логика переходов между ступенями

### Evaluator (Оценщик) — `services/agents/evaluator.ts`

**Роль из ядра**: Определяет разрыв между показателями характеристик

**Функции**:

- Анализирует отчёты (DailyReport)

- Генерирует рекомендации ДЛЯ заданий (описание разрыва между текущим и целевым)

**Входы**: TaskHistory, DailyReport[]

**Выходы**: EvaluatorRecommendation (type, text, reasoning с описанием разрыва)

### Motivator (Мотиватор) — `services/agents/motivator.ts`

**Роль из ядра**: Мотивационные сообщения + лидерство

**Входы**: context, lastReports

**Выходы**: мотивационный текст + tone + progressData + meme

### Будущие агенты (пока не реализуем)

- **Консультант**: обратная связь по прогрессу (подроль Наставника)

- **Planner**: планирование слотов МУП (минимальной устойчивой практики)

- **Librarian**: доступ к руководствам/понятиям (через Graph Worker endpoint)

- **Ethicist**: границы и риски взаимодействия

### Структура данных (КРИТИЧНО!)

#### DailyAssignment v5 — 4-блочная структура

```typescript

{

date: "2025-10-17",

greetingBlock: { // Приветствие

studentName, date, greeting

analyticsBlock: { // Аналитика

hasData, yesterdayStats?, message?

taskBlock: { // Задание на день

studyTask: { guideName, estimatedMinutes },

practices: [ // 1-2-3 практики (прогрессивно)

{ practiceName, emoji, recommendation }

]

motivationBlock: { // Мотивация

qualificationProgress: {

currentLevel, nextLevel, keyFocusReminder // Формальное задание из key_focus

memeText?, memeType?

}

```

#### DailyReport — расширенный формат

```typescript

{

date, done, minutes, investedMinutes, workProducts,

state: { energy, attention, motivation, sleep },

studyProgress: { studied, wantsQuestions, sectionCompleted },

reflection: { satisfaction, praisedSelf, noteOfTheDay },

usedMethods, challenges, successes

}

```

## Работа с Graphiti

### GraphitiWorkerClient (`services/context/graphiti-worker.ts`)

**Запись данных** (8 методов):

- `saveDailyAssignment()` — 4-блочный формат

- `saveDailyReport()` — расширенный формат

- `saveAgentProfile()`, `saveTimePreference()`, `saveWeeklyPlan()`

- `saveQualificationProfile()`, `saveQualificationDecision()`, `saveStrategicLog()`

**Чтение данных** (9 методов):

- `getAgentProfile()`, `getTimePreference()`, `getQualificationProfile()`

- `getWeeklyPlan()`, `getCurrentWeeklyPlan()`

- `getLastNReports()`, `getDailyReports()`, `getTaskHistory()`

- **`loadStudentContext()`** ⭐ — загрузка всего контекста за один вызов

**Конфигурация** (с Neo4j для чтения):

```typescript

const worker = createGraphitiWorkerClient({

apiUrl: 'http://localhost:8080',

apiKey: process.env.GRAPHITI_API_KEY!,

neo4j: {

uri: 'bolt://localhost:17687',

user: 'neo4j',

password: 'password',

});

```

### Neo4j Query Client (`services/context/neo4j-client.ts`)

Используется внутри GraphitiWorkerClient для чтения через Cypher-запросы.

## Модель квалификации и методы

**Квалификация**: `data/qualification/model.yaml` — 5 ступеней (Случайный → Проактивный), критерии, ключевые объекты внимания (key_focus)

**Методы**: `data/idea/table.csv` — таблица 9 (лестница методов), таблица 10 (принципы выбора)

**Ядро проекта**: `data/idea/core.txt` — миссия, вектор развития, механизм "разрыв → задания"

## Правила работы

### 1. Маленькие шаги

Реализуем по одной фиче из `docs/TODO.md`. Не делаем несколько задач параллельно.

### 2. Без мёртвого кода

Каждая функция должна **вызываться**. Не создаём код "на будущее".

### 3. Без заглушек

Если создаём файл — реализуем **полностью**. Если нужно TODO — явно помечаем и возвращаемся.

### 4. Стандарт типов и данных

**ВСЕГДА сверяйся**:

- С `data/idea/core.txt` для ядра проекта и вектора развития

- С `graphiti_types.yaml` для типов узлов и связей в Neo4j

- С `docs/schemas/` для структуры документов

- С `data/qualification/model.yaml` для ступеней квалификации и key_focus

- С `data/idea/table.csv` для принципов выбора методов (таблица 10)

### 5. Тестирование

Для каждого агента/модуля создаём тестовый скрипт в `scripts/test/test-*.ts`.

### 6. Логирование

После завершения задачи отмечай в `docs/TODO.md`.

## Структура проекта

```

/home/cehovoy/project/explorer/

├── services/

│ ├── bot/ # Telegram gateway

│ ├── context/ # GraphitiWorkerClient, Neo4jClient

│ ├── agents/ # AI агенты (Navigator, Methodist, Evaluator, Motivator)

│ └── orchestrator/ # Планировщик (TODO)

├── data/

│ ├── guides/ # Руководство "Системное саморазвитие" (9 разделов)

│ ├── mems/ # 120 непродуктивных мемов

│ ├── qualification/ # model.yaml (5 ступеней)

│ └── methods/ # ladder.yaml (TODO: создать!)

├── docs/

│ ├── TODO.md # Актуальный план

│ ├── architecture.md # Полная архитектура

│ └── schemas/ # 18 JSON-схем

└── scripts/ # Тестовые скрипты

/home/cehovoy/graphiti/ # Graphiti Worker + Neo4j

└── data/graphiti_types.yaml # Схема типов (v2.0)

```

## Документация

- **Ядро проекта**: `data/idea/core.txt` (миссия, вектор развития, механизм разрыв→задания)

- **Архитектура**: `docs/architecture.md`

- **Работа с Graphiti**: `services/context/README.md`

- **Актуальный план**: `docs/TODO.md`

## Команды для разработки

### Запуск

```bash

npm run dev # Запуск бота в режиме разработки

npm run build # Сборка TypeScript

npm start # Запуск production версии

```

### Тестирование

```bash

Want to print your doc?
This is not the way.

Try clicking the ··· in the right corner or using a keyboard shortcut (

CtrlP

) instead.