kushalkumarj2006/repochat
GitHub: kushalkumarj2006/repochat
一个基于浏览器的代码库问答工具，通过克隆 GitHub 仓库并借助 GPU 加速运行的本地大模型，回答用户关于代码库的自然语言问题。
Stars: 0 | Forks: 0
# AskRepo · 代码库问答
[](https://github.com/kushalkumarj2006/repochat/blob/main/LICENSE)
[](https://kushalkumarj2006.github.io/repochat)
[](https://github.com/kushalkumarj2006/repochat/commits/main)
[](https://github.com/kushalkumarj2006/repochat)
## 概述
**AskRepo** 是一个简洁的、基于浏览器的聊天界面，它连接到 ColabBridge 后端来：
- **克隆**任何公开的 GitHub 仓库
- **索引**其文件和结构
- 使用 Ollama 的 `qwen2.5-coder:7b` 模型**回答**有关代码库的自然语言问题
它专为想要探索陌生仓库而无需手动深入代码的开发者、代码审查者和学习者设计。
## 功能
| 功能 | 描述 |
|---------|-------------|
| 🧠 **AI 驱动的问答** | 询问有关任何代码库的问题并获得上下文相关的答案 |
| ⚡ **两种模式** | *快速*（上下文感知）或 *简单*（通用知识） |
| 📦 **仓库支持** | 一键克隆任何公开的 GitHub 仓库 |
| 🔧 **Ollama 集成** | 通过 ColabBridge 后端在本地运行 `qwen2.5-coder:7b` |
| 💾 **会话管理** | 干净地启动、停止和结束会话 |
| 📊 **实时状态** | 实时单元格执行日志和索引进度 |
| 💬 **聊天记录持久化** | 所有对话按会话保存 |
| 🎨 **简洁 UI** | 深色主题，响应式设计，可折叠的设置面板 |
## 技术栈
| 层级 | 技术 |
|-------|------------|
| **前端** | 原生 HTML, CSS, JavaScript |
| **后端 (Bridge)** | Node.js + Express + Google Colab CLI |
| **AI 模型** | Ollama + `qwen2.5-coder:7b` |
| **部署** | Render (后端) + GitHub Pages (前端) |
| **认证** | 基于 API secret 的身份验证 |
## 架构
```
flowchart TB
subgraph Client["Client (Browser)"]
A[AskRepo UI]
end
subgraph Backend["ColabBridge API Server (Render)"]
B[Express.js Server]
C[Session Manager]
D[Colab CLI Wrapper]
end
subgraph Colab["Google Colab VM"]
E[Ollama Server]
F[qwen2.5-coder:7b Model]
G[Repository Files]
H[Python Execution Environment]
end
A -->|/start, /run, /status| B
B --> C
C --> D
D -->|colab new --gpu T4| E
D -->|colab exec| H
H --> F
H --> G
G -->|Indexing| H
F -->|Answers| H
H -->|Output| D
D -->|Response| B
B -->|JSON| A
```
## 仓库结构
该项目由**两个独立的仓库**组成，它们协同工作：
| 仓库 | 角色 | 技术 | 部署至 |
|------------|------|------------|-------------|
| **[repochat](https://github.com/kushalkumarj2006/repochat)** | 前端 UI | HTML, CSS, JavaScript | GitHub Pages / 本地 |
| **[ColabBridge](https://github.com/kushalkumarj2006/ColabBridge)** | 后端 API | Node.js, Express, Colab CLI | Render.com |
```
askrepo-project/
├── repochat/ # Frontend Repository
│ ├── index.html # Main UI page
│ ├── styles.css # Dark theme styles
│ ├── script.js # UI logic + API client
│ ├── LICENSE # MIT License
│ └── README.md # Project documentation
│
└── ColabBridge/ # Backend Repository
└── render/
├── server.js # Express API server
├── package.json # Node.js dependencies
├── .env # Configuration (not in repo)
└── .env.example # Template for .env
```
### 为什么使用两个独立的仓库？
| 原因 | 优势 |
|--------|---------|
| **关注点分离** | 前端和后端可以独立更新 |
| **不同的部署目标** | 前端 → 静态托管 (GitHub Pages)，后端 → 服务器 (Render) |
| **独立扩展** | 每个组件都可以针对自己的工作负载进行优化 |
| **API 复用性** | ColabBridge 可以服务多个前端 |
| **开发灵活性** | 不同的技术栈 (Node.js vs 原生 JS) |
## 工作流
```
sequenceDiagram
participant User
participant UI as AskRepo UI
participant API as ColabBridge API
participant Colab as Colab VM
User->>UI: Click "Start"
UI->>API: POST /start
API->>Colab: Create T4 GPU VM
Colab-->>API: Session ready
API-->>UI: sessionId
UI->>UI: Install Ollama, Pull model
User->>UI: Enter repo URL
UI->>API: POST /run (clone)
API->>Colab: Execute clone command
Colab-->>API: Repository cloned
API-->>UI: Cloning complete
UI->>API: POST /run (index)
API->>Colab: Execute indexing script
Colab-->>API: File structure + content
API-->>UI: Indexing complete
User->>UI: Ask question
UI->>API: POST /run (ask)
API->>Colab: Execute ask_fast() / ask_simple()
Colab-->>API: LLM response
API-->>UI: Answer displayed
User->>UI: Click "End Session"
UI->>API: DELETE /session/:id
API->>Colab: Stop VM
Colab-->>API: VM terminated
API-->>UI: Session ended
```
## 使用的 API 端点
| 方法 | 端点 | 用途 |
|--------|----------|---------|
| `POST` | `/start` | 使用 T4 GPU 创建新的 Colab 会话 |
| `POST` | `/run` | 在会话中执行 Python 代码 |
| `POST` | `/status` | 检查执行进度 |
| `DELETE` | `/session/:sessionId` | 终止会话并释放资源 |
## 安装与设置
### 1. 克隆两个仓库
```
# 克隆前端 (AskRepo UI)
git clone https://github.com/kushalkumarj2006/repochat.git
cd repochat
# 克隆后端 (ColabBridge API)
git clone https://github.com/kushalkumarj2006/ColabBridge.git
cd ColabBridge/render
```
### 2. 配置后端 (ColabBridge)
```
cd ColabBridge/render
npm install
```
创建一个 `.env` 文件：
```
# 认证
API_SECRET=your-secret-key-here
COLAB_AUTH_TOKEN='{"token": "ya29...", "refresh_token": "1//...", ...}'
# 服务器
PORT=3000
NODE_ENV=development
LOG_LEVEL=info
DEBUG_ENABLED=true
# 会话
MAX_SESSIONS=3
SESSION_TIMEOUT=10800000 # 3 hours
SESSIONS_BASE_DIR=/tmp/colab_sessions
PERSIST_SESSION_DATA=true
CLEANUP_INTERVAL=3600000 # 1 hour
# 执行
EXECUTION_TIMEOUT=7200 # 2 hours
MAX_CODE_SIZE=3145728 # 3 MB
MAX_CODE_LENGTH=100000
MAX_RETRY_ATTEMPTS=3
STREAMING_ENABLED=true
# 其他
COMPLETED_EXECUTIONS_TTL=1200000 # 20 minutes
POLL_INTERVAL=10000 # 10 seconds
HANGING_PROCESS_CLEANUP_INTERVAL=900000 # 15 minutes
```
### 3. 认证 Google Colab
```
# 安装 Colab CLI
pip3 install google-colab-cli
# 认证（打开浏览器进行 OAuth）
colab sessions
# 获取 token
cat ~/.config/colab-cli/token.json
# 将整个 JSON 内容复制到 .env 中的 COLAB_AUTH_TOKEN
```
token JSON 应如下所示：
```
{
"token": "ya29.a0AT...........mKcA0206",
"refresh_token": "1//0g4sU.............vhxoCU5Xs",
"token_uri": "https://oauth2.googleapis.com/token",
"client_id": "764086............di341hur.apps.googleusercontent.com",
"client_secret": "d-FL9...........HD0Ty",
"scopes": ["openid", "https://www.googleapis.com/auth/userinfo.profile", ...],
"universe_domain": "googleapis.com",
"account": "",
"expiry": "2026-06-16T10:40:31.096124Z"
}
```
### 4. 启动后端
```
# 从 ColabBridge/render 目录
npm start
```
你应该会看到：
```
🚀 Colab Orchestrator v2.1 running on port 3000
📁 Sessions folder: /tmp/colab_sessions
🔧 Colab binary: python3 (-m colab_cli)
📊 Max sessions: 3
🔐 API Secret: your-secret-key-here
🔑 Colab Auth: ✅ Token configured
```
### 5. 打开前端
前端是一个静态的 HTML 页面。你可以通过以下方式打开它：
**选项 A：直接打开（最简单）**
```
# 从 repochat 目录
open index.html # Mac
start index.html # Windows
xdg-open index.html # Linux
```
**选项 B：使用本地服务器运行**
```
# 从 repochat 目录
npx serve .
# 或
python3 -m http.server 8000
```
然后在浏览器中打开 `http://localhost:8000`。
**选项 C：部署到 GitHub Pages**
1. 将 `repochat` 仓库推送到 GitHub
2. 在仓库设置中启用 GitHub Pages
3. 通过 `https://kushalkumarj2006.github.io/repochat` 访问
### 6. 将前端连接到后端
在浏览器控制台 (F12) 中，设置你的 API 密钥：
```
key("your-secret-key-here")
```
前端已预配置为连接到：
```
https://colabbridge-jyba.onrender.com
```
如果在本地运行，请更新 `script.js` 中的 `BACKEND_URL`：
```
const BACKEND_URL = 'http://localhost:3000';
```
### 7. 开始使用 AskRepo
1. 点击 **"☰"** 展开设置面板
2. 点击 **"▶ Start"** 创建 Colab 会话
3. 等待 Ollama 安装和模型拉取（约 5-10 分钟）
4. 输入一个仓库（例如，`kushalkumarj2006/colab-orchestrator`）
5. 点击 **"✅"** 确认并克隆
6. 等待索引完成
7. 提问关于代码库的问题！
## 使用指南
### 启动会话
1. 点击 **"☰"** 展开设置面板
2. 点击 **"▶ Start"** 创建 Colab 会话
3. 等待 Ollama 安装和模型拉取（约 5-10 分钟）
### 克隆仓库
1. 输入一个 GitHub 仓库（例如，`kushalkumarj2006/colab-orchestrator`）
2. 点击 **"✅"** 确认
3. 仓库将被自动克隆并索引
### 提问
| 模式 | 描述 |
|------|-------------|
| **⚡ 快速** | 扫描仓库文件，寻找相关上下文，并带有文件引用地回答问题 |
| **💬 简单** | 仅使用模型的通用知识（更快，无代码库上下文） |
示例：
- "`orchestrator.py` 文件有什么作用？"
- "这个项目中的身份验证是如何工作的？"
- "数据库连接在哪里配置？"
- "解释 `server.js` 中的主函数"
- "这个项目使用了哪些依赖？"
### 聊天记录
- **所有对话都会自动保存**，按会话存储
- 记录在浏览器刷新后依然存在
- 每个会话维护各自的聊天上下文
- 通过 `/sessions` API 端点访问完整记录
### 结束会话
点击 **"✕ End"** 以终止 Colab 虚拟机并释放资源。
## 索引与问答实现
### 文件索引
```
extensions = ['*.py', '*.js', '*.json', '*.yaml', '*.yml', '*.md', '*.txt', '*.sh', '*.html', '*.css']
for ext in extensions:
for file_path in repo_path.rglob(ext):
content = file_path.read_text(encoding='utf-8', errors='ignore')
file_contents[rel_path] = content.split('\n')
```
### 相关性评分
- 为了速度，仅扫描每个文件的**前 50 行**
- 同时检查文件路径和内容以匹配关键词
- 返回**前 4 个**相关文件
### 关键词扩展
```
mappings = {
'login': ['login', 'sign in', 'auth', 'authenticate', 'credentials'],
'auth': ['auth', 'authentication', 'authorization', 'jwt', 'session'],
'api': ['api', 'endpoint', 'route', 'express'],
'database': ['database', 'db', 'mongodb', 'mongoose', 'schema'],
'user': ['user', 'users', 'profile', 'account'],
'server': ['server', 'app', 'express', 'node', 'backend'],
}
```
### 上下文构建
- 提取匹配行 + 周围上下文（前后各 5 行）
- 限制为每个文件最多 **10 个**匹配和最多 **8 个**代码块
- 为了性能，将上下文截断为 **4000 个字符**
### 缓存
```
cache = {}
def get_cached_answer(question, context_hash):
key = f"{question[:50]}_{context_hash[:20]}"
return cache.get(key)
```
## 聊天记录持久化
### 工作原理
```
flowchart LR
subgraph Frontend["Frontend (Browser)"]
UI[AskRepo UI]
Memory[Browser Memory]
end
subgraph Backend["ColabBridge Backend"]
Session[Session Manager]
Storage[(session_data.json)]
end
UI -->|Save messages| Session
Session -->|Persist to disk| Storage
Storage -->|Restore on reconnection| Session
Session -->|Load history| UI
Memory -->|Temporary cache| UI
```
### 数据结构
```
{
"sessionId": "a1b2c3d4e5f6...",
"createdAt": "2026-06-17T10:00:00.000Z",
"cells": [
{
"type": "execution",
"cellNo": 1,
"code": "print('Hello World')",
"output": "Hello World\n",
"startedAt": "2026-06-17T10:01:00.000Z",
"completedAt": "2026-06-17T10:01:02.000Z",
"status": "completed"
},
{
"type": "execution",
"cellNo": 2,
"code": "ask_fast('What does main.py do?')",
"output": "The main.py file handles...",
"startedAt": "2026-06-17T10:05:00.000Z",
"completedAt": "2026-06-17T10:05:15.000Z",
"status": "completed"
}
],
"totalCells": 2,
"totalExecutions": 2
}
```
### 访问记录
```
# 查看所有会话
curl https://colabbridge-jyba.onrender.com/sessions
# 获取特定会话的详细历史记录
curl https://colabbridge-jyba.onrender.com/sessions/a1b2c3d4
```
## UI 功能
| 组件 | 描述 |
|-----------|-------------|
| **页眉** | 应用标题，会话徽章，结束按钮 |
| **设置面板** | 可折叠的网格，包含启动/停止控制、仓库输入、执行日志 |
| **步骤指示器** | 可视化进度跟踪 (⏳ → 进行中 → ✅ 完成) |
| **单元格输出** | 来自 Colab 虚拟机的实时日志 |
| **聊天消息** | 带有标签和流式指示器的用户/机器人气泡 |
| **问题输入框** | 文本输入框 + "快速" / "简单" 按钮 |
| **状态栏** | 当前会话状态 (需要设置 / 就绪 / 思考中) |
## 环境变量
| 变量 | 描述 | 默认值 | 是否必须 |
|----------|-------------|---------|----------|
| `API_SECRET` | API 身份验证密钥 | - | ✅ 是 |
| `COLAB_AUTH_TOKEN` | Google Colab OAuth token (JSON) | - | ✅ 是 |
| `PORT` | 服务器端口 | 3000 | 否 |
| `NODE_ENV` | 环境模式 | development | 否 |
| `LOG_LEVEL` | 日志详细程度 | info | 否 |
| `MAX_SESSIONS` | 最大并发会话数 | 3 | 否 |
| `SESSION_TIMEOUT` | 会话空闲超时 (毫秒) | 3 小时 | 否 |
| `EXECUTION_TIMEOUT` | 代码执行超时 (秒) | 7200 | 否 |
| `MAX_CODE_SIZE` | 最大代码大小 (字节) | 3 MB | 否 |
| `COMPLETED_EXECUTIONS_TTL` | 历史记录保留时间 (毫秒) | 20 分钟 | 否 |
| `POLL_INTERVAL` | 状态轮询间隔 (毫秒) | 10 秒 | 否 |
## 安全性
- **API Secret**：所有请求都需要一个密钥（通过控制台中的 `key()` 设置）
- **CORS**：将来源限制为已知的前端域名
- **会话隔离**：每个会话都有各自的 Colab 虚拟机和存储
- **清理**：会话在空闲超时后自动终止
## 常见设置问题及解决方案
| 问题 | 解决方案 |
|-------|----------|
| **"No API key" 错误** | 在浏览器控制台运行 `key("your-secret")` |
| **后端未启动** | 检查 `COLAB_AUTH_TOKEN` 是否有效且未过期 |
| **CORS 错误** | 更新 `server.js` 中的 `allowedOrigins` 以包含你的前端 URL |
| **会话创建失败** | Colab CLI 可能需要重新认证：`colab sessions` |
| **前端无法连接到后端** | 检查 `script.js` 中的 `BACKEND_URL` 是否与你的后端 URL 匹配 |
| **模型拉取超时** | 检查网络连接、Colab 虚拟机资源 |
| **未找到仓库** | 确保仓库是公开的，并且 URL 格式正确 |
| **响应缓慢** | 使用 "简单" 模式以获得更快的、无需上下文的答案 |
## 未来改进
- [ ] 支持私有仓库（SSH/HTTPS 认证）
- [ ] 多模型支持（Llama, Mistral 等）
- [ ] 导出聊天会话（JSON/PDF/Markdown）
- [ ] 文件浏览器集成
- [ ] 答案中的代码片段高亮
- [ ] LLM 响应的实时流式传输
- [ ] 搜索聊天记录
- [ ] 删除/清除单条消息
- [ ] 会话重命名/打标签
- [ ] 为重要问题添加书签
## 贡献
欢迎贡献！请随时提交 Pull Request。
1. Fork 该仓库
2. 创建你的功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到该分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request
## 许可证
MIT 许可证 — 详见 [LICENSE](LICENSE)。
## 致谢
- [Google Colab CLI](https://github.com/googlecolab/google-colab-cli)
- [Ollama](https://ollama.com/)
- [Qwen2.5-Coder](https://ollama.com/library/qwen2.5-coder)
- [Render](https://render.com/)
- [Express.js](https://expressjs.com/)
## 作者
**Kushal Kumar J**
- GitHub: [@kushalkumarj2006](https://github.com/kushalkumarj2006)
- 项目: [AskRepo](https://github.com/kushalkumarj2006/repochat)
- 后端: [ColabBridge](https://github.com/kushalkumarj2006/ColabBridge)
**AskRepo · 代码库问答**
[](https://github.com/kushalkumarj200/repochat)
[](https://colabbridge-jyba.onrender.com/health)
标签：AI问答, AI风险缓解, DLL 劫持, GNU通用公共许可证, LLM评估, MITM代理, Node.js, Ollama, SOC Prime, 代码库分析, 多模态安全, 大语言模型, 开发工具, 数据可视化, 自定义脚本, 逆向工具