理脈 limai

Lihua and Liyue's shared nervous system — an independent organ extracted from the characters via first principles.

First-principles derivation

Discarded: the character's LLM task prompts (personality not carried over) and the JS eval triggers in memory (safety). Retained: the weighted‑random scheduling idea → heartbeat backoff; the STALE_READ guard; SSRF protection; bounded reads.

Launch

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

CLI designed for AI agents

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 …       # 同前

Agent contract:

• Output is JSON by default; error code prefixes go into stderr messages (STALE_READ: …); a non‑zero exit code means failure.

• fs edit follows the same strict contract as MCP: fs read must come first; the observed state persists in fs-state.json, so the "read run → edit run" rule still holds across calls, and external changes are always intercepted (--force can bypass it).

• A successful fs write also builds the observation and can be followed by edit (same as o-pi's "immediately after a successful write" rule).

Architecturally, MCP is just one interface above the core modules: the same vision/web/filesys/memory/todo/heartbeat set is used for both CLI subcommands and MCP tools, and the two interfaces share the same data and the same security contract.

First run automatically creates ~/.limai/ (config, etc.) and prints a token.

Client integration

Local (stdio)

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

LAN / same-host GPT clients (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>" } }

Cloud ChatGPT (Connectors / developer mode)

ChatGPT can't reach your localhost; you need public HTTPS — one line of tunnel:

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

Set the connector URL to https://xxxx.trycloudflare.com/mcp?token=<token> (most GPT‑class clients can't set custom headers, so passing the token via query string is supported). Long-term options: Tailscale Funnel (no port exposure) or a Caddy reverse proxy on your own domain.

Security boundaries

• Files: locked to allowedRoots in config.json; .git is always blocked; fs_edit must run after fs_read (STALE_READ version guard); the old text must be unique.

• Network: rejects localhost/private/link-local addresses (SSRF protection), re-validates every redirect hop, 2 MB cap, 30‑second timeout.

• Auth: HTTP is always Bearer/query-token; by default it binds only to 127.0.0.1.

• Privacy: heartbeat records only window titles plus a clipboard hash (with a 60‑character preview when it changes); pixel screenshots only on explicit screen_capture.

Heartbeat semantics (following Lihua)

A beat every 15 minutes (heartbeat.intervalMin configurable). Each beat collects: foreground window, window list (top 8), idle seconds, clipboard state, and open todo count. On failure the interval ×2 (max ×8); on success it resets. Logs are appended in vitals.ndjson.

Upstream sync (o-pi)

• 2026-08-23 check: that day's large upstream commit batch was internal refactoring (file-tools/web-tools/filesystem/lsp simplification), and the behavior contracts of the six file tools and the two web tools are unchanged; duckduckgo-html-provider remains the zero-key fallback path, so the limai extraction is still faithful.

• New capability read supports PDF page images (d762209): limai's fs.read returns a structured error UNSUPPORTED_MEDIA_PDF for .pdf (adding pdfjs violates the zero-dependency principle, so it's listed as a roadmap candidate).

• skill URI / bash tools / approval gate are Pi-specific and not in the extraction scope.

• Same-day double check (d795f92 new approval UI): only touched src/approval/* and the TUI; file-tools/web-tools had zero changes. Based on this, the grep contract alignment is complete: an invalid regex falls back to exact literal matching — if it matches, it returns a literal_fallback warning; if it matches nothing, INVALID_REGEX instead of masquerading an empty result. Tested.

License & Attribution

This project is released under GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full terms.

Source provenance:

• The behavioral contracts and design of the file tools (src/core/filesys.mjs: ls/read/write/edit/find/grep) and web tools (src/core/web.mjs: web_search/web_fetch) derive from Orion-zhen/o-pi (Pi Agent's file-tools and web-tools design docs, AGPL-3.0). limai is an independent zero-dependency Node.js implementation of their essence, not a code copy, and is open-sourced under the same AGPL terms.

• The extraction blueprint for primitives such as heartbeat / todo / memory / vision comes from the capability design of the "心 flow" character in the steve02081504/fount ecosystem (MIT licensed). Only its architectural ideas were referenced (idle polling with backoff, weighted tasks, name × keyword × content) — no code copied.

• The MCP protocol implementation is based on the official @modelcontextprotocol/sdk.