edgeone-makers-deploy

EdgeOne Makers 部署技能

将任何项目部署到 EdgeOne Makers。

⛔ 关键规则（绝不可跳过）

1. CLI 版本必须 ≥ 1.6.0 — 如果版本较低，请重新安装。低于 1.6.0 的版本缺少非交互式修复（whoami 快速失败、--json 输出），并且会在 Agent/CI 环境中卡住。绝不可使用过时版本继续操作。匿名部署和 claim 还要求版本为 1.6.29 — 这是更高的特定功能最低版本要求；请参阅 匿名部署。不要因为 CLI 低于 1.6.29 而阻止正常的已认证部署。

2. 绝不可截断部署 URL — 此规则适用于每一次提及 — EDGEONE_DEPLOY_URL 包含访问所需的查询参数（?eo_token=...&eo_time=...）。如果缺少这些参数，页面会返回 401。始终输出包含完整查询字符串的完整 URL。此规则适用于：主要展示内容、摘要表格、脚注、比较内容、代码块、present_files 调用 — 以及回复中 URL 出现的每一次情况。截断是指删除 ? 及其后的所有内容。

   ❌ 错误（已截断 — 会返回 401）：

   https://my-app-w9t0lxe8.edgeone.cool
   

   ✅ 正确（完整 URL）：

   https://my-app-w9t0lxe8.edgeone.cool?eo_token=abc123&eo_time=1234567890
   

   回复完成后自检：检查每一个 .edgeone.cool 域名实例。它们是否都包含 ?eo_token=？如果有任何一个不包含，请立即修正 — 否则用户会收到 401。 3a. 非交互式运行时优先使用 --json — 在 Agent/CI/无头环境中，运行 deploy 时始终传入 --json，这样结果会以单行机器可读格式输出；无需从带颜色或带 \r 动画的标准输出中提取内容。请参阅解析部署输出。 3b. 使用 edgeone whoami 检查登录状态 — 在 CLI ≥ 1.6.0 中，未登录时 whoami 会快速失败（退出码为 1），而不会卡住。如果退出码为 0，说明用户已登录，无需使用 -t。不要检查 cat .edgeone/.token — CLI 将凭据存储在 ~/.edgeone/<hash> 文件中，而不是固定的 .token 路径。

3. **部署 URL 必须放在可见回复正文的最顶部（单独一行、代码块或标题 — 不得放在行内或回复中段），并且还必须通过 present_files（或 IDE 的预览工具）固定到侧边栏。**要应对两种界面故障：思考 / 推理 /“深度思考”区块默认会隐藏内容；长回复会被 IDE 聊天卡片自动折叠，导致放在中段的内容被埋没。present_files 不受聊天折叠影响 — 这是第二个始终可见的渠道。URL 必须完整，不得截断（规则 2）。格式示例：

   🌐 Live URL: https://my-project-abc123.edgeone.cool?<auth_query_params>
   

   然后再补充其他说明（控制台 URL、注意事项等）。 结束本轮前自检（强制） — 回读用户实际会看到的内容（不是你的思考／推理内容）。检查两个问题：（a）可见回复顶部是否有完整的 .edgeone.cool URL，且位于代码块或标题中？（b）是否已使用该 URL 调用 present_files？如果任一答案是否定的，请发送一条额外的简短消息，其中仅包含 🌐 Live URL: <full URL> 块，并调用 present_files。只有在两个渠道都包含该 URL 后才能结束本轮。“我已经在推理中提到过”不能替代在可见正文中展示该 URL。

4. **在浏览器登录前，询问用户选择中国站点还是全球站点。**切勿自行假设。（通过 edgeone login --token 进行令牌登录时会自动检测站点，无需询问。）

5. 优先使用浏览器登录；只有在确认浏览器登录失败后才回退到令牌登录（参见登录部分关于约 60 秒回退阈值和 IDE 中的 Agent 说明——WorkBuddy 并非无头模式）。仅当用户明确要求时才优先使用令牌登录。

6. 令牌登录后，询问用户是否希望在本地保存令牌以供以后使用。

7. 触发任何浏览器弹窗（登录／注册）之前，先向用户说明原因和好处——切勿悄无声息地打开浏览器窗口。

