Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-24

DeepSeek Harness 源码深潜(中)——工具、提示词与插件内核(附DSH源码)

DeepSeek Harness中篇源码解析,拆解工具系统、提示词组装与插件内核,附DSH源码,助你掌握Agent工业级实现。 核心内容:

  1. 工具系统:function calling的工业级实现(第4章)
  2. 提示词组装:模型调用的“总装车间”(第5章)
  3. Cordis插件内核:DSH的立身之本(第6章)

系列:DeepSeek Harness(dsh)源码教程 · 中篇(第 4-7 章) 上篇:从 API 到 Agent 心脏(第 0-3 章) 下篇:模型适配、多 Agent 与 Python 实战(第 8-10 章)


上篇我们拆完了 Agent 的心脏:事件溯源的日志系统、turn/step 状态机、工具调度器。

但心脏只是泵血。中篇进入让 Agent 真正"能干活、可替换、可扩展"的部分:

如果说上篇是骨架,中篇就是肌肉与神经。


第 4 章 工具系统:FC 的工业级实现

核心机制:schema 驱动的声明式校验、五段执行流水线、TOOL_RUNTIME_SCHEDULER 调度器、执行模式(并行/串行)、作用域隔离。

4.1 从手写 dispatch 到工业工具系统

tools = [{”type”: ”function”, ”function”: {”name”: ”get_weather”, ”parameters”: {...}}}] def dispatch(name, args): if name == ”get_weather”: return get_weather(**args)

这个写法的问题:

  1. 校验靠手写:get_weather(city=123) 这种类型错要自己 if/else
  2. 没有把关:任何人都能调任何工具——delete_all() 被误调谁拦?
  3. 没有流水线:遥测、限流、权限检查要自己塞进 dispatch
  4. 作用域不分:主 agent 和子 agent 共用同一批工具
  5. 结果不可追溯:调用结果怎么和日志关联?

dsh 的答案就是本章内容。

4.2 defineTool:声明式定义 + 自动校验

export function defineTool( options: DefineToolOptions,): ToolDefinition { const parameters = parameterSchemaSpecToJsonSchema(options.parameters) const validate = (args: unknown): string[] => validateJsonSchemaValue(parameters, args, '') return { name: options.name, description: options.description, parameters, async execute(args, exec) { const violations = validate(args) if (violations.length > 0) throw new ToolArgsError(violations) return userExecute(args as InferArgs, exec) }, }}

关键点:ToolDefinition里execute是被包装过的——你写的 userExecute 永远在参数校验通过之后才被调用。

4.3 真实例子:tool-bash 的三层防御

层次 1:参数 schema

