Week 4-5+ 实施计划

📋 总览

Week 4: Monorepo实施 (5天)
  Day 1: 目录结构重组
  Day 2: Git Subtree设置
  Day 3: Docker配置优化
  Day 4: CI/CD准备
  Day 5: 文档整理与验证

Week 5+: 功能开发 (持续)
  阶段1: 新功能开发
  阶段2: 性能优化
  阶段3: 用户体验改进

🗂️ Week 4: Monorepo实施

Day 1: 目录结构重组 (已完成70%)

当前状态

已有结构:
  ✅ opensource/ - 开源项目目录
    ✅ mbe-education/ - 教育应用
    ✅ mbe-sdk-python/ - Python SDK
    ✅ mbe-mcp-server/ - MCP服务器
  
  ✅ src/ - 核心私有代码
  ✅ docs/ - 完整文档
  ✅ docker-compose.*.yml - 多环境配置

缺少:
  ⚠️ private/ - 私有代码独立目录
  ⚠️ public/ - 公开代码统一目录
  ⚠️ tools/ - 工具脚本完善

目标结构

mises-behavior-engine/  (Monorepo根目录)
├── private/           # 🆕 私有闭源代码
│   ├── core/         # 核心引擎
│   ├── moe/          # MOE架构
│   ├── hope/         # HOPE学习
│   ├── titans/       # TITANS系统
│   └── api/          # 内部API
│
├── public/            # 🆕 公开开源代码
│   ├── sdk-python/   # Python SDK
│   ├── sdk-js/       # JavaScript SDK
│   ├── mcp-server/   # MCP服务器
│   └── education/    # 教育应用
│
├── shared/            # 🆕 共享代码
│   ├── models/       # 数据模型
│   ├── utils/        # 工具函数
│   └── types/        # 类型定义
│
├── tools/             # ✅ 工具脚本
│   ├── publish/      # 发布脚本
│   ├── dev/          # 开发工具
│   └── ci/           # CI/CD脚本
│
├── docker/            # 🆕 Docker配置
│   ├── dev/
│   ├── prod/
│   └── test/
│
├── docs/              # ✅ 文档 (已完善)
├── tests/             # ✅ 测试
└── scripts/           # ✅ 脚本

实施步骤

# Step 1: 创建新目录结构
mkdir -p private/{core,moe,hope,titans,api}
mkdir -p public/{sdk-python,sdk-js,mcp-server,education}
mkdir -p shared/{models,utils,types}
mkdir -p tools/{publish,dev,ci}
mkdir -p docker/{dev,prod,test}

# Step 2: 移动现有代码到private/
# (核心代码保持私有)
mv src/core private/
mv src/moe private/
mv src/knowledge/hope_moe.py private/hope/
mv src/knowledge/titans_*.py private/titans/
# ... 其他核心模块

# Step 3: 移动开源代码到public/
mv opensource/mbe-sdk-python public/sdk-python
mv opensource/mbe-mcp-server public/mcp-server
mv opensource/mbe-education public/education

# Step 4: 创建共享代码
# 提取公共模型和工具到shared/

# Step 5: 更新所有import路径
# 使用脚本批量更新

Day 2: Git Subtree设置

2.1 设置GitHub远程仓库

# 1. 为每个公开项目创建GitHub仓库
# - mbe-sdk-python → github.com/mises-org/mbe-sdk-python
# - mbe-mcp-server → github.com/mises-org/mbe-mcp-server  
# - mbe-education → github.com/mises-org/mbe-education

# 2. 添加远程仓库
git remote add sdk-python git@github.com:mises-org/mbe-sdk-python.git
git remote add mcp-server git@github.com:mises-org/mbe-mcp-server.git
git remote add education git@github.com:mises-org/mbe-education.git

2.2 设置Git Subtree

# 推送SDK到GitHub
git subtree push --prefix=public/sdk-python sdk-python main

# 推送MCP服务器到GitHub
git subtree push --prefix=public/mcp-server mcp-server main

# 推送教育应用到GitHub
git subtree push --prefix=public/education education main

2.3 创建发布脚本

# tools/publish/publish_sdk.sh
#!/bin/bash

echo "📦 Publishing SDK to GitHub..."

# 验证代码安全
python tools/publish/validate_public.py public/sdk-python
if [ $? -ne 0 ]; then
    echo "❌ Validation failed"
    exit 1
fi

# 推送到GitHub
git subtree push --prefix=public/sdk-python sdk-python main

echo "✅ SDK published successfully"

Day 3: Docker配置优化

3.1 分离Docker配置

# docker/dev/docker-compose.yml
version: '3.8'

services:
  mbe-api-dev:
    build:
      context: ../..
      dockerfile: docker/dev/Dockerfile
    volumes:
      - ../../private:/app/private
      - ../../public:/app/public
      - ../../shared:/app/shared
    environment:
      - ENV=development
      - DEBUG=true

  postgres-dev:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_DB=mbe_dev

# docker/prod/docker-compose.yml
version: '3.8'