8. **CLI 出现任何失败时，在重试、更换命令或提出变通方案之前，先向用户展示实际错误文本。**不要转述（例如，不要把 Makers project exceeds 40 limit 改写成“可能是名称冲突或权限问题”）。不要悄悄从 makers dev 切换到 makers deploy（或反过来），试图绕过问题——系统性故障（身份验证／配额／权限）会以相同原因影响两者。引用原始错误，指出根本原因，然后提出修复方案或询问用户。

9. 所有面向用户的消息都必须使用用户自己的语言——此技能中的所有说明、引述和提示均以英文书写，只是为了说明含义；不得将其中任何内容直接照搬。用户用中文写给你，就用中文交流——登录说明、站点选择、令牌问题、部署结果，所有内容都要如此。其他语言也一样。在非英语对话中输出此技能里的英文内容属于错误。只有字面 CLI 命令、标志、环境变量名称和 JSON 字段名称保持原样。⚠️ 本技能规定了固定模板（匿名部署步骤 2 和步骤 4），必须翻译，但不得改写或扩展——逐行对应。 规则 11-14 仅适用于匿名部署／认领流程：

10. claim 命令的参数是 --sid，而不是 --token — edgeone makers claim --sid <anonymous-token>。claim 上的 -t / --token 标志用于账号 API 令牌，是完全不同的凭据。将匿名令牌传给 -t 会失败。产品文档中显示的 claim --token <anonymous-token> 是错误的；请遵循此规则。

11. 使用第 4 步中的固定模板展示匿名部署结果 — 这是模板，不是示例：原样复现，只替换 URL 和认领链接。绝不要显示原始的 expiresAt 时间戳，绝不要写成其他时长，也不要添加任何行。60 分钟是产品声明的认领时限，也是保守的指引，因此模板会写明这一点，即使观察到的令牌有效期可能更长。模板表示的是链接会过期，而不是项目会被删除。

12. 展示的认领链接必须来自 edgeone login --claim，绝不能直接使用 claimUrl — 匿名部署后，立即在后台运行 edgeone login --claim --local --json，并将其 claimLoginUrl 填入模板。只有这个链接包含登录 → 认领 → 回调流程，能让 CLI 获取登录状态并自动关联项目；部署输出中的裸 claimUrl 虽然可以认领，但不会通知 CLI，因此用户下次部署时会创建第二个匿名项目。绝不要将 claimCommand、edgeone makers claim --sid ... 或其他命令作为用户认领项目的方式展示——在 WorkBuddy 这类沙盒 IDE 中，用户没有终端，实际上无法运行命令。makers claim 仅作为无头/CI 环境中的备用方案，由你运行，绝不展示给用户。

13. 认领引导语要简短——不要过度承诺，也不要讲解域名 — 只需说明，登录即可保留项目。❌ 绝不要写“永久属于你”“没有时间限制或访问限制”“无限制”，或任何暗示该 URL 此后能永远无条件使用的内容：已认领的项目可能仍需自定义域名，且中国大陆地区的访问可能需要 ICP 备案，因此这些说法并不准确。❌ 用户还在考虑是否认领时，也不要主动提及自定义域名、ICP 备案、DNS 或控制台导航——这会让只想获得可访问 URL 的用户过早面对复杂事项。后续流程由认领页面负责。只有用户询问这些主题时才回答。

---

环境设置

在执行任何 edgeone CLI 命令（安装、登录、部署等）之前，请在当前 shell 会话中设置以下环境变量：

export PAGES_SOURCE=skills

或者在每条命令前内联设置：

PAGES_SOURCE=skills edgeone makers deploy

这会告知平台，此次部署是从 AI 技能上下文触发的。

---

部署流程

先运行这些检查，然后遵循决策表。静默运行这些检查——不要向用户叙述版本、登录状态探测或资格检查结果（例如，绝不要说“CLI 版本 x.x（支持匿名部署）”或“纯静态、无依赖、可直接发布”）。只有检查结果会改变后续操作时才开口（需要升级、需要登录）。

# Check 0: Set environment variable (required before any edgeone command)
export PAGES_SOURCE=skills

# Check 1: CLI installed and correct version? (must be >= 1.6.0; anonymous deploy needs >= 1.6.29)
edgeone -v

# Check 2: Already logged in? (whoami fails fast, won't hang)
edgeone whoami
# If exit 0 → logged in, no -t needed
# If exit 1 → not logged in, need token or browser login

# NOTE: This auth gate is for `deploy` (account-bound upload to your EdgeOne
# account). For `edgeone makers dev` (local preview), login is ONLY required
# when the project uses Blob/credentialed backends — a pure-static dev needs
# no login. When Blob IS used, the chain is: Blob → must be linked → linking
# requires login, so login before linking/starting dev. See makers-storage /
# makers-env-adaption for the dev auth rule and the link chain.

# Check 3: Project already linked?
cat edgeone.json 2>/dev/null

决策表

CLI 版本	登录状态	操作
未安装或 < 1.6.0	—	→ 前往 安装 CLI
≥ 1.6.0 ✓	已登录（或存在令牌）	→ 前往 部署
≥ 1.6.0 ✓	未登录，但有已保存的令牌	→ 前往 使用令牌部署（使用已保存的令牌）
≥ 1.6.29 ✓	未登录，没有已保存的令牌	→ 前往 匿名部署 — 仅当任务原生支持匿名部署（定时／一次性／用户提出要求）时才默认采用匿名部署；否则询问用户选择匿名部署还是登录。如果无法询问，则使用 --anonymous --json 部署，并在结果中提供认领链接和 60 分钟的有效时间窗口（见步骤 2）
1.6.0–1.6.28	未登录，没有已保存的令牌	此版本不支持匿名部署 → 先尝试浏览器登录（见登录部分）。如果浏览器未打开，或约 60 秒内没有任何反应，则改用 令牌登录。不要预先猜测“这看起来像 Agent／CI 环境”并跳过浏览器登录——这种猜测往往是错的；尤其是，WorkBuddy 是桌面 IDE 沙盒，完全支持浏览器登录
≥ 1.6.0 ✓	用户明确提供令牌或要求使用令牌登录	→ 前往 使用令牌部署／令牌登录

---

安装 CLI

npm install -g edgeone@latest

验证：运行 edgeone -v，确认输出为 1.6.0 或更高版本。如果不是，请重新安装。（在非交互环境中，低于 1.6.0 的版本运行 whoami／登录时会卡住，且不支持 --json。）匿名部署和 claim 需要 1.6.29；如果 latest 仍低于此版本，则这两项功能暂不可用——正常的已认证部署不受影响。

---

登录

0. 说明注册／登录步骤

触发任何登录流程之前，都要向用户说明为什么需要这一步，以及接下来会发生什么。不要静默地打开浏览器窗口。

告诉用户：

你需要登录或注册 EdgeOne Makers 账号。接下来会发生这些事：

• 为什么需要登录：部署会将构建产物上传到你的账号，生成唯一的访问 URL 和项目记录。
• 免费权益：EdgeOne Makers 提供免费套餐，包含全球 CDN 加速、自动 HTTPS 和自定义域名绑定——通常足以满足个人项目的需求。
• 接下来会发生什么：我会运行 edgeone login，你的默认浏览器将打开腾讯云登录页面。请完成登录／注册并授权，然后回到这里。
• 如果遇到问题：如果浏览器没有打开，或者登录后 CLI 仍在等待，请告诉我——我会改用令牌登录。

如果用户在约 60 秒内没有回应（没有弹出浏览器或没有报告进展），请主动询问当前情况（浏览器是否打开、是否遇到错误，或是否想改用令牌登录）。不要无限期等待。

1. 请用户选择站点，然后始终传入 --site

运行任何登录命令之前，使用 IDE 的选择控件（ask_followup_question）：

选择你的 EdgeOne Makers 站点：

• 中国 — 面向中国大陆用户（console.cloud.tencent.com）
• 全球 — 面向中国以外的用户（console.intl.cloud.tencent.com）

⚠️ 重要：用户做出选择后，必须在登录命令中明确指定 --site <china|global> 标记（例如 edgeone login --site china）。 由 Agent／技能驱动时，绝不要运行不带 --site 的 edgeone login。 在非交互环境中，不带参数的 login 会立即失败并要求指定 --site（它不会再弹出可能导致卡住的交互式站点选择器）。站点选择应在这里的对话中完成，而不是在 CLI 中。

2. 登录方式参考

有两种登录方式。根据规则 6，始终优先尝试浏览器登录；下表用于说明每种方式适用的情况，并非决策流程——不要用它来猜测环境。

方式	适用情况
浏览器登录	默认方式。适用于所有本地桌面 IDE（VS Code、Cursor、WorkBuddy）——IDE 会将操作系统浏览器和 OAuth 回调接入沙盒。
令牌登录	浏览器登录确认失败后（没有弹出浏览器 / 约 60 秒内没有进展）作为后备方式，或用户明确提供令牌或请求使用令牌登录时使用。也适用于真正分离的环境（仅 SSH、CI 运行器、无浏览器的容器），且是这些环境中的唯一选项。

