跳转至

CS4NCU 标签系统规范与管理指南

文档状态：草案，最后更新：2025-08-27

标签系统的设计与规范

为了使 CS4NCU 知识库的内容保持高度的结构化、可发现性和可维护性，我们设计了一套严格而智能的标签 (Tag) 系统。本指南旨在阐明其设计目的与核心规范。

设计原则

一个优秀的标签系统能将零散的知识点编织成一张有序的网。我们的设计目的在于：

  1. 提升内容可发现性：帮助用户（特别是新生）通过不同维度（如主题、类型、难度）快速找到他们需要的内容。
  2. 实现自动化管理：通过自动化的脚本，将标签的维护成本降至最低，让贡献者专注于内容创作。
  3. 保证知识库质量：建立一套自动化校验机制，从源头上杜绝格式错误、拼写错误和不一致的标签。
  4. 赋能未来功能：结构化的标签是未来实现“相关文章推荐”、“学习路径规划”等高级功能的技术基石。

命名规范

所有标签必须遵循 Prefix-Value 格式：

  • Prefix (前缀): 必须是我们预定义的五个维度之一（Topic, Type, Level, Action, Context），且首字母大写。
  • - (分隔符): 使用半角连字符。
  • Value (值):
    • 必须是有意义的英文单词。
    • 推荐使用帕斯卡命名法 (PascalCase)，即每个单词首字母大写，例如 CareerPlanning。
    • 简单值可以仅首字母大写，例如 Git, Linux。

示例：

  • 正确: Topic-Git, Type-Guide, Level-Beginner, Topic-CareerPlanning
  • 错误: topic-git (前缀小写), Type_Guide (错误的分隔符), Level-beginner (值首字母小写), 学习方法 (非英文)

五维标签模型

我们将所有内容从五个维度进行解构，每个维度对应一个前缀：

前缀 (Prefix) 含义 (Meaning) 示例 (Example)
Topic 关于什么？ (文章的核心主题) Topic-Git, Topic-Linux, Topic-Academics
Type 是什么？ (文章的内容类型) Type-Guide, Type-Concept, Type-Tutorial
Level 给谁看？ (内容的难度级别) Level-Beginner, Level-Intermediate, Level-Advanced
Action 能做什么？ (读者学习后能获得的行动/能力) Action-Building, Action-Learning, Action-Planning
Context 在哪用？ (内容关联的特定场景) Context-NCU, Context-Interview, Context-Competition

单一事实来源 (Single Source of Truth)

项目中所有合法的、官方认可的标签都被统一记录在根目录下的 tag_dictionary.yml 文件中。这个文件是整个标签系统的“宪法”，所有自动化校验都以此为准。任何时候都不应手动编辑此文件，应通过我们提供的管理脚本进行维护。

自动化管理脚本使用指南

为了让标签管理变得轻松，我们开发了 tools/manage_tags.py 脚本。它是一个强大的助手，能帮你完成所有检查和维护工作。

环境准备

在运行脚本前，请确保你已经使用 uv 工具安装了项目所需的所有依赖。

安装/同步所有依赖
uv sync

核心功能模式

脚本提供两种核心运行模式，以适应不同场景。

模式一：交互式同步模式 (sync)

这是项目维护者在本地管理标签时使用的主要模式。它会引导你完成所有必要的维护工作。

何时使用： - 当你添加或修改了大量文章的标签后。 - 当 CI/CD 检查出标签问题，你需要在本地进行修复时。

如何运行：

运行交互式同步
uv run tools/manage_tags.py sync

工作流程：

  1. 自动扫描：脚本会全面扫描 docs/ 目录下的所有 Markdown 文件。
  2. 错误报告：
    • 严重错误：如果发现格式错误或大小写错误的标签，脚本会立即报告并停止，强制你先手动修正这些最基本的问题。
    • 未知标签：如果发现格式正确、但未在词典中定义的“新”标签，它会进入下一步。
  3. 智能管理：
    • 拼写建议：如果某个未知标签与词典中的某个标签非常相似（例如 Type-Guied vs Type-Guide），它会智能地询问你是否写错了，并引导你进行修正。
    • 添加新标签：对于确认无误的新标签，它会询问你是否要将其添加到官方词典中。
  4. 自动更新：在你确认添加新标签后，脚本会自动更新 tag_dictionary.yml 文件，并重新生成 docs/tags.md 索引页。

模式二：自动化检查模式 (check)

这是为 CI/CD (GitHub Actions) 设计的非交互模式。它只负责检查和报告问题，通常你不需要手动执行它。

如何运行 (本地模拟)：

运行自动化检查
uv run tools/manage_tags.py check

工作流程：

  • 脚本会执行与 sync 模式完全相同的扫描和验证逻辑，但绝不会进行任何交互或修改任何文件。
  • 如果发现任何问题（格式、大小写、未知标签），它会打印出详细的错误报告，并以“失败”的退出状态码结束，从而阻止包含不规范标签的 PR 被合并。

其余说明

安全须知：为何不自动替换？

脚本在 sync 模式下，对于识别出的拼写错误，会引导你手动修改文件，而不是自动替换。这是一个安全措施，旨在防止脚本意外地、错误地修改你的文件内容，保证你对每一次修改都有最终的控制权。

  • 保持更新: 如果你修改了 tools/manage_tags.py 脚本本身，请务必在本地运行 sync 和 check 模式，确保脚本逻辑的正确性。

我们相信，通过这套规范的标签系统和强大的自动化工具，CS4NCU 知识库的质量和可用性将达到一个新的高度。感谢每一位遵循规范、严谨认真的贡献者！