coze-studio Bot Creator 工具能力区子包 coze-agent-ide/toolhooks、组件与状态架构详解【免费下载链接】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-studiocoze-agent-ide/tool源码位于 frontend/packages/agent-ide/tool是 coze-studio 前端 monorepo 中定位为Bot Creator 业务子 package的能力包负责 Bot 编辑器中“工具/技能Tool / Agent Skill”区域的 hooks、通用组件与状态管理。本文以该包 README 为骨架结合源码剖析其构建能力eslint、esm/umd 双格式打包、storybook、开发命令以及 Tool 区域从状态机到 UI 渲染的完整实现链路帮助读者理解并复用它来扩展 Agent 能力面板。一、包定位Bot Creator 业务子 packageREADME.md 开篇即明确了该包的定位定位为 Bot Creator 业务子 package里面的通用组件慢慢往外抽。这句话包含两层工程含义业务归属该包服务于 Bot CreatorBot 编辑器/智能体编排业务聚焦工具能力区这一具体场景而不是面向全站的通用库渐进式抽取策略包内通用组件会随业务沉淀逐步外抽到更底层的公共包如coze-arch/*、coze-studio/components等 workspace 依赖保持业务层薄、复用层厚的依赖方向。这一策略在 package.json 中得到印证包名coze-agent-ide/tool版本0.0.1许可 Apache-2.0其dependencies全部以workspace:*引用 monorepo 内部包coze-agent-ide/tool-config、coze-studio/bot-detail-store、coze-arch/bot-*、coze-data/knowledge-modal-base等依赖的选型也说明了该包的实际技术栈依赖类型具体选型用途状态管理zustand^4.4.7immer^10.0.3工具区域状态机与不可变更新UI 基础douyinfe/semi-foundation、coze-arch/coze-design、coze-arch/bot-semi设计体系组件与图标工具函数ahooks^3.7.8、lodash-es、classnames、nanoidHooks 能力与通用工具事件通信eventemitter3^5.0.1跨模块事件中心错误兜底react-error-boundary^4.0.9、coze-arch/logger组件错误边界同时peerDependencies声明react 18.2.0、react-dom 18.2.0由宿主应用提供运行时保证包体积与版本一致性。二、构建与工程能力Features 逐项解读README 的 Features 清单虽然简短但每一项都对应真实的工程配置[x] eslint ts类型检查与 lint 已接入。仓库根目录的 eslint.config.js 与 tsconfig.json 均继承自 monorepo 内部的coze-arch/eslint-config与coze-arch/ts-config工程化标准[x] esm bundlemodule字段指向./dist/esm/index.js供现代打包器webpack/rspack/vite按 ESM 语法 tree-shaking[x] umd bundleunpkg字段指向./dist/umd/index.js可直接通过script标签在浏览器全局引入[x] storybookstories/demo.stories.tsx 提供了组件演示与autodocs自动文档入口stories/hello.mdx 是 MDX 文档示例。从 package.json 的脚本可以看出该包预置了完整的质量保障命令scripts: { build: exit 0, lint: eslint ./ --cache, test: vitest --run --passWithNoTests, test:cov: npm run test -- --coverage }lint对全目录执行 ESLint 并启用缓存加速test/test:cov使用 vitest 执行单测--passWithNoTests保证无测试文件时也能通过 CI覆盖率报告输出目录coverage已在 config/rush-project.json 中登记给 Rush 增量构建系统缓存同文件还登记了ts-check的输出目录./dist说明类型产物也会纳入 Rush 构建缓存管理。三、开发命令从依赖安装到构建README 提供了三条核心命令结合 coze-studio 的 Rush 工程体系rush.json实际开发流程如下1. initrush updatecoze-studio 前端使用 Rush 作为 monorepo 包管理器对应 common/config/rush 目录。首次克隆仓库后执行rush updateRush 会根据 rush.json 中各 package 的依赖声明一次性解析、安装并链接所有 workspace 依赖包括coze-agent-ide/tool的workspace:*内部依赖并生成各子包所需的.npmrc与锁文件。这是进入tool包开发前的第一步。2. devnpm run dev在frontend/packages/agent-ide/tool目录下执行npm run dev进入本地开发模式配合 Storybook 进行组件的独立调试README 已声明 storybook 为已实现能力。3. buildnpm run buildnpm run build当前该脚本为exit 0占位实现——从main: src/index.ts、module: ./dist/esm/index.js与unpkg: ./dist/umd/index.js三个字段可以看出正式构建目标是将src/index.ts入口分别产出为ESM 与 UMD 双格式的dist产物构建工具链rollup swc postcss见 devDependencies已就绪构建逻辑会在后续迭代中补齐。四、公开 API 全景从src/index.ts看包的能力边界该包通过单一入口 src/index.ts 对外暴露能力注释明确标注了长期稳定暴露与过渡期暴露两个层次是理解模块边界的最佳地图4.1 长期稳定 APISTART 长期暴露类型与常量AbilityScope、ToolKey、AgentSkillKey复导出自coze-agent-ide/tool-config状态访问useToolStore/useToolStoreAction/useToolDispatch/useSubscribeToolStore来自 hooks/public/store/use-tool-store.ts能力组件ToolView、ToolContainer、ToolMenu、GroupingContainer、AbilityAreaContainer、ToolContentBlock、ToolItemList、ToolItem、ToolItemSwitch、ToolItemAction及ToolItemActionCard/Copy/Delete/Info/Setting/Edit/Drag动作组件、ToolItemIconInfo/People/Card图标组件、AutoGenerateButton、AddButton、ModelCapabilityTipsDisplayHooks 与工具函数useInit、useToolToggleCollapse、useToolContentBlockDefaultExpand、useRegisteredToolKeyConfigList、useIsAllToolHidden、useToolValidData、useAgentSkillModal、useToolItemContext、abilityKey2ModelFunctionConfigType等Context ProviderAbilityAreaContextProvider。4.2 过渡期 APIDEPRECATED 说明SkillKeyEnum被标注为Deprecated官方建议改用coze-agent-ide/tool-config中的ToolKey同时保留useHasAgentSkillWithPK、useEvent、EventCenterEventName、IToggleContentBlockEventParams供旧代码平滑迁移。这种双窗口期设计体现了包演进时对兼容性的重视。五、状态层源码剖析ToolAreaStore 与订阅机制5.1 工具区域注册表store/tool-area.tsstore/tool-area.ts 基于 zustandcreatedevtools中间件 immerproduce实现createToolAreaStore其状态核心是两份注册表registeredToolKeyConfigList: IRegisteredToolKeyConfig[]——已注册工具配置每条包含toolGroupKey、toolKey、toolTitle、hasValidData四个字段registeredToolGroupList: IRegisteredToolGroupConfig[]——已注册工具分组toolGroupKeygroupTitle。关键行为均有对应单测验证注册去重appendIntoRegisteredToolKeyConfigList以toolKey为唯一键重复注册时保留首次记录详见测试appendIntoRegisteredToolKeyConfigList repeat filter有效性更新setToolHasValidData使用 immer 对目标 toolKey 的hasValidData进行不可变更新驱动后续 UI 的是否有有效配置判断初始化标记isInitialed、isModeSwitching、initialedToolKeyList记录区域初始化状态与已初始化工具集合clearStore用于切换 Agent 时重置区域状态。在开发模式下devtools 中间件以botStudio.tool.ToolAreaStore为名接入 Redux DevTools便于调试状态变化。5.2 全局状态机访问与数据提交use-tool-store.tshooks/public/store/use-tool-store.ts 是整个工具区数据流的枢纽四个 Hook 各司其职Hook职责useToolStore(selector)通过 selector 读取全局 BotSkillStore 状态读useToolStoreAction(selector)获取全局状态机的操作方法写useToolDispatch()以作用域 abilityKey 为键将新状态提交到 Ability 上下文 store提交useSubscribeToolStore(scope, agentId)订阅 Ability store 变化同步到 Bot 详情 store同步实现细节值得关注作用域路由KEY_MAP将AbilityScope.TOOL映射到TOOL_KEY_STORE_MAP、AbilityScope.AGENT_SKILL映射到AGENT_SKILL_KEY_MAP实现同一套提交逻辑对不同能力类型的统一处理数据同步方向useSubscribeToolStore中AbilityScope.TOOL的数据直接调用setBotSkill写入 Bot 详情 storeAGENT_SKILL则通过setMultiAgentByImmer在多智能体状态中按agentId定位目标 agent 并写入其skills字段——这与 coze-studio 多 Agent 编排的业务模型一一对应能力上下文校验useToolStore等 Hook 在未取到abilityKey时会通过generateErrorutils/error.ts抛出明确错误防止在无 Ability 上下文的组件树中误用。5.3 注册与初始化builtin HooksuseRegisterToolKey/useRegisterToolGroup工具与分组注册入口负责把工具声明写入上述注册表useGetToolConfig按toolKey查询工具配置useInithooks/public/init/use-init.ts区域初始化编排入口完成注册、初始化状态标记等启动逻辑。六、组件层ToolContainer 的容器化与错误兜底以 components/tool-container/index.tsx 为例可以清楚看到容器组件的三层设计折叠面板样式通过collapse-panel、collapse-panel-${toolKey}类名接入 Bot 编辑器的折叠面板体系onMouseEnter/Leave负责控制相邻面板下划线的高亮隐藏可见性策略getInvisible()综合enableToolHiddenMode偏好开关、isReadonly只读态与TabStatus.Hide页面运行时状态三类信号决定工具面板是否隐藏只读场景下以hasValidData为准编辑场景下以 API 状态映射TOOL_KEY_TO_API_STATUS_KEY_MAP为准能力上下文注入在ErrorBoundary错误名botEditorTool${toolKey}失败时渲染ToolContainerFallback兜底包裹下通过AbilityConfigContextProvider注入abilityKey与scopeAbilityScope.TOOL其子组件即可通过useAbilityConfig()hooks/builtin/use-ability-config.ts读取能力上下文。ToolItemcomponents/tool-item/index.tsx则定义了单个工具卡片的展示协议title、description、tags、avatar、actions操作区可挂载增删改拖等动作组件、icons图标区、disabled、tooltips、onClick以及size: default | large大尺寸适配 workflow-as-agent 模式并通过ToolItemContextProvider向子动作组件传递上下文。七、测试与质量保障该包在tests下按hooks、store、utils分目录组织测试tests/store/tool-area.test.ts 覆盖了 ToolAreaStore 的全部核心行为单条注册、重复注册过滤同toolKey不同toolGroupKey时保留首条、hasToolKeyInRegisteredToolKeyList查询、初始化列表追加与查询、setToolHasValidData的不可变更新、分组注册测试中使用vi.stubGlobal(IS_DEV_MODE, false)关闭 devtools 以保证断言纯净tests/hooks/duplicate-use-ability-config.tsx 针对 Hook 在重复/嵌套上下文中的行为做验证tests/utils/error.test.ts 验证错误生成工具函数。配合vitest --run、eslint --cache与 Rush 构建缓存config/rush-project.json形成了类型检查 Lint 单测 覆盖率的四层质量保障。八、小结coze-agent-ide/tool虽是一个 业务子 package但其工程形态完整Rush workspace 依赖管理、esm/umd 双格式构建目标、storybook 组件文档、vitest 测试体系一应俱全代码结构上以ToolKey/AbilityScope为能力标识、以 zustand store 为注册中心、以 Ability Context 为数据边界、以useSubscribeToolStore完成与 Bot 详情 store 的同步最终由ToolContainer → ToolItem → ToolItemAction组件树完成渲染。对于希望扩展 Bot 编辑器工具面板或复用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考