Guard42/dsh-humanize

dsh-humanize

Humanize 模式 — humanfia 流理念 × DeepSeek Harness
把「围绕流构建」的纪律原生移植进 DeepSeek Harness 的 agent 预设：
阶段带裁判、锁有哈希、评审先行、事件为权威、可定制成领域变体。

独立社区开源项目，与深度求索（DeepSeek）及 humanfia 团队均无隶属、合作、授权或背书关系。中文 · English

dsh-humanize 是一个 DeepSeek Harness 的 agent preset（智能体预设）。安装后，你的编码代理会以 Humanize 纪律工作：

We build the flow around the agent.
多阶段目标变成显式的流——阶段带裁判命令、锁带哈希、运行前先评审、事件日志高于记忆。"Lean accepts it, or it does not"：验证命令 exit 0，阶段才算数；"The review is the next prompt"：未过审的锁绝不执行。

核心机制一览：

- Flow 内核 — 多阶段目标 → 阶段图；每阶段挂裁判命令，exit 0 才算数。
- 流锁身份 — 语义规范化 + SHA-256 → flk_ 不可变锁；加载时重验，防篡改。
- 评审门禁 — HMAC 签名绑定；approved / rejected / bypassed 终态不可变；拒绝理由折回草案。
- 可恢复运行 — append-only events.jsonl 是唯一权威；中断后 flow_resume 从回放继续——"周四停下的循环，周四继续"。
- Trace 导出 — 每次运行留痕，导出 Markdown 时间线或可导入 ui.perfetto.dev 的 Chrome-JSON。
- 哈希锚定编辑 — 整文件 SHA-256 锚点校验后再做字面替换，杜绝"凭记忆改错文件"。

致谢与灵感来源

本项目的直接灵感来源与方法论贡献来自 humanfia 团队与 humanize2 框架。没有这些项目，就没有这个预设：

- humanfia — humanfia 团队主页，「围绕流构建」理念的源头
- humanfia/humanize2 — 编排、执行、观测 agent 流的框架；本预设的流生命周期、锁身份、评审门禁与事件回放语义均以其为蓝本
- humanfia/oh-my-humanize — 工作流原生的终端编码代理；其哈希锚定编辑与技能组织方式被本预设继承
- humanfia/humanize-plugin — 本预设工具面的直系前身（flow_suggest/check/lock/review/run 的 MCP 插件形态）

同时感谢：

- DeepSeek Harness 与 DeepSeek AI — 上游运行平台：模型路由、沙箱、凭据存储、Web GUI 与 subagents 均来自宿主
- awesome-dsh-plugin — 社区插件名录与生态

逐项能力对照（哪些机制级对齐、哪些由宿主等价承担、哪些明确是非目标）见 docs/parity.md。

安装

方式一：作为 dsh 插件一键安装（推荐）

本仓库同时是一个 DSH 插件包（bundle）：内置的安装器桥会在 DSH 启动时自动把预设同步进预设根目录；升级插件版本后重启，未被手动修改过的文件会自动更新（用户改过的文件永不覆盖）。

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

重启 DSH，在预设选择器里选择 「Humanize 模式」 即可。安装器桥的设计参考了 ChongCyrus/Vibe-Mathematics 的先例。

方式二：PowerShell 一行命令（Windows）
powershell -NoProfile -ExecutionPolicy Bypass -Command "iex(irm 'https://raw.githubusercontent.com/Guard42/dsh-humanize/main/tools/install.ps1')"

方式三：bash 一行命令（macOS / Linux）

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

方式四：手动克隆

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

更新与卸载

- 更新：重跑一次安装命令即可幂等覆盖。
- 卸载：删除 ~/.dsh/.agent-presets/humanize 目录后重启部署。

[!WARNING]
直接 dsh plugin add 一个只含预设文件的仓库并不会激活它——本仓库能这样做，是因为它声明了 dsh.bundle 清单并自带安装器桥（启动时把预设同步进 ~/.dsh/.agent-presets/humanize）。没有这层桥的纯 preset 仍需手动复制，参见 dsh-expert-mode 的踩坑说明。

若安装或同步时报 ACCESS_DENIED：目标目录多半在杀软/HIPS 文件防护范围内（实测火绒 sysdiag 会放行新建、拦截既有文件的写入）。把 %USERPROFILE%\.dsh 加入白名单后重跑即可；更新已安装预设前建议先重启部署，避免进程占用旧文件。

快速上手

选好「Humanize 模式」预设后，直接布置一个多阶段任务：

你: 把测试套件从 Jest 迁到 Vitest，改完全部测试必须绿。

代理: 这个多阶段目标我写成 flow ——
flow_draft    三个阶段：迁移配置 → 全量替换 → 测试全绿门禁
flow_check    结构校验，零错误
flow_lock     规范化+SHA-256 → flk_xxxxxxxx（不可变）
flow_review_prepare 生成 review.md 给你过目

