自动文档

Name: 自动文档
Author: PARS-DOE

作者：PARS-DOE5 星标更新：2025-03-14

安装使用来源：spider==github.com

项目介绍

自动文档生成MCP服务器

一个使用OpenRouter API分析代码仓库目录结构和代码文件以自动生成文档的MCP（模型上下文协议）服务器。

功能

智能目录分析：递归地分析代码仓库中的目录和文件
Git集成：尊重.gitignore模式以跳过被忽略的文件
AI驱动的文档生成：使用OpenRouter API（默认使用Claude 3.7）生成全面的文档
测试计划生成：自动创建包含合适测试类型、边缘案例和模拟需求的测试计划
代码审查：执行高级开发者级别的代码审查，重点关注安全性、最佳实践和改进
自底向上方法：从叶目录开始向上工作，创建连贯的文档层次结构
智能文件处理：
- 在每个目录级别创建documentation.md、testplan.md和review.md文件
- 跳过单文件目录，但将其内容包含在父级输出中
- 支持更新现有文件
- 为超过限制的目录创建备用文件
进度报告：提供详细的进度更新，防止长时间运行操作超时
高度可配置：自定义文件扩展名、大小限制、模型、提示等
可扩展架构：模块化设计使其易于在未来添加更多自动工具

安装

先决条件

Node.js（v16或更高版本）
一个OpenRouter API密钥

安装步骤

# 克隆仓库
git clone https://github.com/PARS-DOE/autodocument.git
cd autodocument

# 安装依赖
npm install

# 构建项目
npm run build

配置

通过环境变量、命令行参数或MCP配置文件来配置autodocument：

环境变量

OPENROUTER_API_KEY：您的OpenRouter API密钥
OPENROUTER_MODEL：要使用的模型（默认：anthropic/claude-3-7-sonnet）
MAX_FILE_SIZE_KB：最大文件大小（KB，默认：100）
MAX_FILES_PER_DIR：每个目录的最大文件数（默认：20）

使用Roo或Cline

Roo Code和Cline是支持模型上下文协议（MCP）的AI助手，允许它们使用外部工具如autodocument。

Roo/Cline设置

克隆并构建仓库（遵循上述安装步骤）

配置MCP服务器：

对于Roo：

在MCP服务器菜单中，编辑MCP设置，并使用您克隆仓库的完整路径添加autodocument配置：

使用您克隆仓库的完整路径添加autodocument配置：

