feishu-codex-connector 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 feishu-codex-bridge contributors
+
+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,169 @@
+# Feishu Codex Connector
+
+Feishu Codex Connector is an unofficial Feishu/Lark bot and local bridge for OpenAI Codex. It lets you send coding tasks from Feishu or Lark chat, run Codex in a controlled local workspace, and stream the result back through rich cards, messages, and document comments.
+
+Use it when you want a personal AI coding agent in Feishu/Lark that can work with local repositories, preserve Codex sessions, switch workspaces, and keep app secrets and OpenAI API keys in a profile-local encrypted keystore.
+
+## At A Glance
+
+| Item | Value |
+| --- | --- |
+| npm package | `feishu-codex-connector` |
+| CLI command | `feishu-codex` |
+| Runtime | Node.js `>=20.12.0` |
+| Chat platforms | Feishu and Lark |
+| Codex auth | OpenAI API key, local Codex state, or inherited user auth |
+| Local state | `~/.feishu-codex` |
+
+## Features
+
+- Run OpenAI Codex from Feishu/Lark direct messages, groups, and document comments.
+- Bootstrap a Feishu/Lark PersonalAgent app with a terminal QR-code wizard.
+- Receive events through Feishu/Lark persistent connection mode.
+- Stream Codex progress and command completion through rich interactive cards.
+- Manage workspace aliases, session reset/resume, timeouts, diagnostics, and process lifecycle from chat.
+- Store app secrets and Codex API keys as profile-scoped secret references instead of plaintext config.
+- Restrict access with owner, admin, user, and group allow lists.
+
+## Install
+
+Install from npm:
+
+```bash
+npm install -g feishu-codex-connector
+feishu-codex run
+```
+
+Or run from a local checkout:
+
+```bash
+pnpm install
+pnpm build
+node bin/feishu-codex.mjs run
+```
+
+## First Run
+
+The first run starts a PersonalAgent bootstrap wizard:
+
+1. The terminal renders a QR code.
+2. Scan it with the Feishu/Lark app.
+3. Pick or create a PersonalAgent app.
+4. The connector initializes a Codex agent profile.
+5. Config is written to `~/.feishu-codex/config.json`; profile state is written under `~/.feishu-codex/profiles/<profile>/`.
+
+If `OPENAI_API_KEY` is present, the wizard uses API-key auth. Otherwise it tries to reuse local Codex state when available.
+
+If you already have a PersonalAgent app, skip QR creation:
+
+```bash
+feishu-codex run \
+  --app-id cli_xxx \
+  --app-secret "$FEISHU_APP_SECRET"
+```
+
+## Manual Profile
+
+Create a profile explicitly when you already know the Feishu/Lark app credentials and target workspace:
+
+```bash
+feishu-codex profile create default \
+  --tenant feishu \
+  --app-id cli_xxx \
+  --app-secret "$FEISHU_APP_SECRET" \
+  --codex-auth api-key \
+  --codex-api-key "$OPENAI_API_KEY" \
+  --workspace /absolute/project/path
+
+feishu-codex run --profile default
+```
+
+Normal profile config stores only secret references. App secrets and Codex API keys are stored in the profile-local encrypted keystore under `~/.feishu-codex/profiles/<name>/`.
+
+## Feishu/Lark Events
+
+The default runtime uses the Feishu/Lark persistent connection:
+
+```bash
+feishu-codex run --profile default
+```
+
+When startup succeeds, the terminal should show `ws client ready`. Send `/status` in the bot DM or an authorized group to verify message delivery.
+
+If the WebSocket connects but messages do not arrive, check the app's Events & Callbacks settings in Feishu/Lark Open Platform:
+
+1. Event subscription mode is set to persistent connection.
+2. `im.message.receive_v1` is subscribed.
+3. Callback subscription mode is set to persistent connection.
+4. `card.action.trigger` is subscribed if card buttons are used.
+
+`--poll-chat <chat_id>` is only a diagnostic fallback for apps whose event subscription is not configured yet.
+
+## CLI Commands
+
+```bash
+feishu-codex profile list
+feishu-codex profile export default
+feishu-codex run --profile default
+feishu-codex start --profile default
+feishu-codex status --profile default
+feishu-codex stop --profile default
+feishu-codex ps
+feishu-codex doctor --profile default --json
+```
+
+## Chat Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/help` | Show the help card |
+| `/status` | Show profile, workspace, session, and queue status |
+| `/new`, `/reset` | Reset the current scope's Codex session |
+| `/new group [name]` | Create a new Feishu/Lark group and inherit the current workspace |
+| `/resume`, `/resume use <nonce>` | List and restore recent sessions for the current workspace |
+| `/cd <path>` | Switch the current scope workspace |
+| `/ws list` | List workspace aliases |
+| `/ws save <name>` | Save the current workspace as an alias |
+| `/ws add <name> <path>` | Save a specific path as a workspace alias |
+| `/ws use <name>` | Switch to a workspace alias |
+| `/ws remove <name>` | Remove a workspace alias |
+| `/stop` | Stop the current run |
+| `/timeout <minutes\|off\|default>` | Set the current scope idle timeout |
+| `/config`, `/config show` | Edit or inspect profile settings |
+| `/invite`, `/remove` | Manage access lists |
+| `/doctor`, `/doctor detail` | Run diagnostics |
+| `/ps`, `/exit <id>`, `/reconnect` | Manage the local connector process |
+
+## Security
+
+- Secrets are not written as plaintext in normal profile config.
+- App secrets and OpenAI API keys are resolved through profile-scoped secret references.
+- Rendered run output is redacted for common API-key and app-secret patterns.
+- Codex receives an explicit prompt rule not to inspect or reveal bridge secret files.
+- The connector is designed for personal local operation; review workspace permissions before granting group access.
+
+## FAQ
+
+**Is this an official Feishu, Lark, or OpenAI project?**  
+No. This is an independent connector for Feishu/Lark and OpenAI Codex.
+
+**Does it work with both Feishu and Lark?**  
+Yes. Use `--tenant feishu` or `--tenant lark` when creating a profile.
+
+**Do I need an OpenAI API key?**  
+API-key auth is the most predictable remote mode. The connector can also use local Codex state or inherited user auth when configured.
+
+**Where are local files stored?**  
+The default state directory is `~/.feishu-codex`.
+
+## Documentation
+
+- [Architecture](./docs/ARCHITECTURE.md)
+- [Functional Specification](./docs/SPEC.md)
+- [Feature Parity Specification](./docs/FEATURE_PARITY_SPEC.md)
+- [Command Completion Specification](./docs/COMMAND_COMPLETION_SPEC.md)
+- [Feishu/Lark Permissions](./docs/FEISHU_PERMISSIONS.md)
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,170 @@
+# Feishu Codex Connector
+
+Feishu Codex Connector 是一个非官方的飞书 / Lark 机器人和本地桥接服务，用来在飞书或 Lark 聊天里运行 OpenAI Codex。你可以从私聊、群聊或文档评论发送编程任务，让 Codex 在本机受控工作区执行，并把进度和结果通过富文本卡片、消息和文档评论回传。
+
+适合这些场景：给自己搭建飞书 Codex 机器人、把 OpenAI Codex 接入 Lark、远程驱动本地代码仓库、保留 Codex session、切换 workspace，并把飞书 App Secret 和 OpenAI API Key 放在 profile 级加密 keystore 中。
+
+## 快速信息
+
+| 项目 | 内容 |
+| --- | --- |
+| npm 包 | `feishu-codex-connector` |
+| CLI 命令 | `feishu-codex` |
+| Node.js | `>=20.12.0` |
+| 平台 | 飞书、Lark |
+| Codex 认证 | OpenAI API Key、本机 Codex 状态、继承用户认证 |
+| 本地状态目录 | `~/.feishu-codex` |
+
+## 主要功能
+
+- 从飞书 / Lark 私聊、群聊、文档评论里运行 OpenAI Codex。
+- 首次运行提供 PersonalAgent 扫码向导，在终端显示二维码创建或绑定应用。
+- 使用飞书 / Lark 开放平台长连接接收消息和卡片回调。
+- 用富文本交互卡片展示 Codex 运行进度、命令完成状态和操作按钮。
+- 在聊天里管理 workspace alias、session reset/resume、timeout、doctor 诊断和本机进程。
+- App Secret 和 Codex API Key 以 profile-scoped secret reference 保存，不明文写入普通配置。
+- 支持 owner、admin、user、group allow list 控制访问范围。
+
+## 安装
+
+通过 npm 安装：
+
+```bash
+npm install -g feishu-codex-connector
+feishu-codex run
+```
+
+从源码运行：
+
+```bash
+pnpm install
+pnpm build
+node bin/feishu-codex.mjs run
+```
+
+## 首次启动
+
+第一次运行会进入 PersonalAgent 扫码向导：
+
+1. 终端渲染二维码。
+2. 用飞书 / Lark App 扫码。
+3. 选择或创建 PersonalAgent 应用。
+4. connector 初始化 Codex agent profile。
+5. 配置写入 `~/.feishu-codex/config.json`，profile 状态写入 `~/.feishu-codex/profiles/<profile>/`。
+
+如果环境里有 `OPENAI_API_KEY`，首次初始化会使用 API key 模式；否则会优先复用本机 Codex 登录状态。
+
+如果已有 PersonalAgent app，可以跳过扫码：
+
+```bash
+feishu-codex run \
+  --app-id cli_xxx \
+  --app-secret "$FEISHU_APP_SECRET"
+```
+
+## 手动创建 Profile
+
+如果已经知道飞书 / Lark 应用凭证和目标代码目录，可以直接创建 profile：
+
+```bash
+feishu-codex profile create default \
+  --tenant feishu \
+  --app-id cli_xxx \
+  --app-secret "$FEISHU_APP_SECRET" \
+  --codex-auth api-key \
+  --codex-api-key "$OPENAI_API_KEY" \
+  --workspace /absolute/project/path
+
+feishu-codex run --profile default
+```
+
+普通 profile config 只保存 secret 引用。App Secret 和 Codex API Key 会写入 profile-local encrypted keystore，不会明文写进 `config.json`。
+
+## 飞书 / Lark 长连接
+
+默认运行方式使用飞书 / Lark 开放平台长连接：
+
+```bash
+feishu-codex run --profile default
+```
+
+启动成功后，终端会看到 `ws client ready`。然后在机器人私聊或已授权群聊里发送 `/status` 测试消息接收。
+
+如果 WebSocket 已连接但收不到消息，请在飞书 / Lark 开放平台检查当前应用的「事件与回调」：
+
+1. 事件配置的订阅方式为「使用长连接接收事件」。
+2. 已订阅 `im.message.receive_v1`。
+3. 回调配置的订阅方式为「使用长连接接收回调」。
+4. 如需卡片按钮，已订阅 `card.action.trigger`。
+
+`--poll-chat <chat_id>` 只作为诊断或事件订阅尚未配置时的兜底方式。
+
+## CLI 命令
+
+```bash
+feishu-codex profile list
+feishu-codex profile export default
+feishu-codex run --profile default
+feishu-codex start --profile default
+feishu-codex status --profile default
+feishu-codex stop --profile default
+feishu-codex ps
+feishu-codex doctor --profile default --json
+```
+
+## 飞书内命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/help` | 查看帮助卡片 |
+| `/status` | 查看当前 profile、workspace、session、队列 |
+| `/new`, `/reset` | 重置当前 scope 的 Codex session |
+| `/new group [name]` | 创建新的飞书 / Lark 群聊并继承当前 workspace |
+| `/resume`, `/resume use <nonce>` | 列出并恢复当前 workspace 下的历史 session |
+| `/cd <path>` | 切换当前 scope 的 workspace |
+| `/ws list` | 查看 workspace 别名 |
+| `/ws save <name>` | 保存当前 workspace 为别名 |
+| `/ws add <name> <path>` | 保存指定路径为 workspace 别名 |
+| `/ws use <name>` | 切换到 workspace 别名 |
+| `/ws remove <name>` | 删除 workspace 别名 |
+| `/stop` | 停止当前 scope 的运行 |
+| `/timeout <minutes\|off\|default>` | 设置当前 scope 的 idle timeout |
+| `/config`, `/config show` | 修改或查看配置 |
+| `/invite user @name`, `/invite admin @name`, `/invite group` | 管理访问控制 |
+| `/remove user @name`, `/remove admin @name`, `/remove group` | 移除访问控制 |
+| `/doctor`, `/doctor detail` | 诊断当前 connector 状态 |
+| `/ps`, `/exit <id>`, `/reconnect` | 查看、停止或重连本机 connector 进程 |
+
+## 安全说明
+
+- 普通 profile 配置不会明文保存 App Secret 或 OpenAI API Key。
+- 敏感信息通过 profile-scoped secret reference 解析。
+- 输出渲染会对常见 API key 和 app secret 模式做脱敏。
+- connector 会显式提示 Codex 不要读取或泄露桥接服务的 secret 文件。
+- 当前设计以个人本地运行为主；给群聊授权前，请确认 workspace 权限和 allow list。
+
+## 常见问题
+
+**这是飞书、Lark 或 OpenAI 官方项目吗？**  
+不是。这是一个独立的 Feishu/Lark + OpenAI Codex connector。
+
+**同时支持飞书和 Lark 吗？**  
+支持。创建 profile 时使用 `--tenant feishu` 或 `--tenant lark`。
+
+**必须使用 OpenAI API Key 吗？**  
+API-key 模式最适合稳定远程运行。也可以按配置使用本机 Codex 状态或继承用户认证。
+
+**本地文件存在哪里？**  
+默认状态目录是 `~/.feishu-codex`。
+
+## 文档
+
+- [Architecture](./docs/ARCHITECTURE.md)
+- [Functional Specification](./docs/SPEC.md)
+- [Feature Parity Specification](./docs/FEATURE_PARITY_SPEC.md)
+- [Command Completion Specification](./docs/COMMAND_COMPLETION_SPEC.md)
+- [Feishu/Lark Permissions](./docs/FEISHU_PERMISSIONS.md)
+
+## License
+
+MIT

package/bin/feishu-codex.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+
+main(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});