你: approve（或给出拒绝理由，代理折回草案重新提交）

代理: flow_run → 各阶段子代理干活、裁判命令把关
中断了？没关系：flow_resume 从 events.jsonl 回放继续，
已完成的阶段绝不重跑。

定制与领域特化

这是本预设最重要的开放性：它不是一个固化的产品，而是一个可以生长的底座。

你可以在 DeepSeek Harness 中向大模型发出请求：

帮我往humanize模式中加入几种XXXX工具，以加强其在YYYY领域的能力，并且成为一个新的agent preset保存下来，命名为humanize-ZZZZ

这条请求背后真实发生的事情：

1. 加工具 — 代理在 plugins/ 下新增模块并 ctx.tools.register({...}) 注册（参数用 JSON Schema，实现只依赖 node: 内置模块——零 npm 依赖是设计红线）；需要共享状态的服务用 ctx.provide('名字', api) 发布，并在 agent.cordis.yml 的 humanize 组内登记。
2. 加技能 — 在 skills//SKILL.md 写入领域方法论（frontmatter：name / description），预设自带的技能扫描会自动发现。
3. 调 persona — 按领域改写组合文件里的行为准则文本。
4. 落成新预设 — 一条命令把当前定制保存为独立预设，与原版并存互不干扰：

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

PRESET_NAME=humanize-ZZZZ bash tools/install.sh

5. 选用 — 重启后在预设选择器里会同时出现「Humanize 模式」和「humanize-ZZZZ」，按任务随时切换。

几个方向示例（工具与技能的具体形态由你和代理共同设计）：

| 领域（YYYY） | 可加入的工具（XXXX）示例 | 可沉淀的技能 |
|---|---|---|
| 量化研究 | 行情数据拉取器、回测结果校验器、因子显著性检验裁判 | 因子研究全流程方法论 |
| 论文写作 | 写作纪律审计封装、引用完整性检查、期刊格式校验 | 投稿前自查清单 |
| 竞赛建模 | 求解器调用封装、数据清洗管道、论文模板渲染 | 建模赛三阶段方法论 |

四条设计红线对变体同样生效（详见下文二次开发指南）：本地模块禁止 import npm 包、服务必须在 isolate realm 组内、events.jsonl 是唯一权威、评审决策一次写入永不降级。

工具面（15 个模型工具）

| 工具 | 作用 |
|---|---|
| flow_draft | 写入完整 FlowDraft（整文档替换） |
| flow_check | 结构校验，产出诊断；锁定要求零错误 |
| flow_lock | 规范化 + SHA-256 → flk_ 不可变锁 |
| flow_list | 列出工作区全部 flows：drafts / locks / reviews / runs |
| flow_show | 渲染一条 flow 为可读图：阶段、裁判命令、路由 |
| flow_review_prepare | 生成 HMAC 签名评审绑定 + 可读 review.md |
| flow_review_decide | 唯一决策工具：approved / rejected / bypassed，终态不可变 |
| flow_run | 校验签名绑定 → 调度就绪节点 → 立即返回 runId |
| flow_status | 从事件日志重放单次运行：节点状态、激活数、工件 |
| flow_resume | 中断后恢复：已完成阶段绝不重跑 |
| flow_stop | 取消运行：中止在途激活，进度保留至最近落定事件 |
| trace_export | md 时间线 / chrome-json（Perfetto）/ jsonl 三种导出 |
| edit_anchored | 哈希锚定编辑：expectSha256 不匹配即拒绝写入 |
| hash_file | 计算文件当前 SHA-256（配合 edit_anchored 使用） |
| model_catalog | 列出可用 provider 路由与模型，供 flow 节点选型 |

配置

编辑 humanize.config.json（缺省即下表默认值），重启会话生效：

| 键 | 默认 | 说明 |
|---|---|---|
| stateRootMode | "workspace" | workspace → /.humanize；home → ~/.dsh/humanize |
| defaultExecutor | "spawn" | 节点缺省执行器 spawn \| fork |
| nodeModelDefault | "" | 子代理模型 "provider/model" 或 "model"；空 = 继承会话模型 |
| maxParallel | 2 | 每 run 并发激活上限 |
| verifyTimeoutMs | 600000 | 裁判命令缺省超时 |

子代理模型三级优先级：节点 model → flow 顶层 model → 配置 nodeModelDefault → 继承会话模型。gate 节点不跑代理，其 model 字段忽略。

架构

