niyogilabs/SkillSpectorWeb

SkillSpector 浏览器移植与升级方法论

本技能提供了将新版本的 SkillSpector Python 安全扫描器移植到完全在浏览器中执行的 WebAssembly/JavaScript Web 应用（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）。

---

📋 逐步移植工作流程

阶段 1：规则与 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. 更新类别列表、规则描述、解释和修复指南。

阶段 2：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)）。

阶段 3：多技能发现引擎

1. 在 skillspector-engine.js 中实现 discoverSkills(filesMap)。
2. 解析仓库中所有 .md 文件的 Markdown frontmatter YAML（--- name: ... description: ... ---）。
3. 在 index.html 中渲染一个多技能选择器栏，允许用户按单个发现的技能过滤结果，或检查整个仓库上下文。

阶段 4：独立的仓库文件过滤

1. 保持 docs/js/repo-filter.js 完全独立于核心扫描引擎。
2. 在 index.html 中提供 UI 复选框：
   • 忽略标准仓库文档（README、CHANGELOG、LICENSE）
   • 忽略系统元数据（.git/、.github/、点文件）
3. 将忽略的文件记录到检查日志中，作为 skipped 项目，并附带明确的原因。

阶段 5：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 文件完好无损。