MySQLTuner 文档同步工作流实战：doc-sync 脚本与版本一致性审计全解析

• 数据库
• 运维

导读

本文围绕 MySQLTuner-perl 仓库中的 .agent/workflows/doc-sync.md 工作流规范，系统讲解由/doc-sync触发的文档自动同步机制：如何使用perl build/doc_sync.pl一键重建.agent/README.md目录索引，如何按评审清单完成 README、CLI 元数据、ROADMAP、POTENTIAL_ISSUES 与脚本注释的全量校验，以及如何通过版本一致性审计确保CURRENT_VERSION.txt、mysqltuner.pl、Changelog与releases/发布说明四处版本号严格对齐。读完本文，你将掌握 MySQLTuner 项目"文档即代码"的自动化维护流程，并了解其背后 Perl 脚本的实现原理与配套测试验证方法。

一、工作流定位：.agent治理体系中的文档同步环节

MySQLTuner-perl 在 .agent/README.md 中维护了一份"项目治理与 AI 智能"索引，将仓库内的治理规则（Rules）、专业技能（Skills）与运维工作流（Workflows）三类 Markdown 文档统一登记成表格。.agent/workflows/doc-sync.md正是负责维护这份索引的自动化工作流，其 Front Matter 元数据如下：

--- trigger: /doc-sync description: Synchronize .agent/README.md with current Rules, Skills, and Workflows category: Documentation ---

三个字段的含义分别为：trigger定义了 AI Agent 触发本工作流的指令/doc-sync；description一句话概括其核心职责——让.agent/README.md与当前的 Rules、Skills、Workflows 保持同步；category将其归类为文档类工作流。它与 .agent/workflows/hey-agent.md（统一管理 Rules/Skills/Workflows）和 .agent/workflows/markdown-lint.md（Markdown 内容规范检查）共同构成了文档治理的自动化闭环。

整个工作流分为四个明确步骤：

1. 执行文档同步脚本更新.agent/README.md；
2. 全量文档评审清单（README、Usage、ROADMAP、POTENTIAL_ISSUES、脚本注释）；
3. 版本一致性审计（CURRENT_VERSION、脚本头、Changelog、release 说明）；
4. 复核更新后的.agent/README.md摘要。

下文按这四个步骤逐一展开，并结合仓库源码剖析其底层实现。

二、第一步：执行perl build/doc_sync.pl重建目录索引

工作流的第一步是运行仓库根目录下构建工具集中的同步脚本：

perl build/doc_sync.pl

脚本执行成功后会在终端打印Documentation synchronized: <绝对路径>/.agent/README.md并返回退出码 0。从仓库内容看，该脚本在 v2.9.1 版本中由其他语言重写为 Perl（见 Changelog 中 "rewrite dev_sync and doc_sync in Perl for consistency" 的变更记录），以保持与主程序mysqltuner.pl一致的 Perl 技术栈。

2.1 脚本的目录定位与路径解析

build/doc_sync.pl 开头通过File::Basename、File::Spec与Cwd 'abs_path'计算出仓库根目录与.agent目录的绝对路径：

my $project_root = abs_path(File::Spec->catfile(dirname(abs_path(__FILE__)), '..')); my $agent_dir = File::Spec->catfile($project_root, '.agent'); my $readme_path = File::Spec->catfile($agent_dir, 'README.md');

这一设计使脚本不依赖当前工作目录，无论从仓库根目录还是其他子目录执行都能正确定位目标文件，这也是tests/doc_sync.t中先chdir到项目根目录再执行脚本的测试前提。

2.2 元数据解析：从 Markdown 头部提取标题与描述

脚本的核心函数parse_markdown_metadata负责从每个文档中提取两项信息：标题与描述。

