# https://github.com/experientiallabs/world-model-optimizer 项目说明书 生成时间：2026-07-27 00:34:57 UTC ## 目录 - [项目概览与快速开始](#page-overview) - [Provider 注册、LLM 适配与价格追踪](#page-providers) - [追踪接入、归一化与路由策略](#page-ingest-routing) - [世界模型、模拟引擎与环境捕获](#page-world-model) - [Agent Harness、变更提议与 E2B 沙箱执行](#page-harness) - [优化器、判定器与奖励建模](#page-optimize) - [模型蒸馏流水线](#page-distill) - [本地服务、托管平台与 Web 界面](#page-serve-platform) ## 项目概览与快速开始 ### 相关页面 相关主题：[Provider 注册、LLM 适配与价格追踪](#page-providers), [本地服务、托管平台与 Web 界面](#page-serve-platform)
相关源码文件 以下源码文件用于生成本页说明： - 资料来源： [README.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/README.md) - 资料来源： [AGENTS.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/AGENTS.md) - 资料来源： [CLAUDE.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/CLAUDE.md) - 资料来源： [pyproject.toml](https://github.com/experientiallabs/world-model-optimizer/blob/main/pyproject.toml) - 资料来源： [justfile](https://github.com/experientiallabs/world-model-optimizer/blob/main/justfile) - 资料来源： [wmo/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/__init__.py)
summary> 以下源码文件用于生成本页说明： - [README.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/README.md) - [AGENTS.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/AGENTS.md) - [CLAUDE.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/CLAUDE.md) - [pyproject.toml](https://github.com/experientiallabs/world-model-optimizer/blob/main/pyproject.toml) - [justfile](https://github.com/experientiallabs/world-model-optimizer/blob/main/justfile) - [wmo/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/__init__.py) # 项目概览与快速开始 ## 项目定位与命名演进 `world-model-optimizer`（命令别名 `wmo`）是 Experiential Labs 发布的开源项目，专注于世界模型（World Model）的优化流程。目前发布的 v0.2.0 是首次以 `world-model-optimizer` 名称发布的版本，并已发布到 PyPI 包仓库 资料来源：[README.md:1-40]()。 在此之前，项目以 `world-model-harness` 命名，本次 v0.2.0 是一次彻底的重命名（rename goes all the way down），涵盖了包名、模块路径、命令名以及任何文档/导入引用。已存在旧版本安装的用户需要参考迁移说明进行升级 资料来源：[pyproject.toml:1-40]()。 ## 安装与快速启动 通过 PyPI 进行标准安装即可获得 CLI 工具与 Python 包： ```bash pip install world-model-optimizer ``` 安装完成后，可以在终端直接调用 `wmo` 命令查看可用子命令与参数： ```bash wmo --help ``` Python 用户可以直接从 `wmo` 包名导入模块，无需再使用旧的 `world-model-harness` 命名空间 资料来源：[wmo/__init__.py:1-20]()。 ## 关键变化对照 下表汇总了 v0.2.0 重命名带来的破坏性变更（Breaking Changes），是迁移前必读的内容： | 项目类别 | 旧名称（before） | 新名称（after） | |---|---|---| | PyPI 包名 | `world-model-harness` | `world-model-optimizer` | | Python 导入名 | `world_model_harness`（推断） | `wmo` | | CLI 命令 | `world-model-harness`（推断） | `wmo` | | 仓库路径 | `world-model-harness` | `world-model-optimizer` | 资料来源：[pyproject.toml:1-40]()、[wmo/__init__.py:1-20]() ## 开发与项目工程 项目使用 [`justfile`](https://github.com/experientiallabs/world-model-optimizer/blob/main/justfile) 作为任务运行器，统一管理常见的开发命令（如格式化、测试、构建等），开发者只需在仓库根目录运行 `just` 即可查看可用任务 资料来源：[justfile:1-40]()。 面向贡献者的进一步规范与协作约定，可在以下两个文档中找到： - `AGENTS.md`：提供给自动化代理（agent）的协作指南 资料来源：[AGENTS.md:1-40]() - `CLAUDE.md`：面向 Claude 编码助手的项目上下文说明 资料来源：[CLAUDE.md:1-40]() ## 下一步建议 - 阅读 `README.md` 了解项目理念与典型使用场景 资料来源：[README.md:1-40]() - 完成 `pip install` 后首先运行 `wmo --help` 熟悉 CLI 结构 - 若从旧版本升级，请先卸载 `world-model-harness` 再安装新包，避免命名冲突 - 参与开发前阅读 `AGENTS.md` 与 `CLAUDE.md` 以对齐工程规范 --- ## Provider 注册、LLM 适配与价格追踪 ### 相关页面 相关主题：[项目概览与快速开始](#page-overview), [追踪接入、归一化与路由策略](#page-ingest-routing)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/providers/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/__init__.py) - [wmo/providers/registry.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/registry.py) - [wmo/providers/models.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/models.py) - [wmo/providers/waterfall.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/waterfall.py) - [wmo/providers/openai.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/openai.py) - [wmo/providers/anthropic.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/providers/anthropic.py)
# Provider 注册、LLM 适配与价格追踪 ## 1. 模块定位与整体职责 `wmo/providers` 子包是 **world-model-optimizer (WMO)** 与外部大模型服务之间的适配层，负责三件核心事情： 1. **统一登记**所有可用的 LLM Provider（OpenAI、Anthropic 等），让上层业务通过名称即可调用。 2. **屏蔽差异**：把不同厂商的 SDK、HTTP 接口、流式协议转换成项目内部的统一接口。 3. **记录与核算成本**：维护每个模型在每种 Provider 上的价格表，供优化器在选择路由时计算总花费。 资料来源：[wmo/providers/__init__.py:1-30]() `__init__.py` 中会对外暴露注册器入口和主要工厂函数，使得 CLI（`wmo`）或其它模块只需要 `from wmo.providers import ...` 即可拿到全部能力。 ## 2. Provider 注册机制（Registry） 注册器是 Provider 体系的“目录中心”，采用“装饰器 + 全局表”的经典模式： - 任何继承自基类 `BaseProvider` 的实现类，可以用 `@register("provider-name")` 装饰后自动登记到全局字典中。 - 上层调用方通过 `get_provider("openai")` 这类工厂方法按字符串名字取回实例，避免硬编码类路径。 - 这种设计让新增厂商（例如未来加入 Google、Mistral）只需要新增一个文件并打上装饰器，无需改动调度逻辑。 资料来源：[wmo/providers/registry.py:1-80]() 注册表内部通常以 `dict[str, type[BaseProvider]]` 形式保存，并在 `__init__` 阶段自动 import 所有内置 Provider 模块，确保 `import wmo.providers` 副作用即可完成自注册（auto-discovery）。 ## 3. LLM 适配层（OpenAI / Anthropic） 每个具体的 Provider 文件都实现一组抽象方法，使得上层只需关心统一的请求/响应模型： - **OpenAI Provider** 负责把内部统一的 `ChatRequest` 翻译为 `openai` SDK 的 `chat.completions.create`，并把响应归一化为项目内部的消息结构，支持流式返回。 资料来源：[wmo/providers/openai.py:1-60]() - **Anthropic Provider** 通过 Anthropic Messages API 完成类似工作，包括 `system` 提示词的拼接、长上下文分块、以及 `usage` 字段中的 token 计数归一化。 资料来源：[wmo/providers/anthropic.py:1-60]() 两者共同遵循 `BaseProvider` 定义的接口（典型如 `complete()`、`stream()`、`count_tokens()`），因此优化器可以把它们当作可互换的“算子”。 ## 4. 价格追踪与 Waterfall 路由 价格追踪并不是一个独立的数据库，而是一组静态+动态结合的模型定义，位于 `models.py`： | 字段 | 含义 | 典型用途 | |---|---|---| | `prompt_price_per_1k` | 每 1K 输入 token 单价 | 输入侧成本估算 | | `completion_price_per_1k` | 每 1K 输出 token 单价 | 输出侧成本估算 | | `currency` | 计价货币 | 多厂商价格对齐 | | `effective_date` | 生效时间 | 价格表版本管理 | 资料来源：[wmo/providers/models.py:1-90]() `waterfall.py` 提供了“瀑布式”选择策略：给定一组候选 Provider/模型，按价格或性价比逐级尝试，直到成功返回或所有候选耗尽。这种方式与 v0.2.0 引入的优化器定位紧密相关——用户期望在不同价位模型之间自动寻找最优组合。 资料来源：[wmo/providers/waterfall.py:1-80]() ## 5. 与 v0.2.0 更名的衔接 从 `world-model-harness` 重命名为 `world-model-optimizer` 后，`wmo.providers.*` 的导入路径也同步更新。如果旧代码里出现 `world_model_harness.providers`，迁移时需要改为 `wmo.providers`，否则注册表将无法发现历史 Provider 类。CLI 安装方式从 `pip install world-model-harness` 变为 `pip install world-model-optimizer`，安装后通过 `wmo --help` 即可验证 Provider 列表是否正确加载。 资料来源：[wmo/providers/__init__.py:1-30]()、社区发布说明（v0.2.0 Breaking 章节） ## 6. 扩展建议 新增一个 Provider 时，推荐流程： 1. 在 `wmo/providers/` 下新建文件，例如 `myvendor.py`。 2. 实现 `BaseProvider` 的全部抽象方法，并把模型价格写入 `models.py`。 3. 用 `@register("myvendor")` 装饰实现类，确保 `__init__.py` 会 import 它。 4. 在 `waterfall.py` 中按需加入该 Provider 作为候选。 完成后无需改动 CLI 或上层优化器，注册器会自动把它纳入调度范围。 --- ## 追踪接入、归一化与路由策略 ### 相关页面 相关主题：[Provider 注册、LLM 适配与价格追踪](#page-providers), [优化器、判定器与奖励建模](#page-optimize)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/ingest/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/__init__.py) - [wmo/ingest/braintrust.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/braintrust.py) - [wmo/ingest/langfuse.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/langfuse.py) - [wmo/ingest/langsmith.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/langsmith.py) - [wmo/ingest/mastra.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/mastra.py) - [wmo/ingest/phoenix.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/ingest/phoenix.py)
# 追踪接入、归一化与路由策略 世界模型优化器（world-model-optimizer，简称 `wmo`）的追踪子系统位于 `wmo/ingest/` 包内，负责将来自不同观测后端的原始追踪数据（traces、spans、events）统一接入、转换为内部标准事件，并按配置路由到下游的世界模型训练与评估管线。本页说明其设计目标、归一化模型与路由决策逻辑。 ## 一、模块定位与目标 `wmo/ingest/__init__.py` 将每个后端实现作为独立子模块导出，形成"插件式"接入面。系统目标包括： - **多源兼容**：同时支持 Braintrust、Langfuse、LangSmith、Mastra、Phoenix 等主流 LLM 观测平台。 - **协议无关**：上层管线只依赖统一的 `NormalizedTrace` / `Span` 数据结构，避免后端 SDK 升级造成的耦合破坏。 - **可路由**：通过统一的配置（CLI 环境变量或 YAML）决定事件送往训练缓冲、评估缓冲或两者兼有。 资料来源：[wmo/ingest/__init__.py:1-40]() ## 二、各后端接入实现 每个后端文件都遵循相同的导出契约：暴露一个 `ingest(source: str | Path, **opts) -> Iterator[NormalizedEvent]` 入口函数，以及一个后端专属的 `_parse_*` 解析器。差异主要体现在原始载荷格式与鉴权方式。 | 后端 | 数据源 | 关键差异点 | |---|---|---| | Braintrust | 项目导出 JSONL | 嵌套 `spans[*].events` 树形结构 | | Langfuse | REST `/api/public/traces` | 基于 `observation` 类型的扁平列表 | | LangSmith | SDK dump 或 API | 强类型的 `runs` 数组，含 `extra.metadata` | | Mastra | OTLP/HTTP JSON | 兼容 OpenTelemetry 语义约定 | | Phoenix | 本地 SQLite/Parquet | 需基于时间窗口增量拉取 | 资料来源：[wmo/ingest/braintrust.py:1-60](), [wmo/ingest/langfuse.py:20-90](), [wmo/ingest/langsmith.py:15-80](), [wmo/ingest/mastra.py:10-55](), [wmo/ingest/phoenix.py:25-95]() ## 三、归一化模型 `NormalizedEvent` 是跨后端的最小数据单元，字段集合固定： - `trace_id: str`：全局唯一追踪标识。 - `span_id: str` / `parent_span_id: str | None`：构成调用树。 - `name: str`：语义化节点名。 - `kind: Literal["llm","tool","chain","retriever","embedding","custom"]`。 - `start_ts` / `end_ts`：UTC 微秒时间戳。 - `inputs` / `outputs`：经 `safe_json` 包装后的可序列化载荷。 - `attributes: dict`：保留 token 用量、模型名、提示模板版本等扩展键。 - `status: Literal["ok","error"]` 与 `error: ErrorPayload | None`。 各后端解析器在 `_to_normalized()` 阶段将原始字段映射到上述结构，例如 Langfuse 的 `GENERATION` 被映射为 `kind="llm"`，Phoenix 的 `RETRIEVER` 被映射为 `kind="retriever"`。时间戳统一以 UTC 微秒存储，避免时区漂移。 资料来源：[wmo/ingest/__init__.py:30-120](), [wmo/ingest/langfuse.py:120-180](), [wmo/ingest/braintrust.py:90-140]() ## 四、路由策略 归一化后的事件流不会直接落地，而是经过 `Router` 进行分类。`Router` 基于以下规则决定去向： ```mermaid flowchart LR A[归一化事件] --> B{kind?} B -->|llm/tool| C[训练缓冲] B -->|chain/retriever| D[评估缓冲] B -->|custom| E[按 attribute.tag 路由] C --> F[世界模型参数更新] D --> G[离线评估与回归] E --> H[自定义导出器] ``` 规则由 `routes.yaml`（或 `WMO_ROUTES` 环境变量）声明，支持通配符与权重。默认策略下，LLM 与工具调用进入训练缓冲，用以拟合世界模型；链式与检索器进入评估缓冲，用于离线回归。当事件携带 `attribute.wmo.sample_rate < 1.0` 时，路由器按伯努利采样进行降采样，从而控制数据量。错误状态（`status="error"`）会被路由器无条件转发到评估缓冲，并附上 `failure=true` 标记，方便后续做失败模式分析。 资料来源：[wmo/ingest/__init__.py:140-220](), [wmo/ingest/langsmith.py:180-230](), [wmo/ingest/mastra.py:120-170](), [wmo/ingest/phoenix.py:160-210]() ## 五、使用与扩展 CLI 入口 `wmo ingest --backend --source ` 会按上述契约加载对应子模块；新增后端只需在 `wmo/ingest/` 下追加一个文件并提供 `ingest()` 入口即可。`__init__.py` 的注册表会自动暴露给上层命令行与 Python API，使追踪接入、归一化与路由三者保持解耦。该设计也解释了 `v0.2.0` 将包名从 `world-model-harness` 改为 `world-model-optimizer` 后的兼容性承诺：旧脚本只要指向新的子模块路径，行为保持一致。 资料来源：[wmo/ingest/__init__.py:220-280](), [wmo/ingest/braintrust.py:200-260]() --- ## 世界模型、模拟引擎与环境捕获 ### 相关页面 相关主题：[Agent Harness、变更提议与 E2B 沙箱执行](#page-harness), [优化器、判定器与奖励建模](#page-optimize)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/engine/world_model.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/world_model.py) - [wmo/engine/play.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/play.py) - [wmo/engine/replay.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/replay.py) - [wmo/engine/build.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/build.py) - [wmo/engine/knowledge.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/knowledge.py) - [wmo/engine/grounding.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/engine/grounding.py)
# 世界模型、模拟引擎与环境捕获 ## 概述 `world-model-optimizer`（包名 `wmo`）在 v0.2.0 中由 `world-model-harness` 改名而来，其核心抽象是**世界模型（World Model）**——一个对环境状态、动作与反馈的可重放描述。`wmo/engine/` 子包负责把所有交互环节（构建、游玩、回放、知识注入、落地对齐）编排成一个一致的流水线，使得一次环境捕获可以在后续被反复驱动、查询与优化。 资料来源：[wmo/engine/world_model.py:1-40]() --- ## 世界模型核心抽象 `wmo/engine/world_model.py` 定义了世界模型的基础数据结构与生命周期：状态容器、动作集合、转移函数入口，以及与外部优化器之间的契约。世界模型不是一个静态的快照，而是一个**可执行对象**——它能够响应 `step(action)` 调用并返回下一个观察、奖励与终止信号。 该模块同时承担序列化职责，把运行时状态（实体位置、资源计数、标记位等）落地为可重放的字节流，从而允许离线分析。 ```python class WorldModel: def reset(self) -> Observation: ... def step(self, action: Action) -> Transition: ... def snapshot(self) -> StateBlob: ... def restore(self, blob: StateBlob) -> None: ... ``` 资料来源：[wmo/engine/world_model.py:42-120]() --- ## 模拟引擎（Play 与 Replay） ### 实时驱动：play `wmo/engine/play.py` 提供面向在线交互的入口，把用户、策略或脚本发起的动作送入世界模型，并把结果以人类可读的结构化日志输出。它是**前向传播**的载体：动作进入，转移函数运行，环境状态前进。 ### 离线回放：replay `wmo/engine/replay.py` 则是**时间反向**的工具：它消费由 `play` 或外部录制器产生的轨迹，按照相同的世界模型定义重新执行，从而验证可复现性、对比策略差异，或抽取反事实样本。回放器在每个时间步校验状态哈希，确保轨迹未被篡改。 | 模式 | 入口模块 | 主要用途 | |---|---|---| | 实时游玩 | `play.py` | 驱动智能体、收集新轨迹 | | 离线回放 | `replay.py` | 重放、审计、反事实分析 | | 构建 | `build.py` | 从原始日志生成世界模型 | 资料来源：[wmo/engine/play.py:1-60]()、[wmo/engine/replay.py:1-80]() --- ## 环境捕获与构建 `wmo/engine/build.py` 是**环境捕获（Environment Capture）**的关键。它把来自外部仿真器、游戏或真实传感器的事件流（键鼠、帧、网络包、API 调用）转换为世界模型可以消费的规范化转移。这一步通常被称为 *trace ingestion*：原始事件 → 语义动作 → 转移记录 → 模型增量。 `build.py` 输出的是一个**初始化的世界模型实例**，它要么直接用于游玩，要么被持久化为可分发工件。 资料来源：[wmo/engine/build.py:30-110]() --- ## 知识与落地对齐 ### 知识层 `wmo/engine/knowledge.py` 维护与世界模型并列的**知识图谱或规则库**——例如物品合成配方、NPC 行为模式、关卡先验知识。知识层在模拟过程中可被查询，用于约束或剪枝搜索空间，从而加速优化。 ### 接地（Grounding） `wmo/engine/grounding.py` 解决的是**符号到像素/连续空间的映射问题**：把抽象动作（如 `use(key, door)`）与底层环境信号（按键序列、坐标偏移、协议字段）对应起来。接地层使同一个世界模型可以跨多种运行环境保持语义一致。 资料来源：[wmo/engine/knowledge.py:1-70]()、[wmo/engine/grounding.py:20-95]() --- ## 整体工作流 ```mermaid flowchart LR A[原始事件流] --> B[build.py
环境捕获] B --> C[world_model.py
世界模型] C --> D[play.py
实时模拟] D --> E[轨迹/日志] E --> F[replay.py
离线回放] C --> G[knowledge.py
知识层] C --> H[grounding.py
符号接地] F --> I[优化器/分析器] ``` 整个引擎遵循**构建 → 游玩 → 回放 → 优化**的闭环：构建阶段产生模型，玩游阶段产出新轨迹，回放阶段验证与挖掘，优化器（外部）则基于回放结果调整策略，再回到游玩阶段验证。这种设计允许在不重新捕获环境的前提下，反复迭代策略与模型。 资料来源：[wmo/engine/world_model.py:42-120]()、[wmo/engine/play.py:1-60]()、[wmo/engine/replay.py:1-80]()、[wmo/engine/build.py:30-110]()、[wmo/engine/knowledge.py:1-70]()、[wmo/engine/grounding.py:20-95]() --- ## Agent Harness、变更提议与 E2B 沙箱执行 ### 相关页面 相关主题：[世界模型、模拟引擎与环境捕获](#page-world-model), [优化器、判定器与奖励建模](#page-optimize)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/harness/create.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/create.py) - [wmo/harness/mutate.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/mutate.py) - [wmo/harness/proposer.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/proposer.py) - [wmo/harness/project_proposer.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/project_proposer.py) - [wmo/harness/skills.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/skills.py) - [wmo/harness/scoring.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/harness/scoring.py)
# Agent Harness、变更提议与 E2B 沙箱执行 `world-model-optimizer` 在 v0.2.0 中将仓库从 `world-model-harness` 重命名而来，CLI 命令变为 `wmo`。其核心抽象是一个 "Agent Harness"——一组围绕 LLM 代理构建、变更提议、评分与沙箱执行的协作模块。本页围绕 `wmo/harness/` 下的源码解释它们如何组合。 ## 1. Agent Harness 的角色与边界 Agent Harness 是优化循环的"驾驶员"：负责构建代理、提供技能、生成变更、对变更打分，并通过沙箱安全地执行。整个 `wmo/harness/` 目录遵循按职责拆分的命名约定： | 文件 | 职责 | |---|---| | `create.py` | 创建代理实例与运行环境 | | `skills.py` | 注入代理可调用的工具/技能 | | `proposer.py` | 生成代码或策略变更提议 | | `project_proposer.py` | 项目级别的批量变更提议 | | `mutate.py` | 对提议应用变异操作 | | `scoring.py` | 评估提议质量并给出分数 | 这种拆分让用户可以单独替换提议策略或评分函数，而不必重新实现整套流水线。 ## 2. 代理创建与技能注入 代理的初始化由 `create.py` 提供，模块导出用于构造 "harness 实例" 的工厂方法。在构造过程中，`skills.py` 把若干领域能力（如文件读写、命令执行、搜索代码）注册为代理可调用的工具。 ```python from wmo.harness.create import build_agent from wmo.harness.skills import default_skills agent = build_agent(skills=default_skills()) ``` `skills.py` 通常以列表或字典形式暴露可枚举技能，以便后续在评分阶段也能复用同套工具集合，保持代理在"提议"和"评估"时能力一致。资料来源：[wmo/harness/create.py:1-40]()、 [wmo/harness/skills.py:1-30]()。 ## 3. 变更提议流水线 变更提议是 Harness 在每个优化轮次中向世界模型递交的"动作"。它由以下三步组成，完整流水线如下： ```mermaid flowchart LR A[当前世界模型] --> B[proposer.py
生成候选提议] B --> C[project_proposer.py
项目级筛选/合并] C --> D[mutate.py
应用变异] D --> E[scoring.py
评估与排序] E -->|保留 Top-K| A ``` - **`proposer.py`**：基于当前上下文产出原始变更候选，例如新增/修改/删除文件片段。资料来源：[wmo/harness/proposer.py:1-50]()。 - **`project_proposer.py`**：当需要把多个提议合并成"项目级 PR"形态时使用，负责跨文件一致性与依赖检查。资料来源：[wmo/harness/project_proposer.py:1-60]()。 - **`mutate.py`**：对提议应用变异（如重写片段、调整参数、注入探索性扰动），是遗传/进化的核心算子。资料来源：[wmo/harness/mutate.py:1-80]()。 ## 4. 评分与 E2B 沙箱执行 提议落地后必须经过客观评估。`scoring.py` 接收提议与其执行结果，返回可比较的数值分数，并据此挑选进入下一轮的最优解。资料来源：[wmo/harness/scoring.py:1-70]()。 由于代理生成的变更可能运行任意代码，Harness 把执行环节交给 [E2B](https://e2b.dev) 沙箱，Harness 与沙箱的交互通常表现为： ```python with e2b.Sandbox() as sbx: result = sbx.filesystem.write_file(path, proposed_code) output = sbx.process.run_and_wait(cmd="pytest -q") score = scoring_fn(output) ``` 在 CLI 层面，用户通过 `wmo --help` 可发现与执行/沙箱相关的子命令，例如指定 E2B API Key、选择基础模板镜像、限制执行超时时间等，这呼应了社区中关于"安全执行代理生成代码"的关注。 ## 5. 三者如何组合 把上述三部分串起来，Harness 一个典型的优化回合为：构建带技能的代理 → 由代理产出提议 → 通过变异增强多样性 → 在 E2B 沙箱内执行 → 由评分函数排序 → 把优胜写回世界模型，进入下一轮。该循环是 `world-model-optimizer` 的核心价值所在，也是 v0.2.0 重命名后 `wmo` 命令的主要工作流。 --- ## 优化器、判定器与奖励建模 ### 相关页面 相关主题：[追踪接入、归一化与路由策略](#page-ingest-routing), [Agent Harness、变更提议与 E2B 沙箱执行](#page-harness) > 相关源码文件 以下源码文件用于生成本页说明： - [wmo/optimize/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/__init__.py) - [wmo/optimize/base.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/base.py) - [wmo/optimize/gepa.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/gepa.py) - [wmo/optimize/judge.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/judge.py) - [wmo/optimize/judge_quality.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/judge_quality.py) - [wmo/optimize/reward.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/optimize/reward.py) # 优化器、判定器与奖励建模 `wmo/optimize` 子包承担了 `world-model-optimizer` 项目中"如何让世界模型在任务上变得更好"的核心职责。它把传统的提示词/策略调优抽象成三条相互衔接的链路：**优化器（Optimizer）**负责驱动搜索与迭代，**判定器（Judge）**负责对候选输出进行打分与质量评估，**奖励建模（Reward）**负责把多维评分合成可被优化器使用的单一信号。资料来源：[wmo/optimize/__init__.py:1-40]()。 ## 整体架构 `wmo/optimize/__init__.py` 中将 `base`、`gepa`、`judge`、`judge_quality`、`reward` 等模块统一对外导出，形成一个"优化器驱动—判定器评估—奖励聚合"的闭环。基础抽象 `Optimize` 在 `wmo/optimize/base.py` 中定义，集中规定了配置注入、轨迹记录与最小 `run()` 接口契约，便于上层 CLI（`wmo --help` 中对应的优化子命令）按统一方式调度。资料来源：[wmo/optimize/__init__.py:1-40]()、资料来源：[wmo/optimize/base.py:1-80]()。 ```mermaid flowchart LR A[候选策略/提示词] --> B[优化器 GEPA] B --> C[世界模型 rollout] C --> D[判定器 Judge / JudgeQuality] D --> E[奖励聚合 Reward] E --> B ``` 上图中，`GEPA` 产生新候选 → 模型 rollout → `Judge` 给出多维度评分 → `Reward` 折算为标量 → 反馈给 `GEPA` 继续迭代。 ## 优化器：GEPA `wmo/optimize/gepa.py` 实现了基于遗传帕累托（Genetic-Pareto）的优化器 `GEPAOptimizer`，它继承自 `base.py` 中的 `Optimize` 抽象。`GEPAOptimizer` 维护一个候选种群，按多目标帕累托前沿进行选择、交叉与变异，并在每一代结束时根据判定器与奖励信号挑选非支配解。资料来源：[wmo/optimize/gepa.py:1-60]()、资料来源：[wmo/optimize/base.py:30-90]()。 关键参数与行为包括： - **种群大小与代数**：通过 `base.py` 的配置接口传入，控制探索广度与计算预算。资料来源：[wmo/optimize/base.py:40-70]()。 - **多目标适应度**：直接消费 `Judge` 返回的多维评分，结合 `Reward` 聚合后的标量共同决定前沿。资料来源：[wmo/optimize/gepa.py:60-120]()。 - **反思/变异策略**：GEPA 的核心是让模型反思自身轨迹，再生成新候选；这部分在 `gepa.py` 的 `mutate` / `reflect` 路径中完成。资料来源：[wmo/optimize/gepa.py:120-200]()。 ## 判定器：Judge 与 JudgeQuality `wmo/optimize/judge.py` 定义了 `Judge` 协议的入口形态：接收一次完整轨迹，输出结构化的多维评分字典。`Judge` 既可以作为 LLM-as-a-judge 的包装，也可以承载规则化打分逻辑，对应上层的"语义质量"维度。资料来源：[wmo/optimize/judge.py:1-60]()。 `wmo/optimize/judge_quality.py` 在 `Judge` 之上提供了"质量判定"特化实现 `JudgeQuality`，重点关注： - **结构性校验**：输出格式、字段完整度、是否包含非法内容。资料来源：[wmo/optimize/judge_quality.py:30-80]()。 - **语义一致性**：候选答案与任务指令、世界模型状态之间的一致性检查。资料来源：[wmo/optimize/judge_quality.py:80-140]()。 - **可配置阈值**：通过 `base.py` 的配置注入失败阈值，低于阈值即判定为硬失败，从候选池中剔除。资料来源：[wmo/optimize/judge_quality.py:140-200]()。 `JudgeQuality` 与 `Judge` 的关系是：通用 `Judge` 提供打分容器，`JudgeQuality` 给出针对世界模型任务的高质量默认实现，用户也可以自定义子类注入到 `GEPAOptimizer` 中。 ## 奖励建模：Reward `wmo/optimize/reward.py` 负责把 `Judge` 输出的多维评分转化为优化器可用的标量信号。常见的聚合策略包括加权平均、阈值门控与帕累托兼容变换，以便与 `GEPAOptimizer` 的多目标搜索对齐。资料来源：[wmo/optimize/reward.py:1-60]()。 `Reward` 模块的设计要点： - **可组合算子**：支持基于权重的线性组合与基于阈值的硬约束，便于在同一优化任务中表达"既要又要"的偏好。资料来源：[wmo/optimize/reward.py:60-120]()。 - **与优化器解耦**：仅依赖 `Judge` 的输出结构，因此可以独立替换聚合策略而不影响 `GEPA` 的搜索逻辑。资料来源：[wmo/optimize/reward.py:120-180]()。 - **归一化与稳定性**：在喂给优化器之前会对不同维度的分数做归一化，以避免量纲差异导致 `GEPA` 选择失衡。资料来源：[wmo/optimize/reward.py:180-240]()。 ## 三者协作流程 一次典型的优化任务执行顺序如下： 1. CLI 通过 `wmo/optimize/__init__.py` 解析得到 `GEPAOptimizer` 实例及其配置。资料来源：[wmo/optimize/__init__.py:10-40]()。 2. `GEPAOptimizer` 产生初始候选种群，对每个候选在世界模型中跑出轨迹。资料来源：[wmo/optimize/gepa.py:60-120]()。 3. `Judge`/`JudgeQuality` 对轨迹进行多维评分。资料来源：[wmo/optimize/judge.py:30-60]()、资料来源：[wmo/optimize/judge_quality.py:30-80]()。 4. `Reward` 把多维评分聚合为标量反馈给 `GEPAOptimizer`。资料来源：[wmo/optimize/reward.py:60-120]()。 5. `GEPAOptimizer` 更新种群并继续迭代，直到达到预算或收敛条件。资料来源：[wmo/optimize/gepa.py:120-200]()。 通过这种分层设计，`world-model-optimizer` 让"如何评估"和"如何搜 --- ## 模型蒸馏流水线 ### 相关页面 相关主题：[优化器、判定器与奖励建模](#page-optimize), [Provider 注册、LLM 适配与价格追踪](#page-providers)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/distill/README.md](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/README.md) - [wmo/distill/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/__init__.py) - [wmo/distill/loop.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/loop.py) - [wmo/distill/teacher.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/teacher.py) - [wmo/distill/rollouts.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/rollouts.py) - [wmo/distill/samples.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/distill/samples.py)
# 模型蒸馏流水线 ## 概述与定位 `wmo.distill` 子包为 `world-model-optimizer`（包名从早期的 `world-model-harness` 迁移而来）提供"模型蒸馏流水线"。其核心目标是把一个更强大的"教师（Teacher）"世界模型产生的轨迹与隐状态，作为监督信号传递给更轻量的"学生（Student）"模型，从而在世界建模任务上以更低的推理成本获得接近教师模型的行为。 子包职责边界明确： - `wmo/distill/__init__.py`：作为子包公共入口，对外仅暴露受控的 API 表面，避免外部直接依赖内部模块。 资料来源：[wmo/distill/__init__.py:1-]()。 - `wmo/distill/teacher.py`：封装教师模型的推理接口，负责返回用于蒸馏的中间信号。 - `wmo/distill/rollouts.py`：在环境或世界模型内部执行轨迹展开，把教师信号与学生动作绑定。 - `wmo/distill/samples.py`：定义样本的数据结构与采样/批处理规则。 - `wmo/distill/loop.py`：把上面的模块编排为一次完整的"采样→蒸馏"循环。 社区上下文中，v0.2.0 是仓库首次以 `world-model-optimizer` 名称发布到 PyPI（`pip install world-model-optimizer`，CLI 入口 `wmo`），这意味着 `wmo.distill` 与 CLI 命令共同属于首次正式对外的稳定面，资料来源：[wmo/distill/README.md:1-]()。 ## 模块划分与职责 | 模块 | 主要职责 | |---|---| | `teacher.py` | 教师模型的加载与调用，向学生暴露统一的隐状态 / 行为分布接口 | | `rollouts.py` | 在世界模型上执行多步 rollout，收集 (state, teacher_signal, student_action) 三元组 | | `samples.py` | 将 rollout 结果组装为可训练的 `Sample` / 批次数据结构 | | `loop.py` | 串联 teacher → rollouts → samples → 学生更新，构成主循环 | | `__init__.py` | 限制导入面，仅发布对外稳定的符号 | 在 CLI 层，`wmo --help` 通常会暴露 `distill` 子命令族，调度到本子包内部的 `loop.py`。 资料来源：[wmo/distill/loop.py:1-]()。 ## 主循环工作流 `loop.py` 是蒸馏流水线的控制中枢，典型一次迭代包括以下阶段： 1. **教师前向**：`teacher.py` 读取当前观测，输出 logits / 隐向量 / 计划（plan）等监督信号。 资料来源：[wmo/distill/teacher.py:1-]()。 2. **学生 Rollout**：`rollouts.py` 使用学生策略在世界中推进 N 步，并同步记录教师在对应时间步的输出。 资料来源：[wmo/distill/rollouts.py:1-]()。 3. **样本封装**：`samples.py` 把轨迹片段切分为可训练样本，过滤掉无效步（例如环境截断、异常奖励），并构造 mini-batch。 资料来源：[wmo/distill/samples.py:1-]()。 4. **学生更新**：在样本上对教师的输出拟合（如 KL 散度 / MSE / 行为克隆损失等），完成一步梯度下降。 资料来源：[wmo/distill/loop.py:1-]()。 ```mermaid flowchart LR A[teacher.py
教师前向] --> B[rollouts.py
学生 Rollout] B --> C[samples.py
样本/批次构造] C --> D[loop.py
学生参数更新] D --> B ``` 该结构遵循"采样 - 学习 - 复用最新学生继续采样"的迭代式蒸馏范式，区别于离线蒸馏的固定数据流，因此学生可以持续校正分布偏移。 资料来源：[wmo/distill/loop.py:1-]()。 ## 输入、输出与扩展点 - **输入**：环境观测、教师模型权重（或远端教师服务句柄）、超参数（rollout 长度、批大小、蒸馏损失权重等），通过 CLI 或配置对象传给 `loop.py`。 - **输出**：更新后的学生检查点，以及用于评估 / 监控的中间指标（教师 - 学生一致性损失、回报等）。 - **可扩展点**： - 替换 `teacher.py` 的实现即可切换不同的监督信号源，无需改动 `rollouts.py`； - `samples.py` 的过滤函数决定了哪些步进入训练集，影响有效样本率； - `loop.py` 在不改变 `teacher / rollouts / samples` 契约的前提下，可以叠加额外的正则化或回放缓冲区。 资料来源：[wmo/distill/__init__.py:1-]() 与 [wmo/distill/README.md:1-]()。 ## 与 CLI 的协作 v0.2.0 起，CLI 入口统一为 `wmo`。`wmo.distill` 通常以子命令形式挂载，例如 `wmo distill `，其内部最终会调用 `loop.py` 的主函数。由于项目沿用 `world-model-harness` → `world-model-optimizer` 的更名链路，旧文档中以 `python -m world_model_harness ...` 启动的等价命令已不再适用，新用户应使用 `wmo` 入口（资料来源：仓库 v0.2.0 发布说明 / [wmo/distill/README.md:1-]()）。 ## 已知约束 - 流水线对教师模型的接口稳定性敏感：`teacher.py` 返回的字段必须与 `samples.py` 期望的字段一致；字段漂移会直接导致 `loop.py` 的批处理失败。 - `rollouts.py` 的步数越多，单次迭代越昂贵，但样本多样性更高；需要在 `loop.py` 中通过配置而不是硬编码进行调节。 - 本子包不负责评测或奖励塑形，专注"教师 → 学生"的监督学习链路；其它训练范式（如强化学习主训）属于项目其它模块。 资料来源：[wmo/distill/teacher.py:1-]()、[wmo/distill/rollouts.py:1-]()、[wmo/distill/samples.py:1-]()、[wmo/distill/loop.py:1-]()、[wmo/distill/__init__.py:1-]() 与 [wmo/distill/README.md:1-]()。 --- ## 本地服务、托管平台与 Web 界面 ### 相关页面 相关主题：[项目概览与快速开始](#page-overview), [Agent Harness、变更提议与 E2B 沙箱执行](#page-harness)
相关源码文件 以下源码文件用于生成本页说明： - [wmo/serving/__init__.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/__init__.py) - [wmo/serving/server.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/server.py) - [wmo/serving/chat.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/chat.py) - [wmo/serving/builds.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/builds.py) - [wmo/serving/endpoint_config.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/endpoint_config.py) - [wmo/serving/savings.py](https://github.com/experientiallabs/world-model-optimizer/blob/main/wmo/serving/savings.py)
# 本地服务、托管平台与 Web 界面 `wmo.serving` 子包承担 world-model-optimizer（v0.2.0）整套"模型对外暴露"的工作：从本地命令行拉起的开发服务器，到面向生产环境的托管平台构建产物，再到浏览器端的聊天界面与成本追踪。该子包与项目重命名同步落地，自 `world-model-harness` 之后，PyPI 包 `world-model-optimizer` 的 `wmo` 命令即可拉起上述能力 资料来源：[wmo/serving/__init__.py:1-40]()。 ## 模块组成与职责划分 子包通过 `__init__.py` 对外暴露一组高层 API，使得 CLI 与其它模块只需要 `from wmo.serving import ...` 即可拿到服务端、聊天端、构建器、端点配置与节省额度计算等对象 资料来源：[wmo/serving/__init__.py:1-40]()。这种薄封装层让本地开发与生产托管共用同一套语义对象，避免出现"开发用一套类、生产用另一套类"的割裂。 | 子模块 | 角色 | 典型调用方 | |---|---|---| | `server` | 本地 HTTP 服务入口 | `wmo` CLI、`wmo serve` 子命令 | | `chat` | 浏览器聊天界面与会话桥接 | `server` 路由、托管平台前端 | | `builds` | 面向托管平台的容器/工件构建 | CI、部署流水线 | | `endpoint_config` | 端点 URL、密钥、模型版本配置 | `server`、`builds` | | `savings` | 优化前后的成本/资源对比 | 报表、CLI 摘要输出 | ## 本地服务器与 Web 界面 `server.py` 实现本地开发与离线测试使用的 HTTP 服务，负责把请求路由到模型推理后端，并把响应流式回传给浏览器；它既可作为开发期的人工验证入口，也可作为托管平台前端的本地替代 资料来源：[wmo/serving/server.py:1-80]()。`chat.py` 在此基础上提供浏览器端的对话 UI 模板与会话状态管理——它把用户输入封装为模型所需的提示词、把模型输出渲染为可读消息，并维护多轮上下文 资料来源：[wmo/serving/chat.py:1-60]()。这两者配合之后，本地用户只需一条 `wmo serve` 即可获得带 Web UI 的交互式入口，无需额外部署前端。 ## 托管平台构建与端点配置 当需要把工作流落到生产环境时，`builds.py` 负责把本地服务打包为托管平台（云端推理服务、容器平台、内部调度系统等）可消费的构建产物，例如容器镜像或构建描述符 资料来源：[wmo/serving/builds.py:1-50]()。每个产物在落盘或推送前都会读取 `endpoint_config.py` 中的端点定义——包括推理服务的 URL 模板、请求/响应协议、模型版本与凭证占位符——从而保证"本地能跑、生产也能跑"的一致性 资料来源：[wmo/serving/endpoint_config.py:1-60]()。这一抽象也让 CI 在不改动业务代码的前提下，仅通过替换配置即可把同一份构建产物部署到不同环境。 ## 成本与节省额度追踪 `savings.py` 与托管路径紧耦合：在模型替换、量化、批处理等优化动作生效后，它会基于端点配置中的价格/资源参数对比"原方案 vs 优化方案"，输出节省额度摘要供报表与 CLI 呈现 资料来源：[wmo/serving/savings.py:1-50]()。该模块通常在构建产物阶段被调用，把节省数字写入构建元数据或部署报告，从而让"上线即看到成本变化"成为可能 资料来源：[wmo/serving/builds.py:30-90]()。 ## 端到端数据流 下面的流程图把上述模块串成一条从本地到托管平台的链路： ```mermaid flowchart LR A[wmo serve] --> B[server.py] B --> C[chat.py
Web UI] B --> D[endpoint_config.py] D --> E[builds.py
托管产物] E --> F[托管平台] E --> G[savings.py
节省摘要] ``` 整体来看，`wmo.serving` 让用户从 `pip install world-model-optimizer` 之后的第一行 `wmo --help` 开始，就能在同一份代码语义下完成"本地调试 → 生产托管 → 成本可视化"三段式落地。 --- --- ## Doramagic 踩坑日志 项目：experientiallabs/world-model-optimizer 摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://news.ycombinator.com/item?id=49063454 | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063454 | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49063454 | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49063454 | no_demo; severity=medium ## 5. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063454 | issue_or_pr_quality=unknown ## 6. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063454 | release_recency=unknown