1. 项目概述：当销售团队不再需要“人肉搜索”

想象一下这个场景：一个销售新人刚入职，面对公司过去几年积累的几百份产品手册、客户案例、报价单和内部培训资料，急需找到一个特定行业客户的解决方案案例。他可能需要在十几个文件夹、甚至不同的在线文档平台里来回切换，用关键词搜索，然后从一堆结果中手动筛选、比对，花上半小时甚至更久。这不仅仅是效率问题，更关键的是，信息的准确性和一致性难以保证——他找到的可能是过时的版本，或者忽略了某份关键的技术白皮书。

这就是“手动翻资料”时代的典型痛点。信息散落在各处，形成一个个数据孤岛，而销售人员的核心能力本应是洞察客户需求和提供专业方案，却不得不耗费大量精力在基础的“信息检索”上。我们这次要聊的项目，就是利用“Agent Plan”这套技术架构，构建一个智能的销售档案管理与问答系统，让机器代替人去“翻资料”，让销售回归销售本身。

简单来说，这个项目的核心目标是：将散乱的非结构化销售文档（如PDF、Word、网页、聊天记录）转化为一个集中、可查询、可对话的知识库。销售或客服人员可以通过自然语言提问，比如“去年我们在金融行业中标的最大项目预算是多少？”或“针对制造业客户，我们的A产品对比B产品的核心优势是什么？”，系统能快速、准确地从海量文档中提取信息，并组织成清晰的答案。这背后依赖的正是当前热门的AI智能体（Agent）技术、大语言模型（LLM）以及一系列高效的工具链。

从网络热词可以看出，大家关注的焦点集中在几个核心组件上：Codex（这里可能指代基于大模型的代码/文本处理工具或特定平台）、飞书（作为常见的企业协作与知识入口）、Supabase（开源的后端即服务，用于数据存储和管理）、以及OpenViking（可能是一个开源的多智能体框架或工具）。这些技术栈的组合，为我们构建这样一个系统提供了清晰的路径。

2. 核心需求与架构设计解析

2.1 销售知识管理的核心痛点

在动手之前，我们必须先厘清销售团队对知识管理的真实需求，这决定了我们架构设计的重心。

1. 信息碎片化与检索低效：资料可能存放在本地硬盘、NAS、公司网盘、飞书文档、Confluence、甚至是微信聊天记录和邮件里。没有统一的检索入口，关键词搜索经常返回大量无关结果。
2. 知识更新与同步滞后：产品迭代了，但发给客户的旧版PPT还没更新；价格策略调整了，但销售手里的报价单还是老的。确保一线人员总能拿到最新、最准确的信息，是个巨大的挑战。
3. 新人上手成本高：销售经验往往存在于老员工的脑子里，形成“隐性知识”。新人培养周期长，问多了怕打扰同事，不问又可能出错。
4. 问答的上下文与精准度：简单的全文搜索无法理解问题的意图。例如，“这个产品贵不贵？” 需要系统结合客户的行业、规模以及我们的定价策略来回答，而不是简单地返回所有包含“价格”的文档片段。

因此，我们需要的不是一个简单的文档管理系统，而是一个具备“理解-推理-回答”能力的智能知识中枢。

2.2 技术架构选型：为什么是Agent Plan？

“Agent Plan”在这里不是一个具体的软件，而是一种解决问题的架构思路，即利用多个具备特定能力的智能体（Agent）协同工作，完成复杂任务。对于销售知识问答这个场景，单一大模型往往力有不逮，原因在于：

• 处理长文本和大量文档有压力：直接将所有文档扔给LLM，会很快耗尽上下文窗口，且成本高昂。
• 缺乏实时、准确的数据源：LLM的内部知识可能过时，无法获取公司内部最新的销售数据。
• 需要执行具体操作：比如，根据问答结果，自动生成一个客户简报摘要，并发送到飞书群。

因此，一个典型的Agent Plan架构会包含以下角色分工：

1. “调度员”Agent（Orchestrator）：接收用户的自然语言问题，进行分析和意图识别，决定需要调用哪些下游工具或Agent来解决问题。它负责整个任务的规划和流程控制。
2. “档案员”Agent（Retrieval Specialist）：专门负责从知识库中查找相关信息。这背后是检索增强生成（RAG）技术。它先将所有销售文档进行切片、向量化处理，存入向量数据库。当接到查询时，它先将问题转化为向量，在向量数据库中快速找到最相关的文本片段（而不仅仅是关键词匹配），将这些片段作为“参考依据”提供给生成器。
3. “分析员”Agent（Generator）：通常由大语言模型（如GPT、DeepSeek等）担任。它接收“调度员”的指令和“档案员”提供的参考资料，综合这些信息，生成通顺、准确、符合业务语境的答案。它负责知识的“创造式”整合。
4. “执行员”Agent（Tool User）：具备调用外部工具的能力。例如，当用户问“把刚才提到的解决方案要点总结一下发到我的飞书文档”，这个Agent可以调用飞书的API，真的去创建一个文档并写入内容。

