Bruce/common_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d5d239ae3a669bd46a847bd98a5b9d3756b9ea5b
common_agent/docs/模块完成度审计.md

11 KiB
Raw Blame History

Common Agent Studio 模块完成度审计

1. 审计范围

本次审计以当前仓库最新状态为准，核对以下资料与实现是否一致：

  • docs/需求分析/*
  • docs/设计文档/*
  • docs/数据库设计/*
  • docs/后端实现文档/*
  • docs/前端实现文档/*
  • script/sql/*.sql

审计目标不是重复设计方案，而是确认当前代码、接口、测试与文档约束之间的对应关系，并标记仍需持续关注的风险点。

2. 总体结论

  • Maven 多模块单体骨架已落地，根 pom.xml 已拆分 common-agent-boot、common-agent-common、common-agent-rag、common-agent-modelprovider、common-agent-agent、common-agent-workflow、common-agent-mcp、common-agent-skill、common-agent-observability。
  • 后端已按业务域拆分模块，每个业务模块均已形成 controller / service / service/impl / mapper / entity / dto / vo / factory 主体结构。
  • sys_enum、整型枚举协议、PersistableSysEnumDefinition 契约、BaseEntity 审计习惯均保持不变。
  • 前端 Studio 九个工作台页面均已对接真实 API，API 层与页面单测已覆盖主要聚合接口。
  • 旧管理接口继续兼容；Studio 原型新增聚合接口用于支撑工作台页面，不替代低层 CRUD 接口。

3. 模块核对

3.1 common

已核对内容：

  • 实体与 SQL 对应：
    • sys_enum -> common-agent-common/src/main/java/com/bruce/common/domain/entity/SysEnum.java
    • sys_attachment -> common-agent-common/src/main/java/com/bruce/common/domain/entity/SysAttachment.java
  • 基础模型：
    • BaseEntity、RequestResult<T>、全局异常、审计配置均位于 com.bruce.common
  • 接口：
    • POST /api/sys-enum/list
    • POST /api/sys-enum/query
    • POST /api/sys-enum/queryForManagement
    • GET /api/sys-enum/detail
    • POST /api/sys-enum/save
    • POST /api/sys-enum/batchSave
    • POST /api/sys-enum/delete
    • POST /api/attachments/upload
  • 文档解析：
    • document/parse 与 document/parse/impl 已提供解析抽象和解析器工厂

证据：

  • 代码：common-agent-common/src/main/java/com/bruce/common/controller/*
  • 测试：
    • common-agent-common/src/test/java/com/bruce/common/controller/SysEnumControllerTests.java
    • common-agent-common/src/test/java/com/bruce/common/factory/*
    • common-agent-common/src/test/java/com/bruce/common/document/parse/*
    • common-agent-common/src/test/java/com/bruce/common/handler/GlobalExceptionHandlerTests.java

3.2 rag

已核对内容：

  • 实体已覆盖：
    • rag_store
    • rag_document
    • rag_document_parse_result
    • rag_chunk
    • rag_chunk_embedding
  • 旧接口保持兼容：
    • /api/rag/store/*
    • /api/rag/documents/*
  • 聚合接口已提供：
    • GET /api/knowledge/workspaces/{storeId}
    • POST /api/knowledge/ingestion-runs
    • GET /api/knowledge/ingestion-runs/{runId}
  • 受控最小运行链路已落地：
    • 批量上传
    • 手动解析
    • 手动切片
    • 向量化记录聚合查询

本轮补充：

  • 新增 POST /api/knowledge/ingestion-runs，与前端实现文档草案保持一致。

证据：

  • 代码：
    • common-agent-rag/src/main/java/com/bruce/rag/controller/*
    • common-agent-rag/src/main/java/com/bruce/rag/service/impl/IngestionRunServiceImpl.java
  • 测试：
    • common-agent-rag/src/test/java/com/bruce/rag/controller/IngestionRunControllerTests.java
    • common-agent-rag/src/test/java/com/bruce/rag/ingestion/IngestionRunServiceTests.java
    • common-agent-rag/src/test/java/com/bruce/rag/workspace/KnowledgeWorkspaceServiceTests.java
    • 其余 Rag*Tests

3.3 modelprovider

已核对内容：

  • 实体已覆盖：
    • model_provider
    • model_config
    • model_route_rule
    • rag_store_model_config
    • model_call_log
  • 控制器已覆盖：
    • ModelProviderController
    • ModelConfigController
    • ModelRouteRuleController
    • RagStoreModelConfigController
    • ModelCallLogController
    • ModelWorkspaceController
  • 网关抽象已位于 gateway

证据：

  • 代码：common-agent-modelprovider/src/main/java/com/bruce/modelprovider/**/*
  • 测试：
    • common-agent-modelprovider/src/test/java/com/bruce/modelprovider/controller/ModelWorkspaceControllerTests.java
    • common-agent-modelprovider/src/test/java/com/bruce/modelprovider/workspace/ModelWorkspaceServiceTests.java
    • common-agent-modelprovider/src/test/java/com/bruce/modelprovider/factory/ModelProviderFactoryTests.java

