维护记录

完成的工作

  • .gitmodules 移除孤儿条目 [submodule "themes/paper"]（指向已不存在的 themes/paper，源自 2026-03-17 的 6d6051b Switch theme to PaperMod 迁移）；本地 .git/config 不含此条目，gitlink 也已不存在，删除安全
  • 新增 .prettierignore 屏蔽 themes/PaperMod（含 node_modules / .tools / .npm-cache / public 作为防御）；修掉 format-markdown-check 永远报 PaperMod 内 PULL_REQUEST_TEMPLATE.md / README.md 的误报
  • 精简 CLAUDE.md：从 134 行压缩为 6 行指针，统一指向 AGENTS.md，仅保留 Claude Code 特有提示（优先用 rg、对外动作需确认）
  • 清理本地残留 node_modules/（49M）与 .npm-cache/（3.4M）—— 均为 gitignored，不影响提交

遇到的问题

  • 本机 deno 不在 PATH，但 .tools/deno/bin/deno 有 2.9.5 二进制 ⚠️ - 临时 export PATH=$PWD/.tools/deno/bin:$PATH 后跑 validate-posts / test / sync-covers-dry / format-markdown-check，CI 走 denoland/setup-deno@v2 无此问题

下次建议

  • AGENTS.md 增加一段「deno 本地安装提示」：如果 deno 命令未找到，仓库根目录 .tools/deno/bin/deno 是可用回退（export PATH=$PWD/.tools/deno/bin:$PATH）

维护记录（追加：CI 工作流加固）

完成的工作

  • 评估整套工作流后落地 4 项高优先级修复 ✅
  • deploy.yml：Hugo 版本从 latest 固定为 0.161.1（与本地已知可用版本一致）；新增 deno task validate-posts 发布前门槛（放在 gen-covers 之后、构建之前）；新增 concurrency: pages + cancel-in-progress，防止旧构建后完成覆盖新部署；bot 守卫从「跳过一切 bot 触发」改为「仅跳过 bot 的 push 事件」，放行 workflow_dispatch
  • update-papermod.yml：推送前用同一固定版本 Hugo 冒烟构建，上游 breaking 改动直接失败在本工作流、不落 master；推完后 gh workflow run deploy.yml 显式触发部署（GITHUB_TOKEN 的 push 不触发任何 workflow，之前主题更新要等下一次人工 push 才上线）；新增 actions: write 权限
  • sync-covers.yml：记录同步前 HEAD，仅在实际推送了清理提交时 dispatch 部署；新增 actions: write 权限
  • 过程中发现并纠正一处自身笔误：守卫条件初版写反，会使 bot push 放行、dispatch 反被拦；已修正为 github.event_name == 'workflow_dispatch' || github.actor != 'github-actions[bot]'
  • 验证：三份 YAML 解析通过；deno task test（45 通过）、validate-posts、format-markdown-check 全绿；本地 hugo --minify（0.161.1）构建成功

遇到的问题

  • 改动仅落在工作树，未提交/推送（推送属对外可见操作，待用户确认后执行）⚠️

下次建议

  • sync-covers.yml 的 checkout 未设 fetch-depth: 0，git-commit-push 内 pull --rebase 在撞并发推送时可能因浅克隆失败（既有行为，deploy.yml 已设 0，可对齐）
  • 评估报告中「顺手可做」清单仍未动：prettier 版本统一进 deno.json、check-dead-links 结果可见化（现在 \|\| true 吞掉失败）、pre-push hook 聚合检查、git-commit-push.ts 里 git show ":${path}" 参数化、private 字段实现消费或移除校验、bot 提交刷新 ShowLastMod 显示