docs(project): 调整中文模块文档位置

docs/前端实现文档/0.前端模块总览.md

@@ -0,0 +1,27 @@
+# 前端模块总览
+
+## 1. 当前原型入口
+
+Studio 原型页面位于 `frontend/src/pages/studio/`，路由集中在 `frontend/src/router/index.ts`，模拟数据位于 `frontend/src/data/studioMock.ts`。
+
+## 2. 页面与模块映射
+
+| 页面 | 模块 |
+|------|------|
+| `StudioDashboardPage.vue` | 工作台与发布就绪 |
+| `KnowledgeWorkspacePage.vue` | 知识资产 |
+| `IngestionPipelinePage.vue` | 文件解析管道 |
+| `ModelWorkspacePage.vue` | 模型与路由 |
+| `WorkflowBuilderPage.vue` | Workflow 编排 |
+| `AgentWorkspacePage.vue` | Agent 对话调试 |
+| `McpImportPage.vue` | MCP 能力接入 |
+| `SkillWorkspacePage.vue` | Skill 编辑 |
+| `ObservabilityPage.vue` | 运行观测 |
+
+## 3. 前端实现原则
+
+- 页面使用聚合 ViewModel，避免页面直接拼多个低层接口。
+- 已落地旧接口保持兼容，新 Studio 接口以聚合资源为主。
+- Long ID 继续按字符串处理，避免 JS 精度问题。
+- 枚举值按整型协议处理，页面展示通过枚举字典或常量映射。
+- 管理后台保持信息密度、稳定布局和清晰状态提示。

docs/前端实现文档/1.系统基础模块前端实现.md

@@ -0,0 +1,28 @@
+# 系统基础模块前端实现
+
+## 1. 页面范围
+
+系统基础前端能力主要体现为枚举字典、上传控件和统一请求处理。当前已有系统枚举管理页，后续 Studio 页面继续复用这些能力。
+
+## 2. API 使用
+
+| 能力 | 接口 |
+|------|------|
+| 枚举管理查询 | `POST /api/sys-enum/queryForManagement` |
+| 枚举详情 | `GET /api/sys-enum/detail` |
+| 枚举保存 | `POST /api/sys-enum/save` |
+| 枚举删除 | `POST /api/sys-enum/delete` |
+| 附件上传 | `POST /api/attachments/upload` |
+
+## 3. 实现约定
+
+- API 层继续使用 `frontend/src/api/request.ts` 解包 `RequestResult<T>`。
+- Long ID 继续通过 `json-bigint` 安全解析。
+- 枚举展示通过字典或本地常量映射，不直接依赖数据库展示顺序。
+- 上传失败时展示后端错误摘要，不吞掉异常。
+
+## 4. Studio 复用点
+
+- 文件解析管道复用附件上传能力。
+- 知识资产、模型路由、Workflow、Agent 等页面复用枚举字典。
+- 运行观测页面复用统一状态颜色和错误提示格式。

docs/前端实现文档/2.知识资产与文件解析模块前端实现.md

@@ -0,0 +1,45 @@
+# 知识资产与文件解析模块前端实现
+
+## 1. 页面
+
+| 页面 | 职责 |
+|------|------|
+| `KnowledgeWorkspacePage.vue` | 展示知识库列表、配置、文档状态和发布影响 |
+| `IngestionPipelinePage.vue` | 展示上传、解析、切片、向量化和任务日志 |
+| 旧 `RagStoresPage.vue` | 保留知识库 CRUD 联调参考 |
+| 旧 `RagDocumentsPage.vue` | 保留知识文档 CRUD 联调参考 |
+
+## 2. 聚合 ViewModel
+
+知识工作台建议使用 `KnowledgeWorkspaceView`：
+
+- 当前知识库基础信息。
+- 文档健康度。
+- Embedding 模型和维度。
+- 检索配置。
+- 文档列表摘要。
+- 待处理任务。
+- 发布影响说明。
+
+文件解析管道建议使用 `IngestionRunView`：
+
+- 上传文件列表。
+- 管道阶段状态。
+- 解析文本预览。
+- 切片预览。
+- 任务日志。
+
+## 3. 接口草案
+
+- `GET /api/knowledge/workspaces/{storeId}`
+- `POST /api/knowledge/ingestion-runs`
+- `GET /api/knowledge/ingestion-runs/{runId}`
+- `POST /api/rag/documents/parse`
+- `POST /api/rag/documents/chunk`
+
+## 4. 交互状态
+
+- 解析失败显示可重试状态。
+- 索引中显示进行中状态，不允许误标为可检索。
+- 切片参数变更后提示需要重建索引。
+- Embedding 模型变更后提示会影响当前知识库向量空间。

docs/前端实现文档/3.模型与路由模块前端实现.md

@@ -0,0 +1,30 @@
+# 模型与路由模块前端实现
+
+## 1. 页面
+
+`ModelWorkspacePage.vue` 当前展示任务路由规则，保留 `model_provider`、`model_config`、`model_route_rule` 语义。
+
+## 2. ViewModel
+
+`ModelRoutingView` 建议包含：
+
+- 服务商健康概览。
+- 模型配置列表。
+- 任务路由规则。
+- Fallback 关系。
+- 最近模型调用失败摘要。
+
+## 3. 接口草案
+
+- `POST /api/model-providers/query`
+- `POST /api/model-configs/query`
+- `POST /api/model-route-rules/query`
+- `POST /api/model-route-rules/save`
+- `GET /api/model-call-logs/query`
+
+## 4. 交互规则
+
+- 禁用服务商时提示关联模型和路由受影响。
+- Embedding 模型维度变更时提示知识库需要重建索引。
+- 草稿路由不得用于生产发布就绪校验。
+- Fallback 模型为空时在发布检查中提示风险。

docs/前端实现文档/4.Workflow编排模块前端实现.md

@@ -0,0 +1,31 @@
+# Workflow 编排模块前端实现
+
+## 1. 页面
+
+`WorkflowBuilderPage.vue` 提供节点库、画布、运行 Trace 抽屉和节点 Inspector。
+
+## 2. ViewModel
+
+`WorkflowBuilderView` 建议包含：
+
+- Workflow 基本信息。
+- 当前草稿版本。
+- 节点列表。
+- 边列表。
+- 当前选中节点配置。
+- 最近测试运行 Trace。
+
+## 3. 接口草案
+
+- `GET /api/workflows/{workflowId}`
+- `POST /api/workflows/save-draft`
+- `POST /api/workflows/{workflowId}/publish`
+- `POST /api/workflows/{workflowId}/runs`
+- `GET /api/workflows/runs/{runId}`
+
+## 4. 交互规则
+
+- 保存草稿只更新草稿版本。
+- 运行测试生成 `workflow_run` 和 `workflow_run_step`。
+- 发布前调用发布就绪检查。
+- 节点 Inspector 只编辑当前节点配置，不直接改其他节点。

docs/前端实现文档/5.Agent会话模块前端实现.md

@@ -0,0 +1,33 @@
+# Agent 会话模块前端实现
+
+## 1. 页面
+
+`AgentWorkspacePage.vue` 当前展示 Agent 对话调试、引用切片、运行追踪和成本延迟指标。
+
+## 2. ViewModel
+
+`AgentWorkspaceView` 建议包含：
+
+- 当前 Agent 基本信息。
+- 当前会话消息列表。
+- 输入框状态。
+- 引用切片列表。
+- 模型请求 ID。
+- 运行追踪步骤。
+- 成本、延迟和 Token 统计。
+
+## 3. 接口草案
+
+- `POST /api/agents/{agentId}/runs`
+- `GET /api/agents/{agentId}/sessions`
+- `GET /api/agent-sessions/{sessionId}`
+- `POST /api/agent-sessions/{sessionId}/messages`
+
+现有 `POST /api/agents/{agentId}/chat` 保留为兼容调试入口。
+
+## 4. 交互规则
+
+- RAG 开关关闭时不展示引用切片。
+- 未召回知识切片时给出明确提示。
+- 模型调用失败时展示 `request_id` 和错误摘要。
+- 会话保存失败不得清空用户输入。

