BHXiang/auto-pwa

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 [] — 实时后台任务 + 迭代日记摘要 |
| 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_--（大小与形状）、角分布 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_run_fit / auto_pwa_fit_status | 提交/查询 ctpwa 拟合（DSH 后台任务 ctpwa-N，完成自动通知；无 GPU 快速失败） | 执行 |
| auto_pwa_try_candidates | 并行候选短拟合：基座上试 2–5 个候选（_trials/ 目录，--runs 1 --max-iter 500），门禁与正式迭代一致 | 执行·探索 |
| auto_pwa_note / auto_pwa_history | 追加/读取迭代日记（SUMMARY.jsonl + 渲染 HTML；含每轮 token 成本） | 执行·审计 |
| auto_pwa_loop_next / auto_pwa_loop_status / auto_pwa_loop_decide | 循环状态机：评估→收敛判定（pull/ΔNLL/预算）→ FINAL-REPORT.md；决策落盘（iterate/rollback/converge）；状态持久化 .loop-state.json 重启可续 | 执行·自动化 |

迭代闭环

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..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 | 空（用 /_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 判（/.slurm-jobs.json*（状态记录：状态/批标记/子任务/submit 目录）。这是"AI 快速重建项目状态"的渠道之一：/pwa-status  实时列出后台任务 + 迭代日记 + 集群作业，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 后端）；运行器探测并快速失败给出明确诊断。

许可证

MIT — 见 LICENSE。