外部消费方不是第四个服务
CONTRACT.md 开头 · 系统模型仍是三个服务
| item事项 | external consumer外部消费方 |
|---|---|
| TiKV keyspace | 无，不接触任何 keyspace |
| 回调义务 | 无，可以什么都不回报 |
| 内部字段可见性 | 无 |
| 可访问接口 | 只有三个导出接口 |
| 认证 | 独立 token，可单独吊销 |
⚠️ 外部消费方是一个受限只读边界，少了它系统照常闭环 —— 待定域名按 30 / 90 / 180 天退避自动重采。
⚠️ 导出给外部的域名是「所有对外请求都经过下载器」这条铁律的唯一豁免。因此必须满足两条约束：认领期间我方停抓、导出项携带限速与 robots 数据。
认领语义
DEV-sampler.md §8.3 · 与 lease 同构，不引入新概念
| state状态 | behaviour行为 |
|---|---|
| 未认领 | 按退避周期自动重采 |
| 被认领 | 采样器停止对该域名的一切请求 ★ 同一时刻单一出口 |
| 认领到期未回报 | 自动回到退避重采队列 ★ 兜底恢复 |
| 收到 hint_list | 采样器确认 → 写 domain_rule → POST scheduling-url/v1/rules |
| property性质 | benefit收益 |
|---|---|
| 认领有 TTL | 外部模块挂了、跑飞了、忘了回报 —— 域名自动回到我方兜底 |
| 不认领也能跑 | 系统闭环不依赖外部存在 |
| 同一时刻单一出口 | 铁律一在实质上得到保持 |
| 模式已验证 | lease、判定任务超时用的是同一套逻辑 |
⚠️ 调度器不需要知道认领的存在。verdict = unknown 的域名本来就不入队，认领是采样器内部状态。契约的 /v1/rules 不新增任何字段。
⚠️ 认领的释放不需要单独接口，三条路径：hint_list 里带 verdict 显式交还；expires_at 到期自动交还；采样器主动回收（consumer 被吊销，运维动作）。
当前认领
sampler:domain_claim_task:{domain} · claim_ttl_seconds 上限 7 天，超过按上限截断并在响应中说明
- claimed domains被认领域名
- 486
- active claims生效中的认领
- 3
- 24h hints24h 回报条数
- 128
- 回流解决率
- 61.4%
| claim_id认领标识 | consumer_id消费方标识 | domain_count认领域名数 | claim_ttl_seconds认领有效期（秒） | expires_at到期时间 | 已回报 | state状态 |
|---|---|---|---|---|---|---|
| c-4a17e902 | legacy-crawler-1 | 300 | 86400 | 2026-08-16T02:10:44Z | 184 | 生效中 |
| c-8b3d1f55 | legacy-crawler-2 | 150 | 604800 | 2026-08-19T22:35:07Z | 61 | 生效中 |
| c-06fe27ab | whois-checker | 36 | 604800 | 2026-08-15T11:02:19Z | 0 | 3 小时后到期 |
⚠️ 第二行请求的 claim_ttl_seconds 若超过 7 天（604800），按上限截断并在响应中说明，不是静默截断也不是报错。
⚠️ 第三行到期时 36 个域名自动回到退避重采队列，不需要任何人操作。这正是 TTL 存在的理由 —— 外部模块一挂，域名不会重新卡死。
verdict 回流的处置
DEV-sampler.md §8.5 · POST /v1/domain-verdict-hints
| external reports外部回报 | sampler action采样器动作 | scheduler result调度器最终行为 |
|---|---|---|
| csr | 写 domain_rule | 正常入队渲染 |
| partial | 写 domain_rule | 入队，降优先级 |
| ssr | 写 domain_rule | 丢弃该域名后续链接 |
| unknown + undetermined_reason | 按九个取值处置 | 丢弃该域名后续链接 |
⚠️ verdict 仍是契约那四个值，不新增枚举取值。verdict = unknown 时必须填 undetermined_reason。
⚠️ 外部只能提交建议，采样器确认后才写规则表 —— 与 v2 的 /v1/api-endpoint-hints 同一模式。域名级配置只能有一个所有者。响应返回 {accepted_count, rejected_count}。
⚠️ 幂等键是 claim_id + domain，在 payload 里，不引用内部字段。
近期回报
hint_list 逐条 · 采样器复核后才写入规则表
| domain域名 | consumer_id消费方标识 | verdict判定结论 | undetermined_reason判不出来的原因 | confidence_score置信度 | sampler decision采样器处置 |
|---|---|---|---|---|---|
| members.example.com | legacy-crawler-1 | ssr | — | 0.90 | 已确认写表 |
| shop2.example.jp | legacy-crawler-1 | csr | — | 0.82 | 已确认写表 |
| gone.example.net | whois-checker | unknown | domain_not_resolvable | 0.98 | 已确认写表 |
| flaky.example.tw | legacy-crawler-2 | unknown | consumer_capability_exceeded | 0.40 | 回退避重采 |
| odd.example.hk | legacy-crawler-2 | csr | — | 0.31 | 已驳回，置信度过低 |
⚠️ 第四行 consumer_capability_exceeded：外部也做不了。它不能退回「转人工」—— 那就绕回原来的黑洞了。回到退避重采，永不放弃。
⚠️ 第五行被驳回，计入响应的 rejected_count。驳回阈值属采样器内部策略，不在契约里，外部只知道被拒绝了几条。
导出率的读法
DEV-sampler.md §8.7 · 整套系统里第一个能直接反映采样器质量的在线数字
| observation观察到 | means说明什么 | action该做什么 |
|---|---|---|
| 导出率上升 | 采样器在退化：阈值漂了 / 反爬普及 / 新语种未标定 | 回阈值标定查基线 |
| 回流解决率高 | 采样器放弃太早，阈值该放宽 | 放宽阈值，减少导出 |
| 回流解决率低 | 这批确实超出能力范围 | 导出是对的，维持现状 |
当前回流解决率 61.4%，落在第二行：外部能判出来的，说明我方本来也有机会判出来。§十 定的「漏判率 < 5%」是离线标定的，上线后无法持续观测，这个数字是它唯一的在线代理。