docs/前端实现文档/6.MCP能力接入模块前端实现.md

@@ -0,0 +1,19 @@
+# MCP 能力接入模块前端实现
+
+## 1. 页面
+
+`McpImportPage.vue` 展示导入方式、Manifest 预览和能力预览。
+
+## 2. 接口草案
+
+- `POST /api/mcp/import`
+- `GET /api/mcp/servers/{serverCode}/capabilities`
+- `POST /api/mcp/servers/query`
+- `POST /api/mcp/capabilities/save`
+
+## 3. 交互规则
+
+- 导入前校验地址或 Manifest 格式。
+- 能力预览成功后才允许保存。
+- 未授权能力显示待授权状态。
+- 已停用 Server 的能力不可被 Workflow 新增选择。

docs/前端实现文档/7.Skill编辑模块前端实现.md

@@ -0,0 +1,19 @@
+# Skill 编辑模块前端实现
+
+## 1. 页面
+
+`SkillWorkspacePage.vue` 提供 Prompt、Code、Config 编辑区，测试面板和版本列表。
+
+## 2. 接口草案
+
+- `GET /api/skills/{skillCode}`
+- `PUT /api/skills/{skillCode}/draft`
+- `POST /api/skills/{skillCode}/test`
+- `POST /api/skills/{skillCode}/publish`
+
+## 3. 交互规则
+
+- 发布版本只读。
+- 草稿变更后提示未发布。
+- 测试结果保存到版本草稿。
+- Workflow 只能选择发布版本或明确选择草稿测试。

docs/前端实现文档/8.运行观测模块前端实现.md

@@ -0,0 +1,28 @@
+# 运行观测模块前端实现
+
+## 1. 页面
+
+`ObservabilityPage.vue` 展示运行记录和步骤日志。
+
+## 2. ViewModel
+
+`ObservabilityView` 建议包含：
+
+- 运行列表。
+- 当前运行详情。
+- 步骤日志。
+- 模型调用摘要。
+- 成本和延迟统计。
+
+## 3. 接口草案
+
+- `GET /api/observability/runs`
+- `GET /api/observability/runs/{requestId}`
+- `GET /api/observability/model-calls`
+- `GET /api/observability/runs/{requestId}/export`
+
+## 4. 交互规则
+
+- 异常运行高亮展示。
+- 步骤日志按执行时间排序。
+- 导出日志不包含密钥或完整敏感请求体。

docs/后端实现文档/0.后端模块总览.md

@@ -0,0 +1,36 @@
+# 后端模块总览
+
+## 1. 当前代码边界
+
+当前后端已有 `common`、`rag`、`modelprovider`、`agent` 包。后续重新实现时，可以保留这些包作为技术分层落点，但业务文档按产品域拆分。
+
+## 2. 后端实现原则
+
+- Controller 不直接暴露实体。
+- 请求使用 `XxxRequest`，响应使用 `XxxResponse`。
+- 统一返回 `RequestResult<T>`。
+- 实体继承 `BaseEntity`，保持审计字段和乐观锁字段。
+- Mapper 继续使用 MyBatis-Plus `BaseMapper<T>`。
+- Service 负责业务校验、状态流转和跨表协调。
+
+## 3. 模块落点建议
+
+| 产品域 | 后端包建议 |
+|--------|------------|
+| 系统基础 | `com.bruce.common` |
+| 知识资产与文件解析 | `com.bruce.rag` |
+| 模型与路由 | `com.bruce.modelprovider` |
+| Workflow 编排 | `com.bruce.workflow` |
+| Agent 会话 | `com.bruce.agent` |
+| MCP 能力接入 | `com.bruce.mcp` |
+| Skill 编辑 | `com.bruce.skill` |
+| 运行观测 | `com.bruce.observability` 或复用运行来源模块 |
+
+## 4. 枚举实现约束
+
+新增结构化枚举时，继续实现 `PersistableSysEnumDefinition`，并同步：
+
+- Java 枚举定义。
+- `sys_enum` 初始化测试。
+- `script/sql/studio_enum.sql` 或对应模块枚举脚本。
+- 前端枚举常量或字典接口。

docs/后端实现文档/1.系统基础模块后端实现.md

@@ -0,0 +1,39 @@
+# 系统基础模块后端实现
+
+## 1. 包结构
+
+当前实现位于 `com.bruce.common`：
+
+- `controller`：枚举和附件 API。
+- `domain/entity`：`SysEnum`、`SysAttachment`。
+- `domain/model`：`BaseEntity`、`RequestResult`。
+- `document/parse`：文档解析抽象和 Tika 实现。
+- `enums`：通用枚举与可持久化枚举契约。
+- `service`：枚举与附件服务。
+
+## 2. Controller 约定
+
+Controller 只接收请求 DTO 或基础参数，不直接暴露实体。响应统一使用 `RequestResult<T>`。
+
+## 3. Service 约定
+
+`SysEnumService` 负责：
+
+- 管理端查询。
+- 单条保存和删除。
+- 批量保存。
+- 按 `catalog + type` 全量替换初始化。
+
+`SysAttachmentService` 负责：
+
+- 校验上传文件。
+- 生成存储路径。
+- 保存本地文件。
+- 写入附件元数据。
+
+## 4. 后续实现注意
+
+- 不调整 `PersistableSysEnumDefinition` 现有方法。
+- 不调整 `sys_enum` 表字段。
+- 新增枚举时同步初始化测试和 SQL 初始化脚本。
+- 文档解析器新增类型时，只扩展解析器实现和工厂注册，不影响 RAG 业务服务。

docs/后端实现文档/2.知识资产与文件解析模块后端实现.md

@@ -0,0 +1,39 @@
+# 知识资产与文件解析模块后端实现
+
+## 1. 当前实现落点
+
+当前实现位于 `com.bruce.rag`，包含知识库、文档、解析、切片和向量实体。
+
+## 2. Controller
+
+已落地接口继续保留：
+
+- `/api/rag/store/list`
+- `/api/rag/store/query`
+- `/api/rag/store/detail`
+- `/api/rag/store/overview`
+- `/api/rag/store/documentOverview`
+- `/api/rag/documents/query`
+- `/api/rag/documents/batchUpload`
+- `/api/rag/documents/parse`
+- `/api/rag/documents/chunk`
+
+Studio 聚合接口后续新增在知识资产模块，不替代旧接口。
+
+## 3. Service
+
+| Service | 职责 |
+|---------|------|
+| `IRagStoreService` | 知识库 CRUD、概览统计 |
+| `IRagDocumentService` | 文档 CRUD、批量上传 |
+| `IRagDocumentParseService` | 解析状态流转和解析快照 |
+| `IRagDocumentChunkService` | 根据解析快照生成切片 |
+| `IRagChunkEmbeddingService` | 向量写入和召回 |
+
+## 4. 校验规则
+
+- 知识库编码唯一。
+- 文档必须绑定存在的知识库和附件。
+- 只有解析成功的文档允许切片。
+- 向量化必须读取知识库生效模型配置。
+- 重新切片或模型变更后，索引状态必须回到待索引或索引中。

docs/后端实现文档/3.模型与路由模块后端实现.md

