Bruce/common_agent

Fork 0

Files

bruce edc3babe6b docs(audit): 补充目标逐条验收矩阵

2026-06-01 06:19:54 +08:00

14 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 接口。

2.1 目标逐条验收矩阵

以下矩阵直接对照本次目标中的显式要求，标记当前证据状态：

验收项	当前状态	主要证据
以 `docs/需求分析`、`docs/设计文档`、`docs/数据库设计`、`docs/后端实现文档`、`docs/前端实现文档` 为实现依据	已核对	本文档第 1 节与模块核对章节；`docs/数据库设计/9.模块一致性校验.md`
后端为 Maven 多模块单体架构	已实现	根 `pom.xml` 的 9 个子模块；`common-agent-boot` 作为启动模块
模块按业务域拆分，而不是按技术类型散落	已实现	`common-agent-common`、`rag`、`modelprovider`、`agent`、`workflow`、`mcp`、`skill`、`observability` 子模块
`sys_enum` 设计与整型枚举协议保持不变	已实现	`script/sql/1.enum.sql`、`script/sql/18.studio_enum.sql`、`PersistableSysEnumDefinition`、`EnumDefinitionTests`
Entity 与 SQL 表结构一致	已强验证	`SqlEntityMappingContractTests` + `docs/数据库设计/9.模块一致性校验.md`
Controller 不直接暴露 Entity，统一 DTO/VO/RequestResult	已实现	各模块控制器签名；controller/component 测试
Factory/Assembler 承担 DTO/Entity/VO 转换	已实现	各模块 `factory` 包与 `*FactoryTests`
Service 承担业务逻辑、状态流转、校验	已实现	各模块 `service/impl` 与 `*ServiceTests`
Mapper 使用 MyBatis-Plus，数据访问与脚本命名一致	基本实现，证据中等	`BaseMapper` 结构测试 + SQL/Entity 契约测试；真实 DB 读写集成仍偏少
核心流程补中文注释与中文业务日志	基本实现，证据中等	`1d401c68` 提交 + 关键控制器/服务实现；未做全仓逐文件注释覆盖率检测
每模块补测试并运行	已实现	当前后端测试文件 68 个；前端 API/页面测试 25 个；多轮 reactor/vitest/build 验证
前端 Studio 页面与真实 API 对接	已实现	9 个工作台页面、16 个 API 单测、9 个页面单测、`npm run build` 通过
旧接口兼容且新增聚合接口支撑工作台	已实现	RAG/Agent/Workflow/MCP/Skill 文档草案兼容路径与聚合接口
输出模块完成总结、测试结果、本地提交	已持续执行	最近提交记录：`c8245ba0`、`73237507`、`d5d239ae` 等

说明：

上表中“基本实现，证据中等”的项目，不表示发现功能缺失，而是提示当前最强证据还不如“脚本/实体一致性”那样直接。
目前最薄弱的仍是“真实数据库读写集成测试”和“全仓中文日志/注释覆盖率的自动化证明”。

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 的文档草案兼容路径与控制器测试。

14 KiB Raw Blame History Unescape Escape

Common Agent Studio 模块完成度审计

1. 审计范围

2. 总体结论

2.1 目标逐条验收矩阵

3. 模块核对

3.1 common

3.2 rag

3.3 modelprovider

3.4 agent

3.5 workflow

3.6 mcp

3.7 skill

3.8 observability

4. 前端对接核对

4.1 文档草案路径兼容收口

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

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

14 KiB

Raw Blame History