# Common Agent Studio 模块设计总览

## 1. 总体设计

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

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

## 2. 产品域关系

```mermaid
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` 保存枚举代码，前后端协议层对结构化枚举继续传整型值。
- 页面展示文案来自枚举定义或前端常量映射，不在业务逻辑中散落硬编码。