把Harness写成代码：Better Harness DSL v0.3资源模型完全教程（skill/workflow/runtime/deployment一次讲透）

把Harness写成代码Better Harness DSL v0.3资源模型完全教程skill/workflow/runtime/deployment一次讲透【免费下载链接】better-harnessAn open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.项目地址: https://gitcode.com/gh_mirrors/be/better-harnessBetter Harness 是一个开源的 Harness 工程平台让你把编码代理coding agent的 Harness 写成代码用 Better Harness DSL v0.3 声明 skill、tool、workflow、runtime 与 deployment运行受控实验、审查执行证据、对比运行结果。这篇文章是一次讲透 v0.3 资源模型的完整教程面向第一次接触 Harness 的新手不需要阅读源码也能跟上。 为什么要把 Harness 写成代码过去写 Harness 配置往往是写了一堆看起来可移植、但执行器根本不会执行的字段强度等级、权限声明、自由配置项……v0.3 做了减法它只允许你写可被编译器、解析器、适配器或执行器证伪的契约这个 Harness 需要哪种 workflow 和哪些能力哪个命名 deployment 选择它的 runtime适配器实际投递了什么设计细节记录在 2026-08-17-harness-dsl-v0.3-semantic-contraction.md。v0.3 的 8 种资源一览资源你声明的契约skill渐进式指引来自source目录、内联description或两者tool由稳定契约 ID 标识的原子可调用能力mcp适配器必须真正打开并发现的服务器连接workflowsession、state-machine、program三种控制形态之一agent逻辑角色及其能力要求状态机模式下 outcomes 是强类型的harness一个 workflow 加上它的逻辑角色runtime宿主 ID 加选定的适配器包deployment一个命名的、显式的 harness/runtime 配对没有通用插件、没有强度阶梯、没有自由配置项——核心语言里只有上面 8 种资源。⚡ 30 秒上手最小可执行 Harness一个真正可部署的 Harness 只需四件事声明语言版本、定义能力、指定 runtime、命名 deployment。完整源码见 minimal.harnesslanguage 0.3 skill require-tests { description Do not report the task complete until tests or a diff review prove it. } workflow single-pass { session coder } harness my-agent { workflow single-pass agent coder { use skill require-tests } } runtime qoder { adapter harness/adapter-qoder } deployment my-agent-qoder { harness my-agent runtime qoder }每个文档都必须以language 0.3开头缺版本号的源文件会被编译器直接拒绝。 四大核心资源逐个讲透skill 与 tool用动词区分满足的标准v0.3 用类型专属动词表达需求动词本身就是满足契约——skill 必须被投递delivered、tool 必须被暴露exposed且契约精确匹配、MCP 必须被连通connected。参考 standard-coding.harnessagent coder { use skill impact-analysis use skill verification-before-complete require tool workspace.read require tool workspace.write require tool process.exec }use skillskill 声明需要source指向真实技能目录或description内联指引至少其一。带 source 的 skill 在运行时会被锁定字节内容并真正投递文件缺失会直接让运行失败——它不是提一嘴而是送上门。require tool6 个标准工具 IDworkspace.read、workspace.glob、workspace.search、workspace.edit、workspace.write、process.exec无需声明编译器会合成冻结契约builtin:tool-id1。自定义工具则必须声明稳定的契约身份tool review.approve { contract urn:acme:review.approve:v1 description Record a review decision. }适配器暴露的工具必须同时匹配宿主工具名和这个精确契约名字差不多不算数。mcp声明连接而非声明工具列表mcp package-registry { transport http url env.PACKAGE_REGISTRY_MCP }mcp声明的是服务器连接stdio需要commandhttp/sse需要url字符串或环境变量。它能提供哪些工具由运行时发现决定——v0.3 特意移除了 v0.2 里那些看起来像 schema 但运行时并不校验的输入/输出名单。workflow三种形态各说各话① session可移植形态——Qoder 与 Pi 适配器实际运行的就是单个宿主会话workflow coding-session { session coder }使用它的每个 harness 必须恰好声明这一个 agent。多个逻辑角色不会被悄悄压扁成一个 prompt 会话。② state-machine显式状态机——角色、结果outcomes、可达性、停止条件全部强类型workflow coding-loop { state-machine entry author on author.ready - verifier on verifier.failed - author stop when verifier.passed } harness reviewed-coding { workflow coding-loop agent author { outcomes { ready } } agent verifier { outcomes { failed passed } } }编译期会校验角色、结果、可达性和停止条件但当前出厂的适配器描述符只支持session状态机在解析阶段会显式失败而不是退化成一段提示词。③ program程序化控制器——不假装 DSL 自己会执行它而是指名控制器workflow scripted-loop { program deno ./flows/coding-loop.ts }仅当适配器声明支持programmatic且把deno列入programmaticLanguages时才能解析。runtime 与 deployment命名配对稀疏可审计runtime qoder { adapter harness/adapter-qoder } deployment my-agent-qoder { harness my-agent runtime qoder }这是 v0.3 组合规则的核心只有被命名 deployment 声明的 harness/runtime 配对才可部署。两个 harness 加两个 runtime 不会静默产生四个组合deployment ID 与配对于源文件内都必须唯一重复会被编译拒绝。revision 中还会记录 deployment 的 ID 与内容哈希。 信任链从源码到证据一个.harness源文件走完这样的链条详见 README.md.harness source │ compile ▼ versioned IR bundleirVersion: 0.3.0 │ resolve named deployment against adapter facts ▼ HarnessRevision ResolutionReport │ preflight and materialize ▼ HarnessMaterializationReceipt run evidenceIR 包锁定语言版本irVersion: 0.3.0是版本判别器v0.2 产物不会被重新解释。Revision深度冻结绑定 harness、deployment、workflow、已解析能力的内容哈希以及 runtime/适配器描述符身份。Preflight在加载宿主 SDK 之前重算 revision ID 与包哈希宿主、适配器、deployment、内容或源码有任何漂移都会被拒绝。Receipt只记录实际投递的事实维度delivered/exposed/connected、状态与机制不再重复那些适配器根本忽略的作者权限声明。 编译、解析与校验动手验证你的 Harness不用读 TypeScript API也可以立即验证自己写的文件。仓库内置了 AI 创作技能与校验脚本见 SKILL.mdnode packages/harness/skills/generate-harness-dsl/scripts/validate.mjs workflow.harness它会解析文档并逐一校验每个命名 deployment像 full-surface.harness 这类全语法面文件编译会通过但其不受支持的 deployment 会带着明确原因解析失败——这正是 v0.3 想要的行为失败要诚实、要可定位。语法本身定义在 harness.langium紧凑的书写契约见 dsl-contract.md。 从证据到洞察Harness 跑完之后看什么Harness 执行留下的不止是日志。Better Harness 的 Harness Inspector 把真实会话证据组织成可审查的视图左侧是日期与活动概览中间是用户 prompt 流右侧是按工具动作聚合的 Checkpoint Activity还能一键展开完整会话——每一次Run Command、Edit Files、Read Files都有归属路径与耗时。当多份运行证据汇总分析后会得到结构化的发现与建议报告每条 finding 标注严重级别High/Medium/Low、所属能力维度如 Controlled Execution、Reliable Delivery并给出为什么重要、预期产出和可执行的 AI 修复路径。配合历史快照你还可以跟踪多个维度Task Understanding、Controlled Execution、Change Validation 等跨时间的变化——注意报告边界会明确提示这是趋势不是因果证明。 延伸阅读包总览与 TS APIcompile → resolve → executepackages/harness/README.md可执行示例standard-coding.harness、full-surface.harnessv0.3 设计与验收证据2026-08-17-harness-dsl-v0.3-semantic-contraction.md语法高亮定义harness-grammar.ts一句话总结Better Harness DSL v0.3 把 Harness 写作从许愿式配置变成契约式声明——8 种资源、3 种 workflow 形态、命名 deployment每一句都能被工具链证伪。把 Harness 写成代码你的代理行为从此可编译、可锁定、可审查。【免费下载链接】better-harnessAn open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.项目地址: https://gitcode.com/gh_mirrors/be/better-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考