@leviyuan/lodestar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 leviyuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/leviyuan/lodestar/main/promo.jpg" alt="夜航星 Lodestar" width="100%">
+</p>
+
+# 夜航星 (Lodestar)
+
+**在你最熟悉的飞书群里，开一段不熄灯的 Claude Code 会话。**
+
+## 项目哲学
+
+AI 不是帮手，是倍率。它放大的不是体力，是你——你的直觉、判断和品味，每一样都被乘以一个你以前不敢想的系数。最终走多远，取决于被放大的你有多强。
+
+夜航星让这件事真正发生：在你思考的地方接住想法，在你转身之后继续把它推向终点。一个群，一个项目，一段不熄灯的对话。你醒着它在听，你睡了它还在跑。
+
+## 怎么用
+
+每个飞书群对应一个 Claude 会话。**群名 = `~/` 下的项目目录名**。
+
+- 在群里发任意文字 — Claude 接管这一轮，回复以**流式打字机**实时渲染在一张飞书卡片里。
+- 思考过程、每一次工具调用都在卡片里被收纳为**可展开折叠面板**：折起来是概述，展开是详情。你随时能审阅它在做什么。
+- 需要授权的操作（执行命令、修改文件……）会单独弹一张橙色**权限卡片**，你在群里点 `允许` / `始终允许` / `拒绝` 就行。
+- **图片、文件双向互传**：用户发到群里的图/文件，Claude 通过消息里的 `[file: /abs/path]` 提示就能读；Claude 想把文件发回来，在回复任意位置写 `[[send: /abs/path]]`，标记会被剥离，文件以独立消息出现在群里。出站路径限制在该会话的工作目录、`/tmp/lodestar-*` 与 inbox 之内，`/etc`、`~/.ssh`、`~/.config` 等敏感目录被白名单拒绝。
+- 一轮跑完，卡片合上、可转发；下一句话开新一轮。
+
+### 文本控制指令
+
+直接发这四个**裸词**（不需要斜杠，不区分大小写），daemon 拦截、不转发给 Claude：
+
+| 指令 | 行为 |
+| --- | --- |
+| `hi` | 未运行时启动；运行中弹一张**控制台卡片**（状态行 + 中断/clear/终止/ls 按钮） |
+| `kill` | 优雅关闭 Claude 进程；记住 `sessionId`，下次 `restart` 还能 resume |
+| `restart` | 用上一次的 `sessionId` 重启会话（保留上下文） |
+| `clear` | 杀掉进程并启动一个全新 session（等价于 Claude Code 的 `/clear`） |
+
+> 这四个词被全局保留：在群里发 "hi" 当问候也会触发控制台卡片，不会到 Claude 那边。换来的是手机上单手打字的便利。
+
+整个对话在群里、在手机上、在桌面上完整发生。**离开终端，但不离开 Claude Code。**
+
+## 安装
+
+### 1. 准备
+
+- 一台能常跑后台进程的机器（自家服务器或闲置主机）
+- [Bun](https://bun.sh) 运行时
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已登录 Anthropic 账号 (`claude auth login`)
+- 一个飞书自建应用 (`cli_xxx`)，开通：
+  - `im:message:send_as_bot` / `im:message` / `im:chat:readonly` / `im:resource`
+  - `cardkit:card:read` `cardkit:card:write`
+    `cardkit:card.element:read` `cardkit:card.element:write`
+    `cardkit:card.settings:read` `cardkit:card.settings:write`
+
+### 2. 配置
+
+把凭据写到 `~/.config/lodestar/config.toml`：
+
+```toml
+[feishu]
+app_id     = "cli_xxxxxxxxxxxxxxxx"
+app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+[runtime]
+projects_root = "~/"        # 可选，新建群对应的项目目录会落到这里
+```
+
+也支持 `LODESTAR_CONFIG=/abs/path.toml` 或 `XDG_CONFIG_HOME` 覆盖。
+
+### 3. 启动
+
+```bash
+git clone https://github.com/leviyuan/lodestar.git ~/lodestar
+cd ~/lodestar
+bun install
+bun daemon.ts
+```
+
+把机器人拉进任意飞书群，发一条消息——Claude 就上线了。
+
+> **小贴士**：群名首次出现时，daemon 会自动在 `~/{群名}/` 创建项目目录并 `git init`。换句话说，开新群 = 开新项目。
+
+### 4. 守护进程（可选）
+
+要让 daemon 7×24 跑，最简单的方法是配一个 `systemd --user` 单元：
+
+```ini
+[Unit]
+Description=Lodestar daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/home/USER/.bun/bin/bun /home/USER/lodestar/daemon.ts
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target
+```
+
+`systemctl --user enable --now lodestar`。
+
+## 许可
+
+[MIT](LICENSE)

package/daemon.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env bun
+/**
+ * Lodestar 2.0 daemon — Feishu (Lark) ↔ Claude Code headless bridge.
+ *
+ * Listens on Lark WebSocket for inbound messages and card-action
+ * callbacks, routes each to a per-chat Session that owns a headless
+ * `claude` subprocess and a streaming Card Kit card.
+ *
+ * Run:   bun daemon.ts
+ * Stop:  SIGTERM
+ */
+
+import * as lark from '@larksuiteoapi/node-sdk'
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { Session } from './src/session'
+import * as feishu from './src/feishu'
+import { config } from './src/config'
+import { log } from './src/log'
+import { PID_FILE } from './src/paths'
+
+// ── PID guard ───────────────────────────────────────────────────────────
+try {
+  const existing = readFileSync(PID_FILE, 'utf8').trim()
+  try {
+    process.kill(Number(existing), 0)
+    console.error(`lodestar-daemon: already running (pid ${existing})`)
+    process.exit(1)
+  } catch {}
+} catch {}
+
+mkdirSync(dirname(PID_FILE), { recursive: true })
+writeFileSync(PID_FILE, String(process.pid))
+
+const cleanup = () => { try { unlinkSync(PID_FILE) } catch {} }
+process.on('exit', cleanup)
+process.on('SIGTERM', () => { log('SIGTERM'); cleanup(); process.exit(0) })
+process.on('SIGINT',  () => { log('SIGINT');  cleanup(); process.exit(0) })
+process.on('unhandledRejection', e => log(`unhandledRejection: ${e}`))
+process.on('uncaughtException',  e => log(`uncaughtException: ${e}`))
+
+// ── Session registry ────────────────────────────────────────────────────
+const sessions = new Map<string, Session>()  // key = chatId
+
+function sessionFor(chatId: string, sessionName: string): Session {
+  let s = sessions.get(chatId)
+  if (!s) {
+    s = new Session(sessionName, chatId)
+    sessions.set(chatId, s)
+  }
+  return s
+}
+
+// ── Inbound message handler ─────────────────────────────────────────────
+const STALE_THRESHOLD_MS = 10_000
+const seenMessageIds = new Set<string>()
+
+async function handleMessage(data: any): Promise<void> {
+  const message = data?.message
+  if (!message) return
+
+  const msgId = message.message_id as string | undefined
+  if (msgId && seenMessageIds.has(msgId)) return
+  if (msgId) {
+    seenMessageIds.add(msgId)
+    if (seenMessageIds.size > 200) {
+      const arr = [...seenMessageIds]
+      seenMessageIds.clear()
+      for (const id of arr.slice(-100)) seenMessageIds.add(id)
+    }
+  }
+
+  // Drop replays of stale messages (Lark redelivers unacked events on reconnect).
+  const createTime = Number(message.create_time ?? 0)
+  if (createTime > 0 && Date.now() - createTime > STALE_THRESHOLD_MS) {
+    log(`drop stale message ${msgId} age=${Math.round((Date.now() - createTime) / 1000)}s`)
+    if (msgId) void feishu.addReaction(msgId, 'CrossMark')
+    return
+  }
+  if (msgId) void feishu.addReaction(msgId, 'OK')
+
+  const chatId = message.chat_id as string
+  let groupName = feishu.chatNameCache.get(chatId)
+  if (!groupName) {
+    await feishu.refreshChatList()
+    groupName = feishu.chatNameCache.get(chatId)
+  }
+  if (!groupName) {
+    log(`unknown chat ${chatId}, dropping message`)
+    await feishu.sendText(chatId, '❌ 无法识别群名，请确认机器人已加入并稍后重试')
+    return
+  }
+  const sessionName = feishu.sanitizeSessionName(groupName)
+  feishu.bindSessionToChat(sessionName, chatId)
+  const session = sessionFor(chatId, sessionName)
+
+  let contentObj: any = {}
+  try { contentObj = JSON.parse(message.content ?? '{}') } catch {}
+  const msgType = message.message_type as string
+  let text = (msgType === 'text' ? contentObj.text ?? '' : '').trim()
+
+  // Text-only control commands — intercept before any work that would
+  // forward to Claude (download / spawn / interrupt). Exact match,
+  // case-insensitive: `hi` `kill` `restart` `clear`. Bare words are
+  // reserved globally by user request — typing "hi" as a literal
+  // greeting will trigger the dashboard, not reach Claude.
+  if (msgType === 'text' && text) {
+    if (await session.runCommand(text)) return
+  }
+
+  let filePath: string | undefined
+  if (msgType === 'image' && contentObj.image_key) {
+    filePath = await feishu.downloadAttachment(message.message_id, contentObj.image_key, 'image')
+  } else if (msgType === 'file' && contentObj.file_key) {
+    filePath = await feishu.downloadAttachment(message.message_id, contentObj.file_key, 'file', contentObj.file_name)
+    if (!text) text = `(file: ${contentObj.file_name})`
+  }
+
+  if (!text && !filePath) return
+  await session.onUserMessage(text || '(empty)', filePath ? [filePath] : [])
+}
+
+// ── Card action handler ────────────────────────────────────────────────
+async function handleCardAction(data: any): Promise<any> {
+  const action = data?.action
+  const value = action?.value
+  if (!value?.kind) return
+  const chatId = data?.context?.open_chat_id ?? ''
+  const userId = data?.operator?.open_id ?? ''
+  const session = sessions.get(chatId)
+  if (!session) return { toast: { type: 'error', content: '会话不存在，请先发消息启动' } }
+
+  switch (value.kind) {
+    case 'permission':
+      await session.onPermissionDecision(value.request_id, value.decision, userId)
+      return { toast: { type: value.decision === 'deny' ? 'error' : 'success', content: '已处理' } }
+    case 'console':
+      await session.onConsoleAction(value.action)
+      return { toast: { type: 'info', content: value.action } }
+    case 'menu':
+      await session.onUserMessage(`(menu choice ${value.choice + 1})`)
+      return { toast: { type: 'success', content: 'OK' } }
+  }
+  return { toast: { type: 'info', content: 'unknown action' } }
+}
+
+// ── WebSocket boot ─────────────────────────────────────────────────────
+function fmt(m: any[]): string {
+  return m.map(x => typeof x === 'string' ? x : JSON.stringify(x)).join(' ')
+}
+
+async function boot(): Promise<void> {
+  log(`lodestar-daemon: pid ${process.pid} starting`)
+  feishu.loadSessionChatMap()
+  await feishu.refreshChatList()
+  setInterval(() => { void feishu.refreshChatList() }, 5 * 60 * 1000)
+
+  // Lark WSClient sends pings every ~120s but doesn't verify pongs. On a
+  // half-open TCP (NAT idle-kill, network blip) the socket stays OPEN and
+  // 'close' never fires — we'd go silently deaf. Stamp every inbound pong
+  // and exit(1) after 180s of silence so systemd reconnects us.
+  let lastPongAt = Date.now()
+  const wsLogger = {
+    error: (m: any[]) => log(`[ws-sdk error] ${fmt(m)}`),
+    warn:  (m: any[]) => log(`[ws-sdk warn] ${fmt(m)}`),
+    info:  (m: any[]) => log(`[ws-sdk] ${fmt(m)}`),
+    debug: (_m: any[]) => { /* drop */ },
+    trace: (m: any[]) => {
+      if (Array.isArray(m) && m[0] === '[ws]' && m[1] === 'receive pong') {
+        lastPongAt = Date.now()
+      }
+    },
+  }
+  setInterval(() => {
+    const idle = Date.now() - lastPongAt
+    if (idle > 180_000) {
+      log(`[watchdog] no WS pong for ${Math.round(idle / 1000)}s — exit for systemd restart`)
+      process.exit(1)
+    }
+  }, 30_000)
+
+  const ws = new lark.WSClient({
+    appId: config.feishu.app_id,
+    appSecret: config.feishu.app_secret,
+    loggerLevel: lark.LoggerLevel.trace,
+    logger: wsLogger,
+  })
+  const dispatcher = new lark.EventDispatcher({})
+  dispatcher.register({
+    'im.message.receive_v1': async (d: any) => {
+      try { await handleMessage(d) } catch (e) { log(`handleMessage: ${e}`) }
+    },
+  })
+  dispatcher.register({
+    'card.action.trigger': async (d: any) => {
+      try { return await handleCardAction(d) } catch (e) { log(`handleCardAction: ${e}`) }
+    },
+  })
+  ws.start({ eventDispatcher: dispatcher })
+  log(`lodestar-daemon: WS started, watching ${feishu.chatNameCache.size} groups`)
+}
+
+boot().catch(e => { log(`boot fatal: ${e}`); process.exit(1) })

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@leviyuan/lodestar",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Lodestar (夜航星) — IM-native frontend for Claude Code via Feishu Card Kit streaming",
+  "type": "module",
+  "license": "MIT",
+  "author": "leviyuan",
+  "homepage": "https://github.com/leviyuan/lodestar#readme",
+  "bugs": "https://github.com/leviyuan/lodestar/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leviyuan/lodestar.git"
+  },
+  "keywords": [
+    "feishu",
+    "lark",
+    "claude-code",
+    "claude",
+    "ai",
+    "agent",
+    "im",
+    "chat",
+    "card-kit",
+    "streaming",
+    "lodestar"
+  ],
+  "scripts": {
+    "start": "bun daemon.ts"
+  },
+  "bin": {
+    "lodestar-daemon": "./daemon.ts"
+  },
+  "files": [
+    "daemon.ts",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.44.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.5.0"
+  }
+}

