企业官网建设流程全解析

1. 项目概述：当“@AI”从功能按钮变成工作本能

“多端工作入口对接工作端升级，让AI成为随时可@的数字同事！”——这个标题乍看像一句市场宣传语，但拆开来看，它其实精准锚定了当前企业级AI落地最真实、最迫切的痛点：不是AI能力不够强，而是它总在“别处”。我在给十多家中大型企业做数字化工具链咨询时反复验证过一个现象：员工手机里装着最先进的人工智能助手App，电脑上开着大模型网页版，但真正要写周报、查合同条款、核对报销单时，他们还得手动复制粘贴、切换窗口、重新描述问题。AI没消失，它只是被隔离在“工作流之外”，成了一个需要主动“拜访”的访客，而不是嵌在流程里的“同事”。

这个项目的核心，就是把AI从“访客”变成“同事”。它不追求训练一个新大模型，也不堆砌炫酷界面，而是聚焦在入口层的无缝缝合——让员工在钉钉发消息时能直接@AI，在飞书文档里划选一段文字右键就能唤出分析，在企业微信会议纪要页面点击“生成待办”按钮背后调用的是同一套推理引擎，在内部OA系统审批流的某个节点自动触发合规性初筛。这里的“多端”，不是简单地把同一个网页套个壳发布到iOS/Android/Web，而是指业务系统级的深度集成：IM工具、协同文档、CRM、ERP、低代码平台、甚至邮件客户端。而“工作端升级”，本质是构建一套轻量、稳定、可灰度发布的AI能力调度中间件，它不替代原有系统，只负责“翻译”和“路由”：把用户在不同端发出的自然语言指令，准确识别意图、匹配对应能力、调用合适模型、注入上下文数据、返回结构化结果，并把结果以该端原生方式呈现。

关键词里没有出现具体技术栈，这恰恰说明它的价值不在底层模型，而在工程化落地的成熟度。我见过太多团队花半年时间调优一个7B模型的推理速度，却卡在“怎么让销售在CRM里点一下就生成客户跟进话术”这个环节上三个月。这个项目解决的，正是那个“点一下”的背后：权限怎么继承？历史对话如何跨端同步？敏感字段如何自动脱敏？模型响应超时了前端怎么优雅降级？这些细节，才是决定AI是“锦上添花”还是“如影随形”的分水岭。它适合两类人深度参考：一是正在规划AI办公助手的企业IT架构师，你需要知道哪些集成点必须前置设计；二是独立开发者或小团队技术负责人，你想快速验证一个AI功能在真实业务场景中的闭环体验，这套入口对接思路比从零造轮子高效十倍。

2. 整体设计与思路拆解：为什么选择“入口缝合”而非“大一统平台”

2.1 核心矛盾：业务系统割裂 vs AI能力原子化

先说一个血泪教训。去年帮一家制造业客户做AI质检报告助手，最初方案是开发一个独立Web应用，所有产线人员通过浏览器访问。上线后发现使用率极低——质检员在车间用工业平板，系统强制要求登录、输入工号、再点进AI模块，平均每次操作耗时47秒。而他们真正需要的，只是拍一张缺陷照片，然后问：“这个划痕算几级不良？” 问题不在AI不准，而在交互路径与工作惯性完全错位。后来我们砍掉整个独立应用，直接在他们已有的MES系统移动端里加了一个相机图标，拍照后自动唤起AI分析服务，结果使用率一周内飙升到83%。这个案例彻底改变了我的设计哲学：AI的价值密度，等于它离用户当前操作焦点的距离的倒数。

因此，“多端工作入口对接”的设计起点，就是承认并利用现有系统的存在。企业里不存在“空白画布”，只有钉钉、飞书、企业微信、自研OA、SAP、用友这些运行了十年以上的庞然大物。强行用一个新平台去覆盖，成本高、阻力大、周期长。而“入口缝合”策略，相当于给每个现有系统安装一个“AI神经末梢”：它不改变主干（核心业务逻辑），只在末端（用户交互层）增加感知和响应能力。这种设计有三个不可替代的优势：

