aiagent/docs/zhini-kefu/知你客服能力的集成和扩展方案.md

# 知你客服能力的集成和扩展方案

本文面向**业务/App 对接**与**平台内二次开发**，说明如何将「知你客服」系列 Agent 接入自有系统，以及如何安全、可维护地扩展工具与版本。具体某版本能力见 `知你客服14号能力文档.md`，记忆机制见 `agent记忆实现方案.md`，App 侧 HTTP 细节可参考 `知你客服Agent智能聊天App接入方案.md`。

---

## 一、集成目标与边界

| 目标 | 说明 |
|------|------|
| **对话能力** | 通过平台 **执行 API** 创建异步任务，由 **Celery** 跑完工作流后返回 `output_data`。 |
| **多轮记忆** | 依赖工作流 **Cache** 键（常见 `user_memory_{user_id}`）；集成侧必须传**稳定 `user_id`**，否则记忆串号或落在 `default`。 |
| **能力边界** | 具体能调用的工具、提示词约束以**当前 Agent 工作流**为准（如 14 号含全量内置工具）；文件、DB、adb 等受**部署环境与配置**限制。 |

---

## 二、集成方式选型

| 方式 | 适用 | 要点 |
|------|------|------|
| **后端代理（推荐）** | 移动 App、多端、需隐藏平台账号 | 服务端用平台账号换 `access_token`，代用户调 `POST /api/v1/executions`，再轮询状态/详情。 |
| **前端直连** | Web、用户已在平台登录 | 浏览器携带 Bearer Token 调同一套 API；需处理 CORS 与 Token 刷新。 |
| **内嵌平台对话页** | 快速验证 | iframe/WebView 打开平台「使用」页，不直接对接执行 API。 |

仓库内 **SAARS** 等示例提供「平台登录 + 转发执行」的代理思路，可与上述方式一对照实现。

---

## 三、执行 API 集成要点

### 3.1 认证

- `POST /api/v1/auth/login`（`application/x-www-form-urlencoded`）获取 `access_token`。
- 后续请求头：`Authorization: Bearer <access_token>`。

### 3.2 创建执行

- `POST /api/v1/executions`
- 典型 body：

```json
{
  "agent_id": "<知你客服某版本的 Agent UUID>",
  "input_data": {
    "query": "用户本轮输入",
    "USER_INPUT": "用户本轮输入",
    "user_id": "业务侧稳定用户标识"
  }
}
```

- **`user_id`**：强烈建议传入且长期不变，与 Cache 键一致方可多轮隔离。
- 字段名可与工作流 Start 节点约定对齐（常见 `query` / `USER_INPUT`）。

### 3.3 获取结果

1. `GET /api/v1/executions/{id}/status` 直至 `completed` / `failed`。  
2. `GET /api/v1/executions/{id}` 读取 **`output_data`**。

### 3.4 展示层处理（避免重复 JSON）

知你类工作流常约定：**自然语言 + 最后一行单行 JSON**（`intent` / `reply` / `user_profile`）。  
前端若直接展示整段字符串，用户会看到「正文 + JSON」重复感。可参考平台 **`AgentChatPreview`** 中的做法：展示前去掉末行结构化 JSON，或仅展示 JSON 中的 `reply`（以产品为准）。

### 3.5 运维

- 工作流在 **Celery Worker** 中执行；升级**引擎或工具**后需 **重启 API + Celery**（可用 `backend/scripts/restart_api_worker.ps1`）。
- 轮询间隔建议约 **0.5～1 s**，并设总超时。

---

## 四、记忆与持久化（集成侧责任）

- **键隔离**：必须传 **`user_id`**；详见 `agent记忆实现方案.md`。  
- **Redis + 可选 MySQL**：热数据与持久化关系、合并规则、条数截断（如默认 `max_history_length`）见该文档。  
- **业务无关数据**：勿把敏感密钥写入可被 `file_write` 触及的公开路径；生产环境应配置 **`LOCAL_FILE_TOOLS_ROOT`** 等。

---

## 五、扩展路径总览

