dsh-knowledge-bridge

Give your DeepSeek Harness agent a brain — host-level knowledge access, zero-config vault discovery, and a safety guard for destructive shell commands.

ต่อสมองให้เอเจนต์ DeepSeek Harness — เข้าถึงคลังความรู้ระดับ host, ค้นหา vault อัตโนมัติแบบไม่ต้องตั้งค่า, และกันคำสั่ง shell ที่ทำลายข้อมูล

English · ภาษาไทย

flowchart LR
    V[("Knowledge vault<br/>50 items · 229 files")]
    D["Discovery<br/>env var → ~ → ./"]
    I["Index<br/>id · title · summary · artifacts"]
    T["Tools<br/>search · read · list"]
    A["Agent context"]
    Q["One-line directive<br/>~140 chars"]
    G{"Safety guard<br/>exec.name + exec.arguments"}

    V --> D --> I --> T --> A
    Q --> A
    A --> G
    G -->|"banned pattern"| X["Denied ❌"]
    G -->|"clean"| R["Executed ✅"]

git clone https://github.com/Babydunx1/dsh-knowledge-bridge && cd dsh-knowledge-bridge
npm test          # 28 tests — unit + bundle contract, no install needed
npm run validate  # 21 static checks on the bundle contract
npm run demo      # index a sample vault and print what the agent would see

  2 · index
      2 item(s) · 3 artifact(s)
      ├─ deploy-guide  ·  1 artifact(s)
      └─ posttracker_engine  ·  2 artifact(s)

  4 · guard (patterns are matched against the command string)
      ⛔ BLOCKED  git reset --hard HEAD~1
      ⛔ BLOCKED  rm -rf /
      ✅ allowed  git status

🇬🇧 English

Why this exists

An agent's quality is bounded by what it can reach, not by how smart it is. Three concrete failure modes motivated this plugin:

