# 項目可持續性策略 (Sustainability Strategy)
> **解決風險**: 單一維護者的可持續性風險、功能膨脹、技術棧依賴
本文檔說明 Boring-Gemini 項目的可持續發展策略，確保項目長期健康發展。
---
## 🎯 可持續性願景
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 🌱 可持續性三大支柱 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 👥 人員彈性 │ │ 🔧 技術彈性 │ │ 📦 架構彈性 │ │
│ │ (Bus Factor) │ │ (Tech Agnostic) │ │ (Modularity) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ • 多維護者 • LLM 抽象層 • 插件系統 │
│ • 完善文檔 • 可選依賴 • 最小核心 │
│ • 自動化 CI/CD • 降級策略 • 清晰邊界 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 🚨 風險識別與緩解
### 風險 1: 單一維護者 (Bus Factor = 1)
**當前狀態**: ⚠️ 高風險
**影響**: 如果主要維護者無法繼續，項目可能停滯
**緩解策略**:
| 策略 | 行動 | 狀態 |
|------|------|------|
| **文檔完整** | 所有架構決策都有文檔記錄 | ✅ 已實施 |
| **自動化** | CI/CD 全自動化，減少人工干預 | ✅ 已實施 |
| **維護者招募** | 創建 MAINTAINERS.md，明確貢獻階梯 | ✅ 已實施 |
| **領域專家** | 在 CODEOWNERS 中定義領域負責人 | 🔄 進行中 |
| **決策記錄** | ADR (Architecture Decision Records) | 🔄 進行中 |
| **知識轉移** | 錄製關鍵系統的說明視頻 | 📅 計劃中 |
**成功指標**:
- [ ] Bus Factor ≥ 2 (至少 2 位活躍維護者)
- [ ] 所有核心模組有備援維護者
- [ ] 100% 關鍵功能有文檔
---
### 風險 2: 功能膨脹 (Feature Creep)
**當前狀態**: ⚠️ 中等風險
**影響**: 維護成本增加，代碼質量下降
**緩解策略**:
| 策略 | 行動 | 狀態 |
|------|------|------|
| **功能矩陣** | 維護 feature-matrix.md | ✅ 已實施 |
| **模組化安裝** | extras: `[mcp]`, `[vector]`, `[gui]` | ✅ 已實施 |
| **插件優先** | 新功能優先作為插件 | ✅ 已實施 |
| **定期審查** | 季度功能審查會議 | 📅 計劃中 |
| **棄用流程** | 明確的功能生命週期 | ✅ 已實施 |
| **覆蓋率門檻** | 新功能必須有 80%+ 測試覆蓋 | ✅ 已實施 |
**功能簡化原則**:
```
┌────────────────────────────┐
│ 新功能提案 │
└─────────────┬──────────────┘
│
┌─────────────▼──────────────┐
│ 是否可以作為插件實現？ │
└─────────────┬──────────────┘
是 │ │ 否
┌─────────▼───┐ ┌───▼─────────┐
│ 創建插件 │ │ 是否核心功能？│
└─────────────┘ └───┬─────────┘
是 │ │ 否
┌───────▼───┐ ┌▼───────────┐
│ 添加到核心 │ │ 拒絕或延後 │
└───────────┘ └────────────┘
```
**成功指標**:
- [ ] 核心依賴 < 15 個
- [ ] 每季度審查並清理 ≥ 1 個實驗性功能
- [ ] 插件佔新功能比例 ≥ 50%
---
### 風險 3: 技術棧強依賴 (Vendor Lock-in)
**當前狀態**: ⚠️ 中等風險
**影響**: 如果依賴的服務變更或停止，項目受影響
**主要依賴風險**:
| 依賴 | 風險等級 | 緩解策略 |
|------|----------|----------|
| `google-genai` (Gemini) | 🟡 中等 | LLM Provider 抽象層 |
| `chromadb` | 🟡 中等 | 可替換向量資料庫介面 |
| `fastmcp` | 🟢 低 | MCP 是開放標準 |
| `sentence-transformers` | 🟢 低 | 可替換 embedding 模型 |
**緩解策略**:
| 策略 | 行動 | 狀態 |
|------|------|------|
| **LLM 抽象** | `src/boring/llm/provider.py` 介面 | ✅ 已實施 |
| **多 Provider** | Gemini, Ollama, OpenAI, Claude | ✅ 已實施 |
| **降級機制** | 功能在依賴不可用時優雅降級 | ✅ 已實施 |
| **本地優先** | 支持完全離線使用 (Ollama) | ✅ 已實施 |
| **可選依賴** | 重型依賴放在 extras 中 | ✅ 已實施 |
**依賴替換矩陣**:
```
┌─────────────────┬─────────────────┬─────────────────┐
│ 當前依賴 │ 替代方案 │ 切換難度 │
├─────────────────┼─────────────────┼─────────────────┤
│ google-genai │ ollama/openai │ 🟢 簡單 │
│ chromadb │ qdrant/milvus │ 🟡 中等 │
│ sentence-trans │ openai embeddings│ 🟡 中等 │
│ fastmcp │ 手動 MCP 實現 │ 🟡 中等 │
│ streamlit │ gradio/flask │ 🟢 簡單 │
│ typer │ click/argparse │ 🔴 困難 │
└─────────────────┴─────────────────┴─────────────────┘
```
**成功指標**:
- [x] 支持 ≥ 3 個 LLM Provider
- [ ] 100% 核心功能可離線運行
- [ ] 每個主要依賴有文檔化的替代方案
---
## 🔄 自動化策略
### 減少人工維護負擔
| 自動化項目 | 工具 | 狀態 |
|------------|------|------|
| 代碼格式化 | `ruff format` | ✅ 已實施 |
| Linting | `ruff check` | ✅ 已實施 |
| 類型檢查 | `mypy` | ✅ 已實施 |
| 測試執行 | `pytest` + GitHub Actions | ✅ 已實施 |
| 依賴更新 | `dependabot` | ✅ 已實施 |
| 依賴審計 | `pip-audit` | ✅ 已實施 |
| 安全掃描 | `bandit` | ✅ 已實施 |
| 文檔生成 | `mkdocs` | ✅ 已實施 |
| 版本發布 | GitHub Actions `publish.yml` | ✅ 已實施 |
| Issue 分類 | GitHub Actions (計劃) | 📅 計劃中 |
| PR 自動合併 | `dependabot-auto-merge.yml` | ✅ 已實施 |
### 質量門檻
```yaml
# 所有 PR 必須通過
quality_gates:
lint: "ruff check . (0 errors)"
format: "ruff format --check (0 changes)"
types: "mypy src/boring/ (0 errors)"
tests: "pytest (100% pass)"
coverage: ">= 50%"
security: "bandit (no high/medium)"
docs: "interrogate >= 80%"
```
---
## 📚 文檔策略
### 降低貢獻門檻
| 文檔類型 | 目標讀者 | 優先級 |
|----------|----------|--------|
| README | 新用戶 | P0 |
| CONTRIBUTING | 新貢獻者 | P0 |
| MAINTAINERS | 潛在維護者 | P0 |
| Architecture | 開發者 | P1 |
| API Reference | 整合開發者 | P1 |
| Tutorials | 學習者 | P2 |
| ADR | 核心團隊 | P2 |
### 雙語維護
- 所有核心文檔提供中英文版本
- 使用 CI 檢查雙語同步
---
## 📅 定期審查清單
### 月度審查
- [ ] 檢查 dependabot PRs
- [ ] 審查新 Issues 和 PRs
- [ ] 更新功能狀態 (如有變更)
### 季度審查
- [ ] 功能矩陣審查 - 標記棄用功能
- [ ] 依賴安全審計
- [ ] 文檔完整性檢查
- [ ] 維護者狀態確認
- [ ] Bus Factor 評估
### 年度審查
- [ ] 主要版本規劃
- [ ] 架構決策回顧
- [ ] 貢獻者感謝與認可
- [ ] 可持續性策略更新
---
## 🎓 知識保存
### 關鍵知識資產
| 知識類型 | 位置 | 負責人 |
|----------|------|--------|
| 架構決策 | `docs/adr/` | @Boring206 |
| API 設計 | `docs/api/` | @Boring206 |
| 配置說明 | `docs/reference/configuration.md` | @Boring206 |
| 故障排除 | `docs/reference/troubleshooting.md` | @Boring206 |
| 變更日誌 | `CHANGELOG.md` | @Boring206 |
### 隱性知識轉化
為防止知識流失，以下隱性知識需要文檔化：
- [ ] MCP 工具設計原則
- [ ] RAG 索引策略決策
- [ ] Brain Manager 資料結構演進
- [ ] 版本發布流程細節
- [ ] 常見 bug 模式和解決方案
---
## 📊 健康指標
### 項目健康儀表板
| 指標 | 目標 | 當前 | 狀態 |
|------|------|------|------|
| Bus Factor | ≥ 2 | 1 | 🟡 |
| 測試覆蓋率 | ≥ 60% | 60% | ✅ |
| 文檔覆蓋率 | ≥ 80% | ~80% | ✅ |
| 開放 Issues | < 50 | ~20 | ✅ |
| PR 響應時間 | < 7 天 | ~2 天 | ✅ |
| 依賴過期數 | 0 | 0 | ✅ |
| 安全漏洞 | 0 高/中 | 0 | ✅ |
| CI 通過率 | 100% | ~99% | ✅ |
---
## 🆘 應急計劃
### 如果主要維護者無法繼續
1. **短期 (1-3 個月)**:
- 社區成員接管 Issue 分類
- Dependabot 自動維護依賴
- CI/CD 持續運行
2. **中期 (3-6 個月)**:
- 招募新維護者 (透過 MAINTAINERS.md)
- 社區投票決定項目方向
3. **長期**:
- 考慮捐贈給基金會 (如 Python Software Foundation)
- 或 Archive 項目並推薦替代方案
### 聯絡方式
緊急情況請聯絡:
- **GitHub Issues**: 公開討論
- **Email**: 見 SECURITY.md
---
*最後更新: 2026-01-12 | 版本: 1.0.0*
