dsh-obsidian-harzva

<h1 align="center">dsh-obsidian</h1>

<p align="center"> <strong>把本机项目接入 Obsidian：扫描项目 → 生成 wiki 链接笔记 → Obsidian 图谱视图自动呈现知识图谱。</strong><br /> Bridge local projects into Obsidian and let its graph view render the knowledge graph. </p>

<p align="center"> <img alt="Status: alpha" src="https://img.shields.io/badge/status-alpha-f59e0b" /> <img alt="DSH 0.1.0-rc.6" src="https://img.shields.io/badge/DSH-0.1.0--rc.6-2563eb" /> <img alt="Tests: 14 passing" src="https://img.shields.io/badge/tests-14%20passing-16a34a" /> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a> </p>

> [!IMPORTANT] > Independent, unofficial DSH integration. Works fully offline: the Obsidian app does not need to be > running while notes are generated, and no data ever leaves your machine.

Obsidian 如何"识别"本机项目并建立知识图谱

Obsidian 的图谱视图不扫描代码仓库，它只索引 vault 里的 .md 文件 + [[wiki 链接]]。 所以关键不是"让 Obsidian 去扫描项目"，而是把项目转译成 Obsidian 能理解的结构，三步完成：

flowchart LR
    P["本机项目目录<br/>package.json · Cargo.toml · .git"] --> S["1. 扫描<br/>manifest 探测 · 技术栈 · repo"]
    S --> G["2. 建边<br/>依赖 · 技术栈 · 区域 · 主题"]
    G --> N["3. 生成笔记<br/>graph/projects/·graph/tech/·graph/areas/"]
    N --> V["Obsidian vault<br/>graph/ 命名空间"]
    V --> O["图谱视图<br/>按 [[链接]] 聚类成簇"]

1. 发现：按 package.json / Cargo.toml / go.mod / pyproject.toml / .git 识别项目； 提取 npm name、依赖、描述、技术栈、git remote。 2. 建边：依赖（npm name、workspace:*、file: 引用）、技术栈、根目录区域、关键词主题 —— 全部确定性，无虚构关联。 3. 落盘：每个项目一张笔记，graph/tech/<栈>、graph/areas/<区域>、graph/topics/<主题> 是 hub 笔记。 Obsidian 打开 vault 即自动索引，图谱视图里 hub 成为簇中心、依赖成为连线。

在 DSH 里只需两步：设置页 扫描项目 → 生成知识图谱。

What works

• Native DSH tab at Settings → Plugins → Obsidian.
• Bounded local project scanner with manifest detection and tech-stack extraction.
• Deterministic knowledge graph: dependency / tech / area / topic edges.
• Dual transport: Obsidian Local REST API (Bearer, loopback) with filesystem fallback — no REST plugin needed.
• Incremental writes via graph/.dsh-obsidian-state.json; only plugin-managed files are ever rewritten or removed.
• Mini force-directed graph preview in the settings tab (dependency view; full graph lives in Obsidian).
• Strict loopback + same-origin guarding; API key never leaves the Host.

Quick start

1. Build and pack the plugin

git clone https://github.com/Harzva/dsh-obsidian.git
cd dsh-obsidian
pnpm install --frozen-lockfile
pnpm check
pnpm run pack:dsh

2. Point it at a vault (optional)

By default the plugin uses the first open vault from Obsidian's obsidian.json and scans its registered vault paths as project roots. Override per-environment:

# PowerShell
$env:DSH_OBSIDIAN_VAULT = '/Volumes/Ultra/study/harzva-local-knowledge-hub/wiki'
$env:DSH_OBSIDIAN_SCAN_ROOTS = '["/Volumes/Ultra/hzh","/Users/harzva/code"]'
# 可选：Local REST API（安装社区插件后设置 API key）
$env:DSH_OBSIDIAN_API_KEY = 'your-api-key'   # 不设置则自动使用文件系统直写
dsh web

3. Install into the DSH Web profile

dsh plugin --profile web add ./artifacts/harness-flow-dsh-obsidian-0.1.0-alpha.0.tgz
dsh web

Open Settings → Plugins → Obsidian, press 扫描项目, then 生成知识图谱. Switch to Obsidian and open the vault's graph view — graph/index.md links everything.

4. Optional: Live transport via Local REST API

Install the community plugin Local REST API, enable its HTTP server (port 27123), copy the API key into DSH_OBSIDIAN_API_KEY, and restart DSH. Writes then land through the REST API while Obsidian is running.

Development

pnpm check
pnpm run pack:dsh
pnpm run verify:dsh-offline

verify:dsh-offline creates an isolated temporary DSH Home, installs the packed plugin into a real DSH 0.1.0-rc.6 Web profile, checks the bridge bootstrap and client module, then removes the temporary profile. It does not read or modify the user's DSH profile.

Project boundaries

Docs: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/PRD.md](docs/PRD.md), [docs/REFERENCE.md](docs/REFERENCE.md).

License

[MIT](LICENSE) © 2026 Harzva