hhd-harness https://github.com/VincentWei2021/hhd-harness
Everything is a Plugin. hhd-harness 是对 deepseek-harness（dsh）架构的 Python 全量实现：同样的插件内核（Cordis 语义）、同样的会话事件日志不变量、同样的工具执行把关流水线、同样的轮次/步骤驱动器、同样的 bundle/profile 组合机制，以及 CLI 与 Web 双端应用。运行时为 Python 3.10+ / asyncio，核心依赖 pydantic v2、httpx、PyYAML，Web 端为 FastAPI + uvicorn。
pip install -e ".[dev]" # 安装（含测试依赖）
hhd --llm mock run "用 bash 打印 hello 并记 todo" # 离线全链路演示
hhd chat # 交互 REPL（/help /sessions /fork）
hhd web # 浏览器聊天应用（SSE 实时渲染）
hhd --profile web --dump-config # 打印生效的插件组合树
pytest # 全量测试
对接真实模型：hhd --llm vllm --base-url http://localhost:8000/v1 --model <name> run "..."，或 hhd --llm ollama --model qwen3 run "..."。
架构映射（原包 → hhd 模块）
| deepseek-harness 包 | hhd 模块 | 职责 |
|---|---|---|
vendor/cordis |
hhd/cordis/（context / events / runtime / loader） |
插件协议、服务容器、inject 驱动挂载、emit/waterfall/parallel/serial 四种事件分发、可逆副作用、patch 分层叠加与 ! 受限表达式 |
packages/llm/llm |
hhd/llm/types.py、hhd/llm/service.py |
消息/流式词汇表、ctx.llm 适配器 seam（llm/stream waterfall） |
packages/llm/llm-deepseek 等 |
hhd/llm/adapter_vllm.py、adapter_ollama.py、adapter_mock.py |
OpenAI 兼容 SSE 流式 + 工具调用增量聚合；Ollama 双模式；脚本化 mock |
| llm retry | hhd/llm/retry.py |
指数退避包裹 llm/stream（首块急切拉取、contextvar 防自递归） |
packages/core/session |
hhd/core/session/ |
仅追加事件日志（SessionEventMap）、derive_messages() 投影、JSONL 持久化、fork 血统 |
packages/core/system-prompt |
hhd/core/system_prompt/ |
片段注册（优先级/身份段）与组装 |
packages/core/tools |
hhd/core/tools/ |
作用域化注册表 + 完整执行流水线（pre-execute → 审批 → 单调守卫 → execute → 工具本体 → post-execute → 规范化 → tool/result） |
packages/core/agent |
hhd/core/agent/ |
Agent 句柄（send/inject/cancel/wait）、inbox（唤醒 vs 留置）、活跃注册表 ctx.agents |
packages/core/agent-loop |
hhd/core/agent_loop/ |
轮次/步骤驱动器：turn → claim → pre-step → step → llm/stream → 工具批 → turn-stopping |
packages/shell/tool-bash |
hhd/tools/bash.py |
经 ctx.subprocess 的沙箱化 shell（超时/合并输出/尾部截断） |
packages/fs/tool-fs(-search)、tool-str-replace-editor |
hhd/tools/fs.py |
read/write/edit（先读后编辑）/glob/grep，写意图经沙箱 |
packages/todo |
hhd/tools/todo.py |
todo 状态以 todo/write 事件持久化 |
packages/web |
hhd/tools/web.py |
web_fetch（HTML → 纯文本） |
packages/subagent |
hhd/tools/subagent.py |
fork 会话委派子 agent，深度受限 |
packages/subprocess |
hhd/services/subprocess.py |
本地进程 spawn seam |
packages/settings / credentials |
hhd/services/settings.py、credentials.py |
settings.yaml 热加载；env:NAME 引用（env > .credentials.yaml） |
packages/sandbox + user-approval |
hhd/services/sandbox.py、hhd/core/tools/approval.py |
read-only / workspace-write / danger-full-access 三档预设 + 单调守卫；一次性询问审批 |
packages/jobs |
hhd/services/jobs.py |
后台任务注册 + job_list/read/stop 工具 |
| token 用量 | hhd/services/token_meter.py |
观察 session/event 累计 usage |
packages/bundle/base + boot/app-boot |
hhd/boot/（bundles / profiles / patches / registry / app） |
base ← profile ← home patch ← --patch 分层组合、--dump-config、可用性驱动挂载 |
apps/cli / apps/web |
hhd/apps/cli.py、hhd/apps/web.py |
hhd run/chat/web；FastAPI + SSE + 内置聊天页 + 浏览器审批 |
按“最小可用”实现（挂在与原项目相同的 seam 上，可按原架构增量补齐）：MCP 客户端、LSP、workflow/ralph、compaction、e2b、ACP、代码生成、遥测。
核心不变量
-
模型可见即已记录：每步发给模型的历史都由
derive_messages(session.events)从事件日志投影而来；持久日志可重建一切。 -
一切注册皆可逆：工具、适配器、提示词片段、监听器通过
ctx.effect()/ctx.on()注册，dispose 时按逆序撤销。 -
每个事件声明唯一分发模式：
emit（观察）、waterfall（中间件，next()委托/短路）、parallel（扇出）、serial（顺序传值）；用错方法即报错。 -
一次 tool/call 的完整把关链：记录 → pre-execute（allow/deny/ask → 审批）→ 单调守卫 → execute 包装（超时）→ 工具本体 → post-execute（改写/追加上下文）→ 异常规范化 →
tools/result。
组合与扩展
生效配置由分层叠加产生（后者按 id 整体替换前者，last-write-wins）：
空条目列表 ← base bundle（hhd/boot/bundles） ← profile 层（web / headless） ← $HHD_HOME/cordis.patch.yml ← --patch overlay（可多个）
配置值支持受限表达式："!env('HHD_PERMISSION_MODE', 'workspace-write')"、"!hhd_home_path('sessions')"、"!cwd()"（AST 白名单求值，替代原 !!js）。
-
加一个模型工具：写
ToolDefinition（name/description/parameters/execute），ctx.tools.register()注册即可获得完整流水线（审批/守卫/超时/日志）。 -
加一个 LLM 适配器：实现
async def stream(request) -> AsyncIterator[StreamChunk]，ctx.llm.register_adapter(adapter)；retry/计量等 waterfall 包装自动生效。 -
加任意插件：
Plugin(name=..., apply=..., inject=[...])，在 bundle/profile patch 中加一行 entry；挂载顺序由 inject 就绪驱动，无需手工编排。
环境变量与目录
-
HHD_HOME（默认~/.hhd）：settings.yaml、.credentials.yaml、cordis.patch.yml、sessions/*.jsonl -
HHD_PERMISSION_MODE：read-only|workspace-write（默认）|danger-full-access -
HHD_VLLM_BASE_URL/VLLM_API_KEY、HHD_OLLAMA_BASE_URL、HHD_WEB_HOST/HHD_WEB_PORT
测试
tests/ 与各阶段一一对应（cordis 内核语义、SSE 解析与重试、会话日志/fork、工具流水线、驱动器生命周期、工具插件、横切服务、boot/CLI/Web）。102 个测试全绿：pytest -q。