逆向与Mac开发 Stijnus/dsh-rev-eng

dsh-rev-eng

一个 DeepSeek Harness 插件，两套技能包：REA 6.8.0 用来理解已发布的 app、二进制文件和 bundle，BAMA 1.0.0 用来把一个原生 macOS app 从想法一路做到 Dock。总共 23 个技能（21 个 BAMA + 1 个 REA + rev-eng 路由器），随每个安装该 bundle 的配置档一起加载；可选的 REA MCP 服务器额外提供 229 个分析工具，供需要的会话使用。

需要 DeepSeek Harness >=0.2.1-rc.3 <0.3.0-0 和 Node.js >= 22。

你能得到什么

用 REA 做逆向工程

REA 从产物本身出发，解释已发布的功能是怎么工作的：原生二进制文件、Electron 和 JavaScript bundle、Android 包、固件、GPU 代码对象、.NET 程序集、打包后的 app，以及运行时抓取。技能会路由目标、收集证据，并报告它能确认什么、不能确认什么。

- reverse-engineer-anything 是工作流技能。它自带七份参考指南，覆盖目标处理、证据工作流、环境、运行时观察、Android、JavaScript 和原生产物，另有一份 dsh 专用指南讲可选的 MCP 挂载。
- 可选的 REA MCP 服务器以 mcp__rea__ 的形式向会话暴露 229 个工具，用于交互式二进制和应用程序分析。
- 分析引擎是可选的，且各自独立：原生代码用 Hopper、Ghidra 或 IDA，Android 用 JADX 加 JDK，Linux 上的固件用 Binwalk 或 Unblob。静态 JavaScript 和 .NET 检查不需要原生引擎。

用 BAMA 做原生 Mac app

BAMA 是一条由 21 个技能组成的流水线，把截图、规格或想法变成 Swift 6 / SwiftUI app：调研、克隆、简报、用户故事、脚手架、代码、macOS 集成、设计、性能、测试和发布。12 个小 app 的规格（窗口吸附、启动器、剪贴板历史、录屏等）作为示例放在 skills/app-brief/specs/ 下。

从这里开始

| 用户想要 | 技能 |
| 挑出流水线的下一步 | bama（输入 /bama） |
| 在逆向工程和 Mac app 工作之间路由 | rev-eng（输入 /rev-eng） |
| 理解已发布的 app 或二进制文件 | reverse-engineer-anything |

用 BAMA 构建，按阶段

| 阶段 | 技能 | 做什么 |
| 开始 | bama | 路由器：找到你当前的位置，调用正确的技能 |
| 开始 | app-brief | 把想法（或示例规格）变成一页简报 |
| 开始 | new-mac-app | 从模板生成可运行的 app：Swift package、SwiftData、构建脚本、快照模式、git |
| 规划 | research | 市场、用户、功能、设计和 macOS API 调研 |
| 规划 | clone | 截取 app 的每个界面，用 computer use 或浏览器 |
| Plan | user-stories | 一份待办清单，按里程碑组织，每条都带可勾选的验收标准 |
| Code | swift-swiftui | Swift 6 并发、状态、SwiftData、AppKit 桥接、编译器报错 |
| Code | os-integrations | 热键、菜单栏、浮动面板、窗口控制、屏幕捕获、快捷指令、URL scheme、权限 |
| Code | performance | 先测量再修：主线程、GPU 合成、图像、Instruments |
| Code | improve-architecture | 找出热点，每次提交只重构一步，并证明行为未变 |
| Code | agent-cli | 可选的命令行和 MCP 服务器，让智能体和脚本能驱动应用 |
| Design | ux-design | 命名、流程、每个功能从哪里打开、文案、无障碍，都在写代码之前定 |
| Design | mac-design | Liquid Glass、布局、工具栏、菜单、键盘、字体、深色模式 |
| Design | design-system | 一个强调色加一套 token，配一页规则说明 |
| Design | layout-grid | 4 pt 网格，配检查项，对不齐就报错 |
| Design | design-kit | 你自己的组件、token、字体、图标集、窗口外框，外加组件库页面 |
| Design | design-from-app | 照着截图重建应用外观，逐像素比对 |
| Design | app-icon | 一枚 Liquid Glass 图标，每种外观都检查过 |
| Ship | build-and-verify | 构建、安装、给每个页面在浅色和深色下截图，然后逐一看过 |
| Ship | test-mac-app | Swift Testing、应用内自测、智能体能驱动的调试桥 |
| Ship | improve-loop | 按待办清单推进，每次提交完成一条故事，直到里程碑做完 |

