OneCode 3.0 微内核引擎 基础注解驱动速查手册（通讯及服务治理）

前言

在现代软件开发中，注解驱动开发已成为提升效率、简化配置的核心范式之一。onecode 3.0框架深度整合注解技术，通过声明式编程替代传统XML配置，实现了业务逻辑与框架能力的解耦。本手册系统梳理了onecode 3.0生态中的28个核心注解，涵盖AI服务、工作流引擎、MCP通信，Agent代理、Web开发及ESB服务六大领域，为开发者提供一站式注解查询与应用指南。

基础主注解（如@EsbBeanAnnotation、@AIGCTask）的设计遵循单一职责原则，通过元数据标注实现Bean自动注册、依赖注入与生命周期管理。其核心目的包括：1）消除样板代码，将配置逻辑内聚到注解属性中；2）构建可扩展的注解体系，支持自定义属性与继承关系；3）实现零配置启动，通过注解扫描自动装配组件。无论是快速开发微服务接口，还是构建复杂的工作流引擎，本手册都将成为您高效使用onecode 3.0注解生态的必备参考。

一、AI服务相关注解

1.1 分类描述

AI服务相关注解体系提供了对人工智能任务全生命周期的配置与管理能力，涵盖模型定义、任务调度、安全控制、提示工程和数据处理五大核心维度。该体系采用分层设计，以@AIGCTask为核心，协同其他注解形成完整的AI服务配置闭环，支持医疗等高敏感场景的合规性要求。

1.2 注解关系结构

@AIGCTask ← 核心任务注解
  ↑     ↑
  │     │
  ├─────┼───── @AIGCModel ← 模型配置
  │     │
  ├─────┼───── @AIGCSecurity ← 安全策略
  │     │
  ├─────┼───── @AIGCPrompt ← 提示工程
  │     │
  └─────┴───── @AIGCData ← 数据处理

1.3 核心注解详解

@AIGCTask

功能描述：定义AI任务的基本属性和执行策略，是AI服务体系的核心注解

属性说明：

属性名	类型	描述	默认值
taskId	String	任务唯一标识符	空
name	String	任务名称	空
description	String	任务详细描述	空
modelId	String	关联模型ID	空
timeout	int	超时时间(秒)	300
retryCount	int	失败重试次数	0
cacheConfig	String	缓存配置策略	空
cpuQuota	int	CPU资源配额(核)	1
memoryQuota	int	内存配额(MB)	2048
gpuQuota	int	GPU资源配额	0
dependencies	String[]	依赖任务ID列表	空数组

使用示例：

@AIGCTask(
    taskId = "medical_report_analysis",
    name = "医疗报告分析任务",
    description = "基于AI模型分析患者医疗报告并生成诊断建议",
    modelId = "medgpt-4.0-clinical",
    timeout = 600,
    retryCount = 2,
    cpuQuota = 4,
    memoryQuota = 8192,
    gpuQuota = 1,
    dependencies = {"data_preprocessing_task"}
)
public class MedicalReportAnalysisTask {
    // 任务实现逻辑
}

@AIGCModel

功能描述：配置AI模型的基础信息和连接参数

属性说明：

属性名	类型	描述	默认值
modelId	String	模型唯一标识符	空
modelName	String	模型名称	空
provider	String	模型提供商	空
version	String	模型版本号	空
endpoint	String	模型服务端点URL	空
apiKey	String	访问密钥	空
parameters	String	模型参数配置(JSON格式)	空

使用示例：

@AIGCModel(
    modelId = "medgpt-4.0-clinical",
    modelName = "医疗专用GPT-4模型",
    provider = "DeepHealth",
    version = "4.0.1",
    endpoint = "https://api.deephealth.ai/medgpt/v4",
    parameters = "{\"temperature\":0.3,\"top_p\":0.9,\"max_tokens\":2048}"
)
public class MedicalGPTModelConfig {
    // 模型配置实现
}

二、工作流相关注解

2.1 分类描述

工作流注解体系提供了业务流程的可视化定义能力，支持串行、并行、条件分支等复杂流程控制。该体系以@Workflow为根节点，通过@WorkflowStep定义步骤，结合@Condition和@Parallel注解实现灵活的流程编排，适用于医疗诊断流程、审批流程等场景。

2.2 注解关系结构

@Workflow ← 工作流根注解
  │
  ├─ @WorkflowStep ← 步骤定义注解
  │    │
  │    ├─ @Condition ← 条件分支注解
  │    │
  │    └─ @Parallel ← 并行执行注解
  │
  └─ @WorkflowListener ← 流程监听器注解

