craft-agents-oss v0.4.8 版本解析call_llm工具、Skills 插件解析修复与 Codex 事件队列竞态修复【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss本篇文章基于 craft-agents-oss 仓库 apps/electron/resources/release-notes/0.4.8.md 展开系统讲解 v0.4.8代号 LLM Tool Plugin Fix的核心技术内容主 Agent 如何通过新增的call_llm工具调用次级 LLM 完成摘要、分类、结构化提取等聚焦子任务并深入剖析三个后端Claude、Codex、Copilot的接入方式同时逐一拆解本版本修复的三个关键缺陷——Skill 插件名解析、Skill 热重载、Codex 事件队列竞态。读完本文你将掌握call_llm的参数语义、结构化输出机制与附件处理约束并理解其背后的源码实现与测试保障可直接对照仓库源码进行二次开发或排障。call_llm工具为 Agent 注入次级 LLM 调用能力v0.4.8 最核心的新增功能是call_llm工具——一个会话级session-scoped工具允许主 Agent 在运行过程中调用另一个独立的 LLM来处理聚焦型子任务例如摘要summarization对长文本或文件内容做浓缩提炼分类classification判定内容所属类别并给出置信度结构化提取structured extraction从非结构化文本中抽取实体、条目分析与对比analysis / comparison输出发现、问题、建议或对比两段内容的异同。该工具之所以有价值核心在于三条设计动机见 llm-tool.ts 中工具描述原文成本优化简单任务摘要、分类可以指定更小、更便宜的模型避免每次都动用主对话的大模型结构化输出通过后端原生结构化输出能力保证 JSON Schema 合规而非依赖提示词碰运气上下文隔离把子任务内容交给次级 LLM 处理不污染主对话的上下文窗口同时支持并行调用——同一条消息里发起多个call_llm会同时执行。跨后端支持Claude、Codex、Copilot发布说明明确该工具在三个后端全部可用Claude走anthropic-ai/claude-agent-sdkClaudeAgent 实现了queryLlm()与runMiniCompletion()见 claude-agent.tsCodex通过 PreToolUse 拦截器与buildCallLlmRequest共享预处理管线执行Copilot同样经由共享的buildCallLlmRequest管线该函数注释明确写到 Used by PiAgents call_llm intercept path见 llm-tool.ts。在鉴权模式上发布说明区分了两档能力鉴权方式功能范围API Key完整功能full featuresOAuth基础功能basic featuresOAuth 路径下的实现示例可见 claude-agent.ts 附近注释 queryLlm — Agent-native LLM query for call_llm tool (OAuth path)。参数语义与结构化输出call_llm的完整参数由 llm-tool.ts 中的 Zod Schema 定义参数类型说明promptstring必填给次级 LLM 的指令不能为空正文内容应直接放入 prompt不要通过 attachments 传内联文本attachmentsstring 或{path, startLine?, endLine?}数组最多 20 个磁盘上已存在文件的路径工具会自动加载内容大文件可配合行区间截取modelstring可选模型 ID 或短名如haiku、sonnet默认使用快速摘要模型systemPromptstring可选可选的系统提示词maxTokensint 1–64000可选最大输出 token 数默认 4096temperature0–1可选采样温度outputFormat枚举可选预定义输出格式summary/classification/extraction/analysis/comparison/validationoutputSchemaJSON Schema可选自定义结构化输出 Schema结构化输出有两种方式且二者互斥同时传outputFormat与outputSchema会返回错误一是使用outputFormat选择内置格式二是用outputSchema提供自定义 JSON Schema。源码中内置了六套预定义 Schema见 llm-tool.ts例如summary要求返回{ summary, key_points, word_count? }classification要求返回{ category, confidence, reasoning }extraction要求返回{ items, count }analysis要求返回{ findings, issues?, recommendations? }。当传入 Schema 时管线会把 JSON Schema 序列化后注入 system prompt明确要求模型仅返回符合该 Schema 的 JSON、不得附带其他文本或 markdown 格式见 llm-tool.ts同时后端会尽量走原生结构化输出通道。附件与文件加载约束call_llm的附件机制定位是传文件路径、工具自动加载内容。其约束在 processAttachment 中有完整实现格式支持文本文件以及 png/jpg/jpeg/gif/webp 图片但 Codex/Copilot 模式明确拒绝图片附件报错提示 Image attachments are not supported in ... mode. Use text files only.文件大小单个文本文件 ≤ 500KB 或 ≤ 2000 行超出时可改用{path, startLine, endLine}行区间全部附件合计 ≤ 2MB图片 ≤ 5MB路径解析相对路径会基于会话目录sessionPath解析校验能力文件不存在、权限拒绝、损坏的符号链接、目录误传、二进制内容含 null 字节、空文件、行区间非法非正整数、start end、区间超限都会返回带可操作建议的错误信息——例如大文件错误中会附带按 imports/exports/functions/classes/tests/comments/config 分类的文件结构摘要帮助 Agent 选择合适的行区间。执行与超时所有调用最终委托给各后端实现的queryLlm()抽象方法定义见 base-agent.ts。次级调用统一超时时间为120 秒LLM_QUERY_TIMEOUT_MS见 llm-tool.ts通过Promise.race与超时定时器配合、并在完成后清理定时器withTimeout。未配置鉴权时工具返回 No authentication configured for call_llm 的错误提示引导用户先登录 AI 提供商。若结果带warning如 SDK 在 max_turns 处停止返回体前会标注[Partial result — ...]保证部分结果不被静默丢弃。对应的测试覆盖见 packages/shared/src/agent/tests/pi-query-llm.test.tsPiAgent.queryLlm 子进程 RPC 往返、超时、子进程退出时拒绝所有挂起调用与 build-call-llm-request.test.ts。修复一Skill 插件名解析——不再依赖目录名问题当工作区目录名与 SDK 插件名plugin name不一致时Skills 无法被正确解析。根因Claude SDK 识别插件时依据的是.claude-plugin/plugin.json清单中的name字段而不是插件目录的path.basename()。旧实现可能退化为使用目录末段作为插件名一旦目录名与清单中的name不一致skill 的限定名pluginName:skillSlug就会错位导致解析失败。修复新增readPluginName()见 workspace.ts从.claude-plugin/plugin.json读取真实插件名不可读时返回 nullextractWorkspaceSlug()workspace.ts优先使用该真实插件名仅在无清单时回退到路径末段legacy 行为。系统提示词构建system.ts与 skill 限定pre-tool-use.ts均改为使用这一真实名称。测试用例见 workspace-slug.test.ts覆盖 plugin.json 存在且含 name、清单缺失、name 字段缺失、清单为非法 JSON 等四种情形。修复二Skill 热重载——三层列表不再消失问题在工作区中添加一个 skill 后全局global和项目project级 skill 会一起消失直到重启应用。根因部分重载路径只返回了工作区这一层的 skill 列表覆盖替换了原本完整的三层列表。修复所有重载路径统一改用loadAllSkills返回完整三层列表。源码中loadAllSkills(workspaceRoot, projectRoot?)每次调用最多读取三个目录storage.tsWorkspace 层{workspaceRoot}/skills/{slug}/插件名取自 plugin.jsonProject 层{workingDir}/.agents/skills/{slug}/插件名为.agentsGlobal 层~/.agents/skills/{slug}/插件名同样为.agents见 storage.ts 与 pre-tool-use.ts。同名 slug 按 project workspace global 优先级覆盖去重。测试 storage.test.ts 覆盖了完整三层加载、三层同名覆盖、projectRoot 缺省时跳过项目层、跨层去重等场景是热重载后三层列表完整保留这一行为的最佳验证。修复三Codex 事件队列竞态——工具结果不再丢失问题Codex 后端中当异步的item/completed事件处理器仍在运行时turn/completed到达工具结果与助手文本可能丢失。根因事件队列在turn/completed到达时即标记完成未等待仍在飞行中的item/completed处理器收尾导致后到的事件被清空/丢弃。修复将队列的完成推迟到所有处理器执行完毕之后再触发。事件队列的同步机制见 event-queue.tsenqueue()入队并唤醒等待者complete()标记完成只有当队列已清空且完成标记已置位时才真正判定 turn 结束isTurnComplete返回done queue.length 0。保证结果先于完成信号落地避免工具结果和助手文本丢失。内部改进Copilot 后端补全与 UI 徽章本版本还有三项偏内部Internal的改动CopilotrunMiniCompletion现已可用runMiniCompletion(prompt)是各后端共有的抽象方法types.ts、base-agent.ts用于标题生成、摘要等快速文本任务。Claude 侧实现见 claude-agent.ts无工具、空系统提示、单轮、禁用 thinkingPi 侧实现通过子进程 RPCmini_completion消息完成超时同样对齐 120 秒pi-agent.ts。Copilot 后端的runMiniCompletion恢复可用后标题生成功能在 Copilot 后端被激活。Copilot 事件适配器抑制 reasoning/intent 事件避免内部推理/意图事件泄漏到对外事件流中。call_llm模型徽章TurnCard 活动行中新增模型徽章展示TurnCard.tsx当工具名为mcp__session__call_llm且传入model参数时在活动行内以徽章形式显示所用模型TurnCard.tsx让调用次级 LLM 时使用的模型一目了然。总结v0.4.8 是一次功能 稳定性并重的版本call_llm工具为 Agent 带来了低成本、可并行、原生结构化输出的次级 LLM 调用通道并在 Claude / Codex / Copilot 三大后端与 API Key / OAuth 两种鉴权模式下统一落地三个 Bug 修复则分别解决了 Skill 插件名解析、Skill 热重载丢列表、Codex 事件竞态丢结果这三类直接影响日常使用体验的问题。开发者如需深入可重点阅读 llm-tool.ts、workspace.ts、storage.ts 及对应的测试文件源码结构与测试用例可完整还原本版本的每一次行为变更。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考