新增「虚拟机框架：帧对象与求值循环」章节，开篇第四部分虚拟机

Prodesire · Prodesire · commit 2a246bb118f2 · 2026-06-24T13:27:43.000+08:00
讲解栈式虚拟机、帧对象 PyFrameObject 各字段、f_back 串成的帧栈，以及 ceval 求值循环的取指令-派发-执行骨架与 BINARY_ADD 实例
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
@@ -70,7 +70,8 @@ export default defineConfig({
       {
         text: '第 4 部分：虚拟机',
         items: [
-          { text: '字节码的执行（编写中…）', link: '/' }
+          { text: 'Python 虚拟机框架（帧对象与求值循环）', link: '/vm/frame-and-eval-loop/' },
+          { text: '一般表达式与名字空间（编写中…）', link: '/' }
         ]
       },
       {
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -29,7 +29,7 @@
 
 ## 第 4 部分：虚拟机
 
-- Python 虚拟机框架（帧对象与求值循环）
+- [Python 虚拟机框架（帧对象与求值循环）](vm/frame-and-eval-loop/index.md)
 - 一般表达式与名字空间
 - 控制流：跳转、循环与迭代器
 - 异常机制：block 栈与栈展开
diff --git a/index.md b/index.md
@@ -30,7 +30,7 @@
     - [x] 从源码到字节码（编译过程）
     - [x] 编译的产物：code object 与 pyc
 - [ ] 第 4 部分：虚拟机
-    - [ ] Python 虚拟机框架（帧对象与求值循环）
+    - [x] Python 虚拟机框架（帧对象与求值循环）
     - [ ] 一般表达式与名字空间
     - [ ] 控制流：跳转、循环与迭代器
     - [ ] 异常机制：block 栈与栈展开
diff --git a/vm/frame-and-eval-loop/eval-loop.svg b/vm/frame-and-eval-loop/eval-loop.svg
@@ -0,0 +1,57 @@
+<svg width="100%" viewBox="0 0 700 300" xmlns="http://www.w3.org/2000/svg" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'PingFang SC','Microsoft YaHei',sans-serif">
+<title>求值循环：取指令 → 派发 → 执行 → 再取指令</title>
+<desc>虚拟机的核心是 ceval.c 里的求值循环。它周而复始地做三件事：先取出下一条字节码指令（NEXTOPARG 解出 opcode 与 oparg），再用一个巨大的 switch 按 opcode 跳转到对应分支，分支里执行该指令、操作求值栈，最后 DISPATCH 回到开头取下一条。如此一条接一条，直到遇到 RETURN_VALUE 返回。</desc>
+<defs>
+  <style>
+    .ti{font-size:12.5px;font-weight:600;}
+    .h{font-size:11.5px;font-weight:600;}
+    .c{font-size:10.5px;font-family:'SF Mono','JetBrains Mono',ui-monospace,Consolas,monospace;}
+    .d{font-size:10px;}
+  </style>
+  <filter id="sh" x="-30%" y="-30%" width="160%" height="160%"><feDropShadow dx="0" dy="1.4" stdDeviation="2" flood-color="#2A2A28" flood-opacity="0.12"/></filter>
+  <linearGradient id="gB" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#EFF3FA"/><stop offset="1" stop-color="#E0E9F6"/></linearGradient>
+  <linearGradient id="gP" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F3F1FD"/><stop offset="1" stop-color="#E9E6FB"/></linearGradient>
+  <linearGradient id="gG" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#E9F6F1"/><stop offset="1" stop-color="#DBF0E7"/></linearGradient>
+  <linearGradient id="gR" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F8EEEE"/><stop offset="1" stop-color="#F1E1E1"/></linearGradient>
+  <marker id="ah" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="#8E8B80" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></marker>
+  <marker id="ahr" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="#B07575" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></marker>
+</defs>
+
+<rect x="0" y="0" width="700" height="300" fill="#FBFAF6"/>
+<text x="350" y="28" text-anchor="middle" class="ti" fill="#28415F">求值循环：一条接一条地执行字节码</text>
+
+<!-- three boxes in a cycle -->
+<!-- 1 fetch -->
+<rect x="60" y="96" width="170" height="64" rx="10" fill="url(#gB)" stroke="#C3D2E8" stroke-width="1.1" filter="url(#sh)"/>
+<text x="145" y="120" text-anchor="middle" class="h" fill="#28415F">① 取下一条指令</text>
+<text x="145" y="138" text-anchor="middle" class="c" fill="#4A5E80">NEXTOPARG()</text>
+<text x="145" y="152" text-anchor="middle" class="d" fill="#6B7E9E">解出 opcode + oparg</text>
+
+<!-- 2 dispatch -->
+<rect x="265" y="96" width="170" height="64" rx="10" fill="url(#gP)" stroke="#CCC7F1" stroke-width="1.1" filter="url(#sh)"/>
+<text x="350" y="120" text-anchor="middle" class="h" fill="#2E2972">② 按 opcode 派发</text>
+<text x="350" y="138" text-anchor="middle" class="c" fill="#4A4396">switch (opcode)</text>
+<text x="350" y="152" text-anchor="middle" class="d" fill="#6A63B0">跳到对应指令的分支</text>
+
+<!-- 3 execute -->
+<rect x="470" y="96" width="170" height="64" rx="10" fill="url(#gG)" stroke="#A8DCC9" stroke-width="1.1" filter="url(#sh)"/>
+<text x="555" y="120" text-anchor="middle" class="h" fill="#0A463A">③ 执行该指令</text>
+<text x="555" y="138" text-anchor="middle" class="d" fill="#0C5945">操作求值栈（压/弹/算）</text>
+<text x="555" y="152" text-anchor="middle" class="c" fill="#0C5945">DISPATCH()</text>
+
+<!-- arrows between -->
+<g fill="none" stroke="#8E8B80" stroke-width="1.7" marker-end="url(#ah)">
+  <path d="M230,128 H263"/>
+  <path d="M435,128 H468"/>
+</g>
+
+<!-- loop back arrow from execute to fetch -->
+<path d="M555,160 C555,210 145,210 145,162" fill="none" stroke="#8E8B80" stroke-width="1.7" marker-end="url(#ah)"/>
+<text x="350" y="204" text-anchor="middle" class="d" fill="#9A988F">DISPATCH：回到 ① 取下一条 —— 周而复始</text>
+
+<!-- exit on RETURN_VALUE -->
+<rect x="470" y="234" width="170" height="40" rx="10" fill="url(#gR)" stroke="#E0C6C6" stroke-width="1.1" filter="url(#sh)"/>
+<text x="555" y="258" text-anchor="middle" class="h" fill="#5C3030">遇 RETURN_VALUE → 退出循环</text>
+<path d="M600,160 V232" fill="none" stroke="#B07575" stroke-width="1.6" marker-end="url(#ahr)"/>
+<text x="638" y="200" text-anchor="middle" class="d" fill="#7A3B3B">返回</text>
+</svg>
diff --git a/vm/frame-and-eval-loop/frame-object.svg b/vm/frame-and-eval-loop/frame-object.svg
@@ -0,0 +1,66 @@
+<svg width="100%" viewBox="0 0 700 340" xmlns="http://www.w3.org/2000/svg" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'PingFang SC','Microsoft YaHei',sans-serif">
+<title>帧对象 PyFrameObject：执行一段字节码的现场</title>
+<desc>一个帧对象是执行某段字节码的完整现场。它通过 f_code 指向要执行的 code object；通过 f_globals、f_locals、f_builtins 指向取名字要用的三个名字空间；自带一个求值栈（f_valuestack 起点、f_stacktop 栈顶）供指令临时存放操作数；用 f_lasti 记录执行到第几条指令；并通过 f_back 指回调用它的上一个帧，从而把所有帧串成调用链。</desc>
+<defs>
+  <style>
+    .ti{font-size:12.5px;font-weight:600;}
+    .h{font-size:11.5px;font-weight:600;}
+    .f{font-size:11px;font-family:'SF Mono','JetBrains Mono',ui-monospace,Consolas,monospace;}
+    .d{font-size:10px;}
+  </style>
+  <filter id="sh" x="-30%" y="-30%" width="160%" height="160%"><feDropShadow dx="0" dy="1.4" stdDeviation="2" flood-color="#2A2A28" flood-opacity="0.12"/></filter>
+  <linearGradient id="gP" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F3F1FD"/><stop offset="1" stop-color="#E9E6FB"/></linearGradient>
+  <linearGradient id="gN" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F1EFE8"/><stop offset="1" stop-color="#E7E4DA"/></linearGradient>
+  <linearGradient id="gA" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#FAEFD9"/><stop offset="1" stop-color="#F4E6C8"/></linearGradient>
+  <linearGradient id="gB" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#EFF3FA"/><stop offset="1" stop-color="#E0E9F6"/></linearGradient>
+  <linearGradient id="gG" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#E9F6F1"/><stop offset="1" stop-color="#DBF0E7"/></linearGradient>
+  <marker id="ah" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="#8E8B80" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></marker>
+</defs>
+
+<rect x="0" y="0" width="700" height="340" fill="#FBFAF6"/>
+<text x="350" y="28" text-anchor="middle" class="ti" fill="#2E2972">帧对象：执行一段字节码的「现场」</text>
+
+<!-- central frame -->
+<rect x="270" y="96" width="170" height="172" rx="11" fill="url(#gP)" stroke="#CCC7F1" stroke-width="1.3" filter="url(#sh)"/>
+<text x="355" y="118" text-anchor="middle" class="h" fill="#2E2972">帧 PyFrameObject</text>
+<g class="f" fill="#2E2972">
+  <text x="286" y="142">f_back</text>
+  <text x="286" y="164">f_code</text>
+  <text x="286" y="186">f_globals</text>
+  <text x="286" y="208">f_locals</text>
+  <text x="286" y="230">f_builtins</text>
+  <text x="286" y="252">f_valuestack</text>
+</g>
+
+<!-- caller frame (top) via f_back -->
+<rect x="290" y="44" width="130" height="34" rx="9" fill="url(#gN)" stroke="#D8D3C6" filter="url(#sh)"/>
+<text x="355" y="65" text-anchor="middle" class="h" fill="#46453F">调用者的帧</text>
+<path d="M355,96 V80" fill="none" stroke="#8E8B80" stroke-width="1.6" marker-end="url(#ah)"/>
+<text x="368" y="92" class="d" fill="#9A988F">f_back</text>
+
+<!-- code object (left) via f_code -->
+<rect x="40" y="150" width="150" height="48" rx="9" fill="url(#gA)" stroke="#E8CB94" filter="url(#sh)"/>
+<text x="115" y="170" text-anchor="middle" class="h" fill="#5C3C08">code object</text>
+<text x="115" y="187" text-anchor="middle" class="d" fill="#8A6A1E">co_code 字节码 + 各表</text>
+<path d="M270,164 H192" fill="none" stroke="#8E8B80" stroke-width="1.6" marker-end="url(#ah)"/>
+<text x="222" y="158" class="d" fill="#9A988F">f_code</text>
+
+<!-- namespaces (right) -->
+<rect x="510" y="150" width="160" height="68" rx="9" fill="url(#gB)" stroke="#C3D2E8" filter="url(#sh)"/>
+<text x="590" y="170" text-anchor="middle" class="h" fill="#28415F">三个名字空间</text>
+<text x="590" y="188" text-anchor="middle" class="d" fill="#4A5E80">局部 / 全局 / 内建</text>
+<text x="590" y="204" text-anchor="middle" class="d" fill="#4A5E80">取名字时按序查这三处</text>
+<path d="M440,186 H508" fill="none" stroke="#8E8B80" stroke-width="1.6" marker-end="url(#ah)"/>
+
+<!-- value stack (bottom) -->
+<rect x="500" y="244" width="170" height="60" rx="9" fill="url(#gG)" stroke="#A8DCC9" filter="url(#sh)"/>
+<text x="585" y="264" text-anchor="middle" class="h" fill="#0A463A">求值栈</text>
+<text x="585" y="281" text-anchor="middle" class="d" fill="#0C5945">指令临时存放操作数的地方</text>
+<text x="585" y="296" text-anchor="middle" class="d" fill="#0C5945">f_stacktop 指向栈顶</text>
+<path d="M440,252 C470,256 480,262 498,268" fill="none" stroke="#8E8B80" stroke-width="1.6" marker-end="url(#ah)"/>
+
+<text x="160" y="246" class="h" fill="#46453F">f_lasti</text>
+<text x="160" y="263" class="d" fill="#8A887E">记录执行到第几条指令</text>
+<text x="160" y="277" class="d" fill="#8A887E">（执行进度）</text>
+<path d="M286,240 C240,238 210,245 200,250" fill="none" stroke="#C0BDB4" stroke-width="1.4" stroke-dasharray="3 3"/>
+</svg>
diff --git a/vm/frame-and-eval-loop/frame-stack.svg b/vm/frame-and-eval-loop/frame-stack.svg
@@ -0,0 +1,48 @@
+<svg width="100%" viewBox="0 0 700 300" xmlns="http://www.w3.org/2000/svg" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'PingFang SC','Microsoft YaHei',sans-serif">
+<title>帧栈：f_back 把帧串成调用链</title>
+<desc>每发生一次函数调用，就新建一个帧并压到帧栈顶；每个帧的 f_back 指回调用它的上一个帧。outer() 调用 inner() 时，inner 的帧在栈顶、f_back 指向 outer 帧，outer 帧再指向模块帧。这条由 f_back 串起来的链就是调用栈，出错时打印的 traceback 正是顺着它回溯的。</desc>
+<defs>
+  <style>
+    .ti{font-size:12.5px;font-weight:600;}
+    .h{font-size:11.5px;font-weight:600;}
+    .f{font-size:11px;font-family:'SF Mono','JetBrains Mono',ui-monospace,Consolas,monospace;}
+    .d{font-size:10px;}
+  </style>
+  <filter id="sh" x="-30%" y="-30%" width="160%" height="160%"><feDropShadow dx="0" dy="1.4" stdDeviation="2" flood-color="#2A2A28" flood-opacity="0.12"/></filter>
+  <linearGradient id="gP" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F3F1FD"/><stop offset="1" stop-color="#E9E6FB"/></linearGradient>
+  <marker id="ah" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="#6A63B0" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></marker>
+</defs>
+
+<rect x="0" y="0" width="700" height="300" fill="#FBFAF6"/>
+<text x="350" y="30" text-anchor="middle" class="ti" fill="#2E2972">帧栈：每次调用压一个帧，f_back 指回调用者</text>
+
+<!-- three stacked frames -->
+<!-- module frame (bottom) -->
+<rect x="200" y="210" width="300" height="56" rx="10" fill="url(#gP)" stroke="#CCC7F1" stroke-width="1.2" filter="url(#sh)"/>
+<text x="220" y="232" class="h" fill="#2E2972">&lt;module&gt; 帧</text>
+<text x="220" y="252" class="d" fill="#6A63B0">模块顶层代码，调用链的底部</text>
+<text x="484" y="240" text-anchor="end" class="f" fill="#9A988F">f_back = NULL</text>
+
+<!-- outer frame -->
+<rect x="200" y="132" width="300" height="56" rx="10" fill="url(#gP)" stroke="#CCC7F1" stroke-width="1.2" filter="url(#sh)"/>
+<text x="220" y="154" class="h" fill="#2E2972">outer 帧</text>
+<text x="220" y="174" class="d" fill="#6A63B0">局部变量 msg = "hi"</text>
+
+<!-- inner frame (top) -->
+<rect x="200" y="54" width="300" height="56" rx="10" fill="url(#gP)" stroke="#CCC7F1" stroke-width="1.4" filter="url(#sh)"/>
+<text x="220" y="76" class="h" fill="#2E2972">inner 帧 ← 栈顶（正在执行）</text>
+<text x="220" y="96" class="d" fill="#6A63B0">sys._getframe() 拿到的就是它</text>
+
+<!-- f_back arrows pointing down (back to caller) -->
+<path d="M540,82 C580,82 580,160 542,160" fill="none" stroke="#6A63B0" stroke-width="1.7" marker-end="url(#ah)"/>
+<text x="592" y="124" text-anchor="middle" class="f" fill="#6A63B0">f_back</text>
+<path d="M540,160 C580,160 580,238 542,238" fill="none" stroke="#6A63B0" stroke-width="1.7" marker-end="url(#ah)"/>
+<text x="592" y="202" text-anchor="middle" class="f" fill="#6A63B0">f_back</text>
+
+<!-- caller direction labels on left -->
+<text x="150" y="86" text-anchor="end" class="d" fill="#9A988F">后调用</text>
+<text x="150" y="244" text-anchor="end" class="d" fill="#9A988F">先调用</text>
+<path d="M150,98 V232" fill="none" stroke="#C0BDB4" stroke-width="1.2" stroke-dasharray="3 4"/>
+
+<text x="350" y="288" text-anchor="middle" class="d" fill="#9A988F">调用链：inner → outer → &lt;module&gt;，traceback 正是顺着 f_back 回溯打印</text>
+</svg>
diff --git a/vm/frame-and-eval-loop/index.md b/vm/frame-and-eval-loop/index.md
diff --git a/vm/frame-and-eval-loop/value-stack.svg b/vm/frame-and-eval-loop/value-stack.svg

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,8 @@ export default defineConfig({`
`70`	`70`	`{`
`71`	`71`	`text: '第 4 部分：虚拟机',`
`72`	`72`	`items: [`
`73`		`- { text: '字节码的执行（编写中…）', link: '/' }`
	`73`	`+ { text: 'Python 虚拟机框架（帧对象与求值循环）', link: '/vm/frame-and-eval-loop/' },`
	`74`	`+ { text: '一般表达式与名字空间（编写中…）', link: '/' }`
`74`	`75`	`]`
`75`	`76`	`},`
`76`	`77`	`{`