pyqcu-md-tex-sync

Files (2)

• AGENTS.md
• SKILL.md

SKILL.md (first lines)

# md-tex-sync — Markdown/LaTeX/PDF 同源与全集归档

把可编辑 Markdown 作为唯一内容源，生成可编译 LaTeX 和可交付 PDF；同时把原始
源文档、附件、图表和数据清册纳入可哈希、可重建、可审阅的归档结构。

## 启用闸门

本技能是显式启用技能，默认不启用。收到候选调用时，先核对当前用户的原始请求；
只有以下任一条件成立才继续：

1. 用户点名 `pyqcu-md-tex-sync`，或明确要求使用 `~pyqcu-md-tex-sync`。
2. 用户明确要求 Markdown 与 LaTeX/PDF 同源维护、双格式同步交付、全文全集与
   全附件归档，或要求执行本技能的完整哈希与渲染验收流程。

仅提到 Markdown、LaTeX、PDF、文档转换或排版问题，不构成明确要求；
`auto/all/make/report` 等技能从任务上下文推断出的调用也不构成明确要求。
闸门未通过时立即停止本技能，改由相应通用技能处理，并说明
“未启用 pyqcu-md-tex-sync”。

## 执行前置

遵循当前目录 `AGENTS.md` 的「技能执行公共契约」。先完成只读盘点，再修改 Markdown、
生成 TeX 或编译 PDF；不得从渲染结果反推源码或覆盖原始证据。

## 核心原则

1. **Markdown 是唯一内容源**：正文、公式、算法、表格、来源和附件索引先写入
   Markdown。TeX 与 PDF 是派生件，不维护第二套人工正文。
2. **先校验正确性，再追求美观**：每个关键公式和算法先对当前源码核验变量、符号、
   更新顺序、归一化和适用条件，再处理排版。
3. **不得用 Markdown 宏包直接吞完整长文**：大型文档中的 `$...$`、`$$...$$`、
   下划线、Setext 标题和 HTML details 会被错误重解释。应由确定性转换器保护数学、
   代码和表格，再生成独立 LaTeX。
4. **原始全文与裁决正文分层**：裁决正文保证可读；原始源文件逐字快照、重复内容
   按 SHA256 去重并保留 aliases；附件与数据建立完整哈希清册。
5. **不自我引用**：Markdown 不把由其生成的 `.tex/.pdf` 纳入自身附件哈希；
   TeX 头注释记录 Markdown 源 SHA256，作为同步锚点。
6. **公式和伪代码不得降级为纯文本**：公式使用 MathJax/KaTeX 兼容语法；算法保留
   输入、初始化、循环、分支、停止条件、输出、断点和源码锚点。
7. **图必须先保证真实，再保证清晰**：优先嵌入原始 PNG/SVG/PDF，保留图题、单位、
   基线、样本数、范围和来源。超宽图使用原向量链接或拆分，不整页缩小到不可读。
8. **渲染闸门必须实测**：PDF 两遍 XeLaTeX 后要求 `Overfull=0`、`Float too large=0`、
   缺字 `=0`、TeX 错误 `=0`；全部页面可栅格化，无空白页和边缘裁切。
9. **构建必须幂等可追踪**：重复运行不得改变 Markdown 与 TeX 内容；PDF 允许编译
   时间元数据变化。每次交付记录三种文件的 SHA256、页数、文件大小和验证命令。

## 触发时机

仅在「启用闸门」通过后，匹配以下请求：

- 用户要求“md 与 tex/PDF 同步”“同源维护”“双格式交付”“编译 PDF”。
- 用户要求修复公式、表格、算法、图片或代码块在 Markdown/PDF 中的显示错误。
- 用户要求把多份文档整合成“全文全集”“全附件”“全数据”，并保留来源与冲突裁决。
- 用户要求把大型 Markdown 转成 LaTeX，且不能依赖在线 Pandoc、MathJax 或浏览器。
- 与其他技能配合：内容裁决用 `analy/pure`，源码核验用 `debug/review`，
  排版验收用 `report`，最终归档和技能索引用 `init/skill-creator/form`。

不触发场景：普通 Markdown/LaTeX/PDF 编辑、一般格式转换、仅因任务涉及文档而启用，
以及由 `auto/all/make` 等技能隐式推断的调用。

## 工作流程

### Step 1. 锁定权威源与交付范围

1. 建立范围清单：Markdown 主源、LaTeX 派生源、PDF、图片、源码附件、数据表、
   Office/PDF 资产和构建脚本。
2. 为每份文件记录：路径、日期、SHA256、大小、类型、生成/源文件关系。
3. 同一主题有多个版本时，按日期、修订链、当前源码和明确撤回声明确定权威版本。
4. 对重复版本只保留最新权威版；旧版独特证据进入历史章节或被撤回结论表。
5. 明确“不纳入本次哈希”的生成物，例如 `.aux/.log/.out`、逐页渲染缓存和
   Markdown 自己生成的 `.tex/.pdf`。

### Step 2. 建立内容正确性基线

1. 从当前源码核验公式的变量、左右乘顺序、dagger、site、parity 和归一化。
2. 每个算法拆成可验证字段：

```text
输入 → 初始化 → 循环 → 分支/更新 → 断点检测 → 停止条件
→ 输出 → 真残差/不变量 → 源码锚点
```

3. 对关键公式执行三类检查：

| 检查 | 目的 |
|---|---|
| 量纲与极限 | 自由场、零场、大质量、退化维度 |
| 对称性 | gamma5、Hermitian、adjoint、parity |
| 实现一致性 | 源码变量位置、更新顺序、默认值、dtype |

4. 公式与源码不一致时，先改正公式与说明，再生成任何一种交付格式。

### Step 3. 完善 Markdown 主源

1. 正文、裁决、附录和来源台账全部写入同一 Markdown。
2. 行内公式使用 `$...$`，展示公式使用独占行的 `$$ ... $$`；不要使用
   `\[...\]`，因为部分 Markdown 解析器会把它当作转义方括号。
3. 伪代码使用四反引号或波浪线围栏，保留缩进、循环和停止条件。
4. 表格避免在数学单元中使用裸 `|`；向量范数使用 `\|x\|` 等无冲突写法。
5. 每一段关键结论附来源路径、版本、口径、单位、误差和限制。
6. 在文件末尾设置生成区标记：

```text
<!-- BEGIN GENERATED FULL ARCHIVE -->
<!-- END GENERATED FULL ARCHIVE -->
```

### Step 4. 生成全文与全附件附录

1. `docs/**` 中所有独立 `.md/.tex` 源按 SHA256 去重。
2. 每个唯一内容只嵌入一次，其他相同路径列入 aliases。
3. 原始行尾空格和 tab 若为了可读展示而转为可见标记，必须同时保留原始 SHA256
   和路径，并在注释中明确这是“可读视图”，不是字节级副本。
4. 所有 PDF、PNG、PPTX、Office XML、脚本、日志和数据文件进入附件清册：

```text
path | bytes | extension | SHA256
```

From ZhangXin8069/PyQCU, MIT.

More from ZhangXin8069/PyQCU