浏览器登录

# China site
edgeone login --site china

# Global site
edgeone login --site global

等待用户完成浏览器身份验证。完成后，CLI 会输出成功消息。

⚠️ 浏览器会话复用陷阱：如果用户之前登录过其他站点（例如之前登录了国际站，现在尝试中国站，或反过来），浏览器可能会静默复用旧的腾讯云会话。CLI 看起来会登录成功，但实际上绑定的是错误的账号——后续执行 deploy 会因身份验证错误而失败，或 whoami 显示意外的账号。

如果发生这种情况，请指导用户：

1. 在登录页面点击“使用其他账号登录”；或
2. 先从所有腾讯云控制台（console.cloud.tencent.com 和 console.intl.cloud.tencent.com）退出登录，然后重新运行 edgeone login。

令牌登录

有两种方式：

方式 A：edgeone login --token（持久化，推荐）

edgeone login --token <token>

根据令牌自动检测中国站 / 国际站——无需 --site 标志。登录状态会保存，供后续命令使用。

💡 复用之前浏览器登录时生成的令牌——无需前往控制台。 edgeone login --site <x>（浏览器登录）会自动生成 API Token，并将其写入 ~/.edgeone/<hash>（JSON 中包含 value.Token）。在无头环境 / Agent 场景中运行 makers dev/deploy 时，可直接将该 Token 值用作 EDGEONE_PAGES_API_TOKEN="<Token>" 或 -t <Token>，而无需在控制台创建新令牌。

方式 B：在 deploy 中直接传入 -t（单次调用）

令牌仅用于本次部署；不会保存持久化登录状态。

edgeone makers deploy -t <token>

⚠️ 重要：edgeone whoami 不支持 -t 标志。不要尝试使用 whoami -t <token> 验证令牌。用户提供令牌时，请跳过所有登录检查，直接开始部署。

指导用户获取令牌：

1. 前往控制台：
   • 中国站：https://console.cloud.tencent.com/edgeone/pages?tab=settings
   • 国际站：https://console.intl.cloud.tencent.com/edgeone/pages?tab=settings
2. 找到 API Token → 创建令牌 → 复制令牌

⚠️ 提醒用户：令牌具有账号级权限。切勿将其提交到代码仓库。

3. 提议在本地保存令牌

用户提供令牌后，询问：

要在本地保存此令牌，以便日后部署时使用吗？

• 是 — 保存到 .edgeone/.token（下次自动使用）
• 否 — 仅用于本次部署

如果选择是：

mkdir -p .edgeone
echo "<token>" > .edgeone/.token
grep -q '.edgeone/.token' .gitignore 2>/dev/null || echo '.edgeone/.token' >> .gitignore

向用户确认：“✅ 令牌已保存到 .edgeone/.token，并已添加到 .gitignore。”

---

部署

使用浏览器身份验证部署（Makers 项目）

# Project already linked (edgeone.json exists)
edgeone makers deploy

# New project (no edgeone.json)
edgeone makers deploy -n <project-name>

<project-name>：根据项目目录名称自动生成。首次部署会自动创建 edgeone.json。

使用令牌部署（Makers 项目）

先检查是否有已保存的令牌：

cat .edgeone/.token 2>/dev/null

• 找到已保存的令牌 → 使用该令牌，并告知用户：“正在使用保存在 .edgeone/.token 中的令牌”
• 未找到已保存的令牌 → 请用户提供令牌（见上文“令牌登录”）

# Project already linked
edgeone makers deploy -t <token>

# New project
edgeone makers deploy -n <project-name> -t <token>

令牌已包含站点信息——无需 --site 标志。

使用手动输入的令牌成功部署后，询问用户是否要保存该令牌（见上文“提议在本地保存令牌”）。

部署到预览环境

edgeone makers deploy -e preview

非交互式 / Agent / CI 部署（推荐：--json）

在 Agent、CI 或任何非 TTY 环境中运行时，请添加 --json，这样最终结果会以单行机器可读格式输出——无需从带颜色的标准输出中提取信息：

edgeone makers deploy -n <project-name> --json
edgeone makers deploy -n <project-name> -t <token> --json

Makers Agent 项目部署

对于包含 agents/ 目录的项目（AI Agent 项目），请使用 edgeone makers deploy，它会自动运行构建：

edgeone makers deploy -n <name> -t <token> --json
edgeone makers deploy -n <name> -t <token> --json -e preview

注意：edgeone makers deploy 会在部署前自动运行构建——无需单独执行 edgeone makers build。

构建行为

CLI 会自动检测框架、运行构建并上传输出目录。无需手动配置。

---

免登录部署（无需登录）

用户未登录且没有令牌时，可以免登录部署，并在之后认领项目。需要 CLI >= 1.6.29。在 1.6.0–1.6.28 上，此功能不可用——请改用登录或令牌。

第 1 步：排除项检查——请先执行

免登录部署会在空环境中构建：它会跳过远程环境变量拉取和 AI 网关凭据注入，因为这两项都需要身份验证。依赖其中任一项的项目仍可成功部署，但运行时会出错。

# Is this an Agent project?
ls agents/ 2>/dev/null && echo "AGENT_PROJECT"

# Does it use Blob storage? (checks source files and the dependency declaration)
grep -rEl "@edgeone/pages-blob" \
  --include="*.ts" --include="*.js" --include="*.mjs" --include="*.cjs" \
  --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.svelte" \
  . 2>/dev/null | head -1
grep -l '"@edgeone/pages-blob"' package.json 2>/dev/null

任一 grep 命令有非空输出，都表示项目使用了 Blob。

⛔ 此流程中的所有检查都是静默执行的——绝不要向用户说明这些检查。 不要报告类似“CLI 版本 x.x（支持免登录部署）”“页面是纯静态、无 Blob/KV 依赖，可直接发布”或任何其他版本 / 资格检查结果。这些属于内部判断；非技术用户无法据此采取行动，因此绝不应看到这些内容。只有当检查会改变结果时，才告知用户——例如，项目需要登录（见下文），或 CLI 版本过旧，需要升级。检查通过时不要发送任何消息。

无法通过这种方式检测 KV——必须询问用户。 KV 命名空间会在控制台中绑定，并以用户自选名称的全局变量形式提供（例如 my_kv），因此没有可供 grep 搜索的包导入。也没有 @edgeone/pages-kv 包。请直接询问用户：

此项目是否使用 KV 存储？

如果任一项检查发现依赖，或用户表示项目使用 KV，请勿免登录部署。 转到登录，并告诉用户原因（注意面向用户的说法：“免登录”，绝不要说“匿名”）：

此项目需要环境变量 / AI 网关凭据或存储绑定，而免登录部署无法提供这些内容。网站可以加载，但这些功能会无法正常运行。我们来登录吧，这样才能确保项目正常工作。

纯静态网站以及没有此类依赖的前端框架项目可以继续部署。

如果用户知悉这些限制后仍想在不登录的情况下发布，可以继续——但必须在结果中醒目说明：在认领并配置项目之前，AI 和存储功能都无法使用（同样，请使用“免登录”，绝不要说“匿名”）。

第 2 步：决定路径 — 仅当任务适合匿名方式时才默认采用，否则先询问

只有当任务本身天然适合匿名方式时，才直接采用匿名方式，无需询问 — 任务本身是临时性的，或本来就无人值守。明显的信号包括：

• 定时 / 自动化任务 — 例如“每日定时生成一个页面并部署”、cron 流水线，以及任何必须在无人看管的情况下运行的任务
• 一次性临时任务 — 临时预览、快速演示、“先看看效果”，以及用户表明只是临时使用或暂时需要的任何内容
• 明确表达匿名意图 — 用户说“免登录”、“不用登录”、“anonymous”或“don't make me sign up”

在这些情况下，60 分钟过期 + 之后认领的模式正是合适的选择，询问只会徒增阻碍。直接进入第 3 步，并使用第 4 步中的固定模板呈现结果（认领链接 + 60 分钟有效期）——模板已经告诉用户，如果之后改变主意，该如何保留项目。

其他所有情况 — 都要询问。 如果任务显然不是临时性的 — 用户可能想保留、广泛分享或在此基础上继续构建的任何内容 — 就应提供选择。不要试图根据环境判断是否跳过询问：沙盒 / TTY 信号并不可靠，猜错了要么会无谓地打断用户，要么会在用户想保留项目时悄悄部署。

