Adobe Commerce App Builder的人工智能编码开发人员工具
迁移到Adobe Commerce as a Cloud Service时,您可以使用AI编码工具将现有Adobe Commerce PHP扩展转换为Adobe Developer App Builder应用程序。 您还可以使用这些工具创建新的App Builder应用程序。
AI编码工具具有以下优势:
- 增强的开发工作流:集成的Adobe Commerce开发工具。
- AI支持的帮助:上下文感知代码生成和调试。
- Commerce特定功能:用于Adobe Commerce App Builder开发的专用工具。
- 自动化工作流:简化了开发和部署流程。
通过安装AI编码工具,您可以访问:
- 技能 — 特定于Adobe Commerce和App Builder的技能集,旨在指导您的应用程序开发并为其提供信息。
- 开发人员MCP服务器
- App Builder MCP服务器
正在更新到最新版本
在安装AI编码开发人员工具后,您可以通过运行以下命令更新到最新版本:
aio commerce extensibility tools-setup
这会将工具更新到最新版本。
先决条件
安装
-
全局安装最新的Adobe I/O CLI:
code language-bash npm install -g @adobe/aio-cli -
安装以下插件:
code language-bash aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce @adobe/aio-cli-plugin-app-dev @adobe/aio-cli-plugin-runtime -
克隆以下项之一:
-
导航到starter kit目录:
code language-bash cd commerce-integration-starter-kit -
通过运行交互式设置命令安装Commerce AI可扩展性工具:
code language-bash aio commerce extensibility tools-setup安装过程会提示您配置选项。 按照提示完成安装。 工具将安装在所选目录中。
-
选择要用于项目的入门工具包。
code language-shell-session ? Which starter kit would you like to use? ❯ Integration starter kit Checkout starter kit -
选择您的首选编码代理。 支持超过40个编码代理,但如果您看不到首选代理,则可以使用
Other选项为任何编码代理安装技能。 有关如何配置技能的说明,请参阅编码代理的文档。code language-shell-session ? Which coding agent would you like to install skills for? ❯ Cursor Claude Code GithubCopilot Windsurf Gemini CLI OpenAI Codex Cline ... -
安装程序将检测您是否安装了NPM或Yarn,并自动进行相应的选择。 但是,如果您尚未安装这两个软件,则会提示您选择包管理器,Adobe建议使用
npm来保持一致性:code language-shell-session ? Which package manager would you like to use? ❯ npm yarn
-
-
成功安装编码工具后,安装过程将配置:
- 用于Adobe Commerce开发的MCP服务器集成
- 代理技能用于增强开发体验
- 特定于Commerce的开发工具和工作流
现已安装技能和MCP工具。 如果您看不到技能和MCP工具,请重新启动编码代理。
- 使用Adobe I/O CLI登录到Adobe Developer Console。
- 创建App Builder项目(请参阅项目设置)。
- 在
.env文件中设置环境变量。
安装后配置
登录到Adobe I/O CLI
安装Adobe I/O CLI后,必须随时登录,才能使用MCP服务器。
aio auth login
要验证您是否已登录,请运行以下命令:
aio where
如果遇到问题,请尝试注销并重新登录:
aio auth logout
aio auth login
光标
-
重新启动光标IDE以加载新的MCP工具和配置。
-
通过确认技能存在于
.cursor/skills/文件夹下来验证安装。 -
启用MCP服务器:
- 使用Cmd+Shift+P (macOS)或Ctrl+Shift+P (Windows和Linux)打开光标MCP设置。
- 类型视图:打开MCP设置
- 在列表中找到commerce-extensibility MCP服务器
- 切换服务器 ON 以启用编码工具
-
验证服务器状态 — Commerce可扩展性MCP服务器应显示为:
code language-shell-session Status: Connected/Active Server: commerce-extensibility Configuration: Automatically configured via .cursor/mcp.json -
使用以下提示查看代理是否使用MCP服务器。 如果不能,请明确要求代理使用可用的MCP工具。
code language-shell-session What are the differences between Adobe Commerce PaaS and Adobe Commerce as a Cloud Service when configuring a webhook that activates an App Builder runtime action?
Copilot
-
重新启动Visual Studio代码以加载新的MCP工具和配置。
-
通过确认
copilot-instructions.md文件夹中存在.github文件来验证安装。 -
启用MCP服务器:
- 单击左侧边栏活动栏中的 Extensions 图标,或者使用Cmd+Shift+X (macOs)或Ctrl+Shift+X (Windows和Linux)打开“扩展”面板。
- 单击MCP服务器 — 已安装。
- 单击 commerce-extensibility MCP服务器 旁边的齿轮图标,然后选择启动服务器(如果服务器已停止)。
- 再次单击齿轮图标,然后选择显示输出。
-
验证服务器状态。
MCP:commerce-extensibility输出应匹配以下内容:code language-shell-session 2025-11-13 12:58:50.652 [info] Starting server commerce-extensibility 2025-11-13 12:58:50.652 [info] Connection state: Starting 2025-11-13 12:58:50.652 [info] Starting server from LocalProcess extension host 2025-11-13 12:58:50.657 [info] Connection state: Starting 2025-11-13 12:58:50.657 [info] Connection state: Running (...) 2025-11-13 12:58:50.753 [info] Discovered 10 tools -
使用以下提示查看代理是否使用MCP服务器。 如果不能,请明确要求代理使用可用的MCP工具。
code language-shell-session What are the differences between Adobe Commerce PaaS and SaaS when configuring a webhook that activates an App Builder runtime action?
示例提示
以下示例提示使用集成入门工具包创建应用程序,以便在下订单时发送通知。
Implement an Adobe Commerce SaaS application that will send an ERP notification when a customer places an order. The ERP notification must be sent as a POST HTTP call to <ERP URL> with the following details in the request JSON body:
Order ID -> orderID
Order Total -> total
Customer Email ID -> emailID
Payment Type -> pType
以下示例提示符使用checkout starter kit创建一个提供自定义配送方法的应用程序。
Implement an Adobe Commerce SaaS application that provides custom shipping methods.
The extension should:
1. Return shipping options based on the destination postal code
2. If postal code is in California, add an "Express California" option for $15
3. If postal code is outside US, add an "International Standard" option for $25
4. The carrier code should be "MYSHIP"
提示命令
除了提示,您还可以使用/search-commerce-docs命令在与代理的对话中搜索文档。 例如:
/search-commerce-docs "How do I subscribe to Commerce events?"
技能
虽然当您与编码代理聊天时,会自动调用技能,但您也可以使用以下命令手动调用这些技能:
/architect— 使用App Builder和选定的入门套件设计Adobe Commerce扩展的架构。 在规划集成、选择事件、设计数据流或做出体系结构决策时使用。/developer— 按照App Builder模式和文件结构实现Adobe Commerce扩展。 在生成代码、更新配置文件或实施运行时操作时使用。/devops-engineer— 部署和运行App Builder扩展。 用于部署应用程序、配置环境、排除部署问题、设置CI/CD或解决载入错误。/product-manager- Adobe Commerce扩展的收集和文档要求。 在启动新项目、定义接受标准、阐明业务目标或创建REQUIREMENTS.md文档时使用。/technical-writer— 为App Builder应用程序创建全面的文档。 在编写README.md、用户指南、API文档、更改日志或确保文档完整性时使用。/tester— 为App Builder应用程序创建全面的测试。 在编写单元测试、集成测试、验证安全性或确保代码质量和覆盖范围时使用。/tutor(实验性) — 教导Adobe Commerce应用程序开发概念,并提供明确的说明和示例。 在学习App Builder、了解事件或需要有关开发模式的指导时使用。
最佳实践
Adobe建议在使用人工智能编码工具时遵循以下最佳实践:
计划模式
与编码代理聊天时,您应该选择 计划 模式以创建项目的详细实施计划。
选择 计划 模式的方法因您使用的代理而异。 有关说明,请参阅代理的文档。 例如:
清单
在开始任何开发会话之前:
- 检查
REQUIREMENTS.md - 验证MCP工具是否正常工作
- 审查当前阶段和目标
- 从示例代码或基架项目开始
在开发过程中:
- 信任四阶段协议
- 为复杂开发请求实施计划
- 在可用时使用MCP工具
- 实施后测试每个功能
- 首先在本地测试,然后再次部署和测试
- 利用编码工具测试支持
- 问题不必要的复杂性
- 增量部署以实现更快的开发
开始新聊天时:
- 提供正确的会话切换
- 使用
@的引用密钥文件 - 为会话设置明确的目标
- 使用基于阶段的边界
工作流
使用AI编码工具进行开发时,请从示例代码或基架项目开始。 此方法可确保您基于坚实的基础进行构建,而不是从零开始,同时还可优化您的AI开发工作流。
这还允许您利用Adobe的模板并基于经验证的模式和体系结构进行构建,同时保留已建立的目录结构和约定。
请查阅以下资源以开始使用:
为什么应使用这些资源
- 经验证的模式:入门套件体现了Adobe的最佳实践和体系结构决策
- 加快开发:减少花在样板和配置上的时间
- 一致性:确保您的应用程序遵循已建立的约定
- 可维护性:遵循标准模式时,更容易维护和更新
- 文档:入门套件随附示例和文档
- 社区支持:使用标准方法时更容易获得帮助
- AI上下文效率:使用熟悉的模式和结构进行处理,从而减少大量解释的需要,并提高代码生成准确性
- 减少了令牌使用量:引用现有模式,而不是从头开始生成所有内容,从而提高对话效率和减少上下文摘要
协议
已安装的技能会自动强制执行以下四阶段协议。 在开发应用程序时,工具应自动遵循此协议:
- 第1阶段:需求分析和说明
- 当被问及澄清问题时,请提供完整的答案。
- 第2阶段:架构规划和用户批准
- 提交计划时,请在批准之前仔细审查计划。
- 阶段3:代码生成和实施
- 第4阶段:文档和验证
为复杂开发请求实施计划
对于涉及多个运行时操作、接触点或集成的复杂开发,明确要求AI工具创建详细的实施计划。 当您在阶段2中看到涉及多个组件的高级计划时,请要求提供详细的实施计划以将其划分为可管理的任务:
Create a detailed implementation plan for this complex development.
复杂的Adobe Commerce应用程序通常涉及:
- 多个运行时操作
- 跨多个接触点的事件配置
- 与外部系统集成
- 状态管理要求
- 跨多个组件测试
使用MCP工具
该工具默认为MCP工具,但在某些情况下,它可以改用CLI命令。 要确保使用MCP工具,请在提示符下明确请求它们。
如果您看到正在使用的CLI命令并希望改用MCP工具,请使用以下提示:
Use only MCP tools and not CLI commands
- MCP工具:aio-app-deploy、aio-app-dev、aio-dev-invoke
- CLI命令:aio应用程序部署、aio应用程序开发
CLI命令可用于以下情况:
- 复杂的部署方案
- 调试特定问题
- 当MCP工具具有限制时
- 无法从MCP集成中受益的一次性操作
开发
质疑AI工具所造成的不必要的复杂性。
为简单只读端点添加不必要的文件(validator.js、transformer.js、sender.js)时,请使用以下提示:
Why do we need these files for a simple read-only endpoint?
Perform a root cause analysis before adding complexity
Verify if simpler solutions exist
测试
测试时请遵循以下最佳实践:
实施后测试每个功能
完成实施计划中的功能开发后,请立即对其进行测试。 早期测试可避免复合问题,并使调试更容易。
- 不要等到所有功能都完成
- 增量测试以及早发现问题
- 在移到下一个功能之前验证功能
首先在本地测试
始终首先使用aio-app-dev工具在本地测试。 这提供了即时反馈,并允许更快的迭代周期、更轻松的调试以及无部署开销。
-
启动本地开发服务器:
code language-bash aio-app-dev -
本地测试操作:
code language-bash aio-dev-invoke action-name --parameters '{"test": "data"}'
再次部署和测试
本地测试成功后,在运行时环境中部署和测试。 运行时环境的行为可能与本地开发不同。
-
部署到运行时:
code language-bash aio-app-deploy -
测试已部署的操作
-
使用Web浏览器或直接HTTP请求
-
检查激活日志以进行调试
利用编码工具测试支持
请求有关测试的帮助。 这些工具可帮助调试、日志分析和为特定运行时操作创建适当的测试数据。
测试运行时操作:
Help me test the customer-created runtime action running locally
调试失败:
Why did the subscription-updated runtime action activation fail?
检查日志:
Help me check the logs for the last stock-monitoring runtime action invocation
创建测试负载:
Generate test data for this Commerce event
Create a test payload for the customer_save_after event
查找运行时终结点:
What's the URL for this deployed action?
处理身份验证:
How do I authenticate with this external API?
疑难解答:
Help me debug why this action is returning 500 errors
调试
停止并评估何时出现问题。 如果您遇到问题:
- 停止并评估 — 不要在中断状态下继续
- 检查日志 — 使用激活日志识别问题
- 简化 — 消除复杂性以隔离问题
- 增量测试 — 一次修复一个问题
- 验证 — 在继续操作之前测试每个修复
部署
部署时请遵循以下最佳实践:
增量部署
仅部署已修改的操作,以加快开发。 此方法可降低中断现有功能的风险,并加快提供更改的反馈。
-
使用MCP工具部署特定操作
code language-bash aio-app-deploy --actions action-name -
在本地测试后部署单个操作
-
以增量方式部署,避免在开发期间进行完整的应用程序部署
运行时清理
在进行重大更改后,请利用这些工具来清理孤立的操作。 让AI工具系统地处理清理过程。 它可以高效地识别孤立的操作,验证其状态,并且无需手动干预即可安全删除它们。
Help me identify and clean up orphaned runtime actions
请求人工智能工具列出已部署的操作并识别未使用的操作
List all deployed actions and identify which ones are no longer needed
让AI工具使用适当的命令删除孤立的操作
Remove the orphaned actions that are no longer part of the current implementation
监控
在监视应用程序时,请使用以下最佳实践:
查看上下文质量指示器
- 良好的上下文: AI记住最近的决策,引用正确的文件
- 较差的上下文: AI会询问以前提供的信息,重复已解决的问题
跟踪开发速度
- 高速:进度清晰,所需说明最少
- 低速:重复解释,AI混乱,进度缓慢
监控成本效益
跟踪令牌使用模式:
- 高效:令牌使用率低,上下文摘要很少
- 效率低下:令牌利用率高,有多个摘要,重复工作
应避免的内容
在使用AI编码工具时,请避免以下反模式:
- 不要跳过澄清阶段 — 始终确保在实施之前完成阶段1。
- 在每个功能之后不要跳过测试 — 增量测试,不要等到所有功能都完成。
- 在没有根本原因分析的情况下不要增加复杂性 — 询问不必要的文件添加情况并要求进行适当的调查。
- 没有实际数据测试时不声明成功 — 始终使用实际数据进行测试,而不仅仅是边缘案例。
- 不要忘记运行时清理 — 始终在主要更改后清理孤立的操作。
提供反馈
希望针对AI编码工具提供反馈的开发者可以使用/feedback命令。
此命令允许您提供文本反馈并将日志发送到Adobe。 您发送的任何日志都将经过清理,以删除任何私人或个人信息。
-
在代理中,键入
/feedback并选择commerce-extensibility/feedback命令。 -
在IDE顶部显示的 反馈 字段中提供工具的反馈,然后按 Enter 键。
{width="600" modal="regular"}
-
在 本地保存 字段中,键入
yes或no,然后按 Enter 指示是否要保存日志的本地副本。 {width="600" modal="regular"}
如果您选择了是,则可以在发送反馈后查看
chats文件夹中的日志。 -
commerce-extensibility/feedback命令显示在代理的聊天输入字段中。 按 Enter 或单击 发送 将您的反馈发送到Adobe。
/feedback命令,则可能需要将更新到最新版本。