AI导哈

Git AI注册表管理工具

oag是一个基于Git的AI注册表管理CLI工具，支持为Claude、Codex和OpenCode等工具安装和管理本地项目中的资产。

  • by wrenfix
  • JavaScript
  • 本地部署
  • 14 星标
  • 更新于
在 GitHub 查看 jiaonliao/oag

使用说明

oag

oag 是一个CLI，用于管理基于Git的AI注册表，并将资产安装到Claude、Codex和OpenCode等工具的本地项目中。

文档

奥干什么

  • 将本地计算机连接到远程注册表存储库。
  • 在读取/应用操作之前自动同步注册表。
  • 允许您以交互方式启用/禁用资产（按类型分组），应用于所有兼容的工具。
  • 将资产捆绑到可以并行启用的插件中。
  • 使用安装文件 copy 或 symlink 模式。
  • 跟踪每个项目的已安装项目，以便更新可重复。
  • 处理Claude、Codex和OpenCode配置格式的MCP资产。

主要特点

  • 远程注册表管理 通过Git(clone 首次使用时，然后 fetch + reset).
  • 工具感知安装 内置路径映射，用于：
    • 克劳德
    • 法典
    • 开源代码
  • 交互式选择界面 在 oag install：在一个菜单中选择资产（按类型分组）和插件，一次应用于所有兼容的工具。
  • 插件捆绑包：直接从启用多个共存插件 oag install 菜单。
  • 基于状态的更新 与 oag update.
  • MCP支持 使用格式处理：
    • 克劳德： .mcp.json
    • 食品法典： .codex/config.toml
    • OpenCode： opencode.json

安装

从npm安装：

npm install -g @wrenfix/oag

验证：

oag --help

配置

全局配置路径：

  • ~/.oag/config.json

默认值：

{
  "registryPath": "~/.oag/registry",
  "remote": null
}

最小配置（推荐）：

{
  "remote": {
    "url": "https://github.com/<you>/<your-registry>.git",
    "branch": "main"
  }
}

笔记：

  • 刀具路径映射内置于 oag （未从用户配置中加载）。
  • 如果没有配置遥控器， list / install / update 将提示它。

快速启动（使用fork工作流）

  1. 分叉您的注册表存储库 （例如在GitHub上）。

  2. 点 oag 到你的叉子:

    oag remote add https://github.com/<you>/<your-registry>.git main

  3. 列出可用资产:

    oag list --tool claude

  4. 交互式安装资产和插件:

    oag install --mode copy

    菜单列出了资产类型和 plugins 类别；检查你想要的并做出选择 Save and exit.

  5. 稍后更新已安装的资产:

    oag update

命令

oag remote add <url> [branch]

保存远程注册表位置。

例子：

oag remote add https://github.com/<you>/<your-registry>.git main

oag list [--type <type>] [--tool <name>]

列出已同步注册表中的资产。

选项：

  • --type <type>：按类型筛选（例如 agent, skill, mcp)
  • --tool <name>：按工具兼容性提示筛选（仅显示筛选器）

例子：

oag list --type skill --tool codex

oag install [--project <path>] [--mode <mode>]

交互式地选择资产（按类型分组）和插件，然后在所有兼容的工具之间进行协调。每个选定的资产都会安装到支持它的每个工具中。插件显示为 plugins 同一菜单中的类别；选中插件会启用其捆绑资产，取消选中则会禁用它。选择是完全覆盖：无论在何处选中 Save and exit 成为已安装的集合。

选项：

  • --project <path>：项目根目录（默认：当前目录）
  • --mode <mode>: copy 或 symlink （默认值： copy)

例子：

oag install --project . --mode symlink

注册表中缺少资产或未应用于已配置工具的插件在菜单中显示为不可用（禁用）。已启用但不再可解析的插件将保持原样，而不是被删除。

oag update [--project <path>] [--mode <mode>]

在最近一次注册表提交时重新安装当前管理的资产。

选项：

  • --project <path>：项目根目录（默认：当前目录）
  • --mode <mode>：此运行的强制模式(copy 或 symlink)

例子：

oag update

oag是如何工作的

1） 注册表同步

之前 list, install，以及 update, oag 同步您配置的注册表：

  • 第一次运行：克隆到 ~/.oag/registry/repo （或你的习惯 registryPath)
  • 稍后运行：获取远程、硬重置到配置的分支、清理未跟踪的文件

2） 安装目标（内置）

