coze-studio Tool 配置体系解析：@coze-agent-ide/tool-config 包与 Agent Tool 接入指南

coze-studio Tool 配置体系解析：@coze-agent-ide/tool-config 包与 Agent Tool 接入指南

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio

本文围绕 coze-studio 前端 agent-ide 下的@coze-agent-ide/tool-config包（README.md），系统讲解 Agent 编辑器 Tool 区域的配置机制：新接入一个 Tool 时，开发者需要在类型定义与常量映射中完成的全部注册步骤，以及这些枚举、映射如何在/api/draftbot/update、/api/draftbot/update_display_info等接口与编辑器界面之间建立关联。读完本文，你将掌握 ToolKey 枚举体系、四张核心映射表的含义与用法、Tool 分组与展示排序规则，以及快捷指令（Shortcut）配置的类型约束与校验逻辑，能够在 coze-studio 前端源码中独立定位并完成一个新 Tool 的接入。

一、包定位：Tool 区域配置的核心约定

@coze-agent-ide/tool-config是 agent-ide 生态中的一个纯配置/类型包，package.json（package.json）中描述为 "tool core"，版本0.0.1，主入口为src/index.tsx。它的职责不是实现 Tool 的具体 UI 逻辑，而是沉淀接入新 Tool 所需的类型约定与常量映射，作为 Agent 编辑器 Tool 区域的"接入规范"。

包的目录结构如下：

frontend/packages/agent-ide/tool-config/ ├── __tests__/shortcut-config/get-strict-shortcuts.test.ts # 快捷指令过滤逻辑单测 ├── src/ │ ├── index.tsx # 包导出入口 │ ├── types.ts # 全部枚举与类型定义 │ ├── constants.ts # 四张核心映射常量表 │ └── shortcut-config/ │ ├── get-strict-shortcuts.ts # 严格快捷指令过滤函数 │ └── type.ts # 快捷指令类型约束 ├── package.json └── ...

从源码结构看，该包对外导出三类内容（见 index.tsx）：一是types中的全部枚举与联合类型；二是constants中的全部映射常量；三是shortcut-config子模块的快捷指令类型与过滤函数getStrictShortcuts。下文依次展开。

二、类型定义层：ToolKey 枚举与配套类型

types.ts 是整个接入体系的"登记处"——新接入的 Tool，首先必须在这里新增一个枚举值。文件定义了以下核心类型：

2.1 AbilityScope 与 AbilityKey

export const enum AbilityScope { TOOL = 'tool', AGENT_SKILL = 'agentSkill', } export type AbilityKey = ToolKey | AgentSkillKey;

AbilityScope区分两种"能力"归属：tool（工具）与agentSkill（Agent 技能）。AbilityKey是二者的联合，统一了后续映射表的键类型。

2.2 ToolKey：Agent 能力的完整清单

ToolKey是当前仓库中 Agent 可配置能力的完整枚举，共 19 个值：

源码注释特别说明："ToolKey has temporarily given everyone a name for the project. If you think the name is not good, you can replace it globally."（ToolKey 暂定名，若命名不佳可全局替换），即该枚举是全项目统一的 Tool 标识符，应保持全局一致。

2.3 AgentSkillKey：Agent 技能维度的能力子集

export const enum AgentSkillKey { PLUGIN = 'plugin', WORKFLOW = 'workflow', KNOWLEDGE = 'knowledge', }

与ToolKey的 19 项相比，AgentSkillKey仅收敛到插件、工作流、知识库三项，用于 Agent 技能（agentSkill）这一更窄的能力维度。

2.4 界面与分组枚举

export const enum AgentModalTabKey { TOOLS = 'tools', WORKFLOW = 'workflow', DATASETS = 'datasets', } export const enum ToolGroupKey { SKILL = 'skill', KNOWLEDGE = 'knowledge', MEMORY = 'memory', DIALOG = 'dialog', HOOKS = 'hooks', CHARACTER = 'character', }

• AgentModalTabKey：Agent 配置弹窗的页签键（工具 / 工作流 / 数据集）。
• ToolGroupKey：Tool 在界面上的分组键，共六组（技能、知识、记忆、对话、钩子、角色）。

2.5 已废弃的 SkillKeyEnum

SkillKeyEnum被标记为@Deprecated，源码注释明确要求改用ToolKey：

