Web 用户界面（中文）¶

项目包含公开的静态首页和双语 Docs，以及安装后的本地单用户智能体工作台。工作台与终端 Shell 使用同一套智能体逻辑，科学计算在本地运行，配置的模型请求和用户明确要求的外部资料检索可以使用网络。

React 应用不实现独立的科学分析决策树。它将对话线程 ID 和用户请求发送给 Python 服务，由该服务调用与 CLI 相同的 LangGraph 交互和分析运行时。浏览器负责界面展示、流式进度和用户控件；后端仍负责意图理解、规划、工具选择、执行、验证和重新规划。

liquid-agent web 和 liquid-agent client 都直接在 /#/agent 打开本地智能体工作台。

公开网站：将首页和 Docs 发布到 GitHub Pages，供访客在安装前浏览。Try it 始终直接打开所选语言的入门 > 安装页面，不探测本地服务。
本地应用：使用 liquid-agent web 启动已安装的工作台。使用 liquid-agent wiki（也可用 liquid-agt wiki 或 liq wiki）打开单独部署的公开主页和 Docs。在 CLI 中输入 wiki 或 /wiki 也可打开主页；portal 保留为兼容入口。

门户¶

公开门户采用暗色全屏水面首页，并提供简洁的导航。门户页面固定显示英文，不提供语言切换；访问门户会保留 Docs 和本地工作台已保存的语言偏好：

探索（/#/explore）通过科研工作流和可停止／播放的动态演示介绍液体活检工作台。
我们的故事（/#/story）介绍科学背景与科研愿景，并链接到莱斯特大学的相关资料。
Docs 提供英文和简体中文的安装教程、功能说明、使用指南与图文工作流示例。
Try it 按照已保存的 Docs 语言打开安装页面，其中原有的 Join the Waitlist 按钮用于申请早期使用权限。
页脚提供用户指南、示例、公开门户仓库和使用条款的链接。

水面背景可以暂停；偏好减少动态效果时，在用户主动播放之前显示静态画面，视频无法播放时也有静态回退。门户不会运行分析或自动打开本地工作台。获得访问权限并安装软件后，可使用 liquid-agent web 启动本地工作台。

旧的示例库、指南和关于页面书签会前往相应的 Docs 页面，或新的探索与 我们的故事页面。

界面语言¶

公开门户始终显示英文，不提供语言选择器。门户中的 Docs 链接沿用已保存的文档语言，访问门户不会更改这一偏好。

通过 Docs 或本地工作区标题栏选择 English 或简体中文。如果左侧工作区已收起，请先展开。工作台和不指定语言的文档入口默认使用英文，即使浏览器或操作系统为中文也一样。中文需主动选择；浏览器会跨页面和刷新记住选择，并在同源标签页之间同步。从英文门户返回后，原有语言选择仍会保留。公开部署的 Docs 与本地应用属于不同来源，语言偏好分别保存。

切换语言不会刷新页面、创建新对话、清空草稿、更换 GPT 模型或中断任务。浏览器禁用存储时，当前页面仍可切换。CLI 输出保持英语。

此设置翻译界面文案、导航、弹窗、内置技能名称、状态和控件，不翻译科学内容。界面语言不会决定 Agent 的回答语言，也不会向模型请求附加语言指令；模型根据对话上下文和用户指令自行选择回答语言。用户消息、GPT 回复、报告正文、表格、图形标签、运行时技能文档、文件路径和命令保持原样。您可独立要求 GPT 用中文回答；界面切换不会自动调用翻译服务，也不会额外上传数据。

颜色主题¶

在本地工作区标题区域 LIQUID-Agent 旁边使用 Colour theme。可选配色包括 Soft sage（默认，柔和鼠尾草绿）、Soft rose（淡玫瑰红）、Light blue（浅蓝）和 Warm stone（暖石色）。公开门户采用固定的暗色外观。如果左侧工作区面板已折叠，需要先展开面板才能使用该选择器。

主题只改变界面颜色，包括背景、边框、文本强调色和控件。面板布局、对话状态、分析设置以及科学图形中编码的颜色均不会改变。选择主题不会发起 LLM 请求，不会重启服务，也不会执行分析。

