Codex Remote · 飞书 / Feishu

在飞书中继续本机 VS Code 的 Codex 会话。Codex Remote 为每个会话建立一个专属飞书群，同步可见历史与新回复，并把群内的文字、图片和交互操作送回原会话。连接由你的 Mac 发起和维护；这不是托管在云端的 Codex 代理。

Continue a local VS Code Codex conversation from Feishu. Codex Remote creates a dedicated Feishu group for each conversation, syncs visible history and new replies, and routes text, images, and supported actions back to the original session. Your Mac initiates and maintains the connection; no hosted Codex agent is involved.

工作方式 / How it works

Remote 插件负责飞书连接、群与会话映射、同步和投递；必需的 Codex IO Bridge 插件通过公开 API 读取本机 Codex 会话并提交输入。同一 macOS 用户的多个 VS Code 窗口共享一个本机后台和一条飞书长连接，但各窗口仍保留自己的 Codex 会话路由。

Remote owns the Feishu connection, group-to-session mapping, sync, and delivery. The required Codex IO Bridge extension reads local Codex sessions and submits input through its public API. VS Code windows belonging to the same macOS user share one local background process and one Feishu WebSocket connection, while each window retains its own Codex route.

本扩展与 IO Bridge 专用于 VS Code 官方 Codex。Codex CLI 和 ChatGPT Desktop 的飞书接入在独立产品中开发；本扩展不会启动 Desktop 的 app-server，也不会在会话被其他程序占用时自动切换宿主。

This extension and IO Bridge serve official Codex in VS Code. Feishu connectors for Codex CLI and ChatGPT Desktop are developed as separate products. This extension does not start a Desktop app-server or automatically switch hosts when another program owns a conversation.

  VS Code 窗口 A / Window A           VS Code 窗口 B / Window B
  +-------------------------+         +-------------------------+
  | Remote                  |         | Remote                  |
  | Codex IO Bridge API     |         | Codex IO Bridge API     |
  | 官方 Codex / Codex      |         | 官方 Codex / Codex      |
  +------------+------------+         +------------+------------+
               | 认证本机 IPC / authenticated local IPC |
               +--------------------+-------------------+
                                    |
                   +----------------v----------------+
                   | 本机共享后台 / Local relay        |
                   | 会话路由 / Session routing       |
                   | 历史同步 / History sync          |
                   | 输入队列 / Input queue           |
                   | 有序出站 / Ordered outbox        |
                   | 本机账号状态 / Local account data |
                   +----------------+----------------+
                                    |
                           WebSocket + Feishu API
                                    |
                   +----------------v----------------+
                   | 飞书应用 / Feishu custom app     |
                   | 机器人私聊 + 专属会话群           |
                   | Bot chat + session groups       |
                   +---------------------------------+

模块 / Module	职责 / Responsibility
Remote 控制面板 / Control panel	配置、连接状态、会话、同步和投递维护 / Configuration, status, sessions, sync, and delivery maintenance
Remote 会话引擎 / Session engine	群绑定、命令、历史与实时消息、交互卡片 / Group binding, commands, history and live messages, interactive cards
本机共享后台 / Local relay process	单例飞书连接、跨窗口路由、持久队列和恢复 / Single Feishu connection, cross-window routing, durable queues, and recovery
Codex IO Bridge	Codex 健康和能力检查、历史读取、输入与事件 / Codex health and capability checks, history reads, input, and events
飞书企业自建应用 / Feishu custom app	机器人私聊、会话群、消息、卡片与媒体 / Bot chat, session groups, messages, cards, and media
定时提醒 / Scheduled reminders	单次、固定间隔或 Cron；持久化调度、原生排队及执行记录 / One-time, interval, or Cron schedules with durable state, native queuing, and run records

从飞书发出的消息先经过机器人长连接与本机后台的身份检查，再交给对应窗口的 IO Bridge；Codex 的可见历史和事件沿反方向进入按群有序的投递队列。发送结果不明时会停下并要求核对，避免把同一任务重新提交给 Codex，或把同一回复重复发到群里。

An incoming Feishu message passes through the bot WebSocket and local relay's identity check before reaching IO Bridge in the window that owns the session. Visible Codex history and events travel back through an ordered, per-group delivery queue. An uncertain submission or send result pauses for review instead of risking a duplicate Codex task or group message.

输入 / Input
飞书群        -> 机器人长连接 -> 身份检查与输入队列 -> IO Bridge -> 原 Codex 会话
Feishu group  -> Bot WebSocket -> Auth + input queue  -> IO Bridge -> Codex session

回复与历史 / Replies and history
Codex 可见消息 -> IO Bridge -> 同步与去重 -> 有序出站队列 -> 原飞书群
Codex records  -> IO Bridge -> Sync + dedup -> Ordered outbox -> Same Feishu group

提交或投递结果不明 / Uncertain result -> 暂停并核对 / Pause for review

Remote 0.18.5 修复问答和最终回复转发：新出现的实时问题会等待原生待答状态确认，再发送一张可选及可填写的提问卡片；历史问题仍只读。与 Bridge 0.12.9 配合后，最终回复直接以最终正文发送，不再先显示进度再发送“上方回复”提示。已有旧记录后来补齐最终标记时，也会按本群模式提供完整最终内容。

Remote 0.18.5 waits for native pending-state confirmation before sending one selectable question card with a free-text field; historical questions remain read-only. Together with Bridge 0.12.9, final replies are delivered directly as final content, without a progress post followed by an empty status notice. Older records whose final phase arrives later also receive complete final content in the group's selected format.

Remote 0.18.6 将飞书常见内置表情名称与富文本表情转换成近似的 Unicode emoji，例如 [笑容满面] → 😁；回复引用也会转换。原有 Unicode 表情保持原样，代码、链接、文件路径及未知自定义表情名称不会被替换。飞书专有表情图案与系统 emoji 的外观可能不同。

Remote 0.18.6 converts common Feishu emoji names and rich-text emotion nodes into approximate Unicode equivalents, including quoted replies. Existing Unicode emoji stay intact. Code, links, file paths, and unknown custom emotion names remain literal. Feishu's proprietary artwork can differ from the system emoji.

Remote 0.18.8 修复带序号的 Codex 问答记录在提交答案时被误判为过期的问题：发卡与提交使用一致的消息身份。此前被此问题误判的卡片，可以在再次提交时重新核对；只有原生问题确实仍在等待回答时才提交，已回答、已结束及结果未确认的提交仍会拦截。

Remote 0.18.8 fixes valid question cards being rejected as expired when Codex history records include ordinals. Card creation and answer submission now use consistent message identities. Previously misclassified cards can be revalidated on explicit resubmission, but only a confirmed pending native question can receive an answer; answered, completed, and uncertain submissions remain protected.

Remote 0.18.9 减少大历史与图片传输造成的后台卡顿：本地消息分片按线性开销处理，状态查询和移除管理使用独立控制连接，重复巡检通知不再反复重写全部状态。操作收到真实结果后立即解除界面锁定，后续状态刷新独立进行；查询失败会保留上次成功状态，并说明当前仍在执行的操作。

Remote 0.18.9 reduces stalls caused by large histories and images. Local message fragments are processed with linear work, status queries and session removal use separate control connections, and repeated maintenance notices no longer rewrite unchanged state. Controls unlock when the actual operation completes; the following status refresh runs independently. Failed reads preserve the last confirmed state and identify any operation still in progress.

Remote 0.18.10 按会话隔离管理操作和后台任务。同一会话的冲突操作保持互斥，不同会话可以分别同步、设置和移除；每条操作在对应会话旁显示进度及结果。移除可中止该会话尚未完成的历史同步，确认后先持久化停止管理，不等待其他会话；旧确认请求不能移除后来重建的新群。同群消息仍按顺序发送，图片渲染和附件处理保留有限并发，账号切换与全机停止仍是全局操作。

Remote 0.18.10 isolates controls and background work by conversation. Conflicting actions within one conversation remain exclusive, while different conversations can sync, change settings, or leave management independently, with progress and results beside each conversation. Removal can stop an unfinished history sync and persists the removal before waiting on any cleanup; stale confirmations cannot remove a newly rebuilt group. Messages within a group remain ordered, rendering and attachment processing retain concurrency limits, and account changes or machine-wide shutdown remain global operations.

