23 KiB

Raw Permalink Blame History

📄 《智能体中枢架构迁移与部署方案》

0. 文档定位与阅读指南

0.1 面向对象

本文档的核心读者为系统架构师与后端开发工程师（轮机长团队）。

0.2 核心动作与交付契约

这是一份架构升级蓝图与接口契约指导。请各位轮机长在仔细阅读并透彻理解本方案后，结合原《旧版销售洞察智能体设计文档》（该文档定义了我们经受过市场验证的业务内核与 AI 逻辑），重新输出一份全新的、基于本混合架构的《V2.0 智能中枢系统详细设计文档》。

本方案未列出最终的开发里程碑，因为 “详细设计评审通过” 才是下一阶段开发工作正式启动的前提。

0.3 核心思想转变（Mindset Shift）

在进入具体的技术细节前，整个研发团队必须完成以下两个根本性的思想转变：

从“控制流硬编码”转向“Agentic 动态调度”：过去的系统里，用户的一个点击，是由 Java 代码里的 if-else 来决定调用哪个大模型 API；现在的系统里，Java 只是提供数据的“手脚”，真正决定下一步该干什么的是处于中枢位置的主控智能体（Agent）。
从“单体项目交付”转向“中台化可复用架构”：我们不再为“A医美机构”或“B教育集团”单独开发一套包含完整 AI 逻辑的后台代码。我们要构建的是一个“通用的高客单价销售 AI 中枢”，业务线的差异仅仅体现为配置参数和外部挂载知识库的不同。

1. 架构升级背景：为什么我们要引入这套新底座？

在第一轮的开发迭代中，我们成功跑通了业务闭环，证明了我们基于“深度画像”与“专业复盘”的智能体能够切实帮客户提升销售转化率。但随着业务准备向多行业（如眼镜、教育、金融）、多企业横向扩张，我们底层的工程架构正在逼近极限。

1.1 痛点直击：我们当下的工程泥潭

如果你是负责核心后台的开发，你现在一定面临着以下极其痛苦的现状：

代码泥潭与极度耦合：当前，系统完全依靠手工编写的 Java 代码来管理 LLM（大语言模型）的调用。冗长且极易变动的 Prompt（提示词）被硬编码在字符串里；为了管理上下文，写了极其丑陋的会话状态机；一旦业务方要求切换更便宜或更聪明的底层模型（哪怕只是换一个 Provider），都可能引发伤筋动骨的代码重构。
单体地狱与复用灾难：我们目前的架构本质上是“将某个特定企业的业务逻辑与系统代码绑死”。这意味着，每当我们签下一个新行业的客户，就需要把整套代码 Copy 一份，重新硬编码修改里面的业务约束并单独部署。这完全违背了 SaaS 化和 AI 中台化的商业愿景，维护成本正在呈指数级上升。

1.2 破局之道：Dify + OpenClaw 的双擎驱动

为了彻底解决上述痛点，我们不再使用“手工作坊”的方式造轮子，而是引入业界最前沿的两大专业底座来进行明确的职责解耦：

为什么引入 Dify（打造专家大脑中台）？

价值定位：剥离极易挥发的 AI 认知逻辑。
解决的问题：把所有的 Prompt、复杂的多步推理（如 A1/A2/B/C 智能体的内部逻辑）、知识库检索机制，全部从 Java 后端代码中连根拔起，迁移到 Dify 平台。Dify 提供了可视化的工作流编排和极佳的模型切换兼容性，让我们的系统拥有了一个可独立维护、独立升级的“AI 大脑”。Java 工程师再也不用去维护大段的 Prompt 字符串了。

为什么引入 OpenClaw（打造自动化编排引擎）？

