lizard

Lizard - 引导

这是一个精简的入口。权威指南位于 lizard CLI 内部，并与其一同进行版本管理，因此始终与已安装的 CLI 版本一致。

**保持乐观：**假设 CLI 已可用。先尝试加载核心指南；只有在命令实际失败时，才提供安装或权限方面的帮助。

请勿根据此文件自行编造 lizard 命令——完整说明、标志和退出代码均来自已加载的核心指南。

绝不要通过 npx 运行 CLI（例如 npx @lizard-build/cli、npx lizard 等）。 始终使用全局安装的 lizard 二进制文件。npx 会将临时副本拉取到缓存中，其版本可能与已加载的指南不一致，也会绕过下方的安装流程。如果 lizard 不在 PATH 中，请安装它（步骤 2a）——不要使用 npx，即使只是检查它是否可用也不行。

步骤 1 - 加载核心指南（优先尝试）

立即运行：

lizard upgrade --check --json
lizard skills get core --json

指南随 CLI 一同发布，因此旧版 CLI 提供的是旧命令（沙盒模板和旧机器上通常会有旧版 CLI）。如果检查结果显示 updateAvailable: true，请运行 lizard upgrade --json，然后重新加载指南。如果返回 upgraded: false 并附有 hint，请运行该提示中的命令（例如 npm install -g @lizard-build/cli@latest）。检查失败（离线、受速率限制）并不构成停止的理由：继续使用现有指南。

lizard skills get core --json 会返回 { name, frontmatter, content, references, ... }。请完整阅读 content——这是涵盖整个平台的最新 Lizard 指南，包括沙盒、部署、附加组件、登录、退出代码和计费。后续任务都应遵循该指南。

references 列出三份更深入的指南：sandboxes、deploys 和 sdk（通过代码使用 Lizard）。只有任务需要深入了解时才加载：

lizard skills get core --ref sdk --json

如果 CLI 不接受 --ref（4.0.45 之前的版本），请跳过：这些版本的 content 已包含全部内容。

如果成功加载，请跳过步骤 2 中的故障恢复，直接前往步骤 4执行操作——假设用户已登录。不要运行 command -v lizard，不要提前登录，也不要安装上述升级之外的任何内容。只有当命令明确报告未通过身份验证时，才转到步骤 3。

步骤 2 - 仅在失败时恢复

按顺序处理步骤 1 中的失败。一旦某条路径奏效，就停止并返回指南。

2a. lizard: command not found（CLI 不在 PATH 中）

在 macOS 或 Linux 上，使用安装脚本安装，然后重试步骤 1：

curl -fsSL https://lizard.build/install.sh | bash

它无需 Node.js 或 sudo，且二进制文件会自行更新。它还会将 lizard 链接到一个已位于 PATH 中的目录，因此 CLI 可立即在本次会话中使用。如果脚本最后几行提示可能找不到 lizard，则在本次会话剩余时间内通过 ~/.lizard/bin/lizard 调用它。如果提示 PATH 中另一个 lizard 排在前面，请告知用户：这通常是旧的 npm 安装，运行 npm uninstall -g @lizard-build/cli 即可移除。

脚本最后会执行登录。如果机器尚未登录，最后几行会输出一个带有 status: "pending" 和登录链接的 JSON 对象：请按照步骤 3 中的说明将链接提供给用户。

在 Windows 上，或者脚本无法运行时（没有 curl、系统不受支持、下载失败），请改用 npm 安装：

npm install -g @lizard-build/cli

2b. 安装因权限错误而失败

请勿使用 sudo 重试。在 macOS 或 Linux 上，请使用步骤 2a 中的安装脚本：它会安装到用户主目录中，无需管理员权限。

如果 npm 因 EACCES 失败，请让用户在自己的终端中运行安装命令（在支持会话内 shell 直通的 Agent 中，例如 Claude Code 或 Cursor，用户可以输入 ! npm install -g @lizard-build/cli）。如果再次失败，建议使用 Node 版本管理器（fnm、nvm、mise），以便将全局二进制文件安装到用户可写入的目录中。

用户确认安装完成后，重试 lizard skills get core --json。

2c. 核心指南不可用（CLI 过旧、处于离线状态或缺少 skills 命令）

运行任何操作前，先回退到运行时发现：

lizard --help --json
lizard <cmd> --help --json

如果 CLI 过旧，请建议更新：lizard upgrade。

Step 3 - 登录（仅在需要时）

不要主动登录。保持乐观，假设用户已登录。 通常不需要运行 lizard login，因为登录链接会自动提供给你：

• 如果安装脚本暂时无法完成登录，链接会出现在脚本末尾几行中（Step 2a）；
• 如果任何命令因退出代码 2 而失败，链接会出现在 JSON 错误的 error.body.login 中。

两者的结构相同：status: "pending"、包含每种登录方式（github、google）各一个链接的 authUrls，以及 instruction。进程不会等待，也不会打开浏览器。询问用户如何登录 Lizard，并将相应链接作为可点击的 URL 提供给他们。已有账户的用户必须使用之前相同的方式登录：使用其他方式会创建第二个空账户，除非两种方式绑定了已验证的邮箱。新用户可以任选一种方式。

用户表示浏览器显示“CLI authorized”后，重新运行失败的命令；如果刚完成安装，则继续操作：下一个 lizard 命令会接续登录。如果仍报告 pending，说明他们尚未完成操作；请等待并重试。链接有效期为 5 分钟，下次运行会生成新链接。

退出代码为 2 的错误如果不包含链接，说明错误来自 CI，或平台无法访问：此时请稍后重试，或运行 lizard login --json，该命令会输出相同的对象。在 CI 或服务器上，没有人能打开链接：请索要 API 令牌并设置 LIZARD_TOKEN，或运行 printf '%s' "$TOKEN" | lizard login --token-stdin 保存令牌。在用户自己的终端中，! lizard login 会询问要使用 GitHub 还是 Google，并打开浏览器。

Step 4 - 执行

如果 $ARGUMENTS 非空，将其视为用户的请求，并使用第 1 步中的指南（或第 2 步中的恢复流程）处理。如果为空，则询问用户想在 Lizard 上做什么。