接入后有什么不同
适合需要“用户看得见、能中止、能审批、能切换多对话”的桌面应用，例如编程工具、学习助手、文件工作台和智能体客户端。应用本身负责界面与本地资源，Codex App Server 负责账号、对话和智能体运行。
| 需求 | 建议 |
|---|---|
| 桌面端多对话、审批、文件和流式过程 | 使用 App Server |
| 批处理、持续集成或无人值守自动化 | 优先使用 Codex SDK |
| 只要一次普通文本补全 | 兼容接口通常更简单 |
| 纯网页且无法启动本机进程 | 不能直接使用 App Server |
安装技能与准备项目
- 下载 ZIP 并完整解压，把技能文件夹交给 Codex 或放进本机技能目录。
- 在目标项目中明确桌面框架、主进程、渲染进程和可写工作区。
- 确认本机 Codex 可执行文件能够启动，并由用户本人完成 ChatGPT 登录。
- 让 Codex 先读取当前安装版本的官方文档、可执行文件帮助和协议结构，再修改源码。
技能包包含协议、Windows、界面、测试参考，可复用的 Node JSONL 客户端、原生对话界面、结构生成器和假服务测试；当前压缩包约 55 KB，不含账号秘密。
推荐的四层架构
| 层 | 职责 | 禁止事项 |
|---|---|---|
| App Server 进程 | 协议、线程、轮次、模型、认证和事件 | 不要把进程句柄直接交给网页 |
| 主进程适配器 | 启动、重连、请求编号、审批、文件桥和安全策略 | 不要把任意命令执行暴露给渲染层 |
| 状态存储 | 线程映射、进行中轮次、配置和恢复信息 | 不要把账号令牌写进业务存档 |
| 渲染界面 | 消息、过程卡、输入、停止、设置和可访问性 | 不要自行猜协议状态 |
通信默认使用标准输入输出上的 JSONL。每一行是一个完整 JSON 对象；日志必须走标准错误或独立文件，避免污染协议流。WebSocket 目前属于实验性能力，不应作为正式桌面端唯一通道。
登录、模型和能力发现
启动后先完成初始化，再读取认证状态。未登录时显示明确入口，由用户本人在系统流程中登录；登录完成后重新读取状态，不在应用里收集密码、Cookie 或恢复代码。
- 从 App Server 获取当前支持的模型列表。
- 按每个模型返回的思考档位、上下文、图片和速度能力生成设置项。
- 保存稳定标识，不把展示名称当协议常量。
- 版本更新后重新发现，不在源码中写死“最新模型”。
模型列表为空时，先检查初始化和账号状态，再检查当前可执行文件是否支持对应方法；不要退回一份长期不更新的静态列表。
多对话和流式事件
应用里的每个对话对应一个 App Server 线程。发送消息会创建一轮运行；轮次开始后持续消费文本、思考摘要、计划、命令、文件改动、工具调用、用量和完成事件。
- 切换页面或对话时，后台轮次继续，不因界面卸载而中断。
- 事件先写入中央状态，再由当前界面订阅，避免丢片段。
- 停止按钮只终止当前对话的当前轮次。
- 同一事件按编号去重；重连后从已确认位置恢复。
- 刷新界面后从线程状态重建消息和过程卡。
文本增量只更新当前消息的尾部；命令、文件和审批应使用独立过程卡，不要把原始事件对象整段倾倒给用户。
审批、文件、图片和工具
审批是一条双向协议：App Server 发出请求，主进程根据范围展示给用户，再把明确结果回传。用户未决定时不能当成允许，应用关闭时也不能留下永久等待的请求。
| 能力 | 界面应展示 | 默认边界 |
|---|---|---|
| 命令 | 完整命令、工作目录、风险和影响范围 | 高风险操作必须逐次审批 |
| 文件修改 | 文件、变更摘要和可恢复性 | 限定到应用工作区 |
| 图片与附件 | 缩略图、文件名、大小和来源 | 按受控本地桥传递 |
| 外部工具 | 工具名、参数摘要和结果 | 不把秘密写进日志 |
图片不能用“[图片]”占位代替真实媒体输入。必须从选择或粘贴一路追踪到本地路径、协议媒体项和模型事件，测试也要验证模型侧实际收到图片。
界面应该让人看得懂
消息正文和智能体过程分层展示：正文用于最终解释，过程卡用于计划、命令、文件和工具。默认只显示对用户有用的状态，技术细节放进可展开区域。
- 输入框、发送、停止和附件始终属于当前对话。
- 用户向上阅读时不强制滚到底部；接近底部时再自动跟随。
- 后台生成用标签或计数提示，切回后完整恢复。
- 错误写清可重试条件，不把断线、取消和服务拒绝混为一谈。
- 键盘、屏幕阅读器、缩放和明暗主题都能使用。
不消耗额度的测试门禁
技能包附假 App Server 和协议夹具，先用它覆盖完整流程，再由用户登录后的真实环境做一次最小验收。自动回归不应调用真实模型。
- 生成当前安装版本的协议结构并做快照差异检查。
- 测试初始化、登录状态、模型列表、线程和轮次。
- 测试文本、思考、计划、命令、文件、图片和审批事件。
- 测试停止、断线、重连、重复事件、应用重启和后台对话。
- 测试错误映射、日志脱敏、无障碍和打包后资源路径。
- 打包安装后运行烟测，再进入正式发布。
常见故障
启动后立刻退出
检查可执行文件路径、工作目录和标准错误日志。Windows 打包后不能假设开发机的绝对路径仍存在。
能发送但没有流式内容
核对通知事件是否由主进程持续转发，是否错误地只等待请求响应，以及渲染层是否按线程和轮次过滤。
审批卡住
确认审批请求编号、允许值和回传方法来自当前协议结构。关闭窗口或取消轮次时应有明确清理。
模型或字段突然失效
重新生成本机协议结构并与适配层对照。版本敏感字段必须通过兼容层解析，不能凭旧示例猜测。
AI能力要求
完成标准不是“聊天框能回字”，而是账号、模型、线程、流式事件、停止、审批、文件、图片、恢复和安装包测试全部形成闭环。