chore: modernize doc tooling workflow

.github/workflows/pr-validation.yml

@@ -27,12 +27,9 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0 
 
-      # 步骤 2: 智能文件变更检测 (可选，如果想每次都跑可以删掉这一步)
       - name: 🔍 智能文件变更检测
         id: changes
         run: |
-          # 注意：我们将 'scripts/' 目录也加入到了检测模式中
-          # 这样，如果只修改了 manage_tags.py 脚本本身，CI 也会运行
           changed_files=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...HEAD)
           build_patterns=("^docs/" "^mkdocs\.yml$" "^tools/" "^\.github/workflows/pr-validation\.yml$")
           echo "检查变更的文件列表:"
@@ -73,13 +70,12 @@ jobs:
 
       - name: Install dependencies
         if: steps.changes.outputs.should-build == 'true'
-        # 假设你的依赖文件是 requirements.txt
         run: uv sync
         # 步骤 4.5: 标签规范性检查
       - name: 🏷️ 标签规范性检查
         if: steps.changes.outputs.should-build == 'true'
         # 并且我们使用 'check' 模式，它在发现问题时会以非零状态码退出，从而使工作流失败。
-        run: uv run tools/manage_tags.py check
+        run: uv run mtag check
 
       # 步骤 5: 核心验证步骤 - 严格模式构建
       # 只有在上面的标签检查通过后，这一步才会执行。

CLAUDE.md