在 会话管理 → 已归档会话 → 加载归档 查看分页列表、JSONL 占用大小和文件数。列表只在点击时加载，不加入自动扫描。配合 Bridge 0.12.12，可逐条确认永久删除归档；删除不可恢复，飞书群和已发送消息保留。活跃会话、文件已变化或仍被其他分支引用的归档不能删除。正常会话列表和自动同步排除明确归档、删除的会话；归档容量不包括工作区里被引用的文件。

Open Sessions → Archived sessions → Load archives (会话管理 → 已归档会话 → 加载归档) to browse pages with JSONL sizes and file counts. Archives load only on request. With Bridge 0.12.12, confirm individual permanent deletions; Feishu groups and delivered messages remain. Active sessions, changed files, and archives still referenced by other branches are protected. Normal listings and automatic synchronization exclude explicitly archived or deleted sessions. Reported archive sizes exclude referenced workspace files.

默认单条删除不会连带删除派生子会话；需要清理整组归档时，使用下述关联删除预览。压缩历史 .jsonl.zst 会计入容量；当前不能可靠检查其中的依赖，因此包含压缩历史的目标不能删除，依赖检查遇到其他压缩会话时也会停止并说明原因。

Ordinary single deletion never silently removes spawned children; use the dependency preview below when cleaning up a family of archives. Compressed .jsonl.zst files count toward storage usage. Their dependencies cannot yet be verified reliably, so compressed targets cannot be deleted; dependency checks also stop with an explanation when another compressed session is encountered.

Remote 0.18.11 与 Bridge 0.12.13 增加归档多选、批量删除和恢复。勾选列表中的会话后点击“预览删除”，先查看名称、容量及依赖清单；需要时选择“连同已归档依赖删除”，重新预览完整范围，再确认永久删除。单纯的 fork 来源关系不再误判为文件依赖；真正共享历史或由 Codex 派生的子会话仍会检查。未归档、已加载或无法核验的会话会阻止相关删除。批量操作显示逐项结果，结果不明时停止后续删除，保留已完成事实，不自动重试。

Remote 0.18.11 with Bridge 0.12.13 adds archive selection, batch deletion, and restoration. Select conversations and preview their names, sizes, and dependencies. Optionally include archived dependents, review the expanded scope, then confirm permanent deletion. Fork provenance alone no longer counts as a file dependency; shared history and spawned children are still checked. Unarchived, loaded, or unverifiable sessions block the affected deletion. Batch results identify each outcome; uncertain results stop further deletion without retrying or hiding completed work.

点击归档旁的“恢复为正常会话”会通过 Codex 原生接口恢复本地历史和列表记录，不启动模型回合，也不会自动新建飞书群。恢复后可在 Codex 打开，或在 Remote 的普通会话列表中主动选择同步。恢复意图在执行前保存，后台重启后仍会将其视为旧会话；若旧版共享后台还在运行，请先重启扩展，使新版恢复保护生效。

Restore an archive through Codex's native interface to return its local history and listing to normal, without starting a model turn or automatically creating a Feishu group. Open it in Codex afterward, or explicitly select it in Remote for synchronization. Restoration intent is saved before execution and survives restarts, so restored history is treated as an existing conversation. Restart extensions first if an older shared service is still running.

Remote 0.18.12 与 Bridge 0.12.14 在 会话管理 → Codex 会话 增加单条及跨页多选永久删除。关联子会话显示父级名称、ID 和关系类型，不能从普通列表删除；批量选择也不会绕过保护。确认前展示实际范围、文件数及容量，正在使用、状态未知或有真实子级依赖的会话不会被强行删除。普通列表不级联删除；需要清理整组归档时，先通过 Codex 归档，再使用上方归档管理的关联删除。

Remote 0.18.12 with Bridge 0.12.14 adds single and multi-page batch permanent deletion under Sessions → Codex conversations. Related child conversations show their parent's name, ID, and relationship and cannot be deleted from the ordinary list, including through batch selection. Confirmation shows the exact scope, file count, and storage size. In-use, unknown, or dependency-bearing conversations are protected. This list never cascades deletion; archive a family through Codex first, then use archive management when needed.

执行使用 Codex 原生归档及删除接口。只有确认归档或删除的会话才停止 Remote 管理，已有飞书群和群消息保留。若只完成归档，结果会明确提示到“已归档会话”继续处理或恢复；结果不明时不会自动重试。新功能需要具备已验证安全写锁的官方 Codex app-server 0.159.2 或更新版本，既有同步及归档功能保持各自的兼容检查。

Execution uses Codex's native archive and delete interfaces. Remote management stops only for confirmed archival or deletion; existing Feishu groups and messages remain. If only archival succeeds, the result points to archive management for further cleanup or restoration. Uncertain outcomes are never automatically retried. This new operation requires official Codex app-server 0.159.2 or later with the verified writer-lock behavior; existing sync and archive features retain their own compatibility checks.

适用环境 / Requirements

定时提醒接口 / Scheduled reminder API

Remote 0.18.4 提供本机定时提醒接口与随包命令行工具，支持创建、查询、修改、暂停、恢复、删除及核对执行记录。提醒到点后交给已关联的 Codex 会话；忙碌时进入 Codex 原生队列并向飞书私聊通知。提醒输入本身不会同步到飞书，Codex 回复仍按该群的设置同步。详见安装包中的 docs/reminders.md；运行随包客户端的 help 命令也能读取接口说明，可据此自行封装 skill 或其他工具。

Remote 0.18.4 includes a local reminder API and bundled CLI for creation, queries, updates, pause, resume, deletion, and run review. Due reminders go to the linked Codex session; a busy session receives them in its native queue, with a private Feishu notice. Reminder inputs are excluded from Feishu synchronization, while Codex replies follow the group's normal settings. Read docs/reminders.md in the installed extension, or run the bundled client’s help command, to build a skill or another client.

调度由本机共享后台负责；电脑休眠、关机或没有可用 Codex 窗口时不能保证准点执行。恢复后默认合并漏掉的周期，只补一次。提交结果不明时暂停并等待核对，不会自动重发；删除提醒不会撤回已交给 Codex 的消息。

Scheduling runs in the shared local process. It cannot guarantee execution while the computer is asleep, powered off, or has no available Codex window. By default, missed intervals are coalesced into one execution after recovery. An uncertain submission pauses for review without automatic resending. Deleting a reminder does not retract a message already handed to Codex.

运行条件 / Runtime requirements

需要 macOS 桌面版 VS Code、已登录且可用的官方 Codex 扩展、Codex IO Bridge，以及你有权限管理的飞书企业自建应用。当前不支持 Windows、Linux、Remote SSH、容器或 Codespaces；电脑关闭或休眠时也无法继续执行和转发。

You need desktop VS Code on macOS, a working signed-in official Codex extension, Codex IO Bridge, and a Feishu custom app you can administer. Windows, Linux, Remote SSH, containers, and Codespaces are not supported. Tasks and relaying cannot continue while the Mac is off or asleep.

IO Bridge 是扩展依赖；安装或更新后，按 VS Code 提示重新加载相关窗口。Remote 会检查 Bridge 的实际健康和能力，不会自行安装或修改 Codex 的桥接补丁。功能需要的能力不可用时，面板会说明原因；现有会话不因缺少“新建会话”能力而失去只读访问。

IO Bridge is an extension dependency. Reload relevant VS Code windows after installing or updating either extension. Remote checks Bridge health and actual capabilities; it does not install or modify the Codex bridge patch. The panel explains unavailable capabilities, and a missing create-session capability does not prevent read-only access to existing sessions.

首次连接 / First connection

1. 准备应用。 在飞书开发者后台创建企业自建应用，启用机器人，将自己纳入应用可用范围，配置下方的消息事件、卡片回调和所需权限，然后发布应用版本。选择“使用长连接接收事件”；不需要为机器人部署公网回调服务器。

1. Prepare the app. Create a Feishu custom app, enable its bot, include yourself in its availability scope, configure the events, card callback, and permissions below, then publish an app version. Select long-connection event delivery; the bot does not need a public callback server.

