ai-agent-rules

AI Rules 是一个命令行工具，用于将多个 AI 编码代理的配置保存在一个由 git 跟踪的单一位置，并通过符号链接将其链接到每个代理预期的配置目录中。其既定目标是“一次编辑，处处应用”，同时仍允许针对每个代理和每台机器进行自定义。 支持的代理及其配置目录： - Amp: ~/.config/amp/（技能位于 ~/.config/agents/skills/） - Claude Code: ~/.claude/（技能位于 ~/.claude/skills/） - Codex CLI: ~/.codex/（技能位于 ~/.agents/skills/） - Gemini CLI: ~/.gemini/（通过 ~/.agents/skills/ 发现技能） - Goose: ~/.config/goose/（技能位于 ~/.config/goose/skills/） - 共享材料，如 AGENTS.md 和技能 安装需要 Python 3.10+ 和 uv。推荐路径是从 PyPI 进行一键设置（uvx --from ai-agent-rules ai-agent-rules setup），该命令会安装符号链接，使 ai-agent-rules 命令（以及 ai-rules 别名）在系统范围内可用，并可选安装辅助工具。--github 标志改为从主分支安装，本地开发使用 uv run ai-agent-rules install。升级命令会检查并安装更新，带有仅检查、强制、跳过升级后安装或仅升级特定工具的选项。 核心命令涵盖设置、安装/同步、状态和检查、配置、排除和覆盖、技能、工具以及 shell 补全。值得注意的行为： - install 支持选择特定代理、试运行预览、自动确认、缓存重建和配置文件选择。 - status 报告符号链接状态、可选工具和活动配置文件，并带有状态符号和差异；validate 检查源文件是否存在；uninstall 移除符号链接。 - config init/show/edit 暴露原始或合并的设置，可选地针对每个代理。 - exclude add/remove/list 管理不应被符号链接的文件的 glob 模式（例如公司管理的文件）。 - override set/unset/list 编辑嵌套设置，包括用于诸如钩子命令数组等结构的数组索引表示法，并带有路径验证，在拼写错误时建议有效键。 - skill list/show 渲染捆绑的技能，可以打印带版本号的 GitHub URL 以供分享，或输出原始 markdown 以便管道传输。 - tool list/show 和 tool source get/set 管理可选工具及其安装来源（pypi、github、本地路径、重置）。 - completions install/uninstall/update/status 以及原始 bash/zsh 脚本输出均已提供。 配置是分层的。用户级文件 ~/.ai-agent-rules-config.yaml 包含排除项和特定机器的 settings_overrides。状态（活动配置文件、上次安装时间戳）位于 ~/.ai-agent-rules/state.yaml，合并的设置缓存在 ~/.ai-agent-rules/cache/ 下。文档化的合并管道是：基础的 git 跟踪设置，然后是配置文件覆盖，然后是用户覆盖，然后是从缓存合并的保留的代理管理字段，然后是缓存，最后是符号链接到代理的目录。保留字段包括 Claude 的 enabledPlugins 和 hooks、Goose 的 extensions、Codex 的 projects 以及 Gemini 的 ide。更改覆盖需要运行 install --rebuild-cache。 配置文件将覆盖分组为命名预设并支持继承；该工具附带三个内置配置文件，链为 default -> personal -> work，其中 default 被描述为通用，personal/work 是作者自己的预设而非一般建议。配置文件可以定义 settings_overrides、plugins、marketplaces、托管工具安装来源、AGENTS.md 片段（agents_md_file，通过继承按父级优先追加，与内联 agents_md 互斥）、排除项和 MCP 覆盖。本地用户配置优先于配置文件覆盖。目前不支持用户定义的配置文件；每台机器的自定义放在用户配置文件中。 MCP 服务器在共享的 mcps.json 中定义一次，并由每个代理的管理器转换为原生格式（Amp、Claude、Gemini 使用 JSON；Codex 使用 TOML；Goose 使用 YAML 扩展）。托管条目带有 _managedBy 标记，以区别于用户添加的服务器，mcp_overrides 允许每台机器的值，如 API 密钥。 Claude Code 插件可以在配置文件或用户配置中声明；install 添加缺失的 marketplaces 和插件，自动卸载以前管理的孤立插件，并警告手动安装的插件而不移除它们。插件状态在托管的 JSON 文件中跟踪。 安全功能包括首次运行警告、带时间戳的备份、交互式提示、试运行模式、声称只管理符号链接且从不删除真实文件，以及上下文错误消息。故障排除指南涵盖错误目标、恢复备份、通过排除禁用符号链接、当覆盖不适用时重建缓存、查看合并设置以及从 pre-v0.35 配置路径自动迁移。该项目采用 MIT 许可证。