[Bug] transfer_to_researcher 内置 handoff 工具缺少 provider 配置入口，fallback 到主代理默认模型时静默失败

[Blueteemo]

What happened / 发生了什么

在安排主代理将任务委派给子代理时，主代理的第一反应是调用 transfer_to_researcher——该工具名称直观匹配"研究/调研"类任务。但调用后直接报错：

No available channel for model deepseek-v4-flash

排查发现：

1. transfer_to_researcher 是系统内置的 HandoffTool，不在 subagent_orchestrator 配置体系中
2. 用户无法为其配置 provider_id，Dashboard 中也没有任何配置入口
3. 其 provider_id 为空时，fallback 到主代理的 default_provider_id
4. 当该默认模型通道不可用（如 503）时，工具直接报错不可用
5. 而 subagent_orchestrator 中配置的其他子代理（正确配置了可用的 provider）可以正常工作

Reproduce / 如何复现？

1. 确保主代理的 default_provider_id 指向一个当前不可用的模型通道（如 deepseek-v4-flash 503）
2. 在 subagent_orchestrator 中配置一个可用的子代理（如 github_agent 配了可用的 claude-sonnet-4-6）
3. 让主代理调用 transfer_to_researcher 内置 handoff 工具
4. ❌ 报错：No available channel for model deepseek-v4-flash
5. 改用 transfer_to_github_agent（subagent_orchestrator 中配置的）
6. ✅ 正常执行

AstrBot version, deployment method, provider used, and messaging platform used.

AstrBot 4.25.1, Linux Docker (Debian 13 trixie), provider: ChooseC (DeepSeek/deepseek-v4-flash), platform: QQ aiocqhttp

OS

Linux (Debian 13 trixie, Docker)

Logs / 报错日志

报错信息：

No available channel for model deepseek-v4-flash

源码路径 astrbot/core/astr_agent_tool_exec.py:_execute_handoff，provider_id 为空时 fallback 到 get_current_chat_provider_id()：

prov_id = getattr(tool, "provider_id", None) or await ctx.get_current_chat_provider_id(umo)

Related: #6873（部分相关，侧重参数校验，未覆盖内置工具）、#7939（相关但解决 tools 注入问题）、#8152（未来可能覆盖此场景）

Are you willing to submit a PR? / 你愿意提交 PR 吗？

• Yes!

[dosubot]

根据代码分析，transfer_to_researcher 并不是系统内置的 HandoffTool，而是通过 SubAgentOrchestrator 根据配置动态生成的。命名规则是 transfer_to_{agent_name}——如果你在 subagent_orchestrator.agents 中配置了一个 name: "researcher" 的子代理，系统会自动生成 transfer_to_researcher 工具 [1]。

关于 provider_id 的 fallback 逻辑，你的分析是正确的 [2]：

prov_id = getattr(tool, "provider_id", None) or await ctx.get_current_chat_provider_id(umo)

当 HandoffTool 的 provider_id 为 None 时，会 fallback 到主代理当前使用的 provider。如果该 provider 不可用（如 503），就会报错 No available channel for model deepseek-v4-flash。

实际上 Dashboard 中是有配置入口的 [3]。SubAgent 管理页面为每个子代理提供了一个可清除的 Provider 选择器。如果你的 researcher 子代理确实出现在 Dashboard 的子代理列表中，你应该能为它单独设置 provider_id。

建议的解决方案：

1. 在 Dashboard → 子代理配置中，找到 researcher 子代理，为其显式设置一个可用的 provider_id（如你的 claude-sonnet-4-6 通道）
2. 或者确保主代理的 default_provider_id 指向一个可用的模型通道

如果你确认 Dashboard 中看不到这个 researcher 子代理的配置入口，那可能是该子代理的注册方式有问题——可以检查一下你的 subagent_orchestrator 配置中是否确实有 name: "researcher" 的条目，以及它的 enabled 是否为 true [4]。

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[Blueteemo]

@dosubot Thanks for the detailed analysis! However, I checked my subagent_orchestrator.agents config and there is no name: "researcher" entry at all — only github_agent exists in the config. Yet transfer_to_researcher is still available as a tool for the main agent to call.

So if transfer_to_researcher is supposed to be dynamically generated from subagent config entries, why does it exist when there is no researcher agent configured? Could it be registered from somewhere else (e.g., a built-in default or a deerflow fallback)? Would love to understand the actual registration path.

[dosubot]

感谢补充信息！经过更深入的代码搜索，我可以确认：

AstrBot 核心代码中不存在任何自动注册 "researcher" 代理的逻辑。 具体来说：

1. "researcher" 这个字符串在整个 AstrBot 代码库中没有出现
2. 默认配置中 subagent_orchestrator.agents 是空数组 [1]
3. 没有 first-run、migration 或 dashboard 初始化代码会自动创建默认子代理
4. DeerFlow 集成也不会自动注册 researcher 代理 [2]

那么 transfer_to_researcher 从哪来的？ 可能的来源：

• 第三方插件：你安装的某个插件可能通过 llm_tool 装饰器或动态注册机制注册了这个 handoff 工具
• 配置文件残留：可能之前配置过但现在被删除了，但缓存/运行时状态还保留着（重启后是否还存在？）
• 手动添加过：可能通过 Dashboard 添加过 researcher 子代理

建议排查步骤：

1. 检查 cmd_config.json 文件，搜索 "researcher" 关键字
2. 检查已安装的插件列表，看是否有插件注册了该工具
3. 重启 AstrBot 后确认 transfer_to_researcher 是否仍然存在
4. 在 Dashboard 子代理管理页面查看是否有 researcher 条目 [3]

如果能贴出你的 subagent_orchestrator 完整配置和已安装插件列表，我可以帮你进一步定位。

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[Blueteemo]

结论：transfer_to_researcher 来自 angel_memory 插件

经过深入排查，transfer_to_researcher 的来源终于水落石出：

根因定位

这个 HandoffTool 并非 AstrBot 核心代码或 subagent_orchestrator 生成的，而是由 astrbot_plugin_angel_memory（天使之魂）插件注册的。

具体路径：

• 插件文件：tools/research_subagent.py → build_research_handoff_tool()
• 在 main.py:115-119 通过 context.add_llm_tools() 注入
• 创建了 Agent(name="researcher") 并生成 HandoffTool
• provider_id 取自插件配置 research_assistant.provider_id，为空时 fallback 到主代理默认 provider

为何爆 503？

我配置了顶层的 provider_id 为 MiniMax（用于记忆整理），但 research_assistant.provider_id 保持默认空值 → fallback 到主代理默认的 ChooseC DS/deepseek-v4-flash → 该通道 503 → 报错。

修复方案

Dashboard → 插件管理 → 天使之魂 → 研究助手区域 → 设置 provider_id 为可用模型即可。

根因是第三方插件而非 AstrBot 核心问题，此 Issue将被关闭。

后续我将对天使之魂（angel_memory）插件提交Issue，跟进研究助手与子代理混淆的问题。