bama 由用户调用：输入 /bama 启动流水线。rev-eng 是包路由，也能由模型调用，所以智能体可以自己找到它。

环境要求

- DeepSeek Harness >=0.2.1-rc.3 <0.3.0-0，桌面应用或命令行。安装前，插件界面会检查包的 bundle patch 和 engines.dsh 兼容性。
- Node.js >= 22，供插件本身使用。
- macOS 26 或更高版本，以及 Xcode 26 工具链（Swift 6.2），供 BAMA 构建使用。你不需要打开 Xcode 应用，但 swift、xcodebuild、sips、xcode-select 必须可用。xcode-select --install 会装好命令行工具。
- Computer use（可选），用于视觉验证：会话具备该能力时，BAMA 的克隆和验证步骤会使用 harness 的 computer-use 能力，否则会向你索取截图。
- Node.js 和 npm，供 REA 使用。REA 的 MCP 服务器和命令行运行在 Node 22 及更高版本上；它的 setup 命令还要求 ^22.23.4、^24.22.1 或 >=26.12.1。首次运行 npx rea-agents 需要联网。
- 可选的 REA 引擎： 原生分析用 Hopper、Ghidra 或 IDA；Android 用 JADX 加 JDK；Linux 上的固件用 Binwalk 或 Unblob。技能不会自行安装引擎：安装引擎是单独一步，需要你批准。
- Windows： 用 scripts/install.ps1 可以正常安装技能，REA 的分析路径并非 macOS 专属，但 BAMA 构建原生 Mac 应用，因此需要 macOS。shell 安装器需要 Git Bash 或 POSIX shell。

安装

两种渠道：把 bundle 装进 dsh 配置档，或把技能目录复制到技能根目录。二选一，不要同时用：两份副本会占用相同技能名，重复项如何解析取决于服务商顺序，而不是你想用哪一份。默认走 bundle 渠道，因为它还会安装提供打包技能的服务商；为什么用 bundle 而不只是技能 解释了这种拆分。

方式 1：安装 bundle（推荐）

bundle 把技能放在包内，所以装一次配置档，该配置档上的每个会话都能拿到整套技能。dsh 会把命令转给 pnpm，因此本地路径、npm 包、Git 地址都能用：

from a checkout (installs as a link: dependency; the checkout must stay in place)
dsh plugin --profile web add /absolute/path/to/dsh-rev-eng

from npm
dsh plugin --profile web add dsh-rev-eng

from git
dsh plugin --profile web add github:Stijnus/dsh-rev-eng

装进已有的应用配置档（web、tui 或 headless），不要随便起新名字：只由 dsh plugin add 创建的配置档含基础运行时，但没有应用 bundle，无法启动。确认层已组合，再启动配置档：

dsh --profile web --dump-config # contains "# == dsh-rev-eng" and "- id: rev-eng-skills"
dsh --profile web

桌面应用。 desktop 配置档只由应用管理，普通命令行启动或对它执行 --dump-config 都会被拒绝。改从应用的 Plugins → Add plugin 对话框安装：它接受带可选版本号的包名（dsh-rev-eng）、Git 地址、tarball，或本地 checkout 的绝对路径。它会先检查 spec（包清单、bundle 补丁，以及 engines.dsh / peer 兼容性），再执行该配置档的包安装，并提供 Enable now。这与命令行执行的 inspect → package-install → enable 是同一套操作，只是范围限定在运行中的 desktop 配置档。卸载也在那里的 bundle 页面进行。不要在终端运行 dsh plugin --profile desktop：desktop 配置档归应用所有，Plugins 页面才是受支持的安装路径。

本地路径安装会保存为 link: 依赖，所以 checkout 必须留在原处。要分发到其他机器，请发布新版本、推送 Git tag，或上传 tarball，再通过命令行或 Plugins 页面安装该 spec。

