chore: remove unused CI scripts, simplify jekyll-dev.sh, update docs

- Remove bin/clean_toc.sh and bin/lower_tag.sh: all source files already
  have lowercase tags/categories and no [toc] placeholders; the scripts
  served only as CI safety nets
- Remove corresponding CI step from pages-deploy.yml
- Simplify bin/jekyll-dev.sh: drop Homebrew Ruby path hack and PID file
  management, add Ruby version check and port polling
- Update summarize-article SKILL.md: allow git push instead of gh api
- Update docs/ruby-env.md: reflect Ruby 4.0 CI, add nokogiri and gem
  compatibility notes
- Clean up README.md and CLAUDE.md references to deleted scripts

Co-Authored-By: Claude <noreply@anthropic.com>

Author: puppylpg

.claude/skills/summarize-article/SKILL.md

@@ -105,20 +105,9 @@ git add <PATH>
 git commit -m "Add: <COMMIT_DESC>
 
 Co-Authored-By: Claude <noreply@anthropic.com>"
+git push
 ```
 
-```bash
-CONTENT_B64=$(base64 -i <PATH>)
-gh api -X PUT "repos/puppylpg/puppylpg.github.io/contents/<PATH>" \
-  -f message="Add: <COMMIT_DESC>" \
-  -f content="$CONTENT_B64" \
-  -f branch=master
-```
-
-（新文件不需要 `-f sha=...`；若文件已存在远端则需要加）
-
-`gh api` 产生的远端 commit 与本地 hash 不同，之后执行 `git fetch && git reset --hard origin/master` 对齐。
-
 查 CI：
 ```bash
 gh run list --workflow=pages-deploy.yml --limit 1
@@ -139,5 +128,4 @@ gh run list --workflow=pages-deploy.yml --limit 1
 - ❌ tag / category 大写
 - ❌ 文件名用中文
 - ❌ 不等用户确认直接 commit
-- ❌ 用 `git push`（禁止，只能用 `gh api`）
 - ❌ title 照搬原文标题

.github/workflows/pages-deploy.yml

@@ -52,10 +52,6 @@ jobs:
           ruby-version: 4.0
           bundler-cache: true
 
-      # 构建前预处理：把 tags/categories 转小写，清理 TOC
-      - name: puppylpg's scripts
-        run: bin/lower_tag.sh && bin/clean_toc.sh
-
       # 核心构建步骤，用 Gemfile.lock 里的 Jekyll（目前 4.4.1）生成静态文件
       # JEKYLL_ENV=production 开启 analytics、comments 等生产环境功能
       - name: Build site

CLAUDE.md

@@ -81,8 +81,7 @@ description: "一句话摘要，用于 SEO 和 feed"
 
 ## 构建坑点
 
-- `bin/lower_tag.sh` 只处理 `_posts` 和 `_tutorials` 里的 `categories:` / `tags:`。如果其他集合重度使用归档，需要扩展这个脚本。
-- `jekyll-archives` 同时生成 category 和 tag 页面；`Java` / `java` 这种大小写混用会生成重复归档页。
+- `jekyll-archives` 同时生成 category 和 tag 页面；`Java` / `java` 这种大小写混用会生成重复归档页。确保 `categories` / `tags` 始终小写。
 - `_tutorials/` 里有 Chirpy starter 模板残留的坏链接。CI 故意给 `htmlproofer` 传 `--ignore-files "/tutorials/"`；清理前不要去掉。
 - `last_modified_at` 依赖 git 历史。CI 已经设置 `fetch-depth: 0`；浅克隆可能让 hook 失效。
 - `assets/lib` submodule 只有在 `_config.yml` 启用 `assets.self_host.enabled` 时才需要，日常开发不必 `git submodule update --init`。

README.md

@@ -39,7 +39,7 @@
 │
 ├── assets/              # 静态资源（含 chirpy-static-assets 子模块）
 ├── pics/                # 头像等图片
