企业官网建设流程全解析

• 后端
• API网关
• MCP 服务
• dsh-plugin

导读

Enrich Arena 是 treg 开源仓库中的一个独立付费功能模块：它把同一条 enrichment（数据补全）查询并发地发送给多个数据供应商，让用户在 Battle（对比）与 Waterfall（按价格升序依次尝试）两种模式下比较各家返回的结果、成本与耗时，并通过一键点赞/点踩沉淀持久化反馈。本文以仓库文档 docs/context/interface/enrich-arena.md 为主线，结合 application/arena.py、domain/arena.py、routers/arena.py 等源码与测试，完整讲解它的页面结构、任务体系、报价与准入机制、执行模型、历史洞察流水线、验证功能与隐私边界，读者读完可以掌握该模块从输入校验到计费结算的完整调用链，以及它区别于普通数据 API 网关的关键设计。

本文是 Enrich Arena 模块的功能与实现指南，不构成对任何数据供应商效果的承诺；文中所有"命中/未命中"均指结构化结果，不代表数据准确性的独立验证。

一、页面形态：三个共享 Shell 的入口

Enrich Arena 由三个共享同一套 Vue 应用的页面组成，路由在 routers/arena.py 中统一返回enrich-arena.html：

• /enrich-arena—— 主页面，包含任务选择、输入区、报价、执行与结果；
• /enrich-arena/leaderboard—— 榜单页，只读展示聚合历史洞察；
• /enrich-arena/people-search-bench—— Benchmark（People Search Bench），只读展示来自/people-search落地页的公开分类评分。

三页共享一个紧凑的账号 Header：Arena / Leaderboard / Benchmark 导航居中，社区链接（GitHub "Open source"、Discord、X）、团队切换器、余额徽标与 Sign out 分布在两侧。按照 enrich-arena.html 的实现，多团队用户才显示 Team 切换器，单团队自动选中且不出现下拉框。余额徽标本身是一个按钮，点击通过topUp打开/app?from=enrich-arena#billing，并保留当前团队与 Arena 草稿。

三个页面的行为边界在文档中写得很明确：

• Arena：可以保存查询草稿、恢复历史、发起付费执行、请求报价；
• Leaderboard：读取与 Arena 相同的数据库快照，但不恢复草稿、不恢复运行、不获取历史、不请求报价；
• Benchmark：启动时加载一次同源/people-search落地页，用ArenaBench.parseDocument抽取已发布的分类评分绘制图表；不完整的分类或非数字评分会显示重试/来源链接错误，而不是部分图表。

二、任务体系与输入校验

2.1 九类任务与输入变体

任务定义集中在 domain/arena.py 的TASKS常量中，共 9 项：

其中people.search与companies.similar属于 Discovery 查询（见第六节）；注释里记录了输入变体顺序来自 30 天生产样本的真实需求占比（约 94% 的 people.search 调用带公司域名）。2026-09-14 起，原people.company.search任务合并进people.search，历史运行通过 catalog_capability() 中的_LEGACY映射仍可解析。

2.2 提交前校验：宁可 422 也不要花一分钱

validate_identity()（domain/arena.py）在创建报价之前完成全部格式校验，测试 test_enrich_arena.py 专门断言这些畸形输入直接返回 422 且不产生任何ArenaRun记录或 Hold：

• 邮箱：必须同时包含非空 mailbox 与带点的域名，person@example、person@example..com、person@example.com/path都会被拒绝；合法的person+tag@example.co.uk、O'connor 和中文邮箱则被接受；
• 公司域名：必须是http/https且主机名含点，拒绝ftp://、嵌入式凭据（user@example.com）、畸形端口（example.com:bad）与畸形方括号主机（https://[invalid）——_web_url()用url.port访问来兜住解析器会抛异常的畸形端口，避免历史结果不可读；
• LinkedIn URL：必须是https://www.linkedin.com/in/<handle>（公司任务要求/company/），拒绝路径之外的 scheme、非法主机与空白；
• 姓名：基于名字的比较要求 first + last 双名，validate_identity只要求首尾两段各含至少一个字母，因此Mary-Jane O'Neill、José García、李 小龙都能通过（test_name_validation_preserves_real_name_characters）；文档明确提示：拿不到全名时请改用 LinkedIn URL；
• 电话：必须匹配+加国际区号的格式（+[1-9][0-9]{6,14}），或者提供 ISO-2country_code的国内号码；没有可用的国家上下文时不会猜测默认国家，而是返回具体说明且不发起任何计费调用。

