gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-07-27 18:57:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: skills - upgrade skill instructions

Browse Source
This commit is contained in:
tukuaiai
2026-04-28 19:14:07 +08:00
parent 3e7a11b6cb
commit 7dd36d6dd3
16 changed files with 1229 additions and 3071 deletions
Download Patch File Download Diff File Expand all files Collapse all files
assets/skills/ccxt/SKILL.md
+100 -66
View File
File diff suppressed because one or more lines are too long
assets/skills/claude-code-guide/SKILL.md
+70 -434
View File
@@ -1,470 +1,106 @@
---
name: claude-code-guide
description: Claude Code 高级开发指南 - 全面的中文教程，涵盖工具使用、REPL 环境、开发工作流、MCP 集成、高级模式和最佳实践。适合学习 Claude Code 的高级功能和开发技巧。
description: "Claude Code guide skill: CLI workflows, project context, tool permissions, slash commands, hooks, MCP, large-file analysis, debugging, and advanced coding-agent operating patterns."
---
# Claude Code 高级开发指南
# claude-code-guide Skill
全面的 Claude Code 中文学习指南，涵盖从基础到高级的所有核心概念、工具使用、开发工作流和最佳实践。
Use this skill to answer Claude Code workflow questions and to turn the long Chinese guide in `references/README.md` into focused operating steps.
## 何时使用此技能
## When to Use This Skill
当需要以下帮助时使用此技能：
- 学习 Claude Code 的核心功能和工具
- 掌握 REPL 环境的高级用法
- 理解开发工作流和任务管理
- 使用 MCP 集成外部系统
- 实现高级开发模式
- 应用 Claude Code 最佳实践
- 解决常见问题和错误
- 进行大文件分析和处理
Trigger when any of these applies:
- Learning or explaining Claude Code CLI workflows, command habits, or project-context handling.
- Designing slash commands, hooks, MCP integrations, memory/context conventions, or task workflows.
- Debugging Claude Code permission, tool-use, file analysis, or large-context problems.
- Comparing interactive coding-agent patterns such as explore-plan-edit-verify, review loops, or multi-agent coordination.
- Extracting a compact answer from the full Claude Code guide in `references/README.md`.
## 快速参考
## Not For / Boundaries
### Claude Code 核心工具（7个）
- Not the source of truth for current Claude product availability, pricing, or model names; verify those with official Anthropic docs when exact current behavior matters.
- Not for bypassing tool permissions, sandbox rules, repository policies, or higher-priority system/developer instructions.
- Do not treat the long guide as automatically correct for every Claude Code version; use it as local project reference material.
- Required inputs: target workflow, OS/shell, Claude Code version if relevant, current repository constraints, and the exact error or behavior observed.
- If a command may mutate files or external systems, identify the blast radius and validation path before recommending it.
1. **REPL** - JavaScript 运行时环境
- 完整的 ES6+ 支持
- 预加载库：D3.js, MathJS, Lodash, Papaparse, SheetJS
- 支持 async/await, BigInt, WebAssembly
- 文件读取：`window.fs.readFile()`
## Quick Reference
2. **Artifacts** - 可视化输出
- React, Three.js, 图表库
- HTML/SVG 渲染
- 交互式组件
### Common Patterns
3. **Web Search** - 网络搜索
- 仅美国可用
- 域名过滤支持
4. **Web Fetch** - 获取网页内容
- HTML 转 Markdown
- 内容提取和分析
5. **Conversation Search** - 对话搜索
- 搜索历史对话
- 上下文检索
6. **Recent Chats** - 最近对话
- 访问最近会话
- 对话历史
7. **End Conversation** - 结束对话
- 清理和总结
- 会话管理
### 大文件分析工作流
**Start with project context**
```text
Read README/AGENTS/CONTRIBUTING, inspect git status, then search for local patterns before editing.
```
**Large-file triage**
```bash
# 阶段 1：定量评估
wc -l filename.md # 行数统计
wc -w filename.md # 词数统计
wc -c filename.md # 字符数统计
# 阶段 2：结构分析
grep "^#{1,6} " filename.md # 提取标题层次
grep "```" filename.md # 识别代码块
grep -c "keyword" filename.md # 关键词频率
# 阶段 3：内容提取
Read filename.md offset=0 limit=50 # 文件开头
Read filename.md offset=N limit=100 # 目标部分
Read filename.md offset=-50 limit=50 # 文件结尾
wc -l path/to/file.md
rg -n '^#{1,6} ' path/to/file.md
sed -n '1,120p' path/to/file.md
```
### REPL 高级用法
```javascript
// 数据处理
const data = [1, 2, 3, 4, 5];
const sum = data.reduce((a, b) => a + b, 0);
// 使用预加载库
// Lodash
_.chunk([1, 2, 3, 4], 2); // [[1,2], [3,4]]
// MathJS
math.sqrt(16); // 4
// D3.js
d3.range(10); // [0,1,2,3,4,5,6,7,8,9]
// 读取文件
const content = await window.fs.readFile('path/to/file');
// 异步操作
const result = await fetch('https://api.example.com/data');
const json = await result.json();
**Slash command authoring shape**
```text
.claude/commands/<command-name>.md
```
### 斜杠命令系统
**内置命令：**
- `/help` - 显示帮助
- `/clear` - 清除对话
- `/plugin` - 管理插件
- `/settings` - 配置设置
**自定义命令：**
创建 `.claude/commands/mycommand.md`：
```markdown
根据需求执行特定任务的指令
**Hook design checklist**
```text
event -> allowed command -> timeout -> logging -> rollback/disable path
```
使用：`/mycommand`
### 开发工作流模式
#### 1. 文件分析工作流
```bash
# 探索 → 理解 → 实现
ls -la # 列出文件
Read file.py # 读取内容
grep "function" file.py # 搜索模式
# 然后实现修改
**MCP integration checklist**
```text
server name -> command/env -> auth source -> minimal permission -> smoke test
```
#### 2. 算法验证工作流
```bash
# 设计 → 验证 → 实现
# 1. 在 REPL 中测试逻辑
# 2. 验证边界情况
# 3. 实现到代码
**Debug a Claude Code failure**
```text
Capture: command, working directory, permission mode, exact error, relevant config, and smallest reproduction.
```
#### 3. 数据探索工作流
```bash
# 检查 → 分析 → 可视化
# 1. 读取数据文件
# 2. REPL 中分析
# 3. Artifacts 可视化
**Context hygiene rule**
```text
Keep entry prompts short; move long references to files and load only the needed section.
```
## 核心概念
## Examples
### 工具权限系统
### Example 1: Add a Custom Slash Command
**自动授予权限的工具：**
- REPL
- Artifacts
- Web Search/Fetch
- Conversation Search
- Input: user wants a repeatable `/review-pr` workflow.
- Steps:
1. Create or update `.claude/commands/review-pr.md` with scope, required inputs, and output format.
2. Reference repository review rules instead of duplicating stale policy text.
3. Test the command on a small diff and refine ambiguous steps.
- Expected output / acceptance: command is discoverable, deterministic, and does not bypass repo review constraints.
**需要授权的工具：**
- Bash (读/写文件系统)
- Edit (修改文件)
- Write (创建文件)
### Example 2: Diagnose a Permission Problem
### 项目上下文
- Input: Claude Code refuses to run or edit a file.
- Steps:
1. Identify whether the blocker is tool permission, filesystem sandbox, repository policy, or OS permissions.
2. Capture the exact path, command, and error.
3. Propose the least-permissive fix and a smoke test.
- Expected output / acceptance: user gets a concrete unblock path without granting broad unnecessary access.
Claude 自动识别：
- Git 仓库状态
- 编程语言（从文件扩展名）
- 项目结构
- 依赖配置
### Example 3: Summarize a Long Guide Section
### 内存系统
- Input: need the MCP section from `references/README.md`.
- Steps:
1. Use heading search to locate the section.
2. Read only the relevant slice.
3. Return a short operator checklist plus links back to the local reference file.
- Expected output / acceptance: answer is actionable and avoids dumping the full long document.
**对话内存：**
- 存储在当前会话
- 200K token 窗口
- 自动上下文管理
## References
**持久内存（实验性）：**
- 跨会话保存
- 用户偏好记忆
- 项目上下文保留
- `references/index.md`: structured navigation for the guide.
- `references/README.md`: long-form Claude Code Chinese guide.
## MCP 集成
## Maintenance
### 什么是 MCP？
Model Context Protocol - 连接 Claude 到外部系统的协议。
### MCP 服务器配置
配置文件：`~/.config/claude/mcp_config.json`
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["path/to/server.js"],
"env": {
"API_KEY": "your-key"
}
}
}
}
```
### 使用 MCP 工具
Claude 会自动发现 MCP 工具并在对话中使用：
```
"使用 my-server 工具获取数据"
```
## 钩子系统
### 钩子类型
在 `.claude/settings.json` 配置：
```json
{
"hooks": {
"tool-pre-use": "echo 'About to use tool'",
"tool-post-use": "echo 'Tool used'",
"user-prompt-submit": "echo 'Processing prompt'"
}
}
```
### 常见钩子用途
- 自动格式化代码
- 运行测试
- Git 提交检查
- 日志记录
- 通知发送
## 高级模式
### 多代理协作
使用 Task 工具启动子代理：
```
"启动一个专门的代理来优化这个算法"
```
子代理特点：
- 独立上下文
- 专注单一任务
- 返回结果到主代理
### 智能任务管理
使用 TodoWrite 工具：
```
"创建任务列表来跟踪这个项目"
```
任务状态：
- `pending` - 待处理
- `in_progress` - 进行中
- `completed` - 已完成
### 代码生成模式
**渐进式开发：**
1. 生成基础结构
2. 添加核心功能
3. 实现细节
4. 测试和优化
**验证驱动：**
1. 写测试用例
2. 实现功能
3. 运行测试
4. 修复问题
## 质量保证
### 自动化测试
```bash
# 运行测试
npm test
pytest
# 类型检查
mypy script.py
tsc --noEmit
# 代码检查
eslint src/
flake8 .
```
### 代码审查模式
使用子代理进行审查：
```
"启动代码审查代理检查这个文件"
```
审查重点：
- 代码质量
- 安全问题
- 性能优化
- 最佳实践
## 错误恢复
### 常见错误模式
1. **工具使用错误**
- 检查权限
- 验证语法
- 确认路径
2. **文件操作错误**
- 确认文件存在
- 检查读写权限
- 验证路径正确
3. **API 调用错误**
- 检查网络连接
- 验证 API 密钥
- 确认请求格式
### 渐进式修复策略
1. 隔离问题
2. 最小化复现
3. 逐步修复
4. 验证解决方案
## 最佳实践
### 开发原则
1. **清晰优先** - 明确需求和目标
2. **渐进实现** - 分步骤开发
3. **持续验证** - 频繁测试
4. **适当抽象** - 合理模块化
### 工具使用原则
1. **正确的工具** - 选择合适的工具
2. **工具组合** - 多工具协同
3. **权限最小化** - 只请求必要权限
4. **错误处理** - 优雅处理失败
### 性能优化
1. **批量操作** - 合并多个操作
2. **增量处理** - 处理大文件
3. **缓存结果** - 避免重复计算
4. **异步优先** - 使用 async/await
## 安全考虑
### 沙箱模型
每个工具在隔离环境中运行：
- REPL：无文件系统访问
- Bash：需要明确授权
- Web：仅特定域名
### 最佳安全实践
1. **最小权限** - 仅授予必要权限
2. **代码审查** - 检查生成的代码
3. **敏感数据** - 不要共享密钥
4. **定期审计** - 检查钩子和配置
## 故障排除
### 工具无法使用
**症状：** 工具调用失败
**解决方案：**
- 检查权限设置
- 验证语法正确
- 确认文件路径
- 查看错误消息
### REPL 性能问题
**症状：** REPL 执行缓慢
**解决方案：**
- 减少数据量
- 使用流式处理
- 优化算法
- 分批处理
### MCP 连接失败
**症状：** MCP 服务器无响应
**解决方案：**
- 检查配置文件
- 验证服务器运行
- 确认环境变量
- 查看服务器日志
## 实用示例
### 示例 1：数据分析
```javascript
// 在 REPL 中
const data = await window.fs.readFile('data.csv');
const parsed = Papa.parse(data, { header: true });
const values = parsed.data.map(row => parseFloat(row.value));
const avg = _.mean(values);
const std = math.std(values);
console.log(`平均值: ${avg}, 标准差: ${std}`);
```
### 示例 2：文件搜索
```bash
# 在 Bash 中
grep -r "TODO" src/
find . -name "*.py" -type f
```
### 示例 3：网络数据获取
```
"使用 web_fetch 获取 https://api.example.com/data 的内容，
然后在 REPL 中分析 JSON 数据"
```
## 参考文件
此技能包含详细文档：
- **README.md** (9,594 行) - 完整的 Claude Code 高级指南
包含以下主题：
- 核心工具深度解析
- REPL 高级协同模式
- 开发工作流详解
- MCP 集成完整指南
- 钩子系统配置
- 高级模式和最佳实践
- 故障排除和安全考虑
使用 `view` 命令查看参考文件获取详细信息。
## 资源
- **GitHub 仓库**: https://github.com/karminski/claude-code-guide-study
- **原始版本**: https://github.com/Cranot/claude-code-guide
- **Anthropic 官方文档**: https://docs.claude.com
## 注意事项
本指南结合了：
- 官方功能和公告
- 实际使用观察到的模式
- 概念性方法和最佳实践
- 第三方工具集成
请在使用时参考最新的官方文档。
---
**使用这个技能深入掌握 Claude Code 的强大功能！**
- Sources: local `references/README.md` and `references/index.md`.
- Last updated: 2026-04-28
- Known limits: Claude Code behavior can change; verify current CLI flags, hooks, and MCP details against official docs when precision matters.
assets/skills/claude-cookbooks/SKILL.md
+81 -267
View File
@@ -1,313 +1,127 @@
---
name: claude-cookbooks
description: Claude AI cookbooks - code examples, tutorials, and best practices for using Claude API. Use when learning Claude API integration, building Claude-powered applications, or exploring Claude capabilities.
description: "Claude cookbooks skill: Claude API examples for messages, tool use, vision, RAG, summarization, text-to-SQL, prompt caching, agents, multimodal workflows, and third-party integrations."
---
# Claude Cookbooks Skill
# claude-cookbooks Skill
Comprehensive code examples and guides for building with Claude AI, sourced from the official Anthropic cookbooks repository.
Use this skill to turn cookbook material into runnable Claude API integration patterns while keeping model/version assumptions explicit.
## When to Use This Skill
This skill should be triggered when:
- Learning how to use Claude API
- Implementing Claude integrations
- Building applications with Claude
- Working with tool use and function calling
- Implementing multimodal features (vision, image analysis)
- Setting up RAG (Retrieval Augmented Generation)
- Integrating Claude with third-party services
- Building AI agents with Claude
- Optimizing prompts for Claude
- Implementing advanced patterns (caching, sub-agents, etc.)
Trigger when any of these applies:
- Building applications that call the Claude API.
- Implementing tool use/function calling, structured outputs, RAG, summarization, classification, or text-to-SQL.
- Working with multimodal inputs such as images and document extraction.
- Exploring prompt caching, agents, sub-agent patterns, or third-party integrations.
- Looking up cookbook examples stored in `references/` and adapting them to a project.
## Not For / Boundaries
- Not the source of truth for latest Anthropic models, pricing, limits, or API changes; verify current API details with official docs when exact current behavior matters.
- Do not hard-code API keys or leak prompts containing private user data.
- Cookbook examples are starting points, not production architecture; add retries, timeouts, observability, evals, and security checks.
- Required inputs: language/runtime, use case, model policy from the project, data sensitivity, expected output schema, and failure handling requirements.
- If local references conflict with current official docs, prefer the official docs and update the reference notes.
## Quick Reference
### Basic API Usage
### Common Patterns
**Basic Messages API shape**
```python
import anthropic
client = anthropic.Anthropic(api_key="your-api-key")
# Simple message
client = anthropic.Anthropic(api_key="YOUR_API_KEY")
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
model="YOUR_APPROVED_MODEL",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Hello, Claude!"
}]
messages=[{"role": "user", "content": "Hello"}],
)
```
### Tool Use (Function Calling)
**Tool definition shape**
```python
# Define a tool
tools = [{
"name": "get_weather",
"description": "Get current weather for a location",
"description": "Get current weather for a location.",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
}]
# Use the tool
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in San Francisco?"}]
)
```
### Vision (Image Analysis)
**Vision content shape**
```python
# Analyze an image
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": base64_image
}
},
{"type": "text", "text": "Describe this image"}
]
}]
)
content = [
{"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": base64_image}},
{"type": "text", "text": "Describe the image."},
]
```
### Prompt Caching
**Prompt caching shape**
```python
# Use prompt caching for efficiency
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
system=[{
"type": "text",
"text": "Large system prompt here...",
"cache_control": {"type": "ephemeral"}
}],
messages=[{"role": "user", "content": "Your question"}]
)
system = [{
"type": "text",
"text": "Large stable system prompt...",
"cache_control": {"type": "ephemeral"},
}]
```
## Key Capabilities Covered
**RAG pipeline skeleton**
```text
ingest -> chunk -> embed/index -> retrieve -> rerank/filter -> answer with citations -> evaluate
```
### 1. Classification
- Text classification techniques
- Sentiment analysis
- Content categorization
- Multi-label classification
**Production hardening checklist**
```text
timeouts, retries, redaction, structured logging, eval set, cost guard, rate-limit handling
```
### 2. Retrieval Augmented Generation (RAG)
- Vector database integration
- Semantic search
- Context retrieval
- Knowledge base queries
## Examples
### 3. Summarization
- Document summarization
- Meeting notes
- Article condensing
- Multi-document synthesis
### Example 1: Add Tool Use to an App
### 4. Text-to-SQL
- Natural language to SQL queries
- Database schema understanding
- Query optimization
- Result interpretation
- Input: user asks for weather lookup through Claude.
- Steps:
1. Define a JSON schema for `get_weather`.
2. Send the user request with the tool definition.
3. Execute only validated tool calls and return tool results to the model.
- Expected output / acceptance: tool arguments pass schema validation and no unapproved function is called.
### 5. Tool Use & Function Calling
- Tool definition and schema
- Parameter validation
- Multi-tool workflows
- Error handling
### Example 2: Build a RAG Answerer
### 6. Multimodal
- Image analysis and OCR
- Chart/graph interpretation
- Visual question answering
- Image generation integration
- Input: local product docs and user questions.
- Steps:
1. Chunk and index documents with stable IDs.
2. Retrieve relevant chunks for each question.
3. Ask Claude to answer only from retrieved evidence and cite chunk IDs.
- Expected output / acceptance: unsupported claims are refused or marked unknown, and answers include source references.
### 7. Advanced Patterns
- Agent architectures
- Sub-agent delegation
- Prompt optimization
- Cost optimization with caching
### Example 3: Vision Extraction
## Repository Structure
- Input: screenshot or document image.
- Steps:
1. Convert image to supported media type and base64.
2. Send image plus extraction instructions.
3. Validate returned fields against the expected schema.
- Expected output / acceptance: extracted data is structured, missing fields are explicit, and raw sensitive images are not logged.
The cookbooks are organized into these main categories:
## References
- **capabilities/** - Core AI capabilities (classification, RAG, summarization, text-to-SQL)
- **tool_use/** - Function calling and tool integration examples
- **multimodal/** - Vision and image-related examples
- **patterns/** - Advanced patterns like agents and workflows
- **third_party/** - Integrations with external services (Pinecone, LlamaIndex, etc.)
- **claude_agent_sdk/** - Agent SDK examples and templates
- **misc/** - Additional utilities (PDF upload, JSON mode, evaluations, etc.)
- `references/index.md`: navigation for cookbook topics.
- `references/main_readme.md` and `references/README.md`: upstream overview material.
- `references/tool_use.md`: tool-use examples.
- `references/capabilities.md`: classification, RAG, summarization, and text-to-SQL.
- `references/multimodal.md`: image and multimodal examples.
- `references/patterns.md`: agents, caching, and advanced patterns.
- `references/third_party.md`: vector DB and external integrations.
- `scripts/memory_tool.py`: local helper script retained from the cookbook material.
## Reference Files
## Maintenance
This skill includes comprehensive documentation in `references/`:
- **main_readme.md** - Main repository overview
- **capabilities.md** - Core capabilities documentation
- **tool_use.md** - Tool use and function calling guides
- **multimodal.md** - Vision and multimodal capabilities
- **third_party.md** - Third-party integrations
- **patterns.md** - Advanced patterns and agents
- **index.md** - Complete reference index
## Common Use Cases
### Building a Customer Service Agent
1. Define tools for CRM access, ticket creation, knowledge base search
2. Use tool use API to handle function calls
3. Implement conversation memory
4. Add fallback mechanisms
See: `references/tool_use.md#customer-service`
### Implementing RAG
1. Create embeddings of your documents
2. Store in vector database (Pinecone, etc.)
3. Retrieve relevant context on query
4. Augment Claude's response with context
See: `references/capabilities.md#rag`
### Processing Documents with Vision
1. Convert document to images or PDF
2. Use vision API to extract content
3. Structure the extracted data
4. Validate and post-process
See: `references/multimodal.md#vision`
### Building Multi-Agent Systems
1. Define specialized agents for different tasks
2. Implement routing logic
3. Use sub-agents for delegation
4. Aggregate results
See: `references/patterns.md#agents`
## Best Practices
### API Usage
- Use appropriate model for task (Sonnet for balance, Haiku for speed, Opus for complex tasks)
- Implement retry logic with exponential backoff
- Handle rate limits gracefully
- Monitor token usage for cost optimization
### Prompt Engineering
- Be specific and clear in instructions
- Provide examples when needed
- Use system prompts for consistent behavior
- Structure outputs with JSON mode when needed
### Tool Use
- Define clear, specific tool schemas
- Validate inputs and outputs
- Handle errors gracefully
- Keep tool descriptions concise but informative
### Multimodal
- Use high-quality images (higher resolution = better results)
- Be specific about what to extract/analyze
- Respect size limits (5MB per image)
- Use appropriate image formats (JPEG, PNG, GIF, WebP)
## Performance Optimization
### Prompt Caching
- Cache large system prompts
- Cache frequently used context
- Monitor cache hit rates
- Balance caching vs. fresh content
### Cost Optimization
- Use Haiku for simple tasks
- Implement prompt caching for repeated context
- Set appropriate max_tokens
- Batch similar requests
### Latency Optimization
- Use streaming for long responses
- Minimize message history
- Optimize image sizes
- Use appropriate timeout values
## Resources
### Official Documentation
- [Anthropic Developer Docs](https://docs.claude.com)
- [API Reference](https://docs.claude.com/claude/reference)
- [Anthropic Support](https://support.anthropic.com)
### Community
- [Anthropic Discord](https://www.anthropic.com/discord)
- [GitHub Cookbooks Repo](https://github.com/anthropics/claude-cookbooks)
### Learning Resources
- [Claude API Fundamentals Course](https://github.com/anthropics/courses/tree/master/anthropic_api_fundamentals)
- [Prompt Engineering Guide](https://docs.claude.com/claude/docs/guide-to-anthropics-prompt-engineering-resources)
## Working with This Skill
### For Beginners
Start with `references/main_readme.md` and explore basic examples in `references/capabilities.md`
### For Specific Features
- Tool use → `references/tool_use.md`
- Vision → `references/multimodal.md`
- RAG → `references/capabilities.md#rag`
- Agents → `references/patterns.md#agents`
### For Code Examples
Each reference file contains practical, copy-pasteable code examples
## Examples Available
The cookbook includes 50+ practical examples including:
- Customer service chatbot with tool use
- RAG with Pinecone vector database
- Document summarization
- Image analysis and OCR
- Chart/graph interpretation
- Natural language to SQL
- Content moderation filter
- Automated evaluations
- Multi-agent systems
- Prompt caching optimization
## Notes
- All examples use official Anthropic Python SDK
- Code is production-ready with error handling
- Examples follow current API best practices
- Regular updates from Anthropic team
- Community contributions welcome
## Skill Source
This skill was created from the official Anthropic Claude Cookbooks repository:
https://github.com/anthropics/claude-cookbooks
Repository cloned and processed on: 2025-10-29
- Sources: local `references/` extracted from Anthropic cookbook material.
- Last updated: 2026-04-28
- Known limits: examples may carry older model names; replace with the project-approved current model before use.
assets/skills/coingecko/SKILL.md
+87 -51
View File
@@ -1,80 +1,116 @@
---
name: coingecko
description: CoinGecko API documentation - cryptocurrency market data API, price feeds, market cap, volume, historical data. Use when integrating CoinGecko API, building crypto price trackers, or accessing cryptocurrency market data.
description: "CoinGecko API skill: cryptocurrency prices, market data, coin IDs, historical charts, trending search, onchain endpoints, API-key authentication, and rate-limit-aware request design."
---
# Coingecko Skill
# coingecko Skill
Comprehensive assistance with coingecko development, generated from official documentation.
Use this skill to integrate CoinGecko market data into applications, agents, dashboards, and analysis pipelines with clear API-key and rate-limit handling.
## When to Use This Skill
This skill should be triggered when:
- Working with coingecko
- Asking about coingecko features or APIs
- Implementing coingecko solutions
- Debugging coingecko code
- Learning coingecko best practices
Trigger when any of these applies:
- Querying token prices, market cap, volume, historical charts, trending coins, NFTs, categories, or exchange data from CoinGecko.
- Choosing Demo API vs Pro API root URLs and authentication headers.
- Designing rate-limit-aware polling, cache refresh, or price freshness checks.
- Building crypto dashboards, price alerts, analytics jobs, or market-data enrichers.
- Navigating CoinGecko MCP, REST, or onchain/GeckoTerminal reference material.
## Not For / Boundaries
- Not financial advice, token endorsement, trade execution, or market manipulation support.
- Do not expose API keys in query strings unless unavoidable; prefer headers and backend proxy insertion.
- Do not assume symbol uniqueness; resolve assets with CoinGecko coin IDs before price calls.
- Required inputs: plan type, root URL, API key availability, coin IDs/symbols/contracts, quote currencies, date range, and freshness requirements.
- CoinGecko endpoints and plan gates evolve; verify paid-only endpoints and rate limits in `references/` before production use.
## Quick Reference
### Common Patterns
*Quick reference patterns will be added as you use the skill.*
**Demo API ping with header auth**
```bash
curl -X GET "https://api.coingecko.com/api/v3/ping" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
## Reference Files
**Pro API ping with header auth**
```bash
curl -X GET "https://pro-api.coingecko.com/api/v3/ping" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
This skill includes comprehensive documentation in `references/`:
**Simple price for coin IDs**
```bash
curl "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd"
```
- **authentication.md** - Authentication documentation
- **coins.md** - Coins documentation
- **contract.md** - Contract documentation
- **exchanges.md** - Exchanges documentation
- **introduction.md** - Introduction documentation
- **market_data.md** - Market Data documentation
- **nfts.md** - Nfts documentation
- **other.md** - Other documentation
- **pricing.md** - Pricing documentation
- **reference.md** - Reference documentation
- **trending.md** - Trending documentation
**Include freshness fields in price response**
```bash
curl "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd&include_last_updated_at=true"
```
Use `view` to read specific reference files when detailed information is needed.
**Market list by market cap**
```bash
curl "https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=100&page=1"
```
## Working with This Skill
**Historical chart by coin ID**
```bash
curl "https://api.coingecko.com/api/v3/coins/bitcoin/market_chart?vs_currency=usd&days=30"
```
### For Beginners
Start with the getting_started or tutorials reference files for foundational concepts.
**Trending search**
```bash
curl "https://api.coingecko.com/api/v3/search/trending"
```
### For Specific Features
Use the appropriate category reference file (api, guides, etc.) for detailed information.
**Onchain trending pools**
```bash
curl "https://api.coingecko.com/api/v3/onchain/networks/trending_pools"
```
### For Code Examples
The quick reference section above contains common patterns extracted from the official docs.
## Examples
## Resources
### Example 1: Price Widget
### references/
Organized documentation extracted from official sources. These files contain:
- Detailed explanations
- Code examples with language annotations
- Links to original documentation
- Table of contents for quick navigation
- Input: coin IDs `bitcoin,ethereum`, quote `usd`, refresh interval.
- Steps:
1. Use `/simple/price` with `include_last_updated_at=true`.
2. Cache responses according to product freshness needs and plan limits.
3. Display stale-data warnings when `last_updated_at` is outside the allowed window.
- Expected output / acceptance: a small response with current prices and explicit freshness handling.
### scripts/
Add helper scripts here for common automation tasks.
### Example 2: Market-Cap Dashboard
### assets/
Add templates, boilerplate, or example projects here.
- Input: quote currency `usd`, `per_page=100`, page number.
- Steps:
1. Query `/coins/markets`.
2. Persist coin ID, symbol, name, price, market cap, and volume.
3. Avoid treating symbols as primary keys because duplicates exist.
- Expected output / acceptance: stable dashboard rows keyed by CoinGecko ID.
## Notes
### Example 3: Trending Research Batch
- This skill was automatically generated from official documentation
- Reference files preserve the structure and examples from source docs
- Code examples include language detection for better syntax highlighting
- Quick reference patterns are extracted from common usage examples in the docs
- Input: need trending coins, NFTs, and categories in the last 24 hours.
- Steps:
1. Query `/search/trending`.
2. Normalize returned entities by type.
3. For coins that require prices, follow up with `/simple/price` using IDs.
- Expected output / acceptance: a typed trending list with price enrichment only where IDs are available.
## Updating
## References
To refresh this skill with updated documentation:
1. Re-run the scraper with the same configuration
2. The skill will be rebuilt with the latest information
- `references/index.md`: navigation for local CoinGecko docs.
- `references/authentication.md`: Demo/Pro API keys, root URLs, and header names.
- `references/coins.md`: coin IDs, markets, charts, simple price, and trending search.
- `references/market_data.md`: NFT market data notes.
- `references/exchanges.md`: exchange endpoints.
- `references/trending.md`: onchain trending pool endpoints.
- `references/llms.md` and `references/llms-full.md`: LLM-oriented reference exports.
## Maintenance
- Sources: local `references/` extracted from CoinGecko documentation.
- Last updated: 2026-04-28
- Known limits: plan availability and rate limits are account-specific; verify against the active CoinGecko plan before shipping.
assets/skills/cryptofeed/SKILL.md
+75 -177
View File
@@ -1,221 +1,119 @@
---
name: cryptofeed
description: Cryptofeed - Real-time cryptocurrency market data feeds from 40+ exchanges. WebSocket streaming, normalized data, order books, trades, tickers. Python library for algorithmic trading and market data analysis.
description: "Cryptofeed real-time crypto market data skill: WebSocket feeds, normalized tickers/trades/order books, NBBO, exchange subscriptions, authenticated channels, and backend streaming to Redis/Kafka/PostgreSQL."
---
# Cryptofeed Skill
# cryptofeed Skill
Comprehensive assistance with Cryptofeed development - a Python library for handling cryptocurrency exchange data feeds with normalized and standardized results.
Use this skill to build Python market-data pipelines with Cryptofeed across exchanges, channels, callbacks, NBBO aggregation, and storage backends.
## When to Use This Skill
This skill should be triggered when:
- Working with real-time cryptocurrency market data
- Implementing WebSocket streaming from crypto exchanges
- Building algorithmic trading systems
- Processing order book updates, trades, or ticker data
- Connecting to 40+ cryptocurrency exchanges
- Using normalized exchange APIs
- Implementing market data backends (Redis, MongoDB, Kafka, etc.)
Trigger when any of these applies:
- Streaming real-time crypto market data from multiple exchanges.
- Subscribing to tickers, trades, L1/L2/L3 order books, candles, funding, liquidations, balances, fills, or order updates.
- Building NBBO, arbitrage monitors, market-data recorders, or backend writers.
- Debugging symbol/channel support, callback shape, reconnection behavior, or backend configuration.
- Comparing Cryptofeed with exchange-specific WebSocket clients.
## Not For / Boundaries
- Not a trading strategy engine, order execution system, or persistence database by itself.
- Authenticated channels require exchange credentials; never commit or print secrets.
- Exchange support, symbols, and channel names vary; confirm against the exchange class and `references/README.md`.
- Required inputs: exchange list, symbols, channels, callback/backend target, auth need, and failure mode.
- For historical backfills, pair this with REST or a storage system; Cryptofeed is WebSocket-first.
## Quick Reference
### Installation
### Common Patterns
```python
# Basic installation
**Install Cryptofeed**
```bash
pip install cryptofeed
# With all optional backends
pip install cryptofeed[all]
```
### Basic Usage Pattern
**Create a simple feed handler**
```python
from cryptofeed import FeedHandler
from cryptofeed.exchanges import Coinbase, Bitfinex
from cryptofeed.defines import TICKER, TRADES, L2_BOOK
from cryptofeed.defines import TICKER
from cryptofeed.exchanges import Coinbase
# Define callbacks
def ticker_callback(data):
print(f"Ticker: {data}")
def ticker(data, receipt_timestamp):
print(data)
def trade_callback(data):
print(f"Trade: {data}")
# Create feed handler
fh = FeedHandler()
# Add exchange feeds
fh.add_feed(Coinbase(
symbols=['BTC-USD'],
channels=[TICKER],
callbacks={TICKER: ticker_callback}
))
fh.add_feed(Bitfinex(
symbols=['BTC-USD'],
channels=[TRADES],
callbacks={TRADES: trade_callback}
))
# Start receiving data
fh.add_feed(Coinbase(symbols=["BTC-USD"], channels=[TICKER], callbacks={TICKER: ticker}))
fh.run()
```
### National Best Bid/Offer (NBBO)
**Subscribe to trades and L2 book**
```python
from cryptofeed.defines import TRADES, L2_BOOK
from cryptofeed.exchanges import Gemini
fh.add_feed(Gemini(
symbols=["BTC-USD", "ETH-USD"],
channels=[TRADES, L2_BOOK],
callbacks={TRADES: trade_callback, L2_BOOK: book_callback},
))
```
**Build NBBO across exchanges**
```python
from cryptofeed import FeedHandler
from cryptofeed.exchanges import Coinbase, Gemini, Kraken
def nbbo_update(symbol, bid, bid_size, ask, ask_size, bid_feed, ask_feed):
print(f'Pair: {symbol} Bid: {bid:.2f} ({bid_size:.6f}) from {bid_feed}')
print(f'Ask: {ask:.2f} ({ask_size:.6f}) from {ask_feed}')
f = FeedHandler()
f.add_nbbo([Coinbase, Kraken, Gemini], ['BTC-USD'], nbbo_update)
f.run()
fh.add_nbbo([Coinbase, Kraken, Gemini], ["BTC-USD"], nbbo_callback)
```
## Supported Exchanges (40+)
### Major Exchanges
- **Binance** (Spot, Futures, Delivery, US)
- **Coinbase**, **Kraken** (Spot, Futures), **Bitfinex**
- **Gemini**, **OKX**, **Bybit**
- **Huobi** (Spot, DM, Swap), **Gate.io** (Spot, Futures)
- **KuCoin**, **Deribit**, **BitMEX**, **dYdX**
### Additional Exchanges
AscendEX, Bequant, bitFlyer, Bithumb, Bitstamp, Blockchain.com, Bit.com, Bitget, Crypto.com, Delta, EXX, FMFW.io, HitBTC, Independent Reserve, OKCoin, Phemex, Poloniex, ProBit, Upbit
## Supported Data Channels
### Market Data (Public)
- **L1_BOOK** - Top of order book
- **L2_BOOK** - Price aggregated sizes
- **L3_BOOK** - Price aggregated orders
- **TRADES** - Executed trades (taker side)
- **TICKER** - Price ticker updates
- **FUNDING** - Funding rate data
- **OPEN_INTEREST** - Open interest statistics
- **LIQUIDATIONS** - Liquidation events
- **INDEX** - Index price data
- **CANDLES** - Candlestick/K-line data
### Authenticated Channels (Private)
- **ORDER_INFO** - Order status updates
- **TRANSACTIONS** - Deposits and withdrawals
- **BALANCES** - Wallet balance updates
- **FILLS** - User's executed trades
## Supported Backends
Write data directly to storage:
- **Redis** (Streams and Sorted Sets)
- **Arctic** - Time-series database
- **ZeroMQ**, **InfluxDB v2**, **MongoDB**
- **Kafka**, **RabbitMQ**, **PostgreSQL**
- **QuasarDB**, **GCP Pub/Sub**, **QuestDB**
- **UDP/TCP/Unix Sockets**
## Key Features
### Real-time Data Normalization
Cryptofeed normalizes data across all exchanges, providing consistent:
- Symbol formatting
- Timestamp handling
- Data structures
- Channel names
### WebSocket + REST Fallback
- Primarily uses WebSockets for real-time data
- Falls back to REST polling when WebSocket unavailable
- Automatic reconnection handling
### NBBO Aggregation
Create synthetic National Best Bid/Offer feeds by aggregating data across multiple exchanges to find arbitrage opportunities.
### Backend Integration
Direct data writing to various storage systems without custom integration code.
## Requirements
- **Python**: 3.8 or higher
- **Installation**: Via pip or from source
- **Optional Dependencies**: Install backends as needed
## Common Use Cases
### Multi-Exchange Price Monitoring
**Separate callback work from IO-heavy persistence**
```python
fh = FeedHandler()
fh.add_feed(Binance(symbols=['BTC-USDT'], channels=[TICKER], callbacks=ticker_cb))
fh.add_feed(Coinbase(symbols=['BTC-USD'], channels=[TICKER], callbacks=ticker_cb))
fh.add_feed(Kraken(symbols=['BTC-USD'], channels=[TICKER], callbacks=ticker_cb))
fh.run()
def trade_callback(data, receipt_timestamp):
queue.put_nowait((data, receipt_timestamp))
```
### Order Book Depth Analysis
**Check supported channel names**
```python
def book_callback(book, receipt_timestamp):
print(f"Bids: {len(book.book.bids)} | Asks: {len(book.book.asks)}")
fh.add_feed(Coinbase(
symbols=['BTC-USD'],
channels=[L2_BOOK],
callbacks={L2_BOOK: book_callback}
))
from cryptofeed.defines import L1_BOOK, L2_BOOK, L3_BOOK, TRADES, TICKER
```
### Trade Flow Analysis
```python
def trade_callback(trade, receipt_timestamp):
print(f"{trade.exchange} - {trade.symbol}: {trade.side} {trade.amount} @ {trade.price}")
## Examples
fh.add_feed(Binance(
symbols=['BTC-USDT', 'ETH-USDT'],
channels=[TRADES],
callbacks={TRADES: trade_callback}
))
```
### Example 1: Single-Exchange Ticker Stream
## Reference Files
- Input: exchange `Coinbase`, symbol `BTC-USD`, channel `TICKER`.
- Steps:
1. Create `FeedHandler`.
2. Add one exchange feed with a lightweight callback.
3. Run the handler and observe normalized ticker objects.
- Expected output / acceptance: ticker updates print with timestamps and no callback-blocking persistence work.
This skill includes documentation in `references/`:
### Example 2: NBBO Monitor
- **getting_started.md** - Installation and basic usage
- **README.md** - Complete overview and examples
- Input: exchanges `Coinbase`, `Kraken`, `Gemini`, symbol `BTC-USD`.
- Steps:
1. Define `nbbo_callback(symbol, bid, bid_size, ask, ask_size, bid_feed, ask_feed)`.
2. Add NBBO with the exchange class list.
3. Alert only when spread or venue changes cross configured thresholds.
- Expected output / acceptance: best bid/ask updates include source venues.
Use `view` to read specific reference files when detailed information is needed.
### Example 3: Backend Recorder
## Working with This Skill
- Input: symbols, channels, and a storage backend such as Redis/Kafka/PostgreSQL.
- Steps:
1. Confirm optional backend dependencies are installed.
2. Configure the backend callback instead of writing inside a custom callback.
3. Run a small symbol set before scaling to many exchanges.
- Expected output / acceptance: records arrive in the backend with normalized exchange and symbol fields.
### For Beginners
Start with basic FeedHandler setup and single exchange connections before adding multiple feeds.
## References
### For Advanced Users
Explore NBBO feeds, authenticated channels, and backend integrations for production systems.
- `references/index.md`: navigation for the local Cryptofeed references.
- `references/README.md`: supported exchanges, basic usage, NBBO, channels, and backends.
- `references/other.md`: additional generated reference material.
### For Code Examples
See the quick reference section above and the reference files for complete working examples.
## Maintenance
## Resources
- **Repository**: https://github.com/bmoscon/cryptofeed
- **PyPI**: https://pypi.python.org/pypi/cryptofeed
- **Examples**: https://github.com/bmoscon/cryptofeed/tree/master/examples
- **Documentation**: https://github.com/bmoscon/cryptofeed/blob/master/docs/README.md
- **Discord**: https://discord.gg/zaBYaGAYfR
- **Related**: Cryptostore (containerized data storage)
## Notes
- Requires Python 3.8+
- WebSocket-first approach with REST fallback
- Normalized data across all exchanges
- Active development and community support
- 40+ supported exchanges and growing
- Sources: local `references/` extracted from Cryptofeed documentation.
- Last updated: 2026-04-28
- Known limits: channel support is exchange-specific; always validate symbol naming and callback signatures against the installed version.
assets/skills/ddd-doc-steward/SKILL.md
+18 -9
View File
@@ -1,3 +1,4 @@
---
name: ddd-doc-steward
description: "文档驱动开发（DDD）文档管家：以仓库真实证据为准，盘点 ~/project 与 docs 目录，生成/更新 SSOT 文档（计划→补丁/全文→摘要→一致性检查）。触发：需要让文档与代码/配置/运行方式同步、补齐 guides/integrations/features/architecture/incidents/archive、无法推导时标注【待确认】并给验证路径。"
---
@@ -6,21 +7,21 @@ description: "文档驱动开发（DDD）文档管家：以仓库真实证据为
让 `~/project/docs` 成为单一可信来源（SSOT）：先盘点、后计划、再增量写文档，所有事实有证据来源，没有证据就【待确认】。
## 何时使用
## When to Use This Skill
- 需要为真实仓库建立/维护文档 SSOT，输出「盘点表 → 计划 → 文档补丁/全文 → 变更摘要 → 一致性检查」的固定交付物。
- 新增/改动功能、集成或事故复盘，需要同步更新 docs 下对应目录。
- 需要在 strict 模式下，避免任何臆测，所有关键事实必须给出代码/配置/命令的路径或说明验证方法。
- 只能获取部分信息时，仍需生成最小可落地模板并标注【待确认】。
## 不适用 / 边界
## Not For / Boundaries
- 与工程无关的纯创作文案。
- 无法提供最小证据集（目录树、README/依赖/配置/路由位置）且不接受【待确认】输出时。
- 涉及密钥明文输出；文档中仅可写占位符与获取方式。
- 未提供 `project_root/docs_root/output_mode` 等输入时，先将自然语言归一到输入 JSON（参见快速参考）。
## 快速参考
## Quick Reference
1) 归一化输入（缺省值）
```json
@@ -68,19 +69,19 @@ description: "文档驱动开发（DDD）文档管家：以仓库真实证据为
- SHOULD：优先用 git diff/related_paths 聚焦；guides 与 integrations 先行；为每个【待确认】提供验证路径。
- NEVER：编造端口/环境变量/接口字段；输出密钥明文；跳过盘点直接写文档。
## 示例
## Examples
### 示例 1：空仓库初始化
### Example 1: 空仓库初始化
- 输入：`change_type=baseline`，docs 为空。
- 步骤：A 扫描→B 盘点表标记全部缺失→计划新增 docs/README.md、guides/getting-started.md 等→C 生成骨架补丁→D 摘要与检查。
- 验收：输出 patch diff，所有命令标【待确认】或给寻找路径。
### 示例 2：新增登录功能
### Example 2: 新增登录功能
- 输入：`change_type=feature`，`scope_hint="auth 登录"`，`use_git_diff=true`。
- 步骤：用 diff 找受影响路由；盘点 features/integrations；计划新增 PRD/Spec，更新 integrations/auth-api；标记 token 过期时间待确认。
- 验收：变更摘要指出新增文档与更新字段；检查清单含鉴权/错误码/验证 curl。
### 示例 3：无法读取仓库
### Example 3: 无法读取仓库
- 输入：仅自然语言“帮我做 SSOT 文档”。
- 步骤：先归一化 JSON，声明“无法真实扫描”→生成六类文档模板，全量标【待确认】并列证据缺口与采集命令。
- 验收：输出 full_files；每条待确认可直接行动补证。
@@ -92,10 +93,18 @@ description: "文档驱动开发（DDD）文档管家：以仓库真实证据为
- Q: 目录过大处理不过来？
A: 按 prefer_priority 分批；声明本次范围与剩余批次计划。
## 维护
## References
- `references/index.md`：导航与长文入口。
- `references/getting_started.md`：DDD 文档管家流程与术语。
- `references/api.md`：输入/输出规范、目录命名与质量门禁。
- `references/examples.md`：可套用场景示例。
- `references/troubleshooting.md`：降级与故障处理。
## Maintenance
- 来源：提示词库（在线表格入口见 `assets/prompt/README.md`）；元技能 `assets/skills/auto-skill/`；自动化辅助工具 `assets/repos/Skill_Seekers-development`.
- 最后更新：2025-12-20
- 最后更新：2026-04-28
- 已知限制：依赖用户提供真实证据；大体量仓库需分批；不输出敏感值。
## 质量门禁（出厂前自检）
assets/skills/hummingbot/SKILL.md
+96 -93
View File
@@ -1,133 +1,136 @@
---
name: hummingbot
description: Hummingbot trading bot framework - automated trading strategies, market making, arbitrage, connectors for crypto exchanges. Use when working with algorithmic trading, crypto trading bots, or exchange integrations.
description: "Hummingbot trading bot framework skill: connector setup, scripts, market making, arbitrage, Gateway DEX operations, headless quickstart, candles, market data provider, and troubleshooting for crypto trading bots."
---
# Hummingbot Skill
# hummingbot Skill
Comprehensive assistance with hummingbot development, generated from official documentation.
Use this skill to operate, configure, or extend Hummingbot bots and Gateway connectors with explicit risk controls and version-aware references.
## When to Use This Skill
This skill should be triggered when:
- Working with hummingbot
- Asking about hummingbot features or APIs
- Implementing hummingbot solutions
- Debugging hummingbot code
- Learning hummingbot best practices
Trigger when any of these applies:
- Running Hummingbot strategies, scripts, or headless bot instances.
- Configuring CEX/DEX connectors, API keys, Gateway routes, or blockchain RPC providers.
- Building market-making, arbitrage, liquidity, or custom script strategies.
- Using candles, order book snapshots, mid-price, volume-for-price, or market data provider APIs.
- Debugging connector failures, Docker/runtime issues, Gateway command errors, or strategy config problems.
## Not For / Boundaries
- Not financial advice, profitability guarantees, or unattended live-trading approval.
- Never paste real exchange API keys, private keys, mnemonics, or wallet secrets into prompts, examples, logs, or commits.
- Use paper/sandbox/small-size validation before live capital; many connectors have exchange-specific limits and failure modes.
- Required inputs: Hummingbot version, install mode, connector, trading pair, strategy/script, config file, live/paper mode, and exact logs.
- Gateway and connector schemas evolve; verify against `references/` and the running version before production deployment.
## Quick Reference
### Common Patterns
**Pattern 1:** For example: candles = [CandlesFactory.get_candle(connector=kucoin, trading_pair="ETH-USDT", interval="1m", max_records=100)]
```
candles = [CandlesFactory.get_candle(connector=kucoin,
trading_pair="ETH-USDT", interval="1m", max_records=100)]
**Run a headless quickstart**
```bash
bin/hummingbot_quickstart.py --headless -p PASSWORD -f CONFIG_FILE_NAME
```
**Pattern 2:** Example:
```
bin/hummingbot_quickstart.py -p a -f simple_pmm_example_config.py -c conf_simple_pmm_example_config_1.yml
**Run a script config**
```bash
bin/hummingbot_quickstart.py -p PASSWORD -f simple_pmm_example_config.py -c conf_simple_pmm_example_config_1.yml
```
**Pattern 3:** >>> gateway swap --help usage: gateway swap [-h] [connector] [args ...] positional arguments: connector Connector name/type (e.g., jupiter/router) args Arguments: [base-quote] [side] [amount] options: -h, --help show this help message and exit
```
>>> gateway swap --help
usage: gateway swap [-h] [connector] [args ...]
positional arguments:
connector Connector name/type (e.g., jupiter/router)
args Arguments: [base-quote] [side] [amount]
options:
-h, --help show this help message and exit
**List Gateway connectors**
```text
gateway list
```
**Pattern 4:** usage: gateway list [-h]
```
usage: gateway list [-h]
**Inspect Gateway swap syntax**
```text
gateway swap --help
```
**Pattern 5:** Example:
```
price = self.market_data_provider.get_price_by_type('binance', 'BTC-USDT', PriceType.MidPrice)
**Get a mid price from the market data provider**
```python
price = self.market_data_provider.get_price_by_type(
"binance",
"BTC-USDT",
PriceType.MidPrice,
)
```
**Pattern 6:** Example:
```
price = self.market_data_provider.get_price_by_volume('binance', 'BTC-USDT', volume: 10000, True)
**Get price by quote volume**
```python
price = self.market_data_provider.get_price_by_volume(
"binance",
"BTC-USDT",
10000,
True,
)
```
**Pattern 7:** Example:
```
price = self.market_data_provider.get_volume_for_price('binance', 'BTC-USDT', 70000, True)
**Get an order book snapshot**
```python
snapshot = self.market_data_provider.get_order_book_snapshot("binance", "BTC-USDT")
```
**Pattern 8:** Example:
```
price = self.market_data_provider.get_order_book_snapshot('binance', 'BTC-USDT')
**Create a candle feed**
```python
candles = CandlesFactory.get_candle(
connector="kucoin",
trading_pair="ETH-USDT",
interval="1m",
max_records=100,
)
```
## Reference Files
**Update Docker deployment images**
```bash
docker compose down
docker pull hummingbot/hummingbot:latest
docker compose up -d
```
This skill includes comprehensive documentation in `references/`:
## Examples
- **advanced.md** - Advanced documentation
- **configuration.md** - Configuration documentation
- **connectors.md** - Connectors documentation
- **development.md** - Development documentation
- **getting_started.md** - Getting Started documentation
- **other.md** - Other documentation
- **strategies.md** - Strategies documentation
- **trading.md** - Trading documentation
- **troubleshooting.md** - Troubleshooting documentation
### Example 1: Headless Bot Smoke Test
Use `view` to read specific reference files when detailed information is needed.
- Input: password, strategy config file, optional script config.
- Steps:
1. Start with `bin/hummingbot_quickstart.py --headless`.
2. Confirm logs show connector initialization and strategy start.
3. Stop the bot and inspect final status before enabling live size.
- Expected output / acceptance: the bot starts from config without interactive prompts and exits cleanly.
## Working with This Skill
### Example 2: Gateway Connector Triage
### For Beginners
Start with the getting_started or tutorials reference files for foundational concepts.
- Input: failing Gateway command and connector name.
- Steps:
1. Run `gateway list` to verify connector availability.
2. Run `gateway swap --help` or the specific command help.
3. Compare arguments with the connector/network schema in `references/trading.md`.
- Expected output / acceptance: failure is classified as missing connector, bad args, RPC/network issue, or credential/config issue.
### For Specific Features
Use the appropriate category reference file (api, guides, etc.) for detailed information.
### Example 3: Strategy Market Data Hook
### For Code Examples
The quick reference section above contains common patterns extracted from the official docs.
- Input: connector `binance`, pair `BTC-USDT`, needed price type.
- Steps:
1. Use `market_data_provider` for mid price or volume-aware price.
2. Keep API calls outside tight loops when cached data is sufficient.
3. Log connector/pair/price source for later debugging.
- Expected output / acceptance: strategy reads a deterministic price source without blocking order logic.
## Resources
## References
### references/
Organized documentation extracted from official sources. These files contain:
- Detailed explanations
- Code examples with language annotations
- Links to original documentation
- Table of contents for quick navigation
- `references/index.md`: navigation for local Hummingbot references.
- `references/getting_started.md`: install and first-run material.
- `references/configuration.md`: bot and connector configuration.
- `references/connectors.md`: exchange connector catalog and notes.
- `references/strategies.md`: strategy and script material.
- `references/trading.md`: Gateway and trading operations.
- `references/development.md`: development, headless, and release-related notes.
- `references/troubleshooting.md`: common failure modes.
### scripts/
Add helper scripts here for common automation tasks.
## Maintenance
### assets/
Add templates, boilerplate, or example projects here.
## Notes
- This skill was automatically generated from official documentation
- Reference files preserve the structure and examples from source docs
- Code examples include language detection for better syntax highlighting
- Quick reference patterns are extracted from common usage examples in the docs
## Updating
To refresh this skill with updated documentation:
1. Re-run the scraper with the same configuration
2. The skill will be rebuilt with the latest information
- Sources: local `references/` extracted from Hummingbot documentation.
- Last updated: 2026-04-28
- Known limits: connector support and Gateway schemas change frequently; validate against the installed Hummingbot version.
assets/skills/markdown-to-epub/SKILL.md
+79 -54
View File
@@ -1,29 +1,34 @@
---
name: markdown-to-epub
description: "将 Markdown 手稿与本地图片资产转换为可校验的 EPUB：修复/归一化图片引用与扩展名，保持标题层级 TOC，并做基础包结构检查。"
description: "Markdown to EPUB build skill: normalize local image references, copy assets, call Calibre ebook-convert, inspect EPUB package structure, and report missing images. Use when turning Markdown manuscripts into reproducible EPUB files."
---
# markdown-to-epub Skill
把 Markdown 手稿（含本地图片）稳定构建为 EPUB：规范化图片引用、拷贝资产到可重复的构建目录、调用 Calibre `ebook-convert` 转换，并输出可核查报告。
Use this skill to build a reproducible EPUB from Markdown manuscripts with local image assets, without mutating the source manuscript.
## When to Use This Skill
触发条件（满足其一即可）：
- 需要把一份（或多份）Markdown 手稿打包交付为 EPUB。
- 图片引用混乱（URL 编码、路径飘忽、扩展名不可信如 `.bin/.idunno`），需要自动归一化。
- 需要在转换后做最基本的 EPUB 包结构检查（OPF/NCX/NAV、图片数量等）。
Trigger when any of these applies:
- Converting one or more Markdown files into an EPUB deliverable.
- Normalizing broken or inconsistent image references before conversion.
- Recovering local assets with unreliable extensions such as `.bin` or `.idunno`.
- Running Calibre `ebook-convert` non-interactively from a repeatable build directory.
- Checking the resulting EPUB archive for OPF, NCX/NAV, and image inclusion.
## Not For / Boundaries
- 不负责生成/改写正文内容（不会修改源手稿，只在构建目录里产出规范化版本）。
- 不下载远程图片（`http(s)`/`data:` 引用会保持原样）。
- 不替代真正的排版/校对流程（这里只做可交付构建与结构验证）。
- Not for authoring, rewriting, proofreading, or typesetting the manuscript body.
- Not for downloading remote `http(s)` or `data:` images; remote references are preserved unless the user supplies local replacements.
- Not a substitute for full EPUB QA in dedicated readers; it performs structural and asset checks only.
- Required inputs: source Markdown path, desired EPUB path/title/authors/language, source root, and any fallback asset map.
- If Calibre is unavailable, fail clearly and provide the install/`--ebook-convert-bin` verification path instead of producing a fake EPUB.
## Quick Start
## Quick Reference
从仓库根目录执行（推荐 `python3`）：
### Common Patterns
**Build a basic EPUB**
```bash
python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--input-md "./book.md" \
@@ -33,28 +38,16 @@ python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--language "zh-CN"
```
脚本会创建构建工作区（默认 `build_epub/`），包含：
- `book.normalized.md`
- `assets/`：拷贝后的图片（会按真实文件签名推断扩展名）
- `conversion.log`
- `report.json`
## 依赖
- 需要安装 Calibre，并确保 `ebook-convert` 在 `PATH` 中（或用 `--ebook-convert-bin` 指定路径）。
## Missing Asset Recovery
如果 Markdown 里引用了图片但文件找不到，可以提供一个 JSON 映射表（按「basename」匹配）：
```json
{
"missing-file.idunno": "replacement-file.idunno"
}
**Use a custom source root and build directory**
```bash
python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--input-md "./manuscript/book.md" \
--source-root "./manuscript" \
--build-dir "./build/book-epub" \
--output-epub "./dist/book.epub"
```
然后重跑（示例）：
**Recover missing assets with a fallback map**
```bash
python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--input-md "./book.md" \
@@ -62,31 +55,63 @@ python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--fallback-map "./fallback-map.json"
```
## Operational Rules
**Allow unresolved local images but report them**
```bash
python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--input-md "./book.md" \
--output-epub "./book.epub" \
--no-strict-missing
```
- 优先使用 `ebook-convert`；缺失时明确报错并快速失败。
- 源手稿只读；所有输出写入 `build_dir/`。
- TOC 以标题层级（`h1/h2/h3`）为准。
- 缺失资产必须显式报告；严格模式下不允许静默跳过。
- 命令保持非交互式。
**Point to a non-standard Calibre binary**
```bash
python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
--input-md "./book.md" \
--ebook-convert-bin "/opt/calibre/ebook-convert"
```
## Script Interface
**Inspect the generated package**
```bash
unzip -l ./book.epub | rg 'content.opf|toc.ncx|nav.xhtml|\\.(png|jpg|jpeg|webp|gif)$'
```
`scripts/build_epub.py` 参数：
- `--input-md`（必选）：源 Markdown 路径
- `--output-epub`（可选）：输出 EPUB 路径，默认 `<input-stem>.epub`
- `--source-root`（可选）：解析图片引用的根目录，默认使用 Markdown 所在目录
- `--build-dir`（可选）：构建工作区目录，默认 `<cwd>/build_epub`
- `--fallback-map`（可选）：JSON 映射（缺失图片 basename → 替换 basename）
- `--title` / `--authors` / `--language`：传给 `ebook-convert` 的元数据
- `--input-encoding`：输入 Markdown 编码，默认 `utf-8`
- `--strict-missing`：严格模式（有任何本地图片无法解析则失败，默认开启）
- `--no-strict-missing`：关闭严格模式（保留未解析链接，继续转换）
- `--ebook-convert-bin`：`ebook-convert` 可执行文件名/路径，默认 `ebook-convert`
## Examples
## Validation Checklist
### Example 1: Clean Manuscript Build
- 确认 EPUB 文件生成且大小不是「几 KB 的空壳」。
- 确认 EPUB（zip）内包含 OPF 与 NCX/NAV。
- 确认 EPUB 内图片数量不低于对手稿的预期。
- 严格模式下确认 `report.json` 的 `missing_images` 为空。
- Input: `book.md` with valid local images and metadata title/author/language.
- Steps:
1. Run the basic build command.
2. Inspect `build_epub/report.json`.
3. Check the EPUB zip listing for OPF and navigation files.
- Expected output / acceptance: `book.epub` exists, `missing_images` is empty, and package structure contains OPF plus NCX or NAV.
### Example 2: Extension Recovery
- Input: Markdown references `images/cover.idunno`, but the file signature is a PNG.
- Steps:
1. Run the build script in strict mode.
2. Confirm copied assets in `build_epub/assets/` use normalized extensions.
3. Rebuild after fixing any missing file mapping.
- Expected output / acceptance: EPUB includes the normalized image and the report records no unresolved local image.
### Example 3: Missing Asset Triage
- Input: manuscript references old file names that no longer exist.
- Steps:
1. Create a JSON fallback map from missing basenames to replacement basenames.
2. Re-run with `--fallback-map`.
3. Keep strict mode enabled so unmapped missing assets fail the build.
- Expected output / acceptance: every missing local image is either resolved by the map or listed in `report.json` for explicit follow-up.
## References
- `references/index.md`: navigation, script contract, and validation notes.
- `scripts/build_epub.py`: executable builder used by this skill.
- `agents/openai.yaml`: agent metadata for this skill package.
## Maintenance
- Sources: local script implementation and EPUB/Calibre behavior observed by the build report.
- Last updated: 2026-04-28
- Known limits: structural checks do not guarantee visual fidelity in every EPUB reader; run reader-specific QA for final publication.
assets/skills/markdown-to-epub/references/index.md
+27
View File
@@ -0,0 +1,27 @@
# markdown-to-epub Reference Index
This directory keeps long-form notes for the Markdown to EPUB skill. The entrypoint stays in `../SKILL.md`; operational behavior is implemented by `../scripts/build_epub.py`.
## Navigation
- `../SKILL.md`: triggers, boundaries, quick commands, and examples.
- `../scripts/build_epub.py`: source of truth for CLI arguments, asset normalization, Calibre invocation, and EPUB inspection.
- `../agents/openai.yaml`: optional agent metadata.
## Script Contract
- Source Markdown is read-only.
- Build artifacts are written to `--build-dir`.
- Local images are copied into the build workspace and normalized when the file signature proves a better extension.
- Remote `http(s)` and `data:` image references are not downloaded.
- Strict mode fails when local image references cannot be resolved.
## Verification
Run the builder, then inspect:
```bash
unzip -l ./book.epub | rg 'content.opf|toc.ncx|nav.xhtml|\\.(png|jpg|jpeg|webp|gif)$'
```
Also inspect `report.json` in the build directory for `missing_images`, copied assets, and conversion status.
assets/skills/polymarket/SKILL.md
+87 -179
View File
@@ -1,233 +1,141 @@
---
name: polymarket
description: Comprehensive Polymarket skill covering prediction markets, API, trading, market data, and real-time WebSocket data streaming. Build applications with Polymarket services, monitor live trades, and integrate market predictions.
description: "Polymarket prediction-market skill: REST/API research, CLOB market data, trading integration boundaries, WebSocket real-time data client, subscriptions, filters, authentication, and LLM-oriented market monitoring."
---
# Polymarket Comprehensive Skill
# polymarket Skill
Complete assistance with Polymarket development - covering the full platform (API, trading, market data) and the real-time data streaming client (WebSocket subscriptions for live market activity).
Use this skill to build Polymarket research, monitoring, market-data, and integration workflows while keeping trading/authentication risks explicit.
## When to Use This Skill
This skill should be triggered when:
Trigger when any of these applies:
- Querying Polymarket markets, events, prices, trades, comments, RFQ, or CLOB data.
- Building prediction-market monitors, dashboards, alerts, or LLM market-analysis tools.
- Using the `@polymarket/real-time-data-client` WebSocket client.
- Subscribing to activity, comments, RFQ, crypto price, `clob_market`, or authenticated `clob_user` topics.
- Debugging subscription filters, authentication payloads, reconnect handling, or message processing.
**Platform & API:**
- Working with Polymarket prediction markets
- Using Polymarket API for market data
- Implementing trading strategies
- Building applications with Polymarket services
- Learning Polymarket best practices
## Not For / Boundaries
**Real-Time Data Streaming:**
- Connecting to Polymarket's WebSocket service
- Building prediction market monitoring tools
- Processing live trades, orders, and market updates
- Monitoring market comments and social reactions
- Tracking RFQ (Request for Quote) activity
- Integrating crypto price feeds
- Not financial advice, market-making advice, or a guarantee of trading profitability.
- Do not expose CLOB API keys, secrets, passphrases, wallet keys, or private signing material.
- Private user streams and trading actions require explicit authentication and security review.
- Required inputs: market/event slug or CLOB market id, topic/type, auth need, filter payload, runtime, and expected output.
- For live trading, verify API terms, regional restrictions, auth scheme, and risk controls before implementation.
## Quick Reference
### Real-Time Data Client Setup
### Common Patterns
**Installation:**
**Install the real-time data client**
```bash
npm install @polymarket/real-time-data-client
```
**Basic Usage:**
**Subscribe to live trades**
```typescript
import { RealTimeDataClient } from "@polymarket/real-time-data-client";
const onMessage = (message: Message): void => {
console.log(message.topic, message.type, message.payload);
};
const client = new RealTimeDataClient({
onMessage: (message) => console.log(message.topic, message.type, message.payload),
onConnect: (c) => c.subscribe({
subscriptions: [{ topic: "activity", type: "trades" }],
}),
});
const onConnect = (client: RealTimeDataClient): void => {
client.subscribe({
subscriptions: [{
topic: "activity",
type: "trades"
}]
});
};
new RealTimeDataClient({ onMessage, onConnect }).connect();
client.connect();
```
### Supported WebSocket Topics
**1. Activity (`activity`)**
- `trades` - Completed trades
- `orders_matched` - Order matching events
- Filters: `{"event_slug":"string"}` OR `{"market_slug":"string"}`
**2. Comments (`comments`)**
- `comment_created`, `comment_removed`
- `reaction_created`, `reaction_removed`
- Filters: `{"parentEntityID":number,"parentEntityType":"Event"}`
**3. RFQ (`rfq`)**
- Request/Quote lifecycle events
- No filters, no auth required
**4. Crypto Prices (`crypto_prices`, `crypto_prices_chainlink`)**
- `update` - Real-time price feeds
- Filters: `{"symbol":"BTC"}` (optional)
**5. CLOB User (`clob_user`)** ⚠️ Requires Auth
- `order` - User's order updates
- `trade` - User's trade executions
**6. CLOB Market (`clob_market`)**
- `price_change` - Price movements
- `agg_orderbook` - Aggregated order book
- `last_trade_price` - Latest prices
- `market_created`, `market_resolved`
### Authentication for User Data
**Filter activity to one market slug**
```typescript
client.subscribe({
subscriptions: [{
topic: "clob_user",
type: "*",
clob_auth: {
key: "your-api-key",
secret: "your-api-secret",
passphrase: "your-passphrase"
}
}]
subscriptions: [{
topic: "activity",
type: "trades",
filters: "{\"market_slug\":\"btc-above-100k-2024\"}",
}],
});
```
### Common Use Cases
**Monitor Specific Market:**
**Subscribe to CLOB market price changes**
```typescript
client.subscribe({
subscriptions: [{
topic: "activity",
type: "trades",
filters: `{"market_slug":"btc-above-100k-2024"}`
}]
subscriptions: [{
topic: "clob_market",
type: "price_change",
filters: "[\"100\",\"101\",\"102\"]",
}],
});
```
**Track Multiple Markets:**
**Subscribe to comments for an event**
```typescript
client.subscribe({
subscriptions: [{
topic: "clob_market",
type: "price_change",
filters: `["100","101","102"]`
}]
subscriptions: [{
topic: "comments",
type: "*",
filters: "{\"parentEntityID\":12345,\"parentEntityType\":\"Event\"}",
}],
});
```
**Monitor Event Comments:**
**Authenticate a user stream**
```typescript
client.subscribe({
subscriptions: [{
topic: "comments",
type: "*",
filters: `{"parentEntityID":12345,"parentEntityType":"Event"}`
}]
subscriptions: [{
topic: "clob_user",
type: "*",
clob_auth: {
key: "YOUR_API_KEY",
secret: "YOUR_API_SECRET",
passphrase: "YOUR_PASSPHRASE",
},
}],
});
```
## Reference Files
## Examples
This skill includes comprehensive documentation in `references/`:
### Example 1: Public Trade Monitor
**Platform Documentation:**
- **api.md** - Polymarket API documentation
- **getting_started.md** - Getting started guide
- **guides.md** - Development guides
- **learn.md** - Learning resources
- **trading.md** - Trading documentation
- **other.md** - Additional resources
- Input: market slug and alert threshold.
- Steps:
1. Subscribe to `activity/trades` with a `market_slug` filter.
2. Normalize messages into timestamp, market, side, price, size.
3. Alert only when trade size or price movement crosses the configured threshold.
- Expected output / acceptance: real-time public trade stream with no private authentication material.
**Real-Time Client:**
- **README.md** - WebSocket client API and examples
- **llms.md** - LLM integration guide
- **llms-full.md** - Complete LLM documentation
### Example 2: CLOB Price Dashboard
Use `view` to read specific reference files for detailed information.
- Input: CLOB market IDs.
- Steps:
1. Subscribe to `clob_market/price_change` with a JSON array filter.
2. Update an in-memory view keyed by market id.
3. Persist snapshots at a controlled interval rather than every message if volume is high.
- Expected output / acceptance: dashboard shows latest market prices and handles reconnects idempotently.
## Key Features
### Example 3: Authenticated User Order Feed
**Platform Capabilities:**
✅ Prediction market creation and resolution
✅ Trading API (REST & WebSocket)
✅ Market data queries
✅ User portfolio management
✅ Event and market discovery
- Input: CLOB API credentials stored in a secret manager.
- Steps:
1. Load credentials at runtime without logging them.
2. Subscribe to `clob_user` order/trade events.
3. Validate message schema and write audit logs without secrets.
- Expected output / acceptance: private user updates are received and secrets never appear in source control or logs.
**Real-Time Streaming:**
✅ WebSocket-based persistent connections
✅ Topic-based subscriptions
✅ Dynamic subscription management
✅ Filter support for targeted data
✅ User authentication for private data
✅ TypeScript with full type safety
✅ Initial data dumps on connection
## References
## Best Practices
- `references/index.md`: navigation for local Polymarket references.
- `references/api.md`: platform API documentation.
- `references/getting_started.md`: onboarding and setup notes.
- `references/trading.md`: trading and market operations.
- `references/realtime-client.md`: WebSocket real-time data client.
- `references/README.md`: platform overview.
- `references/llms.md` and `references/llms-full.md`: LLM integration material.
### WebSocket Connection Management
- Use `onConnect` callback for subscriptions
- Implement reconnection logic for production
- Clean up with `disconnect()` when done
- Handle authentication errors gracefully
## Maintenance
### Subscription Strategy
- Use wildcards (`"*"`) sparingly
- Apply filters to reduce data volume
- Unsubscribe from unused streams
- Process messages asynchronously
### Performance
- Consider batching high-frequency data
- Use filters to minimize client processing
- Validate message payloads before use
## Requirements
- **Node.js**: 14+ recommended
- **TypeScript**: Optional but recommended
- **Package Manager**: npm or yarn
## Resources
### Official Links
- **Polymarket Platform**: https://polymarket.com
- **Real-Time Client Repo**: https://github.com/Polymarket/real-time-data-client
- **API Documentation**: See references/api.md
### Working with This Skill
**For Beginners:**
Start with `getting_started.md` for foundational concepts.
**For API Integration:**
Use `api.md` and `trading.md` for REST API details.
**For Real-Time Data:**
Use `README.md` for WebSocket client implementation.
**For LLM Integration:**
Use `llms.md` and `llms-full.md` for AI/ML use cases.
## Notes
- Real-Time Client is TypeScript/JavaScript (not Python)
- Some WebSocket topics require authentication
- Use filters to manage message volume effectively
- All timestamps are Unix timestamps
- Market IDs are strings (e.g., "100", "101")
- Platform documentation covers both REST API and WebSocket usage
---
**This comprehensive skill combines Polymarket platform expertise with real-time data streaming capabilities!**
- Sources: local `references/` extracted from Polymarket platform and real-time client documentation.
- Last updated: 2026-04-28
- Known limits: API auth, market availability, and regional/legal constraints must be verified outside this skill before live trading.
assets/skills/postgresql/SKILL.md
+86 -102
View File
File diff suppressed because one or more lines are too long
assets/skills/proxychains/SKILL.md
+71 -244
View File
@@ -1,291 +1,118 @@
---
name: proxychains
description: Auto-detect network issues and force proxy usage with proxychains4. Use this skill when encountering connection timeouts, DNS failures, or blocked network access. Default proxy is http://127.0.0.1:9910
description: "proxychains4 network fallback skill: detect timeouts, DNS failures, blocked GitHub/PyPI/npm/curl/git access, configure http://127.0.0.1:9910, and retry commands through proxychains."
---
# Proxychains Network Proxy Skill
# proxychains Skill
**自动使用代理解决网络问题** - 当遇到网络连接失败、超时或访问受限时，自动使用 proxychains4 强制走代理。
Use this skill when network commands fail or known slow/blocked sources need a transparent TCP proxy through `proxychains4`.
## When to Use This Skill
**触发条件（自动应用）:**
- ❌ Connection timeout errors
- ❌ DNS resolution failures
- ❌ "Connection refused" errors
- ❌ HTTP 403/451 blocked access
- ❌ GitHub/PyPI/npm 等国外资源访问失败
- ❌ curl/wget/git/pip 等命令失败
Trigger when any of these applies:
- `curl`, `wget`, `git`, `pip`, `npm`, `yarn`, `docker pull`, or `ssh` fails with timeout, DNS, reset, refused, 403, or 451-like access errors.
- Accessing GitHub, raw GitHub content, PyPI, npm registry, Docker registries, or other known slow foreign resources.
- Configuring a local proxychains profile that points to `http://127.0.0.1:9910`.
- Diagnosing whether failure is proxy service down, proxychains config wrong, unsupported UDP/static binary behavior, or upstream blocked.
**Claude 应该：**
1. 检测到网络错误后，自动在命令前添加 `proxychains4`
2. 使用默认代理配置：`http://127.0.0.1:9910`
3. 如果代理失败，提示用户检查代理服务状态
## Not For / Boundaries
- Not for bypassing legal, account, regional, or enterprise security restrictions.
- Not useful for UDP-only traffic or statically linked binaries that proxychains cannot intercept.
- Do not proxy commands that should remain on a trusted private network without checking routing and policy.
- Required inputs: failed command, full error text, target domain, proxy endpoint, OS package name, and whether the proxy service is running.
- If proxychains retry also fails, inspect proxy service health before repeating the same command.
## Quick Reference
### 基本用法模式
### Common Patterns
**Install on Debian/Ubuntu**
```bash
# ❌ 原命令失败
curl https://github.com/user/repo
sudo apt install proxychains4
```
# ✅ 使用代理重试
**Create user config for the local proxy**
```bash
mkdir -p ~/.proxychains
cp assets/skills/proxychains/references/proxychains.conf ~/.proxychains/proxychains.conf
```
**Test the proxy**
```bash
proxychains4 curl https://ipinfo.io/json
```
**Retry a failed curl**
```bash
proxychains4 curl https://github.com/user/repo
```
### 常见场景自动应用
**场景 1: Git 操作失败**
**Retry a failed git clone**
```bash
# 原命令
git clone https://github.com/user/repo.git
# 自动改为
proxychains4 git clone https://github.com/user/repo.git
```
**场景 2: Python pip 安装失败**
**Retry a failed pip install**
```bash
# 原命令
pip install requests
# 自动改为
proxychains4 pip install requests
```
**场景 3: npm/yarn 安装失败**
**Retry a failed npm install**
```bash
# 原命令
npm install package-name
# 自动改为
proxychains4 npm install package-name
```
**场景 4: wget/curl 下载失败**
**Retry a failed Docker pull**
```bash
# 原命令
wget https://example.com/file.tar.gz
# 自动改为
proxychains4 wget https://example.com/file.tar.gz
```
**场景 5: Docker 拉取镜像失败**
```bash
# 原命令
docker pull image:tag
# 自动改为
proxychains4 docker pull image:tag
```
**场景 6: SSH 连接失败**
**Inspect effective config**
```bash
# 原命令
ssh user@remote-host
# 自动改为
proxychains4 ssh user@remote-host
proxychains4 -f ~/.proxychains/proxychains.conf curl https://example.com
```
## 配置详情
## Examples
### 默认代理配置
### Example 1: GitHub Clone Timeout
**本地代理地址：** `http://127.0.0.1:9910`
- Input: `git clone` fails with a connection timeout.
- Steps:
1. Retry with `proxychains4 git clone ...`.
2. If it fails, run `proxychains4 curl https://github.com` to isolate Git vs network.
3. Check local proxy service on `127.0.0.1:9910`.
- Expected output / acceptance: clone succeeds or failure is classified as proxy service/config/upstream issue.
**配置文件位置：**
- `~/.proxychains/proxychains.conf` (推荐)
- `/etc/proxychains.conf` (系统级)
### Example 2: PyPI Install Fails
### 快速配置脚本
- Input: `pip install` cannot reach PyPI.
- Steps:
1. Retry with `proxychains4 pip install <package>`.
2. If DNS still fails, confirm `proxy_dns` is enabled in config.
3. Avoid writing credentials into `pip.conf` unless explicitly required.
- Expected output / acceptance: package install succeeds through proxy or produces a new non-network error.
创建用户级配置（自动使用 127.0.0.1:9910）：
### Example 3: Unsupported Traffic Diagnosis
```bash
mkdir -p ~/.proxychains
cat > ~/.proxychains/proxychains.conf << 'EOF'
# Proxychains configuration
strict_chain
proxy_dns
remote_dns_subnet 224
tcp_read_time_out 15000
tcp_connect_time_out 8000
- Input: proxychains retry does not affect a command.
- Steps:
1. Confirm the command uses TCP and dynamic linking.
2. Test the proxy with a known-good `curl`.
3. Use application-native proxy options if proxychains cannot intercept it.
- Expected output / acceptance: unsupported mode is identified instead of repeatedly retrying.
[ProxyList]
http 127.0.0.1 9910
EOF
```
## References
### 环境变量方式（临时使用）
- `references/index.md`: navigation for local proxychains references.
- `references/proxychains.conf`: default config targeting `127.0.0.1:9910`.
- `references/quick-reference.md`: command snippets and common scenarios.
- `references/setup-guide.md`: installation and setup notes.
- `references/troubleshooting.md`: failure classification.
- `scripts/setup-proxy.sh`: helper script for local setup.
```bash
# 设置代理环境变量
export PROXYCHAINS_SOCKS5_HOST=127.0.0.1
export PROXYCHAINS_SOCKS5_PORT=9910
## Maintenance
# 使用
proxychains4 curl https://github.com
```
## 工作原理
Proxychains 通过 LD_PRELOAD 机制拦截程序的网络调用：
1. **拦截系统调用**：Hook socket 相关的 libc 函数
2. **重定向连接**：将所有 TCP 连接重定向到代理服务器
3. **DNS 代理**：通过代理服务器解析域名
4. **透明代理**：应用程序无需修改
**重要限制：**
- 只支持动态链接的程序（statically linked 程序不支持）
- 只支持 TCP 连接（UDP 不支持）
- 部分使用特殊网络库的程序可能不兼容
## Claude 自动化规则
### 规则 1: 网络错误自动重试
```
IF 命令返回网络相关错误（timeout, connection refused, DNS failure）
THEN 自动使用 proxychains4 重试该命令
```
### 规则 2: 已知慢速源强制代理
```
IF 访问以下域名/服务：
- github.com
- raw.githubusercontent.com
- pypi.org
- npmjs.org
- registry.npmjs.org
- docker.io
- gcr.io
THEN 直接使用 proxychains4（不等待失败）
```
### 规则 3: 失败提示
```
IF proxychains4 命令也失败
THEN 提示用户：
1. 检查代理服务是否运行（127.0.0.1:9910）
2. 检查 proxychains 配置文件
3. 尝试其他代理地址
```
## 故障排除
### 检查代理服务状态
```bash
# 测试代理是否可用
curl -x http://127.0.0.1:9910 https://www.google.com
# 检查端口是否监听
netstat -tunlp | grep 9910
# 或
ss -tunlp | grep 9910
```
### 验证 proxychains 配置
```bash
# 测试配置是否正确
proxychains4 curl https://ipinfo.io/json
# 应该显示代理服务器的 IP，而不是本机 IP
```
### 常见错误处理
**错误 1: "proxychains: command not found"**
```bash
# 安装 proxychains4
sudo apt install proxychains4 # Debian/Ubuntu
sudo yum install proxychains-ng # CentOS/RHEL
```
**错误 2: "timeout"**
```bash
# 检查代理地址配置是否正确
cat ~/.proxychains/proxychains.conf | grep -A 2 "\[ProxyList\]"
# 修改超时时间（在配置文件中）
tcp_connect_time_out 15000
tcp_read_time_out 30000
```
**错误 3: "can't read configuration file"**
```bash
# 创建配置文件
mkdir -p ~/.proxychains
cp /etc/proxychains.conf ~/.proxychains/proxychains.conf
# 然后编辑配置
```
## 高级用法
### 多代理链
```conf
# ~/.proxychains/proxychains.conf
strict_chain # 按顺序使用所有代理
[ProxyList]
http 127.0.0.1 9910
socks5 127.0.0.1 1080
```
### 动态代理链
```conf
dynamic_chain # 自动跳过死代理
[ProxyList]
http 127.0.0.1 9910
http 127.0.0.1 8080
socks5 127.0.0.1 1080
```
### 随机代理链
```conf
random_chain
chain_len = 2 # 随机选择 2 个代理
[ProxyList]
http 127.0.0.1 9910
socks5 127.0.0.1 1080
socks5 127.0.0.1 1081
```
### 自定义 DNS 服务器
```bash
# 使用自定义 DNS 通过代理解析
export PROXY_DNS_SERVER=8.8.8.8
proxychains4 curl https://example.com
```
## 参考资源
- **官方仓库**: https://github.com/haad/proxychains
- **配置文件**: `references/proxychains.conf` (完整示例)
- **故障排除**: `references/troubleshooting.md`
- **命令速查**: `references/quick-reference.md`
## 总结
**记住这些原则：**
1. ❌ **遇到网络错误** → ✅ 自动加上 `proxychains4`
2. 🌐 **访问国外资源** → ✅ 主动使用 `proxychains4`
3. 🔧 **代理也失败** → ✅ 提示用户检查代理服务
**默认代理:** `http://127.0.0.1:9910`
---
**这个技能让 Claude 在遇到网络问题时自动使用代理，无需用户手动干预！**
- Sources: local proxychains reference files and config template.
- Last updated: 2026-04-28
- Known limits: proxychains relies on `LD_PRELOAD` style interception and is not universal; prefer native proxy settings when available.
assets/skills/snapdom/SKILL.md
+63 -215
View File
@@ -1,274 +1,122 @@
---
name: snapdom
description: snapDOM is a fast, accurate DOM-to-image capture tool that converts HTML elements into scalable SVG images. Use for capturing HTML elements, converting DOM to images (SVG, PNG, JPG, WebP), preserving styles, fonts, and pseudo-elements.
description: "snapDOM DOM-to-image skill: capture HTML elements as SVG/PNG/JPG/WebP/canvas/blob, preserve styles/fonts/pseudo-elements, use scaling/exclusion/CORS proxy options, and compare screenshot output."
---
# SnapDOM Skill
# snapdom Skill
Fast, dependency-free DOM-to-image capture library for converting HTML elements into scalable SVG or raster image formats.
Use this skill to capture browser DOM elements into image outputs with snapDOM while preserving styling and controlling export options.
## When to Use This Skill
Use SnapDOM when you need to:
- Convert HTML elements to images (SVG, PNG, JPG, WebP)
- Capture styled DOM with pseudo-elements and shadows
- Export elements with embedded fonts and icons
- Create screenshots with custom dimensions or scaling
- Handle CORS-blocked resources using proxy fallback
- Implement custom rendering pipelines with plugins
- Optimize performance on large or complex elements
Trigger when any of these applies:
- Exporting a DOM element to SVG, PNG, JPG, WebP, Canvas, or Blob.
- Capturing styled UI with fonts, pseudo-elements, shadows, transforms, or Shadow DOM.
- Building screenshot/export/download features in web apps.
- Debugging missing assets, CORS-blocked images, scaling, tight bounds, or excluded controls.
- Comparing snapDOM with `html2canvas` or browser screenshot workflows.
## Key Features
## Not For / Boundaries
### Universal Export Options
- **SVG** - Scalable vector format, embeds all styles
- **PNG, JPG, WebP** - Raster formats with configurable quality
- **Canvas** - Get raw Canvas element for further processing
- **Blob** - Raw binary data for custom handling
- Not for full-page browser automation screenshots; use Playwright/Puppeteer when viewport, navigation, or browser state is the core need.
- CORS-blocked resources may require a proxy or same-origin setup; do not assume cross-origin images will embed automatically.
- Do not capture sensitive DOM content unless the user explicitly intends to export it.
- Required inputs: target element selector, desired format, dimensions/scale, asset/CORS constraints, and where the image should be used.
- Verify package/API names against the installed version if build errors indicate version drift.
### Performance
- Ultra-fast capture (1.6ms for small elements, ~171ms for 4000×2000)
- **No dependencies** - Uses standard Web APIs only
- Outperforms html2canvas by 10-40x on complex elements
## Quick Reference
### Style Support
- Embedded fonts (including icon fonts)
- CSS pseudo-elements (::before, ::after)
- CSS counters
- CSS line-clamp
- Transform and shadow effects
- Shadow DOM content
### Common Patterns
### Advanced Capabilities
- Same-origin iframe support
- CORS proxy fallback for blocked assets
- Plugin system for custom transformations
- Straighten transforms (remove rotate/translate)
- Selective element exclusion
- Tight bounding box calculation
## Installation
### NPM/Yarn
**Install**
```bash
npm install @zumer/snapdom
# or
yarn add @zumer/snapdom
```
### CDN (ES Module)
**Import from CDN as an ES module**
```html
<script type="module">
import { snapdom } from "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
</script>
```
### CDN (UMD)
```html
<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.umd.js"></script>
```
## Quick Start Examples
### Basic Reusable Capture
**Capture once and export multiple formats**
```javascript
// Create reusable capture object
const result = await snapdom(document.querySelector('#target'));
// Export to different formats
const result = await snapdom(document.querySelector("#target"));
const png = await result.toPng();
const jpg = await result.toJpg();
const svg = await result.toSvg();
const canvas = await result.toCanvas();
const blob = await result.toBlob();
// Use the result
document.body.appendChild(png);
```
### One-Step Export
**One-step PNG export**
```javascript
// Direct export without intermediate object
const png = await snapdom.toPng(document.querySelector('#target'));
const svg = await snapdom.toSvg(element);
const png = await snapdom.toPng(document.querySelector("#target"));
```
### Download Element
**Download an element**
```javascript
// Automatically download as file
await snapdom.download(element, 'screenshot.png');
await snapdom.download(element, 'image.svg');
await snapdom.download(document.querySelector("#target"), "screenshot.png");
```
### With Options
**Set scale and dimensions**
```javascript
const result = await snapdom(element, {
scale: 2, // 2x resolution
width: 800, // Custom width
height: 600, // Custom height
embedFonts: true, // Include @font-face
exclude: '.no-capture', // Hide elements
useProxy: true, // Enable CORS proxy
straighten: true, // Remove transforms
noShadows: false // Keep shadows
});
const png = await result.toPng({ quality: 0.95 });
```
## Essential Options Reference
| Option | Type | Purpose |
|--------|------|---------|
| `scale` | Number | Scale output (e.g., 2 for 2x resolution) |
| `width` | Number | Custom output width in pixels |
| `height` | Number | Custom output height in pixels |
| `embedFonts` | Boolean | Include non-icon @font-face rules |
| `useProxy` | String\|Boolean | Enable CORS proxy (URL or true for default) |
| `exclude` | String | CSS selector for elements to hide |
| `straighten` | Boolean | Remove translate/rotate transforms |
| `noShadows` | Boolean | Strip shadow effects |
## Common Patterns
### Responsive Screenshots
```javascript
// Capture at different scales
const mobile = await snapdom.toPng(element, { scale: 1 });
const tablet = await snapdom.toPng(element, { scale: 1.5 });
const desktop = await snapdom.toPng(element, { scale: 2 });
```
### Exclude Elements
```javascript
// Hide specific elements from capture
const png = await snapdom.toPng(element, {
exclude: '.controls, .watermark, [data-no-capture]'
});
```
### Fixed Dimensions
```javascript
// Capture with specific size
const result = await snapdom(element, {
scale: 2,
width: 1200,
height: 630 // Standard social media size
height: 630,
});
```
### CORS Handling
**Exclude UI controls**
```javascript
// Fallback for CORS-blocked resources
const png = await snapdom.toPng(element, {
useProxy: 'https://cors.example.com/?' // Custom proxy
exclude: ".controls, [data-no-capture]",
});
```
### Plugin System (Beta)
**Use a CORS proxy fallback**
```javascript
// Extend with custom exporters
snapdom.plugins([pluginFactory, { colorOverlay: true }]);
// Hook into lifecycle
defineExports(context) {
return {
pdf: async (ctx, opts) => { /* generate PDF */ }
};
}
// Lifecycle hooks available:
// beforeSnap → beforeClone → afterClone →
// beforeRender → beforeExport → afterExport
const png = await snapdom.toPng(element, {
useProxy: "https://cors.example.com/?",
});
```
## Performance Comparison
## Examples
SnapDOM significantly outperforms html2canvas:
### Example 1: Social Card Export
| Scenario | SnapDOM | html2canvas | Improvement |
|----------|---------|-------------|-------------|
| Small (200×100) | 1.6ms | 68ms | 42x faster |
| Medium (800×600) | 12ms | 280ms | 23x faster |
| Large (4000×2000) | 171ms | 1,800ms | 10x faster |
- Input: element `#card`, target size `1200x630`, PNG output.
- Steps:
1. Ensure fonts and images are loaded.
2. Capture with explicit `width`, `height`, and `scale`.
3. Download or upload the resulting PNG.
- Expected output / acceptance: exported image matches the card bounds and excludes editor controls.
## Development
### Example 2: SVG Snapshot for Documentation
### Setup
```bash
git clone https://github.com/zumerlab/snapdom.git
cd snapdom
npm install
```
- Input: styled component preview.
- Steps:
1. Call `snapdom(element)`.
2. Export `toSvg()` for scalable documentation output.
3. Inspect missing fonts/assets if the snapshot differs from the page.
- Expected output / acceptance: SVG preserves visible styles and remains inspectable as a vector artifact.
### Build
```bash
npm run compile
```
### Example 3: CORS Asset Triage
### Testing
```bash
npm test
```
- Input: export shows missing remote images.
- Steps:
1. Confirm whether assets are same-origin and CORS-enabled.
2. Retry with `useProxy` or replace remote assets with local/same-origin URLs.
3. Validate final output in the target browser.
- Expected output / acceptance: missing images are attributed to CORS, loading, or selector/sizing issues.
## Browser Support
## References
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari 14+, Chrome Mobile)
- `references/index.md`: local snapDOM reference navigation.
- `references/other.md`: generated upstream notes and API details.
## Resources
## Maintenance
### Documentation
- **Official Website:** https://snapdom.dev/
- **GitHub Repository:** https://github.com/zumerlab/snapdom
- **NPM Package:** https://www.npmjs.com/package/@zumer/snapdom
- **License:** MIT
### scripts/
Add helper scripts here for automation, e.g.:
- `batch-screenshot.js` - Capture multiple elements
- `pdf-export.js` - Convert snapshots to PDF
- `compare-outputs.js` - Compare SVG vs PNG quality
### assets/
Add templates and examples:
- HTML templates for common capture scenarios
- CSS frameworks pre-configured with snapdom
- Boilerplate projects integrating snapdom
## Related Tools
- **html2canvas** - Alternative DOM capture (slower but more compatible)
- **Orbit CSS Toolkit** - Companion toolkit by Zumerlab (https://github.com/zumerlab/orbit)
## Tips & Best Practices
1. **Performance**: Use `scale` instead of `width`/`height` for better performance
2. **Fonts**: Set `embedFonts: true` to ensure custom fonts appear correctly
3. **CORS Issues**: Use `useProxy: true` if images fail to load
4. **Large Elements**: Break into smaller chunks for complex pages
5. **Quality**: For PNG/JPG, use `quality: 0.95` for best quality
6. **SVG Vectors**: Prefer SVG export for charts and graphics
## Troubleshooting
### Elements Not Rendering
- Check if element has sufficient height/width
- Verify CSS is fully loaded before capture
- Try `straighten: false` if transforms are causing issues
### Missing Fonts
- Set `embedFonts: true`
- Ensure fonts are loaded before calling snapdom
- Check browser console for font loading errors
### CORS Issues
- Enable `useProxy: true`
- Use custom proxy URL if default fails
- Check if resources are from same origin
### Performance Issues
- Reduce `scale` value
- Use `noShadows: true` to skip shadow rendering
- Consider splitting large captures into smaller sections
- Sources: local `references/` extracted from snapDOM documentation.
- Last updated: 2026-04-28
- Known limits: screenshot fidelity depends on browser support, loaded assets, CORS, fonts, and installed snapDOM version.
assets/skills/telegram-dev/SKILL.md
+90 -711
View File
@@ -1,760 +1,139 @@
---
name: telegram-dev
description: Telegram 生态开发全栈指南 - 涵盖 Bot API、Mini Apps (Web Apps)、MTProto 客户端开发。包括消息处理、支付、内联模式、Webhook、认证、存储、传感器 API 等完整开发资源。
description: "Telegram development skill: Bot API, Mini Apps/Web Apps, webhooks, long polling, inline/reply keyboards, payments, initData validation, TDLib/MTProto, message formatting, and deployment troubleshooting."
---
# Telegram 生态开发技能
# telegram-dev Skill
全面的 Telegram 开发指南，涵盖 Bot 开发、Mini Apps (Web Apps)、客户端开发的完整技术栈。
Use this skill to build Telegram bots, Mini Apps, and client integrations with explicit security boundaries around tokens, webhooks, and user data.
## 何时使用此技能
## When to Use This Skill
当需要以下帮助时使用此技能：
- 开发 Telegram Bot（消息机器人）
- 创建 Telegram Mini Apps（小程序）
- 构建自定义 Telegram 客户端
- 集成 Telegram 支付和业务功能
- 实现 Webhook 和长轮询
- 使用 Telegram 认证和存储
- 处理消息、媒体和文件
- 实现内联模式和键盘
Trigger when any of these applies:
- Creating or debugging a Telegram Bot with Bot API methods, long polling, webhooks, commands, messages, media, files, or payments.
- Building Telegram Mini Apps/Web Apps with `window.Telegram.WebApp`, buttons, theme params, storage, sensors, or `initData` validation.
- Implementing inline keyboards, reply keyboards, callback queries, command menus, or dynamic aligned message views.
- Working with TDLib/MTProto client development or API ID/hash based integrations.
- Troubleshooting webhook TLS/port issues, bot token errors, callback handling, formatting, or deployment.
## Telegram 开发生态概览
## Not For / Boundaries
### 三大核心 API
- Not for spam, unauthorized scraping, account abuse, or bypassing Telegram platform rules.
- Never commit or print bot tokens, API hash, API ID plus phone session data, payment secrets, or user private data.
- Webhook examples require HTTPS and public reachability; local-only servers need a tunnel or local Bot API server setup.
- Required inputs: Bot vs Mini App vs TDLib scope, language/framework, token/auth status, update payload, deployment URL, and exact error.
- Telegram APIs evolve; verify current method parameters and limits in official docs when precision matters.
1. **Bot API** - 创建机器人程序
- HTTP 接口，简单易用
- 自动处理加密和通信
- 适合：聊天机器人、自动化工具
## Quick Reference
2. **Mini Apps API** (Web Apps) - 创建 Web 应用
- JavaScript 接口
- 在 Telegram 内运行
- 适合：小程序、游戏、电商
### Common Patterns
3. **Telegram API & TDLib** - 创建客户端
- 完整的 Telegram 协议实现
- 支持所有平台
- 适合：自定义客户端、企业应用
## Bot API 开发
### 快速开始
**API 端点：**
```
https://api.telegram.org/bot<TOKEN>/METHOD_NAME
**Bot API endpoint shape**
```text
https://api.telegram.org/bot<TOKEN>/<METHOD_NAME>
```
**获取 Bot Token：**
1. 与 @BotFather 对话
2. 发送 `/newbot`
3. 按提示设置名称
4. 获取 token
**第一个 Bot (Python)：**
**Send a message**
```python
import requests
BOT_TOKEN = "your_bot_token_here"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
# 发送消息
def send_message(chat_id, text):
url = f"{API_URL}/sendMessage"
data = {"chat_id": chat_id, "text": text}
return requests.post(url, json=data)
# 获取更新（长轮询）
def get_updates(offset=None):
url = f"{API_URL}/getUpdates"
params = {"offset": offset, "timeout": 30}
return requests.get(url, params=params).json()
# 主循环
offset = None
while True:
updates = get_updates(offset)
for update in updates.get("result", []):
chat_id = update["message"]["chat"]["id"]
text = update["message"]["text"]
# 回复消息
send_message(chat_id, f"你说了：{text}")
offset = update["update_id"] + 1
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
json={"chat_id": chat_id, "text": "Hello"},
timeout=10,
)
```
### 核心 API 方法
**更新管理：**
- `getUpdates` - 长轮询获取更新
- `setWebhook` - 设置 Webhook
- `deleteWebhook` - 删除 Webhook
- `getWebhookInfo` - 查询 Webhook 状态
**消息操作：**
- `sendMessage` - 发送文本消息
- `sendPhoto` / `sendVideo` / `sendDocument` - 发送媒体
- `sendAudio` / `sendVoice` - 发送音频
- `sendLocation` / `sendVenue` - 发送位置
- `editMessageText` - 编辑消息
- `deleteMessage` - 删除消息
- `forwardMessage` / `copyMessage` - 转发/复制消息
**交互元素：**
- `sendPoll` - 发送投票（最多 12 个选项）
- 内联键盘 (InlineKeyboardMarkup)
- 回复键盘 (ReplyKeyboardMarkup)
- `answerCallbackQuery` - 响应回调查询
**文件操作：**
- `getFile` - 获取文件信息
- `downloadFile` - 下载文件
- 支持最大 2GB 文件（本地 Bot API 模式）
**支付功能：**
- `sendInvoice` - 发送发票
- `answerPreCheckoutQuery` - 处理支付
- Telegram Stars 支付（最高 10,000 Stars）
### Webhook 配置
**设置 Webhook：**
**Long polling**
```python
import requests
BOT_TOKEN = "your_token"
WEBHOOK_URL = "https://yourdomain.com/webhook"
updates = requests.get(
f"https://api.telegram.org/bot{BOT_TOKEN}/getUpdates",
params={"offset": offset, "timeout": 30},
timeout=35,
).json()
```
**Set a webhook**
```python
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/setWebhook",
json={"url": WEBHOOK_URL}
json={"url": "https://example.com/webhook"},
timeout=10,
)
```
**Flask Webhook 示例：**
**Inline keyboard**
```python
from flask import Flask, request
import requests
app = Flask(__name__)
BOT_TOKEN = "your_token"
@app.route('/webhook', methods=['POST'])
def webhook():
update = request.get_json()
chat_id = update["message"]["chat"]["id"]
text = update["message"]["text"]
# 发送回复
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
json={"chat_id": chat_id, "text": f"收到: {text}"}
)
return "OK"
if __name__ == '__main__':
app.run(port=5000)
```
**Webhook 要求：**
- 必须使用 HTTPS
- 支持 TLS 1.2+
- 端口：443, 80, 88, 8443
- 公共可访问的 URL
### 内联键盘
**创建内联键盘：**
```python
def send_inline_keyboard(chat_id):
keyboard = {
"inline_keyboard": [
[
{"text": "按钮 1", "callback_data": "btn1"},
{"text": "按钮 2", "callback_data": "btn2"}
],
[
{"text": "打开链接", "url": "https://example.com"}
]
]
}
requests.post(
f"{API_URL}/sendMessage",
json={
"chat_id": chat_id,
"text": "选择一个选项：",
"reply_markup": keyboard
}
)
```
**处理回调：**
```python
def handle_callback_query(callback_query):
query_id = callback_query["id"]
data = callback_query["data"]
chat_id = callback_query["message"]["chat"]["id"]
# 响应回调
requests.post(
f"{API_URL}/answerCallbackQuery",
json={"callback_query_id": query_id, "text": f"你点击了 {data}"}
)
# 更新消息
requests.post(
f"{API_URL}/editMessageText",
json={
"chat_id": chat_id,
"message_id": callback_query["message"]["message_id"],
"text": f"你选择了：{data}"
}
)
```
### 内联模式
**配置内联模式：**
与 @BotFather 对话，发送 `/setinline`
**处理内联查询：**
```python
def handle_inline_query(inline_query):
query_id = inline_query["id"]
query_text = inline_query["query"]
# 创建结果
results = [
{
"type": "article",
"id": "1",
"title": "结果 1",
"input_message_content": {
"message_text": f"你搜索了：{query_text}"
}
}
]
requests.post(
f"{API_URL}/answerInlineQuery",
json={"inline_query_id": query_id, "results": results}
)
```
## Mini Apps (Web Apps) 开发
### 初始化 Mini App
**HTML 模板：**
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<title>My Mini App</title>
</head>
<body>
<h1>Telegram Mini App</h1>
<button id="mainBtn">主按钮</button>
<script>
// 获取 Telegram WebApp 对象
const tg = window.Telegram.WebApp;
// 通知 Telegram 应用已准备好
tg.ready();
// 展开到全屏
tg.expand();
// 显示用户信息
const user = tg.initDataUnsafe?.user;
if (user) {
console.log("用户名:", user.first_name);
console.log("用户ID:", user.id);
}
// 配置主按钮
tg.MainButton.text = "提交";
tg.MainButton.show();
tg.MainButton.onClick(() => {
// 发送数据到 Bot
tg.sendData(JSON.stringify({action: "submit"}));
});
// 添加返回按钮
tg.BackButton.show();
tg.BackButton.onClick(() => {
tg.close();
});
</script>
</body>
</html>
```
### Mini App 核心 API
**WebApp 对象主要属性：**
```javascript
// 初始化数据
tg.initData // 原始初始化字符串
tg.initDataUnsafe // 解析后的对象
// 用户和主题
tg.initDataUnsafe.user // 用户信息
tg.themeParams // 主题颜色
tg.colorScheme // 'light' 或 'dark'
// 状态
tg.isExpanded // 是否全屏
tg.isFullscreen // 是否全屏
tg.viewportHeight // 视口高度
tg.platform // 平台类型
// 版本
tg.version // WebApp 版本
```
**主要方法：**
```javascript
// 窗口控制
tg.ready() // 标记应用准备就绪
tg.expand() // 展开到全高度
tg.close() // 关闭 Mini App
tg.requestFullscreen() // 请求全屏
// 数据发送
tg.sendData(data) // 发送数据到 Bot
// 导航
tg.openLink(url) // 打开外部链接
tg.openTelegramLink(url) // 打开 Telegram 链接
// 对话框
tg.showPopup(params, callback) // 显示弹窗
tg.showAlert(message) // 显示警告
tg.showConfirm(message) // 显示确认
// 分享
tg.shareMessage(message) // 分享消息
tg.shareUrl(url) // 分享链接
```
### UI 控件
**主按钮 (MainButton)：**
```javascript
tg.MainButton.setText("点击我");
tg.MainButton.show();
tg.MainButton.enable();
tg.MainButton.showProgress(); // 显示加载
tg.MainButton.hideProgress();
tg.MainButton.onClick(() => {
console.log("主按钮被点击");
});
```
**次要按钮 (SecondaryButton)：**
```javascript
tg.SecondaryButton.setText("取消");
tg.SecondaryButton.show();
tg.SecondaryButton.onClick(() => {
tg.close();
});
```
**返回按钮 (BackButton)：**
```javascript
tg.BackButton.show();
tg.BackButton.onClick(() => {
// 返回逻辑
});
```
**触觉反馈：**
```javascript
tg.HapticFeedback.impactOccurred('light'); // light, medium, heavy
tg.HapticFeedback.notificationOccurred('success'); // success, warning, error
tg.HapticFeedback.selectionChanged();
```
### 存储 API
**云存储：**
```javascript
// 保存数据
tg.CloudStorage.setItem('key', 'value', (error, success) => {
if (success) console.log('保存成功');
});
// 获取数据
tg.CloudStorage.getItem('key', (error, value) => {
console.log('值:', value);
});
// 删除数据
tg.CloudStorage.removeItem('key');
// 获取所有键
tg.CloudStorage.getKeys((error, keys) => {
console.log('所有键:', keys);
});
```
**本地存储：**
```javascript
// 普通本地存储
localStorage.setItem('key', 'value');
const value = localStorage.getItem('key');
// 安全存储（需要生物识别）
tg.SecureStorage.setItem('secret', 'value', callback);
tg.SecureStorage.getItem('secret', callback);
```
### 生物识别认证
```javascript
const bioManager = tg.BiometricManager;
// 初始化
bioManager.init(() => {
if (bioManager.isInited) {
console.log('支持的类型:', bioManager.biometricType);
// 'finger', 'face', 'unknown'
if (bioManager.isAccessGranted) {
// 已授权，可以使用
} else {
// 请求授权
bioManager.requestAccess({reason: '需要验证身份'}, (success) => {
if (success) {
console.log('授权成功');
}
});
}
}
});
// 执行认证
bioManager.authenticate({reason: '确认操作'}, (success, token) => {
if (success) {
console.log('认证成功，token:', token);
}
});
```
### 位置和传感器
**获取位置：**
```javascript
tg.LocationManager.init(() => {
if (tg.LocationManager.isInited) {
tg.LocationManager.getLocation((location) => {
console.log('纬度:', location.latitude);
console.log('经度:', location.longitude);
});
}
});
```
**加速度计：**
```javascript
tg.Accelerometer.start({refresh_rate: 100}, (started) => {
if (started) {
tg.Accelerometer.onEvent((event) => {
console.log('加速度:', event.x, event.y, event.z);
});
}
});
// 停止
tg.Accelerometer.stop();
```
**陀螺仪：**
```javascript
tg.Gyroscope.start({refresh_rate: 100}, callback);
tg.Gyroscope.onEvent((event) => {
console.log('旋转速度:', event.x, event.y, event.z);
});
```
**设备方向：**
```javascript
tg.DeviceOrientation.start({refresh_rate: 100}, callback);
tg.DeviceOrientation.onEvent((event) => {
console.log('方向:', event.absolute, event.alpha, event.beta, event.gamma);
});
```
### 支付集成
**发起支付 (Telegram Stars)：**
```javascript
tg.openInvoice('https://t.me/$invoice_link', (status) => {
if (status === 'paid') {
console.log('支付成功');
} else if (status === 'cancelled') {
console.log('支付取消');
} else if (status === 'failed') {
console.log('支付失败');
}
});
```
### 数据验证
**服务器端验证 initData (Python)：**
```python
import hmac
import hashlib
from urllib.parse import parse_qs
def validate_init_data(init_data, bot_token):
# 解析数据
parsed = parse_qs(init_data)
received_hash = parsed.get('hash', [''])[0]
# 移除 hash
data_check_arr = []
for key, value in parsed.items():
if key != 'hash':
data_check_arr.append(f"{key}={value[0]}")
# 排序
data_check_arr.sort()
data_check_string = '\n'.join(data_check_arr)
# 计算密钥
secret_key = hmac.new(
b"WebAppData",
bot_token.encode(),
hashlib.sha256
).digest()
# 计算哈希
calculated_hash = hmac.new(
secret_key,
data_check_string.encode(),
hashlib.sha256
).hexdigest()
return calculated_hash == received_hash
```
### 启动 Mini App
**从键盘按钮：**
```python
keyboard = {
"keyboard": [[
{
"text": "打开应用",
"web_app": {"url": "https://yourdomain.com/app"}
}
]],
"resize_keyboard": True
}
requests.post(
f"{API_URL}/sendMessage",
json={
"chat_id": chat_id,
"text": "点击按钮打开应用",
"reply_markup": keyboard
}
)
```
**从内联按钮：**
```python
keyboard = {
reply_markup = {
"inline_keyboard": [[
{
"text": "启动应用",
"web_app": {"url": "https://yourdomain.com/app"}
}
{"text": "Open", "url": "https://example.com"},
{"text": "Action", "callback_data": "action:1"},
]]
}
```
**从菜单按钮：**
与 @BotFather 对话：
```
/setmenubutton
→ 选择你的 Bot
→ 提供 URL: https://yourdomain.com/app
```
## 客户端开发 (TDLib)
### 使用 TDLib
**Python 示例 (python-telegram)：**
**Answer a callback query**
```python
from telegram.client import Telegram
tg = Telegram(
api_id='your_api_id',
api_hash='your_api_hash',
phone='+1234567890',
database_encryption_key='changeme1234',
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/answerCallbackQuery",
json={"callback_query_id": callback_query_id, "text": "OK"},
)
tg.login()
# 发送消息
result = tg.send_message(
chat_id=123456789,
text='Hello from TDLib!'
)
# 获取聊天列表
result = tg.get_chats()
result.wait()
chats = result.update
print(chats)
tg.stop()
```
### MTProto 协议
**Initialize a Mini App**
```javascript
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
```
**特点：**
- 端到端加密
- 高性能
- 支持所有 Telegram 功能
- 需要 API ID/Hash（从 https://my.telegram.org 获取）
**Send Mini App data back to the bot**
```javascript
tg.sendData(JSON.stringify({ action: "submit" }));
```
## 最佳实践
**Validate Mini App initData server-side**
```text
Parse initData -> remove hash -> sort key=value pairs -> HMAC with WebAppData-derived secret -> compare hash.
```
### Bot 开发
## Examples
1. **错误处理**
```python
try:
response = requests.post(url, json=data, timeout=10)
response.raise_for_status()
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
```
### Example 1: Echo Bot with Long Polling
2. **速率限制**
- 群组消息：最多 20 条/分钟
- 私聊消息：最多 30 条/秒
- 全局限制：避免过于频繁
- Input: bot token and a private test chat.
- Steps:
1. Call `getUpdates` with an offset.
2. Extract `message.chat.id` and `message.text`.
3. Reply with `sendMessage` and advance offset.
- Expected output / acceptance: each user message gets one reply and old updates are not processed repeatedly.
3. **使用 Webhook 而非长轮询**
- 更高效
- 更低延迟
- 更好的可扩展性
### Example 2: Webhook Deployment
4. **数据验证**
- 始终验证 initData
- 不要信任客户端数据
- 服务器端验证所有操作
- Input: HTTPS URL `https://example.com/webhook`.
- Steps:
1. Deploy an endpoint that accepts POST JSON updates.
2. Call `setWebhook` with the public URL.
3. Use `getWebhookInfo` to verify status and last error.
- Expected output / acceptance: Telegram delivers updates to the endpoint and webhook info has no current delivery error.
### Mini Apps 开发
### Example 3: Mini App Button Flow
1. **响应式设计**
```javascript
// 监听主题变化
tg.onEvent('themeChanged', () => {
document.body.style.backgroundColor = tg.themeParams.bg_color;
});
// 监听视口变化
tg.onEvent('viewportChanged', () => {
console.log('新高度:', tg.viewportHeight);
});
```
- Input: web app URL and bot chat.
- Steps:
1. Send a reply or inline keyboard button with `web_app.url`.
2. In the Mini App, call `ready()` and validate `initData` on the backend.
3. Send final data with `sendData` or a backend API call.
- Expected output / acceptance: Mini App opens inside Telegram, backend authenticates the user, and bot receives structured data.
2. **性能优化**
- 最小化 JavaScript 包大小
- 使用懒加载
- 优化图片和资源
## References
3. **用户体验**
- 适配深色/浅色主题
- 使用原生 UI 控件（MainButton 等）
- 提供触觉反馈
- 快速响应用户操作
- `references/index.md`: Telegram ecosystem navigation and official links.
- `references/Telegram_Bot_按钮和键盘实现模板.md`: button and keyboard implementation templates.
- `references/动态视图对齐实现文档.md`: aligned data display and dynamic message formatting.
4. **安全考虑**
- HTTPS 强制
- 验证 initData
- 不在客户端存储敏感信息
- 使用 SecureStorage 存储密钥
## Maintenance
## 常用库和工具
### Python
- `python-telegram-bot` - 功能强大的 Bot 框架
- `aiogram` - 异步 Bot 框架
- `telethon` / `pyrogram` - MTProto 客户端
### Node.js
- `node-telegram-bot-api` - Bot API 包装器
- `telegraf` - 现代 Bot 框架
- `grammy` - 轻量级框架
### 其他语言
- PHP: `telegram-bot-sdk`
- Go: `telegram-bot-api`
- Java: `TelegramBots`
- C#: `Telegram.Bot`
## 参考资源
### 官方文档
- Bot API: https://core.telegram.org/bots/api
- Mini Apps: https://core.telegram.org/bots/webapps
- Mini Apps Platform: https://docs.telegram-mini-apps.com
- Telegram API: https://core.telegram.org
### GitHub 仓库
- Bot API 服务器: https://github.com/tdlib/telegram-bot-api
- Android 客户端: https://github.com/DrKLO/Telegram
- Desktop 客户端: https://github.com/telegramdesktop/tdesktop
- 官方组织: https://github.com/orgs/TelegramOfficial/repositories
### 工具
- @BotFather - 创建和管理 Bot
- https://my.telegram.org - 获取 API ID/Hash
- Telegram Web App 测试环境
## 参考文件
此技能包含详细的 Telegram 开发资源索引和完整实现模板：
- **index.md** - 完整的资源链接和快速导航
- **Telegram_Bot_按钮和键盘实现模板.md** - 交互式按钮和键盘实现指南（404 行，12 KB）
- 三种按钮类型详解（Inline/Reply/Command Menu）
- python-telegram-bot 和 Telethon 双实现对比
- 完整的即用代码示例和项目结构
- Handler 系统、错误处理和部署方案
- **动态视图对齐实现文档.md** - Telegram 数据展示指南（407 行，12 KB）
- 智能动态对齐算法（三步法，O(n×m) 复杂度）
- 等宽字体环境的完美对齐方案
- 智能数值格式化系统（B/M/K 自动缩写）
- 排行榜和数据表格专业展示
这些精简指南提供了核心的 Telegram Bot 开发解决方案：
- 按钮和键盘交互的所有实现方式
- 消息和数据的专业格式化展示
- 实用的最佳实践和快速参考
---
**使用此技能掌握 Telegram 生态的全栈开发！**
- Sources: local Telegram reference files plus official links listed in `references/index.md`.
- Last updated: 2026-04-28
- Known limits: API methods, limits, and Mini App capabilities are version-sensitive; verify against official Telegram docs for production releases.
assets/skills/timescaledb/SKILL.md
+97 -77
View File
@@ -1,108 +1,128 @@
---
name: timescaledb
description: TimescaleDB - PostgreSQL extension for high-performance time-series and event data analytics, hypertables, continuous aggregates, compression, and real-time analytics
description: "TimescaleDB time-series skill: PostgreSQL extension setup, hypertables, time_bucket queries, continuous aggregates, compression/columnstore, retention, performance, and migration troubleshooting."
---
# Timescaledb Skill
# timescaledb Skill
Comprehensive assistance with timescaledb development, generated from official documentation.
Use this skill to model and operate time-series workloads on TimescaleDB/Tiger Data using hypertables, time buckets, compression, and continuous aggregates.
## When to Use This Skill
This skill should be triggered when:
- Working with timescaledb
- Asking about timescaledb features or APIs
- Implementing timescaledb solutions
- Debugging timescaledb code
- Learning timescaledb best practices
Trigger when any of these applies:
- Creating or migrating PostgreSQL tables into TimescaleDB hypertables.
- Designing time-series schemas, chunk intervals, indexes, retention, or compression/columnstore policies.
- Writing `time_bucket` analytics queries or continuous aggregates.
- Debugging ingestion performance, query performance, refresh policies, or migration issues.
- Comparing plain PostgreSQL tables with TimescaleDB hypertables for event/time-series data.
## Not For / Boundaries
- Not a replacement for PostgreSQL fundamentals; use `postgresql` for generic SQL, transactions, roles, and non-time-series schema work.
- Do not enable retention/compression policies on production data without restore-tested backups and data-loss review.
- Continuous aggregates have version-specific behavior; verify real-time aggregation and refresh policy defaults against the installed version.
- Required inputs: TimescaleDB version, PostgreSQL version, table schema, time column, ingest rate, query patterns, retention/compression goals, and error text.
- Tiger Cloud features and self-hosted extension features may differ; verify deployment type before prescribing commands.
## Quick Reference
### Common Patterns
*Quick reference patterns will be added as you use the skill.*
### Example Code Patterns
**Example 1** (bash):
```bash
rails new my_app -d=postgresql
cd my_app
```
**Example 2** (ruby):
```ruby
gem 'timescaledb'
```
**Example 3** (shell):
```shell
kubectl create namespace timescale
```
**Example 4** (shell):
```shell
kubectl config set-context --current --namespace=timescale
```
**Example 5** (sql):
**Enable the extension**
```sql
DROP EXTENSION timescaledb;
CREATE EXTENSION IF NOT EXISTS timescaledb;
```
## Reference Files
**Create a time-series table**
```sql
CREATE TABLE conditions (
time timestamptz NOT NULL,
location text NOT NULL,
temperature double precision,
humidity double precision
);
```
This skill includes comprehensive documentation in `references/`:
**Convert a table to a hypertable**
```sql
SELECT create_hypertable('conditions', 'time');
```
- **api.md** - Api documentation
- **compression.md** - Compression documentation
- **continuous_aggregates.md** - Continuous Aggregates documentation
- **getting_started.md** - Getting Started documentation
- **hyperfunctions.md** - Hyperfunctions documentation
- **hypertables.md** - Hypertables documentation
- **installation.md** - Installation documentation
- **other.md** - Other documentation
- **performance.md** - Performance documentation
- **time_buckets.md** - Time Buckets documentation
- **tutorials.md** - Tutorials documentation
**Bucket raw data by hour**
```sql
SELECT
time_bucket('1 hour', time) AS bucket,
location,
avg(temperature) AS avg_temp
FROM conditions
GROUP BY bucket, location
ORDER BY bucket DESC;
```
Use `view` to read specific reference files when detailed information is needed.
**Create a continuous aggregate**
```sql
CREATE MATERIALIZED VIEW conditions_hourly
WITH (timescaledb.continuous) AS
SELECT
time_bucket('1 hour', time) AS bucket,
location,
avg(temperature) AS avg_temp
FROM conditions
GROUP BY bucket, location;
```
## Working with This Skill
**Inspect hypertable size**
```sql
SELECT * FROM hypertable_detailed_size('conditions');
```
### For Beginners
Start with the getting_started or tutorials reference files for foundational concepts.
**Verify extension version**
```sql
SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';
```
### For Specific Features
Use the appropriate category reference file (api, guides, etc.) for detailed information.
## Examples
### For Code Examples
The quick reference section above contains common patterns extracted from the official docs.
### Example 1: Convert Metrics Table to Hypertable
## Resources
- Input: existing table `conditions(time, location, temperature, humidity)`.
- Steps:
1. Confirm `time` is `NOT NULL` and uses a timestamp type.
2. Enable the extension.
3. Run `create_hypertable` in staging and test inserts/queries.
- Expected output / acceptance: the table is a hypertable and existing time-range queries still return correct rows.
### references/
Organized documentation extracted from official sources. These files contain:
- Detailed explanations
- Code examples with language annotations
- Links to original documentation
- Table of contents for quick navigation
### Example 2: Add Hourly Rollups
### scripts/
Add helper scripts here for common automation tasks.
- Input: dashboard needs hourly average temperature by location.
- Steps:
1. Write the raw `time_bucket('1 hour', time)` query.
2. Convert it to a continuous aggregate after correctness is verified.
3. Add a refresh policy only after deciding freshness and backfill windows.
- Expected output / acceptance: dashboard reads from the aggregate with documented refresh expectations.
### assets/
Add templates, boilerplate, or example projects here.
### Example 3: Performance Triage
## Notes
- Input: slow time-range query over a hypertable.
- Steps:
1. Run `EXPLAIN (ANALYZE, BUFFERS)` and confirm chunk pruning.
2. Check time predicate shape and indexes for dimension filters.
3. Inspect hypertable/chunk size and compression state before changing policies.
- Expected output / acceptance: root cause is classified as missing time predicate, bad index, chunk sizing, compression side effect, or stale stats.
- This skill was automatically generated from official documentation
- Reference files preserve the structure and examples from source docs
- Code examples include language detection for better syntax highlighting
- Quick reference patterns are extracted from common usage examples in the docs
## References
## Updating
- `references/index.md`: navigation for local TimescaleDB references.
- `references/installation.md`: install and deployment notes.
- `references/hypertables.md`: hypertables, chunks, sizing, and related APIs.
- `references/time_buckets.md`: `time_bucket` usage.
- `references/continuous_aggregates.md`: aggregate creation and refresh behavior.
- `references/compression.md`: compression/columnstore guidance.
- `references/performance.md`: performance notes.
- `references/tutorials.md`: walkthroughs and examples.
To refresh this skill with updated documentation:
1. Re-run the scraper with the same configuration
2. The skill will be rebuilt with the latest information
## Maintenance
- Sources: local `references/` extracted from TimescaleDB/Tiger Data documentation.
- Last updated: 2026-04-28
- Known limits: examples use common SQL forms; verify exact function signatures and policy defaults against the installed extension version.
assets/skills/twscrape/SKILL.md
+102 -392
View File
@@ -1,438 +1,148 @@
# twscrape
---
name: twscrape
description: "twscrape Twitter/X scraping skill: account pool setup, async search, user/tweet collection, CLI usage, proxy configuration, and rate-limit troubleshooting. Use when extracting public Twitter/X data with twscrape."
---
Python library for scraping Twitter/X data using GraphQL API with account rotation and session management.
# twscrape Skill
## When to use this skill
Use this skill to build or debug `twscrape` workflows for public Twitter/X data extraction with account rotation, async collection, CLI commands, and proxy-aware operation.
Use this skill when:
- Working with Twitter/X data extraction and scraping
- Need to bypass Twitter API limitations with account rotation
- Building social media monitoring or analytics tools
- Extracting tweets, user profiles, followers, trends from Twitter/X
- Need async/parallel scraping operations for large-scale data collection
- Looking for alternatives to official Twitter API
## When to Use This Skill
Trigger when any of these applies:
- Scraping Twitter/X search results, profiles, followers, timelines, replies, retweeters, media, or trends with `twscrape`.
- Setting up account pools, cookies, login flows, email verification, or account rotation.
- Choosing between Python async API and the `twscrape` CLI.
- Diagnosing rate limits, empty results, login failures, proxy failures, or suspended accounts.
- Exporting normalized tweet/user data for monitoring, analytics, research, or archival pipelines.
## Not For / Boundaries
- Not for bypassing access controls, private content, paid-only data, or platform restrictions.
- Not for guaranteed high-volume scraping; account health, platform changes, and endpoint limits can invalidate assumptions.
- Do not place real Twitter/X passwords, cookies, email passwords, or proxy credentials in examples, commits, logs, or issue reports.
- Required inputs: target query/user/tweet/list, collection limit, output format, account source, proxy requirements, and compliance constraints.
- If behavior differs from these notes, verify against `references/` and the upstream repository before changing production collectors.
## Quick Reference
### Installation
### Common Patterns
**Install the library**
```bash
pip install twscrape
```
### Basic Setup
**Create an API client and add a cookie-backed account**
```python
import asyncio
from twscrape import API, gather
from twscrape import API
async def main():
api = API() # Uses accounts.db by default
# Add accounts (with cookies - more stable)
cookies = "abc=12; ct0=xyz"
await api.pool.add_account("user1", "pass1", "email@example.com", "mail_pass", cookies=cookies)
# Or add accounts (with login/password - less stable)
await api.pool.add_account("user2", "pass2", "email2@example.com", "mail_pass2")
await api.pool.login_all()
asyncio.run(main())
api = API("accounts.db")
await api.pool.add_account(
"username",
"password",
"email@example.com",
"email-password",
cookies="ct0=...; auth_token=...",
)
```
### Common Operations
**Login all configured accounts**
```python
# Search tweets
await gather(api.search("elon musk", limit=20))
# Get user info
await api.user_by_login("xdevelopers")
user = await api.user_by_id(2244994945)
# Get user tweets
await gather(api.user_tweets(user_id, limit=20))
await gather(api.user_tweets_and_replies(user_id, limit=20))
await gather(api.user_media(user_id, limit=20))
# Get followers/following
await gather(api.followers(user_id, limit=20))
await gather(api.following(user_id, limit=20))
# Tweet operations
await api.tweet_details(tweet_id)
await gather(api.retweeters(tweet_id, limit=20))
await gather(api.tweet_replies(tweet_id, limit=20))
# Trends
await gather(api.trends("news"))
```
## Key Features
### 1. Multiple API Support
- **Search API**: Standard Twitter search functionality
- **GraphQL API**: Advanced queries and data extraction
- **Automatic switching**: Based on rate limits and availability
### 2. Async/Await Architecture
```python
# Parallel scraping
async for tweet in api.search("elon musk"):
print(tweet.id, tweet.user.username, tweet.rawContent)
```
### 3. Account Management
- Add multiple accounts for rotation
- Automatic rate limit handling
- Session persistence across runs
- Email verification support (IMAP or manual)
### 4. Data Models
- SNScrape-compatible models
- Easy conversion to dict/JSON
- Raw API response access available
## Core API Methods
### Search Operations
#### `search(query, limit, kv={})`
Search tweets by query string.
**Parameters:**
- `query` (str): Search query (supports Twitter search syntax)
- `limit` (int): Maximum number of tweets to return
- `kv` (dict): Additional parameters (e.g., `{"product": "Top"}` for Top tweets)
**Returns:** AsyncIterator of Tweet objects
**Example:**
```python
# Latest tweets
async for tweet in api.search("elon musk", limit=20):
print(tweet.rawContent)
# Top tweets
await gather(api.search("python", limit=20, kv={"product": "Top"}))
```
### User Operations
#### `user_by_login(username)`
Get user information by username.
**Example:**
```python
user = await api.user_by_login("xdevelopers")
print(user.id, user.displayname, user.followersCount)
```
#### `user_by_id(user_id)`
Get user information by user ID.
#### `followers(user_id, limit)`
Get user's followers.
#### `following(user_id, limit)`
Get users that the user follows.
#### `verified_followers(user_id, limit)`
Get only verified followers.
#### `subscriptions(user_id, limit)`
Get user's Twitter Blue subscriptions.
### Tweet Operations
#### `tweet_details(tweet_id)`
Get detailed information about a specific tweet.
#### `tweet_replies(tweet_id, limit)`
Get replies to a tweet.
#### `retweeters(tweet_id, limit)`
Get users who retweeted a specific tweet.
#### `user_tweets(user_id, limit)`
Get tweets from a user (excludes replies).
#### `user_tweets_and_replies(user_id, limit)`
Get tweets and replies from a user.
#### `user_media(user_id, limit)`
Get tweets with media from a user.
### Other Operations
#### `list_timeline(list_id)`
Get tweets from a Twitter list.
#### `trends(category)`
Get trending topics by category.
**Categories:** "news", "sport", "entertainment", etc.
## Account Management
### Adding Accounts
**With cookies (recommended):**
```python
cookies = "abc=12; ct0=xyz" # String or JSON format
await api.pool.add_account("user", "pass", "email@example.com", "mail_pass", cookies=cookies)
```
**With credentials:**
```python
await api.pool.add_account("user", "pass", "email@example.com", "mail_pass")
await api.pool.login_all()
```
### CLI Account Management
**Search recent tweets**
```python
from twscrape import gather
tweets = await gather(api.search("python lang:en", limit=50))
```
**Fetch a user then collect timeline data**
```python
user = await api.user_by_login("xdevelopers")
tweets = await gather(api.user_tweets(user.id, limit=100))
```
**Collect followers or following**
```python
followers = await gather(api.followers(user.id, limit=100))
following = await gather(api.following(user.id, limit=100))
```
**Inspect tweet details and replies**
```python
tweet = await api.tweet_details(1234567890)
replies = await gather(api.tweet_replies(tweet.id, limit=50))
```
**Use the CLI for a small search**
```bash
twscrape search "python lang:en" --limit=20
```
**Manage accounts from the CLI**
```bash
# Add accounts from file
twscrape add_accounts accounts.txt username:password:email:email_password
# Login all accounts
twscrape login_accounts
# Manual email verification
twscrape login_accounts --manual
# List accounts and status
twscrape accounts
# Re-login specific accounts
twscrape relogin user1 user2
# Retry failed logins
twscrape relogin_failed
```
## Proxy Configuration
### Per-Account Proxy
```python
proxy = "http://login:pass@example.com:8080"
await api.pool.add_account("user", "pass", "email@example.com", "mail_pass", proxy=proxy)
```
### Global Proxy
```python
api = API(proxy="http://login:pass@example.com:8080")
```
### Environment Variable
**Set a global proxy**
```bash
export TWS_PROXY=socks5://user:pass@127.0.0.1:1080
twscrape search "elon musk"
twscrape search "bitcoin" --limit=20
```
### Dynamic Proxy Changes
```python
api.proxy = "socks5://user:pass@127.0.0.1:1080"
doc = await api.user_by_login("elonmusk")
api.proxy = None # Disable proxy
```
**Priority:** `api.proxy` > `TWS_PROXY` env var > account-specific proxy
## CLI Usage
### Search Operations
```bash
twscrape search "QUERY" --limit=20
twscrape search "elon musk lang:es" --limit=20 > data.txt
twscrape search "python" --limit=20 --raw # Raw API responses
```
### User Operations
```bash
twscrape user_by_login USERNAME
twscrape user_by_id USER_ID
twscrape followers USER_ID --limit=20
twscrape following USER_ID --limit=20
twscrape verified_followers USER_ID --limit=20
twscrape user_tweets USER_ID --limit=20
```
### Tweet Operations
```bash
twscrape tweet_details TWEET_ID
twscrape tweet_replies TWEET_ID --limit=20
twscrape retweeters TWEET_ID --limit=20
```
### Trends
```bash
twscrape trends sport
twscrape trends news
```
### Custom Database
```bash
twscrape --db custom-accounts.db <command>
```
## Advanced Usage
### Raw API Responses
```python
async for response in api.search_raw("elon musk"):
print(response.status_code, response.json())
```
### Stopping Iteration
```python
from contextlib import aclosing
async with aclosing(api.search("elon musk")) as gen:
async for tweet in gen:
if tweet.id < 200:
break
```
### Convert Models to Dict/JSON
```python
user = await api.user_by_id(user_id)
user_dict = user.dict()
user_json = user.json()
```
### Enable Debug Logging
**Enable debug logging**
```python
from twscrape.logger import set_log_level
set_log_level("DEBUG")
```
## Environment Variables
## Examples
- **`TWS_PROXY`**: Global proxy for all accounts
Example: `socks5://user:pass@127.0.0.1:1080`
### Example 1: Search Export
- **`TWS_WAIT_EMAIL_CODE`**: Timeout for email verification (default: 30 seconds)
- Input: query `python lang:en`, limit `50`, output JSON Lines.
- Steps:
1. Confirm at least one healthy account with `twscrape accounts`.
2. Use `await gather(api.search(query, limit=50))`.
3. Serialize selected fields such as `id`, `date`, `user.username`, and `rawContent`.
- Expected output / acceptance: a JSONL file with up to 50 tweet records and no credentials in logs.
- **`TWS_RAISE_WHEN_NO_ACCOUNT`**: Raise exception when no accounts available instead of waiting
Values: `false`, `0`, `true`, `1` (default: `false`)
### Example 2: User Monitoring
## Rate Limits & Limitations
- Input: username `xdevelopers`, timeline limit `100`.
- Steps:
1. Resolve the account with `await api.user_by_login(username)`.
2. Collect `api.user_tweets(user.id, limit=100)`.
3. Store tweet IDs and timestamps so later runs can deduplicate.
- Expected output / acceptance: user metadata plus a deduplicated timeline batch.
### Rate Limits
- Rate limits reset **every 15 minutes** per endpoint
- Each account has **separate limits** for different operations
- Accounts automatically rotate when limits are reached
### Example 3: Rate-Limit Triage
### Tweet Limits
- `user_tweets` and `user_tweets_and_replies` return approximately **3,200 tweets maximum** per user
- This is a Twitter/X platform limitation
### Account Status
- Rate limits vary based on:
- Account age
- Account verification status
- Account activity history
### Handling Rate Limits
The library automatically:
- Switches to next available account
- Waits for rate limit reset if all accounts exhausted
- Tracks rate limit status per endpoint
## Common Patterns
### Large-Scale Data Collection
```python
async def collect_user_data(username):
user = await api.user_by_login(username)
# Collect tweets
tweets = await gather(api.user_tweets(user.id, limit=100))
# Collect followers
followers = await gather(api.followers(user.id, limit=100))
# Collect following
following = await gather(api.following(user.id, limit=100))
return {
'user': user,
'tweets': tweets,
'followers': followers,
'following': following
}
```
### Search with Filters
```python
# Language filter
await gather(api.search("python lang:en", limit=20))
# Date filter
await gather(api.search("AI since:2024-01-01", limit=20))
# From specific user
await gather(api.search("from:elonmusk", limit=20))
# With media
await gather(api.search("cats filter:media", limit=20))
```
### Batch Processing
```python
async def process_users(usernames):
tasks = []
for username in usernames:
task = api.user_by_login(username)
tasks.append(task)
users = await asyncio.gather(*tasks)
return users
```
## Troubleshooting
### Login Issues
- **Use cookies instead of credentials** for more stable authentication
- Enable **manual email verification** with `--manual` flag
- Check **email password** is correct for IMAP access
### Rate Limit Problems
- **Add more accounts** for better rotation
- **Increase wait time** between requests
- **Monitor account status** with `twscrape accounts`
### No Data Returned
- **Check account status** - they may be suspended or rate limited
- **Verify query syntax** - use Twitter search syntax
- **Try different accounts** - some may have better access
### Connection Issues
- **Configure proxy** if behind firewall
- **Check network connectivity**
- **Verify Twitter/X is accessible** from your location
## Resources
- **GitHub Repository**: https://github.com/vladkens/twscrape
- **Installation**: `pip install twscrape`
- **Development Version**: `pip install git+https://github.com/vladkens/twscrape.git`
- Input: collector returns no data or waits indefinitely.
- Steps:
1. Run `twscrape accounts` and identify locked, suspended, or rate-limited accounts.
2. Enable debug logging and retry the smallest failing query.
3. Add healthy accounts or wait for endpoint-specific reset before scaling up.
- Expected output / acceptance: the failing mode is classified as account health, query syntax, proxy/network, or platform limit.
## References
For detailed API documentation and examples, see the reference files in the `references/` directory:
- `references/index.md`: navigation for the local twscrape reference set.
- `references/installation.md`: installation and dependency notes.
- `references/account_management.md`: account pool, login, and rotation behavior.
- `references/api_methods.md`: Python API method reference.
- `references/cli_usage.md`: command-line usage.
- `references/proxy_config.md`: proxy configuration and precedence.
- `references/examples.md`: longer code examples and extraction patterns.
- `references/installation.md` - Installation and setup
- `references/api_methods.md` - Complete API method reference
- `references/account_management.md` - Account configuration and management
- `references/cli_usage.md` - Command-line interface guide
- `references/proxy_config.md` - Proxy configuration options
- `references/examples.md` - Code examples and patterns
## Maintenance
---
**Repository**: https://github.com/vladkens/twscrape
**Stars**: 1998+
**Language**: Python
**License**: MIT
- Sources: local `references/` extracted from upstream twscrape material and the upstream repository noted there.
- Last updated: 2026-04-28
- Known limits: Twitter/X endpoints and account policies change without notice; validate live collectors against a small sample before large runs.