Plugin Settings

Claude Code 插件的设置模式

概述

插件可以在项目目录中的 .claude/plugin-name.local.md 文件内存储用户可配置的设置和状态。此模式使用 YAML frontmatter 存储结构化配置，并使用 Markdown 正文存储提示词或其他上下文。

主要特征：

• 文件位置：项目根目录中的 .claude/plugin-name.local.md
• 结构：YAML frontmatter + Markdown 正文
• 用途：按项目配置和存储插件状态
• 用法：从钩子、命令和 Agent 中读取
• 生命周期：由用户管理（不纳入 git，应加入 .gitignore）

文件结构

基本模板

---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude
- Documentation or notes

示例：插件状态文件

.claude/my-plugin.local.md：

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Plugin Configuration

This plugin is configured for standard validation mode.
Contact @team-lead with questions.

读取设置文件

从钩子中读取（Bash 脚本）

模式：检查文件是否存在并解析 frontmatter

#!/bin/bash
set -euo pipefail

# Define state file path
STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if file doesn't exist
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Plugin not configured, skip
fi

# Parse YAML frontmatter (between --- markers)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Extract individual fields
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')

# Check if enabled
if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Use configuration in hook logic
if [[ "$STRICT_MODE" == "true" ]]; then
  # Apply strict validation
  # ...
fi

完整可用示例请参见 examples/read-settings-hook.sh。

从命令中读取

命令可以读取设置文件以自定义行为：

---
description: Process data with plugin
allowed-tools: ["Read", "Bash"]
---

# Process Command

Steps:
1. Check if settings exist at `.claude/my-plugin.local.md`
2. Read configuration using Read tool
3. Parse YAML frontmatter to extract settings
4. Apply settings to processing logic
5. Execute with configured behavior

从 Agent 中读取

Agent 可以在指令中引用设置：

---
name: configured-agent
description: Agent that adapts to project settings
---

Check for plugin settings at `.claude/my-plugin.local.md`.
If present, parse YAML frontmatter and adapt behavior according to:
- enabled: Whether plugin is active
- mode: Processing mode (strict, standard, lenient)
- Additional configuration fields

解析技巧

提取 Frontmatter

# Extract everything between --- markers
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

读取单个字段

字符串字段：

VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

布尔字段：

ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
# Compare: if [[ "$ENABLED" == "true" ]]; then

数值字段：

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
# Use: if [[ $MAX -gt 100 ]]; then

读取 Markdown 正文

提取第二个 --- 之后的内容：

# Get everything after closing ---
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

常见模式

模式 1：临时启用钩子

使用设置文件控制钩子的启用状态：

#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# Read enabled flag
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Run hook logic
# ...

适用场景： 无需编辑 hooks.json 即可启用或禁用钩子（需要重启）。

模式 2：Agent 状态管理

存储特定于 Agent 的状态和配置：

.claude/multi-agent-swarm.local.md：

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# Task Assignment

Implement JWT authentication for the API.

**Success Criteria:**
- Authentication endpoints created
- Tests passing
- PR created and CI green

从钩子中读取，以协调 Agent：

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

# Send notification to coordinator
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

模式 3：由配置驱动的行为

.claude/my-plugin.local.md：

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---

# Validation Configuration

Strict mode enabled for this project.
All writes validated against security policies.

在钩子或命令中使用：

LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)
    # Apply strict validation
    ;;
  standard)
    # Apply standard validation
    ;;
  lenient)
    # Apply lenient validation
    ;;
esac

创建设置文件

从命令中创建

命令可以创建设置文件：

# Setup Command

Steps:
1. Ask user for configuration preferences
2. Create `.claude/my-plugin.local.md` with YAML frontmatter
3. Set appropriate values based on user input
4. Inform user that settings are saved
5. Remind user to restart Claude Code for hooks to recognize changes

生成模板

在插件 README 中提供模板：

## Configuration

Create `.claude/my-plugin.local.md` in your project:

