自动文档同步Hook - 学习笔记-Hooks案例

一、自动文档同步Hook的设计

在实际的AI辅助编码工作流中，代码变更后手动更新文档是一件繁琐且容易被忽略的工作。自动文档同步Hook的目标是在每次工具调用（编辑、提交、推送等）之后或之前，自动检测相关文档是否需要更新，并主动执行同步操作，确保代码与文档始终保持一致。

1.1 设计理念

自动文档同步Hook遵循以下核心设计原则：

无侵入性：不打断用户的主要工作流，在后台自动执行文档同步
按需同步：仅当检测到相关文件发生变更时才触发文档更新，避免不必要的操作
可审查性：所有自动生成的文档变更都应提交给用户审查确认，不应静默覆盖
渐进式同步：从简单的README更新到复杂的API文档同步，逐步提升自动化程度

1.2 整体架构

一个完整的自动文档同步系统由以下核心模块组成：

变更检测器

监控文件系统变更，识别新增、修改、删除的文件，判断变更类型和影响范围

文档映射器

维护代码文件与文档文件的映射关系，知道修改了哪些代码需要更新哪些文档

内容生成器

根据代码变更内容生成对应的文档更新，包括API文档、README、CHANGELOG等

审查控制器

将生成的文档变更以diff形式呈现给用户，等待确认后才应用修改

1.3 触发时机映射

不同的文档同步任务应绑定到不同的Hook触发时机：

Hook时机	适用场景	说明
after:tool/Edit	API文档更新、README更新	文件编辑后立即同步相关文档
after:tool/git_commit	CHANGELOG更新	提交后从commit消息提取变更信息
before:tool/git_push	文档一致性检查	推送前做最终检查，阻断不一致的推送

核心要点：自动文档同步Hook的核心价值在于消除"代码已改、文档未更"的信息差。设计时需要根据不同类型的文档选择最合适的Hook触发时机，既要及时更新，又要避免过度频繁的干扰。

二、API文档自动更新Hook（after:tool/Edit）

API文档是项目中最重要的文档类型之一，它直接影响到前后端协作和第三方开发者集成体验。本Hook在检测到API定义文件发生变更后，自动更新对应的API文档。

2.1 检测API定义文件变更

首先需要确定哪些文件属于"API定义文件"，针对不同类型的项目有不同的识别规则：

OpenAPI / Swagger：监测 openapi.yaml、swagger.json 等文件变更
GraphQL Schema：监测 schema.graphql 或 *.graphqls 文件变更
JSDoc / TypeScript 类型：监测带有 @api、@route 等注解的路由处理函数文件
gRPC / Protobuf：监测 *.proto 文件变更

# 检测API定义文件变更的核心逻辑伪代码
function detectApiChanges(changedFiles) {
    const apiPatterns = [
        '**/openapi.{yaml,yml,json}',
        '**/*.graphql',
        '**/*.proto',
        '**/routes/**/*.ts'
    ];
    return changedFiles.filter(file => {
        return apiPatterns.some(pattern => matches(file, pattern));
    });
}

2.2 自动更新API文档

检测到API变更后，根据不同场景采取不同的更新策略：

API定义类型	文档工具	更新策略
OpenAPI	Swagger UI / Redocly	重新生成静态文档站点
JSDoc 注解	MkDocs / Typedoc	重新构建文档页面
GraphQL Schema	GraphQL Voyager / SpectaQL	生成新的schema文档

# API文档自动更新Hook实现示例
const apiDocHook = {
    after: ['tool/Edit', 'tool/Write'],
    handler: async ({ toolResult, context }) => {
        const changedFiles = toolResult.files;
        const apiFiles = detectApiChanges(changedFiles);

        if (apiFiles.length === 0) return;

        // 读取当前API定义文件内容
        const apiContent = await readFile(apiFiles[0]);

        // 解析API端点信息
        const endpoints = parseApiEndpoints(apiContent);

        // 生成或更新文档文件
        const docContent = generateApiDoc(endpoints);
        await writeFile('docs/api-reference.md', docContent);

        // 通知用户
        context.notify(`API文档已更新：检测到 ${apiFiles.length} 个API定义文件变更，已同步至 docs/api-reference.md`);
    }
};

2.3 更新API变更日志

