工作流全部迁到 WSL：新增 WORKFLOW.md，build.sh 改为 WSL 原生 #21

用户要求「全部在 wsl 完成」，原因是 Windows 上工作太多太乱，
WSL 像虚拟环境、坏了能重置、不影响系统。

## 之前为什么乱

分工是「Windows 改代码 + 两端都编」：Windows 侧一份仓库副本装满了
.aux/.log/.toc/.pdf，WSL 侧另一份，靠 scp/git pull 同步维持。
同一项目两份工作副本，漏同步就分叉。

## 实测确认的技术前提

1. **UNC 路径双向读写** —— `\\wsl$\Ubuntu-26.04\home\yongquan\...`
   Read/Write/Edit 三个工具都能直接作用于该路径，读写均落到 WSL 磁盘。
   延迟 6~63ms。⇒ 不需要「本地编辑 → scp」这套中间环节。
   ⚠️ 发行版名是 Ubuntu-26.04，不是常见的 Ubuntu 或 Ubuntu-22.04。

2. **WSL 内 TeX 可完整编译全库** —— `bash build.sh all` 13/13 通过。

3. **WSL 内 git 可推送** —— credential.helper=store 已指向含 token 的
   ~/.git-credentials，fetch 实测通过。

4. **gi.py 可迁** —— 纯标准库，无第三方依赖，复制即用。

5. **Python 依赖** —— 建 ~/.venv-latex，装 pymupdf 2.0 + fonttools 4.68.0，
   不污染系统 Python。

## 本 commit 的改动

### 新增 WORKFLOW.md
写清：为什么在 WSL、目录位置（含 UNC 路径）、日常命令、编辑方式、
PDF 不进版本库的原因、已知排版告警清单、环境重建步骤。

### build.sh 重写为 WSL 原生
原版是「Windows 通过 ssh 远程调 WSL 编译再 scp 取回」，在 WSL 内跑没意义。

新版改动：
- 去掉全部 ssh/scp，直接本地编译
- 两遍编译（目录/页码/LastPage 跨引用第二遍才稳定）
- 自动 cd 到模板目录（.sty 的 ../fonts/ 相对编译目录解析）
- 目录→主文件映射保留：幻灯片/slides、科技报告/report、
  试卷有两个主文件必须显式指定、简历不能拿 ls 第一个 .tex
- `all` 转给 verify_all.sh（那边有完整 TARGETS 清单）
- 新增 SILENT=1 输出紧凑表格，便于脚本消费
- 单目录模式找不到时列出可选目录/主文件，不用去翻源码

### WSL 侧环境（不入库，属个人配置）
- ~/.config/ouc-latex/env.sh 固定 OUC_PY / GI / WB_GITEA_CONFIG / OUC_REPO，
  提供 gi / ouccd / texbuild 别名
- ~/.bashrc 末尾 source
- ~/.local/bin/gi.py + ~/.config/ouc-latex/gitea.json（chmod 600）

## 验证

WSL 内全库编译：

    总数 13 | 通过 13 | 失败 0

逐项：劳务发放说明表 1 / 年度考核登记表 2 / 幻灯片 30(UF1) /
成绩构成说明 1 / 特殊事项说明表 1 / 科技报告 10(UF4) / 简历 3 /
试卷题型示例 6 / 参考答案 3 / 试卷归档封面 1 / 试卷归档目录 1 /
课程执行大纲 5(OF1) / 课程教学日历 2

页数与 Windows 侧历史记录逐个一致。3 处告警均为既有问题，非回归。

WSL 内工单工具：`gi whoami` → token 有效、仓库识别为 ouc_latex_template。
本工单 #21 即由 WSL 内的 gi 创建，工具链已实证可用。

## Windows 侧

备份 D:\Yongquan\backup\ouc_latex_template-win-backup-20261029.tar.gz
（49MB / 244 项 / 不含 .git）。删除前确认两端 HEAD 同为 fb7c76b、
无未推送提交、无 stash。备份保留，不删。

涉及文件：WORKFLOW.md（新增）、build.sh（重写）

WORKFLOW.md

