refactor(doc): 重命名 Gotify 中文指南文件路径

- 将文件从 openclaw-plugins/doc/gotify/zh 目录移至 openclaw-plugins/doc/gotify 目录
- 更新文档内部相对链接以匹配新路径
- 优化目录结构，简化文档访问路径

AWESOME_AGENT_SKILLS.md

@@ -0,0 +1,539 @@
+# Awesome Agent Skills
+
+_Generated at 2026-05-28T16:23:30.883477Z_
+
+## angular-skills
+- [angular](skills/angular-skills/angular) — Provides comprehensive guidance for Angular framework including components, modules, services, dependency injection, routing, forms, and ...
+
+## antd-skills
+- [ant-design-mini](skills/antd-skills/ant-design-mini) — Provides comprehensive guidance for Ant Design Mini component library for mini-programs including components, themes, and platform suppor...
+- [ant-design-mobile](skills/antd-skills/ant-design-mobile) — Provides comprehensive guidance for Ant Design Mobile component library including mobile components, themes, and platform adaptations. Us...
+- [ant-design-react](skills/antd-skills/ant-design-react) — Provides comprehensive guidance for Ant Design React component library including components, design system, themes, and TypeScript suppor...
+- [ant-design-vue](skills/antd-skills/ant-design-vue) — Provides comprehensive guidance for Ant Design Vue (AntDV) component library for Vue 3. Covers installation, usage, API reference, templa...
+
+## ascii-skills
+- [ascii-ansi-colorizer](skills/ascii-skills/ascii-ansi-colorizer) — Add an ANSI color layer to existing ASCII/plain-text output (gradient/rainbow/highlights) with alignment-safe rules and a required no-col...
+- [ascii-cli-logo-banner](skills/ascii-skills/ascii-cli-logo-banner) — Entry point for ASCII CLI banners. Choose the Python built-in font skill or the figlet.js/FIGfont skill depending on needs.
+- [ascii-cli-logo-banner-figletjs](skills/ascii-skills/ascii-cli-logo-banner-figletjs) — Generate TAAG/FIGlet-style ASCII art banners using figlet.js (FIGfont spec), with layout controls (horizontal/vertical layout, width, whi...
+- [ascii-cli-logo-banner-python](skills/ascii-skills/ascii-cli-logo-banner-python) — Generate copy-pastable ASCII banners with a built-in font (no external font deps), including compact fallback and optional ANSI 256 color...
+- [ascii-diagram-boxflow](skills/ascii-skills/ascii-diagram-boxflow) — Generate plain ASCII box-flow diagrams (boxes + arrows) for environments without renderers, with alignment rules and split strategies for...
+- [ascii-image-to-ascii](skills/ascii-skills/ascii-image-to-ascii) — Convert an image into ASCII art (readable + detail variants, width/charset controls, optional ANSI), for terminal previews and plain-text...
+- [ascii-mini-charts](skills/ascii-skills/ascii-mini-charts) — Generate ASCII mini charts (sparkline/bar/simple line) for plain-text trend inspection, with minimal + annotated variants and normalizati...
+- [ascii-motd-profile-banner](skills/ascii-skills/ascii-motd-profile-banner) — Generate ASCII-only MOTD / SSH login banner / shell profile welcome messages (short/long variants, quiet mode guidance, security notices).
+- [ascii-progress-and-spinner](skills/ascii-skills/ascii-progress-and-spinner) — Design ASCII progress bars and spinners for CLI UX (determinate/indeterminate, TTY single-line refresh, non-interactive log fallback) wit...
+- [ascii-table-renderer](skills/ascii-skills/ascii-table-renderer) — Render structured data as aligned ASCII tables (column width rules, truncate/wrap, border styles, compact/readable variants) for terminal...
+- [ascii-terminal-animation-pack](skills/ascii-skills/ascii-terminal-animation-pack) — Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a stat...
+- [ascii-text-art-library](skills/ascii-skills/ascii-text-art-library) — Generate a reusable ASCII-only text template library (titles, dividers, notice boxes, slogans/CTA), with naming conventions and selection...
+- [cli-ascii-logo](skills/ascii-skills/cli-ascii-logo) — 生成 CLI 的 ASCII 艺术 Logo/Banner（支持 box drawing 边框、█ 块字符、ANSI 24-bit 渐变色）并提供可运行脚本与集成代码。适用于“做一个像 Spec Kit CLI 的终端 Logo / 彩色 ASCII banner / fi...
+
+## avue-skills
+- [avue](skills/avue-skills/avue) — Provides comprehensive guidance for Avue framework including CRUD operations, form components, and data management. Use when the user ask...
+- [avue-crud](skills/avue-skills/avue-crud) — Provides comprehensive guidance for Avue CRUD component including table operations, form handling, and data management. Use when the user...
+- [avue-form](skills/avue-skills/avue-form) — Provides comprehensive guidance for Avue Form component including form configuration, validation, and dynamic forms. Use when the user as...
+
+## base-skills
+- [skill-awesome](skills/base-skills/skill-awesome) — Turn scattered Agent Skills docs, specs, best practices, and skill examples into a curated, searchable “awesome list” in Markdown. Use wh...
+- [skill-official-evaluation](skills/base-skills/skill-official-evaluation) — Produce an evaluation conclusion for any Agent Skill based on official Agent Skills specifications and official best practices. Use when ...
+- [skill-trace-evaluation](skills/base-skills/skill-trace-evaluation) — Evaluate any Agent Skill using the SkillHub TRACE model (Trust, Reliability, Adaptability, Convention, Effectiveness) and produce a per-d...
+
+## build-skills
+- [dart-sass](skills/build-skills/dart-sass) — Provides comprehensive guidance for Dart Sass including Sass syntax, compilation, mixins, functions, and best practices. Use when the use...
+- [parcel](skills/build-skills/parcel) — Provides comprehensive guidance for Parcel bundler including zero-configuration setup, asset handling, hot module replacement, and produc...
+- [rollup](skills/build-skills/rollup) — Provides comprehensive guidance for Rollup bundler including configuration, plugins, code splitting, tree shaking, and library bundling. ...
+- [rspack](skills/build-skills/rspack) — Provides comprehensive guidance for Rspack bundler including configuration, plugins, loaders, optimization, and Webpack compatibility. Us...
+- [vite](skills/build-skills/vite) — Guidance for Vite using the official Guide, Config Reference, and Plugins pages. Use when the user needs Vite setup, configuration, or pl...
+- [webpack](skills/build-skills/webpack) — Provides comprehensive guidance for Webpack bundler including configuration, loaders, plugins, code splitting, optimization, and developm...
+
+## chart-skills
+- [lime-echart](skills/chart-skills/lime-echart) — Provides comprehensive guidance for Lime ECharts including chart creation, configuration, data visualization, and interactive charts. Use...
+- [ucharts](skills/chart-skills/ucharts) — Provides comprehensive guidance for uCharts chart library including chart types, data formats, chart configuration, and platform support....
+
+## cocos-skills
+- [cocos2d-x](skills/cocos-skills/cocos2d-x) — Provides comprehensive guidance for Cocos2d-x v4 game engine including scene graph, nodes, sprites, actions, animations, physics, renderi...
+
+## database-skills
+- [dbeaver](skills/database-skills/dbeaver) — Provides comprehensive guidance for DBeaver including database connection, SQL development, data management, and ER diagrams. Use when th...
+- [elasticsearch](skills/database-skills/elasticsearch) — Provides comprehensive guidance for Elasticsearch including indexing, searching, aggregations, mappings, and cluster management. Use when...
+- [oracle](skills/database-skills/oracle) — Provides comprehensive guidance for Oracle database including SQL, PL/SQL, database administration, and Oracle-specific features. Use whe...
+- [postgresql](skills/database-skills/postgresql) — Provides comprehensive guidance for PostgreSQL database including SQL syntax, advanced features, JSON support, full-text search, and perf...
+- [redis](skills/database-skills/redis) — Provides comprehensive guidance for Redis including data structures, commands, pub/sub, persistence, clustering, and caching patterns. Us...
+
+## ddd-skills
+- [clean-ddd-hexagonal](skills/ddd-skills/clean-ddd-hexagonal) — Proactively apply when designing APIs, microservices, or scalable backend structure. Triggers on DDD, Clean Architecture, Hexagonal, port...
+- [ddd-architecture-awesome](skills/ddd-skills/ddd-architecture-awesome) — Provides comprehensive guidance for Domain-Driven Design (DDD) concepts, strategic design, tactical design, and architecture patterns. Us...
+- [ddd-clean-architecture](skills/ddd-skills/ddd-clean-architecture) — Provides comprehensive guidance for clean architecture including layer separation, dependency rules, and architectural patterns. Use when...
+- [ddd-cola](skills/ddd-skills/ddd-cola) — Provides comprehensive guidance for COLA architecture including adapter layer, application layer, domain layer, and infrastructure layer....
+- [ddd-event-driven](skills/ddd-skills/ddd-event-driven) — Provides comprehensive guidance for event-driven architecture including domain events, event sourcing, CQRS, and event patterns. Use when...
+- [ddd-hexagonal-architecture](skills/ddd-skills/ddd-hexagonal-architecture) — Provides comprehensive guidance for hexagonal architecture including ports and adapters, domain isolation, and dependency inversion. Use ...
+- [ddd-microservices](skills/ddd-skills/ddd-microservices) — Provides comprehensive guidance for DDD in microservices including bounded contexts, service boundaries, event-driven architecture, and m...
+- [ddd4j-project-creator](skills/ddd-skills/ddd4j-project-creator) — |
+
+## design-skills
+- [adobe-xd](skills/design-skills/adobe-xd) — Provides comprehensive guidance for Adobe XD including design creation, prototyping, components, and collaboration. Use when the user ask...
+- [algorithmic-art](skills/design-skills/algorithmic-art) — Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating a...
+- [brand-guidelines](skills/design-skills/brand-guidelines) — Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. ...
+- [canvas-design](skills/design-skills/canvas-design) — Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a ...
+
+## dev-utils-skills
+- [agent-browser](skills/dev-utils-skills/agent-browser) — A comprehensive skill for using agent-browser, a CLI tool for browser automation designed for AI agents, developed by Vercel Labs. This s...
+- [code-generator](skills/dev-utils-skills/code-generator) — Provides comprehensive guidance for code generation including template-based generation, code scaffolding, and automated code creation. U...
+- [documentation-builder](skills/dev-utils-skills/documentation-builder) — Provides comprehensive guidance for building documentation including documentation generation, formatting, and documentation best practic...
+- [frontend-design](skills/dev-utils-skills/frontend-design) — Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web compone...
+- [java-code-comments](skills/dev-utils-skills/java-code-comments) — |
+- [maven-search](skills/dev-utils-skills/maven-search) — Provides comprehensive guidance for searching and retrieving Maven components from Maven Central Repository (https://repo1.maven.org/mave...
+- [mcp-builder](skills/dev-utils-skills/mcp-builder) — Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-des...
+- [mybatis-plus-generator](skills/dev-utils-skills/mybatis-plus-generator) — |
+- [test-writer](skills/dev-utils-skills/test-writer) — Provides comprehensive guidance for writing tests including test case creation, test structure, and testing best practices. Use when the ...
+- [theme-factory](skills/dev-utils-skills/theme-factory) — Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-se...
+- [web-artifacts-builder](skills/dev-utils-skills/web-artifacts-builder) — Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind C...
+- [webapp-testing](skills/dev-utils-skills/webapp-testing) — Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI...
+
+## devops-skills
+- [ansible](skills/devops-skills/ansible) — Provides comprehensive guidance for Ansible automation including playbooks, roles, inventory, and module usage. Use when the user asks ab...
+- [cloudformation](skills/devops-skills/cloudformation) — Provides comprehensive guidance for AWS CloudFormation including templates, stacks, parameters, and infrastructure automation. Use when t...
+- [github-actions](skills/devops-skills/github-actions) — Provides comprehensive guidance for GitHub Actions including workflow creation, actions, secrets, and automation. Use when the user asks ...
+- [gitlab-ci](skills/devops-skills/gitlab-ci) — Provides comprehensive guidance for GitLab CI/CD including pipeline configuration, runners, artifacts, and automation. Use when the user ...
+- [kubernetes](skills/devops-skills/kubernetes) — Provides comprehensive guidance for Kubernetes including pods, services, deployments, ingress, and cluster management. Use when the user ...
+- [terraform](skills/devops-skills/terraform) — Provides comprehensive guidance for Terraform including infrastructure as code, providers, modules, and state management. Use when the us...
+
+## docker-skills
+- [docker](skills/docker-skills/docker) — Provides comprehensive guidance for Docker including container creation, images, Dockerfile, docker-compose, and container management. Us...
+- [docker-compose](skills/docker-skills/docker-compose) — Provides comprehensive guidance for Docker Compose including multi-container applications, service definition, networking, and volumes. U...
+
+## document-skills
+- [api-doc-generator](skills/document-skills/api-doc-generator) — |
+- [doc-coauthoring](skills/document-skills/doc-coauthoring) — Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technica...
+- [full-stack-doc](skills/document-skills/full-stack-doc) — >
+- [mermaid](skills/document-skills/mermaid) — Provides comprehensive guidance for creating Mermaid diagrams. Mermaid is a JavaScript-based diagramming and charting tool that uses Mark...
+- [plantuml](skills/document-skills/plantuml) — Provides comprehensive guidance for creating PlantUML diagrams. PlantUML is a component that allows you to create various UML diagrams th...
+- [processon-diagram-generator](skills/document-skills/processon-diagram-generator) — |
+- [processon-mindmap](skills/document-skills/processon-mindmap) — Provides comprehensive guidance for ProcessOn mind mapping including mind map creation, node management, and collaboration. Use when the ...
+- [technical-blog-doc](skills/document-skills/technical-blog-doc) — >
+
+## drawio-skills
+- [drawio-architecture](skills/drawio-skills/drawio-architecture) — Provides comprehensive guidance for draw.io architecture diagrams including diagram creation, shapes, templates, and collaboration. Use w...
+- [drawio-flowchart](skills/drawio-skills/drawio-flowchart) — Provides comprehensive guidance for draw.io flowcharts including flowchart creation, shapes, connectors, and diagramming. Use when the us...
+
+## electron-skills
+- [electron](skills/electron-skills/electron) — Provides comprehensive guidance for Electron framework including main process, renderer process, IPC communication, window management, an...
+- [electron-egg](skills/electron-skills/electron-egg) — Provides comprehensive guidance for Electron EGG framework including project structure, main/renderer processes, IPC, window management, ...
+- [upgradeLink](skills/electron-skills/upgradeLink) — Provides comprehensive guidance for upgrade link management including upgrade link creation, configuration, and upgrade link best practic...
+
+## flutter-skills
+- [flutter](skills/flutter-skills/flutter) — Provides comprehensive guidance for Flutter development including widgets, state management, navigation, platform channels, and mobile ap...
+- [flutter-project-creater](skills/flutter-skills/flutter-project-creater) — Provides one-command project creation for Flutter including project initialization, configuration, and template generation. Use when the ...
+
+## go-skills
+- [gin](skills/go-skills/gin) — Provides comprehensive guidance for Gin Go framework including routing, middleware, request handling, JSON binding, and API development. ...
+- [gin-gonic](skills/go-skills/gin-gonic) — Provides comprehensive guidance for Gin-Gonic framework including routing, middleware, validation, and best practices. Use when the user ...
+
+## jimeng-skills
+- [jimeng-cli-image2image](skills/jimeng-skills/jimeng-cli-image2image) — Provides comprehensive guidance for executing image-to-image (图生图) editing via the dreamina CLI for 即梦 models 4.0+. Image-to-image CLI re...
+- [jimeng-cli-image2video](skills/jimeng-skills/jimeng-cli-image2video) — Provides comprehensive guidance for executing image-to-video (图生视频) generation via the dreamina CLI for 即梦. This skill covers 4 sub-comma...
+- [jimeng-cli-text2image](skills/jimeng-skills/jimeng-cli-text2image) — Provides comprehensive guidance for executing text-to-image generation via the dreamina CLI for 即梦 (Dreamina/Jimeng). The dreamina CLI is...
+- [jimeng-cli-text2video](skills/jimeng-skills/jimeng-cli-text2video) — Provides comprehensive guidance for executing text-to-video generation via the dreamina CLI for 即梦 Seedance 2.0 models. Video generation ...
+- [jimeng-prompt-image2image](skills/jimeng-skills/jimeng-prompt-image2image) — Provides comprehensive guidance for crafting image-to-image (图生图) edit prompts for 即梦 (Dreamina/Jimeng) models 4.0+. Uses a Keep/Change f...
+- [jimeng-prompt-image2video](skills/jimeng-skills/jimeng-prompt-image2video) — Provides comprehensive guidance for crafting image-to-video (图生视频) prompts for 即梦 (Dreamina/Jimeng) Seedance 2.0. Image-to-video prompts ...
+- [jimeng-prompt-text2image](skills/jimeng-skills/jimeng-prompt-text2image) — Provides comprehensive guidance for crafting text-to-image prompts for 即梦 (Dreamina/Jimeng) AI image generation. Use when the user wants ...
+- [jimeng-prompt-text2video](skills/jimeng-skills/jimeng-prompt-text2video) — "Provides comprehensive guidance for crafting text-to-video prompts for 即梦 (Dreamina/Jimeng) video models (视频3.0 Pro, Doubao Seedance 2.0...
+
+## journey
+- [ddd-api-designer](skills/ddd-skills/journey/ddd-api-designer) — 从领域模型到 API/契约设计（Journey）。基于命令/事件/读模型输出 OpenAPI、DTO 设计、错误码、事件契约（schemaVersion）与 BFF 编排边界建议。
+- [ddd-architecture-awesome](skills/ddd-skills/journey/ddd-architecture-awesome) — DDD 入门与适用性判断（Journey 入口）。当用户问“什么是 DDD”“要不要用 DDD”“DDD vs 三层”“充血模型”等，输出可执行的判断结论、学习路径与下一步技能推荐。
+- [ddd-architecture-doc](skills/ddd-skills/journey/ddd-architecture-doc) — 架构文档生成（Journey）。基于 DDD 交付物与代码结构，生成架构概览、ADR、C4（Context/Container/Component）、上下文地图与事件流说明。
+- [ddd-architecture-selector](skills/ddd-skills/journey/ddd-architecture-selector) — DDD 架构选型与边界策略（Journey）。当用户需要在 DDD 四层/六边形/整洁/COLA/CQRS/微服务拆分之间做选择时，输出结构化决策结果、目录模板与边界交付物清单。
+- [ddd-code-reviewer](skills/ddd-skills/journey/ddd-code-reviewer) — DDD 红线门禁与评分（Journey）。扫描/审查现有代码的分层依赖、领域纯净、聚合边界、事件治理与 DTO/DO/PO 穿层等反模式，输出 P0/P1/P2 违规清单与修复建议。
+- [ddd-cola-creator](skills/ddd-skills/journey/ddd-cola-creator) — COLA 工程骨架与目录生成指导（Journey）。输出 COLA 分层目录、模块依赖规则、聚合包示例与最小可运行骨架；不限定 ddd4j（如明确 ddd4j 则改用 ddd4j-project-creator）。
+- [ddd-cola-validator](skills/ddd-skills/journey/ddd-cola-validator) — COLA/分层依赖方向合规检查（Journey）。对项目分层职责与依赖方向做门禁，输出违规清单、严重级别与整改建议。
+- [ddd-cqrs-implementer](skills/ddd-skills/journey/ddd-cqrs-implementer) — CQRS 与读模型落地（Journey）。输出 CQRS 等级选择、读写模型边界、读模型/主题视图清单、投影同步机制与一致性 SLA。
+- [ddd-domain-modeling](skills/ddd-skills/journey/ddd-domain-modeling) — 事件风暴到领域模型的完整建模（Journey）。针对业务场景输出限界上下文、聚合、不变式、领域事件与“领域模型⇄代码模型映射表”等可验收产物。
+- [ddd-eventing-governance](skills/ddd-skills/journey/ddd-eventing-governance) — 事件驱动工程化治理（Journey）。把领域事件从“概念”落成“可运维机制”：Outbox、幂等、重试死信、补偿对账、版本兼容与可观测性。
+
+## mobile-native-skills
+- [android-kotlin](skills/mobile-native-skills/android-kotlin) — Provides comprehensive guidance for Android development with Kotlin including activities, fragments, views, lifecycle, navigation, and An...
+- [ios-swift](skills/mobile-native-skills/ios-swift) — Provides comprehensive guidance for iOS development with Swift including view controllers, views, navigation, lifecycle, and iOS app deve...
+
+## nodejs-skills
+- [express](skills/nodejs-skills/express) — Provides comprehensive guidance for Express.js framework including routing, middleware, request handling, templating, and API development...
+- [fastify](skills/nodejs-skills/fastify) — Provides comprehensive guidance for Fastify framework including routing, plugins, schemas, hooks, and performance optimization. Use when ...
+- [koa](skills/nodejs-skills/koa) — Provides comprehensive guidance for Koa.js framework including middleware, context, async/await patterns, and application structure. Use ...
+- [nestjs](skills/nodejs-skills/nestjs) — Provides comprehensive guidance for NestJS using the official documentation. Use when the user asks about NestJS architecture, controller...
+
+## nvm-skills
+- [nvm](skills/nvm-skills/nvm) — Guidance for installing, configuring, and using nvm (Node Version Manager) based on the official README. Use when the user needs to manag...
+- [nvm-defaults-and-nvmrc](skills/nvm-skills/nvm-defaults-and-nvmrc) — Define default Node versions and manage project-specific versions with .nvmrc and auto-use flows.
+- [nvm-docker-ci](skills/nvm-skills/nvm-docker-ci) — Cover nvm installation and usage in Docker images and CI/CD pipelines, including non-interactive shell loading.
+- [nvm-global-packages](skills/nvm-skills/nvm-global-packages) — Migrate global packages between Node versions and define a default global packages file for consistency.
+- [nvm-install](skills/nvm-skills/nvm-install) — Provide comprehensive guidance for installing and updating nvm from the official README, including install scripts, profile selection, an...
+- [nvm-mirror-and-auth](skills/nvm-skills/nvm-mirror-and-auth) — Configure Node.js binary mirrors and authentication headers for restricted or 10、Company Manger network environments.
+- [nvm-misc](skills/nvm-skills/nvm-misc) — Provide nvm overview, output color customization, tests, and automation examples like Ansible. Use when users ask for an nvm intro, color...
+- [nvm-project-meta](skills/nvm-skills/nvm-project-meta) — Provide nvm project metadata like maintainers, support policy, enterprise support, license, and copyright notice. Use when users ask abou...
+- [nvm-setup](skills/nvm-skills/nvm-setup) — Configure shell initialization and environment variables so nvm loads correctly across bash, zsh, and fish.
+- [nvm-shell-integration](skills/nvm-skills/nvm-shell-integration) — Enable deeper shell integration and auto-switching for nvm across bash, zsh, and fish.
+- [nvm-troubleshooting-linux](skills/nvm-skills/nvm-troubleshooting-linux) — Diagnose common nvm issues on Linux and WSL, including distro differences, profiles, and PATH errors.
+- [nvm-troubleshooting-macos](skills/nvm-skills/nvm-troubleshooting-macos) — Diagnose common nvm issues on macOS, including profile loading, PATH priority, and permissions.
+- [nvm-uninstall](skills/nvm-skills/nvm-uninstall) — Remove nvm cleanly, including NVM_DIR cleanup, profile edits, and PATH restoration.
+- [nvm-usage-basics](skills/nvm-skills/nvm-usage-basics) — Cover everyday nvm usage for installing, switching, and listing Node versions, including LTS and system node.
+- [nvm-verify](skills/nvm-skills/nvm-verify) — Verify nvm installation and diagnose PATH or profile loading issues after setup.
+
+## ocrmypdf-skills
+- [ocrmypdf](skills/ocrmypdf-skills/ocrmypdf) — OCRmyPDF core skill — add searchable OCR text layer to scanned PDFs, convert images to searchable PDFs, support 100+ languages via Tesser...
+- [ocrmypdf-api](skills/ocrmypdf-skills/ocrmypdf-api) — OCRmyPDF Python API and plugin skill — use OCRmyPDF programmatically from Python, integrate with applications, and extend with plugins (E...
+- [ocrmypdf-batch](skills/ocrmypdf-skills/ocrmypdf-batch) — OCRmyPDF batch processing skill — process multiple PDFs, Docker automation, shell scripting, and CI/CD integration. Use when the user nee...
+- [ocrmypdf-image](skills/ocrmypdf-skills/ocrmypdf-image) — OCRmyPDF image processing skill — deskew, rotate, clean, despeckle, remove border from scanned documents. Use when the user needs to impr...
+- [ocrmypdf-optimize](skills/ocrmypdf-skills/ocrmypdf-optimize) — OCRmyPDF optimization skill — compress PDFs, configure PDF/A output, JBIG2 encoding, and lossless optimization. Use when the user needs t...
+
+## openspec-skills
+- [openspec-apply](skills/openspec-skills/openspec-apply) — Implement tasks from the change using `/opsx:apply`, working through the task list and checking off items. Use when the user says "implem...
+- [openspec-archive](skills/openspec-skills/openspec-archive) — Archive a completed change with `/opsx:archive`, merging delta specs into main specs and preserving the change for history. Use when the ...
+- [openspec-bulk-archive](skills/openspec-skills/openspec-bulk-archive) — Archive multiple completed changes at once with `/opsx:bulk-archive`, handling spec conflicts between changes. Use when the user says "ar...
+- [openspec-config](skills/openspec-skills/openspec-config) — Configure OpenSpec project settings and global CLI configuration using `openspec/config.yaml` and `openspec config` commands. Use when th...
+- [openspec-continue](skills/openspec-skills/openspec-continue) — Create the next artifact in the dependency chain with `/opsx:continue`, building up a change incrementally. Use when the user says "conti...
+- [openspec-explore](skills/openspec-skills/openspec-explore) — Think through ideas, investigate problems, and clarify requirements before committing to a change using `/opsx:explore`. Use when the use...
+- [openspec-ff](skills/openspec-skills/openspec-ff) — Fast-forward through artifact creation with `/opsx:ff`, generating all planning artifacts (proposal, specs, design, tasks) at once. Use w...
+- [openspec-initial](skills/openspec-skills/openspec-initial) — Run `openspec init` to initialize OpenSpec in a project directory, creating the openspec/ folder structure and configuring AI tool integr...
+- [openspec-install](skills/openspec-skills/openspec-install) — Install the OpenSpec CLI globally via npm, pnpm, yarn, bun, or nix. Use when the user says "install OpenSpec", "set up OpenSpec", or "ope...
+- [openspec-new](skills/openspec-skills/openspec-new) — Start a new OpenSpec change with `/opsx:new`, creating a change folder with metadata and scaffolding. Use when the user says "start a new...
+- [openspec-onboard](skills/openspec-skills/openspec-onboard) — Guided onboarding through the complete OpenSpec workflow using `/opsx:onboard`, walking the user through a real change in their codebase....
+- [openspec-schema](skills/openspec-skills/openspec-schema) — Create and manage custom workflow schemas using `openspec schema init/fork/validate/which`. Use when the user says "create a custom workf...
+- [openspec-sync](skills/openspec-skills/openspec-sync) — Sync delta specs from a change into main specs using `/opsx:sync`, without archiving the change. Use when the user says "sync specs", "me...
+- [openspec-update](skills/openspec-skills/openspec-update) — Run `openspec update` to regenerate AI tool instruction files after upgrading the OpenSpec CLI. Use when the user says "update OpenSpec",...
+- [openspec-verify](skills/openspec-skills/openspec-verify) — Validate that implementation matches change artifacts using `/opsx:verify`, checking completeness, correctness, and coherence. Use when t...
+
+## pencil-skills
+- ["pencil"](skills/pencil-skills/pencil) — "用于通过 Pencil MCP 读取/修改 .pen 设计文件并校验布局。用户提到 pencil/.pen/设计稿编辑、需要列出工具或执行 batch_get/batch_design 时调用。"
+- [pencil-design-from-stitch-html](skills/pencil-skills/pencil-design-from-stitch-html) — "When you need to turn Stitch page HTML (or a Stitch URL) into a Pencil .pen design. Parses DOM and Tailwind, applies HTML→Pencil mapping...
+- [pencil-mcp-batch-design](skills/pencil-skills/pencil-mcp-batch-design) — Batch execute design changes. The Agent's 'Hands'. Core capability for inserting, updating, moving, or deleting nodes.
+- [pencil-mcp-batch-get](skills/pencil-skills/pencil-mcp-batch-get) — Batch search and read node information. The Agent's 'Eyes'. Use to find specific components e.g. all nodes named 'Button' or get child st...
+- [pencil-mcp-find-empty-space-on-canvas](skills/pencil-skills/pencil-mcp-find-empty-space-on-canvas) — Smartly find empty canvas space. Use to automatically plan artboard placement to avoid overlap and keep the canvas organized.
+- [pencil-mcp-get-editor-state](skills/pencil-skills/pencil-mcp-get-editor-state) — Get current design environment context. Use when you need to understand what is currently selected, canvas position, and environment stat...
+- [pencil-mcp-get-guidelines](skills/pencil-skills/pencil-mcp-get-guidelines) — Get design system guidelines. Use to read and understand specifications e.g. Material Design iOS HIG or custom specs before designing.
+- [pencil-mcp-get-screenshot](skills/pencil-skills/pencil-mcp-get-screenshot) — Get node visual screenshot. Visual Verification. Use to capture screenshots after operations to verify if the design meets expectations.
+- [pencil-mcp-get-style-guide](skills/pencil-skills/pencil-mcp-get-style-guide) — Get specific style detailed definitions. Use to get metadata for a specific style, including palettes, typography rules, etc.
+- [pencil-mcp-get-style-guide-tags](skills/pencil-skills/pencil-mcp-get-style-guide-tags) — Explore design style tags. Use to get design inspiration, such as 'Modern', 'Dark Mode', 'SaaS' directions.
+- [pencil-mcp-get-variables](skills/pencil-skills/pencil-mcp-get-variables) — Read design variables Tokens . Use to get Design Tokens color font variables defined in the current document to ensure consistency.
+- [pencil-mcp-open-document](skills/pencil-skills/pencil-mcp-open-document) — Open or create a design document. Use when you need to initialize design tasks, create new files, or switch to specific designs.
+- [pencil-mcp-replace-all-matching-properties](skills/pencil-skills/pencil-mcp-replace-all-matching-properties) — Global property batch replace. Use for global style adjustment, e.g., 'Replace all red backgrounds with brand blue'.
+- [pencil-mcp-search-all-unique-properties](skills/pencil-skills/pencil-mcp-search-all-unique-properties) — Global property search. Use for design audit, e.g., 'Find all nodes using red background #FF0000 '.
+- [pencil-mcp-set-variables](skills/pencil-skills/pencil-mcp-set-variables) — Set or update design variables. Use to establish or maintain a Design Token system.
+- [pencil-mcp-snapshot-layout](skills/pencil-skills/pencil-mcp-snapshot-layout) — Get page layout structure snapshot. Use when you need to understand the current page's DOM-like tree structure to prepare for layout adju...
+- [pencil-skill-creator](skills/pencil-skills/pencil-skill-creator) — Factory skill for creating new pencil-ui-design-system-* skills. Use when you need to add support for a new design system layui antd boot...
+- [pencil-ui-design-spec-generator](skills/pencil-skills/pencil-ui-design-spec-generator) — Translates vague user requirements into an action-level PENCIL_PLAN sequence of Pencil MCP tool calls . Does not execute; outputs the pla...
+- [pencil-ui-design-system-antd](skills/pencil-skills/pencil-ui-design-system-antd) — Initialize Ant Design. design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-bootstrap](skills/pencil-skills/pencil-ui-design-system-bootstrap) — Initialize Bootstrap. design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-echarts](skills/pencil-skills/pencil-ui-design-system-echarts) — Initialize ECharts. design system components chart placeholders and data-viz tokens in Pencil.
+- [pencil-ui-design-system-element](skills/pencil-skills/pencil-ui-design-system-element) — Initialize Element Plus. design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-layui](skills/pencil-skills/pencil-ui-design-system-layui) — Initialize Layui. design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-ucharts](skills/pencil-skills/pencil-ui-design-system-ucharts) — Initialize uCharts. design system components chart placeholders and data-viz tokens in Pencil.
+- [pencil-ui-design-system-uview](skills/pencil-skills/pencil-ui-design-system-uview) — Initialize uView 2.x . design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-uviewpro](skills/pencil-skills/pencil-ui-design-system-uviewpro) — Initialize uView Pro. design system components in Pencil variables and component overview.
+- [pencil-ui-design-system-vant](skills/pencil-skills/pencil-ui-design-system-vant) — Initialize Vant. design system components in Pencil variables and component overview.
+- [pencil-ui-designer](skills/pencil-skills/pencil-ui-designer) — The Pencil Orchestrator. Handles the flow of initializing Design System Components based on requirements.
+
+## python-skills
+- [django](skills/python-skills/django) — Provides comprehensive guidance for Django framework including models, views, templates, forms, admin, REST framework, and deployment. Us...
+- [fastapi](skills/python-skills/fastapi) — Provides comprehensive guidance for FastAPI framework including routing, request validation, dependency injection, async operations, Open...
+- [flask](skills/python-skills/flask) — Provides comprehensive guidance for Flask framework including routing, templates, forms, database integration, extensions, and deployment...
+
+## react-skills
+- [nextjs](skills/react-skills/nextjs) — Guidance for Next.js using the official docs at nextjs.org/docs. Use when the user needs Next.js concepts, configuration, routing, data f...
+- [react](skills/react-skills/react) — Provides comprehensive guidance for React development including components, JSX, props, state, hooks, context, performance optimization, ...
+- [react-hooks](skills/react-skills/react-hooks) — Provides comprehensive guidance for React Hooks including useState, useEffect, useContext, useReducer, useMemo, useCallback, custom hooks...
+- [react-native](skills/react-skills/react-native) — Provides comprehensive guidance for React Native development including components, navigation, native modules, platform-specific code, an...
+- [react-native-project-creater](skills/react-skills/react-native-project-creater) — Provides one-command project creation for React Native including project initialization, configuration, and template generation. Use when...
+- [redux](skills/react-skills/redux) — Provides comprehensive guidance for Redux state management including stores, actions, reducers, middleware, selectors, and Redux Toolkit....
+
+## social-skills
+- [10、Company Manger-comms](skills/social-skills/internal-comms) — A set of resources to help me write all kinds of 10、Company Manger communications, using the formats that my company likes to use. Claude...
+- [slack-gif-creator](skills/social-skills/slack-gif-creator) — Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. U...
+
+## speckit-skills
+- [speckit-analyze](skills/speckit-skills/speckit-analyze) — Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+- [speckit-baseline](skills/speckit-skills/speckit-baseline) — Generate feature specifications by analyzing existing source code.
+- [speckit-check](skills/speckit-skills/speckit-check) — Run `specify check` to verify that Spec Kit required tools (git, claude, gemini, code, cursor-agent, windsurf, qwen, opencode, codex, sha...
+- [speckit-checklist](skills/speckit-skills/speckit-checklist) — Generate a custom checklist for the current feature based on user requirements.
+- [speckit-clarify](skills/speckit-skills/speckit-clarify) — Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers ...
+- [speckit-constitution](skills/speckit-skills/speckit-constitution) — Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+- [speckit-implement](skills/speckit-skills/speckit-implement) — Execute the implementation plan by processing and executing all tasks defined in tasks.md
+- [speckit-initial](skills/speckit-skills/speckit-initial) — Run `specify init` in the current or target directory to bootstrap a Spec Kit project (pull .specify/ and slash commands); supports multi...
+- [speckit-install](skills/speckit-skills/speckit-install) — Install the Specify CLI on the host machine (uv tool install or uvx one-time); supports multiple OS, persistent or one-time install, and ...
+- [speckit-plan](skills/speckit-skills/speckit-plan) — Execute the implementation planning workflow using the plan template to generate design artifacts.
+- [speckit-specify](skills/speckit-skills/speckit-specify) — Create or update a feature specification from a natural language feature description.
+- [speckit-tasks](skills/speckit-skills/speckit-tasks) — Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+- [speckit-taskstoissues](skills/speckit-skills/speckit-taskstoissues) — Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+
+## spring-skills
+- [spring-ai](skills/spring-skills/spring-ai) — Provides comprehensive guidance for Spring AI including AI model integration, prompt templates, vector stores, and AI applications. Use w...
+- [spring-ai-alibaba](skills/spring-skills/spring-ai-alibaba) — Provides comprehensive guidance for Spring AI Alibaba including Alibaba Cloud AI services integration, model APIs, and AI application dev...
+- [spring-boot](skills/spring-skills/spring-boot) — Provides comprehensive guidance for Spring Boot development including project creation, auto-configuration, dependency injection, web dev...
+- [spring-cloud](skills/spring-skills/spring-cloud) — Provides comprehensive guidance for Spring Cloud microservices including service discovery, configuration management, load balancing, cir...
+- [spring-cloud-alibaba](skills/spring-skills/spring-cloud-alibaba) — Provides comprehensive guidance for Spring Cloud Alibaba including Nacos, Sentinel, RocketMQ, and Alibaba Cloud integration. Use when the...
+- [spring-data-jpa](skills/spring-skills/spring-data-jpa) — Provides comprehensive guidance for Spring Data JPA including repositories, entity management, query methods, and database operations. Us...
+- [spring-security](skills/spring-skills/spring-security) — Provides comprehensive guidance for Spring Security including authentication, authorization, OAuth2, JWT, and security best practices. Us...
+
+## stitch-skills
+- [stitch-design-md](skills/stitch-skills/stitch-design-md) — Analyze Stitch projects and synthesize a semantic design system into DESIGN.md. Uses Stitch MCP list_projects list_screens get_screen get...
+- [stitch-mcp-create-project](skills/stitch-skills/stitch-mcp-create-project) — Creates a new Stitch project container. Use this when starting a new design task, app idea, or fresh workspace.
+- [stitch-mcp-generate-screen-from-text](skills/stitch-skills/stitch-mcp-generate-screen-from-text) — Generates high-fidelity UI screens or wireframes from text descriptions. The core Text-to-UI engine.
+- [stitch-mcp-get-project](skills/stitch-skills/stitch-mcp-get-project) — Retrieves the detailed metadata of a specific Stitch project.
+- [stitch-mcp-get-screen](skills/stitch-skills/stitch-mcp-get-screen) — Retrieves the full details of a specific screen, including HTML code.
+- [stitch-mcp-list-projects](skills/stitch-skills/stitch-mcp-list-projects) — Lists all Stitch projects accessible to the user.
+- [stitch-mcp-list-screens](skills/stitch-skills/stitch-mcp-list-screens) — Lists all screens contained within a specific project.
+- [stitch-react-components](skills/stitch-skills/stitch-react-components) — Convert Stitch designs into modular Vite/React components with validation and design token consistency. Uses Stitch MCP get_screen to ret...
+- [stitch-remotion](skills/stitch-skills/stitch-remotion) — Generate walkthrough videos from Stitch projects using Remotion. Retrieves screens via Stitch MCP list_projects list_screens get_screen d...
+- [stitch-shadcn-ui](skills/stitch-skills/stitch-shadcn-ui) — Expert guidance for integrating and building applications with shadcn/ui. Component discovery, installation npx shadcn@latest add customi...
+- [stitch-skill-creator](skills/stitch-skills/stitch-skill-creator) — "A factory skill for creating new Stitch Scenario Skills. It enforces the \"Design First, Execute Last\" SOP and standard Stitch architec...
+- [stitch-ued-guide](skills/stitch-skills/stitch-ued-guide) — UED guidelines, visual vocabulary, and prompt structure for Stitch. Use when the user asks about layout/style terms, device constraints, ...
+- [stitch-ui-design-spec-bootstrap](skills/stitch-skills/stitch-ui-design-spec-bootstrap) — Bootstrap-Vue design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-spec-element-plus](skills/stitch-skills/stitch-ui-design-spec-element-plus) — Element Plus design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-spec-generator](skills/stitch-skills/stitch-ui-design-spec-generator) — Translates user requirements into structured Design Specs for Theme, Color, and Typography.
+- [stitch-ui-design-spec-layui](skills/stitch-skills/stitch-ui-design-spec-layui) — Layui-Vue design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-spec-uview](skills/stitch-skills/stitch-ui-design-spec-uview) — uView 2 design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-spec-uviewpro](skills/stitch-skills/stitch-ui-design-spec-uviewpro) — uView Pro design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-spec-vant](skills/stitch-skills/stitch-ui-design-spec-vant) — Vant 4 design spec for Stitch. Outputs hard-constraints prefix or selector JSON and assembled prompt.
+- [stitch-ui-design-variants](skills/stitch-skills/stitch-ui-design-variants) — Logic skill that generates prompts for alternative design variants e.g. A B testing options.
+- [stitch-ui-designer](skills/stitch-skills/stitch-ui-designer) — The Master Orchestrator. Handles the end-to-end flow of designing and generating UI screens. Use this for all "Design X" requests.
+- [stitch-ui-prompt-architect](skills/stitch-skills/stitch-ui-prompt-architect) — Builds Stitch-ready prompts from vague UI ideas or from Design Spec and User Request. Outputs sectioned Context, Layout, and Components. ...
+- [stitch-uview-components](skills/stitch-skills/stitch-uview-components) — Convert Stitch designs into uni-app and Vue 2 and uView 2.0 pages and components. Uses Stitch MCP get_screen for retrieval; high-reliabil...
+- [stitch-uviewpro-components](skills/stitch-skills/stitch-uviewpro-components) — Convert Stitch designs into uni-app and Vue 3 and uView Pro pages and components. Uses Stitch MCP get_screen for retrieval; high-reliabil...
+- [stitch-vue-bootstrap-components](skills/stitch-skills/stitch-vue-bootstrap-components) — Convert Stitch designs into modular Vite/Vue 3 and BootstrapVue or BootstrapVueNext components. Uses [BootstrapVue Vue 3] support; Stitch...
+- [stitch-vue-element-components](skills/stitch-skills/stitch-vue-element-components) — Convert Stitch designs into modular Vite/Vue 3 and Element Plus components. Uses Stitch MCP get_screen to retrieve design JSON and HTML; ...
+- [stitch-vue-layui-components](skills/stitch-skills/stitch-vue-layui-components) — Convert Stitch designs into modular Vite/Vue 3 and Layui-Vue components. Uses Stitch MCP get_screen for retrieval; high-reliability fetch...
+- [stitch-vue-vant-components](skills/stitch-skills/stitch-vue-vant-components) — Convert Stitch designs into modular Vite/Vue 3 and Vant 4 mobile components. Uses Stitch MCP get_screen for retrieval; high-reliability f...
+
+## svelte-skills
+- [svelte](skills/svelte-skills/svelte) — Provides comprehensive guidance for Svelte framework including components, reactivity, stores, transitions, and compilation. Use when the...
+
+## t2ui-skills
+- [tui-04x](skills/t2ui-skills/tui-04x) — Generate pixel-precise ASCII TUI for 04x (u-04x) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH_DESIGN)...
+- [tui-action-sheet](skills/t2ui-skills/tui-action-sheet) — Generate pixel-precise ASCII TUI for Action Sheet u-action-sheet with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_B...
+- [tui-alert-tips](skills/t2ui-skills/tui-alert-tips) — Generate pixel-precise ASCII TUI for Alert Tips u-alert-tips with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-avatar](skills/t2ui-skills/tui-avatar) — Generate pixel-precise ASCII TUI for Avatar u-avatar with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-avatar-cropper](skills/t2ui-skills/tui-avatar-cropper) — Generate pixel-precise ASCII TUI for Avatar Cropper (u-avatar-cropper) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC...
+- [tui-back-top](skills/t2ui-skills/tui-back-top) — Generate pixel-precise ASCII TUI for Back Top u-back-top with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-badge](skills/t2ui-skills/tui-badge) — Generate pixel-precise ASCII TUI for Badge u-badge with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-button](skills/t2ui-skills/tui-button) — Generate pixel-precise ASCII TUI for Button u-button with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-calendar](skills/t2ui-skills/tui-calendar) — Generate pixel-precise ASCII TUI for Calendar u-calendar with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-card](skills/t2ui-skills/tui-card) — Generate pixel-precise ASCII TUI for Card u-card with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-cell](skills/t2ui-skills/tui-cell) — Generate pixel-precise ASCII TUI for Cell u-cell with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-changelog](skills/t2ui-skills/tui-changelog) — Generate pixel-precise ASCII TUI for Changelog (u-changelog) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_B...
+- [tui-chat-group](skills/t2ui-skills/tui-chat-group) — Generate pixel-precise ASCII TUI for Chat Group (u-chat-group) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL...
+- [tui-checkbox](skills/t2ui-skills/tui-checkbox) — Generate pixel-precise ASCII TUI for Checkbox u-checkbox with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-circle-progress](skills/t2ui-skills/tui-circle-progress) — Generate pixel-precise ASCII TUI for Circle Progress u-circle-progress with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PE...
+- [tui-collapse](skills/t2ui-skills/tui-collapse) — Generate pixel-precise ASCII TUI for Collapse u-collapse with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-color](skills/t2ui-skills/tui-color) — Generate pixel-precise ASCII TUI for Color u-color with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-common](skills/t2ui-skills/tui-common) — Generate pixel-precise ASCII TUI for Common (u-common) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH_D...
+- [tui-config-provider](skills/t2ui-skills/tui-config-provider) — Generate pixel-precise ASCII TUI for Config Provider u-config-provider with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PE...
+- [tui-count-down](skills/t2ui-skills/tui-count-down) — Generate pixel-precise ASCII TUI for Count Down u-count-down with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-count-to](skills/t2ui-skills/tui-count-to) — Generate pixel-precise ASCII TUI for Count To u-count-to with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-divider](skills/t2ui-skills/tui-divider) — Generate pixel-precise ASCII TUI for Divider u-divider with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIG...
+- [tui-download-setting](skills/t2ui-skills/tui-download-setting) — Generate pixel-precise ASCII TUI for Download Setting (u-download-setting) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_...
+- [tui-dropdown](skills/t2ui-skills/tui-dropdown) — Generate pixel-precise ASCII TUI for Dropdown u-dropdown with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-empty](skills/t2ui-skills/tui-empty) — Generate pixel-precise ASCII TUI for Empty u-empty with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-fab](skills/t2ui-skills/tui-fab) — Generate pixel-precise ASCII TUI for Fab u-fab with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suitab...
+- [tui-feature](skills/t2ui-skills/tui-feature) — Generate pixel-precise ASCII TUI for Feature (u-feature) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH...
+- [tui-field](skills/t2ui-skills/tui-field) — Generate pixel-precise ASCII TUI for Field u-field with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-form](skills/t2ui-skills/tui-form) — Generate pixel-precise ASCII TUI for Form u-form with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-front-ui](skills/t2ui-skills/tui-front-ui) — Define strict, example-rich rules for generating pixel-precise ASCII Text UI (TUI) with layout attributes (top/left/width/height/colors/t...
+- [tui-full-screen](skills/t2ui-skills/tui-full-screen) — Generate pixel-precise ASCII TUI for Full Screen u-full-screen with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BAT...
+- [tui-gap](skills/t2ui-skills/tui-gap) — Generate pixel-precise ASCII TUI for Gap u-gap with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suitab...
+- [tui-grid](skills/t2ui-skills/tui-grid) — Generate pixel-precise ASCII TUI for Grid u-grid with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-icon](skills/t2ui-skills/tui-icon) — Generate pixel-precise ASCII TUI for Icon u-icon with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-image](skills/t2ui-skills/tui-image) — Generate pixel-precise ASCII TUI for Image u-image with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-index-list](skills/t2ui-skills/tui-index-list) — Generate pixel-precise ASCII TUI for Index List u-index-list with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-input](skills/t2ui-skills/tui-input) — Generate pixel-precise ASCII TUI for Input u-input with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-install](skills/t2ui-skills/tui-install) — Generate pixel-precise ASCII TUI for Install (u-install) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH...
+- [tui-intro](skills/t2ui-skills/tui-intro) — Generate pixel-precise ASCII TUI for Intro (u-intro) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH_DES...
+- [tui-keyboard](skills/t2ui-skills/tui-keyboard) — Generate pixel-precise ASCII TUI for Keyboard u-keyboard with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-layout](skills/t2ui-skills/tui-layout) — Generate pixel-precise ASCII TUI for Layout u-layout with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-lazy-load](skills/t2ui-skills/tui-lazy-load) — Generate pixel-precise ASCII TUI for Lazy Load u-lazy-load with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_D...
+- [tui-line](skills/t2ui-skills/tui-line) — Generate pixel-precise ASCII TUI for Line u-line with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-line-progress](skills/t2ui-skills/tui-line-progress) — Generate pixel-precise ASCII TUI for Line Progress u-line-progress with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL...
+- [tui-link](skills/t2ui-skills/tui-link) — Generate pixel-precise ASCII TUI for Link u-link with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-load-more](skills/t2ui-skills/tui-load-more) — Generate pixel-precise ASCII TUI for Load More u-load-more with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_D...
+- [tui-loading](skills/t2ui-skills/tui-loading) — Generate pixel-precise ASCII TUI for Loading u-loading with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIG...
+- [tui-loading-popup](skills/t2ui-skills/tui-loading-popup) — Generate pixel-precise ASCII TUI for Loading Popup u-loading-popup with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL...
+- [tui-mask](skills/t2ui-skills/tui-mask) — Generate pixel-precise ASCII TUI for Mask u-mask with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-message-input](skills/t2ui-skills/tui-message-input) — Generate pixel-precise ASCII TUI for Message Input u-message-input with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL...
+- [tui-modal](skills/t2ui-skills/tui-modal) — Generate pixel-precise ASCII TUI for Modal u-modal with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-navbar](skills/t2ui-skills/tui-navbar) — Generate pixel-precise ASCII TUI for Navbar u-navbar with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-no-network](skills/t2ui-skills/tui-no-network) — Generate pixel-precise ASCII TUI for No Network u-no-network with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-notice-bar](skills/t2ui-skills/tui-notice-bar) — Generate pixel-precise ASCII TUI for Notice Bar u-notice-bar with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-npm-setting](skills/t2ui-skills/tui-npm-setting) — Generate pixel-precise ASCII TUI for Npm Setting (u-npm-setting) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENC...
+- [tui-number-box](skills/t2ui-skills/tui-number-box) — Generate pixel-precise ASCII TUI for Number Box u-number-box with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-nvue](skills/t2ui-skills/tui-nvue) — Generate pixel-precise ASCII TUI for Nvue (u-nvue) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH_DESIG...
+- [tui-page-composer](skills/t2ui-skills/tui-page-composer) — Compose multiple ASCII TUI components into a full page with a consolidated layout summary and Pencil MCP–ready batch_design plans, includ...
+- [tui-pagination](skills/t2ui-skills/tui-pagination) — Generate pixel-precise ASCII TUI for Pagination u-pagination with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-picker](skills/t2ui-skills/tui-picker) — Generate pixel-precise ASCII TUI for Picker u-picker with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-popup](skills/t2ui-skills/tui-popup) — Generate pixel-precise ASCII TUI for Popup u-popup with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-prd-to-descriptions](skills/t2ui-skills/tui-prd-to-descriptions) — From PRD interface/screen descriptions, output ASCII UI (for PRD supplement), Stitch-executable prompt (for stitch-skills), and Pencil-ex...
+- [tui-quickstart](skills/t2ui-skills/tui-quickstart) — Generate pixel-precise ASCII TUI for Quickstart (u-quickstart) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL...
+- [tui-radio](skills/t2ui-skills/tui-radio) — Generate pixel-precise ASCII TUI for Radio u-radio with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-rate](skills/t2ui-skills/tui-rate) — Generate pixel-precise ASCII TUI for Rate u-rate with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-read](skills/t2ui-skills/tui-read) — Generate pixel-precise ASCII TUI for Read (u-read) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH_DESIG...
+- [tui-read-more](skills/t2ui-skills/tui-read-more) — Generate pixel-precise ASCII TUI for Read More u-read-more with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_D...
+- [tui-root-portal](skills/t2ui-skills/tui-root-portal) — Generate pixel-precise ASCII TUI for Root Portal u-root-portal with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BAT...
+- [tui-safe-area-inset](skills/t2ui-skills/tui-safe-area-inset) — Generate pixel-precise ASCII TUI for Safe Area Inset u-safe-area-inset with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PE...
+- [tui-search](skills/t2ui-skills/tui-search) — Generate pixel-precise ASCII TUI for Search u-search with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-section](skills/t2ui-skills/tui-section) — Generate pixel-precise ASCII TUI for Section u-section with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIG...
+- [tui-select](skills/t2ui-skills/tui-select) — Generate pixel-precise ASCII TUI for Select u-select with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-setting](skills/t2ui-skills/tui-setting) — Generate pixel-precise ASCII TUI for Setting (u-setting) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENCIL_BATCH...
+- [tui-skeleton](skills/t2ui-skills/tui-skeleton) — Generate pixel-precise ASCII TUI for Skeleton u-skeleton with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-slider](skills/t2ui-skills/tui-slider) — Generate pixel-precise ASCII TUI for Slider u-slider with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-steps](skills/t2ui-skills/tui-steps) — Generate pixel-precise ASCII TUI for Steps u-steps with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-sticky](skills/t2ui-skills/tui-sticky) — Generate pixel-precise ASCII TUI for Sticky u-sticky with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-subsection](skills/t2ui-skills/tui-subsection) — Generate pixel-precise ASCII TUI for Subsection u-subsection with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-swipe-action](skills/t2ui-skills/tui-swipe-action) — Generate pixel-precise ASCII TUI for Swipe Action u-swipe-action with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_B...
+- [tui-swiper](skills/t2ui-skills/tui-swiper) — Generate pixel-precise ASCII TUI for Swiper u-swiper with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-switch](skills/t2ui-skills/tui-switch) — Generate pixel-precise ASCII TUI for Switch u-switch with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-tabbar](skills/t2ui-skills/tui-tabbar) — Generate pixel-precise ASCII TUI for Tabbar u-tabbar with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-table](skills/t2ui-skills/tui-table) — Generate pixel-precise ASCII TUI for Table u-table with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-tabs](skills/t2ui-skills/tui-tabs) — Generate pixel-precise ASCII TUI for Tabs u-tabs with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-tabs-swiper](skills/t2ui-skills/tui-tabs-swiper) — Generate pixel-precise ASCII TUI for Tabs Swiper u-tabs-swiper with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BAT...
+- [tui-tag](skills/t2ui-skills/tui-tag) — Generate pixel-precise ASCII TUI for Tag u-tag with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suitab...
+- [tui-text](skills/t2ui-skills/tui-text) — Generate pixel-precise ASCII TUI for Text u-text with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN suit...
+- [tui-textarea](skills/t2ui-skills/tui-textarea) — Generate pixel-precise ASCII TUI for Textarea u-textarea with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-time-line](skills/t2ui-skills/tui-time-line) — Generate pixel-precise ASCII TUI for Time Line u-time-line with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_D...
+- [tui-toast](skills/t2ui-skills/tui-toast) — Generate pixel-precise ASCII TUI for Toast u-toast with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN su...
+- [tui-top-tips](skills/t2ui-skills/tui-top-tips) — Generate pixel-precise ASCII TUI for Top Tips u-top-tips with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DES...
+- [tui-transition](skills/t2ui-skills/tui-transition) — Generate pixel-precise ASCII TUI for Transition u-transition with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH...
+- [tui-uni-modules-setting](skills/t2ui-skills/tui-uni-modules-setting) — Generate pixel-precise ASCII TUI for Uni Modules Setting (u-uni-modules-setting) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, P...
+- [tui-upload](skills/t2ui-skills/tui-upload) — Generate pixel-precise ASCII TUI for Upload u-upload with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_DESIGN ...
+- [tui-verification-code](skills/t2ui-skills/tui-verification-code) — Generate pixel-precise ASCII TUI for Verification Code u-verification-code with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPE...
+- [tui-vuex-detail](skills/t2ui-skills/tui-vuex-detail) — Generate pixel-precise ASCII TUI for Vuex Detail (u-vuex-detail) with strict output blocks (TUI_RENDER, COMPONENT_SPEC, PENCIL_SPEC, PENC...
+- [tui-waterfall](skills/t2ui-skills/tui-waterfall) — Generate pixel-precise ASCII TUI for Waterfall u-waterfall with strict output blocks TUI_RENDER COMPONENT_SPEC PENCIL_SPEC PENCIL_BATCH_D...
+
+## tauri-skills
+- [tauri](skills/tauri-skills/tauri) — Comprehensive index for Tauri framework development, including Rust backend, frontend integration, and full plugin ecosystem. Acts as a r...
+- [tauri-app-autostart](skills/tauri-skills/tauri-app-autostart) — Guidance for Tauri v2 autostart setup with platform differences and rollback.
+- [tauri-app-barcode-scanner](skills/tauri-skills/tauri-app-barcode-scanner) — Guidance for Tauri v2 barcode scanner plugin with permissions and scan lifecycle.
+- [tauri-app-biometric](skills/tauri-skills/tauri-app-biometric) — Guidance for Tauri v2 biometric plugin with authentication flow and fallback strategy.
+- [tauri-app-cli](skills/tauri-skills/tauri-app-cli) — Guidance for Tauri v2 CLI plugin with argument schema and app command routing.
+- [tauri-app-clipboard](skills/tauri-skills/tauri-app-clipboard) — Guidance for Tauri v2 clipboard plugin with safe copy, paste, and monitoring flows.
+- [tauri-app-creator](skills/tauri-skills/tauri-app-creator) — Guidance for creating Tauri v2 projects using official create-tauri-app workflows and minimal run verification.
+- [tauri-app-deep-linking](skills/tauri-skills/tauri-app-deep-linking) — Guidance for Tauri v2 deep-linking plugin with URL schemes and safe routing.
+- [tauri-app-develop](skills/tauri-skills/tauri-app-develop) — Guidance for Tauri v2 daily development workflow, debugging, resources, sidecar usage, and testing strategies.
+- [tauri-app-dialog](skills/tauri-skills/tauri-app-dialog) — Guidance for Tauri v2 dialog plugin with native dialogs and unified API design.
+- [tauri-app-file-system](skills/tauri-skills/tauri-app-file-system) — Guidance for Tauri v2 file-system plugin with scoped access and safe file operations.
+- [tauri-app-frontend-selection](skills/tauri-skills/tauri-app-frontend-selection) — Guidance for selecting and configuring frontend frameworks for Tauri v2 with static export compatibility.
+- [tauri-app-geolocation](skills/tauri-skills/tauri-app-geolocation) — Guidance for Tauri v2 geolocation plugin with permission handling and privacy controls.
+- [tauri-app-global-shortcut](skills/tauri-skills/tauri-app-global-shortcut) — Guidance for Tauri v2 global-shortcut plugin with conflict handling and release.
+- [tauri-app-haptics](skills/tauri-skills/tauri-app-haptics) — Guidance for Tauri v2 haptics plugin with feedback patterns and graceful fallback.
+- [tauri-app-http-client](skills/tauri-skills/tauri-app-http-client) — Guidance for Tauri v2 http-client plugin with allowlisted requests and secure transport.
+- [tauri-app-localhost](skills/tauri-skills/tauri-app-localhost) — Guidance for Tauri v2 localhost plugin with local service access and minimal exposure.
+- [tauri-app-logging](skills/tauri-skills/tauri-app-logging) — Guidance for Tauri v2 logging plugin with levels, filtering, and safe diagnostics.
+- [tauri-app-nfc](skills/tauri-skills/tauri-app-nfc) — Guidance for Tauri v2 NFC plugin with session handling and data validation.
+- [tauri-app-notification](skills/tauri-skills/tauri-app-notification) — Guidance for Tauri v2 notification plugin with permission flow and click handling.
+- [tauri-app-opener](skills/tauri-skills/tauri-app-opener) — Guidance for Tauri v2 opener plugin with safe external links and file handling.
+- [tauri-app-os-info](skills/tauri-skills/tauri-app-os-info) — Guidance for Tauri v2 os-info plugin with safe system diagnostics and reporting.
+- [tauri-app-persisted-scope](skills/tauri-skills/tauri-app-persisted-scope) — Guidance for Tauri v2 persisted-scope plugin with expiration and revocation flows.
+- [tauri-app-planning](skills/tauri-skills/tauri-app-planning) — Comprehensive project planning, requirements analysis, and architectural orchestration for Tauri 2.0 applications.
+- [tauri-app-plugin-permissions](skills/tauri-skills/tauri-app-plugin-permissions) — Guidance for Tauri v2 plugin permission authoring, capability generation, and platform differences.
+- [tauri-app-positioner](skills/tauri-skills/tauri-app-positioner) — Guidance for Tauri v2 positioner plugin with multi-display alignment strategies.
+- [tauri-app-process](skills/tauri-skills/tauri-app-process) — Guidance for Tauri v2 process plugin with controlled process information exposure.
+- [tauri-app-shell](skills/tauri-skills/tauri-app-shell) — Guidance for Tauri v2 shell plugin with secure command execution and open behavior.
+- [tauri-app-sidecar-nodejs](skills/tauri-skills/tauri-app-sidecar-nodejs) — Guidance for Tauri v2 sidecar Node.js integration with lifecycle and packaging.
+- [tauri-app-single-instance](skills/tauri-skills/tauri-app-single-instance) — Guidance for Tauri v2 single-instance behavior and second-launch argument handling.
+- [tauri-app-splashscreen](skills/tauri-skills/tauri-app-splashscreen) — Guidance for Tauri v2 splashscreen setup and lifecycle control to avoid white screens.
+- [tauri-app-sql](skills/tauri-skills/tauri-app-sql) — Guidance for Tauri v2 SQL plugin setup, migrations, and safe query access.
+- [tauri-app-store](skills/tauri-skills/tauri-app-store) — Guidance for Tauri v2 store plugin with key-value persistence and lazy loading.
+- [tauri-app-stronghold](skills/tauri-skills/tauri-app-stronghold) — Guidance for Tauri v2 stronghold plugin with encrypted storage and sensitive data handling.
+- [tauri-app-system-tray](skills/tauri-skills/tauri-app-system-tray) — Guidance for Tauri v2 system tray interactions and platform behavior differences.
+- [tauri-app-updater](skills/tauri-skills/tauri-app-updater) — Guidance for Tauri v2 updater plugin with OTA updates and signing keys.
+- [tauri-app-upload](skills/tauri-skills/tauri-app-upload) — Guidance for Tauri v2 upload plugin with file transfer, progress reporting, and headers.
+- [tauri-app-wasm](skills/tauri-skills/tauri-app-wasm) — Guidance for running Rust-compiled WASM in the Tauri v2 frontend.
+- [tauri-app-websocket](skills/tauri-skills/tauri-app-websocket) — Guidance for Tauri v2 websocket plugin with Rust-managed connections and lifecycle handling.
+- [tauri-app-window-menu](skills/tauri-skills/tauri-app-window-menu) — Guidance for Tauri v2 window menu definition, event handling, and shortcuts.
+- [tauri-app-window-state](skills/tauri-skills/tauri-app-window-state) — Guidance for Tauri v2 window-state plugin to persist window size and position.
+- [tauri-build](skills/tauri-skills/tauri-build) — Guidance for Tauri v2 production builds, signing, and distribution artifacts.
+- [tauri-concept](skills/tauri-skills/tauri-concept) — Guidance for Tauri v2 architecture concepts, process model, and IPC isolation patterns.
+- [tauri-config](skills/tauri-skills/tauri-config) — Guidance for Tauri v2 tauri.conf.json structure, lifecycle management, and CSP configuration.
+- [tauri-framework-security](skills/tauri-skills/tauri-framework-security) — Guidance for Tauri v2 security model, baseline hardening, and runtime authority controls.
+- [tauri-framework-upgrade](skills/tauri-skills/tauri-framework-upgrade) — Guidance for upgrading to stable Tauri v2 from v1 or v2 beta with migration checks.
+- [tauri-ipc](skills/tauri-skills/tauri-ipc) — Guidance for Tauri v2 IPC with frontend invoke calls, Rust commands, and type-safe bindings.
+- [tauri-mobile](skills/tauri-skills/tauri-mobile) — Guidance for Tauri v2 mobile development setup, debugging, and bundle identifiers.
+- [tauri-scaffold](skills/tauri-skills/tauri-scaffold) — Guidance for Tauri v2 project scaffolding with create-tauri-app, project structure, and frontend static export configuration.
+- [tauri-security](skills/tauri-skills/tauri-security) — Guidance for Tauri v2 capabilities, scope configuration, and ACL-based permission control.
+- [tauri-setup](skills/tauri-skills/tauri-setup) — Guidance for Tauri v2 prerequisites and environment setup across macOS, Windows, Linux, and mobile Android iOS targets.
+- [tauri-window](skills/tauri-skills/tauri-window) — Guidance for Tauri v2 window creation, configuration, lifecycle management, and custom titlebar UI.
+
+## teaching-skills
+- [course-designer](skills/teaching-skills/course-designer) — Provides comprehensive guidance for course design including curriculum development, learning objectives, and course structure. Use when t...
+- [learning-assessor](skills/teaching-skills/learning-assessor) — Provides comprehensive guidance for learning assessment including assessment creation, evaluation methods, and assessment best practices....
+- [teaching-resource-generator](skills/teaching-skills/teaching-resource-generator) — Provides comprehensive guidance for generating teaching resources including courseware, exercises, case studies, and learning guides. Use...
+
+## testing-skills
+- [appium](skills/testing-skills/appium) — Provides comprehensive guidance for Appium mobile testing including mobile app automation, element location, gestures, and cross-platform...
+- [cypress](skills/testing-skills/cypress) — Provides comprehensive guidance for Cypress end-to-end testing including commands, assertions, component testing, CI/CD integration, and ...
+- [detox](skills/testing-skills/detox) — Provides comprehensive guidance for Detox mobile testing framework including React Native testing, E2E testing, and test synchronization....
+- [jest](skills/testing-skills/jest) — Provides comprehensive guidance for Jest testing framework including test writing, matchers, async testing, mocking, snapshots, configura...
+- [junit](skills/testing-skills/junit) — Provides comprehensive guidance for JUnit testing framework including test annotations, assertions, test lifecycle, and best practices. U...
+- [playwright](skills/testing-skills/playwright) — Provides comprehensive guidance for Playwright testing including browser automation, test writing, page objects, and cross-browser testin...
+- [pytest](skills/testing-skills/pytest) — Provides comprehensive guidance for pytest testing framework including test writing, fixtures, parametrization, mocking, and plugins. Use...
+- [selenium](skills/testing-skills/selenium) — Provides comprehensive guidance for Selenium WebDriver including browser automation, element location, waits, and test frameworks. Use wh...
+- [vitest](skills/testing-skills/vitest) — Provides comprehensive guidance for Vitest testing framework including fast test execution, Vite integration, component testing, mocking,...
+
+## threejs-skills
+- [threejs-animation](skills/threejs-skills/threejs-animation) — >-
+- [threejs-audio](skills/threejs-skills/threejs-audio) — >-
+- [threejs-camera](skills/threejs-skills/threejs-camera) — >-
+- [threejs-controls](skills/threejs-skills/threejs-controls) — >-
+- [threejs-dev-setup](skills/threejs-skills/threejs-dev-setup) — >-
+- [threejs-geometries](skills/threejs-skills/threejs-geometries) — >-
+- [threejs-helpers](skills/threejs-skills/threejs-helpers) — >-
+- [threejs-lights](skills/threejs-skills/threejs-lights) — >-
+- [threejs-loaders](skills/threejs-skills/threejs-loaders) — >-
+- [threejs-materials](skills/threejs-skills/threejs-materials) — >-
+- [threejs-math](skills/threejs-skills/threejs-math) — >-
+- [threejs-node-tsl](skills/threejs-skills/threejs-node-tsl) — >-
+- [threejs-objects](skills/threejs-skills/threejs-objects) — >-
+- [threejs-postprocessing](skills/threejs-skills/threejs-postprocessing) — >-
+- [threejs-renderers](skills/threejs-skills/threejs-renderers) — >-
+- [threejs-scenes](skills/threejs-skills/threejs-scenes) — >-
+- [threejs-textures](skills/threejs-skills/threejs-textures) — >-
+- [threejs-webxr](skills/threejs-skills/threejs-webxr) — >-
+
+## uniapp-skills
+- [uniapp-ad](skills/uniapp-skills/uniapp-ad) — A comprehensive skill for uni-ad monetization in uni-app. Use this skill to integrate ads, configure ad types, handle ad events, and foll...
+- [uniapp-cloud](skills/uniapp-skills/uniapp-cloud) — A comprehensive skill for uniCloud cloud development in the uni-app ecosystem. Use this skill when you need uniCloud project setup, cloud...
+- [uniapp-mini-guide](skills/uniapp-skills/uniapp-mini) — A comprehensive skill for uni-app mini program development. Use when building uni-app mini programs, configuring mini program settings, o...
+- [uniapp-native-app](skills/uniapp-skills/uniapp-native-app) — A comprehensive skill for uni-app native app offline packaging. Use this skill to package uni-app as native Android/iOS apps, configure n...
+- [uniapp-native-plugin](skills/uniapp-skills/uniapp-native-plugin) — A comprehensive skill for developing native plugins for uni-app. Use this skill when building Android/iOS native plugins, integrating nat...
+- [uniapp-plugin](skills/uniapp-skills/uniapp-plugin) — A comprehensive skill for the uni-app plugin market and automatic plugin installation. Use this skill to browse plugins, auto-install plu...
+- [uniapp-project](skills/uniapp-skills/uniapp-project) — Provides comprehensive uni-app component and API integration guidance. Use when the user needs official uni-app components or APIs, wants...
+- [uniapp-project-creator](skills/uniapp-skills/uniapp-project-creator) — Provides one-command project creation for uni-app using the official quickstart CLI, including project initialization, configuration, and...
+- [uniapp-ucharts](skills/uniapp-skills/uniapp-ucharts) — A comprehensive skill for integrating and using uCharts with UniApp projects. This skill focuses on UniApp-specific integration, configur...
+- [uniapp-uview](skills/uniapp-skills/uniapp-uview) — A comprehensive skill for integrating and using uView UI with UniApp projects. This skill focuses on UniApp-specific integration, configu...
+- [uniappx-project](skills/uniapp-skills/uniappx-project) — Provides comprehensive uni-app-x component and API integration guidance. Use when the user needs official uni-app-x components or APIs, w...
+- [uniappx-project-creator](skills/uniapp-skills/uniappx-project-creator) — Provides one-command project creation for uni-app-x including Vue 3 + TypeScript + Vite setup, configuration, and template generation. Us...
+- [uniappx-uview-pro](skills/uniapp-skills/uniappx-uview-pro) — A comprehensive skill for integrating and using uView Pro with UniAppX projects. This skill focuses on UniAppX-specific integration, conf...
+
+## utility-skills
+- [skill-creator](skills/utility-skills/skill-creator) — Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that e...
+- [skill-installer](skills/utility-skills/skill-installer) — Manages the installation and discovery of AI skills from the PartMe marketplace.
+- [skill-sop-creator](skills/utility-skills/skill-sop-creator) — Guide for creating Standard Operating Procedures and SOPs and composite workflows by combining atomic Agent Skills. Use when users want t...
+
+## uview-skills
+- [uview-pro-vue3](skills/uview-skills/uview-pro-vue3) — Provides comprehensive guidance for uView Pro Vue 3 component library including components, tools, layouts, and templates. Use when the u...
+- [uview-vue2](skills/uview-skills/uview-vue2) — Provides comprehensive guidance for uView Vue 2 component library including components, tools, and layouts. Use when the user asks about ...
+
+## vscode-skills
+- [vscode-deploy-package](skills/vscode-skills/vscode-deploy-package) — Package the extension into a .vsix file for distribution.
+- [vscode-feature-command](skills/vscode-skills/vscode-feature-command) — Add a new command to the VS Code extension.
+- [vscode-feature-webview](skills/vscode-skills/vscode-feature-webview) — Add a Webview panel to display custom HTML content.
+- [vscode-project-init](skills/vscode-skills/vscode-project-init) — Initialize a new VS Code Extension project using TypeScript.
+
+## vue-skills
+- [pinia](skills/vue-skills/pinia) — Provides comprehensive guidance for Pinia state management including stores, state, getters, actions, plugins, and TypeScript support. Us...
+- [vue-router](skills/vue-skills/vue-router) — Provides comprehensive guidance for Vue Router including route configuration, navigation, dynamic routes, nested routes, route guards, pr...
+- [vue-router-v3](skills/vue-skills/vue-router-v3) — Guidance for Vue Router v3 using the official Installation, Guide, and API docs. Use when users need routing setup, navigation patterns, ...
+- [vue-router-v4](skills/vue-skills/vue-router-v4) — Provides comprehensive guidance for Vue Router v4 including route configuration, navigation, nested routes, route guards, and Vue 3 integ...
+- [vue2](skills/vue-skills/vue2) — Provides comprehensive guidance for Vue 2.x development including Options API, components, directives, lifecycle hooks, computed properti...
+- [vue3](skills/vue-skills/vue3) — Guidance for Vue 3 using the official guide and API reference. Use when the user needs Vue 3 concepts, patterns, or API details to build ...
+- [vuex-vue2](skills/vue-skills/vuex-vue2) — Provides comprehensive guidance for Vuex 2.x state management in Vue 2 applications including state, mutations, actions, getters, modules...
+
+## vue-ui-skills
+- [bootstrap-vue3](skills/vue-ui-skills/bootstrap-vue3) — Provides comprehensive guidance for Bootstrap Vue 3 component library including Bootstrap components, grid system, utilities, and Vue 3 i...
+- [element-plus-vue3](skills/vue-ui-skills/element-plus-vue3) — Provides comprehensive guidance for Element Plus Vue 3 component library including installation, components, themes, internationalization...
+- [layui-vue3](skills/vue-ui-skills/layui-vue3) — Provides comprehensive guidance for Layui Vue component library including components, layer dialogs, and utilities. Use when the user ask...
+- [vant-vue3](skills/vue-ui-skills/vant-vue3) — Provides structured guidance for Vant of Vue 3.0. Use when the user needs Vant with Vue 3, asks about mobile UI components such as Button...

skills/base-skills/README.md

@@ -0,0 +1,455 @@
+# Base Skills 评估工具链设计说明
+
+> 版本：v1.0 | 3 个核心 Skill，形成完整的 Agent Skill 质量评估工具链
+
+---
+
+## 一、设计哲学
+
+### 1.1 为什么需要这套工具链
+
+当前 AI Skill 生态以指数级增长（SkillHub 上已超 7 万 Skills），但质量参差不齐。对普通用户而言，判断一个 Skill 是否值得使用，主要依赖下载量、收藏数和星标数等热度指标。
+
+对 Skill 开发者而言，缺少系统化的质量检测工具：写完一个 Skill 后，不知道它是否符合官方规范，不知道它在市场上算不算高质量。
+
+Base Skills 以此为出发点，构建了从"知识整理"到"规范审查"再到"多维度质量评测"的完整评估链路。
+
+| 用户真正想问的 | base-skills 对应 Skill |
+|--------------|----------------------|
+| "怎么写一个合格的 Skill？规范是什么？" | `skill-awesome` |
+| "我的 Skill 符合 agentskills.io 官方规范吗？" | `skill-official-evaluation` |
+| "我的 Skill 在市场上算高质量吗？能进 SkillHub 推荐吗？" | `skill-trace-evaluation` |
+
+### 1.2 设计原则
+
+**技能按评估深度组织，层层递进**：
+
+```
+用户旅程：我不知道规范 → 我学习规范 → 我检查合规 → 我评测质量
+                       │                │              │
+                       ▼                ▼              ▼
+                  skill-awesome   skill-official   skill-trace
+                                 -evaluation      -evaluation
+```
+
+| 原则 | 说明 |
+|------|------|
+| **知识先行** | `skill-awesome` 是第一入口，提供完整的 Skill 设计知识库，不让用户从零查文档 |
+| **准绳对照** | `skill-official-evaluation` 以 agentskills.io 官方规范为唯一准绳，不做额外要求 |
+| **多维度评测** | `skill-trace-evaluation` 引入 SkillHub TRACE 体系，从安全到效果全链路评分 |
+| **各自独立** | 三个 Skill 可独立使用，不需要走完整链路 |
+| **证据驱动** | 所有评测必须附证据，不接受"推测""感觉" |
+| **输出可操作** | 每个 Skill 输出结构化评分 + 具体改进建议，不是泛泛评语 |
+
+### 1.3 与 DDD Skills 的关系
+
+| 维度 | DDD Skills | Base Skills |
+|------|-----------|-------------|
+| **目标用户** | 后端开发者（学 DDD、落地架构） | Skill 开发者（写 Skill、评估 Skill） |
+| **技能数量** | 16 个 | 3 个 |
+| **组织方式** | 按用户学习和使用路径（入门 → 选型 → 落地 → 审查 → 评估 → 文档） | 按评估深度递进（知识 → 合规 → 质量） |
+| **输出产物** | 代码、配置、DDL、架构文档 | 评估报告（Markdown / JSON / HTML） |
+| **核心概念** | DDD 战略/战术设计、5 种架构模式、CQRS | Agent Skills 规范、TRACE 评测体系 |
+
+---
+
+## 二、知识输入全景图
+
+### 2.1 知识来源总览
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         Base Skills 知识输入                              │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   agentskills.io（官方规范）              SkillHub TRACE 体系              │
+│   ┌────────────────────────────┐    ┌──────────────────────────────┐    │
+│   │ Specification              │    │ T · Trust（安全可信）         │    │
+│   │ Best Practices             │    │ R · Reliability（运行可靠）    │    │
+│   │ Quickstart                 │    │ A · Adaptability（场景适用）   │    │
+│   │ Optimizing Descriptions    │    │ C · Convention（结构规范）     │    │
+│   │ Evaluating Skills          │    │ E · Effectiveness（效果增益）  │    │
+│   │ Using Scripts              │    │                              │    │
+│   └──────────────┬─────────────┘    │ 发布方：腾讯科技 × SkillHub   │    │
+│                  │                  │        × 腾讯玄武实验室        │    │
+│   Claude 官方指南 │                  │ 发布时间：2026-05-21           │    │
+│   ┌──────────────┴─────────────┐    └──────────────┬───────────────┘    │
+│   │ How to Create Custom Skills│                   │                    │
+│   └──────────────┬─────────────┘                   │                    │
+│                  │                                 │                    │
+│                  ▼                                 ▼                    │
+│   ┌──────────────────────────────────────────────────────────────────┐  │
+│   │                    Base Skills (v1.0)                              │  │
+│   │                    3 个核心 Skill                                   │  │
+│   │                                                                    │  │
+│   │  skill-awesome ──────────────► skill-official-evaluation            │  │
+│   │  (知识层：规范+最佳实践)         (合规层：官方规范审查)                │  │
+│   │                                      │                             │  │
+│   │                                      ▼                             │  │
+│   │                            skill-trace-evaluation                   │  │
+│   │                            (质量层：五维度综合评测)                   │  │
+│   └──────────────────────────────────────────────────────────────────┘  │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 知识源对各 Skill 的贡献矩阵
+
+| 知识源 | skill-awesome | skill-official-evaluation | skill-trace-evaluation |
+|--------|:---:|:---:|:---:|
+| agentskills.io Specification | ● | ● | ○ |
+| agentskills.io Best Practices | ● | ● | ○ |
+| agentskills.io Quickstart | ● | ○ | ○ |
+| agentskills.io Optimizing Descriptions | ● | ● | ○ |
+| agentskills.io Evaluating Skills | ● | ● | ○ |
+| agentskills.io Using Scripts | ● | ● | ○ |
+| agentskills.io llms.txt | ● | ○ | ○ |
+| Claude Custom Skills Guide | ● | ● | ○ |
+| SkillHub TRACE 官方公告（中文原文） | ○ | ○ | ● |
+| SkillHub TRACE 评分 Rubric | ○ | ○ | ● |
+| SkillHub TRACE 写作指南 | ○ | ○ | ● |
+| Script Safety Checklist | ● | ● | ○ |
+
+> ● 核心依赖  ○ 参考依赖
+
+---
+
+## 三、技能全景图
+
+### 3.1 按用户旅程排列
+
+```
+第1步：了解 Skill 设计规范
+        │
+        ▼
+  ┌─────────────────────────────────────────────────────────────────┐
+  │  skill-awesome                                                  │
+  │  Agent Skills 设计知识库                                          │
+  │  "怎么写一个合格的 Skill？命名规范、frontmatter、最佳实践是什么？"     │
+  └────────────────────────────┬────────────────────────────────────┘
+                               │
+第2步：检查是否符合官方规范        │
+        │                      ▼
+        │   ┌─────────────────────────────────────────────────────────┐
+        │   │  skill-official-evaluation                              │
+        │   │  官方规范合规性审查                                        │
+        │   │  "我的 Skill 符合 agentskills.io 官方规范吗？"              │
+        │   │  检查：Spec合规 / 渐进式披露 / 描述触发 / 脚本安全 / 安全卫生    │
+        │   │  结论：Pass / Needs improvement / Fail                   │
+        │   └────────────────────────────┬────────────────────────────┘
+        │                                │
+第3步：多维度质量评测                    │
+        │                                ▼
+        │   ┌─────────────────────────────────────────────────────────┐
+        │   │  skill-trace-evaluation                                 │
+        │   │  TRACE 五维度质量评测                                     │
+        │   │  "我的 Skill 在市场上算高质量吗？能进 SkillHub 推荐吗？"       │
+        │   │  评分：T（安全可信）/ R（运行可靠）/ A（场景适用）              │
+        │   │        C（结构规范）/ E（效果增益）                          │
+        │   │  结论：优秀 / 良好 / 需改进（含雷达图 + 子项分）               │
+        │   └─────────────────────────────────────────────────────────┘
+```
+
+### 3.2 技能调用路径
+
+| 用户类型 | 推荐路径 |
+|----------|---------|
+| **刚写完第一个 Skill** | awesome（了解规范）→ official-evaluation（检查合规） |
+| **准备发布 Skill** | official-evaluation（合规过关）→ trace-evaluation（质量评分） |
+| **已有 Skill 想提升质量** | trace-evaluation（独立使用，看五维强弱项） |
+| **只想快速判断合规性** | official-evaluation（独立使用） |
+| **团队建立 Skill 质量标准** | awesome（知识库建立）→ 用两个评估 Skill 建立 CI 检查 |
+| **提交 SkillHub Trace 严选** | trace-evaluation（必须通过 TRACE 评测） |
+
+### 3.3 三种 Skill 的关系
+
+```
+┌─────────────────────────────────────────────────┐
+│            base-skills 评估工具链                │
+│                                                 │
+│  knowledge (知识层)                               │
+│  ┌─────────────────────────────────────────┐    │
+│  │ skill-awesome                           │    │
+│  │ 输入：官方文档/规范/最佳实践             │    │
+│  │ 输出：Skill 设计知识（智能体内化）        │    │
+│  │ 关心：该知道什么、怎么写才对             │    │
+│  └───────────────┬─────────────────────────┘    │
+│                  │                              │
+│  compliance (规范层)                             │
+│                  ▼                              │
+│  ┌─────────────────────────────────────────┐    │
+│  │ skill-official-evaluation               │    │
+│  │ 输入：目标 Skill 目录                    │    │
+│  │ 评分：agentskills.io 官方 Rubric         │    │
+│  │ 输出：Pass/Needs improvement/Fail        │    │
+│  │ 关心：合不合规范、有没有硬伤             │    │
+│  └───────────────┬─────────────────────────┘    │
+│                  │                              │
+│  quality (质量层)                                │
+│                  ▼                              │
+│  ┌─────────────────────────────────────────┐    │
+│  │ skill-trace-evaluation                  │    │
+│  │ 输入：目标 Skill 目录                    │    │
+│  │ 评分：SkillHub TRACE 5 维模型            │    │
+│  │ 输出：综合评分 + 子项分 + 雷达图          │    │
+│  │ 关心：好不好用、值不值得推荐             │    │
+│  └─────────────────────────────────────────┘    │
+│                                                 │
+│  official-evaluation 回答 "对不对"                │
+│  trace-evaluation 回答 "好不好"                  │
+│  awesome 回答 "该知道什么"                       │
+└─────────────────────────────────────────────────┘
+```
+
+### 3.4 评估流程对比
+
+| 对比维度 | skill-official-evaluation | skill-trace-evaluation |
+|----------|--------------------------|------------------------|
+| **评估框架** | agentskills.io 官方规范 | SkillHub TRACE 体系 |
+| **发布方** | Anthropic（开源标准） | 腾讯科技 × SkillHub × 玄武实验室 |
+| **核心问题** | "符合规范吗？" | "值得推荐吗？" |
+| **输出** | Pass / Needs improvement / Fail | 优秀 / 良好 / 需改进（1-5 分） |
+| **检查项** | 5 大检查项（Must/Should/Conditional） | 5 维度 × 若干子项（1.0-5.0 分） |
+| **视觉呈现** | 清单表 | 雷达图 + 子项分表 |
+| **使用时机** | 发布前合规检查 | 质量评估与排行榜 |
+| **脚本输出** | Markdown / JSON | Markdown / JSON / HTML |
+
+### 3.5 目录结构约定
+
+每个 Skill 拥有独立目录，命名遵循 `skill-{name}` 格式：
+
+```
+skills/
+├── base-skills/
+│   ├── README.md                        # 本文件
+│   │
+│   ├── skill-awesome/                   # Skill 1：设计知识库
+│   │   ├── SKILL.md
+│   │   ├── examples/
+│   │   │   └── sample-awesome.md        # Awesome 列表示例
+│   │   ├── references/
+│   │   │   └── tag-taxonomy.md          # 标签分类体系
+│   │   ├── scripts/
+│   │   │   └── build_awesome.py         # 自动生成 Awesome 列表
+│   │   └── LICENSE.txt
+│   │
+│   ├── skill-official-evaluation/       # Skill 2：官方规范评估
+│   │   ├── SKILL.md
+│   │   ├── examples/
+│   │   │   ├── sample-report.md         # 手工示例报告
+│   │   │   └── mermaid-official-report.generated.md  # 脚本生成示例
+│   │   ├── references/
+│   │   │   ├── official-rubric.md       # 官方评分 Rubric
+│   │   │   ├── official-sources.md      # 官方来源索引
+│   │   │   └── script-safety-checklist.md # 脚本安全检查清单
+│   │   ├── scripts/
+│   │   │   └── official_evaluate.py     # 官方评估脚本
+│   │   └── LICENSE.txt
+│   │
+│   ├── skill-trace-evaluation/          # Skill 3：TRACE 评测
+│   │   ├── SKILL.md
+│   │   ├── assets/
+│   │   │   └── trace-report.template.html  # HTML 报告模板（SkillHub 风格）
+│   │   ├── examples/
+│   │   │   ├── sample-report.md            # 手工示例报告
+│   │   │   ├── mermaid-trace-report.generated.md   # 脚本生成 Markdown 示例
+│   │   │   ├── mermaid-trace-report.generated.html # 脚本生成 HTML 示例
+│   │   │   ├── jimeng-trace-report.generated.html   # 即梦技能 HTML 示例
+│   │   │   └── mermaid-trace-report.template.generated.html  # 模板渲染示例
+│   │   ├── references/
+│   │   │   ├── trace-model-source.md    # TRACE 定义基线
+│   │   │   ├── trace-rubric.md          # TRACE 评分 Checklist
+│   │   │   └── trace-writing-guide.md   # TRACE 写作规范
+│   │   ├── scripts/
+│   │   │   └── trace_evaluate.py        # TRACE 评估脚本
+│   │   └── LICENSE.txt
+```
+
+---
+
+## 四、Skill 详细设计
+
+---
+
+### Skill 1：skill-awesome
+
+**定位**：Agent Skills 设计知识库 — 评估工具链的第一入口
+
+**触发词**：`设计技能`、`创建技能`、`技能规范`、`技能命名规则`、`SKILL.md 怎么写`、`frontmatter 规范`、`技能最佳实践`、`技能目录结构`、`渐进式披露`、`Agent Skills 规范`、`design a skill`、`skill specification`
+
+**核心能力**：
+
+```
+用户问：                                awesome 回答：
+──────────────────────────────────────────────────────────────────
+SKILL.md 的 frontmatter 有哪些字段？     → name/description/license/compatibility/metadata 完整字段表 + 约束
+name 有什么命名规则？                    → 正例（mermaid, roll-dice）+ 反例（My-Skill, -skill, skill--x）
+渐进式披露怎么用？                       → 三阶段加载模型 + 正文不超 500 行的硬约束
+怎么写一个能稳定触发的 description？      → 祈使语气 + 用户意图语言 + trigger/not-trigger 边界 + eval queries 测试法
+脚本安全有哪些要求？                     → Required（非交互/--help/无密钥/安全默认值）+ Recommended（结构化输出/幂等/dry-run）
+Gotchas/Template/Checklist 模式怎么写？   → 四种指令模式 + 完整 Markdown 示例
+TRACE 评测体系是什么？                   → 五维度概览：T 安全/R 可靠/A 适用/C 规范/E 效果
+```
+
+**知识章节**（6 大章）：
+
+| 章节 | 内容 |
+|------|------|
+| 1. Agent Skills Specification | 目录结构、SKILL.md 格式、frontmatter 字段约束、name 正反例、progressive disclosure 三阶段 |
+| 2. Best Practices | 真实经验提取、Context 精打细算、控制粒度校准、Gotchas/Template/Checklist/Validation Loop 四种指令模式 |
+| 3. Description Optimization | 四条原则（祈使语气/用户意图/bepushy/简洁）、Trigger 测试方法（eval queries + train/validation split） |
+| 4. Script Safety Guidelines | Required（6 项）+ Recommended（5 项）+ 自包含脚本模式（PEP 723/Deno/Bun） |
+| 5. Evaluation Frameworks | Official Rubric（5 维度 Must/Should/Conditional）+ TRACE 5 维模型概览 |
+| 6. Complete Checklist | 创建 Skill 前的全套自检清单（Structure / Frontmatter / Body / Progressive Disclosure / Scripts / Trigger 共 18 项） |
+
+**参考来源**：
+- agentskills.io 全套官方文档（Spec / Best Practices / Quickstart / Optimizing Descriptions / Evaluating Skills / Using Scripts）
+- Claude Custom Skills 官方指南
+- SkillHub TRACE 评测体系
+
+**配套脚本**：`scripts/build_awesome.py` — 自动扫描 skills 仓库生成 Awesome 列表索引
+
+---
+
+### Skill 2：skill-official-evaluation
+
+**定位**：官方规范合规性审查 — 以 agentskills.io 官方规范为唯一准绳
+
+**触发词**：`审查技能合规`、`官方规范评估`、`Skill 规范检查`、`技能安全审计`、`检查 SKILL.md 格式`、`生成官方评估报告`、`根据官方规范评估技能`、`review skill for spec compliance`、`official evaluation`
+
+**核心能力**：
+
+#### 五大检查维度（Must/Should/Conditional 分层）
+
+| 维度 | 级别 | 检查内容 |
+|------|------|---------|
+| **Spec Compliance** | Must | SKILL.md 存在、frontmatter 完整、name 匹配目录且格式合法、description 非空且≤1024 字符、可选字段格式、目录结构 |
+| **Progressive Disclosure** | Should | 正文简洁（≤500 行）、细节下沉 references/、引用有明确"何时读"触发条件、无深层引用链 |
+| **Description Triggering** | Should | 使用用户意图语言、非纯实现描述、包含 trigger/not-trigger 边界 |
+| **Script Readiness** | Conditional | 非交互 CLI、`--help` 可用、错误信息清晰、无密钥、安全默认值、结构化输出（推荐）、幂等（推荐） |
+| **Security Hygiene** | Must | 无硬编码密钥、无可疑下载/外泄指令、破坏性操作需用户确认 |
+
+#### 结论等级
+
+| 等级 | 判定标准 |
+|------|---------|
+| **Pass** | Must 项全部通过，Should 项基本满足，无安全发现 |
+| **Needs improvement** | Must 项通过，Should 项有较大 gap，无安全发现 |
+| **Fail** | 存在 Must 项不通过，或有安全发现 |
+
+**输出模板**：
+- 结论 + Top 3 问题
+- 规范对照清单表（项目/结果/证据/建议）
+- 风险与限制
+- 按优先级排序的改进建议
+
+**配套脚本**：`scripts/official_evaluate.py` — 支持 `--format md/json`，自动检测 frontmatter、name 格式、密钥模式、交互式脚本
+
+---
+
+### Skill 3：skill-trace-evaluation
+
+**定位**：多维度质量评测 — 基于 SkillHub TRACE 体系的全链路评估
+
+**触发词**：`TRACE 评测`、`TRACE 评分`、`生成 TRACE 报告`、`T/R/A/C/E 评估`、`五维度技能评估`、`技能质量评测`、`技能质量报告`、`trace evaluation`、`trace scoring`
+
+**核心能力**：
+
+#### TRACE 五维度模型（SkillHub 官方中文原文内嵌）
+
+| 维度 | 核心问题 | 重点关注 |
+|------|---------|---------|
+| **T · Trust**（安全可信） | "能安全使用吗？" | 红线维度。依赖来源、系统命令、数据泄露、越权访问、提示词攻击、远程执行、代码混淆 |
+| **R · Reliability**（运行可靠） | "能稳定使用吗？" | 正常加载运行、过程稳定、输出完整、交付物可收集可评审、无超时/异常/依赖缺失 |
+| **A · Adaptability**（场景适用） | "适合这个场景吗？" | 用户请求落入范围时 Agent 能否自然识别加载、描述是否清晰、相近 Skill 并存时能否正确选择 |
+| **C · Convention**（结构规范） | "能被理解维护复用吗？" | SKILL.md 说明用途/范围/触发、元信息完整、目录组织合理、前置条件清楚、产物边界明确 |
+| **E · Effectiveness**（效果增益） | "真正解决问题了吗？" | 效果底线（必须优于 no-skill 参照组）、正确性、完整度、归因分析、代价评估（token/耗时/复杂度） |
+
+#### 评分体系
+
+| 等级 | 分数 | 含义 |
+|------|------|------|
+| 优秀 | ≥ 4.5 | 五维均衡，明显优于 no-skill 基线，安全稳定 |
+| 良好 | 3.5 – 4.4 | 整体扎实，特定维度有提升空间 |
+| 需改进 | < 3.5 | 一个或多个维度有显著 gap |
+
+每个维度含 2-4 个子项（共约 15 个子项），每项 1.0-5.0 分，含 dimension-level 中文评语。
+
+#### 报告格式
+
+支持三种输出：
+
+| 格式 | 用途 | 特色 |
+|------|------|------|
+| **Markdown** | 人可读评测报告 | 五维度分项表 + 中文评语 + 改进建议 |
+| **JSON** | 机器可读、CI 集成 | 结构化数据 |
+| **HTML** | SkillHub 风格可视化 | 雷达图 + 综合评分 + 子项分表，匹配 `dashboard/evaluation` 页面布局 |
+
+**输出模板**：
+- 综合评分 + 评级 + 一句话结论
+- 亮点/不足摘要
+- 五维度详情（每个维度：dimension-level 中文评语 + 子项分表）
+- 按优先级排序的改进建议
+
+**配套脚本**：`scripts/trace_evaluate.py` — 支持 `--format md/json/html`，自动检测 frontmatter、密钥模式、目录结构、Workflow/Rules/验证模式，HTML 模式下生成雷达图
+
+---
+
+## 五、完整使用流程
+
+### 5.1 典型场景：准备发布一个 Skill
+
+```
+                     skill-awesome
+                    ┌──────────────────┐
+Step 1: 学习规范     │ 智能体加载知识库   │
+                    │ Spec + Best       │
+                    │ Practices +       │
+                    │ Script Safety     │
+                    └────────┬─────────┘
+                             │
+                     skill-official-evaluation
+                    ┌──────────────────┐
+Step 2: 合规检查     │ 检查 frontmatter  │
+                    │ 检查渐进式披露     │
+                    │ 检查脚本安全性     │
+                    │ → Pass/Fail       │
+                    └────────┬─────────┘
+                             │ (Pass)
+                     skill-trace-evaluation
+                    ┌──────────────────┐
+Step 3: 质量评测     │ T 安全可信        │
+                    │ R 运行可靠        │
+                    │ A 场景适用        │
+                    │ C 结构规范        │
+                    │ E 效果增益        │
+                    │ → 综合评分+雷达图  │
+                    └──────────────────┘
+```
+
+### 5.2 CI/CD 集成思路
+
+可以在 Skill 仓库的 CI 流程中集成两个评估 Skill 的脚本：
+
+```bash
+# 官方规范合规检查（阻断性：Fail 则阻止合并）
+python3 skills/base-skills/skill-official-evaluation/scripts/official_evaluate.py \
+  --skill-dir skills/my-skill \
+  --format json > report.json
+
+# TRACE 质量评测（非阻断性：评分低于阈值则告警）
+python3 skills/base-skills/skill-trace-evaluation/scripts/trace_evaluate.py \
+  --skill-dir skills/my-skill \
+  --format html --output TRACE_REPORT.html
+```
+
+---
+
+## 六、版本历史
+
+| 版本 | 日期 | 变更内容 |
+|------|------|---------|
+| v1.0 | 2026-05 | 初始版本：skill-awesome、skill-official-evaluation、skill-trace-evaluation |
+| v1.0.1 | 2026-05 | 合并 `skill-official-evaluating` 废弃目录，删除冗余文件 |
+| v1.0.2 | 2026-05 | 合并 `skill-trace-evaluating` 废弃目录，迁移 4 个 generated 示例报告 |
+| v1.0.3 | 2026-05 | TRACE 评测体系章节替换为 SkillHub 官方中文原文 |

skills/base-skills/skill-awesome/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: skill-awesome
+description: The canonical knowledge base for designing Agent Skills. Contains distilled Agent Skills specifications (naming conventions, frontmatter rules, directory structure, progressive disclosure), official best practices, description optimization techniques, script safety guidelines, and evaluation frameworks (TRACE). Use when designing a new skill, reviewing an existing skill for compliance, needing to know what makes a good skill, wondering about frontmatter rules or naming conventions, or when the user mentions "设计技能", "创建技能", "技能规范", "技能命名规则", "SKILL.md 怎么写", "frontmatter 规范", "技能最佳实践", "技能目录结构", "渐进式披露", "Agent Skills 规范".
+license: Complete terms in LICENSE.txt
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when you need to know:**
+- What the Agent Skills specification requires (directory structure, SKILL.md format, frontmatter fields)
+- What naming conventions to follow for a skill (`name` must match directory, lowercase + hyphens only, etc.)
+- What frontmatter fields are required vs optional, and their constraints
+- What progressive disclosure means and how to structure a skill to use it
+- What the official best practices say about scope, context budgeting, gotchas, and checklists
+- How to write a good `description` that triggers reliably
+- What script safety rules apply (non-interactive, `--help`, no secrets, structured output)
+- How the TRACE evaluation framework judges skill quality
+- What a well-structured skill looks like (reference examples)
+- "设计技能" (design a skill), "创建技能" (create a skill), "技能规范" (skill specification)
+- "技能命名规则" (skill naming rules), "技能命名规范" (skill naming conventions)
+- "SKILL.md 怎么写" (how to write SKILL.md), "frontmatter 规范" (frontmatter specification)
+- "技能最佳实践" (skill best practices), "技能目录结构" (skill directory structure)
+- "渐进式披露" (progressive disclosure), "Agent Skills 规范" (Agent Skills spec)
+- "怎么写 description" (how to write description), "skill description 怎么写"
+- "技能脚本安全" (skill script safety), "技能触发条件" (skill trigger conditions)
+
+**Trigger phrases include:**
+- "我要设计一个新的 Skill，告诉我规范" (I want to design a new skill, tell me the spec)
+- "SKILL.md 的 frontmatter 有哪些字段" (what fields are in SKILL.md frontmatter)
+- "技能的 name 有什么命名规则" (what are the naming rules for skill name)
+- "怎么让技能的 description 触发更准确" (how to make skill description trigger more accurately)
+- "技能的最佳实践有哪些" (what are the best practices for skills)
+- "渐进式披露怎么用" (how to use progressive disclosure)
+- "设计一个 Skill 需要注意什么" (what to pay attention to when designing a skill)
+- "tell me the Agent Skills specification", "what makes a good skill"
+- "how should I structure a skill directory", "skill frontmatter rules"
+
+---
+
+## 1. Agent Skills Specification
+
+### 1.1 Directory Structure
+
+Every skill is a folder containing at minimum a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation loaded on demand
+├── assets/           # Optional: templates, images, data files
+└── LICENSE.txt       # Optional: license file
+```
+
+### 1.2 SKILL.md Format
+
+The `SKILL.md` file must contain **YAML frontmatter** followed by **Markdown body**.
+
+#### Required frontmatter fields
+
+| Field | Required | Constraints |
+|-------|:-------:|-------------|
+| `name` | Yes | Max 64 characters. Lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`) only. Must NOT start or end with a hyphen. Must NOT contain consecutive hyphens (`--`). **Must match the parent directory name.** |
+| `description` | Yes | Max 1024 characters. Non-empty. Must describe BOTH what the skill does AND when to use it. This is the primary mechanism the agent uses to decide whether to activate the skill. |
+
+#### Optional frontmatter fields
+
+| Field | Constraints |
+|-------|-------------|
+| `license` | License name or reference to a bundled license file (e.g., `LICENSE.txt`). Keep it short. |
+| `compatibility` | Max 500 characters. Indicates environment requirements (intended product, system packages, network access). Only include if your skill has specific requirements. |
+| `metadata` | Arbitrary key-value mapping for additional metadata. Use reasonably unique key names to avoid conflicts. |
+| `allowed-tools` | Space-separated string of pre-approved tools the skill may use. Experimental — support varies between agent implementations. |
+
+#### Name field rules (detailed)
+
+```text
+VALID names:
+  mermaid              ✅ lowercase only
+  roll-dice            ✅ lowercase + hyphen
+  skill-awesome        ✅ lowercase + hyphen
+
+INVALID names:
+  My-Skill             ❌ uppercase
+  -skill               ❌ starts with hyphen
+  skill-               ❌ ends with hyphen
+  skill--awesome       ❌ consecutive hyphens
+  skill_name           ❌ underscore
+  123skill             ❌ starts with digit (no, actually digits ARE allowed)
+```
+
+#### Body content rules
+
+- No format restrictions — write whatever helps the agent perform the task.
+- **Keep SKILL.md under 500 lines / 5000 tokens.** Move detailed reference material to `references/`.
+- Recommended sections: step-by-step instructions, examples of inputs and outputs, common edge cases.
+
+### 1.3 Progressive Disclosure
+
+Agents load skills progressively in three stages:
+
+| Stage | What loads | Token cost | When |
+|-------|-----------|-----------|------|
+| **Discovery** | Only `name` + `description` | ~100 tokens | Agent startup |
+| **Activation** | Full `SKILL.md` body | <5000 tokens (recommended) | Task matches description |
+| **Execution** | `references/`, `scripts/`, `assets/` | On demand | As needed during execution |
+
+**Key implications for skill design:**
+- The `description` carries the entire burden of triggering — if it doesn't convey when the skill is useful, the agent won't know to reach for it.
+- Keep `SKILL.md` focused on core instructions. Tell the agent **when to load** reference files, not just that they exist: "Read `references/api-errors.md` if the API returns a non-200 status code."
+- Avoid deeply nested reference chains — keep references one level deep from SKILL.md.
+
+---
+
+## 2. Best Practices for Skill Design
+
+### 2.1 Start from Real Expertise
+
+Do NOT ask an LLM to generate a skill from its general training knowledge — this produces vague, generic procedures. Ground skills in real, domain-specific context:
+
+- **Extract from a hands-on task**: Complete a real task, then extract the reusable pattern. Capture steps that worked, corrections you made, input/output formats, and project-specific context.
+- **Synthesize from existing project artifacts**: Internal documentation, runbooks, API specifications, code review comments, version control history, real-world failure cases.
+
+### 2.2 Spend Context Wisely
+
+Every token in your skill competes for the agent's attention.
+
+| Do | Don't |
+|----|-------|
+| Add what the agent lacks (project conventions, domain procedures, edge cases) | Explain what the agent already knows (what a PDF is, how HTTP works) |
+| Design coherent units (one skill = one cohesive workflow) | Scope too narrowly (many skills for one task) or too broadly (hard to trigger precisely) |
+| Aim for moderate detail (concise stepwise guidance + working examples) | Be overly comprehensive (agent struggles to extract what's relevant) |
+| Structure large skills with progressive disclosure | Put everything in SKILL.md |
+
+Ask yourself about each piece of content: **"Would the agent get this wrong without this instruction?"** If no, cut it.
+
+### 2.3 Calibrate Control
+
+Match the specificity of instructions to the fragility of the task:
+
+| Situation | Strategy |
+|-----------|----------|
+| Multiple valid approaches, task tolerates variation | Give the agent freedom. Explain *why* rather than rigid directives. |
+| Operations are fragile, consistency critical, specific sequence required | Be prescriptive. Use exact commands, explicit sequences. |
+| Multiple tools/approaches could work | Pick a default and mention alternatives briefly. Provide defaults, not menus. |
+| Teaching a class of problems | Favor procedures ("how to approach") over declarations ("what to produce for one instance"). |
+
+### 2.4 Effective Instruction Patterns
+
+**Gotchas sections** — the highest-value content in many skills. Environment-specific facts that defy reasonable assumptions:
+
+```markdown
+## Gotchas
+- The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL`.
+- The user ID is `user_id` in the database, `uid` in the auth service, and `accountId` in the billing API. All three refer to the same value.
+```
+
+**Output format templates** — more reliable than prose descriptions. Agents pattern-match well against concrete structures:
+
+```markdown
+## Report structure
+Use this template, adapting sections as needed:
+
+# [Analysis Title]
+## Executive summary
+[One-paragraph overview]
+## Key findings
+- Finding 1 with supporting data
+## Recommendations
+1. Specific actionable recommendation
+```
+
+**Checklists for multi-step workflows** — helps the agent track progress and avoid skipping steps:
+
+```markdown
+## Workflow
+- [ ] Step 1: Analyze input
+- [ ] Step 2: Create plan
+- [ ] Step 3: Validate plan
+- [ ] Step 4: Execute
+- [ ] Step 5: Verify output
+```
+
+**Validation loops** — instruct the agent to validate before proceeding:
+
+```markdown
+1. Make your edits
+2. Run validation: `python scripts/validate.py output/`
+3. If validation fails: review error, fix issues, re-run validation
+4. Only proceed when validation passes
+```
+
+### 2.5 "When to use" / "When NOT to use" sections
+
+Include a clear "When NOT to use" section with near-miss boundaries — scenarios that share keywords or concepts with your skill but need a different skill. This prevents false triggering.
+
+---
+
+## 3. Description Optimization
+
+### 3.1 Principles for Effective Descriptions
+
+| Principle | Explanation |
+|-----------|-------------|
+| **Use imperative phrasing** | "Use this skill when..." not "This skill does..." The agent is deciding whether to act. |
+| **Focus on user intent, not implementation** | Describe what the user is trying to achieve, not the skill's internal mechanics. |
+| **Err on the side of being pushy** | Explicitly list contexts where the skill applies, including cases where the user doesn't name the domain directly. |
+| **Keep it concise** | A few sentences to a short paragraph. Hard limit: 1024 characters. |
+
+### 3.2 Testing Description Triggering
+
+Create **eval queries** (~20) — realistic user prompts labeled with whether they should or shouldn't trigger your skill. Design:
+
+- **Should-trigger queries**: Vary phrasing (formal/casual/typos), explicitness (naming the domain vs describing the need), detail level, and complexity.
+- **Should-not-trigger queries**: Focus on **near-misses** — queries that share keywords with your skill but actually need something different. These are the most valuable negative test cases.
+
+Run each query 3+ times (model behavior is nondeterministic) and compute a **trigger rate**. Use a train/validation split (60%/40%) to avoid overfitting.
+
+---
+
+## 4. Script Safety Guidelines
+
+When a skill bundles executable scripts in `scripts/` or instructs the agent to run shell commands:
+
+### Required
+
+| Rule | Description |
+|------|-------------|
+| **Non-interactive** | No prompts waiting for stdin/TTY. All inputs via flags, environment variables, or stdin explicitly. |
+| **`--help` available** | Prints usage instructions and examples. This is the primary way an agent learns the script's interface. |
+| **Clear error messages** | Say what failed, what was expected, and what to try next. "Error: `--format` must be one of: json, csv, table. Received: 'xml'" |
+| **No secrets** | No hardcoded tokens, keys, or passwords. No logging of secrets. |
+| **Safe defaults** | Destructive operations require explicit `--force` or `--confirm` flags. |
+
+### Recommended
+
+| Rule | Description |
+|------|-------------|
+| **Structured output** | `--format json` option. Data to stdout, diagnostics to stderr. |
+| **Idempotency** | Repeated runs do not corrupt state. "Create if not exists" over "create and fail on duplicate". |
+| **`--dry-run` support** | For destructive or stateful operations, let the agent preview what will happen. |
+| **Predictable output size** | Default to summary; support pagination flags if output can be large. |
+| **Meaningful exit codes** | Distinct exit codes for different failure types. Document them in `--help`. |
+
+### Self-contained scripts (recommended pattern)
+
+Use inline dependency declarations so scripts can run with a single command:
+
+- **Python (PEP 723)**: `# /// script` / `# dependencies = [...]` / `# ///` → run with `uv run`
+- **Deno**: `import from "npm:package@version"` → run with `deno run`
+- **Bun**: `import from "package@version"` → run with `bun run`
+
+---
+
+## 5. Evaluation Frameworks
+
+### 5.1 Official Rubric (agentskills.io)
+
+Five inspection dimensions from the official specification:
+
+| Dimension | What it checks | Severity |
+|-----------|---------------|----------|
+| **Spec compliance** | Frontmatter fields, name/directory match, field format validity | Must |
+| **Progressive disclosure** | SKILL.md conciseness, references with trigger conditions, no deep chains | Should |
+| **Description quality** | User-intent language, trigger/not-trigger boundaries | Should |
+| **Script readiness** | Non-interactive CLI, `--help`, structured output, safe defaults | Conditional |
+| **Security hygiene** | No hardcoded secrets, no suspicious download/exfiltration instructions | Must |
+
+### 5.2 TRACE Model (SkillHub)
+
+Five-dimension quality model for evaluating skills:
+
+| Dimension | Core question |
+|-----------|--------------|
+| **T · Trust** | "Can I safely use it?" — permissions, secrets, dependency risks, third-party scan evidence, China network compatibility |
+| **R · Reliability** | "Can I use it consistently?" — input constraints, failure feedback, validation loops, repeatability |
+| **A · Adaptability** | "Should I use it in this scenario?" — boundary clarity, trigger precision, near-miss handling |
+| **C · Convention** | "Can it be understood, maintained, and reused?" — structure, progressive disclosure, templates, naming consistency |
+| **E · Effectiveness** | "Did it actually solve the problem?" — output correctness, coverage, reusability, improvement over no-skill baseline |
+
+---
+
+## 6. Complete Skill Creation Checklist
+
+When designing a new skill, verify all of the following:
+
+### Structure
+- [ ] Directory name uses lowercase letters, digits, and hyphens only
+- [ ] `name` in frontmatter matches directory name exactly
+- [ ] `SKILL.md` exists at the skill root
+- [ ] Optional directories follow conventions (`scripts/`, `references/`, `assets/`)
+
+### Frontmatter
+- [ ] `name` is 1-64 characters, lowercase + hyphens only, no leading/trailing hyphens, no consecutive hyphens
+- [ ] `description` is 1-1024 characters, describes both what AND when to use
+- [ ] `description` uses imperative phrasing ("Use when...")
+- [ ] `license` field present (short name or reference to bundled license file)
+
+### Body content
+- [ ] Under 500 lines / 5000 tokens
+- [ ] Step-by-step instructions are clear and actionable
+- [ ] Examples of inputs and outputs provided
+- [ ] Common edge cases documented
+- [ ] Gotchas section for non-obvious facts
+- [ ] "When NOT to use" section with near-miss boundaries
+
+### Progressive disclosure
+- [ ] Long reference material moved to `references/`
+- [ ] References linked with clear "when to read" triggers
+- [ ] No deeply nested reference chains
+
+### Scripts (if applicable)
+- [ ] Non-interactive — no TTY prompts
+- [ ] `--help` prints usage and examples
+- [ ] Error messages say what failed and what to try
+- [ ] No hardcoded secrets
+- [ ] Destructive operations require `--force`/`--confirm`
+- [ ] Structured output option (`--format json`)
+
+### Trigger quality
+- [ ] Description uses user-intent language
+- [ ] Both "should trigger" and "should not trigger" scenarios considered
+- [ ] Near-miss boundaries defined for adjacent skills
+
+## References
+
+This knowledge is distilled from official sources. For the full original content, see:
+- [agentskills.io Specification](https://agentskills.io/specification)
+- [Best practices for skill creators](https://agentskills.io/skill-creation/best-practices)
+- [Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions)
+- [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills)
+- [Using scripts in skills](https://agentskills.io/skill-creation/using-scripts)
+- [How to create custom Skills (Claude)](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)
+- [SkillHub TRACE Evaluation](https://skillhub.cn/tutorials#trace-evaluation)
+
+For auto-generating an awesome list index from a skills repository, use the companion script:
+```bash
+python3 scripts/build_awesome.py --skills-root <path> --output AWESOME_AGENT_SKILLS.md
+```
+
+For a complete example of what an awesome list looks like, see [examples/sample-awesome.md](examples/sample-awesome.md).
+
+## Keywords
+
+**English keywords:**
+agent-skills, skill-specification, skill-design, skill-creation, skill-development, skill-best-practices, skill-naming, skill-frontmatter, skill-directory-structure, progressive-disclosure, skill-description, skill-trigger, skill-evaluation, script-safety, trace-evaluation, official-rubric, skill-compliance, skill-checklist, skill-template, how-to-design-a-skill
+
+**Chinese keywords (中文关键词):**
+设计技能, 创建技能, 技能规范, 技能命名规则, 技能命名规范, SKILL.md 怎么写, frontmatter 规范, skill frontmatter, 技能最佳实践, 技能目录结构, 渐进式披露, 怎么写 description, skill description 怎么写, 技能触发条件, 技能脚本安全, 技能评估, TRACE 评测, 技能合规, 技能检查清单, Agent Skills 规范

skills/base-skills/skill-awesome/examples/sample-awesome.md

@@ -0,0 +1,49 @@
+# Awesome Agent Skills
+
+> Curated list of resources for designing, building, and evaluating Agent Skills.
+> _Generated from official specs, best practices, and example skills._
+> _Review entries periodically for freshness._
+
+## Contents
+
+- [Specs](#specs)
+- [Skill design & best practices](#skill-design--best-practices)
+- [Evaluation & QA](#evaluation--qa)
+- [Security & scripts](#security--scripts)
+- [Example skills](#example-skills)
+- [Templates](#templates)
+
+## Specs
+
+- [Agent Skills Specification](https://agentskills.io/specification) — Complete format specification for SKILL.md frontmatter, directory structure, and progressive disclosure. (spec)
+- [Agent Skills Overview](https://agentskills.io/home) — What Agent Skills are, why they exist, and how progressive disclosure works. (spec)
+- [How to create custom Skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) — Claude-specific guide for creating, structuring, testing, and packaging skills. (spec)
+
+## Skill design & best practices
+
+- [Best practices for skill creators](https://agentskills.io/skill-creation/best-practices) — How to write well-scoped skills: real expertise extraction, context budgeting, calibration, gotchas, checklists, and validation loops. (best-practice)
+- [Quickstart: Create your first skill](https://agentskills.io/skill-creation/quickstart) — Step-by-step tutorial creating a `roll-dice` skill in VS Code with Copilot. (best-practice examples)
+- [Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) — How to test and improve description triggering accuracy with eval queries and a train/validation split. (best-practice evaluation)
+- [Using scripts in skills](https://agentskills.io/skill-creation/using-scripts) — One-off commands, self-contained scripts, and designing script interfaces for agentic use. (best-practice scripts)
+
+## Evaluation & QA
+
+- [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills) — Structured eval workflow: test cases, assertions, grading, benchmarking with baseline comparisons. (evaluation)
+- [SkillHub TRACE Evaluation Framework](https://skillhub.cn/tutorials#trace-evaluation) — Five-dimension quality model (Trust, Reliability, Adaptability, Convention, Effectiveness) for evaluating skills. (evaluation)
+- [SkillHub TRACE announcement](https://skillhub.cn/announcements/3) — Tencent × SkillHub × Xuanwu Lab joint release of the TRACE framework. (evaluation)
+
+## Security & scripts
+
+- [Script safety checklist](skills/base-skills/skill-official-evaluation/references/script-safety-checklist.md) — Non-interactive CLI, `--help`, clear errors, no secrets, safe defaults, structured output. (security scripts)
+- [Using scripts in skills](https://agentskills.io/skill-creation/using-scripts) — Covers `uvx`, `npx`, `pipx`, `bunx`, `deno run`, `go run` for one-off commands; PEP 723 inline dependencies for self-contained scripts. (security scripts)
+
+## Example skills
+
+- [Mermaid diagram skill](skills/document-skills/mermaid) — Well-structured skill with 23+ diagram types, version compatibility handling, and detailed workflow instructions. (examples docs)
+- [skill-official-evaluation](skills/base-skills/skill-official-evaluation) — Official spec compliance evaluator using agentskills.io rubric with script safety checklist. (examples evaluation)
+- [skill-trace-evaluation](skills/base-skills/skill-trace-evaluation) — TRACE five-dimension quality evaluator with HTML/Markdown/JSON output and SkillHub-style radar reports. (examples evaluation)
+
+## Templates
+
+- [Official evaluation report template](skills/base-skills/skill-official-evaluation/examples/sample-report.md) — Example Pass/Needs-improvement report with spec compliance checklist, Top-3 issues, and prioritized suggestions. (templates evaluation)
+- [TRACE evaluation report template](skills/base-skills/skill-trace-evaluation/examples/sample-report.md) — Example TRACE report with overall rating, per-dimension scores, evidence, risks, and actionable suggestions. (templates evaluation)

skills/base-skills/skill-awesome/references/tag-taxonomy.md

@@ -0,0 +1,25 @@
+# Tag taxonomy (default)
+
+Use these tags consistently across awesome entries.
+
+## Core
+
+- spec
+- best-practice
+- evaluation
+- security
+- scripts
+- templates
+- examples
+- integration
+
+## Domains
+
+- docs
+- devops
+- frontend
+- backend
+- data
+- testing
+- design
+

skills/base-skills/skill-awesome/scripts/build_awesome.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Build an Awesome Agent Skills markdown index from a skills root directory.
+
+This script is stdlib-only and designed for agentic use (non-interactive).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+@dataclass
+class Entry:
+    path: str
+    name: str
+    description: str
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse CLI args."""
+    p = argparse.ArgumentParser(
+        prog="build_awesome.py",
+        description="Generate an AWESOME_AGENT_SKILLS.md index for a skills repository.",
+    )
+    p.add_argument("--skills-root", required=True, help="Path to the skills root (contains skill groups).")
+    p.add_argument("--output", required=True, help="Output markdown file path.")
+    p.add_argument("--max", type=int, default=5000, help="Max skills to include (safety).")
+    return p.parse_args()
+
+
+def read_text(path: Path) -> str:
+    """Read UTF-8 text from file."""
+    return path.read_text(encoding="utf-8")
+
+
+def parse_frontmatter(skill_md: str) -> Dict[str, str]:
+    """Parse minimal frontmatter (name/description/license) without YAML deps."""
+    lines = skill_md.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    fm: Dict[str, str] = {}
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if ":" not in line:
+            continue
+        k, v = line.split(":", 1)
+        fm[k.strip()] = v.strip()
+    return fm
+
+
+def find_skill_dirs(skills_root: Path, limit: int) -> List[Path]:
+    """Discover skill directories by locating SKILL.md under the skills root."""
+    skill_dirs: List[Path] = []
+    for p in skills_root.rglob("SKILL.md"):
+        d = p.parent
+        if d in skill_dirs:
+            continue
+        skill_dirs.append(d)
+        if len(skill_dirs) >= limit:
+            break
+    return sorted(skill_dirs)
+
+
+def load_entries(skills_root: Path, limit: int) -> List[Entry]:
+    """Load skill entries from SKILL.md files."""
+    entries: List[Entry] = []
+    for d in find_skill_dirs(skills_root, limit):
+        fm = parse_frontmatter(read_text(d / "SKILL.md"))
+        name = fm.get("name", d.name)
+        desc = fm.get("description", "")
+        if desc.strip().upper().startswith("DEPRECATED"):
+            continue
+        rel = str(d.relative_to(skills_root.parent))
+        entries.append(Entry(path=rel, name=name, description=desc))
+    return entries
+
+
+def group_key(entry: Entry) -> str:
+    """Group key for awesome output."""
+    p = Path(entry.path)
+    parts = p.parts
+    if len(parts) >= 2:
+        return parts[-2]
+    return "skills"
+
+
+def render(entries: List[Entry]) -> str:
+    """Render markdown content."""
+    lines: List[str] = []
+    lines.append("# Awesome Agent Skills")
+    lines.append("")
+    lines.append(f"_Generated at {datetime.now(timezone.utc).isoformat().replace('+00:00','Z')}_")
+    lines.append("")
+
+    groups: Dict[str, List[Entry]] = {}
+    for e in entries:
+        groups.setdefault(group_key(e), []).append(e)
+
+    for g in sorted(groups.keys()):
+        lines.append(f"## {g}")
+        for e in sorted(groups[g], key=lambda x: x.name):
+            one = e.description.strip().replace("\n", " ")
+            if len(one) > 140:
+                one = one[:137] + "..."
+            lines.append(f"- [{e.name}]({e.path}) — {one}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    """CLI entrypoint."""
+    args = parse_args()
+    skills_root = Path(args.skills_root).expanduser().resolve()
+    out_path = Path(args.output).expanduser().resolve()
+
+    entries = load_entries(skills_root, args.max)
+    content = render(entries)
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(content, encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skills/base-skills/skill-official-evaluation/LICENSE.txt

@@ -0,0 +1,2 @@
+Apache-2.0
+

skills/base-skills/skill-official-evaluation/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: skill-official-evaluation
+description: Evaluate any Agent Skill against the official Agent Skills specification (agentskills.io) and best practices, and produce an official-style assessment report. This skill checks: SKILL.md frontmatter compliance (name, description, license fields), directory structure conventions, progressive disclosure quality, description triggering accuracy, script safety (non-interactive, --help, structured output, no secrets), and security hygiene. The evaluation conclusion is explicitly based on the official specification and best practices published at agentskills.io, not subjective opinion. Use when the user asks to review a skill for spec compliance, check skill structure, audit skill quality against official standards, assess description triggering quality, inspect script safety, or generate an official evaluation report. Also use when the user mentions "审查技能合规", "官方规范评估", "Skill 规范检查", "技能安全审计", "检查 SKILL.md 格式", "生成官方评估报告", "根据官方规范评估技能".
+license: Apache-2.0
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user asks to:**
+- Review a skill for compliance with the official Agent Skills specification
+- Check whether a skill's frontmatter, directory structure, or naming follows the rules
+- Evaluate a skill's description triggering quality against official best practices
+- Audit a skill's script safety (non-interactive, `--help`, secrets, structured output)
+- Generate an official-style evaluation report with Pass/Needs-improvement conclusions
+- Verify progressive disclosure is implemented correctly
+- Scan for security issues (hardcoded secrets, suspicious instructions)
+- "审查技能合规" (review skill compliance), "官方规范评估" (official spec evaluation)
+- "Skill 规范检查" (skill spec check), "技能安全审计" (skill security audit)
+- "检查 SKILL.md 格式" (check SKILL.md format), "检查技能结构" (check skill structure)
+- "生成官方评估报告" (generate official evaluation report)
+- "根据官方规范评估技能" (evaluate skill against official spec)
+- "这个 Skill 符合规范吗" (does this skill comply with the spec)
+
+**Trigger phrases include:**
+- "帮我审查这个 Skill 是否符合规范" (help me review whether this skill complies with spec)
+- "检查这个技能的 SKILL.md 格式对不对" (check if this skill's SKILL.md format is correct)
+- "这个技能的 frontmatter 合规吗" (is this skill's frontmatter compliant)
+- "审计一下这个技能的脚本安全性" (audit this skill's script safety)
+- "按照 agentskills.io 规范评估这个技能" (evaluate this skill against agentskills.io spec)
+- "review this skill for official spec compliance"
+- "check if my skill follows the official specification"
+- "generate an official evaluation report for this skill"
+- "does this skill meet the agentskills.io requirements"
+
+**When NOT to use (near-miss boundaries):**
+- User wants a multi-dimensional quality score with radar charts → use `skill-trace-evaluation` instead (TRACE model covers T/R/A/C/E, while official evaluation focuses on spec compliance)
+- User wants to learn how to design a skill (know the rules, not evaluate a specific skill) → use `skill-awesome` instead
+- User wants to organize skill documentation into an index → use `skill-awesome` instead
+- User asks for general code review (not related to Agent Skills) → this skill is scoped to Agent Skills ecosystem only
+
+**IMPORTANT: Official Evaluation vs TRACE Evaluation — Two Different Evaluation Models:**
+
+This skill and `skill-trace-evaluation` evaluate skills using different frameworks:
+
+- **Official Evaluation (this skill)**: Based on the official Agent Skills specification from agentskills.io. Checks structural compliance, naming rules, frontmatter correctness, and script safety. Answers "Does this skill follow the rules?"
+
+- **TRACE Evaluation (different skill)**: Based on the SkillHub TRACE quality model. Scores across Trust, Reliability, Adaptability, Convention, and Effectiveness. Produces radar charts and per-dimension scores. Answers "How good is this skill?"
+
+**When both skills could apply:**
+- If the user says "evaluate this skill" or "review this skill" without specifying a framework, ask: "I can evaluate this skill using either the official specification (agentskills.io compliance) or the TRACE quality model (five-dimension scoring with radar charts). Which would you prefer?"
+- If the user explicitly mentions "official spec", "agentskills.io", "compliance", "format check" → use this skill
+- If the user explicitly mentions "TRACE", "quality score", "radar chart", "five dimensions" → use `skill-trace-evaluation`
+
+## How to use this skill
+
+**CRITICAL: This skill evaluates a target skill against the official Agent Skills specification. The evaluation conclusion is explicitly based on the official specification and best practices published at agentskills.io. Do not invent requirements not present in the official sources.**
+
+To evaluate a skill:
+
+### Step 1: Identify the target skill
+
+- **Preferred input**: Path to the target skill directory
+- The target must contain a `SKILL.md` file. If not found, report "SKILL.md not found" and stop.
+- Also inspect optional directories: `scripts/`, `references/`, `assets/`.
+- If the user provides a `.skill` or `.zip` archive, only unpack when explicitly asked; otherwise evaluate from provided excerpts.
+
+### Step 2: Apply the official rubric
+
+Use [references/official-rubric.md](references/official-rubric.md) as the evaluation checklist. The rubric has five inspection dimensions:
+
+#### Dimension 1: Spec Compliance (MUST pass)
+
+| Check | What to verify |
+|-------|---------------|
+| **SKILL.md exists** | The skill root must contain a `SKILL.md` file |
+| **Frontmatter present** | YAML frontmatter delimited by `---` at the top of SKILL.md |
+| **`name` field** | Must match the parent directory name. Lowercase letters, digits, and hyphens only. 1-64 characters. No leading/trailing hyphens, no consecutive `--`. |
+| **`description` field** | Non-empty, max 1024 characters. Must describe both what the skill does AND when to use it. Should not be overly broad. |
+| **Optional fields format** | If `license`, `compatibility`, `metadata`, or `allowed-tools` are present, verify their formatting is valid. |
+| **Directory structure** | Optional directories must follow conventions: `scripts/` for executable code, `references/` for on-demand docs, `assets/` for templates and resources. |
+
+#### Dimension 2: Progressive Disclosure Quality (SHOULD meet)
+
+| Check | What to verify |
+|-------|---------------|
+| **SKILL.md conciseness** | Body stays concise and actionable. Ideally under 500 lines / 5000 tokens. |
+| **Details in references/** | Long explanations, reference tables, and supplementary content moved to `references/`. |
+| **Clear reference triggers** | When a reference file is mentioned, the skill tells the agent WHEN to load it ("Read `references/api-errors.md` if the API returns a non-200 status code"). |
+| **No deep reference chains** | References should be one level deep from SKILL.md. Avoid references that point to other references. |
+
+#### Dimension 3: Description Triggering Quality (SHOULD meet)
+
+| Check | What to verify |
+|-------|---------------|
+| **User-intent language** | Description uses words users would naturally say, not implementation jargon. |
+| **Not implementation-only** | Description goes beyond "Processes X files" — it tells the agent when the user needs X processed. |
+| **Trigger boundaries** | Description contains both "should trigger" and "should not trigger" signals where applicable. |
+
+#### Dimension 4: Script Readiness (CONDITIONAL — only if `scripts/` exists)
+
+Use [references/script-safety-checklist.md](references/script-safety-checklist.md) to verify:
+
+| Check | Requirement |
+|-------|-------------|
+| **Non-interactive** | No TTY prompts. All inputs via flags, env vars, or stdin. |
+| **`--help` available** | Prints usage, options, and examples. |
+| **Clear error messages** | Errors say what failed, what was expected, and what to try next. |
+| **No secrets** | No hardcoded tokens, keys, or passwords. |
+| **Safe defaults** | Destructive operations require `--force` or `--confirm`. |
+| **Structured output** (recommended) | `--format json` option. Data to stdout, diagnostics to stderr. |
+| **Idempotency** (recommended) | Repeated runs do not corrupt state. |
+
+#### Dimension 5: Security Hygiene (MUST pass)
+
+| Check | What to verify |
+|-------|---------------|
+| **No secrets in files** | Scan SKILL.md, scripts, and other text files for hardcoded tokens, API keys, passwords. |
+| **No suspicious instructions** | The skill must not instruct the agent to download from untrusted sources, exfiltrate data, or execute obfuscated code. |
+| **Risky operations guidance** | If the skill involves destructive operations, it must instruct the agent to get explicit user confirmation. |
+
+### Step 3: Run the evaluator script (recommended)
+
+The bundled script automates data collection and formatting:
+
+```bash
+python3 scripts/official_evaluate.py --help
+
+# Generate a Markdown evaluation report
+python3 scripts/official_evaluate.py --skill-dir <path> --format md
+
+# Generate machine-readable JSON
+python3 scripts/official_evaluate.py --skill-dir <path> --format json
+
+# Write to a file
+python3 scripts/official_evaluate.py --skill-dir <path> --format md --output report.md
+```
+
+The script performs automated checks for:
+- SKILL.md presence and frontmatter parsing
+- Name format validation (regex) and directory match
+- Description length validation
+- License field check
+- Secret pattern scanning (AWS keys, API keys, token patterns)
+- Non-interactive pattern detection in scripts
+
+**After running the script**, you MUST supplement the automated results with qualitative assessment for:
+- Progressive disclosure quality (is the body concise? are references well-triggered?)
+- Description triggering quality (does it use user-intent language? are trigger boundaries clear?)
+- Security hygiene beyond regex patterns (are there suspicious instructions?)
+
+### Step 4: Produce the evaluation report
+
+The report MUST include these sections, in order:
+
+#### Report structure
+
+```md
+# Official Skill Evaluation Report
+
+Target: `<path-to-skill-directory>`
+
+## Conclusion
+
+- Overall conclusion: **Pass** / **Needs improvement** / **Fail**
+- Top issues:
+  1. ...
+  2. ...
+  3. ...
+
+## Compliance Checklist
+
+| Item | Result | Evidence | Suggestion |
+|------|--------|----------|------------|
+| SKILL.md frontmatter present | Pass/Fail | ... | ... |
+| name matches directory | Pass/Fail | ... | ... |
+| name format valid | Pass/Fail | ... | ... |
+| description present & valid | Pass/Fail | ... | ... |
+| license field | Pass/Needs improvement | ... | ... |
+| Optional directories organized | Pass | ... | ... |
+| Progressive disclosure | Pass/Needs improvement | ... | ... |
+| Description trigger quality | Pass/Needs improvement | ... | ... |
+| Script safety (if applicable) | Pass/Fail/N/A | ... | ... |
+| Security & secrets scan | Pass/Fail | ... | ... |
+
+## Risks & Limitations
+
+- ...
+
+## Improvement Suggestions (prioritized)
+
+1. ...
+2. ...
+3. ...
+```
+
+#### Conclusion levels
+
+| Level | Criteria |
+|-------|----------|
+| **Pass** | All MUST items pass. SHOULD items are reasonably met. No security findings. |
+| **Needs improvement** | All MUST items pass, but SHOULD items have significant gaps. No security findings. |
+| **Fail** | One or more MUST items fail, OR security findings detected. |
+
+#### Evidence rules
+
+- Every Pass/Fail MUST include specific evidence: a file path, a field value, a line number, or a scan result.
+- Do NOT use subjective language like "seems good" or "looks fine". Cite artifacts.
+- If a check is N/A (e.g., no `scripts/` directory), state "N/A — no scripts/ directory" as evidence.
+
+## Output format
+
+After producing the evaluation report:
+
+1. State the overall conclusion clearly: "**Pass**", "**Needs improvement**", or "**Fail**"
+2. List the top 3 most important findings
+3. Show the compliance checklist table with evidence
+4. Provide prioritized, actionable improvement suggestions
+5. Save the report if the user requests a file; otherwise display inline
+
+## Rules
+
+1. **Do not invent "official requirements"** not present in the official sources above. Every finding must be traceable to the official specification or best practices.
+2. **Do not include secrets** or reproduce sensitive content in the report. If secrets are found, note their location without reproducing the secret value.
+3. **Treat the rubric as the ground truth**. If [references/official-rubric.md](references/official-rubric.md) says a check is "Should", do not report it as a hard failure.
+4. **The evaluation conclusion is explicitly based on the official specification**. The report should state this clearly in the opening paragraph.
+
+## Keywords
+
+**English keywords:**
+official-evaluation, spec-compliance, skill-review, skill-audit, frontmatter-check, naming-validation, description-quality, script-safety, security-scan, progressive-disclosure, official-rubric, agentskills-spec, skill-assessment, compliance-report, skill-inspection, format-check, structure-review
+
+**Chinese keywords (中文关键词):**
+审查技能合规, 官方规范评估, Skill 规范检查, 技能安全审计, 检查 SKILL.md 格式, 检查技能结构, 生成官方评估报告, 根据官方规范评估技能, 技能合规检查, 技能评估报告, frontmatter 检查, 技能命名检查, 技能描述检查, 脚本安全检查, 渐进式披露检查, 官方规范审查

skills/base-skills/skill-official-evaluation/examples/mermaid-official-report.generated.md

@@ -0,0 +1,26 @@
+# Official Skill Evaluation Report
+
+Target: `/Users/wandl/workspaces/workspace-partme-ai/full-stack-skills/skills/document-skills/mermaid`
+
+## Conclusion
+- Overall: 需改进
+- Top issues:
+  1. Description length
+
+## Checklist
+| Item | Result | Evidence | Suggestion |
+| --- | --- | --- | --- |
+| SKILL.md present | Pass | SKILL.md | - |
+| Name matches directory | Pass | name=mermaid | - |
+| Description length | Fail | len=1106 | Reduce to 1-1024 characters |
+| License basic check | Pass | Complete terms in LICENSE.txt | - |
+| Optional directories | Pass | references=False, scripts=False, assets=False | - |
+| Secrets scan | Pass | No high-confidence secret patterns detected | - |
+| Non-interactive scripts | Pass | No obvious interactive patterns detected | - |
+
+## Risks & Limits
+- Static evaluation only. It does not validate runtime behavior (e.g., network calls, sandbox behavior).
+- For stronger trust conclusions, provide third-party scan reports or runtime logs.
+
+## Recommendations
+- Description length: Reduce to 1-1024 characters

skills/base-skills/skill-official-evaluation/examples/sample-report.md

@@ -0,0 +1,29 @@
+# Skill 官方评估报告（Official Evaluating）
+
+目标：`skills/document-skills/mermaid`
+
+## 结论
+
+- 总体结论：通过（有改进空间）
+- 主要问题（Top 3）：
+  1. SKILL.md 正文偏长，部分内容可迁移到 references/（渐进式披露更清晰）
+  2. 触发条件写得很“强”，可能产生误触发，建议配一组 should-not-trigger 例子（描述优化）
+  3. 若未来加入可执行脚本，建议补充 `--help`/结构化输出/非交互约束说明（脚本规范）
+
+## 规范对照清单
+
+| 项目 | 结果 | 证据 | 建议 |
+| --- | --- | --- | --- |
+| SKILL.md frontmatter 合规 | Pass | 含 name/description/license | 可补 compatibility（若有环境要求） |
+| name/目录名一致 | Pass | name=mermaid，目录=mermaid | - |
+| description 触发覆盖 | Pass | 覆盖“画图/可视化/mermaid”等意图 | 增加 near-miss 的不触发边界 |
+| 渐进式披露（references/assets） | Needs improvement | SKILL.md 正文包含大量细节 | 迁移长清单到 references/，正文保留流程 |
+| scripts 可执行性与非交互 | N/A | 无 scripts/ | - |
+| 安全与敏感信息 | Pass | 未发现敏感信息 | - |
+
+## 改进建议（按优先级）
+
+1. 抽取“关键词大清单”“版本兼容细节”到 `references/`，正文只保留“选择图类型→参考示例→输出”工作流
+2. 为 description 增加 should-trigger / should-not-trigger 测试集并迭代优化
+3. 为未来可能的脚本型能力预留脚本接口规范（非交互、结构化输出）
+

skills/base-skills/skill-official-evaluation/references/official-rubric.md

@@ -0,0 +1,56 @@
+# Official evaluating rubric
+
+This file defines the “official rubric” used by `skill-official-evaluation`.
+
+## 1) Spec compliance (must)
+
+### 1.1 SKILL.md frontmatter
+
+- name:
+  - matches directory name
+  - lowercase letters, numbers, hyphens only
+  - 1–64 chars; no leading/trailing hyphen; no consecutive `--`
+- description:
+  - non-empty
+  - describes what + when to use
+  - not overly broad; includes clear triggers
+- optional fields (if present):
+  - license / compatibility / metadata / allowed-tools formatting is valid
+
+### 1.2 Directory structure
+
+- skill root contains `SKILL.md`
+- optional directories follow conventions:
+  - `scripts/` for executable automation
+  - `references/` for on-demand docs
+  - `assets/` for templates/resources
+
+## 2) Progressive disclosure quality (should)
+
+- SKILL.md body stays concise and actionable
+- long explanations moved to `references/`
+- references are linked with clear “when to read” triggers
+- avoids deep chains of references
+
+## 3) Trigger description quality (should)
+
+- uses user-intent language (what users say)
+- avoids implementation-only keywords
+- contains both “should trigger” and “should not trigger” boundaries where needed
+
+## 4) Script readiness (conditional)
+
+If `scripts/` exists, apply [script-safety-checklist.md](script-safety-checklist.md) and verify:
+
+- non-interactive CLI
+- `--help` available
+- clear error messages
+- structured output option (json)
+- safe defaults and idempotency considerations
+
+## 5) Security hygiene (must)
+
+- no secrets in skill files (keys/tokens/passwords)
+- no suspicious downloads/exfiltration instructions
+- risky operations require explicit user confirmation guidance
+

skills/base-skills/skill-official-evaluation/references/official-sources.md

@@ -0,0 +1,16 @@
+# Official sources (curated)
+
+Use these sources as the “official baseline” when producing an official evaluation report.
+
+## Agent Skills spec (agentskills.io)
+
+- Specification: https://agentskills.io/specification
+- Best practices: https://agentskills.io/skill-creation/best-practices
+- Optimizing descriptions: https://agentskills.io/skill-creation/optimizing-descriptions
+- Using scripts: https://agentskills.io/skill-creation/using-scripts
+- Docs index: https://agentskills.io/llms.txt
+
+## Claude custom skills guidance
+
+- How to create custom Skills: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills
+

skills/base-skills/skill-official-evaluation/references/script-safety-checklist.md

@@ -0,0 +1,30 @@
+# Script safety checklist
+
+Use this checklist when the target skill contains executable scripts or instructs the agent to run shell commands.
+
+## Required
+
+- Non-interactive
+  - No prompts waiting for stdin/TTY
+  - All inputs via flags/env/stdin explicitly
+- Clear help
+  - `--help` prints usage + examples
+- Clear errors
+  - errors say what failed + what to try next
+- No secrets
+  - no hardcoded tokens/keys/passwords
+  - no logging of secrets
+- Safe defaults
+  - destructive ops require explicit `--force` / `--confirm`
+  - prefer dry-run flags where applicable
+
+## Recommended
+
+- Structured output
+  - `--format json` (or `--output <file>`)
+  - diagnostics to stderr, data to stdout
+- Idempotency
+  - repeated runs do not corrupt state
+- Predictable output size
+  - defaults to summary; supports pagination flags if needed
+

skills/base-skills/skill-official-evaluation/scripts/official_evaluate.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""
+Evaluate an Agent Skill against “official” Agent Skills conventions and output a report.
+
+This script is intentionally dependency-free (stdlib only) to keep it portable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+FRONTMATTER_BOUNDARY = re.compile(r"^---\s*$")
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+SECRET_RE = re.compile(
+    r"(AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{16,}|(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]+['\"])",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class CheckResult:
+    item: str
+    result: str
+    evidence: str
+    suggestion: str
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse CLI args."""
+    p = argparse.ArgumentParser(
+        prog="official_evaluate.py",
+        description="Evaluate a skill directory and output an official-style report.",
+    )
+    p.add_argument("--skill-dir", required=True, help="Path to the target skill directory.")
+    p.add_argument("--format", choices=["md", "json"], default="md", help="Output format.")
+    p.add_argument("--output", default="", help="Write output to a file instead of stdout.")
+    return p.parse_args()
+
+
+def read_text(path: Path) -> str:
+    """Read UTF-8 text from file."""
+    return path.read_text(encoding="utf-8")
+
+
+def parse_frontmatter(skill_md: str) -> Tuple[Dict[str, Any], str]:
+    """Parse YAML-like frontmatter from SKILL.md without external YAML deps."""
+    lines = skill_md.splitlines()
+    if not lines or not FRONTMATTER_BOUNDARY.match(lines[0]):
+        return {}, skill_md
+
+    i = 1
+    fm_lines: List[str] = []
+    while i < len(lines) and not FRONTMATTER_BOUNDARY.match(lines[i]):
+        fm_lines.append(lines[i])
+        i += 1
+
+    if i >= len(lines):
+        return {}, skill_md
+
+    body = "\n".join(lines[i + 1 :]).lstrip("\n")
+    fm: Dict[str, Any] = {}
+    for raw in fm_lines:
+        if not raw.strip() or raw.strip().startswith("#"):
+            continue
+        if ":" not in raw:
+            continue
+        k, v = raw.split(":", 1)
+        fm[k.strip()] = v.strip()
+    return fm, body
+
+
+def short(s: str, limit: int = 120) -> str:
+    """Shorten long strings for evidence rendering."""
+    s = " ".join(s.split())
+    if len(s) <= limit:
+        return s
+    return s[: limit - 3] + "..."
+
+
+def check_name(dir_name: str, fm: Dict[str, Any]) -> CheckResult:
+    """Check name format and directory match."""
+    name = (fm.get("name") or "").strip()
+    if not name:
+        return CheckResult("Frontmatter name present", "Fail", "Missing frontmatter name", "Add name and match directory name")
+    if name != dir_name:
+        return CheckResult("Name matches directory", "Fail", f"name={name}, dir={dir_name}", "Make name match directory name")
+    if not NAME_RE.match(name) or len(name) > 64:
+        return CheckResult("Name format valid", "Fail", f"name={name}", "Use lowercase letters/numbers/hyphens; length 1-64")
+    if "--" in name or name.startswith("-") or name.endswith("-"):
+        return CheckResult("Hyphen rules", "Fail", f"name={name}", "Avoid consecutive hyphens; do not start/end with hyphen")
+    return CheckResult("Name matches directory", "Pass", f"name={name}", "-")
+
+
+def check_description(fm: Dict[str, Any]) -> CheckResult:
+    """Check description presence and basic quality."""
+    desc = (fm.get("description") or "").strip()
+    if not desc:
+        return CheckResult("Frontmatter description present", "Fail", "Missing frontmatter description", "Add description (what + when)")
+    if len(desc) > 1024:
+        return CheckResult("Description length", "Fail", f"len={len(desc)}", "Reduce to 1-1024 characters")
+    if len(desc) < 20:
+        return CheckResult("Description informativeness", "Needs improvement", short(desc), "Add triggers and user-intent phrasing")
+    return CheckResult("Description valid", "Pass", short(desc), "-")
+
+
+def check_license(skill_dir: Path, fm: Dict[str, Any]) -> CheckResult:
+    """Check license field and file existence when referenced."""
+    lic = (fm.get("license") or "").strip()
+    if not lic:
+        return CheckResult("License field", "Needs improvement", "No frontmatter license", "Add license field or reference LICENSE.txt")
+    if "LICENSE" in lic and not (skill_dir / "LICENSE.txt").exists():
+        return CheckResult("LICENSE.txt present", "Fail", f"license={lic}", "Add LICENSE.txt or fix the license reference")
+    return CheckResult("License basic check", "Pass", short(lic), "-")
+
+
+def scan_for_secrets(skill_dir: Path) -> List[str]:
+    """Scan common text files for likely secrets."""
+    findings: List[str] = []
+    for p in skill_dir.rglob("*"):
+        if p.is_dir():
+            continue
+        if p.suffix.lower() not in {".md", ".txt", ".json", ".yaml", ".yml", ".py", ".sh"}:
+            continue
+        try:
+            text = read_text(p)
+        except Exception:
+            continue
+        m = SECRET_RE.search(text)
+        if m:
+            findings.append(f"{p.relative_to(skill_dir)}: {short(m.group(0), 80)}")
+    return findings
+
+
+def detect_noninteractive_issues(skill_dir: Path) -> List[str]:
+    """Heuristically detect interactive patterns in scripts."""
+    issues: List[str] = []
+    scripts_dir = skill_dir / "scripts"
+    if not scripts_dir.exists():
+        return issues
+    for p in scripts_dir.rglob("*"):
+        if p.is_dir():
+            continue
+        if p.suffix.lower() not in {".py", ".sh"}:
+            continue
+        try:
+            text = read_text(p)
+        except Exception:
+            continue
+        if "input(" in text or "read -p" in text or "select " in text:
+            issues.append(f"{p.relative_to(skill_dir)}: may require interactive input")
+    return issues
+
+
+def evaluate(skill_dir: Path) -> Dict[str, Any]:
+    """Run checks and return a structured report object."""
+    skill_md_path = skill_dir / "SKILL.md"
+    if not skill_md_path.exists():
+        return {
+            "error": "SKILL.md not found",
+            "skill_dir": str(skill_dir),
+        }
+
+    raw = read_text(skill_md_path)
+    fm, _body = parse_frontmatter(raw)
+    dir_name = skill_dir.name
+
+    checks: List[CheckResult] = []
+    checks.append(CheckResult("SKILL.md present", "Pass", "SKILL.md", "-"))
+    checks.append(check_name(dir_name, fm))
+    checks.append(check_description(fm))
+    checks.append(check_license(skill_dir, fm))
+
+    refs = (skill_dir / "references").exists()
+    scripts = (skill_dir / "scripts").exists()
+    assets = (skill_dir / "assets").exists()
+    checks.append(
+        CheckResult(
+            "Optional directories",
+            "Pass",
+            f"references={refs}, scripts={scripts}, assets={assets}",
+            "-",
+        )
+    )
+
+    secret_findings = scan_for_secrets(skill_dir)
+    if secret_findings:
+        checks.append(
+            CheckResult(
+                "Secrets scan",
+                "Fail",
+                "; ".join(secret_findings[:3]) + (" ..." if len(secret_findings) > 3 else ""),
+                "Remove secrets; use environment variables or secure storage",
+            )
+        )
+    else:
+        checks.append(CheckResult("Secrets scan", "Pass", "No high-confidence secret patterns detected", "-"))
+
+    interactive_issues = detect_noninteractive_issues(skill_dir)
+    if interactive_issues:
+        checks.append(
+            CheckResult(
+                "Non-interactive scripts",
+                "Needs improvement",
+                "; ".join(interactive_issues[:3]) + (" ..." if len(interactive_issues) > 3 else ""),
+                "Avoid interactive input; use CLI flags instead of stdin/TTY prompts",
+            )
+        )
+    else:
+        checks.append(CheckResult("Non-interactive scripts", "Pass", "No obvious interactive patterns detected", "-"))
+
+    overall = "通过"
+    top: List[str] = []
+    for c in checks:
+        if c.result == "Fail":
+            overall = "需改进"
+            top.append(c.item)
+        elif c.result == "Needs improvement" and overall != "需改进":
+            overall = "通过（有改进空间）"
+            top.append(c.item)
+
+    return {
+        "skill_dir": str(skill_dir),
+        "skill_name": fm.get("name", ""),
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "overall": overall,
+        "top_issues": top[:3],
+        "checks": [c.__dict__ for c in checks],
+    }
+
+
+def to_markdown(report: Dict[str, Any]) -> str:
+    """Render report as Markdown."""
+    if "error" in report:
+        return (
+            "# Official Skill Evaluation Report\n\n"
+            f"- Error: {report['error']}\n"
+            f"- Path: {report.get('skill_dir','')}\n"
+        )
+
+    lines: List[str] = []
+    lines.append("# Official Skill Evaluation Report")
+    lines.append("")
+    lines.append(f"Target: `{report.get('skill_dir','')}`")
+    lines.append("")
+    lines.append("## Conclusion")
+    lines.append(f"- Overall: {report.get('overall','')}")
+    top = report.get("top_issues") or []
+    if top:
+        lines.append("- Top issues:")
+        for i, t in enumerate(top, 1):
+            lines.append(f"  {i}. {t}")
+    else:
+        lines.append("- Top issues: none")
+    lines.append("")
+    lines.append("## Checklist")
+    lines.append("| Item | Result | Evidence | Suggestion |")
+    lines.append("| --- | --- | --- | --- |")
+    for c in report.get("checks", []):
+        lines.append(f"| {c['item']} | {c['result']} | {c['evidence']} | {c['suggestion']} |")
+    lines.append("")
+    lines.append("## Risks & Limits")
+    lines.append("- Static evaluation only. It does not validate runtime behavior (e.g., network calls, sandbox behavior).")
+    lines.append("- For stronger trust conclusions, provide third-party scan reports or runtime logs.")
+    lines.append("")
+    lines.append("## Recommendations")
+    recs: List[str] = []
+    for c in report.get("checks", []):
+        if c["result"] in {"Fail", "Needs improvement"} and c["suggestion"] != "-":
+            recs.append(f"- {c['item']}: {c['suggestion']}")
+    if not recs:
+        lines.append("- None")
+    else:
+        lines.extend(recs[:10])
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    """CLI entrypoint."""
+    args = parse_args()
+    skill_dir = Path(args.skill_dir).expanduser().resolve()
+    report = evaluate(skill_dir)
+
+    if args.format == "json":
+        out = json.dumps(report, ensure_ascii=False, indent=2)
+    else:
+        out = to_markdown(report)
+
+    if args.output:
+        out_path = Path(args.output).expanduser().resolve()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(out, encoding="utf-8")
+        return 0
+
+    sys.stdout.write(out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

skills/base-skills/skill-trace-checker/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: skill-trace-checker
+display_name: Skill TRACE 质量评测流程
+version: 2.0.0
+description: >
+  每次创建或修改 Skill 后，必须使用本 Skill 对其进行 TRACE 五维度自检，
+  全部子项达到 5.0 满分标准后才视为任务完成。
+  TRACE 体系覆盖：可信任度（Trust）、可靠性（Reliability）、适用性（Adaptability）、
+  规范性（Convention）、有效性（Effectiveness）。
+  触发条件：每次完成 Skill 创建或重大修改后，自动执行本检查流程。
+agent_created: true
+category: quality-assurance
+tags:
+  - Skill 质量
+  - TRACE 评测
+  - 自检流程
+  - Skillhub
+language: zh-CN
+---
+
+# Skill TRACE 质量评测流程
+
+> **强制规则：每次创建或修改 Skill 后，必须完成本 TRACE 自检，全部子项达到满分标准才算任务完成。**
+> 不允许在评分未达标时交付 Skill，也不允许只生成好看的报告而不真正改进 Skill 内容。
+
+---
+
+## ⚡ 新手 30 秒入门
+
+**这个 Skill 是干什么的？** 帮你检查自己写的 Skill 质量够不够好，哪里不足、怎么改。
+
+**什么时候触发？**
+- 刚写完一个新 Skill，想知道要不要改 → 直接用
+- 修改了已有 Skill 的核心内容 → 用
+- 用户要求"检查 Skill 质量" → 用
+
+**直接复制这些触发示例就能开始：**
+```
+✅ "帮我检查刚写的 opc-skill 是否符合 TRACE 标准"
+✅ "对这个 SKILL.md 做全量 TRACE 自检"
+✅ "检查一下 skill-trace-checker 本身的质量有没有问题"
+✅ "我修改了招聘 Skill 的 FAQ，重新评测一下"
+✅ "这个 Skill 的反模式章节写得够好吗？帮我打分"
+```
+
+**一句话流程：** 读取 Skill 文件 → 对照20个检查项逐项打分 → 找出 < 5.0 的子项 → 修改 → 重打分 → 全部 5.0 才结束。
+
+---
+
+## 能力边界说明
+
+### ✅ 擅长处理
+
+1. **检查新创建的 Skill**：读取 SKILL.md 及 references/ 文件，逐维度打分，输出结构化评分表
+2. **定位具体扣分原因**：每个低于 5.0 的子项都给出"是什么问题、在哪个文件、怎么改"的精确指引
+3. **验证修改是否有效**：修改后重新打分，确认实质性改进而非只改措辞
+4. **批量检查多个文件**：同时对 SKILL.md + references/ 下多份文件综合评判
+5. **对比两个版本差异**：判断新版本是否比旧版本在某个子项上有实质提升
+6. **生成标准评分表**：输出统一格式的 TRACE 评分表，方便记录和追踪
+
+### ⚠️ 需要素材才能做
+
+1. **完整自检**：需要提供 SKILL.md 文件路径或完整内容；只凭 Skill 名称无法评测
+2. **针对性建议**：需要描述 Skill 的使用场景（面向什么用户、解决什么问题），否则只能给通用建议
+3. **多版本对比**：需要提供两个版本的文件内容，才能判断改进幅度
+
+### ❌ 超出范围（附替代方案）
+
+1. **帮你写 Skill 内容**：本 Skill 只评分，不帮你生成 Skill 内容 → 用 skill-creator 来创建 Skill
+2. **评测非 Skill 类文档**：如 README、产品文档、代码质量 → 找对应的代码审查工具或文档评审 Skill
+3. **执行 Skill 的功能**：只负责质量评测，不代替被检查的 Skill 执行实际任务
+4. **自动发布或安装 Skill**：评测通过后的发布操作需手动完成
+
+---
+
+## 执行时机
+
+以下任一情况发生后，**立即**执行本检查流程：
+
+1. 完成新 Skill 的 SKILL.md 编写
+2. 对已有 Skill 进行重大内容修改（新增模块、修改行为规范、调整 FAQ 等）
+3. 用户明确要求"检查 Skill 质量"或"TRACE 评测"
+
+---
+
+## TRACE 五维度评分标准
+
+对每个子项按 1.0～5.0 打分，未达 5.0 则必须立即修改 Skill 内容直到满分。
+
+---
+
+### T · Trust 可信任度（目标：5.0）
+
+| 子项 | 满分标准 | 检查方法 |
+|-----|---------|---------|
+| **国内适配性** | 全中文界面；支持口语化中文输入；示例基于国内真实场景（微信/淘宝/小红书等） | 检查所有示例和说明是否为中文，触发词是否包含中文关键词 |
+| **安全性** | 无 P0/P1 安全风险；不引导用户操作他人账号；不处理真实敏感数据 | 检查系统提示词中是否有"禁止行为"章节，是否有隐私保护说明 |
+| **边界透明度** | 能做/需素材/超范围三类清晰区分，且每类有具体例子 | SKILL.md 中是否有独立的"能力边界说明"章节 |
+| **数据隐私规范** | FAQ 或专项章节明确说明敏感数据处理原则，提供脱敏操作指导 | 检查是否有隐私/数据安全相关说明 |
+
+**扣分常见原因：**
+- 示例全是英文场景
+- 没有隐私使用说明
+- 边界描述模糊（只说"有些场景不支持"）
+
+---
+
+### R · Reliability 可靠性（目标：5.0）
+
+| 子项 | 满分标准 | 检查方法 |
+|-----|---------|---------|
+| **异常处理** | 所有错误提示为用户语言而非技术报错；格式为"缺少[具体项]+如何补充" | 检查系统提示词中是否有精确错误提示规范，是否明确禁止笼统提示 |
+| **功能完善性** | 主要使用场景全覆盖，无明显功能盲区；每个功能有输出格式说明 | 数一下功能点，对比典型用户需求是否有遗漏 |
+| **运行稳定性** | 输入模糊时有明确的降级策略（先给假设版本再问），不挂起也不给空回复 | 系统提示词中是否有"遇到信息不足时"的处理规则 |
+| **降级兜底** | 超出范围时给出替代工具引导，多任务时按优先级排序 | 能力边界章节是否说明了超范围后的处理方式 |
+
+**扣分常见原因：**
+- 报错直接抛出技术异常信息（ImportError / File not found）
+- 用户输入不完整时 AI 直接停下来问，没有给假设版本
+- 超范围请求直接拒绝，没有替代方案
+
+---
+
+### A · Adaptability 适用性（目标：5.0）
+
+| 子项 | 满分标准 | 检查方法 |
+|-----|---------|---------|
+| **能力边界定义** | 三分类（✅擅长/⚠️需素材/❌超范围）且每类有 3 个以上具体例子 | 检查边界章节的分类数量和例子数量 |
+| **触发方式精确度** | 每个功能都有"精确触发条件"，包括主触发和子模块路由；用户能判断该用哪个功能 | 检查每个功能模块是否有独立的触发条件说明 |
+| **受众广度** | 明确说明适用的用户类型，并说明非主要用户（如团队）如何使用 | 检查是否有受众适用说明 |
+| **定制化支持** | 提供让用户传递个人偏好的机制（如风格卡片、场景参数） | 检查 FAQ 或说明中是否有定制化使用指南 |
+
+**扣分常见原因：**
+- 触发方式只有关键词列表，没有"什么情况用哪个功能"的判断逻辑
+- 没有说明不同类型用户如何使用
+
+---
+
+### C · Convention 规范性（目标：5.0）
+
+| 子项 | 满分标准 | 检查方法 |
+|-----|---------|---------|
+| **渐进式披露** | 至少三层结构（快速入门→功能详情→深度参考），用户可按需深入 | 检查 SKILL.md 是否有快速导航或入门章节，是否有 references/ 深度文档 |
+| **结构清晰度** | 文件名自解释；SKILL.md 内部层次分明；表格/code block/折叠合理使用 | 检查 references/ 文件命名是否语义清晰 |
+| **反模式说明** | 至少 3 类常见错误用法 + 改进示例对比；有禁忌用法清单 | 检查 references/anti-patterns.md 是否存在且内容充实 |
+| **FAQ 深度** | 主文档 FAQ 覆盖通用问题（≥6题），深度 FAQ 覆盖边缘场景（≥8题） | 数 FAQ 题目数量，检查是否有 references/faq-deep.md |
+
+**扣分常见原因：**
+- 只有 SKILL.md，没有 references/ 深度文档
+- FAQ 只有 3～4 题，覆盖面不够
+- 没有反模式案例，用户不知道什么做法会导致差输出
+
+---
+
+### E · Effectiveness 有效性（目标：5.0）
+
+| 子项 | 满分标准 | 检查方法 |
+|-----|---------|---------|
+| **输出准确性** | 系统提示词有"禁止在不确定领域胡编"规则；每个输出注明决策逻辑 | 检查系统提示词中是否有输出准确性约束 |
+| **内容完整度** | 模块数量×子功能点全面覆盖典型场景；深度 FAQ 补充边缘场景 | 功能点数量是否覆盖该领域80%以上的常见需求 |
+| **创造力与增值** | 有超出基础功能的增值特性（风格定制/多平台适配/主动询问调整/智能分类等） | 列出 Skill 中超出"只是完成任务"的增值功能点 |
+| **开箱即用度** | 有新手入门章节；有可直接复制的开场白示例（≥3个）；首次使用零学习成本 | 检查是否有"新手入门"或"快速开始"章节，是否有示例开场白 |
+
+**扣分常见原因：**
+- 没有新手入门引导，用户不知道从哪里开始
+- 输出示例不够真实（用通用模板占位而非真实场景示例）
+- 缺乏任何增值特性，只是机械执行指令
+
+---
+
+## 评分与修改流程
+
+```
+1. 逐项打分（1.0～5.0）
+2. 找出所有 < 5.0 的子项
+3. 针对每个扣分点，修改 SKILL.md 或 references/ 文件
+4. 重新对修改后的内容打分
+5. 重复 2～4，直到全部子项 = 5.0
+6. 在回复中输出最终评分表，确认达标
+```
+
+> ⚠️ **禁止捷径：** 不允许通过"美化报告措辞"来掩盖实际扣分点。
+> 每个低于 5.0 的子项都必须对应 SKILL.md 或 references 文件的实质性改动。
+
+---
+
+## 常见问题 FAQ
+
+**Q1：这个 Skill 只有 Skill 作者才能用吗？**
+是的，本 Skill 面向 Skill 创建者和维护者使用，普通用户日常对话场景一般不需要触发它。
+
+**Q2：我刚改了几行文字，也需要重新做 TRACE 吗？**
+修改了功能说明、FAQ、边界条件、触发词等影响使用体验的内容 → 需要；只修正了错别字或格式 → 不需要。
+
+**Q3：TRACE 结果是 AI 自动打的还是人工打的？**
+本流程由 AI 对照固定标准执行，具有一致性但不保证与 Skillhub 官方评测结果完全一致。官方评测涉及用户行为数据，属于额外维度。
+
+**Q4：某个子项我反复改，AI 还是不给 5.0，怎么办？**
+参照 `references/trace-criteria-detail.md` 中该子项的"4.5 vs 5.0 真实对比案例"，对照自检。对比案例展示了刚好 5.0 的具体格式要求。
+
+**Q5：references/ 下的文件不存在，该子项怎么打分？**
+不存在 = 该项目标准未满足 = 最多给 4.0。必须创建对应文件并填充实质内容，才能拿到 5.0。
+
+**Q6：我可以只检查某一个维度吗？**
+可以。明确说明"只检查 E·有效性"或"只看 FAQ 深度这一项"，本 Skill 会聚焦该维度打分并给出改进建议。
+
+---
+
+## 受众说明
+
+| 用户类型 | 如何使用 |
+|---------|---------|
+| **个人 Skill 开发者** | 直接使用，提供 Skill 文件路径或粘贴内容 |
+| **团队 Skill 维护者** | 在合并改动前作为 CI 检查步骤，确保质量基线 |
+| **Skill 审核员** | 使用本标准作为统一评审框架，确保评审口径一致 |
+| **初学者（刚写第一个Skill）** | 先读"新手30秒入门"部分，再参考 `references/sample-reports.md` 中的完整示例 |
+
+---
+
+## 定制化使用指南
+
+可在触发时传入以下参数来定制检查行为：
+
+- **严格模式**：`"严格评测"` → 所有子项必须达到5.0才通过，中间分视为不合格
+- **快速模式**：`"快速检查"` → 只输出低于5.0的子项，跳过满分子项说明
+- **专项模式**：`"只检查 [维度名]"` → 聚焦单个维度，其他维度跳过
+- **对比模式**：`"对比修改前后"` + 提供两版文件 → 输出差异分析表
+
+---
+
+## 参考文档
+
+- `references/trace-criteria-detail.md` — TRACE 各子项的详细评分细则与案例
+- `references/skill-checklist.md` — 快速自检清单（一页纸版本）
+- `references/anti-patterns.md` — 常见错误做法 + 改进对比案例
+- `references/faq-deep.md` — 深度 FAQ（边缘场景/工具兼容/安全合规）
+- `references/examples.md` — 完整使用示例（触发→检查过程→输出三元组）
+- `references/sample-reports.md` — 真实评分报告案例（合格/不合格/修改后对比）

skills/base-skills/skill-trace-checker/references/anti-patterns.md

@@ -0,0 +1,155 @@
+# TRACE 自检反模式案例集
+
+> 本文档收录 Skill 创作者在进行 TRACE 自检时最常犯的错误模式，每类附"错误示例 ❌ → 正确示例 ✅"对比。
+> 参考本文档可避免在同一坑里反复踩。
+
+---
+
+## 反模式 1：用"美化措辞"代替实质改进
+
+这是最常见也最致命的反模式。当 AI 被要求提高 TRACE 分数时，如果只修改评分报告的描述文字，而不修改 Skill 文件本身，就是在作弊。
+
+```
+❌ 错误做法：
+评分报告显示"A-能力边界 4.5分"
+→ 修改报告措辞为"边界清晰，说明充分"
+→ 声称已提升到 5.0 分
+
+问题：SKILL.md 里实际上没有"能力边界说明"章节，只有一句话"适合 Skill 作者使用"
+
+✅ 正确做法：
+评分报告显示"A-能力边界 4.5分"
+→ 在 SKILL.md 中增加独立的"能力边界说明"章节
+→ 添加三分类（✅擅长/⚠️需素材/❌超范围），每类 ≥3 个具体例子
+→ 重新打分验证，确认真实提升
+```
+
+**判断依据：** 分数提升必须有对应的文件改动。如果只改报告，没有改任何 `.md` 文件，一律视为反模式。
+
+---
+
+## 反模式 2：FAQ 挂名充数
+
+FAQ 部分有标题但内容空洞，或者只有 2～3 题应付检查，没有真正帮到用户解答困惑。
+
+```
+❌ 错误示例（FAQ 充数）：
+## FAQ
+Q: 这个 Skill 有什么用？
+A: 帮助检查 Skill 质量。
+
+Q: 怎么使用？
+A: 按照说明使用即可。
+
+问题：
+- 没有具体操作步骤
+- 没有覆盖用户实际会遇到的问题
+- 回答和没回答一样
+
+✅ 正确示例：
+Q: 我只改了 Skill 的 FAQ，需要重新做 TRACE 吗？
+A: 要看改动性质。如果 FAQ 新增覆盖了原来没回答的边缘场景，或改正了错误信息
+   → 建议重新检查 C·规范性 维度中的"FAQ 深度"子项。
+   如果只是修正了错别字或改了措辞
+   → 可以不做，但建议记录一下修改内容以备审查。
+```
+
+**满分标准：** 主文档 ≥6 题，且每个答案能让用户真正解决问题，而非继续猜测。
+
+---
+
+## 反模式 3：能力边界描述模糊
+
+只写一句"适合 Skill 作者"或"不适用于一般用户"，没有具体说明能做什么、不能做什么。
+
+```
+❌ 错误示例（模糊边界）：
+## 适用范围
+本 Skill 适合需要检查 Skill 质量的用户，不适合普通聊天场景。
+
+问题：
+- 用户不知道哪些具体操作支持
+- 不知道遇到超范围场景该怎么办
+- "普通聊天场景"是什么？太模糊
+
+✅ 正确示例（三分类 + 具体例子）：
+## 能力边界说明
+
+### ✅ 擅长处理
+1. 检查新创建的 Skill：读取文件后逐维度打分，输出结构化评分表
+2. 定位具体扣分原因：精确指出是哪个子项、在哪个文件、怎么改
+3. 验证修改效果：修改后重新打分，确认实质性改进
+...
+
+### ❌ 超出范围（附替代方案）
+1. 帮你写 Skill 内容 → 用 skill-creator 创建 Skill
+2. 评测非 Skill 类文档 → 找代码审查工具
+...
+```
+
+---
+
+## 反模式 4：触发条件写成关键词堆砌
+
+只列一堆关键词，没有说明"什么情况下触发哪个功能"，用户自己猜。
+
+```
+❌ 错误示例（关键词堆砌）：
+触发词：TRACE, 质量检查, 评测, 自检, Skill质量, 打分, 审查
+
+问题：
+- 用户不知道"打分"和"自检"有什么区别
+- 不知道是对自己的 Skill 打分还是对别人的
+- 不知道触发后会发生什么
+
+✅ 正确示例（场景化触发判断）：
+**什么时候该用本 Skill：**
+- 刚写完 SKILL.md → 触发全量 TRACE 自检
+- 修改了 FAQ / 反模式 / 行为规范等核心内容 → 触发重新评测（只检查受影响维度）
+- 用户明确要求"检查 Skill 质量" → 触发全量检查
+- 想知道"某项扣分了怎么改" → 触发专项维度检查
+
+**不该用本 Skill 的情况：**
+- 想创作一个新 Skill → 用 skill-creator
+- 想执行某个 Skill 的功能 → 直接调用目标 Skill
+```
+
+---
+
+## 反模式 5：渐进式披露只有一层
+
+整个 SKILL.md 是一个长页面，没有分层结构，用户进来就被全量信息淹没。
+
+```
+❌ 错误结构（单层平铺）：
+# Skill 名称
+一大段介绍文字 + 全部功能说明 + 全部示例 + 全部FAQ + 所有注意事项
+→ 用户需要从头到尾读完才能开始使用
+
+✅ 正确结构（三层渐进）：
+第1层（30秒上手）：
+  - 是什么 / 什么时候用 / 3 个直接可用的触发示例
+  
+第2层（按需查阅）：
+  - 详细功能说明 + 能力边界 + 操作流程
+  
+第3层（深度参考）：
+  - references/ 目录：trace-criteria-detail.md, anti-patterns.md, faq-deep.md
+```
+
+**检查方法：** 问自己"完全陌生的用户只看第一屏，能知道怎么开始用吗？"如果答案是不能，就需要加入门章节。
+
+---
+
+## 禁忌用法清单
+
+以下做法在 TRACE 自检中**一律视为不合格**：
+
+| 禁忌行为 | 为什么不行 | 解决方案 |
+|---------|---------|---------|
+| 没有 references/ 目录 | 深度文档缺失，C·规范性 多项无法满分 | 创建目录并填充核心参考文件 |
+| FAQ 少于 6 题 | C-FAQ深度 必然扣分 | 主文档 ≥6 题 + faq-deep.md ≥8 题 |
+| 能力边界只有一句话 | A-能力边界定义 最多 4.0 | 添加三分类结构，每类 ≥3 例 |
+| 没有新手入门章节 | C-渐进式披露、E-开箱即用 双双扣分 | 在文档开头添加 30 秒入门区块 |
+| 修改报告不修改文件 | TRACE 自检的根本目的是改进 Skill 本身 | 每次评分变化都要有对应文件改动 |
+| 错误提示只说"信息不足" | R-异常处理 无法满分 | 必须指出缺少哪[N]项 + 如何补充 |

skills/base-skills/skill-trace-checker/references/examples.md

@@ -0,0 +1,189 @@
+# TRACE 完整使用示例
+
+> 每个示例包含三元组：用户触发语 → 执行过程（打分+定位问题）→ 最终输出（评分表）。
+> 新手可对照这些示例了解"一次 TRACE 自检完整流程是什么样的"。
+
+---
+
+## 示例 1：全新 Skill 的首次评测（发现多项不足，完成修改）
+
+**场景：** 用户刚写完一个"短视频标题生成"Skill，首次做 TRACE 自检。
+
+---
+
+### 用户触发语
+
+```
+帮我对刚写的 short-title-skill 做 TRACE 评测，文件在 ~/.workbuddy/skills/short-title-skill/SKILL.md
+```
+
+---
+
+### 执行过程（AI 的检查动作）
+
+```
+【读取文件】
+读取 SKILL.md（2.1KB）
+没有找到 references/ 目录
+
+【逐项打分】
+
+T 可信任度：
+  - 国内适配性：全中文，示例含抖音/快手/小红书 → 5.0
+  - 安全性：无敏感操作，无P0/P1风险 → 5.0
+  - 边界透明度：⚠️ 只有一句"适合需要标题的用户"，无三分类 → 4.0
+  - 数据隐私：⚠️ 没有提及 → 4.5（纯文字生成，低风险，但仍需一句说明）
+
+R 可靠性：
+  - 异常处理：⚠️ 系统提示词只说"如果信息不够请补充"，未给出具体清单格式 → 4.0
+  - 功能完善性：覆盖标题/描述/话题标签三大场景 → 5.0
+  - 运行稳定性：⚠️ 没有"先给假设版本"的规则 → 4.0
+  - 降级兜底：⚠️ 未说明超范围场景（如要生成图片）怎么处理 → 4.5
+
+A 适用性：
+  - 能力边界定义：⚠️ 缺失三分类章节 → 3.5
+  - 触发方式精确度：有触发词列表，无场景路由 → 4.5
+  - 受众广度：⚠️ 没有说明不同用户类型 → 4.5
+  - 定制化支持：⚠️ 没有风格参数传递机制 → 4.0
+
+C 规范性：
+  - 渐进式披露：⚠️ 没有新手入门章节，没有 references/ → 4.0
+  - 结构清晰度：层次清楚，表格使用合理 → 5.0
+  - 反模式说明：⚠️ 无 references/anti-patterns.md → 3.5
+  - FAQ 深度：⚠️ 只有 2 题，远低于 ≥6 题标准 → 3.0
+
+E 有效性：
+  - 输出准确性：有"不确定时标注假设"规则 → 5.0
+  - 内容完整度：功能覆盖 → 5.0
+  - 创造力与增值：⚠️ 没有增值特性（只是生成标题，无风格定制等） → 4.0
+  - 开箱即用度：⚠️ 没有新手入门章节，无可复制示例 → 4.0
+
+【找出所有 < 5.0 子项，共 11 项，逐一修改...】
+```
+
+---
+
+### 修改后的最终评分表
+
+```
+TRACE 自检结果（修改后）
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+T 可信任度   国内适配性 5.0 | 安全性 5.0 | 边界透明度 5.0 | 数据隐私 5.0
+R 可靠性     异常处理 5.0 | 功能完善 5.0 | 运行稳定 5.0 | 降级兜底 5.0
+A 适用性     边界定义 5.0 | 触发精确 5.0 | 受众广度 5.0 | 定制化 5.0
+C 规范性     渐进披露 5.0 | 结构清晰 5.0 | 反模式 5.0 | FAQ深度 5.0
+E 有效性     输出准确 5.0 | 内容完整 5.0 | 创造力 5.0 | 开箱即用 5.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+综合：5.0 / 5.0 ✅ 达标，任务完成
+```
+
+---
+
+## 示例 2：专项检查（只检查某一维度）
+
+**场景：** 用户修改了 FAQ 部分，只想重新检查规范性维度。
+
+---
+
+### 用户触发语
+
+```
+我刚给 opc-skill 补充了 8 个 FAQ，只检查一下 C·规范性 这个维度就行
+```
+
+---
+
+### 执行过程
+
+```
+【聚焦 C·Convention 维度，跳过其他4个维度】
+
+读取 SKILL.md + references/faq-deep.md
+
+C 规范性：
+  - 渐进式披露：有新手入门章节（30秒入门），有三层结构 → 5.0
+  - 结构清晰度：文件命名语义清晰，层次分明 → 5.0
+  - 反模式说明：references/anti-patterns.md 存在，含5类反模式+对比 → 5.0
+  - FAQ 深度：主文档 8 题（≥6 ✅）+ faq-deep.md 12 题（≥8 ✅） → 5.0
+```
+
+---
+
+### 输出
+
+```
+C · Convention 专项检查结果
+━━━━━━━━━━━━━━━━━━
+渐进披露 5.0 | 结构清晰 5.0 | 反模式 5.0 | FAQ深度 5.0
+━━━━━━━━━━━━━━━━━━
+C 维度全部达标 ✅
+
+（其他4个维度未检查，如需全量评测请触发完整 TRACE 自检）
+```
+
+---
+
+## 示例 3：快速检查（只输出不合格项）
+
+**场景：** 用户赶时间，只想知道有哪些地方扣分，不需要看满分说明。
+
+---
+
+### 用户触发语
+
+```
+对 recruitment-manager 快速检查，只列出扣分项就行，不用解释满分的
+```
+
+---
+
+### 输出格式（快速模式）
+
+```
+TRACE 快速检查 — 扣分项汇总
+━━━━━━━━━━━━━━━━━━━━━━
+⚠️ A-能力边界 4.0 → 缺少三分类，只有一句"适合HR使用"
+   修复：在 SKILL.md 增加 ✅/⚠️/❌ 三分类章节，每类 ≥3 例
+
+⚠️ C-FAQ深度 3.5 → 主文档只有 3 题，缺 faq-deep.md
+   修复：主文档补充至 ≥6 题，创建 references/faq-deep.md（≥8题）
+
+⚠️ E-开箱即用 4.5 → 没有可直接复制的开场白示例
+   修复：在新手入门章节添加 ≥3 个可粘贴触发语
+━━━━━━━━━━━━━━━━━━━━━━
+待修复项：3 项 | 满分项：17 项
+```
+
+---
+
+## 示例 4：对比修改前后（版本对比模式）
+
+**场景：** 用户修改了 Skill 后想确认改进是否有效。
+
+---
+
+### 用户触发语
+
+```
+对比一下 opc-skill v1 和 v2 的区别，看看哪里有实质提升
+```
+
+---
+
+### 输出格式（对比模式）
+
+```
+版本对比评分表 — opc-skill
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+子项           v1 旧版   v2 新版   变化
+──────────────────────────────────
+A-能力边界     3.5       5.0       +1.5 ✅ 实质改进
+A-触发方式     4.5       5.0       +0.5 ✅ 实质改进
+R-异常处理     4.0       5.0       +1.0 ✅ 实质改进
+C-FAQ深度      4.5       5.0       +0.5 ✅ 实质改进
+E-开箱即用     4.5       5.0       +0.5 ✅ 实质改进
+其他15项       5.0       5.0       无变化
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+v1 综合：4.6  →  v2 综合：5.0  改进 +0.4
+结论：v2 有实质性提升，所有改进均对应文件修改 ✅
+```

skills/base-skills/skill-trace-checker/references/faq-deep.md

@@ -0,0 +1,112 @@
+# TRACE 深度 FAQ
+
+> 本文档覆盖边缘场景、工具兼容性、安全合规等主文档 FAQ 未涵盖的进阶问题。
+> 主文档 FAQ（第1-6题）已覆盖通用使用问题，本文档从第7题开始继续。
+
+---
+
+## 第 7 题：我用的是第三方 Skill 平台（不是 Skillhub），TRACE 标准还适用吗？
+
+适用，但有调整空间。TRACE 五维度（T/R/A/C/E）是通用质量框架，不依赖特定平台。  
+需注意以下差异：
+- **T-国内适配性**：如果目标用户是海外用户，可将"中文示例/国内平台"替换为对应地区的标准
+- **C-规范性**：不同平台对 references/ 文件结构的支持不同，若平台不支持多文件，可将所有内容合并在单文件中，但需标注层级
+- 其余三维度（R/A/E）标准不变
+
+---
+
+## 第 8 题：TRACE 自检通过了，但 Skillhub 官方评测还是扣分，正常吗？
+
+正常。原因有二：
+1. **官方评测包含用户行为数据**：实际用户的使用率、满意度、完成率都是评分因子，AI 自检无法模拟
+2. **官方有人工审核层**：某些标准（如是否含有违规内容、品牌语气是否符合平台调性）需人工判断
+
+建议：把 TRACE 自检作为"发布前保底检查"，官方评测作为"发布后持续改进参考"，两者互补。
+
+---
+
+## 第 9 题：Skill 里需要用到用户的真实数据（如工资、业绩），怎么满足 T-数据隐私？
+
+需要在 FAQ 或专项章节中明确说明以下内容：
+
+1. **数据去向**：用户输入的数据只用于本次会话，不会被存储或用于训练
+2. **脱敏建议**：提供示例脱敏操作，如"可以把真实金额替换为相对比例，如'A 比 B 高 30%'"
+3. **最小化原则**：说明哪些数据是必须的，哪些是可选的，让用户自主决定提供多少
+
+```
+示例说明文字（可直接放入 FAQ）：
+Q: 我需要输入真实数据吗？会不会泄露？
+A: 本 Skill 只在当前对话中使用你输入的数据，关闭对话后数据不会保留。
+   如果你处理的是敏感数据（如工资/业绩），建议使用脱敏版本：
+   - 用代号替换姓名（张三 → 员工A）
+   - 用区间替换精确数字（月薪18500 → 月薪1-2万区间）
+```
+
+---
+
+## 第 10 题：Skill 生成的内容可以商用吗？TRACE 里需要说明吗？
+
+需要在 FAQ 中明确说明，否则 T-边界透明度 会扣分。标准说明方式：
+
+```
+Q: 用这个 Skill 生成的内容可以直接商用吗？
+A: 可以。本 Skill 生成的内容版权归用户所有，可用于商业用途。
+   注意：如果生成内容中引用了特定第三方素材（如品牌名称、歌词），
+   请确认相关权利不涉及版权侵犯，本 Skill 不对引用内容的商用合规性负责。
+```
+
+---
+
+## 第 11 题：多个 Skill 协同工作时（如"地图指挥官"调用三个子 Skill），TRACE 如何评测？
+
+**评测原则：每个 Skill 独立评测，主 Skill 额外要求。**
+
+- 子 Skill：按正常 TRACE 标准各自评测
+- 主 Skill（编排/路由层）额外检查：
+  - **A-触发方式**：是否清楚说明了"什么需求路由到哪个子 Skill"
+  - **R-降级兜底**：某个子 Skill 不可用时，主 Skill 是否有降级处理策略
+  - **T-边界透明度**：用户能否清楚知道自己在和哪个子 Skill 交互
+
+---
+
+## 第 12 题：我的 Skill 只有一个很简单的功能（比如"帮我格式化代码"），也需要 references/ 目录吗？
+
+不是强制的，但要通过 TRACE，必须：
+- **如果没有 references/**：在 SKILL.md 里必须完整覆盖 FAQ ≥6 题、反模式说明、以及能力边界三分类
+- **如果有 references/**：可以将 FAQ、反模式、示例分散到子文件，SKILL.md 可以更简洁
+
+**实用建议：** 对于功能简单的 Skill，建议用"单文件扩展方案"——在 SKILL.md 底部加 `## 常见问题`、`## 注意事项`、`## 使用示例` 三个章节，代替 references/ 多文件。
+
+---
+
+## 第 13 题：references/ 文件有哪些是"必须有"，哪些是"建议有"？
+
+| 文件 | 必须 / 建议 | 缺失影响 |
+|-----|---------|---------|
+| `examples.md` | 必须（若功能复杂） | E-内容完整度、C-文档质量 扣分 |
+| `anti-patterns.md` | 必须 | C-反模式与FAQ 会扣分 |
+| `faq-deep.md` | 必须（FAQ<6题时） | C-FAQ深度 扣分 |
+| `sample-reports.md` | 建议（评测类Skill专用） | E-内容完整度 轻微扣分 |
+| `system-prompt.md` | 建议（若有复杂行为规范） | R-功能完善性 轻微扣分 |
+
+---
+
+## 第 14 题：触发词写了很多，但 AI 有时候还是没有自动调用，这影响 TRACE 评分吗？
+
+影响 A-触发方式精确度。  
+原因通常是：触发词太模糊，与其他 Skill 产生冲突。改进方法：
+- 换用"行为+对象"组合触发词，而非单个名词（"检查 Skill 质量" > "质量"）
+- 在触发词旁边加场景说明（"当用户提到...时触发"）
+- 在 SKILL.md 的触发条件章节列出典型触发句型（整句话，不只是关键词）
+
+---
+
+## 第 15 题：我对同一个 Skill 做了 3 次 TRACE，每次分数都不一样，正常吗？
+
+正常，±0.3 分属于可接受的 AI 评分波动。  
+超过 0.5 分的波动通常意味着：
+- 该子项的满分标准本身描述模糊 → 对照 `trace-criteria-detail.md` 的"5.0 vs 4.5 对比案例"，找到客观标准
+- AI 对该文件理解不一致 → 在 SKILL.md 中把该子项的满足方式写得更明确，减少解读空间
+
+**实用建议：** 分数在 4.8 及以上时，可以视为达到实用标准，不必无限追求字面上的 5.0。
+

skills/base-skills/skill-trace-checker/references/sample-reports.md

@@ -0,0 +1,133 @@
+# 真实评分报告案例集
+
+> 本文档展示三种典型场景的完整评分报告：不合格 Skill、刚好达标 Skill、高质量 Skill。
+> 新手对照这些案例，能快速理解"好的评分报告是什么样的"。
+
+---
+
+## 案例 A：不合格 Skill（综合 3.8 分）
+
+**Skill 概述：** 某"情绪日记助手"Skill，只有 SKILL.md 一个文件，内容约 500 字，无 references/ 目录。
+
+```
+TRACE 自检结果 — emotion-diary-skill
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+T 可信任度
+  国内适配性  5.0  ✅ 全中文，示例含微信/朋友圈场景
+  安全性      4.5  ⚠️ 未声明"不能替代心理医生"，专业领域无免责声明
+  边界透明度  3.5  ⚠️ 缺少三分类章节
+  数据隐私    3.0  ⚠️ 涉及用户情绪/私密内容，完全没有隐私说明
+
+R 可靠性
+  异常处理    4.0  ⚠️ 情绪状态难以描述时，只说"请详细说明"
+  功能完善性  4.5  基本场景覆盖，缺"情绪复盘"功能
+  运行稳定性  4.0  ⚠️ 用户只说"我心情不好"时，AI直接提问，没有先给共情回应
+  降级兜底    3.5  ⚠️ 没有说明"需要专业帮助"时怎么处理
+
+A 适用性
+  能力边界    3.0  ⚠️ 没有边界章节
+  触发方式    4.5  触发词完整，但无场景路由
+  受众广度    3.5  ⚠️ 没有说明不同用户（青少年/职场人/老年人）的使用差异
+  定制化      3.0  ⚠️ 没有风格定制机制
+
+C 规范性
+  渐进披露    3.5  ⚠️ 无新手入门，无 references/
+  结构清晰    4.0  基本分层，但无表格
+  反模式      2.0  ⚠️ 完全没有
+  FAQ深度     2.0  ⚠️ 只有1题
+
+E 有效性
+  输出准确    4.5  有基本准确性约束
+  内容完整    3.5  ⚠️ 缺情绪复盘/情绪追踪等核心功能
+  创造力      3.5  ⚠️ 只是记录，无增值
+  开箱即用    3.5  ⚠️ 无新手入门，无示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+综合：3.8 / 5.0 ❌ 不达标，需要大幅修改
+待修复：15 项低于 5.0，核心缺失：能力边界/隐私说明/反模式/FAQ
+```
+
+---
+
+## 案例 B：修改后达标 Skill（综合 5.0 分）
+
+**背景：** 同一个 emotion-diary-skill，经过两轮修改后达标。
+
+**主要修改：**
+1. 新增 references/ 目录，创建 anti-patterns.md / faq-deep.md / examples.md
+2. 在 SKILL.md 增加"新手30秒入门"章节和能力边界三分类
+3. 系统提示词添加"心理健康声明"和"情绪不明确时先给共情版本"规则
+4. FAQ 从 1 题扩展到 8 题，faq-deep.md 覆盖 10 个边缘场景
+
+```
+TRACE 自检结果（修改后）— emotion-diary-skill v2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+T 可信任度   国内适配性 5.0 | 安全性 5.0 | 边界透明度 5.0 | 数据隐私 5.0
+R 可靠性     异常处理 5.0 | 功能完善 5.0 | 运行稳定 5.0 | 降级兜底 5.0
+A 适用性     边界定义 5.0 | 触发精确 5.0 | 受众广度 5.0 | 定制化 5.0
+C 规范性     渐进披露 5.0 | 结构清晰 5.0 | 反模式 5.0 | FAQ深度 5.0
+E 有效性     输出准确 5.0 | 内容完整 5.0 | 创造力 5.0 | 开箱即用 5.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+综合：5.0 / 5.0 ✅ 达标，任务完成
+```
+
+---
+
+## 案例 C：高质量 Skill（综合 5.0 分，附评分亮点说明）
+
+**Skill 概述：** opc-skill（一人公司运营助手），功能完整，文档体系健全。
+
+```
+TRACE 自检结果 — opc-skill v2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+T 可信任度   国内适配性 5.0 | 安全性 5.0 | 边界透明度 5.0 | 数据隐私 5.0
+R 可靠性     异常处理 5.0 | 功能完善 5.0 | 运行稳定 5.0 | 降级兜底 5.0
+A 适用性     边界定义 5.0 | 触发精确 5.0 | 受众广度 5.0 | 定制化 5.0
+C 规范性     渐进披露 5.0 | 结构清晰 5.0 | 反模式 5.0 | FAQ深度 5.0
+E 有效性     输出准确 5.0 | 内容完整 5.0 | 创造力 5.0 | 开箱即用 5.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+综合：5.0 / 5.0 ✅ 达标，任务完成
+
+--- 亮点说明 ---
+
+T-边界透明度 亮点：
+  三分类结构清晰，超范围每项附替代方案（如"SEO 优化 → 用专业 SEO 工具"）
+
+R-异常处理 亮点：
+  系统提示词固化格式："缺少[N]项才能精准输出：1. [项目] 2. [项目]"
+  明确禁止"请提供更多信息"笼统回复
+
+A-触发精确度 亮点：
+  每个模块有三级路由：主关键词 → 功能分类 → 子功能触发
+
+C-FAQ深度 亮点：
+  主文档 8 题 + faq-deep.md 12 题，覆盖隐私合规/多人协作/商用授权等边缘场景
+
+E-开箱即用 亮点：
+  新手入门章节含 5 个可直接复制的开场白，覆盖5个不同使用场景
+```
+
+---
+
+## 案例 D：边界情况（4.8 分，可接受但有已知局限）
+
+**背景：** 一个功能极简的"番茄钟提醒"Skill，功能单一，不适合建完整 references/ 体系。
+
+```
+TRACE 自检结果 — pomodoro-skill
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+T 可信任度   国内适配性 5.0 | 安全性 5.0 | 边界透明度 5.0 | 数据隐私 5.0
+R 可靠性     异常处理 5.0 | 功能完善 5.0 | 运行稳定 5.0 | 降级兜底 5.0
+A 适用性     边界定义 5.0 | 触发精确 5.0 | 受众广度 4.5 | 定制化 4.5
+C 规范性     渐进披露 5.0 | 结构清晰 5.0 | 反模式 5.0 | FAQ深度 5.0
+E 有效性     输出准确 5.0 | 内容完整 5.0 | 创造力 4.5 | 开箱即用 5.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+综合：4.9 / 5.0
+
+扣分说明（已知局限，非修复必要项）：
+  A-受众广度 4.5：功能极简，团队协作场景天然不适用，非设计缺陷
+  A-定制化 4.5：番茄钟时长已支持参数传入，但无法做更复杂个性化（符合功能定位）
+  E-创造力 4.5：工具型 Skill，功能本身无需增值特性
+
+结论：综合 4.9 达到实用标准，已知局限符合功能定位。
+     按实际标准可视为 ✅ 达标。
+```

skills/base-skills/skill-trace-checker/references/skill-checklist.md

@@ -0,0 +1,61 @@
+# Skill TRACE 自检清单（一页纸版本）
+
+创建或修改 Skill 后，逐项打勾。所有项目通过后才能交付。
+
+---
+
+## T · Trust 可信任度
+
+- [ ] SKILL.md 全文为中文，触发词包含中文关键词
+- [ ] 所有示例场景基于国内真实平台
+- [ ] 系统提示词有"禁止行为"列表，无 P0/P1 安全风险
+- [ ] 有"能力边界说明"独立章节（三分类 + 各类 ≥3 个具体例子）
+- [ ] 有数据隐私/安全使用说明（FAQ 或专项章节）
+
+---
+
+## R · Reliability 可靠性
+
+- [ ] 系统提示词规定：信息不足时先给假设版本 + 列具体补充清单
+- [ ] 明确禁止"请提供更多信息"等笼统提示
+- [ ] 所有主要使用场景有覆盖，每个功能有输出格式说明
+- [ ] 超范围请求有替代工具引导说明
+- [ ] 多任务场景有优先级处理说明
+
+---
+
+## A · Adaptability 适用性
+
+- [ ] 每个功能模块有"精确触发条件"（主触发 + 子模块路由）
+- [ ] 能力边界三分类各有具体例子（不是泛泛而谈）
+- [ ] 说明了不同类型用户（垂直行业/团队等）的使用方式
+- [ ] 有定制化使用指南（风格卡片或参数传递机制）
+
+---
+
+## C · Convention 规范性
+
+- [ ] 有快速导航/新手入门章节（第一屏30秒能上手）
+- [ ] references/ 目录存在且文件名语义清晰
+- [ ] references/anti-patterns.md：≥3类反模式 + 改进对比 + 禁忌清单
+- [ ] 主文档 FAQ ≥6 题（通用问题）
+- [ ] references/faq-deep.md：≥8 题（边缘场景/工具兼容/安全合规）
+
+---
+
+## E · Effectiveness 有效性
+
+- [ ] 系统提示词有输出准确性约束（禁止在不确定领域胡编）
+- [ ] 功能点覆盖该领域 80%+ 的常见需求
+- [ ] 有 ≥3 项超出基础功能的增值特性
+- [ ] 有"新手入门"章节 + ≥3 个可直接复制的开场白示例
+- [ ] references/examples.md：每个主要模块有真实输出示例（三元组格式）
+
+---
+
+## 最终确认
+
+```
+[ ] 全部 25 项通过 → 输出 TRACE 评分表，综合 5.0 / 5.0 ✅
+[ ] 有未通过项 → 修改对应文件后重新检查，不允许交付
+```

skills/base-skills/skill-trace-checker/references/trace-criteria-detail.md

@@ -0,0 +1,163 @@
+# TRACE 评分细则与案例
+
+## T · Trust — 详细评分细则
+
+### 国内适配性
+
+**5.0 标准：**
+- SKILL.md 全文为中文
+- 触发词包含中文关键词（不仅是英文缩写）
+- 所有示例场景基于国内真实平台（微信、淘宝、小红书、微博、飞书、企业微信等）
+- 专有名词使用国内习惯叫法（"公众号"而非"WeChat Official Account"）
+
+**4.0～4.9 常见原因：**
+- 示例中混有英文平台（Slack、Twitter 等）而未提国内替代
+- 触发词只有英文（"content creation" 而非"内容创作"）
+
+**实际修改示例：**
+```
+❌ 扣分状态："Write a Twitter thread about..."
+✅ 修复后："写一组微博/小红书/公众号推文..."
+```
+
+---
+
+### 安全性
+
+**5.0 标准：**
+- 系统提示词中有明确的"禁止行为"列表
+- 不引导用户输入他人账号密码
+- 不承诺能访问用户的后台数据（除非通过正规 API）
+- 法律/税务/医疗等专业领域主动声明局限性
+
+**常见 P0/P1 风险：**
+- P0：引导用户分享账号密码
+- P0：声称能直接访问用户的平台账号后台
+- P1：在专业法律/医疗建议中不声明"请咨询专业人士"
+
+---
+
+### 边界透明度
+
+**5.0 标准（必须同时满足）：**
+- 有独立的"能力边界说明"章节（不能混在其他章节里）
+- 三分类各有 ≥3 个具体例子：
+  - ✅ 擅长处理（列出具体任务类型）
+  - ⚠️ 需要素材（列出每类需要的具体信息）
+  - ❌ 超出范围（列出并给出替代方案）
+
+---
+
+## R · Reliability — 详细评分细则
+
+### 异常处理
+
+**5.0 标准：**
+- 系统提示词中有明确规则：遇到信息不足时，先给假设版本，再列出具体缺少什么
+- 精确错误提示格式：
+  ```
+  需要补充以下[N]项才能完成：
+  1. [具体项目1]（说明为什么需要）
+  2. [具体项目2]
+  ```
+- 明确禁止："请提供更多信息"/"请补充背景"等笼统提示
+
+**4.0 扣分示例：**
+```
+❌ AI 回复："请提供更多关于您产品的信息"
+✅ 应该是："先给你一个手工皂详情页示例版本，如果要精准化，需要补充：
+   1. 产品的核心卖点（天然原料/香味/适合肤质）
+   2. 定价区间（影响文案档次定位）
+   3. 目标买家（20岁学生 vs 30岁白领，文案完全不同）"
+```
+
+---
+
+### 运行稳定性 / 降级兜底
+
+**5.0 标准：**
+- 模糊输入处理：给假设版本（不是空回复或错误）
+- 超范围处理：给替代工具 + 帮用户准备输入内容
+- 多任务处理：按优先级排序，告知处理顺序
+- 信息缺失处理：继续输出可参考版本 + 附具体补充清单
+
+---
+
+## A · Adaptability — 详细评分细则
+
+### 触发方式精确度
+
+**5.0 标准（必须同时满足）：**
+- 每个功能有具体触发示例（不只是关键词）
+- 有"精确触发条件"说明（不同输入路由到不同子模块）
+- 示例能让用户判断"我的需求该用这个功能吗"
+
+**4.5 vs 5.0 对比：**
+```
+4.5（触发条件散乱）：
+"关键词：文章、脚本、文案、月刊、播客"
+
+5.0（精确触发条件）：
+"需要创作文字类内容（文章/脚本/文案/标题/简介）→ 直接触发内容创作模块
+ 需要排期或策划（选题/发布日历/内容规划）→ 触发内容策划子模块
+ 需要多平台适配（同一内容改写为不同平台版本）→ 触发多平台适配子模块"
+```
+
+---
+
+## C · Convention — 详细评分细则
+
+### 渐进式披露
+
+**5.0 标准（至少满足3层）：**
+- 第1层：快速导航/新手入门（30秒能开始用）
+- 第2层：功能详情（按需查阅）
+- 第3层：references/ 深度文档（高频用户/开发者参考）
+
+**检查方法：** 问自己"一个完全不了解这个 Skill 的人，看到第一屏能知道怎么开始用吗？"
+
+### FAQ 深度
+
+**5.0 标准：**
+- 主文档 FAQ：≥6题，覆盖通用使用问题
+- references/faq-deep.md：≥8题，覆盖：
+  - 垂直领域适配
+  - 工具/平台兼容性
+  - 定制化使用
+  - 数据安全
+  - 商用授权
+
+---
+
+## E · Effectiveness — 详细评分细则
+
+### 开箱即用度
+
+**5.0 标准：**
+- 有"新手入门"或"快速开始"专题章节
+- 有 ≥3 个可直接复制粘贴的开场白示例
+- 用户无需阅读完整文档就能开始使用
+- 首次输出效果不低于"达到预期的70%"
+
+**4.5 vs 5.0 对比：**
+```
+4.5（只有功能说明，没有入门引导）：
+"功能列表：月刊撰写、播客脚本、选题策划..."
+
+5.0（有新手30秒入门）：
+"直接把需求发过来就行。几个典型开场白：
+ '帮我写这个月的博客月刊，主题是 AI 工具盘点'
+ '帮我做一个双十一活动方案，我卖手工皂，客单价80元'
+ '有客户投诉质量问题，帮我写回复'"
+```
+
+### 创造力与增值
+
+**5.0 标准（需有 ≥3 项增值特性）：**
+- 风格定制机制
+- 多平台自动适配
+- 主动询问调整意愿
+- 智能分类/排序
+- 同义词/模糊匹配感知
+- 格式自动兼容（Notion/飞书/Excel等）
+- 预防性建议（提前指出潜在问题）

skills/base-skills/skill-trace-evaluation/LICENSE.txt

@@ -0,0 +1,2 @@
+Apache-2.0
+

skills/base-skills/skill-trace-evaluation/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: skill-trace-evaluation
+description: Evaluate any Agent Skill using the SkillHub TRACE model — a five-dimension quality framework covering Trust (可信任度), Reliability (可靠性), Adaptability (适用性), Convention (规范性), and Effectiveness (有效性). This skill produces a per-dimension evaluation report with 20 sub-item scores, evidence-based commentary, baseline comparison (no-skill vs with-skill), Official compliance checklist (agentskills.io), and an overall rating (Excellent / Good / Needs improvement). Outputs both Markdown and interactive HTML reports with SVG radar charts. The evaluation conclusion is explicitly based on the SkillHub TRACE evaluation system, co-developed by Tencent Technology, SkillHub, and Tencent Xuanwu Lab. Use when the user asks for TRACE scoring, a T/R/A/C/E evaluation report, quality assessment by dimension, improvement suggestions organized by Trust/Reliability/Adaptability/Convention/Effectiveness. Also use when the user mentions "TRACE 评测", "T/R/A/C/E 评估", "五维度技能评估", "技能质量评测", "TRACE 评分", "生成 TRACE 报告", "TRACE 打分", "根据 TRACE 评估技能", "TRACE 五维画像", "TRACE 基线对比", "TRACE 雷达图", "技能评估报告", "skill evaluation report", "score this skill".
+license: Apache-2.0
+---
+
+# Skill TRACE 质量评测
+
+> **评估模型：脚本计算确定性基分 + AI 阅读内容后语义校准（±0.3）→ 最终分。**
+> 详细评分标准见 [references/scoring-criteria.md](references/scoring-criteria.md)，校准规则见 [references/calibration-guide.md](references/calibration-guide.md)。
+
+---
+
+## ⚡ 新手 30 秒入门
+
+**干什么？** 对任意 Agent Skill 做 TRACE 五维度质量评分，输出带子项分的评估报告。
+
+**什么时候触发？**
+- 刚写完一个新 Skill，想知道质量怎么样 → 直接用
+- 用户要求 "检查 Skill 质量"、"TRACE 评测"、"技能打分"
+- 提供了 Skill 目录路径 + "评估"/"评测"/"打分" 关键词
+
+**触发示例：**
+```
+✅ "用 TRACE 评测 /path/to/skill"
+✅ "TRACE 评测 ddd-architecture-awesome"
+✅ "对 skill-trace-evaluation 做五维度评估"
+✅ "生成 TRACE 报告 + HTML 雷达图"
+✅ "严格评测 jimeng-prompt-text2image"       （全部子项需 5.0）
+✅ "快速检查这个 Skill 有哪些扣分项"          （仅输出扣分项）
+✅ "只检查 T 维度"                            （单维度聚焦）
+✅ "我修改了 FAQ，重新评测一下规范性"
+✅ "输出 TRACE 五维画像 + 基线对比"
+✅ "技能评估报告 + 官方合规检查"
+```
+
+**一句话流程：** 运行脚本拿基分 → 阅读 SKILL.md → 对照评分细则校准 → 产出报告。
+
+---
+
+## 执行时机
+
+以下场景适合触发 TRACE 评测：
+
+1. **新 Skill 完成编写**：刚写完 SKILL.md，想知道质量基线
+2. **Skill 重大修改后**：修改了功能说明、FAQ、边界条件、触发词等核心内容
+3. **用户明确要求**："检查 Skill 质量"、"TRACE 评测"、"技能打分"
+4. **第三方评审**：平台审核员或社区用户对 Skill 做质量评估
+
+---
+
+## 能力边界说明
+
+### ✅ 擅长处理
+
+1. 评估任意 Agent Skill，输出 20 子项评分
+2. 定位具体扣分原因，每个分数附证据
+3. 生成标准化报告（dimension-level 中文评语 + 子项分表 + 改进建议）
+4. 验证修改是否有效：修改后重新评测，对比前后分数变化
+5. 对比两个版本差异：判断新版本比旧版本在哪些子项有实质提升
+6. 支持标准/严格/快速/单维度四种模式
+
+### ⚠️ 需要素材
+
+1. 完整评估需要 Skill 目录路径（含 SKILL.md），只凭名称无法评测
+2. R1/E1/E3 评分需要 AI 自己阅读正文判断语义质量——脚本只提供结构基分
+
+### ❌ 超出范围（附替代方案）
+
+1. 帮你写 Skill 内容 → 用 `skill-awesome`（规范知识）或 `skill-trace-checker`（发布前自检）
+2. 评测非 Skill 类文档 → 找对应工具
+3. 自动发布 Skill → 手动完成
+
+---
+
+## 评估流程
+
+```
+Step 1 ──── Step 2 ──── Step 3 ──── Step 4
+收集基分    阅读技能    逐项校准    产出报告
+────────────────────────────────────────────
+trace_ev-   AI 直接    基分 ±0.3    Markdown
+aluate.py   阅读正文    附调整理由    + 可选 HTML
+```
+
+### Step 1：收集基分
+
+```bash
+python3 scripts/trace_evaluate.py --skill-dir <path> --format json
+```
+
+输出含 `base_scores`：每子项 `base`（1.0-5.0）、`formula`（计算公式）、`evidence`（证据字段）。
+
+### Step 2：阅读技能
+
+必须自己阅读 SKILL.md 正文 + 扫描 references/、examples/ 目录。脚本提供结构数据，AI 判断内容质量。
+
+**AI 阅读时的检查思路示例：**
+
+```
+【T 维】
+  安全 → 查有无密钥/secrets/脚本，正文有无安全声明
+  国内 → 查全文中文化程度、示例是否基于国内平台
+  边界 → 查有无独立边界章节、三分类是否每类≥3例
+  隐私 → 查有无数据隐私说明（FAQ 或专项章节）
+
+【R 维】
+  异常 → 查 Gotchas 是否包含"交互式引导模板"（先假设版本→列缺失项）
+  功能 → 查 workflow 步骤是否覆盖所有声明功能
+  稳定 → 查有无 validate-plan-execute 循环或等效约束
+  降级 → 查边界章节中超范围后是否给替代方案
+
+【A 维】
+  边界定义 → 查三分类是否有场景化判断逻辑（"什么时候该用/不该用/模糊怎么判"）
+  触发 → 查 description 信息量，是关键词堆砌还是场景化路由
+  受众 → 查有无显式说明适用用户类型
+  定制 → 查有无风格/参数传递机制
+
+【C 维】
+  文档 → 查 examples 数量是否达标（prompt≥10/cli≥4/doc≥5）
+  披露 → 查 body 行数 + references 文件数，是否三层结构
+  结构 → 查 name 规范 + refs 子目录≥2
+  反模式/FAQ → 查 Gotchas 数量是否≥5 + FAQ 是否≥6且非充数
+
+【E 维】
+  准确 → 查有无"禁止胡编"规则或等效约束
+  完整 → 查 examples 数量是否达阈值（prompt≥25/cli≥4/doc≥5）
+  增值 → 查 refs 子目录≥2 + 是否有评估框架/决策树等深度领域知识
+  开箱 → 查有无快速开始章节 + ≥3 个可复制开场白
+```
+
+### Step 3：逐项校准
+
+查 `base` → 读 [references/scoring-criteria.md](references/scoring-criteria.md) 中该子项的满分标准 + 扣分原因 → 判断正文内容匹配哪一档 → 按 [references/calibration-guide.md](references/calibration-guide.md) 调整（±0.3）→ 附一句调整理由。
+
+### Step 4：产出报告 ⚠️ 必须执行
+
+**评分完成后必须输出报告，不允许只口头报告分数而不写入文件。**
+
+报告使用统一模板，模板文件中有 `{...}` 占位符，替换为实际评估结果后写入目标文件。
+
+#### 报告模板
+
+| 格式 | 模板文件 | 说明 |
+|------|----------|------|
+| **Markdown** | `examples/trace-report.generated.md` | 纯文本，控制台可读，适合存档和 diff |
+| **HTML** | `examples/trace-report.generated.html` | 可视化雷达图 + Tailwind 卡片，适合浏览器展示和分享 |
+
+#### 让用户选择格式
+
+**评分完成后，必须用 AskUserQuestion 工具询问用户选择输出格式：**
+
+```
+问题：评估完成，请选择报告输出格式
+选项：
+- "Markdown 报告" — 使用 examples/trace-report.generated.md 模板，输出纯文本报告
+- "HTML 报告" — 使用 examples/trace-report.generated.html 模板，输出含 SVG 雷达图的交互式报告
+- "两者都要" — 同时输出 Markdown + HTML
+```
+
+**用户选择后：**
+- 选 "Markdown" → 基于 `trace-report.generated.md` 模板填入数据 → 写入 `{skill-dir}/trace-report.md`
+- 选 "HTML" → 基于 `trace-report.generated.html` 模板填入数据 → 写入 `{skill-dir}/evaluation-report.html`
+- 选 "两者都要" → 同时生成上述两个文件
+
+**写入完成后，必须向用户报告文件路径。**
+
+#### Markdown 报告结构
+
+1. 综合评分表（5 维 + 综合）
+2. 一句结语
+3. 五维详析（每维 4 子项：得分 + 证据 + 建议）
+4. no-skill 基线对比表
+5. 官方规范合规表（10 项 agentskills.io 检查）
+6. 优化建议（优先级排序 P1/P2/P3）
+7. Skill 基础画像
+
+#### HTML 报告包含
+
+- SVG 雷达图（T/R/A/C/E 五轴）
+- 五维评分卡片 + 进度条
+- 20 子项详表（每子项：得分 + 证据 + 建议）
+- 基线对比 + 官方合规 + 优化建议 + Skill 画像
+- 支持 Print 和移动端响应式
+
+### 评测后的改进指引
+
+TRACE 评测不只是打一个分数，最终目标是帮助 Skill 达到更高质量。评测报告产出后：
+
+1. **定位扣分项**：查看报告中 < 5.0 的子项，对照 [scoring-criteria.md](references/scoring-criteria.md) 中该子项的"满分标准"和"修改对比"示例
+2. **修改对应文件**：每个扣分点都必须对应 SKILL.md 或 references/ 文件的实质改动（禁止只改报告措辞不修改文件）
+3. **重新评测验证**：修改后再次运行评测，确认分数有实质提升
+4. **参考案例**：不知道怎么改时，查看 [trace-anti-patterns.md](references/trace-anti-patterns.md) 中同类问题的正确修复方式
+
+> 评分在 4.8 及以上时可视为达到实用标准，不必无限追求字面上的 5.0。
+
+---
+
+## 评分标准速查
+
+评分细则全文在 [references/scoring-criteria.md](references/scoring-criteria.md)，校准规则全文在 [references/calibration-guide.md](references/calibration-guide.md)。以下为 20 子项的基分公式 + 满分标准摘要。
+
+### T · Trust（可信任度）
+
+| ID | 名称 | 基分公式 | 满分标准摘要 |
+|----|------|---------|------------|
+| T1 | 安全性扫描 | `4.5 + no_scripts(+0.3) + secdecl(+0.2) - secrets(-1.0)` | 无密钥+无scripts+有安全声明 |
+| T2 | 国内适配性 | `has_chinese ? 5.0 : 2.0` | 全中文，示例基于国内平台 |
+| T3 | 边界透明度 | `boundary ? 4.5+0.3(when_to_use) : 3.0` | 三分类（✅/⚠/❌），每类≥3例 |
+| T4 | 数据隐私规范 | `4.5 + secdecl(+0.5) - scripts(-0.2)` | 声明"不收集/不处理数据" |
+
+**T 维扣分常见原因：** 示例全是英文场景；没有隐私使用说明；边界描述模糊（只说"有些场景不支持"）。
+
+### R · Reliability（可靠性）
+
+| ID | 名称 | 基分公式 | 满分标准摘要 |
+|----|------|---------|------------|
+| R1 | 异常处理 | `gotchas ? 4.0+0.5(val) : 3.0` | Gotchas + 交互式引导模板 |
+| R2 | 功能完善性 | `WF ? 4.5+0.3(steps≥5或exs≥10) : 3.5~4.0` | Workflow+场景覆盖无死角 |
+| R3 | 运行稳定性 | `4.0 + gotchas/rules(+0.3) + val(+0.2)` | 约束规则+校验清单 |
+| R4 | 降级兜底 | `boundary ? 4.5 : 3.5` | 超出范围给替代工具引导 |
+
+**R 维扣分常见原因：** 用户输入不完整时 AI 直接停下问，没有先给假设版本；超范围请求直接拒绝，没有替代方案引导。
+
+### A · Adaptability（适用性）
+
+| ID | 名称 | 基分公式 | 满分标准摘要 |
+|----|------|---------|------------|
+| A1 | 能力边界定义 | `boundary+when_to_use ? 4.5 : 4.0` | 场景化判断逻辑 |
+| A2 | 触发方式 | `desc≥100 ? 5.0 : 3.5~4.5` | 场景化路由，非关键词堆砌 |
+| A3 | 受众广度 | `4.0 + chinese(+0.3)` | 显式说明适用用户类型 |
+| A4 | 定制化支持 | `type=cli或exs≥10 ? 4.5 : 4.0` | 风格卡片/场景参数/配置机制 |
+
+**A 维扣分常见原因：** 触发方式只有关键词列表，没有"什么情况用哪个功能"的判断逻辑；没有说明不同类型用户如何使用。
+
+### C · Convention（规范性）
+
+| ID | 名称 | 基分公式 | 满分标准摘要 |
+|----|------|---------|------------|
+| C1 | 文档质量 | `exs≥阈值(cli=4/prompt=10) ? 5.0 : 3.5~4.5` | 示例可直接复制、格式规范 |
+| C2 | 渐进式披露 | `refs≥8+body<200 ? 5.0 : 3.0~4.5+th(+0.2)` | 三层结构30秒上手 |
+| C3 | 结构清晰 | `4.5 + name(+0.2) + refsd≥2(+0.3)` | refs子目录≥2 |
+| C4 | 反模式与FAQ | `gotchas ? 4.5+0.3(gc≥5) : 3.5` | Gotchas≥5 + FAQ≥6非充数 |
+
+**C 维扣分常见原因：** 没有 references/ 深度文档；FAQ 只有 3~4 题覆盖面不够；无反模式案例，用户不知道什么做法会导致差输出。
+
+### E · Effectiveness（有效性）
+
+| ID | 名称 | 基分公式 | 满分标准摘要 |
+|----|------|---------|------------|
+| E1 | 输出准确性 | `WF ? 4.5+0.3(val) : 4.0` | 场景区分明确、禁止胡编规则 |
+| E2 | 内容完整度 | `exs≥阈值(prompt=25/cli=4/doc=5) ? 5.0 : 3.0~4.5` | 场景全覆盖、E2E示例 |
+| E3 | 创造力与增值 | `refsd≥2 ? 4.5+0.2(refs≥10) : 4.0` | 评估框架/决策树/领域知识体系 |
+| E4 | 开箱即用度 | `4.0 + WF(+0.3) + val(+0.3) + gotchas(+0.2) + cli(+0.2)` | 快速开始章节+可复制开场白 |
+
+**E 维扣分常见原因：** 没有新手入门引导，用户不知道从哪里开始；输出示例不够真实（用通用模板而非真实场景）；缺乏增值特性，只是机械执行指令。
+
+---
+
+## 定制化使用指南
+
+在触发时可传入以下参数定制评测行为：
+
+| 模式 | 触发关键词 | 行为 |
+|------|-----------|------|
+| **标准模式** | `"TRACE 评测"`（默认） | 全量 20 子项评测，输出完整报告 |
+| **严格模式** | `"严格评测"` | 所有子项必须达到 5.0，中间分视为不合格 |
+| **快速模式** | `"快速检查"` / `"只看扣分项"` | 仅输出 < 4.5 的扣分项，跳过满分说明 |
+| **专项模式** | `"只检查 [维度]"` | 聚焦单个维度，其他维度跳过 |
+| **对比模式** | `"对比修改前后"` | 提供两版路径 → 输出差异对比表 |
+| **HTML 报告** | `"生成雷达图"` / `"可视化"` | 除 Markdown 外，额外生成含 radar 图的 HTML |
+
+---
+
+## 校准规则速查
+
+| # | 规则 | 说明 |
+|---|------|------|
+| 1 | 仅在有语义信号时调整 | 正文有满分模式→上调，有扣分模式→下调。都不匹配→不调 |
+| 2 | 调幅 ±0.3 | 单子项 max ±0.3。4.5 不能跳到 5.0（只能到 4.8） |
+| 3 | 附调整理由 | 一句中文，引用具体内容 |
+| 4 | 去重降档 | `ref_names` 有 ≥3 同版本前缀 → C2/E2 降一档（max 4.5） |
+| 5 | 完美阈值缓冲 | 同维 4 子项全可到 5.0 → 查隐性瑕疵 → 有则 max 4.8 |
+| 6 | 类型感知 | CLI型 C2=150行 E2=4exs。脚本已内置 |
+
+---
+
+## 综合评分
+
+五维均分 = Overall。
+
+| Rating | Score |
+|--------|-------|
+| **Excellent (优秀)** | ≥ 4.5 |
+| **Good (良好)** | 3.5 – 4.4 |
+| **Needs improvement (需改进)** | < 3.5 |
+
+---
+
+## 报告模板
+
+```md
+# TRACE Evaluation Report
+
+Target: `<path>`
+
+## Overall Assessment
+
+**Overall Score: X.X / 5**
+**Overall Rating: Excellent (优秀) / Good (良好) / Needs improvement (需改进)**
+
+One-sentence conclusion: ...（自然中文，具体不空洞）
+
+## TRACE Dimension Explanation
+
+SkillHub TRACE 评测体系从**可信任度、可靠性、适用性、规范性、有效性**五个维度全面评估。
+[了解详情](https://skillhub.cn/tutorials#trace-evaluation)
+
+评测基于 AI 自动化检测，结果供参考。
+
+## Evaluation Details
+
+### T · Trust — X.X / 5
+（1-2 句中文）
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 安全性扫描 | X.X | 一句话证据 |
+| 国内适配性 | X.X | ... |
+| 边界透明度 | X.X | ... |
+| 数据隐私规范 | X.X | ... |
+
+### R · Reliability — X.X / 5
+（中文评语）
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 异常处理 | X.X | ... |
+| 功能完善性 | X.X | ... |
+| 运行稳定性 | X.X | ... |
+| 降级兜底 | X.X | ... |
+
+### A · Adaptability — X.X / 5
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 能力边界定义 | X.X | ... |
+| 触发方式 | X.X | ... |
+| 受众广度 | X.X | ... |
+| 定制化支持 | X.X | ... |
+
+### C · Convention — X.X / 5
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 文档质量 | X.X | ... |
+| 渐进式披露 | X.X | ... |
+| 结构清晰 | X.X | ... |
+| 反模式与FAQ | X.X | ... |
+
+### E · Effectiveness — X.X / 5
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 输出准确性 | X.X | ... |
+| 内容完整度 | X.X | ... |
+| 创造力与增值 | X.X | ... |
+| 开箱即用度 | X.X | ... |
+
+## Improvement Suggestions (prioritized)
+
+1. ...（具体、可行动）
+2. ...
+3. ...
+```
+
+### 评语规范
+
+- **dimension-level**：1-2 句自然中文，抓住核心。✅ "纯文档型零风险，全中文专为即梦打造。边界清晰但未声明数据隐私" ❌ "整体表现良好"
+- **sub-item**：一句话引用证据。✅ "Gotchas 13 条+checklist，但缺交互式引导模板" ❌ "安全方面没问题"
+
+**各维度建议措辞：**
+
+| 维度 | 正面措辞示例 | 负面措辞示例 |
+|------|------------|------------|
+| **T** | 未发现敏感信息硬编码；安全声明完整 | 发现疑似凭据模式需移除；缺少数据边界说明 |
+| **R** | 异常输入有自检与提示；失败路径处理清晰 | 对异常输入缺少自检提示；缺少降级兜底策略 |
+| **A** | 明确了不适用边界因此不易误用；有 near-miss 防范 | 描述过泛导致误触发；与相邻技能能力边界冲突 |
+| **C** | 结构遵循快速上手→流程→示例且细节下沉 references/ | 内容堆在 SKILL.md 缺索引/目录；示例不可复制 |
+| **E** | 示例覆盖主流场景拿来就能用；能显著减少返工 | 高级场景指导不足；只能完成浅层输出 |
+
+---
+
+## 受众说明
+
+| 用户类型 | 使用方式 |
+|---------|---------|
+| **Skill 评测者** | 对社区或平台上的 Skill 做第三方质量评估，输出标准化报告 |
+| **平台审核员** | 使用本标准作为统一评审框架，确保审核口径一致 |
+| **Skill 作者自查** | 发布前自检，定位短板并针对性修改 |
+| **社区用户** | 选 Skill 前快速了解质量，或对比多个同类型 Skill |
+
+---
+
+## 常见问题 FAQ
+
+**Q1：脚本基分和 AI 校准分不一致，以哪个为准？**
+最终报告中的分数 = 基分 ± AI 语义校准。校准只允许 ±0.3，所以两者不会差太远。如果差幅超过 0.3，说明该子项的满分标准描述模糊，建议对照 [scoring-criteria.md](references/scoring-criteria.md) 中该子项的"4.5 vs 5.0 比对"案例找到客观标准。
+
+**Q2：我只改了 Skill 的几行文字，需要重新做 TRACE 吗？**
+修改了功能说明、FAQ、边界条件、触发词等影响使用体验的内容 → 需要重新评测。只修正了错别字或格式 → 不需要。
+
+**Q3：TRACE 评测结果是 AI 自动打的还是人工打的？**
+脚本计算确定性基分（结构检测），AI 阅读正文后做语义校准（±0.3），最终由 AI 综合输出。具有一致性但不保证与 SkillHub 官方评测结果完全一致——官方还涉及用户行为数据维度。
+
+**Q4：某个子项反复评测还是不给满分，怎么办？**
+对照 [references/scoring-criteria.md](references/scoring-criteria.md) 中该子项的"满分标准"和"4.5 vs 5.0 对比"案例。对比案例展示了刚好 5.0 的具体格式要求，找到差距后针对性修改文件。
+
+**Q5：references/ 下的文件不存在，该子项怎么评分？**
+不存在 = 该标准未满足 = 脚本基分最多给 4.0。必须创建对应文件并填充实质内容，AI 校准后才可能达到 5.0。
+
+**Q6：我可以只检查某一个维度吗？**
+可以。触发时明确说明"只检查 E·有效性"或"只看 C 维度"，评测会聚焦该维度打分并给出改进建议。深度 FAQ（第 7-15 题）见 [references/trace-faq-deep.md](references/trace-faq-deep.md)。
+
+---
+
+## 禁忌清单
+
+| 行为 | 原因 |
+|------|------|
+| 无论据就调基分（纯为凑数） | 校准必须有语义信号支撑 |
+| 无 evidence 就说"表现良好" | 每分必须有可引用证据 |
+| CLI 和 Prompt 型用同一标准 | 必须应用类型感知 |
+| FAQ 充数判满分 | 读内容判断实质价值 |
+| 忽视去重信号 | `ref_names` 前缀 ≥3 必须降档 |
+
+---
+
+## TRACE 评测体系（原文）
+
+> 以下内容来自腾讯科技、SkillHub 与腾讯玄武实验室于 2026 年 5 月 21 日联合发布的 TRACE 严选框架官方公告。
+
+距离 Anthropic 推出 Agent Skills 不过半年，国内 Skill 社区 SkillHub 上的 Skill 数量已进入 7 万量级。5 月 21 日，腾讯科技、SkillHub 与腾讯玄武实验室联合发布 TRACE —— **国内首个面向 Skill 真实使用场景的严选评测体系**。
+
+**T（Trust，安全可信）** — 红线维度。**R（Reliability，运行可靠）** — 稳定性、可复现性和交付可靠性。**A（Adaptability，场景适用）** — Agent 能否自然识别并加载目标 Skill。**C（Convention，结构规范）** — 不是判断写得是否漂亮，而是具备被理解运行评测复用和维护的基础。**E（Effectiveness，效果增益）** — 结果必须明显优于 no-skill 参照组，且改善值得付出代价。
+
+TRACE 是质量观测坐标系，采用"热度信号 + 时间切片 + 系统评测 + 编辑精选"的严选机制，不追求全量评分排名。
+
+---
+
+## References
+
+- [SkillHub TRACE Evaluation System](https://skillhub.cn/tutorials#trace-evaluation)
+- [references/scoring-criteria.md](references/scoring-criteria.md) — 20 子项满分标准 + 扣分原因 + 修改对比 + 五维度速查（含原 trace-criteria-detail、trace-rubric 内容）
+- [references/calibration-guide.md](references/calibration-guide.md) — 校准规则 + 反模式案例 + 调幅指南
+- [references/trace-anti-patterns.md](references/trace-anti-patterns.md) — Skill 创作者自检反模式案例集（来源：skill-trace-checker/东四联周博远）
+- [references/trace-skill-checklist.md](references/trace-skill-checklist.md) — 一页纸自检清单（scoring-criteria 浓缩版）（来源：skill-trace-checker/东四联周博远）
+- [references/trace-sample-reports.md](references/trace-sample-reports.md) — 真实评分报告案例集（来源：skill-trace-checker/东四联周博远）
+- [references/trace-faq-deep.md](references/trace-faq-deep.md) — TRACE 深度 FAQ（来源：skill-trace-checker/东四联周博远）
+- [examples/trace-report.generated.md](examples/trace-report.generated.md) — 真实评测输出样例（Markdown）
+- [examples/trace-report.generated.html](examples/trace-report.generated.html) — 真实评测输出样例（HTML 雷达图）
+
+---
+
+## Keywords
+
+**English:** trace-evaluation, trace-scoring, trace-report, skill-quality, five-dimension-evaluation
+
+**中文：** TRACE 评测, TRACE 评分, TRACE 报告, 五维度评估, T/R/A/C/E 评估, 技能质量评测, Trace 严选, 严格评测, 快速检查

skills/base-skills/skill-trace-evaluation/examples/trace-report.generated.html

@@ -0,0 +1,270 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <script src="https://cdn.tailwindcss.com"></script>
+  <title>TRACE 评测报告 — {SKILL_NAME}</title>
+<style>
+  @media print { body { background: white !important; } .no-print { display: none !important; } }
+</style>
+</head>
+<body class="bg-gray-50">
+<div class="pb-8 max-w-5xl mx-auto px-4 pt-6">
+
+  <!-- ====== Header ====== -->
+  <div class="mb-6 flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3">
+    <div>
+      <h1 class="text-2xl font-bold text-gray-900">{SKILL_NAME}</h1>
+      <p class="text-sm text-gray-500 mt-0.5">{SKILL_PATH}</p>
+    </div>
+    <div class="flex items-center gap-2 text-xs text-gray-400">
+      <span>评测时间：{TIMESTAMP}</span>
+      <span class="px-2 py-0.5 rounded bg-green-50 text-green-700 font-medium">Official: Pass</span>
+    </div>
+  </div>
+
+  <!-- ====== TRACE 维度说明卡 ====== -->
+  <div class="mb-6 rounded-2xl overflow-hidden border" style="border-color:rgba(63,94,255,0.16)">
+    <div class="h-1" style="background:linear-gradient(90deg,#3f5eff 0%,#af52de 100%)"></div>
+    <div class="p-5" style="background:linear-gradient(135deg,rgba(63,94,255,0.04) 0%,rgba(175,82,222,0.04) 100%)">
+      <div class="flex items-start gap-3">
+        <div class="w-9 h-9 rounded-xl bg-gradient-to-br from-blue-500 to-purple-600 flex items-center justify-center flex-shrink-0 mt-0.5 shadow-sm">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-[18px] h-[18px] text-white"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
+        </div>
+        <div>
+          <h3 class="text-[15px] font-semibold text-gray-900 mb-1.5">TRACE 评测维度说明</h3>
+          <p class="text-[13px] leading-relaxed text-gray-600">
+            SkillHub TRACE 评测体系从 <span class="font-medium text-gray-800">可信任度（Trust）</span>、<span class="font-medium text-gray-800">可靠性（Reliability）</span>、<span class="font-medium text-gray-800">适用性（Adaptability）</span>、<span class="font-medium text-gray-800">规范性（Convention）</span>、<span class="font-medium text-gray-800">有效性（Effectiveness）</span> 五个维度全面评估 Skill 的质量。该体系基于 SkillHub 平台的长期运营实践及腾讯新闻团队的内容生产经验沉淀而成，旨在帮助用户快速识别高质量 Skill。
+          </p>
+          <p class="text-[12px] text-gray-500 mt-2 flex items-center gap-1">
+            <span class="inline-block w-1.5 h-1.5 rounded-full bg-amber-400"></span>
+            特别说明：本报告不是官方报告，而是 TRACE 评测体系的模拟检测，最终测评结果以 SkillHub 为准。
+          </p>
+          <p class="text-[12px] text-gray-400 mt-1">
+            等级阈值：≥4.7 优秀（Excellent） | ≥4.2 良好（Good） | ≥3.5 一般（Fair） | &lt;3.5 待改进（Needs improvement）
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- ====== Overall Score + Radar ====== -->
+  <div class="mb-6 p-6 rounded-2xl bg-white border border-gray-100 shadow-sm">
+    <div class="flex flex-col lg:flex-row items-center gap-8">
+      <!-- SVG Radar -->
+      <div class="w-full lg:w-[320px] h-[260px] flex-shrink-0">
+        <svg width="320" height="260" viewBox="0 0 320 260">
+          <!-- 五轴骨架线 -->
+          <line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="160" y2="40"/>
+          <line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="245.595" y2="102.188"/>
+          <line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="212.901" y2="202.812"/>
+          <line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="107.099" y2="202.812"/>
+          <line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="74.405" y2="102.188"/>
+          <!-- 5层同心五边形网格 (20%/40%/60%/80%/100%) -->
+          {RADAR_GRID}
+          <!-- 轴标签 -->
+          <text font-size="12" text-anchor="middle" fill="#4B5563" x="160" y="28">T 可信任度</text>
+          <text font-size="12" text-anchor="start" fill="#4B5563" x="257" y="98">R 可靠性</text>
+          <text font-size="12" text-anchor="start" fill="#4B5563" x="220" y="213">A 适用性</text>
+          <text font-size="12" text-anchor="end" fill="#4B5563" x="100" y="213">C 规范性</text>
+          <text font-size="12" text-anchor="end" fill="#4B5563" x="63" y="98">E 有效性</text>
+          <!-- 数据多边形 (T=pct_T, R=pct_R, A=pct_A, C=pct_C, E=pct_E) -->
+          <!-- 各轴坐标公式：T轴=(160, 130-(pct_T*90)), R轴=(160+(pct_R*85.595), 130-(pct_R*27.812)), A轴=(160+(pct_A*52.901), 130+(pct_A*72.812)), C轴=(160-(pct_C*52.901), 130+(pct_C*72.812)), E轴=(160-(pct_E*85.595), 130-(pct_E*27.812)) -->
+          {RADAR_POLYGON}
+          {RADAR_POINTS}
+        </svg>
+      </div>
+      <div class="flex-1 min-w-0">
+        <div class="flex items-baseline gap-3 mb-4">
+          <span class="text-[48px] font-bold text-gray-900 leading-none">{OVERALL}</span>
+          <span class="text-[16px] text-gray-400 font-medium">/ 5</span>
+        </div>
+        <div class="mb-3">
+          <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-[13px] font-semibold {OVERALL_BADGE_CLASS}">{OVERALL_GRADE}</span>
+        </div>
+        <p class="text-[14px] leading-relaxed text-gray-600">{OVERALL_SUMMARY}</p>
+        <p class="text-[13px] text-gray-500 mt-2">{OVERALL_COMPARISON}</p>
+        <div class="mt-4 grid grid-cols-5 gap-2">
+          {MINI_SCORE_CARDS}
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- ====== Dimension Detail Cards ====== -->
+  <div class="space-y-4">
+    <h3 class="text-[16px] font-semibold text-gray-900">📊 五维度详析（20 子项评分）</h3>
+
+    <!-- T · Trust -->
+    <div class="p-5 rounded-xl border border-gray-100 bg-white">
+      <div class="flex items-center gap-3 mb-3">
+        <div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(16,185,129,0.082)">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(16,185,129)"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/></svg>
+        </div>
+        <div class="flex-1">
+          <span class="text-[14px] font-semibold text-gray-900">T · Trust（可信任度）</span>
+          <span class="text-[12px] text-gray-500 ml-2">安全红线维度</span>
+          <span class="float-right text-[18px] font-bold" style="color:rgb(16,185,129)">{T_SCORE}</span>
+        </div>
+      </div>
+      <div class="flex items-center gap-3 mb-3">
+        <div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{T_PCT}%;background:linear-gradient(90deg,#10b981,#34d399)"></div></div>
+      </div>
+      <p class="text-[13px] text-gray-600 mb-2">{T_SUMMARY}</p>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[13px]">
+          <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
+          {T_ROWS}
+        </table>
+      </div>
+    </div>
+
+    <!-- R · Reliability -->
+    <div class="p-5 rounded-xl border border-gray-100 bg-white">
+      <div class="flex items-center gap-3 mb-3">
+        <div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(59,130,246,0.082)">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(59,130,246)"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/></svg>
+        </div>
+        <div class="flex-1">
+          <span class="text-[14px] font-semibold text-gray-900">R · Reliability（可靠性）</span>
+          <span class="text-[12px] text-gray-500 ml-2">稳定性与交付</span>
+          <span class="float-right text-[18px] font-bold" style="color:rgb(59,130,246)">{R_SCORE}</span>
+        </div>
+      </div>
+      <div class="flex items-center gap-3 mb-3">
+        <div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{R_PCT}%;background:linear-gradient(90deg,#3b82f6,#60a5fa)"></div></div>
+      </div>
+      <p class="text-[13px] text-gray-600 mb-2">{R_SUMMARY}</p>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[13px]">
+          <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
+          {R_ROWS}
+        </table>
+      </div>
+    </div>
+
+    <!-- A · Adaptability -->
+    <div class="p-5 rounded-xl border border-gray-100 bg-white">
+      <div class="flex items-center gap-3 mb-3">
+        <div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(245,158,11,0.082)">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(245,158,11)"><path d="m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z"/><circle cx="12" cy="12" r="10"/></svg>
+        </div>
+        <div class="flex-1">
+          <span class="text-[14px] font-semibold text-gray-900">A · Adaptability（适用性）</span>
+          <span class="text-[12px] text-gray-500 ml-2">场景识别与触发</span>
+          <span class="float-right text-[18px] font-bold" style="color:rgb(245,158,11)">{A_SCORE}</span>
+        </div>
+      </div>
+      <div class="flex items-center gap-3 mb-3">
+        <div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{A_PCT}%;background:linear-gradient(90deg,#f59e0b,#fbbf24)"></div></div>
+      </div>
+      <p class="text-[13px] text-gray-600 mb-2">{A_SUMMARY}</p>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[13px]">
+          <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
+          {A_ROWS}
+        </table>
+      </div>
+    </div>
+
+    <!-- C · Convention -->
+    <div class="p-5 rounded-xl border border-gray-100 bg-white">
+      <div class="flex items-center gap-3 mb-3">
+        <div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(139,92,246,0.082)">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(139,92,246)"><path d="M12 7v14"/><path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
+        </div>
+        <div class="flex-1">
+          <span class="text-[14px] font-semibold text-gray-900">C · Convention（规范性）</span>
+          <span class="text-[12px] text-gray-500 ml-2">结构与可维护性</span>
+          <span class="float-right text-[18px] font-bold" style="color:rgb(139,92,246)">{C_SCORE}</span>
+        </div>
+      </div>
+      <div class="flex items-center gap-3 mb-3">
+        <div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{C_PCT}%;background:linear-gradient(90deg,#8b5cf6,#c4b5fd)"></div></div>
+      </div>
+      <p class="text-[13px] text-gray-600 mb-2">{C_SUMMARY}</p>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[13px]">
+          <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
+          {C_ROWS}
+        </table>
+      </div>
+    </div>
+
+    <!-- E · Effectiveness -->
+    <div class="p-5 rounded-xl border border-gray-100 bg-white">
+      <div class="flex items-center gap-3 mb-3">
+        <div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(239,68,68,0.082)">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(239,68,68)"><path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/></svg>
+        </div>
+        <div class="flex-1">
+          <span class="text-[14px] font-semibold text-gray-900">E · Effectiveness（有效性）</span>
+          <span class="text-[12px] text-gray-500 ml-2">任务增益与代价</span>
+          <span class="float-right text-[18px] font-bold" style="color:rgb(239,68,68)">{E_SCORE}</span>
+        </div>
+      </div>
+      <div class="flex items-center gap-3 mb-3">
+        <div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{E_PCT}%;background:linear-gradient(90deg,#ef4444,#f87171)"></div></div>
+      </div>
+      <p class="text-[13px] text-gray-600 mb-2">{E_SUMMARY}</p>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[13px]">
+          <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
+          {E_ROWS}
+        </table>
+      </div>
+    </div>
+  </div>
+
+  <!-- ====== Baseline Comparison ====== -->
+  <div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
+    <h3 class="text-[15px] font-semibold text-gray-900 mb-3">📊 no-skill 基线对比</h3>
+    <div class="overflow-x-auto">
+      <table class="w-full text-[13px]">
+        <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">对比维度</th><th class="p-2">no-skill（裸模型）</th><th class="p-2">启用此 skill</th><th class="p-2 w-16">增益</th></tr>
+        {BASELINE_ROWS}
+      </table>
+    </div>
+  </div>
+
+  <!-- ====== Official Compliance ====== -->
+  <div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
+    <h3 class="text-[15px] font-semibold text-gray-900 mb-3">📋 官方规范合规（agentskills.io）</h3>
+    <div class="rounded-lg p-3 mb-3" style="background:rgba(16,185,129,0.06);border-left:3px solid rgb(16,185,129)">
+      <span class="text-[14px] font-semibold" style="color:rgb(16,185,129)">✅ {OFFICIAL_OVERALL}</span>
+      <span class="text-[12px] text-gray-500 ml-2">基于 agentskills.io 官方规范</span>
+    </div>
+    <div class="overflow-x-auto">
+      <table class="w-full text-[13px]">
+        <tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2 w-8">#</th><th class="text-left p-2">检查项</th><th class="p-2 w-16">结果</th><th class="text-left p-2">证据</th></tr>
+        {OFFICIAL_ROWS}
+      </table>
+    </div>
+  </div>
+
+  <!-- ====== Suggestions ====== -->
+  <div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
+    <h3 class="text-[15px] font-semibold text-gray-900 mb-3">💡 优化建议（优先级排序）</h3>
+    <div class="space-y-2">
+      {SUGGESTION_ITEMS}
+    </div>
+  </div>
+
+  <!-- ====== Skill Profile ====== -->
+  <div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
+    <h3 class="text-[15px] font-semibold text-gray-900 mb-3">📦 Skill 基础画像</h3>
+    <div class="grid grid-cols-2 sm:grid-cols-4 gap-3 text-[13px]">
+      {PROFILE_ITEMS}
+    </div>
+  </div>
+
+  <!-- ====== Footer ====== -->
+  <div class="mt-6 text-center text-[12px] text-gray-400 pb-4">
+    <p>评估依据：<strong>SkillHub TRACE 评测体系</strong></p>
+    <p>合规检查：<strong>agentskills.io</strong> 官方规范 · Generated {TIMESTAMP}</p>
+  </div>
+
+</div>
+</body>
+</html>

skills/base-skills/skill-trace-evaluation/examples/trace-report.generated.md

@@ -0,0 +1,184 @@
+# TRACE 评测报告
+
+> 评估目标：`{SKILL_PATH}` | 评估时间：{TIMESTAMP}
+> 评估依据：SkillHub TRACE 评测体系
+> 
+> 特别说明：本报告不是官方报告，而是 TRACE 评测体系的模拟检测，最终测评结果以 SkillHub 为准。
+
+---
+
+## 📊 综合评分
+
+| 维度 | 得分 | 等级 |
+|------|:----:|:----:|
+| **T** · Trust（可信任度） | {T_SCORE} | {T_GRADE} |
+| **R** · Reliability（可靠性） | {R_SCORE} | {R_GRADE} |
+| **A** · Adaptability（适用性） | {A_SCORE} | {A_GRADE} |
+| **C** · Convention（规范性） | {C_SCORE} | {C_GRADE} |
+| **E** · Effectiveness（有效性） | {E_SCORE} | {E_GRADE} |
+| **综合** | **{OVERALL}** | **{OVERALL_GRADE}** |
+
+> 等级阈值：≥4.7 优秀（Excellent） | ≥4.2 良好（Good） | ≥3.5 一般（Fair） | <3.5 待改进（Needs improvement）
+
+---
+
+## 一句结语
+
+{ONE_SENTENCE}
+
+---
+
+## 🛡️ T · Trust（可信任度）— {T_SCORE} / 5.0
+
+> 衡量 Skill 在安全、合规和可控性方面是否可信，是整个评估体系中的**红线维度**。
+
+| 子项 | 得分 | 关键证据 | 风险/建议 |
+|------|:----:|------|------|
+| **T1 安全性扫描** | {T1} | {T1_EVIDENCE} | {T1_RISK} |
+| **T2 国内适配性** | {T2} | {T2_EVIDENCE} | {T2_RISK} |
+| **T3 边界/权限控制** | {T3} | {T3_EVIDENCE} | {T3_RISK} |
+| **T4 安全声明** | {T4} | {T4_EVIDENCE} | {T4_RISK} |
+
+### T 维总结
+
+| 亮点 | 待改进 |
+|------|--------|
+| {T_STRENGTH} | {T_WEAKNESS} |
+
+---
+
+## 🔄 R · Reliability（可靠性）— {R_SCORE} / 5.0
+
+> 衡量 Skill 在评测运行中的**稳定性、可复现性和交付可靠性**。
+
+| 子项 | 得分 | 关键证据 | 风险/建议 |
+|------|:----:|------|------|
+| **R1 异常处理** | {R1} | {R1_EVIDENCE} | {R1_RISK} |
+| **R2 可运行性** | {R2} | {R2_EVIDENCE} | {R2_RISK} |
+| **R3 交付物完整性** | {R3} | {R3_EVIDENCE} | {R3_RISK} |
+| **R4 降级处理** | {R4} | {R4_EVIDENCE} | {R4_RISK} |
+
+### R 维总结
+
+| 亮点 | 待改进 |
+|------|--------|
+| {R_STRENGTH} | {R_WEAKNESS} |
+
+---
+
+## 🎯 A · Adaptability（适用性）— {A_SCORE} / 5.0
+
+> 衡量 Skill 是否适合其声明的使用场景，以及在真实候选环境中是否容易被**正确识别和调用**。
+
+| 子项 | 得分 | 关键证据 | 风险/建议 |
+|------|:----:|------|------|
+| **A1 边界清晰度** | {A1} | {A1_EVIDENCE} | {A1_RISK} |
+| **A2 Description 触发质量** | {A2} | {A2_EVIDENCE} | {A2_RISK} |
+| **A3 国内适用性** | {A3} | {A3_EVIDENCE} | {A3_RISK} |
+| **A4 场景覆盖广度** | {A4} | {A4_EVIDENCE} | {A4_RISK} |
+
+### A 维总结
+
+| 亮点 | 待改进 |
+|------|--------|
+| {A_STRENGTH} | {A_WEAKNESS} |
+
+---
+
+## 📐 C · Convention（规范性）— {C_SCORE} / 5.0
+
+> 衡量 Skill 是否具备清晰、可维护、可复用的**结构基础**。
+
+| 子项 | 得分 | 关键证据 | 风险/建议 |
+|------|:----:|------|------|
+| **C1 用途/适用说明** | {C1} | {C1_EVIDENCE} | {C1_RISK} |
+| **C2 渐进披露** | {C2} | {C2_EVIDENCE} | {C2_RISK} |
+| **C3 元信息结构** | {C3} | {C3_EVIDENCE} | {C3_RISK} |
+| **C4 Gotchas 与指令规范** | {C4} | {C4_EVIDENCE} | {C4_RISK} |
+
+### C 维总结
+
+| 亮点 | 待改进 |
+|------|--------|
+| {C_STRENGTH} | {C_WEAKNESS} |
+
+---
+
+## ⚡ E · Effectiveness（有效性）— {E_SCORE} / 5.0
+
+> 衡量 Skill 是否**真正提升任务结果**，以及这种提升是否值得付出相应代价。
+
+| 子项 | 得分 | 关键证据 | 风险/建议 |
+|------|:----:|------|------|
+| **E1 任务完成度** | {E1} | {E1_EVIDENCE} | {E1_RISK} |
+| **E2 正确性/权威性** | {E2} | {E2_EVIDENCE} | {E2_RISK} |
+| **E3 交付物质量** | {E3} | {E3_EVIDENCE} | {E3_RISK} |
+| **E4 增益归因** | {E4} | {E4_EVIDENCE} | {E4_RISK} |
+
+### E 维总结
+
+| 亮点 | 待改进 |
+|------|--------|
+| {E_STRENGTH} | {E_WEAKNESS} |
+
+---
+
+## 📊 no-skill 基线对比
+
+| 对比维度 | no-skill（裸模型） | 启用此 skill | 增益 |
+|----------|:---:|:---:|:---:|
+| 概念准确性 | {BASELINE_ACCURACY} | {SKILL_ACCURACY} | {GAIN_ACCURACY} |
+| 适用场景判断 | {BASELINE_FIT} | {SKILL_FIT} | {GAIN_FIT} |
+| 反模式/错误检测 | {BASELINE_AP} | {SKILL_AP} | {GAIN_AP} |
+| 知识可追溯性 | {BASELINE_TRACE} | {SKILL_TRACE} | {GAIN_TRACE} |
+| Token 成本 | 0 | ~{TOKEN_COST} tokens | {COST_LEVEL} |
+
+---
+
+## 📋 官方规范合规（agentskills.io）
+
+| # | 检查项 | 结果 | 证据 |
+|---|--------|:----:|------|
+| 1 | SKILL.md 存在 | ✅/❌ | {OFFICIAL_O1} |
+| 2 | Name 与目录名一致 | ✅/❌ | {OFFICIAL_O2} |
+| 3 | Name 格式有效（kebab-case） | ✅/❌ | {OFFICIAL_O3} |
+| 4 | Description 有效（1-1024 chars） | ✅/❌ | {OFFICIAL_O4} |
+| 5 | License 字段 | ✅/⚠️/❌ | {OFFICIAL_O5} |
+| 6 | 目录结构规范 | ✅/⚠️ | {OFFICIAL_O6} |
+| 7 | 渐进式披露质量 | ✅/⚠️ | {OFFICIAL_O7} |
+| 8 | Description 触发质量 | ✅/⚠️ | {OFFICIAL_O8} |
+| 9 | 脚本安全性 | ✅/⚠️/N/A | {OFFICIAL_O9} |
+| 10 | 密钥/敏感信息扫描 | ✅/❌ | {OFFICIAL_O10} |
+
+---
+
+## 💡 优化建议（优先级排序）
+
+| 优先级 | 维度 | 建议 |
+|:--:|------|------|
+| P1 | {P1_DIM} | {P1_SUGGESTION} |
+| P2 | {P2_DIM} | {P2_SUGGESTION} |
+| P3 | {P3_DIM} | {P3_SUGGESTION} |
+
+---
+
+## 📦 Skill 基础画像
+
+| 指标 | 值 |
+|------|-----|
+| 路径 | {SKILL_PATH} |
+| SKILL.md | {BODY_LINES} lines · {BODY_CHARS} chars |
+| References | {REF_COUNT} files · {REF_SUBDIRS} subdirs |
+| Examples | {EX_COUNT} files |
+| Scripts | {SCRIPT_COUNT} files |
+| License | {LICENSE} |
+| Secrets | {SECRETS_DETECTED} |
+| Gotchas | {GOTCHAS_COUNT} domain-specific |
+| 中文化 | {CHINESE_STATUS} |
+| Skill Type | {SKILL_TYPE} |
+
+---
+
+> 评估依据 **SkillHub TRACE 评测体系**
+> 官方规范合规检查基于 **agentskills.io** 标准
+> Generated {TIMESTAMP} · {SKILL_NAME}

skills/base-skills/skill-trace-evaluation/references/calibration-guide.md

@@ -0,0 +1,104 @@
+# TRACE 校准规则与反模式案例
+
+本文档定义从基分到最终分的校准规则，以及 AI 评分时最常见的错误模式。
+
+---
+
+## 校准规则
+
+规则按优先级排列。1-3 是必须执行的，4-6 是条件触发的。
+
+### 规则 1：仅在有语义信号时调整
+
+读完正文后再判断是否调整基分。如果脚本计算的基分已准确反映内容质量，**不要为"凑到某个数"而调整**。
+
+**判断方法：** 对照 `scoring-criteria.md` 中该子项的"满分标准 + 扣分原因"。正文中能看到扣分模式 → 下调。正文中能看到上调信号 → 上调。都看不到 → 保持基分。
+
+### 规则 2：调幅范围 ±0.3
+
+单子项最多上调 0.3 或下调 0.3。不能把 4.5 跳到 5.0（最大 4.8）或 3.5 跳到 3.2（最小 3.2）。
+
+### 规则 3：附调整理由
+
+每个校准必须附一句中文理由，引用文件中的具体内容。格式：`"正文 xxx.md 中[具体内容]→ 调整 ±x.x"`
+
+### 规则 4：去重降档
+
+`directory.ref_names` 存在 ≥ 3 个同版本前缀文件（如 `jimeng-3.0-prompt-guide.md`、`jimeng-3.0-vocabulary.md`、`jimeng-3.0-word-library.md`——前缀 `jimeng-3.0` 出现 3 次）→ C2、E2 基分降一档（最高 4.5）。此降档不占用 ±0.3 额度。
+
+检测方法：读取 `ref_names` 列表，对每个文件名提取版本前缀（如 `jimeng-3.0`、`seedream-5.0`），统计每个前缀的出现次数。任一前缀 ≥ 3 次即触发。
+
+### 规则 5：完美阈值缓冲
+
+同一维度所有 4 子项的最终分（基分+校准后）都可达到 5.0 时，检查以下隐性瑕疵：
+- 正文缺少某类边界说明（如纯文档型未声明数据安全 → T4 不应 5.0）
+- 资源文件虽多但部分为模板自动生成（如 `.generated.html` 类文件）
+- Gotchas 数量达标但深度不够（只列错误不解释原因 → C4 不应 5.0）
+
+任一存在 → 该维度最高 **4.8**（非 5.0）。
+
+### 规则 6：类型感知
+
+脚本已内置 CLI/Prompt/Doc 差异化到基分公式中。AI 校准时注意：
+- CLI 型技能的 C2 阈值用 150 行代替 200 行，E2 满分用 4 exs 代替 25 exs
+- Prompt 型技能期望 examples 丰富，CLI 型不需要
+- Doc 型技能 C2/E2 标准介于两者之间
+
+---
+
+## 反模式案例
+
+以下做法一律视为不合格评估：
+
+### 反模式 1：无论据就调基分
+
+```
+❌ T1 基分 4.8 → "感觉安全性不错，调到 5.0"
+   问题：没有引用任何文件中的内容，纯主观判断
+
+✅ T1 基分 4.8 + 正文 "This skill does not access user files" → "正文有明确安全声明 → +0.2 → 5.0"
+```
+
+### 反模式 2：只改报告不改 Skill
+
+评分变化必须有对应的文件改动支持。如果两次评估之间分数变化了，但 SKILL.md 没有变化，评估失败。
+
+### 反模式 3：CLI 和 Prompt 同一标准
+
+```
+❌ CLI 型只有 4 个 examples → "examples 太少，E2 给 3.5"
+   问题：CLI 型 4 个 exs 覆盖所有子命令已满分
+
+✅ CLI 型 4 个 exs + 覆盖 4 个子命令 → E2=5.0（脚本已按 CLI 阈值计算）
+```
+
+### 反模式 4：FAQ 充数判满分
+
+```
+❌ C4 基分 4.8 → 正文有 FAQ 章节 → "FAQ 完善，不调"
+   实际：FAQ 内容 "Q: 怎么使用？A: 按说明使用即可" ——充数
+
+✅ C4 基分 4.8 → 读 FAQ 发现回答空洞 → "FAQ 充数，实质价值低 → -0.3 → 4.5"
+```
+
+### 反模式 5：忽视去重信号
+
+```
+❌ E2 基分 5.0 → "exs=35 完美" → 不调
+   实际：ref_names 中 jimeng-3.0-* 出现 3 次 → 内容冗余
+
+✅ E2 基分 5.0 → 检测到去重信号 → 降一档 → E2=4.5（最高）
+```
+
+---
+
+## 校准调幅指南
+
+| 信号强度 | 幅度 | 示例 |
+|---------|:---:|------|
+| 强正信号（正文有精确匹配满分标准的内容） | +0.3 | 有交互式引导模板、有三分类边界、有 ≥3 个可复制开场白 |
+| 中正信号（有方向但不够系统） | +0.2 | 有边界说明但例子偏少、有参数选择但不系统 |
+| 弱正信号（勉强可以看到相关元素） | +0.1 | 隐含了目标用户、正文偶见注意事项 |
+| 弱负信号 | -0.1 | 个别地方表述模糊 |
+| 中负信号（有明显缺口） | -0.2 | 缺少中间态边界、FAQ 偏浅 |
+| 强负信号（与满分标准直接矛盾） | -0.3 | 无任何边界说明、Gotchas 只列错误不教改对、FAQ 充数 |

skills/base-skills/skill-trace-evaluation/references/scoring-criteria.md

@@ -0,0 +1,308 @@
+# TRACE 评分细则：20 子项 ×（满分标准 + 扣分原因）
+
+本文档是 `skill-trace-evaluation` 的核心评分参考。每个子项含：满分标准（5.0 锚点）、基分公式、扣分常见原因、可上调/下调信号、修改对比（需要时）。
+
+AI 评分流程：脚本计算基分 → 阅读正文 → 对照本文档的满分标准 + 扣分原因 → 校准 ±0.3 → 终分。
+
+---
+
+## 五维度速查（高分信号 + 常见扣分）
+
+### T · Trust
+**高分信号：** 有第三方安全报告或多引擎扫描证据；最小权限原则明确；无敏感信息硬编码；脚本行为清晰无自启动。
+**常见扣分：** 出现敏感信息模式或疑似凭据；未说明权限/数据边界；依赖/脚本行为不透明；强依赖不可达的外部服务。
+
+### R · Reliability
+**高分信号：** 输入要求清晰（格式、范围、前置条件）；异常输入有自检与提示；有可重复的流程与校验步骤；不可完成时解释原因并给建议。
+**常见扣分：** 输入不符合要求时无反馈或返回空/错/幻觉；缺少失败路径处理建议。
+
+### A · Adaptability
+**高分信号：** 明确"什么时候该用/不该用"；有 near-miss 边界（易误触发的相邻任务）；提示典型坑点并给规避方式；能力边界与输出结构清晰可预期。
+**常见扣分：** 描述过泛导致误触发；能力边界不清或与相邻技能冲突。
+
+### C · Convention
+**高分信号：** 结构清晰（快速上手→流程→示例→限制→进阶）；渐进式披露合理（细节放 references/）；模板/示例充分可复制；命名一致、版本说明清楚。
+**常见扣分：** 只有大段描述无模板/示例；内容堆在 SKILL.md 缺索引/目录。
+
+### E · Effectiveness
+**高分信号：** 产出能直接用于任务；高质量示例覆盖主流场景；能显著减少返工（常见翻车点+修复）；输出完整且格式符合预期。
+**常见扣分：** 只能完成浅层输出用户仍需大量重做；高级场景缺乏可操作指导。
+
+---
+
+## T · Trust（可信任度）— 4 子项
+
+### T1 · 安全性扫描
+
+**满分标准（5.0）：** `secrets_detected=false` + `has_scripts=false`（纯文档型零风险），正文有安全声明。或 `has_scripts=true` 但每个脚本有 `--help`、非交互、无硬编码密钥、有 dry-run。
+
+**基分公式：** `4.5 + no_scripts(+0.3) + secdecl(+0.2) - secrets_detected(-1.0每项)`
+
+**扣分常见原因：**
+- 脚本报错直接抛出技术异常（ImportError / FileNotFound），不是用户语言
+- 声称能访问用户平台账号后台数据（P0 红线）
+- 引导用户分享账号密码（P0 红线）
+- `has_scripts=true` 但正文无任何安全考量
+
+**可上调（+0.2~0.3）：** 有第三方安全报告或多引擎扫描证据。
+
+**可下调（-0.2~0.3）：** 脚本有交互式输入（`input()` / `read -p`），或依赖不透明。
+
+---
+
+### T2 · 国内适配性
+
+**满分标准（5.0）：** `has_chinese=true`，正文全中文，示例基于国内真实平台（微信/淘宝/小红书/飞书），专有名词用国内习惯叫法（"公众号"而非"WeChat Official Account"）。
+
+**基分公式：** `has_chinese ? 5.0 : 2.0`
+
+**扣分常见原因：** 示例混有英文平台（Slack/Twitter），触发词只有英文。
+
+**修改对比：**
+```
+❌ "Write a Twitter thread about..."
+✅ "写一组微博/小红书/公众号推文..."
+```
+
+---
+
+### T3 · 边界透明度
+
+**满分标准（5.0）：** 有独立边界章节，明确三类（✅能做 / ⚠️需条件 / ❌超范围），每类 ≥ 3 个具体例子。
+
+**基分公式：** `boundary ? 4.5+0.3(when_to_use) : 3.0`
+
+**扣分常见原因：** 边界只有一句话（"适用：Skill 质量检查。不适用：普通聊天"），无"需要条件"中间态。
+
+**4.5 vs 5.0 比对：**
+```
+4.5（边界存在但弱）："适用场景：Skill 质量检查。不适用：普通聊天。"
+
+5.0（三分类 + 每类 3 例）：
+### ✅ 擅长处理
+1. 检查新创建的 Skill：逐维度打分
+2. 定位具体扣分原因：哪个子项、怎么改
+3. 验证修改效果：重新打分确认提升
+### ⚠️ 需要素材
+1. 完整自检需要 SKILL.md 路径
+2. 针对性建议需描述使用场景
+### ❌ 超出范围（附替代方案）
+1. 帮你写 Skill 内容 → 用 skill-creator
+2. 评测非 Skill 文档 → 用对应工具
+3. 自动发布 → 手动完成
+```
+
+---
+
+### T4 · 数据隐私规范
+
+**满分标准（5.0）：** 纯文档型自动 4.5。若正文/FAQ 明确声明"不收集/不处理用户数据" → 5.0。若涉及文件读写/API 调用 → 需说明处理方式。
+
+**基分公式：** `4.5 + secdecl(+0.5) - has_scripts(-0.2)`
+
+**扣分常见原因：** 涉及文件上传/外部 API 但无隐私声明。
+
+---
+
+## R · Reliability（可靠性）— 4 子项
+
+### R1 · 异常处理
+
+**满分标准（5.0）：** 有 Gotchas/FAQ + **交互式引导模板**："信息不足时先给假设版本 + 列具体缺少什么"，明确禁止笼统提示（"请提供更多信息"）。
+
+**基分公式：** `gotchas ? 4.0+0.5(validation) : 3.0`
+
+**扣分常见原因：** 有 Gotchas 但只列错误不教怎么改对——这与官方评语精确对应：官方对 `jimeng-prompt-text2video` 的 R1 评语"写错了主要靠对照长长的规则表排查，对新手不太友好"就是典型扣分模式。
+
+**修改对比：**
+```
+❌ "请提供更多关于您产品的信息"
+✅ "先给你一个示例版本，如果要精准化，需要补充：
+   1. 产品核心卖点（天然原料/香味/适合肤质）
+   2. 定价区间（影响文案档次定位）
+   3. 目标买家（文案完全不同）"
+```
+
+**可上调（+0.2~0.3）：** Gotchas 含交互式引导模板。
+
+**可下调（-0.2~0.3）：** Gotchas 只列错误不教改对，或 FAQ 充数。
+
+---
+
+### R2 · 功能完善性
+
+**满分标准（5.0）：** `has_workflow_steps=true`（CLI 型 `cli_sections >= 3`），场景覆盖无死角，每个声明的功能都有对应 example。
+
+**基分公式：** `WF ? 4.5+0.3(steps≥5 或 exs≥10) : (cli_secs≥3 ? 4.0 : 3.5)`
+
+**扣分常见原因：** 有流程但场景覆盖有缺口，或 CLI 型流程在代码块内非标题格式。
+
+---
+
+### R3 · 运行稳定性
+
+**满分标准（5.0）：** `has_gotchas=true` 或 `has_rules=true`，且有校验清单或 plan-validate-execute 循环，输出可重复稳定。
+
+**基分公式：** `4.0 + (gotchas 或 rules ? +0.3) + (validation ? +0.2)`
+
+**扣分常见原因：** 无约束规则，完全依赖模型自由发挥；指令矛盾或模糊。
+
+---
+
+### R4 · 降级兜底
+
+**满分标准（5.0）：** 超出范围时给出替代工具引导 + 输入模糊时先给假设版本再反问 + 多任务时按优先级排序。
+
+**基分公式：** `boundary ? 4.5 : 3.5`
+
+**扣分常见原因：** 能识别超出范围但只说了"不支持"，无替代方案。超出范围时产生幻觉。
+
+---
+
+## A · Adaptability（适用性）— 4 子项
+
+### A1 · 能力边界定义
+
+**满分标准（5.0）：** `has_boundary=true` + `has_when_to_use=true`，有场景化判断逻辑（"什么时候该用/不该用/模糊情况怎么判"）。
+
+**基分公式：** `boundary+when_to_use ? 4.5 : 4.0`
+
+**扣分常见原因：** 只有一句话声明，无场景化判断逻辑。
+
+---
+
+### A2 · 触发方式
+
+**满分标准（5.0）：** `description_length >= 100`，使用用户意图语言，每个功能有精确触发条件（场景化路由，非关键词堆砌）。
+
+**基分公式：** `desc≥100 ? 5.0 : (desc≥50 ? 4.5 : 3.5)`
+
+**扣分常见原因：** 只有关键词列表无场景路由。
+
+**4.5 vs 5.0 比对：**
+```
+4.5（关键词堆砌）："关键词：文章、脚本、文案、月刊、播客"
+
+5.0（场景化路由）：
+"需要创作文字类内容（文章/脚本/文案）→ 直接触发内容创作模块
+ 需要排期或策划 → 触发内容策划子模块
+ 需要多平台适配 → 触发多平台适配子模块"
+```
+
+---
+
+### A3 · 受众广度
+
+**满分标准（5.0）：** 明确说明适用用户类型 + 非主要用户使用指引，或提供不同经验级别的使用路径。
+
+**基分公式：** `4.0 + chinese(+0.3)`
+
+**扣分常见原因：** 隐含目标用户但未明确说明，专业术语和基础概念混杂。
+
+---
+
+### A4 · 定制化支持
+
+**满分标准（5.0）：** 提供用户传递偏好的机制（风格卡片/场景参数/配置文件）。CLI 型天然有参数定制 = 5.0。Prompt 型有风格/场景选择。
+
+**基分公式：** `type=cli 或 exs≥10 ? 4.5 : 4.0`
+
+**扣分常见原因：** 输出完全固定，用户只能按预设路径使用。
+
+---
+
+## C · Convention（规范性）— 4 子项
+
+### C1 · 文档质量
+
+**满分标准（5.0）：** `examples_files >= 10`（CLI 型 >= 4），示例可直接复制使用，格式规范。
+
+**基分公式：** `exs≥阈值(cli=4/prompt=10) ? 5.0 : (exs≥3 ? 4.5 : 3.5)`
+
+**扣分常见原因：** 示例需要额外解释才能使用，格式不规范。
+
+---
+
+### C2 · 渐进式披露
+
+**满分标准（5.0）：** 三层结构：第1层正文 30 秒上手 → 第2层功能详情 → 第3层 references/ 深度文档。`references_files >= 8` + `body_lines < 200`（CLI 型 < 150）。
+
+**基分公式：** `refs≥8+body<阈值 ? 5.0 : 3.0~4.5+trigger_hints(+0.2)`
+
+**检查方法：** 问自己"一个完全不了解这个 Skill 的人，看到第一屏能知道怎么开始用吗？"
+
+**扣分常见原因：** `references_files = 0` + `body_lines > 350`，全部堆在 SKILL.md 中。
+
+---
+
+### C3 · 结构清晰
+
+**满分标准（5.0）：** name 符合规范 + `references_subdirs >= 2`（如 rules/word-library/），文件名自解释，层次分明。
+
+**基分公式：** `4.5 + name_valid(+0.2) + ref_subdirs≥2(+0.3)`
+
+**扣分常见原因：** 结构混乱，文件命名不直观，或 frontmatter 缺失。
+
+---
+
+### C4 · 反模式与 FAQ
+
+**满分标准（5.0）：** Gotchas ≥ 5 条覆盖核心陷阱 + FAQ ≥ 6 题且非充数（每个答案让用户真正解决问题）。
+
+**基分公式：** `gotchas ? 4.5+0.3(gc≥5) : 3.5`
+
+**扣分常见原因：** FAQ 充数——"Q: 怎么使用？A: 按照说明使用即可"——回答和没回答一样。
+
+---
+
+## E · Effectiveness（有效性）— 4 子项
+
+### E1 · 输出准确性
+
+**满分标准（5.0）：** 不同场景的执行路径区分明确，用户不容易选错方向。有"禁止在不确定领域胡编"规则或等效约束。
+
+**基分公式：** `WF ? 4.5+0.3(validation) : 4.0`
+
+**扣分常见原因：** 场景覆盖有缺口，指导模糊或存在可验证错误。
+
+---
+
+### E2 · 内容完整度
+
+**满分标准（5.0）：** Prompt 型 `examples_files >= 25`；CLI 型 >= 4 覆盖所有子命令；Doc 型 >= 5。
+
+**基分公式：** `exs≥阈值(prompt=25/cli=4/doc=5) ? 5.0 : (exs≥10 ? 4.5 : 3.0~4.0)`
+
+**扣分常见原因：** 场景缺口明显，高级场景缺端到端示例。
+
+**内容冗余降档：** 若 `ref_names` 存在 ≥3 个同版本前缀文件 → 降一档（最高 4.5）。
+
+---
+
+### E3 · 创造力与增值
+
+**满分标准（5.0）：** 不只告诉"怎么做"——还告诉"怎么评估质量""不同方案有什么区别""哪些坑要避开""为什么这样做"。`references_subdirs >= 2` 是深度正信号。
+
+**基分公式：** `ref_subdirs≥2 ? 4.5+0.2(refs≥10) : 4.0`
+
+**扣分常见原因：** 内容较浅，仅覆盖基础操作，无超出"操作手册"的领域知识。
+
+---
+
+### E4 · 开箱即用度
+
+**满分标准（5.0）：** WF steps + validation + 有快速开始章节或 ≥ 3 个可复制开场白，用户无需阅读全文就能上手。
+
+**基分公式：** `4.0 + WF(+0.3) + val(+0.3) + gotchas(+0.2) + cli_secs≥3(+0.2)`
+
+**扣分常见原因：** 只有功能说明没有入门引导，需要读完全文才知道怎么开始。
+
+**4.5 vs 5.0 比对：**
+```
+4.5（只有功能说明）："功能列表：月刊撰写、播客脚本..."
+
+5.0（有新手30秒入门）：
+"直接把需求发过来就行。几个典型开场白：
+ '帮我写这个月的博客月刊，主题是 AI 工具盘点'
+ '有客户投诉质量问题，帮我写回复'"
+```

skills/base-skills/skill-trace-evaluation/references/trace-anti-patterns.md

@@ -0,0 +1,157 @@
+# TRACE 自检反模式案例集
+
+> **来源声明：** 本文档来源于 [skill-trace-checker](skills/base-skills/skill-trace-checker/references/anti-patterns.md) by 东四联周博远。
+
+> 本文档收录 Skill 创作者在进行 TRACE 自检时最常犯的错误模式，每类附"错误示例 ❌ → 正确示例 ✅"对比。
+> 参考本文档可避免在同一坑里反复踩。
+
+---
+
+## 反模式 1：用"美化措辞"代替实质改进
+
+这是最常见也最致命的反模式。当 AI 被要求提高 TRACE 分数时，如果只修改评分报告的描述文字，而不修改 Skill 文件本身，就是在作弊。
+
+```
+❌ 错误做法：
+评分报告显示"A-能力边界 4.5分"
+→ 修改报告措辞为"边界清晰，说明充分"
+→ 声称已提升到 5.0 分
+
+问题：SKILL.md 里实际上没有"能力边界说明"章节，只有一句话"适合 Skill 作者使用"
+
+✅ 正确做法：
+评分报告显示"A-能力边界 4.5分"
+→ 在 SKILL.md 中增加独立的"能力边界说明"章节
+→ 添加三分类（✅擅长/⚠️需素材/❌超范围），每类 ≥3 个具体例子
+→ 重新打分验证，确认真实提升
+```
+
+**判断依据：** 分数提升必须有对应的文件改动。如果只改报告，没有改任何 `.md` 文件，一律视为反模式。
+
+---
+
+## 反模式 2：FAQ 挂名充数
+
+FAQ 部分有标题但内容空洞，或者只有 2～3 题应付检查，没有真正帮到用户解答困惑。
+
+```
+❌ 错误示例（FAQ 充数）：
+## FAQ
+Q: 这个 Skill 有什么用？
+A: 帮助检查 Skill 质量。
+
+Q: 怎么使用？
+A: 按照说明使用即可。
+
+问题：
+- 没有具体操作步骤
+- 没有覆盖用户实际会遇到的问题
+- 回答和没回答一样
+
+✅ 正确示例：
+Q: 我只改了 Skill 的 FAQ，需要重新做 TRACE 吗？
+A: 要看改动性质。如果 FAQ 新增覆盖了原来没回答的边缘场景，或改正了错误信息
+   → 建议重新检查 C·规范性 维度中的"FAQ 深度"子项。
+   如果只是修正了错别字或改了措辞
+   → 可以不做，但建议记录一下修改内容以备审查。
+```
+
+**满分标准：** 主文档 ≥6 题，且每个答案能让用户真正解决问题，而非继续猜测。
+
+---
+
+## 反模式 3：能力边界描述模糊
+
+只写一句"适合 Skill 作者"或"不适用于一般用户"，没有具体说明能做什么、不能做什么。
+
+```
+❌ 错误示例（模糊边界）：
+## 适用范围
+本 Skill 适合需要检查 Skill 质量的用户，不适合普通聊天场景。
+
+问题：
+- 用户不知道哪些具体操作支持
+- 不知道遇到超范围场景该怎么办
+- "普通聊天场景"是什么？太模糊
+
+✅ 正确示例（三分类 + 具体例子）：
+## 能力边界说明
+
+### ✅ 擅长处理
+1. 检查新创建的 Skill：读取文件后逐维度打分，输出结构化评分表
+2. 定位具体扣分原因：精确指出是哪个子项、在哪个文件、怎么改
+3. 验证修改效果：修改后重新打分，确认实质性改进
+...
+
+### ❌ 超出范围（附替代方案）
+1. 帮你写 Skill 内容 → 用 skill-creator 创建 Skill
+2. 评测非 Skill 类文档 → 找代码审查工具
+...
+```
+
+---
+
+## 反模式 4：触发条件写成关键词堆砌
+
+只列一堆关键词，没有说明"什么情况下触发哪个功能"，用户自己猜。
+
+```
+❌ 错误示例（关键词堆砌）：
+触发词：TRACE, 质量检查, 评测, 自检, Skill质量, 打分, 审查
+
+问题：
+- 用户不知道"打分"和"自检"有什么区别
+- 不知道是对自己的 Skill 打分还是对别人的
+- 不知道触发后会发生什么
+
+✅ 正确示例（场景化触发判断）：
+**什么时候该用本 Skill：**
+- 刚写完 SKILL.md → 触发全量 TRACE 自检
+- 修改了 FAQ / 反模式 / 行为规范等核心内容 → 触发重新评测（只检查受影响维度）
+- 用户明确要求"检查 Skill 质量" → 触发全量检查
+- 想知道"某项扣分了怎么改" → 触发专项维度检查
+
+**不该用本 Skill 的情况：**
+- 想创作一个新 Skill → 用 skill-creator
+- 想执行某个 Skill 的功能 → 直接调用目标 Skill
+```
+
+---
+
+## 反模式 5：渐进式披露只有一层
+
+整个 SKILL.md 是一个长页面，没有分层结构，用户进来就被全量信息淹没。
+
+```
+❌ 错误结构（单层平铺）：
+# Skill 名称
+一大段介绍文字 + 全部功能说明 + 全部示例 + 全部FAQ + 所有注意事项
+→ 用户需要从头到尾读完才能开始使用
+
+✅ 正确结构（三层渐进）：
+第1层（30秒上手）：
+  - 是什么 / 什么时候用 / 3 个直接可用的触发示例
+  
+第2层（按需查阅）：
+  - 详细功能说明 + 能力边界 + 操作流程
+  
+第3层（深度参考）：
+  - references/ 目录：scoring-criteria.md, calibration-guide.md, trace-anti-patterns.md 等
+```
+
+**检查方法：** 问自己"完全陌生的用户只看第一屏，能知道怎么开始用吗？"如果答案是不能，就需要加入门章节。
+
+---
+
+## 禁忌用法清单
+
+以下做法在 TRACE 自检中**一律视为不合格**：
+
+| 禁忌行为 | 为什么不行 | 解决方案 |
+|---------|---------|---------|
+| 没有 references/ 目录 | 深度文档缺失，C·规范性 多项无法满分 | 创建目录并填充核心参考文件 |
+| FAQ 少于 6 题 | C-FAQ深度 必然扣分 | 主文档 ≥6 题 + faq-deep.md ≥8 题 |
+| 能力边界只有一句话 | A-能力边界定义 最多 4.0 | 添加三分类结构，每类 ≥3 例 |
+| 没有新手入门章节 | C-渐进式披露、E-开箱即用 双双扣分 | 在文档开头添加 30 秒入门区块 |
+| 修改报告不修改文件 | TRACE 自检的根本目的是改进 Skill 本身 | 每次评分变化都要有对应文件改动 |
+| 错误提示只说"信息不足" | R-异常处理 无法满分 | 必须指出缺少哪[N]项 + 如何补充 |

skills/base-skills/skill-trace-evaluation/references/trace-faq-deep.md

@@ -0,0 +1,113 @@
+# TRACE 深度 FAQ
+
+> **来源声明：** 本文档来源于 [skill-trace-checker](skills/base-skills/skill-trace-checker/references/faq-deep.md) by 东四联周博远。
+
+> 本文档覆盖边缘场景、工具兼容性、安全合规等主文档 FAQ 未涵盖的进阶问题。
+> 主文档 FAQ（第1-6题）已覆盖通用使用问题，本文档从第7题开始继续。
+
+---
+
+## 第 7 题：我用的是第三方 Skill 平台（不是 Skillhub），TRACE 标准还适用吗？
+
+适用，但有调整空间。TRACE 五维度（T/R/A/C/E）是通用质量框架，不依赖特定平台。  
+需注意以下差异：
+- **T-国内适配性**：如果目标用户是海外用户，可将"中文示例/国内平台"替换为对应地区的标准
+- **C-规范性**：不同平台对 references/ 文件结构的支持不同，若平台不支持多文件，可将所有内容合并在单文件中，但需标注层级
+- 其余三维度（R/A/E）标准不变
+
+---
+
+## 第 8 题：TRACE 自检通过了，但 Skillhub 官方评测还是扣分，正常吗？
+
+正常。原因有二：
+1. **官方评测包含用户行为数据**：实际用户的使用率、满意度、完成率都是评分因子，AI 自检无法模拟
+2. **官方有人工审核层**：某些标准（如是否含有违规内容、品牌语气是否符合平台调性）需人工判断
+
+建议：把 TRACE 自检作为"发布前保底检查"，官方评测作为"发布后持续改进参考"，两者互补。
+
+---
+
+## 第 9 题：Skill 里需要用到用户的真实数据（如工资、业绩），怎么满足 T-数据隐私？
+
+需要在 FAQ 或专项章节中明确说明以下内容：
+
+1. **数据去向**：用户输入的数据只用于本次会话，不会被存储或用于训练
+2. **脱敏建议**：提供示例脱敏操作，如"可以把真实金额替换为相对比例，如'A 比 B 高 30%'"
+3. **最小化原则**：说明哪些数据是必须的，哪些是可选的，让用户自主决定提供多少
+
+```
+示例说明文字（可直接放入 FAQ）：
+Q: 我需要输入真实数据吗？会不会泄露？
+A: 本 Skill 只在当前对话中使用你输入的数据，关闭对话后数据不会保留。
+   如果你处理的是敏感数据（如工资/业绩），建议使用脱敏版本：
+   - 用代号替换姓名（张三 → 员工A）
+   - 用区间替换精确数字（月薪18500 → 月薪1-2万区间）
+```
+
+---
+
+## 第 10 题：Skill 生成的内容可以商用吗？TRACE 里需要说明吗？
+
+需要在 FAQ 中明确说明，否则 T-边界透明度 会扣分。标准说明方式：
+
+```
+Q: 用这个 Skill 生成的内容可以直接商用吗？
+A: 可以。本 Skill 生成的内容版权归用户所有，可用于商业用途。
+   注意：如果生成内容中引用了特定第三方素材（如品牌名称、歌词），
+   请确认相关权利不涉及版权侵犯，本 Skill 不对引用内容的商用合规性负责。
+```
+
+---
+
+## 第 11 题：多个 Skill 协同工作时（如"地图指挥官"调用三个子 Skill），TRACE 如何评测？
+
+**评测原则：每个 Skill 独立评测，主 Skill 额外要求。**
+
+- 子 Skill：按正常 TRACE 标准各自评测
+- 主 Skill（编排/路由层）额外检查：
+  - **A-触发方式**：是否清楚说明了"什么需求路由到哪个子 Skill"
+  - **R-降级兜底**：某个子 Skill 不可用时，主 Skill 是否有降级处理策略
+  - **T-边界透明度**：用户能否清楚知道自己在和哪个子 Skill 交互
+
+---
+
+## 第 12 题：我的 Skill 只有一个很简单的功能（比如"帮我格式化代码"），也需要 references/ 目录吗？
+
+不是强制的，但要通过 TRACE，必须：
+- **如果没有 references/**：在 SKILL.md 里必须完整覆盖 FAQ ≥6 题、反模式说明、以及能力边界三分类
+- **如果有 references/**：可以将 FAQ、反模式、示例分散到子文件，SKILL.md 可以更简洁
+
+**实用建议：** 对于功能简单的 Skill，建议用"单文件扩展方案"——在 SKILL.md 底部加 `## 常见问题`、`## 注意事项`、`## 使用示例` 三个章节，代替 references/ 多文件。
+
+---
+
+## 第 13 题：references/ 文件有哪些是"必须有"，哪些是"建议有"？
+
+| 文件 | 必须 / 建议 | 缺失影响 |
+|-----|---------|---------|
+| `examples.md` | 必须（若功能复杂） | E-内容完整度、C-文档质量 扣分 |
+| `anti-patterns.md` | 必须 | C-反模式与FAQ 会扣分 |
+| `faq-deep.md` | 必须（FAQ<6题时） | C-FAQ深度 扣分 |
+| `sample-reports.md` | 建议（评测类Skill专用） | E-内容完整度 轻微扣分 |
+| `system-prompt.md` | 建议（若有复杂行为规范） | R-功能完善性 轻微扣分 |
+
+---
+
+## 第 14 题：触发词写了很多，但 AI 有时候还是没有自动调用，这影响 TRACE 评分吗？
+
+影响 A-触发方式精确度。  
+原因通常是：触发词太模糊，与其他 Skill 产生冲突。改进方法：
+- 换用"行为+对象"组合触发词，而非单个名词（"检查 Skill 质量" > "质量"）
+- 在触发词旁边加场景说明（"当用户提到...时触发"）
+- 在 SKILL.md 的触发条件章节列出典型触发句型（整句话，不只是关键词）
+
+---
+
+## 第 15 题：我对同一个 Skill 做了 3 次 TRACE，每次分数都不一样，正常吗？
+
+正常，±0.3 分属于可接受的 AI 评分波动。  
+超过 0.5 分的波动通常意味着：
+- 该子项的满分标准本身描述模糊 → 对照 `trace-criteria-detail.md` 的"5.0 vs 4.5 对比案例"，找到客观标准
+- AI 对该文件理解不一致 → 在 SKILL.md 中把该子项的满足方式写得更明确，减少解读空间
+
+**实用建议：** 分数在 4.8 及以上时，可以视为达到实用标准，不必无限追求字面上的 5.0。

skills/base-skills/skill-trace-evaluation/references/trace-sample-reports.md

@@ -0,0 +1,312 @@
+# 真实评分报告案例集
+
+> 本文档展示四种典型场景的完整评分报告，帮助用户理解"好的评测报告是什么样的"。
+> 所有报告使用与 SKILL.md [报告模板](../SKILL.md#报告模板) 一致的格式。
+
+---
+
+## 案例 A：不合格 Skill（综合 3.8 分 ❌）
+
+**Skill 概述：** 某"情绪日记助手"Skill，只有 SKILL.md 一个文件，内容约 500 字，无 references/ 目录。
+
+```md
+# TRACE Evaluation Report
+
+Target: `~/.workbuddy/skills/emotion-diary-skill`
+
+## Overall Assessment
+
+**Overall Score: 3.8 / 5**
+**Overall Rating: Good (良好)**
+
+仅500字单文件 Skill，边界、隐私、反模式、FAQ 四项核心缺失，需要大幅修改。
+
+## Evaluation Details
+
+### T · Trust — 4.0 / 5
+全中文且示例含微信场景，但专业领域无免责声明，边界和隐私均未涉及。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 安全性 | 4.5 | 无 P0/P1 风险，但未声明"不能替代心理医生" |
+| 国内适配性 | 5.0 | 全中文，示例含微信/朋友圈场景 |
+| 边界透明度 | 3.5 | 缺少三分类章节，只有一句"适合记录情绪" |
+| 数据隐私 | 3.0 | 涉及用户情绪/私密内容，完全没有隐私说明 |
+
+### R · Reliability — 4.0 / 5
+基本场景覆盖但异常处理和降级兜底不足。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 异常处理 | 4.0 | 情绪难以描述时只说"请详细说明"，无交互式引导模板 |
+| 功能完善性 | 4.5 | 基本场景覆盖，缺"情绪复盘"功能 |
+| 运行稳定性 | 4.0 | 用户说"心情不好"时直接提问，没有先给共情回应 |
+| 降级兜底 | 3.5 | 没有说明"需要专业帮助"时怎么处理 |
+
+### A · Adaptability — 3.5 / 5
+边界和受众描述严重不足。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 能力边界定义 | 3.0 | 没有边界章节 |
+| 触发方式 | 4.5 | 触发词完整，但无场景路由 |
+| 受众广度 | 3.5 | 没有说明不同用户（青少年/职场人/老年人）的使用差异 |
+| 定制化支持 | 3.0 | 没有风格定制机制 |
+
+### C · Convention — 2.9 / 5
+规范性全面缺失——无 references/、无新手入门、FAQ 仅 1 题。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 文档质量 | 4.0 | 基本分层，但无表格和模板示例 |
+| 渐进式披露 | 3.5 | 无新手入门，无 references/，单层平铺 |
+| 结构清晰 | 4.0 | 层次基本清晰，但无 references 子目录 |
+| 反模式与FAQ | 2.0 | 无反模式说明 + FAQ 只有 1 题 |
+
+### E · Effectiveness — 3.8 / 5
+功能基础但缺乏增值和入门引导。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 输出准确性 | 4.5 | 有基本准确性约束 |
+| 内容完整度 | 3.5 | 缺情绪复盘/情绪追踪等核心功能 |
+| 创造力与增值 | 3.5 | 只是记录，无任何增值特性 |
+| 开箱即用度 | 3.5 | 无新手入门，无示例 |
+
+## Improvement Suggestions
+
+1. **新增能力边界三分类章节**：✅擅长（情绪记录/每日复盘）→ ⚠️需素材（具体事件背景）→ ❌超范围（心理治疗→寻求专业帮助）
+2. **创建 references/ 目录**：至少含 anti-patterns.md + faq-deep.md，FAQ 从 1 题扩到 ≥6 题
+3. **添加隐私声明 + 心理健康免责**：声明数据只在当前会话使用，明确"不能替代心理医生"
+```
+
+---
+
+## 案例 B：修改后达标（综合 5.0 分 ✅）
+
+**背景：** 同一个 emotion-diary-skill，经过两轮修改后达标。
+
+**主要修改：**
+1. 新增 references/ 目录，创建 anti-patterns.md / faq-deep.md / examples.md
+2. 在 SKILL.md 增加"新手30秒入门"章节和能力边界三分类
+3. 系统提示词添加"心理健康声明"和"情绪不明确时先给共情版本"规则
+4. FAQ 从 1 题扩展到 8 题，faq-deep.md 覆盖 10 个边缘场景
+
+```md
+# TRACE Evaluation Report
+
+Target: `~/.workbuddy/skills/emotion-diary-skill`
+
+## Overall Assessment
+
+**Overall Score: 5.0 / 5**
+**Overall Rating: Excellent (优秀)**
+
+修改后文档体系完整，边界清晰，FAQ 深入，已全面达到 TRACE 满分标准。
+
+## Evaluation Details
+
+### T · Trust — 5.0 / 5
+全中文，国内场景适配完善，安全声明和隐私说明完整。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 安全性 | 5.0 | 新增"不能替代心理医生"免责声明，无 P0/P1 风险 |
+| 国内适配性 | 5.0 | 全中文，示例含微信/朋友圈/小红书场景 |
+| 边界透明度 | 5.0 | 三分类（✅5项/⚠️3项/❌3项）每类含替代方案 |
+| 数据隐私 | 5.0 | FAQ 明确声明"数据仅本次会话使用，关闭后不保留" |
+
+### R · Reliability — 5.0 / 5
+异常处理完善，降级兜底有替代方案引导。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 异常处理 | 5.0 | 情绪不明确时先给共情版本+列"需补充：1.具体事件 2.持续时间" |
+| 功能完善性 | 5.0 | 覆盖情绪记录/复盘/趋势分析/疏导建议四大场景 |
+| 运行稳定性 | 5.0 | plan-validate-execute 循环，输出格式说明完整 |
+| 降级兜底 | 5.0 | 超出范围时输出"建议咨询心理咨询师热线：xxx" |
+
+### A · Adaptability — 5.0 / 5
+场景化路由清晰，受众差异化指导完备。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 能力边界定义 | 5.0 | 三分类有场景化判断逻辑 |
+| 触发方式 | 5.0 | 场景化路由：情绪记录/复盘/趋势/疏导 → 各自路由 |
+| 受众广度 | 5.0 | 分青少年/职场人/老年人三种使用路径 |
+| 定制化支持 | 5.0 | 支持风格参数：轻松/严肃/简洁 |
+
+### C · Convention — 5.0 / 5
+三层渐进式披露，FAQ 深度充足。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 文档质量 | 5.0 | examples/ ≥ 10 个，可直接复制使用 |
+| 渐进式披露 | 5.0 | 30秒入门→功能详情→references/ 三层，body < 200 行 |
+| 结构清晰 | 5.0 | references/ 含 3 个子目录，命名语义清晰 |
+| 反模式与FAQ | 5.0 | Gotchas 6 条覆盖核心陷阱 + FAQ 8 题 + faq-deep.md 10 题 |
+
+### E · Effectiveness — 5.0 / 5
+增值特性丰富，开箱即用体验优秀。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 输出准确性 | 5.0 | 场景区分明确，有"禁止替代专业诊断"约束规则 |
+| 内容完整度 | 5.0 | examples 覆盖全部四大场景，有端到端示例 |
+| 创造力与增值 | 5.0 | 情绪趋势分析 + 疏导建议 + 多用户路径，3 项增值 |
+| 开箱即用度 | 5.0 | 新手入门含 3 个可复制开场白 |
+
+## Improvement Suggestions
+
+无需修改，全部 20 子项达到 5.0 ✅
+```
+
+---
+
+## 案例 C：高质量 Skill（综合 5.0 分，附亮点说明）
+
+**Skill 概述：** opc-skill（一人公司运营助手），功能完整，文档体系健全。
+
+```md
+# TRACE Evaluation Report
+
+Target: `~/.workbuddy/skills/opc-skill`
+
+## Overall Assessment
+
+**Overall Score: 5.0 / 5**
+**Overall Rating: Excellent (优秀)**
+
+文档体系健全，三分类边界清晰，异常处理有固化格式模板，FAQ 深度达 20 题。
+
+## Evaluation Details
+
+### T · Trust — 5.0 / 5
+全中文专为国内一人公司场景打造，安全声明和隐私说明完整。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 安全性 | 5.0 | 有禁止行为列表，无 P0/P1 风险，专业领域有免责声明 |
+| 国内适配性 | 5.0 | 全中文，示例基于微信/飞书/企业微信等国内平台 |
+| 边界透明度 | 5.0 | 三分类每类≥3例，超范围每项附替代方案（"SEO→专业SEO工具"） |
+| 数据隐私 | 5.0 | 声明"不存储用户数据"，提供脱敏操作指导 |
+
+### R · Reliability — 5.0 / 5
+异常处理有固化格式模板，降级兜底有替代工具引导。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 异常处理 | 5.0 | 系统提示词固化格式："缺少[N]项才能精准输出：1.xxx 2.xxx" |
+| 功能完善性 | 5.0 | 覆盖内容/运营/财务/客户四大场景，无盲区 |
+| 运行稳定性 | 5.0 | plan-validate-execute 循环，输出可重复 |
+| 降级兜底 | 5.0 | 每个超范围项都有替代工具引导 |
+
+### A · Adaptability — 5.0 / 5
+每个模块有三级路由，场景化触发精确。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 能力边界定义 | 5.0 | 场景化判断逻辑，有 near-miss 边界说明 |
+| 触发方式 | 5.0 | 三级路由：主关键词→功能分类→子功能触发 |
+| 受众广度 | 5.0 | 分个人创业者/小团队/自由职业者三种使用路径 |
+| 定制化支持 | 5.0 | 风格卡片机制（正式/口语化/极简） |
+
+### C · Convention — 5.0 / 5
+三层渐进式披露，FAQ 主文档 8 题 + faq-deep.md 12 题。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 文档质量 | 5.0 | 示例可直接复制使用，格式规范 |
+| 渐进式披露 | 5.0 | 30秒入门→功能详情→references/，body 179 行 |
+| 结构清晰 | 5.0 | references/ 含 4 个子目录，文件命名语义清晰 |
+| 反模式与FAQ | 5.0 | Gotchas 7 条 + FAQ 8 题 + faq-deep.md 12 题（覆盖隐私合规/多人协作/商用授权） |
+
+### E · Effectiveness — 5.0 / 5
+新手入门含 5 个可复制开场白，覆盖 5 个不同使用场景。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 输出准确性 | 5.0 | 禁止胡编规则 + 每个输出注明决策逻辑 |
+| 内容完整度 | 5.0 | 场景覆盖 80%+ 一人公司常见需求 |
+| 创造力与增值 | 5.0 | 风格定制 + 多平台适配 + 主动询问调整意愿，3 项增值 |
+| 开箱即用度 | 5.0 | 新手入门含 5 个可复制开场白，零学习成本 |
+
+## Improvement Suggestions
+
+无需修改，全部 20 子项达到 5.0 ✅
+```
+
+---
+
+## 案例 D：边界情况（综合 4.9 分，可接受但有已知局限）
+
+**背景：** 一个功能极简的"番茄钟提醒"Skill，功能单一，不适合建完整 references/ 体系。
+
+```md
+# TRACE Evaluation Report
+
+Target: `~/.workbuddy/skills/pomodoro-skill`
+
+## Overall Assessment
+
+**Overall Score: 4.9 / 5**
+**Overall Rating: Excellent (优秀)**
+
+功能极简但文档完整，扣分项均为功能定位导致的天然局限，非设计缺陷。
+
+## Evaluation Details
+
+### T · Trust — 5.0 / 5
+纯文档型零风险，边界和隐私说明完整。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 安全性 | 5.0 | 纯文档型，无 scripts/，无敏感操作 |
+| 国内适配性 | 5.0 | 全中文，支持口语化触发 |
+| 边界透明度 | 5.0 | 三分类（✅计时提醒/⚠️需自定义时长/❌项目管理） |
+| 数据隐私 | 5.0 | 声明"不需要任何用户数据" |
+
+### R · Reliability — 5.0 / 5
+异常处理和降级兜底到位。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 异常处理 | 5.0 | 时长未指定时默认 25 分钟，未指定休息时默认 5 分钟 |
+| 功能完善性 | 5.0 | 覆盖开始/暂停/休息/统计四大场景 |
+| 运行稳定性 | 5.0 | 有 validate-plan-execute 循环 |
+| 降级兜底 | 5.0 | 超范围时引导使用"Trello/Notion"做项目管理 |
+
+### A · Adaptability — 4.7 / 5
+受众和定制化受功能定位限制。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 能力边界定义 | 5.0 | 三分类清晰，每类 3 例 |
+| 触发方式 | 5.0 | 场景化路由 |
+| 受众广度 | 4.5 | 功能极简，团队协作场景天然不适用——非设计缺陷 |
+| 定制化支持 | 4.5 | 时长已支持参数传入，但无法做更复杂个性化——符合功能定位 |
+
+### C · Convention — 5.0 / 5
+文档结构清晰，FAQ 完整。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 文档质量 | 5.0 | 示例可直接复制使用 |
+| 渐进式披露 | 5.0 | 三层结构，body 98 行 |
+| 结构清晰 | 5.0 | 命名规范，层次分明 |
+| 反模式与FAQ | 5.0 | Gotchas 4 条（适配简洁功能）+ FAQ 6 题 |
+
+### E · Effectiveness — 4.7 / 5
+创造力和增值受功能定位限制。
+
+| Sub-item | Score | Commentary |
+|----------|-------|------------|
+| 输出准确性 | 5.0 | 有约束规则 |
+| 内容完整度 | 5.0 | 场景全覆盖 |
+| 创造力与增值 | 4.5 | 工具型 Skill，功能本身无需增值特性——非设计缺陷 |
+| 开箱即用度 | 5.0 | 3 个可复制开场白 |
+
+## Improvement Suggestions
+
+无需强制修改。扣分项均为功能定位导致的天然局限（A3: 团队不适用，A4: 无复杂个性化，E3: 功能无需增值特性）。综合 4.9 达到实用标准 ✅
+```

skills/base-skills/skill-trace-evaluation/references/trace-skill-checklist.md

@@ -0,0 +1,64 @@
+# Skill TRACE 自检清单（一页纸版本）
+
+> **来源声明：** 本文档来源于 [skill-trace-checker](skills/base-skills/skill-trace-checker/references/skill-checklist.md) by 东四联周博远。
+> **内容关系：** 本文档是 [scoring-criteria.md](scoring-criteria.md) 的一页纸浓缩版，所有满分标准均衍生自 scoring-criteria.md 的 20 子项定义。详细修改对比和基分公式请查阅 scoring-criteria.md。
+
+创建或修改 Skill 后，逐项打勾。所有项目通过后才能交付。
+
+---
+
+## T · Trust 可信任度
+
+- [ ] SKILL.md 全文为中文，触发词包含中文关键词
+- [ ] 所有示例场景基于国内真实平台
+- [ ] 系统提示词有"禁止行为"列表，无 P0/P1 安全风险
+- [ ] 有"能力边界说明"独立章节（三分类 + 各类 ≥3 个具体例子）
+- [ ] 有数据隐私/安全使用说明（FAQ 或专项章节）
+
+---
+
+## R · Reliability 可靠性
+
+- [ ] 系统提示词规定：信息不足时先给假设版本 + 列具体补充清单
+- [ ] 明确禁止"请提供更多信息"等笼统提示
+- [ ] 所有主要使用场景有覆盖，每个功能有输出格式说明
+- [ ] 超范围请求有替代工具引导说明
+- [ ] 多任务场景有优先级处理说明
+
+---
+
+## A · Adaptability 适用性
+
+- [ ] 每个功能模块有"精确触发条件"（主触发 + 子模块路由）
+- [ ] 能力边界三分类各有具体例子（不是泛泛而谈）
+- [ ] 说明了不同类型用户（垂直行业/团队等）的使用方式
+- [ ] 有定制化使用指南（风格卡片或参数传递机制）
+
+---
+
+## C · Convention 规范性
+
+- [ ] 有快速导航/新手入门章节（第一屏30秒能上手）
+- [ ] references/ 目录存在且文件名语义清晰
+- [ ] references/ 下有 trace-anti-patterns.md：≥3类反模式 + 改进对比 + 禁忌清单
+- [ ] 主文档 FAQ ≥6 题（通用问题）
+- [ ] references/faq-deep.md：≥8 题（边缘场景/工具兼容/安全合规）
+
+---
+
+## E · Effectiveness 有效性
+
+- [ ] 系统提示词有输出准确性约束（禁止在不确定领域胡编）
+- [ ] 功能点覆盖该领域 80%+ 的常见需求
+- [ ] 有 ≥3 项超出基础功能的增值特性
+- [ ] 有"新手入门"章节 + ≥3 个可直接复制的开场白示例
+- [ ] references/examples.md：每个主要模块有真实输出示例（三元组格式）
+
+---
+
+## 最终确认
+
+```
+[ ] 全部 25 项通过 → 输出 TRACE 评分表，综合 5.0 / 5.0 ✅
+[ ] 有未通过项 → 修改对应文件后重新检查，不允许交付
+```

skills/base-skills/skill-trace-evaluation/scripts/trace_evaluate.py

@@ -0,0 +1,632 @@
+#!/usr/bin/env python3
+"""
+Hybrid TRACE evaluator: static base score + evidence packet.
+
+This script computes a deterministic base score for each TRACE sub-item from
+measurable evidence fields. The AI (loaded with skill-trace-evaluation SKILL.md)
+then applies a semantic adjustment (±0.3) based on reading the SKILL.md body.
+
+Final score per sub-item = clamp(base + adjustment, 1.0, 5.0).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+FRONTMATTER_BOUNDARY = re.compile(r"^---\s*$")
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+SECRET_RE = re.compile(
+    r"(AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{16,}|"
+    r"(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]+['\"])",
+    re.IGNORECASE,
+)
+
+SECURITY_DECLARATION_RE = re.compile(
+    r'(?:does not (?:access|collect|upload|send|transmit|share|leak|store|log)'
+    r'|no (?:sensitive|secret|credential|api.key|token|password)'
+    r'|不(?:访问|收集|上传|发送|传输|共享|泄露|存储|记录)'
+    r'|无(?:敏感|密钥|凭据|API|token|密码)'
+    r'|最小权限|least.privilege'
+    r'|安全|security.safe)',
+    re.IGNORECASE,
+)
+
+CLI_SECTION_RE = re.compile(
+    r'(?:^|\n)\s*(?:###?\s+)?(?:Prerequisites|Install(?:ation)?|Setup'
+    r'|Configuration|Usage|Quick\s*Start|Getting\s*Started'
+    r'|Environment\s*(?:Setup|Variables)|Authentication|Login'
+    r'|基本用法|使用方式|安装|配置|环境|登录|前置条件)',
+    re.IGNORECASE,
+)
+
+WORKFLOW_STEP_RE = re.compile(r'(?:^|\n)\s*(?:###?\s+)?Step\s+\d', re.MULTILINE)
+
+
+@dataclass
+class SubItemScore:
+    base: float
+    formula: str
+    evidence: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DimScores:
+    label: str
+    sub_items: Dict[str, SubItemScore] = field(default_factory=dict)
+
+    @property
+    def avg(self) -> float:
+        if not self.sub_items:
+            return 0.0
+        return round(sum(s.base for s in self.sub_items.values()) / len(self.sub_items), 1)
+
+
+@dataclass
+class EvidencePacket:
+    skill_dir: str
+    skill_name: str
+    generated_at: str
+    frontmatter: Dict[str, Any] = field(default_factory=dict)
+    body: Dict[str, Any] = field(default_factory=dict)
+    directory: Dict[str, Any] = field(default_factory=dict)
+    safety: Dict[str, Any] = field(default_factory=dict)
+    base_scores: Dict[str, Any] = field(default_factory=dict)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="trace_evaluate.py",
+        description="Hybrid TRACE evaluator: static base score + evidence packet for AI adjustment.",
+    )
+    p.add_argument("--skill-dir", required=True, help="Path to the target skill directory.")
+    p.add_argument("--format", choices=["json", "pretty"], default="json", help="Output format.")
+    p.add_argument("--output", default="", help="Write output to a file instead of stdout.")
+    return p.parse_args()
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def has_chinese(text: str) -> bool:
+    return bool(re.search(r'[\u4e00-\u9fff]', text))
+
+
+def count_files(dir_path: Path) -> int:
+    if not dir_path.exists():
+        return 0
+    return sum(1 for p in dir_path.rglob("*") if p.is_file())
+
+
+def count_subdirs(dir_path: Path) -> int:
+    if not dir_path.exists():
+        return 0
+    return sum(1 for p in dir_path.iterdir() if p.is_dir())
+
+
+def list_ref_names(dir_path: Path) -> List[str]:
+    if not dir_path.exists():
+        return []
+    return sorted([p.name for p in dir_path.rglob("*") if p.is_file()])
+
+
+def parse_frontmatter(skill_md: str) -> Tuple[Dict[str, Any], str]:
+    lines = skill_md.splitlines()
+    if not lines or not FRONTMATTER_BOUNDARY.match(lines[0]):
+        return {}, skill_md
+    i = 1
+    fm_lines: List[str] = []
+    while i < len(lines) and not FRONTMATTER_BOUNDARY.match(lines[i]):
+        fm_lines.append(lines[i])
+        i += 1
+    if i >= len(lines):
+        return {}, skill_md
+    body = "\n".join(lines[i + 1 :]).lstrip("\n")
+    fm: Dict[str, Any] = {}
+    for raw in fm_lines:
+        if not raw.strip() or raw.strip().startswith("#"):
+            continue
+        if ":" not in raw:
+            continue
+        k, v = raw.split(":", 1)
+        fm[k.strip()] = v.strip()
+    return fm, body
+
+
+def collect_facts(skill_dir: Path) -> Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any], Dict[str, Any], str]:
+    """Collect all raw facts from the skill directory."""
+    skill_md_path = skill_dir / "SKILL.md"
+    if not skill_md_path.exists():
+        return {}, {}, {}, {}, ""
+
+    raw = read_text(skill_md_path)
+    fm, body = parse_frontmatter(raw)
+
+    frontmatter = {
+        "name": (fm.get("name") or "").strip(),
+        "name_valid": bool(fm.get("name") and NAME_RE.match(fm["name"].strip())),
+        "name_matches_dir": (fm.get("name") or "").strip() == skill_dir.name,
+        "description": (fm.get("description") or "").strip()[:200],
+        "description_length": len((fm.get("description") or "").strip()),
+        "description_valid": 1 <= len((fm.get("description") or "").strip()) <= 1024,
+        "license": (fm.get("license") or "").strip(),
+    }
+
+    body_lower = body.lower()
+    body_facts = {
+        "body_lines": len(body.splitlines()),
+        "body_chars": len(body),
+        "has_chinese": has_chinese(body),
+        "has_workflow_steps": bool(WORKFLOW_STEP_RE.search(body)),
+        "step_count": len(WORKFLOW_STEP_RE.findall(body)),
+        "has_rules_section": bool(
+            "## rules" in body_lower
+            or "## writing rules" in body_lower
+            or re.search(r'(?:^|\n)##\s+.*[Rr]ules', body) is not None
+        ),
+        "has_gotchas_section": "## gotchas" in body_lower,
+        "has_validation": bool(
+            re.search(r'(?:validation|校验|自检|checklist|verify|验证)', body_lower)
+        ),
+        "has_boundary": bool(
+            "不该用" in body or "不适用" in body
+            or "should not" in body.lower()
+            or "not use" in body.lower()
+            or "do not use" in body.lower()
+        ),
+        "has_when_to_use": bool("什么时候" in body or "When to" in body),
+        "has_trigger_hints": bool(re.search(
+            r'(?:加载|load|when to read|read.*if|打开.+文件|参考.*文件)', body_lower
+        )),
+        "has_security_declaration": bool(SECURITY_DECLARATION_RE.search(body)),
+        "cli_sections_count": len(CLI_SECTION_RE.findall(body)),
+        "bash_blocks_count": len(re.findall(r'```(?:bash|shell|sh|zsh)', body)),
+        "tool_reference_count": len(re.findall(
+            r'(?:dreamina|uvx|npx|pipx|bunx|deno\s+run|go\s+run|curl|wget)\b',
+            body, re.IGNORECASE
+        )),
+        "prompt_keyword_count": len(re.findall(
+            r'(?:提示词|prompt|word-library|vocabulary|场景|scenario|category|模板|template)',
+            body, re.IGNORECASE
+        )),
+        "gotchas_count": len(re.findall(
+            r'(?:^|\n)\d+\.\s+\*\*', body
+        )) + len(re.findall(r'(?:^|\n)\d+\.\s', body)),
+    }
+
+    cli_score = body_facts["bash_blocks_count"] + body_facts["tool_reference_count"]
+    if cli_score >= 3:
+        body_facts["skill_type"] = "cli"
+    elif body_facts["prompt_keyword_count"] >= 8:
+        body_facts["skill_type"] = "prompt"
+    else:
+        body_facts["skill_type"] = "doc"
+
+    directory = {
+        "has_scripts": (skill_dir / "scripts").exists(),
+        "scripts_files": count_files(skill_dir / "scripts"),
+        "has_references": (skill_dir / "references").exists(),
+        "references_files": count_files(skill_dir / "references"),
+        "references_subdirs": count_subdirs(skill_dir / "references"),
+        "has_examples": (skill_dir / "examples").exists(),
+        "examples_files": count_files(skill_dir / "examples"),
+        "has_license_file": (skill_dir / "LICENSE.txt").exists(),
+        "ref_names": list_ref_names(skill_dir / "references"),
+    }
+
+    safety = {
+        "secrets_detected": False,
+        "secret_findings": [],
+        "has_interactive_patterns": [],
+    }
+    for p in skill_dir.rglob("*"):
+        if p.is_dir():
+            continue
+        if p.suffix.lower() not in {".md", ".txt", ".json", ".yaml", ".yml", ".py", ".sh"}:
+            continue
+        try:
+            text = read_text(p)
+        except Exception:
+            continue
+        m = SECRET_RE.search(text)
+        if m:
+            safety["secrets_detected"] = True
+            safety["secret_findings"].append(f"{p.relative_to(skill_dir)}: {m.group(0)[:60]}")
+        if "input(" in text or "read -p" in text:
+            safety["has_interactive_patterns"].append(
+                f"{p.relative_to(skill_dir)}: may require interactive input"
+            )
+
+    return frontmatter, body_facts, directory, safety, body
+
+
+# ══════════════════════════════════════════════════════════════════
+#  Base score formulas — one function per sub-item.
+#  Each returns a SubItemScore with base in [1.0, 5.0] and the
+#  formula string explaining how the score was computed.
+# ══════════════════════════════════════════════════════════════════
+
+
+def _clamp(v: float) -> float:
+    return round(max(1.0, min(5.0, v)), 1)
+
+
+# ── T · Trust ──
+
+def score_T1(fm, body, directory, safety) -> SubItemScore:
+    s = safety["secrets_detected"]
+    ss = safety.get("secret_findings", [])
+    hs = directory["has_scripts"]
+    sd = body["has_security_declaration"]
+    base = 4.5
+    if s:
+        base = max(2.0, 3.5 - 0.5 * len(ss))
+    else:
+        base = 4.5
+    if not hs:
+        base += 0.3
+    else:
+        base -= 0.3
+    if sd:
+        base += 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"4.5 + (no_scripts:{not hs} ? +0.3 : -0.3) + (secdecl:{sd} ? +0.2 : 0) - (secrets_detected:{s} ? -1.0 : 0)",
+        evidence={"secrets_detected": s, "has_scripts": hs, "has_security_declaration": sd},
+    )
+
+
+def score_T2(fm, body, directory, safety) -> SubItemScore:
+    hc = body["has_chinese"]
+    bl = body["body_lines"]
+    base = 5.0 if hc else 2.0
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"has_chinese={hc} → {base}",
+        evidence={"has_chinese": hc},
+    )
+
+
+def score_T3(fm, body, directory, safety) -> SubItemScore:
+    hb = body["has_boundary"]
+    hw = body["has_when_to_use"]
+    base = 4.5 if hb else 3.0
+    if hb and hw:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"boundary={hb}(+0.3) + when_to_use={hw}(+0.3) off 4.5 base → {base}",
+        evidence={"has_boundary": hb, "has_when_to_use": hw},
+    )
+
+
+def score_T4(fm, body, directory, safety) -> SubItemScore:
+    hs = directory["has_scripts"]
+    sd = body["has_security_declaration"]
+    base = 4.5
+    if sd:
+        base += 0.5
+    if hs:
+        base -= 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"4.5 + (secdecl:{sd} ? +0.5 : 0) - (has_scripts:{hs} ? -0.2 : 0)",
+        evidence={"has_security_declaration": sd, "has_scripts": hs},
+    )
+
+
+# ── R · Reliability ──
+
+def score_R1(fm, body, directory, safety) -> SubItemScore:
+    hg = body["has_gotchas_section"]
+    hv = body["has_validation"]
+    base = 4.0 if hg else 3.0
+    if hg and hv:
+        base += 0.5
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"gotchas={hg}→4.0 + (validation:{hv} ? +0.5)",
+        evidence={"has_gotchas_section": hg, "has_validation": hv},
+    )
+
+
+def score_R2(fm, body, directory, safety) -> SubItemScore:
+    hw = body["has_workflow_steps"]
+    sc = body["step_count"]
+    cs = body["cli_sections_count"]
+    ex = directory["examples_files"]
+    st = body["skill_type"]
+    base = 4.5 if hw else (4.0 if cs >= 3 else 3.5)
+    if sc >= 5 or ex >= 10:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"WF={hw}({sc}steps) CLI={cs} exs={ex} type={st} → {base}",
+        evidence={"has_workflow_steps": hw, "step_count": sc, "cli_sections_count": cs, "examples_files": ex},
+    )
+
+
+def score_R3(fm, body, directory, safety) -> SubItemScore:
+    hg = body["has_gotchas_section"]
+    hr = body["has_rules_section"]
+    hv = body["has_validation"]
+    base = 4.0
+    if hg or hr:
+        base += 0.3
+    if hv:
+        base += 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"gotchas={hg} rules={hr} validation={hv} → {base}",
+        evidence={"has_gotchas_section": hg, "has_rules_section": hr, "has_validation": hv},
+    )
+
+
+def score_R4(fm, body, directory, safety) -> SubItemScore:
+    hb = body["has_boundary"]
+    base = 4.5 if hb else 3.5
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"boundary={hb} → {base}",
+        evidence={"has_boundary": hb},
+    )
+
+
+# ── A · Adaptability ──
+
+def score_A1(fm, body, directory, safety) -> SubItemScore:
+    hb = body["has_boundary"]
+    hw = body["has_when_to_use"]
+    base = 4.5 if (hb and hw) else 4.0
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"boundary={hb} + when_to_use={hw} → {base}",
+        evidence={"has_boundary": hb, "has_when_to_use": hw},
+    )
+
+
+def score_A2(fm, body, directory, safety) -> SubItemScore:
+    dl = fm["description_length"]
+    dv = fm["description_valid"]
+    base = 5.0 if dl >= 100 else (4.5 if dl >= 50 else 3.5)
+    if not dv:
+        base = min(base, 3.0)
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"description_length={dl} valid={dv} → {base}",
+        evidence={"description_length": dl, "description_valid": dv},
+    )
+
+
+def score_A3(fm, body, directory, safety) -> SubItemScore:
+    hc = body["has_chinese"]
+    bl = body["body_lines"]
+    base = 4.0
+    if hc:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"chinese={hc} → {base}",
+        evidence={"has_chinese": hc},
+    )
+
+
+def score_A4(fm, body, directory, safety) -> SubItemScore:
+    ex = directory["examples_files"]
+    rf = directory["references_files"]
+    st = body["skill_type"]
+    base = 4.5 if (ex >= 10 or st == "cli") else 4.0
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"type={st} exs={ex} refs={rf} → {base}",
+        evidence={"skill_type": st, "examples_files": ex, "references_files": rf},
+    )
+
+
+# ── C · Convention ──
+
+def score_C1(fm, body, directory, safety) -> SubItemScore:
+    ex = directory["examples_files"]
+    st = body["skill_type"]
+    threshold = 4 if st == "cli" else 10
+    base = 5.0 if ex >= threshold else (4.5 if ex >= 3 else 3.5)
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"type={st} exs={ex}>={threshold} → {base}",
+        evidence={"skill_type": st, "examples_files": ex},
+    )
+
+
+def score_C2(fm, body, directory, safety) -> SubItemScore:
+    rf = directory["references_files"]
+    bl = body["body_lines"]
+    th = body["has_trigger_hints"]
+    st = body["skill_type"]
+    base = 4.0
+    body_threshold = 150 if st == "cli" else 200
+    if rf >= 8 and bl < body_threshold:
+        base = 5.0
+    elif rf >= 3 and bl < 350:
+        base = 4.5
+    elif rf > 0:
+        base = 4.0
+    else:
+        base = 3.0
+    if th and rf > 0:
+        base += 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"type={st} refs={rf} body={bl} trigger_hints={th} → {base}",
+        evidence={"references_files": rf, "body_lines": bl, "has_trigger_hints": th},
+    )
+
+
+def score_C3(fm, body, directory, safety) -> SubItemScore:
+    nv = fm["name_valid"]
+    nm = fm["name_matches_dir"]
+    rs = directory["references_subdirs"]
+    base = 4.5
+    if nv and nm:
+        base += 0.2
+    if rs >= 2:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"name_valid={nv} name_matches={nm} ref_subdirs={rs} → {base}",
+        evidence={"name_valid": nv, "name_matches_dir": nm, "references_subdirs": rs},
+    )
+
+
+def score_C4(fm, body, directory, safety) -> SubItemScore:
+    hg = body["has_gotchas_section"]
+    gc = body.get("gotchas_count", 0)
+    base = 4.5 if hg else 3.5
+    if gc >= 5:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"gotchas_section={hg} gotchas_count≈{gc} → {base}",
+        evidence={"has_gotchas_section": hg, "gotchas_count_approx": gc},
+    )
+
+
+# ── E · Effectiveness ──
+
+def score_E1(fm, body, directory, safety) -> SubItemScore:
+    hw = body["has_workflow_steps"]
+    hv = body["has_validation"]
+    st = body["skill_type"]
+    base = 4.5 if hw else 4.0
+    if hv:
+        base += 0.3
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"type={st} WF={hw} validation={hv} → {base}",
+        evidence={"skill_type": st, "has_workflow_steps": hw, "has_validation": hv},
+    )
+
+
+def score_E2(fm, body, directory, safety) -> SubItemScore:
+    ex = directory["examples_files"]
+    st = body["skill_type"]
+    thresholds = {"prompt": 25, "cli": 4, "doc": 5}
+    t = thresholds.get(st, 5)
+    base = 5.0 if ex >= t else (4.5 if ex >= 10 else (4.0 if ex >= 3 else 3.0))
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"type={st} exs={ex}>={t} → {base}",
+        evidence={"skill_type": st, "examples_files": ex},
+    )
+
+
+def score_E3(fm, body, directory, safety) -> SubItemScore:
+    rs = directory["references_subdirs"]
+    rf = directory["references_files"]
+    base = 4.5 if rs >= 2 else 4.0
+    if rf >= 10:
+        base += 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"ref_subdirs={rs} refs={rf} → {base}",
+        evidence={"references_subdirs": rs, "references_files": rf},
+    )
+
+
+def score_E4(fm, body, directory, safety) -> SubItemScore:
+    hw = body["has_workflow_steps"]
+    hv = body["has_validation"]
+    hg = body["has_gotchas_section"]
+    cs = body["cli_sections_count"]
+    base = 4.0
+    if hw:
+        base += 0.3
+    if hv:
+        base += 0.3
+    if hg:
+        base += 0.2
+    if cs >= 3:
+        base += 0.2
+    return SubItemScore(
+        base=_clamp(base),
+        formula=f"WF={hw} val={hv} gotchas={hg} cli_secs={cs} → {base}",
+        evidence={"has_workflow_steps": hw, "has_validation": hv, "has_gotchas_section": hg, "cli_sections_count": cs},
+    )
+
+
+# ── Master table ──
+
+SCORE_FUNCTIONS: Dict[str, callable] = {
+    "T1": score_T1, "T2": score_T2, "T3": score_T3, "T4": score_T4,
+    "R1": score_R1, "R2": score_R2, "R3": score_R3, "R4": score_R4,
+    "A1": score_A1, "A2": score_A2, "A3": score_A3, "A4": score_A4,
+    "C1": score_C1, "C2": score_C2, "C3": score_C3, "C4": score_C4,
+    "E1": score_E1, "E2": score_E2, "E3": score_E3, "E4": score_E4,
+}
+
+
+def compute_base_scores(fm, body, directory, safety) -> Dict[str, Any]:
+    dims = {"T": [], "R": [], "A": [], "C": [], "E": []}
+    for key, fn in SCORE_FUNCTIONS.items():
+        dim = key[0]
+        sub = fn(fm, body, directory, safety)
+        dims[dim].append(sub)
+
+    result = {}
+    for dim, subs in dims.items():
+        avg = round(sum(s.base for s in subs) / len(subs), 2) if subs else 0.0
+        result[dim] = {
+            "avg": avg,
+            "sub_items": {f"{dim}{i+1}": {"base": subs[i].base, "formula": subs[i].formula, "evidence": subs[i].evidence} for i in range(len(subs))},
+        }
+    result["overall"] = round(
+        sum(result[d]["avg"] for d in ["T", "R", "A", "C", "E"]) / 5.0, 2
+    )
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    skill_dir = Path(args.skill_dir).expanduser().resolve()
+
+    fm, body, directory, safety, _ = collect_facts(skill_dir)
+    if not fm:
+        return 1
+
+    base_scores = compute_base_scores(fm, body, directory, safety)
+
+    packet = {
+        "skill_dir": str(skill_dir),
+        "skill_name": (fm.get("name") or skill_dir.name).strip(),
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "frontmatter": fm,
+        "body": body,
+        "directory": directory,
+        "safety": safety,
+        "base_scores": base_scores,
+    }
+
+    if args.format == "pretty":
+        out = json.dumps(packet, ensure_ascii=False, indent=2, default=str)
+    else:
+        out = json.dumps(packet, ensure_ascii=False, indent=2, default=str)
+
+    if args.output:
+        out_path = Path(args.output).expanduser().resolve()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(out, encoding="utf-8")
+        return 0
+
+    sys.stdout.write(out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skills/database-skills/dbeaver/LICENSE.txt

@@ -1,14 +0,0 @@
-Apache License 2.0
-Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.

skills/database-skills/dbeaver/SKILL.md

@@ -1,31 +0,0 @@
----
-name: dbeaver
-description: Provides comprehensive guidance for DBeaver including database connection, SQL development, data management, and ER diagrams. Use when the user asks about DBeaver, needs to connect to databases, manage database connections, or use DBeaver for SQL development.
-license: Complete terms in LICENSE.txt
----
-
-## When to use this skill
-
-Use this skill whenever the user wants to:
-- 配置 DBeaver 数据库连接（MySQL、PostgreSQL、Oracle、MongoDB 等）
-- 使用 DBeaver 进行 SQL 开发、查询、数据编辑
-- 管理数据库连接、驱动、书签
-- 导出/导入数据、生成 ER 图、生成 DDL
-
-## How to use this skill
-
-1. **连接管理**：新建连接 → 选择数据库类型 → 配置连接参数 → 测试连接。
-2. **SQL 开发**：使用 SQL 编辑器、查询控制台、结果排序过滤。
-3. **数据管理**：导出数据（CSV、JSON、SQL、Excel）、导入数据、批量编辑。
-4. **ER 图**：从数据库生成实体关系图，可视化表结构。
-
-## Best Practices
-
-- 驱动管理：首次连接需下载数据库驱动，DBeaver 会自动提示。
-- 敏感信息：连接属性中可加密存储密码，启用"记住密码"选项。
-- 事务管理：默认自动提交，生产环境建议手动管理事务。
-- 结果集：使用过滤器、排序、分页查看大量数据。
-
-## Keywords
-
-dbeaver, database, sql, postgresql, mysql, oracle, mongodb, 数据库管理, sql 开发, er 图

skills/database-skills/elasticsearch/SKILL.md

@@ -1,28 +1,199 @@
 ---
 name: elasticsearch
-description: Provides comprehensive guidance for Elasticsearch including indexing, searching, aggregations, mappings, and cluster management. Use when the user asks about Elasticsearch, needs to implement search functionality, work with Elasticsearch queries, or manage Elasticsearch clusters.
+description: Provides comprehensive guidance for Elasticsearch including indexing, mappings, query DSL, aggregations, analyzers, cluster management, and ELK Stack integration. Use when the user asks about Elasticsearch, needs to implement search functionality, work with Elasticsearch queries, or manage Elasticsearch clusters.
 license: Complete terms in LICENSE.txt
 ---
 
-## When to use this skill
+# Elasticsearch — 分布式搜索与分析引擎
 
-Use this skill whenever the user wants to:
-- 设计索引 mapping、分词与查询（term、match、bool、agg）
-- 使用 REST API 或客户端进行索引、搜索与聚合
-- 处理集群、分片、副本与运维（快照、升级）
+Elasticsearch 是基于 Apache Lucene 的分布式搜索和分析引擎，提供近实时的全文搜索、结构化搜索、聚合分析、地理空间查询和向量搜索能力。
 
-## How to use this skill
+## Workflow — 从数据到搜索的 5 步决策流程
 
-1. **API**：PUT index、POST _doc、GET _search；query DSL 与 aggregations；reindex、_bulk。
-2. **环境**：单节点或集群；版本与 Kibana/Logstash 配套；认证与 TLS。
-3. **运维**：分片与副本数规划；快照与恢复；监控集群健康与慢查询。
+```
+遇到 ES 相关需求时按以下顺序决策:
 
-## Best Practices
+Step 1: 明确场景
+├── 全文搜索?                    → Step 2
+├── 结构化数据分析 (日志/指标)?   → Step 2
+├── 向量/KNN 搜索?               → references/ 向量搜索
+├── 地理空间查询?                 → references/ 地理查询
+├── 集群运维/性能问题?             → references/ 07-cluster-ops
+└── 数据管道/日志采集?             → references/ 08-elk-integration
 
-- mapping 设计好分词与类型；避免动态映射导致冲突。
-- 查询用 filter 缓存与合适 size；大结果用 scroll 或 search_after。
-- 生产用副本与快照；安全与权限配置完善。
+Step 2: 设计索引 (Mapping + Analyzer)
+├── 确定字段类型 (text/keyword/date/geo/nested…)
+├── 选择分词器 (standard/ik/pinyin/自定义)
+├── 规划主分片数 (每个分片 20-50GB), 建后不可改
+└── 设置别名用于零停机重建
+
+Step 3: 写入数据
+├── Index API (单条), Bulk API (批量, 5-15MB/批)
+├── _update (部分更新), _update_by_query (条件更新)
+└── Logstash/Filebeat (日志采集管道)
+
+Step 4: 构建查询
+├── 全文搜索: match / multi_match / query_string
+├── 精确过滤: term / terms / range / exists / bool filter
+├── 复合查询: bool (must/should/filter/must_not)
+├── 聚合分析: terms + avg → references/ 聚合专题
+└── 排序/分页: sort / search_after (深度分页) / scroll (导出)
+
+Step 5: 持续优化
+├── 性能问题?  → Profile API + 慢查询日志
+├── 数据增长?  → ILM + Rollover 自动化 (references/ 07-cluster-ops)
+├── Mapping 变更? → Reindex + Alias 零停机 (examples/03)
+└── 查询优化?  → filter 优先 query, 避免 script, 限制 _source
+```
+
+## When to Use / When NOT to
+
+| ✅ 使用 ES | ❌ 不要用 ES |
+|-----------|-------------|
+| **全文搜索** — 商品/文章/文档关键词搜索 | **复杂事务** — 需要 ACID/多表 JOIN, 选 PostgreSQL |
+| **日志/指标分析** — ELK Stack 日志场景 | **键值缓存** — 简单 KV 查询, 选 Redis |
+| **搜索型应用** — 电商/知识库/文档管理 | **强 Schema 约束** — 需要外键/触发器, 选 RDBMS |
+| **聚合/仪表盘** — 实时统计 + Kibana 可视化 | **海量文档存储无需搜索** — 选 MongoDB |
+| **地理空间查询** — 附近的人/POI/地理围栏 | **纯 OLAP 分析** — PB 级离线分析, 选 ClickHouse |
+| **向量搜索** — 语义相似度/RAG 检索 | **消息队列** — 选 Kafka/Pulsar |
+
+**核心原则**：Elasticsearch 是搜索服务器，不是关系型数据库的替代品。
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 |
+|-----------|--------------|---------|
+| 全文搜索、模糊搜索、相关性排序 | 强一致性（ES 是近实时，默认 1s refresh） | 代替关系型数据库做核心业务存储 |
+| 日志/指标聚合分析 (Kibana) | 秒级以下数据可见性（需调 refresh_interval） | 复杂 JOIN 查询（ES 有有限 nested 支持）|
+| 地理空间、自动补全、搜索建议 | 极高写入量（需调优线程池和批量写入） | ACID 事务保证 |
+| 文档搜索、知识库、RAG 检索 | 50+ 节点大集群（需专用协调节点） | 存储二进制大文件（存 OSS 路径） |
+| 时序数据 + ILM 滚动 | PB 级深度分页（需 search_after / PIT） | 强关联约束数据模型 |
+| 向量搜索 (dense_vector + KNN) | 自定义分词器（需先测试分析效果） | 替代 Kafka 做消息队列 |
+
+## 核心概念速查
+
+| 概念 | ES 术语 | 关系型 DB 类比 | 关键说明 | 深度参考 |
+|------|---------|---------------|---------|---------|
+| **Index** | 索引 | Table | 存储文档的逻辑命名空间，名称必须小写 | references/05 |
+| **Document** | 文档 | Row | JSON 格式基本数据单元，不可变（update = delete+index） | — |
+| **Shard** | 分片 | Partition | 水平切分单元，主分片数建后不可改，推荐 20-50GB/分片 | references/07 |
+| **Replica** | 副本 | Replica | 冗余副本提供高可用和读扩展，可动态调整 | references/07 |
+| **Mapping** | 映射 | Schema | 定义字段类型和分词配置，已有字段类型不可修改 | references/05 |
+| **Analyzer** | 分词器 | — | text 字段必须配置，决定搜索质量 | references/06 |
+
+## 查询 DSL 速查
+
+| 查询类别 | 核心查询 | 用途 | 深度参考 |
+|---------|---------|------|---------|
+| **全文查询** | match / match_phrase / multi_match / query_string | 文本分词搜索、短语匹配、多字段搜索 | references/01 |
+| **精确查询** | term / terms / range / exists / ids | keyword 字段精确匹配、范围过滤、存在检查 | references/02 |
+| **复合查询** | bool (must/filter/should/must_not) | 90% 搜索需求可用 bool 实现 | references/02 |
+| **嵌套/父子** | nested / has_child / has_parent | 对象内跨字段关联、父子关系查询 | references/02 |
+| **地理查询** | geo_distance / geo_bounding_box / geo_shape | 附近查询、矩形区域、复杂地理形状 | 见 geospatial 技能 |
+| **向量查询** | knn 参数 / k-NN 插件 | 语义相似度、RAG 检索 | references/05 |
+| **特殊查询** | fuzzy / wildcard / regexp / script / percolate | 模糊纠错、通配符、脚本、反向搜索 | references/02 |
+
+## 聚合速查
+
+| 聚合类型 | 核心聚合 | 类似 SQL | 深度参考 |
+|---------|---------|---------|---------|
+| **指标聚合** | avg / sum / min / max / stats / cardinality / percentiles | AVG / SUM / COUNT(DISTINCT) / PERCENTILE | references/03 |
+| **桶聚合** | terms / date_histogram / histogram / range / filters | GROUP BY / 日期分组 / 区间分组 / 过滤分组 | references/04 |
+| **管道聚合** | derivative / moving_fn / bucket_script / bucket_selector | 环比 / 移动平均 / 子聚合计算 / HAVING | references/04 |
+
+## 集群运维概述
+
+| 运维领域 | 关键要点 | 深度参考 |
+|---------|---------|---------|
+| **节点类型** | Master(3个专用) + Data(SSD) + Coordinating(大查询) | references/07 |
+| **分片管理** | 分配/再平衡/reroute/延迟分配 | references/07 |
+| **快照备份** | S3/FS/GCS 仓库, SLM 自动管理, 增量快照 | references/07 |
+| **ILM 生命周期** | hot → warm → cold → frozen → delete 自动化 | references/07 |
+| **监控命令** | _cluster/health, _cat/nodes, _cat/shards, hot_threads | references/07 |
+| **安全** | RBAC 角色, 字段/文档级安全, TLS, API Key | references/07 |
+
+## Gotchas — 常见陷阱与反模式
+
+| # | 陷阱 | 问题 | 解决方案 |
+|---|------|------|---------|
+| 1 | `term` 查询 `text` 字段 | text 被分词，找不到精确值 | 用 `match` 或 `.keyword` 子字段 |
+| 2 | `from+size` 深度分页 | 越深越慢直至 OOM (限制 10000) | 深翻页用 `search_after`，导出用 `scroll`/PIT |
+| 3 | 建索引后改主分片数 | 建后不可修改 | 提前规划，或重建索引 (reindex) |
+| 4 | 所有字段用 `text` | 聚合/排序报错 | text + keyword 多字段 |
+| 5 | 依赖动态映射 | 时间戳被识别为 long 等 | 生产环境显式 mapping |
+| 6 | 嵌套对象用普通查询 | 跨字段关联条件误匹配 | 必须用 `nested` 查询 |
+| 7 | 分片过多或过少 | 过多→管理开销大，过少→无法扩展 | 每个分片 20-50GB |
+| 8 | 大批量写入不做优化 | 频繁 refresh 产生大量小段 | 关闭 refresh (-1), Bulk API, 副本=0 |
+| 9 | 忽略 filter 缓存 | 重复计算，性能差 | 不需要算分的条件放 filter |
+| 10 | wildcard/regexp 前缀搜索 | 不利用倒排索引，性能极差 | 用 `prefix` 或 edge_ngram |
+| 11 | 脚本查询滥用 | 不可缓存，性能差，调试困难 | 用 ingest pipeline 预处理 |
+| 12 | 集群角色不做分离 | Master 因 Data GC 失联 | 专用 3 个 Master 节点 |
+| 13 | 日志索引无 ILM | 索引无限增长 | ILM 自动化滚动/压缩/删除 |
+| 14 | 忽略 `ignore_above` | keyword 超长导致索引失败 | 设置 `ignore_above: 256` |
+| 15 | 在 text 字段开 `fielddata` | 内存消耗大 | 用 `.keyword` 多字段替代 |
+
+## FAQ
+
+**Q1: ES 是关系型数据库的替代品吗？**
+不是。ES 是搜索服务器，不支持 ACID 事务、外键、复杂 JOIN。正确架构：业务数据存 RDBMS，ES 做搜索和聚合。
+
+**Q2: 数据写入后多久能查到？**
+近实时。写入先到 buffer，默认 1s refresh 后才可搜索。可调 `refresh_interval` 或加 `?refresh` 参数。
+
+**Q3: text 和 keyword 字段区别？**
+text：分词后索引，支持 match 搜索，不支持排序/聚合。keyword：完整值索引，支持 term 搜索、排序、聚合。
+
+**Q4: 主分片数为什么不能修改？**
+路由规则 `hash(_id) % shards`，修改后已有数据无法定位。变更需 reindex。
+
+**Q5: 如何选择分片数？**
+每个分片 20-50GB。500GB 原始数据 → 10-25 个主分片。每个节点 ≤25 分片/GB 堆内存。
+
+**Q6: ES 为什么搜索快？**
+倒排索引：将每个词项映射到文档列表，查找直接定位。加分片并行 + filter 缓存。
+
+**Q7: 聚合 (Aggregation) 是什么？**
+Bucket = GROUP BY 分组，Metric = AVG/SUM/COUNT，Pipeline = 聚合结果的再分析。详见 references/03, references/04。
+
+**Q8: Green/Yellow/Red 状态？**
+Green=全正常，Yellow=主分片正常但副本未分配，Red=主分片丢失。
+
+**Q9: 如何零停机重建索引？**
+Alias + Reindex：创建新索引 → Reindex 数据 → 原子切换 Alias → 删除旧索引。见 examples/03。
+
+**Q10: ES 和 Solr 怎么选？**
+ES 集群管理内置、近实时搜索 1s、聚合强大、ELK 生态完整。Solr 依赖 ZK，配置复杂。
+
+**Q11: Mapping 可以修改吗？**
+可新增字段，不可修改已有字段类型（如 text→keyword），需重建索引。
+
+**Q12: search_after 和 from+size 区别？**
+from+size 深度分页 OOM（限制 10000）。search_after 基于排序值翻页，性能与深度无关。
+
+**Q13: 数据备份怎么做？**
+Snapshot API 备份到 S3/GCS/FS。推荐 SLM 自动管理。增量快照只存变化。
+
+**Q14: 查询慢如何排查？**
+Profile API → 慢查询日志 → filter vs query → segments 数量 → GC 日志。
+
+**Q15: ILM 能解决什么问题？**
+自动滚动（大小/时间阈值）、自动迁移（热→温→冷）、自动压缩、自动删除。
 
 ## Keywords
 
-elasticsearch, search, index, 搜索引擎, 全文检索, 聚合
+elasticsearch, ES, 搜索引擎, 全文搜索, 倒排索引, Lucene, index, mapping, document, shard, replica, analyzer, ik, pinyin, 查询 DSL, match, term, bool, filter, range, multi_match, query_string, nested, geo, aggregation, 聚合, terms, date_histogram, avg, sum, cardinality, percentiles, pipeline, reindex, bulk, scroll, search_after, ILM, rollover, force_merge, alias, snapshot, cluster, ELK, Logstash, Kibana, Filebeat, KNN, dense_vector, 向量搜索, painless, ingest pipeline, RBAC, profile API, 慢查询, zero downtime
+
+## References
+
+- references/01-query-dsl-fulltext.md — 全文查询（match/multi_match/query_string）
+- references/02-query-dsl-term.md — 精确查询与复合查询（term/range/bool）
+- references/03-aggregations-metric.md — 指标聚合（avg/sum/stats/cardinality/percentiles）
+- references/04-aggregations-bucket.md — 桶聚合（terms/date_histogram/range）
+- references/05-mapping-types.md — 映射与字段类型详解
+- references/06-analyzers.md — 分词器（标准/IK/pinyin/自定义）
+- references/07-cluster-ops.md — 集群运维（分片/监控/快照/ILM）
+- references/08-elk-integration.md — Logstash/Filebeat/Kibana 配置
+- examples/01-fulltext-search.md — 全文搜索实战
+- examples/02-aggregation-report.md — 聚合报表实战
+- examples/03-reindex-zero-downtime.md — 零停机重建索引
+- examples/04-cluster-monitoring.md — 集群监控实战

skills/database-skills/elasticsearch/examples/01-fulltext-search.md

@@ -0,0 +1,215 @@
+# 示例: 全文搜索实战 — 电商商品搜索
+
+## 场景
+
+构建一个电商商品搜索功能，支持关键词搜索、多字段搜索、价格筛选、分页。
+
+## 步骤
+
+### 1. 创建索引与 Mapping
+
+```json
+PUT /products
+{
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 1
+  },
+  "mappings": {
+    "dynamic": "strict",
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "description": {
+        "type": "text",
+        "analyzer": "ik_max_word"
+      },
+      "category": { "type": "keyword" },
+      "brand": { "type": "keyword" },
+      "price": { "type": "float" },
+      "tags": { "type": "keyword" },
+      "status": { "type": "keyword" },
+      "created_at": { "type": "date" },
+      "stock": { "type": "integer" }
+    }
+  }
+}
+```
+
+### 2. 导入示例数据
+
+```bash
+POST /products/_bulk
+{"index":{"_id":1}}
+{"title":"Apple MacBook Pro 16英寸 M3 Pro","description":"Apple M3 Pro芯片, 18GB统一内存, 512GB存储","category":"笔记本","brand":"Apple","price":19999,"tags":["electronics","laptop","apple"],"status":"active","stock":50,"created_at":"2024-01-15T10:30:00Z"}
+{"index":{"_id":2}}
+{"title":"华为 MateBook X Pro 2024","description":"13.9英寸 3K触控屏, 32GB内存, 1TB SSD","category":"笔记本","brand":"华为","price":14999,"tags":["electronics","laptop","huawei"],"status":"active","stock":30,"created_at":"2024-01-20T14:00:00Z"}
+{"index":{"_id":3}}
+{"title":"iPhone 15 Pro Max 256GB","description":"A17 Pro芯片, 4800万像素主摄, 钛金属设计","category":"手机","brand":"Apple","price":9999,"tags":["electronics","phone","apple"],"status":"active","stock":100,"created_at":"2024-02-01T09:00:00Z"}
+{"index":{"_id":4}}
+{"title":"Samsung Galaxy S24 Ultra","description":"Snapdragon 8 Gen 3, 200MP相机, S Pen","category":"手机","brand":"Samsung","price":12999,"tags":["electronics","phone","samsung"],"status":"active","stock":80,"created_at":"2024-02-10T11:00:00Z"}
+{"index":{"_id":5}}
+{"title":"机械革命 极光Pro 游戏本","description":"RTX4060显卡, i7-12650H, 15.6英寸165Hz","category":"笔记本","brand":"机械革命","price":6999,"tags":["electronics","laptop","gaming"],"status":"active","stock":20,"created_at":"2024-03-01T16:00:00Z"}
+{"index":{"_id":6}}
+{"title":"Apple MacBook Air M2","description":"M2芯片, 13.6英寸, 8GB内存, 256GB存储","category":"笔记本","brand":"Apple","price":8999,"tags":["electronics","laptop","apple"],"status":"inactive","stock":0,"created_at":"2023-06-01T10:00:00Z"}
+```
+
+### 3. 基本关键词搜索
+
+```bash
+# 搜索"笔记本" (精确匹配标题)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": "笔记本"
+    }
+  }
+}
+# 返回: MacBook Pro, MateBook X Pro, 极光Pro
+
+# 多字段搜索 (标题+描述)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "苹果笔记本 M3",
+      "fields": ["title^3", "description"],
+      "type": "best_fields"
+    }
+  }
+}
+# title 权重 3 倍, MacBook Pro 排最前
+```
+
+### 4. 综合搜索 (关键词 + 筛选 + 分页)
+
+```bash
+# 搜索"笔记本", 过滤价格 5000-15000, 只返回 active 商品
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "match": { "title": "笔记本" } }
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "range": { "price": { "gte": 5000, "lte": 15000 } } }
+      ]
+    }
+  },
+  "sort": [
+    { "price": { "order": "asc" } }
+  ],
+  "_source": ["title", "brand", "price", "stock"]
+}
+# 返回: 极光Pro (6999), MacBook Air (8999), MateBook X Pro (14999)
+```
+
+### 5. 搜索建议 (Completion Suggester)
+
+```json
+PUT /products/_mapping
+{
+  "properties": {
+    "title_suggest": {
+      "type": "completion"
+    }
+  }
+}
+
+POST /products/_update/1
+{
+  "doc": {
+    "title_suggest": ["Apple MacBook Pro", "MacBook Pro"]
+  }
+}
+
+POST /products/_update/3
+{
+  "doc": {
+    "title_suggest": ["iPhone 15 Pro Max", "iPhone 15"]
+  }
+}
+
+# 搜索建议
+GET /products/_search
+{
+  "suggest": {
+    "product_suggest": {
+      "prefix": "mac",
+      "completion": {
+        "field": "title_suggest",
+        "size": 5
+      }
+    }
+  }
+}
+# 返回: ["Apple MacBook Pro", "MacBook Pro"]
+```
+
+### 6. 高亮显示
+
+```bash
+GET /products/_search
+{
+  "query": {
+    "match": { "title": "笔记本" }
+  },
+  "highlight": {
+    "fields": {
+      "title": {},
+      "description": {}
+    },
+    "pre_tags": ["<em>"],
+    "post_tags": ["</em>"]
+  }
+}
+# title 中"笔记本"会被 <em> 标签包裹
+```
+
+## 完整搜索 API 示例
+
+```bash
+# 前端搜索框调用的完整 API
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "multi_match": {
+          "query": "笔记本",
+          "fields": ["title^3", "description", "brand"],
+          "type": "best_fields"
+        }}
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "terms": { "category": ["笔记本", "平板"] }},
+        { "range": { "price": { "gte": 3000, "lte": 20000 } }},
+        { "term": { "brand": "Apple" }}
+      ],
+      "should": [
+        { "term": { "tags": "hot" }},
+        { "term": { "is_new": true }}
+      ]
+    }
+  },
+  "sort": [
+    { "_score": { "order": "desc" }},
+    { "created_at": { "order": "desc" }}
+  ],
+  "from": 0,
+  "size": 20,
+  "_source": ["title", "brand", "price", "stock", "category"],
+  "highlight": {
+    "fields": { "title": { "number_of_fragments": 0 } }
+  }
+}
+```

skills/database-skills/elasticsearch/examples/02-aggregation-report.md

@@ -0,0 +1,206 @@
+# 示例: 聚合报表 — 电商销售分析
+
+## 场景
+
+基于订单数据构建销售分析仪表盘：销售额趋势、TOP 品类、品牌分布、价格区段。
+
+## 步骤
+
+### 1. 创建索引
+
+```json
+PUT /orders
+{
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 1
+  },
+  "mappings": {
+    "properties": {
+      "order_id": { "type": "keyword" },
+      "user_id": { "type": "keyword" },
+      "product_id": { "type": "keyword" },
+      "product_name": { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
+      "category": { "type": "keyword" },
+      "brand": { "type": "keyword" },
+      "amount": { "type": "float" },
+      "quantity": { "type": "integer" },
+      "status": { "type": "keyword" },
+      "region": { "type": "keyword" },
+      "order_date": { "type": "date" },
+      "payment_date": { "type": "date" }
+    }
+  }
+}
+```
+
+### 2. 按品类统计销售额 (terms + sum)
+
+```bash
+# 每个品类的总销售额, 降序排列
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_category": {
+      "terms": {
+        "field": "category",
+        "size": 20,
+        "order": { "total_sales": "desc" }
+      },
+      "aggs": {
+        "total_sales": { "sum": { "field": "amount" } },
+        "avg_order": { "avg": { "field": "amount" } },
+        "order_count": { "value_count": { "field": "order_id" } }
+      }
+    }
+  }
+}
+```
+
+### 3. 每日销售趋势 (date_histogram + sum)
+
+```bash
+# 按天统计销售额
+GET /orders/_search
+{
+  "size": 0,
+  "query": {
+    "range": {
+      "order_date": { "gte": "now-30d", "lte": "now" }
+    }
+  },
+  "aggs": {
+    "daily_sales": {
+      "date_histogram": {
+        "field": "order_date",
+        "calendar_interval": "day",
+        "format": "yyyy-MM-dd",
+        "min_doc_count": 0,
+        "extended_bounds": {
+          "min": "2024-01-01",
+          "max": "2024-12-31"
+        }
+      },
+      "aggs": {
+        "revenue": { "sum": { "field": "amount" } },
+        "orders": { "value_count": { "field": "order_id" } }
+      }
+    }
+  }
+}
+```
+
+### 4. 价格区段分布 (range + stats)
+
+```bash
+# 价格区段 + 每个区段的统计
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_ranges": {
+      "range": {
+        "field": "amount",
+        "ranges": [
+          { "key": "低价 (<100)", "to": 100 },
+          { "key": "中低价 (100-500)", "from": 100, "to": 500 },
+          { "key": "中价 (500-2000)", "from": 500, "to": 2000 },
+          { "key": "高价 (2000-10000)", "from": 2000, "to": 10000 },
+          { "key": "超高 (>10000)", "from": 10000 }
+        ]
+      },
+      "aggs": {
+        "amount_stats": { "stats": { "field": "amount" } },
+        "brand_distribution": {
+          "terms": { "field": "brand", "size": 5 }
+        }
+      }
+    }
+  }
+}
+```
+
+### 5. 地区分布 + TOP 品牌 (嵌套聚合)
+
+```bash
+# 各地区销售额, 每个地区 TOP 品牌
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_region": {
+      "terms": {
+        "field": "region",
+        "size": 10,
+        "order": { "revenue": "desc" }
+      },
+      "aggs": {
+        "revenue": { "sum": { "field": "amount" } },
+        "order_count": { "value_count": { "field": "order_id" } },
+        "top_brands": {
+          "terms": {
+            "field": "brand",
+            "size": 5,
+            "order": { "brand_revenue": "desc" }
+          },
+          "aggs": {
+            "brand_revenue": { "sum": { "field": "amount" } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 6. 综合仪表盘查询 (一次查询完成多项分析)
+
+```bash
+# 一次查询返回多种聚合结果
+GET /orders/_search
+{
+  "size": 0,
+  "query": {
+    "bool": {
+      "filter": [
+        { "term": { "status": "completed" } },
+        { "range": { "order_date": { "gte": "now-30d/d", "lte": "now" } } }
+      ]
+    }
+  },
+  "aggs": {
+    "overview": {        // 总体指标
+      "stats": { "field": "amount" }
+    },
+    "total_revenue": {
+      "sum": { "field": "amount" }
+    },
+    "unique_customers": {
+      "cardinality": { "field": "user_id" }
+    },
+    "sales_trend": {     // 日销售趋势
+      "date_histogram": {
+        "field": "order_date",
+        "calendar_interval": "day"
+      },
+      "aggs": {
+        "daily_revenue": { "sum": { "field": "amount" } }
+      }
+    },
+    "top_categories": {  // TOP 品类
+      "terms": { "field": "category", "size": 10 },
+      "aggs": {
+        "cat_revenue": { "sum": { "field": "amount" } }
+      }
+    },
+    "price_distribution": {  // 价格分布
+      "percentiles": {
+        "field": "amount",
+        "percents": [25, 50, 75, 90, 99]
+      }
+    }
+  }
+}
+# 一次请求返回: 总览统计 + 总销售额 + 去重用户数 + 日趋势 + TOP 品类 + 价格百分位
+```

skills/database-skills/elasticsearch/examples/03-reindex-zero-downtime.md

@@ -0,0 +1,200 @@
+# 示例: 零停机重建索引 (Zero-Downtime Reindex)
+
+## 场景
+
+需要修改已有索引的 mapping（如添加字段、修改分词器），但生产环境不能停机。
+
+## 核心思路
+
+Alias（别名） + Reindex（数据迁移） + 原子切换。
+
+## 步骤
+
+### 1. 假设已有索引和别名
+
+```bash
+# 初始状态: 已有 products_v1 索引, 通过 products 别名访问
+GET /products/_search
+{
+  "query": { "match_all": {} }
+}
+# 别名可以透明访问
+```
+
+### 2. 创建新索引 (v2) 使用新的 mapping
+
+```json
+PUT /products_v2
+{
+  "settings": {
+    "number_of_shards": 5,
+    "number_of_replicas": 1,
+    "refresh_interval": "-1"
+  },
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 },
+          "pinyin": { "type": "text", "analyzer": "pinyin" }
+        }
+      },
+      "description": {
+        "type": "text",
+        "analyzer": "ik_max_word"
+      },
+      "price": { "type": "double" },
+      "new_field": { "type": "keyword" },
+      "search_all": {
+        "type": "text",
+        "analyzer": "ik_max_word"
+      }
+    }
+  }
+}
+```
+
+### 3. 执行 Reindex 数据迁移
+
+```bash
+# 使用 slices=auto 并行加速
+POST /_reindex?slices=auto&wait_for_completion=false
+{
+  "source": {
+    "index": "products_v1"
+  },
+  "dest": {
+    "index": "products_v2"
+  },
+  "script": {
+    "source": """
+      // 如果新索引有 copy_to 字段, 在脚本中处理
+      if (ctx._source.title != null && ctx._source.description != null) {
+        ctx._source.search_all = ctx._source.title + ' ' + ctx._source.description;
+      }
+      // 添加新字段默认值
+      ctx._source.new_field = 'migrated';
+    """
+  }
+}
+# 返回 task id, 可用 _tasks API 查看进度
+GET /_tasks/<task_id>
+```
+
+### 4. 原子切换别名 (零停机)
+
+```bash
+# 关键步骤: 一次操作移除旧别名 + 添加新别名
+# 这期间已有查询不会中断
+POST /_aliases
+{
+  "actions": [
+    { "remove": { "index": "products_v1", "alias": "products" } },
+    { "add": { "index": "products_v2", "alias": "products" } }
+  ]
+}
+# 原子操作, 切换完成后所有通过 products 别名的查询自动指向 v2
+```
+
+### 5. 验证并删除旧索引
+
+```bash
+# 验证新索引数据完整
+GET /products/_search
+{
+  "query": { "match_all": {} },
+  "size": 0
+}
+
+# 确认无误后删除旧索引
+DELETE /products_v1
+```
+
+## Reindex 进阶技巧
+
+### 跨集群 Reindex
+
+```bash
+POST /_reindex
+{
+  "source": {
+    "remote": {
+      "host": "http://old-cluster:9200",
+      "username": "elastic",
+      "password": "pass"
+    },
+    "index": "products"
+  },
+  "dest": {
+    "index": "products_v2"
+  }
+}
+```
+
+### 只迁移部分数据
+
+```bash
+POST /_reindex
+{
+  "source": {
+    "index": "products_v1",
+    "query": {
+      "term": { "status": "active" }
+    }
+  },
+  "dest": {
+    "index": "products_active"
+  }
+}
+```
+
+### 冲突处理
+
+```bash
+# 跳过已存在的文档 (op_type=create)
+POST /_reindex
+{
+  "source": { "index": "products_v1" },
+  "dest": {
+    "index": "products_v2",
+    "op_type": "create"
+  }
+}
+
+# 或者使用 version_type=external 保留旧版本
+```
+
+### Reindex 大小和速度
+
+```bash
+# 限制批次大小 (默认 1000)
+POST /_reindex
+{
+  "source": {
+    "index": "products_v1",
+    "size": 5000
+  },
+  "dest": {
+    "index": "products_v2"
+  }
+}
+
+# 限制速率 (每秒文档数)
+PUT /_cluster/settings
+{
+  "transient": {
+    "indices.recovery.max_bytes_per_sec": "200mb"
+  }
+}
+```
+
+## 注意事项
+
+1. **大索引 Reindex**：建议 `slices=auto` 并行执行，可根据数据节点数自动调整并行度
+2. **源索引不影响**：Reindex 期间源索引可继续读写服务
+3. **Refresh 优化**：新索引设 `refresh_interval: -1`，迁移完再恢复
+4. **副本优化**：新索引设 `number_of_replicas: 0`，迁移完再调回
+5. **验证数据完整性**：迁移后对比文档数 (`_cat/count`)
+6. **善后清理**：确认新索引正常后删除旧索引释放空间

skills/database-skills/elasticsearch/examples/04-cluster-monitoring.md

@@ -0,0 +1,204 @@
+# 示例: 集群监控实战
+
+## 场景
+
+日常运维需要监控 Elasticsearch 集群的健康状态、性能指标和资源使用情况。
+
+## 1. 集群健康检查
+
+### 快速健康状态
+
+```bash
+# 绿色 = 全部正常, 黄色 = 副本未分配, 红色 = 主分片丢失
+GET /_cluster/health?pretty
+```
+
+```json
+{
+  "cluster_name": "production",
+  "status": "yellow",
+  "timed_out": false,
+  "number_of_nodes": 5,
+  "number_of_data_nodes": 3,
+  "active_primary_shards": 125,
+  "active_shards": 240,
+  "relocating_shards": 0,
+  "initializing_shards": 0,
+  "unassigned_shards": 10,
+  "delayed_unassigned_shards": 0,
+  "active_shards_percent_as_number": 96.0
+}
+```
+
+**解读**：unassigned_shards=10, active_shards_percent=96% → 有副本未分配。检查节点是否宕机。
+
+### 详细健康诊断
+
+```bash
+# 查看所有未分配分片的原因
+GET /_cluster/allocation/explain?pretty
+
+# 重点关注字段:
+# - current_node: 当前所在节点
+# - can_remain_on_current_node: 能否保留
+# - can_rebalance_cluster: 能否再平衡
+# - node_decision: 节点决策
+```
+
+## 2. 节点监控
+
+### 节点概览
+
+```bash
+# 节点角色和资源使用
+GET /_cat/nodes?v&h=name,node.role,heap.percent,ram.percent,cpu,load_1m,disk.used_percent,master
+
+# 示例输出:
+# name     node.role heap.percent ram.percent cpu load_1m disk.used_percent master
+# master-1 m                  42          35   8     2.3               42 *
+# data-1   d                  67          72  35    12.5               56 -
+# data-2   d                  55          60  28     9.8               52 -
+# coord-1  -                  48          45  15     4.1               38 -
+```
+
+**告警阈值**：
+- heap.percent > 85 → GC 压力大
+- cpu > 80 → 需要扩容
+- disk.used_percent > 85 → 需要清理或 ILM
+
+### 热点线程排查 (CPU 突增)
+
+```bash
+# 当集群 CPU 突然飙高时
+GET /_nodes/hot_threads
+
+# 返回每个节点的热点线程堆栈
+# 重点关注:
+# - bulk 线程 → 写入压力大
+# - search 线程 → 查询压力大
+# - merge 线程 → 段合并 (大批量写入后)
+# - GC 线程 → 内存问题
+```
+
+### 节点统计
+
+```bash
+# 获取节点级别详细统计
+GET /_nodes/stats/indices,os,process,jvm,fs,transport,http
+
+# 关注指标:
+# - indices.indexing: 写入速率
+# - indices.search: 查询速率
+# - jvm.mem.heap_used_percent: 堆内存使用
+# - jvm.gc.collectors.young.collection_time_in_millis: GC 时间
+# - os.cpu.percent: CPU
+# - fs.total.available_in_bytes: 磁盘空间
+```
+
+## 3. 索引监控
+
+### 索引概览
+
+```bash
+# 查看所有索引的大小和文档数
+GET /_cat/indices?v&h=index,docs.count,store.size,pri.store.size
+
+# 查看索引分片分布
+GET /_cat/shards?v
+
+# 按大小排序
+GET /_cat/indices?v&s=store.size:desc
+```
+
+### 段 (Segment) 监控
+
+```bash
+# 检查段的统计
+GET /my_index/_segments
+
+# 查看各索引段数
+GET /_cat/segments?v&h=index,shard,segment,size,committed,search
+```
+
+**段过多 (>100)** 表示需要 force_merge：`POST /my_index/_forcemerge?max_num_segments=1`
+
+## 4. 性能监控脚本
+
+### Shell 健康检查脚本
+
+```bash
+#!/bin/bash
+# es_health_check.sh
+ES_HOST="http://localhost:9200"
+
+# 集群健康
+echo "=== 集群健康 ==="
+curl -s "$ES_HOST/_cluster/health?pretty" | python3 -c "
+import json, sys
+h = json.load(sys.stdin)
+print(f'状态: {h[\"status\"]}')
+print(f'节点: {h[\"number_of_nodes\"]} (数据节点: {h[\"number_of_data_nodes\"]})')
+print(f'活跃分片: {h[\"active_shards\"]}/{h[\"active_primary_shards\"]}p')
+print(f'未分配: {h[\"unassigned_shards\"]}')
+print(f'活跃率: {h[\"active_shards_percent_as_number\"]:.1f}%')
+"
+
+# 节点资源
+echo -e "\n=== 节点资源 ==="
+curl -s "$ES_HOST/_cat/nodes?v&h=name,node.role,heap.percent,cpu,load_1m,disk.used_percent"
+
+# 索引 TOP 10 大索引
+echo -e "\n=== TOP 10 大索引 ==="
+curl -s "$ES_HOST/_cat/indices?v&h=index,docs.count,store.size&s=store.size:desc&limit=10"
+
+# JVM 堆内存 Top 节点
+echo -e "\n=== JVM 内存 (Top 5) ==="
+curl -s "$ES_HOST/_nodes/stats/jvm" | python3 -c "
+import json, sys
+nodes = json.load(sys.stdin)['nodes']
+for node_id, info in sorted(nodes.items(), key=lambda x: x[1]['jvm']['mem']['heap_used_percent'], reverse=True)[:5]:
+    name = info['name']
+    mem = info['jvm']['mem']
+    gc = info['jvm']['gc']['collectors']
+    print(f'{name}: heap={mem[\"heap_used_percent\"]}%  old_gc={gc[\"old\"][\"collection_count\"]}次({gc[\"old\"][\"collection_time_in_millis\"]//1000}s)')
+"
+```
+
+## 5. 告警规则建议
+
+| 指标 | 警告阈值 | 严重阈值 | 检查间隔 |
+|------|---------|---------|---------|
+| cluster health status | yellow > 5min | red | 1min |
+| heap usage | > 80% | > 90% | 1min |
+| CPU | > 70% | > 85% | 5min |
+| disk usage | > 80% | > 90% | 1min |
+| unassigned shards | > 0 | > 5 | 1min |
+| search latency P99 | > 1s | > 5s | 5min |
+| indexing latency P99 | > 500ms | > 2s | 5min |
+| GC old gen count | > 5/min | > 10/min | 1min |
+
+## 6. Kibana 监控配置
+
+```yaml
+# 启用 Kibana 监控 UI (Stack Monitoring)
+# Management → Stack Monitoring
+# 可查看:
+# - 集群概览 (节点/索引/分片)
+# - 节点 CPU/内存/磁盘/IO
+# - 索引搜索/写入速率
+# - GC 统计
+# - 慢查询 Top N
+```
+
+## 性能排查清单
+
+```
+1. 是否 Yellow/Red → 检查未分配分片 (allocation/explain)
+2. CPU 高 → hot_threads 排查
+3. 查询慢 → Profile API + 慢查询日志
+4. 写入慢 → 检查 refresh_interval + Bulk 优化
+5. 磁盘满 → ILM 清理 + force_merge
+6. GC 频繁 → 减少分片/字段, 增加堆内存
+7. Segments 多 → force_merge (只读索引)
+8. 深度分页 → 改用 search_after
+```

skills/database-skills/elasticsearch/references/01-query-dsl-fulltext.md

@@ -0,0 +1,162 @@
+# 全文查询 (Full Text Queries)
+
+全文查询会对查询文本进行分词，然后搜索倒排索引。这些查询会计算相关性分数 (`_score`)。
+
+## match — 标准全文匹配
+
+```bash
+# 基本 match (默认 OR 逻辑)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": "apple macbook"
+    }
+  }
+}
+
+# AND 逻辑 (必须匹配所有词项)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": {
+        "query": "apple macbook",
+        "operator": "and"
+      }
+    }
+  }
+}
+
+# minimum_should_match (至少匹配 75% 词项)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": {
+        "query": "apple macbook pro",
+        "minimum_should_match": "75%"
+      }
+    }
+  }
+}
+```
+
+**业务场景**：商品搜索、文章搜索、文档搜索。用户输入关键词时自动分词匹配。
+
+## match_phrase — 短语匹配
+
+```bash
+# 精确短语匹配 (顺序必须一致)
+GET /products/_search
+{
+  "query": {
+    "match_phrase": {
+      "title": "macbook pro"
+    }
+  }
+}
+
+# 带 slop 的短语匹配 (允许词项间插入 slop 个词)
+GET /products/_search
+{
+  "query": {
+    "match_phrase": {
+      "title": {
+        "query": "macbook pro",
+        "slop": 1
+      }
+    }
+  }
+}
+```
+
+**业务场景**：搜索"红米手机"不希望匹配"红色小米手机"；搜索完整书名/产品名。
+
+## multi_match — 多字段匹配
+
+```bash
+# 同时在 title 和 description 中搜索
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "轻薄笔记本",
+      "fields": ["title", "description"]
+    }
+  }
+}
+
+# 带权重 (title 字段权重 2 倍)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "轻薄笔记本",
+      "fields": ["title^2", "description", "tags^0.5"]
+    }
+  }
+}
+
+# type 说明:
+# - best_fields (默认): 取最佳匹配字段分数
+# - most_fields: 合并所有匹配字段分数
+# - cross_fields: 将词项拆分到多字段 (适合姓名搜索)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "Will Smith",
+      "fields": ["first_name", "last_name"],
+      "type": "cross_fields"
+    }
+  }
+}
+```
+
+**业务场景**：搜索框同时匹配标题、描述、标签等字段；人名搜索。
+
+## query_string — 完整查询语法
+
+```bash
+# 支持 AND/OR/NOT, 通配符, 正则等
+GET /products/_search
+{
+  "query": {
+    "query_string": {
+      "query": "title:(apple AND macbook) AND price:[10000 TO 20000]",
+      "default_operator": "and"
+    }
+  }
+}
+
+# 支持短语和多字段
+GET /products/_search
+{
+  "query": {
+    "query_string": {
+      "query": "\"macbook pro\" OR \"iphone\"",
+      "fields": ["title^2", "description"]
+    }
+  }
+}
+```
+
+**注意**：query_string 解析语法错误会抛出异常，生产环境推荐用 `simple_query_string`。
+
+## simple_query_string — 安全版查询语法
+
+```bash
+GET /products/_search
+{
+  "query": {
+    "simple_query_string": {
+      "query": "\"macbook pro\" +apple -samsung",
+      "fields": ["title", "description"],
+      "default_operator": "or"
+    }
+  }
+}
+```
+
+**支持语法**：`+` (AND), `|` (OR), `-` (NOT), `"` (短语), `*` (前缀)。语法错误不会抛异常。

skills/database-skills/elasticsearch/references/02-query-dsl-term.md

@@ -0,0 +1,210 @@
+# 精确查询与复合查询
+
+精确查询不会对搜索词进行分词，直接匹配倒排索引中的精确值。
+
+## term / terms — 精确值匹配
+
+```bash
+# 精确匹配 keyword 字段 (不要对 text 字段用 term!)
+GET /products/_search
+{
+  "query": {
+    "term": {
+      "tags": "electronics"
+    }
+  }
+}
+
+# 多值匹配
+GET /products/_search
+{
+  "query": {
+    "terms": {
+      "tags": ["electronics", "laptop"]
+    }
+  }
+}
+
+# ids 查询
+GET /products/_search
+{
+  "query": {
+    "ids": {
+      "values": ["1", "2", "3"]
+    }
+  }
+}
+```
+
+**⚠️ 常见陷阱**：`term` 查询对 `text` 字段几乎永远不匹配，因为 text 字段被分词后存储的是词项而非完整内容。
+
+## range — 范围查询
+
+```bash
+# 数值范围
+GET /products/_search
+{
+  "query": {
+    "range": {
+      "price": { "gte": 10000, "lte": 20000 }
+    }
+  }
+}
+
+# 日期范围 (支持日期数学)
+GET /products/_search
+{
+  "query": {
+    "range": {
+      "created_at": { "gte": "now-7d/d", "lte": "now" }
+    }
+  }
+}
+
+# 日期数学: now-1h, now+1d, now/d, now-1M/M, 2024-01-01||+1y
+```
+
+## exists — 存在性检查
+
+```bash
+# 查找有 description 字段的文档
+GET /products/_search
+{
+  "query": {
+    "exists": { "field": "description" }
+  }
+}
+
+# 查找没有 description 的文档 (using must_not)
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must_not": [
+        { "exists": { "field": "description" } }
+      ]
+    }
+  }
+}
+```
+
+## bool 查询 — 最常用的组合查询
+
+```bash
+# bool 结构: must (AND+算分), filter (AND+缓存), should (OR), must_not (NOT)
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "match": { "title": "轻薄笔记本" } }
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "range": { "price": { "gte": 3000, "lte": 8000 } } }
+      ],
+      "should": [
+        { "match": { "description": "轻薄" } }
+      ],
+      "minimum_should_match": 1
+    }
+  }
+}
+```
+
+**filter vs query 选择**：
+- filter：精确匹配、范围过滤 → 可缓存，不贡献算分
+- query：全文搜索 → 贡献算分，不可缓存
+
+## nested — 嵌套对象查询
+
+```json
+// mapping 定义
+PUT /orders
+{
+  "mappings": {
+    "properties": {
+      "items": {
+        "type": "nested",
+        "properties": {
+          "product_id": { "type": "keyword" },
+          "quantity": { "type": "integer" },
+          "price": { "type": "float" }
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+# nested 查询 (保证跨字段关联正确)
+GET /orders/_search
+{
+  "query": {
+    "nested": {
+      "path": "items",
+      "query": {
+        "bool": {
+          "must": [
+            { "term": { "items.product_id": "p100" } },
+            { "range": { "items.quantity": { "gte": 2 } } }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## 其他特殊查询
+
+```bash
+# fuzzy — 模糊纠错
+GET /products/_search
+{
+  "query": {
+    "fuzzy": {
+      "title": {
+        "value": "macbok",
+        "fuzziness": "AUTO",
+        "prefix_length": 2,
+        "transpositions": true
+      }
+    }
+  }
+}
+# "macbok" → 匹配 "macbook"
+
+# wildcard — 通配符 (性能差, 谨慎使用)
+GET /products/_search
+{
+  "query": {
+    "wildcard": {
+      "title.keyword": "Mac*"
+    }
+  }
+}
+
+# regexp — 正则查询 (性能开销大)
+GET /products/_search
+{
+  "query": {
+    "regexp": {
+      "title.keyword": "Macbook\\s(Pro|Air)"
+    }
+  }
+}
+
+# boosting — 权重控制 (降权不排除)
+GET /products/_search
+{
+  "query": {
+    "boosting": {
+      "positive": { "match": { "title": "手机" } },
+      "negative": { "term": { "status": "discontinued" } },
+      "negative_boost": 0.2
+    }
+  }
+}
+```

skills/database-skills/elasticsearch/references/03-aggregations-metric.md

@@ -0,0 +1,161 @@
+# 指标聚合 (Metric Aggregations)
+
+指标聚合对文档集中的某个字段进行数值计算，类似于 SQL 聚合函数。
+
+## 基本结构
+
+```json
+{
+  "size": 0,
+  "aggs": {
+    "my_agg_name": {       // 自定义聚合名称
+      "avg": {              // 聚合类型
+        "field": "price"
+      }
+    }
+  }
+}
+```
+
+## 常用指标聚合
+
+### avg — 平均值
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "avg_price": {
+      "avg": { "field": "price" }
+    }
+  }
+}
+```
+
+### sum / min / max
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "total_revenue": { "sum": { "field": "price" } },
+    "min_price": { "min": { "field": "price" } },
+    "max_price": { "max": { "field": "price" } }
+  }
+}
+```
+
+### stats — 批量统计
+
+```bash
+# 一次性返回 count/min/max/avg/sum
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_stats": {
+      "stats": { "field": "price" }
+    }
+  }
+}
+```
+
+### extended_stats — 扩展统计
+
+```bash
+# 额外返回方差、标准差、总和平方等
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_extended": {
+      "extended_stats": { "field": "price" }
+    }
+  }
+}
+```
+
+### cardinality — 去重计数 (COUNT DISTINCT)
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "unique_brands": {
+      "cardinality": {
+        "field": "brand",
+        "precision_threshold": 100   // 精度阈值 (默认 3000)
+      }
+    }
+  }
+}
+```
+
+**说明**：cardinality 基于 HyperLogLog++ 算法，近似去重。`precision_threshold` 越高越精确，但消耗更多内存。
+
+### value_count — 非空值计数
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_brand": {
+      "terms": { "field": "brand" },
+      "aggs": {
+        "price_count": { "value_count": { "field": "price" } }
+      }
+    }
+  }
+}
+```
+
+通常作为子聚合，用于计算每个桶的样本数。
+
+### percentiles — 百分位
+
+```bash
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_percentiles": {
+      "percentiles": {
+        "field": "price",
+        "percents": [1, 5, 25, 50, 75, 95, 99]
+      }
+    }
+  }
+}
+```
+
+### percentile_ranks — 百分位排名
+
+```bash
+# 值落在指定阈值内的百分比
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_ranks": {
+      "percentile_ranks": {
+        "field": "price",
+        "values": [5000, 10000]
+      }
+    }
+  }
+}
+```
+
+## 业务场景速查
+
+| 聚合 | 典型场景 |
+|------|---------|
+| avg | 商品均价、平均评分、平均响应时间 |
+| sum | 总销售额、总库存量、总访问量 |
+| stats | 批量统计摘要（报表概览） |
+| cardinality | 独立访客 UV、去重品牌数、唯一 IP 数 |
+| percentiles | 价格分布分析、APM P99 延迟、收入分布 |

skills/database-skills/elasticsearch/references/04-aggregations-bucket.md

@@ -0,0 +1,236 @@
+# 桶聚合 (Bucket Aggregations)
+
+桶聚合将文档分组到不同的"桶"中，类似 SQL 的 GROUP BY。每个桶可以嵌套子聚合。
+
+## terms — 分组聚合 (GROUP BY)
+
+```bash
+# 按标签分组统计
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_tags": {
+      "terms": {
+        "field": "tags",
+        "size": 20,
+        "order": { "_count": "desc" }
+      }
+    }
+  }
+}
+
+# 带子聚合: 每个分组的平均价格
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_brand": {
+      "terms": {
+        "field": "brand",
+        "size": 10,
+        "order": { "avg_price": "desc" }
+      },
+      "aggs": {
+        "avg_price": { "avg": { "field": "price" } },
+        "product_count": { "value_count": { "field": "id" } }
+      }
+    }
+  }
+}
+```
+
+**注意事项**：
+- `size` 控制返回桶数（默认 10），超大 size 消耗内存
+- `order` 支持按文档数 (`_count`)、聚合键 (`_key`)、子聚合排序
+- keyword 字段上聚合性能最佳，text 字段需开启 `fielddata`
+
+## range / date_range — 范围分组
+
+```bash
+# 价格区间分组
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_ranges": {
+      "range": {
+        "field": "price",
+        "ranges": [
+          { "key": "0-1000", "from": 0, "to": 1000 },
+          { "key": "1000-5000", "from": 1000, "to": 5000 },
+          { "key": "5000+", "from": 5000 }
+        ]
+      }
+    }
+  }
+}
+
+# 日期范围
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "date_ranges": {
+      "date_range": {
+        "field": "order_date",
+        "ranges": [
+          { "from": "now-30d/d", "to": "now" },
+          { "from": "now-90d/d", "to": "now-30d/d" }
+        ]
+      }
+    }
+  }
+}
+```
+
+## histogram / date_histogram — 直方图
+
+```bash
+# 价格直方图 (间隔 1000)
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_histogram": {
+      "histogram": {
+        "field": "price",
+        "interval": 1000,
+        "min_doc_count": 1
+      }
+    }
+  }
+}
+
+# 时间直方图 (按小时/天/月/年聚合)
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "orders_over_time": {
+      "date_histogram": {
+        "field": "order_date",
+        "calendar_interval": "day",     // month, quarter, year
+        "format": "yyyy-MM-dd",
+        "min_doc_count": 0,
+        "extended_bounds": {
+          "min": "2024-01-01",
+          "max": "2024-12-31"
+        }
+      }
+    }
+  }
+}
+```
+
+## filter / filters — 过滤聚合
+
+```bash
+# 单一过滤
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "active_products": {
+      "filter": { "term": { "status": "active" } },
+      "aggs": {
+        "avg_price": { "avg": { "field": "price" } }
+      }
+    }
+  }
+}
+
+# 多过滤
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "price_categories": {
+      "filters": {
+        "other_bucket": true,
+        "filters": {
+          "budget":  { "range": { "price": { "lte": 5000 } } },
+          "mid":     { "range": { "price": { "from": 5000, "to": 15000 } } },
+          "premium": { "range": { "price": { "gte": 15000 } } }
+        }
+      }
+    }
+  }
+}
+```
+
+## 管道聚合 (Pipeline Aggregations)
+
+```bash
+# derivative — 环比增量
+GET /orders/_search
+{
+  "size": 0,
+  "aggs": {
+    "sales_per_day": {
+      "date_histogram": {
+        "field": "order_date",
+        "calendar_interval": "day"
+      },
+      "aggs": {
+        "daily_sales": { "sum": { "field": "amount" } },
+        "sales_derivative": {
+          "derivative": { "buckets_path": "daily_sales" }
+        }
+      }
+    }
+  }
+}
+
+# bucket_script — 计算桶间比例
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "total_products": { "value_count": { "field": "id" } },
+    "active_products": {
+      "filter": { "term": { "status": "active" } }
+    },
+    "active_ratio": {
+      "bucket_script": {
+        "buckets_path": {
+          "activeCount": "active_products>_count",
+          "totalCount": "total_products"
+        },
+        "script": "params.activeCount / params.totalCount * 100"
+      }
+    }
+  }
+}
+
+# bucket_selector — 过滤桶 (类似 HAVING)
+GET /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "by_brand": {
+      "terms": { "field": "brand", "size": 100 },
+      "aggs": {
+        "avg_price": { "avg": { "field": "price" } },
+        "brands_having_avg_gt_10000": {
+          "bucket_selector": {
+            "buckets_path": { "avgPrice": "avg_price" },
+            "script": "params.avgPrice > 10000"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 业务场景速查
+
+| 聚合 | 场景 |
+|------|------|
+| terms | 商品分类统计、品牌分布、标签统计 |
+| date_histogram | 销售日报/月报、API 请求时序、监控趋势 |
+| range | 价格区间分布、年龄段统计 |
+| filters | 多条件对比分析 |
+| derivative | 环比增长/下降分析 |
+| bucket_selector | 过滤出符合条件的组 (HAVING) |

skills/database-skills/elasticsearch/references/05-mapping-types.md

@@ -0,0 +1,134 @@
+# 映射与字段类型详解
+
+Mapping 定义文档中每个字段的数据类型和分析方式，相当于关系型数据库的 Schema。
+
+## 字段类型速查
+
+| 字段类型 | 说明 | 适用场景 |
+|---------|------|---------|
+| `text` | 被分词的全文字段 | 全文搜索、文章内容 |
+| `keyword` | 精确值、不被分词 | 标签、状态、分类、ID |
+| `integer` | 32 位整数 | 年龄、计数 |
+| `long` | 64 位整数 | 时间戳、大数值 |
+| `float` | 单精度浮点 | 价格、分数 |
+| `double` | 双精度浮点 | 科学计算 |
+| `boolean` | 布尔值 | 开关、状态 |
+| `date` | 日期 (可多 format) | 时间字段 |
+| `ip` | IPv4/IPv6 | IP 分析、CIDR 匹配 |
+| `geo_point` | 经纬度点 | 地理位置、距离排序 |
+| `geo_shape` | 复杂地理形状 | 区域查询、地理围栏 |
+| `nested` | 嵌套对象 (独立索引) | 保持数组内对象关联 |
+| `object` | JSON 对象 (默认) | 普通嵌套数据 |
+| `completion` | 自动补全 | 搜索建议 |
+| `dense_vector` | 稠密向量 | KNN 语义搜索 |
+| `flattened` | 扁平化嵌套对象 | 未知结构的元数据 |
+| `percolator` | 反向搜索 | 告警规则匹配 |
+| `range` | 范围类型 (integer_range) | IP 段、时间范围 |
+
+## 动态映射 (Dynamic Mapping)
+
+| 设置 | 行为 |
+|------|------|
+| `"dynamic": true` | 自动检测并添加新字段 (默认) |
+| `"dynamic": "runtime"` | 运行时映射 (7.11+) |
+| `"dynamic": false` | 忽略新字段 (不索引，可查询 _source) |
+| `"dynamic": "strict"` | 遇到新字段抛出异常 |
+
+## 映射参数详解
+
+```json
+PUT /articles
+{
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "search_analyzer": "ik_smart",
+        "fields": {
+          "keyword": {
+            "type": "keyword",
+            "ignore_above": 256
+          },
+          "pinyin": {
+            "type": "text",
+            "analyzer": "pinyin"
+          }
+        }
+      },
+      "price": {
+        "type": "float",
+        "coerce": false
+      },
+      "meta_data": {
+        "type": "flattened"
+      }
+    }
+  }
+}
+```
+
+## 关键参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `analyzer` | 索引分词器 | standard |
+| `search_analyzer` | 搜索分词器 | 同 analyzer |
+| `fields` | 多字段 | 无 |
+| `copy_to` | 复制到组合字段 | 无 |
+| `coerce` | 自动类型转换 | true |
+| `doc_values` | 列式存储（排序/聚合） | text 外 true |
+| `index` | 是否索引 | true |
+| `norms` | 归一化因子（算分用） | true |
+| `ignore_above` | 超长不索引 (keyword) | 无 |
+| `eager_global_ordinals` | 预加载全局序数 | false |
+
+## 别名 (Alias) 与索引模板
+
+```json
+// 原子切换别名 (零停机重建)
+POST /_aliases
+{
+  "actions": [
+    { "remove": { "index": "products_v1", "alias": "products" } },
+    { "add": { "index": "products_v2", "alias": "products" } }
+  ]
+}
+
+// 索引模板
+PUT /_index_template/logs_template
+{
+  "index_patterns": ["logs-*"],
+  "template": {
+    "settings": {
+      "number_of_shards": 3,
+      "number_of_replicas": 1
+    },
+    "mappings": {
+      "properties": {
+        "@timestamp": { "type": "date" },
+        "message": { "type": "text" },
+        "level": { "type": "keyword" }
+      }
+    }
+  }
+}
+```
+
+## 索引设置
+
+```json
+PUT /my_index
+{
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 1,
+    "refresh_interval": "30s",
+    "max_result_window": 100000,
+    "codec": "best_compression"
+  },
+  "mappings": { ... }
+}
+```
+
+**重要**：`number_of_shards` 建后不可修改。`refresh_interval` 大批量写入时可设为 `-1`（关闭）。

skills/database-skills/elasticsearch/references/06-analyzers.md

@@ -0,0 +1,187 @@
+# 分词器 (Analyzer)
+
+分词器将文本拆分为词项 (Token)，用于建立倒排索引和搜索。
+
+## Analyzer 组成
+
+```
+Analyzer = Char Filter(s) + Tokenizer + Token Filter(s)
+           (字符过滤)      (分词器)     (词项过滤)
+
+输入: "I <3 Elasticsearch!"
+    ↓
+char_filter: HTML 解码 → "I <3 Elasticsearch!"
+    ↓
+tokenizer: 按空格/标点拆分 → ["I", "<3", "Elasticsearch"]
+    ↓
+token_filter: 小写化 → ["i", "<3", "elasticsearch"]
+    ↓
+输出: ["i", "<3", "elasticsearch"] (存入倒排索引)
+```
+
+## 测试分词器
+
+```bash
+# 测试分析器效果
+POST /_analyze
+{
+  "analyzer": "standard",
+  "text": "I love Elasticsearch 搜索引擎"
+}
+
+# 指定字段测试 (使用字段配置的分析器)
+POST /products/_analyze
+{
+  "field": "title",
+  "text": "Apple MacBook Pro 16英寸"
+}
+```
+
+## 内置分词器
+
+| 分词器 | 说明 | 示例: "I love ES" |
+|--------|------|------------------|
+| `standard` | Unicode 分词, 小写化 (默认) | ["i", "love", "es"] |
+| `simple` | 非字母分割, 小写化 | ["i", "love", "es"] |
+| `whitespace` | 空格分割 (不小写) | ["I", "love", "ES"] |
+| `keyword` | 不分词, 整个字符串输出 | ["I love ES"] |
+| `pattern` | 正则分割 | 取决于 pattern |
+| `stop` | 类似 simple + 去停用词 | ["love", "es"] |
+| `fingerprint` | 排序 + 去重 | ["es", "i", "love"] |
+
+## IK 分词器 (中文)
+
+```bash
+# 安装 (需重启 ES)
+./bin/elasticsearch-plugin install \
+  https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.12.0/elasticsearch-analysis-ik-8.12.0.zip
+
+# ik_smart (粗粒度)
+POST /_analyze { "analyzer": "ik_smart", "text": "中华人民共和国国歌" }
+# → ["中华人民共和国", "国歌"]
+
+# ik_max_word (细粒度, 穷尽所有可能)
+POST /_analyze { "analyzer": "ik_max_word", "text": "中华人民共和国国歌" }
+# → ["中华人民共和国", "中华人民", "中华", "华人", "人民共和国", "人民", "共和国", "共和", "国歌"]
+```
+
+| 场景 | 推荐 | 理由 |
+|------|------|------|
+| 索引 (建倒排索引) | `ik_max_word` | 细粒度, 覆盖更多可能性 |
+| 搜索 (用户输入) | `ik_smart` | 粗粒度, 提高搜索精度 |
+
+## 拼音分词器
+
+```bash
+./bin/elasticsearch-plugin install \
+  https://github.com/medcl/elasticsearch-analysis-pinyin/releases/download/v8.12.0/elasticsearch-analysis-pinyin-8.12.0.zip
+
+# 测试
+POST /_analyze { "analyzer": "pinyin", "text": "王大力" }
+# → ["wang", "da", "li", "wangda", "dali", "wangdali", "wdl"]
+
+# 拼音字段配置
+PUT /products
+{
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "fields": {
+          "pinyin": {
+            "type": "text",
+            "analyzer": "pinyin",
+            "search_analyzer": "pinyin"
+          }
+        }
+      }
+    }
+  }
+}
+# 搜索 "wdali" → 匹配 "王大力"
+```
+
+## 自定义分析器
+
+```json
+PUT /my_index
+{
+  "settings": {
+    "analysis": {
+      "char_filter": {
+        "html_strip": { "type": "html_strip" },
+        "my_mapping": {
+          "type": "mapping",
+          "mappings": ["& => and", "| => or"]
+        }
+      },
+      "tokenizer": {
+        "my_standard": { "type": "standard", "max_token_length": 100 }
+      },
+      "filter": {
+        "my_stop": {
+          "type": "stop",
+          "stopwords": ["a", "an", "the", "is"]
+        },
+        "my_synonym": {
+          "type": "synonym",
+          "synonyms": [
+            "笔记本, 笔记本电脑, laptop",
+            "手机, 移动电话, smartphone"
+          ]
+        }
+      },
+      "analyzer": {
+        "my_custom_analyzer": {
+          "type": "custom",
+          "char_filter": ["html_strip", "my_mapping"],
+          "tokenizer": "my_standard",
+          "filter": ["lowercase", "my_stop", "my_synonym", "asciifolding"]
+        }
+      }
+    }
+  }
+}
+```
+
+## 自动补全 (Edge Ngram)
+
+```json
+PUT /autocomplete_index
+{
+  "settings": {
+    "analysis": {
+      "filter": {
+        "autocomplete_filter": {
+          "type": "edge_ngram",
+          "min_gram": 1,
+          "max_gram": 20
+        }
+      },
+      "analyzer": {
+        "autocomplete": {
+          "type": "custom",
+          "tokenizer": "standard",
+          "filter": ["lowercase", "autocomplete_filter"]
+        }
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "autocomplete",
+        "search_analyzer": "standard"
+      }
+    }
+  }
+}
+```
+
+## 同义词注意事项
+
+- **单向同义词**: `"laptop => 笔记本"` (搜索 laptop 映射到笔记本)
+- **双向同义词**: `"laptop, 笔记本"` (互相等价)
+- **最佳实践**: 索引时不用同义词（保持原始词），搜索时用 `search_analyzer`

skills/database-skills/elasticsearch/references/07-cluster-ops.md

@@ -0,0 +1,225 @@
+# 集群运维
+
+## 节点类型
+
+| 类型 | 角色 | 职责 | 推荐配置 |
+|------|------|------|---------|
+| **Master** | `[master]` | 集群管理、元数据、选主 | 3 个专用, 4C 8G |
+| **Data** | `[data]` | 存储数据、查询/聚合 | N 个, 8C 32G+ SSD |
+| **Ingest** | `[ingest]` | 数据预处理管道 | 日志量大时可用 |
+| **Coordinating** | `[]` | 请求分发、结果合并 | 大查询场景, 8C 32G+ |
+
+**生产环境推荐**：3 个专用 Master + N 个 Data + 2 个 Coordinating。
+
+## 发现与选主
+
+```yaml
+# elasticsearch.yml
+discovery.seed_hosts: ["node1:9300", "node2:9300", "node3:9300"]
+cluster.initial_master_nodes: ["node1", "node2", "node3"]
+```
+
+**防脑裂**：专用 Master 节点、奇数个 (≥3)、堆内存 ≤50% 物理内存。
+
+## 分片分配与再平衡
+
+```bash
+# 查看分片分配
+GET /_cat/shards?v
+
+# 延迟分片分配 (重启节点时)
+PUT /_all/_settings
+{
+  "settings": {
+    "index.unassigned.node_left.delayed_timeout": "5m"
+  }
+}
+
+# 取消再平衡 (维护时)
+PUT /_cluster/settings
+{
+  "transient": {
+    "cluster.routing.rebalance.enable": "none"
+  }
+}
+
+# 重新路由
+POST /_cluster/reroute
+{
+  "commands": [
+    {
+      "move": {
+        "index": "my_index",
+        "shard": 0,
+        "from_node": "node-1",
+        "to_node": "node-2"
+      }
+    }
+  ]
+}
+```
+
+## 快照与恢复 (Snapshot/Restore)
+
+```bash
+# 1. 注册快照仓库
+PUT /_snapshot/my_backup
+{
+  "type": "s3",
+  "settings": {
+    "bucket": "my-es-backups",
+    "region": "us-east-1",
+    "base_path": "elasticsearch/backups"
+  }
+}
+
+# 2. 创建快照
+PUT /_snapshot/my_backup/snapshot_20240101
+{
+  "indices": "logs-*,products",
+  "ignore_unavailable": true,
+  "include_global_state": true
+}
+
+# 3. 查看状态
+GET /_snapshot/my_backup/snapshot_20240101/_status
+
+# 4. 恢复
+POST /_snapshot/my_backup/snapshot_20240101/_restore
+{
+  "indices": "products",
+  "rename_pattern": "(.+)",
+  "rename_replacement": "restored_$1"
+}
+
+# 5. SLM 自动管理
+PUT /_slm/policy/daily_snapshot
+{
+  "name": "<daily-snap-{now/d}>",
+  "repository": "my_backup",
+  "schedule": "0 30 1 * * ?",
+  "retention": {
+    "expire_after": "30d",
+    "min_count": 5,
+    "max_count": 50
+  }
+}
+```
+
+## ILM — 索引生命周期管理
+
+```json
+PUT /_ilm/policy/logs_policy
+{
+  "policy": {
+    "phases": {
+      "hot": {
+        "min_age": "0ms",
+        "actions": {
+          "rollover": {
+            "max_size": "50GB",
+            "max_age": "1d",
+            "max_docs": 5000000
+          }
+        }
+      },
+      "warm": {
+        "min_age": "7d",
+        "actions": {
+          "shrink": { "number_of_shards": 1 },
+          "forcemerge": { "max_num_segments": 1 },
+          "allocate": { "require": { "box_type": "warm" } }
+        }
+      },
+      "cold": {
+        "min_age": "30d",
+        "actions": {
+          "searchable_snapshot": {
+            "snapshot_repository": "my_backup"
+          }
+        }
+      },
+      "delete": {
+        "min_age": "365d",
+        "actions": { "delete": {} }
+      }
+    }
+  }
+}
+```
+
+**生命周期**：hot (热节点 SSD) → warm (温节点 HDD) → cold (可搜索快照) → delete。
+
+## 监控命令
+
+```bash
+# 集群健康
+GET /_cluster/health?pretty
+
+# 节点信息
+GET /_cat/nodes?v&h=name,node.role,heap.percent,ram.percent,cpu,load_1m,master
+
+# 索引信息
+GET /_cat/indices?v&h=index,docs.count,store.size,pri.store.size
+GET /_cat/shards?v
+
+# 热点线程 (排查 CPU 突增)
+GET /_nodes/hot_threads
+
+# 待处理任务
+GET /_cat/pending_tasks
+
+# 节点统计
+GET /_nodes/stats/indices,os,process,jvm,fs,transport,http
+
+# 任务管理
+GET /_tasks?detailed&actions=*byquery
+POST /_tasks/<task_id>/_cancel
+```
+
+## 性能优化
+
+### 分片黄金法则
+
+- 每个分片 20-50GB (最佳)
+- 每 GB 堆内存 20-25 个分片 (含副本)
+- 案例: 1TB → 20-25 主分片 × 1 副本 = 40-50 总分片
+
+### 写入优化
+
+1. 关闭 refresh (`refresh_interval: -1`)
+2. 增加 translog 同步间隔 (`30s`)
+3. Bulk API (5-15MB/批)
+4. 副本数设为 0 (写完恢复)
+5. 合理 mapping (关闭 norms 等)
+
+### 查询优化
+
+- filter 优先 (可缓存, 不贡献算分)
+- 避免 script 查询
+- search_after 替代深度 from+size
+- 限制 _source 返回字段
+
+### 慢查询日志
+
+```bash
+PUT /_settings
+{
+  "index.search.slowlog.threshold.query.warn": "2s",
+  "index.search.slowlog.threshold.query.info": "500ms",
+  "index.search.slowlog.threshold.fetch.warn": "1s",
+  "index.indexing.slowlog.threshold.index.warn": "10s"
+}
+```
+
+### Profile API
+
+```bash
+GET /products/_search
+{
+  "profile": true,
+  "query": {
+    "match": { "title": "手机" }
+  }
+}
+```

skills/database-skills/elasticsearch/references/08-elk-integration.md

@@ -0,0 +1,170 @@
+# ELK Stack 集成
+
+## Elastic Stack 架构
+
+```
+Kibana (可视化/仪表盘/Dev Tools)
+    ↓
+Elasticsearch (存储/搜索/聚合)
+    ↓
+Logstash (ETL)  ←  Filebeat (日志)  ←  Metricbeat (指标)  ←  其他 Beats
+```
+
+## Logstash 配置
+
+```ruby
+# logstash.conf — 接收文件日志, 解析后写入 ES
+input {
+  beats {
+    port => 5044
+  }
+  file {
+    path => "/var/log/app/*.log"
+    start_position => "beginning"
+  }
+}
+
+filter {
+  # 解析 Nginx 日志
+  grok {
+    match => { "message" => "%{COMBINEDAPACHELOG}" }
+  }
+  # 解析 JSON 格式
+  json {
+    source => "message"
+    target => "parsed"
+    skip_on_invalid_json => true
+  }
+  # 添加时间戳
+  date {
+    match => ["timestamp", "ISO8601"]
+    target => "@timestamp"
+  }
+  # 地理 IP 解析
+  geoip {
+    source => "client_ip"
+    target => "geo"
+  }
+  # 字段处理
+  mutate {
+    remove_field => ["message", "original"]
+    convert => ["response", "integer"]
+  }
+}
+
+output {
+  elasticsearch {
+    hosts => ["localhost:9200"]
+    index => "nginx-logs-%{+YYYY.MM.dd}"
+    user => "elastic"
+    password => "${ES_PASSWORD}"
+    ssl => true
+    cacert => "/etc/elasticsearch/certs/ca.crt"
+  }
+}
+```
+
+Logstash 是 ETL 工具，适合复杂数据转换（grok/geoip/useragent）。纯日志采集场景推荐 Filebeat（更轻量）。
+
+## Filebeat 配置
+
+```yaml
+# filebeat.yml — 轻量级日志采集
+filebeat.inputs:
+  - type: log
+    enabled: true
+    paths:
+      - /var/log/nginx/access.log
+      - /var/log/nginx/error.log
+    fields:
+      service: nginx
+      env: production
+    fields_under_root: true
+
+  - type: log
+    enabled: true
+    paths:
+      - /var/log/app/*.log
+    multiline:
+      pattern: '^\d{4}-\d{2}-\d{2}'
+      negate: true
+      match: after       # 合并多行异常堆栈
+
+filebeat.config.modules:
+  path: ${path.config}/modules.d/*.yml
+  reload.enabled: true
+
+output.elasticsearch:
+  hosts: ["localhost:9200"]
+  username: "elastic"
+  password: "${ES_PASSWORD}"
+  index: "filebeat-%{[agent.version]}-%{+yyyy.MM.dd}"
+
+setup.kibana:
+  host: "localhost:5601"
+```
+
+**Filebeat 特点**：轻量级、资源占用低、支持多行合并 (Java 异常堆栈)、模块化配置。
+
+## Metricbeat 配置
+
+```yaml
+# metricbeat.yml — 系统和应用指标采集
+metricbeat.config.modules:
+  path: ${path.config}/modules.d/*.yml
+  reload.enabled: true
+
+metricbeat.modules:
+  - module: system
+    metricsets:
+      - cpu
+      - memory
+      - network
+      - diskio
+      - filesystem
+      - process
+    period: 10s
+    enabled: true
+  - module: elasticsearch
+    metricsets:
+      - node
+      - node_stats
+      - cluster_stats
+      - index
+    period: 10s
+    hosts: ["localhost:9200"]
+```
+
+## Kibana 核心功能
+
+| 功能 | 说明 |
+|------|------|
+| **Discover** | 日志搜索浏览 (KQL / Lucene 查询) |
+| **Dashboard** | 仪表盘组合多个可视化 |
+| **Visualize** | 创建图表 (柱状图/折线图/饼图/地图) |
+| **Maps** | 地理空间分析 |
+| **Canvas** | 自定义报告设计 |
+| **Machine Learning** | 异常检测/预测 |
+| **APM** | 应用性能监控 |
+| **Security** | SIEM 安全分析 |
+
+## KQL 查询语法
+
+```
+service.name: "my-app" AND http.response.status_code >= 400
+agent.hostname: "web-*" AND NOT response_time > 5s
+```
+
+## 实战: 构建 Nginx 日志分析管道
+
+1. **Filebeat** 采集 `/var/log/nginx/access.log`
+2. **Logstash** (可选) 解析日志 → grok 提取字段 + geoip 解析 IP
+3. **Elasticsearch** 存储到 `nginx-logs-YYYY.MM.dd` 索引 (ILM 管理)
+4. **Kibana** 创建 Dashboard: 请求量趋势、状态码分布、TOP URL、地理分布
+
+**完整 pipeline 参考**：
+```bash
+# 使用 Filebeat Nginx 模块 (免手动配置)
+filebeat modules enable nginx
+filebeat setup
+```

skills/database-skills/mysql/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: mysql
+description: Provides comprehensive guidance for MySQL including SQL syntax, functions, indexing, optimization, replication, backup, and high availability. Use when the user asks about MySQL, needs to write MySQL queries, design database schemas, optimize performance, or manage MySQL databases.
+license: Complete terms in LICENSE.txt
+---
+
+# MySQL — 关系型数据库管理系统
+
+MySQL 是最流行的开源关系型数据库管理系统（RDBMS），以 InnoDB 存储引擎为核心，支持 ACID 事务、外键约束和多种复制架构。
+
+## Workflow — 使用流程
+
+```
+遇到 MySQL 需求时，按以下顺序决策:
+
+1. 明确场景
+├── 建库建表 / 设计 schema?    → DDL 与数据类型参考 (references/05)
+├── 复杂查询 / 报表分析?        → DML + 聚合/窗口函数 (references/03)
+├── 性能慢 / 优化 SQL?          → 索引与执行计划 (references/06)
+├── 备份 / 恢复?                → 备份与恢复 (references/08)
+├── 主从 / 高可用?              → 复制与高可用 (references/07)
+├── 存储过程 / 分区 / 事务?     → 高级特性 (references/09)
+├── 字符串/日期/JSON 函数?       → 函数参考 (references/01-04)
+└── 实战配置 / 搭建?             → 示例 (examples/)
+
+2. 引擎选择: InnoDB (99% 场景) → MyISAM (只读归档) → MEMORY (临时表)
+3. 索引设计: 主键先 → 查询/排序/JOIN 列建索引 → 检查最左前缀
+4. 生产措施: 开启慢查询 → 配置主从复制 → 制定备份策略
+```
+
+## When to Use / When NOT to
+
+| ✅ Use When | ❌ Skip When |
+|------------|-------------|
+| 需要 ACID 事务保障的业务系统（订单、支付、账户） | 高频 KV 存取（<1ms 延迟，用 Redis） |
+| 数据结构固定、关系明确的 OLTP 场景 | 文档型非结构化数据（用 MongoDB） |
+| 需要复杂 JOIN/子查询的报表分析 | 海量日志/时序数据（用 ClickHouse） |
+| 中小规模到中大规模 OLTP（百万~亿级） | 超大规模分布式事务（用 TiDB） |
+| 主从复制读写分离架构 | 图关系数据（用 Neo4j） |
+| 需要丰富内置函数和存储过程 | 全文搜索引擎为主（用 Elasticsearch） |
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用（替代方案） |
+|-----------|--------------|------------------|
+| OLTP 业务系统 | 单表过亿行（需分库分表） | 纯内存缓存 → Redis |
+| ACID 事务一致性 | 跨分片分布式事务（XA/Seata） | 文档存储 → MongoDB |
+| 复杂 SQL（JOIN/子查询/聚合） | 实时流计算（MySQL + Flink） | 全文搜索 → Elasticsearch |
+| 主从复制读写分离 | 强一致多主写入（Galera/PXC） | 时序大数据 → ClickHouse |
+| mysqldump/XtraBackup 备份 | JSON 深度查询（不如 MongoDB） | 分布式强一致 → TiDB |
+| 分区表（RANGE/LIST/HASH） | 高并发写入 > 1万 TPS | 图数据库 → Neo4j |
+
+## SQL 语法速查
+
+| 类别 | 核心语法 | 详情参考 |
+|------|---------|---------|
+| DDL | `CREATE/ALTER/DROP TABLE`，数据类型、约束 | references/05-sql-ddl-types.md |
+| DML | `INSERT/UPDATE/DELETE`，`ON DUPLICATE KEY UPDATE` | 同上 |
+| DQL | `SELECT/JOIN/GROUP BY/HAVING/UNION`，CTE，子查询 | references/03, 09 |
+| 事务 | `START TRANSACTION/COMMIT/ROLLBACK/SAVEPOINT` | references/09-advanced-features.md |
+| 分页 | `LIMIT/OFFSET`（小表），`WHERE id > :last` 游标（大表） | references/06-index-optimization.md |
+
+## 函数速查
+
+| 类别 | 最常用函数 | 详情参考 |
+|------|-----------|---------|
+| 字符串 | `CONCAT, SUBSTRING, REPLACE, LPAD, GROUP_CONCAT, LENGTH` | references/01-functions-string.md |
+| 日期时间 | `NOW, DATE_FORMAT, DATEDIFF, DATE_ADD, TIMESTAMPDIFF` | references/02-functions-date.md |
+| 聚合 | `COUNT, SUM, AVG, MAX, MIN, GROUP_CONCAT` | references/03-functions-aggregate-window.md |
+| 窗口 (8.0+) | `ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, NTILE` | references/03-functions-aggregate-window.md |
+| JSON (5.7+) | `JSON_EXTRACT, JSON_SET, JSON_CONTAINS, JSON_TABLE` | references/04-functions-json.md |
+| 条件 | `IF, IFNULL, COALESCE, CASE WHEN` | references/05-sql-ddl-types.md |
+
+## 高级特性索引
+
+| 特性 | 简介 | 参考 |
+|------|------|------|
+| 视图 (View) | 存储的查询定义，简化复杂查询和权限控制 | references/09-advanced-features.md |
+| CTE (8.0+) | 命名临时结果集，支持递归树形查询 | 同上 |
+| 存储过程 | 封装多条 SQL 带事务控制的业务逻辑 | 同上 |
+| 触发器 | 自动响应 INSERT/UPDATE/DELETE 的事件处理 | 同上 |
+| 事务与锁 | ACID、MVCC、四种隔离级别、行锁/表锁/死锁 | 同上 |
+| 分区表 | RANGE/LIST/HASH/KEY 分区，数据归档加速 | 同上 |
+| 全文索引 (5.6+) | FULLTEXT + MATCH AGAINST 代替 LIKE 搜索 | references/06-index-optimization.md |
+| 函数索引 (8.0.13+) | 对表达式/函数结果建索引 | 同上 |
+| 降序索引 (8.0+) | 混合排序方向的索引优化 | 同上 |
+| 主从复制 | Binlog + Relay Log 实现数据同步 | references/07-replication-ha.md |
+| 半同步复制 | 至少一个 Slave 确认，平衡性能与一致性 | 同上 |
+| InnoDB Cluster | Group Replication + MySQL Router 原生 HA | 同上 |
+| XtraBackup | 物理热备份，支持增量 | references/08-backup-restore.md |
+| PITR | 利用 Binlog 实现时间点恢复 | 同上 |
+
+## 引擎对比
+
+| 特性 | InnoDB | MyISAM | MEMORY |
+|------|--------|--------|--------|
+| 事务 | ✅ ACID | ❌ | ❌ |
+| 外键 | ✅ | ❌ | ❌ |
+| 行级锁 | ✅ 行锁 | ❌ 表锁 | ❌ 表锁 |
+| MVCC | ✅ | ❌ | ❌ |
+| 崩溃恢复 | ✅ redo log | ❌ 需 REPAIR TABLE | ❌ 重启即丢 |
+| 全文索引 | ✅ 5.6+ | ✅ | ❌ |
+| 缓存 | Buffer Pool（数据和索引） | Key Cache（仅索引） | 全内存 |
+| 适用场景 | 99% 场景默认首选 | 只读归档（极少用） | 临时表 |
+| 表大小限制 | 64TB | 256TB | max_heap_table_size |
+
+## Gotchas — 常见陷阱
+
+| # | 反模式 | 问题 | 正确做法 |
+|---|--------|------|---------|
+| 1 | 金额用 FLOAT/DOUBLE | 浮点精度误差 | 用 `DECIMAL(10,2)` |
+| 2 | WHERE 列用函数/隐式转换 | 索引失效，全表扫描 | 避免函数操作列，类型匹配 |
+| 3 | 大批量分页用 OFFSET | OFFSET 越深越慢 | 游标分页 `WHERE id > :last` |
+| 4 | 全表无主键 | 无法行级锁，复制延迟 | 每个表必须有 BIGINT 主键 |
+| 5 | SELECT * 生产使用 | 浪费带宽，无法覆盖索引 | 显式列出需要列 |
+| 6 | 大字段无前缀索引 | 索引过大，B+ 树效率低 | 前缀索引 `col(N)` |
+| 7 | 长事务不提交 | undo log 膨胀，MVCC 开销 | 控制事务大小，及时 COMMIT |
+| 8 | 索引过多 | 写入性能降低 | 单表索引 ≤ 5-8 个 |
+| 9 | COUNT(*) InnoDB 大表 | 需要扫描全表（MyISAM 才缓存） | 用近似值或计数表 |
+| 10 | LIKE '%keyword%' 搜索 | 无法用索引 | FULLTEXT + MATCH AGAINST |
+| 11 | NOT IN (子查询) | 不做半连接优化 | 用 NOT EXISTS |
+| 12 | 字符集混用 | 乱码、索引隐性转换 | 统一 utf8mb4 |
+| 13 | TEXT/BLOB 过多 | 行溢出，性能差 | 拆分到子表或 OSS |
+| 14 | REPLACE 常见误解 | 实际是 DELETE+INSERT | 明确需求后用 ON DUPLICATE KEY UPDATE |
+| 15 | 不做备份验证 | 备份损坏但无人知 | 每月定期恢复演练 |
+
+## FAQ
+
+| # | 问题 | 答案 |
+|---|------|------|
+| 1 | 如何选择 DATETIME 还是 TIMESTAMP？ | TIMESTAMP 自动时区转换（范围 1970-2038），DATETIME 无时区影响（范围 1000-9999） |
+| 2 | VARCHAR 最大长度设多少合适？ | 根据业务设合理值（50-200），不要无意义设 255（临时表排序按定义长度分配内存） |
+| 3 | 如何快速插入百万级数据？ | `LOAD DATA INFILE` (最快)，或批量 INSERT（每批 500-1000 行），关闭 AUTOCOMMIT |
+| 4 | 什么时候需要分库分表？ | 单表 > 5000 万行或单实例 > 2TB 且预期继续增长 |
+| 5 | MySQL 8.0 vs 5.7 选哪个？ | 新项目选 8.0（窗口函数、CTE、降序索引、原子 DDL、Hash Join） |
+| 6 | 如何监控 MySQL 性能？ | 慢查询日志 + pt-query-digest + Prometheus + Grafana + performance_schema |
+| 7 | 主从延迟怎么处理？ | 检查 Slave 硬件、拆分大事务、开启并行复制、关键读走主库 |
+| 8 | 误操作删除了数据怎么办？ | 立即停止写入 → 用 Binlog PITR 恢复到误操作前的时间点 |
+| 9 | InnoDB 为什么比 MyISAM 好？ | 事务、行锁、崩溃恢复、MVCC、外键。MyISAM 已过时 |
+| 10 | 如何查看当前数据库的活跃连接？ | `SHOW PROCESSLIST;` 或 `SELECT * FROM sys.session;` |
+| 11 | 如何安全地在大表上添加索引？ | MySQL 8.0 用 `ALGORITHM=INPLACE, LOCK=NONE`；或用 pt-online-schema-change |
+| 12 | 唯一索引和普通索引怎么选？ | 需要唯一约束用 UNIQUE；只需加速查询用普通索引 |
+| 13 | 有哪些推荐的管理工具？ | CLI: mysql CLI；GUI: Sequel Ace / DataGrip / Navicat；命令行: Percona Toolkit |
+| 14 | utf8mb4 和 utf8 有什么区别？ | utf8 是 utf8mb3（最多 3 字节），不支持 emoji；utf8mb4 支持完整的 Unicode（含 emoji）|
+| 15 | 如何排查死锁？ | `SHOW ENGINE INNODB STATUS;` 查看 LATEST DETECTED DEADLOCK 部分 |
+
+## Keywords
+
+MySQL, Database, RDBMS, SQL, DDL, DML, DQL, DCL, InnoDB, MyISAM, MEMORY, ACID, transaction, index, B-Tree, EXPLAIN, query optimization, replication, master-slave, binlog, backup, restore, XtraBackup, mysqldump, PITR, partition, view, stored procedure, trigger, CTE, window function, JSON, utf8mb4, performance_schema, slow query, connection pool, sharding, high availability, HA
+
+## References
+
+### 官方文档
+- [MySQL 8.0 Reference Manual](https://dev.mysql.com/doc/refman/8.0/en/)
+- [MySQL 8.0 Release Notes](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/)
+
+### 工具
+- [Percona XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup)
+- [Percona Toolkit](https://www.percona.com/software/database-tools/percona-toolkit)
+- [Orchestrator](https://github.com/openark/orchestrator) — MySQL 高可用管理
+- [gh-ost](https://github.com/github/gh-ost) — 在线表结构变更
+
+### 本 skill 深度参考
+- references/01-functions-string.md — 字符串函数大全
+- references/02-functions-date.md — 日期时间函数大全
+- references/03-functions-aggregate-window.md — 聚合与窗口函数
+- references/04-functions-json.md — JSON 函数
+- references/05-sql-ddl-types.md — DDL 与数据类型详解
+- references/06-index-optimization.md — 索引与执行计划
+- references/07-replication-ha.md — 主从复制与高可用
+- references/08-backup-restore.md — 备份与恢复
+- references/09-advanced-features.md — 高级特性（视图/CTE/存储过程/触发器/事务/分区）
+
+### 实战示例
+- examples/01-connection-pool.md — 连接池配置
+- examples/02-slow-query-optimization.md — 慢查询优化
+- examples/03-master-slave-setup.md — 主从复制搭建
+- examples/04-backup-strategy.md — 备份策略方案

skills/database-skills/mysql/examples/01-connection-pool.md

@@ -0,0 +1,75 @@
+# 示例: 连接池配置 (Java HikariCP)
+
+## 场景
+
+生产环境高并发 Web 应用中，合理配置数据库连接池是保证性能的关键。本例展示 HikariCP（Spring Boot 默认连接池）的最佳实践配置。
+
+## 问题
+
+- 连接数太少 → 请求排队等待，响应变慢
+- 连接数太多 → MySQL 连接数耗尽（`max_connections`），系统崩溃
+- 连接泄漏 → 连接未正确归还，池逐渐耗尽
+
+## 解决方案
+
+### application.yml 配置
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:mysql://localhost:3306/shop?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8mb4
+    username: root
+    password: your_password
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    hikari:
+      # 核心配置
+      maximum-pool-size: 20           # 最大连接数（核心参数）
+      minimum-idle: 5                 # 最小空闲连接数
+      connection-timeout: 30000       # 等待连接超时（毫秒）
+      idle-timeout: 600000            # 空闲连接最大存活（毫秒，10min）
+      max-lifetime: 1800000           # 连接最大寿命（毫秒，30min）
+      
+      # MySQL 专用优化
+      auto-commit: true
+      connection-test-query: SELECT 1
+      pool-name: ShopHikariPool
+      
+      # 性能监控
+      register-mbeans: true           # 开启 JMX 监控
+```
+
+### 常用计算公式
+
+```
+最大连接数 = ((核心数 * 2) + 有效磁盘数)
+
+示例:
+- 4 核 CPU + 1 SSD → (4 * 2) + 1 = 9
+- 8 核 CPU + 1 SSD → (8 * 2) + 1 = 17
+
+通用建议:
+- 微服务低并发场景: 5-10
+- Web 应用中并发场景: 15-30
+- 高并发场景: 分库后每个库 20-50
+
+注意: 不是越大越好。连接池大小 × 并发请求数 = MySQL 实际并发连接。
+举例: 10 个实例 × 每个 20 连接 = 200 个 MySQL 连接。
+```
+
+### 验证配置
+
+```sql
+-- 查看实际连接数
+SHOW STATUS LIKE 'Threads_connected';
+SHOW STATUS LIKE 'Max_used_connections';
+
+-- 查看连接来源
+SELECT * FROM information_schema.processlist;
+```
+
+## 关键要点
+
+1. **连接池大小不是越大越好**：过多的连接会导致 MySQL 上下文切换开销和锁争用
+2. **max-lifetime 应小于 MySQL 的 wait_timeout**（通常 28800s），避免连接被 MySQL 断开后还留在池中
+3. **connection-test-query** 用于心跳检测，`SELECT 1` 性能最好
+4. 建议配合 `spring.datasource.hikari.leak-detection-threshold` 检测连接泄漏

skills/database-skills/mysql/examples/02-slow-query-optimization.md

@@ -0,0 +1,98 @@
+# 示例: 慢查询优化实战
+
+## 场景
+
+电商系统中查询"最近一个月下单超过 5 次的 VIP 用户及其总消费金额"的报表越来越慢。
+
+## 原始查询
+
+```sql
+SELECT 
+  u.id, u.name, u.email,
+  COUNT(o.id) AS order_count,
+  SUM(o.amount) AS total_amount
+FROM user u
+LEFT JOIN `order` o ON u.id = o.user_id
+WHERE u.level = 'vip' 
+  AND o.created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
+GROUP BY u.id, u.name, u.email
+HAVING order_count > 5
+ORDER BY total_amount DESC
+LIMIT 100;
+```
+
+执行时间：**12.3s**（`EXPLAIN` 显示全表扫 user 和 order）
+
+## 分析过程
+
+### Step 1: EXPLAIN 分析
+
+```sql
+EXPLAIN FORMAT=JSON
+SELECT 
+  u.id, u.name, u.email,
+  COUNT(o.id) AS order_count,
+  SUM(o.amount) AS total_amount
+FROM user u
+LEFT JOIN `order` o ON u.id = o.user_id
+WHERE u.level = 'vip' 
+  AND o.created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
+GROUP BY u.id, u.name, u.email
+HAVING order_count > 5
+ORDER BY total_amount DESC
+LIMIT 100;
+```
+
+**发现的问题**：
+1. `u.level` 没有索引 → type: ALL，全表扫描 50 万用户
+2. `o.created_at` 没有索引 → type: ALL，全表扫描 500 万订单
+3. `GROUP BY` 和 `ORDER BY` 没有索引覆盖 → Using temporary; Using filesort
+
+### Step 2: 添加索引
+
+```sql
+-- 1. user 表的 level 查询索引
+ALTER TABLE user ADD INDEX idx_level (level);
+
+-- 2. order 表的复合索引（user_id 用于 JOIN，created_at 用于时间过滤）
+ALTER TABLE `order` ADD INDEX idx_user_created (user_id, created_at);
+
+-- 3. 覆盖索引（减少回表）
+ALTER TABLE `order` ADD INDEX idx_user_created_amount (user_id, created_at, amount);
+```
+
+### Step 3: 优化后 EXPLAIN
+
+- `user` 表：type: ref（`idx_level`），rows: 5000（从 50 万降到 5000）
+- `order` 表：type: ref（`idx_user_created`），rows: 每用户约 10 行
+- Extra: 不再有 Using temporary; Using filesort
+
+## 优化后结果
+
+```sql
+-- 优化后查询
+SELECT 
+  u.id, u.name, u.email,
+  COUNT(o.id) AS order_count,
+  SUM(o.amount) AS total_amount
+FROM user u
+INNER JOIN `order` o ON u.id = o.user_id
+WHERE u.level = 'vip' 
+  AND o.created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
+GROUP BY u.id
+HAVING order_count > 5
+ORDER BY total_amount DESC
+LIMIT 100;
+```
+
+执行时间：**12.3s → 0.08s**（提升约 150 倍）
+
+## 优化要点总结
+
+| 优化项 | 优化前 | 优化后 | 效果 |
+|--------|--------|--------|------|
+| `level` 索引 | ALL（50万行） | ref（5000行） | 减少 99% 扫描 |
+| `(user_id, created_at)` 复合索引 | ALL（500万行） | ref（平均10行/用户） | 减少 99.99% |
+| `LEFT JOIN` 改为 `INNER JOIN` | 含无订单用户 | 仅含订单用户 | 减少数据处理量 |
+| `GROUP BY u.id`（简化列） | 3 列分组 | 1 列分组（id 唯一） | 减少临时表开销 |
+| 数据范围 | 全表扫描 | 索引范围扫描 | 大幅提高 |

skills/database-skills/mysql/examples/03-master-slave-setup.md

@@ -0,0 +1,144 @@
+# 示例: 主从复制搭建
+
+## 场景
+
+为电商平台搭建一主一从架构，实现读写分离和基本高可用。主库处理 DML（写），从库处理 SELECT（读）。
+
+## 环境
+
+- Master: 192.168.1.100:3306
+- Slave: 192.168.1.101:3306
+- MySQL 8.0.x
+
+## 步骤
+
+### Step 1: Master 配置
+
+编辑 `/etc/my.cnf`：
+
+```ini
+[mysqld]
+server-id = 1
+log_bin = /var/log/mysql/mysql-bin
+binlog_format = ROW
+binlog_expire_logs_seconds = 604800
+sync_binlog = 1
+innodb_flush_log_at_trx_commit = 1
+```
+
+重启 MySQL：`systemctl restart mysqld`
+
+### Step 2: Master 创建复制用户
+
+```sql
+CREATE USER 'replicator'@'192.168.1.101' IDENTIFIED BY 'StrongPassword123!';
+GRANT REPLICATION SLAVE ON *.* TO 'replicator'@'192.168.1.101';
+FLUSH PRIVILEGES;
+```
+
+### Step 3: 记录 Master 二进制日志位置
+
+```sql
+FLUSH TABLES WITH READ LOCK;  -- 锁住所有表
+SHOW MASTER STATUS;
+-- 输出:
+-- File: mysql-bin.000042
+-- Position: 841236
+```
+
+> **注意**：新开一个终端会话执行 `SHOW MASTER STATUS`，不要在锁会话中执行，否则锁会一直持有。
+
+### Step 4: 初始数据同步
+
+```bash
+# 在 Master 上导出数据
+mysqldump -u root -p --all-databases --single-transaction --master-data=2 > /tmp/mysql_full.sql
+
+# 复制到 Slave
+scp /tmp/mysql_full.sql root@192.168.1.101:/tmp/
+
+# 解锁 Master
+UNLOCK TABLES;
+```
+
+### Step 5: Slave 配置
+
+编辑 `/etc/my.cnf`：
+
+```ini
+[mysqld]
+server-id = 2
+relay_log = /var/log/mysql/mysql-relay-bin
+read_only = 1
+log_slave_updates = 0          # 可选：记录从库更新到 binlog
+skip_slave_start = 1           # 防止自动启动复制
+```
+
+重启 MySQL：`systemctl restart mysqld`
+
+### Step 6: Slave 恢复初始数据
+
+```bash
+mysql -u root -p < /tmp/mysql_full.sql
+```
+
+### Step 7: 配置复制
+
+```sql
+CHANGE MASTER TO
+  MASTER_HOST = '192.168.1.100',
+  MASTER_PORT = 3306,
+  MASTER_USER = 'replicator',
+  MASTER_PASSWORD = 'StrongPassword123!',
+  MASTER_LOG_FILE = 'mysql-bin.000042',
+  MASTER_LOG_POS = 841236;
+
+START SLAVE;
+```
+
+### Step 8: 验证复制
+
+```sql
+SHOW SLAVE STATUS\G
+-- Slave_IO_Running: Yes
+-- Slave_SQL_Running: Yes
+-- Seconds_Behind_Master: 0
+```
+
+### Step 9: 测试
+
+```sql
+-- Master 上插入测试数据
+INSERT INTO test.replication_test VALUES (1, 'hello');
+
+-- Slave 上验证
+SELECT * FROM test.replication_test;  -- 应该看到数据
+```
+
+## 验证脚本
+
+```bash
+#!/bin/bash
+# check_replication.sh
+
+IO_STATUS=$(mysql -e "SHOW SLAVE STATUS\G" | grep "Slave_IO_Running" | awk '{print $2}')
+SQL_STATUS=$(mysql -e "SHOW SLAVE STATUS\G" | grep "Slave_SQL_Running" | awk '{print $2}')
+LAG=$(mysql -e "SHOW SLAVE STATUS\G" | grep "Seconds_Behind_Master" | awk '{print $2}')
+
+if [ "$IO_STATUS" = "Yes" ] && [ "$SQL_STATUS" = "Yes" ]; then
+    echo "Replication OK. Lag: ${LAG}s"
+    exit 0
+else
+    echo "Replication ERROR!"
+    exit 1
+fi
+```
+
+## 常见问题排查
+
+| 问题 | 检查 | 解决方案 |
+|------|------|---------|
+| Slave_IO_Running: Connecting | 网络连通性 | `ping 192.168.1.100`，检查防火墙 3306 |
+| Slave_IO_Running: No | 复制用户权限 | 检查 MASTER_USER/MASTER_PASSWORD |
+| 主键冲突 | 初始数据不一致 | `SET GLOBAL sql_slave_skip_counter = 1;` |
+| 复制延迟高 | Slave 性能 | 升级硬件、开启并行复制 |

skills/database-skills/mysql/examples/04-backup-strategy.md

@@ -0,0 +1,212 @@
+# 示例: 生产环境备份策略
+
+## 场景
+
+日活 10 万用户的电商平台，MySQL 总数据量约 200GB，需要 24×7 运行，无法接受超过 30 分钟的数据丢失。
+
+## 备份策略
+
+```
+全量备份:    每天 02:00 (XtraBackup 物理备份)
+增量备份:    每 6 小时 (XtraBackup 增量)
+二进制日志:  实时归档 (自动备份到 S3)
+保留周期:    7 天全量 + 30 天增量 + 90 天 Binlog
+异地备份:    同步到阿里云 OSS (跨区域复制)
+恢复演练:    每月一次
+```
+
+## 备份脚本
+
+### 全量备份脚本
+
+```bash
+#!/bin/bash
+# /usr/local/bin/backup_full.sh
+
+BACKUP_DIR="/data/backup/mysql"
+DATE=$(date +%Y%m%d_%H%M%S)
+FULL_DIR="${BACKUP_DIR}/full/${DATE}"
+MYSQL_USER="backup_user"
+MYSQL_PASS="$(cat /etc/mysql/backup_pass)"
+
+# 创建备份目录
+mkdir -p ${FULL_DIR}
+
+# 执行 XtraBackup 全量备份
+xtrabackup --backup \
+  --user=${MYSQL_USER} \
+  --password=${MYSQL_PASS} \
+  --target-dir=${FULL_DIR} \
+  --compress \
+  --compress-threads=4 \
+  --parallel=4 2>>/var/log/xtrabackup.log
+
+if [ $? -eq 0 ]; then
+  echo "[$(date)] Full backup completed: ${FULL_DIR}" >> /var/log/backup.log
+  
+  # 同步到 OSS
+  ossutil sync ${FULL_DIR} oss://myapp-backup/mysql/full/${DATE}/ \
+    --delete --force 2>>/var/log/oss_backup.log
+    
+  # 清理 7 天前的全量备份
+  find ${BACKUP_DIR}/full/ -type d -mtime +7 -exec rm -rf {} \;
+  echo "[$(date)] Full backup synced to OSS" >> /var/log/backup.log
+else
+  echo "[$(date)] Full backup FAILED!" >> /var/log/backup.log
+  curl -X POST -H "Content-Type: application/json" \
+    -d '{"msg":"MySQL 全量备份失败"}' \
+    https://alert.example.com/notify
+fi
+```
+
+### 增量备份脚本
+
+```bash
+#!/bin/bash
+# /usr/local/bin/backup_inc.sh
+
+BACKUP_DIR="/data/backup/mysql"
+DATE=$(date +%Y%m%d_%H%M%S)
+INC_DIR="${BACKUP_DIR}/inc/${DATE}"
+MYSQL_USER="backup_user"
+MYSQL_PASS="$(cat /etc/mysql/backup_pass)"
+LATEST_FULL=$(ls -td ${BACKUP_DIR}/full/*/ | head -1)
+
+# 找最近的备份作为增量基准备份
+if [ -z "$(ls -A ${BACKUP_DIR}/inc/ 2>/dev/null)" ]; then
+  BASEDIR="${LATEST_FULL}"
+else
+  BASEDIR=$(ls -td ${BACKUP_DIR}/inc/*/ | head -1)
+fi
+
+mkdir -p ${INC_DIR}
+
+xtrabackup --backup \
+  --user=${MYSQL_USER} \
+  --password=${MYSQL_PASS} \
+  --target-dir=${INC_DIR} \
+  --incremental-basedir=${BASEDIR} \
+  --compress \
+  --compress-threads=4 \
+  --parallel=4 2>>/var/log/xtrabackup.log
+
+if [ $? -eq 0 ]; then
+  echo "[$(date)] Incremental backup completed" >> /var/log/backup.log
+  ossutil sync ${INC_DIR} oss://myapp-backup/mysql/inc/${DATE}/ \
+    --delete --force 2>>/var/log/oss_backup.log
+  find ${BACKUP_DIR}/inc/ -type d -mtime +30 -exec rm -rf {} \;
+else
+  echo "[$(date)] Incremental backup FAILED!" >> /var/log/backup.log
+  curl -X POST -H "Content-Type: application/json" \
+    -d '{"msg":"MySQL 增量备份失败"}' \
+    https://alert.example.com/notify
+fi
+```
+
+### Binlog 实时归档
+
+```bash
+#!/bin/bash
+# /usr/local/bin/archive_binlog.sh
+
+BINLOG_DIR="/var/log/mysql"
+ARCHIVE_DIR="/data/backup/binlog"
+FILES=($(ls -1t ${BINLOG_DIR}/mysql-bin.* 2>/dev/null))
+
+# 排除当前正在使用的 binlog
+CURRENT=$(mysql -e "SHOW MASTER STATUS\G" | grep File | awk '{print $2}')
+for FILE in "${FILES[@]}"; do
+  BASENAME=$(basename $FILE)
+  if [ "$BASENAME" != "$CURRENT" ] && [ ! -f "${ARCHIVE_DIR}/${BASENAME}.gz" ]; then
+    gzip -c $FILE > ${ARCHIVE_DIR}/${BASENAME}.gz
+    ossutil cp ${ARCHIVE_DIR}/${BASENAME}.gz oss://myapp-backup/binlog/
+    echo "[$(date)] Archived: ${BASENAME}" >> /var/log/binlog_archive.log
+    
+    # 删除本地归档后的 binlog 释放空间
+    mysql -e "PURGE BINARY LOGS BEFORE DATE_SUB(NOW(), INTERVAL 7 DAY);"
+  fi
+done
+```
+
+## 恢复流程
+
+### 完整恢复步骤
+
+```bash
+#!/bin/bash
+# /usr/local/bin/restore_mysql.sh
+
+RESTORE_DATE=$1  # 格式: 2024-03-15 10:30:00
+
+# 1. 从 OSS 下载最近的全量备份
+ossutil cp -r oss://myapp-backup/mysql/full/latest/ /tmp/restore/full/
+echo "Step 1: Full backup downloaded"
+
+# 2. 准备全量备份
+xtrabackup --prepare --target-dir=/tmp/restore/full/ --apply-log-only
+echo "Step 2: Full backup prepared"
+
+# 3. 按需合并增量备份
+for inc in $(ossutil ls oss://myapp-backup/mysql/inc/ | sort); do
+  ossutil cp -r $inc /tmp/restore/inc/
+  xtrabackup --prepare --target-dir=/tmp/restore/full/ \
+    --incremental-dir=/tmp/restore/inc/ --apply-log-only
+  echo "Step 3: Incremental ${inc} merged"
+done
+
+# 4. 最终准备（非 apply-log-only，回滚未提交事务）
+xtrabackup --prepare --target-dir=/tmp/restore/full/
+echo "Step 4: Final prepare done"
+
+# 5. 停止 MySQL，替换数据目录
+systemctl stop mysqld
+mv /var/lib/mysql /var/lib/mysql_bak
+xtrabackup --copy-back --target-dir=/tmp/restore/full/
+chown -R mysql:mysql /var/lib/mysql
+echo "Step 5: Data restored"
+
+# 6. 启动 MySQL
+systemctl start mysqld
+echo "Step 6: MySQL started"
+
+# 7. 回放 Binlog 到指定时间点（PITR）
+mysqlbinlog --stop-datetime="${RESTORE_DATE}" \
+  /data/backup/binlog/mysql-bin.* | mysql -u root -p
+echo "Step 7: PITR applied to ${RESTORE_DATE}"
+```
+
+## 定时作业配置
+
+```bash
+# crontab -e
+
+# 每天 02:00 全量备份
+0 2 * * * /usr/local/bin/backup_full.sh
+
+# 每 6 小时增量备份
+0 */6 * * * /usr/local/bin/backup_inc.sh
+
+# 每小时检查并归档 binlog
+0 * * * * /usr/local/bin/archive_binlog.sh
+
+# 每天 06:00 检查备份完整性
+0 6 * * * /usr/local/bin/check_backup.sh
+```
+
+## 恢复演练计划
+
+```
+每月第一周周日凌晨 2:00 执行：
+
+1. 在测试环境恢复最近的全量备份
+2. 应用增量备份
+3. 执行 PITR 到指定时间点
+4. 验证数据完整性：
+   - 检查关键表行数
+   - 验证最近订单数据
+   - 运行业务自检脚本
+5. 记录恢复耗时，持续优化
+
+目标 RTO: < 2 小时
+目标 RPO: < 30 分钟
+```

skills/database-skills/mysql/references/01-functions-string.md

@@ -0,0 +1,103 @@
+# 字符串函数 (String Functions)
+
+## 简介
+
+MySQL 提供丰富的字符串处理函数，用于字符串拼接、截取、替换、格式化等操作。这些函数在数据清洗、脱敏、报表生成中广泛使用。
+
+## 常用函数速查
+
+### 拼接与格式化
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `CONCAT(s1, s2, ...)` | 字符串拼接 | `CONCAT(first_name, ' ', last_name)` | 'John Doe' |
+| `CONCAT_WS(sep, s1, s2)` | 带分隔符拼接 | `CONCAT_WS('-', '2024', '01', '15')` | '2024-01-15' |
+| `GROUP_CONCAT(col)` | 分组拼接 | `GROUP_CONCAT(name ORDER BY id SEPARATOR ',')` | 'a,b,c' |
+| `FORMAT(x, d)` | 千分位格式化 | `FORMAT(12345.67, 2)` | '12,345.67' |
+| `LPAD(s, n, pad)` | 左填充 | `LPAD('7', 3, '0')` | '007' |
+| `RPAD(s, n, pad)` | 右填充 | `RPAD('7', 3, '0')` | '700' |
+
+### 截取与定位
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `SUBSTRING(s, pos, len)` | 子串 | `SUBSTRING('Hello World', 1, 5)` | 'Hello' |
+| `LEFT(s, n)` | 左截取 | `LEFT('abcde', 3)` | 'abc' |
+| `RIGHT(s, n)` | 右截取 | `RIGHT('abcde', 2)` | 'de' |
+| `LOCATE(sub, s, pos)` | 子串位置 | `LOCATE('is', 'this is test')` | 3 |
+| `INSTR(s, sub)` | 子串位置 | `INSTR('this is test', 'is')` | 3 |
+| `SUBSTRING_INDEX(s, delim, n)` | 按分隔符截取 | `SUBSTRING_INDEX('a,b,c', ',', 2)` | 'a,b' |
+
+### 替换与转换
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `REPLACE(s, from, to)` | 替换 | `REPLACE('abc123', '123', '456')` | 'abc456' |
+| `INSERT(s, pos, len, new)` | 插入替换 | `INSERT('phone', 2, 4, '****')` | 'p****e' |
+| `UPPER(s)` / `LOWER(s)` | 大小写转换 | `UPPER('abc')` | 'ABC' |
+| `TRIM(s)` | 去首尾空格 | `TRIM(' abc ')` | 'abc' |
+| `LTRIM(s)` / `RTRIM(s)` | 去左/右空格 | `LTRIM(' abc')` | 'abc' |
+| `REVERSE(s)` | 逆序 | `REVERSE('abc')` | 'cba' |
+| `REPEAT(s, n)` | 重复 | `REPEAT('x', 5)` | 'xxxxx' |
+
+### 长度与校验
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `LENGTH(s)` | 字节长度 | `LENGTH('你好')` | 6 (utf8mb4) |
+| `CHAR_LENGTH(s)` | 字符长度 | `CHAR_LENGTH('你好')` | 2 |
+| `BIT_LENGTH(s)` | 位长度 | `BIT_LENGTH('A')` | 8 |
+| `ORD(s)` | 首字符 ASCII | `ORD('A')` | 65 |
+| `ASCII(s)` | 首字符 ASCII | `ASCII('A')` | 65 |
+
+## 业务场景
+
+### 场景 1: 手机号脱敏
+
+```sql
+SELECT 
+  REPLACE(phone, SUBSTRING(phone, 4, 4), '****') AS masked_phone 
+FROM user;
+-- 138****0000
+
+-- 更推荐的做法（INSERT 函数）
+SELECT INSERT(phone, 4, 4, '****') AS masked_phone FROM user;
+```
+
+### 场景 2: 商品编号补零
+
+```sql
+SELECT CONCAT('PRD', LPAD(id, 5, '0')) AS product_no FROM product;
+-- PRD00001, PRD00002, ...
+```
+
+### 场景 3: 统计每个用户的所有订单号
+
+```sql
+SELECT user_id, 
+  GROUP_CONCAT(order_no ORDER BY created_at SEPARATOR ', ') AS order_list
+FROM `order`
+GROUP BY user_id;
+```
+
+### 场景 4: 检查邮箱格式
+
+```sql
+SELECT * FROM user WHERE LOCATE('@', email) = 0;
+```
+
+### 场景 5: JSON 字符串提取（旧版本兼容）
+
+```sql
+-- 在 MySQL 5.7 之前，JSON 字段用字符串存储时的提取方式
+SELECT 
+  SUBSTRING_INDEX(SUBSTRING_INDEX(attrs, '"color":"', -1), '"', 2) AS color
+FROM product;
+```
+
+## 注意事项
+
+- `LENGTH()` 返回**字节数**而非字符数，对于多字节字符集（utf8mb4）一个中文字符占 3-4 字节
+- `CHAR_LENGTH()` 返回**字符数**，处理中文时使用此函数
+- `GROUP_CONCAT` 的结果长度受 `group_concat_max_len` 限制（默认 1024）
+- MySQL 字符串索引默认从 **1** 开始（非 0）

skills/database-skills/mysql/references/02-functions-date.md

@@ -0,0 +1,152 @@
+# 日期时间函数 (Date & Time Functions)
+
+## 简介
+
+MySQL 的日期时间函数用于获取当前时间、提取日期组件、格式化和计算日期差。在报表统计、时间范围查询、过期计算等场景中高频使用。
+
+## 常用函数速查
+
+### 获取当前日期时间
+
+| 函数 | 说明 | 示例结果 |
+|------|------|---------|
+| `NOW()` | 当前日期时间 | '2024-03-15 14:30:00' |
+| `CURDATE()` | 当前日期 | '2024-03-15' |
+| `CURTIME()` | 当前时间 | '14:30:00' |
+| `UTC_DATE()` | UTC 当前日期 | '2024-03-15' |
+| `UTC_TIME()` | UTC 当前时间 | '06:30:00' |
+| `UTC_TIMESTAMP()` | UTC 当前日期时间 | '2024-03-15 06:30:00' |
+| `SYSDATE()` | 函数执行时的当前时间（非语句开始时间） | '2024-03-15 14:30:01' |
+| `CURRENT_TIMESTAMP` | NOW() 的同义词 | '2024-03-15 14:30:00' |
+
+### 提取日期/时间组件
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `DATE(expr)` | 提取日期部分 | `DATE(NOW())` | '2024-03-15' |
+| `TIME(expr)` | 提取时间部分 | `TIME(NOW())` | '14:30:00' |
+| `YEAR(date)` | 提取年 | `YEAR('2024-03-15')` | 2024 |
+| `MONTH(date)` | 提取月 | `MONTH('2024-03-15')` | 3 |
+| `DAY(date)` | 提取日 | `DAY('2024-03-15')` | 15 |
+| `HOUR(time)` | 提取时 | `HOUR('14:30:00')` | 14 |
+| `MINUTE(time)` | 提取分 | `MINUTE('14:30:00')` | 30 |
+| `SECOND(time)` | 提取秒 | `SECOND('14:30:00')` | 0 |
+| `EXTRACT(unit FROM date)` | 提取任意部分 | `EXTRACT(MONTH FROM '2024-03-15')` | 3 |
+
+### 日期运算
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `DATE_ADD(date, INTERVAL expr unit)` | 日期加法 | `DATE_ADD(NOW(), INTERVAL 7 DAY)` | 7 天后 |
+| `DATE_SUB(date, INTERVAL expr unit)` | 日期减法 | `DATE_SUB(NOW(), INTERVAL 1 MONTH)` | 上月同日 |
+| `DATEDIFF(d1, d2)` | 日期差（天） | `DATEDIFF('2024-03-20', '2024-03-15')` | 5 |
+| `TIMESTAMPDIFF(unit, d1, d2)` | 灵活时间差 | `TIMESTAMPDIFF(HOUR, '2024-01-01', NOW())` | 小时数 |
+| `LAST_DAY(date)` | 月末日期 | `LAST_DAY('2024-02-01')` | '2024-02-29' |
+
+**支持的时间单位**：`MICROSECOND`, `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`
+
+### 格式化与转换
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `DATE_FORMAT(date, fmt)` | 日期格式化 | `DATE_FORMAT(NOW(), '%Y年%m月%d日')` | '2024年03月15日' |
+| `TIME_FORMAT(t, fmt)` | 时间格式化 | `TIME_FORMAT('14:30:00', '%H:%i')` | '14:30' |
+| `STR_TO_DATE(str, fmt)` | 字符串转日期 | `STR_TO_DATE('2024-03-15', '%Y-%m-%d')` | 2024-03-15 |
+| `UNIX_TIMESTAMP([date])` | 转 Unix 时间戳 | `UNIX_TIMESTAMP('2024-03-15')` | 1710489600 |
+| `FROM_UNIXTIME(ts)` | 时间戳转日期 | `FROM_UNIXTIME(1710489600)` | '2024-03-15 00:00:00' |
+
+**DATE_FORMAT 常用格式符**：
+
+| 格式符 | 说明 | 示例 |
+|--------|------|------|
+| `%Y` | 四位年份 | 2024 |
+| `%y` | 两位年份 | 24 |
+| `%m` | 两位月份 | 03 |
+| `%c` | 月份（无前导零） | 3 |
+| `%d` | 两位日期 | 15 |
+| `%e` | 日期（无前导零） | 15 |
+| `%H` | 24 小时制（00-23） | 14 |
+| `%h` / `%I` | 12 小时制（01-12） | 02 |
+| `%i` | 分钟（00-59） | 30 |
+| `%s` | 秒（00-59） | 00 |
+| `%W` | 星期名称 | Friday |
+| `%M` | 月份名称 | March |
+| `%a` | 缩写星期 | Fri |
+| `%b` | 缩写月份 | Mar |
+
+### 星期与周
+
+| 函数 | 说明 | 示例 | 结果 |
+|------|------|------|------|
+| `WEEKDAY(date)` | 周索引 (0=Mon, 6=Sun) | `WEEKDAY('2024-03-18')` | 0 (周一) |
+| `DAYOFWEEK(date)` | 周索引 (1=Sun, 7=Sat) | `DAYOFWEEK('2024-03-18')` | 2 (周一) |
+| `DAYNAME(date)` | 星期名 | `DAYNAME('2024-03-18')` | 'Monday' |
+| `MONTHNAME(date)` | 月份名 | `MONTHNAME('2024-03-18')` | 'March' |
+| `WEEK(date[, mode])` | 周数 | `WEEK('2024-03-18')` | 12 |
+| `WEEKOFYEAR(date)` | ISO 周数 | `WEEKOFYEAR('2024-03-18')` | 12 |
+| `QUARTER(date)` | 季度 | `QUARTER('2024-03-18')` | 1 |
+| `DAYOFYEAR(date)` | 一年中的第几天 | `DAYOFYEAR('2024-03-18')` | 78 |
+
+## 业务场景
+
+### 场景 1: 本月、本周、本日统计
+
+```sql
+-- 本月注册用户
+SELECT COUNT(*) FROM user
+WHERE created_at >= DATE_FORMAT(CURDATE(), '%Y-%m-01');
+
+-- 本周注册用户（周一为一周开始）
+SELECT COUNT(*) FROM user
+WHERE created_at >= DATE_SUB(CURDATE(), INTERVAL WEEKDAY(CURDATE()) DAY);
+
+-- 今日统计
+SELECT COUNT(*) FROM `order`
+WHERE DATE(created_at) = CURDATE();
+```
+
+### 场景 2: 按年月聚合
+
+```sql
+SELECT 
+  DATE_FORMAT(created_at, '%Y-%m') AS month, 
+  COUNT(*) AS order_count,
+  SUM(amount) AS total_revenue
+FROM `order`
+GROUP BY month
+ORDER BY month;
+```
+
+### 场景 3: 计算用户注册天数
+
+```sql
+SELECT id, name, 
+  DATEDIFF(NOW(), created_at) AS days_since_reg 
+FROM user;
+```
+
+### 场景 4: 计算任务耗时
+
+```sql
+SELECT task_id, 
+  TIMESTAMPDIFF(SECOND, start_time, end_time) AS duration_seconds
+FROM task;
+```
+
+### 场景 5: 上月同期对比
+
+```sql
+SELECT 
+  DATE_FORMAT(created_at, '%Y-%m-%d') AS day,
+  COUNT(*) AS orders_today
+FROM `order`
+WHERE created_at >= DATE_SUB(DATE_SUB(CURDATE(), INTERVAL 1 MONTH), INTERVAL WEEKDAY(DATE_SUB(CURDATE(), INTERVAL 1 MONTH)) DAY)
+  AND created_at < CURDATE();
+```
+
+## 注意事项
+
+- `DATETIME` vs `TIMESTAMP`：`TIMESTAMP` 会自动时区转换，范围仅到 2038 年
+- `NOW()` 和 `SYSDATE()` 的区别：`NOW()` 返回语句开始的时刻，`SYSDATE()` 返回函数执行时的时刻
+- MySQL 5.6.4+ 支持毫秒精度：`NOW(3)`, `CURTIME(6)`
+- 日期函数中使用 `DATE()` 包裹列会导致索引失效（应改用范围查询）

skills/database-skills/mysql/references/03-functions-aggregate-window.md

@@ -0,0 +1,167 @@
+# 聚合函数与窗口函数 (Aggregate & Window Functions)
+
+## 聚合函数 (Aggregate Functions)
+
+### 简介
+
+聚合函数对一组行进行计算并返回单个值，常与 `GROUP BY` 子句配合使用，用于统计汇总和报表生成。
+
+### 常用聚合函数
+
+| 函数 | 说明 | 使用示例 | 注意 |
+|------|------|---------|------|
+| `COUNT(*)` | 行数计数（含 NULL） | `COUNT(*)` | 性能最好 |
+| `COUNT(expr)` | 非 NULL 值计数 | `COUNT(column_name)` | 排除 NULL |
+| `COUNT(DISTINCT expr)` | 去重计数 | `COUNT(DISTINCT user_id)` | UV 统计 |
+| `SUM(expr)` | 求和 | `SUM(amount)` | 忽略 NULL |
+| `AVG(expr)` | 平均值 | `AVG(score)` | SUM/COUNT 实现 |
+| `MAX(expr)` | 最大值 | `MAX(price)` | 字符串按字典序 |
+| `MIN(expr)` | 最小值 | `MIN(price)` | 字符串按字典序 |
+| `GROUP_CONCAT(expr)` | 组内拼接 | `GROUP_CONCAT(name SEPARATOR ',')` | 长度限制 1024 |
+
+### 业务场景
+
+#### 订单日报统计
+
+```sql
+SELECT
+  COUNT(*) AS total_orders,
+  COUNT(DISTINCT user_id) AS unique_users,
+  SUM(amount) AS total_revenue,
+  AVG(amount) AS avg_order_amount,
+  MAX(amount) AS max_order,
+  MIN(amount) AS min_order
+FROM `order`
+WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 DAY);
+```
+
+#### GROUP_CONCAT 行转列
+
+```sql
+SELECT 
+  u.name,
+  GROUP_CONCAT(o.order_no ORDER BY o.created_at SEPARATOR ', ') AS orders
+FROM user u
+LEFT JOIN `order` o ON u.id = o.user_id
+GROUP BY u.id;
+```
+
+#### CASE WHEN 条件聚合 (Pivot)
+
+```sql
+SELECT
+  SUM(CASE WHEN amount < 100 THEN 1 ELSE 0 END) AS low_orders,
+  SUM(CASE WHEN amount BETWEEN 100 AND 1000 THEN 1 ELSE 0 END) AS mid_orders,
+  SUM(CASE WHEN amount > 1000 THEN 1 ELSE 0 END) AS high_orders
+FROM `order`;
+```
+
+## 窗口函数 (Window Functions, MySQL 8.0+)
+
+### 简介
+
+窗口函数在不折叠行的情况下对结果集进行聚合和排名计算。与 `GROUP BY` 不同，窗口函数保留所有原始行，为每行添加计算结果。
+
+**语法**：
+
+```sql
+function_name() OVER (
+  [PARTITION BY col1, col2, ...]  -- 分组（可选）
+  [ORDER BY col ASC|DESC]          -- 排序（可选）
+  [frame_clause]                   -- 窗口帧（可选）
+)
+```
+
+### 排名函数
+
+| 函数 | 说明 | 行为特点 | 业务场景 |
+|------|------|---------|---------|
+| `ROW_NUMBER()` | 行号 | 每行唯一连续编号，无并列 | TOP-N 查询、分页去重 |
+| `RANK()` | 排名 | 并列跳号（如 1,1,3） | 竞赛排名 |
+| `DENSE_RANK()` | 密集排名 | 并列不跳号（如 1,1,2） | 销售排名分组 |
+| `NTILE(n)` | 分桶 | 均分为 n 组 | 四分位分析、数据分桶 |
+
+#### 示例：每部门薪资 TOP 3
+
+```sql
+SELECT dept_id, name, salary
+FROM (
+  SELECT dept_id, name, salary,
+    ROW_NUMBER() OVER (PARTITION BY dept_id ORDER BY salary DESC) AS rn
+  FROM employee
+) t
+WHERE rn <= 3;
+```
+
+#### 示例：考试成绩排名
+
+```sql
+SELECT name, score,
+  RANK() OVER (ORDER BY score DESC) AS rnk,
+  DENSE_RANK() OVER (ORDER BY score DESC) AS dense_rnk
+FROM exam_score;
+```
+
+### 偏移函数
+
+| 函数 | 说明 | 业务场景 |
+|------|------|---------|
+| `LAG(col, offset, default)` | 向前取第 N 行 | 环比、同比 |
+| `LEAD(col, offset, default)` | 向后取第 N 行 | 下期预测 |
+| `FIRST_VALUE(col)` | 窗口内第一个值 | 基准对比 |
+| `LAST_VALUE(col)` | 窗口内最后一个值 | 期末值 |
+| `NTH_VALUE(col, n)` | 窗口内第 N 个值 | 指定位置值 |
+
+#### 示例：日环比增长
+
+```sql
+SELECT created_at, amount,
+  LAG(amount, 1, 0) OVER (ORDER BY created_at) AS prev_amount,
+  amount - LAG(amount, 1, 0) OVER (ORDER BY created_at) AS diff,
+  ROUND((amount - LAG(amount, 1, 0) OVER (ORDER BY created_at)) / 
+        LAG(amount, 1, 0) OVER (ORDER BY created_at) * 100, 2) AS growth_pct
+FROM daily_sales;
+```
+
+### 聚合窗口函数（累计计算）
+
+聚合函数（SUM、AVG、COUNT 等）加上 `OVER()` 子句后可作为窗口函数使用。
+
+#### 示例：月度累计销售额
+
+```sql
+SELECT date, amount,
+  SUM(amount) OVER (ORDER BY date) AS cumulative_sum,
+  AVG(amount) OVER (ORDER BY date ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS moving_avg_7d
+FROM daily_sales;
+```
+
+#### 示例：部门内薪资对比
+
+```sql
+SELECT dept_id, name, salary,
+  AVG(salary) OVER (PARTITION BY dept_id) AS dept_avg_salary,
+  salary - AVG(salary) OVER (PARTITION BY dept_id) AS diff_from_avg,
+  ROUND(salary / AVG(salary) OVER (PARTITION BY dept_id) * 100, 2) AS pct_of_avg
+FROM employee;
+```
+
+### 窗口帧 (Frame Clause)
+
+帧定义了窗口函数的计算范围：
+
+| 帧语法 | 说明 |
+|--------|------|
+| `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW` | 从开始到当前行（默认） |
+| `ROWS BETWEEN 6 PRECEDING AND CURRENT ROW` | 前 6 行到当前行（移动平均） |
+| `ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING` | 当前行到结束 |
+| `ROWS BETWEEN 3 PRECEDING AND 3 FOLLOWING` | 前后各 3 行 |
+| `RANGE BETWEEN ...` | 按值范围而非行数 |
+| `ROWS UNBOUNDED PRECEDING` | 从开始到当前行（简写） |
+
+## 注意事项
+
+- `COUNT(*)` 和 `COUNT(col)` 不同：前者包含 NULL 行，后者排除
+- `GROUP_CONCAT` 结果受 `group_concat_max_len` 限制（默认 1024），可 `SET SESSION group_concat_max_len = 10000;`
+- 窗口函数只能在 `SELECT` 和 `ORDER BY` 中使用，不能在 `WHERE`、`GROUP BY`、`HAVING` 中使用
+- `LAST_VALUE` 的默认帧是 `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`，需要在 ORDER BY 后显式指定帧才能得到正确结果

skills/database-skills/mysql/references/04-functions-json.md

@@ -0,0 +1,129 @@
+# JSON 函数 (JSON Functions, MySQL 5.7+)
+
+## 简介
+
+MySQL 5.7+ 原生支持 JSON 数据类型和一系列 JSON 操作函数。JSON 类型比字符串存储更高效（自动校验格式、内部二进制存储），支持通过虚拟列建立索引。
+
+## 函数速查
+
+### 查询与提取
+
+| 函数 | 说明 | 版本 | 示例 |
+|------|------|------|------|
+| `JSON_EXTRACT(doc, path)` | 提取 JSON 值 | 5.7+ | `JSON_EXTRACT(attrs, '$.color')` |
+| `col->'$.path'` | JSON_EXTRACT 简写 | 5.7+ | `attrs->'$.color'` |
+| `col->>'$.path'` | 去引号版 | 8.0+ | `attrs->>'$.color'` |
+| `JSON_CONTAINS(doc, val, path)` | 是否包含指定值 | 5.7+ | `JSON_CONTAINS(attrs, '"red"', '$.color')` |
+| `JSON_CONTAINS_PATH(doc, one_or_all, path...)` | 路径是否存在 | 5.7+ | `JSON_CONTAINS_PATH(attrs, 'one', '$.color')` |
+| `JSON_KEYS(doc, path)` | 返回所有键 | 5.7+ | `JSON_KEYS(attrs)` |
+| `JSON_LENGTH(doc, path)` | 数组/对象长度 | 5.7+ | `JSON_LENGTH(attrs, '$.tags')` |
+| `JSON_DEPTH(doc)` | JSON 文档深度 | 5.7+ | `JSON_DEPTH(attrs)` |
+| `JSON_VALID(doc)` | 验证 JSON 合法性 | 5.7+ | `JSON_VALID('{"a":1}')` |
+| `JSON_SEARCH(doc, one_or_all, str)` | 搜索值路径 | 5.7+ | `JSON_SEARCH(attrs, 'one', 'red')` |
+| `JSON_TABLE(doc, path COLUMNS(...))` | JSON 转行（表函数） | 8.0+ | 见下 |
+
+### JSON 路径语法
+
+| 路径表达式 | 说明 |
+|-----------|------|
+| `$` | 根节点 |
+| `$.key` | 对象键 |
+| `$.nested.key` | 嵌套键 |
+| `$[0]` | 数组第一个元素 |
+| `$[*]` | 所有数组元素 |
+| `$.key[*].sub` | 数组中所有元素的子键 |
+
+### 构造与修改
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `JSON_OBJECT(k, v, ...)` | 构造 JSON 对象 | `JSON_OBJECT('id', 1, 'name', 'test')` |
+| `JSON_ARRAY(v1, v2, ...)` | 构造 JSON 数组 | `JSON_ARRAY(1, 2, 3)` |
+| `JSON_QUOTE(str)` | 字符串转 JSON 值 | `JSON_QUOTE('hello "world"')` |
+| `JSON_UNQUOTE(val)` | 去除 JSON 引号 | `JSON_UNQUOTE('"hello"')` |
+| `JSON_SET(doc, path, val)` | 设置/覆盖值 | `JSON_SET(attrs, '$.price', 5999)` |
+| `JSON_INSERT(doc, path, val)` | 插入（不覆盖已有） | `JSON_INSERT(attrs, '$.discount', 0.8)` |
+| `JSON_REPLACE(doc, path, val)` | 替换（仅在路径存在时） | `JSON_REPLACE(attrs, '$.price', 4999)` |
+| `JSON_REMOVE(doc, path)` | 删除键 | `JSON_REMOVE(attrs, '$.discount')` |
+| `JSON_ARRAY_APPEND(doc, path, val)` | 数组追加 | `JSON_ARRAY_APPEND(attrs, '$.tags', 'sale')` |
+| `JSON_ARRAY_INSERT(doc, path, val)` | 数组插入 | `JSON_ARRAY_INSERT(attrs, '$.tags[0]', 'hot')` |
+| `JSON_MERGE_PATCH(doc, patch)` | 合并（覆盖式） | `JSON_MERGE_PATCH(attrs, '{"color":"blue"}')` |
+| `JSON_MERGE_PRESERVE(doc, patch)` | 合并（保留式） | `JSON_MERGE_PRESERVE(attrs, '{"color":"blue"}')` |
+
+### 聚合函数
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `JSON_ARRAYAGG(col)` | 列转 JSON 数组 | `JSON_ARRAYAGG(product_name)` |
+| `JSON_OBJECTAGG(k, v)` | 列转 JSON 对象 | `JSON_OBJECTAGG(id, name)` |
+
+## 业务场景
+
+### 场景 1: 从商品 JSON 字段提取属性
+
+```sql
+SELECT id, name, 
+  attrs->>'$.color' AS color,
+  attrs->'$.specs' AS specs
+FROM product;
+```
+
+### 场景 2: 更新嵌套 JSON 字段
+
+```sql
+UPDATE product 
+SET attrs = JSON_SET(attrs, '$.specs.storage', '256GB', '$.price', 5999) 
+WHERE id = 1;
+```
+
+### 场景 3: 记录操作日志（JSON 动态字段）
+
+```sql
+INSERT INTO audit_log (action, detail) VALUES ('update_product',
+  JSON_OBJECT(
+    'product_id', 1, 
+    'old_price', 99, 
+    'new_price', 129, 
+    'operator', 'admin',
+    'timestamp', NOW()
+  ));
+```
+
+### 场景 4: JSON_TABLE 展开为关系表 (MySQL 8.0+)
+
+```sql
+SELECT jt.*
+FROM product,
+JSON_TABLE(attrs, '$' COLUMNS (
+  color VARCHAR(20) PATH '$.color',
+  ram VARCHAR(10) PATH '$.specs.ram',
+  storage VARCHAR(10) PATH '$.specs.storage'
+)) AS jt
+WHERE color = 'black';
+```
+
+### 场景 5: 通过虚拟列建立 JSON 索引
+
+MySQL 不支持直接对 JSON 列建索引。通过虚拟列 + 普通索引实现：
+
+```sql
+-- 添加虚拟列
+ALTER TABLE product ADD COLUMN color_virtual VARCHAR(20) 
+  GENERATED ALWAYS AS (attrs->>'$.color');
+
+-- 为虚拟列建索引
+CREATE INDEX idx_product_color ON product(color_virtual);
+
+-- 查询自动使用索引
+SELECT * FROM product WHERE color_virtual = 'red';
+```
+
+## 注意事项
+
+- JSON 列不存储重复键（保留最后一个值）
+- JSON 列自动格式校验，非法格式会报错
+- JSON 的二进制格式（BSON）允许快速键值查找，无需解析全文
+- JSON 列不能有 DEFAULT 值（MySQL 限制）
+- JSON 列不能直接索引，必须通过虚拟列间接索引
+- 在 WHERE 中直接使用 `attrs->>'$.key'` 不会使用索引，需走虚拟列
+- MySQL 8.0.13+ 支持 `JSON_TYPE()` 等更多 JSON 工具函数

skills/database-skills/mysql/references/05-sql-ddl-types.md

@@ -0,0 +1,235 @@
+# DDL 与数据类型详解
+
+## 简介
+
+DDL（Data Definition Language）用于定义和管理数据库对象（库、表、索引、约束等）。正确选择数据类型和约束对性能和数据完整性至关重要。
+
+## 数据库操作
+
+```sql
+-- 创建数据库
+CREATE DATABASE IF NOT EXISTS shop
+  DEFAULT CHARACTER SET utf8mb4
+  DEFAULT COLLATE utf8mb4_unicode_ci;
+
+-- 修改数据库
+ALTER DATABASE shop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- 删除数据库
+DROP DATABASE IF EXISTS shop;
+
+-- 查看数据库列表
+SHOW DATABASES;
+
+-- 切换数据库
+USE shop;
+
+-- 查看当前数据库
+SELECT DATABASE();
+```
+
+### 字符集选择建议
+
+| 字符集 | 说明 | 推荐度 |
+|--------|------|--------|
+| `utf8mb4` | 支持 4 字节 emoji，推荐 | ★★★★★ |
+| `utf8mb3` (utf8) | 不支持 emoji，已过时 | ★☆☆☆☆ |
+| `utf8mb4_unicode_ci` | Unicode 通用排序 | ★★★★★ |
+| `utf8mb4_general_ci` | 较宽松排序，稍快但不准确 | ★★★☆☆ |
+| `utf8mb4_bin` | 二进制比较，区分大小写 | ★★★☆☆ |
+| `utf8mb4_0900_ai_ci` | MySQL 8.0 默认，基于 UCA 9.0.0 | ★★★★★ |
+
+**原则**：生产环境统一使用 `utf8mb4` + `utf8mb4_unicode_ci`，避免字符集混用导致乱码和索引失效。
+
+## 数据类型
+
+### 整数类型
+
+| 类型 | 存储 | 有符号范围 | 无符号范围 | 推荐用途 |
+|------|------|-----------|-----------|---------|
+| `TINYINT` | 1B | -128 ~ 127 | 0 ~ 255 | 状态/性别/年龄 |
+| `SMALLINT` | 2B | -32,768 ~ 32,767 | 0 ~ 65,535 | 库存/排名 |
+| `MEDIUMINT` | 3B | -8,388,608 ~ 8,388,607 | 0 ~ 16,777,215 | 中型计数器 |
+| `INT` | 4B | -2,147,483,648 ~ 2,147,483,647 | 0 ~ 4,294,967,295 | 常用主键 |
+| `BIGINT` | 8B | -2^63 ~ 2^63-1 | 0 ~ 2^64-1 | 雪花ID/流水号 |
+
+**主键建议**：预期行数超过 40 亿时用 `BIGINT`，否则用 `INT`。MySQL 8.0.17+ 不推荐 `UNSIGNED`，建议用 `CHECK` 约束代替。
+
+```sql
+-- ❌ 旧做法
+age TINYINT UNSIGNED NOT NULL
+
+-- ✅ MySQL 8.0.17+ 推荐
+age TINYINT NOT NULL CHECK (age >= 0)
+```
+
+### 浮点数与定点数
+
+| 类型 | 存储 | 精度 | 用途 |
+|------|------|------|------|
+| `FLOAT` | 4B | 约 7 位 | 科学计算（不用于金额） |
+| `DOUBLE` | 8B | 约 15 位 | 科学计算 |
+| `DECIMAL(M,D)` | M+2B 变长 | 精确 | **金额必选** |
+
+```sql
+-- 金额字段
+price DECIMAL(10, 2) NOT NULL DEFAULT 0.00  -- 最大 99999999.99
+rate  DECIMAL(5, 4)                          -- 利率 0.0001 ~ 9.9999
+```
+
+### 字符串类型
+
+| 类型 | 最大长度 | 存储 | 用途 |
+|------|---------|------|------|
+| `CHAR(N)` | 255 | 定长，不足补空格 | 固定长度：手机号(11)、编码 |
+| `VARCHAR(N)` | 65535 | 变长+1-2B前缀 | 用户名、邮箱、标题 |
+| `TINYTEXT` | 255B | 行外 | 短备注 |
+| `TEXT` | 64KB | 行外 | 文章内容、评论 |
+| `MEDIUMTEXT` | 16MB | 行外 | 日志、长文本 |
+| `LONGTEXT` | 4GB | 行外 | 大文档 |
+
+**VARCHAR 长度选择**：
+- `VARCHAR(255)` 和 `VARCHAR(50)` 在行内存储消耗相同（只看实际长度）
+- 但临时表排序时按定义长度分配内存，不宜无意义设大
+- 合理范围：50-200
+
+**TEXT 注意事项**：
+- TEXT 列不能有 DEFAULT 值
+- TEXT 列不能用于内存临时表（ORDER BY 含 TEXT 会使用磁盘临时表）
+- TEXT 列的索引必须指定前缀长度：`CREATE INDEX idx_content ON article (content(100));`
+
+### 枚举类型
+
+| 类型 | 存储 | 说明 |
+|------|------|------|
+| `ENUM('v1','v2',...)` | 1-2B | 单选枚举，内部按整数存储 |
+| `SET('v1','v2',...)` | 1-8B | 多选位图 |
+
+**ENUM 注意事项**：
+- 修改 ENUM 定义需全表重建（ALTER TABLE MODIFY）
+- 内部按索引排序（定义顺序），非字母序
+- 推荐用 `TINYINT` + 代码映射，更灵活且迁移友好
+
+```sql
+-- 推荐做法
+status TINYINT NOT NULL DEFAULT 0 COMMENT '0:pending 1:paid 2:shipped'
+
+-- 不推荐
+status ENUM('pending', 'paid', 'shipped') NOT NULL DEFAULT 'pending'
+```
+
+### JSON 类型 (MySQL 5.7+)
+
+```sql
+-- 建表使用 JSON
+attrs JSON DEFAULT NULL COMMENT '商品扩展属性'
+
+-- 插入 JSON 数据
+INSERT INTO product VALUES (1, '手机', '{"color": "black", "specs": {"ram": "8GB"}}');
+
+-- 查询 JSON 值
+SELECT attrs->>'$.color' AS color FROM product;
+```
+
+详情参见 references/04-functions-json.md。
+
+### 空间数据类型
+
+| 类型 | 说明 | 业务场景 |
+|------|------|---------|
+| `POINT` | 点（经纬度） | 位置坐标 |
+| `LINESTRING` | 线 | 路线 |
+| `POLYGON` | 多边形 | 区域 |
+
+```sql
+-- 创建空间表
+CREATE TABLE location (
+  id INT PRIMARY KEY,
+  name VARCHAR(100),
+  coord POINT NOT NULL SRID 4326  -- WGS84 坐标系
+);
+
+-- 插入空间数据
+INSERT INTO location VALUES (1, '北京天安门', ST_GeomFromText('POINT(116.397 39.908)', 4326));
+
+-- 查询距离（米）
+SELECT name, ST_Distance_Sphere(coord, ST_GeomFromText('POINT(116.4 39.9)', 4326)) AS distance_m
+FROM location;
+
+-- 空间索引
+ALTER TABLE location ADD SPATIAL INDEX idx_coord (coord);
+```
+
+## 约束 (Constraints)
+
+| 约束 | 说明 | 注意 |
+|------|------|------|
+| `PRIMARY KEY` | 唯一标识每行，自动非空 | 建议 BIGINT AUTO_INCREMENT 或有序 UUID |
+| `UNIQUE` | 唯一值，允许多个 NULL | 联合唯一: `UNIQUE KEY uk_c1_c2 (c1, c2)` |
+| `FOREIGN KEY` | 引用完整性、级联操作 | InnoDB 专用，影响写入性能 |
+| `CHECK` | 值范围检查 | 8.0.16+ 才实际执行 |
+| `NOT NULL` | 不允许 NULL | 能用就用，提高查询效率 |
+| `DEFAULT` | 默认值 | 8.0.13+ 支持表达式 |
+| `AUTO_INCREMENT` | 自增序列 | 仅整数主键 |
+
+### 完整建表示例
+
+```sql
+CREATE TABLE IF NOT EXISTS `order` (
+  id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '订单ID',
+  order_no    VARCHAR(32) NOT NULL COMMENT '订单号',
+  user_id     INT UNSIGNED NOT NULL COMMENT '用户ID',
+  amount      DECIMAL(10, 2) NOT NULL DEFAULT 0.00 COMMENT '金额',
+  status      TINYINT NOT NULL DEFAULT 0 COMMENT '状态:0待支付1已支付2已取消',
+  quantity    INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '数量',
+  email       VARCHAR(100) DEFAULT NULL COMMENT '通知邮箱',
+  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  deleted_at  DATETIME DEFAULT NULL COMMENT '软删除时间',
+  
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_order_no (order_no),
+  KEY idx_user_id (user_id),
+  KEY idx_status_created (status, created_at),
+  KEY idx_deleted_at (deleted_at),
+  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES user(id) ON DELETE CASCADE,
+  CONSTRAINT chk_amount CHECK (amount >= 0),
+  CONSTRAINT chk_status CHECK (status IN (0, 1, 2))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';
+```
+
+## ALTER TABLE — 表结构变更
+
+```sql
+-- 添加列
+ALTER TABLE user ADD COLUMN avatar VARCHAR(500) DEFAULT NULL AFTER nickname;
+
+-- 修改列类型
+ALTER TABLE user MODIFY COLUMN email VARCHAR(200) NOT NULL;
+
+-- 重命名列
+ALTER TABLE user CHANGE COLUMN email new_email VARCHAR(200) NOT NULL;
+
+-- 重命名表
+RENAME TABLE old_name TO new_name;
+
+-- 添加索引
+ALTER TABLE user ADD INDEX idx_email (email);
+ALTER TABLE user ADD UNIQUE KEY uk_email (email);
+
+-- 删除索引
+ALTER TABLE user DROP INDEX idx_email;
+
+-- 在线 DDL (MySQL 5.6+)
+ALTER TABLE user ADD COLUMN age INT, ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+**生产环境大表改结构**使用 `pt-online-schema-change`(Percona Toolkit) 或 `gh-ost`，避免锁表。
+
+## DROP / TRUNCATE / DELETE 对比
+
+| 操作 | 速度 | 可回滚 | 重置自增值 | 触发 ON DELETE | 释放空间 |
+|------|------|--------|-----------|---------------|---------|
+| `DELETE` | 慢（逐行） | ✅ | ❌ | ✅ | 不释放 |
+| `TRUNCATE` | 快（DROP+CREATE） | ❌ | ✅ | ❌ | 释放 |
+| `DROP` | 快 | ❌ | N/A | ❌ | 全部释放 |

skills/database-skills/mysql/references/06-index-optimization.md

@@ -0,0 +1,232 @@
+# 索引与执行计划 (Index & Query Optimization)
+
+## 简介
+
+索引是 MySQL 性能优化的核心手段。正确的索引能大幅减少扫描行数，错误的索引设计则会导致全表扫描和性能灾难。
+
+## 索引类型
+
+| 索引类型 | 底层结构 | 版本要求 | 适用场景 |
+|---------|---------|---------|---------|
+| **B-Tree** | B+ 树 | 全版本 | 等值/范围/排序查询（默认） |
+| **Hash** | 哈希表 | MEMORY 引擎 | 等值查询（不支持范围） |
+| **Fulltext** | 倒排索引 | 5.6+ | 全文搜索 (MATCH AGAINST) |
+| **Spatial** | R-Tree | 5.7+ | 空间数据查询 |
+| **Descending** | B+ 树降序 | 8.0+ | 混合排序方向优化 |
+| **Invisible** | 同 B-Tree | 8.0+ | 测试删除影响而不实际删除 |
+| **Functional Key Parts** | 表达式索引 | 8.0.13+ | 函数/表达式索引 |
+
+### B-Tree 索引创建
+
+```sql
+-- 普通索引
+CREATE INDEX idx_name ON user (name);
+
+-- 唯一索引
+CREATE UNIQUE INDEX uk_email ON user (email);
+
+-- 复合索引（最左前缀原则）
+CREATE INDEX idx_city_age ON user (city, age);
+
+-- 前缀索引（字符串前 N 字符）
+CREATE INDEX idx_email_prefix ON user (email(10));
+
+-- 全文索引
+CREATE FULLTEXT INDEX ftx_content ON article (title, content);
+
+-- 降序索引 (MySQL 8.0+)
+CREATE INDEX idx_created_desc ON `order` (created_at DESC);
+
+-- 不可见索引（测试用）
+CREATE INDEX idx_test ON user (name) INVISIBLE;
+ALTER TABLE user ALTER INDEX idx_test VISIBLE;
+
+-- 函数索引 (MySQL 8.0.13+)
+CREATE INDEX idx_phone_last4 ON user ((RIGHT(phone, 4)));
+```
+
+## 复合索引最左前缀原则
+
+复合索引 `idx_a_b_c (a, b, c)`：
+
+| 查询条件 | 索引使用情况 |
+|---------|-------------|
+| `WHERE a = 1` | ✅ 使用 a |
+| `WHERE a = 1 AND b = 2` | ✅ 使用 a, b |
+| `WHERE a = 1 AND b = 2 AND c = 3` | ✅ 使用 a, b, c |
+| `WHERE a = 1 ORDER BY b` | ✅ 使用 a（排序） |
+| `WHERE a = 1 AND c = 3` | ✅ 使用 a（c 只能过滤） |
+| `WHERE a IN (1, 2) AND b = 3` | ✅ 使用 a, b |
+| `WHERE b = 2` | ❌ 跳过了 a |
+| `WHERE c = 3` | ❌ 跳过了 a, b |
+
+### 索引设计原则
+
+1. **区分度高的列放前面**：选择性 = `COUNT(DISTINCT col) / COUNT(*)`
+2. **等值条件列放前面**：`=` 比范围查询列放前面
+3. **覆盖索引**：查询列全在索引中（Extra 显示 `Using index`），避免回表
+4. **索引下推 (ICP)**：MySQL 5.6+，引擎层用 WHERE 条件过滤索引记录后再回表
+
+## EXPLAIN 执行计划分析
+
+### 使用 EXPLAIN
+
+```sql
+EXPLAIN SELECT u.name, o.order_no
+FROM user u
+JOIN `order` o ON u.id = o.user_id
+WHERE u.id = 100;
+```
+
+### EXPLAIN 输出列
+
+| 列名 | 含义 | 关键值 |
+|------|------|--------|
+| `id` | SELECT 标识符，id 越大越先执行 | |
+| `select_type` | 查询类型 | SIMPLE, PRIMARY, SUBQUERY, DERIVED, UNION |
+| `table` | 表名 | |
+| `partitions` | 扫描的分区 | |
+| `type` | 访问类型（性能排序） | system > const > eq_ref > ref > range > index > **ALL** |
+| `possible_keys` | 可能使用的索引 | |
+| `key` | 实际使用的索引 | |
+| `key_len` | 使用的索引字节长度 | 越大越好（匹配更多列） |
+| `ref` | 索引匹配的列或常量 | |
+| `rows` | 预估扫描行数 | 越小越好 |
+| `filtered` | 过滤后百分比 | |
+| `Extra` | 额外信息 | **🔑 重要** |
+
+### type 访问类型（从优到劣）
+
+| type | 说明 | 示例 |
+|------|------|------|
+| **system** | 表只有一行 | 最好 |
+| **const** | 主键/唯一索引等值查询 | `WHERE id = 1` |
+| **eq_ref** | JOIN 主键/唯一索引关联 | `ON u.id = o.user_id` |
+| **ref** | 普通索引等值查询 | `WHERE name = '张三'` |
+| **range** | 索引范围扫描 | `WHERE id > 100`, `LIKE '张%'` |
+| **index** | 全索引扫描 | 不推荐 |
+| **ALL** | 全表扫描 | **❌ 最差** |
+
+### Extra 关键信息
+
+| Extra 值 | 含义 |
+|----------|------|
+| **Using index** | 覆盖索引（无需回表）✅ 最佳 |
+| **Using where** | 用 WHERE 过滤 |
+| **Using index condition** | 索引下推 ICP ✅ |
+| **Using temporary** | 使用临时表（需优化）❌ |
+| **Using filesort** | 文件排序（需优化）❌ |
+| **Using join buffer** | JOIN 未用索引 ❌ |
+| **Using MRR** | 多范围读取优化 ✅ |
+
+### EXPLAIN ANALYZE (MySQL 8.0.18+)
+
+```sql
+-- 实际执行并显示各步骤耗时和行数
+EXPLAIN ANALYZE
+SELECT u.name, COUNT(o.id) AS order_count
+FROM user u
+LEFT JOIN `order` o ON u.id = o.user_id
+GROUP BY u.id
+ORDER BY order_count DESC
+LIMIT 10;
+```
+
+## SQL 优化原则
+
+```
+★ 核心原则：减少扫描行数，减少回表，减少排序
+
+1. WHERE 条件列建索引（符合最左前缀）
+2. 避免 SELECT *，仅取需要的列（利用覆盖索引）
+3. 用 EXISTS 代替 IN（大数据量下）
+4. 用 UNION ALL 代替 UNION（不需要去重时）
+5. 用 LIMIT 限制结果集大小
+6. 大表分页用游标（WHERE id > last_id）而非 OFFSET
+7. JOIN 的关联列必须有索引
+8. GROUP BY / ORDER BY 的列尽量利用索引
+9. 避免在 WHERE 条件列上使用函数或计算
+10. 拆分大查询为多次小查询（减少锁范围）
+```
+
+## 常见优化案例
+
+### 隐式类型转换（索引失效）
+
+```sql
+-- ❌ phone 是 VARCHAR，传 INT 导致全表扫描
+SELECT * FROM user WHERE phone = 13800138000;
+
+-- ✅ 字符类型就传字符串
+SELECT * FROM user WHERE phone = '13800138000';
+```
+
+### WHERE 条件函数操作（索引失效）
+
+```sql
+-- ❌ DATE() 函数使索引失效
+SELECT * FROM `order` WHERE DATE(created_at) = '2024-01-01';
+
+-- ✅ 范围查询可用索引
+SELECT * FROM `order` WHERE created_at >= '2024-01-01' AND created_at < '2024-01-02';
+```
+
+### 大分页优化
+
+```sql
+-- ❌ OFFSET 越大越慢（先扫描再丢弃）
+SELECT * FROM `order` ORDER BY id LIMIT 100000, 20;
+
+-- ✅ 游标分页
+SELECT * FROM `order` WHERE id > 100000 ORDER BY id LIMIT 20;
+
+-- ✅ 子查询 + JOIN 方式
+SELECT * FROM `order`
+JOIN (SELECT id FROM `order` ORDER BY id LIMIT 100000, 20) AS tmp
+ON `order`.id = tmp.id;
+```
+
+### OR 改为 UNION
+
+```sql
+-- ❌ OR 可能用不到复合索引
+SELECT * FROM user WHERE name = '张三' OR email = 'zhangsan@example.com';
+
+-- ✅ UNION 分别用各自索引
+SELECT * FROM user WHERE name = '张三'
+UNION
+SELECT * FROM user WHERE email = 'zhangsan@example.com';
+```
+
+## 慢查询配置
+
+```ini
+# my.cnf
+slow_query_log = ON                          # 开启慢查询
+slow_query_log_file = /var/log/mysql/slow.log # 慢查询日志文件
+long_query_time = 1                          # 超过 1 秒的查询记录
+log_queries_not_using_indexes = ON           # 记录未使用索引的查询
+min_examined_row_limit = 100                 # 扫描行数超过此值才记录
+```
+
+### 分析慢查询
+
+```bash
+# mysqldumpslow 排序取前10
+mysqldumpslow -s t -t 10 /var/log/mysql/slow.log
+
+# Percona Toolkit 分析
+pt-query-digest /var/log/mysql/slow.log
+```
+
+## 索引设计规范
+
+1. 每个表必须有主键（推荐 BIGINT AUTO_INCREMENT 或有序 UUID）
+2. 主键不宜过长（B+ 树二级索引过大）
+3. 每个表索引数不超过 5-8 个（过多影响写入性能）
+4. 大表（> 1000 万行）索引必须业务验证后创建
+5. 字符串区分度低或长度大时用前缀索引
+6. ORDER BY / GROUP BY / JOIN 的列考虑建索引
+7. 不建索引的列：频繁更新、区分度极低（如性别）
+8. 用 INVISIBLE 索引测试后再删除
+9. 避免冗余索引（如 idx_a_b 和 idx_a 重复）

skills/database-skills/mysql/references/07-replication-ha.md

@@ -0,0 +1,213 @@
+# 主从复制与高可用 (Replication & High Availability)
+
+## 简介
+
+MySQL 主从复制是生产环境中最常用的高可用和读写分离方案。主库（Master）记录二进制日志（Binlog），从库（Slave）通过网络读取并回放日志，实现数据同步。
+
+## 复制原理
+
+```
+┌─────────────┐          ┌─────────────┐
+│   Master    │          │   Slave     │
+├─────────────┤          ├─────────────┤
+│   Binlog    │─────→    │ Relay Log   │
+│  (二进制日志) │  IO线程  │  (中继日志)  │
+└─────────────┘          └──────┬──────┘
+                               │ SQL线程
+                               ▼
+                           ┌─────────────┐
+                           │  Slave Data  │
+                           └─────────────┘
+```
+
+**复制流程**：
+1. Master 提交事务时写入 Binlog
+2. Slave 的 IO 线程读取 Master 的 Binlog，写入 Relay Log
+3. Slave 的 SQL 线程回放 Relay Log，应用到自身数据
+
+## 主从同步配置
+
+### Master 配置
+
+```ini
+# my.cnf
+server-id = 1
+log_bin = /var/log/mysql/mysql-bin
+binlog_format = ROW             # ROW 格式最安全（推荐）
+binlog_expire_logs_seconds = 604800  # 保留 7 天
+sync_binlog = 1                 # 每次事务提交同步（最安全）
+```
+
+```sql
+-- 创建复制用户
+CREATE USER 'replicator'@'%' IDENTIFIED BY 'password';
+GRANT REPLICATION SLAVE ON *.* TO 'replicator'@'%';
+FLUSH PRIVILEGES;
+
+-- 查看 Master 状态
+SHOW MASTER STATUS;
+-- File: mysql-bin.000001, Position: 1234
+```
+
+### Slave 配置
+
+```ini
+# my.cnf
+server-id = 2
+relay_log = /var/log/mysql/mysql-relay-bin
+read_only = 1                   # 只读（防止误写）
+```
+
+```sql
+-- 设置主节点
+CHANGE MASTER TO
+  MASTER_HOST = '192.168.1.100',
+  MASTER_PORT = 3306,
+  MASTER_USER = 'replicator',
+  MASTER_PASSWORD = 'password',
+  MASTER_LOG_FILE = 'mysql-bin.000001',
+  MASTER_LOG_POS = 1234;
+
+-- 启动复制
+START SLAVE;
+
+-- 查看复制状态（关键字段）
+SHOW SLAVE STATUS\G
+-- Slave_IO_Running: Yes      -- IO 线程正常
+-- Slave_SQL_Running: Yes     -- SQL 线程正常
+-- Seconds_Behind_Master: 0   -- 延迟秒数（0 最佳）
+
+-- 停止复制
+STOP SLAVE;
+
+-- 重置复制
+RESET SLAVE ALL;
+```
+
+### 复制状态监控关键字段
+
+| 字段 | 说明 | 正常值 |
+|------|------|--------|
+| `Slave_IO_Running` | IO 线程状态 | Yes |
+| `Slave_SQL_Running` | SQL 线程状态 | Yes |
+| `Seconds_Behind_Master` | 延迟秒数 | 0（或很小） |
+| `Last_IO_Error` | IO 线程错误 | 空 |
+| `Last_SQL_Error` | SQL 线程错误 | 空 |
+| `Relay_Log_Space` | Relay Log 大小 | 稳定值 |
+| `Exec_Master_Log_Pos` | 已执行位置 | 持续增长 |
+
+## 复制模式对比
+
+| 模式 | 说明 | 一致性 | 性能 | 推荐度 |
+|------|------|--------|------|--------|
+| **异步 (ASYNC)** | Master 不等待 Slave 确认 | 最终一致性 | 最高 | 默认 |
+| **半同步 (SEMISYNC)** | 至少一个 Slave 写入 Relay Log | 较高 | 略微降低 | ★★★★★ |
+| **全同步 (Group Replication)** | 多数节点确认 | 强一致性 | 最低 | 特定场景 |
+
+### 半同步复制配置
+
+```sql
+-- Master 和 Slave 都安装插件
+INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so';
+INSTALL PLUGIN rpl_semi_sync_slave SONAME 'semisync_slave.so';
+
+-- Master 启用
+SET GLOBAL rpl_semi_sync_master_enabled = 1;
+SET GLOBAL rpl_semi_sync_master_timeout = 1000;  -- 1s 超时降级为异步
+
+-- Slave 启用
+SET GLOBAL rpl_semi_sync_slave_enabled = 1;
+```
+
+## 复制延迟处理
+
+### 常见延迟原因
+
+1. Slave 硬件弱于 Master
+2. 大事务（一次 DELETE/UPDATE 百万行）
+3. Slave 上存在慢查询锁竞争
+4. 单线程 SQL 回放（MySQL 5.6+ 可开启并行复制）
+
+### 并行复制配置 (MySQL 5.7+)
+
+```ini
+# my.cnf
+slave_parallel_workers = 4
+slave_parallel_type = LOGICAL_CLOCK
+```
+
+### 应用层处理延迟
+
+```sql
+-- 关键读走主库（如支付成功后的订单查询）
+-- 普通读走从库（容忍秒级延迟）
+
+-- 判断延迟：如果从库读不到数据，降级读主库
+```
+
+## 高可用方案
+
+| 方案 | 原理 | 优点 | 缺点 | 推荐场景 |
+|------|------|------|------|---------|
+| **主从 + 手动切换** | 手动执行 CHANGE MASTER | 简单 | 切换时间 10min+ | 非关键业务 |
+| **MHA** | 自动检测 Master 故障切换 | 成熟稳定 | 需独立管理节点 | 经典方案 |
+| **Orchestrator** | 自动故障检测/拓扑管理 | 自动修复 | 复杂度中等 | **推荐方案** |
+| **InnoDB Cluster** | Group Replication + MySQL Router | 原生方案 | 需 8.0+ | MySQL 官方方案 |
+| **ProxySQL + 读写分离** | 中间层路由 | 灵活路由 | 引入代理层 | 配合复制使用 |
+
+### Orchestrator 工作流程
+
+```
+1. 检测 Master 故障（心跳超时）
+2. 选择最优 Slave（延迟最小、数据最新）
+3. 自动提升为新 Master
+4. 重新配置其他 Slave 指向新 Master
+5. 通知应用层新 Master 地址（通过 API / Consul）
+```
+
+## 读写分离架构
+
+### 应用层实现
+
+```text
+// 伪代码
+if (sql.startsWith("SELECT")) {
+    connection = slavePool.getConnection();
+} else {
+    connection = masterPool.getConnection();
+}
+```
+
+### ProxySQL 实现
+
+```sql
+-- ProxySQL 配置读写分离组
+INSERT INTO mysql_replication_hostgroups 
+(writer_hostgroup, reader_hostgroup, comment) 
+VALUES (10, 20, '读写分离');
+
+-- SELECT 自动路由到从节点（reader_hostgroup=20）
+-- DML 自动路由到主节点（writer_hostgroup=10）
+```
+
+## 分库分表 (Sharding)
+
+### 何时需要分库分表
+
+单表 > 5000 万行或单实例 > 2TB 且预期继续增长。
+
+### 方案选择
+
+| 方案 | 类型 | 说明 |
+|------|------|------|
+| ShardingSphere | 中间件 + 客户端 | Java 生态首选 |
+| MyCAT | 数据库中间件 | 传统方案 |
+| Vitess | 分布式方案 | YouTube 开源 |
+| TiDB | 原生分布式 | 彻底解决但需切换数据库 |
+
+### 分库分表注意事项
+
+1. **分片键选择**：`user_id % shard_count` 或 `order_id % shard_count`
+2. **跨分片查询**：全局表、广播表、ER 分片
+3. **分布式 ID**：雪花算法、Leaf、Segment
+4. **分布式事务**：XA / TCC / Saga / Seata

skills/database-skills/mysql/references/08-backup-restore.md

@@ -0,0 +1,207 @@
+# 备份与恢复 (Backup & Restore)
+
+## 简介
+
+MySQL 备份分为逻辑备份（mysqldump）和物理备份（XtraBackup）。逻辑备份导出 SQL 语句，适合小规模和迁移场景；物理备份直接复制数据文件，适合大数据库的快速恢复。
+
+## mysqldump — 逻辑备份
+
+### 基本用法
+
+```bash
+# 备份单个数据库（推荐使用 --single-transaction 避免锁表）
+mysqldump -u root -p --single-transaction --routines --triggers --events shop > shop_backup.sql
+
+# 备份所有数据库
+mysqldump -u root -p --all-databases --single-transaction > all_db_backup.sql
+
+# 只备份表结构
+mysqldump -u root -p --no-data shop > shop_schema.sql
+
+# 只备份数据
+mysqldump -u root -p --no-create-info shop > shop_data.sql
+
+# 压缩备份
+mysqldump -u root -p shop | gzip > shop_backup.sql.gz
+
+# 备份特定表
+mysqldump -u root -p shop user order product > critical_tables.sql
+
+# 备份到远程服务器
+mysqldump -u root -p shop | ssh user@backup-server "cat > /backups/shop.sql"
+```
+
+### 关键参数说明
+
+| 参数 | 说明 | 推荐 |
+|------|------|------|
+| `--single-transaction` | InnoDB 事务一致性备份，不锁表 | **必选**（InnoDB） |
+| `--lock-tables` | MyISAM 表锁 | 仅 MyISAM 时需要 |
+| `--routines` | 备份存储过程和函数 | ✅ 推荐 |
+| `--triggers` | 备份触发器 | ✅ 推荐 |
+| `--events` | 备份事件调度器 | ✅ 推荐 |
+| `--quick` | 逐行导出（防止大表内存溢出） | ✅ 大表推荐 |
+| `--opt` | 快速导出（默认开启） | 默认 |
+
+### 恢复
+
+```bash
+# 基本恢复
+mysql -u root -p shop < shop_backup.sql
+
+# 恢复压缩备份
+gunzip < shop_backup.sql.gz | mysql -u root -p shop
+
+# 恢复多个数据库
+mysql -u root -p < all_db_backup.sql
+```
+
+## XtraBackup — 物理备份
+
+Percona XtraBackup 是 MySQL 物理备份的事实标准，支持热备份 InnoDB 表而不影响读写。
+
+### 安装
+
+```bash
+# macOS
+brew install percona-xtrabackup
+
+# Ubuntu
+apt install percona-xtrabackup-80
+
+# CentOS
+yum install percona-xtrabackup-80
+```
+
+### 全量备份与恢复
+
+```bash
+# 全量备份
+xtrabackup --backup --target-dir=/data/backup/full/ --user=root --password=xxx
+
+# 准备恢复（应用 redo log，使数据一致）
+xtrabackup --prepare --target-dir=/data/backup/full/
+
+# 恢复到 MySQL 数据目录
+xtrabackup --copy-back --target-dir=/data/backup/full/
+# 或手动复制
+rsync -avrP /data/backup/full/ /var/lib/mysql/
+chown -R mysql:mysql /var/lib/mysql/
+```
+
+### 增量备份与恢复
+
+```bash
+# 全量备份（基础）
+xtrabackup --backup --target-dir=/data/backup/full/
+
+# 增量备份（基于全量）
+xtrabackup --backup --target-dir=/data/backup/inc1/ \
+  --incremental-basedir=/data/backup/full/
+
+# 第二个增量备份（基于前一个增量）
+xtrabackup --backup --target-dir=/data/backup/inc2/ \
+  --incremental-basedir=/data/backup/inc1/
+
+# 增量恢复流程
+# 1. 准备全量（应用 log 但不回滚未提交事务）
+xtrabackup --prepare --apply-log-only --target-dir=/data/backup/full/
+
+# 2. 合并增量 1
+xtrabackup --prepare --apply-log-only --target-dir=/data/backup/full/ \
+  --incremental-dir=/data/backup/inc1/
+
+# 3. 合并增量 2（最后一次不用 --apply-log-only）
+xtrabackup --prepare --target-dir=/data/backup/full/ \
+  --incremental-dir=/data/backup/inc2/
+
+# 4. copy-back 恢复
+xtrabackup --copy-back --target-dir=/data/backup/full/
+```
+
+## 二进制日志与 PITR（时间点恢复）
+
+PITR（Point-In-Time Recovery）允许恢复到某个精确的时间点，是应对误操作（DROP TABLE、DELETE 全表）的核心手段。
+
+### 启用二进制日志
+
+```ini
+# my.cnf
+log_bin = /var/log/mysql/mysql-bin
+binlog_format = ROW         # ROW 格式最安全
+binlog_expire_logs_seconds = 604800  # 保留 7 天
+```
+
+### 查看二进制日志
+
+```sql
+-- 查看 Binlog 是否开启
+SHOW VARIABLES LIKE 'log_bin';
+
+-- 列出所有 Binlog 文件
+SHOW BINARY LOGS;
+
+-- 查看 Binlog 事件
+SHOW BINLOG EVENTS IN 'mysql-bin.000001' LIMIT 10;
+
+-- 查看当前 Binlog 位置
+SHOW MASTER STATUS;
+```
+
+### PITR 恢复流程
+
+```bash
+# Step 1: 恢复最近的完整备份
+mysql -u root -p shop < shop_backup.sql
+
+# Step 2: 回放二进制日志到指定时间点
+mysqlbinlog --stop-datetime="2024-01-15 10:00:00" \
+  /var/log/mysql/mysql-bin.* | mysql -u root -p
+
+# 指定位置恢复
+mysqlbinlog --stop-position=12345 \
+  /var/log/mysql/mysql-bin.000001 | mysql -u root -p
+
+# 指定开始和结束范围
+mysqlbinlog \
+  --start-datetime="2024-01-15 09:00:00" \
+  --stop-datetime="2024-01-15 10:00:00" \
+  /var/log/mysql/mysql-bin.000001 \
+  /var/log/mysql/mysql-bin.000002 \
+  | mysql -u root -p shop
+```
+
+## 备份策略推荐
+
+### 生产环境备份策略
+
+```
+┌──────────────────────────────────────────────┐
+│ 生产环境备份策略：                              │
+│                                               │
+│ 每日凌晨 2:00: 全量备份 (XtraBackup 物理备份)    │
+│ 每 6 小时:      增量备份 (XtraBackup 增量)       │
+│ 实时:           二进制日志持续归档 (BINLOG)       │
+│ 保留周期:       最近 7 天全量 + 30 天增量         │
+│ 异地备份:       备份文件同步到对象存储 (OSS/S3)    │
+│ 定期演练:       每月一次恢复测试                   │
+└──────────────────────────────────────────────┘
+```
+
+### 备份检查清单
+
+- [ ] 全量备份是否成功（检查 `xtrabackup` 退出码）
+- [ ] 备份文件大小是否合理（过大/过小要排查）
+- [ ] 异地备份是否同步完成
+- [ ] 二进制日志是否连续不中断
+- [ ] 每月恢复演练验证备份可用性
+- [ ] 备份保留策略是否符合合规要求
+
+## 注意事项
+
+- **不要只依赖一种备份方式**：逻辑备份 + 物理备份 + Binlog 三者配合
+- **测试恢复**：定期在测试环境演练恢复流程，确保备份可用
+- **监控备份状态**：通过脚本监控备份成功率，发送告警
+- **备份加密**：敏感数据的备份文件应加密存储
+- **备份压缩**：物理备份建议用 `--compress` 参数，可节省 3-5 倍存储空间
+- **mysqldump 对超大表（> 50GB）不适用**：导出和导入都极慢，建议用 XtraBackup

skills/database-skills/mysql/references/09-advanced-features.md

@@ -0,0 +1,345 @@
+# 高级特性 (Advanced Features)
+
+## 简介
+
+MySQL 提供视图、CTE、存储过程/函数、触发器、事务与锁、分区表等高级特性，用于满足复杂业务需求和性能优化。
+
+## 视图 (View)
+
+视图是存储的查询定义，不存储数据，使用时会展开为底层查询执行。
+
+### 创建与使用
+
+```sql
+-- 创建视图
+CREATE VIEW user_order_summary AS
+SELECT u.id, u.name, COUNT(o.id) AS order_count, SUM(o.amount) AS total_amount
+FROM user u
+LEFT JOIN `order` o ON u.id = o.user_id
+GROUP BY u.id;
+
+-- 使用视图（像普通表一样查询）
+SELECT * FROM user_order_summary WHERE order_count > 5;
+
+-- 可更新视图（需满足条件）
+UPDATE active_user SET email = 'new@example.com' WHERE id = 1;
+
+-- 查看视图定义
+SHOW CREATE VIEW user_order_summary;
+
+-- 删除视图
+DROP VIEW IF EXISTS user_order_summary;
+```
+
+### 视图限制
+
+| 限制 | 说明 |
+|------|------|
+| 不可更新条件 | 含 DISTINCT、聚合、GROUP BY、HAVING、UNION 的视图不可更新 |
+| 性能 | 与直接查询无异（视图不存储数据） |
+| 算法 | `ALGORITHM = MERGE | TEMPTABLE | UNDEFINED` |
+
+**业务场景**：封装复杂查询逻辑、简化报表查询、提供权限控制层。
+
+## CTE (Common Table Expression, MySQL 8.0+)
+
+CTE 提供临时结果集的命名引用，可读性更高，支持递归。
+
+### 基础 CTE
+
+```sql
+WITH dept_avg AS (
+  SELECT dept_id, AVG(salary) AS avg_salary
+  FROM employee
+  GROUP BY dept_id
+)
+SELECT e.name, e.salary, da.avg_salary
+FROM employee e
+JOIN dept_avg da ON e.dept_id = da.dept_id
+WHERE e.salary > da.avg_salary;
+```
+
+### 递归 CTE — 树形结构查询
+
+```sql
+WITH RECURSIVE sub_depts AS (
+  -- 基础节点（根部门）
+  SELECT id, name, parent_id, 1 AS level
+  FROM department
+  WHERE parent_id IS NULL
+
+  UNION ALL
+
+  -- 递归子节点
+  SELECT d.id, d.name, d.parent_id, sd.level + 1
+  FROM department d
+  JOIN sub_depts sd ON d.parent_id = sd.id
+)
+SELECT * FROM sub_depts ORDER BY level, id;
+```
+
+**业务场景**：
+- 递归 CTE 查询组织树、分类树、评论树
+- CTE 替代派生表，提高可读性并支持多次引用
+
+## 存储过程与存储函数
+
+### 存储过程
+
+封装多条 SQL，支持事务控制、IN/OUT 参数、错误处理。
+
+```sql
+DELIMITER //
+CREATE PROCEDURE transfer_funds(
+  IN from_account INT,
+  IN to_account INT,
+  IN amount DECIMAL(10, 2),
+  OUT result_code INT,
+  OUT result_msg VARCHAR(200)
+)
+BEGIN
+  DECLARE EXIT HANDLER FOR SQLEXCEPTION
+  BEGIN
+    ROLLBACK;
+    SET result_code = -1;
+    SET result_msg = '转账失败，事务回滚';
+  END;
+
+  START TRANSACTION;
+    UPDATE account SET balance = balance - amount 
+    WHERE id = from_account AND balance >= amount;
+    
+    IF ROW_COUNT() = 0 THEN
+      SET result_code = -2;
+      SET result_msg = '余额不足';
+      ROLLBACK;
+    ELSE
+      UPDATE account SET balance = balance + amount WHERE id = to_account;
+      SET result_code = 0;
+      SET result_msg = '转账成功';
+      COMMIT;
+    END IF;
+END //
+DELIMITER ;
+
+-- 调用
+CALL transfer_funds(1, 2, 100.00, @code, @msg);
+SELECT @code, @msg;
+```
+
+### 存储函数
+
+返回单值的函数，可在 SQL 中直接使用。
+
+```sql
+DELIMITER //
+CREATE FUNCTION get_order_count(user_id INT) RETURNS INT
+READS SQL DATA
+BEGIN
+  DECLARE cnt INT;
+  SELECT COUNT(*) INTO cnt FROM `order` WHERE user_id = user_id;
+  RETURN cnt;
+END //
+DELIMITER ;
+
+-- 使用
+SELECT name, get_order_count(id) AS order_count FROM user;
+```
+
+### 存储过程 vs 函数
+
+| 特性 | 存储过程 | 存储函数 |
+|------|---------|---------|
+| 返回值 | 多个 OUT 参数 | 单个返回值 |
+| 调用方式 | `CALL proc()` | `SELECT func()` 或 SQL 中直接使用 |
+| 事务控制 | ✅ 支持 | ❌ 不支持 |
+| SQL 中使用 | ❌ | ✅ |
+
+**业务场景**：存储过程适合转账、库存核减等事务性操作。但现代应用主要在应用层（如 Spring/Go）实现业务逻辑。
+
+## 触发器 (Trigger)
+
+### 基本语法
+
+```sql
+-- CREATE TRIGGER trigger_name
+-- {BEFORE | AFTER} {INSERT | UPDATE | DELETE}
+-- ON table_name FOR EACH ROW
+-- trigger_body
+```
+
+### 常见用例
+
+```sql
+-- 1. 自动更新时间
+CREATE TRIGGER before_user_update
+BEFORE UPDATE ON user
+FOR EACH ROW
+SET NEW.updated_at = NOW();
+
+-- 2. 审计日志
+CREATE TRIGGER after_order_update
+AFTER UPDATE ON `order`
+FOR EACH ROW
+INSERT INTO audit_log (table_name, action, old_data, new_data)
+VALUES ('order', 'UPDATE',
+  JSON_OBJECT('status', OLD.status, 'amount', OLD.amount),
+  JSON_OBJECT('status', NEW.status, 'amount', NEW.amount));
+
+-- 3. 防止重复签到
+CREATE TRIGGER before_signin_insert
+BEFORE INSERT ON signin
+FOR EACH ROW
+BEGIN
+  DECLARE cnt INT;
+  SELECT COUNT(*) INTO cnt FROM signin
+  WHERE user_id = NEW.user_id AND DATE(created_at) = CURDATE();
+  IF cnt > 0 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '今日已签到';
+  END IF;
+END;
+```
+
+### 触发器注意事项
+
+| 问题 | 说明 |
+|------|------|
+| 隐性执行 | 排查问题困难（"魔法"行为） |
+| 性能影响 | 过多触发器影响 DML 性能 |
+| 错误回滚 | 触发器中的错误会回滚外层事务 |
+| 嵌套复杂度 | 不建议在触发器中调用存储过程 |
+
+**优先在应用层实现业务逻辑**，触发器仅用于审计、自动更新时间等必要场景。
+
+## 事务与锁
+
+### ACID 特性
+
+| 特性 | 含义 | MySQL 实现 |
+|------|------|-----------|
+| 原子性 (A) | 事务全部成功或全部回滚 | undo log |
+| 一致性 (C) | 事务前后数据一致 | 约束 + 事务 |
+| 隔离性 (I) | 事务间互相隔离 | MVCC + 锁 |
+| 持久性 (D) | 提交后数据持久保存 | redo log |
+
+### 事务隔离级别
+
+| 隔离级别 | 脏读 | 不可重复读 | 幻读 | 默认？ |
+|---------|------|-----------|------|-------|
+| READ UNCOMMITTED | ✅ 可能 | ✅ 可能 | ✅ 可能 | ❌ |
+| READ COMMITTED | ❌ | ✅ 可能 | ✅ 可能 | ❌（多数公司用） |
+| REPEATABLE READ | ❌ | ❌ | ✅ 可能 | ✅ MySQL 默认 |
+| SERIALIZABLE | ❌ | ❌ | ❌ | ❌（性能差） |
+
+### 事务使用
+
+```sql
+START TRANSACTION;
+  UPDATE account SET balance = balance - 100 WHERE id = 1;
+  UPDATE account SET balance = balance + 100 WHERE id = 2;
+  -- 成功
+  COMMIT;
+  -- 或失败
+  ROLLBACK;
+
+-- 保存点
+START TRANSACTION;
+  INSERT INTO log VALUES ('step1');
+  SAVEPOINT sp1;
+  INSERT INTO log VALUES ('step2');  -- 出错
+  ROLLBACK TO SAVEPOINT sp1;        -- 回退到 sp1
+  INSERT INTO log VALUES ('step3');
+COMMIT;
+```
+
+### 锁类型
+
+| 锁类型 | 说明 | SQL |
+|--------|------|-----|
+| 共享锁 (S) | 允许其他事务读，禁止写 | `SELECT ... LOCK IN SHARE MODE` |
+| 排他锁 (X) | 禁止其他事务读写 | `SELECT ... FOR UPDATE` |
+| 表锁 (READ) | 其他会话可读不可写 | `LOCK TABLES user READ;` |
+| 表锁 (WRITE) | 其他会话不可读写 | `LOCK TABLES user WRITE;` |
+| 乐观锁 | 应用层版本号控制 | `UPDATE SET version+1 WHERE version=:old` |
+
+### 死锁避免
+
+1. **固定访问顺序**：所有事务按相同顺序访问表
+2. **缩短事务时间**：不要在一个事务内执行大量无关操作
+3. **降低隔离级别**：SERIALIZABLE → REPEATABLE READ → READ COMMITTED
+4. **查看死锁**：`SHOW ENGINE INNODB STATUS;`
+
+## 分区表 (Partitioning)
+
+### 分区类型
+
+| 分区类型 | 说明 | 典型场景 |
+|---------|------|---------|
+| RANGE | 按范围分区（最常用） | 时间范围：订单按年/月分区 |
+| LIST | 按值列表分区 | 区域：按 region_id 分区 |
+| HASH | 按哈希函数分区 | 均匀分布：按 id MOD N |
+| KEY | 类似 HASH，MySQL 内部哈希 | 类似 HASH |
+
+### RANGE 分区
+
+```sql
+CREATE TABLE orders_partitioned (
+  id BIGINT NOT NULL,
+  user_id INT NOT NULL,
+  amount DECIMAL(10, 2),
+  created_at DATETIME NOT NULL
+) PARTITION BY RANGE (YEAR(created_at)) (
+  PARTITION p2022 VALUES LESS THAN (2023),
+  PARTITION p2023 VALUES LESS THAN (2024),
+  PARTITION p2024 VALUES LESS THAN (2025),
+  PARTITION p_future VALUES LESS THAN MAXVALUE
+);
+
+-- 添加分区
+ALTER TABLE orders_partitioned ADD PARTITION (PARTITION p2025 VALUES LESS THAN (2026));
+
+-- 删除分区（极快）
+ALTER TABLE orders_partitioned DROP PARTITION p2022;
+```
+
+### LIST / HASH / KEY 分区
+
+```sql
+-- LIST 分区（按区域）
+CREATE TABLE user_region (
+  id INT NOT NULL, name VARCHAR(50), region_id INT NOT NULL
+) PARTITION BY LIST (region_id) (
+  PARTITION p_north VALUES IN (1, 2, 3),
+  PARTITION p_south VALUES IN (4, 5, 6)
+);
+
+-- HASH 分区（按哈希）
+CREATE TABLE logs (
+  id INT NOT NULL, log_data TEXT, created_at DATETIME
+) PARTITION BY HASH (id) PARTITIONS 8;
+
+-- KEY 分区
+CREATE TABLE sessions (
+  id INT NOT NULL, session_data TEXT
+) PARTITION BY KEY (id) PARTITIONS 4;
+```
+
+### 分区修剪 (Partition Pruning)
+
+查询自动只扫描相关分区：
+
+```sql
+EXPLAIN SELECT * FROM orders_partitioned WHERE created_at >= '2024-01-01';
+-- 只扫描 p2024, p_future
+
+ALTER TABLE orders_partitioned TRUNCATE PARTITION p2022;  -- 快速清理历史数据
+```
+
+### 分区注意事项
+
+| 注意点 | 说明 |
+|--------|------|
+| 分区列必须包含在主键中 | MySQL 硬限制 |
+| 分区数建议 | ≤ 1024，单个分区 ≥ 10GB 时效果明显 |
+| 不是越多越好 | 过多分区增加元数据开销 |
+| 最大适用 | 数据归档场景（按时间删除旧分区极快） |

skills/database-skills/oracle/SKILL.md

@@ -1,28 +1,238 @@
 ---
 name: oracle
-description: Provides comprehensive guidance for Oracle database including SQL, PL/SQL, database administration, and Oracle-specific features. Use when the user asks about Oracle, needs to write Oracle SQL, work with PL/SQL, or manage Oracle databases.
+description: Provides comprehensive guidance for Oracle database including SQL, PL/SQL, functions, performance tuning (AWR/ASH), backup (RMAN), Data Guard, and RAC. Use when the user asks about Oracle, needs to write Oracle SQL, work with PL/SQL, or manage Oracle databases.
 license: Complete terms in LICENSE.txt
 ---
 
-## When to use this skill
+# Oracle Database — 企业级关系型数据库
 
-Use this skill whenever the user wants to:
-- 编写 PL/SQL、设计表与索引、优化 SQL 与执行计划
-- 使用 SQL*Plus、SQL Developer、连接与权限管理
-- 处理 RAC、Data Guard、备份与迁移
+Oracle Database 是全球领先的企业级关系型数据库管理系统，以其高可用性、高性能、强安全性及丰富的功能集（RAC、Data Guard、Flashback、高级分区、物化视图等）著称。
 
-## How to use this skill
+## Workflow — 使用决策树
 
-1. **SQL/PL-SQL**：DDL、DML、存储过程、触发器；EXPLAIN PLAN 与 AWR 分析性能。
-2. **工具**：SQL*Plus、SQL Developer；TNS 或 Easy Connect；用户、角色与权限。
-3. **环境**：版本与兼容（如 19c）；生产常用 RAC 与 Data Guard；许可与补丁策略。
+```
+遇到 Oracle 相关需求时，按以下顺序决策:
 
-## Best Practices
+Step 1: 明确场景
+├── 编写 SQL 查询/DDL/DML?       → references/09-sql-syntax.md
+├── 使用内置函数?                  → 字符串/日期/聚合 → references/01-functions-string.md / 02-functions-date.md
+├── 窗口/分析函数?                 → references/03-analytic-functions.md
+├── 编写 PL/SQL?                  → references/04-plsql-guide.md
+├── 性能调优/执行计划?             → references/05-performance-tuning.md
+├── 备份恢复?                     → references/06-backup-recovery.md
+├── Data Guard / RAC?             → references/07-dataguard-rac.md
+├── 安全/权限/审计?                → references/08-security.md
+└── 分区/物化视图/Flashback/AQ?   → references/10-features.md
 
-- 绑定变量防 SQL 注入与硬解析；索引与分区策略按负载设计。
-- 权限与审计配置完善；备份 RMAN 与恢复演练。
-- 监控等待事件与表空间；升级与迁移前充分测试。
+Step 2: 选择工具
+├── 交互式查询 → SQL*Plus / SQL Developer / DBeaver
+├── 批量脚本   → SQL*Plus 静默模式
+├── PL/SQL 调试 → SQL Developer / TOAD / PL/SQL Developer
+└── 自动化运维 → OEM / 脚本
+
+Step 3: 确定环境
+├── 版本 → 19c (LTS), 21c/23c (最新)
+├── 架构 → 单实例 / RAC / Data Guard / RAC+DG
+├── CDB/PDB? → 12c+ 多租户
+└── 字符集 → AL32UTF8, ZHS16GBK
+```
+
+## When to Use / When NOT to
+
+| ✅ Use When | ❌ Skip When |
+|------------|-------------|
+| 企业级事务处理（ACID 严格保证） | 简单键值缓存（用 Redis） |
+| 复杂 SQL、多表 JOIN、报表分析 | 文档存储（用 MongoDB） |
+| PL/SQL 存储过程/包/触发器 | 全文搜索为主（用 Elasticsearch） |
+| 海量数据分区（TB/PB 级） | 实时内存计算（用 Redis/Spark） |
+| 高可用（RAC/Data Guard） | 轻量嵌入式（用 SQLite） |
+| 数据仓库/OLAP 分析 | 时序数据（用 InfluxDB/TimescaleDB） |
+| 数据安全与审计（TDE/FGA/VPD） | 简单 CRUD 快速开发（用 PostgreSQL） |
+| 大规模 OLTP 交易系统 | 仅需文档型层次化数据（用 PostgreSQL JSONB） |
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 |
+|------------|--------------|---------|
+| OLTP/OLAP 混合负载 | 海量非结构化数据（用对象存储） | 代替 Redis 做内存缓存 |
+| 复杂事务与数据一致性 | 跨数据库异构集成（GoldenGate/DB Link） | 实时流处理（Kafka/Storm） |
+| PL/SQL 业务逻辑封装 | 多写场景（RAC 共享存储写） | 简单 CRUD 原型快速迭代 |
+| 数据分区与物化视图 | 地理分布式多活（用 GoldenGate） | 多模型数据统一管理 |
+| RAC 集群高可用 | 超低延迟（<100μs）查询 | 替代搜索引擎做全文搜索 |
+| 细粒度安全审计 | 作为文档数据库存大量 JSON | 替代对象存储 |
+
+超出范围时请考虑：PostgreSQL（开源关系型）、MongoDB（文档）、Redis（缓存）、Elasticsearch（全文搜索）、MySQL（轻量 Web）。
+
+---
+
+## SQL 语法速查
+
+Oracle 的 SQL 差异主要体现在以下方面。完整内容见 `references/09-sql-syntax.md`。
+
+| 特性 | 说明 | 参考文件 |
+|------|------|---------|
+| 数据类型 | VARCHAR2, NUMBER, CLOB, BLOB, TIMESTAMP, INTERVAL | `references/09-sql-syntax.md` |
+| 序列 | `CREATE SEQUENCE` 替代 AUTO_INCREMENT | `references/09-sql-syntax.md` |
+| MERGE | UPSERT（存在则更新，不存在则插入） | `references/09-sql-syntax.md` |
+| INSERT ALL | 多表条件插入 | `references/09-sql-syntax.md` |
+| CONNECT BY | 层次查询（组织树） | `references/09-sql-syntax.md` |
+| PIVOT/UNPIVOT | 行转列/列转行 | `references/09-sql-syntax.md` |
+| LISTAGG | 列转字符串聚合 | `references/09-sql-syntax.md` |
+| MODEL 子句 | 电子表格式跨行计算 | `references/09-sql-syntax.md` |
+| MATCH_RECOGNIZE | 模式匹配（12c+） | `references/09-sql-syntax.md` |
+| FLASHBACK QUERY | 闪回查询历史数据 | `references/09-sql-syntax.md` |
+| WITH (CTE) / 递归 CTE | 公用表表达式 | `references/09-sql-syntax.md` |
+| 伪列 | ROWNUM, ROWID, LEVEL, ORA_ROWSCN | `references/09-sql-syntax.md` |
+| 集合操作 | UNION, INTERSECT, MINUS（Oracle 差集） | `references/09-sql-syntax.md` |
+
+## 函数速查
+
+| 类别 | 关键函数 | 参考文件 |
+|------|---------|---------|
+| 字符串 | SUBSTR, INSTR, REPLACE, REGEXP_LIKE/SUBSTR/REPLACE, TRANSLATE, LISTAGG | `references/01-functions-string.md` |
+| 数字 | ROUND, TRUNC, MOD, CEIL, FLOOR, POWER, GREATEST/LEAST | `references/01-functions-string.md` |
+| 日期 | SYSDATE, EXTRACT, TO_DATE/TO_CHAR, ADD_MONTHS, MONTHS_BETWEEN, LAST_DAY, NEXT_DAY, TRUNC 日期版 | `references/02-functions-date.md` |
+| 转换 | TO_CHAR/TO_NUMBER/TO_DATE, CAST, CONVERT, SCN_TO_TIMESTAMP | `references/02-functions-date.md` |
+| NULL 处理 | NVL, NVL2, COALESCE, NULLIF, LNNVL | `references/01-functions-string.md` |
+| 聚合 | COUNT, SUM, AVG, MEDIAN, STATS_MODE, ROLLUP/CUBE, GROUPING | `references/03-analytic-functions.md` |
+| 分析/窗口 | ROW_NUMBER, RANK, DENSE_RANK, NTILE, LAG/LEAD, FIRST_VALUE/LAST_VALUE, RATIO_TO_REPORT | `references/03-analytic-functions.md` |
+
+---
+
+## 高级特性索引
+
+| 特性 | 说明 | 参考文件 |
+|------|------|---------|
+| PL/SQL 块结构 | DECLARE/BEGIN/EXCEPTION/END | `references/04-plsql-guide.md` |
+| 游标 (Cursor) | 显式/隐式/REF CURSOR/SYS_REFCURSOR | `references/04-plsql-guide.md` |
+| 存储过程/函数 | CREATE OR REPLACE PROCEDURE/FUNCTION | `references/04-plsql-guide.md` |
+| 包 (Package) | 规范+体，封装/重载/全局变量 | `references/04-plsql-guide.md` |
+| 触发器 (Trigger) | DML/INSTEAD OF/DDL/系统事件 | `references/04-plsql-guide.md` |
+| 集合类型 | 关联数组/嵌套表/VARRAY | `references/04-plsql-guide.md` |
+| 动态 SQL | EXECUTE IMMEDIATE / DBMS_SQL / FORALL / BULK COLLECT | `references/04-plsql-guide.md` |
+| 异常处理 | 预定义/自定义/RAISE_APPLICATION_ERROR | `references/04-plsql-guide.md` |
+| EXPLAIN PLAN / DBMS_XPLAN | 执行计划查看与分析 | `references/05-performance-tuning.md` |
+| AWR/ASH/ADDM | 性能历史/活跃会话/自动诊断 | `references/05-performance-tuning.md` |
+| SQL Tuning Advisor | 自动 SQL 优化建议 | `references/05-performance-tuning.md` |
+| DBMS_STATS | 统计信息收集与管理 | `references/05-performance-tuning.md` |
+| SPM (SQL Plan Management) | 执行计划基线管理 | `references/05-performance-tuning.md` |
+| RMAN | 全库/增量备份与恢复 | `references/06-backup-recovery.md` |
+| EXPDP/IMPDP | 逻辑备份导入导出 | `references/06-backup-recovery.md` |
+| 归档日志模式 | ARCHIVELOG / NOARCHIVELOG | `references/06-backup-recovery.md` |
+| Data Guard | 物理备库/逻辑备库/Switchover/Failover | `references/07-dataguard-rac.md` |
+| RAC | 集群/序列配置/全局等待 | `references/07-dataguard-rac.md` |
+| 用户/角色/权限 | 系统权限/对象权限/Profile | `references/08-security.md` |
+| FGA (细粒度审计) | 基于条件的 SQL 审计 | `references/08-security.md` |
+| VPD (虚拟私有数据库) | 行级安全策略 | `references/08-security.md` |
+| 数据脱敏 (Data Redaction) | 动态数据掩码 | `references/08-security.md` |
+| TDE (透明数据加密) | 列级/表空间级加密 | `references/08-security.md` |
+| 表空间与数据文件 | CREATE/ALTER TABLESPACE | `references/10-features.md` |
+| 分区表 | RANGE/LIST/HASH/复合/间隔分区 | `references/10-features.md` |
+| 索引 | B-Tree/位图/函数/域索引 | `references/10-features.md` |
+| 物化视图 | 查询重写/快速刷新/ON COMMIT | `references/10-features.md` |
+| Flashback | 闪回查询/表/删除/数据库 | `references/10-features.md` |
+| AQ (高级队列) | 消息队列 | `references/10-features.md` |
+
+---
+
+## Gotchas — 常见陷阱
+
+| # | 问题 | 风险 | 解决方案 |
+|---|------|------|---------|
+| 1 | ROWNUM ORDER BY 顺序错误 | 不是 Top-N | 子查询排序或 `FETCH FIRST`（12c+） |
+| 2 | 隐式类型转换导致索引失效 | 全表扫描 | `WHERE hire_date = TO_DATE('2024-01-15','YYYY-MM-DD')` |
+| 3 | NOT IN 子查询含 NULL 返回空 | 数据丢失 | 用 `NOT EXISTS` 替代 |
+| 4 | SELECT INTO 无数据抛出 NO_DATA_FOUND | 过程终止 | 提前检查或用 EXCEPTION 捕获 |
+| 5 | 绑定变量窥视 | 执行计划偏差 | 用 ACS / SQL Profile |
+| 6 | 统计信息过旧 | 优化器选错计划 | 定期 `DBMS_STATS` 收集 |
+| 7 | OLTP 用位图索引 | 行锁阻塞 | OLTP 用 B-Tree 索引 |
+| 8 | UPDATE 大量行不用 FORALL | 性能极差 | 用 `FORALL` 批量 DML |
+| 9 | 忽略分区裁剪 | 全分区扫描 | WHERE 条件含分区键 |
+| 10 | 触发器递归/变异表 (ORA-04091) | 触发器失败 | 复合触发器/自治事务/语句级 |
+| 11 | SELECT * 在视图/过程中 | 结构变更后行为异常 | 显式列出列名 |
+| 12 | 大量 DISTINCT 掩盖 JOIN 不当 | 性能开销大 | 检查 JOIN 条件 |
+| 13 | 物化视图 ON COMMIT 刷新影响 DML 性能 | 写操作拖慢 | 建日志 + ON DEMAND 定时刷新 |
+| 14 | WHERE 中对列应用函数 | 索引失效 | 改写为范围查询 |
+| 15 | DBMS_OUTPUT 打印大量数据 | 缓冲区溢出 | 仅调试用，生产用日志表 |
+
+---
+
+## FAQ
+
+**Q1: VARCHAR2 和 NVARCHAR2 区别？**
+VARCHAR2 使用数据库字符集（AL32UTF8/ZHS16GBK），NVARCHAR2 使用国家字符集（AL16UTF16）。推荐一般场景用 VARCHAR2，多语言用 NVARCHAR2。
+
+**Q2: ROWNUM 和 ROW_NUMBER() 区别？**
+ROWNUM 是伪列（先分配后排序），ROW_NUMBER() 是分析函数（排序后分配序号）。
+
+**Q3: Oracle vs PostgreSQL 主要差异？**
+| 特性 | Oracle | PostgreSQL |
+|------|--------|-----------|
+| 自增 | SEQUENCE / IDENTITY (12c+) | SERIAL / GENERATED AS IDENTITY |
+| 字符串 | VARCHAR2 | VARCHAR / TEXT |
+| 空串 | '' = NULL | '' ≠ NULL |
+| 递归 | CONNECT BY / WITH RECURSIVE | WITH RECURSIVE |
+| 分页 | ROWNUM / FETCH FIRST | LIMIT/OFFSET |
+| UPSERT | MERGE | INSERT...ON CONFLICT |
+| 表空间 | 有 | 无 |
+
+**Q4: UNDO 和 REDO 区别？**
+REDO 记录变更（重做/恢复），UNDO 记录变更前数据（回滚/一致性读/闪回）。
+
+**Q5: 何时用物化视图？**
+查询大聚合可接受延迟、基表变更不频繁、需要跨数据库缓存、需要查询重写。
+
+**Q6: 分区表常见误区？**
+分区不保证查询加速（需分区键）、不能解决所有大表问题、分区不是越多越好、OLTP 也适合分区。
+
+**Q7: 什么是读一致性？**
+Oracle 通过 UNDO 实现 SELECT 不加锁也不被写阻塞，查询使用查询开始时的 SCN 读取一致性版本。
+
+**Q8: 死锁如何处理？**
+Oracle 3 秒内自动检测，回滚牺牲品语句并抛 ORA-00060。最佳实践：统一访问顺序、事务简短。
+
+**Q9: CDB 和 PDB 是什么？**
+12c+ 多租户：CDB = 容器数据库，PDB = 可插拔数据库。一个 CDB 最多 4096 个 PDB。
+
+**Q10: KILL SESSION 后连接未断开？**
+标记为 KILLED，下次执行 SQL 时断开。`KILL SESSION 'sid,serial#' IMMEDIATE` 可立即断开。
+
+**Q11: REDO 日志切换太频繁？**
+增加 REDO 日志大小（建议 15-30 分钟切换一次）、增加日志组数（至少 3-4 组）。
+
+**Q12: ORA-01555 "Snapshot Too Old"？**
+UNDO 数据被覆盖。增大 UNDO 表空间、减少 UNDO_RETENTION、优化长查询。
+
+**Q13: Oracle 中如何实现分页？**
+`SELECT * FROM (SELECT t.*, ROWNUM AS rn FROM (SELECT ... ORDER BY col) t) WHERE rn BETWEEN 11 AND 20` 或 12c+ `OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY`。
+
+**Q14: 什么是 FORCE LOGGING？**
+强制所有 DML 写 REDO（即使是 NOLOGGING 操作），Data Guard 环境要求开启。
+
+**Q15: 如何查看当前数据库版本？**
+`SELECT * FROM v$version;` 或 `SELECT banner FROM v$version WHERE banner LIKE 'Oracle%';`
+
+---
 
 ## Keywords
 
-oracle, PL/SQL, SQL*Plus, 关系型数据库, RAC, Data Guard
+oracle, Oracle Database, PL/SQL, SQL*Plus, RAC, Data Guard, ADG, RMAN, expdp, impdp, flashback, AWR, ASH, ADDM, DBMS_XPLAN, VARCHAR2, NUMBER, CLOB, SEQUENCE, SYNONYM, CONNECT BY, PIVOT, LISTAGG, MERGE, INSERT ALL, MODEL, MATCH_RECOGNIZE, 分析函数, 窗口函数, ROW_NUMBER, RANK, LAG, LEAD, 存储过程, 包, 触发器, 游标, REF CURSOR, 动态SQL, FORALL, BULK COLLECT, 分区表, 物化视图, 位图索引, 表空间, TDE, FGA, VPD, DBMS_STATS, SPM, CDB, PDB, 多租户, UNDO, REDO, 读一致性, ORA-01555
+
+## References
+
+- `references/01-functions-string.md` — 字符串/数字/NULL 处理函数
+- `references/02-functions-date.md` — 日期/转换函数
+- `references/03-analytic-functions.md` — 分析函数（窗口函数）+ 聚合
+- `references/04-plsql-guide.md` — PL/SQL 详解
+- `references/05-performance-tuning.md` — 性能调优
+- `references/06-backup-recovery.md` — 备份恢复
+- `references/07-dataguard-rac.md` — Data Guard / RAC
+- `references/08-security.md` — 安全与权限
+- `references/09-sql-syntax.md` — SQL 语法详解
+- `references/10-features.md` — 特有特性（分区/物化视图/Flashback/AQ）
+- `examples/01-plsql-procedure.md` — PL/SQL 存储过程示例
+- `examples/02-awr-analysis.md` — AWR 性能分析示例
+- `examples/03-rman-backup.md` — RMAN 备份示例
+- `examples/04-dataguard-setup.md` — Data Guard 搭建示例
+- [Oracle 19c 官方文档](https://docs.oracle.com/en/database/oracle/oracle-database/19/)
+- [Oracle Live SQL (在线练习)](https://livesql.oracle.com/)

skills/database-skills/oracle/examples/01-plsql-procedure.md

@@ -0,0 +1,90 @@
+# 示例：PL/SQL 存储过程 — 员工薪资管理包
+
+## 场景
+
+创建一个完整的员工薪资管理包，支持涨薪、查询年收入、批量调整部门薪资。
+
+## 包规范
+
+```sql
+CREATE OR REPLACE PACKAGE salary_mgmt AS
+    -- 涨薪
+    PROCEDURE give_raise(p_emp_id NUMBER, p_percent NUMBER);
+    -- 查询年收入
+    FUNCTION annual_income(p_emp_id NUMBER) RETURN NUMBER;
+    -- 批量调整部门薪资
+    PROCEDURE dept_raise(p_dept_id NUMBER, p_percent NUMBER);
+    -- 获取部门薪资统计
+    FUNCTION dept_stats(p_dept_id NUMBER) RETURN SYS_REFCURSOR;
+END salary_mgmt;
+/
+```
+
+## 包体
+
+```sql
+CREATE OR REPLACE PACKAGE BODY salary_mgmt AS
+
+    PROCEDURE give_raise(p_emp_id NUMBER, p_percent NUMBER) AS
+        v_old_sal employees.salary%TYPE;
+    BEGIN
+        SELECT salary INTO v_old_sal FROM employees WHERE employee_id = p_emp_id FOR UPDATE;
+        UPDATE employees SET salary = salary * (1 + p_percent/100) WHERE employee_id = p_emp_id;
+        DBMS_OUTPUT.PUT_LINE('员工 ' || p_emp_id || ': ' || v_old_sal || ' → ' || ROUND(v_old_sal*(1+p_percent/100),2));
+        COMMIT;
+    EXCEPTION
+        WHEN NO_DATA_FOUND THEN
+            RAISE_APPLICATION_ERROR(-20001, '员工 ' || p_emp_id || ' 不存在');
+        WHEN OTHERS THEN ROLLBACK; RAISE;
+    END;
+
+    FUNCTION annual_income(p_emp_id NUMBER) RETURN NUMBER AS
+        v_sal employees.salary%TYPE;
+        v_comm employees.commission_pct%TYPE;
+    BEGIN
+        SELECT salary, NVL(commission_pct, 0) INTO v_sal, v_comm
+        FROM employees WHERE employee_id = p_emp_id;
+        RETURN v_sal * 12 + v_sal * NVL(v_comm, 0);
+    END;
+
+    PROCEDURE dept_raise(p_dept_id NUMBER, p_percent NUMBER) AS
+    BEGIN
+        UPDATE employees SET salary = salary * (1 + p_percent/100)
+        WHERE department_id = p_dept_id;
+        DBMS_OUTPUT.PUT_LINE('部门 ' || p_dept_id || ' 已更新 ' || SQL%ROWCOUNT || ' 行');
+        COMMIT;
+    END;
+
+    FUNCTION dept_stats(p_dept_id NUMBER) RETURN SYS_REFCURSOR AS
+        c SYS_REFCURSOR;
+    BEGIN
+        OPEN c FOR SELECT employee_id, last_name, salary,
+                          annual_income(employee_id) AS annual
+                   FROM employees WHERE department_id = p_dept_id
+                   ORDER BY salary DESC;
+        RETURN c;
+    END;
+
+END salary_mgmt;
+/
+```
+
+## 调用示例
+
+```sql
+-- 单员工涨薪 10%
+BEGIN salary_mgmt.give_raise(100, 10); END;
+/
+
+-- 查询年收入
+SELECT salary_mgmt.annual_income(100) FROM DUAL;
+
+-- 部门批量涨薪 5%
+BEGIN salary_mgmt.dept_raise(50, 5); END;
+/
+
+-- 获取部门薪资统计
+VARIABLE c REFCURSOR;
+EXEC :c := salary_mgmt.dept_stats(50);
+PRINT c;
+```

skills/database-skills/oracle/examples/02-awr-analysis.md

@@ -0,0 +1,99 @@
+# 示例：AWR 性能分析 — 定位 Top SQL 与等待事件
+
+## 场景
+
+某生产数据库近期响应变慢，需要通过 AWR/ASH 分析找到性能瓶颈。
+
+## 步骤 1：创建 AWR 快照
+
+```sql
+-- 在性能问题期间创建快照
+EXEC DBMS_WORKLOAD_REPOSITORY.CREATE_SNAPSHOT();
+
+-- 等待一段时间（比如 30 分钟）后再次创建
+EXEC DBMS_WORKLOAD_REPOSITORY.CREATE_SNAPSHOT();
+```
+
+## 步骤 2：生成 AWR 报告
+
+```sql
+-- 查找快照 ID
+SELECT snap_id, begin_interval_time, end_interval_time
+FROM dba_hist_snapshot
+ORDER BY snap_id DESC FETCH FIRST 5 ROWS ONLY;
+
+-- 生成 HTML 格式 AWR 报告
+-- 假设 snap_id 分别为 1250 和 1255
+SELECT * FROM TABLE(DBMS_WORKLOAD_REPOSITORY.AWR_REPORT_HTML(
+    l_dbid     => (SELECT dbid FROM v$database),
+    l_inst_num => 1,
+    l_bid      => 1250,
+    l_eid      => 1255,
+    l_options  => 0
+));
+```
+
+## 步骤 3：ASH 分析 — Top 等待事件
+
+```sql
+-- 最近 10 分钟的 Top 等待事件
+SELECT event, wait_class, COUNT(*) AS session_seconds,
+       ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS pct
+FROM v$active_session_history
+WHERE sample_time > SYSTIMESTAMP - INTERVAL '10' MINUTE
+GROUP BY event, wait_class
+ORDER BY session_seconds DESC;
+```
+
+## 步骤 4：定位 Top SQL
+
+```sql
+-- 按消耗找 Top SQL
+SELECT sql_id,
+       ROUND(SUM(elapsed_time)/1000000, 2) AS total_sec,
+       COUNT(*) AS executions,
+       ROUND(AVG(elapsed_time)/1000, 2) AS avg_ms,
+       SUBSTR(MAX(sql_text), 1, 100) AS sql_sample
+FROM v$active_session_history ash
+JOIN v$sql sq USING (sql_id)
+WHERE sample_time > SYSTIMESTAMP - INTERVAL '30' MINUTE
+  AND sql_id IS NOT NULL
+GROUP BY sql_id
+ORDER BY total_sec DESC
+FETCH FIRST 5 ROWS ONLY;
+```
+
+## 步骤 5：分析特定 SQL 的执行计划
+
+```sql
+-- 查看 Top SQL 的执行计划
+-- 假设 Top SQL 的 sql_id 为 'abc123xyz4567'
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY_CURSOR(sql_id => 'abc123xyz4567', format => 'ALLSTATS LAST'));
+```
+
+## 步骤 6：使用 SQL Tuning Advisor
+
+```sql
+DECLARE
+    v_task VARCHAR2(30);
+BEGIN
+    v_task := DBMS_SQLTUNE.CREATE_TUNING_TASK(
+        sql_id => 'abc123xyz4567',
+        scope  => DBMS_SQLTUNE.SCOPE_COMPREHENSIVE,
+        time_limit => 300
+    );
+    DBMS_SQLTUNE.EXECUTE_TUNING_TASK(task_name => v_task);
+    DBMS_OUTPUT.PUT_LINE('Task: ' || v_task);
+END;
+/
+
+-- 查看建议
+SELECT DBMS_SQLTUNE.REPORT_TUNING_TASK(task_name => 'task_name_here') FROM DUAL;
+```
+
+## 分析要点
+
+- `db file sequential read` — 单块读等待，通常是索引扫描
+- `log file sync` — 提交等待，检查小事务频繁提交
+- `enq: TX - row lock contention` — 行锁争用，检查并发更新相同行
+- `read by other session` — 缓存争用，考虑调整 buffer cache

skills/database-skills/oracle/examples/03-rman-backup.md

@@ -0,0 +1,108 @@
+# 示例：RMAN 备份策略 — 每周全量 + 每日增量
+
+## 场景
+
+为生产库制定一套完整的备份策略：每周日凌晨 Level 0 全量备份，周一至周六 Level 1 增量备份，同时备份归档日志。
+
+## RMAN 配置
+
+```bash
+# 登录 RMAN
+rman target /
+
+# 配置备份策略（保留最近 7 天可恢复）
+RMAN> CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 7 DAYS;
+
+# 启用控制文件自动备份
+RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON;
+
+# 启用备份优化（跳过未变更文件）
+RMAN> CONFIGURE BACKUP OPTIMIZATION ON;
+
+# 设置备份格式
+RMAN> CONFIGURE CHANNEL DEVICE TYPE DISK FORMAT '/backup/orcl/%U';
+
+# 设置设备类型和并行度
+RMAN> CONFIGURE DEVICE TYPE DISK PARALLELISM 2;
+```
+
+## 周日：Level 0 全量备份
+
+```bash
+rman target / <<EOF
+RUN {
+    ALLOCATE CHANNEL c1 DEVICE TYPE DISK;
+    ALLOCATE CHANNEL c2 DEVICE TYPE DISK;
+    BACKUP INCREMENTAL LEVEL 0 DATABASE
+        TAG 'LEVEL0_WEEKLY'
+        FORMAT '/backup/orcl/full_%d_%T_%s_%p.bkp';
+    BACKUP ARCHIVELOG ALL DELETE INPUT
+        FORMAT '/backup/orcl/arch_%d_%T_%s.bkp';
+    BACKUP CURRENT CONTROLFILE
+        FORMAT '/backup/orcl/ctrl_%d_%T_%s.bkp';
+    RELEASE CHANNEL c1;
+    RELEASE CHANNEL c2;
+}
+EOF
+```
+
+## 周一至周六：Level 1 增量备份
+
+```bash
+rman target / <<EOF
+BACKUP INCREMENTAL LEVEL 1 DATABASE
+    TAG 'LEVEL1_DAILY'
+    FORMAT '/backup/orcl/incr_%d_%T_%s_%p.bkp';
+BACKUP ARCHIVELOG ALL DELETE INPUT
+    FORMAT '/backup/orcl/arch_%d_%T_%s.bkp';
+EOF
+```
+
+## 验证备份
+
+```bash
+# 验证所有备份是否可恢复
+rman target /
+RMAN> RESTORE DATABASE VALIDATE;
+
+# 列出备份集
+RMAN> LIST BACKUP SUMMARY;
+RMAN> LIST BACKUP OF DATABASE;
+
+# 检查特定备份是否可用
+RMAN> VALIDATE BACKUPSET <bs_key>;
+```
+
+## 模拟恢复
+
+```bash
+# 完全恢复（全量+增量自动应用）
+rman target /
+RMAN> STARTUP MOUNT;
+RMAN> RESTORE DATABASE;
+RMAN> RECOVER DATABASE;
+RMAN> ALTER DATABASE OPEN;
+
+# 时间点恢复（恢复到某个时间点）
+rman target /
+RMAN> STARTUP MOUNT;
+RMAN> RESTORE DATABASE UNTIL TIME "TO_DATE('2024-08-15 14:30:00','YYYY-MM-DD HH24:MI:SS')";
+RMAN> RECOVER DATABASE UNTIL TIME "TO_DATE('2024-08-15 14:30:00','YYYY-MM-DD HH24:MI:SS')";
+RMAN> ALTER DATABASE OPEN RESETLOGS;
+```
+
+## Cron 调度
+
+```bash
+# 编辑 crontab
+# crontab -e
+
+# 每周日凌晨 1:00 执行全量备份
+0 1 * * 0 /u01/scripts/full_backup.sh >> /u01/logs/rman_full.log 2>&1
+
+# 每天凌晨 2:00 执行增量备份（周日除外）
+0 2 * * 1-6 /u01/scripts/incr_backup.sh >> /u01/logs/rman_incr.log 2>&1
+
+# 每天凌晨 3:00 验证备份
+0 3 * * * /u01/scripts/validate_backup.sh >> /u01/logs/rman_val.log 2>&1
+```

skills/database-skills/oracle/examples/04-dataguard-setup.md

@@ -0,0 +1,146 @@
+# 示例：Data Guard 物理备库搭建
+
+## 场景
+
+生产库 PRIMARY (host1) 需要搭建一个物理备库 STANDBY (host2) 实现高可用，使用实时应用（Real-Time Apply）。
+
+## 前提条件
+
+- 主库已启用归档模式 (`SELECT log_mode FROM v$database;` 返回 `ARCHIVELOG`)
+- 主备库 Oracle 版本一致
+- 主备库网络互通（1521 端口）
+- 主库已设置 `FORCE LOGGING`
+
+## 步骤 1：主库参数配置
+
+```sql
+-- 设置 DB_UNIQUE_NAME
+ALTER SYSTEM SET LOG_ARCHIVE_CONFIG='DG_CONFIG=(PRIMARY,STANDBY)' SCOPE=BOTH;
+ALTER SYSTEM SET DB_UNIQUE_NAME=PRIMARY SCOPE=SPFILE;
+
+-- 设置归档目的地
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_1='LOCATION=/u01/archivelog/orcl VALID_FOR=(ALL_LOGFILES,ALL_ROLES) DB_UNIQUE_NAME=PRIMARY' SCOPE=BOTH;
+
+-- 备库归档传输（使用 ASYNC 模式，不影响主库性能）
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_2='SERVICE=standby_host:1521/orcl LGWR ASYNC VALID_FOR=(ONLINE_LOGFILES,PRIMARY_ROLE) DB_UNIQUE_NAME=STANDBY' SCOPE=BOTH;
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_STATE_2=ENABLE SCOPE=BOTH;
+
+-- 网络配置
+ALTER SYSTEM SET FAL_CLIENT='PRIMARY' SCOPE=BOTH;
+ALTER SYSTEM SET FAL_SERVER='STANDBY' SCOPE=BOTH;
+
+-- 文件路径转换
+ALTER SYSTEM SET DB_FILE_NAME_CONVERT='/u01/oradata/orcl/','/u02/oradata/orcl/' SCOPE=SPFILE;
+ALTER SYSTEM SET LOG_FILE_NAME_CONVERT='/u01/oradata/orcl/','/u02/oradata/orcl/' SCOPE=SPFILE;
+
+-- 启用手动备库文件管理
+ALTER SYSTEM SET STANDBY_FILE_MANAGEMENT=AUTO SCOPE=BOTH;
+
+-- 重启数据库使 SPFILE 参数生效
+SHUTDOWN IMMEDIATE;
+STARTUP;
+```
+
+## 步骤 2：准备备库
+
+```text
+# 备库 $ORACLE_HOME/network/admin/tnsnames.ora 配置
+PRIMARY =
+  (DESCRIPTION =
+    (ADDRESS = (PROTOCOL = TCP)(HOST = primary_host)(PORT = 1521))
+    (CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = orcl))
+  )
+
+STANDBY =
+  (DESCRIPTION =
+    (ADDRESS = (PROTOCOL = TCP)(HOST = standby_host)(PORT = 1521))
+    (CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = orcl))
+  )
+
+# 备库 $ORACLE_HOME/network/admin/listener.ora 配置
+LISTENER =
+  (DESCRIPTION =
+    (ADDRESS = (PROTOCOL = TCP)(HOST = standby_host)(PORT = 1521))
+  )
+```
+
+```sql
+-- 备库参数文件（在备库创建 pfile，修改 db_unique_name）
+-- 修改 /u01/app/oracle/admin/orcl/pfile/init.ora
+-- *.db_unique_name='STANDBY'
+```
+
+## 步骤 3：使用 RMAN DUPLICATE 创建备库
+
+```bash
+# 在主库执行
+rman target sys/password@PRIMARY auxiliary sys/password@STANDBY <<EOF
+DUPLICATE TARGET DATABASE FOR STANDBY
+  FROM ACTIVE DATABASE
+  DORECOVER
+  SPFILE
+    SET db_unique_name='STANDBY' COMMENT 'Standby'
+    SET LOG_ARCHIVE_DEST_1='LOCATION=/u01/archivelog/orcl VALID_FOR=(ALL_LOGFILES,ALL_ROLES) DB_UNIQUE_NAME=STANDBY'
+    SET LOG_ARCHIVE_DEST_2='SERVICE=primary_host:1521/orcl LGWR ASYNC VALID_FOR=(ONLINE_LOGFILES,PRIMARY_ROLE) DB_UNIQUE_NAME=PRIMARY'
+    SET FAL_CLIENT='STANDBY'
+    SET FAL_SERVER='PRIMARY'
+    SET DB_FILE_NAME_CONVERT='/u02/oradata/orcl/','/u01/oradata/orcl/'
+    SET LOG_FILE_NAME_CONVERT='/u02/oradata/orcl/','/u01/oradata/orcl/'
+  NOFILENAMECHECK;
+EOF
+```
+
+## 步骤 4：启动备库实时应用
+
+```sql
+-- 备库启动到 MOUNT 状态
+STARTUP MOUNT;
+
+-- 启用实时应用（备库自动应用归档日志）
+ALTER DATABASE RECOVER MANAGED STANDBY DATABASE USING CURRENT LOGFILE DISCONNECT;
+
+-- 验证实时应用状态
+SELECT process, status, sequence# FROM v$managed_standby;
+-- 预期看到 MRP0 进程状态为 APPLYING_LOG
+```
+
+## 步骤 5：启用 Active Data Guard（可选）
+
+```sql
+-- 备库只读打开（19c 及以前）
+ALTER DATABASE OPEN READ ONLY;
+ALTER DATABASE RECOVER MANAGED STANDBY DATABASE DISCONNECT;
+-- 此时备库以只读方式打开，同时应用日志
+
+-- 验证备库可用
+SELECT database_role, open_mode FROM v$database;
+-- 预期返回: PHYSICAL STANDBY / READ ONLY WITH APPLY
+```
+
+## 步骤 6：验证同步状态
+
+```sql
+-- 主库查询
+SELECT database_role, open_mode FROM v$database;
+SELECT dest_name, status, error FROM v$archive_dest WHERE dest_name LIKE '%DEST_2';
+
+-- 备库查询日志应用延迟
+SELECT name, value, time_computed FROM v$dataguard_stats WHERE name LIKE '%lag%';
+-- apply_lag: 应用延迟（秒）
+-- transport_lag: 传输延迟（秒）
+```
+
+## 步骤 7：Switchover 切换（计划内）
+
+```bash
+# 主库操作
+sqlplus / as sysdba
+ALTER DATABASE COMMIT TO SWITCHOVER TO STANDBY;
+SHUTDOWN IMMEDIATE;
+STARTUP MOUNT;
+
+# 备库操作
+sqlplus / as sysdba
+ALTER DATABASE COMMIT TO SWITCHOVER TO PRIMARY;
+ALTER DATABASE OPEN;
+```

skills/database-skills/oracle/references/01-functions-string.md

@@ -0,0 +1,91 @@
+# 字符串 / 数字 / NULL 处理函数
+
+## 字符串函数
+
+```sql
+-- CONCAT / || — 字符串连接
+SELECT 'Hello' || ' ' || 'World' FROM DUAL;          -- Hello World (推荐 ||)
+
+-- SUBSTR — 截取子串
+SELECT SUBSTR('Oracle Database', 1, 6) FROM DUAL;    -- Oracle
+SELECT SUBSTR('Oracle Database', 8) FROM DUAL;       -- Database
+
+-- INSTR — 查找子串位置
+SELECT INSTR('oracleoracle', 'oracle') FROM DUAL;               -- 1
+SELECT INSTR('oracleoracle', 'oracle', 1, 2) FROM DUAL;         -- 7（第 2 次出现）
+
+-- LPAD / RPAD — 左/右填充
+SELECT LPAD('123', 10, '*') FROM DUAL;                           -- *******123
+SELECT RPAD('Oracle', 10, '-.-') FROM DUAL;                      -- Oracle-.-.-
+
+-- TRIM / LTRIM / RTRIM — 去除空格/字符
+SELECT TRIM('  Hello  ') FROM DUAL;                              -- Hello
+SELECT LTRIM('xxxHello', 'x') FROM DUAL;                         -- Hello
+SELECT RTRIM('Hello...', '.') FROM DUAL;                         -- Hello
+
+-- REPLACE — 替换子串
+SELECT REPLACE('Oracle Database 19c', '19c', '23c') FROM DUAL;  -- Oracle Database 23c
+
+-- TRANSLATE — 字符级替换
+SELECT TRANSLATE('12345', '123', 'abc') FROM DUAL;               -- abc45
+
+-- 正则表达式系列
+-- REGEXP_LIKE  — 正则匹配
+SELECT * FROM employees WHERE REGEXP_LIKE(email, '^[A-Z]');
+-- REGEXP_SUBSTR — 正则提取子串
+SELECT REGEXP_SUBSTR('contact@oracle.com', '@[^.]+\\.com') FROM DUAL;
+-- REGEXP_REPLACE — 正则替换（手机号脱敏）
+SELECT REGEXP_REPLACE('13812345678', '(\d{3})\d{4}(\d{4})', '\1****\2') FROM DUAL;
+-- REGEXP_INSTR  — 正则查找位置
+SELECT REGEXP_INSTR('Hello World', '[aeiou]') FROM DUAL;         -- 2
+```
+
+## 数字函数
+
+```sql
+-- ROUND — 四舍五入
+SELECT ROUND(123.4567) FROM DUAL;      -- 123
+SELECT ROUND(123.4567, 2) FROM DUAL;   -- 123.46
+SELECT ROUND(123.4567, -2) FROM DUAL;  -- 100
+
+-- TRUNC — 截断（不四舍五入）
+SELECT TRUNC(123.4567) FROM DUAL;      -- 123
+SELECT TRUNC(123.4567, 2) FROM DUAL;   -- 123.45
+
+-- MOD — 取模
+SELECT MOD(10, 3) FROM DUAL;           -- 1
+
+-- ABS / CEIL / FLOOR
+SELECT ABS(-10) FROM DUAL;             -- 10
+SELECT CEIL(3.14) FROM DUAL;           -- 4
+SELECT FLOOR(3.14) FROM DUAL;          -- 3
+
+-- POWER / SQRT
+SELECT POWER(2, 10) FROM DUAL;         -- 1024
+SELECT SQRT(144) FROM DUAL;            -- 12
+
+-- GREATEST / LEAST
+SELECT GREATEST(10, 20, 5, 30) FROM DUAL;  -- 30
+SELECT LEAST(10, 20, 5, 30) FROM DUAL;     -- 5
+```
+
+## NULL 处理函数
+
+```sql
+-- NVL — 空值替换（2 个参数）
+SELECT last_name, NVL(commission_pct, 0) AS commission FROM employees;
+
+-- NVL2 — 空值条件（3 个参数）
+SELECT last_name, NVL2(commission_pct, '有佣金', '无佣金') AS status FROM employees;
+
+-- COALESCE — 返回第一个非空值（可变参数）
+SELECT COALESCE(phone_number, email, '无联系方式') AS contact FROM employees;
+
+-- NULLIF — 两值相等返回 NULL
+SELECT NULLIF('A', 'B') FROM DUAL;  -- 'A'
+SELECT NULLIF('A', 'A') FROM DUAL;  -- NULL
+
+-- LNNVL — 反转条件结果（对 NULL 敏感）
+SELECT * FROM employees WHERE LNNVL(commission_pct > 0.2);
+-- 等价于: WHERE commission_pct IS NULL OR commission_pct <= 0.2
+```

skills/database-skills/oracle/references/02-functions-date.md

@@ -0,0 +1,71 @@
+# 日期 / 转换函数
+
+## 日期函数
+
+```sql
+-- 当前日期时间
+SELECT SYSDATE FROM DUAL;              -- 当前系统日期时间
+SELECT CURRENT_DATE FROM DUAL;         -- 当前会话时区日期时间
+SELECT SYSTIMESTAMP FROM DUAL;         -- 当前系统时间戳（带时区）
+
+-- EXTRACT — 提取日期部分
+SELECT EXTRACT(YEAR FROM SYSDATE) FROM DUAL;
+SELECT EXTRACT(MONTH FROM SYSDATE) FROM DUAL;
+SELECT EXTRACT(DAY FROM SYSDATE) FROM DUAL;
+SELECT EXTRACT(HOUR FROM SYSTIMESTAMP) FROM DUAL;
+
+-- TO_DATE — 字符串转日期
+SELECT TO_DATE('2024-01-15', 'YYYY-MM-DD') FROM DUAL;
+SELECT TO_DATE('2024/01/15 14:30:00', 'YYYY/MM/DD HH24:MI:SS') FROM DUAL;
+SELECT TO_DATE('15-JAN-24', 'DD-MON-YY') FROM DUAL;
+
+-- TO_CHAR — 日期格式化
+SELECT TO_CHAR(SYSDATE, 'YYYY-MM-DD') FROM DUAL;
+SELECT TO_CHAR(SYSDATE, 'YYYY-MM-DD HH24:MI:SS') FROM DUAL;
+SELECT TO_CHAR(SYSDATE, 'MONTH DD, YYYY') FROM DUAL;
+SELECT TO_CHAR(SYSDATE, 'Dy') FROM DUAL;    -- 星期缩写
+
+-- ADD_MONTHS — 加减月份
+SELECT ADD_MONTHS(SYSDATE, 3) FROM DUAL;
+SELECT ADD_MONTHS(SYSDATE, -6) FROM DUAL;
+
+-- MONTHS_BETWEEN — 月份间隔
+SELECT MONTHS_BETWEEN(DATE '2024-12-31', DATE '2024-01-01') FROM DUAL;
+
+-- LAST_DAY — 月末日期
+SELECT LAST_DAY(SYSDATE) FROM DUAL;
+
+-- NEXT_DAY — 下一个星期几
+SELECT NEXT_DAY(SYSDATE, 'FRIDAY') FROM DUAL;
+
+-- TRUNC 日期版 — 截断到指定精度
+SELECT TRUNC(SYSDATE) FROM DUAL;                          -- 当天 00:00:00
+SELECT TRUNC(SYSDATE, 'MONTH') FROM DUAL;                 -- 当月第一天
+SELECT TRUNC(SYSDATE, 'YEAR') FROM DUAL;                  -- 当年第一天
+SELECT TRUNC(SYSDATE, 'IW') FROM DUAL;                    -- 当周周一（ISO 周）
+
+-- 时间间隔
+SELECT SYSDATE + TO_YMINTERVAL('01-06') FROM DUAL;        -- 加 1年6个月
+SELECT SYSDATE + TO_DSINTERVAL('3 12:00:00') FROM DUAL;   -- 加 3天12小时
+```
+
+## 转换函数
+
+```sql
+-- TO_CHAR — 数字格式化
+SELECT TO_CHAR(1234567.89, 'FM999,999,999.00') FROM DUAL;  -- 1,234,567.89
+SELECT TO_CHAR(1234567.89, 'FML999,999,999.00') FROM DUAL; -- $1,234,567.89
+
+-- TO_NUMBER — 字符串转数字
+SELECT TO_NUMBER('1,234.56', '999,999.99') FROM DUAL;     -- 1234.56
+
+-- CAST — ANSI SQL 标准类型转换
+SELECT CAST('12345' AS NUMBER) FROM DUAL;
+SELECT CAST('2024-01-15' AS DATE) FROM DUAL;
+
+-- CONVERT — 字符集转换
+SELECT CONVERT('Oracle', 'AL32UTF8', 'ZHS16GBK') FROM DUAL;
+
+-- SCN_TO_TIMESTAMP / TIMESTAMP_TO_SCN — SCN 与时间互转
+SELECT SCN_TO_TIMESTAMP(ORA_ROWSCN) FROM employees WHERE employee_id = 100;
+```

skills/database-skills/oracle/references/03-analytic-functions.md

@@ -0,0 +1,103 @@
+# 分析函数（窗口函数）+ 聚合
+
+分析函数是 Oracle 最强大的功能之一，在不改变行数的情况下进行聚合计算。
+
+## 聚合函数
+
+```sql
+-- 基础聚合
+SELECT COUNT(*) FROM employees;                     -- 总行数
+SELECT COUNT(commission_pct) FROM employees;        -- 非 NULL 行数
+SELECT SUM(salary) FROM employees;
+SELECT AVG(salary) FROM employees;
+SELECT MAX(hire_date) FROM employees;
+SELECT MIN(hire_date) FROM employees;
+
+-- MEDIAN — 中位数
+SELECT MEDIAN(salary) FROM employees;
+
+-- STATS_MODE — 众数
+SELECT STATS_MODE(department_id) FROM employees;
+
+-- GROUP BY ROLLUP / CUBE（小计+总计）
+SELECT department_id, job_id, SUM(salary)
+FROM employees
+WHERE department_id IN (50, 80)
+GROUP BY ROLLUP(department_id, job_id);   -- 小计 + 总计
+
+SELECT department_id, job_id, SUM(salary)
+FROM employees
+WHERE department_id IN (50, 80)
+GROUP BY CUBE(department_id, job_id);    -- 所有维度小计
+
+-- GROUPING — 区分 NULL 是数据值还是小计行
+SELECT department_id, job_id, SUM(salary),
+       CASE WHEN GROUPING(department_id)=1 THEN '总计'
+            WHEN GROUPING(job_id)=1 THEN '小计'
+            ELSE '明细'
+       END AS rollup_level
+FROM employees GROUP BY ROLLUP(department_id, job_id);
+```
+
+## 分析函数（窗口函数）
+
+### 排序函数
+
+```sql
+-- ROW_NUMBER — 唯一序号
+SELECT department_id, last_name, salary,
+       ROW_NUMBER() OVER (PARTITION BY department_id ORDER BY salary DESC) AS seq
+FROM employees;
+
+-- RANK / DENSE_RANK — 排名（允许并列）
+SELECT department_id, last_name, salary,
+       RANK()       OVER (PARTITION BY department_id ORDER BY salary DESC) AS rank,
+       DENSE_RANK() OVER (PARTITION BY department_id ORDER BY salary DESC) AS dense_rank
+FROM employees;
+-- RANK: 1,2,2,4   DENSE_RANK: 1,2,2,3
+
+-- NTILE — 分桶
+SELECT customer_id, amount,
+       NTILE(5) OVER (ORDER BY amount DESC) AS bucket
+FROM orders;
+```
+
+### 前后行访问
+
+```sql
+-- LAG — 访问前一行（环比计算）
+SELECT hire_date, salary,
+       LAG(salary, 1, 0) OVER (ORDER BY hire_date) AS prev_salary,
+       salary - LAG(salary, 1, 0) OVER (ORDER BY hire_date) AS diff
+FROM employees;
+
+-- LEAD — 访问后一行
+SELECT hire_date, salary,
+       LEAD(salary, 1) OVER (ORDER BY hire_date) AS next_salary
+FROM employees;
+```
+
+### 窗口聚合
+
+```sql
+-- FIRST_VALUE / LAST_VALUE — 窗口首尾行
+SELECT department_id, last_name, salary,
+       FIRST_VALUE(salary) OVER (PARTITION BY department_id
+           ORDER BY salary DESC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS max_in_dept
+FROM employees;
+
+-- 累计求和
+SELECT sale_date, amount,
+       SUM(amount) OVER (ORDER BY sale_date) AS running_total
+FROM daily_sales;
+
+-- 移动平均（7 日）
+SELECT sale_date, amount,
+       AVG(amount) OVER (ORDER BY sale_date ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS moving_avg_7d
+FROM daily_sales;
+
+-- RATIO_TO_REPORT — 占比
+SELECT department_id, last_name, salary,
+       RATIO_TO_REPORT(salary) OVER (PARTITION BY department_id) AS pct_of_dept
+FROM employees;
+```

skills/database-skills/oracle/references/04-plsql-guide.md

@@ -0,0 +1,303 @@
+# PL/SQL 详解
+
+PL/SQL（Procedural Language/SQL）是 Oracle 的扩展 SQL，支持变量、条件、循环、异常处理等过程式编程。
+
+## 块结构
+
+```sql
+DECLARE
+    v_employee_id employees.employee_id%TYPE;
+    v_salary      employees.salary%TYPE := 5000;
+BEGIN
+    SELECT employee_id, salary INTO v_employee_id, v_salary
+    FROM employees WHERE employee_id = 100;
+    DBMS_OUTPUT.PUT_LINE('员工 ' || v_employee_id || ' 工资: ' || v_salary);
+EXCEPTION
+    WHEN NO_DATA_FOUND THEN
+        DBMS_OUTPUT.PUT_LINE('未找到员工');
+    WHEN OTHERS THEN
+        DBMS_OUTPUT.PUT_LINE('错误: ' || SQLERRM);
+END;
+/
+```
+
+## 游标 (Cursor)
+
+```sql
+-- 隐式游标（SELECT INTO）
+DECLARE v_name employees.last_name%TYPE;
+BEGIN
+    SELECT last_name INTO v_name FROM employees WHERE employee_id = 100;
+EXCEPTION WHEN NO_DATA_FOUND THEN NULL;
+END;
+/
+
+-- 显式游标
+DECLARE
+    CURSOR emp_cursor IS SELECT employee_id, last_name FROM employees WHERE department_id = 50;
+    v_emp emp_cursor%ROWTYPE;
+BEGIN
+    OPEN emp_cursor;
+    LOOP
+        FETCH emp_cursor INTO v_emp;
+        EXIT WHEN emp_cursor%NOTFOUND;
+        DBMS_OUTPUT.PUT_LINE(v_emp.last_name);
+    END LOOP;
+    CLOSE emp_cursor;
+END;
+/
+
+-- CURSOR FOR LOOP（最简洁）
+BEGIN
+    FOR rec IN (SELECT last_name, salary FROM employees WHERE department_id = 50)
+    LOOP
+        DBMS_OUTPUT.PUT_LINE(rec.last_name || ' 工资: ' || rec.salary);
+    END LOOP;
+END;
+/
+
+-- REF CURSOR（动态游标）
+DECLARE
+    TYPE refcur IS REF CURSOR;
+    c_ref refcur;
+    v_id   employees.employee_id%TYPE;
+    v_name employees.last_name%TYPE;
+BEGIN
+    OPEN c_ref FOR 'SELECT employee_id, last_name FROM employees WHERE department_id = :d' USING 50;
+    LOOP
+        FETCH c_ref INTO v_id, v_name;
+        EXIT WHEN c_ref%NOTFOUND;
+    END LOOP;
+    CLOSE c_ref;
+END;
+/
+
+-- SYS_REFCURSOR 函数返回
+CREATE OR REPLACE FUNCTION get_employees(p_dept_id NUMBER) RETURN SYS_REFCURSOR AS
+    c SYS_REFCURSOR;
+BEGIN
+    OPEN c FOR SELECT * FROM employees WHERE department_id = p_dept_id;
+    RETURN c;
+END;
+/
+```
+
+## 存储过程与函数
+
+```sql
+-- 存储过程
+CREATE OR REPLACE PROCEDURE update_salary(
+    p_employee_id IN employees.employee_id%TYPE,
+    p_percent     IN NUMBER
+) AS
+    v_old_salary employees.salary%TYPE;
+BEGIN
+    SELECT salary INTO v_old_salary FROM employees WHERE employee_id = p_employee_id FOR UPDATE;
+    UPDATE employees SET salary = salary * (1 + p_percent / 100) WHERE employee_id = p_employee_id;
+    COMMIT;
+EXCEPTION
+    WHEN NO_DATA_FOUND THEN RAISE_APPLICATION_ERROR(-20001, '员工不存在');
+    WHEN OTHERS THEN ROLLBACK; RAISE;
+END update_salary;
+/
+
+-- 函数（必须有返回值）
+CREATE OR REPLACE FUNCTION get_annual_salary(p_employee_id NUMBER) RETURN NUMBER AS
+    v_salary employees.salary%TYPE;
+    v_commission employees.commission_pct%TYPE;
+BEGIN
+    SELECT salary, NVL(commission_pct, 0) INTO v_salary, v_commission
+    FROM employees WHERE employee_id = p_employee_id;
+    RETURN v_salary * 12 + v_salary * v_commission;
+END get_annual_salary;
+/
+
+-- DETERMINISTIC 函数（可用于函数索引）
+CREATE OR REPLACE FUNCTION calculate_tax(p_amount NUMBER) RETURN NUMBER DETERMINISTIC AS
+BEGIN
+    RETURN p_amount * 0.13;
+END;
+/
+```
+
+## 包 (Package)
+
+```sql
+-- 包规范（公开接口）
+CREATE OR REPLACE PACKAGE emp_mgmt AS
+    c_max_salary CONSTANT NUMBER := 50000;
+    FUNCTION get_salary(p_emp_id NUMBER) RETURN NUMBER;
+    PROCEDURE raise_salary(p_emp_id NUMBER, p_pct NUMBER);
+    PROCEDURE hire_employee(p_last_name VARCHAR2, p_email VARCHAR2, p_job_id VARCHAR2, p_salary NUMBER);
+    PROCEDURE set_debug(p_mode BOOLEAN);
+    PROCEDURE set_debug(p_mode VARCHAR2);  -- 重载
+END emp_mgmt;
+/
+
+-- 包体（实现）
+CREATE OR REPLACE PACKAGE BODY emp_mgmt AS
+    v_last_action VARCHAR2(100);  -- 私有变量
+
+    FUNCTION get_salary(p_emp_id NUMBER) RETURN NUMBER IS
+        v_sal employees.salary%TYPE;
+    BEGIN
+        SELECT salary INTO v_sal FROM employees WHERE employee_id = p_emp_id;
+        RETURN v_sal;
+    EXCEPTION WHEN NO_DATA_FOUND THEN RETURN NULL;
+    END;
+
+    PROCEDURE raise_salary(p_emp_id NUMBER, p_pct NUMBER) IS
+    BEGIN
+        UPDATE employees SET salary = salary * (1 + p_pct/100) WHERE employee_id = p_emp_id;
+        v_last_action := 'Raised salary for ' || p_emp_id;
+    END;
+
+    PROCEDURE hire_employee(p_last_name VARCHAR2, p_email VARCHAR2, p_job_id VARCHAR2, p_salary NUMBER) IS
+    BEGIN
+        INSERT INTO employees(employee_id, last_name, email, job_id, salary, hire_date)
+        VALUES (employees_seq.NEXTVAL, p_last_name, p_email, p_job_id, p_salary, SYSDATE);
+        v_last_action := 'Hired ' || p_last_name;
+    END;
+
+    PROCEDURE set_debug(p_mode BOOLEAN) IS BEGIN g_debug_mode := p_mode; END;
+    PROCEDURE set_debug(p_mode VARCHAR2) IS BEGIN g_debug_mode := UPPER(p_mode) = 'ON'; END;
+
+    -- 包初始化（首次引用时执行一次）
+    BEGIN
+        v_last_action := 'Package initialized';
+    END;
+END emp_mgmt;
+/
+```
+
+## 触发器 (Trigger)
+
+```sql
+-- DML 行级触发器（工资变更审计）
+CREATE OR REPLACE TRIGGER trg_emp_salary_audit
+    BEFORE UPDATE OF salary ON employees FOR EACH ROW
+    WHEN (OLD.salary != NEW.salary)
+BEGIN
+    INSERT INTO salary_audit_log(employee_id, old_salary, new_salary, changed_by, changed_at)
+    VALUES (:OLD.employee_id, :OLD.salary, :NEW.salary, USER, SYSDATE);
+END;
+/
+
+-- 语句级触发器（非工作时间禁止修改）
+CREATE OR REPLACE TRIGGER trg_no_dml_nonbusiness
+    BEFORE INSERT OR UPDATE OR DELETE ON employees
+BEGIN
+    IF TO_CHAR(SYSDATE, 'DY') IN ('SAT', 'SUN') OR
+       TO_NUMBER(TO_CHAR(SYSDATE, 'HH24')) NOT BETWEEN 9 AND 18 THEN
+        RAISE_APPLICATION_ERROR(-20001, '非工作时间禁止修改');
+    END IF;
+END;
+/
+
+-- INSTEAD OF 触发器（视图 DML）
+CREATE OR REPLACE TRIGGER trg_v_emp_dept_ioi
+    INSTEAD OF INSERT ON v_emp_dept FOR EACH ROW
+BEGIN
+    INSERT INTO employees(employee_id, last_name, salary, department_id)
+    VALUES (:NEW.employee_id, :NEW.last_name, :NEW.salary,
+            (SELECT department_id FROM departments WHERE department_name = :NEW.department_name));
+END;
+/
+
+-- 登录审计触发器
+CREATE OR REPLACE TRIGGER trg_logon_audit
+    AFTER LOGON ON DATABASE
+BEGIN
+    INSERT INTO logon_audit_log(session_id, user_name, logon_time)
+    VALUES (SYS_CONTEXT('USERENV', 'SESSIONID'), USER, SYSDATE);
+END;
+/
+```
+
+## 异常处理
+
+```sql
+-- 预定义异常
+EXCEPTION
+    WHEN NO_DATA_FOUND THEN ...
+    WHEN TOO_MANY_ROWS THEN ...
+    WHEN DUP_VAL_ON_INDEX THEN ...
+    WHEN VALUE_ERROR THEN ...
+    WHEN ZERO_DIVIDE THEN ...
+    WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE(SQLERRM); RAISE;
+
+-- 自定义异常
+DECLARE
+    e_salary_too_high EXCEPTION;
+    PRAGMA EXCEPTION_INIT(e_salary_too_high, -20001);
+BEGIN
+    IF v_salary > 50000 THEN RAISE e_salary_too_high; END IF;
+EXCEPTION WHEN e_salary_too_high THEN ... END;
+
+-- RAISE_APPLICATION_ERROR
+RAISE_APPLICATION_ERROR(-20001, '订单已取消', TRUE);
+```
+
+## 集合类型
+
+```sql
+-- 关联数组（Index-By Table）
+DECLARE
+    TYPE dept_name_tab IS TABLE OF departments.department_name%TYPE INDEX BY PLS_INTEGER;
+    t_dept_names dept_name_tab;
+BEGIN
+    FOR rec IN (SELECT department_id, department_name FROM departments)
+    LOOP t_dept_names(rec.department_id) := rec.department_name; END LOOP;
+END;
+/
+
+-- 嵌套表
+CREATE OR REPLACE TYPE phone_list AS TABLE OF VARCHAR2(20);
+/
+DECLARE t_phones phone_list := phone_list('13800138000', '13900139000');
+BEGIN t_phones.EXTEND(1); t_phones(3) := '13700137000'; END;
+/
+
+-- VARRAY（定长数组）
+CREATE OR REPLACE TYPE score_list IS VARRAY(10) OF NUMBER;
+/
+
+-- 集合方法: EXISTS, COUNT, LIMIT, FIRST/LAST, PRIOR/NEXT, EXTEND, TRIM, DELETE
+```
+
+## 动态 SQL
+
+```sql
+-- EXECUTE IMMEDIATE（简单动态 SQL）
+CREATE OR REPLACE FUNCTION count_rows(p_table_name VARCHAR2) RETURN NUMBER AS
+    v_sql VARCHAR2(200); v_cnt NUMBER;
+BEGIN
+    v_sql := 'SELECT COUNT(*) FROM ' || p_table_name;
+    EXECUTE IMMEDIATE v_sql INTO v_cnt;
+    RETURN v_cnt;
+END;
+/
+
+-- 带绑定变量（防 SQL 注入）
+EXECUTE IMMEDIATE 'SELECT last_name FROM employees WHERE employee_id = :id' INTO v_name USING 100;
+
+-- FORALL（批量 DML，提升性能）
+DECLARE
+    TYPE id_list IS TABLE OF employees.employee_id%TYPE;
+    t_ids id_list := id_list(100, 101, 102);
+BEGIN
+    FORALL i IN t_ids.FIRST..t_ids.LAST
+        UPDATE employees SET salary = salary * 1.1 WHERE employee_id = t_ids(i);
+    COMMIT;
+END;
+/
+
+-- BULK COLLECT（批量读取）
+DECLARE
+    TYPE emp_tab IS TABLE OF employees%ROWTYPE;
+    t_emps emp_tab;
+BEGIN
+    SELECT * BULK COLLECT INTO t_emps FROM employees WHERE department_id = 50;
+END;
+/
+```

skills/database-skills/oracle/references/05-performance-tuning.md

@@ -0,0 +1,164 @@
+# 性能调优 — AWR / ASH / ADDM / DBMS_XPLAN
+
+## EXPLAIN PLAN / DBMS_XPLAN
+
+```sql
+-- 生成执行计划
+EXPLAIN PLAN FOR
+SELECT d.department_name, e.last_name, e.salary
+FROM departments d JOIN employees e ON d.department_id = e.department_id
+WHERE e.salary > 10000;
+
+-- 查看执行计划
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY);
+
+-- 查看实际执行计划（带统计信息）
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY_CURSOR(sql_id => 'abc123', format => 'ALLSTATS LAST'));
+
+-- 格式化选项
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY(format => 'BASIC'));    -- 基本
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY(format => 'TYPICAL'));  -- 典型（默认）
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY(format => 'ALL'));      -- 全部
+SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY(format => 'ADVANCED')); -- 高级（含提示）
+
+-- 查找高消耗 SQL
+SELECT sql_id, ROUND(elapsed_time/1000,2) AS elapsed_ms,
+       cpu_time, buffer_gets, executions,
+       SUBSTR(sql_text, 1, 200) AS sql_text_short
+FROM v$sql
+WHERE elapsed_time > 0 AND executions > 0
+ORDER BY elapsed_time DESC FETCH FIRST 10 ROWS ONLY;
+```
+
+## AWR（Automatic Workload Repository）
+
+```sql
+-- 生成 AWR 报告（HTML 格式）
+SELECT * FROM TABLE(DBMS_WORKLOAD_REPOSITORY.AWR_REPORT_HTML(
+    l_dbid     => (SELECT dbid FROM v$database),
+    l_inst_num => 1,
+    l_bid      => 100,    -- 起始快照 ID
+    l_eid      => 110,    -- 结束快照 ID
+    l_options  => 0
+));
+
+-- 创建 AWR 快照
+EXEC DBMS_WORKLOAD_REPOSITORY.CREATE_SNAPSHOT();
+
+-- 修改 AWR 保留策略（默认 8 天）
+EXEC DBMS_WORKLOAD_REPOSITORY.MODIFY_SNAPSHOT_SETTINGS(retention => 14400);   -- 10天
+EXEC DBMS_WORKLOAD_REPOSITORY.MODIFY_SNAPSHOT_SETTINGS(interval => 60);       -- 间隔 60 分钟
+```
+
+## ASH（Active Session History）
+
+```sql
+-- 最近 10 分钟的 Top 等待事件
+SELECT event, COUNT(*) AS cnt,
+       ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS pct
+FROM v$active_session_history
+WHERE sample_time > SYSTIMESTAMP - INTERVAL '10' MINUTE
+GROUP BY event ORDER BY cnt DESC;
+
+-- Top SQL（基于 ASH）
+SELECT sql_id, COUNT(*) AS hits,
+       ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS pct
+FROM v$active_session_history
+WHERE sample_time > SYSTIMESTAMP - INTERVAL '10' MINUTE AND sql_id IS NOT NULL
+GROUP BY sql_id ORDER BY hits DESC FETCH FIRST 5 ROWS ONLY;
+```
+
+## ADDM（Automatic Database Diagnostic Monitor）
+
+```sql
+DECLARE
+    v_task_name VARCHAR2(30);
+BEGIN
+    v_task_name := 'MY_ADDM_TASK';
+    DBMS_ADDM.ANALYZE_DB(
+        task_name => v_task_name,
+        begin_snapshot => 100,
+        end_snapshot => 110
+    );
+END;
+/
+```
+
+## SQL Tuning Advisor
+
+```sql
+DECLARE
+    v_task_name VARCHAR2(30);
+BEGIN
+    v_task_name := DBMS_SQLTUNE.CREATE_TUNING_TASK(
+        sql_id      => 'abc123xyz4567',
+        scope       => DBMS_SQLTUNE.SCOPE_COMPREHENSIVE,
+        time_limit  => 300,
+        task_name   => 'tune_sql_abc123'
+    );
+    DBMS_SQLTUNE.EXECUTE_TUNING_TASK(task_name => v_task_name);
+END;
+/
+
+-- 查看调优建议
+SELECT DBMS_SQLTUNE.REPORT_TUNING_TASK(task_name => 'tune_sql_abc123') FROM DUAL;
+
+-- 接受 SQL Profile
+EXEC DBMS_SQLTUNE.ACCEPT_SQL_PROFILE(task_name => 'tune_sql_abc123');
+```
+
+## DBMS_STATS — 统计信息
+
+```sql
+-- 收集表级统计信息
+EXEC DBMS_STATS.GATHER_TABLE_STATS(
+    ownname => 'HR', tabname => 'EMPLOYEES',
+    estimate_percent => DBMS_STATS.AUTO_SAMPLE_SIZE,
+    cascade => TRUE, degree => DBMS_STATS.AUTO_DEGREE,
+    method_opt => 'FOR ALL COLUMNS SIZE AUTO'
+);
+
+-- 收集模式级统计信息
+EXEC DBMS_STATS.GATHER_SCHEMA_STATS(ownname => 'HR', options => 'GATHER AUTO');
+
+-- 锁定/解锁统计信息
+EXEC DBMS_STATS.LOCK_TABLE_STATS('HR', 'EMPLOYEES');
+EXEC DBMS_STATS.UNLOCK_TABLE_STATS('HR', 'EMPLOYEES');
+
+-- 恢复历史统计信息
+EXEC DBMS_STATS.RESTORE_TABLE_STATS('HR', 'EMPLOYEES', SYSTIMESTAMP - 7);
+
+-- 查看统计信息
+SELECT table_name, num_rows, blocks, avg_row_len, last_analyzed
+FROM dba_tab_statistics WHERE owner = 'HR' AND table_name = 'EMPLOYEES';
+```
+
+## SPM（SQL Plan Management）
+
+```sql
+-- 加载执行计划到 SPM
+DECLARE v_plans_loaded PLS_INTEGER;
+BEGIN
+    v_plans_loaded := DBMS_SPM.LOAD_PLANS_FROM_CURSOR_CACHE(sql_id => 'abc123xyz4567');
+END;
+/
+
+-- 查看 SPM 基线
+SELECT sql_handle, plan_name, enabled, accepted, fixed FROM dba_sql_plan_baselines;
+
+-- 演变计划
+SELECT DBMS_SPM.EVOLVE_SQL_PLAN_BASELINE(sql_handle => 'SQL_handle_here', verify => 'YES') FROM DUAL;
+
+-- 固定计划
+DECLARE v_fixed PLS_INTEGER;
+BEGIN
+    v_fixed := DBMS_SPM.ALTER_SQL_PLAN_BASELINE(
+        sql_handle => 'SQL_handle_here', plan_name => 'SQL_PLAN_xxxxx',
+        attribute_name => 'FIXED', attribute_value => 'YES');
+END;
+/
+
+-- SPM 配置
+ALTER SYSTEM SET optimizer_capture_sql_plan_baselines = FALSE;
+ALTER SYSTEM SET optimizer_use_sql_plan_baselines = TRUE;
+```

skills/database-skills/oracle/references/06-backup-recovery.md

@@ -0,0 +1,115 @@
+# 备份与恢复 — RMAN / EXPDP / IMPDP / 归档
+
+## RMAN 备份
+
+```sql
+-- 连接 RMAN
+-- rman target /
+
+-- 全库备份（含归档日志）
+RMAN> BACKUP DATABASE PLUS ARCHIVELOG DELETE INPUT;
+
+-- 增量备份 Level 0（基础）
+RMAN> BACKUP INCREMENTAL LEVEL 0 DATABASE PLUS ARCHIVELOG;
+
+-- 增量备份 Level 1（差异）
+RMAN> BACKUP INCREMENTAL LEVEL 1 DATABASE;
+
+-- 表空间备份
+RMAN> BACKUP TABLESPACE tbs_app_data;
+
+-- 数据文件备份
+RMAN> BACKUP DATAFILE '/u01/oradata/orcl/app_data01.dbf';
+
+-- 控制文件/归档日志备份
+RMAN> BACKUP CURRENT CONTROLFILE;
+RMAN> BACKUP ARCHIVELOG ALL DELETE INPUT;
+```
+
+## RMAN 恢复
+
+```sql
+-- 全库恢复
+RMAN> STARTUP MOUNT;
+RMAN> RESTORE DATABASE;
+RMAN> RECOVER DATABASE;
+RMAN> ALTER DATABASE OPEN;
+
+-- 时间点恢复（不完全恢复）
+RMAN> STARTUP MOUNT;
+RMAN> RESTORE DATABASE UNTIL TIME "TO_DATE('2024-08-15 14:00:00','YYYY-MM-DD HH24:MI:SS')";
+RMAN> RECOVER DATABASE UNTIL TIME "...";
+RMAN> ALTER DATABASE OPEN RESETLOGS;
+
+-- 表空间恢复
+RMAN> SQL "ALTER TABLESPACE tbs_app_data OFFLINE IMMEDIATE";
+RMAN> RESTORE TABLESPACE tbs_app_data;
+RMAN> RECOVER TABLESPACE tbs_app_data;
+RMAN> SQL "ALTER TABLESPACE tbs_app_data ONLINE";
+
+-- 验证备份
+RMAN> RESTORE DATABASE VALIDATE;
+
+-- 备份策略配置
+RMAN> CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 7 DAYS;
+RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON;
+RMAN> CONFIGURE BACKUP OPTIMIZATION ON;
+```
+
+## 逻辑备份（EXPDP / IMPDP）
+
+```sql
+-- 导出全库
+-- expdp system/password DIRECTORY=dp_dir DUMPFILE=full_export.dmp FULL=Y
+
+-- 导出指定模式
+-- expdp system/password DIRECTORY=dp_dir DUMPFILE=hr_export.dmp SCHEMAS=HR
+
+-- 导出指定表
+-- expdp hr/password DIRECTORY=dp_dir DUMPFILE=emp_export.dmp TABLES=employees,departments
+
+-- 条件导出
+-- expdp hr/password DIRECTORY=dp_dir DUMPFILE=emp_dept50.dmp TABLES=employees QUERY='employees:"WHERE department_id = 50"'
+
+-- 并行导出
+-- expdp hr/password DIRECTORY=dp_dir DUMPFILE=hr_%U.dmp SCHEMAS=HR PARALLEL=4
+
+-- 全库导入
+-- impdp system/password DIRECTORY=dp_dir DUMPFILE=full_export.dmp FULL=Y
+
+-- 导入并重映射表空间/模式
+-- impdp system/password DIRECTORY=dp_dir DUMPFILE=hr_export.dmp REMAP_SCHEMAS=HR:HR_NEW REMAP_TABLESPACE=USERS:TBS_APP_DATA
+
+-- 跳过已存在对象
+-- impdp hr/password DIRECTORY=dp_dir DUMPFILE=hr_export.dmp TABLE_EXISTS_ACTION=SKIP
+-- TABLE_EXISTS_ACTION: SKIP / APPEND / TRUNCATE / REPLACE
+```
+
+## 归档日志模式
+
+```sql
+-- 查看当前日志模式
+SELECT log_mode FROM v$database;
+
+-- 启用归档日志模式
+SHUTDOWN IMMEDIATE;
+STARTUP MOUNT;
+ALTER DATABASE ARCHIVELOG;
+ALTER DATABASE OPEN;
+
+-- 禁用归档日志模式
+SHUTDOWN IMMEDIATE;
+STARTUP MOUNT;
+ALTER DATABASE NOARCHIVELOG;
+ALTER DATABASE OPEN;
+
+-- 归档日志管理
+ALTER SYSTEM SET log_archive_dest_1='LOCATION=/u01/archivelog/orcl' SCOPE=BOTH;
+ALTER SYSTEM SET log_archive_format='orcl_%t_%s_%r.arc' SCOPE=SPFILE;
+ALTER SYSTEM SWITCH LOGFILE;
+
+-- 查看归档日志
+SELECT * FROM v$archived_log ORDER BY sequence#;
+SELECT * FROM v$recovery_file_dest;
+ALTER SYSTEM SET db_recovery_file_dest_size = 200G;
+```

skills/database-skills/oracle/references/07-dataguard-rac.md

@@ -0,0 +1,76 @@
+# Data Guard / RAC
+
+## Data Guard 物理备库
+
+### 主库配置
+
+```sql
+ALTER DATABASE FORCE LOGGING;
+ALTER SYSTEM SET LOG_ARCHIVE_CONFIG='DG_CONFIG=(PRIMARY,STANDBY)' SCOPE=BOTH;
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_1='LOCATION=/u01/archivelog/orcl VALID_FOR=(ALL_LOGFILES,ALL_ROLES) DB_UNIQUE_NAME=PRIMARY' SCOPE=BOTH;
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_2='SERVICE=standby_host:1521/orcl LGWR ASYNC VALID_FOR=(ONLINE_LOGFILES,PRIMARY_ROLE) DB_UNIQUE_NAME=STANDBY' SCOPE=BOTH;
+ALTER SYSTEM SET LOG_ARCHIVE_DEST_STATE_2=ENABLE SCOPE=BOTH;
+ALTER SYSTEM SET FAL_CLIENT='PRIMARY' SCOPE=BOTH;
+ALTER SYSTEM SET FAL_SERVER='STANDBY' SCOPE=BOTH;
+ALTER SYSTEM SET DB_FILE_NAME_CONVERT='/u01/oradata/orcl/','/u02/oradata/orcl/' SCOPE=SPFILE;
+ALTER SYSTEM SET LOG_FILE_NAME_CONVERT='/u01/oradata/orcl/','/u02/oradata/orcl/' SCOPE=SPFILE;
+ALTER SYSTEM SET STANDBY_FILE_MANAGEMENT=AUTO SCOPE=BOTH;
+```
+
+### 创建物理备库
+
+```sql
+-- 使用 RMAN DUPLICATE
+-- DUPLICATE TARGET DATABASE FOR STANDBY FROM ACTIVE DATABASE;
+
+-- 备库启用实时应用
+ALTER DATABASE RECOVER MANAGED STANDBY DATABASE USING CURRENT LOGFILE DISCONNECT;
+```
+
+### 角色切换
+
+```sql
+-- Switchover（计划内切换，不丢数据）
+-- 主库：
+ALTER DATABASE COMMIT TO SWITCHOVER TO STANDBY;
+SHUTDOWN IMMEDIATE; STARTUP MOUNT;
+-- 备库：
+ALTER DATABASE COMMIT TO SWITCHOVER TO PRIMARY;
+ALTER DATABASE OPEN;
+
+-- Failover（故障切换）
+ALTER DATABASE RECOVER MANAGED STANDBY DATABASE FINISH;
+ALTER DATABASE COMMIT TO SWITCHOVER TO PRIMARY;
+ALTER DATABASE OPEN;
+
+-- Active Data Guard（备库只读打开）
+ALTER DATABASE OPEN READ ONLY;
+ALTER DATABASE RECOVER MANAGED STANDBY DATABASE DISCONNECT;
+```
+
+## RAC（Real Application Clusters）
+
+```sql
+-- 查看 RAC 实例
+SELECT instance_name, instance_number, host_name, status FROM gv$instance;
+
+-- 查看 RAC 节点
+SELECT * FROM gv$active_services;
+
+-- 查看 ASM 磁盘组
+SELECT * FROM gv$asm_diskgroup;
+
+-- 全局等待事件
+SELECT inst_id, event, COUNT(*) AS cnt, ROUND(AVG(wait_time_micro)) AS avg_wait_us
+FROM gv$session WHERE wait_class != 'Idle'
+GROUP BY inst_id, event ORDER BY cnt DESC;
+
+-- RAC 序列配置（避免争用）
+CREATE SEQUENCE seq_order_no START WITH 1 CACHE 1000 NOORDER;
+
+-- RAC 关键初始化参数
+-- cluster_database = TRUE
+-- instance_number = 1
+-- thread = 1
+-- undo_tablespace = UNDOTBS1
+```

skills/database-skills/oracle/references/08-security.md

@@ -0,0 +1,170 @@
+# 安全与权限 — 用户 / FGA / VPD / TDE / 数据脱敏
+
+## 用户 / 角色 / 权限
+
+```sql
+-- 创建用户
+CREATE USER app_user IDENTIFIED BY "StrongPassword123!"
+    DEFAULT TABLESPACE tbs_app_data
+    TEMPORARY TABLESPACE TEMP
+    QUOTA UNLIMITED ON tbs_app_data;
+
+-- 创建角色
+CREATE ROLE app_read_role;
+CREATE ROLE app_write_role;
+
+-- 系统权限
+GRANT CREATE SESSION TO app_user;
+GRANT CREATE TABLE, CREATE PROCEDURE, CREATE VIEW, CREATE SEQUENCE TO app_user;
+
+-- 对象权限
+GRANT SELECT, INSERT, UPDATE, DELETE ON hr.employees TO app_write_role;
+GRANT SELECT ON hr.employees TO app_read_role;
+GRANT EXECUTE ON hr.emp_mgmt TO app_admin_role;
+
+-- 角色授予用户
+GRANT app_read_role TO app_user;
+
+-- 撤销
+REVOKE DELETE ON hr.employees FROM app_write_role;
+
+-- 查看用户权限
+SELECT * FROM dba_sys_privs WHERE grantee = 'APP_USER';
+SELECT * FROM dba_tab_privs WHERE grantee = 'APP_USER';
+SELECT * FROM dba_role_privs WHERE grantee = 'APP_USER';
+
+-- 配置文件（Profile）
+CREATE PROFILE app_profile LIMIT
+    SESSIONS_PER_USER      5
+    IDLE_TIME             30
+    CONNECT_TIME         480
+    FAILED_LOGIN_ATTEMPTS  5
+    PASSWORD_LOCK_TIME     1
+    PASSWORD_LIFE_TIME    90
+    PASSWORD_GRACE_TIME    7;
+
+-- 用户管理
+ALTER USER app_user ACCOUNT LOCK;
+ALTER USER app_user ACCOUNT UNLOCK;
+ALTER USER app_user PASSWORD EXPIRE;
+```
+
+## FGA（Fine-Grained Auditing）— 细粒度审计
+
+```sql
+-- 创建 FGA 策略（审计高工资访问）
+BEGIN
+    DBMS_FGA.ADD_POLICY(
+        object_schema   => 'HR',
+        object_name     => 'EMPLOYEES',
+        policy_name     => 'AUDIT_SALARY_ACCESS',
+        audit_condition => 'salary > 10000',
+        audit_column    => 'SALARY, COMMISSION_PCT',
+        enable          => TRUE,
+        statement_types => 'SELECT, UPDATE',
+        audit_trail     => DBMS_FGA.XML + DBMS_FGA.EXTENDED
+    );
+END;
+/
+
+-- 查看 FGA 审计日志
+SELECT timestamp, db_user, object_schema, object_name, sql_text
+FROM dba_fga_audit_trail WHERE object_name = 'EMPLOYEES'
+ORDER BY timestamp DESC;
+
+-- 管理 FGA 策略
+BEGIN
+    DBMS_FGA.DISABLE_POLICY('HR', 'EMPLOYEES', 'AUDIT_SALARY_ACCESS');
+    DBMS_FGA.ENABLE_POLICY('HR', 'EMPLOYEES', 'AUDIT_SALARY_ACCESS');
+    DBMS_FGA.DROP_POLICY('HR', 'EMPLOYEES', 'AUDIT_SALARY_ACCESS');
+END;
+/
+```
+
+## VPD（Virtual Private Database）— 虚拟私有数据库
+
+```sql
+-- 1. 创建策略函数
+CREATE OR REPLACE FUNCTION dept_access_policy(
+    p_schema VARCHAR2, p_object VARCHAR2
+) RETURN VARCHAR2 AS
+    v_dept_id NUMBER;
+BEGIN
+    IF SYS_CONTEXT('USERENV', 'ISDBA') = 'TRUE' THEN
+        RETURN '1=1';
+    END IF;
+    v_dept_id := SYS_CONTEXT('USER_CTX', 'DEPARTMENT_ID');
+    IF v_dept_id IS NOT NULL THEN
+        RETURN 'department_id = ' || v_dept_id;
+    ELSE
+        RETURN '1=0';
+    END IF;
+END;
+/
+
+-- 2. 应用策略到表
+BEGIN
+    DBMS_RLS.ADD_POLICY(
+        object_schema   => 'HR',
+        object_name     => 'EMPLOYEES',
+        policy_name     => 'DEPT_ACCESS_POLICY',
+        function_schema => 'HR',
+        policy_function => 'dept_access_policy',
+        statement_types => 'SELECT, INSERT, UPDATE, DELETE',
+        update_check    => TRUE,
+        enable          => TRUE
+    );
+END;
+/
+
+-- 查看 VPD 策略
+SELECT * FROM dba_policies WHERE object_name = 'EMPLOYEES';
+
+-- 移除
+EXEC DBMS_RLS.DROP_POLICY('HR', 'EMPLOYEES', 'DEPT_ACCESS_POLICY');
+```
+
+## TDE（Transparent Data Encryption）— 透明数据加密
+
+```sql
+-- 打开钱包
+ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "wallet_password";
+ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "wallet_password" WITH BACKUP;
+
+-- 创建加密表空间
+CREATE TABLESPACE tbs_encrypted
+    DATAFILE '/u01/oradata/orcl/encrypted01.dbf' SIZE 5G
+    ENCRYPTION USING 'AES256'
+    DEFAULT STORAGE(ENCRYPT);
+
+-- 列级加密
+CREATE TABLE credit_cards (
+    card_id     NUMBER(10) PRIMARY KEY,
+    customer_id NUMBER(10),
+    card_number VARCHAR2(16) ENCRYPT USING 'AES256',
+    cvv         VARCHAR2(4) ENCRYPT,
+    expiry_date DATE
+);
+```
+
+## 数据脱敏（Data Redaction）
+
+```sql
+-- 创建 Redaction Policy
+BEGIN
+    DBMS_REDACT.ADD_POLICY(
+        object_schema       => 'HR',
+        object_name         => 'CREDIT_CARDS',
+        policy_name         => 'REDACT_CC_NUM',
+        column_name         => 'CARD_NUMBER',
+        function_type       => DBMS_REDACT.PARTIAL,
+        function_parameters => 'VVVVVVVVVVVVVVVV,VVVV-XXXX-XXXX-VVVV,*,1,4',
+        expression          => 'SYS_CONTEXT(''USERENV'', ''SESSION_USER'') != ''APP_ADMIN'''
+    );
+END;
+/
+
+-- 查看脱敏策略
+SELECT * FROM redaction_policies;
+SELECT * FROM redaction_columns;
+```

skills/database-skills/oracle/references/09-sql-syntax.md

@@ -0,0 +1,152 @@
+# SQL 语法详解（Oracle 特有语法）
+
+## 数据类型
+
+| 数据类型 | 说明 | 最大长度 | 业务场景 |
+|---------|------|---------|---------|
+| **VARCHAR2(n)** | 可变长字符串 | 4000B（12c+ 32767） | 用户名、邮箱 |
+| **NVARCHAR2(n)** | Unicode 可变长字符串 | 4000 字符 | 多语言文本 |
+| **CLOB** | 字符大对象 | (4GB-1)*block_size | 文章、JSON |
+| **NUMBER(p,s)** | 数值 | 38 位十进制 | 金额、数量 |
+| **BINARY_FLOAT** | 32位浮点 | ~7位有效数字 | 科学计算 |
+| **BINARY_DOUBLE** | 64位浮点 | ~15位有效数字 | 高精度计算 |
+| **DATE** | 日期时间（精确到秒） | 4712BC~9999AD | 订单时间 |
+| **TIMESTAMP** | 日期时间（精确到纳秒） | 同 DATE + 小数秒 | 高精度时间戳 |
+| **INTERVAL** | 时间间隔 | - | 耗时统计 |
+| **RAW(n)** | 二进制数据 | 2000 字节 | GUID、散列值 |
+
+## DDL
+
+```sql
+-- CREATE TABLE 约束
+CREATE TABLE users (
+    user_id  NUMBER(10) GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    username VARCHAR2(50) NOT NULL,
+    email    VARCHAR2(100) NOT NULL UNIQUE,
+    status   VARCHAR2(10) DEFAULT 'ACTIVE',
+    CONSTRAINT ck_users_status CHECK (status IN ('ACTIVE','INACTIVE','LOCKED'))
+);
+
+-- 虚拟列
+CREATE TABLE products (
+    product_id  NUMBER(10) PRIMARY KEY,
+    unit_price  NUMBER(10,2),
+    quantity    NUMBER(10),
+    total_value NUMBER(10,2) GENERATED ALWAYS AS (unit_price * quantity) VIRTUAL
+);
+
+-- 序列
+CREATE SEQUENCE seq_orders START WITH 10000 INCREMENT BY 1 CACHE 100 NOORDER;
+
+-- 同义词
+CREATE SYNONYM emp FOR hr.employees;
+CREATE PUBLIC SYNONYM dept FOR hr.departments;
+```
+
+## DML
+
+```sql
+-- MERGE（UPSERT）
+MERGE INTO products p USING staging_products s ON (p.product_id = s.product_id)
+WHEN MATCHED THEN UPDATE SET p.price = s.price, p.updated_at = SYSDATE
+WHEN NOT MATCHED THEN INSERT (product_id, product_name, price) VALUES (s.product_id, s.product_name, s.price);
+
+-- INSERT ALL（多表插入）
+INSERT ALL
+    WHEN salary > 10000 THEN INTO emp_active (employee_id, salary)
+    WHEN salary <= 10000 THEN INTO emp_archive (employee_id, salary)
+SELECT employee_id, salary FROM employees;
+
+-- CONNECT BY（层次查询）
+SELECT employee_id, last_name, LEVEL,
+       SYS_CONNECT_BY_PATH(last_name, ' -> ') AS path
+FROM employees
+START WITH manager_id IS NULL
+CONNECT BY PRIOR employee_id = manager_id
+ORDER SIBLINGS BY last_name;
+
+-- 生成日期序列
+SELECT DATE '2024-01-01' + LEVEL - 1 AS day FROM DUAL
+CONNECT BY LEVEL <= 31;
+
+-- FLASHBACK QUERY
+SELECT * FROM employees AS OF TIMESTAMP (SYSTIMESTAMP - INTERVAL '15' MINUTE);
+SELECT * FROM employees AS OF SCN 1234567;
+```
+
+## SELECT 特有语法
+
+```sql
+-- WITH（CTE）
+WITH dept_salary AS (
+    SELECT department_id, SUM(salary) AS total_salary FROM employees GROUP BY department_id
+)
+SELECT * FROM dept_salary ORDER BY total_salary DESC;
+
+-- 递归 CTE
+WITH org_tree(employee_id, manager_id, last_name, lvl) AS (
+    SELECT employee_id, manager_id, last_name, 1 FROM employees WHERE manager_id IS NULL
+    UNION ALL
+    SELECT e.employee_id, e.manager_id, e.last_name, t.lvl + 1
+    FROM employees e JOIN org_tree t ON e.manager_id = t.employee_id
+)
+SELECT * FROM org_tree;
+
+-- PIVOT（行转列）
+SELECT * FROM (
+    SELECT department_id, EXTRACT(MONTH FROM hire_date) AS hire_month FROM employees
+) PIVOT (
+    COUNT(*) FOR hire_month IN (1 AS JAN, 2 AS FEB, 3 AS MAR)
+);
+
+-- LISTAGG（列转字符串）
+SELECT department_id,
+       LISTAGG(last_name, ', ') WITHIN GROUP (ORDER BY hire_date) AS emp_list
+FROM employees GROUP BY department_id;
+-- 19c+ 支持超长处理
+LISTAGG(last_name, ', ' ON OVERFLOW TRUNCATE '...' WITH COUNT)
+
+-- MODEL 子句
+SELECT region, product, year, sales FROM sales_data
+MODEL PARTITION BY (region) DIMENSION BY (product, year) MEASURES (sales)
+RULES ( sales['TOTAL',2024] = sales['TOTAL',2023] * 1.1 );
+
+-- MATCH_RECOGNIZE（12c+ 模式匹配）
+SELECT * FROM stock_prices
+MATCH_RECOGNIZE (
+    PARTITION BY symbol ORDER BY trade_date
+    MEASURES FIRST(price) AS start_price, LAST(price) AS end_price
+    ONE ROW PER MATCH PATTERN (up{3,})
+    DEFINE up AS price > PREV(price)
+);
+```
+
+## 伪列
+
+| 伪列 | 说明 | 使用场景 |
+|------|------|---------|
+| **ROWNUM** | 行号（先筛选后排序） | Top-N、分页 |
+| **ROWID** | 物理行地址 | 最快行定位 |
+| **LEVEL** | 层次查询层级 | CONNECT BY |
+| **CONNECT_BY_ISCYCLE** | 循环检测 | 层次查询 |
+| **CONNECT_BY_ISLEAF** | 叶子节点 | 层次查询 |
+| **ORA_ROWSCN** | 行最后修改 SCN | 数据变更检测 |
+
+```sql
+-- ROWNUM 正确用法
+SELECT * FROM (SELECT * FROM employees ORDER BY salary DESC) WHERE ROWNUM <= 10;
+-- 12c+ 推荐
+SELECT * FROM employees ORDER BY salary DESC FETCH FIRST 10 ROWS ONLY;
+
+-- ROWID 最快行定位
+SELECT * FROM employees WHERE ROWID = 'AAAR3qAAEAAAACvAAA';
+```
+
+## 集合操作
+
+```sql
+-- UNION / UNION ALL / INTERSECT / MINUS
+SELECT department_id FROM departments
+MINUS
+SELECT DISTINCT department_id FROM employees;  -- 没有员工的部门
+```

skills/database-skills/oracle/references/10-features.md

@@ -0,0 +1,174 @@
+# Oracle 特有特性 — 分区 / 索引 / 物化视图 / Flashback / AQ
+
+## 表空间与数据文件
+
+```sql
+-- 创建表空间
+CREATE TABLESPACE tbs_app_data
+    DATAFILE '/u01/oradata/orcl/app_data01.dbf' SIZE 10G
+    AUTOEXTEND ON NEXT 1G MAXSIZE 32G;
+
+-- 创建临时/撤销表空间
+CREATE TEMPORARY TABLESPACE tbs_app_temp TEMPFILE '/u01/oradata/orcl/app_temp01.dbf' SIZE 5G;
+CREATE UNDO TABLESPACE tbs_app_undo DATAFILE '/u01/oradata/orcl/app_undo01.dbf' SIZE 10G;
+
+-- 表空间管理
+ALTER TABLESPACE tbs_app_data ADD DATAFILE '/u01/oradata/orcl/app_data02.dbf' SIZE 10G;
+ALTER TABLESPACE tbs_app_data READ ONLY;
+ALTER TABLESPACE tbs_app_data OFFLINE NORMAL;
+
+-- 表空间使用率
+SELECT df.tablespace_name,
+       ROUND(df.bytes/1024/1024/1024,2) AS total_gb,
+       ROUND((1-fs.bytes/df.bytes)*100,2) AS used_pct
+FROM (SELECT tablespace_name, SUM(bytes) AS bytes FROM dba_data_files GROUP BY tablespace_name) df
+JOIN (SELECT tablespace_name, SUM(bytes) AS bytes FROM dba_free_space GROUP BY tablespace_name) fs
+ON df.tablespace_name = fs.tablespace_name;
+```
+
+## 分区表
+
+```sql
+-- RANGE 分区
+CREATE TABLE sales (
+    sale_id NUMBER(10), sale_date DATE, amount NUMBER(10,2)
+) PARTITION BY RANGE (sale_date) (
+    PARTITION p_2023_q1 VALUES LESS THAN (DATE '2023-04-01'),
+    PARTITION p_2023_q2 VALUES LESS THAN (DATE '2023-07-01'),
+    PARTITION p_future VALUES LESS THAN (MAXVALUE)
+);
+
+-- LIST 分区
+CREATE TABLE customers PARTITION BY LIST (region) (
+    PARTITION p_north VALUES ('北京','天津','河北'),
+    PARTITION p_east VALUES ('上海','江苏','浙江'),
+    PARTITION p_other VALUES (DEFAULT)
+);
+
+-- HASH 分区
+CREATE TABLE logs PARTITION BY HASH (log_id) PARTITIONS 8;
+
+-- 复合分区（RANGE-HASH）
+CREATE TABLE sales_comp PARTITION BY RANGE (sale_date)
+SUBPARTITION BY HASH (region) SUBPARTITIONS 4 (
+    PARTITION p_2023_q1 VALUES LESS THAN (DATE '2023-04-01')
+);
+
+-- 间隔分区（11g+ 自动建分区）
+CREATE TABLE sales_interval PARTITION BY RANGE (sale_date)
+INTERVAL(NUMTOYMINTERVAL(1,'MONTH')) (
+    PARTITION p_first VALUES LESS THAN (DATE '2023-01-01')
+);
+
+-- 分区操作
+ALTER TABLE sales ADD PARTITION p_2024_q1 VALUES LESS THAN (DATE '2024-04-01');
+ALTER TABLE sales TRUNCATE PARTITION p_future;
+ALTER TABLE sales EXCHANGE PARTITION p_2023_q1 WITH TABLE sales_2023_q1;
+ALTER TABLE sales MERGE PARTITIONS p_2023_q1, p_2023_q2 INTO PARTITION p_2023_h1;
+ALTER TABLE sales SPLIT PARTITION p_future AT (DATE '2024-04-01')
+    INTO (PARTITION p_2024_q1, PARTITION p_future);
+```
+
+## 索引
+
+```sql
+-- B-Tree 索引（默认）
+CREATE INDEX idx_emp_dept_id ON employees(department_id);
+CREATE INDEX idx_emp_dept_name ON employees(department_id, last_name);  -- 复合
+CREATE UNIQUE INDEX idx_emp_email ON employees(email);                 -- 唯一
+
+-- 位图索引（适合低基数、数据仓库）
+CREATE BITMAP INDEX idx_sales_region ON sales(region);
+
+-- 函数索引
+CREATE INDEX idx_emp_upper_name ON employees(UPPER(last_name));
+
+-- 域索引（Oracle Text 全文）
+CREATE INDEX idx_docs_content ON documents(content) INDEXTYPE IS CTXSYS.CONTEXT;
+
+-- 索引监控
+ALTER INDEX idx_emp_dept_id MONITORING USAGE;
+SELECT * FROM v$object_usage;  -- 查看未被使用的索引
+```
+
+## 物化视图
+
+```sql
+-- 基本物化视图
+CREATE MATERIALIZED VIEW mv_dept_salary_summary
+    BUILD IMMEDIATE REFRESH COMPLETE ON DEMAND ENABLE QUERY REWRITE
+AS SELECT d.department_id, d.department_name,
+          COUNT(e.employee_id) AS emp_count, SUM(e.salary) AS total_salary
+FROM departments d LEFT JOIN employees e ON d.department_id = e.department_id
+GROUP BY d.department_id, d.department_name;
+
+-- 快速刷新物化视图（需物化视图日志）
+CREATE MATERIALIZED VIEW LOG ON employees WITH PRIMARY KEY, ROWID (salary, department_id) INCLUDING NEW VALUES;
+CREATE MATERIALIZED VIEW mv_emp_fast
+    BUILD IMMEDIATE REFRESH FAST ON COMMIT
+AS SELECT department_id, COUNT(*) AS cnt, SUM(salary) AS total_sal
+FROM employees GROUP BY department_id;
+
+-- 刷新
+EXEC DBMS_MVIEW.REFRESH('mv_dept_salary_summary', 'C');  -- C=完全, F=快速
+ALTER SESSION SET QUERY_REWRITE_ENABLED = TRUE;
+```
+
+## Flashback 技术
+
+```sql
+-- Flashback Query — 见 references/09-sql-syntax.md
+
+-- Flashback Table（需启用行移动）
+ALTER TABLE employees ENABLE ROW MOVEMENT;
+FLASHBACK TABLE employees TO TIMESTAMP (SYSTIMESTAMP - INTERVAL '15' MINUTE);
+FLASHBACK TABLE employees TO SCN 1234567;
+FLASHBACK TABLE employees TO RESTORE POINT before_batch;
+
+-- Flashback Drop（回收站）
+DROP TABLE employees;
+SELECT object_name, original_name, droptime FROM recyclebin;
+FLASHBACK TABLE employees TO BEFORE DROP;
+
+-- Flashback Database（需启用闪回日志）
+-- FLASHBACK DATABASE TO TIMESTAMP (SYSTIMESTAMP - INTERVAL '1' HOUR);
+```
+
+## AQ（Advanced Queuing）— 高级队列
+
+```sql
+-- 创建类型和队列表
+CREATE OR REPLACE TYPE order_msg AS OBJECT (order_id NUMBER, customer_id NUMBER, amount NUMBER);
+/
+BEGIN
+    DBMS_AQADM.CREATE_QUEUE_TABLE(queue_table => 'order_queue_table', queue_payload_type => 'order_msg');
+    DBMS_AQADM.CREATE_QUEUE(queue_name => 'order_queue', queue_table => 'order_queue_table');
+    DBMS_AQADM.START_QUEUE(queue_name => 'order_queue');
+END;
+/
+
+-- 发送消息
+DECLARE
+    enqueue_options    DBMS_AQ.ENQUEUE_OPTIONS_T;
+    message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
+    message_handle     RAW(16);
+    msg                order_msg := order_msg(1001, 500, 1500.00);
+BEGIN
+    DBMS_AQ.ENQUEUE('order_queue', enqueue_options, message_properties, msg, message_handle);
+    COMMIT;
+END;
+/
+
+-- 接收消息
+DECLARE
+    dequeue_options    DBMS_AQ.DEQUEUE_OPTIONS_T;
+    message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
+    message_handle     RAW(16);
+    msg                order_msg;
+BEGIN
+    dequeue_options.wait := DBMS_AQ.FOREVER;
+    DBMS_AQ.DEQUEUE('order_queue', dequeue_options, message_properties, msg, message_handle);
+    COMMIT;
+END;
+/
+```

skills/database-skills/postgresql/SKILL.md

@@ -1,28 +1,182 @@
 ---
 name: postgresql
-description: Provides comprehensive guidance for PostgreSQL database including SQL syntax, advanced features, JSON support, full-text search, and performance tuning. Use when the user asks about PostgreSQL, needs to work with PostgreSQL features, write complex queries, or optimize PostgreSQL databases.
+description: Provides comprehensive guidance for PostgreSQL including SQL syntax, advanced features (JSONB/CTE/Full-text), functions, indexing, performance tuning, replication, and backup. Use when the user asks about PostgreSQL, needs to work with PostgreSQL features, write complex queries, or optimize PostgreSQL databases.
 license: Complete terms in LICENSE.txt
 ---
 
-## When to use this skill
+# PostgreSQL — 高级关系型数据库系统
 
-Use this skill whenever the user wants to:
-- 设计表、索引、约束、触发器与 PL/pgSQL；编写或优化 SQL
-- 使用 psql、pg_dump、用户与角色权限
-- 排查锁、VACUUM、复制与扩展（如 pgvector）
+## Workflow — 使用流程
 
-## How to use this skill
+```text
+遇到 PostgreSQL 需求时，按以下顺序决策:
 
-1. **SQL**：DDL、DML、窗口函数、CTE；EXPLAIN ANALYZE 分析；扩展如 JSONB、全文检索。
-2. **CLI**：`psql` 连接与元命令；`pg_dump/pg_restore` 备份；配置 pg_hba.conf 与 listen_addresses。
-3. **环境**：版本与扩展兼容；生产用流复制与 PITR；监控连接、锁与表膨胀。
+1. 明确需求类型
+   ├── DDL (建表/改表)        → 见 SQL 语法速查
+   ├── DML (查询/插入/更新)    → 见 SQL 语法速查
+   ├── 函数/数据处理            → 见 函数速查
+   ├── 查询性能优化             → 见 references/06-index-types.md + examples/03-performance-tuning.md
+   └── 高可用/备份/复制         → 见 references/08-replication-backup.md + examples/04-streaming-replication.md
 
-## Best Practices
+2. 确定模型: 关系型 → 标准表+B-Tree | JSON文档 → JSONB+GIN | 全文搜索 → tsvector+GIN | 地理 → PostGIS+GiST
 
-- 合理使用索引与 VACUUM；大表分区与归档。
-- 权限用 ROLE 与 GRANT 细化；敏感数据可加密列。
-- 备份与 WAL 归档验证；升级前测试与回滚方案。
+3. 索引策略: 等值→B-Tree | 范围→B-Tree | 全文→GIN | JSON→GIN | 向量→IVFFlat/HNSW | 大表时序→BRIN
+
+4. 数据量评估: <100GB→单实例 | 100GB-1TB→分区 | 1TB-10TB→分区+只读副本 | >10TB→Citus/逻辑复制
+
+5. 运维策略: autovacuum + pg_stat_statements + WAL归档 + PgBouncer
+```
+
+## When to Use (and When NOT to)
+
+| ✅ Use When | ❌ Skip When |
+|------------|-------------|
+| 需要完整 ACID 事务和复杂 SQL | 纯键值缓存 (用 Redis/Memcached) |
+| JSON 文档 + SQL 查询混合 | 纯文档无关联查询 (用 MongoDB) |
+| 地理空间数据分析 (PostGIS) | 大规模全文搜索 (用 Elasticsearch) |
+| 强数据完整性约束 | 海量无模式日志 (用 Elasticsearch/S3) |
+| OLTP + 复杂 OLAP 混合负载 | 超大规模 OLAP (用 ClickHouse/Snowflake) |
+| 需要流复制/逻辑复制/PITR | 自动水平分片 (用 CockroachDB/YugabyteDB) |
+
+**核心原则：PostgreSQL 是全能型关系型数据库，但不是所有场景的最佳选择。**
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 → 替代 |
+|------------|--------------|----------------|
+| 标准 OLTP 业务系统 | 超大规模 OLAP >20TB → ClickHouse/cstore_fdw | 纯内存缓存 <1ms → Redis |
+| JSONB + 关系查询混合 | 高并发简单 KV >50万 QPS → Redis | 海量时序写入 >100万点/秒 → InfluxDB |
+| 全文搜索 (数亿文档) | 实时搜索 >10亿文档 → Elasticsearch | 复杂图遍历 → Neo4j |
+| 流复制 HA (故障恢复 <30s) | 跨地域多活 → CockroachDB | 自动分片无感扩缩容 |
+
+## SQL 语法速查
+
+深度 SQL 内容见 `references/` 各文件，此处为索引。
+
+- **DDL**: `CREATE TABLE` (含分区、继承), `ALTER TABLE`, 数据类型 (JSONB/TSVECTOR/CITEXT/数组等), 约束 (CHECK/EXCLUDE/UNIQUE/FOREIGN KEY)
+- **DML**: `INSERT ... ON CONFLICT` (UPSERT), `UPDATE ... FROM`, `DELETE ... USING`, `TRUNCATE`, `RETURNING` 子句
+- **CTE**: 公用表表达式 (`WITH`), 递归 CTE (`WITH RECURSIVE`) — 见 `examples/02-cte-recursive.md`
+- **连接**: `INNER/LEFT/RIGHT/FULL/CROSS JOIN`, `LATERAL` 子查询
+- **事务**: `READ COMMITTED` (默认), `REPEATABLE READ`, `SERIALIZABLE`, `SAVEPOINT`, `FOR UPDATE/SHARE/NOWAIT/SKIP LOCKED`, 咨询锁
+
+## 函数速查
+
+深度内容见 `references/`:
+
+| 类别 | 关键函数 | 参考文件 |
+|------|---------|---------|
+| 字符串/正则 | `FORMAT`, `SPLIT_PART`, `REGEXP_MATCH/REPLACE`, `STRING_AGG`, `CONCAT_WS`, `TRANSLATE`, `SUBSTRING` | `references/01-functions-string.md` |
+| 日期/时间 | `AGE`, `DATE_TRUNC`, `EXTRACT`, `TO_CHAR`, `MAKE_DATE`, `JUSTIFY_*`, 时区转换 | `references/02-functions-datetime.md` |
+| 聚合/窗口 | `ARRAY_AGG`, `JSONB_AGG`, `STRING_AGG`, `PERCENTILE_CONT/DISC`, `MODE`, `GROUPING SETS/CUBE/ROLLUP`, `ROW_NUMBER`, `RANK`, `LAG/LEAD`, `NTILE`, 窗口帧 | `references/03-functions-aggregate-window.md` |
+| JSONB | `->`/`->>`/`#>`, `@>`/`?`/`?|`/`?&`, `JSONB_SET`, `JSONB_BUILD_OBJECT`, `JSONB_EACH`, `JSONB_TYPEOF`, GIN 索引 | `references/04-functions-jsonb.md` |
+
+## 高级特性索引
+
+| 特性 | 说明 | 参考 |
+|------|------|------|
+| 6种索引 | B-Tree, Hash, GiST, GIN, BRIN, SP-GiST, Bloom + 部分索引/覆盖索引/CONCURRENTLY | `references/06-index-types.md` |
+| 视图与物化视图 | 普通视图 (虚拟表) vs 物化视图 (物理快照), WITH CHECK OPTION, CONCURRENTLY 刷新 | `references/06-index-types.md` |
+| PL/pgSQL | 函数 (FUNCTION) vs 过程 (PROCEDURE), 控制结构, 异常处理, 函数重载 | `references/01-functions-string.md` |
+| 触发器 | BEFORE/AFTER/INSTEAD OF, 行级/语句级, 事件触发器, 约束触发器 | `references/01-functions-string.md` |
+| 全文搜索 | tsvector/tsquery, @@ 操作符, ts_rank, ts_headline, 短语搜索, 中文搜索 (zhparser) | `references/05-fulltext-search.md` |
+| 分区表 | RANGE/LIST/HASH 分区, 子分区, 分区裁剪, ATTACH/DETACH | `references/07-partition-fdw.md` |
+| FDW 外部表 | postgres_fdw, file_fdw, IMPORT FOREIGN SCHEMA | `references/07-partition-fdw.md` |
+| 扩展 | PostGIS, pgvector, pg_stat_statements, uuid-ossp, pgcrypto, citext, pg_trgm, unaccent | `references/08-replication-backup.md` |
+| 权限管理 | ROLE, SCHEMA, GRANT, 默认权限, RLS 行级安全 | `references/08-replication-backup.md` |
+| 流复制与逻辑复制 | 同步/异步, PUBLICATION/SUBSCRIPTION, Patroni/repmgr | `references/08-replication-backup.md` |
+| 备份与恢复 | pg_dump/pg_restore, pg_basebackup, WAL 归档 + PITR | `references/08-replication-backup.md` |
+| 性能优化 | EXPLAIN ANALYZE, VACUUM/autovacuum, pg_stat_statements, 配置调优 | `examples/03-performance-tuning.md` |
+
+## Gotchas — 常见陷阱与反模式
+
+| # | 陷阱 | 风险 | 解决方案 |
+|---|------|------|---------|
+| 1 | JSONB 未建 GIN 索引 | 全表扫描, 性能差 | `CREATE INDEX ... USING GIN (config)` |
+| 2 | 大量直连数据库 | 每个连接耗 5-10MB, 撑爆内存 | 使用 PgBouncer 连接池 |
+| 3 | 索引膨胀未维护 | 索引体积远超表大小 | 定期 `REINDEX` 或 pg_repack |
+| 4 | N+1 查询 + `SELECT *` | 传输冗余数据, 多次查询 | 只选需要列, 用 JOIN/LATERAL |
+| 5 | 生产高峰期 `VACUUM FULL` | 锁表, 业务中断 | 用 pg_repack (不锁表) |
+| 6 | autovacuum 触发不及时 | 死元组堆积 → 表膨胀 → 性能崩溃 | 监控 n_dead_tup, 调参 |
+| 7 | `SERIAL` 而非 `BIGSERIAL` | 超 21 亿行后 ID 溢出 | 新表用 `BIGSERIAL` 或 UUID |
+| 8 | 多租户未设 RLS | 数据泄露 | 启用 RLS + 外键约束 |
+| 9 | 忽略事务 ID 回卷 | 数据库强制只读 | 监控 `age(relfrozenxid)` |
+| 10 | UUID 做主键 (v4 随机) | B-Tree 页分裂, 写入慢 2-3x | 用 UUID v7 或 BIGSERIAL |
+| 11 | 大表 `COUNT(*)` | 千万行以上全表扫描极慢 | 用 `pg_class.reltuples` 近似值 |
+| 12 | 外键无索引 | 删除/更新父表时子表全表扫描 | 外键列上建索引 |
+| 13 | SERIALIZABLE 无重试逻辑 | 事务冲突失败 | 应用层实现重试 |
+
+## FAQ
+
+**Q1: PostgreSQL vs MySQL 主要区别？**
+PostgreSQL: 完全 ACID, JSONB 可索引, 6 种索引类型, 递归 CTE, 流复制+逻辑复制, 丰富 EXTENSION。MySQL: Web 应用为主, 简单查询, InnoDB 事务, 间隙锁并发控制。
+
+**Q2: JSONB vs JSON？**
+始终选 JSONB。二进制格式, 支持 GIN 索引, 查询更快。JSON 仅在你需要保留空格和键顺序时使用。
+
+**Q3: UUID 为什么不适合做主键？**
+UUID v4 随机值导致 B-Tree 页频繁分裂, 比 BIGSERIAL 慢 2-3 倍。方案: UUID v7 (时间排序), BIGSERIAL, 或 ULID/Snowflake。
+
+**Q4: 如何在线迁移 PostgreSQL？**
+逻辑复制 (PG 10+, 推荐) > pglogical 扩展 > pg_dump+pg_restore (需停机)。逻辑复制支持跨大版本、选择性复制。
+
+**Q5: work_mem 怎么设？**
+每个排序操作分配, 最大内存 = work_mem × (连接数 × 并发排序数)。64GB 机器建议 64-128MB。监控 temp_files 指标, 有磁盘排序则调大。
+
+**Q6: pg_repack vs VACUUM FULL？**
+VACUUM FULL 锁表 (ACCESS EXCLUSIVE)。pg_repack 不锁写, 适合在线环境, 优先选择。
+
+**Q7: 死锁怎么处理？**
+PG 自动检测并回滚一个事务。预防: 保持锁顺序一致、缩短事务、用 NOWAIT/SKIP LOCKED, 监控 pg_stat_database.deadlocks。
+
+**Q8: 如何选择分区键？**
+条件: 查询频繁出现 (分区裁剪)、数据均匀分布、稳定不变。常见: 时间 (RANGE)、地区 (LIST)、ID 哈希 (HASH)。分区数建议 10-200。
+
+**Q9: 连接数设多少？**
+每个连接 5-10MB, 一般 200-500 够用。超过 500 必须用 PgBouncer。(max_connections × work_mem × 0.5) + shared_buffers + 系统开销 < 内存 80%。
+
+**Q10: 何时用 SERIALIZABLE？**
+金融转账、库存扣减、强一致性报表。注意: 失败率随冲突上升, 应用层需重试逻辑。
+
+**Q11: 查询没走索引的原因？**
+统计信息过旧→ANALYZE | 类型不匹配→隐式转换 | 选择性低→规划器认为全表更优 | 函数包裹索引列→避免 WHERE DATE(col) = 写法。
+
+**Q12: 怎么判断要不要分区？**
+表 > 100GB | 存在明显按时间/地区查询模式 | 旧数据定期归档 | VACUUM 跟不上更新。不满足则分区复杂度 > 收益。
+
+**Q13: 如何大版本升级？**
+pg_upgrade 最推荐: `pg_upgrade -b old_bin -B new_bin -d old_data -D new_data`, --link 模式最快。升级后执行 ANALYZE。
+
+**Q14: 逻辑复制 vs 流复制？**
+流复制: 物理块级, 全库, 大版本必须一致, 用于 HA。逻辑复制: SQL 变更, 选表/行, 跨大版本, 用于数据同步/迁移。
+
+**Q15: VACUUM 后表大小没变小？**
+VACUUM (不带 FULL) 只标记空间可重用, 不还给 OS。真正缩小需 VACUUM FULL 或 pg_repack。
 
 ## Keywords
 
-postgresql, postgres, psql, 关系型数据库, 索引, 复制
+postgresql, postgres, psql, SQL, DDL, DML, ACID, MVCC, 事务, 索引, B-Tree, GIN, GiST, BRIN, JSONB, hstore, 数组, 全文搜索, tsvector, tsquery, 窗口函数, CTE, 递归CTE, LATERAL, PL/pgSQL, 存储过程, 触发器, 物化视图, 分区表, PostGIS, pgvector, pg_stat_statements, pgcrypto, citext, pg_trgm, FDW, postgres_fdw, EXPLAIN, VACUUM, autovacuum, pg_dump, pg_restore, pg_basebackup, WAL归档, PITR, 流复制, 逻辑复制, PUBLICATION, SUBSCRIPTION, Patroni, repmgr, PgBouncer, RLS, 行级安全, 性能优化, 备份恢复, 高可用, 死锁, 连接池
+
+## References
+
+- [PostgreSQL 官方文档](https://www.postgresql.org/docs/current/)
+- [PostgreSQL 中文文档](http://www.postgres.cn/docs/16/)
+- [PostgreSQL 性能调优 — pgtune](https://pgtune.leopard.in.ua)
+- [Patroni 文档](https://patroni.readthedocs.io/)
+- [PgBouncer 官方文档](https://www.pgbouncer.org/)
+- [pgvector 文档](https://github.com/pgvector/pgvector)
+- [PostGIS 文档](https://postgis.net/documentation/)
+
+### 内部参考
+
+- `references/01-functions-string.md` — 字符串/正则函数详解
+- `references/02-functions-datetime.md` — 日期/时间函数详解
+- `references/03-functions-aggregate-window.md` — 聚合/窗口函数详解
+- `references/04-functions-jsonb.md` — JSONB 函数与操作详解
+- `references/05-fulltext-search.md` — 全文搜索详解
+- `references/06-index-types.md` — 索引类型与视图详解
+- `references/07-partition-fdw.md` — 分区表与 FDW 详解
+- `references/08-replication-backup.md` — 复制/备份/权限详解
+- `examples/01-jsonb-query.md` — JSONB 查询示例
+- `examples/02-cte-recursive.md` — 递归 CTE 示例
+- `examples/03-performance-tuning.md` — 性能调优示例
+- `examples/04-streaming-replication.md` — 流复制搭建示例

skills/database-skills/postgresql/examples/01-jsonb-query.md

@@ -0,0 +1,72 @@
+# JSONB 查询示例
+
+## 场景：电商用户配置系统
+
+本示例演示如何使用 JSONB 存储和查询用户偏好配置。
+
+## 建表与数据
+
+```sql
+-- 建表
+CREATE TABLE user_configs (
+    id      BIGSERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    config  JSONB NOT NULL DEFAULT '{}'
+);
+
+-- 插入示例数据
+INSERT INTO user_configs (user_id, config) VALUES
+(1, '{
+    "theme": "dark",
+    "notifications": {"email": true, "sms": false, "push": true},
+    "preferences": {"language": "zh-CN", "timezone": "Asia/Shanghai"},
+    "tags": ["developer", "premium"],
+    "trust_score": 4.5
+}'),
+(2, '{
+    "theme": "light",
+    "notifications": {"email": false, "sms": true, "push": false},
+    "preferences": {"language": "en", "timezone": "America/New_York"},
+    "tags": ["basic"]
+}');
+
+-- 创建 GIN 索引
+CREATE INDEX idx_config_gin ON user_configs USING GIN (config);
+```
+
+## 查询示例
+
+```sql
+-- 1. 查询所有使用深色主题的用户
+SELECT user_id, config ->> 'theme' AS theme
+FROM user_configs
+WHERE config @> '{"theme": "dark"}';
+
+-- 2. 查询开启了邮件通知的用户
+SELECT user_id FROM user_configs
+WHERE config @> '{"notifications": {"email": true}}';
+
+-- 3. 查询有 trust_score 字段的用户
+SELECT user_id FROM user_configs WHERE config ? 'trust_score';
+
+-- 4. 查询语言为中文的高级用户 (tags 包含 "premium")
+SELECT user_id FROM user_configs
+WHERE config @> '{"preferences": {"language": "zh-CN"}}'
+  AND config @> '{"tags": ["premium"]}';
+
+-- 5. 更新嵌套字段（开启 SMS 通知）
+UPDATE user_configs SET config = JSONB_SET(
+    config, '{notifications, sms}', 'true'::JSONB
+) WHERE user_id = 1;
+
+-- 6. 追加标签
+UPDATE user_configs SET config = config || '{"tags": ["vip"]}'
+WHERE user_id = 1;
+
+-- 7. 展开 JSONB 查看所有键值对
+SELECT key, value FROM user_configs c,
+JSONB_EACH(c.config) WHERE user_id = 1;
+
+-- 8. 聚合用户配置为 JSONB 数组
+SELECT JSONB_AGG(config) AS all_configs FROM user_configs;
+```

skills/database-skills/postgresql/examples/02-cte-recursive.md

@@ -0,0 +1,110 @@
+# 递归 CTE 示例
+
+## 场景 1：组织架构树
+
+查询从根节点到所有子节点的完整部门树。
+
+```sql
+-- 建表
+CREATE TABLE departments (
+    id          SERIAL PRIMARY KEY,
+    name        TEXT NOT NULL,
+    parent_id   INTEGER REFERENCES departments(id)
+);
+
+-- 插入层级数据
+INSERT INTO departments (id, name, parent_id) VALUES
+    (1, '总公司', NULL),
+    (2, '技术部', 1),
+    (3, '市场部', 1),
+    (4, '后端组', 2),
+    (5, '前端组', 2),
+    (6, '数据组', 2),
+    (7, '广告组', 3),
+    (8, 'PR 组', 3);
+
+-- 递归 CTE: 展开整个树
+WITH RECURSIVE org_tree AS (
+    -- 基础: 根节点
+    SELECT id, name, parent_id, 1 AS level, ARRAY[id] AS path
+    FROM departments
+    WHERE parent_id IS NULL
+
+    UNION ALL
+
+    -- 递归: 子节点
+    SELECT d.id, d.name, d.parent_id, t.level + 1, t.path || d.id
+    FROM departments d
+    JOIN org_tree t ON d.parent_id = t.id
+)
+SELECT id, name, level, repeat('  ', level - 1) || name AS tree_display
+FROM org_tree ORDER BY path;
+```
+
+## 场景 2：商品分类全路径
+
+将树形分类扁平化并显示完整路径。
+
+```sql
+-- 建表
+CREATE TABLE categories (
+    id          SERIAL PRIMARY KEY,
+    name        TEXT NOT NULL,
+    parent_id   INTEGER REFERENCES categories(id)
+);
+
+INSERT INTO categories (id, name, parent_id) VALUES
+    (1, '电子产品', NULL),
+    (2, '手机', 1),
+    (3, '电脑', 1),
+    (4, '智能手机', 2),
+    (5, '功能机', 2),
+    (6, '笔记本', 3),
+    (7, '台式机', 3);
+
+-- 从指定节点开始，查询所有子分类及其全路径
+WITH RECURSIVE category_tree AS (
+    SELECT id, name, parent_id, name AS full_path
+    FROM categories WHERE id = 1  -- 从 "电子产品" 开始
+
+    UNION ALL
+
+    SELECT c.id, c.name, c.parent_id,
+           ct.full_path || ' > ' || c.name
+    FROM categories c
+    JOIN category_tree ct ON c.parent_id = ct.id
+)
+SELECT * FROM category_tree ORDER BY full_path;
+```
+
+## 场景 3：斐波那契数列
+
+```sql
+WITH RECURSIVE fib(a, b) AS (
+    SELECT 0::BIGINT, 1::BIGINT
+    UNION ALL
+    SELECT b, a + b FROM fib WHERE b < 1000
+)
+SELECT a FROM fib;
+```
+
+## 场景 4：销售统计占比
+
+使用非递归 CTE 计算每个分类的销售额占比。
+
+```sql
+WITH category_sales AS (
+    SELECT c.name AS category, SUM(oi.quantity * oi.price) AS total
+    FROM order_items oi
+    JOIN products p ON p.id = oi.product_id
+    JOIN categories c ON c.id = p.category_id
+    GROUP BY c.name
+),
+grand_total AS (
+    SELECT SUM(total) AS total FROM category_sales
+)
+SELECT cs.category, cs.total,
+       ROUND(cs.total / gt.total * 100, 2) AS pct
+FROM category_sales cs, grand_total gt
+ORDER BY cs.total DESC;
+```

skills/database-skills/postgresql/examples/03-performance-tuning.md

@@ -0,0 +1,114 @@
+# 性能调优示例
+
+## 场景 1：定位慢查询
+
+使用 EXPLAIN ANALYZE 诊断查询性能问题。
+
+```sql
+-- 创建测试表
+CREATE TABLE orders (
+    id BIGSERIAL, user_id INTEGER NOT NULL, status TEXT,
+    total_amount NUMERIC(12,2), created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- 插入测试数据（假设已有数百万行）
+
+-- 诊断慢查询
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM orders WHERE status = 'pending' AND created_at > '2024-01-01';
+-- 如果看到 Seq Scan → 需要加索引
+
+-- 创建复合索引
+CREATE INDEX idx_orders_status_created ON orders (status, created_at DESC);
+
+-- 再次验证
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM orders WHERE status = 'pending' AND created_at > '2024-01-01';
+-- 现在应该看到 Index Scan
+```
+
+## 场景 2：JOIN 性能优化
+
+```sql
+-- 慢查询：大表 JOIN + GROUP BY
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT u.name, COUNT(o.id) AS order_count
+FROM users u LEFT JOIN orders o ON o.user_id = u.id
+WHERE u.created_at > '2024-01-01'
+GROUP BY u.id, u.name;
+
+-- 检查输出中的 Sort Method
+-- 如果看到 "external merge Disk: 1536kB" → work_mem 不足
+
+-- 临时增加 work_mem（当前会话）
+SET work_mem = '256MB';
+
+-- 或者创建覆盖索引
+CREATE INDEX idx_orders_user_id_covering ON orders (user_id) INCLUDE (id);
+```
+
+## 场景 3：VACUUM 与膨胀监控
+
+```sql
+-- 查看表膨胀情况
+SELECT relname, n_live_tup, n_dead_tup,
+       ROUND(n_dead_tup::NUMERIC / NULLIF(n_live_tup, 0) * 100, 2) AS dead_pct,
+       last_autovacuum, last_autoanalyze
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 0
+ORDER BY n_dead_tup DESC LIMIT 20;
+
+-- 为高频更新表调优 autovacuum
+ALTER TABLE orders SET (
+    autovacuum_vacuum_scale_factor = 0.05,
+    autovacuum_vacuum_threshold = 1000
+);
+
+-- 检查事务 ID 回卷风险
+SELECT datname, age(datfrozenxid) AS age,
+       ROUND(100 * age(datfrozenxid)::NUMERIC / 2000000000, 2) AS pct_wraparound
+FROM pg_database ORDER BY age DESC;
+```
+
+## 场景 4：pg_stat_statements 分析
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- TOP 10 最耗时查询
+SELECT queryid, LEFT(query, 80) AS query_preview, calls,
+       ROUND(total_exec_time::NUMERIC, 2) AS total_ms,
+       ROUND(mean_exec_time::NUMERIC, 2) AS avg_ms,
+       ROUND(shared_blks_hit::NUMERIC / NULLIF(shared_blks_hit + shared_blks_read, 0) * 100, 2) AS hit_ratio
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC LIMIT 10;
+
+-- TOP 10 I/O 密集查询
+SELECT queryid, LEFT(query, 80) AS query_preview,
+       shared_blks_read, temp_blks_read
+FROM pg_stat_statements
+WHERE shared_blks_read > 1000
+ORDER BY shared_blks_read DESC LIMIT 10;
+
+-- TOP 10 临时文件使用（work_mem 不足）
+SELECT queryid, LEFT(query, 80) AS query_preview,
+       temp_blk_read_time, temp_blk_write_time
+FROM pg_stat_statements
+WHERE temp_blk_read_time > 0
+ORDER BY temp_blk_read_time DESC LIMIT 10;
+```
+
+## 场景 5：配置调优参考
+
+```conf
+# 64GB 内存服务器参考配置
+shared_buffers = 12GB            # 物理内存 20-25%
+work_mem = 64MB                  # 每个排序操作
+maintenance_work_mem = 1GB       # VACUUM/CREATE INDEX
+effective_cache_size = 12GB      # 规划器缓存估计
+wal_buffers = 16MB
+max_connections = 200            # 超过则用 PgBouncer
+checkpoint_timeout = 15min
+max_wal_size = 16GB
+default_statistics_target = 100  # 大表可调至 500-1000
+```

skills/database-skills/postgresql/examples/04-streaming-replication.md

@@ -0,0 +1,113 @@
+# 流复制搭建示例
+
+## 场景：搭建一主一从的高可用架构
+
+### 主库配置
+
+```conf
+# postgresql.conf 配置
+listen_addresses = 'localhost,192.168.1.100'
+wal_level = replica
+max_wal_senders = 10
+wal_keep_size = 1GB
+hot_standby = on
+```
+
+```bash
+# 重启主库
+systemctl restart postgresql
+```
+
+### 创建复制用户
+
+```sql
+-- 在主库执行
+CREATE USER replicator WITH REPLICATION LOGIN PASSWORD 'Str0ng!Pass';
+```
+
+```bash
+# 在 pg_hba.conf 添加
+echo 'host replication replicator 192.168.1.0/24 md5' >> /var/lib/pgsql/data/pg_hba.conf
+
+# 重新加载配置
+psql -c "SELECT pg_reload_conf();"
+```
+
+### 从库搭建
+
+```bash
+# 安装相同版本 PostgreSQL
+
+# 停从库
+systemctl stop postgresql
+
+# 清空从库数据目录
+rm -rf /var/lib/pgsql/data/*
+
+# 从主库拉取基础备份
+pg_basebackup -h 192.168.1.100 -U replicator \
+    -D /var/lib/pgsql/data -P -v --wal-method=stream
+
+# PG 12+: 创建 standby 信号文件
+touch /var/lib/pgsql/data/standby.signal
+
+# 配置主库连接信息
+cat > /var/lib/pgsql/data/postgresql.auto.conf << EOF
+primary_conninfo = 'host=192.168.1.100 port=5432 user=replicator password=Str0ng!Pass'
+EOF
+
+# 启动从库
+systemctl start postgresql
+```
+
+### 验证复制
+
+```sql
+-- 在主库检查复制状态
+SELECT pid, application_name, state, sync_state,
+       write_lag, flush_lag, replay_lag
+FROM pg_stat_replication;
+
+-- 在从库检查接收状态
+SELECT pid, status, receive_start_lsn, received_lsn,
+       latest_end_lsn, latest_end_time
+FROM pg_stat_wal_receiver;
+
+-- 测试: 在主库创建表并插入数据
+CREATE TABLE test_replication (id SERIAL PRIMARY KEY, data TEXT, ts TIMESTAMPTZ DEFAULT NOW());
+INSERT INTO test_replication (data) VALUES ('hello from primary');
+
+-- 在从库验证（从库为只读模式）
+SELECT * FROM test_replication;
+```
+
+### 故障转移
+
+```bash
+# 手动提升从库为主库
+# 在从库执行
+pg_ctl promote -D /var/lib/pgsql/data
+# 或
+systemctl stop postgresql
+# 删除 standby.signal 后启动
+rm /var/lib/pgsql/data/standby.signal
+systemctl start postgresql
+
+# 此时原从库变为可读写
+```
+
+### 常见问题排查
+
+```bash
+# 查看复制日志
+tail -f /var/lib/pgsql/data/log/postgresql-*.log
+
+# 检查网络连通性
+psql -h 192.168.1.100 -U replicator -d postgres -c "SELECT 1"
+
+# 检查 WAL 发送进程
+ps aux | grep wal_sender
+
+# 检查磁盘空间（WAL 堆积会导致磁盘满）
+df -h /var/lib/pgsql/data/
+```

skills/database-skills/postgresql/references/01-functions-string.md

@@ -0,0 +1,174 @@
+# 字符串/正则函数详解
+
+## 字符串函数
+
+```sql
+-- FORMAT — 格式化字符串
+SELECT FORMAT('ORD-%s-%04d', TO_CHAR(NOW(), 'YYYYMMDD'), 123);
+-- 结果: ORD-20240529-0123
+
+-- SPLIT_PART — 分割字符串
+SELECT SPLIT_PART('北京市海淀区中关村', '区', 1);
+-- 结果: 北京市海淀
+
+-- STRING_AGG — 字符串聚合（将分类名称合并为逗号分隔字符串）
+SELECT STRING_AGG(DISTINCT c.name, ', ' ORDER BY c.name) AS categories
+FROM products p
+JOIN product_categories pc ON pc.product_id = p.id
+JOIN categories c ON c.id = pc.category_id
+WHERE p.id = 1001;
+
+-- CONCAT / CONCAT_WS
+SELECT CONCAT_WS(', ', province, city, district, detail) AS full_address FROM addresses;
+
+-- LEFT / RIGHT
+SELECT LEFT('Hello World', 5);   -- Hello
+SELECT RIGHT('Hello World', 5);  -- World
+
+-- REPEAT / REVERSE
+SELECT REPEAT('*', 5);           -- *****
+SELECT REVERSE('PostgreSQL');    -- LQSregtsoP
+
+-- POSITION / STRPOS
+SELECT POSITION('SQL' IN 'PostgreSQL');  -- 7
+SELECT STRPOS('PostgreSQL', 'SQL');       -- 7
+
+-- SUBSTRING (支持正则)
+SELECT SUBSTRING('abc123def' FROM '[0-9]+');  -- 123
+
+-- TRANSLATE
+SELECT TRANSLATE('hello', 'aeiou', '12345');  -- h2ll4
+```
+
+## 正则函数
+
+```sql
+-- REGEXP_MATCH — 正则匹配（提取邮箱）
+SELECT REGEXP_MATCH(
+    '联系邮箱: alice@example.com, 备用: bob@test.com',
+    '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}',
+    'g'
+);
+-- 结果: {alice@example.com,bob@test.com}
+
+-- REGEXP_REPLACE — 正则替换（脱敏手机号）
+SELECT REGEXP_REPLACE('13812345678', '(\d{3})\d{4}(\d{4})', '\1****\2');
+-- 结果: 138****5678
+```
+
+## PL/pgSQL 函数
+
+```sql
+-- 标量函数
+CREATE OR REPLACE FUNCTION calculate_discount(
+    price NUMERIC, discount_pct NUMERIC, max_discount NUMERIC DEFAULT 100
+) RETURNS NUMERIC
+LANGUAGE plpgsql IMMUTABLE
+AS $$
+BEGIN
+    RETURN GREATEST(price * (1 - discount_pct / 100), price - max_discount);
+END;
+$$;
+
+-- 表函数 (RETURNS TABLE)
+CREATE OR REPLACE FUNCTION get_user_orders(
+    p_user_id INTEGER, p_status TEXT DEFAULT NULL, p_limit INTEGER DEFAULT 100
+) RETURNS TABLE (order_id BIGINT, total_amount NUMERIC(12,2), status TEXT, created_at TIMESTAMPTZ)
+LANGUAGE plpgsql STABLE
+AS $$
+BEGIN
+    RETURN QUERY
+    SELECT o.id, o.total_amount, o.status, o.created_at
+    FROM orders o
+    WHERE o.user_id = p_user_id AND (p_status IS NULL OR o.status = p_status)
+    ORDER BY o.created_at DESC LIMIT p_limit;
+END;
+$$;
+
+-- 函数 (FUNCTION) vs 过程 (PROCEDURE)
+-- FUNCTION: 必须返回值, SELECT 中调用
+-- PROCEDURE (PG 11+): 无返回值, CALL 调用, 支持事务控制
+
+-- 函数重载
+CREATE OR REPLACE FUNCTION format_price(price NUMERIC) RETURNS TEXT
+LANGUAGE SQL IMMUTABLE AS $$ SELECT '¥' || ROUND(price, 2)::TEXT; $$;
+
+CREATE OR REPLACE FUNCTION format_price(price NUMERIC, currency TEXT) RETURNS TEXT
+LANGUAGE SQL IMMUTABLE AS $$ SELECT currency || ROUND(price, 2)::TEXT; $$;
+
+-- PL/pgSQL 控制结构
+CREATE OR REPLACE FUNCTION process_order(p_order_id BIGINT) RETURNS TEXT
+LANGUAGE plpgsql
+AS $$
+DECLARE
+    v_order orders%ROWTYPE;
+    v_log TEXT := '';
+BEGIN
+    SELECT * INTO STRICT v_order FROM orders WHERE id = p_order_id;
+
+    IF v_order.status = 'pending' THEN
+        v_log := '待处理';
+    ELSIF v_order.status = 'paid' THEN
+        v_log := '已支付';
+    END IF;
+
+    RETURN v_log;
+EXCEPTION
+    WHEN NO_DATA_FOUND THEN RETURN '订单不存在';
+    WHEN OTHERS THEN RETURN '错误: ' || SQLERRM;
+END;
+$$;
+```
+
+## 触发器
+
+```sql
+-- 自动更新 updated_at
+CREATE OR REPLACE FUNCTION update_updated_at_column() RETURNS TRIGGER
+LANGUAGE plpgsql AS $$ BEGIN NEW.updated_at = NOW(); RETURN NEW; END; $$;
+
+CREATE TRIGGER trg_users_updated_at
+    BEFORE UPDATE ON users
+    FOR EACH ROW WHEN (OLD.* IS DISTINCT FROM NEW.*)
+    EXECUTE FUNCTION update_updated_at_column();
+
+-- 审计日志触发器
+CREATE OR REPLACE FUNCTION audit_order_changes() RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        INSERT INTO order_audit_log (order_id, new_data, action) VALUES (NEW.id, row_to_json(NEW)::JSONB, 'INSERT');
+    ELSIF TG_OP = 'UPDATE' THEN
+        INSERT INTO order_audit_log (order_id, old_data, new_data, action) VALUES (NEW.id, row_to_json(OLD)::JSONB, row_to_json(NEW)::JSONB, 'UPDATE');
+    ELSIF TG_OP = 'DELETE' THEN
+        INSERT INTO order_audit_log (order_id, old_data, action) VALUES (OLD.id, row_to_json(OLD)::JSONB, 'DELETE');
+    END IF;
+    RETURN NEW;
+END;
+$$;
+
+-- 事件触发器 (DDL)
+CREATE OR REPLACE FUNCTION prevent_table_drop() RETURNS EVENT_TRIGGER
+LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION '禁止删除表'; END; $$;
+CREATE EVENT TRIGGER prevent_drop_trigger ON sql_drop EXECUTE FUNCTION prevent_table_drop();
+```
+
+## 数字函数
+
+```sql
+-- RANDOM — 随机抽样
+SELECT * FROM users ORDER BY RANDOM() LIMIT 5;
+
+-- GENERATE_SERIES — 生成序列
+SELECT GENERATE_SERIES('2024-01-01'::DATE, '2024-01-10'::DATE, '1 day');
+SELECT GENERATE_SERIES(1, 10, 2);  -- 1, 3, 5, 7, 9
+
+-- WIDTH_BUCKET — 等宽分桶
+SELECT WIDTH_BUCKET(age, 0, 100, 10) AS bucket, MIN(age), MAX(age), COUNT(*)
+FROM users GROUP BY bucket ORDER BY bucket;
+
+-- ROUND / TRUNC / CEIL / FLOOR / POWER / SQRT / ABS / DIV / MOD / GCD / LCM
+SELECT ROUND(123.456, 2), TRUNC(123.456, 2), CEIL(123.001), FLOOR(123.999);
+SELECT POWER(2,10), SQRT(144), ABS(-42), DIV(10,3), MOD(10,3), GCD(12,18), LCM(12,18);
+```

skills/database-skills/postgresql/references/02-functions-datetime.md

@@ -0,0 +1,54 @@
+# 日期/时间函数详解
+
+```sql
+-- AGE — 计算时间差
+SELECT AGE('2024-05-29', '2023-01-15');
+-- 结果: 1 year 4 mons 14 days
+
+-- 计算年龄
+SELECT id, EXTRACT(YEAR FROM AGE(birth_date)) AS age FROM users;
+
+-- DATE_TRUNC — 时间截断（支持: microsecond, millisecond, second, minute, hour, day, week, month, quarter, year, decade, century, millennium）
+SELECT DATE_TRUNC('month', created_at) AS month, COUNT(*) AS order_count
+FROM orders GROUP BY month;
+
+-- EXTRACT — 提取日期部分
+SELECT
+    EXTRACT(YEAR FROM created_at) AS year,
+    EXTRACT(MONTH FROM created_at) AS month,
+    EXTRACT(DOW FROM created_at) AS day_of_week,  -- 0=Sunday
+    EXTRACT(HOUR FROM created_at) AS hour,
+    EXTRACT(QUARTER FROM created_at) AS quarter
+FROM orders;
+
+-- TO_CHAR — 日期格式化
+SELECT
+    TO_CHAR(created_at, 'YYYY-MM-DD HH24:MI:SS') AS formatted_time,
+    TO_CHAR(created_at, 'YYYY年MM月DD日') AS chinese_date,
+    TO_CHAR(created_at, 'Day, DD Month YYYY') AS english_date,
+    TO_CHAR(created_at, 'IW') AS iso_week_number
+FROM orders;
+
+-- JUSTIFY_DAYS / JUSTIFY_HOURS / JUSTIFY_INTERVAL
+SELECT JUSTIFY_DAYS(30::INTERVAL);   -- 30 days → 1 mon
+SELECT JUSTIFY_HOURS(100::INTERVAL); -- 100:00:00 → 4 days 04:00:00
+
+-- MAKE_DATE / MAKE_TIMESTAMPTZ / MAKE_INTERVAL (PG 10+)
+SELECT MAKE_DATE(2024, 6, 1);
+SELECT MAKE_TIMESTAMPTZ(2024, 6, 1, 10, 30, 0, 'Asia/Shanghai');
+SELECT MAKE_INTERVAL(days => 10, hours => 5);
+
+-- DATE 运算
+SELECT NOW(), NOW() + INTERVAL '1 day', NOW() - INTERVAL '3 hours';
+SELECT CURRENT_DATE, CURRENT_TIME;
+
+-- 时区转换
+SELECT
+    NOW() AT TIME ZONE 'Asia/Shanghai',
+    NOW() AT TIME ZONE 'UTC',
+    '2024-06-01 10:00:00+08'::TIMESTAMPTZ AT TIME ZONE 'America/New_York';
+
+-- 日期范围查询最佳实践
+-- ❌ 避免: WHERE created_at BETWEEN '2024-01-01' AND '2024-01-31'
+-- ✅ 推荐: WHERE created_at >= '2024-01-01' AND created_at < '2024-02-01'
+```

skills/database-skills/postgresql/references/03-functions-aggregate-window.md

@@ -0,0 +1,142 @@
+# 聚合/窗口函数详解
+
+## 聚合函数
+
+```sql
+-- ARRAY_AGG — 聚合为数组
+SELECT o.id, ARRAY_AGG(p.name ORDER BY p.name) AS products
+FROM orders o JOIN order_items oi ON oi.order_id = o.id
+JOIN products p ON p.id = oi.product_id GROUP BY o.id;
+
+-- STRING_AGG — 聚合为字符串
+SELECT article_id, STRING_AGG(DISTINCT tag, ', ' ORDER BY tag) AS tags
+FROM article_tags GROUP BY article_id;
+
+-- JSON_AGG / JSONB_AGG — 聚合为 JSON
+SELECT o.id, JSONB_AGG(JSONB_BUILD_OBJECT('product_id', oi.product_id, 'qty', oi.quantity)) AS items
+FROM orders o JOIN order_items oi ON oi.order_id = o.id GROUP BY o.id;
+
+-- MODE — 众数
+SELECT MODE() WITHIN GROUP (ORDER BY category_id) FROM products;
+
+-- PERCENTILE_CONT / PERCENTILE_DISC — 百分位数
+SELECT
+    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY total_amount) AS median,
+    PERCENTILE_CONT(0.25) WITHIN GROUP (ORDER BY total_amount) AS q1,
+    PERCENTILE_CONT(0.9) WITHIN GROUP (ORDER BY total_amount) AS p90
+FROM orders;
+
+-- GROUPING SETS / CUBE / ROLLUP
+SELECT COALESCE(department, 'ALL') AS dept, COALESCE(role, 'ALL') AS role,
+       COUNT(*) AS cnt, AVG(salary)::NUMERIC(10,2) AS avg_sal
+FROM employees
+GROUP BY GROUPING SETS ((department, role), (department), (role), ());
+
+SELECT category, brand, COUNT(*) FROM products GROUP BY CUBE (category, brand);
+
+SELECT EXTRACT(YEAR FROM created_at) AS year, EXTRACT(MONTH FROM created_at) AS month,
+       COUNT(*) FROM orders GROUP BY ROLLUP (year, month) ORDER BY year, month;
+```
+
+## 窗口函数
+
+```sql
+-- ROW_NUMBER — 行号
+SELECT id, name, category_id, price,
+       ROW_NUMBER() OVER (PARTITION BY category_id ORDER BY price DESC) AS rn
+FROM products;
+
+-- RANK / DENSE_RANK — 排名
+SELECT salesperson, amount,
+       RANK() OVER (ORDER BY amount DESC) AS rank,
+       DENSE_RANK() OVER (ORDER BY amount DESC) AS dense_rank
+FROM monthly_sales;
+
+-- NTILE — 分桶
+SELECT id, total_spent, NTILE(4) OVER (ORDER BY total_spent DESC) AS quartile
+FROM customers;
+
+-- LAG / LEAD — 前后行访问
+SELECT dt, revenue,
+       LAG(revenue, 1) OVER (ORDER BY dt) AS prev_day,
+       LAG(revenue, 7) OVER (ORDER BY dt) AS prev_week,
+       ROUND((revenue - LAG(revenue, 1) OVER (ORDER BY dt))
+             / NULLIF(LAG(revenue, 1) OVER (ORDER BY dt), 0) * 100, 2) AS dod_pct,
+       LEAD(revenue, 1) OVER (ORDER BY dt) AS next_day
+FROM daily_revenue;
+
+-- FIRST_VALUE / LAST_VALUE
+SELECT category_id, name, price,
+       FIRST_VALUE(price) OVER (PARTITION BY category_id ORDER BY price) AS min_price,
+       LAST_VALUE(price) OVER (PARTITION BY category_id ORDER BY price
+           RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS max_price
+FROM products;
+
+-- NTH_VALUE
+SELECT DISTINCT category_id,
+       NTH_VALUE(name, 3) OVER (PARTITION BY category_id ORDER BY price DESC
+           RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS third_expensive
+FROM products;
+
+-- 窗口帧控制
+SELECT dt, revenue,
+       AVG(revenue) OVER (ORDER BY dt ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS ma_7d,
+       AVG(revenue) OVER (ORDER BY dt ROWS BETWEEN 29 PRECEDING AND CURRENT ROW) AS ma_30d
+FROM daily_revenue;
+
+-- 累积求和
+SELECT dt, revenue, SUM(revenue) OVER (ORDER BY dt) AS cumulative_revenue
+FROM daily_revenue;
+
+-- 分组累计
+SELECT category_id, dt, revenue,
+       SUM(revenue) OVER (PARTITION BY category_id ORDER BY dt ROWS UNBOUNDED PRECEDING) AS cum_by_cat
+FROM daily_revenue_by_category;
+
+-- 窗口函数 + FILTER 条件聚合
+SELECT dt,
+       COUNT(*) AS total,
+       COUNT(*) FILTER (WHERE status = 'paid') AS paid,
+       COUNT(*) FILTER (WHERE status = 'cancelled') AS cancelled
+FROM orders GROUP BY dt;
+```
+
+## 数组函数
+
+```sql
+-- ARRAY — 构建数组
+SELECT ARRAY[1, 2, 3], ARRAY['a', 'b', 'c'];
+
+-- ANY / ALL — 元素检查
+SELECT * FROM articles WHERE '数据库' = ANY(tags);
+
+-- UNNEST — 展开数组
+SELECT UNNEST(tags) AS tag, COUNT(*) AS freq
+FROM articles GROUP BY tag ORDER BY freq DESC;
+
+-- ARRAY_APPEND / ARRAY_PREPEND / ARRAY_REMOVE / ARRAY_CAT
+SELECT ARRAY_APPEND(ARRAY[1,2], 3);      -- {1,2,3}
+SELECT ARRAY_PREPEND(0, ARRAY[1,2]);      -- {0,1,2}
+SELECT ARRAY_REMOVE(ARRAY[1,2,3], 2);     -- {1,3}
+SELECT ARRAY_CAT(ARRAY[1,2], ARRAY[3,4]); -- {1,2,3,4}
+
+-- 数组信息
+SELECT ARRAY_NDIMS(ARRAY[[1,2],[3,4]]), ARRAY_LENGTH(ARRAY[1,2,3], 1);
+
+-- ARRAY_POSITION / ARRAY_POSITIONS
+SELECT ARRAY_POSITION(ARRAY['a','b','c','b'], 'b');    -- 2
+SELECT ARRAY_POSITIONS(ARRAY['a','b','c','b'], 'b');    -- {2,4}
+
+-- STRING_TO_ARRAY / ARRAY_TO_STRING
+SELECT STRING_TO_ARRAY('a,b,c', ','), ARRAY_TO_STRING(ARRAY['a','b','c'], '|');
+
+-- 数组切片
+SELECT tags[1:3] FROM articles;
+
+-- @> / <@ — 包含, && — 重叠
+SELECT * FROM articles WHERE tags @> ARRAY['SQL', '高级'];
+SELECT * FROM articles WHERE tags && ARRAY['数据库', 'JSON'];
+
+-- 数组 GIN 索引
+CREATE INDEX idx_articles_tags_gin ON articles USING GIN (tags);
+```

skills/database-skills/postgresql/references/04-functions-jsonb.md

@@ -0,0 +1,117 @@
+# JSONB 函数与操作详解
+
+## 访问操作符
+
+```sql
+-- -> 返回 JSONB, ->> 返回 TEXT
+SELECT
+    config -> 'theme' AS theme_jsonb,              -- "dark"
+    config ->> 'theme' AS theme_text,              -- dark
+    config -> 'notifications' -> 'email' AS email_jsonb,
+    config #>> '{preferences, language}' AS lang
+
+FROM user_configs WHERE user_id = 1;
+
+-- #> / #>> 路径访问
+SELECT config #> '{preferences, timezone}' AS tz,
+       config #>> '{notifications, push}' AS push
+FROM user_configs WHERE user_id = 1;
+```
+
+## 包含与存在操作
+
+```sql
+-- @> — 包含（业务场景：查询包含特定配置的用户）
+SELECT user_id, config FROM user_configs
+WHERE config @> '{"notifications": {"email": true}}';
+
+-- ? — 是否存在键
+SELECT user_id FROM user_configs WHERE config ? 'trust_score';
+
+-- ?| — 存在任意键
+SELECT user_id FROM user_configs WHERE config ?| ARRAY['trust_score', 'vip_level'];
+
+-- ?& — 包含所有键
+SELECT user_id FROM user_configs WHERE config ?& ARRAY['theme', 'notifications'];
+```
+
+## 修改函数
+
+```sql
+-- || — JSONB 合并
+UPDATE user_configs SET config = config || '{"vip_level": 2}' WHERE user_id = 1;
+
+-- JSONB_SET — 设置路径值
+UPDATE user_configs SET config = JSONB_SET(config, '{notifications, email}', 'false'::JSONB)
+WHERE user_id = 1;
+
+-- JSONB_INSERT — 插入不覆盖 (PG 9.6+)
+SELECT JSONB_INSERT('{"a":1,"b":2}'::JSONB, '{c}', '3'::JSONB);
+
+-- JSONB_STRIP_NULLS — 移除 null
+SELECT JSONB_STRIP_NULLS('{"a":1,"b":null}'::JSONB);  -- {"a": 1}
+```
+
+## 构建函数
+
+```sql
+-- JSONB_BUILD_OBJECT / JSONB_BUILD_ARRAY
+SELECT JSONB_BUILD_OBJECT(
+    'id', 101, 'name', 'Alice',
+    'roles', JSONB_BUILD_ARRAY('admin', 'editor'),
+    'meta', JSONB_BUILD_OBJECT('last_login', NOW())
+);
+```
+
+## 展开函数
+
+```sql
+-- JSONB_EACH — 展开为 (key, value) 行集
+SELECT * FROM JSONB_EACH((SELECT config FROM user_configs WHERE user_id = 1));
+
+-- JSONB_EACH_TEXT — 展开为 (key, text_value)
+SELECT * FROM JSONB_EACH_TEXT((SELECT config FROM user_configs WHERE user_id = 1));
+
+-- JSONB_OBJECT_KEYS — 仅返回键
+SELECT * FROM JSONB_OBJECT_KEYS((SELECT config FROM user_configs WHERE user_id = 1));
+
+-- JSONB_EXTRACT_PATH — 提取路径
+SELECT JSONB_EXTRACT_PATH(config, 'preferences', 'language') FROM user_configs;
+```
+
+## 类型检查与格式化
+
+```sql
+-- JSONB_TYPEOF (PG 14+)
+SELECT JSONB_TYPEOF(config -> 'theme'),   -- string
+       JSONB_TYPEOF(config -> 'tags'),     -- array
+       JSONB_TYPEOF(config -> 'trust_score') -- number
+FROM user_configs WHERE user_id = 1;
+
+-- JSONB_PRETTY (PG 14+)
+SELECT JSONB_PRETTY(config) FROM user_configs WHERE user_id = 1;
+```
+
+## GIN 索引
+
+```sql
+-- 标准 GIN
+CREATE INDEX idx_config_gin ON user_configs USING GIN (config);
+
+-- jsonb_path_ops（更小更快，不支持 ? 操作符）
+CREATE INDEX idx_config_path ON user_configs USING GIN (config jsonb_path_ops);
+```
+
+## 完整示例表
+
+```sql
+CREATE TABLE user_configs (
+    id      BIGSERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    config  JSONB NOT NULL DEFAULT '{}'
+);
+
+INSERT INTO user_configs (user_id, config) VALUES
+(1, '{"theme":"dark","notifications":{"email":true},"preferences":{"language":"zh-CN","timezone":"Asia/Shanghai"},"tags":["developer","premium"],"trust_score":4.5}'),
+(2, '{"theme":"light","notifications":{"email":false},"preferences":{"language":"en","timezone":"America/New_York"},"tags":["basic"]}');
+```

skills/database-skills/postgresql/references/05-fulltext-search.md

@@ -0,0 +1,109 @@
+# 全文搜索详解
+
+## 基础概念
+
+PostgreSQL 全文搜索基于 **tsvector** (文本搜索向量) 和 **tsquery** (文本搜索查询)，配合 GIN 索引实现高效搜索。
+
+## 建表与索引
+
+```sql
+CREATE TABLE documents (
+    id          SERIAL PRIMARY KEY,
+    title       TEXT NOT NULL,
+    body        TEXT NOT NULL,
+    body_tsv    TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', body)) STORED
+);
+
+CREATE INDEX idx_documents_body_tsv ON documents USING GIN (body_tsv);
+
+INSERT INTO documents (title, body) VALUES
+    ('PostgreSQL Full Text Search',
+     'PostgreSQL provides full-text search capabilities out of the box.'),
+    ('Indexing Strategies',
+     'Proper indexing is crucial for database performance. GIN indexes are optimized for full-text search.'),
+    ('Database Performance Tuning',
+     'Performance tuning involves many aspects including query optimization, indexing strategy, and hardware configuration.');
+```
+
+## 核心函数
+
+```sql
+-- to_tsvector — 文本转搜索向量（停用词被移除, 动词被词根化）
+SELECT to_tsvector('english', 'The quick brown fox jumps over the lazy dog');
+-- 'brown':3 'dog':9 'fox':4 'jump':5 'lazi':8 'quick':2
+
+-- to_tsquery — 文本转搜索查询
+SELECT to_tsquery('english', 'search & indexing');
+-- 'search' & 'index'
+
+-- plainto_tsquery — 简单转换（空格分隔的单词自动加 &）
+SELECT plainto_tsquery('english', 'full text search');
+-- 'full' & 'text' & 'search'
+```
+
+## 匹配查询
+
+```sql
+-- @@ — 全文搜索匹配操作符
+SELECT id, title FROM documents
+WHERE body_tsv @@ to_tsquery('english', 'search & index');
+
+-- plainto_tsquery 简化写法
+SELECT id, title FROM documents
+WHERE body_tsv @@ plainto_tsquery('english', 'full text search');
+
+-- 直接对原始列搜索（不依赖 tsvector 列）
+SELECT id, title FROM documents
+WHERE to_tsvector('english', body) @@ to_tsquery('english', 'search');
+```
+
+## 排序与高亮
+
+```sql
+-- ts_rank / ts_rank_cd — 相关性排序
+SELECT id, title, ts_rank(body_tsv, query) AS rank
+FROM documents, to_tsquery('english', 'search & indexing') AS query
+WHERE body_tsv @@ query ORDER BY rank DESC;
+
+-- ts_headline — 高亮摘要
+SELECT id, ts_headline('english', body, query,
+    'StartSel=<mark>, StopSel=</mark>, MaxWords=30, MinWords=10') AS highlighted
+FROM documents, plainto_tsquery('english', 'full text search') AS query
+WHERE body_tsv @@ query;
+```
+
+## 短语搜索
+
+```sql
+-- <-> : 相邻单词
+SELECT * FROM documents
+WHERE body_tsv @@ to_tsquery('english', 'full <-> text <-> search');
+
+-- <N> : 相隔最多 N 个词
+SELECT * FROM documents
+WHERE body_tsv @@ to_tsquery('english', 'performance <2> tuning');
+-- 匹配 "performance tuning" 或 "performance and tuning"
+```
+
+## 中文全文搜索
+
+```sql
+-- 需要 zhparser 或 jieba 扩展
+-- CREATE EXTENSION zhparser;
+-- CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
+-- ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
+-- SELECT to_tsvector('chinese', '数据库性能优化技巧');
+```
+
+## 多语言与自定义配置
+
+```sql
+-- simple: 不做词干分析
+SELECT to_tsvector('simple', 'running runs ran');  -- 'running':1 'runs':2 'ran':3
+
+-- english: 词干分析
+SELECT to_tsvector('english', 'running runs ran');  -- 'run':1,2,3
+
+-- 创建自定义字典
+CREATE TEXT SEARCH DICTIONARY my_dict (TEMPLATE = pg_catalog.simple, ...);
+```

skills/database-skills/postgresql/references/06-index-types.md

@@ -0,0 +1,95 @@
+# 索引类型与视图详解
+
+## 6种索引类型
+
+| 索引类型 | 适用场景 | 操作符 | 典型用途 |
+|---------|---------|--------|---------|
+| **B-Tree** (默认) | 等值/范围查询 | =, <, <=, >, >=, BETWEEN, IN, IS NULL, LIKE ('abc%') | 主键、外键、排序字段 |
+| **Hash** | 等值查询 | = | 长随机值的等值比较 (有限用途) |
+| **GiST** | 几何/全文/范围 | &&, <@, @>, <<, >>, ~= | PostGIS、范围排除约束 |
+| **GIN** | 复合值索引 | @>, <@, ?, ?|, ?&, @@ | JSONB、数组、全文搜索 |
+| **BRIN** | 大表顺序相关数据 | =, <, <=, >, >=, BETWEEN | 时间序列、日志表 (节省 95%+ 空间) |
+| **SP-GiST** | 空间分区/聚类 | 同 GiST | 四叉树、k-d 树、前缀树 |
+
+## 索引创建
+
+```sql
+-- B-Tree
+CREATE INDEX idx_users_email ON users (email);
+CREATE INDEX idx_orders_created_at ON orders (created_at DESC);
+CREATE INDEX idx_orders_user_status ON orders (user_id, status);
+
+-- 复合索引列顺序: 等值在前，范围在后，选择性高的在前
+-- ✅ WHERE user_id = 1 AND status = 'paid'  → 索引 (user_id, status) 最优
+-- ❌ WHERE status = 'paid' AND created_at > '2024-01-01' → 索引 (created_at, status) 更好
+
+-- 部分索引（仅索引活跃用户，更小更快）
+CREATE INDEX idx_users_active ON users (email) WHERE is_active = TRUE;
+
+-- 覆盖索引 / INCLUDE (PG 11+, 避免回表)
+CREATE INDEX idx_orders_covering ON orders (user_id, status) INCLUDE (total_amount, created_at);
+
+-- Hash 索引
+CREATE INDEX idx_users_email_hash ON users USING HASH (email);
+
+-- GIN 索引
+CREATE INDEX idx_articles_body_tsv ON articles USING GIN (body_tsv);
+CREATE INDEX idx_config_gin ON user_configs USING GIN (config);
+CREATE INDEX idx_articles_tags_gin ON articles USING GIN (tags);
+CREATE INDEX idx_config_path ON user_configs USING GIN (config jsonb_path_ops);
+
+-- GiST 索引
+CREATE INDEX idx_room_bookings_period ON room_bookings USING GIST (period);
+
+-- BRIN 索引（大表时序数据，极大节省空间）
+CREATE INDEX idx_orders_brin ON orders USING BRIN (created_at) WITH (pages_per_range = 32);
+
+-- CONCURRENTLY — 在线建索引（不阻塞写）
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+## 索引维护
+
+```sql
+-- DROP INDEX CONCURRENTLY — 在线删除
+DROP INDEX CONCURRENTLY IF EXISTS idx_orders_old;
+
+-- REINDEX — 重建索引（索引膨胀时）
+REINDEX INDEX idx_orders_user_id;
+REINDEX TABLE orders;
+REINDEX DATABASE mydb;
+
+-- REINDEX CONCURRENTLY — 在线重建 (PG 12+)
+REINDEX INDEX CONCURRENTLY idx_orders_user_id;
+```
+
+## 视图 (View)
+
+```sql
+-- 普通视图 — 虚拟表
+CREATE VIEW user_order_summary AS
+SELECT u.id, u.username, COUNT(o.id) AS total_orders,
+       COALESCE(SUM(o.total_amount), 0) AS total_spent,
+       MAX(o.created_at) AS last_order_date
+FROM users u LEFT JOIN orders o ON o.user_id = u.id
+GROUP BY u.id, u.username;
+
+-- WITH CHECK OPTION — 确保更新满足视图条件
+CREATE VIEW paid_orders AS SELECT * FROM orders WHERE status = 'paid'
+WITH CHECK OPTION;
+
+-- 物化视图 — 物理存储的快照
+CREATE MATERIALIZED VIEW mv_monthly_sales AS
+SELECT DATE_TRUNC('month', o.created_at) AS month, p.category_id,
+       COUNT(DISTINCT o.id) AS order_count, SUM(oi.quantity * oi.price) AS revenue
+FROM orders o JOIN order_items oi ON oi.order_id = o.id
+JOIN products p ON p.id = oi.product_id
+GROUP BY month, p.category_id WITH DATA;
+
+-- 刷新物化视图
+REFRESH MATERIALIZED VIEW mv_monthly_sales;
+
+-- 并发刷新（需唯一索引, PG 9.4+）
+CREATE UNIQUE INDEX idx_mv_monthly_sales_unique ON mv_monthly_sales (month, category_id);
+REFRESH MATERIALIZED VIEW CONCURRENTLY mv_monthly_sales;
+```

skills/database-skills/postgresql/references/07-partition-fdw.md

@@ -0,0 +1,133 @@
+# 分区表与 FDW 详解
+
+## 分区表 (PG 10+)
+
+### RANGE 分区
+
+```sql
+CREATE TABLE orders_partitioned (
+    id BIGSERIAL, user_id INTEGER NOT NULL, total_amount NUMERIC(12,2),
+    status TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE orders_2024_01 PARTITION OF orders_partitioned
+    FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
+CREATE TABLE orders_2024_02 PARTITION OF orders_partitioned
+    FOR VALUES FROM ('2024-02-01') TO ('2024-03-01');
+
+-- 默认分区
+CREATE TABLE orders_default PARTITION OF orders_partitioned DEFAULT;
+```
+
+### LIST 分区
+
+```sql
+CREATE TABLE customers_partitioned (
+    id BIGSERIAL, name TEXT NOT NULL, region TEXT NOT NULL
+) PARTITION BY LIST (region);
+
+CREATE TABLE customers_asia PARTITION OF customers_partitioned
+    FOR VALUES IN ('CN', 'JP', 'KR', 'SG');
+CREATE TABLE customers_americas PARTITION OF customers_partitioned
+    FOR VALUES IN ('US', 'CA', 'BR', 'MX');
+```
+
+### HASH 分区
+
+```sql
+CREATE TABLE logs_partitioned (
+    id BIGSERIAL, level TEXT, message TEXT, logged_at TIMESTAMPTZ DEFAULT NOW()
+) PARTITION BY HASH (id);
+
+CREATE TABLE logs_p0 PARTITION OF logs_partitioned FOR VALUES WITH (MODULUS 4, REMAINDER 0);
+CREATE TABLE logs_p1 PARTITION OF logs_partitioned FOR VALUES WITH (MODULUS 4, REMAINDER 1);
+CREATE TABLE logs_p2 PARTITION OF logs_partitioned FOR VALUES WITH (MODULUS 4, REMAINDER 2);
+CREATE TABLE logs_p3 PARTITION OF logs_partitioned FOR VALUES WITH (MODULUS 4, REMAINDER 3);
+```
+
+### 子分区 (PG 11+)
+
+```sql
+CREATE TABLE sales (id BIGSERIAL, sale_date DATE NOT NULL, region TEXT NOT NULL, amount NUMERIC(12,2))
+PARTITION BY RANGE (sale_date);
+
+CREATE TABLE sales_2024_q1 PARTITION OF sales
+    FOR VALUES FROM ('2024-01-01') TO ('2024-04-01')
+    PARTITION BY LIST (region);
+```
+
+### 分区维护
+
+```sql
+-- 添加新分区
+CREATE TABLE orders_2024_04 PARTITION OF orders_partitioned
+    FOR VALUES FROM ('2024-04-01') TO ('2024-05-01');
+
+-- 分离分区（变成独立表）
+ALTER TABLE orders_partitioned DETACH PARTITION orders_2024_01;
+
+-- 附加分区
+ALTER TABLE orders_partitioned ATTACH PARTITION orders_2024_01
+    FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
+
+-- 分区裁剪自动生效
+EXPLAIN SELECT * FROM orders_partitioned
+WHERE created_at >= '2024-02-15' AND created_at < '2024-03-01';
+-- 只在 orders_2024_02 分区上扫描
+
+-- 分区表索引自动应用到所有分区
+CREATE INDEX ON orders_partitioned (user_id);
+CREATE INDEX ON orders_partitioned (created_at DESC);
+```
+
+### 分区最佳实践
+
+- 每个分区 1-10GB 为宜
+- 时间分区常用：日、周、月、季
+- 定期分离旧分区用于归档
+- 分区数不宜超过 1000
+- 分区键直接影响分区裁剪能力
+
+## FDW (Foreign Data Wrapper)
+
+### postgres_fdw — 跨 PG 数据库
+
+```sql
+CREATE EXTENSION postgres_fdw;
+
+CREATE SERVER remote_prod FOREIGN DATA WRAPPER postgres_fdw
+OPTIONS (host '192.168.1.100', port '5432', dbname 'prod_db');
+
+CREATE USER MAPPING FOR current_user SERVER remote_prod
+OPTIONS (user 'readonly_user', password 'secret');
+
+CREATE FOREIGN TABLE remote_orders (
+    id BIGINT, user_id INTEGER, total_amount NUMERIC(12,2), status TEXT, created_at TIMESTAMPTZ
+) SERVER remote_prod OPTIONS (schema_name 'public', table_name 'orders');
+
+-- 查询远程表
+SELECT * FROM remote_orders WHERE created_at > NOW() - INTERVAL '1 hour';
+
+-- 批量导入外部表结构
+IMPORT FOREIGN SCHEMA public FROM SERVER remote_prod INTO local_schema
+LIMIT TO (users, orders, products);
+```
+
+### file_fdw — 读取 CSV
+
+```sql
+CREATE EXTENSION file_fdw;
+CREATE SERVER file_server FOREIGN DATA WRAPPER file_fdw;
+
+CREATE FOREIGN TABLE csv_orders (
+    id BIGINT, user_id INTEGER, amount NUMERIC(10,2), order_date DATE
+) SERVER file_server OPTIONS (filename '/data/orders.csv', format 'csv', header 'true');
+
+SELECT SUM(amount) FROM csv_orders WHERE order_date >= '2024-01-01';
+```
+
+### FDW 性能考量
+
+- 适合小数据量或低频跨库查询
+- 大数据量传输建议用逻辑复制或 ETL
+- WHERE 条件尽量 push down 到远程

skills/database-skills/postgresql/references/08-replication-backup.md

@@ -0,0 +1,215 @@
+# 复制/备份/权限详解
+
+## 流复制 (Streaming Replication)
+
+### 主库配置
+
+```conf
+# postgresql.conf
+wal_level = replica
+max_wal_senders = 10
+wal_keep_size = 1GB
+hot_standby = on
+```
+
+```sql
+-- pg_hba.conf
+-- host replication replicator 192.168.1.0/24 md5
+
+CREATE USER replicator WITH REPLICATION LOGIN PASSWORD 'strong_password';
+```
+
+### 从库搭建
+
+```bash
+# 清空从库数据目录
+rm -rf /var/lib/postgresql/data/*
+
+# 从主库拉取基础备份
+pg_basebackup -h 192.168.1.100 -U replicator \
+    -D /var/lib/postgresql/data -P -v --wal-method=stream
+
+# PG 12+: 创建 standby.signal
+touch /var/lib/postgresql/data/standby.signal
+
+# 配置主库连接
+echo "primary_conninfo = 'host=192.168.1.100 port=5432 user=replicator password=strong_password'" \
+    >> /var/lib/postgresql/data/postgresql.auto.conf
+
+# 启动从库
+systemctl start postgresql
+
+# 检查复制状态（主库）
+SELECT * FROM pg_stat_replication;
+# 从库
+SELECT * FROM pg_stat_wal_receiver;
+```
+
+### 同步 vs 异步
+
+```sql
+-- 同步复制：主库等待从库确认
+-- 配置: synchronous_standby_names = 'FIRST 1 (slave1, slave2)'
+-- 数据零丢失，但写入延迟增加
+
+-- 检查同步状态
+SELECT application_name, state, sync_state, write_lag, flush_lag, replay_lag
+FROM pg_stat_replication;
+-- sync: 同步, async: 异步, potential: 候选同步
+```
+
+## 逻辑复制 (PG 10+)
+
+```sql
+-- 发布端
+CREATE PUBLICATION my_pub FOR ALL TABLES;
+CREATE PUBLICATION orders_pub FOR TABLE orders, order_items;
+CREATE PUBLICATION paid_orders_pub FOR TABLE orders WHERE (status = 'paid');  -- PG 15+
+
+-- 订阅端
+CREATE SUBSCRIPTION my_sub
+CONNECTION 'host=192.168.1.100 port=5432 dbname=mydb user=replicator password=strong_password'
+PUBLICATION my_pub;
+
+-- 管理
+ALTER SUBSCRIPTION my_sub ENABLE;
+ALTER SUBSCRIPTION my_sub DISABLE;
+ALTER SUBSCRIPTION my_sub REFRESH PUBLICATION;
+DROP SUBSCRIPTION my_sub;
+
+-- 监控
+SELECT * FROM pg_stat_subscription;
+```
+
+## 备份与恢复
+
+### pg_dump — 逻辑备份
+
+```bash
+# SQL 格式
+pg_dump -h localhost -U postgres -d mydb > mydb.sql
+
+# 自定义格式（推荐）
+pg_dump -h localhost -U postgres -d mydb -Fc -f mydb.dump
+
+# 并行导出目录格式
+pg_dump -h localhost -U postgres -d mydb -Fd -j 4 -f /backup/mydb/
+
+# 只导出结构
+pg_dump -h localhost -U postgres -d mydb -s -f mydb_schema.sql
+
+# 指定表
+pg_dump -h localhost -U postgres -d mydb -t orders -t users -f mydb_tables.sql
+
+# 全局对象（角色、表空间）
+pg_dumpall -h localhost -U postgres -g -f global_objects.sql
+```
+
+### pg_restore — 恢复
+
+```bash
+pg_restore -h localhost -U postgres -d mydb /backup/mydb.dump
+pg_restore -h localhost -U postgres -d mydb -j 4 /backup/mydb.dump  # 并行
+pg_restore -h localhost -U postgres -d mydb -t users /backup/mydb.dump  # 指定表
+
+# SQL 文件恢复
+psql -h localhost -U postgres -d mydb < mydb.sql
+```
+
+### WAL 归档与 PITR
+
+```conf
+# postgresql.conf
+archive_mode = on
+archive_command = 'cp %p /archive/%f'
+wal_keep_size = 1GB
+```
+
+```bash
+# 创建基础备份
+pg_basebackup -h localhost -U postgres -D /backup/base -P -v --wal-method=stream
+
+# PITR 恢复步骤:
+# 1. 停止 PG
+# 2. 用基础备份恢复数据目录
+# 3. 创建 recovery.signal (PG 12+)
+# 4. 配置 restore_command 和 recovery_target_time
+# 5. 启动 PG
+```
+
+### pg_basebackup — 物理备份
+
+```bash
+# 基础用法
+pg_basebackup -h localhost -U replicator -D /backup/pg_base -P -v --wal-method=stream
+
+# 压缩 tar 格式
+pg_basebackup -h localhost -U replicator -D /backup/pg_base -Ft -z -P -v
+
+# 验证备份 (PG 13+)
+pg_verifybackup /backup/pg_base
+```
+
+## 高可用工具
+
+```bash
+# Patroni (基于 etcd/consul/ZK)
+# 自动故障转移 + 自动恢复
+patroni /etc/patroni/patroni.yml
+
+# repmgr
+repmgr -f /etc/repmgr.conf primary register
+repmgr -f /etc/repmgr.conf standby clone
+repmgr -f /etc/repmgr.conf standby register
+repmgr -f /etc/repmgr.conf standby switchover
+
+# PgBouncer — 连接池
+# Pgpool-II — 连接池 + 读写分离 + 负载均衡
+```
+
+## 权限管理
+
+```sql
+-- ROLE 管理
+CREATE ROLE app_user WITH LOGIN PASSWORD 'password';
+CREATE ROLE readonly_role;
+CREATE ROLE readwrite_role;
+
+-- 角色层级
+GRANT readonly_role TO app_user;
+
+-- Schema 权限
+GRANT USAGE ON SCHEMA public TO readonly_role;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_role;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO readwrite_role;
+
+-- 默认权限（未来新建表自动授权）
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_role;
+
+-- 序列、函数
+GRANT USAGE, SELECT ON ALL SEQUENCES TO readwrite_role;
+GRANT EXECUTE ON ALL FUNCTIONS TO readwrite_role;
+
+-- RLS 行级安全（多租户隔离）
+CREATE TABLE tenant_orders (id BIGSERIAL PRIMARY KEY, tenant_id INTEGER NOT NULL, ...);
+ALTER TABLE tenant_orders ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON tenant_orders
+    USING (tenant_id = current_setting('app.tenant_id')::INTEGER);
+
+ALTER TABLE tenant_orders FORCE ROW LEVEL SECURITY;
+SET app.tenant_id = '1001';  -- 应用层设置
+```
+
+## 扩展
+
+```sql
+-- PostGIS: CREATE EXTENSION postgis;
+-- pgvector: CREATE EXTENSION vector;
+-- pg_stat_statements: CREATE EXTENSION pg_stat_statements;
+-- uuid-ossp: CREATE EXTENSION "uuid-ossp";
+-- pgcrypto: CREATE EXTENSION pgcrypto;
+-- citext: CREATE EXTENSION citext;
+-- pg_trgm: CREATE EXTENSION pg_trgm;
+-- unaccent: CREATE EXTENSION unaccent;
+```

skills/database-skills/redis/SKILL.md

@@ -1,28 +1,922 @@
 ---
 name: redis
-description: Provides comprehensive guidance for Redis including data structures, commands, pub/sub, persistence, clustering, and caching patterns. Use when the user asks about Redis, needs to use Redis for caching, implement Redis data structures, or work with Redis features.
+description: Provides comprehensive guidance for Redis including data structures (string/hash/list/set/zset/geo/hyperloglog/bitmap/stream), common commands with examples, caching patterns, persistence (RDB/AOF), replication & sentinel, cluster, Lua scripting, transactions, pub/sub, pipelining, security hardening, and production best practices. Use when the user asks about Redis, needs to implement caching, choose Redis data structures, configure persistence or cluster, or troubleshoot Redis performance.
 license: Complete terms in LICENSE.txt
 ---
 
-## When to use this skill
+# Redis — 内存数据结构存储系统
 
-Use this skill whenever the user wants to:
-- 使用 Redis 数据结构（string、hash、list、set、sorted set）与命令
-- 配置持久化（RDB/AOF）、主从、集群与客户端连接
-- 实现缓存、会话、限流、队列等模式
+Redis（Remote Dictionary Server）是一个开源的内存数据结构存储系统，用作数据库、缓存和消息代理。
 
-## How to use this skill
+## Workflow — 使用流程
 
-1. **命令**：GET/SET、HGETALL、LPUSH、SADD、ZRANGE；过期 TTL/EXPIRE；Lua 脚本。
-2. **CLI/驱动**：redis-cli；各语言驱动（连接池、序列化）；Redis Stack 扩展（搜索、JSON）。
-3. **环境**：单机、哨兵或集群；内存与持久化策略；生产注意密码与网络。
+```
+遇到 Redis 相关需求时，按以下顺序决策:
 
-## Best Practices
+Step 1: 明确场景
+├── 缓存加速?     → 转到 Step 2
+├── 数据结构存储? → 转到 Step 2
+├── 消息队列?     → 转到 1.7 Stream 章节
+├── 分布式锁?     → 转到 2.4 分布式锁
+├── 高可用/集群?  → 转到 4. 高可用架构
+└── 性能问题?     → 转到 6. 性能优化
 
-- 键命名规范与 TTL 避免堆积；大 key 拆分或压缩。
-- 持久化与主从按可用性需求选择；集群分片与扩容规划。
-- 监控内存与慢查询；安全加固与备份策略。
+Step 2: 选择数据结构
+├── 简单键值 / 计数器 / Session → String
+├── 对象存储 (多字段)           → Hash
+├── 队列 / 时间线 / 日志        → List
+├── 标签 / 社交关系 / 去重      → Set
+├── 排行榜 / 延时队列 / 范围查询 → ZSet
+├── 签到 / 在线状态 / 布隆过滤   → Bitmap
+├── UV 统计 / 去重计数          → HyperLogLog
+└── 附近的人 / 地理围栏         → Geo
+
+Step 3: 确定持久化策略
+├── 允许丢少量数据?      → RDB (默认配置)
+├── 高数据安全要求?      → AOF appendfsync everysec
+├── 最佳性价比?          → 混合持久化 (推荐)
+└── 纯缓存 (不持久化)?   → 关闭持久化
+
+Step 4: 部署架构
+├── 单机 (<16GB, 可容忍宕机)   → 单机 + AOF
+├── 主从 (读流量大)             → 主从复制
+├── 高可用 (自动故障转移)       → Sentinel (3节点)
+├── 水平扩展 (>单机内存)        → Cluster (6节点起)
+└── 读写分离 + 高可用          → Sentinel + 读写分离
+```
+
+## When to Use (and When NOT to)
+
+| ✅ Use When | ❌ Skip When |
+|------------|-------------|
+| 需要极低延迟（<1ms）的键值存取 | 需要复杂 SQL 关联查询和事务性报表 |
+| 热点数据缓存以减轻数据库压力 | 数据持久性要求超过内存可承受范围 |
+| 高并发计数器（INCR/DECR） | 需要完整的 ACID 事务保证（用关系型数据库） |
+| 排行榜/时间线/消息队列等数据结构场景 | 数据量远大于内存容量且不需要高速访问 |
+| 分布式锁/限流/会话管理 | 已经使用成熟的分布式缓存中间件且不迁移 |
+| 实时分析、地理位置搜索、UV 统计 | 需要数据之间强引用约束和外键 |
+
+**核心原则：Redis 是内存数据库，不是关系型数据库替代品。**
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 |
+|------------|--------------|---------|
+| 缓存加速、API 响应提速 | 强一致性要求场景（需配合 DB + 锁） | 代替关系型数据库作为唯一存储 |
+| 计数器、排行榜、时间线 | Redis 作为消息队列（Stream 替代 Pub/Sub） | 复杂 SQL 查询和 JOIN |
+| 分布式锁、限流、Session 存储 | 生产数据量 > 内存的场景（需 Cluster） | 存储大文件或二进制数据 |
+| 实时排行榜、地理空间查询 | 作为主数据库存储核心业务事务 | 需要外键约束和引用完整性 |
+| 去重统计（HyperLogLog/Bitmap） | 跨业务共享 Redis 实例（需 ACL 隔离） | 替代搜索引擎做全文搜索（用 RediSearch） |
+
+**超出范围时**：请使用 PostgreSQL（关系型数据）、MongoDB（文档型）、Elasticsearch（全文搜索）、RabbitMQ/Kafka（消息队列）。
+
+## When to trigger this skill
+
+**ALWAYS use this skill when the user mentions:**
+- "Redis", "缓存", "cache", "Session 存储", "分布式锁"
+- "String", "Hash", "List", "Set", "ZSet", "Sorted Set", "Geo", "HyperLogLog", "Stream"
+- "SET / GET / INCR /... (any Redis command)"
+- "RDB", "AOF", "持久化", "Persistence"
+- "主从", "Sentinel", "Cluster", "哨兵", "集群", "切片"
+- "redis.conf", "redis-cli", "redis-benchmark"
+- "Lua 脚本", "事务 / MULTI / EXEC", "Pipeline", "Pub/Sub"
+- "缓存穿透", "缓存雪崩", "缓存击穿", "Big Key", "Hot Key"
+- "Redis 性能优化", "慢查询", "内存淘汰"
+
+---
+
+## 1. Redis 核心数据结构与命令
+
+### 1.1 数据结构选型速查表
+
+| 数据结构 | 底层实现 | 最佳场景 | 复杂度 | 最大容量 |
+|---------|---------|---------|-------|---------|
+| **String** | SDS (Simple Dynamic String) | 缓存、计数器、Session、分布式锁 | O(1) | 512MB |
+| **Hash** | ziplist / dict | 对象存储（用户、文章）、字段更新 | O(n) n为字段数 | 4294967295 字段 |
+| **List** | quicklist | 消息队列、时间线、日志 | O(1) 头尾 | 4294967295 元素 |
+| **Set** | intset / dict | 标签、社交关系、去重 | O(1) 增删查 | 4294967295 成员 |
+| **ZSet** | ziplist / skiplist+dict | 排行榜、延时队列、范围查询 | O(log n) 跳表 | 4294967295 成员 |
+| **Bitmap** | String 位操作 | 签到/活跃用户统计、布隆过滤 | O(1) 位操作 | 512MB (2^32位) |
+| **HyperLogLog** | 概率数据结构 | UV 统计、去重计数 | O(1) | 12KB/键 (0.81%误差) |
+| **Geo** | ZSet 封装 | 附近的人、地理围栏 | O(log n) | 同 ZSet |
+| **Stream** | radix tree | 消息队列、事件溯源、消费组 | O(log n) | 4294967295 消息 |
+
+### 1.2 String 命令与示例
+
+```redis
+# 基础操作
+SET key "value"                    -- 设置值
+SET key "value" EX 60              -- 设置值 + 60s 过期
+SET key "value" NX                 -- 仅 key 不存在时设置 (分布式锁)
+GET key                            -- 获取值
+GETSET key "new"                   -- 设置新值返回旧值 (原子操作)
+STRLEN key                         -- 获取字符串长度
+APPEND key "suffix"                -- 追加
+
+# 数字操作 (Redis 内部数字存储为字符串)
+INCR counter                       -- 原子 +1 (自增)
+INCRBY counter 10                  -- 原子 +10
+DECR counter                       -- 原子 -1
+DECRBY counter 5                   -- 原子 -5
+INCRBYFLOAT price 1.5              -- 浮点数增加
+
+# 批量操作
+MSET k1 v1 k2 v2                   -- 批量设置 (非原子)
+MGET k1 k2                         -- 批量获取
+MSETNX k1 v1 k2 v2                 -- 仅当所有 key 都不存在时设置 (原子)
+
+# 子串操作
+GETRANGE key 0 -1                  -- 获取全部子串
+SETRANGE key 6 "Redis"             -- 从偏移 6 覆写
+
+# 带过期操作
+SETEX key 3600 "value"             -- 设置值 + 秒级过期
+PSETEX key 3000 "value"            -- 设置值 + 毫秒级过期
+```
+
+**String 编码选择**：值 ≤ 44 字节用 `embstr`（一次内存分配），> 44 字节用 `raw`（两次分配）。
+
+### 1.3 Hash 命令与示例
+
+```redis
+HSET user:1001 name "Alice" age 30     -- 设置多字段
+HGET user:1001 name                     -- 获取单字段
+HMGET user:1001 name age                -- 获取多字段
+HGETALL user:1001                       -- 获取所有字段 (慎用，大 key 场景阻塞)
+HKEYS user:1001                         -- 获取所有字段名
+HVALS user:1001                         -- 获取所有字段值
+HDEL user:1001 age                      -- 删除字段
+HEXISTS user:1001 name                  -- 检查字段是否存在
+HLEN user:1001                          -- 字段数量
+HINCRBY user:1001 score 10              -- 字段数值增加
+HSETNX user:1001 email "a@b.com"        -- 仅字段不存在时设置
+```
+
+**Hash 编码选择**：字段数 < 512 且每个值长度 < 64 字节使用 `ziplist`（节省内存），否则升级为 `dict`（哈希表）。可配置 `hash-max-ziplist-entries` 和 `hash-max-ziplist-value`。
+
+### 1.4 List 命令与示例
+
+```redis
+# 右进左出 (队列模式 - FIFO)
+RPUSH queue "job1" "job2"              -- 右边推入一个或多个
+LPOP queue                             -- 左边弹出
+
+# 左进右出 (栈模式 - LIFO)
+LPUSH stack "a" "b"                    -- 左边推入
+RPOP stack                             -- 右边弹出
+
+# 范围操作
+LRANGE list 0 -1                       -- 获取全部元素
+LINDEX list 0                          -- 获取指定索引元素
+LLEN list                              -- 列表长度
+LTRIM list 0 99                        -- 修剪保留前 100 个
+LREM list 2 "value"                    -- 移除 2 个匹配的值
+LSET list 0 "new"                      -- 设置指定索引的值
+LINSERT list BEFORE "b" "a"            -- 在元素前插入
+
+# 阻塞操作 (超时秒数，0 表示无限等待)
+BLPOP queue 5                          -- 阻塞式左弹出，超时 5s
+BRPOP queue 5                          -- 阻塞式右弹出
+```
+
+**List 编码选择**：元素数量或单个元素长度超阈值后从 `quicklist` 模式（ziplist 节点链表）转为 linkedlist。
+
+**典型场景**：
+- `LPUSH + LTRIM` = 固定长度最新消息列表
+- `RPUSH + BLPOP` = 可靠消息队列
+- `BRPOPLPUSH` = 安全队列（备份到 backup list）
+
+### 1.5 Set 命令与示例
+
+```redis
+SADD tags "redis" "database"          -- 添加成员
+SREM tags "database"                   -- 移除成员
+SMEMBERS tags                          -- 获取所有成员 (慎用于大 set)
+SISMEMBER tags "redis"                 -- 判断成员 O(1)
+SCARD tags                             -- 成员数量
+
+# 集合运算 (支持集合间操作)
+SINTER set1 set2                       -- 交集
+SUNION set1 set2                       -- 并集
+SDIFF set1 set2                        -- 差集
+SINTERSTORE dest s1 s2                 -- 交集存到新 key
+SUNIONSTORE dest s1 s2                 -- 并集存到新 key
+SDIFFSTORE dest s1 s2                  -- 差集存到新 key
+
+# 随机操作
+SRANDMEMBER key 3                      -- 随机返回 3 个成员 (不删除)
+SPOP key 2                             -- 随机弹出 2 个成员 (删除)
+
+SSCAN key 0 COUNT 100                  -- 渐进迭代 (避免阻塞)
+```
+
+### 1.6 ZSet (Sorted Set) 命令与示例
+
+```redis
+ZADD leaderboard 100 "player1" 200 "player2"  -- 添加成员及分数
+ZREM leaderboard "player1"                    -- 移除成员
+ZSCORE leaderboard "player1"                  -- 获取分数
+ZCARD leaderboard                             -- 成员数量
+ZINCRBY leaderboard 50 "player1"              -- 增加分数
+
+# 按排名查
+ZRANGE leaderboard 0 -1 WITHSCORES            -- 按分数从小到大 (加分差)
+ZREVRANGE leaderboard 0 -1 WITHSCORES         -- 按分数从大到小 (排行榜)
+ZRANK leaderboard "player1"                   -- 获取排名 (从小到大)
+ZREVRANK leaderboard "player1"                -- 获取排名 (从大到小)
+
+# 按分数范围查
+ZRANGEBYSCORE salary 2000 5000                -- 按分数范围查询
+ZREVRANGEBYSCORE salary 5000 2000             -- 按分数范围逆序
+ZCOUNT salary 2000 5000                       -- 统计分数区间数
+ZREMRANGEBYSCORE salary 0 1000                -- 移除分数区间成员
+
+# 按字典序范围查
+ZRANGEBYLEX words [a [z                      -- 字典序范围查询
+ZLEXCOUNT words [a [z                        -- 统计字典序区间数
+ZREMRANGEBYLEX words [a [z                   -- 移除字典序区间成员
+
+# 集合运算
+ZINTERSTORE dest 2 z1 z2                     -- 交集
+ZUNIONSTORE dest 2 z1 z2                     -- 并集
+
+ZSCAN leaderboard 0 COUNT 100                -- 渐进迭代
+```
+
+**ZSet 编码选择**：成员数 < 128 且所有值长度 < 64 字节时用 `ziplist`，否则用 `skiplist + dict`。
+
+### 1.7 高级数据结构
+
+```redis
+# Bitmap — 位图
+SETBIT sign:2024-01 100 1                    -- 用户 100 在 1月签到
+GETBIT sign:2024-01 100                      -- 查询签到状态
+BITCOUNT sign:2024-01                        -- 统计签到人数
+BITOP AND dest sign:01 sign:02               -- 位运算 (AND/OR/NOT/XOR)
+
+# HyperLogLog — 基数统计 (0.81% 误差)
+PFADD visits:2024-01 "user1" "user2"         -- 添加元素
+PFCOUNT visits:2024-01                       -- 近似去重计数
+PFMERGE total visits:01 visits:02            -- 合并
+
+# Geo — 地理位置
+GEOADD cities 116.397 39.908 "北京"           -- 添加地标
+GEODIST cities "北京" "上海" km               -- 计算两地距离
+GEORADIUS cities 116.4 39.9 100 km           -- 查找 100km 内的位置
+GEORADIUSBYMEMBER cities "北京" 500 km        -- 以成员为中心查找
+GEOHASH cities "北京"                         -- 返回 geohash 字符串
+GEOPOS cities "北京"                          -- 返回经纬度
+
+# Stream — 消息流 (Redis 5.0+)
+XADD mystream * sensor-id 1234 temp 19.8     -- 追加消息 (自动时间戳ID)
+XLEN mystream                                 -- 消息长度
+XRANGE mystream - +                           -- 范围查询
+XREAD COUNT 10 STREAMS mystream 0            -- 读取消息
+XGROUP CREATE mystream mygroup $              -- 创建消费组
+XREADGROUP GROUP mygroup consumer1 COUNT 1 STREAMS mystream >  -- 消费
+XACK mystream mygroup 1648123456789-0        -- 确认消息
+```
+
+---
+
+## 2. 缓存模式与架构
+
+### 2.1 缓存读取模式
+
+```
+Read-Through: 应用 → Redis → 数据库
+               命中 ✓ 返回    未命中 ✗ 回源
+```
+
+```redis
+# Cache-Aside (旁路缓存) — 最常用模式
+GET cache_key        → 命中返回
+                      → 未命中: 查 DB → SET cache_key value EX 3600 → 返回
+
+# 伪代码
+function get_user(user_id):
+    user = redis.get("user:" + user_id)
+    if user is None:
+        user = db.query("SELECT * FROM users WHERE id=?", user_id)
+        redis.setex("user:" + user_id, 3600, user)
+    return user
+```
+
+### 2.2 缓存更新模式
+
+| 模式 | 操作方法 | 并发安全 | 说明 |
+|------|---------|---------|------|
+| **Cache-Aside** | 更新 DB → 删除缓存 | ⚠️ 删除失败有脏数据 | 最通用，使用最广泛 |
+| **Write-Through** | 更新 DB → 同步更新缓存 | ✅ 一致性高 | 写延迟增加，适合写少读多 |
+| **Write-Behind** | 先写缓存 → 异步写 DB | ⚠️ 宕机可能丢数据 | 性能最佳，适合允许略丢数据的场景 |
+| **Refresh-Ahead** | 缓存过期前自动刷新 | ✅ 无过期风暴 | 适合热点 key |
+
+### 2.3 缓存三大问题
+
+```
+缓存穿透 (Cache Penetration)
+├── 问题：查询一个不存在的数据，每次穿透到 DB
+├── 后果：大量请求直接打到数据库，可能击垮 DB
+├── 解决：
+│   ├── ① 布隆过滤器 (Bloom Filter): 用 Bitmap 预判 key 是否存在
+│   ├── ② 缓存空值: SET key "" EX 60 (短过期时间)
+│   └── ③ 参数校验: 非法参数直接拒绝
+└── 提示：推荐组合使用 ① + ②
+
+缓存击穿 (Cache Breakdown / Hot Key)
+├── 问题：热点 key 过期瞬间，高并发直接打到 DB
+├── 后果：瞬间高并发，DB 扛不住
+├── 解决：
+│   ├── ① 互斥锁 (Mutex Lock): SETNX 争锁，只有一个线程回源
+│   ├── ② 永不过期 + 异步刷新: 物理上不设 TTL，后台线程定时更新
+│   └── ③ 热点 key 预留: 预估热点，预加载
+└── 提示：互斥锁实现最简单，异步刷新性能最优
+
+缓存雪崩 (Cache Avalanche)
+├── 问题：大量缓存同时过期/Redis 宕机，流量直击 DB
+├── 后果：DB 被击垮，服务雪崩
+├── 解决：
+│   ├── ① TTL 随机化: SET key EX (300 + random(0,60))
+│   ├── ② 互斥锁: 同击穿方案
+│   ├── ③ 双缓存: 主缓存 + 备份缓存
+│   ├── ④ Redis 高可用: 主从 + Sentinel/Cluster
+│   └── ⑤ 本地缓存 + Redis: 二级缓存 (guava/caffeine)
+└── 提示：TTL 随机化是最低成本最高收益的预防措施
+```
+
+### 2.4 分布式锁
+
+```redis
+# 最简单的分布式锁 (单 Redis 实例)
+SET lock:resource "uuid-value" NX EX 30       -- 加锁
+-- 执行业务逻辑...
+DEL lock:resource                                -- 释放锁
+
+# 问题：误删其他线程的锁 → 需要 Lua 脚本保证原子性
+
+# 正确的解锁 (Lua 脚本)
+-- EVAL "if redis.call('get',KEYS[1])==ARGV[1] then return redis.call('del',KEYS[1]) else return 0 end" 1 lock:resource uuid-value
+
+# Redlock 算法 (多实例场景)
+# 1. 获取当前时间 T1
+# 2. 向 N/2+1 个实例尝试加锁 (SET NX PX)
+# 3. 用去时间 > 锁有效时间 → 加锁失败，向所有实例发送解锁
+# 4. 使用 Redisson / Redlock-py 等客户端实现
+
+# 最佳实践：使用 Redisson 等成熟客户端，不要自行实现
+```
+
+### 2.5 常见缓存 Key 设计规范
+
+```
+# 命名规范
+cache:user:{id}           -- 用户缓存
+cache:article:{id}        -- 文章缓存
+lock:order:{order_id}     -- 分布式锁
+rate:limit:ip:{ip}        -- 限流
+session:{session_id}      -- Session
+
+# 过期时间策略
+- 通用原则: TTL = 业务可接受的脏数据时间 + random(0, TTL*1/5)
+- 静态数据 (配置表): 1-24 小时
+- 动态数据 (用户信息): 5-30 分钟
+- 热点数据 (首页推荐): 1-5 分钟 + 异步刷新
+
+# Big Key 应对
+Big Key 指单个 key 存大量数据 (Hash 上百万字段 / List 千万级元素)
+├── 问题：阻塞其他命令、内存不均、慢查询
+├── 发现：redis-cli --bigkeys 扫描
+├── 拆分：Hash → HASH_KEY:{mod(hash_field, 100)}
+└── 替代：List → 改用 Stream + 消费组
+```
+
+---
+
+## 3. 持久化
+
+### 3.1 RDB (Redis Database) — 快照持久化
+
+```
+原理：定时将内存数据生成快照写入磁盘 (dump.rdb)
+```
+
+| 配置 | 说明 | 触发条件 |
+|------|------|---------|
+| `save 900 1` | 900s 内 ≥1 次写 | 自动 |
+| `save 300 10` | 300s 内 ≥10 次写 | 自动 |
+| `save 60 10000` | 60s 内 ≥10000 次写 | 自动 |
+| `BGSAVE` | 后台 fork 子进程生成快照 | 手动 |
+| `SAVE` | 主进程生成 (阻塞所有请求) | 手动 |
+
+```
+RDB 优势：文件紧凑，恢复快，适合备份和灾难恢复
+RDB 劣势：可能丢失最后一次快照后的数据 (最长丢失一个 save 间隔)
+```
+
+### 3.2 AOF (Append Only File) — 日志持久化
+
+```
+原理：记录每次写操作命令，Redis 重启时回放
+```
+
+| `appendfsync` 选项 | 持久化策略 | 数据安全 | 性能影响 |
+|-------------------|-----------|---------|---------|
+| `always` | 每条命令 fsync | 最多丢 1 条 | 极低 (频繁磁盘写入) |
+| `everysec` | 每秒 fsync | 最多丢 1s 数据 | 低 (推荐) |
+| `no` | 操作系统决定 | 不可预测 | 高 |
+
+**AOF 重写**：`BGREWRITEAOF` — 压缩 AOF 文件（将多个命令合并为最小集合）。
+配置 `auto-aof-rewrite-percentage 100` 和 `auto-aof-rewrite-min-size 64mb` 自动触发。
+
+```
+AOF 优势：数据安全性高 (最多丢 1 秒数据)，文件易读
+AOF 劣势：文件体积比 RDB 大，恢复比 RDB 慢
+```
+
+### 3.3 最佳选择：RDB + AOF 混合
+
+Redis 4.0+ 支持混合持久化 (`aof-use-rdb-preamble yes`)：
+- AOF 重写时先生成 RDB 快照写入 AOF 文件头部
+- 后续增量写命令以 AOF 格式追加
+- 重启恢复：先加载 RDB（快），再回放 AOF 增量（补全）
+
+```
+推荐生产配置：
+┌─────────────────────────────────────────────┐
+│ appendonly yes                              │
+│ appendfsync everysec                        │
+│ aof-use-rdb-preamble yes                    │
+│ save 900 1                                  │
+│ save 300 10                                 │
+│ save 60 10000                               │
+└─────────────────────────────────────────────┘
+```
+
+### 3.4 持久化对比总结
+
+| 维度 | RDB | AOF | 混合 (RDB+AOF) |
+|------|-----|-----|----------------|
+| 数据完整性 | 可能丢失多 | 最多丢 1s | 最多丢 1s |
+| 恢复速度 | 快 | 慢 | 快 |
+| 文件大小 | 小 | 大 (可重写) | 中 |
+| 实时性影响 | fork 开销 (内存翻倍) | 磁盘 I/O (可控) | 组合开销 |
+
+---
+
+## 4. 高可用架构
+
+### 4.1 主从复制 (Replication)
+
+```
+┌─────────┐     复制流      ┌──────────┐
+│ Master  │ ──────────────→ │ Replica  │
+│ (写+读)  │                 │ (只读)   │
+└─────────┘                 └──────────┘
+```
+
+**复制流程**：
+```
+1. Replica 发送 SLAVEOF master_ip master_port
+2. Master BGSAVE 生成 RDB → 发送到 Replica
+3. Replica 加载 RDB + 缓存增量命令
+4. 后续持续增量复制 (基于环形缓冲区 repl_backlog)
+5. 网络断开重连 → 部分重同步 (PSYNC2)
+```
+
+**核心配置**：
+```conf
+# master
+replica-read-only no                     # Master 默认不设置只读
+
+# replica
+replicaof 192.168.1.100 6379             # 指定主节点
+replica-read-only yes                    # 从节点只读
+replica-priority 100                     # Sentinel 选主优先级 (越小越高)
+```
+
+**复制注意事项**：
+- 主节点 fork 子进程执行 BGSAVE 时不阻塞读写（但 COW 机制会使内存翻倍）
+- 从节点默认只读，可用于读流量分流
+- 主节点崩溃后需手动切换从节点或使用 Sentinel
+
+### 4.2 Sentinel (哨兵) — 自动故障转移
+
+```
+          ┌─────────────┐
+          │  Sentinel-1  │
+          └──────┬──────┘
+                 │ 监控 + 协调
+    ┌────────────┼────────────┐
+    │            │            │
+┌───▼───┐  ┌────▼────┐  ┌───▼───┐
+│Master  │  │Replica-1│  │Replica-2│
+└───────┘  └─────────┘  └─────────┘
+```
+
+**Sentinel 核心功能**：
+```
+1. 监控：PING 主从节点，判断是否下线
+2. 通知：管理员或程序通过 API 获取状态变化
+3. 故障转移：Master 挂了 → 选举新 Master
+4. 配置提供：客户端请求获取当前 Master 地址
+```
+
+**部署要求**：最少 3 个 Sentinel 实例（奇数，保证 quorum）。
+
+**sentinel.conf 配置**：
+```conf
+sentinel monitor mymaster 127.0.0.1 6379 2    # 监控主节点，2 个哨兵同意即判定下线
+sentinel down-after-milliseconds mymaster 5000 # 5s 无响应判主观下线
+sentinel failover-timeout mymaster 60000       # 故障转移超时
+sentinel parallel-syncs mymaster 1             # 新主后同时多少个从同步
+```
+
+### 4.3 Cluster (集群) — 数据分片 + 高可用
+
+```
+        ┌──────────┐
+        │  客户端   │
+        └────┬─────┘
+             │ 请求任意节点，MOVED 重定向
+    ┌────────┼──────────────┐
+    │        │              │
+┌───▼───┐ ┌──▼───┐    ┌───▼───┐
+│Node 1  │ │Node 2 │... │Node N  │
+│ 0-5460 │ │5461-10922 │  │10923-16383│
+│+Slave  │ │+Slave │  │+Slave  │
+└────────┘ └───────┘    └───────┘
+```
+
+**核心概念**：
+- 16384 个 hash slot：`CRC16(key) % 16384`
+- 每个节点负责一段 slot 区间
+- 节点间 gossip 协议通信（PONG/PING）
+- 自动主从切换：主节点挂了，从节点晋升
+
+**集群搭建要点**：
+```bash
+# 配置文件：(每个节点必须有集群模式)
+cluster-enabled yes
+cluster-config-file nodes-6379.conf
+cluster-node-timeout 5000
+
+# 创建集群 (Redis 5+)
+redis-cli --cluster create 192.168.1.100:6379 192.168.1.101:6379 \
+  192.168.1.102:6379 192.168.1.103:6379 192.168.1.104:6379 192.168.1.105:6379 \
+  --cluster-replicas 1
+
+# 常用操作
+redis-cli --cluster check 192.168.1.100:6379    # 检查集群状态
+redis-cli --cluster info 192.168.1.100:6379     # 集群信息
+redis-cli --cluster rebalance 192.168.1.100:6379 # 重新平衡 slot
+redis-cli --cluster add-node 新节点ip:port 已有节点ip:port --cluster-slave
+```
+
+**集群限制**：
+- 只支持 0 号数据库（SELECT 0）
+- 批量操作（MGET/MSET）的 key 必须在同一 slot（使用 hash tag `{user:1001}`）
+- 事务/Lua 脚本的 key 必须在同一节点（同一 slot）
+- 不支持多 key 操作在跨 slot 场景
+
+### 4.4 架构选型决策树
+
+```
+数据量 < 单个节点内存 (≤16GB) ?
+├── YES → 是否需要自动故障转移?
+│         ├── NO  → 单机 + RDB/AOF
+│         └── YES → 读写分离需要?
+│                   ├── NO  → 主从 + Sentinel (3实例)
+│                   └── YES → 主从 + Sentinel (读写分离)
+│
+└── NO → 数据量预期增长?
+         ├── NO  → 升级单机内存 (垂直扩展)
+         └── YES → Cluster 集群 (水平扩展)
+                   ├── 三主三从 (最小生产配置)
+                   ├── 六主六从 (中等规模)
+                   └── 九主九从 (大规模)
+```
+
+---
+
+## 5. Lua 脚本与事务
+
+### 5.1 事务 (Transaction)
+
+```redis
+MULTI                              -- 开始事务
+SET key1 "value1"                  -- 命令入队 (QUEUED)
+SET key2 "value2"                  -- 命令入队
+EXEC                               -- 按顺序执行所有命令
+
+# WATCH — 乐观锁 (CAS 模式)
+WATCH stock:100                    -- 监视 key
+count = GET stock:100              -- 读取当前值
+MULTI
+SET stock:100 (count - 1)          -- 如果期间 stock:100 被修改 → EXEC 返回 nil
+EXEC
+UNWATCH                            -- 取消监视
+```
+
+**事务 vs Pipeline 对比**：
+
+| 特性 | MULTI/EXEC (事务) | Pipeline (管道) |
+|------|------------------|----------------|
+| 原子性 | ✅ 全部/全部不执行 | ❌ 不保证 |
+| 阻塞等待结果 | ✅ 是 | ✅ 是 |
+| 中间可读结果 | ❌ 仅入队不可读 | ✅ 可读 |
+| 错误处理 | 语法错全部失败/运行时错其他继续 | 每命令独立 |
+| 适用场景 | 需要 "all or nothing" | 批量操作提升性能 |
+
+### 5.2 Lua 脚本
+
+Redis 2.6+ 内置 Lua 5.1 解释器，脚本在服务器端原子执行。
+
+```lua
+-- 原子扣减库存脚本
+-- EVAL script 1 key arg
+-- KEYS[1] = stock:100
+-- ARGV[1] = 1 (扣减数量)
+
+local stock = redis.call("GET", KEYS[1])
+if not stock or tonumber(stock) < tonumber(ARGV[1]) then
+    return -1  -- 库存不足
+end
+redis.call("DECRBY", KEYS[1], ARGV[1])
+return redis.call("GET", KEYS[1])
+
+-- 调用方式: EVAL "上述脚本" 1 stock:100 1
+-- 缓存: SCRIPT LOAD "script" → SHA → EVALSHA SHA 1 stock:100 1
+```
+
+**Lua 脚本最佳实践**：
+- 脚本应短小精悍（控制在 100 行内），长脚本会阻塞其他请求
+- 使用 `SCRIPT LOAD` + `EVALSHA` 减少网络传输
+- 脚本中所有 key 必须使用 KEYS 数组传入，不能用硬编码
+- 脚本不要访问不同节点的 key（Cluster 场景）
+- 使用 `redis.log(redis.LOG_WARNING, msg)` 调试
+
+### 5.3 CAS (乐观锁) 模式
+
+```lua
+-- 更安全的库存扣减：数值检查 + 原子操作
+local key = KEYS[1]
+local expected = tonumber(ARGV[1])
+local new_value = tonumber(ARGV[2])
+
+local current = redis.call("GET", key)
+if tonumber(current) ~= expected then
+    return -1  -- 已被其他客户端修改
+end
+return redis.call("SET", key, new_value)
+```
+
+---
+
+## 6. 性能优化与运维
+
+### 6.1 内存淘汰策略 (maxmemory-policy)
+
+| 策略 | 说明 | 适用场景 |
+|------|------|---------|
+| `noeviction` | 不淘汰，写操作返回错误 | 数据库模式 (禁止丢数据) |
+| `allkeys-lru` | 全 key 最近最少使用 | 通用缓存 (推荐) |
+| `allkeys-lfu` | 全 key 最不经常使用 (Redis 4.0+) | 访问频率差异大的缓存 |
+| `volatile-lru` | 有过期时间的 key LRU | 部分持久化、部分缓存 |
+| `volatile-ttl` | 淘汰 TTL 最短的 key | 特定场景 |
+| `volatile-random` | 随机淘汰有过期时间的 key | 不太推荐 |
+
+```bash
+redis-cli CONFIG SET maxmemory 4gb           # 设置最大内存
+redis-cli CONFIG SET maxmemory-policy allkeys-lru  # LRU 淘汰
+```
+
+### 6.2 Big Key 与 Hot Key
+
+**Big Key 检测**：
+```bash
+# 扫描大 key (阻塞，建议低峰期执行)
+redis-cli --bigkeys
+
+# 用 MEMORY USAGE 精确查看内存占用
+redis-cli MEMORY USAGE mykey
+
+# 用 DEBUG 命令 (Redis 4.0+)
+redis-cli MEMORY DOCTOR
+```
+
+**Big Key 拆分策略**：
+```
+场景 1: Hash 包含上百万字段
+→ 拆分: HASH_KEY:{hash(field) % 100} = {field: value}
+
+场景 2: List 包含千万级元素
+→ 替换为 Stream (支持消费组)
+
+场景 3: ZSet 大排行榜
+→ 分桶: ranking:2024-01, ranking:2024-02...
+
+场景 4: String 存储大 JSON (>10MB)
+→ 压缩存储: Snappy/LZ4 压缩后存，读取解压
+```
+
+**Hot Key 应对**：
+```
+问题：单个 key QPS 极高 (如 10万+/秒)
+解决：
+├── 本地缓存 (Local Cache): 二级缓存 (如 Caffeine)
+├── 读写分离: 从节点分担读流量
+├── 热点拆分: hotkey:{random(0,10)} = value (分片读取)
+└── 代理层: Redis Proxy (如 Twemproxy/RedisShake)
+```
+
+### 6.3 慢查询日志
+
+```bash
+CONFIG SET slowlog-log-slower-than 10000     # 记录 >10ms 的命令
+CONFIG SET slowlog-max-len 128               # 最多保留 128 条记录
+
+SLOWLOG GET 10                               # 获取前 10 条慢查询
+SLOWLOG LEN                                  # 慢查询总数
+SLOWLOG RESET                                # 清空慢查询
+```
+
+### 6.4 性能基准与优化
+
+```bash
+# 基准测试
+redis-benchmark -h 127.0.0.1 -p 6379 -c 50 -n 100000 -q
+redis-benchmark -t set,get,incr,lpush -q    # 指定命令测试
+redis-benchmark -P 10 -q                     # Pipeline 模式
+
+# 预期性能 (单实例):
+# GET/SET: 10万+ QPS (无持久化)
+# Pipeline 100条: 100万+ QPS
+# Lua 脚本: 5-15万 次/秒
+```
+
+**关键优化参数**：
+```conf
+tcp-backlog 511                           # TCP 连接队列
+timeout 300                               # 客户端空闲超时
+tcp-keepalive 300                         # TCP keepalive
+lfu-log-factor 10                         # LFU 计数器对数因子 (Redis 4.0+)
+lfu-decay-time 1                          # LFU 衰减时间
+hz 10                                     # 后台任务频率 (可增加到 100)
+```
+
+### 6.5 安全加固
+
+```bash
+# 基础安全
+requirepass your_strong_password           # 设置密码
+RENAME_COMMAND FLUSHALL ""                 # 禁用危险命令
+RENAME_COMMAND FLUSHDB ""
+RENAME_COMMAND CONFIG ""
+RENAME_COMMAND SHUTDOWN ""
+
+# 网络安全
+bind 127.0.0.1 192.168.1.100              # 绑定内网 IP
+protected-mode yes                         # 保护模式
+port 6379                                  # 修改默认端口
+
+# 连接限制
+maxclients 10000                           # 最大连接数
+client-output-buffer-limit normal 0 0 0    # 客户端输出缓冲区限制
+client-output-buffer-limit replica 256mb 64mb 60
+client-output-buffer-limit pubsub 32mb 8mb 60
+
+# ACL (Redis 6.0+)
+ACL SETUSER alice on >password ~cached:* +get +set -admin
+ACL SETUSER bob on >password ~* +@all -@dangerous
+```
+
+---
+
+## 7. Redis 生态与客户端连接
+
+### 7.1 客户端配置
+
+```java
+// Java (Jedis 连接池)
+JedisPoolConfig config = new JedisPoolConfig();
+config.setMaxTotal(100);           // 最大连接数
+config.setMaxIdle(50);             // 最大空闲
+config.setMinIdle(10);             // 最小空闲
+config.setTestOnBorrow(true);      // 获取时校验
+config.setTestOnReturn(true);      // 返回时校验
+config.setMaxWaitMillis(3000);     // 获取连接超时
+
+// Java (Lettuce — 推荐，支持异步/响应式)
+RedisClient client = RedisClient.create("redis://password@host:6379/0");
+StatefulRedisConnection<String, String> conn = client.connect();
+RedisCommands<String, String> sync = conn.sync();
+RedisAsyncCommands<String, String> async = conn.async();
+```
+
+### 7.2 常用 Redis 监控命令
+
+```bash
+# 实时监控
+redis-cli -a password MONITOR          # 实时打印所有命令 (生产慎用)
+redis-cli -a password INFO             # 全面状态信息
+redis-cli -a password INFO STATS       # 统计信息
+redis-cli -a password INFO MEMORY      # 内存信息
+redis-cli -a password INFO CLIENTS     # 客户端信息
+
+# 连接数监控
+redis-cli CLIENT LIST | wc -l          # 当前连接数
+redis-cli INFO connected_clients       # 连接数
+
+# 内存监控
+redis-cli INFO used_memory_human       # 已用内存
+redis-cli INFO used_memory_peak_human  # 峰值内存
+redis-cli INFO mem_fragmentation_ratio # 内存碎片率 (>1.5 需重启)
+```
+
+### 7.3 Redis Stack 扩展
+
+Redis Stack (Redis 6.2+) 集成了以下模块：
+- **RediSearch**：全文搜索、索引、向量搜索
+- **RedisJSON**：原生 JSON 数据类型支持
+- **RedisTimeSeries**：时间序列数据类型
+- **RedisBloom**：布隆过滤器、Cuckoo Filter
+
+---
+
+## Gotchas — 常见陷阱与反模式 (Common Gotchas & Anti-Patterns)
+
+| # | 问题 | 风险 | 解决方案 |
+|---|------|------|---------|
+
+| # | 反模式 | 问题 | 正确做法 |
+|---|--------|------|---------|
+| 1 | 用 KEYS 在生产环境搜索 | O(n) 扫描全库，阻塞 Redis 数秒 | 用 SCAN 游标迭代 |
+| 2 | 大集合上用 SMEMBERS/HGETALL | 百万级元素 JSON 序列化，内存爆炸 | 用 SSCAN/HSCAN 分批或拆分 key |
+| 3 | 不使用连接池 | 每个请求创建连接，耗尽系统资源 | 使用 JedisPool/Lettuce 连接池 |
+| 4 | 所有 key 不设过期时间 | 内存无限增长，触达 maxmemory | 根据场景设置合适的 TTL |
+| 5 | 单机当数据库永久存储 | 无高可用，宕机丢失数据 | 主从+Sentinel 或 Cluster |
+| 6 | 使用 SELECT 切分数据库 | 不便于管理监控，Cluster 不支持 | 用不同 key 前缀或不同 Redis 实例 |
+| 7 | 生成超长 key 名 | 浪费内存 (key 本身也是存储) | key 名控制在合理长度 (32-64 字符) |
+| 8 | 用 Redis 存大文件/二进制 | 撑爆单 key 512MB 限制，性能差 | 存文件路径 + 对象存储 |
+| 9 | Pipeline 无限攒批 | 客户端缓冲区 OOM | Pipeline 批量大小控制在 100-500 |
+| 10 | 不区分业务用同一个实例 | 互相影响，难以隔离 | 按业务拆分实例 + 限制内存/连接 |
+
+---
+
+## 9. FAQ
+
+**Q1: Redis 为什么不建议用作主数据库？**
+Redis 内存昂贵，虽支持持久化但最多丢 1 秒数据，且不支持 SQL 查询和复杂约束。典型架构是 Redis 作为加速层在前，关系型数据库做持久化存储在后。
+
+**Q2: Redis 内存满后会发生什么？**
+取决于 maxmemory-policy。推荐 `allkeys-lru`，淘汰最近最少使用的 key。如果设为 `noeviction`，写操作返回 OOM 错误。
+
+**Q3: RDB 和 AOF 同时开启时，启动加载顺序？**
+先加载 AOF（数据更完整），AOF 不存在再加载 RDB。混合持久化时 AOF 文件头部是 RDB 快照，先加载 RDB（快），再回放 AOF 增量。
+
+**Q4: 如何选择 Stream 还是 Pub/Sub？**
+
+| 对比 | Pub/Sub | Stream |
+|------|---------|--------|
+| 消息持久化 | ❌ 不持久，离线丢失 | ✅ 持久化到内存/磁盘 |
+| 消费确认 | ❌ 无 ACK | ✅ XACK 确认 |
+| 消费组 | ❌ 不支持 | ✅ XGROUP 消费组 |
+| 消息回溯 | ❌ 不可回溯 | ✅ XRANGE 可回放 |
+| 适用场景 | 实时广播通知 | 可靠消息队列/事件溯源 |
+
+**Q5: Cluster 模式下还能用事务/Lua 吗？**
+可以使用，但所有操作的 key 必须在同一节点。使用 hash tag `{tag}` 确保相关 key 路由到同一 slot。跨 slot 的事务无法执行。
+
+**Q6: Big Key 为什么危险？**
+一个 Big Key 导致：Redis 变慢（命令 O(n) 阻塞）、集群数据分布不均、持久化时间变长、主从同步延迟大。使用 `--bigkeys` 定期扫描。
+
+**Q7: Redis 线程模型是什么样的？**
+Redis 是单线程处理命令（6.0+ 网络 I/O 处理多线程）。单线程避免了锁竞争，但一个慢查询会阻塞所有后续请求。所以 Lua 脚本必须短小，KEYS 不能在 O(n) 命令上操作大集合。
+
+**Q8: 什么情况下用 Redis 6.0+ 的 ACL？**
+多租户场景、团队共用 Redis 实例时，用 ACL 控制权限可防止误操作。例如：业务线 A 只能操作 `a:*`，不能使用 FLUSHALL。
+
+**Q9: 如何在不重启的情况下修改配置？**
+`CONFIG SET` 动态修改运行期配置，`CONFIG REWRITE` 写入 redis.conf 使其重启后生效。
+
+**Q10: Redis 内存碎片率高怎么处理？**
+`mem_fragmentation_ratio > 1.5` 说明碎片严重。Redis 4.0+ 可用 `MEMORY PURGE` 命令触发碎片整理，或设置 `activedefrag yes` 自动整理。
+
+---
 
 ## Keywords
 
-redis, cache, 缓存, 数据结构, 主从, 集群
+redis, redis-cli, 缓存, string, hash, list, set, zset, sorted set, bitmap, hyperloglog, stream, geo, lua, 事务, pipeline, 持久化, RDB, AOF, 混合持久化, 主从复制, sentinel, 哨兵, cluster, 集群, 缓存穿透, 缓存击穿, 缓存雪崩, 分布式锁, 内存淘汰, LRU, LFU, big key, hot key, 慢查询, 性能优化, 安全加固, ACL, Redisson, Jedis, Lettuce, bigkey, hotkey, slot, hash tag, RediSearch, RedisJSON, Redis Stack, 数据淘汰
+
+---
+
+## References
+
+- [Redis 官方文档](https://redis.io/docs/latest/)
+- [Redis 命令参考 — redis.net.cn](https://www.redis.net.cn/order/)
+- [Redis 教程 — redis.net.cn](https://www.redis.net.cn/tutorial/3501.html)
+- [Redis 持久化 RDB/AOF — 官方](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)
+- [Redis 集群教程 — 官方](https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/)
+- [Redis 安全 — 官方](https://redis.io/docs/latest/operate/oss_and_stack/management/security/)
+- [Redis 性能优化 — 官方](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/)
+- [Redis 分布式锁 (Redlock) — 官方](https://redis.io/docs/latest/commands/set/)

skills/database-skills/redis/examples/01-cache-usage.md

@@ -0,0 +1,104 @@
+# Redis 缓存使用示例
+
+## 1. Cache-Aside 模式 (Java + Spring Boot)
+
+```java
+@Service
+public class UserService {
+    @Autowired
+    private RedisTemplate<String, Object> redisTemplate;
+    @Autowired
+    private UserMapper userMapper;
+
+    public User getUserById(Long id) {
+        String key = "user:" + id;
+        // 1. 尝试从缓存获取
+        User user = (User) redisTemplate.opsForValue().get(key);
+        if (user != null) {
+            return user;
+        }
+        // 2. 缓存未命中，查数据库
+        user = userMapper.selectById(id);
+        if (user != null) {
+            // 3. 写入缓存，设置 TTL
+            redisTemplate.opsForValue().set(key, user, 1, TimeUnit.HOURS);
+        }
+        return user;
+    }
+
+    public void updateUser(User user) {
+        // 1. 更新数据库
+        userMapper.updateById(user);
+        // 2. 删除缓存 (下次读取时重建)
+        redisTemplate.delete("user:" + user.getId());
+    }
+}
+```
+
+## 2. 分布式锁 (Python + redis-py)
+
+```python
+import redis
+import uuid
+import time
+
+r = redis.Redis(host='localhost', port=6379, decode_responses=True)
+
+def acquire_lock(lock_name, acquire_timeout=10, lock_timeout=30):
+    """获取分布式锁"""
+    identifier = str(uuid.uuid4())
+    lock_key = f"lock:{lock_name}"
+    end = time.time() + acquire_timeout
+
+    while time.time() < end:
+        if r.set(lock_key, identifier, nx=True, ex=lock_timeout):
+            return identifier  # 成功获取锁
+        time.sleep(0.01)  # 短暂休眠后重试
+    return None  # 超时未获取
+
+def release_lock(lock_name, identifier):
+    """释放分布式锁 (Lua 脚本保证原子性)"""
+    lock_key = f"lock:{lock_name}"
+    lua_script = """
+    if redis.call("get",KEYS[1]) == ARGV[1] then
+        return redis.call("del",KEYS[1])
+    else
+        return 0
+    end
+    """
+    return r.eval(lua_script, 1, lock_key, identifier)
+
+# 使用示例
+lock_id = acquire_lock("order:1001")
+if lock_id:
+    try:
+        print("处理订单 1001...")
+        # 执行业务逻辑
+    finally:
+        release_lock("order:1001", lock_id)
+```
+
+## 3. 限流器 (Node.js)
+
+```javascript
+const Redis = require('ioredis');
+const redis = new Redis();
+
+async function rateLimit(ip, limit = 100, window = 60) {
+    const key = `ratelimit:${ip}`;
+    const current = await redis.incr(key);
+    if (current === 1) {
+        await redis.expire(key, window);
+    }
+    return current <= limit;
+}
+
+// 使用: 每个 IP 每分钟最多 100 次请求
+app.use(async (req, res, next) => {
+    const allowed = await rateLimit(req.ip);
+    if (!allowed) {
+        return res.status(429).json({ error: '请求过于频繁' });
+    }
+    next();
+});
+```

skills/database-skills/redis/examples/02-session-storage.md

@@ -0,0 +1,72 @@
+# Redis Session 存储示例
+
+## 1. Spring Session + Redis
+
+```xml
+<!-- pom.xml 依赖 -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-data-redis</artifactId>
+</dependency>
+<dependency>
+    <groupId>org.springframework.session</groupId>
+    <artifactId>spring-session-data-redis</artifactId>
+</dependency>
+```
+
+```yaml
+# application.yml
+spring:
+  session:
+    store-type: redis
+    timeout: 1800  # Session 过期时间 (秒)
+  redis:
+    host: localhost
+    port: 6379
+    password: your_password
+    timeout: 2000ms
+    lettuce:
+      pool:
+        max-active: 50
+        max-idle: 20
+        min-idle: 5
+```
+
+```java
+@Configuration
+@EnableRedisHttpSession(maxInactiveIntervalInSeconds = 1800)
+public class RedisSessionConfig {
+    // 自动生效，无需额外代码
+}
+```
+
+## 2. Flask Session (Python)
+
+```python
+from flask import Flask, session
+from flask_session import Session
+import redis
+
+app = Flask(__name__)
+app.config['SECRET_KEY'] = 'your-secret-key'
+app.config['SESSION_TYPE'] = 'redis'
+app.config['SESSION_REDIS'] = redis.from_url('redis://localhost:6379/0')
+app.config['SESSION_PERMANENT'] = False
+app.config['SESSION_USE_SIGNER'] = True
+app.config['SESSION_KEY_PREFIX'] = 'session:'
+app.config['SESSION_PERMANENT_TIMEOUT'] = 1800
+
+Session(app)
+
+@app.route('/login')
+def login():
+    session['user_id'] = 1001
+    session['role'] = 'admin'
+    return 'Session stored in Redis'
+
+@app.route('/profile')
+def profile():
+    user_id = session.get('user_id')
+    role = session.get('role')
+    return f'User {user_id} with role {role}'
+```

skills/database-skills/redis/examples/03-leaderboard.md

@@ -0,0 +1,63 @@
+# Redis ZSet 排行榜示例
+
+## 游戏排行榜 (Go)
+
+```go
+package redis
+
+import (
+    "context"
+    "github.com/redis/go-redis/v9"
+)
+
+type Leaderboard struct {
+    rdb *redis.Client
+    key string
+}
+
+func NewLeaderboard(rdb *redis.Client, gameID string) *Leaderboard {
+    return &Leaderboard{rdb: rdb, key: "leaderboard:" + gameID}
+}
+
+// AddScore 增加玩家分数 (原子操作)
+func (lb *Leaderboard) AddScore(ctx context.Context, player string, score float64) error {
+    return lb.rdb.ZIncrBy(ctx, lb.key, score, player).Err()
+}
+
+// GetTopN 获取前 N 名
+func (lb *Leaderboard) GetTopN(ctx context.Context, n int64) ([]redis.Z, error) {
+    return lb.rdb.ZRevRangeWithScores(ctx, lb.key, 0, n-1).Result()
+}
+
+// GetRank 获取玩家排名 (从 0 开始)
+func (lb *Leaderboard) GetRank(ctx context.Context, player string) (int64, error) {
+    rank, err := lb.rdb.ZRevRank(ctx, lb.key, player).Result()
+    if err != nil {
+        return -1, err
+    }
+    return rank + 1, nil // 转为 1-based
+}
+
+// GetScore 获取玩家分数
+func (lb *Leaderboard) GetScore(ctx context.Context, player string) (float64, error) {
+    return lb.rdb.ZScore(ctx, lb.key, player).Result()
+}
+```
+
+## 周榜 + 日榜 + 总榜设计
+
+```redis
+# 命名规范
+leaderboard:total          # 总榜 (长周期)
+leaderboard:2024:W01       # 周榜
+leaderboard:2024:01:15     # 日榜
+
+# 每日零点：创建新日榜
+# 每周一零点：创建新周榜
+
+# 合并多期分数 (ZUNIONSTORE)
+ZUNIONSTORE leaderboard:month 3
+    leaderboard:2024:01:01 leaderboard:2024:01:02 leaderboard:2024:01:03
+    WEIGHTS 1 1 1
+    AGGREGATE SUM
+```

skills/database-skills/redis/examples/04-redis-cluster-setup.md

@@ -0,0 +1,70 @@
+# Redis Cluster 搭建与运维示例
+
+## 1. 最小生产集群 (3主3从)
+
+```bash
+# 6 个节点目录
+mkdir -p /data/redis/{7000,7001,7002,7003,7004,7005}
+
+# 每个节点 redis.conf
+cat > /data/redis/7000/redis.conf << 'EOF'
+port 7000
+cluster-enabled yes
+cluster-config-file nodes-7000.conf
+cluster-node-timeout 5000
+appendonly yes
+appendfsync everysec
+protected-mode no
+bind 0.0.0.0
+daemonize yes
+logfile /var/log/redis/7000.log
+EOF
+
+# 启动 6 个节点
+redis-server /data/redis/7000/redis.conf
+redis-server /data/redis/7001/redis.conf
+redis-server /data/redis/7002/redis.conf
+redis-server /data/redis/7003/redis.conf
+redis-server /data/redis/7004/redis.conf
+redis-server /data/redis/7005/redis.conf
+
+# 创建集群 (Redis 5+)
+redis-cli --cluster create \
+    192.168.1.100:7000 192.168.1.100:7001 192.168.1.100:7002 \
+    192.168.1.100:7003 192.168.1.100:7004 192.168.1.100:7005 \
+    --cluster-replicas 1
+```
+
+## 2. 集群运维命令
+
+```bash
+# 检查集群状态
+redis-cli -c -h 192.168.1.100 -p 7000 cluster info
+redis-cli -c -h 192.168.1.100 -p 7000 cluster nodes
+
+# 重新平衡 slot
+redis-cli --cluster rebalance 192.168.1.100:7000 \
+    --cluster-weight node1=1 node2=2 node3=1 \
+    --cluster-use-empty-masters
+
+# 修复集群
+redis-cli --cluster fix 192.168.1.100:7000
+
+# 动态扩容：添加节点
+redis-cli --cluster add-node 新节点:7006 已有节点:7000 --cluster-slave
+redis-cli --cluster reshard 已有节点:7000 --cluster-from all \
+    --cluster-to 新节点id --cluster-slots 1000 --cluster-yes
+```
+
+## 3. 数据迁移方案
+
+```bash
+# 使用 redis-shake 跨集群迁移
+redis-shake.linux -type sync -conf redis-shake.conf
+
+# redis-shake.conf 示例
+source.type = cluster
+source.address = 192.168.1.100:7000
+target.type = cluster
+target.address = 192.168.1.200:7000
+```

skills/database-skills/redis/examples/05-stream-queue.md

@@ -0,0 +1,65 @@
+# Redis Stream 消息队列示例
+
+## 1. 生产-消费模式
+
+```redis
+# 生产者: 发送消息
+XADD orders * order_id 1001 user_id 42 amount 99.99 status pending
+XADD orders * order_id 1002 user_id 55 amount 199.00 status pending
+
+# 消费者: 读取消息 (非阻塞)
+XRANGE orders - + COUNT 10
+
+# 消费者: 阻塞读取新消息
+XREAD COUNT 1 BLOCK 5000 STREAMS orders $
+
+# 消息长度
+XLEN orders
+
+# 删除消息
+XDEL orders 1700000000000-0
+
+# 修剪 (保留最近的 1000 条)
+XTRIM orders MAXLEN ~ 1000
+```
+
+## 2. 消费组模式
+
+```redis
+# 创建消费组 (从最新消息开始消费)
+XGROUP CREATE orders payment-group $ MKSTREAM
+XGROUP CREATE orders inventory-group $
+XGROUP CREATE orders notification-group $
+
+# 消费组成员: 读取未确认消息
+# payment-service
+XREADGROUP GROUP payment-group worker-1 COUNT 1 BLOCK 2000 STREAMS orders >
+# inventory-service
+XREADGROUP GROUP inventory-group worker-1 COUNT 1 BLOCK 2000 STREAMS orders >
+# notification-service
+XREADGROUP GROUP notification-group worker-1 COUNT 1 BLOCK 2000 STREAMS orders >
+
+# 确认消费 (ACK)
+XACK orders payment-group 1700000000000-0
+
+# 查看待确认消息
+XPENDING orders payment-group
+
+# 查看消费组信息
+XINFO GROUPS orders
+XINFO CONSUMERS orders payment-group
+```
+
+## 3. CAP 对比: Stream vs Kafka
+
+| 特性 | Redis Stream | Apache Kafka |
+|------|-------------|-------------|
+| 延迟 | <1ms | <10ms |
+| 消息持久化 | RDB/AOF | 磁盘日志 |
+| 消息回溯 | 支持 | 支持 |
+| 消费组 | 支持 | 支持 |
+| 分区顺序 | 单分区有序 | 单分区有序 |
+| 数据保留 | 内存+磁盘 (可控) | 磁盘 (可配置) |
+| 吞吐量 | 10万+/s | 百万+/s |
+| 运维复杂度 | 低 (Redis 原生) | 高 (需 ZK) |
+| 适用场景 | 微服务异步、任务队列 | 大数据流、日志采集 |

skills/database-skills/redis/references/command-quick-ref.md

@@ -0,0 +1,180 @@
+# Redis 命令速查
+
+## 操作分类速查
+
+```
+内存操作: SET / GET / DEL / EXISTS / TYPE / TTL / EXPIRE / PERSIST
+计数器:   INCR / DECR / INCRBY / INCRBYFLOAT
+散列:     HSET / HGET / HGETALL / HDEL / HEXISTS / HINCRBY
+列表:     LPUSH / RPUSH / LPOP / RPOP / LRANGE / LLEN / LTRIM / BLPOP
+集合:     SADD / SREM / SMEMBERS / SISMEMBER / SCARD / SINTER / SUNION
+有序集合: ZADD / ZREM / ZRANGE / ZRANK / ZSCORE / ZINCRBY / ZINTERSTORE
+位图:     SETBIT / GETBIT / BITCOUNT / BITOP
+地理:     GEOADD / GEOPOS / GEODIST / GEORADIUS
+流:       XADD / XREAD / XREADGROUP / XACK / XRANGE / XLEN / XTRIM
+超日志:   PFADD / PFCOUNT / PFMERGE
+事务:     MULTI / EXEC / WATCH / DISCARD
+脚本:     EVAL / EVALSHA / SCRIPT LOAD / SCRIPT KILL
+连接:     PING / AUTH / SELECT / CLIENT LIST / CLIENT KILL
+服务器:   INFO / CONFIG GET/SET / SLOWLOG / MONITOR / DBSIZE / FLUSHALL
+发布订阅: PUBLISH / SUBSCRIBE / PSUBSCRIBE / PUBSUB
+```
+
+## 字符串命令速查
+
+```
+SET key value [EX|PX] [NX|XX]     # 设置值，支持过期和条件
+GET key                            # 返回字符串值或 nil
+MGET key1 key2                     # 批量获取
+MSET k1 v1 k2 v2                   # 批量设置
+INCR key                           # 整数 +1 (原子)
+INCRBY key n                       # 整数 +n
+DECR key                           # 整数 -1
+DECRBY key n                       # 整数 -n
+APPEND key value                   # 追加到末尾
+GETRANGE key start end             # 获取子串
+SETRANGE key offset value          # 从 offset 覆写
+STRLEN key                         # 获取长度
+GETSET key new_value               # 返回旧值设新值
+SETEX key sec value                # 设置+过期
+SETNX key value                    # 不存在才设置
+```
+
+## 哈希命令速查
+
+```
+HSET key field value               # 设置字段
+HSETNX key field value             # 不存在才设置
+HGET key field                     # 获取字段
+HGETALL key                        # 获取所有 (慎用)
+HMGET key f1 f2                    # 批量获取
+HMSET key f1 v1 f2 v2             # 批量设置
+HDEL key field                     # 删除字段
+HEXISTS key field                  # 判断存在
+HLEN key                           # 字段数量
+HKEYS key                          # 所有字段名
+HVALS key                          # 所有字段值
+HINCRBY key field n                # 字段值 +n
+HINCRBYFLOAT key field n           # 浮点增加
+```
+
+## 列表命令速查
+
+```
+LPUSH key v1 v2                    # 左推
+RPUSH key v1 v2                    # 右推
+LPOP key                           # 左弹
+RPOP key                           # 右弹
+LRANGE key start stop              # 范围获取
+LINDEX key index                   # 索引获取
+LLEN key                           # 长度
+LREM key count value               # 移除元素
+LTRIM key start stop               # 修剪
+LSET key index value               # 设置索引值
+BLPOP key timeout                  # 阻塞左弹
+BRPOP key timeout                  # 阻塞右弹
+RPOPLPUSH src dst                  # 转存
+BRPOPLPUSH src dst timeout         # 阻塞转存
+```
+
+## 集合命令速查
+
+```
+SADD key m1 m2                     # 添加
+SREM key m1                        # 移除
+SMEMBERS key                       # 所有成员
+SISMEMBER key m                    # 是否在集合中
+SCARD key                          # 数量
+SPOP key                           # 随机弹出
+SRANDMEMBER key count              # 随机取样
+SINTER k1 k2                       # 交集
+SUNION k1 k2                       # 并集
+SDIFF k1 k2                        # 差集
+SINTERSTORE dest k1 k2             # 交集存
+SUNIONSTORE dest k1 k2             # 并集存
+SDIFFSTORE dest k1 k2              # 差集存
+SSCAN key cursor                   # 渐进迭代
+```
+
+## 有序集合命令速查
+
+```
+ZADD key score member              # 添加
+ZREM key member                    # 移除
+ZRANGE key start stop [WITHSCORES] # 按排名取 (小到大)
+ZREVRANGE key start stop [WS]      # 按排名取 (大到小)
+ZRANGEBYSCORE key min max          # 按分数取
+ZRANK key member                   # 排名 (小到大)
+ZREVRANK key member                # 排名 (大到小)
+ZSCORE key member                  # 分数
+ZCARD key                          # 数量
+ZINCRBY key n member               # 分数 +n
+ZCOUNT key min max                 # 分数区间内数量
+ZREM key member                    # 移除
+ZREMRANGEBYRANK key start stop     # 移除排名区间
+ZREMRANGEBYSCORE key min max       # 移除分数区间
+ZINTERSTORE dest n keys [WEIGHTS]  # 交集
+ZUNIONSTORE dest n keys [WEIGHTS]  # 并集
+ZSCAN key cursor                   # 渐进迭代
+```
+
+## 发布订阅命令速查
+
+```
+SUBSCRIBE channel                  # 订阅
+UNSUBSCRIBE channel                # 退订
+PUBLISH channel message            # 发布
+PSUBSCRIBE pattern                 # 模式订阅
+PUNSUBSCRIBE pattern               # 模式退订
+PUBSUB channels                    # 查看活跃频道
+PUBSUB numsub channel              # 查看频道订阅数
+```
+
+## 脚本命令速查
+
+```
+EVAL script numkeys key [key] arg [arg]           # 执行 Lua
+EVALSHA sha1 numkeys key [key] arg [arg]          # 通过 SHA1 执行缓存脚本
+SCRIPT LOAD script                                 # 加载脚本到缓存
+SCRIPT EXISTS sha1                                 # 检查脚本是否在缓存
+SCRIPT FLUSH                                       # 清除脚本缓存
+SCRIPT KILL                                        # 终止正在运行的脚本
+```
+
+## 连接命令速查
+
+```
+PING                               # 检查是否 alive
+ECHO message                       # 回显
+AUTH password                      # 认证
+SELECT index                       # 选择数据库
+QUIT                               # 关闭连接
+```
+
+## 服务器命令速查
+
+```
+INFO [section]                     # 服务器信息
+CONFIG GET parameter               # 获取配置
+CONFIG SET parameter value         # 修改配置 (运行时)
+CONFIG REWRITE                     # 写入配置文件
+DBSIZE                             # 当前数据库 key 数量
+FLUSHDB                            # 清空当前库
+FLUSHALL                           # 清空所有库
+CLIENT LIST                        # 客户端列表
+CLIENT KILL ip:port                # 杀死客户端连接
+SLOWLOG GET n                      # 获取慢查询日志
+MONITOR                            # 实时监控 (生产慎用)
+SAVE                               # 同步保存 RDB
+BGSAVE                             # 后台保存 RDB
+BGREWRITEAOF                       # 重写 AOF
+LASTSAVE                           # 最后保存时间
+SHUTDOWN                           # 关闭服务器
+SLAVEOF host port                  # 设置主从
+ROLE                               # 查看角色
+TIME                               # 服务器时间
+DEBUG OBJECT key                   # key 调试信息
+MEMORY USAGE key                   # 精确内存
+MEMORY PURGE                       # 整理碎片
+COMMAND                            # 命令统计
+```

skills/database-skills/redis/references/commands-admin-key.md

@@ -0,0 +1,413 @@
+# Redis 命令详解 — Key / 事务 / Lua / PubSub / 连接 / 服务器
+
+> 内容源自 doc.redisfans.com 完整翻译版 (Redis 2.8+)，每个命令包含简介、参数说明、业务场景。
+
+---
+
+## 1. Key（键）命令
+
+| 命令 | 时间复杂度 | 可用版本 | 说明 |
+|------|-----------|---------|------|
+| DEL | O(N) | ≥1.0.0 | 删除 key |
+| EXISTS | O(1) | ≥1.0.0 | 检查存在 |
+| EXPIRE | O(1) | ≥1.0.0 | 设置 TTL |
+| TTL | O(1) | ≥1.0.0 | 查看 TTL |
+| TYPE | O(1) | ≥1.0.0 | 返回类型 |
+| KEYS | O(N) | ≥1.0.0 | 查找 key |
+| SCAN | O(1)/cursor | ≥2.8.0 | 渐进遍历 |
+
+### DEL
+**DEL key [key ...]**
+
+删除一个或多个 key。不支持通配符（请使用 SCAN + DEL）。
+- 时间复杂度 O(N)：N 为删除的 key 数量，复杂类型（List/Set/ZSet/Hash）删除时间与元素数量相关
+
+**业务场景**：
+- 清理缓存 `DEL cache:user:42 cache:user:43 cache:user:44`
+- 重置数据 `DEL user:1001:session`
+
+**返回值**：被删除 key 的数量
+
+---
+
+### EXISTS
+**EXISTS key [key ...] (Redis 3.0.3+ 支持多 key)**
+
+检查 key 是否存在。多 key 版本返回存在的 key 数。
+
+**业务场景**：
+- 缓存命中判断 `EXISTS cache:hot:article:42` → 1 命中
+- 批量校验 `EXISTS key1 key2 key3` → 快速判断多个 key 全部存在
+
+---
+
+### EXPIRE / PEXPIRE
+**EXPIRE key seconds**
+**PEXPIRE key milliseconds**
+
+设置 key 的生存时间（秒/毫秒），到期后自动删除（易失性）。
+- TTL 不会被只读/修改命令（INCR/LPUSH/HSET）改变
+- RENAME 后新 key 继承 TTL
+- SET/GETSET 会清除原有 TTL
+
+**业务场景**：
+```
+# 导航会话（60 秒无操作清空）
+MULTI
+    RPUSH navig:user:42 "page_3"
+    EXPIRE navig:user:42 60
+EXEC
+```
+
+---
+
+### EXPIREAT / PEXPIREAT
+**EXPIREAT key timestamp**
+**PEXPIREAT key milliseconds-timestamp**
+
+设置 key 在指定 Unix 时间戳过期。精确到秒/毫秒。
+
+**业务场景**：
+- **优惠券到期**：`EXPIREAT coupon:user:42 1893456000`（2030-01-01 00:00）
+- **定时删除**：配合 cron 计算到期时间戳
+
+---
+
+### TTL / PTTL
+**TTL key** — 返回剩余生存时间（秒），-1 无过期，-2 key 不存在
+**PTTL key** — 返回毫秒数
+
+**业务场景**：
+- 热键 TTL 监控（防止缓存穿透）
+- 动态延长热点数据 TTL：TTL < 30 时 EXPIRE 续期
+
+---
+
+### PERSIST
+**PERSIST key** — 移除 key 的过期时间，使其持久保留
+
+**业务场景**：将热点 key 从"定时过期"转为"永久缓存"
+
+---
+
+### TYPE
+**TYPE key** — 返回 key 的数据类型：string / list / set / zset / hash / stream / none
+
+**业务场景**：键值类型校验，防止对集合类型执行字符串操作
+
+---
+
+### KEYS
+**KEYS pattern** — 查找所有匹配 pattern 的 key
+- 支持 glob 风格：`*` `?` `[a-z]`
+- **O(N) 阻塞操作，生产环境严禁使用**
+
+**正确做法**：使用 `SCAN 0 MATCH user:* COUNT 100`
+
+---
+
+### SCAN
+**SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]**
+
+渐进式迭代数据库中的 key。每次返回游标 + 一批 key。
+- cursor = 0 开始迭代，cursor = 0 结束
+- COUNT 提示每次返回数量（不保证精确）
+- TYPE 过滤类型 (Redis 6.0+)
+
+**业务场景**：
+```
+SCAN 0 MATCH user:* COUNT 100        # 迭代查找 user: 开头的 key
+SCAN 0 TYPE hash COUNT 100           # 只找 hash 类型的 key
+```
+
+---
+
+### RENAME / RENAMENX
+**RENAME key newkey** — 改名（newkey 存在则覆盖）
+**RENAMENX key newkey** — 改名（仅 newkey 不存在时）
+
+**业务场景**：数据迁移、key 命名变更、A/B 测试流量切换
+
+---
+
+### MOVE
+**MOVE key db** — 将当前数据库的 key 移到指定数据库
+
+> 注意：Cluster 模式只支持 0 号数据库，MOVE 无法使用。
+
+---
+
+### RANDOMKEY
+**RANDOMKEY** — 从当前数据库中随机返回一个 key
+
+**业务场景**：数据采样、缓存预热随机检查
+
+---
+
+### DUMP / RESTORE
+**DUMP key** — 序列化 key 并返回（含 TTL 信息）
+**RESTORE key ttl serialized-value [REPLACE] [ABSTTL] [IDLETIME t] [FREQ f]**
+
+**业务场景**：
+- **迁移单个 key**：源 DUMP → 目标 RESTORE
+- **备份恢复**：对单个 key 做序列化备份
+
+---
+
+### OBJECT
+**OBJECT subcommand [arguments [arguments]]**
+- `OBJECT REFCOUNT key` — 引用计数
+- `OBJECT ENCODING key` — 底层编码（raw/embstr/ziplist/dict/intset/skiplist）
+- `OBJECT IDLETIME key` — 空闲时间（LRU 相关）
+
+**业务场景**：
+```
+OBJECT ENCODING user:1001    → "hashtable" 或 "ziplist"
+OBJECT IDLETIME hot_data     → 判断是否为闲置 key
+```
+
+---
+
+### SORT
+**SORT key [BY pattern] [LIMIT offset count] [GET pattern] [ASC|DESC] [ALPHA] [STORE destination]**
+
+对 List、Set、ZSet 中的元素排序（支持外部 key BY/GET，**可能阻塞**）。
+
+> Redis 6.2.0+ 弃用 SORT，推荐使用 SORT_RO（只读版）。
+
+---
+
+## 2. 事务（Transaction）命令
+
+| 命令 | 时间复杂度 | 可用版本 | 说明 |
+|------|-----------|---------|------|
+| MULTI | O(1) | ≥1.2.0 | 开始事务 |
+| EXEC | 取决于命令 | ≥1.2.0 | 执行 |
+| DISCARD | O(1) | ≥2.0.0 | 取消 |
+| WATCH | O(1) | ≥2.0.0 | 乐观锁 |
+
+### MULTI / EXEC / DISCARD
+**MULTI** — 标记事务块开始（后续命令入队）
+**EXEC** — 顺序执行队列中所有命令
+**DISCARD** — 取消事务，清空命令队列
+
+**事务特性**：
+- 原子性：EXEC 时要么全部执行，要么因语法错误全部不执行
+- 无回滚：运行时错误（如对 string 执行 LIST 操作）不影响其他命令
+- 隔离性：EXEC 前其他客户端不会看到中间状态
+
+**业务场景**：
+```
+# 转账（原子扣减 + 增加）
+MULTI
+    DECRBY account:42 1000
+    INCRBY account:100 1000
+EXEC
+```
+
+---
+
+### WATCH / UNWATCH
+**WATCH key [key ...]** — 乐观锁（CAS）
+**UNWATCH** — 取消所有 WATCH
+
+**业务场景**：
+```
+# 库存扣减（CAS 保证）
+WATCH stock:item:1001
+count = GET stock:item:1001
+if count > 0:
+    MULTI
+        DECRBY stock:item:1001 1
+    EXEC    # 如果 stock:item:1001 在此期间被修改 → EXEC 返回 nil
+else:
+    UNWATCH    # 放弃监视
+```
+
+---
+
+## 3. Lua 脚本命令
+
+| 命令 | 可用版本 | 说明 |
+|------|---------|------|
+| EVAL | ≥2.6.0 | 执行脚本 |
+| EVALSHA | ≥2.6.0 | 执行缓存脚本 |
+| SCRIPT LOAD | ≥2.6.0 | 加载到缓存 |
+| SCRIPT EXISTS | ≥2.6.0 | 检查缓存 |
+| SCRIPT FLUSH | ≥2.6.0 | 清理缓存 |
+| SCRIPT KILL | ≥2.6.0 | 终止运行 |
+
+### EVAL
+**EVAL script numkeys key [key ...] arg [arg ...]**
+
+在服务器端执行 Lua 脚本。脚本在 Redis 内原子执行。
+
+**关键规则**：
+- 所有 key 通过 KEYS 数组传入（Cluster 兼容）
+- 所有参数通过 ARGV 数组传入
+- 脚本应短小精悍（Lua 脚本执行时阻塞其他所有请求）
+
+**业务场景：原子取余分配**
+```lua
+-- 一致性哈希槽分配
+local slot = redis.call("HGET", KEYS[1], ARGV[1])
+if not slot then
+    slot = redis.call("HLEN", KEYS[1]) % tonumber(ARGV[2])
+    redis.call("HSET", KEYS[1], ARGV[1], slot)
+end
+return slot
+```
+
+**业务场景：原子限流**
+```lua
+-- 滑动窗口限流
+local key = KEYS[1]
+local now = redis.call("TIME")[1]
+local window = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+
+redis.call("ZREMRANGEBYSCORE", key, 0, now - window)
+local count = redis.call("ZCARD", key)
+
+if count < limit then
+    redis.call("ZADD", key, now, now .. ":" .. math.random())
+    redis.call("EXPIRE", key, window)
+    return 1  -- 允许
+else
+    return 0  -- 限流
+end
+```
+
+---
+
+## 4. Pub/Sub（发布/订阅）命令
+
+| 命令 | 可用版本 | 说明 |
+|------|---------|------|
+| SUBSCRIBE | ≥2.0.0 | 订阅频道 |
+| PUBLISH | ≥2.0.0 | 发布消息 |
+| PSUBSCRIBE | ≥2.0.0 | 模式订阅 |
+
+### SUBSCRIBE / PUBLISH
+**SUBSCRIBE channel [channel ...]** — 订阅一个或多个频道
+**PUBLISH channel message** — 向频道发送消息
+
+**业务场景**：
+- **实时通知广播**：用户发布新内容时通知关注者
+- **服务状态广播**：配置变更通知所有服务实例
+- **实时聊天**：每个聊天室一个频道
+
+### PSUBSCRIBE
+**PSUBSCRIBE pattern [pattern ...]**
+
+按模式订阅频道。模式支持 glob 风格：`news.*` 匹配 `news.sports`、`news.tech` 等。
+
+### PUBSUB
+**PUBSUB subcommand [argument [arguments]]**
+- `PUBSUB CHANNELS [pattern]` — 查看当前活跃频道
+- `PUBSUB NUMSUB [channel ...]` — 查看频道订阅数
+- `PUBSUB NUMPAT` — 查看模式订阅数
+
+---
+
+## 5. 连接（Connection）命令
+
+| 命令 | 可用版本 | 说明 |
+|------|---------|------|
+| AUTH | ≥1.0.0 | 密码认证 |
+| SELECT | ≥1.0.0 | 切换数据库 |
+| PING | ≥1.0.0 | 存活检测 |
+| CLIENT | ≥2.4.0 | 客户端管理 |
+
+### AUTH
+**AUTH password** — 向 Redis 验证密码（requirepass 配置）
+
+### SELECT
+**SELECT index** — 切换到指定数据库（0-15，默认 16 个库）
+> ⚠️ Cluster 模式不支持 SELECT，只可用 0 号库。推荐用不同 key 前缀代替。
+
+### PING
+**PING** — 检查连接是否存活。返回 PONG。
+
+### QUIT
+**QUIT** — 关闭连接
+
+### CLIENT 系列
+**CLIENT SETNAME name** — 设置连接名称（便于 DEBUG）
+**CLIENT GETNAME** — 获取连接名称
+**CLIENT LIST** — 列出所有连接（含名称/地址/状态/缓冲区大小）
+**CLIENT KILL [ip:port] [ID client-id]** — 杀掉连接
+**CLIENT PAUSE timeout** — 暂停所有客户端命令（用于故障转移）
+**CLIENT UNPAUSE** — 恢复
+
+---
+
+## 6. 服务器（Server）命令
+
+| 命令 | 可用版本 | 说明 |
+|------|---------|------|
+| INFO | ≥1.0.0 | 服务器信息 |
+| CONFIG | ≥2.0.0 | 配置管理 |
+| SLOWLOG | ≥2.2.12 | 慢查询日志 |
+| MONITOR | ≥1.0.0 | 实时调试 |
+
+### INFO
+**INFO [section]**
+
+返回服务器信息（含 9 个 section）：
+- Server / Clients / Memory / Persistence / Stats / Replication / CPU / Keyspace / Cluster
+
+**常用**：`INFO MEMORY` `INFO STATS` `INFO REPLICATION` `INFO KEYSPACE`
+
+### CONFIG
+**CONFIG GET parameter** — 获取配置值 `CONFIG GET *` 全部
+**CONFIG SET parameter value** — 修改运行时配置（无需重启）
+**CONFIG REWRITE** — 写入 redis.conf（使修改持久化）
+**CONFIG RESETSTAT** — 重置 INFO 统计
+
+### SLOWLOG
+**SLOWLOG GET [count]** — 返回慢查询
+**SLOWLOG LEN** — 慢查询总数
+**SLOWLOG RESET** — 清空慢查询
+
+### MONITOR
+实时打印 Redis 收到的所有命令。**生产慎用**（降低约 50% 吞吐量）。
+
+### FLUSHDB / FLUSHALL
+**FLUSHDB** — 清空当前数据库
+**FLUSHALL** — 清空所有数据库
+> 用 `CONFIG SET rename-command FLUSHALL ""` 禁用
+
+### BGSAVE / SAVE
+**BGSAVE** — 后台 fork 生成 RDB（不阻塞）
+**SAVE** — 前台生成 RDB（阻塞所有请求）
+
+### BGREWRITEAOF
+异步重写 AOF 文件（压缩）。
+
+### SHUTDOWN
+**SHUTDOWN [NOSAVE|SAVE]** — 关闭服务器
+- SAVE：关闭前生成 RDB
+- NOSAVE：跳过保存
+
+### SLAVEOF
+**SLAVEOF host port** — 设置主从
+**SLAVEOF NO ONE** — 取消复制，提升为主
+
+### ROLE
+返回实例的角色：master / slave / sentinel + 复制状态
+
+### INFO 关键字段解读
+
+```
+used_memory_human: 4.00G           # 已用内存
+used_memory_peak_human: 6.00G      # 峰值内存
+mem_fragmentation_ratio: 1.37      # 碎片率（>1.5 需整理）
+connected_clients: 50              # 当前连接数
+instantaneous_ops_per_sec: 15000   # 当前 QPS
+keyspace_hits: 410000              # 缓存命中率计算
+keyspace_misses: 82000
+expired_keys: 0                    # 过期 key 数
+evicted_keys: 0                    # 淘汰 key 数
+rejected_connections: 0            # 拒绝的连接数
+```