dsh-humanize
Humanize 模式 — humanfia 流理念 × DeepSeek Harness
把「围绕流构建」的纪律原生移植进 DeepSeek Harness 的 agent 预设：
阶段带裁判、锁有哈希、评审先行、事件为权威、可定制成领域变体。
独立社区开源项目，与深度求索（DeepSeek）及 humanfia 团队均无隶属、合作、授权或背书关系。
中文 · English
dsh-humanize 是一个 [DeepSeek Harness](https://github.com/deepseek-ai/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](https://ui.perfetto.dev) 的 Chrome-JSON。
- **哈希锚定编辑** — 整文件 SHA-256 锚点校验后再做字面替换，杜绝"凭记忆改错文件"。
## 致谢与灵感来源
本项目的**直接灵感来源与方法论贡献**来自 humanfia 团队与 humanize2 框架。没有这些项目，就没有这个预设：
- [humanfia](https://github.com/humanfia) — humanfia 团队主页，「围绕流构建」理念的源头
- [humanfia/humanize2](https://github.com/humanfia/humanize2) — 编排、执行、观测 agent 流的框架；本预设的流生命周期、锁身份、评审门禁与事件回放语义均以其为蓝本
- [humanfia/oh-my-humanize](https://github.com/humanfia/oh-my-humanize) — 工作流原生的终端编码代理；其哈希锚定编辑与技能组织方式被本预设继承
- [humanfia/humanize-plugin](https://github.com/humanfia/humanize-plugin) — 本预设工具面的直系前身（`flow_suggest/check/lock/review/run` 的 MCP 插件形态）
同时感谢：
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 与 DeepSeek AI — 上游运行平台：模型路由、沙箱、凭据存储、Web GUI 与 subagents 均来自宿主
- [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) — 社区插件名录与生态
逐项能力对照（哪些机制级对齐、哪些由宿主等价承担、哪些明确是非目标）见 **[docs/parity.md](docs/parity.md)**。
## 安装
### 方式一：作为 dsh 插件一键安装（推荐）
本仓库同时是一个 **DSH 插件包（bundle）**：内置的安装器桥会在 DSH 启动时自动把预设同步进预设根目录；升级插件版本后重启，未被手动修改过的文件会自动更新（用户改过的文件永不覆盖）。
```sh
dsh plugin --profile web add github:Guard42/dsh-humanize
```
重启 DSH，在预设选择器里选择 **「Humanize 模式」** 即可。安装器桥的设计参考了 ChongCyrus/Vibe-Mathematics 的先例。
### 方式二：PowerShell 一行命令（Windows）
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "iex(irm 'https://raw.githubusercontent.com/Guard42/dsh-humanize/main/tools/install.ps1')"
```
### 方式三：bash 一行命令（macOS / Linux）
```bash
curl -fsSL https://raw.githubusercontent.com/Guard42/dsh-humanize/main/tools/install.sh | bash
```
### 方式四：手动克隆
```powershell
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 的踩坑说明](https://github.com/Asher-2000/dsh-expert-mode#option-a-dsh-plugin-add-wont-crash-but--does-not-activate-expert-mode)。
>
> 若安装或同步时报 `ACCESS_DENIED`：目标目录多半在杀软/HIPS 文件防护范围内（实测火绒 sysdiag 会放行新建、拦截既有文件的写入）。把 `%USERPROFILE%\.dsh` 加入白名单后重跑即可；更新已安装预设前建议先重启部署，避免进程占用旧文件。
## 快速上手
选好「Humanize 模式」预设后，直接布置一个多阶段任务：
```text
你: 把测试套件从 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
powershell -NoProfile -ExecutionPolicy Bypass -File tools\install.ps1 -PresetName humanize-ZZZZ
```
```bash
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` 字段忽略。
## 架构
```text
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 执行走宿主沙箱，子代理走宿主注册表，预设只贡献"流"这一层纪律，不触碰凭据、不放宽任何宿主约束。
## 目录结构
```text
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](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），改完跑冒烟：
```powershell
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）的日志已损坏，用修复工具恢复：
```powershell
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](https://www.conventionalcommits.org/zh-hans/)；PR 前请确保三项本地检查全绿：
```powershell
node tools/test-humanize.mjs
node tools/check-composition.mjs
node tools/check-docs.mjs
```
## License
[MIT](LICENSE) © 2026 Guard42 and dsh-humanize contributors
## 特别感谢
特别感谢 [humanfia](https://github.com/humanfia) 团队：[humanize2](https://github.com/humanfia/humanize2)、[oh-my-humanize](https://github.com/humanfia/oh-my-humanize)、[humanize-plugin](https://github.com/humanfia/humanize-plugin) 所代表的"围绕流构建"方法论，是这个项目的直接灵感来源与设计基石。
感谢 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 与 [Cordis](https://github.com/cordiverse/cordis) 提供的插件化底座，感谢 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 社区的生态共建，以及每一个使用、反馈和参与的你。
## Star History
[](https://star-history.com/#Guard42/dsh-humanize&Date)