@@ -0,0 +1,99 @@
+# WSL 工作流
+
+本仓库的所有工作都在 **WSL** 内完成。Windows 侧不保留工作副本。
+
+## 为什么
+
+- 隔离：LaTeX 编译会产生大量中间文件（`.aux` / `.log` / `.toc`），
+  不用清理 Windows 目录。
+- 可重置：环境坏了删掉重建即可，不影响 Windows 系统。
+- 一套工具链：TeX Live 2025 + Python venv + git + 工单工具，全在一个地方。
+
+## 目录位置
+
+| 用途 | 路径 |
+|---|---|
+| 仓库 | `~/code/ouc_latex_template`（WSL 内） |
+| 从 Windows 浏览 | `\\wsl$\Ubuntu-26.04\home\yongquan\code\ouc_latex_template` |
+| Python venv | `~/.venv-latex`（装了 pymupdf / fonttools） |
+| 工单工具 | `~/.local/bin/gi.py` |
+| Gitea 配置 | `~/.config/ouc-latex/gitea.json` |
+| 环境变量 | `~/.config/ouc-latex/env.sh`（已在 `.bashrc` 里 source） |
+
+⚠️ 发行版名是 **Ubuntu-26.04**。若将来重装 WSL 改名了，
+UNC 路径里的这一段要跟着换。用 `wsl -l -v` 查当前名字。
+
+## 日常命令
+
+```bash
+ouccd                          # 进仓库（别名）
+bash build.sh 试卷 试卷题型示例   # 编译单个（自动两遍，打印 error/Overfull/页数）
+bash build.sh all              # 全库编译（13 个模板）
+git status && git add -A && git commit -m "... #N"
+git push origin main
+gi context                     # 查在途工单
+```
+
+`texbuild 试卷 试卷题型示例` 是 `build.sh` 的等价别名（定义在 env.sh 里）。
+
+## 编辑文件
+
+两种方式都行：
+
+1. **在 WSL 里用 vim/nano**（推荐，路径最直接）
+2. **从 Windows 用任意编辑器打开 UNC 路径** —— VS Code、Typora、
+   PDF 阅读器都能直接读写，因为 `\\wsl$\...` 是双向的。
+   但**不要在 Windows 里跑 LaTeX 编译**，那样中间文件会落在
+   Windows 的 9p 文件系统缓存里，慢且容易出权限问题。
+
+## Windows 侧注意事项
+
+- **不要**在 Windows 目录保留第二份仓库副本。两份会分叉，
+  同步靠 scp 很容易漏。这是之前"很乱"的根源。
+- 想快速看 PDF：直接双击 UNC 路径下的 PDF，或
+  `explorer \\wsl$\Ubuntu-26.04\home\yongquan\code\ouc_latex_template`
+- Windows 上装的 TeX Live 2022 **可以留着当兼容性抽检**，
+  但不是主编译环境。真要抽检时，把源码拷到临时目录编，别在仓库里编。
+
+## PDF 不进版本库
+
+`*.pdf` 都在 git 里，但**编译产生的 PDF 不要提交**——
+同源码编两次，页面一致但内嵌 `CreationDate` 不同，git 会认为文件变了。
+提交前统一还原：
+
+```bash
+git checkout -- '*.pdf'
+```
+
+## 已知的少量排版告警（不是回归）
+
+| 模板 | 告警 | 原因 |
+|---|---|---|
+| 幻灯片 | Underfull 1 | 既有问题 |
+| 科技报告 | Underfull 4 | 1 既有 + 3 内容块长串（见 boxes.cls 注释） |
+| 课程执行大纲 | Overfull 1 | 既有问题 |
+
+## 环境重建
+
+万一 WSL 环境坏了：
+
+```bash
+# 1. 装 TeX（功能全集，跳过 11 个 -doc 包，省 800MB+）
+sudo apt-get install --no-install-recommends \
+  texlive-xetex texlive-lang-chinese texlive-latex-extra \
+  texlive-fonts-extra texlive-science texlive-pictures
+
+# 2. Python 依赖
+python3 -m venv ~/.venv-latex
+~/.venv-latex/bin/pip install pymupdf fonttools
+
+# 3. FontAwesome（Debian 的 texlive-fonts-extra 不带，需走 fontconfig）
+cp ~/code/ouc_latex_template/fonts/fontawesome/FontAwesome.otf \
+   ~/.local/share/fonts/ && fc-cache -f
+
+# 4. 仓库
+git clone https://code.yangyq.net/laoyang/ouc_latex_template.git ~/code/ouc_latex_template
+
+# 5. 验证
+cd ~/code/ouc_latex_template && bash build.sh all
+```

