使用智能体

CukeTest 智能体（CTAgent）是运行在 CukeTest 中的 AI 智能体插件。它面向软件测试与测试开发场景，能够理解测试需求，并在同一工作区内协助完成测试探索、用例设计、自动化脚本生成、代码优化和工程维护等任务。

与普通 AI 聊天工具不同，智能体可以在授权后读取和修改工作区文件，也可以运行终端命令。因此，它不仅能给出建议，还能直接参与项目开发和测试执行流程。

1. 安装与配置

1.1 安装智能体

1. 在 CukeTest 中，点击左侧活动栏的 扩展 图标。
2. 在扩展列表中找到 CukeTest 智能体。

3. 点击 安装。

   

如果扩展列表中没有显示 CukeTest 智能体，请联系产品支持人员获取安装包或启用方式。

1.2 配置智能体

智能体依赖大语言模型（LLM）等后端服务运行。使用前，需要对其进行基础配置，包括 API 密钥、执行权限等。

1. 点击活动栏中的 CukeTest 智能体（CTA）图标。

2. 在智能体面板中，点击 Agent 设置 按钮（带齿轮图标），进入设置页面。

   

3. 根据需求配置以下各项内容：

   • 权限审批：决定智能体在请求执行本地工具或终端命令时的默认处理方式。请参阅 权限管理。
   • Skills：管理本地的自定义技能，用于扩展智能体的特定领域专业技能。请参阅 使用自定义 Skill。
   • 模型配置：展示当前已有的模型服务列表。点击模块右侧的 设置（齿轮） 图标，可以添加或修改模型连接参数，即 OpenAI 接口格式的 API 密钥（API Key）、服务地址（Base Url）和具体模型名称（Model）。
   • MCP：配置智能体可调用的内置或自定义工具，使其拥有与环境交互的能力。请参阅 MCP配置。

配置完成后，点击页面左上角的 返回（向左箭头）按钮即可回到聊天主页面。

2. 启动智能体

使用前，需要先启动智能体，使其能够访问当前工作区并开始接受任务。

1. 点击活动栏中的 CukeTest 智能体（CTA）图标。

2. 在智能体面板中，点击 启动智能体 按钮。

   

3. 启动成功后，底部的输入框会变为激活（可输入）状态。

3. 基本用法

3.1 提交任务

在输入框中直接描述您的目标，例如：

• 阅读当前自动化测试脚本，并给出改进建议。
• 根据这个功能说明生成 BDD 测试用例。
• 重构这个步骤定义文件，提高可维护性。
• 检查项目中的失败用例，并分析可能原因。

当智能体开始执行任务时，聊天窗口会实时展示执行动态，方便您跟踪进度：

• 实时状态与耗时：在消息卡片上方显示任务的状态（如“正在思考”、“正在执行”）及累计处理时长。
• 工作详情（展开查看）：点击消息卡片中的“展开”可查看详细的工作流：
  • 推理思考：智能体分析任务意图、规划方案的逻辑过程。
  • 工具执行：记录了智能体执行的具体操作，如 read_file（读取文件）、run_shell_command（运行命令）等。
  • 交互请求：展示任务执行中发起的提问或操作确认请求。
• 任务进度 (Plan)：复杂任务会自动开启“计划”模式，通过步骤清单展示整体执行路径及当前所处阶段。
• 完成输出：任务处理结束后，智能体将提供最终的结构化建议、代码变更说明或操作总结。

3.2 使用斜杠命令

在输入框中输入 / 可以打开快捷命令菜单。

内置命令包括：

• /explore:web：执行网页自动化探索，并生成对应测试用例。
• /explore:qt：执行 Qt 桌面应用自动化探索，并生成对应测试用例。
• /review:auto-tests：审查自动化测试项目的 .feature 文件、步骤脚本、测试对象模型、项目配置和执行效率，并输出质量报告。
• /review:coverage：审查测试用例设计质量与需求覆盖率，支持从需求文档、已有用例中分析缺口和改进点。

3.3 引用工作区文件

当任务需要针对特定文件处理时，可以使用 @ 引用工作区文件。

1. 触发引用：在输入框中输入 @ 符号。
2. 搜索文件：输入框上方将弹出文件建议列表。您可以继续输入文件名的一部分进行模糊搜索，缩小范围。
3. 完成选择：点击列表项，或使用方向键选中后按回车。被选中的文件将以标签（Pill）的形式显示在输入框内。

添加文件引用后，智能体将获得该文件的上下文，从而能够提供更精准的回答。

3.4 回答交互式提问

处理复杂任务时，智能体可能需要进一步确认目标、框架、执行范围或测试对象。此时，它会在聊天窗口中发起交互式提问。

• 选择式表单：智能体会展示一个包含选项的卡片，您可以直接点击选项来提供所需信息。
• 多步确认：如果有多个问题，卡片上方会显示当前进度，例如 1 / 2，您可以通过导航按钮查看或修改之前的选择。
• 继续或忽略：确认信息后点击 继续，不需要回答时可点击 忽略。

交互式提问可以减少来回沟通，使智能体在执行前获得更准确的上下文。

3.5 查看任务计划

对于多步骤任务，智能体会自动生成任务计划。任务计划用于展示当前目标被拆解后的执行路径。

• 自动拆解：将较大的目标拆分为可执行的子任务。
• 状态跟踪：显示每个步骤的状态，例如待处理、进行中或已完成。
• 过程透明：即使任务涉及多个文件或多次命令执行，也可以清楚看到当前进展。

3.6 预览文件变更

当智能体修改工作区文件后，聊天流中会显示 File Changes 卡片，方便您直观确认修改内容：

• 查看修改细节：点击卡片中的文件名，可以打开 Diff 视图 查看详细的行级代码变更。
• 快速打开文件：将鼠标悬停在文件名上，点击右侧出现的编辑器图标，可直接在当前编辑器中打开该文件。
• 自动保存：确认修改符合预期后，文件通常已经自动保存到本地磁盘。

在接受智能体的修改建议后，建议您执行必要的验证（例如运行测试用例、检查自动化报告或重新打开相关页面验证结果），以确保变更为预期行为。

3.7 管理会话

• 新建会话：点击聊天面板右上角的 + 图标。开始新任务时建议创建新会话，避免旧的上下文对新任务产生干扰。
• 查看历史：点击聊天面板右上角的 历史 图标，可以快速检索并找回之前的对话记录。

4. 权限管理

智能体在读取或修改工作区文件、运行终端命令时，需要相应的执行权限。您有两种方式来设置和切换权限模式：

1. 在设置中预设：在 Agent 设置 页面中，通过 权限审批 配置项将默认处理方式设为 每次询问（即默认权限）或 自动批准全部（即完全访问权限）。

2. 在聊天面板快速切换：在启动智能体后的聊天面板最底部，可以直接查看当前的权限状态。点击权限文本（如 完全访问权限 旁边的下拉三角形），即可在弹出的菜单中快速切换当前的授权模式。

   

• 每次询问（默认权限）：默认的安全策略。智能体在读写文件或运行终端命令前，都会在聊天流中发起提问或操作确认请求，需要您点击批准后才会执行。
• 自动批准全部（完全访问权限）：智能体在运行工具和指令时无需逐次询问，自动执行所有操作，无需手动确认，适合对当前工作区和任务完全信任的场景。

5. MCP（Model Context Protocol）配置

MCP（Model Context Protocol，模型上下文协议）是由 Anthropic 提出的一项开放标准，旨在使大语言模型（LLM）能够以安全、标准化的方式接入外部工具与私有数据源。

在 CukeTest 智能体中，内置了 Web 与桌面自动化探索工具。如果需要使用外部工具、特定数据库或企业内部专有的工具集，您可以通过配置自定义 MCP 服务来扩展智能体的能力边界。

5.1 配置入口

1. 打开 Agent 设置 页面。
2. 滚动至页面底部的 MCP 区域，在 自定义 MCP 栏目下，点击 添加自定义 MCP 服务 按钮，即可打开自定义 MCP 的详细配置页面。

5.2 传输模式（Transport）配置说明

自定义 MCP 配置页面支持三种数据传输协议（Transport）模式。您可以点击 Tab 切换并根据要接入的 MCP 服务类型进行具体配置：

1. STDIO 模式（标准输入输出）

适用于运行在本地系统的命令行 MCP 服务。智能体将通过进程的标准输入输出（STDIO）与之通信。

