# Luxonis Agent Toolkit

Luxonis Agent Toolkit 将当前的 Luxonis 知识和 OAK 特定的开发工作流程引入您的编码代理。它将八种专业技能与 Luxonis MCP 服务器打包在一起。在 Claude Code、Codex 或 Cursor 中安装
Toolkit，然后在您已经使用的编码环境中工作。

对于使用兼容编码代理的开发人员，Luxonis Agent Toolkit 是开始使用 OAK 并构建应用程序的推荐方式。它将摄像头设置、当前 Luxonis 知识和直接测试整合到一个工作流程中，因此您无需先学习所有工具即可从新摄像头过渡到可用的应用程序。

从一个正常的请求开始。您无需选择技能或遵循固定的顺序：

```text
构建一个 OAK 应用程序，用于扫描沿传送带移动的包裹上的条形码。
```

主要的 `luxonis` 技能会确定请求需要什么，通过 Luxonis MCP 服务器检索当前的 Luxonis 文档、示例和模型信息，并在有用时引入专家。

> **Beta**
> Toolkit 的技能及其创建的项目文件可能会在不同版本之间发生变化。使用 Toolkit 加速开发和评估，但在依赖结果之前，请审查生成的计划、代码和证据。

## 您可以使用 Toolkit 做什么

使用 Toolkit 可以：

 * 询问 OAK 和 DepthAI 相关问题或为特定用例选择摄像头。
 * 拆箱并设置新的 OAK 摄像头，然后验证它是否已配置并准备好在您的环境中进行开发。
 * 从头开始，为您的用例构建一个完整的 OAK 应用程序的工作基础。
 * 录制真实场景并在开发过程中回放，无需摄像头。
 * 检查正在运行的管道的帧、深度、检测和其他输出。
 * 诊断失败、挂起或产生错误结果的应用程序。
 * 为目标 OAK 平台转换和集成自定义模型。

对于应用程序工作，目标不仅是让流程运行。代理会从管道中收集直接证据，并验证您实际请求的输出，例如文件、API 响应、MQTT 消息、终端事件或用户界面。

## 安装 Toolkit

Toolkit 的完整插件包括八项技能和位于 `https://mcp.luxonis.com/mcp` 的 Luxonis MCP 服务器。MCP 服务器为代理提供当前的 Luxonis 文档、示例、平台上下文和模型信息。

选择适合您工作方式的安装路径。每个完整插件路径都安装相同的 Luxonis 技能和 MCP 服务器。

> **托管工作区**
> 您的组织可能会限制外部插件市场、插件、连接器或自定义 MCP 服务器。如果工作区策略阻止安装，请要求您的管理员批准 `luxonis/skills` 存储库和位于 `https://mcp.luxonis.com/mcp` 的 Luxonis MCP 服务器。

### 让您的代理安装它

当您的编码代理可以运行命令或引导您完成插件设置时，这是最简单的路径。将以下提示复制到代理中。在批准之前审查任何权限请求。

```text
在此编码代理中安装 Luxonis Agent Toolkit。

该工具包是来自 luxonis/skills 市场 (https://github.com/luxonis/skills) 的“luxonis”插件。它添加了 Luxonis 技能和 Luxonis MCP 服务器，地址为 https://mcp.luxonis.com/mcp。

1. 确定您正在运行的工具（Claude Code、Codex、Cursor 或其他）。
2. 阅读 /software-v3/agent-tools/agent-skills.md 并按照该工具的安装步骤进行操作。
3. 安装工具包，然后告诉我您安装了什么，还需要我批准什么，以及我是否需要重新启动或打开新会话。
4. 不要声称新安装的技能或 MCP 服务器在此会话中可用。告诉我如何在重新启动后或在新会话中验证它们。
```

### 使用命令安装

当您更喜欢自己安装插件时，请使用以下命令。单独运行每个命令，并等待其完成，然后再输入下一个命令。

#### Claude Code

在交互式 Claude Code 提示符中一次输入以下斜杠命令。这些不是用于常规终端 shell 或 Claude 应用程序的命令。

添加 Luxonis 市场：

```text
/plugin marketplace add luxonis/skills
```

安装插件：

```text
/plugin install luxonis@luxonis
```

重新加载插件：

```text
/reload-plugins
```

Claude Code 可能会在首次加载时要求您批准 `luxonis` MCP 服务器。您可以从终端验证连接：

```bash
claude mcp list
```

输出应将 `luxonis` 列为已连接到 `https://mcp.luxonis.com/mcp`。

#### Codex

从终端添加 Luxonis 市场：

```bash
codex plugin marketplace add luxonis/skills
```

安装插件：

```bash
codex plugin add luxonis@luxonis
```

启动新的 Codex 会话，以便它加载技能和 MCP 工具：

```bash
codex
```

您还可以在 Codex 中打开 `/plugins`，选择 `luxonis` 市场，然后在此处安装或启用插件。

#### Cursor

该插件尚未在 Cursor Marketplace 中列出。将存储库克隆到 Cursor 的本地插件目录中，然后重新启动 Cursor：

```bash
git clone https://github.com/luxonis/skills ~/.cursor/plugins/local/luxonis
```

在 Cursor Teams 或 Enterprise 上，管理员可以从 Dashboard → Plugins → Add Marketplace → Import from Repo 将 `luxonis/skills` 添加为团队市场。插件安装包括
Luxonis MCP 服务器。

#### Skills only

以下选项安装技能说明，但不安装 Luxonis MCP 服务器。

使用 `npx` 安装程序：

```bash
npx skills@latest add luxonis/skills
```

对于 Cursor 远程规则，请使用：

```text
luxonis/skills
```

