miles

Miles AI 网站设计师

Miles 是一款 AI 网站设计师，你可以通过一套可组合的 CLI 基元来驱动它。每个基元只负责一项任务，输出结构化 JSON 和有意义的退出码；当用户需要完整体验时，这些基元会串联起来，完成整个引导式设计工作流。你可以完成整个流程（需求访谈 → 设计简报 → 设计方向 → 构建 → WordPress 主题），也可以直接跳到所需步骤。

通过随附的 CLI 运行每条命令。$MILES_CLI 表示此技能的 scripts/miles 启动器路径：

MILES_SKILL_DIR="${MILES_SKILL_DIR:-/path/to/miles}"
MILES_CLI="${MILES_CLI:-$MILES_SKILL_DIR/scripts/miles}"
"$MILES_CLI" doctor --json

对于长时间运行的命令，请将 Bash 超时时间设为 10 分钟（600000ms）——构建网站和转换主题都需要几分钟。使用 MILES_HOME=/path/to/isolated/state 创建干净的测试环境（默认为 ~/.miles）。

命令概览

这是受支持的公共命令范围。不要自行编造其他命令。HEADLESS = 无需浏览器即可运行。CONDITIONAL = 只有底层回合不是由浏览器驱动时，才能在无头模式下完成。BROWSER = 需要先通过 connect-browser 连接仪表板。LOCAL = 文件系统辅助工具；其中任何 Miles 服务端操作仍受能力限制。references/ 中的参考文件包含各条命令的标志、JSON 架构和判断标准；使用命令时请加载这些文件。

命令	模式	功能	参考
miles auth [login|poll|status|logout]	HEADLESS	设备代码登录流程	auth.md
miles account-status --json	HEADLESS	套餐、额度、站点数量 — 检查剩余额度	account-status.md
miles site-create "<description>" [--brief <file>] [--attach <file>]	HEADLESS	创建新的云端站点和对话，或在当前配对的本地 WordPress 站点上创建对话；--brief 可跳过需求探索	site-create.md
miles say "<message>" [--attach <file>]	HEADLESS*	与 Miles 对话：获取答复、提供简要反馈、进行编辑	say.md
miles upload-assets <file> [...]	HEADLESS	上传品牌素材（徽标、图片、内容文档）→ 可重复使用的引用	upload-assets.md
miles design-directions --json	HEADLESS	列出生成的设计方向及其 ID 和预览	design-directions.md
miles build-site --design <n>	HEADLESS	确认设计 → 构建完整的 HTML 站点	build-site.md
miles wait-job / miles cancel	HEADLESS	等待 / 停止正在运行的轮次（JSON + 退出代码）	wait-job.md
miles approval-respond --grant <id> --response approved|declined	CONDITIONAL	在用户明确同意 / 拒绝后，回复受保护的线上站点审批请求	live-protection.md
miles undo	HEADLESS	撤销上一轮：同时还原站点和聊天，仅限一级	undo.md
miles site-state [--full] --json	HEADLESS	阶段、设计方向、连接状态、站点计划、建议的下一步；--full 会附加需求文本、设计方向详情和会话记忆	site-state.md
miles site-plan [--history] --json	HEADLESS	无损获取当前站点计划；可选择包含去重后的修订记录和条目级变更	site-plan.md
miles site-attach <siteId> [--duplicate]	HEADLESS	恢复任意自有站点；进行高风险更改前先创建分支	site-attach.md
miles wordpress-detect --json	LOCAL	被动检测当前文件夹或其上级目录中的本地 WordPress 安装	wordpress-detect.md
miles wordpress-setup --use local --json	LOCAL	在指定的本地 WordPress 安装上安装 / 激活 / 连接 Miles	wordpress-setup.md
miles site-pages [path]	HEADLESS	列出已构建站点的文件，或获取单个文件的内容	site-pages.md
miles history [--limit <n>] [--offset <n>]	HEADLESS	分页获取对话记录，默认显示最新轮次	history.md
miles screenshot <preview-url> [--full-page]	HEADLESS	将任意预览截图保存为本地 JPEG	screenshot.md
miles screenshot --live [--viewport]	BROWSER	通过已连接的控制面板，截取线上 WordPress 前端	screenshot.md
miles export [--type html|theme] [--download <file>]	HEADLESS*	获取交付物 URL；--download 会流式下载主题 ZIP（由浏览器支持）	export.md
miles rename "<name>"	HEADLESS	重命名站点的对话	rename.md
miles usage-history	HEADLESS	查看账户的额度交易记录	usage-history.md
miles connect-browser [--open] [--wait]	—	唯一明确的浏览器入口：获取已通过身份验证的控制面板 URL 和连接状态	connect-browser.md
miles convert-theme	BROWSER	将 HTML 站点转换为 WordPress 区块主题	convert-theme.md
支持的动词：doctor、status、sites、use、messages、balance、wait。较早的动词名称（create-site、reply、select-design-direction、preview、build-theme、export-site、export-theme、login、whoami、logout）仍可作为别名使用。

