niyogilabs/SkillSpectorWeb

SkillSpector 瀏覽器移植與升級方法

此技能提供逐步指南，用於將新版本的 SkillSpector Python 安全掃描器移植為 100% 在瀏覽器內執行的 WebAssembly / JavaScript 網頁應用程式（SkillSpectorWeb）。

---

🎯 架構原則

1. 100% 用戶端瀏覽器執行：

   • 掃描器必須完全在使用者的瀏覽器中執行，無需後端伺服器。
   • 所有 GitHub 儲存庫內容皆透過 GitHub REST API（api.github.com 和 raw.githubusercontent.com）擷取。

2. 嚴格的模組隔離：

   • 核心掃描引擎（docs/js/skillspector-engine.js）：純粹的翻譯靜態分析規則，對應 Python 的 nodes/analyzers/。
   • 隔離的儲存庫過濾器（docs/js/repo-filter.js）：將自訂的非技能檔案過濾（README.md、CHANGELOG.md、.git/ 等）與翻譯後的掃描器程式碼分離。
   • GitHub 擷取器（docs/js/github-fetcher.js）：處理 URL 解析、樹狀結構展開與批次下載。

3. 多技能儲存庫支援：

   • 必須鏡像 src/skillspector/multi_skill.py，以探索儲存庫中所有巢狀技能（resources/skills/*.md、skills/*.md、agents/*.md）。

4. 授權與版本一致性：

   • 保留與上游 Python SkillSpector 版本完全相符的版本號碼（vX.Y.Z）。
   • 保留未經編輯的上游 LICENSE（Apache 2.0）。

---

📋 逐步移植工作流程

第一階段：規則與 AST 分析提取

1. 檢查上游 src/skillspector/nodes/analyzers/ 中的新分析器規則：
   • pattern_defaults.py（規則 ID：P1-P8、E1-E5、PE1-PE3、SC1-SC7、EA1-EA4、OH1-OH3、MP1-MP3、TM1-TM4、RA1-RA2、TR1-TR3、MCP1）。
2. 將新的 Python 正規表達式與 AST 檢查轉譯為 docs/js/skillspector-engine.js 內的 JavaScript RegExp 模式。
3. 更新類別清單、規則描述、說明與修復指南。

第二階段：GitHub 擷取器與樹狀結構展開

1. 確保 docs/js/github-fetcher.js 能透過 https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1 擷取遞迴樹狀結構。
2. 請勿將擷取限制在過小的任意檔案數量（使用高門檻，最多 250 個檔案，以支援大型多技能儲存庫）。
3. 使用平行批次擷取（例如每批 10 個檔案），並搭配即時 UI 進度回呼（onProgress(current, total, filename)）。

第三階段：多技能發現引擎

1. 在 skillspector-engine.js 中實作 discoverSkills(filesMap)。
2. 解析儲存庫中所有 .md 檔案的 Markdown 前置元資料 YAML（--- name: ... description: ... ---）。
3. 在 index.html 中渲染多技能選擇列，讓使用者能按個別發現的技能篩選結果，或檢視整個儲存庫的上下文。

第四階段：隔離的儲存庫檔案過濾

1. 將 docs/js/repo-filter.js 與核心掃描引擎完全分離。
2. 在 index.html 中提供 UI 核取方塊：
   • 省略標準儲存庫文件（README、CHANGELOG、LICENSE）
   • 省略系統中繼資料（.git/、.github/、點檔案）
3. 將省略的檔案記錄到檢查總帳中，標記為 skipped 並附上明確原因。

第五階段：GitHub Pages 封裝（docs/）

1. 確保所有靜態網站資源都位於 SkillSpectorWeb/docs/ 目錄下：
   • docs/index.html
   • docs/css/styles.css
   • docs/js/*.js
   • docs/CNAME（skillspector.niyogilabs.com）
   • docs/sitemap.xml
   • docs/robots.txt
   • docs/.nojekyll
   • docs/LICENSE
2. 確保 server.py 預設提供 docs/ 目錄。

---

🧪 驗證檢查清單

• python3 server.py 8090 啟動並從 docs/ 乾淨地提供服務。
• 掃描多技能儲存庫（例如 Bhanunamikaze/Agentic-SEO-Skill）能發現所有巢狀技能。
• 淺色主題設為預設；深色主題切換功能正常，並能儲存在 localStorage 中。
• SEO 端點（/sitemap.xml、/robots.txt、/CNAME）回傳 200 OK。
• SARIF 2.1.0、JSON 和 Markdown 匯出功能正常運作。
• 未經編輯的根目錄 LICENSE 檔案保持完整。