RaphaelLoop

面向 Codex、Claude Code 与 DeepSeek Harness 的有界、可验证 Loop Engineering。

English · 技术架构 · 示例 · 参与贡献 · 安全策略

RaphaelLoop 是面向 Codex、Claude Code 与 DeepSeek Harness 的 Agent 长任务控制面。它把“持续执行，直到完成”转换为一个有目标契约、有修改边界、有独立验证、有资源上限、可中断恢复且能确定退出的工程循环。

它不负责生成业务代码，也不替代 Git、CI 或宿主权限系统。模型继续诊断和实现，Codex、Claude Code 或 DeepSeek Harness 继续提供文件、终端与审批能力，项目测试继续定义验收事实；RaphaelLoop 负责固定目标、调度任务、绑定证据、记录消耗并决定何时停止。

目标 -> 契约 -> 基线 -> 任务 DAG -> 有界实施 -> 独立验证 -> Checkpoint -> 终态

一、RaphaelLoop 解决什么问题

AI Coding 不缺生成代码的能力，缺的是跨轮次的执行控制。任务一旦涉及多文件、多 Agent、长时间运行或会话恢复，系统就必须持续回答：目标是否变化、谁能修改什么、当前证据是否有效、下一轮是否值得继续，以及现在究竟应该成功、阻塞、耗尽还是取消。

| 失控点 | 常见表现 | RaphaelLoop 的处理 | | --- | --- | --- | | 目标漂移 | “修复构建”逐渐变成升级依赖、改 API、顺手重构 | 执行前固定 objective、允许范围、禁止范围和成功谓词 | | 完成标准模糊 | “做到生产可用”“继续优化”没有可判断终点 | 拒绝主观谓词，要求可重复验证器和有限额度 | | 活动冒充进展 | 反复分析、改写计划、增加代码，却没有任何指标改善 | 只认可谓词改善、验收通过或阻塞被独立解除 | | 实现者自证 | Worker 说“已完成”，系统直接结束 | 由独立 Verifier 运行预声明验收命令 | | 证据过期 | 测试通过后代码又变了，旧日志仍被引用 | 证据绑定完整项目指纹，项目变化后自动失效 | | 并发冲突 | 多个 Agent 同时改同一文件或同一外部对象 | DAG 依赖、唯一 Owner、作用域租约和重叠检测 | | 无限重试 | 同一个稳定错误换几种说法继续尝试 | 失败签名计数；第一次允许定向恢复，第二次阻塞 | | 会话中断 | 上下文压缩后不清楚哪些工作已经验收 | 状态、证据和 checkpoint 保存到对话之外的项目目录中 | | 权限膨胀 | “继续执行”被误解为允许发布、删除或提权 | 审批门显式入约，循环不创造新的授权 |

提示词可以描述这些规则，却无法稳定维护跨进程锁、计数器、文件哈希和证据时效。RaphaelLoop 因此把需要判断的工作留给模型，把不能含糊的状态不变量交给本地确定性内核，将普通 Agent 的开放式执行改造成证据驱动的闭环：

flowchart LR
    G["自然语言目标"] --> C["可执行 Goal Contract"]
    C --> B["基线与项目指纹"]
    B --> D["最小任务 DAG"]
    D --> W["有界实施"]
    W --> V["独立验证"]
    V --> P["Checkpoint"]
    P --> T{"终态判断"}
    T -->|仍可推进| D
    T -->|满足全部谓词| S["succeeded"]
    T -->|额度用尽| E["exhausted"]
    T -->|没有安全路径| X["blocked"]
    T -->|用户取消| K["cancelled"]

它的目标不是让 Agent 多跑几轮，而是得到七个可审计结果：

1. 目标稳定：objective、修改范围、禁止项和验收条件不能在执行中被静默改写。
2. 工作有界：每个 Goal 都有有限的轮次、时间、Token、成本、恢复和停滞上限。
3. 调度可解释：每个任务都映射到成功谓词，依赖不满足的节点不会执行。
4. 并发可控：重叠作用域同一时刻只有一个写 Owner，失联任务由有限租约释放。
5. 证据新鲜：通过记录必须晚于交付，并与当前项目指纹一致。
6. 恢复可停止：同类失败不会无限重试，恢复动作必须产生新信息。
7. 终态确定：同一份状态只能得到同一种优先级结论。

