From 205e3a70247d89fc5145656aa3570afdf131f550 Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Tue, 21 Jul 2026 06:34:06 +0200
Subject: [PATCH 1/2] docs: define PikaPython V2 kernel strategy

---
 .../PJ2026-05/specs/PJ2026-05-pikapython.md   | 199 ++++++++++
 .../PJ2026-05/specs/PJ2026-0501-v2-kernel.md  | 340 ++++++++++++++++++
 .../specs/PJ2026-0502-static-acceleration.md  | 116 ++++++
 3 files changed, 655 insertions(+)
 create mode 100644 project-management/PJ2026-05/specs/PJ2026-05-pikapython.md
 create mode 100644 project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md
 create mode 100644 project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md

diff --git a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md
new file mode 100644
index 00000000..e930c96b
--- /dev/null
+++ b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md
@@ -0,0 +1,199 @@
+# PJ2026-05 PikaPython 总规格
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+| v0.1 | 待本版本提交 | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 |
+
+修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
+
+## 正文
+
+## PJ2026-05 PikaPython 总项目需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-05 |
+| 短名 | PikaPython |
+| 层级 | L0 总项目 |
+| 规格状态 | 已生效 |
+| 实现引用版本 | v0.1 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。
+
+本文的正文边界如下：
+
+- 只定义预期终态、稳定使命、路线边界、原子需求和验收契约；
+- 当前实现状态和阶段差距进入 TaskTree 或阶段报告；
+- 提交、PR、benchmark 作业和日志进入执行 issue，不进入本规格正文。
+
+## 2. 目的和范围
+
+### 2.1 项目使命
+
+PikaPython 面向资源受限微控制器提供可裁剪的 Python 运行能力：
+
+- 应用在受控 Flash 和 RAM 预算内运行；
+- 应用可以选择足够的 Python 语法、模块和本地扩展能力；
+- 运行时性能和确定性与功能范围共同参与设计裁决。
+
+项目采用两条互相隔离、可独立验收的技术路线：
+
+- V2 内核路线：
+  - 重写 V1 路线的动态 Python 子集内核；
+  - 从第一版开始以运行时性能、Flash 和 RAM 为核心设计输入；
+  - 允许语法兼容性弱于 MicroPython；
+  - 延续并强化 V1 的编译期和构建期裁剪能力。
+- 静态加速路线：
+  - 面向显式静态约束或编译加速场景独立演进；
+  - 不作为 V2 的依赖、兼容层、发布门禁或架构前提；
+  - strict type、LLVM 或其他静态编译技术只能在该路线的独立规格中决策。
+
+### 2.2 预期终态
+
+PikaPython 应形成一个可持续演进的嵌入式 Python 产品族：
+
+- V1 保持已有用户、语法、模块和板级生态的稳定交付；
+- V2 以重新设计的内核显著超越 V1，并在代表性运行时负载上小幅超越同级 MicroPython 配置；
+- 静态加速路线面向适合编译期约束的代码提供独立加速能力；
+- 两条新路线共享可比较的测试语义、benchmark 方法和板级接口原则，但不共享必须同步演进的内核架构；
+- 所有路线都能对不支持的语法、资源耗尽和运行时错误给出清晰、确定且可测试的结果。
+
+### 2.3 范围内
+
+- Python 子集的解析、编译、字节码或其他执行表示。
+- VM、对象模型、调用约定、内存管理、异常和模块系统。
+- C 模块绑定、平台移植和微控制器资源裁剪。
+- Linux 功能、性能与资源基线，以及目标架构功能和资源验证。
+- V1、V2、MicroPython 和适用静态实现的版本化比较。
+
+### 2.4 范围外
+
+- 以完整 CPython 兼容性作为嵌入式内核的首要目标。
+- 为追求语法数量而牺牲资源边界、错误可见性或可裁剪性。
+- 用 QEMU 性能数据替代 Linux 性能裁决。
+- 把静态类型、LLVM、JIT 或目标相关 native emitter 设为 V2 必需能力。
+- 要求 V2 复用 V1 的内部对象布局、字节码、调用栈或源码架构。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| V1 | 已交付的 PikaPython 内核和兼容生态。 |
+| V2 | 重新设计和实现的动态 Python 子集内核，不表示 V1 内部架构的第二版补丁。 |
+| 静态加速 | 依赖显式静态约束或编译期类型事实的独立执行路线。 |
+| 可裁剪性 | 在构建期按语法、opcode、对象类型、模块和平台能力移除不需要代码与数据的能力。 |
+| 可比较配置 | 为各实现选择相同 workload 所需语义和模块后的最小可运行配置。 |
+| 代表性 suite | 同时覆盖调用、算术、分支、循环、容器、属性、模块和边界调用的版本化 Linux benchmark 集合。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 嵌入式应用开发者、模块开发者、移植维护者和自动化构建系统。 |
+| 外部输入 | Python 源码或预编译产物、C 模块、构建裁剪配置、平台端口和资源预算。 |
+| 受控资源 | 解析器、编译器、执行内核、对象与堆、模块注册表、平台抽象和生成产物。 |
+| 外部输出 | 可执行固件或库、字节码、运行结果、异常、资源报告和 benchmark 报告。 |
+| 用户接口 | Python 子集、C API、模块绑定、构建配置和 workspace CLI。 |
+| 系统边界 | PikaPython 负责语言子集和运行时语义，不替代板级操作系统、驱动、工具链或应用资源规划。 |
+
+## 5. 路线分工与规格索引
+
+| 编号 | 路线 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-0501 | V2内核 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) | 动态 Python 子集、紧凑 VM、对象模型、资源裁剪和 V1 演进替代能力。 | V1 用户语义、嵌入式平台约束、先进 VM 技术。 | 新应用、V1 迁移、模块与板级生态。 |
+| PJ2026-0502 | 静态加速 | [PJ2026-0502 静态加速](PJ2026-0502-static-acceleration.md) | 显式静态约束下的独立编译和执行加速。 | 静态语义契约、编译工具链。 | 计算密集且可静态化的函数或模块。 |
+
+### 5.1 目标路线关系
+
+```mermaid
+flowchart LR
+  APP[嵌入式 Python 应用] --> V1[V1 稳定交付]
+  APP --> V2[V2 动态子集内核]
+  APP -. 显式选择 .-> S[静态加速路线]
+  V1 -->|行为经验与迁移需求| V2
+  V2 -. 不依赖 .-> S
+  S -. 不约束 .-> V2
+  V2 --> MCU[微控制器运行面]
+  S --> MCU
+```
+
+## 6. 全局原子需求
+
+### 6.1 PIKA-L0-REQ-001 双路线隔离
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| PIKA-L0-REQ-001 | 路线隔离 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) | [PJ2026-0502 静态加速](PJ2026-0502-static-acceleration.md) |
+
+V2 和静态加速必须保持以下隔离：
+
+- 分别声明语言前提、内核架构、性能结论和发布门禁；
+- 任一路线的实验失败不得阻塞另一条路线；
+- 任一路线的工具链限制或语法要求不得进入另一条路线。
+
+### 6.2 PIKA-L0-REQ-002 嵌入式优先
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| PIKA-L0-REQ-002 | 嵌入式优先 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) | [PJ2026-0502 静态加速](PJ2026-0502-static-acceleration.md) |
+
+嵌入式优先要求如下：
+
+- 语言能力、数据布局、调度机制和模块边界必须考虑 Flash、RAM 和栈限制；
+- 确定性限制必须参与内核结构裁决；
+- 新增语法或模块不得默认进入最小配置。
+
+### 6.3 PIKA-L0-REQ-003 可重复比较
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| PIKA-L0-REQ-003 | 版本比较 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) | [PJ2026-0502 静态加速](PJ2026-0502-static-acceleration.md) |
+
+性能主张必须满足以下条件：
+
+- 使用版本固定、配置可见、一次性容器运行的 Linux benchmark；
+- 同时披露运行时、Flash、静态 RAM 和峰值动态 RAM；
+- 同时披露功能配置和统计方法；
+- QEMU 不参与性能结论。
+
+### 6.4 PIKA-L0-REQ-004 错误确定性
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| PIKA-L0-REQ-004 | 错误确定性 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) | [PJ2026-0502 静态加速](PJ2026-0502-static-acceleration.md) |
+
+错误确定性要求如下：
+
+- 不支持的语法、非法字节码、类型错误和资源耗尽必须产生明确且可测试的诊断；
+- 栈耗尽属于微控制器致命故障时，系统必须先报告清晰原因；
+- 报告后进入确定停机状态，不得静默继续、无限解析或未报告崩溃。
+
+## 7. 全局验收合同
+
+- 路线验收：
+  - V2 不依赖 strict type、LLVM、JIT 或静态加速路线产物即可独立构建、测试和发布；
+  - 静态加速路线不得改变 V2 的默认语言语义或资源基线。
+- 性能验收：
+  - Linux 是唯一性能裁决环境；
+  - 单一 fib、启动时间或 parser 时间不能替代代表性 runtime suite；
+  - 每项结果必须绑定实现版本、提交、编译器、优化级别和可比较配置。
+- 资源验收：
+  - Flash、静态 RAM、峰值动态 RAM和单次 workload 动态分配必须分别披露；
+  - 资源补偿可以发生在同一发布范围的其他模块，但总配置不得通过隐藏功能差异制造优势。
+
+## 8. 过程控制
+
+- V2 内核实现引用 `PJ2026-0501 V2内核 v0.1`。
+- 静态加速实现引用 `PJ2026-0502 静态加速 v0.1`。
+- 稳定需求变化先修改 SPEC，再进入代码或执行 issue。
+- 当前状态、阶段 benchmark、PR 和阻塞统一进入 TaskTree、阶段报告或 GitHub issue。
+- 新增或修改的手写内核源码应在文件头标注：
+  - 适用 SPEC 编号；
+  - 短名；
+  - 实现引用版本。
+- 生成文件、vendored 文件和二进制产物由生成入口追溯 SPEC。
diff --git a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md
new file mode 100644
index 00000000..93bb1c19
--- /dev/null
+++ b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md
@@ -0,0 +1,340 @@
+# PJ2026-0501 V2内核需求规格
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+| v0.1 | 待本版本提交 | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 |
+
+修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
+
+## 正文
+
+## PJ2026-0501 V2内核需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-0501 |
+| 短名 | V2内核 |
+| 层级 | L1 方向 |
+| 规格状态 | 已生效 |
+| 实现引用版本 | v0.1 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义 V2 的预期终态、稳定边界、目标架构、原子需求和验收合同。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+V2 是对 V1 动态 Python 子集路线的全新内核实现。“重写大于优化”表示：
+
+- 保留有价值的用户语义；
+- 保留嵌入式定位和可裁剪能力；
+- 不继承阻碍性能、资源占用或长期演进的 V1 内部架构。
+
+V2 的目标是：
+
+- 从内核第一版开始极致优化运行时性能、Flash 和 RAM；
+- 通过吸收 Lua、MicroPython、QuickJS 和其他成熟 VM 的可验证技术，提高执行内核质量；
+- 在代表性 runtime suite 上大幅超越 V1，并小幅超越可比较配置的 MicroPython；
+- 以明确的 Python 动态语法子集换取紧凑、确定和可裁剪的嵌入式实现；
+- 为 V1 用户提供按能力逐步迁移的后继路线，而不是要求内部二进制兼容。
+
+### 2.2 范围内
+
+- 动态类型 Python 语法子集和模块语义。
+- 可在 PC 预编译、在微控制器直接执行的紧凑字节码。
+- VM dispatch、调用帧、对象表示、名称访问、容器、异常和内存管理。
+- 编译期和构建期的语法、opcode、对象、模块与平台裁剪。
+- C 模块绑定、平台抽象和可预测错误合同。
+- Linux 性能裁决及目标架构功能、Flash 和 RAM 验证。
+
+### 2.3 范围外
+
+- strict type、强制 type hint、静态类型证明或类型驱动的语言准入。
+- LLVM IR、LLVM 后端、JIT 和目标相关 native emitter 作为 V2 内核依赖。
+- 完整 CPython 或 MicroPython 语法兼容。
+- V1 字节码、对象布局、调用栈、ABI 或源码目录结构的内部兼容。
+- 为提升 parser 性能牺牲 runtime 性能或内核资源；parser 可在 PC 端一次性运行。
+- 仅通过 C 模块 binding 替代通用脚本 VM。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 重写优先 | 当热点或资源债务来自内核结构时，重新设计结构优先于围绕旧结构继续局部优化。 |
+| 动态子集 | 不要求静态类型注解，在运行时保持对象类型语义，但只承诺明确列出的 Python 语法和对象能力。 |
+| 快速路径 | 对高频类型和 opcode 使用无堆分配、少分支或专用表示的执行路径。 |
+| 慢速路径 | 处理通用对象、异常、边界转换或低频语义的共享路径。 |
+| 主机预编译 | 在 PC 端完成解析、语义检查和字节码生成，目标设备只加载或执行产物。 |
+| 功能切片 | 可独立启用或移除的一组语法、opcode、对象类型、模块和测试合同。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 嵌入式应用开发者、V1 迁移者、模块开发者和平台移植者。 |
+| 外部输入 | 受支持 Python 源码或 V2 字节码、C 模块、裁剪配置和平台端口。 |
+| 受控资源 | 编译器、字节码、VM 状态、调用帧、对象、堆、模块表和错误状态。 |
+| 外部输出 | 执行结果、异常、停机诊断、静态库或固件、字节码和资源指标。 |
+| 用户接口 | V2 Python 子集、字节码格式、C API、模块绑定和 workspace CLI。 |
+| 系统边界 | V2 定义动态子集内核，不定义静态加速路线、板级驱动或应用业务逻辑。 |
+
+## 5. 目标架构
+
+### 5.1 内部分工
+
+| 编号 | 课题 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- |
+| PJ2026-050101 | 语言编译 | 语法子集、语义检查、常量折叠、字节码生成和产物校验。 | Python 语义需求、裁剪配置。 | VM执行、错误诊断。 |
+| PJ2026-050102 | VM执行 | opcode、dispatch、调用帧、控制流、快速路径和异常转移。 | 字节码合同。 | 对象内存、模块调用。 |
+| PJ2026-050103 | 对象内存 | 值表示、对象布局、字符串驻留、容器、堆和资源耗尽语义。 | VM 生命周期、平台分配器。 | 全部运行时语义。 |
+| PJ2026-050104 | 裁剪移植 | 功能切片、模块绑定、C API、平台抽象和目标构建。 | 语言、VM、对象能力。 | MCU 应用与板级生态。 |
+| PJ2026-050105 | 验证基准 | 语义测试、差分测试、benchmark、Flash、RAM 和回归门禁。 | 各能力切片。 | 发布决策与性能设计。 |
+
+### 5.2 目标架构图
+
+```mermaid
+flowchart LR
+  SRC[Python 动态子集源码] --> C[主机或目标编译器]
+  CFG[功能裁剪配置] --> C
+  C --> BC[紧凑 V2 字节码]
+  BC --> V[验证器与加载器]
+  V --> VM[高效 VM dispatch]
+  VM --> F[高频值快速路径]
+  VM --> O[通用对象慢速路径]
+  VM --> FR[紧凑调用帧]
+  F --> M[受控内存与栈]
+  O --> M
+  FR --> M
+  VM --> MOD[可裁剪模块与 C binding]
+  MOD --> HAL[平台抽象]
+```
+
+### 5.3 编译与执行数据流
+
+```mermaid
+flowchart TD
+  S[源码] --> P[解析与语义校验]
+  P --> IR[轻量内部表示]
+  IR --> OPT[常量折叠与局部优化]
+  OPT --> E[字节码编码]
+  E --> CHECK[格式与能力校验]
+  CHECK --> LOAD[目标加载]
+  LOAD --> RUN[VM执行]
+  RUN --> RESULT[结果或明确错误]
+```
+
+轻量内部表示遵循以下边界：
+
+- 只服务 V2 编译器自身；
+- 不采用 LLVM IR；
+- 不要求静态类型；
+- 编译器可以在 PC 端运行，因此 parser 吞吐不是内核性能优化优先级。
+
+### 5.4 关键执行时序
+
+```mermaid
+sequenceDiagram
+  participant A as 应用
+  participant L as 字节码加载器
+  participant V as V2 VM
+  participant M as 内存与模块
+  A->>L: 提交字节码与能力配置
+  L->>L: 校验版本、边界和所需能力
+  L->>V: 创建紧凑执行帧
+  loop opcode dispatch
+    V->>V: 执行类型快速路径
+    V->>M: 必要时访问对象、堆或模块
+    M-->>V: 值或明确错误
+  end
+  V-->>A: 结果、异常或致命停机诊断
+```
+
+## 6. 原子需求
+
+### 6.1 V2-L1-REQ-001 重写优先架构
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-001 | 重写优先 | PJ2026-050102 VM执行 | PJ2026-050103 对象内存、PJ2026-050105 验证基准 |
+
+V2 不得以复用 V1 内部架构为默认目标。热点处理顺序如下：
+
+- benchmark 识别对象表示、调用帧或 dispatch 热点；
+- profiler 识别名称查找、容器或内存模型热点；
+- 优先重新设计对应结构；
+- 结构问题解除后再评估局部微优化。
+
+结构选择必须满足以下要求：
+
+- 由可重复 benchmark、资源报告和语义测试共同裁决；
+- 吸收先进项目技术前理解其适用前提；
+- 重新实现适合 V2 的机制，不复制许可证不兼容代码；
+- 不因技术来源先进而跳过本项目验证。
+
+### 6.2 V2-L1-REQ-002 动态语言子集
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-002 | 动态子集 | PJ2026-050101 语言编译 | PJ2026-050102 VM执行、PJ2026-050105 验证基准 |
+
+V2 必须支持不带 type hint 的动态 Python 子集。类型注解即使被语法接受，也不得成为执行正确性、性能快速路径或函数准入的必要条件。
+
+语法子集要求如下：
+
+- 兼容性可以弱于 MicroPython；
+- 已承诺子集必须具备明确语义、专属单元测试和稳定错误；
+- 未支持语法必须在编译或加载阶段清晰拒绝；
+- 不得静默降级成错误行为。
+
+### 6.3 V2-L1-REQ-003 高效执行核心
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-003 | 执行核心 | PJ2026-050102 VM执行 | PJ2026-050103 对象内存、PJ2026-050105 验证基准 |
+
+VM 应针对高频动态值建立紧凑表示和快速路径：
+
+- 整数算术、比较和分支避免不必要堆分配；
+- 局部变量访问避免字符串查找；
+- 已优化函数调用避免通用对象分派。
+
+执行结构要求如下：
+
+- opcode、dispatch 和调用帧共同降低有效语义操作的指令数；
+- 热路径减少分支数和内存访问；
+- 可以在保持字节码语义一致的前提下选择适合平台的 dispatch 实现；
+- 不得要求 LLVM、JIT 或 native emitter。
+
+### 6.4 V2-L1-REQ-004 紧凑对象与内存
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-004 | 对象内存 | PJ2026-050103 对象内存 | PJ2026-050102 VM执行、PJ2026-050104 裁剪移植 |
+
+对象和调用状态必须把 32 位微控制器作为一等目标：
+
+- 值表示、对象头和容器使用紧凑布局；
+- 常用不可变值优先使用紧凑立即数；
+- 局部变量和调用状态优先使用栈或帧；
+- 避免把所有值统一提升为堆对象。
+
+内存故障要求如下：
+
+- 分配、回收和资源上限必须可配置、可观测且确定；
+- 普通可恢复错误返回异常；
+- 栈耗尽等致命故障必须报告原因后停机；
+- 停机后不得继续执行受损状态。
+
+### 6.5 V2-L1-REQ-005 分层裁剪
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-005 | 分层裁剪 | PJ2026-050104 裁剪移植 | PJ2026-050101 语言编译、PJ2026-050102 VM执行、PJ2026-050103 对象内存 |
+
+V2 必须延续并强化 V1 的可裁剪能力：
+
+- 裁剪覆盖语法产生、opcode、对象类型和异常；
+- 裁剪覆盖模块、C binding 和平台能力；
+- 未启用功能的代码、只读数据和注册表能够从最终产物中移除。
+
+每个功能切片必须声明依赖、测试和资源变化。裁剪不得产生无法解释的链接失败、静默行为变化或只在完整配置可见的错误诊断。
+
+### 6.6 V2-L1-REQ-006 Runtime 性能优先
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-006 | 性能优先 | PJ2026-050105 验证基准 | PJ2026-050101 语言编译、PJ2026-050102 VM执行、PJ2026-050103 对象内存 |
+
+性能优化顺序如下：
+
+- 先由 benchmark 或 profiler 识别热点；
+- 再针对热点改变实现；
+- runtime 性能优先级远高于 parser 性能；
+- 只有 parser 成为目标设备上重复执行且可测量的主导成本时才优化 parser；
+- 不得以优化 parser 为由增加 VM 热路径成本。
+
+功能、性能和资源分两阶段验收：
+
+- 第一阶段允许有界资源增量验证架构收益；
+- 第二阶段通过同一发布范围内的实现或其他模块补偿总资源；
+- 最终发布配置按整体 Flash 和 RAM 裁决；
+- 资源补偿不要求发生在最初增量位置。
+
+### 6.7 V2-L1-REQ-007 错误和字节码安全
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-007 | 错误安全 | PJ2026-050101 语言编译 | PJ2026-050102 VM执行、PJ2026-050103 对象内存 |
+
+编译器和加载器必须完成以下校验：
+
+- 语法、常量和跳转；
+- 栈或寄存器边界；
+- 能力依赖和字节码版本。
+
+运行时必须区分可恢复异常与致命资源故障，并为两者提供稳定、可测试的可见信息。
+
+非法输入不得导致未报告崩溃、越界执行、静默退出或无诊断循环。致命故障允许停机，但停机前必须输出最小可靠诊断。
+
+## 7. 验收合同
+
+### 7.1 语义验收
+
+- 每个已支持语法、对象和模块能力必须具备 V2 专属单元测试；
+- 测试粒度参考 V1，但不要求继承 V1 测试或内部行为；
+- 不支持能力必须有负向测试，验证明确拒绝和错误可见性；
+- 模块裁剪组合必须验证功能依赖和最终链接结果。
+
+### 7.2 性能验收
+
+- 裁决环境：
+  - Linux 原生执行是唯一性能裁决；
+  - QEMU 只验证功能、Flash 和静态 RAM，不用于性能结论；
+  - 所有实现使用固定版本、相同 workload、可比较功能配置和公开编译参数。
+- 代表性 suite 至少覆盖：
+  - 递归和非递归函数调用；
+  - 整数算术、比较、分支和循环；
+  - 局部变量、全局变量和属性访问；
+  - 字符串、列表、元组和字典的已支持操作；
+  - Python 到 C 模块边界调用；
+  - 异常正常路径和异常抛出路径。
+- 目标门槛：
+  - V2 相对可比较配置 V1 的 suite 几何平均吞吐至少提升 50%；
+  - V2 相对可比较配置 MicroPython 的 suite 几何平均吞吐至少提升 5%；
+  - 单一 workload 不得独立支撑上述结论；
+  - 报告同时披露每项原始值、几何平均、离散度和退化项。
+
+### 7.3 资源验收
+
+- 对每个可比较配置分别报告：
+  - `text` 与只读数据；
+  - 初始化数据和 `bss`；
+  - 峰值堆、峰值 VM 栈和宿主栈；
+  - benchmark 热路径动态分配次数。
+- V2 最小配置和代表性配置均不得超过各自声明的 YAML 资源预算。
+- V2 的可比较配置应满足：
+  - Flash 不高于 V1 同能力配置；
+  - 峰值 RAM 不高于 V1 同能力配置；
+  - 相对 MicroPython 同能力配置的 Flash 或峰值 RAM 若增加超过 5%，必须由同一发布范围内另一资源项的下降补偿，并在报告中披露。
+- 高频整数算术、局部控制流和已优化函数调用路径应保持零堆分配。
+
+### 7.4 可裁剪验收
+
+- 最小、核心和代表性三类配置由 YAML 声明；
+- 禁用功能后，对应 opcode、对象实现、模块表和只读字符串应能从链接产物移除；
+- 配置差异必须能映射到功能、测试和资源差异；
+- 任何裁剪配置均不得把资源耗尽或非法字节码变成静默故障。
+
+## 8. 过程控制
+
+- V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.1` 和文件职责。
+- 自动生成、vendored、配置和二进制产物可不加源码头，但生成器或配置入口必须能追溯本规格。
+- 架构选择必须记录候选方案、适用前提、benchmark 热点和资源影响；当前结果进入 TaskTree 或 issue，不进入 SPEC。
+- 若实现为了兼容 V1 内部结构而违反“重写优先”，必须先更新本规格或作为偏离停止合并。
+- 若后续决定引入 strict type、LLVM、JIT 或 native emitter，应归入独立静态加速规格，不得直接修改 V2 默认路线。
diff --git a/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md b/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md
new file mode 100644
index 00000000..a99a6f5b
--- /dev/null
+++ b/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md
@@ -0,0 +1,116 @@
+# PJ2026-0502 静态加速需求规格
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+| v0.1 | 待本版本提交 | 2026-07-21 | 建立静态加速独立路线边界，隔离 V2 动态内核。 |
+
+修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
+
+## 正文
+
+## PJ2026-0502 静态加速需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-0502 |
+| 短名 | 静态加速 |
+| 层级 | L1 方向 |
+| 规格状态 | 已生效 |
+| 实现引用版本 | v0.1 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) |
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+静态加速路线的边界如下：
+
+- 面向能够显式提供编译期约束的计算代码；
+- 独立研究和交付高性能执行能力；
+- 本规格只定义与 V2 的稳定隔离边界；
+- 具体类型系统、编译 IR、后端和接入方式由后续 L2 SPEC 决策。
+
+### 2.2 范围内
+
+- 显式选择静态执行的函数、模块或文件边界。
+- 静态语义、编译诊断、独立执行产物和动态运行时边界调用。
+- 与 V1、V2、MicroPython native/Viper 和 C binding 的可比较 benchmark。
+
+### 2.3 范围外
+
+- 改变 V2 默认动态语言语义。
+- 要求 V2 使用 type hint、LLVM、JIT 或静态产物。
+- 用静态 workload 的结果证明动态 V2 内核性能。
+- 在没有独立规格和资源验证时选定 LLVM 或其他重型工具链。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 显式选择 | 源码或构建配置清楚声明代码进入静态路线，不由运行时猜测。 |
+| 边界调用 | 动态运行时与静态产物之间的参数、返回值、异常和资源所有权转换。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 需要静态计算性能的嵌入式开发者和自动化构建系统。 |
+| 外部输入 | 显式静态源码、编译约束、目标配置和边界绑定。 |
+| 受控资源 | 静态编译器、执行产物、边界适配和诊断。 |
+| 外部输出 | 静态执行产物、边界调用结果、编译错误和资源报告。 |
+| 用户接口 | 后续 L2 SPEC 定义的显式选择语法和构建入口。 |
+| 系统边界 | 静态路线只接管显式选择代码，不拥有 V2 动态内核。 |
+
+## 5. 路线边界
+
+```mermaid
+flowchart LR
+  SRC[显式静态源码] --> SC[静态编译路线]
+  SC --> ART[独立执行产物]
+  V2[V2 动态内核] <-->|稳定边界调用| ART
+  SC -. 不改变 .-> V2
+```
+
+## 6. 原子需求
+
+### 6.1 STATIC-L1-REQ-001 独立演进
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| STATIC-L1-REQ-001 | 独立演进 | 后续静态编译 L2 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) |
+
+静态路线必须：
+
+- 独立声明语言前提、编译工具链和目标平台；
+- 独立声明资源预算和验收结果；
+- 禁止其依赖进入 V2 最小构建、默认运行时或发布门禁。
+
+### 6.2 STATIC-L1-REQ-002 显式边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| STATIC-L1-REQ-002 | 显式边界 | 后续边界互操作 L2 | [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) |
+
+静态路线的边界调用必须满足：
+
+- 由源码或构建配置显式选择；
+- 明确动态与静态执行之间的值表示和内存所有权；
+- 明确错误传播和调用成本；
+- 不得依赖未声明的运行时猜测。
+
+## 7. 验收合同
+
+- 独立关闭静态路线后，V2 的构建、测试、性能和资源结果保持不变；
+- 静态 benchmark 必须与 Viper、C binding 和适用动态 VM 分开披露语义前提；
+- LLVM、其他 IR 或 native backend 只有在后续 SPEC 明确收益、工具链成本和 MCU 适用边界后才能成为实现选择。
+
+## 8. 过程控制
+
+- 后续实现引用 `PJ2026-0502 静态加速 v0.1` 及相应 L2 SPEC。
+- 静态路线的当前实验、benchmark 和工具链调查进入 TaskTree 或 GitHub issue。
+- 任何影响 V2 默认语义、构建依赖或资源基线的变化必须先回到 [PJ2026-0501 V2内核](PJ2026-0501-v2-kernel.md) 重新评审。

From 0ceecbbf393e34de84625db3cc2593276f7633df Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Tue, 21 Jul 2026 07:11:17 +0200
Subject: [PATCH 2/2] =?UTF-8?q?fix:=20=E5=BB=B6=E9=95=BF=20Sub2API=20?=
 =?UTF-8?q?=E7=9E=AC=E6=80=81=E9=94=99=E8=AF=AF=E5=86=B7=E5=8D=B4=E6=97=B6?=
 =?UTF-8?q?=E9=97=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 config/platform-infra/sub2api-codex-pool.yaml | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/config/platform-infra/sub2api-codex-pool.yaml b/config/platform-infra/sub2api-codex-pool.yaml
index b823a2da..a64d5b20 100644
--- a/config/platform-infra/sub2api-codex-pool.yaml
+++ b/config/platform-infra/sub2api-codex-pool.yaml
@@ -41,32 +41,32 @@ runtime:
             description: 明确命中 Responses input 列表兼容错误或模型容量不足时短时冷却并切换账号。
           - statusCode: 500
             keywords: [failed to validate api key, do request failed, upstream gateway error]
-            durationMinutes: 1
-            description: 上游 API-key 查询依赖、请求传输或网关内部失败时短时冷却当前账号。
+            durationMinutes: 3
+            description: 上游 API-key 查询依赖、请求传输或网关内部失败时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 502
             keywords: [upstream service temporarily unavailable, upstream request failed, service temporarily unavailable, overloaded, concurrency limit exceeded, upstream rate limit exceeded]
-            durationMinutes: 1
-            description: 明确命中 502 上游不可用、过载或并发限制时短时冷却当前账号。
+            durationMinutes: 3
+            description: 明确命中 502 上游不可用、过载或并发限制时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 503
             keywords: [upstream service temporarily unavailable, upstream request failed, service temporarily unavailable, temporarily unavailable, overloaded, concurrency limit exceeded]
-            durationMinutes: 1
-            description: 明确命中 503 上游暂时不可用、过载或并发限制时短时冷却当前账号。
+            durationMinutes: 3
+            description: 明确命中 503 上游暂时不可用、过载或并发限制时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 504
             keywords: [concurrency limit exceeded, upstream service temporarily unavailable, service temporarily unavailable, upstream gateway error, input must be a list]
-            durationMinutes: 1
-            description: 明确命中 504 上游并发限制、暂时不可用、网关错误或 Responses input 列表兼容错误时短时冷却当前账号。
+            durationMinutes: 3
+            description: 明确命中 504 上游并发限制、暂时不可用、网关错误或 Responses input 列表兼容错误时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 522
             keywords: [upstream request failed]
-            durationMinutes: 1
-            description: 明确命中 522 上游连接超时并返回通用失败信息时短时冷却当前账号。
+            durationMinutes: 3
+            description: 明确命中 522 上游连接超时并返回通用失败信息时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 524
             keywords: [upstream request failed, service temporarily unavailable, overloaded, concurrency limit exceeded]
-            durationMinutes: 1
-            description: 明确命中 524 上游不可用、过载或并发限制时短时冷却当前账号。
+            durationMinutes: 3
+            description: 明确命中 524 上游不可用、过载或并发限制时冷却当前账号三分钟，避免未恢复账号过早回池。
           - statusCode: 529
             keywords: [overloaded, api is at capacity, the api is at capacity]
-            durationMinutes: 1
-            description: 明确命中 529 上游过载或容量不足时短时冷却当前账号并切换账号。
+            durationMinutes: 3
+            description: 明确命中 529 上游过载或容量不足时冷却当前账号三分钟并切换账号，避免未恢复账号过早回池。
 
 profit:
   defaultWindow: 24h