build.sh

@@ -1,104 +1,129 @@
 #!/usr/bin/env bash
-# 在 WSL 内编译模板，并把生成的 PDF 取回 Windows 侧
+# 在 WSL 内编译模板（WSL 原生版，无需 ssh/scp）
 #
-# 适用场景：开发环境在 WSL 里，编译也在 WSL 里做，只把 PDF 拿回 Windows 看。
+# 这套仓库的全部工作都在 WSL 内完成：编辑、编译、查看、提交、提工单。
-# 不追求跨平台通用，是给「Windows + WSL2 + ssh 连入」这套配置用的。
+# Windows 侧只通过 \\wsl$\<发行版>\... 这个 UNC 路径读取文件（只读浏览）。
 #
 # 用法：
 #   bash build.sh 特殊事项说明表                  # 编译该目录下默认主文件
-#   bash build.sh 试卷 试卷题型说明.tex         # 显式指定主文件
+#   bash build.sh 试卷 试卷题型示例                # 显式指定主文件（不带 .tex 也行）
-#   bash build.sh all                         # 全库所有主文件，逐个编译并取回
+#   bash build.sh all                            # 全库所有主文件，逐个编译
+#   bash build.sh all 2>&1 | tee /tmp/v.log      # 想留完整日志
 #
-# 可用环境变量覆盖（都有默认值）：
+# 可用环境变量：
-#   WSL_HOST   默认 yongquan@127.0.0.1
+#   TEXBIN     默认 xelatex
-#   WSL_KEY    默认 $HOME/.ssh/wsl_local
+#   SILENT     非空时只打印结论行（给批量脚本用）
-#   WSL_ROOT   WSL 内仓库路径，默认 /home/yongquan/code/ouc_latex_template
-#   WIN_ROOT   Windows 侧仓库路径，默认脚本所在目录
-#   TEXBIN     WSL 内的 latex 命令，默认 xelatex
 #
-# ⚠️ 两点务必注意
+# ⚠️ 三条务必注意
 #
-# 1) 不要让本脚本的后台运行。WSL2 会按「空闲」把整个虚拟机回收（poweroff），
+# 1) **PDF 不要提交**。同源码编两次，页面一致但内嵌 CreationDate 不同，
-#    一旦回收，正在编译的 xelatex 连同 systemd 的 PID 1 一起消失，日志也随
+#    git 会认为文件变了（全库 13 个 PDF 全变 M）。提交前：
-#    /tmp 清空。本脚本的 ssh 会话在编译期间不断开，正好起到保活作用。
+#        git checkout -- '*.pdf'
-#    若确实需要长时间无人值守编译，得先在 Windows 侧 .wslconfig 里设
+#    或者用 git status 确认只 add 了源码。
-#    vmIdleTimeout=-1 并 wsl --shutdown 一次让它生效，不能只改文件。
 #
-# 2) 取回的 PDF 不要提交。同源码编译两次，页面内容一致但内嵌 CreationDate
+# 2) **每个模板都要在它自己的目录里编**。.sty 里的 Path=../fonts/ 是相对
-#    不同，git 会认为文件变了（全库 12 个 PDF 全会变成 M）。提交前用
+#    编译时工作目录解析的，从仓库根调用会找不到字体，报一堆
-#    git checkout -- '*.pdf' 还原。
+#    "The font ... cannot be found"。本脚本已自动 cd，不用手动。
+#
+# 3) **两遍编译**。目录、页码、LastPage 跨引用要第二遍才稳定。
+#    只编一遍会看到「第 ? 页」或者目录页码错位。
 set -u
 
-WSL_HOST="${WSL_HOST:-yongquan@127.0.0.1}"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WSL_KEY="${WSL_KEY:-$HOME/.ssh/wsl_local}"
-WSL_ROOT="${WSL_ROOT:-/home/yongquan/code/ouc_latex_template}"
-WIN_ROOT="${WIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
 TEXBIN="${TEXBIN:-xelatex}"