RaphaelLoop 适用于下面这些任务：

• 修复一组可稳定复现的测试、构建、lint 或类型检查失败；
• 交付跨组件、跨层功能，并用固定命令闭环验收；
• 围绕性能、覆盖率、错误数等可测指标做有限优化；
• 协调作用域互不重叠的领域 Agent；
• 在上下文压缩、客户端重启或会话中断后恢复长任务；
• 在重复失败、权限缺失或预算耗尽时自动停在正确终态。

一次修改加一次检查就能完成的任务，不需要 RaphaelLoop。完全依赖审美、没有可用证据的目标，无期限监控，以及无人审批的不可逆生产操作，也不应该进入循环。RaphaelLoop 不替代项目测试，不自动证明测试覆盖充分，不作为权限沙箱，也不执行发布、付款、回滚、删除或提权。

二、总体架构：协议、角色、内核、宿主各守一条边界

RaphaelLoop 当前由四层组成：

宿主层。

Codex、Claude Code 或 DeepSeek Harness 提供模型、上下文、文件系统、终端、网络和审批机制。真实业务代码由 Root 或 Worker 通过宿主工具修改。RaphaelLoop 不绕过宿主沙箱，也不会扩大用户原本授予的权限。

协议层。

skills/raphael-loop/SKILL.md 定义与宿主无关的执行纪律：何时接纳循环、如何选择模式、怎样编译契约、如何构造 DAG、哪些角色能请求哪些迁移、怎样处理恢复和终态。

角色层。

Skill 为 Codex、Claude Code 和 DeepSeek Harness 分别内置语义一致的六种角色。它们是职责边界，不是六个必须常驻的进程：

| 角色 | 唯一责任 | 不能越界做什么 | | --- | --- | --- | | Controller | 管理契约、额度、checkpoint、进展和终态 | 代替 Verifier 自证成功 | | Planner | 从成功谓词反推最小任务 DAG | 在执行中静默扩大范围 | | Orchestrator | 选择 runnable 节点并分配唯一 Owner | 给重叠对象并发写权限 | | Worker | 完成一个有界任务包 | 宣布整个 Goal 已成功 | | Verifier | 独立运行预声明验收条件 | 接受 Worker 的口头结论 | | Recovery | 把稳定失败变成一个新动作或停止建议 | 机械重试或绕过审批 |

宿主已有更匹配的领域专家时，Orchestrator 可以优先使用专家 Agent；没有时使用内置 Worker。并发 Worker 最多三个，同时为 Root 保留一个执行槽。只有文件、外部对象、依赖和可变状态都不冲突的任务才适合并行。

确定性内核。

skills/raphael-loop/scripts/raphael_loop.py 是 Python 3.9+、无第三方依赖的本地内核。它不理解业务需求，也不写业务代码，只负责可以机械判断的不变量：

• 校验 JSON Goal Contract 和无环任务 DAG；
• 使用文件锁与原子替换持久化状态；
• 为任务作用域签发有限租约，拒绝重叠 Claim；
• 以 shell=False 执行契约中固定的参数数组；
• 保存有限大小的验证日志、哈希和项目指纹；
• 维护轮次、时间、Token、成本、恢复和停滞计数；
• 校验证据时效、生成 checkpoint、审计篡改；
• 按固定优先级计算终态。

这条分工非常关键：Agent 可以提出状态迁移，只有内核能确认迁移合法；内核可以运行验证器，但不能替 Agent 修改项目。

三、准入、运行模式与目标契约

RaphaelLoop 先做 Admission，而不是看到“继续”就开始重复执行。只有同时满足以下条件，Goal 才适合进入循环：

• 有可重复执行的命令、查询、检查或可测产物来判断结果；
• 工作能拆成一轮内可完成的增量；
• 允许范围、禁止范围和审批边界已知；
• 至少有一个有限的轮次、时间、Token、成本或截止时间上限。

如果目标、范围、验证器和授权都明确，但用户没有给轮次上限，协议允许披露并使用默认最多 10 轮。缺少关键字段且无法安全推导时，应该补齐契约，而不是带着歧义修改项目。

