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

技能已发布到 npm：@raphael-liu/raphael-loop（带官方 dsh.skills 声明）。可通过 DSH 插件通道（profile bundle）安装，或把技能目录放入 DSH 的 Skill 根目录：

# 官方插件通道（profile bundle；安装后重启 dsh 生效）
dsh plugin --profile web add @raphael-liu/raphael-loop

# 文件系统 Skill 根（立即生效；全局或项目级）
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。