教学文档 · REVERSE-SKILL

// BEFORE YOU START

使用前须知

reverse-skill 是客户端无关的安全任务路由包，不绑定 OpenCode、Codex、Claude Code、Cursor 或其他单一平台。正常使用时，你不需要逐条执行本页命令：把仓库交给 AI，并让它完整阅读 README_AI.md 即可。

你真正需要做的只有一件事：在仓库工作区里，把下面这段启动提示交给 AI。AI 读完 README_AI.md 后必须自动检测平台、刷新工具索引、加载规则链并继续处理任务；只有授权、凭据、商业许可证或外部状态变更需要你确认。

请完整阅读 README_AI.md，并严格按照其中第 0 节自动完成当前环境的初始化与检查。
正常步骤请直接自动执行；只有需要我的授权、凭据、商业许可证，或会改变外部状态时再询问我。
完成后汇报已识别的平台、规则链、工具索引状态，然后继续处理我接下来给出的授权任务。
我不需要手动复制执行教学页里展示的流程命令。

AI 应主动完成配置并报告结果，而不是把 refresh、bootstrap、case-init 或测试命令重新抛给用户手工执行。

本页已按 v1.0.1 更新：当前基线为 41 条结构化路由（R0–R40）、163 条回归用例、42 个已跟踪模块、Windows + Ubuntu CI，并包含结构一致性与供应链版本固定门禁。

实际使用只需两步下面四格展示的是 AI 内部自动链路，不是用户操作清单

你 · 准备仓库打开仓库并让 AI 完整阅读 README_AI.md。 你 · 提交任务给出任务、授权范围与期望交付。 AI · 自动初始化识别平台、刷新索引、加载规则与按需配置。 AI · 自动执行路由、Case、Guard、Evidence、Review 与报告。

你会得到什么

41 条结构化路由规则（R0–R40）
客户端无关的专项 Skill 与可选适配层
本机工具索引与按任务自举的工具链
Scope、Timeline、Evidence、Finding、Review 证据链

AI 会自动检查什么

当前操作系统、发行版与真实安装路径
Git、PowerShell / Bash、Node.js 与 Python
当前任务是否需要 Java / JDK 或专项工具
缺失能力能否自动安装，或是否需要用户授权

先选择你的使用路径不同任务的授权与网络配置不同，不要混用

本地样本APK、EXE、固件等自有文件。使用 offline，禁止外连。

隔离实验室 / CTF自建靶场或公开比赛。使用 lab_only 或明确的比赛目标。

已授权线上目标必须有书面授权和资产清单。使用 authorized_target_only。

授权边界：任何目标操作前都必须完成 case-init，确保 auth.status=granted 且 network_profile 就绪。未就绪时只能进行只读规划与准备。

// INSTALLATION

AI 自动初始化与首次检查

读完 README_AI.md 后，AI 会自动完成本节：识别平台与安装路径、检查基础环境、生成本机工具索引、加载规则链，并在任务真正需要时按需自举工具。下面的命令用于展示它在做什么以及故障时如何核对，不是要求用户逐条运行。

自动执行原则：能由 AI 在当前工作区安全完成的步骤应直接执行并汇报；只有系统权限、商业软件许可、账户凭据、授权边界或外部副作用需要用户介入。

AI 识别平台与基础环境

AI 根据实际系统选择 Windows、Kali、普通 Linux 或 macOS 路径，并自行执行对应检查。缺少基础依赖时，它应先判断能否安全自动安装，而不是让用户照抄整段命令。

WindowsWindows PowerShell 5.1+ 或 PowerShell 7

git --version
powershell -NoProfile -Command "$PSVersionTable.PSVersion"
python --version
node --version

Git 有版本号；PowerShell ≥ 5.1；Python 3.x；Node.js ≥ 22.12。Java 只在 APK / Java 工具任务中需要。

Ubuntu / Debian / macOS普通 Linux 与 macOS 使用仓库根目录下的 Bash 脚本

git --version
bash --version
python3 --version
node --version

Python 必须是 3.x；macOS 自带 Bash 3.2 也能运行通用 bootstrap，无需强制安装新版 Bash。

AI 确认版本与仓库根目录

如果仓库已经打开，AI 直接从 README_AI.md 所在位置推导真实根目录，不需要用户重复克隆。只有尚未取得项目时，才选择稳定版 v1.0.1 或 main。