价值定位：原生智能体（Agentic）时代的中央调度器。
解决的问题：如果仅仅接入 Dify，我们依然需要在 Java 里写代码来决定“何时调用哪个 Dify 接口”。鉴于团队目前缺乏从零手搓 Agentic 框架的经验（目前的自研方案扩展性极差），我们直接引入在开源界备受推崇的新星框架 OpenClaw。
它能带来什么：
1. 开箱即用的路由与状态管理：它天生就是一个优秀的“调度员”，能够管理不同用户的并发会话（Session），自动识别用户意图并分发任务。
2. 原生支持 MCP（模型上下文协议）：它定义了一套标准，我们的 Java 后台以后只需要按照标准提供接口（比如“提供客户张三的聊天记录”），OpenClaw 的 Agent 就会在需要时主动来调用，彻底扭转了过去“Java 控制 AI”的被动局面，变成了“AI 根据需要调用 Java 接口”。
3. 多渠道原生接入：它自带与企业微信、飞书、WhatsApp 等多种 IM 工具的桥接能力，为我们未来将系统从“后台管理页面”推向“销售员聊天窗口（伴随式助理）”铺平了道路。

总结：医美销售系统负责提供数据底座（手脚），Dify 负责提供深度认知能力（左脑），而 OpenClaw 则是协调这一切、并主动对外沟通的中枢神经（右脑）。这就是我们此次迁移的终极目标。

内部思考与质量把控 (Internal Thought Process)

紧扣轮机长视角与架构解耦：第2章的核心是解决“C4-复用性与SaaS化”问题。对于习惯了单体应用的Java开发来说，“逻辑与数据分离”是常识，但“AI认知逻辑与行业知识分离”是个新课题。我需要用他们熟悉的“底层框架-中间件-业务层”概念来类比我们的“三层配置结构”，让他们明白以后接入新行业，只需要“配库”不需要“改代码”。
强调物理隔离与安全红线：第3章对应“C3-OpenClaw部署环境”。作为一个拥有底层系统操作权限的Agent框架，OpenClaw的安全性是当前的痛点。必须明确划定物理隔离边界，禁止OpenClaw直连数据库，强制所有交互走MCP协议。同时，安抚轮机长：以前写好的语音转写(ASR)和文本解析代码不用扔，继续在Java端跑，封装成接口给OpenClaw调就行。
语言风格保持：继续使用指令式、架构白皮书式的行文风格，辅以结构化图表展现层级关系，降低阅读者的认知负荷。

2. 核心架构跃迁：从“一次性项目”到“高复用 SaaS 后台”

为了实现真正的 AI 中台化，我们必须摒弃“来一个客户，拷一份代码，改一堆 Prompt”的作坊式开发。

从本质上看，无论是医美面诊、高端眼科咨询，还是国际学校招生、金融保险推销，它们都属于 “高客单价、高决策门槛的复杂销售” 。其背后的“通用销售心智模型”（接触 -> 痛点挖掘 -> 方案展示 -> 异议处理 -> 逼单转化）是完全一致的。

因此，我们的架构设计必须实现 “将不变的逻辑沉淀，将变化的知识外置” 。在新的部署架构中，系统将被严格划分为三个解耦的层级：

2.1 第一层：通用销售心智底座 (The Core)

物理归属：这一层是系统的“引擎”，部署在 OpenClaw (主控调度) 和 Dify (认知推理) 中。
核心内容：包含 OpenClaw 中的主控 Agent (wantsong-sales) 的调度逻辑，以及 Dify 中 A1(清洗)/A2(复盘)/B(画像)/C(话术) 四个专家智能体的骨架 Prompt 和工作流（Workflow）。
工程契约：这一层的代码和配置是跨行业、跨企业完全共享的。 无论接入哪个租户，这里的逻辑都不允许被硬编码修改。它只定义“如何进行心理分析（ORBIT/PRISM模型）”和“如何流转任务”，绝不包含“双眼皮手术多少钱”这种具象信息。

2.2 第二层：行业知识层 (Industry Domain)

物理归属：这一层是系统的“行业字典”，存储于医美系统/业务线数据库，或作为独立知识库挂载在 Dify 中。
核心内容：不同行业的专业术语、SOP 规范、行业黑话、通用痛点库。例如：医美行业的《抗衰项目话术库》或教育行业的《升学焦虑应对指南》。
工程契约：当 OpenClaw 的主控 Agent 接到请求时，它会通过参数（如 industry="医美"）动态调取该层的特定知识块，作为上下文喂给底座模型，实现“一秒切换行业大脑”。

2.3 第三层：企业定制层 (Enterprise Specifics)