多条目批量输入由validate_entries()（domain/arena.py）统一处理：enrichment/verification 最多 50 条、discovery 最多 10 条；所有条目必须是同一输入形状；空白行、重复身份（大小写不敏感指纹去重）会被阻止提交；服务端会在规范化域名、姓名与 LinkedIn URL 之后重复校验。

三、报价模型：公开预估与团队报价

3.1 公开预览：GET /arena/tasks

未登录访客也可以浏览任务、选择输入变体与执行模式并看到供应商价格。public_tasks()（application/arena.py）对每个任务的每个输入变体做一次"形状探测"：用probe中的示例值走route.canonical_identity与route.candidates_for得到候选端点，再基于**已验证适配器 + 规范化派生 + 请求定价（含适配器常量与平台加价）**计算每条预估。它的约束在设计上写得很清楚：

• 不读团队、不读存储报价、不做上游调用；
• 排除异步端点、bulk 端点与EXCLUDED中的个人邮箱查找器（如leadmagic.x.personal-email-finder）；
• 返回的provider_previews按预估升序排序，供页面在输入框下方直接渲染紧凑的供应商/价格表。

3.2 团队报价：POST /arena/plans

登录用户的有效输入在 800ms 停顿后取报价。quote()（application/arena.py）是核心入口：

1. 先做上述输入校验 + 国家代码校验（country_name未知即拒绝）+ demo 团队拦截 + 模式与预算校验（mode ∈ {compare, waterfall}，0 ≤ max_cost_micro ≤ 10_000_000，即单次上限 $10）；
2. 对每条 entry 通过现有路由规划器route.build_plan冻结精确的适配器请求（to_upstream之后的 query/body）、端点哈希、适配器哈希、身份、顺序、预估与预算，全部加密进ArenaRun.payload；
3. 平台级报价 =money.with_margin(_marketplace_pricing(...))，含配置的平台加价；own-key（自带密钥）调用 treg 报价为 0；
4. Battle 的准入额度 = 所有供应商预估之和；Waterfall 的准入额度 = 每条 entry 最便宜第一步的预估之和（required_credit()，domain/arena.py），页面 Run 按钮显示 "Run from" 最便宜供应商的报价；
5. 报价 5 分钟过期（deadline_at），创建报价不预留任何信用额度；旧的未使用报价（超过 100 条）会被惰性退役，而已完成/运行中的会话不受影响（对应测试 test_automatic_quotes_do_not_use_execution_limit_or_erase_history）。

文档特别强调：报价是"按报价的准入限制"，不是对供应商最终账单的担保；UI 会披露这个差异。身份、模式、团队、预算或供应商任何变化都会使当前报价失效并丢弃迟到响应；一次完成运行消耗其报价，新运行必须重新取报价。

四、执行模型：Battle 与 Waterfall

4.1 启动与一次性认领

POST /arena/runs/{id}/start（application/arena.py）做完整的重检后才认领运行：

• 校验报价未过期、目录哈希未变化（_hash(ep)与_hash(adapter.__dict__)，防止目录悄悄换掉端点后旧报价仍能触发计费调用）；
• 重查余额（Battle 需要全部预估之和；Waterfall 只要最便宜第一步，且允许余额恰好相等）；
• 执行限制：100 次实际启动/小时/用户，且同时最多3 个活跃运行（价格预览不计入限制，429 错误文本明确说 "price previews don't count"）；
• 用条件 UPDATEWHERE state='quoted'在数据库层原子认领一次——两个并发 start 只有一个能派发（test_concurrent_start_dispatches_only_once）；
• 认领成功后发出arena_run_started分析事件（不含输入内容）。

所有 Arena 变更端点都经过_guard()（routers/arena.py）的同源检查，跨源请求直接 403（测试 test_no_partial_or_foreign_vote_and_no_cross_origin_start）。

