安装¶
SocioVerse2 以 Apache-2.0 协议开源：
github.com/sii-research/SocioVerse2
（发布页，当前版本
v0.2.0，见版本发布）。核心库也以 socioverse2 之名发布在
PyPI 上。
环境要求¶
- Python 3.11+
- 类 POSIX shell（macOS / Linux；Windows 走 WSL 也可以）
- LLM API key 可选——安装、跑测试、离线跑完一个完整研究都不需要 key （见无 token 模式）。
- 使用
/sv-*工作流 skill 时，还需要一个有自己登录凭据的编程智能体。 模拟用的 LLM key 驱动不了它，见工作流 skill 由什么驱动。
从源码安装（推荐）¶
clone 仓库：运行时之外，工作流 skill、本地研究仪表盘和参考研究都在仓库里。 建议使用独立环境（conda 或 venv）：
验证安装（不需要 key）：
有些测试会跳过——这是正常的
需要配套仓库、可选 extra（chicago、workbench）
或真实 LLM 的测试会检测到缺失并自动跳过。「有跳过、零失败」就是一次健康的安装。
或者：从 PyPI 安装核心库¶
这只安装核心库（socioverse：schema、接口、引擎、DuckDB 存储、校验）。
/sv-* 工作流 skill、仪表盘、参考研究和演示脚本都不在这个包里，需要按上面的方式
clone 仓库获得。如果你用自己的 Python 代码驱动研究
（快速开始的路径 2），用 PyPI 包即可。
不用 API key 跑一个研究¶
Running opinion_diffusion_demo (a local copy of opinion_diffusion): 12 agents, 4 steps, llm_kind=scripted
step mean_opinion opinion_std frac_above_0_5
0 0.500 0.288 0.50
1 0.500 0.282 0.50
2 0.618 0.212 0.67
3 0.707 0.160 0.83
4 0.737 0.142 1.00
该脚本把随仓库提供的参考研究 studies/opinion_diffusion 派生为一个本地研究
studies/opinion_diffusion_demo/（与你创建的所有研究一样被 gitignore），校验复制过来的
产物后在其中运行。决策模型以 llm_kind: "scripted"（确定性规则）运行，因此免费且可复现。
运行结果写入演示研究的 trajectory/，渲染出的报告在它的 reports/（默认英文；
加 --report-lang zh 渲染成中文）。脚本从不写入参考研究，每次运行都会重新生成演示研究。
每次运行都是一个 DuckDB 库，可以直接用 SQL 查询：
import duckdb
con = duckdb.connect("studies/opinion_diffusion_demo/trajectory/study.duckdb", read_only=True)
con.sql("SELECT step, state->>'opinion' AS opinion FROM panel WHERE agent_id = 'od-000' ORDER BY step").show()
con.sql("SELECT * FROM metrics ORDER BY step").show()
con.sql("SELECT step, note FROM events ORDER BY step").show()
运行库不进仓库
trajectory/ 目录和 *.duckdb 文件都被 gitignore，所以随仓库提供的参考研究带着
产物和渲染好的报告，但不带运行库。想用 SQL 查询某个研究，先把它跑一遍
（上面的演示对 opinion_diffusion 做的就是这件事）。
打开研究仪表盘¶
演示会作为一个独立研究出现在参考研究 opinion_diffusion 旁边。仪表盘是 studies/
的本地只读视图；/sv-* skill 在研究开始时会自动启动它。见运行面板。
配置 LLM（可选）¶
用真实 LLM 跑同一个研究：
pip install -e ".[llm]"
cp .env.example .env # 设置 SV_LLM_API_KEY；.env 已被 gitignore，永远不要提交 key
python scripts/demo_offline.py --llm openai
脚本会先探测一次端点，然后发起 48 次简短调用（12 个 agent × 4 步），并用这次运行替换
演示研究原有的运行。无法解析的回复会回退到规则，并在输出中计数。随仓库提供的那次运行
使用中文提示词；加 --prompt-lang en 改用英文提示词。
SocioVerse 从环境变量或 .env 读取 LLM 配置（依次查找 $SV_HOME/.env、./.env、
仓库根目录；进程环境变量优先）：
| 变量 | 含义 |
|---|---|
SV_LLM_API_KEY |
模拟中 agent 的 LLM 调用所用的 key |
SV_LLM_BASE_URL |
可选；任何 OpenAI 兼容端点（未设置时为 OpenAI 官方 API） |
SV_LLM_MODEL |
可选；由 scripts/demo_offline.py、芝加哥适配器以及 simulation.json 未指定模型的研究读取 |
OPENAI_API_KEY |
SV_LLM_API_KEY 为空时的备选。abm_* 研究的 LLM 模式直接读取 OPENAI_API_KEY 和 OPENAI_BASE_URL |
研究的模型固定在哪里
随仓库提供的从零构建研究在 simulation.json 中固定模型（decision_args.model），
consumer_confidence 固定在 environment.json（prediction.model），ABM 研究则
固定在 SocioVerse-ABM 中该任务的 config.yaml 里。若所用端点不提供该模型，就在
这些位置修改；已经运行过的研究请通过 /sv-iterate 修改。
永远不要硬编码密钥
key 只应放在 gitignore 的 .env（或 shell 环境变量）里，
绝不出现在代码或研究产物中。
工作流 skill 由什么驱动¶
一次 /sv-* 研究用到两套彼此独立的 LLM 连接，需要分别配置：
- 运行 skill 的编程智能体。Claude Code 需要它
自己的 Claude 登录（Claude 订阅）或
ANTHROPIC_API_KEY。.env里的SV_LLM_*key 不能驱动 Claude Code，它只用于模拟中的 agent。 Codex CLI 是实验性的替代方案：它读取仓库随附的AGENTS.md和.codex/skills/（两者都由 Claude Code 一侧生成），但 Codex 路径尚未做过 完整的端到端测试。在 Codex 中，在提示里点名要运行的阶段（例如Run sv-init: "How does a rumor spread ..."）。 - 模拟本身的 LLM，负责模拟 agent 的决策：任何 OpenAI 兼容的服务商都可以，通过上面的
SV_LLM_*变量配置。没有它，从零构建的研究仍能在 scripted 模式下完整跑通；/sv-run在花费真实 LLM 调用之前会先询问。
/sv-lit（文献调研）还需要一个 extra：pip install -e ".[lit]"。
会话 hooks
.claude/settings.json 和 .codex/hooks.json 注册了会话 hooks，运行
python3 dashboard/hooks/sv_emit.py。它们只切换仪表盘上「等待你操作」的提示条；
仪表盘本身由 skill 启动。在启动智能体的环境中设置 SV_DASH_DISABLE=1 即可同时关闭两者。
Extras¶
| extra | 增加 |
|---|---|
llm |
用于真实 LLM 运行的 OpenAI 兼容客户端，支持 SOCKS 代理 |
viz |
用于报告图表的 matplotlib |
workbench |
llm + viz，外加 textblob（hisim_roe 的情感打分器）和 openpyxl（germany_auto_market 的工作簿） |
lit |
/sv-lit 背后的检索引擎 |
abm |
11 个 abm_* 研究所需的 numpy 和 networkx |
chicago |
chicago_schelling 的地理与 Mesa 依赖，并包含 abm 的全部内容 |
dev |
pytest、build、twine |
all |
以上全部 |
配套仓库¶
部分参考研究包装了位于独立仓库中的项目。把它 clone 到 SocioVerse2 旁边即可被 自动发现，相应的测试也不再跳过。
workspace/
├── SocioVerse2/
├── SocioVerse-ABM/ # 11 个 abm_* 研究与 chicago_schelling
└── ConsumerSim-Consumer-Confidence-Forecast/ # consumer_confidence
SocioVerse-ABM 包含 11 个经典 agent-based 模型（每个都有规则行为函数和 LLM 行为函数），以及芝加哥隔离模型及其普查数据：
cd .. # 包含 SocioVerse2 的目录
git clone https://github.com/Lishi905/SocioVerse-ABM.git
cd SocioVerse2
pip install -e ".[dev,chicago,workbench]"
pytest -q # ABM 与芝加哥测试现在会运行
配套仓库的目录名必须恰好是 SocioVerse-ABM。
ConsumerSim
是 consumer_confidence 包装的预测管线；HiSim 为可选
（hisim_roe 不依赖它也能运行）。其他目录布局可在 shell 或 .env 中设置 SV_ABM_ROOT、
SV_CHICAGO_LEGACY、SV_CONSUMERSIM_ROOT 或 SV_HISIM_ROOT。
配置外部服务（可选）¶
.env 是服务端点与 key 的唯一来源。Python 客户端直接读它，而会话内的 MCP
注册文件是由它生成的——不要手写：
每次改完 .env 都要重跑一次。目前有两个可选能力走这条路径；只有设置了对应的
*_URL 变量，才会生成它的条目：
| 能力 | 变量 | 说明 |
|---|---|---|
| 事件服务——给 E 的真实宏观 / 新闻背景 | SV_EVENT_API_URL、SV_EVENT_API_KEY，可选 SV_EVENT_LOCAL_CACHE |
URL 是含路径的完整 MCP 端点（例如 http://host:9997/event_mcp），不是裸主机名；key 以 Authorization: Bearer 发送 |
| user pool 问卷 MCP——给 P 的真实 X / 小红书 persona | SV_USER_POOL_MCP_URL、SV_USER_POOL_MCP_KEY |
该服务要求鉴权，所以这里的 key 不是可选项 |
两项服务由 SocioVerse 团队托管，不属于仓库本身；如需访问，请发邮件至 contact@socioverse.fudan-disc.com。在线工作台已配置好这两项服务。
不配置时一切都会优雅降级：事件客户端退到本地缓存、再退到普通网络检索；人群则退到 「先锚定再合成」或你自备的 persona 文件。健康探针、成本与降级细则见 外部能力。
无 token 模式¶
除真实的 LLM 决策调用外，流水线的一切——安装、测试、环境/人群构建、
以及决策模型为规则式的研究——都无需 key。从零构建的研究在 simulation.json 的
decision_args 里设 llm_kind: "scripted" 即可关掉 LLM，scripts/demo_offline.py
就是这样跑的；chicago_schelling 则用它自带的 DeterministicLLMClient 干跑。
见 LLM 接入与干跑。
下一步¶
前往快速开始，跑通你的第一个研究。