物理归属：这一层是系统的“实时业务数据”，严格存放在各个租户自己的 CRM/业务系统数据库中。
核心内容：特定企业的介绍、具体的商品 SKU、实时价格表、过往成功案例，以及客户（如“张三”）的私密聊天记录和面诊录音。
工程契约：大模型绝不记忆这些动态数据。 这些数据必须由 Java 业务系统通过 MCP（Model Context Protocol）服务，在 Agent 需要分析时，像“递纸条”一样实时喂给 OpenClaw。

💡 给轮机长的话：理解了这三层结构，你们未来的工作就不再是“为客户 A 写一套 AI 系统”，而是“维护一套通用的 AI 底座，然后为客户 A 提供数据查询 API（MCP）”。这将极大解放你们的生产力。

3. 物理部署拓扑与安全隔离设计

鉴于 OpenClaw 是一个真正意义上的 Agentic 框架（它有能力执行脚本、读写文件、甚至反向控制系统），并且目前开源版本在沙箱隔离上仍在演进中，安全性与物理隔离是我们本次部署的最高红线。

3.1 三端隔离的网络与机器规划

系统将在物理/逻辑上拆分为三个独立运行的节点集：

大脑端（Dify 中台）：
- 负责执行最消耗算力的长文本推理和画像生成。
- 部署在独立的云服务或内部 GPU 集群上，通过标准 HTTP API 对外提供服务。
中枢端（OpenClaw 守护进程）：
- 这是所有流量的汇聚点和任务分发器。
- 强制要求：必须部署在一台完全独立、物理隔离的 Linux 服务器上。 绝对不允许将其与现有的医美数据库混合部署在同一台机器上。
- OpenClaw 将作为 Daemon（后台守护进程）常驻运行，管理所有的通道接入（IM/API）和 Session 状态。
前端与底座端（现有业务线/医美系统）：
- 这是传统的 Java 后台与前端页面。它掌握着客户核心资料、订单数据。
- 职责复用：原系统中已经开发好的“微信文本解析”、“录音文件 ASR 转写”等脏活累活，全部保留，不需要用 AI 重写。 这些功能继续在 Java 端运行，处理好后生成结构化文本。

3.2 交互契约与安全隔离策略

为了防止高权限的 OpenClaw Agent 出现幻觉或被恶意提示词注入（Prompt Injection）从而影响核心业务库，我们制定以下交互契约：

禁止直连数据库：OpenClaw 所在的 Linux 服务器，其网络策略（Firewall/VPC）禁止直接访问医美系统的 MySQL/Redis 数据库。
唯一的通信桥梁（MCP）：医美系统与 OpenClaw 之间，仅允许通过鉴权后的 MCP (基于 HTTP 的模型上下文协议) 进行受控的数据交换。
最小权限原则：Java 端提供的 MCP 接口必须是原子化且受限的。例如，只提供 get_parsed_chat_text(customer_id) 接口供 OpenClaw 读取清洗好的文本，而不提供任何可以被 Agent 泛化调用的底层 SQL 查询能力。

通过这种“物理隔离 + 协议白名单”的设计，我们既享受了 OpenClaw 强大的自动化编排能力，又死死守住了企业核心数据的安全底线。

内部思考与质量把控 (Internal Thought Process)

紧扣“体验跃迁”与“开发减负”：第4章的核心是展示引入 OpenClaw 后带来的巨大业务增量（即 IM 伴随式触发，C5需求）。必须向轮机长们讲清楚，过去要实现“飞书/企微机器人”需要在 Java 端写大量恶心的 Webhook 鉴权、消息解析和会话状态保持代码；现在有了 OpenClaw，这些工作全部由底座原生接管，Java 开发彻底解放。
通俗化解释 MCP (Model Context Protocol)：第5章是整篇文档最落地的“接口契约”。对于传统的 Java 工程师，“大模型主动调接口”是一个反直觉的概念。我必须将 MCP 降维解释为“带有标准格式的 RESTful API/Controller”，让他们明白：他们不需要学什么高深的 AI 框架原理，只需要按规范写好 Spring Boot 接口，OpenClaw 的主控 Agent 就会像一个“智能的前端”一样，在需要的时候自动发起 HTTP 请求。
流程图与结构化：在描述工作流和接口清单时，大量使用层级列表和数据流向说明，确保轮机长在后续重写《详细设计文档》时，可以直接把这里的流转图抄过去转化为 UML 时序图。

