# Руководство пользователя VeriThink

VeriThink помогает **спланировать и проверить** реализацию до написания кода: edge cases, ошибки, тесты, безопасность, конкурентность. Движок строит когнитивный граф, символически проверяет пробелы и выдаёт структурированный план в Markdown.

Основной способ использования — **MCP-инструменты в Cursor**. Альтернатива — прямой HTTP API.

---

## Установка

### Вариант A: магазин (рекомендуется)

1. **Add to Cursor** — one-click deeplink из [README](../README.md#add-to-cursor) или [DEEPLINK.md](DEEPLINK.md).
2. Либо вручную добавьте в `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "verithink": {
      "command": "npx",
      "args": ["-y", "verithink-mcp"],
      "env": {
        "VERITHINK_AUTOSTART": "1",
        "VERITHINK_LLM_PROVIDER": "openai"
      }
    }
  }
}
```

3. Перезапустите MCP в Cursor. Backend поднимется автоматически (`VERITHINK_AUTOSTART=1`).

> **Важно:** Cursor **не поддерживает MCP sampling**. Значение `VERITHINK_LLM_PROVIDER=mcp-sampling` в deeplink/примерах **не даёт реального LLM** (откат к stub). Для работы в Cursor укажите **свой API-ключ** (`openai` / `anthropic` / `gemini`), **`local`** (Ollama) или **`service`** через [личный кабинет](#личный-кабинет-и-режимы-оплаты) — см. [BILLING.md](BILLING.md).

### Вариант B: локально из репозитория (клон, несколько окон Cursor)

Не запускайте `node …/mcp/dist/server.js` как команду Cursor — окна склеятся на один процесс.

```powershell
powershell -File scripts/setup-cursor.ps1 -RestoreGlobalMultiProject -Lane api
powershell -File scripts/ensure-api-lane.ps1
```

Скрипт пишет **project** `.cursor/mcp.json` + `.cursor/vt-mcp-bridge.cmd`. В `~/.cursor/mcp.json` блока `verithink` быть не должно. Другая папка на этом ПК: `-Target "<абс. путь>" -NoBuild -SkipHooks`.

Пример (путь замените на свой клон):

```json
{
  "mcpServers": {
    "verithink": {
      "command": "E:/Orlov Production2/aithink/.cursor/vt-mcp-bridge.cmd",
      "args": ["E:/Orlov Production2/aithink"],
      "cwd": "E:/Orlov Production2/aithink",
      "env": {
        "VERITHINK_SERVICE_URL": "http://127.0.0.1:8789",
        "VERITHINK_AUTOSTART": "0",
        "VERITHINK_MCP_ASYNC": "1",
        "VERITHINK_MCP_INLINE_BUDGET_MS": "25000"
      }
    }
  }
}
```

Сборка MCP: [ADMIN.md — Сборка](ADMIN.md#сборка). Standalone `node mcp/dist/server.js` **без Cursor** по-прежнему валиден.

### Если backend уже запущен

Агент Cursor (API lane) — без autostart:

```json
"env": { "VERITHINK_SERVICE_URL": "http://127.0.0.1:8789" }
```

Дашборд / browser lane: `http://127.0.0.1:8787`.

Подробнее о публикации и полном тестировании: [ADMIN.md](ADMIN.md).

---

## Как пользоваться через Cursor (MCP)

Убедитесь, что ReasonService запущен (или MCP настроен с `VERITHINK_AUTOSTART=1`). В чате Cursor агент может вызывать инструменты VeriThink по имени.

### Таблица инструментов

| Инструмент | Назначение | Когда вызывать | Пример запроса агенту |
|------------|------------|----------------|------------------------|
| `reason_plan` | Проверенный пошаговый план до кода | Любая нетривиальная фича, рефактор, багфикс | «Спланируй добавление rate limiting на POST /api/login» |
| `reason_check` | Быстрый аудит пробелов/противоречий | Есть черновик плана или ТЗ, нужен review без полного synth | «Проверь этот план на пробелы: …» |
| `reason_testplan` | Тест-матрица: кейсы, границы, негатив, гонки | Перед написанием тестов или после фичи | «Составь тест-план для модуля загрузки файлов» |
| `reason_debug` | Root-cause анализ бага | Стектрейс, воспроизводимая ошибка | «Разбери NullReference в OrderService, стек: …» |
| `reason_refine` | Уточнение прошлого плана по `taskId` | Нужно дополнить/изменить уже полученный план | «Уточни план task-abc: добавь idempotency для retry» |
| `reason_why` | Провенанс шага плана | Непонятно, почему шаг именно такой | «Объясни, почему в плане шаг deploy-migration обязателен» |
| `reason_review` | Аудит плана/кода с CRITIQUE | Code review, pre-merge проверка | «Сделай review этого diff на security и edge cases» |
| `reason_pack` | Memory pack — краткий контекст под бюджет токенов | Перенос контекста в другой чат / обрезка истории | «Собери memory pack по задаче rate limiting» |
| `reason_verify` | Проверка реализации vs план | После написания кода / diff | «Проверь task-abc: вот diff…» |
| `reason_feedback` | Обратная связь для обучения | План сработал / всплыл баг по категории | «Зафиксируй: план task-xyz сработал, категория security» |

---

## Подробно по инструментам

### `reason_plan`

**Вход:**

| Поле | Обязательно | Описание |
|------|-------------|----------|
| `request` | да | Описание задачи или фичи |
| `domain` | нет | Домен (по умолчанию `coding`) |
| `context` | нет | Дополнительный контекст |
| `providedFiles` | нет | Пути файлов, уже прочитанных агентом |

**Выход:** Markdown-план (`answerMarkdown`) + **Coverage**, список **Open questions**.

Если `status` = `needs_grounding`, в ответе будут **Requested files** — прочитайте их и вызовите `reason_plan` снова с `providedFiles`.

**Совет:** вызывайте до любого нетривиального кода; следуйте DoD-чек-листу из плана.

### `reason_check`

**Вход:** `request` (план или описание), опционально `context`.

**Выход:** JSON с `gaps`, `contradictions`, `missingMandatoryCategories`, `coverage` — без полного narrative-плана. Быстрее, чем `reason_plan`, когда нужен только аудит.

### `reason_testplan`

**Вход:** `request`, `context` (код или описание фичи).

**Выход:** Markdown + блок **Tests to write** (список из `synth.testsToWrite`). Режим `options.mode: "test"` на стороне сервиса.

### `reason_debug`

**Вход:** описание бага, стектрейс, `context` с релевантным кодом.

**Выход:** план с гипотезами, минимальным фиксом и регресс-тестом (`options.mode: "debug"`).

### `reason_refine`

**Вход:**

| Поле | Обязательно | Описание |
|------|-------------|----------|
| `refineTaskId` | да | `taskId` из предыдущего `reason_plan` |
| `request` | да | Что добавить или изменить |
| `context` | нет | Новый контекст |

Загружает граф prior task и прогоняет reasoning в режиме `refine` (с diff предыдущего плана).

### `reason_why`

**Вход:** `taskId`, опционально `stepId` (если пусто — первый шаг плана).

**Выход:** JSON `{ taskId, stepId, provenance: [...] }` — какие узлы графа и категории обосновывают шаг.

### `reason_review`

**Вход:** `request` (план или код), `context`.

**Выход:** полный Markdown-отчёт с CRITIQUE (`options.mode: "review"`). На Free-тарифе CRITIQUE ограничен 3 узлами; Trial/Pro — расширенный (`critique_extended`).

### `reason_pack`

**Вход:** `request`, опционально `taskId` (привязка к experience), `tokenBudget` (по умолчанию из `VERITHINK_PACK_TOKEN_BUDGET`).

**Выход:** сжатый Markdown-бриф для вставки в контекст другого чата.

### `reason_verify`

**Вход:** `taskId` (из `reason_plan`), `artifact` (diff, код или описание реализации), опционально `providedFiles`.

**Выход:** JSON `VerificationReport`: `items[]` со статусами `done` / `partial` / `missing`, `doneScore`, `mergeReady`.

Опционально `verifyMode`: `steps` (по умолчанию), `outcome`, `both` — для Goal mode используйте `outcome` после реализации.

Последний отчёт можно получить через HTTP `GET /v1/verify/{taskId}`.

### `reason_goal_session` (Goal mode)

Требует `VERITHINK_GOAL_MODE_ENABLED=1` на сервере. User включает режим в чате: «**режим: цель.** …»

1. `action=start` → `goalRunId`, scope map, `needsUser=true`
2. AskQuestion → `action=advance` с `scopeConfirm`
3. Код → `reason_verify(verifyMode=outcome)` → `action=advance` с `artifact` до `phase=Done`
4. `reason_feedback`

Подробнее (aithink repo): `docs/GOAL_MODE.md`.

### `reason_feedback`

**Вход:**

```json
{
  "taskId": "abc123",
  "outcome": {
    "success": true,
    "category": "error_handling"
  }
}
```

`outcome` — произвольный объект; поля `success` и `category` обновляют профиль и learning report.

---

## Типичные сценарии (workflow)

### 1. Спланировать фичу перед кодом

1. Попросите агента вызвать `reason_plan` с описанием фичи.
2. Если есть open questions — ответьте агенту, затем `reason_refine` или повторный `reason_plan` с `context`.
3. Реализуйте по плану; по завершении — `reason_feedback` с `success: true`.

### 2. Проверить готовый план или diff

1. Вставьте план/описание в чат.
2. `reason_check` для быстрого JSON-отчёта или `reason_review` для глубокого аудита.

### 3. Сгенерировать тест-план

1. Опишите фичу или приложите фрагменты кода в `context`.
2. `reason_testplan` → список **Tests to write**.

### 4. Отладить баг

1. Вставьте стектрейс и симптомы.
2. `reason_debug` → гипотезы, фикс, регресс-тест.
3. После фикса — `reason_feedback` с `success: false` и `category` проблемной области.

### 5. Уточнить план по фидбеку (refine)

1. Сохраните `taskId` из ответа `reason_plan`.
2. `reason_refine` с `refineTaskId` и новым запросом («добавь OAuth», «учти multi-tenant»).

### 6. Понять, почему шаг такой (why)

1. `reason_why` с `taskId` и `stepId` из плана.
2. Или откройте ресурс `verithink://experience/{taskId}` (см. ниже).

### 7. Memory pack для контекста чата

1. После `reason_plan` запомните `taskId`.
2. `reason_pack` с `request` и `taskId` → вставьте Markdown в новый чат.

---

## Промпт `plan-before-code`

MCP регистрирует slash-style промпт **`plan-before-code`** с аргументом `task`.

При вызове он формирует сообщение:

> Before writing code, call reason_plan for: {task}. Follow the returned plan and DoD checklist.

**Когда использовать:** как напоминание агенту в начале сессии или перед крупной задачей — вместо ручного текста «сначала спланируй».

---

## Ресурс `verithink://experience/{taskId}`

MCP-ресурс **`experience-graph`** по URI `verithink://experience/{taskId}`.

Содержимое: полный `ExperienceRecord` в JSON (`graphJson`, цели, категории, coverage).

**Когда использовать:**

- Инспекция когнитивного графа после reasoning
- Отладка провенанса без вызова `reason_why`
- Передача структурированного контекста другому агенту

---

## Прямой вызов HTTP API

Базовый URL: `http://127.0.0.1:8787` (настраивается `VERITHINK_PORT`).

### `POST /v1/reason`

**PowerShell:**

```powershell
$body = @{
  request = "Add retry logic with exponential backoff to HTTP client"
  domain  = "coding"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://127.0.0.1:8787/v1/reason" `
  -Method Post -Body $body -ContentType "application/json"
```

**curl:**

```bash
curl -X POST http://127.0.0.1:8787/v1/reason \
  -H "Content-Type: application/json" \
  -d '{"request":"Add rate limiting to POST /api/login","domain":"coding"}'
```

Ключевые поля ответа:

| Поле | Описание |
|------|----------|
| `taskId` | ID для refine/why/feedback/pack |
| `status` | `ok`, `needs_clarification`, `needs_grounding`, `abstained`, … |
| `answerMarkdown` | Готовый план (Markdown) |
| `coverage` | Доля покрытых категорий (0–1) |
| `openQuestions` | Вопросы к пользователю |
| `reasoningHash` | Хеш рассуждения для трассировки |

Refine через HTTP — то же тело + `refineTaskId`:

```json
{
  "request": "Add idempotency keys for retries",
  "refineTaskId": "prior-task-id",
  "options": { "mode": "refine" }
}
```

### `POST /v1/pack`

```powershell
$body = @{
  request     = "Rate limiting for login endpoint"
  taskId      = "your-task-id"
  tokenBudget = 1500
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://127.0.0.1:8787/v1/pack" `
  -Method Post -Body $body -ContentType "application/json"
```

### `GET /v1/why/{taskId}`

```bash
curl "http://127.0.0.1:8787/v1/why/abc123?stepId=step-deploy"
```

### `GET /v1/experience/recent`

```bash
curl http://127.0.0.1:8787/v1/experience/recent
```

Возвращает до 20 записей: `taskId`, `domain`, `goalTitles`, `categoriesUsed`, `coverage`, `createdAt`.

---

## Дашборд `/ui`

При `VERITHINK_UI=1` откройте `http://127.0.0.1:8787/ui`.

| Панель | Данные |
|--------|--------|
| **Health** | JSON из `/healthz` (модель, store, license tier, config problems) |
| **Recent experience** | Таблица последних задач и coverage |
| **Try reason** | Интерактивный вызов `/v1/reason` |
| **Cognitive graph** | Mermaid из `answerMarkdown` |
| **Learning report** | Категории (uses/failures), lessons, promotion candidates |

---

## FAQ

**Нужен ли API key?**  
Нет, если `VERITHINK_LLM_PROVIDER=fake` или `local`. Для OpenAI/Anthropic/Gemini (BYOK) — да. Режим **`service`** — токен аккаунта вместо ключа провайдера ([BILLING.md](BILLING.md)). **`mcp-sampling` в Cursor не работает** — не считайте его «без ключа».

**Где взять `taskId`?**  
В каждом ответе `reason_plan` / HTTP `/v1/reason` — поле `taskId`. Сохраняйте для refine, why, feedback, pack.

**Что значит низкий Coverage?**  
План не покрыл все обязательные категории (validation, edge cases, error handling, testing). Дополните запрос или вызовите `reason_refine`.

**Что делать при `needs_grounding`?**  
Прочитайте файлы из `requestedFiles`, передайте в `providedFiles` и повторите `reason_plan`.

**Чем `reason_check` отличается от `reason_review`?**  
`reason_check` — компактный JSON (gaps/contradictions). `reason_review` — полный narrative + CRITIQUE (глубже, дороже по LLM).

**Работает ли без Cursor?**  
Да: HTTP API, дашборд `/ui`, curl/Invoke-RestMethod. MCP нужен только для интеграции с IDE-агентом.

**Как включить Pro-фичи?**  
Администратор выпускает ключ через LicenseServer; ключ в `VERITHINK_LICENSE_KEY`. См. [ADMIN.md — Лицензирование](ADMIN.md#лицензирование).

**Можно ли писать планы на русском?**  
Да. `VERITHINK_LANG=auto` определяет язык из запроса; ответ synth следует языку задачи.

**Сколько ждать ответ?**  
Типично 30–120 с; таймаут MCP — `VERITHINK_REQUEST_TIMEOUT_MS` (+20 с для reason). Сложные задачи с CRITIQUE/Judge — дольше.

---

## Личный кабинет и режимы оплаты

Опциональный **AccountServer** (`tools/AccountServer`) даёт регистрацию, биллинг и LLM-шлюз. Веб-кабинет по умолчанию: **`http://127.0.0.1:8091/`** (на удалённом хосте — ваш URL и HTTPS).

### Регистрация и вход

1. Откройте кабинет в браузере.
2. Вкладка **«Регистрация»** — email и пароль (минимум 6 символов).
3. После входа сохраняется Bearer-токен в `localStorage` браузера; его же нужно скопировать для VeriThink.

Разделы кабинета: **Баланс**, **Режим LLM**, **Пополнение**, **Подключение к VeriThink**, **Расход**, **Тарифы**.

### Выбор режима LLM

| Режим в кабинете | Описание |
|------------------|----------|
| **Сервис** (`service`) | Запросы через ключи вендора; **10** бесплатных запросов по умолчанию (`VERITHINK_FREE_QUOTA`), затем списание с баланса |
| **BYOK** (`byok`) | Ваш OpenAI / Anthropic / Gemini ключ (хранится зашифрованно на сервере) |
| **Локальная модель** (`local`) | Ollama, LM Studio и др. — `http://127.0.0.1:11434/v1` по умолчанию, без оплаты через VeriThink |

Режим в кабинете влияет на **`POST /v1/llm/complete`**. Для инструментов Cursor (`reason_plan` и др.) дополнительно настройте ReasonService (ниже).

### Подключение VeriThink (Cursor / admin)

1. В кабинете откройте **«Подключение к VeriThink»** → скопируйте env или `.cursor/mcp.json`.
2. **Вариант A — локальная админка:** `http://127.0.0.1:8787/admin.html` → провайдер **`service`**, URL аккаунт-сервера, токен.
3. **Вариант B — `.cursor/mcp.json`:**

```json
{
  "mcpServers": {
    "verithink": {
      "command": "npx",
      "args": ["-y", "verithink-mcp"],
      "env": {
        "VERITHINK_AUTOSTART": "1",
        "VERITHINK_LLM_PROVIDER": "service",
        "VERITHINK_ACCOUNT_URL": "http://127.0.0.1:8091",
        "VERITHINK_ACCOUNT_TOKEN": "<токен из кабинета>"
      }
    }
  }
}
```

4. Задайте модели при необходимости: `VERITHINK_LLM_MODEL_CHEAP`, `VERITHINK_LLM_MODEL_STRONG` (иначе шлюз использует `gpt-4o-mini` по умолчанию).
5. Перезапустите MCP в Cursor.

При исчерпании баланса ReasonService вернёт ошибку про **402 insufficient_balance** — пополните баланс в кабинете.

### Пополнение, расход и тарифы

- **Пополнение:** блок «Пополнение баланса» → сумма в USD → **Пополнить**. По умолчанию провайдер **`manual`** (мгновенное зачисление для тестов).
- **Расход:** таблица последних вызовов (`GET /v1/usage`) — дата, провайдер, модель, токены, стоимость, источник (`free` / `balance` / `byok` / `local`).
- **Тарифы:** в кабинете показаны итоговые цены за 1000 токенов (USD); точную стоимость каждого запроса видно в журнале расхода.

---

## См. также

- [Биллинг и режимы LLM](BILLING.md) — формулы, тарифы, безопасность
- [Руководство администратора](ADMIN.md) — развёртывание, env, Postgres, лицензии, AccountServer
- [README — Add to Cursor](../README.md#add-to-cursor) — deeplink и npx
- [DEEPLINK.md](DEEPLINK.md) — генерация кнопки установки
- [README](../README.md) — quickstart