方式 2：直接复制技能（不用 bundle）

想快速试用、不装包，就把打包技能复制到 dsh 已在监视的技能根目录。这种方式跨配置档可用，也不需要安装包：

macOS / Linux / Git Bash: into ~/.dsh/skills (DSH_HOME is honored)
bash scripts/install.sh

Windows PowerShell: same targetpowershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1

参数： sh bash scripts/install.sh --list # 随包附带的技能名 + 目标根目录 bash scripts/install.sh --project ~/code/my-app # <project>/.dsh/skills，rank 100 bash scripts/install.sh --user-agents # $DSH_AGENTS_HOME/skills (~/.agents/skills)，rank 500 bash scripts/install.sh --uninstall # 从选定的目标中移除本包的技能

--uninstall 只删除本包已知的技能目录，目录里的其他内容一律不动。--project 要求目录已存在。PowerShell 脚本接受 -Project、-UserAgents、-List 和 -Uninstall。

技能根目录的监听器会自动发现这份直接拷贝，无需重启应用；新建会话是确认生效最干净的方式。安装器做的事：把每个 skills/<name>/ 目录原样拷贝过去（含 references、scripts、templates 和示例 spec），保留脚本的可执行位，重跑时替换同一技能目录的旧副本，并打印目标路径和后续步骤。

没有一键试用整包的方式。用 --patch cordis.patch.yml 启动只会组合出这一层，但插件在包安装进配置档之前无法导入（Cannot find package 'dsh-rev-eng'），于是 harness 启动时不会带上这些技能。想免安装试用，请用直接拷贝的方式。

可选：REA MCP 服务器

安装本包只给智能体 REA 的工作流说明，不给 REA 的工具。MCP 服务器需要显式开启，用于逆向工程会话。REA 6.8.0 官方支持 dsh，所以 REA 可以自己写入注册项；本包也附带一份 overlay，供不应运行那套安装流程的环境使用。

官方注册（由 REA 写入配置行）

先看只读计划，再执行： sh
npx -y rea-agents@6.8.0 setup --client dsh --skill=false --dry-run --json
npx -y rea-agents@6.8.0 setup --client dsh --skill=false --yes

安装流程会往 $DSH_HOME/cordis.patch.yml 写入一行，id 为 rea-mcp，serverName 为 rea，模块为 @deepseek-ai/dsh-mcp-client。这是全局补丁：对本机所有配置档生效，桌面应用也不例外。安装流程会保留无关的补丁和注释，只替换自己的启动器字段。跑完之后重启 dsh（退出并重开应用，或退出并重新启动命令行配置档），然后确认会话里出现 mcp__rea__ 工具。

本包已安装时，--skill=false 是正确选择。本包的服务商在 rank 400 提供适配过的 REA 工作流技能；官方安装流程会装的那份规范副本落在 ~/.agents/skills（设置了 $DSH_AGENTS_HOME/skills 时则是该路径），rank 500，同名技能在那里会被遮蔽，装了也只是多一份冗余副本。
（本包的服务商按 rank 优先。没装本包时，rea setup --skill 才是规范安装方式。）
用 rea doctor --client dsh --json 检查注册情况；只要那一行存在，就会看到健康且对齐的结果。rea uninstall 会删除 REA 那一行，以及 REA 安装过的技能。

Node 版本门槛。 REA 6.8.0 的 setup 对 Node 有硬性门槛：只接受 ^22.23.4、^24.22.1 或 >=26.12.1，其他版本一律拒绝。MCP 服务器本身在被拒绝的版本上运行正常，所以只有 setup 会被挡住。计划里报出这道门槛时，可以这样处理：

- 把 Node 升级到可接受的版本，再重新运行 setup。
- 在可接受的运行时下运行同样的 REA setup，用 npx -y node@24.22.1 指向已安装的 rea-agents/scripts/rea.mjs 入口。
- 跳过 setup，改用下面的 pack overlay，它不需要 rea setup，也没有 Node 门槛。

Pack overlay（无需 setup）

