[Question] 数据遥测：如何将局内难度数据纳入自动发送的对局记录？

[iouter]

范围

Usage（使用）

你的问题

尝试使用数据遥测功能，并成功接收到了对局记录。

但是有个难度选项，已经通过“局内数据”，加到了对局中，该怎么样让它也加入到自动发送的对局记录中呢？

补充上下文

No response

[ritsukage-local-analyzer]

Warning

此分析由 AI 自动生成，仅供开发者参考，最终判断请以人工确认为准。如有疑问建议结合本地环境进一步复现确认。

摘要

这个问题更像是数据遥测 API 的接入问题，而不是当前已确认的缺陷：RunSavedData 能把局内数据保存进跑局存档扩展，但自动发送的 run_history 遥测不会因为某个槽位存在就把它并入原版对局记录 JSON。建议维护者给出官方接入示例：把“难度”作为 RunHistory 类别的 telemetry contribution 注册，并在对应 TelemetryRequest.RunHistory(...) 中订阅它；若目标是改写原始 run_history 字段，则需要明确说明当前 API 不自动支持。

重点结论

项目	结论
简单介绍	提问者已能收到自动发送的对局记录，但希望把通过“局内数据”保存的难度选项一起随对局记录发送。
可能原因	较高可信度：自动对局记录采集只序列化原版 SerializableRun，并把额外数据走 telemetry contribution 机制；RunSavedData 本身是存档/同步扩展，不等同于遥测字段自动提升。
可能解决方案	为难度数据实现 ITelemetryContributionProvider，Category = TelemetryDataCategory.RunHistory，通过 RitsuLibFramework.RegisterTelemetryContributionProvider(...) 注册；同时在 TelemetryRequest.RunHistory(...) 的 ContributionSubscriptions 中订阅该 contribution。
建议处理	将 issue 作为 type/question 保留并回复用法；可补一段文档或示例，说明 RunSavedData 与 RunHistory telemetry contribution 的桥接方式。

展开详细分析、证据与验证

问题描述

期望行为

• 难度选项已通过“局内数据”写入当前跑局后，也能出现在自动发送的对局记录遥测事件中。

实际行为

• 自动发送的对局记录已可被接收，但难度选项没有随该记录自动发送。

复现步骤

• 使用数据遥测功能并成功接收到对局记录。
• 把一个难度选项通过“局内数据”加入跑局。
• 查看自动发送的对局记录，未看到该难度数据。

日志、附件与原文摘录

• 原文：

  尝试使用数据遥测功能，并成功接收到了对局记录。
  但是有个难度选项，已经通过“局内数据”，加到了对局中……

  要点：这是“如何把已有局内数据纳入遥测”的用法问题，未提供错误日志或异常。

详细分析依据

• README.zh.md:87-README.zh.md:94 将“存储跑局内数据”入口列为 RitsuLibFramework.GetRunSavedDataStore(modId)，说明“局内数据”主要是跑局保存数据能力。
• src/RunData/RunSavedDataStore.cs:47-src/RunData/RunSavedDataStore.cs:86 显示 Register / RegisterPerPlayer 只注册跑局保存数据槽位，并进入 RunSavedDataRegistry。
• src/RunData/Patches/RunSavedDataPatches.cs:367-src/RunData/Patches/RunSavedDataPatches.cs:384 在保存跑局时导出 RunSavedData，src/RunData/RunSavedDataDocument.cs:8-src/RunData/RunSavedDataDocument.cs:11 显示其扩展根字段为 _ritsulib.run_saved_data。这证明它会进入保存/同步扩展，但不证明会自动进入 telemetry 的对局记录 payload。
• 自动对局记录采集在 src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:185-src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:244：结束跑局后序列化 evt.Run 为 SerializableRun，为每个已授权且注册了 run_history request 的 applicant 调用 CaptureVanillaRunHistory(..., applicantPayload: null, properties)。
• src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:155-src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:182 构造的 payload 是 run_history 加可选 mod_payload；自动路径传入的是 null，所以不会天然加入提问者的难度字段。
• contribution 机制在 src/Telemetry/Core/TelemetryEnvelopeFactory.cs:143-src/Telemetry/Core/TelemetryEnvelopeFactory.cs:161 装配 private_contributions / shared_contributions，来源由 TelemetryRegistry.ResolvePrivateContributions / ResolveSharedContributions 决定。
• src/Telemetry/Core/TelemetryRequest.cs:36-src/Telemetry/Core/TelemetryRequest.cs:42 和 src/Telemetry/Core/TelemetryRequest.cs:125-src/Telemetry/Core/TelemetryRequest.cs:137 表明 RunHistory request 支持 ContributionSubscriptions；这是把额外 mod 数据挂到对局记录遥测上的现有入口。
• src/Telemetry/Contributions/ITelemetryContributionProvider.cs:23-src/Telemetry/Contributions/ITelemetryContributionProvider.cs:42 定义 contribution 的类别、可见性和 Build(...)；src/RitsuLibFramework.cs:1148-src/RitsuLibFramework.cs:1155 暴露了注册入口。

