Coze Studio后端遵循**领域驱动设计（DDD）**的原则，将业务逻辑组织到清晰定义的领域边界中。本文档深入探讨了核心领域实体的结构、它们之间的关系以及它们如何协同工作以支持应用程序的功能。
领域模型代表了Coze Studio中的核心业务概念、规则和关系。它被组织成不同的有界上下文，代表应用程序功能的不同方面。
Coze Studio的领域模型具有清晰的关注点分离：
每个领域遵循一致的结构：
App实体代表一个可以在Coze Studio中构建、配置和发布的应用程序。应用连接到各种资源，如连接器和工作流。
typeAPPstruct{ID int64SpaceIDint64IconURI *stringName *stringDesc *stringOwnerIDint64ConnectorIDs []int64Version *stringVersionDesc *stringPublishRecordID *int64PublishStatus *PublishStatusPublishExtraInfo *PublishRecordExtraInfoCreatedAtMS int64UpdatedAtMS int64PublishedAtMS *int64}
PublishStatus枚举表示应用在发布工作流中的当前状态：typePublishStatusintconst(PublishStatusOfPacking PublishStatus =0PublishStatusOfPackFailed PublishStatus =1PublishStatusOfAuditing PublishStatus =2PublishStatusOfAuditNotPass PublishStatus =3PublishStatusOfConnectorPublishing PublishStatus =4PublishStatusOfPublishDone PublishStatus =5)
Workflow实体代表一个流程图式的结构，定义了机器人如何处理信息并响应用户输入。工作流是Coze Studio中的核心概念，定义了机器人的智能和行为。
typeWorkflowstruct{ID int64CommitIDstring*vo.Meta*vo.CanvasInfo*vo.DraftMeta*vo.VersionMeta}
typeMetastruct{// 不可变字段SpaceID int64CreatorID int64CreatedAt time.TimeContentType ContentTypeTag *TagAppID *int64SourceID *int64AuthorID int64// 可变字段Name stringDesc stringIconURI stringIconURL stringMode ModeUpdatedAt *time.TimeUpdaterID *int64DeletedAt *time.TimeHasPublished boolLatestPublishedVersion *string}
typeStageuint8const(StageDraft Stage =1StagePublished Stage =2)
Conversation实体模拟用户和机器人之间的互动。对话由多条消息组成，为持续对话提供上下文。
typeConversation = conversation.ConversationtypeCreateMetastruct{AgentID int64 `json:"agent_id"`UserID int64 `json:"user_id"`ConnectorIDint64 `json:"connector_id"`Scene common.Scene`json:"scene"`Ext string `json:"ext"`
对话领域进一步分为子领域：
Coze Studio的核心领域是相互关联的，形成一个紧密的系统。以下图表展示了这些关系：
Coze Studio中的值对象代表不可变的概念，没有自己的身份。这些包括：
聚合是作为单个单元处理的领域对象集群。Coze Studio中的主要聚合包括：
应用聚合：
工作流聚合：
对话聚合：
领域服务实现不属于特定实体的业务逻辑。它们协调跨多个实体的操作并维护领域不变性。
Coze Studio中的关键领域服务包括：
应用服务：
工作流服务：
对话服务：
每个领域都有相应的仓库来处理持久化问题。仓库遵循一致的接口模式：
typeRepositoryinterface{Create(ctxcontext.Context,entity*Entity)errorGet(ctxcontext.Context,idint64)(*Entity,error)Update(ctxcontext.Context,entity*Entity)errorDelete(ctxcontext.Context,idint64)error}这种抽象确保领域逻辑与特定的存储实现保持解耦。
来源：app/repository, workflow/repository
Coze Studio定义了多种可以在应用和工作流中使用的资源类型：
typeResourceTypestringconst(ResourceTypeOfPlugin ResourceType="plugin"ResourceTypeOfWorkflowResourceType="workflow"ResourceTypeOfKnowledgeResourceType="knowledge"ResourceTypeOfDatabaseResourceType="database")
为了说明领域实体如何交互，让我们考察应用发布过程：
PublishStatus设置为PublishStatusOfPackingPublishStatusOfPackFailedPublishStatusOfAuditingPublishStatusOfAuditNotPass或PublishStatusOfConnectorPublishingPublishStatusOfPublishDone此过程涉及多个领域实体和服务协同工作，确保正确的状态转换和业务规则得到遵循。
Coze Studio的领域模型展示了清晰的关注点分离和不同领域之间明确的边界。领域实体设计用于捕捉核心业务概念，同时避免不必要的耦合。
在扩展系统时，重要的是维护这些领域边界，并确保新功能与现有架构保持一致。通过理解领域模型的构建方式，您将更好地装备自己，以做出维护系统完整性的更改。
Coze Studio后端采用结构化的、领域驱动的方法来实现服务。本指南解释了在平台上实现服务的模式、架构和最佳实践，提供了概念理解和实际实施指导。
Coze Studio采用分层服务架构，促进了关注点分离、依赖管理和领域隔离。系统将服务组织成三个层级：
服务实现遵循结构化的层级，有助于管理依赖和初始化顺序：
这一层级在应用初始化代码中定义清晰，服务按顺序初始化：
// 服务初始化流程funcInit(ctx context.Context)(errerror) {// 1. 初始化基础设施infra, err := appinfra.Init(ctx)// 2. 初始化基础服务basicServices, err := initBasicServices(ctx, infra, eventbus)// 3. 初始化主要服务primaryServices, err := initPrimaryServices(ctx, basicServices)// 4. 初始化复杂服务complexServices, err := initComplexServices(ctx, primaryServices)// 5. 注册跨领域服务crossconnector.SetDefaultSVC(connectorImpl.InitDomainService(...))// ... 更多跨领域服务注册}
每个服务使用ServiceComponents结构体来清晰管理依赖。这种模式：
以下是会话服务的典型示例：
// 服务组件包含所有依赖typeServiceComponentsstruct{IDGen idgen.IDGeneratorDB *gorm.DBTosClient storage.StorageImageX imagex.ImageXSingleAgentDomainSVC singleagent.SingleAgent}// 使用组件初始化服务funcInitService(s *ServiceComponents)*ConversationApplicationService {// 使用依赖初始化领域服务messageDomainSVC := message.NewService(&message.Components{MessageRepo: msgRepo.NewMessageRepo(s.DB, s.IDGen),})// 配置并返回应用服务ConversationSVC.MessageDomainSVC = messageDomainSVC// ... 更多配置returnConversationSVC}
服务实现遵循领域驱动设计方法，明确区分：
领域服务实现核心业务逻辑和领域规则：
/backend/domain/{domain}/service应用服务协调各领域并向API层暴露功能：
/backend/application/{domain}让我们看看这种架构在会话服务中的实际应用：
服务结构：
ConversationApplicationServiceAgentRunDomainSVC、ConversationDomainSVC、MessageDomainSVC方法实现：
CreateConversation方法：func(c *ConversationApplicationService)CreateConversation(ctx context.Context,agentIDint64, connectorIDint64) (*conversation.CreateConversationResponse,error) {// 1. 提取认证信息apiKeyInfo := ctxutil.GetApiAuthFromCtx(ctx)userID := apiKeyInfo.UserID// 2. 应用业务规则ifconnectorID != consts.WebSDKConnectorID {connectorID = apiKeyInfo.ConnectorID}// 3. 使用领域实体调用领域服务conversationData, err := c.ConversationDomainSVC.Create(ctx, &entity.CreateMeta{AgentID: agentID,UserID: userID,ConnectorID: connectorID,Scene: common.Scene_SceneOpenApi,})// 4. 将领域实体转换为API响应resp.ConversationData = &conversation.ConversationData{Id: conversationData.ID,LastSectionID: &conversationData.SectionID,ConnectorID: &conversationData.ConnectorID,CreatedAt: conversationData.CreatedAt,}returnresp,nil}
服务通常需要跨领域边界通信。Coze Studio通过跨领域服务注册表处理：
/backend/crossdomain/contract的接口/backend/crossdomain/impl的适配器//跨领域服务注册crossconnector.SetDefaultSVC(connectorImpl.InitDomainService(basicServices.connectorSVC.DomainSVC))crossdatabase.SetDefaultSVC(databaseImpl.InitDomainService(primaryServices.memorySVC.DatabaseDomainSVC))//...更多注册
这种方法保持了清晰的架构，有助于防止领域逻辑泄露到应用服务中。
向系统中添加新服务时，遵循以下步骤：
ServiceComponents结构体// 示例：添加新的主要服务funcinitPrimaryServices(ctx context.Context, basicServices *basicServices)(*primaryServices,error) {// 现有服务...// 添加你的新服务myNewSVC := mynewservice.InitService(basicServices.toMyNewServiceComponents())return&primaryServices{// 现有服务...myNewSVC: myNewSVC,},nil}
服务实现架构支持清晰的测试方法：
funcTestMyService(t *testing.T){// 创建模拟依赖mockRepo := &MockRepository{}// 使用模拟组件初始化服务svc := NewService(&Components{Repo: mockRepo,})// 测试服务方法result, err := svc.DoSomething(ctx, input)// 断言结果assert.NoError(t, err)assert.Equal(t, expected, result)}
Coze Studio中的服务实现架构提供了一种清晰、可维护的方法来构建后端功能。通过遵循既定模式——服务层级、组件模式和领域驱动设计——你可以创建结构良好、可测试和可维护的服务。
在实现新功能时，首先理解领域模型，然后构建实现核心业务逻辑的领域服务，最后创建协调各领域的应用服务，以向用户交付功能。
Coze Studio的API路由遵循层次结构，包含几个顶层组：
Coze Studio的主要功能组织成以下API组：
每个组处理系统内的特定功能域：
/api/conversation)/api/knowledge)/api/memory)/api/plugin_api)/api/workflow_api)Coze Studio的API主要使用两种HTTP方法：
API端点通常遵循以下命名模式：
API包含几种认证机制：
这些通过中间件实现，在请求到达处理器之前进行处理：
/api/passport和/api/permission_api组中。对于公网API访问，Coze Studio在/v1路径下提供OpenAPI兼容端点：
/v1/conversations/v1/conversation/:id/v1/workflow/v1/files这些端点遵循更标准的RESTful约定，专为外部集成设计。
对话APIs处理聊天交互和消息管理：
知识APIs管理文档存储和检索：
工作流APIs支持创建和执行代理工作流：
插件APIs处理外部工具的集成和管理：
API通过一致的响应格式实现标准化错误处理：
{"code":400,"msg":"错误消息详情","data":null}错误响应包括：
API端点作为处理器实现在backend/api/handler/coze目录中。每个处理器遵循一致的模式：
处理器与应用层和领域层交互以执行业务逻辑，同时保持关注点分离。
API使用多个中间件组件处理横切关注点：
Coze Studio API提供了一个全面且结构化的接口，用于与平台的所有方面交互。关键特性包括：
理解这一结构使开发者能够高效地定位、使用和扩展API，以应对各种集成场景。
Coze Studio的前端基于模块化、组织良好的组件架构构建，支持可扩展开发和一致的用户体验。本文档探讨了Coze Studio前端组件的组织结构、设计模式和最佳实践。
Coze Studio前端采用Rush构建的单一代码库（monorepo）结构，组件根据其用途和功能组织到不同的包中。组件架构遵循现代React模式，重点在于可重用性、组合性和可维护性。
主要组件组织在packages/components目录中，每个组件设计为独立的包，具有一致的结构：
每个组件包遵循一致的结构：
src/__tests__/stories/Coze Studio基于Semi Design UI框架构建，并在bot-semi包中进行定制。这种方法在提供一致性的同时，也允许满足应用特定的设计需求。
bot-semi包包括：
组件按照层级结构组织：
前端架构广泛使用适配器模式，这在以下包中尤为明显：
account-adapterspace-store-adapterbot-hooks-adapter这种模式将组件与具体实现解耦，使得以下操作更容易：
组件通过以下方式通信：
组件架构包括多种状态管理方法：
Coze Studio采用混合样式方法：
CSS Modules：组件特定样式，自动作用域
// CSS Modules示例用法importstylesfrom'./component.module.less';functionComponent() {return<divclassName={styles.container}>内容</div>;}
//Tailwind示例用法functionComponent(){return<divclassName="flexp-4bg-whiteroundedshadow">内容</div>;}Semi Design主题化：通过设计系统实现一致的主题
主应用（apps/coze-studio）集成来自各个包的组件，构建完整的用户界面：
前端包括多个开发工具，以增强组件开发体验：
Coze Studio的组件架构遵循React应用的现代最佳实践，重点在于模块化、可重用性和可维护性。通过理解这一架构，开发者可以有效地为项目做出贡献，创建无缝集成的全新组件，并在整个应用中保持一致性。
关键要点：
bot-semi中进行定制架构遵循几个关键原则：
主应用程序位于apps/coze-studio目录，是整个系统的入口点。
应用程序从index.tsx开始，执行以下步骤：
// index.tsx的简化版本constmain= () => {// 初始化功能标志initFlags();// 初始化i18ninitI18nInstance({lng: (localStorage.getItem('i18next') ?? (IS_OVERSEA?'en':'zh-CN'))});// 加载样式dynamicImportMdBoxStyle();const$root =document.getElementById('root');constroot =createRoot($root);root.render(<App/>);};main();
App组件随后设置路由提供者和代码拆分的悬念边界：//app.tsx的简化版本exportfunctionApp(){return(<Suspensefallback={<Loading/>}><RouterProviderrouter={router}fallbackElement={<div>加载中...</div>}/></Suspense>);}Coze Studio使用React Router，采用嵌套结构组织导航。路由在routes.tsx中定义，遵循层次模式：
路由系统通过lazy()函数实现代码拆分，按需加载组件，提高初始加载性能。每个路由定义加载器，指定：
应用程序使用分层的布局系统，包含不同级别的布局组件：
//主布局组件exportconstLayout=()=>{useAppInit();//初始化应用程序状态/数据return<GlobalLayout/>;};前端在packages目录中组织为多个包，每个包有特定的职责：
许多包遵循适配器模式，以-adapter后缀的包作为不同模块间的集成点。这种模式促进松耦合，便于修改实现细节而不影响使用者。
以studio包为例，看看模块是如何组织的：
每个模块通常遵循标准结构：
src/__tests__/为了优化性能，Coze Studio广泛使用代码拆分和懒加载。这通过React的lazy()函数和Suspense组件实现：
// routes.tsx中的示例constAgentIDE=lazy(() =>import('@coze-agent-ide/entry-adapter').then(res=>({default: res.BotEditor,})),);// 在路由中使用{path:'bot/:bot_id',Component:AgentIDELayout,children: [{index:true,Component:AgentIDE,// 懒加载组件},// ...]}
前端使用强大的配置系统，针对不同工具有专门的配置：
Coze Studio的前端架构遵循现代React模式，重点在于：
理解这一结构将帮助您导航代码库，定位特定功能，并在添加新功能或进行更改时遵循既定模式。
在Coze Studio中，状态管理对于处理跨组件的复杂应用数据和UI状态至关重要。本文档解释了前端使用的状态管理架构，为开发者提供了一个全面指南，以有效管理应用状态。
Coze Studio采用了一种混合状态管理方法，结合Zustand进行存储创建和React Context进行存储分发。这种模式提供了一种强大且灵活的方式来管理整个应用的状态。
这种架构提供了多项好处：
Zustand是一个轻量级状态管理库，为Coze Studio的状态管理提供动力。存储通过工厂函数创建，封装了状态和操作。
// 存储工厂模式exportconstcreateSomeStore= (initialState) =>create<StateType&ActionsType>()(devtools((set, get) =>({// 初始状态...initialState,// 修改状态的操作someAction) =>{
set({/* 更新后的状态 */});}})),);
exportconstcreateProcessingKnowledgeStore=()=>create<rocessingKnowledgeInfo&
存储实例通过React Context提供者分发，允许树中的任何组件访问它们。
// 示例Context提供者exportconstSomeStoreProvider:FC<conststoreRef = useRef<StoreType>();if(!storeRef.current) {storeRef.current=createSomeStore(initialState);}return(<SomeStoreContext.Providervalue={{someStore:storeRef.current}}>{children}</SomeStoreContext.Provider>);};
KnowledgeParamsStoreProvider展示了这种模式：exportconstKnowledgeParamsStoreProvider:FC<PropsWithChildren<{params:IParams;onUpdateDisplayName?onStatusChange?resourceNavigateluginNavType;
}>> =({children,params,onUpdateDisplayName,onStatusChange,resourceNavigate,}) => {constparamsStoreRef = useRef<constknowledgeStoreRef = useRef<KnowledgePreviewStore>();constprocessingStoreRef = useRef<paramsStoreRef.current=createParamsStore(params);if(!knowledgeStoreRef.current) {knowledgeStoreRef.current=createKnowledgePreviewStore({version: params.version,});}if(!processingStoreRef.current) {processingStoreRef.current=createProcessingKnowledgeStore();}return(<KnowledgeParamsStoreContext.Providervalue={{paramsStore:paramsStoreRef.current,knowledgeStore:knowledgeStoreRef.current,processingKnowledge:processingStoreRef.current,callbacks:{onUpdateDisplayName,onStatusChange},resourceNavigate,}}>{children}</KnowledgeParamsStoreContext.Provider>);};
自定义钩子为组件访问存储状态和操作提供了一个干净的API：
exportconstuseSomeStore = <T>(selectorconstcontext =useContext(SomeStoreContext);if(!context.someStore) {thrownewError('存储不可用');}returnuseStoreWithEqualityFn(context.someStore, selector, shallow);};
useKnowledgeParamsStore的钩子实现这种模式：exportconstuseKnowledgeParamsStore: <T>(selector: (store: IParamsStore) => T,) => T =selector=>{constcontext =useContext(KnowledgeParamsStoreContext);if(!context.paramsStore) {thrownewCustomError(REPORT_EVENTS.normalError,'params store context');}returnuseStoreWithEqualityFn(context.paramsStore, selector, shallow);};
要在组件中访问状态，使用自定义钩子并传入选择器函数：
// 访问特定状态片段constisProcessing =useProcessingStore(store=>store.getIsProcessing(datasetId));// 访问多个状态值const{ processingDatasets } =useProcessingStore(store=>({processingDatasets: store.processingDatasets}));// 通过调用操作更新状态const{ addProcessingDataset } =useProcessingStore(store=>({addProcessingDataset: store.addProcessingDataset}));// 在组件中稍后consthandleProcess= () => {addProcessingDataset(datasetId);};
Coze Studio将状态组织到特定领域的存储中：
Zustand支持中间件以增强存储功能。Coze Studio使用：
对于复杂状态，Coze Studio使用切片来组织相关状态和操作：
Coze Studio中的Zustand存储集成了Redux DevTools，允许你：
要启用此功能：
devtools中间件时，状态变化将自动跟踪调试状态问题时：
Coze Studio的状态管理架构结合了Zustand的简洁性和React Context的分发能力。这种混合方法允许：
代理开发是Coze Studio的核心能力，允许你创建具有自定义行为、知识和技能的AI助手。本指南将引导你了解在Coze Studio平台中构建、测试和部署智能代理的过程。
在Coze Studio中，代理是一个具有特定目的、个性和能力的自主AI助手。每个代理包括：
Coze Studio中的代理开发遵循草稿-发布工作流。你首先创建和配置一个草稿，彻底测试后，再将其发布以供使用。
//创建代理的后端实现funcCreateSingleAgentDraft(ctxcontext.Context,creatorIDint64,draft*entity.SingleAgent)(agentIDint64,errerror){returns.AgentDraftRepo.Create(ctx,creatorID,draft)}Coze Studio的代理-IDE提供了一个综合界面，用于配置代理的所有方面。
选择适合代理需求的适当语言模型：
提示词是塑造代理行为的核心指令集。Coze Studio提供了一个专门的提示词编辑器，允许你：
插件扩展了代理的对话能力，使其能够执行操作和访问外部数据：
通过集成知识库，增强代理的特定知识：
对于复杂的、多步骤的过程，集成工作流，引导代理通过结构化决策树：
Coze Studio提供了全面的工具，用于在部署前测试你的代理：
使用内置聊天界面测试代理的响应：
运行代理时，你可以访问详细的事件日志，了解其处理请求的方式：
//代理执行的后端实现funcStreamExecute(ctxcontext.Context,req*entity.ExecuteRequest)(events*schema.StreamReader[*entity.AgentEvent],errerror){//实现细节...}执行跟踪包括以下事件：
创建和测试完代理后，你可以将其发布以供使用：
系统会创建代理的版本化快照：
//列出已发布版本funcListAgentPublishHistory(ctxcontext.Context,agentIDint64,pageIndex,pageSizeint32,connectorID*int64)([]*entity.SingleAgentPublish,error){//实现细节...}Coze Studio为每个代理维护已发布版本的历史记录：
配置代理以向用户提供上下文相关的建议回复，增强对话流程并引导用户进行有效互动。
来源：single_agent.go#L78
通过背景图自定义代理聊天界面的视觉外观。
来源：single_agent.go#L80, chat-background/
创建自定义命令，用户可以通过输入这些命令来触发特定的代理行为：
//代理包含快捷命令typeSingleAgentstruct{//其他字段...ShortcutCommand[]string}在配置前定义代理的特定目的。专注的代理比通用型代理表现更好。
用各种输入测试你的代理，包括：
Coze Studio中的代理开发结合了提示词工程、插件集成、知识管理和工作流编排，以创建强大的AI助手。通过遵循本指南中的实践，你可以创建为用户带来价值的同时保持可靠性和性能的代理。
对于复杂的代理场景，考虑探索工作流系统文档，以构建扩展代理能力的复杂多步骤过程。
Coze Studio中的工作流系统是一个强大的编排引擎，允许用户通过可视化画布界面创建、测试和执行复杂的自动化工作流。本文探讨了工作流系统的功能、架构以及开发者如何利用它构建复杂的AI驱动应用。
核心上，工作流系统提供了一个可视化编程环境，用户可以在此定义一系列相互连接的节点来表示具体操作或逻辑。这些工作流可以执行从简单文本处理到集成AI模型的复杂决策树等多种任务。
该系统基于一个全面的领域模型构建，包括工作流定义、执行引擎、节点类型以及一个用于持久化的健壮存储库。它支持同步和流式执行模式，适用于实时应用。
系统的基本构建块是“工作流”实体，包括：
每个工作流属于特定的空间，并可选择性关联到一个应用。
画布是工作流的可视化设计场所，表示一个有向图：
工作流系统提供了丰富的节点类型用于不同操作：
工作流的执行由“工作流运行器”协调：
系统支持同步执行和流式输出，允许与长时间运行的工作流进行实时交互。
工作流系统的一个重要特性是能够处理中断并恢复执行。这对于以下工作流尤其有价值：
中断机制工作原理如下：
工作流系统的前端部分提供了用于创建和管理工作流的可视化编辑器：
画布编辑器使用基于fabric的实现，允许直观地操作节点和连接。
工作流系统使用存储库模式进行持久化：
存储库接口抽象了存储实现，允许根据部署需求使用不同的后端。
系统的一个强大功能是将工作流暴露为工具，供其他组件或工作流使用：
这促进了模块化和可重用性，允许从更简单的构建块构建复杂工作流。
在使用工作流系统时，考虑以下最佳实践：
开发者可以通过以下方式扩展工作流系统：
Coze Studio中的工作流系统提供了一个强大的框架，通过可视化编程创建复杂的AI驱动流程。通过理解其架构和能力，开发者可以利用该系统构建结合AI模型、数据处理和外部集成的复杂应用，且具有可维护性和可扩展性。
无论你是在构建对话代理、数据处理管道还是复杂决策系统，工作流系统都提供了足够的灵活性和强大功能，将你的想法变为现实。
| 欢迎光临 链载Ai (https://www.lianzai.com/) | Powered by Discuz! X3.5 |