-├── bin/                 # 构建前脚本
+├── bin/                 # 辅助脚本
 └── .github/workflows/   # CI / CD
 ```
 
@@ -79,7 +79,7 @@ tags: 标签名
 
 ### 分类与标签
 
-启用 `jekyll-archives` 生成分类、标签归档页。CI 构建前会执行 `bin/lower_tag.sh`，将 `_posts` 与 `_tutorials` 中 `categories:` / `tags:` 行的英文统一为小写，避免归档重复。源文件已统一小写，脚本在 CI 中作为安全网保留。
+启用 `jekyll-archives` 生成分类、标签归档页。源文件中 `categories` / `tags` 已统一小写，无需额外脚本处理。
 
 ## 本地开发
 
@@ -131,17 +131,16 @@ bundle install
 bundle exec jekyll serve
 ```
 
-本地开发与 CI 行为一致；`bin/clean_toc.sh` / `bin/lower_tag.sh` 仅在 CI 中作为安全网执行，日常不必手动跑。
+本地开发与 CI 行为一致。
 
 ## 构建与部署
 
 推送到 `main` 或 `master` 分支时，`.github/workflows/pages-deploy.yml` 会自动：
 
 1. 安装 Ruby 依赖（`bundle`）
-2. 执行 `bin/lower_tag.sh`、`bin/clean_toc.sh`
-3. `bundle exec jekyll build` 生成静态站点
-4. `html-proofer` 校验站内链接
-5. 部署至 GitHub Pages
+2. `bundle exec jekyll build` 生成静态站点
+3. `html-proofer` 校验站内链接
+4. 部署至 GitHub Pages
 
 本地模拟生产构建：
 
@@ -169,8 +168,6 @@ JEKYLL_ENV=production bundle exec jekyll build
 | `_layouts/custom-collection.html` | 自定义集合的按年归档列表 |
 | `_layouts/open-layout.html` | `open` 集合的卡片式列表 |
 | `bin/jekyll-dev.sh` | macOS 本地 `start` / `stop` / `restart` / `status` |
-| `bin/lower_tag.sh` | 构建前统一 `_posts`、`_tutorials` 的 tags / categories 大小写 |
-| `bin/clean_toc.sh` | 移除 `_posts`、`_tutorials` 首行 `[toc]` 占位（CI 安全网） |
 
 站点外观、评论、PWA、分页等全局选项在 `_config.yml` 中配置。主题详细用法见 [Chirpy 文档](https://github.com/cotes2020/jekyll-theme-chirpy#documentation)。
 

bin/clean_toc.sh

@@ -1,58 +1,47 @@
 #!/bin/bash
 # Local Jekyll dev server.
-# Usage: bin/jekyll-dev.sh {start|stop|restart|status}
+# Usage: bin/jekyll-dev.sh {start|stop|restart}
 
 set -euo pipefail
 
+# 切到项目根目录
 cd "$(dirname "${BASH_SOURCE[0]}")/.."
 
+# 端口可通过环境变量 JEKYLL_PORT 覆盖，默认 4000
 PORT="${JEKYLL_PORT:-4000}"
-PIDFILE="/tmp/puppylpg-jekyll.pid"
-LOGFILE="/tmp/puppylpg-jekyll.log"
-URL="http://127.0.0.1:${PORT}/"
 
-# macOS Homebrew Ruby (system Ruby 2.6 ships bundler 1.17, Gemfile.lock needs 2.x).
-for d in /opt/homebrew/opt/ruby/bin /usr/local/opt/ruby/bin; do
-  [[ -d "$d" ]] && export PATH="$d:$PATH" && break
-done
-
-is_running() {
-  [[ -f "$PIDFILE" ]] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null
-}
+# 要求 Ruby >= 3.0
+ruby_ver=$(ruby -e 'puts RUBY_VERSION' 2>/dev/null | cut -d. -f1)
+if [[ "${ruby_ver:-0}" -lt 3 ]]; then
+  echo "Error: Ruby 3.0+ required, got $(ruby -e 'puts RUBY_VERSION' 2>/dev/null || echo 'unknown')"
+  echo "Please set PATH to a newer Ruby before running this script"
+  exit 1
+fi
 
 start() {
-  if is_running; then
-    echo "already running at ${URL} (pid $(cat "$PIDFILE"))"
-    return 0
-  fi
+  # 确保依赖就绪，缺失则安装
   bundle check >/dev/null 2>&1 || bundle install
-  echo "==> starting at ${URL} (log: ${LOGFILE})"
-  nohup bundle exec jekyll serve --host 0.0.0.0 --port "$PORT" --livereload \
-    >"$LOGFILE" 2>&1 &
-  echo $! >"$PIDFILE"
-  for _ in $(seq 1 60); do
-    curl -sf -o /dev/null "$URL" && { echo "==> ready"; return 0; }
+  echo "Starting at http://127.0.0.1:${PORT}/"
+  # 后台启动，日志写 /tmp/jekyll.log
+  nohup bundle exec jekyll serve --host 0.0.0.0 --port "$PORT" --livereload >/tmp/jekyll.log 2>&1 &
+  # 轮询等待端口就绪，避免访问过早返回 404
+  echo -n "Waiting for server"
+  while ! nc -z 127.0.0.1 "$PORT" 2>/dev/null; do
+    echo -n "."
     sleep 1
   done
-  echo "did not respond in time, see $LOGFILE" >&2
-  return 1
+  echo " ready!"
 }
 
 stop() {
-  if [[ -f "$PIDFILE" ]]; then
-    kill "$(cat "$PIDFILE")" 2>/dev/null || true
-    rm -f "$PIDFILE"
-  fi
-  pkill -f "jekyll serve.*--port ${PORT}" 2>/dev/null || true
-  echo "==> stopped"
+  # 匹配所有 "jekyll serve" 进程并终止
+  pkill -f "jekyll serve" || true
+  echo "Stopped"
 }
 
 case "${1:-}" in
   start) start ;;
   stop) stop ;;
   restart) stop; start ;;
