基于实验室抗体库存的流式细胞多色 panel 设计工具。SQLite 保存实验室数据，确定性算法负责查询、通道约束搜索和诊断，AI 助手负责组织工具调用与解释结果。
当前版本 0.2.0。一个内核、三个使用入口，共用相同的数据和计算规则：
| 入口 | 当前能力 | 运行依赖 |
|---|---|---|
| CLI + Skill | pa 查询、初始化/CSV 导入、质量标注、生成和诊断；附带 panelagent-cli Skill |
Python 核心包 |
| MCP | pa mcp 提供 10 个只读/纯计算工具，供 agent 宿主调用 |
核心包 + [mcp] |
| WebUI | 浏览器工作台、库存导入、管理员质量维护、候选历史；可选 AI 对话 | [backend,mcp] + Node / Next Web 包 |
CLI、MCP 和 Web 手动配色均无需模型或 API key。Web 对话需要另行配置支持工具调用的 OpenAI 兼容模型。
需要 Python 3.10+，其内置 SQLite 至少 3.35。首次安装依赖需要联网。
git clone https://github.com/PanCodeInventory/PanelAgent.git
cd PanelAgent
python3 -m venv .venv
.venv/bin/python -m pip install .
source .venv/bin/activate
pa --helpWindows PowerShell 在仓库根目录执行：
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\pa.exe --help下文的 pa 指该安装环境中的可执行文件；未激活环境时使用其完整路径。
如果已经取得 panelagent-cli-0.2.0-install.zip，解压后运行：
python3 install-cli.py # Linux / macOSpy -3 install-cli.py # Windows安装器创建独立虚拟环境，安装本地 wheel，自动执行 11 组 CLI 自检，并在安装目录生成 cli-check-report.json。已有安装可用 --check 复查；自定义位置用 --prefix。
压缩包包含安装脚本、自检脚本、wheel、README、AGENT_GUIDE.md 和校验文件。可直接让 agent 阅读 AGENT_GUIDE.md，协助完成安装、Skill 导入和后续使用。
dist/ 是本地构建输出，已被 Git 忽略；克隆仓库不会得到压缩包。 当前文档不假设包已发布到 PyPI 或 GitHub Releases。构建方法见下文，使用步骤见 CLI 安装指南 和 agent 操作指南。
使用测试包安装器时的默认位置：
| 内容 | Linux / macOS | Windows |
|---|---|---|
| CLI 环境 | ~/.local/share/panelagent/cli/ |
%LOCALAPPDATA%\PanelAgent\cli\ |
| 实验室数据库 | ~/.local/share/panelagent/panelagent.db |
%USERPROFILE%\.local\share\panelagent\panelagent.db |
源码安装的程序位于自己创建的虚拟环境中。数据路径统一按 --db > PANELAGENT_DB > 默认值 选择，可用 pa db path 查看；路径输出不代表数据库已经存在。
一个数据库对应一个实验室，其中可包含多个抗体库和多台仪器。原始 CSV 保存在自己的实验室目录，导入后以 SQLite 为运行数据；编辑原 CSV 不会自动同步。安装器仅用临时数据自检，不建立正式实验室库。
Skill 需要单独安装到 agent 宿主实际支持的目录：
pa skill install --dest /path/to/your/agent/skills实际生成 <dest>/panelagent-cli/SKILL.md。已有文件默认拒绝覆盖，明确需要更新时使用 --force；复制后按宿主机制刷新发现列表。当前只分发 panelagent-cli，其他使用侧 Skills 仍在规划中。
首次建立新实验室库的示例：将 CSV 路径和库名替换为实际值。
pa init --db ./lab-data/lab.db --csv Mouse=./mouse.csv --json
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 --json
pa --db ./lab-data/lab.db panel generate --library Mouse --markers CD3,CD4,CD8 --instrument-id 1 --json
pa --db ./lab-data/lab.db panel diagnose --library Mouse --markers CD3,CD4,CD8 --instrument-id 1 --json仪器 ID 以查询结果为准。CSV 主要识别 Target（或 Name）、Fluorescein、Clone、Brand、Catalog Number，使用 UTF-8 编码。CLI 此入口直接读取 CSV，Web 可导入 CSV/XLSX/XLS。
安装包附带 Beckman/CytoFLEX 参考配置、荧光素光谱参数、亮度和别名，不附带正式实验室数据库、真实库存、质量记录、历史方案或模型密钥。参考仪器必须与实际机器核对后使用。
日常查询和质量标注示例：
pa --db ./lab-data/lab.db antibody list --library Mouse --target CD3 --json
pa --db ./lab-data/lab.db antibody annotate 1 --library Mouse --flag warn --note "需要重新滴定"标注前先查询并确认抗体 ID。bad 抗体默认不参与生成；需要纳入时明确使用 --include-bad。
- 多仪器计算已支持，通用新增入口尚未完成。 单台自动选择，多台必须显式选择；
pa init --config-dir仍更新固定的 Beckman/CytoFLEX 配置，不能借此新增任意型号。 - 日常库存维护 CLI 仍需完善。
pa init每次都会重新写入内置参考数据；目前没有独立的库存追加/更新命令或导入--dry-run。不要把首次初始化当作维护已有定制库的无副作用入口。 - 生成结果是候选。 算法保证通道不冲突，不代表表达量/亮度的全局最优匹配、spreading 建模、全光谱解混或实验适用性。缺失亮度保持未知。
- 无解与未完成搜索不同。 搜索预算耗尽会报错，不能据此断言无解；诊断
ok只是初步检查，仍需实际生成验证。 - 质量与历史的入口有差异。 Web 支持管理员清空质量、保存候选到共享历史；CLI 当前可标注 good/warn/bad，但没有质量清空或共享历史写入命令。
旧独立质量登记 API 已退休为 410，质量直接保存在抗体行上。旧质量 JSON 和旧历史库须显式迁移，见 SQLite 迁移指南。
在同一源码目录和虚拟环境中安装可选依赖：
python -m pip install '.[mcp]'
pa mcp --db /absolute/path/lab.db使用 wheel 时则安装该本地文件的 [mcp] extra。数据库需提前准备，MCP 不负责初始化或写入。
工具覆盖实验室统计、库/仪器/marker 发现、荧光素/通道查询、抗体搜索、生成和诊断。宿主通过 stdio 启动服务，stdout 专用于协议消息。配置示例和工具契约见 MCP 指南 与 宿主配置示例。
源码安装脚本适用于 Bash 环境，需要 Node.js 20.9+、npm 和 Python：
bash scripts/setup-web.sh
# 按需编辑 config/.env
.venv/bin/pa web --env-file config/.env打开 http://127.0.0.1:3000/exp-design。pa web 同时启动 Next 与 FastAPI，并为两者和 MCP 注入一致的数据库及模型配置；Ctrl+C 停止服务。
- 实验工作台：选库、选仪器、维护 marker、手动生成/诊断；配置模型后支持对话、工具进度、取消和重试。
- 库存与质量：导入库存、筛选查询；设置
ADMIN_PASSWORD后可登录管理员修改质量。 - 历史与设置：保存候选及生成时条件，查看共享历史和实际生效的模型配置。
模型留空时可使用手动模式。配置通过环境传入，设置页不保存另一份密钥。独立部署需要另外构建 Next standalone 包，CLI 测试压缩包不含 WebUI。
Web 需要 Node 服务端和 Python MCP 子进程，不支持纯静态托管。安装、配置及操作边界见 Web 工作台指南。旧独立管理前端已移除，桌面打包脚本保留作历史迁移参考。
开发环境：
python -m pip install -e '.[backend,mcp,dev]'
npm ci --prefix frontend
make test-backend PYTHON=.venv/bin/python
make lint-backend PYTHON=.venv/bin/python
make typecheck-frontend
make lint-frontend
PYTHON="$PWD/.venv/bin/python" make generate-client check-drift
npm run test:e2e --prefix frontend上述 Python 命令在项目虚拟环境内运行。维护者构建分发物：
python3 scripts/build-release.py # wheel、sdist、Skill 包及隔离安装验收
python3 scripts/build-cli-installer.py # CLI 跨机器安装测试包，附 agent 指南
python3 scripts/build-release.py --with-web # 另构建并归档 Web 包Web 包需按目标平台构建。本地已完成 Linux 上的隔离安装与 Web 全链路验证、314 项 Python 测试（含 CLI 回归）、36 项浏览器测试和 11 组安装自检；其他系统仍需目标机器验证。模型联调用本地模拟服务完成，不代表已验证所有模型供应商。
更多细节见 内核 API、分发指南 和 使用侧 Skill 规划。
panelagent/ SQLite 内核、CLI、MCP、包内参考数据与用户 Skill
backend/ FastAPI：库存、质量、历史和模型适配
frontend/ Next.js Web 工作台
config/ 参考数据编辑源与环境配置示例
scripts/ 安装、自检、构建和数据迁移
examples/ MCP 宿主配置示例
tests/ Python 测试；浏览器测试位于 frontend/e2e/
docs/ 接入、迁移、分发与使用指南
MIT License，见 LICENSE。