2.3 核心注解详解

@Workflow

功能描述：定义完整工作流的基本信息和全局属性

属性说明：

属性名	类型	描述	默认值
workflowId	String	工作流唯一ID	空
name	String	工作流名称	空
description	String	工作流描述	空
type	WorkflowType	工作流类型	WorkflowType.SEQUENTIAL
timeout	int	超时时间(分钟)	5
retryCount	int	失败重试次数	0
enabled	boolean	是否启用	true
listener	Class<?>	监听器类	Object.class

使用示例：

@Workflow(
    workflowId = "patient_diagnosis_flow",
    name = "患者诊断工作流",
    description = "完整的患者诊断流程，包含症状采集、初步诊断和专家会诊",
    type = WorkflowType.STATE_MACHINE,
    timeout = 30,
    retryCount = 0,
    listener = DiagnosisWorkflowListener.class
)
public class PatientDiagnosisWorkflow {
    // 工作流定义
}

@WorkflowStep

功能描述：定义工作流中的单个执行步骤

属性说明：

属性名	类型	描述	默认值
stepId	String	步骤ID	空
name	String	步骤名称	空
description	String	步骤描述	空
type	StepType	步骤类型	StepType.ACTION
actionClass	Class<?>	动作实现类	Object.class
nextSteps	String[]	后续步骤ID	空数组
timeout	int	步骤超时时间(秒)	60
order	int	执行顺序	0

使用示例：

@WorkflowStep(
    stepId = "symptom_collection",
    name = "症状采集步骤",
    description = "采集患者主诉和临床症状",
    type = StepType.ACTION,
    actionClass = SymptomCollectionAction.class,
    nextSteps = {"preliminary_diagnosis"},
    timeout = 120,
    order = 1
)
public class SymptomCollectionStep {
    // 步骤实现
}

三、MCP通信相关注解

3.1 分类描述

MCP(微服务通信协议)注解体系提供了服务间通信的标准化配置方式，实现了服务注册、负载均衡、协议转换等功能。该体系采用三级结构：@MCPServerAnnotation定义服务端，@MCPClientAnnotation定义客户端，@MCPMethodAnnotation定义方法级通信细节，支持HTTP、RPC等多种协议。

3.2 注解关系结构

@MCPServerAnnotation ← 服务端注解
    ↑
    │
    └─ @MCPMethodAnnotation ← 方法级注解
        ↑
        │
@MCPClientAnnotation ← 客户端注解

3.3 核心注解详解

@MCPClientAnnotation

功能描述：配置微服务客户端的连接参数和调用策略

属性说明：

属性名	类型	描述	默认值
serviceId	String	服务ID	空
protocol	ProtocolType	通信协议	ProtocolType.HTTP
loadBalance	String	负载均衡策略	"round_robin"
timeout	int	超时时间(毫秒)	3000
retries	int	重试次数	1
fallbackClass	Class<?>	降级处理类	Object.class
url	String	服务地址(直连模式)	空

使用示例：

@MCPClientAnnotation(
    serviceId = "patient-service",
    protocol = ProtocolType.HTTP,
    loadBalance = "weighted_round_robin",
    timeout = 5000,
    retries = 2,
    fallbackClass = PatientServiceFallback.class
)
public interface PatientServiceClient {
    // 客户端方法定义
}

四、Web相关注解

4.1 分类描述

Web相关注解体系提供了Web层组件的声明式配置，涵盖UI控制、动态行为、数据绑定等功能。该体系分为三大类：UI控制注解（如@Caption、@Hidden）用于页面元素展示控制；动态行为注解（如@DynLoad、@DynCheck）用于实现组件的动态加载与验证；持久层和视图层注解（如@RepositoryAnnotation、@View）用于数据访问和视图映射。

4.2 注解关系结构

Web相关注解
  ├── UI控制注解
  │    ├── @Aggregation
  │    ├── @Caption
  │    ├── @DirtyMask
  │    ├── @Disabled
  │    ├── @Folded
  │    ├── @Hidden
  │    ├── @Locked
  │    └── @Modal
  │
  ├── 动态行为注解
  │    ├── @DynCheck
  │    ├── @DynLoad
  │    └── @ESDEntity
  │
  └── 持久层和视图层注解
       ├── @RepositoryAnnotation
       └── @View

4.3 核心注解详解

@Aggregation

功能描述：定义领域模型的聚合关系，支持复杂数据结构的视图展示