@@ -0,0 +1,134 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概览
+- 这是一个基于 **MkDocs + Material for MkDocs** 的文档站点仓库，站点内容是“寻路之南”。
+- Python 运行时要求是 **3.12+**，依赖通过 **uv** 管理。
+- 仓库的核心不是传统应用代码，而是：
+  - `docs/`：站点内容、静态资源、自定义样式与脚本
+  - `mkdocs.yml`：站点导航、主题、插件、额外资源的中心配置
+  - `tools/`：为内容仓库服务的自动化脚本（标签管理、完成度分析、原始数据库生成）
+
+## 常用命令
+
+### 安装依赖
+```bash
+uv sync
+```
+
+### 本地开发预览
+```bash
+uv run mkdocs serve
+```
+启动后访问命令行输出的本地地址（通常是 `http://127.0.0.1:8000`）。
+
+### 严格模式构建（最接近 CI 的本地验证）
+```bash
+uv run mkdocs build --clean --strict --verbose
+```
+`--strict` 很重要：构建警告会直接导致失败。
+
+### 标签系统检查
+```bash
+uv run mtag check
+```
+
+### 标签系统交互式同步
+```bash
+uv run mtag sync
+```
+该命令会扫描 `docs/` 下的 Markdown 文件，检查 frontmatter 中的标签，并在需要时更新标签词典与标签索引页。
+
+### 内容完成度报告
+```bash
+uv run cana
+```
+可选静默模式：
+```bash
+uv run cana --quiet
+```
+
+### Docker 本地预览
+```bash
+docker compose up --build
+```
+
+### 启用 git-committers 插件进行本地构建/预览
+默认本地关闭。只有在需要预览贡献者信息时才启用：
+```bash
+export ENABLE_COMMITTERS=true
+export GITHUB_TOKEN=your_token
+uv run mkdocs serve
+```
+
+### 关于“测试”
+- 当前仓库**没有独立的单元测试目录或 pytest 测试套件**。
+- 最重要的验证方式是：
+  - `uv run mkdocs build --clean --strict --verbose`
+  - `uv run mtag check`
+- 因此也不存在“运行单个测试文件”的标准命令；如果需要做最小范围验证，通常是修改后直接用 `mkdocs serve` 本地预览，或跑标签检查脚本。
+
+## 高层架构
+
+### 1. 内容站点层
+- `docs/` 是站点的主要内容源。
+- Markdown 页面通常带有 YAML frontmatter，尤其是 `tags:` 字段。
+- 站点内容按主题组织在 `docs/` 下的多个内容分区中，例如通识课程、技能模块、昌大专属内容、社区与共建等。
+- `docs/css/`、`docs/javascripts/`、`docs/assets/` 存放前端资源；这些资源由 `mkdocs.yml` 挂接到站点中。
+
+### 2. 配置中心
+- `mkdocs.yml` 是整个站点的**单一配置中心**，负责：
+  - 导航树 `nav`
+  - Material 主题与功能开关
+  - 插件配置（尤其是 `search`、`tags`、`git-committers`）
+  - `extra_css` / `extra_javascript`
+- 任何新增页面如果要出现在站点导航中，通常都需要同步修改 `mkdocs.yml`。
+
+### 3. 自动化脚本层 (`tools/`)
+- `tools/manage_tags.py`
+  - 扫描 `docs/**/*.md`
+  - 校验 frontmatter 中的标签格式、大小写与词典合法性
+  - `sync` 模式下可更新 `tag_dictionary.yml`，并重新生成生成文件 `docs/tags.md`
+- `tools/completion_analyzer.py`
+  - 读取 `mkdocs.yml` 的 `nav`
+  - 统计页面内容量与完成度
+  - 输出 CSV 和 Markdown 报告
+  - Markdown 生成文件为 `docs/COMPLETION_REPORT.md`
+  - 输出路径和阈值在 `pyproject.toml` 的 `[tool.completion-analyzer]` 中配置
+- `tools/weaver_build_raw_db.py`
+  - 扫描文档与 frontmatter
+  - 提取标题、标签、摘要、标题层级等元数据
+  - 生成文件 `tools/data/raw_database.json`
+  - 会遵守 `.weaverignore`
+
+### 4. CI / 部署层
+- `.github/workflows/pr-validation.yml`
+  - 针对发往 `main` 的 PR 运行
+  - 先做文件变更检测
+  - 然后执行 `uv sync`
+  - 运行 `uv run mtag check`
+  - 最后运行 `uv run mkdocs build --clean --strict --verbose`
+- `.github/workflows/deploy-docs.yml`
+  - 在 `main` 分支 push 时部署
+  - 也支持 `workflow_dispatch`
+  - 使用 GitHub Pages 发布 `site/`
+  - 部署时会启用 `git-committers` 插件（通过环境变量）
+
+## 重要约定
+- **不要手动维护 `tag_dictionary.yml`。** 标签规范文档明确要求通过 `uv run mtag sync` 进行管理。
+- **`docs/tags.md` 是生成文件。** 如果标签体系变更，优先通过标签脚本重建，而不是手工编辑。
+- **`docs/COMPLETION_REPORT.md` 是生成文件。** 如需更新，请运行 `uv run cana`。
+- **`tools/data/raw_database.json` 是生成文件。** 如需更新，请运行对应构建脚本，而不是手工编辑。
+- 标签遵循 `Prefix-Value` 格式，前缀来自五个固定维度：`Topic`、`Type`、`Level`、`Action`、`Context`。
+- 本仓库的很多“结构性信息”并不分散在目录命名里，而是集中在 `mkdocs.yml` 的 `nav` 中；理解内容结构时优先读 `mkdocs.yml`。
+- `tools/completion_analyzer.py` 依赖 `mkdocs.yml` 的导航结构，因此改动导航时要注意是否会影响完成度报告。
+- `git-committers` 插件本地默认关闭；如果本地构建时忘了配置 `ENABLE_COMMITTERS`/`GITHUB_TOKEN`，通常不是 bug。
+- 因为 CI 使用 `mkdocs build --strict`，所以**坏链接、无效引用、部分构建警告都应视为阻塞问题**。
+
+## 修改内容时的工作方式
+- 纯内容修改：通常改 `docs/` 下对应页面，必要时更新 `mkdocs.yml` 导航。
+- 新增页面：除创建 Markdown 文件外，通常还要补充 frontmatter 标签，并把页面接入 `mkdocs.yml`。
+- 修改标签体系：优先查看 `docs/community/contributing/workflow/tag.md`，然后运行 `uv run mtag sync`。
+- 修改完成度分析逻辑：同时查看 `tools/completion_analyzer.py` 和 `pyproject.toml` 中的 `[tool.completion-analyzer]` 配置。
+- 修改部署/验证行为：查看 `.github/workflows/pr-validation.yml` 与 `.github/workflows/deploy-docs.yml`，因为它们定义了仓库的真实质量门槛与上线流程。

