The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add DeepSeek Harness guide, hooks generator, and setup skill
phungthien26985dd488892c2
diff --git a/docs/DEEPSEEK-HARNESS-GUIDE.md b/docs/DEEPSEEK-HARNESS-GUIDE.mdnew file mode 100644index 000000000..8d62c15fb--- /dev/null+++ b/docs/DEEPSEEK-HARNESS-GUIDE.md@@ -0,0 +1,128 @@+# DeepSeek Harness Guide++ECC runs on the [DeepSeek Harness](https://github.com/deepseek-ai/dsh) (DSH) via its+native skill roots and the first-party Claude Code hooks bridge. This guide covers+what works out of the box, how to mount the ECC hooks, and the current limits.++Unlike the Qwen or Codex adapters, there is no dedicated installer target yet; the+setup is a small amount of manual configuration described below.++## Prerequisites++- DeepSeek Harness 0.2.0-rc.1 or newer (`dsh --version`).+- ECC repository cloned locally, for example `~/ECC` (the hooks bridge commands+ reference this path, so keep the checkout in place).+- Skills need no extra tooling; hooks use the `@deepseek-ai/dsh-hooks-claude-code`+ plugin that ships inside the DSH runtime itself.++## Skills (automatic)++DSH loads skills from these roots (earlier roots win on name conflicts):++```text+<project>/.dsh/skills+<project>/.agents/skills+custom dirs (~/.dsh/profiles/<profile>/cordis.patch.yml -> skill-filesystem)+~/.dsh/skills+~/.agents/skills+```++Because ECC already ships `.agents/skills/` for Codex, opening a session with the+ECC checkout as the working directory exposes a subset of ECC skills immediately.+To expose the full curated set in every project, link the catalog once:++```bash+ln -s /path/to/ECC/skills/<skill-name> ~/.dsh/skills/<skill-name>+```++DSH reads `SKILL.md` frontmatter (name/description), which matches the ECC skill+format, so no conversion is needed. Name conflicts with pre-existing user skills+are resolved by root priority; skip those skills when linking.++## Hooks++### How the bridge works++DSH bridges ECC command hooks through `@deepseek-ai/dsh-hooks-claude-code`+(first-party, bundled with the runtime). Constraints that shape the conversion:++- Supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`,+ `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`. ECC events without a+ bridge counterpart (`PreCompact`, `PostToolUseFailure`, `SessionEnd`) are+ skipped by the generator.+- DSH tool names are lower-case (`bash`, `edit`, `write`, `skill`, `task`),+ while ECC matchers use Claude Code names (`Bash`, `Edit|MultiEdit`, ...). The+ generator maps known tool names and keeps regex passthrough tokens.+- The bridge runs commands with `bash -c` and does not export the plugin root as+ an environment variable for hook processes. The generator prefixes each command+ with `CLAUDE_PLUGIN_ROOT=<ecc-root> ECC_PLUGIN_ROOT=<ecc-root>` (env-prefix+ form), which the ECC hook bootstrap reads at startup.+- `timeout` values are seconds in both formats and are preserved.++### Generate the config++```bash+node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json+```++The script validates nothing about your DSH install; it only converts+`hooks/hooks.json` into the bridge format and prints what it skipped.++### Mount into a profile++Add a bare insert entry to the profile patch layer+(`~/.dsh/profiles/<profile>/cordis.patch.yml`). This mirrors how the bundled web+app preset mounts its plugins:++```yaml+- insert:+ - id: ecc-hooks-claude-code+ name: "@deepseek-ai/dsh-hooks-claude-code"+ config:+ configPath: /absolute/path/to/hooks-dsh.json+```++Configuration notes from practice:++- A plain top-level entry (`- id: ...`) is silently dropped; the loader only+ treats `insert` entries as additions.+- `insert` under an existing non-group id is rejected ("not a group"); use a bare+ insert without a target id.+- The plugin package does not need to be added to the profile `package.json`;+ first-party plugins resolve from the DSH runtime install.+- Validate without booting: `cd ~/.dsh && dsh --profile <profile> --dump-config`+ (compose errors and dropped entries are reported on stderr).++### Verify++```bash+# Compose check (no session boot)+cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK++# End-to-end: fire a SessionStart hook in a one-shot headless session+# (uses a test config with a single marker-writing hook)+dsh --profile headless --patch /tmp/ecc-patch-test.yml 'Reply with exactly: BOOT-OK'+```++In a live web session, the GateGuard fact-forcing hook denies the first+edit/write/bash attempt until facts are presented — a visible signal that the+bridge is active.++## Updating++```bash+cd /path/to/ECC && git pull+node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json+```++Linked skills reflect the pull immediately (symlinks), only the hooks config+needs regeneration.++## Scope++| Surface | Status on DSH |+|---------|---------------|+| Skills (293) | Works; link or rely on `.agents/skills` |+| Hooks (20 command hooks, 4 of 7 events) | Works via the bridge; 3 events unsupported |+| Commands (94 slash commands) | Not available (Claude Code mechanism); workflows are covered by skills |+| Agents (68) | Not available as subagents; equivalent personas exist as skills |diff --git a/scripts/dsh/generate-hooks-config.js b/scripts/dsh/generate-hooks-config.jsnew file mode 100644index 000000000..f66b82570--- /dev/null+++ b/scripts/dsh/generate-hooks-config.js@@ -0,0 +1,154 @@+#!/usr/bin/env node+/**+ * Generate a DeepSeek Harness (DSH) hooks config from hooks/hooks.json.+ *+ * DSH bridges ECC command hooks through the first-party plugin+ * @deepseek-ai/dsh-hooks-claude-code. The bridge supports a subset of+ * Claude Code hook events and lower-cases tool names in matchers, so this+ * script converts the canonical ECC hooks.json into a DSH-compatible file.+ *+ * Usage:+ * node scripts/dsh/generate-hooks-config.js [--ecc-root <dir>] [--out <file>]+ *+ * Defaults:+ * --ecc-root directory of this checkout (repo root)+ * --out <ecc-root>/hooks/hooks.dsh.json+ *+ * The output is a Claude Code hooks-format file consumed by the bridge:+ * { "hooks": { "PreToolUse": [ { "matcher": "...", "hooks": [...] } ] } }+ *+ * Unsupported ECC events (no DSH bridge counterpart) are skipped and+ * reported on stderr: PreCompact, PostToolUseFailure, SessionEnd.+ */+'use strict';++const fs = require('fs');+const path = require('path');++const SUPPORTED_EVENTS = new Set([+ 'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop',+ 'SubagentStart', 'SubagentStop',+]);++// Claude Code tool names -> DSH lower-case tool names used by the bridge.+const TOOL_NAME_MAP = {+ Bash: 'bash',+ PowerShell: 'powershell',+ Write: 'write',+ Edit: 'edit',+ MultiEdit: 'edit',+ Skill: 'skill',+ Task: 'task',+};++function parseArgs(argv) {+ const opts = { eccRoot: null, out: null };+ for (let i = 2; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--ecc-root') opts.eccRoot = argv[++i];+ else if (a === '--out') opts.out = argv[++i];+ else {+ process.stderr.write('Unknown argument: ' + a + '\n');+ process.exit(2);+ }+ }+ return opts;+}++/**+ * Map a Claude Code matcher expression to DSH tool-name tokens.+ * Split on |, map known tool names to lower-case DSH names, keep regex+ * passthrough tokens (like .* or ^mcp__) untouched, de-duplicate.+ */+function mapMatcher(matcher) {+ if (typeof matcher !== 'string' || matcher.length === 0) return matcher;+ const parts = matcher.split('|').map(function (t) {+ const v = t.trim();+ if (v === '' || v === '.*' || v === '^mcp__') return v;+ const mapped = TOOL_NAME_MAP[v];+ return mapped !== undefined ? mapped : v.toLowerCase();+ });+ return Array.from(new Set(parts)).join('|');+}++/**+ * Rewrite an ECC command into a DSH bridge command.+ *+ * The bridge runs commands with bash -c but does not export the plugin+ * root as an environment variable for every hook process. Each ECC hook+ * command embeds a resolver (`node -e "..." <hook-id> <script> [args]`)+ * that resolves scripts/hooks/plugin-hook-bootstrap.js from the+ * CLAUDE_PLUGIN_ROOT environment variable, so prefixing the variables+ * inline (env-prefix form) is the only required change.+ */+function mapCommand(command, eccRoot) {+ const prefix = 'CLAUDE_PLUGIN_ROOT=' + JSON.stringify(eccRoot) ++ ' ECC_PLUGIN_ROOT=' + JSON.stringify(eccRoot) + ' ';+ return prefix + command;+}++/**+ * Convert the ECC hooks document into the DSH bridge format.+ * Returns { config, report } where report lists skipped events/entries.+ */+function generateConfig(eccRoot, sourceDoc) {+ const out = { hooks: {} };+ const report = [];+ for (const entry of Object.entries(sourceDoc.hooks || {})) {+ const event = entry[0];+ const groups = entry[1];+ if (!SUPPORTED_EVENTS.has(event)) {+ report.push('skip event ' + event + ' (not bridged by DSH)');+ continue;+ }+ const outGroups = [];+ for (const group of groups) {+ const hooks = [];+ for (const h of group.hooks || []) {+ if (h.type !== 'command' || typeof h.command !== 'string') {+ report.push('skip non-command hook on ' + event);+ continue;+ }+ const mapped = { type: 'command', command: mapCommand(h.command, eccRoot) };+ if (typeof h.timeout === 'number') mapped.timeout = h.timeout;+ hooks.push(mapped);+ report.push('ok ' + event);+ }+ if (hooks.length) {+ outGroups.push({ matcher: mapMatcher(group.matcher), hooks: hooks });+ }+ }+ if (outGroups.length) out.hooks[event] = outGroups;+ }+ return { config: out, report: report };+}++function main() {+ const opts = parseArgs(process.argv);+ const eccRoot = path.resolve(opts.eccRoot || path.join(__dirname, '..', '..'));+ const sourcePath = path.join(eccRoot, 'hooks', 'hooks.json');+ if (!fs.existsSync(sourcePath)) {+ process.stderr.write('ECC hooks.json not found at ' + sourcePath + '\n');+ process.exit(1);+ }+ let doc;+ try {+ doc = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));+ } catch (err) {+ process.stderr.write('Failed to parse ' + sourcePath + ': ' + err.message + '\n');+ process.exit(1);+ }+ const result = generateConfig(eccRoot, doc);+ const outPath = opts.out || path.join(eccRoot, 'hooks', 'hooks.dsh.json');+ fs.mkdirSync(path.dirname(outPath), { recursive: true });+ fs.writeFileSync(outPath, JSON.stringify(result.config, null, 2) + '\n');+ const okCount = result.report.filter(function (r) { return r.indexOf('ok ') === 0; }).length;+ const notes = result.report.filter(function (r) { return r.indexOf('ok ') !== 0; });+ process.stderr.write('wrote ' + outPath + '\n');+ process.stderr.write('hook commands: ' + okCount + '\n');+ if (notes.length) process.stderr.write(notes.join('; ') + '\n');+}++module.exports = { generateConfig, mapMatcher, mapCommand, SUPPORTED_EVENTS, TOOL_NAME_MAP };++if (require.main === module) main();diff --git a/skills/deepseek-harness-setup/SKILL.md b/skills/deepseek-harness-setup/SKILL.mdnew file mode 100644index 000000000..fd1b41d32--- /dev/null+++ b/skills/deepseek-harness-setup/SKILL.md@@ -0,0 +1,79 @@+---+name: deepseek-harness-setup+description: "Install and operate Everything Claude Code (ECC) on the DeepSeek Harness (DSH): native skill roots (~/.dsh/skills, .agents/skills), the @deepseek-ai/dsh-hooks-claude-code bridge for command hooks, bare-insert patch mounting, generator usage, event-support limits, and update workflow. Use when setting up ECC on DeepSeek Harness, wiring ECC hooks into a DSH profile, or debugging why ECC skills or hooks do not appear in a DSH session."+metadata:+ origin: community+---++# DeepSeek Harness Setup++Run ECC on the DeepSeek Harness. Full guide: `docs/DEEPSEEK-HARNESS-GUIDE.md`.++## When to Use++- Installing ECC skills or hooks on a DeepSeek Harness install.+- Deciding which ECC surfaces work on DSH and which do not.+- Debugging a DSH session that does not show ECC skills or does not fire ECC hooks.++## How It Works++1. **Skills need no conversion.** DSH reads `SKILL.md` frontmatter+ (name/description) from native skill roots. Link the ECC catalog once:++ ```bash+ ln -s /path/to/ECC/skills/<skill-name> ~/.dsh/skills/<skill-name>+ ```++ Root priority (project `.dsh` and `.agents` roots beat `~/.dsh`): skip+ linking skills whose names already exist in a higher-priority root.++2. **Hooks go through the first-party bridge.** Generate a DSH-format config+ from the canonical ECC hooks file:++ ```bash+ node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json+ ```++ The generator lower-cases tool-name matchers, prefixes+ `CLAUDE_PLUGIN_ROOT`/`ECC_PLUGIN_ROOT` inline (the bridge does not export+ the plugin root), preserves timeouts, and skips events DSH cannot bridge:+ `PreCompact`, `PostToolUseFailure`, `SessionEnd`.++3. **Mount with a bare insert** in `~/.dsh/profiles/<profile>/cordis.patch.yml`:++ ```yaml+ - insert:+ - id: ecc-hooks-claude-code+ name: "@deepseek-ai/dsh-hooks-claude-code"+ config:+ configPath: /absolute/path/to/hooks-dsh.json+ ```++ Loader rules that cost debugging time when learned the hard way:+ a plain `- id:` top-level entry is silently dropped; `insert` under an+ existing non-group id is rejected as "not a group"; first-party plugin+ packages need no profile `package.json` entry.++4. **Validate by composing, then verify live.**++ ```bash+ cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK+ ```++ A live GateGuard denial on the session's first edit/write/bash is the+ visible signal the bridge is active.++## Updating++`git pull` reflects into linked skills immediately; regenerate the hooks+config with the same generator command. If the ECC checkout moves, regenerate+(the path is embedded in every hook command) and relink skills.++## Limits++| Surface | Status on DSH |+|---------|---------------|+| Skills | Full catalog works |+| Hooks | 20 command hooks on 4 of 7 bridge events |+| Slash commands | Not available (Claude Code mechanism); workflows covered by skills |+| Agents | Not available as subagents; equivalent personas exist as skills |diff --git a/tests/scripts/dsh-generate-hooks-config.test.js b/tests/scripts/dsh-generate-hooks-config.test.jsnew file mode 100644index 000000000..ebdd80253--- /dev/null+++ b/tests/scripts/dsh-generate-hooks-config.test.js@@ -0,0 +1,104 @@+/**+ * Tests for scripts/dsh/generate-hooks-config.js+ *+ * Run with: node tests/scripts/dsh-generate-hooks-config.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');+const { spawnSync } = require('child_process');++const gen = require('../../scripts/dsh/generate-hooks-config');++function test(name, fn) {+ try {+ fn();+ console.log(' \u2713 ' + name);+ return true;+ } catch (err) {+ console.log(' \u2717 ' + name);+ console.log(' Error: ' + err.message);+ return false;+ }+}++function runTests() {+ let passed = 0;+ let failed = 0;++ if (test('mapMatcher maps Claude tool names to DSH lower-case names', () => {+ assert.strictEqual(gen.mapMatcher('Bash'), 'bash');+ assert.strictEqual(gen.mapMatcher('Edit|MultiEdit'), 'edit');+ assert.strictEqual(gen.mapMatcher('Write|Edit|MultiEdit'), 'write|edit');+ })) passed++; else failed++;++ if (test('mapMatcher keeps regex passthrough tokens untouched', () => {+ assert.strictEqual(gen.mapMatcher('.*'), '.*');+ assert.strictEqual(gen.mapMatcher('^mcp__'), '^mcp__');+ assert.strictEqual(gen.mapMatcher('.*|Task'), '.*|task');+ })) passed++; else failed++;++ if (test('mapCommand prefixes plugin-root env vars and keeps the resolver intact', () => {+ const cmd = 'node -e "resolver" pretooluse:bash:check-console-log scripts/hooks/check-console-log.js standard';+ const out = gen.mapCommand(cmd, '/ecc');+ assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" ' + cmd);+ })) passed++; else failed++;++ if (test('mapCommand passes through non-resolver commands with prefix only', () => {+ const out = gen.mapCommand('echo hi', '/ecc');+ assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" echo hi');+ })) passed++; else failed++;++ if (test('generateConfig skips unsupported events and reports them', () => {+ const doc = { hooks: {+ PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'node -e "x" node scripts/hooks/a.js' }] }],+ PreCompact: [{ matcher: '.*', hooks: [{ type: 'command', command: 'echo hi' }] }],+ SessionEnd: [{ matcher: '.*', hooks: [{ type: 'command', command: 'echo hi' }] }],+ } };+ const { config, report } = gen.generateConfig('/ecc', doc);+ assert.deepStrictEqual(Object.keys(config.hooks), ['PreToolUse']);+ assert.ok(report.some(r => r.includes('PreCompact')));+ assert.ok(report.some(r => r.includes('SessionEnd')));+ })) passed++; else failed++;++ if (test('generateConfig preserves timeout and maps matcher groups', () => {+ const doc = { hooks: {+ PostToolUse: [{ matcher: 'Edit|MultiEdit|Write', hooks: [+ { type: 'command', command: 'node -e "x" node scripts/hooks/b.js', timeout: 30 },+ ] }],+ } };+ const { config } = gen.generateConfig('/ecc', doc);+ const g = config.hooks.PostToolUse[0];+ assert.strictEqual(g.matcher, 'edit|write');+ assert.strictEqual(g.hooks[0].timeout, 30);+ })) passed++; else failed++;++ if (test('generateConfig supports the bridge-only Subagent events', () => {+ assert.ok(gen.SUPPORTED_EVENTS.has('SubagentStart'));+ assert.ok(gen.SUPPORTED_EVENTS.has('SubagentStop'));+ })) passed++; else failed++;++ if (test('CLI end-to-end writes valid JSON to --out', () => {+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-dsh-'));+ const outPath = path.join(tmp, 'hooks.dsh.json');+ const repoRoot = path.resolve(__dirname, '..', '..');+ const res = spawnSync('node', [+ path.join(repoRoot, 'scripts', 'dsh', 'generate-hooks-config.js'),+ '--ecc-root', repoRoot, '--out', outPath,+ ], { encoding: 'utf8' });+ assert.strictEqual(res.status, 0, 'CLI exit 0, stderr: ' + res.stderr);+ const doc = JSON.parse(fs.readFileSync(outPath, 'utf8'));+ assert.ok(doc.hooks.PreToolUse.length > 0, 'PreToolUse groups present');+ assert.ok(Object.keys(doc.hooks).includes('SessionStart'));+ assert.ok(!Object.keys(doc.hooks).includes('PreCompact'), 'unsupported event excluded');+ fs.rmSync(tmp, { recursive: true, force: true });+ })) passed++; else failed++;++ console.log('');+ console.log('Passed: ' + passed + ', Failed: ' + failed);+ return failed === 0;+}++process.exit(runTests() ? 0 : 1);