DeepSeek Harness 源码深潜（二）：工具系统、提示词组装与插件内核全解析

在 Agent 系统的工程实践中，如何让 AI Agent 真正“能干活、可替换、可扩展”，是每个开发者都需要面对的核心挑战。上篇我们已经拆解了 Agent 的心脏——事件溯源的日志系统与状态机，本篇将深入探讨让 Agent 具备实际执行能力的三大支柱：工具系统、提示词组装与插件内核。这三部分共同构成了 Agent 与外部世界交互的基础设施。

声明式定义与自动校验

【第4章：工具系统——Function Calling 的工业级实现】 传统的 Function Calling 实现往往止步于简单的 dispatch 函数：定义工具列表，手写 if-else 匹配参数。这种方式的缺陷显而易见——类型校验靠人工、安全检查靠自觉、调用记录靠运气。一旦系统规模扩大，这些“技术债”就会成为维护的噩梦。 DSH 采用了截然不同的设计思路：通过 defineTool 实现声明式定义，配合 schema 自动校验，再配合五段执行流水线，让工具调用变得可控、可观测、可扩展。

五段执行流水线

defineTool 的核心在于将参数校验与业务逻辑分离。在 defineTool 的实现中，用户的 execute 函数永远被包装在参数校验之后——只有当 JSON Schema 校验通过时，真正的业务逻辑才会被执行。这种设计带来了几个关键优势： 首先，类型安全得到了保障。以 tool-bash 为例，其参数包含 command、description（必填，用于审计追溯）、timeoutMs、workdir 等字段，通过 JSON Schema 约束后，任何类型错误或缺失参数都会在执行前被捕获。其次，业务层校验仍然可以存在——JSON Schema 无法表达“字段A与字段B必须同时出现”这种跨字段约束，这时候业务校验函数就派上了用场。 更精妙的是工具描述的动态生成机制。bashDescription 函数会根据当前沙箱模式和后台执行可用性，动态生成工具的使用说明。这意味着当执行环境变化时，模型看到的工具说明也会相应更新，真正做到了环境自描述。

执行模式与作用域隔离

DSH 的工具执行被设计为一条精心编排的流水线：pre-execute → execute → post-execute → result。每一个阶段都是一个 Cordis 事件，任何插件都可以在流水线上“插一脚”。 pre-execute 阶段采用 waterfall 语义——监听器必须显式调用 next() 才能放行，这意味着安全插件可以在这里拦截危险操作。execute 阶段由 TOOL_RUNTIME_SCHEDULER 调度分发，post-execute 负责结果后处理，result 阶段则用于观测记录。这种设计将“能不能调”与“怎么干活”彻底分离——工具本身只关心业务逻辑，安全策略全部交给流水线上的插件处理。 TOOL_RUNTIME_SCHEDULER 还承担着决策与执行分离的职责。prepare() 方法会触发 pre-execute 瀑布，如果监听器直接返回结果（如“被策略拦截”），工具函数根本不会被调用，从而避免了不必要的资源消耗。

插件内核与能力缝设计

【第5章：提示词组装——从字符串拼接到模块化工厂】 提示词工程在 Agent 系统中扮演着“灵魂塑造者”的角色——它决定了模型如何理解任务、如何调用工具、如何输出结果。但大多数系统的提示词管理还停留在“字符串拼接”阶段，这种方式的弊端同样明显：新增提示词片段需要手工决定插入位置、无法追踪每段内容的来源、修改任意片段都会影响整体。 DSH 将提示词管理从字符串操作升级为“注册表+总装线”模式。通过 PromptSection 注册表，每个插件只需声明自己的片段（名称、排序权重、内容），组装阶段框架负责排序、拼接与冲突检测。这种设计带来了两个关键变化：插件之间解耦了——每个插件只知道自己贡献了什么，不知道也不关心其他插件的存在；组装与渲染分离了——assemble 产生结构化的 PromptAssembly，render 才将其变成最终的字符串。 PromptAssembly 是四路输入的“总装产物”：sections（静态/半静态规则）、contexts（动态上下文，每次请求现算）、tools（工具 schema，组装时排序）、variables（模板变量，渲染时才插值

如有侵权，请联系删除。