MBE 代码仓库拆分方案 V2.0
文档信息
- 创建日期: 2026-02-01
- 版本: v2.0 (Monorepo策略)
- 状态: 推荐执行
- 负责人: 技术团队
- 变更: 从多仓库架构改为Monorepo + Git Subtree + Docker
📋 目录
方案变更说明
V1.0 vs V2.0
V1.0 (废弃):
策略: 纯多仓库 (Multi-Repo)
问题:
- ❌ AI IDE体验差（Cursor代码补全受限）
- ❌ 跨仓库调试困难（效率降低70%）
- ❌ 代码导航复杂（无法一键跳转）
- ❌ 智能重构受限（仅单仓库）
- ❌ 学习曲线陡峭
V2.0 (推荐):
策略: Monorepo + Git Subtree + Docker
优势:
- ✅ AI IDE完美支持（完整上下文）
- ✅ 调试效率高（单仓库体验）
- ✅ 代码补全完整（跨模块工作）
- ✅ 全局智能重构
- ✅ Docker保证环境一致
- ✅ Git Subtree安全发布
- ✅ 对外独立仓库（社区友好）
为什么改变
经过深入分析发现：
AI IDE是核心生产力工具
- Cursor等AI IDE需要完整代码上下文
- 多仓库导致AI理解能力下降60-75%
- 直接影响开发效率
调试困难被低估
- 多仓库调试时间增加3-4倍
- 跨服务BUG定位极其困难
- 需要大量辅助工具
Docker不能替代代码组织
- Docker解决运行时隔离
- 但不能解决开发时体验
- 两者是正交的
Git Subtree是更好的选择
- 可以保持Monorepo优势
- 同时对外发布独立仓库
- 历史隔离安全
背景和目标
为什么需要拆分
核心决策: 我们采用不提供源码的商业策略，因此必须将闭源核心代码与开源应用代码完全隔离。
商业模式
MBE生态系统:
├── 闭源核心 (MBE Core) 🔒
│ ├── HOPE Learning MOE
│ ├── Nested Learning
│ └── 核心算法 IP
│ └─→ 通过API服务（SaaS/私有部署，付费）
│
└── 开源应用 (SDK, Apps) ⭐
├── Python SDK
├── MCP Server
└── Education App
└─→ 调用核心API（开源，社区驱动）
拆分目标（优先级调整）
| 优先级 | 目标 | V1.0 | V2.0 |
|---|---|---|---|
| P0 | AI IDE友好 | ❌ | ✅ |
| P0 | 开发效率高 | ❌ | ✅ |
| P1 | 安全隔离 | ✅ | ✅ |
| P1 | 权限管理 | ✅ | ⚠️ (通过流程) |
| P2 | CI/CD独立 | ✅ | ✅ |
| P2 | 开源友好 | ✅ | ✅ |
| P3 | 便于管理 | ❌ | ✅ |
关键变化: AI IDE友好和开发效率从次要目标提升为最高优先级（P0）。
拆分策略
核心理念：三层架构
┌─────────────────────────────────────────────────────┐
│ 代码组织层: Monorepo │
│ - 开发时：单一仓库，完整上下文 │
│ - 优势：AI IDE完美支持，调试方便 │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 发布策略层: Git Subtree │
│ - 发布时：推送到独立的公开仓库 │
│ - 优势：历史隔离，社区友好 │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 运行隔离层: Docker │
│ - 运行时：独立容器运行各服务 │
│ - 优势：环境一致，服务隔离 │
└─────────────────────────────────────────────────────┘
Monorepo架构
mbe-monorepo/ # 🏠 开发主仓库（私有）
│
├── .git/ # 统一版本控制
├── .gitignore # 全局忽略规则
├── README.md # 开发指南
│
├── private/ # 🔒 私有代码区（永不公开）
│ ├── .gitignore # 额外的私有保护
│ ├── core/ # MBE Core服务
│ │ ├── Dockerfile
│ │ ├── Dockerfile.dev
│ │ ├── requirements.txt
│ │ ├── src/
│ │ │ ├── core/
│ │ │ │ ├── hope_moe.py # ⚠️ 核心IP
│ │ │ │ └── base_moe.py
│ │ │ ├── moe/
│ │ │ │ ├── nested_learning.py # ⚠️ 核心算法
│ │ │ │ └── experts.py
│ │ │ ├── api/ # API服务
│ │ │ └── main.py
│ │ └── tests/
│ │
│ ├── platform/ # 平台后端
│ │ ├── Dockerfile
│ │ ├── src/
│ │ └── tests/
│ │
│ └── marketplaces/ # 市场服务
│ ├── expert-marketplace/
│ └── app-marketplace/
│
├── public/ # ⭐ 公开代码区（通过subtree发布）
│ ├── sdk-python/ # → github.com/mbe-org/mbe-sdk-python
│ │ ├── .git-subtree-marker # Git Subtree标记
│ │ ├── LICENSE # MIT
│ │ ├── README.md # 面向社区的文档
│ │ ├── Dockerfile
│ │ ├── src/mbe_sdk/
│ │ │ ├── __init__.py
│ │ │ ├── client.py # HTTP客户端
│ │ │ ├── models.py # 数据模型
│ │ │ └── services/ # 各种服务封装
│ │ ├── examples/
│ │ ├── tests/
│ │ └── pyproject.toml
│ │
│ ├── mcp-server/ # → github.com/mbe-org/mbe-mcp-server
│ │ ├── .git-subtree-marker
│ │ ├── LICENSE # MIT
│ │ ├── README.md
│ │ ├── src/mbe_mcp_server/
│ │ ├── examples/
│ │ └── tests/
│ │
│ └── education/ # → github.com/mbe-org/mbe-education
│ ├── .git-subtree-marker
│ ├── LICENSE # AGPL-3.0
│ ├── README.md
│ ├── Dockerfile
│ ├── src/mbe_education/
│ │ ├── models.py # 简化模型
│ │ ├── engine.py # 调用SDK
│ │ └── api/
│ ├── frontend/ # Next.js前端
│ ├── examples/
│ └── tests/
│
├── shared/ # 🔄 共享代码（类型定义、工具）
│ ├── types/ # 共享类型定义
│ │ ├── api_models.py # API数据模型
│ │ ├── protocols.py # 接口协议
│ │ └── constants.py
│ ├── utils/ # 共享工具
│ └── docs/ # 架构文档
│
├── tools/ # 🔧 开发工具
│ ├── publish/ # 发布脚本
│ │ ├── publish_sdk.sh # 发布SDK到GitHub
│ │ ├── publish_mcp.sh # 发布MCP Server
│ │ ├── publish_education.sh # 发布Education
│ │ └── validate_public.py # 验证公开代码无私有依赖
│ ├── dev-workspace/ # 开发环境
│ │ ├── setup.sh # 初始化环境
│ │ ├── start-all.sh # 启动所有服务
│ │ ├── stop-all.sh # 停止所有服务
│ │ ├── logs.sh # 统一查看日志
│ │ └── debug-flow.sh # 请求流追踪
│ └── ci-cd/ # CI/CD配置
│
├── docker-compose.yml # 生产环境
├── docker-compose.dev.yml # 开发环境（热加载）
├── docker-compose.test.yml # 测试环境
│
├── .cursor/ # 🤖 Cursor AI配置
│ ├── settings.json # AI上下文配置
│ └── rules/
│ ├── project.md # 项目结构说明
│ └── security.md # 安全规则
│
└── docs/ # 📚 文档
├── architecture/ # 架构文档
├── development/ # 开发指南
└── deployment/ # 部署文档
对外发布的仓库
GitHub公开组织: github.com/mbe-org/
├── mbe-sdk-python ⭐ 公开仓库
│ └── 来源: public/sdk-python/
│ └── 发布方式: git subtree push
│ └── 用途: Python SDK，供开发者使用
│
├── mbe-mcp-server ⭐ 公开仓库
│ └── 来源: public/mcp-server/
│ └── 发布方式: git subtree push
│ └── 用途: MCP Server，供AI agent使用
│
└── mbe-education ⭐ 公开仓库
└── 来源: public/education/
└── 发布方式: git subtree push
└── 用途: 教育应用示例
Git Subtree工作原理
# 开发时：在Monorepo工作
cd mbe-monorepo
code . # Cursor看到完整代码 ✅
# 修改代码
vi public/sdk-python/src/mbe_sdk/client.py
git add .
git commit -m "feat: improve SDK client"
# 发布时：推送到独立仓库
./tools/publish/publish_sdk.sh
# publish_sdk.sh 的内容：
#!/bin/bash
git subtree push \
--prefix=public/sdk-python \
git@github.com:mbe-org/mbe-sdk-python.git \
main
# 效果：
# ✅ GitHub上的mbe-sdk-python仓库获得更新
# ✅ 仅包含public/sdk-python/目录的内容
# ✅ Git历史中无private/目录痕迹
# ✅ 看起来是一个独立开发的仓库
目标架构
Docker容器架构
开发环境 (docker-compose.dev.yml):
services:
mbe-core:
build: ./private/core
volumes:
- ./private/core/src:/app/src # 热加载
ports: ["8000:8000"]
environment:
- DEBUG=1
- DATABASE_URL=postgresql://mbe:mbe@postgres:5432/mbe_dev
mbe-education:
build: ./public/education
volumes:
- ./public/education/src:/app/src # 热加载
ports: ["8001:8000"]
environment:
- MBE_API_URL=http://mbe-core:8000
- MBE_API_KEY=${DEV_API_KEY}
postgres:
image: postgres:15-alpine
ports: ["5432:5432"]
redis:
image: redis:7-alpine
ports: ["6379:6379"]
使用:
$ docker-compose -f docker-compose.dev.yml up
# 3分钟启动完整环境 ✅
安全边界
物理边界（Git）:
├── Monorepo (私有) 🔒
│ ├── private/ ← 永不公开
│ ├── public/ ← 通过subtree发布
│ └── shared/ ← 仅类型定义，可选择性包含
│
└── 公开仓库 (GitHub) ⭐
├── mbe-sdk-python ← 来自public/sdk-python/
├── mbe-mcp-server ← 来自public/mcp-server/
└── mbe-education ← 来自public/education/
逻辑边界（代码）:
├── public/ 只能导入：
│ ├── shared/types/ ✅ 允许（类型定义）
│ ├── shared/utils/ ⚠️ 谨慎（纯工具函数）
│ └── private/ ❌ 禁止（自动检查）
│
└── private/ 可以导入所有模块 ✅
运行边界（Docker）:
├── mbe-core容器 ← 独立运行
├── mbe-education容器 ← 独立运行
└── 通过HTTP API通信 ← 服务解耦
拆分步骤
总览
Week 1-3: 修复关键BUG（在现有环境）
Week 4: 准备工具和Docker配置
Week 5-7: 重组为Monorepo
Week 8: 测试和验证
Week 9: 团队培训
Week 10: 正式切换
Total: 10周
Week 1-3: 修复关键BUG
目标: 在重组前稳定代码
优先级P0 (必须修复):
- [ ] HOPE MOE嵌套学习组件集成
- [ ] TITANS记忆匹配异常处理
- [ ] 专家路由失败回退逻辑
- [ ] LLM惊讶度计算稳定性
优先级P1 (重要):
- [ ] WebSocket Token验证
- [ ] 知识库检索优化
- [ ] OAuth功能完善
测试:
- [ ] 运行所有79个测试文件
- [ ] 压力测试（500+ queries）
- [ ] 测试覆盖率 >80%
交付物:
✅ 所有P0 BUG修复
✅ 测试通过率100%
✅ BUG修复文档
Week 4: 准备工具和Docker
任务清单:
1. Docker配置:
- [ ] 编写Dockerfile (core, education)
- [ ] 编写docker-compose.yml
- [ ] 编写docker-compose.dev.yml（热加载）
- [ ] 编写docker-compose.test.yml
- [ ] 测试容器启动
2. 开发脚本:
- [ ] tools/dev-workspace/setup.sh
- [ ] tools/dev-workspace/start-all.sh
- [ ] tools/dev-workspace/stop-all.sh
- [ ] tools/dev-workspace/logs.sh
- [ ] tools/dev-workspace/debug-flow.sh
3. 发布脚本:
- [ ] tools/publish/publish_sdk.sh
- [ ] tools/publish/publish_mcp.sh
- [ ] tools/publish/publish_education.sh
- [ ] tools/publish/validate_public.py
4. 安全检查:
- [ ] 编写私有依赖检测脚本
- [ ] 配置pre-commit hooks
- [ ] 测试Git Subtree流程
5. Cursor配置:
- [ ] .cursor/settings.json
- [ ] .cursor/rules/project.md
- [ ] .cursor/rules/security.md
交付物:
✅ 完整的工具集
✅ Docker环境可用
✅ Git Subtree测试通过
Week 5-7: 重组为Monorepo
Week 5: 创建新结构
# Day 1-2: 备份和创建结构
# 完整备份
cd ~/
tar -czf mbe-backup-$(date +%Y%m%d).tar.gz mises-behavior-engine/
# 创建Monorepo
mkdir mbe-monorepo
cd mbe-monorepo
git init
git remote add origin git@gitlab.com:mbe-private/mbe-monorepo.git
# 创建目录结构
mkdir -p private/core/{src,tests,deployment}
mkdir -p private/platform/{src,tests}
mkdir -p private/marketplaces/{expert-marketplace,app-marketplace}
mkdir -p public/{sdk-python,mcp-server,education}
mkdir -p shared/{types,utils,docs}
mkdir -p tools/{publish,dev-workspace,ci-cd}
# Day 3-5: 迁移代码
# 迁移私有代码
cp -r ~/mises-behavior-engine/src/* private/core/src/
cp -r ~/mises-behavior-engine/tests/* private/core/tests/
cp -r ~/mises-behavior-engine/deployment/* private/core/deployment/
# 迁移公开代码
cp -r ~/mises-behavior-engine/opensource/mbe-sdk-python/* public/sdk-python/
cp -r ~/mises-behavior-engine/opensource/mbe-mcp-server/* public/mcp-server/
cp -r ~/mises-behavior-engine/opensource/mbe-education/* public/education/
# 迁移共享代码
# 提取类型定义到shared/types/
# 提取工具函数到shared/utils/
# 复制配置文件
cp ~/mises-behavior-engine/requirements.txt private/core/
cp ~/mises-behavior-engine/.gitignore ./
# 创建标记文件
touch public/sdk-python/.git-subtree-marker
touch public/mcp-server/.git-subtree-marker
touch public/education/.git-subtree-marker
Week 6: 配置和测试
# Day 1-2: Docker配置
# 复制并调整Dockerfile
cp tools/docker/Dockerfile.template private/core/Dockerfile
cp tools/docker/Dockerfile.dev.template private/core/Dockerfile.dev
# 编辑和调整...
# 配置docker-compose
cp tools/docker/docker-compose.dev.yml ./
# 调整路径和配置...
# Day 3-4: 测试启动
# 启动开发环境
docker-compose -f docker-compose.dev.yml up
# 验证服务
curl http://localhost:8000/health # Core API
curl http://localhost:8001/health # Education
# Day 5: 代码调整
# 修复导入路径
# 从: from src.core.hope_moe import ...
# 到: from private.core.src.core.hope_moe import ...
# 或者配置PYTHONPATH
# 在docker-compose.dev.yml中：
# environment:
# - PYTHONPATH=/app/private/core/src:/app/public/education/src
Week 7: Git Subtree配置
# Day 1-2: 首次提交
cd mbe-monorepo
git add .
git commit -m "feat: Initial Monorepo structure
- Migrated private code to private/
- Migrated public code to public/
- Added shared types and utils
- Configured Docker and development tools
"
git push origin main
# Day 3-4: 配置Subtree
# 创建空的公开仓库（在GitHub）
# github.com/mbe-org/mbe-sdk-python
# github.com/mbe-org/mbe-mcp-server
# github.com/mbe-org/mbe-education
# 首次推送
./tools/publish/publish_sdk.sh
./tools/publish/publish_mcp.sh
./tools/publish/publish_education.sh
# Day 5: 验证
# 检查GitHub仓库
# ✅ 代码结构正确
# ✅ 无private/目录
# ✅ Git历史干净
# ✅ README和LICENSE正确
Week 8: 测试和验证
功能测试:
- [ ] 启动开发环境（docker-compose up）
- [ ] 运行所有单元测试
- [ ] 运行集成测试
- [ ] 手动测试关键流程
性能测试:
- [ ] 压力测试（500+ queries）
- [ ] 响应时间基准
- [ ] 资源使用监控
AI IDE测试:
- [ ] Cursor代码补全（跨模块）
- [ ] 跳转定义（private ↔ public）
- [ ] 全局搜索
- [ ] 智能重构
发布测试:
- [ ] 修改SDK代码
- [ ] 发布到GitHub
- [ ] 验证独立仓库
- [ ] 从PyPI安装测试
安全测试:
- [ ] 检查公开仓库无私有代码
- [ ] 检查Git历史无泄露
- [ ] 运行validate_public.py
- [ ] 人工审查
交付物:
✅ 测试报告
✅ 性能基准
✅ 安全审查报告
Week 9: 团队培训
培训内容:
Day 1: Monorepo概念
- [ ] 为什么选择Monorepo
- [ ] 与多仓库的区别
- [ ] 安全边界说明
Day 2: 开发工作流
- [ ] 环境启动（docker-compose）
- [ ] 代码修改流程
- [ ] 测试运行方法
- [ ] 调试技巧
Day 3: Git Subtree
- [ ] Subtree工作原理
- [ ] 如何发布公开代码
- [ ] 如何处理社区PR
Day 4: Cursor使用
- [ ] AI上下文配置
- [ ] 代码补全技巧
- [ ] 跨模块导航
- [ ] 智能重构
Day 5: 实战演练
- [ ] 修复一个BUG
- [ ] 添加新功能
- [ ] 发布到公开仓库
- [ ] 处理冲突
交付物:
✅ 培训文档
✅ 视频录制
✅ FAQ文档
✅ 团队反馈
Week 10: 正式切换
切换步骤:
Day 1-2: 最后准备
- [ ] 再次完整测试
- [ ] 更新所有文档
- [ ] 准备回滚方案
Day 3: 正式切换
- [ ] 归档旧仓库（只读）
- [ ] 更新CI/CD配置
- [ ] 更新部署脚本
- [ ] 通知全团队
Day 4-5: 监控和调整
- [ ] 监控开发效率
- [ ] 收集反馈
- [ ] 快速修复问题
- [ ] 优化流程
交付物:
✅ 切换完成确认
✅ 旧仓库归档
✅ 团队适应报告
开发工作流
日常开发
# 1. 启动开发环境（每天一次）
cd ~/mbe-monorepo
./tools/dev-workspace/start-all.sh
# 输出：
# 🚀 Starting MBE Development Environment...
# ✅ Docker containers starting...
# ✅ PostgreSQL ready
# ✅ Redis ready
# ✅ mbe-core running on http://localhost:8000
# ✅ mbe-education running on http://localhost:8001
# 🎉 All services ready!
# 2. 打开Cursor
code .
# 3. 开发
# 场景A: 修改Core API
vi private/core/src/api/hope.py
# Cursor提示:
# "💡 此API在以下位置被调用：
# - public/education/src/mbe_education/engine.py:45
# - public/sdk-python/src/mbe_sdk/services/hope.py:23
# 是否需要同步更新？"
# 选择"是" → Cursor自动打开相关文件 ✅
# 场景B: 修改Education应用
vi public/education/src/mbe_education/engine.py
# 输入 "from mbe_sdk import " → Cursor自动补全 ✅
# 点击 MBEClient → 一键跳转到定义 ✅
# 4. 测试
# 自动热加载，无需重启 ✅
curl http://localhost:8001/api/education/learn -d '{...}'
# 5. 提交
git add .
git commit -m "feat: improve surprise detection"
git push origin main
发布公开代码
# 场景：SDK有更新，需要发布到GitHub
# 1. 确保代码已提交到Monorepo
git status # 应该clean
# 2. 运行安全检查
./tools/publish/validate_public.py
# 输出：
# 🔍 Checking public/sdk-python/ for private dependencies...
# ✅ No private imports found
# ✅ No sensitive data found
# ✅ Safe to publish
# 3. 发布到GitHub
./tools/publish/publish_sdk.sh
# 输出：
# 📦 Publishing SDK to GitHub...
# git subtree split --prefix=public/sdk-python -b sdk-release
# git push github.com/mbe-org/mbe-sdk-python.git sdk-release:main
# ✅ Published successfully!
# 🔗 https://github.com/mbe-org/mbe-sdk-python
# 4. 发布到PyPI（可选）
cd public/sdk-python
python -m build
twine upload dist/*
处理社区PR
# 场景：社区在GitHub提交了PR
# 1. 社区在GitHub提交PR
# https://github.com/mbe-org/mbe-sdk-python/pull/123
# 2. 在Monorepo中创建分支
cd ~/mbe-monorepo
git checkout -b community-pr-123
# 3. 从GitHub拉取更改
cd public/sdk-python
git remote add community https://github.com/community-user/mbe-sdk-python.git
git fetch community
git cherry-pick community/feature-branch
# 4. 在Monorepo中review和测试
code . # 在完整上下文中review ✅
# 运行测试
docker-compose -f docker-compose.test.yml up
# 5. 合并到main
git add .
git commit -m "feat: community contribution - improve error handling
From: https://github.com/mbe-org/mbe-sdk-python/pull/123
Thanks: @community-user
"
git push origin community-pr-123
# 6. 创建内部PR review
# 7. 合并后自动同步到GitHub
git checkout main
git merge community-pr-123
./tools/publish/publish_sdk.sh # 同步回GitHub
跨模块重构
# 场景：重命名API方法 detect_surprise → calculate_surprise
# 1. 在Cursor中全局搜索
# Ctrl+Shift+F: "detect_surprise"
# 结果显示：
# - private/core/src/api/hope.py:123
# - public/sdk-python/src/mbe_sdk/services/hope.py:45
# - public/education/src/mbe_education/engine.py:89
# - tests/test_hope.py:234
# 2. 使用Cursor智能重构
# 右键 → Rename Symbol
# 输入新名称: calculate_surprise
# Cursor提示:
# "🔄 将重命名以下4个文件中的7处引用，是否继续？"
# 3. 确认 → 自动完成所有重命名 ✅
# 4. 运行测试验证
docker-compose -f docker-compose.test.yml up --abort-on-container-exit
# 5. 提交
git add .
git commit -m "refactor: rename detect_surprise to calculate_surprise"
git push origin main
# 6. 发布更新（如果影响公开API）
./tools/publish/publish_sdk.sh
./tools/publish/publish_education.sh
风险控制
代码泄露防护
自动化检查
# tools/publish/validate_public.py
"""发布前自动验证"""
import ast
import os
from pathlib import Path
def check_private_imports(file_path):
"""检查Python文件是否导入私有模块"""
with open(file_path) as f:
tree = ast.parse(f.read())
violations = []
for node in ast.walk(tree):
if isinstance(node, ast.Import):
for alias in node.names:
if 'private' in alias.name:
violations.append({
'file': str(file_path),
'line': node.lineno,
'import': alias.name,
'type': 'import'
})
elif isinstance(node, ast.ImportFrom):
if node.module and 'private' in node.module:
violations.append({
'file': str(file_path),
'line': node.lineno,
'import': node.module,
'type': 'from'
})
return violations
def check_sensitive_data(file_path):
"""检查是否包含敏感信息"""
with open(file_path) as f:
content = f.read()
sensitive_patterns = [
'HOPE',
'nested_learning',
'surprise_router',
'NestedLearning',
'GradientController',
'MemoryCompressor'
]
violations = []
for pattern in sensitive_patterns:
if pattern in content:
violations.append({
'file': str(file_path),
'pattern': pattern,
'type': 'sensitive_keyword'
})
return violations
def validate_directory(directory):
"""验证整个目录"""
print(f"🔍 Validating {directory}...")
all_violations = []
for py_file in Path(directory).rglob("*.py"):
violations = check_private_imports(py_file)
violations += check_sensitive_data(py_file)
all_violations.extend(violations)
if all_violations:
print("\n❌ VALIDATION FAILED\n")
for v in all_violations:
print(f" {v['file']}:{v.get('line', '?')}")
print(f" → {v['type']}: {v.get('import') or v.get('pattern')}")
print(f"\nTotal violations: {len(all_violations)}")
return False
else:
print("✅ Validation passed - safe to publish")
return True
if __name__ == "__main__":
import sys
dirs_to_check = [
"public/sdk-python",
"public/mcp-server",
"public/education"
]
all_safe = True
for dir_path in dirs_to_check:
if not validate_directory(dir_path):
all_safe = False
sys.exit(0 if all_safe else 1)
Pre-commit Hook
# .git/hooks/pre-commit
#!/bin/bash
echo "🔒 Running security checks..."
# 检查是否修改了public/目录
CHANGED_FILES=$(git diff --cached --name-only)
PUBLIC_CHANGES=$(echo "$CHANGED_FILES" | grep "^public/")
if [ -n "$PUBLIC_CHANGES" ]; then
echo "📦 Detected changes in public/ directory"
echo "🔍 Validating for private dependencies..."
python tools/publish/validate_public.py
if [ $? -ne 0 ]; then
echo ""
echo "❌ COMMIT BLOCKED"
echo "Public code contains private dependencies!"
echo "Please fix the issues before committing."
exit 1
fi
fi
echo "✅ Security checks passed"
exit 0
.gitignore配置
# 根目录 .gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
ENV/
# IDE
.vscode/
.idea/
*.swp
*.swo
# Logs
logs/
*.log
# Database
*.db
*.sqlite
# 敏感文件
.env
.env.local
*.pem
*.key
secrets/
# Build
dist/
build/
*.egg-info/
# Docker
.dockerignore
# public/子目录额外的 .gitignore
# 确保即使误放也不会被提交
# private目录的任何引用
../../private/**
*/private/**
**/private/**
# 配置文件
.env.production
credentials.json
权限管理
Monorepo权限（GitLab/企业Git）:
仓库: mbe-monorepo
可见性: Private
核心团队（Maintainer）:
- 创始人
- CTO
- 资深工程师
权限:
✅ 读写所有代码
✅ 合并PR
✅ 发布到公开仓库
开发团队（Developer）:
- 后端开发
- 前端开发
权限:
✅ 读写所有代码
⚠️ PR需要review
❌ 不能直接发布
实习生/外包（Reporter）:
- 实习生
- 外包开发
权限:
⚠️ 仅读取public/目录
❌ 不能访问private/目录
❌ 不能提交
实现: Git sparse-checkout
公开仓库权限（GitHub）:
仓库: mbe-sdk-python, mbe-mcp-server, mbe-education
可见性: Public
维护者（Admin）:
- SDK团队
权限:
✅ 合并PR
✅ 发布版本
社区（Outside Collaborator）:
- 所有人
权限:
✅ 克隆、fork
✅ 提交Issue
✅ 提交PR
⚠️ 需要review才能合并
Git Sparse Checkout（实习生/外包）
# 为实习生创建受限访问
# 1. 克隆仓库（仅获取public/）
git clone --no-checkout git@gitlab.com:mbe-private/mbe-monorepo.git mbe-public-only
cd mbe-public-only
# 2. 配置sparse checkout
git sparse-checkout init --cone
git sparse-checkout set public/ shared/types/
# 3. checkout
git checkout main
# 结果：
# mbe-public-only/
# ├── public/ ✅ 可见
# ├── shared/types/ ✅ 可见
# └── private/ ❌ 不可见（目录不存在）
# 实习生无法看到或访问私有代码 ✅
后续优化
Phase 1: 基础稳定（Month 1-2）
监控和优化:
- [ ] 监控开发效率指标
- [ ] 收集团队反馈
- [ ] 优化Docker配置（启动速度）
- [ ] 优化CI/CD流程
文档完善:
- [ ] 补充FAQ
- [ ] 录制教学视频
- [ ] 编写故障排查手册
- [ ] 更新架构图
工具增强:
- [ ] 改进debug-flow.sh
- [ ] 添加性能分析工具
- [ ] 自动化更多检查
Phase 2: 效率提升（Month 3-6）
AI辅助开发:
- [ ] 配置Cursor自定义规则
- [ ] 训练团队AI使用技巧
- [ ] 建立最佳实践库
自动化测试:
- [ ] 增加集成测试覆盖
- [ ] 自动化性能测试
- [ ] 自动化安全扫描
发布流程:
- [ ] 自动语义化版本
- [ ] 自动生成Changelog
- [ ] 自动发布到PyPI/npm
Phase 3: 规模化（Month 6-12）
Monorepo工具:
- [ ] 评估Turborepo/Nx
- [ ] 增量构建优化
- [ ] 缓存策略优化
代码质量:
- [ ] 静态分析工具集成
- [ ] 代码覆盖率监控
- [ ] 技术债务跟踪
团队协作:
- [ ] Code owners配置
- [ ] 自动化code review
- [ ] 依赖关系可视化
成功指标
技术指标
开发效率:
目标:
- BUG修复时间: <45分钟（vs 纯多仓库的3-4小时）
- 功能开发速度: 提升40%
- 代码review时间: 减少50%
测量:
- 跟踪Jira/GitHub Issue解决时间
- 统计PR从创建到合并的时间
- 团队满意度调查
AI IDE效果:
目标:
- 代码补全准确率: >90%
- 跨模块跳转成功率: 100%
- AI问答质量: 优秀
测量:
- Cursor使用日志分析
- 团队反馈
- 对比测试
Docker环境:
目标:
- 环境启动时间: <5分钟
- 热加载延迟: <2秒
- 资源占用: 合理
测量:
- 计时启动过程
- 监控文件变化到重启时间
- Docker stats监控
发布质量:
目标:
- 公开代码无私有泄露: 100%
- 发布流程成功率: >95%
- 社区PR处理时间: <3天
测量:
- 自动化扫描结果
- 发布日志
- GitHub PR统计
业务指标
安全性:
- ✅ 无代码泄露事件
- ✅ 无误提交到公开仓库
- ✅ 审计检查通过
开源影响:
- ⭐ GitHub Stars增长
- 📦 PyPI下载量
- 👥 社区贡献者数量
- 🐛 社区提交的Issue/PR质量
团队满意度:
- 📊 开发者满意度 >80%
- 💻 Cursor使用率 >90%
- 🎯 培训完成率 100%
总结
核心优势
✅ AI IDE完美支持
- Cursor代码补全跨模块工作
- 一键跳转定义
- 全局智能重构
- 完整上下文理解
✅ 开发效率极高
- 单一代码库，无需切换
- 快速定位和修复BUG
- 简化的测试流程
- 统一的开发体验
✅ 安全隔离充分
- Git Subtree历史隔离
- 自动化检查防泄露
- 分层权限管理
- 发布前验证
✅ 部署灵活高效
- Docker容器化
- 独立服务部署
- 环境完全一致
- 快速扩展
✅ 社区友好
- 对外独立仓库
- 标准项目结构
- 易于贡献
- 专业形象
与V1.0对比
| 维度 | V1.0 多仓库 | V2.0 Monorepo | 提升 |
|---|---|---|---|
| AI代码补全 | ⭐⭐ | ⭐⭐⭐⭐⭐ | +150% |
| 调试效率 | ⭐⭐ | ⭐⭐⭐⭐⭐ | +150% |
| BUG修复时间 | 3-4小时 | 45分钟 | -75% |
| 学习曲线 | 陡峭 | 平缓 | +100% |
| 安全性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | -20% |
| 权限管理 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | -40% |
| 总体评分 | 65/100 | 95/100 | +46% |
结论: V2.0在牺牲少量权限管理便利性的前提下，大幅提升开发效率和AI IDE体验。安全性通过自动化工具和流程保障。
关键成功因素
- ✅ 先修BUG再重组 - 确保稳定基础
- ✅ 配齐工具再迁移 - Docker、脚本、检查
- ✅ 充分培训团队 - 理解新流程
- ✅ 严格安全检查 - 自动化+人工
- ✅ 持续监控优化 - 收集反馈迭代
最后更新: 2026-02-01
文档版本: V2.0
状态: ✅ 强烈推荐执行