Codex Harness Desktop

独立桌面工作台，把 OpenAI Codex 引擎装进一个真正的桌面应用：多会话任务管理、可视化 diff 审阅、内置自动化工具、插件/技能/连接器生态、专家团队协作，开箱即用，无需命令行。

🎯 核心能力速览

还有：专家团并行调度（多位专家同时干活，头像轨看进度）· 审批卡贴输入框一行不占屏 · 会话切换命中缓存直渲（实测 P50 20ms，切回还原窗口与阅读位置）· 大 diff 行级虚拟化（几千行不卡）· 多会话并发按会话裁剪事件· 三层记忆自动沉淀 · 微信/Telegram/飞书/钉钉/QQ Bot 远程接入 + 企微群机器人推送 · 可视化 diff 审阅与撤销 · xterm 内置终端 · 会话备份导出与归档 · 专家团队协作 · 应用内自更新 · 浅色/深色主题。

✨ 功能特性

🚀 任务与会话管理

• 隐私与安全（09-19 二轮加固）：文件预览/保存（fs:read/fs:write）、「在文件夹中显示」（shell:reveal）一律收敛到可信根（各会话工作目录 + 应用数据目录 + 你亲自用系统对话框选过的路径），渲染层再被注入也读不到、写不了全盘文件；「显示安装包」只认刚下载并通过 sha256 校验的那一个文件；本地页面带 CSP（封死注入脚本加载外部代码 + object/base/form 劫持）；API Key、机器人密钥、账号密码全程 safeStorage 加密落盘；更新链路强制 https + sha256 校验；本地服务只绑 127.0.0.1；无遥测、无隐蔽持久化（09-19 全库审计结论）
• 改项目地址是真改（09-19 修复）：在已有会话上切换项目地址，「只显示改了」这件事不存在了——顶栏显示、侧栏项目分组（会话立刻搬到新项目下、新项目自动出现并展开）、引擎运行时目录三处一起变，并且刷新列表/重启应用后依然是新地址（原先只发引擎设置，侧栏是按会话记录里的地址分组的、引擎回包的又是创建时那个 ⇒ 改完侧栏纹丝不动，看着就是假的）。另外启动后会自动展开当前会话所在的项目，不用再手动点开。
• 会话绝对独立（09-19 加固）：每个会话的运行状态互不影响——切到别的会话、回来、开关独立窗口、甚至另一处改了配置，都不会让正在跑的任务停下。三层保证：① 运行状态只由回合级权威事件（开始/完成/中断）点亮与熄灭，引擎回包与本地缓存这类"快照"不能把在跑的会话判成已停；② 引擎报 idle 这类快照式状态时，要先与主进程的引擎侧记账核对才允许熄灭；③ 主进程最后一道硬闸：该会话在引擎侧仍有活动回合时，拒绝任何新回合启动（避免打断），提示改走排队或并入当前回合。唯一的例外是你自己点停止（或语音插话）。
• 长思考不被截断（09-19 修复）：思考/输出绝不受应用限制——真正的问题在供应商单次输出上限（商汤曾把单次响应钳到 8192 tokens，模型思考 16KB 把预算吃光 ⇒ 正文一个字没出，引擎还当"正常完成"）。现在：① 检测这种「思考很长 + 正文为空（或只是思考的复述）+ 无任何动作」的被截断空转（引擎截断时会把思考摘要复制成正文，所以"正文非空"≠"有产出"）；② 检测到就明确提示是供应商截断、并自动从断点续接——发一条"接着上次没写完的继续"（新回合带全新输出预算，不重想、不重复），最多自动续 2 次防死循环，且正常收尾绝不会被误判触发（正常回复哪怕只回一句结论也不动它）。换到输出上限更高的供应商（如豆包）后此场景已不复现。
• 语气自适应（09-19 新增）：agent 有了会话级状态——心情 / 精力 / 默契三个值，随回合结果变化（顺利收尾、连续失败、被你夸、被你催各有权重），再映射成一句语气指引随会话自己的指令下发：失败多了会收紧（少客套、先给结论）、状态好时更轻快、精力见底转极简、半小时不用慢慢回到基线。每个会话各自一份、互不影响——A 会话的低落绝不会改到 B 会话的语气上（状态按 agent-mood-<会话 id> 各自存放，注入走会话自己的 developer_instructions）。它只影响说法、不影响内容（事实 / 结论 / 代码 / 风险提示一律照常，并禁止 agent 谈论自己的状态），发送前会按最新状态刷新一次，保证「这一次回复」用的就是当下语气。设置 → 个性化 可随时关闭。
• 输入框草稿不丢（09-19）：每个会话的输入内容独立保存——切会话、新建会话、关掉应用再打开，打到一半的字都还在（发送成功才清空该会话的草稿）
• 会话通知带会话名（09-19）：后台会话产生的通知弹窗前置「【会话名】」，在别的会话也一眼知道是哪个会话的
• 工具下载源可选（09-20）：设置 → 开发工具顶部可选下载源（自动/国内镜像/gh-proxy/ghfast/官方直连/本机代理），下载慢就换源，下一次下载立即生效，失败自动回落官方源
• 多会话/多窗口并行不掉内容（09-20）：同时跑多个会话（含独立会话窗口）时，正在看的那个会话的流式内容照常实时出字——修掉了「另一个窗口的上报过期，导致本会话事件被误裁、只转圈不出内容」
• 输入框下方一行提示（09-20）：居中显示「内容由AI生成，请核实重要信息」，位置随输入框那一列（右侧面板开合时不会偏）
• 改会话名字现在一定生效（09-20）：修掉「导入的会话改名后仍显示导入…」。根因有两层——引擎会把名字重写成它按第一条消息自动生成的那个，而应用又恰好在同一刻用引擎那份整表刷新把改名抹掉。现在用户改过的名字由本地持有并优先显示，重启、刷新、打开会话都不会弹回去
• 能读文档附件（09-21）：把 PDF / Word / Excel / PowerPoint 拖进对话，模型读到的是转成 Markdown 的正文（markitdown，MIT 许可），不再只拿到一个文件路径；它默认不装，需要时点一次就装（「设置 → 开发工具 → 文档转换（markitdown）」，约 120 MB，走清华 pip 镜像），也可以让 Codex 自己装。转换全程在本机完成，不上传
• 内置写作技能（09-21）：humanizer / no-ai-slop（去 AI 味、改稿）、i-have-adhd（先给下一步动作、编号、限长；仅在你显式调用时生效，不会自作主张改你的输出风格）——三个 MIT 许可技能随应用装好，可在「设置 → 技能」单独停用；来源与许可见 THIRD_PARTY_NOTICES.md
• 生成的图片不再灌爆对话（09-21）：修掉一个"看不见但很贵"的问题 —— 生图网关通常不返回图片网址、只给 base64，而应用原来把它当图片地址回填进了工具返回，于是单条工具输出变成 3 MB 的文本，还留在对话历史里被每一轮重发（长会话越滚越贵）。现在生成的图一律先落盘（应用数据目录下的 images/），工具只拿到本地路径：要展示给你看就引用这个路径，模型需要看图内容时再用 view_image 读它
• 能查到"现在走哪条"（09-21）：设置 → 开发工具顶部新增「当前能力链路」—— 浏览器自动化、桌面控制、看图、生图、文档附件、多智能体调度各自现在实际走哪个后端、为什么是它、备选为什么没走（含「总闸关着」「视觉配置还没下发给 nuphus」「Intel Mac 没有本地 OCR」这类原因）；装/卸工具后自动刷新
• 计划能改（09-21）：Codex 给出的执行计划现在是可编辑的——每条可以勾选完成、改文字、删掉、再加一条；改完点「交给 Codex」就把它作为一条消息发回去，让它按你改后的计划做（不再是只能看的只读列表）
• 自带一个「评审」子智能体（09-21）：它用干净上下文复审——看不到你和 Codex 之前的对话，只按材料本身挑问题并指出具体位置（"写的人不审自己"）。Codex 交出成果前可派它自查；你也可以在「子智能体」里改它的提示词或停用
• 多任务并行：侧栏按分组/项目管理会话，支持置顶、归档、重命名、分支、批量操作
• 消息排队：任务运行中继续输入，消息自动排队依次发送；排队 ≥2 条时列表顶部出现「排队消息 N」折叠开关（默认展开，手动折叠）；每条左侧拖动手柄可拖动调整发送顺序
• 超长上下文 / 重负载优化：时间线对视口外回合启用 content-visibility: auto，几个 G 的会话历史也能流畅滚动；长会话分页懒加载——打开会话只渲染最近 5 回合（≈5 个用户消息，把懒加载做到极致），网络侧也只取这一页；用户自己往上滚到接近顶部（<720px）才自动续载下一页（5 个用户消息）；消息刻度尺与之同步（新加载的页刻度自动补上，刻度多了会自动压缩变短，滚轮一次滑一页；悬停刻度尺滚轮滑窗带轻量棘轮咔哒音效，到顶/到底静默）；滚回最新（贴底）自动把展开的历史收回来（只收渲染、不动数据），也可点「显示更早」按页补齐；没滚过就不加载（打开会话时的程序化滚动不会误触发）；上方插入更早内容时按锚点元素位移精确补偿滚动位置，视口内容不跳（content-visibility 下 scrollHeight 不可靠，故不用它）；前端少渲染不影响模型上下文——上下文由引擎 rollout / 自动压缩管，分页只是读取；切回会话首屏成本恒定；上下文环在占用 ≥80% 变橙、≥95% 变红预警，≥70% 时弹出「压缩上下文」一键释放空间；设置 → 数据管理 可查看各数据目录占用并清理安全缓存（引擎日志 / 图片缩略图 / 内存会话恢复缓存），会话历史不在清理范围
• 统一内置通道（切供应商零迁移）：新建会话一律绑定统一的内部通道名，它永远指向当前生效供应商 —— 所以换供应商只需重启引擎，新旧会话都直接用，不做任何会话迁移；历史会话（旧版本创建的、绑着老供应商名）由「别名段 + 后台静默对齐」兜底，打开即用且不打扰。「要不要迁移」一律走统一判定（绑定统一通道名 = 天然对齐，永不触发迁移）——判定写歪会出现「选完模型一发消息就弹回旧模型」和「每次发送都重启引擎」两个连锁故障（09-15 已修，离线预检有守卫断言盯着）。
• 切换供应商不断档（会话自动接力（成功后旧会话自动删除，只保留新的））：换了供应商后旧会话打开即用——打开会话的瞬间自动把它对齐到当前供应商（原地重绑定，会话 ID、聊天记录、侧栏位置全不变），引擎自发的上下文压缩/重连不会再撞 401；该会话原模型若不在新供应商里，自动落到当前激活模型。原地重绑定失败（极老会话）时自动 fork 出一个带完整历史的新会话，并把旧会话自动归档，侧栏不留两坨。全程提示「已自动接力，历史上下文与聊天记录完整保留」
• 会话备份与导出：本地 Markdown 导出、跨设备恢复
• 移动远程接入：手机扫码远程连接工作台；机器人频道消息驱动任务——微信（手机扫码登录，真实 iLink 网关）、Telegram（@BotFather Bot Token）、飞书（开放平台 App ID/Secret + 官方长连接，免公网 IP，群里 @机器人 对话）、钉钉（开放平台 Client ID/Secret + 官方 Stream 模式，免公网 IP）、QQ 机器人（支持官方扫码连接：桌面出二维码 → 手机 QQ 扫码确认 → 凭据自动回传，无需手敲；也可手动填 AppID/Secret + 官方 WebSocket 网关）；企业微信群机器人为推送型通道（Webhook，推送任务结果/通知到群，腾讯限制不支持收消息对话）。每个渠道都是真实网关，凭据持久化、重启自动恢复，消息统一走 Codex 会话管线并支持会话绑定

