Odc Cli

odc CLI

odc 是一个用于编排 AI 编码 agent 团队的 CLI 工具。它管理一个本地 marketplace，包含可复用组件（atoms：commands、skills、hooks、agents、MCP servers）和插件（plugins：一组 atoms 的集合），以及 agent 运行的工作空间（workspaces）。

本文档聚焦高频场景及其最优调用链。完整命令参考请按需读取对应文件：

• references/global.md — 输出模式、全局选项、错误码、--force 行为
• references/atom.md — atom show / files / add / update / delete / set-inject
• references/plugin.md — plugin list / add / update / merge / delete
• references/marketplace.md — marketplace show / sync / history / rollback / regenerate
• references/subscription.md — subscription list / add / remove / enable / disable / refresh
• references/workspace.md — workspace list / show / open / init / reinit / update / add-plugin / remove-plugin
• references/server-config.md — 服务器启动、配置管理

核心约束

以下约束不可违反，影响所有场景：

1. 没有 atom list 命令。 要枚举 atoms，使用 plugin list --json（按插件查看）或 marketplace show（完整注册表）。
2. 本地插件只能引用本地 atoms。 订阅源的 atoms 必须先通过 plugin merge 合并到本地，本地插件才能引用它们。
3. plugin list --json 返回所有插件（本地 + 所有订阅源）。同名插件可能出现多次但 source.type 不同。始终通过 name + source 共同匹配。
4. 获取当前工作空间信息优先读 .aiworkspace.json，它包含 workspace name、plugins、agent type、permission mode。只有在需要其他工作空间信息时才用 workspace show。要获取 plugin 的 atom 详情，仍需 plugin list --json。
5. 非 TTY 环境自动输出 JSON。 通过 Bash 工具调用 odc 时，输出默认为 JSON。第一行可能是 dotenv 注入信息——解析时需处理。
6. 非 TTY 环境下破坏性操作需要 --force。 atom add（覆盖）、atom delete、plugin delete、marketplace rollback 都需要 --force 跳过确认。

高频场景 Playbook

Playbook 1：查询当前工作空间的 Atoms

用户意图： "当前空间有哪些技能/agent/命令"

步骤 1：读取当前工作空间目录下的 .aiworkspace.json
        → 包含 workspace name、plugins 数组（每项有 name + source）
        → 直接读本地文件，无需 CLI 调用

步骤 2：odc plugin list --json
        → 通过 name 和 source.type/source.name 共同匹配每个插件
        → 提取匹配插件的 skills/agents/commands/mcpServers

步骤 3：去重后展示给用户
        → 标注每个 atom 来自哪个插件

如何获取工作空间上下文： 每个 odc 工作空间目录下都有一个 .aiworkspace.json 文件，包含工作空间名称、挂载的插件、agent 类型和权限模式。直接读取此文件，比调用 workspace show 更快且省一次 CLI 调用。

Playbook 2：将工作空间转为单个本地插件

用户意图： "把当前工作空间打包成一个本地 plugin，方便下次直接用"

一个工作空间可能挂载多个插件（本地 + 订阅源）。此 playbook 创建一个包含所有 atoms 的本地插件。

步骤 1：读取当前工作空间目录下的 .aiworkspace.json
        → 获取工作空间名称、所有挂载的插件及其来源

步骤 2：odc plugin list --json
        → 按 name + source 匹配每个挂载的插件
        → 收集所有插件的 atoms（skills、agents、commands、mcpServers）

步骤 3：对列表中的每个订阅源插件执行：
        odc plugin merge  --source 
        → 将订阅源 atoms 复制到本地 marketplace
        → 必须执行：本地插件无法引用订阅源 atoms

步骤 4：odc plugin add  \
          --description "" \
          --category  \
          --skills "" \
          --agents "" \
          --commands "" \
          --mcps ''
        → 创建合并后的本地插件

步骤 5：odc plugin list --json
        → 校验：按新插件名 + source.type=local 过滤
        → 确认 atom 数量符合预期

要点：

• 创建前先对所有插件的 atom 名称去重。
• MCP servers 需要以 JSON 字符串传给 --mcps。
• 创建前询问用户新插件的名称。

Playbook 3：给插件添加 Atom

用户意图： "把 xxx skill 加到 xxx plugin 里"

atom 来源可以是：本地路径、GitHub URL、订阅源、或已在本地 marketplace 中。

步骤 1：将 atom 添加到本地 marketplace（如果还不在的话）

        来自 GitHub URL：
        odc atom add  --type  --force

        来自本地路径：
        odc atom add  --type  --force

        来自订阅源（必须先合并）：
        odc plugin merge  --source 

        已在本地：跳过此步骤。

步骤 2：检查目标插件是否已包含此 atom
        odc plugin list --json
        → 按 name + source 匹配目标插件
        → 检查 atom 名称是否已存在于对应数组（skills/agents/commands）中

步骤 3：如果已包含：
        → 询问用户："该插件已包含 ，是否要覆盖？"
        → 用户确认：继续执行步骤 4
        → 用户拒绝：停止

步骤 4：将 atom 添加到插件
        odc plugin update  --add-skills ""
        （或 --add-agents / --add-commands，取决于 atom 类型）

步骤 5：校验
        odc plugin list --json → 确认 atom 出现在插件中

说明： --add-skills 即使名称已存在也会添加（会重新指向引用）。对于 atom 内容更新（如用 GitHub 版本覆盖），步骤 1 的 --force 处理内容更新；步骤 4 确保插件引用是最新的。

Playbook 4：将插件合并到本地插件

用户意图： "将某个插件合并到本地的某个插件中"

两种情况：来源是订阅源插件，或来源是另一个本地插件。

情况 A：来源是订阅源插件

步骤 1：odc plugin merge  --source 
        → 将订阅源插件的所有 atoms 批量复制到本地 marketplace
        → 同名 atoms 会被强制覆盖
        → 自动重建注册表

步骤 2：odc plugin list --json
        → 校验目标插件是否已包含合并的 atoms

说明： plugin merge 一条命令同时完成 atom 复制和目标插件装配更新，是最高效的路径。

情况 B：来源是另一个本地插件

步骤 1：odc plugin list --json
        → 获取源插件和目标插件的 atom 列表

步骤 2：对每种 atom 类型（skills、agents、commands、mcps）：
        → 识别源插件有但目标插件没有的 atoms
        → 识别两者都有的 atoms（潜在冲突）

步骤 3：如果有重名 atoms，询问用户冲突解决策略

步骤 4：odc plugin update  \
          --add-skills "" \
          --add-agents "" \
          --add-commands "" \
          --add-mcps ''

步骤 5：odc plugin list --json → 校验结果

Playbook 5：注册表故障排查

用户意图： "atom 找不到" / "注册表不对" / E2002 错误

步骤 1：odc marketplace regenerate
        → 从磁盘重建注册表，修复过期索引

步骤 2：odc marketplace show
        → 检查完整注册表，确认 atom 是否存在

步骤 3：如果 atom 仍然缺失：
        → 检查是否被删除或从未添加
        → 如需要，用 odc atom add 重新添加

命令速查表

| 操作 | 命令 | |---|---| | 列出所有插件 | odc plugin list --json | | 查看工作空间详情 | odc workspace show --json | | 查看 atom 内容 | odc atom show | | 列出 atom 文件 | odc atom files | | 从路径/URL 添加 atom | odc atom add --type --force | | 删除 atom | odc atom delete --force | | 创建插件 | odc plugin add --description "..." --skills "a,b" | | 更新插件 atoms | odc plugin update --add-skills "x" --remove-agents "y" | | 合并订阅源到本地 | odc plugin merge --source | | 重建注册表 | odc marketplace regenerate | | 完整注册表导出 | odc marketplace show | | 列出订阅源 | odc subscription list --json | | 刷新订阅源 | odc subscription refresh [name] | | 列出工作空间 | odc workspace list --json | | 初始化工作空间 | odc workspace init [--source ] | | 重新初始化工作空间 | odc workspace reinit | | 为工作空间添加插件 | odc workspace add-plugin [--subscription-name ] | | 从工作空间移除插件 | odc workspace remove-plugin [--subscription-name ] |

完整命令参数请读取本文档顶部列出的对应参考文件。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: open-deep-crew
• Source: open-deep-crew/marketplace
• License: MIT

Install and usage instructions live in the source repository linked above.