[RFC] 面向学习分析消费者的学习事件导出契约：以 Plot Ark 为例

[Schlaflied]

[RFC] 面向学习分析消费者的学习事件导出契约：以 Plot Ark 为例

背景

延续 #367 和 #320 的讨论，我想先整理 Plot Ark 当前消费的学习事件、这些事件支持的分析问题，以及 OpenMAIC 未来如果提供标准学习事件导出，双方可能采用的最小互操作边界。

OpenMAIC 和 Plot Ark 处于学习流程的不同环节：

• OpenMAIC 负责课程内容、课堂交互、测验和 PBL 等学习体验；
• Plot Ark 尝试消费学习事件，识别课程中摩擦较集中的位置，由教师审核课程修改建议，并在后续教学周期中比较修改前后的结果。

这里的目标不是要求 OpenMAIC 适配 Plot Ark 的内部表结构，也不是现在就确定一个完整 xAPI schema，而是先回答三个问题：

1. 哪些 OpenMAIC runtime facts 值得作为学习事件导出？
2. 哪些结论应由分析消费者推导，而不应由课堂系统直接声明？
3. 如何复用 OpenMAIC 现有的 runtime records 和 learner-state model，避免再造一套平行事件系统？

当前状态与限制

Plot Ark 当前包含一个实验性的 xAPI 风格 mini-LRS。它接收 statement JSON，并主要读取：

字段	当前用途
actor	将同一学习者的活动关联起来
verb	区分访问、尝试、完成、通过、失败等行为
object	关联课程、模块、阅读材料或测验
context.extensions.course_id	关联课程
context.extensions.curriculum_topic	保存课程主题
result.response	保存主动提交的文字反馈或求助内容

当前实现仍有明显限制：

• 只保存了 statement 的一部分字段，没有完整保留原始事件；
• verb 会被映射为内部使用的短名称；
• score、attempt/registration、statement ID、authority 等尚未形成稳定契约；
• 部分现有数据由 mock generator 产生，不能代表已经验证的生产集成；
• struggled 等词目前也被用作内部分析信号，但其语义还需要进一步收紧。

因此，下面内容是用于讨论的候选契约，而不是已经稳定的 Plot Ark API。

与 OpenMAIC 现有 runtime model 的关系

从当前仓库看，OpenMAIC 已经拥有比普通事件 webhook 更丰富的内部状态，包括：

• learner-scoped runtime sessions；
• append-only runtime records；
• quiz attempts；
• chat 与 playback facts；
• PBL submissions 和 evaluations；
• engagement events；
• proficiency assessment 与状态变化。

因此，一个可能更合理的方向不是让 OpenMAIC 在业务逻辑中直接生成另一套 xAPI 数据，而是：

OpenMAIC runtime records
        ↓ 选择可对外解释的学习事实
learning-event projection / adapter
        ↓
xAPI、webhook、JSONL 或其他 consumer format

这样 OpenMAIC 的内部事件模型仍然是 source of truth，xAPI 只是一个可选的互操作投影。

与身份工作的关系

有意义的学习事件需要一个跨会话稳定的学习者标识，因此本讨论依赖 #1658 和 #23 中的身份与服务端持久化工作。

建议导出事件中的学习者身份：

• 使用稳定但不直接暴露个人信息的 learner key；
• 不强制要求姓名或邮箱；
• 由 OpenMAIC 的 server-controlled principal 派生；
• 允许部署方在自己的授权边界内映射班级或课程成员；
• 不把 teacher/student 账户系统硬编码进 OpenMAIC 核心。

对多数课程级分析而言，一个稳定的匿名标识已经足够。姓名、邮箱和组织信息是否导出，应由部署方根据实际授权、告知和隐私要求决定。

候选的第一阶段事件集

为了控制范围，第一阶段可以只覆盖已经存在明确教师报告需求的事件。

experienced

学习者打开或访问课程内容。

它只能说明内容被访问，不能直接解释为已经阅读、理解或掌握。