{
  "mcpServers": {
    "autodocument": {
      "command": "node",
      "args": ["/path/to/autodocument/build/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

对于Claude桌面应用：

编辑Claude桌面应用配置文件的位置：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

使用您克隆仓库的完整路径添加autodocument配置：

{
  "mcpServers": {
    "autodocument": {
      "command": "node",
      "args": ["/path/to/autodocument/build/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

重要：确保使用绝对路径指向您克隆仓库中的build/index.js文件
重启Roo/Cline或Claude桌面应用

使用工具：在与Roo或Claude的对话中，您可以请求它为您项目的代码仓库生成文档或测试计划：

请为我位于/path/to/my/project的项目生成文档

或者为测试计划：

请为我位于/path/to/my/project的项目创建测试计划

或者为代码审查：

请审查我位于/path/to/my/project的项目中的代码

工作原理

autodocument服务器采用自底向上的方法工作：

发现：递归扫描目标目录，遵守.gitignore规则
智能目录处理：
- 识别具有多个代码文件或子目录的目录
- 跳过单文件目录，但将其内容包含在父级文档中
文件分析：分析代码文件，按扩展名和大小过滤
文档生成：对于每个符合条件的目录：
- 读取代码文件
- 将代码发送到OpenRouter API，带有优化的提示
- 创建documentation.md文件（或更新现有文件）
聚合：随着它向上移动目录树：
- 处理每个父级目录
- 包含来自子目录的文档
- 在每个级别创建全面概述

架构

该项目遵循模块化架构：

核心组件：配置管理和服务器实现
爬虫模块：目录遍历和文件发现
分析器模块：代码文件分析和过滤
OpenRouter模块：用于基于LLM的内容生成的AI集成
文档模块：文档过程的编排
工具模块：不同自动工具（文档、测试计划等）的可扩展系统
提示配置：集中化的提示管理，便于定制

示例用法

命令行

# 导航到您克隆的仓库
cd path/to/cloned/autodocument

# 设置您的API密钥（或在环境变量中配置）
export OPENROUTER_API_KEY=your-api-key-here

# 在项目上运行文档生成
node build/index.js /path/to/your/project

程序化使用

const { spawn } = require('child_process');
const path = require('path');

// 您项目的路径
const projectPath = '/path/to/your/project';

// 您的OpenRouter API密钥
const apiKey = 'your-api-key-here';

// 创建一个JSON命令以模拟MCP工具调用
const toolCallCommand = JSON.stringify({
  jsonrpc: '2.0',
  method: 'call_tool',
  params: {
    name: 'generate_documentation',
    arguments: {
      path: projectPath,
      openRouterApiKey: apiKey
    }
  },
  id: 1
});

// 启动服务器进程 - 使用您克隆仓库的完整路径
const serverProcess = spawn('node', ['/path/to/autodocument/build/index.js'], {
  env: {
    ...process.env,
    OPENROUTER_API_KEY: apiKey
  }
});

// 发送工具命令
serverProcess.stdin.write(toolCallCommand + '\n');

// 处理服务器输出和错误
// ...

自定义提示

您可以通过编辑src/prompt-config.ts文件轻松自定义工具使用的提示。这允许您：

调整生成内容的语气和风格
添加特定于您项目需求的指令
修改现有内容的更新方式

提示配置与工具实现分离，使得无需更改代码即可轻松实验不同的提示。

可用工具

generate_documentation

为代码仓库生成全面的文档：

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为true
}

autotestplan

为代码仓库中的函数和组件生成测试计划：

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为true
}

autoreview

为仓库生成高级开发者级别的代码审查：

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为true
}

输出文件

服务器创建几种类型的输出文件：

documentation.md

包含目录中代码的全面文档，包括：

代码的目的
关键函数和类
文件之间的关系
与子组件的集成

testplan.md

包含目录中代码的详细测试计划，包括：

每个函数的适当测试类型（单元、集成、端到端）
常见边缘案例
依赖项模拟要求
集成测试策略

review.md

包含高级开发者级别的代码审查反馈，包括：

安全问题和漏洞
最佳实践违规
潜在的bug或架构问题
重构机会
实用且建设性的反馈（不挑剔样式问题）

备用文件

当目录超出大小或文件数量限制时创建：

undocumented.md - 用于文档生成
untested.md - 用于测试计划生成
review-skipped.md - 用于代码审查生成

这些文件包含：

跳过处理的原因
分析并排除的文件列表
如何修复的说明（增加限制或手动创建内容）

故障排除

API密钥问题

如果您看到关于无效API密钥的错误：

确保已设置OPENROUTER_API_KEY环境变量
检查您的OpenRouter账户是否处于活动状态
验证您有足够的信用额度进行API调用

大小限制错误

如果由于大小限制而跳过了太多目录：

设置环境变量以增加限制：MAX_FILE_SIZE_KB和MAX_FILES_PER_DIR
考虑手动记录非常大的目录

模型选择

如果您对文档质量不满意：

通过设置OPENROUTER_MODEL环境变量尝试不同的模型

许可

CC0-1.0许可 - 此作品由美国能源部根据CC0公有领域贡献

贡献

欢迎贡献！请随时提交Pull Request。

添加新工具

架构设计旨在使添加新的自动工具变得容易：

在src/tools目录下创建一个新的继承自BaseTool的类
在src/prompt-config.ts中定义提示
在ToolRegistry中注册工具

查看现有工具以了解如何实现新功能。