返回 Liquid Agent 首页 使用文档

安装（中文）

Join the Waitlist

早鸟体验申请获批后，请下载并解压邀请中提供的软件包，或使用邀请中提供的访问信息克隆代码。 安装后保留代码目录，启动命令依赖该目录。前提是本机已安装 Python 3.11+（建议 3.12） 及 Node.js/npm；安装器不会连带安装 Python 或 Node。

安装包分发与开源计划

我们计划提供打包好的安装包，点击安装程序即可安装 LIQUID-Agent。 测试阶段结束后，我们会将本软件开源。开源版本会比安装包版本更及时地获得项目更新。

以下内容是开源版本的源码安装教程。测试阶段请使用向你提供的源码包或代码仓库访问权限。

一条命令安装

在项目目录打开终端。如果使用 conda 或 virtualenv，先激活想用的环境。 所有应用 Python 依赖装入该解释器；未激活时用 PATH 中的 Python。 不会自动切换到其他应用环境，也不会绕过系统 Python 的写保护。

macOS（终端或 Finder）：

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

Linux：

bash install_liquid_agent_linux.sh --user-data-dir "$HOME/Liquid Agent Data"

Windows（PowerShell 或命令提示符）：

.\install_liquid_agent_windows.cmd -UserDataDir "D:\Liquid Agent Data"

Windows 文件仅在本次 PowerShell 进程中绕过执行策略，并调用 Windows 安装入口。 Linux 与 macOS 文件只调用 POSIX 安装入口；Windows 专用的命令和 PATH 处理 仍限定在共用 Python 安装器的 Windows 分支。 在线与本地模型安装都必须明确选择独立于项目源码的用户信息目录。在终端运行时 若未传参数，同一个安装器会询问绝对路径。安装器在所选目录下分别创建 credentials/、 memory/、skills/、tasks/、models/，更新应用时继续使用此目录。 显式解释器可在 macOS/Linux 设置 LIQUID_AGENT_PYTHON=/absolute/path/to/python， PowerShell 使用 -Python C:\path\to\python.exe；高级 conda 用户可用 LIQUID_AGENT_ENV 指定已经存在的命名环境。

安装会配置 Python 依赖、构建 Web 与双语文档、创建私有用户目录并注册启动命令。 安装后打开新终端。命令保存安装解释器，conda 会自动进入记录的环境； 环境被删除或改名后需重新安装命令。

liquid-agent       # Web workspace
liquid-agent cli   # Terminal interface
liq                # Short alias for Web
liquid-agent wiki  # Project homepage and documentation

liquid-agent web 和 liquid-agent client 也打开 /#/agent。介绍页 Try it 直接打开本安装指南，不检查或启动本地工作台。若要进入已安装的工作台，请使用启动器 在终端打印的地址。自定义端口使用 liquid-agent wiki --port YOUR_PORT 或服务自身 URL。

可选本地模型

不加 local 时只安装在线模型使用版，不显示本地模型菜单、不下载权重。 本地安装使用相同的用户信息目录，模型放在其中的 models/ 子目录：

bash install_liquid_agent_linux.sh --user-data-dir "$HOME/Liquid Agent Data" local

.\install_liquid_agent_windows.cmd local -UserDataDir "D:\Liquid Agent Data"

macOS 对应命令为 ./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data" local。

遗漏用户信息目录或使用相对路径会在安装依赖前报错，含空格须加引号。 此目录存储应用个人数据，与工作区内选择的研究数据盘分开。

CLI 菜单显示审核过的多模态 Ollama 候选、下载量及工作内存估计。输入编号后检查 系统、可用内存／显存和磁盘，保留科研工作的余量。通过后下载视觉模型及编码器， 按计划配置上下文并运行基本工具调用探测。请在实际使用的设备上评估多图、连续 对话、多步工具及长任务的表现；加载或探测失败表示该配置尚不可用。

8 GiB 显存设备的默认 32K 上下文 Qwen3.5 4B 可能超过预留显存预算。可将 [{"model":"qwen3.5:4b","context_tokens":24576}] 保存为 JSON 模型列表，再运行 install_liquid_agent_windows.cmd local -UserDataDir "D:\Liquid Agent Data" -ModelsList "C:\path\to\models.json" -Yes。 这会缩短实际安装的上下文并重新估算容量，但仍须以目标电脑上的加载和工具探测为准。 如果完整 Web 对话和科学工具超出上下文预算，请减少其他内存占用或选择更大的上下文。

纯文本 Qwen3 GGUF 选项已移除。候选为 Qwen3.5 4B/9B、Qwen3.8 27B 和 Muse Glimmer 30B，依据官方 model card 保留，并受容量筛查约束。 既有配置和密钥会保留。本地语言模型说明完整设置方式。 安装探测不代表已经确认科研准确性或长任务可靠性。

本地安装保留云端密钥和固定型号，Web 模型菜单或 CLI 随时切换。 使用 liquid-agent local-models serve 启动托管服务，再选择对应配置。 关闭最后一个 Web 页面时，Liquid Agent 会通知本次托管的 Ollama 服务退出； 独立安装或用户自行启动的 Ollama 不会被停止。 高级自动化可使用 --user-data-dir PATH --with-local-models --model MODEL --yes （PowerShell：-UserDataDir PATH -WithLocalModels -Model MODEL -Yes）。 旧 --models-dir 参数只有等于 PATH/models 时才有效。 安装器的 --dry-run / -DryRun 只跳过模型部署，仍安装依赖与命令。 仅检查模型计划：