my $title = basename($file_path); if ($content =~ /^#\s+(.*)/m) { $title = $1; $title =~ s/^\s+|\s+$//g; } my $description = "No description available."; if ($content =~ /description:\s*(.*)/) { $description = $1; $description =~ s/^\s+|\s+$//g; }

标题优先取文档中第一个#一级标题（如 doc-sync.md 的# Documentation Synchronization Workflow），描述则取 Front Matter 中description:字段；若文档缺失该字段，则回退为No description available.。这也解释了为什么 .agent/README.md 中每个条目的描述都恰好对应各文档 Front Matter 中的description。

2.3 目录索引生成：固定顺序与 SKILL.md 特殊处理

generate_readme函数定义了三个分类及其在索引中的固定顺序：

my %categories = ( 'rules' => 'Governance & Execution Constraints', 'skills' => 'Specialized Capabilities & Knowledge', 'workflows' => 'Automation & Operational Workflows' ); my @cat_order = ('rules', 'skills', 'workflows');

脚本按rules → skills → workflows的固定顺序遍历，保证每次生成的 README 结构可预测（注释中明确说明 "Keep a fixed iteration order for predictability"）。每个分类下输出标准的 Markdown 表格，并通过readdir读取目录内所有文件、按文件名排序后逐条登记。

值得注意的一个细节是技能目录的处理：skills/下的每一项（如cli-execution-mastery）本身是一个子目录，真正的文档是其中的SKILL.md。脚本通过-f $full_path判断文件不存在时，会尝试拼接子目录下的SKILL.md并解析其元数据，最终在表格中登记为cli-execution-mastery/并链接到对应 SKILL.md。这使得索引既能容纳普通 Markdown 文档，也能容纳"目录 + SKILL.md"结构的技能包。

最后，脚本在 README 尾部追加一行固定落款：

--- *Generated automatically by `/doc-sync`*

并直接写入.agent/README.md（使用print $fh join("\n", @output)），完整覆盖旧内容，因此该文件始终与当前目录状态严格一致——从 .agent/README.md 的末尾落款可以看到，仓库中的这份索引正是由该脚本生成的真实产物。

三、第二步：全量文档评审清单

运行同步脚本只是"机器可自动化"的部分，doc-sync 工作流还要求对项目文档做一次人工/Agent 驱动的全面评审，覆盖五个维度：

3.1 README 多语言同步

MySQLTuner 的主 README 提供了法语、意大利语、俄语等多语言版本。评审要求任何新功能的文档化都要同步覆盖翻译版本，避免各语言 README 出现信息断层。仓库中tests/doc_sync.t与tests/check_release_files.sh等测试会进一步对文档完整性做机械校验。

3.2--help输出与CLI_METADATA的一致性

mysqltuner.pl将全部命令行选项的元数据集中维护在一个哈希%CLI_METADATA中（源码注释明确标注 "Central metadata for CLI options"，并分类为 CONNECTION、PERFORMANCE、OUTPUT、CLOUD、MISC）。例如：

'host' => { type => '=s', default => undef, desc => 'Connect to a remote host to perform tests', placeholder => '<host>', cat => 'CONNECTION' },

--help的输出必须由这份元数据驱动，保证"新增选项 → 元数据更新 → 帮助文本更新"三者同步。若手改帮助文本而遗漏元数据，就会产生文档与实现不一致的问题。这一点在 documentation/specifications/cli_metadata_refactor.md 规范中有更完整的背景说明，其目标正是消除散落各处的硬编码选项描述。

3.3 ROADMAP 与 POTENTIAL_ISSUES 的维护

评审要求将 ROADMAP.md 中已完成的阶段条目（Phase 2/3 的已完成项）移入 COMPLETED 区，确保路线图只反映"待办"，而非堆积历史。同理，POTENTIAL_ISSUES.md 用于登记审计过程中发现的异常（如未初始化变量告警、边界情况），评审时需核对已知问题是否已修复、是否需增删条目。

3.4 脚本注释与逻辑同步

最后一项要求脚本内的 POD 文档与行内注释随逻辑变更同步更新，防止注释描述旧行为而代码已演进，为后续维护者与 AI Agent 提供准确的代码内文档。

四、第三步：版本一致性审计

版本一致性是发布前最关键的审计环节，目标是确保四处版本号指向同一个版本。工作流明确列出四项核查：

• CURRENT_VERSION.txt与mysqltuner.pl中的$tunerversion一致；
• 脚本头部注释与 POD 文档反映当前版本；
• Changelog包含当前版本的章节且日期正确；
• releases/v[VERSION].md存在并与Changelog同步。

4.1 单一事实源：CURRENT_VERSION.txt

仓库根目录的 CURRENT_VERSION.txt 是版本号的唯一事实源，当前内容为2.9.1。它与 mysqltuner.pl 中的两处版本声明严格对应：

# mysqltuner.pl - Version 2.9.1 # 脚本头部注释 our $tunerversion = "2.9.1"; # 内部版本变量

POD 文档部分还包含MySQLTuner 2.9.1 - MySQL High Performance Tuning Script的标题与Version 2.9.1段落。任何一处遗漏更新都会导致版本漂移。

4.2 测试代码如何机械验证一致性

这些审计项并非仅靠人工核对，仓库提供了自动化测试 tests/version_consistency.t 将审计固化为断言。该测试依次校验：

1. mysqltuner.pl头部# mysqltuner.pl - Version ...与CURRENT_VERSION.txt匹配；
2. 内部变量$tunerversion = "..."匹配；
3. POD 标题MySQLTuner ... - MySQL High Performance匹配；
4. POD 中Version ...章节匹配；
5. Changelog最新条目行首的版本号匹配。

测试脚本通过正则逐行扫描文件完成比对，例如：

if ($line =~ /(?:my|our)\s+\$tunerversion\s+=\s+"([\d\.]+)";/) { $var_ver = $1; }

这从工程上保证了"版本号漂移"在发布前就会被测试拦截。

4.3 Changelog 与 release 说明的双向同步

Changelog以2.9.1 2026-07-27格式维护每个版本的变更摘要，而 releases/v2.9.1.md 则提供面向用户的详细发布说明（包含 Executive Summary 与逐条变更分类）。审计要求两者内容同步、日期一致。例如 v2.9.1 的发布说明首段直接复述了 Changelog 中同版本的版本号与日期，正文则按feat、fix、chore、test、ci等 Conventional Commit 分类展开。相关的发布流程工作流（如 .agent/workflows/release-preflight.md、.agent/workflows/release-notes-gen.md、.agent/workflows/git-flow.md）会在发布链路上强制执行这些检查。

五、第四步：复核生成的.agent/README.md

工作流最后要求打开 .agent/README.md，确认脚本生成的三张表格（Governance & Execution Constraints、Specialized Capabilities & Knowledge、Automation & Operational Workflows）完整覆盖了新增/删除/重命名的文档，且描述字段与各文档 Front Matter 一致。复核要点包括：

• rules/下四份治理文档（如 .agent/rules/00_constitution.md）是否全部登记；
• skills/下四个技能包（如 .agent/skills/cli-execution-mastery/SKILL.md、.agent/skills/db-version-rift/SKILL.md、.agent/skills/legacy-perl-patterns/SKILL.md、.agent/skills/testing-orchestration/SKILL.md）是否以目录加链接的形式正确呈现；
• workflows/下所有工作流文档（如 .agent/workflows/run-tests.md）是否排序清晰、描述准确。

由于该文件完全由脚本生成，复核本质上是对"脚本解析结果是否符合预期"的最终确认。

六、测试保障：doc_sync 脚本自身的可验证性

与版本一致性审计一样，doc-sync 脚本本身也有自动化测试护航。tests/doc_sync.t 通过subtest组织三个断言：

ok(-f $doc_sync_script, "build/doc_sync.pl exists"); my $output = qx(perl "$doc_sync_script" 2>&1); my $exit_code = $? >> 8; is($exit_code, 0, "doc_sync.pl executed successfully"); like($output, qr/Documentation synchronized/i, "doc_sync.pl reports success");

测试先确认脚本文件存在，再真实执行一次脚本并断言退出码为 0、输出包含Documentation synchronized字样，从而保证同步脚本在任何环境下都能正常运转。这也与 .agent/workflows/run-tests.md 所描述的测试编排思路一致：凡是"生成类"的构建产物，都应配套"执行并断言"的回归测试。

七、工作流的使用前提与最佳实践

综合仓库现状，落地本工作流时应注意以下前提与习惯：

1. 依赖环境：build/doc_sync.pl使用 Perl 标准库（File::Basename、File::Spec、Cwd），无需安装额外 CPAN 模块，任何带有 Perl 5 的运行环境均可直接执行；主程序mysqltuner.pl同样以use 5.005起步，保持了极低版本的兼容性。
2. 执行顺序：建议在每次规则、技能或工作流文档发生增删改后立即运行一次/doc-sync，而不是等到发布前批量处理，可避免索引与实际目录长期脱节。
3. 与版本发布联动：版本一致性审计应作为发布前的硬性关卡，与 .agent/workflows/release-preflight.md 的预检流程配合执行，并由tests/version_consistency.t提供机械保障。
4. Front Matter 纪律：新增文档务必书写# 标题与description:字段，否则会在索引中回退为文件名与No description available.，影响索引可读性。

结语

.agent/workflows/doc-sync.md虽然篇幅不长，却浓缩了 MySQLTuner-perl 项目"文档自动化 + 发布审计"的完整方法论：以build/doc_sync.pl实现目录索引的机械重建，以五维评审清单覆盖 README、CLI 元数据、路线图与潜在问题，以版本一致性审计串联CURRENT_VERSION.txt、脚本头部、Changelog与 release 说明四处版本号，并以 tests/doc_sync.t 与 tests/version_consistency.t 两个测试文件将人工流程固化为可回归的工程约束。对于任何希望让"项目文档随代码演进、版本号永不失配"的 Perl 项目而言，这套模式都值得直接借鉴。

• 数据库
• 运维