dsh-native-playbook

dsh-native-playbook

Unlock the DeepSeek Harness you already installed.

Use what DeepSeek Harness already ships before building more.

dsh-native-playbook is a community plugin for
DeepSeek Harness, not a separate agent
runtime. It adds one native_capability tool that routes a task to official DSH tools,
checks whether the complete capability is operational, and safely activates a reviewed
native path when possible.

简体中文

Quick start

Install the prebuilt GitHub package into your DSH profile:

dsh plugin --profile web add github:cyanseek/dsh-native-playbook

That's it. Use DSH normally. Ask for the outcome, not the package:

Run the test suite in the background and tell me when it finishes.
Find every reference to this symbol.
Search previous sessions for the deployment decision.

There is no repository clone, local build, build approval, account, project API key,
project config file, daemon, second install, or manual verification step in this path. The
npm package name is reserved for a later release; until then, the GitHub command above is
the supported install route.

What changes for common tasks

Task	Preferred native path	Behavior
Long-running command	bash(run_in_background=true) → job_output	Ready on supported Unix-like profiles; use pwsh on Windows.
Symbol navigation	lsp	Uses LSP only with a working provider; otherwise falls back to grep and glob.
Prior-session search	session_search	Uses the official workspace-authorized query tools. A reviewed first-use activation is available on tested DSH versions and reports when a DSH restart is required.
Delegated investigation	subagent → list_agents / send_message	Uses DSH's built-in child-agent lifecycle.
Fixed multi-step work	workflow	Prefers the deterministic native workflow engine over shell orchestration.

The plugin never treats “a package exists” or “a tool name is visible” as proof that a
capability works.

Readiness you can trust

Every recommendation separates five lifecycle facts:

Fact	Question answered
shipped	Does the tested DSH catalog include it?
mounted	Is its tool or service in the effective profile?
visible	Can the calling Agent currently see it?
providerReady	Are provider prerequisites actually satisfied?
operational	Can the Agent use it now?

The summary state is one of ready, platform-dependent, opt-in,
requires-provider, disabled, or unsupported. Conditional changes also report their
effect as immediate, next-turn, new-session, or restart.

Safe activation

Activation is deliberately narrow:

• Only reviewed recipes shipped in this repository can change a profile.
• The active DSH version must pass an explicit compatibility gate.
• Credentials, security policy, network providers, and arbitrary commands are outside the
  activation surface.
• Every change is checked against DSH and is reversible; failed verification leaves the
  original profile in place.
• Deactivation restores the exact saved content and refuses to overwrite later user edits.

The first Tier-1 recipe enables DSH's official, workspace-authorized session full-text
search with a lazy local index. DSH 0.1.0-rc.6 is the currently verified activation
target. Static lookup remains useful on other versions, while mutation is withheld.

Agent Skill

The same native-first guidance is available as an Agent Skill:

npx skills@latest add cyanseek/dsh-native-playbook \
  --skill dsh-native-playbook \
  --agent codex \
  --yes

The Skill is focused and loads only the reference needed for the current task.

CLI

The CLI is an advanced inspection and automation surface. Every command supports stable
JSON output where shown:

dsh-native lookup "<task>" [--profile <name>] [--json]
dsh-native status --profile <name> [--json]
dsh-native list [--profile <name>] [--json]
dsh-native explain <capability> [--profile <name>] [--json]
dsh-native doctor [--json]
dsh-native install --target project|dsh [--json]
dsh-native plan <capability> --profile <name> [--json]
dsh-native activate <capability> --profile <name> [--json]
dsh-native deactivate <capability> --profile <name> [--json]
dsh-native verify <capability> --profile <name> [--json]

Examples from a development checkout:

pnpm dsh-native lookup "find all symbol references" --json
pnpm dsh-native status --profile web --json
pnpm dsh-native plan session_search --profile web --json

Node API

import {
  inspectDshProfile,
  lookupNativeCapability,
  planNativeActivation,
} from 'dsh-native-playbook'

const profile = await inspectDshProfile({ profile: 'web' })
const result = await lookupNativeCapability('run a long test in background', { profile })
const plan = await planNativeActivation('session_search', { profile: 'web' })

The public API also exports listNativeCapabilities, explainNativeCapability,
activateNativeCapability, deactivateNativeCapability, and
verifyNativeCapability. Public API functions never prompt.

Compatibility and privacy

• Requires Node.js 22 or 24 and DeepSeek Harness.
• Capability facts are pinned to an official DSH source revision.
• Static lookup works without DSH; live readiness needs an existing DSH profile.
• No telemetry is collected.
• No API accesses credential stores or private session contents.
• This project is a community extension and is not affiliated with or endorsed by
  DeepSeek.

Remove

dsh plugin --profile web remove dsh-native-playbook

Development

corepack enable
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm validate:skill
pnpm validate:plugin
pnpm validate:dsh-plugin
pnpm verify:upstream
pnpm smoke:json
pnpm smoke:consumer
pnpm metrics

CI runs the gates on Linux, macOS, and Windows with Node.js 22 and 24, plus a clean GitHub
consumer-install check.

See CONTRIBUTING.md, SECURITY.md, and
CHANGELOG.md.

License

MIT