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 重复注册）：
| 插件 | 角色 |
|---|
plugin/pwa-fit-local.ts | 本地 Provider：拟合注册为 DSH 后台任务（ctpwa-N，owner 围栏）；完成自动通知代理进入下一轮 |
plugin/pwa-guard.ts | 单调 deny 门禁：直接 write/edit/bash 写 config.yml 一律拦截（必须走 auto_pwa_edit_config） |
plugin/pwa-commands.ts | /pwa-status [<iterationsRoot>] — 实时后台任务 + 迭代日记摘要 |
plugin/auto-pwa.ts | Consumer：二十一个 auto_pwa_* 工具；run_fit/fit_status 走 ctx.pwaFit；大输出 spill 进 ctx.spillStore；auto_pwa_note 记录每轮 token 消耗 |
工具
| 工具 | 用途 | 层 |
|---|
auto_pwa_lookup | 查询 PDG-2026 共振态表（名称/J^P/J^PC/质量区间/衰变末态，含不确定度与 C 宇称 + 单实验测量历史：最近 8 条，含 stat/syst 误差、DOI、入平均标记） | 决策·参考 |
auto_pwa_decay_check | A → R + B 允许的中间态 J^P（角动量+宇称守恒），阈值以下候选 | 决策·参考 |
auto_pwa_jpc_check | 两顶点 J^PC 检查：衰变顶点 J^PC 集（ComSL 一致，含全同选择定则）∩ 产生顶点 J^P 与 C 守恒，逐中间态输出 + 按 J^PC 过滤的 PDG 候选（与写入门禁同源） | 决策·参考 |
auto_pwa_config_view | config.yml 只读 JSON 视图（粒子/链+衰变步/共振态/运动学/Constraints + validateConfig + PDG 交叉引用） | 决策·参考 |
auto_pwa_suggest | 候选发现：pull>3σ 质量区 × 允许 J^PC → 按质量对齐度排序的 PDG 候选（含阈值余量） | 决策·发现 |
auto_pwa_diagnose | 拟合诊断：fit.json 事实 → 可行动假设（撞边界/份额不显著/强干涉/参数高相关简并/Hessian） | 决策·诊断 |
auto_pwa_evaluate | 数值诊断（chi2/ndf、pull 区域、分波份额、勒让德矩 M_L/M_0）+ PNG | 决策·诊断 |
auto_pwa_root_view | ROOT 直方图直读（AI 的眼睛）：list 列全部直方图 / read 取任意直方图逐 bin 数据——每个共振态的波谱 h_<chain>-<int>-<res>（大小与形状）、角分布 cosbeta_*、data/fit/bkg 对比 | 决策·视力 |
auto_pwa_wave_view | 任意分波组合分布（干涉视力）：writeResult(waves) 画选中波组合的拟合分布（与全波同归一化直接对比）；eventWeights 时才用逐事件 TTree（大文件，慎用）并输出选中波对干涉分布 | 决策·视力 |
auto_pwa_compare | 基座 vs 候选 trial 的 ΔNLL 显著性裁决 + AIC/BIC 复杂度惩罚（ΔAIC=2Δk+2ΔNLL，ΔBIC 需数据事件数），推荐晋级者 | 决策·裁决 |
auto_pwa_validate_add | "添加共振态"只读门禁（PDG 依据、JPC、阈值、衰变顶点 J^P、C 守恒、全同选择定则、重复、free 结构） | 执行·门禁 |
auto_pwa_edit_config | 强约束 config.yml 编辑：校验 → 结构化修改 → 写前总闸（全文 validateConfig + 交叉引用） → 原子写（+ .bak） | 执行 |
auto_pwa_round | 一轮迭代：评估上一轮（NLL/ΔNLL/最差 pull/收敛提示）+ 迭代，一次调用完成 | 执行 |
auto_pwa_iter_start | 创建 iterations/iter-N/（config 副本 + 脚本软链；Data 路径绝对化告警） |
迭代闭环
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：
| 环境变量 | 默认 | 说明 |
|---|
PWA_CTPWA_PYTHON | python（PATH 解析） | ctpwa 环境 python；非激活环境请显式指定绝对路径 |
PWA_LD_LIBRARY_PATH | 空（不注入，继承环境） | 导入 ctpwa 所需的 ROOT/CUDA/torch 库路径（仅非激活环境需要） |
PWA_FIT_SCRIPT | 插件自带 scripts/aifit.py | 拟合驱动来源（AI 适配：写 results/fit.json + weight_best.root） |
PWA_PLOT_SCRIPT | 空（不软链 plot.py） | 你的求解器 plot.py（需要出图时设置） |
PWA_EVAL_OUT_DIR | 空（用 <cwd>/_auto-pwa-eval） | auto_pwa_evaluate 输出目录 |
PWA_FIT_TRANSPORT | auto | auto/local/slurm：拟合在哪跑。auto = 本机 torch 看得到 CUDA → 本地；无 CUDA 但有 slurm 客户端 → 交作业（"无 GPU 但能 SLURM"规则）。 |
PWA_SLURM_TEMPLATE | a100 | a100/v100：集群模板，决定 partition/qos/account/gres 默认 |
PWA_SLURM_PARTITION / PWA_SLURM_QOS / PWA_SLURM_ACCOUNT / PWA_SLURM_GRES | 模板默认 | 逐集群覆盖（如 --partition=gpupwa --qos=pwadedicate --gres=gpu:a100:2） |
PWA_SLURM_NTASKS / PWA_SLURM_MEM_PER_CPU / PWA_SLURM_TIME | 1 / 50000 / 无 | sbatch 资源覆盖 |
PWA_SLURM_BATCH | auto | auto/one/script/off：候选试探批处理。auto = 按基座拟合实测 fit.json.timeSec 判（<120s → script 多合一脚本；否则 → one 每候选一作业，全部完成才唤醒） |
集群（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。
