common_agent/docs/设计文档/0.模块设计总览.md

Common Agent Studio 模块设计总览

1. 总体设计

Common Agent Studio 以一次 AI 应用发布旅程为主线：知识接入、模型路由、Workflow 编排、Agent 调试、MCP/Skill 扩展和运行观测围绕同一个项目空间协作。

旧代码中的 common、rag、modelprovider、agent 仍作为实现包存在，但新文档按产品域组织，便于后续重新实现时形成更清晰的模块边界。

2. 产品域关系

flowchart LR
    Common["系统基础"] --> Knowledge["知识资产与文件解析"]
    Common --> Model["模型与路由"]
    Knowledge --> Workflow["Workflow 编排"]
    Model --> Workflow
    Workflow --> Agent["Agent 会话"]
    MCP["MCP 能力接入"] --> Workflow
    Skill["Skill 编辑"] --> Workflow
    Agent --> Observability["运行观测"]
    Workflow --> Observability
    Model --> Observability

3. 数据主线

主线	表
系统基础	sys_enum、sys_attachment
知识资产	rag_store、rag_document、rag_document_parse_result、rag_chunk、rag_chunk_embedding
模型路由	model_provider、model_config、model_route_rule、rag_store_model_config、model_call_log
Studio 项目	studio_project
Workflow	workflow_definition、workflow_version、workflow_run、workflow_run_step
Agent	agent_definition、agent_session、agent_message、agent_capability_binding
MCP	mcp_server、mcp_capability
Skill	skill_definition、skill_version

4. 接口命名原则

• 已落地接口保持兼容，例如 /api/rag/documents/query、/api/agents/{agentId}/chat。
• Studio 新接口使用聚合资源命名，例如 /api/knowledge/workspaces/{storeId}、/api/workflows/{workflowId}/runs。
• 请求和响应继续使用 DTO，不直接暴露实体。
• 统一返回体保持 RequestResult<T>。

5. 状态设计原则

• 长期稳定状态使用结构化枚举。
• 枚举设计必须保留 sys_enum 当前格式。
• 数据库中状态字段允许继续使用 VARCHAR 保存枚举代码，前后端协议层对结构化枚举继续传整型值。
• 页面展示文案来自枚举定义或前端常量映射，不在业务逻辑中散落硬编码。