docs-updater

通用文档更新器

分析自最新发布标签以来的 Git 变更，并更新需要随之调整的文档文件。

概述

使用 Git 历史记录找出与发布相关的变更，然后更新 README.md、CHANGELOG.md 以及任何相关文档目录。保持工作流程聚焦于获得用户明确批准、精准编辑，以及遵循仓库特定的文档结构。

使用场景

在以下情况下使用此技能：

• 准备发行说明或更新 Unreleased 变更日志
• 功能开发完成后同步更新 README.md 或文档
• 在提交 PR 或发布前审查自上次发布以来的变更

前置条件

开始前，请确认满足以下条件：

# Verify we're in a git repository
git rev-parse --git-dir

# Check that git tags exist
git tag --list | head -5

# Verify documentation files exist
test -f README.md || echo "README.md not found"
test -f CHANGELOG.md || echo "CHANGELOG.md not found"

如果不存在标签，请告知用户此技能需要至少一个发布标签作为比较基准。

说明

阶段 1：检测最新发布版本

目标：找出用于比较的最新发布版本。

操作：

1. 检测比较基准并显示：

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

if [ -z "$LATEST_TAG" ]; then
    echo "No git tags found. This skill requires at least one release tag."
    echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')"
    exit 1
fi

CURRENT_BRANCH=$(git branch --show-current)
VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/')

echo "Latest release tag: $LATEST_TAG"
echo "Version detected: $VERSION"
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

阶段 2：执行 Git 差异分析

目标：分析上次发布与当前分支之间的所有变更。

操作：

1. 获取提交范围和统计信息：

# Get commit count between tag and HEAD
COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0")
echo "Commits since $LATEST_TAG: $COMMIT_COUNT"

# Get file change statistics
git diff --stat ${LATEST_TAG}..HEAD

2. 提取提交消息以供分析：

# Get all commit messages in the range
COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)

# Display commits for review
echo "$COMMITS"

3. 获取详细的文件变更：

# Get list of changed files
CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)

# Show add/modify/delete status for quick categorization
git diff --name-status ${LATEST_TAG}..HEAD

4. 根据文件路径识别组件领域：

# Detect which components/areas changed
echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

阶段 3：发现文档结构

目标：找出项目中的所有相关文档位置。

操作：

1. 查找常见文档目录：

# Check for common documentation locations
DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/")
[ -d "documentation" ] && DOC_FOLDERS+=("documentation/")
[ -d "doc" ] && DOC_FOLDERS+=("doc/")

