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 全局）

包自带 auto-pwa 启动器（双态 delegating launcher，模式同 dsh-tui）：

# 1. 全局安装 dsh CLI + 本插件
npm install -g @deepseek-ai/dsh auto-pwa

# 2. 首次运行自动执行 dsh plugin --profile web add auto-pwa 并启动 Web GUI；
#    之后每次运行 = dsh --profile web（委托 profile 内副本，版本随 --upgrade 前进）
auto-pwa

# 升级 / headless / 自定义 profile：
auto-pwa --upgrade
auto-pwa -p headless "完成此文件夹分波"     # 或 export DSH_PWA_PROFILE=headless

等价的手动形式（无需启动器）：pnpm dsh plugin --profile web add auto-pwa——包 manifest 声明 dsh.bundle.patch（patch/auto-pwa.bundle.yml），dsh plugin add 会自动把它 reconcile 进 profile 的 dsh.profile.bundles 层栈，之后 pnpm dsh web 直接生效，无需 --patch。

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 重复注册）：

工具

迭代闭环

create_goal（持久化 + 收敛判据）
   └─> Decide：AI 决定加/删/float/trans/plot/baseline
   └─> run_fit（强制 config gate + 你选的 target（cpu/gpu/slurm/runScript）+ provenance）
   └─> evaluate / diagnose / note
   └─> loop_next（评估 + 收敛判定；需要人工收尾用 forceConverge）
   └─> 未收敛 → 下一轮；收敛 → FINAL-REPORT.md + update_goal complete

出处（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 可刷新

PDGID 驱动的粒子身份与对称性（Particles.<name>.pdgid）

config 的 Particles 以分析名为键，而同一末态的多份同种粒子必须取不同名字（pi01/pi02/pi03 都是 π⁰）。这曾让对称性判定退化成"名字启发式"：门禁只在两个 daughter 同名时才提示未声明 Constraints.identical，于是 pi01/pi02、KS1/KS2 这类静默漏判——引擎不做 Bose/Fermi 对称化，波表里还会放进 π⁰π⁰ 的奇 L 波。

现在给粒子写上 PDGID（有符号 Monte-Carlo 编号，即社区说的 PDGID）即可由数据判决：

Particles:
  pi01: {J: 0, P: -1, mass: 0.1350, pdgid: 111}
  pi02: {J: 0, P: -1, mass: 0.1350, pdgid: 111}
  Kp:   {J: 0, P: -1, mass: 0.4937, pdgid: 321}
  Km:   {J: 0, P: -1, mass: 0.4937, pdgid: -321}
Constraints:
  identical:
    - [pi01, pi02]     # 校验会提示这一条缺失（identical-missing）

• 全同：同 PDGID ⇒ 同种粒子（Bose/Fermi 选择定则）。引擎仍只认 Constraints.identical（按名分组），所以校验会报 identical-missing 提示补声明；auto_pwa_jpc_check 用 identicalDerived（物理事实）标出"同 PDGID 但未声明"。
• 正反粒子对：pdgid 变号（或 antiparticle）⇒ C=(−1)^{L+S}；CONJUGATE_PAIRS 名字表降级为无 pdgid 时的回退。
• 自共轭 / C 本征态：selfConjugate（PDG cc_type == 'S'）+ 确定的 PDG C 值。不允许只看 C 值——PDG 表给带电态留了假 C（rho(770)+ → '-'），所以 selfConjugate 是门，c 只取值。
• C 三态标签（auto_pwa_jpc_check）：c-enforced（末态母子均为 C 本征态 → C(R) 被钉死，C 违例的波进 cBlocked）/ c-not-applicable（某端无 C，明确不施加）/ c-unknown（缺运动学）。C 不是引擎输入，这条门禁是唯一拦 C 违例的地方。
• 校验警告（validateConfig(cfg, db)，全部是 warning，不 brick config）：pdgid-unknown、pdgid-j-mismatch、pdgid-p-mismatch、pdgid-c-not-eigenstate、identical-missing、identical-pdgid-mismatch。无 pdgid 的旧 config 行为完全不变。
• 数据来源：data/pdg.json 的 particles 表（mcid → name/ccType/selfConjugate/charge/J/P/C/G/I/conjugate），由 scripts/fetch_pdg.py 从官方 pdg sqlite 生成（599 个介子/重子/轻子/γ 条目）；pdgid 是插件扩展，ctpwa 的 parseParticles 只读 J/P/mass/tex/polarization，会忽略这个键，引擎无感知。

