Commerce Evidence Toolkit

Commerce Evidence Toolkit

为处理商品数据的 Agent 提供三项本地只读检查。该软件包封装了 Agentic Commerce Field Guide 中发布的同一套版本化比较规则。

版本 0.1.0 · MIT 许可。 下载版本化发行包，或按下文所述运行源代码。注册表的可用性与 GitHub 发行版相互独立；请查询实时注册表以了解其当前状态。

功能

工具	输入	结果
review_product_record	一个商品对象、可选的已提供证据、copy 或 mapped 方法	对选定字段进行审核：clear 或 hold
compare_feed_snapshots	明确指定的来源和 Feed 快照、商品 ID、证据引用、时间戳和时效策略	match、update_needed 或 hold
compare_dimensions	同一商品和测量基准、明确指定的长度／宽度／高度、单位和容差	match、mismatch 或 hold

这些检查不会获取引用、验证证据、联系商家、更改 Feed、下订单或发送遥测数据。匹配不代表服务提供方接受、商品实时真实信息、实物适配或兼容性。这是一套针对选定内容的本地审核约定，并非完整的服务提供方架构验证器。暂停结果是基于证据作出的决定，并非协议故障。

安装版本化捆绑包

从 v0.1.0 发行版下载 commerce-evidence-toolkit-0.1.0.mcpb 和 SHA256SUMS。请使用已发布的 SHA-256 校验和验证压缩包。该捆绑包包含服务端和生产依赖项；需要 Node.js 22 或更高版本。

使用兼容客户端的 MCPB 导入流程，或将压缩包解压到目录，然后使用下方的 JSON 示例配置 server/index.mjs 的绝对路径。不同客户端对 MCPB 的支持情况各异。协议测试并不能证明该工具已通过任何桌面应用的认证。

发行版中也包含 Node 软件包归档。安装该归档需要使用 npm 安装其依赖项。该软件包尚未发布到 npm。

从源代码运行

需要 Node.js 22 或更高版本以及 npm。安装依赖项时需要联网；安装完成后，三项比较操作均在本地运行。

npm ci --ignore-scripts
npm test
node server/index.mjs

最后一条命令会启动一个通过标准输入／输出通信的 MCP 服务。它会等待兼容客户端连接，并非浏览器 URL。不要将调试消息打印到 stdout，因为该输出流用于传输协议数据。

对于接受 MCP JSON 配置的兼容客户端，请将下方路径替换为检出目录的绝对路径：

{
  "mcpServers": {
    "commerce-evidence": {
      "command": "node",
      "args": ["/absolute/path/agentic-commerce-field-guide/server/index.mjs"]
    }
  }
}

客户端配置位置各不相同。此示例声明了传输方式和可执行文件；这并不表示每个助手都会自动安装或调用该服务。

尝试完整输入

examples/ 中的文件是完整的工具参数，而非单独的内部记录。以下三个入门示例均为虚构示例，并在适用时使用固定时间。

工具	参数文件	预期示例结果
compare_dimensions	examples/dimensions.json	match
compare_feed_snapshots	examples/feed-snapshots.json	update_needed
review_product_record	examples/product-record.json	显式映射后为 clear

请让客户端使用该文件中的 JSON 对象调用指定工具。每个成功的响应都包含结构化内容，其中有 toolVersion、规范文档 URL 和完整的 result。每项核心结果都会保留自身的规则集版本及证据限制。接受但不完整的输入会返回挂起结果；格式错误的封套和超出限制的请求会返回协议工具错误。封装程序将序列化请求限制为 200,000 个 UTF-8 字节，嵌套层级限制为 25；各项检查还会设置更严格的限制。

尺寸值必须是正十进制字符串，并使用明确的单位（in、cm、mm、m）；公差必须是以毫米为单位的非负十进制字符串。不要擅自将深度重命名为长度、将直径视为两个轴，或改用包装尺寸。产品记录审核涵盖选定的正数 USD 字段；Feed 新鲜度采用选定的当前 USD 快照契约。引用是调用方声明，不会被抓取。

一项已观察的比较

examples/observed-dimensions.json 包含在 9 月 24 日研究期间从美国和英国公开产品页面观察到的 HOLMERUD 40541421 尺寸。在声明的 2 mm 显示阈值下，结果为 match；阈值为零时，结果为 mismatch。英寸的小数显示值按精确十进制数表示。该工具不会抓取或验证所链接的来源。此阈值并非制造或安装公差。该研究保留了八项完整比较和 22 条未解决的商品信息；这不是行业错误率估算。

验证和打包

npm run verify:artifacts
npm test
node scripts/test-clean-install.mjs
npm run bundle

npm run bundle 会在 dist/ 下创建包含生产依赖项的本地 .mcpb 归档及 SHA-256 文件。可使用 npm pack 构建 Node 包。本地构建的包并未发布到 npm 或 MCP Registry。

测试套件会根据来源规则比较全部 40 个夹具／方法用例（10 个尺寸、6 个新鲜度，以及采用 2 种方法审核的 12 条产品记录），检查错误边界和输入不可变性，并使用 TypeScript SDK 客户端通过 stdio 调用全部 40 个用例。全新安装测试会将归档安装到临时目录，并调用全部三个工具。另有一项独立的 Python SDK 客户端测试，会调用全部三个示例以及一项输入不完整的挂起用例。这些是使用合成输入进行的协议测试，并非独立用户测试或桌面应用认证。

证据与范围

provenance.json 记录源站点提交、实际生产环境下载验证时间，以及 artifacts/ 中每个文件的 SHA-256。9 月 24 日的快照为现有的商品 Feed 和测量工件增加了尺寸信息。验证会重新计算哈希，并重新检查此前的可移植性与时效性案例。合成案例展示的是规则行为，而非商家错误率或模型准确率。

主要工具文档：

• 商品记录审核
• Feed 时效性
• 尺寸比较
• Agent 访问与编辑政策

请引用相关指南以及此版本或提交。CITATION.cff 提供作者元数据。要报告更正，请创建 issue，并提供工具版本、最精简的非敏感输入、预期结果、实际结果和支持性参考。切勿发布客户数据或凭据。

许可

原始软件、文档、测试和虚构测试数据集均采用 MIT License；详情请参阅许可范围。第三方依赖保留其在打包依赖目录中的各自许可声明。本仓库不会重新许可链接的规范、源页面、图片和商标。