Python 3.14 标准库 → OKF 工具链优化机会映射笔记

Python 3.14 标准库 → OKF 工具链优化机会映射笔记#

一句话摘要：本笔记将 python314-stdlib-wiki 六个模块（contextlib / contextvars / sys.monitoring / annotationlib / dataclasses / traceback）的系统学习成果，映射到 okf 工具链（d:\AI\projects\xuanspace\tools\okf）的具体优化机会，明确每项 stdlib 能力在 okf 代码中的落点、优化动作与量化收益预判，并诚实标注「暂无收益明确落点」的模块，避免为凑齐六模块而强行引入无收益改造。

一、六模块 → okf 落点总览#

stdlib 能力

wiki 章节

okf 落点（文件 / 函数）

优化动作

落点类型

contextlib

02-contextlib

context.py 的 Context、harness.py 的 Harness

实现 __enter__/__exit__，__exit__ 调 dispose()；补公开 Harness.dispose()

代码落点

dataclasses

06-dataclasses

models.py/service.py/plugin.py/disposable.py 全部 @dataclass(frozen=True) 类

增加 slots=True（省内存、去 __dict__）；关键字段补 field(doc=...)（3.14 新增）

代码落点

traceback

07-traceback

cli.py、harness.py 失败路径

用 traceback.format_exc() 输出含类型/消息/定位的完整回溯，替代裸 print 与吞异常

代码落点

contextvars

03-contextvars

命名澄清（okf.Context vs contextvars.Context）

无需引入；说明显式依赖注入已取代隐式任务级状态隔离，并记录一条条件性未来落点

诚实记录

annotationlib

05-annotationlib

13 个模块的 from __future__ import annotations

评估 3.14 惰性求值下移除 future import 的风险；结论为「保留」，记录原因与推荐内省入口

诚实记录

sys.monitoring

04-sys-monitoring

无

暂无收益明确的代码落点，记录为条件性未来落点（性能剖析/测试插桩）

诚实记录

二、代码落点三个模块（已落地，有量化基线）#

2.1 dataclasses：slots=True 省内存、field(doc=) 文档化#

  • 事实（06-dataclasses）：slots 参数在 Python 3.10 加入，为数据类生成 __slots__，消除每实例的 __dict__，减少内存占用并加速属性访问；field(doc=...) 是 Python 3.14 新增参数，为字段附加文档字符串，供 dataclasses.fields()、help() 内省。

  • 落点：models.py 的 Concept/Bundle/Source/UsageWindow 等 11 个数据类，service.py 的 ServiceDefinition/ServiceProvider，plugin.py 的 InjectSpec/Plugin，disposable.py 的 Disposable。

  • 优化动作：所有 @dataclass(frozen=True) 增加 slots=True；Concept/Bundle/Source/UsageWindow 的关键字段补 field(doc=...) 一句话平实解释。

  • 量化收益预判：hasattr(instance, "__dict__") 由 True 变 False；实例内存（含 __dict__）显著下降（实测见 13-okf-optimization-report，Concept 344→104 字节、Bundle 344→64 字节）。

2.2 contextlib：上下文管理器协议使资源回收由 with 保证#

  • 事实（02-contextlib）：上下文管理器协议的核心是 __enter__/__exit__ 两个魔术方法，with 语句在进入/退出代码块时自动调用，__exit__ 无论正常结束还是抛异常都会执行，用于确定性资源回收。

  • 落点：context.py 的 Context（服务装配容器）与 harness.py 的 Harness（自举装配器）。

  • 优化动作：Context 增 __enter__/__exit__（__exit__ 调 dispose()），Harness 增公开 dispose()、__enter__/__exit__。原先 Harness 仅内部持有 _ctx、缺公开释放入口，属潜在缺陷；现 with Harness.from_config(...) as h: 退出时自动逆序卸载所有 Fiber、清空服务与效应。

  • 量化收益预判：with 退出后 len(ctx._fibers) == 0 且 len(ctx._store) == 0；harness.dispose() 对已释放实例重复调用幂等安全。

2.3 traceback：结构化错误诊断#

  • 事实（07-traceback）：TracebackException.from_exception(exc) 轻量捕获异常对象（不持帧引用、内存驻留低），traceback.format_exc()/print_exc() 输出含异常类型、消息与逐帧定位（文件名/行号）的完整回溯。

  • 落点：harness.py 的插件装配失败路径（_load_plugins_from_map），cli.py 的命令异常路径。

  • 优化动作：插件导入/实例化抛异常时，输出 Warning: Failed to load plugin ... 后紧跟 traceback.format_exc() 的完整回溯；CLI 关键异常路径同样补充结构化诊断，替代原先吞掉异常的 except Exception。

  • 量化收益预判：诊断从「一行 Warning」升级为「类型 + 消息 + 文件名/行号」完整定位，便于定位插件配置错误。