从 0 起草 config（auto_pwa_init_config）

全新分析不再需要手写 config.yml。流程是 对话采集 → 物理研究 → 结构化提案 → 门禁渲染 → 人工复核 → 开跑：

用户对话（ask_user_question）
  └─ 反应道/母粒子/末态；数据与 MC（路径/格式/树名/branch 顺序）；是否含本底；maxL 约定
物理研究（不需要 config）
  ├─ auto_pwa_decay_check：A→R+B 允许的 J^P + 阈值 + 阈值下 PDG 候选
  └─ auto_pwa_lookup：确认候选在 PDG 上（J^P/质量/宽度/衰变模式）
auto_pwa_init_config  →  <dir>/init_config.yml（errors=0 才写；preview 只构建）
人工复核闸门（reviewSummary → 用户确认）
auto_pwa_iter_start(baseConfigPath=<dir>/init_config.yml) → iter-000 → 开跑

• 输入是结构化 spec，不是 YAML：particles（只写 pdgid 即可，J/P/质量自动取自 PDG 表）/ chains（steps + intermediates 的 [J,P] 组）/ resonances（每个都过 auto_pwa_validate_add 同源门禁）/ constraints / data / plot。
• Plot 自动生成：spec 不写 plot 时，按每个中间态的衰变步自动生成 1D 质量谱 M([d1,d2])（范围 = [m(d1)+m(d2), m(母)−m(旁观者)]）+ 1D 衰变角 CosAngle([d1],[d1,d2])。两者都是 1D，因为 auto_pwa_evaluate 从质量谱算 pull/chi2（收敛判据）、从角分布算勒让德矩（缺哪个 J 的信号）。写 plot: [] 可显式关掉。
• Data 文件级校验：传入分析目录后逐样本检查文件是否存在（相对路径按分析目录解析），缺文件 → data-file-missing；样本格式不对 → data-sample-malformed。
• 创建 = 编辑：共振态经 applyResonanceAddition 插入，渲染经同一个 dumpConfig，因此创建与后续编辑产出的 YAML 逐字段一致（有单测对比）。
• 写前总闸：validateConfig(cfg, db) + crossReferenceErrors + 逐共振态物理门禁；errors 非空拒绝写。写入是原子写（临时文件 + rename），覆盖时自动 .bak。
• 人工复核：返回 reviewSummary（反应道、每个中间态的 [J,P] 组与共振态、粒子身份、数据样本、约束、缺项提示）+ requiresHumanReview: true。init_config.yml 仍由 pwa-guard 独占保护（只能由 auto_pwa_init_config 生成）；它复制出的 config.yml/变体 yml 可由 AI 直接编辑，但跑前必过门禁。
• 迭代衔接：auto_pwa_iter_start 会把 init_config.yml 复制成 iter-000/config.yml 并把 Data 路径绝对化（现在对 flow/block、加引号/不加引号的写法都生效）。

研究阶段的两个工具配合：auto_pwa_decay_check（A→R+B 允许的 J^P + 阈值）定粗方向；auto_pwa_jpc_check 逐中间态给出两顶点交集 J^PC + C 三态 + 按阈值过滤的 PDG 候选（每个候选带 thresholdMargin on-shell 余量、decaysTo 是否 PDG 列出该衰变、C 是否已知；超阈值的候选被排除并报 filteredAboveThreshold）。先 init_config（resonances: []，preview: true）拿骨架，再 jpc_check 定候选，最后带 resonances 定稿——不需要手写 YAML。

