# Файлы на диске
> Папки на сервере и сетевые папки SMB как контекст: Word, Excel, PowerPoint (2007+ и 97–2003), PDF и текст — инструменты glob, grep, read; только чтение.
У команды есть папка — на сервере, на общем диске отдела, на NAS, — где лежит то, чего нет
ни в задаче, ни в коде: регламенты в Word, бюджеты и реестры в Excel, планы в PowerPoint,
договоры в PDF, заметки в текстовых файлах. Интеграция даёт модели **читать эту папку** так,
как читает человек: документ — текстом с заголовками и таблицами, таблицу — листами,
презентацию — слайдами, PDF — страницами. **Только чтение**, ничего не индексируется и не
копируется: файл читается в момент вопроса, и в ответе видно, какие файлы были прочитаны.
_Иллюстрация: Вопрос, ответ на который записан только в документе на сетевой папке: модель нашла файл инструментом grep, прочитала его и ответила по нему — с путём к файлу._
## Инструменты
Три инструмента — те же, которыми ИИ-агенты работают с файлами кода, по именам, параметрам и
формату ответа: модель, которая их знает, не учится ничему новому. Разница — в том, что за
ними: файл Office или PDF ищется и читается как текст, путь может вести на сетевую папку, и
всё остаётся внутри области подключения.
| Инструмент | Что делает |
|---|---|
| `glob` | ищет файлы **по имени** — шаблон вида `*.docx`, `**/договор*`, регистр не важен; по всей области или в папке; новые сначала |
| `grep` | ищет **по содержимому** — регулярное выражение по тексту файлов, включая текст документов, таблиц, презентаций и PDF; отвечает файлом, номером строки и строкой |
| `read` | читает файл **целиком** пронумерованными строками — или папку списком; `offset` и `limit` — если модели нужна часть |
Номер строки у `grep` тот же, что покажет `read`: нашла строку — прочитала окрестность.
Ничего не ограничивается и не обрезается: ни число найденных файлов, ни число строк, ни
длина строки. Страницами файл читается только тогда, когда модель сама попросила `offset`
и `limit`.
## Форматы
| Что | Как читается |
|---|---|
| Word `.docx`, `.docm` | markdown: заголовки, абзацы, списки, таблицы, ссылки, текст врезок |
| Excel `.xlsx`, `.xlsm` | каждый лист — таблицей с заголовком из первой строки; даты — датами, а не числом дней |
| PowerPoint `.pptx`, `.pptm` | слайд за слайдом: заголовок, текст, таблицы, заметки докладчика |
| Word 97–2003 `.doc` | текст документа: абзацы, списки, ячейки таблиц |
| Excel 97–2003 `.xls` | листы таблицами, числа и даты — как в новом формате |
| PowerPoint 97–2003 `.ppt` | текст слайдов и заметки |
| PDF | постранично, текстовый слой |
| Текстовые файлы | как есть: `.txt`, `.md`, `.csv`, `.json`, `.xml`, `.yaml`, `.html`, код — UTF-8 или Windows-1251 |
Формат узнаётся **по содержимому**, а не по расширению: документ, переименованный в `.zip`,
всё равно документ. Всё остальное — картинки, архивы, скан в PDF без текстового слоя,
защищённый паролем файл — интеграция **называет** по виду и размеру, а не притворяется, что
прочитала. Старые форматы читаются как текст: диаграммы, картинки и внедрённые объекты в
них не переводятся.
Скан — это картинка. У PDF без текстового слоя интеграция честно скажет «нет текстового
слоя, страниц: N»; распознавание текста (OCR) в неё не входит.
## Пути и область
Путь — **абсолютный локальный** (`/srv/docs/2026/plan.docx`) или **сетевой**, в любом из
трёх написаний: `\\сервер\папка\раздел`, `//сервер/папка/раздел`, `smb://сервер/папка/раздел`.
В ответах сетевой путь всегда показан одним способом — `smb://сервер/папка/раздел`: он
переживает JSON и markdown без экранирования.
В подключении перечисляются **корни** — папки, а при желании и отдельные файлы; бот работает
в них и во всём, что вложено. Второе поле — **исключения**: шаблоны имён и путей, которых бот
не видит, — `*.bak`, `~$*` (временные файлы Office), `.git`, `archive/2019`. Шаблон
сравнивается с именем файла или папки на любой глубине и с путём от корня.
**Пустой список корней означает «весь диск машины с коннектором»** — всё, что читается
пользователем, под которым работает интеграция. Сетевых папок это не касается: к ним ходят с
паролем, и модель не должна сама называть сервер, куда этот пароль уйдёт, — сетевая папка
доступна только через корень.
Путь вне корней не читается, даже если модель назовёт его точно; путь по символической
ссылке проверяется по тому, куда она ведёт. Исключённый файл не находится ни поиском, ни
списком папки.
## Локальный диск и права
Интеграция работает **под отдельным пользователем ОС** — так коннектор изолирует каждое
подключение (см. [Изоляция](/docs/connector/isolation)). Значит, локальные файлы должны быть
этому пользователю **доступны на чтение**: право на чтение «для всех» (`chmod -R a+rX`) или
группа, в которую входит и пользователь подключения. Файл, который прочитать нельзя, в
списке виден, а при чтении называется вместе с причиной.
Коннектор в контейнере видит только то, что в контейнер смонтировано: папку нужно
**пробросить** — `-v /srv/docs:/srv/docs:ro` — и назвать корнем путь внутри контейнера.
Сетевой диск, смонтированный операционной системой (SMB через `cifs`, NFS), — это тоже
локальная папка: пробросьте её так же, пароль в подключении тогда не нужен.
## Сетевая папка SMB
Вторая дорога к сетевому диску — **без монтирования**: интеграция сама говорит по SMB с
сервером из корня. Для этого подключению нужны **учётная запись и пароль** — заведите
отдельную, только на чтение и только на нужную папку. Домен — в имени: `CORP\svc-buff` или
`svc-buff@corp.local`.
Это единственный вид учётных данных, который коннектор **передаёт интеграции**: SMB — не
HTTP, подставить пароль за плагин коннектор не может. В каталоге это видно до установки
(«передаётся самой интеграции»), в журнале запросов — каждая выдача. Все прочие интеграции
своих секретов не видят.
Интеграция говорит **SMB 2.0.2 и 2.1** с самого первого пакета — без SMB1-приветствия, которое
отключено на современных серверах и NAS, — входит по **NTLMv2** и подписывает сессию, если
сервер того требует. Сервер, которому нужно **только SMB3 с шифрованием**, подключить так не
получится: смонтируйте его средствами ОС и подключите как локальную папку.
Соединения, которые интеграция открывает сама, объявлены в её манифесте — протокол, порт и
поле, из которого берутся адреса, — и показаны на странице подключения рядом с адресами
HTTP: `smb://nas.corp:445`.
_Иллюстрация: Форма настройки: корни — локальные и сетевые, исключения, учётная запись и пароль сетевой папки._
## Настройка
| Поле | Значение |
|---|---|
| Папки | корни через запятую: `/srv/docs`, `\\nas\docs\specs`, `smb://nas/docs/regulations.docx`; пусто — весь диск машины с коннектором |
| Исключения | шаблоны через запятую: `*.bak`, `~$*`, `.git` |
| Учётная запись для `share` | `CORP\svc-buff` — нужна только при сетевых корнях |
| Пароль для `share` | пароль этой учётной записи; передаётся интеграции |
Проверка связи говорит, сколько корней из перечисленных доступно, называет недоступные с
причиной и учётную запись, под которой читаются сетевые папки.
Из командной строки: `connector install files`, затем
`connector instance set --plugin files --version 1.0.0 --set roots=/srv/docs,\\nas\docs --set excludes=*.bak`
и `connector instance secret <подключение> --secret share --account 'CORP\svc-buff'` (пароль —
со стандартного ввода).
_Иллюстрация: Проверка связи: сколько корней доступно и под какой учётной записью читаются сетевые папки._
## Чего интеграция не делает
- **Не пишет на диск** — ни файлов, ни комментариев; инструментов записи у неё нет вовсе.
- **Не индексирует и не копирует** содержимое: файлы читаются в момент вопроса. На большой
папке `grep` по содержимому — это чтение и разбор каждого файла при каждом запросе;
сузьте область корнями и исключениями, а модели укажите папку или `include`.
- **Не распознаёт сканы** и не читает картинки.
- **Не говорит по NFS, WebDAV, FTP** — такой диск монтирует ОС, дальше он локальный.
- **Не принимает обращений в файлах** — у папки нет ленты комментариев; вопросы задаются в
Buff («Спросить», глубокое исследование) или обращением в трекере и на странице источника
знаний, а файлы — контекст для ответа. Задачи разработки папку не читают.