EasyClick iOS版 CLI 与 Trae iOS版智能体

本文基于 EasyClick 官方文档（插件版本 9.27.0+），专门介绍 iOS 平台专属的 EC 官方 CLI 工具（ec-ios-cli）与 Trae iOS版智能体，涵盖 USB 版、脱机版差异化适配、命令规范、AI 协同流程及使用细节，全程贴合官方操作标准，助力 iOS 平台 EC 自动化脚本开发者高效上手。

一、EC iOS版 CLI（ec-ios-cli）官方规范

ec-ios-cli 是 EasyClick 官方推出的 iOS 平台专属命令行工具，核心作用是替代 IDEA 部分图形化操作，支持 iOS USB 版、脱机版 EC 项目的全流程命令化开发，无需依赖图形化 IDE，是 Trae iOS版智能体的标准执行接口，同时适配 iOS 免越狱特性及 iOS17+ 高版本系统。

1. 使用前提（官方强制要求）

• 开发插件版本 ≥ 9.27.0，中控版本无限制，兼容所有支持 EasyClick 的 iOS 设备及系统版本（含 iOS17+）；
• 本机已启动 IntelliJ IDEA，并成功加载 EasyClick iOS 开发工具插件，且插件处于可响应命令的状态；
• 命令行中使用的模块名，必须与 IDEA 中 iOS 脚本工程对应的模块名完全一致，否则会导致命令执行失败；
• 多窗口、多工程同时运行时，必须用 -p 参数传入与 IDEA 中打开路径一致的工程根目录，确保精准匹配对应的 IDEA 实例；
• 执行 run、preview 命令前，需将 iOS 设备连接至 IDEA，否则会提示“无设备连接”，无法执行操作。

2. 文件路径与核心文件说明
   ec-ios-cli 及配套说明文件默认存放于工程指定目录，路径规范如下，若未出现对应目录，关闭 IDEA 重新打开工程文件夹即可：

• 核心工具路径：ec_work_config/ios/bin/ec-ios-cli（优先使用该路径调用，避免依赖全局 PATH）；
• AI 辅助文件：ec_work_config/ios/bin/SKILL.md，用于 Trae 智能体抓取 CLI 命令规则、参数说明，辅助 AI 理解 iOS 版 CLI 功能，无需人工修改；
• 补充说明：若本机已单独安装 ec-ios-cli 并加入 PATH，也可直接执行 ec-ios-cli 命令，与上述路径工具为同一程序。

3. 核心子命令（USB版、脱机版通用，除预览外）
   ec-ios-cli 提供 5 个核心子命令，覆盖 iOS 项目预览、运行、停止、打包、日志监控全流程，其中 preview 命令存在版本差异化限制，具体如下表及说明：
   子命令
   核心作用
   是否必需 -m（模块名）
   版本限制说明
   preview
   实时预览工程 UI，查看脚本界面效果、节点查找、图色识别结果
   是
   仅 iOS 脱机版支持，USB 版执行会提示“非 iOS 脱机版项目不可预览”
   run
   运行 iOS 脚本工程，后台执行脚本逻辑，支持调用 iOS 专属 API
   是
   USB 版、脱机版均支持，需提前连接设备至 IDEA
   stop
   停止当前运行的 iOS 脚本工程，终止后台执行流程
   是
   USB 版、脱机版均支持，可通过关键字自动停止监控
   build
   编译打包 iOS 工程，生成可发布的 .iec 文件及相关中间文件
   是
   USB 版、脱机版均支持，默认操作结束后停止日志监控
   monitor
   持续输出日志流，抓取设备运行日志、报错信息、OCR/找图结果
   否
   USB 版、脱机版均支持，无需指定模块名，仅负责日志监控
4. 核心参数详解（官方规范）
   ec-ios-cli 的参数分为通用参数（preview/run/stop/build 共用）和 monitor 专用参数，所有参数需遵循官方约束，具体说明如下：
   （1）通用参数（preview/run/stop/build）

• -m / --module：必填参数，指定 IDEA 中的 iOS 项目模块名，必须与 IDEA 中模块名一致，否则无法匹配工程；
• -p / --project：可选参数，工程根目录路径，与 IDEA 中打开的工程路径保持一致，多工程、多窗口场景必传，避免匹配错误；
• -f / --format：可选参数，日志格式，支持 text或 json，默认值为 json（结构化日志，便于 AI 解析）；
• -o / --log：可选参数，将运行日志追加写入指定文件路径，便于后续查看和分析；
• -k / --stop-on：可选参数，日志中包含该子串时，自动打印提示并退出日志监控；多关键字用||| 连接（任一命中即退出），各命令有默认关键字（如 preview 默认“执行UI结束”，run 默认“脚本已运行结束”）；
• -w / --monitor-logs：可选参数，取值为 true 或 false；preview/run/stop 未指定时，默认 true（持续监控日志）；build 未指定时，默认 false（操作结束即停止日志）；
• -r / --random-log：可选参数，取值为true 或 false；为 true 时，在 ai_logs/ 目录下自动生成日志文件名，不可与 -o 参数同时使用。
  （2）monitor 专用参数
  该命令无需指定模块名、工程路径，仅负责日志监控，参数如下：
