# dsh-okf
**Ingest research PDFs into a citable OKF markdown library.**
*Ingest, search, graph, coverage, and surveys in the same conversation. Models and API keys stay with Harness.*
[](LICENSE)
[](package.json)
[](https://www.npmjs.com/package/dsh-okf)
[](https://github.com/1-CellBio/dsh-okf/releases)
[](https://github.com/topics/dsh-plugin)
[中文](./README.md) · **English**
---
## Compatibility
| Surface | Status |
|---|---|
| Harness | [DeepSeek Harness](https://github.com/deepseek-ai/dsh) with the `dsh` CLI |
| Node | `>=20` |
| Library | Markdown under workspace `OKF/` (Paper / Claim / Topic / Method / Entity / Dataset / Gene / Pathway) |
| Models | None configured here. Compile and vision use the harness default multimodal model |
## What you get
- **Document ingest** — PDFs (anydoc text layer + pdfjs fallback; scans/figures go through vision); docx / pptx / xlsx / epub convert to Markdown.
- **Citable concept graph** — Claim is the citation atom, Paper is a linked digest, hubs are cross-linked.
- **Search and coverage** — full-text search (optional vector fusion), evidence, backlinks, topic × year heatmap.
- **Surveys** — draft → `okf_cite_check` verifies ids → save; BibTeX / Pandoc / LaTeX export.
- **Web UI** — session tab **OKF Library**: help / papers (drag-and-drop) / graph / review / coverage / surveys / notes.
```text
source files → extract / vision → segmented compile → hub align
↓
OKF/ markdown library → search / graph / coverage / survey
```
## Quick start
```sh
# 1. Install into the web profile (npm; prebuilt, usually no allowBuilds)
dsh plugin --profile web add dsh-okf
```
Other install channels below. Then:
2. Run `dsh web` and open a session (the workspace folder is where the library lives).
3. Open **OKF Library → Papers** at the top of the session view and drop a PDF (or use “Choose files”).
4. After compile finishes, paste this into chat:
```
What is in this workspace's OKF library? Give a census by type, year, and the most common topics. Do not open any paper.
```
Without the UI, say “ingest ./paper.pdf into OKF”, then paste the same prompt.
## Install & uninstall
- **npm (recommended)**: `dsh plugin --profile web add dsh-okf`
- **git**: `dsh plugin --profile web add github:1-CellBio/dsh-okf`
- **Release tarball**: `dsh plugin --profile web add https://github.com/1-CellBio/dsh-okf/releases/latest/download/dsh-okf.tgz`
- **Local checkout**: `pnpm install && dsh plugin --profile web add ./dsh-okf`
- **Uninstall**: `dsh plugin --profile web remove dsh-okf`
pnpm ≥10 blocks git `prepare` builds. Copy the snippet `dsh` prints into the profile's `pnpm-workspace.yaml`:
```yaml
allowBuilds:
dsh-okf: true
```
Then re-run `add`. npm and Release tarball installs are prebuilt and usually skip this.
`--profile ` is required (`web` is the usual choice). Restart `dsh web` after changing `dsh.client`.
## Configuration
The library lives in **`OKF/`** inside the session workspace. The browser does not read that folder. You can also send `initialize OKF` / 「初始化OKF」 in chat.
| Path | Role |
|---|---|
| `OKF/papers/`, `topics/`, `methods/`, `entities/`, `datasets/`, `genes/`, `pathways/`, `claims/`, `notes/`, `questions/`, `surveys/`, `extracts/` | Concept markdown |
| `OKF/sources/pdfs/`, `OKF/sources/docs/` | Original files (packs omit PDFs) |
| `OKF/manuscripts/` | Export output |
| `OKF/.okf/` | Rebuildable index |
Optional env: `OKF_DIR`, `OKF_PDF_DIR`, `OKF_EXPORT_DIR`. An id-targeted profile patch **replaces the whole `config`**, so restate every field you still need:
```yaml
- id: okf
config:
okfDir: ${cwd}/OKF
pdfDir: ${okfDir}/sources/pdfs
exportDir: ${okfDir}/manuscripts
```
Semantic retrieval is opt-in: set `KG_EMBED_MODEL` / `KG_EMBED_BASE_URL` / `KG_EMBED_API_KEY`, then `okf_sync_vectors`.
## Tools
| Tool | Role |
|---|---|
| `okf_help` | Usage guide + copy-paste example prompts |
| `okf_ingest` / `okf_compile` | Ingest and compile (background jobs) |
| `okf_search` / `okf_get` / `okf_evidence` | Search, read one page, claim evidence |
| `okf_stats` / `okf_coverage` / `okf_check` | Census, coverage, health audit |
| `okf_graph` / `okf_neighbors` / `okf_backlinks` / `okf_compare` | Graph and bounded compare |
| `okf_cite_check` / `okf_save_survey` / `okf_save_note` | Surveys and notes |
| `okf_bib` / `okf_export` / `okf_pack` / `okf_merge` | Export and migrate |
Cite only `papers/` / `claims/` ids returned by tools. Do not invent DOIs. Do not `okf_compare` an unscoped thousand-paper library.
## Development
```sh
pnpm install
pnpm run build
```
Restart `dsh web` and hard-refresh after client changes.
## License
[MIT](LICENSE) © 2026 1-CellBio