安装

环境要求

• Python 3.11+
• 类 POSIX shell（macOS / Linux；Windows 走 WSL 也可以）
• LLM API key 可选——安装、跑测试、干跑研究都不需要 key （见无 token 模式）。

安装步骤

建议使用独立环境（conda 或 venv）：

condavenv

conda create -n socioverse python=3.11 -y
conda activate socioverse

git clone https://github.com/REPLACE-ME/socioverse   # TODO(launch)：最终仓库地址
cd socioverse
pip install -e .

git clone https://github.com/REPLACE-ME/socioverse   # TODO(launch)：最终仓库地址
cd socioverse
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .

验证安装：

pytest tests -q

有些测试会跳过——这是正常的

依赖大型外部数据集的测试在数据缺失时会自动跳过。 「有跳过、零失败」就是一次健康的安装。

可选功能通过 extras 安装：

pip install -e ".[dev]"    # + pytest
pip install -e ".[viz]"    # + matplotlib（报告绘图）
# 个别内置研究可能声明自己的 extras——见对应研究的 README

配置 LLM（可选）

SocioVerse 从环境变量读取 LLM 配置：

变量	含义
SV_LLM_API_KEY	运行时优先查找的 API key
OPENAI_API_KEY	备选 key（fallback）
SV_LLM_BASE_URL	可选的端点覆写（任何 OpenAI 兼容网关）
SV_LLM_MODEL	可选的模型选择

仓库自带模板——复制一份并填入你的 key：

cp .env.example .env      # .env 已被 gitignore；永远不要提交 key

永远不要硬编码密钥

key 只应放在 gitignore 的 .env（或 shell 环境变量）里， 绝不出现在代码或研究产物中。

配置外部服务（可选）

.env 是服务端点与 key 的唯一来源。Python 客户端直接读它，而会话内的 MCP 注册文件是由它生成的——不要手写：

python scripts/gen_mcp_json.py     # 从 .env 渲染出被 gitignore 的 .mcp.json

每次改完 .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 不是可选项

不配置时一切都会优雅降级：事件客户端退到本地缓存、再退到普通网络检索；人群则退到 「先锚定再合成」或你自备的 persona 文件。健康探针、成本与降级细则见 外部能力。

无 token 模式

除真实的 LLM 决策调用外，流水线的一切——安装、测试、环境/人群构建、 以及决策模型为规则式的研究——都无需 key。对 LLM 驱动的研究， 管线检查、一致性测试和 CI 用确定性客户端替身即可—— 见 LLM 接入与干跑。

下一步

前往快速开始，跑通你的第一个研究。