Agent Skills for Context Engineering 工具索引深度解析：LLM-as-a-Judge 三类工具的 Schema 设计与落地实战

Agent Skills for Context Engineering 工具索引深度解析LLM-as-a-Judge 三类工具的 Schema 设计与落地实战【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering导读本文以examples/llm-as-judge-skills/tools/index.md为骨架系统讲解 Agent 系统中工具Tool的组织方式、设计模式与选型策略。你将掌握 Evaluation、Research、Orchestration 三大工具类别的完整能力清单与调用场景理解基于 Vercel AI SDK 的tool() Zod Schema execute标准工具结构学会错误响应协议与「新增一个工具」的完整流程并结合仓库内 TypeScript 源码看清 LLM-as-a-Judge 评估工具的真实实现原理。工具在 Agent 系统中的角色为什么需要一个「工具索引」在 LLM-as-a-Judge 示例项目中工具是 Agent 与外部世界交互的接口——模型本身无法打分、搜索、读取网页或调度其他 Agent这些能力全部由显式定义的工具提供。工具索引Tools Index就是这些能力的「总目录」它解决三个核心问题发现性Agent 或开发者能快速找到某个能力属于哪个类别、位于哪个路径契约一致性每个工具都通过 Zod Schema 声明输入/输出保证模型调用与结果解析的类型安全审批与安全索引中的 Approval 列显式标记该操作是否危险、是否需要在执行前获得人工确认。该索引位于 examples/llm-as-judge-skills/tools/index.md按能力域拆分为tools/evaluation/、tools/research/、tools/orchestration/三个子目录每个工具一份 Markdown 规范文档含工具定义代码、输入/输出 Schema、使用示例、实现注意事项同时由src/tools/下的 TypeScript 文件提供可执行实现——形成「文档即规格、源码即事实」的双轨结构。三大工具类别全景能力清单与职责边界工具索引将全部工具划分为三个类别每个类别对应 Agent 工作流中的一个典型阶段Evaluation Tools评估 LLM 输出质量路径examples/llm-as-judge-skills/tools/evaluation/用于衡量 LLM 输出质量是 LLM-as-a-Judge 模式的核心执行层ToolPurpose用途Approval需审批directScore依据准则criteria对回答打分NopairwiseCompare比较两份回答并选出更优者NogenerateRubric生成打分细则rubricNoextractCriteria从任务中抽取评估准则No前三者都有完整的规范文档与源码实现direct-score.md、pairwise-compare.md、generate-rubric.md位于examples/llm-as-judge-skills/tools/evaluation/对应实现为 direct-score.ts、pairwise-compare.ts、generate-rubric.ts。extractCriteria在索引中登记但仓库中未见独立文档与实现文件可推断其定位是作为评估流程前序的「准则抽取」辅助能力。这三个核心工具的分工逻辑值得强调generateRubric负责「建立标准」directScore负责「客观维度的量化打分」pairwiseCompare负责「主观偏好的两两比较」。Eugene Yan 的 LLM-as-a-Judge 研究结论表明直接打分更适合客观准则而成对比较对偏好类判断更可靠——这正是三类工具并存的设计依据详见 README.md 的 Background Research 一节。Research Tools信息收集与加工路径examples/llm-as-judge-skills/tools/research/用于采集与处理外部信息为评估提供证据支撑ToolPurpose用途Approval需审批webSearch搜索网络信息NoreadUrl从 URL 提取正文内容NoextractClaims识别文本中的论断claimNoverifyClaim交叉验证某个论断Nosynthesize综合多方发现No其中webSearch与readUrl具备完整规范文档。webSearch见 web-search.md的输入包含query、maxResults默认 10范围 1–20以及filtersdateRange枚举day/week/month/year/any、sourceType枚举all/news/academic/documentation、excludeDomains域名黑名单输出为带relevanceScore的结果数组。readUrl见 read-url.md则负责「搜完再读」支持contentType提示auto/article/documentation/paper/code以优化不同页面的抽取策略输出按标题层级拆分的sections结构化正文并定义了一套完整错误码URL_NOT_FOUND、ACCESS_DENIED、TIMEOUT、BLOCKED、INVALID_CONTENT、UNSUPPORTED_TYPE。从工作流看webSearch → readUrl → extractClaims → verifyClaim → synthesize构成一条完整的「检索—精读—拆解—验证—综合」证据链为后续评估环节提供可追溯的事实基础。Orchestration Tools多 Agent 工作流管理路径examples/llm-as-judge-skills/tools/orchestration/用于编排多 Agent 协作是复杂任务的调度层ToolPurpose用途Approval需审批delegateToAgent将任务路由给专门 AgentNoparallelExecution并发执行多个任务NowaitForCompletion等待异步任务完成NosynthesizeResults合并多个 Agent 的输出NohandleError处理失败与异常NodelegateToAgent见 delegate-to-agent.md是其中最核心的调度原语输入需指定agentName枚举evaluator/researcher/writer/analyst、task任务描述、contextpreviousOutputs前序输出、documents相关文档、constraints约束条件以及expectedOutputformat与可选的 JSONschema默认timeout为 60000ms。输出携带tokenUsageprompt/completion 分别统计便于跨 Agent 的算力成本核算与审计。其错误码覆盖了AGENT_NOT_FOUND、CONTEXT_TOO_LARGE、INVALID_OUTPUT等典型失败场景。标准工具结构从规范到可执行代码工具索引给出了每个工具应当遵循的统一结构。这是全项目工具设计的基础范式源码中的三个评估工具完全照此实现export const toolName tool({ description: Clear description of what tool does, parameters: z.object({ // Required parameters first requiredParam: z.string().describe(What this parameter is for), // Optional parameters with defaults optionalParam: z.number().default(10) .describe(What this parameter controls) }), // Approval for dangerous operations needsApproval: false, // or true, or function // Strict mode for guaranteed schema compliance strict: true, execute: async (input) { try { const result await performOperation(input); return { success: true, data: result }; } catch (error) { return { success: false, error: { code: error.code ?? UNKNOWN, message: error.message, retryable: isRetryable(error) } }; } }, // Optional: control what model sees toModelOutput: (result) ({ summary: result.data.summary, truncated: result.data.full.length 5000 }) });逐字段拆解其设计意图description这是模型理解工具用途的唯一窗口规范要求写得清晰具体。对比源码可以发现实际描述都包含「何时使用」的提示——例如directScoreTool的描述明确写出「Use for objective evaluations like accuracy, completeness, clarity」引导模型在客观评估场景调用它parameters统一使用 Zod Schema 声明必填参数在前、可选参数用.default()给出默认值每个字段用.describe()补充语义说明。以 direct-score.ts 为例weight字段用z.number().min(0).max(1).default(1)限定取值范围并给出默认权重 1criteria用.min(1)保证至少一个准则needsApproval危险操作如修改数据、触发外部副作用应设为true或传入判断函数。当前三个评估工具均为只读评估故都不需要审批strict开启后保证模型输出严格符合 Schema避免 JSON 解析失败execute核心执行函数遵循「try/catch 包裹 结构化错误返回」模式toModelOutput可选用于裁剪返回给模型的上下文——例如只回传摘要与截断标志避免超长结果撑爆上下文窗口。这与项目 skills/tool-design 中「控制模型可见上下文」的上下文工程原则一脉相承。错误响应模式所有工具的统一失败契约索引同时规定了所有工具必须遵守的错误与结果协议。源码实现严格遵循了这一契约interface ToolError { code: string; // Machine-readable error code message: string; // Human-readable message retryable: boolean; // Whether retry might help details?: object; // Additional context } interface ToolResultT { success: boolean; data?: T; error?: ToolError; metadata: { executionTimeMs: number; [key: string]: any; }; }设计要点在于retryable标志它让上层编排层对应handleError工具能区分「瞬时故障可重试」与「永久失败需换方案」。而metadata.executionTimeMs使每次工具调用都自带耗时审计信息。看真实实现executeDirectScore的 try/catch 分支中direct-score.ts失败时返回success: false并在summary.assessment中写入错误信息、分数清零同时metadata依然带上evaluationTimeMs与criteriaCount——即失败结果也必须符合输出 Schema保证调用方无需为错误路径做特殊类型处理。executePairwiseCompare失败时则回退为winner: TIE、confidence: 0避免调用方收到未定义胜者。源码级纵深三个评估工具的真实实现原理索引中的工具表只是入口真正的评估逻辑在 src/tools/evaluation/ 中。以下结合源码解析每个工具的关键机制。directScore加权评分与链式推理强制executeDirectScore的实现direct-score.ts展示了客观打分的完整链路评分尺解析从rubric.scale中解析最大分parseInt(scale.split(-)[1])系统提示词动态生成1-${maxScore}尺度CoT 强制系统提示词要求模型「先找证据、再按 rubric 打分、给出理由、提一条改进建议」Find specific evidence → Score → Justify → Suggest以链式推理提升评分可靠性权重计算overallScore是各准则得分的算术平均weightedScore则是按权重加权后的分数weightedSum / totalWeight。当权重不均时两者产生差异——测试「should handle multiple weighted criteria」正是据此断言低温采样temperature: 0.3压低随机性保证多次评分结果稳定可复现结构化输出通过 JSON 格式约束直接让模型输出scores与summary含strengths、weaknesses、priorities再经JSON.parse后做二次计算。pairwiseCompare位置交换去偏算法成对比较最经典的问题是位置偏差——模型倾向偏好排在前面的回答。源码在 pairwise-compare.ts 中实现了双程交换去偏算法// First pass: A first, B second const pass1 await evaluatePair(input.responseA, input.responseB, ...); // Second pass: B first, A second const pass2 await evaluatePair(input.responseB, input.responseA, ...); // Map pass2 result back and check consistency const pass2WinnerMapped pass2.winner A ? B : pass2.winner B ? A : TIE; const consistent pass1.winner pass2WinnerMapped; if (consistent) { finalWinner pass1.winner; finalConfidence (pass1.confidence pass2.confidence) / 2; } else { // Inconsistent - return tie with lower confidence finalWinner TIE; finalConfidence 0.5; }算法要点有三一致性检测两轮结果方向一致才确认胜者不一致则判定为TIE并强制将置信度降为 0.5逐准则合并每个准则的胜者在两轮中不一致时该准则降级为TIE只有两轮同向的准则才被保留为有效差异differentiators偏置感知提示系统提示词显式要求「不要因为回答更长而偏好它」「不要因位置先/后而偏好」从提示层面双重抑制偏差。系统提示词还根据allowTie动态调整「Ties are acceptable when responses are genuinely equivalent」或「You must choose a winner」让平局策略可配置。generateRubric动态生成一致化评分细则executeGenerateRubricgenerate-rubric.ts通过strictness三档lenient/balanced/strict控制标准松紧系统提示词会逐档解释定义lenient 降低及格门槛、strict 高标严评。输出包含每个分值档位的label/description/characteristics/example、通用scoringGuidelines、以及edgeCases边界情况处理建议。scale支持1-3/1-5/1-10温度略高0.4以保留生成多样性。规范文档还内置了 Factual Accuracy、Clarity、Completeness 三套 1-5 档位的现成模板见 generate-rubric.md 的 Rubric Templates 一节可直接复制使用。EvaluatorAgent工具的组合封装层三个工具通过 evaluator.ts 中的EvaluatorAgent类聚合为高层 APIscore()/compare()/generateRubric()三个方法直接透传各执行函数此外还提供两个组合能力evaluateWithGeneratedRubric()先并行为每个准则生成 rubric再把生成的levelDescriptions拼回评分调用——演示了「先建标准、再按标准打分」的完整闭环工作流chat()以评估者角色Be objective, specific, and constructive进行自由对话式评估。Agent 构造函数默认model与temperature取自全局配置config.openai.model默认温度 0.3也支持传入EvaluatorAgentConfig覆盖便于针对不同评估任务调参。运行环境方面模型与密钥通过.env注入见 src/config/index.ts读取OPENAI_API_KEY与OPENAI_MODEL默认gpt-4o并提供validateConfig()在缺失 API Key 时抛出明确错误提示。新增一个工具五步标准流程索引明确了向本系统添加新工具的操作步骤结合仓库结构可拆解为确定类别归属现有类别则放入tools/category/否则新建类别目录创建工具文件在tools/category/tool-name.md编写规范文档定义五要素用途与描述、Zod 输入 Schema、输出 Schema、错误码、使用示例——这正是每个工具 md 文档的标准章节结构更新本索引将新工具登记进tools/index.md对应类别的表格含 Tool、Purpose、Approval 三列分配给相关 Agent在agents/下的 Agent 文档中声明该工具归哪个 Agent 使用。若按源码实现路径扩展还需要在src/tools/category/tool-name.ts中实现execute并通过src/tools/category/index.ts导出README 的 Development 一节有完整说明这与文档层的五步流程一一对应。值得注意的是索引中的extractCriteria、parallelExecution、waitForCompletion、synthesizeResults、handleError、extractClaims、verifyClaim、synthesize等工具目前仅有索引登记或部分文档尚无独立实现文件——这说明该索引既覆盖了已实现能力也作为待建能力的规划清单存在。工具选择指南按需调用而非全量暴露索引最后给出了一张按动作选工具的速查表这是 Agent 提示工程中「最小工具面」原则的具体化ActionAgent 需要Tool CategorySuggested Tools建议工具Assess quality评估质量EvaluationdirectScore, pairwiseCompareFind information查找信息ResearchwebSearch, readUrlVerify facts核实事实ResearchverifyClaim, extractClaimsCoordinate work协调工作OrchestrationdelegateToAgentWait for results等待结果OrchestrationwaitForCompletion使用建议不要把所有工具一次性暴露给模型——工具越多模型误选与上下文开销越大。应根据当前任务阶段动态注入对应类别评估阶段挂载 Evaluation 三件套研究阶段挂载 Research 工具链多 Agent 场景再叠加 Orchestration 原语。这与项目 skills/tool-design 倡导的「工具描述要精确、参数要有默认值、错误要结构化」一脉相承。总结tools/index.md是 LLM-as-a-Judge 示例项目的工具总纲三大类别Evaluation / Research / Orchestration定义了能力边界tool() Zod Schema execute的统一结构保证了工具契约的一致性ToolError/ToolResult协议让失败可识别、可重试、可审计。配合src/tools/evaluation/下的源码你可以看到从「文档规格」到「可执行实现」的完整映射——包括 CoT 强制的客观打分、位置交换去偏的成对比较、三档严格度的动态 rubric以及EvaluatorAgent对三者的组合编排。这套「索引—规范文档—TypeScript 实现—测试验证」的四层结构是构建生产级 Agent 工具库可直接复用的参考范式。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考