Перейти к содержимому

Notes

Notes обеспечивают персистентное key-value хранилище, привязанное к каждому пользователю. Данные, сохранённые в notes, переживают перезапуски workflow, позволяя хранить настройки, накапливать результаты и организовывать конвейеры данных между workflow.

Сценарии использования

  • Пользовательские настройки: Хранение стиля коммитов, предпочтительного региона, соглашений по коду
  • Накопление данных: Результаты еженедельного анализа для сравнения во времени
  • Межпроцессные конвейеры: Workflow-коллектор сохраняет данные, workflow-репортёр их читает
  • Непрерывность сессии: Промежуточные результаты переживают архивирование сессии

MCP Tool

MCP tool notes предоставляет следующие действия для доступа агентов:

notes({ action: "save", key: "commit-style", value: "conventional", tags: ["preferences"] })
notes({ action: "get", key: "commit-style" })
notes({ action: "list", tag: "preferences" })
notes({ action: "history", key: "commit-style" })
notes({ action: "delete", key: "commit-style" })
notes({ action: "stats" })
ДействиеНазначение
saveСоздание или обновление note
getЧтение содержимого note по ключу
listСтраница notes с фильтрами по тегам/ключам
historyПросмотр истории версий note
deleteМягкое удаление note
statsСтатистика использования и информация о квоте

Формат ключа

Ключи принимают буквенно-цифровые символы, подчёркивание и дефис. Длина: 1-100 символов.

my-config # допустимо
project_settings # допустимо
2024-report # допустимо

Лимиты и пагинация

Ограничения размера одной note, общего хранилища и числа сохраняемых версий задаются действующей политикой сервера. Вызов notes({ action: "stats" }) возвращает текущий общий лимит и его использование; отклонённая запись сообщает применённую границу размера или квоты. Фиксированные ограничения синтаксиса ключей и тегов доступны в MCP-схеме и ошибках валидации.

list возвращает страницу, а не всю коллекцию. Используйте limit и offset и сравнивайте полученные notes с total, чтобы определить, нужна ли следующая страница.

Список и история содержат короткие превью, а не полный текст note. Действие get читает текущее значение; параметр version выбирает конкретную версию. Открытие версии в веб-интерфейсе также загружает полный текст. Сокращённое превью не означает, что сохранённое значение обрезано.

Автоматические типы нод

Три типа нод выполняют операции с notes без участия агента. Они выполняются на сервере и автоматически переходят к следующей ноде.

Примеры — фрагменты объявлений. Определите целевые узлы connections и производящие agent-узлы в содержащем графе. Короткие имена шаблонов projectName, date, analysisData и metricsData требуют объявленных и заранее записанных глобалов реестра; локальные значения читаются через node-id.field.

read-note

Читает notes, соответствующие критериям фильтра, в контекстную переменную:

{
"type": "read-note",
"id": "load-metrics",
"outputVariable": "metricsNotes",
"filter": {
"tag": "metrics",
"keyPattern": "metrics-"
},
"connections": {
"default": "process-data",
"error": "no-data-handler"
}
}
СвойствоОбязательноОписание
outputVariableДаКонтекстная переменная для результатов
filter.tagНетФильтрация по точному тегу
filter.keyPatternНетПоиск в ключе по вхождению, не гарантия префикса
filter.keySearchНетПоиск в ключе (содержит)
singleModeНетОбъект только при одном результате в возвращённой странице; иначе массив
connections.errorНетНода обработки ошибок

Результат чтения выше локален: используйте {{load-metrics.metricsNotes}}, а не {{metricsNotes}}. Автоматический узел читает одну страницу стандартного размера, не неограниченную коллекцию. Для полного чтения большой коллекции используйте страницы MCP notes list.

write-note

Записывает данные из контекста в note:

{
"type": "write-note",
"id": "save-results",
"key": "results-{{projectName}}-{{date}}",
"source": "{{analysisData}}",
"tags": ["analysis", "{{projectName}}"],
"connections": {
"default": "next-step"
}
}
СвойствоОбязательноОписание
keyНет*Ключ note (обязателен в single режиме)
sourceДаКонтекстная переменная или шаблон со значением
tagsНетНазначаемые теги
batchModeНетОбработка массива [{key, value, tags}]

Когда source разрешается в объект или массив, значение автоматически сериализуется в JSON-строку. Строки передаются без изменений, числа и булевы значения преобразуются в строковое представление.

В batch mode source — сырой путь контекста, например collect-items.items, а не {{collect-items.items}}.

upsert-note

Находит существующую note по критериям поиска или создаёт новую:

Поиск выбирает первую подходящую заметку, а не доказывает её уникальность. Используйте достаточно точную схему ключей/тегов: общий для нескольких проектов тег не задаёт identity проекта.

