Symphony Agent Runtime

面向多智能体的操作系统级执行时（Agent Runtime），用于操作系统开源创新大赛高校赛题。 项目将 Agent 任务建模为操作系统级可调度对象，统一管理任务依赖、生命周期、资源准入、进程监督、上下文、通信、故障恢复和系统级可观测性。

参赛信息

• 作品名称：Symphony：面向多 Agent 的操作系统级执行时
• 参赛队伍：进京赶考队

1. 为什么需要 Agent Runtime

现有多 Agent 应用通常由 Workflow、Graph 或协程队列负责编排，缺少统一的运行时控制面，容易出现：

• Agent 任务没有统一调度，依赖、优先级、截止时间和资源竞争相互脱节。
• 多个 Agent 重复复制上下文，大对象通信和上下文构建开销随并发度增加。
• 模型、工具和操作系统资源缺少统一授权边界。
• Worker 崩溃、超时和重启可能造成状态丢失或副作用重复执行。
• 任务状态、调度理由、资源观测和恢复过程无法形成可重放的证据链。

Symphony 的核心思路是把“应用编排”和“Runtime 控制”分离：应用 Agent 通过 Adapter 接入，Runtime 保留任务状态机、DAG、调度、Supervisor、策略和事件事实源的控制权。

2. 面向赛题的能力映射

赛题要求	本项目对应能力	当前状态
Linux 系统运行	Python 用户态 Runtime，能力驱动的 cgroup、沙箱和 GPU 后端选择	已实现，强制隔离需在目标 Linux 环境验收
多 Agent 统一建模	API v1 的 Task、Agent、DAG、Event、Resource、Run 契约	已实现
任务依赖与动态任务	静态 DAG 校验、循环检测、就绪唤醒、失败传播、spawn/join 和配额	已实现并有离线回归
资源感知调度	优先级、deadline、aging、公平性、资源准入和 Cache-Aware Scheduler	已实现，原生 KV 局部性只接受 vLLM /metrics
生命周期与故障隔离	每次 Attempt 独立 Worker 进程、心跳/退出观察、有限重试、超时和进程树回收	已实现
上下文复用与隔离	Context Capsule、内容寻址、ACL、Copy-on-Write、引用生命周期和 Artifact Handle	已实现，不等同于模型 KV Cache
Agent 间通信	有界 Mailbox、request/reply、claim lease、背压、重投和 Artifact/Capsule Handle	已实现
操作前安全控制	Operation Policy Gateway、确认流程、Effect Ledger 和幂等恢复	已实现
复杂应用场景	多角色软件修复流水线、固定离线仓库夹具、Mock/Replay/Qwen Adapter	Runtime 工程闭环已实现，模型质量不作默认结论
系统级可观测性	SQLite StateStore、结构化事件、REST/SSE、CLI 和 MVP Dashboard	已实现

本项目不修改 Linux 内核，也不在 Runtime 内实现 token 级推理调度。vLLM/SGLang 属于可接入的模型后端，Agent 任务调度仍由 Symphony 负责。

3. 总体架构

CLI / REST / SSE / MVP Dashboard
                |
          API Facade + Bundle Validator
                |
      Runtime-owned StateStore + DAG
                |
          Scheduler + Event Log
                |
        Supervisor + Worker Launcher
          |          |          |
       Adapter   ResourceScope  Sandbox
          |
  Mock / Replay / Legacy LangGraph / Model / Repair Agents

  Mailbox + Artifact Store + Context Capsule
  Operation Policy Gateway + Effect Ledger

Runtime 采用单一控制责任边界：状态机负责状态转换，Scheduler 负责派发，Supervisor 负责 Worker 生命周期，StateStore 保存权威状态，Event Log 保存可观察事实。Adapter 只能消费 Runtime 派发的任务并返回结构化结果，不能自行修改全局状态、重试任务或绕过策略网关。

4. 核心模块

