# 行动召回功能实现说明

## 📋 实现概述

本次实现完成了**行动召回功能**的完整开发，遵循项目的分层架构规范，包括接口定义、业务逻辑、服务适配器等各层代码。

## ✅ 已完成内容

### 1. 接口定义层 (interfaces)

**文件:** `/server/interfaces/action_recall.go`

定义了完整的数据模型和接口：
- ✅ `ActionRecallRequest` - 行动召回请求模型
- ✅ `ActionRecallResponse` - 行动召回响应模型
- ✅ `DynamicTool` - 动态工具定义
- ✅ `FixedParams` - 固定参数结构
- ✅ `QueryActionsRequest/Response` - 行动查询相关模型
- ✅ `GetToolDetailRequest/Response` - 工具详情相关模型
- ✅ `IActionRecallService` - 业务逻辑服务接口
- ✅ `DrivenOntologyQueryAction` - 行动查询适配器接口
- ✅ `DrivenOperatorToolbox` - 工具箱服务适配器接口

### 2. 被驱动适配器层 (drivenadapters)

#### 文件 1: `/server/drivenadapters/ontology_query_action.go`
- ✅ 实现 `DrivenOntologyQueryAction` 接口
- ✅ 封装行动查询服务（ontology-query）的 HTTP 调用
- ✅ 完整的错误处理和日志记录

#### 文件 2: `/server/drivenadapters/operator_toolbox.go`
- ✅ 实现 `DrivenOperatorToolbox` 接口
- ✅ 封装工具箱服务（agent-operator-integration）的 HTTP 调用
- ✅ 获取工具详情功能

### 3. 业务逻辑层 (logics/actionrecall)

#### 文件 1: `/server/logics/actionrecall/index.go`
- ✅ 服务实例化和依赖注入
- ✅ 单例模式实现

#### 文件 2: `/server/logics/actionrecall/get_action_info.go`
- ✅ 核心业务逻辑 `GetActionInfo` 实现
- ✅ 完整的处理流程：
  1. 参数转换（unique_identity → unique_identities）
  2. 调用行动查询接口
  3. 校验 action_source 类型（仅支持 tool）
  4. 获取工具详情
  5. 生成 API URL
  6. 映射固定参数
  7. 转换 Schema
  8. 构建动态工具

#### 文件 3: `/server/logics/knactionrecall/schema_converter.go`
- ✅ OpenAPI Schema → OpenAI Function Call Schema 转换
- ✅ **分层结构实现**：保持 header/path/query/body 位置信息
- ✅ **$ref 递归解析**：完整支持 OpenAPI $ref 引用
- ✅ **循环引用防护**：检测并防止无限递归
- ✅ 固定参数映射逻辑（支持基于 OpenAPI 定义和命名规则）

> 📖 **详细实现原理请参考：** [Schema转换实现原理.md](./Schema转换实现原理.md)

### 4. 驱动适配器层 (driveradapters/actionrecall)

**文件:** `/server/driveradapters/actionrecall/index.go`
- ✅ HTTP Handler 实现
- ✅ 请求参数绑定和校验
- ✅ 统一的错误处理和响应格式

### 5. 路由注册

**文件:** `/server/driveradapters/rest_private_handler.go`
- ✅ 注册新路由: `POST /api/agent-retrieval/in/v1/kn/get_action_info`
- ✅ 集成到现有的私有接口路由组

### 6. 错误码和国际化

#### 错误码定义 (`/server/infra/errors/error_code.go`)
- ✅ `ErrExtActionRecallUnsupportedType` - 不支持的行动源类型
- ✅ `ErrExtActionRecallNoActionsFound` - 未找到可用行动
- ✅ `ErrExtActionRecallSchemaConvertFailed` - Schema 转换失败
- ✅ `ErrExtActionRecallToolNotFound` - 工具不存在

#### 国际化翻译
- ✅ 中文翻译 (`/server/infra/localize/locales/zh-Hans.json`)
- ✅ 英文翻译 (`/server/infra/localize/locales/en-US.json`)
- ✅ 包含错误描述、解决方案

## 🎯 关键设计决策

### 1. 仅处理 actions[0]
- **原因**: 当前版本只支持单个 action，使用 `unique_identity`（单数）入参
- **实现**: 从行动查询响应的 actions 数组中只取第一个元素

### 2. 忽略 dynamic_params
- **原因**: dynamic_params 由 LLM 动态生成，不在行动召回接口的处理范围内
- **实现**: 只处理 `actions[0].parameters`（固定参数）

### 3. 参数位置映射策略
- **优先策略**: 根据 OpenAPI 定义中的 `in` 字段判断参数位置
- **备用策略**: 基于命名规则（如 x- 开头识别为 header）
- **灵活性**: 最终由调用方根据 `original_schema` 和 `fixed_params` 组装请求

### 4. 仅支持 tool 类型
- **当前版本**: 只处理 `type=tool` 的行动源
- **下个版本**: 预留 MCP 类型支持的扩展点