docs/COMPLETION_REPORT.md

@@ -1,15 +1,16 @@
 # 内容完成情况报告
-> 报告生成时间：2025-08-31 22:12:42
+> 本页为生成文件，请勿手动编辑。如需更新，请运行 `uv run cana`。
+> 报告生成时间：2026-03-10 13:58:58
 
 ## 报告上下文
-- **版本来源**: [`32994ab`](https://github.com/NCUSCC/cs4ncu/commit/32994ab49e6302f627f1ca7cece0d22f064009f7) - *Add NCU military training guide and update nav labels*
+- **版本来源**: [`7375391`](https://github.com/NCUSCC/cs4ncu/commit/7375391967ba7885acdeb361120e40c88b03d824) - *docs: add my signature to the wall (#157)*
 - **生成脚本**: `cana`
 
 ## 完成度概览
 - `[ ]` 表示待办或内容不足
 - `[x]` 表示已完成或内容充实
 
-- [x] **首页** (`index.md`) - *2857字，substantial*
+- [x] **首页** (`index.md`) - *3058字，substantial*
 
 ## 寻路通识课 (12/13)
 
@@ -36,37 +37,37 @@
 - [x] **设定探索方向** (`growth-general-course/01-the-zero-course/part3/ch5-the-output.md`) - *995字，substantial*
 - [x] **低成本实践与验证** (`growth-general-course/01-the-zero-course/part3/ch6-the-test.md`) - *1248字，substantial*
 
-## 第零点五课堂 (22/46)
+## 第零点五课堂 (29/47)
 - [x] **本部分导览** (`skills/index.md`) - *599字，substantial*
 
-### 认知与心智 (10/12)
-- [ ] **导览** (`skills/mindset/index.md`) - *11字，minimal*
+### 认知与心智 (12/12)
+- [x] **导览** (`skills/mindset/index.md`) - *735字，substantial*
 
 #### 思维定式 (3/3)
 - [x] **优绩主义** (`skills/mindset/fixed/meritocracy.md`) - *2102字，substantial*
 - [x] **名校情节** (`skills/mindset/fixed/elite-complex.md`) - *2827字，substantial*
 - [x] **做题家思维** (`skills/mindset/fixed/solver-mindset.md`) - *1931字，substantial*
 
 #### 认知偏差 (3/3)
-- [x] **幸存者偏差** (`skills/mindset/bias/survivorship-bias.md`) - *2661字，substantial*
-- [x] **确认偏差** (`skills/mindset/bias/confirmation-bias.md`) - *2480字，substantial*
-- [x] **沉没成本** (`skills/mindset/bias/sunk-cost.md`) - *2363字，substantial*
+- [x] **幸存者偏差** (`skills/mindset/bias/survivorship-bias.md`) - *2674字，substantial*
+- [x] **确认偏差** (`skills/mindset/bias/confirmation-bias.md`) - *2734字，substantial*
+- [x] **沉没成本** (`skills/mindset/bias/sunk-cost.md`) - *2377字，substantial*
 
 #### 心智模型 (2/2)
 - [x] **贝叶斯法则** (`skills/mindset/model/bayesian-thinking.md`) - *2510字，substantial*
 - [x] **合作与博弈** (`skills/mindset/model/collaboration.md`) - *2657字，substantial*
 
-#### 心理健康 (2/3)
-- [ ] **冒名顶替综合征** (`skills/mindset/mental/impostor-syndrome.md`) - *10字，minimal*
+#### 心理健康 (3/3)
+- [x] **冒名顶替综合征** (`skills/mindset/mental/impostor-syndrome.md`) - *2578字，substantial*
 - [x] **学会独处** (`skills/mindset/mental/learn-to-be-alone.md`) - *2391字，substantial*
 - [x] **焦虑与内耗** (`skills/mindset/mental/anxiety-impostor.md`) - *2862字，substantial*
 
-### 学会学习 (0/5)
+### 学会学习 (2/5)
 - [ ] **导览** (`skills/learning/index.md`) - *10字，minimal*
-- [ ] **元学习** (`skills/learning/meta/meta-learning.md`) - *6字，minimal*
+- [x] **元学习** (`skills/learning/meta/meta-learning.md`) - *3089字，substantial*
 - [ ] **信息输入** (`skills/learning/intake/information-intake.md`) - *7字，minimal*
 - [ ] **知识内化** (`skills/learning/consolidation/knowledge-consolidation.md`) - *7字，minimal*
-- [ ] **精力管理** (`skills/learning/energy/energy-management.md`) - *0字，empty*
+- [x] **精力管理** (`skills/learning/energy/energy-management.md`) - *2603字，substantial*
 
 ### 沟通与协作 (3/5)
 - [ ] **导览** (`skills/communication/index.md`) - *11字，minimal*
@@ -75,12 +76,12 @@
 - [x] **团队协作** (`skills/communication/teamwork/teamwork.md`) - *1592字，substantial*
 - [x] **人际矛盾处理** (`skills/communication/skills/dealing-conflicts.md`) - *3260字，substantial*
 
-### 工具与系统 (6/15)
+### 工具与系统 (9/16)
 - [ ] **导览** (`skills/tools/index.md`) - *11字，minimal*
 
 #### 数字素养 (3/4)
 - [x] **电脑认知** (`skills/tools/literacy/computer-basics.md`) - *2642字，substantial*
-- [x] **高效打字** (`skills/tools/literacy/typing.md`) - *1956字，substantial*
+- [x] **高效打字** (`skills/tools/literacy/typing.md`) - *2179字，substantial*
 - [ ] **网络工具** (`skills/tools/literacy/network-proxy.md`) - *0字，empty*
 - [x] **版本选择** (`skills/tools/literacy/version-control.md`) - *3944字，substantial*
 
@@ -89,12 +90,13 @@
 - [ ] **协作文档** (`skills/tools/pkm/collaboration-docs.md`) - *7字，minimal*
 - [ ] **任务管理** (`skills/tools/pkm/task-management.md`) - *7字，minimal*
 
-#### 生产力工具 (3/5)
-- [x] **Git** (`skills/tools/pro/git.md`) - *2424字，substantial*
+#### 生产力工具 (6/6)
+- [x] **Git** (`skills/tools/pro/git.md`) - *2434字，substantial*
 - [x] **Linux** (`skills/tools/pro/linux.md`) - *3568字，substantial*
-- [ ] **LaTeX** (`skills/tools/pro/latex.md`) - *0字，empty*
+- [x] **LaTeX** (`skills/tools/pro/latex.md`) - *4020字，substantial*
 - [x] **Prompt Engineering** (`skills/tools/pro/prompt-engineering.md`) - *4685字，substantial*
-- [ ] **Docker** (`skills/tools/pro/docker.md`) - *0字，empty*
+- [x] **Docker** (`skills/tools/pro/docker.md`) - *4232字，substantial*
+- [x] **Premiere Pro** (`skills/tools/pro/premiere.md`) - *11573字，substantial*
 
 #### VS Code 指南 (0/2)
 - [ ] **导览与配置** (`skills/tools/vscode/index.md`) - *0字，empty*
@@ -116,12 +118,12 @@
 - [x] **实验班解读** (`skills/growth/opportunity/innovation-classes.md`) - *3017字，substantial*
 - [ ] **职业规划** (`skills/growth/opportunity/career-planning.md`) - *7字，minimal*
 
-## 昌大专属资源库 (3/11)
-- [ ] **本部分导览** (`ncu-exclusive/index.md`) - *6字，minimal*
+## 昌大专属资源库 (4/11)
+- [ ] **本部分导览** (`ncu-exclusive/index.md`) - *73字，basic*
 
-### 学业发展 (2/6)
+### 学业发展 (3/6)
 - [ ] **培养方案全解** (`ncu-exclusive/academic-development/program-guide.md`) - *15字，minimal*
-- [ ] **学分绩点体系** (`ncu-exclusive/academic-development/credits-and-gpa.md`) - *0字，empty*
+- [x] **学分绩点体系** (`ncu-exclusive/academic-development/credits-and-gpa.md`) - *2758字，substantial*
 - [ ] **特色实验班** (`ncu-exclusive/academic-development/experimental-classes.md`) - *0字，empty*
 
 #### 转专业指南 (1/1)
@@ -141,12 +143,13 @@
 ### 校园生活 (1/3)
 - [ ] **通识课程体系** (`ncu-exclusive/campus-life/general-education-courses.md`) - *0字，empty*
 - [ ] **体育与体测** (`ncu-exclusive/campus-life/pe-and-fitness-tests.md`) - *0字，empty*
-- [x] **新生军训** (`ncu-exclusive/campus-life/military-training.md`) - *1311字，substantial*
+- [x] **新生军训** (`ncu-exclusive/campus-life/military-training.md`) - *1989字，substantial*
 
-## 社区与共建 (18/19)
+## 社区与共建 (19/20)
 - [ ] **我们的初心** (`community/our-story.md`) - *11字，minimal*
-- [x] **打卡教程** (`community/how-to-check-in.md`) - *2294字，substantial*
-- [x] **路友打卡墙** (`community/contributors.md`) - *714字，substantial*
+- [x] **打卡教程** (`community/how-to-check-in.md`) - *2338字，substantial*
+- [x] **路友打卡墙** (`community/contributors.md`) - *2965字，substantial*
+- [x] **友联与推荐** (`community/friends.md`) - *537字，substantial*
 
 ### 项目共建指南 (16/16)
 
@@ -157,10 +160,10 @@
 #### 开发环境与工作流 (6/6)
 - [x] **搭建基础环境** (`community/contributing/development-setup.md`) - *1987字，substantial*
 - [x] **分支保护策略** (`community/contributing/branch-protection.md`) - *1214字，substantial*
-- [x] **网站部署** (`community/contributing/deployment.md`) - *1849字，substantial*
-- [x] **智能 PR 验证系统** (`community/contributing/pr-workflow-guide.md`) - *3476字，substantial*
-- [x] **Tag 系统** (`community/contributing/workflow/tag.md`) - *3255字，substantial*
-- [x] **内容完成度分析** (`community/contributing/workflow/todo.md`) - *2151字，substantial*
+- [x] **网站部署** (`community/contributing/deployment.md`) - *939字，substantial*
+- [x] **PR 校验工作流** (`community/contributing/pr-workflow-guide.md`) - *1105字，substantial*
+- [x] **Tag 系统** (`community/contributing/workflow/tag.md`) - *3272字，substantial*
+- [x] **内容完成度分析** (`community/contributing/workflow/todo.md`) - *2169字，substantial*
 
 #### 开发实践指南 (4/4)
 - [x] **调整全局样式 (CSS)** (`community/contributing/styling.md`) - *3689字，substantial*
@@ -177,5 +180,5 @@
 - [x] **一份开发手记** (`community/contributing/development-log.md`) - *3868字，substantial*
 
 ## 索引 (2/2)
-- [x] **标签索引** (`tags.md`) - *1512字，substantial*
-- [x] **项目进度** (`COMPLETION_REPORT.md`) - *8266字，substantial*
+- [x] **标签索引** (`tags.md`) - *1581字，substantial*
+- [x] **项目进度** (`COMPLETION_REPORT.md`) - *8362字，substantial*