AgentRT-Lite：面向操作系统的多 Agent Runtime

AgentRT-Lite 将 Agent 建模为由 Runtime 管理的执行实体，为任务提供动态 DAG、生命周期、资源准入与核算、Context、独立 Worker、故障恢复、OS 资源控制和可审计持久化。项目使用一个完全离线、确定性的软件修复工作流，展示从任务规划、并行分析、候选修复到验证和报告的完整链路；默认不需要联网、付费服务或真实 LLM API。

最短演示

python -m agentrt demo software-repair

该命令会在临时副本中复现缺陷、由 Planner 原子插入 7 个下游任务、并行分析两个修复候选、执行一次受控故障与有限重试，并以同一测试命令验证“修复前失败、修复后通过”。仓库中的 fixture 不会被修改。

Windows 完整交付验证：

VERIFY_COMPETITION.cmd

它会在系统临时目录运行全量测试、smoke、离线应用和四组实验，并检查资源泄漏、凭证泄漏与仓库污染。openEuler 实机验证必须对同一干净提交依次执行 target 和 full，详见 openEuler 验证手册。

项目状态

项目	当前说明
开发环境	Windows；Python 3.10+
目标环境	openEuler/Linux；Runtime 生产路径仅使用 Python 标准库
Windows 候选验证	2026-07-30：752 项单元测试通过（8 项 Linux 条件测试跳过）；`VERIFY_RELEASE.cmd` 与 `VERIFY_COMPETITION.cmd` 均 PASS
openEuler 实机	尚未对当前候选提交完成 `target/full`；不得标记为 PASS

为什么这是操作系统方向的 Runtime

Agent 是受管执行实体。 每个 Agent 都有 ACB、生命周期、attempt、进程身份、资源所有权、Context 绑定和调度证据，而不是普通库回调。
先准入、后执行。 Runtime 在调度前检查 CPU、内存和模型槽容量，并对 reserve/release、峰值和每次决策进行持久化记账。
独立 Worker 与进程树治理。 每个 attempt 在独立 Worker 进程中执行；Supervisor 识别超时、异常退出和协议错误，并在确认整棵进程树终止后释放所有权。
可选内核强制。 Linux required 模式在请求下发前完成 cgroup v2 配置、附着和读回验证；失败时关闭执行，不静默降级。

核心设计

1. 原子动态 DAG

静态图和动态批次都会拒绝重复任务 ID、缺失依赖、环以及永远无法装入总容量的任务。动态任务先在候选图中完整校验，全部通过后才替换活动图；数据库路径把父任务终态、资源释放、能力撤销、全部子任务与边、Context 继承、幂等记录和 Outbox 放入同一事务，因此动态插入具有全有或全无语义。

2. FIFO / CACS 调度与资源核算

Runtime 支持 --scheduler fifo|cacs。CACS 联合剩余关键路径、Context 驻留亲和度和 aging：

score = 0.55 × critical_path
      + 0.30 × context_affinity
      + 0.15 × aging

每次选择都会记录三个分项、最终分数、可用资源和 Context 逻辑字节证据。CPU/内存/模型槽首先属于 Runtime 领域的准入与记账；Linux cgroup v2 只对 CPU、内存和 PID 实施内核限制，二者不能混为一层。

3. SQLite 权威状态与可审计事件

新 Run 从创建开始以 .agentrt/runs/<run-id>/runtime.db 为唯一权威状态源。workflow.json、state.json 和 events.jsonl 是可删除、可重建的诊断视图；CLI 在数据库存在时直接查询或重算。业务状态与 Transactional Outbox 在同一事务提交，派生快照使用原子替换发布。

ps、tree、trace 和 metrics 均能从 runtime.db 工作。历史 JSON-only M1 Run 仍可只读查看，不会被隐式迁移或补建数据库。

4. ContextSpace 与最小能力凭证

ContextSpace 提供边界隔离、内容寻址 Segment/Blob、不可变 Version DAG，以及 root/fork/append/merge/compact/materialize。相同内容只在相同 tenant/security domain 内复用。每个 attempt 使用至少 256 位随机 bearer token；数据库只保存 SHA-256 digest。

Worker v2 通过 stdin 接收一个有界 UTF-8 JSON envelope。明文 token 不进入 argv、环境变量、SQLite、Outbox、派生视图、指标或实验 CSV；Worker 使用只读数据库连接校验 run、version、subject、scope、expiry 和 revocation 后再 materialize。

5. Supervisor、检查点与恢复

Supervisor 将启动失败、超时、异常退出、协议错误、工具错误和 Context 错误规范化为结构化故障。只有故障码在 allowlist 且未超过 max_retries 时才进行有限重试；checkpoint 只记录 Task 边界的输入版本、TaskSpec digest、attempt 和非敏感结果摘要。

resume 校验数据库、重放 Outbox、重建视图并处理遗留 RUNNING ACB。仍存活的旧进程采用 fail-closed 策略，不会重新附着；确认进程已死后，才按重试预算恢复为 READY 或终结为 FAILED。

6. Linux cgroup v2 强制

每个 attempt 使用独立叶节点：