-SSH="ssh -i $WSL_KEY -o StrictHostKeyChecking=no $WSL_HOST"
+SILENT="${SILENT:-}"
 
 die() { echo "$1" >&2; exit 2; }
 
+# 目录 → 主文件。目录名与主文件名不一致的必须在这里登记。
+# 简历/ 下有 fontawesomesymbols-*.tex 等宏包片段，不能拿 ls 第一个 .tex 当主文件。
+mainfile_of() {
+  case "$1" in
+    幻灯片)   echo "slides" ;;
+    科技报告) echo "report" ;;
+    简历)     echo "简历" ;;
+    试卷)     echo "" ;;                 # 有两个主文件，必须显式指定
+    *)        echo "$1" ;;
+  esac
+}
+
+# 编一个：$1=目录 $2=主文件名（不带 .tex）
+build_one() {
+  local dir="$1" name="$2"
+  local log="/tmp/oucbuild.$$.log"
+  local log1="/tmp/oucbuild.$$.1.log"
+
+  # 第一遍：产出 .aux/.toc，允许非致命错误（TOC 还没生成时会警告）
+  ( cd "$ROOT/$dir" && $TEXBIN -interaction=nonstopmode "$name.tex" ) > "$log1" 2>&1
+  local rc1=$?
+  # 第二遍：交叉引用稳定后的最终结果，统计以这一遍为准
+  ( cd "$ROOT/$dir" && $TEXBIN -interaction=nonstopmode "$name.tex" ) > "$log" 2>&1
+  local rc2=$?
+
+  local err over under pages
+  err=$(grep -c '^!' "$log" 2>/dev/null || :)
+  over=$(grep -c 'Overfull' "$log" 2>/dev/null || :)
+  under=$(grep -c 'Underfull' "$log" 2>/dev/null || :)
+  pages=$(grep -o 'Output written on .*' "$log" 2>/dev/null | tail -1)
+
+  if [ -z "$SILENT" ]; then
+    echo "=== $dir / $name ==="
+    echo "  error     : $err"
+    echo "  Overfull  : $over"
+    echo "  Underfull : $under"
+    echo "  ${pages:-（无输出，见 $log）}"
+  else
+    printf '%-24s err=%-2s over=%-2s under=%-2s %s\n' \
+      "$dir" "$err" "$over" "$under" "$(echo "$pages" | sed 's/Output written on .*(\([0-9]*\) page.*/\1页/')"
+  fi
+
+  if [ "$rc2" -ne 0 ]; then
+    echo "--- 错误片段（$log）---" >&2
+    grep -A6 '^!' "$log" 2>/dev/null | head -20 | sed 's/^/   /' >&2
+    # 保留失败日志，方便排查；成功时删掉
+    return "$rc2"
+  fi
+  rm -f "$log" "$log1"
+  return 0
+}
+
 [ $# -eq 0 ] && die "用法: bash build.sh <目录名|all> [主文件名]"
+
 DIR="$1"; TEX="${2:-}"
 
-# 全库：先跑批量验证，再逐个取回
+#----------------------------------------------------------------------
+# 全库模式：直接转给 verify_all.sh（那边有完整的 TARGETS 清单）
+#----------------------------------------------------------------------
 if [ "$DIR" = "all" ]; then
-  $SSH "bash '$WSL_ROOT/../verify_all.sh'"
+  exec bash "$ROOT/verify_all.sh"
-  rc=$?
-  echo
-  echo "--- 取回全部 PDF ---"
-  while IFS= read -r rel; do
-    [ -z "$rel" ] && continue
-    if scp -i "$WSL_KEY" -q "$WSL_HOST:$WSL_ROOT/$rel" "$WIN_ROOT/$rel" 2>/dev/null; then
-      echo "  $rel"
-    else
-      echo "  $rel  (取回失败)" >&2
 fi
-  done < <($SSH "cd '$WSL_ROOT' && find . -name '*.pdf' -not -path './.git/*' | sed 's|^\./||'")
+
-  exit $rc
+#----------------------------------------------------------------------
+# 单目录模式
+#----------------------------------------------------------------------
+if [ ! -d "$ROOT/$DIR" ]; then
+  echo "没有这个目录：$DIR" >&2
+  echo "可选：" >&2
+  ( cd "$ROOT" && ls -d */ 2>/dev/null | sed 's|/$||' | sed 's/^/  /' ) >&2
+  exit 2
 fi
 
-# 单目录：目录名与主文件名不一致的，在这里登记
 if [ -z "$TEX" ]; then
-  case "$DIR" in
+  TEX="$(mainfile_of "$DIR")"
-    幻灯片)   TEX="slides.tex" ;;
+  if [ -z "$TEX" ]; then
-    科技报告) TEX="report.tex" ;;
+    echo "$DIR/ 有多个主文件，请显式指定：" >&2
-    试卷)     die "试卷/ 有两个主文件，请显式指定：试卷题型示例.tex 或 参考答案与评分标准示例.tex" ;;
+    ( cd "$ROOT/$DIR" && ls *.tex 2>/dev/null | grep -v fontawesome | sed 's/\.tex$//' | sed 's/^/  /' ) >&2
-    *)        TEX="$DIR.tex" ;;
+    echo "例: bash build.sh $DIR $(cd "$ROOT/$DIR" && ls *.tex 2>/dev/null | grep -v fontawesome | head -1 | sed 's/\.tex$//')" >&2
-  esac
+    exit 2
+  fi
 fi
 
