Zettel Link 技能

该技能提供了一组幂等的 Python 脚本，用于在 Obsidian 仓库中基于语义相似度实现笔记的嵌入（embedding）、搜索与链接。所有脚本均位于 scripts/ 目录下，并支持多种嵌入服务提供商。

当用户需要搜索笔记、检索笔记或发现笔记之间的关联关系时，应触发该技能。

若待搜索目录已通过嵌入完成索引，该技能将提示用户是否要重新生成嵌入。

依赖项

• uv 0.10.0+
• Python 3.10+
• 以下任一嵌入服务提供商：
  • Ollama（本地，默认）搭配 mxbai-embed-large
  • OpenAI API 搭配 text-embedding-3-small
  • Google Gemini API 搭配 text-embedding-004

命令概览

• uv run scripts/config.py：配置嵌入模型及其他参数。
• uv run scripts/embed.py：对笔记执行嵌入，并缓存至 .embeddings/embeddings.json。
• uv run scripts/search.py：在已嵌入的笔记上执行语义搜索。
• uv run scripts/link.py：发现语义关联关系，并输出至 .embeddings/links.json。

工作流程

步骤 0 — 初始化与配置

若 config/config.json 文件尚不存在，请先创建：

uv run scripts/config.py

该命令将生成默认配置文件 config/config.json，内容如下：

{
    "model": "mxbai-embed-large",
    "provider": {
        "name": "ollama",
        "url": "http://localhost:11434"
    },
    "max_input_length": 8192,
    "cache_dir": ".embeddings",
    "default_threshold": 0.65,
    "top_k": 5,
    "skip_dirs": [".obsidian", ".trash", ".embeddings", "Spaces", "templates"],
    "skip_files": ["CLAUDE.md", "Vault.md", "Dashboard.md", "templates.md"]
}

如需使用远程服务提供商，请运行：

# OpenAI
uv run scripts/config.py --provider openai

# Gemini
uv run scripts/config.py --provider gemini

# 自定义模型
uv run scripts/config.py --provider openai --model text-embedding-3-large

如需调整调优参数，请运行：

uv run scripts/config.py --top-k 10 --threshold 0.7 --max-input-length 4096

步骤 1 — 生成嵌入

uv run scripts/embed.py --input 

该命令将在 /.embeddings/embeddings.json 中生成嵌入缓存文件。

• 增量更新：仅对自上次运行以来被修改过的文件重新执行嵌入（依据文件修改时间戳判断）。
• 文本截断：在嵌入前自动将文本截断至 max_input_length 长度。
• 过期清理：移除已不存在文件对应的嵌入条目。
• 强制重嵌入：使用 --force 参数可强制对全部文件重新嵌入。

步骤 2 — 语义搜索

uv run scripts/search.py --input  --query ""

该命令使用已配置的服务提供商对查询语句进行嵌入，并将其与所有已缓存的笔记嵌入向量进行比对，返回语义最相近的前 top_k 篇笔记。

搜索结果将保存至 /.embeddings/search_results.json。

步骤 3 — 语义关联发现

uv run scripts/link.py --input 

该命令计算所有笔记两两之间的余弦相似度，并将高于 default_threshold 的关联关系输出至 /.embeddings/links.json。

输出内容包括：

• 所有关联对（含相似度得分）的扁平化列表
• 按笔记组织的分组结构，便于快速查找

调优说明：可通过 --threshold 参数调整阈值，以放宽或收紧关联发现范围。

缓存机制

• 格式：JSON 格式，含元数据封装层（metadata + data）
• 位置：/.embeddings/embeddings.json
• 元数据：记录生成时间戳、模型名称、服务提供商、嵌入向量维度等信息
• 失效机制：基于文件修改时间（mtime）判定是否失效
• 强制重建：删除缓存文件，或使用 --force 参数

智能体操作指引

使用本技能时，请遵循以下操作规范：

1. 若 config/config.json 尚未存在，务必首先运行 config.py。
2. 在运行 search.py 或 link.py 前，必须先运行 embed.py —— 缓存文件为必要前提。
3. 对于远程服务提供商（openai、gemini），请确保已设置对应 API 密钥的环境变量（或在技能目录下提供本地 .env 文件）。
4. 所有脚本均为幂等设计，可安全重复执行。