Инструкция для ИИ-агента
Задача
Помоги пользователю довести Linkly AI до проверенного рабочего состояния:- Определи, установлен и запущен ли Desktop
- Проверь локальный MCP и CLI
- Проведи пользователя через действия с интерфейсом, которые нельзя выполнить самому
- Настрой один рабочий путь доступа — CLI или MCP
- Установи Linkly AI Skills только после согласия пользователя на команду установки
- Выполни сквозную проверку поиска и отчитайся о результате
Ограничения и правила
- Не притворяйся, что нажал кнопку или установил приложение, если этого не сделал
- Не отключай песочницу, защиту ОС или браузера целиком
- Не загружай личные документы во внешние сервисы
- Не изменяй исходные документы; инструменты Linkly AI предназначены для чтения
- Команды установки, требующие сети, сначала покажи пользователю и получи разрешение
- Если
linklyдоступен в песочнице, но Desktop недостижим, повторяй вне сетевой песочницы только точную команду Linkly после разрешения - Не проси запустить Desktop, пока разрешённая проверка вне песочницы не подтвердила недоступность
- Не проси у пользователя API Key (начинается с
lkai_) или токен LAN-доступа и не выполняй за негоlinkly auth set-key: это ключи к его локальной библиотеке, а всё, что проходит через диалог, отправляется поставщику модели и сохраняется в истории чата. Для входа используй двухшаговыйlinkly auth login(R2–R4 в удалённой ветке) — пользователь только подтверждает доступ в браузере. Если пользователь всё же прислал ключ или токен, не используй его: попроси отозвать ключ и создать новый в Dashboard (https://linkly.ai/dashboard/integrations), а LAN-токен — перегенерировать в View MCP connection settings в Desktop
Сначала проверь возможность выполнения команд
Если оболочка недоступна, не выдумывай результаты: используй ручные шаги и проси пользователя присылать точный вывод.Затем проверь, должен ли Desktop стоять на этой машине
Шаги 0–4 предполагают, что Desktop работает на том же компьютере, что и ты. Если его здесь не будет никогда — ты бот на удалённом сервере, в контейнере или облачной VM, а Desktop пользователя (если он есть) стоит на другом компьютере, — не проси ставить Desktop туда, где работаешь ты. Пропусти шаги 0–4 и следуй разделу Удалённая ветка: на этой машине нет Desktop ниже. Если не можешь определить, один раз спроси пользователя.Шаг 0. Проверка состояния
macOS / Linux
Windows PowerShell
Как читать результат
/health — самый надёжный пробник. Успешный ответ HTTP 200 содержит version, doc_count, mcp_endpoint, index_status и capabilities.
- Не фиксируй порт 60606: это только значение по умолчанию; фактический порт всегда читай из JSON
~/.linkly/port. - Файл порта остаётся после аварийного завершения, поэтому сам по себе не доказывает, что служба запущена. HTTP 200 доказывает здоровье; недоступность внутри сетевой песочницы ещё ничего не доказывает.
mcp_endpoint: nullозначает, что переключатель MCP выключен, а не проблему порта: попроси пользователя нажать значок Agent внизу левой боковой панели главного окна, открыть страницу Agent usage и включить Allow local access (или нажать Start на карточке Stopped).index_status:watching— завершено, также возможныscanning,indexing,idle,error.doc_countпоказывает общий объём индекса, но не доказывает, что в него попал конкретный пользовательский файл.
Таблица состояний
Если
doc_count остаётся примерно на уровне встроенных примеров (~150), предложи в итоговом отчёте добавить свои папки через Add folder в разделе Library главного окна, но не считай это блокером.
Шаг 1. Установка и инициализация
1. Скачать и установить
Открой официальную страницу и выбери ОС:- macOS: открой
.dmg, перетащи LinklyAI в Applications, запусти из Launchpad. - Windows: открой
.exe, пройди мастер и запусти из меню Start. - Linux: x86_64 AppImage требует glibc 2.35+; выполни
chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage. При проблеме см. FAQ AppImage.
2. Мастер первого запуска
Последовательность: обложка → Bring your files in → Connect an agent → All set (счётчик 1/2, 2/2 учитывает только два средних экрана). Язык и тему можно переключить в правом нижнем углу любого экрана. На обложке пользователь обязательно принимает Privacy Policy и может снять включённую по умолчанию телеметрию Help improve Linkly AI (anonymous). На экране Bring your files in Sample files обязательны и индексируются в фоне без ожидания; Documents, Desktop и Downloads по умолчанию не отмечены, а при их выборе в macOS нужно разрешить доступ в системном окне. На экране Connect an agent кнопка Install рядом с Install the Linkly CLI and Skills ставит CLI и Skills в фоне, Keep the CLI and Skills up to date включено по умолчанию; без нажатия ничего не устанавливается, позже это можно сделать на странице Agent usage главного окна. На экране All set кнопка Get started открывает главное окно. Шага входа в мастере нет: вход нужен только для квоты официальных моделей и облачных функций, а локальный индекс, поиск и MCP работают без входа и без сети.3. Добавить документы
Если в мастере не отмечена ни одна папка, проиндексированы только примеры. Добавление своих файлов необязательно: попроси открыть Library в боковой панели главного окна и добавить нужные папки через Add folder или поместить файлы в автоматически наблюдаемую~/LinklyAI. Не выбирай личные каталоги за пользователя. При ошибках разрешений macOS добавь Linkly AI в System Settings → Privacy & Security → Full Disk Access и перезапусти приложение.
4. Фоновая загрузка моделей
Объясни, что приложение в фоне загружает около 890 МБ моделей: примерно 639 МБ для семантического поиска и 249 МБ для OCR; при последующем включении расшифровки аудио и видео загрузится ещё около 161 МБ модели распознавания речи. Это может занять от нескольких минут до часа. Ключевой поиск работает сразу; до готовности моделейsearch автоматически переходит на полнотекстовый режим с немного худшей релевантностью. Не объявляй это поломкой.
5. Подтверждение
Попроси пользователя один раз ответить, когда Desktop запущен, мастер завершён и хотя бы одна папка добавлена. Критерий приёмки:/health возвращает 200 и doc_count > 0. Если мастер завершён, но идёт scanning/indexing, повторяй проверку каждые 10 секунд до 6 раз. После этого нулевой счётчик обрабатывай как ошибку. Собственная папка не обязательна — встроенных примеров достаточно.
После ответа пользователя: если на экране Connect an agent была нажата Install, CLI и Skills могут быть уже установлены: CLI в ~/.linkly/bin/linkly (Windows: %LOCALAPPDATA%\linkly\bin\linkly.exe), Skills в ~/.agents/skills/linkly-ai/.
- Сначала повтори проверку шага 0. Если всё установлено, пропусти вариант A шага 2 и шаг 3, не устанавливай повторно.
- Если команда
linklyне найдена, попроси пользователя открыть новое окно терминала. - Исключение: если ты Claude Code и
~/.claude/skills/linkly-aiотсутствует, Skills тебе не видны (Claude Code не читает~/.agents/skills). Тогда всё равно выполниlinkly skills install— команда создаст эту ссылку.
Шаг 2. Подключение инструмента
CLI и MCP можно настроить вместе. Сначала предпочтителен CLI, потому что его можно проверить в текущем сеансе; MCP появляется только после перезагрузки клиента. В начале прочитай реальный порт:$mcpUrl = "http://127.0.0.1:$port/mcp". Не подставляй 60606 напрямую.
Вариант A. CLI (рекомендуется для агентов с оболочкой)
Покажи команду, объясни, что она скачивает и запускает установщик, и получи согласие. Варианты:~/.linkly/bin/linkly на macOS/Linux либо %LOCALAPPDATA%\linkly\bin\linkly.exe на Windows. Критерий: linkly --version печатает версию, а linkly status --json содержит app_version и doc_count.
Дальше называй себя в каждом вызове. Добавляй --client <имя-твоего-приложения> ко всем командам linkly — --client claude-code, --client cursor, как ты называешься. Настольное приложение ведёт локальный журнал доступа, чтобы пользователь видел, какие ИИ-приложения читали его документы; без имени твои вызовы попадают туда безымянной локальной записью. Это метка, а не учётные данные: она ничего не даёт и никогда не проверяется.
Вариант B. MCP
Для клиента на том же компьютере используй вычисленный$MCP_URL с именем linkly-ai:
linkly-ai, тип StreamableHTTP, URL — вычисленное значение с ?client=cursor в конце.
О ?client=: настольное приложение ведёт локальный журнал доступа, чтобы пользователь видел, какие ИИ-приложения читали его документы, и именно этот параметр даёт вызовам имя в журнале. Указывай имя своего приложения. Это метка, а не учётные данные: она ничего не даёт и никогда не проверяется, так что без неё теряется только имя. (Через удалённый туннель добавлять нечего — там имя берётся из входа по OAuth.)
Новый сервер обычно не появляется в текущем сеансе. Сначала начни новый разговор; если не помогло, полностью заверши клиент и открой снова (закрыть окно недостаточно). Запись конфигурации уже завершает шаг; не опрашивай текущий сеанс бесконечно.
Сервис можно проверить прямым рукопожатием:
"serverInfo":{"name":"linkly-ai" подтверждает здоровье; HTTP 403 означает, что переключатель MCP выключен: попроси пользователя на странице Agent usage включить Allow local access (или нажать Start на карточке Stopped).
Шаг 3. Установка Skills
После разрешения пользователя:git pull внутри него. Skills также требуют нового разговора или полного перезапуска клиента. Не считай наличие каталога достаточным: критерий — SKILL.md по одному из путей ~/.claude/skills/linkly-ai/, .claude/skills/linkly-ai/ или ~/.agents/skills/linkly-ai/. Текущий сеанс не обязан уже видеть Skill.
Шаг 4. Сквозная проверка
doc_count примерно равен уровню примеров (~150), ищи Holmes. Если он явно выше, выбери слово из собственных документов пользователя. Успех означает реальные записи документов с doc_id, после чего linkly outline <DOC_ID> или linkly read <DOC_ID> получает содержимое.
При только MCP-подключении текущий сеанс не может закончить проверку. Сообщи: конфигурация записана, рукопожатие успешно, проверка ожидает перезагрузки. Повтори оба способа перезагрузки и передай самодостаточную фразу: «После перезагрузки выполни search Holmes через сервер linkly-ai». Убедись, что реально вызван инструмент, а не дан ответ из памяти модели.
Пустой поиск не означает проблему модели: пока она не готова, работает полнотекстовый fallback. По порядку проверь запрос, doc_count == 0, добавленные папки и поддерживаемый формат. index_status: indexing означает ожидание, error — устранение неполадки. Сразу после сканирования watching может появиться на короткое время до извлечения содержимого, поэтому повтори проверку и посмотри, растёт ли doc_count.
Удалённая ветка: на этой машине нет Desktop
Эта ветка заменяет шаги 0–4, когда на машине, где ты работаешь, нет Linkly AI Desktop (например, бот на удалённом сервере или в контейнере), а Desktop пользователя, если он есть, стоит на другом компьютере. Доступ к контенту пользователя идёт через облако. При входе ниже пользователь подтверждает доступ в браузере, а CLI сам сохраняет ключ: ключ не проходит через диалог, и пользователю ничего не нужно копировать.R1. Установи CLI
Используй команды установки из варианта A шага 2 с тем же правилом: сначала покажи команду и получи согласие. Проверка:linkly --version выводит версию. linkly status здесь завершится ошибкой — Desktop на этой машине нет, это ожидаемо.
R1.5. Проверь, выполнен ли вход
remote.valid равно true, пользователь уже вошёл — переходи к R5. Если null, шлюз сейчас недоступен — повтори позже и не выходи из аккаунта.
R2. Начни вход
{"status":"pending","url":…,"user_code":…,"expires_in":600}. При ошибке сообщение называет следующую команду — выполни её.
R3. Передай ссылку пользователю и остановись
Отправь всё одним сообщением и жди одного ответа:url— открывается на любом устройстве, в том числе на телефоне;user_code— перед нажатием Авторизовать пользователь должен убедиться, что на странице тот же код;- ссылка действует 10 минут, а страница показывает, какой аккаунт авторизуется, — пусть проверит, что это нужный.
R4. Заверши вход
{"status":"ok","account":…,"plan":…,"key_preview":…}. При timeout просто повтори ту же команду: ссылка действует до истечения срока. При expired или denied начни заново с R2.
Слова пользователя «готово» — не доказательство. Верь только выводу CLI: пока --wait не вернул "status":"ok", вход не завершён.
- R2 и R4 выполняй в одном окружении, от одного системного пользователя и с одним каталогом конфигурации. Ожидающий вход хранится там; новый контейнер, другой пользователь или другой
LINKLY_CONFIG_DIRего не увидят. - Обслуживаешь нескольких пользователей? Дай каждому свой
LINKLY_CONFIG_DIR(в каталоге — один аккаунт) и указывай его в каждой команде для этого пользователя, напримерLINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json. - Окружение пересоздано и учётные данные пропали — просто войди заново с R2.
R5. Проверка в три уровня
Проверяй и сообщай о каждом уровне отдельно: успех одного ничего не говорит о следующем.-
Вход выполнен:
linkly auth status --jsonпоказывает"valid": trueи тариф. Это подтверждает только аккаунт, но не доступ к контенту. -
Работает облачный поиск (достаточно Free): возьми облачную библиотеку, подключённую пользователем (если не знаешь ни одной — спроси), и выполни:
Реальные результаты — уровень пройден. Если облачных библиотек нет, сообщи, что уровень пропущен, а не пройден.
-
Работает локальный поиск (документы на Desktop пользователя): нужны Pro и Desktop в сети с подключённым удалённым доступом (см. Удалённый доступ). Сначала проверь:
Если туннель подключён, выполни
linkly search "<query>" --remoteи жди реальных результатов. Если Desktop офлайн или туннель не подключён, так и сообщи и попроси пользователя открыть Desktop, на странице Agent usage включить Allow remote access (internet) и дождаться статуса Connected — не заявляй об успехе.
Устранение неполадок
App: Unreachable
App: Unreachable
Если файла порта нет, Desktop не установлен или не запускался. Если файл есть, он мог устареть после сбоя либо localhost блокирует песочница. Прочитай реальный порт, с разрешения повтори точную проверку вне песочницы и только затем проси запустить приложение.
MCP возвращает 403
MCP возвращает 403
Попроси пользователя на странице Agent usage включить Allow local access (или нажать Start на карточке Stopped); не отлаживай порт.
Index status: error
Index status: error
Выполни
linkly doctor и смотри группу Local; без CLI открой logs/app.log через Settings → General → App Data → Open. Не продолжай до восстановления.CLI не найден после установки
CLI не найден после установки
Открой новый shell. Полные пути:
~/.linkly/bin/linkly или %LOCALAPPDATA%\linkly\bin\linkly.exe. При блокировке PowerShell можно временно выполнить Set-ExecutionPolicy -Scope Process -Bypass в этом окне либо использовать Cargo.MCP подключён, но инструментов нет
MCP подключён, но инструментов нет
Начни новый разговор; если не помогло, полностью заверши клиент и открой снова. Это механизм загрузки, а не ошибка конфигурации.
Поиск пуст
Поиск пуст
Проверь запрос,
doc_count, добавленные папки и формат. Не обвиняй модель: полнотекстовый fallback работает без неё.Индекс долго в состоянии indexing
Индекс долго в состоянии indexing
Для большой коллекции или загрузки моделей это нормально; проверь, растёт ли
doc_count.Ошибки разрешений macOS
Ошибки разрешений macOS
Добавь Linkly AI в System Settings → Privacy & Security → Full Disk Access и перезапусти приложение.
Нужна глубокая диагностика
Нужна глубокая диагностика
Запусти
linkly doctor: он проверяет каждое доступное этой машине подключение (локальный Desktop, а если настроены — удалённое и LAN), по группе на каждое с советами; смотри группу того подключения, которое настраиваешь.Итоговый отчёт
Сообщи пользователю факты: какие шаги и каким путём выполнены, нужен ли новый разговор или полный перезапуск, версия Desktop и CLI, состояние индекса иdoc_count, состояние Skills, команда проверки и результат. Для удалённой ветки перечисли, какие из трёх уровней проверки пройдены. Объясни использование: например, добавить use linkly-ai к запросу открыть launcher поиска через Cmd/Ctrl + L или главное окно через Cmd/Ctrl + K (после обновления со старой версии сохраняются прежние сочетания). Отдельно перечисли незавершённые ручные шаги.
Заверши четырьмя примерами вопросов
Сначала вызовиlinkly explore и подстрой вопросы под реальные материалы пользователя. Если есть только встроенные примеры, предложи:
- Прочитай «A Life in 10 Years» и проанализируй повторяющиеся жизненные паттерны в дневниках Сэмюэла Пипса и его возможные слепые зоны.
- Прочитай 12 дел в Detectives Library, выдели формулу Шерлока Холмса и преврати её в чек-лист диагностики сложных бизнес-проблем.
- Прочитай Federalist Papers: чего боялись основатели США, как они противопоставляли амбицию амбиции и фракцию фракции, и какие принципы это даёт для управления современными AI-компаниями.
- По воспоминаниям бывших рабов из WPA Slave Narratives объясни, что учебники американской истории обычно не проговаривают прямо.