-echo "=== WSL 编译: $DIR/$TEX ==="
+# 允许用户写带 .tex 的
-# 编译输出先落到临时文件，失败时才好把 ! 开头的行捞出来给人看。
+TEX="${TEX%.tex}"
-# 用当前目录下的隐藏文件名，不用 mktemp —— mktemp 在 Windows 的 Git Bash
-# 里返回 /tmp/... 形式，与其后的 rm 组合会触发安全检查（safe-delete），
-# 属于无害噪音但会干扰输出。
-TMPLOG="./.build_out.$$"
-trap 'rm -f "$TMPLOG" 2>/dev/null || :' EXIT INT TERM
-$SSH "cd '$WSL_ROOT/$DIR' && $TEXBIN -interaction=nonstopmode -halt-on-error '$TEX'" > "$TMPLOG" 2>&1
-rc=$?
 
-LOG="${TEX%.tex}.log"
+if [ ! -f "$ROOT/$DIR/$TEX.tex" ]; then
-echo "=== 结论 ==="
+  echo "找不到 $DIR/$TEX.tex" >&2
-# 页码那一行原样输出（含 "pages." 结尾），不要用正则截断 ——
+  exit 2
-# 截了会把括号吃掉，看起来像 "1 page" 少个字符。
-$SSH "cd '$WSL_ROOT/$DIR' && \
-  printf 'error:     %s\n' \"\$(grep -c '^!' '$LOG' 2>/dev/null || :)\"; \
-  printf 'Overfull:  %s\n' \"\$(grep -c 'Overfull' '$LOG' 2>/dev/null || :)\"; \
-  printf 'Underfull: %s\n' \"\$(grep -c 'Underfull' '$LOG' 2>/dev/null || :)\"; \
-  grep 'Output written on' '$LOG' 2>/dev/null | tail -1"
-
-if [ "$rc" -ne 0 ]; then
-  echo "编译失败，日志片段：" >&2
-  grep -A6 "^!" "$TMPLOG" 2>/dev/null | head -20 | sed 's/^/   /' >&2
-  exit $rc
 fi
 
-PDF="${TEX%.tex}.pdf"
+build_one "$DIR" "$TEX"
-# 打印用户熟悉的 Windows 路径形式，而不是 Git Bash 的 /d/... 挂载路径
-WINPDF="$WIN_ROOT/$DIR/$PDF"
-if scp -i "$WSL_KEY" -q "$WSL_HOST:$WSL_ROOT/$DIR/$PDF" "$WINPDF"; then
-  echo "PDF 已取回: $(echo "$WINPDF" | sed 's|^/\([a-zA-Z]\)/|\U\1:/|')"
-else
-  echo "PDF 取回失败" >&2; exit 1
-fi