DeepSeek Harness 源码解析 · 第 10 讲
DeepSeek Harness 源码解析系列 第 10 讲：工具注册表与执行管道 基于 DeepSeek Harness 源码 · 2026-08-25 一、本节概述 前几讲我们拆解了 Agent Loop 的核心循环、工具调用调度器、运行时上下文和不变量检查。本节深入到整个框架的 工具基础设施 —— ToolRuntime 服务。它是所有工具注册、发现、调度、策略钩子和结果归一化的统一入口，源码位于 packages/core/tools/ ，是整个 Harness 最复杂的包之一： tools 包文件结构 🔹 index.ts （1946 行）— ToolRuntime 核心：注册、作用域链、执行管道、策略钩子 🔹 schema.ts （617 行）— ToolDefinition 类型、defineTool 工厂、参数/输出 JSON Schema 🔹 code-mode.ts （673 行）— run_code 传输层、SDK 渲染、语言感知描述 🔹 types.ts （136 行）— 内部类型声明与导出 二、ToolDefinition：工具声明的完整契约 一个工具在 Harness 中不是一个简单的函数，而是一个 完整的声明式契约 。先看 ToolDefinition 接口： 📄 packages/core/tools/src/schema.ts（第 413-441 行） /** One tool's complete declaration. */ export interface ToolDefinition { /** Tool name (unique in its registration scope). */ readonly name: string // ↑ 工具名称，在其注册的作用域内必须唯一。全局作用域和每个 Agent 作用域各自维护一个唯一约束 /** Human-readable description sent to the model. */ readonly description: string // ↑ 面向模型的描述文本，会出现在系统提示词中，帮助模型理解这个工具做什么 /** JSON Schema for the tool's parameters. */ readonly parameters: Record<string, unknown> // ↑ 参数的 JSON Schema 对象，运行时用来验证模型传入的参数是否合法 /** Output schema and rendering pipeline. */ readonly output: { /** Schema enforced against every successful body return value. */ readonly schema: Record<string, unknown> // ↑ 输出值的 JSON Schema，工具执行返回后必须通过此 Schema 校验 /** Pure function: validated canonical value → Native content blocks. */ readonly render(args: unknown, value: JsonValue): ContentBlock[] // ↑ 纯函数：将校验后的规范值渲染为模型可见的 ContentBlock 数组（文本、图片等） /** Optional: pure replayable presentation metadata for direct top-level calls. */ readonly presentationMeta?(args: unknown, value: JsonValue): JsonValue // ↑ 可选的展示元数据，仅在顶层直接调用时生成，用于 UI 卡片展示 } /** Optional cooperative timeout budget in milliseconds. */ readonly timeoutMs?: number // ↑ 可选的超时预算，毫秒级。工具执行超过此时间会被取消 /** Whether this call …