From 8ac568b97e330825188503c498970aadba0139e4 Mon Sep 17 00:00:00 2001 From: "Claude (backend session)" Date: Thu, 9 Jul 2026 16:16:11 +0300 Subject: [PATCH] Archive closed session prompts and add onboarding docs: root CLAUDE.md plus backend and eval READMEs --- CLAUDE.md | 41 +++++++++++++++++++++++++++++++++++++++++ backend/README.md | 41 +++++++++++++++++++++++++++++++++++++++++ docs/README.md | 34 +++++++++++++--------------------- docs/archive/README.md | 5 +++++ eval/README.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 128 insertions(+), 21 deletions(-) create mode 100644 CLAUDE.md create mode 100644 backend/README.md create mode 100644 docs/archive/README.md create mode 100644 eval/README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..39be86c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,41 @@ +# TextMachine — контекст для Claude-сессий + +Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: черновик DeepSeek → монолингвальный редактор grok-4.3 → судья Gemini (Ф2). Цели: победить translationese; низкий COGS (~$0.69/ранобэ); детерминированный банк памяти книги; 18+ с учётом цензуры; телеметрия денег с первого дня. + +## Роли сессий и зоны (НЕ править чужую зону) + +| Роль | Зона записи | Всё остальное | +|---|---|---| +| **Бэкенд** | `backend/` | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` | +| **Полигон (eval)** | `eval/` + `docs/experiments/` | то же | +| **Оркестратор** | `docs/` (architecture/research/PROGRESS), ревью чужого кода read-only | ратифицирует решения, пишет хендофф-промты | + +Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»/«Память»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии. + +## Источники истины (по убыванию) + +1. **`docs/architecture/05-decisions-log.md` (D1–D17)** — ратифицированный контракт; при конфликте с любым другим доком побеждает он. +2. `docs/architecture/07-strategic-review.md` — стратегический аудит 09.07 (вердикт, риски, курс-коррекции). +3. `docs/experiments/00-provider-quirks.md` — wire-квирки провайдеров (читать ПЕРЕД правкой адаптеров/вызовами провайдеров). +4. `docs/architecture/01-decisions.md` (Р1–Р10), `02-mvp-plan.md` (фазы v3), `04-unhappy-paths.md`, `06-memory-risk-registry.md`. +5. `docs/research/*` — фактура; часть под ⚠ superseded-баннерами — читай баннер прежде содержимого. +6. `docs/archive/` — закрытые промты, только история. + +## Гардрейлы (жёсткие) + +- **НИКОГДА не читать `.env`** (`backend/.env`, `eval/.env`) — там ключи. `.env.example` можно. +- **18+ уровень 3** (несовершеннолетние в сексуальном контексте) — не обрабатывать/не анализировать; `eval/data/refusal_corpus/*` не открывать без прямой задачи владельца. +- **PUML не рендерить в svg/png** — владелец смотрит PlantUML-расширением VS Code. +- **Коммиты**: английский, одно предложение ≤30 слов, без Co-Authored-By. `.claude/settings.local.json` НЕ коммитить (ломает пермишены). +- Провайдерские ловушки: **DeepSeek — НИКОГДА не отключать thinking** (эхо-мина; гейт `echoMineViolation` это принуждает); grok-4.3 reasoning off — только ЯВНЫЙ `reasoning_effort:"none"` (дефолт low); слаги моделей не менять без live-фактчека `/models`. +- Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза. + +## Онбординг новой сессии (порядок чтения) + +1. Этот файл → `docs/README.md` (карта) → CURRENT-STATE в `docs/PROGRESS.md`. +2. `docs/architecture/05-decisions-log.md` целиком (контракт). +3. По роли: Бэкенд — `backend/README.md` + `03-implementation-notes.md`; Полигон — `eval/README.md` + `experiments/00` + `09-pilot-protocol.md`; всем — `07-strategic-review.md` §6–9 (вердикт/риски/курс). + +## Текущее состояние (2026-07-09) + +Фаза 0 ✅; машинерия Ф1 в основном построена (память v2, чанкер, disposition, coverage, single-hop эскалация, durable resume). До приёмки Ф1: фиксы D15/D16, `tmctl status`+redrive, дешёвые гейты, автопопуляция/сид, реальный ja→ru прогон. Решающая точка — пилот Ф2.5 (протокол exp09 + поправки D13; харнесс чинится ДО прогона). Ключи: DEEPSEEK, ZAI, KIMI, OPENAI, GEMINI, XAI. Стенд: WSL2, GTX 1070 8GB (прокси-грабли: localhost из-под прокси даёт 403 — no-proxy транспорт для local). diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..173aeaf --- /dev/null +++ b/backend/README.md @@ -0,0 +1,41 @@ +# backend/ — Go-бэкенд TextMachine + +Зона сессии «Бэкенд». Контракт — `docs/architecture/05-decisions-log.md` (D1–D17); контракты Фазы 0 — `03-implementation-notes.md`; квирки провайдеров — `docs/experiments/00-provider-quirks.md`. **`.env` не читать.** + +## Карта пакетов + +| Пакет | Что делает | Ключевые файлы | +|---|---|---| +| `cmd/tmctl` | CLI: `translate --config book.yaml` / `report` (status/redrive — в работе, D15.3) | `main.go` | +| `internal/llm` | OpenAI-совместимый транспорт + retry/backoff, **capability-слой** (budget_field/temperature/reasoning per-модель), failover (написан, НЕ подключён — D4: только local-роли), нативный Anthropic = DEPRECATED-референс под будущий Gemini | `httpllm.go`, `capability.go`, `failover.go` | +| `internal/ledger` | Цены по usage (вкл. reasoning/cache-поля), `PriceForResponse` по фактической модели | `pricing.go` | +| `internal/store` | SQLite (modernc, CGO-free), идемпотентные миграции v1–v5, reserve/settle+checkpoint, chunk_status, глоссарий, ruby, retrieval_state, request_log | `ledger.go`, `migrate.go`, `glossary.go` | +| `internal/config` | fail-fast загрузка models/pipeline/book; **эхо-мина-гейт** `echoMineViolation`; `CheckRunnable` блокирует неисполнимое (C2/fanout/judge) | `models.go`, `pipeline.go` | +| `internal/pipeline` | Раннер (циклы, disposition, single-hop эскалация с ре-гейтом, resume), чанкер v4, ingest txt/epub+ruby, classify/coverage, **банк памяти v2** (Aho-Corasick, спойлер-окна, disposition, post-check), рендер+инъекция | `runner.go`, `memory.go`, `disposition.go`, `coverage.go` | +| `internal/obs` | trace_id, структурные логи, safego | | + +## Инварианты — ЛОМАТЬ НЕЛЬЗЯ (каждый закреплён тестами) + +1. **Деньги:** reserve → call → **settle+checkpoint одной транзакцией**; `committed == SUM(checkpoints)` переживает kill -9 (`kill9_test.go`); цена — по фактически ответившей модели; потолки книга/день считают committed+reserved. +2. **Snapshot-дисциплина:** всё, что влияет на wire-байты ИЛИ на вердикты (capability, память content-hash, context-assembly, версии classify/coverage/chunker/maxtok, эскалационные оверрайды), свёрнуто в `snapshotID`; правка = громкий `--resnapshot`. ⚠ Любой resnapshot = переоплата книги (D15) — content-addressed reuse спроектировать до онгоинга. +3. **Эхо-мина DeepSeek:** thinking у deepseek НИКОГДА не отключать — `reasoning:"off"` там осознанный no-op; `echoes_when_thinking_off` + рекурсивный скан extra_body валят конфиг fail-fast. У grok наоборот: off = ЯВНЫЙ `reasoning_effort:"none"`. +4. **Порядок classify:** refusal-blacklist / CJK-echo — ДО length/empty (усечённый отказ не превращается в платный ретрай); retry-flagged только {length, empty} на той же модели; loop-чек ПЕРЕД удвоением max_tokens. +5. **Эскалация:** ровно 1 хоп на другую модель, результат РЕ-гейтится, retry-бюджет не сбрасывается, editor pinned (escalate_to только на translator — принуждается валидацией), канал adult — только permissive-провайдеры (fail-closed). +6. **Детерминизм:** рендер — чистая функция snapshot; сортировки перед записью; никакого map-order в выводе; length-prefixed хэши. Сорс-чанкер lossless (fuzz-тесты). +7. **Нейтральность адаптера:** `internal/llm` не знает про перевод (src/target/coverage) — контент-вердикты живут в раннере (disposition-слой, post-settle). + +## Как гонять + +```bash +go build ./... && go vet ./... && go test ./... -race # всё зелёное = норма +go run ./cmd/tmctl translate --config example/book.yaml # реальные вызовы — нужны ключи в .env +go run ./cmd/tmctl report --config example/book.yaml # $0, читает store +# live-conformance (реальные провайдеры, платно, вне CI): +set -a; . ./.env; set +a; TM_LIVE=1 go test -tags live -run TestLive -v ./internal/pipeline/ +``` + +Финал каждой вехи — агентское адверсариальное селфревью (несколько дименсий → независимая верификация каждой находки → фиксы mutation-verified: реверт фикса валит именно его тест). Внешнее ревью — оркестратор. + +## Известный техдолг (не трогать молча — см. D-лог) + +F3 at-most-once (после status/redrive); Escal.Chains — валидируемый мёртвый конфиг (раннер читает только `escalate_to`, полные цепочки = шаг 7); модели D3-эскалации не заведены в `models.yaml` (интерим-заглушки помечены); min-budget Kimi≥16k/Gemini≥8k — комментарии, не схема; фиксы границ памяти D16. diff --git a/docs/README.md b/docs/README.md index bc3c114..858b6b4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,34 +1,26 @@ # TextMachine — документация -Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en/ru во все стороны) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD). +Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD). Онбординг Claude-сессий: [../CLAUDE.md](../CLAUDE.md). Ключевые цели: 1. Максимальное художественное качество — победить «нехудожественность» AI-переводов. -2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие вызовы дорогих (судья/селектор). +2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие адресные вызовы дорогих. 3. Банк памяти / глоссарий на всю книгу — консистентность имён, терминов, стиля. -4. Обработка 18+/жёсткого контента с учётом цензуры провайдеров (мультипровайдерность). +4. Обработка 18+ с учётом цензуры провайдеров (мультипровайдерность). 5. Телеметрия токенов/стоимости/качества с первого дня. -6. Высокая маржа; целевой рынок — ru/en переводчики, редакторы, копирайтеры. ## Структура -- `research/` — результаты исследований: - - `01-market.md` — рынок и спрос; `02-competitors.md` — конкуренты; `03-academic-agentic-mt.md` — наука (agentic MT, метрики); `04-api-providers.md` — цены/качество/цензура API; `05-memory-glossary.md` — банк памяти и глоссарий; `06-local-models.md` — локальные модели (8GB VRAM); `07-translation-methodology.md` — методология худперевода; `08-legal.md` — право; `09-cost-model.md` — модель стоимости; `10-vojo-ai-bot-review.md` — ревью переиспользуемого Go-кода; - - `11-gap-1…5.md` — добор пробелов критиком: RU-платежи/санкции, 18+ политики провайдеров (уточнение), валидация ядра пайплайна на zh→ru/ja→ru, российская конкурентная экосистема, платёжеспособный спрос; - - `12-*.md` — дозаправка: отзывы потребителей, таксономии ошибок, режимы отказа ja/zh/ru-сторона (~70 режимов → `architecture/04-unhappy-paths.md`); `13-memory-bank-validation.md` — валидация банка памяти; `14-adaptive-memory.md` — вердикт по адаптивной памяти (гибрид не строим). -- `architecture/` — синтез (**актуальный источник истины по решениям — `05-decisions-log.md`**; при конфликте с 01/02 он выше): - - `01-decisions.md` — принципы Р1–Р10 (стек, экономика, гейты); `02-mvp-plan.md` — фазы 0–3 и приёмка; `03-implementation-notes.md` — контракты Фазы 0; `04-unhappy-paths.md` — ~70 режимов отказа → механизм; **`05-decisions-log.md` — ратифицированный контракт Фазы 1 (D1–D12)**; `06-memory-risk-registry.md` — реестр рисков банка памяти; `components.puml`/`pipeline.puml` — диаграммы (владелец смотрит PlantUML-расширением VS Code, .svg вручную не рендерить). -- `experiments/` — эмпирика «Полигона»: `00-provider-quirks`, `01-token-calibration`, `02-refusal-benchmark`, `03-local-stand`, `04-editor-quality`, `06-local-extraction`, `07-coverage-precision`, `08-cost-model-v2`, `09-pilot-protocol` (текущий промт — `POLYGON_SESSION_PROMPT_PHASE2.md`). -- `PROGRESS.md` — **журнал** прогресса (хронология; НЕ источник решений — решения ратифицированы в `architecture/05-decisions-log.md`). +- `architecture/` — синтез. **Источник истины по решениям — [`05-decisions-log.md`](architecture/05-decisions-log.md) (D1–D17); при конфликте с любым доком он выше.** + - `01-decisions.md` — принципы Р1–Р10; `02-mvp-plan.md` — фазы и приёмка (v3, 09.07); `03-implementation-notes.md` — контракты Фазы 0; `04-unhappy-paths.md` — ~70 режимов отказа → механизм; `06-memory-risk-registry.md` — реестр рисков банка памяти; **[`07-strategic-review.md`](architecture/07-strategic-review.md) — стратегический аудит (09.07): вердикт end-to-end, топ-риски, курс-коррекции**; `components.puml`/`pipeline.puml` — диаграммы v3 (владелец смотрит PlantUML-расширением VS Code; вручную НЕ рендерить). +- `experiments/` — эмпирика «Полигона»: `00-provider-quirks` (читать перед любым вызовом провайдера), `01-token-calibration`, `02-refusal-benchmark`, `03-local-stand`, `04-editor-quality`, `06-local-extraction`, `07-coverage-precision`, `08-cost-model-v2` (актуальная денежная модель), `09-pilot-protocol` (пилот Ф2.5 + поправки D13). +- `research/` — фактура исследований 04–05.07: `01–10` базовые, `11-gap-*` добор критиком, `12-*` режимы отказа/отзывы/таксономии (+ два внешних материала с провенанс-шапками), `13` валидация памяти, `14` адаптивная память. ⚠ Часть под superseded-баннерами (01/02/03/04/05/09 и gap-1/2/5) — **читай баннер прежде содержимого**. +- `PROGRESS.md` — **журнал** (CURRENT-STATE сверху, ниже хронология; НЕ источник решений). +- `archive/` — закрытые сессионные промты (только история, инструкции оттуда не исполнять). -## Статус +## Статус (2026-07-09) -См. [PROGRESS.md](PROGRESS.md). Исследовательская фаза завершена 04.07.2026; **Фаза 0 (каркас) завершена**; машинерия Фазы 1 в основном построена (банк памяти v2, чанкер + txt/epub импорт, disposition/coverage-гейт/эскалация, durable resume, глоссарий→редактор). **Следующий шаг — реальный ja→ru прогон одной книги end-to-end + пилот Ф2.5.** Источник истины по решениям — [architecture/05-decisions-log.md](architecture/05-decisions-log.md). +Фаза 0 ✅ (приёмка на живых ключах). Машинерия Фазы 1 в основном построена: банк памяти v2, чанкер+импорт+ruby, disposition/coverage/эскалация, durable resume, монолингвальный редактор с констрейнтами. Проведено стратегическое ревью (`architecture/07`): архитектура end-to-end цела; до приёмки Ф1 — пакет фиксов D15/D16, status/redrive, дешёвые гейты, ja→ru прогон end-to-end. Решающая точка — пилот Ф2.5 (харнесс чинится до прогона, D13); его блокеры — вебновелл-корпус и explicit-фрагменты от владельца. -## Доступые ключи от моделей -DEEPSEEK_API_KEY -ZAI_API_KEY -KIMI_API_KEY -OPENAI_API_KEY -GEMINI_API_KEY -XAI_API_KEY +## Доступные ключи от моделей +DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..d515d51 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,5 @@ +# Архив + +Закрытые сессионные промты и мёртвые документы. Хранится как история решений/передач — **инструкции отсюда не исполнять**: контракты могли быть переопределены. Актуальные источники истины — `../architecture/05-decisions-log.md` и `../README.md`. + +Правило пополнения: сюда переносится документ, чьи задачи полностью закрыты (промты) или чьё содержимое целиком заменено (мёртвые доки). Частично устаревший research НЕ переносится — получает ⚠ superseded-баннер на месте (ссылки file:line из журнала/архитектуры не ломаем). diff --git a/eval/README.md b/eval/README.md new file mode 100644 index 0000000..49c9805 --- /dev/null +++ b/eval/README.md @@ -0,0 +1,28 @@ +# eval/ — полигон TextMachine + +Зона сессии «Полигон»: эмпирическая валидация допущений архитектуры (мерить, а не верить). Отчёты — `docs/experiments/NN-*.md` (методика + цифры + честные ограничения). `backend/` только читать; расхождения с architecture/research — пингом оркестратору в `docs/PROGRESS.md`. **`.env` не читать; `data/refusal_corpus/*` не открывать без прямой задачи владельца.** + +## Карта + +| Скрипт | Эксперимент | Заметки | +|---|---|---| +| `refusal_bench.py` | exp02; его `split_sentences`/`classify_output` = **приёмочный оракул** coverage-гейта Go (паритет закреплён Go-тестом; любое изменение — Python-first, лок-степ) | `run_refusal.sh` — однокоманда | +| `token_calc.py` | exp01 токен-калибровка (r-множители) | токенизаторы в `tokenizers/` | +| `editor_bench.py` + `build_editor_artifact.py` | exp04 бейк-офф редакторов | ⚠ слепота артефакта была сломана (ключ внутри) — при новых оценках ключ ВНЕ артефакта, рандомизация меток по фрагментам (D13.5) | +| `coverage_precision.py`, `content_filter_probe.py` | exp07 precision гейта (0 FP/57) | | +| `cost_model_v2.py` | exp08 COGS (~$0.69/ранобэ) | цены датировать и перепроверять | +| `extract_bench.py` | exp06 экстракция терминов (спот=локаль/рендер=облако) | health-верификация каждого ответа — образец | +| `retrieval_bench.py` | эмбеддинг-бенч памяти (bge-m3 дефолт) | | +| `pilot/declmetric.py`, `pilot/memory_eval.py` | харнесс пилота Ф2.5 (exp09) | ⚠ чинится ДО решающего прогона: стрип эха глоссария, ПОЛНЫЕ выходы (не [:160]), fidelity-ось, имена M0–M3 (D13.5); инъекция = зеркало `backend/internal/pipeline/memory.go` — при расхождении верить Go | +| `adaptive_*.py` | research/14 пробы (гибрид отклонён) | индикативные, не решения | +| `memory_hotpath.py` | УСТАРЕЛ (контракт до cc57c7b) — не переиспользовать | актуальное зеркало — `pilot/memory_eval.py` | +| `providers.json` | базовые URL/слаги для зондов | квирки — `docs/experiments/00-provider-quirks.md`, читать ПЕРЕД любым вызовом | + +## Правила (выучены на ошибках) + +1. **Провенанс данных:** results-файлы не перезаписывать ре-раном (урок exp02: сырьё 66 вызовов утрачено); каждый прогон — model id + дата + usage; сырые ВЫХОДЫ сохранять целиком. +2. **Претрейн-контаминация:** вся классика (Лу Синь/Акутагава/Уэллс) в претрейне моделей — C0 частично выдаёт канон, эхо систематично (deepseek 13/24 zh-чанков). Выводы на классике = предварительные; решающие замеры — на вебновелл-корпусе владельца. +3. **Тест ставится, только если его исход может перевернуть решение** и не установлен литературой (урок снятого exp05). +4. **LLM-судьи:** ≤2–3 семейства, 11+ повторов со свапом позиций, Bradley-Terry/медиана, судья не судит выходы своего семейства (D13.3); κ против человеческого IAA, не «средняя корреляция». +5. Env: `eval/.venv` (torch-cpu, sentence-transformers, openai, dotenv, pymorphy3); ключи скрипты читают из `eval/.env` сами. Стенд: GTX 1070 8GB — модель полигона `qwen3-abliterated:30b-a3b` в ollama не выселять без нужды; **localhost из-под прокси даёт 403** — для локальных вызовов no-proxy. +6. `data/` в .gitignore (коммитится только код) — критичные результаты дублируй цифрами в `docs/experiments/`.