37 lines
16 KiB
Markdown
37 lines
16 KiB
Markdown
# TextMachine — документация
|
||
|
||
Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы) мультиагентным пайплайном поверх LLM API; **пара языков — данные, не код**, сегодня боевая zh→ru. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, `platform/`, D39.81). Цели и мерило — канон в [../CLAUDE.md](../CLAUDE.md); онбординг сессий — там же. Стартовый бриф владельца: [../START_PROMT.MD](../START_PROMT.MD) — **живой документ**, его V-идеи разобраны в реестр требований (ниже).
|
||
|
||
**Состояние проекта НЕ здесь** — кроме таблицы активных промтов ниже, и это осознанное исключение: она отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (проверено слепым замером входа). Всё остальное состояние — Очередь, курс, бэклог — 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) — реестр «что продукт обязан уметь»: производное живого брифа владельца и его находок, статусы сверены кодом.
|
||
- `architecture/` — синтез и контракты:
|
||
- [05-decisions-log.md](architecture/05-decisions-log.md) — **источник истины по решениям**: ратифицированный контракт, при конфликте побеждает он. Дисциплина чтения (грепать номер, не читать целиком, баннер прежде тела) — в каноне `../CLAUDE.md`, здесь не дублируется. Статус и тело ЛЮБОГО номера одним хопом — реестр [05-decisions-index.md](architecture/05-decisions-index.md) (все ноты, колонка тем для грепа «какой закон по X»).
|
||
- [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/` ОТСТАЛА на `0.2.3` при каноне `0.10.0` (испр. 05.09; ⚠ версию канона брать ФАЙЛОМ — `grep '^ version:' architecture/14-api-contract/openapi.yaml`, число здесь стареет) и зеркалом сегодня НЕ является — зона заморожена, синк при разморозке; читать ТОЛЬКО канон).
|
||
- Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): [15-money-path.md](architecture/15-money-path.md) — деньги от гранта до settle одним маршрутом · [16-events-emitter.md](architecture/16-events-emitter.md) — сборка-норматив эмиттера шва — обязательное пре-чтение перед кодом эмиттера · **[17-seam-inbound-law.md](architecture/17-seam-inbound-law.md) — закон ВХОДНОЙ двери шва движок↔платформа — РАТИФИЦИРОВАН D39.156: семь пунктов дисциплины, двери встают паками без нового решения владельца** · **[18-bank-ontology.md](architecture/18-bank-ontology.md) — онтология банка памяти (РАТИФИЦИРОВАНА D39.158): три роли носителей, единственные писатели, дисциплина проекции — обязательное пре-чтение перед кодом, трогающим банк или его артефакты** · [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; остальные — отчёты экспериментов. ⚠ **У каждого отчёта статус в его ревью-шапке: читай шапку прежде тела** — она первична и говорит, ратифицированы выводы или заморожены.
|
||
- `research/` — фактура ресёрчей; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа · 25 холодное ревью шва — **читать перед любым кодом стыка** · 24 арбитраж банка · 26 официальные практики Anthropic · 28 контракт-ревью API v0 — **носитель для исполняющих сессий, читать оригинал, не пересказ**.
|
||
- [PROGRESS.md](PROGRESS.md) — журнал: CURRENT-STATE + **ЕДИНЫЙ БЭКЛОГ** (единственный трекер) + живой хвост хроники. НЕ источник решений.
|
||
- **Тулчейн на чистой машине.** Версии не здесь — их носители: `backend/Makefile` и `platform/Makefile` (`GO_MIN_VERSION`, `GOLANGCI_VERSION`), `frontend/package.json` (`engines`), `platform/docs/STACK_DECISIONS.md` §«Postgres на стенде без root», `eval/requirements.txt` + `eval/.python-version`. Здесь только то, чего нет нигде: ставим в `~/.local/opt/<инструмент>` с симлинком в `~/.local/bin` (он уже в `PATH`), берём **последний патч пинованного минора, а не следующий минор** — линтер пинован точным равенством и разъедется. Root требуют ровно два пакета: `build-essential` (без C-компилятора нет `-race`, а снять `-race` значит выдать отсутствие тулчейна за зелёный прогон — см. комментарий над целью `test` в `backend/Makefile`) и `python3-venv` (в системном питоне нет `ensurepip`, и установка полигона по `eval/README.md` обрывается на первом шаге).
|
||
- `scripts/counts.py` — **производные числа доков считаются им, а не руками** (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); `--check` даёт ненулевой код на расхождении; `--lint` — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук `scripts/githooks/pre-commit`: **`--lint` якорей — при ЛЮБОМ коммите с непустым индексом, включая коммиты чистого КОДА (гейт по составу снят 21.08: цели якорей живут в коде, и двигает их кодовый коммит; шумовое следствие — строка бэклога 244); `--check` чисел и головы — только при коммите с D-логом или PROGRESS** (оба `--from-index`, предупреждает, не блокирует). ⚠ **Гейт бутстрапится ЧУЖОЙ зоной — это ДЕФЕКТ, а не порядок работы (строка бэклога 220):** судит он `CLAUDE.md` и доки трёх зон, а в `.git/hooks/` его кладёт единственный установщик `frontend/scripts/githooks/install.mjs`, то есть побочный эффект `npm install` в зоне, которая ЗАМОРОЖЕНА. На свежем клоне `.git/hooks/` пуст и гейт молчит, не проверив ничего. Пока строка открыта, бутстрап делается руками (`node frontend/scripts/githooks/install.mjs`) — и это ВРЕМЕННАЯ мера, которую строка 220 закрывает, а не способ жить дальше. ⚠ Шапка систематически отстаёт от хвоста у ЛЮБОГО автора — потому проверка механическая, а не «посмотрю внимательно».
|
||
- **Активные хендофф-промты — какой файл ТВОЙ** (состав обновляется при каждом лендинге, D39.80; хроника, причины и статусы РАБОТ — CURRENT-STATE и D-лог):
|
||
| Роль | Активный промт | Статус |
|
||
|---|---|---|
|
||
| Оркестратор | [ORCHESTRATOR_SESSION_PROMPT.md](ORCHESTRATOR_SESSION_PROMPT.md) | роль и нормы; счётчик роли — CURRENT-STATE |
|
||
| Бэкенд | активного НЕТ | пак «денежный стоп» ОТРАБОТАН и ПРИНЯТ С ДОФИКСОМ 05.09 — акт **D39.206** (`81a89e9` + `616a8e4`), промт в `archive/prompts/` с баннером исхода. Следующая работа зоны — строки **291** (флаг вместо клина, `D39.204`) · **294** (форма «сколько добавить», `D39.203`) · **296** (точечная перегенерация по промаху глоссария, после 295) |
|
||
| Платформа | активного НЕТ | пак «пустить внутрь можно» ОТРАБОТАН и ПРИНЯТ С ДОФИКСОМ 05.09 — акт **D39.201** (`7e2226a` + `3e84716`), промт в `archive/prompts/` с баннером исхода. Следующая работа зоны — строки **293** (невидимый для git файл) · **294** (зеркало словаря под минор потока) |
|
||
| Полигон | [POLYGON_EXP2223_REDO_SESSION_PROMPT.md](POLYGON_EXP2223_REDO_SESSION_PROMPT.md) (отложенный — [POLYGON_PACKAGE4_SESSION_PROMPT.md](POLYGON_PACKAGE4_SESSION_PROMPT.md), строка 85) | фаза Д ИДЁТ; ⚠ живой носитель курса — в `eval/dovodka/`, какой именно называет зона (⚠ [POLYGON_PHASE_D_HANDOFF.md](POLYGON_PHASE_D_HANDOFF.md) — перекрытый снимок, читать не как курс) |
|
||
| Фронт | активного НЕТ | **ЗОНА ЗАМОРОЖЕНА** (D39.136 п.2 + D39.147: разморозка отдельным словом владельца, не привязана к P7); перечень первого касания — в зонном журнале |
|
||
| Контракт | активного НЕТ | канон — `architecture/14-api-contract/`; ⚠ версию брать ФАЙЛОМ (`grep '^ version:' openapi.yaml`), не отсюда: миноры ратифицируются D-нотами и их содержание грепается по реестру нот. |
|
||
|
||
- Чужие зоны — фронт и платформа (читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): [../frontend/](../frontend/) — веб-интерфейс: зонный журнал `docs/frontend-PROGRESS.md` (прогресс зоны только там, D39.100) + промт фронт-сессий + [STACK_DECISIONS.md](../frontend/docs/STACK_DECISIONS.md) (пины версий точными числами и ловушки) + [BACKLOG.md](../frontend/docs/BACKLOG.md) · [../platform/](../platform/) — SaaS control plane: README + [BACKLOG.md](../platform/BACKLOG.md) + `docs/` (зонный журнал `platform-PROGRESS.md` · регистр дефектов · `STACK_DECISIONS.md` с рецептом стенда и инвентарём каналов шва · **[ENGINEERING_STANDARDS.md](../platform/docs/ENGINEERING_STANDARDS.md) — ратифицирован; КАЖДЫЙ промт платформенной сессии обязан на него ссылаться, отступление = пинг** · **[PLATFORM_DIRECTION.md](../platform/docs/PLATFORM_DIRECTION.md) — ратифицированное направление зоны: аутентификация, деньги, стандарты, скорость** · архив промтов).
|
||
- `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), правятся бэкендом одним коммитом с кодом; не рендерить (гардрейл CLAUDE.md).
|
||
|
||
## Ключи провайдеров
|
||
|
||
**Имена** переменных per-провайдер — поле `api_key_env` в `backend/configs/models.yaml` (носитель, который читает КОД, поэтому разойтись с реальностью резолва не может). У полигона свои дополнительные провайдеры — имена в его же скриптах, движковый носитель их не покрывает и не должен. **Наполненность** ключей — `.env` деплоя, его НЕ читать; при сомнении спрашивать владельца. ⚠ Ручной перечень здесь не держим: он уже лгал умолчанием — называл семь имён, когда в ходу было девять.
|