NorthCinder 的作用
NorthCinder 是一个开源的模型上下文协议（Model Context Protocol，MCP）服务器，可帮助 AI 购物代理依据买家定义的需求说明比较商品。它会生成经过排序的候选清单，解释每个商品为何获得相应排名，指出被排除的选项，并报告已搜索或未搜索的商店。
NorthCinder 在你的计算机上运行，并与支持 MCP 的 AI 应用配合使用。代码仓库所有者不运营托管式 NorthCinder 服务、账户系统、控制平面或遥测服务。你需要自行运行客户端和聚合引擎、选择商店连接，并在本地保留配置和审计数据。
其核心设计原则是由买家标准决定排名。卖家付款和联盟营销信息不会提升商品的排名。赞助结果会始终带有标签，并排在自然结果之后。
主要功能
- 买家驱动的排名：商品会根据购物需求说明中的要求进行排序。
- 机器可读的解释：每项推荐都包含评分和结构化理由。
- 明确显示被排除项：未满足必要条件的商品会被列出，并注明其未满足的具体要求。
- 商店覆盖情况报告：无法访问、被阻止和尚未配置的商店仍会显示，而不会被静默省略。
- 商家可信度证据：每个商家都会附有明确的支持证据，或如实标记为未知状态。
- 持久化标签：赞助和来源标签会始终附加在对应商品上。
- 本地验证：客户端会使用服务披露的输入，在本地重新执行确定性排名。
- 受控结账：自动结账需要一份经过签名、仅可使用一次的授权指令，并与具体商品、数量和支出上限绑定。
- 本地审计：推荐结果、授权和结账尝试都会写入本地审计记录。
本地重新排名可以验证根据已披露输入生成的排序，但无法证明上游商品目录是完整的，也无法证明商店提供的每项信息都准确无误。
前提条件
进行标准安装时，你需要 Node.js 20 或更高版本以及一个支持 MCP 的 AI 应用。各个商店集成可能还需要额外的平台访问权限、凭据或配置。
安装并初始化 NorthCinder
第 1 步：运行初始化程序
打开终端并运行：
npx northcinder init初始化程序会引导你完成本地设置，并输出 AI 应用所需的 MCP 配置。
第 2 步：添加 MCP 配置
将初始化程序输出的配置复制到 AI 应用的 MCP 配置区域。具体位置和连接流程因应用而异，请按照该应用的 MCP 文档操作。
第 3 步：连接或重启 AI 应用
应用配置，并根据需要重新连接或重启应用。随后，代理应能将 NorthCinder 作为本地 MCP 服务器使用。
提交你的第一份购物需求说明
NorthCinder 最适合处理具体明确的需求说明，其中应包含必要属性、预算、比较因素和解释要求。例如：
寻找价格低于 130 美元的黑色羊毛跑鞋。比较价格、配送、合脚程度和商家可信度。告诉我排名第一的商品为何胜出，以及哪些选项被排除了。
这份需求说明确定了颜色、材质、商品类型和最高价格等必要条件。它还指明了代理需要比较的因素，并要求同时说明获胜理由和被排除的备选项。
检查响应
不要只查看第一项结果。NorthCinder 的响应可能包括：
- 满足必要条件的商品。
- 每项推荐的评分和机器可读理由。
- 被排除的商品，以及每项商品未满足的具体要求。
- 商家可信度证据，或明确指出缺少相关证据。
- 按商店列出的覆盖情况报告。
- 附加在每项商品上的来源和赞助标签。
覆盖情况报告尤其重要。如果某家商店无法访问或受到阻止，则不应将返回的候选清单视为对整个市场的完整搜索结果。
了解搜索和授权工作流
你的 AI 应用通过 MCP 与 NorthCinder 客户端通信。客户端与买家自行运行的搜索服务通信，该服务会使用已配置的商店适配器。结果返回客户端后，将在本地重新排名、生成解释并进行审计。
搜索和价格监控并不代表获得购买许可。在自动结账前，NorthCinder 要求买家针对具体购买操作进行授权。由此生成的授权指令经过签名、仅可使用一次，并与具体商品、数量和支出上限绑定。跨进程 nonce 账本可防止授权指令被重复使用。
根据可用的集成方式，获批的购买可通过结账通道或购物车移交流程继续进行。系统拒绝接收原始银行卡信息；在条件允许时，自动支付通道会使用不透明的委托支付令牌。
配置商店覆盖范围
不同平台的商店访问方式各不相同。在实际工作流中依赖某个适配器之前，请先阅读其文档。
- Shopify：完成额外的 Shopify 设置后即可使用商品目录搜索。旧版的逐店连接方式已不再适用。
- WooCommerce：可搜索开放了公共 WooCommerce Store API 的商店。
- eBay：原生搜索需要获得批准的 eBay Buy API 访问权限。
- Etsy：原生搜索需要获得批准的 Etsy 应用访问权限。
- Amazon：只读比较可以使用由你控制的浏览器配置文件。遇到验证挑战时会停止，且不会执行结账。
原生访问不可用时，代理可以使用其已控制的浏览器工具比较允许访问的商品页面。NorthCinder 接受从这些观察结果中提取的规范化商品信息，但不接受 Cookie、原始 HTML、屏幕截图、页面指令、密码、一次性验证码或你的 AI 提供商密钥。
在获得原生适配器或商家协议确认之前，代理观察到的商品不能用于自动结账或无人值守监控。
从源代码构建 NorthCinder
该代码仓库是一个 pnpm 工作区。产品软件包需要 Node.js 20 或更高版本。私有站点工作区需要 Node.js 22.12 或更高版本。
第 1 步：安装依赖项
corepack pnpm install --frozen-lockfile第 2 步：构建工作区
corepack pnpm build第 3 步：运行本地初始化程序
node northcinder/bin/northcinder.js init该代码仓库还包含离线构建、类型检查、测试、依赖项、机密信息、打包和公共接口检查。有关完整的发布验证命令，请参阅 CONTRIBUTING.md。
高级使用技巧
编写可测试的要求
将强制要求与偏好分开。例如，先确定严格的支出上限和必要的商品属性，再列出配送速度、合脚程度和商家可信度等次要比较因素。这样更便于审计排除理由和排名解释。
信任获胜商品前先审计覆盖情况
检查哪些适配器成功运行、哪些受到阻止，以及哪些尚未配置。NorthCinder 会有意保留并显示这些缺口。排名第一的商品只是已披露且成功评估的输入中的最佳选项，并不一定是网上所有可购商品中的最佳选项。
区分可验证性与完整性
客户端可以通过确定性方式重新执行排名，以验证已披露的买家标准是否生成了收到的排序结果。这无法验证商品目录的完整性，也不能保证商店提供的信息真实无误。应将证据缺失和可信度未知状态视为重要限制。
确保浏览器观察不超出其适用边界
原生商店适配器不可用时，浏览器辅助比较可以提供帮助，但在进行无人值守监控或自动结账前，观察到的商品必须经过原生适配器或商家协议确认。基于浏览器的 Amazon 比较仅为只读，遇到验证挑战时会停止，并且不会执行结账。
保护凭据和支付数据
将 AI 提供商密钥保留在 AI 应用中，并确保商店凭据只在你与相应商店之间使用。不要向 NorthCinder 传递密码、一次性验证码、Cookie 或原始银行卡信息。请查看代码仓库中的隐私与软件所有权文档以及安全政策，了解完整的边界说明。
检查项目契约
如需进行更深入的技术验证，请查看代码仓库中的排名规范、中立性审计、适配器契约、可信度规范、结账软件包和客户端源代码。这些材料记录了排名中立性、赞助内容位置、覆盖情况报告、可信度证据、购买授权指令和本地审计的实现方式。
当前项目状态
0.1.2 版是首个公开版本。夹具和测试框架的覆盖情况无法证明第三方凭据目前仍然有效、所有商店均可在生产环境中访问，或已成功完成过真实购买。在依赖某项集成前，请先核实相关适配器文档。
该软件包尚未收录到官方 MCP Registry 中，代码仓库内包含的营销网站也尚未发布到规范的生产环境源站。
总结
NorthCinder 为 AI 辅助购物提供了一个可在本地运行、可检查的基础。它结合了买家定义的排名、明确的排除理由、可见的商店覆盖情况、商家可信度证据、本地审计和针对具体购买的授权。首先运行初始化程序，连接生成的 MCP 配置，提交精确的需求说明，并在批准任何购买前检查排名理由和覆盖缺口。