codex-to-im 0.1.0

package/docs/install-windows.md

@@ -0,0 +1,287 @@
+# Codex-to-IM Windows 安装说明
+
+## 1. 当前部署方案
+
+`codex-to-im` 当前采用的是 **单 npm 包 + 本地 Web 工作台 + 本地后台 bridge** 的部署方案。
+
+补充说明：当前版本不是从零开始的新工程，而是在以下两个已有项目基础上整理和改造而来：
+
+- `Claude-to-IM`
+- `Claude-to-IM-skill`
+
+核心形态如下：
+
+- 分发物：`codex-to-im` npm 包
+- 启动入口：全局命令 `codex-to-im`
+- 本地界面：优先 `http://127.0.0.1:4781`，被占用时自动切换到可用端口
+- 后台进程：
+  - `dist/ui-server.mjs` 负责本地工作台
+  - `dist/daemon.mjs` 负责 bridge
+- 运行方式：本地 Node.js detached 子进程，不依赖当前命令窗口常驻
+- 配置目录：`%USERPROFILE%\\.codex-to-im\\`
+- 兼容目录：如果机器上已有旧数据，会回落到 `%USERPROFILE%\\.claude-to-im\\`
+- 可选增强：可安装一层轻量 Codex 集成到 `%USERPROFILE%\\.codex\\skills\\codex-to-im`
+
+这意味着当前推荐的部署方式不是“clone 仓库后让用户手动跑脚本”，而是：
+
+1. 发布一个已经构建好的 npm 包
+2. 在目标 Windows 主机全局安装
+3. 运行 `codex-to-im`
+4. 在浏览器里完成配置、测试和启动
+
+## 2. 适用前提
+
+下面这份说明按 **Windows 主机** 写。
+
+默认假设：
+
+- 目标机是 Windows 10 / 11
+- 目标机已经安装 Node.js 20+
+- 目标机使用同一个 Windows 用户来运行 Codex 和 `codex-to-im`
+- 飞书应用、微信账号等平台侧信息已经准备好
+
+## 3. 安装前准备
+
+目标机至少需要这些前置条件：
+
+### 3.1 安装 Node.js
+
+要求：
+
+- Node.js >= 20
+
+建议安装完成后检查：
+
+```powershell
+node -v
+npm -v
+```
+
+### 3.2 安装并登录 Codex
+
+如果你希望 bridge 接管和继续 Codex 会话，目标机必须在 **同一个 Windows 用户** 下完成 Codex 登录。
+
+建议至少满足以下之一：
+
+- 已安装并使用过 Codex Windows App
+- 已安装 Codex CLI 并完成认证
+
+建议显式安装 Codex CLI：
+
+```powershell
+npm install -g @openai/codex
+```
+
+然后完成登录：
+
+```powershell
+codex auth login
+```
+
+## 4. 目标机安装方式
+
+### 4.1 推荐：从 npm 全局安装
+
+如果包已经发布到 npm：
+
+```powershell
+npm install -g codex-to-im
+```
+
+安装完成后，直接启动：
+
+```powershell
+codex-to-im
+```
+
+### 4.2 备用：从源码安装
+
+如果还没有正式发布 npm 包，可以在目标机直接用源码：
+
+```powershell
+git clone <your-repo-url> D:\codex\codex-to-im
+cd D:\codex\codex-to-im
+npm install
+npm run build
+node dist\cli.mjs open
+```
+
+如果希望源码安装后也能直接使用 `codex-to-im` 命令，可以再执行：
+
+```powershell
+npm link
+```
+
+## 5. 首次启动
+
+首次启动命令：
+
+```powershell
+codex-to-im
+```
+
+当前行为是：
+
+1. 拉起本地 UI 服务
+2. 在后台运行 `ui-server`
+3. 自动打开浏览器到本地工作台
+
+默认地址：
+
+```text
+http://127.0.0.1:4781
+```
+
+如果 `4781` 已被占用，程序会自动查找一个可用端口，并在启动时把实际地址打印到命令行。
+
+如果之后忘记了当前 Web 地址，可以执行：
+
+```powershell
+codex-to-im url
+```
+
+## 6. 在目标机上的首次配置
+
+进入本地工作台后，按这个顺序做：
+
+1. 选择 `Runtime`
+   - 推荐：`codex`
+2. 设置默认工作目录
+3. 设置 `/history` 默认返回条数（可选）
+4. 如果目标目录不是 Codex 已信任的 Git 仓库，可勾选“允许在未信任 Git 目录运行 Codex”
+5. 勾选要启用的通道
+   - 飞书：勾选 `启用飞书`
+   - 微信：勾选 `启用微信`
+6. 飞书场景下填写：
+   - `App ID`
+   - `App Secret`
+   - `Domain`
+   - `Allowed Users` 可选
+   - `启用飞书流式响应卡片` 可选
+7. 微信场景下点击：
+   - `开始微信扫码`
+8. 点击测试
+   - 飞书：`测试飞书凭据`
+   - Codex：`测试 Codex`
+9. 点击：
+    - `启动 Bridge`
+
+说明：
+
+- 飞书流式响应卡片依赖飞书应用侧具备可更新卡片 / CardKit 相关能力。
+- 当前至少需要并发布这些权限：
+  - `cardkit:card:write`
+  - `cardkit:card:read`
+  - `im:message:update`
+- 如果这些权限没有开通，桥接仍然可以工作，但会回退到最终结果消息。
+- 缺权限时，`logs\\bridge.log` 里通常会出现 `99991672` 和 `cardkit:card:write`。
+- 另外，当前 `codex` runtime 下正文通常不是逐字流式输出；更常见的效果是先显示 `Thinking / Tool Progress`，正文在回答完成时一次性落到卡片里。
+- IM 里发送 `/history` 可以查看当前会话最近 N 条消息，N 由“基础配置”中的返回条数控制。
+
+## 7. 目标机上的目录说明
+
+当前版本主要使用这些目录：
+
+### 7.1 新目录
+
+```text
+%USERPROFILE%\.codex-to-im\
+```
+
+其中主要文件有：
+
+- `config.env`
+- `logs\bridge.log`
+- `logs\ui-server.out.log`
+- `runtime\status.json`
+- `runtime\ui-server.json`
+
+### 7.2 旧目录兼容
+
+如果目标机上已经存在旧安装数据，程序会自动回落到：
+
+```text
+%USERPROFILE%\.claude-to-im\
+```
+
+所以安装或排查时，需要先确认当前实际使用的是哪一个 home 目录。
+
+## 8. 可选 Codex 集成
+
+这一步不是必须的。
+
+只有在你希望：
+
+- 从 Codex 里直接打开 `codex-to-im`
+- 或保留“共享当前会话到飞书”的轻入口
+
+时，才需要安装。
+
+当前可以通过本地工作台里的按钮安装到：
+
+```text
+%USERPROFILE%\.codex\skills\codex-to-im
+```
+
+安装后，它只保留两个动作：
+
+- `open codex-to-im`
+- `share current session to Feishu`
+
+## 9. 安装给别的主机时的建议
+
+### 9.1 飞书
+
+如果是同一个飞书应用，只需要在目标机重新填写：
+
+- App ID
+- App Secret
+- Domain
+- Allowed Users（如需）
+
+不需要复制源码里的任何配置文件。
+
+### 9.2 微信
+
+微信建议在 **目标机重新扫码**，不要直接复制旧机器上的登录状态文件。
+
+### 9.3 多台机器
+
+如果你要给多台 Windows 机器部署，推荐流程是：
+
+1. 在发布机完成 `npm run build`
+2. 发布 npm 包
+3. 每台目标机执行 `npm install -g codex-to-im`
+4. 每台机器各自完成本地登录、配置和通道测试
+
+## 10. 当前限制
+
+当前版本有几个需要提前说明的点：
+
+- 默认不是 Windows Service，而是本地 detached 进程
+- 机器重启后，不会自动恢复，需要再次运行 `codex-to-im`
+- 可选 Codex 集成不是主安装路径
+- 当前主路径是“本地工作台 + IM 配置 + Bridge 启动”
+
+## 11. 发布方注意事项
+
+如果你要把这个包发布到 npm，当前实现要求：
+
+1. 先在发布前执行：
+
+```powershell
+npm run build
+```
+
+2. 确保发布包中包含：
+
+- `dist/cli.mjs`
+- `dist/ui-server.mjs`
+- `dist/daemon.mjs`
+
+原因是当前包没有 `postinstall` 或 `prepare` 来在目标机自动构建。
+
+也就是说：
+
+- **发布到 npm 时应发布预构建产物**
+- **目标机安装时不应依赖本地构建**

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "codex-to-im",
+  "version": "0.1.0",
+  "description": "Installable Codex-to-IM bridge with local setup UI and background service",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist/",
+    "docs/",
+    "references/",
+    "scripts/",
+    "LICENSE",
+    "README.md",
+    "README_CN.md",
+    "SECURITY.md",
+    "SKILL.md",
+    "config.env.example"
+  ],
+  "bin": {
+    "codex-to-im": "dist/cli.mjs"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/main.ts",
+    "dev:ui": "tsx src/ui-server.ts",
+    "open": "node dist/cli.mjs open",
+    "weixin:login": "node --import tsx src/weixin-login.ts",
+    "test": "node scripts/run-tests.js",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.62",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "discord.js": "^14.25.1",
+    "markdown-it": "^14.1.1",
+    "qrcode": "^1.5.4"
+    ,
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "@openai/codex-sdk": "^0.110.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22",
+    "@types/ws": "^8.5.0",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/references/setup-guides.md

@@ -0,0 +1,329 @@
+# Platform Setup Guides
+
+Detailed step-by-step guides for each IM platform. Referenced by the `setup` and `reconfigure` subcommands.
+
+---
+
+## Telegram
+
+### Bot Token
+
+**How to get a Telegram Bot Token:**
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot` to create a new bot
+3. Follow the prompts: choose a display name and a username (must end in `bot`)
+4. BotFather will reply with a token like `7823456789:AAF-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+5. Copy the full token and paste it here
+
+**Recommended bot settings** (send these commands to @BotFather):
+- `/setprivacy` → choose your bot → `Disable` (so the bot can read group messages, only needed for group use)
+- `/setcommands` → set commands like `new - Start new session`, `mode - Switch mode`
+
+Token format: `数字:字母数字字符串` (e.g. `7823456789:AAF-xxx...xxx`)
+
+### Chat ID
+
+**How to get your Telegram Chat ID:**
+1. Start a chat with your bot (search for the bot's username and click **Start**)
+2. Send any message to the bot (e.g. "hello")
+3. Open this URL in your browser (replace `YOUR_BOT_TOKEN` with your actual bot token):
+   `https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates`
+4. In the JSON response, find `"chat":{"id":123456789,...}` — that number is your Chat ID
+5. For group chats, the Chat ID is a negative number (e.g. `-1001234567890`)
+
+**Why this matters:** The bot uses Chat ID for authorization. If neither Chat ID nor Allowed User IDs are configured, the bot will reject all incoming messages.
+
+### Allowed User IDs (optional)
+
+**How to find your Telegram User ID:**
+1. Search for `@userinfobot` on Telegram and start a chat
+2. It will reply with your User ID (a number like `123456789`)
+3. Alternatively, forward a message from yourself to `@userinfobot`
+
+Enter comma-separated IDs to restrict access (recommended for security).
+Leave empty to allow anyone who can message the bot.
+
+---
+
+## Discord
+
+### Bot Token
+
+**How to create a Discord Bot and get the token:**
+1. Go to https://discord.com/developers/applications
+2. Click **"New Application"** → give it a name → click **"Create"**
+3. Go to the **"Bot"** tab on the left sidebar
+4. Click **"Reset Token"** → copy the token (you can only see it once!)
+
+**Required bot settings (on the Bot tab):**
+- Under **Privileged Gateway Intents**, enable:
+  - ✅ **Message Content Intent** (required to read message text)
+
+**Invite the bot to your server:**
+1. Go to the **"OAuth2"** tab → **"URL Generator"**
+2. Under **Scopes**, check: `bot`
+3. Under **Bot Permissions**, check: `Send Messages`, `Read Message History`, `View Channels`
+4. Copy the generated URL at the bottom and open it in your browser
+5. Select the server and click **"Authorize"**
+
+Token format: a long base64-like string (e.g. `MTIzNDU2Nzg5.Gxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx`)
+
+### Allowed User IDs
+
+**How to find Discord User IDs:**
+1. In Discord, go to Settings → Advanced → enable **Developer Mode**
+2. Right-click on any user → **"Copy User ID"**
+
+Enter comma-separated IDs.
+
+**Why this matters:** The bot uses a default-deny policy. If neither Allowed User IDs nor Allowed Channel IDs are configured, the bot will silently reject all incoming messages. You must set at least one.
+
+### Allowed Channel IDs (optional)
+
+**How to find Discord Channel IDs:**
+1. With Developer Mode enabled, right-click on any channel → **"Copy Channel ID"**
+
+Enter comma-separated IDs to restrict the bot to specific channels.
+Leave empty to allow all channels the bot can see.
+
+### Allowed Guild (Server) IDs (optional)
+
+**How to find Discord Server IDs:**
+1. With Developer Mode enabled, right-click on the server icon → **"Copy Server ID"**
+
+Enter comma-separated IDs. Leave empty to allow all servers the bot is in.
+
+---
+
+## Feishu / Lark
+
+### App ID and App Secret
+
+**How to create a Feishu/Lark app and get credentials:**
+1. Go to Feishu: https://open.feishu.cn/app or Lark: https://open.larksuite.com/app
+2. Click **"Create Custom App"**
+3. Fill in the app name and description → click **"Create"**
+4. On the app's **"Credentials & Basic Info"** page, find:
+   - **App ID** (like `cli_xxxxxxxxxx`)
+   - **App Secret** (click to reveal, like `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
+
+### Phase 1: Permissions + Bot capability
+
+> Complete Phase 1 and publish before moving to Phase 2. Feishu requires a published version for permissions to take effect, and the bridge service needs active permissions to establish its WebSocket connection.
+
+**Step A — Batch-add required permissions**
+
+1. On the app page, go to **"Permissions & Scopes"**
+2. Use **batch configuration** (click **"Batch switch to configure by dependency"** or find the JSON editor)
+3. Paste the following JSON (required for streaming cards and interactive buttons):
+
+```json
+{
+  "scopes": {
+    "tenant": [
+      "im:message:send_as_bot",
+      "im:message:readonly",
+      "im:message.p2p_msg:readonly",
+      "im:message.group_at_msg:readonly",
+      "im:message:update",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:chat:read",
+      "im:resource",
+      "cardkit:card:write",
+      "cardkit:card:read"
+    ],
+    "user": []
+  }
+}
+```
+
+4. Click **"Save"** to apply all permissions
+
+If the batch import UI is not available, add each scope manually via the search box.
+
+> **Important:** If `cardkit:card:write` is missing, enabling Feishu streaming in the local workbench will not work. The bridge will log Feishu error `99991672` and fall back to a normal final-result message.
+
+**Step B — Enable the bot**
+
+1. Go to **"Add Features"** → enable **"Bot"**
+2. Set the bot name and description
+
+**Step C — First publish (makes permissions + bot effective)**
+
+1. Go to **"Version Management & Release"** → click **"Create Version"**
+2. Fill in version `1.0.0` and a description → click **"Save"** → **"Submit for Review"**
+3. Admin approves in **Feishu Admin Console** → **App Review** (self-approve if you are the admin)
+
+**The bot will NOT work until this version is approved.**
+
+### Phase 2: Event subscription (requires running bridge)
+
+> The bridge service must be running before configuring events. Feishu validates the WebSocket connection when saving event subscription — if the bridge is not running, you'll get "未检测到应用连接信息" (connection not detected) error.
+
+**Step D — Start the bridge service**
+
+Start the bridge from the local `codex-to-im` workbench. This establishes the WebSocket long connection that Feishu needs to detect.
+
+**Step E — Configure Events & Callbacks (long connection)**
+
+1. Go to **"Events & Callbacks"** in the left sidebar
+2. Under **"Event Dispatch Method"**, select **"Long Connection"** (长连接 / WebSocket mode)
+3. Click **"Add Event"** and add:
+   - `im.message.receive_v1` — Receive messages
+4. Click **"Add Callback"** and add:
+   - `card.action.trigger` — Card interaction callback (for permission approval buttons)
+5. Click **"Save"**
+
+**Step F — Second publish (makes event subscription effective)**
+
+1. Go to **"Version Management & Release"** → click **"Create Version"**
+2. Fill in version `1.1.0` → **"Save"** → **"Submit for Review"** → Admin approves
+3. After approval, the bot can receive and respond to messages
+
+> **Ongoing rule:** Any change to permissions, events, or capabilities requires a new version publish + admin approval.
+
+### Upgrading from a previous version
+
+If you already have a Feishu app configured, you need to:
+
+1. **Add new permissions**: Go to Permissions & Scopes, add these scopes:
+   - `cardkit:card:write`, `cardkit:card:read` — Streaming cards
+   - `im:message:update` — Real-time card content updates
+   - `im:message.reactions:read`, `im:message.reactions:write_only` — Typing indicator
+2. **Publish a new version** — Permission changes only take effect after a new version is approved
+3. **Start (or restart) the bridge** — Start it from the local `codex-to-im` workbench so the WebSocket connection is active
+4. **Add callback**: Go to Events & Callbacks, add `card.action.trigger` callback (card interaction for permission buttons). This step requires the bridge to be running — Feishu validates the WebSocket connection when saving.
+5. **Publish again** — The new callback requires another version publish + admin approval
+6. **Restart the bridge** — Stop and start it again from the local `codex-to-im` workbench to pick up the new capabilities
+
+### Current Feishu streaming behavior with Codex runtime
+
+Even after the Feishu permissions are correct, the current `codex` runtime does **not** guarantee token-by-token text streaming into the Feishu card.
+
+As of **2026-03-24**, the `Codex CLI / SDK` event stream typically emits assistant text when the `agent_message` item completes, rather than as token deltas. In practice, Feishu streaming cards are best understood as:
+
+- early `Thinking` / tool progress updates
+- final response text written into the card at completion
+
+So if you see the final answer appear all at once after the card was created successfully, that is currently expected behavior with `codex`.
+
+### Domain (optional)
+
+Default: `https://open.feishu.cn`
+Use `https://open.larksuite.com` for Lark (international version).
+Leave empty to use the default Feishu domain.
+
+### Allowed User IDs (optional)
+
+Feishu user IDs (open_id format like `ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
+You can find them in the Feishu Admin Console under user profiles.
+Leave empty to allow all users who can message the bot.
+
+---
+
+## QQ
+
+> **Note:** QQ first version only supports **C2C private chat** (sandbox access). Group chat and channel are not supported yet.
+
+### App ID and App Secret (required)
+
+**How to get QQ Bot credentials:**
+1. Go to https://q.qq.com/qqbot/openclaw
+2. Log in and enter the QQ Bot / OpenClaw management page
+3. Create a new QQ Bot or select an existing one
+4. Find **App ID** and **App Secret** on the bot's credential page
+5. Copy both values
+
+These are the only two required fields for QQ.
+
+### Sandbox private chat setup
+
+1. In the QQ Bot management page, configure sandbox access
+2. Scan the QR code with QQ to add the bot as a friend
+3. Send a message to the bot via QQ private chat to start using it
+
+### Allowed User OpenIDs (optional)
+
+**Important:** The value is `user_openid`, NOT QQ number.
+
+`user_openid` is an opaque identifier assigned by the QQ Bot platform to each user. You can obtain it from the bot's message logs after a user sends a message to the bot.
+
+If you don't have the openid yet, leave this field empty. You can add it later via `reconfigure`.
+
+---
+
+## Weixin / 微信
+
+> Risk note: this integration follows the same OpenClaw-style WeChat plugin protocol used by CodePilot. Because it connects a non-OpenClaw product to WeChat, there may be account risk. Use with caution.
+
+### QR login flow
+
+Weixin does **not** use a static bot token in `config.env`.
+
+Instead, run the local QR helper from the local app directory or optional Codex integration directory:
+
+- Repo checkout or app install:
+
+```bash
+cd /path/to/codex-to-im
+npm run weixin:login
+```
+
+- Optional Codex integration install:
+
+```bash
+cd ~/.codex/skills/codex-to-im
+npm run weixin:login
+```
+
+If you are running from a checked-out repo, use that repo's `codex-to-im` directory.
+
+What happens next:
+
+1. The helper requests a fresh WeChat QR code
+2. It writes a local HTML file to:
+  `~/.codex-to-im/runtime/weixin-login.html`
+3. It tries to open that HTML file in your default browser automatically
+4. You scan the QR code with the WeChat app and confirm on your phone
+5. On success, the helper stores the linked account in:
+  `~/.codex-to-im/data/weixin-accounts.json`
+
+The filename stays plural for backward compatibility, but Weixin currently runs in single-account mode.
+
+If the browser does not open automatically, open the HTML file manually.
+
+### Replacing the linked Weixin account
+
+Run the helper again:
+
+```bash
+cd <skill-dir>
+npm run weixin:login
+```
+
+Each successful scan replaces the previously linked Weixin account. Only the most recent account is kept locally and used by the bridge.
+
+### Optional config
+
+Most users should leave these unset:
+
+- `CTI_WEIXIN_BASE_URL`
+- `CTI_WEIXIN_CDN_BASE_URL`
+- `CTI_WEIXIN_MEDIA_ENABLED`
+
+Defaults:
+
+- Base URL: `https://ilinkai.weixin.qq.com`
+- CDN Base URL: `https://novac2c.cdn.weixin.qq.com/c2c`
+- Media: disabled by default in CLI setups; when enabled, inbound images/files/videos are downloaded and forwarded as attachments
+
+### Voice message behavior
+
+Weixin voice messages are handled differently from image/file/video media:
+
+- If WeChat includes built-in speech-to-text text in `voice_item.text`, the bridge forwards that text as the user message.
+- If WeChat does **not** include a transcript, the bridge returns a user-visible error asking the sender to enable WeChat voice transcription and resend.
+- The bridge does **not** download, decrypt, or transcribe raw voice audio on its own.
+
+This rule applies in both Claude Code and Codex runtimes.