偏好设置按当前网站地址保存在本浏览器中，刷新后仍然有效，并在同一地址的已打开标签页之间同步。不同浏览器、端口和设备各自保存偏好。清除站点存储会恢复 Soft sage；如果禁用了存储，主题选择仍会在当前页面生效，但刷新后无法保留。字体资源随界面本地打包，不会从外部字体服务下载。

侧栏与回收站¶

工作区标志与标题顶部对齐，语言和颜色控件等宽。回收站是紧凑的折叠卡片，展开后可以恢复对话或请求彻底删除。它与对话列表共用滚动区域；现已移除单独的 idle／底部状态栏。

技能使用紧凑的单行列表。小箭头展开分组，名称按钮打开完整指导。只有名称超宽时，悬停或键盘聚焦才会滚动文字；拉宽侧栏后若能完整容纳，则不再滚动。完整名称也保留在提示中。系统的减少动态效果偏好会禁用滚动动画。

点击技能会在工作区和对话之间滑出独立阅读栏。桌面端的对话和结果栏按比例变窄，不覆盖用户保存的宽度；点击右上角叉号或按 Escape 可收回。正文底部的小按钮用于阅读参考资料或请 GPT 讨论当前技能。正文页不显示刷新/概览按钮；只有打开参考资料后才出现“返回技能正文”。参考资料页面不显示当前文件自身的阅读按钮，只保留其他参考资料入口。阅读正文和参考资料只访问本地，不执行分析或调用 GPT； “讨论此技能”是正常的模型对话，不代表授权执行技能。手机端采用滑入阅读面板，避免四列挤在窄屏上。

保存可复用笔记用于保存自己编写的方法规则或个人偏好，供后续任务参考，并与项目维护的技能分开。从文件、文件夹或网址学习用于从参考文档提炼可复用指导，不会安装分析引擎，也不是数据集分析入口。应使用非敏感参考资料，而非患者测量数据。这两个入口都是可选功能，不使用它们也能正常使用内置技能。

桌面端 Sources、Skills 和 Plan 向上展开，因此收起时箭头向上，展开后箭头向下。 Results 向下展开，箭头相反。手机端 Sources 和 Skills 随页面内容向下展开，箭头会适配这个方向。

对话索引保存在 <data-root>/.liquid-agent/conversation-index/：

active/<chat-hash>.json
trash/<chat-hash>.json
deleted/<chat-hash>.json

移入回收站时，将含有已保存 UI 快照的完整索引从 active 转移到 trash。等待写入任务停止后，该对话自有的结果、图表、报告、上传附件及中间处理文件整棵目录搬到 <data-root>/.liquid-agent/trash/conversations/<chat-hash>/；自定义输出根目录使用同盘相邻的 trash/conversations/。原始数据集和其他对话保持不动。恢复时将文件搬回原路径并恢复索引。彻底删除会移除完整索引、该对话自有的结果/上传附件及运行历史；deleted 仅保留以哈希命名的防复活标记，不含消息、标题、路径或结果，用于拒绝延迟请求。

私有 Codex 历史和 LangGraph 检查点也保存在 <data-root>/.liquid-agent/。升级后需重启本地服务，迁移期间不要同时运行新旧版本。旧配置目录中的索引和运行状态会迁移，但不搬动原始输入或已有输出目录。Skills 和 API key 配置不会迁入数据盘。 LIQUID_BIOPSY_TASK_STATE_ROOT 可显式指定状态根目录。未显式指定数据根目录时，本机配置中只保存一个位置指针，用来记住选定数据盘；数据盘断开时需要重新连接，不会悄悄切换到另一套本机任务存储。

智能体控制台¶

运行 liquid-agent web 直接打开智能体控制台。控制台由三个轻量区域组成：

左侧工作区面板用于对话、已附加的 Sources、紧凑的 Metadata 卡片，以及本地 Skills/偏好设置。
中央对话面板用于自然语言交互、实时工作流状态和最终运行摘要。
右侧工作区面板用于 Results 和 Plan 历史，包括可读报告、嵌入图形、关键 Markdown 表格、生成产物和已归档的计划版本。

