Collègue

Collègue MCP

🇫🇷 法语版本 | 🇬🇧 English version

一个由 专业 AI 专家组成的团队，以 MCP（Model Context Protocol）服务的形式提供。每个工具都是所在领域的专家 Agent，涵盖代码分析、重构、测试、安全和架构；它们通过自动委派、持久化记忆和主动监控系统协同工作。

---

🚀 快速开始（Docker）

git clone https://github.com/VynoDePal/Collegue.git
cd Collegue
cp .env.example .env   # renseigner LLM_API_KEY (Gemini)
docker compose up -d

端点：

URL	角色
http://localhost:4121/mcp/	MCP 服务（HTTP 传输）
http://localhost:4122/_health	健康检查

网络：默认使用 loopback。 docker compose up 会将所有端口发布到 127.0.0.1 （MCP 4121、健康检查 4122、Keycloak 4123、仪表板 4125、nginx 8088）：无法从网络访问。 服务在容器内部监听 0.0.0.0；只有主机端的端口发布受到限制。可通过三个独立变量（在 .env 中）更改发布地址：

变量	涉及的端口
COLLEGUE_PUBLISH_HOST	MCP 4121、健康检查 4122、nginx 8088
COLLEGUE_DASHBOARD_PUBLISH_HOST	Streamlit 仪表板 4125（无身份验证）
COLLEGUE_KEYCLOAK_PUBLISH_HOST	Keycloak 4123（start-dev，切勿直接对外暴露）

远程暴露（例如 COLLEGUE_PUBLISH_HOST=0.0.0.0）：这是明确的选择，仅应在 OAUTH_ENABLED=true 时使用。 这不是强制要求：如果未启用 OAuth，服务只会记录警告，仍可在无身份验证的情况下访问。暴露 MCP 不会开放仪表板或 Keycloak。仍建议使用 TLS 反向代理。

OAuth fail-closed。 当 OAUTH_ENABLED=true 时，如果无法建立身份验证（缺少 JWTVerifier、构造函数出错、 OAUTH_JWKS_URI 和 OAUTH_PUBLIC_KEY 均未设置，或 OAUTH_ISSUER 或 OAUTH_ALGORITHM 为空），服务将拒绝启动， 容器以非零代码退出（Compose 会根据 restart: always 重新启动：请查看日志）。只有通过明确设置并记录的 OAUTH_ENABLED=false（默认值），才能使用无身份验证模式。 每个令牌都会实际应用 OAUTH_ALGORITHM 和 OAUTH_REQUIRED_SCOPES：缺少已配置作用域的令牌将被拒绝（更新前请检查令牌）。 在 Docker 之外，HOST 现在默认为 127.0.0.1。

配置 IDE

Claude Code（CLI）

claude mcp add --transport http collegue http://localhost:4121/mcp/

Windsurf / Cursor / Antigravity

{
  "mcpServers": {
    "collegue": {
      "serverUrl": "http://localhost:4121/mcp/"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "collegue": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4121/mcp/"]
    }
  }
}

stdio 模式（临时启动容器）

{
  "mcpServers": {
    "collegue": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "LLM_API_KEY=votre_clé_gemini",
        "collegue-mcp"
      ]
    }
  }
}

本地构建镜像：docker build -f docker/collegue/Dockerfile -t collegue-mcp .

---

✨ 10 位 AI 专家

每位专家都使用大模型，通过Agent 循环不断迭代，并可委派任务给其他专家。

专家	描述
Code Review	质量、命名、复杂度、安全、DRY、SOLID
Architecture Analysis	模式、依赖、循环、耦合、技术债务
Performance Analysis	O(n²)、阻塞 I/O、循环拼接、性能热点
Code Refactoring	重构结构、优化、验证 AST、比较指标
Test Generation	可执行的单元测试（pytest、jest、phpunit）
Code Documentation	文档字符串、技术文档、覆盖率
IaC Guardrails Scan	Terraform、Kubernetes、Dockerfile 安全
Impact Analysis	变更前的预测性风险分析
Repo Consistency Check	未使用的导入、死代码、重复代码
Smart Orchestrator	规划并协调多位专家

其他工具

类别	工具
静态	Dependency Guard、Secret Scan、Run Tests
集成	PostgreSQL、GitHub、Sentry、Kubernetes

