SuperAPI AI 工具集

plugin-settings

编程与开发

查看项目

更新于 11-10 18:24

技能介绍

用途

plugin-settings 描述了 Google Antigravity 插件保存“用户可配置设置与状态”的文件模式。插件可在项目目录下创建 .claude/plugin-name.local.md,让同一插件在不同项目中拥有独立配置。该文件由用户管理,不进入版本库,也应加入 .gitignore。

文件结构

文件采用 YAML frontmatter 加 Markdown 正文的形式:

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

# Additional Context

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

frontmatter 存放结构化配置,正文可存放任务描述、附加指令、回传给 Antigravity 的提示词或说明文档。

读取方式

  1. 从 hooks 读取:在脚本中先用 [[ ! -f "$STATE_FILE" ]] 判断文件是否存在,不存在则直接 exit 0;再用 sed -n '/^---$/,/^---$/{ /^---$/d; p; }' 提取 frontmatter,用 grep 加 sed 取出单个字段,比如 enabled、strict_mode,判断是否启用或采用严格校验。
  2. 从命令读取:命令可在步骤中先用 view_file 查看设置文件,解析 frontmatter 后按配置调整处理逻辑。
  3. 从智能体读取:智能体可在指令中引用设置文件,按 enabled、mode 等字段调整行为。
  4. 解析正文:用 awk '/^---$/{i++; next} i>=2' "$FILE" 提取第二个 --- 之后的内容。

常见模式

  • 临时启用 hooks:通过设置文件中的 enabled 开关控制 hook 是否生效,无需修改 hooks.json,但需重启。
  • 智能体状态管理:在文件中记录 agent_name、task_number、pr_number、coordinator_session、dependencies 等,供 hook 协调多个智能体并发送通知。
  • 配置驱动行为:如 validation_level: strict、max_file_size、allowed_extensions、enable_logging,在 hook 或命令中用 case 分支处理不同级别。

创建与维护

命令可引导用户选择配置项,生成 .claude/plugin-name.local.md 并写入 YAML frontmatter,随后提示重启 Google Antigravity。插件 README 应提供模板,并说明修改后需退出并重启(如 claude 或 cc),因为 hook 无法在会话内热替换。

最佳实践

  • 文件名统一用 .claude/plugin-name.local.md,与插件名一致,使用 .local.md 后缀。
  • 将 .claude/*.local.md、.claude/*.local.json 写入 .gitignore 并在 README 说明。
  • 文件不存在时提供合理默认值。
  • 校验字段,如数值范围必须为 1–100,非法时告警并用默认值。
  • 写入用户输入前转义引号;若配置含文件路径,检查是否包含 .. 以防路径穿越。
  • 权限建议为仅用户可读(chmod 600),不共享、不提交。

限制

设置变更必须重启 Google Antigravity 才能被 hook 识别;该模式本身只定义文件格式与解析方法,不提供图形界面或自动热加载。