三、诚实记录落点三个模块（不强行改造）#

3.1 contextvars：命名澄清 + 显式 DI 取舍 + 条件性未来落点#

  • 命名澄清（风险点）：okf 的 Context（okf.context.Context）是服务装配容器 / 能力注册中心，管理插件 Fiber 生命周期与依赖注入；而 contextvars.Context 是并发执行单元的取值映射（PEP 567），管理任务级状态隔离。两者同名「Context」但语义完全不同，属命名冲突风险，需在文档与代码注释中显式区分。

  • 为什么 okf 当前无需 contextvars：okf 用显式依赖注入承载传值——Fiber.inject 声明依赖服务名，运行时通过 Context.get(name) 取出实现，依赖关系显式可见、可追踪。这种显式 DI 已取代「隐式的任务级状态隔离」，无需用 ContextVar 在协程间隐式传播触发源上下文。

  • 条件性未来落点（触发条件 + 方案）：当 Context 的 parallel/异步监听器需要跨协程边界感知触发源 Context 时（当前 _parallel 以同步循环收集结果，不涉及跨任务隐式传值），可在模块级声明 ContextVar，配合 03-contextvars 记录的 3.14 Token/with var.set(...) 语义，在派发入口 set、在监听器内 get 以读取触发上下文。当前不满足触发条件，故不引入。

3.2 annotationlib：3.14 惰性求值 + future import 遗留评估#

  • 事实（05-annotationlib）：3.14 起 PEP 649/749 使注解惰性求值成为默认，annotationlib 提供 get_annotations(..., format=...) 等内省入口，Format 四种取值（VALUE/VALUE_WITH_FAKE_GLOBALS/FORWARDREF/STRING）控制返回形态。

  • okf 现状清单：src/okf 下共 13 个模块使用 from __future__ import annotations（PEP 563 遗留）——context.py/conformance.py/cli.py/frontmatter.py/attested.py/harness.py/links.py/loader.py/models.py/plugin.py/service.py/synthesis.py/trust.py。

  • 移除风险评估与结论（保留）：移除 future import 的收益仅有「消除一行 import」（零性能/内存收益），而风险包括——① 依赖标注中前向引用（如 Concept | None、Context 在 TYPE_CHECKING 分支外标注）在 3.14 惰性求值下的行为需逐模块复核；② 运行时类型提示（TYPE_CHECKING）分支语义可能变化。收益不明确且存在回归风险，判定为「保留 future import」，不冒险移除。

  • 后续推荐入口：若未来需要注解内省，优先用 annotationlib.get_annotations(..., format=...)（PEP 649 原生，惰性求值）而非 typing.get_type_hints()。

3.3 sys.monitoring：暂无收益明确的代码落点#

  • 事实（04-sys-monitoring）：PEP 669 低开销事件监控，三要素为工具 ID（0~5）+ 事件集合 + 回调；set_local_events 可实现局部近零开销；BRANCH_LEFT/BRANCH_RIGHT 于 3.14 新增。它不是可独立 import 的模块。

  • 为何暂无落点：okf 是零运行时依赖的 CLI / 库工具链，负责校验、脚手架、索引/日志合成与信任推导，不在运行时动态收集性能事件或追踪执行流；引入 sys.monitoring 无对应收益。

  • 条件性未来落点：若未来需要为 okf 做低开销性能剖析或测试插桩（如函数级耗时、分支覆盖追踪），可用 sys.monitoring + 局部事件开关（回调返回 DISABLE）实现近零开销的观测，无需侵入改动被测代码。

四、小结#

六模块中，dataclasses、contextlib、traceback 三项有明确且已落地的代码改造（内存、资源管理、诊断三方面可量化提升）；contextvars、annotationlib、sys.monitoring 三项经第一性原理评估后判定当前无收益明确的改造必要，其中 contextvars 记录了命名澄清与条件性未来落点，annotationlib 记录了 future import 保留决策，sys.monitoring 记录了未来剖析场景的落点。所有结论均以「不强行引入无收益改动」为原则，量化对比见 13-okf-optimization-report。