Зачем

Telegra.ph удобен как быстрый публичный буфер: агент может за секунды превратить markdown-инструкцию в ссылку, которую можно отправить в Telegram, дать другому агенту или использовать как одноразовый handoff.

Это не замена Trip2G для долговременной базы знаний. Для устойчивых инструкций canonical copy всё равно нужно сохранять в Trip2G/Obsidian или Hermes skill.

Когда НЕ применять

• Если документ должен долго поддерживаться, индексироваться внутри базы и жить как часть знания проекта — сохранять в Trip2G.
• Если текст содержит токены, cookies, персональные данные, приватные URLs или внутренние логи — не публиковать в telegra.ph.
• Если нужна совместная редактура, версии, вложения, права доступа — использовать Trip2G/Docs/Notion, а не telegra.ph.

Предусловия

• Для создания страницы не нужна Telegram-авторизация, номер телефона или бот.
• Нужен только интернет-доступ к Telegraph API.
• Для последующего редактирования надо сохранить access_token и path; если их не сохранить, страница фактически одноразовая.
• Нельзя записывать access_token в публичную заметку.

Минимальный workflow

1. Подготовить markdown/текст инструкции.
2. Убрать секреты: токены, cookies, session strings, приватные ссылки, внутренние идентификаторы.
3. Создать Telegraph account через API createAccount.
4. Получить access_token из ответа.
5. Преобразовать markdown в Telegraph content nodes: массив JSON-узлов {tag, attrs?, children}.
6. Вызвать createPage с access_token, title, author_name, content.
7. Вернуть пользователю result.url.
8. Если инструкция важная — сохранить canonical copy в Trip2G/Obsidian и добавить ссылку в индекс/лог.

Python-шаблон

import json
import urllib.parse
import urllib.request

API = "https://api.telegra.ph"


def post(method: str, data: dict) -> dict:
    body = urllib.parse.urlencode(data).encode()
    req = urllib.request.Request(f"{API}/{method}", data=body, method="POST")
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.loads(r.read().decode("utf-8"))

# 1. Create lightweight account. Telegram login is not required.
acct = post("createAccount", {
    "short_name": "Hermes",
    "author_name": "Hermes Agent",
})
assert acct.get("ok"), acct
access_token = acct["result"]["access_token"]

# 2. Telegraph content nodes. Keep it simple.
content = [
    {"tag": "h3", "children": ["Инструкция"]},
    {"tag": "p", "children": ["Короткий публичный handoff для другого агента."]},
    {"tag": "pre", "children": ["curl example or code block here"]},
    {"tag": "p", "children": [
        {"tag": "a", "attrs": {"href": "https://example.com"}, "children": ["example link"]}
    ]},
]

# 3. Create page.
page = post("createPage", {
    "access_token": access_token,
    "title": "Название инструкции",
    "author_name": "Hermes Agent",
    "content": json.dumps(content, ensure_ascii=False),
    "return_content": "false",
})
assert page.get("ok"), page
print(page["result"]["url"])

Пример конвертации простого markdown

Для быстрых одноразовых ссылок достаточно грубой конвертации:

• строка # Заголовок → {tag: "h3"};
• строка ## Раздел → {tag: "h4"};
• fenced code block → {tag: "pre"};
• обычный блок текста → {tag: "p"};
• важные URL можно заворачивать в {tag: "a", attrs: {href: url}}.

Не обязательно добиваться идеального markdown-рендера. Цель — быстро получить читаемую публичную ссылку.

Проверка результата

• API createPage вернул ok: true.
• Есть result.url вида https://telegra.ph/....
• Ссылка открывается без авторизации.
• В тексте нет секретов и приватных данных.
• Если документ важный, canonical copy сохранена в Trip2G/Obsidian.

Fallback и ошибки

• 401/ошибка токена при редактировании: потерян или неверен access_token; проще создать новую страницу.
• Страница создана, но редактировать нельзя: токен/path не сохранены. Считать страницу одноразовой.
• Слишком сложная структура: упростить до h3, h4, p, pre, a.
• Нужна долговременная публичная база: публиковать в Trip2G, а telegra.ph использовать только как временную/быструю ссылку.

Связано

• Инструкция для агента: вести логи исследования и синкать базу
• Инструкция Trekopes MCP: генерация и watcher