| 1 | # One-pager: протоколы маркеров и сущности KB |
| 2 | |
| 3 | **Версия:** v1 · **2026-05-16** |
| 4 | **Для wiki kb-public:** эту страницу можно зеркалировать как **главный вход** «как пользоваться KB» (рядом с `SHOWCASE.md` и `index-knowledge-router-v1.md`). |
| 5 | **Расширение:** устройство слоёв L0–L3, `work/` / `personal/` — в **`kb-one-pager-structure-and-protocols-v1.md`**. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## За 60 секунд |
| 10 | |
| 11 | | Вопрос | Ответ | |
| 12 | |--------|--------| |
| 13 | | Что писать в чате? | Маркеры **`[HUMAN]`** / **`[WORK]`**, **`[PRIMARY:…]`**, **`[SCOPE:…]`** — см. таблицы ниже. | |
| 14 | | Что важнее? | Маркер в **этом** сообщении → дефолт из карты установки → эвристика по пути файла (не отменяет недавний маркер в треде). | |
| 15 | | Scope vs Primary? | **SCOPE** — «в какой вселенной workspace»; **PRIMARY** — «какой продукт в фокусе». | |
| 16 | | Где полный текст? | `worlds/workspace-context/playbook-multi-project-context-v1.md`; hot `agent-notes.md` (секции протоколов — в полном каноне, часто под `<!-- public-cut -->`). | |
| 17 | |
| 18 | --- |
| 19 | |
| 20 | ## Маркеры в сообщениях (шпаргалка) |
| 21 | |
| 22 | ### Режим треда: `[HUMAN]` и `[WORK]` |
| 23 | |
| 24 | | Маркер | Когда | Что делает агент | По умолчанию | |
| 25 | |--------|--------|------------------|--------------| |
| 26 | | **`[HUMAN]`** | рефлексия, личное, эмоции, смысл, «поговорить» | не уходит в операционные runbook без запроса; уважает personal-контур | **да**, пока не появился `[WORK]` | |
| 27 | | **`[WORK]`** | задача, код, KB, runbook, «сделай», проверка, публикация | исполнение, инструменты, карточки проектов, чеклисты | после явного `[WORK]` в треде | |
| 28 | |
| 29 | **Правило:** один тред — один устойчивый режим, пока не переключили маркером или явной фразой («переходим в work»). |
| 30 | |
| 31 | **Полный текст:** [`domains/agent-operations/playbook-mode-switch-v1.md`](domains/agent-operations/playbook-mode-switch-v1.md). Hot stub: секция `mode-switch-protocol` в `agent-notes.md`. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ### Фокус задачи: `[PRIMARY:…]` и `[SCOPE:…]` |
| 36 | |
| 37 | | Маркер | Когда | Что задаёт | Пример | |
| 38 | |--------|--------|------------|--------| |
| 39 | | **`[PRIMARY:<id>]`** | один главный продукт/репо в фокусе **этого** треда | карточка `project-id`, пути в `work/projects/…`, техконтракт продукта | `[PRIMARY:cascade-ide]` или `[PRIMARY:CIDE]` | |
| 40 | | **`[SCOPE:<slice>]`** | на машине несколько корней workspace; нужен правильный **L1** hot-context | `active_scope` в MCP, scope-хаб в hot | `[SCOPE:door-to-singularity]` или `[SCOPE:DTS]` | |
| 41 | |
| 42 | **Не путать:** |
| 43 | |
| 44 | - **`[PRIMARY:EDWH]`** → репозиторий Harvester (`edw-harvester`). |
| 45 | - **`[SCOPE:HRV]`** → slice `harvester` (память L1), не то же самое, что PRIMARY. |
| 46 | |
| 47 | **Алиасы** (опционально): короткие коды в чате нормализуются к канону — см. таблицу ниже. В долговечные записи в `knowledge/` пиши **канонический** `project-id` / scope. |
| 48 | |
| 49 | **Приоритет резолва:** |
| 50 | |
| 51 | 1. Маркер в текущем сообщении (`[PRIMARY:…]`, `[SCOPE:…]`). |
| 52 | 2. Дефолт из **`workspace-scope-map-v1`** (в hot `agent-notes.md` у владельца канона). |
| 53 | 3. Эвристика по пути к файлу в чате — **не** должна молча перебивать маркер из шага 1 в том же треде. |
| 54 | |
| 55 | **Полный протокол:** `project-switch-protocol-v1` в hot `agent-notes.md`; развёрнуто — `playbook-multi-project-context-v1.md` §6–6c. |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## Сущности: что есть что (схема) |
| 60 | |
| 61 | Термины **не взаимозаменяемы**. |
| 62 | |
| 63 | ```mermaid |
| 64 | flowchart TB |
| 65 | subgraph machine["Машина пользователя"] |
| 66 | WP["workspace_path<br/>(корень в Cursor / MCP)"] |
| 67 | MAP["workspace-scope-map-v1<br/>путь → slice"] |
| 68 | WP --> MAP |
| 69 | end |
| 70 | |
| 71 | subgraph slice["Scope (L1 slice)"] |
| 72 | SC["active_scope / [SCOPE:…]<br/>напр. door-to-singularity, portal, harvester"] |
| 73 | HUB["work/projects/<scope>/<br/>хаб карточек"] |
| 74 | SC --> HUB |
| 75 | end |
| 76 | |
| 77 | subgraph focus["Фокус треда"] |
| 78 | PR["[PRIMARY:project-id]<br/>один продукт"] |
| 79 | CARD["work/projects/<scope>/<project-id>/<br/>README, kb, runbook"] |
| 80 | PR --> CARD |
| 81 | end |
| 82 | |
| 83 | subgraph thread["Тред чата"] |
| 84 | MODE["[HUMAN] | [WORK]"] |
| 85 | end |
| 86 | |
| 87 | MAP --> SC |
| 88 | HUB --> CARD |
| 89 | MODE -.-> PR |
| 90 | MODE -.-> SC |
| 91 | ``` |
| 92 | |
| 93 | **Кратко:** |
| 94 | |
| 95 | | Сущность | Уровень | Зачем | |
| 96 | |----------|---------|--------| |
| 97 | | **workspace_path** | MCP / Cursor | физический корень репозитория на диске | |
| 98 | | **scope** (`active_scope`) | L1 оперативки | не смешивать monorepo DTS и отдельный корень Portal | |
| 99 | | **project-id** + **PRIMARY** | фокус задачи | одна карточка продукта, один техконтракт | |
| 100 | | **world** (KE) | домен роутера | стек/инструменты (Git, HCI, …) — **не** scope | |
| 101 | | **domain** (роутер) | тема запроса | какой playbook/kb подтянуть по словам задачи | |
| 102 | |
| 103 | **Mixed worlds / transfer_boundary:** `worlds/knowledge-engineering/kb-knowledge-engineering-mixed-worlds-rules-v1.md`. |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | ## Типовые scope и project-id (установка автора канона) |
| 108 | |
| 109 | Значения **не глобальный стандарт** — у каждой установки свой список. Ниже — **пример** для workspace «Door to Singularity» (имена из публичного плейбука и quickref; полные пути к карточкам — в полном каноне под `work/`, в kb-public **нет**). |
| 110 | |
| 111 | ### Scope (`[SCOPE:…]` → канон) |
| 112 | |
| 113 | | Маркер / legacy | Канонический scope | Когда выбирать | |
| 114 | |-----------------|-------------------|----------------| |
| 115 | | `DTS`, `current-projects` | `door-to-singularity` | домашний monorepo, open stack, DTS-хаб | |
| 116 | | `PTL` | `portal` | отдельный корень / линия Portal | |
| 117 | | `HRV` | `harvester` | EDW Harvester, не Portal | |
| 118 | | `mixed` | `mixed` | явно несколько slice в одной сессии | |
| 119 | |
| 120 | ### Primary — частые `project-id` (door-to-singularity) |
| 121 | |
| 122 | | `[PRIMARY:…]` | Канон | Зачем | |
| 123 | |-------------|-------|--------| |
| 124 | | `CIDE` | `cascade-ide` | IDE Avalonia | |
| 125 | | `ANKB` | `agent-notes-kb` | канон KB, META, публикация | |
| 126 | | `ANM` | `agent-notes-mcp` | MCP agent-notes | |
| 127 | | `DTS` | `door-to-singularity` | хаб workspace (не отдельный продукт) | |
| 128 | | `FB` | `friction-book` | книга Friction | |
| 129 | | `AFG` | `agent-forge` | vision forge (репо может отсутствовать) | |
| 130 | |
| 131 | Полная таблица алиасов: в полном каноне `work/projects/door-to-singularity/door-to-singularity/project-ids-quickref-v1.md` (в kb-public не входит). |
| 132 | |
| 133 | --- |
| 134 | |
| 135 | ## Инструменты MCP (не маркеры чата) |
| 136 | |
| 137 | | Инструмент / параметр | Когда | Заметка | |
| 138 | |----------------------|--------|---------| |
| 139 | | **`read_hot_context`** | старт сессии, смена scope | L0/L1 срез без всего `knowledge/` | |
| 140 | | **`route_context(query)`** | «что грузить по теме» | router-first; не full load KB | |
| 141 | | **`read_knowledge_file`** | нужен конкретный playbook/kb | путь относительно `knowledge/` | |
| 142 | | **`active_scope`** | явно задать slice для MCP | альтернатива `[SCOPE:…]` в чате | |
| 143 | | **`knowledge_root_id=group`** | чтение **`{ORG_SLUG}/kb`** (private) | read-only; см. `playbook-org-kb-white-label-v1.md` | |
| 144 | | **`knowledge_root_id=public`** | чтение kb-public | read-only | |
| 145 | | **запись** | только **primary** (personal) | [ADR 012](adr/012-multi-canon-workspace-resolution-v1.md) | |
| 146 | |
| 147 | --- |
| 148 | |
| 149 | ## Когда что использовать (дерево решений) |
| 150 | |
| 151 | ```mermaid |
| 152 | flowchart TD |
| 153 | START([Новое сообщение / задача]) |
| 154 | START --> MODE{Нужен режим?} |
| 155 | MODE -->|личное, смысл| HUMAN["[HUMAN]"] |
| 156 | MODE -->|делать, код, runbook| WORK["[WORK]"] |
| 157 | MODE -->|уже ясно из треда| SKIP1[без смены режима] |
| 158 | |
| 159 | WORK --> MULTI{Несколько корней<br/>на машине?} |
| 160 | MULTI -->|да| SCOPE["[SCOPE:…] или active_scope"] |
| 161 | MULTI -->|нет| SKIP2[scope из карты] |
| 162 | |
| 163 | SCOPE --> PROD{Один продукт<br/>в фокусе?} |
| 164 | SKIP2 --> PROD |
| 165 | PROD -->|да| PRIMARY["[PRIMARY:project-id]"] |
| 166 | PROD -->|неясно| ASK[один вопрос или пометка в заметках] |
| 167 | |
| 168 | PRIMARY --> ROUTE["route_context / playbook / карточка"] |
| 169 | ``` |
| 170 | |
| 171 | --- |
| 172 | |
| 173 | ## Связь с контурами организации |
| 174 | |
| 175 | | Контур | Роль | Этот one-pager | |
| 176 | |--------|------|----------------| |
| 177 | | **kb-public** (`{ORG_SLUG}/kb-public`) | публичные playbook, роутер, этот файл | да | |
| 178 | | **group KB** (`{ORG_SLUG}/kb`, private) | командный канон | чтение `knowledge_root_id=group`; white-label: `playbook-org-kb-white-label-v1.md` | |
| 179 | | **handbook** (опционально) | миссия, ценности org | не маркеры KB | |
| 180 | | **personal** | личный канон участника | маркеры чата, `work/local/` | |
| 181 | |
| 182 | --- |
| 183 | |
| 184 | ## Куда дальше |
| 185 | |
| 186 | | Нужно | Файл | |
| 187 | |--------|------| |
| 188 | | Анти-OOM обзор KB | `SHOWCASE.md` | |
| 189 | | Роутер по темам | `index-knowledge-router-v1.md` | |
| 190 | | Мультипроект, куда писать заметки | `worlds/workspace-context/playbook-multi-project-context-v1.md` | |
| 191 | | Слои L0–L3, публикация | `kb-one-pager-structure-and-protocols-v1.md` | |
| 192 | | Целостность | `META/integrity-core.md` | |
| 193 | | Multi-canon (личный + org) | `adr/012-multi-canon-workspace-resolution-v1.md` | |
| 194 | |
| 195 | |