@@ -0,0 +1,41 @@
+# 模型与路由模块后端实现
+
+## 1. 当前实现落点
+
+当前实现位于 `com.bruce.modelprovider`，包含服务商、模型、路由、网关、客户端和调用日志。
+
+## 2. Controller
+
+- `ModelProviderController`
+- `ModelConfigController`
+- `ModelRouteRuleController`
+- `RagStoreModelConfigController`
+- `ModelCallLogController`
+
+## 3. Service
+
+| Service | 职责 |
+|---------|------|
+| `IModelProviderService` | 服务商 CRUD 和健康检查 |
+| `IModelConfigService` | 模型配置 CRUD |
+| `IModelRouteRuleService` | 路由规则 CRUD |
+| `IModelRouteService` | 根据任务上下文选择模型 |
+| `IRagStoreModelConfigService` | 知识库模型绑定 |
+| `IModelCallLogService` | 调用日志写入与查询 |
+
+## 4. 网关
+
+业务模块只能依赖：
+
+- `ChatModelGateway`
+- `EmbeddingModelGateway`
+
+不得直接依赖具体上游客户端。
+
+## 5. 校验规则
+
+- 服务商编码唯一。
+- 同一服务商下模型编码唯一。
+- 路由主模型必须启用。
+- 路由任务类型必须来自枚举。
+- 知识库 Embedding 维度必须与模型配置一致。

docs/后端实现文档/4.Workflow编排模块后端实现.md

@@ -0,0 +1,38 @@
+# Workflow 编排模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.workflow`：
+
+- `controller`
+- `dto/request`
+- `dto/response`
+- `entity`
+- `enums`
+- `mapper`
+- `service`
+- `runner`
+
+## 2. Controller 草案
+
+- `WorkflowDefinitionController`
+- `WorkflowVersionController`
+- `WorkflowRunController`
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IWorkflowDefinitionService` | 定义 CRUD、绑定 Agent |
+| `IWorkflowVersionService` | 草稿保存、发布快照 |
+| `IWorkflowRunService` | 运行测试、运行记录查询 |
+| `IWorkflowRunner` | 按图执行节点并写入步骤日志 |
+
+## 4. 校验规则
+
+- Workflow 编码唯一。
+- 发布版本号不可重复。
+- 运行时必须使用确定的版本快照。
+- 节点类型必须来自枚举。
+- LLM 节点必须配置任务类型。
+- Knowledge Retrieval 节点必须配置知识库或继承项目默认知识库。

docs/后端实现文档/5.Agent会话模块后端实现.md

@@ -0,0 +1,29 @@
+# Agent 会话模块后端实现
+
+## 1. 当前实现落点
+
+当前 Agent 定义和调试入口位于 `com.bruce.agent`。后续会话能力建议继续放在该包下。
+
+## 2. Controller 草案
+
+- `AgentDefinitionController`：保留定义管理和兼容调试入口。
+- `AgentSessionController`：新增会话查询、详情和消息发送。
+- `AgentRunController`：新增运行入口，关联 Workflow 或模型调用。
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IAgentDefinitionService` | Agent 定义管理 |
+| `IAgentSessionService` | 会话创建、关闭、查询 |
+| `IAgentMessageService` | 消息写入和引用保存 |
+| `IAgentRunService` | 对话编排、RAG 召回、模型调用 |
+| `IAgentCapabilityBindingService` | 能力绑定维护 |
+
+## 4. 校验规则
+
+- Agent 必须启用才允许发起对话。
+- RAG 对话必须绑定可用知识库和 Embedding 配置。
+- 消息内容不能为空。
+- `citation_json` 必须是数组结构。
+- 会话关闭后不允许继续写入消息。

docs/后端实现文档/6.MCP能力接入模块后端实现.md

@@ -0,0 +1,20 @@
+# MCP 能力接入模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.mcp`，包含 Controller、DTO、Entity、Mapper、Service 和 MCP Client 适配。
+
+## 2. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IMcpServerService` | Server 导入、启停用、健康检查 |
+| `IMcpCapabilityService` | 能力发现、保存、启停用 |
+| `IMcpImportService` | 处理 URL、package、Manifest 导入 |
+
+## 3. 校验规则
+
+- Server 编码唯一。
+- 能力编码在 Server 下唯一。
+- 导入方式必须来自枚举。
+- 能力 schema 必须为合法 JSON。

docs/后端实现文档/7.Skill编辑模块后端实现.md

@@ -0,0 +1,20 @@
+# Skill 编辑模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.skill`。
+
+## 2. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `ISkillDefinitionService` | Skill 定义管理 |
+| `ISkillVersionService` | 草稿保存、测试、发布、归档 |
+| `ISkillRunner` | 运行 Skill 并生成测试结果 |
+
+## 3. 校验规则
+
+- Skill 编码唯一。
+- 版本号在 Skill 内唯一。
+- Prompt、Code、Config 至少一种非空。
+- 变量 schema 必须为合法 JSON。

docs/后端实现文档/8.运行观测模块后端实现.md

@@ -0,0 +1,24 @@
+# 运行观测模块后端实现
+
+## 1. 包建议
+
+后续实现可新增 `com.bruce.observability`，也可以先由 Workflow、Agent 和模型模块分别提供查询接口。
+
+## 2. Controller 草案
+
+- `ObservabilityRunController`
+- `ObservabilityModelCallController`
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IObservabilityRunService` | 聚合运行记录 |
+| `IObservabilityTraceService` | 聚合步骤、会话和模型调用 |
+| `IObservabilityExportService` | 导出脱敏日志 |
+
+## 4. 校验规则
+
+- 只允许查询脱敏后的运行摘要。
+- 导出接口必须过滤密钥和完整请求内容。
+- requestId 不存在时返回空结果而不是内部异常。

docs/数据库设计/0.数据库与枚举总览.md

@@ -0,0 +1,54 @@
+# 数据库与枚举总览
+
+## 1. 文档目的
+
+本文集中说明本轮数据库和枚举脚本的更新范围，避免需求文档、设计文档、前端文档、后端文档与 SQL 脚本出现冲突。
+
+## 2. SQL 脚本分层
+
+| 脚本位置 | 作用 |
+|----------|------|
+| `script/sql/` | 可执行的模块化建表或初始化脚本 |
+| `docs/MODEL_PROVIDER_SCHEMA.sql` | 模型平台 schema 汇总 |
+| `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | Studio 原型 schema 汇总 |
+
+模块化脚本是后续落库执行的优先参考，`docs/*SCHEMA.sql` 是完整设计快照。
+
+## 3. 必须保持不变的内容
+
+`script/sql/enum.sql` 中 `sys_enum` 表结构不变：
+
+- `catalog`
+- `type`
+- `name`
+- `value`
+- `strvalue`
+- `sort`
+- `version`
+- `create_time`
+- `update_time`
+- `remark`
+- `create_by`
+- `update_by`
+
+Java 枚举契约 `PersistableSysEnumDefinition` 的格式不变。后续如果实现新枚举类，仍按现有 `getCatalog()`、`getType()`、`getValue()`、`getLabel()`、`getRemark()` 风格实现。
+
+## 4. 本轮新增脚本
+
+| 脚本 | 内容 |
+|------|------|
+| `script/sql/studio_project.sql` | Studio 项目空间表 |
+| `script/sql/workflow.sql` | Workflow 定义、版本、运行、步骤日志 |
+| `script/sql/mcp.sql` | MCP Server 与能力表 |
+| `script/sql/skill.sql` | Skill 定义与版本表 |
+| `script/sql/agent_session.sql` | Agent 会话与消息表 |
+| `script/sql/agent_capability_binding.sql` | Agent/Workflow 与 MCP/Skill/知识能力绑定表 |
+| `script/sql/studio_enum.sql` | Studio 相关枚举初始化 |
+
+## 5. 校验规则
+
+- 所有新增表必须包含 `id`、`version`、`create_time`、`update_time`、`remark`、`create_by`、`update_by`。
+- 需要唯一业务编码的表必须增加唯一约束。
+- 需要跨模块引用的字段必须在文档中说明外键关系。
+- JSON 扩展字段统一使用 `JSONB`。
+- 枚举初始化脚本必须使用 `ON CONFLICT (catalog, type, name) DO UPDATE`，与现有脚本风格一致。

