扩展开发

优先在现有模块边界内扩展能力，复用工具、命令和渠道协议，补齐相应的错误与生命周期处理。

本页内容

添加工具与命令
渠道插件协议

添加工具与命令

内置工具通常在 src/tool 下定义工厂函数，返回 ToolImpl：definition 描述名称、用途和 JSON 参数，execute 接收参数文本与 ToolContext，返回 ToolResult。is_read_only 必须符合真实副作用，不能为绕过确认把写操作标为只读。

参考已有小工具，提取参数校验和核心逻辑。
复用 ToolArgsParser、错误、路径与会话辅助函数，限制作用范围。
注册到适用的工具清单；有环境依赖时只在能力可用时暴露。
提供可读结果与结构化摘要，必要时附带差异和元数据。
测试合法输入、缺参、错误路径、取消和权限边界。

C++ · 工具工厂结构示意，不是可直接编译的完整工具

// 结构示意：具体定义与处理函数需在对应模块实现。
ToolImpl create_example_tool() {
    ToolImpl impl;
    impl.definition = make_example_definition();
    impl.execute = execute_example;
    impl.is_read_only = true; // 仅适用于确实没有写入副作用的实现
    impl.source = ToolSource::Builtin;
    return impl;
}

斜杠命令通过 CommandRegistry 注册 SlashCommand，处理函数接收 CommandContext 与参数。需要复用模型输入时使用已有提交辅助函数；界面专属操作通过对应回调进入 TUI 管理面板。

桌面/Web 的内置命令还经过独立的支持清单、请求解析和前端路由。只在 TUI 注册命令不会自动得到所有前端行为，修改时同时检查 builtin_command_handler、commands_handler 和 builtinCommandRouting。涉及持久数据或 API 的变动应同步协议与兼容性测试。

渠道插件协议

Channel v1 插件是独立可执行程序，用 manifest 描述启动方式。ACECode 每次生命周期请求启动一次该程序，向 stdin 写入一条以换行结束的 JSON，读取 stdout 上的 channel.status；标准输出不要混入调试日志。

channel-plugin.json · 使用实际可执行文件与工作目录

{
  "schema": "acecode.channel-plugin.v1",
  "name": "example-channel",
  "transport": "stdio",
  "command": "/absolute/path/to/channel-helper",
  "args": [],
  "cwd": "/absolute/path/to/plugin",
  "timeout_ms": 10000
}

激活消息 channel.activate 包含 protocol_version、session_id、入站 URL、认证头与 Token、出站偏好和 settings。插件完成自身准备后返回连接状态及 Webhook 地址：

激活结果示例 · 地址必须由插件实际提供

{
  "type": "channel.status",
  "state": "connected",
  "already_running": false,
  "binding_token": "opaque-current-binding",
  "outbound": {
    "mode": "webhook",
    "url": "http://127.0.0.1:39001/messages"
  }
}

激活应当幂等。可选 binding_token 必须为非空字符串，ACECode 会在对应 channel.deactivate 中原样回传。插件解除绑定时同时核对 session_id 与 binding_token，防止延迟清理误断开新连接。

旧插件可以不返回 binding_token；返回空串或非字符串会被视为非法状态。daemon 正常关闭会保留托管绑定以便恢复，显式 /rc off 才走当前绑定的解除流程。不能把一次辅助进程退出等同于渠道服务已经永久关闭。

测试至少覆盖重复激活、失败返回、超时、同会话重新绑定、迟到解除和认证错误。协议细节见渠道插件协议；用户配置入口见消息渠道与远程控制。