@hjd-hitsz/claudex-web 4.1.5 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/.env.example +2 -0
  2. package/CHANGELOG.md +31 -0
  3. package/README.md +13 -1
  4. package/bin/auth.mjs +86 -0
  5. package/bin/claudex-web.mjs +20 -0
  6. package/bin/p2p.mjs +134 -0
  7. package/build-info.json +4 -4
  8. package/client/dist/app.js +104 -104
  9. package/client/dist/code-highlight-style.js +1 -1
  10. package/client/dist/document-editor.js +54 -54
  11. package/client/dist/file-panel.js +5 -5
  12. package/client/dist/notification-worker.js +2 -1
  13. package/client/dist/p2p-sw.js +162 -0
  14. package/client/dist/style.css +1 -1
  15. package/client/dist/terminal-panel.js +11 -11
  16. package/docs/architecture/backends.md +8 -1
  17. package/docs/architecture/behavior.md +159 -53
  18. package/docs/architecture.md +36 -339
  19. package/docs/background-tasks.md +30 -26
  20. package/docs/deployment.md +47 -6
  21. package/docs/development.md +107 -151
  22. package/docs/images/desktop-dark.png +0 -0
  23. package/docs/images/desktop-light.png +0 -0
  24. package/docs/images/mobile-sidebar.png +0 -0
  25. package/docs/images/mobile.png +0 -0
  26. package/docs/releases/v4.2.0.md +13 -0
  27. package/docs/versioning.md +13 -3
  28. package/package.json +9 -2
  29. package/packages/background-terminal/LICENSE +674 -0
  30. package/packages/background-terminal/README.md +17 -0
  31. package/packages/background-terminal/background-jobs.mjs +457 -0
  32. package/packages/background-terminal/background-mcp.mjs +79 -0
  33. package/packages/background-terminal/background-protocol.mjs +80 -0
  34. package/packages/background-terminal/cli.mjs +14 -0
  35. package/packages/background-terminal/client.mjs +61 -0
  36. package/packages/background-terminal/codex.mjs +88 -0
  37. package/packages/background-terminal/delivery.mjs +192 -0
  38. package/packages/background-terminal/log.mjs +25 -0
  39. package/packages/background-terminal/native-watches.mjs +160 -0
  40. package/packages/background-terminal/package.json +15 -0
  41. package/packages/background-terminal/service.mjs +126 -0
  42. package/packages/translation-engine/package.json +1 -1
  43. package/server/src/application.mjs +82 -10
  44. package/server/src/auth-http.mjs +187 -0
  45. package/server/src/auth-login.mjs +144 -0
  46. package/server/src/auth-totp.mjs +233 -0
  47. package/server/src/auth.mjs +169 -220
  48. package/server/src/backends/claude/background-tasks.mjs +88 -35
  49. package/server/src/backends/claude/messages.mjs +1 -1
  50. package/server/src/backends/claude/worker-client.mjs +47 -35
  51. package/server/src/backends/claude/worker-lines.mjs +17 -0
  52. package/server/src/backends/claude/worker-server.mjs +49 -69
  53. package/server/src/backends/codex/adapter.mjs +46 -5
  54. package/server/src/backends/codex/background-service.mjs +85 -0
  55. package/server/src/backends/codex/background-task-views.mjs +87 -0
  56. package/server/src/backends/codex/background-terminals.mjs +91 -0
  57. package/server/src/backends/codex/events.mjs +11 -0
  58. package/server/src/backends/codex/methods.mjs +1 -0
  59. package/server/src/backends/codex/native-background-handoff.mjs +72 -0
  60. package/server/src/backends/codex/requests.mjs +51 -38
  61. package/server/src/backends/codex/subscriptions.mjs +34 -4
  62. package/server/src/backends/configuration.mjs +8 -0
  63. package/server/src/backends/manager.mjs +34 -32
  64. package/server/src/backends/storage.mjs +3 -14
  65. package/server/src/config.mjs +13 -0
  66. package/server/src/http/business.mjs +21 -0
  67. package/server/src/http/router.mjs +12 -25
  68. package/server/src/p2p/http.mjs +136 -0
  69. package/server/src/p2p/peers.mjs +132 -0
  70. package/server/src/p2p/service.mjs +229 -0
  71. package/server/src/p2p/storage.mjs +45 -0
  72. package/server/src/p2p/tunnel.mjs +95 -0
  73. package/server/src/p2p-http.mjs +149 -0
  74. package/server/src/p2p-peer.mjs +135 -0
  75. package/server/src/private-file.mjs +14 -0
  76. package/server/src/summary-translation.mjs +1 -1
  77. package/server/src/thread-folders.mjs +3 -13
  78. package/server/src/translation-service.mjs +3 -8
  79. package/shared/codex-preferences.mjs +9 -0
  80. package/shared/p2p-wire.mjs +157 -0
@@ -1,362 +1,59 @@
1
- # Claudex Web 架构设计
1
+ # Claudex Web 架构总览
2
2
 
3
- 本文面向实现和审查 Claudex Web 的开发者,描述仓库当前的模块边界、依赖规则、状态所有权、运行流程及演进方式。功能行为约束见[功能与状态契约](architecture/behavior.md),环境、测试命令和发布操作见[开发者指南](development.md)。改变模块边界、状态归属、协议或构建方式时,同步更新本文及对应回归。
3
+ 本文件是每次任务开始时必读的架构入口,概括系统组成、依赖方向和状态归属。阅读后,AI Agent 根据任务自主选择下方专题及章节,并沿实际调用链查验实现。
4
4
 
5
- ## 1. 系统边界
5
+ ## 系统组成
6
6
 
7
- Claudex Web 同时连接一个 Codex app-server 与一个 Claude Code 运行时。Codex 承担现有 GPT 模型,Claude Code 承担多个非 GPT 供应商;两者分别保存原生对话,执行模型调用、工具和命令。网页桥接负责浏览器身份验证、多页面连接协调及网页专用服务;浏览器负责交互、展示和本地草稿。
8
-
9
- ```mermaid
10
- flowchart TB
11
- Browser[浏览器:React 与本地草稿]
12
- HTTP[HTTP:身份、证书、静态资源、文件、翻译]
13
- Bridge[桥接:请求、订阅、事件、恢复]
14
- Services[服务:PAM、文件、项目设置、标题、撤销]
15
- Codex[Codex app-server:对话、轮次、模型、工具]
16
- Manager[双后端路由:固定 codex / claude]
17
- Worker[Claude 独立执行服务:会话与后台任务]
18
- Claude[Claude Agent SDK:模型与工具]
19
- Browser -->|HTTPS| HTTP
20
- Browser <-->|WSS /rpc| Bridge
21
- HTTP --> Services
22
- Bridge --> Services
23
- Bridge <--> Manager
24
- Manager <-->|JSON-RPC| Codex
25
- Manager <--> Worker
26
- Worker <--> Claude
27
- ```
28
-
29
- 生产网页与业务请求同源。浏览器统一使用 HTTPS/WSS;后端地址由配置解析,明文 WebSocket 限于回环地址,跨主机使用 WSS。会话凭据留在受保护的 Cookie 和服务器会话文件中,前端状态只保存会话结果。
30
-
31
- 后台终端任务 MCP 的规划归属为独立项目,由独立服务持有任务进程、日志、持久化状态与完成通知,供后端代理及其他兼容客户端使用。`feat/mcp-background-tasks` 分支的集成方案保留为拆分参考,Claudex Web 的运行、安装和发行范围排除该分支的任务服务、专用管理界面及自动续跑实现。宿主相关的结果投递与对话续跑在独立项目中通过适配边界设计。网页继续使用现有交互终端、后端原生后台终端管理和通用 MCP 展示能力。计划状态、职责和验收要求见[后台任务 MCP 独立项目计划](background-tasks.md)。
32
-
33
- 持久化与执行边界保持清晰:
34
-
35
- - **原生后端**:Codex app-server 与 Claude Code 各自保存对话、轮次、标题、模型任务与工具记录,是历史恢复的事实来源。
36
- - **Claude 独立执行服务**:持有 Claude SDK 进程、活动轮次、待答提问、持续输入与后台任务。网页桥接关闭时只断开本机连接,重新连接读取同一执行服务的快照;执行服务本身故障后按原生进程身份和持久记录核对恢复。
37
- - **桥接数据目录**:项目模型选择、未分类工作目录、后端连接及供应商配置、认证会话、维护凭据、证书和 Claude 网页索引,统一保存到 `CLAUDEX_WEB_CONFIG_DIR`(默认 `$XDG_CONFIG_HOME/claudex-web`,未设置 XDG 时为 `~/.config/claudex-web`);受限文件采用权限控制及原子写入。
38
- - **模型数据目录**保存翻译模型、原生分词组件及版本校验记录,固定使用当前用户的 `~/.local/share/claudex-web/models`。启停偏好归桥接配置,模型数据独立于 npm 安装与程序升级。
39
- - **浏览器存储**:输入与批注草稿、界面偏好、项目选择缓存和未结束整理任务的恢复线索。重新连接后以实际后端记录核对运行结果。
40
- - **对话用量快照**:公共桥接通过 `token-usage.mjs` 将两个后端上报的 token 用量按完整对话标识分别原子保存到网页配置目录的 `token-usage` 子目录。事件立即更新内存,异步写入按对话串行并合并在途更新;打开与重连的轻量响应恢复对应快照,实时通知优先于迟到响应。归档和删除清除快照,恢复归档后由正常用量通知重新建立。首次缺少快照时保留原生已返回的统计,后续回复继续采集;桥接关闭等待在途写入完成。
41
-
42
- 分支用量在请求原生分支前固定来源快照,成功后以新对话标识独立保存;原生返回的统计和新分支实时通知优先。末尾分支继承来源最新快照,指定轮次分支要求快照所属轮次一致;缺少对应统计时等待新回复上报。快照随原生用量通知记录轮次标识,兼容已有无轮次快照。
43
-
44
- 首次打开缺少用量快照的 Codex 对话时,由 Codex 适配器按原生返回的 rollout 路径逆向分块读取最近的完整用量记录,并交给公共存储持久化。分页分支按照原生 `history_base` 的来源标识及 `end_byte_offset` 追溯有效历史,分支自身的边界统计优先于来源最新快照。读取只返回用量,实时事件与归档、删除状态优先;同一对话的并发补录合并,已有快照直接恢复。原生记录不可读取时保留实际诊断并允许下一次打开重试。
45
-
46
- 原生 `.jsonl.zst` 记录通过流式解压按原始字节边界读取,兼容原生元数据仍返回 `.jsonl` 路径的压缩记录。补录完成后继续使用网页快照。
47
-
48
- `token-usage-reconciliation.mjs` 在每个已启用后端就绪后后台分页核对归档及未归档目录:归档记录清除快照,未归档记录只补录缺失快照。内部读取保持只读并跳过自动标题生成,取消和错误保留可核查状态。维护连接通过 `tokenUsageReconciliation` 提供各后端进度,服务关闭取消核对请求后等待存储排空。
49
-
50
- ## 2. 源码组织与依赖方向
51
-
52
- ```text
53
- client/src/
54
- main.jsx 挂载 React 根节点与全局样式
55
- store.js React 订阅适配与应用动作出口
56
- app/ 页面布局、登录、侧栏、导航、弹窗
57
- application/ 应用用例、共享状态与请求生命周期
58
- domain/ 消息、历史、排序、差异等规则与转换
59
- infrastructure/ RPC、存储、密码管理器和翻译适配
60
- features/
61
- conversation/ 消息、工作过程、提问、目录、文件汇总
62
- composer/ 输入框、模型参数、整理状态
63
- commands/ 快捷命令注册、菜单与执行入口
64
- annotations/ 选区批注与草稿订阅
65
- markdown/ 文本、HTML、图片、链接与 Mermaid
66
- workspace/ 文件、差异、目录、终端与子代理详情
67
- account/ 账户额度交互
68
- ui/ 无业务状态的基础控件与差异展示
69
- styles/ 按界面职责组织的 CSS
70
- server/src/
71
- server.mjs 进程启动与配置装配
72
- application.mjs HTTPS/WSS 生命周期与身份边界
73
- http/ HTTP 路由与静态资源
74
- bridge/ 公共网页操作、写入规则及单文件撤销协调
75
- backends/ 固定双后端路由、配置及适配器契约
76
- codex/ app-server 连接、订阅、请求与事件适配
77
- claude/ SDK 会话、原生历史及独立执行服务
78
- workspace/ 共用文件与网页终端
79
- *.mjs 认证、TLS、文件、标题、配置等独立服务
80
- shared/ 跨端纯逻辑:文件类型、整理状态、传输限制
81
- packages/translation-engine/ 独立翻译子项目:模型存储、分词与 CPU 推理
82
- scripts/ 构建、架构检查、测试、安装与发布工具
83
- tests/ 组件、浏览器、发行包与架构回归
84
- ```
85
-
86
- 前端的箭头表示允许的依赖方向:
7
+ Claudex Web 是连接一个 Codex app-server 和一个 Claude Code 运行时的浏览器工作台。React 前端提供统一交互,Node.js 网页桥接负责身份验证、请求路由与主机工作区;两个原生后端各自执行模型任务并保存历史。
87
8
 