侧边面板可以调整大小。对话和轻量 UI 状态保存在浏览器本地存储中，因此重新打开应用时，会尽可能恢复本地对话/工作区视图。

Run next step 完成后，客户端会自动刷新结果产物并重新生成下一轮计划。预览区以 Markdown 为主：选中的运行报告是主要面向用户的产物；如有关键结果表格和静态 PNG 图形，则在报告内显示。后端 JSON/TXT 产物和生成的 HTML 页面默认不向用户展示，除非审计或后续分析需要。计划记录、结果评估和 analysis_concept_book.json 等台账产物仍可供后端和 CLI 后续分析路径使用，但不会额外增加界面模式。

计划和结果的后续回答会用自然语言概括计划状态、任务执行、验证、QC、发现、后续方向和后端建议审计，而不是展示原始 JSON。当 LLM 被禁用或暂时不可用时，本地备用指引会根据产物类型和扫描状态选择下一步建议。

安装¶

推荐的本地安装方式：

./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data"

等价的终端形式：

./scripts/install_liquid_agent_cli.sh --user-data-dir "$HOME/Liquid Agent Data"

然后运行：

liquid-agent web
liquid-agent client

获准早期使用后，可选择对应的本地安装或启动命令：

路径	适用情况	命令
Mac 一键安装	从 Finder 打开文件并按提示输入用户信息目录	`./install_liquid_agent.command`
终端安装	工作站或远程 Shell 需要明确的安装日志	`./scripts/install_liquid_agent_cli.sh --user-data-dir "$HOME/Liquid Agent Data"`
Web 工作台	已安装的用户准备对话、添加数据并分析	`liquid-agent web`
直接工作	返回的用户希望立即进入智能体工作区	`liquid-agent client`

启动器在后台调用相同的 Python 分析内核。安装程序会记录用户当前启用的环境，因此运行 liquid-agent web 或 liquid-agent client 前无需再激活该环境。只有明确希望使用另一个 conda 环境时，才使用 LIQUID_AGENT_ENV=<env>。

一键启动器¶

在 macOS 上，仓库还提供：

start_liquid_web.command

双击该文件会通过同一个 npm 启动器启动本地服务并打开浏览器。服务按本地使用方式配置，并在浏览器页面关闭后退出。

停止任务和关闭页面是两种不同操作：停止请求会终止当前科学分析子进程组，但保留本地服务，以便继续发送消息或明确恢复任务。关闭最后一个本地客户端页面时，服务及其活动任务会一并退出，避免遗留分析进程。

浏览器命令¶

liquid-web
liquid-client

liquid-web 是 liquid-agent web 的别名；liquid-portal 是 liquid-agent portal 的别名。liquid-client 是 liquid-agent client 的 npm 别名。本地应用默认监听 http://127.0.0.1:8765，API 路由位于 /api/...。除非传入 --no-open 或设置 LIQUID_AGENT_NO_OPEN=1，两种浏览器命令都会自动打开浏览器。

需要时可以使用其他端口：

liquid-agent web --port 8771
liquid-agent client --port 8771

如何使用智能体控制台¶

安装后运行 liquid-agent web 或 liquid-agent client，浏览器会直接打开工作台。从 New chat 开始，应用会询问是否立即绑定数据集：

已知数据路径时，使用系统原生文件夹选择器选择目录。
文件夹选择器不可用时，手动粘贴路径。
如果只想进行纯对话或了解操作方式，选择 Set up later。

如果后续消息明确指出数据集路径，UI 会创建或更新相应的数据集工作区，并将对话与该工作区关联。

左侧 Sources 卡片显示用户明确附加的数据目录。选择父目录时，界面只显示一个用户数据源；内核仍可检查内部子目录或子队列，用于分析规划，但不会让侧边栏变成令人困惑的内部分区列表。通过添加多个目录，仍可进行明确的多源分析。移除数据源会将其从会话中解除关联，绝不会删除源数据。