-  status)
-    if is_running; then echo "running ${URL} (pid $(cat "$PIDFILE"))"
-    else echo "stopped (port ${PORT})"; fi ;;
-  *) echo "usage: $0 {start|stop|restart|status}" >&2; exit 1 ;;
-esac
+  *) echo "usage: $0 {start|stop|restart}" >&2; exit 1 ;;
+esac

bin/jekyll-dev.sh

@@ -25,7 +25,7 @@ Gemfile       （声明依赖：jekyll-theme-chirpy 等）
 
 - **Jekyll**: 静态站点生成器，把 Markdown 转成 HTML
 - **Ruby**: Jekyll 用 Ruby 写的运行环境
-- **Bundler**: 管理 Jekyll 及其依赖 gem
+- **Bundler**: 管理 Jekyll 及其依赖 gem，版本由 `Gemfile.lock` 末尾 `BUNDLED WITH` 字段决定，`ruby/setup-ruby` action 会自动读取并安装对应版本
 - **Chirpy**: Jekyll 主题 gem，提供博客布局/样式/JS
 
 ## 启动方式
@@ -35,7 +35,7 @@ Gemfile       （声明依赖：jekyll-theme-chirpy 等）
 ```bash
 bin/jekyll-dev.sh start
 bin/jekyll-dev.sh restart
-bin/jekyll-dev.sh stop|status
+bin/jekyll-dev.sh stop
 ```
 
 ### 方式二：直接用 Bundler
@@ -76,32 +76,70 @@ Jekyll 版本、插件完全由你的 `Gemfile` 控制。
 本博客走的是模式二（`.github/workflows/pages-deploy.yml`），所以：
 
 - Jekyll 版本 = `Gemfile.lock` 里锁定的（目前是 **4.4.1**）
-- Ruby 版本 = workflow 里 `ruby-version` 指定的（目前是 **3.2.2**）
+- Ruby 版本 = workflow 里 `ruby-version` 指定的（目前是 **4.0**）
 - `pages.github.com/versions/` 那个页面对本博客**无关**
 
 ## 本地与 CI 对齐
 
