@openai-lite/codex-feishu 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# codex-feishu
+
+Codex remote access, straight from Feishu. Use Codex from terminal or Feishu with shared conversation context.
+
+## Chinese docs
+
+- 中文文档（安装、命令、架构、限制）：[docs/README.zh-CN.md](docs/README.zh-CN.md)
+
+## What it does
+
+- No Codex core patching.
+- `codex-feishu init` writes MCP config + bridge config.
+- `codex-feishu daemon` bridges:
+  - Feishu text/image -> Codex
+  - Codex streaming output -> Feishu cards/text
+  - approvals / request_user_input -> Feishu quick actions
+- per-chat mapping for `thread_id` and `cwd`.
+- private chat auto-bind, group chat supports bind code.
+
+## Preview
+
+Feishu side experience snapshots:
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="docs/assets/feishu-preview-session.png">
+        <img src="docs/assets/feishu-preview-session.png" alt="Feishu session status card" width="240" />
+      </a>
+      <br />
+      Session status
+    </td>
+    <td align="center">
+      <a href="docs/assets/feishu-preview-image-reply.png">
+        <img src="docs/assets/feishu-preview-image-reply.png" alt="Feishu image and reply flow" width="240" />
+      </a>
+      <br />
+      Image + reply flow
+    </td>
+    <td align="center">
+      <a href="docs/assets/feishu-preview-image-reply1.jpg">
+        <img src="docs/assets/feishu-preview-image-reply1.jpg" alt="Feishu image and reply flow variant" width="240" />
+      </a>
+      <br />
+      Image + reply flow v2
+    </td>
+  </tr>
+</table>
+
+
+## Install
+
+```bash
+npm i -g @openai/codex  #安装codex(如果已安装可以跳过)
+
+npm i -g @openai-lite/codex-feishu
+```
+
+## Quick start (macOS / Linux)
+
+```bash
+codex-feishu init --app-id <FEISHU_APP_ID> --app-secret <FEISHU_APP_SECRET> daemon
+```
+
+Notes:
+- `init ... daemon` restarts daemon in background and prints bind info automatically.
+- Daemon is treated as singleton; `init ... daemon` will stop previous daemon instances first.
+- If `bot_open_id` can be auto-detected, QR opens bot chat directly.
+- If auto-detect fails, it degrades to `/bind CODE` mode (still usable).
+
+Refresh bind payload anytime:
+
+```bash
+codex-feishu qrcode
+```
+
+## Quick start (Windows)
+
+```powershell
+npm i -g @openai-lite/codex-feishu
+codex-feishu init --app-id <FEISHU_APP_ID> --app-secret <FEISHU_APP_SECRET> daemon
+```
+
+Windows defaults:
+- RPC endpoint: `tcp://127.0.0.1:9765`
+- You can override with `CODEX_FEISHU_RPC_ENDPOINT`.
+
+Optional checks:
+
+```bash
+codex-feishu doctor
+codex
+```
+
+## Feishu setup
+
+- 设置清单（中文）: [docs/FEISHU_SETUP.zh-CN.md](docs/FEISHU_SETUP.zh-CN.md)
+
+## CLI commands
+
+- `codex-feishu init [flags] [daemon|--daemon]`
+- `codex-feishu doctor`
+- `codex-feishu daemon`
+- `codex-feishu qrcode [--purpose <text>] [--ascii] [--json]`
+- `codex-feishu inbound --chat-id <id> --text <msg> [--user-id <id>]`
+- `codex-feishu mcp` (internal MCP entry, normally no manual use)
+
+## Feishu commands
+
+Core:
+- `/bind <CODE>`: bind current Feishu chat
+- `/rebind`: reset binding and generate a new bind code
+- `/status`: show current chat status
+- `/help`: show command help
+- `/group`: show group-chat usage guide
+- `/new`: create and switch to a new thread
+- `/stop`: stop current generation
+- `/pending`: list pending approvals/input requests
+
+Session / directory:
+- `/resume [index|thread_id]`
+- `/fork [index|thread_id]`
+- `/threads`
+- `/sw <index|thread_id>`
+- `/cwd`
+- `/cwd <PATH>`
+- `/cwd <PATH> new`
+
+Codex capability bridge:
+- `/review [instructions|branch:<name>|commit:<sha>]`
+- `/compact`
+- `/model [list|clear|<model_id>]`
+- `/approvals [untrusted|on-failure|on-request|never]`
+- `/permissions [read-only|workspace-write|danger-full-access]`
+- `/plan [on|off|toggle]` (compat mode)
+- `/init` (create/complete `AGENTS.md` through Codex)
+- `/skills`
+- `/mcp [list|get|add|remove|login|logout] ...`
+
+Approval responses:
+- quick reply `1` / `2` / `3`
+- `/approve [pending_id] [session]`
+- `/deny [pending_id]`
+- `/cancel [pending_id]`
+- `/answer <pending_id> <text|json>`
+
+## Behavior notes
+
+- `/mcp` output is intentionally raw passthrough from native `codex mcp ...` (often code-block/table style).
+- If mapped thread is invalid, daemon auto-recovers by creating a new thread and retrying once.
+- Feishu and terminal are state-synced, but rendering is not pixel-identical.
+
+## Runtime files
+
+- `~/.codex/config.toml` (MCP server block)
+- `~/.codex-feishu/config.json`
+- `~/.codex-feishu/state.json`
+- `~/.codex-feishu/run/daemon.pid`
+- `~/.codex-feishu/run/daemon.log`
+
+## Architecture and plan
+
+- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Priority plan: [docs/PRIORITY_PLAN.md](docs/PRIORITY_PLAN.md)