一个维护者可回复的最小方向：

RitsuLibFramework.RegisterTelemetryContributionProvider(new DifficultyContributionProvider());

RitsuLibFramework.RegisterTelemetryApplicant(new TelemetryApplicant
{
    ApplicantId = "your.applicant",
    OwnerModId = "YourMod",
    DisplayName = "Your telemetry",
    Adapter = yourAdapter,
    Requests =
    [
        TelemetryRequest.RunHistory(
            "Send run history with difficulty context.",
            sharedContributionSubscriptions: ["difficulty"]),
    ],
});

其中 DifficultyContributionProvider 应返回 Category = TelemetryDataCategory.RunHistory，如果只发给本 mod 自己的 applicant，可使用 Visibility = TelemetryContributionVisibility.PrivateToApplicant；如果允许其他 applicant 接收，则使用 SharedToAuthorizedSubscribers，订阅名通常写成 YourMod/difficulty，且需要用户对共享来源授权。Build(...) 内部可从 mod 自己维护的运行时状态或可定位的 run-saved data 读取难度并返回一个小的 JsonObject。

反馈规范性提醒

维度	状态
复现步骤	含糊：描述了使用场景，但没有最小代码片段或注册顺序。
期望/实际	已提供：希望难度进入自动对局记录，实际未进入。
环境与版本	缺失：未说明 RitsuLib 版本、游戏分支/版本、单人或多人。
日志/附件	缺失：本问题偏用法咨询，日志不是必需，但若怀疑是丢包/授权问题则需要 telemetry 日志。
标题与背景	已提供：标题和正文能定位到数据遥测 + 局内数据桥接问题。

详细验证建议

• 维护者用一个测试 mod 注册 RunSavedData 槽位并在跑局中写入 difficulty。
• 同一 mod 注册 ITelemetryContributionProvider，类别设为 RunHistory，Build(...) 返回该难度值。
• 注册 TelemetryRequest.RunHistory(...) 并订阅该 contribution；确认用户授权后结束一局。
• 检查发送的 telemetry envelope：原版对局记录应仍在 applicant_payload.run_history，难度应出现在 private_contributions 或 shared_contributions 下。
• 若希望难度直接出现在 run_history JSON 内，单独确认是否需要新增 API 或文档说明“不建议/不支持改写原版 payload”。

风险与未决

• 还不能判断提问者是自有 applicant 发送数据，还是想把某个 mod 的 difficulty 共享给另一个 applicant；这会影响 PrivateToApplicant 与 SharedToAuthorizedSubscribers 的选择。
• 如果难度只存在于 RunSavedData 的当前 RunState，结束跑局事件中是否还能稳定取到它需要用最小测试确认；必要时可以在 mod 侧保留一个轻量运行时快照供 contribution 构造使用。
• 若目标是“自动把所有 RunSavedData 槽位都发送出去”，这涉及隐私/授权边界，不建议默认开启；更合适的是显式 contribution + 用户授权。