进入 Skill 后还要选择唯一运行模式：

| 模式 | 用途 | 是否修改项目或运行状态 | | --- | --- | --- | | design | 编译并校验 Goal Contract 与最小 DAG | 只读，不初始化状态 | | run | 执行任务、验证、checkpoint 和终态决策 | 仅修改契约允许范围 | | resume | 中断后审计原状态并继续 | 保留原计数和已验证任务 | | audit | 检查契约、状态、租约与证据完整性 | 只读 |

这使“帮我设计一下”不会被静默升级为代码实施，“查看状态”也不会消耗新一轮预算。

把自然语言目标编译成可执行契约。

Goal Contract 是循环的控制面输入，使用 schema_version: 1 的 JSON。核心字段如下：

goal_id / objective / success_mode
scope.allowed / scope.prohibited
predicates[]: id, kind, command[], timeout_seconds, runs, required_passes
limits: iterations, minutes, tokens, cost, recoveries, stalls
approval_gates[]
tasks[]: id, deliverable, depends_on, scope, predicate_ids,
         rollback_plan, side_effects

契约不是把需求换成 JSON 就结束，它必须满足一组硬条件：

• goal_id 是最长 63 字符的小写 kebab-case；
• Scope 必须是项目相对路径，不能包含绝对路径或 ..；
• Predicate 类型只能是 custom、test、lint、typecheck、e2e、performance 或 security；
• 验证命令必须是非空参数数组，Shell 字符串无效；
• 每个限制值都必须为正数且有限；
• 每个任务都必须关联至少一个 Predicate；
• 任务依赖必须存在且无环；
• 任务范围必须在允许范围内，且不能与禁止范围相交；
• 副作用必须声明审批门和幂等键，但内核仍不会代为执行。

design 模式可以只验证契约，不创建任何运行状态：

python3 "$RAPHAEL_RUNTIME" validate --contract /absolute/path/to/contract.json

契约一旦初始化会计算 SHA-256 哈希。同一个 goal_id 只有契约哈希一致才能恢复；目标、范围或验收条件发生实质变化时，应产生新的明确决策，而不是沿用旧状态并暗中降低标准。

四、任务 DAG、Agent 所有权与有界执行

Planner 不是先列一张泛化 Todo List，而是从失败的成功谓词向后推导最小交付物。

flowchart LR
    P1["Predicate: Jest 回归测试"] --> T1["修复 JS 导航幂等性"]
    P2["Predicate: TypeScript"] --> T1
    T1 --> T2["校验 Android Intent 接入"]
    P3["Predicate: assembleDebug"] --> T2

任务状态只有六种：

pending | runnable | active | verified | failed | blocked

依赖全部 verified 后，任务才会进入 runnable。Orchestrator 通过 claim 把它变成 active 并签发默认 30 分钟租约。内核把路径规范化为物理路径，并以精确相等、祖先/后代、符号链接别名和保守的大小写归一判断作用域冲突。

租约过期时，未完成任务会回到 runnable，避免失联 Worker 永久占用工作。这个机制解决的是并发所有权，不是代码合并；最终组合结果仍要由 Root 整合，并由 Verifier 面向当前项目重新验收。

一轮循环如何执行。

初始化或恢复状态：

RAPHAEL_RUNTIME="$SKILL_DIR/scripts/raphael_loop.py"
python3 "$RAPHAEL_RUNTIME" init \
  --contract /absolute/path/to/contract.json \
  --project /absolute/path/to/project

运行状态写入消费者项目，而不是 RaphaelLoop 仓库（状态文件位于 .raphael-loop/<goal-id>/state.json）：

.raphael-loop/<goal-id>/
├── state.json
├── state.json.lock
├── checkpoints/
└── evidence/

一轮的真实顺序如下：

# Orchestrator：领取依赖已满足且范围无冲突的任务
python3 "$RAPHAEL_RUNTIME" claim \
  --state "$STATE" --task "$TASK" --owner "$OWNER"

# Root / Worker：通过 Codex、Claude Code 或 DeepSeek Harness 的正常工具修改项目

