progressive-loading

渐进式加载模式

概述

渐进式加载提供了一套标准模式，用于构建可根据上下文、用户意图和可用 token 预算动态加载模块的技能。这可以避免加载不必要的内容，同时确保在需要时具备所需功能。

核心原则：从最少内容开始，智能扩展，持续监控。

适用场景

在以下情况下使用渐进式加载：

• 涵盖多个不同工作流或领域
• 需要高效管理上下文窗口
• 模块会根据上下文互斥
• 长时间运行的会话需要符合 MECW 要求
• 希望优化常见路径，同时支持边缘情况

不适用场景

• 项目未使用 leyline 基础设施模式
• 不需要服务架构的简单脚本

快速开始

基本 Hub 模式

## Progressive Loading

**Context A**: Load `modules/loading-patterns.md` for scenario A
**Context B**: Load `modules/selection-strategies.md` for scenario B

**Always Available**: Core utilities, exit criteria, integration points

验证： 运行带有 --help 标志的命令，以验证其是否可用。

基于上下文进行选择

在技能的 YAML frontmatter 中声明模块，并使用 @modules/ 指令按需加载。Hub 读取 检测到的上下文，然后只加载匹配的模块：

---
modules:
- modules/git-catchup-patterns.md
- modules/python-testing.md
---

When the intent is a branch or PR catch-up, load
`@modules/git-catchup-patterns.md`. When the artifacts include
Python tests, also load `@modules/python-testing.md`.

为使加载量符合 MECW token 预算，请在引入模块前 确认其是否适配。plugins/leyline/src/leyline/mecw.py 中的 MECWMonitor 提供了此处使用的方法：

from leyline.mecw import MECWMonitor

monitor = MECWMonitor()
monitor.track_usage(current_context_tokens)

# module_estimated_tokens comes from the module frontmatter
can_load, reasons = monitor.can_handle_additional(module_estimated_tokens)

仅当 can_load 为 true 时才加载下一个模块。每个 模块都会在其 frontmatter 的 estimated_tokens 字段中记录成本。

Hub-and-Spoke 架构

Hub 的职责

1. 上下文检测：识别用户意图、产物和工作流类型
2. 模块选择：根据上下文选择要加载的模块
3. 预算管理：加载前验证是否符合 MECW 要求
4. 集成协调：提供与其他技能的集成点
5. 退出条件：定义所有路径的完成标准

Spoke 的特征

1. 单一职责：每个模块只服务于一种工作流或领域
2. 自包含：模块之间不相互依赖
3. 标注上下文：明确指出模块适用的场景
4. 设定 token 预算：明确 token 成本，以便做出选择
5. 可独立测试：可以单独评估

选择策略

详细策略请参阅 modules/selection-strategies.md：

• 基于意图：根据检测到的用户目标加载
• 基于产物：根据检测到的文件或系统加载
• 考虑预算：在可用 token 预算内加载
• 渐进式：先加载核心内容，再按需扩展
• 互斥式：从多个选项中加载一条路径

加载模式

实现模式请参阅 modules/loading-patterns.md：

• 条件引入：动态模块引用
• 延迟加载：首次使用时加载
• 分层披露：核心 → 常见场景 → 边缘情况
• 上下文切换：在会话中途更改已加载的模块
• 主动卸载：资源紧张时移除未使用的模块

常见用例

• 多领域技能：imbue:catchup 根据上下文加载 git、docs、logs 模块
• 上下文密集型分析：只加载相关模块，推迟深度分析，并卸载已完成的模块
• 插件基础设施：搭配使用基础设施模块，并进行版本检查

最佳实践

1. 先设计 Hub：定义所有可能的上下文和模块边界
2. 清晰标记模块：使用 YAML frontmatter 指明上下文触发条件
3. 衡量 token 成本：了解每个模块的成本，以便进行选择
4. 监控加载情况：跟踪实际使用了哪些模块
5. 验证路径：确认所有上下文路径都具备所需模块
6. 记录触发条件：让上下文检测逻辑清晰透明

模块参考

核心（始终对 Hub 可用）

• 选择策略：参见 modules/selection-strategies.md，了解如何选择模块
• 加载模式：参见 modules/loading-patterns.md，了解实现技巧
• 性能预算：参见 modules/performance-budgeting.md，了解 Token 预算模型和优化工作流
• 高级模式：参见 modules/advanced-patterns.md，了解嵌套 Hub、多层级披露和跨技能模块共享
• 故障排查：当模块加载失败、上下文检测出错或超出 Token 预算时，参见 modules/troubleshooting.md

特定上下文的模式模块

Hub 会根据检测到的工件和用户意图按需加载这些模块。它们列在 frontmatter 中，以便选择器进行匹配，但 Hub 只应加载触发了激活上下文的模块。

操作系统模式（在检测到平台时加载）：

• modules/linux-patterns.md：Linux 专用的 shell、路径和进程模式
• modules/macos-patterns.md：macOS 专用工具和平台特有问题
• modules/windows-patterns.md：Windows shell、路径和 PowerShell 模式

语言和运行时模式（在检测到生态系统时加载）：

• modules/modern-python.md：Python 3.11+ 惯用写法、类型标注、异步
• modules/legacy-python.md：Python 2 / 3.8 之前版本的兼容性模式
• modules/python-packaging.md：pyproject.toml、uv、pip、hatch、poetry
• modules/python-patterns.md：通用 Python 编写模式
• modules/python-testing.md：pytest、fixtures、参数化、模拟
• modules/cargo-patterns.md：Rust Cargo 工作区和依赖模式
• modules/rust-review.md：Rust 代码审查模式

工作流模式（在检测到任务时加载）：

• modules/api-patterns.md：API 设计和端点约定
• modules/api-review.md：API 接口审查模式
• modules/git-patterns.md：Git 工作流和历史模式
• modules/git-catchup-patterns.md：了解分支或 PR 差异
• modules/document-analysis-patterns.md：阅读和分析文档
• modules/log-analysis-patterns.md：解析和推理日志
• modules/performance.md：性能调查模式

参考资料（仅在明确引用时加载）：

• modules/large-reference.md：大型参考表和查找资料（最后加载； Token 开销不可忽视）

与其他技能集成

此技能提供基础模式，供以下项目引用：

• abstract:modular-skills - 使用渐进式加载来设计技能
• conserve:context-optimization - 用于符合 MECW 要求的加载
• imbue:catchup - 用于基于上下文的模块选择
• 构建多工作流技能的插件作者

在技能的 frontmatter 中引用：

dependencies: [leyline:progressive-loading, conserve:context-optimization]
progressive_loading: true

**验证：**运行带有 --help 标志的命令，以验证其是否可用。

退出标准

• Hub 清晰定义所有模块加载上下文
• 每个模块都标记了激活上下文
• 模块选择遵守 MECW 约束
• 已测量所有模块的 Token 成本
• 已记录上下文检测逻辑
• 已验证加载路径的完整性