添加数据源会进行轻量扫描，并在对话中写入简短摘要：附加了什么、扫描了多少文件、是否选择了元数据标签，以及是否已经启动计划。之后用户可以要求生成计划、输入 /plan，或继续自然交流。在真实计划存在之前，不能启动运行。

附加并扫描数据源后，对话标题区域会提供 Method advice。它会为当前数据源集合写出方法建议报告、刷新结果产物，并在对话中添加简短摘要，列出最匹配的方法和报告路径。

已知元数据或标签状态时，紧凑的 Metadata 卡片会显示在 Sources 下方。卡片展示选中标签、覆盖率、规划模式、后端、置信度，以及 Change/Ignore 控件。卡片有意不显示完整电子表格；详细标签选择应在 Change 对话框或 CLI /metadata 命令中完成。

现有对话可以被选择、删除或重新绑定到数据集。绑定操作刻意保持小巧，与对话行上的其他悬停操作一起显示。

LLM 选择¶

输入框的模型按钮使用可用模型目录，默认 OpenAI GPT，另可选择 Gemini 3.8 Flash。默认选择 GPT-6 Luna（auto）；GPT-6 Sol 和 GPT-6 Astra 是需要用户明确选择的较高费用选项。操作忙碌时不能切换当前模型。Manage keys 会打开可选择服务商的密钥对话框，用于添加、替换或删除密钥。如果保存失败，对话框会保持打开并显示错误。

Manage local models 在任何安装模式下都可用。它显示经过审核且按本机资源筛查的多模态模型，每个模型独立下载，并支持暂停、续传和放弃；放弃会清除该模型的未完成文件。管理框关闭后，模型菜单继续显示下载进度与控制。完成标记会在第一次选择该模型后同步消失，Web 会按需启动安装所拥有的本地运行时。模型权重位于安装时指定的用户信息目录下的 models/ 子目录，系统自动配置，无需填写参数；既有兼容私有服务器仍可通过 CLI/API 管理。

凭据保存在仅文件所有者可访问的本地文件中，绝不存入浏览器存储。删除密钥后，包括现有客户端在内的后续请求都会被禁用，也不会退回使用环境变量中的密钥。已经提交的 OpenAI 请求无法被追溯撤回。Gemini 使用独立密钥，启用前会显示免费层及隐私提示；仅使用公开或不敏感的合成数据。参见 OpenAI 配置。

对话行为¶

Enter 提交提示词。
使用中文、日文或韩文输入法组合输入时，Enter 会先确认正在组合的文本，而不是提交提示词。
Shift+Enter 或 Ctrl+Enter 插入换行。
智能体响应期间，发送按钮变成停止按钮，并阻止新的提交。
用户消息可以编辑。保存并重新发送会截去后续消息，并从编辑位置重新请求智能体回答，并非仅在本地保存。编辑框自动获得键盘焦点，使用清晰可读的主题配色；取消或 Escape 会放弃草稿、保留原消息，空白内容不能提交。
UI 显示经过整理的进度摘要和加载提示，不展示模型私有思维链。
计划或长任务正在运行时，状态卡片保持在对话区域靠近底部的位置。最近工作记录以有长度限制的临时实时信息流展示，不会累积为永久对话气泡。
停止控件通过后端任务端点请求取消。当前安全检查点可能会完成后才退出；最终报告会记录任务是停止、完成还是受阻。

Results 面板¶

报告插图和单独打开的图像均支持内嵌图片查看器。点击放大／缩小按钮调整比例，点击百分比可重置。右上角“适应宽度／适应高度”按钮平滑切换横向填满和纵向填满；放大后可滚动或拖动查看细节。聚焦图片区域后，+ / - 缩放，0 重置，F 切换适应方式。系统的减弱动态效果设置同样生效。“Choose folder”从配置的数据根目录打开目录浏览器。双击文件夹或点击右侧箭头进入下一级，选中后点击“打开”绑定数据。数据根目录之外的位置仍可通过“系统文件夹选择器…”选择。取消不会改变对话。

右侧面板在不需要时保持紧凑。扫描或运行任务后，它可以显示：

