From 1132cf0262f0e53396b9932179fea488a788eb8e Mon Sep 17 00:00:00 2001 From: bruce Date: Mon, 1 Jun 2026 00:56:40 +0800 Subject: [PATCH] =?UTF-8?q?docs(studio):=20=E8=A1=A5=E5=85=A8=E6=89=A9?= =?UTF-8?q?=E5=B1=95=E8=83=BD=E5=8A=9B=E4=B8=8E=E8=A7=82=E6=B5=8B=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/STUDIO_PROTOTYPE_SCHEMA.sql | 8 +++ script/sql/mcp.sql | 48 ++++++++++++++++++ script/sql/skill.sql | 46 +++++++++++++++++ script/sql/studio_enum.sql | 60 +++++++++++++++++++++++ 前端实现文档/6.MCP能力接入模块前端实现.md | 19 +++++++ 前端实现文档/7.Skill编辑模块前端实现.md | 19 +++++++ 前端实现文档/8.运行观测模块前端实现.md | 28 +++++++++++ 后端实现文档/6.MCP能力接入模块后端实现.md | 20 ++++++++ 后端实现文档/7.Skill编辑模块后端实现.md | 20 ++++++++ 后端实现文档/8.运行观测模块后端实现.md | 24 +++++++++ 数据库设计/6.MCP数据库设计.md | 20 ++++++++ 数据库设计/7.Skill数据库设计.md | 20 ++++++++ 数据库设计/8.运行观测数据库设计.md | 29 +++++++++++ 设计文档/6.MCP能力接入模块设计.md | 26 ++++++++++ 设计文档/7.Skill编辑模块设计.md | 23 +++++++++ 设计文档/8.运行观测模块设计.md | 35 +++++++++++++ 需求分析/6.MCP能力接入模块需求.md | 20 ++++++++ 需求分析/7.Skill编辑模块需求.md | 20 ++++++++ 需求分析/8.运行观测模块需求.md | 19 +++++++ 19 files changed, 504 insertions(+) create mode 100644 script/sql/mcp.sql create mode 100644 script/sql/skill.sql create mode 100644 script/sql/studio_enum.sql create mode 100644 前端实现文档/6.MCP能力接入模块前端实现.md create mode 100644 前端实现文档/7.Skill编辑模块前端实现.md create mode 100644 前端实现文档/8.运行观测模块前端实现.md create mode 100644 后端实现文档/6.MCP能力接入模块后端实现.md create mode 100644 后端实现文档/7.Skill编辑模块后端实现.md create mode 100644 后端实现文档/8.运行观测模块后端实现.md create mode 100644 数据库设计/6.MCP数据库设计.md create mode 100644 数据库设计/7.Skill数据库设计.md create mode 100644 数据库设计/8.运行观测数据库设计.md create mode 100644 设计文档/6.MCP能力接入模块设计.md create mode 100644 设计文档/7.Skill编辑模块设计.md create mode 100644 设计文档/8.运行观测模块设计.md create mode 100644 需求分析/6.MCP能力接入模块需求.md create mode 100644 需求分析/7.Skill编辑模块需求.md create mode 100644 需求分析/8.运行观测模块需求.md diff --git a/docs/STUDIO_PROTOTYPE_SCHEMA.sql b/docs/STUDIO_PROTOTYPE_SCHEMA.sql index 17845a4..9a7a28c 100644 --- a/docs/STUDIO_PROTOTYPE_SCHEMA.sql +++ b/docs/STUDIO_PROTOTYPE_SCHEMA.sql @@ -241,6 +241,14 @@ CREATE INDEX IF NOT EXISTS idx_agent_message_session_id ON agent_message (sessio CREATE INDEX IF NOT EXISTS idx_agent_message_role ON agent_message (role); CREATE INDEX IF NOT EXISTS idx_agent_capability_owner ON agent_capability_binding (owner_type, owner_id); CREATE INDEX IF NOT EXISTS idx_agent_capability_type ON agent_capability_binding (capability_type, capability_id); +CREATE INDEX IF NOT EXISTS idx_mcp_server_import_type ON mcp_server (import_type); +CREATE INDEX IF NOT EXISTS idx_mcp_server_health_status ON mcp_server (health_status); +CREATE INDEX IF NOT EXISTS idx_mcp_capability_server_id ON mcp_capability (server_id); +CREATE INDEX IF NOT EXISTS idx_mcp_capability_type ON mcp_capability (capability_type); +CREATE INDEX IF NOT EXISTS idx_skill_definition_status ON skill_definition (status); +CREATE INDEX IF NOT EXISTS idx_skill_definition_type ON skill_definition (skill_type); +CREATE INDEX IF NOT EXISTS idx_skill_version_skill_id ON skill_version (skill_id); +CREATE INDEX IF NOT EXISTS idx_skill_version_publish_status ON skill_version (publish_status); COMMENT ON TABLE studio_project IS 'Studio项目空间表'; COMMENT ON TABLE workflow_definition IS 'Workflow定义表'; diff --git a/script/sql/mcp.sql b/script/sql/mcp.sql new file mode 100644 index 0000000..c990764 --- /dev/null +++ b/script/sql/mcp.sql @@ -0,0 +1,48 @@ +-- MCP 服务与能力表。 + +CREATE TABLE IF NOT EXISTS mcp_server ( + id BIGSERIAL PRIMARY KEY, + server_code VARCHAR(100) NOT NULL, + server_name VARCHAR(200) NOT NULL, + import_type VARCHAR(50) NOT NULL, + endpoint_url VARCHAR(500), + package_name VARCHAR(200), + manifest_json JSONB NOT NULL DEFAULT '{}'::jsonb, + auth_type VARCHAR(50), + secret_ref VARCHAR(200), + health_status VARCHAR(50) NOT NULL DEFAULT 'UNKNOWN', + enabled BOOLEAN NOT NULL DEFAULT TRUE, + version INTEGER NOT NULL DEFAULT 1, + create_time TIMESTAMP, + update_time TIMESTAMP, + remark VARCHAR(500) DEFAULT '', + create_by VARCHAR(64), + update_by VARCHAR(64), + CONSTRAINT uk_mcp_server_code UNIQUE (server_code) +); + +CREATE TABLE IF NOT EXISTS mcp_capability ( + id BIGSERIAL PRIMARY KEY, + server_id BIGINT NOT NULL, + capability_code VARCHAR(150) NOT NULL, + capability_name VARCHAR(200) NOT NULL, + capability_type VARCHAR(50) NOT NULL, + schema_json JSONB NOT NULL DEFAULT '{}'::jsonb, + enabled BOOLEAN NOT NULL DEFAULT TRUE, + version INTEGER NOT NULL DEFAULT 1, + create_time TIMESTAMP, + update_time TIMESTAMP, + remark VARCHAR(500) DEFAULT '', + create_by VARCHAR(64), + update_by VARCHAR(64), + CONSTRAINT uk_mcp_capability_code UNIQUE (server_id, capability_code), + CONSTRAINT fk_mcp_capability_server_id FOREIGN KEY (server_id) REFERENCES mcp_server (id) +); + +CREATE INDEX IF NOT EXISTS idx_mcp_server_import_type ON mcp_server (import_type); +CREATE INDEX IF NOT EXISTS idx_mcp_server_health_status ON mcp_server (health_status); +CREATE INDEX IF NOT EXISTS idx_mcp_capability_server_id ON mcp_capability (server_id); +CREATE INDEX IF NOT EXISTS idx_mcp_capability_type ON mcp_capability (capability_type); + +COMMENT ON TABLE mcp_server IS 'MCP服务表'; +COMMENT ON TABLE mcp_capability IS 'MCP能力表'; diff --git a/script/sql/skill.sql b/script/sql/skill.sql new file mode 100644 index 0000000..bc31678 --- /dev/null +++ b/script/sql/skill.sql @@ -0,0 +1,46 @@ +-- Skill 定义与版本表。 + +CREATE TABLE IF NOT EXISTS skill_definition ( + id BIGSERIAL PRIMARY KEY, + skill_code VARCHAR(100) NOT NULL, + skill_name VARCHAR(200) NOT NULL, + skill_type VARCHAR(50) NOT NULL, + description VARCHAR(1000), + status VARCHAR(50) NOT NULL DEFAULT 'DRAFT', + version INTEGER NOT NULL DEFAULT 1, + create_time TIMESTAMP, + update_time TIMESTAMP, + remark VARCHAR(500) DEFAULT '', + create_by VARCHAR(64), + update_by VARCHAR(64), + CONSTRAINT uk_skill_definition_code UNIQUE (skill_code) +); + +CREATE TABLE IF NOT EXISTS skill_version ( + id BIGSERIAL PRIMARY KEY, + skill_id BIGINT NOT NULL, + version_no INTEGER NOT NULL, + prompt_text TEXT, + code_text TEXT, + config_json JSONB NOT NULL DEFAULT '{}'::jsonb, + variable_schema_json JSONB NOT NULL DEFAULT '{}'::jsonb, + test_result_json JSONB NOT NULL DEFAULT '{}'::jsonb, + publish_status VARCHAR(50) NOT NULL DEFAULT 'DRAFT', + published_time TIMESTAMP, + version INTEGER NOT NULL DEFAULT 1, + create_time TIMESTAMP, + update_time TIMESTAMP, + remark VARCHAR(500) DEFAULT '', + create_by VARCHAR(64), + update_by VARCHAR(64), + CONSTRAINT uk_skill_version_no UNIQUE (skill_id, version_no), + CONSTRAINT fk_skill_version_skill_id FOREIGN KEY (skill_id) REFERENCES skill_definition (id) +); + +CREATE INDEX IF NOT EXISTS idx_skill_definition_status ON skill_definition (status); +CREATE INDEX IF NOT EXISTS idx_skill_definition_type ON skill_definition (skill_type); +CREATE INDEX IF NOT EXISTS idx_skill_version_skill_id ON skill_version (skill_id); +CREATE INDEX IF NOT EXISTS idx_skill_version_publish_status ON skill_version (publish_status); + +COMMENT ON TABLE skill_definition IS 'Skill定义表'; +COMMENT ON TABLE skill_version IS 'Skill版本表'; diff --git a/script/sql/studio_enum.sql b/script/sql/studio_enum.sql new file mode 100644 index 0000000..89188f0 --- /dev/null +++ b/script/sql/studio_enum.sql @@ -0,0 +1,60 @@ +-- Studio 相关枚举初始化。 +-- 保持 sys_enum 现有 catalog/type/name/value/strvalue/sort/remark 格式不变。 + +INSERT INTO sys_enum (catalog, type, name, value, strvalue, sort, version, remark) +VALUES + ('studio', 'environment', '开发环境', 1, 'DEV', 1, 1, 'Studio环境'), + ('studio', 'environment', '测试环境', 2, 'TEST', 2, 1, 'Studio环境'), + ('studio', 'environment', '生产环境', 3, 'PROD', 3, 1, 'Studio环境'), + ('studio', 'publish_status', '草稿', 1, 'DRAFT', 1, 1, '发布状态'), + ('studio', 'publish_status', '已发布', 2, 'PUBLISHED', 2, 1, '发布状态'), + ('studio', 'publish_status', '已归档', 3, 'ARCHIVED', 3, 1, '发布状态'), + ('workflow', 'status', '草稿', 1, 'DRAFT', 1, 1, 'Workflow状态'), + ('workflow', 'status', '启用', 2, 'ENABLED', 2, 1, 'Workflow状态'), + ('workflow', 'status', '停用', 3, 'DISABLED', 3, 1, 'Workflow状态'), + ('workflow', 'run_status', '排队中', 1, 'QUEUED', 1, 1, 'Workflow运行状态'), + ('workflow', 'run_status', '运行中', 2, 'RUNNING', 2, 1, 'Workflow运行状态'), + ('workflow', 'run_status', '成功', 3, 'SUCCESS', 3, 1, 'Workflow运行状态'), + ('workflow', 'run_status', '失败', 4, 'FAILED', 4, 1, 'Workflow运行状态'), + ('workflow', 'run_status', '取消', 5, 'CANCELED', 5, 1, 'Workflow运行状态'), + ('workflow', 'node_type', '开始', 1, 'START', 1, 1, 'Workflow节点类型'), + ('workflow', 'node_type', '大模型', 2, 'LLM', 2, 1, 'Workflow节点类型'), + ('workflow', 'node_type', '知识检索', 3, 'KNOWLEDGE_RETRIEVAL', 3, 1, 'Workflow节点类型'), + ('workflow', 'node_type', 'MCP工具', 4, 'MCP_TOOL', 4, 1, 'Workflow节点类型'), + ('workflow', 'node_type', 'Skill', 5, 'SKILL', 5, 1, 'Workflow节点类型'), + ('workflow', 'node_type', '条件', 6, 'CONDITION', 6, 1, 'Workflow节点类型'), + ('workflow', 'node_type', '回答', 7, 'ANSWER', 7, 1, 'Workflow节点类型'), + ('agent', 'session_status', '活跃', 1, 'ACTIVE', 1, 1, 'Agent会话状态'), + ('agent', 'session_status', '已关闭', 2, 'CLOSED', 2, 1, 'Agent会话状态'), + ('agent', 'session_status', '异常终止', 3, 'FAILED', 3, 1, 'Agent会话状态'), + ('agent', 'message_role', '用户', 1, 'USER', 1, 1, 'Agent消息角色'), + ('agent', 'message_role', '助手', 2, 'ASSISTANT', 2, 1, 'Agent消息角色'), + ('agent', 'message_role', '系统', 3, 'SYSTEM', 3, 1, 'Agent消息角色'), + ('agent', 'message_role', '工具', 4, 'TOOL', 4, 1, 'Agent消息角色'), + ('mcp', 'import_type', 'URL导入', 1, 'URL', 1, 1, 'MCP导入方式'), + ('mcp', 'import_type', 'npm包导入', 2, 'NPM_PACKAGE', 2, 1, 'MCP导入方式'), + ('mcp', 'import_type', 'JSON声明导入', 3, 'JSON_MANIFEST', 3, 1, 'MCP导入方式'), + ('mcp', 'capability_type', '工具', 1, 'TOOL', 1, 1, 'MCP能力类型'), + ('mcp', 'capability_type', '资源', 2, 'RESOURCE', 2, 1, 'MCP能力类型'), + ('mcp', 'capability_type', '提示词', 3, 'PROMPT', 3, 1, 'MCP能力类型'), + ('mcp', 'health_status', '未知', 1, 'UNKNOWN', 1, 1, 'MCP健康状态'), + ('mcp', 'health_status', '健康', 2, 'HEALTHY', 2, 1, 'MCP健康状态'), + ('mcp', 'health_status', '异常', 3, 'UNHEALTHY', 3, 1, 'MCP健康状态'), + ('skill', 'skill_type', '提示词', 1, 'PROMPT', 1, 1, 'Skill类型'), + ('skill', 'skill_type', '代码', 2, 'CODE', 2, 1, 'Skill类型'), + ('skill', 'skill_type', '混合', 3, 'MIXED', 3, 1, 'Skill类型'), + ('skill', 'status', '草稿', 1, 'DRAFT', 1, 1, 'Skill状态'), + ('skill', 'status', '已发布', 2, 'PUBLISHED', 2, 1, 'Skill状态'), + ('skill', 'status', '已归档', 3, 'ARCHIVED', 3, 1, 'Skill状态'), + ('agent', 'capability_owner_type', 'Agent', 1, 'AGENT', 1, 1, '能力绑定主体类型'), + ('agent', 'capability_owner_type', 'Workflow', 2, 'WORKFLOW', 2, 1, '能力绑定主体类型'), + ('agent', 'capability_type', '知识库', 1, 'RAG_STORE', 1, 1, '能力绑定能力类型'), + ('agent', 'capability_type', 'MCP能力', 2, 'MCP_CAPABILITY', 2, 1, '能力绑定能力类型'), + ('agent', 'capability_type', 'Skill', 3, 'SKILL', 3, 1, '能力绑定能力类型') +ON CONFLICT (catalog, type, name) +DO UPDATE SET + value = EXCLUDED.value, + strvalue = EXCLUDED.strvalue, + sort = EXCLUDED.sort, + remark = EXCLUDED.remark, + update_time = CURRENT_TIMESTAMP; diff --git a/前端实现文档/6.MCP能力接入模块前端实现.md b/前端实现文档/6.MCP能力接入模块前端实现.md new file mode 100644 index 0000000..405b748 --- /dev/null +++ b/前端实现文档/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 新增选择。 diff --git a/前端实现文档/7.Skill编辑模块前端实现.md b/前端实现文档/7.Skill编辑模块前端实现.md new file mode 100644 index 0000000..1268005 --- /dev/null +++ b/前端实现文档/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 只能选择发布版本或明确选择草稿测试。 diff --git a/前端实现文档/8.运行观测模块前端实现.md b/前端实现文档/8.运行观测模块前端实现.md new file mode 100644 index 0000000..8c8da5d --- /dev/null +++ b/前端实现文档/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. 交互规则 + +- 异常运行高亮展示。 +- 步骤日志按执行时间排序。 +- 导出日志不包含密钥或完整敏感请求体。 diff --git a/后端实现文档/6.MCP能力接入模块后端实现.md b/后端实现文档/6.MCP能力接入模块后端实现.md new file mode 100644 index 0000000..60b1fe5 --- /dev/null +++ b/后端实现文档/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。 diff --git a/后端实现文档/7.Skill编辑模块后端实现.md b/后端实现文档/7.Skill编辑模块后端实现.md new file mode 100644 index 0000000..fd7fc3e --- /dev/null +++ b/后端实现文档/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。 diff --git a/后端实现文档/8.运行观测模块后端实现.md b/后端实现文档/8.运行观测模块后端实现.md new file mode 100644 index 0000000..3dd8538 --- /dev/null +++ b/后端实现文档/8.运行观测模块后端实现.md @@ -0,0 +1,24 @@ +# 运行观测模块后端实现 + +## 1. 包建议 + +后续实现可新增 `com.bruce.observability`，也可以先由 Workflow、Agent 和模型模块分别提供查询接口。 + +## 2. Controller 草案 + +- `ObservabilityRunController` +- `ObservabilityModelCallController` + +## 3. Service 草案 + +| Service | 职责 | +|---------|------| +| `IObservabilityRunService` | 聚合运行记录 | +| `IObservabilityTraceService` | 聚合步骤、会话和模型调用 | +| `IObservabilityExportService` | 导出脱敏日志 | + +## 4. 校验规则 + +- 只允许查询脱敏后的运行摘要。 +- 导出接口必须过滤密钥和完整请求内容。 +- requestId 不存在时返回空结果而不是内部异常。 diff --git a/数据库设计/6.MCP数据库设计.md b/数据库设计/6.MCP数据库设计.md new file mode 100644 index 0000000..14ca145 --- /dev/null +++ b/数据库设计/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` diff --git a/数据库设计/7.Skill数据库设计.md b/数据库设计/7.Skill数据库设计.md new file mode 100644 index 0000000..266e1ab --- /dev/null +++ b/数据库设计/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` diff --git a/数据库设计/8.运行观测数据库设计.md b/数据库设计/8.运行观测数据库设计.md new file mode 100644 index 0000000..bc06b67 --- /dev/null +++ b/数据库设计/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` diff --git a/设计文档/6.MCP能力接入模块设计.md b/设计文档/6.MCP能力接入模块设计.md new file mode 100644 index 0000000..54f7fe6 --- /dev/null +++ b/设计文档/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 停用时，其能力不应被新运行选择。 diff --git a/设计文档/7.Skill编辑模块设计.md b/设计文档/7.Skill编辑模块设计.md new file mode 100644 index 0000000..59974e1 --- /dev/null +++ b/设计文档/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` 保存最近测试结果摘要。 diff --git a/设计文档/8.运行观测模块设计.md b/设计文档/8.运行观测模块设计.md new file mode 100644 index 0000000..cdcaadb --- /dev/null +++ b/设计文档/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 或敏感密钥。 +- 错误信息只保存摘要，详细日志由运行环境负责。 diff --git a/需求分析/6.MCP能力接入模块需求.md b/需求分析/6.MCP能力接入模块需求.md new file mode 100644 index 0000000..b6298bb --- /dev/null +++ b/需求分析/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` diff --git a/需求分析/7.Skill编辑模块需求.md b/需求分析/7.Skill编辑模块需求.md new file mode 100644 index 0000000..3f63926 --- /dev/null +++ b/需求分析/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` diff --git a/需求分析/8.运行观测模块需求.md b/需求分析/8.运行观测模块需求.md new file mode 100644 index 0000000..d330bf0 --- /dev/null +++ b/需求分析/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`