2. 保存凭据。 打开 VS Code 活动栏中的 Codex Remote · 飞书，在 连接与授权 页填写 App ID 和 App Secret 并保存。全新安装时“已识别用户”留空。密钥保存在 VS Code SecretStorage，密码框不会回显已保存的值。

2. Save credentials. Open Codex Remote · 飞书 in the VS Code Activity Bar. On Connection & Authorization (连接与授权), enter the App ID and App Secret and save. Leave the identified-user field empty on a fresh install. The secret is stored in VS Code SecretStorage and is never echoed back into the password field.

3. 识别本人。 点击 连接飞书并识别账号。面板显示等待私聊后，在此机器人的原私聊发送“菜单”或 /menu。插件只接受本次连接后的真人私聊，取得当前应用下的本人 open_id，保存绑定并发回入口卡片；无需手工填写 ID。

3. Identify yourself. Select Connect to Feishu and identify account. When the panel asks for a direct message, send “菜单” or /menu to this bot. Remote accepts a human direct message from this connection, saves your open_id for this app, and returns the entry card. You do not need to enter the ID manually.

4. 开始会话。 从私聊控制菜单选择“会话管理 → 新建会话”，或在侧栏选择现有 Codex 会话并打开到飞书。首次同步会在历史投递完成后邀请你进入专属群；以后在群内直接发消息。若 Codex 尚未就绪，先到 IO Bridge 设置查看实际状态。

4. Start a conversation. Create a session from the bot's direct-message entry, or select an existing Codex session in the sidebar and open it in Feishu. Initial history is delivered before you are invited to its dedicated group; then you can message the group directly. If Codex is not ready, inspect the actual status in IO Bridge settings.

保存配置、检查配置和启动连接是不同操作。检查只验证应用凭据与机器人身份；启动才建立连接并发送入口。以后可在侧栏停止本机共享后台；关闭某个侧栏或 VS Code 窗口不会停止其他窗口正在使用的连接。

Saving settings, checking settings, and starting the connection are separate actions. A check validates app credentials and bot identity; starting connects and sends the entry card. The sidebar can stop the shared local process. Closing a sidebar or one VS Code window does not stop a connection used by other windows.

飞书应用清单 / Feishu app checklist

以下是功能所需的应用配置。飞书后台的权限名称和租户策略可能变化，请以相应 API 在开发者后台显示的要求为准；新增权限或事件后需发布新应用版本。

These settings cover the app features. Feishu's permission names and tenant policies may change; use the requirements shown for each API in the developer console. Publish a new app version after adding permissions or events.

项目 / Item	配置或用途 / Setting or use
机器人能力 / Bot	启用并发布，授权用户在应用可用范围内 / Enable and publish; include the operator in the app's availability scope
事件模式 / Event mode	使用长连接接收事件 / Receive events over a long connection
消息事件 / Message event	`im.message.receive_v1`
卡片回调 / Card callback	`card.action.trigger`
机器人发送 / Bot sends	`im:message:send_as_bot` 或更宽的 `im:message`
接收私聊 / Direct messages	`im:message.p2p_msg:readonly`
接收群消息 / Group messages	`im:message.group_msg`；只订阅 @ 机器人消息时，每次操作都要 @ 机器人 / With @-only delivery, mention the bot for each action
读取被回复消息 / Read replied-to messages	本地投递记录找不到原消息时，调用 `im.message.get`；需该接口适用的 `im:message`、`im:message:readonly` 或 `im:message.history:readonly`，且机器人在群内 / When the local record lacks the original, use `im.message.get` with an applicable read scope and bot membership
创建群 / Create groups	`im:chat:create` 或更宽的 `im:chat`
邀请成员 / Invite members	`im:chat.members:write_only` 或更宽的 `im:chat`
更新群名和头像 / Rename groups and update avatars	`im:chat:update` 或更宽的 `im:chat`；部分租户还需 `im:chat:operate_as_owner` / Some tenants also require `im:chat:operate_as_owner`
图片和文件 / Media	上传需要 `im:resource` 或 `im:resource:upload`；读取用户消息中的图片需适用的 `im:message`、`im:message:readonly` 或 `im:message.history:readonly` / Upload needs `im:resource` or `im:resource:upload`; reading incoming images needs an applicable message-resource scope
本人身份代发 / Send as user	可选：`im:message`、`im:message.send_as_user`、媒体用 `im:resource`，自动续期用 `offline_access` / Optional: these scopes support user-authorized sends, media, and renewal

“已识别用户”必须是本人在当前应用下的 open_id，不能填机器人的 bot.open_id 或其他应用的 ID。只安装插件并不会预填你的应用、账号或私有服务地址。

The identified user must be your own open_id for this app, not the bot's bot.open_id or an ID from another app. A fresh installation does not prefill an app, account, or private service address.

功能一览 / Features

下表按实际操作归纳功能。会话群设置彼此独立；标为“本机共用”的选项适用于同一 macOS 用户的所有窗口和会话群。

The table groups features by workflow. Group settings are independent; options marked “local-wide” apply to all windows and session groups for the same macOS user.

功能 / Feature	用户能做什么 / What you can do	范围 / Scope
会话映射 / Session mapping	每个 Codex 会话建立或复用一个私有群；群名跟随会话名 / Create or reuse one private group per Codex session; update its title	按会话 / Per session
历史同步 / History sync	新群选择最近 1、5、10、30、50、100 轮或全量；按原时间顺序导入 / Import the latest 1, 5, 10, 30, 50, or 100 rounds, or all history, in source order	按群 / Per group
增量与重同步 / Catch-up and rebuild	`/sync` 补齐原群新记录；必要时完整同步到新群，保留旧群 / Catch up in the same group, or rebuild in a new group while retaining the old one	按群 / Per group
自动同步新会话 / Auto-sync new sessions	可选地自动为本机新会话建群；普通会话全量，分支会话默认最近 5 轮 / Optionally create groups for new local sessions; all history for ordinary sessions, last five rounds for forks	本机共用 / Local-wide
远程新建 / Create remotely	在已打开工作区新建，或选择目录并打开新 VS Code 窗口 / Create in an open workspace or choose a folder and open a new VS Code window	按请求 / Per request
文字与图片输入 / Text and images	群内发送任务、图片或图文；忙碌时选择立即调整方向、原生排队或取消 / Send tasks, images, or both; while busy, steer now, queue natively, or cancel	按会话 / Per session
回复引用与注释 / Replies and annotations	回复同群消息时把原消息文字交给 Codex 作上下文；Codex 所选文字注释在飞书中简明展示 / Pass replied-to group text as context and display Codex text selections readably	按会话 / Per session
会话控制 / Session controls	选择模型和推理强度、中断当前回合、处理受支持的审批与问题 / Choose model and reasoning effort, interrupt a turn, answer supported approvals and questions	按会话 / Per session
MCP 工具审批 / MCP tool approval	在原会话群查看工具参数摘要、允许一次或拒绝；仅显示 Codex 本次允许的会话级及长期授权选项 / Review tool summaries in the original group, allow once or decline, and select only the persistent scopes offered by Codex	按请求 / Per request
最终回复模式 / Final-reply formats	五种 Markdown 与图片呈现方式，按群选择宽度 / Five Markdown and image formats, with group-specific width	按群 / Per group
图表与宽图 / Diagrams and wide images	Mermaid 渲染、源码查看、手动重发图表和最终回复宽图 / Render Mermaid, inspect source, and request diagram or wide-reply images	按群 / Per group
自动附件 / Automatic attachments	按图片、Markdown、配置、代码、其他五类和回复阶段决定是否发送本地引用文件 / Control referenced local-file sends by five categories and reply phase	按群 / Per group
历史回复范围 / Historical reply scope	每群选择是否同步历史中间回复；实时进度独立处理 / Choose whether each group imports historical intermediate replies; live progress remains separate	按群 / Per group
文件分类规则 / File classification	自定义配置、代码类的扩展名或完整文件名 / Customize configuration and code filename or extension rules	本机共用 / Local-wide
历史文件 / History files	`/files` 筛选会话历史引用并手动发送当前本地版本 / Filter referenced files and send their current local versions on demand	按群 / Per group
本人身份 / User identity	可选地授权历史用户消息以本人身份发送；私聊 `/authorize` 可在手机上重新授权 / Optionally send historical user messages as yourself; renew from a phone with `/authorize` in the bot chat	按应用绑定 / Per app binding
会话管理 / Session management	查看同步、离线和归档状态；移除管理时保留飞书群及 Codex 会话 / Inspect sync, offline, and archived states; remove management without deleting groups or Codex sessions	本机共用 / Local-wide
运行中会话 / Running sessions	私聊按需汇总各已接入窗口正在处理、等待授权或等待回答的会话，显示名称与工作目录，包含未同步会话 / On demand, list active or waiting sessions across connected windows with names and working directories, including unmanaged sessions	仅本人私聊 / Owner direct chat only
诊断与恢复 / Diagnostics	查看三层连接状态、日志、失败或未知投递并人工核对 / Inspect bridge, local relay, and Feishu status; review logs and failed or uncertain sends	本机共用 / Local-wide