python -m liquidbiopsy_agent.local_setup setup --models-dir /absolute/path/models --dry-run

macOS、Linux 与 Windows 更新

本地 Web 工作台打开时会检查 GitHub 上较新的稳定版。发现新版本后显示可关闭的 提示；关闭后继续使用旧版，也可随时点击工作台中的 Check for updates。 提示仅提供版本说明和终端命令，不会自动安装。

liquid-agent update --check
liquid-agent update
liquid-agent update --rollback

在原始仓库目录中，macOS 可使用 ./update_liquid_agent.command，Linux 可使用 bash update_liquid_agent_linux.sh，Windows 可运行 .\update_liquid_agent_windows.cmd。更新器先准备隔离的新程序版本与 Python 环境， 构建 Web 界面，然后切换启动命令。准备失败时继续使用当前版本。 原先选定的用户信息目录、加密密钥、记忆、任务、个人技能与本地模型保持原位。 更新或回退后请重新启动正在运行的 Web 工作台。首次更新也会把已有的可编辑安装 转为受管理的版本目录。Windows 的托管版本位于 %LOCALAPPDATA%\liquidbiopsy_agent\app；更新或卸载前请关闭 Web 工作台。

若旧安装尚不识别 liquid-agent update，请下载当前发布版的源码，运行其中的 对应系统的更新脚本一次。脚本读取原安装收据，并沿用原 Python 环境完成首次升级。 早于强制指定用户信息目录的旧安装，须先以 --user-data-dir 重新运行安装器。

安全卸载

先关闭 Web 工作台；其托管的 Ollama 会一起退出。若只启动过模型服务而未启动 Web， 先按 Ctrl+C 停止。首次更新前，从安装时的同一代码目录、同一 Python 环境运行 卸载程序；更新后使用 liquid-agent uninstall，由当前受管理版本完成卸载。 先预览精确删除路径：

bash scripts/uninstall_liquid_agent_cli.sh --dry-run --purge-private --purge-models
bash scripts/uninstall_liquid_agent_cli.sh --yes --purge-private --purge-models

受管理的安装可改用：

liquid-agent uninstall --dry-run --purge-private --purge-models
liquid-agent uninstall --yes --purge-private --purge-models

Windows PowerShell：

.\scripts\uninstall_liquid_agent_cli.ps1 -DryRun -PurgePrivate -PurgeModels
.\scripts\uninstall_liquid_agent_cli.ps1 -Yes -PurgePrivate -PurgeModels

不加清理选项时，只移除本代码目录安装的 Python 包、启动命令和 PATH 登记。 更新后保留用于回退的原可编辑 Python 包及受管理的程序版本也会一并移除。 --purge-private 还会清除本次安装的设置、已保存凭据、对话、记忆和个人技能。 --purge-models 仅清除由安装器创建并标记归属的模型目录；既有或未标记的 模型目录保留。源码目录、输入数据和共用的 Python/Node 依赖始终保留。 无法确认归属时，卸载器会拒绝删除，不会猜测。

浏览器站点存储属于各自的浏览器配置，命令行卸载器不会跨浏览器清理。若要立即清除， 在关闭 Web 前打开其本地地址并加上 ?reset-ui=1。全新安装首次打开时也会识别 不同的安装标识，清除前一次安装的缓存会话列表。

私有存储与任务数据

安装必须指定独立于源码的用户信息目录。每个任务再独立选择研究数据输入目录。 所选父目录下分别存放 credentials/、memory/、skills/、tasks/、 models/。更新或重新安装应用时继续选择同一个父目录；已有安装可选择原私有 应用目录，并在本地模型部署前把既有模型文件移至其中的 models/。

私有目录含配置、凭据、记忆、个人技能、任务状态。云端与私有端点 API key 使用 Fernet 认证加密，主密钥在 macOS 钥匙串、Windows 凭据管理器（仅本机持久化）或 Linux Secret Service。凭据库缺失／锁定时明确报错，不回退明文。无桌面系统可由秘密管理器注入 LIQUID_AGENT_VAULT_KEY，不要提交或记录。环境变量提供的服务商密钥无需保存磁盘。

软件没有这些目录的自动云备份／上传机制，也不允许把私有配置／全局记忆目录当作数据源。 云端提示默认不附加全局记忆；个人指导沿用显式技能审阅披露边界。记忆依靠文件系统权限， 不是应用级加密。目录应避开用户配置的同步盘和源码管理。 使用云端服务时，当前用户消息、允许的汇总、明确上传的图像仍会发送到所选提供商， 参见本地数据与隐私。

可选科学依赖与诊断

标准安装含 web,docs,ml,assay-tables,tools,skills。 特殊编码器、格式和外部工具另装，不要把不兼容的 ML 版本约束盲目装到一个环境。

python -m pip install -e ".[blood-io]"
python -m pip install -e ".[report]"

blood-models 是有独立版本约束的科学编码器 extra；local 才是本地模型部署 extra， 没有 local-llm。原生包供应因系统而异，尤其是 pysam、pyBigWig 和外部 Unix 工具。 WSL 使用 Linux 安装路径，不等同于原生 Windows 安装。