## 📡 API 接口

### 请求示例

```bash
curl --location 'http://agent-retrieval-svc:8000/api/agent-retrieval/in/v1/kn/get_action_info?kn_id=kn_medical&at_id=generate_treatment_plan' \
--header 'x-account-id: bdb78b62-6c48-11f0-af96-fa8dcc0a06b2' \
--header 'x-account-type: user' \
--header 'Content-Type: application/json' \
--data '{
    "unique_identity": {
        "disease_id": "disease_000001"
    }
}'
```

### 响应示例

```json
{
    "_dynamic_tools": [
        {
            "name": "根据单个对象类查询对象实例",
            "description": "该接口基于业务知识网络语义检索接口返回的对象类定义，查询具体的对象实例数据。",
            "parameters": {
                "type": "object",
                "properties": {
                    "kn_id": {
                        "type": "string",
                        "description": "业务知识网络ID"
                    },
                    "ot_id": {
                        "type": "string",
                        "description": "对象类ID"
                    }
                },
                "required": ["kn_id", "ot_id"]
            },
            "api_url": "http://agent-operator-integration:9000/api/agent-operator-integration/internal-v1/tool-box/xxx/proxy/yyy",
            "original_schema": {...},
            "fixed_params": {
                "header": {
                    "x-account-id": "test",
                    "x-account-type": "user"
                },
                "path": {},
                "query": {},
                "body": {}
            }
        }
    ]
}
```

## 📁 文件清单

```
server/
├── interfaces/
│   └── action_recall.go                    ✅ 接口定义
├── drivenadapters/
│   ├── ontology_query_action.go            ✅ 行动查询客户端
│   └── operator_toolbox.go                 ✅ 工具箱客户端
├── logics/actionrecall/
│   ├── index.go                            ✅ 服务入口
│   ├── get_action_info.go                  ✅ 核心业务逻辑
│   └── schema_converter.go                 ✅ Schema 转换工具
├── driveradapters/
│   ├── actionrecall/
│   │   └── index.go                        ✅ HTTP Handler
│   └── rest_private_handler.go             ✅ 路由注册（已更新）
└── infra/
    ├── errors/
    │   └── error_code.go                   ✅ 错误码定义（已更新）
    └── localize/locales/
        ├── zh-Hans.json                    ✅ 中文翻译（已更新）
        └── en-US.json                      ✅ 英文翻译（已更新）
```

## ✅ 编译验证

```bash
cd /root/codes/agent-retrieval
go build ./server/...
```

**结果**: ✅ 编译成功，无错误

## 🚀 部署说明

### 1. 配置文件更新
需要确保配置文件中包含以下配置：
- `OntologyQuery` 服务地址（已存在）
- `OperatorToolbox` 服务地址（需要添加，当前硬编码为 `http://agent-operator-integration:9000`）

### 2. 依赖服务
确保以下服务可用：
- ontology-query 服务
- agent-operator-integration 服务

### 3. 启动服务
```bash
cd /root/codes/agent-retrieval
go run server/main.go
```

## 🔧 TODO 和后续优化

### MVP 版本已完成 ✅
- [x] 接口定义和路由
- [x] 参数转换（unique_identity → unique_identities）
- [x] 调用行动查询接口
- [x] 调用工具详情接口（仅 type=tool）
- [x] 仅处理 actions[0]
- [x] 生成 api_url
- [x] 固定参数映射（基于 OpenAPI 定义或命名规则）
- [x] 基础的 Schema 转换（扁平化，不保留位置信息）
- [x] 异常处理（type != tool 时返回错误）

### 第二阶段：Schema 转换增强 📋
- [x] ✅ **$ref 递归解析**（从 components.schemas 中查找并展开）
- [x] ✅ **循环引用防护**（检测并防止无限递归）
- [x] ✅ **分层结构实现**（保持 header/path/query/body 位置信息）
- [ ] 复杂 schema 类型支持（allOf, oneOf, anyOf）
- [ ] Schema 缓存机制（避免重复解析）
- [ ] 转换规则配置化（支持自定义映射规则）

### 第三阶段：扩展支持 📋
- [ ] MCP 类型行动源支持
- [ ] 多个 actions 的处理策略
- [ ] 行动召回结果缓存
- [ ] 可观测性增强（日志、监控、追踪）
- [ ] 支持行动的条件匹配

## 📖 参考文档

- [需求设计文档](./需求设计文档.md)
- [Schema转换实现原理](./Schema转换实现原理.md) ⭐ **新增：详细实现原理说明**
- [OpenAPI 接口文档](./action-recall.openapi.yaml)
- [原始需求](./01-需求.md)
- [依赖接口文档](./99-依赖接口/)

## 👥 开发团队

- 开发完成时间: 2025-12-23
- 遵循规范: 项目分层架构、Go 编码规范
- 测试状态: 编译通过，待集成测试

---

**实现状态**: ✅ 完成 MVP 版本
**编译状态**: ✅ 通过
**文档状态**: ✅ 完整