第一，用户心智零迁移。员工不需要学习新软件、记住新网址、适应新界面。他们继续用习惯的钉钉发消息，继续在飞书文档里写方案，唯一新增的动作，就是多打一个“@”符号。行为改变成本趋近于零，这是任何全新平台都无法比拟的 adoption 优势。

第二，数据上下文天然保真。当AI在飞书文档里被@时，它能直接获取当前文档的标题、作者、修改时间、甚至光标所在段落的前后500字；当在CRM客户页触发AI时，它能实时读取该客户的全部历史订单、沟通记录、服务工单。这些上下文信息如果靠用户手动复制粘贴，90%会丢失关键背景，导致AI回答泛泛而谈。入口级集成让上下文传递成为自动、无感、高保真的过程。

第三，技术演进解耦灵活。中间件层（我们叫它“AI Router”）与前端入口、后端模型服务完全解耦。今天用Qwen2-7B做基础问答，明天可以无缝切换成DeepSeek-VL处理图片，后天接入私有化部署的千问大模型。只要Router的API契约不变，前端入口无需任何修改，后端模型团队也能独立迭代。这种松耦合架构，让AI能力升级不再是一次全公司停摆的“大版本更新”，而变成后台静默发生的“能力热替换”。

2.2 架构选型：为什么是轻量中间件+标准化协议，而非重客户端或中心化网关

面对“多端接入”，常见方案有三种：A）为每个端开发专属SDK（重客户端）；B）建一个统一AI网关，所有请求都走它（中心化网关）；C）轻量中间件+开放协议（本项目采用）。我们最终放弃A和B，原因很实际：

• 重客户端（A）的陷阱：初期看似可控，但每新增一个端（比如客户突然要求接入Teams或Slack），就要重写、测试、发布一套新SDK。更致命的是，SDK更新依赖各端应用商店审核周期，一个紧急bug修复可能卡住两周。我们曾在一个金融客户项目里吃过亏：iOS SDK修复了一个OCR识别精度问题，但App Store审核拖了11天，期间客户投诉激增。轻量中间件则完全不同——它运行在企业自有服务器或云环境，修复后5分钟内全端生效。

• 中心化网关（B）的瓶颈：听起来很美，所有流量归一管理。但现实是，企业内网策略极其复杂。有些部门禁止外部域名解析，有些系统只允许白名单IP通信，还有些老旧ERP系统连HTTPS都不支持。硬推一个中心网关，90%的对接工作量会消耗在“如何让各个系统连上它”上，而非AI本身。而轻量中间件采用“就近部署”原则：钉钉入口的Router实例部署在钉钉服务商集群侧，飞书入口的Router部署在飞书开放平台侧，内部OA的Router就跑在客户自己的IDC机房。它不追求物理集中，而追求逻辑统一。

所以我们的核心组件是三层结构：

1. 前端适配器（Adapter）：每个端一个极简JS/SDK，职责唯一：捕获用户触发事件（如@、右键菜单、按钮点击）、收集当前上下文（URL、DOM元素、系统变量）、将请求标准化为Router可识别的JSON格式；
2. AI Router中间件：核心调度引擎，负责鉴权、意图路由（判断该请求该发给哪个模型服务）、上下文注入（拼接知识库、历史对话）、结果格式化（把模型原始JSON转成钉钉卡片或飞书富文本）；
3. 后端能力池（Capability Pool）：一组松耦合的微服务，每个服务封装一种原子能力，如/summarize（文档摘要）、/extract-entities（合同关键信息抽取）、/draft-email（邮件草稿生成）。它们只关心自己那块逻辑，不感知前端来源。

这个架构的精妙之处在于，Adapter和Capability Pool可以无限水平扩展，而Router是唯一需要精心设计的“大脑”。我们用Go语言实现Router，单实例轻松支撑5000QPS，横向扩容时通过Redis共享会话状态。这种设计，让项目从第一天起就具备了应对未来三年业务增长的技术弹性。

2.3 安全与合规：不是“加个开关”，而是“织一张网”

把AI塞进工作流，安全不是附加题，而是必答题。很多团队只想到“模型会不会胡说八道”，却忽略了更致命的三类风险：数据泄露、越权访问、审计断链。本项目的安全设计不是事后补丁，而是从协议层就嵌入。