patches/rea-mcp.yml 只有一行 insert，id 和 serverName 与官方注册相同，启动器是 npx -y rea-agents@6.8.0 mcp，并带 toolCallTimeoutMs: 600000。一次性用法，只对某次配置档运行生效： sh
dsh --profile web --patch /absolute/path/to/dsh-rev-eng/patches/rea-mcp.yml

要长期使用，就把这一行 insert 合并进配置档补丁（$DSH_HOME/profiles/<name>/cordis.patch.yml），或者合并进 home 补丁（$DSH_HOME/cordis.patch.yml），然后重启 dsh。是合并，不是替换：文件里可能还有别的补丁。

绝不要同时启用官方注册和 overlay。 两者都用 serverName: rea，而 dsh 拒绝两个 server 名相同的 MCP 条目，即使它们位于不同层。结果就是 duplicate-server-name 加载失败，工具缺失。二选一，不要都用。

挂载后的预期

- 工具在模型看来是 mcp__rea__<rawName>，例如 mcp__rea__open_binary。指南里用的是 REA 的原始名称；调用时加上前缀。
- 超时： dsh 每行设置一个 toolCallTimeoutMs，默认 60000 ms，对真实分析来说远远不够。overlay 设为 600000 ms；官方那一行默认没有超时，所以在它的 config 下加上 toolCallTimeoutMs: 600000（REA 之后重写自己那一行时，会保留调用方拥有的配置字段）。REA 自己的静态分析预算默认 300000 ms，而冷启动时原生服务商导入可能更久。
- 上下文开销： 这一行激活期间，229 个工具会进入模型的工具列表。上下文预算紧张时，只在逆向工程会话里启用挂载，不要当成永久的全局默认。
- 连接行为： 启动不起来的行不会中断 harness。会话照常启动，只是没有 REA 工具，客户端会记录 mcp-client(rea) 行。npm 缓存冷的时候，第一次 npx 启动还要付一次包下载（几秒，不是几分钟）；缓存热了不到一秒就能连上。

用法

提示词通过 rev-eng 路由选中这个 pack，然后由技能干活。几个例子：

| 你说 | 加载什么 |
| “解释 Notes 应用如何渲染搜索结果，细到二进制层，并给我看证据。” | rev-eng → reverse-engineer-anything（原生分析；需要引擎） |
| “检查这个 Electron 应用的 app.asar，列出它的 IPC 通道，并与上一个版本对比。” | rev-eng → reverse-engineer-anything（静态 JavaScript，无需原生引擎） |
| “把这个应用的外观重做成原生 Mac 应用。” | rev-eng → reverse-engineer-anything 收集证据，再用 BAMA 的 clone |
| “为菜单栏剪贴板管理器写一份一页纸的简报。” | bama → app-brief |
| “先写窗口吸附器的规格，再截取每个屏幕并运行测试。” | bama → app-brief → user-stories → new-mac-app → build-and-verify |

你可以跳过路由器，直接按名字点名技能，或者输入 /bama 或 /rev-eng 直接启动。一次只加载一个技能；每个技能都会告诉智能体下一个技能是什么。

工作原理

- 这个包是一个 dsh bundle：package.json 把 dsh.bundle.patch 指向 cordis.patch.yml，由它把名为 dsh-rev-eng 的 rev-eng-skills 行插入配置档的 composition。
- 这一行会挂载 src/index.js 里的插件，插件在打包的 skills/ 目录上注册一个技能服务商。服务商每次 list() 都会扫描目录，用 src/frontmatter.js 里的扁平 frontmatter 解析器读取每个 SKILL.md，并按需提供正文，以技能目录作为资源基准。
- 服务商以 rank 400、来源 bundled 运行。这胜过 ~/.agents/skills 里的副本（rank 500），但项目技能根目录（rank 100 到 200）和配置的自定义目录（rank 300）仍然优先。~/.dsh/skills 里的直接放入副本也是 rank 400，所以两种安装渠道不应混用。
- rev-eng 路由器作为普通技能打包。bama 保留 disable-model-invocation: true，所以由用户用 /bama 调用；其余 22 个技能可由模型调用。
- 实时编辑：打包的服务商每次 list 都会重新扫描 skills/，但不安装文件监视器，技能注册表会缓存目录快照。编辑已安装技能的正文，会在下一次 skill 调用时生效；向已安装的包添加新的技能目录，需要新会话。直接放入副本的路径使用 dsh 监视的本地服务商，所以在那里新增内容无需重启即可出现。

