Guard42/dsh-humanize

dsh-humanize

Humanize Mode — humanfia flow philosophy × DeepSeek Harness
An agent preset that ports the "we build the flow around the agent" discipline
natively into DeepSeek Harness: refereed stages, hashed locks, review-first runs,
event-sourced resumability — and full customization into domain variants.

_{An independent community project, not affiliated with, endorsed by, or sponsored by DeepSeek or the humanfia team.
English · 中文}

dsh-humanize is an agent preset for DeepSeek Harness. Once installed, your coding agent works under the Humanize discipline:

We build the flow around the agent. Multi-stage objectives become explicit flows — stages with referee commands, locks with hashes, reviews before runs, events over impressions. "Lean accepts it, or it does not": a stage counts only when its verification command exits zero. "The review is the next prompt": an unreviewed lock never runs.

Core mechanisms at a glance:

• Flow kernel — multi-stage objectives become stage graphs; every stage carries referee commands whose exit code decides acceptance.
• Lock identity — canonicalization + SHA-256 → immutable flk_<digest> lock, re-verified on load against tampering.
• Review gate — HMAC-signed bindings; approved / rejected / bypassed are terminal and immutable; rejection reasons fold back into the draft.
• Resumable runs — append-only events.jsonl is the sole authority; flow_resume replays after any interruption ("a loop that stopped on Thursday carries on").
• Trace export — every run leaves evidence: Markdown timeline or Chrome-JSON importable at ui.perfetto.dev.
• Hash-anchored edits — literal replacement only after whole-file SHA-256 verification.

Acknowledgments & Inspiration

The direct inspiration and methodological contributions of this project come from the humanfia team and the humanize2 framework. Without these projects this preset would not exist:

• humanfia — the team behind the "we build the flow around the agent" philosophy
• humanfia/humanize2 — orchestrate, execute, and observe agent flows; the blueprint for this preset's flow lifecycle, lock identity, review gate and event replay
• humanfia/oh-my-humanize — workflow-native terminal coding agent; its hash-anchored edits and skill organization carry over here
• humanfia/humanize-plugin — the direct ancestor of this preset's tool surface (flow_suggest/check/lock/review/run as an MCP plugin)

Also thanks:

• DeepSeek Harness and DeepSeek AI — the upstream platform: model routing, sandbox, credential store, Web GUI and subagents all come from the host
• awesome-dsh-plugin — the community plugin directory

For a per-capability honest mapping (mechanism-level parity vs host equivalents vs explicit non-goals), see docs/parity.md.

Install

Option 1: one-line PowerShell (Windows)

Option 1: install as a dsh plugin (recommended)

This repository is also a DSH plugin bundle: a built-in installer bridge syncs the preset into the DSH preset root on startup. After upgrading the plugin and restarting DSH, files you have not modified are updated automatically (user-modified files are never overwritten).

dsh plugin --profile web add github:Guard42/dsh-humanize

Restart DSH and pick Humanize 模式 in the workspace preset selector. The installer-bridge design follows the precedent set by ChongCyrus/Vibe-Mathematics.

Option 2: one-line PowerShell (Windows)

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex(irm 'https://raw.githubusercontent.com/Guard42/dsh-humanize/main/tools/install.ps1')"

