🚀 AI 助手环境一键管理中枢。通过单一入口，只对 Claude Code、Codex、Antigravity CLI 做 Agent 生命周期、MCP、skills 和 rules 管理。退役 Agent 的旧路径只保留必要的清理/迁移逻辑，不再作为受管目标维护。
本项目严格遵循各 Agent 官方最新规范，确保配置注入的精准与安全：
┌────────────────┬─────────────────────────┬──────────┬─────────────┐
│ Agent 名称 │ 官方标准路径 │ 文件格式 │ 核心键名 │
├────────────────┼─────────────────────────┼──────────┼─────────────┤
│ Claude Code │ ~/.claude.json │ JSON │ mcpServers │
│ Antigravity CLI │ ~/.gemini/antigravity-cli/mcp_config.json │ JSON │ mcpServers │
│ Codex │ ~/.codex/config.toml │ TOML │ mcp_servers │
└────────────────┴─────────────────────────┴──────────┴─────────────┘
chrome-devtools- 用途：
Chrome DevTools调试、网络、性能分析。 - 启动：
npx -y chrome-devtools-mcp@<固定版本> --isolated（避免多个 agent 共享同一个 browser profile 导致互相污染）。
- 用途：
grok-search- 用途：联网搜索与网页抓取。
- 注意：真实 provider key 仅从
secrets/注入。
augment-context-engine- 定义仍保留；缺少
AUGMENT_SESSION_AUTH时默认不启用。
- 定义仍保留；缺少
chrome-devtools（MCP）- 由
make update刷新本机config/version-pins.local.json中的版本锁；各 Agent 实际运行时只消费固定版本。 默认受管 skill 仓库当前包含agent-skills、anthropic-frontend-design-skill和playwright-best-practices-skill；它们的仓库、升级策略和初始 commit 保留在config/skills.json，真实运行 commit 由config/version-pins.local.json的本地锁覆盖，并由make update按latest-branch策略刷新。运行时同步只检出固定 commit，不直接跟随默认分支。agent-skills面向Claude Code、Antigravity CLI与Codex暴露，并通过显式skill_paths锁定为当前声明的safe-merge-review、fix-ones-bug、qa-self-verify、architecture-change-review、code-style-contracts、frontend-verification、legacy-unit-test、artifact-hygiene、reader-facing-writing这 9 个 skill 包，避免上游新增 skill 被默认带入；anthropic-frontend-design-skill仅面向Claude Code暴露，并通过显式skill_paths锁定 Anthropic 官方skills/frontend-design。OpenAI 官方仓库当前最新主分支已不再提供frontend-skill，因此默认清单不再引用该路径，避免make all在刷新上游 commit 时失败。 默认自动安装的 Agent 当前只包含Claude Code、Codex和Antigravity CLI。Claude Code与Codex默认走官方 npm 包，并使用config/agents.json中的命令模板加本机版本锁；Antigravity CLI当前默认走官方 native installer。历史brew安装仅用于识别并提示迁移，不再作为这些 CLI 的受管 provider。Claude Code native仍作为兼容 provider 保留官方 install / update / uninstall 语义，但默认不再使用这条动态 updater 路径。Claude Code local install不纳入agent-managerlifecycle 托管，因为它依赖 shell alias 暴露入口，当前探测链路不会越权接管。 以上 lifecycle 口径统一按三个当前受管 Agent 的官方推荐方式维护。Claude Code和Codex的 npm provider 使用config/agents.json中的命令模板，并由make update刷新本机config/version-pins.local.json；Antigravity CLI使用官方curl -fsSL https://antigravity.google/cli/install.sh | bash安装到agy，不由agent-manager伪造 update 命令。若需要阻止agy启动后的官方后台自更新，按官方文档在 shell 环境设置AGY_CLI_DISABLE_AUTO_UPDATE=true；agent-manager不改写用户 shell profile。放弃brew或不用brew不等于所有 agent 都必须 native installer。
- 由
| CLI | 默认受管 provider | 兼容受管 provider | detect-only 历史来源 | 说明 |
|---|---|---|---|---|
Claude Code |
npm |
native |
brew |
默认使用官方 npm 包固定版本；native installer 仅作为兼容 provider 保留。 |
Codex |
npm |
- | brew |
使用官方 npm 包；安装和升级命令固定到 config/agents.json 的版本锁，历史 brew 安装只用于审计和迁移提示。 |
Antigravity CLI |
native |
- | - | 使用官方 installer 安装 agy；无显式受管 update。确定二进制运行版本依赖官方 AGY_CLI_DISABLE_AUTO_UPDATE=true 环境变量。 |
下表列出上游公开安装渠道，但不等于 agent-manager 会默认或继续托管这些渠道；对 Claude Code、Codex、Antigravity CLI 的实际受管策略以上一节为准。
| 助手名称 | 二进制标识 | 官方 npm / 安装器 | Homebrew 官方源 (macOS) | 备注 |
|---|---|---|---|---|
| Claude Code | claude |
@anthropic-ai/claude-code / 官方 native installer |
cask: claude-code |
受管 lifecycle 默认走 npm 固定版本；brew 仅保留 detect-only 语义。 |
| Codex | codex |
@openai/codex |
cask: codex |
受管 lifecycle 默认走 npm。 |
| Antigravity CLI | agy |
官方 native installer | - | 受管 lifecycle 默认走 https://antigravity.google/cli/install.sh。 |
- 仓库基线 (
manager.json)：保存可审计的默认策略。 - 本地覆盖 (
manager.local.json)：运行时与manager.json深度合并；make ui只写这一层，适合机器本地偏好与私有配置。 - 版本锁 (
version_lock) / skill commit：config/agents.json、config/tools.json、config/mcp.json与config/skills.json保存命令模板、包名、仓库和升级策略；make update查询 npm / Git ref / skill 仓库分支的最新版本并写入本机config/version-pins.local.json。同步到 Codex / Claude Code / Antigravity CLI 的实际运行配置会先套用本地 lock，不得使用@latest、分支名或未固定的 skill 仓库。 - 浏览器前置开关：
browser_us_sync.enabled控制update/bootstrap/all/browser:sync是否执行浏览器 Google US 前置同步。 - 模块化定义 (
agents.json等)：保存官方指令细节，支持 Policy 的强制覆盖。
- 原子化写入 (Atomic Write)：配置文件采用“临时文件原子替换”模式；规则同步中的单文件分发同样使用原子替换，目录型 rules 则采用收敛式同步。
- 内容/结构漂移审计：实时监控物理文件与定义仓库的文件内容偏离，以及规则目录中的陈旧残留。
- 全局状态缓存：审计系统启动时会一次性全量抓取 Homebrew 和 GH 的包状态并在内存中构建哈希索引，避免了对底层包管理器的频繁 I/O 调用。
- 物理路径穿透：即使包管理器未记录，探测器也能通过精准的
PATH扫描与.app目录兜底识别出系统已有的残留环境，从而达成 10 倍以上的性能提升。
- 一键大扫除 (Cleanup)：精准回收受管备份、碎片及冗余日志；覆盖当前受管目标和历史 Gemini 临时 JSON 备份。
- 失效洗刷 (Scrubbing)：自动清理 Agent 目录中的死亡软链。
- 安全入口：直接执行
./manage.sh只显示帮助，不触发同步。 - 不接管终端配置：
agent-manager不再维护~/.zshrc、~/.tmux.conf、iTerm2 动态配置等用户级终端文件，避免把机器/个人偏好写死后扩散到其他电脑。 - 主仓库禁存 secrets：真实凭证只允许存在于独立的
secrets/私有仓库或系统环境变量中；make secrets-check、make smoke、CI 与make doctor会扫描主仓库文件并阻止明文敏感信息落入agent-manager。
- 可编辑源码：跨 Agent 的共享规则片段只维护在
agent-rule/rules/src/，这是仓库内唯一可编辑的 rule source。 - 共享 core 职责：
agent-rule/rules/src/shared/core.md只放所有 Agent 都应始终生效的短规则；这里优先约束“非平凡或有歧义任务先显式说明假设、优先最简单本地改动、保持 surgical edits、按 verification point 推进”。 - 生成产物：面向各 Agent 实际分发的规则文件只维护在
agent-rule/rules/dist/，由构建脚本生成；仓库内不再保留第二套rules/global/*source tree。 - 按 Agent 原生格式分发：Codex 生成
AGENTS.md，Claude 生成CLAUDE.md，Antigravity 生成agent-managerplugin 下的 rules 文件。 - 低频专题进 skill：原
architecture、style、frontend、artifact-hygiene、writing、legacy test seeding等低频专题细节不再通过modules/分发，而是在agent-skills中维护为architecture-change-review、code-style-contracts、frontend-verification、legacy-unit-test、artifact-hygiene、reader-facing-writing。 - 分层原则：always-on 规则只保留触发条件、协作边界和最小行为约束；执行步骤、检查清单、失败边界和验证细节进入 skill；Agent 私有差异只放
agent-rule/rules/src/agents/*/adapter.md，不要把这些内容回灌进 shared core。 - 迁移清理：原生分发会清理旧的
~/.<agent>/rules/global.md和旧rules/modules残留，避免新旧入口并存。 - Claude 记忆分层：根目录
CLAUDE.md只保留仓库级高频记忆，agent-rule/CLAUDE.md和tests/CLAUDE.md承载目录级维护细节。 - Claude hooks：
config/claude-hooks.json生成仓库级.claude/settings.json，用make claude-hooks-sync刷新 deterministic hook 配置。 - Codex hooks：
config/codex-hooks.json生成仓库级.codex/hooks.json，用make codex-hooks-sync刷新 deterministic Codex hook 配置；当前包含PreToolUse的生成产物写保护和Stop的规则构建一致性校验。 - 指令质量评测：
make eval-rules现在同时输出任务成功率、verification、skill exposure 和 always-on instruction budget 指标，并强制校验min_case_count、required_agents、success / verification 阈值。 - 分发清单：
config/rules-targets.list只引用rules/dist/*产物，不直接引用源码片段。 - 维护入口：修改
agent-rule/rules/src/后，先执行make rules-build，再执行make rules:sync。
- 本项目当前以 macOS 为主要验证平台；Linux 路径保持 POSIX 兼容设计，但仍建议在目标环境自行回归验证。
- 在 Windows 上，建议使用 WSL2、Git‑Bash 或 Cygwin 等提供 POSIX 兼容层的环境，以获得完整功能。
- 若希望在原生 PowerShell 或 CMD 中直接使用，需要对脚本进行额外的跨平台改造（将外部命令替换为 PowerShell 等价实现），此工作尚未完成。
./manage.sh: 显示帮助；这是脚本的安全默认入口。make sync: 同步当前配置到 rules，并按已锁定版本对齐 skills / MCP；不处理 Agent / Tool 生命周期，也不刷新版本锁。make update: 刷新 CLI/MCP/tool 版本锁与 skill commit、更新远端资源并收敛本地环境，等待 Agent 生命周期更新完成，但不安装缺失 Agent。make bootstrap: 执行全量安装、更新与同步，并等待 Agent 生命周期安装/升级完成，适合新机器初始化。make install:make bootstrap的兼容别名。make all:make bootstrap的兼容别名。make plan: 预演一次完整bootstrap。make self-update: 仅更新 agent-manager 仓库自身逻辑。make smoke: 运行跨平台安全预演 smoke 校验，基于最小策略文件config/manager.smoke.json验证主入口命令的 dry-run / preview 契约。make secrets-check: 扫描主仓库受控文件，拒绝真实 token / 私钥等明文敏感信息进入agent-manager；secrets/私有仓库和忽略缓存不在扫描范围内。make eval-rules: 运行离线规则效果评测，读取scripts/evals/fixtures/中的固定 JSON 样例并输出稳定的机器可读摘要。make instructions:check: 共享指令、skills exposure 和项目内 hooks 变更前的统一回归门（硬门禁）；会串行跑 instruction-related project contracts、rules budget/layout、skill exposure、rules sync / Claude/Codex managed hooks 契约、eval schema/metric 契约，以及 baseline 规则评测。make doctor/make status: 执行全系统深度体检，并把 warning 细分为可选工具未就绪与托管产物尚未生成两类提示项；同时扫描主仓库中是否存在疑似明文敏感信息。追加--json可输出机器可读诊断报告。make rules-build: 从agent-rule/rules/src/生成agent-rule/rules/dist/下的可分发规则产物。make rules:sync: 将agent-rule/rules/dist/中的规则产物分发到各 Agent 原生入口。make codex-hooks-sync: 刷新仓库级.codex/hooks.json。make fetch-models: 探测并获取 API 端点支持的模型列表 (支持 OpenAI / Anthropic 格式)。make restore: 交互式回滚历史快照。make ui: 启动交互式配置管理中心。
- 根目录
AGENTS.md提供仓库级的 setup、测试命令、done-when 规则与生成文件边界。 agent-rule/AGENTS.md只覆盖agent-rule/rules/src/到agent-rule/rules/dist/的编辑和重建流程。tests/AGENTS.md只覆盖测试命令、fixtures 和 contract-test 的写法。
- 不再内置固定的 secrets 仓库地址。
- 真实的
Tailscale/SSH/ 远程访问信息也必须只存放在外部私有secrets/仓库；当前仓库仅允许占位符和通用说明。 - 需要通过环境变量
SECRETS_REPO_URL或脚本参数显式提供仓库地址，例如：
SECRETS_REPO_URL=https://example.com/your-secrets.git make update
# 或
./scripts/init-secrets.sh https://example.com/your-secrets.gitApache-2.0