---

🤖 多 Agent 系统

┌─────────────────────────────────────────────────────┐
│                 Collègue MCP Server                   │
│                                                     │
│  Code Review ─── Architecture ─── Performance       │
│       │               │               │             │
│  Refactoring ─── Test Gen ─── Documentation         │
│       │               │               │             │
│  IaC Scan ─── Consistency ─── Impact Analysis       │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ Délégation · Mémoire · Monitor · Dashboard   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

组件	作用
Agent 循环	执行 → 验证 → 修正 → 重新执行，直到收敛
委派	14 条自动规则（例如：如果评分 < 0.5，则将 code_review → refactoring）
记忆	将结果存储在 .collegue/memory/ 中，供未来会话使用
监视器	检测已修改的文件并触发相关专家
仪表板	汇总项目健康评分

---

🔑 配置

环境变量（.env）

按主题概览（完整列表和默认值见 .env.example）：

变量	描述	必需
LLM_API_KEY	LLM 提供商的 API 密钥（默认使用 Gemini）	✓
LLM_PROVIDER / LLM_MODEL	默认 LLM 提供商和模型
LLM_MODEL_* / LLM_PROVIDER_*	按角色指定的模型/提供商（CODER、QA、PLANNER、REVIEWER）
LLM_RATE_LIMIT_*	每个客户端的 LLM 调用限制（分钟 / 天）
CACHE_ENABLED / CACHE_TTL	工具响应缓存
OAUTH_ENABLED（以及 OAUTH_*、Keycloak）	OAuth 身份验证（默认关闭；启用后采用失败关闭策略：见上文“网络”）
COLLEGUE_PUBLISH_HOST / COLLEGUE_DASHBOARD_PUBLISH_HOST / COLLEGUE_KEYCLOAK_PUBLISH_HOST	Docker 端口发布地址（默认 127.0.0.1）
GITHUB_TOKEN / GITHUB_OWNER / GITHUB_REPO	GitHub 集成（监视程序、PR）
SENTRY_DSN / SENTRY_ENVIRONMENT	Sentry 可观测性
STATE_DATABASE_URL	自主引擎的持久状态（Postgres/SQLite）
MAX_COST_USD / MAX_TOKENS_BUDGET / COLLEGUE_RUN_DEADLINE_SECONDS	运行上限，由持久预算注册表执行（规划、BUILD、IMPROVE、重试）；达到上限时暂停
BUDGET_MODE	strict（默认：在框架发出的每次调用之前预留预算；用量未知时持久阻止）或 advisory（记录但不阻止，不作任何保证）。保证适用于框架发出的调用，而非拥有密钥的工作区程序：见 w2-budget（接受和拒绝的传输方式）
COLLEGUE_HOME	持久化根目录（指标、检查点、可修改的提示词；首次启动时会接续上一次安装中的提示词状态，见 w2-installation）
CODER_SUBSCRIPTION（以及 CODER_SUBSCRIPTION_MODEL、SANDBOX_SUBSCRIPTION_AUTH_DIR）	使用 ChatGPT/Codex 订阅进行编码（API 成本为 $0），无需密钥
BUILD_AUTO_MERGE	构建阶段的合并机器人（自动合并任务 PR；默认关闭，需显式启用）。仅在有持久交付证据、必需检查通过、基准未变化且严格保护确实适用时才会合并（w3-merge）。与 Phase 5 不同	false
GATE_ACCEPTANCE_TESTS	QA 角色在计划时生成的 pytest 判定器，与计划一起封存，然后在不使用 LLM 的情况下重新运行（默认关闭）
SANDBOX_NETWORK / SANDBOX_MEMORY / SANDBOX_CPUS / SANDBOX_TIMEOUT	coder 容器的网络和资源
AUTO_MERGE_ENABLED / AUTO_REVERT_ENABLED / PILOT_TOOL_ENABLED	受风险门控的自主能力（选择启用，默认关闭）

自主引擎的详细设置（预算、自动合并/还原、试点 MCP 工具）： docs/moteur_autonome.md。

---

🧭 自主开发引擎

