OpenMAIC
OpenMAIC 源码分析：追踪代理、课堂工具、会话与导出器
以固定的小型课程夹具为起点，阅读请求处理、LangGraph 状态、工具注册、持久化事件和产物导出。
你将学会
- Build a source-analysis fixture
- Trace state, tools, persistence, and export seams
- Frame a contribution with reproducible evidence
开始前需要
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
先看结论
- Anchor code reading to a pinned, observable lesson fixture.
- Trace session state, tool schemas, persistence events, and exporter boundaries separately.
- Contribution-quality findings include fixtures, idempotency checks, and redacted traces.
Start from a reproducible fixture
阅读 OpenMAIC 源码时，先固定提交、材料哈希、Provider 和一个课堂产物，再从请求处理追踪到图状态、工具 schema、持久化事件和导出文件。文章区分 README 证据、运行轨迹和待验证假设，并给出可贡献的恢复、脱敏和导出回归测试方向。
The README identifies a monorepo-style stack with reusable @openmaic packages, an agent workbench, course tools, persistence, and exporters. Use those as search anchors, but confirm names and call paths in the checked-out tree; article claims should follow symbols and tests, not assumptions from the feature list.
Trace the request and state machine
Follow the UI action that creates or resumes a session into the server boundary, then locate the state object passed to the agent runtime. Record where materials, learning goals, cancellation, and resume tokens enter the graph. A useful trace table has event name, state fields read, state fields written, side effects, and retry behavior.
Next locate the tool or skill registry. For one slide, quiz, or interactive scene, identify the schema validation, model call, renderer, and artifact write. If a tool can be invoked twice after a network retry, inspect whether its write is idempotent or whether duplicate assets are possible. Keep the analysis explicit when a path is inferred from tests rather than directly observed.
Inspect persistence and export seams
The v1.0.0 notes emphasize server-backed sessions and incremental saves. Find the persistence adapter and test the boundary with a forced restart or cancelled run. Verify which events are durable, how the latest state is selected, and whether a partial artifact is marked incomplete instead of presented as final.
Exporters deserve their own pass. Trace how an internal artifact becomes editable PowerPoint or interactive HTML, where fonts and media are resolved, and how untrusted material is escaped. A renderer test that only checks a file exists misses broken links, executable HTML, and nondeterministic output; compare checksums or normalized snapshots for a fixed fixture.
Turn findings into contribution-sized work
Prefer a small contribution with a fixture: an idempotent resume test, a provider capability matrix, a redacted event logger, or an exporter regression test. Include the pinned input, expected event sequence, and failure boundary. Avoid claiming a performance improvement until the same provider, model, material, and hardware have been measured before and after.
The goal of source analysis is not to reverse-engineer undocumented behavior as fact. Separate README evidence, observed traces, and hypotheses in the issue or article, and keep secrets and copyrighted course materials out of fixtures. That discipline makes a multi-agent education platform easier to extend without turning generated lessons into an opaque black box.
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
Pin the repository and create a one-artifact public fixture.
- 2
Follow the request into agent state and record reads, writes, and retries.
- 3
Inspect one course tool, persistence adapter, and exporter with tests.
- 4
Submit a narrow regression or observability improvement with evidence.
可复制示例
fixture -> request handler -> graph state -> skill/tool schema
-> provider call -> event/save -> renderer -> exported artifact常见问题
Can README feature bullets prove an internal call path?
No. Use them as navigation hints, then confirm the path with source symbols, tests, or an instrumented fixture.
What is a safe first source contribution?
A deterministic fixture and regression test for resume, provider capability, event redaction, or exporter correctness is safer than a broad refactor.
资料来源
- OpenMAIC README (captured 2026-08-31)来源核查 2026-08-31
- OpenMAIC repository来源核查 2026-08-31