- Python 3.10+
- LangChain 1.0：只用 langchain_core, langchain_openai, langchain_ollama 等现代包
- LangGraph（StateGraph 构建工作流）
- LangSmith（基础 tracing）
- py2neo（Neo4j 连接）
- rapidfuzz + pyahocorasick（实体归一化，保留原有实现）
- FastAPI + Uvicorn（Web API）
- React 19 + TypeScript + Vite + Tailwind CSS 4（前端）
- 禁止使用
from langchain import ...或已弃用的Chain/Agent。 - 所有 LLM 调用使用
invoke/ainvoke，通过settings.py的工厂函数获取模型。 - LangGraph 工作流必须定义清晰的状态类型（TypedDict），节点函数纯函数风格。
- 保留现有的实体词典和 Cypher 模板，不要试图用 LLM 替代。
- 代码必须能独立运行，注释中文，异常处理友好。
- 遵循 PEP 8 规范
- 使用 4 空格缩进（见
.editorconfig） - 行宽 ≤ 100 字符（与 ruff/pyproject.toml 保持一致）
- 导入顺序：标准库 → 第三方 → 本地模块
- 类型注解：函数签名必须标注参数和返回值类型
- 文档字符串：使用 Google 风格 docstring
- 命名：
- 模块/包：
snake_case - 类：
PascalCase - 函数/方法/变量：
snake_case - 常量：
UPPER_SNAKE_CASE
- 模块/包：
- 使用 2 空格缩进（见
.editorconfig） - 组件：
PascalCase，文件名与组件名一致 - Hooks：
camelCase，以use开头 - 类型/接口：
PascalCase，优先使用interface - 常量：
UPPER_SNAKE_CASE或camelCase - 使用函数组件 + Hooks，禁止 class 组件
- 编码：UTF-8
- 换行符：LF（
\n） - 文件末尾保留一个空行
- 去除行尾空白字符
<type>(<scope>): <subject>
<body>
<footer>
常用 type：
feat: 新功能fix: 修复 Bugrefactor: 重构docs: 文档更新test: 测试相关chore: 构建/工具/依赖style: 代码格式（不影响功能）perf: 性能优化
示例：
feat(qa_engine): 新增 GraphRAG 超时降级机制
当子图检索超过 30 秒时自动回退到 LLM 直接回答，
避免用户长时间等待。
Closes #42
main：稳定发布分支，禁止直接提交develop：开发分支feat/<功能名>：新功能分支fix/<问题描述>：修复分支
- 严禁提交
.env、密钥文件、凭证到仓库 .env.example提供模板，不含真实密钥- 敏感配置一律通过环境变量注入
- 定期审查依赖安全性（
pip-audit/npm audit）