Skip to content
Back to search

dsh-obsidian-assistant

SkillWorks with Claude CodeGitHub

操作本地 Obsidian 知识库:搜索、读写笔记、查询双向链接与关系图谱、批量整理,并可通过 Obsidian Local REST API 调用高级能力。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iamzcr--dsh-obsidian-assistant/badge.svg)](/listings/iamzcr--dsh-obsidian-assistant)

HTML

<a href="/listings/iamzcr--dsh-obsidian-assistant"><img src="/api/listings/iamzcr--dsh-obsidian-assistant/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 50 lines
  1. ---
  2. name: dsh-obsidian-assistant
  3. description: 操作本地 Obsidian 知识库:搜索、读写笔记、查询双向链接与关系图谱、批量整理,并可通过 Obsidian Local REST API 调用高级能力。
  4. whenToUse: 当用户要求查找、阅读、创作、编辑、分析或整理其本地 Obsidian vault 中的笔记时使用。
  5. ---
  6. # Obsidian 知识库操作规范
  7. 本技能通过 `obsidian_*` 工具操作一个本地 Obsidian vault(知识库)。
  8. ## 可用工具
  9. | 工具 | 用途 |
  10. |---|---|
  11. | `obsidian_search` | 全文/标题检索(支持 `tag` 过滤),返回路径 + 片段 + 标签 |
  12. | `obsidian_read_note` | 读单篇笔记(正文 + frontmatter) |
  13. | `obsidian_create_note` | 新建笔记(可带 frontmatter) |
  14. | `obsidian_update_note` | 字面量替换编辑 / 追加 |
  15. | `obsidian_list_structure` | 文件夹树 + 标签统计 + 孤立笔记 |
  16. | `obsidian_backlinks` | 反向链接、出链与 tag 归属图谱 |
  17. | `obsidian_batch` | 批量移动/重命名(自动重写内部 `[[链接]]`) |
  18. | `obsidian_export_novel` | 把 `第X章-标题` 章节笔记清洗导出为 TXT/Markdown 小说文稿,按章号落盘到 `导出/`,可用 `exclude` 排除废稿/整章 |
  19. | `obsidian_rest_query` | 透传 Local REST API 任意端点(通道 B) |
  20. | `obsidian_rest_search` | Obsidian 内部索引高速全文搜索(通道 B,适合大库) |
  21. | `obsidian_list_commands` | 列出 Obsidian 命令(id + 名称,通道 B) |
  22. | `obsidian_run_command` | 触发 Obsidian 命令(Templater / Dataview 重渲染等,通道 B) |
  23. ## 使用规则(务必遵守)
  24. 1. **路径边界**:所有路径都是 vault 相对路径(正斜杠,可省略 `.md` 后缀)。绝对不要拼接到 vault 之外的路径。
  25. 2. **先读后改**:编辑或覆盖前先 `obsidian_read_note` 确认现状,保留已有 frontmatter 字段。
  26. 3. **frontmatter 规范**:新增字段用合法 YAML;`tags` 用数组,别名用 `aliases`,创建时间用 `created`。
  27. 4. **双向链接**:`[[笔记名]]` 用不含扩展名的笔记名;`[[笔记名#标题]]` 指向小节;`![[笔记名]]` 为嵌入。
  28. 5. **标签**:`#kebab-case` 或 `#嵌套/标签`。
  29. 6. **写作工具**:只读工具 `obsidian_search`/`read_note`/`list_structure`/`backlinks` 无需审批即可用;写工具 `create_note`/`update_note`/`batch`/`export_novel` 优先走 harness 文件系统真实写入。
  30. ## 双通道说明
  31. - **通道 A(文件直读写)**:始终可用,通过 harness 文件系统服务读写 vault 里的 `.md`。
  32. - **通道 B(Local REST API)**:当 Obsidian 正在运行且安装了 "Local REST API" 社区插件时自动可用。用于高速全文搜索(`obsidian_rest_search`)、触发命令/模板(`obsidian_run_command` + `obsidian_list_commands`)。不可用时自动降级到通道 A,无需向用户解释技术细节。
  33. - **Dataview 查询**:Local REST API 无原生 dataview 端点。需要 dataview 时,先 `obsidian_list_commands` 找到 dataview 相关命令 id,再用 `obsidian_run_command` 触发它。
  34. ## 典型任务流程
  35. - **"找到讲 XX 的笔记"**:`obsidian_search(query="XX")` → 对命中的路径 `obsidian_read_note`。(库很大时优先 `obsidian_rest_search`)
  36. - **"新建一篇 XX 笔记"**:`obsidian_create_note(path="XX", content="...", frontmatter={tags:[...]})`。
  37. - **"谁引用了这篇笔记"**:`obsidian_backlinks(note="笔记名")`。
  38. - **"整理库结构"**:`obsidian_list_structure` 先看树与孤立笔记,再 `obsidian_batch` 移动。
  39. - **"把小说导出方便发布到起点/番茄等平台"**:`obsidian_export_novel(folder="小说", format="txt"|"markdown"|"both", exclude=["章号或标题"], includeCode=...)` 把 `第X章` 章节清洗成可直接粘贴的文稿,落盘到 `导出/`;用 `exclude` 排掉废稿/重复章。
  40. - **"跑一下 XX 模板/命令"**:`obsidian_list_commands` 找命令 id → `obsidian_run_command(commandId=...)`。
