@debbl/relay 0.0.0

package/README.md

@@ -0,0 +1,101 @@
+# relay
+
+[English](./README.md) | [简体中文](./README.zh.md)
+
+A Feishu bot that forwards chat messages to Codex and returns results in chat.
+
+## Prerequisites
+
+1. Node.js 20+ and `pnpm`.
+2. `codex` CLI installed and logged in (`codex login`).
+3. Feishu app with bot capability enabled [create-bot](https://open.feishu.cn/document/develop-an-echo-bot/introduction).
+4. Feishu event subscription enabled for `im.message.receive_v1`.
+5. Feishu bot permissions:
+   - P2P messages to bot.
+   - Group messages `@` bot (or all group messages if you prefer).
+
+## Configuration
+
+Relay reads configuration only from `~/.relay/config.json`.
+
+Run `pnpm dev` once to auto-generate a template file (the process exits after creation), then edit:
+
+```bash
+~/.relay/config.json
+```
+
+Config fields:
+
+```json
+{
+  "locale": "en",
+  "env": {
+    "BASE_DOMAIN": "https://open.feishu.cn",
+    "APP_ID": "your_app_id",
+    "APP_SECRET": "your_app_secret",
+    "BOT_OPEN_ID": "ou_xxx",
+    "CODEX_BIN": "codex",
+    "CODEX_TIMEOUT_MS": null
+  }
+}
+```
+
+- Required fields (inside `env`): `BASE_DOMAIN`, `APP_ID`, `APP_SECRET`.
+- Optional fields:
+  - `locale` (root level, supported values: `en`, `zh`; default: `en`; unsupported value falls back to `en` with a warning).
+  - `BOT_OPEN_ID` (empty or missing means disabled).
+  - `CODEX_BIN` (default: `codex`).
+  - `CODEX_TIMEOUT_MS` (default: no timeout; if set, must be a positive integer).
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## How To Use In Feishu
+
+### Message flow
+
+1. Send a text message to the bot.
+2. Bot replies immediately with a processing echo:
+   - `已收到，正在处理任务: <task preview>`
+3. Bot sends final Codex result when done.
+4. After `/new`, the first normal prompt triggers one extra model call to auto-generate a session title.
+
+### P2P chat
+
+- Any text message is handled.
+
+### Group chat
+
+- Bot only handles messages that `@` the bot.
+- Session is isolated by `group + sender` (different users in same group do not share context).
+
+### Commands
+
+- `/help` show help.
+- `/new [default|plan]` create a new conversation (default mode if omitted).
+- `/mode <default|plan>` switch mode for current conversation.
+- `/status` show current thread info.
+- `/projects` show current fixed workspace root.
+- `/reset` clear current conversation.
+
+## Notes
+
+- Sessions are in-memory only; restarting the process resets session mapping.
+- Codex runtime still stores its own threads under `~/.codex/sessions`.
+- Relay fixes workspace root to the process startup directory (`process.cwd()`).
+- Ensure process user can read/write `~/.codex/sessions`.
+- `.env.local` is no longer used for runtime config.
+
+## Quality checks
+
+```bash
+pnpm i18n:extract
+pnpm i18n:compile
+pnpm lint
+pnpm typecheck
+pnpm test
+```

package/README.zh.md

@@ -0,0 +1,101 @@
+# relay
+
+[English](./README.md) | [简体中文](./README.zh.md)
+
+一个将飞书聊天消息转发给 Codex，并将结果回传到聊天中的机器人。
+
+## 前置条件
+
+1. Node.js 20+ 和 `pnpm`。
+2. 已安装并登录 `codex` CLI（`codex login`）。
+3. 已创建并启用机器人能力的飞书应用 [创建机器人](https://open.feishu.cn/document/develop-an-echo-bot/introduction)。
+4. 已开启飞书事件订阅 `im.message.receive_v1`。
+5. 飞书机器人权限：
+   - 与机器人单聊（P2P）消息。
+   - 群聊中 `@` 机器人消息（或按需放开为全部群消息）。
+
+## 配置
+
+Relay 仅从 `~/.relay/config.json` 读取配置。
+
+先运行一次 `pnpm dev` 自动生成模板文件（生成后进程会退出），然后编辑：
+
+```bash
+~/.relay/config.json
+```
+
+配置字段：
+
+```json
+{
+  "locale": "en",
+  "env": {
+    "BASE_DOMAIN": "https://open.feishu.cn",
+    "APP_ID": "your_app_id",
+    "APP_SECRET": "your_app_secret",
+    "BOT_OPEN_ID": "ou_xxx",
+    "CODEX_BIN": "codex",
+    "CODEX_TIMEOUT_MS": null
+  }
+}
+```
+
+- 必填字段（放在 `env` 内）：`BASE_DOMAIN`、`APP_ID`、`APP_SECRET`。
+- 可选字段：
+  - `locale`（放在根级，支持：`en`、`zh`；默认：`en`；如果值不支持会告警并回退到 `en`）。
+  - `BOT_OPEN_ID`（为空或缺失表示禁用）。
+  - `CODEX_BIN`（默认：`codex`）。
+  - `CODEX_TIMEOUT_MS`（默认：不超时；如果设置，必须为正整数）。
+
+## 运行
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## 在飞书中使用
+
+### 消息流程
+
+1. 给机器人发送一条文本消息。
+2. 机器人会先立即回复处理中回显：
+   - `已收到，正在处理任务: <task preview>`
+3. Codex 处理完成后，机器人发送最终结果。
+4. 执行 `/new` 后，首条普通提示词会额外触发一次模型调用，用于自动生成会话标题。
+
+### 单聊（P2P）
+
+- 任意文本消息都会被处理。
+
+### 群聊
+
+- 机器人只处理 `@` 机器人的消息。
+- 会话按 `群 + 发送者` 隔离（同一群内不同用户不会共享上下文）。
+
+### 命令
+
+- `/help` 显示帮助。
+- `/new [default|plan]` 新建会话（省略参数时为 default 模式）。
+- `/mode <default|plan>` 切换当前会话模式。
+- `/status` 显示当前线程信息。
+- `/projects` 显示当前固定工作区根目录。
+- `/reset` 清空当前会话。
+
+## 说明
+
+- 会话映射仅保存在内存中；重启进程后会重置。
+- Codex 运行时仍会把自己的线程存到 `~/.codex/sessions`。
+- Relay 将工作区根目录固定为进程启动目录（`process.cwd()`）。
+- 请确保进程用户对 `~/.codex/sessions` 有读写权限。
+- 运行时不再使用 `.env.local`。
+
+## 质量检查
+
+```bash
+pnpm i18n:extract
+pnpm i18n:compile
+pnpm lint
+pnpm typecheck
+pnpm test
+```

package/bin/relay.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.mjs'

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };