Kylin Agent Runtime —— 面向多智能体的操作系统级执行时

赛题：面向多智能体的操作系统级执行时（Agent Runtime）一句话：给每个 AI 智能体发一张「操作系统工牌」——有身份（APCB）、有工位限额（cgroup）、有看资源派活的调度、有团队共享记忆（KV Cache）、出错只开除一个人不开除全厂（容错隔离）。

1. 🧭 项目导航

本 README 按大赛五维评分组织，评委可按需直达：

章节	内容	对应评分维度
§2 这是什么	解什么题、应用场景	背景
§3 四大 OS 级机制	APCB / 资源感知调度 / KV 共享 / 容错隔离	① 系统设计与机制创新
§4 真实性能数据	全部实测数字与数据来源	③ 性能优化效果
§5 工程实现与质量	模块清单、规模、质量闭环	② 功能完整性与实现深度 ④ 工程实现质量
§6 实验与评测体系	六类实验、数据诚信、PAWBench	⑤ 实验与分析质量
§7 构建运行测试	已验证的复现命令	可复现性

仓库目录：

目录	是什么
`src/os_runtime/`	赛题核心：OS 级执行时控制面（APCB / 调度 / 资源 / 容错 / KV 共享 / 可观测），本届自研
`src/`（agent、gateway 等）	应用层 Agent 框架：基于开源 Hermes-Agent v0.14.0（Nous Research，MIT）适配扩展，为运行时提供真实多 Agent 工作负载
`src/kylin-agent/`	KylinAgent：Qt5 桌面监控前端（C++/CMake），经本地 HTTP/SSE 与运行时对接
`tests/experiments/`	实验脚本 + 冻结原始数据（`results/` 下 JSON 与图表）
`docs/`	四份官方文档 PDF + 技术报告 + 设计文档
`demo/`	可验证演示材料（脚本与视频字幕）
`presentation/`	决赛 PPT 与演示视频

2. 🎯 这是什么——解什么题

现有多 Agent 系统停留在应用层框架：一群智能体像「临时工外包队」，没编制、没工位、各干各的还抢资源。赛题要求把管理下沉到操作系统执行时。

我们交付的 Kylin Agent Runtime 分两层：