Option 3: one-line bash (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/Guard42/dsh-humanize/main/tools/install.sh | bash

Options 2–4 install the preset into %USERPROFILE%\.dsh\.agent-presets\humanize (i.e. ~/.dsh/.agent-presets/humanize) with a per-file SHA256 verification. Restart dsh web, then pick Humanize 模式 in the workspace preset selector.

Option 4: manual clone

git clone https://github.com/Guard42/dsh-humanize.git
cd dsh-humanize
powershell -NoProfile -ExecutionPolicy Bypass -File tools/install.ps1

Update & uninstall

• Update: rerun the same install command; it mirrors idempotently.
• Uninstall: delete ~/.dsh/.agent-presets/humanize and restart the deployment.

[!WARNING] Running dsh plugin add against a repository that merely contains preset files does NOT activate it — this repository can do it because it declares a dsh.bundle manifest and ships an installer bridge that syncs the preset into ~/.dsh/.agent-presets/humanize on startup. Pure presets without such a bridge still need a manual copy; see the pitfall documented by dsh-expert-mode.

If the installer reports ACCESS_DENIED: the destination is likely inside an antivirus/HIPS file-protection scope (observed with Huorong sysdiag: creations allowed, writes to existing files denied). Whitelist %USERPROFILE%\.dsh in your security product and rerun; restart the deployment before updating an installed preset so no process holds old files open.

Quick start

After selecting the Humanize preset, hand it a multi-stage task:

You: Migrate the test suite from Jest to Vitest; everything must be green afterwards.

Agent: I'll shape that objective as a flow —
  flow_draft    three stages: migrate config → replace suites → green-gate
  flow_check    structural validation, zero errors
  flow_lock     canonicalize + SHA-256 → flk_xxxxxxxx (immutable)
  flow_review_prepare  hands you a review.md to judge

You: approve (or give a rejection reason; the agent folds it back into the draft)

Agent: flow_run → subagents work the stages, referees check every exit code.
       Interrupted? No problem: flow_resume replays events.jsonl and
       completed stages never rerun.

Customize & specialize

This preset's most important property: it is not a frozen product but a base you can grow.

From inside DeepSeek Harness you can simply ask the model:

Help me add several XXXX tools to the humanize mode to strengthen its YYYY-domain capabilities, and save the result as a new agent preset named humanize-ZZZZ

Here is what actually happens behind that request:

1. Add tools — the agent creates a module under plugins/ and registers it via ctx.tools.register({...}) (JSON Schema parameters; implementation may depend only on node: builtins — zero-npm-dependency is a design red line). Shared services publish through ctx.provide('name', api) and register in the humanize group of agent.cordis.yml.

2. Add skills — domain methodology goes into skills/<name>/SKILL.md (frontmatter: name / description); the preset's own skill scanner picks it up automatically.

3. Tune the persona — rewrite the behavioral charter text in the composition file for your domain.

4. Save as a new preset — one command installs the current customization side by side with the stock preset:

   powershell -NoProfile -ExecutionPolicy Bypass -File tools\install.ps1 -PresetName humanize-ZZZZ
   

   PRESET_NAME=humanize-ZZZZ bash tools/install.sh
   

5. Use it — after a restart the preset selector lists both「Humanize 模式」and humanize-ZZZZ; switch per task.

A few directions (the concrete tool/skill shapes are co-designed with your agent):

All four design red lines apply to variants too (see the development guide): no npm imports in local modules, services must live inside the isolate realm group, events.jsonl is the sole authority, review decisions are write-once and never downgraded.

Tool surface (15 model tools)

Configuration

Edit humanize.config.json (absent = these defaults), then restart the session:

Subagent model priority: node model → flow-level model → config nodeModelDefault → session's model. Gate nodes run no agent; their model field is ignored.

Architecture

DeepSeek Harness host (model routing · sandbox/approval · credential store · Web GUI · subagents registry)
└─ humanize preset (isolate-realm group, travels with its directory, zero build zero deps)
   ├─ persona                     flow-first behavioral charter ({{model}}/{{cwd}} resolved by host)
   ├─ skills/humanize-flow        skill teaching the model to author & drive flows correctly
   ├─ plugins/flow-kernel.mjs     pure-function kernel: document model · canonicalization · SHA-256 · check · predicates
   ├─ plugins/humanize-store.mjs  persistence: drafts · locks · HMAC reviews · event log
   └─ plugins/tool-flow.mjs       15 model tools + replay-driven scheduler

Host and preset responsibilities stay strictly layered: shell execution goes through the host sandbox, subagents through the host registry; the preset contributes only the "flow" discipline — it never touches credentials and never relaxes host confinement.

Repository layout

agent.cordis.yml        composition: full standard capabilities + humanize runtime group (isolate realm)
preset.yml              roster metadata
humanize.config.json    preset configuration
plugins/
  flow-kernel.mjs       pure-function kernel (no I/O)
  humanize-store.mjs    persistence + HMAC review store + event log
  tool-flow.mjs         15 model tools + replay-driven scheduler
skills/humanize-flow/   flow-authoring skill
bridge/installer.mjs    dsh bundle installer bridge (plugin install form)
package.json            dsh.bundle manifest (`dsh plugin add` entry)
cordis.patch.yml        bundle patch: injects the installer bridge into the host
tools/                  smoke tests · composition checker · docs checker · one-line installer
docs/design.md          porting design spec
docs/parity.md          capability-parity audit against the humanfia ecosystem

Mapping to the original humanfia projects

Full per-item audit (✅ aligned / 🔁 host-equivalent / 🚧 partial / ⛔ non-goal + closing paths): docs/parity.md.

Development

Add a tool: ctx.tools.register({...}) in tool-flow.mjs; JSON Schema parameters; consume host capabilities via ctx.get('service') inside execute(args, exec).

Add a service: export name and apply(ctx), publish with ctx.provide('name', api); add a row name: ./plugins/<module>.mjs inside the humanize group of agent.cordis.yml. Consumers resolve via inject: ['name']; the group's isolate realm keeps sessions safe.

Swap skills/prompts: drop directories into skills/; edit persona text in the composition.

Change kernel semantics: flow-kernel.mjs is pure (no I/O); after editing run the smoke test:

node tools/test-humanize.mjs

Design red lines (read before changing code)

• Local modules must never import npm packages (user dirs have no node_modules resolution chain); only node: builtins.
• Service rows must sit inside the isolate realm group or the mount audit rejects them (process-global service leakage).
• events.jsonl is the sole authority: caches only rebuild views and must never become the source of truth.
• Review decisions are write-once, never overwritten; MAC verification failure must hard-fail, never degrade.

Contributing

Issues and PRs welcome. Follow Conventional Commits; make sure all three local checks pass before submitting:

node tools/test-humanize.mjs
node tools/check-composition.mjs
node tools/check-docs.mjs

License

MIT © 2026 Guard42 and dsh-humanize contributors

Special thanks

Special thanks to the humanfia team: the "we build the flow around the agent" methodology embodied by humanize2, oh-my-humanize and humanize-plugin is this project's direct inspiration and design foundation.

Thanks to DeepSeek Harness and Cordis for the plugin-based foundation, to the awesome-dsh-plugin community for the ecosystem, and to everyone who uses, reports and builds.

Star History