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

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`