为什么用 bundle 而不只是技能

技能就是纯 Markdown，一个技能目录不用这个包也能工作：那就是方案 2。插件不是技能的副本；它是技能的安装机制。包本身无法让 dsh 加载技能文件。在支持的 dsh 版本线（0.2.1）中，插件 bundle 只能通过 dsh.bundle.patch 贡献配置档层；未声明 bundle 的依赖会作为普通包，dsh 不会扫描包内的文件。也没有哪个 manifest 字段能把技能目录挂载到这一行的位置。

所以安装路径有三环：bundle 补丁插入 rev-eng-skills 行，这一行挂载 src/index.js，服务商再从 import.meta.url 解析出 skills/，提供技能目录。服务商是最小的可移植做法。customSkillDirs 行需要绝对路径：dsh 解析相对条目时以进程工作目录为基准，那是用户的工作区，不是配置档或包目录。硬编码 node_modules/dsh-rev-eng 路径则要假定配置档名称和目录布局。dsh 自己打包带技能的 bundle 也是同样做法：dsh-skill-badge 和 dsh-skill-office 都针对包内相对资源目录注册服务商，dsh-experimental-badge-skill-bundle 则是一个 bundle，整个补丁就是挂载其服务商的那一行。

bundle 相比直接复制技能目录多了什么：

| | Bundle | 直接复制 |
| 安装 | dsh plugin --profile <name> add dsh-rev-eng | 克隆仓库，然后运行 scripts/install.sh |
| 作用范围 | 单个配置档 | 所有监听所选技能根目录的配置档 |
| 更新 | 安装下一个包版本 | 重新运行安装脚本 |
| 移除 | Plugins UI，或 dsh plugin --profile <name> remove dsh-rev-eng | scripts/install.sh --uninstall |
| 可见性 | 列在 Plugins 下，可启用或禁用 | 技能根目录里的普通文件 |

代价是服务商 API 这一层：src/index.js 和 src/frontmatter.js 里约 200 行无依赖代码，要跟着 dsh 各版本跟踪 ctx.skills。这是安装渠道的成本，不是技能的成本。

去掉插件层并不会让包变成「只有技能」：dsh plugin add dsh-rev-eng 会装上一个惰性依赖，它的 23 个技能目录没人提供服务。那时这个包就只是给选项 2 用的 tarball，npm/Git 安装路径也不复存在。只要 dsh-rev-eng 还以包的形式分发，就保留 bundle；如果技能只需要存在于你自己的机器上、你又不想引入配置档依赖，就选选项 2。

与上游的差异

技能就是上游的工作流，换成了 dsh 的工具名、路径习惯和客户端配置；技术实质、技能名、参考文档、脚本、模板和示例规格都保留。REA 的客户端专用连接指南按 dsh 重写，并新增了一份 dsh harness 指南。BAMA 的嵌套布局被展平，跨技能链接重新指向，specs/ 移到 app-brief 技能下，客户端专用的元数据目录被删除。

映射表、REA 官方客户端的处理方式，以及每个技能的变更日志，都在 docs/adaptation.md。逐文件的详细日志仓库的 notes/bama-adaptations.md 和 notes/rea-adaptations.md 里有说明。

故障排查

技能没有列出来

- 把 bundle 安装到你实际启动的配置档，然后在该配置档上启动新会话。安装之前就已启动的会话，不会加载 bundle 的目录。
- 只用 dsh plugin add 创建的配置档没有可启动的应用 bundle。请安装到随应用发布的配置档（web、tui、headless），或者通过 Plugins 页面安装到桌面配置档。
- 用 dsh --profile <name> --dump-config 检查有没有 # == dsh-rev-eng 层。如果这一层缺失，说明包没有安装到该配置档。
- 如果 bundle 和 drop-in 副本都装了，重名的技能按服务商顺序解析。删掉其中一个渠道。
- 如果你在已安装的包内编辑或新增了技能目录，请重启会话：打包的服务商不会监听文件系统。

