label-capture-ios

Label Capture iOS 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit Label Capture API。Label Capture 在近期的 SDK 版本中经历了多次演进：

• 在 v7→v8 大版本升级中，LabelFieldDefinition 正则表达式构建方法更名（setPattern→valueRegex、setPatterns→valueRegexes、setDataTypePattern→anchorRegex、setDataTypePatterns→anchorRegexes）。
• 在 v8.1 中，引入了 Swift 结果构建器 DSL（LabelCaptureSettings { LabelDefinition("...") { ... } }），并移除了 Symbology 枚举自动桥接对 NSNumber 封装的需求。v8.0 集成使用数组初始化器 LabelCaptureSettings(labelDefinitions: [...])。可选的 VF 代理方法 didSubmitManualInputFor:replacingValue:withValue: 也在 v8.1 中添加。
• 在 v8.2 中，Validation Flow UI 经过重新设计。新增了 LabelCaptureValidationFlowSettings.setPlaceholderText(_:forLabelDefinition:) 和可选的代理方法 didUpdateResult:asyncId:fields:frameData:。
• iOS 符号系统枚举值使用驼峰命名法：.ean13UPCA、.gs1DatabarExpanded、.code128（而非 Android 中的下划线形式 EAN13_UPCA）。
• iOS 标签设置使用 Swift 结果构建器 DSL（v8.1+）或数组初始化器（v8.0），而非 Android 使用的链式 .addLabel().buildFluent(...) 风格。

编写或建议代码前，务必根据此技能提供的参考资料核实 API。 不要依赖记忆中的方法签名、参数或视图修饰符。如果无法在提供的参考资料中找到某个 API，请先获取相关文档页面，再作答。

运行约束

以下是 Label Capture 的运行时和许可事实，并非 API 版本信息；在编写代码前，它们会影响你能向用户承诺什么。

Label Capture 只能读取印刷文本。 不支持手写文本。设备端 OCR 引擎和 ARE 均针对机器印刷的字符（拉丁字母、数字、常见标点）。如果用户询问扫描手写值，请明确说明这一点，并建议采用手动输入作为替代方案（例如使用 Validation Flow 的手动输入字段）。

ARE（Adaptive Recognition Engine） 是 Scandit 基于云的 OCR 备用方案，可通过 LabelDefinition 上的 .adaptiveRecognition(.auto) 启用。它是标签定义的属性，且不依赖覆盖层（无论使用 Basic、Advanced 还是 Validation Flow 覆盖层，它都能正常工作——不要告诉用户它仅适用于 Validation Flow）。该功能目前处于 Beta 阶段，需要 Adaptive Recognition Engine 权限；Scandit 会在服务器端为你的订阅启用该权限——用户无法自行切换客户端标志；该权限包含在签发的许可证密钥中。可签发试用密钥用于评估；生产密钥需要联系 [email protected]。默认情况下不要启用它。（这与 Beta Receipt Scanning 不同，后者确实需要专用覆盖层。）

意图路由

根据用户的请求，在回复前加载相应的参考文件：

• 关于其他 Scandit 产品或扫描模式的问题（例如 SparkScan、Barcode Capture、MatrixScan、ID Capture，或与 Label Capture 无关的一般 SDK 设置问题）→ 转交给 data-capture-sdk skill。不要凭记忆尝试回答有关其他采集模式的问题——专用 skill 提供了正确且最新的参考资料。

• 从头开始集成 Label Capture（例如“将 Label Capture 添加到我的 iOS 应用中”“扫描同时包含条码和有效期的价签”“扫描价格/货架标签”“读取 VIN”“读取七段显示屏/电子秤”“如何使用 Smart Label Capture”“我想构建一个标签扫描应用”“应该使用哪个 overlay”“什么是 ARE”“扫描整张收据”“如何提高 OCR 准确度”“如何使用 Basic Overlay 捕获扫描图像”“构建完全自定义的 AR overlay / 浮动图钉 / 在相机画面上绘制自己的视图”“使用 Advanced Overlay”“锚定/定位/偏移跟踪标签上的自定义视图”“停止重复的采集提示音/每个标签只发出一次反馈”“同时扫描条码和标签/同时使用 Barcode Capture 和 Label Capture/为什么添加第二种模式后扫描停止”“使用哪些 SPM 产品/为什么我的 IMEI 或序列号标签会在启动时导致崩溃”）→ 阅读 references/integration.md，并遵循其中的说明。该文件包含预构建的整标签工厂定义（价格采集、VIN、七段显示屏）以及 Beta Receipt Scanning 路径——在组合自定义字段之前，请先查阅。如果用户还没有现有项目，该指南会引导你先提供预构建示例。

