Инструкция v2 для внешнего агента: что запросить у пользователя и зачем

Дата: 2026-05-04 11:05 UTC

Зачем появилась v2

Предыдущая инструкция объясняла Trip2G onboarding слишком мягко: внешний агент мог прочитать её и не понять, какие доступы реально нужны, чтобы начать работу, и почему простой URL страницы недостаточен.

Эта версия написана как прямое сообщение для агента, которому пользователь дал Trip2G instance и попросил помочь с базой.

Короткая версия для агента

Если пользователь хочет, чтобы ты сам разобрался в его Trip2G instance, подготовил изменения и загрузил результат, попроси сразу:

1. URL Trip2G instance.
2. Архив vault/site из admin UI Trip2G/simplecloud.
3. Admin token/cookie или admin session secret — если нужно самому открыть админку, скачать архив, загрузить результат или менять настройки.
4. Цель первого прохода: что должно получиться в конце.

Не называй это абстрактно “агентский токен”. Объясняй конкретно:

Мне нужен не токен “для меня как агента”, а временный доступ к твоему Trip2G instance, чтобы я мог:
- прочитать текущую структуру базы;
- понять, какие файлы уже есть;
- найти sync/API key или использовать admin API;
- загрузить изменения обратно;
- проверить, что сайт/MCP действительно обновились.

Что попросить у пользователя — готовый текст

Скопируй пользователю:

Чтобы я мог не просто дать советы, а реально начать работу с твоим Trip2G instance, пришли, пожалуйста:

1. URL инстанса
   Например: https://your-project.2pub.me/

2. Архив vault/site из Trip2G admin/simplecloud
   Он нужен, чтобы я увидел текущие markdown-файлы, структуру, настройки Obsidian plugin и возможный sync/API key.

3. Временный admin token/cookie или другой admin secret
   Он нужен, если ты хочешь, чтобы я сам:
   - открыл admin UI;
   - скачал архив, если ты его ещё не скачал;
   - загрузил изменения обратно;
   - настроил public/private доступ;
   - изменил templates/frontmatter patches;
   - проверил MCP/admin-only поведение.

4. Что сделать первым
   Например:
   - собрать первую LLM Wiki базу;
   - переписать главную страницу;
   - добавить AGENTS.md/index.md/log.md;
   - импортировать Obsidian vault;
   - настроить MCP-инструкции для Claude/Cursor/Codex.

Не присылай token/cookie в публичный GitHub issue или публичный markdown. Передай как secret/env/личное сообщение, если возможно. После работы токен лучше отозвать или перевыпустить.

Почему одного URL недостаточно

URL публичной страницы обычно даёт только то, что видит обычный посетитель.

С ним агент может:

- прочитать опубликованную главную;
- понять внешний вид;
- сделать UX/landing audit;
- предложить новые тексты;
- подготовить markdown-патч локально.

Но с одним URL агент обычно не может:

- увидеть приватные/скрытые заметки;
- понять структуру vault полностью;
- узнать, какие файлы лежат за страницами;
- скачать текущий vault;
- загрузить изменения обратно;
- настроить templates/frontmatter patches/access rules;
- проверить admin-only настройки;
- понять, есть ли уже sync/API key.

Поэтому, если задача звучит как “разберись и сделай”, агент должен просить не только URL.

Зачем нужен архив

Архив из Trip2G/simplecloud admin — это стартовый снимок базы.

Он нужен агенту, чтобы:

1. Увидеть реальные markdown-файлы, а не только опубликованные HTML-страницы.
2. Понять структуру папок: `_index.md`, `AGENTS.md`, `SCHEMA.md`, `log.md`, `concepts/`, `sources/` и т.д.
3. Найти, что уже есть, чтобы не создавать дубли.
4. Сделать изменения локально и показать diff.
5. Проверить, есть ли настроенный Obsidian Trip2G plugin.

Важный файл, который может быть внутри архива:

.obsidian/plugins/trip2g/data.json

В нём может лежать sync/API key. Поэтому архив — чувствительный артефакт. Его нельзя публиковать в открытом GitHub, публичном чате или отчёте.

Зачем нужен admin token/cookie

Admin token/cookie нужен не “для красоты” и не потому, что агенту хочется лишних прав.

Он нужен, если агент должен выполнить действия, которые доступны только владельцу/админу instance:

