Merge branch 'feature/full_statck_skills' into main

- Security fix: corrected unclaimed npm package names (electron-egg→ee-core, @avue/form→@smallwei/avue, removed non-existent lime-echart)
- Added https://v2.tauri.app/llms.txt reference to all 52 tauri skill SKILL.md files
- Added missing Tauri docs URLs: flatpak distribute, asset-protocol security, mobile-file-associations, mobile-multiwindow
- Removed deprecated DDD and dbeaver skills

.claude-plugin/marketplace.json

@@ -141,6 +141,15 @@
         "./skills/spring-skills/spring-data-jpa"
       ]
     },
+    {
+      "name": "java-skills",
+      "description": "Java 编码规范与注释规范（1个技能）：统一 SLF4J+Lombok、判空与工具类优先级、以及 Controller/Service/ServiceImpl/Mapper 注释一致性。",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/java-skills/java-conventions"
+      ]
+    },
     {
       "name": "nodejs-skills",
       "description": "Node.js 后端框架：Express、Fastify、NestJS、Koa（4个技能）。",
@@ -311,7 +320,7 @@
     },
     {
       "name": "document-skills",
-      "description": "文档与图表：docx、pptx、pdf、xlsx、文档协作、API 文档、全栈产品文档标准（full-stack-doc）、ProcessOn 思维导图、Mermaid、PlantUML（10个技能，与 skill-group-mapping 一致）。",
+      "description": "文档与图表：docx、pptx、pdf、xlsx、文档协作、API 文档、全栈产品文档标准（full-stack-doc）、ProcessOn 思维导图、ProcessOn 图表生成、Mermaid、PlantUML（11个技能，与 skill-group-mapping 一致）。",
       "source": "./",
       "strict": false,
       "skills": [
@@ -323,6 +332,7 @@
         "./skills/document-skills/api-doc-generator",
         "./skills/document-skills/full-stack-doc",
         "./skills/document-skills/processon-mindmap",
+        "./skills/document-skills/processon-diagram-generator",
         "./skills/document-skills/mermaid",
         "./skills/document-skills/plantuml"
       ]

AWESOME_AGENT_SKILLS.md

@@ -0,0 +1,243 @@
+# Awesome Agent Skills — 全技能索引
+
+_索引生成时间：2026-05-29 | 44 个技能组 | 463 个技能_
+
+---
+
+## 📊 技能组总览
+
+| 分类 | 技能组 | 技能数 | 状态 |
+|------|--------|:-----:|------|
+| 🏗️ 架构 | [ddd](#ddd) | 16 | ✅ 全部高质量 (TRACE 4.5+) |
+| 🗄️ 数据库 | [database](#database) | 5 | ✅ 全部深度技能 |
+| 🎨 前端框架 | [angular](#angular) / [react](#react) / [vue](#vue) / [svelte](#svelte) / [flutter](#flutter) / [uniapp](#uniapp) / [cocos](#cocos) / [electron](#electron) | 17 | |
+| 🔧 后端 | [spring](#spring) / [go](#go) / [python](#python) / [nodejs](#nodejs) | 16 | |
+| 🛠️ 工具 | [build](#build) / [docker](#docker) / [devops](#devops) / [nvm](#nvm) / [vscode](#vscode) | 37 | |
+| ✅ 测试 | [testing](#testing) | 9 | |
+| 📄 文档 | [document](#document) | 9 | |
+| 🎨 设计 | [design](#design) / [pencil](#pencil) / [drawio](#drawio) | 37 | |
+| 🧩 UI库 | [antd](#antd) / [avue](#avue) / [uview](#uview) / [vue-ui](#vue-ui) / [t2ui](#t2ui) | 112 | |
+| 📊 图表 | [chart](#chart) | 2 | |
+| 🎮 3D | [threejs](#threejs) | 19 | |
+| 🏗️ 桌面 | [tauri](#tauri) | 54 | |
+| 🔢 工具 | [ascii](#ascii) / [dev-utils](#dev-utils) / [utility](#utility) | 28 | |
+| 📝 规范 | [base](#base) / [openspec](#openspec) / [speckit](#speckit) | 37 | |
+| 📱 原生 | [mobile-native](#mobile-native) | 2 | |
+| 🤖 AI | [jimeng](#jimeng) | 8 | |
+| 👥 社交 | [social](#social) | 2 | |
+| 📚 教学 | [teaching](#teaching) | 3 | |
+| 🔌 集成 | [stitch](#stitch) / [ocrmypdf](#ocrmypdf) | 36 | |
+
+---
+
+## 🗄️ database — 数据库 (5 个，全部深度优化)
+
+| 技能 | 内容深度 | TRACE | 说明 |
+|------|:---:|:----:|------|
+| [redis](skills/database-skills/redis) | ~38KB | **4.67** | 9 大数据结构 + 缓存/持久化/集群/Lua/安全 |
+| [mysql](skills/database-skills/mysql) | ~76KB | **4.34** | SQL语法+80+函数+引擎+索引+复制+优化 |
+| [postgresql](skills/database-skills/postgresql) | ~99KB | **4.51** | JSONB+CTE+全文搜索+扩展+窗口函数+FDW |
+| [oracle](skills/database-skills/oracle) | ~85KB | **4.39** | PL/SQL+AWR+RMAN+Data Guard+RAC+分析函数 |
+| [elasticsearch](skills/database-skills/elasticsearch) | ~82KB | **4.38** | 查询DSL+聚合+分词器+映射+集群+ELK |
+
+---
+
+## 🏗️ ddd — 领域驱动设计 (16 个，全部 TRACE 4.5+)
+
+> 设计哲学：按用户学习路径组织 — 入门认知 → 架构选型 → 架构落地 → 领域设计 → CQRS → API → 审查 → 评估 → 文档 → 测试 → DevOps
+
+### 入门与选型
+| 技能 | 职责 | TRACE |
+|------|------|:----:|
+| [ddd-architecture-awesome](skills/ddd-skills/ddd-architecture-awesome) | DDD 概念入门 + 适用性评估 + 复杂度阶梯 + 架构全景 | - |
+| [ddd-architecture-selector](skills/ddd-skills/ddd-architecture-selector) | 5 种架构决策矩阵 + 决策树 + 域三分法 + CQRS 级别建议 | **4.59** |
+
+### 架构落地（5 种架构独立 Skill）
+| 技能 | 架构 | 项目示例 | TRACE |
+|------|------|:---:|:----:|
+| [ddd-architecture-layered](skills/ddd-skills/ddd-architecture-layered) | DDD 四层分层 | 7 种规模 | **4.69** |
+| [ddd-architecture-onion](skills/ddd-skills/ddd-architecture-onion) | 洋葱架构 | 7 种规模 | **4.72** |
+| [ddd-architecture-hexagonal](skills/ddd-skills/ddd-architecture-hexagonal) | 六边形架构 (Ports & Adapters) | 7 种规模 | **4.68** |
+| [ddd-architecture-clean](skills/ddd-skills/ddd-architecture-clean) | 整洁架构 (Robert C. Martin) | 7 种规模 | **4.68** |
+| [ddd-architecture-cola](skills/ddd-skills/ddd-architecture-cola) | COLA v5 菱形架构 + ddd4j 脚手架 | 7+4 种规模 | **4.67** |
+
+### 领域与模式
+| 技能 | 职责 | TRACE |
+|------|------|:----:|
+| [ddd-domain-designer](skills/ddd-skills/ddd-domain-designer) | 事件风暴驱动6步领域建模 + 聚合设计五步法六原则 | **4.69** |
+| [ddd-event-storming](skills/ddd-skills/ddd-event-storming) | 事件风暴工作坊引导 + 6步流程 + 便签颜色规范 | **4.64** |
+| [ddd-cqrs-architecture](skills/ddd-skills/ddd-cqrs-architecture) | CQRS L1/L2/L3 落地 + Event Sourcing + 幂等设计 | **4.71** |
+| [ddd-api-designer](skills/ddd-skills/ddd-api-designer) | CQRS 读写 API + PO/DO/DTO/VO 转换链 + BFF + OpenAPI | **4.78** |
+
+### 质量与运维
+| 技能 | 职责 | TRACE |
+|------|------|:----:|
+| [ddd-code-reviewer](skills/ddd-skills/ddd-code-reviewer) | 12 种反模式 P0/P1/P2 检测 + 充血模型验证 + 5维评分 | **4.60** |
+| [ddd-architecture-evaluator](skills/ddd-skills/ddd-architecture-evaluator) | DDD 成熟度5级 + 适配度评估 + 技术债务量化 | **4.71** |
+| [ddd-architecture-doc](skills/ddd-skills/ddd-architecture-doc) | C4 模型 + ADR + 领域模型文档 + API 文档 | **4.54** |
+| [ddd-testing-strategist](skills/ddd-skills/ddd-testing-strategist) | 测试金字塔 + TDDD + 各架构测试策略 | **4.67** |
+| [ddd-devops-integration](skills/ddd-skills/ddd-devops-integration) | CI/CD + ArchUnit 自动化 + K8s 部署 + Flyway 迁移 | **4.65** |
+
+---
+
+## 🎨 前端框架
+
+### angular (1)
+- [angular](skills/angular-skills/angular) — Angular 框架综合指南
+
+### antd (4)
+- [ant-design-mini](skills/antd-skills/ant-design-mini) — Ant Design Mini 小程序组件库
+- [ant-design-mobile](skills/antd-skills/ant-design-mobile) — Ant Design Mobile 移动端组件库
+- [ant-design-react](skills/antd-skills/ant-design-react) — Ant Design React 组件库
+- [ant-design-vue](skills/antd-skills/ant-design-vue) — Ant Design Vue 组件库
+
+### ascii (13)
+- [ascii-ansi-colorizer](skills/ascii-skills/...) — ANSI 配色
+- [ascii-cli-logo-banner](skills/ascii-skills/...) — CLI ASCII Logo
+- [ascii-diagram-boxflow](skills/ascii-skills/...) — 盒状流程图
+- [ascii-image-to-ascii](skills/ascii-skills/...) — 图像转 ASCII
+- [ascii-mini-charts](skills/ascii-skills/...) — ASCII 迷你图表
+- [ascii-motd-profile-banner](skills/ascii-skills/...) — MOTD Banner
+- [ascii-progress-and-spinner](skills/ascii-skills/...) — 进度条
+- [ascii-table-renderer](skills/ascii-skills/...) — 表格渲染
+- [ascii-terminal-animation-pack](skills/ascii-skills/...) — 终端动画
+- [ascii-text-art-library](skills/ascii-skills/...) — 文字艺术库
+- [cli-ascii-logo](skills/ascii-skills/...) — CLI Logo 生成
+
+### avue (3)
+- [avue](skills/avue-skills/avue) — Avue 框架
+- [avue-crud](skills/avue-skills/avue-crud) — Avue CRUD
+- [avue-form](skills/avue-skills/avue-form) — Avue Form
+
+### vue (7)
+- [vue2](skills/vue-skills/vue2) — Vue 2
+- [vue3](skills/vue-skills/vue3) — Vue 3
+- [vue-router](skills/vue-skills/vue-router) — Vue Router
+- [vue-router-v3](skills/vue-skills/vue-router-v3) — Vue Router v3
+- [vue-router-v4](skills/vue-skills/vue-router-v4) — Vue Router v4
+- [vuex-vue2](skills/vue-skills/vuex-vue2) — Vuex
+- [pinia](skills/vue-skills/pinia) — Pinia
+
+### react (6)
+- [react](skills/react-skills/react) — React
+- [react-hooks](skills/react-skills/react-hooks) — React Hooks
+- [react-native](skills/react-skills/react-native) — React Native
+- [react-native-project-creater](skills/react-skills/react-native-project-creater) — RN 项目创建
+- [redux](skills/react-skills/redux) — Redux
+- [nextjs](skills/react-skills/nextjs) — Next.js
+
+### 更多前端 (13)
+- svelte (1) / flutter (2) / uniapp (13) / cocos (1) / electron (3) / tauri (54) / threejs (19)
+- vue-ui (4) / uview (2) / t2ui (99)
+
+---
+
+## 🔧 后端与基础设施
+
+### spring (7)
+- [spring-boot](skills/spring-skills/spring-boot.md) / spring-data-jpa / spring-security / spring-cloud / ...
+
+### go (2)
+- [gin](skills/go-skills/gin) / [gin-gonic](skills/go-skills/gin-gonic)
+
+### python (3)
+- [flask](skills/python-skills/flask) / [django](skills/python-skills/django) / [fastapi](skills/python-skills/fastapi)
+
+### nodejs (4)
+- [express](skills/nodejs-skills/express) / [koa](skills/nodejs-skills/koa) / [fastify](skills/nodejs-skills/fastify) / nestjs
+
+### 构建工具 — build (6)
+- [vite](skills/build-skills/vite) / [webpack](skills/build-skills/webpack) / [rollup](skills/build-skills/rollup) / [rspack](skills/build-skills/rspack) / [parcel](skills/build-skills/parcel) / [dart-sass](skills/build-skills/dart-sass)
+
+### 容器 — docker (2)
+- [docker](skills/docker-skills/docker) / [docker-compose](skills/docker-skills/docker-compose)
+
+### DevOps (6)
+- [terraform](skills/devops-skills/terraform) / [kubernetes](skills/devops-skills/kubernetes) / [ansible](skills/devops-skills/ansible) / [github-actions](skills/devops-skills/github-actions) / [gitlab-ci](skills/devops-skills/gitlab-ci) / ...
+
+### NVM (17)
+- [nvm](skills/nvm-skills/nvm) 及全套管理工具
+
+### VSCode (6)
+- 扩展开发与发布
+
+---
+
+## ✅ 测试 — testing (9)
+- [pytest](skills/testing-skills/pytest) / [junit](skills/testing-skills/junit) / [selenium](skills/testing-skills/selenium) / [playwright](skills/testing-skills/playwright) / [appium](skills/testing-skills/appium) / [detox](skills/testing-skills/detox)
+
+---
+
+## 📄 文档 — document (9)
+- [docx](skills/document-skills/docx) / [pptx](skills/document-skills/pptx) / [pdf](skills/document-skills/pdf) / [xlsx](skills/document-skills/xlsx)
+- [mermaid](skills/document-skills/mermaid) / [plantuml](skills/document-skills/plantuml) / [full-stack-doc](skills/document-skills/full-stack-doc) / ...
+
+---
+
+## 🎨 设计与原型
+
+### design (4)
+- [algorithmic-art](skills/design-skills/algorithmic-art)
+
+### drawio (2)
+- [drawio-flowchart](skills/drawio-skills/drawio-flowchart) / [drawio-architecture](skills/drawio-skills/drawio-architecture)
+
+### pencil (31)
+- 完整 UI 设计原型工具链
+
+---
+
+## 🔢 工具辅助
+
+### base (5) — Skill 开发质量基础设施
+- [skill-trace-evaluation](skills/base-skills/skill-trace-evaluation) — TRACE 五维度评测
+- [skill-official-evaluation](skills/base-skills/skill-official-evaluation) — 官方规范评测
+- [skill-trace-checker](skills/base-skills/skill-trace-checker) — TRACE 检查
+- [skill-awesome](skills/base-skills/skill-awesome) — Skills AWESOME 列表生成
+
+### chart (2)
+- [ucharts](skills/chart-skills/ucharts) / [lime-echart](skills/chart-skills/lime-echart)
+
+### dev-utils (12)
+- 开发者工具集
+
+### mobile-native (2)
+- [android-kotlin](skills/mobile-native-skills/android-kotlin) / [ios-swift](skills/mobile-native-skills/ios-swift)
+
+### utility (3)
+- [skill-creator](skills/utility-skills/skill-creator) / [skill-installer](skills/utility-skills/skill-installer)
+
+---
+
+## 📝 规范驱动 — openspec/speckit (32)
+- openspec (17) + speckit (15)：Spec 驱动开发完整工具链
+
+---
+
+## 🤖 AI — jimeng (8)
+- [jimeng-prompt-text2image](skills/jimeng-skills/...) — 文生图提示词
+- [jimeng-prompt-text2video](skills/jimeng-skills/...) — 文生视频提示词
+- [jimeng-cli-text2image](skills/jimeng-skills/...) — CLI 生图
+- [jimeng-cli-text2video](skills/jimeng-skills/...) — CLI 生视频
+- 等 8 个技能
+
+---
+
+## 其他
+- social (2) / teaching (3) / stitch (31) / ocrmypdf (5) / spring (7)
+
+---
+
+## 📋 本次优化记录
+
+| 优化内容 | 涉及技能 | 成果 |
+|---------|---------|------|
+| **database 全组重写** | redis/mysql/postgresql/oracle/elasticsearch | 空壳 28 行 → 深度参考 76-99KB |
+| **DDD 全组重构** | 15 个 DDD 技能 | TRACE 4.54-4.78，平均 4.66 |
+| **项目规模示例** | 5 个架构技能 | 各 7 种项目规模 + ddd4j 真实参考 |
+| **文件序号化** | 15 个 DDD 技能 | 100% 中英文序号对齐 |
+| **ddd4j 融合** | cola 吸收 project-creator | 删除冗余，保留脚手架能力 |
+
+---
+
+_SkillHub TRACE 评测体系 | agentskills.io 官方规范_

CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Full-Stack-Skills is an open-source Agent Skills marketplace repository — a collection of 421+ skills across 42 groups covering frontend, backend, DevOps, design, documentation, and spec-driven development. Skills are packaged as `SKILL.md` files that Claude Code (and other Agent Skills-compatible platforms) loads on demand to extend its capabilities for specific tasks.
+
+The repository serves dual roles:
+- **Authoring environment**: Where skills are created, edited, and maintained following the [Agent Skills specification](https://agentskills.io/)
+- **Marketplace source**: Published via `.claude-plugin/marketplace.json` for installation through Claude Code's `/plugin` system
+
+Language convention (inherited from parent workspace): **Chinese** for documentation, comments, and commit messages.
+
+## Skill Directory Structure
+
+Skills follow a strict two-level grouping:
+
+```
+skills/<group>-skills/<skill-name>/SKILL.md
+```
+
+Each skill directory may optionally contain:
+- `examples/` — usage examples
+- `references/` — longer reference material (keeps SKILL.md under 500 lines)
+- `scripts/` — executable automation scripts
+- `assets/` — images, templates, and other resources
+- `templates/` — code templates
+
+### Naming Conventions
+
+- **Skill directory**: `kebab-case` (e.g., `vue3`, `spring-boot`, `tauri-app-creator`)
+- **SKILL.md**: Always uppercase, exact filename `SKILL.md`
+- **Scripts**: `kebab-case.sh` with `#!/bin/bash` shebang, `set -e`, status to stderr, machine-readable output to stdout
+- **Zip files**: Must match directory name exactly (`{skill-name}.zip`)
+
+## SKILL.md Format
+
+Every skill file requires YAML frontmatter with `name` and `description`:
+
+```markdown
+---
+name: {skill-name}
+description: {One sentence describing trigger conditions. Be specific so Claude can determine when to activate.}
+---
+
+# {Skill Title}
+
+{Brief description of what the skill does and when to use it.}
+```
+
+Key frontmatter rules:
+- `name` must match the directory name
+- `description` is the primary trigger mechanism — Claude uses it to decide whether to load the skill. Write it to describe *when* to use the skill, not just what it is
+- Keep SKILL.md under 500 lines; move reference material to `references/`
+
+## Marketplace Configuration
+
+The file `.claude-plugin/marketplace.json` defines which skills are published. Each plugin maps to a skill group:
+
+```json
+{
+  "name": "full-stack-skills",
+  "plugins": [
+    {
+      "name": "vue-skills",
+      "description": "...",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/vue-skills/vue2",
+        "./skills/vue-skills/vue3"
+      ]
+    }
+  ]
+}
+```
+
+**Important distinction**: `skills/` directory is the source of truth for what exists in the repo; `marketplace.json` is the source of truth for what is published. Currently 2 groups exist in-repo but are not published: `threejs-skills` (18 skills) and `vscode-skills` (4 skills). When adding new skills, update both the directory and marketplace.json together.
+
+The `docs/repository-map.md` tracks all known discrepancies between the directory and marketplace.
+
+## Cross-Platform Adapter (`fskill`)
+
+The `adapters/` directory contains a standalone TypeScript CLI (`fskill`) that exports skills for 43 platforms. It converts the repo's `skills/<group>/<skill>/` structure into standard skill directories placed in each platform's expected path.
+
+### Development Commands
+
+```bash
+# Install the CLI globally from the adapters directory
+npm install -g ./adapters
+
+# Or for local development
+cd adapters && npm install && npm link
+
+# Build TypeScript
+cd adapters && npm run build
+
+# Audit skill counts and integrity
+fskill audit
+
+# List all 43 supported platforms
+fskill platforms
+
+# Export skills for all platforms (dry-run first)
+fskill convert --platform all --output ./adapters-output --dry-run
+fskill convert --platform all --output ./adapters-output
+
+# Export for a single platform
+fskill convert --platform claude-code --output ./adapters-output
+
+# Install to current project (defaults to .agents/skills/)
+fskill install
+
+# Install to specific platform with scope
+fskill install --platform cursor --scope project
+fskill install --platform antigravity --scope global
+```
+
+### Adapter source files:
+- `adapters/src/index.ts` — CLI entry point
+- `adapters/src/platform-registry.ts` — 43-platform path matrix
+- `adapters/src/skills.ts` — skill discovery and audit logic
+
+## Key Documentation Files
+
+- `README.md` — Full project README (Chinese, with marketplace tables, installation guides, scenario-based install paths)
+- `README_EN.md` — English README
+- `AGENTS.md` — Guidance for AI agents working in this repo (skill creation rules, directory conventions, zip packaging)
+- `AGENTS_EN.md` — English version of AGENTS.md
+- `AGENTS_PROMPT.md` — Role definitions and agent prompts for 50+ roles (product manager, architect, developer, etc.)
+- `ROLE_DEFINITIONS.md` — Structured role definitions with responsibilities, tools, and skill assignments
+- `PLATFORM_GUIDE.md` — Complete platform matrix with install paths for all 43 platforms
+- `QUICKSTART.md` — 5-minute marketplace setup guide for users forking this repo
+- `PLANNING_SKILL_CATEGORIES.md` — Skill category planning and classification
+- `docs/repository-map.md` — Canonical snapshot of repo structure vs. marketplace state
+- `docs/skill-group-mapping.md` — Mapping of skills to groups
+- `docs/pipeline-stage-to-skills.md` — Pipeline stage (requirements → design → dev → test → deploy) to skills mapping
+- `docs/skills-ecosystem.md` — Overview of the broader skills ecosystem across related repos
+
+## Adding a New Skill
+
+1. Create `skills/<group>-skills/<skill-name>/SKILL.md` with proper frontmatter
+2. Add optional subdirectories (`references/`, `scripts/`, `examples/`, `assets/`)
+3. If the group plugin already exists in `marketplace.json`, append the skill path to its `skills` array
+4. If it's a new group, add both the plugin entry in `marketplace.json` and update `docs/repository-map.md`
+5. Run `fskill audit` to verify the skill is discoverable
+6. Update README snapshot numbers if counts changed
+
+## Important Constraints
+
+- `skills/pencil-skills/docs/` is treated as supporting documentation, not a skill directory — excluded from conversion
+- The `.gitignore` excludes `.DS_Store`, `__pycache__/`, `.idea/`, `.vscode/`
+- License: Apache 2.0 (repo-level), but `skills/document-skills/{docx,pptx,pdf,xlsx}` are source-available, not open source
+- Skills use progressive disclosure: SKILL.md should be concise, reference material goes in separate files
+- Script paths in SKILL.md should use the absolute mount path format: `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

PLANNING_SKILL_CATEGORIES.md

@@ -210,6 +210,7 @@ Marketplace (full-stack-skills)
 - `mermaid` - Mermaid 图表绘制（已存在）
 - `drawio-flowchart` - Draw.io 流程图绘制指南
 - `processon-mindmap` - ProcessOn 思维导图指南
+- `processon-diagram-generator` - ProcessOn 智能图表生成（流程图、架构图、时序图等）
 
 ---
 

README.md

@@ -6,7 +6,7 @@
 
 ![Version](https://img.shields.io/badge/Version-0.0.1-red)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green)
-![Skill Docs](https://img.shields.io/badge/SKILL.md-421-orange)
+![Skill Docs](https://img.shields.io/badge/SKILL.md-422-orange)
 ![Skill Groups](https://img.shields.io/badge/Groups-42-blue)
 ![Marketplace Plugins](https://img.shields.io/badge/Plugins-40-brightgreen)
 
@@ -18,7 +18,7 @@
 
 > **⚠️ 注意：** 当前文档口径以仓库内 `skills/` 实际目录和 `.claude-plugin/marketplace.json` 为准。
 
-> **说明：** 当前仓库内共有 **42 个技能组目录**、**421 个 `SKILL.md` 文件**；其中 Marketplace 当前发布 **40 个插件**、共 **410 条技能路径**。未进入 Marketplace 的仓库内技能组为 `threejs-skills` 与 `vscode-skills`。
+> **说明：** 当前仓库内共有 **42 个技能组目录**、**422 个 `SKILL.md` 文件**；其中 Marketplace 当前发布 **40 个插件**、共 **411 条技能路径**。未进入 Marketplace 的仓库内技能组为 `threejs-skills` 与 `vscode-skills`。
 
 ## ⚡ 5 分钟安装与转换示例
 
@@ -127,9 +127,9 @@ Skills 是由说明、脚本和资源组成的文件夹，Claude 会按需动态
 | 指标 | 当前值 |
 |---|---:|
 | `skills/` 下技能组目录 | 42 |
-| 仓库内 `SKILL.md` 文件 | 421 |
+| 仓库内 `SKILL.md` 文件 | 422 |
 | Marketplace 插件数 | 40 |
-| Marketplace 技能路径数 | 410 |
+| Marketplace 技能路径数 | 411 |
 | 仓库内未发布技能组 | 2 |
 
 ### ✨ 核心特性
@@ -137,7 +137,7 @@ Skills 是由说明、脚本和资源组成的文件夹，Claude 会按需动态
 #### 1. 分组式组织
 - **42 个技能组目录**：按领域、框架和工作流拆分，便于维护与扩展
 - **40 个 Marketplace 插件**：按技能组发布，便于按需安装与组合使用
-- **421 个 `SKILL.md` 文件**：沉淀可复用的 Agent Skills 资产
+- **422 个 `SKILL.md` 文件**：沉淀可复用的 Agent Skills 资产
 
 #### 2. 全链路覆盖
 - **前端与 UI**：Vue、React、Angular、Svelte、各类 UI 组件库与构建工具
@@ -176,7 +176,7 @@ Skills 是由说明、脚本和资源组成的文件夹，Claude 会按需动态
 
 - `threejs-skills` 当前在仓库中包含 18 个技能，但未进入 Marketplace 发布面。
 - `vscode-skills` 当前在仓库中包含 4 个技能，但未进入 Marketplace 发布面。
-- `document-skills` 当前目录中有 6 个技能（含 `full-stack-doc`），而 Marketplace 仍引用 10 个条目，其中 `docx`、`pptx`、`pdf`、`xlsx` 为缺失目录引用。
+- `document-skills` 当前目录中有 7 个技能（含 `full-stack-doc`、`processon-diagram-generator`），而 Marketplace 仍引用 11 个条目，其中 `docx`、`pptx`、`pdf`、`xlsx` 为缺失目录引用。
 - `tauri-skills` 当前目录中有 52 个技能，而 Marketplace 当前发布 51 个条目；`tauri-app-updater` 目前仅存在于仓库目录中。
 
 ### 阅读路径建议
@@ -262,9 +262,9 @@ full-stack-skills/
 | 项目 | 当前值 |
 |---|---:|
 | 技能组目录 | 42 |
-| `SKILL.md` 文件 | 421 |
+| `SKILL.md` 文件 | 422 |
 | Marketplace 插件 | 40 |
-| Marketplace 技能路径 | 410 |
+| Marketplace 技能路径 | 411 |
 | 仓库内未发布技能组 | 2 |
 
 ### 免责声明
@@ -477,7 +477,7 @@ fskill install
 | `dev-utils-skills` | 12 | 是 | 12 | 已与当前发布面对应；`full-stack-doc` 已迁至 `document-skills` |
 | `devops-skills` | 6 | 是 | 6 | 已与当前发布面对应 |
 | `docker-skills` | 2 | 是 | 2 | 已与当前发布面对应 |
-| `document-skills` | 6 | 是 | 10 | 目录技能数与 Marketplace 引用数不一致（含缺失的 docx/pptx/pdf/xlsx），详见 repository-map |
+| `document-skills` | 7 | 是 | 11 | 目录技能数与 Marketplace 引用数不一致（含缺失的 docx/pptx/pdf/xlsx），详见 repository-map |
 | `drawio-skills` | 2 | 是 | 2 | 已与当前发布面对应 |
 | `electron-skills` | 3 | 是 | 3 | 已与当前发布面对应 |
 | `flutter-skills` | 2 | 是 | 2 | 已与当前发布面对应 |

README_EN.md

@@ -4,7 +4,7 @@ A grouped Agent Skills repository for Claude Code, Claude.ai, and compatible Age
 
 ![Version](https://img.shields.io/badge/Version-0.0.1-red)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green)
-![Skill%20Docs](https://img.shields.io/badge/SKILL.md-421-orange)
+![Skill%20Docs](https://img.shields.io/badge/SKILL.md-422-orange)
 ![Skill%20Groups](https://img.shields.io/badge/Groups-42-blue)
 ![Marketplace%20Plugins](https://img.shields.io/badge/Plugins-40-brightgreen)
 
@@ -99,7 +99,7 @@ Skills are folders of instructions, scripts, and resources that Claude loads dyn
 
 ## About This Repository
 
-This repository is PartMeAI’s grouped Agent Skills catalog. The current repository snapshot contains **42** skill-group directories and **421** `SKILL.md` files. `.claude-plugin/marketplace.json` currently publishes **40** plugins with **410** skill paths.
+This repository is PartMeAI’s grouped Agent Skills catalog. The current repository snapshot contains **42** skill-group directories and **422** `SKILL.md` files. `.claude-plugin/marketplace.json` currently publishes **40** plugins with **411** skill paths.
 
 The main repo now covers frontend, backend, mobile, cross-platform development, testing, DevOps, documentation, OCR, Tauri, Stitch, Pencil, T2UI, OpenSpec, and Spec Kit workflows.
 
@@ -108,9 +108,9 @@ The main repo now covers frontend, backend, mobile, cross-platform development,
 | Metric | Current Value |
 |---|---:|
 | Skill-group directories under `skills/` | 42 |
-| `SKILL.md` files on disk | 421 |
+| `SKILL.md` files on disk | 422 |
 | Plugins in `.claude-plugin/marketplace.json` | 40 |
-| Published skill refs in Marketplace | 410 |
+| Published skill refs in Marketplace | 411 |
 | Repo-only groups not published | 2 |
 
 ### Coverage Map

docs/repository-map.md

@@ -5,8 +5,8 @@
 ## 一、当前仓库概况
 
 - `skills/` 下共有 **42** 个技能组目录。
-- 仓库内共检出 **421** 个 `SKILL.md` 文件。
-- Marketplace 当前配置了 **40** 个插件，合计 **410** 个技能路径。
+- 仓库内共检出 **422** 个 `SKILL.md` 文件。
+- Marketplace 当前配置了 **40** 个插件，合计 **411** 个技能路径。
 - 已发布插件组：angular-skills、antd-skills、ascii-skills、avue-skills、build-skills、chart-skills、cocos-skills、database-skills、ddd-skills、design-skills、dev-utils-skills、devops-skills、docker-skills、document-skills、drawio-skills、electron-skills、flutter-skills、go-skills、mobile-native-skills、nodejs-skills、nvm-skills、ocrmypdf-skills、openspec-skills、pencil-skills、python-skills、react-skills、social-skills、speckit-skills、spring-skills、stitch-skills、svelte-skills、t2ui-skills、tauri-skills、teaching-skills、testing-skills、uniapp-skills、utility-skills、uview-skills、vue-skills、vue-ui-skills。
 - 文档入口建议优先查看：`README.md`、`docs/skill-group-mapping.md`、`docs/pipeline-stage-to-skills.md`、本文件。
 
@@ -47,7 +47,7 @@ full-stack-skills/
 | `dev-utils-skills` | 12 | 12 | 已发布 | `full-stack-doc` 已迁至 `document-skills` |
 | `devops-skills` | 6 | 6 | 已发布 | — |
 | `docker-skills` | 2 | 2 | 已发布 | — |
-| `document-skills` | 6 | 10 | 已发布 | 含 `full-stack-doc`；仍缺目录：docx、pptx、pdf、xlsx |
+| `document-skills` | 7 | 11 | 已发布 | 含 `full-stack-doc`、`processon-diagram-generator`；仍缺目录：docx、pptx、pdf、xlsx |
 | `drawio-skills` | 2 | 2 | 已发布 | — |
 | `electron-skills` | 3 | 3 | 已发布 | — |
 | `flutter-skills` | 2 | 2 | 已发布 | — |
@@ -85,7 +85,7 @@ full-stack-skills/
 
 ## 五、当前一致性说明
 
-- Marketplace 当前声明 410 个技能路径，其中 406 个可在仓库中直接解析。
+- Marketplace 当前声明 411 个技能路径，其中 407 个可在仓库中直接解析。
 - `document-skills` 当前存在未落地目录引用：`docx`、`pptx`、`pdf`、`xlsx`。
 - `tauri-skills` 目录下已有技能尚未纳入 Marketplace：`tauri-app-updater`。
 

docs/skill-group-mapping.md

@@ -32,7 +32,7 @@
 | **chart-skills** | lime-echart, ucharts | 2 | 图表组件 |
 | **dev-utils-skills** | code-generator, test-writer, java-code-comments, mybatis-plus-generator, documentation-builder, mcp-builder, webapp-testing, frontend-design, web-artifacts-builder, theme-factory, agent-browser, maven-search | 12 | 开发工具链（与 development-skills-utils 对应） |
 | **design-skills** | algorithmic-art, brand-guidelines, canvas-design, figma, figma-ai, sketch, adobe-xd, dalle, uizard, galileo-ai, runway-ml, framer | 12 | 设计与 AI 绘图（midjourney/stable-diffusion/axure/modao 待补目录则入本组） |
-| **document-skills** | docx, pptx, pdf, xlsx, doc-coauthoring, api-doc-generator, full-stack-doc, processon-mindmap, mermaid, plantuml | 10 | 文档与图表（与 document 插件对应） |
+| **document-skills** | docx, pptx, pdf, xlsx, doc-coauthoring, api-doc-generator, full-stack-doc, processon-mindmap, processon-diagram-generator, mermaid, plantuml | 11 | 文档与图表（与 document 插件对应） |
 | **testing-skills** | jest, vitest, pytest, junit, cypress, playwright, selenium, appium, detox | 9 | 测试框架与 E2E/移动端测试 |
 | **devops-skills** | gitlab-ci, github-actions, kubernetes, terraform, ansible, cloudformation | 6 | CI/CD 与 IaC（jenkins 待补目录则入本组） |
 | **database-skills** | postgresql, oracle, redis, elasticsearch, dbeaver | 5 | 数据库与工具（mysql/mongodb/navicat 待补目录则入本组） |

skills/avue-skills/avue-form/SKILL.md

@@ -1,33 +1,121 @@
 ---
 name: avue-form
-description: "Builds configuration-driven dynamic forms with Avue Form, including field types (input, select, date, upload), validation rules, form groups, tabbed layouts, and event handling. Use when the user needs to create forms with Avue in Vue applications, implement form validation, or build dynamic multi-step forms."
+description: Provides comprehensive guidance for Avue Form component including form configuration, validation, and dynamic forms. Use when the user asks about Avue Form, needs to create dynamic forms, implement form validation, or work with form configurations.
 license: Complete terms in LICENSE.txt
 ---
 
 ## When to use this skill
 
 Use this skill whenever the user wants to:
-- Create configuration-driven forms with Avue Form
-- Define form fields with types (input, select, date, checkbox, upload, etc.)
-- Implement form validation rules
-- Build dynamic forms, form groups, or tabbed form layouts
-- Handle form submit, reset, and field change events
+- Install and set up Avue-form in a Vue project
+- Use Avue-form components in Vue applications
+- Configure form options and columns
+- Handle form validation
+- Use form events and methods
+- Customize form components
+- Understand Avue-form API and methods
+- Troubleshoot Avue-form issues
 
 ## How to use this skill
 
-### Workflow
+This skill is organized to match the Avue-form official documentation structure (https://avuejs.com/form/form-doc.html). When working with Avue-form:
+
+1. **Identify the topic** from the user's request:
+   - Installation/安装 → `examples/components/installation.md`
+   - Basic Usage/基础用法 → `examples/components/basic-usage.md`
+   - Configuration/配置 → `examples/components/configuration.md`
+   - Features/功能特性 → `examples/features/`
+   - API/API 文档 → `api/`
+
+2. **Load the appropriate example file** from the `examples/` directory:
+
+   **Components (组件)**:
+   - `examples/components/intro.md` - Introduction to Avue-form
+   - `examples/components/installation.md` - Installation guide
+   - `examples/components/basic-usage.md` - Basic usage
+   - `examples/components/configuration.md` - Configuration
+   - `examples/components/options.md` - Form options
+   - `examples/components/columns.md` - Form columns
+   - `examples/components/validation.md` - Form validation
+   - `examples/components/events.md` - Form events
+   - `examples/components/methods.md` - Form methods
+
+   **Features (功能特性)**:
+   - `examples/features/dynamic-form.md` - Dynamic form
+   - `examples/features/form-layout.md` - Form layout
+   - `examples/features/form-rules.md` - Form rules
+   - `examples/features/form-submit.md` - Form submit
+   - `examples/features/form-reset.md` - Form reset
+   - `examples/features/custom-components.md` - Custom components
+   - `examples/features/form-group.md` - Form group
+   - `examples/features/form-tabs.md` - Form tabs
+
+3. **Follow the specific instructions** in that example file for syntax, structure, and best practices
+
+   **Important Notes**:
+   - Avue-form is based on Vue
+   - Components use Vue syntax
+   - Examples include both Options API and Composition API
+   - Each example file includes key concepts, code examples, and key points
+
+4. **Reference API documentation** in the `api/` directory when needed:
+   - `api/form-api.md` - Form component API
+   - `api/options-api.md` - Options API
+   - `api/columns-api.md` - Columns API
+   - `api/events-api.md` - Events API
+   - `api/methods-api.md` - Methods API
+
+5. **Use templates** from the `templates/` directory:
+   - `templates/installation.md` - Installation templates
+   - `templates/basic-form.md` - Basic form templates
+   - `templates/configuration.md` - Configuration templates
+
+### 1. Understanding Avue-form
+
+Avue-form is a Vue form component library that provides rich form controls and configuration options.
+
+**Key Concepts**:
+- **Form Component**: Main form component
+- **Options**: Form configuration options
+- **Columns**: Form field definitions
+- **Validation**: Form validation rules
+- **Events**: Form events
+- **Methods**: Form methods
+
+### 2. Installation
+
+**Using npm**:
+
+```bash
+npm install @smallwei/avue
+```
+
+**Using yarn**:
+
+```bash
+yarn add @smallwei/avue
+```
+
+**Using pnpm**:
+
+```bash
+pnpm add @smallwei/avue
+```
+
+### 3. Basic Setup
 
-1. **Install** - `npm install @avue/form` and register with `Vue.use(Avue)`
-2. **Define option** - Configure columns with labels, props, types, and rules
-3. **Bind v-model** - Two-way bind the form data object
-4. **Handle events** - Listen for @submit, @reset-change, and field-level events
+```javascript
+// main.js
+import Vue from 'vue'
+import Avue from '@smallwei/avue'
+import '@smallwei/avue/lib/theme-default/index.css'
 
-### Quick-Start Example: Form with Validation
+Vue.use(Avue)
+```
 
 ```vue
 <template>
-  <avue-form :option="option" v-model="form" @submit="handleSubmit" @reset-change="handleReset">
-  </avue-form>
+  <avue-form :option="option" v-model="form"></avue-form>
 </template>
 
 <script>
@@ -36,78 +124,90 @@ export default {
     return {
       form: {},
       option: {
-        submitText: 'Save',
         column: [
           {
             label: 'Name',
             prop: 'name',
-            type: 'input',
-            span: 12,
-            rules: [{ required: true, message: 'Name is required', trigger: 'blur' }]
-          },
-          {
-            label: 'Role',
-            prop: 'role',
-            type: 'select',
-            span: 12,
-            dicData: [
-              { label: 'Admin', value: 'admin' },
-              { label: 'User', value: 'user' }
-            ]
-          },
-          {
-            label: 'Start Date',
-            prop: 'startDate',
-            type: 'date',
-            format: 'yyyy-MM-dd'
+            type: 'input'
           }
         ]
       }
     }
-  },
-  methods: {
-    handleSubmit(form, done) {
-      console.log('Form data:', form)
-      // Call API, then done() to re-enable button
-      done()
-    },
-    handleReset() {
-      console.log('Form reset')
-    }
   }
 }
 </script>
 ```
 
-### Feature Reference
 
-| Feature | File |
-|---------|------|
-| Dynamic form | `examples/features/dynamic-form.md` |
-| Form layout | `examples/features/form-layout.md` |
-| Validation rules | `examples/features/form-rules.md` |
-| Form groups | `examples/features/form-group.md` |
-| Tabbed forms | `examples/features/form-tabs.md` |
-| Custom components | `examples/features/custom-components.md` |
+### Doc mapping (one-to-one with official documentation)
+
+- `examples/` → https://avuejs.com/form/form-doc.html
+
+## Examples and Templates
+
+This skill includes detailed examples organized to match the official documentation structure. All examples are in the `examples/` directory (see mapping above).
+
+**To use examples:**
+- Identify the topic from the user's request
+- Load the appropriate example file from the mapping above
+- Follow the instructions, syntax, and best practices in that file
+- Adapt the code examples to your specific use case
+
+**To use templates:**
+- Reference templates in `templates/` directory for common scaffolding
+- Adapt templates to your specific needs and coding style
+
+## API Reference
+
+Detailed API documentation is available in the `api/` directory, organized to match the official Avue-form API documentation structure:
+
+### Form Component API (`api/form-api.md`)
+- Form component props
+- Form component events
+- Form component slots
+
+### Options API (`api/options-api.md`)
+- Form options configuration
+- Option properties
+- Option methods
+
+### Columns API (`api/columns-api.md`)
+- Column definitions
+- Column properties
+- Column types
+
+### Events API (`api/events-api.md`)
+- Form events
+- Event handlers
+- Event parameters
 
-### API Reference
+### Methods API (`api/methods-api.md`)
+- Form methods
+- Method parameters
+- Method return values
 
-- `api/form-api.md` - Component props, events, and slots
-- `api/columns-api.md` - Column types and properties
-- `api/options-api.md` - Form option configuration
+**To use API reference:**
+1. Identify the API you need help with
+2. Load the corresponding API file from the `api/` directory
+3. Find the API signature, parameters, return type, and examples
+4. Reference the linked example files for detailed usage patterns
+5. All API files include links to relevant example files in the `examples/` directory
 
 ## Best Practices
 
-1. **Use column types** - Set `type: 'select'`, `type: 'date'`, `type: 'upload'` for automatic controls
-2. **Call done() after submit** - Always call `done()` in the submit handler to re-enable the button
-3. **Use span for layout** - Set `span: 12` for half-width fields (24 = full width grid)
-4. **Group related fields** - Use `group` option to organize complex forms into sections
-5. **Validate on blur** - Set `trigger: 'blur'` for a less intrusive validation experience
+1. **Configure options properly**: Set up form options correctly
+2. **Define columns clearly**: Define form columns with proper types
+3. **Handle validation**: Use validation rules appropriately
+4. **Handle events**: Use form events for interactions
+5. **Use methods**: Leverage form methods for operations
+6. **Customize components**: Customize components when needed
+7. **Follow Vue patterns**: Follow Vue.js best practices
 
 ## Resources
 
-- **Official Docs**: https://avuejs.com/form/form-doc.html
+- **Official Documentation**: https://avuejs.com/form/form-doc.html
+- **GitHub Repository**: https://github.com/avue/avue
 
 ## Keywords
 
-Avue Form, avue-form, Vue form, dynamic form, 表单组件, 表单验证, form validation, form configuration, form columns, form rules
+Avue-form, avue-form, @avue/form, Vue form, form component, 表单组件, 表单配置, 表单验证, 表单事件, 表单方法, form options, form columns, form validation, form events, form methods, dynamic form, form layout, form rules, form submit, form reset, custom components, form group, form tabs

skills/avue-skills/avue-form/examples/components/installation.md

@@ -18,13 +18,13 @@ This example demonstrates how to install Avue-form.
 
 ```bash
 # Using npm
-npm install @avue/form
+npm install @smallwei/avue
 
 # Using yarn
-yarn add @avue/form
+yarn add @smallwei/avue
 
 # Using pnpm
-pnpm add @avue/form
+pnpm add @smallwei/avue
 ```
 
 ### Example: Global Registration
@@ -32,8 +32,8 @@ pnpm add @avue/form
 ```javascript
 // main.js
 import Vue from 'vue'
-import Avue from '@avue/form'
-import '@avue/form/lib/theme-default/index.css'
+import Avue from '@smallwei/avue'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 Vue.use(Avue)
 ```
@@ -42,10 +42,10 @@ Vue.use(Avue)
 
 ```javascript
 // Import default theme
-import '@avue/form/lib/theme-default/index.css'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 // Or import custom theme
-import '@avue/form/lib/theme-custom/index.css'
+import '@smallwei/avue/lib/theme-custom/index.css'
 ```
 
 ### Example: Complete Setup
@@ -54,8 +54,8 @@ import '@avue/form/lib/theme-custom/index.css'
 // main.js
 import Vue from 'vue'
 import App from './App.vue'
-import Avue from '@avue/form'
-import '@avue/form/lib/theme-default/index.css'
+import Avue from '@smallwei/avue'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 Vue.use(Avue)
 
@@ -66,7 +66,7 @@ new Vue({
 
 ### Key Points
 
-- Install @avue/form package
+- Install @smallwei/avue package
 - Register globally with Vue.use()
 - Import CSS styles
 - Ready to use in components

skills/avue-skills/avue-form/templates/installation.md

@@ -3,7 +3,7 @@
 ## npm Installation
 
 ```bash
-npm install @avue/form
+npm install @smallwei/avue
 ```
 
 ## Global Registration
@@ -11,8 +11,8 @@ npm install @avue/form
 ```javascript
 // main.js
 import Vue from 'vue'
-import Avue from '@avue/form'
-import '@avue/form/lib/theme-default/index.css'
+import Avue from '@smallwei/avue'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 Vue.use(Avue)
 ```
@@ -21,10 +21,10 @@ Vue.use(Avue)
 
 ```javascript
 // Import default theme
-import '@avue/form/lib/theme-default/index.css'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 // Or import custom theme
-import '@avue/form/lib/theme-custom/index.css'
+import '@smallwei/avue/lib/theme-custom/index.css'
 ```
 
 ## Complete Setup
@@ -33,8 +33,8 @@ import '@avue/form/lib/theme-custom/index.css'
 // main.js
 import Vue from 'vue'
 import App from './App.vue'
-import Avue from '@avue/form'
-import '@avue/form/lib/theme-default/index.css'
+import Avue from '@smallwei/avue'
+import '@smallwei/avue/lib/theme-default/index.css'
 
 Vue.use(Avue)
 

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,234 @@
+---
+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: 对任意 Agent Skill 做 TRACE 五维度评测（T/R/A/C/E），输出 Markdown/HTML 报告与雷达图；当用户要求“TRACE 评测/打分/生成 TRACE 报告/五维度评估”或需要改进建议时使用。
+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/chart-skills/lime-echart/examples/getting-started/installation.md

@@ -13,17 +13,13 @@ lime-echart 是为 UniApp 和 UniAppX 提供 ECharts 图表兼容支持的插件
 2. 点击"使用 HBuilderX 导入插件"或下载插件
 3. 将插件导入到项目的 `uni_modules` 目录
 
-### 方式二：通过 npm 安装
+### 方式二：通过 npm 安装 ECharts 依赖
 
 ```bash
 npm install echarts --save
 ```
 
-然后从插件市场下载 lime-echart 插件，或使用 npm：
-
-```bash
-npm install lime-echart --save
-```
+然后从 [DCloud 插件市场](https://ext.dcloud.net.cn/plugin?id=4899) 下载 lime-echart 插件，放入 `uni_modules` 目录。
 
 ### 方式三：手动安装
 

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,63 +0,0 @@
----
-name: dbeaver
-description: "Guides DBeaver usage for database connection management, SQL development, data import/export, and ER diagram generation across MySQL, PostgreSQL, Oracle, MongoDB, and other databases. Use when the user needs to configure DBeaver connections, write queries in the SQL editor, export data, or generate ER diagrams."
-license: Complete terms in LICENSE.txt
----
-
-## When to use this skill
-
-Use this skill whenever the user wants to:
-- Configure DBeaver database connections (MySQL, PostgreSQL, Oracle, MongoDB, etc.)
-- Write and execute SQL queries in the DBeaver SQL editor
-- Export data to CSV, JSON, SQL, or Excel formats
-- Import data from files into database tables
-- Generate ER diagrams to visualize table relationships
-- Manage multiple database connections, bookmarks, and drivers
-
-## How to use this skill
-
-### Workflow
-
-1. **Create a connection** - New Connection > Select database type > Configure host/port/credentials > Test Connection
-2. **Write SQL** - Open SQL Editor (F3) > Write query > Execute (Ctrl+Enter)
-3. **Manage data** - Right-click table > Export Data or Import Data > Choose format
-4. **Generate ER diagram** - Right-click schema > View Diagram > Arrange tables
-
-### Quick-Start Example: Connect and Query
-
-```
-1. File > New > Database Connection
-2. Select "PostgreSQL" > Enter:
-   Host: localhost
-   Port: 5432
-   Database: mydb
-   Username: admin
-   Password: ****
-3. Click "Test Connection" to verify
-4. Open SQL Editor (F3), run:
-   SELECT table_name, pg_size_pretty(pg_total_relation_size(table_name::text))
-   FROM information_schema.tables
-   WHERE table_schema = 'public'
-   ORDER BY pg_total_relation_size(table_name::text) DESC;
-```
-
-### Data Export
-
-```
-Right-click table > Export Data >
-  Format: CSV / JSON / SQL INSERT / Excel
-  Options: Set delimiter, encoding, header row
-  Target: File or clipboard
-```
-
-## Best Practices
-
-1. **Driver management** - DBeaver auto-downloads drivers on first connect; update drivers periodically
-2. **Secure credentials** - Enable encrypted password storage in connection properties
-3. **Transaction mode** - Switch to manual commit in production to prevent accidental changes
-4. **Result set navigation** - Use filters, sorting, and pagination for large result sets
-5. **Keyboard shortcuts** - Ctrl+Enter to execute, Ctrl+Shift+E to explain plan, F3 for SQL editor
-
-## Keywords
-
-dbeaver, database, SQL, PostgreSQL, MySQL, Oracle, MongoDB, 数据库管理, SQL editor, ER diagram, data export, data import, database tool

skills/database-skills/elasticsearch/SKILL.md

@@ -1,77 +1,199 @@
 ---
 name: elasticsearch
-description: "Guides Elasticsearch usage including index mapping design, query DSL (match, term, bool, aggregations), bulk indexing, cluster management, and performance tuning. Use when the user needs to implement full-text search, design index mappings, write complex search 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
-
-Use this skill whenever the user wants to:
-- Design index mappings with analyzers and field types
-- Write search queries (match, term, bool, multi_match, nested, aggregations)
-- Index, update, or bulk-load documents via the REST API
-- Manage clusters (shards, replicas, snapshots, upgrades)
-- Integrate Elasticsearch with Kibana or Logstash (ELK stack)
-
-## How to use this skill
-
-### Workflow
-
-1. **Design the mapping** - Define field types, analyzers, and index settings
-2. **Index documents** - Use PUT/POST or bulk API
-3. **Write queries** - Use Query DSL with filters for caching
-4. **Monitor and tune** - Check cluster health, slow logs, and shard balance
-
-### Quick-Start Example: Create Index and Search
-
-```json
-// Create index with mapping
-PUT /products
-{
-  "mappings": {
-    "properties": {
-      "name":        { "type": "text", "analyzer": "standard" },
-      "description": { "type": "text" },
-      "price":       { "type": "float" },
-      "category":    { "type": "keyword" },
-      "created_at":  { "type": "date" }
-    }
-  }
-}
-
-// Index a document
-POST /products/_doc
-{
-  "name": "Wireless Mouse",
-  "description": "Ergonomic wireless mouse with USB-C receiver",
-  "price": 29.99,
-  "category": "electronics",
-  "created_at": "2025-01-15"
-}
-
-// Search with bool query and aggregation
-GET /products/_search
-{
-  "query": {
-    "bool": {
-      "must": [{ "match": { "description": "wireless" } }],
-      "filter": [{ "range": { "price": { "lte": 50 } } }]
-    }
-  },
-  "aggs": {
-    "by_category": { "terms": { "field": "category" } }
-  }
-}
+# Elasticsearch — 分布式搜索与分析引擎
+
+Elasticsearch 是基于 Apache Lucene 的分布式搜索和分析引擎，提供近实时的全文搜索、结构化搜索、聚合分析、地理空间查询和向量搜索能力。
+
+## Workflow — 从数据到搜索的 5 步决策流程
+
+```
+遇到 ES 相关需求时按以下顺序决策:
+
+Step 1: 明确场景
+├── 全文搜索?                    → Step 2
+├── 结构化数据分析 (日志/指标)?   → Step 2
+├── 向量/KNN 搜索?               → references/ 向量搜索
+├── 地理空间查询?                 → references/ 地理查询
+├── 集群运维/性能问题?             → references/ 07-cluster-ops
+└── 数据管道/日志采集?             → references/ 08-elk-integration
+
+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
 ```
 
-## Best Practices
+## 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 |
+
+## 集群运维概述
 
-1. **Define explicit mappings** - Avoid dynamic mapping in production; set `dynamic: strict` to catch errors
-2. **Use filters for exact matches** - Filters are cached and faster than queries for keyword/range conditions
-3. **Paginate with search_after** - Avoid deep `from`/`size` pagination; use `search_after` for large result sets
-4. **Plan shards carefully** - Target 20-40 GB per shard; avoid too many small shards
-5. **Snapshot regularly** - Use snapshot/restore for backups; test restore procedures
+| 运维领域 | 关键要点 | 深度参考 |
+|---------|---------|---------|
+| **节点类型** | 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, mapping, query DSL, aggregation, 搜索引擎, 全文检索, 聚合, ELK, Kibana, bulk API, cluster
+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,75 +1,238 @@
 ---
 name: oracle
-description: "Guides Oracle database development including SQL, PL/SQL stored procedures, triggers, EXPLAIN PLAN optimization, AWR analysis, RMAN backup, RAC clustering, and Data Guard. Use when the user needs to write Oracle SQL, create PL/SQL procedures, tune query performance, or manage Oracle database administration."
+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
-
-Use this skill whenever the user wants to:
-- Write Oracle SQL or PL/SQL (stored procedures, functions, triggers, packages)
-- Design tables, indexes, partitions, or constraints in Oracle
-- Tune query performance with EXPLAIN PLAN, AWR, or ASH reports
-- Manage Oracle administration (users, roles, tablespaces, RMAN backup)
-- Configure RAC, Data Guard, or Oracle replication
-
-## How to use this skill
-
-### Workflow
-
-1. **Identify the task** - SQL writing, PL/SQL development, performance tuning, or DBA operations
-2. **Write the code** - Use the patterns below matching Oracle syntax
-3. **Analyze performance** - Run EXPLAIN PLAN or review AWR snapshots
-4. **Apply Oracle-specific best practices** - Bind variables, partitioning, RMAN
-
-### Quick-Start Example: PL/SQL Procedure with Error Handling
-
-```sql
-CREATE OR REPLACE PROCEDURE transfer_funds(
-    p_from_acct  IN NUMBER,
-    p_to_acct    IN NUMBER,
-    p_amount     IN NUMBER
-) AS
-    v_balance NUMBER;
-BEGIN
-    -- Check source balance
-    SELECT balance INTO v_balance
-    FROM accounts WHERE account_id = p_from_acct
-    FOR UPDATE;
-
-    IF v_balance < p_amount THEN
-        RAISE_APPLICATION_ERROR(-20001, 'Insufficient funds');
-    END IF;
-
-    UPDATE accounts SET balance = balance - p_amount WHERE account_id = p_from_acct;
-    UPDATE accounts SET balance = balance + p_amount WHERE account_id = p_to_acct;
-
-    COMMIT;
-EXCEPTION
-    WHEN OTHERS THEN
-        ROLLBACK;
-        RAISE;
-END transfer_funds;
-/
-```
+# Oracle Database — 企业级关系型数据库
 
-### Performance Analysis
+Oracle Database 是全球领先的企业级关系型数据库管理系统，以其高可用性、高性能、强安全性及丰富的功能集（RAC、Data Guard、Flashback、高级分区、物化视图等）著称。
 
-```sql
-EXPLAIN PLAN FOR
-SELECT /*+ INDEX(o idx_orders_date) */ * FROM orders o WHERE order_date > SYSDATE - 30;
+## Workflow — 使用决策树
 
-SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY);
 ```
+遇到 Oracle 相关需求时，按以下顺序决策:
+
+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
+
+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 读取一致性版本。
 
-## Best Practices
+**Q8: 死锁如何处理？**
+Oracle 3 秒内自动检测，回滚牺牲品语句并抛 ORA-00060。最佳实践：统一访问顺序、事务简短。
 
-1. **Use bind variables** - Prevent SQL injection and hard parsing; never concatenate user input into SQL
-2. **Partition large tables** - Range partition on date columns; hash partition for even distribution
-3. **RMAN backup strategy** - Full weekly + incremental daily; test restore procedures quarterly
-4. **Monitor wait events** - Use AWR/ASH to identify I/O, latch, or lock contention
-5. **Audit and secure** - Use Oracle Audit Vault; grant least-privilege roles; encrypt sensitive columns
+**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, SQL Developer, RMAN, RAC, Data Guard, AWR, 关系型数据库, stored procedure, EXPLAIN PLAN, tablespace, 索引, 分区
+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,72 +1,182 @@
 ---
 name: postgresql
-description: "Guides PostgreSQL development including table design, indexing, constraints, PL/pgSQL, JSONB, full-text search, window functions, CTEs, EXPLAIN ANALYZE tuning, backup/restore, replication, and extensions like pgvector. Use when the user needs to write or optimize PostgreSQL queries, design schemas, or manage 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
-
-Use this skill whenever the user wants to:
-- Design tables, indexes, constraints, triggers, or PL/pgSQL functions
-- Write or optimize SQL queries (joins, CTEs, window functions, aggregations)
-- Use PostgreSQL-specific features (JSONB, full-text search, array types, pgvector)
-- Manage users, roles, and permissions with psql
-- Configure backup (pg_dump), replication, or performance tuning (EXPLAIN ANALYZE)
-
-## How to use this skill
-
-### Workflow
-
-1. **Identify the task** - Schema design, query writing, optimization, or administration
-2. **Write the SQL** - Use the patterns and examples below
-3. **Analyze performance** - Run EXPLAIN ANALYZE on slow queries
-4. **Apply best practices** - Index strategy, VACUUM, partitioning as needed
-
-### Quick-Start Example: Table with Index and Query
-
-```sql
--- Create a table with constraints
-CREATE TABLE orders (
-    id          BIGSERIAL PRIMARY KEY,
-    customer_id BIGINT NOT NULL REFERENCES customers(id),
-    status      TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','shipped','delivered')),
-    total       NUMERIC(10,2) NOT NULL,
-    metadata    JSONB DEFAULT '{}',
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
--- Create an index for common queries
-CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);
-
--- Query with CTE and window function
-WITH monthly_totals AS (
-    SELECT customer_id,
-           date_trunc('month', created_at) AS month,
-           SUM(total) AS month_total
-    FROM orders
-    WHERE status = 'delivered'
-    GROUP BY customer_id, date_trunc('month', created_at)
-)
-SELECT customer_id, month, month_total,
-       LAG(month_total) OVER (PARTITION BY customer_id ORDER BY month) AS prev_month
-FROM monthly_totals;
-```
+# PostgreSQL — 高级关系型数据库系统
+
+## Workflow — 使用流程
+
+```text
+遇到 PostgreSQL 需求时，按以下顺序决策:
+
+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
+
+2. 确定模型: 关系型 → 标准表+B-Tree | JSON文档 → JSONB+GIN | 全文搜索 → tsvector+GIN | 地理 → PostGIS+GiST
 
-### Performance Analysis
+3. 索引策略: 等值→B-Tree | 范围→B-Tree | 全文→GIN | JSON→GIN | 向量→IVFFlat/HNSW | 大表时序→BRIN
 
-```sql
-EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
-SELECT * FROM orders WHERE customer_id = 42 AND status = 'pending';
+4. 数据量评估: <100GB→单实例 | 100GB-1TB→分区 | 1TB-10TB→分区+只读副本 | >10TB→Citus/逻辑复制
+
+5. 运维策略: autovacuum + pg_stat_statements + WAL归档 + PgBouncer
 ```
 
-## Best Practices
+## 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 无重试逻辑 | 事务冲突失败 | 应用层实现重试 |
 
-1. **Index strategically** - Create indexes for WHERE/JOIN columns; use partial indexes for filtered queries
-2. **Run VACUUM regularly** - Prevent table bloat; configure autovacuum thresholds for high-write tables
-3. **Partition large tables** - Use range partitioning on timestamp columns for tables over 100M rows
-4. **Use ROLE/GRANT** - Grant least privilege; never use superuser for application connections
-5. **Backup and verify** - Use `pg_dump` or WAL archiving; test restore procedures regularly
+## 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, SQL, JSONB, full-text search, CTE, window function, 关系型数据库, 索引, 复制, EXPLAIN ANALYZE, pg_dump, partitioning
+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, ...);
+```