Data 路径绝对化已改为 YAML 感知（parseDocument 改标量后重排），块状写法（AI 生成的默认形式）不再漏改；unresolved 才告警，已绝对化的配置不会误报。

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

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

执行目标：run_fit 强制只审 config，在哪跑由 AI 决定

auto_pwa_run_fit 的强制项只有一个：先审查 config.yml（跑前门禁）。执行方式每次调用决定：

三种执行都包在同一个 DSH 后台任务里，所以跑完都会唤醒 AI、都能用 auto_pwa_fit_status。

runScript 的契约（最大自由，仍可唤醒）：

#!/bin/bash
python -u fit.py "$@"               # 本机；stdout/stderr 进 <iterDir>/fit.log
# 或： sbatch --wait job.sh "$@"    # 集群；必须 --wait，否则立刻"完成"

slurm 的 job.sh 仍然只有一份模板（scripts/slurm-job.sh，默认 V100，A100 改 ★ 三行）：

1. jobScript: "auto"（或省略）—— 插件把模板装成 <iterDir>/job.sh 并提交；iter_start 会继承到下一轮。
2. 自己写/改 <iterDir>/job.sh，auto_pwa_run_fit({ iterDir, target: "slurm" })。

job.sh 三条契约：不写 cd/写死路径（--chdir 已设 cwd，同一脚本给 _trials/ 复用）、日志写 fit.log、参数用 "$@" 透传。模板 Part 1 每个 #SBATCH 都注明作用，环境直接指向 <env>/bin|lib（计算节点上 conda activate 不可靠），前台运行（& 会让作业提前结束）。

一条线看完提交→执行→唤醒：run_fit 解析 target → 审查 config.yml → （slurm）sbatch / （cpu,gpu）本地跑 / （script）bash run.sh → DSH 后台任务等待 → 结束 → 注入 background job ctpwa-N finished → 唤醒 agent → fit_status 取结果。代码级时序见 docs/io-and-usage.md §4.5.1。

要点：

• CPU 可用了但别滥用：ctpwa 0.3.19+ 有 CPU 后端，两后端 NLL 差 1e-11（ΔNLL 筛选可信）；但慢 2060×，只适合低统计量/冒烟，登录节点是共享的。CPU 上 getFitFractions 目前不可用（ctpwa 侧仍要求 CUDA 张量）→ 没有分波份额。
• 登录节点不会被 auto 悄悄降级：有 slurm 无 GPU 时 auto 直接报错，要求 target:"cpu" 或 "slurm"；长期只跑集群就设 PWA_FIT_TARGET=slurm。
• 唤醒 = 一个 DSH 后台任务（ctpwa-N）包住一次执行；批量候选（try_candidates + slurm）合成一个 DSH 任务（每候选一个作业，共用 job.sh，--chdir 到各 trial 目录），全部结束才 settle。
• SLURM cancel 默认只 detach、不 scancel：harness 重启/会话结束不该杀掉已经跑了很久的集群作业。要真停：scancel <sbatch>（或 PWA_SLURM_SCANCEL_ON_CANCEL=1）。
• PENDING 不等于 running：fit_status 显示 [slurm] PENDING (Resources)；sacct 记账延迟也不会被当成完成（继续轮询约 5 分钟）。
• goal 不会空转：DSH 的 goal 轮次只看"agent 空闲"，不看后台作业；插件在作业运行期间 disarm goal、结束时 resume，唤醒只来自完成通知（PWA_GOAL_PARK=off 可关）。
• 重启后恢复：fit_status({ jobId, iterDir }) 读 .slurm-jobs.json + squeue/sacct；cpu/gpu/script 目标直接看 results/ 与 fit.log。
• 共享文件系统是前提（slurm）：compute 节点要能读 iterDir 并写 results/。
• /pwa-status <iterationsRoot> 列出后台任务 + 迭代日记 + 集群作业。

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

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

