跳到主要内容

外部编码工具

CountBot 可以把外部编码 CLI 接进系统，作为一个可配置的编码执行层。它的定位不是替代主模型，而是在需要时承接编码、调试、重构、命令执行这类工作，或者直接作为某个 IM 渠道账号的默认目标。

为什么要单独一章​

外部编码工具不是普通“第三方集成”，它同时影响三件事：

  • Web 与 IM 中的编码任务怎么执行
  • 渠道账号默认路由如何工作
  • 当前聊天如何在 ai 与 direct 间切换

所以这块最好单独看，而不是混在渠道配置里一笔带过。

支持什么类型的工具​

适合接入的通常是可通过命令行启动的编码工具，例如：

  • Claude Code
  • Codex CLI
  • OpenCode
  • 其他本地 CLI 编码代理

一个 profile 包含什么​

每个外部编码工具 profile 通常会定义：

  • 名称与可选别名
  • 启动命令
  • 参数列表
  • 工作目录
  • 会话模式
  • 环境变量
  • 成功退出码
  • 是否启用

这些配置通过设置 API 持久化，供 external_coding_agent 工具和 IM 渠道路由使用。

会话模式​

当前实现支持三类会话模式规范值：

  • stateless
  • history
  • native

在文档和界面上，你通常可以把它们理解为：

  • 单轮模式：只发当前任务，不带历史
  • 最近历史模式：携带最近几条对话历史
  • 原生会话模式：尽量使用工具自身会话能力

一个重要实现细节​

并不是所有工具都真的支持稳定的原生会话。当前实现里：

  • claude profile 支持 native
  • 其他 profile 即使配置成 native，也会在运行时回退到 history

这就是为什么某些工具页面看起来选了“原生会话模式”，但实际运行并不是完全按该模式执行。

与渠道默认路由的关系​

每个 IM 渠道账号都可以保存两项高级设置：

  • 默认路由模式 routing_mode
  • 默认外部编码工具 external_coding_profile

routing_mode=ai​

普通消息先进 CountBot 主 Agent，再由主模型决定是否调用外部编码工具。

routing_mode=direct​

普通消息直接转发给当前账号绑定的外部编码工具，适合持续编码场景。

如果渠道账号配置成 direct 却没有绑定 external_coding_profile，后端会直接拒绝这份渠道配置。

与 IM 命令的关系​

IM 聊天里支持临时切换：

  • /route ai
  • /route direct
  • /route default
  • /coder <profile>
  • /coder default

这几个命令只影响当前聊天，不会修改后台保存的默认值。

详细见 IM 命令。

当前可用 API​

方法路径说明
GET/api/settings/external-coding-tools获取外部编码工具配置
PUT/api/settings/external-coding-tools保存外部编码工具配置
POST/api/settings/external-coding-tools/check检查某个 profile 是否可用

推荐接入顺序​

  1. 先新增一个 profile。
  2. 填写命令、参数、工作目录和环境变量。
  3. 先用检查接口验证 profile 本身可运行。
  4. 再把它绑定到某个 IM 渠道账号。
  5. 最后再通过 /route 和 /coder 在真实聊天里验证行为。

排查思路​

页面看起来已启用，但聊天里没有生效​

优先检查：

  • 该 profile 是否真正启用
  • 渠道账号默认 external_coding_profile 是否指向它
  • 当前聊天是否被 /coder default 或 /route default 恢复成了后台默认值

为什么某个工具“默认开启”​

通常不是系统自动乱开，而是以下之一：

  • 该渠道账号高级设置本来就保存了默认 profile
  • 当前聊天之前执行过 /coder <profile>
  • 当前聊天路由是 direct

为什么会话模式和预期不同​

重点检查：

  • profile 配置的是不是 native
  • 当前工具是否真的支持 native
  • 不支持时是否被运行时自动回退为 history

相关文档​