釘釘 AI 助手怎麼接入？三種方案對比（附 Stream 模式程式碼）

釘釘開發者後台 →「應用開發」→「企業內部應用」→ 建立應用，然後在應用裡「加入機器人」，訊息接收模式選 Stream 模式。記下三個值：

• Client ID（原 AppKey）：應用憑證頁
• Client Secret（原 AppSecret）：應用憑證頁（只顯示一次，立即存入金鑰管理，不要進程式庫）
• robotCode：機器人詳情頁，發訊息時要帶上

發布前先把可見範圍設成一個小部門做灰度，驗證通過再放開。

Stream 模式的核心是：服務啟動時用憑證換一個臨時連線位址，然後連上去、訂閱機器人訊息主題。連線斷了要重連——這是後面坑 1 的根源。

# dingtalk_stream_bot.py —— 建立長連線並訂閱機器人訊息
from dingtalk_stream import DingTalkStreamClient, Credential
from dingtalk_stream.chatbot import ChatbotHandler, ChatbotMessage

class AIHandler(ChatbotHandler):
    async def process(self, callback):
        msg = ChatbotMessage.from_dict(callback.data)
        # 先回執，再異步處理，別在回調裡等 AI（見坑 3）
        self.reply_text("收到，正在處理…", msg)
        question = msg.text.content.strip()
        answer = ask_ai(question)          # 你自己的 AI 服務 / 知識庫
        self.reply_text(answer, msg)
        return 200, "OK"

credential = Credential(CLIENT_ID, CLIENT_SECRET)      # 從環境變數讀，別寫死
client = DingTalkStreamClient(credential)
client.register_callback_handler("/v1.0/im/bot/messages/get", AIHandler())
client.start_forever()                 # 內含自動重連，但要有行程級守護

除錯期最容易踩的坑：主題（topic）寫錯——機器人訊息的主題是固定的，寫錯會表現為「連上了但永遠收不到訊息」，日誌裡卻沒有任何報錯。

回覆會話用機器人訊息介面；如果要做「審批進度」「工單狀態」這類可點擊的互動，用互動卡片。兩個介面都走同一個 access_token，必須集中快取（有效期 7200 秒，有取得頻率限制）。

# dingtalk_client.py —— token 集中快取 + 發送機器人訊息
import time, requests

_token, _ts = "", 0

def get_token():
    global _token, _ts
    if _token and time.time() - _ts < 7000:          # 留 200 秒餘量
        return _token
    r = requests.post("https://api.dingtalk.com/v1.0/oauth2/accessToken",
                      json={"appKey": CLIENT_ID, "appSecret": CLIENT_SECRET},
                      timeout=5).json()
    _token, _ts = r["accessToken"], time.time()
    return _token

def reply_text(user_id, text):
    requests.post(
        "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend",
        headers={"x-acs-dingtalk-access-token": get_token()},
        json={"robotCode": ROBOT_CODE, "userIds": [user_id],
              "msgKey": "sampleText", "msgParam": '{"content": "%s"}' % text[:1800]},
        timeout=5)

注意最後一行：釘釘的文字訊息內容是包在 msgParam 的 JSON 字串裡的，超長要先截斷或分段，否則介面直接報錯（見坑 5）。

把 ask_ai() 換成你的 RAG 知識庫或大模型服務即可。三個工程要點：

• 逾時兜底：AI 超過 10 秒沒結果，先回一句「正在查，稍等」，別讓員工對著輸入框乾等
• 會話上下文：按 conversationId 存最近幾輪，別把整段歷史無限拼進 prompt
• 權限過濾：回答前先判斷提問人有沒有看這份文件的權限，知識庫檢索要帶權限條件，而不是檢索完再過濾