metavibe-dsh 🚀

Language: English | 中文

MetaVibe as a native DeepSeek Harness plugin — a read-only architecture advisor for Vibe Coding. The original Python CLI engine is retired; this package is the single implementation: TypeScript sources + Cordis plugin + defineTool model tools, built with the exact pipeline the official packages use (tsc → lib/types/, tsdown → lib/index.js).

🧭 What it is (and what it is not)

MetaVibe advises — it never reaches into the project being worked on.

• ✅ Architecture map (metavibe_hub_list): the built-in golden meta-architectures (layers / slots / guardrails) to pick a top-level design direction.
• ✅ Best-practices catalog (metavibe_catalog_tree / metavibe_catalog_inspect): the knowledge matrix (data flows, data models, philosophies, meta-skills) with golden examples and agent instructions.
• ❌ No workspace scanning, no file writes, no spec binding, no code generation, no guardrail enforcement inside the target project.

Because every tool is pure and read-only, the plugin needs no fs service, cannot stall the agent loop with workspace sweeps, and never interferes with the project it is advising.

🛠️ Tools (4 model tools)

| Tool | Purpose | | :--- | :--- | | metavibe_blueprint | Flow-first advisory: classify the required information flows (write / read / event / integration / realtime / task), match the golden architecture(s), and compose a blueprint (layers / slots / guardrails) with alternatives and gap suggestions | | metavibe_hub_list | List the golden architecture map: name, source, version, description, flows, layers and slots per preset | | metavibe_catalog_tree | Browse the knowledge matrix by category (data flows / data models / philosophies / meta-skills) | | metavibe_catalog_inspect | Inspect one catalog entry in depth: summary, data-flow diagram, schemas, golden examples, agent instructions |

Advisory method (flow-first): information-flow paths are the primary lens — metavibe_blueprint first recognizes the flows a system needs, then maps them onto common paradigms, then synthesizes an architecture blueprint. The hub's golden architectures each declare the flows they realize, so flow → architecture matching is grounded in the knowledge base.

🎯 Triggers & Usage Scenarios

How these tools get triggered inside a DeepSeek Harness session: the agent maps a user request to a concrete tool call. All tools are read-only and never touch the workspace.

| When the user says… | The agent calls | | :--- | :--- | | “What architecture should I use for a clean-arch web API?” / “帮我选个后端架构” | metavibe_hub_list | | “How do I structure CQRS / DTOs / an auth factory?” | metavibe_catalog_tree → metavibe_catalog_inspect | | “Give me the golden patterns for payments / Next.js / FastAPI” | metavibe_hub_list (pick the preset) → metavibe_catalog_inspect (best practice details) |

Scenario — choose a top-level architecture direction

1. metavibe_hub_list — the agent inventories the golden architecture map.
2. The agent (and the user) pick the preset that fits the project, and the agent proposes the layer/one-way-dependency plan from the spec.
3. The agent drafts the project structure following the spec — the plugin only guides, it never writes files.

Scenario — look up a best practice while coding

1. metavibe_catalog_tree — overview of the knowledge matrix.
2. metavibe_catalog_inspect { "id": "data_flows/cqrs_flow" } — data-flow diagram, schemas, golden example code, agent instructions.
3. The agent applies the pattern in the code it is writing.

📁 Structure

metavibe-dsh/
├── package.json          # ESM package metadata (name: metavibe-dsh, main: lib/index.js)
├── tsconfig.json         # mirrors official base: es2024 / bundler / .ts imports → .js on emit
├── tsdown.config.ts      # same shape as official: entry lib/types/index.js → lib/index.js
├── cordis.yml.example    # mounting example (copy into an agent preset)
├── scripts/
│   ├── install.sh            # one-command installer (explicit dsh.bundle profile-layer plugin)
│   ├── assemble-dynamic.mjs  # assemble the session demo Package 1:1 from compiled output
│   └── gen-data.mjs          # regenerate src/data/hub.ts from skeletons/*.json
├── skeletons/            # golden meta-architecture sources (.json spec + .md design doc)
├── src/                  # TypeScript sources (every file < 300 lines)
│   ├── index.ts          # Cordis plugin entry (name/inject/Config/apply)
│   ├── engine.ts         # read-only engine (Hub map + Catalog matrix)
│   ├── specs.ts          # Spec types & parsing (lossless JSON: absent fields omitted)
│   ├── tools/            # grouped tool registration (hub / catalog / blueprint / helpers / index)
│   ├── data/             # embedded Hub / Catalog data (.ts)
│   └── types/dsh.d.ts    # ambient types for the cordis / dsh-tools runtime contract
├── tests/                # vitest suite (engine + tools, 13 cases)
├── examples/             # historical before/after effect-comparison projects (pre-0.3)
├── docs/                 # effect-comparison documentation (historical, pre-0.3)
└── lib/                  # build output (tsc → lib/types/, tsdown → lib/index.js)

All modules honor MetaVibe's own anti-entropy rules (single files < 300 lines). engine.ts + specs.ts are dependency-free pure logic (no I/O at all) and unit-testable standalone; tools/* only wires the contract.

🔨 Build

pnpm install       # devDeps: typescript / tsdown / @types/node / schemastery
pnpm test          # vitest
pnpm run typecheck # tsc --noEmit
pnpm run build     # tsc → lib/types/ + tsdown → lib/index.js

@deepseek-ai/dsh-tools / @deepseek-ai/cordis are peerDependencies supplied by the host deployment. The npm-registry versions of these packages are older than the runtime API, so they are NOT installed for type checking; src/types/dsh.d.ts declares the exact contract the plugin consumes.

📦 Install & Mount

Recommended — explicit profile-layer plugin. The package declares dsh.bundle (see package.json), so installing it with the one-command installer makes it a first-class plugin of the profile: dsh plugin add installs the package and automatically appends it to the profile's dsh.profile.bundles layer list. The plugin loads with the profile and the tools are available in every session — no manual patch editing, no agent preset to pick:

cd metavibe-dsh
bash scripts/install.sh                # web profile (default)
bash scripts/install.sh --profile tui  # a different profile

After installing, restart dsh web; metavibe_hub_list / metavibe_catalog_tree / metavibe_catalog_inspect appear in all sessions.

Per-session alternative (agent preset): if you only want the tools in one preset, copy the row from cordis.yml.example into that preset's agent.cordis.yml instead. No config needed.

🚀 Publishing to the DSH plugin ecosystem (npm publish → dsh plugin add metavibe-dsh → mount) → see PUBLISHING.md.

↔️ History

• 0.4.0 — flow-first advisory: added metavibe_blueprint (classify information flows → match golden architectures → compose blueprint), a flows dimension on every hub architecture, and six data-flow primitives in the catalog.
• 0.3.0 — scoped to a read-only architecture advisor: metavibe_check / metavibe_hub_use / metavibe_assemble / metavibe_inject / metavibe_extract_* were removed (they scanned, wrote to, or generated code in the target workspace). The plugin now consumes only the tools registry — no fs service, no config, no sandbox writes.
• ≤ 0.2.x — the anti-entropy suite (guardrail check, spec binding, rule injection, slot assembly, extraction). See docs/effect-comparison.md for the historical before/after record.