mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-07-07 11:17:48 +02:00
Add Vietnamese (Tiếng Việt) Localization (#42)
* feat(i18n): add Vietnamese localization infrastructure Add comprehensive infrastructure for Vietnamese translation of the claude-howto documentation: Features: - Parallel vi/ directory structure for Vietnamese content - Modified build_epub.py with --lang flag for Vietnamese EPUB - Vietnamese-specific pre-commit hooks for quality checks - Translation support files (glossary, style guide, queue tracker) - sync_translations.py script to detect outdated translations Infrastructure: - vi/ directory with all 10 module subdirectories - TRANSLATION_NOTES.md: comprehensive glossary and style guide - TRANSLATION_QUEUE.md: progress tracking for 66+ files - vi/README.md: Vietnamese landing page EPUB Build: - Added --lang CLI flag (en/vi) to build_epub.py - Language-specific metadata (title, subtitle) - Automatic root path adjustment for vi/ directory - Dynamic output filename (claude-howto-guide-vi.epub) Quality Assurance: - Vietnamese markdown linting - Vietnamese cross-reference checking - Vietnamese Mermaid syntax validation - Vietnamese link checking - Vietnamese EPUB build validation Ready for translation work to begin. * feat(vi): translate INDEX.md to Vietnamese Complete Vietnamese translation of INDEX.md - the comprehensive index of all example files in the repository. Translation follows vi/TRANSLATION_NOTES.md guidelines: - Technical terms kept per glossary (slash command → "lệnh slash") - File paths and code blocks preserved in English - Table structure and formatting maintained - All 882 lines translated Content includes: - Complete file tree (10 modules, 100+ files) - Feature coverage matrix - Quick start guides by use case - Learning path progression - Search by keyword sections Progress: 1/5 core documents completed * feat(vi): translate CATALOG.md to Vietnamese Complete Vietnamese translation of CATALOG.md - the quick reference guide to all Claude Code features. Translation follows vi/TRANSLATION_NOTES.md guidelines: - Technical terms kept per glossary (slash command → "lệnh slash") - All command names preserved (/help, /optimize, etc.) - Code blocks, JSON examples, and bash commands unchanged - All tables and formatting maintained - 517 lines translated with complete feature coverage Content includes: - Summary statistics (99 built-in + 43 examples = 117 total) - Complete built-in commands reference (55+ commands) - Custom commands examples (8 commands) - Permission modes (6 modes) - Subagents (6 built-in + 10 custom) - Skills (5 bundled + 4 custom) - Plugins (3 complete plugins) - MCP servers (1 built-in + 8 common servers) - Hooks (25 events + 7 example hooks) - Memory files (7 types) - New features (March 2026) - 17 new features - Installation priority guide - Complete one-command installation Progress: 2/5 core documents completed * docs(vi): translate learning roadmap to Vietnamese - Add complete Vietnamese translation of LEARNING-ROADMAP.md (747 lines) - Include self-assessment quiz for level determination - Translate three learning levels: Beginner, Intermediate, Advanced - Translate all milestones (1A, 1B, 2A, 2B, 3A, 3B) with hands-on exercises - Preserve Mermaid diagram for learning path visualization - Maintain progress tracking checklists and learning tips * docs(vi): translate quick reference guide to Vietnamese - Add complete Vietnamese translation of QUICK_REFERENCE.md (507 lines) - Include installation quick commands for all features - Translate feature cheat sheet with usage examples - Translate common use cases (code review, documentation, DevOps, etc.) - Preserve all code snippets, commands, and file paths in English - Maintain file locations reference diagram - Include learning path and new features (March 2026) sections - Keep tips & tricks, feature matrix, and checklist intact * docs(vi): translate module 01 - slash commands to Vietnamese - Add complete Vietnamese translation of 01-slash-commands/README.md (553 lines) - Translate slash commands overview and architecture - Include 55+ built-in commands reference table with Vietnamese descriptions - Translate bundled skills section (5 skills) - Document custom commands (now skills) migration path - Include frontmatter reference, arguments, and dynamic context sections - Preserve all command names, code examples, and Mermaid diagrams - Translate 8 available commands in folder with usage examples - Include installation, troubleshooting, and best practices sections * docs(vi): update translation queue progress - Module 01 README done - Mark 01-slash-commands/README.md as completed (2026-04-02) - Update Module 01 progress: 1/9 files (11%) - Update overall progress: 6/66 files (9%) - Update Priority 2 progress: 1/31 files (3%) - Add recent completion note to queue header * docs(vi): translate slash command - commit to Vietnamese - Translate commit.md slash command to Vietnamese - Keep all git commands and technical syntax intact - Translate instructions and descriptions - Maintain conventional commits format documentation * docs(vi): translate slash command - doc-refactor to Vietnamese - Translate doc-refactor.md slash command to Vietnamese - Keep all technical terms and file paths intact - Translate documentation refactoring instructions - Maintain structure and numbering * docs(vi): translate slash command - generate-api-docs to Vietnamese - Translate generate-api-docs.md slash command to Vietnamese - Keep all technical terms and file paths intact - Translate API documentation generation instructions - Maintain output format specifications * docs(vi): translate slash command - optimize to Vietnamese - Translate optimize.md slash command to Vietnamese - Keep all technical terms and code concepts intact - Translate code optimization instructions - Maintain issue priority and response format * docs(vi): translate slash command - pr to Vietnamese - Translate pr.md slash command to Vietnamese - Keep all commands and technical syntax intact - Translate PR preparation checklist instructions - Maintain conventional commits format documentation * docs(vi): translate slash command - push-all to Vietnamese - Translate push-all.md slash command to Vietnamese (153 lines) - Keep all git commands and technical syntax intact - Translate comprehensive workflow with safety checks - Maintain API key validation patterns and error handling - Preserve when to use/avoid sections and alternatives * docs(vi): translate slash command - setup-ci-cd to Vietnamese - Translate setup-ci-cd.md slash command to Vietnamese - Keep all tool names and technical terms intact - Translate CI/CD pipeline implementation instructions - Maintain pre-commit hooks and GitHub Actions sections * docs(vi): translate slash command - unit-test-expand to Vietnamese - Translate unit-test-expand.md slash command to Vietnamese - Keep all framework names and technical terms intact - Translate test coverage expansion instructions - Maintain testing frameworks and scenario sections * docs(vi): update translation queue - Module 01 complete (100%) - Mark all 9 Module 01 files as completed (2026-04-02) - Update Module 01 progress: 9/9 files (100%) ✅ - Update overall progress: 14/66 files (21%) - Update Priority 2 progress: 9/31 files (29%) - Update header with Module 01 completion milestone Module 01: Slash Commands - All files translated: ✅ README.md (overview, built-in commands, skills) ✅ commit.md (git commit with context) ✅ doc-refactor.md (documentation restructuring) ✅ generate-api-docs.md (API documentation generator) ✅ optimize.md (code optimization analysis) ✅ pr.md (pull request preparation) ✅ push-all.md (stage, commit, push with safety) ✅ setup-ci-cd.md (CI/CD pipeline implementation) ✅ unit-test-expand.md (test coverage expansion) * docs(vi): translate module 02 - memory guide to Vietnamese - Add complete Vietnamese translation of 02-memory/README.md (1162 lines) - Translate memory system overview and architecture - Include quick reference for memory commands (/init, /memory, #) - Document complete memory hierarchy (8 levels with precedence) - Translate auto memory section with architecture diagrams - Include practical examples (project, directory-specific, personal memory) - Add best practices, installation instructions, and troubleshooting - Preserve all code examples, file paths, and technical terms - Maintain Mermaid diagrams and tables * docs(vi): translate example project CLAUDE.md to Vietnamese - Translate project-CLAUDE.md example memory file - Keep all technical terms, commands, and code style intact - Translate descriptions and explanations - Maintain project configuration structure * docs(vi): translate example personal CLAUDE.md to Vietnamese - Translate personal-CLAUDE.md example memory file - Keep all technical terms, tools, and preferences intact - Translate descriptions and explanations - Maintain personal preferences structure * docs(vi): translate example directory-specific CLAUDE.md to Vietnamese - Translate directory-api-CLAUDE.md example memory file - Keep all technical terms, API standards, and code examples intact - Translate descriptions and explanations - Maintain API module standards structure * docs(vi): update translation queue - Module 02 complete (100%) - Mark all 4 Module 02 files as completed (2026-04-02) - Update Module 02 progress: 4/4 files (100%) ✅ - Update overall progress: 18/66 files (27%) - Update Priority 2 progress: 13/31 files (42%) - Update header with Module 02 completion milestone Module 02: Memory - All files translated: ✅ README.md (1162 lines - comprehensive memory guide) ✅ project-CLAUDE.md (example project memory) ✅ personal-CLAUDE.md (example personal preferences) ✅ directory-api-CLAUDE.md (example directory-specific rules) * docs(vi): translate module 03 - skills guide to Vietnamese - Add complete Vietnamese translation of 03-skills/README.md (805 lines) - Translate Agent Skills overview and architecture - Include progressive disclosure loading mechanism (3 levels) - Document skill types, locations, and automatic discovery - Translate skill creation process and SKILL.md format - Include required and optional frontmatter fields - Document skill content types (reference vs task) - Translate controlling skill invocation and string substitutions - Include dynamic context injection with shell commands - Document running skills in subagents with context: fork - Translate 6 practical examples with directory structures - Add supporting files, management, and best practices sections - Preserve all code examples, YAML frontmatter, and Mermaid diagrams - Maintain tables, troubleshooting guides, and security considerations * docs(vi): translate skill - blog-draft to Vietnamese - Translate blog-draft/SKILL.md to Vietnamese (275 lines) - Keep all workflow steps and technical structure intact - Translate instructions and descriptions - Maintain version tracking and file structure - Preserve all markdown formatting and code examples * docs(vi): translate skill - brand-voice to Vietnamese - Translate brand-voice/SKILL.md to Vietnamese (73 lines) - Keep brand identity, tone, and vocabulary intact - Translate writing guidelines and examples - Maintain preferred/avoided terms sections - Preserve good/bad examples with explanations * docs(vi): translate skill - claude-md to Vietnamese - Translate claude-md/SKILL.md to Vietnamese (213 lines) - Keep all golden rules and core principles intact - Translate execution flow and content strategy - Maintain WHAT/WHY/HOW structure - Preserve quality constraints and validation checklist - Keep anti-patterns and output format sections * docs(vi): translate skill - code-review to Vietnamese - Translate code-review/SKILL.md to Vietnamese (71 lines) - Keep all review categories and template intact - Translate security, performance, quality, maintainability sections - Maintain review template structure - Preserve version history * docs(vi): translate skill - refactor to Vietnamese - Translate refactor/SKILL.md to Vietnamese (427 lines) - Keep all Martin Fowler refactoring methodology intact - Translate 6-phase workflow with detailed steps - Maintain core principles and safety rules - Preserve code smell catalog and refactoring techniques - Keep quick start example with before/after code - Maintain version history and references sections * docs(vi): update translation queue - Module 03 complete (100%) - Mark all 6 Module 03 files as completed (2026-04-02) - Update Module 03 progress: 6/6 files (100%) ✅ - Update overall progress: 24/66 files (36%) - Update Priority 2 progress: 19/31 files (61%) - Update header with Module 03 completion milestone Module 03: Skills - All files translated: ✅ README.md (805 lines - comprehensive skills guide) ✅ blog-draft/SKILL.md (275 lines - blog post creation workflow) ✅ brand-voice/SKILL.md (73 lines - brand voice consistency) ✅ claude-md/SKILL.md (213 lines - CLAUDE.md best practices) ✅ code-review/SKILL.md (71 lines - comprehensive code review) ✅ refactor/SKILL.md (427 lines - Fowler refactoring methodology) * docs(vi): translate Module 04 Subagents README Complete Vietnamese translation of subagents reference guide: - Configuration and built-in subagents (general-purpose, Plan, Explore, Bash, statusline-setup, Claude Code Guide) - Agent management with /agents command - Automatic delegation vs explicit invocation - Resumable agents and chaining - Persistent memory across agent sessions - Background subagents for parallel work - Worktree isolation for safe experimentation - Agent Teams (experimental feature) - Best practices and usage patterns * docs(vi): complete Module 04 Subagents translation Translate all 6 subagent example definitions: - code-reviewer.md: Expert code review specialist - debugger.md: Root cause analysis and debugging - documentation-writer.md: Technical documentation creation - implementation-agent.md: Full-stack feature implementation - secure-reviewer.md: Security-focused code review - test-engineer.md: Comprehensive test coverage Update translation queue progress: - Module 04: 7/7 files (100%) ✅ - Overall: 31/66 files (47%) - Next: Module 05 (MCP) * docs(vi): complete Module 05 MCP translation Translate comprehensive MCP (Model Context Protocol) guide: - Overview and architecture diagrams - Installation methods (HTTP, Stdio, SSE, WebSocket) - OAuth 2.0 authentication support - MCP tool search and dynamic updates - Elicitation and prompt slash commands - Configuration management (local, project, user scopes) - Practical examples (GitHub, Database, Filesystem, Slack MCPs) - MCP vs Memory decision matrix - Code execution approach for solving context bloat - MCPorter runtime reference - Security best practices and troubleshooting Translate 4 MCP configuration JSON examples: - filesystem-mcp.json: File operations - github-mcp.json: GitHub integration - database-mcp.json: SQL queries - multi-mcp.json: Multiple servers configuration Update translation queue progress: - Module 05: 5/5 files (100%) ✅ - Overall: 36/66 files (55%) - Next: Module 06 (Hooks) * docs(vi): complete Module 06 Hooks translation Translate comprehensive Hooks guide: - Overview and architecture - Configuration structure (user, project, local scopes) - Four hook types: command, HTTP, prompt, agent - 25 hook events with matcher patterns - Component-scoped hooks and subagent frontmatter - JSON input/output format and exit codes - Environment variables and best practices - Security considerations and debugging - Installation instructions Copy 9 hook example files (code, no translation needed): - format-code.sh: Auto-format code after write/edit - log-bash.sh: Bash command logging - notify-team.sh: Team notifications - pre-commit.sh: Pre-commit validation - security-scan.sh: Security scanning - validate-prompt.sh: Prompt validation - context-tracker.py: Token usage tracking - context-tracker-tiktoken.py: Accurate token counting Update translation queue progress: - Module 06: 9/9 files (100%) ✅ - Overall: 45/67 files (67%) - Next: Module 07 (Plugins) * docs(vi): complete Module 07 Plugins translation Translate comprehensive Plugins guide: - Overview and architecture diagrams - Plugin loading process and lifecycle - Plugin types (Official, Community, Organization, Personal) - Plugin definition structure and manifest - Plugin structure example with all directories - LSP server configuration and examples - Plugin options (v2.1.83+) with userConfig - Persistent plugin data via CLAUDE_PLUGIN_DATA - Inline plugins via settings (v2.1.80+) - Standalone vs Plugin approach comparison - Practical examples (PR Review, DevOps, Documentation plugins) - Plugin marketplace and distribution - Marketplace configuration and definition schema - Plugin source types and distribution methods - Plugin CLI commands and installation methods - Plugin features comparison table - Testing, hot-reload, and managed settings - Plugin security restrictions - Publishing workflow and best practices - Complete troubleshooting guide Copy all plugin subdirectories (code, no translation needed): - devops-automation/: Deployment workflows, incident management - documentation/: API docs, README generation, templates - pr-review/: Pull request review automation Update translation queue progress: - Module 07: 10+/10+ files (100%) ✅ - Overall: 55+/67 files (82%) - Next: Module 08-10 (Checkpoints, Advanced Features, CLI) * docs(vi): complete Modules 08-10 translation Module 08: Checkpoints and Rewind (2 files) - Overview and architecture - Access methods (keyboard shortcut, slash command) - Five rewind options (restore code+conversation, conversation, code, summarize, cancel) - Automatic checkpoints and retention policies - Use cases and practical examples - Integration with git and best practices Module 09: Advanced Features (3 files) - Planning Mode: Two-phase implementation approach - Extended Thinking: Deep reasoning for complex problems - Auto Mode: Background safety classifier - Background Tasks, Scheduled Tasks - Permission Modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) - Print Mode, Session Management - Voice Dictation, Channels, Remote Control - Web Sessions, Desktop App, Task List - Git Worktrees, Sandboxing, Managed Settings Module 10: CLI Reference (1 file) - CLI commands reference - Core flags and options - Interactive vs Print Mode - Model selection and configuration - System prompt customization - Tool & permission management - Output formats and scripting Update translation queue progress: - Modules 08-10: 6/6 files (100%) ✅ - All Modules 01-10: 61+/61+ files (100%) ✅ - Overall: 61+/67 files (91%) - Remaining: Supporting docs (6 files) * docs(vi): complete supporting documentation translation Translate all 5 supporting documents: - CONTRIBUTING.md: Contribution guidelines - SECURITY.md: Security policy and vulnerability reporting - CODE_OF_CONDUCT.md: Community standards and harassment policy - STYLE_GUIDE.md: Documentation formatting conventions - CHANGELOG.md: Version history (v2.2.0, v2.1.1, v2.1.0, v2.0.0) Update translation queue to 100% completion: - All Modules 01-10: 61+ files (100%) ✅ - Supporting Docs: 5/5 files (100%) ✅ - Overall: 67+/67 files (100%) ✅ - Status: HOÀN THÀNH ✅ * fix(vi): fix mermaid syntax and broken cross-references in Vietnamese translation Fix invalid `#` comment in mermaid block (use `%%` instead) and update cross-reference script to support Unicode/Vietnamese diacritics in anchor generation. Fix broken anchor links across vi/ documentation files. * fix(vi): remove inline mermaid comment causing parse error Inline %% comments on node definition lines are not supported by the mermaid parser. The surrounding HTML comment already explains this is an incorrect example.
This commit is contained in:
Thiên Toán
@@ -0,0 +1,943 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# Claude Code Plugins / Plugins Claude Code
|
||||
|
||||
Thư mục này chứa các ví dụ plugin hoàn chỉnh đóng gói nhiều tính năng Claude Code thành các gói có thể cài đặt liền mạch.
|
||||
|
||||
## Tổng Quan / Overview
|
||||
|
||||
Claude Code Plugins là các bộ sưu tập được đóng gói của các tùy chỉnh (slash commands, subagents, MCP servers, và hooks) cài đặt với một lệnh duy nhất. Chúng đại diện cho cơ chế mở rộng cấp cao nhất—kết hợp nhiều tính năng thành các gói gắn kết, có thể chia sẻ.
|
||||
|
||||
## Kiến Trúc Plugin / Plugin Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["Plugin"]
|
||||
B["Slash Commands"]
|
||||
C["Subagents"]
|
||||
D["MCP Servers"]
|
||||
E["Hooks"]
|
||||
F["Configuration"]
|
||||
|
||||
A -->|bundles| B
|
||||
A -->|bundles| C
|
||||
A -->|bundles| D
|
||||
A -->|bundles| E
|
||||
A -->|bundles| F
|
||||
```
|
||||
|
||||
## Quy Trình Tải Plugin / Plugin Loading Process
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Claude as Claude Code
|
||||
participant Plugin as Plugin Marketplace
|
||||
participant Install as Installation
|
||||
participant SlashCmds as Slash Commands
|
||||
participant Subagents
|
||||
participant MCPServers as MCP Servers
|
||||
participant Hooks
|
||||
participant Tools as Configured Tools
|
||||
|
||||
User->>Claude: /plugin install pr-review
|
||||
Claude->>Plugin: Download plugin manifest
|
||||
Plugin-->>Claude: Return plugin definition
|
||||
Claude->>Install: Extract components
|
||||
Install->>SlashCmds: Configure
|
||||
Install->>Subagents: Configure
|
||||
Install->>MCPServers: Configure
|
||||
Install->>Hooks: Configure
|
||||
SlashCmds-->>Tools: Ready to use
|
||||
Subagents-->>Tools: Ready to use
|
||||
MCPServers-->>Tools: Ready to use
|
||||
Hooks-->>Tools: Ready to use
|
||||
Tools-->>Claude: Plugin installed ✅
|
||||
```
|
||||
|
||||
## Các Loại Plugin & Phân Phối / Plugin Types & Distribution
|
||||
|
||||
| Loại | Phạm Vi | Chia Sẻ | Quyền | Ví Dụ |
|
||||
|------|-------|--------|-----------|----------|
|
||||
| Chính Thức | Toàn cầu | Tất cả người dùng | Anthropic | PR Review, Security Guidance |
|
||||
| Cộng Đồng | Công khai | Tất cả người dùng | Cộng Đồng | DevOps, Data Science |
|
||||
| Tổ Chức | Nội bộ | Các thành viên nhóm | Công ty | Tiêu chuẩn nội bộ, công cụ |
|
||||
| Cá Nhân | Cá nhân | Người dùng duy nhất | Nhà phát triển | Workflows tùy chỉnh |
|
||||
|
||||
## Cấu Trúc Định Nghĩa Plugin / Plugin Definition Structure
|
||||
|
||||
Plugin manifest sử dụng định dạng JSON trong `.claude-plugin/plugin.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-first-plugin",
|
||||
"description": "A greeting plugin",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
},
|
||||
"homepage": "https://example.com",
|
||||
"repository": "https://github.com/user/repo",
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
## Ví Dụ Cấu Trúc Plugin / Plugin Structure Example
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Manifest (tên, mô tả, phiên bản, tác giả)
|
||||
├── commands/ # Skills như các file Markdown
|
||||
│ ├── task-1.md
|
||||
│ ├── task-2.md
|
||||
│ └── workflows/
|
||||
├── agents/ # Định nghĩa agent tùy chỉnh
|
||||
│ ├── specialist-1.md
|
||||
│ ├── specialist-2.md
|
||||
│ └── configs/
|
||||
├── skills/ # Agent Skills với các file SKILL.md
|
||||
│ ├── skill-1.md
|
||||
│ └── skill-2.md
|
||||
├── hooks/ # Event handlers trong hooks.json
|
||||
│ └── hooks.json
|
||||
├── .mcp.json # Cấu hình MCP server
|
||||
├── .lsp.json # Cấu hình LSP server
|
||||
├── settings.json # Cài đặt mặc định
|
||||
├── templates/
|
||||
│ └── issue-template.md
|
||||
├── scripts/
|
||||
│ ├── helper-1.sh
|
||||
│ └── helper-2.py
|
||||
├── docs/
|
||||
│ ├── README.md
|
||||
│ └── USAGE.md
|
||||
└── tests/
|
||||
└── plugin.test.js
|
||||
```
|
||||
|
||||
### Cấu hình LSP server / LSP server configuration
|
||||
|
||||
Plugins có thể bao gồm hỗ trợ Language Server Protocol (LSP) để thông minh code thời gian thực. LSP servers cung cấp chẩn đoán, điều hướng code, và thông tin ký hiệu khi bạn làm việc.
|
||||
|
||||
**Vị trí cấu hình:**
|
||||
- File `.lsp.json` trong thư mục gốc plugin
|
||||
- Key `lsp` inline trong `plugin.json`
|
||||
|
||||
#### Tham khảo trường / Field reference
|
||||
|
||||
| Trường | Bắt Buộc | Mô Tả |
|
||||
|-------|----------|-------------|
|
||||
| `command` | Có | Binary LSP server (phải trong PATH) |
|
||||
| `extensionToLanguage` | Có | Ánh xạ các phần mở rộng file đến ID ngôn ngữ |
|
||||
| `args` | Không | Các đối số dòng lệnh cho server |
|
||||
| `transport` | Không | Phương thức giao tiếp: `stdio` (mặc định) hoặc `socket` |
|
||||
| `env` | Không | Biến môi trường cho tiến trình server |
|
||||
| `initializationOptions` | Không | Các tùy chọn được gửi trong quá trình khởi tạo LSP |
|
||||
| `settings` | Không | Cấu hình workspace được chuyển đến server |
|
||||
| `workspaceFolder` | Không | Ghi đè đường dẫn thư mục workspace |
|
||||
| `startupTimeout` | Không | Thời gian tối đa (ms) để chờ khởi động server |
|
||||
| `shutdownTimeout` | Không | Thời gian tối đa (ms) để tắt graceful |
|
||||
| `restartOnCrash` | Không | Tự động khởi động lại nếu server bị lỗi |
|
||||
| `maxRestarts` | Không | Số lần khởi động lại tối đa trước khi bỏ cuộc |
|
||||
|
||||
#### Các cấu hình ví dụ / Example configurations
|
||||
|
||||
**Go (gopls):**
|
||||
|
||||
```json
|
||||
{
|
||||
"go": {
|
||||
"command": "gopls",
|
||||
"args": ["serve"],
|
||||
"extensionToLanguage": {
|
||||
".go": "go"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Python (pyright):**
|
||||
|
||||
```json
|
||||
{
|
||||
"python": {
|
||||
"command": "pyright-langserver",
|
||||
"args": ["--stdio"],
|
||||
"extensionToLanguage": {
|
||||
".py": "python",
|
||||
".pyi": "python"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```json
|
||||
{
|
||||
"typescript": {
|
||||
"command": "typescript-language-server",
|
||||
"args": ["--stdio"],
|
||||
"extensionToLanguage": {
|
||||
".ts": "typescript",
|
||||
".tsx": "typescriptreact",
|
||||
".js": "javascript",
|
||||
".jsx": "javascriptreact"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Các plugin LSP có sẵn / Available LSP plugins
|
||||
|
||||
Marketplace chính thức bao gồm các plugin LSP được cấu hình trước:
|
||||
|
||||
| Plugin | Ngôn Ngữ | Server Binary | Lệnh Cài Đặt |
|
||||
|--------|----------|---------------|----------------|
|
||||
| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` |
|
||||
| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
|
||||
| `rust-lsp` | Rust | `rust-analyzer` | Cài đặt qua `rustup component add rust-analyzer` |
|
||||
|
||||
#### Khả năng LSP / LSP capabilities
|
||||
|
||||
Khi được cấu hình, LSP servers cung cấp:
|
||||
|
||||
- **Chẩn đoán tức thì** — lỗi và cảnh báo xuất hiện ngay sau khi chỉnh sửa
|
||||
- **Điều hướng code** — đi đến định nghĩa, tìm tham chiếu, implementations
|
||||
- **Thông tin hover** — chữ ký kiểu và tài liệu khi hover
|
||||
- **Liệt kê ký hiệu** — duyệt các ký hiệu trong file hoặc workspace hiện tại
|
||||
|
||||
## Tùy Chọn Plugin (v2.1.83+) / Plugin Options
|
||||
|
||||
Plugins có thể khai báo các tùy chọn có thể cấu hình bởi người dùng trong manifest qua `userConfig`. Các giá trị được đánh dấu `sensitive: true` được lưu trữ trong system keychain thay vì các file settings plain-text:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"userConfig": {
|
||||
"apiKey": {
|
||||
"description": "API key for the service",
|
||||
"sensitive": true
|
||||
},
|
||||
"region": {
|
||||
"description": "Deployment region",
|
||||
"default": "us-east-1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dữ Liệu Plugin Liên Tục (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+)
|
||||
|
||||
Plugins có quyền truy cập đến một thư mục trạng thái liên tục qua biến môi trường `${CLAUDE_PLUGIN_DATA}`. Thư mục này là duy nhất cho mỗi plugin và tồn tại qua các phiên, làm cho nó phù hợp cho caches, databases, và các trạng thái liên tục khác:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Thư mục được tạo tự động khi plugin được cài đặt. Các file được lưu trữ ở đây tồn tại cho đến khi plugin được gỡ cài đặt.
|
||||
|
||||
## Plugin Inline qua Settings (`source: 'settings'`) (v2.1.80+)
|
||||
|
||||
Plugins có thể được định nghĩa inline trong các file settings như các mục marketplace sử dụng trường `source: 'settings'`. Điều này cho phép nhúng định nghĩa plugin trực tiếp mà không cần repository hoặc marketplace riêng:
|
||||
|
||||
```json
|
||||
{
|
||||
"pluginMarketplaces": [
|
||||
{
|
||||
"name": "inline-tools",
|
||||
"source": "settings",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "quick-lint",
|
||||
"source": "./local-plugins/quick-lint"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Cài Đặt Plugin / Plugin Settings
|
||||
|
||||
Plugins có thể gửi một file `settings.json` để cung cấp cấu hình mặc định. Điều này hiện hỗ trợ key `agent`, thiết lập agent luồng chính cho plugin:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "agents/specialist-1.md"
|
||||
}
|
||||
```
|
||||
|
||||
Khi một plugin bao gồm `settings.json`, các mặc định của nó được áp dụng khi cài đặt. Người dùng có thể ghi đè các cài đặt này trong cấu hình project hoặc user của riêng họ.
|
||||
|
||||
## Cách Tiếp Cận Standalone vs Plugin / Standalone vs Plugin Approach
|
||||
|
||||
| Cách Tiếp Cận | Tên Lệnh | Cấu Hình | Tốt Nhất Cho |
|
||||
|----------|---------------|---|---|
|
||||
| **Standalone** | `/hello` | Thiết lập thủ công trong CLAUDE.md | Cá nhân, cụ thể project |
|
||||
| **Plugins** | `/plugin-name:hello` | Tự động qua plugin.json | Chia sẻ, phân phối, sử dụng nhóm |
|
||||
|
||||
**Sử dụng slash commands standalone** cho workflows cá nhân nhanh. **Sử dụng plugins** khi bạn muốn đóng gói nhiều tính năng, chia sẻ với một nhóm, hoặc xuất bản để phân phối.
|
||||
|
||||
## Ví Dụ Thực Tiễn / Practical Examples
|
||||
|
||||
### Ví Dụ 1: Plugin PR Review / Example 1: PR Review Plugin
|
||||
|
||||
**File:** `.claude-plugin/plugin.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "pr-review",
|
||||
"version": "1.0.0",
|
||||
"description": "Complete PR review workflow with security, testing, and docs",
|
||||
"author": {
|
||||
"name": "Anthropic"
|
||||
},
|
||||
"repository": "https://github.com/your-org/pr-review",
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
**File:** `commands/review-pr.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Review PR
|
||||
description: Start comprehensive PR review with security and testing checks
|
||||
---
|
||||
|
||||
# PR Review
|
||||
|
||||
Lệnh này khởi tạo một pull request review hoàn chỉnh bao gồm:
|
||||
|
||||
1. Phân tích bảo mật
|
||||
2. Xác minh phủ vùng test
|
||||
3. Cập nhật tài liệu
|
||||
4. Kiểm tra chất lượng code
|
||||
5. Đánh giá tác động hiệu suất
|
||||
```
|
||||
|
||||
**File:** `agents/security-reviewer.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Security-focused code review
|
||||
tools: read, grep, diff
|
||||
---
|
||||
|
||||
# Security Reviewer
|
||||
|
||||
Chuyên về việc tìm các lỗ hổng bảo mật:
|
||||
- Vấn đề xác thực/ủy quyền
|
||||
- Lộ dữ liệu
|
||||
- Các tấn công tiêm nhiễm
|
||||
- Cấu hình bảo mật
|
||||
```
|
||||
|
||||
**Cài Đặt:**
|
||||
|
||||
```bash
|
||||
/plugin install pr-review
|
||||
|
||||
# Result:
|
||||
# ✅ 3 slash commands installed
|
||||
# ✅ 3 subagents configured
|
||||
# ✅ 2 MCP servers connected
|
||||
# ✅ 4 hooks registered
|
||||
# ✅ Ready to use!
|
||||
```
|
||||
|
||||
### Ví Dụ 2: Plugin DevOps / Example 2: DevOps Plugin
|
||||
|
||||
**Các Thành Phần:**
|
||||
|
||||
```
|
||||
devops-automation/
|
||||
├── commands/
|
||||
│ ├── deploy.md
|
||||
│ ├── rollback.md
|
||||
│ ├── status.md
|
||||
│ └── incident.md
|
||||
├── agents/
|
||||
│ ├── deployment-specialist.md
|
||||
│ ├── incident-commander.md
|
||||
│ └── alert-analyzer.md
|
||||
├── mcp/
|
||||
│ ├── github-config.json
|
||||
│ ├── kubernetes-config.json
|
||||
│ └── prometheus-config.json
|
||||
├── hooks/
|
||||
│ ├── pre-deploy.js
|
||||
│ ├── post-deploy.js
|
||||
│ └── on-error.js
|
||||
└── scripts/
|
||||
├── deploy.sh
|
||||
├── rollback.sh
|
||||
└── health-check.sh
|
||||
```
|
||||
|
||||
### Ví Dụ 3: Plugin Tài Liệu / Example 3: Documentation Plugin
|
||||
|
||||
**Các Thành Phần Được Đóng Gói:**
|
||||
|
||||
```
|
||||
documentation/
|
||||
├── commands/
|
||||
│ ├── generate-api-docs.md
|
||||
│ ├── generate-readme.md
|
||||
│ ├── sync-docs.md
|
||||
│ └── validate-docs.md
|
||||
├── agents/
|
||||
│ ├── api-documenter.md
|
||||
│ ├── code-commentator.md
|
||||
│ └── example-generator.md
|
||||
├── mcp/
|
||||
│ ├── github-docs-config.json
|
||||
│ └── slack-announce-config.json
|
||||
└── templates/
|
||||
├── api-endpoint.md
|
||||
├── function-docs.md
|
||||
└── adr-template.md
|
||||
```
|
||||
|
||||
## Marketplace Plugin / Plugin Marketplace
|
||||
|
||||
Thư mục plugin do Anthropic quản lý chính thức là `anthropics/claude-plugins-official`. Các quản trị viên enterprise cũng có thể tạo các plugin marketplaces riêng để phân phối nội bộ.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["Plugin Marketplace"]
|
||||
B["Official<br/>anthropics/claude-plugins-official"]
|
||||
C["Community<br/>Marketplace"]
|
||||
D["Enterprise<br/>Private Registry"]
|
||||
|
||||
A --> B
|
||||
A --> C
|
||||
A --> D
|
||||
|
||||
B -->|Categories| B1["Development"]
|
||||
B -->|Categories| B2["DevOps"]
|
||||
B -->|Categories| B3["Documentation"]
|
||||
|
||||
C -->|Search| C1["DevOps Automation"]
|
||||
C -->|Search| C2["Mobile Dev"]
|
||||
C -->|Search| C3["Data Science"]
|
||||
|
||||
D -->|Internal| D1["Company Standards"]
|
||||
D -->|Internal| D2["Legacy Systems"]
|
||||
D -->|Internal| D3["Compliance"]
|
||||
|
||||
style A fill:#e1f5fe,stroke:#333,color:#333
|
||||
style B fill:#e8f5e9,stroke:#333,color:#333
|
||||
style C fill:#f3e5f5,stroke:#333,color:#333
|
||||
style D fill:#fff3e0,stroke:#333,color:#333
|
||||
```
|
||||
|
||||
### Cấu Hình Marketplace / Marketplace Configuration
|
||||
|
||||
Người dùng enterprise và nâng cao có thể kiểm soát hành vi marketplace qua các cài đặt:
|
||||
|
||||
| Cài Đặt | Mô Tả |
|
||||
|---------|-------------|
|
||||
| `extraKnownMarketplaces` | Thêm các nguồn marketplace bổ sung ngoài mặc định |
|
||||
| `strictKnownMarketplaces` | Kiểm soát marketplace nào người dùng được phép thêm |
|
||||
| `deniedPlugins` | Blocklist do quản trị viên quản lý để ngăn cài đặt các plugin cụ thể |
|
||||
|
||||
### Các Tính Năng Marketplace Thêm / Additional Marketplace Features
|
||||
|
||||
- **Git timeout mặc định**: Tăng từ 30s lên 120s cho các repository plugin lớn
|
||||
- **npm registries tùy chỉnh**: Plugins có thể chỉ định URLs registry npm tùy chỉnh để giải quyết dependency
|
||||
- **Version pinning**: Khóa plugins đến các phiên bản cụ thể cho các môi trường có thể tái sản xuất
|
||||
|
||||
### Schema định nghĩa marketplace / Marketplace definition schema
|
||||
|
||||
Plugin marketplaces được định nghĩa trong `.claude-plugin/marketplace.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-team-plugins",
|
||||
"owner": "my-org",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "code-standards",
|
||||
"source": "./plugins/code-standards",
|
||||
"description": "Enforce team coding standards",
|
||||
"version": "1.2.0",
|
||||
"author": "platform-team"
|
||||
},
|
||||
{
|
||||
"name": "deploy-helper",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "my-org/deploy-helper",
|
||||
"ref": "v2.0.0"
|
||||
},
|
||||
"description": "Deployment automation workflows"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Trường | Bắt Buộc | Mô Tả |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Có | Tên marketplace trong kebab-case |
|
||||
| `owner` | Có | Tổ chức hoặc người dùng duy trì marketplace |
|
||||
| `plugins` | Có | Mảng các mục plugin |
|
||||
| `plugins[].name` | Có | Tên plugin (kebab-case) |
|
||||
| `plugins[].source` | Có | Nguồn plugin (chuỗi đường dẫn hoặc object nguồn) |
|
||||
| `plugins[].description` | Không | Mô tả plugin ngắn |
|
||||
| `plugins[].version` | Không | Chuỗi phiên bản semantic |
|
||||
| `plugins[].author` | Không | Tên tác giả plugin |
|
||||
|
||||
### Các loại nguồn plugin / Plugin source types
|
||||
|
||||
Plugins có thể được sourced từ nhiều vị trí:
|
||||
|
||||
| Nguồn | Cú Pháp | Ví Dụ |
|
||||
|--------|--------|---------|
|
||||
| **Đường dẫn tương đối** | Chuỗi đường dẫn | `"./plugins/my-plugin"` |
|
||||
| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` |
|
||||
| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` |
|
||||
| **Git subdirectory** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` |
|
||||
| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` |
|
||||
| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` |
|
||||
|
||||
Các nguồn GitHub và git hỗ trợ các trường tùy chọn `ref` (nhánh/tag) và `sha` (hash commit) để version pinning.
|
||||
|
||||
### Các phương thức phân phối / Distribution methods
|
||||
|
||||
**GitHub (khuyến nghị):**
|
||||
```bash
|
||||
# Người dùng thêm marketplace của bạn
|
||||
/plugin marketplace add owner/repo-name
|
||||
```
|
||||
|
||||
**Các dịch vụ git khác** (yêu cầu URL đầy đủ):
|
||||
```bash
|
||||
/plugin marketplace add https://gitlab.com/org/marketplace-repo.git
|
||||
```
|
||||
|
||||
**Repository riêng tư**: Được hỗ trợ qua các git credential helpers hoặc token môi trường. Người dùng phải có quyền truy cập đọc đến repository.
|
||||
|
||||
**Nộp marketplace chính thức**: Gửi plugins đến marketplace do Anthropic quản lý để phân phối rộng hơn.
|
||||
|
||||
### Chế độ nghiêm ngặt / Strict mode
|
||||
|
||||
Kiểm soát cách các định nghĩa marketplace tương tác với các file `plugin.json` cục bộ:
|
||||
|
||||
| Cài Đặt | Hành Vi |
|
||||
|---------|----------|
|
||||
| `strict: true` (mặc định) | `plugin.json` cục bộ là có thẩm quyền; mục marketplace bổ sung nó |
|
||||
| `strict: false` | Mục marketplace là định nghĩa plugin hoàn chỉnh |
|
||||
|
||||
**Hạn chế tổ chức** với `strictKnownMarketplaces`:
|
||||
|
||||
| Giá Trị | Hiệu Ứng |
|
||||
|-------|--------|
|
||||
| Không được đặt | Không có hạn chế — người dùng có thể thêm bất kỳ marketplace nào |
|
||||
| Mảng rỗng `[]` | Khóa — không cho phép marketplaces |
|
||||
| Mảng các mẫu | Allowlist — chỉ các marketplaces khớp có thể được thêm |
|
||||
|
||||
```json
|
||||
{
|
||||
"strictKnownMarketplaces": [
|
||||
"my-org/*",
|
||||
"github.com/trusted-vendor/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
> **Cảnh Báo**: Trong chế độ nghiêm ngặt với `strictKnownMarketplaces`, người dùng chỉ có thể cài đặt plugins từ các marketplaces được allowlist. Điều này hữu ích cho các môi trường doanh nghiệp yêu cầu phân phối plugin được kiểm soát.
|
||||
|
||||
## Vòng Đời & Cài Đặt Plugin / Plugin Installation & Lifecycle
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["Discover"] -->|Browse| B["Marketplace"]
|
||||
B -->|Select| C["Plugin Page"]
|
||||
C -->|View| D["Components"]
|
||||
D -->|Install| E["/plugin install"]
|
||||
E -->|Extract| F["Configure"]
|
||||
F -->|Activate| G["Use"]
|
||||
G -->|Check| H["Update"]
|
||||
H -->|Available| G
|
||||
G -->|Done| I["Disable"]
|
||||
I -->|Later| J["Enable"]
|
||||
J -->|Back| G
|
||||
```
|
||||
|
||||
## So Sánh Tính Năng Plugin / Plugin Features Comparison
|
||||
|
||||
| Tính Năng | Slash Command | Skill | Subagent | Plugin |
|
||||
|---------|---------------|-------|----------|--------|
|
||||
| **Cài Đặt** | Copy thủ công | Copy thủ công | Cấu hình thủ công | Một lệnh |
|
||||
| **Thời Gian Thiết Lập** | 5 phút | 10 phút | 15 phút | 2 phút |
|
||||
| **Đóng Gói** | File đơn | File đơn | File đơn | Nhiều |
|
||||
| **Phiên Bản Hóa** | Thủ công | Thủ công | Thủ công | Tự động |
|
||||
| **Chia Sẻ Nhóm** | Copy file | Copy file | Copy file | Cài đặt ID |
|
||||
| **Cập Nhật** | Thủ công | Thủ công | Thủ công | Tự động có sẵn |
|
||||
| **Phụ Thuộc** | Không | Không | Không | Có thể bao gồm |
|
||||
| **Marketplace** | Không | Không | Không | Có |
|
||||
| **Phân Phối** | Repository | Repository | Repository | Marketplace |
|
||||
|
||||
## Các Lệnh CLI Plugin / Plugin CLI Commands
|
||||
|
||||
Tất cả các thao tác plugin có sẵn như các lệnh CLI:
|
||||
|
||||
```bash
|
||||
claude plugin install <name>@<marketplace> # Cài đặt từ marketplace
|
||||
claude plugin uninstall <name> # Gỡ bỏ plugin
|
||||
claude plugin list # Liệt kê các plugin đã cài đặt
|
||||
claude plugin enable <name> # Kích hoạt plugin đã bị vô hiệu hóa
|
||||
claude plugin disable <name> # Vô hiệu hóa plugin
|
||||
claude plugin validate # Xác thực cấu trúc plugin
|
||||
```
|
||||
|
||||
## Các Phương Thức Cài Đặt / Installation Methods
|
||||
|
||||
### Từ Marketplace
|
||||
```bash
|
||||
/plugin install plugin-name
|
||||
# hoặc từ CLI:
|
||||
claude plugin install plugin-name@marketplace-name
|
||||
```
|
||||
|
||||
### Kích Hoạt / Vô Hiệu Hóa (với phạm vi tự phát hiện)
|
||||
```bash
|
||||
/plugin enable plugin-name
|
||||
/plugin disable plugin-name
|
||||
```
|
||||
|
||||
### Plugin Cục Bộ (cho phát triển)
|
||||
```bash
|
||||
# Cờ CLI để test cục bộ (có thể lặp lại cho nhiều plugins)
|
||||
claude --plugin-dir ./path/to/plugin
|
||||
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
|
||||
```
|
||||
|
||||
### Từ Git Repository
|
||||
```bash
|
||||
/plugin install github:username/repo
|
||||
```
|
||||
|
||||
## Khi Nào Tạo Một Plugin / When to Create a Plugin
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A["Should I create a plugin?"]
|
||||
A -->|Need multiple components| B{"Multiple commands<br/>or subagents<br/>or MCPs?"}
|
||||
B -->|Yes| C["✅ Create Plugin"]
|
||||
B -->|No| D["Use Individual Feature"]
|
||||
A -->|Team workflow| E{"Share with<br/>team?"}
|
||||
E -->|Yes| C
|
||||
E -->|No| F["Keep as Local Setup"]
|
||||
A -->|Complex setup| G{"Needs auto<br/>configuration?"}
|
||||
G -->|Yes| C
|
||||
G -->|No| D
|
||||
```
|
||||
|
||||
### Các Trường Hợp Sử Dụng Plugin / Plugin Use Cases
|
||||
|
||||
| Trường Hợp Sử Dụng | Khuyến Nghị | Tại Sao |
|
||||
|----------|-----------------|-----|
|
||||
| **Team Onboarding** | ✅ Use Plugin | Thiết lập tức thì, tất cả cấu hình |
|
||||
| **Framework Setup** | ✅ Use Plugin | Đóng gói các lệnh cụ thể framework |
|
||||
| **Enterprise Standards** | ✅ Use Plugin | Phân phối trung tâm, kiểm soát phiên bản |
|
||||
| **Quick Task Automation** | ❌ Use Command | Quá phức tạp |
|
||||
| **Single Domain Expertise** | ❌ Use Skill | Quá nặng, sử dụng skill thay thế |
|
||||
| **Specialized Analysis** | ❌ Use Subagent | Tạo thủ công hoặc sử dụng skill |
|
||||
| **Live Data Access** | ❌ Use MCP | Standalone, đừng đóng gói |
|
||||
|
||||
## Testing Một Plugin / Testing a Plugin
|
||||
|
||||
Trước khi xuất bản, test plugin của bạn cục bộ sử dụng cờ CLI `--plugin-dir` (có thể lặp lại cho nhiều plugins):
|
||||
|
||||
```bash
|
||||
claude --plugin-dir ./my-plugin
|
||||
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin
|
||||
```
|
||||
|
||||
Điều này khởi chạy Claude Code với plugin của bạn được tải, cho phép bạn:
|
||||
- Xác minh tất cả các lệnh slash có sẵn
|
||||
- Test subagents và agents hoạt động chính xác
|
||||
- Xác nhận MCP servers kết nối đúng
|
||||
- Xác thực thực thi hook
|
||||
- Kiểm tra các cấu hình LSP server
|
||||
- Kiểm tra các lỗi cấu hình
|
||||
|
||||
## Hot-Reload
|
||||
|
||||
Plugins hỗ trợ hot-reload trong quá trình phát triển. Khi bạn sửa đổi các file plugin, Claude Code có thể phát hiện các thay đổi tự động. Bạn cũng có thể force reload với:
|
||||
|
||||
```bash
|
||||
/reload-plugins
|
||||
```
|
||||
|
||||
Điều này đọc lại tất cả các plugin manifests, commands, agents, skills, hooks, và cấu hình MCP/LSP mà không cần khởi động lại phiên.
|
||||
|
||||
## Cài Đặt Được Quản Lý Cho Plugins / Managed Settings for Plugins
|
||||
|
||||
Các quản trị viên có thể kiểm soát hành vi plugin trên một tổ chức sử dụng các cài đặt được quản lý:
|
||||
|
||||
| Cài Đặt | Mô Tả |
|
||||
|---------|-------------|
|
||||
| `enabledPlugins` | Allowlist của các plugin được kích hoạt theo mặc định |
|
||||
| `deniedPlugins` | Blocklist của các plugin không thể được cài đặt |
|
||||
| `extraKnownMarketplaces` | Thêm các nguồn marketplace bổ sung ngoài mặc định |
|
||||
| `strictKnownMarketplaces` | Hạn chế marketplace nào người dùng được phép thêm |
|
||||
| `allowedChannelPlugins` | Kiểm soát plugins nào được phép theo kênh phát hành |
|
||||
|
||||
Các cài đặt này có thể được áp dụng ở cấp tổ chức qua các file cấu hình được quản lý và có ưu tiên hơn các cài đặt cấp người dùng.
|
||||
|
||||
## Bảo Mật Plugin / Plugin Security
|
||||
|
||||
Các subagent plugin chạy trong một sandbox bị hạn chế. Các key frontmatter sau **không được phép** trong định nghĩa subagent plugin:
|
||||
|
||||
- `hooks` -- Subagents không thể đăng ký event handlers
|
||||
- `mcpServers` -- Subagents không thể cấu hình MCP servers
|
||||
- `permissionMode` -- Subagents không thể ghi đè mô hình quyền
|
||||
|
||||
Điều này đảm bảo rằng plugins không thể leo thang đặc quyền hoặc sửa đổi môi trường host vượt quá phạm vi được khai báo của chúng.
|
||||
|
||||
## Xuất Bản Một Plugin / Publishing a Plugin
|
||||
|
||||
**Các bước để xuất bản:**
|
||||
|
||||
1. Tạo cấu trúc plugin với tất cả các thành phần
|
||||
2. Viết manifest `.claude-plugin/plugin.json`
|
||||
3. Tạo `README.md` với tài liệu
|
||||
4. Test cục bộ với `claude --plugin-dir ./my-plugin`
|
||||
5. Gửi đến plugin marketplace
|
||||
6. Được review và phê duyệt
|
||||
7. Xuất bản trên marketplace
|
||||
8. Người dùng có thể cài đặt với một lệnh
|
||||
|
||||
**Ví dụ gửi:**
|
||||
|
||||
```markdown
|
||||
# PR Review Plugin
|
||||
|
||||
## Mô Tả
|
||||
Workflow PR review hoàn chỉnh với các kiểm tra bảo mật, testing, và tài liệu.
|
||||
|
||||
## Những Gì Được Bao Gồm
|
||||
- 3 lệnh slash cho các loại review khác nhau
|
||||
- 3 subagents chuyên biệt
|
||||
- Tích hợp GitHub và CodeQL MCP
|
||||
- Các hooks quét bảo mật tự động
|
||||
|
||||
## Cài Đặt
|
||||
```bash
|
||||
/plugin install pr-review
|
||||
```
|
||||
|
||||
## Tính Năng
|
||||
✅ Phân tích bảo mật
|
||||
✅ Kiểm tra phủ vùng test
|
||||
✅ Xác minh tài liệu
|
||||
✅ Đánh giá chất lượng code
|
||||
✅ Phân tích tác động hiệu suất
|
||||
|
||||
## Sử Dụng
|
||||
```bash
|
||||
/review-pr
|
||||
/check-security
|
||||
/check-tests
|
||||
```
|
||||
|
||||
## Yêu Cầu
|
||||
- Claude Code 1.0+
|
||||
- Truy cập GitHub
|
||||
- CodeQL (tùy chọn)
|
||||
```
|
||||
|
||||
## Plugin vs Cấu Hình Thủ Công / Plugin vs Manual Configuration
|
||||
|
||||
**Thiết Lập Thủ Công (2+ giờ):**
|
||||
- Cài đặt các lệnh slash từng cái một
|
||||
- Tạo subagents riêng lẻ
|
||||
- Cấu hình MCPs riêng biệt
|
||||
- Thiết lập hooks thủ công
|
||||
- Tài liệu hóa mọi thứ
|
||||
- Chia sẻ với nhóm (hy vọng họ cấu hình đúng)
|
||||
|
||||
**Với Plugin (2 phút):**
|
||||
```bash
|
||||
/plugin install pr-review
|
||||
# ✅ Mọi thứ được cài đặt và cấu hình
|
||||
# ✅ Sẵn sàng sử dụng ngay lập tức
|
||||
# ✅ Nhóm có thể tái sản xuất thiết lập chính xác
|
||||
```
|
||||
|
||||
## Thực Hành Tốt Nhất / Best Practices
|
||||
|
||||
### Nên Làm ✅ / Do's ✅
|
||||
- Sử dụng tên plugin rõ ràng, mô tả
|
||||
- Bao gồm README toàn diện
|
||||
- Phiên bản hóa plugin của bạn đúng cách (semver)
|
||||
- Test tất cả các thành phần cùng nhau
|
||||
- Tài liệu hóa các yêu cầu rõ ràng
|
||||
- Cung cấp các ví dụ sử dụng
|
||||
- Bao gồm xử lý lỗi
|
||||
- Gắn thẻ phù hợp để khám phá
|
||||
- Duy trì tương thích ngược
|
||||
- Giữ các plugin tập trung và gắn kết
|
||||
- Bao gồm các tests toàn diện
|
||||
- Tài liệu hóa tất cả các dependencies
|
||||
|
||||
### Không Nên Làm ❌ / Don'ts ❌
|
||||
- Đừng đóng gói các tính năng không liên quan
|
||||
- Đừng hardcode credentials
|
||||
- Đừng bỏ qua testing
|
||||
- Đừng quên tài liệu
|
||||
- Đừng tạo các plugin dư thừa
|
||||
- Đừng bỏ qua versioning
|
||||
- Đừng làm phức tạp quá mức các dependencies thành phần
|
||||
- Đừng quên xử lý các lỗi một cách graceful
|
||||
|
||||
## Hướng Dẫn Cài Đặt / Installation Instructions
|
||||
|
||||
### Cài Đặt Từ Marketplace
|
||||
|
||||
1. **Duyệt các plugins có sẵn:**
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
2. **Xem chi tiết plugin:**
|
||||
```bash
|
||||
/plugin info plugin-name
|
||||
```
|
||||
|
||||
3. **Cài đặt một plugin:**
|
||||
```bash
|
||||
/plugin install plugin-name
|
||||
```
|
||||
|
||||
### Cài Đặt Từ Đường Dẫn Cục Bộ
|
||||
|
||||
```bash
|
||||
/plugin install ./path/to/plugin-directory
|
||||
```
|
||||
|
||||
### Cài Đặt Từ GitHub
|
||||
|
||||
```bash
|
||||
/plugin install github:username/repo
|
||||
```
|
||||
|
||||
### Liệt Kê Các Plugins Đã Cài Đặt
|
||||
|
||||
```bash
|
||||
/plugin list --installed
|
||||
```
|
||||
|
||||
### Cập Nhật Một Plugin
|
||||
|
||||
```bash
|
||||
/plugin update plugin-name
|
||||
```
|
||||
|
||||
### Vô Hiệu Hóa/Kích Hoạt Một Plugin
|
||||
|
||||
```bash
|
||||
# Vô hiệu hóa tạm thời
|
||||
/plugin disable plugin-name
|
||||
|
||||
# Kích hoạt lại
|
||||
/plugin enable plugin-name
|
||||
```
|
||||
|
||||
### Gỡ Cài Đặt Một Plugin
|
||||
|
||||
```bash
|
||||
/plugin uninstall plugin-name
|
||||
```
|
||||
|
||||
## Các Khái Niệm Liên Quan / Related Concepts
|
||||
|
||||
Các tính năng Claude Code sau hoạt động cùng với plugins:
|
||||
|
||||
- **[Slash Commands](../01-slash-commands/)** - Các lệnh riêng lẻ được đóng gói trong plugins
|
||||
- **[Memory](../02-memory/)** - Ngữ cảnh liên tục cho plugins
|
||||
- **[Skills](../03-skills/)** - Chuyên môn lĩnh vực có thể được bọc trong plugins
|
||||
- **[Subagents](../04-subagents/)** - Các agents chuyên biệt được bao gồm như các thành phần plugin
|
||||
- **[MCP Servers](../05-mcp/)** - Các tích hợp Model Context Protocol được đóng gói trong plugins
|
||||
- **[Hooks](../06-hooks/)** - Event handlers kích hoạt workflows plugin
|
||||
|
||||
## Workflow Ví Dụ Hoàn Chỉnh / Complete Example Workflow
|
||||
|
||||
### Workflow Plugin PR Review Đầy Đủ / PR Review Plugin Full Workflow
|
||||
|
||||
```
|
||||
1. User: /review-pr
|
||||
|
||||
2. Plugin executes:
|
||||
├── pre-review.js hook validates git repo
|
||||
├── GitHub MCP fetches PR data
|
||||
├── security-reviewer subagent analyzes security
|
||||
├── test-checker subagent verifies coverage
|
||||
└── performance-analyzer subagent checks performance
|
||||
|
||||
3. Results synthesized and presented:
|
||||
✅ Security: No critical issues
|
||||
⚠️ Testing: Coverage 65% (recommend 80%+)
|
||||
✅ Performance: No significant impact
|
||||
📝 12 recommendations provided
|
||||
```
|
||||
|
||||
## Xử Lý Sự Cố / Troubleshooting
|
||||
|
||||
### Plugin Won't Install
|
||||
- Kiểm tra tính tương thích phiên bản Claude Code: `/version`
|
||||
- Xác minh cú pháp `plugin.json` với một trình xác thực JSON
|
||||
- Kiểm tra kết nối internet (cho plugins từ xa)
|
||||
- Review quyền: `ls -la plugin/`
|
||||
|
||||
### Components Not Loading
|
||||
- Xác minh các đường dẫn trong `plugin.json` khớp với cấu trúc thư mục thực tế
|
||||
- Kiểm tra quyền file: `chmod +x scripts/`
|
||||
- Review cú pháp file thành phần
|
||||
- Kiểm tra logs: `/plugin debug plugin-name`
|
||||
|
||||
### MCP Connection Failed
|
||||
- Xác minh các biến môi trường được đặt đúng
|
||||
- Kiểm tra cài đặt và sức khỏe MCP server
|
||||
- Test kết nối MCP độc lập với `/mcp test`
|
||||
- Review cấu hình MCP trong thư mục `mcp/`
|
||||
|
||||
### Commands Not Available After Install
|
||||
- Đảm bảo plugin được cài đặt thành công: `/plugin list --installed`
|
||||
- Kiểm tra nếu plugin được kích hoạt: `/plugin status plugin-name`
|
||||
- Khởi động lại Claude Code: `exit` và mở lại
|
||||
- Kiểm tra xung đột đặt tên với các lệnh hiện có
|
||||
|
||||
### Hook Execution Issues
|
||||
- Xác minh các file hook có các quyền đúng
|
||||
- Kiểm tra cú pháp hook và tên sự kiện
|
||||
- Review logs hook để biết chi tiết lỗi
|
||||
- Test hooks thủ công nếu có thể
|
||||
|
||||
## Tài Nguyên Thêm / Additional Resources
|
||||
|
||||
- [Tài Liệu Plugins Chính Thức](https://code.claude.com/docs/en/plugins)
|
||||
- [Khám Phá Plugins](https://code.claude.com/docs/en/discover-plugins)
|
||||
- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)
|
||||
- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference)
|
||||
- [MCP Server Reference](https://modelcontextprotocol.io/)
|
||||
- [Hướng Dẫn Cấu Hình Subagent](../04-subagents/README.md)
|
||||
- [Hệ Thống Hook Reference](../06-hooks/README.md)
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"name": "devops-automation",
|
||||
"version": "1.0.0",
|
||||
"description": "Complete DevOps automation for deployment, monitoring, and incident response",
|
||||
"author": {
|
||||
"name": "Community"
|
||||
},
|
||||
"license": "MIT"
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# DevOps Automation Plugin
|
||||
|
||||
Complete DevOps automation for deployment, monitoring, and incident response.
|
||||
|
||||
## Features
|
||||
|
||||
✅ Automated deployments
|
||||
✅ Rollback procedures
|
||||
✅ System health monitoring
|
||||
✅ Incident response workflows
|
||||
✅ Kubernetes integration
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
/plugin install devops-automation
|
||||
```
|
||||
|
||||
## What's Included
|
||||
|
||||
### Slash Commands
|
||||
- `/deploy` - Deploy to production or staging
|
||||
- `/rollback` - Rollback to previous version
|
||||
- `/status` - Check system health
|
||||
- `/incident` - Handle production incidents
|
||||
|
||||
### Subagents
|
||||
- `deployment-specialist` - Deployment operations
|
||||
- `incident-commander` - Incident coordination
|
||||
- `alert-analyzer` - System health analysis
|
||||
|
||||
### MCP Servers
|
||||
- Kubernetes integration
|
||||
|
||||
### Scripts
|
||||
- `deploy.sh` - Deployment automation
|
||||
- `rollback.sh` - Rollback automation
|
||||
- `health-check.sh` - Health check utilities
|
||||
|
||||
### Hooks
|
||||
- `pre-deploy.js` - Pre-deployment validation
|
||||
- `post-deploy.js` - Post-deployment tasks
|
||||
|
||||
## Usage
|
||||
|
||||
### Deploy to Staging
|
||||
```
|
||||
/deploy staging
|
||||
```
|
||||
|
||||
### Deploy to Production
|
||||
```
|
||||
/deploy production
|
||||
```
|
||||
|
||||
### Rollback
|
||||
```
|
||||
/rollback production
|
||||
```
|
||||
|
||||
### Check Status
|
||||
```
|
||||
/status
|
||||
```
|
||||
|
||||
### Handle Incident
|
||||
```
|
||||
/incident
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code 1.0+
|
||||
- Kubernetes CLI (kubectl)
|
||||
- Cluster access configured
|
||||
|
||||
## Configuration
|
||||
|
||||
Set up your Kubernetes config:
|
||||
```bash
|
||||
export KUBECONFIG=~/.kube/config
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
User: /deploy production
|
||||
|
||||
Claude:
|
||||
1. Runs pre-deploy hook (validates kubectl, cluster connection)
|
||||
2. Delegates to deployment-specialist subagent
|
||||
3. Runs deploy.sh script
|
||||
4. Monitors deployment progress via Kubernetes MCP
|
||||
5. Runs post-deploy hook (waits for pods, smoke tests)
|
||||
6. Provides deployment summary
|
||||
|
||||
Result:
|
||||
✅ Deployment complete
|
||||
📦 Version: v2.1.0
|
||||
🚀 Pods: 3/3 ready
|
||||
⏱️ Time: 2m 34s
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: alert-analyzer
|
||||
description: Analyzes monitoring alerts and system metrics
|
||||
tools: read, grep, bash
|
||||
---
|
||||
|
||||
# Alert Analyzer
|
||||
|
||||
Analyzes system health and alerts:
|
||||
- Alert correlation
|
||||
- Trend analysis
|
||||
- Root cause identification
|
||||
- Metric visualization
|
||||
- Proactive issue detection
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: deployment-specialist
|
||||
description: Handles all deployment operations
|
||||
tools: read, write, bash, grep
|
||||
---
|
||||
|
||||
# Deployment Specialist
|
||||
|
||||
Expert in deployment operations:
|
||||
- Blue-green deployments
|
||||
- Canary releases
|
||||
- Rollback procedures
|
||||
- Health checks
|
||||
- Database migrations
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: incident-commander
|
||||
description: Coordinates incident response
|
||||
tools: read, write, bash, grep
|
||||
---
|
||||
|
||||
# Incident Commander
|
||||
|
||||
Manages incident response:
|
||||
- Severity assessment
|
||||
- Team coordination
|
||||
- Status updates
|
||||
- Resolution tracking
|
||||
- Post-mortem facilitation
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
name: Deploy
|
||||
description: Deploy application to production or staging
|
||||
---
|
||||
|
||||
# Deploy Application
|
||||
|
||||
Execute deployment workflow:
|
||||
|
||||
1. Run pre-deployment checks
|
||||
2. Build application
|
||||
3. Run tests
|
||||
4. Deploy to target environment
|
||||
5. Run health checks
|
||||
6. Notify team on Slack
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
name: Incident Response
|
||||
description: Handle production incidents with structured response
|
||||
---
|
||||
|
||||
# Incident Response
|
||||
|
||||
Structured incident response workflow:
|
||||
|
||||
1. Create incident record
|
||||
2. Assess severity and impact
|
||||
3. Notify on-call team
|
||||
4. Gather diagnostic information
|
||||
5. Coordinate response efforts
|
||||
6. Document resolution
|
||||
7. Schedule post-mortem
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Rollback
|
||||
description: Rollback to previous deployment
|
||||
---
|
||||
|
||||
# Rollback Deployment
|
||||
|
||||
Rollback to previous stable version:
|
||||
|
||||
1. Identify previous deployment
|
||||
2. Verify rollback target is healthy
|
||||
3. Execute rollback procedure
|
||||
4. Run health checks
|
||||
5. Notify team
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
name: System Status
|
||||
description: Check overall system health and status
|
||||
---
|
||||
|
||||
# System Status Check
|
||||
|
||||
Check system health across all services:
|
||||
|
||||
1. Query Kubernetes pod status
|
||||
2. Check database connections
|
||||
3. Monitor API response times
|
||||
4. Review error rates
|
||||
5. Check resource utilization
|
||||
6. Report overall health
|
||||
@@ -0,0 +1,34 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Post-deployment hook
|
||||
* Runs after deployment completes
|
||||
*/
|
||||
|
||||
async function postDeploy() {
|
||||
console.log('Running post-deployment tasks...');
|
||||
|
||||
const { execSync } = require('child_process');
|
||||
|
||||
// Wait for pods to be ready
|
||||
console.log('Waiting for pods to be ready...');
|
||||
try {
|
||||
execSync('kubectl wait --for=condition=ready pod -l app=myapp --timeout=300s', {
|
||||
stdio: 'inherit'
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('❌ Pods failed to become ready');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Run smoke tests
|
||||
console.log('Running smoke tests...');
|
||||
// Add your smoke test commands here
|
||||
|
||||
console.log('✅ Post-deployment tasks complete');
|
||||
}
|
||||
|
||||
postDeploy().catch(error => {
|
||||
console.error('Post-deploy hook failed:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
@@ -0,0 +1,35 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Pre-deployment hook
|
||||
* Validates environment and prerequisites before deployment
|
||||
*/
|
||||
|
||||
async function preDeploy() {
|
||||
console.log('Running pre-deployment checks...');
|
||||
|
||||
const { execSync } = require('child_process');
|
||||
|
||||
// Check if kubectl is installed
|
||||
try {
|
||||
execSync('which kubectl', { stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
console.error('❌ kubectl not found. Please install Kubernetes CLI.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Check if connected to cluster
|
||||
try {
|
||||
execSync('kubectl cluster-info', { stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
console.error('❌ Not connected to Kubernetes cluster');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('✅ Pre-deployment checks passed');
|
||||
}
|
||||
|
||||
preDeploy().catch(error => {
|
||||
console.error('Pre-deploy hook failed:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"kubernetes": {
|
||||
"command": "npx",
|
||||
"args": ["@modelcontextprotocol/server-kubernetes"],
|
||||
"env": {
|
||||
"KUBECONFIG": "${KUBECONFIG}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,28 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🚀 Starting deployment..."
|
||||
|
||||
# Load environment
|
||||
ENV=${1:-staging}
|
||||
echo "📦 Target environment: $ENV"
|
||||
|
||||
# Pre-deployment checks
|
||||
echo "✓ Running pre-deployment checks..."
|
||||
npm run lint
|
||||
npm test
|
||||
|
||||
# Build
|
||||
echo "🔨 Building application..."
|
||||
npm run build
|
||||
|
||||
# Deploy
|
||||
echo "🚢 Deploying to $ENV..."
|
||||
kubectl apply -f k8s/$ENV/
|
||||
|
||||
# Health check
|
||||
echo "🏥 Running health checks..."
|
||||
sleep 10
|
||||
curl -f http://api.$ENV.example.com/health
|
||||
|
||||
echo "✅ Deployment complete!"
|
||||
@@ -0,0 +1,30 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "🏥 System Health Check"
|
||||
echo "===================="
|
||||
|
||||
ENV=${1:-production}
|
||||
|
||||
# Check API
|
||||
echo -n "API: "
|
||||
if curl -sf http://api.$ENV.example.com/health > /dev/null; then
|
||||
echo "✅ Healthy"
|
||||
else
|
||||
echo "❌ Unhealthy"
|
||||
fi
|
||||
|
||||
# Check Database
|
||||
echo -n "Database: "
|
||||
if pg_isready -h db.$ENV.example.com > /dev/null 2>&1; then
|
||||
echo "✅ Healthy"
|
||||
else
|
||||
echo "❌ Unhealthy"
|
||||
fi
|
||||
|
||||
# Check Pods
|
||||
echo -n "Kubernetes Pods: "
|
||||
PODS_READY=$(kubectl get pods -n $ENV --no-headers | grep "Running" | wc -l)
|
||||
PODS_TOTAL=$(kubectl get pods -n $ENV --no-headers | wc -l)
|
||||
echo "$PODS_READY/$PODS_TOTAL ready"
|
||||
|
||||
echo "===================="
|
||||
@@ -0,0 +1,25 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "⏪ Starting rollback..."
|
||||
|
||||
ENV=${1:-staging}
|
||||
echo "📦 Target environment: $ENV"
|
||||
|
||||
# Get previous deployment
|
||||
PREVIOUS=$(kubectl rollout history deployment/app -n $ENV | tail -2 | head -1 | awk '{print $1}')
|
||||
echo "🔄 Rolling back to revision: $PREVIOUS"
|
||||
|
||||
# Execute rollback
|
||||
kubectl rollout undo deployment/app -n $ENV
|
||||
|
||||
# Wait for rollback
|
||||
echo "⏳ Waiting for rollback to complete..."
|
||||
kubectl rollout status deployment/app -n $ENV
|
||||
|
||||
# Health check
|
||||
echo "🏥 Running health checks..."
|
||||
sleep 5
|
||||
curl -f http://api.$ENV.example.com/health
|
||||
|
||||
echo "✅ Rollback complete!"
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"name": "documentation",
|
||||
"version": "1.0.0",
|
||||
"description": "Comprehensive documentation generation and maintenance",
|
||||
"author": {
|
||||
"name": "Community"
|
||||
},
|
||||
"license": "MIT"
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# Documentation Plugin
|
||||
|
||||
Comprehensive documentation generation and maintenance for your project.
|
||||
|
||||
## Features
|
||||
|
||||
✅ API documentation generation
|
||||
✅ README creation and updates
|
||||
✅ Documentation synchronization
|
||||
✅ Code comment improvements
|
||||
✅ Example generation
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
/plugin install documentation
|
||||
```
|
||||
|
||||
## What's Included
|
||||
|
||||
### Slash Commands
|
||||
- `/generate-api-docs` - Generate API documentation
|
||||
- `/generate-readme` - Create or update README
|
||||
- `/sync-docs` - Sync docs with code changes
|
||||
- `/validate-docs` - Validate documentation
|
||||
|
||||
### Subagents
|
||||
- `api-documenter` - API documentation specialist
|
||||
- `code-commentator` - Code comment improvements
|
||||
- `example-generator` - Code example creation
|
||||
|
||||
### Templates
|
||||
- `api-endpoint.md` - API endpoint documentation template
|
||||
- `function-docs.md` - Function documentation template
|
||||
- `adr-template.md` - Architecture Decision Record template
|
||||
|
||||
### MCP Servers
|
||||
- GitHub integration for documentation syncing
|
||||
|
||||
## Usage
|
||||
|
||||
### Generate API Documentation
|
||||
```
|
||||
/generate-api-docs
|
||||
```
|
||||
|
||||
### Create README
|
||||
```
|
||||
/generate-readme
|
||||
```
|
||||
|
||||
### Sync Documentation
|
||||
```
|
||||
/sync-docs
|
||||
```
|
||||
|
||||
### Validate Documentation
|
||||
```
|
||||
/validate-docs
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code 1.0+
|
||||
- GitHub access (optional)
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
User: /generate-api-docs
|
||||
|
||||
Claude:
|
||||
1. Scans all API endpoints in /src/api/
|
||||
2. Delegates to api-documenter subagent
|
||||
3. Extracts function signatures and JSDoc
|
||||
4. Organizes by module/endpoint
|
||||
5. Uses api-endpoint.md template
|
||||
6. Generates comprehensive markdown docs
|
||||
7. Includes curl, JavaScript, and Python examples
|
||||
|
||||
Result:
|
||||
✅ API documentation generated
|
||||
📄 Files created:
|
||||
- docs/api/users.md
|
||||
- docs/api/auth.md
|
||||
- docs/api/products.md
|
||||
📊 Coverage: 23/23 endpoints documented
|
||||
```
|
||||
|
||||
## Templates Usage
|
||||
|
||||
### API Endpoint Template
|
||||
Use for documenting REST API endpoints with full examples.
|
||||
|
||||
### Function Documentation Template
|
||||
Use for documenting individual functions/methods.
|
||||
|
||||
### ADR Template
|
||||
Use for documenting architectural decisions.
|
||||
|
||||
## Configuration
|
||||
|
||||
Set up GitHub token for documentation syncing:
|
||||
```bash
|
||||
export GITHUB_TOKEN="your_github_token"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep documentation close to code
|
||||
- Update docs with code changes
|
||||
- Include practical examples
|
||||
- Validate regularly
|
||||
- Use templates for consistency
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: api-documenter
|
||||
description: API documentation specialist
|
||||
tools: read, write, grep
|
||||
---
|
||||
|
||||
# API Documenter
|
||||
|
||||
Creates comprehensive API documentation:
|
||||
- Endpoint documentation
|
||||
- Parameter descriptions
|
||||
- Response schemas
|
||||
- Code examples (curl, JS, Python)
|
||||
- Error codes
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: code-commentator
|
||||
description: Code comment and inline documentation specialist
|
||||
tools: read, write, edit
|
||||
---
|
||||
|
||||
# Code Commentator
|
||||
|
||||
Improves code documentation:
|
||||
- JSDoc/docstring comments
|
||||
- Inline explanations
|
||||
- Parameter descriptions
|
||||
- Return type documentation
|
||||
- Usage examples
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: example-generator
|
||||
description: Code example and tutorial specialist
|
||||
tools: read, write
|
||||
---
|
||||
|
||||
# Example Generator
|
||||
|
||||
Creates practical code examples:
|
||||
- Getting started guides
|
||||
- Common use cases
|
||||
- Integration examples
|
||||
- Best practices
|
||||
- Troubleshooting scenarios
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
name: Generate API Documentation
|
||||
description: Generate comprehensive API documentation from source code
|
||||
---
|
||||
|
||||
# API Documentation Generator
|
||||
|
||||
Generate complete API documentation:
|
||||
|
||||
1. Scan API endpoints
|
||||
2. Extract function signatures and JSDoc
|
||||
3. Organize by module/endpoint
|
||||
4. Create markdown with examples
|
||||
5. Include request/response schemas
|
||||
6. Add error documentation
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
name: Generate README
|
||||
description: Create or update project README
|
||||
---
|
||||
|
||||
# README Generator
|
||||
|
||||
Generate comprehensive README:
|
||||
|
||||
1. Project overview and description
|
||||
2. Installation instructions
|
||||
3. Usage examples
|
||||
4. API documentation links
|
||||
5. Contributing guidelines
|
||||
6. License information
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Sync Documentation
|
||||
description: Sync documentation with code changes
|
||||
---
|
||||
|
||||
# Documentation Sync
|
||||
|
||||
Synchronize documentation with codebase:
|
||||
|
||||
1. Detect code changes
|
||||
2. Identify outdated documentation
|
||||
3. Update affected docs
|
||||
4. Verify examples still work
|
||||
5. Update version numbers
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Validate Documentation
|
||||
description: Validate documentation for completeness and accuracy
|
||||
---
|
||||
|
||||
# Documentation Validation
|
||||
|
||||
Validate documentation quality:
|
||||
|
||||
1. Check for broken links
|
||||
2. Verify code examples
|
||||
3. Ensure completeness
|
||||
4. Check formatting
|
||||
5. Validate against actual code
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
# ADR [Number]: [Title]
|
||||
|
||||
## Status
|
||||
[Proposed | Accepted | Deprecated | Superseded]
|
||||
|
||||
## Context
|
||||
What is the issue that we're seeing that is motivating this decision or change?
|
||||
|
||||
## Decision
|
||||
What is the change that we're proposing and/or doing?
|
||||
|
||||
## Consequences
|
||||
What becomes easier or more difficult to do because of this change?
|
||||
|
||||
### Positive
|
||||
- Benefit 1
|
||||
- Benefit 2
|
||||
|
||||
### Negative
|
||||
- Drawback 1
|
||||
- Drawback 2
|
||||
|
||||
### Neutral
|
||||
- Consideration 1
|
||||
- Consideration 2
|
||||
|
||||
## Alternatives Considered
|
||||
What other options were considered and why were they not chosen?
|
||||
|
||||
### Alternative 1
|
||||
Description and reason for not choosing.
|
||||
|
||||
### Alternative 2
|
||||
Description and reason for not choosing.
|
||||
|
||||
## References
|
||||
- Related ADRs
|
||||
- External documentation
|
||||
- Discussion links
|
||||
@@ -0,0 +1,101 @@
|
||||
# [METHOD] /api/v1/[endpoint]
|
||||
|
||||
## Description
|
||||
Brief explanation of what this endpoint does.
|
||||
|
||||
## Authentication
|
||||
Required authentication method (e.g., Bearer token).
|
||||
|
||||
## Parameters
|
||||
|
||||
### Path Parameters
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| id | string | Yes | Resource ID |
|
||||
|
||||
### Query Parameters
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| page | integer | No | Page number (default: 1) |
|
||||
| limit | integer | No | Items per page (default: 20) |
|
||||
|
||||
### Request Body
|
||||
```json
|
||||
{
|
||||
"field": "value"
|
||||
}
|
||||
```
|
||||
|
||||
## Responses
|
||||
|
||||
### 200 OK
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "123",
|
||||
"name": "Example"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 400 Bad Request
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Invalid input"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "Resource not found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### cURL
|
||||
```bash
|
||||
curl -X GET "https://api.example.com/api/v1/endpoint" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
```javascript
|
||||
const response = await fetch('/api/v1/endpoint', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer token',
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
const data = await response.json();
|
||||
```
|
||||
|
||||
### Python
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
'https://api.example.com/api/v1/endpoint',
|
||||
headers={'Authorization': 'Bearer token'}
|
||||
)
|
||||
data = response.json()
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
- 1000 requests per hour for authenticated users
|
||||
- 100 requests per hour for public endpoints
|
||||
|
||||
## Related Endpoints
|
||||
- [GET /api/v1/related](#)
|
||||
- [POST /api/v1/related](#)
|
||||
@@ -0,0 +1,50 @@
|
||||
# Function: `functionName`
|
||||
|
||||
## Description
|
||||
Brief description of what the function does.
|
||||
|
||||
## Signature
|
||||
```typescript
|
||||
function functionName(param1: Type1, param2: Type2): ReturnType
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| param1 | Type1 | Yes | Description of param1 |
|
||||
| param2 | Type2 | No | Description of param2 |
|
||||
|
||||
## Returns
|
||||
**Type**: `ReturnType`
|
||||
|
||||
Description of what is returned.
|
||||
|
||||
## Throws
|
||||
- `Error`: When invalid input is provided
|
||||
- `TypeError`: When wrong type is passed
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Usage
|
||||
```typescript
|
||||
const result = functionName('value1', 'value2');
|
||||
console.log(result);
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
```typescript
|
||||
const result = functionName(
|
||||
complexParam1,
|
||||
{ option: true }
|
||||
);
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Additional notes or warnings
|
||||
- Performance considerations
|
||||
- Best practices
|
||||
|
||||
## See Also
|
||||
- [Related Function](#)
|
||||
- [API Documentation](#)
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"name": "pr-review",
|
||||
"version": "1.0.0",
|
||||
"description": "Complete PR review workflow with security, testing, and docs",
|
||||
"author": {
|
||||
"name": "Anthropic"
|
||||
},
|
||||
"license": "MIT"
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# PR Review Plugin
|
||||
|
||||
Complete PR review workflow with security, testing, and documentation checks.
|
||||
|
||||
## Features
|
||||
|
||||
✅ Security analysis
|
||||
✅ Test coverage checking
|
||||
✅ Documentation verification
|
||||
✅ Code quality assessment
|
||||
✅ Performance impact analysis
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
/plugin install pr-review
|
||||
```
|
||||
|
||||
## What's Included
|
||||
|
||||
### Slash Commands
|
||||
- `/review-pr` - Comprehensive PR review
|
||||
- `/check-security` - Security-focused review
|
||||
- `/check-tests` - Test coverage analysis
|
||||
|
||||
### Subagents
|
||||
- `security-reviewer` - Security vulnerability detection
|
||||
- `test-checker` - Test coverage analysis
|
||||
- `performance-analyzer` - Performance impact evaluation
|
||||
|
||||
### MCP Servers
|
||||
- GitHub integration for PR data
|
||||
|
||||
### Hooks
|
||||
- `pre-review.js` - Pre-review validation
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic PR Review
|
||||
```
|
||||
/review-pr
|
||||
```
|
||||
|
||||
### Security Check Only
|
||||
```
|
||||
/check-security
|
||||
```
|
||||
|
||||
### Test Coverage Check
|
||||
```
|
||||
/check-tests
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code 1.0+
|
||||
- GitHub access
|
||||
- Git repository
|
||||
|
||||
## Configuration
|
||||
|
||||
Set up your GitHub token:
|
||||
```bash
|
||||
export GITHUB_TOKEN="your_github_token"
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
User: /review-pr
|
||||
|
||||
Claude:
|
||||
1. Runs pre-review hook (validates git repo)
|
||||
2. Fetches PR data via GitHub MCP
|
||||
3. Delegates security review to security-reviewer subagent
|
||||
4. Delegates testing to test-checker subagent
|
||||
5. Delegates performance to performance-analyzer subagent
|
||||
6. Synthesizes all findings
|
||||
7. Provides comprehensive review report
|
||||
|
||||
Result:
|
||||
✅ Security: No critical issues found
|
||||
⚠️ Testing: Coverage is 65%, recommend 80%+
|
||||
✅ Performance: No significant impact
|
||||
📝 Recommendations: Add tests for edge cases
|
||||
```
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: performance-analyzer
|
||||
description: Performance impact analysis
|
||||
tools: read, grep, bash
|
||||
---
|
||||
|
||||
# Performance Analyzer
|
||||
|
||||
Evaluates performance impact of changes:
|
||||
- Algorithm complexity
|
||||
- Database query efficiency
|
||||
- Memory usage
|
||||
- Caching opportunities
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Security-focused code review
|
||||
tools: read, grep, diff
|
||||
---
|
||||
|
||||
# Security Reviewer
|
||||
|
||||
Specializes in finding security vulnerabilities:
|
||||
- Authentication/authorization issues
|
||||
- Data exposure
|
||||
- Injection attacks
|
||||
- Secure configuration
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: test-checker
|
||||
description: Test coverage and quality analysis
|
||||
tools: read, bash, grep
|
||||
---
|
||||
|
||||
# Test Checker
|
||||
|
||||
Analyzes test coverage and quality:
|
||||
- Coverage percentage
|
||||
- Missing test cases
|
||||
- Test quality assessment
|
||||
- Edge case identification
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Security Check
|
||||
description: Run security-focused code review
|
||||
---
|
||||
|
||||
# Security Check
|
||||
|
||||
Perform focused security analysis on code changes:
|
||||
|
||||
1. Authentication/authorization checks
|
||||
2. Data exposure risks
|
||||
3. Injection vulnerabilities
|
||||
4. Cryptographic weaknesses
|
||||
5. Sensitive data in logs
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Test Coverage Check
|
||||
description: Verify test coverage and quality
|
||||
---
|
||||
|
||||
# Test Coverage Check
|
||||
|
||||
Analyze test coverage and quality:
|
||||
|
||||
1. Check test coverage percentage
|
||||
2. Identify untested code paths
|
||||
3. Review test quality
|
||||
4. Suggest missing test cases
|
||||
5. Verify edge cases are covered
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Review PR
|
||||
description: Start comprehensive PR review with security and testing checks
|
||||
---
|
||||
|
||||
# PR Review
|
||||
|
||||
This command initiates a complete pull request review including:
|
||||
|
||||
1. Security analysis
|
||||
2. Test coverage verification
|
||||
3. Documentation updates
|
||||
4. Code quality checks
|
||||
5. Performance impact assessment
|
||||
@@ -0,0 +1,37 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Pre-review hook
|
||||
* Runs before starting PR review to ensure prerequisites are met
|
||||
*/
|
||||
|
||||
async function preReview() {
|
||||
console.log('Running pre-review checks...');
|
||||
|
||||
// Check if git repository
|
||||
const { execSync } = require('child_process');
|
||||
try {
|
||||
execSync('git rev-parse --git-dir', { stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
console.error('❌ Not a git repository');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Check for uncommitted changes
|
||||
try {
|
||||
const status = execSync('git status --porcelain', { encoding: 'utf-8' });
|
||||
if (status.trim()) {
|
||||
console.warn('⚠️ Warning: Uncommitted changes detected');
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('❌ Failed to check git status');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('✅ Pre-review checks passed');
|
||||
}
|
||||
|
||||
preReview().catch(error => {
|
||||
console.error('Pre-review hook failed:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user