+### gem 版本对齐
+
 只需要：
 
 ```bash
 bundle install   # 按 Gemfile.lock 安装，和 CI 完全一致
 ```
 
-如果想 Ruby 版本也一致（CI 用 3.2.2），可以用 rbenv：
+### Ruby 版本对齐
+
+本地 Ruby 版本不需要和 CI 完全一致，只要所有 gem 都兼容即可。CI 用的是 Ruby 4.0。
+
+如果出现 gem 不兼容的问题，用 rbenv 切换版本：
 
 ```bash
-# 安装 rbenv
+# 安装 rbenv（如果没有）
 brew install rbenv ruby-build
+
+# 写入 shell 配置
 echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
 echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
-
-# 设置国内镜像（加速下载）
-echo 'export RUBY_BUILD_MIRROR_URL=https://cache.ruby-china.com/' >> ~/.zshrc
 source ~/.zshrc
 
-# 安装和 CI 一致的版本
-rbenv install 3.2.2
-rbenv local 3.2.2  # 在项目目录生效
+# 安装指定版本（用国内镜像加速）
+export RUBY_BUILD_MIRROR_URL=https://cache.ruby-china.com/
+rbenv install 4.0.5
+rbenv local 4.0.5  # 在项目目录生效
+```
+
+### gem 源
+
+Gemfile 已配置国内镜像源（`gems.ruby-china.com`），`bundle install` 速度正常。
+
+系统级 gem 命令也建议切换：
+
+```bash
+gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
+```
+
+### nokogiri 编译问题
+
+nokogiri 有 native extension，在某些环境下编译 libxml2 可能失败。用系统自带库绕过：
+
+```bash
+bundle config set --local build.nokogiri "--use-system-libraries"
+bundle install
+```
+
+## gem 兼容性注意事项
+
+升级 Ruby 大版本时需要关注 gem 的 Ruby 版本约束，尤其是：
+
+- **有 native extension 的 gem**（nokogiri、ffi、sass-embedded 等）：包含 C 代码，需要针对 Ruby 版本重新编译，但通常不限制版本范围
+- **明确限制 Ruby 版本的 gem**：如 html-proofer 4.x 要求 `< 4.0`，升级到 Ruby 4.0 时必须同步升级到 html-proofer 5.x
+
+查看某个 gem 的 Ruby 版本要求：
+
+```bash
+gem specification --remote <gem名> -v <版本> | grep -A8 required_ruby_version
 ```
 
 ## 常见问题
@@ -110,25 +148,25 @@ rbenv local 3.2.2  # 在项目目录生效
 
 A: 运行 `bundle install` 安装依赖。
 
-### Q: 本地跑没问题，推到 GitHub 报错
+### Q: `cannot load such file -- bundler`
 
-A: 查看 Actions 日志定位问题：
+A: Ruby 版本切换后 bundler 需要重新安装：
 ```bash
-gh run list --workflow=pages-deploy.yml
-gh run view <id> --log-failed
+gem install bundler:$(grep -A1 "BUNDLED WITH" Gemfile.lock | tail -1 | tr -d ' ')
+bundle install
 ```
 
-### Q: Bundler 版本问题
+### Q: 本地跑没问题，推到 GitHub 报错
 
-A: 如果遇到 `cannot load such file -- bundler`，尝试：
+A: 查看 Actions 日志定位问题：
 ```bash
-gem install bundler
-bundle install
+gh run list --workflow=pages-deploy.yml
+gh run view <id> --log-failed
 ```
 
 ## 参考
 
 - Jekyll 文档：https://jekyllrb.com/
 - Chirpy 主题：https://github.com/cotes2020/jekyll-theme-chirpy
 - GitHub Pages 依赖版本（模式一适用）：https://pages.github.com/versions/
-- Ruby 中国镜像：https://cache.ruby-china.com/
+- Ruby 中国镜像：https://gems.ruby-china.com/