稳定版 v1.0.1

git clone --branch v1.0.1 --depth 1 https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
git status --short

主线最新版

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
git status --short

git status --short 默认无输出，说明刚克隆的工作区干净。若已有本地修改，更新前先确认这些修改是否需要保留。

AI 自动生成本机工具索引

README_AI.md 明确要求首次运行先刷新索引。AI 应自行生成 skills/tool-index.md 与 skills/tool-index.json，记录当前机器真实可用的工具和路径，不能要求用户复制其他机器的结果。

Windows

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1
Get-Item skills/tool-index.md, skills/tool-index.json

Ubuntu / Debian / macOS

bash skills/scripts/refresh-tool-index.sh
ls -l skills/tool-index.md skills/tool-index.json

Kali Linux

bash kali/scripts/refresh-tool-index.sh
ls -l skills/tool-index.md skills/tool-index.json

终端显示索引写入位置；两个索引文件存在。打开 Markdown 后，工具状态应包含“已发现 / 未发现”、实际路径和 bootstrap 提示。

AI 在需要时安全更新

只有用户要求更新时，AI 才先检查工作区并保留现有改动；主线只接受快进更新。发现本地修改或分支分歧时，AI 应先汇报差异，不能让用户盲目执行覆盖命令。

git status --short
git fetch --tags --prune
git pull --ff-only

看到本地修改时不要直接覆盖。先确认差异属于你自己还是生成文件；提交、暂存或备份后再更新。禁止用破坏性重置解决版本冲突。

AI 自动汇报初始化结果

完成配置后，AI 主动汇报平台、实际路径、规则链、工具索引与缺失能力。此时尚未收到授权任务，就停在准备阶段，不访问任何外部目标。

AI INITIALIZATION REPORT Platform: <自动识别的系统与发行版> Skill root: <README_AI.md 所在仓库的真实路径> Tool index: generated / refreshed Rules: README_AI.md → platform doc → RULES.md → routing Missing tools: auto-install when the PRIMARY Skill actually needs them Ops gate: case-init + auth.status=granted + network_profile

AI 的自动报告应明确提到 structured routing、case-init、auth.status=granted、network_profile，并且不会把核心绑定到单一客户端。

平台文档由 AI 自动选择：Kali → kali/README-kali.md；Ubuntu / Debian → docs/platforms/linux.md；macOS → docs/platforms/macos.md。用户无需提前判断该读哪一份。

AI 不应一次安装全部工具。它先看 tool-index.md，只为当前 PRIMARY Skill 安装状态为“未发现”的必要能力；需要许可证或额外授权时再询问用户。

// CLIENT INTEGRATION

接入 AI 客户端

接入不是要求用户安装某个专用插件或手工配置整套路由。通常只需用代码 Agent 打开仓库，并让它完整阅读 README_AI.md；之后平台识别、规则加载和工具索引都由 AI 自动完成。

客户端	打开方式	必须读取	注意事项
Codex	把仓库作为工作区打开	AGENTS.md、README_AI.md、RULES.md	按项目指令自动路由；不要复制规则到全局提示
Claude Code	从仓库根目录启动	README_AI.md、RULES.md	先要求只读检查，再开始 Case
Cursor / Cline / Windsurf	Open Folder 打开仓库	README_AI.md、RULES.md	确保 Agent 能读取整个 skills 目录
OpenCode	以仓库为 project	README_AI.md、RULES.md	可选使用项目级 skills.paths；不得成为核心依赖
其他客户端	使用项目指令 / Skill 入口	README_AI.md、RULES.md	只要能读取文件并运行本机脚本即可

AI 自动接入链路这是验收 AI 是否正确执行 README_AI.md，不是用户的四步操作

AI 定位仓库根目录

Agent 通过 README_AI.md 的真实位置推导 Skill Root，并确认能访问 RULES.md 与 skills/。

AI 加载完整规则链

Agent 按 README_AI 第 0 节自动选择平台文档、刷新索引、读取 RULES 与结构化路由，不应只概括 README 后停下。

下面提示仅用于故障排查：只有客户端没有自动执行 README_AI.md 时，才用它检查规则链；正常首次启动不需要再发送第二套配置提示。

你现在位于 reverse-skill 仓库根目录。
请读取 README_AI.md 与 RULES.md，并列出从“用户任务”到“PRIMARY Skill”的完整文件链。
然后说明 case-init、tool-index、bootstrap 和 case-review 分别在什么时候使用。
只读检查，不执行外部网络动作。