```
┌─────────────────────────────────────────────────────────────┐
│  扩展维度          │  主要改动位置                              │
├─────────────────────────────────────────────────────────────┤
│  新内置工具        │  builtin_tools 实现 + tools_bootstrap 注册 │
│  新版本 Agent      │  scripts/create_zhini_kefu_XX.py 复制/补丁  │
│  工作流结构        │  平台工作流编辑器 + 导出/入库 API           │
│  提示词与工具列表  │  llm-unified 节点 data.prompt / tools      │
│  HTTP/外部工具     │  平台「工具管理」中配置 + tool_registry     │
└─────────────────────────────────────────────────────────────┘
```

---

## 六、扩展内置工具（后端）

1. **实现**：在 `backend/app/services/builtin_tools.py` 中实现异步函数，并定义 **JSON Schema**（与 OpenAI function calling 兼容）。  
2. **注册**：在 `backend/app/core/tools_bootstrap.py` 的 `ensure_builtin_tools_registered` 中 **`register_builtin_tool(name, func, schema)`**。  
3. **生效**：确保 **API 进程与 Celery Worker** 均会 import 执行流（已含 bootstrap）；部署后**重启**两处进程。  
4. **工作流**：在目标 Agent 的 **LLM 节点** `data.tools` / `selected_tools` 中加入新工具名，`enable_tools: true`。

**注意**：工具名、参数 schema 与模型实际调用必须一致；敏感能力（如 shell）不建议放入内置工具。

---

## 七、扩展「知你客服」版本（脚本化）

- 仓库已提供 **`create_zhini_kefu_12.py` … `create_zhini_kefu_14.py`** 等脚本：登录平台 → 复制 Agent → 调整边与布局 → 更新 `llm-unified` 提示词与工具列表 → `PUT` 写回。  
- **推荐做法**：以**上一稳定版本**为源复制，只改差异（工具数组、追加提示段落、描述），便于回溯。  
- **文档**：为新版本补充 **`知你客服XX号能力文档.md`**，避免运营与开发认知不一致。

---

## 八、扩展工作流结构（天工）

- 在平台 **工作流设计器** 中增删节点：Cache、LLM、条件分支、向量检索、HTTP 等。  
- **记忆链路**勿随意断开：保证 **读 Cache → LLM → 写 Cache** 顺序仍可达，且 `user_memory_*` 键模板未破坏。  
- **自动布局**仅影响坐标，不改变执行语义；复杂图建议配合引擎的占位符与合并逻辑测试多轮对话。

---

## 九、安全与合规

| 项 | 建议 |
|----|------|
| **database_query** | 引擎侧限制 **SELECT**；生产应限制可见表/行或仅用只读账号；勿在提示词中鼓励随意扫库。 |
| **adb_log** | 仅在内网或受控环境开启；需本机 adb 与设备授权。 |
| **file_read / file_write** | 严格 **`LOCAL_FILE_TOOLS_ROOT`**；控制写入大小上限。 |
| **http_request** | 注意 SSRF 与出站策略（若平台侧有网关/白名单应一并配置）。 |
| **Token** | App 代理勿把平台账号密码下发客户端；`access_token` 缓存于服务端并处理过期。 |

---

## 十、测试建议

- **单轮**：工具是否被调用、返回是否进入 `reply` 或末行 JSON。  
- **多轮**：同一 `user_id` 连续两轮，验证画像与历史是否写入 Cache/DB。  
- **回归**：升级引擎或工具后跑一遍「问名—再问名」与一次需要工具调用的用例。

---

## 十一、相关文档与代码索引

| 说明 | 路径 |
|------|------|
| 14 号能力与工具表 | `知你客服14号能力文档.md` |
| 记忆与 Redis/DB | `agent记忆实现方案.md` |
| App HTTP 接入示例 | `知你客服Agent智能聊天App接入方案.md` |
| 创建/更新 14 号脚本 | `backend/scripts/create_zhini_kefu_14.py` |
| 内置工具注册 | `backend/app/core/tools_bootstrap.py` |
| 引擎与 Cache | `backend/app/services/workflow_engine.py` |

---

*随平台版本与仓库迭代，以实际接口与工作流配置为准。*