属性说明：

属性名	类型	描述	默认值
domainId	String	领域ID	空
moduleName	String	模块名称	空
userSpace	String[]	用户空间数组	空数组
type	AggregationType	聚合类型	AggregationType.ENTITY
entityClass	Class<?>	实体类	Object.class
sourceClass	Class<?>	源数据类	Object.class
rootClass	Class<?>	根实体类	Object.class

使用示例：

@Aggregation(
    domainId = "patient_domain",
    moduleName = "patient_management",
    userSpace = {"doctor", "admin"},
    type = AggregationType.TREE,
    entityClass = PatientEntity.class,
    sourceClass = PatientDataSource.class,
    rootClass = MedicalRecordRoot.class
)
public class PatientAggregation {
    // 聚合实现
}

@DynLoad

功能描述：实现页面组件的动态加载，支持按需加载以提升性能

属性说明：

属性名	类型	描述	默认值
viewInstanceId	String	视图实例ID	空
sourceClass	Class<?>	数据源类	Object.class
rootClass	Class<?>	根数据类	Object.class
lazyLoad	boolean	是否延迟加载	true
cacheable	boolean	是否可缓存	false

使用示例：

@DynLoad(
    viewInstanceId = "patient_medical_history",
    sourceClass = MedicalHistoryDataSource.class,
    rootClass = PatientRoot.class,
    lazyLoad = true,
    cacheable = true
)
public class MedicalHistoryComponent {
    // 动态加载组件实现
}

五、ESB相关注解

5.1 分类描述

ESB(企业服务总线)注解体系提供了服务集成和流程编排的配置能力，支持服务注册、消息路由、数据转换等企业级集成功能。该体系以@EsbBeanAnnotation为核心，配合@EsbConstructor、@EsbRequest等注解实现服务的完整生命周期管理，支持本地和远程服务的统一调用。

5.2 注解关系结构

@EsbBeanAnnotation ← ESB核心注解
    ↑
    │
    ├── @ClassMappingAnnotation ← 类映射注解
    │
    ├── @EsbConstructor ← 构造函数注解
    │
    ├── @EsbRequest ← 请求注解
    │
    ├── @EsbSpring ← Spring集成注解
    │
    └── @EsbInvocationAnnotation ← 调用注解

5.3 核心注解详解

@EsbBeanAnnotation

功能描述：定义ESB服务Bean的基本属性和行为特征

属性说明：

属性名	类型	描述	默认值
id	String	唯一标识	空
expressionArr	String	表达式数组	空
filter	String	过滤器	空
name	String	名称	空
desc	String	描述	空
type	FormulaType	类型	FormulaType.UNKNOW
flowType	EsbFlowType	流程类型	EsbFlowType.localAction
tokenType	TokenType	令牌类型	TokenType.guest
clazz	String	类名	空
serverUrl	String	服务URL	空
dataType	ContextType	数据类型	ContextType.Action
jspUrl	String	JSP URL	空
version	int	版本号	0

使用示例：

@EsbBeanAnnotation(
    id = "patient_query_service",
    name = "患者查询服务",
    desc = "提供患者基本信息查询功能",
    type = FormulaType.SERVICE,
    flowType = EsbFlowType.remoteAction,
    tokenType = TokenType.user,
    clazz = "com.ds.medical.service.PatientQueryService",
    serverUrl = "http://medical-service:8080/patient",
    dataType = ContextType.JSON,
    version = 1
)
public class PatientQueryEsbBean {
    // ESB服务实现
}

@EsbInvocationAnnotation

功能描述：配置ESB服务的调用参数和策略

属性说明：

属性名	类型	描述	默认值
id	String	唯一标识	空
expressionArr	String	表达式数组	空
filter	String	过滤器	空
name	String	名称	空
desc	String	描述	空
flowType	String	流程类型	空
clazz	String	类名	空
dataType	String	数据类型	"action"
jspUrl	String	JSP URL	空
version	int	版本号	0

使用示例：

@EsbInvocationAnnotation(
    id = "patient_invocation",
    name = "患者服务调用配置",
    flowType = "sync",
    clazz = "com.ds.medical.invocation.PatientInvocationHandler",
    dataType = "json",
    version = 1
)
public class PatientServiceInvocation {
    // 调用实现
}

六、AI Agent相关注解

6.1 分类描述

AI Agent相关注解体系提供了对AI智能体全生命周期的配置与管理能力，涵盖Agent定义、能力声明、动作配置和生命周期管理四大核心维度。该体系以@Agent为核心，协同其他注解形成完整的AI Agent配置闭环，支持各类智能体应用场景的快速开发。

