v2.4.0 — 回路标记、未使用变量检查与完整模板

新建模型更像人画的：回路标记、极性、未使用变量

这一版的重点是让 build 出来的图更接近人工绘制的效果，并且换成能力较弱的模型照模板写也能得到同样的结果。

新增

• R/B 回路标记由 build 画出。 按 feedback_loops 画出核对过的标记（方程推出、links 声明或数值偏导一致，整条回路在同一视图里）。排版时标记是占位的节点：被所属回路的中心吸引、落在回路里面，其他变量围绕它排布，圈的方向按回路走向设定；位置是否正确写进报告的 marker_check。没有声明回路时，build 找出能核对的回路，给出可直接粘贴的条目。
• 箭头极性自动标注。 默认给变量之间的链接标 +/-，方程推不出的（如两个变量相乘）按基准运行逐时刻数值求偏导；sketch.polarity 可改为 all 或 declared。
• 避免 Vensim 打开时的“未使用变量”提示（USE FLAG）。 新建模型里没人用的常量直接报错，没人用的输出指标自动写 :SUPPLEMENTARY。check 加入同口径检查和 --strict；fix --mark-supplementary 给已有模型标输出指标，不替没人用的常量掩盖。
• 完整模板 ev_adoption_zh.json。 新能源汽车推广：3 个存量、4 条回路、23 个变量，附对应示例 MDL 和 README 图；库存、水量模板补上回路声明。SPECIFICATIONS 新增“照模板写”一节。

改进

• 新建模型的存量链上下顺序按连线长短选择，不再受“原图行序”约束；另一种行序的最好结果也走完改进流程再比较。
• 中文存量名 10 个字以内一行写完，更长的折成长度相近的两行，不再把词拆开。
• 只被另一个视图使用的常量自动移到使用它的视图，避免多余的影子和孤立变量。
• build 输出“建议”：名字过长、常量被移视图、极性来自数值核对、回路未声明，都给出可照做的写法。
• 预览里极性符号避开管道。

验证

• 全量测试：Python 3.12 通过 284 项、跳过 1 项（外部多视图模型回归，需设置环境变量）；Python 3.10 与 3.14 只装 pytest 跑核心用例，各通过 247 项，依赖 SciPy、PySD、Matplotlib 的用例按设计跳过。
• 新增 21 个测试，覆盖未使用变量、Supplementary、数值极性、回路建议、视图归位、回路标记形状和三个示例模板。
• 随附的新能源汽车示例与 PySD 逐点一致；ruff、ruff format、bandit、shellcheck 通过。
• 7 个参考模型的排版与 PySD 对照保持不变。

已知边界

• 极性的数值核对只在基准运行覆盖的取值范围内成立。
• Overshoot 作者原图仍有 1 处箭头穿字，保留作者的弧线。
• 本机 Vensim PLE 无法自动原生导出，README 中的结构图是 preview 渲染的预览图，图注已注明；最终结构图请在 Vensim 中打开核对后导出。
• 二十几个变量的模型 build 约需 20 秒。

v2.3.1 — 修复参考依据与测试覆盖

修复与参考依据校正

这一版不改变排版算法，修的是文档与测试中不准确的地方，并补上一个测试缺口。

测试覆盖

• 内置引擎与 PySD 的逐点对照从 2 个参考模型扩展到全部 7 个，覆盖每个模型的全部标量变量。图形函数不能单独导出，由调用它的变量间接检验。
• 实测缩放误差不超过 1e-15，测试容差为 1e-10。
• PySD 对小数时长取整时的已知警告，只在对应测试中过滤，测试输出不再刷屏。

文档与依据

• Overshoot 的说明改为准确描述：原图两处文字相压、两条箭头穿过变量名；layout 挪开 2 个变量后，文字相压全部消除，穿字只剩作者原来的一条弧线，报告中会列出。
• 存量框尺寸补充官方示例的中位数（约 104×56）；视图规模 6–40 个定义变量标明为设计取值，并给出统计依据。
• 直线占比按研究模型、教材、官方示例分别给出中位数。
• Sterman《Business Dynamics》中无法确认的章节号改为引用“验证与模型检验”部分；Systems Thinker 两篇文章的引用与内容对齐。
• 结果图字体说明改为真实字体名：Windows 的 SimSun，macOS 的 Songti SC。

命令与配置

• README 功能表补充 fix 与 preview。
• --keep-going 的说明改为“把失败变量置零后继续”。
• 删除 .gitignore 中的冗余规则和没有用到的 SVG 属性规则；Windows 入口注释改为“命令行入口”。

已知边界

• Overshoot 作者原图仍有 1 处箭头穿字，保留作者的弧线，不强行改动。
• 本机 Vensim PLE 无法自动原生导出，README 中的结构图仍是 preview 渲染的预览图，图注已注明。
• 最终结构图请在 Vensim 中打开核对后导出。

验证

• 全量测试：263 项通过，1 项跳过（外部多视图回归，需设置 VENSIM_SKILL_REGRESSION_MODEL 后运行）；ruff、ruff format、bandit、shellcheck 通过。
• 参考模型 7 个全部通过 PySD 逐点对照。

v2.3.0 — Rule-based layout and reference models

排版规则落到代码里，换哪个大模型调用都按同一套规矩画图；收录 7 个真实教材模型作为参考和回归基准；删掉不再需要的功能。

排版

• auto 保留作者版面：原图只有一两处压字时，只挪开那几个变量，弧线和其他坐标不动；问题多时才整体重建。
• natural 重建存量链时，跳过中间存量的流量画成绕行支路或直角折线管道，画法取自 Duggan 教材原图；行距按教材模型统计设定。
• 长存量名在框内折成两行，不再把框拉成长条；碰撞检查按折行后的实际高度和对象自身字号计算。
• R/B 回路标记在弧线定下来以后放回它所在回路的内部。
• 隐藏变量的进出箭头一起隐藏，与 Vensim Hide/unhide 一致。
• 预览中的极性符号沿箭头方向放置，避开文字。

仿真

• crosscheck 按 max(1, |值|) 缩放差值，大数值变量的浮点舍入不再误报。
• simulate 不写 --var 时导出全部变量。

Skill

• 新增 assets/reference_models：Duggan System Dynamics Modeling with R 5 个模型、SDXorg 测试模型 2 个，MIT 许可，与上游逐字节一致；内置引擎与 PySD 对全部变量逐点一致。
• SKILL.md 改写为 12 条硬性规则；参考文档精简为 6 篇，补充文献出处。
• 删除 MCP 服务、circular 与 graphviz 模式、学术门禁和 16 个过时示例；旧配置使用这些模式时报错并提示替代方案。
• README 重写，附排版前后对比图和结果图。

验证

本地 macOS：Python 3.12 装齐可选依赖，258 个测试通过；Python 3.10、3.14 核心测试 226 个通过。ruff、bandit、shellcheck 无问题。GitHub Actions 因账号计费问题本次未能启动。

安装

npx skills add 1837620622/vensim-system-dynamics-skill --skill vensim-skill
gh skill install 1837620622/vensim-system-dynamics-skill vensim-skill --pin v2.3.0

v2.2.6 — Native layout and official shadow handling

主要变更

• 移除布局流程中的 Graphviz 外部调用；auto 使用确定性的本地存量—流量骨架、局部锚点、文字框和原生单控制点圆弧候选。旧 graphviz 模式只保留为迁移别名，不启动外部可执行文件，也不把外部样条写回 MDL。
• 大型连通模块改用局部锚点或圆角边界，小型闭环保留椭圆候选，避免规则大圆、云团、超宽长对角线和机械交错弧线。
• 按 Vensim Hide Depth 处理影子变量：shadow_visibility: orphan 默认只隐藏没有可见入/出线的重复影子；preserve 保留全部影子；all 必须显式选择，并连同出入箭头隐藏。方程字节、对象身份、箭头端点、极性和延迟字段保持不变。
• 几何报告区分可见与隐藏影子；增加影子隐藏拓扑回归、无外部布局器回归以及大型自然布局回归。
• 更新中英文 README、Skill 规则、操作手册、实现依据、规格和审计记录；机器可读版本统一为 2.2.6。

验证

• 非 MCP 完整回归：221 passed，2 deselected，2 个 PySD 固定延迟取整警告。
• 布局、影子、分发专项：52 passed。
• Ruff、Bandit、Skill quick validation、gh skill publish --dry-run 和本地 skill 识别通过。
• 当前全局 MCP SDK 为 1.27.0，项目安全门禁要求 mcp>=1.28.1,<2；因此全套测试中的 2 个 MCP 用例在启动时被安全门禁拒绝，未将该环境结果标为通过。安装 requirements/mcp.txt 后再运行 MCP 用例。

使用边界

结构图仍必须由交付 MDL 在原生 Vensim 中打开后导出或截图；SVG/HTML 预览只用于几何诊断。Python 仿真和 PySD 交叉检查不能单独宣称原生 Vensim 数值等价。

English

This release removes Graphviz execution from the layout path, adds deterministic skeleton-first local layout candidates, and implements conservative Vensim Hide Depth shadow handling. The legacy graphviz mode is a migration alias only. The delivered MDL remains the source of truth for native structure figures.

v2.2.5

Full Changelog: v2.2.4...v2.2.5

v2.2.4

Full Changelog: v2.2.3...v2.2.4

v2.2.3

Full Changelog: v2.2.2...v2.2.3

v2.2.2 — Function boundaries and reproducible experiments

修复 Vensim STEP 半步/非网格边界、负被除数的 MODULO 余数符号和 RAMP 开始时刻。批量情景、敏感性和步长检查保持同一 MDL 哈希，拒绝运行之间或绘图期间的源模型变化；收敛比较要求相同保存时刻。

• 204 项完整本地测试通过；可选库缺失的独立检查为 176 项通过、28 项按预期跳过。
• Ruff lint/format、Bandit、ShellCheck、Skill 格式、Python 3.10 语法和本地文档链接通过。
• Betterleaks 发布范围未报告泄漏，实际测试依赖清单 65 个包的 OSV 扫描未报告已知漏洞；不等同于全局环境或全部逻辑安全证明。
• Context7、Exa、官方 Vensim 文档与本地实际 PySD 源码交叉核对。原生 PLE 测试副本通过单位检查并生成 VDFX，没有获得全量原生数值导出，不写为逐点原生数值验收。
• MODULO 非正除数明确报出原生核对要求；极小正除数、反向 RAMP 与脉冲边界的跨后端限制写入语义手册。
• 中文默认变量、自然环形布局、黑/纯蓝原生箭头、影子变量规则、真实 MDL 图源、彩色无标题 Python 图件和非商业署名约束保留。
• 完整中英文 README 与审查记录同步更新。

发布资产来自同一版本标签的 Skill 目录，包含许可证与作者说明；仅 Windows skill.cmd 的换行规范化为 CRLF，原生 MDL 字节保持标签内容，POSIX 入口保留执行权限。ZIP 配套 SHA256SUMS。

当前提交的 GitHub Actions 未启动测试：账号账单锁定，9 个 job 的 steps 均为空。不能把本地通过写为 Windows/macOS/Linux 远程 CI 全部通过。详情：Actions 状态

完整变更比较

v2.2.1 · 仿真语义修复、工程规范与英文文档

修复内置仿真语义、变量身份和结果来源检查，并补齐英文 README 与可执行代码规范。新建中文环形布局、黑色／原生纯蓝箭头、真实 MDL 原生结构图和无标题彩色结果图的规则继续保留。

修复与补充

• ZIDZ(A,B) 恢复原生两参数语法；XIDZ/ZIDZ 使用绝对分母小于 1e-6 的保护规则。
• DELAY FIXED 使用独立状态，冻结初始化时长与初值，支持延迟反馈与离散取整；嵌入其他表达式时报错。
• PULSE 支持零宽度及官方半步比较；文档明确非网格边界在不同后端可能不同。
• 原生名称大小写、空格／下划线等价规则用于引用和重复检查；隐式状态冲突、嵌套内部别名错配有单独回归。
• Lookup 支持独立表和 WITH LOOKUP，显示范围与参考点不参加插值；真实数据点支持科学计数法，乱序、重复及非有限值拒绝。
• 非有限常量、函数输入／结果及状态更新不能作为成功轨迹；时间浮点精度与延迟状态规模有保护。
• CSV 与运行／实验／搜索清单核对 SHA-256，恢复诊断状态、时间单位及 Monte Carlo 身份；诊断结果拒绝正式出图。
• MCP 输出在解析前拒绝断裂符号链接，CSV 相邻清单不能越出结果目录。
• doctor 检查当前解释器的已安装依赖与安全修复下限，区分缺包、需要升级和待核对版本；不自动修改全局 Python。
• pyproject.toml 统一 Ruff 导入、Python 3.10 类型语法、异常／闭包检查和格式，CI 增加格式校验。
• 新增完整 English README、仿真语义手册 和 审查记录。

验证与实际边界

• 本地 182 项测试通过，包含 PySD、MCP、SciPy、Matplotlib 和针对性仿真边界回归。两条 PySD 延迟取整提示是预期测试输入。
• 修正后的 Lookup 示范对照 241 个保存点，Price／Demand／Supply 的内置与 PySD 最大绝对差均为 0，MDL 源字节保留。这不是所有模型的原生逐点等价证明。
• Ruff lint/format、Bandit、ShellCheck、Skill 规范和文档链接校验通过。Betterleaks 未报告发布范围泄漏。
• OSV 对重新解析的 65 项依赖和补足修复版本后的 65 项实际测试依赖均未报告已知漏洞。初次实际环境扫描发现旧 lxml／Pillow；已在临时测试目录补足修复版本。全局旧包保持原状，doctor 会提示；不能把这个范围扩写成整台机器安全。
• 既有原生图件与验收记录保留。新增函数边界没有全部在原生 Vensim 中逐点核验；任意复杂网络零交叉、自动符号位置、完整 Vensim 函数及官方 DSS MCP 调用仍不作保证。
• Windows/macOS/Linux 的测试矩阵已配置；本次 Actions 的 9 个任务均执行 0 步，账号因计费问题被锁定，任务未启动。不能用本机通过代替远程三平台通过。

