Тема
Документы компании
Семейство documents.
norm_documents_list
Документы, которые компания открыла агентам NORM: правила, регламенты, матрицы ролей, инструкции агентам. Список без текста — название, метки, дата последней правки, длина текста и ссылка на оригинал; текст отдаёт norm_document_get окнами. Метки ставит компания, и смысл им задаёт она: какую метку спросить, говорит настройка агента. tag — только документы с этой меткой: метка сравнивается целиком, без учёта регистра. Документов, убранных в архив, в списке нет. Порядок — по названию; total — сколько документов подошло под фильтр до применения страницы. Пустой список — компания не открыла агентам ни одного подходящего документа. Документы открыты каждому, кому открыто чтение данных компании; тем, кому оно закрыто, реализация отказывает unauthorized_scope. Доменное состояние not_ready — документы компании не подключены.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
tag | нет | string | Только документы с этой меткой: метка целиком, без учёта регистра и пробелов по краям. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
documents | да | список CompanyDocument | Документы этой страницы по названию; пустой список — подходящих документов нет. |
total | да | integer | Сколько документов подошло под фильтр всего, на всех страницах. |
error | нет | DomainError | Почему списка нет: документы компании не подключены. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "documents",
"label": "Документы для агентов"
}
],
"freshness": {
"as_of": "2026-10-13T06:00:00.000Z",
"ttl_sec": 129600,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"total": 3,
"documents": [
{
"id": "2f6d0b84-93a7-4e15-b2c8-7a5e9d3f0b62",
"title": "Матрица ролей Актива",
"tags": [
"Дайджест — день",
"Дайджест — неделя"
],
"updated_at": "2026-10-10T12:40:00.000Z",
"total_chars": 8420,
"url": "https://docs.example.com/aktiv/roles-matrix"
},
{
"id": "5a3e8f20-6b4d-4c97-8e02-f9b7d5a3e8f2",
"title": "Правила Актива",
"tags": [
"Дайджест — день",
"Дайджест — неделя"
],
"updated_at": "2026-10-12T15:05:00.000Z",
"total_chars": 31250,
"url": "https://docs.example.com/aktiv/rules"
},
{
"id": "8e7b6a54-0d2f-4a83-9b65-3e2d7f8a6b05",
"title": "Регламент и расписание встреч Актива",
"tags": [
"Дайджест — день"
],
"updated_at": "2026-10-01T09:20:00.000Z",
"total_chars": 12780,
"url": "https://docs.example.com/aktiv/meetings-schedule"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "documents"
}
],
"freshness": {
"as_of": "2026-10-13T06:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Документы компании не подключены: база документов для агентов не выбрана. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}norm_document_get
Текст документа компании в Markdown окнами, по id из norm_documents_list. Текст — как его написала компания, без пересказа и сокращений; вложенные файлы, встроенные страницы и встроенные базы данных в него не входят. max_chars — размер окна в символах (умолчание 12000, максимум 24000; те же значения, что у окна расшифровки, раздел limits слепка). Для следующего окна передайте page.next_cursor как cursor; нет курсора — текст дочитан. Повторный вызов с тем же курсором вернёт тот же текст, пока документ не правили; склейка окон равна полному тексту. Пустой документ — законный ответ с пустым text. updated_at приходит в каждом окне — это редакция документа: запишите её, чтобы знать, по какой редакции вы работали. Сменилась между окнами — документ правили, пока вы читали: начните чтение заново. Права — как у norm_documents_list. Доменные состояния: unknown_id — документа с таким id нет, в том числе убранного в архив; not_ready — документы компании не подключены.
Доступ: чтение · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Какой документ читать: id из norm_documents_list. |
cursor | нет | string | Откуда продолжить чтение: next_cursor из прошлого ответа. Без него — с начала. |
max_chars | нет | integer | Сколько символов прислать за раз. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
id | да | string | Какой это документ: тот же id, что передан во входе. |
text | да | string | Markdown этого окна; пустой у пустого документа. |
title | да | string | Название документа: сослаться на него в ответе. |
total_chars | да | integer | Длина всего текста: по ней видно, сколько окон впереди. |
updated_at | да | string (date-time) | Редакция документа — когда его последний раз правили; сменилась между окнами — читайте заново. |
error | нет | DomainError | Почему текста нет: документа с таким id нет или документы компании не подключены. |
url | нет | string (uri) | Ссылка на оригинал для человека; может требовать входа в систему компании. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "documents:5a3e8f20-6b4d-4c97-8e02-f9b7d5a3e8f2",
"label": "Правила Актива"
}
],
"freshness": {
"as_of": "2026-10-13T06:00:00.000Z",
"ttl_sec": 129600,
"stale": false
},
"page": {
"has_more": true,
"next_cursor": "eyJvIjoxMjAwMH0"
},
"data": {
"id": "5a3e8f20-6b4d-4c97-8e02-f9b7d5a3e8f2",
"title": "Правила Актива",
"updated_at": "2026-10-12T15:05:00.000Z",
"total_chars": 31250,
"text": "# Правила Актива\n\n## 1. Встречи\n\n- Встреча Актива стоит в календаре не позже чем за сутки до начала.\n- У встречи есть повестка: что решаем и кто готовит материалы.\n- Встреча записывается, протокол рассылается в тот же день.\n\n## 2. Поручения\n\n- У поручения есть исполнитель и срок.\n",
"url": "https://docs.example.com/aktiv/rules"
}
}Пример: случай «unknown_id»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "documents"
}
],
"freshness": {
"as_of": "2026-10-13T06:00:00.000Z",
"ttl_sec": 129600,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "unknown_id",
"message": "Документа с id «0b1d2e3f» нет среди документов, открытых агентам: возьмите id из norm_documents_list.",
"retryable": false
}
}
}Пример: случай «not_ready»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "documents"
}
],
"freshness": {
"as_of": "2026-10-13T06:00:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Документы компании не подключены: база документов для агентов не выбрана. Это ждёт человека — повторный вызов ничего не изменит.",
"retryable": false
}
}
}Объекты семейства
Объекты, из которых состоят аргументы и ответы инструментов этого семейства.
CompanyDocument
Документ компании. Документ, который компания открыла агентам NORM: правило, регламент, матрица ролей, инструкция агенту. Название, метки, дата последней правки и длина текста; самого текста здесь нет — его отдаёт norm_document_get окнами. Метки ставит компания, и смысл им задаёт она.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Чтобы прочитать текст: id для norm_document_get. |
tags | да | список string | Метки, которые поставила компания; пустой список — меток нет. |
title | да | string | Название документа, как его назвала компания. |
total_chars | да | integer | Длина текста в символах: по ней видно, сколько окон займёт чтение. |
updated_at | да | string (date-time) | Когда документ последний раз правили: по этой дате записывают, по какой редакции работали. |
url | нет | string (uri) | Ссылка на оригинал для человека; может требовать входа в систему компании. |