package/bin/codex-feishu.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,118 @@
+# codex-feishu Architecture
+
+## Scope
+
+- Keep Codex as the main runtime.
+- Do not patch Codex core.
+- Bridge Feishu <-> Codex via daemon and stable interfaces.
+
+## Topology
+
+```text
+Feishu Client <-> Feishu OpenAPI (long connection)
+                     |
+                     v
+               codex-feishu daemon
+                 |            |
+                 |            +-- state.json (binding/thread/cwd/pending)
+                 |
+                 +-- AppServerClient <-> codex app-server / codex proto
+                 |
+                 +-- JSON-RPC endpoint (UDS or TCP on Windows)
+                         ^
+                         |
+                     Codex MCP
+```
+
+## System diagram
+
+```mermaid
+flowchart LR
+  U1[User in Feishu] --> F[Feishu App]
+  U2[User in Terminal] --> C[Codex CLI]
+  F <--> O[Feishu OpenAPI\nLong Connection]
+  O <--> D[codex-feishu daemon]
+  C <--> D
+  D <--> A[AppServerClient]
+  A <--> S[codex app-server / proto]
+  D <--> R[JSON-RPC Endpoint\nUDS or TCP on Windows]
+  C --> M[MCP tools]
+  M --> R
+  D --> ST[state.json]
+```
+
+## Request/response flow (one question)
+
+```mermaid
+sequenceDiagram
+  participant User as Feishu User
+  participant Feishu as Feishu App/OpenAPI
+  participant Daemon as codex-feishu daemon
+  participant Codex as codex app-server/proto
+  participant Terminal as Codex CLI (optional)
+
+  User->>Feishu: Send text/image
+  Feishu->>Daemon: im.message.receive_v1
+  Daemon->>Daemon: Resolve binding (chat_id -> thread_id/cwd)
+  Daemon->>Codex: turn/start
+  Codex-->>Daemon: Streaming deltas + status events
+  Daemon-->>Feishu: Patch/send cards and text
+  Daemon-->>Terminal: Same thread state remains available
+```
+
+## Components
+
+- `codex-feishu daemon`
+  - Handles binding, per-chat thread/cwd mapping, message relay, approval relay.
+  - Exposes RPC methods under `feishu/*` and `bridge/*`.
+- `FeishuBridge`
+  - Long-connection event/message receiver and sender.
+- `AppServerClient`
+  - Prefers `codex app-server`; degrades to `codex proto` when needed.
+- MCP server (`codex-feishu mcp`)
+  - Exposes tools to Codex side (`feishu_qrcode`, `feishu_status`, `feishu_new_thread`).
+
+## Data model (persisted)
+
+- `bindings[chat_id]`
+  - `active_thread_id`, `active_cwd`
+  - per-chat preferences: `preferred_model`, `approval_policy`, `sandbox_mode`, `plan_mode`
+- `pending_bind_codes`
+- `thread_titles`
+- `active_thread_id`
+
+`thread_buffers` and recent streaming caches are runtime-only and not fully persisted.
+
+## Main flows
+
+### 1) Bind
+
+1. Generate bind payload (`feishu/qrcode`).
+2. User sends `/bind CODE` (or private-chat auto-bind).
+3. Daemon stores `chat_id -> thread/cwd` mapping.
+
+### 2) User message
+
+1. Feishu message enters daemon (`feishu/inbound_text` / `feishu/inbound_image`).
+2. Daemon resolves mapped thread/cwd and per-chat overrides.
+3. Daemon starts turn via app-server/proto.
+4. Streaming events are relayed back to Feishu cards/messages.
+
+### 3) Approval
+
+1. Codex emits approval or request_user_input.
+2. Daemon stores pending item and sends action hints to Feishu.
+3. Feishu quick reply (`1/2/3` or explicit command) resolves pending item.
+4. First valid reply wins.
+
+## Compatibility strategy
+
+- Treat Codex as evolving upstream.
+- Prefer passthrough behavior when possible (`/mcp`, `/skills` style).
+- Keep custom adapter logic minimal and isolated in daemon RPC handlers.
+- For unsupported app-server methods, return explicit downgrade message or fallback path.
+
+## Known tradeoffs
+
+- Terminal and Feishu are state-consistent, but rendering cannot be pixel-identical.
+- Some TUI-only commands have no strict app-server equivalent; daemon uses compatibility mode where possible.