- открыть admin UI;
- скачать архив vault/site;
- загрузить изменённые markdown-файлы;
- изменить templates/layout;
- настроить frontmatter patches;
- изменить public/private access rules;
- включить webhooks/cron;
- проверить GraphQL/admin API;
- проверить, что MCP tools появились после изменений;
- починить настройки публикации.

Если пользователь уже скачал архив и внутри есть рабочий sync/API key, отдельный admin cookie может не понадобиться для простого upload. Но для диагностики admin-настроек и полного onboarding он часто экономит время.

Разница между sync/API token и admin token/cookie

Sync/API token

Нужен для файловой работы:

- скачать/загрузить markdown;
- выполнить sync;
- обновить базу после локальных правок.

Обычно используется CLI или API:

node ./bin/trip2g-sync.mjs ./vault \
  --api-url https://YOUR_INSTANCE.2pub.me/graphql \
  --api-key "$TRIP2G_API_KEY" \
  --two-way

Admin token/cookie

Нужен для админских действий:

- зайти в admin UI;
- менять настройки instance;
- смотреть admin-only state;
- скачивать архив из UI;
- настраивать domains/templates/access/webhooks/frontmatter patches.

Как объяснять пользователю

Если мне нужно только подготовить файлы — достаточно архива.
Если нужно загрузить изменения — нужен sync/API token или архив с уже настроенным sync key.
Если нужно менять настройки инстанса или самому скачать/загрузить через admin — нужен временный admin token/cookie.

Примеры задач и какие доступы просить

Пример 1 — только аудит лендинга

Задача:

Посмотри мой Trip2G site и скажи, что улучшить.

Попросить:

- URL instance.

Не нужно:

- архив;
- admin token/cookie;
- sync token.

Пример 2 — подготовить новую главную, но не загружать

Задача:

Напиши новую `_index.md`, но я сам загружу.

Попросить:

- URL instance;
- архив или текущий `_index.md`;
- цель/аудитория страницы.

Не обязательно:

- admin token/cookie;
- sync token.

Пример 3 — создать первую LLM Wiki и загрузить её

Задача:

Сделай мне первую Trip2G LLM Wiki базу и залей результат.

Попросить:

- URL instance;
- архив vault/site из admin;
- sync/API token или архив с `.obsidian/plugins/trip2g/data.json`;
- временный admin token/cookie, если нужно самому проверить admin/MCP/settings.

Зачем:

Архив нужен, чтобы понять текущую структуру.
Sync/API token нужен, чтобы загрузить файлы.
Admin token/cookie нужен, чтобы проверить настройки и результат в admin UI.

Пример 4 — импортировать существующий Obsidian vault

Задача:

Импортируй мой Obsidian vault в Trip2G.

Попросить:

- URL Trip2G instance;
- архив существующего Obsidian vault;
- архив текущего Trip2G vault/site, если он уже не пустой;
- sync/API token для загрузки;
- список папок, которые нельзя публиковать;
- правила приватности.

Admin token/cookie нужен, если:

- надо менять access rules;
- надо настраивать templates;
- надо проверить публикацию приватных/публичных разделов.

Пример 5 — настроить MCP-инструкции для агентов

Задача:

Сделай так, чтобы Claude/Cursor/Codex понимали эту базу через MCP.

Попросить:

- URL instance;
- архив vault/site;
- sync/API token для загрузки `AGENTS.md`, `SCHEMA.md`, `_mcp_initialize.md`;
- admin token/cookie, если нужно проверить tools/list, public visibility, frontmatter patches или MCP exposure.

Что создать:

AGENTS.md
SCHEMA.md
index.md
log.md
_mcp_initialize.md optional

Как получить архив из simplecloud/admin

Попроси пользователя:

1. Открой https://simplecloud.2pub.me/
2. Войди в аккаунт.
3. Открой свой Trip2G instance через фиолетовую кнопку “открыть как админ”.
4. В admin UI найди download/export/archive vault/site.
5. Скачай архив.
6. Передай архив агенту как приватный файл.

Если пользователь не видит кнопку скачивания:

Скажи мне это. Тогда мне может понадобиться временный admin token/cookie, чтобы самому открыть admin UI и найти способ скачать/синхронизировать vault.

Как получить admin cookie/token

Использовать только для приватной передачи агенту.

Инструкция пользователю:

