用途
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 的提示词或说明文档。
读取方式
- 从 hooks 读取:在脚本中先用
[[ ! -f "$STATE_FILE" ]]判断文件是否存在,不存在则直接exit 0;再用sed -n '/^---$/,/^---$/{ /^---$/d; p; }'提取 frontmatter,用grep加sed取出单个字段,比如enabled、strict_mode,判断是否启用或采用严格校验。 - 从命令读取:命令可在步骤中先用
view_file查看设置文件,解析 frontmatter 后按配置调整处理逻辑。 - 从智能体读取:智能体可在指令中引用设置文件,按
enabled、mode等字段调整行为。 - 解析正文:用
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 识别;该模式本身只定义文件格式与解析方法,不提供图形界面或自动热加载。