# Worker：记录本轮结果和资源消耗
python3 "$RAPHAEL_RUNTIME" record \
  --state "$STATE" --task "$TASK" --owner "$OWNER" \
  --outcome progress --tokens 2400 --cost 0.35

# Verifier：只能运行 Contract 中对应 Predicate 的固定命令
python3 "$RAPHAEL_RUNTIME" verify \
  --state "$STATE" --predicate "$PREDICATE"

# Controller：接受新鲜证据并判断终态
python3 "$RAPHAEL_RUNTIME" checkpoint \
  --state "$STATE" --task "$TASK" --owner "$OWNER"
python3 "$RAPHAEL_RUNTIME" decide --state "$STATE"

record 是轮次、Token 和成本正式入账的边界。纯状态查询、等待审批或恢复状态加载不算新一轮。progress 需要记录交付时间和交付项目指纹；no-progress 增加停滞计数并释放租约；failure 必须附带规范化失败签名。

每轮开始前和 checkpoint 后都先做终态判断。到达终态后立即停止，不能再附带“顺手优化”。

五、证据、状态、恢复与确定性终态

Verifier 每次执行都会记录：

• Predicate ID 与类型；
• 开始和结束时间；
• 每次运行的退出码、超时状态和耗时；
• 最多 1 MiB 的合并输出日志；
• 日志 SHA-256；
• 通过次数和要求的 quorum；
• 验证完成时的项目指纹。

在 Git 项目中，指纹覆盖已跟踪文件和未忽略的未跟踪文件，并递归覆盖已 checkout 的 Submodule；.raphael-loop/ 自身被排除。非 Git 目录会遍历项目文件，同时排除 .git、.raphael-loop、node_modules、.venv 和 __pycache__ 等控制或依赖目录。

Checkpoint 只接受同时满足三个条件的证据：

1. 对应 Predicate 已通过；
2. 验证开始时间晚于本次交付记录；
3. 证据指纹与当前项目指纹完全一致。

因此下面这条证据链是无效的：

项目指纹 A -> Jest 通过 -> Agent 又修改 Android 文件 -> 项目指纹 B

即使 Android 修改看似与 Jest 无关，A 上的测试也不能证明 B。最终 succeeded 需要成功模式要求的全部 Predicate 都有绑定当前指纹的新鲜通过证据。这是一种保守设计：它会增加重跑成本，但避免“旧日志为新代码背书”。

证据账本只能证明某条命令在某份项目快照上得到某个结果，不能证明测试覆盖充分，更不能证明外部系统在验证后没有变化。Predicate 的质量仍然决定了结论的上限。

状态为什么能恢复，又为什么不能手改。

内核用相邻锁文件保护状态更新，再把 JSON 写入临时文件，执行 flush、fsync，最后通过 os.replace 原子替换；目录本身也会 fsync。这让进程中断不容易留下半份状态。

state.json 内嵌完整契约和契约哈希，并用规范化 state_hash 覆盖其余完整记录。状态文件路径还必须与内嵌 project_root 和 goal_id 对应。证据日志有独立哈希。audit --state 会检查这些关系、日志是否存在、哈希是否一致、租约是否过期以及多次运行 Predicate 是否使用了 quorum。

python3 "$RAPHAEL_RUNTIME" status --state "$STATE"
python3 "$RAPHAEL_RUNTIME" audit --state "$STATE"

这意味着恢复只继承可验证事实：已验收任务、剩余预算、失败签名、有效租约和最新 checkpoint。不能通过手改计数器、伪造 Evidence 或搬动 state.json 来获得成功。状态损坏时应保留现场审计，不能删除历史后假装是一个全新的成功任务。

.raphael-loop/ 通常应该加入消费者项目的 .gitignore。其中的 Evidence 可能包含测试输出，验证命令不应打印凭据。

Recovery 如何阻止无限重试。

失败被规范化为：

<verifier-name> + <exit-code-or-result> + <error-class>

例如：

deep-link-tests:1:ExpectedOneNavigation

第一次出现时，Recovery 必须基于原始证据提出一个信息增益更高的动作，例如“用假时钟确认 native initialURL 与 Linking event 是否在同一渲染周期重复到达”，然后记录恢复边界：