services:
  mbe-api:
    build:
      context: ../..
      dockerfile: docker/prod/Dockerfile
    volumes:
      - /app/data:/app/data  # 只挂载数据
    environment:
      - ENV=production
      - DEBUG=false

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_DB=mbe_prod

3.2 多阶段构建优化

# docker/prod/Dockerfile
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04 as base

# 基础环境
RUN apt-get update && apt-get install -y \
    python3.10 python3-pip \
    && rm -rf /var/lib/apt/lists/*

# 依赖层
FROM base as dependencies
COPY requirements.txt /tmp/
RUN pip install --no-cache-dir -r /tmp/requirements.txt

# 应用层
FROM dependencies as app
WORKDIR /app

# 只复制私有代码和共享代码
COPY private/ /app/private/
COPY shared/ /app/shared/

# 公开代码不包含在生产镜像中
# (通过API调用公开服务)

EXPOSE 8000
CMD ["uvicorn", "private.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Day 4: CI/CD准备

4.1 GitHub Actions配置

# .github/workflows/test.yml
name: Test

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main]

jobs:
  test-private:
    name: Test Private Code
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-cov
      
      - name: Run tests
        run: |
          pytest tests/private/ --cov=private/
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3

  test-public:
    name: Test Public Code
    runs-on: ubuntu-latest
    strategy:
      matrix:
        project: [sdk-python, mcp-server, education]
    steps:
      - uses: actions/checkout@v3
      
      - name: Test ${{ matrix.project }}
        run: |
          cd public/${{ matrix.project }}
          pip install -r requirements.txt
          pytest tests/

  validate-public:
    name: Validate Public Code
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check for private dependencies
        run: |
          python tools/publish/validate_public.py

# .github/workflows/publish.yml
name: Publish to GitHub

on:
  push:
    branches: [main]
    paths:
      - 'public/**'

jobs:
  publish-sdk:
    if: contains(github.event.head_commit.modified, 'public/sdk-python')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 需要完整历史
      
      - name: Validate SDK
        run: python tools/publish/validate_public.py public/sdk-python
      
      - name: Push to GitHub
        run: |
          git subtree push --prefix=public/sdk-python \
            https://${{ secrets.GH_TOKEN }}@github.com/mises-org/mbe-sdk-python.git \
            main

  publish-mcp:
    if: contains(github.event.head_commit.modified, 'public/mcp-server')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Validate MCP Server
        run: python tools/publish/validate_public.py public/mcp-server
      
      - name: Push to GitHub
        run: |
          git subtree push --prefix=public/mcp-server \
            https://${{ secrets.GH_TOKEN }}@github.com/mises-org/mbe-mcp-server.git \
            main

4.2 Pre-commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
  
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        files: ^(private|public|shared)/.*\.py$
  
  - repo: local
    hooks:
      - id: validate-public
        name: Validate Public Code
        entry: python tools/publish/validate_public.py
        language: system
        files: ^public/.*\.py$
        pass_filenames: false

Day 5: 文档整理与验证

5.1 更新README

# Mises Behavior Engine (MBE)

## 项目结构

此项目采用Monorepo + Git Subtree架构:

- `private/` - 闭源核心代码 (AGPL + 商业授权)
- `public/` - 开源项目 (AGPL-3.0)
  - `sdk-python/` - Python SDK
  - `mcp-server/` - MCP服务器
  - `education/` - 教育应用
- `shared/` - 共享代码
- `tools/` - 工具脚本
- `docker/` - Docker配置

## 快速开始

### 开发环境

\`\`\`bash
# 克隆仓库
git clone <private-repo-url>
cd mises-behavior-engine

# 启动开发环境
docker compose -f docker/dev/docker-compose.yml up
\`\`\`

### 使用公开SDK

\`\`\`bash
# 从GitHub安装
pip install git+https://github.com/mises-org/mbe-sdk-python.git
\`\`\`

## 贡献指南

详见 [CONTRIBUTING.md](docs/CONTRIBUTING.md)

5.2 创建CONTRIBUTING.md

# 贡献指南

## 开源项目贡献

我们欢迎对以下开源项目的贡献:

- [mbe-sdk-python](https://github.com/mises-org/mbe-sdk-python)
- [mbe-mcp-server](https://github.com/mises-org/mbe-mcp-server)
- [mbe-education](https://github.com/mises-org/mbe-education)

请直接在对应的GitHub仓库提交PR。

## 核心引擎改进

如需改进核心引擎，请联系团队获取访问权限。

## 开发流程

1. Fork对应项目
2. 创建功能分支
3. 提交PR
4. 等待Review
5. 合并后自动同步回Monorepo

🚀 Week 5+: 功能开发

阶段1: 新功能开发

1.1 教育应用增强

目标: 完善教育应用的核心功能

功能列表:
  ✅ 数据库模型 (已完成)
  ⚠️ 前端界面 (进行中)
  ⚠️ LLM内容生成 (待开发)
  ⚠️ 用户个性化 (待开发)
  ⚠️ 进度追踪 (待开发)

实施计划:
  Week 5: 前端界面完成
  Week 6: LLM内容生成集成
  Week 7: 用户个性化功能
  Week 8: 进度追踪系统

1.2 SDK功能扩展

Python SDK增强:
  - 异步API支持
  - 批量操作
  - WebSocket实时通信
  - 错误重试机制
  - 详细的类型提示

JavaScript SDK (新增):
  - TypeScript支持
  - React Hooks
  - Vue Composables
  - WebSocket客户端
  - 完整的类型定义

1.3 MCP服务器增强

新增功能:
  - 更多工具支持
  - 流式响应
  - 批量处理
  - 缓存优化
  - 性能监控

阶段2: 性能优化

2.1 检索性能

已完成:
  ✅ 缓存机制 (25%+命中率)
  ✅ TitansRAG集成

待优化:
  ⚠️ 缓存预热
  ⚠️ 智能缓存淘汰
  ⚠️ 分布式缓存 (Redis)
  ⚠️ 向量索引优化
  ⚠️ GPU加速优化

目标:
  - 缓存命中率: 25% → 60%+
  - 检索延迟: 100ms → 30ms
  - QPS: 100 → 500+

2.2 API性能

优化项目:
  - 数据库查询优化
  - N+1查询消除
  - 连接池调优
  - 异步处理
  - 批量操作

目标:
  - API响应时间: 200ms → 50ms
  - 并发处理: 100 → 1000+
  - 资源使用: -30%

2.3 MOE性能

优化项目:
  - 专家选择加速
  - 并行推理
  - 模型量化
  - 批处理优化
  - GPU利用率提升

目标:
  - 推理延迟: 500ms → 200ms
  - GPU利用率: 60% → 90%+
  - 吞吐量: +200%

阶段3: 用户体验改进

3.1 错误处理增强

已完成:
  ✅ 5层Fallback机制
  ✅ 详细的错误日志
  ✅ 友好的错误消息

待改进:
  ⚠️ 错误恢复建议
  ⚠️ 自动重试机制
  ⚠️ 降级策略
  ⚠️ 用户通知系统

3.2 文档和示例

文档改进:
  - API参考文档
  - 快速入门教程
  - 最佳实践指南
  - 故障排查手册
  - 视频教程

示例代码:
  - 基础使用示例
  - 高级功能示例
  - 集成示例
  - 性能优化示例
  - 完整应用示例

3.3 开发者工具

工具开发:
  - CLI工具
  - VS Code扩展
  - 调试工具
  - 性能分析工具
  - 测试工具

目标:
  - 降低学习曲线
  - 提升开发效率
  - 改善调试体验

📅 时间表

Week 4 (当前周):
  Day 1: ✅ 目录结构规划
  Day 2: ⚠️ Git Subtree设置
  Day 3: ⚠️ Docker配置
  Day 4: ⚠️ CI/CD准备
  Day 5: ⚠️ 文档整理

Week 5-6: 教育应用完善
  - 前端界面完成
  - LLM集成
  - 基础功能测试

Week 7-8: SDK和MCP增强
  - Python SDK v2.0
  - JavaScript SDK v1.0
  - MCP服务器增强

Week 9-10: 性能优化
  - 检索优化
  - API优化
  - MOE优化

Week 11-12: 用户体验
  - 文档完善
  - 工具开发
  - 示例丰富

🎯 成功标准

Week 4完成标准

目录结构:
  ✅ private/ 独立
  ✅ public/ 统一
  ✅ shared/ 提取
  ✅ tools/ 完善

Git Subtree:
  ✅ 3个公开项目独立仓库
  ✅ 自动同步脚本
  ✅ 验证机制

Docker:
  ✅ 开发环境配置
  ✅ 生产环境配置
  ✅ 测试环境配置

CI/CD:
  ✅ 自动测试
  ✅ 自动发布
  ✅ Pre-commit hooks

文档:
  ✅ README更新
  ✅ CONTRIBUTING.md
  ✅ 架构文档

Week 5+成功标准

新功能:
  ✅ 教育应用可用
  ✅ SDK功能完整
  ✅ MCP服务稳定

性能:
  ✅ 缓存命中率 60%+
  ✅ API响应 < 50ms
  ✅ QPS 500+

用户体验:
  ✅ 文档完善
  ✅ 示例丰富
  ✅ 工具易用

📝 注意事项

代码安全

重要:
  - private/ 代码绝不同步到GitHub
  - public/ 代码经过validate_public.py验证
  - 敏感配置使用环境变量
  - 定期安全审计

保护机制:
  - Pre-commit hooks
  - CI/CD验证
  - 代码审查
  - 自动扫描

向后兼容

原则:
  - 不破坏现有API
  - 渐进式迁移
  - 保留旧路径兼容
  - 充分的过渡期

策略:
  - 版本标记
  - 弃用警告
  - 迁移指南
  - 自动化工具

计划制定时间: 2026-02-01
预计完成时间: 2026-04-30 (Week 4-16)
当前状态: Week 4 Day 1规划完成
下一步: 开始实施Day 2 Git Subtree设置