开发者指南NorthCinder协议包、排名验证与一致性检查机制【免费下载链接】northcinderBuyer-run, ad-neutral shopping-agent MCP software with deterministic ranking, signed purchase mandates, and a local audit trail.项目地址: https://gitcode.com/gh_mirrors/no/northcinderNorthCinder 是一款买家主导、广告中立的购物代理 MCP 软件核心卖点是确定性排名无论服务端如何动手脚用户都能在自己的电脑上复核排名结果。本文面向开发者用最短时间讲透 NorthCinder 协议包northcinder/protocol的三大支柱——确定性排名机制、客户端排名验证、以及适配器一致性检查机制并给出可直接上手的接入路径。一、NorthCinder协议包是什么三大职责一次看懂NorthCinder 协议包是仓库中的packages/protocol/目录发布为northcinder/protocol包。它不只是一个数据格式定义而是整个项目可验证中立性的根基主要承担三件事职责说明核心文件共享 Schema用 Zod 定义 Offer、SearchQuery、PurchaseMandate 等核心数据契约packages/protocol/src/schemas/适配器 SDK定义商店适配器必须实现的接口与权限清单packages/protocol/src/adapter/一致性测试框架用 7 条规则自动校验每个适配器是否合规packages/protocol/src/conformance/简单说任何商店适配器如亚马逊、eBay、Shopify只要遵循这份协议就能接入 NorthCinder并接受同样的质量与中立性检验。二、确定性排名机制排名为何无法被广告操控排名是 NorthCinder 的品牌承诺实现在packages/protocol/src/ranking/rank.ts的rankOffers函数中。它的设计有两条铁律纯函数 确定性不读时钟、不用随机数、不做 I/O同样的输入必然产生逐字节相同的输出。打分只来源于买家条件价格、预算、必选属性、到货时间、库存、商家信任度、道德偏好——没有任何一个输入是卖家花钱能影响的。评分权重一览RANK_WEIGHTS权重项分值生效条件最优价格40同币种组内最便宜者得满分最贵者得 0超预算惩罚−25报价超过买家maxPrice属性全匹配30按必选属性匹配比例缩放缺属性惩罚−10每个缺失的必选属性按时到货10承诺到货日期满足买家deliveryBy逾期惩罚−15承诺到货日期晚于买家要求有货5库存状态为 in_stock缺货惩罚−20库存状态为 out_of_stock商家受信10 / 5trust 级别为 trusted / known商家被标记−40trust 级别为 flagged道德偏好8匹配买家 ethicsFlags关键设计赞助位永不参与打分最值得开发者注意的是sponsored标记不是打分输入。它只会把商品放进一个严格低于所有非赞助商品的层级并打上赞助降级标签。代码中有测试保证——给任意商品打上赞助标记它的排名永远不可能上升。这就是花钱只能吃亏不能买排名的实现根基。三、排名验证机制如何在自己电脑上复核服务端排名确定性排名要真正可信必须让用户自己的机器能验证。这就是packages/protocol/src/ranking/verify.ts中verifySearchRanking的使命原理服务端每次搜索响应都返回排名消费过的全部输入商品列表 trustSignals客户端用开源的rankOffers重新计算一遍再与服务端返回的顺序、分数、理由逐一比对。比对结果有三种结果含义verified: true服务端排序与本地重算完全一致无差异verified: false发现差异并给出精确的差异详情not_applicable无结果可验或服务端未返回 trustSignals无法确定性重算绝不假报绿色差异类型分为order_mismatch顺序不符、score_mismatch分数被篡改、reasons_mismatch理由被改写三种每条差异都带有 1 基数的位置号和期望/实际值。这意味着服务端想偷偷给某个商品提权、改分或美化理由都会被逐条标记出来。四、一致性检查机制7条规则守护每一个适配器适配器质量是排名可信的前提。packages/protocol/src/conformance/check.ts中的checkConformance定义了 7 条固定规则CONFORMANCE_RULES任何适配器接入前都必须全部通过规则校验内容manifest-schema适配器清单是否符合 Schemamanifest-permission-scope权限范围是否明确allowedHosts、userSessionsearch-offers-schema-valid搜索结果中的每个 Offer 是否合法search-provenance-matches-manifest商品来源标识是否与清单一致search-timeout-graceful超时是否优雅降级为结构化错误get-offer-known-id已知商品 ID 能否正确解析get-offer-unknown-id-structured未知 ID 是否返回结构化的 not_found 错误规则设计有两大亮点一是结构化错误——适配器跨过 SDK 边界时绝不抛异常而是返回带错误码的结果二是超时优雅降级——某一家商店卡住绝不会拖垮整个搜索。五、中性自审计三组探针电池如何量化中立性除了运行时验证NorthCinder 还内置了一套确定性自审计packages/protocol/src/ranking/neutrality-audit.ts用固定种子生成合成数据跑三组探针电池结果写入docs/NEUTRALITY-AUDIT.md位置洗牌测试同一批商品打乱输入顺序重排 250 次结果必须逐字节一致。赞助注入测试把非赞助商品翻转为赞助标记 99 次要求 0 次排名提升、0 次分数变化、0 次层级违规、0 次标签缺失。属性权重探针11 个单维度探针逐一验证实测分数差值 公布的权重其中赞助维度必须精确等于 0。这套审计由固定种子驱动同一次运行结果逐字节相同并且接入 CI——中立性一旦回退测试直接失败。六、开发者快速上手三步接入 NorthCinder 协议包第一步获取代码。克隆仓库git clone https://gitcode.com/gh_mirrors/no/northcinder第二步编写适配器。实现StoreAdapter接口packages/protocol/src/adapter/store-adapter.ts至少提供manifest、search、getOffer三个成员若声明支持 checkout 能力还需实现带签名购买授权的beginCheckout。参考实现见packages/protocol/src/reference/reference-adapter.ts内存版基准适配器。第三步跑一致性套件。在测试文件中调用runConformanceSuite来自northcinder/protocol/conformance子路径传入你自己的已知查询词和商品 ID即可一次性执行全部 7 条规则。仓库内 amazon、ebay、etsy、shopify、woocommerce 各适配器的测试目录都有现成用法可参考。七、关键文件速查表想了解什么看哪里排名算法实现packages/protocol/src/ranking/rank.ts客户端排名验证packages/protocol/src/ranking/verify.ts一致性检查规则packages/protocol/src/conformance/check.tsVitest 一致性套件packages/protocol/src/conformance/vitest-suite.ts适配器契约与权限清单packages/protocol/src/adapter/参考适配器packages/protocol/src/reference/reference-adapter.ts排名规范文档docs/RANKING.md中性自审计报告docs/NEUTRALITY-AUDIT.md小结NorthCinder 协议包的巧妙之处在于它不要求你相信服务端而是把验证能力开放给每个用户。确定性排名保证了可复算客户端验证保证了可复核一致性检查保证了每个接入方都合规三者的组合让广告中立的购物代理从一句口号变成了可编程、可测试、可审计的工程现实。对开发者来说从packages/protocol/入手就是理解这套机制最高效的路径。【免费下载链接】northcinderBuyer-run, ad-neutral shopping-agent MCP software with deterministic ranking, signed purchase mandates, and a local audit trail.项目地址: https://gitcode.com/gh_mirrors/no/northcinder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考