88
9
  ```mermaid
89
10
  flowchart LR
90
- App[app / features] --> Facade[store.js:React 适配]
91
- Facade --> Application[application:用例与状态]
92
- Application --> Infrastructure[infrastructure:外部访问]
93
- Application --> Domain[domain:规则与转换]
94
- Infrastructure --> Domain
95
- App --> UI[ui:基础展示]
96
- App --> Domain
97
- UI --> Domain
98
- Domain --> Shared[shared:跨端纯逻辑]
99
- ```
100
-
101
- `application/create-application.js` 是前端组装入口,创建状态容器、传输对象和控制器,并显式传入协作接口。控制器通过这些接口调用其他能力,各自保存请求修订号及在途任务。`store.js` 只连接 React 的 `useSyncExternalStore` 与应用实例,保留统一的公开动作入口。
102
-
103
- 核心约束如下:
104
-
105
- - `domain` 只依赖本层和 `shared`。需要读取历史等外部数据的算法接收 `rpc` 参数,由调用方提供实现。
106
- - `infrastructure` 可依赖领域规则;`application` 可依赖领域与基础设施。三层都保持与 React 无关。
107
- - `ui` 只依赖本层和领域规则。业务动作由功能组件传入。
108
- - `app` 负责页面组合,`features` 负责具体交互;功能间共用消息渲染、Markdown 和文件入口时直接引用有明确职责的模块。涉及多项业务的状态变更统一放入应用控制器。
109
- - 前后端共用逻辑放在 `shared`,该目录保持无平台和外部包依赖。浏览器源码与服务器源码之间通过协议协作。
110
- - 服务端 `http` 与 `bridge` 通过 `application.mjs` 组装;两者各自依赖独立服务,运行状态由函数参数传入。
111
-
112
- 源码依赖图必须无环。创建新目录前先明确该目录的输入、输出、状态所有者和允许依赖,避免用通用 `utils` 或层层转发掩盖业务关系。
113
-
114
- ## 3. 前端状态与用例
115
-
116
- ### 3.1 状态容器与视图状态
117
-
118
- `application/state.js` 的 `createAppState()` 创建独立状态容器,统一处理状态补丁、共享快照、草稿订阅,以及详情折叠、未读完成标记和整理恢复记录的一致性约束。
119
-
120
- 状态分为两个订阅通道:`useStore()` 取得省去输入草稿的共享快照;`useDraft()` 取得即时草稿。仅改变草稿时,共享快照引用稳定,侧栏、历史和文件面板可继续复用原有渲染结果。`get()` 返回完整即时状态,发送动作使用它读取输入,草稿仍按对话持久保存。
121
-
122
- 状态容器按对话持久保存计划模式选择,切换时恢复目标选择,新建对话恢复默认模式,首次创建实际对话时继承尚未发送时的选择。后端恢复返回协作模式时应用于尚未手动调整的选择。
123
-
124
- 共享状态保存跨组件协作所需的事实:当前对话、消息、轮次、连接、账户、模型选择、详情目标及终端摘要。控件展开、选区位置、编辑器实例、滚动锚点和媒体对象归功能组件所有。文件编辑缓冲区按主对话保存,文件面板首次打开后保留挂载,详情折叠与切换继续保留未保存内容。
125
-
126
- 后端启停以桥接快照为事实来源。状态容器在后端目录或列表更新时按启用状态过滤对话与模型选项,保证实时事件及迟到读取遵循同一可见范围;连接控制器取消已停用后端的当前或待打开对话,并重新读取目录。搜索弹窗按相同规则过滤局部结果,启用范围变化后重新查询。停用只改变网页可见范围,原生历史与按对话保存的草稿继续保留。
127
-
128
- ### 3.2 应用控制器的所有权
129
-
130
- - `thread-records.js`:轮次开始与结束时间、轮次修订、名称修订与已删除记录。它负责协调迟到历史和实时事件的优先级。状态容器在列表或活动轮次变动时应用领域排序。
131
- - `thread-navigation.js`:新建、打开、历史加载、写入能力检查及实际对话创建。`opening` 修订号标识当前打开动作,连接版本共同限定读取结果的目标。
132
- - 附件草稿由导航控制器按对话在页面内存中保存,未首次发送的新对话使用独立草稿。切换时恢复目标附件,创建实际对话时迁移原草稿;图片读取和发送清理持有草稿对象,迟到结果继续归属原对话,成功仅移除已提交快照中的附件。
133
- - 打开主对话时,轮次时间恢复与消息读取并行;历史读取的首个消息分页回调负责提前交付最近记录并启动写入能力检查,其余分页完成后统一合并。首屏记录作为读取基线,期间到达的实时修改继续优先。后台重连读取沿用完整合并,保留现有界面。
134
- - `thread-catalog.js`:完整列表、项目分组、固定、归档、删除、重命名和分支命名。拖放归属通过服务端保存,通知与响应按归属版本合并,当前对话同步有效目录及未分类状态。创建分支前并行读取所属后端的已归档与未归档家族元数据。命名成功后以分支响应打开历史,完整列表随后同步。Codex 分支响应已确认写入并携带模型设置,直接用于初始化新对话。
135
- - `messages.js`:输入快照、附件、引用与批注合成、首次发送、运行中补充、提问回答和计划批准。计划批准按当前方案与轮次复核,复用发送用例,以默认模式提交完整计划;成功后通过状态容器更新原对话的模式,切换后的当前对话保持独立。失败保留可重试内容,成功只清理与已提交快照一致的草稿。
136
- - `message-editing.js`:编辑重发的后端历史核对、回退、重试与已移除轮次状态清理。原地编辑器持有正文、附件和批注,编辑会话记录已成功回退后保留的轮次,用于避免重试时重复回退;底部草稿继续由原输入流程持有。回退前使导航控制器中已有的历史读取失效,其他页面的回退通知通过对话导航恢复实际历史。
137
- - `models.js`:新对话的项目模型与思考强度选择、本地待保存记录、服务端同步和恢复时的选择版本。已有对话的模型与思考强度由导航控制器按后端对话读取和恢复结果取得;连接初始化只为新对话应用项目默认选择,恢复期间的手动调整按选择版本保护。
138
- - `goals.js`:按完整对话标识持有原生目标快照、读取错误和写入占用;请求版本隔离迟到读取与保存响应,原生 `thread/goal/updated` 和 `thread/goal/cleared` 通知优先。目标输入复用主输入及附件草稿,替换已有目标先确认,成功只清理已提交内容。
139
- - `account.js`:账户与额度读取、并发合并、通知版本及账户切换隔离。额度组件负责前台刷新触发和局部倒计时。
140
- - `compaction.js`:手动整理、状态检查及断线恢复核对。整理占用进入共享状态后,所有发送入口采用相同限制。领域层按任务标识合并桥接记录,已结束结果只更新页面已跟踪的同一任务;状态容器在离开对话时清理其完成提示,浏览器只持久保存未结束任务。
141
- - `events.js`:后端通知到应用状态的转换。消息、轮次、标题、差异与终端变化按所属对话和轮次更新。
142
- - `connection.js`:连接快照、首次初始化、后台恢复和通知分发。初始化只恢复开始时的选择,保留期间用户新建或切换的对话。
143
- - `session.js`:会话读取、登录、退出与连接启停。认证变化和当前用户交互各有明确处理入口。
144
- - `notifications.js`:完成通知偏好、权限状态与点击导航。仅实时确认的活动轮次完成事件触发提醒;基础设施负责浏览器授权、Service Worker 展示及 IndexedDB 唯一键去重。通知记录按系统登录用户、对话及轮次隔离,刷新与多页面共享;点击事件等待登录及初始化就绪后交给对话导航。Service Worker 随前端静态资源交付,只承担通知展示及点击处理。
145
-
146
- `infrastructure/rpc-client.js` 独立持有 WebSocket、请求编号和待响应集合。断开或替换连接时清理相关请求;旧连接响应保持失效。执行权限在传输入口调用领域策略统一补全。业务通知交给应用层解释,功能组件只订阅需要的事件并在卸载时取消。
147
-
148
- ### 3.3 一次发送的数据流
149
-
150
- ```mermaid
151
- sequenceDiagram
152
- participant UI as 输入框或快捷命令
153
- participant App as 应用控制器
154
- participant RPC as RPC 客户端
155
- participant Bridge as 桥接请求与订阅
156
- participant Backend as 所属后端适配器
157
- UI->>App: 读取正文、附件、批注快照
158
- App->>App: 检查登录、连接、写入能力、整理占用
159
- App->>RPC: 确保对话存在,提交开始或补充请求
160
- RPC->>Bridge: 带请求 ID 的 JSON-RPC
161
- Bridge->>Bridge: 检查占用并恢复所需写入订阅
162
- Bridge->>Backend: 路由产品操作,调用所属原生后端
163
- Backend-->>Bridge: 请求确认和统一异步通知
164
- Bridge-->>RPC: 映射响应,广播轮次与消息事件
165
- RPC-->>App: 结算请求,按对话与版本更新状态
166
- App-->>UI: 清理已提交快照并展示任务进度
11
+ Browser[浏览器:交互与草稿] <-->|HTTPS / WSS| Web[网页桥接]
12
+ Browser <-->|可选 WebRTC 直连| Web
13
+ Web --> Host[主机服务:文件、网页终端、配置]
14
+ Web <-->|JSON-RPC| Codex[Codex app-server]
15
+ Web <-->|本机 IPC| Worker[Claude 独立执行服务]
16
+ Worker <--> SDK[Claude Agent SDK]
167
17
  ```