3.4 agent

已核对内容：

  • 实体已覆盖：
    • agent_definition
    • agent_session
    • agent_message
    • agent_capability_binding
  • 兼容接口与会话接口并存：
    • Agent 定义管理
    • /api/agents/{agentId}/chat
    • /api/agent-sessions/*
    • 工作台聚合接口

证据：

  • 代码：common-agent-agent/src/main/java/com/bruce/agent/**/*
  • 测试：
    • common-agent-agent/src/test/java/com/bruce/agent/controller/AgentSessionControllerTests.java
    • common-agent-agent/src/test/java/com/bruce/agent/session/AgentSessionServiceTests.java
    • common-agent-agent/src/test/java/com/bruce/agent/workspace/AgentWorkspaceServiceTests.java

3.5 workflow

已核对内容：

  • 实体已覆盖：
    • studio_project
    • workflow_definition
    • workflow_version
    • workflow_run
    • workflow_run_step
  • 控制器已覆盖：
    • ProjectController
    • WorkflowDefinitionController
    • WorkflowVersionController
    • WorkflowRunController
    • WorkflowWorkspaceController
  • 前端工作台聚合使用 GET /api/workflow-workspace/detail； 旧管理接口继续承担定义、版本与运行管理能力。
  • 文档草案兼容路径已补充：
    • GET /api/workflows/{workflowId}
    • POST /api/workflows/save-draft
    • POST /api/workflow-versions/compat/workflows/{workflowId}/publish
    • POST /api/workflow-runs/compat/workflows/{workflowId}/runs
    • GET /api/workflow-runs/compat/workflows/runs/{runId}

证据：

  • 代码：common-agent-workflow/src/main/java/com/bruce/workflow/**/*
  • 测试：
    • common-agent-workflow/src/test/java/com/bruce/workflow/controller/WorkflowCompatControllerTests.java
    • common-agent-workflow/src/test/java/com/bruce/workflow/controller/WorkflowWorkspaceControllerTests.java
    • common-agent-workflow/src/test/java/com/bruce/workflow/workspace/WorkflowWorkspaceServiceTests.java
    • common-agent-workflow/src/test/java/com/bruce/workflow/version/WorkflowVersionServiceTests.java
    • common-agent-workflow/src/test/java/com/bruce/workflow/WorkflowComponentStructureTests.java

3.6 mcp

已核对内容：

  • 实体已覆盖：
    • mcp_server
    • mcp_capability
  • 接口已覆盖：
    • POST /api/mcp/import
    • GET /api/mcp/servers
    • POST /api/mcp/servers/query
    • GET /api/mcp/servers/{serverId}/capabilities
    • GET /api/mcp/servers/code/{serverCode}/capabilities
    • POST /api/mcp/capabilities/save
    • GET /api/mcp/workspace

证据：

  • 代码：common-agent-mcp/src/main/java/com/bruce/mcp/**/*
  • 测试：
    • common-agent-mcp/src/test/java/com/bruce/mcp/controller/McpImportControllerTests.java
    • common-agent-mcp/src/test/java/com/bruce/mcp/importing/McpImportServiceTests.java
    • common-agent-mcp/src/test/java/com/bruce/mcp/workspace/McpWorkspaceServiceTests.java

3.7 skill

