项目定位与命名演进

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 包：

pip install world-model-optimizer

安装完成后，可以在终端直接调用 wmo 命令查看可用子命令与参数：

wmo --help

Python 用户可以直接从 wmo 包名导入模块，无需再使用旧的 world-model-harness 命名空间 资料来源：wmo/__init__.py:1-20。

关键变化对照

下表汇总了 v0.2.0 重命名带来的破坏性变更（Breaking Changes），是迁移前必读的内容：

资料来源：pyproject.toml:1-40、wmo/__init__.py:1-20

开发与项目工程

项目使用 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 以对齐工程规范

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 文件都实现一组抽象方法，使得上层只需关心统一的请求/响应模型：

资料来源：wmo/providers/openai.py:1-60

资料来源：wmo/providers/anthropic.py:1-60

• OpenAI Provider 负责把内部统一的 ChatRequest 翻译为 openai SDK 的 chat.completions.create，并把响应归一化为项目内部的消息结构，支持流式返回。
• Anthropic Provider 通过 Anthropic Messages API 完成类似工作，包括 system 提示词的拼接、长上下文分块、以及 usage 字段中的 token 计数归一化。

两者共同遵循 BaseProvider 定义的接口（典型如 complete()、stream()、count_tokens()），因此优化器可以把它们当作可互换的“算子”。

4. 价格追踪与 Waterfall 路由

价格追踪并不是一个独立的数据库，而是一组静态+动态结合的模型定义，位于 models.py：

资料来源：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 或上层优化器，注册器会自动把它纳入调度范围。

一、模块定位与目标

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_* 解析器。差异主要体现在原始载荷格式与鉴权方式。

资料来源：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 基于以下规则决定去向：

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 <name> --source <path> 会按上述契约加载对应子模块；新增后端只需在 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

概述

world-model-optimizer（包名 wmo）在 v0.2.0 中由 world-model-harness 改名而来，其核心抽象是世界模型（World Model）——一个对环境状态、动作与反馈的可重放描述。wmo/engine/ 子包负责把所有交互环节（构建、游玩、回放、知识注入、落地对齐）编排成一个一致的流水线，使得一次环境捕获可以在后续被反复驱动、查询与优化。

资料来源：wmo/engine/world_model.py:1-40

1. Agent Harness 的角色与边界

Agent Harness 是优化循环的"驾驶员"：负责构建代理、提供技能、生成变更、对变更打分，并通过沙箱安全地执行。整个 wmo/harness/ 目录遵循按职责拆分的命名约定：

这种拆分让用户可以单独替换提议策略或评分函数，而不必重新实现整套流水线。

2. 代理创建与技能注入

代理的初始化由 create.py 提供，模块导出用于构造 "harness 实例" 的工厂方法。在构造过程中，skills.py 把若干领域能力（如文件读写、命令执行、搜索代码）注册为代理可调用的工具。

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 在每个优化轮次中向世界模型递交的"动作"。它由以下三步组成，完整流水线如下：

flowchart LR
    A[当前世界模型] --> B[proposer.py<br/>生成候选提议]
    B --> C[project_proposer.py<br/>项目级筛选/合并]
    C --> D[mutate.py<br/>应用变异]
    D --> E[scoring.py<br/>评估与排序]
    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 沙箱，Harness 与沙箱的交互通常表现为：

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 命令的主要工作流。

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。

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 让"如何评估"和"如何搜

概述与定位

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-。

模块划分与职责

在 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-。

flowchart LR
    A[teacher.py<br/>教师前向] --> B[rollouts.py<br/>学生 Rollout]
    B --> C[samples.py<br/>样本/批次构造]
    C --> D[loop.py<br/>学生参数更新]
    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 <config>，其内部最终会调用 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-。

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。这种薄封装层让本地开发与生产托管共用同一套语义对象，避免出现"开发用一套类、生产用另一套类"的割裂。

本地服务器与 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。

端到端数据流

下面的流程图把上述模块串成一条从本地到托管平台的链路：

flowchart LR
    A[wmo serve] --> B[server.py]
    B --> C[chat.py<br/>Web UI]
    B --> D[endpoint_config.py]
    D --> E[builds.py<br/>托管产物]
    E --> F[托管平台]
    E --> G[savings.py<br/>节省摘要]

整体来看，wmo.serving 让用户从 pip install world-model-optimizer 之后的第一行 wmo --help 开始，就能在同一份代码语义下完成"本地调试 → 生产托管 → 成本可视化"三段式落地。

Pitfall Log / 踩坑日志

项目：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