---

English translation

Summary

This looks like a telemetry API usage question rather than a confirmed defect: RunSavedData can persist in-run data into the run-save extension, but the automatically sent run_history telemetry does not merge a saved-data slot into the vanilla run-history JSON just because the slot exists. The recommended maintainer response is to document the supported bridge: register the difficulty value as a RunHistory telemetry contribution and subscribe to it from the relevant TelemetryRequest.RunHistory(...); if the goal is to mutate the raw run_history field, clarify that the current API does not do that automatically.

Key Takeaways

Item	Takeaway
Brief description	The reporter can already receive automatically sent run records, but wants a difficulty option saved through “in-run data” to be sent with those records too.
Likely cause	High confidence: automatic run-history capture serializes the vanilla SerializableRun and attaches extra data through the telemetry contribution mechanism; RunSavedData is a save/sync extension, not an automatic telemetry field promotion path.
Possible solution	Implement an ITelemetryContributionProvider for the difficulty data with Category = TelemetryDataCategory.RunHistory, register it through RitsuLibFramework.RegisterTelemetryContributionProvider(...), and subscribe to that contribution in TelemetryRequest.RunHistory(...) via ContributionSubscriptions.
Recommended handling	Keep the issue as type/question and answer with usage guidance; optionally add docs or a sample showing how to bridge RunSavedData into a RunHistory telemetry contribution.

Expand detailed analysis, evidence, and verification

Problem Description

Expected behavior

• After a difficulty option is written into the current run through “in-run data”, it should also appear in the automatically sent run-history telemetry event.

Actual behavior

• The automatically sent run record can be received, but the difficulty option is not included automatically.

Reproduction steps

• Use the data telemetry feature and successfully receive run records.
• Add a difficulty option to the run through “in-run data”.
• Inspect the automatically sent run record and observe that the difficulty data is absent.

Logs, Attachments, and Source Excerpts

• Original:

  尝试使用数据遥测功能，并成功接收到了对局记录。
  但是有个难度选项，已经通过“局内数据”，加到了对局中……

  Key point: this is a usage question about including existing in-run data in telemetry; no error log or exception was provided.

Detailed Analysis Basis

• README.zh.md:87-README.zh.md:94 lists RitsuLibFramework.GetRunSavedDataStore(modId) as the entry point for “storing in-run data”, so the referenced “局内数据” primarily maps to run saved data.
• src/RunData/RunSavedDataStore.cs:47-src/RunData/RunSavedDataStore.cs:86 shows that Register / RegisterPerPlayer only register run saved data slots and pass them to RunSavedDataRegistry.
• src/RunData/Patches/RunSavedDataPatches.cs:367-src/RunData/Patches/RunSavedDataPatches.cs:384 exports RunSavedData when saving a run, and src/RunData/RunSavedDataDocument.cs:8-src/RunData/RunSavedDataDocument.cs:11 shows the extension root as _ritsulib.run_saved_data. This proves it enters the save/sync extension, but does not prove automatic inclusion in the telemetry run-history payload.
• Automatic run-history capture is implemented in src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:185-src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:244: when a run ends, it serializes evt.Run as SerializableRun and calls CaptureVanillaRunHistory(..., applicantPayload: null, properties) for each authorized applicant with a registered run_history request.
• src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:155-src/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs:182 builds a payload containing run_history plus optional mod_payload; the automatic path passes null, so the reporter’s difficulty field is not naturally inserted there.
• The contribution mechanism is assembled in src/Telemetry/Core/TelemetryEnvelopeFactory.cs:143-src/Telemetry/Core/TelemetryEnvelopeFactory.cs:161, which attaches private_contributions / shared_contributions resolved by TelemetryRegistry.ResolvePrivateContributions / ResolveSharedContributions.
• src/Telemetry/Core/TelemetryRequest.cs:36-src/Telemetry/Core/TelemetryRequest.cs:42 and src/Telemetry/Core/TelemetryRequest.cs:125-src/Telemetry/Core/TelemetryRequest.cs:137 show that RunHistory requests support ContributionSubscriptions; this is the existing entry point for attaching extra mod data to run-history telemetry.
• src/Telemetry/Contributions/ITelemetryContributionProvider.cs:23-src/Telemetry/Contributions/ITelemetryContributionProvider.cs:42 defines a contribution’s category, visibility, and Build(...); src/RitsuLibFramework.cs:1148-src/RitsuLibFramework.cs:1155 exposes the registration entry point.

