# 纲担 (GangDan) - 离线开发助手

基于 [Ollama](https://ollama.ai/) 和 [ChromaDB](https://www.trychroma.com/) 的本地离线编程助手。支持 LLM 对话、向量知识库检索、终端命令执行、AI 命令生成等功能，全部在浏览器中完成。

> **纲担** -- 有纲领有担当。

![聊天面板](images/chat.png)

## 功能特性

- **RAG 智能对话** -- 支持从本地 ChromaDB 知识库和/或网络搜索（DuckDuckGo、SearXNG、Brave）中检索相关内容，通过 SSE 实时流式输出回复。
- **AI 命令助手** -- 用自然语言描述需求，AI 自动生成 Shell 命令，支持拖拽到终端、一键执行并自动总结结果。
- **内置终端** -- 在浏览器中直接执行命令，显示 stdout/stderr 输出。
- **文档管理器** -- 一键下载和索引 25+ 种热门库文档（Python、Rust、Go、JS、C/C++、CUDA、Docker 等）。支持批量操作和 GitHub 仓库搜索。
- **10 种语言界面** -- 支持中文、英语、日语、法语、俄语、德语、意大利语、西班牙语、葡萄牙语、韩语，切换语言无需刷新页面。
- **代理支持** -- 提供无代理 / 系统代理 / 手动代理三种模式，适用于聊天后端和文档下载。
- **离线优先** -- 完全在本地运行，无需任何云端 API。

## 界面截图

| 聊天 | 终端 |
|:----:|:----:|
| ![聊天](images/chat.png) | ![终端](images/terminal.png) |

| 文档管理 | 设置 |
|:--------:|:----:|
| ![文档](images/documents.png) | ![设置](images/setting.png) |

## 环境要求

- Python 3.10+
- [Ollama](https://ollama.ai/) 本地运行（默认 `http://localhost:11434`）
- 已拉取聊天模型（如 `ollama pull qwen2.5`）
- 已拉取嵌入模型用于 RAG（如 `ollama pull nomic-embed-text`）

## 快速开始

```bash
# 1. 进入项目目录
cd gangdan

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 确保 Ollama 正在运行
ollama serve

# 4. 启动纲担
python app.py
```

在浏览器中打开 [http://127.0.0.1:5000](http://127.0.0.1:5000) 即可使用。

## 项目结构

```
gangdan/
├── app.py                  # Flask 后端（路由、Ollama 客户端、ChromaDB、国际化）
├── requirements.txt        # Python 依赖
├── templates/
│   └── index.html          # Jinja2 HTML 模板
├── static/
│   ├── css/
│   │   └── style.css       # 应用样式（暗色主题）
│   └── js/
│       ├── i18n.js          # 国际化与状态管理
│       ├── utils.js         # 面板切换与通知
│       ├── markdown.js      # Markdown / LaTeX (KaTeX) 渲染
│       ├── chat.js          # 聊天面板与 SSE 流式传输
│       ├── terminal.js      # 终端与 AI 命令助手
│       ├── docs.js          # 文档下载与索引
│       └── settings.js      # 设置面板与初始化
├── images/                 # 运行截图
└── data/                   # 运行时自动创建
    ├── gangdan_config.json # 持久化配置
    ├── docs/               # 下载的文档
    └── chroma/             # ChromaDB 向量数据库
```

## 架构设计

前后端完全解耦：

- **后端**（`app.py`）-- 单个 Python 文件，包含 Flask 路由、Ollama 客户端、ChromaDB 管理器、文档下载器、网络搜索器和对话管理器。服务端配置通过 `window.SERVER_CONFIG` 注入模板。
- **前端**（`templates/` + `static/`）-- 纯 HTML/CSS/JS，无需构建步骤。JavaScript 文件按依赖顺序加载，通过全局函数共享状态。LaTeX 渲染使用 CDN 加载的 KaTeX。

ChromaDB 初始化具有自动故障恢复机制：如果数据库损坏，会自动备份并重新创建。

## 配置说明

所有设置均可通过界面中的**设置**标签页管理：

| 设置项 | 说明 |
|--------|------|
| Ollama 地址 | Ollama 服务地址（默认 `http://localhost:11434`） |
| 聊天模型 | 对话使用的模型（如 `qwen2.5:7b-instruct`） |
| 嵌入模型 | RAG 嵌入模型（如 `nomic-embed-text`） |
| 重排序模型 | 可选的重排序模型，提升搜索质量 |
| 代理模式 | `无代理` / `系统代理` / `手动代理` |

配置保存在 `data/gangdan_config.json` 文件中。

## 许可证

本项目仅供个人学习和研究使用。