README.md · README · 160 lines
  1. # dsh-obsidian-assistant
  2. DeepSeek Harness 插件(Cordis toolset):操作本地 Obsidian 知识库(vault),提供搜索、读写笔记、双向链接 / 关系图谱、批量整理,并通过 Obsidian 的 "Local REST API" 社区插件调用高级能力(高速全文搜索、触发命令 / 模板)。
  3. > 一套插件,双通道,统一操作同一个 vault:不依赖 Obsidian 运行也能读写(文件通道),Obsidian 在线时自动增强(REST 通道)。
  4. ---
  5. ## 功能一览(12 个工具)
  6. ### 通道 A · 文件直读写(始终可用,不依赖 Obsidian 运行)
  7. | 工具 | 说明 |
  8. |---|---|
  9. | `obsidian_search` | 全文 / 标题检索,支持按 `tag` 过滤,返回路径 + 片段 + 标签 |
  10. | `obsidian_read_note` | 读单篇笔记(frontmatter + 正文),可带 / 不带 `.md` 后缀 |
  11. | `obsidian_create_note` | 新建笔记(可带 YAML frontmatter,拒绝覆盖已存在笔记) |
  12. | `obsidian_update_note` | 字面量替换 / 追加编辑(幂等、安全) |
  13. | `obsidian_list_structure` | 文件夹树 + 标签统计 + 孤立笔记 |
  14. | `obsidian_backlinks` | 反向链接 + 出链 + tag 归属图谱 |
  15. | `obsidian_batch` | 批量移动 / 重命名,自动重写全库 `[[wikilink]]` |
  16. | `obsidian_export_novel` | 把 vault 里按 `第X章-标题` 命名的章节笔记,清洗成可粘贴到小说平台的 TXT / Markdown 文稿,按章号排序落盘 |
  17. ### 通道 B · Local REST API(需 Obsidian 运行 + 安装该社区插件)
  18. | 工具 | 说明 |
  19. |---|---|
  20. | `obsidian_rest_search` | Obsidian 内部索引高速全文搜索(大库首选) |
  21. | `obsidian_list_commands` | 列出 Obsidian 命令(id + 名称) |
  22. | `obsidian_run_command` | 触发命令(Templater / Dataview 重渲染等) |
  23. | `obsidian_rest_query` | 透传任意 REST 端点(兜底 / 高级用法) |
  24. > **Dataview 说明**:Local REST API 无原生 dataview 端点,dataview 查询需通过 `obsidian_list_commands` 找到 Dataview 命令 id,再用 `obsidian_run_command` 触发。
  25. ---
  26. ## 安装与注册
  27. 本插件是一个 **profile bundle**。完整、可操作的接入步骤见 [`DEPLOY.md`](./DEPLOY.md)。核心两步:
  28. 1. 把 `dsh-obsidian-assistant` 加进 profile 的 bundles 列表(`$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles`);
  29. 2. 在 profile 的 `cordis.patch.yml` 里为它指定 `vaultPath`(唯一必填项,没有可移植的默认值,所以 bundle 里不预设):
  30. ```yaml
  31. # $DSH_HOME/profiles/<name>/cordis.patch.yml(顶层数组里追加)
  32. - id: dsh-obsidian-assistant
  33. config:
  34. vaultPath: 'D:/my-notes' # 必填:vault 根目录绝对路径(正斜杠)
  35. # 以下均为可选,有默认值:
  36. # apiUrl: 'https://127.0.0.1:27124'
  37. # apiToken: ''
  38. # enableRestApi: true
  39. # excludePatterns: ['.obsidian', '.trash']
  40. # maxResults: 50
  41. ```
  42. > 本插件 `inject: ["tools", "fs"]`,依赖 base bundle 提供的 `tools` 与 `fs` 服务,因此必须挂在 base bundle 之后(base 天然是第一个 bundle)。
  43. ### 配置项
  44. | 字段 | 必填 | 默认 | 说明 |
  45. |---|---|---|---|
  46. | `vaultPath` | ✅ | — | vault 根目录绝对路径(正斜杠) |
  47. | `apiUrl` | | `https://127.0.0.1:27124` | Local REST API 地址 |
  48. | `apiToken` | | `""` | Local REST API 的 API Key(每个 vault 独立) |
  49. | `enableRestApi` | | `true` | 是否启用通道 B(不可用自动降级) |
  50. | `excludePatterns` | | `['.obsidian', '.trash']` | 排除目录(前缀匹配或 `*` 通配) |
  51. | `maxResults` | | `50` | 文件通道搜索最大命中数 |
  52. > ⚠️ **自签名证书**:Local REST API 默认 HTTPS + 自签名,本插件已在请求层用 `node:https`(`rejectUnauthorized: false`)容忍,无需额外设置环境变量。
  53. ---
  54. ## 关键行为
  55. - **路径安全**:所有路径必须是 vault 相对路径,逃逸(`../`)一律拒绝。
  56. - **移动 = 重写链接**:`obsidian_batch` 的 `move` 会把全库中 `[[旧名]]` 自动改写为 `[[新名]]`(对齐 Obsidian rename 行为),并返回更新了几处链接。
  57. - **排除规则**:`excludePatterns` 支持目录名前缀匹配和 `*` 通配。
  58. - **孤立笔记**:`obsidian_list_structure` 的 orphan 判定 = 既无入链也无出链。
  59. - **双通道降级**:REST API 不可用时所有读写自动走文件模式,无感知降级。
  60. ## 已知限制
  61. - harness 的 `FileSystem` 服务无 `delete`/`rename` API,因此 `move` 在 harness `ctx.fs` 后端下是「复制 + 源文件清空」(`sourceRemoved: false`),在纯 Node fallback 下才是真正的 `rename`(`sourceRemoved: true`)。数据不会丢失,但源位置可能残留空文件。
  62. - Local REST API 无原生 dataview 端点(见上)。
  63. ---
  64. ## Obsidian 小说导出(`obsidian_export_novel`)
  65. 用于把 vault 里按 **`第X章-标题`** 命名的小说章节笔记,导出成**可直接粘贴到小说平台后台**(起点 / 番茄 / 晋江 / 纵横 / 飞卢 等)的文稿,零风险(不做浏览器自动化、不触碰平台风控)。
  66. **行为**
  67. - **识别章节**:文件名匹配 `第X章`(支持中文数字与阿拉伯数字)或裸数字章节(`12. 标题`)。
  68. - **排序**:按解析出的章号升序排序,不以 frontmatter 的 `章节` 字段为准(该字段常与文件名不一致)。
  69. - **排除**:`exclude` 可排掉整章(章号)或指定废稿(路径/标题子串),命中章号的重复/草稿一并跳过。
  70. - **清洗**:自动去掉 YAML frontmatter、`#` 标题标记、`>` 引用、`**粗体**`/`*斜体*`、`~~删除~~`、图片/链接/`[[wikilink]]`、脚注、HTML 注释与列表记号,保留正文;代码块 / 行内代码默认保留(`includeCode: false` 时整体去除)。
  71. - **落盘**:写入 vault 的 `<outDir>/<书名>_<UTC时间戳>/` 文件夹,每章一个 `.txt` 和/或 `.md` 文件。
  72. **参数**
  73. | 参数 | 默认 | 说明 |
  74. |---|---|---|
  75. | `format` | `both` | `txt` / `markdown` / `both`,每章产出对应格式文件 |
  76. | `folder` | 全库 | 可选,限定扫描的 vault 相对子目录(如 `小说`) |
  77. | `query` | 无 | 可选,按路径/标题子串过滤章节 |
  78. | `exclude` | 无 | 可选,排除章节。数字或 `第X章` 项排除整个章号(含其所有重复/草稿);其他项按路径/标题子串(忽略大小写)排除废稿 |
  79. | `includeCode` | `true` | 是否保留代码块与行内代码 |
  80. | `outDir` | `导出` | 输出目录(vault 相对路径) |
  81. | `bookName` | folder 末段 / `小说` | 用来命名输出文件夹 |
  82. 示例(在会话里让模型执行):
  83. ```
  84. 把 小说/ 目录下的章节导出成 txt 方便我发布到起点
  85. ```
  86. 等价于调用 `obsidian_export_novel({ folder: "小说", format: "txt" })`,产出 `导出/小说_2026-08-17_153000/第一章-xxx.txt ...`。
  87. 排除草稿/重复章节(例如库里有两份「第三章」、两份「他的浪漫代码」):
  88. ```
  89. 导出 小说,但排除第 3 章和标题带 "浪漫代码" 的废稿
  90. ```
  91. 等价于 `obsidian_export_novel({ folder: "小说", format: "txt", exclude: ["3", "浪漫代码"] })`。
  92. ## 开发
  93. ```bash
  94. npm install
  95. npm run build # 编译到 lib/
  96. npm run smoke # 核心逻辑冒烟测试(不依赖 harness)
  97. npm run test:int # 集成测试(验证 12 工具注册 + execute)
  98. npm run rest:smoke # 通道 B 实时冒烟(需 OBSIDIAN_API_KEY / OBSIDIAN_API_URL 环境变量)
  99. ```
  100. `rest:smoke` 用法:
  101. ```bash
  102. OBSIDIAN_API_KEY=<key> OBSIDIAN_API_URL=https://127.0.0.1:27124 npm run rest:smoke
  103. ```
  104. ## 目录结构
  105. ```
  106. src/
  107. index.ts 插件入口(name/inject/Config/apply + 12 个工具注册)
  108. export.ts 小说导出(章节识别/排序/清洗/TXT+Markdown 渲染)
  109. vault.ts VaultService(通道 A:读写/图谱/批量/链接重写/排除/路径防护)
  110. rest.ts ObsidianApiClient(通道 B:探测 + 搜索/命令/透传,node:https 容忍自签名)
  111. scripts/
  112. smoke.mjs 核心逻辑冒烟测试
  113. integration.mjs 集成测试(mock ctx.fs/ctx.tools 验证工具注册 + execute)
  114. rest-smoke.mjs 通道 B 实时冒烟(环境变量传 key)
  115. fixtures/vault/ 测试用 vault 示例笔记
  116. cordis.patch.yml bundle patch(insert 插件条目)
  117. SKILL.md 模型可见的技能指令
  118. DEPLOY.md 完整接入步骤
  119. ```
  120. ## License
  121. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.