前言¶
DSH 的核心理念是“一切皆插件”，这意味着工具需要具备极强的环境连接能力。对于使用 Obsidian 作为知识库的开发者，最大的痛点在于：Obsidian 默认不扫描代码仓库，它仅索引 vault 里的 .md 文件和 [[wiki 链接]]。因此，关键不在于让 Obsidian 去扫描项目，而在于将本地项目的元数据（如依赖、技术栈）转化为 Obsidian 能理解的 Wiki 链接结构。
dsh-obsidian 插件通过 DSH 扫描本地项目，生成对应的笔记与图谱边，使 Obsidian 图谱视图自动呈现项目间的知识关联。它是一个独立、非官方的 DSH 集成方案。
核心功能¶
- 原生 DSH 集成：在 DSH 的设置中直接提供原生标签页，无需额外 UI 组件。
- 本地项目扫描：扫描器支持 manifest 探测，能够提取技术栈与项目信息。
- 确定性知识图谱：自动生成依赖、技术、区域、主题四种类型的边，结构确定，无虚构关联。
- 双传输模式：支持本地 REST API（loopback）与文件系统回退模式。若不启用 REST 插件，可使用文件系统直写。
- 增量写入：通过
graph/.dsh-obsidian-state文件管理状态，仅重写或删除插件管理的文件。 - 安全与预览：具备严格的 loopback + 同源保护机制。设置页中提供迷你力导向图预览。
安装与启用¶
使用以下命令将插件安装到 DSH Web 配置文件中：
dsh plugin --profile web add ./artifacts/harness-flow-dsh-obsidian-0.1.0-alpha.0.tgz
安装完成后，在 DSH 设置页开启插件，即可使用“扫描项目”与“生成知识图谱”功能。
典型用法¶
- 配置环境变量（可选）：
若需指定 vault 路径或扫描根目录，可通过环境变量覆盖默认行为：
export DSH_OBSIDIAN_VAULT="/path/to/vault"
export DSH_OBSIDIAN_SCAN_ROOTS='["/path/to/project1", "/path/to/project2"]'
-
执行生成：
在 DSH 设置页点击“扫描项目”，确认识别到本地项目后，点击“生成知识图谱”。 -
在 Obsidian 中查看：
打开对应的 Obsidian vault，进入图谱视图。生成的笔记位于graph/命名空间下，通过[[链接]]将项目、技术栈与区域关联起来。
注意事项¶
- 完全离线：Obsidian 应用无需在生成笔记期间运行，插件以当前 DSH 进程权限工作，完全本地化处理。
- 数据安全：无数据会离开本机。
- 基本功能：基础功能无需安装 Obsidian 的 REST 插件，依赖文件系统即可运行。
- 文件管理：插件仅会重写或删除其自身管理的文件，不会影响用户手动编写的笔记。