• 名称：设置此自定义 MCP 服务的唯一名称标识。
• 启动命令：本地 MCP 服务的启动命令或可执行文件路径（例如 node server.js 启动 Node.js 服务，或 python server.py 启动 Python 服务）。
• 参数：如果启动命令需要携带命令行参数，可点击 + 添加参数 按钮进行配置；点击右侧垃圾桶图标可删除参数。
• 环境变量：点击 + 添加环境变量 按钮，可以配置 MCP 服务进程运行时所需的系统环境变量键值对（Key-Value）。

2. HTTP 模式

适用于通过标准的 HTTP 请求暴露接口的远程或本地 MCP 服务。

• 名称：设置此自定义 MCP 服务的唯一名称标识。
• HTTP 地址：服务接口的端点 URL 地址（例如 http://localhost:3000/mcp）。
• 请求头：如果该 HTTP 服务需要鉴权（如 API 密钥、身份令牌）或携带特定的元数据，可点击 + 添加请求头 按钮，增设一组或多组 HTTP 请求头（Header）键值对。

3. SSE 模式（Server-Sent Events，服务器发送事件）

适用于基于 SSE 保持长连接并持续推送事件的 MCP 服务。

• 名称：设置此自定义 MCP 服务的唯一名称标识。
• SSE 地址：SSE 连接的端点 URL 地址（例如 http://localhost:3000/sse）。
• 请求头：点击 + 添加请求头 按钮，配置连接该 SSE 服务时所需的自定义 HTTP 请求头键值对。

配置填写完成后，点击右上角的 保存 按钮以保存配置，或点击左上角的 返回（向左箭头）按钮放弃当前更改并返回设置页面。

6. 使用自定义 Skill

Skill（技能） 是面向 CukeTest 智能体定制开发的功能指令与行业知识库的集合。通过在本地配置 Skills，您可以让智能体学会并掌握针对特定业务逻辑、私有框架、非公开 API 或复杂操作规程的自动化执行能力。

6.1 打开 Skills 目录

1. 打开 Agent 设置 页面。
2. 找到 Skills 区域，点击右侧的 文件夹 图标。
3. 系统将在操作系统的文件管理器中自动打开本地的 Skills 技能文件夹目录。
   • 默认路径：Windows 系统下，默认的 Skills 目录为 C:\Users\用户名\.cuke\skills（其中 用户名 为您当前的操作系统用户名）。

6.2 技能的运作机制

• 自动加载：当您启动智能体时，智能体插件会自动扫描并动态加载该本地 Skills 目录下的所有可用技能。
• 智能调用：在后续的会话中，智能体会根据您提交的任务目标，智能决策并在必要时主动调用加载的 Skill，从而根据 Skill 中定义的规则与专业步骤，更加精准高效地完成相应任务。

7. 智能体指示 (AGENTS.md)

为了让智能体更好地理解当前项目或您的开发习惯，您可以创建一个名为 AGENTS.md 的 Markdown 文件作为智能体的指示指南。

7.1 位置与使用场景

AGENTS.md 支持存放在以下两个位置，智能体启动并载入工作区时会自动读取它们：

1. 项目级指南（推荐）：放置在当前打开的项目（工作区）根目录下。
   • 使用场景：用于定义当前项目的特定规则。您可以在此定义项目的业务背景、代码风格、开发规范、构建与测试命令、以及智能体在当前项目中的执行边界（如“必须做什么”、“禁止做什么”），以确保智能体在该项目内的开发行为符合规范。
2. 全局级指南：放置在用户目录的 .cuke 目录下（对于 Windows 系统，其默认路径为 C:\Users\用户名\.cuke\AGENTS.md）。
   • 使用场景：用于定义您个人的全局规则。适合定义通用的代码风格习惯、首选语言偏好或智能体通用行为习惯，这些规则将对您在该智能体中打开的所有项目生效。

7.2 编写建议

一个典型的 AGENTS.md 可以包含以下内容：

• 项目结构：简要说明核心目录及文件的用途。
• 常用命令：提供项目构建、安装依赖和运行测试的准确命令。
• 规范与约定：例如代码风格、测试用例的编写规范。
• 执行边界：明确规定智能体可以直接执行的操作或需要先询问的敏感操作。

8. 使用建议

• 任务描述越具体，结果越稳定。建议明确指出目标文件、期望输出、测试框架和限制条件。
• 对复杂任务，优先让智能体先分析并给出计划，再执行文件修改。
• 涉及批量修改或终端命令执行时，请先查看权限提示和任务计划。
• 修改完成后，请使用 Diff 视图检查变更，并运行相关测试进行充分验证。