# Odc Cli

> 使用 odc CLI 管理 marketplace 的 atoms/plugins、订阅源、工作空间、服务器和配置。当用户提到列出技能、添加 atom、创建插件、合并插件、管理工作空间等 odc 操作时使用此技能——即使用户没有明确说"odc"。

- **Type:** Skill
- **Install:** `agentstack add skill-open-deep-crew-marketplace-odc-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [open-deep-crew](https://agentstack.voostack.com/s/open-deep-crew)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [open-deep-crew](https://github.com/open-deep-crew)
- **Source:** https://github.com/open-deep-crew/marketplace/tree/main/atoms/skills/odc-cli

## Install

```sh
agentstack add skill-open-deep-crew-marketplace-odc-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/open-deep-crew)
- **Source:** [open-deep-crew/marketplace](https://github.com/open-deep-crew/marketplace)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-open-deep-crew-marketplace-odc-cli
- Seller: https://agentstack.voostack.com/s/open-deep-crew
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.