RSIAgent
源码与论文技术学习文档

01论文定义与核心机制

论文关注新数字环境中的适应：预训练模型可能缺少某个软件环境的具体操作规律、隐藏约束与失败模式。RSIAgent 不通过更新模型权重解决，而是让 Agent 在环境中获得经验、验证结果并把环境特定知识保存在持久记忆中。

用两个表达式区分执行与学习

对已有 Agent 开发经验的人，最值得学习的部分是经验提交边界、独立验证、状态机与可追溯运行记录。把模型换强只是其中一个变量；这个仓库展示了如何组织模型外部的运行系统。

依据：README.md · docs/ARCHITECTURE.md · explore/charter.py · 论文第 3 页

02三个角色与四类状态

不要把所有东西都塞进一个对话历史

一个具体收益：验证者不需要相信执行者“我已经修好了”的描述，而是打开实际文件、读取持久状态或检查画面。上下文隔离降低同一个错误解释在多个角色之间直接传递的机会，但模型仍可能产生相似错误。

依据：core/verifier.py · core/self_evolving_loop.py · explore/unified_evolution.py · 论文第 20 页

03从入口到冻结评估的完整流程

论文有两个探索阶段；代码把最终记忆复用也单独编排，所以运行时是三个 Phase。官方基线已经包含 Actor–Verifier 机制，比较“有无 RSI”时不能把基线误认为只调用一次模型。

流程示意。BRS 自身可以继续下一波；DRS 的练习循环返回目标尝试。图中不把“预算用尽”“停滞”画成成功，它们需要分别记录。

04BRS：并行工作，顺序学习

evolve_parallel_phase1() 是最值得逐行阅读的模块之一。Curriculum 一次发布一波项目和输入材料；宿主保存当前记忆快照，所有分支从这一版本出发。每个分支在自己的环境中执行并取得有效验证结果。

snapshot = copy(canonical_memory)
projects = curriculum.author_wave(target, snapshot, previous_outcomes)
branches = parallel_execute_and_verify(projects, snapshot)

require_all_branches_have_grounded_verdicts(branches)
for branch in curriculum_authored_order(branches):
    restore_latest_memory_to(branch.environment)
    resume_same_actor_context(branch)
    distill(branch.verdict, branch.evidence)
    reconcile_entire_memory()
    validate_and_commit_memory()

# 只有整波结束，才判断是否继续下一波或到达预算边界。

为什么不能直接合并四个目录？

假设 A 学到了新的导出命令，B 发现旧命令在某版本失效。若简单合并文件，同名文件可能覆盖，冲突规则可能同时存在。当前实现让 B 的原 Actor 读取 A 已提交的新记忆，再依据 B 的执行证据修订整个记忆库。合并的对象是知识含义，不只是文件差异。

依据：explore/phase1_wave.py · explore/phase1_wave.py · benchmarks/ale/learning.py

05DRS：把失败和脆弱成功变成练习

默认 DRS 先实际尝试目标。Actor 得到明确的 PASS 或 FAIL 后，在原上下文中学习；Curriculum 再根据结果、学习诊断和当前记忆选择后续项目。练习完成后必须重新尝试目标，先前的 PASS 不能证明新记忆下的目标仍然成功。

交互示例：相同的 PASS，会走向不同的后续状态

run_self_evolving_loop() 通过 Hooks 将环境、执行、验证、学习和探索拆开。它不接收官方评估分数。要理解实际行为，应同时读调用方的 Hook 配置：通用数据类中部分布尔值默认为 false，而 Phase 2 入口会按照协议开启 PASS 学习与课程判断。

依据：core/self_evolving_loop.py · benchmarks/osworld/phase2.py · tests/test_self_evolving_loop.py · tests/test_phase2_stop_policy.py

06记忆的文件协议与上下文管理

持久化对象到底是什么？

宿主侧核心对象是 dict[str, bytes]，即相对路径到文件字节的映射；客体侧放在 ~/.memory/。文件可以是说明、操作手册、脚本或失败记录。没有强制 Schema、索引文件名、文件数量或记忆长度。

一次完整学习不是“总结聊天记录”

# 教学抽象：示例文件结构由工程设计者选择，仓库不强制。
{
  "playbooks/video_export.md": b"...",
  "failures/unsupported_filter.md": b"...",
  "scripts/check_render.py": b"..."
}

