使用说明

见证

将混乱转化为秩序的AI伴侣

Witness是一个黑曜石插件，可以将你的保险库变成一个智能的、人工智能可访问的知识库。它直接在Obsidian内部运行一个MCP（模型上下文协议）服务器，允许Claude Desktop和其他AI助手代表您读取、写入和组织笔记。

哲学：混沌→ Order

见证是围绕一个简单的组织理念建立的：

混沌：来自世界各地的未经处理的信息（文章、视频、快速笔记、成绩单）
订单：你提炼和组织的结构化知识（主题、项目、综合）

该插件可帮助您将信息从混乱转移到有序，并在人工智能的帮助下处理、分类和合成您的笔记。

特性

电流（第1+2+3阶段）✅

MCP服务器：在黑曜石内部运行，无外部依赖
文件操作：通过AI读取、写入、编辑和列出vault中的文件
全文检索：使用可选过滤器搜索所有markdown文件
语义搜索：使用本地Ollama嵌入+Orama矢量存储按含义查找文档
搜索面板：通过模糊自动补全进行路径和标签过滤的侧边栏搜索
背景索引：自动增量索引，带空闲门控执行（等待2分钟不活动）、取消暂停保存、活动文件延迟和状态栏倒计时器
命令执行：通过AI执行任何黑曜石命令
Claude桌面集成：直接从Claude Desktop应用程序连接
远程访问：Cloudflare快速隧道或命名隧道（永久URL），可从任何地方访问
命名隧道支护：将您自己的域名与Cloudflare命名隧道一起使用，以获得永久、稳定的URL
主要机器：指定在跨多个设备同步时运行隧道的计算机
令牌身份验证：使用简单令牌保护您的远程端点
混沌分类：通过队列管理和安全的前台更新，人工智能辅助处理未读的混乱项目
混沌队列面板：用于浏览和分类混乱项目的可视化侧边栏——基于卡片的UI，具有悬停操作、批量编辑模式、键盘快捷键和文件资源管理器上下文菜单
LLM重新排名：可选的两阶段搜索——快速混合结果立即显示，然后由本地LLM重新排名以获得更高的精度
上下文搜索：切换搜索面板根据光标位置、选择或当前段落自动显示相关注释的模式，无需键入
页面预览：Cmd+将鼠标悬停在任何搜索结果上，无需离开面板即可预览笔记
隐私第一：一切都在本地运行，你的隧道，你的数据

16种MCP工具可用:

read_file -读取文件内容（可选数据视图渲染）
write_file -创建新文件（仅创建，现有文件有错误）
list_files -浏览目录
edit_file -查找和替换文本
search -统一内容搜索：混合（关键字+语义）、矢量或全文模式，带标签/路径过滤
find -按名称、路径、标签或带有元数据的frontmatter属性查找文件
move_file -移动或重命名文件
copy_file -将文件复制到新位置
create_folder -创建文件夹（支持mkdir-p）
delete -删除文件/文件夹（支持垃圾桶）
execute_command -运行黑曜石命令
get_vault_context -加载vault的上下文文档（自动呈现Dataview）
dataview_query -执行Dataview查询，获取结构化vault数据（需要Dataview插件）
get_next_chaos -获取下一个未处理的混乱项目进行分类（单模式或列表模式）
mark_triage -记录分诊决定（已处理、推迟、确认、下一步、重置）
copy-obsidian-url -复制当前文件的内部黑曜石URL

即将推出

聊天界面：通过WhatsApp/Telegram连接以进行移动访问
心跳提示：每日/每周提示您保持保险库新鲜
混沌监测：未处理的项目堆积时收到通知

安装

先决条件

黑曜石1.0.0或更高版本
Node.js 20+（用于克劳德桌面连接）
Claude Desktop应用程序（可选，用于AI集成）
奥拉玛（可选，用于语义搜索）

通过BRAT安装（推荐）

安装Witness最简单的方法是使用 BRAT插件:

从黑曜石社区插件安装BRAT
打开BRAT设置并单击“添加Beta插件”
输入： jawache/witness
点击“添加插件”
在社区插件中启用见证

BRAT将在新版本发布时自动更新Witness。

手动安装

如果您更喜欢手动安装：

下载最新版本
- 首选发布
- 下载 main.js 和 manifest.json

在您的保险库中安装

# Create plugin folder
mkdir -p /path/to/your/vault/.obsidian/plugins/witness/

# Copy files
cp main.js manifest.json /path/to/your/vault/.obsidian/plugins/witness/

