Gemini CLI + MCP 文档生成器

此仓库包含一个多功能的GitHub Actions工作流，该工作流使用Google的Gemini CLI与模型上下文协议（MCP）集成自动生成文档。

功能

• 跨平台支持：Windows和Linux工作流
• 可配置路径：自定义输入和输出目录
• 灵活触发：手动调度或自动推送触发
• 错误处理：全面验证和错误报告
• MCP集成：GitHub MCP服务器提供增强的上下文
• 自动化工作流：无缝更新文档

快速开始

1. 复制工作流

将适当的工作流文件复制到您的仓库中：

• Windows：.github/workflows/update_docs_windows.yml
• Linux：.github/workflows/update_docs_linux.yml

2. 设置密钥

在仓库中添加这些密钥（设置 → 密钥和变量 → 操作）：

• PERSONAL_ACCESS_TOKEN：具有repo权限的GitHub个人访问令牌
• GITHUB_TOKEN：由GitHub Actions自动提供的

3. 配置您的仓库

工作流设计为开箱即用，默认设置如下：

• 输入目录：src/
• 输出目录：docs/
• 分支：main

工作原理

MCP服务器配置

工作流会自动配置一个GitHub MCP服务器，提供以下内容：

• 仓库上下文和文件信息
• 问题和拉取请求数据
• 增强的文档生成能力

文档生成过程

1. 安装：安装Node.js和Gemini CLI
2. MCP配置：创建带有GitHub MCP服务器的.gemini/settings.json
3. 文档生成：从源文件生成文档
4. 提交和推送：自动提交并推送更改

自定义选项

仓库变量（可选）

您可以在仓库设置中设置这些变量（设置 → 密钥和变量 → 操作 → 变量）：

• INPUT_DIR：用于文档生成的源目录（默认：src/）
• OUTPUT_DIR：生成文档的输出目录（默认：docs/）
• COMMIT_MESSAGE：自定义提交消息（默认："Auto-update docs with Gemini CLI + MCP"）
• ENABLE_AUTO_PUSH：启用/禁用自动推送（默认：true）
• CLEAN_CACHE：在运行前清理npm缓存（默认：true）

手动触发选项

当手动触发工作流时，您可以覆盖以下内容：

• 输入目录：指定自定义源目录
• 输出目录：指定自定义输出目录
• 分支名称：提交的目标分支
• 提交消息：自定义提交消息
• 自动推送：启用/禁用自动推送
• 清理缓存：启用/禁用npm缓存清理

使用示例

基本使用

# 将工作流文件复制到您的仓库
# 设置所需的密钥
# 工作流将在主分支上推送到时自动运行

自定义目录结构

如果您的项目有不同的结构：

# 设置仓库变量：
INPUT_DIR: "source/"
OUTPUT_DIR: "documentation/"

不同分支

# 设置仓库变量：
DEFAULT_BRANCH: "develop"

手动触发并自定义设置

1. 转到操作 → 工作流 → "Auto Update Docs with Gemini CLI + MCP"
2. 点击"运行工作流"
3. 填写自定义参数：
   • 输入目录：lib/
   • 输出目录：api-docs/
   • 提交消息： "更新API文档"

工作流特性

错误处理

• 验证输入目录是否存在
• 验证MCP配置创建
• 检查文档生成是否成功
• 提供详细的错误消息

性能优化

• 使用NPM缓存以加快安装速度
• 条件缓存清理
• 高效的文件操作

安全性

• 使用GitHub令牌进行身份验证
• 安全的MCP服务器配置
• 不硬编码凭据

高级功能

MCP服务器集成

工作流包括一个GitHub MCP服务器，提供以下内容：

• 访问仓库元数据
• 文件内容和结构信息
• 问题和PR管理能力
• 增强的文档生成上下文

自定义文档脚本

仓库包含一个示例scripts/generate_docs.js，演示了以下内容：

• 文件系统操作
• 文档模板生成
• 与外部工具的集成

故障排除

常见问题

1. "输入目录不存在"
   • 确保您的源目录存在

• 检查INPUT_DIR变量或工作流输入

2. "MCP配置失败"

   • 验证PERSONAL_ACCESS_TOKEN密钥已设置
   • 检查令牌权限

3. "没有要提交的更改"

   • 如果文档没有变化，这是正常的
   • 检查源文件是否被修改

4. "文档生成失败"

   • 验证Gemini CLI安装
   • 检查源文件是否有效

调试步骤

1. 在操作标签中检查工作流日志
2. 验证密钥是否正确配置
3. 先使用手动触发测试
4. 检查文件权限和路径

高级配置

多个文档集

为不同的文档类型创建多个工作流文件：

# api-docs.yml
INPUT_DIR: "api/"
OUTPUT_DIR: "api-docs/"

# user-guide.yml  
INPUT_DIR: "docs/"
OUTPUT_DIR: "user-guide/"

条件执行

修改工作流以仅在特定条件下运行：

on:
  push:
    branches: [main, develop]
    paths: ['src/**', 'docs/**']

自定义MCP服务器

扩展MCP配置以添加额外的服务器：

mcpServers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
  custom:
    command: "npx"
    args: ["-y", "your-custom-mcp-server"]

开发

本地测试

要本地测试工作流：

1. 克隆仓库
2. 设置您的GitHub令牌
3. 手动运行工作流
4. 检查生成的文档

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 使用不同的仓库结构进行测试
5. 提交拉取请求

相关文件

• .github/workflows/update_docs_windows.yml：Windows工作流
• .github/workflows/update_docs_linux.yml：Linux工作流
• scripts/generate_docs.js：示例文档脚本
• Gemini.md：项目配置和约定

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件获取详情。 </中文翻译>