# 学习边界
restore(canonical_memory)       # 撤销工作期随手改动
resume(original_actor_history)
distill(verdict, verifier_report)
reconcile_all_claim_files()
write_learning_diagnosis()      # 适用的 DRS 学习路径
candidate = pull_memory()
validate_boundary(candidate)
journal(candidate)
atomic_install(candidate)

“因果知识”的合理读法是：在已观察的条件 C 下，动作 A 导致了结果 O，并保留反例与不确定性。验证者证明产物是否符合要求，并不会自动证明失败原因。因果解释仍由 Actor 依据轨迹判断，需要对比实验才能增强可信度。

依据：explore/charter.py · explore/charter.py · explore/target_learning.py · explore/practice_loop.py · core/loop.py · explore/memory_hash.py

07Actor 如何把模型输出变成程序执行

core/actor.py 定义动作结构与解析；core/loop.py 驱动模型调用、动作执行、观察返回和验证。模型输出的是回复正文中的 JSON，运行时解析后分派；原生 API function call 不是这条动作通道的默认协议。

{"program":{"lang":"bash","code":"ls -lah ~/.memory"}}

{"look":{"path":"/tmp/candidate.png","question":"连接线是否接到正确的图形边缘？"}}

{"done":{"checks":[{"desc":"产物存在且可读","probe":"test -s /tmp/result.txt"}]}}

默认配置中 Actor 使用 GLM-5.3，视觉读取由 Kimi-K3 协助，Verifier 和 Curriculum 也使用 Kimi-K3 的独立上下文。因此把结果归因于“某个单模型提升多少”会遗漏视觉与验证角色的贡献。配置还允许停滞触发角色交换，分析实验时需要把这些运行设置纳入记录。

工程判断：程序动作适合复杂桌面软件，因为一次程序能操作结构化文件、检查应用状态，再用实际应用验证画面。但应用名称、可编辑格式、导出产物和操作约束仍是任务的一部分；程序成功退出只证明程序运行结束。

依据：core/actor.py · core/loop.py · core/loop.py · config/osworld/baseline.yaml · config/roles/actor.yaml

08独立验证为何需要环境隔离

如果验证者通过测试意外修改了文件，再去检查这个文件，就可能把自己修好的结果当成 Actor 的成果。仓库用环境机制保护候选，并给验证者独立的会话与可持续的私有工作区。

AgenticVerifierExecutor 负责执行边界；VerifierSession 保存本次目标尝试的验证上下文及 scratch。验证报告直接发布给宿主，不先写入客体文件让 Actor 任意替换。Actor 的私有路径如 /home/user/.memory 与工作目录按配置隐藏。

判断必须保留三种含义

• PASS：要求有证据支持候选满足任务条件。
• FAIL：有证据显示实质要求被违反；也能形成有价值的失败经验。
• UNVERIFIED：重要结论尚无充分证据或证据冲突；目标路径需要继续补证，不能当成成功或学习失败。

Verifier 本身仍是模型；隔离能保护证据来源与产物，不能保证它正确理解需求。这也是论文报告“本地验证通过，但正式评分仍不完整”的原因之一。

依据：core/verifier_runtime.py · core/verifier_runtime.py · core/verifier.py · env/qemu_rollback.py · config/osworld/baseline.yaml · 论文第 21 页

09冻结、评分与任务隔离的真实边界

默认研究设计是针对目标的适应

公开 runner 提供的示例协议包含 target_conditioned_adaptation 等研究设计选项；在这种配置里，开发与评估任务可以围绕同一目标展开。这个事实用于理解源码实验控制，不应直接扩展成“论文所有结果都属于 held-out 泛化”或相反结论。论文结果应按各自附录与 reporting scope 阅读。

冻结首先保护宿主正式记忆

Phase 3 写入 memory_lock.json，标注关闭回写与课程。每次任务后检查宿主记忆树哈希。记忆被复制到 VM 中，Actor 的客体本地工作改动不回写。不能仅凭“frozen”推断所有客体记忆文件都被操作系统挂成只读。

两个容易忽视的源码细节

依据：config/osworld/rsi.example.json · benchmarks/osworld/pipeline.py · benchmarks/osworld/pipeline.py · benchmarks/osworld/task.py · explore/commit.py

10论文实验结果与报告范围

下表为作者论文报告的聚合结果。Partial 是任务部分得分的均值，Binary / Full credit 是获得满分的任务比例；差值使用百分点。这里展示的是作者 manuscript 中的统计口径，而不是本次 review 重新执行得到的独立复现实验。