除了响应式专家之外，Collègue 还可以端到端驱动开发：规划 → 编码 → 测试 → 开启 PR，并在预算内以 GitHub 为基础。阶段：planner → pilote → executor → improve，依托持久化状态（Postgres/SQLite）和 Docker 沙箱。

默认安全：除非传入 --execute，否则运行始终处于 dry_run（不进行任何写入）；plan draft 只会持久化其草稿；操作员随后批准显示的哈希，只有 plan sync --execute 会触及 GitHub； 预算以 strict 模式持久化（达到上限或用量未知时暂停；不可限定用量的传输会被拒绝，而非假装可控）。在真实 BUILD 中，merge-bot（选择启用：BUILD_AUTO_MERGE，默认关闭）可在交付证据通过验证后自动合并每项任务，以构建 MVP；默认情况下，改进阶段会将 PR 保持开启，等待人工合并（§6）。Phase 5 的风险门控自动合并已真正接通，但仍需选择启用：必须满足 CI 全部通过、SHA 稳定、重新同步以及 main 健康状况良好。如果健康状况恶化且启用了 AUTO_REVERT_ENABLED，系统会发布一个精确恢复到先前树状态的提交，通过 CI 验证，在 SHA 守卫下合并，然后再进行最后一次检查。合并前写入的持久化事务可在崩溃后恢复，且不会重复合并或回滚。回滚会在 workers 之间使用 CAS lease，并保持 recovered 状态，直到人工确认（phase5 show/ack），以防同一变更被反复提议。整套机制仍然默认禁用，并采用故障关闭策略。 编码器可以通过 ChatGPT/Codex 订阅运行（API 成本 $0）。

# Phase 1 : trois gestes séparés — le processus LLM ne s'auto-approuve jamais
python -m collegue.pilot plan draft --name app --problem "..." --owner org --repo app --base main
python -m collegue.pilot plan approve --project-id 1 --expected-plan-hash SHA256_AFFICHE
python -m collegue.pilot plan sync --project-id 1 --execute

# Build : aperçu (dry_run) puis exécution réelle
python -m collegue.pilot --project-id 1 --repo-source /chemin/clone --owner org --repo app
python -m collegue.pilot ... --execute            # écritures réelles (PR + état)
python -m collegue.pilot ... --execute --improve  # + cycle d'amélioration

MVP 实际完成合并并重新同步到 origin/<base> 后，--improve 会接着运行持续改进循环（Phase 4）：确定性的质量目标（覆盖率 − 安全性 − lint − 复杂度，不采用 LLM 意见）仅在差异有所改进且没有退步时才开启 PR（故障关闭门控）；PR 会堆叠，并在达到平台期时停止。如果最后一个 BUILD PR 尚未合并，或 git 重新同步失败，Phase 4 就会受阻，而不会产生虚假的 completed 成功状态。

架构、改进循环、防护措施、可观测性/审计、崩溃后恢复和配置：docs/moteur_autonome.md。

---

🤖 Agent Watchdog（自愈）

监控 Sentry，并自动生成 GitHub PR 来修复错误。

Sentry (erreurs) → Watchdog (analyse) → LLM (fix) → GitHub (PR)

部署说明请参见 docs/watchdog_deployment.md。

---

📚 文档

文档	描述
用户指南	安装、配置、入门和最佳实践
集成指南	集成 Claude Desktop、Cursor、Windsurf、CI/CD
专家参考	各专家的参数、输出和使用场景
多 Agent 系统	技术架构、委派和记忆
自主开发引擎	自主驱动器：架构、持续改进（Phase 4）、防护措施、审计、恢复和配置
LLM 评估	LLM 输出质量基准测试
速率限制	配额和限制

---

🛠️ 开发

python -m venv .venv && source .venv/bin/activate
pip install --require-hashes --no-deps -r locks/dev.txt   # dépendances verrouillées et hachées (outils de test inclus)
python -m collegue.migrations upgrade                      # schéma de l'état durable (STATE_DATABASE_URL)
python -m collegue.app

pyproject.toml 是依赖项的唯一来源；locks/*.txt 文件由其生成 （python scripts/locks.py，参见 w2-installation）。软件包包含自身的 资源（skills、提示词种子、迁移文件）：从 wheel 安装后，即使不在仓库中也能运行。

测试：

python -m pytest --tb=short -q
ruff check collegue tests