mcpField
S
sparkscan-web

sparkscan-web

github.com/scandit开发2060 次安装5 天前更新
代码仓库

关于 sparkscan-web

面向 Web 的编码技能，用于集成和排查 Scandit SparkScan。它引导编码 Agent 查阅版本对应的参考资料，并提供 API 核验、设置、迁移和运行时指导。

主要功能

  1. 01按集成、React、迁移和故障排查分流
  2. 02要求核对提供的 API 参考资料
  3. 03说明 CDN 版本固定与隔离设置
  4. 04指导通过 MCP 设置 Scandit 许可证密钥

适用场景

  1. 01将 SparkScan 添加到 Web 应用
  2. 02为 React 项目调整 SparkScan 指导
  3. 03排查摄像头或部署问题

MCP 相关

该技能说明如何使用 Scandit MCP 服务准备扫描器设置并获取许可证密钥，同时提供密钥处理规范。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scandit/skills --skill sparkscan-web

安装后在 Claude Code 中输入/sparkscan-web确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
integration.md
migration.md
react.md
troubleshooting.md
references/fixtures/
ScanditProvider.tsx
spark-scan-view.d.ts

详细介绍

原文在翻译后有更新，译文可能不是最新。

SparkScan Web 技能

关键：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。SparkScan API 在不同主要 SDK 版本之间变化很大——属性可能会重命名、移除或重新组织。

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

意图路由

根据用户的请求，在作答前加载相应的参考文件。可能需要多个文件（例如，React 集成同时遇到相机问题）——请阅读所有相关文件：

  • 从零开始集成 SparkScan（例如，“将 SparkScan 添加到我的应用”“设置条码扫描”“如何使用 SparkScan”“如何处理 SparkScan 中的反馈”“我想构建一个扫描应用”）→ 阅读 references/integration.md，并遵循其中的说明。如果用户还没有现有项目，指南会引导你优先提供预构建示例。
  • 项目使用 React（package.json 中有 react 依赖、存在 .tsx/.jsx 文件、使用 hooks 或 JSX）→ 还要阅读 references/react.md。绑定 <spark-scan-view> 自定义元素的正确方式因 React 主版本而异，因此先检查 package.json 中的 react 版本——指南会说明 React 18 与 19 之间的差异，以及 context/lifecycle 陷阱。编写 React 代码前务必查阅该指南；通用的 integration.md 示例使用原生 TS。
  • 迁移或升级现有 SparkScan 集成（例如，“从 v6 升级到 v7”“迁移我的 SparkScan”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
  • 运行时、相机或部署问题（例如，“手机上无法打开相机”“运行一秒后就停止”“跨源/COOP/COEP/标头问题”“通过 LAN IP 显示空白预览”）→ 阅读 references/troubleshooting.md。这些属于环境或托管问题，而不是 API 使用错误，很容易被误诊为代码错误。

API 使用政策

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

绝不要自行构造或猜测文档 URL。 需要特定类或属性的 API 页面时：

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

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

许可证密钥

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

请按以下顺序操作——绝不要让用户因 MCP 而受阻：

  1. 已连接 Scandit MCP 服务 — 使用产品 sdk 和平台 webassembly 调用 ensure_scanner_setup，然后运行 get_license_env_command 返回的命令，将密钥写入项目的 .env。在聊天中最多展示经过遮蔽的预览；绝不要打印完整密钥。

  2. 未连接 — 提议连接一次，然后从第 1 步继续：

    • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
    • Cursor：将 {"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} 添加到 ~/.cursor/mcp.json
    • VS Code：将 {"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} 添加到 MCP 用户配置

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

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

然后将密钥填入代码，替换占位符；仅将密钥放入 .env 不会自动传入应用。通过打包工具的环境变量支持读取密钥，例如在 Vite 中使用 import.meta.env（除非 envPrefix 另有设置，否则它只会公开以 VITE_ 为前缀的名称）。适用于所有平台的最简单方法：读取 .env，并将密钥直接填入许可证密钥调用中；在聊天中仍只展示经过遮蔽的预览。

参考资料

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

主题资源
基本集成入门 · 示例
React 集成入门 · 示例
高级主题（自定义反馈、硬件触发器、扫描模式、UI 自定义）高级配置
完整 API 参考SparkScan API

评论

支持 Markdown