理脈 limai

Общая нервная система Ли Хуа и Ли Юэ — самостоятельный орган, извлечённый из персонажей по первым принципам.

Вывод из первых принципов

Отброшено: LLM-промпты персонажей (личность не переносится), JS-eval-триггер для памяти (безопасность). Сохранена суть: идея взвешенного случайного планирования → backoff в пульсе; защита по механизму STALE_READ; защита от SSRF; ограниченное чтение.

Запуск

npm install
npm run start          # ① stdio → Claude Desktop / Cursor 等本地客戶端
npm run serve:http     # ② HTTP MCP → GPT 客戶端 / 區網 / 遠端
npm run tick           # ③ 手動跑一次心跳（驗證感知層）

CLI спроектирован для AI-агентов

limai shot                       # → {"file":...,"width":1920,"height":1080,"bytes":...}
limai win                        # → {"foreground":...,"windows":[{process,title},…]}
limai clip [--json]              # 剪貼簿原文走 stdout（利於管線）
limai tick                       # 心跳一次，生命徵象 JSON
limai web search <q>             # → [{title,url,snippet},…]
limai web fetch <url>            # 正文走 stdout、中繼 stderr；--json 得全包裝
limai fs ls|read|write|edit|find|grep …
limai mem … / limai todo …       # 同前

Контракт для агента:

• Вывод по умолчанию в JSON, коды ошибок с префиксом попадают в сообщения stderr (STALE_READ: …), ненулевой код выхода означает сбой.

• fs edit подчиняется тому же строгому контракту, что и MCP: обязателен предварительный fs read; состояние наблюдения сохраняется в fs-state.json, инвариант «проход чтения → проход правки» выполняется при последовательных вызовах, внешние изменения обязательно перехватываются (обход возможен через --force).

• Успешный fs write также создаёт наблюдение и допускает последующий edit (по тому же правилу o-pi «сразу после успешного write»).

Архитектурно MCP — лишь один из интерфейсов поверх базовых модулей: один и тот же набор vision/web/filesys/memory/todo/heartbeat одновременно доступен и для subcommand CLI, и для вызовов MCP-инструментов; оба интерфейса используют одни данные и один контракт безопасности. `

При первом запуске автоматически создаётся ~/.limai/ (config.json・memory.json・todo.json・vitals.\*・screenshots/) и выводится токен.

Подключение клиентов

Локально (stdio)

// claude_desktop_config.json
{ "mcpServers": { "limai": { "command": "node", "args": ["F:\\fount開發項目\\理脈\\src\\cli.mjs", "serve", "--stdio"] } } }

Локальная сеть / GPT-клиенты на той же машине (Cherry Studio, LobeChat, OpenWebUI…)

node src/cli.mjs serve --http                # 預設 127.0.0.1:8931
# 對區網開放：--host 0.0.0.0 --token <強密碼>

{ "type": "http", "url": "http://192.168.x.x:8931/mcp",
  "headers": { "Authorization": "Bearer <token>" } }

Облачный ChatGPT (Connectors / режим разработчика)

ChatGPT не может достучаться до твоего localhost — нужен публичный HTTPS: одна команда туннеля:

cloudflared tunnel --url http://127.0.0.1:8931
# → https://xxxx.trycloudflare.com

В URL коннектора укажите https://xxxx.trycloudflare.com/mcp?token=<token> (GPT-клиенты чаще всего не позволяют задавать собственный заголовок, поэтому поддерживается передача токена через query). Долгосрочное решение: Tailscale Funnel (без открытия портов) либо обратный прокси Caddy на своём домене.

Границы безопасности

• Файлы: ограничение по allowedRoots из config.json; .git блокируется навсегда; fs_edit требует предварительный fs_read (стража версии STALE_READ); старый текст должен быть уникальным.

• Сеть: отказ для localhost/частных адресов/link-local (защита от SSRF), повторная проверка редиректов на каждом хопе, лимит 2 МБ, таймаут 30 секунд.

• Аутентификация: на всём HTTP — Bearer/query-token; по умолчанию привязка только к 127.0.0.1.

• Конфиденциальность: пульс запоминает только заголовок окна и hash буфера обмена (при изменении сохраняется превью первых 60 символов); пиксельные скриншоты — только при явном вызове screen_capture.

Семантика пульса (по образцу Ли Хуа)

Один цикл каждые 15 минут (настраивается через heartbeat.intervalMin). Каждый цикл собирает: активное окно, список окон (top 8), время бездействия в секундах, изменения буфера обмена, число открытых TODO-задач. При сбое интервал увеличивается в 2 раза (потолок 8×), при успехе — возвращается к исходному. Журнал ведётся с ротацией в vitals.ndjson.

Синхронизация с upstream (o-pi)

• Проверка от 2026-08-23: массовые коммиты того дня — внутренний рефакторинг (упрощение file-tools/web-tools/filesystem/lsp), поведение шести инструментов и двух веб-инструментов не изменилось; duckduckgo-html-provider остаётся резервным путём без ключа — извлечение limai по-прежнему честное.

• Новая возможность read поддерживает постраничные изображения PDF (d762209): fs_read в limai на .pdf возвращает структурированную ошибку UNSUPPORTED_MEDIA_PDF (подключение pdfjs нарушило бы принцип ноль внешних зависимостей — внесено в roadmap).

• skill URI / инструмент bash / approval gate принадлежат только ходу Pi, в извлечение не входят.

• Повторная проверка тем же днём (d795d92 new approval UI): затронуты только src/approval/* и TUI, file-tools/web-tools — без изменений. По этому было завершено выравнивание контракта grep': недопустимое регулярное выражение понижается до точного литерала — при совпадениях выводится предупреждение literal_fallback; при их отсутствии возвращается INVALID_REGEX, а не «пустой результат». Протестировано.

Лицензия и источники (License & Attribution)

Проект публикуется под GNU Affero General Public License v3.0 или новее (AGPL-3.0-or-later). Полных условия — LICENSE.

Заявление об источниках кода:

• Файловые инструменты (src/core/filesys.mjs: ls/read/write/edit/find/grep) и веб-инструменты (src/core/web.mjs: web_search/web_fetch) — их поведенческий контракт и дизайн происходит из Orion-zhen/o-pi (документы по дизайну file-tools и web-tools опера Pi Agent, AGPL-3.0). limai — независимая реализацияNode.js с нулевыми зависимостями этой сути, а не копирование кода; она открыта на тех же лицензионных условиях AGPL.

• Образцы примитивов heartbeat / todo / memory / vision извлечены по образцу возможностей персонажа «理華» из экосистемы steve02081504/fount (MIT). Заимствована только архитектурная идея (опрос бездействия с backoff, взвешенные задачи, память «имя × ключевые слова × содержимое»), без копирования кода.

• Реализация протокола MCP основана на официальном @modelcontextprotocol/sdk.