🎨 沉浸式对话体验

• 全宽顶行 + 独立面板（两段式布局）：窗口第一行是横跨全宽的独立顶行——左侧任务名，右侧工作区选择/任务操作（⋯：压缩上下文/审查/撤销/消息队列等）/新建终端/右栏开关四钮紧贴系统原生窗口钮（titleBarOverlay），位置恒定；顶行以下才是侧栏/聊天/右栏三列，拖面板分隔条只影响面板，顶行不动；面板与顶行完全拆开（板块独立），聊天区随面板开合自适应；分隔条为 1px 细线（前后 3px 加宽热区），拖拽直写 DOM 样式流畅无卡顿；底部分隔线止于窗口钮左侧（原生 overlay 区域无法绘制）
• 内置浏览器（右侧面板）：右侧面板「浏览器」标签即极简浏览器（多标签页 + 地址栏 + 收藏 + 空状态引导页），聊天主区不受影响，可边对话边浏览；渲染走 Electron 独立 webContents（与宿主隔离）；盾牌按钮「隐身浏览」调 cloak-browsers 指纹内核以独立窗口打开当前页（需在开发工具安装自动化包并下载内核），失败时提示原因；右侧面板四个标签（变更/终端/浏览器/项目树）常驻直达，右栏开关独立于标签（任意标签下均可一键收起/展开，Ctrl+B 同效）
• 流式平滑渲染：正文/深度思考逐字平滑揭示，无跳字闪烁；流式光标内联跟在末行文字后（不占独立行）——正文与下方运行状态行之间无多余留白
• 长会话分页兜底（最新优先）：引擎弃用长线程全量加载后，切会话 resume 拿不到回合时自动用 thread/turns/list 分页拉齐（修复「切会话回答消失」）。分页策略从"从最老一页页爬"改为从最新往回取：小会话第一页到头即全量；大会话最多取最近 3 页（600 回合）立即渲染——切会话从"十几秒"降到秒级，最新消息优先到达
• 代码高亮：不重复算、也不提前算（09-18）：切换会话时消息区整体卸载再挂载，原先每段代码都要重新高亮一遍——真机 CPU profile 实证那个递归建元素的函数单次自耗 2.2 秒，且切换耗时几乎正比于目标会话的 DOM 规模（相关性 r=0.974）：六千元素的会话约 0.7 秒、两万三千元素的会话要 3.6 秒。两层修法：① 结果缓存（同语言+同代码+同主题+同行号/换行设置 → 复用上次算好的元素树），再次切回同一会话从 1.9 秒降到 0.15 秒（12.5×）；② 懒高亮——没点开看、没滚到跟前的大代码块（≥1500 字符）不预先高亮，进视口邻近区（预载 1200px）或展开折叠组时才现算（小块直接高亮，行为不变）。外观逐像素一致（复用的一定是同一次计算的结果），未高亮时的兜底文本用与高亮相同的主题底色与字体，不会闪白。逐字流式期间不写缓存也不懒加载（中间态只会挤掉别的会话的缓存、还跟追字动画打架）
• 回复等待可见化：回合进行中超过 90 秒没有任何流式事件（上游模型卡住/断流），时间线内提示「回复等待中，正在与引擎校对」而不是干等；校对确认任务已在上游完成时自动同步状态并提示；限流类错误继续走自动重试（指数退避，最多 5 次）。「正文给完了但回合没结束」单独说明（09-18）：GPT 系模型输出完正文后，上游可能迟迟不发流结束信号（真机实测 gpt-5.6-sol 正文落盘后 28 秒零事件才收尾，引擎只能等），此时界面如实写「正文已完整，等待模型收尾」，不再说「正在生成回复」让人以为还在憋正文。这句话只在底部状态行说一次 —— 计时条只管报「正在处理 N 秒」，两处各说一遍等于同屏重复（用户实测反馈后收口）。计时跨会话延续（09-18 修复）：原先计时起点存在组件内部的 ref 里，而切换会话会把消息区整体卸载再挂载 ⇒ 「切出去看一眼、切回来」时间从 0 重数（真机实测：切走前 2 秒、切走 8 秒、旧实现切回显示 0 秒）。现在起点按回合 id 记忆在一个跨挂载存活、有容量上限的表里，切走期间流逝的时间被正确计入（同一场景实测切回为 11 秒）
• 引擎提示中文化：弹卡里的引擎英文提示（项目级配置被忽略/限流/断流重连等）按已知模式翻译成中文，未收录文案原样展示
• GPU 渲染可调：默认硬件加速交给 Chromium 自动管理（健康显卡默认启用）。曾试过强制 GPU 通道的四开关，健康显卡实测点击延迟变高已回退；但低配机/弱核显默认软件渲染会卡——设置 → 通用 → 显示与性能提供「硬件加速」三档（自动 / 强制开启 / 关闭），重启生效，低配机卡顿时可选强制开启。启动时输出 GPU 功能状态日志可诊断
• 设置页按需加载（软件渲染机器专项优化）：无 GPU 加速（gpu_compositing: disabled_software）的机器上界面全靠 CPU 绘制，重内容同步挂载会「点了没反应」。三层优化：①点击市场入口骨架先行（弹窗框架秒现，分区内容延后一帧挂载）；②MCP 重查询懒加载——mcpServerStatus/list {detail:"toolsAndAuthOnly"} 会逐个拉起 MCP 服务枚举工具，只在真正进入 MCP 管理页时才请求；③市场数据进页才拉——SkillHub/插件市场网络请求不再应用启动就全量打（原先是全局 effect 挂载即请求），只在对应市场页可见时请求，搜索输入 350ms 防抖；长页分区 content-visibility: auto 视口外跳过布局绘制
• 自动跟随与发送定位：发送后新消息固定落在对话区顶部往下一行半处（36px；不是悬浮钉顶，而是尾部留白把它顶到这个固定落点，agent 回复从它下方长出来，所以永不遮挡内容），配合上浮光斑出场动画（0.55s 上浮淡入 + 光斑扫过）；排队消息同样落在落点上（09-19 修复）——任务正在跑时你发的消息会先进队列，等它真正开始执行时也按同一落点定位（原先这条路径不建立定位意图，消息会散在正文流里）；落点永远滚得到（09-19 修复）——回复变长时尾部留白会随之收缩，若收缩过头会让落点跑到"滚不到的地方"（视口被内容下限钳住、消息停在半屏），现在收缩后会校验可达性、不够就把留白补回来；Agent 流式回复期间自动滚动跟随，正在吐的字实时可见；深度思考卡内部同样自动跟随（思考正文流式增长时贴底滚动，用户滚轮/触摸/拖滚动条接管即停，滚回底部或新思考开始自动恢复）；用户向上滚动（滚轮/拖滚动条/翻页键）立即停止跟随，滚回底部后自动恢复
• 停止任务后过程与内容都保留（09-18）：点「停止」后运行过程默认展开（原先会折叠成一行，用户看不到刚才做到哪一步、也没法顺着继续交代），内容一字不丢；并在最新内容之后给出明确的「用户已停止」标记（写明运行过程与内容都已保留、接着发消息即可继续）。用户自己点的停止不再重复弹顶部那条通用中断提示 —— 那条列举「点了停止 / 语音插话 / 手机端停止」三种可能，自己按的却要读一段猜，而且与末尾标记重复说同一件事；非用户触发的中断（语音插话 / 手机端 / 引擎主动中止）仍照旧给出原因与处置建议
• 会话折叠：工具调用、计划步骤自动折叠成卡片；深度思考块输出完即自动折叠，正文衔接不悬挂，长任务一眼看清结构
• 提示词增强：输入框一键 AI 润色提示词（悬停预览、一键还原）
• 引用体系：@ 引用上下文、# 引用技能（与 / 命令面板同款：输入 # 弹出技能面板，等宽技能名 + 一句中文注释，回车或点击即引用；未匹配时按普通文本发送；输入框占位符常驻提示「# 引用技能」，不再额外占位提示条）；引用会话/文件、图片内联粘贴；图片一律按图片正常发送（09-18 收口）——不再按「模型声明支不支持图片」预判把图吞掉换成文字（预判会误伤「其实支持视觉、只是漏勾了图片」的模型；被塞进消息正文的那段说明文字还会让模型照抄出来、在气泡里对用户讲道理）。真遇到接入点不支持图片时，引擎会明确报错，届时自动摘掉该模型的图片模态并说明——且只在这时：一旦有会话正在跑，这个自动修正会跳过并提示（改配置要重启引擎，会打断所有正在跑的回合，绝不能让一个后台便利动作杀掉你的任务；手动到「设置 → 模型」改即可）；输入框直接粘贴文件（系统复制的 PDF/代码/文档等 Ctrl+V 即作为附件，多选批量粘贴，发送时以附件清单带上）；文件与图片在输入框里是同一款内联 chip（09-18 用户：「把文件展示不要在输入框上面了，改成在输入框里面的 chip，跟图片一样的展示」——原先输入框上方那条附件条已删除，文件 chip 与图片 chip 同高同圆角，点主体打开文件/预览、点 × 移除）；粘贴超 200 字的纯文本自动转 .txt（09-18 用户：「复制的内容超过 200 字的时候把文本直接显示成一个 .txt 文件的方式」——内容按哈希落盘到应用数据目录（同一段文本粘两次得到同一个文件），输入框里只留一个文件 chip，不再把长文本铺满输入框）；.txt chip 点击开大窗口预览并可编辑（09-18 用户：「要支持打开大窗口预览，而且要可以编辑，方便我修改」——行数/字数实时显示，保存写回原文件、关窗自动保存，Esc 关闭走应用的统一快捷键管线；只有应用自己保存的粘贴文本可编辑，你自己的同名 .txt 不会被误改）；输入框高度随内容自适应（有下限 48px、上限约 42vh/360px，到上限后框内滚动，不会把上方正文顶出视野）；你发出的图片与文件内联在正文文字流里（09-18 用户三次纠正后的定稿：「文件和图片会在用户名字上面」→「都靠右，自适应排序啊，靠左多丑」→「谁让你单独一行靠右了，我要的是像输入框那样，内联在里面」）。最终形态与输入框里粘贴时逐字一致：chip 直接跟在正文文字之后，同一行内排布、装不下自动换行，发送前看到的样子 == 发送后显示的样子（图片与文件共用同一款「图标 + 文件名」chip，composer-image-chip-inline）；图片查看灯箱：点击消息/附件图片放大（滚轮缩放/拖拽平移），工具栏支持复制图片（本地图片经主进程写入剪贴板，网络图直取）与打开所在位置（本地图在文件管理器定位、网络图用浏览器打开）；悬停小预览（09-18）：鼠标移到消息里的图片 chip 上，立即在它上方弹出自适应小预览（横图竖图都按原始宽高比缩到框内、不变形，不占布局）；靠近聊天区顶部时自动翻到下方弹出，不会被滚动容器切掉；附件名含方括号不再漏出协议文本（09-18 修复）：附件段的结束标记原先允许「行中任意 [方括号]」就截断，于是文件名里带方括号（如 22 钛光金 [最终版].png）会把段切断，残留的 .png 与 [附件结束] 被当成用户正文显示在气泡里（用户截图实证）。现在结束标记必须独占一行（附件列表每行都以 - 开头，真正的标记必然整行），并且兼容 CRLF 行尾——已发出的历史消息也会一起恢复正常，因为泄漏发生在解析环节而不是存储环节
• 项目树与文件预览：右侧「项目树」标签浏览工程文件，点开即预览——顶部多文件标签切换（内容缓存秒切）、行号常开、语法高亮/主题/字号跟随代码显示设置，图片棋盘格底预览，PDF 内嵌查看，二进制文件（Excel/Word/压缩包等）给占位说明而非乱码，中文 GBK 编码文本自动识别，支持直接编辑保存；HTML 文件一键「浏览器打开」——右侧内置浏览器新开标签渲染该页面（file:// 直载，改完可反复打开看效果），亦可「放大预览」独立大窗口（可自由调整大小）；内置浏览器菜单支持「放大查看（新窗口）」「在系统浏览器打开」（本地 HTML 亦可用系统默认浏览器打开）