4.2 Battle：四路并发对比

compare模式用asyncio.Semaphore(4)限制最多四条并发腿，每条腿：

1. _fresh_caller()重新校验 membership、用户/组织未停用、以及发起时携带的托管密钥仍活跃且仍属于同一 membership/team（密钥生成代次变化会阻止后续步骤，但不取消已在途请求）；
2. 先持久化running状态（派发前可见），再构造CallInput并携带x-treg-client: enrich-arena、x-treg-route-max-cost头，通过现有 application.call.service.execute_call 打直接端点；
3. 每条腿有 90 秒超时，运行总期限 240 秒（批量按 240 秒/条封顶一小时）；
4. 每次尝试都记录 charged/duration，并在落库前关闭响应流。

普通调用运行时负责定价、凭据优先级、授权、预留（reserve）、结算（settle）与取消清理；Arena 本身从不写余额或持有多余的 Hold。聚合器溢出（overflow）在此关闭、归档查找被绕过，保证对比测量的是全新调用。

4.3 Waterfall：按价格升序、命中即停

waterfall模式在 application/arena.py 中实现：

• 供应商按报价升序排序（平局保留规划器顺序）；
• 每步显示 queued/running、found/no match、error/timeout、skipped/not attempted、timing、charge 与停止原因；
• 在第一个结构化命中处停止——"found work email" 不代表已验证可达，"found phone" 不代表活线，一个负面的邮箱验证结论反而是成功答案；
• 错误回退有界（route.MAX_ERROR_FALLBACKS）；供应商侧 401/403 会被标记为 caller-fault，后续步骤不再在该付费服务上重试；
• 运行预算上限是共享的：spent + estimate > max_cost_micro的后续步骤标记为skipped；
• 批量 Waterfall 按价格层级推进：先完成列表里所有条目的同一档价格，未解决的条目再进入下一档（见entry/stopped逻辑与测试 test_batch_waterfall_stops_per_entry_and_manual_uses_correct_identity）。

4.4 取消、中断与账单恢复

• 取消通过轮询cancel_requested标志 + 取消在途 asyncio 任务实现；取消会释放所有 Hold，且取消轮询绝不在数据库 I/O 内部被取消——否则 SQLite rollback journal 下会遗留读锁，阻塞最终提交与测试 schema 重置（测试test_run_finishes_while_cancel_poll_is_reading专门覆盖该竞态）；
• 进程丢失后运行按持久化的 deadline 变为interrupted，绝不自动重试（避免一次不确定的上游完成后重复付费）；
• 未知费用保持未知，直到持久化账本（LedgerEntry的settle/release）能在后续读取中解析；get_run会用账本条目回填charged_micro（测试 test_interrupted_receipt_recovers_durable_settlement）；
• 重复 start 幂等：row.state != "quoted"时直接返回当前状态而不重复派发。

五、结果呈现、历史与持久化反馈

5.1 可见结果与胜者规则

GET /arena/runs/{id}返回私有、归属明确的快照；运行中 UI 每 1.5 秒轮询，实时显示每个供应商 queued/running/completed 状态。展示层保持"查看结果 ≠ 投票 ≠ 付费调用"的边界：

• 单条命中即出现结果；无确认价格弹窗；每个结果行有供应商 logo、关键字段、状态、成本、耗时与独立的一键 👍/👎；
• 点击行或 Enter/Space 展开完整字段与原始响应（原始响应单独存储、不参与归一化）；
• 工作邮箱行的返回域名与请求公司域名不一致时会标记（子域名可接受），这只是"可能不匹配"提示，不自动判定无效，也不改写供应商答案；
• 供应商 402 与团队余额拒绝是两种状态：upstream_status字段保留前者（domain/arena.py），UI 提示改用其他供应商，而不是引导充值；
• 一个 👍 即产生 Winner 皇冠；Fastest/Cheapest 腰带只在"成功且未被点踩"的结果之间比较；多个 👍 时腰带只在这些结果内比较；未评分供应商不能超越已点赞供应商；评分变化立即重算胜者与腰带。历史比较评估（ArenaEvaluation）保持不变但不驱动当前胜者指示器。

5.2 批量矩阵