attempted

学习者开始一次练习、测验或可重复尝试的活动。

如果同一活动允许多次尝试，需要稳定的 attempt ID 或 context.registration 区分每次尝试。

answered

学习者提交一道题的答案。候选字段包括：

• 稳定的 assessment/question ID；
• attempt ID；
• 提交时间；
• 可选的规范化 response；
• 已完成评分时的 score 和 success。

原始答案可能含有敏感信息，不一定适合默认导出。部署方应能选择只导出得分和状态。

completed

学习者完成一个模块、测验或具有明确完成条件的活动。

completed 只表示满足完成条件，不自动等同于掌握或通过。

passed / failed

仅在活动存在明确通过标准，并且系统已经完成判定时使用。建议同时提供：

• result.score.raw
• result.score.min
• result.score.max
• result.score.scaled
• result.success

requested-help（候选扩展）

仅用于记录学习者主动执行的求助动作，例如点击“需要帮助”或提交求助内容。它不同于系统推断出的“学习者遇到了困难”。

原始事实与分析推断的边界

建议 OpenMAIC 导出可观察或可验证的事实，例如：

• 打开内容；
• 开始尝试；
• 提交答案；
• 获得分数；
• 完成活动；
• 达到或未达到明确的通过标准；
• 主动请求帮助。

以下内容更适合由 Plot Ark 等分析消费者根据多个事件推导，不建议作为学习者的原始事实直接输出：

• struggled
• at-risk
• disengaged
• mastered
• 对动机、能力或人格的判断

例如，一次低分不能单独证明学习者没有理解；多次打开同一模块也可能是复习，而不一定代表困难。

分析系统可以产生课程摩擦或风险信号，但应保留证据来源、推断规则、不确定性和人工复核入口。

Agent 如何消费这些数据：尚未定型的问题

Plot Ark 当前还没有一个稳定的“原始事件直接进入 Agent”契约。我倾向于避免把大量原始 statements 直接放入模型上下文，而采用分层处理：

原始学习事件
  → 确定性校验、去重与聚合
  → 带来源和覆盖率的课程级 evidence summary
  → Agent 解释并提出可审核的课程修改建议
  → 教师接受、拒绝或修改

在这个模型中：

• 确定性代码负责计数、比率、时间窗口、跨版本对齐和数据质量检查；
• Agent 不负责从原始日志中“猜”统计规律；
• Agent 只在有证据引用的结构化上下文上提出解释与建议；
• 最终课程修改仍由人审核。

这一中间 evidence schema 仍是 Plot Ark 需要继续设计和验证的部分，也希望听取 OpenMAIC 社区对事件粒度和稳定对象标识的意见。

示例：提交测验答案

以下只是候选 xAPI 投影，用于讨论字段语义：

{
  "id": "018f-example-statement-id",
  "actor": {
    "account": {
      "homePage": "https://openmaic.example",
      "name": "opaque-learner-key"
    }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/answered",
    "display": {
      "en-US": "answered",
      "zh-CN": "提交了答案"
    }
  },
  "object": {
    "id": "https://openmaic.example/courses/course-123/assessments/quiz-2/questions/5",
    "definition": {
      "name": {
        "zh-CN": "测验 2，第 5 题"
      },
      "type": "http://adlnet.gov/expapi/activities/cmi.interaction"
    }
  },
  "result": {
    "score": {
      "raw": 1,
      "min": 0,
      "max": 1,
      "scaled": 1
    },
    "success": true,
    "completion": true
  },
  "context": {
    "registration": "018f-example-attempt-id",
    "extensions": {
      "https://openmaic.example/xapi/extensions/course-id": "course-123",
      "https://openmaic.example/xapi/extensions/module-id": "module-4"
    }
  },
  "timestamp": "2026-09-23T14:30:00Z"
}

openmaic.example 在这里仅为占位命名空间，并非建议的正式 URI。

对象标识与课程版本

为了支持后续分析，至少需要区分：

