Oni

一个净室开发、源码级的逆向工程引擎。
将其指向一个 repo。它会将 codebase 拆解为值得关注的核心要素 ——
它是什么、它是如何运作的、哪些 文件是核心资产，
以及在不复制一行代码的情况下，原生重建其优秀理念的方案。

纯标准库 · 零依赖 · 离线且无需密钥 · 可选 LLM

## 为什么需要 每个团队最终都会去逆向工程别人的代码 —— 为了学习一种模式、为了评估 竞争对手，为了决定 *这里是否有值得借鉴的东西？* 依靠手工完成是一个缓慢的爬行过程：clone、 grep、猜测哪些文件重要、先读了不相关的文件，并最终重构出整体轮廓。 **Oni 将这一繁琐过程简化为一条命令。** 它会为你找出重要的代码（基于中心度分析，而非主观 猜测），解释其运行机制，并且 —— 这是大多数工具会忽略的部分 —— 告诉你目标的 **许可证** 是如何规范你对所学知识的使用权限的。 ``` oni Aider-AI/aider oni ./path/to/local/repo --query "how does the planner work" oni https://github.com/psf/requests --no-llm --out ./teardowns ``` ## 你能得到什么 生成一个 `TEARDOWN.md`（以及匹配的 `teardown.json`），包含： | 部分 | 告诉你的内容 | |---|---| | **采用策略** | 许可证，以及你*确切*可以如何复用它 —— 刻意将其放在首位展示。 | | **概览** | 语言、规模、许可证，以及信号（测试 / CI / Docker / 文档）。 | | **它是什么 / 如何工作** | 紧凑、具体的叙述 —— 真实的模块和符号，没有废话。 | | **架构** | 按中心度排名的顶层区域 + 检测到的入口点。 | | **核心资产** | 中心度最高的符号，每个都附有简短的源码摘录。请优先研究这些。 | | **模式 · 优势 · 劣势** | 可复用的理念、它做得好的地方、以及它的薄弱环节。 | | **采用方案** | 针对每个模式：*原生构建什么*、工作量（S/M/L）以及原因 —— 一份净室开发规范，绝非简单复制。 | ## 核心资产引擎 寻找“重要的文件”是最困难的部分，Oni 采用了与 [Aider](https://github.com/Aider-AI/aider) 相同的方法来实现 —— 纯粹使用标准库重新实现： 1. **将 repo 建模为图。** 节点即文件。对于一个文件*引用*而在另一个文件中 *定义*的每个标识符，添加一条边（引用方 → 定义方），其权重取决于引用次数， 并且对于有意义的 `snake_case` / `CamelCase` 命名会增加权重。 2. **在该图上运行 PageRank**（幂迭代法，阻尼系数 0.85）。定义了 被广泛使用符号的文件会浮到顶部。通过 `--query` 可以偏置转移向量，使得*“指向身份验证”*的查询能够 展现出验证机制，而不仅仅是全局核心文件。 3. **将每个文件的级别分布到其包含的符号上** → 得到*每个符号*的排名。这些就是你的核心 资产：codebase 其余部分所依赖的核心代码。 没有 embedding，没有外部服务，没有索引服务器 —— 仅使用 `ast`、正则表达式和约 30 行 PageRank 代码。 ## 天生为净室开发设计 Oni 的存在是为了帮助你从代码中**学习**，而不是洗白代码。因此它从不将目标代码复制到你的 目录树中，保持摘录简短（展示意图，而非具体实现），并在每份报告的开头注明许可证： - **宽松型** (MIT / Apache / BSD / ISC) → 自由复用模式；保留署名说明即可。 - **Copyleft 型** (GPL / AGPL / LGPL / MPL) → **仅限净室开发**：研究行为，编写规范， 根据规范重新实现。AGPL 会被标记为具有网络传染性。对 copyleft 源码的近似重写本身可能构成衍生作品 —— Oni 会醒目地提醒你这一点。 - **未知 / 无** → 在人类确认之前，一律视为保留所有权利。 采用方案只会提出*原生重写*的建议。 ## 安装说明 ``` ./install.sh # pipx / pip --user / zero-install shim, in that order # 或者 pip install -e . # then `oni` is on your PATH # 或者只是 python3 -m oni # no install at all ``` 需要 Python 3.8+。无需其他依赖。 ## 使用模型（可选） 每个阶段都有启发式的备选方案，因此即使**完全不使用模型**，Oni 也非常实用。提供一个 模型，叙述和采用方案会变得更加精准。通过环境变量进行配置 —— 它可以无缝接入任何 兼容 OpenAI 的 endpoint（OpenAI、OpenRouter、Ollama、vLLM、LM Studio 等）： ``` export ONI_API_KEY=sk-... # omit for a local/Ollama endpoint export ONI_MODEL=gpt-4o-mini # or any model your endpoint serves export ONI_ENDPOINT=https://api.openai.com/v1 # or http://localhost:11434/v1, etc. oni some/repo ``` 随时可以通过 `--no-llm` 强制使用离线模式。 ## 作为库使用 ``` import oni result = oni.teardown("Aider-AI/aider", query="repo map", n_jewels=15) print(result["jewels"][0]["name"]) # highest-centrality symbol print(result["posture"]["banner"]) # how you may adopt it for a in result["adoption"]["adopt"]: print(a["pattern"], "→", a["build"], f"({a['effort']})") ``` ## 命令行参考 ``` oni [options] local path | GitHub URL | owner/repo[@ref] -o, --out DIR write TEARDOWN.md + teardown.json to DIR -q, --query TEXT bias the crown-jewel ranking toward a concept -n, --jewels N how many crown jewels to surface (default 12) -c, --context TEXT your own context, so the adoption plan maps ideas onto it --no-llm skip the model; structural teardown only --json print JSON instead of Markdown --cache-dir DIR clone remotes here (kept) instead of a tempdir ``` ## 如何保持客观真实 - **全方面容错。** 没有 git → 下载 tarball。没有模型 → 启发式拆解。没有 网络 → 在本地检出上运行。某个环节失效会降级处理；它不会导致整个运行中止。 - **确定性。** 输入相同的 repo，得到相同的排名结果 —— 采用排序遍历，没有随机性。 - **只读模式。** Oni 从不修改目标，除非你传入 `--out`，否则它绝不会向你的项目中写入任何内容。 ## 测试 ``` pip install pytest && pytest -q # runs fully offline against a bundled fixture repo ``` ## 致谢 请参阅 [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md)。核心资产排名采用了 Aider 的 repo-map 思想； 语言检测遵循 github-linguist；净室开发策略遵循既定的 逆向工程原则。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。请负责任地使用 Oni 从代码中学习。

标签：Python, SOC Prime, 云安全监控, 云资产清单, 人工智能, 代码分析, 凭证管理, 开发工具, 无后门, 用户模式Hook绕过, 自动化payload嵌入, 逆向工具, 逆向工程, 静态分析