coze-studio 前端工程解析：@coze-studio/workspace-adapter 工作空间入口适配包（Develop 与 Library 页面）

• 人工智能
• AI Agent
• 低代码
• RAG
• 后端
• 前端
• 工作流自动化

导读

@coze-studio/workspace-adapter是 coze-studio 前端仓库中承载「工作空间」两个核心入口页面（项目开发台 Develop、资源库 Library）的 React 适配包。本文以该包的 README.md 为主线，结合其源码实现与宿主应用（frontend/apps/coze-studio）的调用链路，讲清楚这个包在工程化上的模板出身、在业务上的页面职责，以及它如何通过 adapter/base 双层结构把"页面编排"与"业务实现"解耦。读完本文，你将掌握该包的目录结构、子路径导出机制、两个入口页面的实现原理与改造入口，并能在本地按标准命令跑通它的开发与检查流程。

包定位：从"React 组件项目模板"长出来的工作台入口

仓库中该包的 README 很短，自述为：

Project template for react component with storybook.

并声明了以下能力清单与命令：

• Features：[x] eslint & ts、[x] esm bundle、[x] umd bundle、[x] storybook
• Commands：init: rush update、dev: npm run dev、build: npm run build

但对照 package.json 可以发现，这个包在仓库中的真实身份远超模板：其description明确写着「工作空间菜单栏入口页面」，版本号为0.0.1，作者为duwenhan@bytedance.com，License 为 Apache-2.0。也就是说，这是一个"从项目模板起步、最终落地为业务入口页"的典型包：模板提供了统一的工程化骨架，业务代码则在骨架之上生长。

从仓库结构看，该包与同目录下的 entry-base 是一对：

这种分层的好处是：业务细节沉淀在 base 包中，adapter 只做"状态装配 + 视图编排"，宿主应用则只负责路由挂载，三层各司其职。

工程化模板能力：eslint & ts、双格式产物与 storybook

README 声明的四项 Features 中，"eslint & ts" 在当前仓库有完整的落地证据：

• eslint.config.js：直接复用@coze-arch/eslint-config的defineConfig，指定packageRoot为包目录、preset: 'web'，rules 留空（表示完全继承仓库统一规则）。
• tsconfig.json 与 tsconfig.misc.json：承接@coze-arch/ts-config的 Web 预设（配合 vitest.config.ts 中的preset: 'web'使用）。
• config/rush-project.json：为test:cov声明coverage产物目录、为ts-check声明dist产物目录，这是 Rush 增量构建的产物缓存配置。

而"esm bundle / umd bundle / storybook"属于模板声明的产物能力。需要特别说明的是：在当前仓库快照中，该包 package.json 的dev与build脚本实际为exit 0（空操作占位），且包内并不存在 storybook 配置目录。结合exports字段把./develop、./library直接指向src/pages/**/*.tsx源码文件来看，可以推断：本包的设计初衷并非"独立打包成 esm/umd 供三方消费"，而是"以源码形式被宿主应用（rsbuild 构建的 coze-studio 应用）直接引用"，真正的打包发生在应用层。因此，若在本文语境下复现 README 的模板命令，需区分两层含义：模板命令是脚手架通用的，而本包在仓库内的实际构建动作由宿主应用完成。

包结构与子路径导出：src/index.ts 的"空壳"与 exports 的"重头戏"

该包目录结构为：

entry-adapter/ ├── config/rush-project.json ├── src/ │ ├── index.ts # 仅含 Apache-2.0 License 头，无实际导出 │ ├── typings.d.ts │ └── pages/ │ ├── develop/index.tsx # Develop 页面 │ └── library/index.tsx # LibraryPage 页面 ├── package.json / tsconfig*.json / eslint.config.js / vitest.config.ts └── README.md

值得注意的细节是 src/index.ts 是一个"空壳"——只有 License 头、没有任何代码导出。真正的对外接口全部定义在 package.json 的exports与typesVersions中：

"exports": { "./develop": "./src/pages/develop/index.tsx", "./library": "./src/pages/library/index.tsx" }, "main": "src/index.ts", "typesVersions": { "*": { "develop": ["./src/pages/develop/index.tsx"], "library": ["./src/pages/library/index.tsx"] } }

即：外部消费者通过@coze-studio/workspace-adapter/develop与@coze-studio/workspace-adapter/library两个子路径分别拿到两个页面组件。这种"空主入口 + 子路径导出"的写法，本质是把包当作一个轻量 facade，只暴露路由级页面，不暴露任何内部实现细节。

