一个基于 LangChain 和 OpenAI 的智能文档问答系统，专为 Joern 代码分析平台打造。支持多轮对话、上下文记忆，帮助你深入理解 Joern 的功能和用法。
- 完整文档索引：递归抓取 Joern 官方文档的所有页面（30-100+ 页）
- 语义搜索：基于向量相似度的智能检索，而非简单的关键词匹配
- 准确回答：结合检索到的文档上下文，生成专业、准确的答案
- 上下文记忆：AI 能记住之前的对话，支持逐步深入探讨
- 连贯交互：可以使用"它"、"这个"等指代词，AI 能理解上下文
- 主动引导：AI 会根据对话历史，主动询问用户是否需要进一步了解
- 聊天界面：类似 ChatGPT 的对话体验
- 实时反馈：显示抓取进度、构建状态、对话统计
- 示例问题：内置常见问题，一键填入
- 对话管理：清空历史、查看统计等便捷功能
| 组件 | 技术选型 | 用途 |
|---|---|---|
| 前端界面 | Streamlit | Web 应用框架 |
| LLM | OpenAI GPT-4o-mini | 大语言模型 |
| RAG 框架 | LangChain | 检索增强生成 |
| 向量数据库 | Chroma (langchain-chroma) | 文档向量存储与检索 |
| 文档抓取 | BeautifulSoup + Requests | 递归抓取文档页面 |
| 文本分割 | RecursiveCharacterTextSplitter | 文档分块 |
| 环境管理 | Conda | Python 环境隔离 |
- Python: 3.10 或更高版本
- Conda: Anaconda 或 Miniconda
- OpenAI API Key: 从 OpenAI Platform 获取
git clone https://github.com/your-username/doc-agent-app.git
cd doc-agent-app# 创建环境（Python 3.10）
conda create -n joern-docs python=3.10 -y
# 激活环境
conda activate joern-docspip install -r requirements.txt# 复制示例脚本
Copy-Item start_app.example.ps1 start_app.ps1 # Windows
cp start_app.example.ps1 start_app.ps1 # Linux/Mac
# 编辑脚本，填入你的 OpenAI API Key
notepad start_app.ps1 # Windows
nano start_app.ps1 # Linux/Mac在脚本中找到第 20 行，替换为你的 API Key：
$env:OPENAI_API_KEY = "sk-proj-你的完整Key"# Windows PowerShell
.\start_app.ps1
# 如果遇到执行策略问题
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\start_app.ps1# Linux/Mac (需要先修改为 bash 脚本)
export OPENAI_API_KEY="sk-proj-你的Key"
streamlit run joern_doc_agent_app.py- 浏览器自动打开
http://localhost:8501 - 点击左侧 "🚀 开始抓取并构建" 按钮
- 等待构建完成（约 3-5 分钟）
- 开始提问！
用户: Joern 是什么？
AI: Joern 是一个代码分析平台，用于分析源代码、字节码和二进制代码...
用户: 它支持哪些编程语言？
AI: Joern 支持 C/C++、Java、JavaScript、Python、x86/x64 等 12 种语言...
用户: Code Property Graph 是什么？
AI: CPG 是一种图表示，将代码的多种抽象层次整合到一个统一的数据结构中...
用户: 它包含哪些节点类型？
AI: (理解"它"指 CPG) CPG 主要包含以下节点类型：1. AST 节点...
用户: 这些节点之间的边表示什么？
AI: (继续基于上下文) 边表示节点之间的关系，主要有三类...
- 清空对话：点击侧边栏 "🗑️ 清空对话" 重新开始
- 示例问题：点击预设问题快速提问
- 对话统计：查看已进行的轮数
doc-agent-app/
├── joern_doc_agent_app.py # 主程序（Streamlit 应用）
├── requirements.txt # Python 依赖列表
├── start_app.example.ps1 # 启动脚本模板
├── start_app.ps1 # 实际启动脚本（包含 API Key，被 .gitignore 忽略）
├── .gitignore # Git 忽略配置
├── README.md # 项目文档（本文件）
├── 重建知识库指南.md # 知识库重建说明
└── joern_docs_db/ # 向量数据库（自动生成）
└── chroma.sqlite3
| 变量名 | 说明 | 必需 |
|---|---|---|
OPENAI_API_KEY |
OpenAI API 密钥 | ✅ |
USER_AGENT |
HTTP User-Agent（可选） | ❌ |
start_app.ps1 会自动完成：
- ✅ 设置 API Key 环境变量
- ✅ 激活 Conda 环境
- ✅ 切换到项目目录
- ✅ 启动 Streamlit 应用
错误: 无法加载文件，因为在此系统上禁止运行脚本
解决:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\start_app.ps1错误: AuthenticationError: account_deactivated
原因: API Key 无效或账户被停用
解决:
- 登录 OpenAI Platform
- 检查账户余额
- 生成新的 API Key
- 更新
start_app.ps1中的密钥
问题: AI 只能回答部分问题（如只知道快速入门）
原因: 知识库未包含完整文档
解决:
- 删除旧数据库：
Remove-Item -Recurse -Force .\joern_docs_db\ - 重启应用并点击 "🔄 重新构建知识库"
- 确认抓取到 30-100 个页面（查看构建日志）
参考：重建知识库指南.md
错误: 无法解析导入 "langchain_chroma"
解决:
pip install langchain-chroma>=0.1.0修改 joern_doc_agent_app.py 中的 crawl_joern_docs 函数：
def crawl_joern_docs(base_url="https://your-custom-docs.io"):
# 自定义抓取逻辑
pass修改 Agent 创建时的检索数量：
retriever = db.as_retriever(search_kwargs={"k": 5}) # 从 3 改为 5llm = ChatOpenAI(
model_name="gpt-4", # 使用更强大的 GPT-4
temperature=0,
openai_api_key=api_key
)- 时间: 3-5 分钟
- 抓取页面: 30-100 个
- 向量化: ~1000-2000 个文档块
- 数据库大小: ~10-50 MB
- 响应时间: 2-5 秒（包括检索 + LLM 生成）
- 内存占用: ~500 MB（向量数据库加载到内存）
欢迎贡献！请遵循以下步骤：
- Fork 本项目
- 创建功能分支：
git checkout -b feature/amazing-feature - 提交更改：
git commit -m 'Add amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 提交 Pull Request
- 遵循 PEP 8
- 使用中文注释
- 函数要有清晰的 docstring
- 优先简洁明了的实现
本项目采用 MIT 许可证 - 详见 LICENSE 文件
- 问题反馈: 提交 GitHub Issue
- 功能建议: 提交 Feature Request
- ✅ 完整的文档抓取（递归爬虫）
- ✅ 多轮对话支持（上下文记忆）
- ✅ 现代化聊天界面
- ✅ 示例问题和对话管理
- ✅ Windows PowerShell 启动脚本
- ✅ 完整的错误处理和用户反馈
⭐ 如果这个项目对你有帮助，请给个 Star！
Made with ❤️ and Python