# 无 GPU 校验 config（DecayInfo，秒级，不构造 analysis()）：
# 日常直接用 auto_pwa_validate_config（deep: true 走的就是这条），会打印
# 权威自由参数清单/顺序/振幅数——按名字对齐续算初值时不需要 GPU。
python aifit.py --config config.yml --validate-only --json /tmp/validate.json

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

变体实验：auto_pwa_run_fit 的 config 参数会补成 --config <path>（本地与 SLURM 一致），配合 scriptArgs 即可在同一迭代目录里跑 variant_xxx.yml、切阈值区、换模型等对照，无需复制成 config.yml。

优化器内核与 ctpwa/example/fit.py 同源。 aifit.py 不再自带旧内联优化器 （"torch LBFGS + 就地 clamp + 投影梯度清零"，会在边界静默伪收敛、耦合无界增长 到 1e14、被 free_range 钉住的参数仍报伪误差）；它复用 scripts/pwa_optimizer.py —— 自 example/fit.py vendored 的优化器内核（MIT），默认走 reparam 重参数化软墙路径（耦合极坐标 amp = amp_max·sigmoid(u)、共振态 theta = lo+(hi-lo)·sigmoid(u)），随后对 最优起点做 damped-Newton polish，并在非活跃子空间上判正定/求参数误差 （被边界钉住的参数如实报 null）。--optimizer projected|lbfgs 可切到对照路径； --no-polish、--amp-max、--amp-lambda、--vmax、--lr/--tol-grad/ --tol-change/--history-size 与 FIT_* 环境变量同名同默认值。 另外 --config 现在会把路径显式交给 ctpwa.analysis(path)（旧代码依赖 cwd/config.yml，传 --config other.yml 会静默读错文件）。

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），以及 example/fit.py 同名的 FIT_*。auto_pwa_fit_status 自动优先读 fit.json （参数/分波/干涉直接出现在工具输出里）；旧的 optimization_summary.txt 解析保留为回退。

pull 分布的定义（auto_pwa_evaluate）

auto_pwa_evaluate 的残差按物理模型算：ctpwa 把信号模型 hfit 与本底模板 hbkg 分开写，因此

residual = data - (fit + bkg)          # 无 hbkg 时退化为 data - fit
pull     = residual / sqrt(fit + bkg)  # Pearson；chi2 = Σ residual²/(fit+bkg)

与 ctpwa/example/plot.py 一致（此前误用 data-fit + 1/sqrt(data)）。每个分布的 evaluate.json 记录 has_background 与 residual 字段，工具输出顶部也会标注本 次评估用的是哪一种残差。

开发

• 纯核心无环境依赖、单测覆盖（160+ 测试）：npm test。
• Python 数值回归（pull 残差定义 / reparam 往返 / vendored 优化器 + polish / build_best_json）：<ctpwa env>/bin/python tests/python/test_optimizer_and_pull.py （只需 numpy+torch，无 GPU/无 ctpwa 也可跑）。
• 插件导入 @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 后端）；运行器探测并快速失败给出明确诊断。

设计文档

• 工具真值表 — 24 个工具：层/实测频次/何时用/何时不要用→改用什么 + 7 条不变式（路由评估的 ground truth）。
• 工具表面与记忆系统：现状、业界做法与待办 — 实测数据、拆分/合并方案、记忆系统分类、评测协议 v2（MemoryAgentBench 四大能力 + 确定性聚合的实证）与反模式（T1/T3/T4 已执行，T2/T5 与记忆系统仍待做）。
• IO 与用法 — 完整输入输出、工具清单、跑前门禁与本地 git 记录约定。
• 能力评估与计划 — 能力边界与演进路线。

License

MIT — 见 LICENSE。