• -f / --format：同通用参数，日志格式 text/json，默认 json；
• -o / --log：同通用参数，日志追加写入指定文件；
• -k / --stop-on：同通用参数，命中关键字退出日志监控；
• -r / --random-log：同通用参数，自动生成日志文件名，不可与 -o 同用。

5. 版本差异（iOS USB版 vs 脱机版）
   iOS USB 版与脱机版的使用方式、命令规则、参数要求基本一致，核心差异仅在于 UI 预览功能，具体对比及注意事项如下：

• 相同点：均支持 run、stop、build、monitor 命令，执行逻辑、参数规范完全一致；均依赖 IDEA 及 iOS 插件运行；均支持免越狱开发、日志监控、工程打包；
• 不同点：仅 iOS 脱机版支持 preview 命令（预览工程 UI），iOS USB 版执行 preview 命令会直接失败，提示“非 iOS 脱机版项目不可预览”；
• 注意事项：开发时需明确当前使用的 iOS 版本，避免在 USB 版中执行 preview 命令；若需预览 UI，需切换至 iOS 脱机版项目。

6. 官方命令调用示例
   以下示例均假定当前目录为工程根目录，优先使用官方推荐的工具路径，覆盖常用场景，可直接复制使用：

• 编译模块 testai（默认不持续监控日志）：./ec_work_config/ios/bin/ec-ios-cli build -m testai -w false；
• 运行模块 testai，日志格式为 json 并写入指定文件：./ec_work_config/ios/bin/ec-ios-cli run -m testai -f json -o /tmp/easyclick.log；
• 预览脱机版模块 testai（仅脱机版可用）：./ec_work_config/ios/bin/ec-ios-cli preview -m testai；
• 停止模块 testai 运行：./ec_work_config/ios/bin/ec-ios-cli stop -m testai；
• 监控日志，格式为 text，命中“完成”关键字退出：./ec_work_config/ios/bin/ec-ios-cli monitor -f text -k “完成”；
• 多工程场景运行模块：./ec_work_config/ios/bin/ec-ios-cli run -m app -p /path/to/project/root。

7. 常见注意事项（官方提醒）

• 编译工程时，若 obfuscator.json 中 nodeBinPath 为空，日志会提示“跳过 JS 混淆”，属于正常行为，如需开启混淆，需配置 nodeBinPath / obfuscatorBinPath；
• 常规日志默认输出到标准错误（stderr），使用 -o 或 -r 参数时，日志会同时写入指定文件；
• 查看命令帮助：总帮助 ./ec_work_config/ios/bin/ec-ios-cli -h，子命令帮助 ./ec_work_config/ios/bin/ec-ios-cli <子命令> -h；
• 若命令执行失败，优先检查：插件版本是否 ≥9.27.0、设备是否连接 IDEA、模块名是否与 IDEA 一致、多工程场景是否传入 -p 参数。

二、Trae iOS版智能体（专属适配 ec-ios-cli）

Trae iOS版智能体是基于 LLM（大语言模型）开发的 iOS 平台专属 AI 开发助手，专为适配 ec-ios-cli 设计，可实现“自然语言驱动 iOS 版 EC 开发”，无需开发者记忆复杂命令、参数及版本差异，自动完成命令生成、执行、日志分析、问题修复全流程，完美适配 iOS USB 版、脱机版开发场景。

1. 核心定位
   Trae iOS版智能体作为 ec-ios-cli 的“AI 大脑”，衔接开发者与 CLI 工具，核心作用是将开发者的自然语言需求，自动转化为合规的 ec-ios-cli 命令并执行，同时具备项目解析、日志分析、代码调试等能力，无需人工干预 CLI 命令的编写与执行，大幅降低 iOS 平台 EC 开发门槛，提升开发效率。
2. 核心能力（适配 iOS 开发场景）

