Skip to content

distribution.md

Latest commit

 

History

History
154 lines (124 loc) · 8.67 KB

distribution.md

File metadata and controls

154 lines (124 loc) · 8.67 KB
Raw

PanelAgent 分发指南（v0.2.0）

本文说明正式分发物、构建方式、干净环境验证与发布流程。运行原理见 docs/panelagent-core.md；MCP 接入见 docs/mcp.md；Web 工作台见 docs/web-workbench.md。

1. 三个入口与发布物

入口 安装形态 依赖
CLI pa（init/查询/生成/诊断/skill 分发） wheel（核心） 仅 pydantic
stdio MCP 服务器 pa mcp wheel + mcp extra mcp>=1.29.1,<2
pa serve（FastAPI 后端）+ pa web（Web 工作台） wheel + backend extra（serve）；web 另需独立构建的 Node 产物 见下

scripts/build-release.py 产出（dist/，已 gitignore）：

panelagent-0.2.0-py3-none-any.whl   核心包：panelagent（含 web.py、seed、skills）
                                    + backend 包 + 根级领域模块
panelagent-0.2.0.tar.gz             sdist（wheel 的构建来源）
panelagent-skills-0.2.0.zip         用户 skill 独立档案（供不装 wheel 的宿主）
panelagent-web-0.2.0.tar.gz         可搬迁 Web 产物（仅 --with-web；平台相关）

CLI 与 MCP 不依赖 backend extra 或 Node；backend extra 才引入 FastAPI/pandas 等重依赖。Python extra 只有一个 backend，没有 web extra——pa web 启动的是独立构建的 Next standalone 产物。

2. 版本与包内容

  • 版本单一来源：panelagent/__init__.py 的 __version__，pyproject 以 setuptools.dynamic 读取。改版本只改这一处。
  • wheel 无条件附带：backend/ 包、根级领域模块 data_preprocessing/panel_generator/llm_api_client/spectral_viewer （backend 经 importlib 惰性加载；只有 [backend] extra 才装其第三方 依赖）。开发脚本 launcher.py、_convert_txt.py 不打包。
  • package-data：panelagent/data/seed/（光谱/别名/亮度/仪器快照）与 panelagent/data/skills/（用户 skill）。config/ 是仓库编辑源，不 进 wheel；pa init 在无 --config-dir 时使用包内 seed。

3. 构建与可复现性

python3 scripts/build-release.py                  # wheel+sdist+skills + 全部验证
python3 scripts/build-release.py --with-web       # 另跑 npm run build:bundle 并归档
python3 scripts/build-release.py --skip-verify    # 只构建+内容审计
python3 scripts/build-release.py --verify-dir /tmp/panelagent-0.2.0-verify
                                                   # 干净房 venv/目录持久保留，供下游验证（如 pa web 全链）
  • 脚本自建隔离构建 venv（钉住 build==1.2.2、setuptools==77.0.3、 wheel==0.45.1、pip==24.0），并以 SOURCE_DATE_EPOCH（环境变量 → git HEAD 提交时间 → 固定回退值）固定全部时间戳：sdist 会被重写为 排序条目+固定 mtime/gzip 头，wheel+sdist 在同一源码状态下字节可 复现（已背靠背验证）。多代理仓库中若构建间隙有文件落盘，产物自然 不同——以 SOURCE_DATE_EPOCH 对应的提交为复现锚点。
  • Web 产物（--with-web）：在临时目录构建 Next standalone，再生成 panelagent-web-<version>.tar.gz；新构建成功后原子替换同名档案，保留 dist/panelagent-web/ 手动构建目录。Web 包与 Node 版本/平台相关， 每个目标平台应分别构建。本次包在 Linux x86_64、Node 22 上验收。 独立构建用 cd frontend && npm run build:bundle；已有输出目录时可 通过 npm run build:bundle -- /new/output/path 指定新目录。

4. extras 与同步义务

extra 内容
（默认） pydantic>=2
mcp mcp>=1.29.1,<2
backend 镜像 backend/requirements.txt（fastapi、uvicorn[standard]、pydantic、pydantic-settings、python-multipart、pandas、numpy、scipy、openai、openpyxl、xlrd（.xls 上传）、python-dotenv、itsdangerous）
dev pytest>=8、ruff>=0.6