启用黑曜石
- 打开黑曜石设置→ 社区插件
- 如果系统提示，禁用安全模式
- 在列表中找到“见证人”并启用它

从源代码构建

对于希望从源代码构建的开发人员：

克隆存储库

git clone https://github.com/jawache/witness.git
cd witness

构建插件
```
npm install
npm run build
```

在您的保险库中安装

cp main.js manifest.json /path/to/your/vault/.obsidian/plugins/witness/

连接到克劳德桌面

配置Claude桌面版

编辑 ~/.claude/claude_desktop_config.json （或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "witness": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:3000/mcp",
        "--transport",
        "http-only",
        "--allow-http"
      ]
    }
  }
}

重新启动克劳德桌面
验证连接

在Claude Desktop中，您应该在MCP服务器列表中看到“见证”。试着问：

“你能列出我保险库中的文件吗？”

用法

整理您的保险库

为了获得最佳效果，请使用以下顶级文件夹组织您的保管库：

vault/
├── chaos/
│   ├── external/     # Articles, videos, clippings
│   └── inbox/        # Quick capture notes
└── order/
    ├── knowledge/    # Organized information
    ├── heartbeat/    # Daily/weekly notes
    ├── projects/     # Active work
    └── synthesis/    # Published output

这种结构不是必需的，但Witness旨在帮助您保持这种流程。

设置

打开黑曜石设置→ 证人。设置被组织到选项卡中：

常规选项卡

启用MCP服务器：打开/关闭服务器
端口：HTTP服务器端口（默认值：3000）

远程访问选项卡

启用隧道：通过Cloudflare隧道暴露您的MCP服务器
隧道类型：快速（随机URL）或命名（域名上的永久URL）
需要认证：使用令牌保护远程访问

搜索标签

基本URL：Ollama服务器地址（默认值： http://localhost:11434)
嵌入模型：使用哪种Olama模型进行嵌入（参见支持的型号)
索引状态：显示索引文档的数量，并提供构建/清除按钮
最小内容长度：跳过小于此字符数的文件（默认值：50）。短文件会产生与任何查询匹配的嘈杂的通用嵌入——过滤它们可以显著提高搜索质量。看为什么要过滤短文档？了解详情。
文件夹排除：选择要从索引中排除的文件夹（例如附件、模板）。使用文件夹选择器进行轻松选择。

远程访问

Witness支持两种类型的Cloudflare隧道，以远程公开您的保险库：

选项A：快速隧道（简易、临时）

一个快速隧道会给你一个随机的URL，每次黑曜石重启时都会发生变化。适合测试。

转到黑曜石设置→ 见证
切换“启用隧道”
将隧道类型设置为“快速隧道（临时）”
等待隧道URL出现
启用“要求身份验证”并复制您的MCP URL

URL看起来像： https://random-words.trycloudflare.com/mcp?token=xxx

选项B：命名隧道（永久URL）

命名隧道为您提供自己域上的永久URL。需要一个免费的Cloudflare帐户。

步骤1：在Cloudflare中创建隧道

注册地址： Cloudflare零信任
首选 网络→ 隧道
点击 创建隧道
选择 云雾缭绕 作为连接器类型
命名您的隧道（例如，“目击者”）
在“安装连接器”页面上， 复制隧道令牌 （长 eyJh... 字符串）
跳过连接器安装（Witness会自动处理此问题）
添加一个 公共主机名:
- 子域：例如。， witness
- 域名：选择您的域名（例如。， example.com)
- 服务类型： HTTP
- 网址： localhost:3456 （或您在见证设置中设置的任何端口）
保存隧道

步骤2：配置见证

转到黑曜石设置→ 见证
设置MCP服务器端口以匹配您的隧道配置（例如。， 3456)
切换“启用隧道”
将隧道类型设置为 “命名隧道（永久）”
粘贴您的 隧道令牌 来自Cloudflare
集 隧道URL 到您的公共主机名（例如。， https://witness.example.com)
启用“要求身份验证”（推荐）
点击“复制URL”以获取完整的MCP URL

第三步：连接克劳德

在MCP客户端配置中使用隧道URL：

{
  "mcpServers": {
    "witness": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://witness.example.com/mcp?token=YOUR_TOKEN",
        "--transport",
        "http-only"
      ]
    }
  }
}

这适用于Claude Desktop、Claude.ai web和Claude mobile。

多个设备（黑曜石同步）

如果使用黑曜石同步在多台计算机上同步保管库，则见证插件设置也会同步，包括隧道令牌。如果没有预防措施，每台机器都会尝试启动隧道，Cloudflare会不可预测地在它们之间循环流量。

