内容
璃
[](https://github.com/humantorch/blackglass/releases/latest)
[](LICENSE)
[](https://obsidian.md)
[](https://github.com/humantorch/blackglass#requirements)
[](https://www/downloads/)
[](https://buymeacoffee.com/scman)
玻璃将 [Claude Code](https://claude.ai/code) 集成到 Obsidian 中，内置 MCP 服务器，让 Claude 直接访问你的知识库 — 读取、搜索和编写笔记，无需任何配置。不是聊天界面，也不是重新实现：实际的 Claude Code CLI 在真正的终端中运行，与你的笔记并排。
每个斜杠命令、每个 MCP 工具、每个会话，你都可以在独立的终端中找到。如果你已经使用 Claude Code，那么这里没有什么新东西需要学习。
**注意：** 该插件以前称为 Blackglass。名称已缩短为 Glass；插件 ID 仍为glass`，因此现有无缝更新。
ATS-NEW-START 1.8.2 版本新增功能
-OS 选项键输入 选项键组合（、€、¢可以正确到达终端，而不是被浏览器的默认键盘处理所吞噬。
- **终端自动聚焦** — 终端现在在打开会话时自动，以便你可以立即开始<!-- WHATS-NEW## 功能
- **真正的 Claude Code 终端**聊天界面或包装器；实际的 Claude Code CLI 在侧边栏的完整 xterm.js 终端中运行。所有斜杠命令、所有 MCP 工具、完整的会话连续性。
- **内置知识库 MCP 服务器**：在插件加载 Claude 提供结构化的写入访问权限；
- **认证 MCP 服务器**：在每次启动生成的 Bearer token写入 `.mcp.json`；任何其他都被拒绝访问
只读知识库模式设置，隐藏 Claude 的写入工具，限制其仅读取和搜索
- **快速询问模态**： Code 的 `--print`进行一次性查询；；以 Markdown 渲染响应
- **文件资源菜单**：右键单击任意 `.md` 文件，选择“询问 Claude 关于此文件”以查询 Claude，无需打开 **知识库询问**：使用活动笔记或选定文本预填充模态
- **每查询模型选择器**：在快速询问模态中直接选择模型；覆盖默认设置而不更改你的设置
- **会话恢复**：在每次打开时继续上一次会话（`--continue`）
- **主题自适应终端**：终端颜色源自活动 Obsidian 主题；在切换主题时实时更新 **跨平台**：macOS、Linux 和 Windows（Windows 需要 `pip install pywinpty`）
## 要求
- Obsidian 桌面应用程序（1.7.7+）
- [Claude Code CLI](https://claude.ai/code) 已安装并在你的 PATH 上（`claude --version` 应在你的终端中工作）
- Python 3（由终端桥使用；随 macOS 捆绑，在 Linux 上通过包管理器提供；在 Windows 上从 [python.org](https://www.python.org 安装）
**平台支持 macOS 和箱即用。Windows 3 和一个：
```bash
pip install pywinpty
```
`pywinpty` 是一个 Python 包，提供 Windows PTY 支持，包括终端调整大小。快速询问模态在所有平台上无需此包即可工作。
**Agent SDK 积分：** 快速询问模态以非交互模式（`-p`）运行 Claude Code。截至 2026 年 6 月 15 日，Anthropic 对此单独计费，与交互式使用分开 — 专业计划包含 20月的 Agent SDK 积分详情](https://aude.com/en/articles/150-use-the-claude-with-your-cl)）。交互式终端所有平台上可用）使用你的常规 Claude 订阅，而不是此池。
## 安装
在设置 → 社区 浏览中搜索 **然后安装并。
**手动安装：** 从 [最新版本](https://github.com/humantorch/blackglass/releases/latest) 下载 `main.js`、`styles.css` 和 `manifest.json`，并将它们复制到 `<your-vault>/.obsidian/plugins/blackglass/`。
## 命令
所有命令均可通过命令调色板（Cmd+P）访问：
| 命令 | 描述 |
|---|---|
| 打开 Claude Code 终端 | 打开侧边栏终端面板 |
| 询问 Claude（快速） | 打开快速询问模态（打印模式，无需终端） |
| 询问 Claude 关于此笔记 | 使用当前笔记的内容预填充模态 |
| 询问 Claude 关于选择 | 使用选定的文本预填充模态 |
| 开始新的 Claude Code 会话 | 终止当前会话并启动一个干净的新会话 |
| 将笔记引用插入终端 | 打开笔记选取器并将 `@<path>` 插入终端； 在设置 → 快捷键中分配热键 |
工具栏图标（机器人）也直接打开终端面板。终端工具栏有 **新会话** 按钮，启动一个全新的会话，**清除** 按钮清除终端输出而不结束会话，**@** 按钮打开模糊笔记选取器并将选定的路径写入终端（Claude Code 直接读取文件 — 不会转储内容），** 按钮（⚙）打开 Glass 设置，会话和 MCP 服务器的状态点（绿色 = 活动，灰色 = 非活动）。
右文件资源管理器中的任意` 文件，显示 Claude 关于此文件选项，打开快速询问模态，预填充该。
## 设置
设置 → Glass：
| 设置 | 默认值 | 描述 |
---|
| Claude 二 | `claude` | `claude`路径。如果不在 PATH 中，请使用完整路径。 |
目录 | *（知识库根目录）* 启动的目录。默认为知识库根目录。 |
快速询问模型 | 快速询问模态使用的模型。可以覆盖每查询态本身。 |
字体大小 | | 像素更新正在运行的 |
| 终端字体monospace`终端的字体系列。从系统字体中填充字体枚举不可用落到精选列表。正在运行的终端| 终端字体 `正常` |字体的权重或样式。选项源自（例如 Light、SemiBold、Bold）。立即更新正在运行的终端。 |
| 终端滚动缓冲区 | `5000` | 保留在滚动历史记录中的行数。 在下次终端打开时生效。有效范围：100–100,000。 |
| 启动时打开面板 | 关闭 | Obsidian 启动时自动打开终端。 |
| 恢复上一次会话 | 开启传递 `--continue` 以一次会话。 |
启用知识库 MCP 服务器 | 开启 | 启动 服务器。禁用以在无知识库工具访问。 |
| MCP 服务器端口 | `27123` 服务器绑定的端口被占用，则自动。有效范围：1024-65535。 |
| 只读知识库访问 | 关闭 | 从 Claude 中隐藏 `create_note` 和 `update_note`。Claude 仍然可以读取和搜索笔记。 |
| 跳过权限提示 | 关闭 | 将 `--dangerously-skip-permissions` 传递给 Claude Code。Claude 将在无需确认的情况下执行工具调用。仅为受信任的任务启用。 |
## 知识库 MCP 服务器
Glass 内 MCP 服务器，为嵌入式 Claude Code 会话提供对知识库的结构化访问。启用后（默认开启），插件：
1.:27123`（或下一个可用端口）上启动本地 HTTP 服务器
2. 生成一个随机 Bearer token，并将服务器地址写入 `.mcp.json`，以便 Claude Code 自动身份验证
3. 在插件卸载时删除条目
服务器要求每个请求都有有效的 `Authorization: Bearer <token>` 头。在每次插件加载时重新生成，因此任何其他本地进程在重启后都会令牌的访问权限。
Claude Code 获得了以下知识库工具| 工具 | 描述 |
|---|---|
_note` | 按知识库相对路径读取完整内容 |
| `list_notes` | 列出路径（默认为知识库）处的笔记和 |
| `search_v | 查找路径或文件名与查询字符串匹配的笔记 |
| `search_note_content` | 对笔记内容进行全文搜索，返回带有上下文的匹配行 |
get_active_note` | 获取当前打开笔记的路径和内容 |
| `create_note` | 在知识库相对路径处创建新| `update_note 替换现有笔记`search_note_content` 接受一个可选的 `directory` 参数，以将搜索限制在子树中，还接受一个可选的 `max_results` 参数（默认为 10，最大 50）。每个 3 个匹配行，带有周围上下文，以便 Claude哪些笔记需要完整读取。
要禁用 MCP 服务器，请在设置 - Glass关闭 - “库 MCP 服务器”。要使用不同的端口，请更改“MCP 服务器端口”设置（有效范围：1024-65535）。要 编写知识库“只读知识；这会完全隐藏 Claude 的 `create `update_note`。
**注意：** 知识库根目录中的 `.mcp.json` 由 Glass已经拥有带有其他服务器的 `.mcp，Glass 将合并mcpServers.obsidian` 条目，而不是覆盖整个文件。
## 远程Claude Code 内置的 `/remote-control` 命令允许您从任何已登录 Claude 的设备访问正在运行的 Glass 会话 — 手机、平板电脑或其他计算机 — 无需额外安装。
在您的桌面上打开 Glass：
1. 在终端中输入 `/remote-control`
2. Claude Code 显示远程会话的 URL
3. 在任何设备（任何浏览器，无需安装）上打开该 URL
知识库 MCP 服务器在您的桌面上继续运行，因此 Claude 仍然可以从远程会话中读取、搜索和编写笔记。您可以询问有关知识库的问题、启动长时间任务并获取结果 — 所有操作均来自您的手机。
**限制：** 此功能需要 Obsidian 在您的桌面机器上保持打开状态。关闭应用程序或将其置于睡眠状态将关闭 MCP 服务器，远程会话将失去知识库访问权限。
## 网络使用情况
Glass 本身仅通过 localhost 进行通信：知识库 MCP 服务器绑定到 `127.0.0.1`，暴露给网络。
Glass 运行的 Claude Code CLI 是一个单独的进程，它通过 HTTPS 将会话历史记录发送到 [Anthropic](https://www.anthropic.com)。这是与您在终端中使用 Claude Code 时发生的相同网络活动。Glass 不会直接向 Anthropic 传输任何数据；所有 API 通信都由 Claude Code CLI 使用您自己的帐户和 API 凭证处理。
## 安全
知识库工作目录的上下文中为 Claude Code 提供完全的 shell 访问权限。这意味着包含对抗性指令的笔记（通过 `read_note`、`get_active_note` 或快速询问命令读取到 Claude 的上下文中）可能会尝试影响 Claude 的行为，包括运行 shell 命令。
**Glass 的做法：** 所有传递给 Claude 的笔记内容都用样式的分隔符附有明确的指示将其视为数据指令。这可以防御和适度的复杂。它不是一个完整的解决方案；精心设计的笔记可能会尝试逃避包装，但它有意义地提高了门槛。
**不会保护您：** **只读知识库访问** 设置删除了 `create_note` 和 `update_note` MCP 工具，但这不是一个有意义的注入防御。成功的注入仍然具有完全的 shell 访问权限；它可以通过 `curl` 泄露系统直接写入文件任何其他 shell只读模式在浏览或查询会话期间防止意外知识库写入时很有用；不应将其误边界。
**推荐的做法：
- 运行“询问 Claude文件”以获取来自不受信任来源的笔记：网页剪辑、共享知识库、下载的模板
- 终端面板是交互式的；您会在执行任何操作之前看到 Claude，这是对意外行为的重要检查
## 从源代码构建
### 要求
- Node.js 18+
- Python 3
- PATH 上的 Claude Code CLI
### 步骤
```bash
git clone git@github.com:humantorch/blackglass.git
cd blackglass
npm install
npm run build # 生成 main.js
```
然后将 `main.js`、`styles.css` 和 `manifest.json` 复制到您的知识库插件目录中。
### 发布
```bash
npm runpatch # 0.2.0 → 0.2.1
npm run release:minor # 0.2.0 → 0.3.0
npm run release:major # 0.2.01.0
```
递manifest.json` 和 ` 中的版本号，构建，提交，标记并使用 `manifest.json` 附件创建 GitHub 版本。 GitHub Actions 工作流随后会构建发布资产，证明构建出处并上传 `main.js` 和 `styles.css`。 需要通过 `gh` CLI 进行身份验证。
### 开发循环
```bash
npm run dev # 监视模式 — 每次保存时重新编译
```
### 测试
```bash
npm run lint # 运行 Obsidian 插件检查（零错误 = ）
npm test # 运行测试一次
npm run test:watch # 文件更改时重新运行
```
集成测试涵盖知识库 MCP 服务器：身份验证、七种工具、只读模式、端口回退和 HTTP 边缘情况。测试启动了一个针对模拟知识库的真实 HTTP 服务器 — 无需 Obsidian 实例。
PTY 终端、xterm.js 渲染和 Obsidian 插件生命周期不涵盖在自动化测试中；请手动在测试知识库中验证这些。
在专用测试知识库中安装 [hot-reload](https://github.com/pjeby/hot-reload) 社区插件，将此目录符号链接到其插件文件夹，插件将在您编辑时自动重新加载。
```bash
mkdir -p /path/to/test-vault/.obsidian/plugins/
ln -s "$(pwd)" /path/to/test-vault/.obsidian/plugins/blackglass
```
符号链接文件夹名称应与插件 ID (`blackglass`) 匹配，以便 Obsidian 可以正确定位它。
**绝不使用你的主知识库进行开发测试。**
### 故障排除
**“pywinpty 未安装”**：Windows 终端支持需要 `pywinpty`。在终端中运行 `pip install pywinpty`，然后重新加载插件。如果您有多个 Python 安装，请确保您正在将安装到 Glass 在 PATH 中找到的相同 Python 中（`where python` 将显示它）。
**“未找到 Python 3”**：从 [python.org](https://www.python.org/downloads/) 或通过 Homebrew (`brew install python3`) 安装 Python 3 3 随 macOS 12.3+ 捆绑；如果您使用的是较旧的版本，则可能缺少此功能。
**“会话以退出代码 1 结束” 立即：** Claude 要么不在 PATH 上，要么未找到。Obsidian 的 Electron 进程不会继承您的完整 shell PATH。插件尝试通过常见安装位置补充 PATH（`~/.local/bin`、`/opt/homebrew/bin`、`/usr/local/bin` 等），但如果 Claude 安装在其他位置，最可靠的解决方法是在设置 → Glass →“Claude 二进制路径”中显式（在终端中使用 `which claude`）。
**“未找到上一个会话，启动新会话”**：在首次启动或新工作目录中预期。插件在没有 `--continue` 的情况下自动重试，此消息可以忽略。
**MCP 服务器在插件内不可用**：Electron 的进程环境不会继承您的完整 shell 配置文件，因此诸如 `GITHUB_PERSONAL_ACCESS_TOKEN` 之类的环境变量默认情况下不存在。插件通过捕获启动登录 shell 环境（通过 `zsh -l -c "env"`）来解决这个问题，这依赖 shell 配置文件的自动工作。如果仍然缺少 MCP 工具，请检查相关环境变量是否在您的 shell 配置文件中导出（`.zshrc`.zprofile` 等），而不是仅在终端会话中设置。
## 架构
```
src/
.ts #入口、命令、/保存
├── types.ts # 共享接口和常量
├── SettingsTab.ts # Obsidian 设置 UI
├── ContextBuilder.ts # 知识库上下文提取（文件内容、选择、路径 ProcessManager.ts # Claude 子进程管理（PTY + 打印模式）
├── ClaudeTerminalView.ts # xterm.js 交互式终端视图
├── ClaudeQuickModal.ts # 使用 --print 模式的一次性查询模态
└── VaultMcpServer.ts # 内置 MCP 服务器，向 Claude 公开知识库工具
```
**双模式设计：** 终端视图运行一个持久的 PTY 会话（式 Claude Code模态使用 `claude --print --output-format json` 进行一次性查询，无需打开终端会话。
## 许可证
MIT