docs/数据库设计/2.知识资产数据库设计.md

@@ -0,0 +1,37 @@
+# 知识资产数据库设计
+
+## 1. 表关系
+
+| 表 | 说明 | 关键关系 |
+|----|------|----------|
+| `rag_store` | 知识库主表 | 独立业务编码 |
+| `rag_document` | 知识文档 | 引用 `rag_store`、`sys_attachment` |
+| `rag_document_parse_result` | 解析快照 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk` | 知识切片 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk_embedding` | 切片向量 | 引用 `rag_store`、`rag_document`、`rag_chunk` |
+| `rag_store_model_config` | 知识库模型配置 | 引用 `rag_store`、`model_config` |
+
+## 2. 脚本清单
+
+- `script/sql/rag_store.sql`
+- `script/sql/rag_document.sql`
+- `script/sql/rag_document_parse_result.sql`
+- `script/sql/rag_chunk.sql`
+- `script/sql/rag_chunk_embedding.sql`
+- `docs/MODEL_PROVIDER_SCHEMA.sql` 中的 `rag_store_model_config`
+
+## 3. 枚举组
+
+| catalog | type | Java 枚举 |
+|---------|------|-----------|
+| `rag` | `parse_status` | `RagParseStatusEnum` |
+| `rag` | `index_status` | `RagIndexStatusEnum` |
+| `rag` | `chunk_strategy` | `RagChunkStrategyEnum` |
+
+## 4. 一致性要求
+
+- `rag_document.attachment_id` 保持唯一，避免一个附件重复建档。
+- `rag_document_parse_result.document_id` 保持唯一，表示一个文档一个当前解析快照。
+- `rag_chunk` 使用 `(document_id, chunk_index)` 保证同文档切片序号唯一。
+- `rag_chunk_embedding` 使用 `(chunk_id, embedding_model)` 防止同模型重复写入。
+- RAG 现有脚本与本文档一致，本轮不调整 `sys_enum` 格式。

docs/数据库设计/3.模型与路由数据库设计.md

@@ -0,0 +1,37 @@
+# 模型与路由数据库设计
+
+## 1. 表关系
+
+| 表 | 说明 |
+|----|------|
+| `model_provider` | 模型服务商配置 |
+| `model_config` | 服务商下具体模型 |
+| `model_route_rule` | 任务路由规则 |
+| `rag_store_model_config` | 知识库 Embedding 与切片配置 |
+| `model_call_log` | 模型调用日志 |
+
+## 2. 关键约束
+
+- `model_provider.provider_code` 全局唯一。
+- `model_config` 使用 `(provider_id, model_code)` 唯一。
+- `model_route_rule.route_code` 全局唯一。
+- `rag_store_model_config` 使用 `(store_id, active)` 约束一个知识库只有一个生效配置。
+- `model_call_log.request_id` 全局唯一。
+
+## 3. 枚举组
+
+| catalog | type |
+|---------|------|
+| `model_provider` | `provider_type` |
+| `model_provider` | `protocol_type` |
+| `model_provider` | `model_type` |
+| `model_provider` | `task_type` |
+| `model_provider` | `route_strategy` |
+| `model_provider` | `call_status` |
+| `model_provider` | `health_status` |
+
+## 4. 脚本
+
+- `docs/MODEL_PROVIDER_SCHEMA.sql` 是完整 schema 快照。
+- `script/sql/model_provider.sql` 是后续执行入口。
+- 若模型枚举变更，需要同步 Java 枚举、初始化测试和 SQL 枚举脚本。

docs/数据库设计/4.Workflow数据库设计.md

@@ -0,0 +1,33 @@
+# Workflow 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `studio_project` | Studio 项目空间 |
+| `workflow_definition` | Workflow 主定义 |
+| `workflow_version` | Workflow 版本快照 |
+| `workflow_run` | Workflow 运行记录 |
+| `workflow_run_step` | Workflow 节点步骤日志 |
+
+## 2. 关键约束
+
+- `studio_project.project_code` 唯一。
+- `workflow_definition.workflow_code` 唯一。
+- `workflow_version` 使用 `(workflow_id, version_no)` 唯一。
+- `workflow_run.request_id` 唯一。
+- `workflow_definition.bound_agent_id` 可引用 `agent_definition`。
+
+## 3. 脚本
+
+- `script/sql/studio_project.sql`
+- `script/sql/workflow.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+
+## 4. JSON 字段
+
+- `workflow_version.graph_json` 保存流程图快照。
+- `workflow_run.input_json` 与 `output_json` 保存运行输入输出摘要。
+- `workflow_run_step.input_json` 与 `output_json` 保存节点级输入输出摘要。
+
+JSON 字段只保存运行必要摘要，不保存敏感密钥。

docs/数据库设计/5.Agent会话数据库设计.md

@@ -0,0 +1,32 @@
+# Agent 会话数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `agent_definition` | Agent 定义 |
+| `agent_session` | Agent 会话 |
+| `agent_message` | Agent 消息 |
+| `agent_capability_binding` | 能力绑定 |
+
+## 2. 关键约束
+
+- `agent_definition.agent_code` 唯一。
+- `agent_session.session_code` 唯一。
+- `agent_session.agent_id` 引用 `agent_definition`。
+- `agent_session.workflow_run_id` 可引用 `workflow_run`。
+- `agent_message.session_id` 引用 `agent_session`。
+- `agent_capability_binding` 使用 `(owner_type, owner_id, capability_type, capability_id)` 唯一。
+
+## 3. JSON 字段
+
+- `agent_session.metadata_json` 保存会话扩展信息。
+- `agent_message.citation_json` 保存引用切片摘要。
+- `agent_capability_binding.config_json` 保存能力绑定配置。
+
+## 4. 脚本
+
+- `script/sql/agent_definition.sql`
+- `script/sql/agent_session.sql`
+- `script/sql/agent_capability_binding.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`

docs/数据库设计/6.MCP数据库设计.md

@@ -0,0 +1,20 @@
+# MCP 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `mcp_server` | MCP 服务配置 |
+| `mcp_capability` | MCP 能力清单 |
+
+## 2. 约束
+
+- `mcp_server.server_code` 唯一。
+- `mcp_capability` 使用 `(server_id, capability_code)` 唯一。
+- `mcp_capability.server_id` 引用 `mcp_server`。
+
+## 3. 脚本
+
+- `script/sql/mcp.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+- `script/sql/studio_enum.sql`

docs/数据库设计/7.Skill数据库设计.md