package/docs/FEISHU_SETUP.zh-CN.md

@@ -0,0 +1,46 @@
+# 飞书准备与权限
+
+这份文档用于单独说明 `codex-feishu` 的飞书侧准备步骤与权限清单。
+
+## 必要配置
+
+1. 开启应用的机器人能力。
+2. 事件订阅方式选择“长连接（long connection）”。
+3. 订阅事件：
+   - `im.message.receive_v1`
+4. 开通接口权限（按当前代码实际调用）：
+   - `im.v1.message.create`（发送文本/卡片/图片消息）
+   - `im.v1.message.patch`（更新卡片）
+   - `im.v1.image.create`（上传图片）
+   - `im.v1.messageResource.get`（下载会话内图片）
+   - `im.v1.image.get`（图片下载兜底）
+   - `bot.v3.info`（可选，仅用于自动获取 `bot_open_id`）
+5. 权限或事件变更后，发布应用版本。
+
+## 权限清单 JSON
+
+```json
+{
+  "subscription_mode": "long_connection",
+  "events": [
+    "im.message.receive_v1"
+  ],
+  "scopes": {
+    "tenant": [
+      "aily:message:read",
+      "aily:message:write",
+      "im:message",
+      "im:message.group_at_msg:readonly",
+      "im:message.group_msg",
+      "im:message.p2p_msg:readonly",
+      "im:message:send_as_bot",
+      "im:resource"
+    ],
+    "user": [
+      "aily:message:read",
+      "aily:message:write",
+      "im:message"
+    ]
+  }
+}
+```

package/docs/README.zh-CN.md