4. 全新调用场景与流转工作流

引入 OpenClaw 最直观的业务价值，是系统交互方式的根本性升级。过去，我们的医美系统是一个“被动工具”，销售必须登录后台、找到客户、点击按钮才能触发分析。现在，借由 OpenClaw 强大的原生通道（Channels）能力和路由分发，我们将同时支持系统内嵌式与IM 伴随式两大核心调用场景。

4.1 场景一：系统内嵌式触发 (System API)

这是对现有业务流程的平滑替换。业务人员依然在 CRM 系统操作，但背后的控制流已经完全交由 OpenClaw 接管。

业务表现：咨询师在 CRM 后台的“张三档案页”，点击“生成面诊复盘报告”。
数据流向契约：
1. [触发] 医美前端 -> 发送 HTTP 请求至医美 Java 后台。
2. [唤醒] 医美 Java 后台 -> 构造包含 customer_id 的系统级指令，调用 OpenClaw Gateway 的 API（类似于“帮我处理张三的复盘”）。
3. [分发] OpenClaw 主控 Agent 接收指令 -> 识别意图为“面诊复盘” -> 调起 Dify 中的 Agent A2 (复盘质检)。
4. [索要数据] OpenClaw 发现缺少文本 -> 触发 MCP 工具，向医美 Java 后台请求 获取张三录音转写文本 接口 -> Java 后台返回文本。
5. [推理] OpenClaw 将文本传给 Dify Agent A2 进行深度思考与抽取 -> Dify 返回结构化 JSON 报告。
6. [落盘与展示] OpenClaw 再次触发 MCP 工具，调用 Java 后台的 保存分析结果 接口 -> Java 后台存入数据库，并通知前端刷新页面展示。
开发减负点：Java 后台不再需要等待和维护与 Dify 的长连接，也不需要处理重试逻辑，只需“发出指令”和“提供查询/保存接口”。

4.2 场景二：IM 伴随式触发 (基于 OpenClaw 的巨大增量)

这是我们迈向“全天候数字员工”的关键一步。OpenClaw 原生内置了企微、飞书、钉钉等 IM 接入网关，它自带了多轮对话记忆（Session）和用户鉴权绑定。

业务表现：销售员在下班路上，直接在企业微信/飞书里 @销售智能体：“帮我分析一下张三刚才发给我的微信聊天记录，看看他在顾虑什么。”
数据流向契约：
1. [接收消息] IM (飞书/企微) Webhook -> OpenClaw Gateway 直接接收自然语言消息。
2. [意图识别] OpenClaw 主控 Agent 理解自然语言 -> 识别出客户是“张三”，动作是“聊天记录清洗与画像”。
3. [动态调度] OpenClaw 自动请求医美系统 MCP (获取张三聊天记录) -> 串行调用 Dify Agent A1 (清洗) 和 Agent B (画像)。
4. [流式返回] OpenClaw 将最终生成的《3C客户心理全景图》和催单建议，直接以富文本/Markdown 的形式推送回飞书/企微的聊天窗口。
开发减负点：轮机长们一行对接企微/飞书的代码都不用写。不用处理恶心的 Token 刷新、不用写正则匹配用户发了什么指令、不用维护并发 Session，所有通信脏活全部由 OpenClaw 底层网关包办。

5. 接口契约：医美系统如何通过 MCP 与 OpenClaw 对话？

前面多次提到 MCP (Model Context Protocol)。不要被这个高大上的词汇吓到。 💡 给 Java 开发的降维解释：对于你们来说，开发一个 MCP 工具，仅仅意味着写一个符合标准出入参规范的 Spring Boot Controller (RESTful API)。唯一的区别是，这个接口不是给前端 Vue/React 调用的，而是给 OpenClaw 的大模型调用的。大模型会自己阅读这个接口的 description，并在需要时自动把参数填好发给你们。

为了支撑上述场景，医美 Java 后台需要向 OpenClaw 提供以下两类标准化接口契约：

5.1 Inbound 接口（医美系统唤醒 OpenClaw）

当业务系统需要主动发起任务时（如场景一），通过 HTTP REST API 唤醒 OpenClaw。

接口类型：POST /v1/chat/completions (遵循类 OpenAI 接口标准，由 OpenClaw 提供)