至少出现：routing.json / MASTER-ROUTING.md → case-init → PRIMARY SKILL.md → tool-index / bootstrap → Evidence → Case Review。

AI 自动进行只读路由检查

AI 可在不访问外部目标的前提下调用路由入口，确认输出包含 PRIMARY、confidence 和 route-scope.md。命令由 AI 选择并执行。

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "安卓 APK 加固 反编译"

# Linux / macOS / Kali
bash skills/scripts/master-route.sh --hint "安卓 APK 加固 反编译"

PRIMARY 应指向 skills/apk-reverse/SKILL.md。如果落入 R0，先确认当前分支、routing.json 与 Python 3（Bash 路由器需要）是否正常。

AI 确认平台中立

切换客户端时不修改 routing.json。客户端只改变项目指令的加载方式，路由结果和 Case 结构保持一致。

不要复制整套规则到客户端配置。仓库中的 skills/config/routing.json 是路由唯一事实源，客户端只做加载与调用。

// YOUR FIRST CASE

完成第一个授权 Case

初始化完成后，用户只需提供任务、授权依据、允许范围、禁止动作和期望交付。AI 会自动完成路由、Case 初始化、Scope 结构化与 Guard；本节命令只是把自动过程展开给你看。本教程使用保留示例域名 https://lab.example/，不会连接真实目标。

这一节唯一需要用户提供的是授权任务描述。后面的 route、case-init、scope、case-guard 与 Skill 加载都应由 AI 自动执行。AI 不能替用户臆造授权；授权信息不足时应停下来询问。

你提供授权任务

任务描述至少包含目标类型、授权基础、允许范围、禁止动作和交付物。描述越具体，AI 自动生成的路由与 Scope 越可靠。

目标：公司自有测试环境 https://lab.example/。
授权依据：内部工单 SEC-001；仅允许该域名，禁止 DoS、钓鱼和访问真实用户数据。
任务：审查登录接口的请求签名与前端 JS 调用链。
交付：复现步骤、证据、Finding、修复建议和 Case Review 报告。

AI 自动预览路由

AI 先只读分析文字并写出 route-scope.md，不会访问目标。Windows 与 Bash 使用同一个 routing.json。

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "已授权前端签名 JS逆向 加密参数分析"

# Linux / macOS / Kali
bash skills/scripts/master-route.sh --hint "已授权前端签名 JS逆向 加密参数分析"

PRIMARY -> skills/js-reverse/SKILL.md Label: JS / frontend reverse | confidence: medium Wrote .../work/master-route-.../route-scope.md ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED.

PRIMARY 指向 js-reverse，confidence 为 medium，secondary 通常包含通用逆向；这是多关键词命中的正常结果，应同时查看路由文件和完整矩阵。

AI 自动初始化 Case

AI 从用户提供的任务中提取授权、资产和网络模式，自动选择平台入口并运行初始化；信息不足时先询问，不能自行补造授权字段。

Windows PowerShell

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/case-init.ps1 `
  -Hint "已授权前端签名 JS逆向 加密参数分析" `
  -CaseName "demo-js-signature" `
  -AuthGranted `
  -AuthBasis "written_contract" `
  -EvidenceOfAuth "internal ticket SEC-001" `
  -TargetUrl "https://lab.example/" `
  -NetworkProfile "authorized_target_only"

Linux / macOS / Kali

bash skills/scripts/case-init.sh \
  --hint "已授权前端签名 JS逆向 加密参数分析" \
  --case-name "demo-js-signature" \
  --auth-granted \
  --auth-basis "written_contract" \
  --evidence-of-auth "internal ticket SEC-001" \
  --target-url "https://lab.example/" \
  --network-profile "authorized_target_only"

CASE -> .../work/demo-js-signature PRIMARY skill: skills/js-reverse/SKILL.md (...) auth.status=granted network_profile=authorized_target_only ready_for_act=true NEXT: open PRIMARY SKILL.md and ACT within scope

生成 work/demo-js-signature/，其中至少包含 scope.md、timeline.md、workitems.md、README.md、evidence/、notes/ 和 report/。

AI 逐字段校验 Scope

AI 自动核对下表并向用户确认无法推导的授权边界，尤其是禁止动作、活动类型和数据处理约束。用户负责确认真实授权，AI 负责写入和校验结构。

字段	示例	判定标准
auth.status	`granted`	必须有可追溯授权依据，不能凭 Agent 推断
auth.evidence_of_auth	`internal ticket SEC-001`	写工单、合同、比赛页面或所有权证明
in_scope.assets	`https://lab.example/`	逐项列资产；不能用模糊的“公司所有域名”
in_scope.activities	`recon, reverse, report`	只列获准动作
out_of_scope.activities	`DoS, phishing, data exfil`	明确禁止项
network_profile.mode	`authorized_target_only`	网络只能到 in_scope 列表
signoff.ready_for_act	`true`	前述字段全部完成后才为 true

