KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA
多 Agent 协作项目：事件响应协作组 — keel 龙骨
Multi-Agent Collaboration 的配套项目：多 Agent 协作项目：事件响应协作组
从一条固定的事件诊断运行开始，逐步把任务契约、Agent 白名单、Ollama Specialist、Supervisor、并行汇聚、Reviewer 和失败策略连起来。先读概念，再运行对应示例；不需要一开始通读全部源码。
准备环境
建议使用 Python 3.11 或更高版本：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r courses/advanced/multi-agent-collaboration/course/project/requirements.txt
真实模型实验还需要本机运行 Ollama：
ollama serve
ollama pull qwen3:8b
$env:OLLAMA_MODEL = "qwen3:8b"
示例会自动把 src 加入导入路径，不需要设置 PYTHONPATH。
按章节运行和观察
第 02/04 章：任务契约和白名单
python courses/advanced/multi-agent-collaboration/course/project/examples/01_task_contract.py
先看 contracts.py，再看 registry.py 和 coordinator.py。把 capability 改成未知值，观察任务如何在执行前失败。
第 03 章：真实 Ollama Specialist
python courses/advanced/multi-agent-collaboration/course/project/examples/02_ollama_specialist.py
这个示例只让模型填写 FindingArtifact。模型不会创建任务、调用工具或修改 TeamRun。输出通过 Pydantic 和 evidence ID 再校验。
第 06 章：两个真实 Ollama Worker
python courses/advanced/multi-agent-collaboration/course/project/examples/07_ollama_team.py
这里把两个不同 capability 的 Ollama Specialist 注册到同一个 Coordinator，并行分析指标和变更证据。模型调用负责产生 Artifact；任务关联、scope、并行上限、结果汇聚和最终状态仍由确定性代码负责。
第 05 章：显式 Handoff
python courses/advanced/multi-agent-collaboration/course/project/examples/06_handoff.py
观察记录中有任务、原所有者、新所有者、原因、工件引用和剩余预算，但没有 credential。交接记录本身不执行任何动作。
第 06 章：并行 Fan-out/Gather
python courses/advanced/multi-agent-collaboration/course/project/examples/03_parallel_team.py
两个 Worker 使用不同延迟，返回顺序可能不同；Coordinator 按 task_id 关联结果。事件只由主线程追加，避免并发写乱序号。
第 08 章：确定性 Review
python courses/advanced/multi-agent-collaboration/course/project/examples/04_review_loop.py
先用代码检查不存在的 evidence ID 和缺失 limitation。能写成确定性规则的约束不必消耗额外模型调用。
第 09 章：部分失败和降级
python courses/advanced/multi-agent-collaboration/course/project/examples/05_failure_recovery.py
$env:DEMO_FAIL_CHANGE = "1"
$env:DEMO_POLICY = "best_effort"
python courses/advanced/multi-agent-collaboration/course/project/examples/03_parallel_team.py
all_required 和 best_effort 会得到不同的运行状态，但成功任务的 Artifact 都应保留下来。
源码阅读顺序
contracts.py 任务、Agent、Artifact、Result、Event、Run
registry.py Agent 白名单和 capability 路由
workers.py 确定性 Worker、领域工件和失败注入
ollama_agent.py Ollama Structured Outputs 适配器
coordinator.py 分派、并行、超时、取消和汇聚
review.py 可写成代码的审查规则
domain.py 固定事件证据和任务构造
复杂的 Coordinator.run_parallel() 可以按四段阅读：
创建 TeamRun
-> 解析 Registry 并提交 Worker
-> 主线程收集并验证 TaskResult
-> 按策略计算最终状态并写事件
测试
python -m unittest discover -s courses/advanced/multi-agent-collaboration/course/project/tests -v
测试固定验证：
- 重复 Agent 和重复 capability 会被拒绝；
- 未知 capability 不会动态创建 Agent；
- TaskResult 必须关联原 task ID 和 Worker；
- 并行结果按 ID 汇聚；
- 必需任务失败会阻止
all_required成功； best_effort保留成功 Artifact 并明确降级；- 取消和任务超时有稳定错误码；
- Ollama 输出必须通过 schema 和 evidence 校验；
- Reviewer 能发现未知证据和缺失限制说明。
目前实现的边界
项目是用于学习的单进程实现：Registry 在内存中，协调器使用线程池，Artifact 没有接入外部对象存储，取消不能强杀已经运行的 Python 线程，也没有分布式 worker lease。
这些不是生产系统可以忽略的问题。进入真实项目时，需要补上持久化任务状态、消息队列、幂等提交、租约、身份传播、远程 Agent 健康检查、脱敏事件存储和独立评估集。