除了更新文档正文外，还需要记录API的变更历史，包括新增、废弃和修改的接口：

# 自动生成API变更日志
function generateApiChangelog(oldEndpoints, newEndpoints) {
    const changes = [];

    // 检测新增的API
    for (const endpoint of newEndpoints) {
        if (!oldEndpoints.find(e => e.path === endpoint.path)) {
            changes.push({ type: 'added', endpoint });
        }
    }

    // 检测废弃的API
    for (const endpoint of oldEndpoints) {
        if (!newEndpoints.find(e => e.path === endpoint.path)) {
            changes.push({ type: 'removed', endpoint });
        }
    }

    // 检测修改的API
    for (const newEp of newEndpoints) {
        const oldEp = oldEndpoints.find(e => e.path === newEp.path);
        if (oldEp && !deepEqual(oldEp, newEp)) {
            changes.push({ type: 'modified', endpoint: newEp, diff: computeDiff(oldEp, newEp) });
        }
    }

    return changes;
}

最佳实践：API文档更新后，应在Hook的反馈信息中明确告知用户具体变更了哪些内容，例如"新增了 /api/v2/users 端点的文档，废弃了 /api/v1/users 端点的文档"，让用户清楚知道自动同步的结果。

三、README自动维护Hook

README是项目的门面，它需要随着项目的发展持续更新。然而在实际开发中，README经常成为被遗忘的角落。本Hook在检测到代码变更后，自动更新README中的功能列表、使用示例和配置说明。

3.1 检测新功能添加

通过分析代码变更内容，自动识别新增的功能模块，并更新README中的功能列表：

