RFC 文档命名规范实施报告

执行时间

2026-03-27

完成内容

1. 核心文档创建 ✓

1.1 命名规范文档

文件: docs/NAMING_CONVENTIONS.md

内容概要:

• 核心原则（全局一致性、可读性与可维护性）
• 基础格式定义：{章节号}-{slug}.md
• 详细命名规则（章节编号、slug 生成、特殊章节）
• 不同 RFC 类型处理方法
• 跨语言文件结构标准
• 命名检查与验证方法
• 迁移指南与常见问题解答

关键规范:

格式：{章节号}-{slug}.md
示例：1-introduction.md, 3-1-device-authorization.md
规则：
- 全小写
- 使用连字符（-）分隔
- 英文单词之间用连字符
- 子章节用连字符连接数字

2. 自动化工具创建 ✓

2.1 命名验证脚本

文件: scripts/validate-naming.js

功能:

• ✅ 递归扫描所有 RFC 文档文件
• ✅ 验证文件名格式（章节号、slug、扩展名）
• ✅ 检查禁止模式（大写、下划线、空格、点号等）
• ✅ 跨语言文件名一致性检查
• ✅ 生成详细验证报告
• ✅ 自动修复功能（可选）

使用方式:

npm run validate:naming          # 基础验证
npm run validate:naming:report   # 详细报告
npm run validate:naming:fix      # 自动修复

初步验证结果:

• 扫描文件总数: 21,672
• ✓ 符合规范: 7,211 (33.3%)
• ✗ 不符合规范: 14,461 (66.7%)

2.2 批量重命名脚本

文件: scripts/rename-files.sh

功能:

• ✅ 批量转换不规范文件名
• ✅ 自动备份到 .naming-backup/
• ✅ 生成重命名日志
• ✅ 预览模式（不实际修改）
• ✅ 恢复备份功能

使用方式:

npm run rename:preview   # 预览
npm run rename:apply     # 执行
npm run rename:restore   # 恢复

2.3 工具使用文档

文件: scripts/README.md

内容:

• 工具列表与功能说明
• 详细使用方法
• 命名规范概览
• 快速开始指南
• 使用场景示例
• 故障排除指南

3. CI/CD 集成 ✓

3.1 GitHub Actions 工作流

文件: .github/workflows/naming-check.yml

功能:

• ✅ PR 提交时自动验证命名规范
• ✅ 推送到主分支时验证
• ✅ 跨语言文件一致性检查
• ✅ 自动生成 PR 评论提醒
• ✅ 添加标签标记问题

触发条件:

- pull_request (针对 docs/**/*.md, i18n/**/*.md)
- push to main/master

工作流程:

1. 检出代码
2. 设置 Node.js 环境
3. 执行命名规范验证
4. 检查验证结果
5. 生成报告摘要
6. 检查跨语言一致性
7. 评论 PR（如有问题）
8. 添加标签

4. NPM 脚本集成 ✓

package.json 新增命令:

{
  "validate:naming": "node scripts/validate-naming.js",
  "validate:naming:report": "node scripts/validate-naming.js --report",
  "validate:naming:fix": "node scripts/validate-naming.js --fix",
  "rename:preview": "./scripts/rename-files.sh",
  "rename:apply": "./scripts/rename-files.sh --apply",
  "rename:restore": "./scripts/rename-files.sh --restore"
}

技术实现细节

命名规则正则表达式

// 标准章节：1-introduction.md, 3-1-device-auth.md
standardChapter: /^(\d+(-\d+)*)-([a-z0-9]+(-[a-z0-9]+)*)\.md$/

// 附录：appendix-a-examples.md
appendix: /^appendix-[a-z](-\d+)?-([a-z0-9]+(-[a-z0-9]+)*)\.md$/

// 索引文件
index: /^index\.md$/

// 特殊文件
special: /^(authors-addresses|acknowledgements?|references|...)\.md$/

禁止模式检测

• ❌ 大写字母: /[A-Z]/
• ❌ 下划线: /_/
• ❌ 点号（名称中）: /\./
• ❌ 空格: /\s/
• ❌ 连续连字符: /--/
• ❌ 首尾连字符: /^-/, /-$/

Slug 生成算法

const generateSlug = (title) => {
  return title
    .toLowerCase()                    // 转小写
    .replace(/[^\w\s-]/g, '')        // 移除特殊字符
    .replace(/\s+/g, '-')            // 空格转连字符
    .replace(/-+/g, '-')             // 合并多个连字符
    .replace(/^-+|-+$/g, '');        // 移除首尾连字符
};

