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.

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):

Domain (YYYY)	Example tools (XXXX)	Skills worth capturing
Quant research	market-data fetcher, backtest result validator, factor-significance referee	end-to-end factor research methodology
Paper writing	writing-discipline audit wrapper, citation integrity checker, journal format validator	pre-submission checklist
Contest modeling	solver invocation wrapper, data-cleaning pipeline, paper template renderer	three-phase modeling methodology

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)

Tool	Purpose
flow_draft	write a complete FlowDraft (whole-document replace)
flow_check	structural validation producing diagnostics; locking requires zero errors
flow_lock	canonicalize + SHA-256 → immutable flk_<digest>
flow_list	list everything tracked: drafts / locks / reviews / runs
flow_show	render one flow as a readable graph: stages, referees, routes
flow_review_prepare	produce the HMAC-signed binding + a readable review.md
flow_review_decide	THE single decision tool: approved / rejected / bypassed, terminal
flow_run	verify the binding → schedule ready nodes → return a run id immediately
flow_status	replay one run from its event log: node status, activations, artifacts
flow_resume	continue after interruption; completed stages never rerun
flow_stop	cancel a run: aborts in-flight activations, progress stays valid
trace_export	md timeline / chrome-json (Perfetto) / jsonl exports
edit_anchored	hash-anchored edit: refuses when expectSha256 mismatches
hash_file	compute a file's current SHA-256 (pairs with edit_anchored)
model_catalog	list provider routes and models for flow node selection

Configuration

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

Key	Default	Meaning
stateRootMode	"workspace"	workspace → <cwd>/.humanize; home → ~/.dsh/humanize
defaultExecutor	"spawn"	default node executor spawn | fork
nodeModelDefault	""	subagent model "provider/model" or "model"; empty = inherit session model
maxParallel	2	concurrent activation cap per run
verifyTimeoutMs	600000	default referee command timeout

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

Original mechanism	This preset
FlowDraft → FlowLock (canonical bytes, flk_<digest>)	flow-kernel canonicalization + identityOf
Review Store (HMAC, terminal states, single decision tool)	reviews/ + review-mac.key + flow_review_decide
Append-only events as authority, snapshots as caches	events.jsonl + replayRun
humanize-plugin's tmux window→run, pane→node activation	run directories + activation events (subagents spawn/fork)
hmz trace collect → Perfetto	trace_export (chrome-json)
oh-my-pi/omp's hash-anchored edits	edit_anchored

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