python3 "$RAPHAEL_RUNTIME" retry \
  --state "$STATE" --task "$TASK" \
  --failure-signature 'deep-link-tests:1:ExpectedOneNavigation' \
  --action '验证 initialURL 与 Linking event 的重复到达路径'

第一次相同签名会让任务回到 runnable 并增加恢复计数；第二次相同签名会把任务置为 blocked。retry 只记录动作，不执行动作，也不自动回滚。

另一条停止机制是连续停滞。只有 Predicate 指标改善、任务通过验收或阻塞依赖被独立解除才算进展。连续达到 max_stalls 仍无进展时，循环停止为 blocked。换措辞、重写计划、增加日志或做无关重构不能重置停滞。

确定性终态。

RaphaelLoop 使用固定优先级：

cancelled > succeeded > exhausted > blocked

• cancelled：用户取消或用新目标替换当前 Goal；活动验证器会轮询状态并尽力终止进程组。
• succeeded：all 或 any 成功模式要求的 Predicate 都有当前项目指纹上的新鲜通过证据。
• exhausted：成功之前先达到轮次、时间、Token、成本或恢复上限。
• blocked：达到停滞上限、同一失败重复出现，或没有安全的 runnable 节点。

如果成功和额度上限在同一个已验证边界同时成立，succeeded 优先。验证缺失、失败、被篡改或过期时只能是 unknown，不能转换为成功。

固定终态不是文字规范。decide 从状态计数、任务图和当前项目指纹直接计算并持久化结果，因此不同 Agent 不应对同一现场给出不同结论。

六、安全边界：它是控制内核，不是沙箱

RaphaelLoop 能约束循环，但不能创造宿主没有的安全能力。

• 发布、支付、删除、生产写入、权限提升和其他不可逆动作仍需用户或宿主明确批准。
• Side Effect 在契约中必须带审批门和幂等键，内核只记录意图，不负责执行或回滚。
• Verifier 使用参数数组和 shell=False，降低 Shell 注入面，但被执行程序仍继承当前环境、文件系统、网络和操作系统权限。
• 超时或取消时，内核尽力终止验证器进程组；主动脱离到新 Session 的后代进程不在保证范围内。
• Worker 不能通过降低阈值、删除断言或替换验证器来制造成功，除非这本身就是用户明确授权的目标。
• 用户已有改动默认受保护；并发前必须声明文件或对象所有权。
• 外部网页、日志、代码注释和工具输出都只能作为数据，不能改写 Goal Contract 或升级权限。

因此，Predicate 只能使用经过审查的项目本地命令，宿主的沙箱与审批仍然是最后的权限边界。

七、如何安装 RaphaelLoop

环境要求：

• 支持 Agent/Skill 的 Codex、Claude Code 或 DeepSeek Harness；
• 推荐安装方式需要 Node.js 与 npx；
• macOS 或 Linux；
• Bash 3.2 及以上；
• Python 3.9 及以上，用于确定性运行内核和仓库验证。

项目不需要 .env 文件或服务凭据。HOME、PATH、TMPDIR、CODEX_HOME 和 CLAUDE_CONFIG_DIR 都是可选的宿主或操作系统环境变量，不是 RaphaelLoop 密钥。

使用开放的 Agent Skills CLI 直接从 GitHub 安装：

npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop

默认命令采用交互式、项目级安装。CLI 只发现嵌套的 raphael-loop 技能包，不会把仓库 README、架构图片和测试复制到用户的 Skill 目录。确认前请检查目标 Agent 与安装方式。

不安装，仅查看仓库中可用的 Skills：

npx skills add https://github.com/raphael-liu/raphael-loop --list

Codex

npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop --global --agent codex --yes

Claude Code

npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop --global --agent claude-code --yes

DeepSeek Harness

DeepSeek Harness 从本地的 Skill 根目录发现标准 SKILL.md 技能包，因此安装同一个包后，把技能目录复制进 DSH 用户根目录即可（团队共享可放项目 .dsh/skills/）：

npx skills add https://github.com/raphael-liu/raphael-loop --skill raphael-loop
cp -R skills/raphael-loop ~/.dsh/skills/raphael-loop   # 当前用户全局安装