📱 移动端远程控制

• 手机扫码即控：侧栏底部「手机」图标打开「移动端远程控制」面板，手机扫码（或复制链接）即可在手机上查看会话、收发消息，回复实时同步；优先走 Cloudflare 免费隧道（https，跨网直连），不可用时回退局域网地址
• 首次连接要过两道关（09-13 加固）：① 6 位配对码——电脑端面板大字显示（5 分钟有效、错 10 次自动作废、可一键刷新），手机扫码后要输入它；② 电脑端审批——配对码正确后手机进入「等待批准」，电脑端弹出审批卡（显示设备名），点「允许」才真正接入，点「拒绝」手机端立即看到拒绝
• 已批准设备免重复配对：批准过的设备记住身份（持久化在 userData），再次连接直接进入；面板里可随时「移除」撤销，下次重走配对
• 凭据不落链接：二维码与配对链接不夹带任何凭据（能力式 URL 会随链接、截图、浏览器历史、隧道日志外泄）；凭据只在配对通过后以 HttpOnly cookie 下发；控制面所有路由（含 WebSocket）统一鉴权，未配对访问一律 401 / 落到配对页；不再自动修改系统防火墙策略
• 机器人聊天同样要配对：微信 / QQ / 飞书 / 钉钉 / Telegram 里首次给机器人发消息时，机器人不会直接执行——先在聊天里发送电脑端显示的 6 位授权码（与手机远控同一个码），电脑端点「允许」后该聊天才被记住并正常使用；配对码 5 分钟有效、连错 5 次冷却，已批准的聊天可随时在面板「移除」

🎙️ 本机离线语音通话

• 一键通话悬浮球：右下角常驻悬浮球（可拖动、位置记忆），点一下开始通话；通话中变成状态指示（聆听 / 思考 / 播报），点开面板看实时字幕与麦克风电平，随时「打断」或「挂断」
• 应用内通话界面（来电式）：接通自动弹出的全屏通话界面——深色底、居中大头像（跟着声音呼吸发光）、通话状态大字、实时字幕区、底部大圆钮（打断 / 挂断）；右上角「收起」只收界面不挂断，通话继续在悬浮球上跑；悬浮球右键「打开通话界面」随时再唤起，也可不用界面只留悬浮球
• 全本机推理、零凭据、零联网：语音识别与合成都在本机跑（sherpa-onnx 原生推理），不调用任何云端语音接口，也不需要在设置里配额外的 Key；首次使用按需下载模型（约 270MB，双镜像 + SHA256 校验 + 断点续传）
• 边说边出字 + 开口打断：流式识别实时上屏，停顿自动断句提交；播报期间开口即打断（回声门控 + 自适应地板判定，外放误触发时可切手动打断）
• 旁挂新增，不动原有输入：语音只在你主动点「开始通话」后生效，挂断即彻底退出（不留常驻麦克风监听、不留后台采集）；识别文本走与打字完全相同的提交路径。打字输入、@///# 面板、排队、粘贴、引用全部一行未改
• 语音唤醒（内置关键词模型）：说唤醒词即可唤起，不用点按钮。内置专用 KWS 关键词模型（3.3M 参数，按需下载约 31MB），按读音匹配而不是按识别出的字匹配——这就是为什么以前「小柯小柯」被通用识别模型写成「小咳小壳 / 小哥小哥」就唤不醒；同声母韵母的口音与同音字容错，不同声母（柯 ≠ 哥）不会误唤醒。模型没装时自动回退到通用识别 + 同音容错，不装也能正常通话与听写
• 模型下载：会提速、可取消：多镜像按首字节延迟自动排序（实测 55.7s → 11.2s），探测窗口压到 2 秒（点下去不再"半天没反应"）；中途取消保留已下载的部分，下次点「下载」从断点接着传。下载入口与诊断在 设置 → 语音通话 的唤醒卡片，卡片还会显示「最近听到什么」，方便自查有没有在听
• 听写与实时语音优化：开麦与识别加载的顺序调整（不再丢开头 1~3 秒）、首句出声更早、松手补静音改短；播报打断带世代号（打断后不会继续念被打断前的旧内容）；朗读时跳过代码块/表格/链接/emoji，只念人话，数字与日期会中文化；引擎能区分语音消息与打字消息（语音发的消息带 [语音] 标记，且 turnTrigger=voice）
• 音色：内置精选 + 我的克隆音色：设置 → 语音通话 可选内置音色并试听（试听走常驻合成线程，第二次起秒出；播放中可随时点「停止」）；另带 3 个随包精选克隆音色（音源取自 GitHub 热门开源 TTS 项目的官方示例：CosyVoice 温柔女声「晓晨」、FireRedTTS2 沉稳男声「阿远」、F5-TTS 磁性英文男声「Nature」），点「启用」一键创建；也可导入/录制自己的参考音频做专属音色
• 跨平台：Windows 与 macOS 通用（mac 版含完整适配：原生红绿灯左让位、⌘ 系快捷键、随包原生 darwin 工具链、系统麦克风授权声明、关窗不退出后 Dock 重开仍可用、手机配对的公网隧道随包）；macOS 首次使用会弹系统麦克风授权框，被拒时给出明确提示而不是静默失败