• 自动解析工程与 CLI 规则：可直接读取 iOS 工程结构、ec-ios-cli 工具及 SKILL.md 文件，精准理解子命令、参数规范、版本差异（USB 版/脱机版），无需人工告知；
• 自然语言转 CLI 命令：开发者只需用自然语言描述需求（如“编译 testai 模块并输出日志”“运行脱机版 testai 并预览 UI”），智能体自动解析意图，生成合规的 ec-ios-cli 命令，自动补充必填参数（如 -m），规避版本限制（USB 版自动屏蔽 preview 命令）；
• 全流程自动化执行：支持从工程预览、脚本运行、打包编译，到日志监控、结果验证的全流程自动化，开发者只需提出需求，智能体自动调用 ec-ios-cli 完成所有操作，无需手动输入任何命令；
• 日志自动解析与排错：抓取 ec-ios-cli 输出的 JSON 或 text 格式日志，自动识别执行结果（成功/失败）、报错信息，定位问题根源（如设备未连接、模块名错误、USB 版预览失败等），并给出针对性修复建议；
• 脚本辅助修改与验证：可辅助修改 iOS 项目脚本（如删除自动化服务启动逻辑、编写循环日志打印代码），修改完成后自动调用 ec-ios-cli run 命令，验证修改效果，确保脚本可正常运行；
• 文档投喂与能力优化：支持在 AI 对话框中输入 @ 符号，添加 EC 官方文档地址，智能体自动抓取文档内容并学习，持续优化命令生成精度，适配更多 iOS 开发场景；
• 多工程精准匹配：自动识别多工程场景，无需人工提醒，自动添加 -p 参数传入工程根目录，避免 IDEA 实例匹配错误。

3. 版本适配亮点（USB版、脱机版差异化适配）
   Trae iOS版智能体针对 iOS USB 版、脱机版的差异，做了专属适配，确保不同版本开发场景下均能流畅运行：

• 自动识别版本：智能体可自动判断当前 iOS 项目版本（USB 版/脱机版），无需开发者手动说明；
• 规避无效操作：若为 iOS USB 版，智能体自动屏蔽 preview 命令，当开发者提出“预览 UI”需求时，会提示“当前为 iOS USB 版，不支持预览功能”，避免命令执行失败；
• 版本专属优化：针对 USB 版、脱机版的命令执行逻辑，分别优化指令生成规则，确保命令适配对应版本，如脱机版自动生成 preview 命令，USB 版自动跳过该命令，优先执行 run、build 等可用命令。

4. 标准执行流程（iOS 专属）
5. 开发者用自然语言描述 iOS 开发需求（如“编译 testai 模块，将日志写入 run.log 文件”“运行脱机版 testai 模块并预览 UI”）；
6. Trae iOS版智能体解析需求，识别项目版本（USB 版/脱机版）、模块名、核心操作；
7. 智能体生成合规的 ec-ios-cli 命令，自动补充必填参数，规避版本限制；
8. 自动调用终端执行命令，实时监控日志输出；
9. 自动解析日志，判断执行结果，若出现报错，自动定位问题并给出修复建议；
10. 输出清晰的执行报告，告知开发者操作结果、产物路径（如编译后的 .iec 文件路径）或问题解决方案。

三、ec-ios-cli + Trae iOS版智能体 核心价值

1. 零命令记忆负担：开发者无需记忆 ec-ios-cli 的子命令、参数、版本限制，用自然语言即可完成所有操作，彻底告别繁琐的命令编写；
2. 版本适配无压力：智能体自动区分 iOS USB 版、脱机版，规避无效操作，无需开发者手动判断版本差异，减少操作失误；
3. 开发效率翻倍：自动化完成命令执行、日志分析、脚本修改、结果验证全流程，减少人工重复性工作，专注核心脚本逻辑设计；
4. 操作标准化合规：智能体生成的命令严格遵循官方规范，避免人工输入错误，确保开发流程、配置规范统一，提升开发质量；
5. 降低入门门槛：新手无需熟悉 ec-ios-cli 命令体系、iOS 开发细节，借助 AI 辅助，快速上手 iOS 平台 EC 自动化开发；
6. 适配性全面：完美适配 iOS 免越狱场景、iOS17+ 高版本系统，同时支持 USB 版、脱机版，满足不同开发场景需求。

四、适用场景（iOS 专属）

• 使用 iOS USB 版、脱机版进行 EC 自动化脚本开发的开发者；
• 新手开发者，希望快速上手 iOS 平台 EC 开发，无需记忆复杂命令；
• 需要批量执行 iOS 脚本、管理多台 iOS 设备的团队或工作室；
• 适配 iOS17+ 高版本系统，实现免越狱自动化开发的开发者；
• 希望通过 AI 辅助，减少重复性工作，专注核心脚本逻辑设计的开发者；
• 使用 Cursor + IDEA 进行 iOS 平台 EC 开发，需要提升编程效率的开发者。

五、官方温馨提示

1. Trae iOS版智能体的所有操作，均基于 ec-ios-cli 官方规范，确保与 IDEA、iOS 插件协同兼容，若 CLI 命令执行失败，优先检查插件版本、设备连接状态；
2. 若智能体对某些特殊场景（如高版本 iOS 适配、复杂脚本编译）支持不足，可通过投喂 EC 官方文档，提升智能体的理解能力；
3. 建议开发者熟悉 ec-ios-cli 的核心命令与参数，便于在特殊场景下（如 AI 执行异常）快速排查问题，提升开发流畅度。