网络热词中提到的OpenViking，很可能就是这样一个用于编排多智能体的开源框架。而Codex，在AI编程辅助的语境之外，也可能指某些集成了LLM和工具调用能力的平台或中间件，用于快速构建此类智能体应用。

2.3 工具链选型背后的逻辑

结合热搜词，我们的技术栈逐渐清晰：

• 前端/交互层：飞书。这是非常自然的选择。飞书是国内众多企业的协作中心，员工每天都在使用。将问答机器人以“飞书机器人”的形式嵌入群聊或作为单独应用，用户无需切换平台，体验无缝。这也是为什么热词中频繁出现“飞书机器人codex”、“飞书对接”的原因。
• 数据存储与处理层：Supabase。我们需要存储两种数据：
  • 结构化数据：用户信息、对话记录、文档元数据（如文件名、更新时间、所属项目等）。Supabase提供的PostgreSQL数据库完全胜任，且其开箱即用的身份认证、实时订阅功能非常方便。
  • 非结构化数据（向量）：文档切片后生成的向量。Supabase也提供了pgvector扩展支持，可以让我们在同一套数据库体系内管理结构化数据和向量数据，简化架构。热词“supabase怎么结合自己项目”正反映了开发者对其集成方式的关注。
• 智能体与模型层：Codex/OpenViking + 大模型。这里“Codex”可能是一个封装了智能体逻辑的应用或SDK。我们需要一个强大的LLM作为“分析员”的大脑。可以选择云服务商提供的API（如OpenAI GPT-4、DeepSeek-V3等），也可以部署开源模型（如Qwen、Llama等）。OpenViking则负责将这些组件（检索器、LLM、工具）连接和编排起来。
• 文档处理与检索层：需要一套流程来处理原始文档。包括：
  • 文档加载：支持飞书云文档、本地PDF/Word、网页等。
  • 文本分割：将长文档切成语义连贯的小块（如每块500字）。
  • 向量化：使用嵌入模型（Embedding Model，如text-embedding-3-small）将文本块转化为向量。
  • 向量数据库：即Supabase的pgvector。

注意：热词中出现的“app secret复制不上去”、“cc switch local proxy failed”等错误，很可能是在配置飞书机器人或Codex平台时遇到的典型网络或配置问题，这提醒我们在部署时要仔细检查回调地址、网络代理设置和密钥信息。

3. 系统搭建核心步骤详解

3.1 第一步：构建销售知识库——从杂乱文档到向量数据

这是整个系统的基石，也是最耗时但必须精细操作的一步。质量直接决定最终问答的准确性。

1. 文档收集与预处理

• 来源：确定范围。是仅限飞书知识库？还是包括邮箱附件、公司服务器上的项目文件夹？建议初期以一个核心飞书知识空间为起点。
• 工具：对于飞书，可以使用官方API或第三方工具（如Obsidian插件，对应热词“obsidian如何将飞书文档导入”）将文档批量导出为Markdown或文本格式。对于本地文件，可以使用PyPDF2、python-docx、BeautifulSoup等库进行解析。
• 清洗：去除文档中的页眉页脚、无关图片的标记、特殊字符等。统一格式，确保核心文本内容纯净。

2. 文本分割（Chunking）这是RAG的关键技巧。分割得太碎，会丢失上下文；分割得太大，检索会不精准，且给LLM的负担重。

• 策略：推荐使用“递归式字符分割”结合“语义分割”。先用固定大小（如512个字符）分割，再确保分割点落在句子末尾或自然段落处。更高级的做法是使用专门模型进行语义边界识别。
• 实操：可以使用langchain库的RecursiveCharacterTextSplitter，并设置chunk_size=500，chunk_overlap=50。这个50字符的重叠很重要，能防止一个完整的句子被腰斩，保证上下文的连贯性。

3. 向量化与存储

• 嵌入模型选择：如果使用OpenAI，text-embedding-3-small是性价比很高的选择。如果希望数据完全私有化，可以部署开源的嵌入模型，如BGE-M3或text2vec系列。
• 流程：将每一个文本块通过嵌入模型转换为一个高维向量（例如1536维）。同时，需要记录该文本块的元数据：来源文档、页码、分割ID等。
• 存入Supabase：
  1. 在Supabase中启用pgvector扩展。
  2. 创建一张表，例如document_chunks，包含字段：id、content（文本内容）、embedding（向量，使用vector(1536)类型）、metadata（JSON类型，存储文档名、来源等）。
  3. 编写一个脚本，循环处理所有分割后的文本块，生成向量后插入数据库。