宿主应用的挂载也印证了这一点。frontend/apps/coze-studio/src/pages/develop.tsx 与 library.tsx 均从@coze-studio/workspace-adapter/develop、@coze-studio/workspace-adapter/library导入页面，从路由useParams中取出space_id后渲染；随后在 routes/async-components.tsx 中以lazy()异步加载，并注册到 routes/index.tsx 的develop路径与library路径（分别对应SpaceSubModuleEnum.DEVELOP/LIBRARY菜单）。这意味着：只要替换 adapter 内部实现，不修改路由与菜单代码，即可整体换掉工作台两个入口页面的呈现，这正是"入口适配包"一词的含义。

Develop 页面：项目开发台入口的实现拆解

src/pages/develop/index.tsx 导出的Develop: FC<DevelopProps>接收spaceId一个 prop，本身只做"装配"，核心逻辑几乎全部来自@coze-studio/workspace-base/develop（其导出清单见 entry-base/src/pages/develop/index.tsx）。页面结构自上而下为：Header（标题 + 新建按钮）→ SubHeader（三个筛选下拉 + 搜索框）→ Content（项目卡片网格 / 空态 / 加载态）。

1. 筛选参数与搜索

筛选状态由useCachedQueryParams统一管理，默认值定义在 develop-filter-options.ts：

