开源项目文档质量检测工具

这是一个用于自动化分析 GitHub 开源项目文档质量的工具。它结合了基于规则的静态检查和基于大模型（LLM）的语义分析，为开源项目提供多维度的文档评估报告。

✨ 功能特性

文档完整性检查 (Completeness Check)
- 自动扫描项目根目录及 /docs 目录。
- 检查关键文件是否存在（如 README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT 等）。
- 根据文件重要性进行加权评分。
格式规范检查 (Format Check)
- 基于规则对 Markdown 文件进行语法分析。
- 检测行长过长、代码块闭合缺失、标题层级混乱、空链接等问题。
语义深度分析 (Semantic Check)
- 集成 Alibaba Cloud DashScope (通义千问 Qwen-Plus) 模型。
- 对 README 等核心文档进行内容理解，生成摘要。
- 评估文档的可读性、逻辑性，并提供具体的改进建议。
- 支持 Mock 模式，无 API Key 也可体验基础功能。
可视化报告
- 提供现代化的 React 前端界面。
- 直观展示项目总分、雷达图维度分析及详细的问题列表。

🛠️ 技术栈

后端: Python 3.8+, FastAPI, Uvicorn
前端: React 18, Vite, Chart.js, Tailwind CSS (或类似样式库)
AI 能力: OpenAI SDK (兼容调用阿里云 DashScope API)
工具库: PyGithub (GitHub API), Markdown-it-py

📦 系统要求

Python 3.8 及以上
Node.js 16 及以上（建议最新 LTS）
npm 8+（随 Node 一起安装）
Git
操作系统：Windows / macOS / Linux，前端在现代浏览器（Chrome/Edge/Firefox/Safari）上测试

🚀 安装与配置

克隆项目

git clone https://gitlink.org.cn/YYJ1/ops.git
cd ops

后端依赖（FastAPI 服务）

cd backend
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install -r requirements.txt

前端依赖（React + Vite）
```
cd ../frontend
npm install
```
DashScope API Key（必填才能启用语义分析）
- 前端页面会要求输入；
- 若直接调用后端 API，请在请求体的 api_key 字段传入。
需要代理访问 GitHub 时，可在终端设置 HTTPS_PROXY，示例：
```
$env:HTTPS_PROXY="http://127.0.0.1:7890"
```

⚡ 快速开始

启动后端（默认端口 8000）
```
cd backend
uvicorn app.main:app --reload
```
访问 http://127.0.0.1:8000/docs 查看 API 文档。
启动前端（默认端口 5173）
```
cd frontend
npm run dev
```
打开浏览器访问 http://127.0.0.1:5173，输入 GitHub 仓库地址与 DashScope API Key，点击 Analyze 即可生成报告。

🧭 使用示例

通过 API 直接分析仓库

curl -X POST "http://127.0.0.1:8000/analyze" \
  -H "Content-Type: application/json" \
  -d '{
        "repo_url": "https://github.com/fastapi/fastapi",
        "api_key": "YOUR_DASHSCOPE_API_KEY"
      }'

返回的 JSON 将包含项目完整性得分、各文档格式/语义分析结果与改进建议。

在前端界面操作

访问前端页面，输入仓库地址（如 https://github.com/fastapi/fastapi）与 DashScope API Key。
点击 Analyze，等待雷达图和问题列表生成。

📚 依赖与版本

后端依赖：见 backend/requirements.txt
前端依赖：见 frontend/package.json
需要的运行时版本：Python 3.8+、Node.js 16+（建议最新 LTS）

📄 许可证

本项目采用 MIT License，详见 LICENSE 文件。

🤝 贡献与支持

欢迎通过 Issues/PR 贡献代码或反馈问题
开发与提交规范详见 CONTRIBUTING.md。

🧩 兼容性说明

支持 Windows / macOS / Linux 开发环境；
前端面向现代浏览器（Chrome/Edge/Firefox/Safari）；
DashScope API 需稳定的网络访问，若访问 GitHub 或 DashScope 受限，请按需配置代理。