DeepSeek Harness 模型侧目标工具深度解析get_goal / create_goal / update_goal 的持久化目标生命周期控制【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南以 DeepSeek Harness 仓库中已实现的 Agent Note: Model-facing same-session goal tools 为骨架完整剖析deepseek-ai/dsh-tool-goal插件如何为模型提供get_goal、create_goal、update_goal三个目标工具从工具契约、执行期权威校验、阻塞阈值到系统提示词策略与测试验证读者读完可以掌握该模型侧目标生命周期的设计原理、配置方式与实战接线方法。背景为何模型需要一套目标工具而不直接操作目标服务在 DeepSeek Harness 中持久化目标领域persisted goal domain刻意只对插件暴露生命周期动词而不是直接暴露给模型。模型仍然需要一个小的控制 API 来完成三件事发现当前目标discover、从人类意图创建目标create、改变目标生命周期change lifecycle。仅仅依赖提示词无法确立谁授权了这次变更一个子代理subagent、一条注入的插件消息、一次过期模型轮次stale model turn或一个恢复的会话都可能产生完全相同的工具参数。因此权威必须由运行时在执行时裁决而不是由模型自述。同时工具 API 还必须保留**持久状态durable state与实时执行权威live execution authority**之间的分离一个被恢复restored或分叉forked的会话可以重放一个活动目标但开始时处于**解除武装disarmed**状态后续人类的继续请求应让模型通过工具重新武装rearm它而不需要用户说出特定的命令短语。反过来一个被接纳的自主目标轮次autonomous goal round必须能报告完成或持久阻塞但不能因此获得编辑、暂停、恢复或替换人类目标的权限。这一设计最终落地为packages/goal/tool-goal/目录下的deepseek-ai/dsh-tool-goal插件它通过ctx.goals贡献三个排他工具exclusive tools和一段系统提示词策略节。工具与模型契约三个工具的完整参数面工具清单工具签名作用get_goalget_goal()读取当前目标无目标时返回nullcreate_goalcreate_goal(objective, max_goal_rounds?)创建一个长期运行的同一会话目标update_goalupdate_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)对精确目标修订执行edit/pause/resume/complete/blocked名称与读-创建-更新read-create-update的形状借鉴了 Codex 的紧凑目标工具面而权威规则则使用本仓库公开的 agent、session、tool 与 goal 服务。三个工具均以**排他执行exclusive execution**方式注册因此模型在一次批次中发出的多个调用会观察到先前的变更及其新修订号参见 index.ts 中的ctx.tools.register(defineTool(...))。get_goal 的返回结构非null结果包含compare-and-set 标识id目标稳定标识与revision正数修订号每次持久化变更递增objective人类请求的完成目标文本phase持久化生命周期阶段枚举为active | paused | blocked | completeroundsStarted当前目标已接纳的最高轮次号maxGoalRounds自动继续轮次的总上限blockedReason可选包含稳定的code与人类可读的messageactivation进程本地激活观测取值为armed | disarmed从不写入重放状态。底层类型定义见 types.ts 中的GoalView、GoalSnapshot、GoalRef与GoalActivation以及 domain.ts 中声明的goal/change事件与goal/changed生命周期钩子。update_goal 的动作与字段规则update_goal的字段约束在 index.ts 中通过hasText/hasRoundCap两个守卫实现替换字段仅对edit有效objective与max_goal_rounds只在action: edit时允许携带blocked_reason仅在action: blocked时必需且持久化时使用稳定代码model-reported严格模式空填充符strict-schema fillers视为省略精确的空字符串可选字段、以及为0的max_goal_rounds都按未提供处理——因为严格模式的 provider 会把每个可选字段序列化为零值占位但edit仍至少需要一个有意义的替换字段所有非填充值依然遵守动作限制。例如在pause/resume下携带了非空objective、非零max_goal_rounds或非空blocked_reason会抛出GOAL_TOOL_INVALID_UPDATE错误。结果统一为紧凑 JSON{ goal: null }或{ goal: {...}, activation }其 JSON Schema 定义在GOAL_VALUE_SCHEMA中UI 展示是参数与结果的纯函数读取用通用读卡片read card变更用通用变更卡片mutation card且变更卡片把有意义的 action 值放在目标 id 之前渲染从而避免被接受的填充符清空输入框。系统提示词策略节插件注册了一个名为tool:goal、顺序号为FIRST_PARTY_SECTION_ORDER.TOOL_GOAL的系统提示词节其指导文本见guidance()函数向模型说明可以从任何措辞或语言的直接人类请求中推断目标意图来调用create_goal但不应把常规单轮工作转化为目标更新前必须先get_goal并原样复制返回的goal_id与revision在恢复或分叉的活动但已解除武装active-but-disarmed目标上语义上的人类继续请求是resume的正当依据只有目标真正达成才可complete困难或不确定性本身不构成阻塞阻塞报告必须指名具体的阻塞条件。该段文本会插值部署配置的阻塞阈值默认 3 轮因此模型看到的指导与执行期强制的阈值始终一致。执行权威Execution Authority运行时如何裁决每一次调用权威检查集中在 authority.ts全部为执行期检查无法被提示词注入或手写工具参数绕过。所有调用的公共前提每一次调用都要求exec.agent必须是AgentRegistry中正在运行的精确对象ctx.agents.get(agent.id) ! agent或状态非running即拒绝必须是当前继承的驱动发起者inherited driver initiatorctx.agents.currentInitiator() ! agent即拒绝必须有一个开放的模型轮次openTurn()会从事件流尾部向前扫描若遇到turn/end或找不到turn/start就抛出GOAL_TOOL_DRIVER_REQUIRED。失败统一抛出带稳定错误码的HarnessError例如GOAL_TOOL_AGENT_REQUIRED、GOAL_TOOL_DRIVER_REQUIRED。直接人类权威create / edit / pause / resume这四个动作额外要求当前轮次中、运行时根runtime-rootagent 上存在一条被接纳的人类消息或人类转向事件。hasDirectHumanInput()的判定逻辑是ctx.agents.roots().includes(execution.agent)—— 调用者必须是当前活动 agent 图中的根而不是活的子代理当前轮次事件中存在type: user/message且event.data.source.kind user的条目。关键点在于根归属root ownership来自实时 agent 图而非持久化的分叉祖先durable fork ancestry一个被恢复为顶层会话的分叉fork可以获得直接人类权威而一个活的子代理永远不能变更这些状态。hasDirectHumanInput中有一条值得注意的实现细节当Agent.followup()或steer()的调用者省略 source时默认解析为user——因此插件、调度器等非人类生产者必须显式提供自己的 source而不是继承这份人类权威。此外运行时证明的是当前轮次包含一条直接人类消息而不是人类措辞在语义上是否值得创建或恢复目标——语义解读始终留给模型。完成权威complete / blocked 的双通道complete与blocked接受两类权威直接人类权威与上面相同人类可以直接立即停止目标精确当前目标轮次exact current goal round要求轮次事件中存在source.kind goal的用户消息且其goalId、revision、round三者和折叠后的当前目标完全相等见isMatchingGoalRound()。目标轮次权威只授予这两个终结报告不允许编辑、暂停、恢复或替换目标——自主目标轮次可以收尾但不能扩权。completionAuthority()先检查直接人类输入再回退到目标轮次匹配。阻塞阈值blockedAfterConsecutiveRounds配置与校验blockedAfterConsecutiveRounds是tool-goal唯一的配置项声明在 index.tsexport const Config: zConfig z.object({ blockedAfterConsecutiveRounds: z.number().step(1).min(1).default(3), })resolveConfig()会在插件直接apply时再次校验必须是正的 safe integer否则抛出TypeError。默认值为3。强制执行逻辑当自主目标轮次调用blocked时插件机械地要求至少达到配置轮数的已接纳轮次authority.goal.roundsStarted blockedAfterConsecutiveRounds否则抛出GOAL_TOOL_BLOCK_THRESHOLD错误必须提供非空的blocked_reasonargs.blocked_reason.trim().length 0即拒绝。配置值同时出现在模型指导文本中guidance()插值保证提示词告知的规则与执行强制的规则为同一个解析值。注意运行时无法判断这些轮次是否遇到同一阻塞条件语义等价性仍然是模型判断且该计数刻意与目标自身的宽裕继续上限max_goal_rounds相互独立。配置示例- id: tool-goal name: deepseek-ai/dsh-tool-goal config: blockedAfterConsecutiveRounds: 3完整的配置字段清单以生成的 配置目录 为准。自主轮次的收尾指令从硬停止到回写消息一个自主目标轮次成功报告complete或blocked时不会立即结束物理轮次而是通过ToolRunContext.deferContext()注入一条收尾指令到工具结果上使模型在轮次结束前、通过常规的无工具调用停止no-tool-calls stop再对用户说一次话。这取代了最初在结果处结束conclude-at-result stop的设计——后者的缺陷记录在 目标轮次收尾消息修复笔记自主轮次报告终结后模型永远不再说话会话以一张光秃秃的update_goal卡片结束模型调用前的预告文本永远等不到正文。wrapup.ts中的renderWrapupContext()生成两种指令goal_complete要求模型立即向用户写收尾消息——陈述结果、总结做了什么与如何验证、指向具体成果文件、提交或其他工件、注明用户需要审阅或下一步的事项并且本轮不再调用任何工具goal_blocked要求模型陈述已完成的进展、描述具体阻塞条件与尝试过的做法、准确说明继续所需的用户输入同样不得再调用工具。两种指令都包含**会话锚定grounding**子句只报告本会话中先前轮次和工具结果实际建立的内容细节不在会话中就明说而不是编造。该上下文以source: { kind: plugin, plugin: tool-goal, form: notice }的用户消息形式注入。直接人类发起的变更不注入任何指令助手可以简单确认变更并保留并发人类转向concurrent human steering给常规停止检查。代价是每个目标生命周期多一次模型请求而非每轮一次。测试与验证从单元覆盖到无密钥重放快照tool-goal.spec.ts 对整套行为做了系统化覆盖可归纳为几组注册与展示三个排他工具的注册与销毁、配置化指导文本生成、通用展示意图、非法直接配置在注册前失败、默认值解析执行权威根模型从被接纳的人类轮次推断创建意图、agentless/driverless/非人类/活子代理创建被拒、过期 agent 对象与非 running 状态被拒、被恢复的分叉作为运行时根的权威、轮次边界调用前/结束后被拒、无人类输入与无目标轮次时终结报告被拒、目标来源轮次中的直接人类转向、initiator 不匹配被拒状态迁移读取 null → 编辑 → 暂停 → 恢复的精确修订链、自主完成的收尾指令注入人类暂停保持交互、直接人类权威下完成不注入收尾指令、恢复的活动目标在新的直接人类提示后才重新武装agent/session-start来源为resume的边缘场景、结构化领域与条件参数失败、严格填充符下未使用字段只接受空填充、精确目标轮次可完成但不可编辑/暂停、配置的自阻塞下限跨已接纳轮次强制、直接人类权威可在阈值前阻塞。此外一份无密钥keyless重放快照把目标领域与工具挂载到真实的 headless 一次性应用one-shot application中用严格填充符的update_goal探针驱动create_goal与get_goal走完整的发布循环与持久化栈钉住其 stream-json 转录并检查外部持久化的目标变更。该快照刻意不使用echo-agent fixture 作为应用 UX 的替身。为支撑这种无密钥证明快照基础设施新增了{{fromRequest:regex}}占位符解析见 收尾消息修复笔记因为静态 sidecar 无法预知模型必须回显进update_goal的随机目标 id。备选方案权衡与最终取舍设计过程中明确否决过的方案及其理由详见原 Agent Note备选方案被否决的理由完全依赖提示词指令来授予权威文本能引导模型判断但无法认证调用者、轮次或来源事件把目标服务的每个动词暴露成独立工具紧凑的 read/create/update API 降低 schema 成本并统一 CAS 行为要求精确命令短语自然语言意图含英语以外语言应交由模型解读执行权威依赖当前轮次中的直接人类消息而非拼写依据持久化根或分叉元数据授权独立恢复为顶层会话的分叉应接受新的人类权威而被当前拥有的子代理不应允许自主轮次编辑或恢复目标继续权威比重新定义或重启人类目标的权限更窄把阻塞阈值当作评估器事件计数无法证明障碍在语义上未变或真正终结拒绝所有当前动作专属字段严格 schema 的 provider 会为每个可选字段序列化零值占位只有有意义的值才能表达冲突动作集成与运行效果dsh-tool-goal是目标表面的模型侧一半与以下组件配合使用dsh-goal目标服务packages/goal/goal/工具所变更的目标状态与生命周期dsh-command-goalpackages/goal/command-goal/人类斜杠命令slash-command的发现与渲染由它独立负责目标轮次驱动goal-round driverpackages/goal/goal-round-driver/自主继续轮次的调度器工具本身不调度目标轮次、不分类异常驱动停止、也不取消活动轮次——这些由同一会话驱动same-session driver负责挂载方式将tool-goal与dsh-goal一同挂载模型即可自行管理目标。效果总结模型获得稳定紧凑的生命周期 API无需直接访问目标服务状态变更调用要求活的运行时根 agent 当前轮次直接人类消息 持久化 CAS 引用三重条件人类请求可以通过任意自然语言创建与重新武装目标而恢复的会话在收到此类输入前保持惰性目标轮次可以完成或报告持续阻塞但不能扩大自己的授权部署策略选定阻塞下限同一个解析值同时控制执行强制与提示词指导严格 schema 的 provider 填充符可以互通而不会允许有意义的跨动作更新。已知限制与后续工作语义分类仍是模型判断一个目标是否足够重大、一次继续请求、目标完成判定、以及同一阻塞条件的判定都依赖模型独立评估器或完成证书completion certificate仍在延后只变更状态不做调度这些工具不调度目标轮次、不分类异常驱动停止、不取消活动轮次目标轮次权威默认休眠除非单独挂载的继续驱动接纳目标来源的用户轮次否则自主complete/blocked路径不会被激活——本工具包从不自行制造该权威提示词注册与工具过滤相互独立作用域scope可以隐藏工具注册却仍保留独立注册的提示词节除非部署时把两者一起限定作用域。深入阅读工具包 README安装、配置与模型体验说明目标服务 README工具所变更的目标状态机与投影目标领域类型定义GoalView/GoalSnapshot/GoalRef的纯类型契约权威检查实现执行期权威判定的完整源码生成的工具目录模型实际收到的精确 schema生成的配置目录blockedAfterConsecutiveRounds的完整配置说明。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
