lqcd-course

name	lqcd-course
description	当用户要求创建、扩展、编译、审查或维护格点 QCD 系列课程、千页级教学 PPT、从零基础到研究实现的讲义，或要求把梯度流核子胶子 TMD-PDF、论文/教材、SymPy 推导验证与 PyQCD 算法编成自包含课程时使用。
metadata	{"openclaw":{"emoji":"🎓"}}

lqcd-course — 格点 QCD 长课程工程

目的与边界

把物理课程当作可验证的软件与证据工程：同一份结构化内容生成分卷、全集、索引和论文图谱；每条主 公式都有稳定编号、完整推导、算法映射、边界声明和可执行 SymPy 代理。

本技能只写课程目录和用户明确要求的技能文档，不修改 MyQCD/PyQCD 源码、refer/ 原文、系统配置， 也不把 smoke/demo 结果升级为真实物理结论。文献转排与 INDEX 修复使用 refer。

执行前置

1. 读取课程目录中与本次任务直接相关的内容模块、构建器和验证器；不要为背景扫描无关仓库文件。
2. 内容扩展、结构调整或全量交付时，完整读取 references/course-contract.md。
3. 涉及核子胶子 TMD 时，读取 PyQCD 的 pyqcd-tmd-chain 与 pyqcd-tmd-algorithm；涉及谱学、 统计、管线或文档时读取相应领域技能，保持共享轴序、单位、符号和证据状态。
4. refer/papers/INDEX.md 是书目信息事实源，课程内 paper_sources.json 是 P01--P50 到完整原始 PDF 的唯一映射；二者必须同时核对，原文 PDF 只读。

不可破坏的不变量

• 课程卷号、单元号和对象 ID 稳定；分卷与全集不得因合订方式重新编号。
• 每卷恰有 5 个单元；每单元包含物理图、至少 3 个定义、主公式、至少 3 步推导、至少 4 步算法、 两个边界检查、练习和完整答案。
• SYM-卷.单元 与单元一一对应；符号代数只能验证代数、有限维代理、级数或极限，不能冒充非微扰 动力学、因子化或真实数据验证。
• 梯度流只处理 UV 平滑/流方案；它不自动完成 Wilson-line 线性发散、soft subtraction 或 rapidity renormalization。只有非零横向间隔、有限 staple、真实核子三点、同几何 soft/rapidity、胶子匹配及 多尺度误差全部闭合，才称完整 TMD-PDF 结果。
• 非局域算符的 flow window 按整条路径支撑计算：除 b_T/|z|/ell/Lambda_QCD^{-1} 外，还必须把路径 及端点到源、汇和最近时间边界的最短物理距离（扣除源汇 smearing 支撑）纳入最小尺度。周期时间方向 检查绕回污染，开放边界检查边界污染；不存在 a << sqrt(8 tau) << d_Gamma 的窗口时必须降级。
• 课程研究主目标固定为自旋平均非极化 f_1^{g[-,-]}。link class、future/past 方向、核子自旋平均、 Euclidean projector 与 2E 归一化属于定义，不得留给实现者猜测；其他 TMD 通道明确标作扩展。
• z→0 在固定非零 b_T 时不是局域极限；b_T→0 到 collinear PDF 使用 small-b_T OPE。局域 SFTE 不能替代 finite-staple 依赖 z,b_T,ell,sqrt(8tau)、端点、cusp、mixing 与方案的 C_Gamma 矩阵/卷积转换核；缺核时必须停在 finite-flow prototype。
• 证据状态只允许按“接口存在 → 测试通过 → 方案闭合 → 真实数据验证”升级，并保留未通过门。
• 教学核心必须自包含；论文原页是进一步核查证据，不承担缺失定义或推导的兜底职责。
• 文本中的根号、上下标和指数必须序列化为真实 TeX 数学结构；生成片段中不得出现空根号占位或把 ^ 当作可见字符的退化公式，视觉无越界不能替代公式语义检查。
• P01--P50 每篇在六册图谱中恰好出现一次；映射记录仓库、相对路径/官方 URL、原页数与 SHA-256， 不得用缺图转排件冒充完整原文。
• SymPy 分两层：SYM-卷.单元 的 175 条结构验收，以及 myqcd/ 中面向学习者、可独立运行的教学例题； 二者都必须输出机器可读结果，且不得共享伪造的“通过”记录。

工作流程

1. 固定课程契约

写明受众、终点能力、卷/单元数量、核心页数下限、来源范围和交付物。扩展时先判断新内容位于哪条 先修依赖链，避免在终章堆放无先修的孤立专题。

2. 编写结构化内容

先给物理图像和量纲/对称性，再给定义与公式；推导逐步注明等价变换、近似和适用域。算法必须写出 输入、数组/状态、更新、停止条件、误差检查和输出，并映射到当前仓库实际接口或明确标为纸笔代理。