@@ -0,0 +1,130 @@
+# codex-feishu 中文文档
+
+Codex 远程化：飞书直连。你可以在飞书或终端任意一端继续同一条对话，上下文自动同步。
+
+## 目标
+
+在不修改 Codex 本体的前提下，通过 sidecar/daemon + MCP，把飞书与终端接到同一条会话链路。
+
+## 快速架构图
+
+```text
+飞书用户 -> 飞书 -> codex-feishu daemon -> codex(app-server/proto) -> 结果回传飞书
+                               ^
+                               |
+                          Codex CLI / MCP
+```
+
+完整架构与时序图： [ARCHITECTURE.md](./ARCHITECTURE.md)
+
+## 安装
+
+### Linux / macOS
+
+```bash
+npm i -g @openai-lite/codex-feishu
+codex-feishu init --app-id <FEISHU_APP_ID> --app-secret <FEISHU_APP_SECRET> daemon
+```
+
+### Windows
+
+```powershell
+npm i -g @openai-lite/codex-feishu
+codex-feishu init --app-id <FEISHU_APP_ID> --app-secret <FEISHU_APP_SECRET> daemon
+```
+
+Windows 说明：
+- 默认 RPC 端点：`tcp://127.0.0.1:9765`
+- 可通过 `CODEX_FEISHU_RPC_ENDPOINT` 覆盖
+
+## init/daemon 说明
+
+- `init ... daemon` 会自动重启后台 daemon，并自动打印绑定信息（含二维码/链接/绑定指令）。
+- daemon 按单实例运行；`init ... daemon` 会先停止旧进程，再启动新进程。
+- 需要重新获取绑定信息时，执行：
+
+```bash
+codex-feishu qrcode
+```
+
+- 日志文件：`~/.codex-feishu/run/daemon.log`
+- Linux/macOS 实时看日志：`tail -f ~/.codex-feishu/run/daemon.log`
+- Windows 实时看日志：
+
+```powershell
+Get-Content -Path "$env:USERPROFILE\.codex-feishu\run\daemon.log" -Wait
+```
+
+- 可选检查命令（不是安装必需）：
+
+```bash
+codex-feishu doctor
+codex
+```
+
+## 飞书准备与权限
+
+- [FEISHU_SETUP.zh-CN.md](./FEISHU_SETUP.zh-CN.md)
+
+## 飞书侧命令
+
+### 基础
+
+- `/bind <CODE>`：绑定当前飞书会话到 Codex
+- `/rebind`：解除当前绑定并生成新绑定码
+- `/status`：查看当前会话状态（会话ID、目录、待审批等）
+- `/help`：查看命令帮助
+- `/group`：查看群聊触发与绑定说明
+- `/new`：新建会话并切换到新会话
+- `/stop`：中断当前生成
+- `/pending`：查看当前待审批/待输入项
+
+### 会话与目录
+
+- `/resume [序号|会话ID]`
+- `/fork [序号|会话ID]`
+- `/threads`
+- `/sw <序号|会话ID>`
+- `/cwd`
+- `/cwd <PATH>`
+- `/cwd <PATH> new`
+
+### Codex 能力桥接
+
+- `/review [说明|branch:<分支>|commit:<sha>]`
+- `/compact`
+- `/model [list|clear|<model_id>]`
+- `/approvals [untrusted|on-failure|on-request|never]`
+- `/permissions [read-only|workspace-write|danger-full-access]`
+- `/plan [on|off|toggle]`（兼容模式）
+- `/init`（通过 Codex 生成/补全 `AGENTS.md`）
+- `/skills`
+- `/mcp [list|get|add|remove|login|logout] ...`
+
+### 审批快捷
+
+- 直接回复 `1` / `2` / `3`
+- `/approve [pending_id] [session]`
+- `/deny [pending_id]`
+- `/cancel [pending_id]`
+- `/answer <pending_id> <text|json>`
+
+## 行为细节
+
+- 私聊支持自动绑定：首次消息可自动建立映射并继续转发。
+- 群聊建议 `@机器人` 触发；未绑定时需先 `/bind <CODE>`。
+- `/mcp` 返回是对原生 `codex mcp ...` 的透传，通常是代码块/表格样式。
+- 线程失效时，daemon 会自动新建线程并重试一次。
+
+## 运行文件
+
+- `~/.codex/config.toml`（MCP 配置）
+- `~/.codex-feishu/config.json`
+- `~/.codex-feishu/state.json`
+- `~/.codex-feishu/run/daemon.pid`
+- `~/.codex-feishu/run/daemon.log`
+
+## 相关文档
+
+- 架构说明：[ARCHITECTURE.md](./ARCHITECTURE.md)
+- 迭代清单：[PRIORITY_PLAN.md](./PRIORITY_PLAN.md)

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@openai-lite/codex-feishu",
+  "version": "0.1.0",
+  "description": "Feishu bridge for Codex with dual-end synchronized conversations.",
+  "type": "module",
+  "bin": {
+    "codex-feishu": "bin/codex-feishu.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "*",
+    "qrcode": "^1.5.4"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "license": "Apache-2.0"
+}

package/src/cli.js