export const FILTER_PARAMS_DEFAULT: FilterParamsType = { searchScope: SearchScope.All, // 全部空间（All）/ 我创建的（CreateByMe） searchValue: '', // 关键词 isPublish: DevelopCustomPublishStatus.All, // 全部 / 已发布 searchType: DevelopCustomTypeStatus.All, // 全部 / 项目 / Agent recentlyOpen: undefined, // 是否"最近打开" };

三个筛选下拉分别对应：

• 类型筛选（TYPE_FILTER_OPTIONS）：全部类型 / 项目 / Agent；
• 创建者筛选（CREATOR_FILTER_OPTIONS）：全部（bot_list_team）/ 我创建的（bot_list_mine），仅在非个人空间（isPersonal === false）时渲染，个人空间直接隐藏该下拉；
• 状态筛选（STATUS_FILTER_OPTIONS）：全部 / 已发布 / 最近打开。

交互上有几个值得注意的联动：切换"我创建的"时会强制清掉recentlyOpen与发布状态筛选；切换状态筛选时会把searchScope强制拉回SearchScope.All；选中"最近打开"时搜索框被禁用（disabled={filterParams.recentlyOpen}）。当某类筛选非默认值时，对应的 Select 会套上highlightFilterStyle高亮样式，提示用户当前处于过滤态。

2. 列表请求：无限滚动 + 取消令牌

列表数据来自 use-intelligence-list.ts，它基于 ahooks 的useInfiniteScroll实现分页加载，内部请求intelligenceApi.GetDraftIntelligenceList，核心参数包括：

• space_id、name（搜索关键词）、types（类型数组）、size（固定每页 24 条）；
• has_published、recently_open、search_scope；
• order_by：来自历史代码的固定逻辑——按"已发布"筛选时用PublishTime，否则用UpdateTime；
• status：固定传入[Using, Banned, MoveFailed]，即只展示在使用中、被封禁、迁移失败三态的草稿智能体；
• 每次新请求都会通过axios.CancelToken.source()重建取消令牌，避免快速切换筛选时旧请求回写污染新列表。

adapter 侧在Develop中把筛选状态映射为请求参数（develop/index.tsx），并额外挂了三件事：useGlobalEventListeners监听全局事件刷新列表、useProjectCopyPolling轮询"项目复制任务"的完成状态（配合BotCard上的onRetryCopy/onCancelCopyAfterFailed卡片操作）、sendTeaEvent(EVENT_NAMES.view_bot)上报页面访问埋点。

3. 卡片网格与空态

数据到达后按响应式网格渲染BotCard：默认 3 列，视口宽度 ≥ 1600px 时切 4 列；卡片上的时间前缀（编辑时间/发布时间/最近打开时间）随当前筛选态切换。删除操作按类型分发：Agent 走deleteIntelligence({ agentId })，项目走deleteIntelligence({ projectId })。无数据时渲染WorkspaceEmpty空态组件，若当前处于过滤态则提供"清除筛选"按钮（onClear恢复FILTER_PARAMS_DEFAULT）；列表底部还会显示"加载中"图标与无更多数据的占位符。

Library 页面：资源库入口的"配置化"装配

src/pages/library/index.tsx 导出的LibraryPage只做一件事：把五类资源的实体配置（entityConfig）组合起来，喂给 base 包里的通用资源列表页BaseLibraryPage。

五类资源及其 Hook 来源（均在 entry-base/src/pages/library/hooks/use-entity-configs 下）：

• 插件：usePluginConfig
• 工作流：useWorkflowConfig
• 知识库：useKnowledgeConfig
• 提示词：usePromptConfig
• 数据库：useDatabaseConfig

每个 config Hook 接收{ spaceId, reloadList }公共参数，返回{ config, modals }：modals是各类资源自带的弹窗（如新建插件的表单弹窗、插件代码编辑弹窗）；config则实现LibraryEntityConfig接口，描述该资源在列表页中的类型筛选项、新建菜单项、点击跳转、行内操作与默认图标。

以 use-plugin-config.tsx 为例，插件实体的 config 包含：

• typeFilter：{ label: '插件', value: ResType.Plugin }，用于合并进列表页的类型筛选下拉；
• renderCreateMenu：渲染"新建插件"菜单项，点击后弹出CreateFormPluginModal，创建成功后跳转/space/{spaceId}/plugin/{pluginID}并刷新列表；
• onItemClick：对res_sub_type === 2（App 类插件）的条目打开插件代码编辑弹窗（useBotCodeEditOutPlugin），其余跳转插件详情页；
• renderItem：渲染资源条目卡片，对PluginType.LOCAL本地插件额外打上青色"本地插件"标签；
• renderActions：渲染行内操作，包含受ActionKey.Delete权限控制的删除动作，删除走PluginDevelopApi.DelPlugin后reloadList()并 Toast 提示。

而 base 侧的 BaseLibraryPage 通过useInfiniteScroll调用PluginDevelopApi.LibraryResourceList拉取混排列表：请求参数先以{ ...params, cursor, space_id, size }打底（LIBRARY_PAGE_SIZE控制分页大小），再依次经过各实体的parseParams回调做业务自定义，随后把resource_list/cursor/has_more映射为 ahooks 的列表结构；reloadList通过forwardRef+useImperativeHandle暴露给 adapter 层的 config Hook，从而在"新建/删除/编辑"任一动作完成后都能刷新整个混排列表。adapter 侧还额外把pluginModals、workflowModals、knowledgeModals、promptModals、databaseModals全部渲染在BaseLibraryPage之后，保证弹窗挂载点在页面内。

本地开发与质量门禁

回到 README 的命令清单，结合仓库实际配置，该包及所在 workspace 的常用流程如下：

• 初始化依赖：rush update（Rush 管理，workspace:*依赖如@coze-studio/workspace-base均通过工作区协议链接，详见 package.json）；
• 静态检查：npm run lint（eslint + 缓存）；
• 单元测试：npm run test（vitest，--passWithNoTests保证无用例时也通过）、npm run test:cov（生成覆盖率产物）；
• 构建/开发：模板语义下为npm run dev/npm run build，而本包内的这两个脚本是exit 0占位——真正的页面渲染由宿主应用frontend/apps/coze-studio（rsbuild 构建）消费源码完成。

质量配置上，包还复用了@coze-arch/eslint-config的preset: 'web'、@coze-arch/vitest-config的preset: 'web'，并在源码中显式声明行数上限（max-lines-per-function500 行）与complexity禁用注释，以保证页面装配代码的可维护性。

小结

@coze-studio/workspace-adapter是一个麻雀虽小、分层清晰的入口适配包：工程化层面继承仓库统一的 eslint/ts/vitest 模板（README 所声明的 esm/umd/storybook 能力在当前仓库中已退化为源码直引模式）；业务层面通过子路径导出develop与library两个路由级页面，分别基于workspace-base的useIntelligenceList无限滚动列表和BaseLibraryPage实体配置化混排实现。对需要定制工作台入口页的开发者而言，改造路径非常明确：要么在 adapter 层调整页面编排（换 Hook、调布局），要么深入 entry-base 修改业务能力实现，宿主路由与菜单无需任何改动。

• 人工智能
• AI Agent
• 低代码
• RAG
• 后端
• 前端
• 工作流自动化