四任务报告中 Full RSI、仅 BRS、仅 DRS 的平均部分得分分别为 74.54%、65.52%、56.50%。它支持继续研究“先广后深”的组合，但小样本选择、重复次数和预算不对称限制了结论强度。

论文另有 40 个游戏开发任务实验。当前公开仓库的主要入口是 OSWorld 与 ALE；在已检查的当前树中没有相应游戏实验入口，因此不能声称一条现成命令能复现论文全部实验。

依据：论文表 1 · 附录 C.3–C.4 · 附录 C.5 与 D · docs/PAPER.md · README.md

11用两个案例理解经验如何影响结果

T049：失败纠正了需求解释

演示文稿修复任务要求保留元素尺寸和外观。第一次 DRS 误把它理解成“盒子位置也不能移动”，只修箭头，结果布局仍错误。失败经验促使后续练习区分“保持尺寸”和“恢复位置”，并学习怎样借助完整元素或参考图确定坐标。

案例可支持的解释：记忆纠正的是动作前的解释规则，随后才影响坐标计算。最终内部 PASS 仍未带来满分，说明验证覆盖仍可能不完整。这里的迭代减少也不能忽略前期探索成本。

T044：相似视觉效果，不代表相同应用语义

视频案例中，两次输出都去除了顶部水印并保留画面比例。无记忆运行使用通用裁切/补边滤镜；记忆运行采用 Shotcut 原生裁切表示。正式评分同时读取导出视频和工程结构，所以仅看画面不足以解释得分。

案例可支持的解释：可复用经验应涵盖指定软件的原生操作、工程格式和验证方法；这次改进增加了完成质量，并没有减少执行迭代。不能把记忆作用统一描述成“更快”。

依据：T049：附录 E.3 · T049：表 A7 · T044：附录 E.5 · T065 限定

12按调用关系阅读源码

测试文件可以当作边界说明书

重点看 test_self_evolving_loop.py、test_phase1_wave_authoring.py、test_verifier_isolation.py、test_phase2_stop_policy.py、test_memory_retrieval_lifecycle.py。例如已有测试明确要求：一次 PASS 后若开展新练习，再次目标失败就不能沿用旧 PASS；UNVERIFIED 不进入记忆学习。

有些注释还保留历史实验名称与旧模块描述。判断当前行为时依次看公开入口 → 生效配置 → 调用点 → 实际分支 → 对应测试，不要仅靠注释里的“默认值”或历史路由名称。

依据：tests/test_self_evolving_loop.py · tests/test_phase1_wave_authoring.py · tests/test_verifier_isolation.py · tests/test_memory_retrieval_lifecycle.py

13复现路径：从协议检查到单任务

以下命令依据当前仓库文档整理，未在本次分析中启动正式实验。参考环境是 Python 3.12、uv、Linux、Docker 与 /dev/kvm，并需要模型 API、固定版本基准、VM 镜像及任务资产。默认方案通过 API 调用模型；桌面 VM 与软件环境是另一组资源需求。

git clone https://github.com/AetherLabsAI/RSIAgent.git
cd RSIAgent
git checkout a9e56263f6deaa493496ad6b155fe24bf131bc12
cp .env.example .env
# 在 .env 中填入自己的 OPENROUTER_API_KEY

git clone --branch v2026.08.08 https://github.com/xlang-ai/OSWorld-V2.git ../OSWorld-V2
cd ../OSWorld-V2
uv sync --frozen
uv pip install --python .venv/bin/python -r ../RSIAgent/requirements.txt
source .venv/bin/activate
cd ../RSIAgent

python tools/prepare_osworld_v2_release.py
python tools/build_p2_corpus.py
python tools/exam_fence.py build
python tools/smoke_osworld.py --output results/smoke/osworld

# 查看完整任务计划，不启动 VM / 模型，也不写输出
python run_osworld.py --arm both --name learning_batch_01 --dry-run

先用仓库的单任务协议学习生命周期；根目录批处理默认会面向完整任务列表。示例协议已经是 task_080，无需臆造一个根入口不支持的 --task 参数。

cp config/osworld/rsi.example.json config/osworld/rsi.learning.json

# 编辑 rsi.learning.json：
# 1. run_name 改为唯一名称，如 learning_task080_01
# 2. 保留 task_080 与其方向文件，或同步修改三处目标信息
# 3. 保留明确的 study_design 与 phase2.stop_policy