🔌 能力生态

• OpenAI 官方订阅（ChatGPT 登录）：设置 → 模型 页「OpenAI 官方订阅」卡 + 独立管理页（设置 → 账户 → OpenAI 订阅）——设备码登录（引擎原生 codex login --device-auth，自动打开浏览器并显示验证码，无需 API Key、无需本地回调端口），多账号批量管理：每账号独立保存在本机 vault，列表一键切换（写回 auth.json + 引擎重启生效）/删除/重新启用，每账号独立额度监控；启用后引擎走内置 openai 通道 + ChatGPT 订阅额度（配置写入 preferred_auth_method = "chatgpt"）；代理端口自动探测（配置端口连不通自动扫 7897/7890/10808 等常见端口）并透传引擎与官方接口（OpenAI 有区域限制，无代理网络不可用）；模型列表/订阅额度实时同步官方（额度面板：PLUS 档位、订阅有效期、5 小时/本周窗口用量进度条）；管理界面为账号卡片 + 二级弹窗。对话链路走引擎内置 openai 通道 + ChatGPT 登录凭据（不使用任何 API Key）。
• 中转站中心（sub2api 兼容，独立设置页）：设置 → 账户 → 中转站：登录中转站站点（默认 PPtoken，任何 sub2api 网关均可）后展示余额总览与套餐卡片（用量进度条/上限/到期），点「使用此套餐 / 使用余额」一键生成命名好的供应商并切换生效；多账号管理：可添加多个中转站账号，列表一键切换（自动重配该账号的套餐/密钥并同步规格表）或删除；API 密钥管理区自选用哪把 key；启动登录界面也有「中转站账户」tab（登录即自动配好供应商直接进主界面）；模型设置页保留精简入口横幅；输入框旁与侧栏账号区实时透出当前套餐余量或余额（5 分钟自动刷新）；切换账号时输入框余额徽标与模型配置立即跟随刷新（按账户切换指纹强制重拉，同网关多账号也能区分，不再卡在旧账号）；密钥 safeStorage 加密，401 自动重登
• 技能中心：技能清单直连腾讯 SkillHub 市场 API（总排行=四榜单并集 280+ / 近期最热 / 最新上传 / 官方精选 + 10 大分类筛选 + 搜索），卡片显示真实图标（iconUrl，缺失走 emoji/图标映射），点卡片弹出详情预览（简介/分类/一键安装/来源直达），一键安装（zip 下载 → 安全审计 → 写入技能目录 → 重启引擎确认），来源清单按市场写 .skillhub.json；技能列表统一走中文注释——输入框 # 面板、+ 技能子面板、/skills 命令同一份数据源（本地 + 引擎技能规范化去重，插件限定名 ponytail:ponytail-audit 与本地 ponytail-audit 不再重复），市场/引擎的英文描述统一替换为中文说明，面板全量展示（滚动承载）不再截断；SKILL.md 的 UTF-8 BOM 自动剥离——带 BOM 的技能文件引擎会判「缺 frontmatter」整份拒载（表现为「装了、列表里有，但引擎永远不用」），安装/本地导入时统一剥掉，启动时还会扫一遍用户技能目录自愈存量文件；新安装的技能也带中文注释——安装时把市场提供的中文简介（SkillHub description_zh）写进来源清单，装完即可显示中文，不再回退英文；卸载技能与安装同款分步流程（校验技能目录 → 删除技能文件 → 清理来源登记 → 重启 Codex 引擎 → 确认引擎已移除），结束时明确给出「引擎是否已不再发现该技能」的结论，不再是点一下弹个提示、让人怀疑没卸干净
• 插件市场：页内直连 Codex Plugin Marketplace（codex-marketplace.com，419+ 插件，含 OpenAI 官方 openai/plugins 仓库），卡片展示 + 中文简介，点卡片弹出详情预览；图标原地址优先、失败切 jsDelivr 镜像再回退首字母；一键安装完整接通引擎（GitHub 拉取文件（带重试）→ 本地 marketplace + .claude-plugin/marketplace.json 清单 → 引擎 plugin/install RPC 拷入 plugins/cache 置 installed → plugin/list 回读验证），无需 ChatGPT 登录；下方保留已安装插件启停管理（含随包 ponytail）
• 写代码模式插件：ponytail（会话钩子 + 6 个技能）随包安装源，「开发工具」页一键安装，引擎初始化保持原生
• 连接器（MCP）：飞书/钉钉/腾讯文档等 MCP 服务器可视化配置；新增 MCP 市场（SkillHub MCP 工具广场 27 个服务，分类/搜索/已接入标记，点卡片弹出详情预览，带接入模板的服务一键写入连接器——落盘→重启引擎→自动验证 MCP 状态，密钥可事后补充，其余直达官网详情页）；页头另有 AIbase 广场入口
• 专家团队：「专家中心」按领域分类陈列全部专家（研发交付/投资交易/内容创作/数据分析/市场增长/产品设计/专项专家），点卡直达一对一会话；可组建多角色专家团，主理人按 SOP 编排协作。并行阶段（SOP 标「并行」）一次 team_phase_invoke 提交整组成员，宿主并发执行（实测 3 名成员同时跑，整轮耗时≈最慢者）；消息区右侧有成员头像轨——主理人在上、成员在下灰线相连，谁在干活谁亮起（呼吸环 + 流光），干完打勾，窗口变窄/侧栏展开自动收起；成员开工自动弹出工作弹窗实时流式显示它的产出、结束自动收起，点头像随时翻历史工作记录；同一成员多次委托复用同一线程（有记忆），成员线程标题为「团名·角色」；专项专家里的独立单人专家：知微（内容创作）、呈象（PPT 演示）、洞明（代码审查——先读上下文再看 diff、按 52 份语言级规则（Java/Go/Python/TS-JS-React/Rust/C++/SQL…）过筛、报错前自审去误报、按严重度分级给可执行修法；技能包沿用 alibaba/open-code-review 的规则集与方法论；安装位置有变时自动校正技能包路径，不会静默失效）
• 运行动态状态行（09-16）：任务跑起来后，消息流底部会显示一行「正在执行命令 · 让子弹飞一会儿，看它落在哪儿」——前半句跟着 agent 的真实动作切换（执行命令 / 编辑文件 / 深度思考 / 搜索网页 / 调用工具 / 生成回复，以及「正文已完整，等待模型收尾」这一收尾等待态），后半句每次任务随机锁一句（词库 62 句：40 条通用 + 按活动类型各配的 22 条专属，专属在前、通用兜底；收尾等待态只用专属句，避免「正在把改动收拢干净」这类干活句误导）。任务跑完状态行即消失，恢复正常消息流，不常驻、不占位。
• 会话级调度（09-15，09-16 修复工具注册）：顶栏**「独立弹窗」图标左边的调度按钮（会话级，与模型/权限同源存放）——开启后 Codex 可把合适的独立子任务交给专家 / 专家团 / 子智能体去做并拿回产出，开启瞬间自动往对话框发一条告知消息，它立刻知道自己有这个能力。⛔ 工具走内置 MCP（harness-dispatch，本机 HTTP 直连）：引擎硬约束 —— dynamicTools 只在 thread/start 生效（实测 resume / fork / turn-start / queue-start 四种通道全不认，"补注册"是假象），老会话永远拿不到；MCP 是唯一覆盖所有会话（含老会话）的注册通道。端口固定（47120）+ 令牌持久化，config.toml 的 url 跨运行稳定。独占锁：同一时间只允许一个会话开调度（其它会话面板显示占用者 + 「接管并开启」原子转移，执行侧校验持有者，非法调用一律拒绝）。受保护会话：专家 / 专家团 / 被调度的临时会话的调度按钮直接禁用（锁图标）。四层防护：① 提示词层（给被委派会话下发会话级持久指令**：直接干活、不要转派，专家团主理人只许调度本团成员）② 注册层（委派会话不给调度工具，少给一次犯错机会）③ 执行层硬闸（委派会话再发起调度一律拒绝 —— 给了工具也不认，这是防「专家调专家」无限套娃的最后一道）④ 总量闸（并发 4 / 调用链深 1 / 回传输出超长自动截断）。调度可视化（09-16）：调度运行中右侧消息区出现头像轨（专家/专家团/子智能体各带图标 + 呼吸环），点开看实时产出流；跑完头像停留 20 秒（呼吸环停、头像回正，方便你查看内容）后自动消失。归档调度临时会话时真调引擎归档 —— 侧栏那个会话会立刻消失（不是只做个标记）。被调度的临时会话在左侧侧栏展示并带「调度中 / 调度 / 调度失败」标记，任务结束后保留不自动清理；一个任务整体做完后 Codex 会主动问你是否归档这些临时会话，你同意它才会归档。一键释放（09-17）：面板显示被占用时多一个**「释放并删除该会话」——确认后收回调度权并删除那条旧调度会话（级联清掉它的衍生态）；同时会话被归档/删除时会自动清掉它的调度记录，渲染层发现持有者已不在会话列表也会自动释放**（此前漏清 ⇒ 孤儿记录永久占着全局唯一的调度权，而那条会话在侧栏上已找不到，用户没有任何入口能关掉它）。

