架构分层¶

SocioVerse 分为两层：你复用的 Core 运行时，和你编写的 study 层。 Core 定义契约并驱动循环；study 提供实现。新增研究永远不需要改引擎。

socioverse/                CORE 运行时 —— 复用，不要动
├── schemas/               类型化契约（StudySpec、EnvironmentBundle、PopulationBundle、
│                          SimulationConfig、Observation、Action、TrajectoryRecord……）
├── abc/                   研究要实现的接口（EnvironmentProvider、
│                          PopulationProvider、DecisionModel、MetricCollector）
│                          + Simulator / TrajectoryStore / Reporter / MessageBus
├── engine/                LongitudinalSimulator（主循环）、AgentMemory、registry、
│                          InMemoryMessageBus、build_simulator（装配）
├── env_layers/            信息轴助手（广播投递、邻居信息流）
├── io/duckdb_store.py     可查询的 panel / metrics / events / messages 存储
├── providers.py           通用 File / MCP 人群 provider
└── validation.py          validate_handoff —— 严格的阶段边界校验

studies/<id>/              STUDY 层 —— 你写（或由工作流生成）
└── model.py + 产物         四个接口实现 + study.yaml / env / pop / sim

四个接口¶

实现 socioverse/abc/ 里的四个抽象基类，一个研究就完整了：

接口	职责	关键方法
`EnvironmentProvider`	持有世界状态 E	`reset`、`advance_to(t)`（外生）、`observe_batch()`（四象限视图）、`apply(actions)`（内生）
`PopulationProvider`	构建固定人群 P	`build()` → 带确定性持久 id 的 `Persona[]` + 交互结构
`DecisionModel`	计算 B = f(P, E)	`decide_batch(observations)` → `Action[]` —— 批式、类型化
`MetricCollector`	度量每一步	`collect()` → 该步的聚合指标

其余由 Core 提供：LongitudinalSimulator 循环、轨迹存储、报告器、消息总线、agent 记忆。

运行时动线¶

build()  → Persona[]                 # P：只建一次，持久 id，此后固定
reset()                              # E_0
loop t = 1..N:
    advance_to(t)                    # 外生：定时事件 + 广播改变 E
    observe_batch() → Observation[]  # 每个 agent 的四象限视图（宏观/局部 × 物理/信息）
    decide_batch()  → Action[]       # = B，批式决策（LLM 或规则）
    apply(actions)                   # 内生反馈：E_t → E_{t+1}
    collect() → metrics              # 度量
    record()  → DuckDB               # 持久化面板行 + 指标 + 事件

这些调用之间的交接是类型化的（Persona[] → Observation[] → Action[] → metrics），所有类型都定义在 socioverse/schemas/。Schemas 是所有组件共同引用的契约层—— 不是数据「流经」的一个阶段。

Core 内置的场景钩子¶

三类常见需求已在 Core 解决，研究只需声明、无需实现：

按受众投放信息 —— Broadcast / InformationProgram （env_layers/information.py）：audience: "all" 抵达每个 agent 的宏观信息象限；选择器 dict 命中匹配 agent 的局部信息象限。
大规模 agent 交互 —— 中介化的 MessageBus 加 interaction_rounds （不是 O(N²) 的两两聊天）：发言落到总线上，邻居通过研究声明的 InteractionStructure 读取（engine/messaging.py、 env_layers/neighbor_feed.py）。
自带数据 —— ResourceManifest 加通用的 FilePopulationProvider / McpPopulationProvider （socioverse/providers.py），人群可来自文件或外部服务。

一个值得内化的命名区分¶

Core 引擎是被复用的 LongitudinalSimulator——主循环本身。
engine-seam（引擎缝合层）是研究内部的胶水，用来包装遗留模拟器（见包装既有模拟器）。 Core 永远不调用它；只有研究自己的 provider 引用它。

注册与装配¶

研究用 @register(kind, key) 装饰器（socioverse.engine.registry）发布实现，产物里按 key 引用它们（provider_ref、decision_ref、 collector_ref……）。此后装配是通用的：

build_simulator(env_bundle=…, pop_bundle=…, sim_config=…, store_path=…)

它把每个 *_ref 在 registry 中解析、实例化 provider、接好 DuckDB 存储，返回就绪的 LongitudinalSimulator。这就是全部集成面——不改引擎，也没有要学的插件系统。