如果环境确实完全无法让你询问（没有 TTY，也没有提问工具），那么询问是不可能的 — 这是客观限制，不是判断选择。使用 --anonymous --json 部署，并在结果中醒目地标出认领链接和 60 分钟有效期。

如何询问（需要询问时）： 使用 IDE 的选项控件（例如 ask_followup_question）提供选择。选项标签刻意避开了“anonymous”一词 — 这是术语，容易让非技术用户困惑。请严格按照用户所用语言提供以下两个选项。不要改写标签，不要在选项本身添加注意事项，也完全不要向用户提及“anonymous” — 必须指代这一概念时，请称为**“免登录部署”**，绝不要称为“匿名部署”。 选项文本必须原样放在 label 中；不得将其拆开放入 description。

英语用户 — 请严格提供以下两个选项：

• 立即发布，之后登录 — 无需登录。立即获取预览链接；准备好后，你可以登录并认领该站点。
• 登录后发布 — 先登录 EdgeOne Makers 账户；该站点将直接保存到你的账户中。

中文用户 — 请严格提供以下两个选项：

• 直接发布，无需登录
• 登录后发布

根据用户的选择进入相应流程：

• 立即发布，之后登录 → 这是匿名部署路径 — 继续执行第 3 步。
• 登录后发布 → 前往登录（浏览器流程），然后继续常规部署。

⛔ 不要过度承诺认领后的权益。 只说项目会保留 / 保存到其账户中，不要说其他内容。具体而言，不要说“没有访问限制”、“永久归你所有”，或任何暗示该 URL 之后无条件保持公开且最终确定的说法 — 已认领的项目仍可能需要自定义域名，并且在中国大陆访问还可能需要 ICP 备案。此时也不要提及自定义域名、ICP 备案或 DNS：用户正在决定是否登录，这些概念只会造成干扰。认领页面会引导用户完成后续步骤。

第 3 步：部署

export PAGES_SOURCE=skills
edgeone makers deploy --anonymous --json

仅当必须固定站点时，才添加 --site china 或 --site global（用户已告知目标站点，或 CI 需要确定性）。否则省略该选项 — CLI 会根据自身的出口 IP 自动检测站点。不要自行探测站点，也不要根据自己的检查结果拼出 --site。

不要传入 -n、-e 或 --area — 在 --anonymous 下这些选项会被忽略。项目名称会自动生成。

第 4 步：启动认领监听器，然后展示结果

将部署标准输出的最后一行解析为 JSON（前面是人类可读的输出）。字段使用驼峰命名法：url、projectId、deploymentId、anonymousToken、claimUrl、claimCommand、expiresAt、site。

立即在后台启动认领监听器——必须在用户点击认领链接前开始监听，否则登录状态无法传递到 CLI，下一次部署会创建第二个匿名项目：

edgeone login --claim --local --json

使用 run_in_background 运行。它会立即打印一行 {"status":"waiting","claimLoginUrl":...} JSON，然后继续监听（最长 60 分钟）。从该行中获取 claimLoginUrl。⛔ 你要向用户展示的认领链接是这个 URL，而不是部署 JSON 中的 claimUrl 字段。 只有这个链接才能串联起登录 → 认领页面 → 回调到 CLI。部署输出中的裸 claimUrl 会在未通知 CLI 的情况下认领项目，导致用户下一次部署转到新的匿名项目，而不是已认领的项目。

⛔ 用户看不到监听器——绝不要提及它。 不要告诉用户监听器正在运行、正在“等待认领回调”，也不要提及任何其他内部机制的状态（状态文件、JSON 解析、端口）。面向用户的内容必须且只能是下方模板。认领流程应表述为“打开链接并登录”，而不是你正在监视的过程。

⛔ 部署命令完全返回后，单独发送模板作为一条消息。 不要在运行部署命令的同一条消息中输出，不要将其附在命令输出中，也不要在命令仍在运行时打印。在 WorkBuddy 中，与正在运行或已完成的命令一同输出的内容可能会折叠到可折叠的进程消息中——如果发生这种情况，用户就看不到 URL 或认领链接。等待 Bash 调用结束，然后在下一条回复中单独发送模板。

⛔ 这是固定模板，不是建议。 必须原样复现：四行内容、顺序、表情符号和分隔符均相同。只替换 <url>（取自部署 JSON）和 <claimLoginUrl>（取自 login --claim 的输出）。不要改写、合并、拆分或调整行的顺序。前后都不要添加任何句子。不要附加项目 ID、部署 ID、控制台 URL、expiresAt、后续步骤或任何形式的说明。