🛠 自动化工具箱（开发工具页按需下载）

• 桌面自动化：截屏/键鼠/窗口控制/OCR 感知（Nuphus，压缩包解压即用）；视觉识图已接通——内置「视觉辅助插件」配好后会下发给 Nuphus（NUPHUS_MCP_VISION_*），desktop_vision 不再报「没配 API key」，也不需要回落到慢的本地 OCR
• 浏览器自动化：Playwright CLI + 反检测指纹浏览器（过 Cloudflare/reCAPTCHA），包体与浏览器内核分别下载；内置 browser-skill 技能随应用写入（playwright-cli 全工作流实操手册 + 通道选型 + CloakBrowser 反爬升级，升级自动替换旧版说明）
• RPA 流程自动化：跑通的自动化流程一键存为配方，随时复现；agent 自动询问沉淀配方；任务清单 agent 可自主维护
• 「目标与进程」面板（对话区右上角悬浮）：两个分区各自计数——「执行计划」显示引擎 plan 模式的计划与目标，「待办事项」显示 agent 通过 task_add 维护的待办（本地勾选/删除即时生效）；面板会随任务进度实时刷新，任务跑完即自动隐藏（不占屏），顶行工具栏的常驻入口（带 已完成/总数 徽标）可随时把它叫回来
• 基础运行时：Node/VS Code CLI 随应用内置；Python/Git/PowerShell/rg/uv/CMake/7-Zip/jq/Ninja 在「开发工具」页按需下载（国内镜像优先，失败回落官方源），首次启动检测到缺 Git 会自动后台安装（Windows；macOS 的开发工具页同套卡片，下载原生 darwin 构建、git 走系统 CLT，界面自动反映真实安装状态）
• 终端：xterm 内置终端，会话级持久化

⚙️ 工程化细节

• 权限分级：只读/自动编辑/完全访问三档审批，敏感操作确认执行；会话中途切换即时生效（经引擎 thread/resume 通道下发 sandbox + 审批档位），切换后工作区外读写按所选档位放行；重启应用后权限显示与生效状态保持一致（打开会话只恢复显示、不再向引擎回写旧策略，完全访问不再被静默降级成灰色）

• MCP 按工具权限（09-16 修正为引擎真支持的机制）：连接器页可对每个 MCP 服务器逐工具设「允许 / 需批准 / 拒绝」。拒绝＝真阻断——写进引擎的 disabled_tools，该工具直接从引擎工具表里消失、模型看不到也调不动；「允许 / 需批准」写进 [mcp_servers.<服务器>.tools.<工具>] approval_mode（auto / prompt）。此前把规则写成 [permissions.allow/ask/deny] + "mcp__x__y" = true 是无效的（引擎没有工具级权限表，规则被静默丢弃），而且缺 default_permissions 会让引擎判定整份 config.toml 非法（config/read、mcpServerStatus/list 全部硬报错）；这条路径已删除，用户自己手写的 [permissions.*] 档位也不再被 harness 重写时删掉

• 供应商连接自检：模型设置页列表底部有**「测试当前供应商」按钮（不必先进编辑器），编辑器内每个供应商也有「测试连接并拉取模型列表」与单模型「测试该模型连通」；失败会弹醒目提示并附排查清单——认证类错误保留供应商原文**（网关说「API key 格式不正确」= Key 与通道/Key 类型不配套，如火山 /api/plan/v3 要套餐专属 Key，「Invalid API key」才是 Key 值不对），并给出 ① Key 是否复制完整（末尾空格/换行）② Key 与 Base URL 通道是否配套 ③ Key 是否过期/未开通模型 三条排查方向，不用再翻引擎日志

• 上下文窗口只有一个真相（09-19 修复）：供应商表单里的「上下文窗口」只是新建模型时的默认值，每个模型自己的那个值才是生效上限（引擎实际读的就是它）。原先两处各写各的，保存后经常留下一对打架的数字——界面按大值算（显示 12% 的假安全感）、文件里另一个值（128000）却像真上限。现在保存时顶层会自动同步为生效模型的值，模型编辑器里也会直接写明「本模型的值才是生效上限」，四个地方（两个配置文件 / 引擎 catalog / 界面显示）永远一致

• 模型配置防误填：模型编辑器对超常见的上下文窗口（>256K）/最大输出（>128K）值显示中文预警——虚标会导致长任务请求被供应商拒绝或无限等待；填写的**「最大输出 Token」真实生效**（写入引擎 config.toml 的 provider 段，作为单次输出上限，防止超长输出撑爆上下文）

• 供应商切换「强制重启生效」：切换/保存供应商会弹窗确认后立即重启引擎使新配置生效（正在运行的任务会中断，会话历史保留）；重启后旧会话自动跟随新供应商——在绑定旧供应商的历史会话里发消息会自动迁移到当前激活供应商（引擎 thread/resume 官方通道，历史完整保留），不再因 Key 错配而 401 无限重连；全局一次只生效一个供应商（OpenAI 官方订阅 / 中转站 / 自定义 互斥）——启用一个后其他供应商的启用/设为当前按钮全部置灰，只有停用当前供应商后才能启用其他；旧会话永久跟随当前供应商——config.toml 里每个供应商段（含已删除供应商的历史 id，由会话存档扫描补成别名段）都指向当前生效供应商的地址与协议，任何历史会话都必然走当前供应商、切换后原会话直接可用（引擎只有一把全局 Key，这是唯一自洽形态）；模型配置页进入即展开当前已配置生效的供应商（不再停空白表单），启用/停用合并为状态药丸按钮（带状态点与「点击停用/点击启用」），并去掉多余的「设为当前」按钮（启用即生效）

• 模型删除即生效：模型列表移除某个模型后点「保存」即为最终状态，不会再被旧配置复活（保存以界面完整列表为权威）

• 每个会话独立选模型：引擎的 thread/resume 不回带模型，模型由客户端在每轮 turn/start 里下发——所以模型是会话级状态。规则只有两条：打开会话用它自己记着的模型（切到哪个会话就亮哪个会话的模型，互不串扰），只有它还没有记录（新建 / 从没选过）才落到全局默认；改全局默认只影响新会话 + 当时打开的那一个会话，绝不波及其它会话。设置页、一键切中转站、启用官方订阅、登录导入这些全局动作同样只同步「当前打开的那一个」。判定逻辑是纯函数 src/lib/model-scope.mjs（离线预检跑它的行为断言，另有守卫盯着「default-model 只许有一处写入」）。改了就要立刻生效：在输入框下方的模型下拉里换一个模型，下一条消息就用新模型（不是「重开会话/重开应用才生效」）——model-scope 场景第 ⑦bis 步专门钉死这条：改完下拉立刻真发一条，再回 rollout 核对引擎这一轮跑的确实是新模型。选模型时还会100% 同步整套档案（custom-model.json 顶层 model + config.toml 顶层 model + catalog 上下文窗口；apply:true, restart:false —— 一次写齐配置文件但不重启引擎，不打断正在跑的回合）——模型被问「你是什么模型」时会读这个文件自查，不同步它就会自报旧模型，让人误判「切换没生效」；提示只在真有别的窗口改过时才出现（09-14 修正）：主进程会把变更广播给所有窗口（包括写入者自己），而且广播可能早于界面状态更新，于是「我自己切个模型」也会被当成「另一个窗口改了」弹提示。现在写入时登记自己的签名、广播回来先认回声；版本号过期（conflict）也不再提示——那常常是自己连续两次写入造成的，不是别人。
  但会话自己的模型绝不回写全局档案：有会话打开时 modelId 是该会话的模型，拿它去写全局，别的会话（和另一个独立窗口）被问「你是什么模型」时就会读到这个会话的模型——这正是 09-14 用户实测「模型还是串全局的」的第二条泄漏路径。所以档案对账 effect 加了「无会话才写」守卫，全局档案只在「无会话时选默认」「跨供应商切换」两条路径上更新（离线预检有守卫断言，accept.mjs 的 session-scope 场景用「切模型 / 切走再切回」两步钉死）。

• 会话作用域下发（模型自报「我是谁」读会话级，不再读全局）：会话级配置不会自动进 prompt——模型被问「你是什么模型 / 什么档位 / 什么权限」时，它能读到的只有全局 config.toml / custom-model.json 的顶层，那是「新建会话时的默认值」，于是自报成全局那个（rollout 的 turn_context.model 反而证明它真的跑在会话级模型上）。修法：把「会话 ID / 当前模型 / 思考档位 / 执行权限 / 工作区」+ 一句「全局顶层不代表当前会话」拼成会话作用域块，写进该会话自己的 developer instructions（thread/settings/update 的 collaborationMode.settings.developer_instructions，引擎按 thread 持久、不进全局 config.toml），切模型 / 切档位 / 改权限 / 打开会话时随变更一并下发（签名未变不重发，反复下发幂等）。纯逻辑 src/lib/session-scope.mjs（离线预检【4a-2】14 条断言），回归 accept.mjs 的 session-scope 场景（rollout 取证：块里写的 == 引擎侧 turn_context.model，且全局基线没被顶掉）。