新群默认使用 模式 2：文本 Markdown 自适应、1200 像素图片宽度和全量历史。历史中的普通中间回复默认不导入；正常连接期间的新进度仍可实时同步。自动同步新会话默认关闭，本地文件自动发送默认只包含最终回复中的图片和 Markdown 文件。

A new group defaults to mode 2: adaptive Markdown, 1200 px image width, and all history. Ordinary intermediate replies are omitted from historical imports by default; new progress can still be relayed live. Auto-sync of new sessions is off by default, and automatic local-file sends initially include only images and Markdown files referenced by final replies.

设置分为 连接与授权、会话管理、群消息、全局配置、维护与诊断 五页。连接设置和会话管理的主要区块可以折叠，并保留展开状态。已同步、全部可同步、已归档三个列表统一显示完整会话 ID、工作目录、当地时间的最后更新时间、本地历史容量和文件数；已同步列表另显示本群轮数、会话总轮数及群设置。容量仅统计会话自身的本地历史文件（包括压缩副本），不包含继承的父历史或工作目录中的附件；信息无法读取时显示未知，不当作零。普通列表和已同步列表只在查看或主动刷新时请求容量，不新增后台扫描。

Settings have five pages: Connection & authorization, Sessions, Group messages, Global settings, and Maintenance & diagnostics. Main connection and session sections can collapse and retain their state. Managed, available, and archived conversation lists show full IDs, working directories, local update times, and local history sizes and file counts. Managed entries also show synchronized/total rounds and group settings. Sizes count only a conversation's own local history files, including compressed copies, excluding inherited parent history and workspace attachments. Unreadable metadata appears as unknown rather than zero. Available and managed lists request storage metadata on viewing or manual refresh, without new background scans.

在 群消息 保存手动新群的默认设置，或选择已有群修改：最终回复形式、图片宽度、自动发送的五类本地文件、非最终回复是否发送文件、历史是否包含中间回复。会话管理 → 自动同步新会话 有单独的建群默认设置；从飞书主动创建的群使用手动新群默认值。默认值只在建群时使用，修改它们不覆盖已有群。升级会把原全局文件和历史开关复制到已有群；之后各群独立生效。文件分类规则、宽度档位和渲染浏览器位于 全局配置。内嵌图片、回复渲染图和 /files 手动发送不受自动本地文件开关限制。

In Group messages, save defaults for manually created groups or select an existing group to change its final-reply format, image width, five allowed local-file categories, non-final file delivery, and historical intermediate replies. Sessions → Auto-sync new sessions has separate creation defaults; groups explicitly created from Feishu use the manual defaults. Defaults apply only when creating a group and never overwrite existing groups. Upgrading copies the former global file and history switches into existing groups, after which each group is independent. File classification rules, width presets, and the rendering browser remain in Global settings. Embedded images, rendered reply images, and explicit /files sends are exempt from automatic local-file switches.

群内 /settings 管理当前群，/attachments、/history 快速进入相应选项；机器人私聊中的对应入口管理手动新群默认值。更改设置仅影响后续投递，已经发送或已经按历史范围跳过的消息不会重发或撤回。

In a group, /settings manages that group, with /attachments and /history opening the corresponding options. The matching bot-private-chat controls manage defaults for manually created groups. Changes affect subsequent deliveries; already sent messages and history previously skipped by scope are neither replayed nor recalled.

发送到飞书的静态图片达到 10 MB 上传限制时，Remote 会自动在本机生成小于 10,000,000 字节的上传副本。先尝试无损重编码，再逐步降低编码质量，必要时才等比缩小尺寸，不裁剪、不覆盖本地原图。小于限制的图片保持原始字节。历史/实时图片、富文本图片、回复宽图和图表共用此处理，机器人及本人身份发送都支持；原有按群自动发送开关与手动发送规则继续生效。

When a static image reaches Feishu's 10 MB upload limit, Remote creates a local upload copy below 10,000,000 bytes. It tries lossless re-encoding first, then progressively adjusts encoding quality, and only scales proportionally if needed. It never crops or overwrites the original file. Images below the limit retain their original bytes. Historical/live images, rich-text images, wide replies, and diagrams share this handling for both bot and user-identity sends; existing group policies and manual-send rules remain in effect.

自动压缩复用 全局配置 中选择的 Chrome、Edge 或 Chromium，在独立离线进程中串行、按需运行，完成后释放。透明背景和图片显示方向会保留。为限制内存占用，单张原图最多读取 40 MiB、最多解码 4000 万像素；Bridge 需要 0.12.16 或更新版本才能按需读取超过旧上限的原图。超限动图不会静默变成静态首帧；不支持的格式、损坏图片、超出处理范围或缺少浏览器时会说明原因，原图保留供手动处理。

Compression reuses Chrome, Edge, or Chromium selected in Global settings, running serially on demand in a separate offline process that is released afterward. Transparency and display orientation are preserved. To bound memory, source reads are limited to 40 MiB and decoding to 40 million pixels per image. Bridge 0.12.16 or later is needed to explicitly read originals beyond the former limit. Oversized animations are never silently flattened to their first frame. Unsupported formats, damaged images, processing-limit violations, or a missing browser produce an explanation while preserving the original for manual handling.

群内回复优先使用本机已保存的同群消息，必要时再从飞书读取原消息。读取失败时当前正文仍照常提交，群里会说明引用没有附上；回复图片或文件只附类型说明，不会悄悄把原媒体重新交给 Codex。Codex 的所选文字注释仅改变飞书里的展示，原始会话内容和发送队列保持不变。

Group replies first use the locally saved message and otherwise read the original from Feishu. If that read fails, the new text still goes to Codex and the group is told that the quote was omitted. Replying to an image or file adds a type description, not the original media. Codex text selections are reformatted only for display in Feishu; stored conversation content and input queue behavior remain unchanged.

Codex 的结构化问题使用 ❓ 提问 · 本地时间 标记。已关联群中的实时问题，经 Codex 当前待回答状态确认后，直接显示为一张支持选项和自由填写的问答卡；回答提交到原来的问题，并在原群反馈。历史问题保留题目、选项和已知回答，不会因为同步历史而重新要求作答。普通进度中的问号不自动变成问答卡。

Structured Codex questions use ❓ Question · local time. In an existing linked group, a question confirmed as pending in Codex appears as one card with choices and a free-text field. Answers go to the original question, with confirmation in the same group. Historical questions preserve their prompts, choices, and known answers without reopening a completed interaction. Question marks in ordinary progress text do not create forms.

本人身份授权可自动续期。遇到确定未发送的断网请求时，联网后会重新尝试；授权确实不可用时，机器人会在私聊提醒。此时确认未送达的历史用户消息由机器人按原顺序继续同步，发送结果不明的消息仍需先在 Remote 面板核对。手机上可在机器人私聊发送 /authorize，打开授权卡片中的链接，再把浏览器最终跳转的完整 localhost 地址填入卡片；授权码只接受本次授权和已绑定的本人账号。

User authorization can renew automatically. A request known not to have reached Feishu is retried after reconnection. If authorization becomes unavailable, the bot sends a direct-message reminder. Historical user messages definitely not sent continue in order as bot messages; uncertain sends still need review in Remote. On a phone, send /authorize to the bot, open the consent link, and enter the complete final localhost redirect URL in the card. The code is accepted only for the current request and bound operator.

