技术写作规范与构建期静态检查：受控标签、SVG 架构图与敏感信息扫描 | 青柠小站

随着博客文章数量增加，单靠人工检查很容易遗漏草稿标记、写重近义标签、改坏历史章节锚点，或者不小心将带有真实 IP 和密钥的配置片段提交到公开仓库。

把这些检查规则写成可执行的 Node.js 脚本并接入构建流程，能在发版前自动拦截大部分常见疏漏。本文记录文稿编写约定、标签词表约束、SVG 架构图制作规范以及构建期静态检查脚本的实现。

技术文稿结构与命令书写约定

为了让运维笔记和项目记录在几个月后自己重看或他人参考时依然容易复现，文稿统一遵循四条书写约定：

1. 先交代适用环境与问题背景： 开篇简要说明文章解决的具体问题、适用的操作系统或软件版本，以及配置完成后的预期结果。
2. 配合矢量图与对比表说明链路： 涉及多组件协作或网络流向时，先用一张 SVG 图和参数表把请求路径讲清楚（例如 try_files 的查找顺序，或 logrotate 切分日志后发送 USR1 信号的原因）。
3. 命令标注执行位置与占位符： 代码块注明执行位置（如 # 在本地电脑执行 或 # 在服务器执行），关键参数附上注释，并将真实 IP、用户名和端口统一替换为 <服务器地址>、<管理用户名>、<新SSH端口> 等占位符。
4. 文末附带验证命令与排错表： 每篇配置笔记末尾列出核验命令、预期正常输出和常见报错处理方式，方便操作后逐项核对。

构建前后的四项自动化检查流程

每次执行 git commit 或运行 npm run check 时，仓库会依次执行以下四项静态检查：

从 Git 暂存区敏感信息拦截、受控标签词表校验、全站死链与草稿隔离检查，到章节锚点与 SVG 插图哈希核验的自动化检查链路。

暂存区敏感信息与危险路径拦截（Pre-commit Secret Scan）

在整理线上故障笔记时，最需要注意的安全隐患是把未脱敏的配置文件、SSH 私钥或云厂商 API Token 提交进 Git 历史。一旦推送到公开仓库，即使后续提交 git rm，凭据依然会留在历史 commit 对象中。

为此，在 .githooks/pre-commit 与站点检查脚本中设置了「路径黑名单 + 内容特征码」两层扫描：

1. 危险路径与后缀直接拦截：凡是暂存区或公开目录中出现 .env*、private/、resume/、.ssh/、*.pem、*.key、*.p12、*.bak 或符号链接（Symlink），检查脚本直接报错退出。
2. 凭据特征正则匹配：扫描待提交文本是否包含私钥头部（-----BEGIN ... PRIVATE KEY-----）、GitHub Token（ghp_ / github_pat_）、API 密钥（sk-）或 AWS AKIA 标识。
3. 正文脱敏占位符写法：

# 避免在文章或注释中写入真实公网 IP、个人邮箱或线上端口
# ssh root@198.51.100.42 -p 54321

# 统一使用尖括号占位符
ssh -i <私钥文件路径> -p <新SSH端口> <管理用户名>@<服务器地址>

受控标签词表（Controlled Tag Vocabulary）

不少博客在使用一段时间后，标签页会同时出现 Docker、docker、容器、Docker Compose 等多个近义标签，导致同类文章被分散在不同页面，知识图谱中也会产生大量孤立节点。

解决办法是在 docs/tag-vocabulary.json 中维护一份受控标签词表：

{
  "version": 1,
  "max_per_post": 4,
  "tags": {
    "Linux": "Linux 系统管理、文件系统与命令行",
    "SSH": "OpenSSH 登录认证、密钥与端口加固",
    "服务器安全": "账号隔离、防火墙与主机安全基线",
    "Docker": "Docker 容器引擎、镜像构建与 Compose 编排",
    "Nginx": "Nginx 网关配置、反向代理与静态托管",
    "部署": "静态构建产物交付、发布流水线与回滚",
    "CSS": "现代 CSS 样式、设计令牌与视觉层级",
    "响应式布局": "多端网格断点与长文阅读排版",
    "可访问性": "WCAG 对比度、键盘导航与系统无障碍偏好",
    "JavaScript": "前端按需交互、异步控制与 Canvas 图形",
    "开源项目": "经过实测的优质开源工具与架构拆解",
    "AI": "AI 模型应用、工作流与工程化实践",
    "Agent": "AI Agent 技能体系、MCP 与自动化插件",
    "视频": "程序化视频渲染、剪辑与音画工作流",
    "效率工具": "提升研发与知识管理效率的桌面及自托管软件",
    "安全": "网络安全审计、红蓝对抗与隐私保护"
  }
}

词表检查脚本执行三条规则：

• 单篇文章最多绑定 4 个标签（max_per_post: 4），只保留最相关的技术维度；
• 分类与标签职责分开（Linux 与系统安全、网络与容器架构、前端与建站工程 等属于分类 categories，不混入 tags）；
• 未登记在词表中的标签直接报错，避免拼写不一致产生孤立标签。

SVG 矢量架构图规范与哈希校验

文章中的架构图、网络握手图和状态流转图优先使用 SVG（可缩放矢量图形）制作：

1. 文件体积小且缩放清晰：一张 1200×600 的 SVG 原理图文件体积通常在 5 KB ～ 9 KB 左右，在高分屏或手机端放大查看时文字与线条依然清晰。
2. 便于纳入 Git 版本控制：SVG 本质上是 XML 文本，可直接查看 diff，并在 docs/article-diagrams.json 中记录文件字节数与 SHA-256 哈希，防止图片文件意外损坏。
3. HTML 嵌入结构：

<figure class="article-diagram">
  <a href="/images/articles/content-quality-gates.svg">
    <img src="/images/articles/content-quality-gates.svg" alt="技术写作与发布前自动化静态检查流程图" width="1200" height="580" loading="lazy" decoding="async">
  </a>
  <figcaption>图注说明：简要概括图中各模块的输入、处理边界与输出关系。</figcaption>
</figure>

全站内链、SEO 元信息与固定锚点回归检查

在 astro build 生成 public/ 目录后，tools/check-site.js 与 tools/check-editorial.js 会对生成产物做只读扫描：

检查模块	校验范围	报错条件
草稿隔离检查	遍历 public/posts/*/index.html、atom.xml、sitemap.xml、search.json	任何 draft: true 文章的标题或 URL 出现在公开产物中即报错
全站死链扫描	解析所有 HTML 中的本地 href 与 src 属性	指向不存在的本地页面路径或缺失的静态图片即报错
SEO 与订阅源校验	校验 <title>、canonical、og:url 及 Atom RFC 3339 时间戳	缺失规范链接、重复标题或时间戳格式不合法即报错
章节锚点与配图哈希	核对 docs/article-anchor-contract.json 与 article-diagrams.json	同页出现重复 id、已登记章节锚点缺失或 SVG 配图哈希不符即报错