Skip to content

feat(core): ChartController 暴露 Agent 工具宿主注册(registerToolHost) - #272

Closed
EliteOtaku wants to merge 2 commits into
363045841:mainfrom
EliteOtaku:pr/agent-tool-host-registration
Closed

EliteOtaku wants to merge 2 commits into
363045841:mainfrom
EliteOtaku:pr/agent-tool-host-registration

Conversation

@EliteOtaku

@EliteOtaku EliteOtaku commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

依赖:基于 #266(外部渲染器加载点/ChartController 渲染器 API)。建议在 #266 合并后评审;分支含少量 preview 与 controller 相邻行改动。

动机

Tool 装饰器协议(foundation/agent/chartToolRegistry)允许任何持有宿主对象的代码把领域方法暴露为 Agent 工具,但 ChartAgentController.toolHosts 目前是硬编码数组(仅内置对比品种宿主)——外部宿主(插件、嵌入方)无法把自己的 @Tool 宿主注册进 Agent 的方法归属解析,@Tool 协议因此对第三方宿主不可用。

方案(纯增量 API)

ChartController 新增两个方法:

/** 注册 Agent 工具宿主:宿主的 @Tool 标注方法会成为 Agent 可调用工具,
 *  调用时按方法函数身份在已注册宿主中解析执行目标。幂等。 */
registerToolHost(host: object): void
/** 移除先前注册的 Agent 工具宿主。 */
unregisterToolHost(host: object): void
  • ChartAgentControllerDependencies 增加可选 extraToolHosts?: () => ReadonlyArray<object>;
  • toolHosts getter 返回 [comparisonCommands, ...extraToolHosts()],既有消费方(browser tool registry 的 chartToolTarget 按 owns() 解析)零改动;
  • 根导出补充通用工具协议:Tool 装饰器与 ChartToolConfig / ChartToolExecutionContext / ChartToolSafety / RegisteredChartTool 类型——外部宿主此前无法从公开 API 获取装饰器。

典型用法(外部宿主/插件):

class MyToolHost {
  @Tool({ name: 'my_query', label: '...', description: '...', parameters: MySchema, safety: 'read-only' })
  myQuery(input: Static<typeof MySchema>) { /* 领域查询 */ }
}
controller.registerToolHost(new MyToolHost())

验证

  • 新增 createChartController.toolHosts.test.ts 3 用例:注册幂等(重复注册仅一份)/ unregister 移除 / @Tool 方法经 owns 解析宿主并执行(TypeBox 校验走通);
  • core 全量:251 文件 / 2676 用例全绿;tsc build 绿。

兼容性

纯增量:不改既有接口行为;未注册宿主时 toolHosts 行为与之前完全一致。

补充(第二段:工具目录动态源)

@Tool 装饰器依赖模块级注册表,外部宿主 bundle 与 core 不共享模块实例时不可达;工具目录又只在 bridge 构造时静态快照。本 PR 同时补齐:

  • core:chartToolRegistry 增 registerChartTool(tool) / unregisterChartTool(name)(编程式写入唯一真源,冲突语义与装饰器一致);
  • vue:BrowserAgentBridgeOptions 增 extraChartTools?: () => ReadonlyArray<RegisteredChartTool>,BrowserToolRegistry.registerTools 合并内置与外部源。

组合用法(外部宿主/插件):

const host = new MyToolHost()                    // @Tool 标注方法
controller.registerToolHost(host)                // 方法归属解析(toolHosts.owns)
bridge = new BrowserAgentBridge({                // 宿主装配 bridge 时声明工具目录源
  getChartAgent,
  extraChartTools: () => getRegisteredChartTools().filter(t => t.config.name.startsWith('my_')),
})

…egisterToolHost)

Tool 装饰器协议允许任意宿主把领域方法暴露为 Agent 工具,但 toolHosts
硬编码(仅内置对比品种宿主),外部宿主的 @tool 方法无法被归属解析。

- ChartController 新增 registerToolHost/unregisterToolHost(幂等去重);
  ChartAgentControllerDependencies 加可选 extraToolHosts()
- toolHosts getter 合并内置+动态宿主;browser tool registry 的 owns()
  解析消费方零改动
- 根导出补通用工具协议:Tool 装饰器 + ChartToolConfig/
  ChartToolExecutionContext/ChartToolSafety/RegisteredChartTool 类型
- 新增 toolHosts 测试 3 用例;core 251 文件 2676 用例全绿
EliteOtaku added a commit to EliteOtaku/KCQ-NexusAI that referenced this pull request Sep 29, 2026
@tool 装饰器依赖跨 bundle 不可达(外部插件与 core 不共享模块实例),
bridge 工具目录又只在构造时静态快照——外部宿主的 Agent 工具无法进入目录。

- core:chartToolRegistry 增 registerChartTool/unregisterChartTool(编程式
  写入唯一真源,冲突语义与装饰器一致);根导出同步
- vue:BrowserAgentBridgeOptions 增 extraChartTools?: () => RegisteredChartTool[]
  (惰性求值一次),BrowserToolRegistry.registerTools 合并内置+外部源
- 与 363045841#272(registerToolHost 方法归属解析)组成外部 Agent 工具完整链:
  宿主持有 @tool 类实例 → registerToolHost 注册归属 → bridge extraChartTools
  声明工具目录
@tool 装饰器依赖跨 bundle 不可达(外部插件与 core 不共享模块实例),
bridge 工具目录又只在构造时静态快照——外部宿主的 Agent 工具无法进入目录。

- core:chartToolRegistry 增 registerChartTool/unregisterChartTool(编程式
  写入唯一真源,冲突语义与装饰器一致);根导出同步
- vue:BrowserAgentBridgeOptions 增 extraChartTools?: () => RegisteredChartTool[]
  (惰性求值一次),BrowserToolRegistry.registerTools 合并内置+外部源
- 与 363045841#272(registerToolHost 方法归属解析)组成外部 Agent 工具完整链:
  宿主持有 @tool 类实例 → registerToolHost 注册归属 → bridge extraChartTools
  声明工具目录
@EliteOtaku EliteOtaku closed this Sep 29, 2026
@EliteOtaku
EliteOtaku deleted the pr/agent-tool-host-registration branch September 29, 2026 18:20
EliteOtaku added a commit to EliteOtaku/KCQ-NexusAI that referenced this pull request Sep 29, 2026
与 363045841#272(工具宿主注册)同族的注册表编程入口:指标目录的注册只有类装饰器
(依赖模块加载),外部宿主 bundle 与 Core 不共享模块实例时不可达。

- indicatorDefinitionRegistry:抽共享组装 defineIndicator,新增
  registerIndicatorDefinition(config, rendererFactory)(同名重复注册抛错,
  与装饰器语义一致);name 放宽为 string(契约 union 仅约束内置编译期拼写)
- IndicatorDefinitionConfig/IndicatorMetadata 增可选 ui 字段(name/description/
  params):内置指标 UI 元数据来自静态 uiMeta 表,外部指标随定义携带——
  indicatorCatalog rebuild 映射 uiMeta ?? def.ui
- 测试 +4(编程式注册进目录/重复注册拒绝/params 通道/装饰器与编程式同表),
  全量 252 文件 2680 用例全绿
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant