oag (Jiaonliao)

开角型青光眼

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

文档

• 中文自述
• 注册表维护指南（英文）
• 注册表维护指南（中文）

奥干什么

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

主要特点

• 远程注册表管理 通过Git(clone 首次使用时，然后 fetch + reset).
• 工具感知安装 内置路径映射，用于：

- 克劳德 - 法典 - 开源代码

• 交互式选择界面 在 oag install.
• 基于预设的对账安装 通过 oag preset.
• 基于状态的更新 随着 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//.git",
    "branch": "main"
  }
}

笔记：

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

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

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

1. 点 oag 到你的叉子:

   oag remote add https://github.com//.git main

1. 列出可用资产:

   oag list --tool claude

1. 列出可用预设:

   oag list-presets --tool claude

1. 交互式安装资产:

   oag install --tool claude --mode copy

1. 直接应用预设:

   oag preset --tool claude --name oag-starter --mode copy

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

   oag update

命令

oag remote add [branch]

保存远程注册表位置。

例子：

oag remote add https://github.com//.git main

oag list [--type ] [--tool ]

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

选项：

• --type ：按类型筛选（例如 agent, skill, mcp)
• --tool ：按工具兼容性提示筛选

例子：

oag list --type skill --tool codex

`oag install [--tool ] [--project

] [--mode ]`

交互式启用或禁用项目中工具的资源。

选项：

• --tool ：目标工具（例如 claude, codex, opencode)
• `--project

`：项目根目录（默认：当前目录）

• --mode : copy 或 symlink （默认值： copy)

例子：

oag install --tool codex --project . --mode symlink

oag list-presets [--tool ]

列出同步注册表中的预设模板。

选项：

• --tool ：仅显示定义此工具的预设

例子：

oag list-presets --tool codex

`oag preset [--name

] [--tool ] [--project ] [--mode ]`

应用一个预设，并将管理资产与预设集完全对账。

选项：

• `--name

`：预设名称（如果省略，请交互式选择）

• --tool ：目标工具（如果省略，请交互式选择）
• `--project

`：项目根目录（默认：当前目录）

• --mode : copy 或 symlink （默认值： copy)

例子：

oag preset --name oag-starter --tool codex --project . --mode copy

`oag update [--tool ] [--project

] [--mode ]`

重新安装/更新已记录在项目状态中的项目。

选项：

• --tool ：仅更新一个工具
• `--project

`：项目根目录（默认：当前目录）

• --mode ：此运行的强制模式(copy 或 symlink)

例子：

oag update --tool claude

oag是如何工作的

1） 注册表同步

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

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

2） 安装目标（内置）

oag 具有每个资产类型写入位置的内置映射。

克劳德

• agent -> CLAUDE.md
• skill -> .claude/skills/
• mcp -> .mcp.json

法典

• agent -> AGENTS.md
• skill -> .codex/skills/
• mcp -> .codex/config.toml

开源代码

• agent -> AGENTS.md
• skill -> .opencode/skills/
• mcp -> opencode.json

3） 项目状态

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

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

州被使用 update 知道应该刷新什么以及在哪里刷新。

预设文件格式

预设文件位于以下位置 presets/*.json 在您的注册表仓库中。

例子：

{
  "name": "oag-starter",
  "description": "Project starter preset for oag (codex + claude + opencode)",
  "tools": {
    "codex": [
      "agent/develop-agent",
      "mcp/context7",
      "mcp/chrome-devtools",
      "skill/commit",
      "skill/frontend-design",
      "skill/skill-creator"
    ],
    "claude": [
      "agent/develop-agent",
      "mcp/context7",
      "mcp/chrome-devtools",
      "skill/commit",
      "skill/frontend-design",
      "skill/skill-creator"
    ],
    "opencode": [
      "agent/develop-agent",
      "mcp/context7",
      "mcp/chrome-devtools",
      "skill/commit",
      "skill/frontend-design",
      "skill/skill-creator"
    ]
  }
}

笔记：

• 资产ID的使用 type/name 格式。
• name 和 tools 是必需的； description 是可选的。
• tools 必须定义至少一个工具，每个工具 tools. 值必须是字符串数组。
• oag preset 严格：如果所选工具缺少/不支持/未映射任何预设资源，则命令将失败，而不是部分应用。

MCP注释

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

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

故障排除

• 错误： No remote configured.

- 跑 oag remote add [branch] 第一。

• 错误： Type 'hook' has been removed and is no longer supported.

- hook 已弃用，无法作为新类型列出/安装。

• 错误： Type 'prompt' has been removed and is no longer supported.

- prompt 已弃用，无法作为新类型列出/安装。

• 错误： Tool '' is not configured.

- 使用内置工具名称(claude, codex，或 opencode).

• 错误： Invalid mode ''. Use symlink or copy.

- 选择 --mode copy 或 --mode symlink.

• 错误： Preset '' not found

- 检查预设是否存在 presets/*.json 和那个 name 符合你的论点。

• 错误： Preset '' does not define assets for tool ''

- 添加目标工具密钥（例如 codex, claude，或 opencode)under tools.

• 错误： Invalid preset: ... (invalid asset ID '...', expected type/name)

- 使用 type/name 每个资产ID的格式（例如 skill/commit).

• 错误： Preset '' has invalid assets for tool ''

- 修复报告的项目：缺少资产、工具不匹配或缺少路径映射。