数据截至 (上游 commit 676a0a228882)
DeepSeek Provider 与扩展面(MCP/Skills/Plugins)
30 秒导读: 一个 AI agent 有两条边界。一条朝模型:怎么把用户的历史消息发给 DeepSeek、怎么把它吐回来的 token 流接住并翻译成 Whale 内部能用的事件。另一条朝外部世界:怎么让第三方给 Whale 加新工具、新技能、新行为。这章讲透这两条边界——DeepSeek Provider 和四个扩展口(MCP / Skills / Plugins / Hooks)。
本章处在整套讲解的"下游"和"侧翼"。回合循环(见 01-turn-loop.md)是主干,提示词缓存(见 02-prompt-cache-memory.md)是招牌,工具系统(见 03-tools-and-edit.md)是手脚。这一章讲的是:手脚从哪来(扩展面) 以及 主干靠什么驱动(Provider 事件)。
1. 这是什么(零基础也能懂)
1.1 两条边界,一个比喻
把 Whale 想成一家餐厅的后厨总管:
- 朝厨师那条边界(Provider):总管要跟主厨(DeepSeek 大模型)沟通——把订单(对话历史)递过去,再把主厨一句一句报出来的菜名(流式 token)接住、听懂、转成后厨看板上的条目。主厨有时报到一半噎住了(网络断流),总管得决定重报还是放弃。
- 朝 供应商那条边界(扩展面):总管不可能什么都自己做。需要新食材、新设备时,他对接外部供应商(MCP server / Skills / Plugins),把它们的能力"挂进"后厨。供应商有 1000 种设备目录,但总管不会把整本目录堆在操作台上——要用哪个,现查现取。
1.2 它解决什么问题
| 边界 | 要解决的问题 |
|---|---|
| Provider | 大模型的 HTTP/SSE 协议、流式解析、断流重试、推理内容、多模态附件——这些又脏又杂的活,不能污染 agent 主循环 |
| 扩展面 | agent 内置工具永远不够用;要让用户/第三方安全地加工具、加技能、加生命周期钩子,而不改 Whale 源码 |
1.3 一句话直觉
Provider 是"翻译官 + 收发室": 把 Whale 的统一消息模型翻成 DeepSeek 的 JSON,把 DeepSeek 的 SSE token 流翻回 Whale 的
ProviderEvent。扩展面是"插座": MCP、Skills、Plugins、Hooks 是四种不同规格的插座,外部能力插上就能用;其中 MCP 这个插座还带一个"目录检索开关"(
tool_search),不用把上千个工具一次性通电。
本节不出现代码。目标:知道这一章在讲哪两件事。
2. 顶层全 景(它大概怎么转)
2.1 一张图:两条边界
先说怎么读这张图:中间是 Whale 主循环,左边是它跟 DeepSeek 的对话(Provider),右边是四种扩展口。数据流是双向的——历史出去,事件回来;工具挂进来,调用出去。
┌───────────────────────────────────────┐
│ Whale 回合循环 (agent) │
│ (见 01-turn-loop:主线在这) │
└───────────────────────────────────────┘
历史 msgs ↑↓ ProviderEvent 工具目录 ↑↓ 工具调用
┌───────────────────────────┐ ┌──────────────────────────────────┐
│ Provider 边界 (朝模型) │ │ 扩展面 (朝外部世界) │
│ │ │ │
│ DeepSeek Client │ │ ① MCP stdio/http server │
│ ├ StreamResponse (SSE) │ │ └ 1000+ 工具 → tool_search │
│ ├ StreamRespWithPrefix │ │ 延迟检索(不全塞上下文) │
│ │ (/beta 前缀补全) │ │ ② Skills SKILL.md 说明书 │
│ ├ streamWithRetries │ │ (只加载、不执行) │
│ │ (重试 + 错误分类) │ │ ③ Plugins 运行时装能力 │
│ └ multimodal (图/PDF/音) │ │ (tools/skills/hooks/mcp...) │
│ │ │ ④ Hooks 生命周期钩子 │
│ ↓ HTTPS │ │ (PreToolUse/Stop/...) │
│ api.deepseek.com │ │ │
└───────────────────────────┘ └──────────────────────────────────┘
2.2 部件一句话职责
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
deepseek.Client | 跟 DeepSeek 对话的全部逻辑:请求组装、SSE 解析、重试 | internal/llm/deepseek/client.go:35 |
ProviderEvent / ProviderResponse | Provider 与主循环之间的统一事件契约 | internal/llm/provider.go:52 |
retry.Policy | 与 Provider 无关的通用重试策略(退避、Retry-After) | internal/llm/retry/retry.go:16 |
MCP Manager | 连接 MCP server、发现工具、按名调用 | internal/mcp/manager.go:34 |
DeferredToolCatalog | 上千 MCP 工具的可搜索目录(不进上下文) | internal/mcp/deferred.go:26 |
tool_search 工具 | 模型按需检索并"激活"延迟工具 | internal/tools/catalog_mcp.go:47 |
skills 包 | 发现/解析本地 SKILL.md 说明书 | internal/skills/skills.go:27 |
plugins.Manager | 运行时聚合插件贡献的各类能力 | internal/plugins/plugin.go |
HookRunner | 在生命周期各点跑用户配置的钩子 | internal/agent/hooks.go:357 |
2.3 主线走一遍(高层)
一个回合里,这两条边界这样协作:
- 主循环把
[]core.Message历史交给Client.StreamResponse。 - Client 把历史翻成 DeepSeek 的 messages JSON,POST 到
/chat/completions,拿到 SSE 流。 - Client 边读边把每个 delta 翻成
ProviderEvent(内容/推理/工具参数/完成…)喂回主循环。 - 主循环发现模型要调工具。若是 MCP 延迟工具,先前模型已用
tool_search把它激活;调用经 MCPManager转发到对应 server。 - 工具执行前后,
HookRunner在PreToolUse/PostToolUse等点插入用户钩子。
Provider 事件如何逐帧驱动主循环,是 01-turn-loop.md 的内容;这里只讲事件怎么产生。
3. Provider:怎么跟 DeepSeek 对话
这一节由浅入深讲清朝模型那条边界。
3.1 统一契约:ProviderEvent
要解决的小问题: 主循环不该知道"DeepSeek 的 SSE 帧长什么样"。它只想收到一串语义清晰的事件。
Whale 的做法是定义一套与厂商无关的事件类型,任何 Provider 都产出它们:
| 事件 | 含义 |
|---|---|
EventContentDelta | 又来一小段可见回答文本 |
EventReasoningDelta | 又来一小段"思考"内容(reasoning) |
EventToolArgsDelta | 某个工具调用的参数又流来一段 |
EventToolUseStart / EventToolUseStop | 工具调用开始 / 全部结束 |
EventRetryScheduled | 断流了,已排定重试 |
EventComplete | 本轮结束,带完整 ProviderResponse |
EventError | 出错 |
事件类型定义在 internal/llm/provider.go:15,ProviderEvent 结构体在 provider.go:52,收尾的 ProviderResponse(含内容、工具调用、Usage)在 provider.go:63。
Provider 的接口本身极窄——只有一个方法:
// internal/llm/provider.go:72 # 真实源码
type Provider interface {
StreamResponse(ctx context.Context, history []core.Message, tools []core.Tool) <-chan ProviderEvent
}
返回一个事件 channel,主循环 range 它即可。可选的 PrefixCompletionProvider(provider.go:76)多一个前缀补全方法,DeepSeek 客户端两个都实现。
3.2 Option 家族:怎么配置一个 Client
思路: 用函数式选项(functional options)。New(opts ...Option) 逐个应用,默认值来自 defaults 包。
| Option | 作用 | 定义 |
|---|---|---|
WithModel | 选模型 | client.go:70 |
WithReasoningEffort | 推理力度(low/medium/high…) | client.go:78 |
WithThinking | 是否开启"思考"模式 | client.go:82 |
WithMaxTokens | 输出上限 | client.go:86 |
WithPrefixCompletion | 允许隐式前缀补全(见 3.4) | client.go:90 |
WithMultimodal | 配置多模态旁路(见 3.6) | client.go:94 |
WithThinking 一开,请求体里 thinking 从 {"type":"disabled"} 翻成 {"type":"enabled"},并带上 reasoning_effort(client.go:215-220)。这时 DeepSeek 会额外流回 reasoning_content,被翻成 EventReasoningDelta。
3.3 核心:SSE 流式解析
要解决的小问题: DeepSeek 用 Server-Sent Events(SSE,服务器逐行推送的长连接)一段段吐 token。要把这条字节流,实时切成一个个 ProviderEvent。
思路,分三层:
StreamResponse(client.go:180)起一个 goroutine,把错误也包成事件塞进 channel。parseSSE(client.go:575)逐行读,遇到data:行就攒着,遇到空行就把攒的一帧交给parseSSEData。parseSSEData(client.go:691)解一帧 JSON,按 delta 里有什么,发对应事件。
原理演示(把核心想法演出来):
# 示意,非源码:SSE 帧 → 事件
acc = Accumulator() # 累加器:攒完整内容 / 工具参数
for frame in sse_frames(response): # 逐帧
delta = frame["choices"][0]["delta"]
if delta.get("content"):
acc.content += delta["content"]
emit(ContentDelta(delta["content"])) # 可见文本
if delta.get("reasoning_content"):
emit(ReasoningDelta(delta["reasoning_content"])) # 思考
for tc in delta.get("tool_calls", []):
acc.tool_args[tc.index] += tc.function.arguments # 工具参数分片流来
emit(ToolArgsDelta(...))
if frame["choices"][0]["finish_reason"] == "tool_calls":
emit(Complete(acc.build())) # 重点看:工具调用参数是"流式拼起来"的
关键细节:
- 工具名归一化。 模型可能报
Bash/Read或它自己发明的别名,进入注册表前统一过core.CanonicalToolName(client.go:764)。 - 工具参数边流边判完整。 每来一段就试着
json.Unmarshal,一旦成为合法 JSON 就标记 ready(looksLikeCompleteJSON,client.go:948),让 UI 能尽早知道"这个工具调用凑齐了"。 - 收尾产出 Usage。
emitComplete(client.go:799)把prompt_cache_hit_tokens等缓存计数、推理重放、工具结果压缩节省等,全打进llm.Usage——这正是 02-prompt-cache-memory.md 观测缓存命中率的数据来源。
3.4 招牌配套:前缀补全(prefix completion)
要解决的小问题: 有时 Whale 想让模型接着一段已经写好的开头往下续——比如 Plan 模式收尾时,已有半句计划,要模型补完。普通 chat 接口做不到"你从这里接着写"。
思路: DeepSeek 的 /beta 端点支持在 messages 末尾塞一条特殊的 assistant 消息,标 prefix: true,模型就会把它当"已经说出口的话"续写下去。
StreamResponseWithPrefix(client.go:191)→ streamPrefix(client.go:236)干这件事,核心两步:
// internal/llm/deepseek/client.go:249 # 真实源码:把前缀塞回去
msgs = append(msgs, map[string]any{
"role": "assistant",
"content": prefix,
"prefix": true,
})
而端点必须切到 /beta,这由 prefixCompletionBaseURL(client.go:319)决定:官方 base URL 或其 /v1 会被改写成 defaultBaseURL + "/beta";非 DeepSeek 端点则回退成普通 stream(client.go:244-247)。补完后 joinPrefixCompletionContent(client.go:333)保证最终内容带上前缀、不重复。
为什么这事关缓存: 前缀补全让 Whale 能"续写"而不是"重开一段",从而保住前缀不变——这正是提示词缓存高命中的前提。前缀补全服务缓存的完整链条,见 02-prompt-cache-memory.md;这里只讲它的机制。 主循环侧的触发条件(opts.PrefixCompletion 且无工具时才走前缀 provider)在 internal/agent/stream_ingest.go:46。
一个易错点值得记:显式传入非空 prefix 时,无视 prefixCompletionEnabled 自动开关——调用方传了 prefix 就是直接选择;那个开关只管"隐式"使用(client.go:237-243 注释)。
3.5 重试与错误分类
这是 Provider 里最见功力的部分:网络会抖、模型偶尔吐空,得分清"重试有用"和"重试白费"。
两层重试。 streamWithRetriesAuth(client.go:344)有两个独立计数:
| 阶段 | 计数 | 说明 |
|---|---|---|
| 发请求 | requestAttempt | 连不上/收到可重试 HTTP 码,走通用 retry.Policy |
| 读流 | streamAttempt | 已连上但流中途断,上限 defaultStreamMaxAttempts = 6(client.go:25) |
通用重试策略在 internal/llm/retry/retry.go:DefaultPolicy(retry.go:52)默认 4 次、指数退避、抖动 0.1;ShouldRetry(retry.go:110)只对 429/500/502/503/504 和网络错重试;Backoff(retry.go:125)优先尊重服务器给的 Retry-After(甚至从响应体里正则抠 retry_after_ms,retry.go:197)。
流错误的三分类,是精华所在。shouldRetryStreamError(client.go:474)要判断一次断流该不该重来:
| 错误类型 | 何时产生 | 可重试? |
|---|---|---|
streamTerminalError{retryable:true} | 模型只思考、没吐正文也没工具调用(reasoning-only 空补全) | ✅ 是 |
streamTerminalError{retryable:false} | 彻底空补全(连思考都没有)——多半是坏流 | ❌ 否 |
streamProgressError | 已经吐出过内容才断——重来会重复输出 | ❌ 否 |
streamStallError | 空闲超过 defaultStreamIdleTimeout = 90s(client.go:26)无输出 | ✅ 是(除非 ctx 取消) |
为什么 reasoning-only 空补全可以安全重发?emitComplete(client.go:810-814)里解释得很清楚:模型思考了但没产出可用内容,没有为输出 token 计费,是 DeepSeek 侧采样波动,重发一次通常就好了;而且 stream-retry 路径会通过 StreamReset 事件清掉已累积的推理/文本,重发不会重复。这个错误被 llm.ErrEmptyCompletion(provider.go:13)包裹,让上层不依赖包内私有类型也能识别。
3.6 多模态旁路
要解决的小问题: DeepSeek 主聊天模型不吃图片。但用户会贴图/PDF/音频。
思路: 检测到最新用户消息带附件(latestUserMessageHasAttachments,multimodal.go:17),就改走一条 OpenAI 兼容的旁路(streamMultimodal,multimodal.go:43)——用单独配置的多模态端点/模型,把附件编码成 OpenAI 格式的 content 分块。图片转 image_url data URL,PDF/文件转 file,音频转 input_audio(encodeOpenAIAttachment,multimodal.go:207)。这条旁路默认关闭,要在配置里显式 enabled = true(multimodal.go:82)。
4. 扩展面①:MCP 与延迟工具搜索
MCP(Model Context Protocol,模型上下文协议)是一个开放标准:第三方进程(server)通过它暴露一批工具,agent 连上去就能调。这是 Whale 最重的扩展口。
4.1 连接一个 MCP server
Manager.Initialize(manager.go:94)并发启动配置里的每个 server。每个 server 走 startServer(manager.go:217):
createTransport(manager.go:389)按传输类型建连接——两种:- stdio:启一个子进程,用它的标准输入输出通信(
sdk.CommandTransport)。 - http:连一个 URL 端点(
StreamableClientTransport),可带鉴权头。
- stdio:启一个子进程,用它的标准输入输出通信(
session.ListTools拉取该 server 的工具清单。- 每个工具记成
discoveredTool,附上允许目录、workspace 根等。
传输类型的判定在 config.go:87 的 transportKind:显式 type/transport 优先,否则有 url 当 http、有 command 当 stdio。
调用时,Manager.CallTool(manager.go:205)按 server 名找到会话,带超时转发 CallTool。
4.2 工具命名:全局唯一且合法
要解决的小问题: 不同 server 可能有同名工具;工具名还得符合模型 API 的字符与长度限制(≤64)。
QualifyToolName(names.go:17)把 (server, tool) 拼成 mcp__<server>__<tool>,非法字符清洗、超长则截断加短哈希。UniqueToolName(names.go:46)再解决碰撞:重名就补哈希后缀。反向解析用 ParseQualifiedToolName(names.go:30)。
4.3 招牌机制:tool_search 延迟工具搜索
要解决的小问题: 一个用户可能挂了十几个 MCP server,合计 1000+ 工具。如果把每个工具的完整 schema 都塞进模型上下文,光工具定义就撑爆窗口、且每回合都得重发——直接打死提示词缓存。
思路(呼应缓存目标): 不把工具全塞进去,只塞一份轻量目录索引;模型需要哪个,用一个特殊工具 tool_search 现查、现"激活"。
怎么读下面这张流程图:从上到下是一次按需取用,左边是模型看到的东西,右边是幕后目录。
模型上下文里只有: 幕后(不进上下文):
┌────────────────────────┐ ┌──────────────────────────┐
│ <available-deferred- │ │ DeferredToolCatalog │
│ tools> 每个 server │ ← 一行摘要 │ 1000+ 条 {name,server, │
│ 下列工具名 + 一句描述 │ │ description} │
│ + 一个 tool_search 工具 │ └──────────────────────────┘
└────────────────────────┘ ↑ Search(query)
│ 模型:"我需要 github 搜代码" │
│ 调用 tool_search("+github search") │
▼ │
catalog.Search → 最多 5 条命中 ─────────────────┘
│ promote(names)
▼
BuildTools:把这几个工具的完整 schema 加进注册表
│
▼
返回"已激活 N 个工具",后续回合可直接调
目录只存轻量元数据。 DeferredToolMeta(deferred.go:19)每条只有名字、server、一行描述;DeferredToolCatalog(deferred.go:26)是不可变、可搜索的集合,还算了内容哈希用于版本校验。
三种查询语法。 Search(deferred.go:97)支持:
| 语法 | 含义 | 实现 |
|---|---|---|
select:NameA,NameB | 按精确限定名取 | selectSearch deferred.go:117 |
+must_have extras | 名字必须含 must_have,extras 加分排序 | mustHaveSearch deferred.go:140 |
keyword phrase | 名字/描述上的大小写不敏感正则 | regexSearch deferred.go:184 |
三者都最多返回 5 条(maxSearchResults = 5,deferred.go:13),按相关性排序——名字命中(2 分)高于描述命中(1 分)。正则若语法非法,自动降级成字面量匹配(compileCatalogRegex,deferred.go:217)。
激活 = promote。 tool_search 工具(NewToolSearchTool,catalog_mcp.go:47)拿到命中名字后调 promote,后者经 Manager.BuildTools(manager.go:340)按同一套确定性排序重建这几个工具的完整对象、加进注册表,并把 schema 渲染回给模型(catalog_mcp.go:154-166)。之后这些工具就"在你的工具 schema 里"了。
为什么这保护缓存: 目录索引是稳定前缀的一部分,基本不变;激活发生在对话后段,不动前面——契合 02-prompt-cache-memory.md 讲的"把变化推到上下文末尾"。给模型看的清单由 RenderAvailableDeferredTools(deferred.go:245)渲染成 <available-deferred-tools> 块,按 server 分组。
app 层怎么接: refreshMCPTools(internal/app/mcp_runtime.go:45)在 MCP 初始化后 BuildDeferredCatalog,通过 mcpCatalogAdapter(mcp_runtime.go:69)把 mcp 包的目录适配成 tools 包要的接口;激活过的工具还会被持久化,重启后 RestorePromotedTools 恢复(mcp_runtime.go:34)。
5. 扩展面②③④:Skills / Plugins / Hooks
5.1 Skills:只加载、不执行的说明书
它是什么: 一个 Skill 就是一份 SKILL.md——带 frontmatter(名字、描述、可选 requires)加一段自然语言指令。它教模型"遇到某类任务该怎么做",本身不是可执行代码。
发现: skills 包扫描一组根目录——工作区的 .whale/skills、.agents/skills,以及 home 下同名目录(DefaultRoots,skills.go:109)。每个 Skill(skills.go:27)解析出 Instructions;Requires(skills.go:38)可声明依赖的命令/环境变量/MCP,用于标注"需要 setup"。
加载: 模型调 loadSkill 工具(internal/tools/skills.go:12)时,Whale 校验名字合法、未被禁用、存在,然后把说明书正文(必要时截断)连同 setup 状态返回。返回体里明确写着 "execution": "not_executed" 和用法提示:"这个工具只加载技能说明,不执行脚本、不改文件"(tools/skills.go:80-81)。安全边界很清楚——skill 是给模型看的提示,不是自动执行的动作。这与 04-safety-permissions.md 的权限观一致。
5.2 Plugins:运行时装配的能力包
它是什么: 插件是能一次性贡献多种能力的包。internal/plugins/ 共 7 个文件,核心是 plugin.go(接口与 Manager)、local.go(本地安装/加载)、local_components.go(组件解析),外加两个内置插件目录 memoryplugin/、skillsimprover/。
能力是"按接口选配"的。 一个插件实现哪些 provider 接口,就贡献哪类能力(plugin.go:108 起):
| 接口 | 贡献 |
|---|---|
ToolProvider | 额外工具 |
SkillProvider | 额外技能 |
MCPProvider | 额外 MCP server 配置 |
HookProvider / CommandHookProvider | 生命周期钩子 |
SlashCommandProvider | 斜 杠命令 |
StartupContextProvider | 启动时注入的上下文 |
plugins.Manager(plugin.go:291)加载所有启用插件后,用 Tools()/Skills()/MCPServers()/Hooks()(plugin.go:519 起)把各家贡献聚合起来,交给主程序。每个插件在 manifest 里声明 Capabilities 与 Permissions(plugin.go:20-40)——比如要读写工作区、跑后台任务,都是显式授权。
5.3 Hooks:生命周期钩子
它是什么: 在 Whale 运行的关键节点插入用户自定义逻辑。事件清单在 HookEvents(internal/agent/hooks.go:53):
| 事件 | 触发点 |
|---|---|
PreToolUse / PostToolUse | 工具执行前 / 后 |
PermissionRequest | 请求权限时 |
PreCompact / PostCompact | 上下文压缩前 / 后 |
SessionStart / UserPromptSubmit | 会话开始 / 用户提交 |
SubagentStart / SubagentStop | 子代理起 / 止(见 05-subagents-workflows.md) |
Stop | Whale 结束本回合前 |
四种钩子类型,一套决策模型。 钩子可以是 command(跑 shell)、http(POST 到 URL)、prompt、agent(runResolvedHook,hooks.go:574)。跑完得到一个 HookDecision(hooks.go:264):pass / warn / block / halt。
关键在于谁能拦。 isBlockingEvent(hooks.go:1428)规定只有 PreToolUse、PermissionRequest、UserPromptSubmit、SubagentStart 这几个"事前"事件能真正 block;事后事件即使返回 block 也被降级成 warn(normalizeHookDecision,hooks.go:1334)。命令钩子的退出码约定很简洁:
// internal/agent/hooks.go:1432 # 真实源码:退出码 → 决策
func decideHookOutcome(event HookEvent, res HookSpawnResult) HookDecision {
if res.SpawnErr != nil { return HookDecisionError }
if res.TimedOut { return HookDecisionTimeout }
if res.ExitCode == 0 { return HookDecisionPass }
if res.ExitCode == 2 && isBlockingEvent(event) { return HookDecisionBlock } // 退出码 2 = 拦截
return HookDecisionWarn
}
信任模型。 钩子来自 .whale/config.toml 等文件(LoadHooks,hooks.go:826)。项目级钩子首次出现是 Untrusted,要显式信任;内容一改哈希变了就回到 Modified,需重新信任(hookTrustForEntry,hooks.go:1035)。这防止仓库里夹带的钩子 未经用户同意就跑——与 04-safety-permissions.md 的信任边界呼应。
6. 巧妙之处(可带走的技术)
- 窄接口 + 事件 channel 解耦 Provider。
Provider只有一个StreamResponse方法返回 channel(provider.go:72)——换任何模型厂商,主循环一行不用改。可选能力(前缀补全)用第二个接口表达(provider.go:76),按类型断言探测,避免污染主接口。 - 空补全的"可重试"判定基于计费语义。 区分 reasoning-only(没为输出计费,重发安全)与彻底空(坏流,重发无益),不是拍脑袋,而是从"有没有产出、有没有计费"推导(
client.go:810、shouldRetryStreamErrorclient.go:474)。 - 延迟工具:目录进上下文、schema 不进。 用一份 5 条上限的可搜索索引 + 一个
tool_search工具,把 1000+ 工具的上下文成本压到近乎常量,还保住了缓存前缀(deferred.go:97、catalog_mcp.go:47)。 - 前缀补全走 /beta 且能优雅回退。 只有官方端点改写到
/beta,别的端点自动退回普通流(client.go:319、244),扩展能力不牺牲兼容性。 - 重试延迟会读服务器意图。 不只指数退避,还解析
Retry-After头、甚至从错误响应体正则抠出建议等待(retry.go:173、197),对齐服务端限流。 - 钩子拦截权限按事件收窄。 只有事前事件能真拦,事后 block 降级为 warn(
hooks.go:1334),避免"事已成再拦"的语义混乱。
7. 边界与局限(诚实)
- 单一厂商实现。 仓库里
llm/下只有deepseek一个具体 Provider;接口虽通用,但目前没有第二家实现来印证抽象是否够宽(基于本次所读代码)。 - 多模态是旁路、默认关闭。 主聊天模型不吃图,附件必须配一个独立的 OpenAI 兼容端点才行(
multimodal.go:82);未配就直接报错。 - 前缀补全依赖 DeepSeek
/beta。 非 DeepSeek base URL 一律回退成普通流,拿不到"续写已有 assistant 前缀"这个能力(client.go:319)。 - MCP 工具全靠 server 存活。
CallTool要求会话已连接,server 崩了调用即失败(manager.go:209);npx/npm 启动的 stdio server 还有"下载/占用 stdio 导致启动超时"的坑,代码专门给了提示(startupHint,manager.go:775)。 - Skill 只加载不执行。 想让 skill 里的脚本真正跑起来,得靠模型再去调别的工具;
loadSkill本身绝不执行(tools/skills.go:80)。
8. 代码地图(导航索引)
用符号名 grep 比行号更抗漂移(上游更新后行号会变)。
| 主题 | 文件 | 符号 |
|---|---|---|
| DeepSeek 客户端与选项 | internal/llm/deepseek/client.go | Client、New、WithModel、WithThinking、WithPrefixCompletion、WithMultimodal |
| SSE 流式解析 | internal/llm/deepseek/client.go | StreamResponse、parseSSE、parseSSEData、emitComplete |
| 前缀补全 | internal/llm/deepseek/client.go | StreamResponseWithPrefix、streamPrefix、prefixCompletionBaseURL、joinPrefixCompletionContent |
| 重试与流错误分类 | internal/llm/deepseek/client.go | streamWithRetriesAuth、shouldRetryStreamError、streamTerminalError、streamStallError、streamProgressError |
| 通用重试策略 | internal/llm/retry/retry.go | Policy、DefaultPolicy、ShouldRetry、Backoff、retryAfterDelay |
| Provider 契约 | internal/llm/provider.go | Provider、PrefixCompletionProvider、ProviderEvent、ProviderResponse、Usage、ErrEmptyCompletion |
| 多模态旁路 | internal/llm/deepseek/multimodal.go | streamMultimodal、toOpenAICompatibleMessages、encodeOpenAIAttachment |
| MCP 连接与调用 | internal/mcp/manager.go | Manager、Initialize、startServer、createTransport、CallTool、BuildDeferredCatalog、BuildTools |
| MCP 命名 | internal/mcp/names.go | QualifyToolName、ParseQualifiedToolName、UniqueToolName |
| 延迟工具目录 | internal/mcp/deferred.go | DeferredToolCatalog、Search、selectSearch、mustHaveSearch、regexSearch、RenderAvailableDeferredTools |
| tool_search 工具 | internal/tools/catalog_mcp.go | NewToolSearchTool、DeferredToolCatalog(接口)、DeferredToolPromoter |
| app 层接线 | internal/app/mcp_runtime.go | refreshMCPTools、mcpCatalogAdapter、makeDeferredPromoter;internal/app/provider.go newDeepSeekProvider |
| Skills | internal/skills/skills.go / internal/tools/skills.go | Skill、DefaultRoots、Requires;loadSkill |
| Plugins | internal/plugins/plugin.go / local.go | Plugin、Manager、ToolProvider、MCPProvider、HookProvider |
| Hooks | internal/agent/hooks.go | HookEvents、HookRunner、RunHookWithObserver、decideHookOutcome、isBlockingEvent、hookTrustForEntry |