Skip to content

cli-agent-guide.md

Latest commit

 

History

History
177 lines (121 loc) · 10.7 KB

cli-agent-guide.md

File metadata and controls

177 lines (121 loc) · 10.7 KB
Raw

PanelAgent CLI：给使用侧 agent 的指南

本指南随 CLI 安装包提供。你的任务是协助用户安装、自检、导入 Skill，并使用实验室实际库存设计 panel。无需访问 PanelAgent 源码仓库。

先判断用户处于哪一步，直接继续尚未完成的工作。用户已安装成功时，不要重新安装；已给出的路径、选择和操作授权继续有效。只对无法从当前环境或会话确定、且会影响操作的必要信息提问。

1. 识别安装包与运行环境

包内应包含 install-cli.py、verify-cli.py、一个 panelagent-…-py3-none-any.whl、README.md、本指南和 SHA256SUMS。安装脚本需要相邻的自检脚本；不要只复制其中一个文件。

  • 需要 Python 3.10+，其 SQLite 至少 3.35，以及 venv/pip。安装器会检查版本。
  • Linux/macOS 通常使用 python3；Windows 通常使用 py -3。先检测实际可用的解释器。
  • PanelAgent 本体从包内 wheel 安装；首次安装仍需联网取得 pydantic 等依赖。不要将此包描述为完全离线安装包，也不要改用包索引上未经确认的同名包。
  • 默认只安装 CLI。执行本指南的查询和计算不需要模型密钥、Node 或 MCP。

2. 安装或验证已有安装

从解压目录执行。Linux/macOS：

python3 install-cli.py
# 自定义位置时使用明确的路径，例如：
python3 install-cli.py --prefix ./my-cli

以上是二选一，通常执行一次即可。Windows PowerShell 对应为：

py -3 .\install-cli.py
# 或指定位置：
py -3 .\install-cli.py --prefix .\my-cli

默认安装位置及 CLI 路径：

系统 安装目录 CLI 相对安装目录的位置
Linux/macOS ~/.local/share/panelagent/cli/ bin/pa
Windows %LOCALAPPDATA%\PanelAgent\cli\ Scripts\pa.exe

用户使用过 --prefix 时，以该路径和安装输出为准。可核对安装目录中的 .panelagent-cli-install.json 及 cli-check-report.json。不要仅因终端里有一个同名 pa 就认定找到了本次安装。

默认路径直接调用示例：

"$HOME/.local/share/panelagent/cli/bin/pa" --help
& "$env:LOCALAPPDATA\PanelAgent\cli\Scripts\pa.exe" --help

下文的 pa 均指已经确认的安装环境中的可执行文件；不在 PATH 时替换为其绝对路径，PowerShell 使用 & 调用。带空格路径必须正确引用。

版本可从本次自检报告的 version 字段读取。当前 CLI 没有 --version 参数；也可用安装环境内的 Python 查询，例如默认路径：

"$HOME/.local/share/panelagent/cli/bin/python" -c "from importlib.metadata import version; print(version('panelagent'))"
& "$env:LOCALAPPDATA\PanelAgent\cli\Scripts\python.exe" -c "from importlib.metadata import version; print(version('panelagent'))"

已有安装需要复查时，在解压目录运行：

python3 install-cli.py --check
# 若原来指定了安装位置，复查时也指定同一位置：
python3 install-cli.py --prefix ./my-cli --check

Windows 同样把 python3 换成 py -3。自检不联网，使用临时数据库和临时 Skill 目录，结束后清理。

成功依据是命令退出码为 0，且本次 cli-check-report.json 的 status 为 passed。安装失败时，旧的成功报告不能证明本次成功。不要删除未被安装器管理的已有目录来绕过拒绝提示；改用用户允许的新安装路径。

3. 安装并启用用户 Skill

当前包只包含 panelagent-cli 这个 Skill。它的安装和 CLI 安装是两个步骤，自检中的临时 Skill 也不算已安装到用户的宿主。

  1. 从用户要求、宿主配置或已知宿主规范确定 Skill 根目录，以及项目级/用户级范围。目录无法确定时，只询问宿主名称和安装范围，不猜测所有 agent 都使用同一个路径。

  2. 运行安装命令，例如用户明确选择 ~/.agents/skills 时：

    pa skill install --dest ~/.agents/skills --json

    Windows 示例（仅当该宿主使用此目录时）：

    & "$env:LOCALAPPDATA\PanelAgent\cli\Scripts\pa.exe" skill install --dest "$env:USERPROFILE\.agents\skills" --json

  3. 验证实际生成了 <dest>/panelagent-cli/SKILL.md，读取其操作说明。目标已存在时先检查内容；相同内容可直接复用，需要更新且已在用户授权范围内时才加 --force。

  4. 按宿主机制刷新 Skill 列表或新建会话，确认宿主能发现 panelagent-cli。文件复制成功和宿主发现成功分别报告；不能观察宿主状态时明确说明待用户刷新确认。宿主暂不支持 Skill 自动加载时，可以让 agent 显式读取该文件执行工作流。

规划中的数据管理、设计、复盘独立 Skills 尚未随此包提供，不要声称已安装它们。

4. 定位实验室数据

