im-agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qijieinnet
+
+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

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# im-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用飞书（以后还有 Telegram 等）和 Web 页面，驱动本机的 **Claude Code** 和 **Codex**。
+
+由 `feishu-claude-bridge` 和 `feishu-codex-bridge` 合并而来：一个进程、一份配置，飞书和网页共用同一套会话、审批和模型切换。
+
+## 能做什么
+
+- **多个 agent**：Claude Code（官方 Claude Agent SDK）、Codex（官方 `codex app-server`）。在同一条会话里 `/agent` 切换，各 agent 的上下文各自保留。
+- **多个飞书机器人**：一个机器人对应一个 agent，或者一个机器人能切换多个 agent，都在设置页里勾选。机器人能在 Web 上扫码创建，改完配置立即生效，不用重启。
+- **Web 聊天页**：电脑和手机都能用，界面参照 ChatGPT。
+  - 回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠。
+  - 授权卡、提问卡直接在页面上点。
+  - 支持上传附件（粘贴、拖拽，手机上可以拍照）。
+  - 可以「添加到主屏幕」当 App 用。手机切到后台再回来会自动重连，并补上错过的内容。
+- **跨渠道同步**：飞书里的会话在 Web 上也能打开，接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。
+- **设置都在网页上**：工作目录、各 agent 的默认模型和思考程度、Codex 沙箱、飞书机器人、配对批准、Claude 的「总是允许」名单、登录设备管理。
+
+## 安装
+
+```bash
+npm install -g im-agent         # 或者在仓库里 npm install 后用 node bin/cli.js
+im-agent start                  # 前台运行，日志里会打印首次登录用的设置码
+im-agent service install        # 注册为开机自启服务（systemd / launchd）
+```
+
+打开 `http://<机器 IP>:8800`：第一次需要输入日志里的设置码，然后设一个登录密码。
+
+### 从旧桥接器迁移
+
+```bash
+im-agent import --dry-run       # 先看会导入什么
+systemctl --user disable --now feishu-claude-bridge feishu-codex-bridge   # 同一个机器人不能被两个程序同时连
+im-agent import                 # 导入机器人凭据、白名单、配对、会话绑定、总是允许名单
+im-agent service install
+```
+
+导入后，飞书群里原来的会话会接着聊。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `im-agent start` | 启动 |
+| `im-agent import [--only claude\|codex] [--disabled] [--dry-run]` | 从旧桥接器导入 |
+| `im-agent pair list \| approve <码> \| revoke <机器人id> <open_id>` | 配对管理（Web 设置页里也能做） |
+| `im-agent passwd [新密码]` | 重置 Web 登录密码，所有设备下线 |
+| `im-agent service install \| uninstall \| restart \| status` | 开机自启 |
+| `im-agent doctor` | 体检 |
+
+聊天里的命令（飞书和 Web 通用）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/approve <id> allow-once|allow-always|deny` `/help`
+
+## 安全
+
+这个服务能让 agent 在你的机器上执行命令，等于一个远程 shell。
+
+- Web 登录密码用 scrypt 哈希保存。首次设置必须用启动日志里的一次性设置码，防止「谁先打开页面谁就成了主人」。
+- 登录态通过 HttpOnly cookie 保存，服务端只存它的哈希。同一 IP 连续输错 5 次锁 15 分钟。所有写请求和 WebSocket 都校验 Origin。页面开启了严格的 CSP。
+- 暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）访问，并把反代的 IP 加进 `web.trustedProxies`（只有从这些地址来的连接才采信 `X-Forwarded-*`）。不要直接把 8800 端口映射出去。
+- 审批超时一律按拒绝处理。Codex 默认沙箱为 `workspace-write`，不会因为 `~/.codex/config.toml` 里配了 `never` 或 `danger-full-access` 就绕过审批。
+- agent 子进程拿不到本服务自己的凭据（`FEISHU_*`、`IM_AGENT_*` 等环境变量会被剔除）。
+
+## 结构
+
+```
+src/
+  core/            与渠道、agent 都无关的中枢
+    hub.ts         会话调度：事件广播、命令、切 agent / 模型 / 目录
+    interactions.ts 审批与提问：一个请求，多个渠道都能处理
+    store.ts       会话持久化（每个 agent 的会话 id 各自保存）
+    config.ts      配置（Web 可改，改完热加载）
+    pairing.ts uploads.ts commands.ts …
+  agents/
+    claude/        Claude Agent SDK 驱动
+    codex/         codex app-server 驱动
+  channels/
+    feishu/        飞书：一个 FeishuBot 对应一个机器人，支持多个
+    web/           HTTP + WebSocket + 鉴权
+web/               前端（原生 JS，不需要构建）
+```
+
+### 接入新的消息渠道（比如 Telegram）
+
+参照 `channels/feishu/bot.ts`，做三件事：
+
+1. 收到消息 → `hub.ensure()` 建会话 → `parseCommand()`。是命令就调 `hub.command()`，再把 `CommandReply` 画出来；是聊天就调 `hub.send()`。
+2. 订阅 `hub.on("event")`，挑出自己的会话（键前缀如 `telegram:<botId>:`），把 step / text / result / error 画出来。
+3. 订阅 `interactions` 的 `created / updated / settled`，把授权卡和提问卡画成按钮。用户点击后调 `interactions.decide / select / submit / skip`。
+
+### 接入新的 agent
+
+实现 `core/types.ts` 里的 `AgentDriver`，然后在 `main.ts` 里 `hub.registerDriver()`。`AgentDriver` 包括开会话、发消息、中断、切模型、列历史、读历史，审批通过传入的 `InteractionHost` 发起。以后要接 ACP 协议的 agent（Gemini CLI、OpenCode 等），写一个通用的 ACP 驱动就行。
+
+## 开发
+
+```bash
+npm install
+npm run dev          # IM_AGENT_HOME=./.dev，改代码自动重启
+npm test
+npm run typecheck
+```

package/bin/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// 统一入口：im-agent <start|import|pair|passwd|service|doctor>
+//
+// 源码是 TypeScript，用 tsx 的 ESM loader 直接加载，装完即可运行，不需要先 build。
+import { register } from "tsx/esm/api";
+
+const COMMANDS = {
+  start: "../src/main.ts",
+  import: "../src/cli/import.ts",
+  pair: "../src/cli/pair.ts",
+  passwd: "../src/cli/passwd.ts",
+  service: "../src/cli/service.ts",
+  doctor: "../src/cli/doctor.ts",
+};
+
+const USAGE = `im-agent —— 用飞书 / Web 驱动本机的 Claude Code 和 Codex
+
+用法：
+  im-agent start            启动（默认命令）
+  im-agent import           从旧的 feishu-claude-bridge / feishu-codex-bridge 导入配置和会话
+  im-agent pair ...         配对管理：list | approve <配对码> | revoke <机器人id> <open_id>
+  im-agent passwd           重置 Web 登录密码
+  im-agent service ...      开机自启：install | uninstall | restart | status
+  im-agent doctor           体检：配置 / agent / 飞书连通性
+
+配置目录：~/.im-agent（可用 IM_AGENT_HOME 覆盖）
+`;
+
+const [, , rawCommand, ...rest] = process.argv;
+const command = rawCommand ?? "start";
+
+if (command === "-h" || command === "--help" || command === "help") {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+const target = COMMANDS[command];
+if (!target) {
+  process.stderr.write(`未知命令：${command}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+process.argv = [process.argv[0], process.argv[1], ...rest];
+
+register();
+try {
+  await import(new URL(target, import.meta.url).href);
+} catch (err) {
+  if (process.env.IM_AGENT_DEBUG) throw err;
+  process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "im-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "把飞书（以及以后的 Telegram 等）和 Web 页面桥接到本机 Claude Code / Codex：聊天驱动、卡片审批、会话与模型切换",
+  "keywords": [
+    "feishu",
+    "lark",
+    "claude-code",
+    "codex",
+    "bridge",
+    "agent",
+    "飞书"
+  ],
+  "license": "MIT",
+  "author": "qijieinnet",
+  "homepage": "https://github.com/qijieinnet/im-agent#readme",
+  "bugs": {
+    "url": "https://github.com/qijieinnet/im-agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qijieinnet/im-agent.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "im-agent": "bin/cli.js",
+    "ima": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js start",
+    "dev": "IM_AGENT_HOME=./.dev tsx watch src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.302",
+    "@highlightjs/cdn-assets": "^11.12.0",
+    "@larksuiteoapi/node-sdk": "^1.73.0",
+    "dompurify": "^3.2.0",
+    "marked": "^16.0.0",
+    "qrcode": "^1.5.4",
+    "tsx": "^4.20.6",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/agents/claude/driver.ts

@@ -0,0 +1,149 @@
+// Claude Code 驱动：官方 Claude Agent SDK。
+//
+// 会话列表 / 历史全部走 SDK 自带的 listSessions / getSessionInfo / getSessionMessages，
+// 不再自己去扒 ~/.claude/projects 下的 jsonl —— 那是 CLI 的内部约定，SDK 才是公开接口。
+import {
+  getSessionInfo,
+  getSessionMessages,
+  listSessions,
+} from "@anthropic-ai/claude-agent-sdk";
+import { config } from "../../core/config.js";
+import type {
+  AgentDriver,
+  AgentEvents,
+  AgentSession,
+  HistoryMessage,
+  InteractionHost,
+  ModelInfo,
+  RuntimeInfo,
+  SessionOptions,
+  SessionSummary,
+} from "../../core/types.js";
+import { diagnose } from "./errors.js";
+import { ClaudeSession, describeToolUse, summarize } from "./session.js";
+
+/** sessionId 会被拼进路径，先验形，防 /resume ../../x 越界 */
+const SESSION_ID = /^[A-Za-z0-9_-]{8,64}$/;
+
+function titleOf(info: { customTitle?: string; summary?: string; firstPrompt?: string }): string {
+  const raw = (info.customTitle || info.summary || info.firstPrompt || "").replace(/\s+/g, " ").trim();
+  if (!raw) return "(无标题)";
+  return raw.length > 60 ? `${raw.slice(0, 60)}…` : raw;
+}
+
+type Block = { type?: string; text?: string; name?: string; input?: unknown; thinking?: string };
+
+function blocksOf(message: unknown): Block[] {
+  const content = (message as { content?: unknown } | null)?.content;
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return Array.isArray(content) ? (content as Block[]) : [];
+}
+
+/** 用户消息里我们自己拼进去的附件说明，历史里只留一行简述 */
+function cleanUserText(text: string): string {
+  const cut = [text.indexOf("[用户通过飞书发来了以下附件"), text.indexOf("[用户发来了以下附件")]
+    .filter((i) => i >= 0)
+    .sort((a, b) => a - b)[0];
+  if (cut === undefined) return text;
+  const files = (text.slice(cut).match(/^- /gm) ?? []).length;
+  return `${text.slice(0, cut).trim()}${files ? `\n\n📎 ${files} 个附件` : ""}`.trim();
+}
+
+export class ClaudeDriver implements AgentDriver {
+  readonly id = "claude";
+  readonly label = "Claude Code";
+  readonly capabilities = { effort: true, fork: true, cost: true, streaming: true };
+
+  async start(): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  createSession(opts: SessionOptions, events: AgentEvents, host: InteractionHost): AgentSession {
+    return new ClaudeSession(opts, events, host);
+  }
+
+  async listSessions(cwd: string | undefined, limit = 10): Promise<SessionSummary[]> {
+    try {
+      const sessions = await listSessions({ ...(cwd ? { dir: cwd } : {}), limit });
+      return sessions.map((s) => ({
+        id: s.sessionId,
+        title: titleOf(s),
+        ...(s.cwd ? { cwd: s.cwd } : {}),
+        updatedAt: s.lastModified,
+      }));
+    } catch (err) {
+      console.error("[claude] 读取会话列表失败:", err);
+      return [];
+    }
+  }
+
+  async sessionExists(id: string, cwd: string): Promise<boolean> {
+    if (!SESSION_ID.test(id)) return false;
+    try {
+      return !!(await getSessionInfo(id, { dir: cwd }));
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 把会话记录整理成「一问一答」：用户一条，助手把这一轮所有文本拼成一条，
+   * 中间的工具调用作为过程摘要挂在助手那条上。工具结果（type=user 的 tool_result）
+   * 和子 agent 的消息不算对话。
+   */
+  async readHistory(id: string, cwd: string): Promise<HistoryMessage[]> {
+    if (!SESSION_ID.test(id)) return [];
+    const raw = await getSessionMessages(id, { dir: cwd });
+    const out: HistoryMessage[] = [];
+    let assistant: HistoryMessage | null = null;
+    const flush = () => {
+      if (assistant && (assistant.text.trim() || assistant.steps?.length)) out.push(assistant);
+      assistant = null;
+    };
+    for (const msg of raw) {
+      if (msg.parent_tool_use_id) continue;
+      const blocks = blocksOf(msg.message);
+      if (msg.type === "user") {
+        const texts = blocks.filter((b) => b.type === "text" && b.text).map((b) => b.text!);
+        if (texts.length === 0) continue; // 纯 tool_result
+        const text = cleanUserText(texts.join("\n"));
+        if (!text || text.startsWith("<command-") || text.startsWith("<local-command")) continue;
+        flush();
+        out.push({ role: "user", text });
+      } else if (msg.type === "assistant") {
+        assistant ??= { role: "assistant", text: "", steps: [] };
+        for (const b of blocks) {
+          if (b.type === "text" && b.text?.trim()) {
+            assistant.text += (assistant.text ? "\n\n" : "") + b.text;
+          } else if (b.type === "tool_use" && b.name) {
+            assistant.steps!.push(`🔧 ${describeToolUse(b.name, b.input)}`);
+          } else if (b.type === "thinking" && b.thinking) {
+            const t = summarize(b.thinking);
+            if (t) assistant.steps!.push(`💭 ${t}`);
+          }
+        }
+      }
+    }
+    flush();
+    return out;
+  }
+
+  async listModels(session: AgentSession): Promise<ModelInfo[]> {
+    return (session as ClaudeSession).listModels();
+  }
+
+  async defaults(): Promise<RuntimeInfo> {
+    const c = config().agents.claude;
+    return {
+      ...(c.defaultModel ? { model: c.defaultModel } : {}),
+      ...(c.defaultEffort ? { effort: c.defaultEffort } : {}),
+    };
+  }
+
+  async statusLines(): Promise<string[]> {
+    return [];
+  }
+
+  diagnose(err: unknown) {
+    return diagnose(err);
+  }
+}

package/src/agents/claude/errors.ts

@@ -0,0 +1,129 @@
+// 把 SDK / CLI 抛出的原始错误翻译成人能看懂、且知道下一步做什么的提示。
+//
+// 原则：聊天里给一句人话 + 一条明确动作；终端给完整修复步骤。
+// 不要把 SDK 堆栈直接甩给用户 —— 那既吓人又没有信息量。
+
+export type DiagnosisKind =
+  | "auth_expired"
+  | "auth_missing"
+  | "cli_missing"
+  | "rate_limit"
+  | "billing"
+  | "turn_aborted"
+  | "unknown";
+
+export type Diagnosis = {
+  kind: DiagnosisKind;
+  /** 发到聊天里的简短说明 */
+  chatMessage: string;
+  /** 打在终端的修复步骤 */
+  consoleHint: string;
+  /** 是否属于「配置好之前重试也没用」的问题 */
+  fatal: boolean;
+};
+
+const LOGIN_STEPS = [
+  "  1) npm i -g @anthropic-ai/claude-code",
+  "  2) claude          # 然后用 /login 登录",
+  '  3) claude -p "回复 OK"   # 验证认证是否恢复',
+  "  4) 重启 im-agent：im-agent service restart",
+].join("\n");
+
+export function diagnose(err: unknown): Diagnosis {
+  const raw = err instanceof Error ? err.message : String(err);
+  const text = raw.toLowerCase();
+
+  if (
+    text.includes("oauth session expired") ||
+    text.includes("could not be refreshed") ||
+    text.includes("failed to authenticate")
+  ) {
+    return {
+      kind: "auth_expired",
+      chatMessage:
+        "Claude 的登录状态已过期，我暂时无法工作。\n请机器主人在终端重新登录（`claude` → `/login`），完成后我就能继续。",
+      consoleHint: `Claude Code 登录已过期，需要重新登录：\n${LOGIN_STEPS}`,
+      fatal: true,
+    };
+  }
+
+  if (
+    text.includes("invalid api key") ||
+    text.includes("authentication_error") ||
+    text.includes("unauthorized")
+  ) {
+    return {
+      kind: "auth_missing",
+      chatMessage:
+        "Claude 的凭证无效，我暂时无法工作。\n请机器主人检查登录状态或 ANTHROPIC_API_KEY。",
+      consoleHint: `Claude 凭证无效。若用订阅账号，重新登录：\n${LOGIN_STEPS}\n若用 API key，检查 ANTHROPIC_API_KEY 是否正确。`,
+      fatal: true,
+    };
+  }
+
+  if (
+    text.includes("enoent") ||
+    text.includes("command not found") ||
+    text.includes("spawn") ||
+    text.includes("could not find claude")
+  ) {
+    return {
+      kind: "cli_missing",
+      chatMessage:
+        "本机还没装好 Claude Code，我暂时无法工作。\n请机器主人先完成安装。",
+      consoleHint: `找不到可用的 Claude Code。安装并登录：\n${LOGIN_STEPS}`,
+      fatal: true,
+    };
+  }
+
+  if (text.includes("rate limit") || text.includes("usage limit")) {
+    return {
+      kind: "rate_limit",
+      chatMessage: "Claude 的用量已达上限，请稍后再试。",
+      consoleHint: "已达用量上限。等配额恢复，或换用额度更充足的账号 / API key。",
+      fatal: false,
+    };
+  }
+
+  // CLI 在一轮结束时发现 transcript 收尾不自洽（典型形态：最后一条是用户侧
+  // 消息，而助手那边还停在 tool_use），就判为 error_during_execution。
+  // 也就是工具调用循环跑到一半被打断了 —— /stop、审批超时、CLI 进程挂掉都算。
+  // SDK 会把它包成 Error("Claude Code returned an error result: …") 抛出来。
+  if (
+    text.includes("error_during_execution") ||
+    text.includes("returned an error result")
+  ) {
+    return {
+      kind: "turn_aborted",
+      chatMessage:
+        "这一轮没能正常收尾，多半是工具跑到一半被打断了（/stop、审批超时，或 Claude Code 自己退出了）。\n上下文没丢，把刚才的需求再说一遍就行。",
+      consoleHint:
+        "一轮执行被中途打断（error_during_execution）。\n" +
+        "常见原因：用户发了 /stop、审批超时按拒绝处理、或 Claude Code 进程退出。\n" +
+        "偶发不用管，下一条消息会带着原 sessionId 重新拉起。\n" +
+        "如果反复出现，去 ~/.claude/projects 下看对应会话的 jsonl 尾部，确认是不是每次都断在同一个工具上。",
+      fatal: false,
+    };
+  }
+
+  if (text.includes("credit balance") || text.includes("billing")) {
+    return {
+      kind: "billing",
+      chatMessage: "Claude 账户余额不足，请机器主人处理后再试。",
+      consoleHint: "账户余额不足，请到 Claude 控制台充值或检查订阅状态。",
+      fatal: false,
+    };
+  }
+
+  return {
+    kind: "unknown",
+    // 未知错误才把原文带给用户 —— 有原文总比一句「出错了」强
+    chatMessage: `出错了：${raw}`,
+    consoleHint: raw,
+    fatal: false,
+  };
+}
+
+/** 同一类问题只在终端刷一次完整指引，避免每条消息都刷屏 */
+const announced = new Set<DiagnosisKind>();
+