AI 自动运行 Case Guard

AI 在任何访问目标的命令前自动执行 Guard。退出码 0 才继续；退出码 2 就停在准备阶段并说明缺少什么，不能把 Guard 命令交给用户代跑后直接继续。

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/case-guard.ps1 -CaseRoot "work/demo-js-signature"

# Linux / macOS / Kali
bash skills/scripts/case-guard.sh --case-root "work/demo-js-signature"

显示 CASE-GUARD OK。若提示 auth、network、assets 或 ready_for_act 问题，回到 scope.md 修正；不要用 --force / -Force 绕过正常工作流。

AI 自动进入 PRIMARY Skill

Guard 通过后，AI 读取 skills/js-reverse/SKILL.md 的 ACTION REQUIRED、工具要求、停止条件和产物格式，然后在 Scope 内继续执行。

本地离线样本怎么做？APK、EXE、BIN 等自有文件不需要公网目标

bash skills/scripts/case-init.sh \
  --hint "分析自有 APK 的加密协议" \
  --case-name "demo-apk-offline" \
  --preset offline-sample \
  --sample "./samples/app.apk"

Windows 离线样本：AI 可使用 -AuthGranted -AuthBasis own_system -InScopeAssets "C:\samples\app.apk" -NetworkProfile offline 初始化。入口会保守地保持 ready_for_act=false；AI 向用户确认文件所有权、out_of_scope 与“禁止外连”后，再更新 Scope 并自动运行 Case Guard，用户无需手工编辑。

路由结果与任务意图一致
授权证据、资产、允许和禁止动作均已写入 Scope
Case Guard 返回 OK，未使用 Force 绕过
工具路径来自 tool-index.md，而不是猜测
证据可追溯到 Finding 与最终报告
脱敏经验写入 field-journal，避免重复踩坑

// END-TO-END WORKFLOW

完整工作流

下面展示 AI 在后台自动执行的完整链路，便于审计与排错。正常使用时，用户不需要逐步调用这些脚本；AI 必须保留每一步的输入、输出和中间产物，并在需要用户授权时暂停询问。

AI：任务 → 结构化路由

routing.json 根据任务语义评分并选择 PRIMARY。输出保存在 work/master-route-*/route-scope.md，方便回看当时为什么选择该 Skill。

AI：路由 → 授权 Case

case-init 建立 Scope、Timeline 与 Work Item；case-guard 是 ACT 前的机器校验。

AI：Case → 专项 Skill

AI 读取 Skill 的 ACTION REQUIRED 和必要引用，记录计划、工具需求、停止条件和预期证据，不会跳过门禁直接运行扫描。

AI：检查并自举缺失工具

AI 打开 skills/tool-index.md，只处理当前 Skill 的 Required 工具。状态已就绪时直接使用索引中的绝对路径；状态缺失且允许自动安装时再运行 bootstrap。

Windows 示例：安装 jadx 并刷新索引

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/bootstrap-reverse.ps1 -Capability @('jadx')
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

Linux / macOS 示例

# 先查看支持的 capability 名称
bash skills/scripts/bootstrap-reverse.sh --list

# 只安装当前任务需要的能力
bash skills/scripts/bootstrap-reverse.sh jadx
bash skills/scripts/refresh-tool-index.sh

Kali 示例

bash kali/scripts/bootstrap-reverse.sh jadx apktool frida jshookmcp
bash kali/scripts/refresh-tool-index.sh

刷新后的 tool-index.md 应从“未发现”变为“已发现”，并给出可执行路径。若仍未发现，不要猜路径；查看 bootstrap 的失败输出和 manualInstallHint。