首先，数据不出域。Router收到请求后，第一步不是转发给模型，而是启动“数据净化流水线”：自动识别并脱敏手机号、身份证号、银行卡号、客户名称等敏感字段。脱敏不是简单星号替换，而是基于正则+NER模型的双重校验。例如，识别到“张三，138****1234，北京朝阳区XX大厦”时，会精准脱敏手机号，但保留“北京朝阳区”这个非敏感地理信息，确保后续分析仍有空间维度。所有脱敏规则可配置、可审计、可回滚。

其次，权限继承。用户在钉钉里@AI，Router会自动向钉钉OpenAPI发起get_user_info请求，获取该用户的组织架构、部门、角色标签；在CRM里触发，则调用CRM的get_current_user_permissions接口。AI返回的结果，严格遵循该用户在原系统的数据权限。比如，销售助理只能看到自己名下客户的合同，他@AI分析“所有客户回款情况”，AI会自动在查询语句里加上WHERE owner_id = 'sales_assistant_id'，绝不会越界。

最后，全链路审计。Router内置审计日志模块，每条请求记录包含：触发时间、来源端标识、用户ID、原始请求摘要（脱敏后）、路由决策日志（发给了哪个Capability）、模型响应摘要、最终返回给用户的内容快照。日志直连企业SIEM系统，满足等保三级对AI应用的审计要求。我们甚至预留了“审计沙箱”模式：管理员可设置某部门所有AI交互进入只读审计通道，不执行实际操作，纯用于观察和培训。

提示：很多团队在POC阶段忽略审计日志，结果正式上线后被法务部叫停。务必在Router设计之初就定义好日志Schema，否则后期补录成本极高。

3. 核心细节解析与实操要点：从“能用”到“好用”的关键跃迁

3.1 入口适配器（Adapter）的极简实现哲学

Adapter的目标是“最小侵入”。它不该是一个功能完备的SDK，而应该像一个“智能挂钩”，只做三件事：监听、打包、发送。以钉钉适配器为例，其核心代码不足200行：

// 钉钉Adapter核心逻辑（简化版） dd.ready(function() { // 1. 监听@AI消息事件（钉钉开放平台提供） dd.on('atMessage', function(data) { if (data.text.includes('@AI')) { // 2. 打包上下文：获取当前会话ID、用户ID、消息内容、群组ID const context = { source: 'dingtalk', chat_id: data.chatId, user_id: data.senderId, message: data.text, timestamp: Date.now() }; // 3. 发送至Router（注意：走企业内网，非公网） fetch('https://router.internal.company.com/v1/invoke', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(context) }); } }); });

这个设计的关键在于所有复杂逻辑都推给Router。Adapter不解析用户意图，不调用模型，不处理返回结果。它甚至不存储任何状态——每次触发都是无状态的HTTP请求。这种“傻瓜式”设计带来巨大好处：

• 维护成本趋近于零：钉钉API升级时，只需更新几行dd.on()监听代码，Router侧完全不受影响；
• 故障隔离清晰：如果AI响应慢，问题一定在Router或后端模型，绝不会是Adapter卡住；
• 多端复用度高：飞书Adapter只需把dd.on()换成lark.on()，把chatId换成chat_id，其余逻辑几乎一致。

我们为六个主流端（钉钉、飞书、企微、Web OA、移动OA、邮件客户端）编写了Adapter，平均每个不到300行代码，全部开源在内部GitLab。新端接入，资深前端工程师半天即可完成。

3.2 Router的意图路由引擎：让AI听懂“人话”背后的业务逻辑

Router的“智能”不在于它多懂AI，而在于它多懂业务。用户说“帮我看看王经理上周的报销有没有问题”，Router必须能拆解出：

• 实体：“王经理” → 映射到CRM/HR系统中的员工ID；
• 时间：“上周” → 转换为2024-05-20T00:00:00到2024-05-26T23:59:59；
• 业务动作：“报销有没有问题” → 匹配到/audit-expense这个Capability；
• 权限校验：确认当前用户是否有权查看王经理的报销单。

