前言¶
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 开发场景。
