igniteui-mcp-testbed

# Ignite UI · MCP / Skills Testbed 一款用于尝试 Ignite UI AI 工具链的单容器设备，搭配 **opencode**（一个开源的 AI 编码代理）。它可以调用两个 **MCP 服务器**（Model Context Protocol 工具，代理可以调用 - 这里是实时 Ignite UI 组件文档/API查找和主题查询）和 **Agent Skills**（指令文件，代理自动加载）。 一个小型网页向导收集您的选择，搭建一个 Ignite UI 项目，连接 AI 配置，并将您交给 opencode。每个会话都在自己的 **全新、短暂的无根 Podman 容器**中运行，因此不同运行之间不会有任何泄露。 ## 您需要 - **Podman**（无根）- 您的机器上唯一需要安装的东西。其他所有东西（Node、.NET、Ignite UI CLI、opencode、无头 Chromium）都已包含在镜像中。在 **Windows** 上使用 PowerShell 脚本（`run.ps1` / `stop.ps1`）；在 **Linux / macOS**（或 Windows Git Bash）上使用 shell 脚本（`run.sh` / `stop.sh`）。两者都可以处理 Windows 与 Linux 之间的路径和标志差异。 - **模型 + API 密钥** - 例如，Anthropic 或 OpenAI 密钥，或本地 OpenAI 兼容端点（Ollama、LM Studio 等）。您将其输入向导；它作为环境变量传递给 opencode，**从不写入磁盘**。无密钥提供商（例如 opencode 的免费托管模型，如 `opencode/big-pickle`）根本不需要密钥 - 只需模型 ID。 ## 快速开始 **Windows (PowerShell):** ```powershell .\run.ps1 build # 构建镜像（podman build -t localhost/igniteui-testbed:latest .） .\run.ps1 build -Prune # 构建，然后删除悬空的 <none> 镜像 .\run.ps1 # 运行一个全新的容器；发布端口 8080 / 4096 / 5000 .\run.ps1 -MatrixConfig .\matrix.json # 运行 + 执行矩阵配置（无需 UI） .\run.ps1 -MatrixConfig .\matrix.json -Validate # 仅验证配置并退出 ``` **Linux / macOS / Git Bash:** ```bash ./run.sh build # 构建镜像 ./run.sh build --prune # 构建，然后删除悬空的 <none> 镜像 ./run.sh # 运行一个全新的容器；发布端口 8080 / 4096 / 5000 ./run.sh --matrix-config ./matrix.json # 运行 + 执行矩阵配置（无需 UI） ./run.sh --matrix-config ./matrix.json --validate # 仅验证配置并退出 ``` 每次重建都会留下前一个未标记的镜像（`<none>`），这会迅速累积（每个镜像约 3 GB）。`-Prune` / `--prune` 标志会在成功构建后运行 `podman image prune -f` 以回收该空间；它只会触及未标记的镜像，而不会触及您的已标记镜像。 ### 许可网格（可选） 历史选项卡使用商业 Ignite UI 网格，因此默认情况下会构建**带有水印的试用版**。要使用许可包构建，请复制 `.env.example` 到 `.env` 并将 `IG_NPM_TOKEN` 设置为 Infragistics 私有源访问令牌（在 <https://account.infragistics.com/access-tokens> 生成），以及 `IG_NPM_USERNAME` 和 `IG_NPM_EMAIL`（您的 Infragistics 帐户登录名和电子邮件 - 源需要这三个） : ```bash cp .env.example .env # 然后编辑 .env 并填写令牌、用户名和电子邮件 ``` `run.sh` / `run.ps1` 将这些写入一个临时的 `.npmrc`，构建会将其绑定挂载以安装许可的 `@infragistics/*` 包 - 没有水印 - 然后在构建后删除它。凭证**仅在构建时使用**（网格被捆绑到镜像中）；运行时容器永远不会看到它们，并且绑定挂载的文件永远不会进入镜像层。`.env` 和 `.npmrc` 都被 gitignore - **永远不要提交您的凭证**。如果要保持试用版本，请将 `IG_NPM_TOKEN` 留空。 打开 <http://localhost:8080>，填写向导并启动。对于交互式会话，opencode web 在新标签页中打开（<http://localhost:4096>），生成的应用程序在 <http://localhost:5000> 运行；向导选项卡保持打开以显示实时统计信息。 > 如果 PowerShell 拒绝运行脚本（“此系统上禁用了运行脚本”），请使用 `Unblock-File .\run.ps1` 取消阻止它一次，或者使用 `pwsh -ExecutionPolicy Bypass -File .\run.ps1` 调用它。 ### 停止会话 容器在前台运行，因此 **Ctrl-C** 在其终端中停止它。要从另一个终端停止，请使用停止脚本（`<session>` 是容器启动时打印的时间戳 - 省略它以停止所有正在运行的测试床容器）： ```powershell .\stop.ps1 # PowerShell - 停止所有 .\stop.ps1 <session> # - 停止一个 ``` ```bash ./stop.sh # Git Bash / Linux / macOS - 停止所有 ./stop.sh <session> # - 停止一个 ``` 容器使用 `--rm` 运行，因此停止也会删除它们；您的会话工件保存在 `./sessions/<timestamp>/` 中，未受影响。 ## 模式 头部切换器在四种视图之间切换： - **配置** - 管理 **提供者包**：JSON 文件，用于教测试床如何搭建和配置第三方库（其自己的搭建/开发服务器命令、MCP 服务器和技能源）。在此加载的包在主机上的 `./providers-data/` 中持续存在（您也可以直接将包 `.json` 文件放入其中），并且它们出现在交互式和矩阵视图中作为额外的平台。[`provider.example.angular-material.json`](provider.example.angular-material.json) 是一个现成的示例（Angular Material）。矩阵配置文件也可以通过其 `providers` 字段内联携带包 - 请参见下文。 - **交互式**（默认）- 搭建一个项目，连接配置，然后交给 opencode web 进行实时会话，并带有流式令牌/成本统计信息。这是下面的“会话工作原理”中的流程。 - **矩阵** - 在 **平台 × 变体** 网格上运行一个共享（变体 = 一组 MCP + 技能开启/关闭）。每个单元格是一个一次性 **无头** 代理运行：它搭建，运行 `opencode run "<prompt>"`，构建已编辑的应用一次，对每个路由进行截图，并运行任何注入的 Playwright 测试（请参见“验证测试”）。使用它来比较，例如，在 Angular / React / Blazor / Web Components 上“启用技能”和“禁用技能”。结果保存在历史记录中。 - **历史记录** - 一个可排序的 Ignite UI 网格，包含每个运行（配置、阶段计时、令牌/成本统计信息、截图、日志），具有可展开的详细行、1-5★ 评分和 Excel 导出。它在 `./sessions/history/` 中持续存在于主机上，因此它在容器之间持续存在 - 不仅仅是当前会话。 ## 从终端运行矩阵 矩阵选项卡收集的所有内容也可以来自 JSON 配置文件，因此可以在不打开 UI 的情况下执行矩阵： ```bash ./run.sh --matrix-config ./matrix.json # Bash .\run.ps1 -MatrixConfig .\matrix.json # PowerShell ``` 文件被绑定挂载到容器中并在启动时加载；默认情况下，矩阵 **自动运行**。向导服务器仍然启动，因此打开 <http://localhost:8080> 显示 **预填充的矩阵表单** 和运行的实时进度 - 可以像任何 UI 配置的矩阵一样调整和重新提交。失败的配置会在启动时停止容器并显示清晰的错误。 进度 **镜像到终端**（`[2/4 react · none · no-skills] — agent —`，每个条目的 ✔/✖ 结果），因此可以在没有 UI 的情况下跟踪配置驱动的运行。当矩阵稳定时，两个工件保存在主机上的 `./sessions/history/reports/<matrixId>/` 中：一个 **静态 HTML 报告**（`report.html` - 摘要表，每个条目的阶段计时，令牌/成本使用情况，测试结果和嵌入的截图；可以直接从文件系统打开，无需容器）和一个 **机器可读的 `summary.json`**（每个条目的状态/持续时间/阶段计时/令牌/成本/测试计数 - CI 作业读取哪些组合回归）。最终的控制台消息指示它们的位置以及可以停止容器。两个都是为 UI 提交的矩阵生成的；设置 `MATRIX_CONSOLE=1` 也可以为它们获取控制台镜像（例如，通过 `podman logs`）。 要检查配置而不运行任何操作，请添加 `--validate` / `-Validate`： ```bash ./run.sh --matrix-config ./matrix.json --validate # Bash .\run.ps1 -MatrixConfig .\matrix.json -Validate # PowerShell ``` 它在容器环境中加载并验证文件（包括提供者包和测试目录），打印配置解析的内容 - 条目，模型，API 密钥是否解析，警告 - 然后退出而不会启动向导或发布端口（安全运行同时另一个测试床启动）。退出代码 0 = 有效，1 = 无效。 复制 [`matrix.example.json`](matrix.example.json) 作为起点： | 字段 | 必需 | 含义 | |---|---|---| | `name` | 否 | 提交的整个名称（最多 80 个字符）。记录在每个条目的历史记录中（在历史记录面板和矩阵标签提示中显示），在报告标题和 `summary.json` 中 - 因此“Tuesday's grid run”无需解码时间戳即可找到。 | | `platforms` | 是 | 内置框架 ID（`angular`、`blazor`、`react`、`webcomponents`）**或任何已注册的提供者包的框架 ID**（来自 `./providers-data/` 或此文件的 `providers` 字段）。未知名称被忽略并发出警告。 | | `variants` | 是 | `{ "mcps": [...], "skills": bool, "localSkills": bool }` 行。对于内置平台，`mcps` ⊆ `igniteui` / `theming` / `custom`；对于提供者平台，请使用包的 MCP 服务器 `class` 名称（+ `custom`）。未选择的平台声明警告加载时。`localSkills` 无 `skills` = 仅本地。重复。 | | `model` | 是 | 模型 ID，例如 `anthropic/claude-sonnet-4-5`。 | | `providers` | 否 | **提供者包定义** 数组（与配置选项卡上传的 JSON 形状相同：`name`、`displayName`、`frameworks[]`、`configure.mcpServers[]`，...）。在启动时在内存中注册 **before** 请求被验证，因此 `platforms` / `mcps` 可以引用它们 - 终端运行在一个文件中完全自包含。像 UI 上传一样，它们 **不** 持久存储到 `./providers-data/`；配置重新注册每个启动（如果有同名的磁盘包，则替换该容器）。具有 `containerDeps.npmGlobal` 的包会发出警告：这些包必须被编译到镜像中。 | | `prompt` | 是 | 共享的每个条目运行。 | | `apiKey` | 否 | **明文提供者 API 密钥** - 不建议；改用以下两个方法之一。 | | `apiKeyEnv` | 否 | 容器内环境变量（env）名称（里面）。 | | *(两者)* | - | 提供者模型的默认前缀被使用（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`OPENROUTER_API_KEY`，`GOOGLE_GENERATIVE_AI_API_KEY`）。运行脚本读取 `.env` 并转发其中任何一个，因此将密钥放入 gitignore 的 `.env` 中是最安全的简单路径。 | | `customMcp` | 否 | 自定义 MCP 服务器定义（s）- 一个 JSON 对象（单个定义，命名映射或完整的 `mcp.json` 形状）或 JSON 字符串。只有包含 `"custom"` 的变体在 `mcps` 中才使用。 | | `customBaseUrl` | 否 | 自定义 OpenAI 兼容基 URL（与 `CUSTOM_API_KEY` 配对）。 | | `selectedTests` | 否 | 验证规格运行为 `<platform>::<category>/<file>` 键（例如 `angular::shared/smoke.spec.ts`）。省略 = 运行所有发现的；`[]` = 运行无。未知键发出警告。 | | `autoRun` | 否 | 默认 `true`。设置为 `false` 仅预填充 UI（文件成为已保存的预设）。 | | `exitOnDone` | 否 | 默认 `false`（容器保持服务 UI 以使结果可浏览）。`true` = 退出时矩阵完成，用于 CI - 退出代码 **0** = 每个条目成功，**2** = 每个条目构建但某些验证测试失败，**1** = 任何更糟糕（构建错误/错误/取消）。 | API 密钥在容器内从不写入磁盘，从不回显到浏览器；从预填充的 UI 提交的矩阵配置带有空密钥字段，会自动回落到配置的密钥。 [`matrix.example.angular-material.json`](matrix.example.angular-material.json) 是 `providers` 字段的完整自包含示例：它定义了一个 **Angular Material** 提供者内联（Angular CLI 搭建 + `@angular/material` / `@angular/cdk` 安装后搭建 - **代理** 留下 Material 布线，这是正在测试的内容）以及 Angular CLI MCP 作为其可切换服务器（类 `angular`），然后运行一个提示并启用/禁用该 MCP： ```bash ./run.sh --matrix-config ./matrix.example.angular-material.json ``` 它的 `containerDeps.npmGlobal` 列表 `@angular/cli`; 搭建工作流程无需编译（npx 需按需获取，速度较慢每个条目）- 将其添加到 Containerfile 的“第三方提供者依赖”部分并重建以跳过每个会话的获取。 ## 适配到您的软件包 这些集成点取决于您设置中的确切软件包和生成的脚本，因此它们最可能需要调整： 1. **`src/frameworks.ts`** — 每个框架的开发服务器命令。默认值假设为 `npm run start` / `npm run dev`（Angular 的 `ng serve`，React / Web 组件使用 Vite）和 Blazor 的 `dotnet watch run`，所有这些都被强制绑定到 `0.0.0.0:5000`。请将这些与您的脚手架实际生成的脚本相匹配。 2. **`Containerfile`** — 全局软件包名称（`opencode-ai`，`igniteui-cli`，`igniteui-theming`）和 Blazor 模板安装行（`dotnet new install <YourTemplateId>`）。 3. **`ig ai-config` 标志** — 通过 `--framework --agents --assistants` 以非交互方式驱动。如果您的 CLI 版本添加了 `--skills` 选择器，请优先使用它而不是生成后修剪。 4. **矩阵模式的 opencode 解析** — 无头运行解析人类 `opencode stats` 报告的令牌 / 成本（`src/capture/usage.ts`），发现路由（`src/capture/route-discovery.ts`），并使用 Playwright / Chromium 对它们进行截图（`src/capture/screenshots.ts`）。`opencode` 输出格式和路由发现启发式方法取决于版本 — 如果较新的 opencode 更改了其 `run` / `stats` 输出，请调整这些。 ## 注意事项和限制 - **固定端口。** Podman 无法在容器创建后添加已发布的端口，因此应用开发服务器绑定到 5000。如果框架拒绝自定义端口，请更改 `APP_PORT`（环境变量）或切换到 `--network=host`（较少的隔离）。 - **opencode web 未加密。** 它默认绑定到 localhost；向导使用 `--hostname 0.0.0.0` 启动它，以便可以访问已发布的端口。在您自己的机器上 — 如果您将其暴露到它之外，请设置 `OPENCODE_SERVER_PASSWORD`。 - **版本敏感集成。** “适配到您的软件包”下的集成点（CLI 软件包名称，`opencode` 输出格式，生成的开发脚本）跟踪特定的工具版本。将针对您的确切工具链的第一次构建视为一个测试。 - **许可网格与试用网格。** 历史记录网格是商业 Ignite UI 组件，因此构建默认使用 **带有水印的试用版本**。在 `.env` 中设置 `IG_NPM_TOKEN`（以及 `IG_NPM_USERNAME` / `IG_NPM_EMAIL`），以构建许可软件包 — 请参见上面的“许可网格（可选）”。没有其他私有注册表身份验证已连接。