package/src/cardkit.ts

@@ -0,0 +1,215 @@
+/**
+ * Feishu Card Kit v1 wrapper.
+ *
+ * Endpoints used (base = https://open.feishu.cn/open-apis/cardkit/v1):
+ *   POST   /cards/id_convert                              message_id → card_id
+ *   POST   /cards                                         create a card entity
+ *   PUT    /cards/:card_id/elements/:element_id/content   stream text (typewriter)
+ *   POST   /cards/:card_id/elements                       add element
+ *   PUT    /cards/:card_id/elements/:element_id           replace element
+ *   DELETE /cards/:card_id/elements/:element_id           remove element
+ *   PATCH  /cards/:card_id/settings                       toggle streaming_mode etc.
+ *
+ * Per-card invariants enforced here:
+ *   - `sequence` is monotonically increasing per card_id
+ *   - all writes for a card are serialized through a Promise queue
+ *   - text-streaming PUTs are batched on a 120ms / 32-char heuristic to
+ *     stay well under cardkit's per-card rate ceiling
+ */
+
+import { getTenantToken } from './feishu'
+import { log } from './log'
+
+const BASE = 'https://open.feishu.cn/open-apis/cardkit/v1'
+
+const FLUSH_INTERVAL_MS = 120
+const FLUSH_MIN_DELTA = 32
+
+interface CardState {
+  sequence: number
+  queue: Promise<void>
+  buffer: Map<string, string>          // element_id → latest full text
+  lastSent: Map<string, string>        // element_id → text last actually PUT
+  flushTimer: ReturnType<typeof setTimeout> | null
+}
+
+const cards = new Map<string, CardState>()
+
+function state(cardId: string): CardState {
+  let s = cards.get(cardId)
+  if (!s) {
+    s = {
+      sequence: 0,
+      queue: Promise.resolve(),
+      buffer: new Map(),
+      lastSent: new Map(),
+      flushTimer: null,
+    }
+    cards.set(cardId, s)
+  }
+  return s
+}
+
+function nextSeq(cardId: string): number {
+  const s = state(cardId)
+  s.sequence += 1
+  return s.sequence
+}
+
+async function call(method: string, path: string, body?: object): Promise<any> {
+  const token = await getTenantToken()
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  })
+  const json = await res.json() as any
+  if (json?.code && json.code !== 0) {
+    throw new Error(`cardkit ${method} ${path}: code=${json.code} msg=${json.msg}`)
+  }
+  return json?.data
+}
+
+/** Convert a sent interactive message into a card entity. */
+export async function convertMessageToCard(messageId: string): Promise<string> {
+  const data = await call('POST', '/cards/id_convert', { message_id: messageId })
+  return data.card_id
+}
+
+/** Create a card entity from raw schema-2.0 card JSON. */
+export async function createCardEntity(card: object): Promise<string> {
+  const data = await call('POST', '/cards', {
+    type: 'card_json',
+    data: JSON.stringify(card),
+  })
+  return data.card_id
+}
+
+/** PUT element content (full text) — triggers typewriter on prefix-match.
+ *
+ * NOTE: CardKit rejects empty-string content with code 99992402 ("field
+ * validation failed"); we drop empty/whitespace-only writes here so callers
+ * can stream naively without per-call empty checks. */
+export function streamText(cardId: string, elementId: string, content: string): Promise<void> {
+  if (!content || !content.trim()) return Promise.resolve()
+  const s = state(cardId)
+  const seq = nextSeq(cardId)
+  s.queue = s.queue.then(async () => {
+    try {
+      await call('PUT', `/cards/${cardId}/elements/${elementId}/content`, {
+        content, sequence: seq,
+      })
+      s.lastSent.set(elementId, content)
+    } catch (e) {
+      log(`cardkit streamText ${cardId}/${elementId}: ${e}`)
+    }
+  })
+  return s.queue
+}
+
+/** Throttled streaming: buffer + auto-flush every FLUSH_INTERVAL_MS or
+ * when the buffered delta crosses FLUSH_MIN_DELTA characters. */
+export function streamTextThrottled(cardId: string, elementId: string, fullContent: string): void {
+  if (!fullContent || !fullContent.trim()) return
+  const s = state(cardId)
+  s.buffer.set(elementId, fullContent)
+
+  const last = s.lastSent.get(elementId) ?? ''
+  const delta = fullContent.length - last.length
+  if (delta >= FLUSH_MIN_DELTA) {
+    flush(cardId).catch(e => log(`cardkit flush(min-delta) ${cardId}: ${e}`))
+    return
+  }
+  if (!s.flushTimer) {
+    s.flushTimer = setTimeout(() => {
+      flush(cardId).catch(e => log(`cardkit flush(timer) ${cardId}: ${e}`))
+    }, FLUSH_INTERVAL_MS)
+  }
+}
+
+/** Force an immediate flush of the buffered streams for a card. */
+export async function flush(cardId: string): Promise<void> {
+  const s = cards.get(cardId)
+  if (!s) return
+  if (s.flushTimer) { clearTimeout(s.flushTimer); s.flushTimer = null }
+  const pending = [...s.buffer.entries()]
+  s.buffer.clear()
+  for (const [eid, text] of pending) {
+    if (s.lastSent.get(eid) === text) continue
+    await streamText(cardId, eid, text)
+  }
+}
+
+/** Add a new element to the card body or relative to a sibling. */
+export function addElement(
+  cardId: string,
+  element: object,
+  opts: { type?: 'append' | 'insert_before' | 'insert_after'; targetElementId?: string } = {},
+): Promise<void> {
+  const s = state(cardId)
+  const seq = nextSeq(cardId)
+  s.queue = s.queue.then(async () => {
+    try {
+      await call('POST', `/cards/${cardId}/elements`, {
+        type: opts.type ?? 'append',
+        ...(opts.targetElementId ? { target_element_id: opts.targetElementId } : {}),
+        elements: JSON.stringify([element]),
+        sequence: seq,
+      })
+    } catch (e) { log(`cardkit addElement ${cardId}: ${e}`) }
+  })
+  return s.queue
+}
+
+/** Replace an entire element (used to swap a tool placeholder with its result). */
+export function replaceElement(cardId: string, elementId: string, element: object): Promise<void> {
+  const s = state(cardId)
+  const seq = nextSeq(cardId)
+  s.queue = s.queue.then(async () => {
+    try {
+      await call('PUT', `/cards/${cardId}/elements/${elementId}`, {
+        element: JSON.stringify(element),
+        sequence: seq,
+      })
+    } catch (e) { log(`cardkit replaceElement ${cardId}/${elementId}: ${e}`) }
+  })
+  return s.queue
+}
+
+/** Delete an element by id. */
+export function deleteElement(cardId: string, elementId: string): Promise<void> {
+  const s = state(cardId)
+  const seq = nextSeq(cardId)
+  s.queue = s.queue.then(async () => {
+    try {
+      await call('DELETE', `/cards/${cardId}/elements/${elementId}`, {
+        sequence: seq,
+      })
+    } catch (e) { log(`cardkit deleteElement ${cardId}/${elementId}: ${e}`) }
+  })
+  return s.queue
+}
+
+/** Patch settings — used to flip streaming_mode off when a turn finishes. */
+export function patchSettings(cardId: string, settings: object): Promise<void> {
+  const s = state(cardId)
+  const seq = nextSeq(cardId)
+  s.queue = s.queue.then(async () => {
+    try {
+      await call('PATCH', `/cards/${cardId}/settings`, {
+        settings: JSON.stringify(settings),
+        sequence: seq,
+      })
+    } catch (e) { log(`cardkit patchSettings ${cardId}: ${e}`) }
+  })
+  return s.queue
+}
+
+/** Drop in-memory bookkeeping for a finished card. */
+export async function dispose(cardId: string): Promise<void> {
+  const s = cards.get(cardId)
+  if (!s) return
+  await flush(cardId)
+  await s.queue
+  cards.delete(cardId)
+}