五种最终回复模式 / Five final-reply modes

模式按群保存，修改后影响新安排的消息，不改写已经送出的历史。需要生成图片时使用本机 Chrome、Edge 或 Chromium；普通文字在自适应模式下无需启动浏览器。

The mode is saved per group. Changing it affects newly planned messages, not previously delivered history. Image rendering uses a local Chrome, Edge, or Chromium installation; ordinary text in adaptive mode does not launch a browser.

同一条 Codex 消息中的文字、原有图片和渲染宽图会按原顺序合并为一条飞书富文本消息，标题和时间只显示一次，图片本身只包含原内容。只有超过飞书单条消息的承载限制时才分段；Remote 按完整请求的 UTF-8 字节计量，并为飞书解析样式预留空间。普通文件不支持内嵌富文本，仍作为独立文件附件发送。已经排入发送队列的旧消息保留原来的格式和投递记录。

Text, original images, and rendered previews from one Codex message are combined in order into one Feishu rich-text message. The heading and time appear once, outside the images. Messages are split only when needed to fit Feishu's limit; Remote measures the full UTF-8 request and reserves space for Feishu's style processing. Files cannot be embedded in rich text and remain separate file attachments. Existing queued messages keep their original format and delivery records.

模式 / Mode	呈现方式 / Presentation
1 · 文本 Markdown / Text Markdown	全文文字，代码和 Mermaid 保留源码 / Full text; code and Mermaid stay as source
2 · 自适应 / Adaptive (default)	文字保留 Markdown，表格、代码块和 Mermaid 在原位置转图片 / Keep prose as Markdown; render tables, code blocks, and Mermaid in place
3 · 自适应整图 / Adaptive full image	有宽内容时整篇转图片，否则发送文字 / Render the whole reply only when it contains wide content
4 · 纯图片 / Image only	每条最终回复整篇转图片 / Render every final reply as images
5 · 文本与图片 / Text and image	在同一条消息中先展示完整文字，再展示整篇图片 / Show full text followed by full-reply images in the same message

常用入口 / Common commands

当 Codex 请求 MCP 工具执行审批 时，Remote 会在对应会话群显示审批卡，列出服务器、工具名称，以及可识别的模型、尺寸、参考图片数量和提示词摘要；“查看详情”展示经过清洗的参数。图片编码和敏感凭据不会随这张审批卡发送，也不会作为原始 MCP 参数进入 Remote 的持久化状态。清洗在窗口发送给共享后台之前完成，避免大图片参数挤占本机通信通道。

When Codex requests MCP tool execution approval, Remote posts a card in the session's group with the server, tool, and recognizable model, size, reference-image count, and prompt summary. View details shows sanitized parameters. Image encodings and sensitive credentials are excluded from the card and from persisted raw MCP arguments. Projection happens before the window sends the event to the shared backend, keeping large image arguments out of local transport frames.

默认提供 允许一次、拒绝。只有当前 Codex 请求提供相应范围，才显示 本会话允许、始终允许；这两项需确认作用范围，“始终允许”会修改该服务器、该工具的长期授权策略。审批选择和反馈留在原群；重复点击、电脑端已处理、Codex 已重启或群已重建的旧卡不会重复授权。提交结果不明时请在 VS Code 核对，Remote 不自动重发。普通 MCP 表单、网页验证及无法识别的审批结构仍提示在 VS Code 处理；历史同步不会把旧工具记录变成可点击审批。

Cards normally offer Allow once and Decline. Allow for this session and Always allow appear only when the current Codex request permits those scopes and require scope confirmation; Always allow changes the persistent policy for that server and tool. Responses stay in the original group. Duplicate clicks and cards resolved on the computer, invalidated by a Codex restart, or belonging to a rebuilt group cannot repeat authorization. If delivery is uncertain, check VS Code; Remote never resubmits automatically. Ordinary MCP forms, web verification, and unrecognized approval schemas remain in VS Code. Historical imports do not turn old tool records into actionable approvals.

在机器人私聊或会话群发送一次菜单（也兼容 /help、/menu），即可进入按功能分类的控制菜单。之后使用按钮、选项和输入框完成操作，无需记忆其他命令。旧命令继续兼容，但不再作为菜单流程的必要步骤。

Send 菜单 once in the bot's direct chat or a session group (/help and /menu also work) to open the categorized control menu. From there, use buttons, choices, and input forms without memorizing additional commands. Existing commands remain compatible as optional shortcuts.

位置 / Where	分类 / Category	按钮提供的操作 / Actions
私聊 / Direct chat	会话管理 / Sessions	新建、目录、三类会话列表、图片减脂与瘦身、整理任务、批量删除、归档恢复、运行中会话 / Create, directories, conversation lists, image compression/removal and maintenance jobs, batch deletion, restore and running sessions
私聊 / Direct chat	新群默认 / New-group defaults	自动同步开关与默认策略、手动新群默认 / Automatic discovery and its defaults; independent manual defaults
私聊 / Direct chat	全局配置 / Shared settings	宽度档位、浏览器、文件分类、历史图片压缩范围 / Width presets, browser, file classification, image compression targets
私聊 / Direct chat	机器人头像 / Bot avatar	十个预设、手机上传、预览确认与发布 / Ten presets, mobile upload, preview and publication
私聊 / Direct chat	本人身份授权 / User identity	查看授权状态、发起授权、切换发送身份、取消等待、确认清除授权 / View consent, authorize, change sender, cancel consent, confirm credential removal
私聊 / Direct chat	状态与帮助 / Status and help	版本、窗口、连接诊断、投递核对、整理任务、待处理问答 / Versions, windows, diagnostics, delivery reconciliation, maintenance jobs and interactions
会话群 / Session group	对话控制 / Conversation	模型、改名表单、调整方向表单、原生排队表单、停止确认、待处理事项 / Models, rename, steering and queue forms, interruption confirmation, pending interactions
会话群 / Session group	历史同步 / History	增量同步到当前群 / Catch up in the same group
会话群 / Session group	阅读与图表 / Reading	最终回复宽图、最近图表、图表源码 / Wide final reply, recent diagrams and source
会话群 / Session group	会话文件 / Files	分类、排序、翻页、发送当前文件版本 / Filter, sort, paginate, send the current local file
会话群 / Session group	此群设置 / Group settings	回复模式、图片宽度、文件类型、历史中间回复范围 / Reply mode, image width, attachments and historical progress
会话群 / Session group	状态与帮助 / Status and help	当前会话状态及返回分类入口 / Session status and menu navigation

电脑设置与飞书菜单共用配置和操作服务。已管理、可同步、已归档列表统一展示 ID、目录、更新时间和本地占用；删除和图片整理先预览范围及前后尺寸，再确认执行。

Desktop settings and Feishu menus share the same services. Managed, available and archived lists show IDs, directories, update times and local storage. Deletion and image maintenance preview the scope and before/after sizes before confirmation.

首次绑定和应用密钥更换仍使用电脑端安全存储；手机菜单提供账号状态与打开电脑设置的按钮。后台已经停止时，需要先在电脑启动连接。手机重载操作会检查 Codex 忙闲；VS Code 未开放独立启用新版扩展的命令时，会明确提示并回退到重载所选窗口。

Initial binding and app-secret changes use secure storage on the computer; the mobile menu shows account details and can open that settings page. A stopped relay must be started on the computer. Mobile reload checks Codex activity first; when VS Code does not expose a separate command to activate installed updates, the confirmation explains that the selected window will reload.

改名、文件分类和消息内容通过卡片输入框填写。调整方向及排队仍使用 Codex 原生提交链路；同一表单只提交一次，重启后也不会自动重复发送。停止操作先确认打开卡片时的回合；旧回合结束后，旧卡不能中断新的任务。卡片过期或会话群变化时，可通过反馈中的按钮返回菜单重新操作。

Rename conversations, edit file classification, and compose messages in card forms. Steering and queuing use the existing native Codex submission path. Each form is submitted once and is not replayed after restart. Interruption confirms the original turn, so an old card cannot stop a newer task. Expired cards or changed group bindings return an actionable menu link.