这个过程靠传统NLU模型效果很差——业务术语太专、表达太随意。我们的方案是规则引擎+轻量微调模型双轨制：

• 规则引擎（覆盖80%高频场景）：用正则+词典+语法树构建。例如，报销类意图，预置规则：(报销|费用|差旅|发票) + (审核|检查|有没有|是否|问题)→ 触发/audit-expense。词典包含公司所有部门、常用项目编号、报销类型代码（如TRAVEL_2024_Q2）。规则可热更新，运营同学在后台页面点几下就能新增一条。

• 微调模型（处理长尾模糊表达）：用LoRA微调一个1.5B参数的中文小模型（如Phi-3-mini），仅训练意图分类头。训练数据来自历史客服工单、内部论坛提问、用户访谈录音转文字。模型不生成答案，只输出概率最高的3个Capability ID。Router最终决策是规则匹配结果与模型预测结果的加权融合。

注意：模型只做“选择题”，不做“解答题”。这极大降低了计算开销和幻觉风险。Router的CPU占用常年低于15%，而同等规模的端到端大模型推理服务需8核CPU满载。

3.3 上下文注入：让AI的回答“有根有据”

没有上下文的AI，就像没有地图的司机。Router的上下文注入模块，是区分“玩具”和“生产力工具”的关键。它不是简单地把文档全文塞给模型，而是进行结构化、分层、带权重的上下文组装：

1. 强上下文（Must-Have）：当前操作对象的元数据。例如，在CRM客户页触发AI，强上下文包括：{customer_id: "CUST-2024-0876", name: "北京智算科技有限公司", industry: "人工智能", last_contact_date: "2024-05-22"}。这部分数据由Adapter在请求中携带，Router直接透传给Capability。

2. 弱上下文（Nice-to-Have）：用户近期相关行为。Router会查询Redis缓存，获取该用户过去24小时内的5次同类操作（如其他客户页访问、相关合同下载记录），提取关键词加入上下文。这能让AI回答更具连续性：“上次您看了‘上海云图’的合同，这次‘北京智算’的合同条款差异在哪？”

3. 知识上下文（Knowledge-Augmented）：动态注入企业知识库片段。Router调用向量数据库API，以当前请求为Query，检索Top3最相关的知识条目（如《2024版销售合同模板》《GDPR数据处理附录》），经RAG重排后，截取最相关段落注入。关键技巧是：对知识片段做“可信度打分”，分数低于阈值的条目自动丢弃，避免错误知识污染模型。

实测表明，加入分层上下文后，AI在合同审查类任务的准确率从62%提升至89%，且错误回答中95%是“无法判断”，而非“胡编乱造”。这才是企业敢把AI用在关键流程里的底气。

3.4 结果格式化：让AI的输出“长成它该有的样子”

Router的最后一公里，是把模型冷冰冰的JSON输出，变成用户眼前活生生的交互。这步看似简单，实则暗藏玄机。我们绝不允许“把模型response.text直接塞进钉钉卡片”这种粗暴做法。

• 钉钉卡片：需转换为符合 钉钉开放平台卡片Schema 的JSON。Router内置模板引擎，针对不同Capability预置卡片模板。例如/summarize返回的摘要，会渲染成带“展开全文”按钮的折叠卡片；/extract-entities返回的合同条款，则渲染成带“复制条款”按钮的表格卡片。按钮点击事件绑定Router的/copy-to-clipboardAPI，实现一键复制。

• 飞书文档：需转换为 飞书富文本格式 。Router会将模型返回的Markdown，解析成飞书支持的text,mention,link等节点。特别处理@人：模型输出“请找@张三确认”，Router会自动查找张三的飞书ID，渲染成真正的可点击@提及。

• Web OA系统：最复杂。Router需注入一段轻量JavaScript，动态修改DOM。例如，在审批流页面，AI返回“建议驳回，理由：预算超支15%”，Router脚本会找到“审批意见”输入框，自动填入文字，并高亮显示“预算超支15%”关键词。