* say 在发现、简介和构建前反馈阶段无需浏览器。对已构建的 WordPress 站点进行编辑则需要浏览器支持：如果缺少连接，CLI 会立即失败并以退出码 3 退出。approval-respond 可以在无头模式下响应授权，但恢复受保护的工作后，仍可能需要仪表板。export --type html 完全支持无头模式。

CLI 会自动检查已连接服务支持的原语（miles doctor --json 会在 server.primitives 下显示这些原语；不会在此处列出每个原语的操作，CLI 会在命令内部检查这些操作）。如果服务缺少某个服务端原语，说明该服务版本早于此原语——不要尝试绕过；请告知用户。如果能力检查完全无法连接服务，命令会以退出码 2 退出，并返回 capabilities_unreachable 和 safeToRetry: true——这是暂时性故障，而不是缺少原语。wordpress-setup --use local 特别需要 wordpress-bootstrap；在服务包含该原语之前，它会以退出码 2 退出，而不会触碰本地 WordPress 安装。在配对的本地站点上开始设计还需要 site-create.operations.local-wordpress 操作。如果该操作不可用，site-create 会在上传、远程修改或消耗额度之前以退出码 2 退出；绝不能回退到云端站点。

退出码和结果

所有动词共用一套退出码规则。根据代码分支处理，而不是根据文字描述：

• 0 — 已完成
• 1 — 失败或已中止（请查看错误，不要盲目重试）
• 2 — 缺少前置条件（未登录、没有活动站点、不支持该原语、用法错误）
• 3 — 需要连接：打开 connect-browser --json 返回的 URL，等待 connected: true，然后重试同一命令一次
• 4 — 已阻止、需要授权或已拒绝：请求的工作并未执行
• 5 — 容量不足：已有其他轮次正在运行，或服务已满载；请等待后重试

已结束的轮次还会在 wait-job JSON 中携带 outcome（completed | blocked | declined | aborted | need_connection | capacity | failed），并在流式输出中显示为 [outcome: ...]。切勿因为命令输出了文字就认定成功。declined 结果表示用户拒绝了——不要重试，也不要绕过拒绝。详情：outcomes.md。

无头模式与浏览器的边界

直到并包括已构建的 HTML 站点为止，所有操作都支持无头模式：发现、简介、设计方向、完整站点构建、截图和 HTML 导出。浏览器介入的分界点正好位于“已构建的 HTML 站点”和“WordPress”之间：主题转换以及对已转换 WordPress 站点的编辑，都需要通过已连接的仪表板浏览器进行。

connect-browser 是唯一明确且可查询的连接关卡——绝不会在命令执行过程中突然要求连接。需要浏览器的命令会立即失败并以退出码 3 退出；连接后重试一次即可。进行无头操作前不要提前打开仪表板；但如果用户想实时观看设计生成或站点构建，则应打开仪表板（这是查看进度的最佳界面）。有关按主机映射浏览器工具和恢复连接的信息，请参阅：browser.md。

实时保护授权是独立于浏览器连接的安全关卡。当 wait-job、status 或 site-state 返回 approvalRequired 时，请停止操作，并询问用户是否批准或拒绝这项具体的受保护变更。**切勿通过 say 响应该授权，也绝不能从原始任务、沉默、“继续”或笼统的肯定答复中推断用户已批准。**只有在用户的最新消息明确批准或拒绝了这项具体的待处理变更后，才能运行 miles approval-respond --grant <id> --response approved|declined。无法通过此技能锁定或解锁 Miles 本身；请告知用户使用 Miles 应用中的控件。详情：live-protection.md。

WordPress 站点选择

当用户想使用 WordPress 时，先与用户确定 WordPress 目标。安全的默认选择是 Miles 云端，除非用户明确选择本地或远程 WordPress 站点。

你可以在询问前运行被动的本地结构检查：

"$MILES_CLI" wordpress-detect --json

此命令必须仅用于被动检查：它可以检查文件名并报告当前文件夹是否看起来像 WordPress，但不得执行 WordPress、WP-CLI、PHP、插件、主题或基于数据库的检查。如果 localWordPress.found 为 false，则继续常规云端流程（site-create）。如果为 true，请直接询问用户一个问题：使用 Miles 云端、此本地 WordPress 安装，还是远程 WordPress 站点？不得仅因检测到本地站点就默认使用它。详情：wordpress-detect.md。