DeepSeek Harness 宿主（模型路由 · sandbox/approval · 凭据存储 · Web GUI · subagents 注册表）
└─ humanize 预设（isolate realm 组，随目录安装，零构建零依赖）
├─ persona                     流优先的行为准则（{{model}}/{{cwd}} 由宿主解析）
├─ skills/humanize-flow        教模型正确编写与驾驶 flow 的技能
├─ plugins/flow-kernel.mjs     纯函数内核：文档模型 · 规范化 · SHA-256 · check · 谓词
├─ plugins/humanize-store.mjs  持久化服务：草稿 · 锁 · HMAC 评审存储 · 事件日志
└─ plugins/tool-flow.mjs       15 个模型工具 + 事件回放调度器

宿主职责与预设职责严格分层：shell 执行走宿主沙箱，子代理走宿主注册表，预设只贡献“流”这一层纪律，不触碰凭据、不放宽任何宿主约束。

目录结构

agent.cordis.yml        组合：standard 全部能力 + humanize 运行时组（isolate realm）
preset.yml              roster 元数据
humanize.config.json    预设级配置
plugins/
flow-kernel.mjs       纯函数内核（无 I/O）
humanize-store.mjs    持久化 + HMAC 评审存储 + 事件日志
tool-flow.mjs         15 个模型工具 + 事件回放调度器
skills/humanize-flow/   flow 编写技能
bridge/installer.mjs    dsh bundle 安装器桥（plugin 安装形态）
package.json            dsh.bundle 清单（dsh plugin add 入口）
cordis.patch.yml        bundle patch：向宿主注入安装器桥
tools/                  冒烟测试 · 组合检查器 · 文档检查器 · 一键安装器
docs/design.md          移植设计规格
docs/parity.md          与 humanfia 生态的能力对齐审计

与 humanfia 原版的对应

| 原版机制 | 本预设实现 |
|---|---|
| FlowDraft → FlowLock（canonical bytes, flk_） | flow-kernel 规范化 + identityOf |
| Review Store（HMAC、终态、单一决策工具） | reviews/ + review-mac.key + flow_review_decide |
| append-only 事件为权威、快照为缓存 | events.jsonl + replayRun |
| humanize-plugin 的 tmux window→run、pane→节点激活 | run 目录 + activation 事件（subagents spawn/fork 驱动） |
| hmz trace collect → Perfetto | trace_export（chrome-json） |
| oh-my-pi/omp 的 hash-anchored edits | edit_anchored |

完整逐项对照（✅ 对齐 / 🔁 宿主等价 / 🚧 部分 / ⛔ 非目标 + 补齐路径）见 docs/parity.md。

二次开发指南

加一个工具：在 tool-flow.mjs 里 ctx.tools.register({...})，参数 schema 用 JSON Schema 对象，execute(args, exec) 里通过 ctx.get('服务名') 消费宿主能力。

加一个服务：新模块导出 name 与 apply(ctx)，用 ctx.provide('名字', api) 发布；在 agent.cordis.yml 的 humanize 组内加一行 name: ./plugins/.mjs。同组消费者 inject: ['名字'] 即可解析；组内 isolate realm 保证跨会话安全。

换技能/提示词：skills/ 直接加目录；persona 在组合文件里改文本。
调内核语义：flow-kernel.mjs 是纯函数（无 I/O），改完跑冒烟：

node tools/test-humanize.mjs

设计红线（改代码前先读）

- 本地模块禁止 import 任何 npm 包（用户目录没有 node_modules 解析链）；只用 node: 内置。
- 服务行必须在 isolate realm 组内，否则挂载审计拒绝（process-global service 泄漏）。
- events.jsonl 是唯一权威：任何状态缓存都只是重建视图，不得反向成为事实来源。
- 评审决策一次写入、永不覆盖；MAC 校验失败必须硬失败，不许降级放行。
- 禁止向会话日志写自定义事件：原版 harness 对未知事件类型按必需事件拒绝解读整份日志
（SessionFormatUnsupportedError），且信封的 ignorable 标记无法通过公开 append API 表达。
状态一律落 .humanize/ 文件。若旧版本（<= 0.1.0）的日志已损坏，用修复工具恢复：

node tools/repair-session-log.mjs "$env:USERPROFILE\.dsh\sessions" --scan   # 盘点（默认 dry-run）
node tools/repair-session-log.mjs "$env:USERPROFILE\.dsh\sessions" --scan --apply  # 备份后原地修复
参与

欢迎 Issue 与 PR。提交信息遵循 Conventional Commits；PR 前请确保三项本地检查全绿：

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

License

MIT © 2026 Guard42 and dsh-humanize contributors

特别感谢

特别感谢 humanfia 团队：humanize2、oh-my-humanize、humanize-plugin 所代表的"围绕流构建"方法论，是这个项目的直接灵感来源与设计基石。

感谢 DeepSeek Harness 与 Cordis 提供的插件化底座，感谢 awesome-dsh-plugin 社区的生态共建，以及每一个使用、反馈和参与的你。

Star History

Star History