面向英语用户——原样输出以下内容：

🌐 线上 URL：<url>

---

⏳ 此链接将在 60 分钟后失效。

👉 认领此项目 — 请在 60 分钟内完成认领。

面向中文用户——原样输出以下内容：

🎉 部署成功 🌐 访问地址：<url>

---

⏳ 该链接 60 分钟后失效。

👉 认领这个项目 —— 请在 60 分钟内完成认领。

对于其他语言，只翻译此模板，不添加任何其他内容——保留四行、表情符号、分隔符和完全相同的内容。不要自行添加或解释。

之后停止。任何你想在此处补充的内容——认领能解锁什么、自定义域名、ICP备案、DNS、控制台导航、代用户认领的提议——均被关键规则 13 和 14 禁止。只有用户询问时，才回答这些问题。

用户认领后

后台的 login --claim 进程会在控制台传回结果时自行退出。当进程以 {"status":"success",...,"linked":true} 成功退出（退出码为 0）时：

• CLI 已登录（凭据已保存，使用 --local 时还会保存 .edgeone/auth.json），
• 项目已关联（.edgeone/project.json），
• .edgeone/anonymous.json 已移除。

用用户的语言明确告知：该项目现已归属其账户，之后的部署都会更新同一个项目。之后的所有部署都使用常规部署流程（edgeone makers deploy --json）。

如果进程以非零状态退出（用户在 60 分钟内没有完成关联），匿名项目仍未被认领：重新运行 edgeone login --claim --local --json，生成新的链接，并使用相同模板再次提供给用户。

如果用户要求你“帮我认领” / “claim it for me”：在监听进程仍在运行时，再次提供同一个链接；如果进程已经退出，则重新运行命令生成新链接。绝不要打印 CLI 认领命令——edgeone makers claim --sid 仅适用于没有浏览器的无头 / CI 环境（参见关键规则 13）。

完整的 JSON 架构、速率限制、错误代码、状态文件字段和站点解析规则，请参阅 references/anonymous-deploy.md。

---

⚠️ 解析部署输出（重要）

首选：--json

使用 --json 运行部署时，stdout 的最后一行是一个独立的 JSON 对象—— 直接解析即可，无需使用正则表达式 / 清理 ANSI 代码：

{"status":"success","url":"https://my-project-abc123.edgeone.cool?<auth_query_params>","type":"preset","projectId":"makers-xxxxxxxx","deploymentId":"dp-xxxx","consoleUrl":"https://console.cloud.tencent.com/edgeone/pages/project/makers-xxxxxxxx/deployment/xxxxxxx"}

失败时，最后一行是 {"status":"error","error":"<message>"}，且进程以非零状态退出。

直接使用 url（完整 URL，包含查询字符串）、projectId 和 consoleUrl。

回退方式：文本输出（不使用 --json）

edgeone makers deploy 成功后，CLI 会输出：

[cli][✔] Deploy Success
EDGEONE_DEPLOY_URL=https://my-project-abc123.edgeone.cool?<auth_query_params>
EDGEONE_DEPLOY_TYPE=preset
EDGEONE_PROJECT_ID=makers-xxxxxxxx
[cli][✔] You can view your deployment in the EdgeOne Makers Console at:
https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deployment/xxxxxxx

提取规则：

字段	提取方法	⛔ 警告
访问 URL	EDGEONE_DEPLOY_URL= 后的完整值	包含完整查询字符串（? 及其后的所有内容）——缺少这些参数，页面将无法加载
项目 ID	EDGEONE_PROJECT_ID= 后的值	—
控制台 URL	"You can view your deployment..." 后的行	—

向用户展示——部署 URL 必须出现在可见回复的最顶部，并通过 present_files 固定到侧边栏（请参阅规则 4，了解为什么必须通过这两个渠道提供）：

⚠️ URL 完整性规则（撰写回复前请阅读）：

规则	详情
每次提及都必须完整	如果你在表格、列表、脚注、对比内容或任何其他位置写入 URL，都必须包含完整查询字符串。没有例外。
不要为了美观而删减	不要为了让表格更整洁而缩短 URL。被截断的 URL 是损坏的 URL，不是更整洁的 URL。
使用实际值，不要抽象替代	使用部署输出中的实际 URL。面向用户的文本中，不要用 ...、(params omitted) 或任何占位符替代查询参数。
发送前自查	搜索草稿中的 .edgeone.cool——每次出现后面都必须有 ?eo_token=。