interface BashToolArgs { command: string description: string // 必填——”为什么执行”(可审计) timeoutMs?: number workdir?: string run_in_background?: boolean}

层次 2:业务校验

function validateBashArgs(args: BashToolArgs): void { if (args.command.trim().length === 0) { throw new Error('invalid command: expected a non-empty string') } // timeoutMs 必须是正有限数 // sandbox_permissions ⇔ justification 必须配对}

为什么 schema 之外还要手写校验?JSON Schema 表达不了"两个字段必须配对出现"这种跨字段约束。

层次 3:动态生成的工具描述

function bashDescription(backgroundEnabled: boolean, escalationModes: readonly SandboxMode[]): string { // 把当前沙箱模式、后台执行可用性写进描述}

工具描述不是静态字符串,是运行时生成的——环境变了,模型看到的工具说明就变了。

4.4 五段执行流水线

tools/pre-execute (瀑布事件:允许 / 拒绝 / 询问) ↓tools/execute (调度器分发) ↓tools/post-execute (结果后处理) ↓tools/result (结果观测)

每一个阶段都是一个Cordis 事件,任何插件都能在流水线上插一脚:

设计精髓:工具自己不管"能不能调",只管"怎么干活"。安全策略在流水线上。

4.5 TOOL_RUNTIME_SCHEDULER:决策与执行分离

第 3 章的 tool-calls.ts 里出现了一个常量 TOOL_RUNTIME_SCHEDULER:

ctx.provide(TOOL_RUNTIME_SCHEDULER, { prepare(exec) // 进入流水线(跑 pre-execute),返回 dispatch / post-result / final-result dispatch(prepared) // 真正执行工具函数 finalize(exec, result) // 结果后处理 finish(exec, result) // 直接收尾})
const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)switch (prepared.kind) { case 'dispatch': promise = ctx.tools[TOOL_RUNTIME_SCHEDULER].dispatch(prepared.exec) case 'post-result': case 'final-result':}

为什么要套这一层?prepare() 里跑了 pre-execute 瀑布——监听器可能直接给出结果("被策略拦下了"),此时根本不需要执行工具。

4.6 执行模式:并行还是串行?

defineTool({ ..., isConcurrencySafe: true, // 如 read_file:可并行 // 默认 false:如 bash:必须串行})

为什么"可并行"要工具自己声明?

  1. 读文件可以并行,写文件不能——只有工具作者知道语义
  2. 猜错了后果严重:两个并行 bash 都改环境变量,结果不可预测
  3. 声明是"契约",调度器按契约执行

4.7 作用域隔离

ctx.tools.register(tool, { scope: agentId }) // 只给这个 agent 注册ctx.tools.register(tool) // 全局注册

主 agent 能调"创建子任务",子 agent 只能调"读写文件"——最小权限在 agent 世界落地。

4.8 Python 对照:带流水线和并发声明的工具系统

class ToolRuntime: def __init__(self): self.tools = {} self.pre_execute_hooks = [] def register(self, tool_def: dict, scope: str = ”*”): self.tools[(scope, tool_def[”name”])] = tool_def def get(self, scope: str, name: str): return self.tools.get((scope, name)) or self.tools.get((”*”, name)) def add_pre_execute_hook(self, hook): self.pre_execute_hooks.append(hook) async def prepare(self, scope: str, name: str, args: dict): tool = self.get(scope, name) if not tool: return {”kind”: ”rejected”, ”reason”: ”tool not found”} for hook in self.pre_execute_hooks: decision = hook(name, args) if decision: return {”kind”: ”rejected”, ”reason”: decision} return {”kind”: ”dispatch”, ”tool”: tool} async def dispatch(self, prepared, args: dict): return prepared[”tool”][”execute”](args) def define_tool(runtime: ToolRuntime, name: str, description: str, parameters: dict, concurrency_safe: bool = False, scope: str = ”*”): def decorator(func): def execute(args: dict): for key, spec in parameters.get(”properties”, {}).items(): if spec.get(”required”) and key not in args: raise ValueError(f”缺少参数: {key}”) return func(**args) runtime.register({ ”name”: name, ”description”: description, ”parameters”: parameters, ”execute”: execute, ”concurrency_safe”: concurrency_safe, }, scope) return func return decorator rt = ToolRuntime() @define_tool(rt, ”read_file”, ”读取文件(可并行)”, {”type”: ”object”, ”properties”: {”path”: {”type”: ”string”, ”required”: True}}}, concurrency_safe=True)def read_file(path: str): return f”[内容] {path}” @define_tool(rt, ”delete_file”, ”删除文件(危险)”, {”type”: ”object”, ”properties”: {”path”: {”type”: ”string”, ”required”: True}}})def delete_file(path: str): return f”[已删除] {path}” rt.add_pre_execute_hook(lambda name, args: f”禁止执行 {name}” if name == ”delete_file” else None) import asyncioasync def main(): print(”决策:”, await rt.prepare(”*”, ”delete_file”, {”path”: ”/etc/passwd”})) prepared = await rt.prepare(”*”, ”read_file”, {”path”: ”a.py”}) print(”执行:”, await rt.dispatch(prepared, {”path”: ”a.py”})) asyncio.run(main())

对照 dsh 的差距:dsh 的瀑布是带 next() 委托语义的 Cordis 事件;校验是完整 JSON Schema 引擎;scope 是分层作用域。但"决策与执行分离 + 瀑布把关 + 并发声明"三个核心已实现。

4.9 本章小结


第 5 章 提示词组装:从字符串拼接到"总装车间"

核心机制:组装/渲染分离、变量后插值、complete 语义、组装瀑布。

5.1 你现在的做法,和它的三个致命伤

system_prompt = f”””你是一个智能助手。当前工作目录:{cwd}可用工具:{”, ”.join(tool_names)}规则:{rules}”””

三个问题:

  1. 顺序靠手排:新增一段提示词要手工决定插在哪
  2. 没有"来源"概念:拼出来的字符串不知道每段来自哪个插件
  3. 改动是整体性的:想换某一段等于重拼整个字符串

dsh 的答案:把"提示词"变成注册表…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/tishicijiqiao/2026082451839.html