auto-pwa

面向 DeepSeek Harness（DSH）的 AI 驱动**分波分析（PWA）**插件：物理门禁的 config 编辑、ctpwa 拟合执行、数值化拟合评估、goal 驱动的迭代收敛。

分两层架构：

• src/ — 纯物理核心（无 DSH 依赖）：PDG-2026 查询、J^P 可达性、两顶点 J^PC 规则（jpc.ts：逐点复刻 ctpwa Amp2BD::ComSL 波枚举、共轭对/全同粒子 C 规则）、共振态添加校验（10 条硬规则）、结构化 config.yml 编辑（含 Constraints/衰变步解析与 validateConfig）、float 策略建议、拟合结果解析、迭代日记（JSONL + HTML）、本地拟合运行器。
• plugin/ — 薄 DSH 集成：十四个 auto_pwa_* 工具包装核心，经 --patch 挂入任意 DSH profile。

快速开始

# 1. 安装依赖（yaml 运行时 + 开发工具）
npm install

# 2.（可选）链接 DeepSeek Harness 检出，做真实 API 开发
DSH_ROOT=/path/to/deepseek-harness npm run dev:setup

# 3. 测试 / 类型检查 / 构建
npm test
npm run typecheck
npm run build

方式 A：npm bundle 安装（推荐，profile 持久声明）

包 manifest 声明 dsh.bundle.patch（patch/auto-pwa.bundle.yml），可发布到 npm（公开或私有 registry）后像任何 DSH 插件一样安装：

# 1. 安装依赖 + 声明 bundle（转发 pnpm；然后手动在 profile package.json 的
#    dsh.profile.bundles 列表加一行 "auto-pwa"）
pnpm dsh plugin --profile web add auto-pwa

# 2. 之后每次启动都生效，无需 --patch：
pnpm dsh web

skill（auto-pwa-analysis）由插件启动时自动注册（ctx.skills.register），无需手动复制到 ~/.dsh/skills。

方式 B：本地 patch 挂载（开发/未发布时）

pnpm dsh web --patch /absolute/path/to/auto-pwa/patch/auto-pwa.cordis.yml
# headless:
pnpm dsh --profile headless --patch /absolute/path/to/auto-pwa/patch/auto-pwa.cordis.yml "完成此文件夹分波"

两种方式挂载相同的四个插件文件（服务 Provider + 硬门禁 + 斜杠命令；plugin/pwa-fit.ts 是服务定义库，由 pwa-fit-local 导入并注册 ctx.pwaFit，不作为插件挂载——挂载它会被 loader 当类插件实例化，导致 service "pwaFit" has been registered 重复注册）：

工具

迭代闭环

auto_pwa_loop_next（评估 + 收敛判定）
   └─> 未收敛 → auto_pwa_suggest / auto_pwa_diagnose（决策输入）
   └─> auto_pwa_try_candidates + auto_pwa_compare（并行探索，最优晋级）
   └─> auto_pwa_loop_decide iterate（验证 + 建轮 + 写 config + 提交拟合）
   └─> 拟合后台运行（RTX 级 GPU 约 8 分钟；DSH 完成通知自动送达）
   └─> 收敛 → FINAL-REPORT.md + phase done

用同会话 goal 驱动自动多轮迭代（create_goal + 自动续回合；拟合完成通知会唤醒/注入下一轮评估）。

出处（reference）机制：参数不跟 PDG 平均

真实分波分析中，某些共振态参数来自最新实验结果而非 PDG 平均值（或该态尚未被 PDG 收录）。提案带 reference 字段（DOI 或论文名）即声明出处：

• 质量/J^P 与 PDG 平均的偏离：从硬错误降为警告（mass-mismatch/jpc-mismatch 豁免；not-on-pdg 对未收录态放行）——记录 jpc-deviates-with-reference / not-on-pdg-with-reference 警告
• 物理门禁绝不豁免：运动学阈值、衰变顶点 J^P、C 守恒照常强制
• DOI 交叉核对：reference 命中 pdg.json 里该态的单实验测量时，输出 reference-measurement-check 警告（测量值 vs 提案值偏差）；未命中给 reference-not-found
• 随 config 继承：reference 写入 config.yml 的 Resonances.<name>.reference，随迭代复制，auto_pwa_config_view 可见
• 数据来源：data/pdg.json 的 measurements[] 由 scripts/fetch_pdg.py 从官方 pdg 包提取（单实验值 + stat/syst 误差 + DOI/Inspire 引用，最近 6 条/态，137/200 态已覆盖）；重跑 npm run fetch:pdg 可刷新

环境配置（可选，开箱即用）

所有机器相关路径都通过环境变量覆盖；默认值可移植——拟合驱动默认用插件自带的 scripts/aifit.py，python 走 PATH：

集群（SLURM）传输：无本地 GPU 也能跑

大多数用户没有本地 GPU，但集群登录节点有 SLURM。插件按 PWA_FIT_TRANSPORT 自动路由：

