介绍
# Mastodon Scout
## 用途
这是一个只读的 Mastodon CLI 工具，用于从 Mastodon API 获取数据。默认返回人类可读的摘要，或者使用 `--json` 标志返回原始 JSON。
---
## 调用规则（强制）
### 二进制文件选择 - **macOS / Darwin** → `{baseDir}/bin/mastodon-scout` - **Linux** → `{baseDir}/bin/mastodon-scout`
### 命令
#### 主页时间线 ``` {baseDir}/bin/mastodon-scout home ``` 获取已认证用户的主页时间线。
#### 用户推文 ``` {baseDir}/bin/mastodon-scout user-tweets ``` 获取已认证用户自己的帖子。
#### 提及 ``` {baseDir}/bin/mastodon-scout mentions ``` 获取提及已认证用户的帖子。
#### 搜索 ``` {baseDir}/bin/mastodon-scout search <query> ``` 搜索与查询匹配的帖子。
### 标志（可选） ``` --instance <url> # Mastodon instance URL (default: https://mastodon.social) --limit <int> # Number of items to return (default: 20) --timeout <int> # Timeout in seconds (default: 30) --json # Output raw JSON instead of human-readable text ```
### 环境变量（必需） ``` MASTODON_TOKEN # OAuth bearer token for authentication ```
---
## 输出模式
### 文本模式（默认） ```bash mastodon-scout home ``` 返回时间线数据的人类可读摘要。
代理（Agent）可以总结并解释时间线结果，以便用户更容易理解。
### JSON 模式 ```bash mastodon-scout --json home ``` 返回来自 Mastodon API 的原始 JSON 数据。
当使用 JSON 模式时，原样返回输出而不进行解释。
---
## 错误处理
- 如果二进制文件以非零状态退出： - 在 JSON 模式下：原样返回错误输出 - 在文本模式下：代理可以向用户解释错误 - 不要重试
- 如果未设置 MASTODON_TOKEN： - 二进制文件将退出并显示错误消息 - 代理应引导用户前往身份验证设置部分
---
## 触发此技能的示例
- `mastodon-scout home` - `show my mastodon timeline` - `check mastodon mentions` - `search mastodon for "golang"` - `get my mastodon posts`
---
## 性能要求
- 直接执行二进制文件 - 不进行网络搜索 - 除二进制文件外不使用辅助工具 - 最小化延迟
---
## 注意事项
- 在文本模式下：代理可以总结并解释结果 - 在 JSON 模式下：原样输出，不进行解释 - 此技能为**只读**（无法发布、关注或其他变更操作）
---
## 身份验证设置（代理可以提供帮助）
**严格模式的例外**：如果用户在获取令牌方面需要帮助，代理**可以**在执行技能之前提供指导。
该工具需要在 `MASTODON_TOKEN` 环境变量中设置 Mastodon OAuth bearer token。
### 如何获取令牌（引导用户）：
**步骤 1：访问开发设置** - 用户应登录其 Mastodon 实例（例如 mastodon.social、fosstodon.org） - 导航至：**Settings → Development**（或 Preferences → Development） - 直接 URL 格式：`https://[instance-domain]/settings/applications`
**步骤 2：创建应用** - 点击“New Application” - 填写详细信息： - **Application name**：`mastodon-scout`（或任意名称） - **Application website**：可以留空或使用任意 URL - **Redirect URI**：`urn:ietf:wg:oauth:2.0:oob`（用于 CLI 应用） - **Scopes**：**关键 - 仅选择 `read`**（取消勾选 write、follow、push）
**步骤 3：获取访问令牌** - 点击“Submit” - 点击创建的应用以查看详细信息 - 复制 **"Your access token"** 字段的值
**步骤 4：设置环境变量** ```bash export MASTODON_TOKEN="paste_token_here" ```
**步骤 5：验证令牌是否有效** ```bash {baseDir}/bin/mastodon-scout home ```
### 常见的 Mastodon 实例： - `mastodon.social` - 通用（默认） - `fosstodon.org` - FOSS/技术社区 - `mas.to` - 专注于技术 - `hachyderm.io` - 技术/信息安全社区
对于非默认实例，请使用 `--instance https://your-instance.com` 标志。
### 需传达的安全说明： - 令牌是**只读**的（无法发布、关注或删除） - 保密令牌（不要提交到 git） - 可以随时在开发设置中撤销 - 每个 Mastodon 实例都需要自己的令牌
---
## 输出格式
### 文本模式（默认） 帖子的人类可读摘要，格式化以提高可读性。代理决定如何展示信息。
### JSON 模式（`--json` 标志） 所有命令均按以下格式返回 JSON：
```json { "success": true, "data": [ /* Mastodon API response */ ] } ```
或者在出错时：
```json { "success": false, "error": "error message" } ```
`data` 字段包含未加修改的原始 Mastodon API 响应。