A minimal maintainer-facing direction could be:

RitsuLibFramework.RegisterTelemetryContributionProvider(new DifficultyContributionProvider());

RitsuLibFramework.RegisterTelemetryApplicant(new TelemetryApplicant
{
    ApplicantId = "your.applicant",
    OwnerModId = "YourMod",
    DisplayName = "Your telemetry",
    Adapter = yourAdapter,
    Requests =
    [
        TelemetryRequest.RunHistory(
            "Send run history with difficulty context.",
            sharedContributionSubscriptions: ["difficulty"]),
    ],
});

DifficultyContributionProvider should return Category = TelemetryDataCategory.RunHistory. If the data is only sent to the same mod’s applicant, use Visibility = TelemetryContributionVisibility.PrivateToApplicant; if other applicants may receive it, use SharedToAuthorizedSubscribers, subscribe with a name such as YourMod/difficulty, and require user consent for that shared source. Build(...) can read the difficulty from the mod’s own runtime state or a locatable run-saved-data value and return a small JsonObject.

Feedback Quality Reminder

Dimension	Status
Reproduction steps	Ambiguous: the scenario is described, but there is no minimal code snippet or registration order.
Expected/actual	Provided: the expected difficulty field is absent from the automatically sent run record.
Environment and versions	Missing: no RitsuLib version, game branch/version, or single-player/multiplayer context.
Logs/attachments	Missing: logs are not required for this usage question, but telemetry logs would be needed if this turns out to be a drop/consent issue.
Title and background	Provided: the title and body are specific enough to identify a data telemetry + in-run data bridging question.

Detailed Verification Suggestions

• Use a test mod to register a RunSavedData slot and write difficulty during a run.
• In the same mod, register an ITelemetryContributionProvider with category RunHistory and have Build(...) return that difficulty value.
• Register TelemetryRequest.RunHistory(...), subscribe to the contribution, grant user consent, and end a run.
• Inspect the sent telemetry envelope: the vanilla run record should remain under applicant_payload.run_history, while the difficulty should appear under private_contributions or shared_contributions.
• If the desired outcome is to place difficulty directly inside the run_history JSON, decide separately whether a new API is needed or whether docs should state that mutating the vanilla payload is unsupported/not recommended.

Risks and Open Questions

• It is not yet clear whether the reporter sends data through their own applicant or wants to share one mod’s difficulty data with another applicant; that determines whether PrivateToApplicant or SharedToAuthorizedSubscribers is appropriate.
• If the difficulty only exists in the RunSavedData attached to the current RunState, maintainers should verify with a minimal test that it can still be read reliably during the run-ended event; if needed, the mod can keep a lightweight runtime snapshot for contribution construction.
• Automatically sending every RunSavedData slot would cross privacy/consent boundaries and should not be enabled by default; explicit contribution registration plus user consent is the safer shape.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#74 · 退出码 0 · 进程 315.60s
• gpt-5.5(high) · API 314565ms · 34 轮 · ↓86552 ↑7874 · 缓存读346624 写0 · $0.8029
• MCP available: management tools exposed to Claude.

[BAKAOLC]

https://github.com/LuoTianOrange/STS2_WineFox/blob/main/Telemetry/WineFoxTelemetryBootstrap.cs

这是一个现成的示例，它会添加一些自身的额外数据与其一起发送
它本身比较轻量所以应该很容易理解，如果还有其他问题的话可以继续询问

只能说我确实缺少文档这些说明，因为我个人并不太会除了正常交流以外的文本工作

[iouter]

大概明白了，需要测试一下

[iouter]

ok, it works