为了防止这种情况，Witness有一个 主要机器 特点：

打开黑曜石设置→ 在你想运行隧道的机器上作证
在“命名隧道设置”下，单击 “设置为主”
这将保存机器的主机名——只有这台机器将启动隧道
在其他机器上，隧道在启动时会自动跳过

要将主计算机切换到其他计算机，请打开该计算机上的见证设置，然后单击“设置为主计算机”。要完全清除限制，请单击 ✕ 主主机名旁边的按钮。

移动设备

隧道和MCP服务器功能如下 仅限桌面。黑曜石手机（iOS/Android）无法运行HTTP服务器或cloudflared二进制文件。要从移动设备访问您的保险库，请从客户端应用程序（例如Claude mobile）连接到隧道URL——保险库由运行隧道的任何台式机提供服务。

安全说明

身份验证令牌包含在URL查询参数中。HTTPS在传输过程中对此进行加密，但在共享URL或记录URL时要谨慎。
为了提高安全性，令牌也可以通过以下方式传递 Authorization: Bearer xxx header而不是查询参数。
这 cloudflared 二进制文件会自动下载并存储在 ~/.witness/bin/.

语义搜索

Witness提供语义搜索，由奥拉玛用于本地嵌入和奥拉马用于矢量存储。一切都在本地运行-没有云服务，没有API密钥。

先决条件

安装Ollama：从下载 ollama.com

拉取嵌入模型:

ollama pull nomic-embed-text    # Good default (768 dims, 2048 token context)
ollama pull mxbai-embed-large   # Higher quality (1024 dims, 512 token context)

您还可以直接从见证设置页面中提取模型。

构建索引：打开见证设置→ “搜索”选项卡→ 单击“构建索引”

搜索模式

这 search MCP工具（和搜索面板）支持三种模式：

混合（默认）：将QPS关键字匹配与向量余弦相似度相结合。最适合大多数查询——通过语义理解的召回来获得关键字的准确性。
矢量：纯粹的语义相似性。查找概念上相关的文档，即使它们不共享关键字。适合探索性查询，如“关于改善睡眠质量的笔记”。
全文：纯QPS（量子邻近评分）关键字匹配。当你知道确切的术语时，快速准确。不需要嵌入。通过象征性的接近度得分——相邻单词的“碳强度”排名高于分散出现的单词。

支持的嵌入模型

型号	尺寸	上下文	前缀	注释
`nomic-embed-text`	768	2048个令牌	两者都有（必填）	默认值良好。需要 `search_document:` / `search_query:` 前缀——自动处理。
`mxbai-embed-large`	1024	512个令牌	仅限查询	更高质量的嵌入。需要查询前缀--自动处理。
`all-minilm`	384	256个令牌	无	最小且最快。短上下文窗口。
`bge-m3`	1024	8192个标记	无	最长的上下文--最适合非常长的文档。
`bge-large`	1024	512个令牌	无	质量好，不需要前缀。
`snowflake-arctic-embed`	384	512个令牌	仅限查询	紧凑型，质量不错。

任务前缀 是添加到输入文本前的特殊字符串，用于告诉模型是处理文档进行存储还是处理查询进行搜索。见证人通过以下方式自动处理此问题 embedDocuments() 和 embedQuery() --您不需要手动添加前缀。使用错误的前缀（或在需要前缀时不使用前缀）会在错误的向量空间中产生嵌入，使相似性得分毫无意义。

上下文长度和截断

每个嵌入模型都有一个以令牌为单位的最大上下文窗口。超过此长度的文档在嵌入之前会被截断。见证人会自动处理此问题：

动态分辨率：在启动时，Witness询问Ollama的 /api/show 端点，用于获取模型的实际架构上下文长度
客户端预截断：作为安全网，文本被截断为 context_tokens × 2 发送给Ollama之前的字符数（2的系数是保守的每个令牌字符数估计值）
服务器端截断：奥利玛的 truncate: true 参数提供了第二个安全网

重要：重要的上下文长度是模型的建筑上下文长度（例如。， nomic-bert.context_length: 2048), 不模型文件 num_ctx 参数（可以是8192，但不扩展嵌入上下文）。这种区别让我们大吃一惊——nomic嵌入文本报告 num_ctx 8192 但只能嵌入2048个令牌。

具有大量JSON、HTML、URL或非ASCII内容的文档标记效率较低（每个标记低至约1.5个字符，而英语散文的典型标记为约4个字符）。保守的 CHARS_PER_TOKEN = 2 解释了这一点。