• 会话级配置只存一个对象（09-14 向 ZCode 形态收敛）：模型 / 思考档位 / 权限以前是三套 localStorage 键族（thread-model-* / thread-effort-* / thread-permissions-*）各写各的，约 20 处写、15 处读散在十来个函数里——「档案与会话记录分叉」「兜底 effect 冲掉刚选的模型」都源于此。现在收敛成一个对象 thread-runtime-<id> = { model, effort, sandbox, approval, rev }：一次读、一次写、一个校验点，以后加会话级字段（子代理默认模型等）不必再加第四个键族。旧三键降级为派生镜像（只写不读，仅给旧版本降级兼容），首次读取时自动迁移，升级不丢配置。配套规矩：只有明确的用户动作才落盘，effect 一律只改内存。纯逻辑 src/lib/thread-runtime.mjs（离线预检【4a-3】14 条断言），回归 accept.mjs 的 thread-runtime 场景（切模型/切档位/切权限各改一处不冲掉别处、镜像一致、旧键迁移、旧键写成伪造值也不影响取值）。

• 多窗口并发保护（09-14）：独立会话弹窗与主窗口是两个渲染进程，共享同一份 localStorage（存储一致），但各自 React 状态是旧的、写入又是「读-改-写」——两个窗口改同一会话会互相看不见、丢更新（都读到同一个版本号，各写回一次，后写的把前者的改动抹掉）。现在会话运行时配置的权威值放在主进程（<userData>/thread-runtime.json）：写入天然串行、字段级合并（两个窗口各改一个字段都不丢）、按版本号 rev 判冲突，改完广播给所有窗口，其它窗口的界面与本地缓存立刻跟着更新。localStorage 降级为同步读缓存，playwright/渲染层的大量同步读取不受影响；升级时首读自动从本地播种，不丢配置。

• 复制走主进程剪贴板：消息/密钥/路径等所有「复制」按钮统一走主进程 electron clipboard（clipboard:write IPC），不再依赖渲染层 Clipboard API——窗口失焦或权限被拒时后者会抛「Write permission denied」（用户实测的「复制失败」toast 即此因）；IPC 不可用时回落浏览器 API，再回落隐藏 textarea + execCommand。

• config.toml 孤儿键自清理 + 钩子中文徽标：引擎运行中写进 config.toml 的顶层键若错位落到某个段落内（如 model_reasoning_effort 落进 [mcp_servers.nuphus]，TOML 语义上属于该段、引擎不读，还会误导排查），重写时自动清除；消息 footer 的小扳手钩子徽标把「session-start:0C:\Users...」这类原始名映射成「会话启动钩子 #0」等中文短名，长路径悬停可见。

• 会话切换直切（缓存秒开不再遮罩）：打开过的会话（缓存命中）切换时直接渲染缓存内容并定位到最新消息，不再强制显示 ~200ms 过渡遮罩——缓存直渲 + 后台 resume 对齐（30 秒内切回免重复 resume）；只有首次打开、需要真正加载的会话才显示遮罩。

• 独立会话弹窗（09-13 新增）：把会话开成独立窗口，多个会话窗口可同时存在、各自独立滚动与操作，不用来回切。三种打开方式：① 顶栏 📁 左边「独立会话弹窗」按钮（当前会话弹窗）；② 侧栏会话行长按 600ms 拖出（行高亮 + 跟随鼠标的「松开拖出」提示，松手即弹窗）；③ 同一会话重复弹窗自动聚焦已有窗口。弹窗窗口与主界面外观一致（同款无边框标题栏/侧栏/顶栏，可拉到应用外任意位置）；弹窗顶栏同位置变为「返回主应用」按钮，点击把该会话带回主窗口并关闭弹窗；主窗口关闭时所有弹窗跟随关闭。

• 欢迎页「项目地址」选择：欢迎页输入框左上角可切换「使用项目地址」（与右上角 📁 同一全局目录联动）或「不使用项目地址」——后者每次新建会话自动创建一个独立临时子目录（scratch/chat-<日期>-<id>），各会话互不干扰；Windows 落应用安装目录（不可写时回落应用数据目录），macOS 直接落应用数据目录（不写 .app bundle——写进去会破坏代码签名）；发送首条消息后该选择器随欢迎态消失。

• 我的音色（音色克隆，09-12 新增）：装好音色克隆模型后，在「设置 → 语音通话 → 我的音色」里
  导入一段 wav（或录制 10 秒），本机 ASR 会自动识别出音频里念的那句话作为参考文本，你核对/改对后
  保存即可——之后语音通话就用这个嗓音说话。支持多个音色档案（试听 / 选用 / 删除 / 改回内置音色）。
  硬约束：参考音频与参考文本必须一致，对不上克隆音质会明显劣化，所以必须经你校对。

• 实时语音三修（09-12）：字幕浮窗改成实心白底、固定在对话区上半部（旧版贴着输入框且半透明+毛玻璃，后面的消息会透上来和字幕重影，也会随输入区一起动 = 「上下文跳动」）；悬浮球右键新增「打开 / 收起通话面板」，通话界面可独立开关；播报不再被自己打断（回声门控起播静音不再把地板压到 0，且要求连续多块超阈才算插话）；首句更早出声，语音跟上正文不再慢半拍；渲染进程崩溃不再让应用整体退出（自动重载 + 落盘 voice-crash.log 取证）。

• 发送锚顶（09-12 晚已修完）：发送消息后新消息钉在对话区顶部（WorkBuddy 观感），回复向下方的空白处流式展开，视口全程稳定——不做自动转贴底（旧贴底模式每个字都把整屏往上顶 = 「出字上下跳动」）；长回复超屏后点「回到底部」或自己滚到底即恢复实时跟随；向上滚动随时解除钉顶翻阅历史。每条消息都钉顶（含连发第二、三条），且落点往下留两行（不贴视口上沿，顶部有呼吸空间），偏移由 App.tsx 的 ANCHOR_TOP_OFFSET_PX 一个常量控制、想再往下调它就够。实现要点：锚顶专用底部留白按「视口高 − 锚点高」自适应，保证短消息下方也有足够空间让 scrollTop 够得着锚点（否则会被浏览器钳在 maxScroll、消息停在视口中间）；并用「最近一次钉顶落点」把程序滚动造成的触底从「用户主动滚到底」里区分开，避免钉顶自杀。回归场景：scripts/e2e/scenarios/send-anchor-top.mjs（连发三条逐条断言，21/21）。

• 通话界面 + 快捷键修复（09-12 下午）：新增应用内通话界面（见语音通话节，右上角「收起」钮已避开系统标题栏关闭钮的区域，不再重叠）；修复全局快捷键三连 bug——①回调闭包锁死挂载时的会话/模型（切会话后快捷键「就用不了」的根因）；②录入组合键时数字/符号键按 e.key 匹配被静默丢弃（按 Ctrl+Shift+1 收到的是「!」）；③先落盘再注册，新键被占用时旧键已注销、配置里存的是死键——现在注册成功才落盘，失败保留原设置并提示；主进程改为先注册新键再放旧键，同键重复设置不再误判失败。e2e 流程改版：npm run e2e 默认只跑最新的场景（按场景文件 mtime），--all 才全量回归，验收不再每次从头跑全部历史场景。

• 桌面与浏览器自动化可安装（09-12 修复，09-16 升级为随包直装）：随包 automation-tools.zip 由打包钩子在打包前自动生成（此前 Windows 包漏带该文件，点安装必报「缺少 automation-tools.zip」）。09-16 起该工具链改为「预解压随包」——tools/npm-global 直接进安装包，装完即「已安装」、nuphus/playwright-cli/cloakbrowser 开箱可用，用户不用再点安装解压（zip 仍随包，作为修复备用）。安装包因此约 +18MB（zip）/+64MB 原始（预解压目录，压缩后约 +20MB）。

• 大模型文件下载更稳（09-12）：音色克隆模型/声码器改「直连 + 加速镜像轮换、每个地址两次（第二次断点续传）、45 秒无数据判卡死」，不再一次请求定生死。

• 音色克隆模型（ZipVoice，开发工具页按需下载）：zero-shot 语音克隆——导入（或录制）一段参考音频，就能用那个嗓音朗读任意文本，中英双语；现有 5 个内置音色不受影响。模型约 156MB（主包 109MB + 声码器 54MB），走「开发工具 → 语音模型」下的独立卡片安装，不进安装包。参考音频需配精确文本（后续导入界面会自动用本机 ASR 生成并允许校对）。

• 渠道语音消息转写：飞书给机器人发语音，会自动下载 → ffmpeg 归一 16k wav → 本地 ASR 转写 → 按普通文本走会话管线（绑定/回复机制全复用），需要 FFmpeg（开发工具页下载）；转写进度与失败原因都会回消息提示。

• 输入框语音听写 + 动态发送按钮：发送键旁新增麦克风按钮，点一下说话、中文实时字幕直接进输入框（不自动发送）；支持长按快捷键松手即发送。任务运行中发送/暂停合并为一个按钮：输入了新内容平滑过渡成发送（点击加入排队），清空后自动过渡回暂停。