@@ -0,0 +1,20 @@
+# Skill 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `skill_definition` | Skill 定义 |
+| `skill_version` | Skill 版本 |
+
+## 2. 约束
+
+- `skill_definition.skill_code` 唯一。
+- `skill_version` 使用 `(skill_id, version_no)` 唯一。
+- `skill_version.skill_id` 引用 `skill_definition`。
+
+## 3. 脚本
+
+- `script/sql/skill.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+- `script/sql/studio_enum.sql`

docs/数据库设计/8.运行观测数据库设计.md

@@ -0,0 +1,29 @@
+# 运行观测数据库设计
+
+## 1. 表范围
+
+运行观测复用已有运行表，不单独新增观测主表：
+
+- `workflow_run`
+- `workflow_run_step`
+- `model_call_log`
+- `agent_session`
+- `agent_message`
+
+## 2. 索引建议
+
+- `workflow_run.request_id`
+- `workflow_run.status`
+- `workflow_run_step.run_id`
+- `model_call_log.request_id`
+- `model_call_log.task_type`
+- `agent_session.agent_id`
+
+## 3. 脚本
+
+索引分散在：
+
+- `script/sql/workflow.sql`
+- `script/sql/model_provider.sql`
+- `script/sql/agent_session.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`

docs/数据库设计/9.模块一致性校验.md

@@ -0,0 +1,79 @@
+# 模块一致性校验
+
+## 1. 校验范围
+
+本次校验覆盖：
+
+- `需求分析/`
+- `设计文档/`
+- `数据库设计/`
+- `前端实现文档/`
+- `后端实现文档/`
+- `script/sql/*.sql`
+- `docs/MODEL_PROVIDER_SCHEMA.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+
+## 2. 文档占位检查
+
+已检查常见未决占位关键词，当前新增文档与 SQL 脚本中未保留未决占位。
+
+## 3. 数据库脚本一致性
+
+| 模块 | 汇总 schema | 模块化脚本 | 结论 |
+|------|-------------|------------|------|
+| 模型与路由 | `docs/MODEL_PROVIDER_SCHEMA.sql` | `script/sql/model_provider.sql` | 已补齐 `rag_store_model_config.store_id` 外键 |
+| Studio 项目 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/studio_project.sql` | 表、唯一约束、索引一致 |
+| Workflow | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/workflow.sql` | 定义、版本、运行、步骤表一致 |
+| Agent 会话 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/agent_session.sql` | 会话和消息表一致 |
+| 能力绑定 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/agent_capability_binding.sql` | 唯一约束和索引一致 |
+| MCP | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/mcp.sql` | Server 与 Capability 表一致 |
+| Skill | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/skill.sql` | 定义与版本表一致 |
+
+## 4. 枚举一致性
+
+`script/sql/studio_enum.sql` 保持 `sys_enum` 既有格式：
+
+- `catalog`
+- `type`
+- `name`
+- `value`
+- `strvalue`
+- `sort`
+- `version`
+- `remark`
+
+校验结果：
+
+- 枚举行数：48。
+- 枚举组数：14。
+- 同一 `catalog + type` 下 `value` 无重复。
+- 同一 `catalog + type` 下 `sort` 无重复。
+
+## 5. 跨模块依赖检查
+
+| 依赖 | 结论 |
+|------|------|
+| 知识资产依赖系统附件 | `rag_document.attachment_id` 引用 `sys_attachment` 的设计保持不变 |
+| 知识资产依赖模型配置 | `rag_store_model_config` 连接 `rag_store` 与 `model_config` |
+| Workflow 依赖 Agent | `workflow_definition.bound_agent_id` 引用 `agent_definition` |
+| Workflow 运行依赖 Agent | `workflow_run.agent_id` 引用 `agent_definition` |
+| Agent 会话依赖 Workflow 运行 | `agent_session.workflow_run_id` 引用 `workflow_run` |
+| MCP/Skill 依赖能力绑定 | `agent_capability_binding` 通过类型和 ID 绑定能力 |
+| 运行观测依赖运行日志 | 复用 `workflow_run`、`workflow_run_step`、`model_call_log`、`agent_session` |
+
+## 6. 保留约束
+
+- 不修改 `sys_enum` 表结构。
+- 不修改 `PersistableSysEnumDefinition` 枚举契约。
+- 不把结构化枚举协议从整型值改为字符串值。
+- 本轮不修改 Java、Vue 或测试代码。
+
+## 7. 后续实现提示
+
+后续按文档重写代码时，新增 Java 枚举必须补齐：
+
+- Java 枚举类。
+- `SysEnumDataInitTests` 初始化入口。
+- `EnumDefinitionTests` 稳定性断言。
+- `script/sql/studio_enum.sql` 初始化数据。
+- 前端字典或常量映射。

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

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

docs/设计文档/1.系统基础模块设计.md

@@ -0,0 +1,32 @@
+# 系统基础模块设计
+
+## 1. 模块边界
+
+系统基础模块不承载具体 AI 业务逻辑，只提供跨模块复用能力。知识资产、模型路由、Workflow、Agent、MCP、Skill 和观测模块都可以依赖它。
+
+## 2. 核心对象
+
+| 对象 | 说明 |
+|------|------|
+| `SysEnum` | 系统枚举配置，面向前端字典和初始化脚本 |
+| `SysAttachment` | 附件元数据，保存文件名称、路径、来源和大小 |
+| `BaseEntity` | 主键、审计字段、乐观锁字段 |
+| `RequestResult<T>` | 统一 API 响应信封 |
+| `DocumentParser` | 文档文本抽取接口 |
+| `DocumentParserFactory` | 根据文件类型选择解析器 |
+
+## 3. 枚举设计原则
+
+结构化枚举继续以 Java 枚举为单一事实来源。Java 枚举实现 `PersistableSysEnumDefinition`，暴露 `catalog`、`type`、`name`、`value`、`strvalue`、`sort` 和 `remark`。
+
+`sys_enum` 表结构不变，新增 Studio 枚举只能新增枚举组或枚举行，不能调整原字段含义。
+
+## 4. 状态与错误
+
+- 业务启停用统一使用 `EnableStatusEnum` 或模块自有状态。
+- 长流程处理状态使用模块自有枚举，但必须同步到 `sys_enum`。
+- 全局异常处理将校验错误转换为统一响应。
+
+## 5. 依赖关系
+
+系统基础模块不能依赖其他业务模块。业务模块可依赖系统基础模块的枚举、附件、解析、返回体和异常处理。

docs/设计文档/2.知识资产与文件解析模块设计.md

@@ -0,0 +1,44 @@
+# 知识资产与文件解析模块设计
+
+## 1. 领域模型
+
+| 对象 | 职责 |
+|------|------|
+| 知识库 | 聚合文档、模型配置、检索配置和索引版本 |
+| 知识文档 | 关联附件，维护解析和索引状态 |
+| 解析快照 | 保存文本抽取结果，作为切片输入 |
+| 知识切片 | 保存切片内容、序号、元数据和启用状态 |
+| 切片向量 | 保存 Embedding 向量、模型名和维度 |
+| 知识库模型配置 | 固定知识库 Embedding 模型和切片配置 |
+
+## 2. 状态流转
+
+文档解析状态：
+
+`UPLOADED -> PARSING -> PARSED`，失败时进入 `FAILED`。
+
+文档索引状态：
+
+`PENDING -> INDEXING -> INDEXED`，失败时进入 `FAILED`。
+
+切片策略继续使用整型枚举值，例如 `1` 表示固定长度，`5` 表示按分隔符。
+
+## 3. 数据流
+
+```mermaid
+flowchart LR
+    Upload["上传文件"] --> Attachment["sys_attachment"]
+    Attachment --> Document["rag_document"]
+    Document --> Parse["rag_document_parse_result"]
+    Parse --> Chunk["rag_chunk"]
+    Chunk --> Embedding["rag_chunk_embedding"]
+    Embedding --> Retrieval["检索召回"]
+```
+
+## 4. 设计约束
+
+- `rag_document` 只引用附件和知识库，不存储大段解析文本。
+- 解析快照按文档唯一，重新解析时更新快照。
+- `rag_chunk_embedding` 必须记录模型和维度，防止向量空间混用。
+- 知识库模型配置由模型与路由模块维护，但知识资产模块负责消费。
+- 检索配置要面向 Workflow 和 Agent 复用，不绑定某一个页面。

docs/设计文档/3.模型与路由模块设计.md

@@ -0,0 +1,47 @@
+# 模型与路由模块设计
+
+## 1. 分层设计
+
+| 层 | 职责 |
+|----|------|
+| 配置层 | 管理服务商、模型、路由规则和知识库模型绑定 |
+| 路由层 | 根据任务类型、范围和策略选择模型 |
+| 调用层 | 通过 OpenAI-compatible 客户端调用 Chat/Embedding |
+| 观测层 | 写入模型调用日志，供运行观测查询 |
+
+## 2. 路由输入
+
+模型路由至少需要：
+
+- `taskType`
+- `matchScope`
+- `scopeId`
+- `bizType`
+- `bizId`
+- 调用参数。
+
+`matchScope` 初始支持 `GLOBAL`、`RAG_STORE`、`AGENT`。
+
+## 3. 路由输出
+
+路由结果包含：
+
+- 服务商。
+- 模型配置。
+- 上游模型名。
+- 超时时间。
+- Fallback 列表。
+- 调用选项。
+
+## 4. 失败策略
+
+- 主模型失败时按 Fallback 顺序重试。
+- 全部失败时返回统一错误。
+- 每次调用均写入 `model_call_log`。
+- Fallback 成功时状态记为 `FALLBACK_SUCCESS`。
+
+## 5. 与其他模块关系
+
+- 知识资产模块使用 Embedding 路由和知识库模型绑定。
+- Workflow 和 Agent 使用 Chat 路由。
+- 运行观测读取 `model_call_log`。

docs/设计文档/4.Workflow编排模块设计.md

@@ -0,0 +1,46 @@
+# Workflow 编排模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| Studio 项目 | 聚合多个 Workflow、Agent 和发布配置 |
+| Workflow 定义 | 可编辑流程主数据 |
+| Workflow 版本 | 发布或草稿快照，保存 `graph_json` |
+| Workflow 运行 | 一次测试或正式运行 |
+| Workflow 步骤 | 单个节点的输入、输出、耗时和错误 |
+
+## 2. 图模型
+
+`workflow_version.graph_json` 保存节点与边：
+
+- 节点：`id`、`type`、`label`、`config`、`position`
+- 边：`from`、`to`、`condition`
+
+图模型由后端做最小结构校验，复杂交互由前端画布负责。
+
+## 3. 运行链路
+
+```mermaid
+flowchart LR
+    Start["Start"] --> Retrieve["Knowledge Retrieval"]
+    Retrieve --> LLM["LLM"]
+    LLM --> Tool["MCP Tool"]
+    Tool --> Skill["Skill"]
+    Skill --> Answer["Answer"]
+```
+
+## 4. 状态设计
+
+- Workflow 定义状态：草稿、启用、停用、归档。
+- 发布状态：草稿、已发布、已归档。
+- 运行状态：排队中、运行中、成功、失败、取消。
+- 节点状态：等待、运行中、成功、失败、跳过。
+
+## 5. 依赖关系
+
+- Knowledge Retrieval 节点依赖知识资产模块。
+- LLM 节点依赖模型与路由模块。
+- MCP Tool 节点依赖 MCP 模块。
+- Skill 节点依赖 Skill 模块。
+- 运行记录被运行观测模块消费。

docs/设计文档/5.Agent会话模块设计.md

@@ -0,0 +1,50 @@
+# Agent 会话模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| Agent 定义 | Agent 配置主数据 |
+| Agent 会话 | 一段连续对话上下文 |
+| Agent 消息 | 会话中的单条消息 |
+| 能力绑定 | Agent 或 Workflow 绑定知识库、MCP、Skill 等能力 |
+
+## 2. 对话模式
+
+- 普通对话：直接根据会话消息调用 Chat 模型。
+- RAG 对话：先向量化问题，再召回知识切片，再组装上下文调用 Chat 模型。
+- Workflow 对话：通过绑定的 Workflow 运行，消息与运行记录互相关联。
+
+## 3. 引用设计
+
+`agent_message.citation_json` 保存回答引用：
+
+- 文档 ID。
+- 切片 ID。
+- 分数。
+- 引用文本摘要。
+- 知识库 ID。
+
+引用只保存必要摘要，完整切片仍以 `rag_chunk` 为准。
+
+## 4. 状态设计
+
+会话状态建议包括：
+
+- ACTIVE：活跃。
+- CLOSED：已关闭。
+- FAILED：异常终止。
+
+消息角色建议包括：
+
+- USER。
+- ASSISTANT。
+- SYSTEM。
+- TOOL。
+
+## 5. 模块依赖
+
+- 依赖知识资产模块完成 RAG 召回。
+- 依赖模型与路由模块完成 Chat 调用。
+- 可依赖 Workflow 模块执行复杂流程。
+- 运行观测模块读取会话关联的运行记录。

docs/设计文档/6.MCP能力接入模块设计.md

@@ -0,0 +1,26 @@
+# MCP 能力接入模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| MCP Server | 外部能力服务 |
+| MCP Capability | Server 暴露的工具或资源 |
+| Manifest | Server 能力声明 |
+
+## 2. 导入流程
+
+```mermaid
+flowchart LR
+    Input["输入 URL/package/Manifest"] --> Validate["校验连接与声明"]
+    Validate --> Server["写入 mcp_server"]
+    Server --> Capability["写入 mcp_capability"]
+    Capability --> Binding["绑定给 Workflow/Agent"]
+```
+
+## 3. 设计约束
+
+- `secret_ref` 只保存密钥引用，不保存明文密钥。
+- `manifest_json` 保存原始能力声明摘要。
+- `schema_json` 保存单个能力输入输出 schema。
+- Server 停用时，其能力不应被新运行选择。

docs/设计文档/7.Skill编辑模块设计.md

@@ -0,0 +1,23 @@
+# Skill 编辑模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| Skill 定义 | Skill 主数据 |
+| Skill 版本 | Prompt、Code、Config 与测试结果快照 |
+
+## 2. 版本规则
+
+- 草稿版本可编辑。
+- 发布版本不可直接修改。
+- 归档版本仅可查看。
+- Workflow 运行必须引用确定版本。
+
+## 3. 数据设计
+
+- `prompt_text` 保存提示词。
+- `code_text` 保存脚本或函数片段。
+- `config_json` 保存运行配置。
+- `variable_schema_json` 保存输入输出变量定义。
+- `test_result_json` 保存最近测试结果摘要。

docs/设计文档/8.运行观测模块设计.md

@@ -0,0 +1,35 @@
+# 运行观测模块设计
+
+## 1. 观测主键
+
+运行观测以 `request_id` 为主线串联：
+
+- Workflow 运行。
+- Workflow 步骤。
+- Agent 会话。
+- 模型调用日志。
+
+## 2. 展示维度
+
+- 名称。
+- 类型。
+- 状态。
+- 延迟。
+- 成本。
+- 步骤输出。
+- 错误摘要。
+
+## 3. 数据来源
+
+| 来源 | 表 |
+|------|----|
+| 流程运行 | `workflow_run` |
+| 步骤日志 | `workflow_run_step` |
+| 模型调用 | `model_call_log` |
+| Agent 会话 | `agent_session`、`agent_message` |
+
+## 4. 设计约束
+
+- 观测模块只读业务运行数据。
+- 不保存完整 Prompt 或敏感密钥。
+- 错误信息只保存摘要，详细日志由运行环境负责。

docs/需求分析/0.模块总览.md

@@ -0,0 +1,66 @@
+# Common Agent Studio 模块总览
+
+## 1. 文档目的
+
+本文用于统一本轮文档重构的模块口径。后续需求分析、设计文档、前端实现文档、后端实现文档和数据库设计均以本文的产品域模块为准，不再直接按旧后端包名划分。
+
+本轮只处理文档和 SQL 脚本，不修改 Java、Vue、测试代码。
+
+## 2. 模块划分
+
+| 序号 | 模块 | 范围 |
+|------|------|------|
+| 1 | 系统基础 | 系统枚举、附件、审计字段、统一返回体、文档解析抽象 |
+| 2 | 知识资产与文件解析 | 知识库、知识文档、解析快照、切片、向量、索引任务 |
+| 3 | 模型与路由 | 模型服务商、模型配置、任务路由、知识库模型绑定、调用日志 |
+| 4 | Workflow 编排 | 项目空间、Workflow 定义、版本快照、运行记录、步骤日志 |
+| 5 | Agent 会话 | Agent 定义、调试运行、会话、消息、引用切片 |
+| 6 | MCP 能力接入 | MCP Server 导入、能力发现、能力启停用 |
+| 7 | Skill 编辑 | Skill 定义、版本、Prompt/Code/Config、测试结果 |
+| 8 | 运行观测 | Workflow Trace、模型调用日志、成本、延迟、异常排查 |
+
+## 3. 目录规范
+
+| 目录 | 用途 |
+|------|------|
+| `需求分析/` | 描述业务目标、角色、场景、范围和验收标准 |
+| `设计文档/` | 描述领域模型、状态流转、模块依赖和接口形态 |
+| `数据库设计/` | 描述表结构、枚举、脚本同步规则和跨模块关系 |
+| `前端实现文档/` | 描述页面、ViewModel、API 调用和交互状态 |
+| `后端实现文档/` | 描述 Controller、DTO、Service、Entity、Mapper 和校验规则 |
+
+## 4. 脚本范围
+
+本轮 SQL 脚本属于正式交付范围：
+
+- `script/sql/*.sql`：面向落库执行的模块化脚本。
+- `docs/MODEL_PROVIDER_SCHEMA.sql`：模型平台 schema 汇总。
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`：Studio 原型 schema 汇总。
+
+新增或调整数据库设计时，必须同步更新对应脚本。新增或调整枚举设计时，必须同步更新 `sys_enum` 初始化脚本。
+
+## 5. 枚举约束
+
+`sys_enum` 表结构保持不变，Java 枚举契约保持现有格式不变：
+
+- `catalog`
+- `type`
+- `name`
+- `value`
+- `strvalue`
+- `sort`
+- `remark`
+
+前后端结构化枚举继续使用整型 `value` 作为协议值，不改成字符串协议。
+
+## 6. 交叉引用规则
+
+每个模块文档必须说明：
+
+- 关联数据库表。
+- 关联枚举组。
+- 关联 SQL 脚本。
+- 关联前端页面或原型 View。
+- 关联后端接口草案。
+
+最终以 `数据库设计/9.模块一致性校验.md` 统一检查跨模块冲突。

docs/需求分析/1.系统基础模块需求.md

@@ -0,0 +1,38 @@
+# 系统基础模块需求
+
+## 1. 模块目标
+
+系统基础模块为 Common Agent Studio 提供所有产品域共用的底座能力，包括系统枚举、附件上传、审计字段、统一响应、文档解析抽象和全局异常处理。
+
+## 2. 用户角色
+
+| 角色 | 诉求 |
+|------|------|
+| 平台管理员 | 维护系统枚举、检查附件上传和基础配置 |
+| 开发者 | 复用统一 DTO、返回体、审计字段和解析能力 |
+| 前端开发者 | 使用一致的枚举字典和错误响应 |
+| 运维人员 | 通过统一字段排查创建人、更新时间和异常信息 |
+
+## 3. 功能需求
+
+1. 系统枚举必须支持按 `catalog + type` 查询，用于前端字典、后台管理和初始化校验。
+2. `sys_enum` 结构必须保持现状，不因 Studio 新增模块调整字段格式。
+3. 附件模块必须支持本地上传、元数据入库和业务来源关联。
+4. 文档解析抽象必须支持 TXT/Markdown/LOG、PDF、Word、Excel 的文本抽取。
+5. 所有业务接口继续返回 `RequestResult<T>`。
+6. 所有业务实体继续继承公共审计字段和乐观锁字段。
+
+## 4. 非功能需求
+
+- 枚举值稳定，不能随展示文案调整而改变。
+- 附件路径不直接暴露为外部可访问地址。
+- 异常响应保持统一结构，便于前端统一提示。
+- 文档解析失败必须返回可定位的错误摘要。
+
+## 5. 关联资料
+
+- 表：`sys_enum`、`sys_attachment`
+- 枚举：`common/enable_status`、`common/common_status`
+- 脚本：`script/sql/enum.sql`、`script/sql/attachment.sql`
+- 后端入口：`SysEnumController`、`SysAttachmentController`、`DocumentParserFactory`
+- 前端入口：系统枚举 API、文件上传组件、枚举字典调用

docs/需求分析/2.知识资产与文件解析模块需求.md

@@ -0,0 +1,36 @@
+# 知识资产与文件解析模块需求
+
+## 1. 模块目标
+
+知识资产与文件解析模块负责把外部文件变成可检索知识资产，覆盖知识库维护、文件上传、文本解析、切片、向量化和索引状态管理。
+
+## 2. 核心场景
+
+1. 知识维护者创建知识库并批量上传文档。
+2. 系统保存附件元数据并创建 `rag_document`。
+3. 文档解析管道抽取文本并保存解析快照。
+4. 用户选择切片策略生成 `rag_chunk`。
+5. 系统调用 Embedding 模型写入 `rag_chunk_embedding`。
+6. 知识库达到可检索状态后供 Workflow 和 Agent 调用。
+
+## 3. 功能需求
+
+- 知识库支持新增、编辑、删除、查询和概览统计。
+- 文档支持上传、解析、解析失败重试、切片和索引状态查看。
+- 解析结果必须落到 `rag_document_parse_result`，切片不能直接依赖原始附件。
+- 同一文档重新切片时，必须替换旧切片并推动索引重建。
+- 知识库必须绑定稳定的 Embedding 模型和向量维度。
+- 前端需要展示文档健康度、解析失败数、待向量化任务数和发布影响。
+
+## 4. 验收标准
+
+- 能从知识库视角看到文档数量、解析状态、索引状态和切片数量。
+- 能从文件解析管道看到上传、解析、切片、向量化、可检索的阶段。
+- 枚举值与现有 `RagParseStatusEnum`、`RagIndexStatusEnum`、`RagChunkStrategyEnum` 一致。
+
+## 5. 关联资料
+
+- 表：`rag_store`、`rag_document`、`rag_document_parse_result`、`rag_chunk`、`rag_chunk_embedding`、`rag_store_model_config`
+- 枚举：`rag/parse_status`、`rag/index_status`、`rag/chunk_strategy`
+- 脚本：`script/sql/rag_store.sql`、`script/sql/rag_document.sql`、`script/sql/rag_document_parse_result.sql`、`script/sql/rag_chunk.sql`、`script/sql/rag_chunk_embedding.sql`
+- 前端原型：`KnowledgeWorkspacePage.vue`、`IngestionPipelinePage.vue`

docs/需求分析/3.模型与路由模块需求.md

@@ -0,0 +1,39 @@
+# 模型与路由模块需求
+
+## 1. 模块目标
+
+模型与路由模块负责统一管理模型服务商、模型配置、任务路由、知识库模型绑定和模型调用日志，为 RAG、Workflow、Agent 和 Skill 提供统一模型入口。
+
+## 2. 功能需求
+
+- 支持配置 Ollama、硅基流动、百炼、OpenAI 和自定义 OpenAI-compatible 服务。
+- 支持维护 Chat、Embedding、Rerank、多模态模型。
+- 支持按任务类型配置主模型、Fallback 模型和路由策略。
+- 支持知识库固定 Embedding 模型、向量维度、切片策略和索引版本。
+- 支持记录模型调用状态、耗时、Token、成本和错误摘要。
+
+## 3. 任务类型
+
+初始任务类型包括：
+
+- RAG 文档向量化。
+- RAG 查询向量化。
+- RAG 问答生成。
+- 简单文本处理。
+- 复杂文本处理。
+- Agent 规划。
+- 重排序。
+
+## 4. 验收标准
+
+- 业务模块不直接调用上游模型服务。
+- 同一知识库不能混用不同 Embedding 向量空间。
+- 所有调用必须有 `request_id`，方便观测模块追踪。
+- 路由规则禁用时不能被选中。
+
+## 5. 关联资料
+
+- 表：`model_provider`、`model_config`、`model_route_rule`、`rag_store_model_config`、`model_call_log`
+- 枚举：`model_provider/provider_type`、`protocol_type`、`model_type`、`task_type`、`route_strategy`、`call_status`、`health_status`
+- 脚本：`docs/MODEL_PROVIDER_SCHEMA.sql`、`script/sql/model_provider.sql`
+- 前端原型：`ModelWorkspacePage.vue`

docs/需求分析/4.Workflow编排模块需求.md

@@ -0,0 +1,27 @@
+# Workflow 编排模块需求
+
+## 1. 模块目标
+
+Workflow 编排模块负责把知识检索、模型调用、MCP 工具、Skill 和回答输出组织成可保存、可测试、可发布、可追踪的图形化流程。
+
+## 2. 功能需求
+
+- 支持项目空间管理，区分环境和发布状态。
+- 支持 Workflow 草稿编辑、保存和发布版本。
+- 支持节点库：Start、LLM、Knowledge Retrieval、MCP Tool、Skill、Condition、Answer。
+- 支持 JSON Graph 保存画布结构。
+- 支持运行测试并生成运行记录和步骤日志。
+- 支持绑定默认 Agent，供对话调试和发布使用。
+
+## 3. 发布要求
+
+- 草稿可以保存但不能直接作为生产版本。
+- 发布时必须生成不可变版本快照。
+- 发布前必须检查模型路由、知识库索引、MCP 授权和 Skill 发布状态。
+
+## 4. 关联资料
+
+- 表：`studio_project`、`workflow_definition`、`workflow_version`、`workflow_run`、`workflow_run_step`
+- 枚举：`studio/environment`、`studio/publish_status`、`workflow/status`、`workflow/run_status`、`workflow/node_type`
+- 脚本：`script/sql/studio_project.sql`、`script/sql/workflow.sql`
+- 前端原型：`StudioDashboardPage.vue`、`WorkflowBuilderPage.vue`

docs/需求分析/5.Agent会话模块需求.md

@@ -0,0 +1,29 @@
+# Agent 会话模块需求
+
+## 1. 模块目标
+
+Agent 会话模块负责 Agent 定义、对话调试、会话持久化、消息记录、引用切片和运行追踪，使一次调试或发布后的对话可以被复盘。
+
+## 2. 功能需求
+
+- 支持 Agent 定义管理，包含编码、名称、系统提示词、默认知识库和状态。
+- 支持普通对话和 RAG 对话。
+- 支持会话持久化，记录 `agent_session`。
+- 支持消息持久化，记录用户、Agent、系统等角色消息。
+- 支持保存引用切片 JSON，便于回答溯源。
+- 支持关联 Workflow 运行记录，形成端到端 Trace。
+
+## 3. 会话场景
+
+1. 用户选择 Agent 输入调试问题。
+2. 系统创建或复用会话。
+3. RAG 模式下执行检索召回。
+4. 调用 Chat 模型生成回答。
+5. 写入消息、引用、模型请求 ID 和运行追踪。
+
+## 4. 关联资料
+
+- 表：`agent_definition`、`agent_session`、`agent_message`、`agent_capability_binding`
+- 脚本：`script/sql/agent_definition.sql`、`script/sql/agent_session.sql`、`script/sql/agent_capability_binding.sql`
+- 前端原型：`AgentWorkspacePage.vue`
+- 后端入口：`AgentDefinitionController`、`AgentDefinitionServiceImpl`

docs/需求分析/6.MCP能力接入模块需求.md

@@ -0,0 +1,20 @@
+# MCP 能力接入模块需求
+
+## 1. 模块目标
+
+MCP 能力接入模块负责导入外部 MCP Server，读取能力清单，并把工具或资源能力绑定给 Workflow 和 Agent 使用。
+
+## 2. 功能需求
+
+- 支持 URL、npm package、JSON Manifest 三种导入方式。
+- 支持保存 Server 连接信息、鉴权方式、密钥引用和 Manifest。
+- 支持发现工具、资源等能力。
+- 支持能力启停用。
+- 支持健康状态展示。
+
+## 3. 关联资料
+
+- 表：`mcp_server`、`mcp_capability`
+- 枚举：`mcp/import_type`、`mcp/capability_type`、`mcp/health_status`
+- 脚本：`script/sql/mcp.sql`、`script/sql/studio_enum.sql`
+- 前端原型：`McpImportPage.vue`

docs/需求分析/7.Skill编辑模块需求.md

@@ -0,0 +1,20 @@
+# Skill 编辑模块需求
+
+## 1. 模块目标
+
+Skill 编辑模块负责维护可复用的提示词、代码片段、配置和测试结果，使 Workflow 或 Agent 可以复用稳定的能力单元。
+
+## 2. 功能需求
+
+- 支持 Skill 定义管理。
+- 支持版本草稿、发布和归档。
+- 支持 Prompt、Code、Config 三类编辑区域。
+- 支持变量 schema 和测试结果保存。
+- 支持发布版本供 Workflow 或 Agent 绑定。
+
+## 3. 关联资料
+
+- 表：`skill_definition`、`skill_version`
+- 枚举：`skill/skill_type`、`skill/status`、`studio/publish_status`
+- 脚本：`script/sql/skill.sql`、`script/sql/studio_enum.sql`
+- 前端原型：`SkillWorkspacePage.vue`

docs/需求分析/8.运行观测模块需求.md

@@ -0,0 +1,19 @@
+# 运行观测模块需求
+
+## 1. 模块目标
+
+运行观测模块负责展示 Workflow、Agent、MCP、Skill 和模型调用的运行记录，支撑排障、成本分析和发布质量评估。
+
+## 2. 功能需求
+
+- 展示最近运行记录。
+- 展示步骤日志和节点输出摘要。
+- 展示模型调用耗时、Token 和成本。
+- 支持按 requestId 追踪一次完整运行。
+- 支持导出日志。
+
+## 3. 关联资料
+
+- 表：`workflow_run`、`workflow_run_step`、`model_call_log`、`agent_session`、`agent_message`
+- 脚本：`script/sql/workflow.sql`、`script/sql/model_provider.sql`、`script/sql/agent_session.sql`
+- 前端原型：`ObservabilityPage.vue`