同步义务（改动一侧时必须同步另一侧）：

  1. backend/requirements.txt ↔ pyproject [project.optional-dependencies].backend。
  2. config/*.json ↔ panelagent/data/seed/（既有规则，见 panelagent-core.md）。
  3. panelagent/data/skills/ ↔ skill 档案（构建时自动包含）。

后端运行数据已改为 SQLite；project_root() 仅保留给历史开发工具， 安装包运行不依赖仓库配置文件。构建脚本覆盖 backend 安装与导入，服务 启动和实际 Web 链路的验证结果见第 8 节。

5. 发行检查（脚本内置）

editable 安装会掩盖缺文件，因此验证全部基于"干净 venv + wheel 安装 + cwd 离开仓库 + HOME 重定向"：

  1. wheel 内容审计：必须含 seed 五件、skills（SKILL.md）、 backend/app/**、四个领域模块、panelagent/web.py、LICENSE、 METADATA 版本与 Provides-Extra: mcp/backend；必须不含 config/、tests/、frontend/、docs/、__pycache__、.env。
  2. sdist 审计：pyproject/LICENSE/MANIFEST/seed/backend/领域模块在， 且 wheel 由该 sdist 构建。
  3. 干净房 core+mcp：pa init（seed 必须来自 wheel，不碰仓库 config/）→ pa db stats → pa marker list（发现）→ pa panel generate（含成功候选）→ pa panel diagnose → 原生 JSON-RPC stdio 握手（initialize → tools/list 恰好 10 个工具 → db_stats 调用）→ pip check → 版本断言（wheel 元数据 == panelagent.__version__）。
  4. 干净房 backend：安装 wheel[backend] → pip check → import backend.app.main 与四个领域模块 importlib 加载。
  5. skill 分发：pa skill install --dest DIR 落出 SKILL.md。

6. 发布准备与公网发布（严格区分）

发布准备（本仓库内完成，脚本即覆盖）：

python3 scripts/build-release.py            # 产出并验证 dist/ 全部产物
python3 -m twine check \
  dist/panelagent-<version>-py3-none-any.whl \
  dist/panelagent-<version>.tar.gz          # 精确指定：dist/ 里还混有 root 的 Web 目录/zip

公网发布是人工决策与人工执行的动作，本仓库脚本绝不包含：不打 git tag、不 twine upload、不发布任何渠道。需要发布时由维护者人工： bump 版本 → 复跑构建验证 → 审阅 CHANGELOG → 打 tag → twine upload dist/panelagent-<version>*（PyPI 凭据由维护者环境提供）。

7. 安装指南（面向使用方）

python3 -m pip install panelagent-0.2.0-py3-none-any.whl            # CLI 核心
python3 -m pip install "panelagent-0.2.0-py3-none-any.whl[mcp]"     # + stdio MCP
python3 -m pip install "panelagent-0.2.0-py3-none-any.whl[backend]" # + FastAPI 后端
  • 初始化实验室库：pa init --db /path/lab.db [--csv Library=inv.csv] （不传 --config-dir 即使用包内 seed）。发现命令：pa library list、 pa instrument list、pa marker list --library Mouse（均支持 --json）。
  • MCP 宿主配置：command 指向安装了本包的解释器，args 为 ["-m", "panelagent", "mcp", "--db", "/abs/path/lab.db"]（示例见 examples/mcp-client.json）。
  • 用户 skill：pa skill install --dest ~/.agents/skills（写入 <dest>/panelagent-cli/，--force 覆盖自有文件）。
  • Web：先在目标平台 cd frontend && npm run build:bundle 得到 dist/panelagent-web/，再 pa web --web-dir DIR。同机需 [backend,mcp] extras；数据库缺失时 pa web 会自动初始化新库 （PANELAGENT_DB/--db 指定路径，可用 pa init 预先导入库存）。

8. v0.2.0 整合验收（2026-09-06）

  • Python 全量在 2026-09-07 提交前复核为 314 passed；后端/内核 Ruff、前端 TypeScript、ESLint、OpenAPI 漂移检查通过。
  • 浏览器 36 项通过，覆盖工作台、API 边界、恢复、库存导入、管理员质量维护、设置和历史。
  • 在源码目录之外的全新虚拟环境安装 wheel，运行搬迁的 Next standalone：库存上传、质量修改立即被真实 MCP 读取、生成候选、保存共享历史和 390px 页面布局通过。
  • 同一安装环境完成 pa serve 独立启动；真实 MCP + 本地模拟模型验证条件绑定、错误与取消恢复。模拟模型不产生外部模型费用，此结果不代表对每家模型服务的兼容性保证。
  • 发行物准备在本地 dist/（Git 忽略），尚未打发行 tag 或上传公开分发平台；源码提交不包含这些构建产物。

9. CLI 跨机器测试包

运行 python3 scripts/build-cli-installer.py，产出 dist/panelagent-cli-0.2.0-install.zip。包内包含本地 wheel、跨平台 Python 安装脚本、自检脚本、使用指南和校验文件；首次安装依赖仍需联网。 详见 CLI 安装测试指南。