deepseek-harness-forge-plugins

Readme

# ⚒️ Forge Plugins for DeepSeek Harness

> **Everything is a Plugin.** — Bring the **Forge (铸剑炉)** arsenal into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tools](https://img.shields.io/badge/tools-12-green.svg)](#-plugins--tools)
[![Plugins](https://img.shields.io/badge/plugins-4-green.svg)](#-plugins--tools)
[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#)
[![dsh](https://img.shields.io/badge/DeepSeek%20Harness-ready-purple.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![OS](https://img.shields.io/badge/Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](#-build-gates-from-source)

**13 production-grade tools · 4 plugins · zero npm dependencies · pure Cordis** — the fastest way to give your DeepSeek Harness agent a *real* compute brain: symbolic math, formal logic, theorem proving, regex verification, model checking, code repair, TCM diagnosis, and memory recall.

---

## ✨ Why Forge Plugins?

| | |
|---|---|
| 🧮 **Real computation** | Symbolic math and logic that never hallucinate — every tool runs a compiled gate binary and returns **verified** results |
| 🧠 **Formal reasoning** | TPTP first-order theorem proving (EPROVER) + state-machine model checking, not just text generation |
| 🀄 **TCM diagnosis** | Unique 八极八势 (Eight Trigrams) pattern diagnosis and herb-pair retrieval across an ancient-formula corpus — **the only TCM plugin for DeepSeek Harness** |
| 🪶 **Zero deps** | Pure Cordis plugins, no npm install, no framework bootstrap code — drop-in and go |
| 🔒 **Sandboxed** | All file access goes through `ctx.fs` (host-plane discipline) — no bare `fs` calls |
| 🎁 **Prebuilt binaries** | Windows `.exe` included in [Releases](https://github.com/jinguanghai/deepseek-harness-forge-plugins/releases/latest) — Linux/macOS build from `src/go` in one command |

---

## 🔌 Plugins and Tools

| Plugin | Tool | What it does | Example result |
|---|---|---|---|
| **forge-gates** | `forge_math` | Symbolic simplification / evaluation | `3*(x+1)-3*x` → **`3`** |
| | `forge_logic` | Formal proof / equivalence check | `x>0 and x<10 -> x>0` → **proved** |
| | `forge_regex` | Fullmatch regex validation | `[A-Z]\d{3}` vs `B456` → **pass** |
| | `forge_eprover` | TPTP first-order theorem proving | CNF axioms → **theorem / counter-sat** |
| | `forge_system` | State-machine model checking (deadlock/invariant) | 6 states → **passed** |
| | `forge_repair` | Code defect fix suggestions | bare `except:` → **`except Exception:`** |
| **forge-tcm** | `tcm_diagnose` | 八极八势 TCM pattern diagnosis | text/vector → trigram + strategy |
| | `tcm_herb_pair` | Herb-pair co-occurrence retrieval | 附子+干姜 → 916 formulas |
| **forge-memory** | `memory_recall` | BM25 experience recall | query → ranked snippets |
| | `memory_fold_list` | Folded-memory index (π/φ) | list folded sections |
| | `memory_fold_preview` | Preview a folded section | content preview |
| | `memory_fold_deep` | Deep-read a folded section | full content |
| **evidence-first** | `evidence_audit` | Evidence audit: warns when a "done/success/fixed" claim has no tool-execution evidence | "任务完成" with no tool call → ⚠️ warning |

**13 tools · 4 plugins · MIT · works with dsh ≥ 0.1.0-rc.5**

---

## 🚀 Quick Start

```bash
# 1. Put this repo anywhere, e.g.:
#    ~/.dsh/.agent-presets/forge-plus/   (repo root = preset dir)

# 2. Register plugins in your agent preset (see examples/agent.cordis.yml.snippet)

# 3. Start DeepSeek Harness:
npx @deepseek-ai/dsh web
```

`agent.cordis.yml` snippet:

```yaml
# inside your preset directory
plugins:
  - path: ./plugins/forge-gates
  - path: ./plugins/forge-tcm
  - path: ./plugins/forge-memory
  - path: ./plugins/evidence-first
```

Then just ask your agent:

> *"Simplify 3*(x+1)-3*x"* → `3` ✅
> *"Prove that x>0 follows from x>0 and x<10"* → `proved` ✅
> *"Check regex [A-Z]\d{3} against B456 and order B456 ok"* → pass/fail ✅
> *"附子 配 干姜 有哪些方剂?"* → ranked formulas from your corpus ✅

---

## 🔧 Environment

| Variable | Default | Purpose |
|---|---|---|
| `FORGE_GATE_BIN` | `<repo>/bin/windows` | gate binary dir (Linux/macOS: `go build` from `src/go`, see below) |
| `FORGE_HOME` | `process.cwd()` | memory data dir (`memory.json` / `.forge-temp/memory_current.json` / `data/memory_current.json`) |
| `FORGE_DATA` | cwd / `data/` | TCM formula dir (must contain `formula_db.json`) |

## 🔨 Build Gates from Source (Linux / macOS / Windows)

```bash
cd src/go
for g in math logic regex eprover system repair tcm; do
  go build -o ${g}_gate${EXT} ${g}_gate.go
done   # Windows: set EXT=.exe
```

> 💡 Windows users: prebuilt `.exe` binaries are attached to the [v0.1.0 Release](https://github.com/jinguanghai/deepseek-harness-forge-plugins/releases/latest) — no build needed.

---

## 🏗️ Architecture

```
DeepSeek Harness (dsh) agent
        │  inject: ['tools']
        ▼
   ┌─ forge-plus preset ──────────────────┐
   │ forge-gates ── forge-memory ── forge-tcm │
   │        └──────┐         └────────┐      │
   │        subprocess               │      │
   │               ▼                 ▼      │
   │     ┌─ gate binaries ──┐  ┌─ data ─────┐│
   │     │ math / logic /   │  │ memory.json││
   │     │ regex / eprover /│  │ formula_db ││
   │     │ system / repair  │  │ (yours)    ││
   │     │ tcm              │  └────────────┘│
   │     └──────────────────┘                │
   └─────────────────────────────────────────┘
Gate protocol: tools invoke gate binaries, each writes ONE JSON object to stdout.
```

---

## 📊 Data Notes

- **forge-tcm** herb-pair retrieval requires **`formula_db.json`** — a private ancient-formula corpus (家传古籍数据) that is **NOT distributed with this repo**. Provide your own and point `FORGE_DATA` at it.
- **forge-memory** reads `memory.json` / `.forge-temp/memory_current.json` / `data/memory_current.json` — bring your own memory files (empty templates in `data/`).
- The gates themselves are pure logic (no private data baked in).

---

## 🎯 Project Lineage

Forge (铸剑炉) is a general-purpose digital agent: a multi-language compiler sandbox with **12 tool gates** (Python / Go / Node / Math / Logic / Regex / Knowledge / TCM / …), an LLM brain over a code body, and self-evolving architecture. This repo is its **dsh-native plugin family** — same gates, same discipline, now *Everything is a Plugin*.

- Main project: [github.com/jinguanghai/forge](https://github.com/jinguanghai/forge)
- DeepSeek Harness: [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)

## 📜 License

[MIT](LICENSE) © jinguanghai

## INSTALL

Three plugins are published as **Cordis bundles** -- install any of them into a dsh profile:

```bash
# 1 dsh CLI (local dir / tarball)
dsh plugin add ./plugins/forge-gates
# 2 pnpm (npm registry / local tarball)
pnpm add dsh-forge-gates
# 3 Manual: symlink/copy the plugin dir into your profile's node_modules,
#    then add the bundle entry to package.json's dsh.profile.bundles.
```

Prebuilt Windows `.exe` binaries ship inside each bundle (`bin/windows/`).
Latest bundle tarballs: https://github.com/jinguanghai/deepseek-harness-forge-plugins/releases/latest

> Linux/macOS: build the 7 gate binaries from `src/go/` in one command, see [BUILDING](BUILDING.md).