当用户选择本地站点时，运行：

"$MILES_CLI" wordpress-setup --use local --json

设置命令是明确征得本地操作许可的边界。在复制或激活任何内容之前，它要求服务端支持 wordpress-bootstrap。当 WP-CLI 能够报告 WordPress 版本时，它会在复制或激活前检查 Miles 插件标头；如果站点不兼容，则以状态码 2 退出，并显示检测到的版本和所需版本；如果没有 WP-CLI，则版本未知，文件会未经检查地复制，并转入手动交接流程。它可能会将 Miles 插件文件下载到 wp-content/plugins/miles，或者仅在明确设置了 MILES_PLUGIN_SOURCE 时复制本地插件源；当 WP-CLI 可用时，它还可以激活插件，在应用程序密码需要时为明显属于本地/开发环境的 URL 配置 WP_ENVIRONMENT_TYPE=local，向 Miles API 请求本地站点凭据，将这些凭据交给 wp miles local-setup，并将本地 WordPress 管理页面保存为当前 Miles 操作界面。WP-CLI 是可选的：如果缺失，或无法加载本地站点的数据库/运行时环境，则回退方案是由用户执行操作的交接，而不是假设 Agent 可以点击。对于容器化安装，请使用文档中说明的官方 Docker WP-CLI 适配器。请用户打开 adminPluginsUrl，并在出现提示时登录 WordPress；仅当无法自动激活时，才请用户激活 Miles。用户确认激活后，请其打开 milesAdminUrl 并完成插件设置流程。如果宿主环境支持浏览器自动化，且用户已通过身份验证，则可以使用浏览器自动化辅助操作，但此技能必须能够在不假设具备任何点击能力的情况下正常工作。不得自行写入插件选项或密钥。详情：wordpress-setup.md。

本地 WordPress 站点激活后，它就成为唯一目标锁定。将云端站点视为不存在：sites 仅返回该本地站点，use 无法切换到其他站点，site-attach 无法附加或复制其他站点，account-status 不查询或统计云端站点。所有构建、编辑、转换、导出和浏览器交接操作都必须针对完全匹配的配对本地站点。唯一支持的退出方式是用户明确选择后运行 miles wordpress-setup --use cloud --json；这会清除当前本地站点选择，但保留其已保存的配对信息以供日后重用。切勿仅为绕过本地功能缺失而运行此命令。

对于位于远程域名上的 WordPress 站点，不要尝试从文件系统安装或引导该站点。提供 wordpress-setup 输出或发布清单中的 Miles 插件链接，请用户手动安装，并在安装后使用插件的配对流程。

选择你的入口

状态源自对话，并且是单调的——你可以从符合现有工作进度的任意任务开始。访谈只是众多基本操作之一，并非整个流程的容器。

• “帮我做个网站”（用户在场，想要体验整个过程） → 运行完整的引导式工作流：将 Miles 的访谈转述给用户，展示简介，提供设计方向，然后开始构建。加载 full-workflow.md——其中包含转述规则、简介审阅模板和进度展示风格。
• 已有另一个 Miles 网站在运行时说“帮我做个新网站” → 不要通过当前网站上的 say 发送这条提示。如果意图不明确，就简短询问一次。在已配对的本地 WordPress 网站上，site-create 表示在那个确切的网站上开始新设计；它绝不会创建云端备用方案。在云端网站上，它会创建一个独立交付成果。如果用户想重新设计现有云端网站，请明确说明，并考虑在进行高风险更改前使用 site-attach <siteId> --duplicate。
• “我已经有内容／简介——围绕它来设计” → 将简介写入文件 → site-create --brief brief.md "<summary>"（如果用户提供了徽标／图像，添加 --attach logo.svg，并说明每个文件的内容）→ 不进行需求探索 → design-directions → 展示设计方向 → build-site。
• “给我一些这个项目的设计方案” → site-create --brief ... → design-directions --json → 对每个预览运行 screenshot → 在你自己的界面中展示。用户选定方案前，绝不开始构建。
• “编辑我的 Miles 网站”／“从上次停下的地方继续” → 对于云端连接，使用 site-attach <siteId>（跨设备）或 use <siteId>（已在本地凭据中）→ site-state --json → 按照其中的 next[] 提示操作。对于已配对的本地 WordPress 连接，留在那个确切的网站上并运行 site-state --json；云端附加和切换有意设为不可用。需要完整信息（简介文本、讨论内容）时，添加 site-state --full --json 和 history。
• “接下来我们应该做什么？” → 运行 site-state --json 查看阶段／阻碍事项，然后运行 site-plan --json 获取完整的当前计划 → 展示待处理／失败的事项，让用户选择 → 用 say 告知选定的工作。
• “网站计划有哪些变化？” → site-plan --history --json → 对比去重后的修订版本及其 added／removed／changed 项目集合。
• “把它做成 WordPress 主题” → connect-browser → convert-theme → export --type theme。
• “撤销上次更改” → miles undo 会还原最近一轮操作（网站和聊天一起还原，只支持一级）。要回退得更早，先运行 site-attach <siteId> --duplicate——分支就是副本。
• “让我看看网站现在的样子”（转换之后） → screenshot --live 通过已连接的仪表板截取正在运行的 WordPress 前端；存储的预览截图只显示转换前的 HTML 网站。

