27 lines
16 KiB
Markdown
27 lines
16 KiB
Markdown
# TextMachine — документация
|
||
|
||
Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) мультиагентным пайплайном поверх LLM API. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, `platform/`, D39.81). Цели и мерило — канон в [../CLAUDE.md](../CLAUDE.md); онбординг сессий — там же. Стартовый бриф владельца: [../START_PROMT.MD](../START_PROMT.MD) — **живой документ**, его V-идеи разобраны в реестр требований (ниже).
|
||
|
||
**Состояние проекта НЕ здесь** — кроме одной строки ниже, и это осознанное исключение: строка «активные промты» отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (нашёл слепой онбординг-замер 08.08). Всё остальное состояние — Очередь, курс, бэклог — CURRENT-STATE в шапке [PROGRESS.md](PROGRESS.md); решения — [architecture/05-decisions-log.md](architecture/05-decisions-log.md) (при конфликте с любым доком побеждает он). Эта страница — только карта «что где лежит».
|
||
|
||
## Карта
|
||
|
||
- [glossary.md](glossary.md) — жаргон и сокращения (D-номер, паки, банк, голден, K/DC/H/L…) одним экраном.
|
||
- [product-requirements.md](product-requirements.md) — реестр «что продукт обязан уметь»: START_PROMT V0–V5 + находки H6–H18, статусы сверены кодом.
|
||
- `architecture/` — синтез и контракты:
|
||
- [05-decisions-log.md](architecture/05-decisions-log.md) — **источник истины по решениям**. Живой файл после диеты D39.125 и подрезки D39.139: карта + эрраты + живые тела + голова D39.124+; тела закрытых эр — слайсы `archive/architecture/05-decisions-*.md`. Грепай номер сначала в живом, затем в слайсах (тело ноты = строка `^## D<номер>`, прочие хиты — упоминания); целиком не читать. **Статус/суть/тело ЛЮБОГО номера одним хопом — реестр [05-decisions-index.md](architecture/05-decisions-index.md)** (все ноты, колонка тем для грепа «какой закон по X»; D39.126).
|
||
- [09-target-architecture.md](architecture/09-target-architecture.md) — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · [10-prompt-architecture.md](architecture/10-prompt-architecture.md) — промпт-слой · [12-go-style-notes.md](architecture/12-go-style-notes.md) — норматив общности §0 · [13-tech-debt-anchors.md](architecture/13-tech-debt-anchors.md) — якоря техдолга + археология выселенных строк бэклога §Б-* (справочник к бэклогу, НЕ трекер) · [14-api-contract/](architecture/14-api-contract/) — **контракт API v0 фронт↔платформа (D39.99)**: нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README (провенанс ✓/◆/○, К-вопросы; зонная копия `frontend/docs/api-contract/` — байт-зеркало, сверять при лендинге).
|
||
- Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): [15-money-path.md](architecture/15-money-path.md) — деньги от гранта до settle одним маршрутом · [16-events-emitter.md](architecture/16-events-emitter.md) — сборка-норматив эмиттера шва (обязательное пре-чтение сессии строки 103) · **[17-seam-inbound-law.md](architecture/17-seam-inbound-law.md) — закон ВХОДНОЙ двери шва движок↔платформа (⚠ ПРЕДЛОЖЕНО, НЕ РАТИФИЦИРОВАНО: до слова владельца это записка, ссылаться как на норму нельзя; исходящее направление ратифицировано, входное — нет)** · [STACK.md](STACK.md) — карта «роль → модель → конфиг → квирки».
|
||
- Исторические, читать через ⚠-баннеры: [01-decisions.md](architecture/01-decisions.md) (Р1–Р10) · [02-mvp-plan.md](architecture/02-mvp-plan.md) · [03-implementation-notes.md](architecture/03-implementation-notes.md) · [04-unhappy-paths.md](architecture/04-unhappy-paths.md) · [06-memory-risk-registry.md](architecture/06-memory-risk-registry.md).
|
||
- `experiments/` — эмпирика полигона: [00-provider-quirks.md](experiments/00-provider-quirks.md) — **читать перед любым вызовом провайдера**; [08-cost-model-v2.md](experiments/08-cost-model-v2.md) — денежная модель; [09-pilot-protocol.md](experiments/09-pilot-protocol.md) — пилот Ф2.5; остальные 01–21 — отчёты ЗАКРЫТЫХ экспериментов (21 принят D39.117); ⚠ 22/23 — залендены с ревью-шапками приёмки №16 (10.08), НЕ ратифицированы: выводы заморожены до фазы Д (шапка первична; 18–20 — с ревью-шапками приёмки D39.108).
|
||
- `research/` — фактура ресёрчей 01–28; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа (транспорт superseded D39.106) · 25 холодное ревью шва — форма D39.106, отвергнутые альтернативы, требования к эмиттеру (читать перед любым кодом стыка) · 24 арбитраж банка (ПРИНЯТ D39.102: консилиум закрыт классом, вход фикс-пака банка — §G) · 26 официальные практики Anthropic (D39.121: записка-план, сниппеты хендоффов, карта «уже делаем/перенять») · **28 контракт-ревью API v0 (ПРИНЯТ D39.138: решения владельца 16.08 — §8, состав батча 0.3.0 — §5; НОСИТЕЛЬ для исполняющих сессий, читать оригинал, не пересказ)**.
|
||
- [PROGRESS.md](PROGRESS.md) — журнал: CURRENT-STATE + **ЕДИНЫЙ БЭКЛОГ** (единственный трекер) + живой хвост хроники. НЕ источник решений.
|
||
- `scripts/counts.py` — **производные числа доков считаются им, а не руками** (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); `--check` даёт ненулевой код на расхождении; `--lint` — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук `scripts/githooks/pre-commit`: **`--lint` якорей — при коммите, задевающем ЛЮБОЙ док или `CLAUDE.md`; `--check` чисел и головы — при коммите с D-логом или PROGRESS** (оба `--from-index`, предупреждает, не блокирует; вплетение линта — ревизия D39.148). Заведено по D39.112 п.5б: голова отставала трижды у трёх разных оркестраторов.
|
||
- Активные хендофф-промты сессий (состав обновляется при каждом лендинге — норма D39.80): [ORCHESTRATOR_SESSION_PROMPT.md](ORCHESTRATOR_SESSION_PROMPT.md) (роль/нормы; состояния не дублирует; ⚠ счётчик роли — **№19** с 22.08, передача и разбор смены №18 — D39.155) · **Контракт: активного промта НЕТ — канон стоит на 0.4.0, РАТИФИЦИРОВАН 20.08 (D39.152)**; батч 0.3.0 отработан целиком (D39.142+D39.143), промт в `archive/prompts/`, отчёт — `archive/reports/CONTRACT_BATCH_0.3.0_REPORT.md`; синк 0.4.0 сделан ОТДЕЛЬНОЙ контрактной сессией по записке зоны платформы (`platform/docs/archive/CONTRACT_SYNC_FROM_PLATFORM_2026-08-20.md`, разбор — §6в компаньона), следующий минор — сквозная полоса прогресса, строка 200 · **Полигон: [POLYGON_EXP2223_REDO_SESSION_PROMPT.md](POLYGON_EXP2223_REDO_SESSION_PROMPT.md)** — фаза Д доводки эксп-22/23 ИДЁТ (заказ владельца 10.08; потолки фазы поднимал владелец напрямую — числа в CURRENT-STATE; выводы 22/23 заморожены до неё), ⚠ [POLYGON_PHASE_D_HANDOFF.md](POLYGON_PHASE_D_HANDOFF.md) — СНИМОК на 15.08, перекрытый зоной: живой носитель курса фазы живёт в `eval/dovodka/` (цепь планов 16.08→22.08), какой именно — называет зона; баннер с перечнем опровержений стоит в шапке файла (22.08) · [POLYGON_PACKAGE4_SESSION_PROMPT.md](POLYGON_PACKAGE4_SESSION_PROMPT.md) (отложен). **Фронт: ЗОНА ЗАМОРОЖЕНА (D39.136 п.2)** — S4 ИСПОЛНЕН и ПРИНЯТ (D39.135, лендинг `267aa35`; контракт 0.2.3 в каноне; промт в `frontend/docs/archive/`); ⚠ **разморозка БОЛЬШЕ НЕ привязана к P7** — слово владельца 17.08 (D39.147): зона морозится дальше лендинга P7, S5-промт не выдаётся, курс — движок и платформа до «работает и отдаёт результат»; разморозка отдельным словом. Перечень первого касания (синк зеркала на ТЕКУЩИЙ канон — версия к моменту разморозки, не «0.3.0» · типы · моки · гейт утечки · ФС-1..12 · Ф-63/Ф-28 · фразы В-11 по словарю кодов; ~~В-10~~ закрыт «вежливость») не отменён, ждёт разморозки; живой smoke против дев-стенда легитимен и во фризе; фикс-лист ФС — запись приёмки 15.08 в зонном журнале · **Платформа: активный промт — [PLATFORM_P8_REVIEW_SESSION_PROMPT.md](../platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md)** (read-only ревью четырёх осей: деньги и леджер · вход/сессии/CSRF · очередь и джобы · метрики; запуск по слову владельца; шапка несёт дельту после P8-FIX — ось 2 не тронута ничем, оси 1 и 4 задеты точечно). Прожито: P6 + дофикс (D39.132) · **P7 — пять актов, ПРИНЯТ С ФИКС-ЛИСТОМ, ЗАЛЕНДЕН, сессия закрыта владельцем 20.08** (D39.153) · **P8-FIX — фикс-лист P7 плюс блокер свипа, ПРИНЯТ и ЗАЛЕНДЕН 22.08** (D39.154, лендинг `31f1f82`: голодание свипа закрыто четырьмя механизмами, снят пер-термный write-путь банка). Все отработанные промты — `platform/docs/archive/`. Дальше по очереди: ревью-пак → живой прогон книги насквозь (гейт — холодный прогон движка, строка 202) · **Бэкенд: активного промта НЕТ** — пак «честные числа и статусы» ИСПОЛНЕН и ПРИНЯТ С ФИКС-ЛИСТОМ (D39.149, лендинг `f840867`; промт с баннером-исходом — `archive/prompts/BACKEND_HONESTY_PACK_SESSION_PROMPT_2026-08-17.md`); остаток — фикс-лист ФЧ-1…ФЧ-8 строкой бэклога **197**, носителя-сессии пока нет по слову владельца** (оба рубежа D39.141 закрыты: механическая сверка 11/11 блоков + ДВА прохода опровергателя другой моделью + узкая сверка вливания находок; первый проход сам принёс ошибку атрибуции — она вскрыта автором и подтверждена вторым проходом) (пак «честные числа и статусы»: строки 176 · 181 · 172-г · 187; п.5 живой вахты весов исполняется ТОЛЬКО при названной владельцем сумме) — ранее: пере-пин цен DeepSeek ИСПОЛНЕН и ПРИНЯТ (D39.137, лендинг `76049bb`; промт в `archive/prompts/`), потолки снова защищают; `tmctl migrate` — D39.134 (`d55edd4`), деплой эмиттер-бинаря разблокирован. Эмиттер шва ИСПОЛНЕН и ПРИНЯТ (D39.131, промт в архиве). Все ОТРАБОТАННЫЕ промты — в `archive/prompts/`, отчёты с ревью-шапками — в `archive/reports/`; статусы паков — CURRENT-STATE и D-лог, здесь не дублируются. Зонные журналы фронта/платформы — `frontend-PROGRESS.md` / `platform-PROGRESS.md` в их зонах (прогресс зон только там, D39.100).
|
||
- Зоны фронта (чужие, читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): [../frontend/](../frontend/) — веб-интерфейс: промт фронт-сессий S0–S7 + [STACK_DECISIONS.md](../frontend/docs/STACK_DECISIONS.md) (пины версий точными числами и ловушки, сверены с вебом 02.08) + [BACKLOG.md](../frontend/docs/BACKLOG.md) · [../platform/](../platform/) — SaaS control plane: README + [BACKLOG.md](../platform/BACKLOG.md) (П-1..П-21) + `docs/` (зонный журнал `platform-PROGRESS.md` · регистр дефектов · `STACK_DECISIONS.md` с рецептом стенда и инвентарём каналов шва · архив промтов P0–P8).
|
||
- `archive/` — история ([правила архива](archive/README.md)): закрытые промты (`prompts/`) · отчёты с ревью-шапками (`reports/` — на них ссылаются приёмки) · исполненные арх-доки (`architecture/`) · слайсы хроники `PROGRESS-*.md`. Инструкции оттуда не исполнять.
|
||
- Диаграммы: [../backend/docs/components.puml](../backend/docs/components.puml) · [../backend/docs/pipeline.puml](../backend/docs/pipeline.puml) — дом рядом с кодом (D39.80), правятся бэкендом одним коммитом с кодом; вручную НЕ рендерить (владелец смотрит PlantUML-расширением VS Code).
|
||
|
||
## Доступные ключи от моделей
|
||
|
||
DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY
|