From d72a1f52b1e303898b316113a230fd9148d82c0b Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 08:39:01 +0200 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20=E4=BF=AE=E8=AE=A2=20PikaPython=20?= =?UTF-8?q?=E6=96=B0=E5=86=85=E6=A0=B8=E8=A7=84=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../PJ2026-05/specs/PJ2026-05-pikapython.md | 74 +++-- .../PJ2026-05/specs/PJ2026-0501-v2-kernel.md | 255 +++++++++++++++--- .../specs/PJ2026-0502-static-acceleration.md | 2 +- .../specs/pikapython-capability-profiles.md | 234 ++++++++++++++++ 4 files changed, 510 insertions(+), 55 deletions(-) create mode 100644 project-management/PJ2026-05/specs/pikapython-capability-profiles.md diff --git a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md index e930c96b..6502b9ce 100644 --- a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md +++ b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md @@ -5,9 +5,12 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.1 | 待本版本提交 | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 | +| v0.2 | 待本版本提交 | 2026-07-21 | 待评审：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 +v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟议终态，不改变当前实现合同。 + ## 正文 ## PJ2026-05 PikaPython 总项目需求规格 @@ -20,7 +23,9 @@ | 短名 | PikaPython | | 层级 | L0 总项目 | | 规格状态 | 已生效 | -| 实现引用版本 | v0.1 | +| 当前生效版本 | v0.1 | +| 待评审修订 | v0.2 | +| 实现引用版本 | v0.2（评审通过后生效） | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 @@ -47,10 +52,13 @@ PikaPython 面向资源受限微控制器提供可裁剪的 Python 运行能力 - 重写 V1 路线的动态 Python 子集内核； - 从第一版开始以运行时性能、Flash 和 RAM 为核心设计输入； - 允许语法兼容性弱于 MicroPython； - - 延续并强化 V1 的编译期和构建期裁剪能力。 + - 延续并强化 V1 的编译期和构建期裁剪能力； + - 允许以主机侧、阶段性的 V1 parser 适配器引导前端，但长期合同必须是 V2 中性类型化 IR； + - 使用原子 capability、显式依赖图和命名 profile 组织能力，不把语法能力建模为单一直线等级； + - 每个 profile 独立满足语义、性能和资源合同，较大能力闭包不得掩盖最小配置退化。 - 静态加速路线： - 面向显式静态约束或编译加速场景独立演进； - - 不作为 V2 的依赖、兼容层、发布门禁或架构前提； + - 不作为 V2 的依赖、兼容层、发布判定前提或架构前提； - strict type、LLVM 或其他静态编译技术只能在该路线的独立规格中决策。 ### 2.2 预期终态 @@ -58,9 +66,9 @@ PikaPython 面向资源受限微控制器提供可裁剪的 Python 运行能力 PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： - V1 保持已有用户、语法、模块和板级生态的稳定交付； -- V2 以重新设计的内核显著超越 V1，并在代表性运行时负载上小幅超越同级 MicroPython 配置； +- V2 以重新设计的内核显著超越 V1，并在能力等价的代表性运行时负载上相对 MicroPython 形成可解释的 Pareto 优势； - 静态加速路线面向适合编译期约束的代码提供独立加速能力； -- 两条新路线共享可比较的测试语义、benchmark 方法和板级接口原则，但不共享必须同步演进的内核架构； +- 两条新路线共享 capability 语义、可比较配置、benchmark 方法和板级接口原则，但不共享必须同步演进的内核架构； - 所有路线都能对不支持的语法、资源耗尽和运行时错误给出清晰、确定且可测试的结果。 ### 2.3 范围内 @@ -68,6 +76,7 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： - Python 子集的解析、编译、字节码或其他执行表示。 - VM、对象模型、调用约定、内存管理、异常和模块系统。 - C 模块绑定、平台移植和微控制器资源裁剪。 +- capability 依赖、命名 profile 和跨实现能力等价比较。 - Linux 功能、性能与资源基线，以及目标架构功能和资源验证。 - V1、V2、MicroPython 和适用静态实现的版本化比较。 @@ -78,6 +87,7 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： - 用 QEMU 性能数据替代 Linux 性能裁决。 - 把静态类型、LLVM、JIT 或目标相关 native emitter 设为 V2 必需能力。 - 要求 V2 复用 V1 的内部对象布局、字节码、调用栈或源码架构。 +- 把 V1 parser 或 MicroPython fork 设为 V2 目标运行时的长期依赖。 ## 3. 术语表 @@ -88,7 +98,10 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： | 静态加速 | 依赖显式静态约束或编译期类型事实的独立执行路线。 | | 可裁剪性 | 在构建期按语法、opcode、对象类型、模块和平台能力移除不需要代码与数据的能力。 | | 可比较配置 | 为各实现选择相同 workload 所需语义和模块后的最小可运行配置。 | -| 代表性 suite | 同时覆盖调用、算术、分支、循环、容器、属性、模块和边界调用的版本化 Linux benchmark 集合。 | +| capability | 可独立标识、声明依赖、测试语义和报告资源成本的语言或 runtime 能力。 | +| profile | 有稳定名称和产品意图的 capability 根集合，不表示线性兼容等级。 | +| 能力等价配置 | 所需 capability 闭包和被测语义一致，并只启用 workload 必需平台模块的配置。 | +| 代表性 suite | 覆盖产品 profile 真实使用路径的版本化 benchmark 集合；不等同于单一内核上限测试。 | ## 4. 系统边界和接口 @@ -108,7 +121,13 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： | 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 目标路线关系 +### 5.1 共享规格 + +| 规格编号 | 短名 | 规格文档 | 适用范围 | +| --- | --- | --- | --- | +| PIKA-CAP | 能力配置档 | [PikaPython 能力与配置档](pikapython-capability-profiles.md) | V1、V2、静态加速及后续内核；当前待评审。 | + +### 5.2 目标路线关系 ```mermaid flowchart LR @@ -132,7 +151,7 @@ flowchart LR V2 和静态加速必须保持以下隔离： -- 分别声明语言前提、内核架构、性能结论和发布门禁； +- 分别声明语言前提、内核架构、性能结论和发布适用范围； - 任一路线的实验失败不得阻塞另一条路线； - 任一路线的工具链限制或语法要求不得进入另一条路线。 @@ -157,9 +176,17 @@ V2 和静态加速必须保持以下隔离： 性能主张必须满足以下条件： - 使用版本固定、配置可见、一次性容器运行的 Linux benchmark； -- 同时披露运行时、Flash、静态 RAM 和峰值动态 RAM； -- 同时披露功能配置和统计方法； -- QEMU 不参与性能结论。 +- Linux 原生执行是快速主裁决环境；涉及 MCU 发布主张时，必须在对应真实 Cortex-M 或 RV32 目标上复核； +- QEMU 只用于功能、Flash 和静态 RAM 验证，不参与性能结论； +- benchmark 必须区分内核上限、动态能力等价、产品代表性和静态加速对照四类 suite； +- benchmark 必须区分 cold-start 与 warm execution： + - cold-start 分别报告 runtime 或 root 创建、解析或编译、首次执行和销毁； + - warm execution 的计时区间只包含已加载或已编译程序的重复执行； + - 无法分离生命周期阶段的结果必须标记为不可与 warm execution 直接比较； +- 同时披露运行时、Flash、静态 RAM、峰值堆、VM 栈、宿主栈和动态分配； +- 同时披露功能配置、样本数、原始样本、离散度和统计方法； +- allocation、峰值堆和栈数据必须来自 instrumentation；无法测量时报告 unavailable 和原因，不得以手工零值代替； +- Viper 或其他静态实现只属于静态加速对照，不得作为 V2 动态路线的产品基线。 ### 6.4 PIKA-L0-REQ-004 错误确定性 @@ -173,22 +200,39 @@ V2 和静态加速必须保持以下隔离： - 栈耗尽属于微控制器致命故障时，系统必须先报告清晰原因； - 报告后进入确定停机状态，不得静默继续、无限解析或未报告崩溃。 +### 6.5 PIKA-L0-REQ-005 能力可比性 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| PIKA-L0-REQ-005 | 能力可比性 | [PIKA-CAP 能力配置档](pikapython-capability-profiles.md) | PJ2026-0501、PJ2026-0502 | + +路线和实现之间的比较必须以 capability 闭包为基础： + +- 每个产物声明所需 capability，runtime 声明提供 capability； +- 比较双方必须使用相同的能力闭包、workload 语义和必要平台模块； +- profile 名称不能替代能力清单，也不能暗示未声明的兼容性； +- 能力差异、模块差异和资源预算差异必须在报告中分别披露。 + ## 7. 全局验收合同 - 路线验收： - V2 不依赖 strict type、LLVM、JIT 或静态加速路线产物即可独立构建、测试和发布； - 静态加速路线不得改变 V2 的默认语言语义或资源基线。 - 性能验收： - - Linux 是唯一性能裁决环境； - - 单一 fib、启动时间或 parser 时间不能替代代表性 runtime suite； + - Linux 原生是快速主裁决，真实 Cortex-M 或 RV32 目标用于对应发布主张的确认； + - 单一 fib、启动时间或 parser 时间只能作为内核上限证据，不能替代动态等价和产品代表性 suite； + - MicroPython 的 `+5%` 吞吐只作为延伸目标； + - MicroPython 对照采用能力等价条件下的 Pareto 分析； + - 性能、Flash、峰值 RAM 至少一项明确领先，其余项不得越过本 profile 的资源预算； - 每项结果必须绑定实现版本、提交、编译器、优化级别和可比较配置。 - 资源验收： - - Flash、静态 RAM、峰值动态 RAM和单次 workload 动态分配必须分别披露； + - Flash、静态 RAM、峰值动态 RAM、VM 栈、宿主栈和单次 workload 动态分配必须分别披露； - 资源补偿可以发生在同一发布范围的其他模块，但总配置不得通过隐藏功能差异制造优势。 ## 8. 过程控制 -- V2 内核实现引用 `PJ2026-0501 V2内核 v0.1`。 +- v0.2 评审通过后，V2 内核实现引用 `PJ2026-0501 V2内核 v0.2`；在此之前继续遵循 v0.1 的生效合同。 +- V2 的 capability 和 profile 实现引用 `PIKA-CAP v0.1`，仅在该共享规范生效后将其作为实现合同。 - 静态加速实现引用 `PJ2026-0502 静态加速 v0.1`。 - 稳定需求变化先修改 SPEC，再进入代码或执行 issue。 - 当前状态、阶段 benchmark、PR 和阻塞统一进入 TaskTree、阶段报告或 GitHub issue。 diff --git a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md index 93bb1c19..3a80f88a 100644 --- a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md +++ b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md @@ -5,9 +5,12 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.1 | 待本版本提交 | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 | +| v0.2 | 待本版本提交 | 2026-07-21 | 待评审：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 +v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟议终态，不改变当前实现合同。 + ## 正文 ## PJ2026-0501 V2内核需求规格 @@ -20,7 +23,9 @@ | 短名 | V2内核 | | 层级 | L1 方向 | | 规格状态 | 已生效 | -| 实现引用版本 | v0.1 | +| 当前生效版本 | v0.1 | +| 待评审修订 | v0.2 | +| 实现引用版本 | v0.2（评审通过后生效） | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) | @@ -34,31 +39,37 @@ V2 是对 V1 动态 Python 子集路线的全新内核实现。“重写大于 - 保留有价值的用户语义； - 保留嵌入式定位和可裁剪能力； -- 不继承阻碍性能、资源占用或长期演进的 V1 内部架构。 +- 允许以主机侧、阶段性的 V1 parser 适配器缩短前端引导期； +- 不继承阻碍性能、资源占用或长期演进的 V1 执行内核架构。 V2 的目标是： - 从内核第一版开始极致优化运行时性能、Flash 和 RAM； - 通过吸收 Lua、MicroPython、QuickJS 和其他成熟 VM 的可验证技术，提高执行内核质量； -- 在代表性 runtime suite 上大幅超越 V1，并小幅超越可比较配置的 MicroPython； +- 在能力等价的代表性 runtime suite 上大幅超越 V1，并相对 MicroPython 取得可解释的 Pareto 优势； - 以明确的 Python 动态语法子集换取紧凑、确定和可裁剪的嵌入式实现； - 为 V1 用户提供按能力逐步迁移的后继路线，而不是要求内部二进制兼容。 ### 2.2 范围内 - 动态类型 Python 语法子集和模块语义。 +- 可选、主机侧的 V1 lexer/parser 适配器和可迁移前端测试资产。 - 可在 PC 预编译、在微控制器直接执行的紧凑字节码。 +- 带稳定 ID、显式依赖和命名 profile 的 capability 配置。 - VM dispatch、调用帧、对象表示、名称访问、容器、异常和内存管理。 - 编译期和构建期的语法、opcode、对象、模块与平台裁剪。 - C 模块绑定、平台抽象和可预测错误合同。 -- Linux 性能裁决及目标架构功能、Flash 和 RAM 验证。 +- 实现文件和代码标识符的职责化命名合同。 +- Linux 快速性能裁决及真实 Cortex-M、RV32 目标的功能、性能、Flash 和 RAM 确认。 ### 2.3 范围外 - strict type、强制 type hint、静态类型证明或类型驱动的语言准入。 - LLVM IR、LLVM 后端、JIT 和目标相关 native emitter 作为 V2 内核依赖。 - 完整 CPython 或 MicroPython 语法兼容。 -- V1 字节码、对象布局、调用栈、ABI 或源码目录结构的内部兼容。 +- V1 字节码、对象布局、调用栈、ABI 或 runtime 源码目录结构的内部兼容。 +- 将 V1 parser、V1 runtime 或 MicroPython fork 设为 V2 目标运行时的长期依赖。 +- 由本规格预先固定宽度寄存器 VM、紧凑栈 VM 或字节码编码形态。 - 为提升 parser 性能牺牲 runtime 性能或内核资源；parser 可在 PC 端一次性运行。 - 仅通过 C 模块 binding 替代通用脚本 VM。 @@ -71,7 +82,12 @@ V2 的目标是： | 快速路径 | 对高频类型和 opcode 使用无堆分配、少分支或专用表示的执行路径。 | | 慢速路径 | 处理通用对象、异常、边界转换或低频语义的共享路径。 | | 主机预编译 | 在 PC 端完成解析、语义检查和字节码生成，目标设备只加载或执行产物。 | -| 功能切片 | 可独立启用或移除的一组语法、opcode、对象类型、模块和测试合同。 | +| capability | 可独立标识、声明依赖、测试语义和报告资源成本的语言或 runtime 能力。 | +| profile | 有稳定名称和产品意图的 capability 根集合，不表示线性兼容等级。 | +| V1 前端适配器 | 仅在主机侧把 V1 parser 的输出转换为 V2 中性类型化 IR 的可替换引导组件。 | +| 中性类型化 V2 IR | V2 前端与后端之间版本化、结构节点和操作数类别显式、无 V1 对象和 ABI 依赖的唯一长期合同；不表示静态类型证明。 | +| 能力等价配置 | 所需 capability 闭包、被测语义和必需平台模块一致的比较配置。 | +| 职责化命名 | 文件名和代码标识符表达内核职责、数据语义或生命周期，不携带路线代际缩写。 | ## 4. 系统边界和接口 @@ -94,14 +110,19 @@ V2 的目标是： | PJ2026-050102 | VM执行 | opcode、dispatch、调用帧、控制流、快速路径和异常转移。 | 字节码合同。 | 对象内存、模块调用。 | | PJ2026-050103 | 对象内存 | 值表示、对象布局、字符串驻留、容器、堆和资源耗尽语义。 | VM 生命周期、平台分配器。 | 全部运行时语义。 | | PJ2026-050104 | 裁剪移植 | 功能切片、模块绑定、C API、平台抽象和目标构建。 | 语言、VM、对象能力。 | MCU 应用与板级生态。 | -| PJ2026-050105 | 验证基准 | 语义测试、差分测试、benchmark、Flash、RAM 和回归门禁。 | 各能力切片。 | 发布决策与性能设计。 | +| PJ2026-050105 | 验证基准 | 语义测试、差分测试、benchmark、Flash、RAM 和回归分析。 | 各能力切片。 | 发布决策与性能设计。 | ### 5.2 目标架构图 ```mermaid flowchart LR - SRC[Python 动态子集源码] --> C[主机或目标编译器] - CFG[功能裁剪配置] --> C + SRC[Python 动态子集源码] --> FE[V2 原生前端] + SRC -. 引导期可选 .-> V1A[V1 parser 适配器，仅主机侧] + V1A --> IR[中性类型化 V2 IR] + FE --> IR + CFG[capability 与 profile 配置] --> FE + CFG --> C[V2 优化与字节码生成] + IR --> C C --> BC[紧凑 V2 字节码] BC --> V[验证器与加载器] V --> VM[高效 VM dispatch] @@ -119,24 +140,78 @@ flowchart LR ```mermaid flowchart TD - S[源码] --> P[解析与语义校验] - P --> IR[轻量内部表示] + S[源码] --> P[V2 原生前端或主机侧 V1 parser 适配器] + P --> IR[中性类型化 V2 IR] + CAP[capability 闭包] --> P IR --> OPT[常量折叠与局部优化] OPT --> E[字节码编码] - E --> CHECK[格式与能力校验] + CAP --> E + E --> CHECK[格式和 capability 校验] CHECK --> LOAD[目标加载] LOAD --> RUN[VM执行] RUN --> RESULT[结果或明确错误] ``` -轻量内部表示遵循以下边界： +中性类型化 V2 IR 遵循以下边界： -- 只服务 V2 编译器自身； -- 不采用 LLVM IR； -- 不要求静态类型； +- 只服务 V2 编译器自身，并由版本化 IR 合同定义； +- V1 parser 适配器必须在 IR 边界前终止，V1 的前端容器、对象、VM 状态和 ABI 不得跨越该边界； +- 适配器仅在主机侧使用，目标 runtime 不得依赖 V1 parser、对象、VM、ABI 或模块注册； +- 目标内编译若被支持，必须使用 V2 原生前端； +- 不采用 LLVM IR，也不要求静态类型； - 编译器可以在 PC 端运行，因此 parser 吞吐不是内核性能优化优先级。 -### 5.4 关键执行时序 +### 5.4 capability 与 profile 在 V2 中的应用 + +能力和 profile 的唯一共享合同是 +[PikaPython 能力与配置档](pikapython-capability-profiles.md)。V2 构建必须从命名 profile 或显式 capability 根集合解析依赖闭包。 + +V2 对 capability 的应用必须满足以下要求： + +- 编译器只接受当前 capability 闭包承诺的源码语义； +- 字节码携带所需 capability 清单，runtime 声明提供 capability 清单； +- profile 选择能力和资源预算，不选择独立 VM 或隐含的能力顺序； +- `compute-min` 可用于最小计算和内核上限验证，但不定义其他 profile 的实现继承关系； +- V1 parser 即使能识别更多语法，适配器也必须拒绝未启用 capability； +- 定制 profile 必须显式记录根集合、展开后的闭包和资源预算。 + +### 5.5 单一内核与证据驱动专用化 + +V2 必须以一个共享内核架构作为默认实现，通过 capability 闭包在构建期移除不需要的代码和数据。profile 不得默认选择完整独立的 VM。 + +候选架构包括： + +- 固定宽度寄存器 VM； +- 紧凑栈 VM； +- 变长字节码编码； +- 其他适合目标平台的编码或 dispatch 方案。 + +本规格不预先承诺候选终态。结构选择必须在相同 capability 闭包、相同 workload 和相同资源预算下完成 A/B 验证，并同时比较： + +- 动态能力等价 suite 的吞吐、延迟和离散度； +- Flash、静态 RAM、峰值堆、VM 栈和宿主栈； +- 热路径动态分配、错误路径和实现复杂度； +- 真实 Cortex-M 或 RV32 目标上的对应结果。 + +局部专用化只在上述验证证明有稳定收益时允许，并且必须满足： + +- 专用化仅覆盖已识别的 opcode、值类型、调用路径或对象操作； +- 保持相同 capability 语义、字节码校验和错误合同； +- 未启用 capability 的代码、数据和注册表仍可从最终产物移除； +- 不得以 profile 或单一整数宏选择整套 VM； +- 不得因局部专用化把 V1 或 MicroPython 内部结构带入 V2 runtime。 + +```mermaid +flowchart TD + Y[owning YAML] --> R[capability 依赖解析] + R --> M[版本化 capability 清单] + M --> K[共享 V2 内核] + K --> P[构建期裁剪的目标产物] + B[能力等价 A/B 证据] -. 仅局部热点 .-> S[局部专用实现] + S --> K +``` + +### 5.6 关键执行时序 ```mermaid sequenceDiagram @@ -175,6 +250,7 @@ V2 不得以复用 V1 内部架构为默认目标。热点处理顺序如下： - 由可重复 benchmark、资源报告和语义测试共同裁决； - 吸收先进项目技术前理解其适用前提； - 重新实现适合 V2 的机制，不复制许可证不兼容代码； +- MicroPython 作为架构参考、语义对照和竞争基线，不得被 fork 后作为 V2 内核底座； - 不因技术来源先进而跳过本项目验证。 ### 6.2 V2-L1-REQ-002 动态语言子集 @@ -185,6 +261,16 @@ V2 不得以复用 V1 内部架构为默认目标。热点处理顺序如下： V2 必须支持不带 type hint 的动态 Python 子集。类型注解即使被语法接受，也不得成为执行正确性、性能快速路径或函数准入的必要条件。 +V1 lexer/parser 只能作为可选、阶段性的主机侧引导适配器。复用必须满足以下边界： + +- V1 前端输出必须经适配器归一化为版本化、中性类型化 V2 IR； +- V1 字节码生成、对象、调用栈、ABI、模块注册和 runtime 语义不得作为 V2 后端输入； +- V1 内部数据结构不得跨越 V2 IR 边界； +- V2 的长期发布工具链必须可在不链接 V1 parser 的条件下生成相同 IR 合同； +- 主机预编译配置必须能从目标固件完全移除 parser 和前端只读数据； +- 目标内编译若被支持，必须使用 V2 原生前端，不得引入 V1 runtime 依赖； +- V1 parser 升级不得静默改变 V2 IR、字节码或目标 runtime 语义。 + 语法子集要求如下： - 兼容性可以弱于 MicroPython； @@ -208,7 +294,8 @@ VM 应针对高频动态值建立紧凑表示和快速路径： - opcode、dispatch 和调用帧共同降低有效语义操作的指令数； - 热路径减少分支数和内存访问； -- 可以在保持字节码语义一致的前提下选择适合平台的 dispatch 实现； +- 固定宽度寄存器 VM、紧凑栈 VM、变长编码和其他 dispatch 方案必须以能力等价 A/B 结果选择； +- 可以在保持 capability 语义一致的前提下选择适合平台的 dispatch 实现； - 不得要求 LLVM、JIT 或 native emitter。 ### 6.4 V2-L1-REQ-004 紧凑对象与内存 @@ -239,11 +326,11 @@ VM 应针对高频动态值建立紧凑表示和快速路径： V2 必须延续并强化 V1 的可裁剪能力： -- 裁剪覆盖语法产生、opcode、对象类型和异常； +- 裁剪由 capability 依赖闭包驱动，并覆盖语法产生、opcode、对象类型和异常； - 裁剪覆盖模块、C binding 和平台能力； - 未启用功能的代码、只读数据和注册表能够从最终产物中移除。 -每个功能切片必须声明依赖、测试和资源变化。裁剪不得产生无法解释的链接失败、静默行为变化或只在完整配置可见的错误诊断。 +每个 capability 必须声明依赖、测试和资源变化。裁剪不得产生无法解释的链接失败、静默行为变化或只在完整配置可见的错误诊断。 ### 6.6 V2-L1-REQ-006 Runtime 性能优先 @@ -259,12 +346,12 @@ V2 必须延续并强化 V1 的可裁剪能力： - 只有 parser 成为目标设备上重复执行且可测量的主导成本时才优化 parser； - 不得以优化 parser 为由增加 VM 热路径成本。 -功能、性能和资源分两阶段验收： +性能结果必须按以下 suite 分类，且不得混用结论： -- 第一阶段允许有界资源增量验证架构收益； -- 第二阶段通过同一发布范围内的实现或其他模块补偿总资源； -- 最终发布配置按整体 Flash 和 RAM 裁决； -- 资源补偿不要求发生在最初增量位置。 +- 内核上限 suite：衡量最小 capability 闭包的热点上限，用于候选内核 A/B，不代表完整动态产品性能； +- 动态能力等价 suite：使用相同 capability 闭包和语义，对照 V1 与 MicroPython，是跨动态内核比较的基础； +- 产品代表性 suite：覆盖命名 profile 的调用、容器、属性、模块、C binding 和异常等真实路径，是产品发布结论的基础； +- 静态加速对照：Viper 或其他静态实现仅用于 PJ2026-0502 的独立对照，不参与 V2 动态产品结论。 ### 6.7 V2-L1-REQ-007 错误和字节码安全 @@ -282,11 +369,61 @@ V2 必须延续并强化 V1 的可裁剪能力： 非法输入不得导致未报告崩溃、越界执行、静默退出或无诊断循环。致命故障允许停机，但停机前必须输出最小可靠诊断。 +### 6.8 V2-L1-REQ-008 原子 capability 与 profile + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| V2-L1-REQ-008 | capability 配置 | PJ2026-050101 语言编译 | PJ2026-050102 VM执行、PJ2026-050104 裁剪移植、PJ2026-050105 验证基准 | + +V2 必须遵循 [PIKA-CAP 能力配置档](pikapython-capability-profiles.md) 的原子 capability、显式依赖和命名 profile 合同： + +- 每个已启用 capability 必须有稳定 ID、依赖、语义测试、负向测试和资源报告； +- 编译器从 profile 或显式根集合解析 capability 闭包，并拒绝闭包外源码语义； +- 字节码必须声明所需 capability 清单和格式版本； +- 加载器必须拒绝 runtime 未提供完整 capability 闭包的产物； +- `compute-min`、`control-core`、`embedded-app` 和 `dynamic-full` 是命名 profile，不构成实现成熟度或 VM 选择顺序； +- 定制 profile 必须显式记录根集合、展开后的闭包和资源预算。 + +### 6.9 V2-L1-REQ-009 共享内核与局部专用化 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| V2-L1-REQ-009 | 共享内核 | PJ2026-050102 VM执行 | PJ2026-050101 语言编译、PJ2026-050104 裁剪移植、PJ2026-050105 验证基准 | + +V2 必须以一个共享内核作为默认实现，并由 capability 闭包完成构建期裁剪。该要求贯彻“重写大于优化”： + +- 未启用 capability 的对象、opcode、模块、错误路径和只读数据不得进入最终产物； +- profile 不得选择完整独立 VM，也不得由单一整数宏成为第二配置真相； +- 局部专用化只在能力等价 A/B benchmark 证明有稳定性能或资源收益时允许； +- 专用化不得改变 capability 语义、字节码验证、错误合同或配置可追溯性； +- 固定宽度寄存器 VM、紧凑栈 VM 和混合实现的选择必须记录适用 profile、候选对照和资源影响； +- owning YAML 是 capability、profile 和资源预算的唯一配置事实源。 + +### 6.10 V2-L1-REQ-010 职责化实现命名 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| V2-L1-REQ-010 | 职责化命名 | PJ2026-050102 VM执行 | PJ2026-050101 语言编译、PJ2026-050103 对象内存、PJ2026-050104 裁剪移植、PJ2026-050105 验证基准 | + +V2 作为路线和规格称谓，不得进入实现仓库的文件名或项目自有代码标识符： + +- 文件名、目录内构建 target、函数、变量、类型、枚举、宏和 namespace 必须按职责命名； +- 禁止项按大小写不敏感方式检查，不得通过别名、兼容宏或包装函数保留代际缩写； +- 公开 API 应表达程序、参数、调用方存储、执行结果和运行指标等稳定职责； +- 路线名称可以出现在规格、阶段报告和产品版本元数据中，但不得成为实现结构或 ABI 名称； +- 版本控制内全部实现文件名和项目自有代码标识符必须由自动扫描验证。 + ## 7. 验收合同 ### 7.1 语义验收 -- 每个已支持语法、对象和模块能力必须具备 V2 专属单元测试； +- 每个已支持 capability 必须具备 V2 专属正向、负向和依赖缺失测试； +- 每个命名 profile 必须能确定性展开为完整 capability 闭包； +- V1 parser 测试资产必须映射到明确 capability，不得把全部 V1 语法变成 V2 承诺； +- 相同源码、capability 闭包和编译配置必须产生确定的中性类型化 V2 IR； +- 对共同支持的源码，任意两个已启用前端必须产生语义等价的 V2 IR； +- V1 parser 升级不得静默改变 IR；必要的 IR 变化必须先修改 IR 版本和对应语义测试； +- V2 IR 和目标产物不得包含 V1 对象、VM、ABI 或模块注册依赖； - 测试粒度参考 V1，但不要求继承 V1 测试或内部行为； - 不支持能力必须有负向测试，验证明确拒绝和错误可见性； - 模块裁剪组合必须验证功能依赖和最终链接结果。 @@ -294,21 +431,38 @@ V2 必须延续并强化 V1 的可裁剪能力： ### 7.2 性能验收 - 裁决环境： - - Linux 原生执行是唯一性能裁决； + - Linux 原生执行是快速主裁决环境； + - 涉及 MCU 发布主张时，必须在对应真实 Cortex-M 或 RV32 目标上确认； + - 声称跨 Cortex-M 和 RV32 通用的结论必须分别在至少一个真实目标上确认； - QEMU 只验证功能、Flash 和静态 RAM，不用于性能结论； - - 所有实现使用固定版本、相同 workload、可比较功能配置和公开编译参数。 -- 代表性 suite 至少覆盖： + - 所有实现使用固定版本、相同 workload、能力等价配置和公开编译参数。 +- 生命周期口径： + - cold-start 分别报告 runtime 或 root 创建、parser 或 compile、首次执行和销毁； + - warm execution 在 fixture setup 完成 runtime 或 root 创建及程序编译，在全部 iteration 结束后统一销毁； + - warm iteration 只执行已加载或已编译程序，不得包含 root 创建、销毁、parser 或 compile； + - V1 生命周期修复前后的原始数据必须同时保留，旧数据不得改写为 warm execution； + - 重复执行必须核对结果、错误状态、活跃对象、峰值堆和 teardown 稳定性。 +- suite 分类： + - 内核上限 suite 只裁决候选内核和局部热点，不支撑完整动态产品结论； + - 动态能力等价 suite 对照 V1 与 MicroPython，并绑定完整 capability 闭包； + - 产品代表性 suite 覆盖命名 profile 的真实应用路径； + - Viper 或其他静态实现只进入 PJ2026-0502 静态加速对照。 +- 动态能力等价和产品代表性 suite 合计至少覆盖： - 递归和非递归函数调用； - 整数算术、比较、分支和循环； - 局部变量、全局变量和属性访问； - 字符串、列表、元组和字典的已支持操作； - Python 到 C 模块边界调用； - 异常正常路径和异常抛出路径。 -- 目标门槛： - - V2 相对可比较配置 V1 的 suite 几何平均吞吐至少提升 50%； - - V2 相对可比较配置 MicroPython 的 suite 几何平均吞吐至少提升 5%； +- 比较目标： + - `compute-min` 必须独立满足最小计算闭环的语义、性能和资源预算； + - V2 相对能力等价 V1 的动态能力等价和产品代表性 suite 几何平均吞吐分别至少提升 50%； + - V2 相对能力等价 MicroPython 必须形成预算约束下的 Pareto 优势； + - 性能、Flash 和峰值 RAM 至少一项明确领先 MicroPython，其余项不得越过对应 profile 预算； + - 领先幅度必须大于预先声明的测量噪声或置信区间； + - 相对 MicroPython 的 suite 几何平均吞吐提升 5% 仅作为延伸目标，不作为第一阶段完成条件； - 单一 workload 不得独立支撑上述结论； - - 报告同时披露每项原始值、几何平均、离散度和退化项。 + - 报告同时披露每项原始值、样本数、median、p95、标准差、变异系数、几何平均和退化项。 ### 7.3 资源验收 @@ -317,24 +471,47 @@ V2 必须延续并强化 V1 的可裁剪能力： - 初始化数据和 `bss`； - 峰值堆、峰值 VM 栈和宿主栈； - benchmark 热路径动态分配次数。 -- V2 最小配置和代表性配置均不得超过各自声明的 YAML 资源预算。 +- 资源指标必须来自 allocator、执行存储水位、栈水位或等价 instrumentation；无法测量的字段必须报告 unavailable 和原因，不得填写推测值或手工零值。 +- 每个命名或定制 profile 均不得超过 owning YAML 声明的资源预算。 - V2 的可比较配置应满足： - Flash 不高于 V1 同能力配置； - 峰值 RAM 不高于 V1 同能力配置； - - 相对 MicroPython 同能力配置的 Flash 或峰值 RAM 若增加超过 5%，必须由同一发布范围内另一资源项的下降补偿，并在报告中披露。 -- 高频整数算术、局部控制流和已优化函数调用路径应保持零堆分配。 + - 相对 MicroPython 的性能、Flash 和峰值 RAM 按 7.2 的预算约束做 Pareto 分析。 +- 高频整数算术、局部控制流和已优化函数调用路径应保持零堆分配；该结论必须由分配器计数或等价 trace 证明，不得使用手工源码计数代替。 +- 宿主 C 栈或目标栈上的帧、寄存器数组和临时缓冲必须单独计入峰值栈，不得因“零堆分配”而省略。 +- 构建产物必须证明只链接 capability 闭包需要的 opcode、对象、模块和辅助路径。 ### 7.4 可裁剪验收 -- 最小、核心和代表性三类配置由 YAML 声明； +- `config/pikapython-capabilities.yaml` 是 capability、profile、依赖和资源预算的目标事实源； +- 构建生成的 capability 清单和细粒度编译开关不得成为第二配置真相； +- 命名 profile 和定制 profile 均必须显式解析完整 capability 闭包； +- 主机预编译的目标配置必须能够完全移除 lexer/parser 代码和前端只读数据； +- 目标 runtime 和固件不得链接 V1 parser、对象、VM、ABI 或模块注册实现； - 禁用功能后，对应 opcode、对象实现、模块表和只读字符串应能从链接产物移除； - 配置差异必须能映射到功能、测试和资源差异； - 任何裁剪配置均不得把资源耗尽或非法字节码变成静默故障。 +### 7.5 内核结构验收 + +- 固定宽度寄存器 VM、紧凑栈 VM、变长编码或混合候选必须使用相同 capability 闭包、IR 语义、workload 和编译条件比较； +- 候选结论必须同时包含 Linux、对应真实目标、Flash、RAM、栈和动态分配证据； +- 单一 fib 或其他内核上限 workload 不得独立决定产品内核结构； +- profile 默认使用共享 V2 内核，完整 profile 专用 VM 不得作为无证据的预设架构； +- 局部专用实现只有在收益超出测量噪声、未违反 profile 预算且语义回归全部通过时才可进入默认构建。 + +### 7.6 实现命名验收 + +- 扫描版本控制内全部实现文件名，按大小写不敏感方式确认不存在路线代际缩写； +- 对 C、C++、CMake 和项目脚本执行标识符级扫描，并输出命中的路径、行和标识符； +- 公开头文件、链接符号、构建 target 和测试 fixture 不得保留兼容别名； +- 第三方依赖必须位于明确的 vendored 边界，其上游标识符不构成本项目公开 API。 + ## 8. 过程控制 -- V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.1` 和文件职责。 +- v0.2 评审生效后，V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.2` 和文件职责。 - 自动生成、vendored、配置和二进制产物可不加源码头，但生成器或配置入口必须能追溯本规格。 - 架构选择必须记录候选方案、适用前提、benchmark 热点和资源影响；当前结果进入 TaskTree 或 issue，不进入 SPEC。 -- 若实现为了兼容 V1 内部结构而违反“重写优先”，必须先更新本规格或作为偏离停止合并。 +- 任何实现若让 V1 内部结构越过中性类型化 V2 IR 边界，必须先更新本规格或作为偏离停止合并。 +- PIKA-CAP 生效前，capability 和 profile 条款只用于评审，不改变当前实现合同。 - 若后续决定引入 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 index a99a6f5b..29fb583c 100644 --- a/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md +++ b/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md @@ -88,7 +88,7 @@ flowchart LR - 独立声明语言前提、编译工具链和目标平台； - 独立声明资源预算和验收结果； -- 禁止其依赖进入 V2 最小构建、默认运行时或发布门禁。 +- 禁止其依赖进入 V2 最小构建、默认运行时或发布判定前提。 ### 6.2 STATIC-L1-REQ-002 显式边界 diff --git a/project-management/PJ2026-05/specs/pikapython-capability-profiles.md b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md new file mode 100644 index 00000000..4ba74acd --- /dev/null +++ b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md @@ -0,0 +1,234 @@ +# PIKA-CAP PikaPython 能力与配置档规范 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | +| v0.1 | 待本版本提交 | 2026-07-21 | 待评审：建立原子 capability、显式依赖图和命名 profile 合同。 | + +修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 + +## 正文 + +## PIKA-CAP PikaPython 能力与配置档规范 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PIKA-CAP | +| 短名 | 能力配置档 | +| 层级 | L0 共享规范 | +| 规格状态 | 未生效 | +| 实现引用版本 | v0.1（待评审） | +| 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | + +## 2. 目的和范围 + +### 2.1 目的 + +本规范为 PikaPython 各内核和执行路线提供统一的能力描述方法： + +- 使用稳定、可独立寻址的 capability ID 表达语言和 runtime 能力； +- 使用显式依赖图计算一次构建或字节码产物需要的能力闭包； +- 使用命名 profile 聚合常见产品配置，但不把 profile 建模为线性兼容等级； +- 使用相同能力闭包约束语义测试、资源报告和跨实现比较。 + +capability 描述对外语义和可裁剪单元，不规定 parser、IR、字节码、对象布局、调用帧或 VM 的内部实现。 + +### 2.2 范围内 + +- Python 动态子集及其最小 runtime 语义依赖。 +- capability ID、依赖、冲突、裁剪和拒绝语义。 +- 命名 profile、定制 profile 和能力清单。 +- 编译器、字节码、加载器、测试和资源报告中的能力标识。 + +### 2.3 范围外 + +- 用单一数字表示实现成熟度、兼容程度或性能等级。 +- 规定某条路线必须实现全部 capability。 +- 要求不同 profile 使用不同 VM、字节码或对象模型。 +- 用 profile 名称代替 CPython、MicroPython 或 V1 的逐项兼容性测试。 +- 自动承诺未在 capability 语义中明确列出的语言行为。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| capability | 可独立标识、声明依赖、测试语义和报告资源成本的语言或 runtime 能力。 | +| 依赖闭包 | 从选中 capability 出发递归展开全部必需依赖后得到的完整能力集合。 | +| profile | 有稳定名称和产品意图的 capability 根集合；profile 之间不存在隐含顺序。 | +| 定制 profile | 由产品或应用显式选择 capability 根集合形成的构建配置。 | +| 提供能力清单 | runtime 或固件声明能够执行的完整 capability 集合。 | +| 所需能力清单 | 字节码或其他执行产物声明正确执行所必需的完整 capability 集合。 | +| 能力等价配置 | 所需能力闭包和被测语义一致，并只启用 workload 必需平台模块的配置。 | + +“原子”表示 capability 在配置、依赖、测试和报告中可独立寻址，不要求每个 capability 都由单独源码文件或 opcode 实现。 + +## 4. 初始 capability 目录 + +下表定义首批稳定 ID。依赖列为空表示该 capability 不依赖其他语言 capability，但仍受平台和资源预算约束。 + +| capability ID | 语义边界 | 直接依赖 | +| --- | --- | --- | +| `exec.module` | 模块入口、常量装载和顺序执行。 | 无 | +| `value.int` | 有符号整数值及其稳定溢出语义。 | `exec.module` | +| `value.bool` | 布尔值和布尔结果。 | `exec.module` | +| `value.none` | `None` 单例值。 | `exec.module` | +| `value.float` | 浮点值和目标配置声明的浮点语义。 | `exec.module` | +| `value.string` | 字符串构造、比较和基础只读操作。 | `exec.module` | +| `value.bytes` | 字节序列构造、比较和基础只读操作。 | `exec.module` | +| `name.local` | 局部变量绑定和 slot 访问。 | `exec.module` | +| `name.global` | 模块全局名称绑定和访问。 | `exec.module` | +| `op.integer` | 整数算术和比较。 | `value.int` | +| `op.float` | 浮点算术和比较。 | `value.float` | +| `protocol.truth` | 对全部已启用值类型执行真值判断。 | `value.bool` | +| `flow.branch` | 条件分支。 | `protocol.truth` | +| `flow.loop` | `while`、`break` 和 `continue`。 | `flow.branch` | +| `logic.short-circuit` | `and`、`or` 和 `not` 的短路语义。 | `flow.branch` | +| `call.positional` | 位置参数函数、调用、返回和递归。 | `name.local` | +| `call.defaults` | 默认参数绑定。 | `call.positional` | +| `call.keyword` | 关键字参数绑定。 | `call.positional` | +| `call.variadic` | `*args` 和 `**kwargs` 参数绑定。 | `call.positional`、`container.tuple`、`container.dict` | +| `iter.range` | `for`、`range` 和最小内部迭代协议。 | `flow.loop`、`value.int` | +| `container.tuple` | tuple、索引和迭代。 | `exec.module` | +| `container.list` | list、索引、迭代和基础变更。 | `exec.module` | +| `container.dict` | dict、键查找、迭代和基础变更。 | `exec.module` | +| `module.import` | 模块命名空间和 `import`。 | `name.global` | +| `binding.c` | Python 到 C 模块的基础调用。 | `module.import`、`call.positional` | +| `object.attribute` | 属性读取、写入和绑定方法。 | `name.global`、`call.positional` | +| `object.class` | `class`、实例构造、实例字段和基础继承。 | `object.attribute` | +| `exception.basic` | `raise`、`try` 和 `except`。 | `exec.module` | +| `exception.finally` | `finally` 和异常展开清理。 | `exception.basic` | +| `protocol.context` | 基础上下文管理协议。 | `exception.finally`、`object.attribute` | +| `closure.cell` | lambda、闭包和 `nonlocal`。 | `call.positional` | +| `iterator.user` | 用户对象迭代协议。 | `flow.loop`、`object.attribute` | +| `generator.basic` | `yield`、可暂停帧和生成器迭代。 | `iterator.user`、`call.positional` | +| `comprehension.basic` | 基础列表、字典和生成器推导。 | `flow.loop`、`closure.cell`、`container.list`、`container.dict`、`generator.basic` | +| `async.basic` | 目标版本明确承诺的基础异步语法和调度语义。 | `generator.basic`、`exception.basic`、`module.import` | + +新增 capability 必须使用新的语义 ID。既有 ID 不得被复用为不兼容语义；删除能力时保留 ID 并标记废弃。 + +## 5. 依赖与 profile 合同 + +### 5.1 依赖解析 + +能力解析必须满足以下条件： + +- 输入是命名 profile 或显式 capability 根集合； +- 输出是去重、稳定排序且可序列化的依赖闭包； +- 缺失依赖、未知 ID、循环依赖和显式冲突必须在构建或编译阶段拒绝； +- parser 能识别某个语法节点，不代表对应 capability 已启用； +- 未启用能力必须产生稳定的 unsupported-capability 诊断或等价错误。 + +依赖闭包约束语义和产物兼容，不要求实现按 capability 拆成运行时分支。 + +### 5.2 命名 profile + +命名 profile 是常见产品配置，不是从低到高的兼容等级。 + +| profile | 产品意图 | +| --- | --- | +| `compute-min` | 最小整数计算、分支和函数调用。 | +| `control-core` | 小型控制逻辑、循环和短路表达式。 | +| `embedded-app` | 常见嵌入式脚本、容器、模块和 C 扩展。 | +| `dynamic-full` | V2 承诺的广义动态语言能力，不表示 MicroPython 全兼容。 | + +profile 根集合如下： + +- `compute-min`： + - `op.integer`； + - `flow.branch`； + - `call.positional`。 +- `control-core`： + - `value.none`； + - `op.integer`； + - `logic.short-circuit`； + - `iter.range`； + - `call.positional`。 +- `embedded-app`： + - `value.none`； + - `op.integer`； + - `op.float`； + - `value.string`； + - `value.bytes`； + - `logic.short-circuit`； + - `container.tuple`； + - `container.list`； + - `container.dict`； + - `iter.range`； + - `module.import`； + - `binding.c`； + - `exception.basic`。 +- `dynamic-full`： + - `embedded-app` 的全部根 capability； + - `object.class`； + - `call.defaults`； + - `call.keyword`； + - `call.variadic`； + - `exception.finally`； + - `protocol.context`； + - `closure.cell`； + - `iterator.user`； + - `generator.basic`； + - `comprehension.basic`； + - `async.basic`。 + +profile 合同如下： + +- profile 名称稳定，但可通过规格修订改变其根集合； +- profile 是否包含另一个 profile 只能由展开后的能力集合判断； +- runtime、编译器和加载器不得根据 profile 名称推断未声明能力； +- 产品可以声明定制 profile，但必须记录完整根集合、依赖闭包和资源预算； +- 同名 profile 在不同路线中必须保持语义等价，内部实现可以不同。 + +### 5.3 产物与加载 + +- 编译产物必须携带 capability schema 版本和所需能力清单； +- runtime 必须携带 capability schema 版本和提供能力清单； +- 仅当所需能力集合是提供能力集合的子集时，加载器才可执行产物； +- 字节码格式版本与 capability schema 版本分别演进，不得互相替代； +- 主机预编译和目标内编译必须使用相同 capability 语义； +- 未知 capability 或语义版本不匹配必须明确拒绝。 + +### 5.4 实现边界 + +- V2 默认使用一个共享内核架构实现全部已支持 profile； +- 构建期根据能力闭包移除未启用 opcode、对象、模块、错误路径和只读数据； +- profile 不得默认选择一套完全独立的 VM； +- 只有能力等价的 A/B benchmark 证明存在稳定收益时，才允许为局部热点提供专用实现； +- 局部专用实现必须保持相同 capability 语义、产物校验和错误合同； +- V1、静态加速和后续内核可以独立实现相同 capability，不继承 V2 内部结构。 + +## 6. 路线应用 + +- V1： + - 通过兼容性映射声明已交付行为对应的 capability； + - 不要求为遵循本规范重写 parser 或 runtime。 +- V2： + - 使用 capability 依赖图驱动前端拒绝、字节码清单、runtime 裁剪和测试选择； + - 使用一个共享内核作为默认实现，不按 profile 完整重写 VM； + - 可通过主机侧 V1 parser 适配器引导前端，但不得让 V1 内部类型进入 V2 IR 或目标 runtime。 +- 静态加速： + - 声明接受的 capability 输入范围； + - 静态约束属于独立合同，不改变 capability 的动态语义； + - Viper 或其他静态执行结果只用于静态路线对照。 + +## 7. 验收合同 + +- 每个 capability 必须有正向语义测试、禁用时的负向测试和依赖缺失测试； +- 每个命名 profile 必须能确定性展开为完整能力闭包； +- 编译器必须拒绝使用未启用 capability 的源码； +- 加载器必须拒绝所需能力不属于 runtime 提供能力的产物； +- 资源报告必须绑定 capability 闭包，并分别披露 Flash、静态 RAM、峰值堆、VM 栈、宿主栈和动态分配； +- 跨 V1、V2 和 MicroPython 的产品比较必须使用能力等价配置； +- profile 名称相同但能力闭包不同的结果不得声明为可比较。 + +## 8. 过程控制 + +- capability 和 profile 的目标事实源为 `config/pikapython-capabilities.yaml`； +- SPEC 定义稳定语义和验收合同，owning YAML 定义启用状态、依赖映射、profile 根集合和资源预算； +- 本规范评审生效前只用于评审，不改变 V1、V2 或静态路线的当前实现合同； +- 当前实现进度、benchmark 数值和一次性差异证据进入 TaskTree、阶段报告或 GitHub issue； +- 改变 capability 语义、依赖或命名 profile 合同时必须先修订本规范。 From 99b7017d3361d4f45c979c1285e3cd39999301d9 Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 08:41:59 +0200 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20PikaPython=20?= =?UTF-8?q?=E8=A7=84=E6=A0=BC=E7=89=88=E6=9C=AC=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- project-management/PJ2026-05/specs/PJ2026-05-pikapython.md | 4 ++-- project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md | 4 ++-- .../PJ2026-05/specs/PJ2026-0502-static-acceleration.md | 2 +- .../PJ2026-05/specs/pikapython-capability-profiles.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md index 6502b9ce..73d6185a 100644 --- a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md +++ b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md @@ -4,8 +4,8 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待本版本提交 | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 | -| v0.2 | 待本版本提交 | 2026-07-21 | 待评审：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 | +| v0.1 | `205e3a70` | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 | +| v0.2 | `d72a1f52` | 2026-07-21 | 待评审：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 diff --git a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md index 3a80f88a..59a62a8c 100644 --- a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md +++ b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md @@ -4,8 +4,8 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待本版本提交 | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 | -| v0.2 | 待本版本提交 | 2026-07-21 | 待评审：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 | +| v0.1 | `205e3a70` | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 | +| v0.2 | `d72a1f52` | 2026-07-21 | 待评审：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 diff --git a/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md b/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md index 29fb583c..1058df61 100644 --- a/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md +++ b/project-management/PJ2026-05/specs/PJ2026-0502-static-acceleration.md @@ -4,7 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待本版本提交 | 2026-07-21 | 建立静态加速独立路线边界，隔离 V2 动态内核。 | +| v0.1 | `d72a1f52` | 2026-07-21 | 建立静态加速独立路线边界，隔离 V2 动态内核。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 diff --git a/project-management/PJ2026-05/specs/pikapython-capability-profiles.md b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md index 4ba74acd..7d0a2f15 100644 --- a/project-management/PJ2026-05/specs/pikapython-capability-profiles.md +++ b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md @@ -4,7 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待本版本提交 | 2026-07-21 | 待评审：建立原子 capability、显式依赖图和命名 profile 合同。 | +| v0.1 | `d72a1f52` | 2026-07-21 | 待评审：建立原子 capability、显式依赖图和命名 profile 合同。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 From 45e9456ea6e2af1b0bbaa50b98e133164cde53be Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 09:02:15 +0200 Subject: [PATCH 3/3] docs: activate PikaPython kernel specs --- .../PJ2026-05/specs/PJ2026-05-pikapython.md | 15 +++++++-------- .../PJ2026-05/specs/PJ2026-0501-v2-kernel.md | 13 ++++++------- .../specs/pikapython-capability-profiles.md | 8 ++++---- 3 files changed, 17 insertions(+), 19 deletions(-) diff --git a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md index 73d6185a..9974a245 100644 --- a/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md +++ b/project-management/PJ2026-05/specs/PJ2026-05-pikapython.md @@ -5,11 +5,11 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.1 | `205e3a70` | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 | -| v0.2 | `d72a1f52` | 2026-07-21 | 待评审：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 | +| v0.2 | `d72a1f52` | 2026-07-21 | 已批准：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 -v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟议终态，不改变当前实现合同。 +v0.2 及其引用的 PIKA-CAP v0.1 已批准生效，作为当前实现合同。 ## 正文 @@ -23,9 +23,8 @@ v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟 | 短名 | PikaPython | | 层级 | L0 总项目 | | 规格状态 | 已生效 | -| 当前生效版本 | v0.1 | -| 待评审修订 | v0.2 | -| 实现引用版本 | v0.2（评审通过后生效） | +| 当前生效版本 | v0.2 | +| 实现引用版本 | v0.2 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 @@ -125,7 +124,7 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族： | 规格编号 | 短名 | 规格文档 | 适用范围 | | --- | --- | --- | --- | -| PIKA-CAP | 能力配置档 | [PikaPython 能力与配置档](pikapython-capability-profiles.md) | V1、V2、静态加速及后续内核；当前待评审。 | +| PIKA-CAP | 能力配置档 | [PikaPython 能力与配置档](pikapython-capability-profiles.md) | V1、V2、静态加速及后续内核。 | ### 5.2 目标路线关系 @@ -231,8 +230,8 @@ V2 和静态加速必须保持以下隔离： ## 8. 过程控制 -- v0.2 评审通过后，V2 内核实现引用 `PJ2026-0501 V2内核 v0.2`；在此之前继续遵循 v0.1 的生效合同。 -- V2 的 capability 和 profile 实现引用 `PIKA-CAP v0.1`，仅在该共享规范生效后将其作为实现合同。 +- V2 内核实现引用 `PJ2026-0501 V2内核 v0.2`。 +- V2 的 capability 和 profile 实现引用 `PIKA-CAP v0.1`。 - 静态加速实现引用 `PJ2026-0502 静态加速 v0.1`。 - 稳定需求变化先修改 SPEC，再进入代码或执行 issue。 - 当前状态、阶段 benchmark、PR 和阻塞统一进入 TaskTree、阶段报告或 GitHub issue。 diff --git a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md index 59a62a8c..7d73f7c8 100644 --- a/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md +++ b/project-management/PJ2026-05/specs/PJ2026-0501-v2-kernel.md @@ -5,11 +5,11 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.1 | `205e3a70` | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 | -| v0.2 | `d72a1f52` | 2026-07-21 | 待评审：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 | +| v0.2 | `d72a1f52` | 2026-07-21 | 已批准：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 -v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟议终态，不改变当前实现合同。 +v0.2 及其引用的 PIKA-CAP v0.1 已批准生效，作为当前实现合同。 ## 正文 @@ -23,9 +23,8 @@ v0.1 继续生效。v0.2 及其引用的 PIKA-CAP 在评审通过前只表示拟 | 短名 | V2内核 | | 层级 | L1 方向 | | 规格状态 | 已生效 | -| 当前生效版本 | v0.1 | -| 待评审修订 | v0.2 | -| 实现引用版本 | v0.2（评审通过后生效） | +| 当前生效版本 | v0.2 | +| 实现引用版本 | v0.2 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) | @@ -509,9 +508,9 @@ V2 作为路线和规格称谓，不得进入实现仓库的文件名或项目 ## 8. 过程控制 -- v0.2 评审生效后，V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.2` 和文件职责。 +- V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.2` 和文件职责。 - 自动生成、vendored、配置和二进制产物可不加源码头，但生成器或配置入口必须能追溯本规格。 - 架构选择必须记录候选方案、适用前提、benchmark 热点和资源影响；当前结果进入 TaskTree 或 issue，不进入 SPEC。 - 任何实现若让 V1 内部结构越过中性类型化 V2 IR 边界，必须先更新本规格或作为偏离停止合并。 -- PIKA-CAP 生效前，capability 和 profile 条款只用于评审，不改变当前实现合同。 +- capability 和 profile 实现引用 `PIKA-CAP v0.1`。 - 若后续决定引入 strict type、LLVM、JIT 或 native emitter，应归入独立静态加速规格，不得直接修改 V2 默认路线。 diff --git a/project-management/PJ2026-05/specs/pikapython-capability-profiles.md b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md index 7d0a2f15..e44f07c1 100644 --- a/project-management/PJ2026-05/specs/pikapython-capability-profiles.md +++ b/project-management/PJ2026-05/specs/pikapython-capability-profiles.md @@ -4,7 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | `d72a1f52` | 2026-07-21 | 待评审：建立原子 capability、显式依赖图和命名 profile 合同。 | +| v0.1 | `d72a1f52` | 2026-07-21 | 已批准：建立原子 capability、显式依赖图和命名 profile 合同。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 @@ -19,8 +19,8 @@ | 编号 | PIKA-CAP | | 短名 | 能力配置档 | | 层级 | L0 共享规范 | -| 规格状态 | 未生效 | -| 实现引用版本 | v0.1（待评审） | +| 规格状态 | 已生效 | +| 实现引用版本 | v0.1 | | 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | @@ -229,6 +229,6 @@ profile 合同如下： - capability 和 profile 的目标事实源为 `config/pikapython-capabilities.yaml`； - SPEC 定义稳定语义和验收合同，owning YAML 定义启用状态、依赖映射、profile 根集合和资源预算； -- 本规范评审生效前只用于评审，不改变 V1、V2 或静态路线的当前实现合同； +- V1、V2 和静态路线按各自适用范围引用本规范； - 当前实现进度、benchmark 数值和一次性差异证据进入 TaskTree、阶段报告或 GitHub issue； - 改变 capability 语义、依赖或命名 profile 合同时必须先修订本规范。