• competition_runtime/runtime.py：Runtime 控制循环、任务状态、动态 DAG、恢复和完成屏障。
• competition_runtime/storage.py、migrations.py：SQLite 持久化、幂等键、Controller Lease、fencing 和事件/发件箱状态。
• competition_runtime/dag.py、scheduler.py：依赖图、资源准入、优先级、aging、deadline、公平性和 Cache-Aware 放置。
• competition_runtime/supervisor.py、worker_launcher.py：独立 Worker 进程、心跳、退出状态、超时、重试和进程树回收。
• competition_runtime/resource_scope.py、sandbox.py、linux_capabilities.py：cgroup v2、Bubblewrap 和 Linux 能力探测，能力不足时显式降级或 fail closed。
• competition_runtime/mailbox.py、artifacts.py：有界 IPC、投递租约、背压、Artifact Handle 和大对象传递。
• competition_runtime/contexts.py：Context Capsule 的 ACL、COW、内容完整性、引用与恢复。
• competition_runtime/policy.py、effects.py：操作前授权、确认/拒绝和副作用幂等账本。
• competition_runtime/model_adapters.py、api_models.py：Mock、Replay、Qwen API、Transformers/vLLM Adapter 及预算控制。
• competition_runtime/repair_pipeline.py、repair_agents.py、repair_executors.py：确定性软件修复夹具、Agent 角色和 B0/B1/B2/B3 工程执行模式。
• competition_runtime/service.py、mvp_service.py、cli.py：REST/SSE 服务、本地 MVP 和机器可读 CLI。
• specs.py：兼容旧 Symphony 执行层的任务、状态和资源契约。

根目录的 config.py、outer.py、task_runtime.py、execute_graph.py 等旧模块保留为 Legacy/Baseline 兼容路径。比赛核心控制面位于 competition_runtime/，旧入口需要外部模型和额外依赖，不是默认离线演示入口。

5. 快速开始

5.1 环境

推荐 Python 3.11 和 Linux。默认离线 Runtime 只需要本仓库列出的 Python 依赖，不需要创建 .env。

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

Conda 用户也可以使用：

conda env create -f environment.yml
conda activate symphony

5.2 测试

python -m pytest -q

测试覆盖契约、DAG、Scheduler、Supervisor、持久化恢复、动态任务、Mailbox、Artifact、Policy Gateway、Effect Ledger、ResourceScope、Context Capsule、模型 Adapter、修复流水线和 Dashboard API。需要 Conda 环境、真实 GPU 或付费 Qwen API 的测试会显式跳过，不会偷偷发起外部请求。

5.3 离线 CLI Demo

STATE_DIR="$(mktemp -d /tmp/symphony-runtime.XXXXXX)"
python -m competition_runtime.cli --state-dir "$STATE_DIR" \
  demo --scenario success

可用场景包括：

python -m competition_runtime.cli --state-dir "$STATE_DIR" demo --scenario retry
python -m competition_runtime.cli --state-dir "$STATE_DIR" demo --scenario dynamic
python -m competition_runtime.cli --state-dir "$STATE_DIR" demo --scenario resource
python -m competition_runtime.cli --state-dir "$STATE_DIR" demo --scenario aging

也可以直接提交 Task Bundle：

python -m competition_runtime.cli --state-dir "$STATE_DIR" \
  submit --file examples/mock_repair_success.json

submit 输出包含 run_id。使用 query 查看状态，使用 events 查看结构化事件：

python -m competition_runtime.cli --state-dir "$STATE_DIR" \
  query --run-id <run_id>
python -m competition_runtime.cli --state-dir "$STATE_DIR" \
  events --run-id <run_id>

5.4 持久化恢复 Demo

STATE_DIR="$(mktemp -d /tmp/symphony-recovery.XXXXXX)"
python -m competition_runtime.cli --state-dir "$STATE_DIR" submit \
  --file examples/mock_repair_success.json --defer-execution
RUN_ID="$(STATE_DIR="$STATE_DIR" python -c 'import os; from competition_runtime.storage import StateStore; print(StateStore(os.environ["STATE_DIR"]).nonterminal_run_ids()[0])')"
python -m competition_runtime.cli --state-dir "$STATE_DIR" resume --run-id "$RUN_ID"
python -m competition_runtime.cli --state-dir "$STATE_DIR" events --run-id "$RUN_ID"

