| name | lqcd-course |
| description | 当用户要求创建、扩展、编译、审查或维护格点 QCD 系列课程、千页级教学 PPT、从零基础到研究实现的讲义，或要求把梯度流核子胶子 TMD-PDF、论文/教材、SymPy 推导验证与 PyQCD 算法编成自包含课程时使用。
|
| metadata | {"openclaw":{"emoji":"🎓"}} |
lqcd-course — 格点 QCD 长课程工程
目的与边界
把物理课程当作可验证的软件与证据工程：同一份结构化内容生成分卷、全集、索引和论文图谱；每条主
公式都有稳定编号、完整推导、算法映射、边界声明和可执行 SymPy 代理。
本技能只写课程目录和用户明确要求的技能文档，不修改 MyQCD/PyQCD 源码、refer/ 原文、系统配置，
也不把 smoke/demo 结果升级为真实物理结论。文献转排与 INDEX 修复使用 refer。
执行前置
- 读取课程目录中与本次任务直接相关的内容模块、构建器和验证器；不要为背景扫描无关仓库文件。
- 内容扩展、结构调整或全量交付时，完整读取
references/course-contract.md。
- 涉及核子胶子 TMD 时，读取 PyQCD 的
pyqcd-tmd-chain 与 pyqcd-tmd-algorithm；涉及谱学、
统计、管线或文档时读取相应领域技能，保持共享轴序、单位、符号和证据状态。
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。未逐页检查时必须写“未完成视觉验收”。