程序目录、数据库和 Skill 目录各自独立。 CSV 放在用户自己的实验室文件夹即可，无需写入安装环境的 site-packages 或包内 seed。

  • 数据库优先级：本次命令 --db PATH > PANELAGENT_DB > ~/.local/share/panelagent/panelagent.db。
  • Windows 的当前默认数据库也在用户主目录下，即 %USERPROFILE%\.local\share\panelagent\panelagent.db，不在 CLI 的 LocalAppData 安装目录中。
  • pa db path 显示本次命令选择的路径，不创建数据库；它不会记住之前某条命令的 --db。用户已选定数据库后，在后续调用里保持同一个显式 --db 或环境配置。
  • 路径输出不证明文件已存在、schema 有效或属于当前实验室。先检查文件是否存在；用户已明确选定已有数据库时，再用只读 db stats 核对。
  • 一个 SQLite 数据库对应一个实验室，其中可有多个抗体库。安装自检不会创建正式实验室库。
  • 导入后 SQLite 是运行事实来源，编辑原 CSV 不会自动同步。

用户已有数据库时，先查询该库，不默认创建另一个空库，也不为了修复查询失败而直接在原库运行 init。

5. 首次导入与后续维护

首次导入需要用户的库存 CSV、抗体库名称和目标数据库路径。目标路径应在用户指定的实验室目录中，并明确是新建还是已有库。

当前 CSV 识别的主要列为 Target（或 Name）、Fluorescein、Clone、Brand、Catalog Number。为了可用于配色，应有可识别的 marker 和荧光素。CSV 需为 UTF-8；CLI 此入口不直接导入 Excel。需要格式转换时保留原文件，对副本转换并检查列、中文和行数。

以下示例仅用于用户要求建立的新数据库，路径、库名和 marker 均需替换为实际值：

pa init --db ./lab-data/lab.db --csv Mouse=./mouse.csv --json
pa --db ./lab-data/lab.db db stats --json
pa --db ./lab-data/lab.db library list --json

读取导入返回的行数与 warnings，再查询实际库内容；不能只凭退出码认定每一行都成功导入。

当前边界：

  • 每次 pa init 都重写内置参考数据；当前尚无独立的库存追加/更新命令或导入 --dry-run。向已有定制库增加库存时，说明此副作用并明确处理方式，不把首次初始化命令当作无副作用的日常导入。
  • --config-dir 仍更新固定 Beckman/CytoFLEX 配置，当前不能通过通用命令新增任意仪器型号。需要新增仪器时收集实际配置并报告入口缺口，不编造 pa instrument add 等命令。
  • 多仪器的查询、选择、生成已支持；多台时必须显式指定仪器 ID。参考仪器不代表用户实际机器的配置。
  • 质量维护可用 pa antibody annotate ID --library LIB --flag good|warn|bad --note TEXT。先查询并确定唯一记录及所属库；当前 CLI 没有清空质量的专用选项。
  • 需要数据库备份时采用 SQLite 一致性备份方法；不能假设复制正在写入的单个 .db 文件就包含全部 WAL 数据。

6. 日常查询、生成与诊断

先发现库、仪器和 marker，再根据用户条件计算；已确认的条件可复用。示例：

pa --db ./lab-data/lab.db library list --json
pa --db ./lab-data/lab.db instrument list --json
pa --db ./lab-data/lab.db marker list --library Mouse --limit 100 --offset 0 --json
pa --db ./lab-data/lab.db antibody list --library Mouse --target CD3 --json
pa --db ./lab-data/lab.db panel generate --library Mouse --markers CD3,CD4,CD8 --instrument-id 1 --max 10 --json
pa --db ./lab-data/lab.db panel diagnose --library Mouse --markers CD3,CD4,CD8 --instrument-id 1 --json

库名与仪器 ID 以查询结果为准。marker 分页不足时继续读取。bad 抗体默认排除；用户要求纳入时使用 --include-bad，并保持生成和诊断的条件一致。

返回结果时说明所用数据库/库/仪器、marker、质量设置以及候选限制。缺失亮度保持未知；模型建议不能伪装成查询到的库存。候选只保证通道无冲突，不代表表达量优化、spreading 建模或实验验证。

同时检查进程退出码和 JSON 内容：

  • 非零退出码和 {code,error}：参数、数据库或执行错误，按具体原因处理。
  • 生成返回 status: error 和诊断：本次搜索未找到可用候选，属于业务结果。
  • search_budget_exhausted：搜索未完成，不能据此断言无解。
  • 诊断 status: ok 只是初步冲突检查，不能替代候选生成。

需要保存方案时可按用户指定路径导出 CLI JSON。当前 CLI 没有 Web 共享历史写入命令，不声称文件导出已同步到 Web 历史。

7. 故障处理与交付给用户的信息

现象 下一步
pa 找不到 查实际 prefix，使用其中的绝对路径；不立即重复安装
Python/SQLite/venv 不满足要求 报告具体缺项，按用户系统处理；需要系统级安装时遵循当前环境权限
下载依赖失败 保留错误，检查用户配置的网络/包源；不要关闭 TLS 验证或随意替换来源
wheel 校验不匹配 重新取得完整压缩包，不跳过校验
Skill 目标已存在 比较内容，按用户意图复用或更新
database_missing 核对显式路径；确认确实需要新建后再初始化
multiple_instruments 列出仪器并确定本次 ID
没有候选 阅读诊断，区分缺库存、通道冲突和质量筛选；讨论条件调整

完成后简要交代：CLI 可执行文件位置和版本、自检是否通过及报告路径、Skill 实际安装位置和宿主发现状态、正式数据库位置或“尚未建立”，以及下一条适用于用户当前状态的命令。

排障报告优先使用安装目录的 cli-check-report.json；安装阶段失败时提供具体错误。报告无需包含模型凭据或整份私人库存。