系列:DeepSeek Harness(dsh)源码教程 · 中篇(第 4-7 章) 上篇:从 API 到 Agent 心脏(第 0-3 章) 下篇:模型适配、多 Agent 与 Python 实战(第 8-10 章)
上篇我们拆完了 Agent 的心脏:事件溯源的日志系统、turn/step 状态机、工具调度器。
但心脏只是泵血。中篇进入让 Agent 真正"能干活、可替换、可扩展"的部分:
- 第 4 章:工具系统——function calling 的工业级实现
- 第 5 章:提示词组装——模型看到世界的"总装车间"
- 第 6 章:Cordis 插件内核——dsh 的立身之本
- 第 7 章:能力缝 seam——可替换的能力接口
如果说上篇是骨架,中篇就是肌肉与神经。
第 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)
这个写法的问题:
- 校验靠手写:
get_weather(city=123)这种类型错要自己 if/else - 没有把关:任何人都能调任何工具——
delete_all()被误调谁拦? - 没有流水线:遥测、限流、权限检查要自己塞进 dispatch
- 作用域不分:主 agent 和子 agent 共用同一批工具
- 结果不可追溯:调用结果怎么和日志关联?
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 事件,任何插件都能在流水线上插一脚:
- 安全插件监听
pre-execute:rm -rf /→ 拒绝 - 遥测插件监听
result:统计每次调用的耗时/token - 沙箱插件监听
pre-execute:检查参数是否越权
设计精髓:工具自己不管"能不能调",只管"怎么干活"。安全策略在流水线上。
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:必须串行})
为什么"可并行"要工具自己声明?
- 读文件可以并行,写文件不能——只有工具作者知道语义
- 猜错了后果严重:两个并行 bash 都改环境变量,结果不可预测
- 声明是"契约",调度器按契约执行
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 本章小结
- defineTool = 声明式 schema + 自动校验 + 动态描述
- 五段流水线是事件驱动的,安全策略是插件不是代码
- TOOL_RUNTIME_SCHEDULER 分离"决策"与"执行"
- 并发安全是工具的声明,调度器不猜
- 作用域隔离实现 agent 级最小权限
第 5 章 提示词组装:从字符串拼接到"总装车间"
核心机制:组装/渲染分离、变量后插值、complete 语义、组装瀑布。
5.1 你现在的做法,和它的三个致命伤
system_prompt = f”””你是一个智能助手。当前工作目录:{cwd}可用工具:{”, ”.join(tool_names)}规则:{rules}”””
三个问题:
- 顺序靠手排:新增一段提示词要手工决定插在哪
- 没有"来源"概念:拼出来的字符串不知道每段来自哪个插件
- 改动是整体性的:想换某一段等于重拼整个字符串
dsh 的答案:把"提示词"变成注册表…