@harness-flow/dsh-obsidian

Readme

<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 能理解的结构**，三步完成：

```mermaid
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

```powershell
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
# 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

```powershell
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](https://github.com/coddingtonbear/obsidian-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

```powershell
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

| Repository | Responsibility |
|---|---|
| [coddingtonbear/obsidian-local-rest-api](https://github.com/coddingtonbear/obsidian-local-rest-api) | Upstream Obsidian REST/MCP plugin (integration contract only) |
| `Harzva/dsh-obsidian` | This plugin: project scanner, graph generator, DSH bridge and UI |

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

## License

[MIT](LICENSE) © 2026 Harzva