okf-notebooks

Свои пресеты типов

У ваших блокнотов свой словарь типов заметок (ADR, Runbook, Incident…)

Пресет — это YAML-файл с набором типов. Блокнот при создании выбирает пресет (--preset) и получает его типы. Встроенный пресет один: core (Project, Decision, Playbook, Term). Его нельзя переопределить.

В репозитории в presets/ лежат три пресета: dev-project, personal-finance и agent-retros. Это примеры, а не стандарт. Формат базы знаний вы выбираете сами: возьмите пресет как есть, поправьте его, напишите свой с нуля или попросите агента придумать формат под вашу задачу.

1. Создайте каталог и укажите его в конфиге 

# config.yaml
presets_dir: ./presets

Каталог читается при каждом обращении, перезапускать сервер не нужно. Подхватываются файлы *.yaml / *.yml.

2. Опишите пресет

presets/ops.yaml:

name: ops                       # необязательно: по умолчанию имя файла без расширения
description: Эксплуатация: инциденты, runbook-и, решения
types:
  - name: Incident
    description: Разбор инцидента: хронология, причина, действия
    dir: incidents              # подкаталог; по умолчанию имя типа во множественном числе (slug)
    fields: [description, tags, sources, stale_after, severity]
    required: [severity]        # поля, без которых запись отклоняется
    stale_after: 365d
  - name: Runbook
    description: Пошаговая инструкция для дежурного
    dir: runbooks
    fields: [description, tags, sources, stale_after]
    stale_after: 90d
  - name: Decision
    description: Принятое решение и рассмотренные альтернативы

description пресета — это ответ на вопрос «для чего он подходит». Агент видит его в инструменте presets_list и по нему выбирает пресет для notebook_create, поэтому пишите в нём, для каких блокнотов пресет годится и для каких нет («Подходит для … Не для …»). Без описания агент увидит только имя и типы.

Допустимые формы записи types: список имён (- Decision), список словарей (как выше) или словарь Имя: {…}. Поля required и stale_after можно вынести во вложенный template:.

Правила:

  • у типа обязательно описание (для блокнотов, созданных с types: напрямую);
  • имена типов и каталоги в пресете не должны совпадать (два типа в одном каталоге — ошибка);
  • в блокноте не больше 12 типов;
  • stale_after — срок вида 90d; если он некорректен, пресет пропускается целиком, в лог идёт предупреждение;
  • битый или пустой YAML тоже пропускается, остальные пресеты остаются доступными.

3. Создайте блокнот из пресета 

uv run okf-notebooks notebook create runbooks \
  --description "Эксплуатационные заметки: инциденты, runbook-и и решения по продакшену" \
  --scope "Устойчивые знания об эксплуатации; не писать черновики разборов" \
  --preset ops

Агент через MCP делает то же: смотрит доступные пресеты через presets_list, затем notebook_create с preset: "ops" (при политике proposal создание пойдёт в очередь на одобрение — см. жизненный цикл).

Описание — 40–300 символов, scope обязателен: по нему агент выбирает блокнот.

Попросите агента придумать формат

Писать типы самому не обязательно. Расскажите агенту, что хотите хранить и как будете этим пользоваться, и попросите предложить формат, например:

Хочу блокнот для чтения: книги, заметки по главам, цитаты и идеи, к которым хочу вернуться. Предложи типы заметок с полями и обязательными полями, покажи мне, потом подай заявку на блокнот.

Агент смотрит существующие пресеты через presets_list и вызывает notebook_create со своими types (до 12) и rationale. При политике proposal по умолчанию заявка ждёт вас: её показывает okf-notebooks notebook pending, предложенные типы лежат в _proposed/<slug>/.okf/notebook.yaml, а вы одобряете или отклоняете её (жизненный цикл). Позже агент может запросить ещё один тип через notebook_type_define. Если формат прижился и нужен для других блокнотов, сохраните его файлом пресета.

Типы без пресета

Одноразовый набор типов можно передать файлом (--preset и --types-file вместе не указываются):

uv run okf-notebooks notebook create demo --description "…" --scope "…" --types-file types.yaml

types.yaml — список типов в том же формате, что и в пресете.

Что происходит с блокнотом при изменении пресета

В notebook.yaml блокнота сохраняются имена типов и ссылка на пресет. Описание, поля и stale_after, которые блокнот не задал сам, подтягиваются из пресета при чтении. Правка пресета меняет эти значения в уже созданных блокнотах; набор типов блокнота она не меняет. Добавление и переименование типов в существующем блокноте — через notebook_type_define и okf-notebooks type ….