# dsh-x-connect

这是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 X API v2 插件。它通过 OAuth 2.0 PKCE 绑定一个 X 账号，让 Agent 可以检索、阅读、总结和发布帖子。

## 安装与配置

```sh
dsh plugin --profile web add dsh-x-connect
```

重启 `dsh web`，进入 **设置 → 插件 → X Connect**：

1. 在 [X Developer Console](https://developer.x.com/) 创建应用，开启 OAuth 2.0，选择 Public/Native Client 和 Authorization Code + PKCE。
2. 在 X 应用中注册回调地址 `http://127.0.0.1:56130/callback`。
3. 将 OAuth 2.0 Client ID 填入插件并保存；无需也不要填写 Client Secret。
4. 保留 `tweet.read`、`users.read`、`offline.access`；需要发帖时勾选 `tweet.write`。
5. 点击“生成授权链接”，在 X 完成授权；回到设置页后点击“测试连接”。

回调服务只会在等待授权期间自动启动，并且只监听本机回环地址；平时不会常驻。

## 功能

- `x_search`：检索近期帖子。
- `x_user_tweets` / `x_tweet` / `x_me`：阅读时间线、单条帖子和账号资料。
- 总结：读取工具将结构化原文交给当前 DSH 模型总结，不额外调用另一套 LLM。
- `x_post`：发布帖子或回复；默认必须通过 DSH 的一次性用户批准。
- `x_status` / `x_activity_log`：查看连接、scope、操作记录和费用估算。
- `x_connect` / `x_disconnect`：绑定或解绑账号；模型触发解绑时也必须批准。

X API 按量计费，插件显示的是版本发布时的估算值，实际价格、余额与上限以 X Developer Console 为准。令牌保存在 `~/.dsh/x-connect/credentials.json`，文件权限为 `0600`，不会返回给 Web 页面或模型。

## 绑定后如何使用

不需要在对话中输入特殊命令，直接用自然语言描述任务即可。为避免 Agent 扩大读取范围，建议在提示词中写明工具名、调用次数和最大条数。

### 查看自己的帖子

```text
请只调用一次 x_user_tweets，读取当前绑定账号最近 5 条帖子，
排除转帖和回复。用中文列出时间、链接和一句话摘要。
不搜索其他账号，不发帖。
```

这会使用 `x_user_tweets`，不填 `username` 时默认读取当前绑定账号。X 时间线端点每次最少请求 5 条，所以 5 是插件允许的最小值。

### 阅读并总结一条帖子

```text
请只调用一次 x_tweet 阅读这个链接：
https://x.com/<username>/status/<post-id>
然后用中文总结核心观点和一条风险提示。不调用 x_search，不发帖。
```

`x_tweet` 接受完整 X 链接或纯数字帖子 ID。“总结”是当前 DSH 模型对返回内容的处理，不会再调用一个 X 接口。

### 谨慎回复帖子

推荐分成两步，避免读取后立即发布：

```text
第一步：只调用一次 x_tweet 阅读这条帖子：
https://x.com/<username>/status/<post-id>
拟一条不超过 100 字、不含链接的中文回复。
只显示草稿，不调用 x_post。
```

检查草稿后，再单独发出：

```text
请调用一次 x_post，将下面文字回复到帖子 <post-id>：
<已确认的回复文字>
不要修改文字，不要执行其他 X 工具。
```

`<post-id>` 必须是 `status/` 后的纯数字 ID。保持设置中的“发帖前要求一次性批准”开启；`x_post` 真正发布前，DSH 会再展示文本和估算费用，只有你点击允许后才会调用 X API。

### 费用与最小化调用

根据 [X 官方当前按量计费说明](https://docs.x.com/x-api/getting-started/pricing)：

| 操作 | 当前公开单价 | 插件行为 |
| --- | ---: | --- |
| 读取 1 条帖子 | $0.005/资源 | `x_tweet`、`x_search`和时间线返回的帖子 |
| 读取 1 条用户资料 | $0.010/资源 | `x_me`；按用户名查时间线也需先解析账号 |
| 符合条件的自有数据读取 | $0.001/资源 | 仅当认证用户是开发者应用所有者且端点符合 X 规则时 |
| 发布纯文本帖子或回复 | $0.015/请求 | `x_post` |
| 发布含 URL 的帖子或回复 | $0.200/请求 | `x_post` |

插件在无法确定“自有数据读取”资格时使用普通读取价格作保守估算。X 说明同一资源在 24 小时 UTC 日窗口内通常会去重，失败且没有返回数据的请求不计费；去重是软保证，最终以 Developer Console 账单为准。

控制费用时：

- 先说“只拟稿，不调用 X 工具”，确认任务后再允许一次读取。
- 显式限制工具调用次数和 `maxResults`；查看自己帖子时从 5 条开始。
- 尽量读取精确 URL，不要在只需一条帖子时使用 `x_search`。
- 在 X Developer Console 中设置 Spending limit 并检查余额；插件估算不是账单。
- 用 `x_status` 查连接和本地统计，用 `x_activity_log` 看插件历史操作。这两个工具只读本地状态，不调用 X API。

## 开发验证

```sh
npm ci
npm run check
npm pack --dry-run
```

MIT License。