\`\`\`markdown
---
enabled: true
mode: standard
max_retries: 3
---

# Plugin Configuration

Your settings are active.
\`\`\`

After creating or editing, restart Claude Code for changes to take effect.

最佳实践

文件命名

✅ 应该：

• 使用 .claude/plugin-name.local.md 格式
• 与插件名称完全一致
• 用户本地文件使用 .local.md 后缀

❌ 不应该：

• 使用其他目录（而非 .claude/）
• 使用不一致的命名
• 使用不带 .local 的 .md（可能会被提交）

Gitignore

始终将其添加到 .gitignore：

.claude/*.local.md
.claude/*.local.json

在插件 README 中说明这一点。

默认值

设置文件不存在时，提供合理的默认值：

if [[ ! -f "$STATE_FILE" ]]; then
  # Use defaults
  ENABLED=true
  MODE=standard
else
  # Read from file
  # ...
fi

验证

验证设置值：

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

# Validate numeric range
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "⚠️  Invalid max_value in settings (must be 1-100)" >&2
  MAX=10  # Use default
fi

重启要求

重要： 更改设置后需要重启 Claude Code。

在 README 中说明：

## Changing Settings

After editing `.claude/my-plugin.local.md`:
1. Save the file
2. Exit Claude Code
3. Restart: `claude` or `cc`
4. New settings will be loaded

无法在会话中热切换钩子。

安全注意事项

清理用户输入

根据用户输入写入设置文件时：

# Escape quotes in user input
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

# Write to file
cat > "$STATE_FILE" <<EOF
---
user_setting: "$SAFE_VALUE"
---
EOF

验证文件路径

如果设置中包含文件路径：

FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

# Check for path traversal
if [[ "$FILE_PATH" == *".."* ]]; then
  echo "⚠️  Invalid path in settings (path traversal)" >&2
  exit 2
fi

权限

设置文件应当：

• 仅对用户可读（chmod 600）
• 不提交到 git
• 不在用户之间共享

实际示例

multi-agent-swarm 插件

.claude/multi-agent-swarm.local.md：

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: Use JWT tokens, not sessions
---

# Task: Implement Authentication

Build JWT-based authentication for the REST API.
Coordinate with auth-agent on shared types.

钩子用法（agent-stop-notification.sh）：

• 检查文件是否存在（第 15–18 行：不存在则快速退出）
• 解析 frontmatter 以获取 coordinator_session、agent_name、enabled
• 如果启用，则向协调器发送通知
• 可通过 enabled: true/false 快速启用或停用

ralph-wiggum 插件

.claude/ralph-loop.local.md：

---
iteration: 1
max_iterations: 10
completion_promise: "All tests passing and build successful"
---

Fix all the linting errors in the project.
Make sure tests pass after each fix.

钩子用法（stop-hook.sh）：

• 检查文件是否存在（第 15–18 行：未激活则快速退出）
• 读取迭代次数和 max_iterations
• 提取 completion_promise 以终止循环
• 将正文作为提示词读取并反馈
• 每次循环时更新迭代次数

快速参考

文件位置

project-root/
└── .claude/
    └── plugin-name.local.md

Frontmatter 解析

# Extract frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

# Read field
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

正文解析

# Extract body (after second ---)
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

快速退出模式

if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # Not configured
fi

其他资源

参考文件

有关详细的实现模式：

• references/parsing-techniques.md - 解析 YAML frontmatter 和 Markdown 正文的完整指南
• references/real-world-examples.md - 深入介绍 multi-agent-swarm 和 ralph-wiggum 的实现

示例文件

examples/ 中的可运行示例：

• read-settings-hook.sh - 读取并使用设置的 Hook
• create-settings-command.md - 创建设置文件的命令
• example-settings.md - 设置文件模板

实用脚本

​​scripts/ 中的开发工具：

• validate-settings.sh - 验证设置文件结构
• parse-frontmatter.sh - 提取 frontmatter 字段

实现工作流

为插件添加设置：

1. 设计设置架构（字段、类型和默认值）
2. 在插件文档中创建模板文件
3. 为 .claude/*.local.md 添加 gitignore 条目
4. 在 Hook/命令中实现设置解析
5. 使用快速退出模式（检查文件是否存在，检查 enabled 字段）
6. 在插件 README 中通过模板说明设置
7. 提醒用户，更改需要重启 Claude Code 才能生效

设置文件不存在时，应优先保持设置简单，并提供合理的默认值。