1. Открой свой instance как админ.
2. Открой DevTools: F12 / Cmd+Option+I / Ctrl+Shift+I.
3. Перейди Application → Storage → Cookies.
4. Выбери домен своего instance, например https://your-project.2pub.me.
5. Найди auth/session cookie Trip2G.
6. Скопируй Name и Value.
7. Передай агенту как secret/env, например:
   TRIP2G_ADMIN_COOKIE="cookie_name=cookie_value"

Если агентный интерфейс поддерживает secrets, лучше передать так:

export TRIP2G_INSTANCE="https://your-project.2pub.me"
export TRIP2G_ADMIN_COOKIE="[REDACTED]"
export TRIP2G_API_KEY="[REDACTED]"

Не вставлять cookie/token:

- в GitHub issue;
- в README;
- в markdown-заметку;
- в публичный Discord/Telegram чат;
- в финальный отчёт агента.

Что агент должен сделать после получения доступа

Создать рабочую папку.
Распаковать архив.
Составить inventory файлов.
Проверить наличие чувствительных файлов:
- .env
- credentials
- cookie
- token
- api_key
- .obsidian/plugins/trip2g/data.json
Не печатать найденные секреты.
Найти или создать минимальные LLM Wiki файлы:
- _index.md
- AGENTS.md
- SCHEMA.md
- index.md
- log.md
Обновить/создать первые useful pages.
Sync/upload через API key или admin flow.
Проверить публичную страницу.
Проверить MCP, если задача про агентов:
- tools/list
- search
- note_html
- custom instructions() / schema() если настроены.
Вернуть пользователю краткий отчёт без секретов.

Минимальная структура результата

Для первого прохода агент должен оставить:

_index.md           # главная/публичный вход
AGENTS.md           # правила для агентов
SCHEMA.md           # типы страниц и frontmatter
index.md            # карта базы
log.md              # журнал изменений
concepts/...        # первые concept pages, если есть содержание
sources/...         # исходники, если есть

AGENTS.md желательно делать MCP-доступным:

---
free: true
mcp_method: instructions
mcp_description: "How agents should read, update, cite and maintain this Trip2G knowledge base."
---
# Agent Instructions

SCHEMA.md можно сделать отдельным MCP method:

---
free: true
mcp_method: schema
mcp_description: "Schema for this Trip2G LLM Wiki: page types, required frontmatter, folders and update rules."
---
# Knowledge Base Schema

Что вернуть пользователю в конце

Формат отчёта:

Готово:
- создано/обновлено: ...
- загружено в Trip2G: да/нет
- проверено публично: URL
- проверено через MCP: да/нет

Как начать читать базу:
- человеку: открыть `_index.md` / главную страницу;
- агенту: начать с `index.md`, затем `AGENTS.md`, затем релевантные страницы.

Что я использовал:
- archive: yes/no
- sync/API token: yes/no, значение не показываю
- admin token/cookie: yes/no, значение не показываю

Что отозвать после работы:
- временный admin token/cookie, если выдавался;
- временный sync/API token, если выдавался.

Следующие шаги:
1. ...
2. ...
3. ...

Главная мысль

Для внешнего агента Trip2G onboarding начинается не с красивой страницы, а с доступа к реальному состоянию базы.

URL показывает фасад.
Архив показывает vault.
Sync/API token позволяет записать изменения.
Admin token/cookie позволяет управлять instance.

Если пользователь хочет реальную работу “под ключ”, агент должен прямо попросить архив и временный admin/sync доступ, объяснив зачем каждый secret нужен и как он будет защищён.

Инструкция v2 для внешнего агента: что запросить у пользователя и зачем

Зачем появилась v2

Короткая версия для агента

Что попросить у пользователя — готовый текст

Почему одного URL недостаточно

Зачем нужен архив

Зачем нужен admin token/cookie

Разница между sync/API token и admin token/cookie

Sync/API token

Admin token/cookie

Как объяснять пользователю

Примеры задач и какие доступы просить

Пример 1 — только аудит лендинга

Пример 2 — подготовить новую главную, но не загружать

Пример 3 — создать первую LLM Wiki и загрузить её

Пример 4 — импортировать существующий Obsidian vault

Пример 5 — настроить MCP-инструкции для агентов

Как получить архив из simplecloud/admin

Как получить admin cookie/token

Что агент должен сделать после получения доступа

Минимальная структура результата

Что вернуть пользователю в конце

Главная мысль

Связанные заметки