{
"type": "upsert-note",
"id": "update-latest",
"search": { "tag": "latest-metrics-{{projectName}}" },
"keyTemplate": "latest-metrics-{{projectName}}",
"value": "{{metricsData}}",
"tags": ["metrics", "latest-metrics-{{projectName}}"],
"connections": {
"default": "next-step"
}
}
СвойствоОбязательноОписание
search.tagНетПоиск по тегу
search.keyPatternНетПоиск внутри ключа
keyTemplateДаКлюч для новой note, если не найдена
valueДаКонтекстная переменная со значением note
tagsНетНазначаемые теги
outputVariableНетСохранение результата upsert в контексте

Когда value разрешается в объект или массив, значение автоматически сериализуется в JSON-строку.

Все параметры фильтров, ключей и тегов поддерживают шаблонные выражения {"{{variable}}"}, которые разрешаются из контекста выполнения.

Синтаксис шаблонов

Ссылайтесь на содержимое notes в полях directive и completionCondition, используя синтаксис {{note:KEY}}:

Analyze the project using this configuration: {{note:project-config}}

Содержимое note инжектируется до того, как агент увидит директиву. Отсутствующие notes выдают [NOTE NOT FOUND: KEY].

Шаблонные переменные внутри содержимого note разрешаются после инжекции:

// Note "greeting" содержит: "Hello, {{userName}}!"
// Директива: {{note:greeting}}
// Агент видит: "Hello, Alice!" (когда userName="Alice")

Руководство: межпроцессный конвейер данных

Этот пример показывает два workflow, взаимодействующих через Notes: Коллектор сохраняет метрики проекта, Репортёр их читает и анализирует.

Workflow 1: Коллектор метрик

Собирает метрики и сохраняет их как notes:

flowchart LR
    A[start] --> B[gather-metrics]
    B --> C[write-note]
    C --> D[upsert-note]
    D --> E[confirm-saved]
    E --> F[end]

Ключевые ноды:

write-note сохраняет сырые метрики с ключом, содержащим временную метку. Поле source ссылается на вывод агента через dot-path синтаксис — объекты и массивы автоматически сериализуются в JSON:

{
"type": "write-note",
"id": "write-metrics-note",
"key": "metrics-{{gather-metrics.projectName}}-{{gather-metrics.collectionDate}}",
"source": "{{gather-metrics.metrics}}",
"tags": ["metrics", "{{gather-metrics.projectName}}", "raw-data"]
}

upsert-note поддерживает ссылку на «последнюю» версию:

{
"type": "upsert-note",
"id": "upsert-latest-summary",
"search": { "tag": "latest-metrics-{{gather-metrics.projectName}}" },
"keyTemplate": "latest-metrics-{{gather-metrics.projectName}}",
"value": "{{gather-metrics.metrics}}",
"tags": [
"metrics",
"{{gather-metrics.projectName}}",
"latest-metrics-{{gather-metrics.projectName}}"
]
}

Workflow 2: Репортёр метрик

Читает сохранённые метрики и генерирует отчёт:

flowchart LR
    A[start] --> B[ask-project]
    B --> C[read-note]
    C --> D[generate-report]
    D --> E[end]
    C -->|error| F[no-data]
    F --> G[end-no-data]

read-note загружает страницу метрик по тегу и поиску в ключе:

{
"type": "read-note",
"id": "load-all-metrics",
"outputVariable": "metricsNotes",
"filter": {
"tag": "metrics",
"keyPattern": "metrics-"
}
}

Директива отчёта использует {{note:KEY}} для инжекции последнего снимка. Dot-path синтаксис ссылается на вывод агента из предыдущих нод:

Generate a metrics report.
Latest metrics snapshot:
{{note:latest-metrics-{{ask-project.projectName}}}}
Matching metrics page:
{{load-all-metrics.metricsNotes}}

Запуск конвейера

  1. Запустите workflow Коллектора и передайте метрики проекта.
  2. Автоматические write-note/upsert-note сохраняют данные, используя поиск latest-заметки именно этого проекта.
  3. Запустите Репортёр для того же проекта.
  4. Прочитайте страницу результатов и полный latest snapshot через {{note:KEY}}; при необходимости доберите страницы через MCP.
  5. Сравните собранные даты и явно назовите неполноту коллекции, если она осталась.

Если каждому сбору нужна отдельная заметка, выбирайте уникальный collection key. Повтор ключа создаёт новую версию той же заметки; upsert-note обновляет найденную latest-заметку и не доказывает, что очередной сбор сохранён отдельно.

Веб-интерфейс

Notes управляются через веб-интерфейс на странице Notes (доступна из боковой навигации):

  • Просмотр notes с ключом, тегами, размером и превью
  • Фильтрация по тегу или поиск по имени ключа
  • Создание, редактирование и удаление notes
  • Просмотр истории версий — прошлая версия сама по себе, рядом с текущей или как построчное сравнение — и восстановление; диалог истории тот же, что у playbooks и глобальных настроек
  • Мониторинг использования квоты

Связанное

  • Справочник MCP Tools — действия и схемы tool notes
  • Ноды — Конфигурация автоматических типов нод
  • Шаблоны — Синтаксис шаблонных переменных, включая {{note:KEY}}