为什么要过滤短文档？

非常短的文档（例如，只包含一个单词如“gold”的文件）会产生 通用嵌入 它们位于向量空间的中心附近。因为它们缺乏独特的内容，所以它们最终与所有东西等距——余弦相似性在任何查询中都给它们带来了惊人的高分。

这 最小内容长度 设置（默认值：50个字符）在索引时过滤掉这些字符。这是在不改变嵌入模型的情况下提高搜索质量的最有效设置。

您可能希望提高此阈值的迹象：

搜索结果包括存根页、空模板或占位符文件
相同的短文档出现在无关查询的结果中
矢量搜索返回的结果明显比全文差

指数持久性

索引存储在 .witness/index.orama 作为单个JSON文件存储在vault中。它包含一个模式版本号——当模式更改时（例如，添加新字段时），旧索引会自动丢弃，并在下次使用时触发完整的重新索引。

强制完全重新索引：设置→ 搜索→ 清除索引→ 构建索引。

示例命令

连接到Claude Desktop后，您可以问：

“显示我混乱/收件箱文件夹中的所有文件”
“阅读我每日笔记的内容”
“按照[主题]的顺序/知识创建新笔记”
“列出我保管库中的所有标记文件”

发展

建筑

npm run build          # Production build
npm run dev            # Development mode with watch

测试

# Build and install plugin in test vault
npm run test:install-plugin

# Start Obsidian with test vault
npm run test:start-obsidian

# Run integration tests (47 tests)
npm test

# Check server status
curl http://localhost:3000/health

日志

MCP服务器日志将写入vault的插件文件夹：

.obsidian/plugins/witness/logs/mcp-YYYY-MM-DD.log

这使得以下操作变得容易：

共享错误报告日志
在没有开发人员控制台的情况下调试问题
让AI助手直接读取日志

其他日志位置：

黑曜石控制台： Cmd+Option+I → 控制台选项卡
克劳德桌面： ~/Library/Logs/Claude/mcp-server-witness.log

故障排除

插件无法加载

检查黑曜石控制台是否有错误
验证文件是否位于正确位置： .obsidian/plugins/witness/
尝试禁用并重新启用插件

Claude Desktop无法连接

检查MCP服务器是否正在运行：

curl http://localhost:3000/health
# Should return: {"status":"ok","plugin":"witness"}

检查克劳德桌面日志：

tail -f ~/Library/Logs/Claude/mcp-server-witness.log

验证Node.js版本：

node --version  # Should be 20.x or higher

MCP服务器断开连接（macOS睡眠）

如果MCP服务器在一段时间不活动后无法访问，则您的Mac可能正在休眠并断开网络连接。检查您当前的电源设置：

pmset -g

按键设置为 networkoversleep --如果是 0，macOS在睡眠期间会断开所有网络连接，从而杀死远程客户端的MCP服务器。

修复：在睡眠期间启用网络访问

sudo pmset -a networkoversleep 1

保持服务器可访问的其他有用电源设置：

# Prevent system sleep on AC power
sudo pmset -c sleep 0

# Enable Wake on LAN (allows remote wake)
sudo pmset -c womp 1

# Disable Power Nap (can interfere with network stability)
sudo pmset -c powernap 0

快速修复：暂时保持清醒

如果您不想永久更改系统设置，请运行 caffeinate 在终端中：

# Prevent idle and system sleep (Ctrl+C to stop)
caffeinate -si

# Or run in the background
caffeinate -si &

关键pmset设置

设置	值	效果
`networkoversleep`	`1`	在睡眠期间保持网络活动
`womp`	`1`	启用LAN唤醒
`tcpkeepalive`	`1`	在睡眠期间保持TCP连接
`sleep`	`0`	禁用系统睡眠（交流电源： `-c`)
`powernap`	`0`	禁用电源小睡

端口已在使用中

如果端口3000被占用：

打开黑曜石设置→ 见证
更改端口号（例如3001）
更新您的Claude Desktop配置以匹配

建筑

Witness在Obsidian的Electron进程中运行一个HTTP服务器：

Claude Desktop (MCP Client)
    ↓ stdio
mcp-remote bridge
    ↓ HTTP + SSE
Witness Plugin (MCP Server)
    ↓ Direct API
Obsidian Vault

这与其他在外部运行并通过REST API连接的黑曜石MCP服务器不同。Witness可以直接访问Obsidian的内部API，以获得最大的可靠性和性能。

路线图

第一阶段：MCP服务器✅