# Find plugin-specific docs
for plugin_dir in plugins/*/; do
    if [ -d "${plugin_dir}docs" ]; then
        DOC_FOLDERS+=("${plugin_dir}docs/")
    fi
done

echo "Documentation folders found:"
printf '  - %s\n' "${DOC_FOLDERS[@]}"

2. 找出现有文档文件：

# Check for standard doc files
DOC_FILES=()

[ -f "README.md" ] && DOC_FILES+=("README.md")
[ -f "CHANGELOG.md" ] && DOC_FILES+=("CHANGELOG.md")
[ -f "CONTRIBUTING.md" ] && DOC_FILES+=("CONTRIBUTING.md")
[ -f "docs/GUIDE.md" ] && DOC_FILES+=("docs/GUIDE.md")

echo "Documentation files found:"
printf '  - %s\n' "${DOC_FILES[@]}"

阶段 4：生成 CHANGELOG 更新

目标：按照 Keep a Changelog 标准创建分类的变更日志条目。

操作：

1. 使用约定式提交语义解析提交，并将其归入 Keep a Changelog 的相应部分，例如 Added、Changed、Fixed、Removed 和 Security。

2. 阅读现有的 CHANGELOG.md 以了解其结构，然后按照 Keep a Changelog 格式生成新条目。

详细的 bash 命令和变更日志模板，请参阅 references/examples.md。

阶段 5：更新 README.md

目标：在主 README 中更新相关的高层变更。

操作：

1. 阅读当前的 README.md 以了解其结构
2. 找出需要更新的部分（功能列表、技能/Agent、设置说明、版本引用）
3. 使用 Edit 工具应用更新：保留结构、保持语气，并更新版本号

阶段 6：更新文档目录

目标：将变更同步到 docs/ 目录中的相关文档。

操作：

1. 检查找到的每个文档目录，找出引用了变更代码的文件
2. 将变更文件映射到对应文档
3. 生成更新：添加新功能文档、更新 API 参考、修正过时示例

详细的发现模式和更新策略，请参阅 references/examples.md。

阶段 7：提交变更供审查

目标：在应用变更前向用户展示拟议的更新。

操作：

1. 提供拟议变更的摘要：

## Proposed Documentation Updates

### Version Information
- Previous release: $LATEST_TAG
- Current branch: $CURRENT_BRANCH
- Commits analyzed: $COMMIT_COUNT

### Files to Update
- [ ] CHANGELOG.md - Add new version section with categorized changes
- [ ] README.md - Update [specific sections]
- [ ] docs/[specific files] - Update documentation

### Summary of Changes
**Added**: N new features
**Changed**: N modifications
**Fixed**: N bug fixes
**Breaking**: N breaking changes

2. 通过 AskUserQuestion 征求用户确认：

• 确认要更新哪些文件
• 询问是否需要修改任何变更
• 获得继续操作的批准

阶段 8：应用文档更新

目标：写入已批准的更新，然后验证更新是否正确生效。

操作：

1. 更新 CHANGELOG.md：

# Read current changelog
CURRENT_CHANGELOG=$(cat CHANGELOG.md)

# Prepend new section
cat > CHANGELOG.md << 'EOF'
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
[New content goes here]

[Rest of existing changelog]
EOF

2. 使用 Edit 工具更新 README.md：

• 对特定部分进行定点编辑
• 保留整体结构
• 适用时更新版本号

3. 更新文档文件：

# For each documentation file that needs updates
# Use Edit tool to make precise changes

4. 验证已应用的变更：

# Confirm key files still exist after editing
test -f CHANGELOG.md && echo "CHANGELOG.md present"
test -f README.md && echo "README.md present"

# Review the scope of markdown changes
git diff --stat -- '*.md'

# Spot-check the actual content written
git diff -- '*.md' | sed -n '1,240p'

5. 如果仓库已定义文档或 Markdown 验证命令，请在完成前运行这些命令。

示例

示例 1：功能开发后更新文档

用户请求：“更新我刚添加的新功能的文档”

输出：

• 最新标签：v2.4.1 → 当前分支：develop
• 已分析 5 个提交
• 已为新的 Spring Boot Actuator 技能生成 CHANGELOG 条目
• 已更新 README.md 中的技能列表

示例 2：准备发布文档

用户请求：“为 v2.5.0 版本发布准备文档”

输出：

• 已分析自 v2.4.1 以来的 47 个提交
• 检测到 15 项功能、8 项修复、3 项重大变更
• 已生成完整的 CHANGELOG.md [2.5.0] 部分
• 已更新 README.md 和插件文档

示例 3：增量同步

用户请求：“同步文档，我做了一些更改”

输出：

• 已分析 2 个提交
• 已针对 github-issue-workflow 技能的更改更新 CHANGELOG
• 无需更新 README 或插件文档

有关详细的会话记录和故障排除，请参阅 references/examples.md。

最佳实践

1. 写入前预览，写入后验证：先展示计划，然后在编辑后确认最终差异
2. 遵循 Keep a Changelog：保持一致的变更日志格式
3. 正确分类：使用正确的类别（Added、Changed、Fixed 等）
4. 明确具体：在变更日志条目中包含插件／组件名称
5. 保留结构：维持现有文档结构和风格
6. 引用提交：在有助于追溯时，包含提交哈希
7. 处理重大变更：通过迁移说明清楚标注重大变更
8. 更新版本引用：确保文档中的版本号保持一致

限制与警告

1. 需要 git 标签：只有当仓库至少有一个发布标签时，此技能才能运行
2. 只读分析：此技能会分析更改，但会在写入前征求确认
3. 需要手动审查：应审查生成的变更日志条目，确保准确无误
4. 约定式提交：对于使用约定式提交格式的项目，效果最佳
5. 不会创建标签：此技能会更新文档，但不会创建发布标签
6. 不会自动提交：文档更改会准备好，但不会自动提交
7. 项目特定模式：某些项目可能有需要遵循的自定义变更日志格式
8. 文件路径：所有文件路径均使用正斜杠（Unix 风格），以确保跨平台兼容