codex-to-im 0.1.0

package/docs/codex-to-im-prd.md

@@ -0,0 +1,424 @@
+# Codex-to-IM 产品需求与技术可行性说明
+
+## 1. 文档目的
+
+本文档用于明确 `codex-to-im` 的产品目标、核心场景、功能需求、会话模型、技术可行性和分阶段实现计划。
+
+目标不是继续堆叠单独的 IM 机器人配置能力，而是把 `Codex Windows App` 作为主工作台，把飞书等 IM 作为远程协同入口，让用户可以在同一条会话上无缝切换。
+
+配套技术设计见：
+
+- [D:/codex/Claude-to-IM-skill/docs/codex-to-im-shared-thread-design.md](D:/codex/Claude-to-IM-skill/docs/codex-to-im-shared-thread-design.md)
+
+## 2. 产品定位
+
+### 2.1 核心定位
+
+`codex-to-im` 是一个本地安装、后台常驻的桥接系统。
+
+它负责：
+
+- 管理 IM 渠道配置
+- 管理本地后台 bridge 服务
+- 把 IM 消息接入 Codex
+- 把 Codex 会话同步到 IM
+- 让用户在电脑端和 IM 端之间共享同一条会话
+
+### 2.2 主次关系
+
+- 主端：`Codex Windows App`
+- 辅助端：`飞书`
+- 后续扩展端：微信、企业微信机器人等
+
+飞书不是独立替代端，而是远程控制与远程观察端。
+
+## 3. 核心目标
+
+### 3.1 产品目标
+
+用户在电脑上主要通过 `Codex Windows App` 工作。
+
+当用户离开电脑时，可以在飞书里：
+
+- 查看当前会话进展
+- 继续给当前会话发送指令
+- 继续推动 Codex 工作
+- 查看工具调用、状态变化、输出内容
+
+回到电脑后，用户仍然能在 `Codex Windows App` 中继续同一条会话，不需要重建上下文，不需要切换到另一条 bridge 私有会话。
+
+### 3.2 用户体验目标
+
+- 安装方式尽可能简单：最终支持 `npm install -g codex-to-im`
+- 启动方式尽可能简单：启动后自动打开本地配置界面
+- 配置方式尽可能图形化：在本地页面填写飞书 / 微信等配置并测试
+- 会话同步尽可能无感：最多只增加一个“是否同步当前会话到飞书”的按钮
+- 飞书切换尽可能清晰：支持固定指令切换会话和线程
+
+## 4. 非目标
+
+以下内容不作为当前第一阶段目标：
+
+- 做一个完整替代 `Codex Windows App` 的 IM 聊天产品
+- 在 IM 中重建一套独立于 Codex 的长期主工作流
+- 在没有显式绑定动作的情况下，自动推断并接管用户当前所有桌面会话
+- 假装已经支持企业微信机器人，若当前没有对应 adapter，则应明确列为后续能力
+
+## 5. 核心用户场景
+
+### 5.1 场景 A：电脑主用，飞书补充
+
+用户在 `Codex Windows App` 中开启一个工作会话。
+
+用户点击“同步到飞书”。
+
+系统将当前会话绑定到飞书聊天。
+
+之后：
+
+- Codex 输出会同步到飞书
+- 飞书可继续发消息到该会话
+- 飞书可查看状态和执行进度
+- 用户回到电脑后可继续在同一条会话里工作
+
+### 5.2 场景 B：用户离开电脑继续下指令
+
+用户在吃饭、开会、路上时，没有电脑在手边。
+
+用户打开飞书，进入对应机器人会话，继续发送：
+
+- 新任务
+- 跟进指令
+- 停止命令
+- 状态查询
+
+这些消息继续进入同一条底层 Codex 会话，而不是进入新的桥接私有线程。
+
+### 5.3 场景 C：多个会话并行时的飞书切换
+
+用户电脑上同时有多个 Codex 会话。
+
+飞书端必须能明确查看和切换“当前控制的是哪一条会话 / 线程”，避免上下文混乱。
+
+## 6. 正式需求
+
+## 6.1 安装与启动
+
+系统应满足：
+
+- 可以作为单个 npm 包发布，包名为 `codex-to-im`
+- 支持全局安装
+- 安装后提供统一入口命令，例如 `codex-to-im`
+- 启动后能拉起本地后台服务
+- 启动后能打开本地 Web 配置界面
+
+## 6.2 本地配置界面
+
+系统应提供本地配置页，至少支持：
+
+- 查看当前服务状态
+- 查看可选 Codex 集成是否安装
+- 填写飞书配置
+- 触发微信扫码
+- 保存配置
+- 测试配置是否可用
+- 启动 / 停止 bridge
+- 安装可选 Codex 集成
+- 查看运行日志
+
+## 6.3 IM 渠道配置
+
+### 飞书
+
+飞书配置页至少支持：
+
+- App ID
+- App Secret
+- Domain
+- Allowed Users
+- 连通性测试
+
+### 微信
+
+微信配置页至少支持：
+
+- 扫码登录
+- 查看扫码是否成功
+- 管理当前登录账户
+- 可选媒体下载能力开关
+
+### 企业微信机器人
+
+企业微信机器人应作为明确的后续需求。
+
+若当前代码中没有 adapter，不应在第一阶段承诺“可用”，但应在产品设计中预留配置区和扩展位。
+
+## 6.4 后台服务
+
+系统应支持本地后台运行，至少满足：
+
+- 不依赖用户一直打开当前终端窗口
+- 可以查询是否运行中
+- 可以查看日志
+- 可以重启
+- 可以在系统重启后恢复运行，作为后续增强项
+
+## 6.5 可选 Codex 集成
+系统应支持把一层很薄的可选集成安装到 Codex 的 skill 目录。
+
+这层集成不是主流程前提，只用于补充两个入口：
+
+- 在 Codex 内直接打开 `codex-to-im`
+- 后续承载“共享当前会话到飞书”的入口
+
+至少应支持：
+
+- 检测是否已安装
+- 自动安装到 `~/.codex/skills/codex-to-im`
+- 若安装目录已存在，给出明确状态
+
+## 6.6 会话共享
+
+这是本产品最关键的需求。
+
+系统必须支持：
+
+- 将电脑端当前工作会话绑定到飞书
+- 飞书继续在该会话上发送消息
+- 飞书消息进入同一条底层 Codex thread
+- Codex 端继续看到这条会话的历史
+- Codex 输出同步到飞书
+
+系统不应默认采用“飞书一条会话、电脑一条会话，然后做内容搬运”的模型。
+
+第一原则应是：**共享同一条底层 thread**。
+
+## 6.7 飞书端会话切换
+
+飞书端必须支持会话 / 线程管理。
+
+至少包括：
+
+- 查看当前绑定会话
+- 列出可用会话
+- 切换到指定会话
+- 绑定到底层指定 thread
+- 新建一个远程会话
+- 查看当前 chat 正在控制哪条 thread
+
+### 建议的固定命令
+
+第一版建议至少支持以下文本命令：
+
+- `/status`
+- `/sessions`
+- `/use <session-id>`
+- `/threads`
+- `/thread <thread-id>`
+- `/new`
+- `/bind <thread-id>`
+- `/stop`
+
+按钮和卡片交互可以作为增强，但不能替代文本命令。
+
+## 6.8 远程控制能力
+
+飞书端不应只是只读观察端。
+
+飞书端必须支持：
+
+- 发送普通文本消息
+- 继续任务
+- 停止当前任务
+- 查看当前状态
+- 查看权限请求
+- 继续推动 Codex 工作
+
+## 7. 会话与线程模型
+
+## 7.1 基本原则
+
+需要明确区分两个概念：
+
+- 产品层会话：用户可理解、可切换、可管理的会话
+- 底层 thread：Codex SDK / Codex CLI 持久化的真实线程
+
+第一阶段推荐模型：
+
+- 一个产品层共享会话对应一个底层 `thread_id`
+- 一个飞书 chat 同时只控制一个“当前活动共享会话”
+- 切换飞书会话，本质上是切换当前绑定的 `thread_id`
+
+## 7.2 同步关系
+
+### 从 Codex 到飞书
+
+- 输出同步到飞书
+- 工具调用同步到飞书
+- 权限请求同步到飞书
+- 运行状态同步到飞书
+
+### 从飞书到 Codex
+
+- 飞书消息写入共享 thread
+- 飞书指令影响当前 thread
+- 飞书停止命令作用于当前共享会话
+
+## 7.3 并发控制
+
+因为电脑端和飞书端都可能同时发输入，所以需要并发控制机制。
+
+第一阶段建议：
+
+- 同一 thread 串行化输入
+- 飞书和桌面消息进入统一队列
+- 当前有任务运行时，新的输入明确提示排队 / 中断 / 拒绝策略
+
+后续可增强：
+
+- 输入权控制
+- 接管模式
+- 只读观察模式
+
+## 8. 技术可行性结论
+
+## 8.1 已确认可行
+
+通过本地代码和官方资料，可以确认以下事项成立：
+
+- `Codex SDK` 支持 `startThread()` 和 `resumeThread(savedThreadId)`
+- `Codex SDK` 线程持久化在 `~/.codex/sessions`
+- 当前 bridge 代码已经可以保存和复用 `sdkSessionId`
+- Codex App 官方说明其会接上 CLI 和 IDE extension 的 session history 和 configuration
+
+因此，**“共享同一条底层 Codex thread” 这条方案本身是可行的。**
+
+## 8.2 未完全确认的部分
+
+目前尚未确认官方是否公开支持以下能力：
+
+- 外部程序自动读取“当前 Codex Windows App 正在聚焦的 thread”
+- 外部程序零动作接管“当前 App 正在打开的 tab”
+- App 对外部线程写入是否总是实时刷新到当前界面
+
+因此，当前最稳妥的产品路径不应依赖“完全自动接管当前 tab”。
+
+## 8.3 第一阶段技术判断
+
+第一阶段应采用：
+
+- 显式绑定当前会话到飞书
+- 共享底层 `thread_id`
+- 通过 `resumeThread(thread_id)` 从飞书继续写入
+
+而不应采用：
+
+- 猜测 App 当前焦点 tab
+- 依赖不可验证的桌面内部状态
+
+## 9. 主要技术风险
+
+## 9.1 桌面会话接管能力不足
+
+如果 Codex Windows App 没有公开“当前会话导出 / 绑定”能力，则产品不能做到完全零按钮同步。
+
+规避方式：
+
+- 设计一个显式按钮“同步当前会话到飞书”
+- 明确这一步会把当前 thread 绑定到飞书 chat
+
+## 9.2 双端同时输入导致上下文混乱
+
+如果电脑和飞书同时往同一条 thread 发消息，会造成任务竞争和用户困惑。
+
+规避方式：
+
+- 统一排队
+- 明确提示当前任务状态
+- 提供 `/stop`
+- 后续增加“接管中”状态提示
+
+## 9.3 IM 渠道能力不一致
+
+飞书、微信、企业微信机器人在交互能力上不同。
+
+规避方式：
+
+- 用文本命令提供通用能力
+- 将按钮 / 卡片作为增强能力，而不是唯一入口
+
+## 10. 分阶段实现建议
+
+## Phase 1：单包可安装、可配置、可运行
+
+目标：
+
+- 合并工程为 `codex-to-im`
+- 本地配置页可用
+- 飞书配置可保存和测试
+- 微信扫码可用
+- bridge 可后台运行
+- 可选 Codex 集成可自动安装
+
+这是当前已经开始落地的阶段。
+
+## Phase 2：共享 thread 模式
+
+目标：
+
+- 产品层会话与底层 `thread_id` 建立映射
+- 飞书端可绑定到共享 thread
+- 飞书消息通过 `resumeThread(thread_id)` 写回共享会话
+- 飞书端可查看当前绑定状态
+
+这是本产品的核心能力阶段。
+
+## Phase 3：会话切换与远程接管
+
+目标：
+
+- 飞书端支持 `/sessions`、`/use`、`/bind`、`/thread`
+- 飞书端支持切换当前活动共享会话
+- 支持“同步当前会话到飞书”按钮
+- 支持从飞书端继续推动工作
+
+## Phase 4：高可用与多渠道增强
+
+目标：
+
+- 启动项 / 系统服务安装
+- 更稳定的后台管理
+- 微信和飞书并行能力完善
+- 企业微信机器人支持
+- 更细粒度的权限与并发控制
+
+## 11. 当前正式结论
+
+本产品应被定义为：
+
+**一个以 Codex Windows App 为主端、以飞书为远程控制端的共享会话系统。**
+
+它的关键不在于“多机器人配置”，而在于：
+
+- 共享同一条底层 thread
+- 电脑与飞书之间无缝切换
+- 飞书可以继续发送指令
+- 会话 / 线程可切换、可绑定、可管理
+
+在技术上，这条路线是可行的。
+
+但第一阶段应采用“显式绑定共享 thread”的可靠方案，而不是依赖桌面 App 内部未公开的自动接管能力。
+
+## 12. 参考依据
+
+### 本地代码依据
+
+- `@openai/codex-sdk` 本地 README：支持 `startThread()` 与 `resumeThread(savedThreadId)`，线程持久化于 `~/.codex/sessions`
+- 当前桥接实现：`src/codex-provider.ts`
+- 当前会话绑定实现：`src/store.ts`
+- 当前 channel 路由实现：`src/lib/bridge/channel-router.ts`
+
+### 官方资料
+
+- OpenAI，《Introducing the Codex app》，发布于 2026 年 2 月 2 日，2026 年 3 月 4 日更新说明 Windows 已可用  
+  https://openai.com/index/introducing-the-codex-app/