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_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.<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 输出目录

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 解析保留为回退。

开发

• 纯核心无环境依赖、单测覆盖（123 个测试）：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。