Course Drift Oracle

Course Drift Oracle

针对 Microsoft 的 ai-agents-for-beginners 课程生成的签名漂移报告。它会扫描课程中两类悄然出现的问题：

• 模型固定项：指定了已弃用或计划退役的部署
• 软件包版本下限：开放的 >= 要求如今解析到的版本，比编写课程时所依据的主版本更新

这两类问题在差异中都不可见。课程仓库中没有任何信息会告诉你，某个固定的模型即将停止提供服务，或是如今运行 pip install 会拉取一个比课程内容所假定的版本高两个主版本的软件包。要回答这个问题，必须有人逐一对照平台自己的退役时间表和软件包的实际发布历史来检查这些固定项。本仓库会持续执行这项检查，并将结果作为签名报告提供。

为什么值得信任

每份报告都有签名，而不只是声明：

• 基于 RFC 8785 规范化 JSON 的 Ed25519 签名。 任何人都可以使用任何语言重建已签名的确切字节并重新计算哈希值。由 Python 签名的回执可通过 TypeScript 验证器验证，两者之间无需共享信任——请参阅 oracle/receipt.py（负责签名）和 worker/src/logic.ts（负责验证）。
• 只追加的发布链。 每份已发布的报告都是 oracle/chain.jsonl 中的一个链接，每个条目都指向前一个条目的哈希值。删除一个条目、编辑一个条目或调换两个条目的顺序，都会导致后续所有链接无法匹配。oracle/verify_chain.py 会独立于写入这些条目的代码来检查这条链。
• verify_report 免费。 付款前调用它，确认免费摘要中的说法有真实签名作为依据；付款后再调用，确认付费报告与免费摘要中已承诺的哈希值相符。卖家若提供的发现项少于承诺数量，会被算术验证揭穿，而不是靠信任来判断。
• 本仓库就是源代码。 这里的内容并非对产品的描述，而是产品实际使用的扫描器、签名代码和服务器，与在线服务运行时的形式一致。

五分钟内开始使用

该服务是一个通过流式 HTTP 提供服务的 MCP 服务：

https://signetworks.atelieri.workers.dev/mcp

可直接复制粘贴的快速入门示例，使用原生 curl，不依赖客户端库（此处的每条命令在写下前都已针对生产环境运行）：

# 1. Initialize and capture the session id from the response headers.
SESSION_ID=$(curl -si -X POST https://signetworks.atelieri.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0"}}}' \
  | tr -d '\r' | awk 'tolower($1)=="mcp-session-id:"{print $2}')

# 2. Complete the handshake.
curl -s -X POST https://signetworks.atelieri.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. Call a free tool. Responses are SSE frames; strip the data: prefix.
curl -s -X POST https://signetworks.atelieri.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"drift_summary","arguments":{}}}' \
  | grep '^data:' | sed 's/^data: //'

同样的模式可以调用上表中的每个工具；只需更改 name 和 arguments。

十个工具：

工具	价格	返回内容
drift_summary	免费	按严重程度和课程统计问题数量，并附带签名回执
verify_report	免费	检查回执的签名，并可选择验证问题数组是否与回执匹配
drift_report	$0.25	每条问题：文件、行号、诊断结果和修复方法。通过 MPP（Tempo 测试网）付费
drift_report_x402	$0.25	相同的报告，通过 x402/USDC（Base Sepolia 测试网）付费
model_status	免费	输入一个模型 ID，返回其签名目录条目：当前、已弃用、已停用，或如实说明“unknown: not in catalog”（未知：不在目录中）
model_status_batch	$0.10	输入模型 ID 列表，每个 ID 返回一条目，并附带 any_action_needed 门控布尔值；通过 MPP（Tempo 测试网）付费
model_status_batch_x402	$0.10	相同的批量查询，通过 x402/USDC（Base Sepolia 测试网）付费
site_audit_summary	免费	公共网站的 Agent 就绪度评分（12 项检查）：仅返回计数、目标和日期；每项检查的详细信息和签名回执属于付费档位
site_audit	$0.25	全部 12 项检查，包含每项检查的状态、详细信息和修复清单，并生成带签名的日期回执。通过 MPP（Tempo 测试网）付费
site_audit_x402	$0.25	相同的完整审计，通过 x402/USDC（Base Sepolia 测试网）付费

以下是 12 项审计检查，让你在付费前了解评分的含义： robots-exists、robots-ai-directives、robots-not-blanket、 llmstxt-exists、llmstxt-shape、llmstxt-links、mcp-advert、 structured-data、title-meta、charset、content-type-sanity、 homepage-response。其中 10 项可计分；homepage-response 和 robots-not-blanket 按设计仅提供信息性读数，不会给网站加分或扣分， 因此，即使网站毫无瑕疵，得分也是 10 分（满分 10 分），而不是 12 分（满分 12 分）。

典型运行流程：

1. 调用 drift_summary。它免费，会返回一份签名回执，说明问题的数量、严重程度以及受影响的课程。根据这些信息，判断是否值得购买完整报告。
2. 使用第 1 步中的回执调用 verify_report。在支付任何费用前，确认签名有效。
3. 支付 $0.25 并调用 drift_report（若使用 USDC 付款，则调用 drift_report_x402）。你会获得每条问题的文件、行号、问题说明和修复方法。
4. 再次调用 verify_report，这次将刚收到的问题数组和同一份回执一并传入。确认哈希匹配——这可以证明你拿到的是付费购买的全部内容，而不是经过删减的版本。

