Obsidian Smart Links
为指定的 Obsidian 笔记深度分析链接机会，构建双向连接，支持段落级链接。
核心能力
- 分析笔记的现有外链和反链
- AI 推理潜在链接机会（不只是关键词匹配）
- 支持三层链接粒度：笔记级 / 章节级 / 段落级
- 生成结构化外链详情报告，交互确认后写入
- 同时建立正向链接和反向链接（双向连接）
工作流：分 5 步执行
Step 1：CLI 侦察（确定目标笔记）
确认目标笔记及其在 vault 中的位置：
# 列出目标目录的笔记
obsidian files folder="笔记目录" ext=md
# 获取目标笔记的章节结构（含行号，用于段落级链接）
obsidian outline file="笔记名" format=json
# 查看现有外链和反链
obsidian links path="笔记路径"
obsidian backlinks file="笔记名"
也可直接指定笔记路径，Claude Code 会自动分析。
Step 2：采集链接数据（Commands）
使用 slash commands 简化脚本调用：
/obsidian-links-status "笔记名" # 获取笔记链接现状
/obsidian-links-search "笔记名" "关键词" # 在 vault 中搜索相关段落
/obsidian-links-context "笔记名" # 导出完整分析上下文
等价于手动运行：
python3 .claude/skills/obsidian-smart-links/scripts/analyze_links.py "笔记名" --status
Step 3：Claude Code 深度分析
Claude Code 读取笔记全文 + 采集数据，深度推理链接机会：
- 理解笔记主题：识别核心技术栈、方法论、核心观点
- 搜索相关笔记：在 vault 中找出语义相关的笔记
- 判断链接粒度：
- 笔记级：
[[Note]]— 引用整篇 - 章节级：
[[Note#Heading]]— 引用特定章节 - 段落级：
[[Note#^block-id]]— 引用具体观点
- 笔记级：
- 生成推荐理由：说明链接价值
详细策略见 references/LINK_STRATEGIES.md。
Step 4：生成外链详情报告
Claude Code 依据 references/LINK_REPORT_TEMPLATE.md 生成报告，包含：
- 现有链接状态：已有哪些外链和反链
- 推荐链接列表：每个推荐包含理由、插入位置、链接粒度
- 交互确认：用户逐条确认（Y/n/q）
- block-id 清单：段落级链接需要的 block-id
Step 5：写入链接
Claude Code 根据确认结果写入 wikilink：
# 章节级链接（直接插入）
Prompts 是即时灵活的对话指令。[[Agent Skills#Skills：可复用的专属能力包]] 则进一步将高频方法固化为可复用能力包。
# 段落级链接（两步操作）
# 步骤 1: 在目标笔记添加 block-id
Agentic 生态系统通过整合 MCP 等组件... ^mcp-ecosystem
# 步骤 2: 在当前笔记插入段落级链接
[[Agent 前沿解读#^mcp-ecosystem]] 详细描述了...
三层链接粒度
| 粒度 | 格式 | 适用场景 |
|---|---|---|
| 笔记级 | [[Note]] | 延伸阅读、引用整篇 |
| 章节级 | [[Note#Heading]] | 引用特定章节（Claude Code 自动从 outline 获取 heading） |
| 段落级 | [[Note#^block-id]] | 引用具体观点（需先定义 block-id） |
详见 references/LINK_STRATEGIES.md。
段落级链接的工作流程
段落级链接需要两步操作：
步骤 1：在目标笔记的相关段落添加 block-id
Agentic 生态系统通过整合 MCP 等组件... ^mcp-ecosystem
步骤 2：在当前笔记插入段落级链接
[[Target Note#^mcp-ecosystem]]
Claude Code 会自动生成稳定的 block-id（基于 heading + 段落内容的 hash）。
双向链接策略
好的链接是双向的。Claude Code 在建立链接时会同时考虑：
- 正向链接：在当前笔记 → 目标笔记
- 反向链接：在目标笔记的相关位置 → 当前笔记（如果有语义相关性）
注意事项
- CLI 侦察不要跳过：先了解现有链接状态，避免重复建立
- 段落级链接谨慎使用：只对有独立价值的段落使用，避免标签噪音
- block-id 稳定性：基于内容 hash 生成，即使笔记重构也保持有效
- 交互确认不可跳过：每次写入前必须确认，用户掌控最终结果