按运行或报告分组的结果历史。
选中的 Markdown 报告，以及嵌入的关键表格和静态图形。
来自 assistant/ledger/plan_*.json 的计划历史。
当前可执行计划和已归档的旧计划。
报告链接到的生成产物，或用户审计时需要的产物。
生成图形的图像预览。
结果历史，以及生成输出文件的隐藏/恢复和安全删除操作。
用户询问适合数据集的工具、研究方法或检测类型特定路径时生成的方法建议报告。

从 Results 删除生成报告时，还会删除报告元数据中记录的关联生成文件，前提是这些文件位于系统认可的 Liquid Agent 输出目录内。该操作不会删除原始源数据。

检查表格或图形时，可以拖宽面板。

数据根目录¶

路径解析方式与 CLI 一致：设置 LIQUID_BIOPSY_DATA_ROOT，或通过 API 创建会话时使用可选的 data_root 字段，以获得稳定的默认路径。用户选择的绝对目录也可以直接附加；相对数据集名称会在配置的数据根目录下解析。

例如，用户可以将数据根目录指向任意已挂载的文件夹：

/path/to/your/liquid-agent-data

普通用户机器没有该数据盘时，除非设置了 LIQUID_BIOPSY_DATA_ROOT，否则 Liquid Agent 会回退到本地应用数据目录。

UI 也支持在没有数据盘时进行纯对话、了解操作方式、配置 LLM 和询问文档类问题。

备注¶

完整扫描/自动执行路径加载与智能体相同的 Python 软件栈；如果内核环境已安装相应扩展，还会加载可选模型和文件 IO 依赖。
Web 层调用与交互式 Shell 相同的自动执行引擎，并通过可选的 event_callback / cancel_event 钩子提供流式进度。
本地 UI 集成可通过 /api/session/{session_id}/sources 使用数据源管理 API。
Web 结果路由包括 /api/session/{session_id}/results、/api/session/{session_id}/file 和 /api/session/{session_id}/artifact。删除路由只会移除已被识别为当前会话生成的 Liquid Agent 输出的文件。
长任务使用 /api/session/{session_id}/autopilot、/api/jobs/{job_id}/events 和 /api/jobs/{job_id}/cancel 提供流式状态和安全停止。
浏览器状态属于当前浏览器配置文件。清除浏览器存储会移除保存的对话和 UI 布局状态，但不会删除磁盘上的分析输出。

任务状态与技能审阅¶

任务名称旁的旋转圆圈表示运行中。若完成时您正在其他对话，任务旁会保留蓝点，进入该对话后自动消失。蓝点表示有完成状态待查看，不保证执行成功：仍需阅读最终回复中的失败或取消信息。运行任务所附加的数据源在 Sources 中有高亮边框，不表示所有已附加数据都在同时计算。

Skill changes 保留在产生草案的那轮对话位置，接受或拒绝后也不挪到底部；后续消息会让它滚入历史。待审阅的 Skills 横条最右侧显示小绿色勾和红色叉，可直接接受／拒绝，也可点击技能名称查看差异。这里显示的是当前所选对话的草案；查看其他任务的草案需要进入相应对话。

新版工作区图文操作提供完整界面截图，并介绍密钥管理、多图提问及 Plan 到 Results 的操作衔接。

跟随真实操作，而不只是阅读功能列表¶

GSE174302 图文流程从目录选择、元数据核对、技能阅读、计划审阅开始，完成六项科学任务，再操作 Results 按钮、PCA 选区、双图追问、技能接受／拒绝与报告纠正。独立图片对话演示上传两张实际 PNG，以及垃圾箱恢复。新增截图全部来自这次实际调用 API 的浏览器会话。

分项步骤见图片与选区截图和技能审阅截图。场景集合里本次没有执行的其他检测提问，已明确标为模板。

紧凑侧栏状态¶

左侧栏展开时显示 LIQUID-Agent Logo 按钮；收起后换成展开侧栏图标，下方单独的 + 用于新建任务。窄栏隐藏任务选择控件；点击垃圾桶会展开侧栏并显示完整回收站列表。先展开侧栏，再选择并链接任务。刷新页面仍保留之前保存的栏宽。