# README功能列表自动更新
async function updateFeatureList(readmePath, newFeatures) {
    let readme = await readFile(readmePath);

    // 查找"功能特性"章节
    const featureSectionMatch = readme.match(/## 功能特性[\s\S]*?(?=## )/);

    if (featureSectionMatch) {
        const existingFeatures = parseFeatureList(featureSectionMatch[0]);

        for (const feature of newFeatures) {
            if (!existingFeatures.includes(feature.name)) {
                // 将新功能添加到列表中
                const newItem = `- **${feature.name}**：${feature.description}`;
                readme = readme.replace(
                    '## 功能特性',
                    `## 功能特性\n${newItem}`
                );
            }
        }

        await writeFile(readmePath, readme);
    }
}

3.2 更新使用示例

当检测到API签名或CLI参数发生变化时，自动更新README中的使用示例代码：

CLI工具：根据命令参数定义自动生成使用示例，确保--help输出与README一致
库函数：根据函数签名变更更新示例代码中的导入语句和调用方式
配置文件：检测配置项的增删改，同步更新README中的配置说明和示例

# 自动更新README中的使用示例
function updateUsageExamples(readme, apiChanges) {
    for (const change of apiChanges) {
        if (change.type === 'signature_changed') {
            // 查找并替换旧的使用示例
            const oldExample = findExampleForFunction(readme, change.functionName);
            if (oldExample) {
                const newExample = generateExample(change.newSignature);
                readme = readme.replace(oldExample, newExample);
            }
        }
    }
    return readme;
}

3.3 更新项目徽章和状态

README头部通常包含一系列项目状态徽章，这些信息也可以自动维护：

徽章类型	自动更新策略
构建状态	监听CI Hook结果，自动更新徽章链接和状态
版本号	检测 package.json / Cargo.toml 等版本文件变更后更新
许可证	检测 LICENSE 文件变更后更新
API稳定性	根据API变更的幅度自动调整（稳定/测试中/不稳定）

注意：README自动维护Hook应谨慎操作，特别是对于存在大量手动定制内容的README。建议只维护结构化的部分（功能列表、配置项表、API参考），保留用户手动编写的描述性内容不变。Hook的更新操作应生成diff供用户审查。

四、CHANGELOG自动更新Hook（after:tool/git_commit）

CHANGELOG是记录项目版本变更历史的重要文档。传统的手动维护方式经常出现遗漏或不规范的记录。本Hook在每次代码提交后，自动从commit消息中提取变更信息并按规范格式写入CHANGELOG。

4.1 从Commit消息自动提取变更

根据约定式提交（Conventional Commits）规范解析commit消息，提取结构化的变更信息：

# 从commit消息提取变更信息
function parseCommitMessage(message) {
    // 支持 Conventional Commits 格式
    // feat: 添加用户登录功能
    // fix(auth): 修复token过期未刷新问题
    // BREAKING CHANGE: 重构API认证方式

    const patterns = {
        'feat': 'Added',
        'fix': 'Fixed',
        'docs': 'Documentation',
        'refactor': 'Changed',
        'perf': 'Changed',
        'deprecate': 'Deprecated',
        'remove': 'Removed'
    };

    const match = message.match(/^(\w+)(\(.+?\))?: (.+)$/m);
    if (!match) return null;

    const [, type, scope, description] = match;

    return {
        category: patterns[type] || 'Other',
        scope: scope ? scope.replace(/\(|\)/g, '') : '',
        description,
        isBreaking: message.includes('BREAKING CHANGE')
    };
}

4.2 按类型分类写入CHANGELOG

提取的变更信息按标准分类组织到CHANGELOG的对应版本标题下：

# CHANGELOG自动更新Hook
const changelogHook = {
    after: ['tool/git_commit'],

    handler: async ({ gitContext, context }) => {
        const { message, version, date } = gitContext;
        const change = parseCommitMessage(message);

        if (!change) return;  // 不符合规范，跳过

        let changelog = await readFile('CHANGELOG.md');

        // 检查当前版本标题是否存在
        const versionHeader = `## [${version}] - ${date}`;

        if (!changelog.includes(versionHeader)) {
            // 创建新的版本条目
            const newSection = `\n${versionHeader}\n\n### ${change.category}\n- ${change.description}\n`;
            changelog = changelog.replace('# Changelog', `# Changelog${newSection}`);
        } else {
            // 添加到现有版本条目
            const categoryHeader = `### ${change.category}`;
            if (changelog.includes(categoryHeader)) {
                // 追加到对应分类下
                changelog = changelog.replace(
                    `${categoryHeader}\n`,
                    `${categoryHeader}\n- ${change.description}\n`
                );
            } else {
                // 创建新的分类
                changelog = changelog.replace(
                    versionHeader,
                    `${versionHeader}\n\n${categoryHeader}\n- ${change.description}`
                );
            }
        }

        await writeFile('CHANGELOG.md', changelog);
        context.suggest(`CHANGELOG已更新：添加了 "${change.description}" 到 ${version} 版本的 ${change.category} 分类下`);
    }
};

4.3 生成Release Notes预览

在CHANGELOG更新后，自动生成一个Release Notes预览，方便用户快速了解本次发布的内容：

# Release Notes 预览生成
function generateReleasePreview(version, changes) {
    const lines = [
        `# Release ${version}`,
        ''
    ];

    const categories = groupBy(changes, 'category');
    for (const [category, items] of Object.entries(categories)) {
        lines.push(`### ${category}`);
        lines.push(...items.map(item => `- ${item.description}`));
        lines.push('');
    }

    return lines.join('\n');
}

// 输出预览供用户审查
context.preview('Release Notes 预览', generateReleasePreview(version, allChanges));

提示：CHANGELOG自动更新Hook的效果高度依赖于commit消息的规范性。建议在项目中推广使用约定式提交（Conventional Commits）规范，并在pre-commit Hook中加入commit消息格式校验，确保消息格式正确。

五、文档一致性检查Hook（before:tool/git_push）

在将代码推送到远程仓库之前，进行最终的文档一致性检查，确保没有遗漏的文档更新。这是自动文档同步系统的最后一道防线。

5.1 检查代码与文档的一致性

推送前执行一系列自动化检查，验证代码变更与文档的对应关系：

函数/接口检查：检查代码中新增的函数是否有对应的文档条目
配置项检查：检查新增的配置项是否有对应的配置说明
参数检查：检查函数参数变更后文档中的参数说明是否同步更新
废弃标记检查：检查标记为废弃的接口在文档中是否有对应的废弃说明

# 文档一致性检查实现
async function checkConsistency(codeChanges, context) {
    const issues = [];

    // 1. 提取代码中定义的公共API
    const publicApis = extractPublicApis(codeChanges);

    // 2. 读取现有文档中的API参考
    const documentedApis = extractDocumentedApis(await readFile('docs/api-reference.md'));

    // 3. 比对差异
    for (const api of publicApis) {
        const documented = documentedApis.find(d => d.name === api.name);

        if (!documented) {
            issues.push({
                severity: 'error',
                message: `函数 "${api.name}" 缺少对应的API文档`,
                file: api.file,
                line: api.line
            });
        } else if (!deepEqual(api.params, documented.params)) {
            issues.push({
                severity: 'warning',
                message: `函数 "${api.name}" 的参数已变更，文档可能已过期`,
                detail: {
                    expected: api.params,
                    documented: documented.params
                }
            });
        }
    }

    return issues;
}

5.2 生成不一致报告

检查完成后，将结果汇总为结构化的报告：

# 文档一致性检查结果示例
═════ 文档一致性检查报告 ═════

┌─ 错误 (2) ──────────────────────┐
│ 1. 函数 "createUser" 缺少API文档 │
│    位置：src/services/user.ts:42 │
│ 2. 配置项 "auth.ttl" 缺少配置说明│
│    位置：src/config/default.ts:18│
└──────────────────────────────────┘

┌─ 警告 (1) ───────────────────────────┐
│ 1. 函数 "sendNotification" 参数已变更 │
│    预期: { userId, template, channel }│
│    文档: { userId, template }         │
│    位置：src/services/notify.ts:55    │
└───────────────────────────────────────┘

┌─ 建议 (2) ──────────────────────────┐
│ 1. README功能列表未包含 "批量导入"   │
│ 2. CHANGELOG存在未分类的提交记录      │
└──────────────────────────────────────┘

⚠ 推送已阻断。请修复上述错误后重试。

5.3 阻断与放行策略

并非所有不一致都需要阻断推送，应根据严重程度分级处理：

严重级别	条件	行为
阻断（Blocking）	存在严重不一致：公共API完全无文档	阻止推送，要求用户修复
警告（Warning）	存在部分不一致：参数变更文档未更新	询问用户是否继续推送或修复
建议（Suggestion）	存在轻量不一致：README未包含新功能	提示用户但不阻断推送

# 文档一致性检查Hook
const consistencyHook = {
    before: ['tool/git_push'],

    handler: async ({ gitContext, context }) => {
        context.report('正在进行推送前文档一致性检查...');

        const issues = await checkConsistency(gitContext.changedFiles);

        if (issues.length === 0) {
            context.report('✓ 文档一致性检查通过，所有代码均有对应的文档覆盖');
            return;  // 放行
        }

        // 展示详细报告
        context.showReport(generateReport(issues));

        // 根据严重级别决定是否阻断
        const blockingIssues = issues.filter(i => i.severity === 'error');
        if (blockingIssues.length > 0) {
            await context.ask(
                `发现 ${blockingIssues.length} 个严重不一致问题，是否仍然推送？`,
                { choices: ['修复后推送', '忽略并强制推送'] }
            );
        }
    }
};

核心要点：文档一致性检查Hook是文档同步体系的最后一道关卡。它应当作为一个"安全网"（Safety Net）而非"绊脚石"（Stumbling Block）。设计上要给用户选择权——阻断严重问题、警告一般问题、提示轻微问题，做到既不遗漏也不过度干扰。

六、总结与最佳实践

自动文档同步Hook系统从三个层面解决了文档维护的难题：

及时性（after:tool/Edit）：在代码变更的第一时间同步API文档和README，杜绝"改完忘了更新"
规范性（after:tool/git_commit）：从commit消息自动提取变更写入CHANGELOG，保证版本记录的完整和一致
完整性（before:tool/git_push）：推送前的全量检查兜底，确保没有遗漏的文档更新

在实际项目中实施自动文档同步时，建议遵循以下最佳实践：

渐进式引入：先从CHANGELOG自动更新开始，再逐步引入README维护和API文档同步
约定大于配置：推广约定式提交和标准化的代码注释格式，降低自动解析的复杂度
人工审查闭环：所有自动生成的文档变更都应生成diff供用户确认，不静默覆盖
可配置开关：每个同步模块都应提供启用/禁用开关，允许用户按需定制
失败优雅降级：当自动同步失败时（如网络问题、格式解析错误），记录日志并通知用户手动处理

文档是代码的影子。好的影子应该与本体同步移动，而不是在原地等待被追上。