bash scripts/run_rsi.sh config/osworld/rsi.learning.json

# 查看入口支持的检查选项
python -m benchmarks.osworld.pipeline --help

并发参数要区分两层：根命令的 --concurrency 控制独立任务链；BRS 的 parallelism 控制单个任务链内部的分支。两者一起增加会放大同时运行的 VM 数量。

默认目标 Actor 单次调用 watchdog 为 36,000 秒，练习与课程配置为 86,400 秒。它们是单次运行上限，不是完整项目的成本估算或整个探索链的总时限。当前材料不足以给出可信的美元预算。

依据：README.md · docs/OPERATIONS.md · scripts/run_rsi.sh · config/roles/target.yaml · config/roles/actor.yaml

14迁移到自研 Agent：最小可行实现

以下是基于源码的工程设计建议，不是仓库已经提供的 Java SDK。已有 Java Agent 系统可以先迁移角色边界和记忆生命周期，再决定是否接入完整桌面环境。

enum Verdict { PASS, FAIL, UNVERIFIED }
enum CurriculumDecision { PRACTICE, READY, STALLED }

record MemoryVersion(String id, String treeHash) {}
record Verification(Verdict verdict, String evidenceRef) {}

interface MemoryRepository {
    MemoryVersion snapshot();
    MemoryVersion commit(String expectedParentId, MemoryDraft draft);
}

// 建议：提交前比较父版本；冲突时重新协调，不采用最后写入覆盖。
// BRS 的多个 Actor 可并行执行，学习提交放入同一串行队列。

一个适合第一版的练习环境

选择一个可重置的表格或文档处理沙盒：任务是修复含公式、格式和导出要求的文件。BRS 分别探索公式、引用、格式与导出；DRS 针对某个失败补充边界样例；最终使用冻结记忆完成另一个预先保留的任务。文件可直接检查，环境成本比多应用桌面基准更容易控制。

最小实验要保存四组信息

• 效果：任务通过率、部分得分、回退任务及错误类别。
• 成本：探索和评估分别统计 token、工具次数、VM 时间和墙钟时间。
• 验证质量：内部 PASS 对应的外部失败率；UNVERIFIED 的原因分布。
• 记忆使用：读取过哪些版本、哪些条目影响动作、修订过哪些错误规则。

先比较同一 Actor–Verifier 框架的空记忆与冻结记忆，在相同测试集、模型与预算下重复运行。之后再比较仅 BRS、仅 DRS 和组合。这样才能回答你的业务到底从哪一层得到收益。

15适用场景、失败模式与改进优先级

错误如何被放大

练习没有触及真正难点 → 验证遗漏关键要求 → Actor 把局部接受理解为通用规则 → 下一轮更确信错误。这个链条说明，记忆量增加和模型调用增加都不必然提高质量。

源码层面的成熟度判断：项目有清晰的状态边界、隔离机制、运行证据与恢复模块，适合研究复杂 Agent 的编排实现。它仍依赖特定基准环境、长时间模型调用和操作性恢复流程；当前发布包含的是运行框架，不能等同于已封装好的通用生产 Agent 平台。

依据：docs/ARCHITECTURE.md · docs/OPERATIONS.md · docs/RELEASE.md · 失败模式分析 · 限制

16学习路线与自测

17版本、依据与分析范围

1. arXiv v1 PDF：研究方法、结果、附录与案例。
2. README.md：安装、公开入口、报告范围。
3. docs/ARCHITECTURE.md：角色权限、阶段与提交边界。
4. docs/PAPER.md：论文统计口径、历史变体、消融限定。
5. docs/OPERATIONS.md：运行时限、并发与恢复方式。
6. docs/RELEASE.md：来源记录与作者已报告的发布验证；不作为本次测试结果。
7. explore/phase1_wave.py：广度探索与有序提交。
8. core/self_evolving_loop.py：目标尝试和自演进状态机。
9. explore/charter.py：角色与学习提示词。
10. core/verifier_runtime.py：验证隔离机制。
11. benchmarks/osworld/pipeline.py：三阶段协议与记忆完整性检查。
12. benchmarks/osworld/task.py：记忆加载、执行与封闭评分。

链接固定在分析提交版本。数值标注为作者报告；源码行为与工程建议分别叙述。正文没有把静态检查等同于运行验证。