DeepSeek Harness ↔ 企业微信桥接实操清单（落地版）

配套第 18 篇《把 DeepSeek Harness 接入企业微信，让全员用上 AI 助手》。那篇讲"为什么、整体怎么连"，这份讲"照着敲、照着配、照着排查"。

〇、结论先行（避免走弯路）

DeepSeek Harness 本身不对外暴露 OpenAI 兼容 API 服务，它是模型后端的"客户端"。所以"让企微用上 Harness"的正确链路是：

企微用户发消息 → 企微服务器回调你的 Bridge 服务 → Bridge 把任务交给 Harness 会话 / 你的模型后端 跑 → Bridge 把结果通过 主动发消息接口 推回企微

也就是说，Bridge 是你自己写的胶水服务，不是 Harness 自带功能。下面全部围绕"怎么写好这个 Bridge"。

一、整体架构（照抄）

[员工]               [企业微信服务器]                [你的 Bridge 服务]            [Harness / 模型后端]
  |  发消息(IM)  →       |  回调 POST /wecom          →       |  解密 + 验签            →  驱动 dsh web 会话
  |                      |  (HTTPS + Token+AESKey)    |  (5 秒内必须回 200)        |  或调模型 API
  |  ← 收到 AI 回复 ←    |  ← 主动推送 message/send  ←       |  调 message/send 主动推  ←  返回结果

全员协作

二、企微后台配置清单（先备齐）

配置项	在哪拿	用途	备注
CorpID	我的企业 → 企业信息	企业唯一标识	全局一个
CorpSecret	应用管理 → 自建应用 → Secret	换 access_token	每个应用独立
AgentID	自建应用详情	发消息指定应用	每个应用独立
可信域名	自建应用 → 可信域名	回调 URL 必须在此域下	需备案 + HTTPS
回调 URL	自建应用 → 接收消息 → 设置 API	填你的 Bridge 公网地址	`https://你的域名/wecom`
Token	同上	GET 验签	自定义字符串
EncodingAESKey	同上	消息 AES-256-CBC 加密	43 位随机串

⚠️ 回调 URL 必须公网可达 + HTTPS。Harness 默认只监听 127.0.0.1，所以 Bridge 单独部署在有公网 IP 的机器/容器上，Harness 可在内网或同机。

三、Bridge 最小可跑骨架（Flask）

# bridge.py —— 仅展示链路骨架，production 请加日志/限流/密钥管理
import time, hashlib, xml.etree.ElementTree as ET
import requests
from flask import Flask, request

CORP_ID   = "你的CorpID"
SECRET    = "你的Secret"
AGENT_ID  = 1000002
TOKEN     = "你设的Token"
AES_KEY   = "你设的43位EncodingAESKey"
BRIDGE_URL = "https://你的域名/wecom"

# 1) access_token 必须缓存（7200s 有效，别每次都换）
_token_cache = {"t": "", "exp": 0}
def get_token():
    if time.time() < _token_cache["exp"] - 60:
        return _token_cache["t"]
    r = requests.get("https://qyapi.weixin.qq.com/cgi-bin/gettoken",
                     params={"corpid": CORP_ID, "corpsecret": SECRET}, timeout=5)
    d = r.json(); _token_cache["t"] = d["access_token"]
    _token_cache["exp"] = time.time() + d.get("expires_in", 7200)
    return _token_cache["t"]

# 2) GET 验签：sha1(token, timestamp, nonce, echostr) 排序后 hex
def verify_get(args):
    arr = sorted([TOKEN, args["timestamp"], args["nonce"], args["echostr"]])
    return hashlib.sha1("".join(arr).encode()).hexdigest() == args["msg_signature"]

# 3) POST 收消息：先验签 → 解密 AES-256-CBC → 取明文（此处略解密实现，用伪代码占位）
def handle_post(xml_text):
    # 真实实现：按企微文档用 AESKey 做 AES-256-CBC 解密 msg_encrypt
    plain = decrypt_wecom(xml_text, AES_KEY)   # 见企微官方加解密库
    user = plain.findtext("FromUserName")
    content = plain.findtext("Content")
    # 关键：5 秒内必须回 200，AI 结果用"主动推送"异步发
    ask_harness(content)          # 驱动 dsh web 会话 / 调模型后端（见第四节）
    return "", 200

# 4) 主动推送结果：异步把 AI 回复发回用户
def push_reply(user, text):
    tok = get_token()
    requests.post("https://qyapi.weixin.qq.com/cgi-bin/message/send",
                  params={"access_token": tok},
                  json={"touser": user, "msgtype": "text", "agentid": AGENT_ID,
                        "text": {"content": text}}, timeout=5)

app = Flask(__name__)
@app.route("/wecom", methods=["GET"])
def challenge():
    if verify_get(request.args): return request.args["echostr"]
    return "verify fail", 403
