diff --git a/AGENTS.md b/AGENTS.md index a2dee29..a5b2797 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,195 +1,149 @@ -# Repository Guidelines - +# Repository Guidelines + ## Project Structure & Module Organization - 根目录:`README.md` 给出全貌,`Makefile` 封装日常命令,`CONTRIBUTING.md` 说明贡献流程,`LICENSE` 载明协议。保持根目录扁平,避免巨石文件。 -- 多语言 i18n:`i18n//` 统一三层结构(documents / prompts / skills)。现有语言:中文 `zh`、英文 `en`、希伯来语 `he`,以及高频/常用的 `es`、`hi`、`ar`、`pt`、`ru`、`fr`、`de`、`ja`、`ko`、`it`、`tr`、`nl`、`pl`、`id`、`vi`、`th`、`fa`、`uk`、`bn`、`ta`、`ur`、`ms`、`sw`、`ha`;新增语言遵循同样层级。 -- 文档库:`i18n/zh/documents/` 仍是默认中文方法论入口(如 `i18n/zh/documents/模板与资源/代码组织.md` 等),新增语言文档按需在对应 `documents/` 下创建并保持同步。 -- 提示词资产:`i18n/zh/prompts/` 按角色拆分(system / assistant / coding / user),`libs/external/prompts-library/` 提供 Excel ↔ Markdown 互转工具与脚本目录,便于批量维护提示词,适合作为“单一真实来源”。 -- 代码与集成:`libs/` 预留核心实现骨架,`common/`、`database/`、`external/` 分别对应通用模型、存储适配与外部依赖登记;新增模块需保持分层边界与单一职责,避免跨层调用。 -- 备份:`backups/` 内含 `一键备份.sh` 与 `快速备份.py`,用于本地快照或同步,请先在隔离目录试跑,确认输出路径与权限。 - -## Build, Test, and Development Commands -- `make help`:列出所有 Make 目标,是新人快速上手的入口。 -- `make lint`:使用 `markdownlint-cli` 校验全仓库 Markdown,一旦新增文档请先跑通(需本地 Node/npm 环境,可用 `npm install -g markdownlint-cli` 安装)。 -- `make build` / `make test` / `make clean`:目前为占位,落地具体实现后务必更新脚本和说明;建议在 `Makefile` 旁补充注释并保持幂等,避免修改全局状态。 -- 提示词转换:进入 `libs/external/prompts-library/` 后执行 `python main.py` 按交互提示进行转换,运行前请确认虚拟环境、依赖与输出目录,并在完成后检查生成 Markdown 是否符合 lint 规则。 - -## Coding Style & Naming Conventions -- 文字层:文档、注释、日志使用中文;代码符号(函数 / 变量 / 模块)统一英文且语义直白,避免晦涩缩写。 -- 缩进与排版:全仓保持空格缩进(2 或 4 空格任选其一但不得混用);Markdown 列表、代码块与表格对齐清晰,行宽控制在 120 列内。Git diff 可读性优先。 -- 设计品味:优先消除分支与重复;函数力求单一职责且短小;命名遵循小写加中划线或下划线,不使用空格与特殊字符;跨模块接口保持稳定签名。 -- 依赖管理:新增工具或库时记录安装方式、最小版本与来源,必要时在 `i18n/zh/documents/模板与资源/工具集.md` 或 README 中补充,并说明为何需要它(性能、兼容、功能)。 - -## Testing Guidelines -- 当前无实测用例;引入代码时请至少提供最小可复现测试。推荐 Python 使用 `pytest`,文件命名 `test_*.py`,夹具精简可读,遵循 red-green-refactor 循环。 -- 文档与提示词改动:提交前运行 `make lint`;如转换脚本涉及数据,附带示例输入 / 输出说明或最小数据样例,确保可重复。 -- 覆盖率基线由模块维护者设定;若暂无标准,确保主流程和边界条件均可被测试验证,必要时在 PR 描述中写明未覆盖的风险,并建议后续补测计划。 - -## Commit & Pull Request Guidelines -- Commit 建议遵循简化 Conventional Commits:`feat|fix|docs|chore|refactor|test: scope – summary`,一句话说明行为与范围;避免笼统的 “update”。 -- PR 必填:变更摘要、动机或关联 Issue、测试与验证步骤(列出运行的命令与结果概览);涉及文档 / UI 的修改应附对比截图或链接,方便 reviewer 快速复核。 -- 提交前清单:跑通 `make lint`;若新增脚本 / 依赖,更新对应文档与 `Makefile` 目标;确认不携带临时文件或机密数据,并在描述中注明潜在风险或需要 reviewer 特别关注的点。 - -## Security & Configuration Tips -- 运行备份或转换脚本前,确认输出目录不会覆盖私有数据;建议先在临时目录试跑并检查生成文件,必要时使用只读副本。 -- 外部依赖来源记录在 `libs/external/` 目录下,增减依赖时同步维护,保持可追溯;引入第三方脚本需标明许可证与来源。 - -## Architecture Overview & Workflow -- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」,对应资产分别存放在 `i18n/zh/documents/`、`i18n/zh/prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。 -- 设计决策与目录结构更新后,请同步修订本文件与相关文档,确保团队共享同一真相源,减少口头约定与隐式规则。 - ---- - -# CLAUDE.md - -This file provides guidance to Claude series models when working with code in this repository. - -## Repository Overview - -This is the **Vibe Coding CN** repository, a workflow, toolset, and knowledge base for advanced AI-assisted programming. The project's core assets are its extensive `prompts` and `skills` libraries. - -## Key Commands - -### Prompt Library Management -```bash -# Enter the library directory -cd libs/external/prompts-library - -# Run the interactive conversion tool -python3 main.py -``` - -### Development & Maintenance -```bash -# Lint all markdown files in the repository -make lint - -# Create a full project backup (respects .gitignore) -bash backups/一键备份.sh -``` - -## Architecture & Structure - -### Core Directories -- **`i18n/zh/prompts/`**: The core asset. A massive, well-organized library of prompts. - - `coding_prompts/`, `system_prompts/`, `user_prompts/`, `meta_prompts/` -- **`i18n/zh/skills/`**: A modular library of skills for the AI, providing domain-specific knowledge for various tools like `ccxt`, `postgresql`, `telegram-dev`, -etc. -- **`i18n/zh/documents/`**: The project's knowledge base, containing methodology, principles, and guides. -- **`libs/external/prompts-library/`**: A Python-based tool for converting prompts between Excel and Markdown formats. -- **`backups/`**: Scripts for project backups. -- **`libs/`**: Skeleton for shared Python library code. - -### Key Technical Details -1. **Prompt Organization**: Prompts use a `(row,col)_` prefix for categorization. -2. **Conversion Tool**: The `prompts-library` uses Python with `pandas` and `openpyxl`. -3. **Documentation Standard**: User-facing documentation is in Chinese. Code, file names, and structure are in English. -4. **Skills**: The `skills` directory provides context and knowledge for specific tools and domains, each with its own `SKILL.md`. - -## Development Workflow - -When modifying this repository: -1. Follow the existing prompt and skill categorization systems. -2. Use the `prompts-library` tool to maintain consistency when updating prompts. -3. Run `make lint` after changing any Markdown files. -4. Run a backup with `bash backups/一键备份.sh` before any major refactoring. - ---- - -# GEMINI.md - 项目上下文文档 (Project Context Document) - -## 项目概述 (Project Overview) - -`vibe-coding-cn` 项目旨在提供一个通过与 AI 结对编程实现“将想法变为现实”的终极工作流程。它强调“规划驱动”和“模块化”的核心理念,旨在避免 AI 失控导致的项目混乱。该项目不仅仅是一个代码库,更是一个全面的 AI 结对编程指南、庞大的提示词库和模块化的技能工具集,涵盖了从项目构思、技术选型、实施规划到具体开发、调试和扩展的全过程。 - -**核心理念:** 规划是核心,通过结构化、模块化的方式引导 AI,确保项目可控、可维护。 - -## 技术栈 (Technology Stack) - -本项目主要的技术栈和相关工具包括: - -* **核心语言:** Python (用于 `prompts-library` 工具和备份脚本) -* **CLI 交互:** `rich`, `InquirerPy` (用于 `prompts-library` 提供友好的命令行界面) -* **数据处理:** `pandas`, `openpyxl` (用于 `prompts-library` 处理 Excel 文件) -* **配置管理:** `PyYAML` (用于 `prompts-library` 的配置) -* **文档规范:** `markdownlint-cli` (用于 `Makefile` 中的 `lint` 任务) -* **版本控制:** Git -* **自动化:** Makefile -* **操作系统:** 兼容 Linux - -## 主要功能与工作流程 (Key Features & Workflow) - -1. **AI 提示词库 (`i18n/zh/prompts/`):** - * 一个极其庞大和精细分类的提示词集合,是项目的核心资产。 - * `coding_prompts/`: 专注于编程和代码生成的提示词。 - * `system_prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。 - * `user_prompts/`: 用户自定义或常用的提示词。 - * `meta_prompts/`: 元提示词与提示工程辅助。 - -2. **提示词库管理工具 (`libs/external/prompts-library/`):** - * 提供 Python 工具 (`main.py`),用于在 Excel 工作簿 (`prompt_excel/`) 和 Markdown 文档 (`prompt_docs/`) 之间进行提示词的相互转换。 - * 支持交互式和非交互式操作。 - -3. **技能库 (`i18n/zh/skills/`):** - * 一个模块化的技能集合,为 AI 提供了特定工具和领域的知识。 - * 每个技能(如 `ccxt`, `postgresql`, `telegram-dev`)都包含独立的 `SKILL.md` 描述, 参考资料和脚本。 - -4. **项目备份工具 (`backups/`):** - * `快速备份.py` 脚本能根据 `.gitignore` 规则智能地打包项目文件为 `.tar.gz` 格式。 - -5. **知识库与文档 (`i18n/zh/documents/`):** - * 包含代码组织、开发经验、系统提示词构建原则、项目架构模板等各类文档。 - -6. **外部工具与个人配置 (`libs/external/`):** - * 存放非核心项目代码但有用的外部工具、个人配置或实验性代码。例如:`my-nvim/` (nvim 配置), `XHS-image-to-PDF-conversion/` (图片转PDF工具)。 - -## 文件结构 (File Structure) - +- 多语言 i18n:`i18n//` 统一三层结构(documents / prompts / skills)。现有语言:中文 `zh`、英文 `en`、希伯来语 `he`,以及 `es`、`hi`、`ar`、`pt`、`ru`、`fr`、`de`、`ja`、`ko`、`it`、`tr`、`nl`、`pl`、`id`、`vi`、`th`、`fa`、`uk`、`bn`、`ta`、`ur`、`ms`、`sw`、`ha`;新增语言遵循同样层级。 +- 文档库:`i18n/zh/documents/` 是默认中文方法论入口,含子目录:`方法论与原则/`、`模板与资源/`、`教程与指南/`、`外部资源聚合/`、`胶水编程/`、`从零开始vibecoding/` 等。 +- 提示词资产:`i18n/zh/prompts/` 按角色拆分(`system_prompts/`、`assistant_prompts/`、`coding_prompts/`、`user_prompts/`、`meta_prompts/`),`libs/external/prompts-library/` 提供 Excel ↔ Markdown 互转工具。 +- 技能库:`i18n/zh/skills/` 包含模块化技能集,如 `ccxt/`、`postgresql/`、`telegram-dev/`、`claude-code-guide/`、`claude-skills/` 等 16+ 个技能目录。 +- 代码与集成:`libs/` 预留核心实现骨架,`common/`(含 `models/`、`utils/`)、`database/`、`external/` 分别对应通用模型、存储适配与外部依赖。 +- 外部工具:`libs/external/` 含 `prompts-library/`、`l10n-tool/`、`my-nvim/`、`MCPlayerTransfer/`、`XHS-image-to-PDF-conversion/` 等。 +- 备份:`backups/` 内含 `一键备份.sh`、`快速备份.py` 和 `gz/` 存档目录。 +- 脚本:`scripts/` 目录预留项目脚本。 +- GitHub 配置:`.github/` 含 `ISSUE_TEMPLATE/`、`PULL_REQUEST_TEMPLATE.md`、`SECURITY.md`、`FUNDING.yml`。 + +## Build, Test, and Development Commands +- `make help`:列出所有 Make 目标。 +- `make lint`:使用 `markdownlint-cli` 校验全仓库 Markdown。 +- `make build` / `make test` / `make clean`:目前为占位。 +- 提示词转换:`cd libs/external/prompts-library && python main.py`。 +- 备份:`bash backups/一键备份.sh` 或 `python backups/快速备份.py`。 + +## Coding Style & Naming Conventions +- 文字层:文档、注释、日志使用中文;代码符号统一英文且语义直白。 +- 缩进与排版:全仓保持空格缩进(2 或 4 空格不混用);行宽控制在 120 列内。 +- 设计品味:优先消除分支与重复;函数单一职责且短小;命名小写加中划线或下划线。 +- 依赖管理:新增工具或库时记录安装方式、最小版本与来源。 + +## Testing Guidelines +- 当前无实测用例;引入代码时请至少提供最小可复现测试。 +- 文档与提示词改动:提交前运行 `make lint`。 +- 覆盖率基线由模块维护者设定。 + +## Commit & Pull Request Guidelines +- Commit 遵循简化 Conventional Commits:`feat|fix|docs|chore|refactor|test: scope – summary`。 +- PR 必填:变更摘要、动机或关联 Issue、测试与验证步骤。 +- 提交前清单:跑通 `make lint`;更新对应文档与 `Makefile` 目标;确认不携带临时文件或机密数据。 + +## Security & Configuration Tips +- 运行备份或转换脚本前,确认输出目录不会覆盖私有数据。 +- 外部依赖来源记录在 `libs/external/` 目录下,引入第三方脚本需标明许可证与来源。 + +## Architecture Overview & Workflow +- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」。 +- 设计决策与目录结构更新后,请同步修订本文件与相关文档。 + +--- + +# CLAUDE.md + +This file provides guidance to Claude series models when working with code in this repository. + +## Repository Overview + +This is the **Vibe Coding CN** repository, a workflow, toolset, and knowledge base for advanced AI-assisted programming. The project's core assets are its extensive `prompts` and `skills` libraries. + +## Key Commands + +```bash +# Prompt library conversion +cd libs/external/prompts-library && python3 main.py + +# Lint all markdown files +make lint + +# Create a full project backup +bash backups/一键备份.sh +``` + +## Architecture & Structure + +### Core Directories +- **`i18n/zh/prompts/`**: Core prompt library (`coding_prompts/`, `system_prompts/`, `user_prompts/`, `assistant_prompts/`, `meta_prompts/`) +- **`i18n/zh/skills/`**: Modular skills library (16+ skills including `ccxt`, `postgresql`, `telegram-dev`, `claude-skills`) +- **`i18n/zh/documents/`**: Knowledge base (`方法论与原则/`, `模板与资源/`, `教程与指南/`, `胶水编程/`, `从零开始vibecoding/`) +- **`libs/external/prompts-library/`**: Excel ↔ Markdown conversion tool +- **`libs/external/`**: External tools (`l10n-tool/`, `my-nvim/`, `MCPlayerTransfer/`) +- **`backups/`**: Backup scripts and archives +- **`scripts/`**: Project scripts placeholder + +### Key Technical Details +1. **Prompt Organization**: Prompts use `(row,col)_` prefix for categorization. +2. **Conversion Tool**: Uses Python with `pandas` and `openpyxl`. +3. **Documentation Standard**: User-facing docs in Chinese; code/filenames in English. +4. **Skills**: Each skill has its own `SKILL.md`. + +## Development Workflow + +1. Follow existing prompt and skill categorization systems. +2. Use `prompts-library` tool for prompt updates. +3. Run `make lint` after Markdown changes. +4. Run backup before major refactoring. + +--- + +# GEMINI.md - 项目上下文文档 + +## 项目概述 + +`vibe-coding-cn` 是一个通过与 AI 结对编程实现"将想法变为现实"的终极工作流程。强调"规划驱动"和"模块化"核心理念。 + +## 技术栈 + +- **核心语言:** Python +- **CLI 交互:** `rich`, `InquirerPy` +- **数据处理:** `pandas`, `openpyxl` +- **配置管理:** `PyYAML` +- **文档规范:** `markdownlint-cli` +- **版本控制:** Git +- **自动化:** Makefile + +## 文件结构 + ``` . -├── .gitignore # Git 版本控制忽略文件配置 -├── AGENTS.md # 面向 AI Agent 的贡献与行为准则。 -├── CLAUDE.md # 面向 Claude 模型的上下文与指令。 -├── CODE_OF_CONDUCT.md # 项目行为准则。 -├── CONTRIBUTING.md # 贡献指南。 -├── GEMINI.md # 面向 Gemini 模型的上下文与指令 (本文档)。 -├── LICENSE # 项目许可证。 -├── Makefile # 项目自动化脚本 (lint, backup 等)。 -├── README.md # 项目主文档,包含项目概览、使用指南等。 -│ -├── i18n/ -│ ├── zh/{documents,prompts,skills} # 中文主语料与方法论。 -│ ├── en/{documents,prompts,skills} # 英文版本资产。 -│ ├── he/{documents,prompts,skills} # 希伯来语(以色列)。 -│ ├── es|hi|ar|pt|ru|fr|de|ja|ko|it|tr|nl|pl|id|vi|th|fa|uk|bn|ta|ur|ms|sw|ha/{documents,prompts,skills} # 其他常用语言骨架。 +├── .github/ # GitHub 配置 (Issue/PR 模板, SECURITY, FUNDING) +├── AGENTS.md # AI Agent 行为准则 +├── CLAUDE.md # Claude 模型上下文 +├── GEMINI.md # Gemini 模型上下文 +├── CODE_OF_CONDUCT.md # 行为准则 +├── CONTRIBUTING.md # 贡献指南 +├── LICENSE # MIT 许可证 +├── Makefile # 自动化脚本 +├── README.md # 项目主文档 │ -├── libs/ # 核心库代码。 -│ ├── common/ # 通用功能和工具库。 -│ │ ├── __init__.py # Python 包初始化文件。 -│ │ ├── models/ # 数据模型定义。 -│ │ └── utils/ # 实用工具函数。 -│ ├── database/ # 数据库相关代码。 -│ └── external/ # 外部工具、个人配置或实验性代码。 -│ ├── prompts-library/ # 提示词库管理工具 (Excel-Markdown 互转)。 -│ │ ├── main.py # 提示词库管理工具主程序。 -│ │ ├── requirements.txt # 工具依赖。 -│ │ ├── prompt_excel/ # Excel 格式提示词。 -│ │ ├── prompt_docs/ # Markdown 格式提示词文档。 -│ │ └── ... (其他 prompts-library 内部文件) -│ ├── l10n-tool/ # 多语言批量翻译脚本,保护代码块,先机翻后润色。 -│ ├── my-nvim/ # 个人 Neovim 配置。 -│ └── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF 工具。 -│ -├── i18n/zh/prompts/ # 核心资产:AI 提示词库。 -│ ├── coding_prompts/ # 编程与代码生成相关提示词。 -│ ├── system_prompts/ # AI 系统级提示词(含 CLAUDE 版本目录)。 -│ ├── user_prompts/ # 用户自定义提示词。 -│ └── meta_prompts/ # 元提示词与提示工程辅助。 -│ -└── i18n/zh/skills/ # 模块化技能库。 - ├── ccxt/ # CCXT 加密货币交易库技能。 - ├── claude-code-guide/ # Claude Code 使用指南技能。 - ├── postgresql/ # PostgreSQL 数据库技能。 - ├── telegram-dev/ # Telegram Bot 开发技能。 - └── ... (其他 10+ 个技能) +├── i18n/ # 多语言资产 (29 种语言) +│ ├── zh/ # 中文主语料 +│ │ ├── documents/ # 文档库 (方法论/模板/教程/胶水编程等) +│ │ ├── prompts/ # 提示词库 (system/coding/user/assistant/meta) +│ │ └── skills/ # 技能库 (16+ 技能) +│ ├── en/ # 英文版本 +│ └── ... # 其他语言骨架 +│ +├── libs/ # 核心库代码 +│ ├── common/ # 通用模块 (models/, utils/) +│ ├── database/ # 数据库模块 +│ └── external/ # 外部工具 +│ ├── prompts-library/ # Excel-Markdown 互转工具 +│ ├── l10n-tool/ # 多语言翻译脚本 +│ ├── my-nvim/ # Neovim 配置 +│ ├── MCPlayerTransfer/ # MC 玩家迁移工具 +│ └── XHS-image-to-PDF-conversion/ +│ +├── backups/ # 备份脚本与存档 +│ ├── 一键备份.sh +│ ├── 快速备份.py +│ └── gz/ # 压缩存档 +│ +└── scripts/ # 项目脚本 ``` diff --git a/i18n/en/skills/README.md b/i18n/en/skills/README.md index 311407a..b3271a0 100644 --- a/i18n/en/skills/README.md +++ b/i18n/en/skills/README.md @@ -1,242 +1,241 @@ -TRANSLATED CONTENT: -# 🎯 AI Skills 技能库 +# 🎯 AI Skills Library -`i18n/zh/skills/` 目录存放 AI 技能(Skills),这些是比提示词更高级的能力封装,可以让 AI 在特定领域表现出专家级水平。当前包含 **14 个**专业技能。 +The `i18n/zh/skills/` directory stores AI Skills. These are advanced capability encapsulations, more sophisticated than simple prompts, that enable AI to perform at an expert level in specific domains. Currently includes **14** professional skills. -## 目录结构 +## Directory Structure ``` i18n/zh/skills/ -├── README.md # 本文件 +├── README.md # This file │ -├── # === 元技能(核心) === -├── claude-skills/ # ⭐ 元技能:生成 Skills 的 Skills(11KB) +├── # === Meta Skills (Core) === +├── claude-skills/ # ⭐ Meta Skill: Skills for Generating Skills (11KB) │ -├── # === Claude 工具 === -├── claude-code-guide/ # Claude Code 使用指南(9KB) -├── claude-cookbooks/ # Claude API 最佳实践(9KB) +├── # === Claude Tools === +├── claude-code-guide/ # Guide for using Claude Code (9KB) +├── claude-cookbooks/ # Best practices for Claude API (9KB) │ -├── # === 数据库 === -├── postgresql/ # ⭐ PostgreSQL 专家技能(76KB,最详细) -├── timescaledb/ # 时序数据库扩展(3KB) +├── # === Databases === +├── postgresql/ # ⭐ PostgreSQL Expert Skill (76KB, most detailed) +├── timescaledb/ # Time-series Database Extension (3KB) │ -├── # === 加密货币/量化 === -├── ccxt/ # 加密货币交易所统一 API(18KB) -├── coingecko/ # CoinGecko 行情 API(3KB) -├── cryptofeed/ # 加密货币实时数据流(6KB) -├── hummingbot/ # 量化交易机器人框架(4KB) -├── polymarket/ # 预测市场 API(6KB) +├── # === Cryptocurrency / Quant === +├── ccxt/ # Unified Cryptocurrency Exchange API (18KB) +├── coingecko/ # CoinGecko Market Data API (3KB) +├── cryptofeed/ # Cryptocurrency Real-time Data Stream (6KB) +├── hummingbot/ # Quant Trading Bot Framework (4KB) +├── polymarket/ # Prediction Market API (6KB) │ -├── # === 开发工具 === -├── telegram-dev/ # Telegram Bot 开发(18KB) -├── twscrape/ # Twitter/X 数据抓取(11KB) -├── snapdom/ # DOM 快照工具(8KB) -└── proxychains/ # 代理链配置(6KB) +├── # === Development Tools === +├── telegram-dev/ # Telegram Bot Development (18KB) +├── twscrape/ # Twitter/X Data Scraping (11KB) +├── snapdom/ # DOM Snapshot Tool (8KB) +└── proxychains/ # Proxy Chains Configuration (6KB) ``` -## Skills 一览表 +## Skills Overview Table -### 按文件大小排序(详细程度) +### Sorted by File Size (Detail Level) -| 技能 | 大小 | 领域 | 说明 | -|------|------|------|------| -| **postgresql** | 76KB | 数据库 | ⭐ 最详细,PostgreSQL 完整专家技能 | -| **telegram-dev** | 18KB | Bot 开发 | Telegram Bot 开发完整指南 | -| **ccxt** | 18KB | 交易 | 加密货币交易所统一 API | -| **twscrape** | 11KB | 数据采集 | Twitter/X 数据抓取 | -| **claude-skills** | 11KB | 元技能 | ⭐ 生成 Skills 的 Skills | -| **claude-code-guide** | 9KB | 工具 | Claude Code 使用最佳实践 | -| **claude-cookbooks** | 9KB | 工具 | Claude API 使用示例 | -| **snapdom** | 8KB | 前端 | DOM 快照与测试 | -| **cryptofeed** | 6KB | 数据流 | 加密货币实时数据流 | -| **polymarket** | 6KB | 预测市场 | Polymarket API 集成 | -| **proxychains** | 6KB | 网络 | 代理链配置与使用 | -| **hummingbot** | 4KB | 量化 | 量化交易机器人框架 | -| **timescaledb** | 3KB | 数据库 | PostgreSQL 时序扩展 | -| **coingecko** | 3KB | 行情 | CoinGecko 行情 API | +| Skill | Size | Domain | Description | +|---|---|---|---| +| **postgresql** | 76KB | Database | ⭐ Most detailed, complete PostgreSQL expert skill | +| **telegram-dev** | 18KB | Bot Development | Complete guide for Telegram Bot development | +| **ccxt** | 18KB | Trading | Unified API for cryptocurrency exchanges | +| **twscrape** | 11KB | Data Collection | Twitter/X data scraping | +| **claude-skills** | 11KB | Meta Skill | ⭐ Skills for Generating Skills | +| **claude-code-guide** | 9KB | Tools | Best practices for Claude Code usage | +| **claude-cookbooks** | 9KB | Tools | Claude API usage examples | +| **snapdom** | 8KB | Frontend | DOM snapshots and testing | +| **cryptofeed** | 6KB | Data Stream | Cryptocurrency real-time data stream | +| **polymarket** | 6KB | Prediction Market | Polymarket API integration | +| **proxychains** | 6KB | Network | Proxy chains configuration and usage | +| **hummingbot** | 4KB | Quant | Quant trading bot framework | +| **timescaledb** | 3KB | Database | PostgreSQL time-series extension | +| **coingecko** | 3KB | Market Data | CoinGecko Market Data API | -### 按领域分类 +### Categorized by Domain -#### 🔧 元技能与工具 +#### 🔧 Meta Skills & Tools -| 技能 | 说明 | 推荐场景 | -|------|------|----------| -| `claude-skills` | 生成 Skills 的 Skills | 创建新技能时必用 | -| `claude-code-guide` | Claude Code CLI 使用指南 | 日常开发 | -| `claude-cookbooks` | Claude API 最佳实践 | API 集成 | +| Skill | Description | Recommended Scenarios | +|---|---|---| +| `claude-skills` | Skills for Generating Skills | Essential for creating new skills | +| `claude-code-guide` | Claude Code CLI Usage Guide | Daily development | +| `claude-cookbooks` | Claude API Best Practices | API integration | -#### 🗄️ 数据库 +#### 🗄️ Databases -| 技能 | 说明 | 推荐场景 | -|------|------|----------| -| `postgresql` | PostgreSQL 完整指南(76KB) | 关系型数据库开发 | -| `timescaledb` | 时序数据库扩展 | 时间序列数据 | +| Skill | Description | Recommended Scenarios | +|---|---|---| +| `postgresql` | Complete PostgreSQL Guide (76KB) | Relational database development | +| `timescaledb` | Time-series Database Extension | Time-series data | -#### 💰 加密货币/量化 +#### 💰 Cryptocurrency / Quant -| 技能 | 说明 | 推荐场景 | -|------|------|----------| -| `ccxt` | 交易所统一 API | 多交易所对接 | -| `coingecko` | 行情数据 API | 价格查询 | -| `cryptofeed` | 实时数据流 | WebSocket 行情 | -| `hummingbot` | 量化交易框架 | 自动化交易 | -| `polymarket` | 预测市场 API | 预测市场交易 | +| Skill | Description | Recommended Scenarios | +|---|---|---| +| `ccxt` | Unified Exchange API | Multi-exchange integration | +| `coingecko` | Market Data API | Price queries | +| `cryptofeed` | Real-time Data Stream | WebSocket market data | +| `hummingbot` | Quant Trading Framework | Automated trading | +| `polymarket` | Prediction Market API | Prediction market trading | -#### 🛠️ 开发工具 +#### 🛠️ Development Tools -| 技能 | 说明 | 推荐场景 | -|------|------|----------| -| `telegram-dev` | Telegram Bot 开发 | Bot 开发 | -| `twscrape` | Twitter 数据抓取 | 社交媒体数据 | -| `snapdom` | DOM 快照 | 前端测试 | -| `proxychains` | 代理链配置 | 网络代理 | +| Skill | Description | Recommended Scenarios | +|---|---|---| +| `telegram-dev` | Telegram Bot Development | Bot development | +| `twscrape` | Twitter Data Scraping | Social media data | +| `snapdom` | DOM Snapshots | Frontend testing | +| `proxychains` | Proxy Chains Configuration | Network proxy | -## Skills vs Prompts 的区别 +## Difference Between Skills vs Prompts -| 维度 | Prompts(提示词) | Skills(技能) | -|------|------------------|----------------| -| 粒度 | 单次任务指令 | 完整能力封装 | -| 复用性 | 复制粘贴 | 配置后自动生效 | -| 上下文 | 需手动提供 | 内置领域知识 | -| 适用场景 | 临时任务 | 长期项目 | -| 结构 | 单文件 | 目录(含 assets/scripts/references) | +| Dimension | Prompts | Skills | +|---|---|---| +| Granularity | Single task instruction | Complete capability encapsulation | +| Reusability | Copy-paste | Automatically effective after configuration | +| Context | Needs manual provision | Built-in domain knowledge | +| Use Case | Temporary tasks | Long-term projects | +| Structure | Single file | Directory (includes assets/scripts/references) | -## 技能目录结构 +## Skill Directory Structure -每个技能遵循统一结构: +Each skill follows a unified structure: ``` skill-name/ -├── SKILL.md # 技能主文件,包含领域知识和规则 -├── assets/ # 静态资源(图片、配置模板等) -├── scripts/ # 辅助脚本 -└── references/ # 参考文档 +├── SKILL.md # Main skill file, contains domain knowledge and rules +├── assets/ # Static resources (images, config templates, etc.) +├── scripts/ # Helper scripts +└── references/ # Reference documents ``` -## 快速使用 +## Quick Start -### 1. 查看技能 +### 1. View a Skill ```bash -# 查看元技能 +# View meta-skill cat i18n/zh/skills/claude-skills/SKILL.md -# 查看 PostgreSQL 技能(最详细) +# View PostgreSQL skill (most detailed) cat i18n/zh/skills/postgresql/SKILL.md -# 查看 Telegram Bot 开发技能 +# View Telegram Bot development skill cat i18n/zh/skills/telegram-dev/SKILL.md ``` -### 2. 复制到项目中使用 +### 2. Copy to Project for Use ```bash -# 复制整个技能目录 +# Copy entire skill directory cp -r i18n/zh/skills/postgresql/ ./my-project/ -# 或只复制主文件到 CLAUDE.md +# Or just copy main file to CLAUDE.md cp i18n/zh/skills/postgresql/SKILL.md ./CLAUDE.md ``` -### 3. 结合 Claude Code 使用 +### 3. Use with Claude Code -在项目根目录创建 `CLAUDE.md`,引用技能: +Create `CLAUDE.md` in the project root, referencing skills: ```markdown -# 项目规则 +# Project Rules -请参考以下技能文件: +Please refer to the following skill files: @i18n/zh/skills/postgresql/SKILL.md @i18n/zh/skills/telegram-dev/SKILL.md ``` -## 创建自定义 Skill +## Create Custom Skill -### 方法一:使用元技能生成(推荐) +### Method 1: Generate using Meta Skill (Recommended) -1. 准备领域资料(文档、代码、规范) -2. 将资料和 `i18n/zh/skills/claude-skills/SKILL.md` 一起提供给 AI -3. AI 会生成针对该领域的专用 Skill +1. Prepare domain materials (documents, code, specifications) +2. Provide materials along with `i18n/zh/skills/claude-skills/SKILL.md` to AI +3. AI will generate a dedicated Skill for that domain ```bash -# 示例:让 AI 读取元技能后生成新技能 +# Example: Let AI generate a new skill after reading the meta-skill cat i18n/zh/skills/claude-skills/SKILL.md -# 然后告诉 AI:请根据这个元技能,为 [你的领域] 生成一个新的 SKILL.md +# Then tell AI: Based on this meta-skill, please generate a new SKILL.md for [your domain] ``` -### 方法二:手动创建 +### Method 2: Manual Creation ```bash -# 创建技能目录 +# Create skill directory mkdir -p i18n/zh/skills/my-skill/{assets,scripts,references} -# 创建主文件 +# Create main file cat > i18n/zh/skills/my-skill/SKILL.md << 'EOF' # My Skill -## 概述 -简要说明技能用途和适用场景 +## Overview +Briefly describe skill purpose and applicable scenarios -## 领域知识 -- 核心概念 -- 最佳实践 -- 常见模式 +## Domain Knowledge +- Core concepts +- Best practices +- Common patterns -## 规则与约束 -- 必须遵守的规则 -- 禁止的操作 -- 边界条件 +## Rules & Constraints +- Mandatory rules +- Prohibited operations +- Boundary conditions -## 示例 -具体的使用示例和代码片段 +## Examples +Specific usage examples and code snippets -## 常见问题 -FAQ 和解决方案 +## FAQ +FAQ and solutions EOF ``` -## 核心技能详解 +## Core Skill Details -### `claude-skills/SKILL.md` - 元技能 ⭐ +### `claude-skills/SKILL.md` - Meta Skill ⭐ -**生成 Skills 的 Skills**,是创建新技能的核心工具。 +**Skills for Generating Skills**, is the core tool for creating new skills. -使用方法: -1. 准备你的领域资料(文档、代码、规范等) -2. 将资料和 SKILL.md 一起提供给 AI -3. AI 会生成针对该领域的专用 Skill +Usage: +1. Prepare your domain materials (documents, code, specifications, etc.) +2. Provide materials along with SKILL.md to AI +3. AI will generate a dedicated Skill for that domain -### `postgresql/SKILL.md` - PostgreSQL 专家 ⭐ +### `postgresql/SKILL.md` - PostgreSQL Expert ⭐ -最详细的技能(76KB),包含: -- 数据库设计最佳实践 -- 查询优化技巧 -- 索引策略 -- 性能调优 -- 常见问题解决方案 -- SQL 代码示例 +The most detailed skill (76KB), includes: +- Database design best practices +- Query optimization techniques +- Indexing strategies +- Performance tuning +- Common problem solutions +- SQL code examples -### `telegram-dev/SKILL.md` - Telegram Bot 开发 +### `telegram-dev/SKILL.md` - Telegram Bot Development -完整的 Telegram Bot 开发指南(18KB): -- Bot API 使用 -- 消息处理 -- 键盘与回调 -- Webhook 配置 -- 错误处理 +Complete Telegram Bot development guide (18KB): +- Bot API usage +- Message handling +- Keyboards and callbacks +- Webhook configuration +- Error handling -### `ccxt/SKILL.md` - 加密货币交易所 API +### `ccxt/SKILL.md` - Cryptocurrency Exchange API -统一的交易所 API 封装(18KB): -- 支持 100+ 交易所 -- 统一的数据格式 -- 订单管理 -- 行情获取 +Unified exchange API encapsulation (18KB): +- Supports 100+ exchanges +- Unified data format +- Order management +- Market data retrieval -## 相关资源 +## Related Resources -- [Skills 生成器](https://github.com/yusufkaraaslan/Skill_Seekers) - 把任何资料转为 AI Skills -- [元技能文件](./claude-skills/SKILL.md) - 生成 Skills 的 Skills -- [提示词库](../prompts/) - 更细粒度的提示词集合 -- [Claude Code 指南](./claude-code-guide/SKILL.md) - Claude Code 使用最佳实践 -- [文档库](../documents/) - 方法论与开发经验 +- [Skills Generator](https://github.com/yusufkaraaslan/Skill_Seekers) - Convert any material into AI Skills +- [Meta Skill File](./claude-skills/SKILL.md) - Skills for Generating Skills +- [Prompt Library](../prompts/) - More granular prompt collections +- [Claude Code Guide](./claude-code-guide/SKILL.md) - Claude Code Usage Best Practices +- [Document Library](../documents/) - Methodologies and development experiences \ No newline at end of file diff --git a/i18n/en/skills/coingecko/SKILL.md b/i18n/en/skills/coingecko/SKILL.md index c3ec5b5..8259d9c 100644 --- a/i18n/en/skills/coingecko/SKILL.md +++ b/i18n/en/skills/coingecko/SKILL.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: --- 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. diff --git a/assets/demos/.gitkeep b/i18n/en/skills/coingecko/assets/.gitkeep similarity index 100% rename from assets/demos/.gitkeep rename to i18n/en/skills/coingecko/assets/.gitkeep diff --git a/i18n/en/skills/coingecko/references/authentication.md b/i18n/en/skills/coingecko/references/authentication.md index b857314..50406fd 100644 --- a/i18n/en/skills/coingecko/references/authentication.md +++ b/i18n/en/skills/coingecko/references/authentication.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Authentication **Pages:** 3 diff --git a/i18n/en/skills/coingecko/references/coins.md b/i18n/en/skills/coingecko/references/coins.md index 14dddd8..e512fb1 100644 --- a/i18n/en/skills/coingecko/references/coins.md +++ b/i18n/en/skills/coingecko/references/coins.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Coins **Pages:** 65 diff --git a/i18n/en/skills/coingecko/references/contract.md b/i18n/en/skills/coingecko/references/contract.md index 3e0a8d0..036a35d 100644 --- a/i18n/en/skills/coingecko/references/contract.md +++ b/i18n/en/skills/coingecko/references/contract.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Contract **Pages:** 1 diff --git a/i18n/en/skills/coingecko/references/exchanges.md b/i18n/en/skills/coingecko/references/exchanges.md index bdb9156..abecdb6 100644 --- a/i18n/en/skills/coingecko/references/exchanges.md +++ b/i18n/en/skills/coingecko/references/exchanges.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Exchanges **Pages:** 14 diff --git a/i18n/en/skills/coingecko/references/introduction.md b/i18n/en/skills/coingecko/references/introduction.md index 5d28279..57a727b 100644 --- a/i18n/en/skills/coingecko/references/introduction.md +++ b/i18n/en/skills/coingecko/references/introduction.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Introduction **Pages:** 4 diff --git a/i18n/en/skills/coingecko/references/llms-full.md b/i18n/en/skills/coingecko/references/llms-full.md index cebcd60..539d313 100644 --- a/i18n/en/skills/coingecko/references/llms-full.md +++ b/i18n/en/skills/coingecko/references/llms-full.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Changelog Source: https://docs.coingecko.com/changelog diff --git a/i18n/en/skills/coingecko/references/llms.md b/i18n/en/skills/coingecko/references/llms.md index f832776..6772ecc 100644 --- a/i18n/en/skills/coingecko/references/llms.md +++ b/i18n/en/skills/coingecko/references/llms.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # CoinGecko API ## Docs diff --git a/i18n/en/skills/coingecko/references/market_data.md b/i18n/en/skills/coingecko/references/market_data.md index e5b914d..8a20741 100644 --- a/i18n/en/skills/coingecko/references/market_data.md +++ b/i18n/en/skills/coingecko/references/market_data.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Market Data **Pages:** 3 diff --git a/i18n/en/skills/coingecko/references/nfts.md b/i18n/en/skills/coingecko/references/nfts.md index fb3313d..4a8e629 100644 --- a/i18n/en/skills/coingecko/references/nfts.md +++ b/i18n/en/skills/coingecko/references/nfts.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Nfts **Pages:** 2 diff --git a/i18n/en/skills/coingecko/references/other.md b/i18n/en/skills/coingecko/references/other.md index 5bc2843..ef02b52 100644 --- a/i18n/en/skills/coingecko/references/other.md +++ b/i18n/en/skills/coingecko/references/other.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Other **Pages:** 16 diff --git a/i18n/en/skills/coingecko/references/pricing.md b/i18n/en/skills/coingecko/references/pricing.md index b21fb65..ad690e2 100644 --- a/i18n/en/skills/coingecko/references/pricing.md +++ b/i18n/en/skills/coingecko/references/pricing.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Pricing **Pages:** 1 diff --git a/i18n/en/skills/coingecko/references/reference.md b/i18n/en/skills/coingecko/references/reference.md index af4e2aa..4fccf59 100644 --- a/i18n/en/skills/coingecko/references/reference.md +++ b/i18n/en/skills/coingecko/references/reference.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Reference **Pages:** 9 diff --git a/i18n/en/skills/coingecko/references/trending.md b/i18n/en/skills/coingecko/references/trending.md index d2b9941..656b6dc 100644 --- a/i18n/en/skills/coingecko/references/trending.md +++ b/i18n/en/skills/coingecko/references/trending.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Coingecko - Trending **Pages:** 2 diff --git a/assets/screenshots/.gitkeep b/i18n/en/skills/coingecko/scripts/.gitkeep similarity index 100% rename from assets/screenshots/.gitkeep rename to i18n/en/skills/coingecko/scripts/.gitkeep diff --git a/i18n/en/skills/cryptofeed/SKILL.md b/i18n/en/skills/cryptofeed/SKILL.md index 9d858f7..b76cf76 100644 --- a/i18n/en/skills/cryptofeed/SKILL.md +++ b/i18n/en/skills/cryptofeed/SKILL.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: --- 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. diff --git a/i18n/en/skills/cryptofeed/assets/.gitkeep b/i18n/en/skills/cryptofeed/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/i18n/en/skills/cryptofeed/references/README.md b/i18n/en/skills/cryptofeed/references/README.md index 282a9aa..f501fb7 100644 --- a/i18n/en/skills/cryptofeed/references/README.md +++ b/i18n/en/skills/cryptofeed/references/README.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Cryptocurrency Exchange Feed Handler [![License](https://img.shields.io/badge/license-XFree86-blue.svg)](LICENSE) ![Python](https://img.shields.io/badge/Python-3.8+-green.svg) diff --git a/i18n/en/skills/cryptofeed/references/index.md b/i18n/en/skills/cryptofeed/references/index.md index 22c50c4..f4baf7f 100644 --- a/i18n/en/skills/cryptofeed/references/index.md +++ b/i18n/en/skills/cryptofeed/references/index.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Cryptofeed Documentation Index ## Categories diff --git a/i18n/en/skills/cryptofeed/references/other.md b/i18n/en/skills/cryptofeed/references/other.md index 3cd4e88..4dae500 100644 --- a/i18n/en/skills/cryptofeed/references/other.md +++ b/i18n/en/skills/cryptofeed/references/other.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Cryptofeed - Other **Pages:** 1 diff --git a/i18n/en/skills/cryptofeed/scripts/.gitkeep b/i18n/en/skills/cryptofeed/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/i18n/en/skills/timescaledb/SKILL.md b/i18n/en/skills/timescaledb/SKILL.md index 21a2aa9..239ef09 100644 --- a/i18n/en/skills/timescaledb/SKILL.md +++ b/i18n/en/skills/timescaledb/SKILL.md @@ -1,109 +1,230 @@ -TRANSLATED CONTENT: --- name: timescaledb -description: TimescaleDB - PostgreSQL extension for high-performance time-series and event data analytics, hypertables, continuous aggregates, compression, and real-time analytics +description: Manage time-series data in PostgreSQL with TimescaleDB. Use this skill to install, configure, optimize, and interact with TimescaleDB for high-performance time-series data storage and analysis. This includes creating hypertables, continuous aggregates, handling data retention, and querying time-series data efficiently. --- -# Timescaledb Skill +# TimescaleDB Skill -Comprehensive assistance with timescaledb development, generated from official documentation. +Manage time-series data in PostgreSQL using TimescaleDB, extending PostgreSQL for high-performance time-series workloads. ## 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 +Use this skill when you need to: +- Work with time-series data in PostgreSQL +- Install and configure TimescaleDB +- Create and manage hypertables +- Optimize performance for time-series data +- Implement continuous aggregates for rollup data +- Manage data retention and compression +- Query and analyze time-series data +- Migrate existing PostgreSQL tables to hypertables +- Integrate with other PostgreSQL tools and extensions + +## Not For / Boundaries + +This skill is NOT for: +- General PostgreSQL administration (use a specific PostgreSQL skill for that) +- Deep database tuning unrelated to time-series performance +- Replacing dedicated time-series databases if TimescaleDB's PostgreSQL foundation is not a requirement +- Providing data visualization beyond basic SQL queries (use a BI tool or separate visualization library) ## Quick Reference -### Common Patterns +### Installation & Configuration -*Quick reference patterns will be added as you use the skill.* - -### Example Code Patterns - -**Example 1** (bash): +**Install TimescaleDB Extension (Debian/Ubuntu):** ```bash -rails new my_app -d=postgresql - cd my_app +sudo apt install -y postgresql-{{pg_version}}-timescaledb +sudo pg_createcluster {{pg_version}} main --start +sudo pg_ctlcluster {{pg_version}} main start +sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;" ``` +*(Replace `{{pg_version}}` with your PostgreSQL version, e.g., 16)* -**Example 2** (ruby): -```ruby -gem 'timescaledb' +**Configuration (postgresql.conf):** +```ini +# Add to postgresql.conf +shared_preload_libraries = 'timescaledb' +timescaledb.max_background_workers = 8 # Adjust based on CPU cores +max_connections = 100 # Adjust based on workload ``` +*(After changes, restart PostgreSQL: `sudo systemctl restart postgresql`)* -**Example 3** (shell): -```shell -kubectl create namespace timescale -``` +### Hypertables -**Example 4** (shell): -```shell -kubectl config set-context --current --namespace=timescale -``` - -**Example 5** (sql): +**Create Hypertables:** ```sql -DROP EXTENSION timescaledb; +CREATE TABLE sensor_data ( + time TIMESTAMPTZ NOT NULL, + device_id INT, + temperature DOUBLE PRECISION, + humidity DOUBLE PRECISION +); + +SELECT create_hypertable('sensor_data', 'time'); ``` -## Reference Files +**Convert Existing Table to Hypertable:** +```sql +SELECT create_hypertable('your_existing_table', 'time_column', migrate_data => true); +``` -This skill includes comprehensive documentation in `references/`: +**Show Hypertables:** +```sql +\d+ +SELECT * FROM timescaledb_information.hypertables; +``` -- **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 +### Continuous Aggregates -Use `view` to read specific reference files when detailed information is needed. +**Create Continuous Aggregate:** +```sql +CREATE MATERIALIZED VIEW device_hourly_summary +WITH (timescaledb.continuous) AS +SELECT + time_bucket('1 hour', time) AS bucket, + device_id, + AVG(temperature) AS avg_temp, + MAX(temperature) AS max_temp +FROM sensor_data +GROUP BY time_bucket('1 hour', time), device_id +WITH NO DATA; -- Initially create without data -## Working with This Skill +-- Refresh the continuous aggregate +CALL refresh_continuous_aggregate('device_hourly_summary', NULL, NULL); +``` -### For Beginners -Start with the getting_started or tutorials reference files for foundational concepts. +**Get Continuous Aggregates Info:** +```sql +SELECT * FROM timescaledb_information.continuous_aggregates; +``` -### For Specific Features -Use the appropriate category reference file (api, guides, etc.) for detailed information. +### Data Retention & Compression -### For Code Examples -The quick reference section above contains common patterns extracted from the official docs. +**Set Data Retention Policy (Drop data older than 3 months):** +```sql +SELECT add_retention_policy('sensor_data', INTERVAL '3 months'); +``` -## Resources +**Enable Compression (Compress data older than 7 days):** +```sql +ALTER TABLE sensor_data SET (timescaledb.compress = TRUE); +SELECT add_compression_policy('sensor_data', INTERVAL '7 days'); +``` -### 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 +**Show Compression Status:** +```sql +SELECT * FROM timescaledb_information.compression_settings; +``` -### scripts/ -Add helper scripts here for common automation tasks. +### Querying Time-Series Data -### assets/ -Add templates, boilerplate, or example projects here. +**Basic Time-Range Query:** +```sql +SELECT * FROM sensor_data +WHERE time >= NOW() - INTERVAL '1 day' + AND time < NOW() +ORDER BY time DESC; +``` -## Notes +**Gapfilling and Interpolation:** +```sql +SELECT + time_bucket('1 hour', time) AS bucket, + AVG(temperature) AS avg_temp, + locf(AVG(temperature)) OVER (ORDER BY time_bucket('1 hour', time)) AS avg_temp_locf +FROM sensor_data +GROUP BY bucket +ORDER BY bucket; +``` -- 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 +### High-Performance Queries -## Updating +**Approximate Count:** +```sql +SELECT COUNT(*) FROM sensor_data TABLESAMPLE BERNOULLI (1); +``` -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 +**Top-N Queries:** +```sql +SELECT time, device_id, temperature +FROM sensor_data +WHERE time >= NOW() - INTERVAL '1 day' +ORDER BY temperature DESC +LIMIT 10; +``` + +## Examples + +### Example 1: IoT Sensor Data Pipeline + +- Input: Stream of sensor readings (time, device_id, value) +- Steps: + 1. Create a hypertable for `iot_readings`. + 2. Ingest data into the hypertable. + 3. Create a continuous aggregate to compute hourly average readings. + 4. Query the continuous aggregate for a specific device's hourly trend. + 5. Set a retention policy to keep only 1 year of raw data. +- Expected output / acceptance: Efficient storage, automatic hourly rollups, and proper data pruning. + +### Example 2: Financial Tick Data Analysis + +- Input: High-frequency financial tick data (timestamp, symbol, price, volume) +- Steps: + 1. Create a hypertable `tick_data` with proper chunk sizing for high ingest rate. + 2. Enable compression for older `tick_data`. + 3. Query `tick_data` to calculate 5-minute VWAP (Volume Weighted Average Price) for a specific symbol. + 4. Visualize the VWAP over the last trading day. +- Expected output / acceptance: Ability to ingest and analyze millions of rows/second, with optimized storage and fast analytical queries. + +### Example 3: Monitoring System Metrics + +- Input: Server metrics (timestamp, host_id, cpu_usage, memory_usage, network_io) +- Steps: + 1. Create a hypertable `system_metrics` partitioned by `time` and `host_id`. + 2. Use a `time_bucket_gapfill` query to find CPU usage for all hosts over the last 24 hours, filling in missing data points. + 3. Create an alert based on `MAX(cpu_usage)` exceeding a threshold using a continuous aggregate. +- Expected output / acceptance: Comprehensive monitoring with gap-filled data for visualization and real-time alerting. + +## References + +- `references/installation.md`: Detailed installation and setup +- `references/hypertables.md`: Deep dive into hypertable management +- `references/continuous_aggregates.md`: Advanced continuous aggregate techniques +- `references/compression.md`: Comprehensive guide to data compression +- `references/api.md`: TimescaleDB SQL functions and commands reference +- `references/performance.md`: Performance tuning and best practices +- `references/getting_started.md`: Official TimescaleDB Getting Started Guide +- `references/llms.md`: Using TimescaleDB with LLMs (e.g., storing embeddings, RAG) +- `references/llms-full.md`: Full LLM integration scenarios +- `references/tutorials.md`: Official TimescaleDB Tutorials and Use Cases +- `references/time_buckets.md`: Guide to `time_bucket` and gapfilling functions +- `references/hyperfunctions.md`: Advanced analytical functions for time-series + +## Maintenance + +- Sources: Official TimescaleDB Documentation, GitHub repository, blog posts. +- Last updated: 2025-12-17 +- Known limits: This skill focuses on core TimescaleDB features. Advanced PostgreSQL features (e.g., PostGIS, JSONB) are covered by other specialized skills. + +## Troubleshooting + +### Slow Queries +- Ensure indexes are on `time` and other frequently queried columns. +- Verify chunk sizing is appropriate for your data ingestion rate. +- Use `EXPLAIN ANALYZE` to identify bottlenecks. +- Consider creating continuous aggregates for frequently accessed aggregated data. + +### High Disk Usage +- Implement data retention policies for older, less critical data. +- Enable compression for older chunks. +- Regularly run `VACUUM ANALYZE` on your tables. + +### Failed to Create Hypertable +- Ensure the `time` column is `TIMESTAMPTZ` or a supported integer type. +- The table must be empty or you must use `migrate_data => true`. +- Check for existing triggers or foreign keys that might conflict. + +--- + +**This skill provides a robust foundation for managing time-series data with TimescaleDB!** \ No newline at end of file diff --git a/i18n/en/skills/timescaledb/references/api.md b/i18n/en/skills/timescaledb/references/api.md index d44145c..824f5ed 100644 --- a/i18n/en/skills/timescaledb/references/api.md +++ b/i18n/en/skills/timescaledb/references/api.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Api **Pages:** 100 diff --git a/i18n/en/skills/timescaledb/references/compression.md b/i18n/en/skills/timescaledb/references/compression.md index 22a3a7b..b618ac0 100644 --- a/i18n/en/skills/timescaledb/references/compression.md +++ b/i18n/en/skills/timescaledb/references/compression.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Compression **Pages:** 19 diff --git a/i18n/en/skills/timescaledb/references/getting_started.md b/i18n/en/skills/timescaledb/references/getting_started.md index b44f1b5..d1b704d 100644 --- a/i18n/en/skills/timescaledb/references/getting_started.md +++ b/i18n/en/skills/timescaledb/references/getting_started.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Getting Started **Pages:** 3 diff --git a/i18n/en/skills/timescaledb/references/hyperfunctions.md b/i18n/en/skills/timescaledb/references/hyperfunctions.md index 0055737..b52cd3d 100644 --- a/i18n/en/skills/timescaledb/references/hyperfunctions.md +++ b/i18n/en/skills/timescaledb/references/hyperfunctions.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Hyperfunctions **Pages:** 34 diff --git a/i18n/en/skills/timescaledb/references/hypertables.md b/i18n/en/skills/timescaledb/references/hypertables.md index 28e9437..0c0eb83 100644 --- a/i18n/en/skills/timescaledb/references/hypertables.md +++ b/i18n/en/skills/timescaledb/references/hypertables.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Hypertables **Pages:** 103 diff --git a/i18n/en/skills/timescaledb/references/index.md b/i18n/en/skills/timescaledb/references/index.md index 1dc044c..27237af 100644 --- a/i18n/en/skills/timescaledb/references/index.md +++ b/i18n/en/skills/timescaledb/references/index.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb Documentation Index ## Categories diff --git a/i18n/en/skills/timescaledb/references/other.md b/i18n/en/skills/timescaledb/references/other.md index ed4a046..ab2794b 100644 --- a/i18n/en/skills/timescaledb/references/other.md +++ b/i18n/en/skills/timescaledb/references/other.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Other **Pages:** 248 diff --git a/i18n/en/skills/timescaledb/references/performance.md b/i18n/en/skills/timescaledb/references/performance.md index 4dfbe67..2abf614 100644 --- a/i18n/en/skills/timescaledb/references/performance.md +++ b/i18n/en/skills/timescaledb/references/performance.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Performance **Pages:** 2 diff --git a/i18n/en/skills/timescaledb/references/time_buckets.md b/i18n/en/skills/timescaledb/references/time_buckets.md index 0eacf24..1786965 100644 --- a/i18n/en/skills/timescaledb/references/time_buckets.md +++ b/i18n/en/skills/timescaledb/references/time_buckets.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Time Buckets **Pages:** 16 diff --git a/i18n/en/skills/timescaledb/references/tutorials.md b/i18n/en/skills/timescaledb/references/tutorials.md index afc90be..b412b53 100644 --- a/i18n/en/skills/timescaledb/references/tutorials.md +++ b/i18n/en/skills/timescaledb/references/tutorials.md @@ -1,4 +1,3 @@ -TRANSLATED CONTENT: # Timescaledb - Tutorials **Pages:** 12 diff --git a/i18n/en/skills/timescaledb/scripts/.gitkeep b/i18n/en/skills/timescaledb/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/i18n/zh/documents/模板与资源/通用项目架构模板.md b/i18n/zh/documents/模板与资源/通用项目架构模板.md index 97269c4..8f82645 100644 --- a/i18n/zh/documents/模板与资源/通用项目架构模板.md +++ b/i18n/zh/documents/模板与资源/通用项目架构模板.md @@ -455,6 +455,241 @@ build-backend = "setuptools.build_meta" --- +在**编程 / 软件开发**里,**项目架构(Project Architecture / Software Architecture)**指的是: + +> **一个项目在“整体层面”是如何被拆分、组织、通信和演进的设计方案** +> ——它决定了代码怎么分层、模块怎么分工、数据怎么流动、系统如何扩展和维护。 + +--- + +## 一句话理解 + +**项目架构 = 不写具体业务代码之前,就先决定“代码怎么放、模块怎么连、职责怎么分”。** + +--- + +## 一、项目架构主要解决什么问题? + +项目架构不是“写代码的技巧”,而是解决这些**更高层问题**: + +* 📦 代码怎么组织才不乱? +* 🔁 模块之间怎么通信? +* 🧱 哪些地方可以独立修改而不影响全局? +* 🚀 项目以后怎么扩展? +* 🧪 如何方便测试、调试、部署? +* 👥 多人协作如何不互相踩代码? + +--- + +## 二、项目架构一般包含哪些内容? + +### 1️⃣ 目录结构(最直观) + +```text +project/ +├── src/ +│ ├── main/ +│ ├── services/ +│ ├── models/ +│ ├── utils/ +│ └── config/ +├── tests/ +├── docs/ +└── README.md +``` + +👉 决定 **“不同类型代码放哪里”** + +--- + +### 2️⃣ 分层设计(核心) + +最常见的是 **分层架构(Layered Architecture)**: + +```text +表示层(UI / API) + ↓ +业务逻辑层(Service) + ↓ +数据访问层(DAO / Repository) + ↓ +数据库 / 外部系统 +``` + +**规则:** + +* 上层可以调用下层 +* 下层不能反过来依赖上层 + +--- + +### 3️⃣ 模块划分(职责边界) + +比如一个交易系统: + +```text +- market_data # 行情 +- strategy # 策略 +- risk # 风控 +- order # 下单 +- account # 账户 +``` + +👉 每个模块: + +* 只做一类事情 +* 尽量低耦合、高内聚 + +--- + +### 4️⃣ 数据与控制流 + +* 数据从哪里来? +* 谁负责处理? +* 谁负责存储? +* 谁负责对外输出? + +例如: + +```text +WebSocket → 数据清洗 → 指标计算 → AI评分 → SQLite → API → 前端 +``` + +--- + +### 5️⃣ 技术选型(架构的一部分) + +* 编程语言(Python / Java / Go) +* 框架(FastAPI / Spring / Django) +* 通信方式(HTTP / WebSocket / MQ) +* 存储(SQLite / Redis / PostgreSQL) +* 部署(本地 / Docker / 云) + +--- + +## 三、常见项目架构类型(入门必懂) + +### 1️⃣ 单体架构(Monolith) + +```text +一个项目,一个进程 +``` + +**适合:** + +* 个人项目 +* 原型 +* 小系统 + +**优点:** + +* 简单 +* 好调试 + +**缺点:** + +* 后期难扩展 + +--- + +### 2️⃣ 分层架构(最常见) + +```text +Controller → Service → Repository +``` + +**适合:** + +* Web 后端 +* 业务系统 + +--- + +### 3️⃣ 模块化架构 + +```text +core + plugins +``` + +**适合:** + +* 可插拔系统 +* 策略 / 指标系统 + +👉 **你做量化、AI分析,非常适合这个** + +--- + +### 4️⃣ 微服务架构(进阶) + +```text +每个服务一个独立进程 + API 通信 +``` + +**适合:** + +* 大团队 +* 高并发 +* 长期演进 + +❌ **新手不建议一开始用** + +--- + +## 四、用一个“真实例子”理解(贴近你现在做的) + +假设你做 **币安永续 AI 分析系统**: + +```text +backend/ +├── data/ +│ └── binance_ws.py # 行情订阅 +├── indicators/ +│ └── vpvr.py +├── strategy/ +│ └── signal_score.py +├── storage/ +│ └── sqlite_writer.py +├── api/ +│ └── http_server.py +└── main.py +``` + +这就是**项目架构设计**: + +* 每个文件夹只负责一件事 +* 可替换、可测试 +* 后面想接 Telegram Bot / Web 前端都不用重写核心 + +--- + +## 五、初学者常见误区 ⚠️ + +❌ 一开始就搞微服务 +❌ 所有代码写在一个文件 +❌ 架构追求“高级感”,而不是“可维护” +❌ 没想清楚数据流就开始写 + +--- + +## 六、学习路线建议(很重要) + +你现在学 CS,很推荐这个顺序: + +1. **先写能跑的项目(不完美)** +2. **代码开始乱 → 才学架构** +3. 学会: + + * 模块拆分 + * 分层 + * 依赖方向 +4. 再学: + + * 设计模式 + * 微服务 / 消息队列 + +--- + **版本**: 1.0 **更新日期**: 2025-11-24 **维护**: CLAUDE,CODEX,KIMI