mbackschat/atari-st-reverse-engineer-skill

# Atari ST 逆向工程技能 这是一项 Claude Code 技能，用于指导 Atari ST (Motorola 68000) 二进制文件的逆向工程，产出三个交付物： - **`SOURCE.txt`** — 完全注释的 68000 反汇编列表 - **`ANALYSIS.md`** — 技术分析文档 - **`MANUAL.md`** — 用户手册（根据程序类型调整） 此外还会生成一个 **`CONTEXT.md`**，用于捕获所有累积的知识，以便在未来的会话中使用。 该方法论、提示词、Python 工具和参考资料均经过通用化处理，适用于任何 Atari ST 二进制文件——不仅是开发工具，还包括游戏、演示、GEM 应用程序、TSR 和实用程序。 ## 安装 此仓库已包含 `.claude/skills/` 目录结构。将其复制到你的项目中： ``` # 克隆 repo git clone https://github.com/mbackschat/atarist-reverse-engineer-skill.git # 将 .claude 目录复制到你的项目中 cp -r atarist-reverse-engineer-skill/.claude your-project/ ``` 或者，为了保持可更新，将其作为 Git submodule 添加到项目根目录并创建符号链接： ``` cd your-project/ git submodule add https://github.com/mbackschat/atarist-reverse-engineer-skill.git vendor/atarist-reverse-engineer-skill mkdir -p .claude/skills ln -s ../../vendor/atarist-reverse-engineer-skill/.claude/skills/atarist-reverse-engineer-skill .claude/skills/atarist-reverse-engineer-skill ``` Claude Code 会自动发现 `.claude/skills/` 下的 `SKILL.md` 文件——无需额外配置。 安装后，该技能将显示为 `/atari-st-reverse-engineer` 斜杠命令。 ## 快速开始 ### 作为 Claude Code 技能 ``` /atari-st-reverse-engineer path/to/BINARY.PRG ``` Claude 将自动遵循 7 阶段剧本：扫描二进制文件、确定程序类型、识别段、使用并行代理分析代码、构建注释、生成所有交付物、审查它们并添加伪代码。 ### 手动工作流 如果你更喜欢逐步控制，请遵循 [plan.md](.claude/skills/atarist-reverse-engineer-skill/plan.md) —— 完整的逆向工程剧本。 ## 功能 该技能编排了一个完整的逆向工程流水线： ``` Binary File (.PRG / .TOS / .ACC / raw) │ ├─ Phase 1: Setup ──────── Copy disassembler, install capstone via uv │ ├─ Phase 2: Initial Scan ── Parse header, extract strings, find system calls, │ map subroutines, auto-detect data regions, │ determine program type (tool/game/demo/GEM/TSR) │ ├─ Phase 3: Deep Analysis ─ Launch parallel agents to analyze each section: │ trace logic, identify algorithms, document │ subroutine signatures (entry/exit registers) │ ├─ Phase 4: Annotate ────── Build annotations.py with block comments │ (routine headers) and inline comments │ (per-instruction explanations), regenerate listing │ ├─ Phase 5: Document ────── Write ANALYSIS.md (technical, with global variable │ maps, utility catalog, design patterns, background │ primer) and MANUAL.md (adapted to program type) │ ├─ Phase 6: Review ──────── Cross-check all deliverables against raw binary │ with parallel reviewer agents; verify annotation │ coverage (target ≥60% of instructions commented) │ └─ Phase 7: Pseudocode ─── Write pseudocode for key algorithms and main logic, insert into ANALYSIS.md subsystem sections ``` ## 文件结构 ``` your-project/ ├── .claude/ │ └── skills/ │ └── atarist-reverse-engineer-skill/ │ ├── SKILL.md Skill definition (YAML frontmatter + instructions) │ ├── README.md Skill-internal documentation and changelog │ ├── plan.md Step-by-step RE playbook (7 phases, 10 tips) │ │ │ ├── prompts/ │ │ ├── analysis-sections.md 14 template prompts for code section analysis │ │ │ (generic + tool + GEM + game/demo + sound + TSR) │ │ ├── annotation-guide.md Style guide with mandatory decode rules and │ │ │ structure field reference (basepage, DTA, Line-A) │ │ └── review-checklist.md 4 reviewer agent prompts including coverage check │ │ │ ├── scripts/ │ │ ├── disasm_atari.py 68000 disassembler & analyzer (Capstone-based) │ │ ├── build_annotations.py Fragment merger + density stats reporter │ │ ├── annotations_template.py Starter annotation file with format examples │ │ └── requirements.txt Python dependency: capstone>=5.0.7 │ │ │ └── reference/ │ ├── tos-quick-ref.md Condensed TOS reference (all calls, vectors, memory map) │ ├── gem-quick-ref.md GEM AES/VDI parameter reference │ ├── TOS.TXT Complete TOS system call reference │ ├── GEMDOS.TXT Full GEMDOS reference │ ├── BIOS.TXT BIOS quick reference │ ├── BIOS_Calls _Trap_13.TXT BIOS Trap #13 detailed reference │ ├── XBIOS.TXT XBIOS reference │ ├── AES.md Full AES reference with parameter tables │ ├── AES_CALL.TXT AES function calls (detailed) │ ├── GDOS_INF.TXT GDOS reference │ ├── SALAD.TXT System Assembly Language documentation │ ├── 68000_Assembly_Language.txt 68000 instruction set reference │ ├── INTRO68K.txt Introduction to 68000 programming │ └── atari.s Atari ST hardware register definitions │ └── README.md This file ``` ## 反汇编器 `scripts/disasm_atari.py` 是一个独立的 Python 工具，用于读取任何 Atari ST 二进制文件并生成带注释的汇编列表。 ### 用法 ``` # 初步侦察 — 仅显示提取的字符串 python disasm_atari.py BINARY.PRG --strings-only # 使用默认前缀进行完全反汇编 python disasm_atari.py BINARY.PRG --prefix TOOLNAME ``` ### 自动执行的操作 - 解析 28 字节的 Atari ST 可执行文件头（$601A magic） - 提取所有可打印字符串并进行质量过滤（拒绝二进制噪声） - **自动检测数据区域**（字体、字符串表、位图），方法是通过启发式算法：查找没有代码引用或高密度 ASCII 的连续区域 - 通过从每条 TRAP 指令向后扫描以找到函数编号压入操作，来识别 **TRAP #1** (GEMDOS)、**TRAP #13** (BIOS)、**TRAP #14** (XBIOS) 系统调用 - 通过检测 `MOVE.W #200,D0` (AES) 或 `MOVE.W #115,D0` (VDI) 来识别 **TRAP #2** (GEM AES/VDI) 调用，并尽力从参数块中解析函数 - 识别 **Line-A** 图形调用（$A000–$A00F） - 映射所有 **BSR/JSR** 调用目标（子程序入口点） - 映射所有 **Bcc/BRA** 分支目标 - 查找所有 **RTS/RTE** 指令（子程序边界） - 解析 **LEA xxx(PC)** 字符串和数据引用（导出到 analysis.json） - 生成基于 Capstone 的反汇编，并将上述所有内容作为注释包含在内 ### 你在分析期间添加的内容 - **`KNOWN_SUBS`** 字典：将偏移量映射到有意义的子程序名称 - **`SECTIONS`** 列表：定义带有描述的段边界 - `annotations.py` 中的 **`DATA_REGIONS`** 列表：手动标记字体数据、字符串表、精灵数据（补充自动检测） - **`annotations.py`**：块注释、行内注释和数据区域（从工作目录加载） ### 内置 TOS 数据库 反汇编器包含以下功能的完整数据库： | 数据库 | 覆盖范围 | |---|---| | GEMDOS | 38 个函数（$00–$57）：文件 I/O、内存、进程控制、控制台 | | BIOS | 12 个函数（$00–$0B）：设备 I/O、向量、键盘 | | XBIOS | 32 个函数（$00–$27）：屏幕、鼠标、定时器、声音、串口、软盘 | | AES | 65+ 个函数（10–130）：窗口、菜单、对话框、表单、资源 | | VDI | 50+ 个函数（1–134）：图形、文本、光栅、输入、属性 | | Line-A | 16 个函数（$A000–$A00F）：图形原语、鼠标光标 | 这些会自动为反汇编中的每个系统调用添加注释。 ## 注释系统 注释是通过**片段文件流水线**构建的： 1. **并行分析代理**各自写入一个片段文件（`annot_frag_SECTION.py`），其中包含五个 Python 字典：`BLOCK_COMMENTS`、`INLINE_COMMENTS`、`KNOWN_SUBS`、`SECTIONS`、`DATA_REGIONS` 2. **`build_annotations.py`** 将所有片段与自动生成的脚手架（来自 `analysis.json`）合并为单个 `annotations.py` 3. **`disasm_atari.py`** 在重新生成时导入 `annotations.py` 以生成最终的带注释列表 脚手架为每个检测到的子程序提供骨架块注释，并为所有自动检测到的系统调用提供行内注释。片段条目会覆盖相同偏移量处的脚手架条目。运行 `build_annotations.py --stats` 以检查注释密度（目标：60% 以上的指令行有注释）。 SECTIONS 条目接受 `(offset, name)` 和 `(start, end, name)` 元组格式。 有关格式，请参阅 `scripts/annotations_template.py`；有关风格指南，请参阅 `prompts/annotation-guide.md`。 ## 提示 1. **从字符串开始** — `--strings-only` 可在几秒钟内揭示程序的用途 2. **系统调用揭示结构** — 文件操作集群 = 文件管理器，Bconin = 键盘处理程序 3. **主循环总是存在的** — 找到跳回顶部的 `BRA.W`，那就是你的主循环 4. **A5 通常是基址寄存器** — 入口处的 `LEA (PC),A5` 意味着所有数据都是相对于 A5 的 5. **数据看起来像垃圾** — 当被反汇编时，无意义的指令 = 字体/字符串/表数据 6. **PEA $XXXX 是紧凑的** — `PEA $000BFFFF` = Kbshift(-1)，而不是随机地址 7. **低内存写入 = 向量** — 任何写入 $00–$3FF 的操作都是在安装异常处理程序 8. **ROL.L #8 循环字节** — 这是处理长字中每个字节的 68000 惯用写法 9. **检查帮助文本** — 许多 Atari ST 工具将其整个帮助屏幕嵌入为字符串块 10. **编写 CONTEXT.md** — 未来的你会感谢现在的你

标签：AI 编程助手, Atari ST, Claude Code, Demo 场景, GEM 应用, Motorola 68000, Python, TSR 程序, Wayback Machine, 二进制分析, 云安全运维, 云资产清单, 代码分析, 凭证管理, 反汇编, 技术文档生成, 无后门, 汇编代码, 游戏破解, 源码恢复, 软件考古, 逆向工具, 逆向工程