vlad/reverse-skills-max
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
reverse-skills-max/vendor-new/rev-skills/CLAUDE.md

17 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

仓库性质

通用逆向工程 AI 技能库（122 个技能），发布形态有三个：npm 包（bin/install.mjs 安装器）、Claude Code 插件市场（.claude-plugin/marketplace.json）、以及可被任意 Agent Skills 兼容运行时读取的 .claude/skills/ 目录。

内容主体是 Markdown 技能文档，工具代码是零依赖 Node.js（>=22，当前受支持 LTS，ESM）。没有构建步骤——技能即目录，改完跑校验即可。

仓库按 LF 存储（.gitattributes：* text=auto eol=lf）。校验与转换按 LF 解析 frontmatter 与能力注册表，Windows 上 core.autocrlf=true 的旧检出会把技能读成 CRLF 并让 node validate.mjs 整库报错（missing frontmatter + 能力标签全判未注册）；重新检出即可，或把工作树按 LF 归一（lib/frontmatter.mjs 自身已容错 CRLF，但注册表读取还没有）。

双许可：技能文档内容 CC BY 4.0，工具代码（bin/、validate.mjs、tests/）Apache-2.0。新增文件注意落在正确一侧。

常用命令

npm test                                        # 全量：结构校验 + 单元测试
node validate.mjs                               # 只跑结构校验，输出 OK: 122 skills validated
node --test tests/validate.test.mjs             # 单跑一个测试文件
node --test --test-name-pattern="good-skill" tests/*.test.mjs   # 按用例名过滤

node bin/capindex.mjs                           # 重新生成能力索引（改 capabilities 声明后必跑）
node bin/capindex.mjs --check                   # 只校验索引是否过期（npm test 已含）

node bin/toollife.mjs check                     # 命令/API 登记表一致性 + 时效（npm run toollife；npm test 已含一致性）
node bin/toollife.mjs candidates                # 技能里出现但未登记的命令候选
node bin/toollife.mjs stale                     # 按超期排序的待核验项
node bin/toollife.mjs smoke                     # 本机探测（仅报告，CI 机器不必装）

node bin/examplecheck.mjs                       # 技能示例代码块语法检查（npm run examples；需 python3/bash，缺失时跳过）
node bin/auditstate.mjs status                  # 增量审查：哪些技能内容在复核之后又变了（= 下一轮审查波的工作集）
node bin/auditstate.mjs update <技能...>         # 复核后回填（写当前 hash + 日期）
node bin/probelist.mjs                          # 由登记表生成 probe.sh 的工具清单（--check 校验新鲜度，npm test 已含）

npx rev-skills install --target <claude|gemini|cline|codex|cursor|copilot|windsurf|dsh|all> \
  [--global|--project] [--dry-run] [--link] [--force]
node bin/convert.mjs --target <cursor|copilot|windsurf> --out <dir>   # 技能 → 规则文件转换（调试用）

node bin/dsh.mjs check [--dir <skillsRoot>] [--json]   # 按 DSH 发现规则校验技能根：通过则输出 OK: N skills DSH-compatible
node bin/dsh.mjs preset spec                    # 打印预设配置（含技能根解析结果与 REV_SKILLS_DIR 覆盖）
node bin/dsh.mjs preset status [--profile-dir <dir>] [--json]   # 只读检查 profile 是否已启用该 bundle
node bin/dsh.mjs preset install [--profile-dir <dir>] [--force] [--apply]    # 默认 dry-run，--apply 才写（写前备份）
node bin/dsh.mjs preset uninstall [--profile-dir <dir>] [--apply]           # 默认 dry-run，有备份时从备份还原
npx rev-skills install --target dsh --global    # 技能装进 DSH 技能根（~/.dsh/skills）
npx rev-skills install --target dsh --project   # → .dsh/skills

node bin/wxsource.mjs kanxue list [--board re] [--pages 2] [--md]     # 看雪论坛列表（经验采集源）
node bin/wxsource.mjs kanxue thread <帖子ID> [--md]
node bin/wxsource.mjs wechat <文章URL> [--md]

node validate.mjs 输出的技能数必须等于 .claude/skills/ 下 re- 目录数——这条已有自动检查（tests/counts.test.mjs 比对 README / README_EN / AGENTS / CLAUDE / package.json / marketplace.json 六处的计数），不必再靠人工 grep。

检查分层（npm test = validate + 203 项测试；该计数由 tests/counts.test.mjs 自校验，增删测试后需同步此处）：

层 查什么 落点
结构 frontmatter / 命名 / 能力标签 / 链接 / guard / 章节 validate.mjs
一致性 计数同步、指纹表覆盖、登记表与路由、审查状态覆盖 tests/counts tests/fingerprints tests/toollife tests/review-state
语法 技能里 python / shell 示例块（含 sh 内嵌 python heredoc） tests/examples（无解释器则跳过）
事实 已修缺陷的回归断言（错的说法不得写回）、格式断言 fixture tests/audit-regressions tests/format-fixtures
预算 SKILL.md ≤240 行、单分支 ≤600 行、必备章节仍在 tests/skill-budget

DSH（DeepSeek Harness）集成

两种集成形态，改动时都要与计数/清单同步：

  • 技能目录路线：npx rev-skills install --target dsh [--global|--project]——写入 DSH 技能根（全局 <dshHome>/skills，项目 .dsh/skills）。DSH 按 Agent Skills 风格扫描，一层深度（<root>/<name>/SKILL.md），frontmatter 的 --- 分界行与 YAML 合法性由 DSH 严格执行：不合法时记告警并静默跳过该技能（新技能要跑 node validate.mjs，别只看 npm test 的汇总行）。
  • 独立预设路线：根包自身即 bundle（rev-skills），根 package.json 用 "dsh": { "bundle": { "patch": "./dsh.patch.yml" } } 指向仓库根的补丁文件，补丁插入预设行 preset-rev-skills（config.id = rev-skills），该预设用 includeDefaultRoots: false + customSkillDirs 给预设自带本库 .claude/skills 技能层（该提供方实例不再重复扫描项目/用户技能根；技能服务读取时仍把预设层与全局层合并，同名以预设层为准，其他预设不受影响）；目录可用环境变量 REV_SKILLS_DIR 覆盖。启用方式：dsh plugin --profile <profile> add rev-skills（宿主的包管理器会自动登记 dsh.profile.bundles 行；本地路径用 link: / file: 规格），或仓库自带 CLI node bin/dsh.mjs preset install --apply。

必须成对同步的项（历史上漏同步过）：根 package.json 的 dsh.bundle.patch ↔ dsh.patch.yml 实际路径 ↔ 该路径必须出现在根 package.json 的 files 里（pnpm 按 files 复制 file: 依赖，漏列则 dsh plugin add 报 failed to read overlay … ENOENT 并整体回滚，测试有回归断言）；根 package.json 的 name ↔ profile 里 dsh.profile.bundles 的对应行与同名依赖；补丁里的 config.id（rev-skills）↔ docs/dsh-integration.md 的说明。

标准预设会裁剪超过 8192 字符的工具结果，本库 32 个 SKILL.md 的文件字符数超过该阈值（CRLF 检出下为 34；node bin/dsh.mjs check 会逐条报出），被加载时可能被截断（完整内容直接读文件）。集成全貌与排错表见 docs/dsh-integration.md。

架构：三层技能图，按状态机运转

re-analyze（entry，唯一入口）
  └─ 12 个大类网关（type: gateway）：re-binary-core / re-malware / re-firmware / re-protocol /
     re-mobile / re-anti-analysis / re-cracking / re-vuln / re-ctf / re-managed / re-forensics / re-feedback
        └─ 原子技能（type: atomic，109 个）

这不是调用链，是状态转移：triage → route → skill 执行 → 产出证据 → 再路由（循环）。每个技能执行后产出新证据，证据决定下一跳。技能之间靠 [[技能名]] 链接互引，靠会话变量（RE_OS/RE_TOOLS/RE_GOAL/RE_DECOMPILER/RE_DEPTH/RE_REPORT/RE_AUTH/RE_VISITED）传状态。

控制文件是单一事实源，改路由逻辑只需改这些文件，不要散落到各技能：

文件 职责
.claude/skills/re-analyze/SKILL.md 入口四步：环境探测 → 偏好分级询问 → 任务识别 → 路由
re-analyze/references/triage.md 入口决策表：目标 + 输入文件 → 编排路径；第 0 步定 RE_AUTH
re-analyze/references/rerouting.md 中途再路由：A 表「证据特征 → 触发技能」，B 表「卡住信号 → 换路」
re-analyze/references/preferences.md 偏好询问分级（Level 0 用默认值直接开始 / Level 1 完整问 5 项）
re-analyze/references/analysis-contract.md 分析契约：上下文清单（按域展开）、数据契约（核心字段 + 域扩展字段两层）、独立复核、调查预算
re-analyze/references/platform-tips.md 平台经验库（最高原则：默认沙箱；内存读取默认转储优先）
re-analyze/references/system-fingerprints.md 系统识别指纹表（载体格式 → 家族 → 系统 → 易混淆对 → 负判据；新增系统分支须同步加行）
re-analyze/references/cross-system-models.md 跨系统误判总表（十类误判 / 共同规律 A–F / 异常速查表；判定 hook·dead code·恶意 前的强制前置）
re-analyze/references/capabilities.md 能力注册表（capabilities frontmatter 的合法标签全集）
re-analyze/references/probe.sh 环境探测脚本（OS/ARCH/CORES/MEM/工具清单）

能力层：技能用 capabilities: [tag1, tag2] 声明「提供哪些可执行分析动作」，标签必须在 capabilities.md 注册表内。原子技能必须声明（入口/元网关可省略）。声明的消费端是 re-analyze/references/capability-index.md（机器生成的「能力 → 技能」反查表：node bin/capindex.mjs 生成、npm test 校验过期、--check 单查）。路由已按能力匹配：triage.md 与 rerouting.md 的表格带「需要能力」列，技能列是索引反查结果——新增/修改路由行时必须先定能力标签再反查技能，不能只写领域名。CI 四条防漂移：标签不得悬空｜原子技能必须声明｜路由能力列须在注册表内｜路由标称能力须被本行技能声明｜索引须与声明同步。网关选择树里的技能链接用 [[re-xxx]]（能力：tag） 标注（选择树段内强制，npm test 校验标注与声明一致；无「能力：」前缀的括号视为普通说明，不参与校验）。

guard 字段：敏感技能必须带机器可读安全前置声明，JSON 格式 {"require_authorization": true, "forbidden": ["行为标签"]}。入参与 RE_AUTH（owned / ctf / research / unknown）联动——require_authorization: true 时仅 owned/ctf/research 可执行，unknown 只做静态分析并先询问归属。

技能目录布局：每技能一个目录，必含 SKILL.md，可选 references/*.md（深度知识、坑、探针）。references/*.md 的文件名（去扩展名）本身是合法的 [[链接]] 目标。

validate.mjs 校验规则（改技能前必读）

frontmatter 解析的唯一实现在 lib/frontmatter.mjs（validate.mjs 与 bin/convert.mjs 共用；支持简单 scalar / 块标量 > | / 内联 flow list 与 JSON，其余 YAML 特性不支持）。新增 frontmatter 写法前先扩展该模块并补测试——历史上校验与转换各写一套解析，104 个技能的 description 因此在校验侧被解析成字面量 >，非空校验空转。

validate.mjs 是结构闸口，以下任一不满足即 npm test 失败：

  • frontmatter 必须有 name（必须等于目录名）与非空 description；name 以 re- 前缀
  • description 必须同时含 CJK 与拉丁字母（中英触发词约定——英文环境也要能命中该技能）
  • type 只认 atomic / entry / gateway（缺省视为 atomic）
  • 原子技能且是叶子目录（无子技能目录）必须含 ## 工具准备 章节；入口/网关豁免
  • 正文所有 [[xxx]] 必须解析：技能链接 [[re-xxx]] 指向技能；裸 references 链接 [[文件名]] 必须落在本技能自己的 references/ 内；跨技能引用别人的 references 必须限定前缀 [[re-xxx/文件名]]——先建文件再加链接，否则断链（同名 references 普遍：gotchas.md 33 个、decision-tree.md 13 个）
  • capabilities 必须是非空 YAML 内联 list，且每个标签在 capabilities.md 注册表内（新标签要先注册）
  • guard 必须严格是 {"require_authorization": <bool>, "forbidden": [<非空字符串>]}，否则报错

技能正文结构规范见 docs/skill-template.md（原子技能固定章节顺序：任务分类器 → 何时使用/何时不用 → 工具准备 → 操作步骤 → 跨域联合 → 常见坑与陷阱；网关另有一套）。

新增/修改技能的标准流程

  1. 按 docs/skill-template.md 建 .claude/skills/re-xxx/SKILL.md（知识/操作分离：机制原理留正文，易变参数如槽位索引/offset 放 references/probes.md 探针层）
  2. 挂载（缺一即孤儿技能）：网关 SKILL.md 的子技能清单 + triage.md 路由表；若是「看到某证据就该触发」的技能，还要挂 rerouting.md A 表
  3. 声明 capabilities（新标签先加进 capabilities.md 注册表）；敏感技能加 guard
  4. 同步计数与导航——计数散落多处，按清单逐处核对（曾因只改"记得的几处"漏过 5 处）：
    • README.md：技能总数（首段）、「技能导航（N）」标题、前言「12 大类网关 → N 原子技能」、对应网关的技能行
    • README_EN.md：同上 4 处（## Skill map (N)、N atomic skills）
    • AGENTS.md：技能总数、原子技能数
    • package.json / .claude-plugin/marketplace.json：description 里的技能数
    • CLAUDE.md：技能总数（仓库性质段）、OK: N skills validated 示例、架构图里的原子技能数
    • 自查方式：grep -rln "<旧数>\|<旧原子数>" --include="*.md" --include="*.json" .，逐个候选文件人工核（不要用"旧数+单位"的复合模式，全角括号/措辞差异会造成假阴性）；TODO.md、docs/audit/、历史注释里的旧值是当时事实，保留不动
  5. npm test 必须输出 OK: N skills validated 且 N 与实际目录数一致

开发工作流：spec → plan → 波次 → 审查波

本仓库按「波次」推进，历史全在 docs/superpowers/：

  • specs/YYYY-MM-DD-*-design.md —— 设计文档（用户批准后落地）
  • plans/YYYY-MM-DD-*.md —— 实施计划（任务拆解，带 - [ ] 复选框与逐步 commit 点，供 subagent 逐任务执行）
  • 这两个目录是历史存档（冻结于各自日期，不随技能修订同步）——可能保留已修正的过时表述，不要当现行技术指引检索/引用；当前事实一律以 .claude/skills/ 为准，已修正错误与核验依据见 docs/audit/
  • 每任务一张 Files 清单，commit 只 git add 本任务列出的文件，严禁 git add -A
  • 多计划并行时约定「文件集隔离」——不交叉修改对方文件
  • 变更后收尾是审查波：grep/抽查断言事实性（命令是否可执行、字段值是否与官方文档一致），发现的错误以 fix: 提交；TODO.md 记录了「增量审查机制」待办（用内容 hash 跳过未变技能，把审查成本从 O(技能总数) 降到 O(变更数)）

commit message 用中文，前缀：feat: / fix: / chore: / enhance: / docs: / 经验:。

发布流程：npm test 通过 → git tag → npm publish → 同步 package.json 与 marketplace.json 的版本号（历史上常见漏同步，需成对检查）。

仓库红线（内容与输出）

  1. 呈现中性：选项/建议禁用「最推荐」「强烈建议」等最高级强推措辞，最多用「推荐」，由用户自决
  2. 隐私脱敏：内容禁止具体到某个项目/公司/产品，暗示也不行（行业+规模+地域组合、专有协议名、内部代号）；本库公开发布，本地入库同样受约束
  3. 不用 emoji：文档与输出一律纯文本表达
  4. 事实核验：命令必须可执行、字段/格式断言以官方文档为准——本库多处断言曾因想当然出错（如 dex opcode 值、pclntab 头长度），写断言前先验证
  5. 授权边界：全库面向授权范围内的安全研究；破解/绕过类路径受 RE_AUTH 与 re-cracking 授权边界约束，不得写成无条件可用的操作指引
  6. 内容边界：.claude/skills/ 是随库发布的分析内容——不写审查历史（日期戳、"本次补录/已完成"叙事、finding 编号、✅ 进度标记、docs/audit/ 引用）；那类内容进 docs/audit/，开发约定进 CLAUDE.md。技能内容只写"是什么/怎么做"，不写"何时改的/谁审的"

本地分析产物（勿提交）

.gitignore 已排除 /aaa/、/analysis/、demo_target.*、sandbox.sh——这些是本地逆向产物与沙箱脚本，不得提交到公开仓库。新增本地工作目录时同步加进 .gitignore。

经验采集

bin/wxsource.mjs 抓取看雪论坛/微信技术文章 → 按 re-feedback 网关蒸馏（坑格式：**标题**：现象——…；原因——…；对策——…）→ 归域 → 追加到目标技能的 references/experience.md（SKILL.md 保留精选条目 + 链接）→ npm test 校验 → 提交 经验: 第N轮扫描入库X篇——<篇目>。入库前必须脱敏自检与 grep 去重。