Stelquis · Stelquis · Apr 8, 2026 · Apr 8, 2026 · Apr 8, 2026 · Apr 8, 2026
diff --git a/.coverage b/.coverage
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,216 @@
+# 贡献指南
+
+> **AI 时代你的第二大脑**
+
+感谢你对 ByteBrain 项目感兴趣！
+
+---
+
+## 开发环境设置
+
+### 1. 克隆仓库
+```bash
+git clone https://github.com/your-username/ByteBrain.git
+cd ByteBrain
+```
+
+### 2. 创建虚拟环境
+```bash
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# 或
+venv\Scripts\activate  # Windows
+```
+
+### 3. 安装依赖
+```bash
+# 安装开发依赖
+make install-dev
+
+# 验证安装
+python -m pytest tests/unit/ -v
+```
+
+---
+
+## 开发工作流
+
+### 1. 创建分支
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. 编写代码
+- 遵循项目的 [代码规范](#代码规范)
+- 添加必要的类型注解
+- 编写单元测试
+- 确保代码符合 ByteBrain 的设计哲学
+
+### 3. 运行测试
+```bash
+# 运行单元测试
+make test-unit
+
+# 运行集成测试
+make test-integration
+
+# 运行所有测试
+make test
+```
+
+### 4. 代码质量检查
+```bash
+# 格式化代码
+make format
+
+# 运行代码检查
+make lint
+```
+
+### 5. 提交代码
+```bash
+git add .
+git commit -m "feat: 描述你的变更"
+git push origin feature/your-feature-name
+```
+
+### 6. 创建 Pull Request
+在 GitHub 上创建 PR，填写 PR 模板
+
+---
+
+## 代码规范
+
+### Python 代码
+- **PEP 8 标准**：遵循 PEP 8 代码风格指南
+- **类型提示**：使用 Python 类型提示增强代码可读性和IDE支持
+- **命名规范**：
+  - 类名：使用 `CamelCase`
+  - 函数和变量：使用 `snake_case`
+  - 常量：使用 `UPPERCASE_WITH_UNDERSCORES`
+  - 私有属性和方法：使用 `_single_leading_underscore`
+- **文档字符串**：使用 Google 风格的文档字符串
+- **格式化工具**：使用 Black 格式化代码
+- **代码检查**：遵循 Flake8 检查
+
+### 文档
+- 使用 Markdown 格式
+- 代码示例要可运行
+- 英文术语首字母大写
+- 保持与 README.md 风格一致
+
+---
+
+## 提交信息规范
+
+使用 Conventional Commits 格式：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+Type 类型：
+- **feat**: 新功能
+- **fix**: 修复 bug
+- **docs**: 文档变更
+- **style**: 代码格式（不影响功能）
+- **refactor**: 重构
+- **test**: 测试相关
+- **chore**: 构建/工具相关
+
+---
+
+## 项目架构
+
+ByteBrain 采用分层架构设计：
+
+```
+bytebrain/
+├── core/               # 核心模块
+│   ├── agent.py        # Agent 核心逻辑
+│   ├── rag.py          # RAG 核心逻辑
+│   └── workflow.py     # 工作流定义
+├── skills/             # Skill 系统
+│   ├── knowledge-retrieval/  # 知识检索技能
+│   ├── code-coaching/        # 代码教练技能
+│   └── concept-explanation/  # 概念解释技能
+├── guardrails/         # 防护系统
+│   ├── input_guard.py  # 输入防护
+│   ├── output_guard.py # 输出防护
+│   └── behavior_guard.py # 行为防护
+├── prompts/            # Prompt 系统
+│   ├── system/         # 系统提示
+│   └── skill/          # 技能提示
+├── ui/                 # UI 模块
+│   └── streamlit_app.py # Streamlit 应用
+└── utils/              # 工具模块
+    ├── config.py       # 配置管理
+    └── logger.py       # 日志管理
+```
+
+---
+
+## 技术栈
+
+| 技术 | 用途 | 版本 |
+|------|------|------|
+| **LangGraph** | Agent 工作流编排 | 0.3+ |
+| **LlamaIndex** | RAG 框架 | 0.10+ |
+| **MCP** | 数据源连接协议 | 2024-11-05 |
+| **Qdrant/Chroma** | 向量数据库 | 1.5+ |
+| **Streamlit** | Web UI | 1.30+ |
+| **Python** | 开发语言 | 3.12+ |
+
+---
+
+## 问题报告
+
+使用 Issue 模板报告 Bug 或请求新功能：
+- **Bug 报告**：使用 [bug_report.md](ISSUE_TEMPLATE/bug_report.md) 模板
+- **功能请求**：使用 [feature_request.md](ISSUE_TEMPLATE/feature_request.md) 模板
+- **文档问题**：使用 [documentation.md](ISSUE_TEMPLATE/documentation.md) 模板
+
+---
+
+## 行为准则
+
+我们希望这个社区是包容和友好的。请尊重其他贡献者，遵循以下原则：
+- 保持友善和尊重的沟通
+- 接受建设性的批评
+- 关注问题本身，而不是人
+- 共同努力创造积极的社区环境
+
+---
+
+## 获取帮助
+
+如有问题，请：
+1. 查看 [README.md](../../README.md) 文档
+2. 搜索现有 Issue
+3. 创建新 Issue
+
+---
+
+## 贡献者指南
+
+### 核心贡献领域
+- **Agent 开发**：扩展和改进 Agent 系统
+- **Skill 开发**：创建新的技能和功能
+- **RAG 优化**：改进检索和生成系统
+- **Guardrails**：增强安全防护机制
+- **UI 改进**：提升用户界面体验
+- **文档完善**：改进和扩展文档
+
+### 首次贡献
+如果你是首次贡献，建议从以下方面入手：
+- 修复文档中的拼写错误或格式问题
+- 为现有功能添加测试
+- 实现小型的功能改进
+
+---
+
+**再次感谢你的贡献！ByteBrain 因你而更强大！**
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,52 @@
+# Bug 报告
+
+> **AI 时代你的第二大脑**
+
+## 描述 Bug
+请清晰简洁地描述这个 bug，包括它发生的上下文和影响。
+
+## 复现步骤
+1. 步骤一
+2. 步骤二
+3. 步骤三
+
+## 预期行为
+你期望的正常行为是什么？
+
+## 实际行为
+实际发生了什么？
+
+## 环境信息
+- **操作系统**：
+- **Python 版本**：
+- **ByteBrain 版本**：
+- **依赖包版本**：
+- **向量数据库**：
+- **LLM 模型**：
+
+## 截图或日志
+如果可以的话，请提供截图或错误日志。
+
+```
+# 错误日志
+```
+
+## 复现环境
+- [ ] 本地开发环境
+- [ ] 生产环境
+- [ ] 其他环境：
+
+## 严重程度
+- [ ] 阻塞性（无法使用）
+- [ ] 高（影响主要功能）
+- [ ] 中（影响次要功能）
+- [ ] 低（轻微影响）
+
+## 可能的原因
+你认为可能的原因是什么？
+
+## 建议的解决方案
+你有什么建议的解决方案吗？
+
+## 其他信息
+任何其他相关信息。
diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md
@@ -0,0 +1,13 @@
+# 文档问题
+
+## 文档位置
+哪个文档有问题？
+
+## 问题描述
+请描述文档中的问题或不清楚的地方。
+
+## 建议的修改
+你希望如何修改？
+
+## 额外信息
+任何其他相关信息。
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,37 @@
+# 功能请求
+
+> **AI 时代你的第二大脑**
+
+## 功能描述
+请清晰简洁地描述你想要的功能，包括它的用途和预期效果。
+
+## 解决的问题
+这个功能能解决什么问题？为什么这个问题重要？
+
+## 建议的解决方案
+你希望如何实现这个功能？包括技术方案和实现思路。
+
+## 替代方案
+你考虑过其他解决方案吗？它们的优缺点是什么？
+
+## 预期行为
+这个功能的预期行为是什么？
+
+## 用例示例
+请提供一个或多个使用示例，说明这个功能如何被使用。
+
+## 技术要求
+- **所需技术**：
+- **依赖项**：
+- **兼容性**：
+
+## 优先级
+- [ ] 高（重要功能）
+- [ ] 中（有用功能）
+- [ ] 低（增强功能）
+
+## 额外背景
+任何其他相关信息、截图或示例。
+
+## 参考资料
+如果有相关的文档、代码或其他参考资料，请提供链接。
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,56 @@
+# Pull Request 模板
+
+> **AI 时代你的第二大脑**
+
+## 描述
+请简要描述这个 PR 的内容，包括解决的问题和实现的功能。
+
+## 类型
+- [ ] 🐛 Bug 修复
+- [ ] ✨ 新功能
+- [ ] 🔄 代码重构
+- [ ] 📚 文档更新
+- [ ] 🔧 其他（请描述）：
+
+## 变更列表
+- [ ] 变更一
+- [ ] 变更二
+- [ ] 变更三
+
+## 测试
+- [ ] ✅ 已添加单元测试
+- [ ] ✅ 已通过所有现有测试
+- [ ] ✅ 已手动测试
+
+## 截图
+如果有 UI 变更，请提供截图。
+
+## 相关 Issue
+相关的 Issue 编号：
+
+## 技术实现
+请简要描述技术实现细节，包括：
+- 使用的技术栈
+- 实现的核心逻辑
+- 与现有代码的集成方式
+
+## 检查清单
+- [ ] ✅ 代码遵循 [项目规范](CONTRIBUTING.md#代码规范)
+- [ ] ✅ 已运行 `make format`
+- [ ] ✅ 已运行 `make lint`
+- [ ] ✅ 已运行 `make test`
+- [ ] ✅ 已更新相关文档
+- [ ] ✅ 提交信息符合 [Conventional Commits](CONTRIBUTING.md#提交信息规范) 格式
+- [ ] ✅ 代码符合 ByteBrain 的设计哲学
+
+## 性能影响
+- [ ] 无性能影响
+- [ ] 有性能优化
+- [ ] 可能有性能影响（请说明）：
+
+## 兼容性
+- [ ] 向后兼容
+- [ ] 破坏性变更（请说明）：
+
+## 备注
+任何其他需要说明的内容。