[x] 基础插件脚手架
[x] HTTP服务器实现
[x] 文件操作（读、写、列表、编辑）
[x] Claude桌面集成
[x] 全文搜索
[x] 命令执行
[x] 定向文件系统
[x] 基于文件的日志记录
[x] 集成测试套件（47个测试）

第二阶段：远程访问✅

[x] Cloudflare快速隧道集成
[x] Cloudflare命名隧道支持（永久URL）
[x] 多设备同步的主机名称
[x] 远程访问的令牌身份验证
[]WhatsApp/电报机器人
[]多用户会话

第三阶段：语义搜索✅

[x] 通过Ollama进行本地嵌入（nomic嵌入文本、mxbai嵌入大等）
[x] Orama矢量存储，具有混合（BM25+矢量）、仅矢量和全文模式
[x] 实现最佳检索质量的特定于模型的任务前缀
[x] 通过Ollama解析动态模型信息 /api/show
[x] 客户端预截断以确保上下文长度安全
[x] 针对短文档噪声的最小内容长度过滤器
[x] 使用文件夹选择器UI排除文件夹
[x] 搜索面板侧边栏视图
[x] 带模型拉取和实时索引进度的标签设置UI
[x] 在4097文件库上测试

数据视图集成✅

[x] dataview_query MCP工具（标记+JSON输出）
[x] read_file 用于解析Dataview代码块的呈现参数
[x] get_vault_context 自动呈现Dataview查询
[x] 8集成测试

混沌分类✅

[x] get_next_chaos 工具（单列表模式、队列计数、优先级排序）
[x] mark_triage 工具（已处理、延迟、确认、下一步、重置）
[x] 安全前沿更新通过 processFrontMatter API
[x] AI护栏：仅创建 write_file，改善 edit_file 错误

混沌队列面板✅

[x] 带有基于卡片的UI的可视化侧边栏（标题、路径、智能片段）
[x] 带有可折叠部分的“Next Up”和“Queue”组
[x] 仅悬停操作按钮（确认、标记下一步、移动到死亡、重置）
[x] 批量编辑模式，包括全选、批量确认、批量移动到死亡
[x] 10个键盘命令（分流操作、兄弟导航、面板切换）
[x] 具有冲突检测功能的设置中的内联热键捕获
[x] 混乱文件和文件夹的文件资源管理器上下文菜单
[x] 动作后导航（移动到死亡后的下一个兄弟文件）
[x] Live vault事件侦听器（从面板中删除已删除/重命名的文件）

第四阶段：情报

[]心跳调度程序（每日/每周提示）
[]混沌监测（检测陈旧项目）
[]聪明的建议
[]自动分类

阶段5：高级功能

[]图形分析
[]模板系统
[]工作流自动化

贡献

欢迎投稿！该项目正处于积极的早期开发阶段。

指南

保持简单和专注
保持对其他插件的零依赖
测试包含 test-vault/
遵循现有代码样式

许可证

麻省理工学院

致谢

建立在模型上下文协议通过Anthropic
受Zettelkasten和PARA方法的启发
感谢黑曜石社区提供这个令人惊叹的平台

支持

问题: GitHub 问题
讨论: GitHub讨论
推特: @牙疼

“预测未来的最好方法就是发明它。”-艾伦·凯

使用说明

见证

哲学：混沌→ Order

特性

电流（第1+2+3阶段）✅

即将推出

安装

先决条件

通过BRAT安装（推荐）

手动安装

从源代码构建

连接到克劳德桌面

用法

整理您的保险库

设置

常规选项卡

远程访问选项卡

搜索标签

远程访问

选项A：快速隧道（简易、临时）

选项B：命名隧道（永久URL）

多个设备（黑曜石同步）

移动设备

安全说明

语义搜索

先决条件

搜索模式

支持的嵌入模型

上下文长度和截断

为什么要过滤短文档？

指数持久性

示例命令

发展

建筑

测试

日志

故障排除

插件无法加载

Claude Desktop无法连接

MCP服务器断开连接（macOS睡眠）

修复：在睡眠期间启用网络访问

快速修复：暂时保持清醒

关键pmset设置

端口已在使用中

建筑

路线图

第一阶段：MCP服务器✅

第二阶段：远程访问✅

第三阶段：语义搜索✅

数据视图集成✅

混沌分类✅

混沌队列面板✅

第四阶段：情报

阶段5：高级功能

贡献

指南

许可证

致谢

支持

相关 MCP

Qdrant向量搜索MCP服务器

开发者辅助工具

GSAP动画生成工具

Obsidian笔记搜索服务

n8n工作流管理服务

组件参考服务