• 本机有 CUDA（作者开发机）→ 本地 python fit.py（现状不变）。
• 无 CUDA 但有 sbatch/squeue/sacct（登录节点）→ 写 fit.slurm 并 sbatch 交作业；登录节点轮询直到作业离开队列，DSH 后台任务的 done 在作业真正结束前不 resolve——所以跑完会唤醒 AI（background job ctpwa-N finished 通知注入/打开下一轮）。cancel → scancel。
• 两者都不可用 → 立即失败并给诊断。

要点：

• 唤醒 = 一个 DSH 后台任务（ctpwa-N）包住一个/一批 SLURM 作业；批量（auto_pwa_try_candidates，SLURM transport）会把这些候选合成一个 DSH 任务（one = 每候选一个 SLURM 作业并行，script = 一个脚本顺序跑），全部结束才 settle，一次唤醒，不会刷屏。
• 本机 transport 不变：作者开发机/测试仍走 ctx.pwaFit.submit 每候选一个 DSH 任务（PWA_FIT_TRANSPORT 未显式设 slurm 时不批处理）。
• 共享文件系统是前提：compute 节点要能读 iterDir（config.yml/fit.py）并写 results/；典型 NFS/Lustre 的 home/scratch 满足。
• 脚本里 #SBATCH 用前台 python -u fit.py（A100/V100 一致），并 cd 到迭代目录（aifit.py 从 cwd 读 config.yml）。
• 每次提交/结束都写 <iterations>/.slurm-jobs.json（状态记录：状态/批标记/子任务/submit 目录）。这是"AI 快速重建项目状态"的渠道之一：/pwa-status <iterationsRoot> 实时列出后台任务 + 迭代日记 + 集群作业，auto_pwa_history 读迭代日记（SUMMARY.jsonl），两者合起来即项目状态全景。
• DSH 后台任务在内存里：登录节点重启/GUI 关闭会丢失唤醒锚点（SLURM 作业仍会在集群跑完、但 DSH 不知道要唤醒）。小时级作业建议在登录节点上保持 harness 会话存活；跨重启的自动重挂 done 在确认重启后可作为后续增强。

AI 优先拟合驱动（scripts/aifit.py，默认拟合程序）

aifit.py 是面向 AI 的拟合驱动——同一 ctpwa 引擎、零引擎改动，跑相同的 LBFGS 循环并写出结构化的 results/fit.json；它是 PWA_FIT_SCRIPT 的默认值，新装插件无需任何配置即可迭代（也兼容手写 fit.py，设置 PWA_FIT_SCRIPT 或工具参数即可切换）：

# 无 GPU 校验 config（DecayInfo，秒级，不构造 analysis()）：
python aifit.py --config config.yml --validate-only --json results/fit.json

# 完整拟合（默认 10 次运行 × 10000 迭代；短拟合用于多候选并行）：
python aifit.py --config config.yml --runs 1 --max-iter 500 --json results/fit.json

fit.json 包含：每轮 NLL/迭代数/正定性、best 参数带误差与撞边界标记、参数相关性矩阵（Hessian 反演，含 Re/Im 耦合与共振态参数名，|ρ|>0.8 由 diagnose 自动标记简并）、分波贡献（getFitFractions）/分支比（config 提供 phsp_truth 时）、从 weight_best.root 读回的干涉矩阵（引擎已把 interference TMatrixD + legends 波名写进 ROOT 文件，无需 getSLAmpsTensor——每事件全波表太大易爆内存）、warnings、结构化错误码（config-error / no-gpu / fit-failed / usage-error，非零退出码）。读取器有防御性：未初始化内存条目（|M| > 1e6）会被检测并报告为 interference.available: false，绝不把垃圾当物理喂给模型。

# 从已有权重文件提取干涉矩阵（不拟合、无 GPU）：
python aifit.py --interference results/weight_best.root --json results/interference.json

环境变量默认值：PWA_AIFIT_RUNS（10）、PWA_AIFIT_MAX_ITER（10000）。auto_pwa_fit_status 自动优先读 fit.json（参数/分波/干涉直接出现在工具输出里）；旧的 optimization_summary.txt 解析保留为回退。

开发

• 纯核心无环境依赖、单测覆盖（160+ 测试）：npm test。
• 插件导入 @deepseek-ai/dsh-tools / @deepseek-ai/cordis / @deepseek-ai/dsh-jobs；测试解析 vendored stubs（vendor/dsh/），无需 DSH 检出。stub 恰好覆盖插件用到的 API 面；DSH API 变化时保持同步。
• scripts/fetch_pdg.py 从官方 PDG-2026 包重新生成 data/pdg.json（需在 ctpwa 环境 pip install pdg）。
• 拟合需要 CUDA GPU（ctpwa 无 CPU 后端）；运行器探测并快速失败给出明确诊断。

License

MIT — 见 LICENSE。