• 首次对话身份引导（取名 + 认识你）：新会话的第一次对话，Codex 会热情欢迎你、邀请你给它取一个名字、并了解怎么称呼你和你的使用场景——信息齐了自动保存（助手名/用户称呼/使用场景写入个性化档案并重建引擎全局指令），之后所有新会话都不再引导、语气回归正常工作风格；取的名字会作为 Codex 的长期身份（「Your name is X」写进引擎指令）。只对新会话生效，不影响正在运行的回合。

• 思考等级档案持久化 + 立即生效：思考档位跟模型一起进档案——custom-model.json（models[].effort + 顶层 effort）+ config.toml 顶层 model_reasoning_effort。在输入框「思考」菜单里换档位，下一条消息立刻生效（每轮 turn/start 逐回合下发引擎），同时写档案（切供应商/重装不丢、重启后 resume 的老会话也有兜底默认）；打开旧会话时优先用该会话的显式记录，没有才落档案档位。回归场景 effort-scope（UI 切档 → 档案三处落盘 → rollout 取证引擎实收值）。另注：模型自报思考档位不可信——模型看不到请求参数，问它「你思考等级是几」得到的答案是编的，判定只认 rollout 的 turn_context.effort。

• 审批就是输入框上的一行（09-14）：审批请求不再是一张张大卡往下堆（两条就把输入框上方占满），而是收起态只占一行——图标 + 标题 + 一句话预览（命令首个非空行 / 改动原因 / 权限项）+ 允许/拒绝按钮，点这一行才展开完整内容（完整命令与工作目录、改动原因、权限清单）看清楚了再决定；多条统一收进限高容器、超出滚动，再多的审批也不推挤输入框。需要你填东西的两类（问问题 / MCP 连接器确认）本来就是表单，保持展开，但也只占表单本身的高度。窄窗口也自适应（09-14）：把窗口缩到 380px 宽，这一行仍会按视口收窄、超长命令用省略号截断，允许/拒绝 始终留在可视区内——不再出现「卡片比窗口还宽、按钮跑到屏幕外」。

• 沙箱隔离：Windows 沙箱执行，命令越界走审批流

• 多模型接入：任意 OpenAI 兼容端点，多供应商多模型自由切换；内置 GPT 系/主流国模规格表（上下文/最大输出/思考档位/视觉模态按型号自动识别），填模型 ID 即自动填好全部参数；支持外部规格文件更新模型数据无需改代码；API 协议自动适配、无需选择——引擎按 Responses 请求，本机协议桥按上游实际能力原样透传或转成 Chat Completions（流式输出、工具调用、思考过程一并保留），所以只提供 Chat Completions 的网关（火山 coding / Kimi Coding 等）现在也能直接对话；桥只监听 127.0.0.1、不留存密钥（凭据由引擎带入原样转发），换电脑只需重填一次 API Key；Coding Plan 套餐网关（火山方舟/智谱/Kimi/MiniMax）不提供模型列表接口时自动加载内置推荐清单

• 思考等级（09-16 定稿）：菜单展示 低 / 中 / 高 / 最高 / 极高 五档（最高=引擎扩展档 ultra，按模型映射实际强度；极高=xhigh 顶格档），一般模型默认给 低/中/高/极高 四档；档位跟着模型保存——会话里选的档位即时写入档案 models[].effort（同时同步 config.toml 兜底默认），切模型、开新会话、重启应用都自动跟随，不需要二次保存；旧版档案里自动生成的三档声明升版时自动补「极高」，用户显式勾选的档位列表不会被迁移改动

• 记忆分层：用户档案/项目记忆/会话日志三层记忆体系，自动沉淀

• 会话记录完整性（09-16 校正口径）：历史记录文件（rollout）丢失的会话，引擎会把整条线程从列表里隐藏——实测「跑过一回合的会话删掉 rollout 后，thread/list 不再返回它、按 id thread/resume 报 no rollout found」，所以用户看到的是会话静默消失（旧文档写成「侧栏可见但点开报错」不准确）。harness 侧补齐了两件事：历史会话的 provider 别名段改以引擎线程索引（thread/list 的 modelProvider）为权威源（含归档会话、不解析文件内容，旧实现只扫 sessions/ 首行且文件一坏就静默返回空集），以及防御性的 rolloutMissing 标记（若某版引擎仍返回带 path 的条目，侧栏会显示「记录丢失」徽标并拦下点击，而不是点开才吃引擎原始报错）

• 归档管理：会话归档集中管理，恢复/永久删除，恢复后内容完整可直接续聊

• 账户中心：头像昵称、使用统计一站式菜单；界面主题为一级菜单项，内置浅色/深色两个并排按钮一键切换，语言/缩放菜单项直达

• 应用内自更新：GitHub Releases 单源（09-15 起），检查/下载/安装一体化；发版由 tag 触发 GitHub Actions 构建三端包并发布（见「发版」一节）。下载器会跟随 GitHub 资产的 302 重定向（release-assets.githubusercontent.com）并逐跳校验 https

📦 下载安装

前往 Releases 页面下载：

GitHub 会把文件名里的空格显示为 .，因此 macOS 包在 Release 页显示为 Codex.Harness.Desktop-<版本>-arm64-mac.zip，下载链接请以 Release 页实际名称为准。

不确定选哪个包：左上角苹果菜单 →「关于本机」→ 看「芯片」一行 —— 写着 Apple M1/M2/M3/M4… 就选 arm64，写着 Intel 才选 x64。装错架构靠 Rosetta 也能跑，但更慢、更占空间，建议直接下对的那份。

⚠️ 磁盘空间：macOS 包本体约 580 MB（Windows 包约 350 MB），解压时还要再占一份，之后首次启动还会按需下载运行时与工具链（Node / Git / 引擎 / 浏览器内核等）——建议留 10 GB 可用空间。只剩 1~2 GB 时的典型症状：解压直接报「错误 640」、解压出来的 App 不完整、更新下载失败、工具装到一半报错。这些都不是应用本身的 bug，先腾空间再排查。

基础运行时不再整体内置（09-16 瘦身）：仅 Node（安装器引导）与 VS Code CLI 随包，其余在「开发工具」页按需下载——npmmirror/gh 国内加速优先、失败自动回落官方源，缺 Git 时首次启动自动后台补装；桌面/浏览器自动化工具与浏览器内核同样按需下载，不再随包塞 1.2GB 内核。缺必需工具时，进入主界面会自动弹一次「环境体检」（列出缺什么、多大、缺了会怎样，可一键补齐；必备＝模型 / 工作区 / Git / ripgrep / PowerShell 7，常用＝Python / jq / 7-Zip）——登录页不打扰你，已经配好模型的也不会再被引导配模型。

macOS 首次打开（安装包未做开发者签名，Gatekeeper 会拦截）：

1. 在「下载」里解压（双击 zip 即可）。⛔ 别把 zip 拖进「应用程序」里解压 —— 那是受保护目录，而且解压还要再占一份空间，容易直接失败。
   解压报「无法将 … 解压缩到“应用程序”（错误 640）」= 位置不对或空间不够。换个地方用终端解压：

   cd ~/Downloads && ditto -x -k "Codex.Harness.Desktop-<版本>-arm64-mac.zip" .
   

   （ditto -x -k 是 mac 解 .app 包最可靠的方式，符号链接与权限都能保住；空间不足时它会明说 No space left on device。）
2. 把解压出来的 App 拖进「应用程序」（别在「下载」里直接双击运行 —— 那样系统会把它挂在只读的临时卷上，功能会异常）
3. 右键 → 打开（不要直接双击），弹窗中点「打开」
4. 若仍提示「已损坏」/「无法验证开发者」，在终端执行：

xattr -cr "/Applications/Codex Harness Desktop.app"

路径不用手打：在访达里把 App 图标拖进终端窗口，路径会自动填上。
若报 xattr: No such file: /Applications/Codex Harness Desktop.app，意思是这个位置没有 App —— 通常是还没把它拖进「应用程序」（或放在了别处）。先用 ls -d /Applications/Codex*Harness*.app 确认，不在就换成你看得到的实际路径。

🛠 从源码构建

git clone https://github.com/<YOUR_ACCOUNT>/codex-harness-desktop.git
cd codex-harness-desktop
npm install

# 开发模式
npm run dev

# 构建 Windows 安装包（NSIS）
npm run dist

# macOS 包：在 macOS 机器上执行，或用仓库内 GitHub Actions 云端构建
# （Actions → Build macOS → Run workflow，同时产出 arm64 与 x64 两个 zip）
CSC_IDENTITY_AUTO_DISCOVERY=false npx electron-builder --mac zip --arm64   # 或 --x64

