ShadowSwaps/REA-Reconstruction-Companion · 上手攻略
- 仓库：ShadowSwaps/REA-Reconstruction-Companion
- 链接：https://github.com/ShadowSwaps/REA-Reconstruction-Companion
- 分类：agent · skill · 软件逆工程与重建
- 作者：spark
- 更新：2026-10-22
1. 这是什么
REA-Reconstruction-Companion 是一个开源、模型无关（model-independent）的 Agent Skill，专门配合 REA 使用，把对既有软件的逆向工程证据，组织成"需求 + 架构 + 实施路线图 + 可验证结果"。它的核心假设是：重建不是"复刻界面"，而是"重建证据 + 重建契约 + 分阶段推进"。
它的工作流被官方 README 描述为一个 6 节点图：
User goal → Scope & questions → REA evidence → Requirements & design
→ Implementation (when requested) → Validation & measurements
任意节点发现证据缺口都会回到 REA 取证，避免"猜完再补"。这与"看到 UI 就开始仿写"的常见做法形成显式隔离。
代码本身以 JavaScript 写成的安装脚本 install.mjs + 一组 Markdown 化的 Skill 指令、参考文档和离线示例（skills/.../references/ 和 evals/）为主，没有模型权重或闭源组件——你提供的 LLM 客户端负责推理，仓库只负责"怎么推理"。
2. 解决什么问题
如果你正面对以下场景，Companion 才值得用：
- 你拿到一个未文档化的桌面/Web 应用，想先理解它（不部署、不收费、不调用付费 API）。
- 你想仿写类似工具，并要求"先证据后实现"。
- 你要回放某个具体函数或特性（如 CSV 导入、日期时区处理），并接受一组"输入/输出/副作用/错误"的契约式描述。
- 你已经在做重建，发现规则过时或边界有歧义，需要对照证据逐项更新。
- 你想对一个有可见 UI、但服务后端私有的产品做有限重建：可用 screenshots/recordings 当起点，不强求完整推倒。
它刻意不做的事：自动验证与外部服务实时等价、自动部署、自动开付费账户。README 多次强调"the agent must report missing tools or evidence instead of claiming live analysis"。
3. 快速安装
3.1 前置
- 一个能跑现代 Node 的 AI 客户端（Claude Code / Codex 等），具备本地文件 + 命令行访问。
- 若要用
--integration on，先装好 REA 并选定客户端。 - 若启用了"weekly update check"（v1.2.0 起），会调用外部轻量探活，离线环境建议关掉。
3.2 通过 Agent 一次性安装
把以下 prompt 整段发给具备本地访问能力的 Agent：
Install REA-Reconstruction-Companion from:
https://github.com/ShadowSwaps/REA-Reconstruction-Companion
Read README.md and INSTALL.md, identify my AI client and its skills
directory, and follow the documented installation workflow.
Before making installation changes, explain the optional REA integration
rule and ask me to choose:
- Enable: relevant REA reconstruction requests also load the companion,
sharing evidence, requirements, and validation work.
- Skip: install the companion without changing REA; I can invoke it
explicitly. This does not remove an integration rule already installed.
Wait for my choice unless I have already provided it. Then install using
that setting, preview changes with --dry-run, preserve existing work and
backups, and verify with --check. Explain any missing prerequisites or
access limitations. Report what was installed, where, and whether the
integration was enabled. Do not claim success unless verified.
Also explain the optional weekly update check (included since v1.2.0)
and ask whether I want it enabled. Keep it off unless I choose it.
This checks on skill use and still asks me before installing an update.
Do not incur additional charges: use existing local tools and do not
activate billing, paid services, metered APIs, or automatic paid usage.
If a step could incur a charge and that cannot be ruled out, stop that
step and explain a no-charge alternative.
Prompt 中已经明确"Enable"或"Skip"二选一的提前决策项；不带 --client 也能执行，但会先停下询问。
3.3 手动安装（命令行）
下载 Release zip 或 clone 仓库，进入根目录后：
# Claude Code + 启用 REA 自动协同
node install.mjs --client claude-code --integration on
# Codex + 启用 REA 自动协同
node install.mjs --client codex --integration on
# 只装 Companion，不动 REA
node install.mjs --client claude-code --integration off
任何命令都可加 --dry-run 只看路径与变更，或 --check 校验既有安装是否完好。
显式调用入口（取决于客户端）：
- Codex：$rea-reconstruction-companion
- Claude Code：/rea-reconstruction-companion
3.4 每周更新检查（可选）
v1.2.0 起默认提供 --weekly-update 选项。该检查会先向用户确认才安装新版本，且不会引入任何付费调用。要离线/沙箱环境保持关闭。
4. 核心用法
4.1 自然语言驱动
Companion 不要求填写表单或模板变量。用普通语言描述目标即可：
"用 REA 和 Companion 帮我理解这个桌面笔记应用，准备之后做一个类似的。先聚焦笔记的创建、编辑、搜索和保存。把需求跟证据链起来，把观察和推断分开，列出未回答的问题和分阶段路线图。规范和计划阶段之后停下来。"
它会消费 REA 工具或你提供的证据，识别缺口，并把工作量控制在你设定的范围内。
4.2 三类典型场景
| 场景 | 行为期望 | 强度授权 |
|---|---|---|
| 理解现有软件 | 给出行为/需求/未知/分阶段路线图 | 不会实施任何东西 |
| 现在仿做一个 | 范围内可增量实现 + 比对观察需求、报告差距 | 在你授权"构建"前不写代码 |
| 调查一个特性/函数 | 给出"输入/输出/副作用/错误/接受用例"的契约 | 仅调研，不动实现 |
4.3 引用明确边界
Companion 对以下情况都给出可执行的"如何处理"指引：
- 不完美的原行为：明确要求说出"哪些兼容必须保留 / 哪些可以改进"，例如 "保留我现有工具能读的导出，但让保存失败更明显"。参考
evals/quirk-decisions.md。 - 截图/录屏/不完整描述：把可见状态/可观察的转换与"假设"分离；详见
evals/visual-evidence/README.md（强调：截图不需要重建整个 app，也不暗示能访问其服务器）。 - 服务不可达："Build local editing now; keep actual sharing pending until I supply authorized service evidence." 本地替代必须显式标记，真实服务要求仍要补齐；见
evals/unavailable-backend/README.md。 - 无障碍改进：键盘操作/对焦/标签/错误/状态反馈与视觉保真分开；见
evals/interface-accessibility/README.md（明确"模拟认证 ≠ 真实访问保护"）。 - 加密/协议互操作：记录参数并核对独立向量与拒绝用例。
- 从断点恢复：可读检查点 + 自动保留仍适用的历史结果，避免重复劳动；见
evals/resume/WALKTHROUGH.md。
4.4 显式分阶段流程图（README 摘录）
flowchart LR
A[User goal and target] --> B[Scope and questions]
B --> C[REA evidence]
C --> D[Requirements and design]
D --> E[Implementation when requested]
E --> F[Validation and measurements]
D -->|Evidence gap| C
F -->|Evidence gap| C
只要 D 或 F 触发回退，证据缺口立刻被记录，不会偷偷"编合理"。
4.5 学会之前先看走查
仓库自带三套自检走查（它们会暴露答案与预备样本，只用于学习，不构成"全新 Agent 试用"的凭据）：
- 调查示例：
evals/reference/WALKTHROUGH.md - 重建示例：
evals/reference/reconstruction/README.md - Resume 示例：
evals/resume/WALKTHROUGH.md
首次试跑建议先翻 evals/first-use.md，把"我想手动 vs 我想脚本化"先分清。
5. 典型适用场景
- 二次开发前的证据沉淀：已有的内部工具要重写或迁移到云，先用它搭"行为契约 + 风险清单"。
- 老桌面程序数字化：截图、录制、过往 bug 报告作为起点，重建一个轻量 Web 版。
- 功能级小型重构：只针对某个函数/特性，比如把
decodeFrame重写并比对正确性与性能。 - 有残余 bug 的工具维护：把"看起来不对但用户能忍受"的行为显式记录在 quirk 决策里，避免误改。
- 加密/协议 replay 沙盒：借助 Companion 的"可重放、可拒绝"工作流做互操作测试，但不要把它当成"获取访问权限"的黑盒。
6. 坑与注意
| # | 现象 | 影响 | 修复 |
|---|---|---|---|
| 1 | Chat-only 助手（无本地读写）尝试安装 | "Installing" 永远停在文件读写步骤 | 换成 Claude Code/Codex 这类有文件权限的客户端，或仅做引导 |
| 2 | 误启 weekly update check 走外网 |
离线/沙箱环境被 weekly probe 卡住 | 安装时显式选 Skip；后续可在配置里关 |
| 3 | 把"截图 = 已访问服务"等同起来 | 据此下结论"服务行为 = X" | Companion 明确：截图不重建整个 app，不假设服务器可达 |
| 4 | 用本地 dummy 替代声称"通过真实服务验证" | 报告失真、审计链断裂 | 显式标记 local substitute；真实要求另起 |
| 5 | 在集成 REA 后误以为"REA 启动 = Companion 也跑" | 任务路由错误、加载两份 | Companion 提示：只装一条后台 Agent 协同时，不要把 REA + Companion 视为两个独立后台进程 |
| 6 | 把模拟认证当作真实访问保护 | 安全结论被推翻 | 显式区分 simulated auth 与真实 access control；安全 boundary 决策必须由真实证据驱动 |
| 7 | 续接断点时把"未跑测试"当成"通过" | 后续回归被掩盖 | 走 checkpoints.md 的"untested transitions"标记，避免把未验证项当结论 |
7. 与同类对比
| 维度 | REA-Reconstruction-Companion | 普通"看着 UI 仿写"做法 | 通用 Agent（Claude/Cursor 等不针对 REA） |
|---|---|---|---|
| 证据链路 | 强制 REA 工具与 README 引用 | 自由发挥 | 取决于用户提示 |
| 模型无关 | 是（任何能读 SKILL.md 的客户端） | 取决于实现者 | 否（自带 LLM） |
| 付费 API 触发 | 安装脚本主动问询、再决定 | 隐式 | 经常默认打开 |
| 集成 REA 时路由冲突 | 明确只装一条后台 Agent | 容易双开 | 不涉及 |
| 离/在线 substitute 显式化 | 是 | 否 | 否 |
| 适合做"特征级小型重构" | 是 | 否 | 弱 |
| 学习成本 | 高（要先读 SKILL.md + evals） | 低 | 中 |
8. 一句话推荐结论
仅在你已经有 REA、且任务确实是"基于证据的逆向+分阶段重建"时启用它；其它场景用更轻量的 Agent 流程即可——Companion 的价值在于把"猜"的环节硬性压缩到最小，而不是让你跑得更快。
不确定/诚实标注
- 周增/版本：仓库卡片最近一次采集时间 2026-10-22，"最近提交 2026-10-21"，但
install.mjs的最新参数（如对 Codex 的支持细节）需在拉取后用node install.mjs --help现核实。 - "weekly update check" 自 v1.2.0 起作为可选特性，但具体默认行为取决于客户端版本，本文以 README 表述为准。
evals/下的所有"worked example" 都自带"含答案 + 已知先验"，不是"全新 Agent 试用"证据，下游若引用应标注。- 安全结论（"simulated auth ≠ real access protection"）源自 README 自身的明示安全边界；如需用于正式安全审计，请独立复核。