@hjd-hitsz/claudex-web 4.0.1 → 4.1.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.
- package/CHANGELOG.md +46 -0
- package/README.md +33 -55
- package/build-info.json +4 -4
- package/client/dist/app.js +81 -82
- package/client/dist/style.css +1 -1
- package/docs/architecture/backends.md +2 -0
- package/docs/architecture/behavior.md +23 -1
- package/docs/architecture.md +33 -4
- package/docs/deployment.md +34 -14
- package/docs/development.md +14 -3
- package/docs/releases/v4.1.0.md +21 -0
- package/docs/versioning.md +10 -0
- package/package.json +24 -7
- 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/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/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,8 @@ Claude 原生思考按所属 API 消息的内容块顺序保留独立标识,
|
|
|
12
12
|
|
|
13
13
|
## 双后端与供应商
|
|
14
14
|
|
|
15
|
+
网页安装与启动支持尚未安装任何原生 CLI 的环境,登录后可在设置中安装所需后端。新建 Codex 用户服务通过已有后端启动脚本运行,缺少 CLI 时由 systemd 重试;安装完成后启动原生 app-server,桥接按原连接流程恢复就绪状态。
|
|
16
|
+
|
|
15
17
|
自定义供应商在列表的编辑按钮旁提供删除按钮;请求期间禁止重复操作,成功后刷新供应商及模型目录并关闭该供应商的编辑表单,失败保留列表及编辑内容并显示错误。默认供应商通过清空 API Key 停用。
|
|
16
18
|
|
|
17
19
|
项目模型偏好在所属后端离线时仍可读取和保存;保存成功向所有页面广播所属后端的完整项目偏好,保存失败保留原数据并允许重试。依赖执行状态的目录创建、单文件撤销、整理核对和子代理消息读取在后端就绪后执行。整理占用期间,两端统一暂停开始轮次、补充输入、审查、历史回退和再次整理,历史与项目偏好保持可读。
|
|
@@ -127,7 +129,7 @@ flowchart LR
|
|
|
127
129
|
|
|
128
130
|
消息目录以实际独立用户消息为条目,支持搜索、键盘、当前位置高亮和跳转;默认缩略标记数量受控。目录和详情卡片各有稳定位置,主消息滚动条贴工作区最右侧。新建按钮在侧栏收起和窄屏下保持可用。
|
|
129
131
|
|
|
130
|
-
|
|
132
|
+
思考内容翻译默认关闭,设置开关保存在网页服务。启用后准备本地模型,完整消息的完成事件或已结束历史触发翻译;运行中会话的历史摘要缺少消息状态时,以同轮后续非用户活动确认其已结束,当前流式消息继续等待完成事件,标题优先,正文在折叠期间也可准备。流式阶段及翻译等待期间展示原文,成功后提供原文与译文切换。Markdown 解析只提取普通文字送入引擎,代码、公式与链接目标沿用源码。译文按模型版本和完整原文在同一标签页的内存与会话存储中复用,失败可重试;卸载、关闭翻译或模型切换后忽略迟到结果。模型下载、存储及离线迁移见[部署文档](../deployment.md#思考内容翻译)。
|
|
131
133
|
|
|
132
134
|
## 工作区、文件与终端
|
|
133
135
|
|
|
@@ -149,6 +151,8 @@ Claude Code 的原生后台任务按所属会话保存任务标识、类型、
|
|
|
149
151
|
|
|
150
152
|
## 子代理与共享渲染
|
|
151
153
|
|
|
154
|
+
Claude 子代理原生历史中,带有 `isSidechain=true` 与 `agentId` 的任务输入以侧链来源建立轮次,即使继承 SDK 入口和父轮次 `promptId`。主对话内部通知继续按其来源字段过滤,子代理任务、工具和回答完整恢复。
|
|
155
|
+
|
|
152
156
|
子代理按对话 ID 合并不同协议版本的活动,主对话工作过程与详情概览共用入口。只读详情复用完整历史、消息和工作过程,消息路径使用子代理的实际目录。切换代理或关闭详情清理监听并丢弃迟到结果。
|
|
153
157
|
|
|
154
158
|
桥接通过父对话协作调用与子代理接收记录核对初始任务和后续消息,按接收者及调用 ID 隔离,保留重复发送并避免原生输入重复。标记为加密的正文在桥接返回前替换为“消息内容已加密”。发送成功而接收记录尚未落盘时,对整条正文符合 Fernet 封包布局的内容立即使用同一状态,检查 Base64URL 编码、版本、固定字段长度及加密块长度;接收后的结构化标记继续覆盖其他密文格式。明文保留原文,包括正文中引用的封包及仅包含相似前缀的文本。失败保留已有内容并可重试。
|
|
@@ -159,12 +163,20 @@ Claude Code 的原生后台任务按所属会话保存任务标识、类型、
|
|
|
159
163
|
|
|
160
164
|
## 账户、登录与外观
|
|
161
165
|
|
|
166
|
+
已有 Codex 对话缺少本地用量快照时,首次读取从原生持久记录补录并保存。分页分支按原生历史引用及截断字节边界恢复对应上下文统计,后续打开直接读取快照。归档对话跳过补录。
|
|
167
|
+
|
|
168
|
+
桥接每次启动后,在后端就绪时后台分页核对全部归档和未归档对话。归档对话删除已保存的快照,未归档对话只补录缺少的统计。核对过程、完成数量和读取错误可通过只读维护状态查询。
|
|
169
|
+
|
|
170
|
+
创建末尾分支时继承请求发出前的来源用量快照,之后按新对话独立持久化和更新。指定轮次分支仅继承该轮次的已知统计,统计暂缺时等待分支回复上报。原生返回及分支实时上报的用量优先于继承值;Claude 较早轮次分支清除从来源索引复制的最新用量。
|
|
171
|
+
|
|
162
172
|
对话完成通知默认开启,浏览器已有的手动关闭偏好保持有效。开关表示通知偏好,浏览器尚未授权时提供“允许系统通知”按钮,由用户点击请求权限;已有授权直接生效。正常状态仅展示开关,权限被拒绝、环境不支持及发送失败时显示必要状态。已登录页面观察到活动轮次成功完成后发送一条带对话标题及完成状态的通知;失败、中断、手动整理及历史读取保持各自原有展示。浏览器从桥接活动快照恢复进行中的轮次后可继续接收提醒,刷新和重连恢复已结束历史时保持安静。同源页面通过 IndexedDB 以系统登录用户、对话 ID 与轮次 ID 的唯一主键原子领取提醒,重复事件及多个页面保持一次。发送前重新检查开关、权限和登录用户,关闭提醒立即阻止尚未发送的通知。权限被拒绝、环境不支持及发送失败在设置页明确显示,聊天独立继续。
|
|
163
173
|
|
|
164
174
|
通知点击优先聚焦原页面并打开所属对话,保留其他对话的草稿与文件缓冲区;原页面已关闭时打开新页面并在登录及初始化就绪后恢复目标。导航事件验证通知所属登录用户,页面监听在登录界面同样有效,卸载时清理监听及待导航目标。提醒开关为浏览器偏好,浏览器权限及系统通知设置共同决定展示;在线页面与服务连接负责接收完成事件。
|
|
165
175
|
|
|
166
176
|
Claude Code 原生账户额度来自原生 `get_usage` 控制响应,按真实窗口、重置时间和额外用量单位展示;配置外部供应商时显示外部计费状态,余额以该供应商提供的数据为准。上下文用量按原生 token 记录及上下文查询恢复,与账户额度分别管理。
|
|
167
177
|
|
|
178
|
+
Codex 与 Claude 的所有未归档对话分别在网页配置目录持久保存最近一次收到的完整 token 用量快照,包含累计用量、最近上下文用量及后端实际容量。打开、刷新及桥接重启后通过轻量对话响应读回快照;统计更新优先采用读取期间到达的实时通知。每个对话独立读写,重复值省去写入,并发更新合并为最新快照。归档和删除清除所属统计,归档期间停止采集;恢复归档按普通流程处理,统计暂缺时等待下一次模型回复上报。未归档历史对话首次缺少快照时,按后端原生记录补录。
|
|
179
|
+
|
|
168
180
|
账户额度按后端实际窗口展示。完整读取替换快照,稀疏通知合并已有元数据;并发读取合并,连接、账户与通知版本共同隔离迟到响应。断线或失败保留上次数据并标记待更新。前台、轮次完成、额度重置及恢复连接触发校准;计时器和页面监听随生命周期清理。
|
|
169
181
|
|
|
170
182
|
额度详情默认折叠,以圆环显示窗口及剩余比例,展开后显示方案、额度与同一行的倒计时和重置时间。点击外部、Esc 和账户切换收起详情,布局保持账户行高度。
|
|
@@ -204,3 +216,13 @@ Claude Code 网络代理在设置中提供跟随服务环境、关闭和 HTTP,
|
|
|
204
216
|
设置、搜索、重命名、删除确认、目录选择、技能、插件、模型及命令弹窗,以及图片和批注预览的右下角提供尺寸调节手柄。文件预览、文件差异和子代理详情共用的右侧面板通过左边缘调节宽度。支持鼠标及触控拖动、聚焦后的方向键调节、Shift 加速、双击或 Home 恢复默认。窗口手柄支持 Enter 或空格复位。尺寸按用途分别记忆,关闭重开与刷新恢复;尺寸按可用空间比例适应缩放和窄屏,并受当前视口边界约束。详情宽度同步调整聊天与输入区域的避让空间,拖动保留文件编辑和批注内容。项目侧栏、终端高度、终端列表及各类多行表单输入框使用同一套尺寸手柄。默认显示轻量短标记,悬停时增强、拖动时保持高亮,键盘焦点仅围绕局部标记显示。透明操作区与标记分离,方向分别表达调宽、调高或双向调整;失焦、取消或释放捕获结束拖动反馈。输入框保留原有字段、内容与禁用状态,双击或 Home 恢复自动高度。
|
|
205
217
|
|
|
206
218
|
上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
|
|
219
|
+
|
|
220
|
+
## 网页更新与重启
|
|
221
|
+
|
|
222
|
+
设置中的“更新与重启”显示当前版本、npm 最新稳定版与检查错误。桥接启动时及每小时自动检查,网页发现更新提供设置入口。npm 全局安装可更新并重启,源码部署使用源码更新流程。重启服务在当前版本下同样可用,操作要求当前进程属于安装的 systemd 用户服务。整个网页服务进程重启,网页交互终端随之结束,原生后端继续按各自生命周期执行。独立维护任务持久记录进度,重复操作合并,安装与启动失败提供错误及重试。新包先在隔离目录安装并验证,替换后启动失败恢复原包。网页重连后保留草稿和文件编辑,用户保存编辑后主动刷新页面加载新资源。
|
|
223
|
+
|
|
224
|
+
更新及重启请求遇到活动轮次、后台任务、排队输入、待答提问、内部命令或上下文整理时,结束本次操作并短暂提示用户结束任务后重试。提示五秒后关闭,用户稍后重新发起操作。切换阶段暂停网页提交,避免提交与重启竞争。重启成功后网页显示“服务已重启,请刷新网页”,用户自行刷新。
|
|
225
|
+
|
|
226
|
+
发现新版本后,侧栏底部显示带版本号的更新入口并标记设置按钮;侧栏收起或窄屏时,顶部显示紧凑更新入口。设置页按更新与重启、模型与服务配置、通知与翻译、网页登录分组。更新卡片集中显示产品身份和主操作,当前与最新版本在产品名下同行显示,检查更新、重启服务与更新按钮在卡片底部固定排成一行,复用设置页按钮的尺寸和边框,主要更新操作位于右侧,有新版时显示“更新至版本号”,无需更新时显示灰色禁用的“无需更新”,按钮数量与位置保持稳定;检查期间显示进行状态。设置卡片通过间距区分内部内容。原生后端的当前版本合并到标题行,正常连接以状态点显示,安装操作失败作为本次设置访问中的短暂提示,重新打开设置跳过历史安装提示,有新版时在按钮直接显示目标版本并允许更新,版本相同或本机更新时保留灰色禁用的“无需更新”按钮;未安装、停用及连接失败保留文字状态。网页主题始终跟随系统。点击更新入口直接打开设置并滚动、聚焦“更新与重启”区域。界面只显示版本、操作与必要状态,检查周期及部署实现保留在部署文档。
|
|
227
|
+
|
|
228
|
+
维护任务的持久结果用于状态核对,操作提示归属当前设置访问。首次加载、刷新及重新打开设置跳过历史完成和失败提示;当前访问发起的操作按任务开始时间确认结果并只显示一次。关闭设置清除提示并使在途请求的后续反馈失效,后台任务继续按真实状态执行。代理保存反馈五秒后消失,表单错误和实际连接、下载故障按各自当前状态提供处理入口。
|
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 名称,原生协议和运行状态由所属适配器解释。管理器统一组装网页及维护连接的快照。
|
|
@@ -225,7 +244,9 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
225
244
|
|
|
226
245
|
文件引用查询按对话所属后端路由:Codex 的 `fuzzyFileSearch` 继续由原生 app-server 处理,Claude Code 由 `catalogue.mjs` 调用原生 `file_suggestions`,复用 CLI 的文件索引及建议。持续会话和目录查询会话在初始化时预热原生索引;目录、供应商配置与对话标识限定查询归属,前端统一展示文件和目录。验证同时核对已有 Codex 路径、Claude 原生结果和真实工作区的查询表现。
|
|
227
246
|
|
|
228
|
-
|
|
247
|
+
新增供应商及预置 DeepSeek 默认使用原生 Message API,原生请求保留中途系统消息;自定义模型显式配置的能力优先于 CLI 模型目录。历史自定义供应商缺少协议字段时沿用原有兼容模式,编辑保存保留其实际协议。Message API 兼容模式使用顶层 `system` 承载系统上下文,用户正文与工具调用继续保留原始内容块和顺序。协议转换在首次请求前完成,并保留原生思考控制、结构化输出及辅助评估请求;处理规则与原生接口依据见双后端产品契约。文件变更通过工具钩子记录前后内容,撤销复用现有补丁校验。能力声明描述模型参数、外部事实和原生扩展,通用产品入口使用统一契约;原生历史跨运行时交接属于独立设计。
|
|
248
|
+
|
|
249
|
+
外部供应商的模型环境由 `provider-environment.mjs` 生成,主模型与 Opus、Sonnet、Haiku 三个原生别名随本轮选择一起更新。初始化与持续会话共用映射,运行时等待原生模型和设置更新完成后提交输入,设置失败按本轮错误结算并允许重试。
|
|
229
250
|
|
|
230
251
|
## 5. 功能模块与共享展示
|
|
231
252
|
|
|
@@ -257,15 +278,21 @@ Claude 网页桥接重启或异常退出时,独立执行服务继续持有模
|
|
|
257
278
|
|
|
258
279
|
## 6. 样式、加载与分发
|
|
259
280
|
|
|
260
|
-
`style.css`
|
|
281
|
+
`style.css` 是有序样式入口。设置窗口的分组与控件尺寸由 `styles/settings-layout.css` 限定在设置弹窗内,更新卡片及常驻更新入口由 `styles/service-maintenance.css` 持有。`styles/theme.css` 和 `base.css` 定义主题及基础排版,其余按侧栏、导航、消息、批注、文件、终端和弹窗等职责组织;响应式及排版覆盖按入口中声明的顺序应用。移动规则时保持选择器顺序、媒体条件和变量作用域;增加规则优先放到所属模块,修改覆盖顺序时验证全部受影响布局。
|
|
261
282
|
|
|
262
283
|
主页面先加载聊天所需的代码。文件面板和终端通过 `React.lazy` 首次打开时加载,文件面板完成首次加载后保持编辑缓冲区;Mermaid 按图表需求加载本站模块。终端面板持有终端列表及活动选择,每个终端组件独立持有 xterm 实例、输入订阅及尺寸观察,切换保留各实例,桥接拥有进程及恢复缓冲区。网页交互终端统一由桥接工作区服务的 node-pty 持有,浏览器通过独立的 `lan/terminal/*` 接口创建、输入、调整尺寸及结束进程,操作先于后端资源路由处理,与模型后端和启用状态独立。服务直接启动系统登录 shell,每 500 毫秒读取实际 PTY 前台进程名,变更时发送元数据通知;快照及启动事件保存进程名、输出、工作区归属与规范化的绝对启动目录,浏览器按名称选择图标并省去目录和编号。应用状态按启动目录保存面板开关,终端组件按目录恢复运行列表和选中项;跨目录切换隐藏原终端,同目录切换对话或模型后端保留同一终端组件。选中项按目录持久保存,后台目录退出只更新所属选择。面板框架独立持有纵向拖动及高度比例偏好,按实际可用高度、输入区和 CSS 保留空间限制高度;高度变化沿用终端尺寸观察同步 PTY 行数。列表组件独立持有拖动、键盘及相对宽度偏好,CSS 定义默认宽度和容器上限,尺寸变化或卸载时释放指针捕获。切换文件夹、隐藏和重连保留进程及缓冲区;全部进程结束或工作区服务关闭后清理检测计时器。后端代理原生命令与后台任务保持所属运行时的路径。终端的基础样式在挂载入口先于项目样式导入,JavaScript 仍按需加载。Vite 保持单一 CSS 产物和根部 JavaScript 分块,保持第三方样式与项目规则的覆盖顺序。
|
|
263
284
|
|
|
264
|
-
根 `package.json` 与单一锁文件管理 workspaces
|
|
285
|
+
根 `package.json` 与单一锁文件管理 workspaces。翻译子项目的源码、许可证、CLI 与构建后的原生分词器随发行包交付,模型权重、Microsoft 分词运行库和 ONNX Runtime CPU 文件在用户启用后独立下载。
|
|
286
|
+
|
|
287
|
+
npm 分发由独立的 `npm-publish.yml` 工作流监听即时及定时 GitHub 发布工作流的成功结果,以 OIDC 身份上传已公开的 Release 附件。`publish-npm.mjs` 持有附件下载、校验、临时安装、注册表完整性核对与同版本重试;发布时间继续由发布计划和 Release 草稿状态约束,稳定版与预发布分别进入 `latest` 与 `next`。
|
|
288
|
+
|
|
289
|
+
发行白名单包含 `client/dist`、`server/src`、`shared`、命令入口、运行脚本、许可证和构建信息。增加共享运行模块或动态分块时,验证实际打包清单、生产响应和临时全局安装。生产版本来源由 `server/src/version.mjs` 统一读取,网页在构建时固定,桥接在启动时固定;干净标签构建可交付稳定版本或 alpha、beta、rc 预发布版本;发布工具维护版本顺序和 GitHub 成熟度标记,预发布保留稳定下载入口及 Latest。流程见[版本管理](versioning.md)。
|
|
265
290
|
|
|
266
291
|
## 7. 可执行约束与验证
|
|
267
292
|
|
|
268
|
-
|
|
293
|
+
服务安装器创建网页服务时独立于原生 CLI 的安装状态。新建的 Codex 用户服务以当前 Node.js 运行 `scripts/start-backend.mjs`,显式传入网页配置目录、原生目录和连接地址;启动脚本沿用原生 app-server 参数。CLI 缺失时该服务失败后由 systemd 每 5 秒重试,网页继续提供登录、设置和 CLI 安装入口。既有 Codex 服务的保留与新服务的首次启动分别回归。
|
|
294
|
+
|
|
295
|
+
`npm run architecture:check` 扫描 `client/src`、`server/src`、`shared`、`scripts`、`bin` 和翻译子项目中的 JavaScript、JSX、MJS 与 CSS:
|
|
269
296
|
|
|
270
297
|
1. 单文件最多 **500 行**,计入注释和空行。日常按单一职责组织,接近上限时先拆分,保持格式化后的正常排版。
|
|
271
298
|
2. 检查相对导入、重导出、字符串动态导入和 CSS 导入是否存在,并检查整个源码图的循环。
|
|
@@ -304,3 +331,5 @@ Codex 设置中的模型显示偏好由网页后端配置持久保存并广播
|
|
|
304
331
|
上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
|
|
305
332
|
|
|
306
333
|
长历史首屏读取最近 100 条消息;首屏全部属于同一轮次且仍有历史时,后续按每页一个完整轮次恢复,减少工具密集对话的串行网络往返。首屏跨轮次时继续使用消息分页,保持短轮次对话的读取效率;两条路径均保留完整历史、轮内顺序、实时更新优先和切换隔离。
|
|
334
|
+
|
|
335
|
+
网页更新由 `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.0.
|
|
33
|
-
npm install -g ./claudex-web-4.0.
|
|
31
|
+
sha256sum -c claudex-web-4.1.0.tgz.sha256
|
|
32
|
+
npm install -g ./claudex-web-4.1.0.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,6 +80,8 @@ 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`,同步生成并提交兼容资源;普通构建与发行包安装直接使用这些资源。验证时同时检查浏览器实际请求的图标地址、响应类型及标签页显示,手机浏览器的验证独立于窄屏页面布局检查。
|
|
@@ -160,6 +163,8 @@ CLAUDE_EXECUTABLE=/absolute/path/to/claude MODEL_BASE_URL=https://model.example
|
|
|
160
163
|
|
|
161
164
|
脚本将“介绍这个文件夹里面各个文件的功能”的请求原文交给真实 Claude Code,以临时配置和原生计划模式读取指定目录。验证成功的工具响应包含实际源码 API、最终正文覆盖目录文件与公开 API、全部模型请求返回 200,以及目标文件 SHA-256 前后相同。`MODEL_API_KEY` 按服务认证要求设置,`VALIDATION_OUTPUT` 可指定证据目录,默认 `.cache/backend-acceptance/original-user-case`。证据包含 `answer.md`、工具事件、原生会话、请求响应和结果报告。该入口读取已有目录,写入仅发生在临时配置及证据目录中。
|
|
162
165
|
|
|
166
|
+
`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`。测试始终使用临时原生目录与网页状态目录。
|
|
167
|
+
|
|
163
168
|
### 客户端与既有网页行为查验
|
|
164
169
|
|
|
165
170
|
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 项命令以当前仓库注册表为准。
|
|
@@ -383,3 +388,9 @@ Ubuntu 安装指引回归在设备选择器中实际切换 Ubuntu,检查 DER
|
|
|
383
388
|
对话拖拽回归使用 `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
389
|
|
|
385
390
|
批注换行边界回归在构建后执行 `ANNOTATION_WRAPPING=1 CHROME_PATH=/path/to/chromium node tests/browser/annotations.mjs`,使用隔离浏览器与模拟历史,逐字覆盖窄字符、中文长文、深浅主题及删除后收起。结果保存在 `.cache/annotations-browser/wrapping-results.json`。
|
|
391
|
+
|
|
392
|
+
### 本地思考内容翻译验证
|
|
393
|
+
|
|
394
|
+
中途进入运行中会话的回归执行 `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 演示图展示已结束对话,沿用现有截图。
|
|
395
|
+
|
|
396
|
+
构建后执行 `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/`,测试结束后清理浏览器与临时配置。
|
|
@@ -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))
|
package/docs/versioning.md
CHANGED
|
@@ -47,6 +47,8 @@ v2.0.0 标签上的干净代码 2.0.0 正式发
|
|
|
47
47
|
|
|
48
48
|
## 准备和发布
|
|
49
49
|
|
|
50
|
+
README 和部署文档的默认安装命令使用 `npm install -g @hjd-hitsz/claudex-web`,由 npm 的 `latest` 分发标签选择最新稳定版本。版本准备保留此命令,单独更新固定版本下载与校验示例;预发布提供对应版本的独立安装入口,转正式版时移除预发布入口。
|
|
51
|
+
|
|
50
52
|
用户指定具体版本号或 `patch`、`minor`、`major` 级别后,直接使用该版本,或从当前正式版本计算目标版本并执行发布;同一发布批次沿用该目标完成准备、提交、推送、发布和失败重试。用户尚未指定版本或级别、或需要改变已指定目标时,再确认建议版本及依据。
|
|
51
53
|
|
|
52
54
|
1. 审阅未发布条目,按整个批次的兼容性影响选择版本。
|
|
@@ -117,3 +119,11 @@ GitHub cron 补偿 ─┘ ↓
|
|
|
117
119
|
- `curl http://127.0.0.1:8766/healthz` 返回 `ready` 与桥接进程的 `version` 对象。HTTP 200 / 503 继续表示后端连接就绪 / 未就绪。
|
|
118
120
|
|
|
119
121
|
前端重新构建并刷新后显示新网页标识;桥接版本随进程重启更新。全局命令查看当前磁盘安装包,健康接口查看正在运行的进程。升级排查时同时核对这两个来源。
|
|
122
|
+
|
|
123
|
+
## npm 自动发布
|
|
124
|
+
|
|
125
|
+
`Publish npm package`(`npm-publish.yml`)监听 `Publish release` 和 `Publish scheduled releases` 的成功运行,通过 npm Trusted Publishing 获取 OIDC 发布凭据。Trusted Publisher 绑定实际 GitHub 仓库和 `npm-publish.yml`,允许直接执行 `npm publish`。工作流使用 GitHub 托管 runner,授予 `id-token: write`。
|
|
126
|
+
|
|
127
|
+
即时发布按来源提交选取公开标签,定时发布读取已到期计划并要求 Release 已公开。流程下载发行包及校验文件,核对包名、版本、构建提交和标签,临时全局安装验证后上传 npm。稳定版使用 `latest`,预发布使用 `next`。同版本重试核对已发布内容,内容不一致时报错。上传后轮询公开状态并校验下载,最长等待 15 分钟。
|
|
128
|
+
|
|
129
|
+
重试使用 Actions 的 `Publish npm package` 手动入口,`tag` 填已有公开标签。核对 GitHub Release、npm 公开下载和安装结果后确认发布完成。
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hjd-hitsz/claudex-web",
|
|
3
|
-
"version": "4.0
|
|
3
|
+
"version": "4.1.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Codex 与 Claude Code 的浏览器工作台",
|
|
6
6
|
"license": "GPL-3.0-only",
|
|
7
7
|
"engines": {
|
|
8
|
-
"node": ">=24"
|
|
8
|
+
"node": ">=24.5"
|
|
9
9
|
},
|
|
10
10
|
"bin": {
|
|
11
11
|
"claudex-web": "bin/claudex-web.mjs"
|
|
@@ -22,21 +22,28 @@
|
|
|
22
22
|
"scripts/start-backend.mjs",
|
|
23
23
|
"scripts/restart-when-idle.mjs",
|
|
24
24
|
".env.example",
|
|
25
|
-
"docs/"
|
|
25
|
+
"docs/",
|
|
26
|
+
"packages/translation-engine/src/",
|
|
27
|
+
"packages/translation-engine/native/",
|
|
28
|
+
"packages/translation-engine/bin/",
|
|
29
|
+
"packages/translation-engine/package.json",
|
|
30
|
+
"packages/translation-engine/LICENSE",
|
|
31
|
+
"packages/translation-engine/README.md"
|
|
26
32
|
],
|
|
27
33
|
"workspaces": [
|
|
28
34
|
"client",
|
|
29
|
-
"server"
|
|
35
|
+
"server",
|
|
36
|
+
"packages/translation-engine"
|
|
30
37
|
],
|
|
31
38
|
"scripts": {
|
|
32
39
|
"dev": "npm run dev --workspace @claudex-web/client",
|
|
33
|
-
"build": "npm run build --workspace @claudex-web/client",
|
|
40
|
+
"build": "npm run build --workspace @claudex-web/translation-engine && npm run build --workspace @claudex-web/client",
|
|
34
41
|
"icons:generate": "node scripts/generate-icons.mjs",
|
|
35
42
|
"prepack": "npm run build",
|
|
36
43
|
"start": "node --env-file-if-exists=.env server/src/server.mjs",
|
|
37
44
|
"start:backend": "node --env-file-if-exists=.env scripts/start-backend.mjs",
|
|
38
45
|
"test": "npm run test:unit && npm run test:components",
|
|
39
|
-
"test:unit": "node --test client/tests/*.test.js server/tests/*.test.mjs tests/architecture.test.mjs tests/version.test.mjs tests/release.test.mjs",
|
|
46
|
+
"test:unit": "node --test client/tests/*.test.js server/tests/*.test.mjs tests/architecture.test.mjs tests/version.test.mjs tests/release.test.mjs tests/npm-release.test.mjs packages/translation-engine/tests/*.test.mjs",
|
|
40
47
|
"test:components": "node scripts/test-components.mjs",
|
|
41
48
|
"test:package": "npm run build && node --test tests/package.test.mjs",
|
|
42
49
|
"version:check": "node scripts/version.mjs check",
|
|
@@ -63,10 +70,20 @@
|
|
|
63
70
|
"dependencies": {
|
|
64
71
|
"@anthropic-ai/claude-agent-sdk": "0.3.318",
|
|
65
72
|
"node-pty": "1.1.0",
|
|
66
|
-
"ws": "8.22.0"
|
|
73
|
+
"ws": "8.22.0",
|
|
74
|
+
"@claudex-web/translation-engine": "file:packages/translation-engine",
|
|
75
|
+
"fflate": "0.8.2"
|
|
67
76
|
},
|
|
68
77
|
"repository": {
|
|
69
78
|
"type": "git",
|
|
70
79
|
"url": "git+https://github.com/hjd-hitsz/claudex-web.git"
|
|
80
|
+
},
|
|
81
|
+
"homepage": "https://github.com/hjd-hitsz/claudex-web#readme",
|
|
82
|
+
"bugs": {
|
|
83
|
+
"url": "https://github.com/hjd-hitsz/claudex-web/issues"
|
|
84
|
+
},
|
|
85
|
+
"publishConfig": {
|
|
86
|
+
"access": "public",
|
|
87
|
+
"registry": "https://registry.npmjs.org/"
|
|
71
88
|
}
|
|
72
89
|
}
|