SimPy 是一个基于进程的离散事件仿真（process-based discrete-event simulation）框架，用于在 Python 中构建、测试和分析有界仿真模型。它适用于主动实体通过 yield 事件并竞争资源的场景，例如队列、生产系统、物流、网络、服务运营、库存以及其他事件驱动系统。SimPy 只提供事件调度器和建模原语，不负责选择科学上有效的概念模型、输入分布、预热期、运行长度、重复次数、估计量或因果解释，这些属于仿真研究方法论范畴。
【版本与安装】 最新稳定版为 SimPy 4.1.2，于 2026-05-24 发布到 PyPI，源码标签 4.1.2 指向提交 f4381649。包元数据要求 Python >=3.8，支持 CPython 3.8-3.14 及 PyPy，无运行时依赖。4.1.2 增加了对 Python 3.13/3.14 的支持并修复了现代解释器测试问题。上游与本技能均为 MIT 许可。可复现环境安装命令： uv venv --python 3.13 source .venv/bin/activate uv pip install "simpy==4.1.2" python -c "import importlib.metadata; print(importlib.metadata.version('simpy'))" 不要用最新文档构建替代版本化文档，因为它可能描述未发布的开发修订。
【建模工作流】
- 定义目的与估计量：说明决策/问题、系统边界、实体、资源、状态、输出、时间单位，以及终止事件或稳态目标。
- 先写概念模型：记录假设、分布、路由、优先级、初始条件和省略的机制。
- 实现生成器：SimPy 进程是 yield 事件的 Python 生成器，用 env.process(...) 注册生成器对象。
- 限制执行：为每次生产运行设置明确的时间、实体、事件和重复次数上限，绝不在包含无限进程的模型上调用 env.run()。
- 分离随机流：为逻辑上不同的随机源使用本地 RNG 实例，并保留种子清单。
- 有意识地插桩：在感兴趣的转换之后观察状态，在时间边界关闭时间加权区间，并测试监控不会改变事件顺序。
- 验证与确认：测试确定性边界情况、守恒恒等式、轨迹、队列规则和分析基准，并与系统或专家证据比较。
- 运行独立重复：从重复级估计构建区间，而不是单次运行内相关实体。
- 报告局限性：包括初始化、未完成实体、运行长度、种子/流、精度、敏感性和验证证据，绝不把仿真关联转化为因果主张。
【核心语义】 Environment 是单线程的，队列按仿真时间、事件优先级、严格递增的事件 ID 排序，同时间同优先级事件按调度顺序 FIFO 处理。env.now 是无单位仿真时钟；env.peek() 返回下一事件时间或无穷；env.step() 处理一个事件，空时抛出 EmptySchedule；env.active_process 返回当前执行进程；env.run() 排空队列，对循环或无限进程不安全。env.run(until=number) 与 env.run(until=event) 在边界上不可互换：数值会调度一个紧急停止事件并排除该时刻的普通事件；Event 条件在其停止回调触发时返回该事件的值。在 4.1.2 中，Environment.step() 会保留 StopSimulation 之后剩余的回调并重新调度目标，因此 env.run(until=target) 后 target.processed 可能仍为 False，直到再执行一次 step()/run()，不要用 processed 作为运行后完成的唯一测试。
Event 经历 not-triggered -> triggered/scheduled -> processed 一次；succeed(value) 或 fail(exception) 触发一次。Timeout 在创建时触发，调度为 now + delay，不能再次手动成功。env.process(generator) 创建 Process，生成器以 yield 事件的值恢复，返回则成功，未捕获异常则失败。AnyOf / a | b 和 AllOf / a & b 产生 ConditionValue：从事件对象到其值的有序类字典映射，用原始事件对象测试成员关系，不要假设标量结果。AnyOf 不会取消失败事件，放弃待处理资源请求时需显式取消。
【中断】 process.interrupt(cause) 调度紧急中断，向目标生成器抛出 simpy.Interrupt。在可能被中断的 yield 工作周围捕获它，检查 interrupt.cause，更新剩余工作，然后恢复、重新 yield 原事件或终止。中断进程会从其当前目标移除恢复回调，但不会取消该目标事件。进程不能中断自身或已终止进程。
【共享资源】 Resource 是 FIFO 信号量式使用槽；PriorityResource 按较小数值优先级先排序；PreemptiveResource 是优先级队列加可选抢占当前用户；Container 是同质数值水平，put/get 等待容量/物料；Store 是 FIFO Python 对象；FilterStore 返回满足请求谓词的第一个可用项；PriorityStore 按优先级顺序返回可比较项。使用请求上下文管理器，退出时释放已获取请求或取消仍待处理的请求，包括异常展开期间。对于手动保留的待处理 put/get/request，若中断或超时使进程放弃它，需调用 cancel()。PreemptiveResource.request(priority=..., preempt=True) 使用较小数字为较高优先级，被抢占进程收到 Interrupt，其 cause 是 Preempted 对象，cause.by 是抢占进程，cause.usage_since 是开始使用时间，cause.resource 是资源。排队优先级优先于 preempt 标志，混合抢占与非抢占请求需要显式测试。
【监控与步进】 优先在状态转换处进行显式领域观察。对于通用资源监控，包装器或子类可检查 count、queue、level、items、put_queue 和 get_queue。对于事件追踪，schedule() 和 step() 是核心钩子。队列测量对时序敏感：请求方法的前状态、调用后状态、授予回调和释放回调在同一仿真时间戳可能不同。样本平均值按事件观察加权而非时间，应计算左连续状态路径下的面积并除以经过时间。添加初始和最终样本，在分析边界关闭最后区间。env._queue、resource _env 和 monkey-patching 是实现细节，应固定 SimPy 版本、隔离插桩并在升级后回归测试。追踪每个事件会改变运行时和内存使用，需限制追踪记录。
【实时执行】 simpy.rt.RealtimeEnvironment(initial_time=0, factor=1.0, strict=True) 将一个仿真单位映射为 factor 墙钟秒。严格模式下，step()/run() 在计算落后时抛出 RuntimeError；strict=False 容忍滞后，但不恢复时序精度。先用 Environment 开发逻辑，再用宽松的平台感知容差运行单独时序测试。
【捆绑安全 CLI】 所有 CLI 使用固定内置队列模型或汇总本地工件，拒绝未知 JSON 键、URL、符号链接、非有限数字、超大输入以及无界时间/事件/实体/重复。它们从不评估配置文本、执行用户 Python、导入插件或调用网络服务。示例命令： python skills/simpy/scripts/bounded_queue_scenario.py --help python skills/simpy/scripts/replication_runner.py --help python skills/simpy/scripts/event_trace_summary.py --help python skills/simpy/scripts/validate_simulation_config.py --help python skills/simpy/scripts/bounded_queue_scenario.py python skills/simpy/scripts/replication_runner.py python skills/simpy/scripts/validate_simulation_config.py config.json 重复运行器拒绝单次重复区间，其区间量化配置模型下的蒙特卡洛不确定性，既不验证模型也不识别因果效应。
【测试】
对排序、边界时间、条件、中断、所有资源规则、守恒、事件/实体限制、种子可复现性和监控非干扰使用确定性单元测试。仅在固定种子下添加随机测试作为广泛分布检查，避免脆弱的精确样本估计。在精确固定环境中运行测试套件：
PYTHONDONTWRITEBYTECODE=1 uv run --isolated --no-project
--python 3.13 --with "simpy==4.1.2"
python -m unittest discover -s tests/simpy -v
【参考文档】 references/events.md 涵盖调度器、生命周期、运行边界、条件；references/process-interaction.md 涵盖生成器、共享事件、中断；references/resources.md 涵盖所有 Resource、Container 和 Store 变体；references/monitoring.md 涵盖时间加权、队列时序、追踪、步进；references/real-time.md 涵盖 factor、严格模式、漂移、时序测试；references/simulation-methodology.md 涵盖重复、预热、验证、置信区间；references/cli-guide.md 涵盖模式、边界、输出和安全 CLI 示例；references/sources.md 提供带日期的官方和主要方法来源。