Glossary

One name per concept, used the same way in the docs, in the code, and in the dashboard. If a page and this table disagree, this table is right.

The vocabulary

Term (EN)	中文	One-line definition	Details
B = f(P, E)	行为 = f(人群, 环境)	The identity the runtime implements: a step's behaviour B_t is the behaviour function applied to the fixed population and the current environment, with E_{t+1} = g(E_t, B_t) closing the loop.	Overview
population (P)	人群	The pool of personas built once per run by PopulationProvider.build(seed), each carrying a persistent agent_id that is never reused — the longitudinal key.	Anatomy of a Study
environment (E)	环境	The world the population acts in, declared as tagged EnvironmentLayers on two axes (modality ∈ {physical, information} × scope ∈ {macro, local}) plus the exogenous entries scheduled on them.	Overview
behaviour function (f)	行为函数	The mapping from a persona and its Observation to one typed Action, implemented by a study's DecisionModel.decide_batch — LLM, rule, or hybrid (Action.source ∈ {llm, rule, fallback, replay}).	Architecture
study state (σ)	研究状态	Everything a study is — σ = (P, E_{0:T}, f, Θ) — which on disk is the set of artifacts in the study workspace; an edit rewrites it as σ_{k+1} = h(a_k, σ_k).	Versions & the research loop
step	步	One iteration of the five phases exogenous update → observe → decide → apply → record; step 0 is materialization only (P and E_0, no decisions), and a run has n_steps of them (default 5).	One step, five phases
panel row	面板行	One TrajectoryRecord per agent per step — (agent_id, step) is the primary key — landing in DuckDB as panel(agent_id, step, state, action_kind, action_payload).	One step, five phases
intervention	干预	One entry in the environment bundle that changes E from outside — either a ScheduledEvent or a Broadcast — applied in phase 1 of its at_step, before anyone observes, so the whole step faces one state.	Intervention & branching
scheduled event	定时事件	The numeric intervention: ScheduledEvent(at_step, target_layer, op ∈ {set, add, multiply, add_pct, replace_source}, selector, property_name, value, note), validated against the declared layer names.	Intervention & branching
broadcast	广播	The information intervention: Broadcast(message_id, content, channel="news", at_step, ttl=1, audience) — visible for ttl steps, delivered to macro_information when audience == "all", otherwise to the matching agents' local_information.	Intervention & branching
branch	分支	A version node whose only difference from its parent is environment entries at at_step ≥ fork_step, and which inherits the parent's earlier steps by replay (kind: "branch" in versions.json).	Intervention & branching
fork step	分叉步	fork_step — the first step a branch computes for itself (warm_start.resume_from + 1, must be ≥ 1); before it the branch is its parent, from it on it is the counterfactual.	Intervention & branching
replay	重放	Re-running the parent version's stored actions for the inherited steps — phases 1, 4 and 5 only, no model call and no spend — so the inherited history reproduces the parent exactly (Action.source == "replay").	Intervention & branching
version	版本	A version node that starts from a cold run at step 0 (kind: "version") — what any edit other than a late environment-only one produces: a change to P, to f, to run settings Θ, or to E before the fork step.	Versions & the research loop
fork	派生	Study-level reuse only: fork_study() copies a matched or reference: true study into a new study_id with its own version history and leaves the source read-only.	Versions & the research loop
study workspace	研究工作区	studies/<study_id>/ — the directory holding every artifact of one study, and therefore the study's complete state.	Anatomy of a Study
artifact	工件	The one validated document a stage writes (study.yaml, environment.json, population.json + roster.jsonl, simulation.json, study.duckdb, report.md), written and re-read through write_artifact / validate_handoff.	Anatomy of a Study
stage / skill	阶段 / 技能	One pipeline step: a /sv-* skill that reads upstream artifacts, writes exactly one artifact of its own, and pauses at a gate — sv-init, sv-build-model, sv-build-environment, sv-build-population, sv-run, sv-report, plus /sv-iterate for changing a study that already exists (/sv-lit and /sv-paper sit under the report stage).	Architecture
grounding	真实世界锚定	grounding/grounding.json — the merge-friendly sidecar recording each real-world fact the study rests on, with basis ∈ {sourced, proxy, assumed} and source.via ∈ {event_service, web_search, provider, user}.	Grounding & Provenance
resource manifest	资源清单	resources.json — the ResourceManifest declaring, by name, the mcp_servers / datasets / tools a study actually used (endpoints and keys stay out of it).	External Capabilities
review gate	待复核	The rule that marks a stage carried over from the parent version as review when it sits at or after the version's resume_from_stage and has no narrative written in this version — it holds the pipeline pointer until the stage is re-authored or explicitly verified.	Versions & the research loop
Population service	人群池服务	The build-time MCP (user_pool_survey_mcp) that routes an attribute request across the registered persona pools, reports coverage, and samples P to target distributions.	External Capabilities
Event service	事件信号服务	The build-time service (event_tool) returning structured macro / news / market data — list_sources, get_data, get_source_detail, search_web — which the runtime loop never calls.	External Capabilities

Branch vs. version vs. fork

The three words are not interchangeable. The difference is what may change and what is re-run.

	what may change	earlier steps	cost of a run	written by
branch 分支	environment entries at at_step ≥ fork_step only	inherited from the parent by replay	only fork_step..n_steps	create_branch(study_dir, note, fork_step=…)
version 版本	anything in σ — P, f, Θ, or E before the fork step	none, the run is cold	every step	create_version(study_dir, note, …)
fork 派生	a whole new study, source untouched	not applicable — a new study	every step of the new study	fork_study(studies_root, src_id, new_id)

A branch that breaks the rule becomes a version

check_branch_invariant() re-checks the branch contract before the run: population bundle and roster, the study's *.py code, the fixed keys of simulation.json (seed, decision_ref, collector_ref, interaction_rounds, store_ref, engine_args, …) and every environment entry at at_step < fork_step must match the parent. n_steps may differ, and new layers may be added. A violation is downgraded, not raised: the entry becomes kind: "version", warm_start is cleared, the run goes cold, and downgraded_from_branch records why.

Wording we retired

Do not write	Write instead	Why
warm start	replay	The mechanism is user-facing as "the branch inherits its parent's steps"; the class name WarmStartSpec is kept only so artifacts written earlier still load.
policy shock, event injection	intervention	An intervention is exactly a ScheduledEvent or a Broadcast in the environment bundle — nothing else.
sub-experiment, variant, "fork" for a version node	branch or version	fork is reserved for the study level.