“待回答与待授权”只显示可核实的当前请求，重新打开时把原卡发回所属会话群；不会将历史提问变成新的待答问题。跨会话列表和全局设置在机器人私聊处理，本群操作绑定原会话与群。

Pending interactions show current verifiable requests and reopen the original card in its owning group. Historical questions are never revived. Cross-session listings and shared settings stay in the bot's private chat; group actions remain bound to their original session and chat.

在机器人私聊控制菜单点击 会话管理 → 正在运行的会话，即可查询已接入本机 Remote 的各个 VS Code Codex 窗口。结果显示会话名称、完整工作目录及 处理中／等待授权／等待回答 状态，包含尚未同步到飞书的会话；同一后端的同一会话会去重。结果只发到已绑定本人的机器人私聊，群内使用该命令会提示前往私聊。

Select 会话管理 → 正在运行的会话 (Sessions → Running sessions) in the bot's direct-chat menu, to query VS Code Codex windows connected to this local Remote. Results include names, full working directories, and running / waiting for approval / waiting for input states, including sessions not synchronized to Feishu. The same session on the same backend is deduplicated. Results go only to the bound owner's direct chat; group invocations point you there.

Codex 自动派生的子代理按原生父子关系归入所属主会话，主会话旁显示仍在运行或等待的子代理数量，不再将它们计为多个“未命名会话”。主会话自身空闲而子代理仍工作时，会注明子代理正在处理或等待。用户手动 checkout／fork 的会话继续独立展示；不会按名称为空、工作目录相同或 fork 来源猜测归属。父关系无法确认、关系冲突或旧版 Bridge 未提供关系信息时，保留已确认的活动并注明结果不完整。

Codex-spawned subagents are grouped under their main conversation using native ancestry, with a count of active or waiting subagents instead of separate unnamed conversation entries. If only subagents remain active, the row explicitly describes subagent activity. Manually checked-out or forked conversations stay separate. Empty names, shared directories, and fork origins never establish agent ancestry. Missing or conflicting ancestry and older Bridge versions preserve confirmed activity while marking the result incomplete.

卡片标明本地时区的查询时间，支持翻页及 刷新运行状态。翻页使用同一份快照，保留 15 分钟；刷新才重新查询。该功能需要支持 running-threads 的 Bridge，只在请求时读取已加载会话的原生运行状态，不增加后台轮询或完整历史扫描。断连、旧版 Bridge 或部分窗口读取失败时，会明确显示结果不完整，不能据此认定所有会话均已空闲。

Cards show the query time in the local timezone and provide paging and Refresh running status. Pages share a snapshot retained for 15 minutes; refresh performs a new query. This requires Bridge's running-threads capability and reads native status for loaded sessions only on request, without additional background polling or full-history scans. Disconnected windows, older Bridge versions, and failed reads are reported as incomplete results, never as evidence that every session is idle.

机器人与群头像 / Bot and group avatars

在“连接与授权 → 机器人头像”中可以查看机器人当前已经生效的头像，并打开共享头像选择器。选择器提供机器人、猫、狐狸、熊、猫头鹰、鲸鱼、火箭、星球、山峰和叶子共 10 个默认头像，也可以通过本机文件选择器上传 PNG 或 JPEG 图片。图片需不超过 2 MiB，宽、高均为 241–4096 像素；建议使用 512×512、未经圆角裁剪的正方形图片。选中后先预览，再确认应用。

In Connection and authorization → Bot avatar, view the bot's current online avatar and open the shared picker. It includes ten presets—robot, cat, fox, bear, owl, whale, rocket, planet, mountain, and leaf—and supports local PNG or JPEG uploads. Images must be at most 2 MiB, with each dimension between 241 and 4096 pixels; a 512×512 square without rounded cropping is recommended. Preview the selection before applying it.

机器人头像属于飞书应用配置。点击保存只更新头像草稿；随后单独点击“提交发布”，确认将提交该应用当前所有待发布配置。飞书审核通过且头像正式生效后，当前头像预览才会更新。该功能需要应用身份权限 application:application:patch，查询自身应用配置与版本状态需要 application:application:self_manage；不依赖“以本人身份发送”的 OAuth 授权。应用正在审核或提交结果未确认时，先刷新状态核对，再进行下一次操作。

The bot avatar is part of the Feishu application configuration. Saving changes only the avatar draft. Use the separate Submit for release action and confirm that it submits all of the application's current unpublished changes. The online preview updates after approval and the avatar takes effect. This requires the application scope application:application:patch; reading the app's own configuration and version status requires application:application:self_manage. It does not use the optional send-as-user OAuth authorization. Refresh and verify an under-review or uncertain release before performing another operation.

Remote 创建的新会话群会复用机器人当时已经生效的头像，未发布的头像草稿不会用于建群。“会话管理 → 已同步到飞书的会话”中的每个群提供“同步头像”和“设置头像”：前者复制机器人的当前线上头像，后者打开同一个头像选择器，为该群单独选择头像。已有群的独立头像不会因为修改机器人头像而自动覆盖；需要更新时手动同步即可。头像下载和上传结果在本机共用并缓存，空闲时不会持续轮询头像。

New session groups created by Remote inherit the bot's current online avatar; unpublished drafts are never used. Each group in Session management → Synced sessions provides Sync avatar to copy the bot's current avatar and Set avatar to use the same picker for an independent group avatar. Changing the bot avatar does not overwrite existing group avatars automatically; sync them explicitly when needed. Downloads and upload keys are shared and cached locally, with no idle avatar polling.

本机中转服务功能表 / Local relay service inventory

“中转服务”是 Remote 在本机启动的共享后台，不是可供他人访问的公网服务。下面列出它承担的完整职责，便于判断消息经过哪里、状态存放在哪里，以及某一步失败时如何恢复。

The “relay service” is Remote's local shared background process, not a public service. This inventory shows its responsibilities, where messages pass, where state lives, and how each part recovers.

功能 / Function	行为与边界 / Behavior and boundary
单例生命周期 / Single instance	本机内核锁防止多个后台争用同一飞书长连接；最后一个窗口离开后空闲退出 / A kernel lock prevents competing local connections; idle exit follows the last window
认证本机 IPC / Authenticated local IPC	VS Code 窗口通过认证 Unix socket 接入；路由和恢复信息只授予已接入窗口 / Windows connect through authenticated Unix sockets; routes and recovery data stay with attached windows
飞书连接 / Feishu connection	一条 SDK WebSocket 长连接收消息与卡片事件；连接状态依据实际回调 / One SDK WebSocket receives messages and card events; status follows actual connection callbacks
临时身份识别 / Temporary pairing	只在明确发起识别后处理新私聊，识别完成或取消后清理临时状态 / Process a new direct message only during explicit pairing; clear temporary state afterward
账号分区 / Account partition	App ID 与授权用户共同划分群映射、队列和同步状态；切换账号保留旧分区 / Partition mappings, queues, and sync state by app and operator; retain old partitions on switch
跨窗口路由 / Window routing	记录 Bridge 的后端与窗口身份，把会话输入交给正确的可用窗口 / Route session input to the available window for its Bridge backend
桥接能力门禁 / Bridge capability gate	根据公开健康状态与能力决定可用操作，不从扩展版本号推测 / Gate operations by public health and capabilities, not inferred version numbers
入站鉴权与去重 / Inbound authorization and deduplication	仅授权用户可操作；飞书消息 ID 和操作 ID 防止重复事件执行 / Restrict actions to the operator; message and operation IDs prevent duplicate handling
输入持久队列 / Durable input queue	忙碌或明确未提交时等待；提交结果不明时暂停，避免重复模型调用 / Wait for busy or definitely unsubmitted input; pause unknown results to avoid duplicate model calls
会话创建与群绑定 / Session and group creation	保存操作进度，避免重复按钮重开窗口、重建会话或群 / Persist operation progress to prevent duplicate windows, sessions, or groups
历史与实时观察 / History and live observation	按 Bridge 可见 JSONL 消息和事件追赶，同群保存同步位置与去重记录 / Catch up from Bridge-visible JSONL messages and events; retain per-group position and deduplication
顺序出站队列 / Ordered outbound queue	文字、卡片、图片和文件按群有序发送；上传和投递记录持久化 / Send text, cards, images, and files in group order; persist upload and delivery records
重试与人工核对 / Retry and review	限流或明确可重试失败退避；超出去重保护的未知结果等待人工确认 / Back off on retryable failures; require review for uncertain sends beyond deduplication protection
配置与凭据 / Settings and credentials	共享设置存于本机受限文件；App Secret 保留在 SecretStorage 并仅在连接期间供后台使用 / Shared settings use restricted local files; the secret stays in SecretStorage and reaches the process only while connected
可选用户授权 / Optional user authorization	本机浏览器 OAuth、身份校验、加密凭据、自动续期及代发回流去重 / Local-browser OAuth, identity checks, encrypted credentials, renewal, and echo deduplication
诊断与恢复 / Diagnostics and recovery	报告连接层级、投递异常和窗口状态；重启后从持久状态恢复可确认的工作 / Report connection layers, delivery issues, and window state; resume confirmable work from persistent state