@app.route("/wecom", methods=["POST"])
def callback():
    return handle_post(request.data)

上面是骨架。AES-256-CBC 解密请直接用企业微信官方提供的 WXCrypt 加解密库（Python/Java/Go/Node 都有），别自己造轮子上生产。

四、Harness 侧怎么接

# Harness 起 Web UI（默认仅本机，Bridge 与 Harness 同机时直接访问）
npx @deepseek-ai/dsh web          # http://127.0.0.1:3080
# 换端口：
npx @deepseek-ai/dsh web --port 8080

同机模式：Bridge 直接 http://127.0.0.1:3080 驱动 Harness 会话（用 Harness 的会话 API 或 UI 自动化）。
跨机/上云：Harness 与 Bridge 分置时，Bridge 通过内网地址访问；若 Harness 在纯内网、Bridge 在公网，反过来——让 Bridge 在内网侧、用内网穿透/反向代理接企微回调（见第五节拓扑 B）。
模型后端若走 DeepSeek/百炼等，apiKey 用环境变量注入 Bridge 进程，别写死在代码。

企微内对话

五、部署拓扑三档（按规模选）

方案	部署	适用	风险
A 同机	Harness + Bridge 一台内网机，企微回调走内网穿透	个人/小团队试水	公网穿透是单点
B 内网 Bridge	Bridge 在内网侧接企微回调，Harness 同内网	数据不出企业	需有固定公网入口
C 全上云	Bridge 部署在云服务器（HTTPS 域名），Harness 在云内网	全员长期使用	云成本 + 运维

六、5 秒红线（最容易翻车）

企微 POST 回调 5 秒内必须收到 200，否则认为失败、最多重试 3 次。AI 生成往往超过 5 秒，所以：

✅ 正确：回调里只做"验签 + 收消息 + 入队"，立刻回 200；AI 结果用 message/send 主动推送。
❌ 错误：在回调里同步等 AI 跑完再返回 → 超时 → 企微重试 → 用户收到 3 条重复回复。

七、安全双红线

Harness 不直连公网：dsh web 默认 127.0.0.1，别用 --host 0.0.0.0 裸奔。
Bridge 每条入站必校验：GET 验签 + POST 验签名 + AES 解密，缺一不可；非法请求直接 403。

安全红线

八、上线检查清单（8 项）

[ ] CorpID / Secret / AgentID 已填，Secret 用环境变量不入库
[ ] 可信域名已备案 + HTTPS，回调 URL 公网可达
[ ] Token / EncodingAESKey 已配，GET 验签通过（echostr 原样返回）
[ ] 用企微官方 WXCrypt 库做 AES-256-CBC 解密，POST 能取到明文
[ ] 回调 5 秒内回 200，AI 结果走 message/send 主动推（非同步返回）
[ ] access_token 已做 7200s 缓存，无频繁刷新
[ ] Harness dsh web 仅监听 127.0.0.1，Bridge 与 Harness 网络互通
[ ] 异常有日志 + 限流，重复消息有幂等处理

九、常见故障排查

现象	原因	处理
配置回调时验证失败	Token/域名不对	检查可信域名 HTTPS + Token 一致
用户发消息无回复	回调超时/解密失败	看 Bridge 日志；确认 5 秒回 200
收到 3 条重复回复	同步等 AI 超时重试	改异步主动推送
access_token 频繁失效	没缓存每次新建	加 7200s 缓存
Harness 连不上	监听 127.0.0.1 跨机	Bridge 与 Harness 同网或加内网代理

十、回链

想看完整背景与设计取舍？回复 【企微】 看第 18 篇《把 DeepSeek Harness 接入企业微信，让全员用上 AI 助手》。
想顺手把 Harness 插件也配齐？回复 【插件】 看第 19 篇《DeepSeek Harness 办公环境下必装插件指南》+ 赠品《办公插件选型清单》。

—— 莱驰云 AI 实战课堂 · 配套赠品 ——

DeepSeek Harness ↔ 企业微信 桥接实操清单（落地版）

〇、结论先行（避免走弯路）

一、整体架构（照抄）

二、企微后台配置清单（先备齐）

三、Bridge 最小可跑骨架（Flask）

四、Harness 侧怎么接

五、部署拓扑三档（按规模选）

六、5 秒红线（最容易翻车）

七、安全双红线

八、上线检查清单（8 项）

九、常见故障排查

十、回链

相关推荐

腾讯Marvis马维斯完全上手：系统级AI助手是什么、怎么装、怎么用

ChatGPT正式住进Word：免费用户也能用，选中段落直接改

用 AI 做短视频：从选题到发布的完整操作手册（附配图自托管接口用法）

别只用来聊天！腾讯 WorkBuddy 这 5 个玩法，才是打工人的效率核武

DeepSeek Harness 办公插件选型清单（落地版）

DeepSeek Harness ↔ 企业微信桥接实操清单（落地版）