多条目运行使用 entry-by-vendor 矩阵代替单表：概览单元格只显示已尝试结果（queued/skipped/uncalled 留空）；点击某行展开该条目下嵌套的供应商详情表；一次只展开一个供应商或条目，避免重复反馈表单与 ID。Found 用绿色对勾徽标、No match 用红色叉徽标，颜色与符号双通道区分。运行成本汇总在条目控件上方，使用服务端结算总额（含验证与不成功调用）；平均成本 = 总额 ÷ 有 found/非 rejected 结果的去重条目数（多个供应商找到同一人只计一次）；运行结束自动滚动到该汇总（reduced-motion 用户立即滚动）。

5.3 历史列表与私有书签

• 左侧会话列表每页 30 条，GET /arena/runs?limit=1..100&before=<id>按创建时间与 ID 双键降序分页（并列时间戳靠 ID 决胜，新运行不会移动旧页边界）；
• 读取历史不做任何供应商调用（测试里no_relay直接 fail）；
• 选择历史或启动运行会写入/enrich-arena?run=<id>&team=<slug>URL；该 URL 只能由所属团队的登录成员读取，缺失/过期/无权访问显示错误而不是回退到别的结果——这是私有书签，不是公开分享链接；
• 草稿保存在 session-storage（10 分钟、单次使用标记），OAuth 返回只允许 Arena/Leaderboard/Benchmark 路径且带 Fernet 加密的 return cookie，回调先认证再解密并再次白名单校验，缺失或篡改则回退到 dashboard。

5.4 反馈：点赞/点踩、报告与兼容评估

• 每个返回结果（两种模式、含批量单格）可即时 👍/👎：POST /arena/runs/{id}/attempts/{attempt_id}/rating乐观更新、失败回滚并报错；重复相同评分幂等，切换 thumbs 则更新记录（保留created_at）；
• 👎 可追加可选 reason/note（/report，首条提交幂等，绝不覆盖其他标签页的 👍）；评分与报告存于 attempt 加密 payload，仅对会话所有者/团队私有，随历史/导出在 30 天保留期内共存；
• 旧版POST /arena/runs/{id}/evaluations保持兼容：winner/tie/none/cannot-judge/skip 类型与/reveal仍在，首条评估在 run-row 锁 + 唯一 run-id 约束下不可变；v2 评估携带feedback_context: attributed、冻结的 cohort 指纹与暴露的候选 id/顺序，用于区分"归属明确的偏好"与历史盲投；revealed_at只记录评估事件，不再控制结果可见性；
• 反馈永不改变供应商输出、命中分类或计费。

六、Discovery 查询与验证功能

6.1 Discovery：Find people / Find similar companies

• Find people（people.search）四种输入变体按需求排序；Find similar companies（companies.similar）接受种子域名；
• 这些是直接目录查询：无 agent 框架、无模型编写计划、无自动翻页、无隐式后续 enrichment；
• 每个批次查询返回各供应商自己的列表，最多显示 10 个归一化匹配；预览价格按这些精确请求计算；会丢弃请求约束或合约过滤的适配器（包括结果上限）会被排除出公开预览与私有计划；未知国家代码在规划前拒绝而不是静默省略；
• Waterfall 对 discovery 的"结构化命中"定义为可用的非空列表，不是相关性判断；批次覆盖率和 cost-per-kept 以 query 为分母，不是联系人数量；
• discovery 端点暂不进入 enrichment 洞察聚合，直到出现合适的 discovery 指标。

6.2 可选验证（lookup 之后）