将其用作 GitHub Action

只需一行，即可将扫描器添加到课程仓库的 CI 中：

- uses: 710git/course-drift-oracle@v1

添加就这么简单——下面的每个输入都有默认值。

输入

输入	默认值	功能
path	.	相对于检出目录的待扫描目录
exclude	""	要跳过的目录名称或相对于仓库的路径，每项占一行；此外还会跳过扫描器内置的排除项
fail-on	critical	若存在严重程度达到或超过此级别的问题，则使此步骤失败（info、warning、critical）；留空则禁用门控
include-translations	false	同时扫描 translations/<locale>/...（默认仅扫描 en 目录树）
offline	true	跳过实时 PyPI 查询；仅使用捆绑的目录检查模型固定版本

输出

输出	含义
critical-count	严重级别问题的数量
warning-count	警告级别问题的数量
info-count	信息级别问题的数量
findings-path	本次运行生成的原始 findings.json 文件路径

为什么默认离线

查询 PyPI 依赖实时网络，而只需添加一行 CI 配置，不应默认就要求陌生用户联网。启用 offline: true（默认值）时，Action 只会根据此仓库中附带的目录检查模型固定版本，不会发起除检出仓库之外的任何外部请求。设置 offline: false，还会根据实时 PyPI JSON API 检查软件包版本是否漂移。

它绝不会触碰什么

Action 绝不会触碰 Ed25519 签名密钥或发布链（oracle/chain.jsonl）。它只读取提供给它的检出内容和 Action 附带的目录，不会向其运行所在的仓库写入任何内容。

自行验证回执

每个响应都包含一个 receipt 对象：一份签名声明，说明发现了什么、何时发现以及使用了哪个密钥，并与此前发布的每份报告相链接。verify_report 会通过 MCP 为你执行检查，但整个过程并非黑箱——实际执行这些操作的两个文件都很短且易读：

• oracle/receipt.py 构建并签署回执：规范化载荷（RFC 8785）、计算哈希（SHA-256）、签署哈希（Ed25519）。
• worker/src/logic.ts 在 TypeScript 中执行相同步骤以检查签名。将两者并排阅读，就没有任何内容需要盲目信任。

oracle/verify_chain.py 会遍历 oracle/chain.jsonl 中的完整发布历史，确认每个签名都有效，且每条记录都正确链接到前一条记录——买家或外部审计员会针对完整记录运行这项检查，而不只是验证单份回执。

免费的签名技能

skills/course-drift-check/SKILL.md 是使用此预言机的正确流程，专为 Agent 编写：付款前审查卖家，选择任一支付通道付款，然后验证商品。它免费且经过签名——其旁边的 receipt.json 会在同一个用于签署每份报告的 Ed25519 密钥下，承诺该文件的精确 SHA-256，因此加载此技能的 Agent 可以证明自己运行的是运营方发布的原始流程（oracle/sign_skill.py 是一个 100 行的签名工具；验证无需依赖我们）。签名证明来源和完整性，而非正确性——这正是此处每份回执都明确划定的界限。

付款

两种支付通道提供完全相同的商品：

• MPP（Machine Payments Protocol）旨在通过银行卡或稳定币结算；此部署目前在 Tempo 测试网上收费。
• x402 使用 USDC 结算，主要用于服务发现：通过 x402 Bazaar 搜索服务的 Agent，只会找到通过 x402 facilitator 结算的服务。

目前两种支付通道都运行在测试网上——MPP 使用 Tempo 测试网，x402 使用 Base Sepolia。x402 通道的付款机制已通过端到端验证：2026-08-28，一笔真实的测试网结算通过了实时运行的 worker（clients/ 中的买家客户端签署了一笔 $0.25 USDC 付款，facilitator 在 Base Sepolia 上完成结算，客户端并独立验证了其所支付的结果哈希——7 passed, 0 failed, 0 skipped）。尚未发生任何主网资金转移，MPP 结算也尚未实际测试；这些情况都如实说明，没有刻意淡化。你可以亲自复现验证：用水龙头 USDC 为临时钱包充值（无需 ETH），然后按照 clients/buyer/README.md 中的“Wiring a real x402 payer”操作买家。

此仓库包含的内容

oracle/     the scanner and the signing code
            (to run it locally: clone the course repo it scans, then
             python3 oracle/drift_scan.py --repo-root /path/to/ai-agents-for-beginners
             with no course checkout, --offline runs the model-pin
             checks only)
worker/     the MCP server: four free tools, six paid tools, HTTP 402
web/        the storefront pages served alongside the endpoint
clients/    an independent buyer client - run it yourself before you pay

私有仓库 Project-Office 是此镜像的来源，其中包含日常工作流程、部署自动化和凭据。使用或验证此服务都不需要这些内容，因此此处不包含它们。

诚实说明局限

• 截至撰写本文时，付款在测试网而非主网上结算。
• 此扫描器核对的模型和软件包目录由人工维护，目前仅涵盖有限的模型。覆盖范围会在每个周期扩展，但目前尚不全面。
• 签名验证可证明报告由此服务生成且未被篡改，但不能证明报告正确——这一说法依据的是每项发现中引用的来源，你可以自行核查。

许可证

未包含许可证文件。若没有许可证，默认保留所有权利；这应由仓库所有者明确决定，而不应是疏忽所致。

联系方式

[email protected]