内置工具链随 extraResources 整目录打包。⚠️ 但 resources/tools/* 不在 git 里（大体积二进制，
.gitignore 排除），干净检出里是空的 —— 构建前由 scripts/prepare-windows-tools.cjs（Windows）或
scripts/prepare-mac-tools.cjs（macOS）现造；CI 走的是同一条链（见「发版」）。electron-builder 对
缺失的 extraResources 源是静默跳过，所以装出来的包可能少了随包能力却不报错 —— 打包后必须
node scripts/verify-packaged-tools.cjs <产物 tools 目录> 做真 MCP 握手验收。

🚀 发版（推 tag 即发布）

发布渠道只有 GitHub Releases，且构建与发布全部在 CI 完成：本机远端是 SSH（deploy key），
SSH 只能推代码/标签，既不能创建 Release 也不能上传资产，本机也没有 gh 与任何 API token。
所以发版动作 = 推一个 tag，其余交给流水线。

# ① 版本对齐三处：package.json / package-lock.json（顶部 + packages[""]）/ electron/codex-server.ts 的 clientInfo
# ② 写更新说明：docs/releases/v<版本>.md（应用内「发现新版本」弹窗展示的内容，缺失会让发布 job 直接失败）
npm run check                          # ③ 离线预检必须全绿
git push origin HEAD:refs/heads/main   # ④ 推代码
git push origin v0.0.18                # ⑤ 推 tag → 触发 .github/workflows/release.yml

release.yml 依次做：复用 build-mac.yml（arm64 + x64 双芯片）与 build-win.yml（Windows，含随包
工具链现造）→ 三端产物齐了才发布 → 规范化资产名 → gh release create + gh release upload --clobber。

资产命名是应用侧更新器的匹配契约（electron/updates.ts）：Windows 取 *.exe；macOS 必须同时含
mac、.zip 与架构名。⚠️ macOS x64 的 electron-builder 原生产物不带 x64（叫 …-mac.zip），
流水线会强制改名成 …-x64-mac.zip —— 名字错了用户端静默显示「已是最新」，不会报任何错。

CI 失败要重跑：修好后删 tag 重推（git push origin :refs/tags/v<版本> 再推一次）。

🧪 验证与测试

⛔ 本项目硬性要求：任何源码改动，必须以自动验收全绿为完成标准，不接受「我改完了，你自己点一下试试」。一条命令跑完两层：

npm run verify   # = npm run check && npm run e2e

只跑一半不算验收；改了哪个模块，就给 scripts/guards/ 下对应域的文件加可保留的检查项（静态守卫 + 纯函数断言，毫秒级、不起应用，让这次验证沉淀成下次的自动回归）——⛔ 不是 scripts/check-preflight.mjs，那只是个聚合器、其头注释明确禁止往里加守卫；需要真链路证据的每轮现写、跑完即删——不往常驻套件里沉淀、也不重复跑已经验过的流程（用户 09-14 口径）。不做反证（用户 09-19 明令：「把你的反证流程删了，以后不需要再反证了」），UI 改动必须看截图。

改完代码不必手点一遍，两条命令覆盖：

npm run check   # 离线预检：构建 + 产物新鲜度 + IPC 桥接/类型一致性 + CSS 类覆盖 + 纯函数行为断言（不需要图形界面）
npm run e2e     # 验收（默认只跑 LATEST_ROUND 那一轮，不是全部）：拉起已构建的应用，经 CDP 驱动主界面跑验收项，失败自动截图

• npm run e2e 跑完在 .e2e-artifacts/shots/ 留下每步截图（文件名带场景前缀），扫一眼就知道有没有破相；退出码非 0 即有断言失败。
• 需要真链路证据时，按本轮改动现写一个 CDP 脚本（复用 scripts/e2e/lib/harness.mjs：launch / eval / waitFor / click / screenshot / close），跑在跨轮次复用的持久 profile（.e2e-profile/<name>/，含真实会话历史）上，优先操作既有会话（不新建、不发新消息）；跑完即删，需要历史证据时从 git 里找。跨轮次复用的常驻验收项集中在 scripts/accept.mjs（npm run accept -- --list 可看清单）。 + 既有输入链路零回归守卫）。
• 无 GPU 的机器 / CI 也能跑：Chromium 的 GPU 子进程在无显卡环境里会反复起不来并最终 FATAL 自杀（表现为「CDP 超时」，实测连零项目代码的最小 Electron 应用也一样），框架会带上 CODEX_HARNESS_IN_PROCESS_GPU 开关把 GPU 进程合并进主进程——该开关只对测试实例生效，不影响你日常使用。
• 测试实例的工作区固定为项目根目录：隔离 profile 是一张白纸，界面本来会停在「尚未选择工作区」（部分路径下发送会被拦）。框架现在会把 workspace 注入成项目根并重载一次，所以截图里顶栏显示的就是本仓库路径。
• 隔离 profile 会带上你的真实模型配置（custom-model.json / custom-models.json / codex-home/{config.toml,model-catalog.json}，外加 Local State，并保留密钥密文）：否则选择器里一个模型都没有，「切换模型到底生效没、会话之间是否独立」这类断言只能拿假 id 糊弄，等于没测。保留真 Key（本机 safeStorage 密文 + 同机 Local State 的 DPAPI 密钥材料即可解出）是为了让断言打到真实后端——真实网关真的回包才算数；只想跑「无 Key」的纯逻辑断言可设 CODEX_HARNESS_KEEP_SECRETS=0。改过供应商/模型配置后，这些场景测的就是你的真实环境。
• 「生效没生效」查到引擎侧、并且要查到后端：涉及下发给引擎的开关（模型、权限等）只断言 localStorage / UI 文案不够——框架提供 h.engineModelOf(threadId) 直读该会话 rollout：turn_context.model = 引擎真正跑的模型，token_usage_record.response_id = 真实网关真的回了包（没有它只能证明「引擎接了参数」，09-11 用户指正过这点）。常驻验收项用前者证明「A 会话跑 deepseek、B 会话跑 glm，互不串扰」，用后者证明这几轮都是真实后端回的话。
• Codex 引擎自己也能跑（无需 npm）：resources/tools/node/node.exe scripts/accept.mjs。E2E 拉的是隔离实例，与应用内常驻的引擎互不干扰。
• 打包发布前的门槛验收用 npm run verify:packaged-tools。
• 想亲眼看一眼「全新用户」长什么样（未登录 / 未配模型 / 无历史，不碰你的真实配置与历史）：

  npm run preview:fresh     # 前台运行，关掉窗口即结束；临时数据目录会打印出来
  

  它会拉起一个隔离实例，点「暂时不登录，直接进入」就能看到首启引导与侧栏「模型配置」入口。
  ⛔ 必须在你自己的终端前台跑（别丢后台）—— 应用随这个前台进程存活，进程一退窗口就没了。

详见 docs/TESTING.md。

🏗 技术栈

• Electron 43 + React 19 + Vite 8 + TypeScript 5.9
• 引擎通信：stdio JSON-RPC 对接 @openai/codex app-server
• 终端：@lydell/node-pty + @xterm/xterm
• 远程通道：SSH2 / Telegram / 微信 / 飞书 / 钉钉 / QQ 网关 + 企微 Webhook 推送

📁 目录结构

├── AGENTS.md           # 项目环境速览（Codex 引擎自动读取：能力/工具清单/安装操作）
├── electron/          # 主进程（引擎 RPC、窗口、网关、更新）
├── src/               # 渲染层（React 界面、hooks、纯函数库）
├── scripts/           # 构建/运行时安装/打包脚本
├── docs/              # 文档（TOOLCHAIN.md：工具链清单与安装手册）
├── release-site/      # 配套版本发布中心（Node 服务端，可选部署）
├── build/             # 应用图标源文件
└── docs/screenshots/  # 界面截图

📚 项目文档体系与更新规则

读取机制澄清（09-24 更正）：项目根 AGENTS.md 确实会被动态注入到每次会话的上下文里（本仓实测：它一度长到 502 KB，宿主按 64 KB 预算截断后只送进 13%，2026-09-24 才拆骨到约 39 KB）。
⛔ 此前这里写的是「不是每次会话动态注入的上下文」—— 那句话是错的，而且正是它让这个文件被放任长到 502 KB（按「反正不进上下文」算的账）。写这里的每一行都要按「会被注入、会占预算」来算。
真正每会话/每请求动态读取的是另两份：①应用内引擎读 codex-home/AGENTS.md（个性化 + 中文语言规范，每请求重读）；②WorkBuddy 助手读 .workbuddy/memory/MEMORY.md（工作记忆）。三者内容不同、互不干扰。

功能更新流程铁律（每轮改动固定顺序）：① 改动同步更新 README.md → ② 重要功能额外更新 AGENTS.md → ③ 最后提交 git。

💾 数据与更新

所有用户数据（供应商配置、会话记录、记忆、归档）均存放在 %APPDATA%\Codex Harness Desktop\（macOS 为 ~/Library/Application Support/），更新应用或引擎都不会丢失。禁用供应商只是让它不再出现在模型下拉里，其配置会保留——用该供应商创建的历史会话依然可以打开和续聊。

📋 系统要求

• Windows 10 1809+ / macOS 12+（Intel 或 Apple Silicon）
• 至少 10 GB 可用磁盘空间（首次启动按需下载运行时与工具链；空间不足会表现为解压不全 / 下载失败，见「下载安装」的磁盘提示）
• 建议 8 GB 及以上内存（8 GB 可用，但同时跑多个会话 + 浏览器自动化会比较吃紧）
• 需要能访问所配置的模型 API 端点

💬 反馈与交流

遇到 Bug 或有好想法，欢迎通过以下渠道告诉我们：

⚠️ 免责声明

本项目是对 OpenAI Codex CLI 的独立桌面封装，与 OpenAI 官方无隶属关系。使用本项目产生的 API 调用费用由用户自行承担。请遵守所在地区法律法规及 OpenAI 使用条款。

💝 赞助支持

如果你觉得这个项目有用，欢迎通过赞助商支持我们，助力持续开发：

💝 立即注册支持我们 →

https://api.pptoken.cc/register?aff=X82JSNVC3W3S

License

MIT