尽可能使用完整的 Toolkit 安装，以便技能可以检索当前的 Luxonis 信息，而不是仅依赖本地上下文。

### 在应用程序中安装

当您不想运行安装命令时，请使用应用程序界面。标签可能会随着应用程序的变化而移动，但流程是相同的：添加 `luxonis/skills` 市场，安装 `Luxonis` 插件，并连接 `luxonis` MCP 服务器。

#### Codex app

打开 Plugins，选择 Add，然后选择 Add a marketplace。

输入 `luxonis/skills` 作为源。将 Git ref 保留为 `main`，将稀疏路径设置为 `plugins/codex`，然后选择 Add marketplace。

搜索 `luxonis`，然后安装 Luxonis 插件。安装后启动新的 Codex 会话，以便加载技能和 MCP 工具。

#### Claude app

打开 Customize → Plugins，选择 Add，然后选择 Add marketplace 和 Add from a repository。

输入 `luxonis/skills` 作为存储库 URL，保持自动同步启用，然后选择 Sync。在它出现后打开 Luxonis 插件，并确保插件已启用。

打开插件的 Connectors 选项卡并安装 `luxonis` 连接器。当 Claude 询问时批准连接。

在新聊天中，打开 Connectors 菜单并确认 Luxonis 已启用，然后才能使用 Toolkit。

## 从您的目标开始

在您希望工作所在的文件夹中打开您的编码代理，然后用简单的语言描述结果。例如：

```text
我应该使用哪种 OAK 摄像头进行户外车牌识别？
```

```text
让这个 OAK 摄像头与这个项目一起工作。
```

```text
构建一个人员计数应用程序，当有人穿过这个门口时发布一个 MQTT 事件。
```

兼容的代理可以自动选择正确的技能。要在 Claude Code 中显式调用主要技能，请使用：

```text
/luxonis:luxonis
```

在 Codex 中，使用：

```text
$luxonis
```

## 应用程序工作如何进行

流程量取决于请求。一个小的首次运行，例如显示深度或流式传输 RGB，不需要完整的产品简介。新的产品应用程序或材料重新设计会获得更多结构。

代理读取项目，仅询问会改变构建的缺失决策，并在工作需要产品简介时将用例记录在 `docs/brief.md` 中。

对于重要的应用程序工作，代理会在 `docs/plans/` 下编写一个带日期的计划。该计划可以包括管道、设备和模型选择、主机与设备放置、用户界面或最终输出、记录策略和验证检查。在继续实施之前审查重要的决策。

代理实现最小的有用垂直切片。在有用时，它会在 `recordings/` 下记录摄像头和 IMU 源，以便开发可以通过回放代表性输入继续进行。

代理使用 `evidence/` 下的有限证据检查正在运行的管道实际产生的结果，然后单独验证请求的最终输出。它报告观察到的内容和尚未证明的内容。

## Toolkit 技能

Toolkit 包括以下专家。当您有狭窄的任务时，您可以直接调用其中一个。否则，从 `luxonis` 开始，让代理路由工作。

| 技能 | 作用 |
| --- | --- |
| `luxonis` | 回答 Luxonis 问题，帮助选择设备，检查工作文件夹，并路由实施工作。 |
| `luxonis-workspace` | 为 Luxonis 开发准备文件夹，包括项目指导、oakctl、DepthAI 环境和词汇表。 |
| `luxonis-app` | 构建或更改 OAK 应用程序并验证请求的行为。 |
| `luxonis-device-setup` | 使 OAK 硬件可用于开发，并将可重用的设置说明记录在 `docs/device.md` 中。 |
| `luxonis-record` | 捕获或回放真实摄像头和 IMU 源的整体记录。 |
| `luxonis-inspect` | 检查正在运行的管道的帧、深度、检测、主题和其他输出。 |
| `luxonis-troubleshoot` | 在现有应用程序中查找并修复第一个可重现的故障层。 |
| `luxonis-model` | 为特定的 OAK 目标转换或集成自定义模型。 |

## 跨会话的项目上下文

Toolkit 将有用的状态保存在项目中，而不是依赖于一个长时间的聊天。文件仅在请求需要时创建。

| 路径 | 目的 |
| --- | --- |
| `AGENTS.md` | 兼容编码代理的始终在线项目指导和指针。 |
| `docs/glossary.md` | 项目词汇和定义。 |
| `docs/brief.md` | 活生生的产品问题和验收行为。 |
| `docs/device.md` | 可重用的主机和设备设置说明。实时设备状态仍然优先。 |
| `docs/plans/` | 带日期的实施计划和当前计划的指针。 |
| `recordings/` | 可以在开发过程中回放的真实摄像头和 IMU 输入。 |
| `evidence/` | 有限的帧、消息和其他运行时观察。 |

## 范围和限制

Toolkit 可以帮助构建和观察 OAK 或 DepthAI 应用程序，包括支持的自定义模型转换和集成。它不能自主训练模型、构建标记的训练数据集、发明专有的 SLAM 系统、提供完整的 ROS 解决方案或认证应用程序用于生产。

当用例依赖于这些系统之一时，代理应明确识别边界，并在仍然有用时继续支持的 OAK 工作。

## 相关

### Toolkit 存储库

浏览源代码、报告问题并检查完整的技能定义。

[在 GitHub 上打开](https://github.com/luxonis/skills)

### oakctl CLI

用于设备设置、应用程序运行和管道检查的主机工具链。

[安装 oakctl](/software-v3/oak-apps/oakctl.md)

### OAK 示例

您的编码代理可以检查和改编的已知良好 DepthAI 应用程序。

[浏览示例](https://github.com/luxonis/oak-examples)