本机状态位于 ~/Library/Application Support/CodexRemote/。它包含群映射、聊天正文、同步位置和投递记录，因此卸载插件不等于删除飞书群或本机历史；请按自己的设备备份和访问控制要求管理此目录。App Secret 不写入这些状态文件。

Local state lives under ~/Library/Application Support/CodexRemote/. It contains group mappings, message content, sync positions, and delivery records. Uninstalling the extension does not delete Feishu groups or this local history; manage the directory according to your device's backup and access policy. App Secret is not written to those state files.

可选：以本人身份发送 / Optional: send as yourself

默认由机器人发送同步消息。若要让历史中的用户消息显示为本人，先在飞书应用中开通表格所列用户身份权限，在 Remote 面板复制本机回调地址并加入应用的重定向 URL，然后点击授权。授权使用本机浏览器；助手回复仍由机器人发送，既有消息不会改写。

By default, the bot sends synced messages. To show historical user messages under your own identity, grant the optional user scopes above, copy the local callback URL from Remote into the app's redirect URL list, and authorize in your local browser. Assistant replies still come from the bot, and existing messages are not rewritten.

授权按应用和操作者隔离，可在面板关闭代发或清除本机授权。清除凭据后，已安排但尚未发送的本人身份消息会等待重新授权，不会自动改成机器人身份。此功能不需要公网 OAuth 回调服务。

Authorization is isolated by app and operator. You can turn off user sends or clear local authorization in the panel. Already planned user-identity messages wait for renewed authorization if credentials are cleared; they are not silently switched to bot identity. This feature does not require a public OAuth callback service.

投递、隐私与限制 / Delivery, privacy, and limits

群内历史按原记录顺序发送；飞书消息的系统发送时间仍是同步时刻，正文中的时间才是 Codex 原记录时间。首次建群在选定历史投递完成后邀请本人入群。同步途中断线会保留进度，/sync 可补齐新记录；已发送的旧消息不会原地重排。

History is sent in source order. Feishu's system timestamp remains the time of delivery; timestamps in the content reflect the original Codex records. Initial group creation invites the operator after selected history is delivered. Interrupted sync retains progress, and /sync catches up new records; previously sent messages are not reordered in place.

消息、图片和文件会离开本机并进入你配置的飞书租户。只有已绑定的本人能操作机器人；本地文件自动发送按类别开关控制，/files 只列该会话历史中可见的本地引用。请在同步包含敏感内容的会话前检查飞书应用可用范围、群成员和文件策略。

Messages, images, and files leave your Mac for the configured Feishu tenant. Only the bound operator can control the bot. Automatic local-file sends obey category switches, and /files lists only local references visible in that session's history. Check the app's availability scope, group membership, and file policy before syncing sensitive sessions.

图片输入支持 PNG、JPEG、WebP 和 GIF，单张最多 10 MiB、一条最多 10 张且合计最多 30 MiB；一般文件附件最多 20 MiB。图片回复需要本机可用的 Chrome、Edge 或 Chromium。审批与用户问题可远程处理；未支持的交互需回 VS Code 完成。

Image input supports PNG, JPEG, WebP, and GIF, up to 10 MiB per image, ten images and 30 MiB per message. Ordinary file attachments are limited to 20 MiB. Image replies need local Chrome, Edge, or Chromium. Supported approvals and user questions can be handled remotely; other interactions must be completed in VS Code.

Remote 不是逐 token 流式转发器：它按 Codex 已落盘的可见消息同步，网络、图片渲染、飞书限流和前方积压都可能增加等待时间。面板区分 Bridge、本机后台和飞书长连接状态；对于明确失败的投递可修复后重试，结果未知的投递必须先在飞书核对。

Remote does not stream tokens. It syncs visible Codex messages after they are written locally, so network delays, image rendering, Feishu rate limits, and earlier queued sends can add latency. The panel separates Bridge, local-process, and Feishu connection status. You can retry definitely failed sends after fixing the cause; uncertain sends require checking Feishu first.

选择“立即调整方向”或“发送到 Codex 排队”后，Remote 会立即发起本群的提交提示，同时提交给 Codex。成功或失败回执按顺序跟随提示；这些回执不等待历史宽图渲染。输入已经有结果后，过时的“正在提交”不会在重连时补发。明确的输入界面未就绪错误表示消息没有提交，仍可从原卡片选择排队或取消。

Choosing Steer now or Queue in Codex immediately starts a submission notice in the same group and submits the input to Codex. Success or failure follows that notice in order, independently of historical image rendering. Obsolete submission notices are not replayed after reconnecting. A definite renderer-not-ready refusal means no input was submitted; the original card can still queue or cancel it.

源码构建与安装包 / Building and installation packages

在仓库根目录安装依赖后，执行 npm run package。脚本会自动编译，并按当前插件名称和版本生成 release/codex-remote-<version>.vsix。所有历史安装包都保留在 release/ 并由 Git 管理；发布修改时先升级版本号，脚本会拒绝覆盖已有版本。release/ 不会被嵌套打包进插件。

After installing dependencies in the repository root, run npm run package. The script builds the extension and writes release/codex-remote-<version>.vsix using the current package version. Historical installers remain in release/ under Git management. Bump the version before packaging changes; the script refuses to overwrite an existing installer. The release directory is excluded from the extension package.

npm ci
npm run package

许可证 / License

MIT。Codex Remote 与 Codex IO Bridge 是配合使用的独立 VS Code 扩展；飞书与 Codex 的账号、应用权限及服务条款仍分别由对应平台管理。

MIT. Codex Remote and Codex IO Bridge are separate VS Code extensions designed to work together. Feishu and Codex accounts, app permissions, and service terms remain governed by their respective platforms.

历史图片整理 / History image maintenance

在 Remote 的 会话管理 → 已同步到飞书的会话 中，选择一条会话的“一键减脂…”或“极致瘦身…”。先生成副本预览，核对当前会话的全部内嵌图片占用、整个文件体积、预计处理后大小、图片数量、父会话与共享历史的关联会话，再确认安排任务。此操作整理本机 Codex 历史，不修改已发送到飞书的消息，也不删除工作目录中的图片文件。

In Remote, open Session management → Managed conversations and choose image compression or image removal for a conversation. Inspect the current embedded-image footprint, total file size, estimated result, image counts, ancestors, and conversations sharing history before confirming. This maintains local Codex history; it does not change existing Feishu messages or delete images from your workspace.

飞书机器人私聊的 控制菜单 → 会话管理 直接提供“一键减脂”“极致瘦身”和“图片整理任务”。先分页选择已同步会话，再生成占用预览并确认；任务卡可以查看处理前后尺寸、取消等待或恢复未完成的整理。对应会话群的“此会话维护”也保留这些操作。

The Feishu direct-chat Control menu → Sessions provides image compression, image removal and maintenance jobs directly. Select a managed conversation, inspect the footprint preview, and confirm. Job cards show before/after sizes, cancellation and recovery. The linked group's maintenance menu provides the same operations.

操作 / Action	效果 / Effect
一键减脂 / Compress	按原图大小自适应压缩旧内嵌图片，以设置的 Base64 体积为上限；不会因清晰度下降而保留大图。Compress old embedded images to the configured encoded-size budget, without a visual-quality veto.
极致瘦身 / Remove	移除计划处理范围内的全部内嵌图片数据，包括最新一轮；保留消息结构、文字及原有轮次。Remove every embedded image in the selected maintenance scope, including the latest round, while preserving records, text, and turn identity.