🌐 在线 URL：https://my-project-abc123.edgeone.cool?eo_token=abc123&eo_time=1234567890

---

• 控制台 URL：https://console.cloud.tencent.com/edgeone/pages/project/...

ℹ️ 注意：此预览 URL 用于快速验证部署。从中国大陆访问时，由于域名 ICP 备案状态或 CDN 加速策略，链接可能会在一段时间后或被分享时受到限制（例如返回 401）。如需长期稳定地公开访问，请绑定已完成 ICP 备案的自定义域名。

---

错误处理

错误	解决方案
command not found: edgeone	运行 npm install -g edgeone@latest
CLI 版本 < 1.6.0	重新安装：npm install -g edgeone@latest。旧版本在非交互环境中执行 whoami/login 时会卡住
--anonymous / claim 被报告为未知选项	已安装的 CLI 低于 1.6.29。运行 npm install -g edgeone@latest；如果版本仍低于 1.6.29，说明匿名部署尚未发布，请改用登录或令牌
登录时浏览器未打开	切换为令牌登录
whoami 显示“not authenticated”/退出码为 1	未登录时的预期行为——whoami 会快速失败，而不会卡住。提供匿名部署（参见“匿名部署”）、运行 edgeone login 或提供令牌
非交互式部署提示“browser login is unavailable”并以退出码 1 结束	在没有令牌的 Agent/CI/无头环境中，这是预期的快速失败行为。通过 -t <token> 提供令牌，或设置 EDGEONE_PAGES_API_TOKEN
部署似乎卡在 [DeployStatus] Deploying...	非 TTY 环境会输出心跳行；这并非卡住。如果包装程序仍然误判，请使用 --json，或在后台运行并轮询状态。不要终止进程
使用令牌时出现身份验证错误	令牌可能已过期——请在控制台重新生成
登录似乎成功，但 deploy 报告身份验证错误	浏览器复用了来自错误站点的会话，绑定了错误的账户。点击登录页面上的“使用其他账户登录”，或先从所有腾讯云控制台退出登录
edgeone whoami 显示了意外的账户	浏览器会话被复用。点击“使用其他账户登录”，或从所有控制台退出登录后重新登录
Failed to create pages project（dev）/ Makers project exceeds 40 limit（deploy）	账户已达到 40 个项目上限。dev 和 deploy 都会以相同方式失败。只能向用户提供以下两个选项，措辞保持原样——不要给任一选项添加“推荐”标签，也不要提供第三个选项（不要建议使用 CloudStudio 或任何其他平台，也不要编造替代方案）：① 用户在 EdgeOne Makers 控制台删除一个未使用的项目；② 用户通过 -n <existing-project-name> 指定一个已关联的现有项目。Agent 不得自行删除项目（CLI 按设计不提供删除命令——不要通过 HTTP API 或缓存的凭据绕过限制）。
项目名称冲突	使用 -n 指定其他名称
构建失败	检查日志——通常是缺少依赖项或构建脚本有误
whoami 显示“not authenticated”，但刚刚成功运行了 edgeone login	在 Agent/无头环境中，这是预期行为：whoami 和 makers dev/deploy 读取的是 API-Token 身份验证，而不是浏览器会话。将 ~/.edgeone/<hash>（value.Token）中的自动生成令牌复用为 EDGEONE_PAGES_API_TOKEN / -t。参见上方的“令牌登录”说明。
makers dev 卡在交互式“Link existing / Create and link”菜单	启动 dev 时未提供 -n，因此进入了交互式选择器。终止该进程，然后使用 edgeone makers dev -n <project-name> --skip-env-sync 重新启动——如果项目不存在，dev 会自动创建项目并在内部关联。项目使用 Blob/KV 时，启动 dev 务必传入 -n。
对部署 URL 执行 curl 返回 302 → DingTalk SSO 登录	预览网关需要基于浏览器的 eo_token 验证（JS），curl 无法执行。请在真实浏览器中打开完整的 ?eo_token=...&eo_time=... URL——浏览器会验证令牌并绕过 SSO。这不是代码错误。

---

有关 CLI 命令参考、环境变量、本地开发设置和令牌管理的详细信息，请参阅 references/command-reference.md。