Skip to content

Commit 041add6

Browse files
淼淼claude
andcommitted
docs: Update README_CN.md to match README.md structure
- Sync Chinese documentation with English version - Add architecture diagram with Chinese labels - Add complete quick start guide (6 steps) - Add API endpoints table - Add scan types and alert channels configuration - Add project structure overview Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent e6a3330 commit 041add6

1 file changed

Lines changed: 112 additions & 18 deletions

File tree

README_CN.md

Lines changed: 112 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,70 @@
33
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
44
[![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen.svg)](https://www.python.org/)
55
[![Vue](https://img.shields.io/badge/Vue-3.x-4FC08D.svg)](https://vuejs.org/)
6+
[![LangGraph](https://img.shields.io/badge/LangGraph-1.x-FF6B6B.svg)](https://github.com/langchain-ai/langgraph)
67

7-
基于 DeepAgents + LangGraph + OpenSandbox GitHub 开源情报系统。
8+
基于 LangGraph + DeepAgents + OpenSandbox 的智能 GitHub 开源情报系统,实现自动化安全扫描、趋势分析和合规审计
89

910
**[English](./README.md)**
1011

1112
## 功能特性
1213

1314
- **技术趋势分析**: 分析组织仓库的 Star 增长趋势,识别高潜力项目
14-
- **安全风控分析**: 通过 OSV.dev API 扫描依赖漏洞(CVE),检测敏感信息泄露
15+
- **安全风险分析**: 通过 OSV.dev API 扫描依赖漏洞(CVE),检测敏感信息泄露
1516
- **社区健康分析**: 分析 Issue/PR 响应速度、贡献者活跃度
1617
- **合规审计分析**: 检查许可证合规性和版权声明
17-
- **实时预警**: 钉钉/飞书 Webhook 集成,高危风险实时推送
18+
- **实时预警**: 支持钉钉、飞书、Slack、Discord、Email 等多种通知渠道
1819
- **分层扫描**: L1(轻量/每日)→ L2(标准/触发)→ L3(深度/每周)
1920

21+
## 系统架构
22+
23+
```
24+
┌─────────────────────────────────────────────────────────────────┐
25+
│ 前端控制台 (Vue3) │
26+
│ 对话界面 │ 情报看板 │ 预警列表 │ 配置管理 │
27+
└─────────────────────────────────┬───────────────────────────────┘
28+
│ SSE 流式传输
29+
┌─────────────────────────────────▼───────────────────────────────┐
30+
│ FastAPI 服务层 │
31+
│ 流式对话 │ 扫描触发 │ 状态查询 │ 健康检查 │
32+
└─────────────────────────────────┬───────────────────────────────┘
33+
34+
┌─────────────────────────────────▼───────────────────────────────┐
35+
│ DeepAgents 主 Agent │
36+
│ ┌────────────┬────────────┬────────────┬────────────┐ │
37+
│ │ 趋势 │ 安全 │ 社区 │ 合规 │ │
38+
│ │ 分析师 │ 分析师 │ 分析师 │ 分析师 │ │
39+
│ └─────┬──────┴─────┬──────┴─────┬──────┴─────┬──────┘ │
40+
└─────────────────────────────────┬───────────────────────────────┘
41+
│ OpenSandbox 安全执行
42+
┌───────────────────────┼───────────────────────┐
43+
▼ ▼ ▼
44+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
45+
│ GitHub API │ │ OSV.dev API │ │ 预警 │
46+
│ │ │ (CVE数据) │ │ 渠道 │
47+
└─────────────┘ └─────────────┘ └─────────────┘
48+
```
49+
50+
## 技术栈
51+
52+
| 组件 | 技术 |
53+
|------|------|
54+
| **后端** | FastAPI, Python 3.12+ |
55+
| **前端** | Vue3, Vite |
56+
| **AI框架** | DeepAgents, LangChain, LangGraph |
57+
| **数据库** | MySQL 8.0+, Redis |
58+
| **沙箱** | OpenSandbox |
59+
| **调度** | APScheduler |
60+
2061
## 快速开始
2162

2263
### 前置要求
2364

2465
- Python 3.12+
2566
- Node.js 18+
2667
- MySQL 8.0+
27-
- Redis(可选,用于分布式锁)
68+
- Redis(可选,用于分布式部署)
69+
- GitHub Personal Access Token
2870

2971
### 1. 克隆项目
3072

@@ -36,52 +78,87 @@ cd github-osint-agent
3678
### 2. 配置环境变量
3779

3880
```bash
81+
# 复制配置模板
3982
cp .env.example .env
40-
# 编辑 .env 文件,填入:
83+
84+
# 编辑 .env 文件,填入你的凭证:
4185
# - GITHUB_TOKEN: GitHub Personal Access Token
4286
# - MYSQL_*: MySQL 连接配置
43-
# - LLM_*: LLM API 配置(OpenAI/Anthropic)
87+
# - LLM_*: 大模型 API 配置(OpenAI/Anthropic)
4488
```
4589

4690
### 3. 启动依赖服务
4791

4892
```bash
93+
# 使用 Docker Compose(推荐)
4994
docker-compose up -d
95+
96+
# 或手动启动 MySQL 和 Redis
5097
```
5198

5299
### 4. 安装依赖
53100

54101
```bash
102+
# Python 依赖
55103
pip install -r requirements.txt
56-
cd frontend && npm install && cd ..
104+
105+
# 前端依赖
106+
cd frontend
107+
npm install
108+
cd ..
57109
```
58110

59-
### 5. 启动服务
111+
### 5. 启动应用
60112

61113
```bash
114+
# 启动后端服务
62115
python run.py
116+
117+
# 启动前端开发模式
118+
cd frontend
119+
npm run dev
63120
```
64121

65-
访问 http://localhost:8000 查看界面。
122+
### 6. 访问应用
123+
124+
- 前端界面: http://localhost:5173
125+
- 后端 API: http://localhost:8000
126+
- API 文档: http://localhost:8000/docs
66127

67128
## API 接口
68129

69130
| 接口 | 方法 | 说明 |
70131
|------|------|------|
71-
| `/api/osint/chat/stream` | POST | SSE 流式对话 |
72-
| `/api/scanner/trigger` | POST | 触发扫描 |
73-
| `/api/scanner/status/{run_id}` | GET | 查询扫描状态 |
74-
| `/api/findings` | GET | 发现列表 |
132+
| `/api/osint/chat/stream` | POST | SSE 流式对话接口 |
133+
| `/api/scanner/trigger` | POST | 触发仓库扫描 |
134+
| `/api/scanner/status/{run_id}` | GET | 查询扫描任务状态 |
135+
| `/api/findings` | GET | 发现列表(分页筛选) |
75136
| `/api/orgs` | GET/POST | 组织配置管理 |
137+
| `/api/channel` | GET/POST | 告警渠道管理 |
138+
| `/health` | GET | 健康检查 |
76139

77-
## 扫描类型
140+
## 配置说明
141+
142+
### 扫描类型
78143

79144
| 类型 | 频率 | 覆盖范围 | 大模型调用 |
80145
|------|------|----------|-----------|
81146
| **L1 轻量** | 每日 | 全部仓库 ||
82147
| **L2 标准** | 触发时 | 高危仓库 | 中等 |
83148
| **L3 深度** | 每周 | Top 仓库 | 全量分析 |
84149

150+
### 告警渠道
151+
152+
| 渠道 | 区域 | 配置项 |
153+
|------|------|--------|
154+
| **钉钉** | 中国 | `DINGTALK_WEBHOOK`, `DINGTALK_SECRET` |
155+
| **飞书/Lark** | 中国 | `FEISHU_WEBHOOK` |
156+
| **Slack** | 国际 | `SLACK_WEBHOOK`, `SLACK_CHANNEL` |
157+
| **Discord** | 国际 | `DISCORD_WEBHOOK` |
158+
| **Email** | 国际 | `SMTP_HOST`, `SMTP_PORT`, `EMAIL_TO` |
159+
160+
`.env` 中配置一个或多个渠道。CRITICAL 和 HIGH 级别的告警会立即发送到所有已配置的渠道。
161+
85162
## 项目结构
86163

87164
```
@@ -92,17 +169,34 @@ github-osint-agent/
92169
│ ├── scanner/ # 扫描模块
93170
│ ├── tools/ # Agent 工具
94171
│ ├── routes/ # API 路由
172+
│ ├── database/ # 数据库操作
95173
│ └── alert/ # 预警通知
96174
├── frontend/ # Vue3 前端
97-
├── subagents/ # 子 Agent 配置
175+
│ └── src/
176+
│ ├── components/ # UI 组件
177+
│ └── styles/ # CSS 样式
178+
├── subagents/ # 子 Agent YAML 配置
98179
├── skills/ # 技能模块
99-
└── docker/ # Docker 配置
180+
├── docker/ # Docker 配置
181+
├── scripts/ # 工具脚本
182+
├── tests/ # 测试文件
183+
├── requirements.txt # Python 依赖
184+
├── docker-compose.yml # Docker Compose 配置
185+
├── pyproject.toml # 包配置
186+
├── Makefile # 便捷命令
187+
└── .env.example # 环境变量模板
100188
```
101189

102190
## 贡献指南
103191

104-
参见 [CONTRIBUTING.md](CONTRIBUTING.md)
192+
详见 [CONTRIBUTING.md](CONTRIBUTING.md)
105193

106194
## 许可证
107195

108-
Apache License 2.0,详见 [LICENSE](LICENSE) 文件。
196+
本项目采用 Apache License 2.0 许可证,详见 [LICENSE](LICENSE) 文件。
197+
198+
## 致谢
199+
200+
- [LangGraph](https://github.com/langchain-ai/langgraph) - Agent 编排框架
201+
- [OpenSandbox](https://github.com/alibaba) - 安全代码执行沙箱
202+
- [OSV.dev](https://osv.dev) - 开源漏洞数据库

0 commit comments

Comments
 (0)