**执行时控制面 src/os_runtime/**（本届自研）：把 Agent 当作操作系统的一等公民来管理；
应用层（基于开源 Hermes-Agent v0.14.0 适配扩展）：真实的多 Agent 任务流跑在运行时之上，验证机制有效。

赛题四大痛点与对症机制：

痛点	大白话	对症机制
① 多 Agent 无统一调度	一群人抢一台电脑，互相拖累	资源感知调度（§3-②）
② KV Cache 冗余拷贝	5 个人各自把同一本手册从头背 5 遍	KV 前缀共享（§3-③）
③ 缺统一执行抽象	模型/工具/资源各管各的，一盘散沙	APCB + 六态状态机（§3-①）
④ 缺系统级容错与可观测	一个出错全体瘫痪，出了问题两眼一抹黑	容错隔离 + 可观测（§3-④）

应用场景：软件工程多智能体协作（需求→架构→编码→测试→验收）、批量 Agent 任务执行、端侧 AI 助手监控。

3. ⚡ 四大 OS 级机制

对应评分维度：① 系统设计与机制创新

   ┌───────────────────────────┐          ┌───────────────────────────┐
   │     调度节点（本仓库主体）   │          │      GPU 推理节点          │
   │  APCB + 六态状态机          │  HTTP    │  vLLM 推理引擎             │
   │  资源感知调度器（psutil+     │ ───────► │  APC 前缀缓存              │
   │    cgroup 内核级配额）      │ ◄─────── │  radix tree 前缀匹配       │
   │  容错熔断 + 可观测           │  KV 共享  │                           │
   │  KylinAgent（Qt5 前端）     │          └───────────────────────────┘
   └───────────────────────────┘

调度与推理分离，运行时统一编排本地 CPU 与远程 GPU——正是操作系统调度异构资源的思路。

① APCB —— Agent 进程控制块（统一执行抽象）

对标 OS 的 task_struct。每个 Agent 持有 APCB：身份、六态状态机（CREATED→READY→RUNNING→BLOCKED→TERMINATED/FAILED）、资源配额、任务依赖、生命周期回调。状态转换严格校验，非法跳转执行前拦截。代码：src/os_runtime/apcb.py、state_machine.py。

② 资源感知调度 —— 看资源派活

对标 Linux CFS。调度器实时读取 psutil 负载与 cgroup 内核级配额，按系统容量分批派发；资源紧张时多余任务排队而非全量并发（避免过载雪崩）。支持 DAG 依赖、动态子任务生成。代码：src/os_runtime/scheduler.py、resource_manager.py。

③ KV Cache 共享 —— 团队只背一本手册

对标共享内存。多 Agent 共享同一前缀（系统指令/工具定义/代码规范），KVScheduler 统一调度到 vLLM，radix tree 前缀匹配复用已算好的 KV Cache——先到者算前缀，后来者直接用，省去重复 prefill。代码：src/os_runtime/kv_scheduler/。

④ 容错隔离 —— 一个出错不开除全厂

对标进程隔离。双重隔离：进程级（start_new_session 独立会话）+ 资源级（cgroup 限额）。故障 Agent 被熔断为 FAILED、调度器不再选中，不级联拖垮全局；支持 BLOCKED→反馈→重派→复审 的恢复闭环。配套可观测模块实时暴露运行状态。代码：src/os_runtime/fault_tolerance.py、observer/。

4. 📊 真实性能数据

对应评分维度：③ 性能优化效果。全部为实测，非模拟；原始 JSON 见 tests/experiments/results/，逐项来源标注在表后。

实验	对比（基线 → 本系统）	提升
调度·常规并发	吞吐 22.801 → 39.698 任务/s	1.74×
调度·过载恢复	吞吐 1.428 → 9.973 任务/s	6.98×
调度·平均等待	700.76 → 251.00 ms	−64.2%
容错·含故障场景	makespan 优化	2.25×–2.4×
容错·熔断速度	注入 3 故障：3/3 全部隔离、0/3 正常任务受拖累、平均 0.301 s 完成隔离	故障边界成立
KV 共享（真实 vLLM，30B 模型 / L40s GPU）	TTFT 110.86 / 107.90 ms（两轮基线）→ 38.11 ms（APC 开启）	2.91×
cgroup 内核级硬限额（真实 cgroup v2）	CPU 限流生效 46.0%（111 个周期中 103 次节流）；内存超限触发 OOM kill	硬限额真实生效
端到端 E2E（1 root + 5 worker + 1 故障注入）	4/4 正常完成、1/1 故障隔离、KV 命中率 75%、节省 1,107 token	全机制协同

数据来源：调度 = results/benchmark_aggregate.json（5 轮配对）；容错 = results/fault_summary_*.json；cgroup = results/cgroup_real_test.json；vLLM = results/vllm_apc_summary_*.json；E2E = results/e2e_demo_summary.json。

5. 🏗️ 工程实现与质量

对应评分维度：② 功能完整性与实现深度、④ 工程实现质量

执行时模块清单（src/os_runtime/，生产代码 14,657 行 + 测试 5,741 行）：

模块	职责
`apcb.py` + `state_machine.py`	Agent 控制块与六态状态机
`scheduler.py`	资源感知调度（容量分批、DAG、吞吐统计）
`resource_manager.py`	psutil 采集 + cgroup v2 限额
`fault_tolerance.py`	熔断隔离与恢复闭环
`kv_scheduler/`	KV 共享调度（radix tree + vLLM 适配）
`ipc/`	Agent 间通信
`observer/`	可观测（状态导出与 dashboard 数据源）
`adapters/` + `registry.py`	与应用层框架的接入适配与注册

质量闭环：接口约定（src/os_runtime/接口约定.md）→ 设计确认记录 → 实现 → 单元测试 148/148 通过（26.82 s）→ 基准实验 → 冻结数据归档，每一步产物都在仓库内可查。

应用层与前端：Hermes-Agent 适配扩展（src/agent 等）+ KylinAgent Qt5 前端（src/kylin-agent/，实时监控与 SSE 流式对接）。全仓 Python 文件 1,908 个、约 21.6 万行。

6. 🧪 实验与评测体系

对应评分维度：⑤ 实验与分析质量

层级	实验	结果
单元	`pytest src/os_runtime`	148/148 通过
调度	`scheduling_benchmark.py`（5 轮配对）	1.74× / 6.98× / −64.2%
容错	`fault_experiment.py`（故障注入）	2.25×–2.4× / 0.301 s / 3/3 隔离
资源	`cgroup_real_test.py`（内核级）	46.0% 限流 / OOM kill
推理	`vllm_apc_benchmark.py`（真实 GPU）	TTFT 2.91×
端到端	`e2e_demo.py`（全机制协同）	4/4 + 1/1 + 75% + 1,107 token

数据诚信：所有数字可由 tests/experiments/ 下同名脚本复现，原始 JSON 冻结在 results/；无 GPU 环境的降级演示数据明确隔离在 results/mock/，不与真实数据混用。

任务级评测（PAWBench）：本系统 74.21 分（101/150）。对比：Hermes-Agent 基线 70.66（+3.55）、Hermes 最新版 69.56（+4.65）；与同场最强队伍 QwenPaw（73.75）差 0.46 分，处于波动区间内，我们不据此宣称任务能力占优——系统层收益（上表）才是本工作的主要贡献。

7. 🚀 构建、运行与测试

对应评分维度：可复现性。以下命令均在本仓库实测通过。

环境：openKylin / Ubuntu 等通用 Linux；Python 3.11+；pip install psutil 即可运行调度/容错/E2E。Qt5 前端与 GPU vLLM 为可选（无 GPU 时 KV 部分自动降级为 mock 命中统计）。

台阶一：30 秒看懂（无需 GPU）

cd tests/experiments
python e2e_demo.py          # 端到端：调度+KV+容错三模块协同，输出摘要 JSON
python demo_workflow.py     # 完整任务流：DAG 提交、分批派发、六态流转、故障熔断
python e2e_demo_viz.py      # 可视化：多 Agent 协作 + dashboard

台阶二：复现冻结数据

cd tests/experiments
python scheduling_benchmark.py       # 调度 1.74× / 6.98× / −64.2%
python fault_experiment.py           # 容错 2.25×–2.4× / 0.301s
sudo python cgroup_real_test.py      # cgroup 内核级硬限额（需 root）
python vllm_apc_benchmark.py         # KV/TTFT 2.91×（需 GPU + vLLM）

台阶三：测试与前端

python -m pytest -o addopts='' src/os_runtime -q      # 148 passed
cd src/kylin-agent && mkdir -p build && cd build && cmake .. && make -j$(nproc)

📄 更多文档与分工

docs/项目说明书.pdf / docs/项目创新说明.pdf / docs/人工智能及第三方工具使用说明.pdf / docs/技术报告.md
成员分工与主要贡献：见 docs/成员分工及主要贡献说明.pdf（按大赛要求以 A/B/C 匿名表述）

License

MIT，见 LICENSE。