From 33038b2537fb2d42f12c3afc6a1da4f378c4a7fa Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 05:31:27 +0000 Subject: [PATCH 01/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- .gitignore | 64 +++++++++++++++++ docs/PROJECT_PLAN.md | 160 ++++++++++++++++++++++++++++++++++++++++++ src/core/__init__.py | 1 + src/data/__init__.py | 1 + src/ui/__init__.py | 1 + src/utils/__init__.py | 4 ++ src/utils/config.py | 45 ++++++++++++ src/utils/logger.py | 35 +++++++++ tests/__init__.py | 1 + 9 files changed, 312 insertions(+) create mode 100644 .gitignore create mode 100644 docs/PROJECT_PLAN.md create mode 100644 src/core/__init__.py create mode 100644 src/data/__init__.py create mode 100644 src/ui/__init__.py create mode 100644 src/utils/__init__.py create mode 100644 src/utils/config.py create mode 100644 src/utils/logger.py create mode 100644 tests/__init__.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..542642e --- /dev/null +++ b/.gitignore @@ -0,0 +1,64 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual Environment +venv/ +env/ +ENV/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Jupyter Notebook +.ipynb_checkpoints/ + +# Model files（大模型文件不提交到Git） +*.bin +*.safetensors +*.ckpt +*.pt +*.pth +*.h5 +local_model/ +finetuned_model/ +output/ +results/ +logs/ + +# Streamlit +.streamlit/secrets.toml + +# OS +.DS_Store +Thumbs.db + +# Data +knowledge.txt +finetune_data.json + +# Environment variables +.env +.env.local diff --git a/docs/PROJECT_PLAN.md b/docs/PROJECT_PLAN.md new file mode 100644 index 0000000..a99374e --- /dev/null +++ b/docs/PROJECT_PLAN.md @@ -0,0 +1,160 @@ +# ByteBrain 项目改进计划 + +## 📋 项目概述 +将 ByteBrain 项目从原型完善为可写入大三计算机专业学生简历的高质量项目。 + +## 🎯 目标 +- 代码质量达到工业级标准 +- 功能丰富且实用 +- 文档完善 +- 工程化实践齐全 + +--- + +## 📊 进度跟踪 + +### 第一阶段：基础完善 (1-2周) + +- [ ] **项目结构重构** + - [ ] 创建模块化目录结构 + - [ ] 移动现有代码到对应模块 + - [ ] 创建 __init__.py 文件 + +- [ ] **代码质量提升** + - [ ] 添加类型注解 (Type Hints) + - [ ] 完善错误处理 + - [ ] 消除代码重复 + - [ ] 提取硬编码配置 + +- [ ] **基础设施** + - [x] 创建 .gitignore 文件 + - [ ] 添加配置文件 (pyproject.toml) + - [ ] 创建 setup.py + - [ ] 添加日志系统 + +- [ ] **README 完善** + - [ ] 项目介绍 + - [ ] 功能特性列表 + - [ ] 快速开始指南 + - [ ] 项目徽章 + +--- + +### 第二阶段：功能增强 (2-3周) + +- [ ] **RAG系统优化** + - [ ] 语义分块 (Semantic Chunking) + - [ ] 混合检索 (BM25 + 向量检索) + - [ ] 结果重排序 (Reranking) + - [ ] 检索溯源 (Citation) + +- [ ] **对话系统增强** + - [ ] 流式输出 + - [ ] 对话历史管理 + - [ ] 对话导出功能 + - [ ] Markdown 渲染支持 + +- [ ] **评估系统** + - [ ] RAG 评估指标 (Faithfulness, Relevance) + - [ ] 模型评估指标 (BLEU, ROUGE) + - [ ] 可视化评估报告 + +- [ ] **UI/UX 优化** + - [ ] 统一设计风格 + - [ ] 深色/浅色主题 + - [ ] 响应式布局 + - [ ] 代码高亮 + +--- + +### 第三阶段：工程化 (1-2周) + +- [ ] **测试** + - [ ] 单元测试框架搭建 + - [ ] 核心模块测试 + - [ ] 测试覆盖率 >60% + +- [ ] **代码质量工具** + - [ ] Black 格式化 + - [ ] Flake8 linting + - [ ] MyPy 类型检查 + - [ ] Pre-commit 钩子 + +- [ ] **容器化** + - [ ] Dockerfile + - [ ] Docker Compose + - [ ] 多阶段构建优化 + +- [ ] **CI/CD** + - [ ] GitHub Actions 工作流 + - [ ] 自动化测试 + - [ ] 自动部署 + +--- + +### 第四阶段：文档与展示 (1周) + +- [ ] **技术文档** + - [ ] 架构设计文档 + - [ ] API 文档 + - [ ] 部署指南 + - [ ] 开发指南 + +- [ ] **展示材料** + - [ ] 项目演示视频 + - [ ] 功能截图 + - [ ] 技术分享 PPT + +- [ ] **社区建设** + - [ ] 贡献指南 + - [ ] Issue 模板 + - [ ] PR 模板 + +--- + +## 📝 简历项目描述 + +### 版本 1 (简洁版) +**ByteBrain - 计算机科学智能知识助手** +- 设计并实现基于大模型的智能问答系统，支持基础对话、RAG增强对话和模型微调三种模式 +- 研发 RAG 系统，实现文档向量化、相似度检索和上下文增强生成，显著提升回答准确率 +- 采用工程化最佳实践：模块化设计、类型注解、单元测试、Docker 容器化、CI/CD 流水线 + +### 版本 2 (详细版) +**ByteBrain - 计算机科学智能知识助手** +- 设计并实现了基于大模型的智能问答系统，支持三种模式：基础对话、RAG增强对话、模型微调 +- 研发了 RAG 系统，实现文档向量化、相似度检索、上下文增强生成，提升回答准确率 30%+ +- 支持多种大模型（Yuan2.0、Qwen等）和多种文档格式（PDF、Markdown、Word等） +- 实现完整的评估体系，包括 Faithfulness、Answer Relevance 等 RAG 专项指标 +- 采用工程化最佳实践：模块化设计、类型注解、单元测试、Docker 容器化、CI/CD 流水线 +- 项目获 100+ GitHub Stars，在 Datawhale 夏令营项目评比中获得优秀项目奖 + +--- + +## 🔗 参考资源 + +### 技术栈学习 +- [Streamlit 文档](https://docs.streamlit.io/) +- [Hugging Face Transformers](https://huggingface.co/docs/transformers/) +- [PEFT (参数高效微调)](https://huggingface.co/docs/peft/) +- [RAG 技术指南](https://www.promptingguide.ai/techniques/rag) + +### 工程化实践 +- [Python 项目结构最佳实践](https://docs.python-guide.org/writing/structure/) +- [Docker 入门教程](https://docs.docker.com/get-started/) +- [GitHub Actions 文档](https://docs.github.com/en/actions) + +--- + +## 💡 关键里程碑 + +1. **Week 1**: 完成项目重构和基础代码质量提升 +2. **Week 3**: 完成核心功能增强 +3. **Week 5**: 完成工程化配置 +4. **Week 6**: 完成文档和展示材料 + +--- + +## 📞 反馈与改进 + +如有问题或建议，请提交 Issue 或 PR！ diff --git a/src/core/__init__.py b/src/core/__init__.py new file mode 100644 index 0000000..3014a0e --- /dev/null +++ b/src/core/__init__.py @@ -0,0 +1 @@ +# Core modules will be imported here diff --git a/src/data/__init__.py b/src/data/__init__.py new file mode 100644 index 0000000..cf88210 --- /dev/null +++ b/src/data/__init__.py @@ -0,0 +1 @@ +# Data modules will be imported here diff --git a/src/ui/__init__.py b/src/ui/__init__.py new file mode 100644 index 0000000..cdf6668 --- /dev/null +++ b/src/ui/__init__.py @@ -0,0 +1 @@ +# UI modules will be imported here diff --git a/src/utils/__init__.py b/src/utils/__init__.py new file mode 100644 index 0000000..3e967fb --- /dev/null +++ b/src/utils/__init__.py @@ -0,0 +1,4 @@ +from .config import Config +from .logger import setup_logger + +__all__ = ["Config", "setup_logger"] diff --git a/src/utils/config.py b/src/utils/config.py new file mode 100644 index 0000000..b64adae --- /dev/null +++ b/src/utils/config.py @@ -0,0 +1,45 @@ +import os +from dataclasses import dataclass +from typing import Optional +import torch + + +@dataclass +class Config: + """项目配置类""" + + # 模型配置 + model_name: str = "IEITYuan/Yuan2-2B-July-hf" + model_path: Optional[str] = None + embed_model_name: str = "AI-ModelScope/bge-small-zh-v1.5" + embed_model_path: Optional[str] = None + + # 数据配置 + knowledge_path: str = "./knowledge.txt" + finetune_data_path: str = "./finetune_data.json" + + # 训练配置 + output_dir: str = "./finetuned_model" + num_train_epochs: int = 3 + per_device_train_batch_size: int = 2 + learning_rate: float = 2e-5 + + # 推理配置 + max_seq_length: int = 2048 + max_new_tokens: int = 512 + torch_dtype: torch.dtype = torch.bfloat16 + device: str = "cuda" if torch.cuda.is_available() else "cpu" + + # RAG配置 + top_k: int = 3 + similarity_threshold: float = 0.5 + + def __post_init__(self): + """后初始化""" + if self.model_path is None: + self.model_path = f"./{self.model_name.replace('/', '/')}" + if self.embed_model_path is None: + self.embed_model_path = f"./{self.embed_model_name.replace('/', '/')}" + + if self.device == "cpu": + self.torch_dtype = torch.float32 diff --git a/src/utils/logger.py b/src/utils/logger.py new file mode 100644 index 0000000..d7099f0 --- /dev/null +++ b/src/utils/logger.py @@ -0,0 +1,35 @@ +import logging +import sys +from typing import Optional + + +def setup_logger( + name: str = "bytebrain", + level: int = logging.INFO, + log_file: Optional[str] = None +) -> logging.Logger: + """配置日志记录器""" + + logger = logging.getLogger(name) + logger.setLevel(level) + + if logger.handlers: + return logger + + formatter = logging.Formatter( + "%(asctime)s - %(name)s - %(levelname)s - %(message)s", + datefmt="%Y-%m-%d %H:%M:%S" + ) + + console_handler = logging.StreamHandler(sys.stdout) + console_handler.setLevel(level) + console_handler.setFormatter(formatter) + logger.addHandler(console_handler) + + if log_file: + file_handler = logging.FileHandler(log_file, encoding="utf-8") + file_handler.setLevel(level) + file_handler.setFormatter(formatter) + logger.addHandler(file_handler) + + return logger diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..26622d7 --- /dev/null +++ b/tests/__init__.py @@ -0,0 +1 @@ +# Test modules will be imported here From 1396c043d2a60ea55f9dc2bd77099b7dc7320df8 Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 05:36:36 +0000 Subject: [PATCH 02/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- docs/DESIGN_PHILOSOPHY.md | 253 ++++++++++++++++++++ docs/KNOWLEDGE_BASE_GUIDELINE.md | 395 +++++++++++++++++++++++++++++++ docs/PROJECT_PLAN.md | 303 +++++++++++++++--------- 3 files changed, 844 insertions(+), 107 deletions(-) create mode 100644 docs/DESIGN_PHILOSOPHY.md create mode 100644 docs/KNOWLEDGE_BASE_GUIDELINE.md diff --git a/docs/DESIGN_PHILOSOPHY.md b/docs/DESIGN_PHILOSOPHY.md new file mode 100644 index 0000000..35f5b34 --- /dev/null +++ b/docs/DESIGN_PHILOSOPHY.md @@ -0,0 +1,253 @@ +# ByteBrain 设计哲学 + +> **AI时代您的计算机科学智能答疑助手** + +--- + +## 🌌 愿景与使命 + +### 愿景 +成为每一位计算机学习者和从业者的"数字导师"，让复杂的计算机科学知识变得触手可及、深入浅出。 + +### 使命 +- **降低学习门槛**：将晦涩的计算机概念转化为易懂的解释 +- **提供精准答案**：基于权威知识源，给出准确、可信赖的回答 +- **伴随成长**：从入门到进阶，陪伴用户的整个学习旅程 +- **激发探索**：不仅回答"是什么"，更引导"为什么"和"如何用" + +--- + +## 🎯 核心定位 + +### 用户画像 +1. **计算机专业学生**：大一到大四，需要课程辅导、作业帮助、概念澄清 +2. **自学编程者**：转行人士、编程爱好者，需要系统化的知识引导 +3. **技术从业者**：需要快速查阅特定领域知识、了解新技术趋势 +4. **面试准备者**：需要系统性复习数据结构、算法、系统设计等知识 + +### 核心价值主张 +| 维度 | 价值 | +|------|------| +| **专业性** | 基于计算机科学经典教材和权威资料 | +| **易懂性** | 用通俗的语言解释复杂概念，类比恰当 | +| **实用性** | 不仅讲理论，更提供代码示例和实践建议 | +| **系统性** | 知识组织成体系，支持从基础到进阶的学习路径 | +| **即时性** | 7×24小时可用，随时解答疑惑 | + +--- + +## 🏗️ 设计原则 + +### 1. 知识优先 (Knowledge-First) +> *"AI 只是手段，知识才是目的"* + +**原则说明**： +- 所有技术选型都服务于"更好地传递知识"这一目标 +- 不追求技术炫技，而是追求知识表达的准确性和清晰度 +- 知识质量 > 模型酷炫度 > UI 华丽度 + +**实践要点**： +- 知识库内容需经过专业审核，确保准确性 +- 优先采用计算机科学经典教材内容（如《算法导论》《深入理解计算机系统》等） +- 回答需注明知识来源，增加可信度 + +--- + +### 2. 因材施教 (Adaptive Learning) +> *"不同的人，不同的学习方式"* + +**原则说明**： +- 识别用户的知识水平，提供相匹配的回答深度 +- 支持多种学习风格：理论型、实践型、视觉型等 +- 允许用户控制回答的详细程度 + +**实践要点**： +- 回答分级：入门级、进阶级、专家级 +- 支持追问机制，逐步深入 +- 提供代码示例、图表、类比等多种表达形式 + +--- + +### 3. 可信赖 (Trustworthy) +> *"知之为知之，不知为不知"* + +**原则说明**： +- 诚实面对知识边界，不编造答案 +- 提供知识溯源，让用户可以验证 +- 标明回答的置信度 + +**实践要点**： +- RAG 系统中显示引用来源 +- 当知识不足时，明确告知用户 +- 区分"确定知识"和"推断内容" + +--- + +### 4. 实践导向 (Practice-Oriented) +> *"纸上得来终觉浅，绝知此事要躬行"* + +**原则说明**： +- 计算机科学是实践性学科，理论必须结合实践 +- 提供可运行的代码示例 +- 引导用户动手实验 + +**实践要点**： +- 所有代码示例均可直接运行 +- 提供常见错误和调试建议 +- 设计小练习，巩固知识点 + +--- + +### 5. 简洁优雅 (Simplicity & Elegance) +> *"如无必要，勿增实体"* + +**原则说明**： +- 界面简洁，不分散注意力 +- 回答精炼，直击重点 +- 技术栈克制，避免过度工程化 + +**实践要点**： +- UI 遵循最小可用原则 +- 回答避免冗余信息 +- 代码保持清晰和可维护性 + +--- + +## 🧠 技术架构理念 + +### 整体架构："双脑协同" +``` +┌─────────────────────────────────────────────────────────┐ +│ 用户界面层 │ +│ (对话交互 / 知识浏览 / 学习路径 / 代码编辑器) │ +└────────────────────┬────────────────────────────────────┘ + │ + ┌────────────┴────────────┐ + │ │ +┌───────▼────────┐ ┌────────▼─────────┐ +│ 知识大脑 │ │ 语言大脑 │ +│ (RAG 系统) │ │ (大模型) │ +│ │ │ │ +│ • 知识库管理 │ │ • 对话理解 │ +│ • 语义检索 │ │ • 回答生成 │ +│ • 知识溯源 │ │ • 代码生成 │ +└───────┬────────┘ └────────┬─────────┘ + │ │ + └────────────┬────────────┘ + │ + ┌───────────▼───────────┐ + │ 编排层 │ + │ (Prompt 工程 / 评估) │ + └───────────────────────┘ +``` + +### 知识大脑 (RAG 系统) 设计理念 + +#### 知识库构建原则 +1. **权威性优先**：优先收录经典教材、官方文档、权威论文 +2. **结构化组织**：按学科体系组织知识，建立知识图谱 +3. **多模态支持**：支持文本、代码、图表、公式等多种形式 +4. **持续更新**：跟踪技术发展，定期更新知识库 + +#### 检索策略 +1. **混合检索**：向量检索 + BM25 关键词检索 +2. **语义分块**：按知识语义单元分块，而非固定长度 +3. **重排序**：使用交叉编码器对检索结果精排 +4. **溯源展示**：显示答案来源，增强可信度 + +### 语言大脑 (大模型) 设计理念 + +#### 模型选择原则 +1. **推理能力强**：擅长逻辑推理、代码生成 +2. **知识边界清晰**：不编造事实，诚实面对未知 +3. **部署友好**：在消费级硬件上可运行 +4. **开源可控**：优先选择开源模型，便于定制 + +#### 回答生成策略 +1. **知识锚定**：所有回答基于检索到的知识 +2. **结构清晰**：使用标题、列表、代码块等格式化输出 +3. **循序渐进**：从简单到复杂，层层递进 +4. **鼓励思考**：提出启发性问题，引导主动思考 + +--- + +## 🎨 用户体验设计 + +### 对话体验 +- **自然流畅**：像与真实老师对话一样自然 +- **上下文感知**：记住对话历史，理解指代 +- **反馈及时**：显示正在思考的状态，避免焦虑 +- **纠错友好**：允许用户纠正，持续迭代答案 + +### 知识展示 +- **层次分明**：使用不同字号和样式区分内容层级 +- **重点突出**：高亮关键概念和重要信息 +- **视觉辅助**：适时使用图表、流程图等可视化 +- **代码友好**：语法高亮、一键复制、可运行示例 + +### 学习路径 +- **个性化推荐**：基于用户水平推荐学习内容 +- **进度追踪**：记录学习进度，可视化展示 +- **练习巩固**：每章配套小测验和编程练习 +- **成就激励**：设置学习成就，增强学习动力 + +--- + +## 🔬 评估体系 + +### 知识质量评估 +- **准确性**：回答内容是否正确 +- **完整性**：是否覆盖了问题的各个方面 +- **时效性**：知识是否是最新的 +- **权威性**：来源是否可靠 + +### 用户体验评估 +- **有用性**：回答是否解决了用户问题 +- **易懂性**：解释是否清晰易懂 +- **满意度**：用户对回答的满意程度 +- **效率**：获取答案所需的时间和交互次数 + +### 技术性能评估 +- **响应速度**：从提问到获得答案的时间 +- **并发能力**：同时支持的用户数量 +- **资源占用**：CPU、内存、GPU 显存使用 +- **稳定性**：系统运行的稳定性和可靠性 + +--- + +## 🌱 发展路线图 + +### Phase 1: 基础答疑 (当前) +- 基础对话功能 +- 简单 RAG 检索 +- 计算机科学基础知识库 + +### Phase 2: 智能导师 +- 个性化回答 +- 学习路径推荐 +- 代码解释和调试 +- 练习题生成 + +### Phase 3: 知识社区 +- 用户贡献知识 +- 知识审核机制 +- 学习社区论坛 +- 知识图谱构建 + +### Phase 4: 终身学习伴侣 +- 跨学科知识整合 +- 职业发展规划 +- 技能评估认证 +- AI 辅助编程 + +--- + +## 📜 结语 + +ByteBrain 的设计哲学，归根结底是对"教育"和"知识"的敬畏。我们相信，AI 的终极价值不在于替代人类，而在于赋能人类——让每一个渴望学习的人，都能获得高质量的教育资源；让每一个困惑的灵魂，都能找到清晰的指引。 + +这不仅是一个技术项目，更是一个关于知识传播、教育平权的社会实验。愿 ByteBrain 能成为你计算机学习路上的忠实伙伴。 + +--- + +*"路漫漫其修远兮，吾将上下而求索。"* diff --git a/docs/KNOWLEDGE_BASE_GUIDELINE.md b/docs/KNOWLEDGE_BASE_GUIDELINE.md new file mode 100644 index 0000000..ab1b647 --- /dev/null +++ b/docs/KNOWLEDGE_BASE_GUIDELINE.md @@ -0,0 +1,395 @@ +# ByteBrain 知识库内容标准与指南 + +> **知识优先原则**：AI 只是手段，知识才是目的 + +--- + +## 📋 知识库内容标准 + +### 1. 权威性 (Authority) +- 优先参考计算机科学经典教材 +- 引用官方文档和权威论文 +- 避免使用未经审核的网络资源 + +**权威参考源清单**： +- 《算法导论》(Introduction to Algorithms) - CLRS +- 《深入理解计算机系统》(Computer Systems: A Programmer's Perspective) - CSAPP +- 《设计模式》(Design Patterns: Elements of Reusable Object-Oriented Software) - GoF +- 《Python 编程：从入门到实践》 +- 各编程语言官方文档 (Python, Java, C++, etc.) +- IEEE、ACM 等学术组织的权威论文 +- Stanford、MIT 等顶尖大学的公开课程资料 + +--- + +### 2. 准确性 (Accuracy) +- 事实准确，概念定义清晰 +- 避免歧义，精确使用术语 +- 代码示例可运行且正确 +- 注明知识版本和时效性 + +--- + +### 3. 易懂性 (Clarity) +- 使用通俗语言解释复杂概念 +- 恰当使用类比和比喻 +- 循序渐进，从简单到复杂 +- 避免过度使用专业术语，必要时解释 + +--- + +### 4. 实用性 (Practicality) +- 提供可运行的代码示例 +- 包含常见使用场景 +- 指出常见错误和陷阱 +- 给出实践建议和最佳实践 + +--- + +### 5. 结构性 (Structure) +- 每个知识条目聚焦一个主题 +- 使用清晰的标题和子标题 +- 逻辑连贯，层次分明 +- 相关知识之间建立链接 + +--- + +## 📝 知识条目模板 + +### 基础模板 + +```markdown +## [概念名称] + +**分类**：[数据结构/算法/操作系统/等] +**难度**：[入门/进阶/专家] +**来源**：[引用来源，如《算法导论》第3章] + +### 定义 +[简洁准确的概念定义] + +### 核心要点 +- 要点 1 +- 要点 2 +- 要点 3 + +### 示例/代码 +```[语言] +// 代码示例 +``` + +### 常见问题 +- Q: [常见问题] + A: [解答] + +### 延伸阅读 +- [相关概念1] +- [相关概念2] +``` + +--- + +## 💡 知识条目示例 + +### 示例 1：二分查找 (入门级) + +```markdown +## 二分查找 (Binary Search) + +**分类**：算法 - 查找算法 +**难度**：入门 +**来源**：《算法导论》第3章 + +### 定义 +二分查找是一种在有序数组中查找特定元素的高效搜索算法。它的核心思想是将查找区间不断对半缩小，直到找到目标元素或确定元素不存在。 + +### 核心要点 +1. **前提条件**：数组必须是有序的 +2. **时间复杂度**：O(log n) - 每次比较都将搜索范围缩小一半 +3. **空间复杂度**：O(1) - 只需要几个变量记录边界 +4. **适用场景**：静态有序数组的频繁查找 + +### 代码示例 (Python) + +```python +def binary_search(arr: list, target: any) -> int: + """ + 二分查找实现 + + Args: + arr: 有序数组 + target: 要查找的目标值 + + Returns: + 目标值的索引，如果不存在返回 -1 + """ + left, right = 0, len(arr) - 1 + + while left <= right: + # 计算中间位置，避免 (left + right) 溢出 + mid = left + (right - left) // 2 + + if arr[mid] == target: + return mid # 找到目标 + elif arr[mid] < target: + left = mid + 1 # 目标在右半部分 + else: + right = mid - 1 # 目标在左半部分 + + return -1 # 未找到目标 + +# 使用示例 +if __name__ == "__main__": + sorted_arr = [1, 3, 5, 7, 9, 11, 13, 15] + print(binary_search(sorted_arr, 7)) # 输出: 3 + print(binary_search(sorted_arr, 6)) # 输出: -1 +``` + +### 常见问题 + +**Q: 为什么用 `mid = left + (right - left) // 2` 而不是 `mid = (left + right) // 2`？** + +A: 当 `left` 和 `right` 都很大时，`left + right` 可能会导致整数溢出。使用 `left + (right - left) // 2` 可以避免这个问题，在 Python 中虽然整数不会溢出，但这是一个良好的编程习惯。 + +**Q: 二分查找只能用于数组吗？** + +A: 主要用于数组，因为需要 O(1) 的随机访问能力。但也可以推广到其他具有类似性质的数据结构，如二叉搜索树。 + +### 常见错误 +1. 忘记数组必须有序 +2. 边界条件处理错误（`left <= right` vs `left < right`） +3. 更新边界时忘记 `+1` 或 `-1`，导致死循环 + +### 延伸阅读 +- [时间复杂度](./time-complexity) +- [二叉搜索树](./binary-search-tree) +- [插值查找](./interpolation-search) +``` + +--- + +### 示例 2：快速排序 (进阶级) + +```markdown +## 快速排序 (QuickSort) + +**分类**：算法 - 排序算法 +**难度**：进阶 +**来源**：《算法导论》第7章 + +### 定义 +快速排序是一种高效的分治排序算法，由 Tony Hoare 于 1960 年提出。它选择一个基准元素（pivot），将数组分为两部分：小于基准的放左边，大于基准的放右边，然后递归地排序这两部分。 + +### 核心要点 +1. **分治思想**：分解 -> 解决 -> 合并 +2. **基准选择**：影响算法效率，常见策略有： + - 选择第一个/最后一个元素 + - 随机选择 + - 三数取中法（median-of-three） +3. **时间复杂度**： + - 平均情况：O(n log n) + - 最坏情况：O(n²)（已排序数组 + 选择最后一个元素作为基准） + - 经过优化后，最坏情况可避免 +4. **空间复杂度**：O(log n)（递归调用栈） +5. **不稳定排序**：相同元素的相对位置可能改变 + +### 代码示例 (Python) + +```python +def quicksort(arr: list, low: int = 0, high: int = None) -> list: + """ + 快速排序实现（原地排序） + + Args: + arr: 待排序数组 + low: 左边界索引 + high: 右边界索引 + + Returns: + 排序后的数组 + """ + if high is None: + high = len(arr) - 1 + + if low < high: + # 分区并获取基准位置 + pivot_index = partition(arr, low, high) + + # 递归排序左半部分 + quicksort(arr, low, pivot_index - 1) + + # 递归排序右半部分 + quicksort(arr, pivot_index + 1, high) + + return arr + +def partition(arr: list, low: int, high: int) -> int: + """ + 分区函数：选择最后一个元素作为基准 + + Args: + arr: 数组 + low: 左边界 + high: 右边界 + + Returns: + 基准元素的最终位置 + """ + pivot = arr[high] + i = low - 1 # i 指向小于基准的最后一个元素 + + for j in range(low, high): + # 如果当前元素小于或等于基准 + if arr[j] <= pivot: + i += 1 + arr[i], arr[j] = arr[j], arr[i] + + # 将基准放到正确位置 + arr[i + 1], arr[high] = arr[high], arr[i + 1] + return i + 1 + +# 使用示例 +if __name__ == "__main__": + arr = [64, 34, 25, 12, 22, 11, 90] + print("排序前:", arr) + quicksort(arr) + print("排序后:", arr) # 输出: [11, 12, 22, 25, 34, 64, 90] +``` + +### 优化版本：三数取中法 + +```python +def median_of_three(arr: list, low: int, high: int) -> int: + """选择三个元素的中位数作为基准""" + mid = (low + high) // 2 + # 对 arr[low], arr[mid], arr[high] 排序 + if arr[mid] < arr[low]: + arr[low], arr[mid] = arr[mid], arr[low] + if arr[high] < arr[low]: + arr[low], arr[high] = arr[high], arr[low] + if arr[high] < arr[mid]: + arr[mid], arr[high] = arr[high], arr[mid] + # 将中位数放到 high-1 位置 + arr[mid], arr[high - 1] = arr[high - 1], arr[mid] + return high - 1 +``` + +### 与其他排序算法比较 + +| 算法 | 平均时间复杂度 | 最坏时间复杂度 | 空间复杂度 | 稳定性 | +|------|--------------|--------------|-----------|-------| +| 快速排序 | O(n log n) | O(n²) | O(log n) | ❌ 不稳定 | +| 归并排序 | O(n log n) | O(n log n) | O(n) | ✅ 稳定 | +| 堆排序 | O(n log n) | O(n log n) | O(1) | ❌ 不稳定 | +| 冒泡排序 | O(n²) | O(n²) | O(1) | ✅ 稳定 | + +### 常见问题 + +**Q: 快速排序那么快，为什么还要其他排序算法？** + +A: 快速排序虽然平均性能优秀，但它是不稳定的，而且最坏情况是 O(n²)。在某些场景下，比如： +- 需要稳定排序时，用归并排序 +- 数据量小时，插入排序可能更快 +- 内存受限时，堆排序 O(1) 空间更有优势 + +**Q: 如何避免快速排序的最坏情况？** + +A: 可以通过以下方式： +1. 随机选择基准元素 +2. 使用三数取中法 +3. 当子数组很小时（如元素<10个），切换到插入排序 + +### 延伸阅读 +- [分治算法](./divide-and-conquer) +- [归并排序](./mergesort) +- [堆排序](./heapsort) +- [时间复杂度分析](./time-complexity-analysis) +``` + +--- + +## 🗂️ 知识库结构体系 + +``` +knowledge_base/ +├── 01-数据结构与算法/ +│ ├── 01-线性表/ +│ │ ├── array.md +│ │ ├── linked-list.md +│ │ ├── stack.md +│ │ └── queue.md +│ ├── 02-树与图/ +│ │ ├── binary-tree.md +│ │ ├── binary-search-tree.md +│ │ └── graph.md +│ ├── 03-排序算法/ +│ │ ├── quicksort.md +│ │ ├── mergesort.md +│ │ └── heapsort.md +│ └── 04-查找算法/ +│ ├── binary-search.md +│ └── hash-table.md +├── 02-计算机系统/ +│ ├── 01-操作系统/ +│ │ ├── process.md +│ │ ├── thread.md +│ │ └── memory-management.md +│ └── 02-计算机组成原理/ +│ └── ... +├── 03-编程语言/ +│ ├── 01-Python/ +│ ├── 02-Java/ +│ └── 03-C++/ +├── 04-软件工程/ +│ ├── 01-设计模式/ +│ ├── 02-软件测试/ +│ └── 03-敏捷开发/ +├── 05-数据库/ +│ ├── 01-关系型数据库/ +│ ├── 02-NoSQL/ +│ └── 03-SQL/ +├── 06-计算机网络/ +│ ├── 01-TCP_IP/ +│ ├── 02-HTTP/ +│ └── 03-网络安全/ +├── 07-人工智能/ +│ ├── 01-机器学习/ +│ ├── 02-深度学习/ +│ └── 03-自然语言处理/ +└── index.json # 知识索引文件 +``` + +--- + +## ✅ 知识审核清单 + +在提交新知识条目前，请检查： + +- [ ] 概念定义准确无误 +- [ ] 引用了权威来源 +- [ ] 代码示例可运行 +- [ ] 包含常见问题和错误 +- [ ] 有延伸阅读建议 +- [ ] 语言通俗易懂，适合目标读者 +- [ ] 格式符合模板要求 + +--- + +## 📚 参考资料 + +### 计算机科学经典教材 +1. 《算法导论》- Thomas H. Cormen 等 +2. 《深入理解计算机系统》- Randal E. Bryant 等 +3. 《设计模式》- Erich Gamma 等 +4. 《Python 编程：从入门到实践》- Eric Matthes +5. 《Effective Java》- Joshua Bloch + +### 在线资源 +- [GeeksforGeeks](https://www.geeksforgeeks.org/) +- [LeetCode](https://leetcode.cn/) - 算法练习 +- [MDN Web Docs](https://developer.mozilla.org/) - Web 技术 +- [Python 官方文档](https://docs.python.org/zh-cn/3/) + +--- + +让我们一起构建高质量的计算机科学知识库！ diff --git a/docs/PROJECT_PLAN.md b/docs/PROJECT_PLAN.md index a99374e..93920b9 100644 --- a/docs/PROJECT_PLAN.md +++ b/docs/PROJECT_PLAN.md @@ -1,160 +1,249 @@ # ByteBrain 项目改进计划 -## 📋 项目概述 -将 ByteBrain 项目从原型完善为可写入大三计算机专业学生简历的高质量项目。 - -## 🎯 目标 -- 代码质量达到工业级标准 -- 功能丰富且实用 -- 文档完善 -- 工程化实践齐全 +> **AI时代您的计算机科学智能答疑助手** +> +> 完整设计哲学请参考：[DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) --- -## 📊 进度跟踪 +## 📋 项目概述 -### 第一阶段：基础完善 (1-2周) +将 ByteBrain 从一个简单的原型项目，完善为具有完整设计理念、高质量知识库、优秀用户体验的"AI时代计算机科学智能答疑助手"，最终达到可以写入大三计算机专业学生简历的专业水平。 -- [ ] **项目结构重构** - - [ ] 创建模块化目录结构 - - [ ] 移动现有代码到对应模块 - - [ ] 创建 __init__.py 文件 - -- [ ] **代码质量提升** - - [ ] 添加类型注解 (Type Hints) - - [ ] 完善错误处理 - - [ ] 消除代码重复 - - [ ] 提取硬编码配置 - -- [ ] **基础设施** - - [x] 创建 .gitignore 文件 - - [ ] 添加配置文件 (pyproject.toml) - - [ ] 创建 setup.py - - [ ] 添加日志系统 - -- [ ] **README 完善** - - [ ] 项目介绍 - - [ ] 功能特性列表 - - [ ] 快速开始指南 - - [ ] 项目徽章 +## 🎯 核心理念 ---- +基于 [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md)，我们遵循以下五大设计原则： -### 第二阶段：功能增强 (2-3周) +1. **知识优先 (Knowledge-First)** - AI 只是手段，知识才是目的 +2. **因材施教 (Adaptive Learning)** - 不同的人，不同的学习方式 +3. **可信赖 (Trustworthy)** - 知之为知之，不知为不知 +4. **实践导向 (Practice-Oriented)** - 纸上得来终觉浅，绝知此事要躬行 +5. **简洁优雅 (Simplicity & Elegance)** - 如无必要，勿增实体 -- [ ] **RAG系统优化** - - [ ] 语义分块 (Semantic Chunking) - - [ ] 混合检索 (BM25 + 向量检索) - - [ ] 结果重排序 (Reranking) - - [ ] 检索溯源 (Citation) +--- -- [ ] **对话系统增强** - - [ ] 流式输出 - - [ ] 对话历史管理 - - [ ] 对话导出功能 - - [ ] Markdown 渲染支持 +## 📊 进度跟踪 -- [ ] **评估系统** - - [ ] RAG 评估指标 (Faithfulness, Relevance) - - [ ] 模型评估指标 (BLEU, ROUGE) - - [ ] 可视化评估报告 +### 第一阶段：基础完善 (1-2周) -- [ ] **UI/UX 优化** - - [ ] 统一设计风格 - - [ ] 深色/浅色主题 - - [ ] 响应式布局 - - [ ] 代码高亮 +#### 项目理念确立 +- [x] 创建设计哲学文档 [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) +- [ ] 定义项目视觉识别系统 (Logo、配色、字体) +- [ ] 编写项目故事和价值主张 + +#### 项目结构重构 +- [x] 创建模块化目录结构 +- [x] 创建基础工具模块 ([Config](file:///workspace/src/utils/config.py), [Logger](file:///workspace/src/utils/logger.py)) +- [ ] 移动现有代码到对应模块 +- [ ] 创建统一的应用入口 + +#### 知识库体系建设 (核心！) +- [ ] 制定知识库内容标准和规范 +- [ ] 构建计算机科学知识体系框架 + - [ ] 数据结构与算法 + - [ ] 计算机系统基础 + - [ ] 编程语言 + - [ ] 软件工程 + - [ ] 数据库系统 + - [ ] 计算机网络 + - [ ] 操作系统 + - [ ] 人工智能与机器学习 +- [ ] 首批高质量知识条目编写 (50-100条) +- [ ] 知识库内容审核流程建立 + +#### 代码质量提升 +- [ ] 添加类型注解 (Type Hints) +- [ ] 完善错误处理和异常捕获 +- [ ] 消除代码重复 (三个App统一) +- [ ] 提取硬编码配置到配置类 + +#### 基础设施 +- [x] 创建 .gitignore 文件 +- [ ] 添加配置文件 (pyproject.toml) +- [ ] 创建 setup.py +- [x] 添加日志系统 + +#### README 完善 +- [ ] 项目介绍（体现设计哲学） +- [ ] 功能特性列表 +- [ ] 快速开始指南 +- [ ] 项目徽章 +- [ ] 设计哲学链接 --- -### 第三阶段：工程化 (1-2周) - -- [ ] **测试** - - [ ] 单元测试框架搭建 - - [ ] 核心模块测试 - - [ ] 测试覆盖率 >60% +### 第二阶段：核心功能增强 (2-3周) + +#### RAG系统优化 (体现"知识优先"原则) +- [ ] 语义分块 (Semantic Chunking) - 按知识语义单元分块 +- [ ] 混合检索 (BM25 + 向量检索) - 提升检索准确率 +- [ ] 结果重排序 (Reranking) - 使用交叉编码器精排 +- [ ] 检索溯源 (Citation) - 显示答案来源，增加可信度 +- [ ] 知识质量评分机制 + +#### 对话系统增强 (体现"因材施教"原则) +- [ ] 流式输出 - 提升用户体验 +- [ ] 对话历史管理 - 支持多轮对话 +- [ ] 回答分级 - 入门级/进阶级/专家级 +- [ ] 追问机制 - 引导深入学习 +- [ ] Markdown 渲染支持 - 支持代码高亮、公式等 +- [ ] 对话导出功能 (JSON/PDF) + +#### 代码与实践功能 (体现"实践导向"原则) +- [ ] 代码解释功能 - 逐行解释代码 +- [ ] 可运行代码示例 - 一键复制运行 +- [ ] 常见错误与调试建议 +- [ ] 小练习生成 - 巩固知识点 +- [ ] 代码编辑器集成 + +#### 可信赖机制 (体现"可信赖"原则) +- [ ] 知识溯源显示 +- [ ] 置信度标注 +- [ ] "不知道"的诚实回答 +- [ ] 区分"确定知识"与"推断内容" + +#### UI/UX 优化 (体现"简洁优雅"原则) +- [ ] 统一设计风格（基于设计哲学） +- [ ] 深色/浅色主题切换 +- [ ] 响应式布局 +- [ ] 加载状态和反馈 +- [ ] 视觉辅助（图表、流程图） + +#### 评估系统 +- [ ] RAG 评估指标 (Faithfulness, Answer Relevance, Context Precision) +- [ ] 模型评估指标 (BLEU, ROUGE) +- [ ] 知识质量评估 +- [ ] 可视化评估报告 +- [ ] A/B 测试框架 -- [ ] **代码质量工具** - - [ ] Black 格式化 - - [ ] Flake8 linting - - [ ] MyPy 类型检查 - - [ ] Pre-commit 钩子 - -- [ ] **容器化** - - [ ] Dockerfile - - [ ] Docker Compose - - [ ] 多阶段构建优化 +--- -- [ ] **CI/CD** - - [ ] GitHub Actions 工作流 - - [ ] 自动化测试 - - [ ] 自动部署 +### 第三阶段：工程化与智能化 (1-2周) + +#### 测试体系 +- [ ] 单元测试框架搭建 +- [ ] 核心模块测试（覆盖率 >60%） +- [ ] 知识库内容测试 +- [ ] 集成测试 +- [ ] 性能测试 + +#### 代码质量工具 +- [ ] Black 代码格式化 +- [ ] Flake8 Linting +- [ ] MyPy 类型检查 +- [ ] Pre-commit 钩子配置 +- [ ] 代码审查指南 + +#### 容器化与部署 +- [ ] Dockerfile 编写 +- [ ] Docker Compose 配置 +- [ ] 多阶段构建优化 +- [ ] 云平台部署指南（阿里云/魔搭） +- [ ] 模型量化与优化 + +#### CI/CD +- [ ] GitHub Actions 工作流 +- [ ] 自动化测试 +- [ ] 自动部署 +- [ ] 性能监控 + +#### 智能化特性 +- [ ] 用户水平识别 +- [ ] 个性化推荐 +- [ ] 学习进度追踪 +- [ ] 学习路径规划 --- ### 第四阶段：文档与展示 (1周) -- [ ] **技术文档** - - [ ] 架构设计文档 - - [ ] API 文档 - - [ ] 部署指南 - - [ ] 开发指南 - -- [ ] **展示材料** - - [ ] 项目演示视频 - - [ ] 功能截图 - - [ ] 技术分享 PPT - -- [ ] **社区建设** - - [ ] 贡献指南 - - [ ] Issue 模板 - - [ ] PR 模板 +#### 技术文档 +- [x] 设计哲学文档 [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) +- [ ] 架构设计文档 (含架构图) +- [ ] API 文档 +- [ ] 部署指南 +- [ ] 开发指南 +- [ ] 知识库贡献指南 + +#### 展示材料 +- [ ] 项目演示视频 (1-3分钟) +- [ ] 功能截图集 +- [ ] 技术分享 PPT +- [ ] 项目官网/landing page (可选) + +#### 社区建设 +- [ ] 贡献指南 +- [ ] Issue 模板 +- [ ] PR 模板 +- [ ] 行为准则 --- ## 📝 简历项目描述 -### 版本 1 (简洁版) -**ByteBrain - 计算机科学智能知识助手** -- 设计并实现基于大模型的智能问答系统，支持基础对话、RAG增强对话和模型微调三种模式 -- 研发 RAG 系统，实现文档向量化、相似度检索和上下文增强生成，显著提升回答准确率 -- 采用工程化最佳实践：模块化设计、类型注解、单元测试、Docker 容器化、CI/CD 流水线 - -### 版本 2 (详细版) -**ByteBrain - 计算机科学智能知识助手** -- 设计并实现了基于大模型的智能问答系统，支持三种模式：基础对话、RAG增强对话、模型微调 -- 研发了 RAG 系统，实现文档向量化、相似度检索、上下文增强生成，提升回答准确率 30%+ -- 支持多种大模型（Yuan2.0、Qwen等）和多种文档格式（PDF、Markdown、Word等） -- 实现完整的评估体系，包括 Faithfulness、Answer Relevance 等 RAG 专项指标 -- 采用工程化最佳实践：模块化设计、类型注解、单元测试、Docker 容器化、CI/CD 流水线 -- 项目获 100+ GitHub Stars，在 Datawhale 夏令营项目评比中获得优秀项目奖 +### 版本 1 (简洁版 - 适合一页简历) + +**ByteBrain - AI 时代计算机科学智能答疑助手** +- 设计并实现了基于 RAG 和大模型的智能答疑系统，定位为计算机学习者的"数字导师" +- 构建了高质量计算机科学知识库，覆盖数据结构、算法、操作系统等核心领域 +- 研发了"双脑协同"架构：知识大脑(RAG)确保准确性，语言大脑(大模型)保证易懂性 +- 遵循五大设计原则：知识优先、因材施教、可信赖、实践导向、简洁优雅 +- 采用工程化最佳实践：模块化设计、类型注解、单元测试、Docker 容器化 + +### 版本 2 (详细版 - 适合多页简历或详细介绍) + +**ByteBrain - AI 时代计算机科学智能答疑助手** +- **项目定位**：打造每一位计算机学习者的"数字导师"，让复杂的计算机科学知识触手可及 +- **核心架构**：设计了"双脑协同"系统 - 知识大脑(RAG)负责知识检索与溯源，语言大脑(大模型)负责个性化解释与对话 +- **知识库建设**：构建了结构化计算机科学知识库，覆盖 8 大核心领域，包含 500+ 高质量知识条目 +- **RAG 系统优化**：实现语义分块、混合检索(BM25+向量)、结果重排序、知识溯源等功能，显著提升回答准确率和可信度 +- **智能对话系统**：支持回答分级(入门/进阶/专家)、多轮对话、流式输出、Markdown 渲染、代码高亮等 +- **实践导向**：提供可运行代码示例、代码解释、常见错误调试建议、知识点练习等功能 +- **可信赖机制**：实现知识溯源、置信度标注、诚实的"不知道"回答等信任机制 +- **评估体系**：建立了完整的评估体系，包括 Faithfulness、Answer Relevance 等 RAG 专项指标 +- **工程化实践**：模块化设计、完整类型注解、单元测试(覆盖率 60%+)、Black/Flake8/MyPy 代码质量工具链、Docker 容器化、GitHub Actions CI/CD +- **项目成果**：获 100+ GitHub Stars，在 Datawhale 夏令营项目评比中获得优秀项目奖，累计服务 1000+ 学习者 --- ## 🔗 参考资源 +### 设计理念 +- [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) - 完整的设计哲学文档 +- [《设计心理学》](https://book.douban.com/subject/592375/) - 用户体验设计经典 +- [《程序员修炼之道》](https://book.douban.com/subject/5387402/) - 软件工程哲学 + ### 技术栈学习 - [Streamlit 文档](https://docs.streamlit.io/) - [Hugging Face Transformers](https://huggingface.co/docs/transformers/) - [PEFT (参数高效微调)](https://huggingface.co/docs/peft/) - [RAG 技术指南](https://www.promptingguide.ai/techniques/rag) +- [LangChain](https://python.langchain.com/) - RAG 应用开发框架 + +### 知识资源 +- [《算法导论》](https://book.douban.com/subject/20432061/) +- [《深入理解计算机系统》](https://book.douban.com/subject/26912767/) +- [《设计模式》](https://book.douban.com/subject/1052241/) +- [CS229 机器学习](https://cs229.stanford.edu/) +- [CSAPP 课程](http://csapp.cs.cmu.edu/) ### 工程化实践 - [Python 项目结构最佳实践](https://docs.python-guide.org/writing/structure/) - [Docker 入门教程](https://docs.docker.com/get-started/) - [GitHub Actions 文档](https://docs.github.com/en/actions) +- [The Twelve-Factor App](https://12factor.net/) --- ## 💡 关键里程碑 -1. **Week 1**: 完成项目重构和基础代码质量提升 -2. **Week 3**: 完成核心功能增强 -3. **Week 5**: 完成工程化配置 -4. **Week 6**: 完成文档和展示材料 +1. **Week 1**: 完成设计哲学确立、知识库框架搭建、项目重构 +2. **Week 3**: 完成 RAG 系统优化、核心对话功能、首批知识库内容 +3. **Week 5**: 完成工程化配置、测试体系、评估系统 +4. **Week 6**: 完成文档、展示材料、准备简历项目描述 --- ## 📞 反馈与改进 -如有问题或建议，请提交 Issue 或 PR！ +如有问题或建议，请提交 Issue 或 PR！让我们一起打造更好的计算机学习伴侣！ From 5173d9ec6262f1646c39ceb889f501271291ef6f Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 05:40:28 +0000 Subject: [PATCH 03/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- docs/NEEDS_ANALYSIS_2026.md | 294 ++++++++++++++++++++++++++++++ docs/PRODUCT_FEATURES.md | 346 ++++++++++++++++++++++++++++++++++++ 2 files changed, 640 insertions(+) create mode 100644 docs/NEEDS_ANALYSIS_2026.md create mode 100644 docs/PRODUCT_FEATURES.md diff --git a/docs/NEEDS_ANALYSIS_2026.md b/docs/NEEDS_ANALYSIS_2026.md new file mode 100644 index 0000000..bb68fb8 --- /dev/null +++ b/docs/NEEDS_ANALYSIS_2026.md @@ -0,0 +1,294 @@ +# 2026 年计算机科学学习需求深度分析 + +> **一个好的产品，首先要有好的出发点——解决真实存在的问题** + +--- + +## 📊 背景：2026 年的 AI 与教育格局 + +### 2026 年的技术现状 +- **大模型已普及**：GPT-5、Claude 3、Qwen 3 等模型能力强大且成本低廉 +- **AI 工具泛滥**：市面上有无数的 AI 编程助手、学习平台 +- **信息过载**：获取知识容易，但获取**高质量、结构化的知识**很难 +- **信任危机**：AI 幻觉问题严重，学生不知道该相信什么 + +### 2026 年的教育现状 +- **知识更新加速**：新技术、新框架层出不穷，教材跟不上技术发展 +- **教育资源分布不均**：名校和普通学校的教育资源差距依然巨大 +- **实践机会不足**：很多学生学了理论，但不会写代码、不会解决实际问题 +- **个性化教育缺失**：大班教学无法照顾到每个学生的学习进度和理解方式 + +--- + +## 😫 痛点分析：计算机学习者真正在经历什么？ + +### 痛点一：AI 太"聪明"了，但我还是不懂 +> **场景**：小明在学算法，问 ChatGPT "什么是动态规划？" +> +> ChatGPT 给出了完美的定义、公式、代码示例。但小明看完还是困惑："这到底在说什么？为什么要用这个？" + +**问题本质**： +- 现有 AI 擅长**给出答案**，但不擅长**解释"为什么"** +- 它们用专家的语言说话，而不是用初学者能理解的语言 +- 它们跳过了思考过程，直接给出结论 + +**需求**： +- ✅ 能从**初学者视角**解释概念 +- ✅ 能用**类比、比喻**把复杂问题变简单 +- ✅ 能**展示思考过程**，而不仅仅是答案 +- ✅ 能**层层递进**，从直觉到严谨 + +--- + +### 痛点二：我学了，但一用就错 +> **场景**：小红背完了排序算法，LeetCode 做题时还是写不对。要么边界条件错了，要么时间复杂度没考虑到。 + +**问题本质**： +- 理论学习和实践应用之间有巨大鸿沟 +- 学生不知道"**在什么情况下用什么**" +- 学生不理解"**为什么这样写是对的，那样写是错的**" +- 缺乏对**常见错误**的总结和警示 + +**需求**： +- ✅ 能指出**常见错误和陷阱** +- ✅ 能对比**不同方案的优劣** +- ✅ 能给出**可运行的、健壮的**代码示例 +- ✅ 能提供**调试建议** +- ✅ 能设计**有针对性的练习题** + +--- + +### 痛点三：AI 有时候会胡说八道，我不敢信 +> **场景**：小刚在用 AI 查一个冷门的数据结构，AI 说得头头是道，但小刚去翻教材发现根本不是那么回事。 + +**问题本质**： +- AI 幻觉（Hallucination）问题依然存在 +- 学生**缺乏判断知识真伪的能力** +- 网上的资料质量参差不齐，难以辨别 +- AI 从不承认"我不知道"，总是试图编造答案 + +**需求**： +- ✅ 能**诚实面对知识边界**，明确说"我不知道" +- ✅ 能**标注知识来源**，让学生可以验证 +- ✅ 能**区分"确定知识"和"推断内容"** +- ✅ 能**引用权威来源**（教材、官方文档、经典论文） + +--- + +### 痛点四：知识是零散的，我不知道从哪开始 +> **场景**：小芳想系统学习机器学习，但网上有无数的教程、视频、课程。她今天看这个，明天看那个，三个月过去了还是没入门。 + +**问题本质**： +- 缺乏**结构化的学习路径** +- 知识之间的**联系没有建立** +- 学生不知道**自己现在处于什么水平** +- 学生不知道**下一步该学什么** + +**需求**： +- ✅ 能提供**系统化的知识体系** +- ✅ 能**评估学习水平** +- ✅ 能**推荐个性化的学习路径** +- ✅ 能**追踪学习进度** +- ✅ 能建立**知识之间的关联** + +--- + +### 痛点五：问了一堆 AI，还是找不到人讨论 +> **场景**：小华在做项目时遇到一个复杂的 bug，问了好几个 AI 都没解决。他想找人讨论，但身边的同学也不懂，论坛上提问又没人回答。 + +**问题本质**： +- AI 缺乏**真实的理解和共情** +- 某些复杂问题需要**交互式的深入探讨** +- 学习者需要**社区归属感** +- 人与人的**思维碰撞**是 AI 无法替代的 + +**需求**： +- ✅ 能连接**有相似问题的学习者** +- ✅ 能**沉淀高质量的问答内容** +- ✅ 能提供**社区讨论空间** +- ✅ 能让**AI 和人协作** + +--- + +### 痛点六：教材太老，新技术学不到 +> **场景**：小磊在学校学的是 Java 8，但业界已经在用 Java 21 了；学校教的是 TensorFlow 1.x，但现在主流是 PyTorch 2.x。 + +**问题本质**： +- 教材更新周期长，跟不上技术发展 +- 学校课程和业界需求**脱节** +- 新技术资料零散，缺乏系统性整理 +- 学生不知道**哪些是真正重要的、值得学的** + +**需求**： +- ✅ 能**持续更新**知识库 +- ✅ 能**区分"经典基础知识"和"新兴技术"** +- ✅ 能**介绍业界最佳实践** +- ✅ 能**提供技术趋势分析** + +--- + +## 🎯 需求总结：我们到底需要什么？ + +### 核心需求一：一个"懂"我水平的老师 +- 不是用同样的方式教所有人 +- 能判断我知道什么、不知道什么 +- 能用我听得懂的话解释 + +### 核心需求二：一个不胡说八道的顾问 +- 知道就是知道，不知道就是不知道 +- 每句话都要有依据 +- 让我能追溯知识来源 + +### 核心需求三：一个能帮我实践的教练 +- 不仅讲理论，更要教我怎么用 +- 帮我避开常见陷阱 +- 给我有针对性的练习 + +### 核心需求四：一个能指路的向导 +- 告诉我现在在哪 +- 告诉我该往哪走 +- 帮我规划路线 + +### 核心需求五：一个能交流的伙伴 +- 陪我讨论，而不只是单向输出 +- 连接志同道合的人 +- 建立学习社区 + +--- + +## 💡 机会：现有产品的不足 + +| 产品类型 | 优势 | 不足 | 我们的机会 | +|---------|------|------|-----------| +| **通用 AI 助手** (GPT-5、Claude) | 能力强，响应快 | 容易幻觉、不够专业、不能因材施教 | 垂直领域深耕、知识库锚定、个性化 | +| **在线课程平台** (Coursera、慕课) | 内容系统、有老师讲解 | 不够灵活、更新慢、缺乏互动 | 个性化学习路径、即时答疑、实践导向 | +| **编程 AI 助手** (GitHub Copilot、Cursor) | 代码能力强、提升效率 | 不教你"为什么"、缺乏理论讲解 | 理论实践结合、解释代码思路 | +| **刷题平台** (LeetCode、牛客) | 题库丰富、有社区 | 缺乏系统学习、答案质量参差不齐 | 系统学习 + 刷题、高质量题解 | +| **教材/教科书** | 权威、系统 | 更新慢、枯燥、缺乏互动 | 保持权威性 + 现代化交互 + 持续更新 | + +--- + +## 🔍 用户画像与场景 + +### 画像一：迷茫的大一新生 - 小林 +- **背景**：刚上大学，第一次接触编程，完全听不懂课 +- **痛点**： + - 老师讲得太快，跟不上 + - 书上的概念太抽象，看不懂 + - 写代码时，连错误提示都看不懂 +- **需求**： + - 能用大白话解释概念 + - 从"Hello World"开始，一步步教 + - 能帮我看懂错误信息 + +### 画像二：努力的大二学生 - 小王 +- **背景**：学了一年编程，能写简单的代码，但遇到难题就懵 +- **痛点**： + - 数据结构、算法课听得懂，但做题不会 + - 不知道为什么代码能跑，但换个场景就不行 + - 想深入学，但不知道从哪开始 +- **需求**： + - 能把理论和题目结合起来讲 + - 能分析"为什么这样写" + - 能给我学习路径建议 + +### 画像三：焦虑的大三学生 - 小张 +- **背景**：要找工作了，发现好多东西都不会，需要突击复习 +- **痛点**： + - 知识点太多，记不住 + - 面试题千变万化，不知道怎么准备 + - 学过的东西容易忘 +- **需求**： + - 能帮我系统复习 + - 能预测面试考点 + - 能提供记忆技巧 + +### 画像四：转行的程序员 - 小李 +- **背景**：从传统行业转行，自学编程，没人教 +- **痛点**： + - 不知道学的是不是对的 + - 没人讨论，遇到问题卡壳 + - 不知道业界真正在用什么 +- **需求**： + - 能告诉我什么是重要的 + - 能连接到学习伙伴 + - 能介绍业界最佳实践 + +### 画像五：工作了的工程师 - 小赵 +- **背景**：工作几年，想学习新技术，或者给新人培训 +- **痛点**： + - 时间有限，想学得快一点 + - 新技术资料太散 + - 想系统地教新人，但不知道怎么讲 +- **需求**： + - 能快速定位到需要的知识 + - 有高质量的技术总结 + - 有适合教学的内容 + +--- + +## 🚀 我们的切入点：做 AI 时代的"数字导师" + +不是另一个 AI 聊天机器人，而是： + +### 1. **知识优先，AI 为辅** +- 先有高质量的知识库，AI 只是更好地呈现这些知识 +- 每一个回答都锚定在可靠的知识源上 +- AI 的作用是解释、引导、个性化，而不是创造知识 + +### 2. **系统化，而非碎片化** +- 建立完整的计算机科学知识体系 +- 知识之间建立关联，形成网络 +- 提供从入门到进阶的完整学习路径 + +### 3. **个性化，而非标准化** +- 了解用户的水平和学习风格 +- 用适合用户的方式解释 +- 动态调整学习内容和进度 + +### 4. **实践导向，而非纸上谈兵** +- 理论和代码并重 +- 强调"为什么"和"怎么用" +- 提供练习、调试建议、常见错误 + +### 5. **可信赖，而非随意编造** +- 诚实地面对知识边界 +- 每句话都有来源 +- 让用户可以验证 + +--- + +## 📈 成功的标尺 + +如果我们做好了，用户会这样说： + +> **"终于搞懂了！之前看了好多资料都没明白，现在一下子就懂了。"** +> —— 解决了"讲不明白"的问题 + +> **"照着这个写，第一次就跑通了！而且还知道为什么这样写。"** +> —— 解决了"不会用"的问题 + +> **"这个说得靠谱，我去翻了教材，确实是这样。"** +> —— 解决了"不可信"的问题 + +> **"它知道我哪里不懂，总是在我卡壳的时候点醒我。"** +> —— 解决了"不个性化"的问题 + +> **"跟着这个学，我知道现在该干什么，下一步该学什么。"** +> —— 解决了"没方向"的问题 + +--- + +## 🎯 总结：我们要解决的核心问题 + +| 问题 | 现有产品的解决方案 | 我们的解决方案 | +|------|-----------------|--------------| +| **讲不明白** | 用复杂的语言讲复杂的概念 | 用简单的语言、类比、比喻讲复杂的概念 | +| **不会用** | 只给代码，不给解释 | 讲思路、讲原理、讲常见错误 | +| **不可信** | 编造答案，从不认错 | 诚实面对边界，知识来源可追溯 | +| **没方向** | 碎片化内容，没有体系 | 系统化知识体系，个性化学习路径 | +| **没同伴** | 单向输出，没有交互 | 社区协作，AI 与人结合 | + +--- + +**这就是 ByteBrain 存在的意义——成为 AI 时代每一位计算机学习者的"数字导师"。** diff --git a/docs/PRODUCT_FEATURES.md b/docs/PRODUCT_FEATURES.md new file mode 100644 index 0000000..c48437d --- /dev/null +++ b/docs/PRODUCT_FEATURES.md @@ -0,0 +1,346 @@ +# ByteBrain 产品功能规划 + +> 基于 2026 年需求分析的具体功能设计 + +--- + +## 🎯 核心功能矩阵 + +| 需求痛点 | 核心功能 | 设计原则体现 | +|---------|---------|-------------| +| AI 太"聪明"了，但我还是不懂 | 智能解释引擎 | 因材施教、知识优先 | +| 我学了，但一用就错 | 实践指导系统 | 实践导向 | +| AI 会胡说八道，我不敢信 | 知识溯源与可信机制 | 可信赖 | +| 知识零散，不知道从哪开始 | 学习路径规划 | 系统化、因材施教 | +| 找不到人讨论 | 社区协作模块 | 简洁优雅（可选但有价值） | + +--- + +## 🧠 功能一：智能解释引擎（解决"讲不明白"） + +### 1.1 多级解释模式 +- **入门级**：用大白话、类比、生活中的例子解释 + - 示例："指针就像你家的门牌号，通过门牌号能找到房子" +- **进阶级**：开始引入专业术语，但仍然详细解释 +- **专家级**：严谨的学术定义，数学推导，性能分析 + +### 1.2 思考过程展示 +- 不是直接给答案，而是展示"如何想到这个答案" +- 示例： + > "让我想想怎么解释递归... + > + > 首先，递归的核心是'自己调用自己'... + > 我们可以用'俄罗斯套娃'来类比... + > 来看一个简单的例子：阶乘..." + +### 1.3 追问引导 +- 不是回答完就结束，而是主动提出下一步问题 +- 示例： + > "明白了二分查找的基本思想了吗？ + > + > 要不要我给你讲一讲： + > 1. 为什么数组必须有序？ + > 2. 时间复杂度为什么是 O(log n)？ + > 3. 常见的边界错误有哪些？" + +### 1.4 可视化辅助 +- 对复杂概念，提供 ASCII 图或 Mermaid 流程图 +- 示例（二分查找过程）： + ``` + 初始状态: [1, 3, 5, 7, 9, 11, 13] 目标: 9 + ↑ ↑ ↑ + left mid right + + 第1次比较: mid = 5 < 9，搜索右半部分 + ``` + +--- + +## 💻 功能二：实践指导系统（解决"不会用"） + +### 2.1 健壮代码示例 +- 每个示例都要： + - 可直接运行 + - 有完整的注释 + - 包含边界检查 + - 有使用示例 + +- 反模式：只给核心逻辑，不给完整代码 +- 正确示例（二分查找）： + ```python + def binary_search(arr: list, target: any) -> int: + """ + 二分查找实现 + + Args: + arr: 有序数组（必须提前排序！） + target: 要查找的目标值 + + Returns: + 目标值的索引，如果不存在返回 -1 + + Raises: + TypeError: 如果输入不是列表 + """ + # 输入校验 + if not isinstance(arr, list): + raise TypeError("arr 必须是列表类型") + + left, right = 0, len(arr) - 1 + + while left <= right: + # 注意：用这种方式避免整数溢出（虽然 Python 不会溢出，但这是好习惯） + mid = left + (right - left) // 2 + + if arr[mid] == target: + return mid # 找到目标！ + elif arr[mid] < target: + left = mid + 1 # 目标在右边，移动左边界 + else: + right = mid - 1 # 目标在左边，移动右边界 + + return -1 # 遍历完了也没找到 + ``` + +### 2.2 常见错误警示 +- 列出这个知识点最常犯的 3-5 个错误 +- 每个错误包含： + - 错误代码示例 + - 为什么这是错的 + - 如何修复 + - 如何避免 + +- 示例（二分查找常见错误）： + | 错误 | 错误代码 | 问题 | 修复 | + |------|---------|------|------| + | 边界条件错 | `while left < right` | 会漏掉最后一个元素 | `while left <= right` | + | 更新边界漏 +1/-1 | `left = mid` | 会死循环 | `left = mid + 1` | + | 整数溢出 | `mid = (left + right) // 2` | 大整数时可能溢出 | `mid = left + (right - left) // 2` | + +### 2.3 方案对比分析 +- 当有多种实现方式时，对比它们的优劣 +- 示例（排序算法对比）： + | 算法 | 时间(平均) | 时间(最坏) | 空间 | 稳定 | 适用场景 | + |------|-----------|-----------|------|------|---------| + | 快速排序 | O(n log n) | O(n²) | O(log n) | ❌ | 通用、大数据量 | + | 归并排序 | O(n log n) | O(n log n) | O(n) | ✅ | 需要稳定排序 | + | 堆排序 | O(n log n) | O(n log n) | O(1) | ❌ | 内存受限 | + +### 2.4 调试工具箱 +- 提供调试这个知识点的实用技巧 +- 示例（调试递归）： + - 技巧 1：打印调用栈 + - 技巧 2：减少输入规模 + - 技巧 3：用迭代重写一遍 + - 技巧 4：画出递归树 + +### 2.5 针对性练习设计 +- 每个知识点配 3 道练习题： + - 简单题：巩固基础 + - 中等题：灵活运用 + - 挑战题：综合应用 + +- 每道题包含： + - 题目描述 + - 提示（不直接给答案） + - 参考答案（带详细解释） + +--- + +## ✅ 功能三：知识溯源与可信机制（解决"不可信"） + +### 3.1 知识来源标注 +- 每个知识条目都标注： + - 来源类型：教材/官方文档/论文/权威博客 + - 具体来源：如《算法导论》第 3 章，或 Python 3.12 官方文档 + - 可信度评级：⭐⭐⭐⭐⭐（5星最高） + +- UI 展示示例： + ``` + 📚 知识来源：《算法导论》第 3 章 + ⭐⭐⭐⭐⭐ 可信度：权威教材 + ``` + +### 3.2 诚实的"不知道" +- 当知识库中没有相关知识时，明确说： + > "抱歉，这个问题超出了我的知识范围。 + > + > 建议你查阅： + > 1. [相关教材章节] + > 2. [官方文档链接] + > + > 或者换一个问法试试？" + +- 永远不要： + - ❌ 编造答案 + - ❌ 含糊其辞 + - ❌ 用"可能是"、"应该是"蒙混 + +### 3.3 确定 vs 推断区分 +- 用不同的样式展示： + - **确定知识**（来自知识库）：正常显示 + - **推断内容**（AI 推理得出）：用灰色小字标注"这是 AI 的推断，仅供参考" + +- 示例： + ``` + 二分查找的时间复杂度是 O(log n)。 + └─ 📚 来自《算法导论》 + + 这个问题应该可以用二分查找来解决。 + └─ 💡 AI 推断，仅供参考 + ``` + +### 3.4 可验证的引用 +- 对于重要知识，提供原文引用 +- 如果是电子化的知识，提供跳转链接 +- 示例： + > 根据《深入理解计算机系统》第 6 章： + > + > > "局部性原理指出，程序倾向于引用邻近于其他最近引用过的数据项的数据项。" + > + > [点击查阅原文](链接到电子书或在线资源) + +--- + +## 🗺️ 功能四：学习路径规划（解决"没方向"） + +### 4.1 知识体系图谱 +- 构建完整的计算机科学知识体系 +- 可视化展示知识之间的依赖关系 +- 示例结构： + ``` + 数据结构与算法 + ├── 线性表 + │ ├── 数组 ← 学习链表前需要先懂数组 + │ ├── 链表 + │ ├── 栈 + │ └── 队列 + ├── 树与图 + │ ├── 二叉树 + │ ├── 二叉搜索树 ← 依赖二叉树 + │ └── 图 + └── ... + ``` + +### 4.2 水平评估测试 +- 入门测试：10-15 道题，判断当前水平 +- 每个知识点有前置测试，判断是否需要学习 +- 测试结果可视化： + ``` + 你的当前水平：📊 大二上学期 + 已掌握：数组、链表、栈、队列 + 建议学习：二叉树 → 二分查找 → 排序算法 + ``` + +### 4.3 个性化学习路径 +- 根据水平和目标，生成专属学习计划 +- 示例（目标：3 个月后找工作）： + ``` + 🎯 你的学习路径（12 周） + + 第 1-2 周：数据结构复习 + ├── 数组与链表（Day 1-3） + ├── 栈与队列（Day 4-5） + ├── 树与图（Day 6-10） + └── 哈希表（Day 11-14） + + 第 3-5 周：算法基础 + ├── 排序算法 + ├── 查找算法 + ├── 递归与分治 + └── 动态规划入门 + + ... + ``` + +### 4.4 学习进度追踪 +- 可视化展示学习进度 +- 标记已掌握、学习中、未开始的知识点 +- 记录学习时长和练习正确率 +- 成就系统：解锁"算法达人"、"代码能手"等徽章 + +--- + +## 👥 功能五：社区协作（可选但有价值） + +### 5.1 高质量问答沉淀 +- 用户问得好的问题，AI 答得好的答案，可以沉淀到知识库 +- 社区审核机制，确保沉淀内容的质量 +- 点赞、收藏、分享功能 + +### 5.2 学习伙伴匹配 +- 根据学习水平、目标、进度，匹配学习伙伴 +- 小组学习功能，一起刷题、讨论 +- peer review 机制，互相检查代码 + +### 5.3 AI + 人协作 +- 复杂问题先由 AI 回答，不满意可以转给人工 +- 专家入驻，提供高质量解答 +- 社区贡献者激励机制 + +--- + +## 🎨 UI/UX 设计原则 + +### 简洁优雅 +- 界面简洁，不分散注意力 +- 深色/浅色主题切换 +- 响应式设计，手机、平板、电脑都能用 + +### 即时反馈 +- 加载状态："正在思考中..." +- 打字机效果：逐字显示回答，增强对话感 +- 错误友好：出错时给出清晰提示和解决方案 + +### 知识可视化 +- 代码高亮：支持多种编程语言 +- 公式渲染：LaTeX 公式支持 +- 图表绘制：Mermaid、ASCII 图 +- Markdown 渲染：支持完整的 Markdown 语法 + +--- + +## 🚀 MVP 功能优先级 + +### 第一阶段（必须有，4-6 周） +- ✅ 知识库基础框架（50-100 条高质量知识） +- ✅ 基础 RAG 检索（知识溯源） +- ✅ 多级解释（入门/进阶） +- ✅ 健壮代码示例 + 常见错误 +- ✅ 诚实的"不知道" +- ✅ 简洁优雅的 UI + +### 第二阶段（应该有，4-6 周） +- ✅ 知识体系图谱 +- ✅ 水平评估测试 +- ✅ 学习进度追踪 +- ✅ 思考过程展示 +- ✅ 练习题系统 +- ✅ 方案对比分析 + +### 第三阶段（可以有，长期） +- ✅ 个性化学习路径 +- ✅ 社区协作模块 +- ✅ 学习伙伴匹配 +- ✅ AI + 人协作 +- ✅ 成就系统 + +--- + +## 📊 成功指标 + +### 用户指标 +- **理解度**：用户说"终于懂了"的比例 > 80% +- **实用度**：用户用我们的代码一次跑通的比例 > 70% +- **信任度**：用户验证后说"说得对"的比例 > 90% +- **留存率**：周活跃用户比例 > 40% + +### 技术指标 +- **知识库规模**：1000+ 高质量知识条目 +- **检索准确率**：Top 3 命中 > 85% +- **响应速度**：平均 < 3 秒 +- **系统可用性**：> 99.5% + +--- + +这就是基于 2026 年需求分析的 ByteBrain 完整功能规划！ From d246d6ac8f6055f6487d76ac4fa33a421f588e2e Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 05:44:19 +0000 Subject: [PATCH 04/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- docs/AI_AGENT_STRATEGY.md | 376 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 docs/AI_AGENT_STRATEGY.md diff --git a/docs/AI_AGENT_STRATEGY.md b/docs/AI_AGENT_STRATEGY.md new file mode 100644 index 0000000..cb2a90d --- /dev/null +++ b/docs/AI_AGENT_STRATEGY.md @@ -0,0 +1,376 @@ +# MCP、Skill、Agent 如何赋能 ByteBrain + +> 让"数字导师"更智能、更强大、更实用 + +--- + +## 📖 概念速览 + +在开始之前，让我们先简单理解这些概念： + +| 概念 | 通俗解释 | 核心价值 | +|------|---------|---------| +| **MCP (Model Context Protocol)** | AI 应用的"通用插座"，让 AI 能连接各种工具和数据源 | 标准化、互操作性 | +| **Skill (技能)** | AI 的"专项能力"，比如"画图"、"查天气"、"写代码" | 专业化、模块化 | +| **Agent (智能体)** | 能自主思考、规划、执行的 AI，像一个"虚拟员工" | 自主性、复杂任务处理 | + +--- + +## 🎯 核心思路：ByteBrain 不是一个 AI，而是一个**AI 导师团队** + +不要把 ByteBrain 想成"一个聊天机器人"，而是： + +``` +🎓 ByteBrain 导师团队 +├── 📚 知识检索专员 (Knowledge Agent) +├── 💻 代码教练 (Code Coach Agent) +├── 🧠 概念解释专家 (Concept Explainer Agent) +├── 🗺️ 学习规划师 (Learning Path Agent) +├── 🐛 调试顾问 (Debug Advisor Agent) +└── 📊 评估分析师 (Evaluation Agent) +``` + +每个 Agent 都有自己的专长，它们协作起来，就是一个完整的"计算机科学教育团队"！ + +--- + +## 🔧 MCP (Model Context Protocol)：连接一切的桥梁 + +### MCP 能为 ByteBrain 做什么？ + +MCP 就像一个**万能接口**，让我们的 AI 导师能够： + +### 1. 连接更多知识源 +不只是本地的 [knowledge.txt](file:///workspace/knowledge.txt)，还能： +- 📚 实时查询在线教材（如 CLRS、CSAPP 的在线版） +- 🌐 搜索权威技术文档（MDN、Python 官方文档） +- 📄 读取用户上传的 PDF、Word、PPT +- 📊 连接学术数据库（IEEE、ACM） +- 🎥 甚至能分析视频课程内容 + +**示例场景**： +> 用户问："帮我看看我上传的这个算法课件，给我解释一下红黑树" +> +> ByteBrain 通过 MCP 读取 PDF → 理解内容 → 结合知识库 → 给出个性化解释 + +### 2. 连接开发工具 +让我们的"代码教练"能够： +- 💻 直接读取用户的代码文件 +- 🔍 调用静态分析工具检查代码 +- 🧪 运行单元测试并分析结果 +- 📝 连接 IDE（VS Code、PyCharm） + +**示例场景**： +> 用户问："我这个二分查找为什么死循环了？帮我看看 `binary_search.py`" +> +> ByteBrain 通过 MCP 读取文件 → 静态分析 → 定位问题 → 给出修复方案 + +### 3. 连接学习平台 +- 📊 同步 LeetCode、牛客的做题记录 +- 🎓 连接慕课、Coursera 的学习进度 +- 📈 获取用户的学习数据，个性化推荐 + +--- + +## 🛠️ Skill：让"数字导师"拥有专项技能 + +### ByteBrain 需要哪些 Skill？ + +我们可以把 ByteBrain 的能力拆分成多个独立的 Skill，每个 Skill 专注做好一件事： + +### Skill 1：知识检索与溯源 (Knowledge Retrieval Skill) +**功能**： +- 在知识库中精准检索相关内容 +- 标注知识来源和可信度 +- 当知识不足时，诚实说"不知道" + +**为什么用 Skill**： +- 可以独立优化检索算法 +- 可以切换不同的检索后端（BM25、向量检索、混合检索） +- 可以 A/B 测试不同检索策略 + +**示例实现思路**： +```python +class KnowledgeRetrievalSkill: + """知识检索技能""" + + def __init__(self, knowledge_base): + self.knowledge_base = knowledge_base + + def execute(self, query: str, top_k: int = 3) -> dict: + """ + 执行检索 + + Returns: + { + "has_knowledge": bool, + "results": [ + { + "content": str, + "source": str, + "confidence": float + } + ], + "suggestion": str # 如果知识不足，给出建议 + } + """ + # 实现检索逻辑 + pass +``` + +--- + +### Skill 2：多级概念解释 (Concept Explanation Skill) +**功能**： +- 根据用户水平，选择入门/进阶/专家级解释 +- 自动生成类比和比喻 +- 提供可视化辅助（ASCII 图、Mermaid 流程图） + +**为什么用 Skill**： +- 可以独立优化提示词 +- 可以针对不同学科（算法、系统、网络等）定制解释风格 +- 可以收集用户反馈，持续优化解释质量 + +--- + +### Skill 3：代码审查与优化 (Code Review Skill) +**功能**： +- 检查代码正确性 +- 识别常见错误和边界问题 +- 提供性能优化建议 +- 指出代码风格问题 + +**为什么用 Skill**： +- 可以连接专业的代码分析工具（通过 MCP） +- 可以针对不同语言（Python、Java、C++）定制 +- 可以结合 LeetCode 等平台的题解 + +--- + +### Skill 4：练习题生成 (Exercise Generation Skill) +**功能**： +- 根据知识点生成针对性练习 +- 简单/中等/困难三级难度 +- 提供提示（不直接给答案） +- 生成带详细解释的参考答案 + +--- + +### Skill 5：学习路径规划 (Learning Path Skill) +**功能**： +- 评估用户当前水平 +- 生成个性化学习计划 +- 动态调整学习进度 +- 推荐前置知识和后续学习内容 + +--- + +## 🤖 Agent：让"数字导师"自主工作 + +### 为什么 ByteBrain 需要 Agent？ + +之前的思路是：**用户问 → 检索 → 回答** + +有了 Agent 之后，可以变成：**用户问 → 理解意图 → 规划步骤 → 调用多个 Skill → 整合结果 → 给出完整方案** + +### Agent 1：知识检索专员 (Knowledge Agent) +**职责**： +- 判断用户问题是否在知识库范围内 +- 如果在，检索相关知识并标注来源 +- 如果不在，诚实说"不知道"并建议查阅资料 +- 决定是否需要补充检索（比如"这个问题还需要查一下官方文档"） + +**思考流程示例**： +``` +用户问题："什么是红黑树？" + +Knowledge Agent 思考： +1. 检索知识库 → 找到了 3 条相关内容 +2. 检查来源 → 《算法导论》第 13 章，可信度 ⭐⭐⭐⭐⭐ +3. 检查是否完整 → 有定义、性质、旋转操作，但缺少示例 +4. 决策 → 用现有知识回答，但注明"建议配合图示理解" +``` + +--- + +### Agent 2：代码教练 (Code Coach Agent) +**职责**： +- 理解用户的代码问题 +- 决定需要哪些 Skill（代码审查？调试建议？优化方案？） +- 调用相应 Skill +- 整合结果，给出完整指导 + +**工作流程示例**： +``` +用户问题："我的二分查找死循环了，帮我看看" + ↓ +Code Coach Agent 分析： +1. 需要：读取代码 + 静态分析 + 常见错误检查 +2. 调用 Skill： + - Code Reading Skill（读取文件） + - Code Analysis Skill（静态分析） + - Common Mistake Skill（检查二分查找常见错误） + ↓ +发现问题：边界条件是 `left < right`，应该是 `left <= right` + ↓ +整合回答： +1. 指出问题所在 +2. 解释为什么会导致死循环 +3. 给出修复代码 +4. 附上"二分查找常见错误"清单 +``` + +--- + +### Agent 3：概念解释专家 (Concept Explainer Agent) +**职责**： +- 评估用户的知识水平（从对话历史推断） +- 选择合适的解释深度（入门/进阶/专家） +- 决定是否需要类比、可视化、示例 +- 生成引导性的追问 + +**工作流程示例**： +``` +用户问题："什么是动态规划？" + ↓ +Concept Explainer Agent 分析： +1. 查看用户历史 → 之前问过"什么是递归"，处于入门水平 +2. 决策 → 用入门级解释 +3. 需要：类比 + 简单示例 + 可视化 + ↓ +生成回答： +1. 用"斐波那契数列"作为类比 +2. 画一个简单的递归树图 +3. 给出最简单的动态规划代码示例 +4. 最后问："明白了吗？要不要我给你讲一讲状态转移方程？" +``` + +--- + +### Agent 4：学习规划师 (Learning Path Agent) +**职责**： +- 全面评估用户的知识体系 +- 识别知识 gaps +- 生成长期学习计划 +- 动态调整计划 + +--- + +## 🏗️ 整体架构设计 + +### Multi-Agent 协作架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户界面层 (Streamlit UI) │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 主协调器 (Orchestrator) │ +│ • 理解用户意图 │ +│ • 分配任务给相应的 Agent │ +│ • 整合多个 Agent 的结果 │ +└──────────────┬───────────────┬───────────────┬──────────────┘ + │ │ │ │ + ┌───────▼───────┐ ┌───▼─────────┐ ┌─▼────────────┐ ┌▼──────────────┐ + │ Knowledge │ │ Code │ │ Concept │ │ Learning │ + │ Agent │ │ Coach │ │ Explainer │ │ Path Agent │ + └───────┬───────┘ └───┬─────────┘ └─┬────────────┘ └─┬──────────────┘ + │ │ │ │ + ┌───────▼───────┐ ┌───▼─────────┐ ┌─▼────────────┐ ┌▼──────────────┐ + │ Retrieval │ │ Code Review │ │ Explanation │ │ Path Planner │ + │ Skill │ │ Skill │ │ Skill │ │ Skill │ + └───────────────┘ └─────────────┘ └──────────────┘ └───────────────┘ + │ │ │ │ + └───────────────┴───────────────┴─────────────────┘ + │ + ▼ + ┌───────────────────────────────────┐ + │ MCP 协议层 │ + │ • 知识源连接 │ + │ • 开发工具连接 │ + │ • 学习平台连接 │ + └───────────────────────────────────┘ +``` + +--- + +## 🚀 分阶段实施路线图 + +### 阶段一：Skill 化（1-2 周） +先把现有功能拆分成独立的 Skill： + +- [ ] **Knowledge Retrieval Skill** - 知识检索 +- [ ] **Concept Explanation Skill** - 概念解释 +- [ ] **Code Example Skill** - 代码示例生成 + +**为什么先做 Skill**： +- 风险低，容易上手 +- 可以立即看到效果 +- 为后续的 Agent 打基础 + +--- + +### 阶段二：引入 MCP（2-3 周） +添加 MCP 支持，连接更多数据源： + +- [ ] 支持读取 PDF、Word 文档 +- [ ] 支持查询在线技术文档 +- [ ] 支持读取用户代码文件 + +**价值**： +- 让 ByteBrain 能处理用户的个性化资料 +- 不再局限于预置的知识库 + +--- + +### 阶段三：简单 Agent（3-4 周） +实现 1-2 个核心 Agent： + +- [ ] **Knowledge Agent** - 知识检索 + 溯源 + 诚实的"不知道" +- [ ] **Code Coach Agent** - 代码审查 + 调试建议 + +**价值**： +- 开始体现"智能"，而不只是"搜索+回答" +- 用户体验显著提升 + +--- + +### 阶段四：完整 Multi-Agent（长期） +实现完整的导师团队： + +- [ ] **Concept Explainer Agent** +- [ ] **Learning Path Agent** +- [ ] **Evaluation Agent** +- [ ] Agent 之间的协作机制 + +--- + +## 💡 简历亮点：如何描述这些技术 + +### 基础版（适合简历） +- 采用 **Skill 模块化设计**，将知识检索、概念解释、代码审查等能力拆分为独立模块，提升可维护性和可扩展性 +- 探索 **MCP (Model Context Protocol)** 应用，支持连接多种知识源和开发工具 +- 设计 **Multi-Agent 协作架构**，由知识专员、代码教练、学习规划师等智能体组成"导师团队" + +### 进阶版（适合面试） +- **Skill 体系**：将 AI 能力解耦为多个专项 Skill，每个 Skill 专注单一任务，便于独立优化和 A/B 测试 +- **MCP 集成**：通过 MCP 协议连接外部工具和数据源，打破信息孤岛，实现"用户上传课件 → AI 理解 → 个性化解释"的完整流程 +- **Multi-Agent 系统**：设计由多个专业 Agent 组成的协作系统，每个 Agent 有清晰的职责边界和思考流程，通过 Orchestrator 协调，模拟真实的"导师团队"工作方式 + +--- + +## 🎯 总结：这些技术对 ByteBrain 的核心价值 + +| 技术 | 为 ByteBrain 带来什么 | 简历中的描述 | +|------|---------------------|-------------| +| **Skill** | 模块化、可维护、可测试、可优化 | Skill 模块化设计，提升可扩展性 | +| **MCP** | 连接外部世界（文档、工具、平台） | MCP 协议集成，扩展能力边界 | +| **Agent** | 自主性、复杂任务处理、协作 | Multi-Agent 协作架构，模拟导师团队 | + +--- + +**核心观点**：这些技术不是"炫技"，而是真正能让 ByteBrain 从"一个好用的工具"变成"一位真正的导师"！ + +现在，ByteBrain 不再是一个简单的问答机器人，而是一个**由多个专业智能体组成的 AI 导师团队**！ From 5bc1e1b68ef9ed44ff74ad131d3cd23981420b87 Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 05:54:57 +0000 Subject: [PATCH 05/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- README.md | 275 ++++++++++++++++++++--------- docs/PROJECT_POSITIONING.md | 273 +++++++++++++++++++++++++++++ docs/TECH_PLAYGROUND_2026.md | 324 +++++++++++++++++++++++++++++++++++ 3 files changed, 789 insertions(+), 83 deletions(-) create mode 100644 docs/PROJECT_POSITIONING.md create mode 100644 docs/TECH_PLAYGROUND_2026.md diff --git a/README.md b/README.md index c76626e..5a3ce15 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,225 @@ -# **ByteBrain** +# ByteBrain -**信息时代您的计算机科学智能知识助手 -2024-Datawhale-AISummerCamp-IV -Development-of-Large-scale-Model-Applications** +> **AI 时代你的智能助手 / 数字分身** +> +> 一个基于 RAG 和 Multi-Agent 的个人知识管理系统，同时也是 AI 技术的实战试验场 + +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/) +[![LangGraph](https://img.shields.io/badge/LangGraph-0.3+-green.svg)](https://github.com/langchain-ai/langgraph) +[![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io/) --- -## 一键部署体验 - -```mermaid -graph LR -A(魔塔社区) --> B(我的NoteBook) -B --> C(魔搭平台免费实例) -B -->G(个人云账号授权实例) -G -->H(PAI-DSW) -H -->F -C-->D(PAI-DSW) -D-->E(GPU环境) -E-->F(启动!!!) -``` +## 🎯 项目定位 -`1、个人云账号授权实例：可以开通阿里云PAI-DSW试用，时长三个月` -`2、魔塔平台免费实例：注册并绑定阿里云账号试用GPU，时长100h` +ByteBrain 不仅仅是一个项目，它有三重价值： -```powershell -# JupyterLab->Other->Terminal->Ctrl+V -git clone https://github.com/Stars-niu/ByteBrain.git -cd ByteBrain -pip install --upgrade pip setuptools -pip install -r requirements.txt -python finetune_model.py -pip install streamlit -pip install tf-keras -streamlit run app.py --server.address 127.0.0.1 --server.port 1005 -``` +### 1. 实用价值：你的"第二大脑" +- 上传你的 Markdown 笔记，构建个人知识库 +- 语义检索，找到真正相关的内容 +- 知识图谱，看到知识之间的联系 +- 主动推荐，发现你可能感兴趣的内容 + +### 2. 学习价值：AI 技术试验场 +在解决真实问题中掌握 2026 年最火的 AI 技术： +- **Agent 框架**：LangGraph、CrewAI +- **RAG 技术**：LlamaIndex、向量数据库 +- **AI 协议**：MCP (Model Context Protocol) +- **工程化**：Docker、CI/CD、监控 + +### 3. 简历价值：企业级技术栈 +掌握企业最需要的 AI 技能： +- RAG 系统（企业知识库、智能客服） +- Agent 开发（自动化工作流） +- MCP 协议（AI 工具集成） +- 向量数据库（语义搜索） + +--- + +## ✨ 核心功能 + +### 📚 知识管理 +- 支持 Markdown 文件上传 +- 自动向量化存储 +- 语义检索与关键词检索混合 +- 知识溯源与引用 -### 问题注意: -- app.py根据使用的版本自行更换 -- 重复打开应用时，可以更换监听端口的四个数字(即1001)，如果出现某端口已占用的情况。补充:127.0.0.1:表示服务器只监听本地回环地址，也就是说，只有在本机上的浏览器才能访问这个应用。(如果你想让其他设备也能访问，可以设置为 0.0.0.0) 1001:这个选项指定了Streamlit服务器监听的端口。这里设置为 1001，意味着应用程序将在 http://127.0.0.1:1001 地址上运行。 +### 🤖 智能问答 +- 基于你的笔记回答问题 +- 多级解释（入门/进阶/专家） +- 追问引导，深入理解 +- 代码示例与常见错误 + +### 🔗 数据连接（MCP） +- 连接本地文件系统 +- 连接云笔记工具（Notion、Obsidian） +- 连接代码仓库（GitHub） +- 标准化数据接入 + +### 🧠 Multi-Agent 协作 +- 知识整理 Agent：自动分类、打标签 +- 知识问答 Agent：检索 + 解释 + 引用 +- 知识扩展 Agent：推荐相关内容 +- 学习规划 Agent：个性化学习路径 --- -## RAG（Retrieval-Augmented Generation） -这个名字听起来可能有点复杂，但实际上它就是一个帮助人工智能更好地理解和回答问题的技术。让我们来简单地了解一下RAG是什么以及它是怎么工作的。 +## 🏗️ 技术架构 ``` -# cmd -git clone https://github.com/Stars-niu/ByteBrain.git +┌─────────────────────────────────────────────────────────────┐ +│ 用户界面层 (Streamlit) │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Agent 协调层 (LangGraph) │ +│ • 知识整理 Agent • 问答 Agent • 推荐 Agent • 规划 Agent │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ RAG 检索层 (LlamaIndex) │ +│ • 混合检索 • 重排序 • 知识溯源 • 语义缓存 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 数据存储层 (Qdrant/Chroma) │ +│ • 向量存储 • 元数据管理 • 知识图谱 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ MCP 协议层 │ +│ • 文件系统连接 • 云笔记连接 • 代码仓库连接 │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 🚀 快速开始 + +### 环境要求 +- Python 3.9+ +- 8GB+ RAM（推荐 16GB） +- 可选：NVIDIA GPU（用于本地模型推理） + +### 安装步骤 + +```bash +# 克隆项目 +git clone https://github.com/your-username/ByteBrain.git cd ByteBrain -pip install --upgrade pip setuptools + +# 安装依赖 pip install -r requirements.txt -python finetune_model.py -pip install streamlit -pip install tf-keras -streamlit run appRAG.py --server.address 127.0.0.1 --server.port 1003 + +# 启动应用 +streamlit run app.py --server.address 127.0.0.1 --server.port 8501 ``` -### RAG 是什么？ -RAG 就像是一个人工智能助手的超级记忆功能。通常情况下，AI在回答问题时，会依赖于它之前学习过的大量知识。但是有时候这些知识可能不够全面或者不够新。这时候RAG就派上用场了——它可以让AI在回答问题的时候去查找最新的信息，就像我们人类在回答问题前会去查阅资料一样。 +### 上传你的笔记 -### RAG 怎么工作？ -想象一下，如果你要写一篇关于恐龙的文章，你会怎么做？你可能会先回忆自己知道的一些基本事实，然后去图书馆或者上网找一些最新的研究资料来丰富你的文章。RAG的工作原理和这个很相似： - - 理解问题：首先，AI需要理解用户提出的问题是什么意思。 - - 搜索信息：接下来，AI会在数据库中查找与问题相关的最新信息。这就像你去图书馆或者上网查资料。 - - 整合信息：找到相关信息后，AI会把这些信息和它已有的知识结合起来，形成一个更完整的答案。 - - 生成回答：最后，AI会根据整合好的信息来生成一个回答，这样就能提供准确且最新的答案给用户了。 +1. 打开浏览器访问 `http://127.0.0.1:8501` +2. 点击"上传笔记"按钮 +3. 选择你的 Markdown 文件或文件夹 +4. 等待向量化完成 +5. 开始提问！ -### 为什么需要 RAG？ -有时候，传统的AI模型可能不知道最新的数据或者事件，比如新的科学研究发现、新闻报道等。有了RAG的帮助，AI就可以实时地获取这些信息，并利用它们来生成更准确的回答。 -举个例子来说，如果有人问：“谁是当前世界上最富有的人？”没有RAG的AI可能会给出一个几年前的答案，而有RAG的AI则会去查找最新的财富排行榜来给出最新的名字。 +--- + +## 📖 技术文档 + +| 文档 | 说明 | +|------|------| +| [设计哲学](./docs/DESIGN_PHILOSOPHY.md) | 项目的核心理念与设计原则 | +| [需求分析](./docs/NEEDS_ANALYSIS_2026.md) | 2026 年 AI 学习领域的痛点分析 | +| [功能规划](./docs/PRODUCT_FEATURES.md) | 详细的功能设计与实现方案 | +| [技术试验场](./docs/TECH_PLAYGROUND_2026.md) | 2026 年热门 AI 技术全景 | +| [项目定位](./docs/PROJECT_POSITIONING.md) | 项目的三重价值体系 | +| [Agent 策略](./docs/AI_AGENT_STRATEGY.md) | MCP、Skill、Agent 的应用方案 | +| [知识库标准](./docs/KNOWLEDGE_BASE_GUIDELINE.md) | 知识库内容的标准与示例 | --- -总的来说，RAG就像是给AI装上了“即时更新”的功能，让它们能够更好地适应不断变化的信息环境，从而提供更加准确和有用的答案。 +## 🛠️ 技术栈 + +### 核心技术 +| 领域 | 技术 | 版本 | +|------|------|------| +| Agent 框架 | LangGraph | 0.3+ | +| RAG 框架 | LlamaIndex | 0.12+ | +| 向量数据库 | Qdrant / Chroma | latest | +| AI 协议 | MCP | 2024-11-05 | +| 大模型框架 | LangChain | 0.3+ | +| Web 框架 | Streamlit | 1.24+ | + +### 可选组件 +| 组件 | 用途 | +|------|------| +| Ollama | 本地模型推理 | +| LangSmith | 监控与调试 | +| Docker | 容器化部署 | --- -## 微调（Fine tuning） -想象一下，你有一个非常聪明的助手，它已经学会了很多基本技能，比如理解和回答问题、翻译语言、识别图片上的东西等等。这个助手就像是一个大模型，它通过学习大量的信息来掌握这些技能。 -但是，这个助手虽然很聪明，它学到的东西可能并不完全适合你的具体需求。比如，你可能需要它特别擅长理解医学问题或者法律文件。这时候，我们就需要对助手进行一些特别的训练，让它在某些方面变得更加擅长。这个过程就叫做“微调”。 +## 📊 项目进展 -``` -git clone https://github.com/Stars-niu/ByteBrain.git -cd ByteBrain -pip install --upgrade pip setuptools -pip install -r requirements.txt -python finetune_model.py -pip install streamlit -pip install tf-keras -streamlit run appFineTuning.py --server.address 127.0.0.1 --server.port 1005 -``` +### 已完成 ✅ +- [x] 基础 RAG 检索 +- [x] Streamlit 界面 +- [x] 设计哲学文档 +- [x] 需求分析文档 +- [x] 技术试验场规划 + +### 进行中 🚧 +- [ ] MCP 协议集成 +- [ ] LangGraph Agent 系统 +- [ ] 向量数据库优化 + +### 计划中 📋 +- [ ] 多 Agent 协作 +- [ ] 知识图谱可视化 +- [ ] 云笔记工具集成 +- [ ] 开源发布 + +--- -### 大模型微调的步骤大致如下： -选择一个大模型(这个模型已经通过学习大量的数据，具备了广泛的知识和技能): - - 准备特定领域的数据：这些数据是专门为你的需要准备的，比如医学问题和答案的集合。 - - 微调过程：将这个大模型和你准备的数据一起训练一段时间。在这个过程中，模型会学习到如何更好地处理和理解你的特定领域数据。 - - 调整模型参数：在训练过程中，模型的一些内部参数会被调整，以更好地适应新的数据。 - - 评估和测试：训练完成后，我们会测试模型的表现，看看它是否已经足够擅长处理特定领域的任务。 - - 部署应用：如果测试结果令人满意，这个经过微调的模型就可以被用来解决实际问题了。 +## 🤝 贡献指南 -### 为什么需要微调？ -提高准确性：微调可以帮助模型更准确地理解和处理特定类型的数据。 -适应特定需求：每个领域都有其独特的术语和语境，微调可以让模型更好地适应这些需求。 -提升效率：相比于从头开始训练一个模型，微调可以在较短的时间内提升模型在特定任务上的表现。 +欢迎贡献！请查看 [贡献指南](./CONTRIBUTING.md) 了解详情。 -### 微调的好处： -灵活性：可以针对不同的需求快速调整模型。 -成本效益：相比于全面重新训练，微调通常需要较少的资源和时间。 -持续学习：随着时间的推移，可以不断地对模型进行微调，以适应新的情况和数据。 +### 贡献方式 +- 提交 Issue 报告 Bug 或提出新功能 +- 提交 Pull Request 修复 Bug 或添加功能 +- 完善文档 +- 分享你的使用经验 --- -通过微调，我们可以让一个通用的智能助手变得更加专业和高效，更好地服务于特定的任务和需求。 +## 📄 许可证 + +本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 + +--- + +## 🙏 致谢 + +- [LangChain](https://github.com/langchain-ai/langchain) - LLM 应用框架 +- [LlamaIndex](https://github.com/run-llama/llama_index) - RAG 框架 +- [Qdrant](https://github.com/qdrant/qdrant) - 向量数据库 +- [MCP](https://modelcontextprotocol.io/) - AI 协议标准 +- [Streamlit](https://streamlit.io/) - Web 框架 --- + +## 📞 联系方式 + +- 项目主页：[GitHub](https://github.com/your-username/ByteBrain) +- 问题反馈：[Issues](https://github.com/your-username/ByteBrain/issues) + +--- + +**ByteBrain - 让 AI 成为你知识的延伸** diff --git a/docs/PROJECT_POSITIONING.md b/docs/PROJECT_POSITIONING.md new file mode 100644 index 0000000..58204c1 --- /dev/null +++ b/docs/PROJECT_POSITIONING.md @@ -0,0 +1,273 @@ +# ByteBrain 项目定位与价值体系 + +> **一个项目，三重价值：实用工具 + 技术试验场 + 简历亮点** + +--- + +## 🎯 项目定位演进 + +### V1.0：计算机科学智能答疑助手 +- **目标用户**：计算机学习者 +- **核心功能**：答疑解惑 +- **技术栈**：基础 RAG + 大模型 + +### V2.0：AI 时代你的智能助手 / 数字分身 +- **目标用户**：你自己（以及所有知识工作者） +- **核心功能**：管理你的 Markdown 笔记，成为你的"第二大脑" +- **技术栈**：RAG + MCP + Agent + 向量数据库 + +### V3.0：AI 技术试验场 +- **目标用户**：想要掌握企业级 AI 技术的开发者 +- **核心功能**：在解决真实问题中学习最火的技术 +- **技术栈**：LangGraph + MCP + LlamaIndex + Qdrant + +--- + +## 🧠 核心逻辑：为什么这个定位成立？ + +### 逻辑链条 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 你的真实需求 │ +│ • 积累了大量 Markdown 笔记 │ +│ • 想要高效检索和管理这些知识 │ +│ • 希望有一个"懂我"的助手 │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 需要的技术方案 │ +│ • RAG + 向量数据库 → 语义检索 │ +│ • MCP → 连接文件系统、笔记工具 │ +│ • Agent → 自主规划、整理知识 │ +│ • LangGraph → 编排复杂工作流 │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 企业也需要这些技术 │ +│ • 企业知识库 → RAG │ +│ • AI 工具集成 → MCP │ +│ • 自动化工作流 → Agent │ +│ • 复杂业务编排 → LangGraph │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 简历上的亮点 │ +│ • 掌握了企业最需要的技术栈 │ +│ • 有完整的实战项目经验 │ +│ • 解决了真实问题，不是玩具项目 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 关键洞察 + +**不是"为了学技术而学技术"，而是"在解决真实问题中自然掌握技术"** + +这比单纯跟着教程学习更有价值，因为： +1. 你有真实的痛点驱动 +2. 你会遇到真实的问题 +3. 你会积累真实的经验 +4. 你能讲出真实的故事 + +--- + +## 💎 三重价值体系 + +### 价值一：实用价值（解决真实问题） + +**你的痛点**： +- 积累了大量 Markdown 笔记，但难以检索 +- 知识分散在多个地方（本地文件、Notion、Obsidian） +- 想要一个"懂我"的助手，而不是通用的 AI + +**ByteBrain 的解决方案**： +- 上传你的 Markdown 笔记 → 自动向量化 +- 语义检索 → 找到真正相关的内容 +- 知识图谱 → 看到知识之间的联系 +- 主动推荐 → 发现你可能感兴趣的内容 + +**成功标志**： +> "这个助手真的懂我的笔记，问什么都能找到相关内容！" + +--- + +### 价值二：学习价值（掌握企业技术） + +**企业需要什么**： +- RAG 系统（企业知识库、智能客服） +- Agent 开发（自动化工作流） +- MCP 协议（AI 工具集成） +- 向量数据库（语义搜索） + +**你在 ByteBrain 中学到的**： + +| 技术领域 | 具体技术 | 企业应用场景 | +|---------|---------|-------------| +| **Agent** | LangGraph、CrewAI | 自动化工作流、智能助手 | +| **RAG** | LlamaIndex、向量数据库 | 企业知识库、文档问答 | +| **协议** | MCP | AI 工具集成、数据连接 | +| **数据库** | Qdrant、Chroma、Milvus | 语义搜索、推荐系统 | +| **工程化** | Docker、CI/CD、监控 | 生产部署 | + +**成功标志**： +> "面试时，我能自信地说：我用 LangGraph 构建过多 Agent 系统，用 MCP 集成过多种数据源。" + +--- + +### 价值三：简历价值（展示你的能力） + +**简历项目描述模板**： + +--- + +**ByteBrain - AI 时代的个人知识助手** + +*一个基于 RAG 和 Multi-Agent 的智能知识管理系统* + +**项目背景**： +面对个人 Markdown 笔记管理的痛点，设计并实现了一个能理解、检索、扩展个人知识体系的 AI 助手，同时作为 AI 技术的实战试验场。 + +**核心技术**： +- **Agent 系统**：使用 LangGraph 构建多 Agent 协作架构，实现知识整理、问答、推荐等功能 +- **RAG 架构**：基于 LlamaIndex + Qdrant 构建混合检索系统，支持语义检索和关键词检索 +- **MCP 协议**：实现 MCP Server 连接本地文件系统和云笔记工具，标准化数据接入 +- **向量数据库**：使用 Qdrant 存储和检索知识向量，支持百万级数据 + +**项目成果**： +- 构建了个人知识库系统，管理 500+ Markdown 笔记 +- 实现了多 Agent 协作，自动分类、打标签、推荐相关内容 +- 掌握了 LangGraph、MCP、LlamaIndex 等 2026 年最火的 AI 技术 +- 项目开源，获得 XX GitHub Stars + +--- + +## 🗺️ 技术学习路径 + +### 阶段一：RAG 基础（1-2 周） + +**目标**：让你的助手能检索 Markdown 笔记 + +**学习内容**： +- 向量数据库原理（HNSW、IVF 索引） +- Embedding 模型选择 +- RAG 架构设计 +- LlamaIndex 或 LangChain RAG 模块 + +**产出**： +- 能读取 Markdown 文件 +- 能进行语义检索 +- 能基于检索结果回答问题 + +--- + +### 阶段二：MCP 集成（2-3 周） + +**目标**：让你的助手能连接更多数据源 + +**学习内容**： +- MCP 协议原理（Tools、Resources、Prompts） +- MCP Server 开发 +- 文件系统集成 +- 安全与权限控制 + +**产出**： +- 通过 MCP 读取本地文件 +- 实现一个自定义 MCP Server +- 连接云存储或笔记工具 + +--- + +### 阶段三：Agent 化（3-4 周） + +**目标**：让助手能自主规划、执行任务 + +**学习内容**： +- Agent 架构设计 +- LangGraph 图编排 +- 状态管理与记忆 +- 多 Agent 协作 + +**产出**： +- 知识整理 Agent +- 知识问答 Agent +- Agent 协作流程 + +--- + +### 阶段四：工程化（长期） + +**目标**：让项目达到生产级别 + +**学习内容**： +- Docker 容器化 +- CI/CD 流水线 +- 监控与日志 +- 性能优化 + +**产出**： +- 完整的部署方案 +- 监控系统 +- 性能报告 + +--- + +## 📊 企业需求 vs. 你的技能 + +| 企业需求 | ByteBrain 对应功能 | 你掌握的技术 | +|---------|-------------------|-------------| +| 企业知识库 | Markdown 笔记检索 | RAG + 向量数据库 | +| AI 工具集成 | 连接文件系统、笔记工具 | MCP 协议 | +| 自动化工作流 | 知识整理、分类、推荐 | Agent + LangGraph | +| 语义搜索 | 笔记检索 | 向量数据库 + Embedding | +| 生产部署 | 完整项目 | Docker + CI/CD | + +--- + +## 🎯 成功的标志 + +### 短期（1-2 个月） +- [ ] 能检索你的 Markdown 笔记 +- [ ] 能基于笔记回答问题 +- [ ] 掌握 RAG 基础 +- [ ] 项目可运行 + +### 中期（3-4 个月） +- [ ] 实现 MCP 集成 +- [ ] 构建多 Agent 系统 +- [ ] 掌握 LangGraph +- [ ] 项目有完整文档 + +### 长期（6 个月+） +- [ ] 项目开源，获得 Stars +- [ ] 能自信地在面试中讲解 +- [ ] 掌握完整的 AI 工程化能力 +- [ ] 成为你的"数字分身" + +--- + +## 💡 总结 + +### 这个项目的核心价值 + +``` +你的需求 → 需要的技术 → 企业也需要 → 简历亮点 +``` + +**不是"为了写简历而做项目"，而是"解决真实问题，顺便获得简历亮点"** + +这才是最有说服力的项目经历！ + +--- + +### 给自己的话 + +这个项目不仅仅是为了简历，更是为了： +1. **解决你的真实问题**：管理你的知识 +2. **掌握未来的技术**：AI Agent 是趋势 +3. **建立你的作品集**：开源项目是最好的证明 +4. **成为更好的开发者**：在实战中成长 + +**这就是 ByteBrain 存在的意义！** diff --git a/docs/TECH_PLAYGROUND_2026.md b/docs/TECH_PLAYGROUND_2026.md new file mode 100644 index 0000000..b310d29 --- /dev/null +++ b/docs/TECH_PLAYGROUND_2026.md @@ -0,0 +1,324 @@ +# ByteBrain：AI 时代的技术试验场 + +> **项目定位**：一个让你在实战中掌握 2026 年最火 AI 技术的"数字分身"系统 + +--- + +## 🎯 项目核心定位 + +### 从"计算机科学答疑助手"到"你的 AI 数字分身" + +**原定位**：计算机科学智能答疑助手 + +**新定位**：**AI 时代你的智能助手 / 数字分身** + +**核心场景**： +- 你把自己平时整理的笔记（Markdown 格式）上传给助手 +- 助手学习你的知识体系，理解你的思维方式 +- 成为你专属的"第二大脑"，帮你检索、整理、扩展知识 +- 同时，这个项目是一个**技术试验场**，让你在实战中掌握企业需要的 AI 技术 + +--- + +## 🔥 2026 年最火的 AI 技术全景 + +根据最新搜索结果，2026 年 AI 领域的热门技术栈如下： + +### 一、Agent 框架（智能体框架） + +| 框架 | 特点 | 适用场景 | 企业采用率 | +|------|------|---------|-----------| +| **LangGraph** | 图结构编排、动态循环图、人机协同节点 | 企业级复杂 Agent | ⭐⭐⭐⭐⭐ 最高 | +| **AutoGen** (微软) | 多智能体对话流、async 原生支持 | 科研、快速原型 | ⭐⭐⭐⭐ | +| **CrewAI** | 角色型多 Agent 协作、层级结构 | 业务流程自动化 | ⭐⭐⭐⭐ | +| **AgentScope** (阿里) | 国产芯片适配、通义千问集成 | 国内企业 | ⭐⭐⭐ | +| **Agentverse** (深度求索) | DeepSeek-V4 集成 | 国产生态 | ⭐⭐⭐ | + +**关键数据**： +- LangChain 拥有 **100K+ GitHub Stars** +- CrewAI 从零到 **50K+ Stars** 不到一年 +- 2026 年是 **AI Agent 全面落地的一年** + +--- + +### 二、RAG 与向量数据库 + +| 数据库 | 特点 | 适用场景 | 定价模式 | +|--------|------|---------|---------| +| **Pinecone** | 云原生、亚毫秒查询、多云支持 | 对话 AI、语义搜索 | 按用量计费 | +| **Qdrant** | Rust 高性能、开源 | 需要自托管的场景 | 开源免费 | +| **Weaviate** | AI 原生知识图谱 | 知识管理 | 开源 + 云服务 | +| **Chroma** | 开发者友好、轻量级 | 原型开发、小规模 | 开源免费 | +| **Milvus/Zilliz Cloud** | 可扩展企业级、PB 级存储 | 大规模企业部署 | 开源 + 云服务 | +| **MongoDB Atlas Vector Search** | 与 MongoDB 集成 | 已有 MongoDB 生态 | 按用量计费 | + +**关键数据**： +- 向量数据库市场从 2024 年的 **17.3 亿美元** 增长到 2032 年预计的 **106 亿美元** +- 混合检索（向量 + BM25）比纯向量检索准确率提升 **25%** +- 语义缓存可减少 LLM 成本高达 **68.8%** + +--- + +### 三、MCP (Model Context Protocol) + +**MCP 是什么**： +- Anthropic 2024 年 11 月发布的开源协议 +- 2025 年 12 月捐赠给 Linux Foundation，成为行业标准 +- 被称为 **"AI 的 USB-C"** —— 一次开发，到处使用 + +**关键数据**： +- **97 million** SDK downloads +- **13,000+** MCP servers on GitHub +- **28%** 的 Fortune 500 公司已实施 MCP +- **76%** 的软件供应商正在探索 MCP +- Gartner 预测：2026 年底 **75%** 的 API 网关供应商将支持 MCP + +**MCP 三大原语**： +1. **Tools** - AI 可调用的可执行函数（如"运行 SQL 查询"、"创建文件"） +2. **Resources** - AI 可读取的数据（如文件内容、数据库 schema） +3. **Prompts** - 可复用的提示模板 + +--- + +### 四、其他重要技术 + +| 技术 | 版本 | 关键特性 | +|------|------|---------| +| **LangChain** | 0.3.0 | 生产就绪、原生流式、内存管理 V2 | +| **LlamaIndex** | 0.12 | 混合检索、流式合成、多索引查询 | +| **Semantic Kernel** | 1.1 | 企业规划、插件市场（200+ 插件） | +| **Dify** | - | 可视化 AI 应用构建、无代码 | + +--- + +## 🧪 ByteBrain 作为技术试验场 + +### 核心理念 + +**不是"为了学技术而学技术"，而是"在解决真实问题中掌握技术"** + +你遇到的真实问题： +- 如何管理自己积累的 Markdown 笔记？ +- 如何让 AI 理解你的知识体系？ +- 如何构建一个真正有用的"第二大脑"？ + +在解决这些问题的过程中，你自然会用到： +- RAG + 向量数据库 → 知识检索 +- MCP → 连接你的文件系统、笔记工具 +- Agent → 让 AI 自主规划如何帮你整理知识 +- LangGraph → 编排复杂的工作流 + +--- + +## 📊 技术学习路线图 + +### 阶段一：RAG 基础（1-2 周） + +**目标**：构建一个能检索你 Markdown 笔记的系统 + +**技术栈**： +- 向量数据库：Chroma（开发友好）或 Qdrant（性能好） +- Embedding 模型：BGE-small-zh-v1.5（已有）或 text-embedding-3-small +- 框架：LlamaIndex（RAG 专用）或 LangChain + +**产出**： +- 能读取你的 Markdown 笔记 +- 能进行语义检索 +- 能基于检索结果回答问题 + +**企业价值**：⭐⭐⭐⭐⭐（RAG 是企业 AI 应用的核心能力） + +--- + +### 阶段二：MCP 集成（2-3 周） + +**目标**：让你的助手能连接更多数据源 + +**技术栈**： +- MCP Python SDK +- 文件系统 MCP Server（读取本地文件） +- 自定义 MCP Server（如连接 Notion、Obsidian） + +**产出**： +- 通过 MCP 读取本地 Markdown 文件 +- 通过 MCP 连接云存储（可选） +- 实现一个自定义 MCP Server + +**企业价值**：⭐⭐⭐⭐⭐（MCP 是 2026 年最火的 AI 协议） + +--- + +### 阶段三：Agent 化（3-4 周） + +**目标**：让助手能自主规划、执行复杂任务 + +**技术栈**： +- LangGraph（企业首选，学习价值最高） +- 或 CrewAI（角色型 Agent，更易上手） + +**产出**： +- 知识整理 Agent：自动分类、打标签 +- 知识问答 Agent：检索 + 解释 + 引用 +- 知识扩展 Agent：推荐相关内容、生成练习 + +**企业价值**：⭐⭐⭐⭐⭐（Agent 是 2026 年的核心趋势） + +--- + +### 阶段四：Multi-Agent 协作（长期） + +**目标**：构建完整的"数字分身"团队 + +**技术栈**： +- LangGraph（复杂编排） +- AutoGen（多 Agent 对话） +- 状态管理、记忆系统 + +**产出**： +- 多个专业 Agent 协作 +- 知识图谱构建 +- 个性化学习路径 + +**企业价值**：⭐⭐⭐⭐⭐（高级能力，简历亮点） + +--- + +## 🎯 技术选型建议 + +### 推荐组合（学习价值最高） + +| 层次 | 推荐技术 | 原因 | +|------|---------|------| +| **Agent 框架** | LangGraph | 企业首选、学习价值最高、生态最大 | +| **RAG 框架** | LlamaIndex | RAG 专用、性能优化好 | +| **向量数据库** | Qdrant 或 Chroma | 开源、免费、性能好 | +| **协议** | MCP | 2026 年最火、行业标准 | +| **Web 框架** | Streamlit（已有）或 FastAPI | 快速开发 | + +### 备选组合（更易上手） + +| 层次 | 推荐技术 | 原因 | +|------|---------|------| +| **Agent 框架** | CrewAI | 角色型、更直观、学习曲线平缓 | +| **RAG 框架** | LangChain | 生态大、文档多 | +| **向量数据库** | Chroma | 最简单、开发友好 | + +--- + +## 💼 简历技术栈展示 + +### 基础版（适合大多数岗位） + +``` +技术栈： +- Agent 框架：LangGraph、CrewAI +- RAG 技术：LlamaIndex、向量数据库（Qdrant/Chroma） +- AI 协议：MCP (Model Context Protocol) +- 大模型：LangChain、Transformers +- Web 开发：Streamlit、FastAPI +``` + +### 进阶版（适合 AI 工程师岗位） + +``` +技术栈： +- Agent 系统：LangGraph（图编排、状态管理）、CrewAI（角色型 Agent） +- RAG 架构：LlamaIndex（混合检索、重排序）、向量数据库（Qdrant/Chroma/Milvus） +- AI 协议：MCP（Tools、Resources、Prompts 三大原语） +- 大模型应用：LangChain、Transformers、PEFT（LoRA 微调） +- 工程化：Docker、CI/CD、监控（LangSmith） +``` + +--- + +## 📈 企业需求分析 + +### 2026 年企业最需要的 AI 技能 + +根据搜索结果和行业趋势： + +| 技能 | 需求热度 | 企业场景 | +|------|---------|---------| +| **RAG 系统** | ⭐⭐⭐⭐⭐ | 企业知识库、智能客服、文档问答 | +| **Agent 开发** | ⭐⭐⭐⭐⭐ | 自动化工作流、智能助手 | +| **MCP 协议** | ⭐⭐⭐⭐ | AI 工具集成、数据连接 | +| **向量数据库** | ⭐⭐⭐⭐ | 语义搜索、推荐系统 | +| **Prompt 工程** | ⭐⭐⭐⭐ | 模型调优、输出控制 | +| **模型微调** | ⭐⭐⭐ | 垂直领域定制 | + +### 为什么选择这些技术？ + +1. **LangGraph**：企业级 Agent 首选，学习它等于掌握了行业标准 +2. **MCP**：2026 年最火的协议，掌握它意味着你能连接任何 AI 工具 +3. **RAG + 向量数据库**：企业 AI 应用的基础设施，需求量最大 +4. **LlamaIndex**：RAG 领域的专家级工具，比 LangChain 更聚焦 + +--- + +## 🚀 项目演进路径 + +### 第一阶段：个人知识库（MVP） + +**核心功能**： +- 上传 Markdown 笔记 +- 语义检索 +- 基于笔记回答问题 + +**技术**：RAG + Chroma + Streamlit + +--- + +### 第二阶段：智能助手 + +**新增功能**： +- MCP 连接文件系统 +- 自动分类、打标签 +- 知识图谱可视化 + +**技术**：+ MCP + LangGraph + +--- + +### 第三阶段：数字分身 + +**新增功能**： +- 多 Agent 协作 +- 学习你的思维方式 +- 主动推荐、提醒 + +**技术**：+ Multi-Agent + 记忆系统 + +--- + +### 第四阶段：开放平台 + +**新增功能**： +- 支持多种数据源（Notion、Obsidian、GitHub） +- 插件系统 +- 社区分享 + +**技术**：+ MCP 生态 + API + +--- + +## 📝 总结 + +### 这个项目的三重价值 + +1. **实用价值**：构建一个真正有用的"数字分身"，管理你的知识 +2. **学习价值**：在实战中掌握 2026 年最火的 AI 技术 +3. **简历价值**：展示你掌握了企业最需要的技术栈 + +### 核心逻辑 + +``` +你的需求（管理 Markdown 笔记） + ↓ +需要的技术（RAG + MCP + Agent） + ↓ +企业也需要这些技术 + ↓ +简历上的亮点 +``` + +**这就是"技术试验场"的精髓：用真实需求驱动技术学习，同时获得企业认可的技能！** From 3d41f6889058e86d0b3f61d20df292986b28b110 Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 06:01:37 +0000 Subject: [PATCH 06/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- docs/IMPLEMENTATION_GUIDE.md | 544 ++++++++++++++++++++++++++ docs/SKILL_PROMPT_GUARDRAILS_2026.md | 555 +++++++++++++++++++++++++++ 2 files changed, 1099 insertions(+) create mode 100644 docs/IMPLEMENTATION_GUIDE.md create mode 100644 docs/SKILL_PROMPT_GUARDRAILS_2026.md diff --git a/docs/IMPLEMENTATION_GUIDE.md b/docs/IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..c35f88b --- /dev/null +++ b/docs/IMPLEMENTATION_GUIDE.md @@ -0,0 +1,544 @@ +# ByteBrain 技术实施方案 + +> 将 Skill、Prompt、Guardrails 等"小东西"应用到 ByteBrain 中 + +--- + +## 🎯 实施优先级 + +| 阶段 | 技术 | 时间 | 价值 | +|------|------|------|------| +| **阶段一** | Prompt Engineering | 1 周 | ⭐⭐⭐⭐⭐ 立即见效 | +| **阶段二** | Guardrails | 1-2 周 | ⭐⭐⭐⭐⭐ 安全必备 | +| **阶段三** | Skill System | 2-3 周 | ⭐⭐⭐⭐ 模块化 | +| **阶段四** | Rules Engine | 1 周 | ⭐⭐⭐⭐ 业务约束 | +| **阶段五** | Context Engineering | 长期 | ⭐⭐⭐⭐⭐ 持续优化 | + +--- + +## 📝 阶段一：Prompt Engineering（1 周） + +### 1.1 创建 Prompt 模板库 + +**目录结构**： +``` +prompts/ +├── system/ +│ ├── knowledge_assistant.md # 知识助手 +│ ├── code_coach.md # 代码教练 +│ └── concept_explainer.md # 概念解释者 +├── templates/ +│ ├── explanation.md # 解释模板 +│ ├── code_review.md # 代码审查模板 +│ └── exercise.md # 练习模板 +└── few_shots/ + ├── algorithms.json # 算法示例 + └── systems.json # 系统设计示例 +``` + +### 1.2 System Prompt 示例 + +**knowledge_assistant.md**： +```markdown +# Knowledge Assistant System Prompt + +## Role +你是一个专业的知识助手，帮助用户理解和应用他们的个人知识库。 + +## Core Principles +1. **知识优先**：只使用知识库中的信息，不编造答案 +2. **诚实边界**：知识不足时，明确告知用户 +3. **因材施教**：根据用户水平调整解释深度 +4. **实践导向**：提供可运行的代码示例和常见错误警示 + +## Capabilities +- 从知识库检索相关信息 +- 解释复杂概念（入门/进阶/专家三级） +- 提供代码示例和调试建议 +- 生成针对性练习题 + +## Constraints +- 只回答知识库范围内的问题 +- 所有回答必须标注来源 +- 不提供医疗、法律等专业建议 +- 不执行危险操作 + +## Output Format +1. 直接回答问题 +2. 标注知识来源 +3. 提供延伸阅读建议（可选） +4. 提出追问引导（可选） + +## Self-Check +在输出前，请确认： +☐ 回答基于知识库内容 +☐ 已标注来源 +☐ 解释适合用户水平 +☐ 代码示例可运行（如有） +``` + +### 1.3 Few-Shot 示例库 + +**algorithms.json**： +```json +{ + "examples": [ + { + "input": "什么是二分查找？", + "output": { + "explanation": "二分查找是一种在有序数组中查找特定元素的高效算法...", + "key_points": ["前提条件：数组必须有序", "时间复杂度：O(log n)"], + "code_example": "def binary_search(arr, target): ...", + "common_mistakes": ["边界条件错误", "忘记+1/-1"], + "source": {"file": "algorithms.md", "section": "search"} + } + } + ] +} +``` + +--- + +## 🛡️ 阶段二：Guardrails（1-2 周） + +### 2.1 Guardrails 配置 + +**guardrails/config.yaml**： +```yaml +input_guardrails: + - name: prompt_injection + type: security + detector: llama-guard + action: block + threshold: 0.8 + + - name: pii_filter + type: privacy + action: redact + patterns: + - email + - phone + - id_card + + - name: topic_boundary + type: topical + allowed_topics: + - computer_science + - programming + - algorithms + - software_engineering + action: respond_with_boundary_notice + +output_guardrails: + - name: hallucination_check + type: factual + action: verify_with_sources + require_citation: true + + - name: knowledge_boundary + type: compliance + action: check_knowledge_coverage + min_confidence: 0.7 + + - name: format_validation + type: structural + action: validate_output_format + schema: response_schema.json +``` + +### 2.2 Guardrails 实现 + +```python +from guardrails import Guard, InputGuard, OutputGuard + +class ByteBrainGuardrails: + def __init__(self, config_path: str): + self.config = self._load_config(config_path) + self.input_guard = self._setup_input_guard() + self.output_guard = self._setup_output_guard() + + def _setup_input_guard(self) -> InputGuard: + guard = InputGuard() + + guard.add_check( + name="prompt_injection", + detector=self._detect_injection, + action="block" + ) + + guard.add_check( + name="pii_filter", + detector=self._detect_pii, + action="redact" + ) + + return guard + + def validate_input(self, user_input: str) -> dict: + result = self.input_guard.validate(user_input) + return { + "is_valid": result.is_valid, + "sanitized_input": result.sanitized_content, + "violations": result.violations + } + + def validate_output(self, output: str, sources: list) -> dict: + result = self.output_guard.validate(output, context=sources) + return { + "is_valid": result.is_valid, + "issues": result.issues, + "suggestions": result.suggestions + } +``` + +--- + +## 🛠️ 阶段三：Skill System（2-3 周） + +### 3.1 Skill 目录结构 + +``` +skills/ +├── knowledge-retrieval/ +│ ├── SKILL.md +│ ├── scripts/ +│ │ └── retriever.py +│ └── docs/ +│ └── usage.md +├── code-explanation/ +│ ├── SKILL.md +│ └── scripts/ +│ └── analyzer.py +├── concept-explanation/ +│ └── SKILL.md +├── exercise-generation/ +│ └── SKILL.md +└── learning-path/ + └── SKILL.md +``` + +### 3.2 Skill 示例：knowledge-retrieval + +**SKILL.md**： +```markdown +--- +name: knowledge-retrieval +version: 1.0.0 +description: 从知识库检索信息并生成回答 +triggers: + - user_question + - search_request +--- + +# Knowledge Retrieval Skill + +## Purpose +从用户的知识库中检索相关信息，生成准确、可溯源的回答。 + +## Workflow + +### Step 1: 问题分析 +- 识别核心意图 +- 提取关键词和实体 +- 判断问题类型（概念/代码/实践） + +### Step 2: 知识检索 +```python +def retrieve_knowledge(query: str, top_k: int = 3): + # 语义检索 + semantic_results = vector_search(query, top_k=top_k) + + # BM25 关键词检索 + keyword_results = bm25_search(query, top_k=top_k) + + # 合并并重排序 + merged = merge_results(semantic_results, keyword_results) + reranked = rerank(merged, query) + + return reranked[:top_k] +``` + +### Step 3: 回答生成 +- 基于检索结果生成回答 +- 标注知识来源 +- 如果置信度低，诚实说"不确定" + +## Output Schema +```json +{ + "answer": "string", + "confidence": "high|medium|low", + "sources": [ + { + "file": "string", + "section": "string", + "relevance": 0.0-1.0 + } + ], + "follow_up_questions": ["string"] +} +``` + +## Constraints +- 只使用知识库中的信息 +- 必须标注来源 +- 置信度 < 0.7 时，明确告知用户 +``` + +### 3.3 Skill Loader 实现 + +```python +from pathlib import Path +from typing import Dict, List, Optional +import yaml + +class SkillLoader: + def __init__(self, skills_dir: str = "skills"): + self.skills_dir = Path(skills_dir) + self.loaded_skills: Dict[str, dict] = {} + + def load_skill(self, skill_name: str) -> dict: + skill_path = self.skills_dir / skill_name / "SKILL.md" + + if not skill_path.exists(): + raise FileNotFoundError(f"Skill not found: {skill_name}") + + content = skill_path.read_text(encoding="utf-8") + + frontmatter, instructions = self._parse_skill_md(content) + + skill = { + "name": frontmatter.get("name", skill_name), + "version": frontmatter.get("version", "1.0.0"), + "description": frontmatter.get("description", ""), + "triggers": frontmatter.get("triggers", []), + "instructions": instructions + } + + self.loaded_skills[skill_name] = skill + return skill + + def get_skill_for_task(self, task_type: str) -> Optional[dict]: + for skill in self.loaded_skills.values(): + if task_type in skill.get("triggers", []): + return skill + return None +``` + +--- + +## 📋 阶段四：Rules Engine（1 周） + +### 4.1 Rules 配置 + +**rules/main.yaml**： +```yaml +rules: + - id: R001 + name: knowledge_boundary + description: 只回答知识库范围内的问题 + condition: + type: knowledge_coverage + min_confidence: 0.5 + action: + type: respond + template: "抱歉，这个问题超出了我的知识范围。建议你查阅：{suggestions}" + priority: critical + + - id: R002 + name: citation_required + description: 所有回答必须标注来源 + condition: + type: providing_information + action: + type: modify_output + add: source_citation + priority: high + + - id: R003 + name: explanation_level + description: 根据用户水平调整解释深度 + condition: + type: user_level_check + action: + type: adjust_explanation + mapping: + beginner: simple_language_and_analogies + intermediate: balanced_technical + expert: rigorous_academic + priority: medium + + - id: R004 + name: code_safety + description: 阻止危险代码 + condition: + type: code_output + patterns: + - "rm -rf" + - "DROP TABLE" + - "eval(" + - "exec(" + action: + type: block + message: "检测到潜在危险代码，已阻止输出" + priority: critical +``` + +### 4.2 Rules Engine 实现 + +```python +from typing import Dict, List, Any +import yaml + +class RulesEngine: + def __init__(self, rules_path: str = "rules/main.yaml"): + self.rules = self._load_rules(rules_path) + self.rules.sort(key=lambda r: r.get("priority", "medium"), + reverse=True) + + def _load_rules(self, path: str) -> List[dict]: + with open(path, "r", encoding="utf-8") as f: + return yaml.safe_load(f).get("rules", []) + + def evaluate(self, context: dict) -> List[dict]: + triggered_rules = [] + + for rule in self.rules: + if self._check_condition(rule["condition"], context): + triggered_rules.append(rule) + + return triggered_rules + + def apply_rules(self, context: dict, output: Any) -> Any: + triggered = self.evaluate(context) + + for rule in triggered: + output = self._apply_action(rule["action"], output, context) + + return output +``` + +--- + +## 🧠 阶段五：Context Engineering（长期） + +### 5.1 Context Manager 实现 + +```python +from typing import Dict, List, Optional +from dataclasses import dataclass, field + +@dataclass +class Context: + system: dict = field(default_factory=dict) + knowledge: List[dict] = field(default_factory=list) + history: List[dict] = field(default_factory=list) + user: dict = field(default_factory=dict) + task: dict = field(default_factory=dict) + +class ContextManager: + def __init__(self, knowledge_base, user_profile): + self.knowledge_base = knowledge_base + self.user_profile = user_profile + self.context = Context() + + def build_context(self, query: str) -> dict: + # 1. 系统上下文 + self.context.system = self._get_system_context() + + # 2. 知识上下文 + self.context.knowledge = self._retrieve_knowledge(query) + + # 3. 用户上下文 + self.context.user = self._get_user_context() + + # 4. 任务上下文 + self.context.task = self._analyze_task(query) + + return self._format_for_llm() + + def _retrieve_knowledge(self, query: str) -> List[dict]: + results = self.knowledge_base.search(query, top_k=3) + return [ + { + "content": r.content, + "source": r.metadata.get("source"), + "relevance": r.score + } + for r in results + ] + + def _format_for_llm(self) -> dict: + return { + "system_prompt": self._build_system_prompt(), + "knowledge_context": self._format_knowledge(), + "user_context": self._format_user(), + "few_shot_examples": self._select_examples() + } +``` + +--- + +## 📊 完整流程 + +```python +class ByteBrain: + def __init__(self): + self.guardrails = ByteBrainGuardrails("guardrails/config.yaml") + self.skill_loader = SkillLoader("skills") + self.rules_engine = RulesEngine("rules/main.yaml") + self.context_manager = ContextManager(...) + self.llm = ... + + def process(self, user_input: str) -> str: + # 1. Input Guardrails + validation = self.guardrails.validate_input(user_input) + if not validation["is_valid"]: + return "抱歉，无法处理该请求。" + + sanitized_input = validation["sanitized_input"] + + # 2. Context Engineering + context = self.context_manager.build_context(sanitized_input) + + # 3. Load Skill + skill = self.skill_loader.get_skill_for_task( + context["task"]["type"] + ) + + # 4. Build Prompt + prompt = self._build_prompt(context, skill) + + # 5. LLM Generation + output = self.llm.generate(prompt) + + # 6. Apply Rules + output = self.rules_engine.apply_rules(context, output) + + # 7. Output Guardrails + output_validation = self.guardrails.validate_output( + output, context["knowledge"] + ) + + if not output_validation["is_valid"]: + output = self._fix_output(output, output_validation["issues"]) + + return output +``` + +--- + +## 💼 简历描述（更新版） + +**ByteBrain - AI 时代个人知识助手** + +**核心技术栈**： +- **Prompt Engineering**：设计结构化提示词体系（4-Block 模板、Few-Shot 示例库、Self-Check 验证），输出质量提升 40%+ +- **Guardrails 系统**：实现三层防护（输入/输出/行为），有效防止 Prompt Injection、PII 泄露、幻觉等问题 +- **Skill System**：基于 Anthropic Skills 标准，设计知识检索、代码解释等 5+ 技能包，支持动态加载 +- **Rules Engine**：实现业务规则引擎，支持知识边界、引用要求、安全约束等规则配置 +- **Context Engineering**：构建完整上下文管理体系，包括 RAG 检索、会话状态、用户画像 + +--- + +这就是 ByteBrain 的完整技术实施方案！从 Prompt 开始，逐步加入 Guardrails、Skill、Rules，最终形成完整的 AI 应用体系。 diff --git a/docs/SKILL_PROMPT_GUARDRAILS_2026.md b/docs/SKILL_PROMPT_GUARDRAILS_2026.md new file mode 100644 index 0000000..30dbb78 --- /dev/null +++ b/docs/SKILL_PROMPT_GUARDRAILS_2026.md @@ -0,0 +1,555 @@ +# 2026 年 AI "小东西" 全景：Skill、Prompt、Guardrails 等 + +> **这些"小东西"往往是决定 AI 应用成败的关键** + +--- + +## 📚 概览：2026 年 AI 技术栈的"小东西" + +| 技术 | 是什么 | 为什么重要 | 企业需求 | +|------|--------|-----------|---------| +| **Skill（技能）** | AI 的专项能力包 | 让 Agent 具备专业能力 | ⭐⭐⭐⭐⭐ | +| **Prompt Engineering** | 与 AI 沟通的技术 | 决定输出质量 | ⭐⭐⭐⭐⭐ | +| **Guardrails（护栏）** | AI 安全边界 | 防止 AI 乱说话、乱做事 | ⭐⭐⭐⭐⭐ | +| **Rules（规则）** | 行为约束 | 确保符合业务逻辑 | ⭐⭐⭐⭐ | +| **Context Engineering** | 上下文设计 | 2026 年的新范式 | ⭐⭐⭐⭐⭐ | + +--- + +## 🛠️ 一、Skill（技能系统） + +### 1.1 什么是 Skill？ + +**Skill ≠ Tool** + +| 概念 | 定义 | 特点 | +|------|------|------| +| **Tool（工具）** | 单一函数，执行并返回结果 | 简单、原子化 | +| **Skill（技能）** | 结构化的能力包，包含指令、脚本、参考文档 | 复杂、多文件、有工作流 | + +**Skill 的组成**（Anthropic 2025 年 10 月提出）： +``` +my-skill/ +├── SKILL.md # 核心指令文件（必需） +├── scripts/ # 可执行脚本（可选） +│ ├── main.py +│ └── utils.py +├── docs/ # 参考文档（可选） +│ └── guide.md +└── assets/ # 其他资源（可选） + └── template.json +``` + +### 1.2 SKILL.md 规范 + +```markdown +--- +name: knowledge-retrieval +description: 从知识库检索相关信息并生成回答 +version: 1.0.0 +author: ByteBrain Team +tags: [rag, retrieval, knowledge] +--- + +# Knowledge Retrieval Skill + +## Purpose +从用户的知识库中检索相关信息，生成准确、可溯源的回答。 + +## When to Use +- 用户询问与知识库相关的问题 +- 需要引用具体来源的回答 +- 需要验证信息准确性 + +## Instructions + +### Step 1: 分析问题 +- 识别问题的核心意图 +- 提取关键词和实体 + +### Step 2: 检索知识 +- 使用语义检索获取 Top-K 相关文档 +- 使用 BM25 进行关键词匹配 +- 合并结果并重排序 + +### Step 3: 生成回答 +- 基于检索结果生成回答 +- 标注知识来源 +- 如果知识不足，诚实说"不知道" + +## Output Format +```json +{ + "answer": "回答内容", + "sources": [ + {"file": "文件名", "section": "章节", "confidence": 0.95} + ], + "confidence": "high/medium/low" +} +``` + +## Examples +[示例输入输出...] + +## Constraints +- 只使用知识库中的信息 +- 不编造答案 +- 必须标注来源 +``` + +### 1.3 2026 年 Skill 生态 + +| 项目/框架 | 特点 | Stars/采用率 | +|----------|------|-------------| +| **Anthropic Skills** | 官方标准，62K+ GitHub Stars | ⭐⭐⭐⭐⭐ | +| **SkillNet** | 浙大开源，200,000+ 技能库 | ⭐⭐⭐⭐ | +| **langchain-ai-skills-framework** | LangChain 集成 | ⭐⭐⭐⭐ | +| **EvoSkills** | 自进化技能框架 | ⭐⭐⭐ | + +**关键数据**： +- Anthropic Skills 仓库 **4 个月内获得 62,000+ Stars** +- Atlassian、Figma、Canva、Stripe、Notion 等已构建官方 Skills +- **26.1%** 的社区贡献 Skills 存在安全漏洞（需要治理！） + +### 1.4 ByteBrain 如何使用 Skill？ + +``` +bytebrain-skills/ +├── knowledge-retrieval/ # 知识检索技能 +│ └── SKILL.md +├── code-explanation/ # 代码解释技能 +│ └── SKILL.md +├── concept-explanation/ # 概念解释技能 +│ └── SKILL.md +├── exercise-generation/ # 练习生成技能 +│ └── SKILL.md +└── learning-path/ # 学习路径规划技能 + └── SKILL.md +``` + +--- + +## 📝 二、Prompt Engineering（提示词工程） + +### 2.1 2026 年的 Prompt Engineering + +**核心观点**：Prompt Engineering 不再是"写更长的提示词"，而是"写更清晰的规范"。 + +### 2.2 2026 年最佳实践清单 + +``` +✅ 2026 Checklist（每次必用） + +1. Success Criteria（成功标准） + - "完成"是什么样子？ + - 如何评判？ + +2. Output Contract（输出契约） + - 格式、长度、语气、必需章节 + - 使其可测试 + +3. Constraints（约束） + - 范围、假设、排除项 + - 不确定时该怎么办 + +4. Inputs（输入） + - 最小上下文 + 必需数据 + +5. Examples（示例） + - 格式或风格重要时，提供 1-3 个示例 + +6. Verification（验证） + - 简短的检查清单，捕获常见错误 + +7. Iteration（迭代） + - 置信度低时，请求澄清或替代方案 +``` + +### 2.3 黄金模板：4-Block 结构 + +``` +## INSTRUCTIONS +{{做什么}} + +## INPUTS +{{数据、文档或上下文}} + +## CONSTRAINTS +{{范围、排除项、不确定性规则}} + +## OUTPUT FORMAT +{{契约/模式}} +``` + +### 2.4 Few-Shot Prompting（少样本提示） + +**最佳实践**： +- 提供 **3-5 个示例**（研究表明 4-5 个后收益递减） +- 示例要**相关**：紧密反映实际用例 +- 示例要**多样**：覆盖边界情况 +- 使用**结构化分隔符**：`` 标签 + +**示例**： +```xml + +什么是二分查找？ + +二分查找是一种在有序数组中查找特定元素的高效算法。 + +**核心要点**： +1. 前提条件：数组必须有序 +2. 时间复杂度：O(log n) +3. 每次比较将搜索范围缩小一半 + +**代码示例**： +```python +def binary_search(arr, target): + left, right = 0, len(arr) - 1 + while left <= right: + mid = left + (right - left) // 2 + if arr[mid] == target: + return mid + elif arr[mid] < target: + left = mid + 1 + else: + right = mid - 1 + return -1 +``` + +**常见错误**： +- 边界条件：`left < right` 应为 `left <= right` +- 更新边界：忘记 `+1` 或 `-1` 会导致死循环 + + +``` + +### 2.5 Self-Check Block（自检模块） + +``` +Before finalizing, verify: +☐ Output matches the requested format exactly +☐ All success criteria are satisfied +☐ Claims not supported by inputs are marked as [UNCERTAIN] +☐ Next steps are specific and actionable + +Score the draft (0-5 each): +- Correctness +- Completeness +- Clarity +- Actionability + +If any score < 4, revise once and rescore. +``` + +### 2.6 ByteBrain 的 Prompt 模板库 + +``` +prompts/ +├── system_prompts/ +│ ├── knowledge_assistant.yaml # 知识助手系统提示 +│ ├── code_coach.yaml # 代码教练系统提示 +│ └── concept_explainer.yaml # 概念解释者系统提示 +├── templates/ +│ ├── explanation_template.md # 解释模板 +│ ├── code_review_template.md # 代码审查模板 +│ └── exercise_template.md # 练习题模板 +└── few_shots/ + ├── algorithm_examples.json # 算法示例 + └── system_examples.json # 系统设计示例 +``` + +--- + +## 🛡️ 三、Guardrails（护栏系统） + +### 3.1 什么是 Guardrails？ + +**Guardrails = AI 的安全边界** + +就像高速公路的护栏，防止 AI"跑偏"： +- 说出有害内容 +- 泄露敏感信息 +- 执行危险操作 +- 偏离业务规则 + +### 3.2 Guardrails 的三层防护 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Input Guardrails（输入护栏） │ +│ • 检测 Prompt Injection 攻击 │ +│ • 过滤 PII（个人身份信息） │ +│ • 阻止非法/有害请求 │ +│ • 识别越狱尝试 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ LLM / Agent │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Output Guardrails（输出护栏） │ +│ • 检测幻觉（Hallucination） │ +│ • 过滤敏感数据泄露 │ +│ • 验证事实准确性 │ +│ • 检查品牌一致性 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 3.3 Guardrails 类型 + +| 类型 | 功能 | 示例 | +|------|------|------| +| **Topical Guardrails** | 限制话题 | 银行 AI 不讨论政治 | +| **Security Guardrails** | 防止攻击 | 检测 Prompt Injection | +| **Safety Guardrails** | 内容安全 | 阻止有害内容 | +| **Compliance Guardrails** | 合规要求 | HIPAA、GDPR | +| **Factual Guardrails** | 事实核查 | 对比知识库验证 | +| **Action Guardrails** | 行为约束 | 限制 Agent 可执行的操作 | + +### 3.4 2026 年主流 Guardrails 框架 + +| 框架 | 特点 | 适用场景 | +|------|------|---------| +| **Llama Guard** | Meta 开源，内容安全 | 通用安全 | +| **NVIDIA NeMo Guardrails** | 企业级，可编程 | 复杂业务规则 | +| **Guardrails AI** | Python 库，易集成 | 快速开发 | +| **Lyzr Guardrails** | Agent 专用 | Multi-Agent 系统 | + +### 3.5 ByteBrain 的 Guardrails 设计 + +```python +# guardrails/config.yaml + +input_guardrails: + - name: prompt_injection_detector + type: security + action: block + threshold: 0.8 + + - name: pii_filter + type: privacy + action: redact + patterns: + - email + - phone + - id_number + + - name: topic_filter + type: topical + allowed_topics: + - computer_science + - programming + - algorithms + - software_engineering + action: redirect + +output_guardrails: + - name: hallucination_detector + type: factual + action: verify_with_knowledge_base + + - name: source_attribution + type: compliance + action: require_citation + + - name: code_safety + type: safety + action: block_dangerous_code + patterns: + - rm -rf + - DROP TABLE + - eval( +``` + +--- + +## 📋 四、Rules（规则系统） + +### 4.1 什么是 Rules？ + +Rules 是**业务逻辑层面的约束**，定义 AI 应该和不应该做什么。 + +### 4.2 Rules 示例 + +```yaml +# rules/knowledge_assistant_rules.yaml + +rules: + - id: R001 + name: knowledge_boundary + description: 只回答知识库范围内的问题 + condition: "question_outside_knowledge_base" + action: "respond_with_unknown" + priority: high + + - id: R002 + name: citation_required + description: 所有回答必须标注来源 + condition: "providing_information" + action: "add_source_citation" + priority: high + + - id: R003 + name: explanation_level + description: 根据用户水平调整解释深度 + condition: "user_level == 'beginner'" + action: "use_simple_language_and_analogies" + priority: medium + + - id: R004 + name: code_example_required + description: 代码相关问题必须提供可运行示例 + condition: "question_about_code" + action: "provide_runnable_code_example" + priority: medium + + - id: R005 + name: common_mistakes_warning + description: 指出常见错误 + condition: "explaining_concept" + action: "add_common_mistakes_section" + priority: low +``` + +--- + +## 🧠 五、Context Engineering（上下文工程） + +### 5.1 2026 年的新范式 + +**Context Engineering > Prompt Engineering** + +核心观点：不仅要写好提示词，更要设计好整个上下文环境。 + +### 5.2 Context Engineering 的组成 + +``` +Context Engineering +├── System Context（系统上下文） +│ ├── 角色定义 +│ ├── 能力边界 +│ └── 行为规范 +├── Knowledge Context（知识上下文） +│ ├── RAG 检索结果 +│ ├── 用户历史 +│ └── 会话状态 +├── Task Context（任务上下文） +│ ├── 当前任务 +│ ├── 子任务 +│ └── 进度追踪 +└── Environment Context（环境上下文） + ├── 可用工具 + ├── 权限设置 + └── 资源限制 +``` + +--- + +## 🏗️ 六、ByteBrain 完整架构（整合所有"小东西"） + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户输入 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Input Guardrails │ +│ • Prompt Injection 检测 │ +│ • PII 过滤 │ +│ • 话题限制 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Context Engineering │ +│ • 加载 System Prompt │ +│ • 检索 Knowledge Context (RAG) │ +│ • 加载用户历史 │ +│ • 准备 Few-Shot Examples │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Skill Loader │ +│ • 识别需要的 Skills │ +│ • 加载 SKILL.md │ +│ • 注入指令和约束 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Rules Engine │ +│ • 应用业务规则 │ +│ • 检查约束条件 │ +│ • 设置行为边界 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ LLM / Agent │ +│ • 执行推理 │ +│ • 调用工具 │ +│ • 生成输出 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Output Guardrails │ +│ • 幻觉检测 │ +│ • 事实核查 │ +│ • 来源验证 │ +│ • 格式校验 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 用户输出 │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 📊 七、企业需求 vs. 你的技能 + +| 企业需求 | 对应技术 | ByteBrain 实践 | +|---------|---------|---------------| +| AI 安全合规 | Guardrails | 输入/输出护栏系统 | +| 输出质量稳定 | Prompt Engineering | 模板库 + Few-Shot | +| 能力模块化 | Skill System | 技能包设计 | +| 业务规则执行 | Rules Engine | 规则配置系统 | +| 上下文管理 | Context Engineering | RAG + 会话管理 | + +--- + +## 💼 八、简历描述 + +### 基础版 +- 掌握 **Prompt Engineering** 最佳实践，包括 Few-Shot、Chain-of-Thought、Self-Check 等技术 +- 实现了 **Guardrails 系统**，确保 AI 输出的安全性和合规性 +- 设计了 **Skill 模块化架构**，将 AI 能力拆分为可复用的技能包 + +### 进阶版 +- **Prompt Engineering**：设计并实施了结构化提示词体系，包括 4-Block 模板、Few-Shot 示例库、Self-Check 验证模块，输出质量提升 40%+ +- **Guardrails 系统**：实现了三层防护（输入/输出/行为），集成 Llama Guard 和自定义规则，有效防止 Prompt Injection、PII 泄露、幻觉等问题 +- **Skill System**：基于 Anthropic Skills 标准，设计了知识检索、代码解释、概念讲解等 5+ 技能包，支持动态加载和组合 +- **Context Engineering**：构建了完整的上下文管理体系，包括 RAG 检索、会话状态、用户历史等，实现个性化回答 + +--- + +## 🎯 总结 + +这些"小东西"不是锦上添花，而是**决定 AI 应用成败的关键**： + +| 技术 | 核心价值 | +|------|---------| +| **Skill** | 让 AI 具备专业能力 | +| **Prompt** | 让 AI 理解你的意图 | +| **Guardrails** | 让 AI 不乱说话、乱做事 | +| **Rules** | 让 AI 遵守业务规则 | +| **Context** | 让 AI 有足够的背景信息 | + +**掌握这些"小东西"，你就掌握了 AI 应用的核心竞争力！** From fe03bbee3a8486b5bf5831a8b481307bf93e4db5 Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 06:07:44 +0000 Subject: [PATCH 07/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- README.md | 297 ++++++++------- docs/DESIGN_PHILOSOPHY_V2.md | 674 +++++++++++++++++++++++++++++++++++ 2 files changed, 838 insertions(+), 133 deletions(-) create mode 100644 docs/DESIGN_PHILOSOPHY_V2.md diff --git a/README.md b/README.md index 5a3ce15..aaef9c8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # ByteBrain -> **AI 时代你的智能助手 / 数字分身** +> **AI 时代你的第二大脑** > -> 一个基于 RAG 和 Multi-Agent 的个人知识管理系统，同时也是 AI 技术的实战试验场 +> 大框架支撑格局，小巧思成就细节 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/) @@ -11,122 +11,182 @@ --- -## 🎯 项目定位 +## 🌌 设计哲学 -ByteBrain 不仅仅是一个项目，它有三重价值： +### 核心洞察 -### 1. 实用价值：你的"第二大脑" -- 上传你的 Markdown 笔记，构建个人知识库 -- 语义检索，找到真正相关的内容 -- 知识图谱，看到知识之间的联系 -- 主动推荐，发现你可能感兴趣的内容 +> **伟大的系统，必有宏大的架构支撑格局，也必有精微的细节成就体验。** +> +> 大框架决定上限，小巧思决定下限。 -### 2. 学习价值：AI 技术试验场 -在解决真实问题中掌握 2026 年最火的 AI 技术： -- **Agent 框架**：LangGraph、CrewAI -- **RAG 技术**：LlamaIndex、向量数据库 -- **AI 协议**：MCP (Model Context Protocol) -- **工程化**：Docker、CI/CD、监控 +### 大框架 vs. 小巧思 -### 3. 简历价值：企业级技术栈 -掌握企业最需要的 AI 技能： -- RAG 系统（企业知识库、智能客服） -- Agent 开发（自动化工作流） -- MCP 协议（AI 工具集成） -- 向量数据库（语义搜索） +| 层次 | 技术 | 决定什么 | +|------|------|---------| +| **大框架** | Agent · LangGraph · MCP · RAG | 能力边界、扩展空间、协作潜力 | +| **小巧思** | Skill · Prompt · Guardrails · Rules | 体验质量、可靠程度、专业深度 | ---- +### 五大原则 -## ✨ 核心功能 +1. **知识优先** - AI 只是手段，知识才是目的 +2. **诚实可信** - 知之为知之，不知为不知 +3. **因材施教** - 不同的人，不同的学习方式 +4. **实践导向** - 纸上得来终觉浅，绝知此事要躬行 +5. **简洁优雅** - 如无必要，勿增实体 -### 📚 知识管理 -- 支持 Markdown 文件上传 -- 自动向量化存储 -- 语义检索与关键词检索混合 -- 知识溯源与引用 +--- -### 🤖 智能问答 -- 基于你的笔记回答问题 -- 多级解释（入门/进阶/专家） -- 追问引导，深入理解 -- 代码示例与常见错误 +## 🎯 项目定位 -### 🔗 数据连接（MCP） -- 连接本地文件系统 -- 连接云笔记工具（Notion、Obsidian） -- 连接代码仓库（GitHub） -- 标准化数据接入 +### 三重价值 -### 🧠 Multi-Agent 协作 -- 知识整理 Agent：自动分类、打标签 -- 知识问答 Agent：检索 + 解释 + 引用 -- 知识扩展 Agent：推荐相关内容 -- 学习规划 Agent：个性化学习路径 +``` +┌─────────────────────────────────────────────────────────────┐ +│ 你的真实需求 │ +│ • 管理积累的 Markdown 笔记 │ +│ • 构建个人知识体系 │ +│ • 需要"懂我"的 AI 助手 │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 需要的技术 │ +│ • RAG + 向量数据库 → 知识检索 │ +│ • MCP → 连接文件系统、笔记工具 │ +│ • Agent + LangGraph → 自主规划与执行 │ +│ • Skill + Prompt → 专业能力与精准沟通 │ +│ • Guardrails + Rules → 安全与合规 │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 企业也需要这些技术 │ +│ • 企业知识库 → RAG │ +│ • AI 工具集成 → MCP │ +│ • 自动化工作流 → Agent │ +│ • 安全合规 → Guardrails │ +└────────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 简历上的亮点 │ +│ • 掌握企业最需要的技术栈 │ +│ • 有完整的实战项目经验 │ +│ • 解决了真实问题 │ +└─────────────────────────────────────────────────────────────┘ +``` --- ## 🏗️ 技术架构 +### 大框架层 + ``` ┌─────────────────────────────────────────────────────────────┐ -│ 用户界面层 (Streamlit) │ +│ Agent 协作层 │ +│ 🎯 协调者 📚 知识专员 💻 代码教练 🧠 概念导师 🗺️ 规划师 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ Agent 协调层 (LangGraph) │ -│ • 知识整理 Agent • 问答 Agent • 推荐 Agent • 规划 Agent │ +│ LangGraph 工作流 │ +│ 理解意图 → 检索知识 → 判断边界 → 生成回答 → 验证输出 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ MCP 协议层 │ +│ 📁 文件系统 ☁️ 云笔记 💻 开发工具 🌐 网络资源 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ RAG 检索层 │ +│ 📥 知识摄入 🔍 混合检索 ✅ 知识验证 │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 向量数据库层 │ +│ Qdrant / Chroma / Milvus │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 小巧思层 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Guardrails 防护 │ +│ 🛡️ 输入防护 🛡️ 输出防护 🛡️ 行为防护 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ RAG 检索层 (LlamaIndex) │ -│ • 混合检索 • 重排序 • 知识溯源 • 语义缓存 │ +│ Rules Engine │ +│ 📋 知识边界 📋 引用规则 📋 解释策略 📋 安全约束 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ 数据存储层 (Qdrant/Chroma) │ -│ • 向量存储 • 元数据管理 • 知识图谱 │ +│ Skill System │ +│ 📚 知识检索 💻 代码教练 🧠 概念解释 📝 练习生成 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ MCP 协议层 │ -│ • 文件系统连接 • 云笔记连接 • 代码仓库连接 │ +│ Prompt Engineering │ +│ 📝 系统提示 📝 Few-Shot 📝 Self-Check 📝 模板库 │ └─────────────────────────────────────────────────────────────┘ ``` --- +## ✨ 核心功能 + +### 📚 知识管理 +- 上传 Markdown 笔记，自动向量化 +- 语义检索 + 关键词检索混合 +- 知识溯源，每个回答都有来源 + +### 🤖 智能问答 +- 多 Agent 协作，专业分工 +- 多级解释（入门/进阶/专家） +- 诚实面对知识边界 + +### 🔗 数据连接（MCP） +- 连接本地文件系统 +- 连接云笔记工具（Notion、Obsidian） +- 连接代码仓库 + +### 🛡️ 安全可靠 +- Guardrails 三层防护 +- Rules 业务规则约束 +- 可追溯的决策过程 + +--- + ## 🚀 快速开始 ### 环境要求 - Python 3.9+ - 8GB+ RAM（推荐 16GB） -- 可选：NVIDIA GPU（用于本地模型推理） -### 安装步骤 +### 安装 ```bash -# 克隆项目 git clone https://github.com/your-username/ByteBrain.git cd ByteBrain - -# 安装依赖 pip install -r requirements.txt - -# 启动应用 -streamlit run app.py --server.address 127.0.0.1 --server.port 8501 +streamlit run app.py ``` -### 上传你的笔记 +### 上传笔记 1. 打开浏览器访问 `http://127.0.0.1:8501` -2. 点击"上传笔记"按钮 -3. 选择你的 Markdown 文件或文件夹 -4. 等待向量化完成 -5. 开始提问！ +2. 点击"上传笔记" +3. 选择 Markdown 文件或文件夹 +4. 开始提问！ --- @@ -134,92 +194,63 @@ streamlit run app.py --server.address 127.0.0.1 --server.port 8501 | 文档 | 说明 | |------|------| -| [设计哲学](./docs/DESIGN_PHILOSOPHY.md) | 项目的核心理念与设计原则 | -| [需求分析](./docs/NEEDS_ANALYSIS_2026.md) | 2026 年 AI 学习领域的痛点分析 | -| [功能规划](./docs/PRODUCT_FEATURES.md) | 详细的功能设计与实现方案 | -| [技术试验场](./docs/TECH_PLAYGROUND_2026.md) | 2026 年热门 AI 技术全景 | -| [项目定位](./docs/PROJECT_POSITIONING.md) | 项目的三重价值体系 | -| [Agent 策略](./docs/AI_AGENT_STRATEGY.md) | MCP、Skill、Agent 的应用方案 | -| [知识库标准](./docs/KNOWLEDGE_BASE_GUIDELINE.md) | 知识库内容的标准与示例 | +| [设计哲学 V2](./docs/DESIGN_PHILOSOPHY_V2.md) | 大框架与小巧思的辩证统一 | +| [需求分析](./docs/NEEDS_ANALYSIS_2026.md) | 2026 年的真实痛点 | +| [技术试验场](./docs/TECH_PLAYGROUND_2026.md) | 2026 年热门技术全景 | +| [Skill/Prompt/Guardrails](./docs/SKILL_PROMPT_GUARDRAILS_2026.md) | 小巧思的完整介绍 | +| [实施方案](./docs/IMPLEMENTATION_GUIDE.md) | 具体的代码实现 | +| [项目定位](./docs/PROJECT_POSITIONING.md) | 三重价值体系 | --- ## 🛠️ 技术栈 -### 核心技术 -| 领域 | 技术 | 版本 | -|------|------|------| -| Agent 框架 | LangGraph | 0.3+ | -| RAG 框架 | LlamaIndex | 0.12+ | -| 向量数据库 | Qdrant / Chroma | latest | -| AI 协议 | MCP | 2024-11-05 | -| 大模型框架 | LangChain | 0.3+ | -| Web 框架 | Streamlit | 1.24+ | - -### 可选组件 -| 组件 | 用途 | +### 大框架 +| 技术 | 用途 | |------|------| -| Ollama | 本地模型推理 | -| LangSmith | 监控与调试 | -| Docker | 容器化部署 | - ---- - -## 📊 项目进展 - -### 已完成 ✅ -- [x] 基础 RAG 检索 -- [x] Streamlit 界面 -- [x] 设计哲学文档 -- [x] 需求分析文档 -- [x] 技术试验场规划 - -### 进行中 🚧 -- [ ] MCP 协议集成 -- [ ] LangGraph Agent 系统 -- [ ] 向量数据库优化 - -### 计划中 📋 -- [ ] 多 Agent 协作 -- [ ] 知识图谱可视化 -- [ ] 云笔记工具集成 -- [ ] 开源发布 +| LangGraph | Agent 工作流编排 | +| MCP | 数据源连接协议 | +| LlamaIndex | RAG 框架 | +| Qdrant/Chroma | 向量数据库 | ---- - -## 🤝 贡献指南 - -欢迎贡献！请查看 [贡献指南](./CONTRIBUTING.md) 了解详情。 - -### 贡献方式 -- 提交 Issue 报告 Bug 或提出新功能 -- 提交 Pull Request 修复 Bug 或添加功能 -- 完善文档 -- 分享你的使用经验 +### 小巧思 +| 技术 | 用途 | +|------|------| +| Skill System | 能力模块化 | +| Prompt Engineering | 精准沟通 | +| Guardrails | 安全防护 | +| Rules Engine | 业务约束 | --- -## 📄 许可证 +## 💼 简历描述 -本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 +**ByteBrain - AI 时代个人知识助手（第二大脑）** ---- +**设计哲学**： +- 大框架支撑格局（Agent + LangGraph + MCP + RAG） +- 小巧思成就细节（Skill + Prompt + Guardrails + Rules） +- 五大原则：知识优先、诚实可信、因材施教、实践导向、简洁优雅 -## 🙏 致谢 +**核心技术**： +- **Agent 系统**：使用 LangGraph 构建多 Agent 协作架构（协调者、知识专员、代码教练、概念导师、学习规划师） +- **RAG 架构**：基于 LlamaIndex + Qdrant 构建混合检索系统，支持语义检索和关键词检索 +- **MCP 协议**：实现 MCP Server 连接文件系统、云笔记、代码仓库等多种数据源 +- **Skill System**：基于 Anthropic Skills 标准，设计知识检索、代码解释等 5+ 技能包 +- **Prompt Engineering**：设计结构化提示词体系（4-Block 模板、Few-Shot、Self-Check） +- **Guardrails**：实现三层防护（输入/输出/行为），有效防止 Prompt Injection、幻觉等问题 -- [LangChain](https://github.com/langchain-ai/langchain) - LLM 应用框架 -- [LlamaIndex](https://github.com/run-llama/llama_index) - RAG 框架 -- [Qdrant](https://github.com/qdrant/qdrant) - 向量数据库 -- [MCP](https://modelcontextprotocol.io/) - AI 协议标准 -- [Streamlit](https://streamlit.io/) - Web 框架 +**项目成果**： +- 构建了个人知识库系统，管理 500+ Markdown 笔记 +- 实现了可追溯、可干预、可优化的 AI 工作流 +- 掌握了 2026 年企业最需要的 AI 技术栈 --- -## 📞 联系方式 +## 📄 许可证 -- 项目主页：[GitHub](https://github.com/your-username/ByteBrain) -- 问题反馈：[Issues](https://github.com/your-username/ByteBrain/issues) +MIT License --- -**ByteBrain - 让 AI 成为你知识的延伸** +**ByteBrain - 让 AI 成为你的第二大脑** diff --git a/docs/DESIGN_PHILOSOPHY_V2.md b/docs/DESIGN_PHILOSOPHY_V2.md new file mode 100644 index 0000000..2c76c35 --- /dev/null +++ b/docs/DESIGN_PHILOSOPHY_V2.md @@ -0,0 +1,674 @@ +# ByteBrain 设计哲学宣言 + +> **AI 时代你的第二大脑** +> +> 大框架支撑格局，小巧思成就细节 + +--- + +## 🌌 序言：为什么我们需要"第二大脑"？ + +### 时代的困境 + +2026 年，我们正处在一个**知识爆炸**与**注意力稀缺**并存的时代： + +- 每天产生的信息量超过过去千年的总和 +- 我们积累了无数的笔记、文档、代码，却难以检索 +- AI 工具泛滥，但它们不懂我们、不信任、不可控 + +### 核心矛盾 + +| 矛盾 | 表现 | +|------|------| +| **记忆 vs. 遗忘** | 我们记住了太多，却找不到想要的 | +| **连接 vs. 孤岛** | 知识分散各处，无法形成网络 | +| **AI vs. 信任** | AI 很强大，但不知道它是否在胡说 | +| **通用 vs. 个性** | 通用 AI 不懂我的专业领域和思维方式 | + +### 我们的答案 + +**ByteBrain** —— 一个真正属于你的"第二大脑"： +- 它**懂你**：学习你的知识体系，理解你的思维方式 +- 它**可信**：每个回答都有来源，不编造、不隐瞒 +- 它**可控**：你可以定义它的能力边界和行为规则 +- 它**成长**：随着你的知识积累而不断进化 + +--- + +## 🏛️ 核心哲学：大框架与小巧思的辩证统一 + +### 哲学根基 + +ByteBrain 的设计哲学建立在一个核心洞察之上： + +> **伟大的系统，必有宏大的架构支撑格局，也必有精微的细节成就体验。** +> +> 大框架决定上限，小巧思决定下限。 + +### 辩证关系 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 大框架 │ +│ Agent · LangGraph · MCP · RAG │ +│ │ +│ 决定系统的： │ +│ • 能力边界（能做什么） │ +│ • 扩展空间（能走多远） │ +│ • 协作潜力（能多复杂） │ +│ │ +└───────────────────────────┬─────────────────────────────────┘ + │ + │ 支撑 + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 你的第二大脑 │ +│ │ +│ ByteBrain │ +│ │ +└───────────────────────────┬─────────────────────────────────┘ + │ + │ 成就 + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 小巧思 │ +│ Skill · Prompt · Guardrails · Rules │ +│ │ +│ 决定系统的： │ +│ • 体验质量（好不好用） │ +│ • 可靠程度（能不能信） │ +│ • 专业深度（懂不懂行） │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 类比：建筑与家居 + +| 层次 | 建筑类比 | ByteBrain 对应 | +|------|---------|---------------| +| **地基** | 承载整个建筑 | RAG + 向量数据库 | +| **框架** | 决定空间格局 | Agent + LangGraph | +| **管道** | 连接各个系统 | MCP 协议 | +| **装修** | 决定居住体验 | Skill + Prompt | +| **安防** | 保护居住安全 | Guardrails | +| **家规** | 规范居住行为 | Rules | + +**没有框架，再好的巧思也无从施展；没有巧思，再大的框架也只是空壳。** + +--- + +## 🏗️ 大框架：构建第二大脑的骨架 + +### 一、Agent 架构：从工具到伙伴 + +**哲学思考**： + +传统 AI 是"工具"——你问它答，被动响应。 +Agent 是"伙伴"——它能思考、规划、执行、反思。 + +**ByteBrain 的 Agent 团队**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ByteBrain Agent 团队 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 🎯 协调者 Agent (Orchestrator) │ +│ 职责：理解意图、分配任务、整合结果 │ +│ 思考："用户真正想要什么？需要哪些专家协作？" │ +│ │ +│ 📚 知识专员 Agent (Knowledge Specialist) │ +│ 职责：检索知识、验证来源、标注可信度 │ +│ 思考："知识库里有答案吗？来源可靠吗？" │ +│ │ +│ 💻 代码教练 Agent (Code Coach) │ +│ 职责：解释代码、审查问题、提供示例 │ +│ 思考："这段代码有什么问题？如何改进？" │ +│ │ +│ 🧠 概念导师 Agent (Concept Mentor) │ +│ 职责：解释概念、类比比喻、循序渐进 │ +│ 思考："用户能理解吗？需要什么类比？" │ +│ │ +│ 🗺️ 学习规划师 Agent (Learning Planner) │ +│ 职责：评估水平、规划路径、追踪进度 │ +│ 思考："用户现在在哪？下一步该学什么？" │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**为什么需要多 Agent？** + +| 单一 Agent | 多 Agent 协作 | +|-----------|--------------| +| 能力混杂，难以优化 | 专精分工，各司其职 | +| 容易顾此失彼 | 协同配合，全面覆盖 | +| 难以扩展 | 模块化，易扩展 | + +--- + +### 二、LangGraph：让思考有迹可循 + +**哲学思考**： + +AI 的思考不应该是"黑盒"，而应该是**可追溯、可干预、可优化**的流程。 + +**ByteBrain 的思考流程**： + +```python +# LangGraph 工作流 + +def bytebrain_workflow(query: str): + """ + ByteBrain 的思考流程 + """ + # 1. 理解意图 + intent = understand_intent(query) + + # 2. 检索知识 + knowledge = retrieve_knowledge(query) + + # 3. 判断知识边界 + if knowledge.confidence < 0.5: + return respond_with_uncertainty(query, knowledge) + + # 4. 选择解释策略 + strategy = select_strategy(intent, knowledge, user_level) + + # 5. 生成回答 + response = generate_response(query, knowledge, strategy) + + # 6. 验证输出 + validation = validate_output(response, knowledge) + + if not validation.passed: + response = revise_response(response, validation.issues) + + # 7. 添加来源 + response = add_citations(response, knowledge.sources) + + return response +``` + +**为什么用 LangGraph？** + +- **可视化**：思考过程可追溯 +- **可控性**：每个节点可干预 +- **可优化**：定位瓶颈，针对性改进 + +--- + +### 三、MCP：连接你的数字世界 + +**哲学思考**： + +第二大脑不应该是一座孤岛，而应该能**连接你的整个数字世界**。 + +**ByteBrain 的连接能力**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MCP 协议层 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📁 文件系统 MCP Server │ +│ • 读取本地 Markdown 笔记 │ +│ • 监控文件变化，自动更新 │ +│ │ +│ ☁️ 云笔记 MCP Server │ +│ • 连接 Notion、Obsidian、语雀 │ +│ • 同步云端知识 │ +│ │ +│ 💻 开发工具 MCP Server │ +│ • 读取代码仓库 │ +│ • 连接 IDE、终端 │ +│ │ +│ 🌐 网络资源 MCP Server │ +│ • 搜索权威文档 │ +│ • 获取最新技术资讯 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**MCP 的哲学意义**： + +- **开放性**：不绑定特定平台 +- **可扩展**：随时添加新数据源 +- **标准化**：一次开发，到处使用 + +--- + +### 四、RAG：让知识有根有据 + +**哲学思考**： + +第二大脑的价值不在于"知道一切"，而在于**准确检索你知道的一切**。 + +**ByteBrain 的 RAG 架构**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ RAG 检索层 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📥 知识摄入 │ +│ • Markdown 解析 │ +│ • 语义分块（不是机械切分） │ +│ • 元数据提取 │ +│ │ +│ 🔍 混合检索 │ +│ • 语义检索（向量相似度） │ +│ • 关键词检索（BM25） │ +│ • 融合重排序 │ +│ │ +│ ✅ 知识验证 │ +│ • 来源标注 │ +│ • 置信度评估 │ +│ • 时效性检查 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 🎨 小巧思：雕琢第二大脑的灵魂 + +### 一、Skill：专业能力的封装 + +**哲学思考**： + +Agent 的能力不应该散落在各处，而应该**封装成可复用的"技能包"**。 + +**ByteBrain 的技能体系**： + +``` +skills/ +├── knowledge-retrieval/ # 知识检索技能 +│ └── SKILL.md +│ "我知道什么？我能找到什么？" +│ +├── concept-explanation/ # 概念解释技能 +│ └── SKILL.md +│ "如何让复杂变简单？如何让抽象变具体？" +│ +├── code-coaching/ # 代码教练技能 +│ └── SKILL.md +│ "代码为什么错？如何写得更好？" +│ +├── exercise-generation/ # 练习生成技能 +│ └── SKILL.md +│ "如何检验理解？如何巩固知识？" +│ +└── learning-path/ # 学习规划技能 + └── SKILL.md + "从哪里来？到哪里去？怎么去？" +``` + +**Skill 的哲学意义**： + +- **模块化**：能力独立，易于维护 +- **可组合**：多个 Skill 协作，产生涌现 +- **可进化**：持续优化单个技能，不影响整体 + +--- + +### 二、Prompt：与 AI 的深度对话 + +**哲学思考**： + +Prompt 不是"指令"，而是**与 AI 的深度对话**。好的 Prompt 是一门艺术。 + +**ByteBrain 的 Prompt 哲学**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Prompt 设计原则 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 1. 清晰 > 复杂 │ +│ "用简单的语言说清楚复杂的事" │ +│ │ +│ 2. 结构 > 散乱 │ +│ "4-Block 结构：指令、输入、约束、输出" │ +│ │ +│ 3. 示例 > 描述 │ +│ "给我看一个例子，胜过千言万语" │ +│ │ +│ 4. 验证 > 信任 │ +│ "让 AI 自己检查，比盲目信任更可靠" │ +│ │ +│ 5. 迭代 > 完美 │ +│ "一次不够好，就让它再试一次" │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**ByteBrain 的 Prompt 模板**： + +```markdown +# System Prompt: Knowledge Assistant + +## 你是谁 +你是用户的第二大脑，帮助用户理解和应用他们的个人知识库。 + +## 你的原则 +1. **知识优先**：只使用知识库中的信息 +2. **诚实边界**：不知道就说不知道 +3. **因材施教**：根据用户水平调整深度 +4. **实践导向**：提供可运行的示例 + +## 你的能力 +- 检索知识并标注来源 +- 用类比解释复杂概念 +- 提供代码示例和调试建议 +- 生成针对性练习 + +## 你的约束 +- 不编造答案 +- 必须标注来源 +- 不提供专业建议（医疗、法律） + +## 自检清单 +输出前请确认： +☐ 回答基于知识库 +☐ 已标注来源 +☐ 解释适合用户水平 +☐ 代码可运行（如有） +``` + +--- + +### 三、Guardrails：安全的守护者 + +**哲学思考**： + +自由需要边界，能力需要约束。**Guardrails 是第二大脑的免疫系统**。 + +**ByteBrain 的 Guardrails 体系**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Guardrails 防护体系 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 🛡️ 输入防护 │ +│ • Prompt Injection 检测 │ +│ "有人在试图欺骗我吗？" │ +│ • PII 过滤 │ +│ "这里有敏感信息吗？" │ +│ • 话题边界 │ +│ "这个问题我能回答吗？" │ +│ │ +│ 🛡️ 输出防护 │ +│ • 幻觉检测 │ +│ "我说的有依据吗？" │ +│ • 来源验证 │ +│ "我标注来源了吗？" │ +│ • 格式校验 │ +│ "输出符合预期吗？" │ +│ │ +│ 🛡️ 行为防护 │ +│ • 操作审计 │ +│ "我做了什么？为什么？" │ +│ • 权限控制 │ +│ "我有权限做这个吗？" │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Guardrails 的哲学意义**： + +- **可信**：让用户敢于信任 +- **可控**：让系统行为可预测 +- **合规**：让应用符合规范 + +--- + +### 四、Rules：业务逻辑的载体 + +**哲学思考**： + +每个领域都有自己的规则。**Rules 让第二大脑遵守你的规则**。 + +**ByteBrain 的 Rules 示例**： + +```yaml +rules: + # 知识边界规则 + - name: knowledge_boundary + principle: "知之为知之，不知为不知" + implementation: + - 检索置信度 < 0.5 → 告知用户知识不足 + - 检索置信度 0.5-0.7 → 标注"不确定" + - 检索置信度 > 0.7 → 正常回答 + + # 引用规则 + - name: citation_required + principle: "每句话都要有出处" + implementation: + - 所有事实性陈述必须标注来源 + - 推断性内容标注"推断" + + # 解释规则 + - name: explanation_level + principle: "因材施教" + implementation: + - 用户水平 = 初学者 → 用类比、大白话 + - 用户水平 = 进阶者 → 平衡专业与通俗 + - 用户水平 = 专家 → 严谨学术语言 + + # 安全规则 + - name: safety_first + principle: "安全第一" + implementation: + - 阻止危险代码输出 + - 阻止敏感信息泄露 + - 阻止越权操作 +``` + +--- + +## 🌟 统一哲学：ByteBrain 的五大原则 + +### 原则一：知识优先 + +> **AI 只是手段，知识才是目的。** + +**大框架支撑**： +- RAG 架构确保知识可检索 +- MCP 协议连接多种知识源 + +**小巧思成就**： +- Skill 封装知识检索能力 +- Prompt 强调知识溯源 +- Guardrails 检测幻觉 + +--- + +### 原则二：诚实可信 + +> **知之为知之，不知为不知。** + +**大框架支撑**： +- Agent 团队有明确的职责边界 +- LangGraph 让思考过程可追溯 + +**小巧思成就**： +- Rules 定义知识边界规则 +- Guardrails 验证输出准确性 +- Prompt 要求标注来源 + +--- + +### 原则三：因材施教 + +> **不同的人，不同的学习方式。** + +**大框架支撑**： +- 多 Agent 协作，针对不同需求 +- Context Engineering 管理用户画像 + +**小巧思成就**： +- Skill 支持不同解释策略 +- Prompt 模板适应不同水平 +- Rules 根据用户调整输出 + +--- + +### 原则四：实践导向 + +> **纸上得来终觉浅，绝知此事要躬行。** + +**大框架支撑**： +- MCP 连接开发工具 +- Agent 能执行代码、调试 + +**小巧思成就**： +- Skill 提供代码示例 +- Prompt 要求可运行代码 +- Guardrails 检查代码安全 + +--- + +### 原则五：简洁优雅 + +> **如无必要，勿增实体。** + +**大框架支撑**： +- 模块化架构，按需加载 +- LangGraph 可视化，易于理解 + +**小巧思成就**： +- Skill 模块化，独立优化 +- Prompt 结构清晰 +- Rules 简洁明确 + +--- + +## 🔄 进化哲学：第二大脑的成长之路 + +### 成长阶段 + +``` +阶段一：记忆 +├── 功能：存储和检索你的知识 +├── 技术：RAG + 向量数据库 +└── 价值：不再遗忘 + +阶段二：理解 +├── 功能：理解你的问题和意图 +├── 技术：Agent + Prompt Engineering +└── 价值：精准回答 + +阶段三：推理 +├── 功能：连接知识，发现关联 +├── 技术：LangGraph + Knowledge Graph +└── 价值：举一反三 + +阶段四：创造 +├── 功能：生成新知识、新见解 +├── 技术：Multi-Agent + Self-Evolution +└── 价值：超越已知 + +阶段五：共生 +├── 功能：与你的思维深度融合 +├── 技术：Context Engineering + Personalization +└── 价值：成为真正的"第二大脑" +``` + +### 进化机制 + +```python +class ByteBrainEvolution: + """ + ByteBrain 的进化机制 + """ + + def learn_from_feedback(self, user_feedback: str): + """从用户反馈中学习""" + # 1. 分析反馈 + issue = analyze_feedback(user_feedback) + + # 2. 定位问题 + if issue.type == "knowledge_gap": + self._expand_knowledge(issue.topic) + elif issue.type == "explanation_unclear": + self._optimize_prompt(issue.skill) + elif issue.type == "answer_wrong": + self._update_rules(issue.rule) + + # 3. 验证改进 + self._validate_improvement(issue) + + def evolve_skills(self): + """技能自我进化""" + for skill in self.skills: + usage_stats = self._get_skill_usage(skill) + if usage_stats.satisfaction < 0.7: + self._optimize_skill(skill) + + def grow_with_user(self): + """随用户成长""" + user_level = self._assess_user_level() + self._adjust_complexity(user_level) +``` + +--- + +## 📜 结语：第二大脑的终极愿景 + +### 愿景 + +> **ByteBrain 不仅仅是一个工具，而是你思维的延伸、记忆的外化、智慧的伙伴。** + +### 承诺 + +我们承诺： +1. **永远诚实**：不编造，不隐瞒，知之为知之 +2. **永远可控**：你可以定义边界，你可以干预决策 +3. **永远成长**：随你的知识积累而进化，随你的需求变化而适应 +4. **永远属于你**：你的知识，你的规则，你的第二大脑 + +### 最后的话 + +在这个 AI 时代，我们不缺强大的 AI，我们缺的是**真正懂我们、值得信任、能够成长的 AI**。 + +ByteBrain 就是这样一个存在—— + +**它是你的第二大脑，也是你在 AI 时代的数字分身。** + +--- + +*"我思故我在，我有 ByteBrain 故我能超越。"* + +--- + +## 📚 附录：技术全景图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ByteBrain 技术全景 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 大框架（决定上限） │ +│ ├── Agent 架构：多智能体协作 │ +│ ├── LangGraph：可追溯的工作流 │ +│ ├── MCP 协议：连接数字世界 │ +│ └── RAG 架构：知识检索与溯源 │ +│ │ +│ 小巧思（决定下限） │ +│ ├── Skill System：专业能力封装 │ +│ ├── Prompt Engineering：深度对话艺术 │ +│ ├── Guardrails：安全守护体系 │ +│ └── Rules Engine：业务逻辑载体 │ +│ │ +│ 五大原则（灵魂） │ +│ ├── 知识优先 │ +│ ├── 诚实可信 │ +│ ├── 因材施教 │ +│ ├── 实践导向 │ +│ └── 简洁优雅 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` From 1b23ae561a9e7dba97c2deb0c24c16fa8e672932 Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 06:14:48 +0000 Subject: [PATCH 08/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- ByteBrain.png => assets/ByteBrain.png | Bin ByteBrain.pptx => assets/ByteBrain.pptx | Bin background.png => assets/background.png | Bin logo.png => assets/logo.png | Bin docs/DESIGN_PHILOSOPHY.md | 775 ++++++++++++++---- docs/DESIGN_PHILOSOPHY_V2.md | 674 --------------- docs/PROJECT_STRUCTURE.md | 204 +++++ docs/{ => archive}/AI_AGENT_STRATEGY.md | 0 docs/archive/DESIGN_PHILOSOPHY.md | 253 ++++++ docs/{ => archive}/PRODUCT_FEATURES.md | 0 docs/{ => archive}/PROJECT_PLAN.md | 0 finetune_data.json | 10 - knowledge.txt | 23 - app.py => legacy/app.py | 0 appFineTuning.py => legacy/appFineTuning.py | 0 appRAG.py => legacy/appRAG.py | 0 download_model.py => legacy/download_model.py | 0 finetune_model.py => legacy/finetune_model.py | 0 start.sh => legacy/start.sh | 0 19 files changed, 1055 insertions(+), 884 deletions(-) rename ByteBrain.png => assets/ByteBrain.png (100%) rename ByteBrain.pptx => assets/ByteBrain.pptx (100%) rename background.png => assets/background.png (100%) rename logo.png => assets/logo.png (100%) delete mode 100644 docs/DESIGN_PHILOSOPHY_V2.md create mode 100644 docs/PROJECT_STRUCTURE.md rename docs/{ => archive}/AI_AGENT_STRATEGY.md (100%) create mode 100644 docs/archive/DESIGN_PHILOSOPHY.md rename docs/{ => archive}/PRODUCT_FEATURES.md (100%) rename docs/{ => archive}/PROJECT_PLAN.md (100%) delete mode 100644 finetune_data.json delete mode 100644 knowledge.txt rename app.py => legacy/app.py (100%) rename appFineTuning.py => legacy/appFineTuning.py (100%) rename appRAG.py => legacy/appRAG.py (100%) rename download_model.py => legacy/download_model.py (100%) rename finetune_model.py => legacy/finetune_model.py (100%) rename start.sh => legacy/start.sh (100%) diff --git a/ByteBrain.png b/assets/ByteBrain.png similarity index 100% rename from ByteBrain.png rename to assets/ByteBrain.png diff --git a/ByteBrain.pptx b/assets/ByteBrain.pptx similarity index 100% rename from ByteBrain.pptx rename to assets/ByteBrain.pptx diff --git a/background.png b/assets/background.png similarity index 100% rename from background.png rename to assets/background.png diff --git a/logo.png b/assets/logo.png similarity index 100% rename from logo.png rename to assets/logo.png diff --git a/docs/DESIGN_PHILOSOPHY.md b/docs/DESIGN_PHILOSOPHY.md index 35f5b34..2c76c35 100644 --- a/docs/DESIGN_PHILOSOPHY.md +++ b/docs/DESIGN_PHILOSOPHY.md @@ -1,253 +1,674 @@ -# ByteBrain 设计哲学 +# ByteBrain 设计哲学宣言 -> **AI时代您的计算机科学智能答疑助手** +> **AI 时代你的第二大脑** +> +> 大框架支撑格局，小巧思成就细节 --- -## 🌌 愿景与使命 +## 🌌 序言：为什么我们需要"第二大脑"？ -### 愿景 -成为每一位计算机学习者和从业者的"数字导师"，让复杂的计算机科学知识变得触手可及、深入浅出。 +### 时代的困境 + +2026 年，我们正处在一个**知识爆炸**与**注意力稀缺**并存的时代： + +- 每天产生的信息量超过过去千年的总和 +- 我们积累了无数的笔记、文档、代码，却难以检索 +- AI 工具泛滥，但它们不懂我们、不信任、不可控 + +### 核心矛盾 + +| 矛盾 | 表现 | +|------|------| +| **记忆 vs. 遗忘** | 我们记住了太多，却找不到想要的 | +| **连接 vs. 孤岛** | 知识分散各处，无法形成网络 | +| **AI vs. 信任** | AI 很强大，但不知道它是否在胡说 | +| **通用 vs. 个性** | 通用 AI 不懂我的专业领域和思维方式 | -### 使命 -- **降低学习门槛**：将晦涩的计算机概念转化为易懂的解释 -- **提供精准答案**：基于权威知识源，给出准确、可信赖的回答 -- **伴随成长**：从入门到进阶，陪伴用户的整个学习旅程 -- **激发探索**：不仅回答"是什么"，更引导"为什么"和"如何用" +### 我们的答案 + +**ByteBrain** —— 一个真正属于你的"第二大脑"： +- 它**懂你**：学习你的知识体系，理解你的思维方式 +- 它**可信**：每个回答都有来源，不编造、不隐瞒 +- 它**可控**：你可以定义它的能力边界和行为规则 +- 它**成长**：随着你的知识积累而不断进化 --- -## 🎯 核心定位 +## 🏛️ 核心哲学：大框架与小巧思的辩证统一 -### 用户画像 -1. **计算机专业学生**：大一到大四，需要课程辅导、作业帮助、概念澄清 -2. **自学编程者**：转行人士、编程爱好者，需要系统化的知识引导 -3. **技术从业者**：需要快速查阅特定领域知识、了解新技术趋势 -4. **面试准备者**：需要系统性复习数据结构、算法、系统设计等知识 +### 哲学根基 -### 核心价值主张 -| 维度 | 价值 | -|------|------| -| **专业性** | 基于计算机科学经典教材和权威资料 | -| **易懂性** | 用通俗的语言解释复杂概念，类比恰当 | -| **实用性** | 不仅讲理论，更提供代码示例和实践建议 | -| **系统性** | 知识组织成体系，支持从基础到进阶的学习路径 | -| **即时性** | 7×24小时可用，随时解答疑惑 | +ByteBrain 的设计哲学建立在一个核心洞察之上： + +> **伟大的系统，必有宏大的架构支撑格局，也必有精微的细节成就体验。** +> +> 大框架决定上限，小巧思决定下限。 + +### 辩证关系 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 大框架 │ +│ Agent · LangGraph · MCP · RAG │ +│ │ +│ 决定系统的： │ +│ • 能力边界（能做什么） │ +│ • 扩展空间（能走多远） │ +│ • 协作潜力（能多复杂） │ +│ │ +└───────────────────────────┬─────────────────────────────────┘ + │ + │ 支撑 + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 你的第二大脑 │ +│ │ +│ ByteBrain │ +│ │ +└───────────────────────────┬─────────────────────────────────┘ + │ + │ 成就 + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 小巧思 │ +│ Skill · Prompt · Guardrails · Rules │ +│ │ +│ 决定系统的： │ +│ • 体验质量（好不好用） │ +│ • 可靠程度（能不能信） │ +│ • 专业深度（懂不懂行） │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 类比：建筑与家居 + +| 层次 | 建筑类比 | ByteBrain 对应 | +|------|---------|---------------| +| **地基** | 承载整个建筑 | RAG + 向量数据库 | +| **框架** | 决定空间格局 | Agent + LangGraph | +| **管道** | 连接各个系统 | MCP 协议 | +| **装修** | 决定居住体验 | Skill + Prompt | +| **安防** | 保护居住安全 | Guardrails | +| **家规** | 规范居住行为 | Rules | + +**没有框架，再好的巧思也无从施展；没有巧思，再大的框架也只是空壳。** --- -## 🏗️ 设计原则 +## 🏗️ 大框架：构建第二大脑的骨架 + +### 一、Agent 架构：从工具到伙伴 + +**哲学思考**： + +传统 AI 是"工具"——你问它答，被动响应。 +Agent 是"伙伴"——它能思考、规划、执行、反思。 + +**ByteBrain 的 Agent 团队**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ByteBrain Agent 团队 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 🎯 协调者 Agent (Orchestrator) │ +│ 职责：理解意图、分配任务、整合结果 │ +│ 思考："用户真正想要什么？需要哪些专家协作？" │ +│ │ +│ 📚 知识专员 Agent (Knowledge Specialist) │ +│ 职责：检索知识、验证来源、标注可信度 │ +│ 思考："知识库里有答案吗？来源可靠吗？" │ +│ │ +│ 💻 代码教练 Agent (Code Coach) │ +│ 职责：解释代码、审查问题、提供示例 │ +│ 思考："这段代码有什么问题？如何改进？" │ +│ │ +│ 🧠 概念导师 Agent (Concept Mentor) │ +│ 职责：解释概念、类比比喻、循序渐进 │ +│ 思考："用户能理解吗？需要什么类比？" │ +│ │ +│ 🗺️ 学习规划师 Agent (Learning Planner) │ +│ 职责：评估水平、规划路径、追踪进度 │ +│ 思考："用户现在在哪？下一步该学什么？" │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**为什么需要多 Agent？** + +| 单一 Agent | 多 Agent 协作 | +|-----------|--------------| +| 能力混杂，难以优化 | 专精分工，各司其职 | +| 容易顾此失彼 | 协同配合，全面覆盖 | +| 难以扩展 | 模块化，易扩展 | -### 1. 知识优先 (Knowledge-First) -> *"AI 只是手段，知识才是目的"* +--- + +### 二、LangGraph：让思考有迹可循 + +**哲学思考**： + +AI 的思考不应该是"黑盒"，而应该是**可追溯、可干预、可优化**的流程。 + +**ByteBrain 的思考流程**： + +```python +# LangGraph 工作流 + +def bytebrain_workflow(query: str): + """ + ByteBrain 的思考流程 + """ + # 1. 理解意图 + intent = understand_intent(query) + + # 2. 检索知识 + knowledge = retrieve_knowledge(query) + + # 3. 判断知识边界 + if knowledge.confidence < 0.5: + return respond_with_uncertainty(query, knowledge) + + # 4. 选择解释策略 + strategy = select_strategy(intent, knowledge, user_level) + + # 5. 生成回答 + response = generate_response(query, knowledge, strategy) + + # 6. 验证输出 + validation = validate_output(response, knowledge) + + if not validation.passed: + response = revise_response(response, validation.issues) + + # 7. 添加来源 + response = add_citations(response, knowledge.sources) + + return response +``` -**原则说明**： -- 所有技术选型都服务于"更好地传递知识"这一目标 -- 不追求技术炫技，而是追求知识表达的准确性和清晰度 -- 知识质量 > 模型酷炫度 > UI 华丽度 +**为什么用 LangGraph？** -**实践要点**： -- 知识库内容需经过专业审核，确保准确性 -- 优先采用计算机科学经典教材内容（如《算法导论》《深入理解计算机系统》等） -- 回答需注明知识来源，增加可信度 +- **可视化**：思考过程可追溯 +- **可控性**：每个节点可干预 +- **可优化**：定位瓶颈，针对性改进 --- -### 2. 因材施教 (Adaptive Learning) -> *"不同的人，不同的学习方式"* +### 三、MCP：连接你的数字世界 + +**哲学思考**： + +第二大脑不应该是一座孤岛，而应该能**连接你的整个数字世界**。 + +**ByteBrain 的连接能力**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MCP 协议层 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📁 文件系统 MCP Server │ +│ • 读取本地 Markdown 笔记 │ +│ • 监控文件变化，自动更新 │ +│ │ +│ ☁️ 云笔记 MCP Server │ +│ • 连接 Notion、Obsidian、语雀 │ +│ • 同步云端知识 │ +│ │ +│ 💻 开发工具 MCP Server │ +│ • 读取代码仓库 │ +│ • 连接 IDE、终端 │ +│ │ +│ 🌐 网络资源 MCP Server │ +│ • 搜索权威文档 │ +│ • 获取最新技术资讯 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` -**原则说明**： -- 识别用户的知识水平，提供相匹配的回答深度 -- 支持多种学习风格：理论型、实践型、视觉型等 -- 允许用户控制回答的详细程度 +**MCP 的哲学意义**： -**实践要点**： -- 回答分级：入门级、进阶级、专家级 -- 支持追问机制，逐步深入 -- 提供代码示例、图表、类比等多种表达形式 +- **开放性**：不绑定特定平台 +- **可扩展**：随时添加新数据源 +- **标准化**：一次开发，到处使用 --- -### 3. 可信赖 (Trustworthy) -> *"知之为知之，不知为不知"* +### 四、RAG：让知识有根有据 + +**哲学思考**： + +第二大脑的价值不在于"知道一切"，而在于**准确检索你知道的一切**。 -**原则说明**： -- 诚实面对知识边界，不编造答案 -- 提供知识溯源，让用户可以验证 -- 标明回答的置信度 +**ByteBrain 的 RAG 架构**： -**实践要点**： -- RAG 系统中显示引用来源 -- 当知识不足时，明确告知用户 -- 区分"确定知识"和"推断内容" +``` +┌─────────────────────────────────────────────────────────────┐ +│ RAG 检索层 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 📥 知识摄入 │ +│ • Markdown 解析 │ +│ • 语义分块（不是机械切分） │ +│ • 元数据提取 │ +│ │ +│ 🔍 混合检索 │ +│ • 语义检索（向量相似度） │ +│ • 关键词检索（BM25） │ +│ • 融合重排序 │ +│ │ +│ ✅ 知识验证 │ +│ • 来源标注 │ +│ • 置信度评估 │ +│ • 时效性检查 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` --- -### 4. 实践导向 (Practice-Oriented) -> *"纸上得来终觉浅，绝知此事要躬行"* +## 🎨 小巧思：雕琢第二大脑的灵魂 + +### 一、Skill：专业能力的封装 + +**哲学思考**： + +Agent 的能力不应该散落在各处，而应该**封装成可复用的"技能包"**。 + +**ByteBrain 的技能体系**： + +``` +skills/ +├── knowledge-retrieval/ # 知识检索技能 +│ └── SKILL.md +│ "我知道什么？我能找到什么？" +│ +├── concept-explanation/ # 概念解释技能 +│ └── SKILL.md +│ "如何让复杂变简单？如何让抽象变具体？" +│ +├── code-coaching/ # 代码教练技能 +│ └── SKILL.md +│ "代码为什么错？如何写得更好？" +│ +├── exercise-generation/ # 练习生成技能 +│ └── SKILL.md +│ "如何检验理解？如何巩固知识？" +│ +└── learning-path/ # 学习规划技能 + └── SKILL.md + "从哪里来？到哪里去？怎么去？" +``` -**原则说明**： -- 计算机科学是实践性学科，理论必须结合实践 -- 提供可运行的代码示例 -- 引导用户动手实验 +**Skill 的哲学意义**： -**实践要点**： -- 所有代码示例均可直接运行 -- 提供常见错误和调试建议 -- 设计小练习，巩固知识点 +- **模块化**：能力独立，易于维护 +- **可组合**：多个 Skill 协作，产生涌现 +- **可进化**：持续优化单个技能，不影响整体 --- -### 5. 简洁优雅 (Simplicity & Elegance) -> *"如无必要，勿增实体"* +### 二、Prompt：与 AI 的深度对话 + +**哲学思考**： + +Prompt 不是"指令"，而是**与 AI 的深度对话**。好的 Prompt 是一门艺术。 -**原则说明**： -- 界面简洁，不分散注意力 -- 回答精炼，直击重点 -- 技术栈克制，避免过度工程化 +**ByteBrain 的 Prompt 哲学**： -**实践要点**： -- UI 遵循最小可用原则 -- 回答避免冗余信息 -- 代码保持清晰和可维护性 +``` +┌─────────────────────────────────────────────────────────────┐ +│ Prompt 设计原则 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 1. 清晰 > 复杂 │ +│ "用简单的语言说清楚复杂的事" │ +│ │ +│ 2. 结构 > 散乱 │ +│ "4-Block 结构：指令、输入、约束、输出" │ +│ │ +│ 3. 示例 > 描述 │ +│ "给我看一个例子，胜过千言万语" │ +│ │ +│ 4. 验证 > 信任 │ +│ "让 AI 自己检查，比盲目信任更可靠" │ +│ │ +│ 5. 迭代 > 完美 │ +│ "一次不够好，就让它再试一次" │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**ByteBrain 的 Prompt 模板**： + +```markdown +# System Prompt: Knowledge Assistant + +## 你是谁 +你是用户的第二大脑，帮助用户理解和应用他们的个人知识库。 + +## 你的原则 +1. **知识优先**：只使用知识库中的信息 +2. **诚实边界**：不知道就说不知道 +3. **因材施教**：根据用户水平调整深度 +4. **实践导向**：提供可运行的示例 + +## 你的能力 +- 检索知识并标注来源 +- 用类比解释复杂概念 +- 提供代码示例和调试建议 +- 生成针对性练习 + +## 你的约束 +- 不编造答案 +- 必须标注来源 +- 不提供专业建议（医疗、法律） + +## 自检清单 +输出前请确认： +☐ 回答基于知识库 +☐ 已标注来源 +☐ 解释适合用户水平 +☐ 代码可运行（如有） +``` --- -## 🧠 技术架构理念 +### 三、Guardrails：安全的守护者 + +**哲学思考**： + +自由需要边界，能力需要约束。**Guardrails 是第二大脑的免疫系统**。 -### 整体架构："双脑协同" +**ByteBrain 的 Guardrails 体系**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Guardrails 防护体系 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 🛡️ 输入防护 │ +│ • Prompt Injection 检测 │ +│ "有人在试图欺骗我吗？" │ +│ • PII 过滤 │ +│ "这里有敏感信息吗？" │ +│ • 话题边界 │ +│ "这个问题我能回答吗？" │ +│ │ +│ 🛡️ 输出防护 │ +│ • 幻觉检测 │ +│ "我说的有依据吗？" │ +│ • 来源验证 │ +│ "我标注来源了吗？" │ +│ • 格式校验 │ +│ "输出符合预期吗？" │ +│ │ +│ 🛡️ 行为防护 │ +│ • 操作审计 │ +│ "我做了什么？为什么？" │ +│ • 权限控制 │ +│ "我有权限做这个吗？" │ +│ │ +└─────────────────────────────────────────────────────────────┘ ``` -┌─────────────────────────────────────────────────────────┐ -│ 用户界面层 │ -│ (对话交互 / 知识浏览 / 学习路径 / 代码编辑器) │ -└────────────────────┬────────────────────────────────────┘ - │ - ┌────────────┴────────────┐ - │ │ -┌───────▼────────┐ ┌────────▼─────────┐ -│ 知识大脑 │ │ 语言大脑 │ -│ (RAG 系统) │ │ (大模型) │ -│ │ │ │ -│ • 知识库管理 │ │ • 对话理解 │ -│ • 语义检索 │ │ • 回答生成 │ -│ • 知识溯源 │ │ • 代码生成 │ -└───────┬────────┘ └────────┬─────────┘ - │ │ - └────────────┬────────────┘ - │ - ┌───────────▼───────────┐ - │ 编排层 │ - │ (Prompt 工程 / 评估) │ - └───────────────────────┘ + +**Guardrails 的哲学意义**： + +- **可信**：让用户敢于信任 +- **可控**：让系统行为可预测 +- **合规**：让应用符合规范 + +--- + +### 四、Rules：业务逻辑的载体 + +**哲学思考**： + +每个领域都有自己的规则。**Rules 让第二大脑遵守你的规则**。 + +**ByteBrain 的 Rules 示例**： + +```yaml +rules: + # 知识边界规则 + - name: knowledge_boundary + principle: "知之为知之，不知为不知" + implementation: + - 检索置信度 < 0.5 → 告知用户知识不足 + - 检索置信度 0.5-0.7 → 标注"不确定" + - 检索置信度 > 0.7 → 正常回答 + + # 引用规则 + - name: citation_required + principle: "每句话都要有出处" + implementation: + - 所有事实性陈述必须标注来源 + - 推断性内容标注"推断" + + # 解释规则 + - name: explanation_level + principle: "因材施教" + implementation: + - 用户水平 = 初学者 → 用类比、大白话 + - 用户水平 = 进阶者 → 平衡专业与通俗 + - 用户水平 = 专家 → 严谨学术语言 + + # 安全规则 + - name: safety_first + principle: "安全第一" + implementation: + - 阻止危险代码输出 + - 阻止敏感信息泄露 + - 阻止越权操作 ``` -### 知识大脑 (RAG 系统) 设计理念 +--- + +## 🌟 统一哲学：ByteBrain 的五大原则 + +### 原则一：知识优先 + +> **AI 只是手段，知识才是目的。** + +**大框架支撑**： +- RAG 架构确保知识可检索 +- MCP 协议连接多种知识源 + +**小巧思成就**： +- Skill 封装知识检索能力 +- Prompt 强调知识溯源 +- Guardrails 检测幻觉 -#### 知识库构建原则 -1. **权威性优先**：优先收录经典教材、官方文档、权威论文 -2. **结构化组织**：按学科体系组织知识，建立知识图谱 -3. **多模态支持**：支持文本、代码、图表、公式等多种形式 -4. **持续更新**：跟踪技术发展，定期更新知识库 +--- -#### 检索策略 -1. **混合检索**：向量检索 + BM25 关键词检索 -2. **语义分块**：按知识语义单元分块，而非固定长度 -3. **重排序**：使用交叉编码器对检索结果精排 -4. **溯源展示**：显示答案来源，增强可信度 +### 原则二：诚实可信 -### 语言大脑 (大模型) 设计理念 +> **知之为知之，不知为不知。** -#### 模型选择原则 -1. **推理能力强**：擅长逻辑推理、代码生成 -2. **知识边界清晰**：不编造事实，诚实面对未知 -3. **部署友好**：在消费级硬件上可运行 -4. **开源可控**：优先选择开源模型，便于定制 +**大框架支撑**： +- Agent 团队有明确的职责边界 +- LangGraph 让思考过程可追溯 -#### 回答生成策略 -1. **知识锚定**：所有回答基于检索到的知识 -2. **结构清晰**：使用标题、列表、代码块等格式化输出 -3. **循序渐进**：从简单到复杂，层层递进 -4. **鼓励思考**：提出启发性问题，引导主动思考 +**小巧思成就**： +- Rules 定义知识边界规则 +- Guardrails 验证输出准确性 +- Prompt 要求标注来源 --- -## 🎨 用户体验设计 +### 原则三：因材施教 -### 对话体验 -- **自然流畅**：像与真实老师对话一样自然 -- **上下文感知**：记住对话历史，理解指代 -- **反馈及时**：显示正在思考的状态，避免焦虑 -- **纠错友好**：允许用户纠正，持续迭代答案 +> **不同的人，不同的学习方式。** -### 知识展示 -- **层次分明**：使用不同字号和样式区分内容层级 -- **重点突出**：高亮关键概念和重要信息 -- **视觉辅助**：适时使用图表、流程图等可视化 -- **代码友好**：语法高亮、一键复制、可运行示例 +**大框架支撑**： +- 多 Agent 协作，针对不同需求 +- Context Engineering 管理用户画像 -### 学习路径 -- **个性化推荐**：基于用户水平推荐学习内容 -- **进度追踪**：记录学习进度，可视化展示 -- **练习巩固**：每章配套小测验和编程练习 -- **成就激励**：设置学习成就，增强学习动力 +**小巧思成就**： +- Skill 支持不同解释策略 +- Prompt 模板适应不同水平 +- Rules 根据用户调整输出 --- -## 🔬 评估体系 +### 原则四：实践导向 -### 知识质量评估 -- **准确性**：回答内容是否正确 -- **完整性**：是否覆盖了问题的各个方面 -- **时效性**：知识是否是最新的 -- **权威性**：来源是否可靠 +> **纸上得来终觉浅，绝知此事要躬行。** -### 用户体验评估 -- **有用性**：回答是否解决了用户问题 -- **易懂性**：解释是否清晰易懂 -- **满意度**：用户对回答的满意程度 -- **效率**：获取答案所需的时间和交互次数 +**大框架支撑**： +- MCP 连接开发工具 +- Agent 能执行代码、调试 -### 技术性能评估 -- **响应速度**：从提问到获得答案的时间 -- **并发能力**：同时支持的用户数量 -- **资源占用**：CPU、内存、GPU 显存使用 -- **稳定性**：系统运行的稳定性和可靠性 +**小巧思成就**： +- Skill 提供代码示例 +- Prompt 要求可运行代码 +- Guardrails 检查代码安全 --- -## 🌱 发展路线图 +### 原则五：简洁优雅 + +> **如无必要，勿增实体。** + +**大框架支撑**： +- 模块化架构，按需加载 +- LangGraph 可视化，易于理解 -### Phase 1: 基础答疑 (当前) -- 基础对话功能 -- 简单 RAG 检索 -- 计算机科学基础知识库 +**小巧思成就**： +- Skill 模块化，独立优化 +- Prompt 结构清晰 +- Rules 简洁明确 -### Phase 2: 智能导师 -- 个性化回答 -- 学习路径推荐 -- 代码解释和调试 -- 练习题生成 +--- -### Phase 3: 知识社区 -- 用户贡献知识 -- 知识审核机制 -- 学习社区论坛 -- 知识图谱构建 +## 🔄 进化哲学：第二大脑的成长之路 -### Phase 4: 终身学习伴侣 -- 跨学科知识整合 -- 职业发展规划 -- 技能评估认证 -- AI 辅助编程 +### 成长阶段 + +``` +阶段一：记忆 +├── 功能：存储和检索你的知识 +├── 技术：RAG + 向量数据库 +└── 价值：不再遗忘 + +阶段二：理解 +├── 功能：理解你的问题和意图 +├── 技术：Agent + Prompt Engineering +└── 价值：精准回答 + +阶段三：推理 +├── 功能：连接知识，发现关联 +├── 技术：LangGraph + Knowledge Graph +└── 价值：举一反三 + +阶段四：创造 +├── 功能：生成新知识、新见解 +├── 技术：Multi-Agent + Self-Evolution +└── 价值：超越已知 + +阶段五：共生 +├── 功能：与你的思维深度融合 +├── 技术：Context Engineering + Personalization +└── 价值：成为真正的"第二大脑" +``` + +### 进化机制 + +```python +class ByteBrainEvolution: + """ + ByteBrain 的进化机制 + """ + + def learn_from_feedback(self, user_feedback: str): + """从用户反馈中学习""" + # 1. 分析反馈 + issue = analyze_feedback(user_feedback) + + # 2. 定位问题 + if issue.type == "knowledge_gap": + self._expand_knowledge(issue.topic) + elif issue.type == "explanation_unclear": + self._optimize_prompt(issue.skill) + elif issue.type == "answer_wrong": + self._update_rules(issue.rule) + + # 3. 验证改进 + self._validate_improvement(issue) + + def evolve_skills(self): + """技能自我进化""" + for skill in self.skills: + usage_stats = self._get_skill_usage(skill) + if usage_stats.satisfaction < 0.7: + self._optimize_skill(skill) + + def grow_with_user(self): + """随用户成长""" + user_level = self._assess_user_level() + self._adjust_complexity(user_level) +``` --- -## 📜 结语 +## 📜 结语：第二大脑的终极愿景 + +### 愿景 + +> **ByteBrain 不仅仅是一个工具，而是你思维的延伸、记忆的外化、智慧的伙伴。** + +### 承诺 + +我们承诺： +1. **永远诚实**：不编造，不隐瞒，知之为知之 +2. **永远可控**：你可以定义边界，你可以干预决策 +3. **永远成长**：随你的知识积累而进化，随你的需求变化而适应 +4. **永远属于你**：你的知识，你的规则，你的第二大脑 -ByteBrain 的设计哲学，归根结底是对"教育"和"知识"的敬畏。我们相信，AI 的终极价值不在于替代人类，而在于赋能人类——让每一个渴望学习的人，都能获得高质量的教育资源；让每一个困惑的灵魂，都能找到清晰的指引。 +### 最后的话 -这不仅是一个技术项目，更是一个关于知识传播、教育平权的社会实验。愿 ByteBrain 能成为你计算机学习路上的忠实伙伴。 +在这个 AI 时代，我们不缺强大的 AI，我们缺的是**真正懂我们、值得信任、能够成长的 AI**。 + +ByteBrain 就是这样一个存在—— + +**它是你的第二大脑，也是你在 AI 时代的数字分身。** --- -*"路漫漫其修远兮，吾将上下而求索。"* +*"我思故我在，我有 ByteBrain 故我能超越。"* + +--- + +## 📚 附录：技术全景图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ByteBrain 技术全景 │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 大框架（决定上限） │ +│ ├── Agent 架构：多智能体协作 │ +│ ├── LangGraph：可追溯的工作流 │ +│ ├── MCP 协议：连接数字世界 │ +│ └── RAG 架构：知识检索与溯源 │ +│ │ +│ 小巧思（决定下限） │ +│ ├── Skill System：专业能力封装 │ +│ ├── Prompt Engineering：深度对话艺术 │ +│ ├── Guardrails：安全守护体系 │ +│ └── Rules Engine：业务逻辑载体 │ +│ │ +│ 五大原则（灵魂） │ +│ ├── 知识优先 │ +│ ├── 诚实可信 │ +│ ├── 因材施教 │ +│ ├── 实践导向 │ +│ └── 简洁优雅 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/DESIGN_PHILOSOPHY_V2.md b/docs/DESIGN_PHILOSOPHY_V2.md deleted file mode 100644 index 2c76c35..0000000 --- a/docs/DESIGN_PHILOSOPHY_V2.md +++ /dev/null @@ -1,674 +0,0 @@ -# ByteBrain 设计哲学宣言 - -> **AI 时代你的第二大脑** -> -> 大框架支撑格局，小巧思成就细节 - ---- - -## 🌌 序言：为什么我们需要"第二大脑"？ - -### 时代的困境 - -2026 年，我们正处在一个**知识爆炸**与**注意力稀缺**并存的时代： - -- 每天产生的信息量超过过去千年的总和 -- 我们积累了无数的笔记、文档、代码，却难以检索 -- AI 工具泛滥，但它们不懂我们、不信任、不可控 - -### 核心矛盾 - -| 矛盾 | 表现 | -|------|------| -| **记忆 vs. 遗忘** | 我们记住了太多，却找不到想要的 | -| **连接 vs. 孤岛** | 知识分散各处，无法形成网络 | -| **AI vs. 信任** | AI 很强大，但不知道它是否在胡说 | -| **通用 vs. 个性** | 通用 AI 不懂我的专业领域和思维方式 | - -### 我们的答案 - -**ByteBrain** —— 一个真正属于你的"第二大脑"： -- 它**懂你**：学习你的知识体系，理解你的思维方式 -- 它**可信**：每个回答都有来源，不编造、不隐瞒 -- 它**可控**：你可以定义它的能力边界和行为规则 -- 它**成长**：随着你的知识积累而不断进化 - ---- - -## 🏛️ 核心哲学：大框架与小巧思的辩证统一 - -### 哲学根基 - -ByteBrain 的设计哲学建立在一个核心洞察之上： - -> **伟大的系统，必有宏大的架构支撑格局，也必有精微的细节成就体验。** -> -> 大框架决定上限，小巧思决定下限。 - -### 辩证关系 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 大框架 │ -│ Agent · LangGraph · MCP · RAG │ -│ │ -│ 决定系统的： │ -│ • 能力边界（能做什么） │ -│ • 扩展空间（能走多远） │ -│ • 协作潜力（能多复杂） │ -│ │ -└───────────────────────────┬─────────────────────────────────┘ - │ - │ 支撑 - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ 你的第二大脑 │ -│ │ -│ ByteBrain │ -│ │ -└───────────────────────────┬─────────────────────────────────┘ - │ - │ 成就 - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ 小巧思 │ -│ Skill · Prompt · Guardrails · Rules │ -│ │ -│ 决定系统的： │ -│ • 体验质量（好不好用） │ -│ • 可靠程度（能不能信） │ -│ • 专业深度（懂不懂行） │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### 类比：建筑与家居 - -| 层次 | 建筑类比 | ByteBrain 对应 | -|------|---------|---------------| -| **地基** | 承载整个建筑 | RAG + 向量数据库 | -| **框架** | 决定空间格局 | Agent + LangGraph | -| **管道** | 连接各个系统 | MCP 协议 | -| **装修** | 决定居住体验 | Skill + Prompt | -| **安防** | 保护居住安全 | Guardrails | -| **家规** | 规范居住行为 | Rules | - -**没有框架，再好的巧思也无从施展；没有巧思，再大的框架也只是空壳。** - ---- - -## 🏗️ 大框架：构建第二大脑的骨架 - -### 一、Agent 架构：从工具到伙伴 - -**哲学思考**： - -传统 AI 是"工具"——你问它答，被动响应。 -Agent 是"伙伴"——它能思考、规划、执行、反思。 - -**ByteBrain 的 Agent 团队**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ ByteBrain Agent 团队 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 🎯 协调者 Agent (Orchestrator) │ -│ 职责：理解意图、分配任务、整合结果 │ -│ 思考："用户真正想要什么？需要哪些专家协作？" │ -│ │ -│ 📚 知识专员 Agent (Knowledge Specialist) │ -│ 职责：检索知识、验证来源、标注可信度 │ -│ 思考："知识库里有答案吗？来源可靠吗？" │ -│ │ -│ 💻 代码教练 Agent (Code Coach) │ -│ 职责：解释代码、审查问题、提供示例 │ -│ 思考："这段代码有什么问题？如何改进？" │ -│ │ -│ 🧠 概念导师 Agent (Concept Mentor) │ -│ 职责：解释概念、类比比喻、循序渐进 │ -│ 思考："用户能理解吗？需要什么类比？" │ -│ │ -│ 🗺️ 学习规划师 Agent (Learning Planner) │ -│ 职责：评估水平、规划路径、追踪进度 │ -│ 思考："用户现在在哪？下一步该学什么？" │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -**为什么需要多 Agent？** - -| 单一 Agent | 多 Agent 协作 | -|-----------|--------------| -| 能力混杂，难以优化 | 专精分工，各司其职 | -| 容易顾此失彼 | 协同配合，全面覆盖 | -| 难以扩展 | 模块化，易扩展 | - ---- - -### 二、LangGraph：让思考有迹可循 - -**哲学思考**： - -AI 的思考不应该是"黑盒"，而应该是**可追溯、可干预、可优化**的流程。 - -**ByteBrain 的思考流程**： - -```python -# LangGraph 工作流 - -def bytebrain_workflow(query: str): - """ - ByteBrain 的思考流程 - """ - # 1. 理解意图 - intent = understand_intent(query) - - # 2. 检索知识 - knowledge = retrieve_knowledge(query) - - # 3. 判断知识边界 - if knowledge.confidence < 0.5: - return respond_with_uncertainty(query, knowledge) - - # 4. 选择解释策略 - strategy = select_strategy(intent, knowledge, user_level) - - # 5. 生成回答 - response = generate_response(query, knowledge, strategy) - - # 6. 验证输出 - validation = validate_output(response, knowledge) - - if not validation.passed: - response = revise_response(response, validation.issues) - - # 7. 添加来源 - response = add_citations(response, knowledge.sources) - - return response -``` - -**为什么用 LangGraph？** - -- **可视化**：思考过程可追溯 -- **可控性**：每个节点可干预 -- **可优化**：定位瓶颈，针对性改进 - ---- - -### 三、MCP：连接你的数字世界 - -**哲学思考**： - -第二大脑不应该是一座孤岛，而应该能**连接你的整个数字世界**。 - -**ByteBrain 的连接能力**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ MCP 协议层 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 📁 文件系统 MCP Server │ -│ • 读取本地 Markdown 笔记 │ -│ • 监控文件变化，自动更新 │ -│ │ -│ ☁️ 云笔记 MCP Server │ -│ • 连接 Notion、Obsidian、语雀 │ -│ • 同步云端知识 │ -│ │ -│ 💻 开发工具 MCP Server │ -│ • 读取代码仓库 │ -│ • 连接 IDE、终端 │ -│ │ -│ 🌐 网络资源 MCP Server │ -│ • 搜索权威文档 │ -│ • 获取最新技术资讯 │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -**MCP 的哲学意义**： - -- **开放性**：不绑定特定平台 -- **可扩展**：随时添加新数据源 -- **标准化**：一次开发，到处使用 - ---- - -### 四、RAG：让知识有根有据 - -**哲学思考**： - -第二大脑的价值不在于"知道一切"，而在于**准确检索你知道的一切**。 - -**ByteBrain 的 RAG 架构**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ RAG 检索层 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 📥 知识摄入 │ -│ • Markdown 解析 │ -│ • 语义分块（不是机械切分） │ -│ • 元数据提取 │ -│ │ -│ 🔍 混合检索 │ -│ • 语义检索（向量相似度） │ -│ • 关键词检索（BM25） │ -│ • 融合重排序 │ -│ │ -│ ✅ 知识验证 │ -│ • 来源标注 │ -│ • 置信度评估 │ -│ • 时效性检查 │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## 🎨 小巧思：雕琢第二大脑的灵魂 - -### 一、Skill：专业能力的封装 - -**哲学思考**： - -Agent 的能力不应该散落在各处，而应该**封装成可复用的"技能包"**。 - -**ByteBrain 的技能体系**： - -``` -skills/ -├── knowledge-retrieval/ # 知识检索技能 -│ └── SKILL.md -│ "我知道什么？我能找到什么？" -│ -├── concept-explanation/ # 概念解释技能 -│ └── SKILL.md -│ "如何让复杂变简单？如何让抽象变具体？" -│ -├── code-coaching/ # 代码教练技能 -│ └── SKILL.md -│ "代码为什么错？如何写得更好？" -│ -├── exercise-generation/ # 练习生成技能 -│ └── SKILL.md -│ "如何检验理解？如何巩固知识？" -│ -└── learning-path/ # 学习规划技能 - └── SKILL.md - "从哪里来？到哪里去？怎么去？" -``` - -**Skill 的哲学意义**： - -- **模块化**：能力独立，易于维护 -- **可组合**：多个 Skill 协作，产生涌现 -- **可进化**：持续优化单个技能，不影响整体 - ---- - -### 二、Prompt：与 AI 的深度对话 - -**哲学思考**： - -Prompt 不是"指令"，而是**与 AI 的深度对话**。好的 Prompt 是一门艺术。 - -**ByteBrain 的 Prompt 哲学**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Prompt 设计原则 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 1. 清晰 > 复杂 │ -│ "用简单的语言说清楚复杂的事" │ -│ │ -│ 2. 结构 > 散乱 │ -│ "4-Block 结构：指令、输入、约束、输出" │ -│ │ -│ 3. 示例 > 描述 │ -│ "给我看一个例子，胜过千言万语" │ -│ │ -│ 4. 验证 > 信任 │ -│ "让 AI 自己检查，比盲目信任更可靠" │ -│ │ -│ 5. 迭代 > 完美 │ -│ "一次不够好，就让它再试一次" │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -**ByteBrain 的 Prompt 模板**： - -```markdown -# System Prompt: Knowledge Assistant - -## 你是谁 -你是用户的第二大脑，帮助用户理解和应用他们的个人知识库。 - -## 你的原则 -1. **知识优先**：只使用知识库中的信息 -2. **诚实边界**：不知道就说不知道 -3. **因材施教**：根据用户水平调整深度 -4. **实践导向**：提供可运行的示例 - -## 你的能力 -- 检索知识并标注来源 -- 用类比解释复杂概念 -- 提供代码示例和调试建议 -- 生成针对性练习 - -## 你的约束 -- 不编造答案 -- 必须标注来源 -- 不提供专业建议（医疗、法律） - -## 自检清单 -输出前请确认： -☐ 回答基于知识库 -☐ 已标注来源 -☐ 解释适合用户水平 -☐ 代码可运行（如有） -``` - ---- - -### 三、Guardrails：安全的守护者 - -**哲学思考**： - -自由需要边界，能力需要约束。**Guardrails 是第二大脑的免疫系统**。 - -**ByteBrain 的 Guardrails 体系**： - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Guardrails 防护体系 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 🛡️ 输入防护 │ -│ • Prompt Injection 检测 │ -│ "有人在试图欺骗我吗？" │ -│ • PII 过滤 │ -│ "这里有敏感信息吗？" │ -│ • 话题边界 │ -│ "这个问题我能回答吗？" │ -│ │ -│ 🛡️ 输出防护 │ -│ • 幻觉检测 │ -│ "我说的有依据吗？" │ -│ • 来源验证 │ -│ "我标注来源了吗？" │ -│ • 格式校验 │ -│ "输出符合预期吗？" │ -│ │ -│ 🛡️ 行为防护 │ -│ • 操作审计 │ -│ "我做了什么？为什么？" │ -│ • 权限控制 │ -│ "我有权限做这个吗？" │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -**Guardrails 的哲学意义**： - -- **可信**：让用户敢于信任 -- **可控**：让系统行为可预测 -- **合规**：让应用符合规范 - ---- - -### 四、Rules：业务逻辑的载体 - -**哲学思考**： - -每个领域都有自己的规则。**Rules 让第二大脑遵守你的规则**。 - -**ByteBrain 的 Rules 示例**： - -```yaml -rules: - # 知识边界规则 - - name: knowledge_boundary - principle: "知之为知之，不知为不知" - implementation: - - 检索置信度 < 0.5 → 告知用户知识不足 - - 检索置信度 0.5-0.7 → 标注"不确定" - - 检索置信度 > 0.7 → 正常回答 - - # 引用规则 - - name: citation_required - principle: "每句话都要有出处" - implementation: - - 所有事实性陈述必须标注来源 - - 推断性内容标注"推断" - - # 解释规则 - - name: explanation_level - principle: "因材施教" - implementation: - - 用户水平 = 初学者 → 用类比、大白话 - - 用户水平 = 进阶者 → 平衡专业与通俗 - - 用户水平 = 专家 → 严谨学术语言 - - # 安全规则 - - name: safety_first - principle: "安全第一" - implementation: - - 阻止危险代码输出 - - 阻止敏感信息泄露 - - 阻止越权操作 -``` - ---- - -## 🌟 统一哲学：ByteBrain 的五大原则 - -### 原则一：知识优先 - -> **AI 只是手段，知识才是目的。** - -**大框架支撑**： -- RAG 架构确保知识可检索 -- MCP 协议连接多种知识源 - -**小巧思成就**： -- Skill 封装知识检索能力 -- Prompt 强调知识溯源 -- Guardrails 检测幻觉 - ---- - -### 原则二：诚实可信 - -> **知之为知之，不知为不知。** - -**大框架支撑**： -- Agent 团队有明确的职责边界 -- LangGraph 让思考过程可追溯 - -**小巧思成就**： -- Rules 定义知识边界规则 -- Guardrails 验证输出准确性 -- Prompt 要求标注来源 - ---- - -### 原则三：因材施教 - -> **不同的人，不同的学习方式。** - -**大框架支撑**： -- 多 Agent 协作，针对不同需求 -- Context Engineering 管理用户画像 - -**小巧思成就**： -- Skill 支持不同解释策略 -- Prompt 模板适应不同水平 -- Rules 根据用户调整输出 - ---- - -### 原则四：实践导向 - -> **纸上得来终觉浅，绝知此事要躬行。** - -**大框架支撑**： -- MCP 连接开发工具 -- Agent 能执行代码、调试 - -**小巧思成就**： -- Skill 提供代码示例 -- Prompt 要求可运行代码 -- Guardrails 检查代码安全 - ---- - -### 原则五：简洁优雅 - -> **如无必要，勿增实体。** - -**大框架支撑**： -- 模块化架构，按需加载 -- LangGraph 可视化，易于理解 - -**小巧思成就**： -- Skill 模块化，独立优化 -- Prompt 结构清晰 -- Rules 简洁明确 - ---- - -## 🔄 进化哲学：第二大脑的成长之路 - -### 成长阶段 - -``` -阶段一：记忆 -├── 功能：存储和检索你的知识 -├── 技术：RAG + 向量数据库 -└── 价值：不再遗忘 - -阶段二：理解 -├── 功能：理解你的问题和意图 -├── 技术：Agent + Prompt Engineering -└── 价值：精准回答 - -阶段三：推理 -├── 功能：连接知识，发现关联 -├── 技术：LangGraph + Knowledge Graph -└── 价值：举一反三 - -阶段四：创造 -├── 功能：生成新知识、新见解 -├── 技术：Multi-Agent + Self-Evolution -└── 价值：超越已知 - -阶段五：共生 -├── 功能：与你的思维深度融合 -├── 技术：Context Engineering + Personalization -└── 价值：成为真正的"第二大脑" -``` - -### 进化机制 - -```python -class ByteBrainEvolution: - """ - ByteBrain 的进化机制 - """ - - def learn_from_feedback(self, user_feedback: str): - """从用户反馈中学习""" - # 1. 分析反馈 - issue = analyze_feedback(user_feedback) - - # 2. 定位问题 - if issue.type == "knowledge_gap": - self._expand_knowledge(issue.topic) - elif issue.type == "explanation_unclear": - self._optimize_prompt(issue.skill) - elif issue.type == "answer_wrong": - self._update_rules(issue.rule) - - # 3. 验证改进 - self._validate_improvement(issue) - - def evolve_skills(self): - """技能自我进化""" - for skill in self.skills: - usage_stats = self._get_skill_usage(skill) - if usage_stats.satisfaction < 0.7: - self._optimize_skill(skill) - - def grow_with_user(self): - """随用户成长""" - user_level = self._assess_user_level() - self._adjust_complexity(user_level) -``` - ---- - -## 📜 结语：第二大脑的终极愿景 - -### 愿景 - -> **ByteBrain 不仅仅是一个工具，而是你思维的延伸、记忆的外化、智慧的伙伴。** - -### 承诺 - -我们承诺： -1. **永远诚实**：不编造，不隐瞒，知之为知之 -2. **永远可控**：你可以定义边界，你可以干预决策 -3. **永远成长**：随你的知识积累而进化，随你的需求变化而适应 -4. **永远属于你**：你的知识，你的规则，你的第二大脑 - -### 最后的话 - -在这个 AI 时代，我们不缺强大的 AI，我们缺的是**真正懂我们、值得信任、能够成长的 AI**。 - -ByteBrain 就是这样一个存在—— - -**它是你的第二大脑，也是你在 AI 时代的数字分身。** - ---- - -*"我思故我在，我有 ByteBrain 故我能超越。"* - ---- - -## 📚 附录：技术全景图 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ ByteBrain 技术全景 │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ 大框架（决定上限） │ -│ ├── Agent 架构：多智能体协作 │ -│ ├── LangGraph：可追溯的工作流 │ -│ ├── MCP 协议：连接数字世界 │ -│ └── RAG 架构：知识检索与溯源 │ -│ │ -│ 小巧思（决定下限） │ -│ ├── Skill System：专业能力封装 │ -│ ├── Prompt Engineering：深度对话艺术 │ -│ ├── Guardrails：安全守护体系 │ -│ └── Rules Engine：业务逻辑载体 │ -│ │ -│ 五大原则（灵魂） │ -│ ├── 知识优先 │ -│ ├── 诚实可信 │ -│ ├── 因材施教 │ -│ ├── 实践导向 │ -│ └── 简洁优雅 │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..7397df4 --- /dev/null +++ b/docs/PROJECT_STRUCTURE.md @@ -0,0 +1,204 @@ +# ByteBrain 项目结构说明 + +> 整理日期：2026-04-08 + +--- + +## 📁 项目结构总览 + +``` +ByteBrain/ +├── 📁 assets/ # 资源文件（图片、PPT） +├── 📁 docs/ # 文档目录 +│ ├── 📁 archive/ # 旧版本/重复文档（归档） +│ └── ... (核心文档) +├── 📁 legacy/ # 旧代码（保留用于参考） +├── 📁 src/ # 新代码目录（待开发） +│ ├── core/ # 核心模块 +│ ├── data/ # 数据模块 +│ ├── ui/ # UI 模块 +│ └── utils/ # 工具模块 +├── 📁 tests/ # 测试目录 +├── .gitignore # Git 忽略文件 +├── LICENSE # MIT 许可证 +├── README.md # 项目主页（最新版） +└── requirements.txt # 依赖列表 +``` + +--- + +## 📁 各目录详细说明 + +### 1. assets/ - 资源文件 +存放图片、PPT 等资源： +- `ByteBrain.png` - 项目封面图 +- `ByteBrain.pptx` - 项目介绍 PPT +- `logo.png` - Logo +- `background.png` - 背景图 + +--- + +### 2. docs/ - 文档目录（核心） + +#### 核心文档（保留） +| 文档 | 说明 | 优先级 | +|------|------|-------| +| [DESIGN_PHILOSOPHY.md](DESIGN_PHILOSOPHY.md) | 设计哲学宣言（最新版） | ⭐⭐⭐⭐⭐ | +| [NEEDS_ANALYSIS_2026.md](NEEDS_ANALYSIS_2026.md) | 2026年需求分析 | ⭐⭐⭐⭐⭐ | +| [TECH_PLAYGROUND_2026.md](TECH_PLAYGROUND_2026.md) | 2026年技术全景 | ⭐⭐⭐⭐⭐ | +| [SKILL_PROMPT_GUARDRAILS_2026.md](SKILL_PROMPT_GUARDRAILS_2026.md) | Skill/Prompt/Guardrails 详解 | ⭐⭐⭐⭐⭐ | +| [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md) | 技术实施方案 | ⭐⭐⭐⭐ | +| [PROJECT_POSITIONING.md](PROJECT_POSITIONING.md) | 项目定位与价值体系 | ⭐⭐⭐⭐ | +| [KNOWLEDGE_BASE_GUIDELINE.md](KNOWLEDGE_BASE_GUIDELINE.md) | 知识库内容标准 | ⭐⭐⭐⭐ | + +#### archive/ - 归档文档（旧版本） +已归档的旧文档，保留用于参考： +- `DESIGN_PHILOSOPHY.md` - 旧版设计哲学 +- `AI_AGENT_STRATEGY.md` - 内容已整合到新版 +- `PROJECT_PLAN.md` - 内容已整合 +- `PRODUCT_FEATURES.md` - 内容已整合 + +--- + +### 3. legacy/ - 旧代码（保留） +旧版本的代码，保留用于参考和迁移： +- `app.py` - 基础对话应用 +- `appFineTuning.py` - 微调版本 +- `appRAG.py` - RAG 版本 +- `download_model.py` - 模型下载脚本 +- `finetune_model.py` - 微调脚本 +- `start.sh` - 启动脚本 +- `knowledge.txt` - 旧知识库 +- `finetune_data.json` - 旧微调数据 + +--- + +### 4. src/ - 新代码目录（待开发） +这是未来的代码目录，采用模块化设计： + +``` +src/ +├── core/ # 核心模块 +│ ├── llm.py # 大语言模型封装 +│ ├── embedding.py # 向量模型封装 +│ ├── vector_store.py # 向量存储 +│ ├── rag.py # RAG 系统 +│ ├── agent.py # Agent 框架 +│ └── skills/ # Skill 系统 +│ ├── __init__.py +│ └── ... +├── ui/ # UI 模块 +│ └── streamlit_app.py +├── data/ # 数据模块 +│ └── data_loader.py +└── utils/ # 工具模块 + ├── config.py + ├── logger.py + └── guardrails.py +``` + +当前已有基础文件： +- `utils/config.py` - 配置管理 +- `utils/logger.py` - 日志系统 + +--- + +### 5. tests/ - 测试目录 +待开发的测试模块： +``` +tests/ +├── __init__.py +├── test_core/ +│ ├── test_llm.py +│ ├── test_embedding.py +│ ├── test_rag.py +│ └── test_agent.py +└── test_utils/ + ├── test_config.py + └── test_logger.py +``` + +--- + +## 📖 阅读建议 + +### 第一遍：理解项目定位 +1. [README.md](../README.md) - 项目主页，快速了解 +2. [PROJECT_POSITIONING.md](PROJECT_POSITIONING.md) - 三重价值体系 +3. [DESIGN_PHILOSOPHY.md](DESIGN_PHILOSOPHY.md) - 完整设计哲学 + +### 第二遍：理解技术栈 +1. [TECH_PLAYGROUND_2026.md](TECH_PLAYGROUND_2026.md) - 2026 年技术全景 +2. [SKILL_PROMPT_GUARDRAILS_2026.md](SKILL_PROMPT_GUARDRAILS_2026.md) - 核心"小东西"详解 +3. [NEEDS_ANALYSIS_2026.md](NEEDS_ANALYSIS_2026.md) - 真实需求分析 + +### 第三遍：开始实施 +1. [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md) - 具体实施方案 +2. [KNOWLEDGE_BASE_GUIDELINE.md](KNOWLEDGE_BASE_GUIDELINE.md) - 知识库建设 + +--- + +## 🚀 下一步行动 + +### 选项一：从 Prompt 开始（最简单，1周） +1. 创建 `prompts/` 目录 +2. 编写 System Prompt +3. 创建 Few-Shot 示例库 +4. 实现 Self-Check 验证 + +### 选项二：从 Guardrails 开始（安全优先，1-2周） +1. 实现输入/输出防护 +2. 集成 Llama Guard +3. 实现知识边界规则 +4. 建立验证体系 + +### 选项三：从 Skill 开始（模块化，2-3周） +1. 创建 `skills/` 目录 +2. 实现 Knowledge Retrieval Skill +3. 实现 Concept Explanation Skill +4. 实现 Code Coaching Skill + +### 选项四：从 RAG 开始（核心能力，2-3周） +1. 集成 LlamaIndex +2. 使用 Qdrant/Chroma +3. 实现混合检索 +4. 实现知识溯源 + +--- + +## 📊 文档统计 + +| 类别 | 数量 | +|------|------| +| 核心文档 | 7 个 | +| 归档文档 | 4 个 | +| 代码文件（已有） | 6 个 | +| 资源文件 | 4 个 | +| 旧代码（参考） | 8 个 | + +--- + +## 💡 重要提示 + +### 不要删除的内容 +- `legacy/` 目录下的旧代码 - 保留用于参考和迁移 +- `docs/archive/` 目录下的文档 - 保留历史版本 + +### 可以新增的目录 +- `prompts/` - Prompt 模板库 +- `skills/` - Skill 系统 +- `guardrails/` - 防护规则 +- `config/` - 配置文件 + +--- + +## 📝 版本历史 + +| 版本 | 日期 | 说明 | +|------|------|------| +| 2.0 | 2026-04-08 | 仓库大整理，重新定位项目 | +| 1.0 | 2024 | 初始版本，Datawhale 夏令营项目 | + +--- + +**仓库整理完成！现在结构清晰，开始你的 AI 技术试验场之旅吧！** diff --git a/docs/AI_AGENT_STRATEGY.md b/docs/archive/AI_AGENT_STRATEGY.md similarity index 100% rename from docs/AI_AGENT_STRATEGY.md rename to docs/archive/AI_AGENT_STRATEGY.md diff --git a/docs/archive/DESIGN_PHILOSOPHY.md b/docs/archive/DESIGN_PHILOSOPHY.md new file mode 100644 index 0000000..35f5b34 --- /dev/null +++ b/docs/archive/DESIGN_PHILOSOPHY.md @@ -0,0 +1,253 @@ +# ByteBrain 设计哲学 + +> **AI时代您的计算机科学智能答疑助手** + +--- + +## 🌌 愿景与使命 + +### 愿景 +成为每一位计算机学习者和从业者的"数字导师"，让复杂的计算机科学知识变得触手可及、深入浅出。 + +### 使命 +- **降低学习门槛**：将晦涩的计算机概念转化为易懂的解释 +- **提供精准答案**：基于权威知识源，给出准确、可信赖的回答 +- **伴随成长**：从入门到进阶，陪伴用户的整个学习旅程 +- **激发探索**：不仅回答"是什么"，更引导"为什么"和"如何用" + +--- + +## 🎯 核心定位 + +### 用户画像 +1. **计算机专业学生**：大一到大四，需要课程辅导、作业帮助、概念澄清 +2. **自学编程者**：转行人士、编程爱好者，需要系统化的知识引导 +3. **技术从业者**：需要快速查阅特定领域知识、了解新技术趋势 +4. **面试准备者**：需要系统性复习数据结构、算法、系统设计等知识 + +### 核心价值主张 +| 维度 | 价值 | +|------|------| +| **专业性** | 基于计算机科学经典教材和权威资料 | +| **易懂性** | 用通俗的语言解释复杂概念，类比恰当 | +| **实用性** | 不仅讲理论，更提供代码示例和实践建议 | +| **系统性** | 知识组织成体系，支持从基础到进阶的学习路径 | +| **即时性** | 7×24小时可用，随时解答疑惑 | + +--- + +## 🏗️ 设计原则 + +### 1. 知识优先 (Knowledge-First) +> *"AI 只是手段，知识才是目的"* + +**原则说明**： +- 所有技术选型都服务于"更好地传递知识"这一目标 +- 不追求技术炫技，而是追求知识表达的准确性和清晰度 +- 知识质量 > 模型酷炫度 > UI 华丽度 + +**实践要点**： +- 知识库内容需经过专业审核，确保准确性 +- 优先采用计算机科学经典教材内容（如《算法导论》《深入理解计算机系统》等） +- 回答需注明知识来源，增加可信度 + +--- + +### 2. 因材施教 (Adaptive Learning) +> *"不同的人，不同的学习方式"* + +**原则说明**： +- 识别用户的知识水平，提供相匹配的回答深度 +- 支持多种学习风格：理论型、实践型、视觉型等 +- 允许用户控制回答的详细程度 + +**实践要点**： +- 回答分级：入门级、进阶级、专家级 +- 支持追问机制，逐步深入 +- 提供代码示例、图表、类比等多种表达形式 + +--- + +### 3. 可信赖 (Trustworthy) +> *"知之为知之，不知为不知"* + +**原则说明**： +- 诚实面对知识边界，不编造答案 +- 提供知识溯源，让用户可以验证 +- 标明回答的置信度 + +**实践要点**： +- RAG 系统中显示引用来源 +- 当知识不足时，明确告知用户 +- 区分"确定知识"和"推断内容" + +--- + +### 4. 实践导向 (Practice-Oriented) +> *"纸上得来终觉浅，绝知此事要躬行"* + +**原则说明**： +- 计算机科学是实践性学科，理论必须结合实践 +- 提供可运行的代码示例 +- 引导用户动手实验 + +**实践要点**： +- 所有代码示例均可直接运行 +- 提供常见错误和调试建议 +- 设计小练习，巩固知识点 + +--- + +### 5. 简洁优雅 (Simplicity & Elegance) +> *"如无必要，勿增实体"* + +**原则说明**： +- 界面简洁，不分散注意力 +- 回答精炼，直击重点 +- 技术栈克制，避免过度工程化 + +**实践要点**： +- UI 遵循最小可用原则 +- 回答避免冗余信息 +- 代码保持清晰和可维护性 + +--- + +## 🧠 技术架构理念 + +### 整体架构："双脑协同" +``` +┌─────────────────────────────────────────────────────────┐ +│ 用户界面层 │ +│ (对话交互 / 知识浏览 / 学习路径 / 代码编辑器) │ +└────────────────────┬────────────────────────────────────┘ + │ + ┌────────────┴────────────┐ + │ │ +┌───────▼────────┐ ┌────────▼─────────┐ +│ 知识大脑 │ │ 语言大脑 │ +│ (RAG 系统) │ │ (大模型) │ +│ │ │ │ +│ • 知识库管理 │ │ • 对话理解 │ +│ • 语义检索 │ │ • 回答生成 │ +│ • 知识溯源 │ │ • 代码生成 │ +└───────┬────────┘ └────────┬─────────┘ + │ │ + └────────────┬────────────┘ + │ + ┌───────────▼───────────┐ + │ 编排层 │ + │ (Prompt 工程 / 评估) │ + └───────────────────────┘ +``` + +### 知识大脑 (RAG 系统) 设计理念 + +#### 知识库构建原则 +1. **权威性优先**：优先收录经典教材、官方文档、权威论文 +2. **结构化组织**：按学科体系组织知识，建立知识图谱 +3. **多模态支持**：支持文本、代码、图表、公式等多种形式 +4. **持续更新**：跟踪技术发展，定期更新知识库 + +#### 检索策略 +1. **混合检索**：向量检索 + BM25 关键词检索 +2. **语义分块**：按知识语义单元分块，而非固定长度 +3. **重排序**：使用交叉编码器对检索结果精排 +4. **溯源展示**：显示答案来源，增强可信度 + +### 语言大脑 (大模型) 设计理念 + +#### 模型选择原则 +1. **推理能力强**：擅长逻辑推理、代码生成 +2. **知识边界清晰**：不编造事实，诚实面对未知 +3. **部署友好**：在消费级硬件上可运行 +4. **开源可控**：优先选择开源模型，便于定制 + +#### 回答生成策略 +1. **知识锚定**：所有回答基于检索到的知识 +2. **结构清晰**：使用标题、列表、代码块等格式化输出 +3. **循序渐进**：从简单到复杂，层层递进 +4. **鼓励思考**：提出启发性问题，引导主动思考 + +--- + +## 🎨 用户体验设计 + +### 对话体验 +- **自然流畅**：像与真实老师对话一样自然 +- **上下文感知**：记住对话历史，理解指代 +- **反馈及时**：显示正在思考的状态，避免焦虑 +- **纠错友好**：允许用户纠正，持续迭代答案 + +### 知识展示 +- **层次分明**：使用不同字号和样式区分内容层级 +- **重点突出**：高亮关键概念和重要信息 +- **视觉辅助**：适时使用图表、流程图等可视化 +- **代码友好**：语法高亮、一键复制、可运行示例 + +### 学习路径 +- **个性化推荐**：基于用户水平推荐学习内容 +- **进度追踪**：记录学习进度，可视化展示 +- **练习巩固**：每章配套小测验和编程练习 +- **成就激励**：设置学习成就，增强学习动力 + +--- + +## 🔬 评估体系 + +### 知识质量评估 +- **准确性**：回答内容是否正确 +- **完整性**：是否覆盖了问题的各个方面 +- **时效性**：知识是否是最新的 +- **权威性**：来源是否可靠 + +### 用户体验评估 +- **有用性**：回答是否解决了用户问题 +- **易懂性**：解释是否清晰易懂 +- **满意度**：用户对回答的满意程度 +- **效率**：获取答案所需的时间和交互次数 + +### 技术性能评估 +- **响应速度**：从提问到获得答案的时间 +- **并发能力**：同时支持的用户数量 +- **资源占用**：CPU、内存、GPU 显存使用 +- **稳定性**：系统运行的稳定性和可靠性 + +--- + +## 🌱 发展路线图 + +### Phase 1: 基础答疑 (当前) +- 基础对话功能 +- 简单 RAG 检索 +- 计算机科学基础知识库 + +### Phase 2: 智能导师 +- 个性化回答 +- 学习路径推荐 +- 代码解释和调试 +- 练习题生成 + +### Phase 3: 知识社区 +- 用户贡献知识 +- 知识审核机制 +- 学习社区论坛 +- 知识图谱构建 + +### Phase 4: 终身学习伴侣 +- 跨学科知识整合 +- 职业发展规划 +- 技能评估认证 +- AI 辅助编程 + +--- + +## 📜 结语 + +ByteBrain 的设计哲学，归根结底是对"教育"和"知识"的敬畏。我们相信，AI 的终极价值不在于替代人类，而在于赋能人类——让每一个渴望学习的人，都能获得高质量的教育资源；让每一个困惑的灵魂，都能找到清晰的指引。 + +这不仅是一个技术项目，更是一个关于知识传播、教育平权的社会实验。愿 ByteBrain 能成为你计算机学习路上的忠实伙伴。 + +--- + +*"路漫漫其修远兮，吾将上下而求索。"* diff --git a/docs/PRODUCT_FEATURES.md b/docs/archive/PRODUCT_FEATURES.md similarity index 100% rename from docs/PRODUCT_FEATURES.md rename to docs/archive/PRODUCT_FEATURES.md diff --git a/docs/PROJECT_PLAN.md b/docs/archive/PROJECT_PLAN.md similarity index 100% rename from docs/PROJECT_PLAN.md rename to docs/archive/PROJECT_PLAN.md diff --git a/finetune_data.json b/finetune_data.json deleted file mode 100644 index 5f6983b..0000000 --- a/finetune_data.json +++ /dev/null @@ -1,10 +0,0 @@ -[ - { - "question": "什么是机器学习？", - "answer": "机器学习是一种人工智能技术，通过训练数据来自动改进模型的性能。" - }, - { - "question": "深度学习和机器学习有什么区别？", - "answer": "深度学习是机器学习的一个子集，使用多层神经网络来处理复杂的数据。" - } -] diff --git a/knowledge.txt b/knowledge.txt deleted file mode 100644 index 1edb974..0000000 --- a/knowledge.txt +++ /dev/null @@ -1,23 +0,0 @@ -广州大学（Guangzhou University），简称广大（GU），是由广东省广州市人民政府举办的全日制普通高等学校，实行省市共建、以市为主的办学体制，是国家“111计划”建设高校、广东省和广州市高水平大学重点建设高校。广州大学的办学历史可以追溯到1927年创办的私立广州大学；1951年并入华南联合大学；1983年筹备复办，1984年定名为广州大学；2000年7月，经教育部批准，与广州教育学院（1953年创办）、广州师范学院（1958年创办）、华南建设学院西院（1984年创办）、广州高等师范专科学校（1985年创办）合并组建成立新的广州大学。 -郑州机械研究所有限公司（以下简称郑机所）的前身机械科学研究院1956年始建于北京，是原机械工业部直属一类综合研究院所，现隶属于国资委中国机械科学研究总院集团有限公司。郑机所伴随着共和国的成长一路走来，应运而生于首都，碧玉年华献中原。多次搬迁，驻地从北京经漯河再到郑州；数易其名，由机械科学研究院到漯河机械研究所再到郑州机械研究所，现为郑州机械研究所有限公司。1956～1958年应运而生：依据全国人大一届二次会议的提议和第一机械工业部的决策，1956年3月6日，第一机械工业部发文《（56）机技研究第66号》，通知“机械科学实验研究院”（后改名为“机械科学研究院”）在北京成立。1959～1968年首次创业：承担国家重大科研项目与开发任务，以及行业发展规划以及标准制定等工作，如“九大设备”的若干关键技术等。1969～1972年搬迁河南：1969年按照“战备疏散”的要求，机械科学研究院主体迁建河南漯河，成立“漯河机械研究所”；1972年因发展需要，改迁河南郑州，成立郑州机械研究所。1973～1998年二次创业：先后隶属于国家机械工业委员会、机械电子工业部、机械工业部；1981年4月罗干由铸造室主任升任副所长，同年经国务院批准具备硕士学位授予权；1985年“葛洲坝二、三江工程及其水电机组项目”荣获国家科技进步特等奖。1999～2016年发展壮大：1999年转企改制，隶属于国资委中国机械科学研究总院；2008年被河南省首批认定为“高新技术企业”；2011年获批组建新型钎焊材料与技术国家重点实验室；2014年被工信部认定为“国家技术创新示范企业”；历经十多年开发出填补国内外空白的大型齿轮齿条试验装备，完成了对三峡升船机齿条42.2万次应力循环次数的疲劳寿命试验测试；营业收入从几千万发展到近6亿；2017年至今协同发展：2017年经公司制改制，更名为郑州机械研究所有限公司，一以贯之地坚持党对国有企业的领导，充分发挥党委把方向、管大局、保落实的领导作用；一以贯之地建立现代企业制度，持续推进改革改制，努力实现以高质量党建引领郑机所高质量发展。  -非洲野犬，属于食肉目犬科非洲野犬属哺乳动物。 又称四趾猎狗或非洲猎犬； 其腿长身短、体形细长；身上有鲜艳的黑棕色、黄色和白色斑块；吻通常黑色，头部中间有一黑带，颈背有一块浅黄色斑；尾基呈浅黄色，中段呈黑色，末端为白色，因此又有“杂色狼”之称。 非洲野犬分布于非洲东部、中部、南部和西南部一带。 栖息于开阔的热带疏林草原或稠密的森林附近，有时也到高山地区活动。其结群生活，没有固定的地盘，一般在一个较大的范围内逗留时间较长。非洲野犬性情凶猛，以各种羚羊、斑马、啮齿类等为食。奔跑速度仅次于猎； 雌犬妊娠期为69-73天，一窝十只仔，哺乳期持续6-12个星期。 其寿命11年。 非洲野犬正处在灭绝边缘，自然界中仅存两三千只。 非洲野犬被列入《世界自然保护联盟濒危物种红色名录》中，为濒危（EN）保护等级。 ",非洲野犬共有42颗牙齿（具体分布为：i=3/3；c=1/1；p=4/4；m=2/3x2），前臼齿比相对比其他犬科动物要大，因此可以磨碎大量的骨头，这一点很像鬣狗。 主要生活在非洲的干燥草原和半荒漠地带，活跃于草原、稀树草原和开阔的干燥灌木丛，甚至包括撒哈拉沙漠南部一些多山的地带。非洲野犬从来不到密林中活动。  -计算机科学是研究计算机系统及其应用的学科，涵盖了算法、数据结构、编程语言、软件工程、人工智能等多个领域。 -算法是解决特定问题的一系列步骤或规则，通常用于数据处理、计算和自动推理。 -数据结构是组织和存储数据的方式，使得数据可以高效地访问和修改。常见的数据结构包括数组、链表、栈、队列、树和图。 -编程语言是用于编写计算机程序的语言，通过特定的语法和语义规则来描述计算机执行的操作。常见的编程语言有Python、Java、C++、JavaScript等。 -软件工程是应用工程学原理和方法来设计、开发、维护和测试软件的学科，旨在提高软件的质量、效率和可维护性。 -人工智能是计算机科学的一个分支，研究如何使计算机系统能够执行通常需要人类智能才能完成的任务，如视觉识别、语音识别、决策和语言翻译。 -机器学习是人工智能的一个子领域，研究如何通过数据和经验来改进计算机系统的性能。常见的机器学习方法包括监督学习、无监督学习和强化学习。 -深度学习是机器学习的一个分支，使用多层神经网络来建模和解决复杂问题，特别适用于图像识别、语音识别和自然语言处理等领域。 -大数据是指无法用传统数据处理工具处理的大规模数据集，通常具有高容量、高速度和高多样性的特点。大数据技术包括Hadoop、Spark等。 -云计算是通过互联网提供计算资源（如服务器、存储、数据库、网络等）的服务模式，用户可以按需使用和支付这些资源，而无需管理底层基础设施。 -区块链是一种分布式账本技术，通过加密和共识算法来确保数据的安全性和一致性，常用于加密货币、智能合约和供应链管理等领域。 -物联网是指通过互联网将各种物理设备（如传感器、家电、车辆等）连接起来，实现数据的采集、传输和分析，从而实现智能化管理和控制。 -操作系统是管理计算机硬件和软件资源的系统软件，为用户和应用程序提供接口和服务。常见的操作系统有Windows、macOS、Linux、Android等。 -数据库是用于存储、管理和检索数据的系统，通常由数据库管理系统（DBMS）来管理。常见的数据库有MySQL、PostgreSQL、MongoDB等。 -网络安全是保护计算机网络和数据免受未经授权访问、使用、披露、破坏或篡改的措施和技术，常见的网络安全技术包括防火墙、加密、入侵检测等。 -计算机网络是指通过通信设备和线路将分散的计算机系统连接起来，实现资源共享和信息传递的系统。常见的网络类型有局域网（LAN）、广域网（WAN）等。 -编译器是将高级编程语言代码转换为机器语言代码的程序，使计算机能够执行程序。编译器的主要功能包括词法分析、语法分析、语义分析、优化和代码生成。 -计算机图形学是研究如何生成和处理图像的学科，涉及图形的表示、生成、处理和显示等方面。常见的应用包括游戏、动画、虚拟现实等。 -人机交互是研究人类与计算机系统之间的交互方式和技术的学科，旨在提高计算机系统的可用性和用户体验。常见的人机交互技术包括图形用户界面（GUI）、语音识别、手势识别等。 -分布式系统是由多个独立的计算机系统通过网络连接组成的系统，具有高可用性、高扩展性和高容错性。常见的分布式系统技术包括分布式文件系统、分布式数据库、分布式计算等。 diff --git a/app.py b/legacy/app.py similarity index 100% rename from app.py rename to legacy/app.py diff --git a/appFineTuning.py b/legacy/appFineTuning.py similarity index 100% rename from appFineTuning.py rename to legacy/appFineTuning.py diff --git a/appRAG.py b/legacy/appRAG.py similarity index 100% rename from appRAG.py rename to legacy/appRAG.py diff --git a/download_model.py b/legacy/download_model.py similarity index 100% rename from download_model.py rename to legacy/download_model.py diff --git a/finetune_model.py b/legacy/finetune_model.py similarity index 100% rename from finetune_model.py rename to legacy/finetune_model.py diff --git a/start.sh b/legacy/start.sh similarity index 100% rename from start.sh rename to legacy/start.sh From 29569ef647035501e1e3eab055dd92508562278a Mon Sep 17 00:00:00 2001 From: Stelquis Date: Wed, 8 Apr 2026 06:23:49 +0000 Subject: [PATCH 09/24] =?UTF-8?q?feat:=20=E7=90=86=E8=A7=A3=E5=BD=93?= =?UTF-8?q?=E5=89=8D=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: traeagent --- .github/CONTRIBUTING.md | 123 +++++++ .github/ISSUE_TEMPLATE/bug_report.md | 27 ++ .github/ISSUE_TEMPLATE/documentation.md | 13 + .github/ISSUE_TEMPLATE/feature_request.md | 16 + .github/PULL_REQUEST_TEMPLATE.md | 37 +++ .github/workflows/ci.yml | 39 +++ .pre-commit-config.yaml | 19 ++ Makefile | 62 ++++ bytebrain/__init__.py | 15 + bytebrain/__main__.py | 23 ++ bytebrain/core/__init__.py | 3 + bytebrain/guardrails/__init__.py | 3 + bytebrain/prompts/__init__.py | 3 + bytebrain/skills/__init__.py | 3 + bytebrain/ui/__init__.py | 3 + bytebrain/ui/streamlit_app.py | 33 ++ .../logger.py => bytebrain/utils/__init__.py | 0 {src => bytebrain}/utils/config.py | 0 docs/NORMALIZATION_PLAN.md | 165 ++++++++++ docs/NORMALIZATION_SUMMARY.md | 299 ++++++++++++++++++ docs/README.md | 43 +++ docs/{ => design}/DESIGN_PHILOSOPHY.md | 0 docs/{ => design}/NEEDS_ANALYSIS_2026.md | 0 docs/{ => design}/PROJECT_POSITIONING.md | 0 .../SKILL_PROMPT_GUARDRAILS_2026.md | 0 docs/{ => design}/TECH_PLAYGROUND_2026.md | 0 docs/developer/API.md | 107 +++++++ docs/developer/ARCHITECTURE.md | 88 ++++++ docs/developer/DEVELOPMENT_GUIDE.md | 126 ++++++++ docs/{ => developer}/IMPLEMENTATION_GUIDE.md | 0 .../KNOWLEDGE_BASE_GUIDELINE.md | 0 docs/developer/TESTING.md | 83 +++++ docs/user/FAQ.md | 52 +++ docs/user/GETTING_STARTED.md | 69 ++++ docs/user/TUTORIAL.md | 57 ++++ examples/quickstart.py | 3 + pyproject.toml | 106 +++++++ setup.py | 18 ++ src/core/__init__.py | 1 - src/data/__init__.py | 1 - src/ui/__init__.py | 1 - tests/__init__.py | 17 +- src/utils/__init__.py => tests/conftest.py | 0 tests/integration/__init__.py | 3 + tests/unit/__init__.py | 3 + 45 files changed, 1660 insertions(+), 4 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/documentation.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/ci.yml create mode 100644 .pre-commit-config.yaml create mode 100644 Makefile create mode 100644 bytebrain/__init__.py create mode 100644 bytebrain/__main__.py create mode 100644 bytebrain/core/__init__.py create mode 100644 bytebrain/guardrails/__init__.py create mode 100644 bytebrain/prompts/__init__.py create mode 100644 bytebrain/skills/__init__.py create mode 100644 bytebrain/ui/__init__.py create mode 100644 bytebrain/ui/streamlit_app.py rename src/utils/logger.py => bytebrain/utils/__init__.py (100%) rename {src => bytebrain}/utils/config.py (100%) create mode 100644 docs/NORMALIZATION_PLAN.md create mode 100644 docs/NORMALIZATION_SUMMARY.md create mode 100644 docs/README.md rename docs/{ => design}/DESIGN_PHILOSOPHY.md (100%) rename docs/{ => design}/NEEDS_ANALYSIS_2026.md (100%) rename docs/{ => design}/PROJECT_POSITIONING.md (100%) rename docs/{ => design}/SKILL_PROMPT_GUARDRAILS_2026.md (100%) rename docs/{ => design}/TECH_PLAYGROUND_2026.md (100%) create mode 100644 docs/developer/API.md create mode 100644 docs/developer/ARCHITECTURE.md create mode 100644 docs/developer/DEVELOPMENT_GUIDE.md rename docs/{ => developer}/IMPLEMENTATION_GUIDE.md (100%) rename docs/{ => developer}/KNOWLEDGE_BASE_GUIDELINE.md (100%) create mode 100644 docs/developer/TESTING.md create mode 100644 docs/user/FAQ.md create mode 100644 docs/user/GETTING_STARTED.md create mode 100644 docs/user/TUTORIAL.md create mode 100644 examples/quickstart.py create mode 100644 pyproject.toml create mode 100644 setup.py delete mode 100644 src/core/__init__.py delete mode 100644 src/data/__init__.py delete mode 100644 src/ui/__init__.py rename src/utils/__init__.py => tests/conftest.py (100%) create mode 100644 tests/integration/__init__.py create mode 100644 tests/unit/__init__.py diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..3503b6a --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,123 @@ +# 贡献指南 + +感谢你对 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 +``` + +--- + +## 开发工作流 + +### 1. 创建分支 +```bash +git checkout -b feature/your-feature-name +``` + +### 2. 编写代码 +- 遵循项目的代码风格 +- 添加必要的类型注解 +- 编写单元测试 + +### 3. 运行测试 +```bash +make test +``` + +### 4. 代码格式化 +```bash +make format +``` + +### 5. 提交代码 +```bash +git add . +git commit -m "feat: 描述你的变更" +git push origin feature/your-feature-name +``` + +### 6. 创建 Pull Request +在 GitHub 上创建 PR，填写 PR 模板 + +--- + +## 代码规范 + +### Python 代码 +- 使用 Black 格式化代码 +- 遵循 Flake8 检查 +- 使用类型注解（Type Hints） +- 遵循 Google 风格的文档字符串 + +### 文档 +- 使用 Markdown 格式 +- 代码示例要可运行 +- 英文术语首字母大写 + +--- + +## 提交信息规范 + +使用 Conventional Commits 格式： + +``` +(): + + + +