REA MCP 工具不见了

- 确认存在对应行：官方 setup 之后是 home 补丁 $DSH_HOME/cordis.patch.yml，永久 overlay 合并之后是配置档补丁，一次性运行则用 --patch 参数。
- 任何配置改动之后都要重启 dsh：home 和配置档补丁层在启动时组合。行加载之前就已启动的会话，永远不会获得这些工具。
- 运行 rea doctor --client dsh --json，从 REA 一侧检查注册情况。
- 检查有没有重复的 serverName: rea 行，官方 setup 和 overlay 同时启用就会产生。删掉一行并重启。
- 确保 npx 在 harness 的 PATH 上：该行把 npx 作为子进程启动，会继承 PATH，但不继承以凭据命名的变量和 DSH_* 变量。npm 缓存是冷的，首次连接会更慢；先重试一次再排查。
- 如果工具存在但调用失败，多半是该行触发了 toolCallTimeoutMs（默认 60000 ms）。调大它，并注意客户端超时并不能证明 REA 已经完成或释放了分析会话。
- 审批提示来自 harness，不是 REA：会话的权限预设决定允许什么。无人值守运行时，会报告被阻止的操作，而不是重试。
- 该行启动不了时，去 harness 日志里找 mcp-client(rea) 行：首次连接和发现失败、重连尝试，以及最后的 giving up ... tools unregistered 行都在那里。最快的独立检查方法，是从终端启动同一个配置档。

BAMA 构建失败

- 验证工具链：xcode-select -p 会打印开发者目录，swift --version 报告 Swift 6.2 或更高版本。缺少命令行工具时，用 xcode-select --install 安装。
- BAMA 面向 macOS 26 及更高版本，使用 Xcode 26 工具链。旧工具链会在应用代码运行之前，就在生成的包上失败。
- 会话具备 harness 的 computer-use 能力时，视觉检查需要用到它；否则技能会退回到向你索取截图。请说明无法提供时，请明确说明。
- Windows：技能可以安装，但 BAMA 技能用来构建原生 Mac 应用，在 Windows 上跑不起来。

卸载

- Bundle： 在 Plugins UI 里打开 bundle 页面，卸载 dsh-rev-eng；命令行配置档则运行 dsh plugin --profile <name> remove dsh-rev-eng。桌面配置档请用 Plugins 页面。
- Drop-in 副本： 运行 bash scripts/install.sh --uninstall（加上 --project <dir> 或 --user-agents 指定当初安装的目标）。PowerShell 脚本接受 -Uninstall，目标参数相同。
- REA MCP： 走完官方安装流程后，运行 rea uninstall 删掉那一行（以及 REA 装上的技能）。手工合并的 overlay 行不归 REA 管：从补丁文件里删掉那段 insert。一次性 --patch 运行不会写入任何永久内容。
- Bundle 和 drop-in 副本之间不共享任何配置，卸载其中一个不影响另一个。

来源与许可

- PROVENANCE.md 记录上游仓库、锁定的 commit、许可证和刷新流程。
- LICENSE 是 MIT：本包的适配部分，加上保留的上游声明——REA（Copyright (c) 2026 morluto）和 BAMA（Copyright (c) 2026 Dave Ebbelaar）。
- CHANGELOG.md 列出 0.1.0 的内容。

负责任地使用

REA 是双用途分析工具包。目标执行是真实的：运行时工具会挂到进程上，能改动文件、内存和网络状态，客户端外面的 harness 沙箱拦不住。只分析你有权分析的目标，范围要写清楚。用 REA 之前先读上游的免责声明。

开发 sh
npm test # syntax checks + plugin unit tests
npm run lint:skills # validate every SKILL.md, link, and frontmatter rule
./verification/verify.sh # acceptance gate in an isolated DSH_HOME
./verification/verify.sh --full # plus a live boot and REA MCP connection check

验收门不会碰你真实的 dsh home 或桌面配置档。
docs/adaptation.md 说明如何从上游重新同步，verification/REPORT.md 记录实际测过的安装流程和已知限制。