每卷至少一张 PGFPlots 定量图；其坐标、单位、数据/示意状态和来源必须完整。关系图优先 TikZ，避免 装饰图。真实数据缺失时只画带“示意”的解析/合成曲线。

3. 建立双层 SymPy 证据

为每个单元写一个独立记录，验证该页主推导中可符号化的核心不变量。每条记录保存假设和边界；验证 数量必须动态等于课程单元数，ID 集合必须完全一致。每条记录还需核对 lesson code、非空 checks、 assumptions、boundary 与 verified 状态；现场运行结果须与绑定脚本/版本/内容指纹的交付 JSON 一致， 0/0 或只有伪造 ID 的缓存不得通过。使用项目指定的含 SymPy 环境执行，不因系统 Python 缺包降低到 静态检查。

另在课程 myqcd/ 子目录提供可阅读、可修改、可单独运行的例题，至少覆盖群论/QFT、谱学/有限体积/ 有限温度/统计，以及梯度流/多种重整化/TMD 三组。统一断言接口与 JSON 汇总，但每例仍展示物理假设、 符号结论和失败条件；课程验收记录与教学例题记录分别保存。

4. 同源生成

从同一 VOLUMES 生成：所有分卷、核心全集、独立索引、SOURCES.md 和论文图谱。核心全集引用同一 frame 片段，不复制教学文字。论文图谱严格读取 paper_sources.json，为每篇增加课程接口页，并为每个 原页叠加稳定 Pxx-pyyy ID；构建前验证 50 个 ID、路径、哈希、原页数和六主题分区均闭合。

5. 分层验证

依次执行：Python 语法与内容结构 → 两层 SymPy 全绿 → TeX 生成 → XeLaTeX 两遍 → 日志检查 → 页数 闭合 → 96 DPI 或更高全页渲染 → 自动空白/边缘/比例筛查 → 联系表逐张人工检查。人工记录必须与当前 pages_expected 和联系表总数完全一致；PDF 或渲染结果变化后旧记录立即失效。失败时先定位一个主因 并最小修复，再做全回归；不要用缩小到不可读字号掩盖布局。

活动视觉根目录固定为 visual_audit/，其 render manifest 必须使用 lattice-qcd-course-render-audit-v2；外部人工记录与 manifest 内嵌记录都使用 lattice-qcd-course-manual-visual-review-v1。两份人工记录的 status、审计指纹、页数、联系表数和三类 缺陷计数必须逐字段相同。旧版本只允许保存在带版本或日期的归档目录，不得被验证器或 README 当作活动证据。

每份 PDF 还必须保存通过状态、两遍 XeLaTeX、结构化内容/生成器/来源/验证结果的 generation 指纹、当前 TeX/样式/片段（论文图谱另含原始 PDF）的输入指纹、PDF 哈希和日志哈希。逐页图与联系表分别保存唯一 路径、尺寸和哈希。验证器必须重算并比对这些值，禁止旧 PDF 或重复图片仅凭页数相同继续通过。 严格验收 JSON 还必须写出本次运行时间、严格模式开关、活动审计 schema 与精确指纹；旧失败快照或不同 指纹的通过快照都不得用于当前交付摘要。

6. 交付

更新 README 的学习路径、构建命令、编号和证据语言；更新 SOURCES 的 book/paper/code/skill 定位。 最终按“改动内容 → 推理依据 → 验证结果 → 后续步骤”汇报，明确未执行的 GPU/真实系综路径。

常见失败与处理

失败	处理
卷/单元/SymPy 数量不一致	比较三组 ID 集合，先修事实源，不在构建器里填假记录
核心页数不足	增加有教学价值的闭合 frame 或完整专题；不复制背景、目录或空总结页
公式过宽	按等价推导边界拆页或使用 aligned；保留符号定义与假设
论文页数不符	回到 refer 核对 INDEX 与实际 PDF；课程端拒绝构建
论文映射漂移或重复	核对 paper_sources.json 的 Pxx、SHA-256、原页数和六图谱唯一分区
Overfull/缺字/遮挡	修宽高预算并重编、全页重渲染；警告为零仍要视觉检查
人工视觉记录页数过期	保持 pending，重新生成联系表并连续检查全部页面；不得沿用旧的零缺陷计数
TMD 链缺 soft/rapidity/真实三点	降级为原型或接口状态，并列出下一道验证门
统计结果依赖单窗/单 prior	增加共享重采样、协方差、窗扫描和覆盖测试后再升级结论

收尾证据

交付前至少记录：课程卷数/单元数/核心实际页数、SymPy passed/total、50 篇论文与原页总数、每份 PDF 两遍编译状态、Overfull/Float/Missing/undefined-reference 计数、实际/渲染/检查页数，以及 git diff --check。未逐页检查时必须写“未完成视觉验收”。