@hjd-hitsz/claudex-web 0.0.0-stage → 4.0.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/.env.example +27 -0
- package/CHANGELOG.md +449 -0
- package/LICENSE +674 -0
- package/README.md +128 -2
- package/bin/claudex-web.mjs +129 -0
- package/build-info.json +8 -0
- package/client/dist/_baseMerge.js +1 -0
- package/client/dist/abnfDiagram-WEYOIA3C.js +1 -0
- package/client/dist/apl.js +1 -0
- package/client/dist/app.js +393 -0
- package/client/dist/apple-touch-icon.png +0 -0
- package/client/dist/arc.js +1 -0
- package/client/dist/architectureDiagram-ZHVYKT53.js +36 -0
- package/client/dist/asciiarmor.js +1 -0
- package/client/dist/asn1.js +1 -0
- package/client/dist/asterisk.js +1 -0
- package/client/dist/blockDiagram-RJAE7QA3.js +140 -0
- package/client/dist/brainfuck.js +1 -0
- package/client/dist/c4Diagram-XDPPPE54.js +38 -0
- package/client/dist/channel.js +1 -0
- package/client/dist/chunk-2E7WHVMD.js +88 -0
- package/client/dist/chunk-2Q5K7J3B.js +1 -0
- package/client/dist/chunk-4EMNKR2T.js +1 -0
- package/client/dist/chunk-55XCU76K.js +1 -0
- package/client/dist/chunk-5VM5RSS4.js +15 -0
- package/client/dist/chunk-JWPE2WC7.js +1 -0
- package/client/dist/chunk-VQ5W62QI.js +1 -0
- package/client/dist/chunk-XXDRQBXY.js +1 -0
- package/client/dist/chunk-ZCHMQSOR.js +2 -0
- package/client/dist/classDiagram-v2-4MYWR3UA.js +217 -0
- package/client/dist/clike.js +1 -0
- package/client/dist/clojure.js +1 -0
- package/client/dist/cmake.js +1 -0
- package/client/dist/cobol.js +1 -0
- package/client/dist/code-highlight-style.js +13 -0
- package/client/dist/coffeescript.js +1 -0
- package/client/dist/commonlisp.js +1 -0
- package/client/dist/cose-bilkent-JH36ORCC.js +1 -0
- package/client/dist/crystal.js +1 -0
- package/client/dist/css.js +1 -0
- package/client/dist/cynefin-EF2NZ3EQ.js +141 -0
- package/client/dist/cynefinDiagram-WF24UDRP.js +62 -0
- package/client/dist/cypher.js +1 -0
- package/client/dist/cytoscape.esm.js +321 -0
- package/client/dist/d.js +1 -0
- package/client/dist/dagre-NK4GIZVX.js +4 -0
- package/client/dist/defaultLocale.js +1 -0
- package/client/dist/diagram-CBK3MWTC.js +24 -0
- package/client/dist/diagram-I5XIIV2D.js +24 -0
- package/client/dist/diagram-ODIL2UCW.js +30 -0
- package/client/dist/diagram-PFBEJUXE.js +3 -0
- package/client/dist/diagram-RJA3I4VV.js +41 -0
- package/client/dist/diagram-TYUNFSNR.js +200 -0
- package/client/dist/diff.js +1 -0
- package/client/dist/dockerfile.js +1 -0
- package/client/dist/document-editor.js +1040 -0
- package/client/dist/dtd.js +1 -0
- package/client/dist/dylan.js +1 -0
- package/client/dist/ebnf.js +1 -0
- package/client/dist/ebnfDiagram-V4P3TTPT.js +1 -0
- package/client/dist/ecl.js +1 -0
- package/client/dist/eiffel.js +1 -0
- package/client/dist/elk-QONTBCTQ.js +27 -0
- package/client/dist/elm.js +1 -0
- package/client/dist/erDiagram-KYQIGQAA.js +99 -0
- package/client/dist/erlang.js +1 -0
- package/client/dist/factor.js +1 -0
- package/client/dist/favicon.ico +0 -0
- package/client/dist/favicon.png +0 -0
- package/client/dist/fcl.js +1 -0
- package/client/dist/file-panel.js +1 -0
- package/client/dist/flowDiagram-IUGLLWBU.js +213 -0
- package/client/dist/forth.js +1 -0
- package/client/dist/fortran.js +1 -0
- package/client/dist/ganttDiagram-R7GPNTJY.js +292 -0
- package/client/dist/gas.js +1 -0
- package/client/dist/gherkin.js +1 -0
- package/client/dist/gitGraphDiagram-PDYL7XHY.js +106 -0
- package/client/dist/graph.js +1 -0
- package/client/dist/groovy.js +1 -0
- package/client/dist/haskell.js +1 -0
- package/client/dist/haxe.js +1 -0
- package/client/dist/http.js +1 -0
- package/client/dist/idl.js +1 -0
- package/client/dist/index.html +25 -0
- package/client/dist/index.js +2 -0
- package/client/dist/index10.js +1 -0
- package/client/dist/index11.js +1 -0
- package/client/dist/index12.js +1 -0
- package/client/dist/index13.js +7 -0
- package/client/dist/index14.js +1 -0
- package/client/dist/index15.js +1 -0
- package/client/dist/index16.js +6 -0
- package/client/dist/index17.js +1 -0
- package/client/dist/index18.js +3 -0
- package/client/dist/index19.js +1 -0
- package/client/dist/index2.js +1 -0
- package/client/dist/index20.js +1 -0
- package/client/dist/index21.js +1 -0
- package/client/dist/index22.js +1 -0
- package/client/dist/index3.js +1 -0
- package/client/dist/index4.js +1 -0
- package/client/dist/index5.js +1 -0
- package/client/dist/index6.js +13 -0
- package/client/dist/index7.js +1 -0
- package/client/dist/index8.js +1 -0
- package/client/dist/index9.js +1 -0
- package/client/dist/infoDiagram-MVDRKAX5.js +2 -0
- package/client/dist/init.js +1 -0
- package/client/dist/isArrayLikeObject.js +1 -0
- package/client/dist/ishikawaDiagram-HPEHV2GE.js +70 -0
- package/client/dist/javascript.js +1 -0
- package/client/dist/journeyDiagram-BOSHW7O7.js +139 -0
- package/client/dist/julia.js +1 -0
- package/client/dist/kanban-definition-FNSA4HC5.js +89 -0
- package/client/dist/katex.js +257 -0
- package/client/dist/linear.js +1 -0
- package/client/dist/livescript.js +1 -0
- package/client/dist/lua.js +1 -0
- package/client/dist/mathematica.js +1 -0
- package/client/dist/mbox.js +1 -0
- package/client/dist/mermaid.core.js +310 -0
- package/client/dist/mindmap-definition-6OY57UG3.js +98 -0
- package/client/dist/mirc.js +1 -0
- package/client/dist/mllike.js +1 -0
- package/client/dist/modelica.js +1 -0
- package/client/dist/mscgen.js +1 -0
- package/client/dist/mumps.js +1 -0
- package/client/dist/nginx.js +1 -0
- package/client/dist/notification-worker.js +45 -0
- package/client/dist/nsis.js +1 -0
- package/client/dist/ntriples.js +1 -0
- package/client/dist/octave.js +1 -0
- package/client/dist/ordinal.js +1 -0
- package/client/dist/oz.js +1 -0
- package/client/dist/pascal.js +1 -0
- package/client/dist/pegDiagram-ECIUJNBX.js +1 -0
- package/client/dist/perl.js +1 -0
- package/client/dist/pieDiagram-GNMPY74T.js +39 -0
- package/client/dist/pig.js +1 -0
- package/client/dist/powershell.js +1 -0
- package/client/dist/properties.js +1 -0
- package/client/dist/protobuf.js +1 -0
- package/client/dist/pug.js +1 -0
- package/client/dist/puppet.js +1 -0
- package/client/dist/purify.es.js +3 -0
- package/client/dist/python.js +1 -0
- package/client/dist/q.js +1 -0
- package/client/dist/quadrantDiagram-D57K4MC3.js +7 -0
- package/client/dist/r.js +1 -0
- package/client/dist/railroadDiagram-Y72NRBL7.js +1 -0
- package/client/dist/requirementDiagram-EQYSW5RA.js +84 -0
- package/client/dist/rpm.js +1 -0
- package/client/dist/ruby.js +1 -0
- package/client/dist/sankeyDiagram-SY24JHO5.js +40 -0
- package/client/dist/sas.js +1 -0
- package/client/dist/scheme.js +1 -0
- package/client/dist/sequenceDiagram-BLEHNHQU.js +169 -0
- package/client/dist/shell.js +1 -0
- package/client/dist/sieve.js +1 -0
- package/client/dist/simple-mode.js +1 -0
- package/client/dist/sizeCapture-INFHLROL.js +1 -0
- package/client/dist/smalltalk.js +1 -0
- package/client/dist/solr.js +1 -0
- package/client/dist/sparql.js +1 -0
- package/client/dist/spreadsheet.js +1 -0
- package/client/dist/sql.js +1 -0
- package/client/dist/stateDiagram-v2-A6IESKWZ.js +291 -0
- package/client/dist/stex.js +1 -0
- package/client/dist/style.css +1 -0
- package/client/dist/stylus.js +1 -0
- package/client/dist/swift.js +1 -0
- package/client/dist/swimlanes-B3ENRKFQ.js +1 -0
- package/client/dist/swimlanesDiagram-AYQRV4AK.js +8 -0
- package/client/dist/tcl.js +1 -0
- package/client/dist/terminal-panel.js +18 -0
- package/client/dist/textile.js +1 -0
- package/client/dist/tiddlywiki.js +1 -0
- package/client/dist/tiki.js +1 -0
- package/client/dist/timeline-definition-JXYKGLGB.js +120 -0
- package/client/dist/toml.js +1 -0
- package/client/dist/troff.js +1 -0
- package/client/dist/ttcn-cfg.js +1 -0
- package/client/dist/ttcn.js +1 -0
- package/client/dist/turtle.js +1 -0
- package/client/dist/usecaseDiagram-WPOLBNNX.js +370 -0
- package/client/dist/vb.js +1 -0
- package/client/dist/vbscript.js +1 -0
- package/client/dist/velocity.js +1 -0
- package/client/dist/vennDiagram-Q3Y3IDCW.js +34 -0
- package/client/dist/verilog.js +1 -0
- package/client/dist/vhdl.js +1 -0
- package/client/dist/wardleyDiagram-IVAIDKWA.js +78 -0
- package/client/dist/webidl.js +1 -0
- package/client/dist/xquery.js +1 -0
- package/client/dist/xychartDiagram-4URNHDU4.js +7 -0
- package/client/dist/yacas.js +1 -0
- package/client/dist/z80.js +1 -0
- package/docs/architecture/backend-regressions.md +53 -0
- package/docs/architecture/backends.md +113 -0
- package/docs/architecture/behavior.md +206 -0
- package/docs/architecture.md +306 -0
- package/docs/background-tasks.md +39 -0
- package/docs/cli-command-coverage.md +60 -0
- package/docs/deployment.md +269 -0
- package/docs/development.md +385 -0
- package/docs/images/desktop-dark.png +0 -0
- package/docs/images/desktop-light.png +0 -0
- package/docs/images/mobile-sidebar.png +0 -0
- package/docs/images/mobile.png +0 -0
- package/docs/releases/v2.0.0.md +5 -0
- package/docs/releases/v2.1.0.md +6 -0
- package/docs/releases/v2.1.1.md +6 -0
- package/docs/releases/v2.1.2.md +8 -0
- package/docs/releases/v2.2.0.md +11 -0
- package/docs/releases/v2.3.0.md +12 -0
- package/docs/releases/v2.3.1.md +8 -0
- package/docs/releases/v2.4.0.md +8 -0
- package/docs/releases/v2.4.1.md +8 -0
- package/docs/releases/v2.4.2.md +8 -0
- package/docs/releases/v3.0.0.md +9 -0
- package/docs/releases/v3.1.0.md +10 -0
- package/docs/releases/v3.1.1.md +7 -0
- package/docs/releases/v4.0.0-beta.1.md +10 -0
- package/docs/releases/v4.0.0.md +20 -0
- package/docs/releases/v4.0.1.md +10 -0
- package/docs/versioning.md +119 -0
- package/package.json +70 -4
- package/scripts/install-services.mjs +134 -0
- package/scripts/restart-when-idle.mjs +125 -0
- package/scripts/start-backend.mjs +29 -0
- package/server/src/agent-messages.mjs +124 -0
- package/server/src/application.mjs +133 -0
- package/server/src/auth.mjs +328 -0
- package/server/src/backends/claude/account.mjs +171 -0
- package/server/src/backends/claude/adapter.mjs +366 -0
- package/server/src/backends/claude/agent-history.mjs +70 -0
- package/server/src/backends/claude/background-tasks.mjs +168 -0
- package/server/src/backends/claude/catalogue.mjs +266 -0
- package/server/src/backends/claude/execution-errors.mjs +44 -0
- package/server/src/backends/claude/execution-session.mjs +390 -0
- package/server/src/backends/claude/git-tool-changes.mjs +77 -0
- package/server/src/backends/claude/goals.mjs +319 -0
- package/server/src/backends/claude/history-actions.mjs +170 -0
- package/server/src/backends/claude/history.mjs +65 -0
- package/server/src/backends/claude/hooks.mjs +232 -0
- package/server/src/backends/claude/input-stream.mjs +24 -0
- package/server/src/backends/claude/messages-request.mjs +34 -0
- package/server/src/backends/claude/messages.mjs +300 -0
- package/server/src/backends/claude/model-options.mjs +18 -0
- package/server/src/backends/claude/native-commands.mjs +48 -0
- package/server/src/backends/claude/native-records.mjs +76 -0
- package/server/src/backends/claude/process-ownership.mjs +82 -0
- package/server/src/backends/claude/project-instructions.mjs +40 -0
- package/server/src/backends/claude/provider-balance.mjs +40 -0
- package/server/src/backends/claude/provider-environment.mjs +93 -0
- package/server/src/backends/claude/provider-transport.mjs +70 -0
- package/server/src/backends/claude/recovery.mjs +54 -0
- package/server/src/backends/claude/runtime.mjs +463 -0
- package/server/src/backends/claude/session-worker.mjs +32 -0
- package/server/src/backends/claude/sessions.mjs +347 -0
- package/server/src/backends/claude/token-usage.mjs +98 -0
- package/server/src/backends/claude/worker-client.mjs +344 -0
- package/server/src/backends/claude/worker-launcher.mjs +119 -0
- package/server/src/backends/claude/worker-location.mjs +31 -0
- package/server/src/backends/claude/worker-revision.mjs +45 -0
- package/server/src/backends/claude/worker-server.mjs +290 -0
- package/server/src/backends/cli-installation.mjs +140 -0
- package/server/src/backends/codex/adapter.mjs +153 -0
- package/server/src/backends/codex/compaction-recovery.mjs +78 -0
- package/server/src/backends/codex/events.mjs +125 -0
- package/server/src/backends/codex/methods.mjs +17 -0
- package/server/src/backends/codex/reference-mcp.mjs +97 -0
- package/server/src/backends/codex/reference-tools.mjs +71 -0
- package/server/src/backends/codex/requests.mjs +170 -0
- package/server/src/backends/codex/subscriptions.mjs +91 -0
- package/server/src/backends/codex/upstream.mjs +148 -0
- package/server/src/backends/configuration.mjs +122 -0
- package/server/src/backends/identity-mapping.mjs +87 -0
- package/server/src/backends/manager.mjs +412 -0
- package/server/src/backends/network-proxy.mjs +55 -0
- package/server/src/backends/provider-presets.mjs +45 -0
- package/server/src/backends/providers.mjs +132 -0
- package/server/src/backends/storage.mjs +35 -0
- package/server/src/bridge/conversation-policy.mjs +29 -0
- package/server/src/bridge/file-operations.mjs +47 -0
- package/server/src/bridge/product-methods.mjs +66 -0
- package/server/src/compaction.mjs +82 -0
- package/server/src/config.mjs +57 -0
- package/server/src/file-content.mjs +99 -0
- package/server/src/file-undo.mjs +142 -0
- package/server/src/http/router.mjs +80 -0
- package/server/src/http/static.mjs +62 -0
- package/server/src/product-config.mjs +80 -0
- package/server/src/project-models.mjs +59 -0
- package/server/src/rpc-transport.mjs +21 -0
- package/server/src/server.mjs +20 -0
- package/server/src/summary-translation.mjs +82 -0
- package/server/src/system-auth.mjs +45 -0
- package/server/src/thread-folders.mjs +76 -0
- package/server/src/thread-names.mjs +264 -0
- package/server/src/thread-projects.mjs +36 -0
- package/server/src/tls.mjs +87 -0
- package/server/src/version.mjs +55 -0
- package/server/src/web-config-migration.mjs +48 -0
- package/server/src/workspace/commands.mjs +33 -0
- package/server/src/workspace/files.mjs +44 -0
- package/server/src/workspace/service.mjs +27 -0
- package/server/src/workspace/terminals.mjs +122 -0
- package/shared/backend-activity.mjs +13 -0
- package/shared/backend-capabilities.mjs +33 -0
- package/shared/backend-identity.mjs +17 -0
- package/shared/compaction-state.mjs +49 -0
- package/shared/file-types.mjs +82 -0
- package/shared/product-contract.mjs +26 -0
- package/shared/rpc-limits.mjs +2 -0
- package/shared/terminal-workspace.mjs +26 -0
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# 双后端回归审查
|
|
2
|
+
|
|
3
|
+
本轮对照起点为 `main` 的 `479de3d` 与双后端分支的 `37209e4`。本记录以 Codex 单后端 `main` 的产品行为为基线,审查双后端引入的共享流程变化与 Claude 消息适配。测试使用临时目录、模拟传输及隔离浏览器,原生运行测试使用真实 Claude CLI/SDK 和本地模拟 Messages 服务。
|
|
4
|
+
|
|
5
|
+
## 已修复问题与依据
|
|
6
|
+
|
|
7
|
+
- 旧网页未分类目录:网页配置根目录迁移后,分类只接收新根路径。管理器现同时发布当前根路径与所属 Codex 配置中的旧根路径;已固定目录、明确项目归属、其他创建者及子目录继续按原规则分类。
|
|
8
|
+
- 桌面未分类索引:索引曾路由到当前后端,使 Claude 选择期间读取错误的原生目录。管理器统一从 Codex 状态读取;启用状态与当前模型独立。
|
|
9
|
+
- 用户消息 Markdown:气泡曾直接输出文本。现复用现有安全 Markdown 渲染器;文件引用通过文本节点转换,代码、公式及已有链接保留语义,复制与编辑保留源码。
|
|
10
|
+
- Claude 内部记录:后台通知、合成消息和仅供原生终端显示的中断记录曾创建用户气泡及轮次。转换依据原生来源字段区分;CLI 2.1.318 的 SDK 中断附加记录可能只继承 `entrypoint=sdk-ts` 与 `promptId`,没有 `isVisibleInTranscriptOnly`。此类缺少 `promptSource`、`turnOrigin`、`turnPosition` 和 `origin` 的记录归入内部输入。SDK 实时帧缺少这些入口字段时,使用本轮实际提交的输入 UUID 确认用户归属。工具结果继续更新工具项,用户输入相同正文保持可见。自动唤醒采用保存的轮次锚点。回归同时使用带标记与无标记的记录结构,分别核对直接转换、SDK 历史恢复和浏览器展示。
|
|
11
|
+
- 子代理事件归属:转发的子代理帧曾先经过主会话的自动轮次、任务和用量处理。现先隔离转发帧与重放帧,再处理主会话生命周期。
|
|
12
|
+
- 旧项目模型偏好:服务端只读取新配置目录。目标文件缺失时读取旧网页偏好,修改时将完整内容写入新目录,已有目标文件优先。
|
|
13
|
+
- 项目偏好同步:激活后端曾关闭同步而未重新开启;跨后端共享单个在途写入还会阻塞新后端保存。现激活后重新同步,按后端管理写入,并检查连接实例隔离旧响应;默认模型及思考强度从所属后端配置读取。
|
|
14
|
+
- 初始化迟到:启动时的旧模型与配置响应可能覆盖期间切换的对话或后端。初始化应用设置前检查启动时后端与导航版本,列表恢复继续按原有打开版本保护。
|
|
15
|
+
- 单后端恢复:桥接整体保持在线时,所属后端由未就绪恢复为就绪会重新恢复模型、历史和写入状态,保留原消息区及草稿。额度、技能及待核对输入跟随后端就绪状态停止和恢复读取;队列刷新按请求版本隔离迟到结果。
|
|
16
|
+
- 后端目录迟到:模型目录和账户读取现同时检查激活版本、后端、目录及连接实例,断线或替换连接后停止应用旧结果。
|
|
17
|
+
- 列表初始化失败:启用后端构造失败时曾直接从汇总列表中消失。现将其保留为有明确后端标识的读取错误,已有记录由前端保留及提供重试。
|
|
18
|
+
- 证书与登录迁移:自动证书与登录文件随目录切换重新创建。现只在目标目录缺失时原子复制已有网页自有文件,保持受限权限及旧文件;证书对缺失时提供明确错误。
|
|
19
|
+
- 后端启停列表:停用后端后曾只更新后端配置,所属对话与当前对话保留到页面刷新。现由桥接状态通知触发列表重新读取,停用后立即移除所属对话,正在查看的所属对话回到新对话,并清除被停用后端的模型选择;重新启用后恢复显示。
|
|
20
|
+
|
|
21
|
+
## 网页交互对照
|
|
22
|
+
|
|
23
|
+
使用 `tests/browser/backend-interactions.mjs` 对 `main` 与双后端各自的独立生产构建执行相同步骤,覆盖工作区收放、搜索弹窗、技能目录、运行中模型选择、思考强度键盘收起、Enter 换行、草稿保留、深浅主题、80%~200% 缩放与手机侧栏。构建目录通过 `UI_BUILD_DIR` 指定,`UI_MAIN=1` 标记基线;修复前双后端构建通过 `UI_BEFORE=1` 记录退化状态。截图和几何数据保存在 `.cache/backend-interactions/`。双后端额外通过 Chrome 设置中的实际页面缩放验证桌面与窄屏各自的深浅主题及五档缩放,核对 `devicePixelRatio`、实际视口、输入框高度和控件边界;结果位于其 `browser-zoom/report.json`。
|
|
24
|
+
|
|
25
|
+
- 同供应商的模型选择保留 `main` 在运行期间为下一轮调整参数的操作;跨供应商调整等当前轮次结束后进行。
|
|
26
|
+
- Claude 同供应商切换模型保留技能、命令和代理目录,恢复连接及刷新配置时保留同一账户已读取的额度。
|
|
27
|
+
- 新草稿先恢复已选择的供应商,再读取所属模型、账户及项目偏好,避免初始化的原生默认值替换供应商选择。
|
|
28
|
+
- 窄屏保留顶部项目名称及目录选择入口,后端标识继续采用独立图标。
|
|
29
|
+
- Claude 原生额度窗口到期后自动校准;Codex 同一账户切换工作目录时保留已展开的额度详情。
|
|
30
|
+
- 信息提示层保持可见并让鼠标事件到达下方控件,验证已有 `AGENTS.md` 提示仍显示时点击发送重试。
|
|
31
|
+
- 旧浏览器脚本改为操作实际富文本输入;详情重置脚本显式展开默认折叠的项目后再切换对话。
|
|
32
|
+
|
|
33
|
+
## 验证入口
|
|
34
|
+
|
|
35
|
+
- `server/tests/backend-product-contract.test.mjs`:两端实际适配器执行同一套网页操作,覆盖离线偏好、旧目录继承、保存成功通知、验证和写入失败后的重试、目录创建、整理占用及历史读取。传输为模拟 app-server,Claude 仅检查版本,原生模型执行单独验证。
|
|
36
|
+
- `server/tests/codex-close-lifecycle.test.mjs` 与 `subscriptions.test.mjs`:取消订阅确认和实际关闭分别到达、顺序交换、断线清理及关闭后重新恢复。`tests/integration/codex-subscription-release.mjs` 通过真实 CLI 和适配器执行八组立即重新打开,使用人工历史,模型轮次数为零。原生响应语义见 [app-server 协议](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)。
|
|
37
|
+
- `server/tests/backend-routing.test.mjs`:工作区根据适配器所有者声明路由,浏览器关闭只通过 `releaseClient` 释放所属代理;管理器保持与原生订阅集合隔离。`tests/architecture.test.mjs` 同时核对公共桥接、原生适配器和 HTTP 的依赖边界。
|
|
38
|
+
- `client/tests/backend-connection-recovery.test.js` 与组件输入队列回归:单后端恢复、另一后端状态隔离、草稿保留及队列迟到隔离。
|
|
39
|
+
- `client/tests/thread-order.test.js`:新旧目录、来源判定、明确归属、完整分页、活动排序及迟到事件。
|
|
40
|
+
- `client/tests/backend-project-models.test.js`:激活后项目同步、原生默认强度、跨后端在途写入与缓存隔离。
|
|
41
|
+
- `server/tests/backend-routing.test.mjs`:相同原生标识隔离、后端初始化失败及全局未分类索引。
|
|
42
|
+
- `server/tests/claude-internal-history.test.mjs`:后台通知、中断、合成记录与相同文字的人类输入。
|
|
43
|
+
- `server/tests/project-models.test.mjs` 与 `web-config-migration.test.mjs`:旧配置继承、目标优先、原文件保留及文件权限。
|
|
44
|
+
- `tests/integration/claude-message-provenance.mjs`:真实 SDK 读取临时原生记录,验证来源字段在历史恢复中保留。
|
|
45
|
+
- `tests/browser/backend-regressions.mjs`:生产构建下的分组、Markdown、引用键盘打开、Claude 历史、刷新、深浅主题、规定缩放和窄屏。截图及构建来源保存到 `.cache/backend-regressions/`。
|
|
46
|
+
- `client/tests/backend-toggle.test.js`:核对启停快照同步过滤列表和模型选项、迟到响应与实时插入隔离、当前及待打开对话退出,以及两个后端全部停用和恢复。
|
|
47
|
+
- `tests/browser/backend-toggle.mjs`:实际点击设置中的后端启停,核对停用后对话列表与当前对话立即更新、重新启用后恢复,以及两个后端全部停用后列表清空,且无需刷新页面;覆盖深浅主题、手机侧栏,并通过 `UI_BUILD_DIR` 与 `UI_BEFORE=1` 在旧构建上复现。截图保存到 `.cache/backend-toggle/`。
|
|
48
|
+
- 既有 `plans.mjs`、`message-editing.mjs` 与 `connection-recovery.mjs` 浏览器测试:计划收放及批准、编辑失败重试、重连期间草稿与消息区保留。
|
|
49
|
+
- `tests/browser/history-performance.mjs`:完整 33 页与 3210 条隔离记录、最近消息先显示、历史前插阅读位置、草稿及迟到分页隔离。
|
|
50
|
+
- `npm run check`:版本、架构、格式、单元、组件及临时全局安装。
|
|
51
|
+
- `npm run test:backends`:真实 Claude CLI 的会话、分支、文件 checkpoint、子代理、目标、目录、设置、项目指令、思考、运行生命周期、执行服务恢复及升级。
|
|
52
|
+
|
|
53
|
+
真实模型服务调用与真实外部账户额度需要对应环境单独验证;模拟 Messages 服务验证原生调用链、参数及生命周期。测试结果按实际执行来源报告。
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# 双后端产品契约与实施
|
|
2
|
+
|
|
3
|
+
Claudex Web 提供一致的浏览器工作台,连接一个 Codex app-server 和一个 Claude Code 运行时。模型选择决定执行后端,用户操作及其状态、错误恢复和数据保护规则由网页产品契约决定。后端适配层负责实现完整契约;原生协议差异在服务端吸收。既有 Codex 的正常调用链作为回归基线,Claude 适配补齐同一产品操作,共享实现按实际职责确定。
|
|
4
|
+
|
|
5
|
+
## 职责与依赖
|
|
6
|
+
|
|
7
|
+
```mermaid
|
|
8
|
+
flowchart TD
|
|
9
|
+
UI[统一网页:对话、输入、工作区、设置] --> UseCases[应用用例:操作与恢复规则]
|
|
10
|
+
UseCases --> Contract[产品操作契约与资源标识]
|
|
11
|
+
Contract --> Workspace[工作区服务:文件、命令、网页终端]
|
|
12
|
+
Contract --> Router[对话路由与后端生命周期]
|
|
13
|
+
Router --> Codex[Codex 适配器]
|
|
14
|
+
Router --> IPC[本机 IPC 客户端]
|
|
15
|
+
IPC --> Worker[Claude 独立执行服务]
|
|
16
|
+
Worker --> Claude[Claude Code 适配器]
|
|
17
|
+
Claude --> Sessions[原生会话与历史服务]
|
|
18
|
+
Claude --> Runs[执行、计划、整理、提问]
|
|
19
|
+
Claude --> Tasks[目标与后台任务]
|
|
20
|
+
Claude --> Extensions[模型、技能、插件、MCP]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
工作区目录浏览、文件保存和网页交互终端属于桥接主机。Codex 的工作区请求沿用原生 app-server;Claude 的查询和文件读取优先使用原生控制接口,超出原生读取大小范围的完整文件由已有认证 HTTP 服务传输。模型生成的文件变更、对话历史、计划与后台任务按所属对话保存;后台任务的管理与网页交互终端分别维护。
|
|
24
|
+
|
|
25
|
+
浏览器继续采用现有消息协议名称以兼容既有状态控制器。方法名是传输表示,产品契约中的功能分组、输入输出及生命周期才是适配器实现依据。`shared/product-contract.mjs` 将工作区方法与对话方法分别注册为 `workspaceMethods` 和 `conversationMethods`,供桥接按状态所有者路由。完整产品范围按下文的用户操作与状态契约维护,新增网页功能同步维护所属路由及实际操作验收。
|
|
26
|
+
|
|
27
|
+
### 适配器边界
|
|
28
|
+
|
|
29
|
+
管理器通过相同接口使用两个后端,Codex 原生实现位于 `backends/codex/`,Claude 原生实现位于 `backends/claude/`。接口的操作与生命周期约定如下:
|
|
30
|
+
|
|
31
|
+
- `connect()` 启动所属传输,`ready` 表达当前就绪状态,`capabilities` 提供真实模型参数与扩展能力。
|
|
32
|
+
- `receive(client, message)` 接收原生资源标识的请求或提问回答,通过注入的 `send` 返回同一请求编号的结果或错误,通过 `broadcast` 发布统一事件。管理器承担浏览器资源标识与原生标识的转换,用户正文和工具参数保持原样。
|
|
33
|
+
- `state()` 返回 `lan/state` 快照,其中活动轮次、提问、整理、原生命令及撤销结果均使用原生标识。网页手动终端独立使用工作区标识,由管理器合并工作区快照。Claude 执行服务补充后台任务、排队输入及内部命令占用。管理器汇总快照并加入网页配置与版本信息。
|
|
34
|
+
- `releaseClient(client)` 释放该适配器中属于指定浏览器代理的连接资源。Codex 清除订阅所有者并检查空闲释放,Claude 的模型会话独立于浏览器连接,释放浏览器保持执行服务运行。管理器只调用接口,订阅集合由 Codex 自己持有。
|
|
35
|
+
- `releaseUnusedThreads()` 按所属运行时的生命周期释放空闲资源;`close()` 关闭桥接连接并结算其在途请求。独立执行服务通过 `shutdown()` 原子检查实际占用并确认停止,网页桥接的 `close()` 只断开 IPC。
|
|
36
|
+
- `workspaceOwner` 明确工作区路由所有者:`backend` 保留原生工作区调用,`bridge` 使用管理器持有的主机工作区服务。Codex 选择前者,Claude 选择后者。管理器按声明路由,两端原生文件搜索与文件读取继续进入所属适配器。
|
|
37
|
+
|
|
38
|
+
`bridge/product-methods.mjs` 为两个适配器提供同一套网页操作处理器:项目模型读取与保存、目录创建、单文件撤销,以及注入的整理核对和子代理消息读取。模型偏好保存成功广播 `lan/projectModels/updated`,失败保留原文件并允许重试。Codex 继续读取网页配置目录中的偏好,并在目标文件缺失时继承旧目录;Claude 继续使用已有后端状态目录。管理器独立提供桌面端未分类目录索引,切换或停用后端保持相同来源。
|
|
39
|
+
|
|
40
|
+
公共写入规则只读取执行方提供的即时状态。整理占用期间暂停开始轮次、补充输入、审查、回退和再次整理;活动任务或待提交输入阻止新整理;单文件撤销占用期间暂停可能写入的相关操作。原生订阅恢复、会话变更锁和队列原子检查继续归所属适配器。两端共用产品规则,同时保留原生状态的唯一所有者。
|
|
41
|
+
|
|
42
|
+
## 完整功能范围
|
|
43
|
+
|
|
44
|
+
以下清单同时约束两个后端。共用界面只实现一次;运行时相关功能分别提供适配及契约回归。
|
|
45
|
+
|
|
46
|
+
- 对话与项目:创建、重命名、归档、恢复、删除、固定、搜索、实际活动时间排序、未分类目录、完整分页历史、最近页优先、分支与原地编辑重发。
|
|
47
|
+
- 输入:Markdown、GFM、公式、中文输入、快捷建议、全部现有命令、Ctrl+Enter、图片附件、文件和目录引用、回复批注、技能、即时发送、草稿及附件隔离。
|
|
48
|
+
- 执行:流式消息、思考与翻译、工作过程、命令及工具结果、运行中补充、中断、断线恢复、关闭网页后继续执行、完成通知及多页面去重。
|
|
49
|
+
- 计划:只读调查、方案流式正文、预览收放、修改、批准后执行、批准失败重试、刷新恢复及对话切换隔离。
|
|
50
|
+
- 整理:异步提交、常驻状态、写入门控、成功和失败、历史核对、刷新与多页面恢复。
|
|
51
|
+
- 工作区:文件和目录浏览、模糊查询、源码编辑及未保存缓冲区、差异、媒体和下载、变更汇总、单文件撤销、代码审查、网页交互终端。
|
|
52
|
+
- 目标:读取、设置、修改、暂停、恢复、清除、预算、实际用量、持续执行与完成状态。
|
|
53
|
+
- 后台任务:读取全部分页、呈现实际运行任务、停止全部后台终端、独立于当前轮次中断。
|
|
54
|
+
- 子代理:名称、任务、进度、初始任务和后续消息、完整历史、计划预览、切换隔离和失败重试。
|
|
55
|
+
- 配置与连接:账户或供应商身份、模型、思考强度、速度、项目默认选择、插件目录、MCP 状态与工具、后端独立故障、认证、证书、主题、字体、快捷键与版本。
|
|
56
|
+
|
|
57
|
+
账户余额和套餐等外部事实使用所属服务真实提供的数据,配置自定义供应商时保留供应商身份。使用量、读取失败与缺少外部数据分别表达,任何外部字段缺失均不能影响对话和工作区操作。
|
|
58
|
+
|
|
59
|
+
Claude Code 原生账户依据 SDK `initializationResult().account` 的实际认证来源确定。未登录时 `account/read` 返回空账户及 `usageSupported: false`,模型选择省去 CLI 在未登录状态仍返回的默认原生模型;配置供应商继续按其配置提供模型和身份。OAuth 认证、API Key 及外部原生提供方分别保留真实身份与适用的用量入口。
|
|
60
|
+
|
|
61
|
+
自定义模型的上下文容量由供应商模型参数中的 `contextWindow` 记录服务实际加载的 tokens 上限,并通过原生 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 配置保持 CLI 计量及整理策略一致。模型最大支持容量与当前服务加载容量分别核对;产品默认值保持为空。流式消息开始时即通过 `getContextUsage({detail: "summary"})` 读取原生容量,轮次结束再校准已用上下文;更换原生进程或模型时重新查询,查询失败保留实际用量及错误信息。
|
|
62
|
+
|
|
63
|
+
Claude Code 的附加能力通过后端扩展描述提供,采用显式命令、工具记录、任务和提问界面呈现。扩展描述保留参数及生命周期,前端无需根据后端名称硬编码功能路径。原生技能、插件、MCP 和子代理目录按当前工作目录与本机 CLI 原有配置读取。Codex 沿用 `CODEX_HOME`,Claude 沿用 `CLAUDE_CONFIG_DIR`,未设置时分别使用 `~/.codex` 和 `~/.claude`。网页自身配置与 Claude 执行状态存入 `CLAUDEX_WEB_CONFIG_DIR`,原生 `dataDir` 与网页 `stateDir` 分别传递。原生模式保留本机认证环境;用户显式选择供应商时,在首次输入前通过原生 `applyFlagSettings` 覆盖该会话的供应商环境,避免原有用户设置改变已选择的请求目标,原配置文件保持原样。
|
|
64
|
+
|
|
65
|
+
## 验收规则
|
|
66
|
+
|
|
67
|
+
能力声明用于描述真实的模型参数、外部账户数据和附加能力。完整功能范围中的通用入口始终可用,适配器承担能力转换。新增实现必须通过实际行为验证后才算完成,空结果和硬编码支持标记不能作为实现证据。
|
|
68
|
+
|
|
69
|
+
两端的验收场景覆盖创建、输入、执行、恢复、编辑、分支、计划、整理、审查、目标及任务,按具体操作记录证据。临时目录和模拟传输验证状态所有者及失败恢复;真实 CLI/SDK 配合隔离 Messages 服务验证原生会话、控制接口和工具;真实模型验证实际供应商调用与模型操作;浏览器验证界面、布局及完整用户流程。每项结果注明实际使用的 CLI、模型与传输来源。
|
|
70
|
+
|
|
71
|
+
每个异步结果携带所属资源和修订依据。切换模型、供应商、主对话、子代理及断线后,旧结果只归属原目标。历史与索引的修改保持原子性,编辑重发保留原生历史分叉并将网页对话重新指向保留后的会话。
|
|
72
|
+
|
|
73
|
+
## 已实现的模块与事实来源
|
|
74
|
+
|
|
75
|
+
- `workspace/service.mjs` 提供共用文件、目录与网页交互终端。网页手动终端统一使用 `lan/terminal/*`,在后端路由之前由工作区服务处理;node-pty 持有实际 shell 和前台进程名称,终端按绝对启动目录隔离,同目录跨模型后端保留,代理的原生命令与后台任务保持原有路径。管理器依据所属后端路由 `fuzzyFileSearch`:Codex 沿用原生 app-server,Claude Code 调用 SDK 的原生 `file_suggestions` 控制请求,复用 CLI 文件索引;查询初始化预热索引并按目录、供应商配置与对话隔离,两者使用相同输入建议和结果展示。
|
|
76
|
+
- `claude/sessions.mjs` 管理网页逻辑对话与原生会话的对应关系。`history-actions.mjs` 使用 SDK 原生分支保留消息前缀,依据原生 `forkedFrom.messageUuid` 重新建立轮次、补充输入和自动唤醒消息锚点,截断使用下一轮输入的 `parentUuid` 保留已完成轮次的全部输出附件;网页对话标识保持稳定。`nativeAliases` 将保留的历史分支归入同一逻辑对话,列表和删除后的恢复避免重复导入。
|
|
77
|
+
- `session-worker.mjs` 在独立工作进程中使用同一原生配置目录调用 SDK 会话 API;SDK 选择原生 `parentUuid` 链,`native-records.mjs` 通过 SDK `importSessionToStore` 加载临时内存快照,按 UUID 补回投影省略的时间、系统子类型及错误字段。原生正文和工具结果是事实来源,索引补充已确认的轮次状态、计划类型、错误分类和文件变更。
|
|
78
|
+
- `worker-client.mjs` 与独立 `worker-server.mjs` 通过受限本机 IPC 协作,执行服务持有 Claude 适配器、原生进程和后台任务。systemd 环境使用独立用户 service 及 cgroup,网页桥接关闭或崩溃后仍保留任务。IPC 目录 0700、socket 0600,双方核对用户归属。源码、入口路径或运行配置变化时,忙碌服务先继续执行,完全空闲后确认停止并替换,较旧桥接保持较新执行代际。
|
|
79
|
+
- `runtime.mjs` 管理每个逻辑对话的活动轮次、待提交输入和原生进程;`execution-session.mjs` 持有可持续接收输入的 SDK 会话。普通轮次结束后继续保留原生会话和后台任务,运行中补充进入当前轮次。持续会话空闲满 5 分钟且没有活动轮次、待启动任务、活动目标或原生后台任务时释放,后续发送从原生历史恢复。编辑、分支及删除先结束空闲的原生会话,变更锁与发送入口共用;浏览器和网页桥接连接释放保持模型任务独立运行。正常网页重连恢复同一执行服务的活动快照,独立执行服务故障才进入原生进程核对及未确认输入恢复。
|
|
80
|
+
- `messages.mjs` 将原生用户图片及工具返回的图片统一转换为网页媒体内容,保留 base64 数据和 MIME 类型,实时展示与原生历史恢复采用同一转换。
|
|
81
|
+
- 模型支持能力与用户思考启停分别处理。`providerModelEnvironment` 将明确配置的自适应支持和 effort 档位映射到原生 `CLAUDE_CODE_MODEL_CAPABILITIES` 部分覆盖规则;自适应支持为 false 时由 CLI 选择固定预算思考及其原生预算,自适应支持为 true 时由 CLI 选择 adaptive。未配置字段保持原生判断。旧的 `ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` 在 firstParty 请求路径被 CLI 忽略,因此采用实际生效的能力覆盖入口。运行时通过原生 `--thinking-display=summarized` 请求可展示的思考正文,省去依赖原生实验性默认展示模式。已有会话每轮同步模型能力、上下文容量及 effort;模型切换清除旧容量覆盖,配置变更按供应商版本重建空闲会话并恢复原生历史。
|
|
82
|
+
- 标准 Messages 供应商的请求转换保留原生思考控制及结构化输出,主请求中的 `adaptive`、`enabled` 和 `disabled` 按原文传递;省略 `thinking` 的原生请求按 Anthropic 的关闭语义显式传递 `{type: "disabled"}`。目标评估的 JSON schema 保持完整。供应商环境保持原生功能开启,避免全局关闭实验功能同时移除结构化输出。
|
|
83
|
+
- 流式 `message_delta.stop_reason` 确定最终正文与计划正文;完整 assistant 消息提前到达时保留过程状态。刷新按原生消息标识恢复已确认的展示类型和阶段,正文仍读取原生内容。API 错误转换为轮次错误,公开提示与诊断详情分别保存。
|
|
84
|
+
- `project-instructions.mjs` 在每次 `UserPromptSubmit` 从根目录到当前目录读取 `AGENTS.override.md` 或 `AGENTS.md`,同目录优先 override,保留路径、作用域和完整正文。每轮完整快照替换此前的 AGENTS 快照,空列表同样提交;原生 `CLAUDE.md` 加载继续由 Claude Code 负责。
|
|
85
|
+
- `hooks.mjs` 处理提问、子代理及文件操作;`git-tool-changes.mjs` 记录工具实际引起的 Git 文件变化。`agent-history.mjs` 根据原生子代理目录、调用标识和消息恢复任务与接收历史,保留已分支对话中子代理的真实来源。
|
|
86
|
+
- SDK 会话启用原生文件 checkpoint。`Query.rewindFiles` 按用户消息恢复完整 checkpoint,并提供只读预览;原生分支从独立的文件历史开始。网页单文件撤销继续采用路径级补丁与当前文件校验,明确选择目标文件并保护用户并发编辑。
|
|
87
|
+
- `goals.mjs` 使用原生 `/goal` 设置目标,由 CLI 的会话级 Stop 提示钩子评估条件并持续执行;通过 `getHooksListing` 与 SDK 导入的原生 `goal_status` 核对活动、完成及阻塞,保留显式设置和清除的 `sentinel`。网页保存目标面板、暂停和预算状态,使用实际 token 事件核算预算。`native-commands.mjs` 将内部清除指令按 UUID 与普通轮次隔离;刷新及分支保持这一隔离。`background-tasks.mjs` 接收原生任务事件、保留任务所有者并调用 SDK 停止后台终端;后台任务结束后的原生唤醒使用独立轮次和消息锚点保存。
|
|
88
|
+
- 目标检查按原生记录 UUID 区分当前执行与旧结果。CLI 已结束轮次、目标钩子仍在且没有后台活动时,将目标显示为阻塞并保留原生检查错误;原生评估超时或返回无效结构时及时结算,等待明确的继续操作。后台任务仍运行时保留活动目标,等待真实原生唤醒;目标适配器使用原生评估结果,不另行创建评估请求。
|
|
89
|
+
- `catalogue.mjs` 从当前执行目录与运行时读取模型、命令、插件、代理及 MCP 工具;模型使用 `list_models`,技能使用 `reloadSkills`。18 项网页通用命令维持统一入口,当前原生目录中的附加命令按名称提供建议与执行;网页已经管理的同名功能继续进入统一用例。`config/read` 将原生 `get_settings.applied` 的模型及思考强度交给前端,原始环境与设置来源保留在服务端。
|
|
90
|
+
- Claude 文件内容在原生 `read_file` 的 10 MB 范围内使用该控制接口,保留 base64 完整内容并核对截断状态。浏览器文件读取先通过同源认证 HEAD 确认实际大小,超过原生硬上限时直接采用已有 HTTPS 文件接口读取全文件,编辑和保存继续使用完整内容。
|
|
91
|
+
- `account.mjs` 区分 Claude 原生账户与外部供应商;原生账户额度从持续 SDK 会话的 `get_usage` 控制响应读取,保留各窗口及额外用量的实际单位。外部供应商显示供应商身份和外部计费状态。`token-usage.mjs` 将原生用量和上下文查询转换为统一的最近用量、累计用量与上下文容量,读取失败保留已取得的事实和错误。
|
|
92
|
+
|
|
93
|
+
列表与搜索汇总每页后端错误。一个后端读取失败时,保留同一范围内已经显示的该后端对话,其余后端照常更新;侧栏和搜索提供实际错误与重试。搜索查询、归档范围、页面卸载与列表修订共同隔离迟到结果。
|
|
94
|
+
|
|
95
|
+
## 验证入口
|
|
96
|
+
|
|
97
|
+
`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#双后端开发与验收)。
|
|
98
|
+
|
|
99
|
+
`claude-native-fork-boundary.mjs` 使用真实 SDK 和临时原生记录验证结构化输出附件完整保留、原生 UUID 来源和逻辑轮次映射。`claude-native-checkpoints.mjs` 通过真实 CLI 的 Read/Write 工具修改两个文件,核对原生 checkpoint 预览、完整恢复及会话历史保留。
|
|
100
|
+
|
|
101
|
+
`npm run test:codex:live` 使用独立配置、临时项目及真实 app-server 和模型验证文件写读、原生查询、重启续聊、分支和历史。`claude-installed-worker.mjs` 则实际打包、临时安装并从发行包启动 Claude 执行服务,验证原生文件、技能、配置、工具轮次、历史及停止;其模型响应由隔离服务提供。安装包、真实模型和界面夹具的验证结果各自注明来源。
|
|
102
|
+
|
|
103
|
+
单元测试覆盖共享产品方法清单、路由与资源隔离、工作区服务、模型参数、用量转换和错误分类。文件查询同时验证原有 Codex 请求直接到达原生后端,以及 Claude 在大目录和真实工作区中的查询结果;结果数量限制与目录遍历范围分别核对。浏览器回归覆盖同一界面的实际操作、断线恢复、失败重试、主题和布局。真实 CLI 配合隔离服务验证原生接口,外部账户授权及余额属于相应服务的真实环境事实,分别记录验证证据。
|
|
104
|
+
|
|
105
|
+
## 协议查验依据
|
|
106
|
+
|
|
107
|
+
2026-11-06 核对 Claude Code 2.1.318、Agent SDK 0.3.318、原生请求记录及官方接口文档。中途 `system` 消息属于具备该能力的 Anthropic 模型的原生协议,标准端点通过顶层 `system` 接收相同系统指令。传输层在首次请求前转换系统消息布局,保留系统指令优先级、正文、工具内容块、思考参数和结构化输出。原生功能配置保持开启,辅助评估请求与普通请求采用相同的标准协议转换。
|
|
108
|
+
|
|
109
|
+
- [中途系统消息与模型支持范围](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages)
|
|
110
|
+
- [Claude Code 环境变量与实验协议字段](https://code.claude.com/docs/en/env-vars)
|
|
111
|
+
- [Agent SDK 持续流式会话](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode)
|
|
112
|
+
|
|
113
|
+
开发先查明实际原生行为、输入输出和状态归属,再实现产品用例。已确认的实现错误直接修正其构造或状态转换,避免用错误字符串匹配、请求补发和隐式降级替代正确实现。验证先核对首次请求及完整执行链,再报告用户可见结果。
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# 功能与状态契约
|
|
2
|
+
|
|
3
|
+
文件夹选择器默认隐藏名称以 `.` 开头的目录。“显示隐藏文件夹”由选择器持有,切换目录时保留,重新打开选择器时恢复关闭;直接输入绝对路径仍可进入隐藏目录并选择。
|
|
4
|
+
|
|
5
|
+
供应商模型支持可选显示别名,按供应商及模型 ID 保存到服务端配置。供应商编辑表单默认显示紧凑模型行,点击铅笔展开别名输入,清空使用原名称;供应商保存成功后更新菜单,取消编辑或保存失败时分别放弃或保留表单草稿。模型请求与历史记录继续使用原始模型 ID。
|
|
6
|
+
|
|
7
|
+
活动轮次的耗时从真实开始时间持续计算,历史读取中的用户及工具消息时间保留为消息事实。轮次成功、失败或中断后使用实际结束时间固定总耗时;刷新、切换和重新展开工作过程继续沿用同一开始时间。
|
|
8
|
+
|
|
9
|
+
Claude 原生思考按所属 API 消息的内容块顺序保留独立标识,流式、完整消息与历史读取使用相同标识,正文到达时保留已有思考。完整思考以独立标题和可展开正文呈现,单段长文本与多段正文均保留;原生摘要继续按其标题与正文展示。首个思考增量立即归属所属轮次,主对话及子代理采用一致的合并和恢复规则。
|
|
10
|
+
|
|
11
|
+
本文记录跨模块协作必须保持的产品行为,用于实现评审和回归选择。模块关系见[架构设计](../architecture.md),测试运行方法见[开发者指南](../development.md)。每项契约同时约束实时通知、历史恢复与页面重新连接;修改行为时同步检查它的所有入口。
|
|
12
|
+
|
|
13
|
+
## 双后端与供应商
|
|
14
|
+
|
|
15
|
+
自定义供应商在列表的编辑按钮旁提供删除按钮;请求期间禁止重复操作,成功后刷新供应商及模型目录并关闭该供应商的编辑表单,失败保留列表及编辑内容并显示错误。默认供应商通过清空 API Key 停用。
|
|
16
|
+
|
|
17
|
+
项目模型偏好在所属后端离线时仍可读取和保存;保存成功向所有页面广播所属后端的完整项目偏好,保存失败保留原数据并允许重试。依赖执行状态的目录创建、单文件撤销、整理核对和子代理消息读取在后端就绪后执行。整理占用期间,两端统一暂停开始轮次、补充输入、审查、历史回退和再次整理,历史与项目偏好保持可读。
|
|
18
|
+
|
|
19
|
+
新对话的项目模型偏好须在当前供应商的模型目录中匹配后恢复;失效偏好依次采用目录内的配置默认模型、原生默认模型及首项,空目录清空模型和思考强度。历史对话保留原模型身份,目录缺失时在模型菜单中显示禁用的不可用状态,用户可主动选择有效模型。
|
|
20
|
+
|
|
21
|
+
侧栏底部跟随当前对话所属后端,新对话跟随所选模型后端。Codex 显示账户用户名、套餐或 Codex;Claude Code 原生账户显示实际身份及可取得的额度窗口,配置外部供应商时显示供应商名称及外部计费状态。读取失败保留已有数据并提供重试,未取得外部余额时保留实际状态。连接状态同时检查网页连接和所属后端就绪状态。
|
|
22
|
+
|
|
23
|
+
对话顶部与侧栏各对话仅用图标区分后端,Codex 使用 OpenAI 标识,Claude Code 使用 Claude 官方标识,图标省去名称、悬停提示和附加标签;标识在单后端、断线和刷新后继续显示,依据对话归属确定。页面提供固定的 Codex 和 Claude Code 两个后端,模型菜单以“供应商 · 模型”区分选择。ChatGPT 模型沿用 Codex 原生配置;Claude Code 供应商在设置中配置地址、凭据和模型,多个供应商共用同一个 Claude Code 后端。设置保存和接口校验均约束为两个后端。标题前的复选框即时保存启停;停用后端的对话立即从侧栏移除,正在查看的所属对话回到新对话,重新启用后恢复显示,无需刷新页面。CLI 安装位置及原生目录自动取得。设置自动展示安装状态、当前 CLI 版本与 npm 官方最新版本,未安装提供“一键安装”,已安装提供“一键更新”。服务器持有安装任务,关闭设置或重连后继续展示结果;忙时拒绝更新,失败保留实际错误及重试入口。版本由桥接服务启动时及此后每小时自动检测并广播,网页在各自后端内展示缓存结果,省去手动检测入口和“已是最新”文案。版本查询失败保留已取得的版本并标明查询错误。
|
|
24
|
+
|
|
25
|
+
新对话选择模型后自动确定后端;已有 Claude 对话空闲时切换供应商和模型,下一轮恢复同一个原生会话。用户消息、助手正文及工具记录沿用原生历史。原生 `origin.kind=task-notification`、`isSynthetic` 及 `isVisibleInTranscriptOnly` 标记的记录保持内部归属;SDK 实时帧按本轮实际提交的输入 UUID 确认用户归属,原生历史中仅继承 `entrypoint=sdk-ts` 与 `promptId`、缺少提交来源与轮次归属的附加记录保持内部归属。工具结果仍更新对应工具;用户主动输入相同文字继续显示。内部记录不创建用户轮次或推进活动时间,已保存的自动唤醒锚点仍用于恢复独立轮次。子代理转发帧在处理主对话生命周期和用量前隔离。运行中的轮次沿用启动配置。同供应商的模型选择仍可为下一轮调整,切换模型保留已有技能与命令目录;跨供应商切换在空闲时进行。新草稿初始化先恢复供应商,再读取其模型、账户及项目偏好。重新打开对话以已保存的供应商与模型恢复,供应商间重复的模型名称按供应商标识区分。已有对话的模型菜单显示所属后端的模型;跨运行时交接按独立需求设计。
|
|
26
|
+
|
|
27
|
+
## 对话、项目与历史
|
|
28
|
+
|
|
29
|
+
输入区 `@` 提供文件、目录、技能和同后端其他会话。文件搜索对返回的全部候选按相关性排序后再截取展示数量,名称精确、前缀、连续与紧凑跳字匹配依次优先,仅父目录命中的结果靠后;文件与目录使用相同排序,同分保留原生顺序。空查询与以 `/` 结尾的目录浏览继续按目录优先、名称排序。`@` 查询包含路径分隔符时仅提供文件和目录,分隔符保持路径输入语义;独立的 `/` 查询提供快捷命令和技能。技能候选支持名称、显示名和技能目录的大小写无关模糊匹配,允许按字符顺序输入缩写与跳字;精确、前缀、连续和紧凑跳字匹配依次优先,描述关键词作为低优先级补充。Tab 将当前候选补全为可继续编辑的查询文本并保持建议打开,文件与目录补全完整路径,支持继续输入 `/` 逐级查询;Enter 或点击确认后以独立的行内引用显示,文件按扩展名区分图标,目录、技能与会话使用对应图标;菜单关闭,光标移到引用后的空格。引用节点支持两侧输入、整项删除、撤销、复制粘贴、切换与刷新草稿恢复,发送和消息编辑保持名称与目标。删除引用同时移除该项的提交数据;重复引用保留正文位置,原生元数据按目标去重。Codex 使用原生技能与 thread:// 会话引用,通过同后端只读 read_thread 工具按需读取已保存正文,Claude 技能使用原生命令,会话引用在发送时读取完整分页的用户和助手正文;读取失败保留完整草稿。代码与普通外部链接保留原语义。
|
|
30
|
+
|
|
31
|
+
侧栏将所有可见的活动轮次对话集中排列在置顶和项目文件夹上方,仅沿用会话行左侧的运行圆圈,省去分区标题和说明。顶部作为快捷入口按最近活动时间排序,同时保留原项目或置顶列表中的会话。成功完成且带未读绿点的会话继续保留顶部快捷入口,当前选中的顶部会话在阅读清除绿点或轮次结束后继续保留,切换会话或新建对话后再移除;其他已结束会话沿用未读状态保留顶部入口。原项目归属、置顶偏好和文件夹收放状态保持不变。活动状态沿用实时轮次事件与重连快照。
|
|
32
|
+
|
|
33
|
+
对话列表和搜索结果以创建时间、轮次开始时间、有效结束时间中的最大值排序,显示时间沿用相同依据。打开、重命名和切换对话保留活动时间;新轮次开始和结束立即更新顺序。全分页历史补齐时保留已经收到的较新事件。两个后端独立读取,任一后端失败时保留已显示且符合当前归档和搜索范围的记录,其余后端继续更新;侧栏及搜索显示所属后端的实际错误并提供重试。相同查询保留此前已确认的正文匹配记录,修改查询及卸载后忽略旧请求结果。
|
|
34
|
+
|
|
35
|
+
项目按固定状态分组,固定项目始终位于未固定项目之前,空项目及仅含置顶对话的项目同样遵循此规则,“未分类”始终位于末尾。同类项目的顺序使用页面内快照,归档、恢复和实时活动保留快照;固定与取消固定立即按新状态重新分组,各组内部沿用快照顺序。手动添加或固定的项目跨刷新保存。固定文件夹默认展开,其余默认折叠,每组先显示最新五条;“查看更多”覆盖后端全部分页。“未分类”保留独立归属,新建时按首次发送流程准备工作目录,已有目录可以沿用。
|
|
36
|
+
|
|
37
|
+
侧栏对话可拖到项目文件夹或“未分类”标题,悬停高亮,保存成功后展开目标并显示对话。移入文件夹为后续轮次选用目标目录,移到未分类保留有效工作目录;运行中的轮次继续完成,后续恢复和新轮次应用迁移结果。归属保存在服务端,刷新、重新连接、归档恢复及其他页面均沿用;保存失败保留原归属、草稿及附件,并提供错误提示。置顶对话移入文件夹后取消置顶。每个网页项目对应一个文件夹,原生历史通过所属后端读取。
|
|
38
|
+
|
|
39
|
+
主对话与子代理使用 `domain/thread-history.js` 的完整历史读取流程。仅在 `thread/items/list` 明确不受支持时回退到 `thread/turns/list` 的完整消息分页。写入被其他客户端占用时继续提供已保存历史;其他读取错误保留实际错误和重试入口。
|
|
40
|
+
|
|
41
|
+
分支通过 `thread-catalog.js` 的统一动作创建。读取所有未归档与已归档家族元数据,按真实 `forkedFromId` 关系生成数字后缀,兼容旧网页后缀并保留手动标题。侧栏菜单、回复操作与 `/fork` 共用流程。归档、删除和标题通知同时更新当前对话与列表,旧列表或打开响应保留通知中更新的结果。
|
|
42
|
+
|
|
43
|
+
Codex 首轮发送后,桥接使用独立连接及临时会话生成简短标题;写入前重新读取目标记录。手动改名、归档、删除及断线取消旧生成任务,生成失败可在后续打开或发送时重试。标题生成的消息和订阅与用户对话隔离。Claude Code 对话沿用其原生标题与网页保存的用户名称。
|
|
44
|
+
|
|
45
|
+
Claude Code 的模型会话和后台任务由独立执行服务持有。网页关闭、桥接正常重启或异常退出后继续执行,恢复连接时读取同一服务的活动轮次、执行状态及待答提问;同一输入保持一次原生提交。停止或替换执行服务按真实在途请求、活动轮次、整理、队列、提问及后台任务检查占用,忙时保留服务并返回实际状态。代码与运行配置变化在忙时标记待更新,空闲后切换;旧网页桥接重新连接保持较新的执行代际。无活动任务、目标或后台任务的 SDK 会话空闲 5 分钟后释放,再次发送从原生历史恢复。
|
|
46
|
+
|
|
47
|
+
## 输入、草稿与执行
|
|
48
|
+
|
|
49
|
+
图片及其他附件随所属对话在当前页面内保留,切换到其他对话再返回时恢复原附件列表;尚未首次发送的新对话同样恢复。移除附件后保持移除,首次发送创建实际对话时迁移附件草稿。一次选择多个文件时,在文件选择框重置前取得全部文件,并将每个文件的读取绑定到原草稿。异步文件读取完成后更新原草稿,发送失败保留附件供重试,发送成功仅清理已提交附件,保留等待期间新增的附件。
|
|
50
|
+
|
|
51
|
+
正文输入即时更新独立草稿订阅,按对话持久保存。正文编辑区保持两行固定高度,换行及长文本通过内部滚动查看;输入内容变化时,输入框及发送工具栏保持尺寸和位置稳定。普通正文和同级列表的两行文字完整显示,光标与选区由浏览器原生维护;滚动后继续输入时定位到真实编辑位置。加载期间的文本、焦点及完整选区交接给文档编辑器,对话切换后旧实例只清理自己的输入适配。Ctrl+Enter 与发送按钮走同一提交入口,Enter 保留换行;组合输入确认保持正常编辑。输入期间共享状态快照稳定,长历史和文件面板保持渲染隔离。
|
|
52
|
+
|
|
53
|
+
正文使用 Markdown 富文本编辑,支持 CommonMark、GFM(表格、任务列表、删除线、自动链接及脚注)、数学公式。Mermaid 以普通代码块输入,HTML 保留源码。用户直接编辑排版后的正文及表格单元格,选区格式工具提供常用操作;持久化和发送使用 Markdown。编辑器实例及撤销栈归当前对话的输入组件所有,切换对话时销毁;异步初始化及迟到输入回调按挂载生命周期隔离。输入后立即发送读取即时草稿,文件引用和快捷命令继续使用统一入口。编辑器和运行时资源从本站加载,加载期间保留可编辑的 Markdown 文本框。
|
|
54
|
+
|
|
55
|
+
提交快照包含正文、附件、文件引用和全部批注。失败保留可重试内容,成功只清理与已发送快照一致的草稿;请求等待期间的新输入或批注继续保留。运行中补充使用当前轮次通道,新的轮次带上当前模型、有效思考强度、速度模式和统一执行策略。
|
|
56
|
+
|
|
57
|
+
新对话的模型和思考强度按项目保存。已有对话打开、刷新及重连时,从后端对话读取与恢复结果取得该对话的模型和思考强度;项目默认选择仅用于新建对话,恢复请求期间的手动调整继续保留。服务端项目设置是跨浏览器恢复来源,本地缓存和待写入选择用于即时交互及失败重试;迁移只补齐服务端缺失值。同项目新建沿用当前有效选择,跨项目恢复目标选择。模型切换保持支持的强度,不支持时由领域规则选择最近的可用档位;迟到恢复保留期间的手动调整。
|
|
58
|
+
|
|
59
|
+
思考强度通过带离散档位圆点的胶囊滑块调整,标题旁显示当前档位,滑块下方省去重复的档位文字。输入框的紧凑入口展开独立面板,模型弹窗复用同一控件;拖动、点击轨道和方向键使用后端返回的支持档位。模型选择和速度模式分别使用各自入口。
|
|
60
|
+
|
|
61
|
+
执行策略统一为完全访问。快捷命令注册与参数解析集中在 `features/commands`,菜单、按钮和键盘使用同一入口。18 项网页通用命令保留统一用例,Claude Code 当前目录的原生附加命令由实际运行时目录提供。`/init` 保留并打开已有目录指令文件;`/goal` 使用实际目标接口;`/stop` 清理当前对话全部后台终端分页。Claude Code 每次提交按祖先到当前目录读取 AGENTS 项目指令,同目录优先 `AGENTS.override.md`,保留完整原文、路径与作用域;本轮快照替换此前快照,修改和删除在下一轮生效,原生 `CLAUDE.md` 持续适用。完整支持范围见[命令覆盖记录](../cli-command-coverage.md)。
|
|
62
|
+
|
|
63
|
+
所有公式使用 `$$公式$$`,同一行及换行输入统一生成当前段落内的行内公式,光标停在公式后并可继续正文。单美元符号作为普通文本。闭合前保留可编辑源码,公式可双击或通过键盘重新编辑,修改后以 `$$` 再次闭合。粘贴、草稿恢复和发送沿用同一双美元符号语法;代码块与行内代码保留美元符号源码。
|
|
64
|
+
|
|
65
|
+
Markdown 输入以逐字键入后自动排版为主要交互,选区格式工具用于补充操作。列表中的行内公式、标题、强调及代码围栏均支持连续输入;代码语言保留在围栏标记中,闭合围栏后回到正文。回归分别覆盖逐字键入、整段插入、粘贴和中文输入法提交,检查可见结果及发送的 Markdown。
|
|
66
|
+
|
|
67
|
+
链接末尾续写时使用普通正文格式,空格及后续文字保留在链接之外;链接内部继续支持编辑显示文字。粘贴网址、Markdown 链接和草稿恢复遵循同一边界。
|
|
68
|
+
|
|
69
|
+
最近一轮的初始用户消息提供铅笔形“编辑上一条消息”入口;原消息位置切换为紧凑的 Markdown 编辑框,正文固定两行并通过内部滚动查看长内容;宽度最多为 42rem,窄屏内最多占消息区的 90%。背景、边框、阴影和聚焦边框与底部输入框共用规则,发送使用主操作配色,深色及跟随系统主题同步适配。支持取消、发送、Enter 换行与 Ctrl+Enter 提交。编辑正文、引用附件和批注由消息组件独立持有,底部草稿保持原值。运行中补充消息继续通过运行轮次发送,历史编辑针对完整轮次。
|
|
70
|
+
|
|
71
|
+
编辑提交先读取完整分页核对最近消息及运行状态,通过 `thread/revert` 回退到原轮次之前;仅在该方法明确不支持时使用 `thread/rollback`。成功回退后清理已移除的历史、时间与差异,再提交新轮次,刷新以实际后端记录恢复。回退失败保留原历史,发送失败保留编辑框及输入,重试核对保留轮次并复用已成功的回退。取消已回退的失败编辑时读取实际历史。连接、写入检查、整理及运行状态限制提交,异步读取和回退响应按对话及打开版本隔离;回退使较早的历史分页请求失效。其他页面收到 `thread/reverted` 时重新恢复所属对话。
|
|
72
|
+
|
|
73
|
+
Claude Code 编辑及分支通过原生会话分支保存保留前缀,网页逻辑对话与保留轮次标识稳定,原生 UUID 和后台自动唤醒锚点随分支更新。保留的原生别名归属原逻辑对话,列表和删除恢复保持去重;发送失败后重试沿用已成功完成的历史回退。
|
|
74
|
+
|
|
75
|
+
## 批注、引用与提问
|
|
76
|
+
|
|
77
|
+
文件引用建议在两个后端保持相同操作:Codex 沿用原生 app-server 查询,Claude Code 通过原生 `file_suggestions` 查询。Claude Code 对话的 `@关键词` 使用 CLI 文件索引和匹配规则,包含文件、目录与中文名称;`@` 及以 `/` 结尾的路径沿用目录浏览。搜索读取失败时显示实际错误,用户可修改关键词重试。
|
|
78
|
+
|
|
79
|
+
用户消息正文与助手正文共用 Markdown、GFM、公式及安全过滤渲染器,复制和编辑保留 Markdown 源码。引用仅在 Markdown 文本节点中转换,代码、链接和公式保持自身语义。
|
|
80
|
+
|
|
81
|
+
用户消息统一解析正文、文件引用及回复批注。显示、复制、编辑使用可读内容,提交保留所需引用协议。文件和目录以类型图标及蓝色链接呈现;点击目录定位到文件列表,点击文件在右侧打开。解析失败的普通内容保留原文。
|
|
82
|
+
|
|
83
|
+
批注解析兼容桌面端的 Markdown 标记和 JSON 格式。选区旁的编辑器只更新草稿;批注按对话保存,可连续添加、重新编辑或移除,再随主输入统一提交。编辑批注时,Enter 与对勾按钮均完成当前批注并将焦点返回主输入框,Shift+Enter 换行,中文输入法选词期间的 Enter 保持输入;Ctrl+Enter 将全部批注、正文和附件统一发送。回复中的编号引用按所属轮次和前置用户消息关联,代码与公式中的标记保留源码。
|
|
84
|
+
|
|
85
|
+
待答问题按请求 ID 去重,并按对话和轮次展示。提问卡片仅显示标题、题目、选项、回答框和提交按钮;失败时按钮显示“重试”并保留填写内容,具体错误通过按钮提示取得。提问卡片默认使用单行高度的可调节回答框和紧凑间距;Enter 提交整份回答,Shift+Enter 在自由输入中换行,输入法选字期间保留原生键盘行为。提问卡片的选择、私密字段与自由输入独立;异步回答、运行中补充和普通消息分别保持其提交语义。已解决请求跨页面同步,断线恢复采用桥接快照。已回答及已结束的提问收入所属工作过程。
|
|
86
|
+
|
|
87
|
+
Claude Code 的完整 assistant 消息与流式结束原因分别到达时,按照真实 `message_delta.stop_reason` 确认最终回答或计划,过程文字继续收入工作过程。刷新按相同消息标识恢复已确认的展示类型。供应商 API 错误归入失败轮次和错误提示,公开提示与诊断详情分开,错误正文保持在诊断详情中。
|
|
88
|
+
|
|
89
|
+
## 整理上下文
|
|
90
|
+
|
|
91
|
+
整理使用独立的异步任务状态。浏览器在发送前设置占用并保存恢复记录,桥接在提交到轮次结束之间保留订阅。空确认只代表提交成功;实际成功、失败或中断由对应轮次通知或完整历史核对确定。
|
|
92
|
+
|
|
93
|
+
```mermaid
|
|
94
|
+
flowchart LR
|
|
95
|
+
A[提交并持久化恢复线索] --> B[等待开始或结果]
|
|
96
|
+
B --> C[运行中]
|
|
97
|
+
C --> D[完成、失败或中断]
|
|
98
|
+
B --> D
|
|
99
|
+
B --> E[断线后待核对]
|
|
100
|
+
C --> E
|
|
101
|
+
E -->|分页核对实际轮次| C
|
|
102
|
+
E -->|已结束| D
|
|
103
|
+
D --> F[清理恢复记录]
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
整理占用同时约束发送按钮、Ctrl+Enter、运行中补充、重复整理、审查和桥接请求。正文及附件仍可编辑。刷新、重连、回到前台和“检查状态”核对实际记录,旧桥接缺少专用接口时使用已有历史接口。新轮次、无关自动整理及迟到响应按任务标识隔离。
|
|
107
|
+
|
|
108
|
+
手动整理期间由输入框上方的状态栏统一显示进度、耗时与恢复操作,聊天区隐藏通用工作提示及同一整理轮次的整理活动,保留其他历史和活动。整理结束后,整理记录继续按工作过程规则展示;自动整理沿用原有活动展示。
|
|
109
|
+
|
|
110
|
+
整理完成提示在关闭、离开该对话或提交有效新消息时收起;空消息保留提示。浏览器重新打开及重连快照只恢复进行中的整理,已结束结果仅更新页面已跟踪的同一任务,已收起提示保持关闭;浏览器离线期间结束的未完成任务仍显示核对后的结果。失败保留待发送内容,其他对话的完成提示保持独立。
|
|
111
|
+
|
|
112
|
+
## 计划模式
|
|
113
|
+
|
|
114
|
+
计划模式用于调查需求和制定方案。后端的 `plan` 消息作为独立方案卡片显示部分正文预览,底部渐隐并提供“展开计划”;展开后可从顶部收起,批准与修改按钮保持在预览区外,`item/plan/delta` 追加正文,完成记录替换同一消息;主对话和子代理只读历史采用相同排版。执行工具的 `turn/plan/updated` 步骤列表继续显示为执行进度。
|
|
115
|
+
|
|
116
|
+
最新方案所属轮次成功结束、且后续尚无用户消息时,提供“批准并执行”和“修改计划”。批准携带完整方案,通过 `turn/start` 显式选择 `default` 模式,确认成功后更新原对话的模式;失败保留原方案及重试入口。修改入口选择计划模式并聚焦原输入框,保留草稿,由用户提交修改意见。批准消息显示为简洁的操作结果,传输与历史保留完整计划。
|
|
117
|
+
|
|
118
|
+
模式按对话保存在浏览器中,刷新和切换恢复,新建对话使用默认模式。连接、写入检查、整理和消息提交期间统一限制批准,运行期间等待轮次结果。重复点击共用发送占用,提交前重新核对当前对话及方案;发送后的迟到结果按原对话保存模式,底部草稿、附件和其他对话选择继续保留。刷新后从完整历史和轮次状态重新确定批准资格,已有后续用户消息的方案保持为历史展示。
|
|
119
|
+
|
|
120
|
+
## 消息展示与导航
|
|
121
|
+
|
|
122
|
+
领域层按轮次组合消息与工作过程,用户提问和中途补充保留独立消息;同轮补充同时按原始消息顺序收入工作过程,摘要行直接显示消息正文,短消息完整可读,长消息省略并可展开正文与附件,实时预览继续显示最新工作活动;工作过程默认折叠,运行时展示最新有效活动,结束后固定耗时。最终回答的复制及分支按钮位于本轮文件汇总之后,实时生成和历史恢复遵循相同顺序。
|
|
123
|
+
|
|
124
|
+
全部历史保持连续可滚动。打开对话和回到最新时定位到真实底部,包括消息底部留白;自动跟随期间,输入框恢复、图片、图表及容器变化继续贴底。上翻或目录跳转后保留阅读位置,切换对话清理监听和待处理帧。
|
|
125
|
+
|
|
126
|
+
主对话打开时,最近一页消息先显示,写入能力检查独立恢复输入,其余历史在后台自动读完并合并;完整轮次时间读取与消息读取并行。补齐较早记录时维持正在阅读的内容位置,实时修改优先于首屏及历史快照。后台分页失败保留已显示记录并提供重试;切换后停止继续分页并丢弃迟到结果。未改变的正文和批注复用 Markdown 解析,普通状态通知和滚动操作保持既有回复渲染结果。
|
|
127
|
+
|
|
128
|
+
消息目录以实际独立用户消息为条目,支持搜索、键盘、当前位置高亮和跳转;默认缩略标记数量受控。目录和详情卡片各有稳定位置,主消息滚动条贴工作区最右侧。新建按钮在侧栏收起和窄屏下保持可用。
|
|
129
|
+
|
|
130
|
+
思考摘要通过独立翻译适配器合并请求,标题优先,正文按流式更新节奏处理。译文在同一标签页的内存和会话存储中复用,正文失败与标题隔离,失败内容可重试;卸载清理组件计时器并忽略迟到结果。翻译所用远程服务和发送数据范围见[部署文档](../deployment.md)。
|
|
131
|
+
|
|
132
|
+
## 工作区、文件与终端
|
|
133
|
+
|
|
134
|
+
详情卡片集中提供文件、变更、终端和子代理入口。主对话首次加载默认折叠;显式展开状态跨布局变化保留。折叠、新建或切换主对话清除面板与子代理选择,重新展开回到概览。
|
|
135
|
+
|
|
136
|
+
桌面详情面板延伸至聊天工作区底部,输入框与错误提示随左侧对话区域收窄;折叠后恢复全宽输入。窄屏详情覆盖聊天工作区并保留关闭入口。文件下载使用文件名工具栏中的图标,提供可访问名称和悬停提示。
|
|
137
|
+
|
|
138
|
+
文件面板首次打开后保留挂载,编辑缓冲区按主对话保存。切换目录或文件时按已有未保存确认流程处理;迟到读取和保存只更新原目标。文件面板支持普通源文件、差异片段和带变更装饰的完整文件,切换视图保留编辑内容。
|
|
139
|
+
|
|
140
|
+
统一差异按区块坐标提供原行号和新行号;隐藏坐标元数据,复制、统计及撤销保留完整差异。完整文件通过逆序还原逐次补丁计算净装饰,删除内容作为只读装饰插回原位置,保存使用实际编辑正文。当前文件与记录冲突时保留差异入口并显示变化状态。
|
|
141
|
+
|
|
142
|
+
本轮文件汇总合并成功完成的修改,默认最多展示五项;按对话、轮次保存实时净差异,历史采用所属轮次记录。按文件撤销由桥接重新读取真实记录,在临时目录校验补丁与源文件后写回;运行、冲突和重复请求分别受控,并广播结果。
|
|
143
|
+
|
|
144
|
+
Markdown 文件默认预览,可切换源码并保留未保存内容。文本按文件名选择语法;媒体、PDF 和其他二进制由文件类型规则选择预览或下载,支持的流式媒体通过已认证 HTTP 路由读取。目标变化时清理播放器和对象 URL。
|
|
145
|
+
|
|
146
|
+
Claude Code 的原生后台任务按所属会话保存任务标识、类型、进度和实际所有者,`/stop` 读取全部后台终端分页并调用原生停止接口。后台任务通知触发的原生自动唤醒按独立轮次保存,轮次绑定真实消息锚点,刷新、编辑回退与分支维持顺序。
|
|
147
|
+
|
|
148
|
+
交互终端独立于对话任务,按完整启动文件夹隔离。切换到其他文件夹的对话时恢复目标文件夹的列表、选中项和面板开关;没有终端的文件夹默认收起,返回原文件夹恢复原进程和输出。同目录切换对话或模型后端保留终端,shell 内的 cd 保持启动归属,其他文件夹的后台退出不会收起当前面板。面板上边缘支持拖动调高、上下方向键和双击复位,高度比例跨刷新及隐藏保存;缩放和容器高度变化重新限制上限,保留输入框及发送工具栏。列表默认使用紧凑宽度,左边界支持拖动及键盘调节,双击恢复默认;相对宽度跨刷新、隐藏及目录切换保存,窄屏和缩放按实际容器限制宽度。加号创建并选中独立终端,已有终端保留进程与输出,右侧紧凑列表切换活动终端,名称与图标反映实际前台程序(例如 zsh、Python),省去目录及编号;单个终端隐藏列表,窄屏使用图标列表,名称由可访问标签及悬停提示提供;垃圾桶只结束当前终端,退出后切换到其他运行终端,最后一个退出时收起面板。当前面板依据自身会话集合的运行状态收起,退出事件缺少启动目录时同样生效;Ctrl+D 在 Python 中返回 shell,退出最后一个 shell 才收起面板。隐藏面板保留运行进程,重新打开恢复运行终端。桥接保存运行状态及恢复缓冲区,页面重新连接可恢复显示;关闭终端执行对应清理。重启网页服务会失去进程内终端状态,服务重启流程见[开发者指南](../development.md#从源码运行后台服务)。
|
|
149
|
+
|
|
150
|
+
## 子代理与共享渲染
|
|
151
|
+
|
|
152
|
+
子代理按对话 ID 合并不同协议版本的活动,主对话工作过程与详情概览共用入口。只读详情复用完整历史、消息和工作过程,消息路径使用子代理的实际目录。切换代理或关闭详情清理监听并丢弃迟到结果。
|
|
153
|
+
|
|
154
|
+
桥接通过父对话协作调用与子代理接收记录核对初始任务和后续消息,按接收者及调用 ID 隔离,保留重复发送并避免原生输入重复。标记为加密的正文在桥接返回前替换为“消息内容已加密”。发送成功而接收记录尚未落盘时,对整条正文符合 Fernet 封包布局的内容立即使用同一状态,检查 Base64URL 编码、版本、固定字段长度及加密块长度;接收后的结构化标记继续覆盖其他密文格式。明文保留原文,包括正文中引用的封包及仅包含相似前缀的文本。失败保留已有内容并可重试。
|
|
155
|
+
|
|
156
|
+
消息、工具结果、子代理及文件预览共用 Markdown 和 HTML 白名单过滤。安全的标题、对齐、图片、`picture` 及折叠内容统一处理,代码保留源码。相对资源以所属对话或文件目录解析;图片失败、主题切换及迟到读取均有隔离处理。
|
|
157
|
+
|
|
158
|
+
图片按统一等比缩略图展示,点击可查看大图,Esc、关闭按钮和空白区域退出后恢复焦点。Mermaid 从本站按需加载,严格模式绘制;流式未完成或解析失败时保留源码,清理临时节点并隔离旧主题及旧源码结果。
|
|
159
|
+
|
|
160
|
+
## 账户、登录与外观
|
|
161
|
+
|
|
162
|
+
对话完成通知默认开启,浏览器已有的手动关闭偏好保持有效。开关表示通知偏好,浏览器尚未授权时提供“允许系统通知”按钮,由用户点击请求权限;已有授权直接生效。正常状态仅展示开关,权限被拒绝、环境不支持及发送失败时显示必要状态。已登录页面观察到活动轮次成功完成后发送一条带对话标题及完成状态的通知;失败、中断、手动整理及历史读取保持各自原有展示。浏览器从桥接活动快照恢复进行中的轮次后可继续接收提醒,刷新和重连恢复已结束历史时保持安静。同源页面通过 IndexedDB 以系统登录用户、对话 ID 与轮次 ID 的唯一主键原子领取提醒,重复事件及多个页面保持一次。发送前重新检查开关、权限和登录用户,关闭提醒立即阻止尚未发送的通知。权限被拒绝、环境不支持及发送失败在设置页明确显示,聊天独立继续。
|
|
163
|
+
|
|
164
|
+
通知点击优先聚焦原页面并打开所属对话,保留其他对话的草稿与文件缓冲区;原页面已关闭时打开新页面并在登录及初始化就绪后恢复目标。导航事件验证通知所属登录用户,页面监听在登录界面同样有效,卸载时清理监听及待导航目标。提醒开关为浏览器偏好,浏览器权限及系统通知设置共同决定展示;在线页面与服务连接负责接收完成事件。
|
|
165
|
+
|
|
166
|
+
Claude Code 原生账户额度来自原生 `get_usage` 控制响应,按真实窗口、重置时间和额外用量单位展示;配置外部供应商时显示外部计费状态,余额以该供应商提供的数据为准。上下文用量按原生 token 记录及上下文查询恢复,与账户额度分别管理。
|
|
167
|
+
|
|
168
|
+
账户额度按后端实际窗口展示。完整读取替换快照,稀疏通知合并已有元数据;并发读取合并,连接、账户与通知版本共同隔离迟到响应。断线或失败保留上次数据并标记待更新。前台、轮次完成、额度重置及恢复连接触发校准;计时器和页面监听随生命周期清理。
|
|
169
|
+
|
|
170
|
+
额度详情默认折叠,以圆环显示窗口及剩余比例,展开后显示方案、额度与同一行的倒计时和重置时间。点击外部、Esc 和账户切换收起详情,布局保持账户行高度。
|
|
171
|
+
|
|
172
|
+
额度详情同时展示所选额度桶的 `credits` 点数余额,通用额度优先使用 `codex` 桶;后端余额四舍五入至最多两位小数并省略末尾的零,`hasCredits: false` 显示零,`unlimited: true` 显示无限额。已有点数信息但余额暂缺时显示余额暂不可用,完整读取未提供点数信息时隐藏该行。仅有点数时仍可通过圆环入口展开详情,断线或读取失败保留余额并标记待更新;通知合并及账户切换沿用账户额度的版本隔离。
|
|
173
|
+
|
|
174
|
+
登录表单保留稳定字段和自动填充语义,从表单真实值取凭据。成功时通过导航及可用密码管理 API 通知浏览器,失败请求保持表单并显示实际错误。刷新、浏览器重开及服务重启恢复有效会话;退出或过期返回登录界面,保留草稿和已提交后端任务。
|
|
175
|
+
|
|
176
|
+
主题变量统一维护中性灰阶、蓝色链接和控件状态,显式深色与跟随系统一致。字号和间距采用相对单位,输入框至少容纳两行。侧栏宽度由容器空间、字体和保存的比例共同决定,拖动与键盘读取同一组 CSS 约束。
|
|
177
|
+
|
|
178
|
+
页面显示功能、结果与必要操作,版本只展示产品版本号;完整构建来源通过构建信息、健康接口及命令行核对。图标统一来自仓库 SVG,兼容浏览器资源由生成脚本维护。
|
|
179
|
+
|
|
180
|
+
技能入口根据当前目录读取后端已安装技能;Claude Code 使用原生技能目录,选择后将 `/技能名称` 写入下一条消息草稿,保留已有附件;Codex 沿用技能附件流程;插件与连接入口展示后端插件和 MCP 服务状态。这些目录查询由对应弹窗触发,输入提交继续沿用统一消息流程。
|
|
181
|
+
|
|
182
|
+
## 传输与维护契约
|
|
183
|
+
|
|
184
|
+
浏览器与桥接共用 `shared/rpc-limits.mjs` 的消息大小限制(64 MiB),桥接发送 JSON 文本时分成至多 1 MiB 的 WebSocket 帧,保持原始图片数据和完整 UTF-8 消息。超限返回可重试错误,隔离当前请求并保留其他页面连接。
|
|
185
|
+
|
|
186
|
+
维护状态使用本机独立凭据与只读 WSS 入口,仅提供就绪、活动轮次和整理占用。空闲重启同时检查轮次与整理;用户终端和后端服务按各自生命周期处理。配置与运行目录来自环境或安装方式,发行包、源码模式和临时测试各用自己的目录。
|
|
187
|
+
|
|
188
|
+
测试数据使用模拟后端、临时目录和独立浏览器配置。回归记录应说明目标场景、构建来源和实际结果;环境配置、真实账户和真实对话数据保留在运行环境中。
|
|
189
|
+
|
|
190
|
+
## 本机 CLI 与网页配置归属
|
|
191
|
+
|
|
192
|
+
Codex 和 Claude Code 复用本机 CLI 的原有配置、认证、技能、插件和原生历史。网页连接与执行保持相同的原生目录,Claude 原生配置环境沿用既有认证变量,用户明确选择供应商时才应用供应商覆盖。网页自己的配置与持久化状态统一归属 `CLAUDEX_WEB_CONFIG_DIR`,默认 `~/.config/claudex-web`;原生配置目录与网页状态目录独立配置,切换网页目录保持原生目录不变。
|
|
193
|
+
|
|
194
|
+
Codex 设置中的模型显示偏好由网页后端配置持久保存并广播,模型菜单过滤隐藏项,已有对话保留原模型;设置通过完整原生目录恢复显示。修改显示偏好保持原生执行会话。DeepSeek 默认供应商通过服务端查询官方 `/user/balance`,凭据留在服务器,账户额度快照保存各币种总余额、赠金与充值余额及可用状态。账户行复用额度详情、前台刷新、并发合并、切换隔离和失败保留机制,金额按响应币种展示。
|
|
195
|
+
|
|
196
|
+
外部供应商账户余额使用响应币种对应的货币符号,金额固定保留两位小数;账户行摘要与展开详情采用相同格式。
|
|
197
|
+
|
|
198
|
+
Codex 的模型显示设置默认折叠,以轻量文字入口展开紧凑勾选列表,沿用设置页配色与间距,省去列表外框。
|
|
199
|
+
|
|
200
|
+
Claude Code 网络代理在设置中提供跟随服务环境、关闭和 HTTP,HTTP CONNECT 同时支持 HTTP/HTTPS 网页;旧 HTTPS 选项读取时迁移为 HTTP,显式代理可填写服务器可访问的主机地址及 1~65535 端口。旧配置沿用服务环境。保存前检查所属后端任务占用,忙碌或保存失败时保留旧运行配置及表单输入;成功保存后替换空闲执行服务,后续原生会话使用新配置。关闭代理清除继承的大小写代理变量,本机回环连接始终直接访问。
|
|
201
|
+
|
|
202
|
+
## 窗口尺寸调节
|
|
203
|
+
|
|
204
|
+
设置、搜索、重命名、删除确认、目录选择、技能、插件、模型及命令弹窗,以及图片和批注预览的右下角提供尺寸调节手柄。文件预览、文件差异和子代理详情共用的右侧面板通过左边缘调节宽度。支持鼠标及触控拖动、聚焦后的方向键调节、Shift 加速、双击或 Home 恢复默认。窗口手柄支持 Enter 或空格复位。尺寸按用途分别记忆,关闭重开与刷新恢复;尺寸按可用空间比例适应缩放和窄屏,并受当前视口边界约束。详情宽度同步调整聊天与输入区域的避让空间,拖动保留文件编辑和批注内容。项目侧栏、终端高度、终端列表及各类多行表单输入框使用同一套尺寸手柄。默认显示轻量短标记,悬停时增强、拖动时保持高亮,键盘焦点仅围绕局部标记显示。透明操作区与标记分离,方向分别表达调宽、调高或双向调整;失焦、取消或释放捕获结束拖动反馈。输入框保留原有字段、内容与禁用状态,双击或 Home 恢复自动高度。
|
|
205
|
+
|
|
206
|
+
上传附件保留原始字节与文件元数据,草稿仍归所属对话。图片使用大图预览,UTF-8 文本、音视频和 PDF 按格式展示;压缩包、Office 及其他二进制文件提供信息与原文件下载。非图片附件发送前由公共工作区服务写入网页配置目录下的受限附件目录,再以本机文件引用提交给所属后端;上传失败保留草稿,重试复用已上传路径。预览对象 URL 由窗口持有并在关闭时释放。
|