安装

npx skills add 1837620622/vensim-system-dynamics-skill --skill vensim-skill

固定版本：

gh skill install 1837620622/vensim-system-dynamics-skill vensim-skill --pin v2.2.1 --agent codex --scope user

本发布提供 vensim-skill-v2.2.1.zip 和 SHA256SUMS.txt。压缩包根目录为 vensim-skill/，包含标准 Skill 入口、脚本、手册、模板与许可证。英文 README 是仓库完整说明，安装包内保留中文任务手册。

作者：传康KK（万能程序员）。禁止商业使用；非商业修改与分发须保留署名和许可证，图内不添加水印。第三方依赖遵守各自许可。

v2.2.0 · 环形布局、反馈核对与彩色论文图件

新建中文 MDL 现在默认按真实反馈关系组织环形布局，参数靠近作用对象。存量、阀门、云与实体管道保持原生骨架，图上的正负极性与模型方程共同检查。

新增与修复

• 自然环形布局：独立模块分别展开，外围参数不占反馈环的位置，文字框与影子括号参与间距计算。显式坐标优先，不调用 Graphviz 路由。
• 反馈核对：新增 feedback 命令与 check_feedback MCP 工具。检查已标箭头的正负号和指定回路的 R/B；可确定的冲突阻止新建，复杂关系列为待核对。初值边不构成动态反馈，回路正负与顺逆时针分开判断。
• 符号位置规则：正负号靠近对应目标箭头的空白侧，R/B 放在对应回路内部留白。位置仍要求原生审图；不把近似几何检查当作原生验收。
• 彩色仿真图：单曲线、多情景和分位带默认彩色，图例与线型同步，密集编号在真实采样点上避让。支持可配置网格、色表、分位带透明度及 600/1200 DPI，保留 PDF/SVG 矢量输出。默认无标题、图号、图标或水印。
• 场景身份保护：大量命名政策情景不再自动合并为分位带；自动分位带只用于明确的 Monte Carlo 样本。
• 几何与输入修复：锚点先参与避让，明确建模坐标不被移动，实体管道穿字计入失败；拒绝把布尔值当作坐标或把浮点数当作路由次数。
• 通用模板：业务方程、初值、参数、时间与实验设置来自当前任务。空模板不会加载旧案例；示范数值只用于演示与回归。
• 文献与工程说明：新增学术表达和反馈核对手册，参考 Vensim 原生文档、Sterman、Rahmandad 与 MIT 教材；CLI、Python 与 MCP 共用规则，MCP 提供 13 个固定工具。

模型结构图保留黑色／纯蓝原生箭头，正式结构图必须从对应真实 MDL 在 Vensim 原生导出。新增环形示范附有 MDL、JSON、原生 SVG 与哈希验收记录。

验证与边界

• 本机 144 项测试通过，包含 PySD、MCP、SciPy 校准优化、反馈、布局与绘图。
• Ruff、Bandit、ShellCheck、Skill 规范与发现检查通过。
• Betterleaks 未报告待发布文件泄漏；OSV 对实际解析的 65 个可选依赖版本未报告已知漏洞。这不等于完整安全证明。
• macOS 的 Vensim PLE 10.5.0 已完成环形示范的 Check Model、Units Check、原生图面与 SVG 导出检查；没有声称完成原生逐点数值对照。
• Windows/macOS/Linux 测试矩阵已配置，但远程任务因 GitHub 账户计费锁未能启动，不能视为远程三平台测试通过。
• 自动布局不保证任意网络零交叉；复杂语法和非线性极性保留明确边界。校准、优化和高级分析为独立 Python 实现，不声称与 DSS 全部能力等价。

安装

npx skills add 1837620622/vensim-system-dynamics-skill --skill vensim-skill

需要固定版本时：

gh skill install 1837620622/vensim-system-dynamics-skill vensim-skill --pin v2.2.0 --agent codex --scope user

也可下载本发布中的 vensim-skill-v2.2.0.zip；压缩包根目录为 vensim-skill/，包含标准 SKILL.md、脚本、参考手册、模板与许可证。SHA256SUMS.txt 用于核对下载文件。

作者：传康KK（万能程序员）。仅限非商业使用，署名及许可证随 Skill 分发，图内不添加作者水印。