介绍
# xAI Skill
搜索 X (Twitter)，搜索网络，与 Grok 模型聊天（包括视觉），并使用 xAI 的 API 分析 X 内容模式。
## 功能
- **X 搜索**：使用日期/句柄过滤器搜索帖子、帖子串和账户 - **网络搜索**：通过 Grok 的 web_search 工具搜索网络 - **聊天**：使用 Grok 模型进行文本和视觉（图像分析）交互 - **分析**：语音模式、趋势研究、帖子安全检查 - **模型**：列出可用的 xAI 模型
## 设置
### API 密钥
从 [console.x.ai](https://console.x.ai) 获取您的 xAI API 密钥。
```bash # Via clawdbot config (recommended) clawdbot config set skills.entries.xai-plus.apiKey "xai-YOUR-KEY"
# Or environment variable export XAI_API_KEY="xai-YOUR-KEY" ```
脚本按顺序检查以下位置： 1. `XAI_API_KEY` 环境变量 2. `~/.clawdbot/clawdbot.json` → `env.XAI_API_KEY` 3. `~/.clawdbot/clawdbot.json` → `skills.entries.xai-plus.apiKey` 4. `~/.clawdbot/clawdbot.json` → `skills.entries["grok-search"].apiKey`（回退）
### 默认模型（可选）
覆盖默认模型（`grok-4-1-fast`）：
```bash # Via config clawdbot config set skills.entries.xai-plus.model "grok-3"
# Or environment variable export XAI_MODEL="grok-3" ```
模型优先级： 1. 命令行 `--model` 标志（最高优先级） 2. `XAI_MODEL` 环境变量 3. `~/.clawdbot/clawdbot.json` → `env.XAI_MODEL` 4. `~/.clawdbot/clawdbot.json` → `skills.entries.xai-plus.model` 5. 默认：`grok-4-1-fast`
## 搜索
### X 搜索
使用可选过滤器搜索 X 帖子和帖子串。
**基本搜索：** ```bash node {baseDir}/scripts/grok_search.mjs "query" --x ```
**带日期过滤器：** ```bash # Last 7 days node {baseDir}/scripts/grok_search.mjs "Claude AI" --x --days 7
# Specific date range node {baseDir}/scripts/grok_search.mjs "AI agents" --x --from 2026-01-01 --to 2026-01-31 ```
**按句柄过滤：** ```bash # Only from specific accounts node {baseDir}/scripts/grok_search.mjs "AI news" --x --handles @AnthropicAI,@OpenAI
# Exclude accounts node {baseDir}/scripts/grok_search.mjs "GPT" --x --exclude @spam1,@spam2 ```
**输出格式：** ```bash # JSON (default, agent-friendly) node {baseDir}/scripts/grok_search.mjs "query" --x
# Links only node {baseDir}/scripts/grok_search.mjs "query" --x --links-only
# Human-readable text node {baseDir}/scripts/grok_search.mjs "query" --x --text ```
**JSON 输出模式：** ```json { "query": "search query", "mode": "x", "results": [ { "title": "@handle", "url": "https://x.com/handle/status/123", "snippet": "Post text...", "author": "@handle", "posted_at": "2026-01-15T10:30:00Z" } ], "citations": ["https://x.com/..."] } ```
### 网络搜索
通过 Grok 搜索网络。
```bash node {baseDir}/scripts/grok_search.mjs "TypeScript best practices 2026" --web ```
**JSON 输出模式：** ```json { "query": "search query", "mode": "web", "results": [ { "title": "Page title", "url": "https://example.com/page", "snippet": "Description...", "author": null, "posted_at": null } ], "citations": ["https://example.com/..."] } ```
### 搜索选项
| 标志 | 描述 | 示例 | |------|-------------|---------| | `--x` | 搜索 X/Twitter | X 搜索必需 | | `--web` | 搜索网络 | 网络搜索必需 | | `--days N` | 过去 N 天（仅 X） | `--days 7` | | `--from YYYY-MM-DD` | 开始日期（仅 X） | `--from 2026-01-01` | | `--to YYYY-MM-DD` | 结束日期（仅 X） | `--to 2026-01-31` | | `--handles a,b` | 仅这些账户（仅 X） | `--handles @user1,@user2` | | `--exclude a,b` | 排除账户（仅 X） | `--exclude @spam` | | `--max N` | 最大结果数 | `--max 20` | | `--model ID` | 覆盖模型 | `--model grok-3` | | `--json` | JSON 输出（默认） | - | | `--links-only` | 仅 URL | - | | `--text` | 人类可读 | - | | `--raw` | 包含调试输出 | - |
有关高级查询模式和优化技巧，请参阅 [references/search-patterns.md](references/search-patterns.md)。
## 聊天
### 文本聊天
询问 Grok 任何问题。
```bash node {baseDir}/scripts/chat.mjs "What is quantum computing?" ```
**覆盖模型：** ```bash node {baseDir}/scripts/chat.mjs --model grok-3 "Explain transformers in ML" ```
**JSON 输出：** ```bash node {baseDir}/scripts/chat.mjs --json "What is TypeScript?" ```
JSON 模式： ```json { "model": "grok-4-1-fast", "prompt": "What is TypeScript?", "text": "TypeScript is...", "citations": ["https://..."] } ```
### 视觉聊天
使用 Grok 分析图像。
```bash node {baseDir}/scripts/chat.mjs --image ./screenshot.png "What's in this image?" ```
**多张图像：** ```bash node {baseDir}/scripts/chat.mjs --image ./pic1.jpg --image ./pic2.jpg "Compare these" ```
**支持的格式：** JPG, PNG, WebP, GIF
### 聊天选项
| 标志 | 描述 | 示例 | |------|-------------|---------| | `--model ID` | 要使用的模型 | `--model grok-2-vision-1212` | | `--image PATH` | 附加图像（可重复） | `--image ./pic.jpg` | | `--json` | JSON 输出 | - | | `--raw` | 包含调试输出 | - |
有关模型比较和功能，请参阅 [references/models.md](references/models.md)。
## 分析
分析 X 内容的语音模式、趋势和帖子质量。
### 语音分析
分析账户的语音和写作模式。
```bash node {baseDir}/scripts/analyze.mjs voice @username ```
**自定义日期范围：** ```bash # Last 60 days node {baseDir}/scripts/analyze.mjs voice @username --days 60 ```
**JSON 输出模式：** ```json { "handle": "@username", "analyzed_posts": 150, "voice": { "tone": "casual, technical", "personality": ["curious", "direct", "helpful"], "perspective": "practitioner sharing lessons", "energy_level": "medium" }, "patterns": { "sentence_structure": ["short declarative", "occasional fragments"], "vocabulary": ["technical", "accessible"], "formatting_quirks": ["line breaks for emphasis", "minimal punctuation"], "recurring_phrases": ["here's the thing", "turns out"] }, "topics": ["AI", "software engineering", "startups"], "best_posts": [ { "url": "https://x.com/username/status/123", "text": "Post text...", "why": "Authentic voice, specific example" } ], "anti_patterns": ["never uses em-dashes", "avoids numbered lists"] } ```
### 趋势研究
研究关于某个主题的趋势和讨论。
```bash node {baseDir}/scripts/analyze.mjs trends "AI agents" ```
**JSON 输出模式：** ```json { "topic": "AI agents", "trends": [ { "pattern": "Shift from chatbots to autonomous agents", "description": "Discussion focuses on...", "example_posts": ["https://x.com/..."] } ], "perspectives": [ { "viewpoint": "Agents will replace most SaaS", "supporters": ["@user1", "@user2"] } ], "hashtags": ["#AIAgents", "#AutonomousAI"], "key_accounts": ["@researcher1", "@founder2"], "posting_angles": [ { "angle": "Practical implementation challenges", "hook": "Everyone talks about AI agents. Nobody talks about...", "target_audience": "Engineers building with AI" } ] } ```
### 帖子安全检查
检查草稿帖子或现有帖子的 AI 信号和平台标记模式。
**检查草稿文本：** ```bash node {baseDir}/scripts/analyze.mjs post "Your draft post text here" ```
**检查现有帖子：** ```bash node {baseDir}/scripts/analyze.mjs post --url "https://x.com/user/status/123" ```
**JSON 输出模式：** ```json { "post_text": "Your post...", "ai_detection_score": 3, "ai_signals": [ "Contains em-dash", "Ends with engagement bait question" ], "platform_flag_score": 2, "platform_risks": [ "Generic question could trigger spam filter" ], "quality_score": 7, "suggestions": [ "Replace em-dash with period or comma", "Remove 'What do you think?' closer", "Add specific personal detail" ] } ```
**评分：** - **AI 检测**：0-10（10 = 肯定是 AI） - **平台标记风险**：0-10（10 = 高垃圾邮件风险） - **质量**：0-10（10 = 优秀）
### 分析选项
| 标志 | 描述 | 示例 | |------|-------------|---------| | `--days N` | 分析的日期范围 | `--days 60` | | `--url URL` | 分析现有帖子 | `--url https://x.com/...` | | `--model ID` | 覆盖模型 | `--model grok-3` | | `--json` | JSON 输出 | - | | `--raw` | 包含调试输出 | - |
有关详细的提示结构和评分标准，请参阅 [references/analysis-prompts.md](references/analysis-prompts.md)。
## 模型
列出可用的 xAI 模型。
```bash node {baseDir}/scripts/models.mjs ```
**输出：** ``` grok-2-vision-1212 grok-3 grok-4-1-fast grok-4-fast ```
**JSON 输出：** ```bash node {baseDir}/scripts/models.mjs --json ```
快速模型比较：
| 模型 | 速度 | 质量 | 视觉 | 最适用于 | |-------|-------|---------|--------|----------| | grok-4-1-fast | 快 | 好 | 否 | 默认（搜索、聊天、分析） | | grok-4-fast | 快 | 好 | 否 | 替代快速模型 | | grok-3 | 慢 | 最好 | 否 | 复杂推理、详细分析 | | grok-2-vision-1212 | 中 | 好 | 是 | 图像分析 |
有关详细的模型功能和用例，请参阅 [references/models.md](references/models.md)。
## 高级用法
### 引用去重
对于 X 搜索，工具会自动对帖子 URL 进行去重，优先使用规范的 `/@handle/status/id` 格式而不是 `/i/status/id` 格式。
### 自定义模型选择
为任何操作覆盖默认模型：
```bash # Search with grok-3 for better quality node {baseDir}/scripts/grok_search.mjs "complex query" --x --model grok-3
# Chat with vision model node {baseDir}/scripts/chat.mjs --model grok-2-vision-1212 --image pic.jpg "Describe"
# Analysis with grok-3 for deeper insights node {baseDir}/scripts/analyze.mjs voice @username --model grok-3 ```
### 调试
在任何命令中添加 `--raw` 以查看完整的 API 响应：
```bash node {baseDir}/scripts/grok_search.mjs "query" --x --raw ```
## 参考文档
- [API 参考](references/api-reference.md) - xAI API 端点和参数 - [搜索模式](references/search-patterns.md) - 查询模式、过滤器、优化技巧 - [模型](references/models.md) - 模型比较和功能 - [分析提示](references/analysis-prompts.md) - 结构化提示和评分标准 - [X 算法](references/x-algorithm.md) - 排名、互动权重、垃圾邮件检测
## 示例
### 研究主题 ```bash # Find recent discussions node {baseDir}/scripts/grok_search.mjs "Claude Sonnet 4.5" --x --days 3
# Get trend analysis node {baseDir}/scripts/analyze.mjs trends "Claude Sonnet 4.5" ```
### 起草前分析语音 ```bash # Study the target account node {baseDir}/scripts/analyze.mjs voice @target_account --days 30
# Check your draft node {baseDir}/scripts/analyze.mjs post "Your draft here" ```
### 多模态研究 ```bash # Search web for context node {baseDir}/scripts/grok_search.mjs "TypeScript 5.7 features" --web
# Ask follow-up node {baseDir}/scripts/chat.mjs "What are the key TypeScript 5.7 improvements?"
# Analyze screenshot node {baseDir}/scripts/chat.mjs --image ./code.png "Review this code" ```
## 错误处理
常见错误和解决方案：
**缺少 API 密钥：** ``` Missing XAI_API_KEY ``` → 设置 `XAI_API_KEY` 环境变量或添加到 `~/.clawdbot/clawdbot.json`
**无效模式：** ``` Must specify --web or --x ``` → 在搜索命令中添加 `--web` 或 `--x` 标志
**图像格式错误：** ``` Unsupported image type ``` → 使用 JPG、PNG、WebP 或 GIF 格式
**API 错误：** ``` xAI API error: 401 Unauthorized ``` → 检查 API 密钥是否有效且处于活动状态
## 提示
- 默认模型 (`grok-4-1-fast`) 速度快，适用于大多数任务 - 使用 `grok-3` 进行复杂分析或在质量比速度更重要时使用 - X 搜索受最近性限制（xAI x_search 工具约束） - 网络搜索最适合针对特定的、当前的查询 - 语音分析需要足够的帖子历史记录（建议 30 个以上帖子） - 帖子安全检查仅供参考；最终决策请自行判断 - JSON 输出最适合代理/脚本使用 - 文本输出更适合终端/人类阅读
## 故障排除
**X 搜索无结果：** - 尝试更广泛的查询或更长的日期范围 - 检查句柄是否存在且公开 - 移除过度限制的过滤器
**语音分析不完整：** - 增加 `--days` 以获取更多帖子历史记录 - 检查账户是否公开且活跃 - 验证句柄是否正确（带或不带 @）
**API 速率限制：** - xAI 对每个 API 密钥执行速率限制 - 如果遇到限制，请分散请求时间 - 考虑升级 xAI 计划以获得更高的限制
## 内容撰写工作流
使用分析工具改进您的 X 内容：
```bash # Research before writing node {baseDir}/scripts/analyze.mjs trends "your topic" node {baseDir}/scripts/grok_search.mjs "your topic" --x --days 7
# Study voice patterns node {baseDir}/scripts/analyze.mjs voice @target_account
# Check draft before posting node {baseDir}/scripts/analyze.mjs post "$(cat draft.txt)" ```
使用 JSON 输出来： - 研究当前的讨论和发帖角度 - 向细分领域中的成功语音学习 - 在发布前捕获 AI 信号和平台标记