商业或手工安装工具：IDA Pro、JEB、BurpSuite 等可能需要许可证或应用内扩展。bootstrap 只应给出指引，不能绕过授权、下载未知二进制或伪造安装成功。

AI：执行时持续更新时间线

AI 为每个重要动作写入 timeline.md：时间、角色、命令或引用、结果摘要、产物、证据 ID 和下一步；失败尝试也会保留。

## 2026-08-08T10:00:00Z | analyst | inspect-signature - action: inspect frontend bundle - command_or_ref: browser devtools / app.js - result_summary: signature entry located; dynamic nonce source unresolved - artifacts: [notes/app-js-call-chain.md] - evidence_ids: [E-001] - next: trace nonce generator without leaving in_scope host

AI：自动追加 Evidence

AI 记录观察时间、来源、复现命令、原始摘录、严重性和状态，不会只输出无法追溯的结论。

Set-Content -Path "work/demo-js-signature/notes/E-001-excerpt.txt" -Value "signature() calls buildNonce() before request dispatch"
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/append-evidence.ps1 `
  -CaseRoot "work/demo-js-signature" `
  -Id "E-001" `
  -Title "Request signature call chain observed" `
  -ReproCommand "Open app.js and trace signature() call sites" `
  -Severity "info" `
  -Status "observed" `
  -RawExcerptFile "work/demo-js-signature/notes/E-001-excerpt.txt"

生成 evidence/E-001.md，同时更新 evidence/INDEX.md。特殊字符或多行内容优先使用 -RawExcerptFile，避免命令行引号破坏字段。

AI：从 Evidence 提升到 Finding

AI 只将引用一个或多个 Evidence ID 的结论提升为 Finding，并说明影响、置信度、适用范围和验证状态。

状态	含义	可否进入报告
observed	原始现象已记录，尚未完整解释	可作为证据，不直接下漏洞结论
candidate	存在合理假设，仍需复现或排除	只能标注“待验证”
validated	在 Scope 内稳定复现并有证据链	可进入正式 Finding
false_positive	已证明不成立	保留审计记录，不作为风险

AI：自动运行只读 Case Review

AI 在交付前自动执行 strict 与哈希校验；审查器只读取 Case，不改写原始证据，任何 error 都是阻塞项。

# 先看人类可读结果
python3 skills/case-review/scripts/review_case.py work/demo-js-signature --format markdown

# 交付前严格检查与哈希验证
python3 skills/case-review/scripts/review_case.py work/demo-js-signature --verify-hashes --strict

Scope、Timeline、Work Item、Evidence 与 Finding Path 均通过；strict 模式退出码为 0。Windows 若命令名是 python，可将 python3 替换为索引中记录的 Python 3 路径。

AI：生成报告与沉淀经验

AI 将正式报告写入 report/，包含范围、方法、证据引用、Finding、限制和修复建议；仅把脱敏、可复用的经验写入 field-journal。

// TASK EXAMPLES

三条完整示例路径

这些示例展示 AI 收到授权任务后会怎样自动路由、初始化与审查，不是要求用户照抄终端命令。用户只需要提供真实资产、授权依据、允许范围和交付目标。

用户输入任务，AI 执行流程。表格与命令用于解释自动化结果、审计 AI 行为和定位故障；除非 AI 因权限或许可证明确请求协助，否则无需手动操作。

示例 A：自有 APK 离线分析网络模式 offline · 不向外发包

目标	`./samples/app.apk`	确认文件归属和哈希，原始文件只读保存
预期路由	`R1 → apk-reverse`	关键词包含 APK / jadx / smali
允许	解包、静态分析、本地模拟	如需真机 Hook，单独补充设备 Scope
禁止	公网请求、修改原始样本	输出放入 Case evidence / notes

sha256sum ./samples/app.apk
bash skills/scripts/master-route.sh --hint "自有 APK jadx smali 静态分析"
bash skills/scripts/case-init.sh --hint "自有 APK 静态分析" --case-name apk-local-001 --preset offline-sample --sample ./samples/app.apk
bash skills/scripts/case-guard.sh --case-root work/apk-local-001

Guard 通过后才打开 skills/apk-reverse/SKILL.md。所有工具路径从 tool-index.md 获取；若 jadx 缺失，再自举。

示例 B：隔离 Web 靶场网络模式 lab_only · 仅实验室资产

目标	`http://10.10.10.20/`	示例地址；实际使用前确认它属于隔离实验网
预期路由	`pentest-tools` 或更具体 Web Skill	以任务语义为准，不强制指定工具
允许	限定端口和速率的验证	Scope 中写明超时、并发、时间窗
禁止	越出实验网、DoS、真实凭证攻击	发现边界外资产立即停止