心得：在向量化之前，可以考虑对文本块进行轻微的“增强”，比如在内容前加上“文档标题：XXX， 章节：XXX”。这样生成的向量会携带一些结构信息，有助于提升检索相关性。例如，一个关于“服务器报价”的文本块，可以增强为“[产品手册-服务器篇] 关于服务器报价：...”。

3.2 第二步：搭建智能体后端——让机器理解与协作

这部分是系统的“大脑”，我们以OpenViking这类框架的思路来构建。

1. 环境搭建与模型接入

• 框架选择：假设我们使用一个类似OpenViking的Python智能体框架。你需要安装相关依赖，并配置好模型API。
• 模型配置：在框架的配置文件中，设置你的LLM（如DeepSeek）的API Base URL和Key。热词中“codex接入deepseek”就指向这个环节。

  # 示例配置片段 llm_config = { "model": "deepseek-chat", "api_key": os.getenv("DEEPSEEK_API_KEY"), "base_url": "https://api.deepseek.com" }

• 解决网络问题：热词中“cc switch local proxy failed”提示了网络代理问题。如果你的服务器或开发环境需要代理，务必在代码中或系统环境变量里正确配置，否则所有对外部API的调用都会失败。

2. 定义核心智能体

• 检索智能体：这个Agent的唯一职责就是“找资料”。它接收用户问题，调用嵌入模型将问题向量化，然后在Supabase的document_chunks表中执行向量相似度搜索（使用<->余弦距离运算符）。

  -- 在Supabase中执行向量检索的SQL示例 SELECT content, metadata, 1 - (embedding <=> query_vector) as similarity FROM document_chunks ORDER BY embedding <=> query_vector LIMIT 5; -- 返回最相关的5个片段

• 生成智能体：这个Agent接收“用户问题”和“检索到的资料”。它的系统提示词（System Prompt）至关重要，需要被精心设计：

  “你是一个专业的销售知识助手。请严格根据提供的参考资料来回答问题。如果资料中没有相关信息，请直接说‘根据现有资料，我无法回答这个问题’，不要编造答案。答案要简洁、专业，并注明关键信息的来源文档。”

3. 编排工作流

• 调度逻辑：主接收器（可能是FastAPI写的Web服务）收到飞书机器人转发的用户消息后，启动工作流。
  1. 调用检索智能体，获取相关文档片段。
  2. 判断检索结果的相关性（例如，最高相似度是否低于某个阈值）。如果相关性太低，直接回复“未找到相关信息”。
  3. 将问题和相关片段组装成Prompt，调用生成智能体（LLM）产生最终答案。
  4. 将答案返回给飞书机器人接口。

3.3 第三步：集成飞书——打造无缝业务入口

这是用户直接接触的部分，体验必须流畅。

1. 创建飞书机器人