export enum SkillKeyEnum { PLUGIN_API_BLOCK = 'plugin', WORKFLOW_BLOCK = 'workflow', IMAGE_BLOCK = 'imageflow', DATA_SET_BLOCK = 'knowledge', DATA_MEMORY_BLOCK = 'variable', TABLE_MEMORY_BLOCK = 'database', TIME_CAPSULE_BLOCK = 'time_capsule', FILEBOX_BLOCK = 'filebox', TASK_MANAGE_BLOCK = 'scheduled_task', ONBORDING_MESSAGE_BLOCK = 'opening_dialog', AUTO_SUGGESTION = 'suggestion', TEXT_TO_SPEECH = 'tts', BACKGROUND_IMAGE_BLOCK = 'background_image', }

对比可见，SkillKeyEnum使用"业务块"语义命名（如TIME_CAPSULE_BLOCK、ONBORDING_MESSAGE_BLOCK），而新的ToolKey采用更简洁的通用命名（如TRIGGER、ONBOARDING），两者存在明显的语义映射关系。新接入 Tool 时一律使用ToolKey，不要新增SkillKeyEnum成员。

三、存储映射层：TOOL_KEY_STORE_MAP 与 AGENT_SKILL_KEY_MAP

constants.ts 中定义了接入 Tool 的第二项必备工作——配置 ToolKey 与/api/draftbot/update接口入参字段名的映射。

export const TOOL_KEY_STORE_MAP = { [ToolKey.PLUGIN]: 'pluginApis', [ToolKey.SHORTCUT]: 'shortcut', [ToolKey.DEV_HOOKS]: 'devHooks', }; export const AGENT_SKILL_KEY_MAP = { [AgentSkillKey.PLUGIN]: 'pluginApis', };

这两张表的作用是：把编辑器内部的ToolKey（如plugin）翻译成draftbot/update接口期望的存储字段名（如pluginApis），从而将界面配置落到 bot 草稿的存储结构上。目前仓库内已注册的映射包括：

• TOOL_KEY_STORE_MAP：PLUGIN → pluginApis、SHORTCUT → shortcut、DEV_HOOKS → devHooks；
• AGENT_SKILL_KEY_MAP：AgentSkillKey.PLUGIN → pluginApis。

值得注意：该表并非全量覆盖——WORKFLOW、KNOWLEDGE等 ToolKey 未出现在存储映射中，说明这些能力的存储路径与字段命名由其他模块（或通过update_display_info的展示状态机制）处理。从源码结构看，接入新 Tool 时应按需判断其是否拥有独立的草稿存储字段：若有，则必须在此表补充ToolKey → 接口字段名条目。

四、展示状态映射层：TOOL_KEY_TO_API_STATUS_KEY_MAP

这是接入 Tool 的第三项必备工作——将ToolKey映射为/api/draftbot/update_display_info接口的字段名。该映射表以keyof TabDisplayItems为类型约束，保证了键的合法性由后端 IDL 类型在编译期校验：

export const TOOL_KEY_TO_API_STATUS_KEY_MAP: { [key in ToolKey]: keyof TabDisplayItems; } = { [ToolKey.PLUGIN]: 'plugin_tab_status', [ToolKey.WORKFLOW]: 'workflow_tab_status', [ToolKey.IMAGEFLOW]: 'imageflow_tab_status', [ToolKey.DATABASE]: 'database_tab_status', [ToolKey.FILE_BOX]: 'filebox_tab_status', [ToolKey.KNOWLEDGE]: 'knowledge_tab_status', [ToolKey.ONBOARDING]: 'opening_dialog_tab_status', [ToolKey.SUGGEST]: 'suggestion_tab_status', [ToolKey.TRIGGER]: 'scheduled_task_tab_status', [ToolKey.VARIABLE]: 'variable_tab_status', [ToolKey.VOICE]: 'tts_tab_status', [ToolKey.LONG_TERM_MEMORY]: 'long_term_memory_tab_status', [ToolKey.BACKGROUND]: 'background_image_tab_status', [ToolKey.TABLE]: 'knowledge_table_tab_status', [ToolKey.DOCUMENT]: 'knowledge_text_tab_status', [ToolKey.PHOTO]: 'knowledge_photo_tab_status', [ToolKey.SHORTCUT]: 'shortcut_tab_status', [ToolKey.DEV_HOOKS]: 'hook_info_tab_status', [ToolKey.USER_INPUT]: 'default_user_input_tab_status', };

该表将 19 个ToolKey全量映射到TabDisplayItems的对应字段，用于控制各 Tool 在界面上的显示状态（开关、显隐等）。

4.1 类型约束的真实来源：TabDisplayItems

TabDisplayItems接口定义在 arch 包生成的 IDL 类型文件中（developer_api.ts），共 23 个可选的TabStatus字段，除上述 19 项外还包括：