这个过程的关键是前端适配器与Router的双向契约。Adapter告诉Router“我在什么环境下运行”，Router据此选择对应格式化器。我们抽象出Formatter接口，每个端实现自己的DingTalkFormatter、FeishuFormatter，Router根据source字段自动调用。新增端时，只需实现一个Formatter，无需改动核心逻辑。

4. 实操过程与核心环节实现：从零搭建一个可用的Router

4.1 环境准备与依赖安装

Router采用Go 1.21+开发，目标部署环境为企业内网Linux服务器（CentOS 7.6+/Ubuntu 20.04+）。所有依赖均通过go mod管理，无外部C库依赖，编译产物为单二进制文件，部署极简。

必备基础设施：

• Redis 6.2+：用于会话状态、缓存、分布式锁。推荐单节点（开发）或哨兵模式（生产）。
• PostgreSQL 12+：存储审计日志、用户配置、规则引擎词典。不存储业务数据，仅运维元数据。
• 向量数据库（可选但强烈推荐）：我们选用 Qdrant ，因其轻量（单节点Docker即可）、中文支持好、API简洁。若暂无向量库，Router可降级为纯规则匹配。

初始化步骤（以Ubuntu 22.04为例）：

# 1. 安装Go wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz export PATH=$PATH:/usr/local/go/bin # 2. 安装Redis（单节点） sudo apt update && sudo apt install redis-server -y sudo systemctl enable redis-server && sudo systemctl start redis-server # 3. 安装PostgreSQL sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - sudo apt-get update && sudo apt-get install postgresql-14 -y sudo -u postgres psql -c "CREATE DATABASE ai_router;" sudo -u postgres psql -c "CREATE USER router WITH PASSWORD 'your_secure_password';" sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE ai_router TO router;" # 4. 初始化Router数据库表（执行SQL脚本） psql -h localhost -U router -d ai_router -f ./migrations/init.sql

init.sql包含核心表：audit_logs（审计日志）、intent_rules（意图规则）、user_configs（用户个性化配置）、capability_endpoints（能力服务注册表）。表结构设计遵循“宽表+JSONB”原则，audit_logs的request_context字段为JSONB类型，可灵活存储各端异构上下文。

4.2 Router核心服务启动与配置

Router配置采用YAML文件驱动，config.yaml示例：

server: port: 8080 host: "0.0.0.0" cors_allowed_origins: ["https://oapi.dingtalk.com", "https://open.feishu.cn"] database: postgres: host: "localhost" port: 5432 database: "ai_router" user: "router" password: "your_secure_password" redis: addr: "localhost:6379" password: "" db: 0 # 向量数据库配置（可选） vector_db: qdrant: endpoint: "http://qdrant:6333" collection_name: "company_knowledge" # 能力服务注册表（关键！） capabilities: - id: "summarize" name: "文档摘要" endpoint: "http://summarize-service:8000/v1/summarize" timeout_ms: 15000 - id: "audit-expense" name: "报销审核" endpoint: "http://audit-service:8001/v1/audit" timeout_ms: 20000 - id: "draft-email" name: "邮件草稿" endpoint: "http://email-service:8002/v1/draft" timeout_ms: 10000 # 意图路由规则（可热更新） intent_rules: - pattern: "(报销|费用|差旅|发票) + (审核|检查|有没有|是否|问题)" capability_id: "audit-expense" weight: 0.95 - pattern: "(总结|概括|提炼|摘要) + (文档|报告|会议纪要)" capability_id: "summarize" weight: 0.98

启动命令：

go build -o ai-router main.go ./ai-router --config config.yaml

服务启动后，访问http://localhost:8080/healthz返回{"status":"ok"}即表示健康。Router提供/v1/capabilities端点，可动态注册/注销能力服务，无需重启。

4.3 接入第一个端：钉钉适配器实战

以钉钉为例，完成一次完整对接需四步：

Step 1：在钉钉开放平台创建自建应用

• 登录 钉钉开放平台 → 创建应用 → 选择“企业内部应用”
• 记录AppKey和AppSecret，填入Router的config.yaml中dingtalk.app_key和app_secret字段
• 在“应用功能”中开启“接收消息”和“发送消息”权限

Step 2：配置Router的钉钉回调地址