1. Sandbox false negatives. Under workspace-write, an agent cannot read knowledge vaults or repositories outside the active workspace. On Windows the shell turns that denial into a misleading File Not Found, so the agent concludes the knowledge does not exist — and starts guessing.
2. Context amnesia. Teams keep 50+ architecture docs, SOPs and API contracts in a vault (Antigravity's ~/.gemini/antigravity-ide/knowledge, shared drives, docs/). DeepSeek Harness has no native way to discover or index them.
3. Irreversible commands. Autonomous agents happily run git reset --hard, git clean -fd or git restore . and destroy uncommitted work.

dsh-knowledge-bridge runs as a host-level cordis plugin: it reads the host filesystem with the host process's own permissions, exposes three fast retrieval tools, injects a one-line directive so the model knows a vault exists, and denies destructive shell calls before they execute.

Goals

What this plugin is not

• It is not a memory system that loads your whole vault into every prompt. A 2 MB vault is ~1M tokens: slow and expensive.
• It is not a vector database. Ranking is deterministic keyword scoring — predictable, debuggable, no embedding service to run.

Features

Installation

dsh plugin --profile <profile> add https://github.com/Babydunx1/dsh-knowledge-bridge

dsh plugin --profile <profile> update dsh-knowledge-bridge
# or: Plugins → uninstall → Add plugin again

# 1. Clone / copy the package somewhere permanent
git clone https://github.com/Babydunx1/dsh-knowledge-bridge dsh-knowledge-bridge

# 2. Register it in your profile
#    ~/.dsh/profiles/<profile>/package.json
{
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-knowledge-bridge"] } },
  "dependencies": { "dsh-knowledge-bridge": "link:/absolute/path/to/dsh-knowledge-bridge" }
}

# 3. Install the link
cd ~/.dsh/profiles/<profile>
pnpm install

# Windows (PowerShell) — semicolon or comma separated
$env:DSH_KNOWLEDGE_PATHS = "D:/team-docs/knowledge;~/my-vault"

# macOS / Linux
export DSH_KNOWLEDGE_PATHS="$HOME/my-vault:$HOME/team-docs"

Configuration reference

Every key is optional; the defaults below are what a zero-config install uses.

bannedPatterns: [
  'git\\s+reset\\s+--hard',
  'git\\s+clean\\s+-fd',
  'git\\s+restore\\s+\\.',
  'rm\\s+-rf\\s+/(?!tmp)',
]

If the vault cannot be found the plugin logs Initialized with 0 path(s) — check that line first when nothing is indexed.

Supported vault layouts

A. Structured items (Antigravity and similar multi-file vaults):

knowledge/
└── posttracker_engine/
    ├── metadata.json          # title, summary + optional tags / aliases / references
    ├── timestamps.json        # optional
    └── artifacts/
        ├── master_guide.md    # read first: table of contents + current status
        ├── 01_watchdog.md
        └── 02_reconciliation.md

metadata.json fields, in search-weight order:

The document bodies are searched too (+1) as a last resort, so a symbol that only appears inside a file is still findable — but a body hit always ranks below a metadata hit.

B. Plain markdown — any directory tree of .md / .txt files:

knowledge/
├── architecture.md
├── deploy-guide.md
└── deployment/
    └── README.md

Recommended read order, which keeps context small: item outline → master_guide.md → the one numbered artifact that matches the task → source code.

How the safety guard behaves

• The guard inspects the execution object DSH passes to tools.guard(): exec.name (tool name) and exec.arguments (parsed arguments). Not exec.tool / exec.args — reading those yields undefined and the guard silently never fires.
• It only inspects bash, pwsh, cmd, terminal; every other tool returns undefined and runs normally.
• A denial returns a reason beginning with [BLOCKED BY DSH-KNOWLEDGE-BRIDGE SAFETY POLICY], surfaced by the runtime as Error: ....
• The guard is monotonic: a denial cannot be overridden by another plugin.

Development

npm test           # 28 tests: engine, host plugin, bundle contract
npm run validate   # 21 static checks on the bundle contract
npm run demo       # index examples/vault and print the agent's view
npm run demo -- ~/my-vault --query deployment   # or any other vault

Narrower runs while iterating:

node --test lib/knowledge.test.js          # discovery, index, search, read
node --test lib/index.test.js              # tools, guard contract, prompt sections
node --test scripts/validate-bundle.test.js # the validator refuses broken bundles

No network, no writes outside a temp directory, and no install step — the CI matrix runs the same commands on Linux and Windows across Node 20/22/24. In a sandboxed DSH session the OS temp directory may be read-only; point TEMP/TMP at a writable directory first.

index.js                       cordis host plugin: inject, tools, guard, prompt sections
lib/knowledge.js               pure engine: discovery, index, search, read, rules loading
cordis.patch.yml               bundle patch row applied by DSH
locale/{en,th}.json            Plugin Manager display title and description
assets/{banner,logo}.svg       repo artwork
scripts/demo.mjs               zero-install demo (npm run demo)
scripts/validate-bundle.js     21 static bundle-contract checks (npm run validate)
scripts/validate-bundle.test.js  proves the validator refuses broken bundles
examples/vault/                sample vault in both supported layouts
lib/*.test.js                  node:test suites
.github/workflows/ci.yml       test matrix (no install step)
CHANGELOG.md                   release history
CONTRIBUTING.md                invariants a pull request must keep
SECURITY.md                    what counts as a vulnerability here
CODE_OF_CONDUCT.md             Contributor Covenant 2.1

Quality gates a change must pass:

Troubleshooting

🇹🇭 ภาษาไทย

ทำไมต้องมีปลั๊กอินนี้

คุณภาพของเอเจนต์ไม่ได้ขึ้นกับความฉลาดอย่างเดียว แต่ขึ้นกับว่า มันเอื้อมถึงอะไรได้ ปัญหาจริง 3 ข้อที่ทำให้เกิดปลั๊กอินนี้:

1. Sandbox หลอกว่า "ไม่พบไฟล์" — โหมด workspace-write อ่าน vault หรือ repo นอก workspace ไม่ได้ และบน Windows shell จะแปลง error เป็น File Not Found ทำให้เอเจนต์สรุปว่า "ความรู้ไม่มีอยู่" แล้วเริ่มเดาสุ่ม
2. ความจำขาดตอน — ทีมเก็บเอกสารสถาปัตยกรรม SOP และ API contract ไว้ 50+ ฉบับใน vault (เช่น ~/.gemini/antigravity-ide/knowledge, ไดรฟ์แชร์, docs/) แต่ DeepSeek Harness ไม่มีวิธีค้นหา/index ไฟล์พวกนี้
3. คำสั่งที่ย้อนกลับไม่ได้ — เอเจนต์อัตโนมัติเผลอรัน git reset --hard, git clean -fd, git restore . แล้วงานที่ยังไม่ commit หายหมด

dsh-knowledge-bridge ทำงานเป็น cordis plugin ระดับ host: อ่านไฟล์ด้วยสิทธิ์ของ process หลักของแอป เปิด tool ค้นหา 3 ตัว ฉีด directive บรรทัดเดียวให้โมเดลรู้ว่ามีคลังอยู่ และสกัดคำสั่ง shell ที่อันตรายก่อนจะถึงดิสก์

เป้าหมาย

สิ่งที่ปลั๊กอินนี้ ไม่ใช่

• ไม่ใช่ ระบบที่โหลด vault ทั้งก้อนเข้า prompt ทุกครั้ง — vault 2 MB ≈ 1 ล้านโทเคน ช้าและแพง
• ไม่ใช่ vector database — การจัดอันดับใช้ keyword scoring แบบ deterministic ทำนายผลได้ debug ง่าย ไม่ต้องรัน embedding service

ฟีเจอร์

การติดตั้ง

dsh plugin --profile <profile> add https://github.com/Babydunx1/dsh-knowledge-bridge

dsh plugin --profile <profile> update dsh-knowledge-bridge
# หรือ: Plugins → ถอน (uninstall) → Add plugin ใหม่

# 1. โคลน / คัดลอกแพ็กเกจไปเก็บถาวร
git clone https://github.com/Babydunx1/dsh-knowledge-bridge dsh-knowledge-bridge

# 2. ลงทะเบียนใน profile ของคุณ
#    ~/.dsh/profiles/<profile>/package.json
{
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-knowledge-bridge"] } },
  "dependencies": { "dsh-knowledge-bridge": "link:/absolute/path/to/dsh-knowledge-bridge" }
}

# 3. ติดตั้ง link
cd ~/.dsh/profiles/<profile>
pnpm install

# Windows (PowerShell) — คั่นด้วย ; หรือ ,
$env:DSH_KNOWLEDGE_PATHS = "D:/team-docs/knowledge;~/my-vault"

# macOS / Linux
export DSH_KNOWLEDGE_PATHS="$HOME/my-vault:$HOME/team-docs"