export interface TabDisplayItems { plugin_tab_status?: TabStatus; workflow_tab_status?: TabStatus; knowledge_tab_status?: TabStatus; database_tab_status?: TabStatus; variable_tab_status?: TabStatus; opening_dialog_tab_status?: TabStatus; scheduled_task_tab_status?: TabStatus; suggestion_tab_status?: TabStatus; tts_tab_status?: TabStatus; filebox_tab_status?: TabStatus; long_term_memory_tab_status?: TabStatus; answer_action_tab_status?: TabStatus; imageflow_tab_status?: TabStatus; background_image_tab_status?: TabStatus; shortcut_tab_status?: TabStatus; knowledge_table_tab_status?: TabStatus; knowledge_text_tab_status?: TabStatus; knowledge_photo_tab_status?: TabStatus; hook_info_tab_status?: TabStatus; default_user_input_tab_status?: TabStatus; knowledge_volcano_unstructured_tab_status?: TabStatus; knowledge_volcano_structured_tab_status?: TabStatus; model_tab_status?: TabStatus; }

从映射表与接口定义的对比可以看出：TOOL_KEY_TO_API_STATUS_KEY_MAP目前覆盖了TabDisplayItems中除answer_action_tab_status、knowledge_volcano_*、model_tab_status之外的 19 个字段。也就是说，后端接口能力大于当前前端 ToolKey 清单——这也是新 Tool 接入时"先加 ToolKey 枚举、再加展示状态映射"这一流程的直接体现。此外，skill.ts 中也有注释提醒：字段命名需与自动生成的developer_api > TabDisplayItems保持一致，说明该命名约定是全链路共用的。

五、界面分组与顺序：TOOL_GROUP_CONFIG

/** * The order here determines the order of presentation, please note */ export const TOOL_GROUP_CONFIG = { [ToolGroupKey.SKILL]: 'Skill', [ToolGroupKey.KNOWLEDGE]: 'Knowledge', [ToolGroupKey.MEMORY]: 'Memory', [ToolGroupKey.DIALOG]: 'Dialog', [ToolGroupKey.CHARACTER]: 'Character', [ToolGroupKey.HOOKS]: 'Hooks', };

TOOL_GROUP_CONFIG定义了 Tool 分组键到展示文案的映射，源码注释明确指出：对象键的书写顺序即界面展示顺序（Skill → Knowledge → Memory → Dialog → Character → Hooks）。新 Tool 若归属于新分组，需在ToolGroupKey枚举中新增分组键，并在本表中按期望的展示位置插入条目。

六、快捷指令子模块：shortcut-config

除 Tool 主配置外，该包还承担快捷指令（Shortcut）的类型与过滤逻辑。

6.1 类型约束（type.ts）

快捷指令的类型体系以服务端模型ShortcutCommandFromService为基础做了前端侧收紧：

• ShortCutStruct：继承服务端结构的shortcut_sort字段，并携带shortcut_list；
• ShortCutCommand：由三种形态联合而成；
• TemplateShortCutForWorkFlow：工作流模板型快捷指令，tool_type固定为ToolType.ToolTypeWorkFlow，必须具备work_flow_id；
• TemplateShortCutForPlugin：插件模板型快捷指令，tool_type固定为ToolType.ToolTypePlugin，必须具备plugin_id、plugin_api_name、plugin_api_id；
• QueryShortCut：查询型快捷指令，send_type固定为SendType.SendTypeQuery。

模板型（Panel 型）指令额外要求components_list字段，用于面板卡片渲染。这些类型通过BaseShortCutInfo统一约束command_name、template_query、description、send_type、command_id、object_id与bot_info（含icon_url、name）。

6.2 严格过滤逻辑（get-strict-shortcuts.ts）

export function getStrictShortcuts(shortcuts?: ShortcutCommandFromService[]) { return shortcuts?.filter((shortcut): shortcut is ShortCutCommand => { const { tool_type } = shortcut; const withoutCommandId = !shortcut.command_id; const workflowWithoutWorkflowId = tool_type === ToolType.ToolTypeWorkFlow && !shortcut.plugin_id; const pluginWithoutPluginId = tool_type === ToolType.ToolTypePlugin && !shortcut.plugin_id; return !( withoutCommandId || workflowWithoutWorkflowId || pluginWithoutPluginId ); }); }

getStrictShortcuts会剔除三类"无效"快捷指令：缺少command_id的；工作流类型但缺少plugin_id的；插件类型但缺少plugin_id的。同时，源码中有一段被注释的panelWithoutCardSchema判定（Panel 型指令缺少card_schema时剔除），说明该校验曾在历史版本启用，当前版本已将其关闭，仅保留 ID 与归属完整性校验。

