# 平台定位与架构总览

## 当前定位

睿池 ReachAI 当前定位是“面向 Java 企业系统的 Agent 开发与治理中台”。它既服务历史系统低侵入接入，也服务可改造业务系统通过 SDK 主动声明能力。平台核心不是聊天窗口，而是把企业能力资产注册、理解、编排、执行、治理和开放成一条可追踪链路。

## 当前已落地

### 服务边界

| 模块 | 当前职责 | 主要代码 |
| --- | --- | --- |
| `ai-agent-service` | Agent、注册中心、能力目录、Studio、Runtime、RunOps、MCP/A2A、治理与市场 | `ai-agent-service/src/main/java/com/enterprise/ai/agent` |
| `ai-skills-service` | 知识库、文档处理、RAG、业务索引、扫描器和向量化辅助 | `ai-skills-service/src/main/java/com/enterprise/ai` |
| `ai-model-service` | 模型实例、Chat、Embedding、Rerank、OpenAI 兼容代理 | `ai-model-service/src/main/java/com/enterprise/ai/model` |
| `ai-skill-sdk` | `AiTool`、`AiSkill`、`ToolRegistry`、`@AiCapability`、`@AiParam`、`@AiOutput` 契约 | `ai-skill-sdk/src/main/java/com/enterprise/ai/skill` |
| `ai-spring-boot-starter` | 业务系统自动扫描、注册、心跳、能力同步、SDK 图同步、嵌入式 Runtime 入口 | `ai-spring-boot-starter/src/main/java/com/enterprise/ai/spring/registry` |
| `ai-admin-front` | 管理端，承载注册中心、Agent、知识、模型、治理和开放协议页面 | `ai-admin-front/src/router/index.ts` |

### 管理端功能地图

前端路由显示当前产品已经形成以下区域：

- Agent：`AgentList.vue`、`AgentEdit.vue`、`AgentStudio.vue`、`AgentVersions.vue`、`AgentDebug.vue`。
- RunOps：`RunOpsList.vue`、`RunOpsDetail.vue`。
- 注册中心：`RegistryProjectList.vue`、`RegistryProjectDetail.vue`、`CapabilitySyncDebug.vue`、`RuntimeRegistry.vue`。
- Tool 与 Capability：`ToolList.vue`、`ToolRetrievalTest.vue`、`CapabilityList.vue`、`CapabilityMining.vue`。
- 槽位与交互能力：`SlotExtractorList.vue`、`SlotDictDept.vue`、`SlotDictUser.vue`、`SlotExtractLogs.vue`。
- 知识与业务索引：`KnowledgeList.vue`、`KnowledgeDetail.vue`、`KnowledgeImport.vue`、`RetrievalTest.vue`、`BizIndexList.vue`、`BizIndexDetail.vue`。
- 模型：`ModelInstances.vue`、`ModelPlayground.vue`。
- 对外开放：`McpVisibilityBoard.vue`、`McpClientList.vue`、`McpCallMonitor.vue`、`McpOnboarding.vue`、`A2aEndpointList.vue`、`A2aSessionMonitor.vue`。
- 治理：`ToolAclList.vue`、`DomainList.vue`、`DomainAssignmentBoard.vue`、`DomainClassifierTest.vue`。

### 统一 SQL 基线

`sql/init.sql` 是当前首次上线基线，已经合并历史补丁。重要表包括：

- 模型与知识：`ai_model_instance`、`knowledge_base`、`file_info`、`chunk`、`knowledge_tag`、`knowledge_question`、`knowledge_hit_log`。
- 业务索引：`business_index`、`business_index_record`、`business_index_attachment`。
- 项目与能力：`scan_project`、`scan_module`、`scan_project_tool`、`tool_definition`。
- 语义和图谱：`semantic_doc`、`api_graph_node`、`api_graph_edge`、`api_graph_layout`。
- Agent：`agent_definition`、`agent_version`、`agent_release_event`、`agent_eval_dataset`、`agent_eval_case`、`agent_eval_run`、`agent_eval_case_result`。
- 运行日志：`tool_call_log`、`agent_trace_span`、`guard_decision_log`。
- 注册中心：`ai_project_instance`、`capability_sync_log`、`capability_snapshot`、`capability_diff_item`、`capability_apply_record`、`registry_project_credential`。
- 开放协议：`mcp_client`、`mcp_call_log`、`mcp_visibility`、`a2a_endpoint`、`a2a_call_log`、`a2a_task`。
- 治理和运营：`tool_acl`、`domain_def`、`domain_assignment`、`agent_workflow_credential`、`market_item`。

## 仍待补齐

- 统一 SQL 中仍有部分历史注释使用阶段编号或 legacy naming，后续应在 SQL 注释层同步改成产品能力口径。
- 根目录 `README.md` 仍过时，本轮没有改动；后续应按本目录文档重新改写。
- 前端路由已覆盖多数能力，但文档还没有逐页操作手册，本目录目前只维护架构和产品级知识。
- `ai-skills-service` 与 `ai-agent-service` 在扫描、语义和 RAG 上仍有交叉，后续需要继续明确长期服务边界。