Mosaic 将软件系统建模为带版本的本体，并通过这些本体模拟用户和系统操作，一直模拟到最小建模组件之间传递的假数据，包括重试、超时和注入的故障。

本仓库是第 1 个支柱的基础：一个由 Dolt 支持、带修订的本体存储，一个确定性模拟器，一个带技能的 agent CLI，以及一个 Web UI。docs/DESIGN.md 是契约：元模型、行为语言、模拟语义、API 和 CLI。

安装

需要 Go 1.27 或更新版本，以及 Node 20.9 或更新版本。请自行安装；安装脚本会检查它们，若任一缺失或版本过旧就会停止。Mosaic 还需要 Dolt 2.x，脚本会在缺失时安装它。

scripts/install.sh # 检查 Go 和 Node，按需安装 Dolt，构建 bin/，安装 Web UI 的依赖 scripts/install.sh --go-install # 同上，并把 mosaic 和 mosaicd 安装到 Go 的 bin 文件夹

不使用脚本时，你需要把 Dolt 放在 PATH 上；参见 Dolt 安装指南。

Dolt。脚本在 macOS 上会优先使用 Homebrew（如果可用）。否则会把最新发行版下载到 ~/.local/bin，无需 sudo；传 --prefix DIR 可选择其他文件夹。运行 scripts/install.sh --help 查看所有选项。

从任意位置运行 mosaic 和 mosaicd。--go-install 会把两个二进制文件放进 Go 的 bin 文件夹：若设置了 $GOBIN 则用它，否则用 $(go env GOPATH)/bin，通常是 ~/go/bin。确保该文件夹在 PATH 上，例如在 ~/.zshrc 或 ~/.bashrc 中：

export PATH="$(go env GOPATH)/bin:$PATH"

不用脚本的话，从克隆的仓库执行：

go install ./cmd/mosaic ./cmd/mosaicd

或者直接从 GitHub 安装：

go install github.com/xleelz/mosaic/cmd/mosaic@latest github.com/xleelz/mosaic/cmd/mosaicd@latest

为自己的仓库建模

对仓库建模的首选方式是使用 Claude，配合 .claude/skills 中的技能。Claude Code，或任何加载了这些技能的 Claude agent，在本仓库中启动时就会加载它们：

在 mosaicd 运行的情况下，在 mosaic 检出目录中启动 claude，然后提出例如“使用 mosaic-generate 技能为 ~/src/ 构建一个本体”，或者对小项目说“用 mosaic 为这个服务建模”。手写 YAML 并用 -f 应用（如下文“运行”所示）是手动路径，适用于小型模型和修改。

从检出目录执行，在 scripts/install.sh 之后，一条命令即可一起构建并运行 mosaicd 和 Web UI，并让它们保持最新：

scripts/serve.sh # mosaicd 在 127.0.0.1:7878，UI 在 http://127.0.0.1:3000 scripts/serve.sh --dev # UI 用 pnpm dev，而非生产构建 scripts/serve.sh --data-dir ~/.mosaic --addr 127.0.0.1:7878 --web-port 3000 -- --token "$MOSAIC_TOKEN"

两者的日志都输出到 stdout，分别以 [mosaicd] 和 [web] 为前缀；Ctrl-C 会同时停止两者。-- 之后的参数会传给 mosaicd。

更新。UI 顶栏中 mosaicd 徽标旁的标签会显示你正在运行的提交，当检出目录的上游有更新时会显示“N new commits”。点击它，然后 Update and restart：mosaicd 会快进检出目录（git merge --ff-only）并退出，serve.sh 会重新构建二进制文件和 UI 并重启两者；它们恢复后页面会重新加载。在终端中，mosaic version 显示同样的状态，mosaic update --yes 执行同样的更新。当检出目录对已跟踪文件有本地修改、有不在上游的提交，或不在带上游的分支上时，更新会被拒绝并给出原因；mosaicd --no-self-update 会关闭更新。

以下命令假设 mosaic 和 mosaicd 在 PATH 上：用 scripts/install.sh --go-install 或 go install 安装它们，并按上面所示把 Go 的 bin 文件夹加入 PATH。

mosaicd --data-dir ~/.mosaic & # 管理它自己的 dolt sql-server，在 127.0.0.1:7878 mosaic ontology create envoy-demo --name "Envoy proxy" mosaic apply envoy-demo -f examples/envoy/ontology.yaml -m "Model Envoy 1.36.2" mosaic test envoy-demo # 运行全部 22 个场景的预期 mosaic sim run envoy-demo --scenario upstream-503-retried --format summary

h1 挂起超过每次尝试 2 秒的超时，且重试熔断器已满：504，标志 UO,UT

mosaic sim run envoy-demo --flow downstream-request --fixture three-hosts
--fault backend-host.handle:timeout --state circuit-breakers.retries=3 --format summary

然后针对运行中的 mosaicd 启动 Web UI，打开 http://localhost:3000：

cd web && pnpm dev

Web UI 位于 web/。如果 mosaicd 监听在其他地址，设置 MOSAIC_SERVER；或设置 NEXT_PUBLIC_MOSAIC_FIXTURES=1 以使用从引擎生成的 fixture，无需守护进程。其标签页为系统的 Overview、Map、Flows 和 Runs，然后是模型的 Evidence 和 History。大型模型会打开其区域视图，运行会打开带跳转键的摘要。每个页面都显示一个 passport，说明该模型的可信程度：在已存储的情况下显示盲测基准和机制覆盖率，否则显示“Not benchmarked”。运行显示的一切都是模型的断言，而非关于真实系统的事实。按 / 搜索，按 ? 查看按键。

点击任意代码引用（path:line）会在浮动查看器中打开被引用的文件，由 mosaicd 从 GitHub 按模型的提交获取，并显示其所支撑的断言、语法着色和 vim 按键；私有仓库需要在 mosaicd 运行处配置 GITHUB_TOKEN 或 gh auth login。

Map 标签页显示 Envoy 模型的组件（按父级嵌套）以及它们之间的调用：

一次模拟运行，暂停在 upstream-503-retried 中途：h1 的 503 返回，路由器的重试策略在退避后发送第 2 次尝试。时序图、检查器、状态账本和架构图都跟随播放光标：

examples/envoy 建模了一个通过 v1.36.2 的 Envoy 代理的下游 HTTP 请求：监听器的过滤器链匹配、HTTP 连接管理器及其头部大小限制、本地限流和 RBAC 过滤器、路由表（先是虚拟主机，然后是路由，包含直接响应和重定向），以及路由器过滤器的超时和重试策略，作用于一个带熔断器和异常点检测的轮询集群。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）