mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into feat/nc01-registry-retention-gc

Browse Source
This commit is contained in:
pikastech
2026-07-21 07:20:33 +02:00
parent 03c96bec19 57e870fe0d
commit fbdef32efc
4 changed files with 669 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
config/platform-infra/sub2api-codex-pool.yaml
+14 -14
View File
@@ -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
project-management/PJ2026-05/specs/PJ2026-05-pikapython.md
+199
View File
@@ -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。
project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md
+340
View File
@@ -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 默认路线。
project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md
+116
View File
@@ -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) 重新评审。