• Find work email 与 Find phone number 默认开启验证开关（存于草稿并绑定进报价）；验证通过treg.people.email.verify路由运行时执行，候选按价格顺序优先，报价上限 = 所有可达验证器预估之和（own keys 零成本）；
• 冻结的供应商集合 + 目录哈希 + route-max-cost 头共同约束执行，新加供应商不能悄悄进入既有报价；路由器在不可用供应商/缺失判定上按既有错误回退限制降级，在 completed valid/invalid/risky 判定处停止；
• 电话验证是直达 Tomba 的单供应商调用（当前只有一家集成电话验证器）；
• 未勾选验证的 found 结果行上有按价格的 Verify email/phone 动作：5 分钟报价、同源、owned、读取加密存储结果中的联系方式、认领嵌套 attempt 恰好一次；每行独立 UI 状态，不阻塞其他供应商；
• Verify phone number 也是独立批量任务：默认要求+国际号码，也接受国内格式 + ISO-2country_code；verification_identity()会把 lookup 报告的国家上下文带进验证请求（Tomba adapter 作为查询参数转发），显式国际区号优先于上下文；缺失/不可用上下文会给出明确解释且不发起也不计费验证调用（not_started状态 → "Verification not run"）；
• 验证只给出号码规划有效性、国家、线路类型与运营商，不证明线路是活的或属于目标人。

6.3 邮箱验证结果的分级展示

邮箱验证行使用emailVerdict/outcomeClass显示三色判定：Valid（绿）/ Invalid（红）/ Risky（琥珀），而不是笼统的"返回答案"徽标；catch-all/accept-all 与显式 risky 优先于 adapter 的valid布尔；unknown/unverified/unrecognized 保持中性 "Unknown"，绝不会因为 adapter 投影valid: false就显示为 invalid；原始供应商状态保留在结果与展开数据中。显式 invalid/undeliverable 判定会在锁定后端合并时自动创建incorrect_data报告（幂等、跨 worker 生效、带automated_verificationprovenance），UI 标记为 "Invalid email · automatically reported"；catch-all、unknown、risky、失败/取消的检查与电话判定都不会触发该规则。

七、历史洞察：两分钟增量流水线

7.1 采集器：drain()与collect_batch()

Arena 表只展示四列历史统计：Vendor、Hit rate（验证任务为 Verdict rate）、Response time、Price，数据来自application.arena_insights的数据库聚合，页面渲染绝不扫描证据或调用验证器：

• 采集器由treg-worker arena insightscron 每两分钟运行一次（drain()，application/arena_insights.py），--max-seconds约束单趟时长，下一趟从游标续跑；
• 它已从 web 进程 lifespan 协程移出——之前每个 web 进程（含部署期的多余实例）都会争抢游标行并全表扫描callrecord，与资金路径争数据库；现在只使用 worker 进程唯一的 API 连接池；
• 每事务读 100 条审计记录，沿精确的归档 key/content 与可选 body 载体取证据，用当前 Arena 必需字段规则重新分类存储的响应，upsert 匿名ArenaObservation事实；它从不调用供应商、从不信任CallRecord.hit，不写钱、不碰代理；
• 证据去重按 key/content 对，通过既有(key_id, version)索引找每对最新快照——避免同一响应被许多请求共享时反复扫全局内容索引；确切内容缺失保持 unresolved，新答案绝不替代历史证据；
• ArenaInsightState跨 worker 序列化游标并存储聚合；首次回填前部分初始历史被隐藏；版本触发的重建期间旧的已完成发布仍然可见；SQL 里 PostgreSQL 计算中位数与去重计数，本地 SQLite 用精确 Python 中位数；values CTE 要求 SQLAlchemy 2.0.42+（已反映在服务端依赖下限）。

7.2 保守分类规则

domain/arena_insights.py 的error_outcome()定义了什么算"覆盖"：

• 覆盖 = 结构化可用结果 ÷（可用结果 + 真实 miss），每个 endpoint/input/request-hash 取最新一次 decided 观察；
• 错误请求、限流、余额、访问/服务失败、拒绝与 pending 结果被排除；歧义错误、不可用 body、缺失 request hash 保持 unresolved；
• own-key、overflow 与缓存 scope 被省略；只有可归属到所选形状的输入才出现在该行；
• 响应时间 = 成功调用（含重复）的中位数，至少 20 次成功且有时序聚合才显示；唯一请求少于 20 次时隐藏比率；验证显示的是"返回判定"占比而不是准确率；
• 不同 cohort 与 waterfall 位置决定了这里不能产生受控排名，返回字段也未独立验证——文档与页面都明确这是"观测结果，不是受控基准"。

7.3 快照读取与公开验证试点