6.2 注解关系结构

@Agent ← 核心Agent注解
  ↑     ↑
  │     │
  ├─────┼───── @AgentAction ← 动作定义注解
  │     │
  ├─────┼───── @AgentParam ← 参数配置注解
  │     │
  ├─────┼───── @AgentCapability ← 能力声明注解
  │     │
  └─────┴───── @AgentLifecycle ← 生命周期注解

6.3 核心注解详解

@Agent

功能描述：标记一个类为AI Agent组件，用于定义Agent的基本信息和元数据

属性说明：

属性名	类型	描述	默认值
id	String	Agent唯一标识符	空
name	String	Agent名称	空
description	String	Agent功能描述	空
version	String	版本号	"1.0"
domain	AgentDomain	所属领域	AgentDomain.DEFAULT

使用示例：

@Agent(id = "nlp-agent", name = "自然语言处理Agent", 
       description = "提供文本分类和实体识别能力的AI智能体",
       version = "2.1", domain = AgentDomain.NLP)
public class NLPAgent {
    // Agent实现
}

@AgentAction

功能描述：标记Agent的具体操作方法，定义方法的执行策略和元数据

属性说明：

属性名	类型	描述	默认值
name	String	操作名称	空
description	String	操作描述	空
executionMode	ExecutionMode	执行模式	ExecutionMode.SYNC
timeout	int	超时时间（毫秒）	3000

使用示例：

@AgentAction(name = "classifyText", 
             description = "对输入文本进行分类",
             executionMode = ExecutionMode.SYNC, 
             timeout = 5000)
public ClassificationResult classifyText(String text) {
    // 实现逻辑
}

@AgentParam

功能描述：标记Agent操作的参数信息，提供参数验证和元数据定义

属性说明：

属性名	类型	描述	默认值
name	String	参数名称	空
description	String	参数描述	空
required	boolean	是否必填	false
defaultValue	String	默认值	空
validationRule	ValidationRule	验证规则	ValidationRule.NONE

使用示例：

public void analyzeText(
    @AgentParam(name = "text", required = true, 
               description = "待分析的文本内容",
               validationRule = ValidationRule.NOT_EMPTY) String text,
    @AgentParam(name = "threshold", defaultValue = "0.8",
               description = "置信度阈值") double threshold
) {
    // 实现逻辑
}

@AgentCapability

功能描述：声明Agent支持的能力，用于服务发现和能力治理

属性说明：

属性名	类型	描述	默认值
name	String	能力名称	空
version	String	能力版本	"1.0"
provider	String	能力提供者	空
isCore	boolean	是否核心能力	false
config	String	配置参数(JSON格式)	空

使用示例：

@AgentCapability(name = "text-classification", 
                version = "2.0",
                provider = "AI-Lab",
                isCore = true,
                config = "{\"supportLanguages\": [\"zh\", \"en\"], \"maxLength\": 1000}")
public class TextClassificationCapability {
    // 能力实现
}

@AgentCapabilities

功能描述：组合多个@AgentCapability注解，用于声明Agent的多项能力

属性说明：

属性名	类型	描述	默认值
value	@AgentCapability[]	@AgentCapability注解数组	空数组

使用示例：

@AgentCapabilities({
    @AgentCapability(name = "text-classification", version = "1.0", isCore = true),
    @AgentCapability(name = "entity-recognition", version = "1.0", isCore = true),
    @AgentCapability(name = "sentiment-analysis", version = "1.0")
})
public class NLPCapabilities {
    // 能力集合定义
}

@AgentLifecycle

功能描述：标记Agent的生命周期回调方法，定义Agent在特定阶段的行为

属性说明：

属性名	类型	描述	默认值
value	Stage	生命周期阶段	Stage.INIT
order	int	执行顺序	0

使用示例：

@AgentLifecycle(value = Stage.INIT, order = 1)
public void initializeResources() {
    // 初始化资源
}

@AgentLifecycle(value = Stage.DESTROY, order = 2)
public void releaseResources() {
    // 释放资源
}

七、核心枚举类型

7.1 Agent相关枚举

AgentDomain

描述：定义AI Agent的应用领域

枚举值	描述
DEFAULT	默认领域
NLP	自然语言处理
CV	计算机视觉
SPEECH	语音处理
RECOMMENDATION	推荐系统
MEDICAL	医疗领域
FINANCIAL	金融领域

ExecutionMode