bash skills/scripts/case-init.sh \
  --hint "隔离实验室 Web 安全验证" \
  --case-name "lab-web-001" \
  --preset own-system \
  --target-url "http://10.10.10.20/" \
  --network-profile "lab_only"
bash skills/scripts/case-guard.sh --case-root work/lab-web-001

scope.md 的资产只能包含实验室地址，网络模式为 lab_only。任何扫描参数都应先写进 work item，再执行。

示例 C：已有 Case 的只读交接审查不访问目标 · 不修改证据

python3 skills/case-review/scripts/review_case.py work/case-001 --format markdown
python3 skills/case-review/scripts/review_case.py work/case-001 --verify-hashes --strict
python3 skills/case-review/scripts/review_case.py work/case-001 --format json

先处理 scope.* 错误，再处理 Evidence / Finding Path；warning 可以解释但必须在交付记录中说明，error 必须清零。

如何写一个合格任务提示

资产与归属：<本地文件 / 实验室 URL / 书面授权目标>
授权证据：<工单、合同、比赛页面、所有权证明>
允许动作：<静态分析、重放、有限验证等>
禁止动作：<DoS、越权资产、真实用户数据等>
网络模式：offline / lab_only / authorized_target_only
期望交付：证据、Finding、复现、修复建议、报告

提示写法：明确“目标归属 / 授权来源 / 允许范围 / 禁止动作 / 期望输出”。信息不足时，Agent 应停在规划阶段并补齐 Scope。

// VERIFICATION

AI 自动验证

普通用户只使用仓库时不需要手动跑完整测试。AI 修改 routing.json、脚本、Skill 索引或供应链清单后，必须自动按下面顺序验证并修复失败，再向用户汇报结果。

AI 在 Windows 自动执行

# 163 条路由回归
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

# 结构一致性 + 供应链 pin gate
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# 冒烟与 INDEX 漂移检查
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/extract-summaries.ps1 -Check

AI 在 Ubuntu CI 等 PowerShell 环境自动执行

pwsh -NoProfile -File skills/scripts/test-routing.ps1
pwsh -NoProfile -File skills/scripts/verify-routing-coherence.ps1
pwsh -NoProfile -File skills/scripts/smoke.ps1
pwsh -NoProfile -File skills/scripts/extract-summaries.ps1 -Check

检查	验证内容	失败时先看
test-routing	163 个 Hint 是否映射到预期 PRIMARY	失败用例、priority、关键词 must / exclude
verify-coherence	routes / priority、Skill 路径、供应链 pin、授权引用	第一条 BAD；不要绕过 pin gate
smoke	脚本解析与中英快速路由样例	缺失文件、PowerShell 解析错误
extract-summaries	INDEX.md 是否与 Skill 摘要同步	先重新生成，再检查实际差异

路由回归为 163 / 163
结构一致性与供应链版本固定通过
脚本解析、快速路由与 INDEX 检查通过
Windows 与 Ubuntu CI 结果一致

路由变更最小规则：只修改 skills/config/routing.json，不要在 master-route.ps1 或 master-route.sh 重新写一份硬编码路由表。新增规则时同时补回归用例。

// TROUBLESHOOTING

常见问题

需要手动执行教学页里的命令吗？

正常情况下不需要。用户只需让 AI 完整阅读 README_AI.md，再提供授权任务。页面中的命令用于展示 AI 自动执行的流程、方便审计与排错；只有权限、凭据、商业许可证或外部副作用必须由用户确认。

为什么杀毒软件或 EDR 会把某些文件报成木马、后门或黑客工具？

本项目面向授权安全研究，包含逆向、Hook / 调试、扫描、解包、漏洞验证、CTF 方法与工具自举等内容。安全产品通常使用关键词、静态特征和行为启发式检测；这些研究逻辑可能与恶意样本共享局部特征，因此会产生误报。但检测结果不能自动当作误报处理。

正确做法是：只从官方仓库或 Release 获取；核对版本、提交来源和 SHA-256；审查被命中文件及最近差异；在隔离虚拟机或沙箱中以最小权限、受限网络运行。不要把整个项目目录直接加入白名单。若发现来源不明二进制、非预期联网、凭据读取、持久化启动项、哈希不符或超出 Scope 的行为，应立即停止并按真实安全事件处理。

AI 可以协助计算哈希、解释脚本和审查差异，但不能替用户绕过组织策略。反馈误报时请提供安全软件名称、检测标签、相对路径、SHA-256、项目版本和下载来源；不要上传公司代码、真实样本、凭据或其他敏感文件。

稳定版 v1.0.1 和 main 应该选哪个？

只想稳定使用时选择 v1.0.1；需要最新修复并愿意跟随主线变化时选择 main。无论选择哪个版本，都不要在有未确认本地修改的工作区直接覆盖更新。

更新仓库后需要重新生成工具索引吗？

需要，但由 AI 自动刷新。更新可能增加工具定义、候选路径或 bootstrap 提示；AI 应重新运行当前平台的 refresh 脚本并汇报结果。

AI 没有自动路由，直接开始猜命令怎么办？

立即停止目标动作。要求它重新读取 README_AI.md、RULES.md 与 skills/MASTER-ROUTING.md，运行 master-route，并先汇报 PRIMARY、confidence、Scope 计划和所需工具。

tool-index.md 不存在怎么办？

这是正常的首次运行状态。AI 读完 README_AI.md 后必须首先运行当前平台的 refresh 脚本，生成 Markdown 和 JSON 两个索引；用户无需手工生成。

索引说工具不存在，但我刚刚装好了怎么办？

告诉 AI 工具刚刚发生变化。AI 会重新刷新索引并检查候选路径；若仍未发现，它应汇报检测过程，而不是让用户伪造“已安装”。

缺少 jadx、Frida 或其他工具怎么办？

AI 只为当前 PRIMARY Skill 的 Required 工具自动运行 bootstrap，安装完成后再刷新索引。商业工具遵循 manualInstallHint 和许可证要求，需要许可证或管理员权限时 AI 才询问用户。

Bash 路由提示 Python 3 required 怎么办？

AI 应识别 master-route.sh 需要 Python 3，检查能否安全自动安装并验证 python3 --version；不能改成另一份硬编码 Shell 路由。

PowerShell 提示脚本执行被系统策略阻止怎么办？

AI 可使用文档中的进程级 -ExecutionPolicy Bypass 形式，不应永久降低整台机器的策略。企业策略阻止时，AI 应说明阻塞并请求管理员处理。

路由结果是 R0 或 confidence=low 怎么办？

用户补充“目标类型 + 意图 + 关键技术”即可；AI 会自动重跑。仍然模糊时，AI 打开 skills/routing.md 全矩阵选择，并在 Case 时间线中记录理由。

为什么 Case Guard 返回退出码 2？

AI 会读取每个错误项：常见原因是 auth.status 不是 granted、网络模式缺失、非离线 Case 没有资产，或 ready_for_act 不是 true。AI 修正可确定字段，并向用户确认真实授权后重跑；不能用 Force 绕过。

Windows 离线样本为何 ready_for_act 仍是 false？

PowerShell 入口对 offline 默认保守。AI 向用户确认样本所有权、本地文件路径、禁止外连和 out_of_scope 后更新 Scope，再自动运行 Case Guard；用户无需手工编辑。Bash 可由 AI 使用 --preset offline-sample --sample ...。

Case Review 的 strict 模式失败怎么办？

AI 按顺序处理：Scope error → 缺失的 timeline / workitems / evidence → 无证据引用的 Finding → 哈希不一致。它不能为了通过审查修改原始证据；需要更正时新增证据并记录 supersedes 关系。

重复使用同一个 CaseName 安全吗？

不建议。AI 应为每个新任务生成唯一 CaseName；需要续做时在原 Case 中追加 timeline、work item 和 evidence，避免覆盖先前结构。

可以只绑定一个 AI 客户端吗？

可以为某客户端写可选适配，但不能让核心依赖它。迁移客户端时不改 routing.json、Scope 契约和测试；只改变客户端如何加载项目指令或 Skill。

为什么流程命令还保留 COPY 按钮？

它只方便开发者审计、复现和故障排查，不代表普通用户必须手工执行。部分浏览器阻止剪贴板时会显示 SELECT；这不影响 AI 自动化流程。

提交 Issue ↗ 邮件联系 →