@hjd-hitsz/claudex-web 4.0.1 → 4.1.1
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.
- package/CHANGELOG.md +71 -0
- package/README.md +33 -55
- package/build-info.json +4 -4
- package/client/dist/app.js +95 -95
- package/client/dist/document-editor.js +96 -93
- package/client/dist/style.css +1 -1
- package/docs/architecture/backends.md +2 -0
- package/docs/architecture/behavior.md +34 -6
- package/docs/architecture.md +42 -5
- package/docs/deployment.md +34 -14
- package/docs/development.md +31 -4
- package/docs/images/desktop-dark.png +0 -0
- package/docs/images/desktop-light.png +0 -0
- package/docs/images/mobile.png +0 -0
- package/docs/releases/v4.1.0.md +21 -0
- package/docs/releases/v4.1.1.md +19 -0
- package/docs/versioning.md +10 -0
- package/package.json +25 -8
- package/packages/translation-engine/LICENSE +674 -0
- package/packages/translation-engine/README.md +69 -0
- package/packages/translation-engine/bin/tokenizer-linux-x64 +0 -0
- package/packages/translation-engine/bin/translate.mjs +29 -0
- package/packages/translation-engine/native/build.mjs +15 -0
- package/packages/translation-engine/native/tokenizer.c +73 -0
- package/packages/translation-engine/package.json +29 -0
- package/packages/translation-engine/src/catalog.mjs +103 -0
- package/packages/translation-engine/src/cpu-runtime.mjs +90 -0
- package/packages/translation-engine/src/download.mjs +94 -0
- package/packages/translation-engine/src/index.mjs +70 -0
- package/packages/translation-engine/src/inference.mjs +177 -0
- package/packages/translation-engine/src/model-store.mjs +197 -0
- package/packages/translation-engine/src/tokenizer.mjs +77 -0
- package/packages/translation-engine/src/worker.mjs +83 -0
- package/scripts/install-services.mjs +5 -4
- package/scripts/start-backend.mjs +7 -1
- package/server/src/application.mjs +40 -5
- package/server/src/backends/claude/catalogue.mjs +5 -3
- package/server/src/backends/claude/execution-session.mjs +7 -1
- package/server/src/backends/claude/messages.mjs +2 -1
- package/server/src/backends/claude/provider-environment.mjs +6 -4
- package/server/src/backends/claude/sessions.mjs +1 -0
- package/server/src/backends/claude/worker-client.mjs +13 -6
- package/server/src/backends/claude/worker-location.mjs +12 -0
- package/server/src/backends/cli-installation.mjs +28 -13
- package/server/src/backends/cli-package.mjs +116 -0
- package/server/src/backends/codex/adapter.mjs +2 -0
- package/server/src/backends/codex/events.mjs +1 -1
- package/server/src/backends/codex/token-usage.mjs +140 -0
- package/server/src/backends/manager.mjs +87 -21
- package/server/src/backends/provider-presets.mjs +1 -1
- package/server/src/backends/providers.mjs +6 -3
- package/server/src/backends/storage.mjs +7 -3
- package/server/src/config.mjs +7 -0
- package/server/src/http/maintenance.mjs +28 -0
- package/server/src/http/router.mjs +20 -2
- package/server/src/server.mjs +9 -0
- package/server/src/service-maintenance-worker.mjs +124 -0
- package/server/src/service-maintenance.mjs +222 -0
- package/server/src/summary-translation.mjs +42 -53
- package/server/src/token-usage-reconciliation.mjs +105 -0
- package/server/src/token-usage.mjs +208 -0
- package/server/src/translation-service.mjs +133 -0
|
@@ -92,6 +92,8 @@ Claude Code 的附加能力通过后端扩展描述提供,采用显式命令
|
|
|
92
92
|
|
|
93
93
|
列表与搜索汇总每页后端错误。一个后端读取失败时,保留同一范围内已经显示的该后端对话,其余后端照常更新;侧栏和搜索提供实际错误与重试。搜索查询、归档范围、页面卸载与列表修订共同隔离迟到结果。
|
|
94
94
|
|
|
95
|
+
外部供应商的主模型及 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 统一由 `providerModelEnvironment` 根据本轮模型生成。初始化与持续会话每轮提交共用这份映射,通过原生会话级设置同步生效后再提交输入;新启动的子代理按当前映射选择模型,已经运行的任务继续归属其原会话与模型。
|
|
96
|
+
|
|
95
97
|
## 验证入口
|
|
96
98
|
|
|
97
99
|
`npm run test:backends` 使用指定的真实 Claude Code 可执行文件、临时配置与会话、隔离 Messages 服务执行原生历史、目录、项目指令、工具及运行生命周期回归,日志和 CLI 版本保存在 `.cache/backend-acceptance`。`claude-runtime-restart.mjs` 通过真实 systemd 用户服务验证网页代理 SIGKILL、独立 cgroup、相同原生 PID 和后台 shell 保留、重连及忙时停止拒绝;`claude-worker-upgrade.mjs` 验证代码与配置更新代际及空闲替换。`npm run test:backends:live` 使用显式配置的模型服务验证模型调用,环境条件与命令见[开发者指南](../development.md#双后端开发与验收)。
|
|
@@ -12,6 +12,10 @@ Claude 原生思考按所属 API 消息的内容块顺序保留独立标识,
|
|
|
12
12
|
|
|
13
13
|
## 双后端与供应商
|
|
14
14
|
|
|
15
|
+
网页安装与启动支持尚未安装任何原生 CLI 的环境,登录后可在设置中安装所需后端。新建 Codex 用户服务通过已有后端启动脚本运行,缺少 CLI 时由 systemd 重试;安装完成后启动原生 app-server,桥接按原连接流程恢复就绪状态。
|
|
16
|
+
|
|
17
|
+
CLI 一键安装以当前平台原生组件完整下载为前提,完成后安装同一清单版本并校验实际 CLI。下载失败保留已有安装及版本,提供重试。CLI 检测与安装失败在设置中显示简短提示,原始错误保留在默认收起的详情中,展开后限制高度并允许长路径换行。操作成功后清理对应错误和诊断。
|
|
18
|
+
|
|
15
19
|
自定义供应商在列表的编辑按钮旁提供删除按钮;请求期间禁止重复操作,成功后刷新供应商及模型目录并关闭该供应商的编辑表单,失败保留列表及编辑内容并显示错误。默认供应商通过清空 API Key 停用。
|
|
16
20
|
|
|
17
21
|
项目模型偏好在所属后端离线时仍可读取和保存;保存成功向所有页面广播所属后端的完整项目偏好,保存失败保留原数据并允许重试。依赖执行状态的目录创建、单文件撤销、整理核对和子代理消息读取在后端就绪后执行。整理占用期间,两端统一暂停开始轮次、补充输入、审查、历史回退和再次整理,历史与项目偏好保持可读。
|
|
@@ -48,17 +52,19 @@ Claude Code 的模型会话和后台任务由独立执行服务持有。网页
|
|
|
48
52
|
|
|
49
53
|
图片及其他附件随所属对话在当前页面内保留,切换到其他对话再返回时恢复原附件列表;尚未首次发送的新对话同样恢复。移除附件后保持移除,首次发送创建实际对话时迁移附件草稿。一次选择多个文件时,在文件选择框重置前取得全部文件,并将每个文件的读取绑定到原草稿。异步文件读取完成后更新原草稿,发送失败保留附件供重试,发送成功仅清理已提交附件,保留等待期间新增的附件。
|
|
50
54
|
|
|
51
|
-
|
|
55
|
+
正文输入即时更新独立草稿订阅,按对话持久保存。正文编辑区默认容纳两行,随正文、代码及公式的实际高度自动增高,到达可用空间上限后在内部滚动。上边缘公共手柄支持向上拖动增高、方向键调节及双击或 Home 恢复自动高度,手动高度按可用空间比例保存并跨刷新恢复;展开入口打开居中的编辑窗口,复用同一文档实例和撤销栈;底部保留放大前的正文预览、输入框轮廓、工具栏及原有尺寸,页面布局与阅读位置保持连续,背景预览通过隔离节点提供只读展示;通过关闭按钮、Esc 或收起入口返回紧凑输入,保留草稿、选区及原高度选择。编辑窗口复用公共窗口手柄,支持拖动、键盘调节、复位及尺寸偏好恢复。窄屏、缩放及附件变化重新限制高度,发送工具栏保持可见。普通正文和同级列表完整显示,光标与选区由浏览器原生维护;滚动后继续输入时定位到真实编辑位置。加载期间的文本、焦点及完整选区交接给文档编辑器,对话切换后旧实例只清理自己的输入适配。Ctrl+Enter 与发送按钮走同一提交入口,Enter 保留换行;组合输入确认保持正常编辑。输入期间共享状态快照稳定,长历史和文件面板保持渲染隔离。
|
|
52
56
|
|
|
53
|
-
正文使用 Markdown 富文本编辑,支持 CommonMark、GFM(表格、任务列表、删除线、自动链接及脚注)、数学公式。Mermaid 以普通代码块输入,HTML 保留源码。用户直接编辑排版后的正文及表格单元格,选区格式工具提供常用操作;持久化和发送使用 Markdown
|
|
57
|
+
正文使用 Markdown 富文本编辑,支持 CommonMark、GFM(表格、任务列表、删除线、自动链接及脚注)、数学公式。Mermaid 以普通代码块输入,HTML 保留源码。用户直接编辑排版后的正文及表格单元格,选区格式工具提供常用操作;持久化和发送使用 Markdown。纯文本 Markdown 粘贴直接插入原生文档节点,保留代码语言、公式及表格,选区替换和光标落点遵循粘贴位置;块后保留正文续写位置,一次撤销恢复整次粘贴。富文本副本保留其文档结构,代码内部保留字面内容。编辑器实例及撤销栈归当前对话的输入组件所有,切换对话时销毁;异步初始化及迟到输入回调按挂载生命周期隔离。输入后立即发送读取即时草稿,文件引用和快捷命令继续使用统一入口。编辑器和运行时资源从本站加载,加载期间保留可编辑的 Markdown 文本框。
|
|
54
58
|
|
|
55
59
|
提交快照包含正文、附件、文件引用和全部批注。失败保留可重试内容,成功只清理与已发送快照一致的草稿;请求等待期间的新输入或批注继续保留。运行中补充使用当前轮次通道,新的轮次带上当前模型、有效思考强度、速度模式和统一执行策略。
|
|
56
60
|
|
|
57
61
|
新对话的模型和思考强度按项目保存。已有对话打开、刷新及重连时,从后端对话读取与恢复结果取得该对话的模型和思考强度;项目默认选择仅用于新建对话,恢复请求期间的手动调整继续保留。服务端项目设置是跨浏览器恢复来源,本地缓存和待写入选择用于即时交互及失败重试;迁移只补齐服务端缺失值。同项目新建沿用当前有效选择,跨项目恢复目标选择。模型切换保持支持的强度,不支持时由领域规则选择最近的可用档位;迟到恢复保留期间的手动调整。
|
|
58
62
|
|
|
63
|
+
输入区模型入口按当前选项显示完整的供应商与模型名称,宽度随内容和工具栏可用空间调整,超长名称允许换行。原生下拉选择、键盘操作和禁用状态保持一致,窄屏及页面缩放后发送与停止按钮保持可见。
|
|
64
|
+
|
|
59
65
|
思考强度通过带离散档位圆点的胶囊滑块调整,标题旁显示当前档位,滑块下方省去重复的档位文字。输入框的紧凑入口展开独立面板,模型弹窗复用同一控件;拖动、点击轨道和方向键使用后端返回的支持档位。模型选择和速度模式分别使用各自入口。
|
|
60
66
|
|
|
61
|
-
执行策略统一为完全访问。快捷命令注册与参数解析集中在 `features/commands
|
|
67
|
+
执行策略统一为完全访问。快捷命令注册与参数解析集中在 `features/commands`,菜单、按钮和键盘使用同一入口。`/` 在输入开头、空格及换行后提供命令与技能建议。中途确认网页命令时仅移除当前查询,保留前后正文及附件,执行失败恢复完整草稿;原生命令将已有正文作为参数提交,原生技能将命令放到正文前等待发送。开头命令继续读取后续参数。18 项网页通用命令保留统一用例,Claude Code 当前目录的原生附加命令由实际运行时目录提供。`/init` 保留并打开已有目录指令文件;`/goal` 使用实际目标接口;`/stop` 清理当前对话全部后台终端分页。Claude Code 每次提交按祖先到当前目录读取 AGENTS 项目指令,同目录优先 `AGENTS.override.md`,保留完整原文、路径与作用域;本轮快照替换此前快照,修改和删除在下一轮生效,原生 `CLAUDE.md` 持续适用。完整支持范围见[命令覆盖记录](../cli-command-coverage.md)。
|
|
62
68
|
|
|
63
69
|
所有公式使用 `$$公式$$`,同一行及换行输入统一生成当前段落内的行内公式,光标停在公式后并可继续正文。单美元符号作为普通文本。闭合前保留可编辑源码,公式可双击或通过键盘重新编辑,修改后以 `$$` 再次闭合。粘贴、草稿恢复和发送沿用同一双美元符号语法;代码块与行内代码保留美元符号源码。
|
|
64
70
|
|
|
@@ -119,7 +125,7 @@ flowchart LR
|
|
|
119
125
|
|
|
120
126
|
## 消息展示与导航
|
|
121
127
|
|
|
122
|
-
|
|
128
|
+
领域层按轮次组合消息与工作过程,用户提问和中途补充保留独立消息;同轮补充同时按原始消息顺序收入工作过程,摘要行直接显示消息正文,短消息完整可读,长消息省略并可展开正文与附件,实时预览继续显示最新工作活动;工作过程默认折叠,运行时展示最新有效活动,结束后固定耗时。Codex 的 `delivery: async` 中途回复始终收入同轮过程,即使阶段为 `final_answer`;异步投递保留待答提问,回复操作只归属真实最终回答。最终回答的复制及分支按钮位于本轮文件汇总之后,实时生成和历史恢复遵循相同顺序。
|
|
123
129
|
|
|
124
130
|
全部历史保持连续可滚动。打开对话和回到最新时定位到真实底部,包括消息底部留白;自动跟随期间,输入框恢复、图片、图表及容器变化继续贴底。上翻或目录跳转后保留阅读位置,切换对话清理监听和待处理帧。
|
|
125
131
|
|
|
@@ -127,7 +133,7 @@ flowchart LR
|
|
|
127
133
|
|
|
128
134
|
消息目录以实际独立用户消息为条目,支持搜索、键盘、当前位置高亮和跳转;默认缩略标记数量受控。目录和详情卡片各有稳定位置,主消息滚动条贴工作区最右侧。新建按钮在侧栏收起和窄屏下保持可用。
|
|
129
135
|
|
|
130
|
-
|
|
136
|
+
思考内容翻译默认关闭,设置开关保存在网页服务。启用后准备本地模型,完整消息的完成事件或已结束历史触发翻译;运行中会话的历史摘要缺少消息状态时,以同轮后续非用户活动确认其已结束,当前流式消息继续等待完成事件,标题优先,正文在折叠期间也可准备。流式阶段及翻译等待期间展示原文,成功后提供原文与译文切换。Markdown 解析只提取普通文字送入引擎,代码、公式与链接目标沿用源码。译文按模型版本和完整原文在同一标签页的内存与会话存储中复用,失败可重试;卸载、关闭翻译或模型切换后忽略迟到结果。模型下载、存储及离线迁移见[部署文档](../deployment.md#思考内容翻译)。
|
|
131
137
|
|
|
132
138
|
## 工作区、文件与终端
|
|
133
139
|
|
|
@@ -149,22 +155,32 @@ Claude Code 的原生后台任务按所属会话保存任务标识、类型、
|
|
|
149
155
|
|
|
150
156
|
## 子代理与共享渲染
|
|
151
157
|
|
|
158
|
+
Claude 子代理原生历史中,带有 `isSidechain=true` 与 `agentId` 的任务输入以侧链来源建立轮次,即使继承 SDK 入口和父轮次 `promptId`。主对话内部通知继续按其来源字段过滤,子代理任务、工具和回答完整恢复。
|
|
159
|
+
|
|
152
160
|
子代理按对话 ID 合并不同协议版本的活动,主对话工作过程与详情概览共用入口。只读详情复用完整历史、消息和工作过程,消息路径使用子代理的实际目录。切换代理或关闭详情清理监听并丢弃迟到结果。
|
|
153
161
|
|
|
154
162
|
桥接通过父对话协作调用与子代理接收记录核对初始任务和后续消息,按接收者及调用 ID 隔离,保留重复发送并避免原生输入重复。标记为加密的正文在桥接返回前替换为“消息内容已加密”。发送成功而接收记录尚未落盘时,对整条正文符合 Fernet 封包布局的内容立即使用同一状态,检查 Base64URL 编码、版本、固定字段长度及加密块长度;接收后的结构化标记继续覆盖其他密文格式。明文保留原文,包括正文中引用的封包及仅包含相似前缀的文本。失败保留已有内容并可重试。
|
|
155
163
|
|
|
156
164
|
消息、工具结果、子代理及文件预览共用 Markdown 和 HTML 白名单过滤。安全的标题、对齐、图片、`picture` 及折叠内容统一处理,代码保留源码。相对资源以所属对话或文件目录解析;图片失败、主题切换及迟到读取均有隔离处理。
|
|
157
165
|
|
|
158
|
-
图片按统一等比缩略图展示,点击可查看大图,Esc、关闭按钮和空白区域退出后恢复焦点。Mermaid
|
|
166
|
+
图片按统一等比缩略图展示,点击可查看大图,Esc、关闭按钮和空白区域退出后恢复焦点。Mermaid 从本站按需加载,严格模式绘制,默认使用 13px 字号与紧凑节点间距,按可用宽度等比缩小,长图默认在受限高度内滚动,工具栏的四角展开图标可显示完整高度,再次点击四角收起图标恢复紧凑高度,悬停及可访问名称分别为“展开图表”和“收起图表”;消息与文件预览共用展示规则。流程图方向菜单以当前实际布局选中横向或纵向,可选择另一方向进行切换,切换时恢复默认缩放,子图内部的方向声明保持原样。缩放按钮以 25% 为一步,在 50% 至 800% 之间调整,点击百分比复位;图表聚焦后支持 `+`、`-`、`0`,Ctrl+滚轮或触控板捏合缩放。方向、缩放与展开状态归当前图表组件,流式更新与主题重绘保留选择,卸载后恢复默认。查看及复制源码始终使用消息原文。流式未完成或解析失败时保留源码,清理临时节点并隔离旧主题及旧源码结果。
|
|
159
167
|
|
|
160
168
|
## 账户、登录与外观
|
|
161
169
|
|
|
170
|
+
已有 Codex 对话缺少本地用量快照时,首次读取从原生持久记录补录并保存。分页分支按原生历史引用及截断字节边界恢复对应上下文统计,后续打开直接读取快照。归档对话跳过补录。
|
|
171
|
+
|
|
172
|
+
桥接每次启动后,在后端就绪时后台分页核对全部归档和未归档对话。归档对话删除已保存的快照,未归档对话只补录缺少的统计。核对过程、完成数量和读取错误可通过只读维护状态查询。
|
|
173
|
+
|
|
174
|
+
创建末尾分支时继承请求发出前的来源用量快照,之后按新对话独立持久化和更新。指定轮次分支仅继承该轮次的已知统计,统计暂缺时等待分支回复上报。原生返回及分支实时上报的用量优先于继承值;Claude 较早轮次分支清除从来源索引复制的最新用量。
|
|
175
|
+
|
|
162
176
|
对话完成通知默认开启,浏览器已有的手动关闭偏好保持有效。开关表示通知偏好,浏览器尚未授权时提供“允许系统通知”按钮,由用户点击请求权限;已有授权直接生效。正常状态仅展示开关,权限被拒绝、环境不支持及发送失败时显示必要状态。已登录页面观察到活动轮次成功完成后发送一条带对话标题及完成状态的通知;失败、中断、手动整理及历史读取保持各自原有展示。浏览器从桥接活动快照恢复进行中的轮次后可继续接收提醒,刷新和重连恢复已结束历史时保持安静。同源页面通过 IndexedDB 以系统登录用户、对话 ID 与轮次 ID 的唯一主键原子领取提醒,重复事件及多个页面保持一次。发送前重新检查开关、权限和登录用户,关闭提醒立即阻止尚未发送的通知。权限被拒绝、环境不支持及发送失败在设置页明确显示,聊天独立继续。
|
|
163
177
|
|
|
164
178
|
通知点击优先聚焦原页面并打开所属对话,保留其他对话的草稿与文件缓冲区;原页面已关闭时打开新页面并在登录及初始化就绪后恢复目标。导航事件验证通知所属登录用户,页面监听在登录界面同样有效,卸载时清理监听及待导航目标。提醒开关为浏览器偏好,浏览器权限及系统通知设置共同决定展示;在线页面与服务连接负责接收完成事件。
|
|
165
179
|
|
|
166
180
|
Claude Code 原生账户额度来自原生 `get_usage` 控制响应,按真实窗口、重置时间和额外用量单位展示;配置外部供应商时显示外部计费状态,余额以该供应商提供的数据为准。上下文用量按原生 token 记录及上下文查询恢复,与账户额度分别管理。
|
|
167
181
|
|
|
182
|
+
Codex 与 Claude 的所有未归档对话分别在网页配置目录持久保存最近一次收到的完整 token 用量快照,包含累计用量、最近上下文用量及后端实际容量。打开、刷新及桥接重启后通过轻量对话响应读回快照;统计更新优先采用读取期间到达的实时通知。每个对话独立读写,重复值省去写入,并发更新合并为最新快照。归档和删除清除所属统计,归档期间停止采集;恢复归档按普通流程处理,统计暂缺时等待下一次模型回复上报。未归档历史对话首次缺少快照时,按后端原生记录补录。
|
|
183
|
+
|
|
168
184
|
账户额度按后端实际窗口展示。完整读取替换快照,稀疏通知合并已有元数据;并发读取合并,连接、账户与通知版本共同隔离迟到响应。断线或失败保留上次数据并标记待更新。前台、轮次完成、额度重置及恢复连接触发校准;计时器和页面监听随生命周期清理。
|
|
169
185
|
|
|
170
186
|
额度详情默认折叠,以圆环显示窗口及剩余比例,展开后显示方案、额度与同一行的倒计时和重置时间。点击外部、Esc 和账户切换收起详情,布局保持账户行高度。
|
|
@@ -204,3 +220,15 @@ Claude Code 网络代理在设置中提供跟随服务环境、关闭和 HTTP,
|
|
|
204
220
|
设置、搜索、重命名、删除确认、目录选择、技能、插件、模型及命令弹窗,以及图片和批注预览的右下角提供尺寸调节手柄。文件预览、文件差异和子代理详情共用的右侧面板通过左边缘调节宽度。支持鼠标及触控拖动、聚焦后的方向键调节、Shift 加速、双击或 Home 恢复默认。窗口手柄支持 Enter 或空格复位。尺寸按用途分别记忆,关闭重开与刷新恢复;尺寸按可用空间比例适应缩放和窄屏,并受当前视口边界约束。详情宽度同步调整聊天与输入区域的避让空间,拖动保留文件编辑和批注内容。项目侧栏、终端高度、终端列表及各类多行表单输入框使用同一套尺寸手柄。默认显示轻量短标记,悬停时增强、拖动时保持高亮,键盘焦点仅围绕局部标记显示。透明操作区与标记分离,方向分别表达调宽、调高或双向调整;失焦、取消或释放捕获结束拖动反馈。输入框保留原有字段、内容与禁用状态,双击或 Home 恢复自动高度。
|
|
205
221
|
|
|
206
222
|
上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
|
|
223
|
+
|
|
224
|
+
## 网页更新与重启
|
|
225
|
+
|
|
226
|
+
设置中的“更新与重启”显示当前版本、npm 最新稳定版与检查错误。桥接启动时及每小时自动检查,网页发现更新提供设置入口。npm 全局安装可更新并重启,源码部署使用源码更新流程。重启服务在当前版本下同样可用,操作要求当前进程属于安装的 systemd 用户服务。整个网页服务进程重启,网页交互终端随之结束,原生后端继续按各自生命周期执行。独立维护任务持久记录进度,重复操作合并,安装与启动失败提供错误及重试。新包先在隔离目录安装并验证,替换后启动失败恢复原包。网页重连后保留草稿和文件编辑,用户保存编辑后主动刷新页面加载新资源。
|
|
227
|
+
|
|
228
|
+
更新及重启请求遇到活动轮次、后台任务、排队输入、待答提问、内部命令或上下文整理时,结束本次操作并短暂提示用户结束任务后重试。提示五秒后关闭,用户稍后重新发起操作。切换阶段暂停网页提交,避免提交与重启竞争。重启成功后网页显示“服务已重启,请刷新网页”,用户自行刷新。
|
|
229
|
+
|
|
230
|
+
发现新版本后,侧栏底部显示带版本号的更新入口并标记设置按钮;侧栏收起或窄屏时,顶部显示紧凑更新入口。设置页按更新与重启、模型与服务配置、其他设置、网页登录分组。更新卡片集中显示产品身份和主操作,当前与最新版本在产品名下同行显示,产品图标、版本信息与检查更新、重启服务、更新按钮在卡片中垂直居中并同行排列,空间不足时操作组整体换行,三个按钮保持同行,复用设置页按钮的尺寸和边框,主要更新操作位于右侧,有新版时显示“更新至版本号”,无需更新时显示灰色禁用的“无需更新”,按钮数量与位置保持稳定;检查期间显示进行状态。设置卡片通过间距区分内部内容。其他设置的选项间距保持一致,状态与错误说明紧随所属选项并与选项文字对齐。原生后端的当前版本合并到标题行,正常连接以状态点显示,安装操作失败作为本次设置访问中的短暂提示,重新打开设置跳过历史安装提示,有新版时在按钮直接显示目标版本并允许更新,版本相同或本机更新时保留灰色禁用的“无需更新”按钮;未安装、停用及连接失败保留文字状态。网页主题始终跟随系统。点击更新入口直接打开设置并滚动、聚焦“更新与重启”区域。界面只显示版本、操作与必要状态,检查周期及部署实现保留在部署文档。
|
|
231
|
+
|
|
232
|
+
维护任务的持久结果用于状态核对,操作提示归属当前设置访问。首次加载、刷新及重新打开设置跳过历史完成和失败提示;当前访问发起的操作按任务开始时间确认结果并只显示一次。关闭设置清除提示并使在途请求的后续反馈失效,后台任务继续按真实状态执行。代理保存反馈五秒后消失,表单错误和实际连接、下载故障按各自当前状态提供处理入口。
|
|
233
|
+
|
|
234
|
+
运行与加载状态使用静态图标,任务进度与耗时按实际数据更新。等待期间省去循环旋转和呼吸动画,使稳定内容仅随进度变化重新绘制;任务完成后清除运行提示并停止对应计时。
|
package/docs/architecture.md
CHANGED
|
@@ -35,7 +35,17 @@ flowchart TB
|
|
|
35
35
|
- **原生后端**:Codex app-server 与 Claude Code 各自保存对话、轮次、标题、模型任务与工具记录,是历史恢复的事实来源。
|
|
36
36
|
- **Claude 独立执行服务**:持有 Claude SDK 进程、活动轮次、待答提问、持续输入与后台任务。网页桥接关闭时只断开本机连接,重新连接读取同一执行服务的快照;执行服务本身故障后按原生进程身份和持久记录核对恢复。
|
|
37
37
|
- **桥接数据目录**:项目模型选择、未分类工作目录、后端连接及供应商配置、认证会话、维护凭据、证书和 Claude 网页索引,统一保存到 `CLAUDEX_WEB_CONFIG_DIR`(默认 `$XDG_CONFIG_HOME/claudex-web`,未设置 XDG 时为 `~/.config/claudex-web`);受限文件采用权限控制及原子写入。
|
|
38
|
+
- **模型数据目录**保存翻译模型、原生分词组件及版本校验记录,固定使用当前用户的 `~/.local/share/claudex-web/models`。启停偏好归桥接配置,模型数据独立于 npm 安装与程序升级。
|
|
38
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` 提供各后端进度,服务关闭取消核对请求后等待存储排空。
|
|
39
49
|
|
|
40
50
|
## 2. 源码组织与依赖方向
|
|
41
51
|
|
|
@@ -68,6 +78,7 @@ server/src/
|
|
|
68
78
|
workspace/ 共用文件与网页终端
|
|
69
79
|
*.mjs 认证、TLS、文件、标题、配置等独立服务
|
|
70
80
|
shared/ 跨端纯逻辑:文件类型、整理状态、传输限制
|
|
81
|
+
packages/translation-engine/ 独立翻译子项目:模型存储、分词与 CPU 推理
|
|
71
82
|
scripts/ 构建、架构检查、测试、安装与发布工具
|
|
72
83
|
tests/ 组件、浏览器、发行包与架构回归
|
|
73
84
|
```
|
|
@@ -168,6 +179,14 @@ sequenceDiagram
|
|
|
168
179
|
|
|
169
180
|
`http/static.mjs` 按实例维护文件内容和 gzip 缓存,按文件修改时间刷新。路由支持固定入口、图标及根部 JavaScript/CSS 分块。静态缓存与后端运行状态分别归属自己的对象。
|
|
170
181
|
|
|
182
|
+
### 本地翻译服务
|
|
183
|
+
|
|
184
|
+
`translation-service.mjs` 持有启停偏好、准备进度、引擎实例和修订号,通过公开包入口调用 `packages/translation-engine`。HTTP 处理器经参数取得翻译与设置操作。子项目只依赖自身及外部包,提供独立 CLI 与 `prepare`、`translate`、`close` 接口,模型目录由调用方传入。模型下载、校验、分词及 ONNX 推理归独立子进程,桥接主线程继续处理网页请求。
|
|
185
|
+
|
|
186
|
+
首次启用才创建引擎和下载模型。安装锁合并并发下载,临时目录完成校验后原子替换版本索引。已安装文件在准备时校验,损坏后重新安装。关闭时取消下载、结算在途请求并释放独立子进程与分词进程,已安装版本保留。修订号隔离关闭或重启前的迟到结果。
|
|
187
|
+
|
|
188
|
+
前端 `application/translation.js` 持有设置同步与下载状态轮询,组件依据已完成消息安排翻译;工作过程按消息状态和同轮活动顺序识别中途加载的已结束摘要,轮次运行状态继续独立维护。基础设施解析 Markdown 并翻译普通文字节点,源格式、代码、公式和链接目标保留。会话缓存按模型版本及完整原文隔离,等待期间显示原文,译文完成后允许切换。
|
|
189
|
+
|
|
171
190
|
### 4.2 桥接模块
|
|
172
191
|
|
|
173
192
|
`backends/manager.mjs` 是公共桥接的组装与路由入口,组合固定的 Codex 和 Claude 适配器、工作区服务与连接配置。浏览器继续使用现有 JSON-RPC 名称,原生协议和运行状态由所属适配器解释。管理器统一组装网页及维护连接的快照。
|
|
@@ -207,6 +226,8 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
207
226
|
|
|
208
227
|
`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 启用,清空后停用,运行时读取同时校验启用状态。
|
|
209
228
|
|
|
229
|
+
`cli-package.mjs` 从上游 npm 清单取得版本和当前平台的原生依赖,先将原生包作为必需依赖安装到临时目录,完成下载与 npm 完整性校验,再以同一固定版本执行全局安装。临时目录在成功与失败后均清理,全局安装复用校验缓存,显式包含可选依赖并启用安装脚本。版本查询和安装共同使用网页 Node.js 的 PATH。下载失败结束操作,已有全局安装继续保留。最终 CLI 版本须与安装清单一致。安装状态分别保存简短提示与原始诊断,设置页按需展开有高度限制、可换行的错误详情。
|
|
230
|
+
|
|
210
231
|
`application/backends.js` 汇总 Codex 原生模型与 Claude 供应商模型,选择键包含后端、供应商和模型。输入区的 `model-select.jsx` 只负责呈现与调用动作。新对话依据所选模型确定运行时;已有对话继续使用所属运行时,Claude 对话空闲时可以切换供应商及模型。打开对话以其已保存的供应商和模型恢复选择。顶部与侧栏复用 `app/backend-badge.jsx` 仅显示图标,领域层按对话资源标识确定后端,当前新对话采用已选后端;显示归属与供应商名称独立。
|
|
211
232
|
|
|
212
233
|
默认 Codex 对话保留原 ID,Claude 资源使用 `backend:claude:<原生 ID>`;桥接只转换协议中的资源字段,工具参数和用户正文保持原样。历史读取、原生命令和提问响应按资源归属路由,两个后端的同名原生 ID 相互隔离。
|
|
@@ -225,7 +246,9 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
225
246
|
|
|
226
247
|
文件引用查询按对话所属后端路由:Codex 的 `fuzzyFileSearch` 继续由原生 app-server 处理,Claude Code 由 `catalogue.mjs` 调用原生 `file_suggestions`,复用 CLI 的文件索引及建议。持续会话和目录查询会话在初始化时预热原生索引;目录、供应商配置与对话标识限定查询归属,前端统一展示文件和目录。验证同时核对已有 Codex 路径、Claude 原生结果和真实工作区的查询表现。
|
|
227
248
|
|
|
228
|
-
|
|
249
|
+
新增供应商及预置 DeepSeek 默认使用原生 Message API,原生请求保留中途系统消息;自定义模型显式配置的能力优先于 CLI 模型目录。历史自定义供应商缺少协议字段时沿用原有兼容模式,编辑保存保留其实际协议。Message API 兼容模式使用顶层 `system` 承载系统上下文,用户正文与工具调用继续保留原始内容块和顺序。协议转换在首次请求前完成,并保留原生思考控制、结构化输出及辅助评估请求;处理规则与原生接口依据见双后端产品契约。文件变更通过工具钩子记录前后内容,撤销复用现有补丁校验。能力声明描述模型参数、外部事实和原生扩展,通用产品入口使用统一契约;原生历史跨运行时交接属于独立设计。
|
|
250
|
+
|
|
251
|
+
外部供应商的模型环境由 `provider-environment.mjs` 生成,主模型与 Opus、Sonnet、Haiku 三个原生别名随本轮选择一起更新。初始化与持续会话共用映射,运行时等待原生模型和设置更新完成后提交输入,设置失败按本轮错误结算并允许重试。
|
|
229
252
|
|
|
230
253
|
## 5. 功能模块与共享展示
|
|
231
254
|
|
|
@@ -235,6 +258,8 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
235
258
|
|
|
236
259
|
`features/markdown` 集中提供 Markdown、HTML 白名单、图片、链接、数学公式和 Mermaid。消息、工具结果和文件预览复用同一渲染入口;文件目录由上下文传递,局部组件负责媒体加载与清理。文本安全过滤和路径解析在这里统一维护。
|
|
237
260
|
|
|
261
|
+
Mermaid 的流程图主方向转换归 `domain/mermaid.js`,原始正文保持独立;`mermaid-block.jsx` 持有方向、缩放、展开和源码查看状态,`mermaid-diagram.jsx` 按容器宽度等比绘制并处理图内滚动、键盘及 Ctrl+滚轮缩放。尺寸观察与滚轮监听随组件卸载清理,重新绘制继续隔离旧源码和主题结果。
|
|
262
|
+
|
|
238
263
|
`features/workspace` 把文件树、目录选择、文件编辑、差异、终端和对话详情拆成独立模块。编辑器与文件变更装饰分别封装;显示的删除装饰与实际保存正文分开处理。`context-panel.jsx` 组合概览和子代理详情,主对话切换统一清理选择,编辑缓冲区继续按原主对话保存。
|
|
239
264
|
|
|
240
265
|
`app` 将输入框和错误提示作为底部插槽传入对话布局。对话布局统一提供消息、底部输入和右侧详情的几何边界;桌面展开详情时输入区域避让右侧面板,详情占满工作区高度。文件下载入口归文件面板工具栏,媒体预览组件负责内容展示及加载重试。
|
|
@@ -247,7 +272,7 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
247
272
|
|
|
248
273
|
`features/composer` 管理输入交互;`features/commands/composer-commands.js` 是快捷命令的独立注册表,菜单、按钮和键盘提交走同一解析和执行入口。`domain/commands` 只负责工具命令描述的分类与解析,命令支持范围见[命令覆盖记录](cli-command-coverage.md)。
|
|
249
274
|
|
|
250
|
-
输入区的 `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`
|
|
275
|
+
输入区的 `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` 交付。
|
|
251
276
|
|
|
252
277
|
批注编辑在 `features/annotations`,协议解析在 `domain/annotations.js`,存储和订阅在 `infrastructure/annotation-drafts.js`。选区编辑只更新草稿,统一发送由消息控制器完成。账户详情、侧栏宽度和主题分别保留自己的控件生命周期。
|
|
253
278
|
|
|
@@ -257,15 +282,23 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
257
282
|
|
|
258
283
|
## 6. 样式、加载与分发
|
|
259
284
|
|
|
260
|
-
`style.css`
|
|
285
|
+
`style.css` 是有序样式入口。设置窗口的分组与控件尺寸由 `styles/settings-layout.css` 限定在设置弹窗内,更新卡片及常驻更新入口由 `styles/service-maintenance.css` 持有。`styles/theme.css` 和 `base.css` 定义主题及基础排版,其余按侧栏、导航、消息、批注、文件、终端和弹窗等职责组织;响应式及排版覆盖按入口中声明的顺序应用。移动规则时保持选择器顺序、媒体条件和变量作用域;增加规则优先放到所属模块,修改覆盖顺序时验证全部受影响布局。
|
|
261
286
|
|
|
262
287
|
主页面先加载聊天所需的代码。文件面板和终端通过 `React.lazy` 首次打开时加载,文件面板完成首次加载后保持编辑缓冲区;Mermaid 按图表需求加载本站模块。终端面板持有终端列表及活动选择,每个终端组件独立持有 xterm 实例、输入订阅及尺寸观察,切换保留各实例,桥接拥有进程及恢复缓冲区。网页交互终端统一由桥接工作区服务的 node-pty 持有,浏览器通过独立的 `lan/terminal/*` 接口创建、输入、调整尺寸及结束进程,操作先于后端资源路由处理,与模型后端和启用状态独立。服务直接启动系统登录 shell,每 500 毫秒读取实际 PTY 前台进程名,变更时发送元数据通知;快照及启动事件保存进程名、输出、工作区归属与规范化的绝对启动目录,浏览器按名称选择图标并省去目录和编号。应用状态按启动目录保存面板开关,终端组件按目录恢复运行列表和选中项;跨目录切换隐藏原终端,同目录切换对话或模型后端保留同一终端组件。选中项按目录持久保存,后台目录退出只更新所属选择。面板框架独立持有纵向拖动及高度比例偏好,按实际可用高度、输入区和 CSS 保留空间限制高度;高度变化沿用终端尺寸观察同步 PTY 行数。列表组件独立持有拖动、键盘及相对宽度偏好,CSS 定义默认宽度和容器上限,尺寸变化或卸载时释放指针捕获。切换文件夹、隐藏和重连保留进程及缓冲区;全部进程结束或工作区服务关闭后清理检测计时器。后端代理原生命令与后台任务保持所属运行时的路径。终端的基础样式在挂载入口先于项目样式导入,JavaScript 仍按需加载。Vite 保持单一 CSS 产物和根部 JavaScript 分块,保持第三方样式与项目规则的覆盖顺序。
|
|
263
288
|
|
|
264
|
-
根 `package.json` 与单一锁文件管理 workspaces
|
|
289
|
+
根 `package.json` 与单一锁文件管理 workspaces。翻译子项目的源码、许可证、CLI 与构建后的原生分词器随发行包交付,模型权重、Microsoft 分词运行库和 ONNX Runtime CPU 文件在用户启用后独立下载。
|
|
290
|
+
|
|
291
|
+
npm 分发由独立的 `npm-publish.yml` 工作流监听即时及定时 GitHub 发布工作流的成功结果,以 OIDC 身份上传已公开的 Release 附件。`publish-npm.mjs` 持有附件下载、校验、临时安装、注册表完整性核对与同版本重试;发布时间继续由发布计划和 Release 草稿状态约束,稳定版与预发布分别进入 `latest` 与 `next`。
|
|
292
|
+
|
|
293
|
+
发行白名单包含 `client/dist`、`server/src`、`shared`、命令入口、运行脚本、许可证和构建信息。增加共享运行模块或动态分块时,验证实际打包清单、生产响应和临时全局安装。生产版本来源由 `server/src/version.mjs` 统一读取,网页在构建时固定,桥接在启动时固定;干净标签构建可交付稳定版本或 alpha、beta、rc 预发布版本;发布工具维护版本顺序和 GitHub 成熟度标记,预发布保留稳定下载入口及 Latest。流程见[版本管理](versioning.md)。
|
|
265
294
|
|
|
266
295
|
## 7. 可执行约束与验证
|
|
267
296
|
|
|
268
|
-
|
|
297
|
+
服务安装器创建网页服务时独立于原生 CLI 的安装状态。新建的 Codex 用户服务以当前 Node.js 运行 `scripts/start-backend.mjs`,显式传入网页配置目录、原生目录和连接地址;启动脚本沿用原生 app-server 参数。CLI 缺失时该服务失败后由 systemd 每 5 秒重试,网页继续提供登录、设置和 CLI 安装入口。既有 Codex 服务的保留与新服务的首次启动分别回归。
|
|
298
|
+
|
|
299
|
+
Codex 启动脚本将 WebSocket 连接地址转换为原生 CLI 的 `ws://主机:端口` 监听参数,保留 IPv6 方括号并显式补齐默认端口 80。连接地址的 URL 规范化与原生监听参数构造分别处理,监听入口校验协议、路径、查询参数及片段。回归精确核对命令行和服务生成入口实际提交的完整参数。
|
|
300
|
+
|
|
301
|
+
`npm run architecture:check` 扫描 `client/src`、`server/src`、`shared`、`scripts`、`bin` 和翻译子项目中的 JavaScript、JSX、MJS 与 CSS:
|
|
269
302
|
|
|
270
303
|
1. 单文件最多 **500 行**,计入注释和空行。日常按单一职责组织,接近上限时先拆分,保持格式化后的正常排版。
|
|
271
304
|
2. 检查相对导入、重导出、字符串动态导入和 CSS 导入是否存在,并检查整个源码图的循环。
|
|
@@ -281,6 +314,8 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
281
314
|
- 浏览器测试使用生产构建和隔离数据,验证真实布局、键盘、焦点、媒体、动态加载及刷新恢复。
|
|
282
315
|
- 发行包测试在临时 npm prefix 安装包,验证共享模块、分块资源、无 Git 版本来源和服务配置生成。
|
|
283
316
|
|
|
317
|
+
单元与发行包测试的控制台日志由 `tests/helpers/test-console.mjs` 在模块加载前统一送入 stderr,Node.js 从独立文本流生成日志事件,stdout 保持二进制测试事件传输。该隔离由公共 npm 测试入口持有,回归覆盖 Unicode 日志、并发输出及真实失败退出状态。
|
|
318
|
+
|
|
284
319
|
浏览器回归按功能风险选择,命令及依赖见[开发者指南](development.md#格式与验证)。修改界面布局或渲染时,在实际消息区和文件面板验证深浅主题、窄屏及规定缩放;修改认证和桥接时使用真实的隔离 HTTPS/WSS 连接。
|
|
285
320
|
|
|
286
321
|
## 8. 扩展流程与设计取舍
|
|
@@ -304,3 +339,5 @@ Codex 设置中的模型显示偏好由网页后端配置持久保存并广播
|
|
|
304
339
|
上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
|
|
305
340
|
|
|
306
341
|
长历史首屏读取最近 100 条消息;首屏全部属于同一轮次且仍有历史时,后续按每页一个完整轮次恢复,减少工具密集对话的串行网络往返。首屏跨轮次时继续使用消息分页,保持短轮次对话的读取效率;两条路径均保留完整历史、轮内顺序、实时更新优先和切换隔离。
|
|
342
|
+
|
|
343
|
+
网页更新由 `service-maintenance.mjs` 持有 npm 稳定版检查缓存及维护操作,启动时和每小时读取官方注册表。认证后的 HTTP 维护接口通过应用装配注入服务。独立 systemd 用户任务执行下载、隔离安装、版本校验、目录替换、网页服务重启与 HTTPS 启动检查,任务状态原子保存在网页配置目录。失败时恢复原安装目录并重启。源码部署提供检查与服务重启,npm 全局部署另提供更新。浏览器应用控制器轮询持久任务状态,页面保留编辑缓冲区,重启成功提示用户手动刷新网页加载新版本资源。
|
package/docs/deployment.md
CHANGED
|
@@ -4,16 +4,15 @@
|
|
|
4
4
|
|
|
5
5
|
## 安装发行包
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
安装最新稳定版本。
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npm install -g
|
|
10
|
+
npm install -g @hjd-hitsz/claudex-web
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
准备 Node.js 24+、npm、
|
|
13
|
+
准备 Node.js 24.5+、npm、OpenSSL、Linux PAM、`pamtester` 和 systemd,完成上方安装后,以运行服务的普通用户启动服务。进入网页后,在设置中安装并启用所需的 Codex 或 Claude Code。
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
npm install -g https://github.com/hjd-hitsz/claudex-web/releases/download/v4.0.1/claudex-web-4.0.1.tgz
|
|
17
16
|
claudex-web service install
|
|
18
17
|
loginctl enable-linger "$USER"
|
|
19
18
|
claudex-web service status
|
|
@@ -26,15 +25,15 @@ curl --cacert "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claud
|
|
|
26
25
|
|
|
27
26
|
### 下载后安装与校验
|
|
28
27
|
|
|
29
|
-
|
|
28
|
+
从[目标版本 Release](https://github.com/hjd-hitsz/claudex-web/releases) 下载 `.tgz` 和同名 `.sha256` 文件,将两者放在同一目录,然后执行以下命令。
|
|
30
29
|
|
|
31
30
|
```bash
|
|
32
|
-
sha256sum -c claudex-web-4.
|
|
33
|
-
npm install -g ./claudex-web-4.
|
|
31
|
+
sha256sum -c claudex-web-4.1.1.tgz.sha256
|
|
32
|
+
npm install -g ./claudex-web-4.1.1.tgz
|
|
34
33
|
claudex-web service install
|
|
35
34
|
```
|
|
36
35
|
|
|
37
|
-
|
|
36
|
+
仓库安装命令按 Git 标签选择最新稳定版源码;Release 的 `.tgz` 包含预构建网页资源,可用于固定版本安装。两种方式均通过 npm 获取运行依赖。
|
|
38
37
|
|
|
39
38
|
文件差异与撤销校验需要服务环境能够运行 `git`。文件变更汇总也支持 Git 仓库以外的目录;“撤销”遇到后续修改冲突时会保留当前文件。升级后先等待当前任务和网页终端结束,再重启网页服务并刷新页面,以使用更新后的功能。
|
|
40
39
|
|
|
@@ -120,9 +119,9 @@ CLI 自动从当前 Node.js 的安装目录、服务 PATH 和用户 `~/.local/bi
|
|
|
120
119
|
|
|
121
120
|
在设置页 Claude Code 的供应商列表中添加服务名称、API 地址、凭据和模型标识。多个供应商共用此 Claude Code 后端。在输入框的模型菜单选择“供应商 · 模型”,新对话会使用对应后端;已有 Claude 对话可在任务结束后更换供应商或模型并继续。
|
|
122
121
|
|
|
123
|
-
API 地址需支持 Messages 请求及工具调用,填写服务基地址,例如 `https://model.example`,请求路径会追加 `/v1/messages
|
|
122
|
+
API 地址需支持 Messages 请求及工具调用,填写服务基地址,例如 `https://model.example`,请求路径会追加 `/v1/messages`;服务有统一路径前缀时将其保留在基地址中。默认选择“Message API”使用原生请求,选择“Message API (兼容)”会将消息中的系统指令合并到顶层 `system`,用于要求这种布局的服务。模型标识和支持的思考强度、速度档位以服务实际配置为准。API Key 保存在服务器,编辑时留空保留原凭据,勾选清除会移除已保存凭据。
|
|
124
123
|
|
|
125
|
-
默认供应商 DeepSeek
|
|
124
|
+
默认供应商 DeepSeek 使用原生 Message API,仅提供 API Key 输入,接口、模型与能力参数由程序按官方文档配置,API Key 初始为空。点击“编辑”,填写 Key 并保存即可启用;编辑后保存空 Key 会清除已保存凭据并停用,模型菜单同步移除该供应商。DeepSeek 使用 `https://api.deepseek.com/anthropic`,预置 `deepseek-flash` 和 `deepseek-v4-pro`,上下文容量为 1,048,576 tokens,思考强度提供 low、high、max,支持思考开关,服务端默认强度为 high;接口与模型依据 [DeepSeek 官方文档](https://api-docs.deepseek.com/guides/anthropic_api/)。自行添加的供应商继续使用上述留空保留及勾选清除规则。
|
|
126
125
|
|
|
127
126
|
自定义模型可填写可选的显示别名,留空沿用原名称。别名随供应商配置保存在服务器,其他浏览器连接同一服务后使用相同名称,实际调用使用原始模型标识。
|
|
128
127
|
|
|
@@ -183,16 +182,19 @@ Claude Code 的任务使用独立执行服务。关闭网页、重启网页服
|
|
|
183
182
|
```bash
|
|
184
183
|
systemctl --user list-units --all 'claudex-web-claude-*'
|
|
185
184
|
journalctl --user -u 'claudex-web-claude-*' -n 100 --no-pager
|
|
185
|
+
journalctl --user -u claudex-web.service -n 100 --no-pager
|
|
186
186
|
```
|
|
187
187
|
|
|
188
|
+
网页提示无法连接 Claude 后台服务时会自动重试;持续失败时检查以上服务状态和日志。网页服务日志保留本地连接失败的详细原因。
|
|
189
|
+
|
|
188
190
|
修改 Claude Code 运行配置或升级程序后,新网页服务自动核对执行服务。仍有对话、提问、整理或后台任务时继续使用原服务,空闲后完成更新。需要完全停止或更换执行服务时,先结束任务、处理待答提问并通过 `/stop` 清理后台终端;普通网页重启只重新连接。前台运行且没有 systemd 用户管理器时,执行服务日志保存在 `CLAUDEX_WEB_CONFIG_DIR/backends/claude/worker.log`。
|
|
189
191
|
|
|
190
192
|
## 升级和回退
|
|
191
193
|
|
|
192
|
-
|
|
194
|
+
更新到最新稳定版并重启服务。
|
|
193
195
|
|
|
194
196
|
```bash
|
|
195
|
-
npm install -g
|
|
197
|
+
npm install -g @hjd-hitsz/claudex-web
|
|
196
198
|
claudex-web service install
|
|
197
199
|
claudex-web service restart-when-idle
|
|
198
200
|
```
|
|
@@ -214,9 +216,21 @@ claudex-web service restart-when-idle
|
|
|
214
216
|
- Codex 每个项目上次选择的模型和思考强度保存在服务所在电脑的 `CLAUDEX_WEB_CONFIG_DIR/project-models.json`。Claude Code 项目选择保存在 `CLAUDEX_WEB_CONFIG_DIR/backends/claude/project-models.json`,迁移服务时分别保留。同项目新建沿用当前选择,跨项目及重新打开网页时恢复目标项目设置,清空浏览器数据后可再次从服务端读取。保存失败时会提示重试。切换模型时保留当前思考强度,目标模型缺少该档位时采用最近的可用档位,距离相同时选较低档。
|
|
215
217
|
- “未分类”对话的文件保存在 `CLAUDEX_WEB_CONFIG_DIR/workspaces/chat-XXXXXX`,首次发送时分配。迁移电脑时随 Claudex Web 配置目录一起保留。
|
|
216
218
|
- 网页配置 `.env` 与新建后端服务使用的 `.env.backend` 位于用户配置目录,迁移时应一并保留;已有后端服务的配置按原部署方式迁移。
|
|
217
|
-
-
|
|
219
|
+
- 思考内容翻译的开关保存在 `CLAUDEX_WEB_CONFIG_DIR/translation.json`,模型保存在独立的用户数据目录。译文缓存在当前标签页的内存与会话存储中,关闭标签页后结束该缓存会话。
|
|
218
220
|
- 自动对话标题使用 Codex 模型,会产生少量额外模型用量。
|
|
219
221
|
|
|
222
|
+
## 思考内容翻译
|
|
223
|
+
|
|
224
|
+
功能默认关闭。在“设置 → 思考内容翻译”开启后,服务器从 Microsoft 组件服务取得模型和分词组件,并通过 npm 获取 CPU 运行库,首次合计下载约 300 MB。校验后保留英译中所需文件,当前版本安装后约占 147 MiB。Linux x64(glibc 2.34+)服务器使用单线程 CPU 推理,客户端可使用任意受支持的浏览器。源码构建需要 C 编译器,预构建发行包已包含分词器。
|
|
225
|
+
|
|
226
|
+
思考消息接收完整后再翻译,流式阶段、下载及翻译等待期间继续显示原文。译文完成后可切换原文与译文,代码、公式及链接目标保持原始内容。翻译正文只在浏览器与本站服务间传输,推理在服务器本地完成。首次下载通过 HTTPS 获取组件目录及 SHA-256,组件文件沿用 Microsoft 返回的下载地址,完整校验后启用。
|
|
227
|
+
|
|
228
|
+
模型固定保存在运行服务的当前用户的 `~/.local/share/claudex-web/models`。目录按模型及版本组织,下载在临时目录中完成,校验后原子切换已安装版本。
|
|
229
|
+
|
|
230
|
+
关闭功能会停止下载并释放引擎,已完成的模型继续保留。重新开启和程序升级复用已安装版本,准备完成后可离线翻译。首次下载失败时,在设置中查看错误并点击“重试”。文件缺失或校验失败时,重试会重新下载完整组件。
|
|
231
|
+
|
|
232
|
+
迁移或离线部署时,将完整模型目录复制到目标服务账户的 `~/.local/share/claudex-web/models`,保留该账户的读取权限,再开启功能。目录中保留 `installed.json`、版本子目录和 `ready.json` 校验记录。模型可在相同 Linux x64 部署间复用。
|
|
233
|
+
|
|
220
234
|
## 故障定位
|
|
221
235
|
|
|
222
236
|
网页不可访问时,先检查网页服务状态、监听端口和主机网络。网页可打开但显示后端未连接时,按当前对话所属服务检查 Codex 后端日志与监听地址,或 Claude Code 可执行文件、原有配置目录和供应商连接。列表中某个后端读取失败时,已有对话会继续显示,按实际错误处理后点击重试。
|
|
@@ -225,7 +239,7 @@ claudex-web service restart-when-idle
|
|
|
225
239
|
|
|
226
240
|
Claude Code 请求失败时,错误提示显示认证、额度、连接或接口协议等实际问题,并可展开诊断详情。检查并修改对应供应商配置后,可以编辑失败消息重新提交。模型执行期间的草稿和附件继续保留。
|
|
227
241
|
|
|
228
|
-
|
|
242
|
+
思考内容翻译失败时,页面保留原文并提供重试入口。先在设置中检查开关、下载进度和实际错误。首次下载需允许服务账户访问 `edge.microsoft.com` 、返回的 Microsoft 下载地址及所配置的 npm registry,并确认 npm、tar 可用且模型目录可写。已安装模型启动时会校验文件,损坏或缺失后点击设置中的“重试”重新下载。
|
|
229
243
|
|
|
230
244
|
### 对话被占用
|
|
231
245
|
|
|
@@ -267,3 +281,9 @@ Claudex Web 4.0.0 使用本页顶部的正式版安装地址。已发布的 Code
|
|
|
267
281
|
Claude Code 的网络代理使用服务器可访问的代理地址和端口,支持 HTTP 代理、关闭及跟随服务环境。HTTP 代理通过 CONNECT 访问 HTTPS 目标;旧 HTTPS 代理选项会迁移为 HTTP。服务器本机部署的代理可填写 `127.0.0.1`,远端代理填写其主机名或 IP。保存配置前结束 Claude 后端的活动任务及后台终端;保存成功后,后续会话使用新代理。
|
|
268
282
|
|
|
269
283
|
首次升级沿用服务进程的代理环境;选择关闭会清除继承的代理。本机回环地址直接连接,以便访问本地模型服务。代理影响 Claude 执行服务、模型请求及其原生联网工具;WebFetch 的域名安全检查继续开启。WebSearch 还要求上游提供实际搜索能力,或通过搜索 MCP 接入独立搜索服务。
|
|
284
|
+
|
|
285
|
+
## 网页更新与重启
|
|
286
|
+
|
|
287
|
+
在设置的“更新与重启”查看当前版本和最新稳定版。服务启动时及每小时自动检查,也可点击“检查更新”。通过 npm 全局安装并执行 `claudex-web service install` 的部署,发现新版后可点击“更新至版本号”完成更新和重启,服务账户须具有安装目录写权限。新版本先在隔离目录完成安装与校验,启动失败会恢复原安装。源码部署先更新源码并构建,再点击“重启服务”。
|
|
288
|
+
|
|
289
|
+
“重启服务”随时可用于重新启动整个网页服务进程,执行期间连接短暂中断,网页自动重连。网页交互终端会结束,请先保存文件编辑。原生后端由其独立服务管理。更新完成后保存编辑并手动刷新网页加载新版界面。维护进度保存在网页配置目录的 `maintenance/status.json`,执行日志可通过 `journalctl --user -u claudex-web-maintenance` 查询。
|
package/docs/development.md
CHANGED
|
@@ -10,7 +10,7 @@ Claudex Web 的现有网页交互终端、后端原生后台终端 `/stop` 命
|
|
|
10
10
|
|
|
11
11
|
## 本地环境与源码启动
|
|
12
12
|
|
|
13
|
-
开发环境需要 Linux、Node.js 24+、npm、OpenSSL、Linux PAM
|
|
13
|
+
开发环境需要 Linux、Node.js 24.5+、npm、OpenSSL、Linux PAM 和 pamtester。验证原生后端时,安装并配置对应的 Codex 或 Claude Code CLI。网页终端依次使用 `SHELL` 环境变量、系统账户的登录 shell、`/bin/sh`,支持 Bash、Zsh 等 shell。终端集成测试覆盖本机已安装的 sh、Bash 和 Zsh,专用浏览器回归的额外依赖见对应章节。本项目使用根目录 npm workspaces 和单一 `package-lock.json` 管理前后端依赖。
|
|
14
14
|
|
|
15
15
|
克隆仓库后,在项目根目录安装依赖并创建配置:
|
|
16
16
|
|
|
@@ -39,7 +39,7 @@ npm start
|
|
|
39
39
|
npm run dev
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
打开 Vite 输出的 HTTPS 地址。Vite 与桥接复用证书,代理验证桥接证书;本地开发同样使用系统账户登录。开发服务器将 `/rpc`、`/healthz` 和 `/api` 代理到网页桥接端口,模型调用和工具执行按对话归属交给 Codex 或 Claude Code
|
|
42
|
+
打开 Vite 输出的 HTTPS 地址。Vite 与桥接复用证书,代理验证桥接证书;本地开发同样使用系统账户登录。开发服务器将 `/rpc`、`/healthz` 和 `/api` 代理到网页桥接端口,模型调用和工具执行按对话归属交给 Codex 或 Claude Code,思考内容翻译由桥接适配独立的本地翻译子项目。
|
|
43
43
|
|
|
44
44
|
验证生产构建时,执行 `npm run build`,再通过网页桥接地址访问,默认 `https://127.0.0.1:8766`。生产服务直接读取 `client/dist`,前端更新后重新构建并刷新网页即可;桥接代码更新后需要重启网页服务。
|
|
45
45
|
|
|
@@ -65,7 +65,8 @@ server/
|
|
|
65
65
|
src/bridge/ 请求、事件、订阅与后端连接
|
|
66
66
|
src/backends/ 双后端配置、供应商、路由及原生适配
|
|
67
67
|
src/workspace/ 共用文件与网页终端
|
|
68
|
-
src/summary-translation.mjs
|
|
68
|
+
src/summary-translation.mjs 本站翻译与设置 HTTP 接口
|
|
69
|
+
src/translation-service.mjs 翻译偏好、下载状态与引擎生命周期
|
|
69
70
|
src/version.mjs 正式版本与 Git / 安装包构建来源
|
|
70
71
|
tests/ 配置和桥接集成测试
|
|
71
72
|
scripts/ 后端启动、组件测试、systemd 安装及发布脚本
|
|
@@ -79,12 +80,20 @@ CHANGELOG.md 未发布变更与正式版本总览
|
|
|
79
80
|
package-lock.json 全项目依赖锁文件
|
|
80
81
|
```
|
|
81
82
|
|
|
83
|
+
`packages/translation-engine` 独立维护模型下载、完整性校验、原生分词器和 ONNX CPU 推理,使用方法见[子项目说明](../packages/translation-engine/README.md)。Linux x64 源码构建需要 C 编译器,发行包包含已构建的分词器。模型由首次启用功能触发下载,测试夹具与模型数据分别管理。
|
|
84
|
+
|
|
82
85
|
前端采用 React,Node.js 桥接服务负责静态资源和 WebSocket JSON-RPC 转发。组件职责、状态流转、协议和生命周期约束见[架构说明](architecture.md)。
|
|
83
86
|
|
|
84
87
|
服务图标源文件为 `client/src/assets/claudex-web.svg`。侧栏和欢迎页使用内联 SVG,浏览器标签页使用 `client/public` 中的 PNG、ICO 和触屏图标,通过本站独立路径读取。修改 SVG 后,在安装了 `gdk-pixbuf-thumbnailer` 的 Linux 环境中执行 `npm run icons:generate`,同步生成并提交兼容资源;普通构建与发行包安装直接使用这些资源。验证时同时检查浏览器实际请求的图标地址、响应类型及标签页显示,手机浏览器的验证独立于窄屏页面布局检查。
|
|
85
88
|
|
|
86
89
|
快捷命令的 CLI 对照、网页复用入口、专用能力边界及浏览器回归方法见[命令覆盖记录](cli-command-coverage.md)。
|
|
87
90
|
|
|
91
|
+
CLI 安装回归使用 `server/tests/cli-package.test.mjs` 验证原生平台包选择、下载失败保留旧安装、重试顺序、npm 成功后 CLI 失效及版本不一致。构建后以 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/cli-installation.mjs` 检查设置中的简短提示、诊断展开和安装重试,覆盖深浅主题、窄屏及 80% 至 200% 实际浏览器缩放。截图和构建来源保存在 `.cache/cli-installation/after`。设置 `BROWSER_BEFORE=1` 使用 `.cache/cli-installation-before` 的构建复现原始堆栈撑宽窗口。README 图片展示聊天、文件与侧栏,安装错误通过专项截图核对。
|
|
92
|
+
|
|
93
|
+
单元和发行包测试通过 `--import ./tests/helpers/test-console.mjs` 预加载测试专用 `Console`,将控制台日志统一送入 stderr。Node.js 将该文本流独立转换为测试日志事件,stdout 专供二进制测试事件,避免旧版测试运行器混读 Unicode 日志导致反序列化错误。模块加载、测试执行和清理阶段均使用同一入口,直接运行单个测试时同样携带此参数。`tests/test-console.test.mjs` 连续十次启动两个并行测试进程,核对中文、emoji、多参数、对象和调用栈日志完整保留,并核对真实断言失败仍返回非零退出状态。上游问题见 [nodejs/node#65934](https://github.com/nodejs/node/issues/65934)。
|
|
94
|
+
|
|
95
|
+
构建后执行 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/slash-commands.mjs`,使用隔离浏览器与模拟后端验证输入开头及正文中途的斜杠建议、Tab 补全、确认、光标中间替换、正文保留、撤销重做、失败恢复、技能及原生命令,并检查深浅主题、桌面及窄屏、80% 至 200% 实际页面缩放与侧栏开关。脚本核对 DPR 和视口,结束时恢复缩放并清理独立浏览器目录。截图与构建来源保存在 `.cache/slash-commands/after`。修复前将 `client/dist` 与 `build-info.json` 复制到 `.cache/slash-commands/before`,以 `BROWSER_BEFORE=1` 运行可复现中途缺少菜单。README 图片展示普通消息与文件预览,现有图片继续适用。
|
|
96
|
+
|
|
88
97
|
## 双后端开发与验收
|
|
89
98
|
|
|
90
99
|
双后端的统一范围由[产品契约](architecture/backends.md)定义;`shared/product-contract.mjs` 只注册工作区和对话方法的路由分组。原生能力分别接入统一用例,文件与网页终端由共用工作区服务提供。文件模糊查询按所属后端路由,Codex 保留原生 app-server 调用,Claude Code 使用原生 `file_suggestions` 控制请求及 CLI 文件索引;两端共用输入建议,回归同时核对原有 Codex 路径和 Claude 新增实现。CLI/SDK 生命周期、原生历史及参数发生变化时,同时检查首次请求、流式展示、轮次完成、刷新恢复和错误重试。Claude 执行服务通过受限本机 IPC 独立于网页桥接运行,网页关闭仅释放连接;源码与安装来源的代码身份按实际发行文件计算。
|
|
@@ -160,6 +169,8 @@ CLAUDE_EXECUTABLE=/absolute/path/to/claude MODEL_BASE_URL=https://model.example
|
|
|
160
169
|
|
|
161
170
|
脚本将“介绍这个文件夹里面各个文件的功能”的请求原文交给真实 Claude Code,以临时配置和原生计划模式读取指定目录。验证成功的工具响应包含实际源码 API、最终正文覆盖目录文件与公开 API、全部模型请求返回 200,以及目标文件 SHA-256 前后相同。`MODEL_API_KEY` 按服务认证要求设置,`VALIDATION_OUTPUT` 可指定证据目录,默认 `.cache/backend-acceptance/original-user-case`。证据包含 `answer.md`、工具事件、原生会话、请求响应和结果报告。该入口读取已有目录,写入仅发生在临时配置及证据目录中。
|
|
162
171
|
|
|
172
|
+
`claude-model-switch.mjs` 在同一真实 CLI 会话连续执行 A → B → A,使用隔离 Messages 响应触发 Opus、Sonnet、Haiku 三类子代理,检查主请求、子代理请求、持久模型和设置通知均跟随本轮选择。设置 `MODEL_BASE_URL` 与 `MODEL_ID` 后使用真实模型响应,验证 Haiku 子代理。该模式将两个临时测试模型标识转发到同一个指定模型,上游请求限制为 1024 输出 tokens 并关闭思考;上下文容量为 65536,须与测试服务的加载配置一致。`VALIDATION_OUTPUT` 指定请求与报告目录,默认 `.cache/backend-acceptance/model-switch`。测试始终使用临时原生目录与网页状态目录。
|
|
173
|
+
|
|
163
174
|
### 客户端与既有网页行为查验
|
|
164
175
|
|
|
165
176
|
2026-11-06 查验本机保存的网页客户端 `codex-lan-client 2.0.0`,目录为 `~/.local/share/codex-lan/client-source`。`src/shortcuts.jsx` 的文件建议逻辑在空查询或目录后缀时读取目录,其余查询调用 `fuzzyFileSearch` 并传入当前目录,保留 60 项及请求代次隔离;同文件的命令注册列出原有网页入口。`src/store.js` 的发送流程根据活动轮次选择 `turn/steer` 或 `turn/start`,通知分派处理 `turn/started` 与 `turn/completed`。这些代码作为既有网页交互和用户体验的查验依据,统一 18 项命令以当前仓库注册表为准。
|
|
@@ -170,6 +181,8 @@ CLAUDE_EXECUTABLE=/absolute/path/to/claude MODEL_BASE_URL=https://model.example
|
|
|
170
181
|
|
|
171
182
|
## 格式与验证
|
|
172
183
|
|
|
184
|
+
模型名称布局回归在构建后执行 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/model-select.mjs`。脚本使用隔离模型目录及模拟后端,在桌面、平板竖屏和手机窄屏核对完整名称、键盘选择、两行输入、发送与停止按钮、深浅主题及 80%~200% 实际页面缩放;结束后恢复缩放并清理浏览器配置。截图与测量记录保存在 `.cache/model-select/after`。修复前将构建复制到 `.cache/model-select/before/dist`,设置 `BROWSER_BEFORE=1` 可复现固定宽度截断。
|
|
185
|
+
|
|
173
186
|
长对话切换回归先执行 `npm run build`,再运行 `CHROME_PATH=/path/to/chromium PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs node tests/browser/history-performance.mjs`。脚本使用生产构建、独立浏览器和 15 轮、3,210 条记录的隔离历史(消息分页基线 33 页,优化后首屏加 15 个轮次分页),每页模拟 50 毫秒往返;记录首屏和完整恢复耗时,验证最近消息及输入先可用、自动完整分页、普通状态更新复用 Markdown、读取期间草稿与实时更新保留、历史前插时的阅读位置、目录跳转和快速切换隔离,覆盖深浅主题、80% 至 200% 缩放及窄屏。证据与构建来源保存在 `.cache/history-performance/after`。修改前的构建及来源分别保存为 `.cache/history-performance-before/dist` 和 `build-info.json`,以 `BROWSER_BEFORE=1` 记录同机对照,耗时用于比较同机行为。单元及组件回归同时验证旧接口完整轮次回退、分页失败后的可读记录与重试、实时结果优先及切换隔离。现有 README 图片展示完整加载后的界面,布局和内容继续适用。
|
|
174
187
|
|
|
175
188
|
侧栏收纳回归执行 `SIDEBAR_DENSITY=1 CHROME_PATH=/path/to/chromium node tests/browser/project-pins.mjs`,使用隔离的 Atlas/Beacon 与最近有活动的未分类对话、超过 60 条的后端分页,验证未分类始终位于末尾、固定与未固定的默认收放、每组最新五条、全部展开及收起、刷新重置、键盘操作、深浅主题、80% 至 200% 缩放和手机布局。截图与构建信息保存在 `.cache/sidebar-density-browser/after/`。旧构建及来源位于 `.cache/sidebar-density-before/`,追加 `SIDEBAR_DENSITY_BEFORE=1` 保存旧版全部展开的对照截图。
|
|
@@ -235,6 +248,10 @@ npm run test:package
|
|
|
235
248
|
|
|
236
249
|
右侧详情隔离回归先执行 `npm run build`,再运行 `CHROME_PATH=/path/to/chromium CONTEXT_RESET=1 BROWSER_OUTPUT_DIR=.cache/context-reset/after node tests/browser/annotations.mjs`。脚本以隔离 WebSocket 历史和独立浏览器配置,实际打开文件差异与变更面板并点击新建,检查默认收起、重新展开的概览、文件列表、深浅主题和手机布局。修改前的生产构建及构建信息分别保存在 `.cache/context-reset-before/dist` 与 `.cache/context-reset-before/build-info.json`,通过 `BROWSER_BEFORE=1`、`BROWSER_BUILD_DIR` 和 `BROWSER_BUILD_INFO` 指定并复现残留;截图和构建来源写入指定目录。组件回归补充文件、变更、子代理与待打开文件的清理,以及原对话未保存文件的恢复。README 及其他文档引用的现有截图展示任务对话与文件预览,本次修复的新建状态未出现在这些图片中,图片内容保持适用。
|
|
237
250
|
|
|
251
|
+
## Mermaid 图表回归
|
|
252
|
+
|
|
253
|
+
Mermaid 回归先执行 `npm run build`,再运行 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/mermaid.mjs`。使用隔离的后端历史与文件正文,在真实消息区和 Markdown 文件预览中绘制长流程图、短流程图及中文时序图;核对紧凑字号、长图展开与收起、完整高度、方向切换、原始源码保留,以及按钮、键盘和 Ctrl+滚轮缩放与复位。深浅主题、390px 窄屏及 80% 至 200% 的实际浏览器缩放均检查页面边界。截图、尺寸记录及构建来源保存在 `.cache/mermaid-size-browser/after`。修改前的构建与来源复制到 `.cache/mermaid-size-before/dist` 和 `build-info.json` 后,使用 `BROWSER_BEFORE=1` 记录对照。
|
|
254
|
+
|
|
238
255
|
## 网页交互终端回归
|
|
239
256
|
|
|
240
257
|
网页手动终端通过独立的 `lan/terminal/*` 接口进入宿主工作区,由 node-pty 持有进程;模型后端、原生命令与后台任务分别按各自所有者维护。`node --test server/tests/web-terminals.test.mjs server/tests/backend-native-workspace-routing.test.mjs` 使用真实 PTY 和模拟后端,核对 Codex 与 Claude Code 标识均进入同一工作区、后端离线时仍可使用终端、连续创建五个、前台进程切换、单独结束及原生工作区路由。组件回归覆盖名称与图标更新、切换复用实例、启动目录隔离、面板开关与选中项恢复、后台目录退出隔离、Ctrl+D 及当前目录最后退出后的收起。`client/tests/terminal-workspace.test.js` 检查完整路径、中文目录及路径规范化,同目录切换后端和不同目录分别验证。
|
|
@@ -328,7 +345,7 @@ Ubuntu 安装指引回归在设备选择器中实际切换 Ubuntu,检查 DER
|
|
|
328
345
|
|
|
329
346
|
### Markdown 富文本输入回归
|
|
330
347
|
|
|
331
|
-
输入框采用直接编辑排版正文的交互,持久化与提交使用 Markdown。执行 `npm run build` 后,使用 `CHROME_PATH=/path/to/chromium PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs node tests/browser/markdown-composer.mjs`
|
|
348
|
+
输入框采用直接编辑排版正文的交互,持久化与提交使用 Markdown。执行 `npm run build` 后,使用 `CHROME_PATH=/path/to/chromium PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs node tests/browser/markdown-composer.mjs` 验证生产构建。脚本使用隔离模拟后端和独立浏览器上下文,检查双美元符号公式的同段渲染、单美元符号普通文本、闭合前源码、源码重入及撤销重做;同时检查延迟加载期间的文本及选区恢复、快速切换对话后的实例隔离、正文及列表的完整边界、点击与方向键定位、撤销重做、滚动后继续输入、原生光标、连续换行自动增高及可用空间边界、混合块在正文中间粘贴及选区替换后的顺序、光标与整次撤销、代码续写、公共手柄拖动及展开收起、放大时底部输入区的轮廓与尺寸保留、只读预览与编辑器节点隔离、编辑区滚轮上下滚动、混合 Markdown 粘贴、表格直接编辑、任务复选框、公式、脚注、代码与 HTML 源码保留、草稿、发送及快捷建议,并覆盖深浅主题、80%~200% 缩放和窄屏。截图、结果和构建来源保存在 `.cache/markdown-composer`。组件回归使用文本输入适配,实际富文本行为由浏览器回归覆盖;发行包回归验证编辑器分块的安装与资源响应,浏览器回归拦截外站请求。
|
|
332
349
|
|
|
333
350
|
使用相同环境变量运行 `tests/browser/markdown-typing.mjs`,验证逐字键入、整段插入、粘贴和中文组合输入自动排版。覆盖列表内公式 `- $$x_{t+1}=x_{t}+dx$$`、标题、强调、链接、任务列表、表格分隔行及代码围栏进出,同时核对实际可见排版、表格光标和 Markdown 草稿。证据保存在 `.cache/markdown-typing/after`。
|
|
334
351
|
|
|
@@ -383,3 +400,13 @@ Ubuntu 安装指引回归在设备选择器中实际切换 Ubuntu,检查 DER
|
|
|
383
400
|
对话拖拽回归使用 `THREAD_FOLDER_DRAG=1 CHROME_PATH=/path/to/chromium node tests/browser/project-pins.mjs`,验证真实鼠标拖起、目标高亮、保存、刷新恢复、未分类及深浅主题,证据保存到 `.cache/project-pins-browser/after`。`node tests/integration/codex-folder-native.mjs` 使用隔离历史验证原生目录恢复,模型请求为零;`node tests/integration/thread-folder-native.mjs` 使用真实 Claude CLI 与本机模拟模型服务验证跨目录继续、旧正文及目标 AGENTS 指令,全部数据位于临时目录。网页项目以单个文件夹为归属边界。
|
|
384
401
|
|
|
385
402
|
批注换行边界回归在构建后执行 `ANNOTATION_WRAPPING=1 CHROME_PATH=/path/to/chromium node tests/browser/annotations.mjs`,使用隔离浏览器与模拟历史,逐字覆盖窄字符、中文长文、深浅主题及删除后收起。结果保存在 `.cache/annotations-browser/wrapping-results.json`。
|
|
403
|
+
|
|
404
|
+
### 本地思考内容翻译验证
|
|
405
|
+
|
|
406
|
+
中途进入运行中会话的回归执行 `TRANSLATION_TEST_MODEL_DIR=/path/to/installed/models PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/translation-active-history.mjs`。脚本使用生产构建、临时配置与隔离历史,保留原生历史摘要缺少状态字段的结构,实际调用本地 CPU 引擎,验证旧摘要翻译、当前摘要等待完成、原译文切换、刷新缓存、深浅主题、窄屏及 80% 至 200% 实际页面缩放。证据保存在 `.cache/translation-active-history/after`。修复前先将 `client/dist` 和 `build-info.json` 分别复制到 `.cache/translation-active-history/before/dist` 和 `build-info.json`,再加 `BROWSER_BEFORE=1` 运行,记录旧摘要零翻译请求及对照截图。测试恢复页面缩放并清理临时配置与浏览器;README 演示图展示已结束对话,沿用现有截图。
|
|
407
|
+
|
|
408
|
+
构建后执行 `TRANSLATION_TEST_MODEL_DIR=/path/to/installed/models PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/thinking-translation.mjs`。脚本使用独立浏览器、临时配置和模拟对话,实际调用本地 CPU 引擎,验证默认关闭、完整消息触发、等待原文、Markdown 文字提取、原译文切换及关闭恢复原文,覆盖深浅主题、桌面与窄屏、80% 至 200% 实际浏览器缩放。已安装模型目录由运行者提供,截图和结果保存在 `.cache/thinking-translation/`,测试结束后清理浏览器与临时配置。
|
|
409
|
+
|
|
410
|
+
异步回复收纳回归在构建后执行 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/async-replies.mjs`。夹具保留真实 Codex 消息的 `delivery: async` 与 `phase: final_answer` 组合,检查中途回复在折叠时隐藏、展开后完整可读、连续补充保留一个工作过程及原展开状态、流式投递、最终回答操作与草稿;刷新、深浅主题、桌面与窄屏、80% 至 200% 实际页面缩放采用相同断言。截图及结果保存在 `.cache/async-replies/after`。`BROWSER_BEFORE=1 BROWSER_BUILD_DIR=/path/to/previous/dist` 使用旧构建复现外露;`CONVERSATION_NATIVE_FILE=/path/to/turn.json` 可重放只读导出的真实轮次,原生记录保存在 Git 忽略目录且不调用模型。测试结束恢复缩放并清理独立浏览器配置。README 图片展示普通已完成任务,现有图片继续适用。
|
|
411
|
+
|
|
412
|
+
运行状态渲染回归使用 `PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs CHROME_PATH=/path/to/chromium node tests/browser/status-rendering.mjs`,通过隔离后端和生产构建验证运行、展开、完成、草稿保留及计时更新,并记录 3.1 秒稳定内容期间的绘制帧数与活动动画。证据写入 `.cache/status-rendering/after`。旧构建放入 `.cache/status-rendering/before/dist`,设置 `BROWSER_BEFORE=1` 复现循环动画引起的逐帧绘制。该回归关闭 GPU,验证浏览器绘制调度;实际 GPU 占用另通过桌面静置采样核对。
|
|
Binary file
|
|
Binary file
|
package/docs/images/mobile.png
CHANGED
|
Binary file
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Claudex Web v4.1.0
|
|
2
|
+
|
|
3
|
+
- 设置中可按需开启思考内容翻译,首次启用下载本地模型,之后可离线使用;下载显示进度并支持失败重试。思考接收完整后自动翻译,可切换原文与译文,保留代码、链接与公式。([325e136](https://github.com/hjd-hitsz/claudex-web/commit/325e136))
|
|
4
|
+
|
|
5
|
+
- 设置页支持检查新版、更新 npm 全局安装版本及重启服务,完成后提示刷新网页;更新与重启入口置顶,主题自动跟随系统。([575b6ac](https://github.com/hjd-hitsz/claudex-web/commit/575b6ac))
|
|
6
|
+
|
|
7
|
+
- 对话 token 用量按后端与对话独立保存,重新打开、刷新及服务重启后恢复;已有对话自动补齐可读取的统计,分支继承对应历史位置的用量。([0233f3e](https://github.com/hjd-hitsz/claudex-web/commit/0233f3e))
|
|
8
|
+
|
|
9
|
+
- 修复 Claude Code 子代理详情已有消息时仍显示“当前没有消息”的问题。([51ead17](https://github.com/hjd-hitsz/claudex-web/commit/51ead17))
|
|
10
|
+
|
|
11
|
+
- 运行中的会话重新打开或重连后,已有思考摘要继续翻译;完整思考与摘要的原译文切换入口统一位于标题行。([7b2495e](https://github.com/hjd-hitsz/claudex-web/commit/7b2495e)、[de80a07](https://github.com/hjd-hitsz/claudex-web/commit/de80a07))
|
|
12
|
+
|
|
13
|
+
- 后端连接恢复后及时清除旧错误,Claude 后台服务连接失败时提供清晰的处理提示。([b8d2e1a](https://github.com/hjd-hitsz/claudex-web/commit/b8d2e1a))
|
|
14
|
+
|
|
15
|
+
- 首次部署可先启动网页,再从设置安装 Codex 或 Claude Code;新增供应商与预置 DeepSeek 默认使用原生 Message API,并明确标识兼容协议选项。([ceab7ed](https://github.com/hjd-hitsz/claudex-web/commit/ceab7ed))
|
|
16
|
+
|
|
17
|
+
- Claude Code 切换模型后,三档模型别名及新启动的子代理同步使用当前选择的模型。([3000a63](https://github.com/hjd-hitsz/claudex-web/commit/3000a63))
|
|
18
|
+
|
|
19
|
+
- 默认安装与升级统一使用 @hjd-hitsz/claudex-web 作用域包名,可直接从 npm 获取正式版本。([bf15f47](https://github.com/hjd-hitsz/claudex-web/commit/bf15f47))
|
|
20
|
+
|
|
21
|
+
- 复选框与选项对勾统一使用蓝色,深浅主题保持一致。([0bfce9b](https://github.com/hjd-hitsz/claudex-web/commit/0bfce9b))
|