同一个 idempotency_key 与同一份规范化 Bundle 会复用原 Run，同一个 key 搭配不同正文会被拒绝。

6. 服务和可视化演示

只启动 REST/SSE 服务：

STATE_DIR="$(mktemp -d /tmp/symphony-service.XXXXXX)"
python scripts/run_competition_service.py --state-dir "$STATE_DIR" \
  --host 127.0.0.1 --port 8080

启动包含后端和 React Dashboard 的 MVP：

MVP_PORT=8080 scripts/run_mvp.sh

浏览器访问 http://127.0.0.1:8080/。Dashboard 使用同一 StateStore 和 Event Log。真实 GPU 不可用时切换到明确标注的 Mock 模式。Cache Demo 的合成数据只用于说明调度逻辑，不是 vLLM 原生 KV 证据。

前端独立开发和检查命令见 frontend/README.md：

cd frontend
npm ci
npm run typecheck
npm run lint
npm run build

7. 可复现的工程演示

下面的脚本不要求外部模型，可用于答辩时展示不同 Runtime 机制：

python scripts/demo_p1c_reliability.py --scenario controller
python scripts/demo_p1d_mailbox.py request-reply
python scripts/demo_p1e.py all
python scripts/demo_p2a.py probe
python scripts/demo_p2c_context.py all

软件修复场景支持 Mock/Replay，例如：

STATE_DIR="$(mktemp -d /tmp/symphony-repair.XXXXXX)"
WORKSPACE_DIR="$(mktemp -d /tmp/symphony-work.XXXXXX)"
python scripts/run_p3a_repair_demo.py \
  --state-dir "$STATE_DIR" \
  --workspace-root "$WORKSPACE_DIR" \
  --benchmark single-file-logic \
  --backend mock

真实 Qwen API、模型下载、vLLM 和 GPU 验收都需要显式配置、预算和环境检查。

8. 关键设计边界与诚实的实验口径

1. 上下文与 KV Cache 分开计量。 Context Capsule 的逻辑/物理字节、Prompt Token 数、API usage 都不能冒充 GPU/KV 命中。原生 KV 结论只接受本地 vLLM /metrics 等后端原生观测。
2. 资源声明与内核强制分开。 没有 cgroup 委派、namespace 或 Bubblewrap 能力时，Runtime 会记录观测/降级原因。代码存在不等于当前机器已经通过强制隔离验收。
3. Mock 结果与模型质量分开。 Mock/Replay 用于验证状态机、调度、通信、恢复和安全边界。不能用于宣称真实模型修复成功率或推理性能。
4. 重建数据分开。 benchmarks/ 中的作者查询池和重建任务仅用于兼容性/工程测试。
5. 控制点而非 token 抢占。 Runtime 在 Agent step、模型/工具调用和 IPC 等控制点调度，不中断正在进行的模型 token 解码或已发生的外部副作用。

9. 安全与开源边界

• 只提交 .env.example，不要提交 .env、.secrets/、API Key、Cookie、浏览器 Profile、执行数据库、模型权重、运行日志、下载数据或实验结果。
• 所有副作用操作应先经过 OperationPolicyGateway。输出过滤不能替代执行前授权。
• 默认服务绑定回环地址，Dashboard 不展示 Prompt、隐藏推理、凭据或本机 Workspace 路径。

10. 目录结构

competition_runtime/       Runtime 控制面与比赛核心实现
scripts/                   CLI、服务、离线 Demo 和环境验收脚本
tests/                     Python 单元/集成回归
examples/                  Mock Task Bundle 和策略场景
frontend/                  React + TypeScript Dashboard
benchmarks/                Smoke 与重建评测资源
docs/competition/          比赛方案、接口、MVP 和 Linux 验收说明
specs.py                   Task/Status/Resource 兼容契约
requirements*.txt          Python 依赖配置
environment.yml            Conda 环境定义