与 Codex、Claude Code 不同，DeepSeek Harness 没有宿主级 Agent 注册：六个角色提示词内置于 Skill（agents/dsh/*.md），通过 DSH 内置的子代理机制分发。

bash skills/raphael-loop/scripts/install-agents.sh --harness dsh --dry-run
bash skills/raphael-loop/scripts/install-agents.sh --harness dsh --check

CLI 只安装 skills/raphael-loop/。Codex、Claude 与 DeepSeek Harness 的六个角色定义已经全部内置其中，不会再下载或克隆额外的 Agent 仓库。

首次使用为什么还要注册 Agents。

Skill 目录与宿主 Agent 目录是两个生命周期。第一次进入 run 或 resume 前，RaphaelLoop 会检查当前宿主的六个角色是否健康：

bash "$SKILL_DIR/scripts/install-agents.sh" --harness codex --check
# Claude Code 使用 --harness claude
# DeepSeek Harness 使用 --harness dsh

退出码含义：

| 退出码 | 含义 | 正确处理 | | --- | --- | --- | | 0 | 角色已安装且与 Skill 一致 | 继续运行 | | 10 | 尚未安装 | Dry Run 展示全部目标，取得授权后安装 | | 3 | 文件被修改、损坏或版本过期 | Dry Run 说明备份与替换目标，再请求授权 | | 4 | Skill 内置 Agent 集合不完整或无效 | 停止，恢复完整发行包 | | 2 | Harness 参数错误或无法识别 | 显式指定 codex、claude 或 dsh |

安全顺序是：

bash "$SKILL_DIR/scripts/install-agents.sh" --harness codex --dry-run
# DeepSeek Harness 没有宿主级角色注册，--harness dsh 只会校验内置角色提示词：
bash "$SKILL_DIR/scripts/install-agents.sh" --harness dsh --check
# 用户确认准确的宿主级写入目标后
bash "$SKILL_DIR/scripts/install-agents.sh" --harness codex
bash "$SKILL_DIR/scripts/install-agents.sh" --harness codex --check

遇到内容不同的同名文件，安装器会先写入时间戳备份目录，再原子替换角色文件并记录 manifest。它不会下载远程角色，也不会静默写入。卸载前同样要先执行 --uninstall --dry-run，明确批准后再 --uninstall；已被用户修改或与 manifest 不一致的文件会拒绝删除，备份目录也不会自动清理。 Skill 更新不会自动刷新已注册角色。下次运行会重新检查、展示变化并等待授权。项目级安装用 npx skills update raphael-loop --project 更新，全局安装用 npx skills update raphael-loop --global；移除技能前先让已加载的 Skill 清理其托管角色（--uninstall --dry-run → 明确批准 → --uninstall），再执行 npx skills remove raphael-loop（项目级）或 npx skills remove raphael-loop --global（全局）。

源码仓库维护者可以运行完整发布门禁：

bash scripts/validate.sh

在本文分析的提交上，门禁实际通过了布局、分发、32 项运行内核测试、Agent、安装器、Skill、文档、发布检查和官方 Skill Validator。

八、唯一使用范例：用 RaphaelLoop 修复 RN Android 冷启动 Deep Link 重复跳转

考虑一个典型 RN 故障：应用被杀死后，从 myapp://checkout/42 冷启动。Android Intent 的 initial URL 和 JS Linking 事件先后到达，导航层对同一个 URL 执行两次 navigate，用户看到 Checkout 页面压栈两次。热启动正常，因此人工回归很容易漏掉。

这个问题适合 RaphaelLoop，因为它同时具备：

• 明确的结果：同一个冷启动 URL 只能消费一次；
• 跨层边界：JS 导航幂等性与 Android Intent 接入；
• 可重复验证器：Jest、TypeScript 和 Android Debug 构建；
• 需要保护的范围：iOS、依赖、Gradle Wrapper、签名与发布配置；
• 有价值的失败恢复：区分 native 重复派发、JS 重复订阅和导航状态竞态。

可执行 Goal Contract。

• 修复失败测试
• 优化可测性能
• 交付跨层功能
• 可执行运行契约
• 运行契约与命令参考

每个示例都包含允许与禁止范围、固定验证命令、有限额度、可复制提示词和终态报告要求。

DAG 与 Agent 所有权。

flowchart LR
    A["stabilize-js-deep-link\nOwner: RN Worker\nScope: src/navigation + tests"]
    B["verify-android-intent-integration\nOwner: Android Worker\nScope: android/app/src/main"]
    V1["Jest + TypeScript"]
    V2["assembleDebug"]
    A --> V1
    A --> B
    B --> V2

虽然 JS 与 Android 文件范围不重叠，第二个任务仍依赖第一个任务，因为 native 交接要接入已经确定的幂等消费路径。此处追求的是正确依赖，不是最大并发。

一次实际循环。

进入项目目录后，先让 Skill 只读设计：

使用 $raphael-loop 的 design 模式，按文中的 fix-android-cold-deep-link
目标编译并验证 Contract。只读分析当前 RN 项目的真实脚本、Gradle Variant、
Deep Link 入口和导航实现；如果示例命令与项目不一致，报告差异，不要直接修改。

确认 Contract 后再授权执行：

使用 $raphael-loop 的 run 模式执行已确认的
fix-android-cold-deep-link Contract。

只修改 Contract 允许的路径。不要修改 iOS、依赖、Gradle Wrapper、
签名或发布配置。由独立 Verifier 运行三项预声明检查；
只有三项证据都绑定当前项目指纹并通过，才能返回 succeeded。

控制流可能是：

1. Controller 初始化状态，记录基线项目指纹。
2. Orchestrator Claim stabilize-js-deep-link，RN Worker 获得 JS 与测试路径租约。
3. Worker 用 Jest fake timer 或受控 EventEmitter 重现 initial URL 与 Linking event 重复到达，加入基于规范化 URL 和消费周期的幂等保护。
4. Worker record --outcome progress；Verifier 运行 deep-link-tests 与 typecheck；证据通过后 Controller checkpoint 第一个任务。
5. 第二个任务变为 runnable。Android Worker 检查 MainActivity/Intent 转发是否绕过统一入口，只在允许范围内做必要修改。
6. Verifier 运行 android-debug-build。因为 Android 文件变化让第一轮项目指纹过期，最终决策前还必须重新运行 Jest 和 TypeScript。
7. 三条最新 Evidence 都指向同一当前项目指纹后，decide 才返回 succeeded。

如果 Android 修复必须升级 React Native、修改 android/app/build.gradle 或触碰签名配置，现有 Contract 没有授权。正确结果是 blocked，并明确列出需要用户决定的新范围，而不是为了完成循环越界修改。

如果同一 deep-link-tests:1:ExpectedOneNavigation 失败在一次定向恢复后再次出现，任务同样进入 blocked。这说明现有证据和预算没有提供安全的新路径，不代表把测试删掉或把断言从一次改成两次。

九、工程权衡、结论与源码索引

RaphaelLoop 的成本很明确：编译契约、运行独立验证、重算项目指纹和保存 checkpoint 都会增加固定开销；保守的新鲜度策略还可能让看似无关的修改触发全量重验。因此它不适合一行替换或一次性查询。

但在跨文件、跨层、多 Agent、长时间或高风险任务中，这些开销换来了四个普通对话循环很难稳定提供的性质：

1. 目标和授权不会随着轮次悄悄漂移；
2. Agent 的工作声明与可验证事实被严格分开；
3. 会话中断后可以从已验收边界恢复，而不是从聊天记忆猜测；
4. 成功、耗尽、阻塞和取消都有确定语义。

RaphaelLoop 不承诺“AI 一定把任务做完”。它承诺的是更工程化的事情：没有当前证据就不宣布完成，没有可测进展就不继续消耗，同类失败不会无限重试，权限不足时明确停住。

参与贡献

修改角色契约前请阅读 CONTRIBUTING.md。Codex、Claude 与 DeepSeek Harness 定义必须保持语义一致；可执行行为必须有确定性验证；仓库不得包含凭据和私有运行状态。

安全问题请通过 GitHub 私密漏洞报告提交，详见 SECURITY.md。

许可证

RaphaelLoop 使用 MIT License。