Rinkia/modscan

# MODScan [](https://pypi.org/project/modscan/) [](https://github.com/Rinkia/modscan/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) **扫描代码库，获取为其编写插件和 mod 所需的一切。** ## 为什么 优秀的 mod 和插件已经将普通的游戏和应用变成了杰作。但是 开始为一个项目做 mod 开发是非常痛苦的：你必须自己逆向分析 架构，才能找到哪里甚至允许你插入。MODScan 自动化了这个发现步骤。 ## 它有何不同 现有的工具从源码生成 API 文档。MODScan 专注于每个人都忽略的困难且有价值的部分：**extension point 发现**。 - 检测 hooks、事件/callback 系统、动态导入 / 插件发现、 注册装饰器、可子类化的接口（ABC / Protocols）以及 配置/数据驱动的行为。 - 根据 *可 mod 化*的程度对 seam 进行排名。 - 所有生成的文档均基于静态分析 —— **事实来自于 parser， 文字来自于 LLM，绝不凭空捏造。** - 形成闭环：它生成的示例插件必须能实际加载到 目标中，文档才会被认为是正确的。 ## 工作原理 ``` flowchart TD SRC["Source-available codebase"] SRC --> PARSE["1 · Parse — AST into a shared model
deterministic, no LLM"] PARSE --> GRAPH["2 · Extension graph — dependencies and public seams"] GRAPH --> DETECT["3 · Detect — score and rank seams by moddability"] DETECT -->|"modscan detect · no LLM, no API key"| RANK["Ranked extension points
Markdown or JSON"] DETECT --> PROBE{"Pre-flight:
does the target import?"} PROBE -->|no| FAIL["Stop early — cause plus a pip install remediation
no LLM call spent"] PROBE -->|yes| VALIDATE["5 · Validate — load each seam against the target"] VALIDATE --> FACTS["FactBlocks — facts from static analysis only"] FACTS --> LLM["4 · Doc generator — LLM prose grounded on FactBlocks"] LLM --> DOCS["modding-docs/
index.md · plugin-guide.md · examples/ · extension-points.json"] DOCS --> SCAFFOLD["modscan scaffold — a plugin skeleton from the manifest"] classDef trust stroke-dasharray:5 5; class VALIDATE,LLM trust; ``` 事实来自于 parser，文字来自于 LLM，正确性来自于 validator。 第 1–3 层是确定性和可验证的；LLM（第 4 层）永远只能看到结构化的 FactBlocks，从不会看到原始源代码，因此它是解释分析所发现的内容，而不是凭空捏造。Validator（第 5 层）构建在文档生成器*之前*，因此每个后续阶段都可以根据真正加载的插件进行衡量。 虚线阶段**导入并执行目标代码** —— 那就是加载真实插件以证明 seam 的地方。仅在您信任的代码上运行；`--sandbox` 将其限制在子进程中，而 `--no-validate-examples` 会完全跳过执行（并随之跳过预检探测）。 ## 范围 (MVP) | 在范围内 | 不在范围内（目前） | |---|---| | 源码可查的代码库 | 闭源二进制文件 / 逆向工程 | | Python（首个目标） | 同时支持所有语言 | | 核心库 + 轻量级 CLI | Web 应用 / SaaS UI | ## 语言 Python 是主要的、完全集成的目标。**TypeScript/JavaScript 解析 是实验性的**（通过 tree-sitter）：它为图和探测器提供数据，因此 extension point 和文档可以工作，但示例的*执行*验证目前 仅限 Python。通过 `pip install modscan[typescript]` 安装；前端注册在 `typescript` 和 `javascript` 下。 ## LLM 提供商 文档生成器是与提供商无关的。选择您的模型；SDK 是可选的依赖项， 进行惰性导入，因此您只需安装您使用的部分。API key 来自环境变量， 从不进行硬编码。 | 提供商 | 安装 | 涵盖范围 | |---|---|---| | `anthropic`（默认） | `pip install modscan[anthropic]` | Claude（默认模型：`claude-opus-4-8`） | | `openai` | `pip install modscan[openai]` | OpenAI，以及任何通过 `base_url` 的 OpenAI 兼容 endpoint：Gemini、OpenRouter、DeepSeek、Mistral、本地 Ollama / LM Studio | | `gemini` | `pip install modscan[gemini]` | Google Gemini（原生 SDK；也可通过 `openai` adapter + `base_url` 访问） | ## 输出 两个产出物，一个供人类使用，一个供工具使用： - `modding-docs/*.md` — 架构概览 + 针对每个 seam 的插件指南，包含一个 经过验证的示例插件。 - `modding-docs/extension-points.json` — 每个已验证 extension point 的版本化、机器可读的 manifest。这是将为 `modscan scaffold `、编辑器工具和破坏性变更 diff 提供支持的契约。 每个生成的示例都会针对目标重新加载以确认其有效； 无法验证的示例会被清晰地标记为 `unverified`。 ## 路线图 1. ✅ AST parser + extension graph (Python) 2. ✅ Extension detector + 可 mod 化排名 3. ✅ Validator — 针对检测到的 seam 加载真实的示例插件 4. ✅ 文档生成器（LLM，有依据）— Markdown + JSON manifest 5. ✅ `modscan ./path` CLI wrapper，端到端 6. ✅ `modscan scaffold ` — 从 JSON manifest 生成插件骨架 7. ✅ TypeScript/JavaScript 前端（实验性）、破坏性变更 diff、 沙盒验证、支出控制 8. ✅ `modscan detect`（离线排名）、GitHub Action 和 MCP server 请参阅 **[ROADMAP.md](ROADMAP.md)** 了解接下来的计划，客观评估排名在哪些地方有效、 在哪些地方无效（通过六个真实 package 进行衡量），以及 如何贡献。 ## 30 秒试用（无需 API key） `modscan detect` 仅使用静态分析对代码库的 extension point 进行排名 —— 无需 LLM、无需 API key、不执行代码。这是在决定进行完整的文档生成运行之前，快速查看 MODScan 能发现什么的好方法。*(需要 modscan ≥ 0.1.1。)* ``` pip install modscan modscan detect ./path/to/project # ranked Markdown table modscan detect ./path/to/project --json # machine-readable, for tooling/CI modscan detect ./path/to/project --limit 10 # just the top 10 ``` 将其指向一个已安装的 package，即可立即看到其工作效果： ``` modscan detect "$(python -c 'import os,click;print(os.path.dirname(click.__file__))')" --limit 5 ``` ### 在 CI 中 (GitHub Action) 将排名的 extension point 放入每个 pull request 的 job summary 中 —— 在不受信任的 PR 上是安全的，因为 `detect` 不运行 LLM 且不执行目标代码： ``` - uses: actions/checkout@v4 - uses: Rinkia/modscan@v0.1.1 with: path: . min-score: "0.5" ``` ### 从 AI 客户端 (MCP server) 无需离开对话，即可询问支持 MCP 的客户端（Claude Desktop、Cursor 等）：“这个代码库的 extension point 是什么？”。该 server 仅公开离线探测器 —— 无 LLM、不执行代码 —— 因此它在任何本地检出上都是安全的。 ``` pip install modscan[mcp] modscan-mcp # stdio server; register the `modscan-mcp` command with your client ``` 唯一的工具 `detect_extension_points_tool` 接收一个路径并返回排名的 points。*(需要 modscan ≥ 0.1.1。)* ## 完整文档运行（使用 LLM） ``` pip install modscan[anthropic] # or [openai], [gemini], [typescript] export ANTHROPIC_API_KEY=sk-... # keys come from the environment, never flags modscan ./path/to/project # -> 写入 modding-docs/: index.md, plugin-guide.md, examples/*.py, # 和 extension-points.json ``` 常用 flag： ``` modscan ./proj --provider openai --model gpt-x --base-url http://localhost:11434/v1 modscan ./proj --min-score 0.6 --limit 20 --retries 5 modscan ./proj --language typescript # scan a TS/JS codebase (static docs) modscan ./proj --no-validate-examples # skip importing/executing target code modscan ./proj --sandbox # validate examples in an isolated subprocess modscan ./proj --cache-dir .modscan-cache # cache LLM responses for cheap re-runs modscan ./proj --max-tokens 2048 --max-calls 50 # spend controls: per-call cap + hard run ceiling modscan ./proj --concurrency 8 # parallel LLM calls (the main speed-up) ``` 然后从任何已记录的 extension point 脚手架生成一个可随时编辑的插件（无需 LLM， 读取 JSON manifest）： ``` modscan scaffold "pkg.mod:Symbol" --manifest modding-docs/extension-points.json # -> 写入 pkg_mod_Symbol_plugin.py: 一个包含 stubbed methods 的具体 subclass modscan scaffold --all --out plugins/ # skeletons for every documented point ``` 对比两个 manifest，以便在目标应用更新时捕获破坏性变更（遇到破坏性变更会以非零状态退出 —— 作为 CI gate 非常方便）： ``` modscan diff old/extension-points.json new/extension-points.json ``` 要自动对 pull request 进行 gate，请将 [`examples/ci/breaking-change.yml`](examples/ci/breaking-change.yml) 复制到您的 项目中：它会将提交的 manifest 与 PR 的 base branch 进行 diff，在 PR 上评论结果，并在遇到破坏性变更时使检查失败。无需 API key。 ## License [Apache License 2.0](LICENSE)。宽松许可，带有明确的专利授权 —— extension point 检测是核心价值，因此专利条款值得这 额外的篇幅。另请参阅 [`NOTICE`](NOTICE)。 *规划文档位于 [`.claude/plans/modscan.plan.md`](.claude/plans/modscan.plan.md)。*

标签：Python, SOC Prime, 云安全监控, 代码分析, 凭证管理, 开发工具, 插件化, 数据可视化, 无后门, 系统triage, 逆向工具, 静态分析