6.3 单元测试验证（get-strict-shortcuts.test.ts）

仓库为上述逻辑提供了 5 个 vitest 用例，覆盖了全部关键分支：

• 输入undefined时返回undefined；
• 过滤掉无command_id的指令（两条输入仅保留 1 条）；
• 过滤掉无plugin_id的工作流指令；
• 过滤掉无plugin_id的插件指令；
• 保留所有合法指令（含ToolType.ToolTypeNone等其他类型）；
• 空数组原样返回。

测试用例清晰地印证了过滤规则的判定边界，可作为接入新快捷指令类型时的回归参考。

七、消费侧实证：Tool 区域如何引用这些配置

该包并非孤立定义，实际消费方位于 agent-ide 的 entry 包中。在 tool-area.tsx 里，同时引用了ToolGroupKey（来自@coze-agent-ide/tool-config）与ToolKey（来自@coze-agent-ide/tool），并以如下方式驱动界面渲染：

import { ToolGroupKey } from '@coze-agent-ide/tool-config'; import { GroupingContainer, ToolKey, ToolView } from '@coze-agent-ide/tool'; // ... <ToolView toolKey={ToolKey.PLUGIN} /> <ToolView toolKey={ToolKey.WORKFLOW} /> <ToolView toolKey={ToolKey.DOCUMENT} /> <ToolView toolKey={ToolKey.TABLE} /> <ToolView toolKey={ToolKey.PHOTO} /> <ToolView toolKey={ToolKey.VARIABLE} /> <ToolView toolKey={ToolKey.ONBOARDING} /> <ToolView toolKey={ToolKey.SUGGEST} /> <ToolView toolKey={ToolKey.SHORTCUT} /> <ToolView toolKey={ToolKey.BACKGROUND} />

可以推断：Agent 配置区的 Tool 面板以ToolKey为标识逐项渲染各能力区块，ToolGroupKey用于能力分组，而TOOL_KEY_TO_API_STATUS_KEY_MAP等常量则负责将界面状态写回update_display_info接口。此外，agent-ide下多个子包（space-bot、plugin-area-adapter、model-manager、onboarding等）的package.json与源码均引用了@coze-agent-ide/tool-config，可见该包是 agent-ide 各模块共享的 Tool 配置中枢。

八、接入新 Tool 的完整操作清单

综合上文，结合 README 的三条核心要求与源码实现，在 coze-studio 中接入一个新 Tool 的完整步骤如下：

1. 注册类型：在 types.ts 的ToolKey枚举中新增一个枚举值（如[ToolKey.XXX]: 'xxx'），并同步检查是否需要扩充AgentSkillKey或新增ToolGroupKey分组。
2. 配置存储映射（如该 Tool 在/api/draftbot/update有独立存储字段）：在 constants.ts 的TOOL_KEY_STORE_MAP（或AGENT_SKILL_KEY_MAP）中新增ToolKey → 接口字段名条目。
3. 配置展示状态映射：在TOOL_KEY_TO_API_STATUS_KEY_MAP中新增[ToolKey.XXX]: '<对应字段>_tab_status'条目，该字段必须是TabDisplayItems（developer_api.ts）中已定义的键；若后端 IDL 尚无对应字段，需先扩展TabDisplayItems类型。
4. 配置分组与顺序：如需新分组，在ToolGroupKey与TOOL_GROUP_CONFIG中按期望展示位置插入条目。
5. 渲染接入：在 tool-area.tsx 等消费方中，使用ToolView toolKey={ToolKey.XXX}挂载对应能力视图。
6. 回归验证：运行npm run test（vitest）确保getStrictShortcuts等既有用例不回归；若涉及快捷指令类型调整，同步补充 get-strict-shortcuts.test.ts 中的用例。

九、小结

@coze-agent-ide/tool-config以极小的代码量（类型 + 常量 + 一个过滤函数）构建了 coze-studio Agent 编辑器 Tool 接入的"契约层"：ToolKey枚举统一定义能力标识，TOOL_KEY_STORE_MAP/AGENT_SKILL_KEY_MAP桥接草稿存储接口，TOOL_KEY_TO_API_STATUS_KEY_MAP桥接展示状态接口，TOOL_GROUP_CONFIG控制界面分组与顺序，shortcut-config则约束快捷指令的合法形态。理解这一套"先类型、后映射、再渲染"的接入链路，是向 coze-studio 添加新 Agent 能力的第一步。

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio