你會得到什麼
- 41 條結構化路由規則（R0–R40）
- 客户端无关的专项 Skill 与可选适配层
- 本機工具索引與任務自舉的工具鏈
- Scope、Timeline、Evidence、Finding、Review 證據鏈
// 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 與報告。
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 在目前工作區安全完成的步驟應直接執行並報告；只有系統權限、商業軟體許可、帳戶憑證、授權邊界或外部副作用需要使用者介入。
01
AI 識別平台與基礎環境
AI 會根據實際系統選擇 Windows、Kali、普通 Linux 或 macOS 路徑，並自行執行對應檢查。缺少基礎依賴時，它應先判斷能否安全自動安裝，而不是讓使用者照抄整段指令。
WindowsWindows PowerShell 5.1+ 或 PowerShell 7
git --version
powershell -NoProfile -Command "$PSVersionTable.PSVersion"
python --version
node --versionGit 有版本號；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 --versionPython 必須是 3.x；macOS 自備 Bash 3.2 也能運行通用 bootstrap，無需強制安裝新版 Bash。
02
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 --shortgit status --short 預設無輸出，表示剛克隆的工作區乾淨。若已有本地修改，更新前先確認這些修改是否需要保留。03
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.jsonUbuntu / Debian / macOS
bash skills/scripts/refresh-tool-index.sh
ls -l skills/tool-index.md skills/tool-index.jsonKali Linux
bash kali/scripts/refresh-tool-index.sh
ls -l skills/tool-index.md skills/tool-index.json終端機顯示索引寫入位置；兩個索引檔案存在。開啟 Markdown 後，工具狀態應包含「已發現 / 未發現」、實際路徑和 bootstrap 提示。
04
AI 在需要時安全更新
只有當使用者要求更新時，AI 才先檢查工作區並保留現有改動；主線只接受快轉更新。發現本地修改或分支分歧時，AI 應先報告差異，不能讓使用者盲目執行覆蓋命令。
git status --short
git fetch --tags --prune
git pull --ff-only看到本地修改時不要直接覆蓋。先確認差異屬於你自己還是產生文件；提交、暫存或備份後再更新。禁止用破壞性重置解決版本衝突。
05
AI 自動報告初始化結果
完成配置後，AI 主動報告平台、實際路徑、規則鏈、工具索引與缺失能力。此時尚未收到授權任務，就停在準備階段，不存取任何外部目標。
AI INITIALIZATION REPORT Platform: <自動辨識的系統與發行版> Skill root: <README_AI.md 所在倉庫的真實路徑> Tool index: generated / refreshed Rules: README_AI.md → platform doc → RULES MissPRI → routinging toolen: 投 autop. 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，不是使用者的四步驟操作
01
AI 定位倉庫根目錄
Agent 透過 README_AI.md 的真實位置推導 Skill Root，並確認能訪問 RULES.md 與 skills/。
02
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。03
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 路由器需要）是否正常。04
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 無法替用戶臆造授權；授權資訊不足時應停下來詢問。
01
你提供授權任務
任務描述至少包含目標類型、授權基礎、允許範圍、禁止動作和交付物。描述越具體，AI 自動產生的路由與 Scope 越可靠。
目標：公司自有測試環境 https://lab.example/。
授權依據：內部工單 SEC-001；僅允許該域名，禁止 DoS、釣魚和存取真實使用者資料。
任務：審查登入介面的請求簽章與前端 JS 呼叫鏈。
交付：復現步驟、證據、Finding、修復建議和 Case Review 報告。02
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 通常包含通用逆向；這是多關鍵字命中的正常結果，應同時查看路由檔案和完整矩陣。03
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/。04
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 |
05
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 繞過正常工作流程。06
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 必須保留每一步的輸入、輸出和中間產物，並在需要使用者授權時暫停詢問。
01
AI：任務 → 結構化路由
routing.json 根據任務語義評分並選擇 PRIMARY。輸出保存在 work/master-route-*/route-scope.md，方便回看當時為什麼選擇該 Skill。
02
AI：路由 → 授權 Case
case-init 建立 Scope、Timeline 與 Work Item；case-guard 是 ACT 前的機器校驗。
03
AI：Case → 專案 Skill
AI 读取 Skill 的 ACTION REQUIRED 和必要引用，记录计划、工具需求、停止条件和预期证据，不会跳过门禁直接运行扫描。
04
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.ps1Linux / macOS 範例
# 先查看支援的 capability 名稱
bash skills/scripts/bootstrap-reverse.sh --list
# 只安裝目前任務所需的能力
bash skills/scripts/bootstrap-reverse.sh jadx
bash skills/scripts/refresh-tool-index.shKali 範例
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 只應給予指引，不能繞過授權、下載未知二進位或偽造安裝成功。
05
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
06
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，避免命令列引號破壞欄位。07
AI：從 Evidence 提升到 Finding
AI 只將引用一個或多個 Evidence ID 的結論提升為 Finding，並說明影響、置信度、適用範圍和驗證狀態。
| 狀態 | 意義 | 可否進入報告 |
|---|---|---|
| observed | 原始現像已記錄，尚未完整解釋 | 可作為證據，不直接下漏洞結論 |
| candidate | 有合理假設，仍需復現或排除 | 只能標註“待驗證” |
| validated | 在 Scope 內穩定復現並有證據鏈 | 可進入正式 Finding |
| false_positive | 已證明不成立 | 保留審計記錄，不作為風險 |
08
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 --strictScope、Timeline、Work Item、Evidence 與 Finding Path 皆通過；strict 模式退出碼為 0。 Windows 若指令名稱是
python，可將 python3 替換為索引中記錄的 Python 3 路徑。09
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-001Guard 通過後才打開
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-001scope.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 -CheckAI 在 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 自動化流程。