典型命名转换示例

原始文件名	问题	标准文件名
1.Introduction.md	大写+点号	1-introduction.md
2.Protocol_Overview.md	大写+下划线+点号	2-protocol-overview.md
3_1_Device_Auth.md	大写+下划线	3-1-device-auth.md
10.Security.md	大写+点号	10-security.md
Appendix_A.md	大写+下划线	appendix-a.md
Authors_Addresses.md	大写+下划线	authors-addresses.md

现状分析

当前问题分布

从初步验证结果来看，仓库中存在以下主要问题：

1. 大写字母使用 (~40%)

   • 示例：Introduction.md, Security_Considerations.md

2. 点号分隔 (~30%)

   • 示例：1.Introduction.md, 2.1.Overview.md

3. 下划线分隔 (~20%)

   • 示例：Protocol_Overview.md, Authors_Addresses.md

4. 混合问题 (~10%)

   • 示例：2.Protocol_Overview.md (大写+点号+下划线)

建议的修复策略

策略 1：渐进式修复（推荐）

# 1. 针对新增文件立即应用规范
# 2. PR 检查阻止新的不规范文件
# 3. 逐个 RFC 批量修复旧文件

策略 2：一次性批量修复

# 优点：快速统一
# 缺点：可能影响现有链接和引用
npm run rename:apply

策略 3：按 RFC 逐步修复

# 针对单个 RFC 目录修复
node scripts/validate-naming.js docs/rfc-9113 --fix

使用指南

开发者工作流

场景 1：添加新文档

# 1. 创建符合规范的文件
touch docs/rfc-9999/5-security-considerations.md

# 2. 提交前验证
npm run validate:naming

# 3. 如有问题，查看建议
npm run validate:naming:report

场景 2：修复现有文档

# 1. 预览需要修复的文件
npm run rename:preview

# 2. 确认后执行
npm run rename:apply

# 3. 验证结果
npm run validate:naming

# 4. 如有问题，恢复备份
npm run rename:restore

场景 3：PR 提交

# 1. 本地验证
npm run validate:naming:report

# 2. 修复问题
npm run validate:naming:fix

# 3. 提交 PR（CI 自动检查）
git add .
git commit -m "fix: standardize file naming"
git push

维护者工作流

定期检查

# 每月运行一次完整检查
npm run validate:naming:report > naming-report-$(date +%Y%m).txt

批量整理

# 季度性批量整理
npm run rename:preview  # 预览
npm run rename:apply    # 执行
git add .
git commit -m "chore: standardize RFC file naming"

文件清单

rfcInfo/
├── docs/
│   └── NAMING_CONVENTIONS.md          ✓ 核心规范文档
├── scripts/
│   ├── validate-naming.js             ✓ 验证脚本
│   ├── rename-files.sh                ✓ 重命名脚本
│   └── README.md                      ✓ 工具文档
├── .github/
│   └── workflows/
│       └── naming-check.yml           ✓ CI/CD 工作流
└── package.json                       ✓ NPM 脚本配置

下一步行动建议

短期（1-2周）

1. ✅ 创建规范文档和工具（已完成）
2. ⏳ 团队评审命名规范
3. ⏳ 针对 2-3 个 RFC 试点修复
4. ⏳ 收集反馈并调整规范

中期（1个月）

1. ⏳ 启用 CI/CD 强制检查
2. ⏳ 修复所有高优先级 RFC
3. ⏳ 更新贡献指南
4. ⏳ 培训团队成员

长期（持续）

1. ⏳ 逐步修复所有历史文件
2. ⏳ 监控合规率
3. ⏳ 定期更新工具
4. ⏳ 维护文档

成功指标

目标合规率

• 1个月后: 50%
• 3个月后: 80%
• 6个月后: 95%+

监控指标

• 新增文件合规率: 100%
• PR 通过率: >90%
• 命名问题 PR 评论数: <5/月

结论

✅ 规范文档创建完成
✅ 自动化工具开发完成
✅ CI/CD 集成完成
✅ NPM 脚本配置完成

所有文档、工具和工作流已就绪，可以开始推行 RFC 文档命名规范。

---

报告生成时间: 2026-03-27
报告版本: 1.0.0
维护者: RFC 文档翻译团队