GET /arena/insights（routers/arena.py）先按主键读当前版本的持久化聚合（含updated_at、源窗口、真实观测首末日期、采集状态与仅公开聚合字段）；当前版本未发布时，用一次有界快照查询回退到上一版本最新完成的兼容发布，保留其源窗口与更新时间戳；全新数据库返回warming空行。UI 每两分钟轮询一次，刷新失败保留最后一次成功值并显示最后更新时间。

验证试点部分（application/arena_verification_insights，Alembic0029）发布只含聚合的ArenaVerificationSnapshot，/arena/insights把它作为verification附加到滚动调用统计旁：

• Email validity rate：样本中两个验证器都标记 valid 的去重邮箱数 ÷ 已完成检查数（不乘 lookup 命中率，也不需要历史基线）——这是样本内观测到的验证器一致性，不是投递保证或所有权；
• Phone format validity：通过格式检查的样本号码百分比，绝不被提升为 email validity 或 verified hit rate；
• 少于 20 次已完成检查的比率被隐藏，small-sample 标签不显示；risky/unknown/冲突判定留在分母但不计 valid；未完成检查排除；真 0 显示、缺失值无图表柱；
• 发布保留旧rate投影给老消费者，同时加checked_n/validity_rate（电话为format_validity_rate）字段，UI 只消费新字段，防止旧快照把 lookup 投影误显示为 validity。

迁移部署后可用uv run python scripts/import_arena_verification.py /private/path/aggregate.json导入公开聚合（--check只校验不写库；文件必须留在 checkout 之外）；导入器只接受 schema 白名单内的聚合、源日期、端点/输入标识、验证器名与计数，拒绝原始联系方式字段，也不运行付费验证。相同 run_id 的重复导入是 no-op，内容不同则失败。

八、多条目批处理与手动补调

8.1 批量运行语义

• POST /arena/plans接受identity或identities之一（不可同时）；服务端要求单一输入形状 + 共同供应商 cohort；每条 entry 都走既有路由规划器，拥有独立冻结的 adapter 请求与预估；
• 原始响应快照共享每运行 2 MB 上限，按 attempt 均分、单响应 256 KB 封顶；超限仍做正常分类与字段提取，raw_omitted在展开详情中说明缺失原因（测试 test_batch_raw_snapshot_limit_keeps_normalized_answers 证明归一化答案不受影响）；
• Battle 对每条 entry 的每个选中供应商都调用，共享四腿并发上限；Waterfall 按价格层级推进、每 entry 独立 hit/error 状态、运行花销上限共享；批量不可负担时没有隐性部分购买，未触及的尝试留给显式、按格的 Try 动作；
• 批量运行期限 240 秒/条、封顶一小时；单批占据一个活跃运行槽；每次尝试后持久化状态，刷新/历史恢复只读不花钱；取消与进程丢失保留已完成工作，绝不重试已派发调用。

8.2 Try：给未调用供应商补一次机会

每个not_attempted/skipped结果有按价的 Try 动作（/attempts/{id}/plan+/start）：

• plan 重查该精确端点的当前路由访问并计算真实 adapter 请求预估，在运行加密 payload 里存 5 分钟报价，不预留信用、不调用供应商；
• start 锁定 owned run、重查报价/目录哈希/信用准入/活跃运行上限，认领未调用 attempt 恰好一次；已完成尝试（含 error/timeout/interrupted 的手动尝试）绝不提供 rerun；
• 最多 4 条手动尝试并发；手动尝试与原始 waterfall 预算分开准入；结果带manual: true，时序在先前尝试之后继续；重复 start、过期报价、已尝试供应商均无法派发；
• 持久化以 run-row 锁合并，只合并该 worker 自己的 attempts，保留并发报价、结果与反馈；运行只有等所有活跃尝试结束才进入 terminal。

九、隐私、安全与运维

9.1 隐私边界

• 运行与评估属于创建者 + 活跃团队；其他团队成员不能读创建者的运行；输入、响应快照与评论用既有 Fernet 密钥加密（测试直接断言stored.payload != plaintext）；
• 结果每供应商 256 KB 封顶；访问 30 天后过期，有界惰性清扫在历史/报价请求上删除过期运行与评估；团队删除先删评估再删运行；账本正常保留不变；
• 页面通过sitetrack.js的data-private-page标志退出 PostHog autocapture 与 session recording；输入不进 URL；所有 Arena 路由属于 control role（及默认 all role），dataplane 的/call/合约不变；
• GET /arena/insights不暴露身份、哈希、组织 ID 或响应体；生产指标不出现在 assets 或 fixtures 中。

