Babydunx1/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

The package declares dsh.bundle.patch, so DSH can install it like any other bundle.

# 1. Clone / copy the package somewhere permanent
git clone <your-repo-url> 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

Restart DeepSeek Harness. The plugin is applied from cordis.patch.yml.

Copy the insert row from cordis.patch.yml into ~/.dsh/profiles/<profile>/cordis.patch.yml and restart DSH.

Nothing to configure when your vault is in a standard location. Otherwise:

# 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"

…or set it explicitly in the patch: knowledgePaths: ["~/my-vault"].

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.bundle.patch ไว้แล้ว จึงติดตั้งเหมือน bundle อื่นของ DSH

# 1. โคลน / คัดลอกแพ็กเกจไปเก็บถาวร
git clone <your-repo-url> 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

รีสตาร์ท DeepSeek Harness — ปลั๊กอินจะถูก apply จาก cordis.patch.yml

คัดลอกแถว insert จาก cordis.patch.yml ไปวางใน ~/.dsh/profiles/<profile>/cordis.patch.yml แล้วรีสตาร์ท DSH

ถ้า vault อยู่ในตำแหน่งมาตรฐาน ไม่ต้องตั้งค่าอะไรเลย มิฉะนั้น:

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

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

…หรือระบุตรง ๆ ใน patch: knowledgePaths: ["~/my-vault"]

ตารางตั้งค่า (config)

ทุกคีย์เป็น optional ค่า default ด้านล่างคือสิ่งที่ใช้เมื่อติดตั้งแบบไม่ตั้งค่าอะไร

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

ถ้าหา vault ไม่เจอ ปลั๊กอินจะ log ว่า Initialized with 0 path(s) — ให้ดูบรรทัดนี้ก่อนเป็นอันดับแรกเมื่อไม่มีอะไรถูก index

รูปแบบ vault ที่รองรับ

A. แบบมีโครงสร้าง (vault หลายไฟล์สไตล์ Antigravity):

knowledge/
└── posttracker_engine/
    ├── metadata.json          # title, summary + tags / aliases / references (ไม่บังคับ)
    ├── timestamps.json        # ไม่บังคับ
    └── artifacts/
        ├── master_guide.md    # อ่านตัวนี้ก่อน: สารบัญ + สถานะล่าสุด
        ├── 01_watchdog.md
        └── 02_reconciliation.md

ฟิลด์ใน metadata.json เรียงตามน้ำหนักการค้น:

เนื้อในไฟล์ก็ถูกค้นด้วย (+1) เป็นทางเลือกสุดท้าย symbol ที่ปรากฏแค่ในไฟล์จึงหาเจอ แต่จะถูกจัดอันดับต่ำกว่าเสมอถ้า metadata match

B. markdown ธรรมดา — โฟลเดอร์อะไรก็ได้ที่มีไฟล์ .md / .txt:

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

ลำดับการอ่านที่แนะนำ (ประหยัด context): ดูสารบัญ item → master_guide.md → ไฟล์ NN_*.md ที่ตรงกับงานนั้น → แล้วค่อยไปดูซอร์สโค้ด

พฤติกรรมของ safety guard

• guard ตรวจ execution object ที่ DSH ส่งให้ tools.guard(): exec.name (ชื่อ tool) และ exec.arguments (อาร์กิวเมนต์ที่ parse แล้ว) — ไม่ใช่ exec.tool / exec.args เพราะสองตัวนั้นอ่านได้ undefined แล้ว guard จะไม่ทำงานแบบเงียบ ๆ
• ตรวจเฉพาะ bash, pwsh, cmd, terminal; tool อื่นคืน undefined และทำงานปกติ
• เมื่อถูกปฏิเสธจะคืนข้อความขึ้นต้นด้วย [BLOCKED BY DSH-KNOWLEDGE-BRIDGE SAFETY POLICY] และ runtime จะแสดงเป็น Error: ...
• guard เป็น monotonic: คำสั่งที่ถูกปฏิเสธแล้ว ปลั๊กอินอื่นบังคับให้ผ่านไม่ได้

การพัฒนาและทดสอบ

npm test           # 28 เทสต์: engine, host plugin, bundle contract
npm run validate   # 21 checks แบบ static บนสัญญาของ bundle
npm run demo       # index examples/vault แล้วแสดงสิ่งที่เอเจนต์จะเห็น
npm run demo -- ~/my-vault --query deployment   # หรือชี้ vault อื่นก็ได้

รันเฉพาะชุดที่ต้องการระหว่างพัฒนา:

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 # ตัว validator ต้องปฏิเสธ bundle ที่พัง

ไม่ต่อเน็ต ไม่เขียนไฟล์นอกโฟลเดอร์ temp และ ไม่ต้องติดตั้งอะไรเลย — CI รันคำสั่งเดียวกันบน Linux และ Windows กับ Node 20/22/24 ถ้ารันในเซสชัน DSH ที่มี sandbox โฟลเดอร์ temp ของระบบอาจเขียนไม่ได้ ให้ตั้ง TEMP/TMP ไปที่ที่เขียนได้ก่อน

index.js                       cordis host plugin: inject, tools, guard, prompt sections
lib/knowledge.js               engine ล้วน: discovery, index, search, read, โหลดไฟล์กฎ
cordis.patch.yml               แถว patch ของ bundle ที่ DSH นำไปใช้
locale/{en,th}.json            ชื่อและคำอธิบายที่แสดงใน Plugin Manager
assets/{banner,logo}.svg       ภาพประกอบของรีโป
scripts/demo.mjs               เดโมไม่ต้องติดตั้ง (npm run demo)
scripts/validate-bundle.js     21 checks ของสัญญา bundle (npm run validate)
scripts/validate-bundle.test.js พิสูจน์ว่า validator ปฏิเสธ bundle ที่พังจริง
examples/vault/                vault ตัวอย่างทั้ง 2 รูปแบบที่รองรับ
lib/*.test.js                  ชุดเทสต์ node:test
.github/workflows/ci.yml       test matrix (ไม่มีขั้นตอนติดตั้ง)
CHANGELOG.md                   ประวัติเวอร์ชัน
CONTRIBUTING.md                ข้อกำหนดที่ PR ต้องรักษา
SECURITY.md                    อะไรถือเป็นช่องโหว่ของปลั๊กอินนี้
CODE_OF_CONDUCT.md             Contributor Covenant 2.1

ประตูคุณภาพที่ทุกการแก้ต้องผ่าน:

แก้ปัญหาที่พบบ่อย

📄 License · สัญญาอนุญาต

MIT License — see LICENSE. Use it, fork it, ship it. สัญญาอนุญาต MIT — ดูไฟล์ LICENSE ใช้ แก้ไข และเผยแพร่ได้เลย