• 启用或自定义 Validation Flow（例如“如何启用 Validation Flow”“添加 validation flow overlay”“自定义 validation flow 中的占位文字/按钮标签”“如何处理 validation flow 的结果”“为什么无法配置 Validation Flow”“我可以在 VF 中更改什么”“如何在 Validation Flow 期间捕获帧图像”“能否将 Validation Flow 嵌入卡片或工作表中”）→ 阅读 references/validation-flow.md，并遵循其中的说明。如果用户尚未完成基础 Label Capture 集成，也要先阅读 references/integration.md——Validation Flow 是 Basic Overlay 的替换方案，而不是从头开始的流程。

• 迁移或升级现有的 Label Capture 集成（例如“将我的 Label Capture 升级到最新 SDK”“从 v7 迁移到 v8”“Label Capture 的 SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

仅使用下方 Scandit 参考资料中明确记载的 API。不要编造或猜测方法签名、参数或视图修饰符。如果不确定某个 API 是否存在或如何调用，或者出现编译错误，请在回复前获取相关参考页面。不要让用户自行查阅文档。回答后，始终附上相关链接，方便用户进一步了解。

切勿构造或猜测文档 URL。 需要特定类或属性的 API 页面时：

1. 首先检查已获取的页面（例如 Advanced Configurations 页面）是否包含指向该页面的直接链接——主题页面会直接链接到相关 API 符号。提取内容时，务必同时请求链接。
2. 如果没有找到直接链接，请获取 API 索引（见下表中的 完整 API 参考），从中提取实际链接，然后访问该链接。

URL 结构可能有所不同（例如包含 api/ui/ 子目录），猜测 URL 会导致 404 错误。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 native，许可证平台为 ios。

请按顺序完成以下步骤——切勿因 MCP 而阻塞用户：

1. Scandit MCP 服务已连接 — 使用产品 native、平台 ios、app_identifier（应用的 bundle 或 application ID；对于 Web，应为其生产域名，绝不能是 localhost）和 env_var SCANDIT_LICENSE_KEY 调用 ensure_scanner_setup。不要运行它返回的命令。然后使用该结果或 list_license_keys 提供的密钥 ID 调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征求用户同意再获取。聊天中最多显示经过遮盖的预览；绝不打印完整密钥。

2. 尚未连接 — 只告知用户一次，他们可以在自己的 MCP 客户端中连接远程 Scandit MCP 服务 https://ssl.scandit.com/mcp，然后从第 1 步继续。不要自行编辑 MCP 客户端配置。

   该服务使用基于浏览器的身份验证，因此不支持无头模式或 CI。该服务只会配置试用密钥；绝不会创建、撤销或修改生产许可证。

3. 用户拒绝，或没有 MCP 客户端 — 请用户自行在 https://ssl.scandit.com 生成密钥（尚无账户时：https://ssl.scandit.com/dashboard/sign-up?p=test），然后粘贴该密钥。

然后将密钥写入代码：在许可证密钥调用中，将占位符替换为密钥——get_license_key 返回的密钥，或用户粘贴或提供的密钥——聊天中仍只显示经过遮盖的预览。不要在项目、其文件或环境中搜索密钥。

参考资料

根据用户的问题，引导他们查看相应资源：

主题	资源
基本集成	快速入门 · 示例 (LabelCaptureSimpleSample)
标签定义（字段、正则表达式、预设）	标签定义
高级主题（验证流程自定义、自适应识别、自定义叠加层）	高级配置
完整 API 参考	Label Capture API