核心载荷 (Payload)：

{
  "model": "openclaw:wantsong-sales", 
  "messages":[
    {
      "role": "system", 
      "content": "你现在的上下文客户是 ID: CUST_8899。请执行【面诊复盘】工作流。"
    }
  ]
}

5.2 Outbound 接口（OpenClaw 调用的 MCP 服务列表）

这是轮机长接下来开发的核心工作量所在。请基于这套契约，在现有的医美系统中暴露出相应的 API（建议统一加上 /api/mcp/v1/ 前缀及独立的 Token 鉴权）：

① 数据供给类 MCP (提供原材料)

get_customer_chat_logs:
- 入参：customer_id
- 出参：该客户最近的原始微信聊天文本内容（由现有 Java 逻辑从库中提取）。
get_customer_transcripts:
- 入参：customer_id
- 出参：该客户的面诊录音转写全量文本（复用现有的 ASR 解析入库结果）。

② 知识下发类 MCP (实现三层架构的解耦)

query_industry_knowledge:
- 入参：industry_code (如 "medical_beauty"), topic (如 "price_objection")
- 出参：该行业的通用 SOP 或反击话术。
query_enterprise_profile:
- 入参：enterprise_id
- 出参：该企业的简介、主打项目及脱敏的成功案例库（动态下发，杜绝大模型幻觉）。

③ 结果落盘类 MCP (接收劳动成果)

save_agent_analysis_result:
- 入参：customer_id, agent_type (如 A1/A2/B/C), result_json (Dify 产出的结构化数据)
- 执行逻辑：Java 后台拿到 JSON 后，将其解析并落盘到 CRM 数据库的对应字段中，触发后续的业务流（如生成待办任务）。

开发铁律：在提供以上 MCP 接口时，必须对入参做严格校验，且严格限制查询范围。绝不允许提供类似 execute_sql 这种危险的泛型接口，必须将 OpenClaw 视为一个“具有极高执行力但可能随时发癫的外部实习生”来进行权限管控。

6. 环境管理与配置迁移指南 (挑战点攻克)

Agentic 系统的运维与传统 Java Web 系统有着本质的区别。OpenClaw 的运行不仅依赖代码，更高度依赖其所在的工作区（Workspace）状态、技能挂载（Skills）和动态路由配置。为了防止出现“在我的环境里明明能跑”的经典灾难，我们必须建立极其严格的环境隔离与配置迁移纪律。

6.1 试验环境 vs 生产环境的物理界定

试验环境 (Sandbox / Test Environment)
- 定位：这是我们的“炼丹炉”和“排雷场”。
- 配置：部署在开发测试机的 OpenClaw Gateway。它连接的是 Dify 的测试环境 API，以及医美系统 Java 后台的测试环境 MCP 接口（甚至可以是 Mock 数据）。
- 核心任务：用于调试主控 Agent 的意图识别是否精准、Dify 的 Prompt 是否会产生幻觉、以及飞书/企微通道的连通性测试。
生产环境 (Production Environment)
- 定位：高稳定性的“中枢神经”。
- 配置：部署在前文提到的完全独立的 Linux 物理/虚拟主机上。连接真实的医美服务器和生产库（仅限 MCP 协议）。
- 安全红线：生产环境的 OpenClaw 严禁开启任何未经白名单授权的 Terminal（终端）或 FileSystem（文件系统）执行权限。

6.2 配置管理与“代码化”备份机制 (Configuration as Code)

在使用 OpenClaw 时，最容易犯的错误就是“在服务器的 Web UI 上随手改了一个配置，但没有记录下来”，导致系统崩溃时无法回滚。我们必须遵守以下配置迁移 SOP（标准作业程序）：

工作区 Git 化： OpenClaw 的所有核心配置（包括 agents.json、主控调度提示词、挂载的 Dify API Skill 脚本、通道绑定配置等），默认存放在本地工作区目录中（如 ~/.openclaw/workspace/）。要求：该目录下的所有非敏感配置文档，必须建立一个专属的 Git 仓库（如 ai-agent-configs）进行版本控制。
禁止生产环境直改（No Hot-Fixing on Prod）：任何针对主控 Agent 调度逻辑的修改、MCP 接口地址的更换，必须先在 Git 仓库修改，提交 PR 并由架构师 Review 后，通过 CI/CD 流水线拉取到生产服务器的 OpenClaw 工作区，然后执行 openclaw gateway reload 热重载。
敏感凭证分离： Dify 的 API Key、医美系统的 MCP 鉴权 Token、企业微信的 Secret，严禁硬编码在 Git 仓库中。必须统一使用生产服务器的环境变量（.env 文件）进行注入。