已核对内容：

  • 实体已覆盖：
    • skill_definition
    • skill_version
  • 工作台接口已覆盖：
    • GET /api/skills/{skillCode}
    • POST /api/skills/{skillCode}/draft
    • PUT /api/skills/{skillCode}/draft
    • POST /api/skills/{skillCode}/test
    • POST /api/skills/{skillCode}/publish
    • POST /api/skills/{skillCode}/archive

证据：

  • 代码：common-agent-skill/src/main/java/com/bruce/skill/**/*
  • 测试：
    • common-agent-skill/src/test/java/com/bruce/skill/controller/SkillWorkspaceControllerTests.java
    • common-agent-skill/src/test/java/com/bruce/skill/version/SkillVersionServiceTests.java
    • common-agent-skill/src/test/java/com/bruce/skill/workspace/SkillWorkspaceServiceTests.java

3.8 observability

已核对内容：

  • 聚合来源已复用：
    • workflow_run
    • workflow_run_step
    • model_call_log
    • agent_session
    • agent_message
  • 接口已覆盖：
    • GET /api/observability/runs
    • GET /api/observability/runs/{requestId}
    • GET /api/observability/model-calls
    • GET /api/observability/runs/{requestId}/export
  • 导出接口返回脱敏摘要对象

证据：

  • 代码：common-agent-observability/src/main/java/com/bruce/observability/**/*
  • 测试：
    • common-agent-observability/src/test/java/com/bruce/observability/controller/ObservabilityTraceControllerTests.java
    • common-agent-observability/src/test/java/com/bruce/observability/trace/ObservabilityTraceServiceTests.java

4. 前端对接核对

已核对内容：

  • Studio 页面：
    • frontend/src/pages/studio/StudioDashboardPage.vue
    • frontend/src/pages/studio/KnowledgeWorkspacePage.vue
    • frontend/src/pages/studio/IngestionPipelinePage.vue
    • frontend/src/pages/studio/ModelWorkspacePage.vue
    • frontend/src/pages/studio/WorkflowBuilderPage.vue
    • frontend/src/pages/studio/AgentWorkspacePage.vue
    • frontend/src/pages/studio/McpImportPage.vue
    • frontend/src/pages/studio/SkillWorkspacePage.vue
    • frontend/src/pages/studio/ObservabilityPage.vue
  • API 封装已覆盖：
    • frontend/src/api/*.ts
  • 页面/API 单测已覆盖：
    • frontend/src/pages/studio/__tests__/*
    • frontend/src/api/__tests__/*

4.1 文档草案路径兼容收口

为减少“文档草案路径”和“现有聚合接口路径”之间的偏差，当前已额外补齐以下兼容入口：

  • Workflow：
    • GET /api/workflows/{workflowId}
    • POST /api/workflows/save-draft
    • POST /api/workflow-versions/compat/workflows/{workflowId}/publish
    • POST /api/workflow-runs/compat/workflows/{workflowId}/runs
    • GET /api/workflow-runs/compat/workflows/runs/{runId}
  • Agent：
    • POST /api/agents/{agentId}/runs
    • GET /api/agent-sessions/agents/{agentId}/sessions
    • GET /api/agent-sessions/{sessionId}
  • MCP：
    • POST /api/mcp/servers/query
  • Skill：
    • PUT /api/skills/{skillCode}/draft

5. 当前仍需持续关注的风险

  • 当前多数“mapper / repository 验证”仍以结构契约测试为主，真实数据库集成测试覆盖度有限。
  • 当前实现仍保留“旧管理接口 + Studio 聚合接口 + 文档草案兼容路径”的三轨并行方式，能力已覆盖，但后续如进入正式 API 收敛阶段，仍建议选定长期主路径并逐步淘汰别名。
  • 现有运行链路以“主数据优先 + 最小可运行”实现为主，复杂分支调度、远程 MCP 实时执行编排、重型运行器能力仍适合后续继续增强。

6. 本次审计后的新增变更

  • 新增 POST /api/knowledge/ingestion-runs，补齐前端实现文档中的摄取运行创建入口。
  • 补充 IngestionRunControllerTests 与前端 ingestion.spec.ts 创建接口测试。
  • 补充 WorkflowWorkspaceController 中文注释与标准化业务日志。
  • 补充 Workflow / Agent / MCP / Skill 的文档草案兼容路径与控制器测试。
Reference in New Issue View Git Blame Copy Permalink