描述：定义Agent动作的执行模式

枚举值	描述
SYNC	同步执行 - 阻塞等待结果返回
ASYNC	异步执行 - 立即返回Future对象
DELAYED	延迟执行 - 按指定时间延迟后执行
SCHEDULED	定时调度执行 - 按 cron 表达式定期执行

Stage

描述：定义Agent的生命周期阶段

枚举值	描述
INIT	初始化阶段 - Agent创建后执行
START	启动阶段 - Agent初始化完成后执行
DESTROY	销毁阶段 - Agent关闭前执行

ValidationRule

描述：定义参数验证规则

枚举值	描述
NONE	无验证
NOT_EMPTY	非空验证
EMAIL	邮箱格式验证
PHONE	电话号码验证
URL	URL格式验证
NUMBER	数字格式验证

7.2 任务管理枚举

TaskType

描述：定义AI任务的类型

枚举值	描述
TEXT_GENERATION	文本生成任务
IMAGE_ANALYSIS	图像分析任务
DATA_PROCESSING	数据处理任务
MODEL_TRAINING	模型训练任务
INFERENCE	推理任务

PriorityLevel

描述：定义任务优先级

枚举值	描述
LOW	低优先级
NORMAL	正常优先级
HIGH	高优先级
URGENT	紧急优先级
CRITICAL	关键优先级

7.3 工作流枚举

WorkflowType

描述：定义工作流类型

枚举值	描述
SEQUENTIAL	串行工作流
PARALLEL	并行工作流
STATE_MACHINE	状态机工作流
RULE_BASED	规则驱动工作流

StepType

描述：定义工作流步骤类型

枚举值	描述
ACTION	动作步骤
DECISION	决策步骤
SUBFLOW	子流程步骤
WAIT	等待步骤
EVENT	事件步骤

七、注解与Bean类映射关系

注解名称	对应的Bean类	包路径	主要用途
@AIGCTask	AIGCTaskBean	com.ds.ai.bean	AI任务配置的结构化映射
@Workflow	WorkflowBean	com.ds.workflow.bean	工作流配置的结构化映射
@MCPClientAnnotation	MCPClientBean	com.ds.mcp.bean	MCP客户端配置的结构化映射
@EsbBeanAnnotation	ExpressionTempBean	com.ds.esb.config.manager	ESB Bean配置的结构化映射
@Aggregation	AggregationBean	com.ds.web.bean	Web聚合组件的结构化映射

八、跨分类注解应用示例

8.1 医疗诊断全流程示例

// 工作流定义
@Workflow(
    workflowId = "integrated_diagnosis_flow",
    name = "综合诊断工作流",
    type = WorkflowType.STATE_MACHINE,
    timeout = 60
)
public class IntegratedDiagnosisWorkflow {
    
    // AI分析步骤
    @WorkflowStep(
        stepId = "ai_diagnosis_step",
        name = "AI辅助诊断",
        actionClass = AIDiagnosisAction.class,
        order = 2
    )
    @AIGCTask(
        taskId = "ai_diagnosis_task",
        modelId = "medgpt-4.0-clinical",
        timeout = 300,
        cpuQuota = 4,
        memoryQuota = 8192
    )
    @AIGCSecurity(
        sensitiveLevel = SensitiveLevel.HIGH,
        complianceLevel = ComplianceLevel.MEDICAL,
        dataMasking = true
    )
    public void aiDiagnosisStep() {
        // 步骤实现
    }
    
    // 结果查询步骤
    @WorkflowStep(
        stepId = "result_query_step",
        name = "诊断结果查询",
        actionClass = ResultQueryAction.class,
        order = 3
    )
    @MCPClientAnnotation(
        serviceId = "diagnosis-result-service",
        protocol = ProtocolType.HTTP,
        timeout = 5000
    )
    public void resultQueryStep() {
        // 步骤实现
    }
}

8.2 Web动态组件与ESB服务集成示例

@DynLoad(
    viewInstanceId = "patient_medication_view",
    sourceClass = MedicationDataSource.class,
    rootClass = PatientRoot.class
)
@Aggregation(
    domainId = "medication_domain",
    moduleName = "medication_management",
    type = AggregationType.TABLE
)
@EsbBeanAnnotation(
    id = "medication_query_bean",
    name = "用药查询组件",
    type = FormulaType.SERVICE,
    flowType = EsbFlowType.remoteAction,
    serverUrl = "http://medication-service:8080/medication"
)
public class PatientMedicationComponent {
    // 组件实现
}