跳转至

快速开始

驱动 SocioVerse 有两种方式，产物与可查询的输出完全一致：

  • Agentic 方式（推荐）—— 用 Claude Code 打开仓库，让内置的 sv-* 工作流 skill 把你从研究问题带到报告， 每个阶段都停下来等你审阅。
  • 编程方式 —— 用 Python API 自己装配研究目录并运行。

路径 1 —— agentic 工作流

用 Claude Code 把 socioverse/ 作为项目打开，新开一个会话 （skill 在会话启动时被发现），然后从你的问题开始：

/sv-init "一个中等规模的线上社区里谣言如何传播？
          官方辟谣在第 3 天广播后会发生什么？"

sv-init 会先把你的问题路由到已有研究目录（catalog）上做匹配， 再在 studies/<id>/ 下搭建新研究的骨架。此后每个 skill 只写 一份经 schema 校验的产物，并暂停等你检查或修改：

阶段 skill 写出
路由与立项 /sv-init study.yaml + grounding/grounding.json
模型 （仅从零构建路径） /sv-build-model model.py
环境 E /sv-build-environment environment/environment.json
人群 P /sv-build-population population/population.json + population/roster.jsonl
运行 /sv-run trajectory/study.duckdb + metrics_history.json
报告 /sv-report reports/report.md + 图表
后续修改 /sv-iterate versions.json + versions/vN/ 快照

节奏由你控制：说「全部构建好，跑 /sv-run 之前问我」或 「整条流水线一路跑完」都可以——每份产物仍会在经过时呈现给你。

agentic 流水线：每个阶段恰好一个校验过的产物，阶段间有检查点，跑批前有花费关口

路由：复用、新建、还是包装

写任何代码之前，sv-init 先在三条路径中做选择：

  • Path A —— 复用/调整：已有研究覆盖了你的问题 → fork 出一个新 study_id，只改 fork 的产物。不写新代码。
  • Path B —— 从零构建：没有匹配 → /sv-build-model 原生实现四个核心 接口。新问题的默认路径。
  • Path C —— 包装你自己的模拟器：见 包装既有模拟器。

检查每一步产出了什么

每个阶段的输出都是 studies/<id>/ 下的普通文件：

S=studies/<your-study-id>
cat $S/study.yaml                    # StudySpec：研究问题、n_steps、指标
cat $S/environment/environment.json  # E：层 + 定时事件 + 广播
cat $S/population/population.json    # P：personas、规模、交互结构
cat $S/population/roster.jsonl       # 实例化后的 agent 在 t=0 的状态
cat $S/reports/report.md             # 渲染出的轨迹 + 干预注记

路径 2 —— 编程方式

一个研究目录就是数据（经校验的 JSON 产物），加上——对从零构建的研究—— 一个在 import 时自注册的 model.py。装配一次运行只需四次校验加载和一个调用：

import studies.your_study  # noqa: F401 —— 副作用：@register() 生效
                           # （随仓库提供的模板是 studies/opinion_diffusion）

from socioverse.engine import build_simulator
from socioverse.validation import validate_handoff
from socioverse.schemas import EnvironmentBundle, PopulationBundle, SimulationConfig

S = "studies/your_study"
env_b   = validate_handoff(f"{S}/environment/environment.json", EnvironmentBundle)
pop_b   = validate_handoff(f"{S}/population/population.json",  PopulationBundle)
sim_cfg = validate_handoff(f"{S}/simulation/simulation.json",  SimulationConfig)

sim = build_simulator(
    env_bundle=env_b, pop_bundle=pop_b, sim_config=sim_cfg,
    store_path=f"{S}/trajectory/study.duckdb",
)
history = sim.run()   # E_t → B_t → E_{t+1}；面板与指标落入 DuckDB

build_simulator 会把产物里的 *_ref 字符串在 registry 中解析， 返回就绪的 LongitudinalSimulator；run() 返回 MetricsHistory。

无 token 干跑（零 LLM 花费、确定性）见 LLM 接入与干跑。

读取结果

运行结果落在一个持久化的 DuckDB 存储里，可直接查询：

-- 单个 agent 的时间线（纵向视角）
SELECT step, state FROM panel WHERE agent_id = '…' ORDER BY step;

-- 聚合轨迹
SELECT * FROM metrics ORDER BY step;

-- 哪些干预在何时触发
SELECT step, note FROM events ORDER BY step;

duckdb studies/<your-study-id>/trajectory/study.duckdb

接下来