只有“一键减脂”保护各处理会话最新一轮的图片，包括父历史中被分支继承为最新一轮的部分；无法证明最新轮次边界的部分会明确报告并保留。“极致瘦身”则移除选中会话及本次计划列出的父级祖先历史中的全部内嵌图片，包括最新一轮。祖先处理范围以实际预览为准；其他仅需更新位置引用的共享分支保留其独立文件中的图片，删除预览中的“非处理范围保留”指这些图片。

Compression alone preserves each processed conversation's latest-round images, including inherited ancestor prefixes. It reports and preserves ranges whose latest-round boundary cannot be proven. Removal deletes every embedded image in the selected conversation and the ancestors listed in the actual plan, including their latest rounds. Other shared branches that only need reference updates retain the images in their own files; the removal preview reports those as retained outside the processing scope.

既有极致瘦身任务保留其原有规则和范围。采用旧保护规则的任务，最新一轮仍会保留，界面会标明“旧规则计划”；若要连最新一轮一起删除，请先取消等待中的旧任务，再重新预览和确认。

Existing removal jobs keep their captured rule and scope. Jobs using the old preservation policy retain latest-round images and are labeled as legacy plans. To remove those images too, cancel a waiting legacy job and prepare a new plan before confirming again.

全局配置 → 历史图片减脂 默认范围为 4～64 KiB，可设置为 1～128 KiB 内的整数范围。这里计算的是 Base64 在会话文件中的占用，不是解码后图片的字节数。已经足够小的图片保持原样；不支持的格式、解码失败等会在结果中说明。设置只用于新生成的预览，已生成的计划保持当时的设置。

The global image-maintenance settings default to 4–64 KiB, configurable within 1–128 KiB. The budget counts encoded Base64 in the history file, not decoded image bytes. Already-small images stay unchanged, and unsupported formats or decoding failures are reported. Settings apply to newly prepared plans; existing plans retain their captured settings.

执行与恢复 / Execution and recovery

新预览默认采用在线整理。确认前，预览列出的目标会话、父级来源和共享关联会话必须没有运行中、等待回答、等待授权或原生排队消息，也不能正在同步或发送历史内容。整理不会中断这些任务、删除已有队列或重新投递消息；请先正常结束相关操作。确认后，只暂停所列会话的 Remote 同步及新输入，其他会话继续使用。发往受影响会话的新输入会明确提示“未提交”，不会放进隐藏队列。

New previews default to online maintenance. Before scheduling, the listed target, ancestors, and shared dependent conversations must have no running work, pending answers or approvals, native queued messages, or in-flight synchronization. Maintenance never interrupts that work, deletes queued messages, or resubmits them; let the related operations finish normally first. Confirmation pauses synchronization and new input only for the listed conversations. Other conversations remain usable. Inputs to protected conversations receive an explicit not-submitted response rather than entering a hidden queue.

在线整理会为所列会话建立持久化保护，阻止相关窗口重新加载或写入这些会话，再卸载原生会话并取得真实的存储独占锁。通常原生卸载可能需要约 1 分钟，大文件的整理还需要额外时间；无需退出全部 Codex 窗口或进程。执行前会再次核对原生程序、关联范围、文件和图片内容；出现未经确认的新消息或范围变化时停止修改，需重新预览。不能验证在线保护能力的旧 Bridge 会明确拒绝本次整理，需要先启用新版，不会静默改成离线执行。

Online maintenance creates durable protection for the listed conversations, blocks their reloads and writes through participating windows, unloads their native state, and obtains real storage writer locks. Native unloading may take about a minute, with extra time for large files. There is no requirement to quit every Codex window or process. Before changing files, the worker rechecks the executable, dependency scope, files, and image content. Unconfirmed new messages or scope changes stop the operation and require a new preview. Older Bridge versions without verified online protection explicitly refuse maintenance until updated; they do not silently fall back to offline execution.

会话管理 → 历史图片整理任务 显示“等待会话独占权”、提交、文件完成或恢复状态。等待独占权阶段可以取消。如果意外断电或进程中断留下未完成提交，使用“恢复到处理前”，不要手动删除存储保护标记。即使 Codex 暂时无法启动，仍可从 VS Code 命令面板执行 Codex IO: 恢复中断的历史图片整理。

The maintenance job list shows waiting for exclusive access, committing, files completed, or recovery states. Jobs waiting for exclusive access can be cancelled. If shutdown interrupts a commit, use rollback to restore the pre-maintenance state; do not manually delete storage guards. When Codex cannot start, the VS Code command Codex IO: 恢复中断的历史图片整理 provides recovery independently of native readiness.

任务列表区分待完成任务和已结束记录。文件修改完成但同步记录尚未核对时，仍显示暂停原因和重试入口；全部收尾后显示“整理与同步恢复已完成”。最近 30 条已结束记录默认折叠保留，用来查看处理结果，不表示仍在运行，也不会重复整理。

The list separates unfinished jobs from ended records. When file changes are complete but synchronization has not been reconciled, the pause reason and retry control remain visible. Fully settled jobs report that maintenance and synchronization recovery are complete. The latest 30 ended records are kept collapsed for reviewing results; retaining them does not mean a job is still running or will be repeated.

同一个 Codex 数据目录中，如果还有未接入保护的 CLI、Desktop 或未知原生进程，界面会给出具体 PID 并要求关闭该外部进程后重试。这不是要求关闭所有 Codex；其他数据目录和已接入保护的无关会话可以继续使用。不要在整理期间启动未接入保护的新客户端。

If a CLI, Desktop, or unknown native process also uses the same Codex data directory without participating in protection, the error identifies its PID and asks you to close that external process before retrying. This does not require quitting all Codex instances; other data directories and unrelated conversations behind the guard remain usable. Do not start an unguarded client during maintenance.

升级前生成的计划和任务保留原执行方式：executionMode 未记录或为 offline 的任务仍等待所有本机 Codex 正常退出，其恢复也遵循原离线要求。界面会明确标为“旧离线任务”；如果任务还在等待，取消后重新预览并确认即可使用在线整理。不要把正在提交或需要恢复的旧任务当作新任务重做。

Plans and jobs prepared before online support keep their captured execution mode. An absent or offline executionMode still waits for all local Codex processes to exit, and recovery follows its original offline requirements. The UI marks these as legacy offline jobs. Cancel a still-waiting job and prepare a new confirmed plan to use online maintenance. Never resubmit an already-committing or recovery-required legacy job as a new operation.

历史文件和 Codex 的本地历史缓存一起更新；Remote 随后迁移各机器人账号的同步游标。只有这些迁移成功后才恢复同步，避免把旧消息重新发到飞书。已成功完成的整理不会永久保留原始大图备份；需要原图时，请在操作前自行备份。

History files and Codex's local history cache are updated together. Remote then rebases synchronization references for every local bot account. Synchronization resumes only after reconciliation, preventing historical messages from being sent again. Completed operations do not retain permanent copies of the original large images; make your own backup beforehand if you need them.

本功能当前面向 macOS 上的 VS Code 官方 Codex，使用系统图片与存储工具。它会检查实际 Codex 程序的维护屏障能力和历史缓存格式；无法验证时拒绝整理，原有消息同步不受影响。不会启动模型回合、调用图片生成服务，也不会自动上传待处理图片。

This feature currently targets official Codex in VS Code on macOS using system image and storage tools. It verifies the actual executable's maintenance barrier and history-cache format, refusing maintenance when these cannot be established while leaving normal synchronization available. It does not start model turns, call image-generation services, or upload images being maintained.

任务完成后，列表显示实际图片数据占用及文件大小的前后对比。图片统计包含本计划保留或未处理的图片；对压缩存储文件，图片占用按展开后的记录计算，文件体积按磁盘中的实际压缩文件计算。

Completed jobs show before/after image-data totals and file sizes, including any images retained or left unprocessed by the plan. For compressed storage, image totals refer to decoded records, while file sizes refer to the actual compressed files on disk.

Codex Remote · 飞书

koupualen