• course/stage；
• course version；
• module/scene；
• assessment；
• question/interaction；
• attempt/registration。

Plot Ark 尤其关心课程修改前后的比较。因此，希望在保持逻辑课程身份稳定的同时，能够识别内容版本，进而回答：

某项课程修改之后，下一批学习者在相同模块或学习目标上的结果是否发生变化？

这部分不一定需要由 OpenMAIC 直接完成分析，但事件中需要有足够稳定的标识供下游消费者对齐。

可能的传输方式

事件结构和传输方式可以分开决定：

1. 可配置 webhook；
2. 批量 JSON/JSONL 导出；
3. 标准 xAPI LRS endpoint；
4. OpenMAIC runtime store 上的可插拔 event sink/adapter。

无论采用哪种方式，建议考虑：

• 唯一事件 ID；
• 幂等重试；
• schema/version；
• 安全重放；
• 可配置的事件与身份字段范围；
• 服务端凭据与授权边界。

暂不包含的范围

本讨论暂不要求：

• OpenMAIC 内置教师、学生或管理员账户系统；
• OpenMAIC 运行 Plot Ark 的分析逻辑；
• OpenMAIC 输出 at-risk 或 struggled 等推断标签；
• 立即实现完整 LRS；
• 将 Agent 内部状态全部转换为 xAPI；
• 现在就承诺双向课程同步。

Agent 状态持久化与学习事件导出有关联，但不是同一个接口问题。

希望讨论的问题

1. OpenMAIC 当前的 runtime record 中，哪些已经适合作为稳定的对外学习事实？
2. 是否更适合在现有 RuntimeStore 上增加 projection/adapter，而不是在业务代码中直接生成 xAPI？
3. 第一阶段应只覆盖 quiz result，还是同时覆盖内容访问、模块完成与 PBL 活动？
4. stage、scene、assessment 和 question 是否已有适合长期导出的稳定 ID？
5. learner key 在导出边界上应如何匿名化与授权？
6. 对题目答案，应默认导出原始 response，还是只导出得分和结果？
7. OpenMAIC 更倾向严格采用 xAPI 1.0.3，还是先定义内部 event projection，再提供 xAPI adapter？

如果这个方向合理，下一步可以先共同选择 2–3 个最小事件，用同一组 fixture 验证 OpenMAIC 导出端和 Plot Ark 消费端对字段与语义的理解，而不是一开始覆盖完整标准。

[wyuc]

Thanks @Schlaflied for writing this up. Separating raw facts from derived signals, and listing the open questions instead of fixing a schema up front, is the right way to start.

For timing: meaningful learning events need a stable learner identity, and the owner/identity seam that provides it is tracked in #1658 and is landing in stages now. Once that is in place, we'll come back to this RFC with concrete feedback on the event boundary and statement design, and link it from #320 and #367 so the related requests converge here.

[Schlaflied]

Thanks for the update, @wyuc. Makes sense to sequence it behind #1658 — a stable learner identity is the right thing to land first, since most of the field-boundary questions above (learner key anonymization, what's safe to default-export) depend on how that seam turns out.

Happy to wait on your side, and whenever #1658 is far enough along, I'm glad to help validate the event boundary against a small shared fixture (2-3 events, both directions) rather than trying to agree on the full contract in the abstract first.

[wyuc]

Thanks for your patience, @Schlaflied. Following up as promised: the owner/identity seam from #1658 has landed on main via #1669. Runtime and asset data are now keyed by the resolved owner, and it ships in the next release.

To be upfront about where this leaves the RFC: a learning-event export isn't on our near-term roadmap. When we do build one, it will be a generic export following an established standard such as xAPI, and our own product needs will set its scope. We won't be shaping a contract around a specific consumer. So we won't start the shared-fixture validation for now, but thank you for offering it.

We'll keep this discussion open as the reference for learning-event export. If more deployments need it, please add a 👍 or a comment describing the use case; that's what will move it up our list, and we'll revisit it then.