<cgroup-root>/<run-id>/<task-id>/attempt-<n>

Runtime 先持久化 attempt 和进程身份，再写入并读回验证 cpu.max、memory.max、pids.max，随后通过 cgroup.procs 附着 Worker，最后才释放 stdin 请求。模式语义如下：

off：使用 Noop 后端；
auto：允许明确降级，并持久化降级原因；
required：任何配置、附着或验证失败都在执行前关闭。

Windows Fake backend 只验证事务顺序、生命周期、故障和清理，不等价于真实内核 enforcement。

执行主链路

Workflow / dynamic task batch
        ↓
DAG + ACB + resource admission
        ↓
FIFO / CACS ← immutable Context residency snapshot
        ↓
SQLite transaction: reservation + attempt + capability
        ↓
blocked Worker → process identity → OS enforcement
        ↓
release stdin request
        ↓
Supervisor + checkpoint + finite retry
        ↓
process-tree proof + metrics + cleanup
        ↓
revoke capability + release reservation

完整模块边界见架构说明。

快速开始与观测

python -m agentrt run examples/basic.json --run-id demo-basic --max-workers 2
python -m agentrt ps demo-basic
python -m agentrt tree demo-basic
python -m agentrt trace demo-basic
python -m agentrt metrics demo-basic

动态 DAG 与 CACS 示例：

python -m agentrt run examples/dynamic.json --run-id demo-dynamic --scheduler cacs --max-workers 3 --cpu-units 3 --memory-mb 1024 --model-slots 1

如需显式记录宿主 OS enforcement 的自动选择或降级证据：

python -m agentrt demo software-repair --os-enforcement auto

保留 Runtime 后再检查同一 state root 的正确方式，见软件修复演示说明。

软件修复多 Agent 应用

演示包含 8 个角色：Planner、Repository Analyzer、Test Failure Analyzer、Candidate Patch A、Candidate Patch B、Reviewer、Verifier 和 Final Reporter。Planner 原子插入其余 7 个角色；两个分析分支和两个候选分支可并行执行。一条候选路径触发确定性故障和有限重试，另一条在隔离副本中通过测试，Reviewer 选择后由 Verifier 用相同测试命令验证。

演示输出 JSON 与 Markdown 报告，记录测试前后状态、静态/动态任务数、重试与 checkpoint、Context 请求字节、资源峰值、OOM 事件，以及最终活动 reservation、capability 和 OS-enforcement 计数。

四组正式实验

实验	对照	可以支持的结论	不应声称
调度	FIFO / CACS	在输入受控时，CACS 可优先选择 Context 已驻留任务	CACS 总是更快
Context 传输	inline copy / ContextHandle	Handle 减少 fan-out 请求中的重复 stdin 字节	shared memory、zero-copy 或必然更低延迟
故障恢复	no recovery / retry + checkpoint	在确定性故障下比较成功率、重试和恢复时间	恢复模式一定更快
OS 控制	off / on normal / on over-limit	Linux `required` 可用真实附着、内核 OOM 计数和清理证据验证限制	Windows Fake 等价于内核强制

正式运行分别生成 raw.csv、summary.json 和 report.md，Context 实验另含 workers.csv；失败样本保留在成功率分母中。未生成原始证据前不填写性能数字。详见实验设计。

验证

开发检查：

python scripts/check_workspace.py
python -m unittest discover -s tests -v
python -m compileall -q agentrt benchmarks tests scripts
git diff --check

Windows 发布检查：

VERIFY_RELEASE.cmd
VERIFY_COMPETITION.cmd

openEuler 从 master 的同一干净提交导出并固定完整 SHA：

powershell -ExecutionPolicy Bypass -File scripts/export_openeuler_validation.ps1 -Upload

在 openEuler 终端执行导出器打印的 M4I_REMOTE_BOOTSTRAP_COMMAND，加载它打印的环境文件，然后依次运行：

bash scripts/run_openeuler_validation.sh target
bash scripts/run_openeuler_validation.sh full

只有 M4I_TARGET_VERIFY=PASS 和 M4I_FULL_OPENEULER_VERIFY=PASS 才代表对应阶段通过。Windows 结果不能替代 openEuler cgroup v2 实机证据。

能力边界

ContextHandle 减少重复 stdin 请求字节，但不是 zero-copy、shared memory 或 Unix Socket，也不保证更快。
checkpoint 是 Task 边界元数据，不保存进程内存、模型/token 中间状态；resume 不重新附着运行中的旧 Worker，也不声称透明进程级恢复。
cgroup 是资源强制，不是完整安全沙箱；Context capability 也不等于 SELinux、MAC、OS ACL 或恶意 OS 用户间隔离。
当前未实现 namespace/seccomp 隔离、eBPF、GPU KV Cache、共享内存、多节点、复杂 Web UI 或通用自主编程平台。
默认软件修复演示使用确定性角色逻辑；它验证 Runtime 原语，不声称使用真实 LLM 完成通用代码修复。

文档导航

历史 M1/M2/M3 审计材料保留在 docs/ 中作为演进证据，但不代表当前候选的能力边界或验证状态。