无论从哪个入口开始，都应遵循以下判断原则：保护当前网站，避免意图偏移；启动构建前检查 account-status 的可用额度；先提供设计方向再构建（用户通常比起描述偏好，更容易对选项作出反应）；先确定内容再设计布局；向用户展示设计选项，而不是默默替他们做决定，除非用户明确授权你来决定。

将完整工作流串联起来

每个箭头代表一个基本操作；可根据现有进度调整顺序或跳过：

auth → account-status                     # headroom before committing
site-create "<description>"               # --brief skips discovery; --attach
                                          # sends the user's logo/imagery
  loop: say "<user's answer>"             # relay interview; approve brief
connect-browser --open                    # user watching? open the live canvas
design-directions --json → screenshot     # inspect, recommend, let user pick
build-site --design N                     # headless full-site build
say "<edit>" ...                          # iterate on the built site
connect-browser → convert-theme           # the browser fault line
export --type html | --type theme         # deliverables

较长的操作（site-create、say、build-site、convert-theme）默认会流式返回进度并等待完成。添加 --no-wait 可立即获取 JSON 句柄，然后自行调用 wait-job／cancel——适用于主机能轮询但无法流式接收的情况。--no-wait 要求服务端支持 cancel；绝不要启动无法停止的工作。

长时间运行的命令：绝不让用户干等

site-create（带有简述）、通过 say 审批简述、build-site 和 convert-theme 每次运行都需要数分钟。在启动第一个命令之前，必须遵守以下两条规则：

1. 整个过程中，用户都必须看到进度。 许多宿主（包括 Claude Code）会缓冲前台 stdout，导致实时进度流变成数分钟的沉默。在这些宿主上，要么在后台运行命令并监控其输出日志，要么使用 --no-wait 启动，然后循环运行 miles wait-job --timeout 60，将每次轮询的进度转述为简短的 Miles: <action> 里程碑信息。在运行第一个长时间命令之前，请先阅读 full-workflow.md，了解适用于你所用宿主的传输方式——别等用户已经干等半天才看。

请记住：已启动的运行任务驻留在服务端，而不是你的进程中——并且总会自行完成。 一轮对话是有界工作：如果用户在运行过程中打断你，Miles 会完成这一轮然后停止；不会产生失控费用。CLI 会用一个能在进程退出后保留的进行中标记来跟踪任务；下次运行 Miles 命令时，会针对尚未结束的任务显示 [note: ...]（在某些宿主上，钩子会自动注入此信息）。恢复工作是你的责任，不是用户的：悄悄重新接续任务（miles wait-job），然后根据实际情况回复——已完成就呈现结果，仍在运行就如实说明并继续监控。只有当用户的消息表明他们不再需要这项工作时，才提及 miles cancel；不要就此追问用户，也绝不能在尚未结束的任务上默默启动新的 Miles 工作。详情和各宿主的钩子设置： interrupts.md。

2. 用户在场时，应让他们看到设计过程。 这适用于每一次长时间运行，无论任务如何启动——site-create --brief（会立即开始生成）、简述审批、build-site、convert-theme。只要用户在场且此类任务正在运行，就应打开仪表板：运行 connect-browser --json，并在你能控制的浏览器界面中打开已认证的 url——可以是内部／应用内浏览器、预览窗口、WebView 或浏览器 MCP 工具。使用 --no-wait 时，要在句柄返回后立即执行此操作，并在第一次 wait-job 轮询之前完成。强烈建议使用内部浏览器，而非启动操作系统浏览器：这样你也能看到画布（自行检查设计、观察 connected 是否变为 true），用户也能在当前上下文中查看，而不是看到一个突然弹出的标签页。宿主通常会把这些工具放在不明显的位置——在断定自己没有内部浏览器之前，请检查完整工具列表（包括延迟加载／可搜索工具）以及 browser.md 中适用于你所用宿主的配置。实在不行，也要使用 connect-browser --open 打开用户的操作系统浏览器，而不是让用户什么都看不到。仪表板就是实时画布——无头模式不需要它，但用户眼看着网站生成时，屏幕上却只有一片空白，这就是产品体验的失败。仅在无人值守／自动化调用时跳过此步骤；无论哪种情况，都要在任务开始前告诉用户这一步大约需要多长时间。