@@ -0,0 +1,158 @@
+import { runDaemon } from "./commands/daemon.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runInbound } from "./commands/inbound.js";
+import { runInit } from "./commands/init.js";
+import { runMcp } from "./commands/mcp.js";
+import { fetchQrcode, formatQrcodeSummary, renderAsciiQr, runQrcode } from "./commands/qrcode.js";
+import { restartDaemonDetached } from "./lib/daemon_control.js";
+
+const HELP = `codex-feishu
+
+Usage:
+  codex-feishu init [--app-id <id>] [--app-secret <secret>] [--bot-open-id <open_id>] [--encrypt-key <key>] [--verify-token <token>] [--codex-bin <path>] [daemon|--daemon]
+  codex-feishu doctor
+  codex-feishu daemon
+  codex-feishu qrcode [--purpose <text>] [--ascii] [--json]
+  codex-feishu inbound --chat-id <chat_id> --text <message> [--user-id <id>]
+  codex-feishu mcp (internal, for Codex MCP server)
+  codex-feishu help
+`;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function fetchQrcodeWithRetry(options = {}) {
+  const maxWaitMs = Number.isFinite(options.maxWaitMs) ? Math.max(1000, options.maxWaitMs) : 20000;
+  const intervalMs = Number.isFinite(options.intervalMs) ? Math.max(100, options.intervalMs) : 500;
+  const deadline = Date.now() + maxWaitMs;
+  let lastErr = null;
+
+  while (Date.now() < deadline) {
+    try {
+      return await fetchQrcode({
+        purpose: options.purpose ?? "init_daemon_start",
+        autostart: false,
+        cwdHint: options.cwdHint ?? process.cwd(),
+        timeoutMs: options.timeoutMs ?? 1500,
+      });
+    } catch (err) {
+      lastErr = err;
+      // Wait daemon socket ready after background spawn.
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(intervalMs);
+    }
+  }
+
+  throw lastErr ?? new Error(`waited ${maxWaitMs}ms but qrcode is still unavailable`);
+}
+
+function parseArgs(argv) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+      flags[key] = value;
+    } else {
+      args.push(token);
+    }
+  }
+  return { args, flags };
+}
+
+function watchLogCommand(logPath) {
+  if (process.platform === "win32") {
+    return `powershell -NoProfile -Command "Get-Content -Path '${logPath}' -Wait"`;
+  }
+  return `tail -f ${logPath}`;
+}
+
+export async function runCli(argv) {
+  const { args, flags } = parseArgs(argv);
+  const cmd = args[0] ?? "help";
+
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    // eslint-disable-next-line no-console
+    console.log(HELP);
+    return;
+  }
+
+  if (cmd === "init") {
+    const startDaemon = args[1] === "daemon" || flags.daemon === "true";
+    await runInit(flags, { startDaemon });
+    if (startDaemon) {
+      const result = await restartDaemonDetached();
+      // eslint-disable-next-line no-console
+      console.log("\nDaemon:");
+      // eslint-disable-next-line no-console
+      console.log(
+        `- Previous: ${result.stopResult.action}${
+          result.stopResult.pid ? ` (pid=${result.stopResult.pid})` : ""
+        }`,
+      );
+      // eslint-disable-next-line no-console
+      console.log(`- Started: pid=${result.startResult.pid} (background)`);
+      // eslint-disable-next-line no-console
+      console.log(`- PID file: ${result.pidPath}`);
+      // eslint-disable-next-line no-console
+      console.log(`- Log file: ${result.logPath}`);
+      if (Array.isArray(result.stopResults) && result.stopResults.length > 1) {
+        // eslint-disable-next-line no-console
+        console.log(`- Cleaned stale daemons: ${result.stopResults.length}`);
+      }
+      // eslint-disable-next-line no-console
+      console.log(`- Watch log: ${watchLogCommand(result.logPath)}`);
+      // eslint-disable-next-line no-console
+      console.log("- Bind: waiting for daemon readiness (up to 20s)...");
+
+      try {
+        const qr = await fetchQrcodeWithRetry({
+          purpose: "init_daemon_start",
+          cwdHint: process.cwd(),
+          maxWaitMs: 20000,
+          intervalMs: 500,
+          timeoutMs: 1500,
+        });
+        const asciiQr = await renderAsciiQr(qr?.qr_text);
+        // eslint-disable-next-line no-console
+        console.log("\nBind:");
+        // eslint-disable-next-line no-console
+        console.log(formatQrcodeSummary(qr, { asciiQr }));
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.log(`\nBind: unavailable (${err?.message ?? String(err)})`);
+      }
+    }
+    return;
+  }
+
+  if (cmd === "doctor") {
+    await runDoctor();
+    return;
+  }
+
+  if (cmd === "daemon") {
+    await runDaemon(flags);
+    return;
+  }
+
+  if (cmd === "qrcode" || cmd === "qr") {
+    await runQrcode(flags);
+    return;
+  }
+
+  if (cmd === "mcp") {
+    await runMcp();
+    return;
+  }
+
+  if (cmd === "inbound") {
+    await runInbound(flags);
+    return;
+  }
+
+  throw new Error(`unknown command: ${cmd}\n\n${HELP}`);
+}