• 在飞书开放平台创建一个企业自建应用，添加“机器人”能力。
• 获取关键凭证：App ID、App Secret。这里就会遇到热词中的“app secret复制不上去”问题，通常是因为浏览器插件干扰或文本框格式问题，尝试在无痕模式下操作或直接手动输入。
• 配置权限：为机器人申请“获取用户发给机器人的单聊消息”、“获取用户在群聊中@机器人的消息”、“以应用身份发消息”等权限。
• 配置事件订阅：这是核心。设置请求网址（你的后端服务API地址），用于接收飞书推送的消息事件。验证URL时，需要你的服务端正确响应飞书的挑战码。“飞书 {"errmsg":"requestaccess:fail invalid redirect uri in h5 case”这类错误，通常与配置的重定向URI不正确或应用发布状态有关，需仔细检查开放平台设置。

2. 实现消息处理与响应

• 你的后端需要提供一个API端点（如/feishu/webhook）来接收飞书的POST请求。
• 验证请求签名，确保安全性。
• 解析事件内容，提取出用户的open_id、text（消息内容）和chat_id（会话ID）。
• 将用户消息text送入你的智能体工作流。
• 获取智能体生成的答案后，调用飞书的“回复消息”API，将答案发送回原会话。

3. 高级功能：消息卡片与交互

• 纯文本有时不够直观。飞书支持丰富的消息卡片格式。你可以让智能体生成的答案不仅仅是文字，还可以是结构化的卡片，例如：
  • 将产品对比做成表格。
  • 将解决方案要点做成带图文的列表。
  • 在答案末尾提供按钮，如“查看源文档”、“生成客户简报”。
• 这需要你的生成智能体不仅输出文本，还能输出结构化的数据，然后由后端根据模板渲染成飞书卡片。

4. 核心环节：检索增强生成（RAG）的优化实战

RAG听起来简单，但想做好，让答案精准可靠，需要大量调优。以下是几个关键优化点。

4.1 检索质量优化：找到真正相关的“证据”

检索是第一步，如果找错了资料，LLM再强也无力回天。

• 多路检索（Hybrid Search）：不要只依赖向量相似度。结合关键词搜索（BM25）。因为有些专业术语、产品型号（如“X-1000型服务器”），向量搜索可能模糊，但关键词搜索非常精准。可以在Supabase中同时进行向量检索和全文检索，然后对结果进行加权融合（Rerank）。
• 元数据过滤：在检索时加入业务过滤条件。例如，当销售问“金融行业的案例”，除了语义匹配，我们可以在SQL查询中加上WHERE metadata->>'industry' = '金融'。这就要求我们在向量化存储时，把文档的行业、产品线、年份等元信息提取好并存入metadata字段。
• 查询重写（Query Rewriting）：用户的问题可能很口语化。例如，“这东西咋卖？”可以重写为“产品的价格策略和报价方式”。可以在检索前，先用一个小型的LLM（或规则）对用户查询进行优化和扩展，提升检索命中率。

4.2 提示词工程：让LLM成为可靠的“分析师”

给LLM的指令（Prompt）决定了答案的质量和风格。

• 严格的引用要求：在Prompt中强制要求LLM“引用”来源。例如：“请在你的回答中，为每一个关键事实注明其来源的文档编号或标题，格式如【来源：2024产品白皮书】”。这增加了答案的可信度和可追溯性。
• 分角色与场景：可以为不同场景设计不同的系统提示词。例如：
  • 快速查询模式：“请用一句话直接回答核心问题。”
  • 深度分析模式：“请从背景、解决方案、优势、客户见证四个方面进行结构化回答。”
  • 对比模式：“请以表格形式对比A和B产品的参数、适用场景和价格。”
• 处理“不知道”：必须明确指令LLM在缺乏资料时承认无知。这是避免“幻觉”（胡编乱造）的最重要防线。可以这样写：“如果提供的参考资料中完全没有相关信息，请直接回复：‘我暂时没有找到关于这个问题的确切资料，建议您咨询相关产品经理或查看最新的官方文档。’”

4.3 迭代与评估：建立反馈闭环

系统上线不是终点。需要建立评估机制。

• 设计测试集：收集销售团队实际会问的100个典型问题，并准备好标准答案或期望的答案方向。
• 自动化评估：可以定期用测试集跑一遍系统，从答案相关性、信息准确性、引用正确性、流畅度几个维度打分（初期可以人工评，后期可尝试用LLM作为裁判进行自动评估）。
• 收集用户反馈：在飞书机器人的回答下方，可以加入“有帮助”和“无帮助”的反馈按钮。收集这些隐式反馈，用于定位问题（是检索不准？还是生成不好？）。

5. 部署、监控与常见问题排查

5.1 系统部署策略

• 环境分离：开发、测试、生产环境严格分开。Supabase可以用不同项目，LLM API Key也使用不同账号。
• 服务化部署：将智能体后端、文档处理流水线分别部署为独立的微服务（如使用Docker容器），方便扩展和维护。可以使用docker-compose或Kubernetes进行编排。
• 配置管理：所有API密钥、数据库连接字符串等敏感信息，必须通过环境变量或密钥管理服务（如Vault）传递，绝不能硬编码在代码中。

5.2 核心监控指标

一个健康的系统需要被持续观察：

1. 接口健康度：飞书机器人回调接口、智能体API的可用性和响应时间（P99延迟）。
2. LLM API消耗：监控Token使用量和费用，设置每日预算告警。
3. 检索效果：记录每次问答的“检索结果Top-1相似度”分布，如果相似度普遍偏低，说明知识库构建或检索策略需要优化。
4. 用户反馈率：“无帮助”反馈的比率和具体问题，是宝贵的优化线索。

5.3 常见问题与排查清单

以下是开发运维中几乎一定会遇到的问题及解决思路：

关于热词中一些具体错误的解读：

• “app secret复制不上去”：大概率是前端输入框的兼容性问题，尝试手动键入或更换浏览器。
• “cc switch local proxy failed while handling codex endpoint ...”：这明确指向网络代理配置错误。检查运行Codex服务或调用Codex的环境变量（如HTTP_PROXY,HTTPS_PROXY）是否正确设置。
• “飞书 {"errmsg":"requestaccess:fail invalid redirect uri ...”：检查飞书开放平台应用“安全设置”中的“重定向URL”是否与代码中回调的URL完全一致，包括协议（http/https）、域名、端口和路径。

构建这样一个系统，最大的挑战往往不在技术本身，而在于对业务知识的梳理和持续运营。技术栈可以选Codex、OpenViking，也可以用LangChain、LlamaIndex等其他框架组合实现。核心在于理解Agent Plan的分工协作思想，并扎实地做好RAG的每一个环节——从文档处理、检索优化到提示词设计。当销售同事能瞬间得到他想要的准确信息时，这个项目的价值就真正体现出来了。