oag 具有每个资产类型写入位置的内置映射。资产应用于所有兼容的工具。

克劳德

  • agent -> CLAUDE.md
  • subagent -> .claude/agents/<name>.md
  • skill -> .claude/skills/
  • mcp -> .mcp.json

法典

  • agent -> AGENTS.md
  • subagent -> .codex/agents/<name>.toml （由Markdown转换而来）
  • skill -> .codex/skills/
  • mcp -> .codex/config.toml

开源代码

  • agent -> AGENTS.md
  • subagent -> .opencode/agents/<name>.md
  • skill -> .opencode/skills/
  • mcp -> opencode.json

3） 项目状态

已安装的结果在以下位置进行跟踪：

  • .oag/state.json （在项目根目录内）

状态文件具有以下形状 { manual: [...], plugins: {...}, tools: {...} }:

  • manual：单独选择的资产ID（中的非插件复选框 oag install).
  • plugins：启用的插件和每个插件贡献的资产（ plugins 类别在 oag install).
  • tools：每个工具的实际安装记录。

所需的资产集是以下各项的联合 manual 以及每个启用的插件。 update 使用此状态知道应该刷新什么以及在哪里刷新。

插件文件格式

插件文件位于 plugins/*.json 在注册表仓库中，使用平面模式。

例子：

{
  "name": "oag-starter",
  "description": "Project starter plugin for oag",
  "assets": [
    "agent/develop-agent",
    "subagent/code-reviewer",
    "mcp/context7",
    "mcp/chrome-devtools",
    "skill/commit",
    "skill/frontend-design",
    "skill/skill-creator"
  ]
}

笔记：

  • 资产ID的使用 type/name 格式。
  • name 是必需的，并且必须是唯一的； description 是可选的。
  • assets 必须列出至少一个资产ID；每个资产都安装到每个兼容的工具中。
  • 插件共存：启用多个插件会安装其资产的联合。取消选择一个插件只会删除任何已启用的插件或个人不再需要的资产 oag install 选择。

MCP注释

对于 mcp 资产， oag 应用配置更新而不是简单的文件副本：

  • 对于Claude，服务器被合并到 .mcp.json.
  • 对于Codex，服务器写在 mcp_servers 在 .codex/config.toml.
  • 对于OpenCode，服务器被写入 mcp 对象在 opencode.json （例如， { "mcp": { "context7": { ... } } }).
  • 传统OpenCode mcp 在安装/更新过程中，数组格式被迁移为对象格式。
  • 在重新安装/更新期间， oag 使用存储状态安全地回滚/重新应用托管MCP条目。

子代理备注

subagent assets只发送一个Markdown文件，前面的内容最少(name 和 description)系统提示为正文：

  • 对于Claude和OpenCode，Markdown文件被逐字复制到 .claude/agents/<name>.md / .opencode/agents/<name>.md.
  • 对于Codex，其子代理是TOML， oag 将源转换为 .codex/agents/<name>.toml，仅映射 name, description，以及 developer_instructions （身体）。
  • model 和 tools/权限是故意不定义的，因为 字段因工具而异。每个工具都可以继承父级/main 会话的模型和工具。仅当满足以下条件时，才在源中设置工具特定字段 需要它们（它们通过Markdown工具，被Codex忽略）。
  • 子代理资产必须只包含一个文件。

故障排除

  • 错误： No remote configured.
    • 跑 oag remote add <url> [branch] 第一。
  • 错误： Type 'hook' has been removed and is no longer supported.
    • hook 已弃用，无法作为新类型列出/安装。
  • 错误： Type 'prompt' has been removed and is no longer supported.
    • prompt 已弃用，无法作为新类型列出/安装。
  • 错误： Invalid mode '<mode>'. Use symlink or copy.
    • 选择 --mode copy 或 --mode symlink.
  • 插件显示为 (unavailable: ...) 无法办理入住手续 oag install.
    • 注册表中不存在插件的一个或多个资产，或者这些资产不适用于任何配置的工具。修复其中报告的资产ID plugins/*.json.
  • 错误： Invalid plugin: ... (invalid asset ID '...', expected type/name)
    • 使用 type/name 每个资产ID的格式（例如 skill/commit).
  • oag plugin / oag preset / oag list-presets 不再存在。
    • 现在可以在内部选择插件 oag install 一 plugins 菜单中的类别）。没有单独的 plugin 命令。

相关 MCP