Lima 仓库 AI 编码代理开发指南构建、测试、代码地图与工程规范【免费下载链接】limaLinux virtual machines, with a focus on running containers项目地址: https://gitcode.com/GitHub_Trending/lim/limaLimagithub.com/lima-vm/lima/v2是一个以运行容器为目标的 Linux 虚拟机管理工具其仓库根目录的 AGENTS.md 是面向 AI 编码代理AI coding agent的权威开发入口文档。本文以该文档为骨架结合仓库中的 Makefile、go.mod 与pkg/下核心源码系统梳理 Lima 的构建产物、测试分层、模块地图与提交规范帮助开发者和 AI Agent 快速掌握在 Lima 代码库中能改什么、怎么验证、改完如何提交的完整工作流。AGENTS.md 的设计一份指针式开发指南AGENTS.md 开篇就说明了自身定位它为在 Lima 仓库中工作的 AI 编码代理提供指引但不复制文档内容而是指向权威文档It points to the authoritative docs instead of duplicating them, so it stays in sync with the code。这意味着仓库维护者只需更新一处权威文档AGENTS.md 与代码不会因重复拷贝而失步读者包括 AI Agent需要沿着指针去阅读权威来源而非依赖摘要。全文四个板块覆盖了开发者的完整诉求AI 协作贡献规则、构建/测试/lint 命令、代码所在位置Where things are、工程约定Conventions。下面逐一展开并补充源码级证据。AI 贡献规则人与 AI 协作的边界AGENTS.md 要求所有 AI 辅助贡献遵循 website/content/en/docs/community/contributing.md 中的 AI Contribution Rules 小节。其核心规则包括人类对全部内容负责无论 PR 内容是人类撰写还是 AI 生成提交者都必须逐条审查、编辑并确保描述准确无错评审意见也应由人类自己回复而不是依赖 AI 工具代答。法律签署DCOAI 工具无法在法律意义上签署代码。只有提交代码的人类可以添加Signed-off-by行对应 Developer Certificate of Origin 1.1 版。使用 AI 生成代码时必须提交前阅读并检查全部生成代码、添加自己的Signed-off-by标记、对提交的代码负全部责任。披露 AI 使用如果使用 AI 工具需要在 PR 描述中以Assisted-by: AI_TOOL_NAME尾注trailer披露AI 工具添加的Co-Authored-By尾注也可接受不会阻塞合并。执行机制不遵守上述规则的 PR 可能被维护者关闭提交者可在认为关闭不当时在 PR 中留言申诉。此外contributing.md 还明确了通用的 PR 规范先开 issue 沟通再写代码小修复、简单依赖升级等例外、一个 PR 只修一个问题、非平凡改动尽量写成单元测试以避免拖慢集成测试 CI、合并前通常需要 squash 为单个 commit 并 rebase 到最新master。构建体系Makefile 与_output/产物布局模块路径与构建入口Lima 的 Go 模块路径带/v2后缀见 go.mod 第 2 行module github.com/lima-vm/lima/v2所有 import 都要使用/v2前缀。构建由 GNU Makefile 驱动所有产物输出到_output/目录。从 Makefile 的help-targets可以看出_output/内的三类关键产物_output/bin/limactl主 CLI、lima/lima.bat启动脚本、nerdctl.lima、apptainer.lima、docker.lima、podman.lima、kubectl.lima等 helper_output/libexec/lima/limactl-mcp、limactl-url-fedora-rawhide以及可选的lima-driver-*外部驱动二进制_output/share/lima/各架构的lima-guestagent.*、templates/含_default/、_images/、experimental/以及_output/share/doc/lima文档与_output/share/man/man1手册页。版本号通过git describe --match v[0-9]*自动推导Makefile 第 65 行并借助-ldflags -X $(PACKAGE)/pkg/version.Version$(VERSION)嵌入二进制从非 git 仓库构建时需要显式指定make VERSIONvX.Y.Z。两个核心构建目标AGENTS.md 推荐开发者优先使用make native需要最小构建时使用make minimalmake native # 构建 limactl 原生 guestagent 全部模板最快的完整开发构建 make minimal # 仅构建 limactl 原生 guestagent default 模板对照 Makefile 第 190-192 行两个目标的依赖链非常清晰minimal: clean limactl native-guestagent default_template native: clean limactl limactl-plugins helpers native-guestagent templates template_experimentals additional-drivers也就是说make minimal产出_output/bin/limactl、_output/share/lima/lima-guestagent.Linux-arch及 macOS 上的 Darwin guestagent和templates/default.yaml适合快速验证 CLI 改动make native额外构建limactl-mcp等插件、nerdctl.lima等 helper、全部模板含实验性模板以及ADDITIONAL_DRIVERS声明的外部驱动是完整的本地开发构建。平台适配与构建变量Makefile 中还有大量与平台相关的构建逻辑值得开发者了解构建标签GO_BUILDTAGS会根据平台自动追加。macOS SDK 版本低于 13 时追加no_vzvz模式需要 macOS 13 SDKWindows 版本过低时追加no_wslWSL2 驱动需要 build ≥ 19041。启用外部驱动时会追加external_vz、external_qemu、external_wsl2标签Makefile 第 294-306 行。附加驱动ADDITIONAL_DRIVERS默认值取决于平台——macOS 14 的 arm64 上默认启用krunkitMakefile 第 33-41 行可通过变量覆盖。guestagent 架构矩阵Linux guestagent 支持aarch64、armv7l、ppc64le、riscv64、s390x、x86_64六个架构Darwin 仅aarch64每个架构通过ENVS_*指定CGO_ENABLED0 GOOSlinux GOARCH...等交叉编译参数Makefile 第 425-432 行。产物默认 gzip 压缩为.gz。limactl 必须开启 CGOMakefile 第 290-292 行注释说明hostagent随 limactl 构建必须以CGO_ENABLED1编译使 DNS 服务器中的net.LookupIP()调用原生解析器而非 Go 库中的简化实现。安装与清理构建完成后可执行make native install安装到$(PREFIX)默认/usr/local。install 使用 tar 而非 cp 以更好地处理符号链接卸载用make uninstall清理构建产物用make clean。测试分层单元测试、BATS 集成测试与模板测试AGENTS.md 明确了一条关键纪律单元测试绝不启动 VM任何会启动 VM 的测试都属于 BATS 或模板测试。go test ./... # 单元测试永不启动 VM make bats # 集成测试BATS启动真实 VM需要 git submodules单元测试go test ./...纯 Go 单元测试覆盖pkg/与cmd/下所有包例如 pkg/limayaml/validate_test.go、pkg/cidata/cidata_test.go、pkg/store/store_test.go 等。由于不启动 VM改动配置解析、模板渲染、磁盘格式等逻辑时优先补充这类测试以加快 CI。BATS 集成测试make batsmake bats的完整定义在 Makefile 第 612-614 行bats: native limactl-plugins PATH$$PWD/_output/bin:$$PATH ./hack/bats/lib/bats-core/bin/bats --timing ./hack/bats/tests它会先执行native构建再把_output/bin加入 PATH用 BATS 框架运行 hack/bats/tests/ 下的集成用例。运行前提是初始化 git submodulesBATS 框架本体bats-core、bats-assert、bats-file、bats-support都挂在 hack/bats/lib/ 下。从 hack/bats/helpers/load.bash 可见测试默认使用独立的LIMA_HOME$HOME/.lima-bats避免破坏真实~/.lima中的_config、_templates等数据并支持通过LIMA_BATS_ALL_TESTS_RETRIES对已知 flaky 用例重试。现有测试套件覆盖了相当广的功能面例如shell.bats验证limactl shell对已停止实例、不存在实例、--instance参数解析等错误路径的报错行为copy.bats验证limactl copy在不同后端下对SRC/SRC//DST/DST/四种路径组合的目录拷贝语义mcp.bats启动limactl mcp serve以 JSON-RPC 逐条断言 MCP 协议的initialize、工具调用与自增 ID 行为path.bats验证 guest 主目录同时可通过.guest与.linux路径访问其他如list.bats、protect.bats、param.bats、preserve-env.bats、passwordless-sudo.bats、yq.bats、url-github.bats。模板测试hack/test-templates.sh凡是改动模板或 guest 初始化逻辑的需要跑模板冒烟测试。AGENTS.md 给出的示例是./hack/test-templates.sh ./templates/default.yaml该脚本位于 hack/test-templates.sh配合 hack/bats/extras/ 下的 k8s、colima、port-monitor 等额外套件用于验证真实镜像在目标驱动下能否完整启动。提交要求git commit -s每个 commit 必须带 DCO 签名git commit -s否则 CI 会失败。这与上文 AI 贡献规则中的只有人类可以签名是一致的签名行Signed-off-by: REAL NAME emailexample.com是法律声明不可由 AI 工具代签。代码地图Where things areAGENTS.md 的核心价值在于给出了一张权威来源索引下面结合源码逐一深入。架构与内部数据internals.mdwebsite/content/en/docs/dev/internals.md 是了解 Lima 内部数据结构的权威文档涵盖三块内容三大进程架构limactlCLI 前端→hostagent宿主机侧守护见 pkg/hostagent/→guestagentguest 内守护见 pkg/guestagent/ 与 cmd/lima-guestagent。limactl start最终在后台拉起 hostagenthostagent 再驱动 VM 并监听 guest 事件。${LIMA_HOME}磁盘布局默认~/.lima有意避开 macOS 的~/Library/Application Support/Lima因为 socket 路径在 macOS 上必须短于 104 字符。其中_config/存放全局身份user、user.pub私钥/公钥每个实例目录存放lima.yaml、cidata.iso、disk、serial.log、ssh.sock、ha.pid、ha.sock等元数据另有_disk/数据盘目录、_templates/用户模板目录以及按平台区分的缓存目录macOS~/Library/Caches/lima、Linux$XDG_CACHE_HOME/lima、Windows%LocalAppData%\lima。每一个LIMA_CIDATA_*变量从LIMA_CIDATA_DEBUG、LIMA_CIDATA_IID每次启动重新生成到LIMA_CIDATA_MOUNTS_%d_MOUNTPOINT、LIMA_CIDATA_DISK_%d_*、LIMA_CIDATA_SLIRP_*、LIMA_CIDATA_VMTYPE等数十个变量全部在文档中逐一列出语义。这些变量在 guest 内boot.sh执行期间可用其来源可以在 pkg/cidata/template.go 的TemplateArgs结构体中找到一一对应关系。配置与数据模型pkg/limatype 与 pkg/limayamlpkg/limatype/ 定义核心数据模型LimaYAMLpkg/limatype/lima_yaml.go与Instancepkg/limatype/lima_instance.go以及dirnames、filenames等路径常量包。pkg/limayaml/ 承担配置的加载/默认值/校验三段职责加载load.go 的Load/LoadWithWarnings不仅解析用户 YAML还会把${LIMA_HOME}/_config/default.yaml与_config/override.yaml按层混合进来第 45-60 行形成默认值 → 覆盖值 → 用户配置的合并语义默认值defaults.go及defaults_unix.go/defaults_windows.go通过FillDefaults补齐未指定字段例如把非法的 Linux 用户名替换为Lima并给出警告校验validate.go 的Validate检查字段合法性如base必须为空、minimumLimaVersion约束等。模板机制pkg/limatmpl 与 pkg/templatestorepkg/limatmpl/ 负责模板解析与定位template.go处理模板语法embed.go通过go:embed内嵌仓库内模板github.go与locator.go负责把形如https://...或本地路径的模板来源解析为实际文件abs.go处理路径绝对化。pkg/templatestore/templatestore.go 负责模板存储它支持把额外模板放入${LIMA_HOME}/_templates且该目录在未设置$LIMA_TEMPLATES_PATH时优先于系统自带的/usr/local/share/lima/templates被搜索。虚拟化后端pkg/driver/pkg/driver/driver.go 定义了统一的Driver接口由LifecycleValidate/Create/CreateDisk/Start/Stop/Delete/InspectStatus/BootScripts、GUI、SnapshotManager、GuestAgent以及Info、Configure、SSHAddress、AdditionalSetupForSSH组合而成Info中的DriverFeatures通过SupportedImageFormats如raw、qcow2、DynamicSSHAddress、StaticSSHPort、NoCloudInit、RosettaEnabled等能力位让 hostagent 和 cidata 生成逻辑按驱动差异自适应。具体实现位于pkg/driver/qemu/QEMU 后端pkg/driver/vz/Apple Virtualization.framework 后端仅 macOSpkg/driver/wsl2/WSL2 后端仅 Windowspkg/driver/hcs/Windows HCS 后端pkg/driver/krunkit/macOS arm64 上的 krunkit 后端pkg/driver/external/基于 gRPC 的外部驱动协议driver.proto使驱动可以独立进程运行单个 Lima 实例对应一个外部驱动服务进程见 internals.md 中driver-name.drv.pid/.drv.sock的描述。Guest 初始化pkg/cidata/ 与 cidata.isopkg/cidata/ 负责构建注入 guest 的cidata.isocloud-init NoCloud 数据源卷标固定为cidata。其核心函数在 cidata.goGenerateCloudConfig第 365 行生成仅用于参考的cloud-config.yamlWindows guest 不生成GenerateISO9660第 398 行把user-data、meta-data、network-config、lima.env、param.env、lima-guestagent二进制、nerdctl-full.tgz、boot.sh、boot.OS/*与boot.essential.OS/*模块、provision.*目录以及驱动注入的BootScripts一起打包成 ISO9660 镜像ISO9660 要求文件名长度 ≤ 30 字符注释见第 475 行GenerateWindowsISO第 587 行Windows 使用autounattend卷标与独立的 wincidata.TEMPLATE.d/ 模板并生成 16 位初始密码、按 ISO 标签区分 Windows 11 与 Server 2025。正如 AGENTS.md 所强调的user-data采用 cloud-init 定义的 cloud-config YAML 格式模板位于 pkg/cidata/cidata.TEMPLATE.d/user-dataguest 端即便不使用 Python cloud-init 实现也可以用其他实现消费。模板渲染入口是 pkg/cidata/template.go 的ExecuteTemplateCIDataISO/ExecuteTemplateWindowsISOTemplateArgs第 91-140 行中User、Mounts、Disks、Containerd、Provision、CACerts、DNSAddresses、VSockPort、VirtioPort等字段与上文LIMA_CIDATA_*变量一一对应。实例生命周期pkg/instance/pkg/instance/ 承载实例的创建与生命周期管理包括create.go、start.go、stop.go、delete.go、restart.go、clone.go、ansible.go。以 start.go 为例启动链路是StartWithPaths第 224 行先检查ha.pid判断实例是否已在运行Prepare第 55 行创建驱动实例driverutil.CreateConfiguredDriver、校验 YAML、按需下载镜像/内核/initrd通过fileutils.DownloadFile与SupportedImageFormats做格式转换、CreateDisk、prepareDisk用go-qcow2reader读取 qcow2/vhdx 并自动扩容缩小磁盘会直接报错在后台以limactl hostagent --pidfile ... --socket ...拉起 hostagent 进程并把日志写入ha.stdout.log/ha.stderr.logwatchHostAgentEvents第 364 行订阅 hostagent 事件流等待running状态事件——默认超时 10 分钟Windows 首次启动为 30 分钟见第 42-46 行收到事件后打印 READY. Runlimactl shell name(或lima) to open the shell.若状态为Degraded则提示文件共享与端口转发可能不可用。工程约定SPDX 头与 go.mod 注解SPDX 头与 ltagAGENTS.md 的约定是新增的 Go、shell、Dockerfile 和 Makefile 文件必须带 SPDX 头例如// SPDX-FileCopyrightText: Copyright The Lima Authors与// SPDX-License-Identifier: Apache-2.0由ltag在 CI 中强制检查其他文件类型包括 markdown豁免。ltag的 lint 目标定义在 Makefile 第 659-661 行ltag: $(GO) run -modfile./hack/tools/go.mod github.com/containerd/ltag -t ./hack/ltag --check --excludes vendor _output -v模板文件位于 hack/ltag/go.txt、bash.txt、dockerfile.txt、makefile.txt维护各语言文件的模板格式。make lint是上述 ltag 与 editorconfig-checker、golangci-lint、yamllint、ls-lint、shellcheck、shfmt、go-licenses、gosocialcheck、protolint 的汇总目标Makefile 第 669 行。gomodjail / gosocialcheck 注解AGENTS.md 要求保持 go.mod 中的gomodjail/gosocialcheck注解。从 go.mod 可见其用法模块头部// gomodjail:confined声明主模块受限依赖项按信任级别标注如github.com/lima-vm/sshocker v0.3.11 // gomodjail:unconfined、golang.org/x/sys v0.47.0 // gomodjail:unconfined同时有//gosocialcheck:trusted分组注释配合gosocialcheck工具Makefile 第 654-657 行在 CI 中对依赖的社会属性如维护组织、许可做审计。新增依赖时如果不理解这些注解的语义很容易被 CI 拒绝因此 AGENTS.md 特意提醒保持Keep而不是移除。从 AGENTS.md 出发的快速开发工作流综合全文一个典型的 Lima 代码改动循环可以归纳为定位代码按 Where things are 找到权威来源——架构细节读 website/content/en/docs/dev/internals.md配置模型看 pkg/limayaml/驱动看 pkg/driver/guest 初始化看 pkg/cidata/生命周期看 pkg/instance/写单元测试用go test ./...验证纯逻辑改动配置解析、模板渲染、校验规则等不启动 VM完整构建make native快速全量开发构建或make minimal只验证 CLI guestagent 默认模板静态检查make lint跑全部 lint 阶段确保新增 Go/shell/Dockerfile/Makefile 文件带 SPDX 头、go.mod 注解未被破坏修改 .proto 后执行make generate重新生成 protobuf并用make check-generated即git diff --exit-code确认生成物已提交集成验证涉及真实 VM 行为的改动跑make bats需先初始化 git submodules涉及模板的改动跑./hack/test-templates.sh ./templates/default.yaml合规提交每个 commit 用git commit -s添加 DCO 签名AI 生成内容需人工审查并在 PR 描述中通过Assisted-by:尾注披露。这份文档的价值在于它把 Lima 这样一个跨平台QEMU / vz / WSL2 / HCS / krunkit、多进程limactl / hostagent / guestagent、配置与 provisioning 链路复杂的项目浓缩成了一份 AI Agent 也能直接执行的开发 SOP。开发者与 AI 协作工具只要沿着 AGENTS.md 的指针就能在正确的权威文档与源码之间快速定位避免在不复制、不同步的前提下迷失在庞大的代码库中。【免费下载链接】limaLinux virtual machines, with a focus on running containers项目地址: https://gitcode.com/GitHub_Trending/lim/lima创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考