168
18
 
169
- 请求确认与任务结束分别处理。开始轮次、整理上下文和交互终端均可先收到确认,再通过通知或历史核对得到最终状态。超时只结束相应等待,界面继续依据真实轮次结果恢复。
170
-
171
- ## 4. 服务端请求与生命周期
172
-
173
- `server.mjs` 读取配置、证书、认证与版本,创建 `createWebApplication()` 并启动。应用实例持有 HTTPS 服务、浏览器 WSS 集合、维护连接和心跳;`close()` 释放监听、连接、心跳及后端重连任务。监听失败通过 `start()` 拒绝返回,便于独立测试和嵌入式启动。
174
-
175
- ### 4.1 HTTP 与身份边界
176
-
177
- `http/router.mjs` 按证书、认证、业务 API、健康状态和静态资源分发。公开证书端点只提供证书与公开指纹;文件、媒体和翻译接口在身份检查后执行。WSS 升级检查来源和会话,每条业务消息及发往页面的消息继续校验会话有效性。退出或过期撤销相关连接与文件传输。
178
-
179
- `auth.mjs` 通过 PAM 验证系统账户,密码经标准输入传给验证程序。会话文件只保存标识哈希,Cookie 使用 Secure、HttpOnly、SameSite=Strict。会话时长及 PAM 程序由 `config.mjs` 统一解析,运行配置说明见[部署文档](deployment.md#配置)。
180
-
181
- `http/static.mjs` 按实例维护文件内容和 gzip 缓存,按文件修改时间刷新。路由支持固定入口、图标及根部 JavaScript/CSS 分块。静态缓存与后端运行状态分别归属自己的对象。
182
-
183
- ### 本地翻译服务
184
-
185
- `translation-service.mjs` 持有启停偏好、准备进度、引擎实例和修订号,通过公开包入口调用 `packages/translation-engine`。HTTP 处理器经参数取得翻译与设置操作。子项目只依赖自身及外部包,提供独立 CLI 与 `prepare`、`translate`、`close` 接口,模型目录由调用方传入。模型下载、校验、分词及 ONNX 推理归独立子进程,桥接主线程继续处理网页请求。
186
-
187
- 首次启用才创建引擎和下载模型。安装锁合并并发下载,临时目录完成校验后原子替换版本索引。已安装文件在准备时校验,损坏后重新安装。关闭时取消下载、结算在途请求并释放独立子进程与分词进程,已安装版本保留。修订号隔离关闭或重启前的迟到结果。
188
-
189
- 前端 `application/translation.js` 持有设置同步与下载状态轮询,组件依据已完成消息安排翻译;工作过程按消息状态和同轮活动顺序识别中途加载的已结束摘要,轮次运行状态继续独立维护。基础设施解析 Markdown 并翻译普通文字节点,源格式、代码、公式和链接目标保留。会话缓存按模型版本及完整原文隔离,等待期间显示原文,译文完成后允许切换。
190
-
191
- ### 4.2 桥接模块
192
-
193
- `backends/manager.mjs` 是公共桥接的组装与路由入口,组合固定的 Codex 和 Claude 适配器、工作区服务与连接配置。浏览器继续使用现有 JSON-RPC 名称,原生协议和运行状态由所属适配器解释。管理器统一组装网页及维护连接的快照。
194
-
195
- 公共操作按以下职责组织:
196
-
197
- - `bridge/product-methods.mjs`:组合项目模型偏好、未分类目录创建、单文件撤销、整理核对和子代理消息读取。项目偏好读取与保存可离线执行,保存成功统一广播更新;依赖执行状态的操作通过所属适配器的就绪检查。历史及整理查询以回调传入,偏好存储位置与旧目录继承由组装参数明确指定。
198
- - `bridge/conversation-policy.mjs`:定义整理期间的写入限制、活动或待提交任务期间的整理限制,以及撤销期间的操作限制。Codex 请求入口与 Claude 请求入口使用同一规则;Claude 入队时在持久化更新内再次读取实际队列和活动状态,保护异步间隔中的状态变化。
199
- - `bridge/file-operations.mjs`:持有单文件撤销占用和重复请求结果,实际补丁校验及写回交给 `file-undo.mjs`。Claude 的实例位于独立执行服务内,网页桥接重启后保留同一实例。
200
- - `shared/backend-activity.mjs`:根据统一快照判断活动轮次、后台任务、排队输入、内部命令、提问及整理占用。配置修改、执行服务升级与停止共用该判定,执行服务在停止前原子复核在途请求和实际快照。
201
-
202
- Codex 原生适配全部位于 `backends/codex/`。`adapter.mjs` 组合原生传输与公共网页操作;`upstream.mjs` 持有 app-server 握手、请求编号、超时及重连;`subscriptions.mjs` 持有原生订阅、写入恢复及空闲释放;`requests.mjs` 与 `events.mjs` 分别处理原生请求和事件;`compaction-recovery.mjs` 通过原生历史核对整理结果。Codex 的原生命令执行和标题生成沿用原有调用链。
203
-
204
- Codex 目标查询直接读取原生已持久化状态,页面显示目标时省去加载写入会话。发送新轮次继续按实际订阅恢复写入。已有列表记录的顺序随实时轮次状态更新,列表全量同步在记录尚未显示或轮次结束时执行。
205
-
206
- Codex 适配器在原生新建、恢复和分支参数中加入 `claudex_references` 只读 MCP 配置,保留原有会话配置并沿用实际后端地址,不修改原生全局配置。原生 CLI 持有 `reference-mcp.mjs` 子进程,它直接连接同一 app-server,提供带游标的 `read_thread` 用户与助手正文读取,网页断开不影响读取。引用按 `thread://` 目标提交并提示代理通过该工具读取;读取结果作为历史参考数据。单元测试覆盖配置合并、分页、后端隔离与错误,`tests/integration/codex-reference-tools.mjs` 用真实 CLI 验证 MCP 注册和调用,隔离模拟历史数据并保持模型调用为零。
207
-
208
- Codex 取消订阅在原生响应确认后结束本连接的释放;其他连接仍持有订阅时原生会话继续存在。后续请求等待取消订阅响应,发送按原生恢复流程重新订阅。Codex 0.169.0 的关闭任务在响应后异步完成,`thread/resume` 在此期间返回目标线程的明确 closing 错误。原生传输通过 `resume-lifecycle.mjs` 将该恢复请求保留到对应 `thread/closed` 到达后重新发送一次,关闭事件先到时同样处理;严格核对原生错误码、完整文本和目标 ID,其他错误直接结算。网页请求及内部写入恢复共用此流程,沿用原请求的 120 秒期限,超时或断线清理等待,运行轮次只在恢复成功后提交。`thread/closed` 同时清理实际已卸载会话的状态。
209
-
210
- 公共桥接通过参数取得后端能力;两个原生适配器各自依赖所属后端和公共服务。架构检查禁止公共桥接依赖具体后端、两个原生适配器互相依赖,以及 HTTP 处理器直接依赖桥接或后端实现。
211
-
212
- `thread-folders.mjs` 保存网页项目归属和待应用目录,管理器按完整后端对话标识投影列表与读取结果,并在恢复和开始轮次时传入目标目录。迁移原子保存后广播递增版本;移动到未分类保留有效目录。Codex 原生恢复与轮次开始接收 `cwd`,Claude 在队列事务中应用目录、按目录变化重建原生持续会话,并通过 SDK 跨项目发现已有历史。
213
-
214
- 标题生成、认证、TLS、项目设置、文件内容、子代理接收记录和补丁撤销继续各自封装。新增独立服务通过组装入口注入到使用它的处理器。
215
-
216
- ### 4.3 断线与恢复
217
-
218
- Claude 网页桥接重启或异常退出时,独立执行服务继续持有模型和后台任务,重连恢复活动轮次、执行状态、提问和原生进程标识。独立执行服务本身重启时,运行时按 PID、系统启动标识和进程起始时间核对原生进程,将待确认输入保留为可重试或取消的状态;网页连接恢复沿用存活进程。
219
-
220
- 浏览器断线时保留可读历史及草稿,RPC 结束旧连接的等待;认证有效后重连,先接收桥接快照,再补齐历史及核对写入状态。后端断线时桥接清理连接所属的在途请求和暂态活动,将未结束整理标为待核对,终端标记为停止,重连成功后重新核对。
221
-
222
- 迟到结果的隔离按资源选择:对话读取使用对话 ID、打开修订及连接版本;账户读取增加账户和通知版本;文件与媒体读取使用目标路径和读取序号;批注提交比较已提交快照;子代理详情使用代理 ID 及挂载生命周期。新增异步操作必须明确其隔离键、取消方式、错误呈现和恢复依据。
223
-
224
- ### 4.4 双后端与模型选择
225
-
226
- 双后端以相同的产品操作、状态及恢复规则验收,完整范围和职责边界见[双后端产品契约](architecture/backends.md)。产品操作保持统一,既有 Codex 的正常调用链作为回归基线;Claude Code 由适配器或职责明确的工作区服务补齐对应体验。前端按产品用例组织,后端能力声明用于原生扩展及模型参数。共享实现的范围依据实际职责和对照验证确定。
227
-
228
- 原生配置根目录沿用本机 CLI:Codex 使用 `CODEX_HOME` 或 `~/.codex`,Claude Code 使用 `CLAUDE_CONFIG_DIR` 或 `~/.claude`。配置、认证、技能、插件和原生历史继续由所属 CLI 管理。网页首次启动在新目录尚未建立时原子复制旧 `$XDG_CONFIG_HOME/codex-web`(或 `CODEX_WEB_CONFIG_DIR`)中的完整配置,保留旧目录及原有工作目录引用;Claude 网页索引同时迁移为新文件名。新目录已有数据优先。网页配置迁移继续读取旧 `CODEX_HOME/codex-web` 下的项目选择,并将已有证书与登录状态原子复制到尚未建立的目标目录;新目录已有状态优先,旧目录保留原样。管理器提供与当前后端无关的未分类索引,同时发布当前及旧版自动目录根路径,前端按原有来源与目录规则分类。后端记录的 `dataDir` 表示原生配置根目录,Claude 的 `stateDir` 从网页配置目录派生,仅保存网页索引、执行服务配置、环境和日志;原生执行、目录查询及历史读取均使用同一个原生目录。桥接自身持久化只写网页配置目录。
229
-
230
- `backends/manager.mjs` 持有固定的 `codex` 和 `claude` 两个适配器,汇总状态、列表与能力声明;配置写入只接受这两个标识,网页后端配置接受启停选择及 Claude Code 网络代理,原生目录与 Codex 地址从服务配置取得,旧网页程序路径及启动参数在读取时归一化。`cli-installation.mjs` 负责标准 CLI 查找、当前版本、npm 官方最新版本及固定官方包的全局安装;桥接管理器启动版本检测服务,启动时及此后每小时检测两个 CLI 并广播缓存状态,关闭时清理定时器;网页读取缓存,版本信息位于所属后端内。管理器持有安装任务并广播状态,安装前复用任务占用与独立服务原子停止边界,重复点击合并。Claude 执行服务取得实际 CLI 绝对路径,systemd 网页服务保留安装时的 PATH。Codex 适配器在专属目录中沿用原有 app-server 连接、账户和模型配置。Claude 供应商配置及按模型 ID 关联的显示别名由 `backends/providers.mjs` 保存;别名随供应商配置同步,模型目录与菜单优先使用别名,模型请求保留原始 ID。供应商通过配置存储的独立读取入口取得记录,Claude 执行服务读取供应商时只依赖自己的配置范围。Codex 地址校验由网页管理器读取后端配置时执行。凭据只在服务器使用,公开响应提供凭据是否存在。默认供应商由 `backends/provider-presets.mjs` 统一登记,和已保存配置按稳定标识合并;设置页通过 `includeDisabled` 读取全部目录,模型目录只读取启用项。默认供应商按目录顺序置于自定义项之前,定义必须包含 `icon`,对应品牌 SVG 放在 `client/src/assets/providers` 并经 Vite 打包;设置页显示品牌图标,供应商列表行展示身份、状态及操作,具体模型名称在模型菜单和编辑表单中展示。默认供应商仅接受 Key 编辑,地址、协议、模型与能力由官方目录固定;读取旧配置时保留凭据并使用当前官方参数。默认供应商以非空 Key 启用,清空后停用,运行时读取同时校验启用状态。
231
-
232
- `cli-package.mjs` 从上游 npm 清单取得版本和当前平台的原生依赖,先将原生包作为必需依赖安装到临时目录,完成下载与 npm 完整性校验,再以同一固定版本执行全局安装。临时目录在成功与失败后均清理,全局安装复用校验缓存,显式包含可选依赖并启用安装脚本。版本查询和安装共同使用网页 Node.js 的 PATH。下载失败结束操作,已有全局安装继续保留。最终 CLI 版本须与安装清单一致。安装状态分别保存简短提示与原始诊断,设置页按需展开有高度限制、可换行的错误详情。
233
-
234
- `application/backends.js` 汇总 Codex 原生模型与 Claude 供应商模型,选择键包含后端、供应商和模型。输入区的 `model-select.jsx` 只负责呈现与调用动作。新对话依据所选模型确定运行时;已有对话继续使用所属运行时,Claude 对话空闲时可以切换供应商及模型。打开对话以其已保存的供应商和模型恢复选择。顶部与侧栏复用 `app/backend-badge.jsx` 仅显示图标,领域层按对话资源标识确定后端,当前新对话采用已选后端;显示归属与供应商名称独立。
235
-
236
- 默认 Codex 对话保留原 ID,Claude 资源使用 `backend:claude:<原生 ID>`;桥接只转换协议中的资源字段,工具参数和用户正文保持原样。历史读取、原生命令和提问响应按资源归属路由,两个后端的同名原生 ID 相互隔离。
237
-
238
- `worker-client.mjs` 将网页桥接连接到独立的 `worker-server.mjs`,后者持有 Claude 适配器和原生执行状态。`worker-launcher.mjs` 在 systemd 用户环境中创建独立的 transient service,配置失败重启;直接前台运行且无用户管理器时,使用独立进程。IPC 目录由 `worker-location.mjs` 按用户和网页执行状态目录定位,目录权限 0700、socket 权限 0600,连接双方核对类型、权限和用户归属。网页桥接的 `close()` 仅断开 IPC,独立服务的停止操作按实际活动轮次、整理、队列、提问、在途请求和后台任务原子检查占用。
239
-
240
- `worker-revision.mjs` 对发行源码、共享模块及包元数据生成代码身份,结合入口路径、模块加载代次及实际配置核对升级。新桥接连接到旧执行服务时,任务运行期间保留原进程并标记待更新;完全空闲后确认旧进程退出,再启动匹配的实现。旧桥接重新连接较新的执行服务时保持新代际。代理、证书和语言环境白名单通过受限 IPC 保存;启动环境使用权限 0600 的 `EnvironmentFile` 在创建 Node 进程前加载,使 `NODE_EXTRA_CA_CERTS` 和 `NODE_USE_ENV_PROXY` 按启动语义生效。代理凭据保留在受限文件中,退出时清理本次环境文件;配置变化沿用同一空闲替换规则。
241
-
242
- `backends/claude/runtime.mjs` 持有每个逻辑对话的活动轮次、输入队列与持续运行的 SDK 会话,`execution-session.mjs` 管理原生输入流及事件。运行中补充进入当前轮次,普通轮次结束后原生会话继续承接输入与后台任务。空闲满 5 分钟且无活动轮次、待启动任务、活动目标或原生后台任务时释放该 SDK 会话,后续提交从原生记录恢复。浏览器断开保持任务运行;服务重启后,未确认完成的输入保留待确认状态,由用户选择重试或取消。后台任务引起的原生自动唤醒按实际消息锚点形成新轮次。
243
-
244
- `sessions.mjs` 管理稳定的网页对话标识,原生 JSONL 是正文与工具历史的事实来源。历史读取通过独立工作进程设置 `CLAUDE_CONFIG_DIR`,SDK 选择实际消息链,`importSessionToStore` 将原生记录导入临时内存快照,按 UUID 补齐投影省略的时间及生命周期字段。网页索引保存轮次状态、原生消息锚点、已确认的文本阶段及补充展示记录。`history-actions.mjs` 使用 SDK 原生分支实现编辑回退与分支,按 `forkedFrom.messageUuid` 重新映射原生消息并保留网页轮次标识,截断边界取下一轮原生输入的 `parentUuid`,保留前一轮完整输出附件;旧原生别名继续归入所属逻辑对话。编辑、分支、归档及删除与发送共用变更门控,先释放空闲原生会话,保护并发写入。
245
-
246
- `project-instructions.mjs` 在每次用户提交时实时读取当前目录及祖先的 `AGENTS.override.md` 或 `AGENTS.md`,保留完整原文、路径与作用域,按更具体目录的优先级组成当前快照。更新与删除通过下一轮的新快照生效;原生 `CLAUDE.md` 继续由 CLI 加载。项目指令读取错误作为本轮失败处理。
247
-
248
- `goals.mjs` 与 `background-tasks.mjs` 分别拥有目标与原生后台任务状态;网页交互终端归共用工作区服务。`catalogue.mjs` 从实际目录与运行时读取模型、命令、插件、代理及 MCP。`account.mjs` 区分原生账户额度与外部供应商计费,`token-usage.mjs` 将原生用量及上下文查询转换为统一展示。列表与搜索归集后端读取错误,保留失败后端已有的同范围记录并支持重试。
249
-
250
- 文件引用查询由管理器依据工作区归属路由。Claude Code 和回环地址的 Codex 通过 `workspace/service.mjs` 调用本机搜索,其他 Codex 地址通过原生 `fuzzyFileSearch` 获取远端结果。路径、显示名称和文件类型使用统一返回结构。本机结果携带已排序标记,浏览器按服务顺序展示;远端结果继续由网页领域层调整优先级。
251
-
252
- 新增供应商及预置 DeepSeek 默认使用原生 Message API,原生请求保留中途系统消息;自定义模型显式配置的能力优先于 CLI 模型目录。历史自定义供应商缺少协议字段时沿用原有兼容模式,编辑保存保留其实际协议。Message API 兼容模式使用顶层 `system` 承载系统上下文,用户正文与工具调用继续保留原始内容块和顺序。协议转换在首次请求前完成,并保留原生思考控制、结构化输出及辅助评估请求;处理规则与原生接口依据见双后端产品契约。文件变更通过工具钩子记录前后内容,撤销复用现有补丁校验。能力声明描述模型参数、外部事实和原生扩展,通用产品入口使用统一契约;原生历史跨运行时交接属于独立设计。
253
-
254
- 外部供应商的模型环境由 `provider-environment.mjs` 生成,主模型与 Opus、Sonnet、Haiku 三个原生别名随本轮选择一起更新。初始化与持续会话共用映射,运行时等待原生模型和设置更新完成后提交输入,设置失败按本轮错误结算并允许重试。
255
-
256
- 两个后端的子代理默认值由网页配置独立持有,保存直接校验、原子写入并广播,保持后端连接、执行服务及当前轮次。前端使用保存响应更新配置,保存链路只包含这一次请求。管理器向 Codex 适配器注入配置读取入口,Claude 独立执行服务从同一配置文件读取;Codex 在原生新建、恢复和分支前读取最新值,Claude 在每轮提交前读取并通过原生会话级设置应用。子代理偏好从执行服务代码与启动配置的代际比较中排除。Codex 在新建、恢复和分支中传入原生 `agents.default_subagent_model` 与 `agents.default_subagent_reasoning_effort`,保留主模型与显式任务模型的原生优先级。Claude 通过原生子代理模型环境设置选择模型,`provider-transport.mjs` 为跨供应商目标生成会话专属模型标识,只将匹配请求路由到目标供应商,并恢复真实模型 ID、目标协议与凭据。Claude 子代理默认强度通过 `CLAUDE_CODE_SUBAGENT_EFFORT` 传入。显式配置的子代理模型请求同时按所属标识设置 `output_config.effort`,使主会话环境中的强度覆盖继续只影响主请求,计数请求保留原参数。同名模型保持隔离。原生账户目标使用 `@native` 标识和模型目录解析出的真实 ID,`native-provider.mjs` 按请求读取原生认证环境或 CLI OAuth 文件,凭据只在服务端使用。持续会话每轮核对目标供应商,子代理目标或强度变化时更新会话级设置并生成新的专属路由标识,主会话进程继续运行。旧路由随会话保留,使已启动子代理继续使用其原模型、强度和凭据;清空默认值恢复原生默认选择,停用或删除的供应商明确报错。输入区模型目录同时为设置页提供“供应商 / 模型”下拉选项,Codex 通过同一 `hiddenModels` 偏好过滤候选。模型与思考强度同行展示,强度选项来自所选模型的 `supportedReasoningEfforts`,切换到不支持当前强度的模型时清除该强度选择。控件仅持有尚未保存的模型、强度及错误。
257
-
258
- ## 5. 功能模块与共享展示
259
-
260
- 顶部文件夹和对话标题复用 `app/header-switcher.jsx` 的菜单、键盘与焦点管理。两者共享侧栏的分组及排序。选择文件夹打开排序首位的对话,选择标题打开对应对话,进行中条目共用侧栏的转圈图标。
261
-
262
- `features/conversation` 组合消息、工作过程、提问和目录。领域层负责按轮次分组与排序;主对话和子代理的只读详情使用相同历史读取和展示规则。计划正文由独立的 `plan-message.jsx` 展示,默认保留约 320 像素的正文预览(用字体相对单位定义),底部渐隐并提供展开入口;收放状态由卡片组件持有,流式更新保留用户选择,卸载后恢复默认折叠,领域层 `plans.js` 根据最新用户消息、计划消息与成功轮次确定批准资格;步骤进度保持独立。工作过程记录、最终回答操作以及本轮文件汇总分别渲染,保持流式过程与历史恢复的顺序一致。
263
-
264
- 主对话按消息快照一次建立轮次到记录的索引,供文件汇总复用;文件汇总按记录、净差异及工作目录缓存计算。Markdown 组件按正文、批注内容和目录复用解析结果,内部媒体和主题更新保持各自订阅。历史前插时,消息区根据前后滚动高度补偿阅读位置;自动跟随时继续定位到真实底部,视口快照归消息区所有并在切换时清理。
265
-
266
- `features/markdown` 集中提供 Markdown、HTML 白名单、图片、链接、数学公式和 Mermaid。消息与工具结果复用同一渲染入口,文件富文本编辑器的 HTML、代码与图表节点继续复用该入口;文件目录由上下文传递,局部组件负责媒体加载与清理。文本安全过滤和路径解析在这里统一维护。
267
-
268
- Mermaid 的流程图主方向转换归 `domain/mermaid.js`,原始正文保持独立;`mermaid-block.jsx` 持有方向、缩放、展开和源码查看状态,`mermaid-diagram.jsx` 按容器宽度等比绘制并处理图内滚动、键盘及 Ctrl+滚轮缩放。尺寸观察与滚轮监听随组件卸载清理,重新绘制继续隔离旧源码和主题结果。
269
-
270
- `features/workspace` 把文件树、目录选择、文件编辑、差异、终端和对话详情拆成独立模块。编辑器与文件变更装饰分别封装;显示的删除装饰与实际保存正文分开处理。`context-panel.jsx` 组合概览和子代理详情,主对话切换统一清理选择,编辑缓冲区继续按原主对话保存。
271
-
272
- `file-markdown-editor.jsx` 复用文档编辑器的文件模式提供可编辑预览,文件模式使用标准 Markdown 数学语法,输入区继续使用其双美元符号规则。`file-document-views.jsx` 按原始源码位置组合成对 HTML,持有本地图片、HTML 和代码的节点展示,复用公共安全渲染及 Mermaid 交互,节点销毁时释放展示实例。文件正文仍归文件面板持有,源码与富文本共用同一缓冲区及保存入口。
273
-
274
- `app` 将输入框和错误提示作为底部插槽传入对话布局。对话布局统一提供消息、底部输入和右侧详情的几何边界;桌面展开详情时输入区域避让右侧面板,详情占满工作区高度。文件下载入口归文件面板工具栏,媒体预览组件负责内容展示及加载重试。
275
-
276
- `workspace/file-search.mjs` 持有本机工作区按根目录隔离的短期内存索引,并合并同目录的在途扫描。扫描应用各级 `.gitignore` 和 `.ignore`,索引条目保留原始路径和类型。符号链接目录可作为条目引用,递归扫描沿工作区中的实际目录进行,`.git` 元数据可通过目录浏览访问。FuzzySort 匹配文件名称和路径,候选按目录、可见性与名称或路径相关性排序。扫描范围与 60 项返回上限独立,索引按批搜索以让出事件循环。服务关闭时取消在途工作并释放索引。浏览器以查询代次隔离迟到响应;`domain/file-suggestions.js` 负责远端原生候选的重排。
277
-
278
- `domain/skill-suggestions.js` 拥有技能建议的模糊匹配与排序规则,`@`、`/` 和技能面板共用该规则。
279
-
280
- `domain/inline-references.js` 管理引用链接与类型解析,`domain/composer-references.js` 定义同后端候选与 Claude 会话正文快照。`document-references.jsx` 拥有文件、目录、技能和会话的原子行内节点,使用 Markdown 链接持久保存名称和目标;输入与消息回显共用 `ui/inline-reference.jsx` 和 `ui/path-icon.jsx`。编辑器在单次事务中替换查询、关闭建议并移动光标,整项删除与撤销由文档历史管理。`application/reference-input.js` 在发送用例的正文快照上生成原生 skill/mention;Claude 技能交给原生命令,Claude 会话引用复用完整分页历史。引用随正文删除和恢复,图片附件继续使用既有附件草稿。
281
-
282
- `features/composer` 管理输入交互;`features/commands/composer-commands.js` 是快捷命令的独立注册表,菜单、按钮和键盘提交走同一解析和执行入口。`domain/commands` 只负责工具命令描述的分类与解析,命令支持范围见[命令覆盖记录](cli-command-coverage.md)。
283
-
284
- 输入区的 `markdown-editor.jsx` 按当前对话异步挂载 Milkdown/ProseMirror 文档编辑器。`document-editor.js` 组装 CommonMark、GFM 和数学能力,逐事务将 Markdown 同步到既有草稿订阅;`document-input-rules.js` 处理整段输入与代码围栏的进入和退出,`document-table-input.js` 将表头及分隔行转换为可编辑表格,`document-list.js` 同步维护列表内容与任务复选框,保持连续键入的光标位置。`document-math-schema.js` 统一解析和序列化双美元符号公式,将同一行和换行写法都表示为行内数学节点;单美元符号保留普通文本。`document-math-input.js` 在编辑器输入入口保留未闭合源码,闭合后在当前段落生成公式并将光标留在公式后。`document-math-view.js` 提供行内公式展示与源码重入,草稿与提交统一保存 `$$公式$$`;Crepe 自带的单美元符号和数学块功能关闭。选中文字时展示格式工具,常规输入直接按 Markdown 语法排版。文档选区与 Markdown 源码位置的转换由 `editor-selection.js` 提供,快捷建议沿用输入适配接口。`document-clipboard.js` 直接将 Markdown 解析结果作为原生文档切片插入,按段落边界合并前后正文,并为末尾块提供正文续写位置;公式粘贴拦截限定在已打开的公式源码内。`composer.jsx` 持有输入框展开状态,展开按钮与发送操作同行;`composer-surface.jsx` 通过原生 dialog 的顶层模态窗口提供集中编辑,窗口切换保留相同文档 DOM、编辑器实例和撤销栈,沿用公共窗口尺寸偏好与手柄;放大前捕获输入区的排版与滚动位置,`composer-placeholder.jsx` 在原位置保留同尺寸只读预览,通过隔离的 Shadow DOM 复用本站样式,预览退出焦点与辅助功能树,关闭及 Esc 返回原输入位置;`editor-frame.jsx` 持有自动高度、手动高度偏好及公共手柄的拖动生命周期,按文档实际高度增高,手动偏好按工作区可用高度比例持久保存;容器、附件及视口变化重新约束高度,工具栏保持可见。`.document-editor-viewport` 是正文的纵向滚动容器,内部 ProseMirror 文档按内容自然排版;正文段落、列表及引用共用输入区字号与行高。仅导入已启用功能的组件样式,基础排版由项目样式定义。使用浏览器原生光标与选区,取消虚拟光标绘制。异步加载期间使用独立持有的文本框,初始化后接收最新草稿、焦点和完整选区;对外输入适配按实例发布与清理,卸载使异步回调失效。编辑器、语言支持、样式及公式字体由 Vite 生成本站分块或内联资源,随 `client/dist` 交付。
285
-
286
- 原位消息编辑通过 `MarkdownEditor` 的 `fill` 模式挂载文档,沿用两行高度及内部滚动。底部输入区的 `EditorFrame` 独立持有高度偏好和调节手柄,按 `.composer` 容器测量可用空间;原位编辑保持自身尺寸。
287
-
288
- 消息编辑器通过 `documentPaste` 将带语言的单行剪贴板文本转换为 ProseMirror 行内代码标记,多行剪贴板文本使用代码块节点。两种节点共用选区替换、撤销和 Markdown 序列化流程。
289
-
290
- 批注编辑在 `features/annotations`,协议解析在 `domain/annotations.js`,存储和订阅在 `infrastructure/annotation-drafts.js`。选区编辑只更新草稿,统一发送由消息控制器完成。账户详情、侧栏宽度和主题分别保留自己的控件生命周期。
291
-
292
- `ui/resize-handle.jsx` 与 `styles/resize-handles.css` 统一所有尺寸手柄的透明操作区、局部圆角标记、默认/悬停/拖动/键盘聚焦状态及全局拖动光标;横向、纵向与双向仅改变标记方向。侧栏、终端高度、终端列表、详情与各类窗口使用同一组件,尺寸规则及持久化仍由各自容器持有。`ui/resizable-textarea.jsx` 为供应商模型、命令目标、提问回答和消息批注字段提供同一手柄,保留表单字段、草稿与禁用语义,高度仅在挂载期间保留。
293
-
294
- `ui/surface-resize.jsx` 持有公共弹窗、图片与批注浮窗以及右侧详情的尺寸偏好、指针捕获和键盘操作;偏好按窗口用途分别以可用空间比例保存在浏览器,CSS 负责最小尺寸和视口边界。详情宽度由对话布局上的 `--context-preferred` 同步到面板与底部输入区的避让空间。尺寸调整保持内容组件挂载,文件编辑与批注草稿继续归所属功能持有;失焦、视口或容器边界变化、隐藏及卸载时释放拖动。批注编辑器独立于选区与标记组件,由调用方提供原文范围定位能力。
295
-
296
- ## 6. 样式、加载与分发
297
-
298
- `style.css` 是有序样式入口。设置窗口的分组与控件尺寸由 `styles/settings-layout.css` 限定在设置弹窗内,更新卡片及常驻更新入口由 `styles/service-maintenance.css` 持有。`styles/theme.css` 和 `base.css` 定义主题及基础排版,其余按侧栏、导航、消息、批注、文件、终端和弹窗等职责组织;响应式及排版覆盖按入口中声明的顺序应用。移动规则时保持选择器顺序、媒体条件和变量作用域;增加规则优先放到所属模块,修改覆盖顺序时验证全部受影响布局。
299
-
300
- 主页面先加载聊天所需的代码。文件面板和终端通过 `React.lazy` 首次打开时加载,文件面板完成首次加载后保持编辑缓冲区;Mermaid 按图表需求加载本站模块。终端面板持有终端列表及活动选择,每个终端组件独立持有 xterm 实例、输入订阅及尺寸观察,切换保留各实例,桥接拥有进程及恢复缓冲区。网页交互终端统一由桥接工作区服务的 node-pty 持有,浏览器通过独立的 `lan/terminal/*` 接口创建、输入、调整尺寸及结束进程,操作先于后端资源路由处理,与模型后端和启用状态独立。服务直接启动系统登录 shell,每 500 毫秒读取实际 PTY 前台进程名,变更时发送元数据通知;快照及启动事件保存进程名、输出、工作区归属与规范化的绝对启动目录,浏览器按名称选择图标并省去目录和编号。应用状态按启动目录保存面板开关,终端组件按目录恢复运行列表和选中项;跨目录切换隐藏原终端,同目录切换对话或模型后端保留同一终端组件。选中项按目录持久保存,后台目录退出只更新所属选择。面板框架独立持有纵向拖动及高度比例偏好,按实际可用高度、输入区和 CSS 保留空间限制高度;高度变化沿用终端尺寸观察同步 PTY 行数。列表组件独立持有拖动、键盘及相对宽度偏好,CSS 定义默认宽度和容器上限,尺寸变化或卸载时释放指针捕获。切换文件夹、隐藏和重连保留进程及缓冲区;全部进程结束或工作区服务关闭后清理检测计时器。后端代理原生命令与后台任务保持所属运行时的路径。终端的基础样式在挂载入口先于项目样式导入,JavaScript 仍按需加载。Vite 保持单一 CSS 产物和根部 JavaScript 分块,保持第三方样式与项目规则的覆盖顺序。
301
-
302
- 根 `package.json` 与单一锁文件管理 workspaces。翻译子项目的源码、许可证、CLI 与构建后的原生分词器随发行包交付,模型权重、Microsoft 分词运行库和 ONNX Runtime CPU 文件在用户启用后独立下载。
303
-
304
- npm 分发由独立的 `npm-publish.yml` 工作流监听即时及定时 GitHub 发布工作流的成功结果,以 OIDC 身份上传已公开的 Release 附件。`publish-npm.mjs` 持有附件下载、校验、临时安装、注册表完整性核对与同版本重试;发布时间继续由发布计划和 Release 草稿状态约束,稳定版与预发布分别进入 `latest` 与 `next`。
305
-
306
- 发行白名单包含 `client/dist`、`server/src`、`shared`、命令入口、运行脚本、许可证和构建信息。增加共享运行模块或动态分块时,验证实际打包清单、生产响应和临时全局安装。生产版本来源由 `server/src/version.mjs` 统一读取,网页在构建时固定,桥接在启动时固定;干净标签构建可交付稳定版本或 alpha、beta、rc 预发布版本;发布工具维护版本顺序和 GitHub 成熟度标记,预发布保留稳定下载入口及 Latest。流程见[版本管理](versioning.md)。
307
-
308
- ## 7. 可执行约束与验证
309
-
310
- 服务安装器创建网页服务时独立于原生 CLI 的安装状态。新建的 Codex 用户服务以当前 Node.js 运行 `scripts/start-backend.mjs`,显式传入网页配置目录、原生目录和连接地址;启动脚本沿用原生 app-server 参数。CLI 缺失时该服务失败后由 systemd 每 5 秒重试,网页继续提供登录、设置和 CLI 安装入口。既有 Codex 服务的保留与新服务的首次启动分别回归。
311
-
312
- Codex 启动脚本将 WebSocket 连接地址转换为原生 CLI 的 `ws://主机:端口` 监听参数,保留 IPv6 方括号并显式补齐默认端口 80。连接地址的 URL 规范化与原生监听参数构造分别处理,监听入口校验协议、路径、查询参数及片段。回归精确核对命令行和服务生成入口实际提交的完整参数。
313
-
314
- `npm run architecture:check` 扫描 `client/src`、`server/src`、`shared`、`scripts`、`bin` 和翻译子项目中的 JavaScript、JSX、MJS 与 CSS:
315
-
316
- 1. 单文件最多 **500 行**,计入注释和空行。日常按单一职责组织,接近上限时先拆分,保持格式化后的正常排版。
317
- 2. 检查相对导入、重导出、字符串动态导入和 CSS 导入是否存在,并检查整个源码图的循环。
318
- 3. 检查前后端边界、共享模块的平台隔离、核心层与 React 的隔离,以及前端核心层和服务端处理器的依赖方向。
319
-
320
- 检查覆盖源码;生成构建、依赖、文档和测试数据采用各自管理方式。测试按场景拆分,共用隔离夹具;大型场景继续按业务流程拆分,避免单个测试入口累计全部功能。架构检查关注模块级依赖,浏览器 API 的使用和状态归属仍须通过审查及行为回归确认。
321
-
322
- 根 `npm run check` 依次执行版本一致性、架构检查、格式检查、单元与组件测试,以及构建和发行包安装验证。`.github/workflows/check.yml` 在分支推送和 PR 时运行同一入口,发布工作流在标签发布前再次执行。相关测试职责为:
323
-
324
- - 领域测试验证排序、分页、协议解析、差异和命令描述;状态及 RPC 测试验证实例、订阅和连接隔离。
325
- - 实际 React 组件测试验证输入、选择、切换、草稿、异步恢复和文件编辑保护。
326
- - 桥接集成测试使用模拟后端、临时记录和模拟 PAM,验证权限、订阅、并发、事件和连接生命周期。
327
- - 浏览器测试使用生产构建和隔离数据,验证真实布局、键盘、焦点、媒体、动态加载及刷新恢复。
328
- - 发行包测试在临时 npm prefix 安装包,验证共享模块、分块资源、无 Git 版本来源和服务配置生成。
19
+ 网页关闭或桥接重启时,原生模型任务继续由所属运行时持有。Claude 执行服务独立于桥接进程;Codex 后台终端扩展的任务服务负责后台结果投递。本地翻译在独立子进程中执行 CPU 推理。
329
20
 
330
- 单元与发行包测试的控制台日志由 `tests/helpers/test-console.mjs` 在模块加载前统一送入 stderr,Node.js 从独立文本流生成日志事件,stdout 保持二进制测试事件传输。该隔离由公共 npm 测试入口持有,回归覆盖 Unicode 日志、并发输出及真实失败退出状态。
21
+ ## 模块与依赖
331
22
 
332
- 浏览器回归按功能风险选择,命令及依赖见[开发者指南](development.md#格式与验证)。修改界面布局或渲染时,在实际消息区和文件面板验证深浅主题、窄屏及规定缩放;修改认证和桥接时使用真实的隔离 HTTPS/WSS 连接。
23
+ - `client/src/app` 组装应用外壳与路由,`features` 组织业务界面并通过参数取得外壳操作,`ui` 提供基础控件。`main.jsx` 只挂载,`store.js` 连接 React 订阅与应用动作。
24
+ - 前端核心依赖方向为 `application → infrastructure → domain → shared`,应用层也可直接使用领域规则。`application` 管理用例与请求生命周期,`infrastructure` 访问 RPC 和浏览器存储,`domain` 维护纯规则。核心三层保持与 React 无关;`ui` 只依赖本层与领域层。
25
+ - `server/src/server.mjs` 与 `application.mjs` 组装服务。`http` 处理 HTTP,`bridge` 维护公共网页操作,`backends/manager.mjs` 路由固定的两个后端,`workspace` 提供主机文件和网页交互终端。
26
+ - HTTP 与公共桥接通过参数取得所需服务和状态;`backends/codex` 与 `backends/claude` 分别管理自己的原生传输、订阅与执行。公共桥接保持与具体后端解耦,两个原生适配器保持独立。
27
+ - `shared` 提供跨端纯逻辑,只依赖本层;前后端通过协议协作。`packages/background-terminal` 与 `packages/translation-engine` 各自只依赖本子项目及外部包。
333
28
 
334
- ## 8. 扩展流程与设计取舍
29
+ 源码依赖图保持无环。新增职责沿上述边界放置;跨组件状态变更由应用控制器协调,状态和服务通过显式参数注入。
335
30
 
336
- 新增功能按以下顺序落地:
31
+ ## 状态与生命周期
337
32
 
338
- 1. 确定输入、输出、事实来源和行为契约,检查现有应用控制器及协议能力。
339
- 2. 将规则或数据转换放入领域层,将外部访问放入基础设施或独立服务;跨组件用例由应用控制器协调。
340
- 3. 为新状态指定唯一所有者,列明对话切换、断线、取消和迟到结果的处理。只在需要跨组件协作时加入共享状态。
341
- 4. 在所属功能目录增加视图,复用统一 Markdown、文件入口和输入提交逻辑;增加协议时在桥接注册并维护生命周期。
342
- 5. 编写能观测真实行为的针对性回归,执行架构检查和完整检查,更新架构、行为契约与相关使用文档。
33
+ 原生后端保存对话、轮次和工具历史,是恢复执行结果的事实来源。桥接只持有网页连接及网页专用状态,原生会话和后台任务由所属适配器及运行时管理。网页交互终端的进程与缓冲区归主机工作区服务。
343
34
 
344
- 当前保留 React、原生 ESM、共享状态快照和现有 JSON-RPC 协议。应用控制器采用工厂函数和显式依赖,沿用现有动作出口,便于逐项验证行为并单独创建状态与传输实例。共享状态的字段关系由控制器和测试约束;未来引入新的状态机制或类型系统时,应以具体的维护收益和迁移验证为依据。
35
+ 网页配置、证书、登录状态、项目偏好及 Claude 网页索引保存在 `CLAUDEX_WEB_CONFIG_DIR`;原生配置沿用 `CODEX_HOME` 与 `CLAUDE_CONFIG_DIR`。浏览器持有草稿、界面偏好和文件编辑缓冲区。私有持久文件采用权限限制与原子写入;目录设置和迁移见[部署与维护](deployment.md#数据保存与迁移)。
345
36
 
346
- 文件规模限制是维护上限,模块划分依据仍是业务职责和生命周期。调整架构规则须同时更新本设计、`AGENTS.md`、检查实现和回归用例,说明影响范围及迁移方式。新功能持续遵循这些边界,现有模块在触及新职责时同步拆分。
37
+ 前端共享状态保存跨组件事实。频繁更新路径上的独立视图使用选择订阅,读取原始值或引用稳定的数据。草稿使用独立订阅,避免每次输入刷新完整历史。展开状态、选区、滚动位置和编辑器实例归组件,未保存文件按所属主对话保留。发送读取输入快照,成功后只清理已提交内容。
347
38
 
348
- Codex 设置中的模型显示偏好由网页后端配置持久保存并广播,模型菜单过滤隐藏项,已有对话保留原模型;设置通过完整原生目录恢复显示。修改显示偏好保持原生执行会话。DeepSeek 默认供应商通过服务端查询官方 `/user/balance`,凭据留在服务器,账户额度快照保存各币种总余额、赠金与充值余额及可用状态。账户行复用额度详情、前台刷新、并发合并、切换隔离和失败保留机制,金额按响应币种展示。
39
+ 请求链为“界面 → 应用用例 → RPC → 桥接 → 所属后端”,通知与历史读取共同更新界面。请求确认、轮次结束和进程退出分别结算。异步结果按资源标识、请求修订和连接代次隔离,实时事件优先于迟到读取;断线保留草稿和可读历史,恢复后核对原生状态。每个异步操作明确取消、清理、失败呈现和恢复依据。
349
40
 
350
- 网络代理由 `backends/network-proxy.mjs` 校验并生成环境覆盖,配置随 Claude 后端保存在网页配置目录。未配置及 `system` 沿用服务环境;`off` 清空大小写代理变量并关闭 Node 环境代理;HTTP 设置同时覆盖大小写 HTTP 代理,旧 HTTPS 选项读取时迁移为 HTTP CONNECT,清空 ALL_PROXY,并让回环地址直接连接。工作进程启动前加载覆盖,SDK 会话设置同步应用,供应商配置覆盖继续保留代理。代理保存复用管理器的忙碌检查、执行服务原子停止与配置事务,保存失败保留旧值,空闲保存后新进程使用新配置。
41
+ 局域网浏览器使用同源 HTTPS/WSS。可选 P2P 使用链接授权和 HTTPS 信令建立 WebRTC 直连,随后使用与局域网一致的网页登录流程。业务请求校验所属传输的登录会话,退出或过期撤销会话和传输权限。协议和生命周期见[传输与维护契约](architecture/behavior.md#传输与维护契约)。
351
42
 
352
- 上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
43
+ ## 构建与验证
353
44
 
354
- 长历史首屏读取最近 100 条消息;首屏全部属于同一轮次且仍有历史时,后续按每页一个完整轮次恢复,减少工具密集对话的串行网络往返。首屏跨轮次时继续使用消息分页,保持短轮次对话的读取效率;两条路径均保留完整历史、轮内顺序、实时更新优先和切换隔离。
45
+ 根 npm workspaces 使用单一锁文件。生产桥接读取 `client/dist`,根包 `files` 白名单控制发行内容。`style.css` 按顺序导入职责样式;Vite 交付根部 JavaScript 分块和单一 CSS,按需加载保持原有样式顺序与编辑缓冲区生命周期。新增运行模块或分块同时验证生产路由和安装包。
355
46
 
356
- 网页更新由 `service-maintenance.mjs` 持有 npm 稳定版检查缓存及维护操作,启动时和每小时读取官方注册表。认证后的 HTTP 维护接口通过应用装配注入服务。独立维护任务执行 npm 下载、隔离安装、版本校验、目录替换、网页重启与 HTTPS 启动检查,任务状态原子保存在网页配置目录。失败时恢复原安装目录并核对恢复后的健康状态。源码部署提供检查与重启,npm 全局部署另提供更新。浏览器应用控制器轮询持久任务状态,页面保留编辑缓冲区,重启成功提示用户手动刷新网页加载新版本资源。部署条件由服务端在点击后的请求中校验并返回原因。
47
+ `npm run architecture:check` 检查源码行数、导入存在性、循环和分层方向;`npm run check` 依次检查版本、架构、格式、单元与组件、构建及发行包安装。测试命令和适用场景由开发指南维护,模块或状态边界变化同步更新相应约束与回归。
357
48
 
358
- 维护任务与 npm 安装方式分别管理:网页进程属于 `claudex-web.service` 时,通过独立 systemd 用户单元维护并由原服务重启;直接运行的网页由脱离原进程的维护进程完成相同操作。维护入口及 `service-maintenance-process.mjs` 复制到配置目录,替换安装后继续可用。普通进程记录原 Node.js、参数、工作目录及完整环境,SIGTERM 退出后按原入口启动;更新先安装和校验,再等待旧进程退出后替换目录。退出宽限期为 30 秒,超时后仅向身份仍匹配的网页进程发送 SIGKILL 并等待退出。进程操作按 PID、系统启动标识及进程启动时间核对归属,状态恢复核对所属维护进程,日志保存在 `maintenance/worker.log` 与 `maintenance/web.log`。原生后端继续由各自运行时持有。
49
+ ## 专题导航
359
50
 
360
- CLI 安装同样属于维护占用,公共快照与只读维护快照分别携带所属后端的安装状态;网页重启及更新在安装完成后才接受新操作。桥接关闭时,尚未结束的 CLI 安装按实际结果完成,关闭后的管理器保持适配器关闭。
51
+ 以下按职责提供下一层入口,Agent 自主判断本任务需要哪些内容。
361
52
 
362
- 维护任务在权限 0600 的作业文件中保存网页服务的 npm 运行环境,包含优先使用当前 Node.js 目录的 PATH、用户配置位置、npm 配置、代理及证书设置。npm 安装子进程显式使用该环境,覆盖独立 systemd 用户单元继承的管理器环境。维护单元启动失败时立即释放网页提交门控,持久记录失败并允许重试。回归将 npm 与 systemctl 分别放入独立目录,让工作进程的 PATH 只包含 systemctl,验证环境传递、安装失败保留原包及重启失败回滚。
53
+ - **产品行为**:[功能与状态契约](architecture/behavior.md)。
54
+ - [对话与历史](architecture/behavior.md#对话项目与历史)、[输入与草稿](architecture/behavior.md#输入草稿与执行)、[计划](architecture/behavior.md#计划模式)及[目标](architecture/behavior.md#目标交互)。
55
+ - [工作区、文件与终端](architecture/behavior.md#工作区文件与终端)、[子代理与渲染](architecture/behavior.md#子代理与共享渲染)、[账户与界面](architecture/behavior.md#账户登录与外观)。
56
+ - **原生后端**:[双后端产品契约与实施](architecture/backends.md),包含适配器职责、执行生命周期与协议差异;[回归审查](architecture/backend-regressions.md)保留兼容基线与验证依据。
57
+ - [命令覆盖](cli-command-coverage.md)维护快捷命令及原生扩展;[Codex 后台终端](background-tasks.md)维护独立任务扩展;[翻译引擎](../packages/translation-engine/README.md)维护独立翻译子项目。
58
+ - **开发与交付**:[开发者指南](development.md)提供本地环境、测试入口和源码服务操作。
59
+ - [部署与维护](deployment.md)维护安装、配置、迁移和排障;[版本管理](versioning.md)维护版本准备、发布及重试。
@@ -1,39 +1,43 @@
1
- # 后台任务 MCP 独立项目计划
1
+ # Codex 后台终端 MCP
2
2
 
3
- 后台终端任务能力规划为独立项目,为后端代理及其他兼容客户端提供 MCP 服务。Claudex Web 负责浏览器交互与已有后端能力的展示;独立项目负责长命令的执行、日志、状态恢复与完成通知。
3
+ 启用后,原生 `exec_command` 到达前台等待上限时会返回运行中的会话 ID,同一进程继续运行。模型可以直接结束当前轮次,独立服务会保留仍在运行的原生终端订阅,命令完成后向原对话投递结果并唤醒。模型也可使用 `background_start` 立即启动后台任务。Claudex Web 默认关闭此扩展。Claude Code 使用自身的后台 Bash、任务输出和完成通知,两端共用网页的 `/stop` 入口。
4
4
 
5
- 本文用于约束后续开发和功能合并。当前阶段记录拆分方向,独立仓库、包名、配置协议及宿主适配方案待实施时确定。
5
+ ## 启用
6
6
 
7
- ## 已有原型与处理方向
7
+ 扩展适用于 Linux、Node.js 24.5 或更高版本,以及同机监听 WebSocket 的 Codex app-server。任务服务与 Codex 使用同一系统账户和工作区。命令以该账户执行,服务在启动任务前核对原生会话的完全访问权限。
8
8
 
9
- `feat/mcp-background-tasks` 分支保存了后台任务集成原型,包含四个 MCP 工具:`background_start`、`background_read`、`background_list` 和 `background_cancel`,以及任务守护进程、网页管理界面、完成结果投递和对话续跑逻辑。
9
+ 在网页的「设置 → 其他设置」勾选「为Codex开启后台终端功能」。首次开启会通过用户级 systemd 启动独立任务服务,默认状态目录位于网页配置目录的 `background-terminal` 下。新建对话或重新加载已卸载的对话后,工具连接中会显示四项工具。原生终端接手与此开关联动,关闭后新命令沿用 Codex 原有生命周期。已接手的原生终端和已提交的 MCP 任务继续运行,仍可通过 `/stop` 查看和停止。
10
10
 
11
- 拆分时可参考该分支的 `server/src/background-mcp.mjs`、`background-protocol.mjs`、`background-daemon.mjs`、`background-jobs.mjs` 及对应测试。`background-client.mjs`、`background-rpc.mjs` 与 `background-wake.mjs` 中的网页配置、Codex 对话访问和续跑耦合需要重新划定边界。分支中的 `docs/background-tasks.md` 描述早期集成原型;后续方向以本计划为准。
11
+ 手动运行独立服务时,在 Claudex Web 源码根目录运行以下示例,地址应与目标 Codex app-server 一致。用户级 systemd 单元持有任务服务及命令的进程组,独立于网页和 MCP stdio 连接。
12
12
 
13
- 该分支保留为拆分参考,后台任务 MCP 及其专用网页功能排除在 Claudex Web 的合并、安装和发行范围之外。原型中的实现与验证记录供迁移时核对,独立项目的可用性以迁移后的实际验证为依据。
13
+ ```bash
14
+ state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/codex-background-terminal"
15
+ entry="$(realpath packages/background-terminal/cli.mjs)"
16
+ upstream="ws://127.0.0.1:8765"
17
+ systemd-run --user --unit=codex-background-terminal --collect \
18
+ --property=Restart=on-failure \
19
+ "$(command -v node)" "$entry" serve "$state_dir" "$upstream"
20
+ ```
21
+
22
+ 已有部署会沿用 `CLAUDEX_BACKGROUND_TASKS_DIR` 指定的任务服务,首次读取时开关自动开启,之后以网页保存的偏好为准。停止独立任务服务使用 `systemctl --user stop codex-background-terminal`,服务会结束仍在运行的命令。示例创建的 transient 单元适用于当前用户管理器的运行期。
14
23
 
15
- ## 职责与依赖
24
+ 独立使用时可从 `packages/background-terminal` 打包安装,安装后的命令为 `codex-background-terminal`。同一 app-server 的客户端也可通过 Codex 原生配置注册 stdio 入口。以下命令写入运行该 app-server 的 Codex 配置,工具按原生 MCP 调用元数据确定所属对话。
16
25
 
17
- ```text
18
- 后端代理或其他兼容客户端 → MCP 接口 → 独立后台任务服务 → 命令进程与日志
19
- ↓
20
- 任务状态与完成通知
21
- ↓
22
- 宿主适配 → 结果投递或续跑
26
+ ```bash
27
+ codex mcp add claudex_background -- "$(command -v node)" "$entry" mcp "$state_dir"
23
28
  ```
24
29
 
25
- - 独立项目提供任务启动、状态查询、日志读取和取消能力,持有进程、任务标识、持久化记录及资源清理责任。
26
- - MCP 接口按兼容客户端设计。客户端身份、任务归属和工作目录采用明确的输入或配置约定;Codex 专用元数据的解释放入宿主适配。
27
- - 完成通知与宿主相关的对话续跑分开设计。自动续跑所需的身份、权限、投递确认、去重和失败恢复由适配契约明确,并在独立项目中验证。
28
- - 安装包、服务生命周期、配置和数据目录由独立项目管理,支持使用者独立部署。路径、shell、后端地址和认证从配置或运行环境取得。
29
- - Claudex Web 保留现有网页交互终端、后端原生后台终端的 `/stop` 清理入口,以及通用 MCP 服务状态和工具结果展示;这些能力沿用现有行为契约。
30
+ ## 任务与结果
31
+
32
+ 输入区左侧的终端图标显示当前对话正在运行的任务数,点击打开右上角的工作区概览。概览中的「后台终端」列表支持单独停止任务,点击任务在右侧查看终端收到的标准输出与标准错误。命令重定向到文件的内容保存在对应文件中。输出跟随任务刷新,任务结束后保留最后一段。Codex 任务面板显示最后 8 KiB,可从「完整日志」下载已保存的输出。Claude Code 的原生后台 Bash 使用相同入口。
33
+
34
+ - `background_start(command, title, timeout_ms?)` 在当前对话的实际目录执行 shell 命令,返回任务 ID。相同会话的同一工具调用 ID 对应同一任务。
35
+ - `background_list()` 列出当前对话的任务、执行状态与结果投递状态。
36
+ - `background_read(job_id, offset?)` 读取任务状态、退出码及输出。省略字节偏移时取末尾,从零开始按 `nextOffset` 翻页可读取保留的日志。每页最多 32 KiB,每个任务最多保留 64 MiB;超过上限时记录 `logTruncated`。
37
+ - `background_cancel(job_id)` 停止 MCP 任务的 Unix 进程组,或调用 Codex 原生终端停止接口,并抑制尚未提交的续跑。网页 `/stop` 可一并停止当前对话的原生终端及 MCP 任务。Claude Code 使用 SDK 的 `stopTask`。
30
38
 
31
- ## 后续实施与验收
39
+ 任务服务通过私有目录中的 Unix socket 接受本机同用户请求。目录权限为 0700,socket、任务状态和日志权限为 0600。每个状态目录绑定一个 Codex 后端地址。后台服务可在网页桥接关闭后继续工作。原生终端由 Codex app-server 持有,独立订阅用于防止正常会话卸载。任务服务重启后将遗留的运行记录标为中断。
32
40
 
33
- 1. 确定独立仓库与发布边界,审查原型依赖及 GPL-3.0-only 代码的许可证义务。
34
- 2. 提取任务服务与 MCP 接口,将网页桥接依赖和宿主专用逻辑整理为明确的适配接口,编写独立安装与配置文档。
35
- 3. 使用临时目录、模拟宿主和隔离任务,验证启动、成功、失败、超时、取消进程树、日志分页、重复调用、服务重启及状态恢复。
36
- 4. 验证兼容客户端和多种独立配置;在未安装、未启动 Claudex Web 的环境中完成任务执行、查询、读取日志及取消。
37
- 5. 对完成通知和可选续跑验证断线恢复、重复投递、响应丢失、宿主忙碌及任务归属隔离,再确定独立项目的交付范围。
41
+ 成功、非零退出及超时都产生终态。服务等待原对话空闲后恢复原生会话,用 `turn/start` 投递退出状态、输出文件与日志摘要,并持有订阅直到续跑轮次结束。同次请求用 `additionalContext` 提醒模型向用户汇报。对话按原生轮次顺序显示续跑和模型回复。续跑失败、中断或模型没有输出正文时,对话直接显示任务结果与输出入口。模型已读取的终态和已取消任务会退出待投递队列。提交响应丢失时进入 `uncertain`,服务按通知 ID 核对原对话历史;任务工具仍可主动读取结果。
38
42
 
39
- 独立仓库创建、代码迁移与原分支清理属于后续实施阶段,进度以对应仓库和实际验证记录为依据。
43
+ ZCode 的 Bash 结束后先入队并保存面向模型的任务通知,再由运行时执行对应会话。通知包含任务标识、状态、输出文件和摘要,由独立来源标记区分人工输入。Claudex Web 使用 Codex 原生轮次请求中的结构化工具结果和应用上下文分别承载任务事实与汇报要求。[ZCode 后台调度](https://github.com/zai-org/ZCode/blob/fec975905a2abd4c07e35c40d51fa097a2258ec9/apps/zcode-cli/packages/core/src/runtime/methods/runtime-command-queue.ts) · [ZCode 通知持久化](https://github.com/zai-org/ZCode/blob/fec975905a2abd4c07e35c40d51fa097a2258ec9/apps/zcode-cli/packages/core/src/runtime/methods/background-notifications.ts) · [Codex 原生提交](https://github.com/openai/codex/blob/rust-v0.170.0/codex-rs/app-server/src/request_processors/turn_processor.rs)