9.2 分析事件（转换漏斗）

TregTracking将匿名页面浏览在loadIdentity后连接到已认证邮箱与活跃team组，事件仅含产品元数据：

• arena_page_viewed（挂载即发、每页一次、带surface=arena|leaderboard|benchmark）与arena_signup_opened；
• signup_completed仅在提交后且是新 User时发出（email OTP 与 GitHub/Google provisioning）；回归登录与失败证明不计；
• arena_run_started在数据库认领成功后发出（报价与重复 start 不计数）；arena_run_completed在保存初始运行的 terminal 状态后发出，含successful_call（至少一个 hit 或 evaluated miss）与returned_data（至少一个 hit）；进程崩溃后的完成不会被重建；手动 Try 与验证继续发普通tool_called事件（client=enrich-arena），不产生额外逻辑运行事件；
• arena_topup_clicked记录链接点击，应用在两个充值入口都带checkout_source=arena，Stripe Session/PaymentIntent 元数据同时携带首入渠道与 checkout 来源，保证任一 webhook 顺序都可用。

漏斗建议（文档原文）：对arena_page_viewed过滤surface=arena计数独立访客 →signup_completed→tool_called过滤client=enrich-arena（成功调用加outcome=ok），使用有序列转换窗口（如 30 天），把回归用户激活与新用户激活分开报告；把激活用户的 run/callteamjoin 到后续topup_completed可捕捉队友付费，按预期粒度对人/团队去重；新付费者按团队首次充值计数。事件仍是 best-effort 分析（未配置 key 即禁用），持久化账本才是支付事实来源。

9.3 迁移与测试

Arena 迁移按序排在主链0026（call reviews）之后：0027_enrich_arena.py（arenarun+arenaevaluation）、0028_arena_insights（ArenaObservation+ArenaInsightState）、0029_arena_verification_snapshot（ArenaVerificationSnapshot）。发布新版本前先运行python -m treg upgrade。

测试覆盖面（依据 test_enrich_arena.py）：私有/访问控制、聚合准入、直接计费、own keys、取消、重复 start/投票、归属进度/结果、计费前姓名校验、waterfall 推进、OAuth 返回白名单、中断账单恢复、畸形输入零开销等。前端计费流检查用node --test tests/js/enrich-arena.test.cjs覆盖内联定价、价格失效、登录门禁、重复点击、报价过期与正确团队充值链接；arena-template.test.cjs 用打包的 Vue runtime 编译共享页面与组件模板，专门捕获方法级测试漏掉的模板表达式错误（此前嵌套 footer 插值曾导致所有 Arena 视图无法挂载）。

十、关键设计原则小结

1. 先校验、后报价、再执行：一切畸形输入在创建报价/计费前就被 422 拒绝；报价创建零预留，执行时才做余额与目录哈希重检；
2. 认领一次、绝不重复：数据库条件 UPDATE + 进程内 task 所有权 + 永久 deadline，进程丢失绝不自动重试，避免歧义完成后的重复付费；
3. 复用普通调用运行时：定价、凭据优先级、授权、reserve/settle/release、取消清理全部来自application.call.service.execute_call，Arena 只增加编排与展示层，不触碰资金写路径；
4. 观测不等于基准：历史洞察是匿名、保守分类、快照化的数据库聚合，页面反复声明其"不是受控基准"，验证比率是"判定返回率"而非准确率；
5. 反馈可追溯但不可篡改：旧版评估不可变，新版 thumbs/report 归属明确、幂等、随运行加密保留，但永不改变计费与结果分类。

如需在本地查看/运行该模块：仓库为只读，读者可在自己的环境中克隆后按 部署文档 与 本地运行文档 配置环境，执行python -m treg upgrade完成迁移，再启动服务访问/enrich-arena。

• 后端
• API网关
• MCP 服务
• dsh-plugin