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

2026-06-01 02:02:08 +08:00
parent e9abf0b689
commit d92496854d
45 changed files with 0 additions and 0 deletions
--- a/docs/设计文档/0.模块设计总览.md
+++ b/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` 保存枚举代码，前后端协议层对结构化枚举继续传整型值。
+- 页面展示文案来自枚举定义或前端常量映射，不在业务逻辑中散落硬编码。
--- a/docs/设计文档/1.系统基础模块设计.md
+++ b/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. 依赖关系
+
+系统基础模块不能依赖其他业务模块。业务模块可依赖系统基础模块的枚举、附件、解析、返回体和异常处理。
--- a/docs/设计文档/2.知识资产与文件解析模块设计.md
+++ b/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 复用，不绑定某一个页面。
--- a/docs/设计文档/3.模型与路由模块设计.md
+++ b/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`。
--- a/docs/设计文档/4.Workflow编排模块设计.md
+++ b/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 模块。
+- 运行记录被运行观测模块消费。
--- a/docs/设计文档/5.Agent会话模块设计.md
+++ b/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 模块执行复杂流程。
+- 运行观测模块读取会话关联的运行记录。
--- a/docs/设计文档/6.MCP能力接入模块设计.md
+++ b/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 停用时，其能力不应被新运行选择。
--- a/docs/设计文档/7.Skill编辑模块设计.md
+++ b/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` 保存最近测试结果摘要。
--- a/docs/设计文档/8.运行观测模块设计.md
+++ b/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 或敏感密钥。
+- 错误信息只保存摘要，详细日志由运行环境负责。