7. 下一步行动要求 (Next Steps)

各位轮机长，至此，新架构的蓝图已经铺开。我们通过 Dify 抽离了极其复杂的 AI 认知逻辑，通过 OpenClaw 获得了一个不知疲倦、能听懂人话、能自动调接口的中央调度器。

过去的痛点正在被彻底剥离，通往“一处开发，多租户多行业复用”的 SaaS 大门已经打开。但现在还不是写代码的时候。

7.1 当前交付物要求：重构《详细设计文档》

请各位轮机长以本《部署方案》为骨架，结合我们最初始的《旧版销售洞察智能体核心设计文档》（保留里面关于 A1/A2/B/C 的业务定义），在 [待定] 个工作日内，向我输出一份全新的 《V2.0 智能中枢系统详细设计文档》。

这份详细设计文档必须包含但不限于以下内容：

全局 UML 时序图：画出从前端/IM 触发 -> Java 后台 -> OpenClaw -> Dify -> OpenClaw -> Java 后台落盘的完整交互时序。
MCP 接口契约明细：详细定义第 5 章中提到的所有 Inbound 和 Outbound API 的 JSON 结构、字段类型、非空约束及错误码（Error Codes）。
数据库 Schema 变更预案：为了适配多行业/多租户（三层架构），现有的 CRM 数据库需要做哪些表结构改造（如增加 industry_code 字典表、独立的话术库存储表等）。

7.2 后续节奏控制

在《V2.0 详细设计文档》进行严格的架构评审（Review）并全员达成共识通过之前，任何人不得提前启动 Java 业务代码或 OpenClaw 脚本的开发。

一旦评审通过，我们将制定具体的开发、联调与灰度上线里程碑。我们第一阶段的战役，将从“跑通一个最简单的 MCP 连通性测试”开始。

23 KiB Raw Permalink Blame History Unescape Escape

📄 《智能体中枢架构迁移与部署方案》

0. 文档定位与阅读指南

0.1 面向对象

0.2 核心动作与交付契约

0.3 核心思想转变（Mindset Shift）

1. 架构升级背景：为什么我们要引入这套新底座？

1.1 痛点直击：我们当下的工程泥潭

1.2 破局之道：Dify + OpenClaw 的双擎驱动

为什么引入 Dify（打造专家大脑中台）？

为什么引入 OpenClaw（打造自动化编排引擎）？

内部思考与质量把控 (Internal Thought Process)

2. 核心架构跃迁：从“一次性项目”到“高复用 SaaS 后台”

2.1 第一层：通用销售心智底座 (The Core)

2.2 第二层：行业知识层 (Industry Domain)

2.3 第三层：企业定制层 (Enterprise Specifics)

3. 物理部署拓扑与安全隔离设计

3.1 三端隔离的网络与机器规划

3.2 交互契约与安全隔离策略

内部思考与质量把控 (Internal Thought Process)

4. 全新调用场景与流转工作流

4.1 场景一：系统内嵌式触发 (System API)

4.2 场景二：IM 伴随式触发 (基于 OpenClaw 的巨大增量)

5. 接口契约：医美系统如何通过 MCP 与 OpenClaw 对话？

5.1 Inbound 接口（医美系统唤醒 OpenClaw）

5.2 Outbound 接口（OpenClaw 调用的 MCP 服务列表）

① 数据供给类 MCP (提供原材料)

② 知识下发类 MCP (实现三层架构的解耦)

③ 结果落盘类 MCP (接收劳动成果)

6. 环境管理与配置迁移指南 (挑战点攻克)

6.1 试验环境 vs 生产环境的物理界定

6.2 配置管理与“代码化”备份机制 (Configuration as Code)

7. 下一步行动要求 (Next Steps)

7.1 当前交付物要求：重构《详细设计文档》

7.2 后续节奏控制

23 KiB

Raw Permalink Blame History