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：

{
  "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

---

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