• Router内置钉钉消息接收Handler，暴露/v1/dingtalk/callback端点
• 在钉钉开放平台“事件订阅”中，将“消息事件”回调地址设为https://your-router-domain.com/v1/dingtalk/callback
• Router会自动处理钉钉签名验证，开发者无需关心

Step 3：前端注入钉钉JSAPI
在企业钉钉工作台的某个H5页面（如OA首页）中，引入钉钉JSAPI：

<script src="https://g.alicdn.com/dingding/open-develop/2.1.0/dingtalk-open.js"></script> <script> // 初始化 dd.config({ agentId: 'your_agent_id', corpId: 'your_corp_id', timeStamp: timestamp, nonceStr: nonceStr, signature: signature }); // 注册@AI监听（核心！） dd.on('atMessage', function(data) { // 将data转发给Router fetch('https://router.internal.company.com/v1/invoke', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ source: 'dingtalk', chat_id: data.chatId, user_id: data.senderId, message: data.text, timestamp: Date.now() }) }); }); </script>

Step 4：配置Router的钉钉适配器
在config.yaml中添加钉钉专属配置：

dingtalk: app_key: "your_app_key" app_secret: "your_app_secret" # 钉钉消息加密密钥（可选，增强安全） aes_key: "your_32bit_aes_key"

完成以上四步，用户在钉钉群聊中发送“@AI 总结一下昨天的项目会议纪要”，Router就会收到请求，路由到/summarize能力，返回摘要后，自动渲染成钉钉卡片发送回群聊。整个过程，从用户触发到结果返回，实测平均耗时1.8秒（P95<3秒）。

4.4 能力服务（Capability）的快速接入范式

Router的价值，最终由它能调度的能力决定。我们定义了一套极简的Capability接入规范，让后端团队1小时内即可接入一个新AI功能：

规范核心三要素：

1. HTTP RESTful API：POST /v1/{capability-id}，接收Router转发的标准化JSON请求；
2. 请求契约：必须包含context（Router注入的上下文）、query（用户原始问题）、user_id（用户标识）；
3. 响应契约：必须返回{ "result": "...", "format": "markdown|text|json", "metadata": {...} }。

以接入一个“合同关键条款抽取”能力为例：

• 后端服务暴露POST /v1/extract-clauses；
• Router收到飞书文档中触发的请求，自动注入context（含文档URL、当前段落ID）、query（“提取付款条款”）；
• 后端服务解析文档URL，下载PDF，用PyMuPDF提取文本，调用微调的NER模型识别payment_terms,delivery_date,penalty_clause等实体；
• 返回JSON：{"result": "付款方式：电汇；付款时间：验收后30日内；违约金：每日0.1%...", "format": "text", "metadata": {"confidence": 0.92}}；
• Router根据format字段，选择TextFormatter，将结果渲染为飞书纯文本消息。

这套规范让AI能力开发与Router解耦。我们已有12个Capability服务，涵盖会议纪要生成、日报自动填写、代码注释生成、财务凭证识别等，全部遵循同一契约。新能力上线，只需在Router的config.yaml中注册endpoint，无需修改Router一行代码。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “@AI没反应”——90%的问题出在前端适配器

这是最高频的报障。表面看是Router或模型问题，实则87%源于Adapter。我们整理了一份“前端五查清单”：

1. 查JS加载顺序：Adapter必须在dd.config()或lark.config()成功回调后才注册事件监听。常见错误是JS脚本放在<head>里，早于钉钉JSAPI加载，导致dd.on()报错“dd is not defined”。解决方案：将Adapter代码包裹在dd.ready()或lark.ready()回调内。

2. 查跨域限制：Router若部署在router.internal.company.com，而前端页面在oa.company.com，浏览器会拦截fetch请求。解决方案：Router必须配置CORS，cors_allowed_origins明确列出所有前端域名；或让前端通过后端代理转发（更安全）。

3. 查钉钉/飞书权限：新创建的钉钉应用默认无“接收消息”权限。需在开放平台“应用功能”中手动开启，并重新发布应用。飞书同理，需在“机器人”设置中勾选“接收消息”。

