内容
# nnlens
**抛出论文、GitHub 仓库或技术名称，即可获得神经网络的分层解释，涵盖五种关联视图。**
<details>
<summary>… 同时支持多语言 — 相同的查看器渲染日语 Transformer-block 解释</summary>
</details>
nnlens 是一个 **MCP 服务器 + 本地渲染器**。您将其连接到已有的 MCP 主机（Claude Desktop、Claude Code、Cursor 等）。主机的模型由 **您自己的订阅** 驱动，进行解释；nnlens 提供方法，获取实际来源，运行代码，并将结果渲染到本地网页。
> nnlens **从不直接调用 LLM，也从不处理 API 密钥**。推理在您的 MCP 主机上进行，使用您现有的计划。这就是重点：无需按次计费的 API，无需共享凭证，也无需托管服务借用您的订阅。
## 五种视图
每个组件（层、块或技术）都以五种方式解释，视图通过共享的**概念账本**关联，以便相同的想法在所有视图中保持相同的日常词汇、符号和正式名称：
1. **结构** — 数据流的 Mermaid 图表，以及简要说明。
2. **用日常语言解释** — 仅使用日常语言。无符号，无专业术语。
3. **数学表达** — 使用实际符号，并延续视图 2 中的日常词汇，将每个词汇与其符号关联（悬停高亮的词汇以查看映射）。
4. **简单实现** — 从头开始的实现，**直接执行**，输出真实。
5. **优化实现** — 快速版本，从官方仓库（带源码链接）或从头编写，当官方仓库不存在时，通过数值验证与简单视图一致。
超出单个页面：
- **任意语言** — 解释用您要求的语言编写，页面布局适配：日语/英语标签内置，主机提供其他语言的 `ui_labels` 翻译。语言支持无硬编码。
- **库** — 生成的每个解释都保存在本地（`~/.nnlens/store`）并在侧栏列出；删除时鼠标悬停 ✕。
- **交叉链接** — 解释相互引用（`related` 芯片和 `[[slug]]` 维基链接在正文中）。链接到您尚未生成的解释时显示为灰色 — 内置的“下一步解释”列表。
- **合约检查** — `render` 在视图不一致时返回警告（账本术语未标记，符号泄漏到日常语言视图，未引用的优化视图，未验证的简单运行），以便主机修复它们。
- **自我修复页面** — 页面带有模板哈希，当 nnlens 更新其渲染器时自动重建。
## 安装
```bash
pip install nnlens # 或：pipx install nnlens
```
或从源码：
```bash
git clone https://github.com/tsuzakiii/nnlens
cd nnlens
pip install -e .
```
## 连接到您的 MCP 主机
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"nnlens": { "command": "nnlens" }
}
}
```
**Claude Code**：
```bash
claude mcp add nnlens -- nnlens
```
（如果 `nnlens` 脚本不在您的 PATH 中，请使用 `"command": "python", "args": ["-m", "nnlens"]` 代替。）
## 使用
在您的主机上，调用 `explain` 提示（例如，输入 `/nnlens` / `/explain`）或直接询问：
> 使用 nnlens 解释 Scaled Dot-Product Attention
用任何语言询问 — 「nnlens で RoPE を説明して」 将为您提供相同的五种视图，日语文本和日语界面。
主机将获取论文/仓库，编写五种视图，运行简单代码验证，并为您提供一个 URL，如 `http://127.0.0.1:8787/e/…` — 打开它，查看带有图表、数学公式和悬停链接术语的渲染页面。
## 在没有主机的情况下尝试渲染器
```bash
python scripts/build_example.py # （重新）构建捆绑的示例，运行其代码
python scripts/demo_render.py --open
```
## 工作原理
```
MCP 主机（您的订阅） ── 驱动 ──► nnlens 工具
│ ├─ fetch_paper / find_official_repo / fetch_repo_code
│ 编写 5 种视图 ├─ run_python （验证视图 4 运行）
└───────────────────────────────────► render （→ 本地网页 URL）
```
- **工具** = 确定性工作（检索、代码执行、渲染）。
- **`explain` 提示** = 主机遵循的方法论，用于组装视图。
## 限制（使用前请阅读）
- **正确性不保证**。文本和数学公式由主机模型编写。图表由模型生成，是最薄弱的环节 — 将视图 1 视为草图。视图 4 已执行，因此其输出是真实的；其余部分是尽力而为。
- **`run_python` 在尽力而为的沙箱中运行，而不是强化沙箱**。代码片段获取隔离的解释器（`python -I`），清理的环境（您的 API 密钥和令牌不在其中），无网络（`socket` 和 `_socket` 禁用），无进程创建（`subprocess`/`os.system`/`exec*`/`spawn*` 拒绝，因此子解释器无法绕过代理），内存/CPU 时间/文件大小上限，超时时进程树终止。这些是在进程中防御：确定要达到 C 级 API 的有效载荷（例如，通过 `ctypes`）仍然可以取消它们 — 请保持主机的权限提示在此工具上，并在需要实际边界时将整个服务器运行在容器中。
- **视图 5 摘录** 在视图时从公共仓库获取并显示，其来源署名；无内容被重新分发。请尊重每个源仓库的许可证。
- 渲染器从 CDN 加载 Markdown/Mermaid/KaTeX，因此查看需要互联网。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
