前言¶
DeepSeek Harness（DSH）通過插件機制擴展智能體的能力。在開發涉及社交網絡交互的智能體時，對接 X (Twitter) API 通常需要處理複雜的 OAuth 2.0 流程、令牌刷新以及權限管理。dsh-x-connect 是爲此場景提供的插件，它將 X API v2 的連接封裝爲 DSH 的原生工具，允許智能體直接搜索、閱讀、總結併發布內容。
是什麼¶
這是一個爲 DeepSeek Harness 提供的 X API v2 連接器。它通過 OAuth 2.0 Authorization Code with PKCE 協議綁定一個 X 賬號，爲 DSH 模型提供搜索、閱讀、總結和發佈帖子的能力。
安裝與啓用¶
在安裝之前，請確保你的環境滿足 Node.js ^22.19 || >=24。
- 使用 DSH 官方命令安裝插件：
dsh plugin --profile web add dsh-x-connect
- 安裝完成後，重啓
dsh web。 - 打開 Settings → Plugins → X Connect 進行配置。
X 應用配置¶
插件需要你在 X Developer Console 中創建一個應用並獲取憑證：
- 在 X Developer Console 創建項目和應用。
- 啓用 OAuth 2.0，配置一個 Public/Native 類型的客戶端，使用 Authorization Code with PKCE。
- 在回調 URI 中註冊
http://127.0.0.1:56130/callback（或其他本地迴環 URI 及明確端口）。 - 在 DSH 設置頁面輸入 OAuth 2.0 的 Client ID 並保存。
- 授權所需權限：至少保留
tweet.read、users.read、offline.access，發佈功能需啓用tweet.write。 - 在設置卡片中點擊 Generate authorization link，在 X 網站完成授權後返回 DSH，點擊 Test connection。
回調監聽器僅在授權進行時啓動，僅監聽本地迴環接口，不會對外暴露。
核心功能¶
- 賬號綁定與測試：在設置頁面配置並綁定賬號，支持測試連接狀態。
- 信息讀取與總結：提供搜索、讀取單條帖子或用戶時間線的能力，並將內容結構化返回給 DSH 模型進行總結。
- 安全發佈：發佈帖子和回覆默認需要經過 DSH 的一鍵審批，用戶確認後纔會發送。
- 本地管理：OAuth 令牌在本地刷新，並記錄操作審計日誌。
- 安全設計：僅使用 X 的 Public Client PKCE 模式，絕不發送 OAuth Client Secret。
Agent 工具列表¶
插件提供了以下工具供智能體調用：
| 工具名稱 | 功能描述 |
|---|---|
x_status |
查看賬號、權限、回調狀態及預估用量 |
x_connect / x_disconnect |
綁定或移除本地 OAuth 憑證 |
x_me |
讀取綁定的賬號資料 |
x_search |
搜索最近的 X 帖子 |
x_user_tweets |
讀取賬號的時間線 |
x_tweet |
讀取指定 ID 或 URL 的帖子 |
x_post |
發佈帖文或回覆（需批准） |
x_activity_log |
檢查或（經批准後）清除本地活動日誌 |
典型用法¶
智能體調用工具時無需前綴，直接使用自然語言描述即可。
示例 1：總結最近 5 條原創帖子¶
要求智能體調用一次 x_user_tweets，獲取當前綁定賬號的最近 5 條帖子（排除轉發和回覆），並用一句話總結每條帖子的要點、日期和鏈接。
Call x_user_tweets exactly once for the currently bound account with maxResults 5.
Exclude reposts and replies. Summarize each result in one sentence with its date and URL.
Do not search other accounts and do not publish anything.
示例 2：讀取並總結特定帖子¶
要求智能體調用 x_tweet 讀取指定 URL 的帖子，並總結其主要論點和一個注意事項。
Call x_tweet exactly once for https://x.com/<username>/status/<post-id>.
Summarize its main claim and one caveat. Do not call x_search or x_post.
示例 3：起草併發布回覆¶
分兩步走。第一步請求草稿，第二步經用戶批准後發佈。
第一步（起草）：
Call x_tweet exactly once for https://x.com/<username>/status/<post-id>.
Draft a reply under 100 characters with no URL. Show the draft only; do not call x_post.
第二步（發佈）：
Call x_post exactly once to reply to <post-id> with this exact text:
<approved reply text>
Do not alter the text and do not call any other X tool.
請保持“Require one-time approval before posting”開啓。在調用
x_post之前，DSH 會顯示最終文本和預估成本，拒絕批准將阻止發佈。
適用場景與注意¶
- 計費說明：X API 按使用付費。當前費率爲每條 Post 讀 $0.005，每條 User 讀 $0.010，純文本創建 $0.015，含 URL 創建 $0.200。插件基於發佈時的文檔費率估算，但 X 官方文檔爲準。失敗請求不收費，但去重是軟保證。
- 憑證安全：OAuth 憑證存儲在
~/.dsh/x-connect/credentials.json，文件權限爲0600，僅本地可讀寫，不會被返回給瀏覽器或模型。 - 環境要求：插件以 DSH 進程權限運行，安裝前請檢查源碼與許可證（MIT）。
總結¶
dsh-x-connect 通過封裝 X API 的 OAuth 流程和工具調用，降低了智能體接入社交網絡的技術門檻。它強調本地管理和安全審批，適合需要代理自動處理社交媒體內容的 DSH 開發場景。