4. 查消息格式：钉钉的atMessage事件，data.text是纯文本，不包含@人的用户ID。Router需调用/v1.0/im/v1/messages/{message_id}/senderAPI反查用户信息。若忘记这步，权限校验会失败。我们在Router日志中加了[DEBUG] Missing sender info, fetching from DingTalk API...提示，方便定位。

5. 查网络策略：企业内网常禁用公网DNS。Router若配置了qdrant.endpoint: "http://qdrant.cloud"，而内网无法解析qdrant.cloud，会导致上下文注入失败。解决方案：所有内部服务地址必须用内网域名或IP，如qdrant.internal.company.com。

实操心得：我们开发了一个adapter-debugger.html页面，内嵌所有端的Adapter代码，提供“模拟触发”按钮。运维同学打开此页，点一下就能看到Adapter是否正常发送请求、Router是否收到，5分钟内完成前端链路诊断。

5.2 “AI回答驴唇不对马嘴”——上下文注入失效的三大诱因

当用户说“帮我看看这份合同”，AI却回答“今天天气不错”，问题几乎100%出在上下文。Router日志里context字段为空或错误，是首要排查点：

• 诱因1：Adapter未正确提取上下文。例如，在CRM客户页，Adapter应抓取URL中的?customerId=CUST-2024-0876，但前端路由用了Hash模式（#/customer/CUST-2024-0876），导致Adapter只拿到window.location.hash，没解析出ID。解决方案：Adapter必须兼容History API和Hash模式，我们封装了getCustomerIdFromUrl()通用函数。

• 诱因2：Router上下文注入超时。Router调用CRM API获取客户详情时，若CRM响应慢（>2秒），Router会放弃注入，继续路由。此时日志会打印[WARN] Context injection timeout for customer_id=CUST-2024-0876, proceeding without context。解决方案：在config.yaml中为关键能力设置context_timeout_ms: 5000，并优化CRM接口性能。

• 诱因3：知识库检索失准。向量数据库中，用户提问“付款方式”，但知识库条目标题是“结算条款”，语义相似度低。解决方案：我们增加了“查询扩展”模块，Router在调用Qdrant前，用小模型将用户问题重写为3个变体（如“付款方式”→“结算方式”、“支付条款”、“资金交付条件”），并行检索，取最高分结果。

5.3 “Router CPU飙升”——性能瓶颈的精准定位与优化

Router作为流量中枢，CPU是核心指标。我们曾遇到一次线上事故：CPU持续95%，但QPS仅200。pprof分析发现，90%时间消耗在json.Unmarshal上——Router为兼容各端异构请求，对每个请求都做完整JSON解析，而某些端（如老旧OA）发送的请求体巨大（含完整HTML快照）。优化方案：

• 流式解析：对context字段，Router不再json.Unmarshal整个body，而是用json.RawMessage延迟解析，仅当该Capability确实需要context时，才按需解析对应字段。
• 请求体截断：在Router入口加Middleware，对message字段长度超过5000字符的请求，自动截断并记录[WARN] Message truncated to 5000 chars for performance。
• 连接池优化：Router调用后端Capability时，HTTP Client连接池MaxIdleConnsPerHost从默认的2提升至50，避免频繁建连开销。

优化后，Router单实例QPS从800提升至5000，CPU峰值降至35%。

5.4 “审计日志查不到记录”——日志链路断裂的隐形杀手

审计日志是合规生命线，但日志缺失往往悄无声息。我们发现两个隐蔽原因：

• Redis连接泄漏：Router使用github.com/go-redis/redis/v8，若未正确调用defer client.Close()，连接数会缓慢增长，最终Redis拒绝新连接，日志写入失败。解决方案：所有Redis操作封装在withRedisClient()函数中，确保Close()被调用。

• PostgreSQL事务未提交：Router日志写入使用BEGIN事务，若某条日志写入失败（如磁盘满），事务回滚，之前成功的日志也丢失。解决方案：改为每条日志独立事务，牺牲一点性能，换取日志可靠性。INSERT INTO audit_logs (...) VALUES (...)不加BEGIN。

我们建立了日志健康检查：Router每5分钟向`audit_logs