首次运行

在新会话中，先检查技能生命周期，再执行设置，然后进行身份验证：

~/.miles/bin/miles-skill check-update --json   # 24h-gated; prompt user only when shouldPrompt is true
"$MILES_CLI" doctor --json
"$MILES_CLI" auth status

如果尚未通过身份验证，请启动非阻塞式设备登录。auth login 必须请求验证码并退出；它不会等待。

"$MILES_CLI" auth login --json

解析 userCode、verificationUrl 和 pendingState。向用户显示这条消息，然后立即启动监听器——不要等用户说“完成”：

Code: <userCode>
Open: <verificationUrl>

Open the URL. The page should show this same code; if it matches, click Authorize. I will keep listening for authorization.

"$MILES_CLI" auth poll --json    # 10-minute timeout; polls until authorized

验证码匹配检查是安全要求：切勿让用户授权一个并非刚刚生成的验证码。遇到 expired/timeout 时生成新验证码；遇到 rate_limited 时等待并重新轮询同一个验证码。所有轮询状态和边缘情况见：auth.md。如果任何命令报告 SANDBOX_NETWORK_BLOCKED，请停止重试并遵循 sandbox.md——必须在最终回复中说明补救措施。

不要假设 frontmatter 钩子已运行：非 Claude 主机可能会忽略它们，因此状态不明确时，请明确检查 doctor/auth status 并执行登录。

处理结果

• site-create、say、build-site、wait 和 convert-theme 会将 Miles 已完成的响应输出到 stdout（也会输出到钩子中继文件，某些主机会将其作为额外上下文传递）。直接执行下一步；不要重新运行 messages 或 status 来重读已有内容。
• 当 Miles 提出问题（[question: ...]）时，如果有原生问题 UI，请通过该 UI 转达给用户；否则使用简洁的 Markdown 卡片。该问题必须在本轮最终回复中显示。用户回答后，将其原样通过 say 传递。中继机制和模板见：full-workflow.md。
• 当 Miles 返回 [approval_required] 或 approvalRequired 时，转达受保护变更摘要，并询问用户是批准还是拒绝。这不是普通的聊天问题：不要使用 say；请使用 live-protection.md。
• 当简报到达（phase: brief_review）时，在最终回复中向用户展示完整简报，并提供批准/请求修改的选项。绝不要将其概述掉——它是整个网站的蓝图。
• 方向方案准备就绪后，请检查它们（如果仪表板已打开，则在已连接的仪表板中检查；否则逐个对每个预览运行 screenshot），结合简报给出推荐，并为每个方向附上简短说明，然后让用户选择。只有在内容确实加载后，才能声称自己已进行视觉检查。
• 当 Miles 返回有关同意、条款、风险、备份或破坏性操作确认的阻止项时，请向用户展示实际面向用户的风险/确认文本，询问其明确决定，并将“否”视为最终决定。不要代替用户批准，不要将法律/安全措辞简化成含糊摘要，也不要通过改换措辞重试来绕过阻止项。
• 进度：转达简短的 Miles: <action> 里程碑行，不要转达原始日志或段落——有关如何在主机上保持这些内容可见，请参阅上文“长时间运行的命令”。
• 积分：立即显示 [warning: ...]；遇到与积分有关的 [error: ...] 时，停止并告知用户充值。可随时通过 account-status --json 查看余额。

更新或卸载 Miles

将“更新 Miles”/“卸载 Miles”视为生命周期请求：

~/.miles/bin/miles-skill check-update --json --force   # summarize, ask approval
~/.miles/bin/miles-skill update
~/.miles/bin/miles-skill uninstall --dry-run --json    # summarize, ask approval
~/.miles/bin/miles-skill uninstall

除非用户明确要求清除所有本地数据（uninstall --purge），否则绝不要删除 ~/.miles/credentials.json。如果 Miles 是通过原生 Agent UI 安装的，请优先使用该主机的更新/卸载机制。