lark-to-codex 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +141 -0
  3. package/README.zh.md +141 -0
  4. package/bin/lark-to-codex.mjs +2 -0
  5. package/dist/cli.js +5934 -0
  6. package/dist/index.d.ts +134 -0
  7. package/dist/index.js +879 -0
  8. package/package.json +56 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lark Channel Bridge contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # lark-to-codex
2
+
3
+ A lightweight bot that bridges Feishu / Lark messenger with your local [Codex CLI](https://developers.openai.com/codex/cli). Talk to Codex from chat — send messages, images, files, and slash commands, and get streaming responses in real time.
4
+
5
+ [中文 README](./README.zh.md)
6
+
7
+ ---
8
+
9
+ ## Quick start
10
+
11
+ **Prerequisites:** Node.js >= 20, Codex CLI installed and logged in.
12
+
13
+ ```bash
14
+ npm i -g lark-to-codex
15
+ lark-to-codex run
16
+ ```
17
+
18
+ First run detects no app is configured and launches a **QR-code wizard** — scan it with the Feishu/Lark app to create or bind a PersonalAgent app. Credentials are saved automatically to `~/.lark-channel/config.json`.
19
+
20
+ That's it. DM the bot or `@bot` in a group and start talking.
21
+
22
+ ---
23
+
24
+ ## Features
25
+
26
+ | Feature | Description |
27
+ |---|---|
28
+ | **Streaming cards** | Codex output (text + tool calls) updates on a single interactive card in real time |
29
+ | **Per-chat sessions** | Each chat/topic keeps its own Codex session — conversations resume where they left off |
30
+ | **Preempt + batch** | New messages interrupt the current run; rapid-fire messages coalesce into one request |
31
+ | **Multiple workspaces** | `/ws` switches between named project directories, sessions reset per workspace |
32
+ | **Images & files** | Send them to the bot — Codex reads the locally cached paths |
33
+ | **Cloud-doc comments** | `@bot` in a Feishu doc comment gets a Codex-powered reply in-thread |
34
+ | **Quoted context** | Reply-quoted messages, forwarded messages, and interactive card JSON are expanded into Codex context |
35
+ | **Codex → Feishu actions** | After `lark-cli config bind --source lark-channel`, Codex can send cards, access docs, calendar, tasks, etc. |
36
+ | **Idle watchdog** | Auto-kills Codex if it goes silent for N minutes (configurable per session via `/timeout` or globally via `/config`) |
37
+
38
+ ---
39
+
40
+ ## Commands
41
+
42
+ ### Host CLI (terminal)
43
+
44
+ | Command | Effect |
45
+ |---|---|
46
+ | `lark-to-codex run [-c <config>]` | Run the bot in the foreground |
47
+ | `lark-to-codex start` | Register as an OS daemon (launchd / systemd / Task Scheduler) and start |
48
+ | `lark-to-codex stop` | Stop the daemon |
49
+ | `lark-to-codex restart` | Restart the daemon |
50
+ | `lark-to-codex status` | Show daemon status |
51
+ | `lark-to-codex unregister` | Remove daemon registration and stop |
52
+ | `lark-to-codex ps` | List running bridge processes |
53
+ | `lark-to-codex kill <id\|#>` | Kill a bridge process |
54
+
55
+ > Daemon commands require global install (`npm i -g`). Do not use `npx` for daemon commands — the cache path gets garbage collected.
56
+
57
+ ### Slash commands (inside Feishu / Lark)
58
+
59
+ | Command | Effect |
60
+ |---|---|
61
+ | `/new` `/reset` | Clear current chat's session |
62
+ | `/cd <path>` | Switch working directory (resets session) |
63
+ | `/ws list` / `save` / `use` / `remove` | Manage named workspaces |
64
+ | `/status` | Show cwd / session / agent info |
65
+ | `/config` | Adjust preferences (reply style, tool-call display, access control) |
66
+ | `/stop` | Stop the current run (or click the ⏹ button on the card) |
67
+ | `/timeout [N\|off\|default]` | Set idle watchdog minutes for current session |
68
+ | `/ps` | List all `start` processes on this host |
69
+ | `/exit <id\|#>` | Stop a `start` process |
70
+ | `/reconnect` | Force WebSocket reconnect (after network blip) |
71
+ | `/doctor [description]` | Feed recent logs to Codex for self-diagnosis |
72
+ | `/help` | Help card |
73
+ | Other `/xxx` | Forwarded verbatim to Codex |
74
+
75
+ **Reply policy:** In DM, the bot replies to everything. In **groups (including topic groups)**, `@bot` is required by default. `@all` is never answered.
76
+
77
+ ---
78
+
79
+ ## Data directory
80
+
81
+ Everything lives under `~/.lark-channel/`:
82
+
83
+ | File | Purpose |
84
+ |---|---|
85
+ | `config.json` | App credentials, preferences, access control |
86
+ | `sessions.json` | Codex session IDs per chat/topic |
87
+ | `workspaces.json` | Named workspace definitions |
88
+ | `secrets.enc` | AES-256-GCM encrypted secrets |
89
+ | `media/<chatId>/` | Downloaded images/files (auto-cleaned after 24h) |
90
+ | `logs/YYYY-MM-DD.log` | Structured JSON logs (7-day rotation) |
91
+
92
+ ---
93
+
94
+ ## Access control (optional)
95
+
96
+ Out of the box the bot is **open** — anyone who finds it can use it. Send `/config` inside Feishu to restrict access via three allowlists:
97
+
98
+ - **Allowed users** — only these `open_id`s can interact (others are silently ignored)
99
+ - **Allowed chats** — only these `chat_id`s trigger responses (DMs are always exempt)
100
+ - **Admins** — only these `open_id`s can run sensitive commands (`/config`, `/cd`, `/ws`, `/exit`, etc.)
101
+
102
+ DM the bot with `/config` to configure. Changes take effect on the next message — no restart needed.
103
+
104
+ To find `open_id` / `chat_id`: have the user send a message, then check the log:
105
+
106
+ ```bash
107
+ grep '"event":"enter"' ~/.lark-channel/logs/$(date +%Y-%m-%d).log | tail -5
108
+ ```
109
+
110
+ ---
111
+
112
+ ## FAQ
113
+
114
+ **Bot stays silent / Codex never replies.** Usually Codex CLI isn't logged in, or the session points to a nonexistent cwd. Try `/status` to inspect, `/new` for a fresh session.
115
+
116
+ **Codex freezes (card stuck).** The idle watchdog (if enabled via `/config` or `/timeout`) auto-kills processes that are silent for N minutes.
117
+
118
+ **How to upgrade?** `npm i -g lark-to-codex@latest` then restart. If upgrading from before 0.1.11, run `lark-to-codex migrate` once.
119
+
120
+ ---
121
+
122
+ ## Development
123
+
124
+ Build and link globally for local development:
125
+
126
+ ```bash
127
+ git clone https://github.com/kev1n-zhao/lark-to-codex.git
128
+ cd lark-to-codex
129
+ pnpm install
130
+ pnpm link:local
131
+ ```
132
+
133
+ This runs `pnpm build` (typecheck + bundle) then `npm link` to make the `lark-to-codex` command available globally from your local clone.
134
+
135
+ To unlink: `npm unlink -g lark-to-codex`
136
+
137
+ ## License
138
+
139
+ [MIT](./LICENSE)
140
+
141
+ <img src="./assets/feedback-group-qr.png" alt="Feedback group QR code" width="360">
package/README.zh.md ADDED
@@ -0,0 +1,141 @@
1
+ # lark-to-codex
2
+
3
+ 把飞书 / Lark 消息和本地 [Codex CLI](https://developers.openai.com/codex/cli) 打通的轻量 bot。一条命令起服务，扫码绑应用，在飞书里和 Codex 对话、发图发文件、敲斜杠命令，实时看到流式回复。
4
+
5
+ [English README](./README.md)
6
+
7
+ ---
8
+
9
+ ## 快速开始
10
+
11
+ **前置条件：** Node.js >= 20，已安装并登录 Codex CLI。
12
+
13
+ ```bash
14
+ npm i -g lark-to-codex
15
+ lark-to-codex run
16
+ ```
17
+
18
+ 首次启动自动进入**扫码向导**——用飞书 App 扫码，创建或绑定一个 PersonalAgent 应用。凭据自动保存到 `~/.lark-channel/config.json`。
19
+
20
+ 之后私聊 bot 或在群里 `@bot` 即可开始使用。
21
+
22
+ ---
23
+
24
+ ## 功能
25
+
26
+ | 功能 | 说明 |
27
+ |---|---|
28
+ | **流式卡片** | Codex 的文本和工具调用实时更新在同一张交互卡片上 |
29
+ | **会话延续** | 每个 chat/话题独立 session，对话可接着上次说 |
30
+ | **抢占 + 批处理** | 新消息打断当前任务；快速连发多条自动合并请求 |
31
+ | **多工作空间** | `/ws` 切换项目目录，session 自动重置 |
32
+ | **图片 & 文件** | 直接发给 bot，Codex 读取本地缓存路径 |
33
+ | **云文档评论** | 在飞书文档里 `@bot`，Codex 在评论线程内回复 |
34
+ | **引用上下文** | 引用消息、合并转发、交互卡 JSON 自动展开为 Codex 上下文 |
35
+ | **Codex → 飞书** | 完成 `lark-cli config bind --source lark-channel` 后，Codex 可直接操作飞书卡片、文档、日历、任务等 |
36
+ | **空闲探活** | Codex 静默超时自动终止（`/timeout` 按会话设定，`/config` 设全局默认） |
37
+
38
+ ---
39
+
40
+ ## 命令速查
41
+
42
+ ### 宿主 CLI（终端）
43
+
44
+ | 命令 | 作用 |
45
+ |---|---|
46
+ | `lark-to-codex run [-c <配置路径>]` | 前台启动 bot |
47
+ | `lark-to-codex start` | 注册为 OS 后台 daemon 并启动 |
48
+ | `lark-to-codex stop` | 停止 daemon |
49
+ | `lark-to-codex restart` | 重启 daemon |
50
+ | `lark-to-codex status` | 查看 daemon 状态 |
51
+ | `lark-to-codex unregister` | 取消 daemon 注册并停止 |
52
+ | `lark-to-codex ps` | 列出本机所有 bridge 进程 |
53
+ | `lark-to-codex kill <id\|#>` | 终止指定 bridge 进程 |
54
+
55
+ > daemon 命令需全局安装（`npm i -g`），不要用 `npx`——缓存路径会被 GC 清理。
56
+
57
+ ### 斜杠命令（飞书内使用）
58
+
59
+ | 命令 | 作用 |
60
+ |---|---|
61
+ | `/new` `/reset` | 清空当前 chat 的会话 |
62
+ | `/cd <路径>` | 切换工作目录（重置 session） |
63
+ | `/ws list` / `save` / `use` / `remove` | 管理命名工作空间 |
64
+ | `/status` | 查看当前 cwd / session / agent |
65
+ | `/config` | 调整偏好和访问控制 |
66
+ | `/stop` | 终止当前运行（或点卡片 ⏹ 按钮） |
67
+ | `/timeout [N\|off\|default]` | 设置当前会话空闲超时（分钟） |
68
+ | `/ps` | 列出本机所有 start 进程 |
69
+ | `/exit <id\|#>` | 终止指定 start 进程 |
70
+ | `/reconnect` | 强制重连 WebSocket |
71
+ | `/doctor [描述]` | 把运行日志喂给 Codex 自助诊断 |
72
+ | `/help` | 帮助卡片 |
73
+ | 其它 `/xxx` | 原样传给 Codex |
74
+
75
+ **消息策略：** 私聊 = 任何消息都回；**群（含话题群）= 默认需 `@bot`**，不 @ 则沉默。`@all` 永远不响应。
76
+
77
+ ---
78
+
79
+ ## 数据目录
80
+
81
+ 所有数据在 `~/.lark-channel/` 下：
82
+
83
+ | 文件 | 内容 |
84
+ |---|---|
85
+ | `config.json` | 应用凭据、偏好、访问控制 |
86
+ | `sessions.json` | 每个 chat/topic 的 Codex session ID |
87
+ | `workspaces.json` | 命名工作空间定义 |
88
+ | `secrets.enc` | AES-256-GCM 加密凭据 |
89
+ | `media/<chatId>/` | 下载的图片/文件（24h 自动清理） |
90
+ | `logs/YYYY-MM-DD.log` | 结构化运行日志（7天滚动） |
91
+
92
+ ---
93
+
94
+ ## 访问控制（可选）
95
+
96
+ 默认 bot 是开放的。在飞书里发 `/config` 可限制访问：
97
+
98
+ - **用户白名单** — 仅这些 `open_id` 可用（其他人被静默忽略）
99
+ - **群白名单** — 仅在这些群触发响应（私聊不受约束）
100
+ - **管理员** — 仅这些人可运行敏感命令（`/config` `/cd` `/ws` `/exit` 等）
101
+
102
+ 修改后下一条消息即生效，无需重启。
103
+
104
+ 找 `open_id` / `chat_id`：让目标用户发一条消息，然后查日志：
105
+
106
+ ```bash
107
+ grep '"event":"enter"' ~/.lark-channel/logs/$(date +%Y-%m-%d).log | tail -5
108
+ ```
109
+
110
+ ---
111
+
112
+ ## 常见问题
113
+
114
+ **Bot 不回复。** 通常是 Codex CLI 未登录或 session 指向了不存在的目录。试 `/status` 查看，`/new` 重开会话。
115
+
116
+ **Codex 卡住（卡片不动）。** 可通过 `/config` 或 `/timeout` 启用空闲探活，静默超时自动终止。
117
+
118
+ **如何升级？** `npm i -g lark-to-codex@latest` 然后重启。从 0.1.11 之前版本升级，先跑一次 `lark-to-codex migrate`。
119
+
120
+ ---
121
+
122
+ ## 本地开发
123
+
124
+ 构建并全局链接，用于本地开发调试：
125
+
126
+ ```bash
127
+ git clone https://github.com/kev1n-zhao/lark-to-codex.git
128
+ cd lark-to-codex
129
+ pnpm install
130
+ pnpm link:local
131
+ ```
132
+
133
+ 这会执行 `pnpm build`（类型检查 + 打包），然后 `npm link` 将本地克隆的 `lark-to-codex` 命令注册为全局可用。
134
+
135
+ 取消链接：`npm unlink -g lark-to-codex`
136
+
137
+ ## 许可
138
+
139
+ [MIT](./LICENSE)
140
+
141
+ <img src="./assets/feedback-group-qr.png" alt="飞书反馈群二维码" width="360">
package/bin/lark-to-codex.mjs ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import '../dist/cli.js';