理脈 limai

理華與理月的共享神經系統——從角色中按第一性原理提取的獨立器官。

第一性原理推斷

捨棄的：角色的 LLM 任務提示詞（人格不放入）、記憶的 JS eval 觸發器（作為安全防線）。 保留的精髓：加權隨機排程概念 → 心跳退避；STALE_READ 守衛；SSRF 防護；有界讀取。

啟動

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

CLI 為 AI agent 而設計

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 契約：

• 輸出預設 JSON、錯誤碼前綴進 stderr 訊息（STALE_READ: …）、退出碼非零表失敗

• fs edit 契約與 MCP 相同：需先 fs read；觀測狀態持久化於 fs-state.json， fs 子命令會跨呼叫保存狀態、edit 的 read/edit 也會跨呼叫；外部異動必被攔截（--force 可跳過）

• 成功的 fs write 亦建立觀測，可接 edit（同 o-pi「接續成功的 write」規則）

架構上 MCP 只是核心模組之上的一種介面：同一套 vision/web/filesys/memory/todo/heartbeat 同時供應 CLI 子命令與 MCP 工具呼叫，介面共享同樣的數據與安全契約。
首次執行會自動建立 ~/.limai/（含 config.json・memory.json・todo.json・vitals.*・screenshots/）並印出 token。

客戶端接入

本機（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 類用戶大多不能自訂 headers，故支援 query 傳送 token）。長期方案：Tailscale Funnel（免開埠）或 Caddy 反代自有網域。

安全邊界

• 檔案：限制在 config.json 的 allowedRoots； .git 永久阻擋；fs_edit 必須先 fs_read（STALE_READ 版本守衛）；old 文本必須唯一

• 網路：拒絶 localhost/私網/link-local（SSRF 防護）、重定向逐跳複檢、2 MB 上限、30 秒逾時

• 認證：HTTP 全程 Bearer/query-token；預設只綁 127.0.0.1

• 隱私：心跳只紀錄窗格、標題與剪貼簿 hash（變化時存放前 60 字元預覽）；像素截圖僅限明確呼叫 screen_capture 時

心跳語義（沿襲理華）

每 15 分鐘一跳，時間可調於 heartbeat.intervalMin。每次心跳收集：前景視窗、窗格清單（前 8）、閒置秒數、剪貼簿變化、開放待辦數。失敗時間隔 ×2（上限 8×），成功後重置；記錄滾動寫入 vitals.ndjson。

上游同步（o-pi）

• 2026-08-23 檢查：上游當日大量提交為內部重構（簡化 file-tools/web-tools/filesys/lsp），六工具＋兩網頁工具行為契約不變； duckduckgo- 的 html-provider 仍為零 key 的備援路徑，通過檢查。Model 的提取仍然忠實。

• 新能力 read 支援 PDF 頁面影像（d762209）：fs_read 遇到 .pdf 回傳結構化錯誤 UNSUPPORTED_MEDIA_PDF（引入 PDF 會破壞零依賴原則，列為候選 roadmap）。

• skill URI／bash 工具／approval gate 屬 Pi host 專用，不在提取範圍。

• 同日二檢（d795f92 new approval UI）：僅動 src/approval/* 與 TUI，file-tools/web-tools 零變更。grep 契約由此對齊：非法正規表示式降級為精確字面比對；有 matched → 回傳 literal_fallback 警告；無 matched → 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（Pi Agent 的 PT 內容 AGPL-3.0）。理脈為其中的精化代表，為 Node.js 零重依賴實作，非 copy systemcode，依 AGPL 相同條件回饋開源。

• 心跳／todo／memory／視覺等功能原語の提取源，來自 fount 生態中的「理華」角色設計（MIT license）。僅採用其架構思想（dispatch backoff、weighted task、name×keyword×content memory），未複製該 code。

• MCP 協議用官方 @modelcontextprotocol/sdk 實現。