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](https://github.com/deepseek-ai/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_` 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](https://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](https://github.com/humanfia) — the team behind the "we build the flow around the agent" philosophy
- [humanfia/humanize2](https://github.com/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](https://github.com/humanfia/oh-my-humanize) — workflow-native terminal coding agent; its hash-anchored edits and skill organization carry over here
- [humanfia/humanize-plugin](https://github.com/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](https://github.com/deepseek-ai/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](https://github.com/awesome-dsh-plugin/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](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).
```sh
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
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)
```bash
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
```bash
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](https://github.com/Asher-2000/dsh-expert-mode#option-a-dsh-plugin-add-wont-crash-but--does-not-activate-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:
```text
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//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
powershell -NoProfile -ExecutionPolicy Bypass -File tools\install.ps1 -PresetName humanize-ZZZZ
```
```bash
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](#development)): 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_` |
| `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 → `/.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
```text
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
```text
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_`) | 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](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/.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:
```bash
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](https://www.conventionalcommits.org/); make sure all three local checks pass before submitting:
```bash
node tools/test-humanize.mjs
node tools/check-composition.mjs
node tools/check-docs.mjs
```
## License
[MIT](LICENSE) © 2026 Guard42 and dsh-humanize contributors
## Special thanks
Special thanks to the [humanfia](https://github.com/humanfia) team: the "we build the flow around the agent" methodology embodied by [humanize2](https://github.com/humanfia/humanize2), [oh-my-humanize](https://github.com/humanfia/oh-my-humanize) and [humanize-plugin](https://github.com/humanfia/humanize-plugin) is this project's direct inspiration and design foundation.
Thanks to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and [Cordis](https://github.com/cordiverse/cordis) for the plugin-based foundation, to the [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) community for the ecosystem, and to everyone who uses, reports and builds.
## Star History
[](https://star-history.com/#Guard42/dsh-humanize&Date)