edgeone-makers-env-adaption

运行环境适配指南

本文介绍 EdgeOne Makers Skills 在不同 AI 编码环境中的特殊限制和适配规则。 当前涵盖：WorkBuddy（腾讯沙盒 IDE）

---

🚦 快速参考：预览决策树

到达“显示 / 预览”步骤时，请先阅读此处，再决定如何调用 present_files：

            ┌─ Delivering finished work? ── Yes ──→ present_files(deployed EdgeOne URL) ✅
            │
Enter       ┤
preview     │                      ┌─ dev server running? ─ Yes ──→ present_files(http://127.0.0.1:8088/) ✅
            └─ Still iterating? ───┤
                                    └─ No ──→ start edgeone makers dev → present_files(...)

想要执行的操作	正确做法	错误做法（会导致故障）
预览本地开发服务器	present_files("http://127.0.0.1:8088/")	❌ 传入 /path/to/index.html（IDE 会通过 file:// 打开）
预览已部署的项目	使用带有 ?eo_token=... 的 present_files(deploy_url)	❌ 传入本地 dist/index.html 路径
启动开发服务器	edgeone makers dev --name <p> --skip-env-sync	❌ python -m http.server / npx serve
验证开发服务器已启动（Agent 端 API 检查）	curl --noproxy '*' http://127.0.0.1:8088/api/... ✅ 可用（同一沙盒）	❌ curl localhost:8088 / 普通 curl（代理 + IPv6 → 404/000）
验证开发服务器已启动（面向用户）	present_files(http://127.0.0.1:8088/)（平台隧道）	❌ 告诉用户打开 127.0.0.1:8088——其浏览器无法访问沙盒

核心铁律：在 Makers 项目中，所有 HTML / URL 预览都必须通过 HTTP 协议进行。file:// 看似方便，但在这种方式下，fetch / SSE / Blob / KV 都会出问题。

违规症状自查（如果看到以下情况，请立即返回上方检查）

• 浏览器控制台：出现 TypeError: Failed to fetch / CORS policy 错误
• 页面 HTML 加载正常，但所有 JS 请求均返回 404
• SSE / EventSource 连接后立即断开
• 本地运行正常，但部署后出问题（或反之）

---

WorkBuddy 沙盒环境

WorkBuddy 是一个沙盒化的远程 IDE 环境。运行 AI 编码任务时，它具有以下不同于本地开发的限制。

⚠️ 常见误解：WorkBuddy 是一个桌面 IDE 沙盒，不是无头环境。

• CLI 交互式提示（站点选择器、确认提示）会在沙盒中卡住 → 请使用本节中的非交互式标志。
• 但是，浏览器登录（edgeone login --site <x>）完全可用——WorkBuddy 会启动宿主操作系统的浏览器，并将 OAuth 回调路由回沙盒。

部署 / 链接登录应默认使用浏览器登录，仅在确认浏览器登录失败后才回退到 -t <token>。不要仅仅因为调用方是“Agent”就直接改用令牌登录。

---

1. 非交互模式（所有 CLI 命令都必须避免交互式提示）

在 WorkBuddy 沙盒中，CLI 交互式提示会导致进程永久卡住。所有 edgeone CLI 命令都必须带上非交互式标志：

场景	必需标志	原因
本地开发	--skip-env-sync	跳过“是否同步环境变量？”确认提示
关联项目	--name <project>	跳过交互式项目选择器
未登录时进行身份验证	-t <token>	直接传递令牌，不显示登录弹窗
部署输出	--json	输出机器可读的 JSON，避免解析 ANSI

# Correct: local development
edgeone makers dev --name my-project --skip-env-sync

# Correct: deploy
edgeone makers deploy -n my-project --json

# Wrong: will hang
edgeone makers dev

2. 登录认证

令牌解析优先级（CLI 会自动按以下顺序检查）：

1. -t <token> 命令行参数
2. EDGEONE_PAGES_API_TOKEN 环境变量
3. <cwd>/.edgeone/auth.json（由 edgeone login --local 写入）
4. ~/.edgeone/ 全局凭据

推荐方式：浏览器登录 + --local 标志：

edgeone login --site china --local

--local 会将凭据写入项目目录 <cwd>/.edgeone/auth.json，绕过主目录写入限制。

登录状态检测：

edgeone whoami  # exit 0 = logged in, exit 1 = not logged in (does not hang)

什么时候才需要登录？ 只有项目使用 Blob 或其他需要凭据的后端时才需要登录——而且这完全是由依赖链决定的：Blob 要求项目已关联，而关联要求先登录账户。 因此，纯静态网站运行 edgeone makers dev 无需登录——纯静态预览时请勿强制提示登录。当开发或部署必须访问 Blob 存储时，登录（或 -t <token>）就成为必需条件。（触发条件和关联链路位于 makers-storage 中。）

CLI 版本要求：>= 1.6.7（较旧版本缺少非交互式修复；whoami 会一直挂起）

---

3. 网络隔离（Bash 对开发服务器的访问）

Bash 工具和 edgeone makers dev 在同一沙箱（同一台机器）中运行，因此 Bash 可以访问环回开发服务器。之前声称“Bash curl 被隔离，会返回 404”是错误的——失败是由代理（§5）和 IPv6 localhost（§4）导致的，而不是网络隔离。

验证方式	是否可用	说明
内置浏览器预览（present_files）	✅ 可用	使用平台隧道；这是用户的浏览器访问沙箱开发服务器的唯一方式
用户的系统终端	✅ 可用	curl http://127.0.0.1:8088/
Bash 工具 curl（Agent 端 API 检查）	✅ 仅在使用 --noproxy '*' + 127.0.0.1 时可用	直接运行 curl localhost:8088 会失败：(a) localhost→::1（§4）；(b) 代理劫持请求（§5）

实用规则：

• 在 Bash 中使用 curl --noproxy '*' http://127.0.0.1:8088/...，在测试期间从 Agent 端验证 API 端点——此方法有效（曾用于验证完整的创建→上传→点赞流程）。
• 请勿依赖 Bash curl 向用户展示页面。用户的浏览器无法访问沙箱内的 127.0.0.1:8088；如需面向用户的预览，请将开发 URL 传给 present_files（平台隧道），或部署并分享线上 URL。

---

4. 强制使用 IPv4（127.0.0.1，而非 localhost）

开发服务器监听 IPv6 双栈（::），但在沙箱中 localhost 会解析为 ::1，导致误报 404。

# Correct
curl http://127.0.0.1:8088/

# Wrong (404 in the sandbox)
curl http://localhost:8088/

预览 URL 也必须使用 127.0.0.1：

present_files: http://127.0.0.1:8088/

---

5. 代理劫持（curl 需要 --noproxy）

沙箱会注入 http_proxy 环境变量；curl 默认会通过代理发送请求，而代理会吞掉 SSE 流式响应。

# Correct
curl --noproxy '*' http://127.0.0.1:8088/api/chat

# Wrong (returns "Empty reply" / status 000)
curl http://127.0.0.1:8088/api/chat

内置浏览器预览不受代理影响。

---

6. 主目录写入限制

沙箱会阻止写入 ~/.edgeone/，但允许写入项目目录。

路径	可写入	说明
<cwd>/.edgeone/	✅	--local 写入的位置
~/.edgeone/	❌	EPERM 错误

setLocalData EPERM 不会影响正在运行的服务；它只会影响 CLI 本地状态的持久化。

---

7. 命令执行模式（同步与异步）

命令	执行模式	原因
npm install	前台同步	通常需要 10-30 秒；若在后台运行，后续命令会因缺少依赖而无法执行
edgeone makers dev	后台异步（run_in_background）	长时间运行的进程，不得阻塞对话
edgeone makers deploy	后台异步（run_in_background）	冷启动部署（build → upload → Process → live）通常需要 2–10+ 分钟。前台墙钟时间预算（约 100 秒）会在部署中途对 CLI 发送 SIGKILL（退出码 137），即使它还在持续输出进度也一样——你会丢失最终的 URL 行。请在后台运行，并等待完成通知。

7.2 在后台部署——原因及进程被终止的真正含义

• 前台进程被终止 = 墙钟时间预算耗尽，而不是卡住。 在此沙盒中，前台 Bash 命令的墙钟时间预算固定为约 100 秒；达到上限时，整个进程树都会收到 SIGKILL（exit 137 = 128 + 9），无论它是否还在持续输出。部署期间，CLI 每隔约 10 秒会输出一次 Deployment in progress... elapsed: ~XXs——这些心跳行不会重置或延长预算。因此，“仍在输出 → 在约 100 秒时被终止”是预期行为，并非停滞。
• 终止 CLI 通常不会导致部署失败。 部署本身在服务端运行。CLI 若在前台运行时于 Created deployment / Process 阶段被终止，部署很可能仍在服务端继续并成功上线（实际已确认：一次在约 100 秒时被终止的部署后来被验证已上线，端到端耗时约 674 秒）。重新运行 deploy（使用相同的 -n <project>）会复用该项目并返回 URL。
• 部署时始终使用 run_in_background: true，这样 CLI 才能在前台预算耗尽后继续运行，并输出包含线上 URL 的最终 --json 行。不要在后续轮次中轮询任务——请依赖 <task-notification> 完成事件。（跨轮次的 TaskOutput 可能会报告句柄“未找到”；但进程仍已完成。）
• --json 仍会向 stdout/stderr 输出进度心跳，而非单独输出一行干净的 JSON。 解析最后一行以获取结果对象；将进度行视为无关内容。（这是 CLI 输出整洁度问题，与进程被终止无关——不要认为“没有输出 = 进程已结束”；沙盒根据 OS 进程状态而非 stdout 字节判断进程是否仍在运行。）
• 使用后清理后台进程：未停止的 edgeone makers dev 会持续占用端口 8088，可能与下一个 dev/deploy 冲突。会话继续后，请使用 TaskStop 停止它，或将其终止。

7.1 预览与开发服务器完整流程（必须使用 HTTP，禁止使用 file://）

开发完成后，启动开发服务器并直接预览——不要询问“是否要预览？”

⚠️ WorkBuddy 默认行为：创建 HTML 文件时，平台可能会通过 file:// 自动打开预览——忽略它，那不是有效预览。必须等到 edgeone makers dev 启动后，再通过 HTTP URL 重新打开以覆盖它。

1. 启动 edgeone makers dev --name <project> --skip-env-sync（后台异步，见 §7）
2. 等待 2-3 秒，让开发服务器准备就绪
3. 将 http://127.0.0.1:8088/ 传给 present_files（注意是 127.0.0.1，不是 localhost——见 §4）
4. 告知用户：“项目的本地预览已运行，请查看。如果一切正常，我可以直接为你部署上线。”

只有在用户确认后，才运行 edgeone makers deploy -n <project> --json（后台异步，见 §7 和 §7.2——前台墙钟时间预算不足以完成该操作）。

⛔ 严禁使用 file:// 预览

绝不要将本地 HTML 路径传给 present_files——IDE 会通过 file:// 协议打开它，导致 fetch / SSE / Blob / KV 全部无法正常工作。没有例外，也不存在“只是快速看一眼”的情况。

# ✅ Correct
present_files("http://127.0.0.1:8088/")                                       # dev server
present_files("https://my-app-w9t0lxe8.edgeone.cool?eo_token=...")            # after deploy (full URL with query params)

# ❌ Wrong (IDE opens via file://, all APIs fail)
present_files("/Users/foo/dist/index.html")
present_files("./dist/index.html")
present_files("file:///Users/foo/dist/index.html")

# ❌ Wrong (truncated query params — the user gets a 401 when they open it)
present_files("https://my-app-w9t0lxe8.edgeone.cool")                         # missing ?eo_token=...

⚠️ URL 被截断 = 401：部署 URL 中的 ?eo_token=...&eo_time=... 是身份验证参数；如果被截断，用户打开时会收到 401 UNAUTHORIZED。回复中的每个 URL 都必须包含完整的查询字符串，包括表格、列表和脚注中的引用 URL。

违规症状（如果遇到以下情况，请立即重新检查 § 快速参考）：

• 控制台：TypeError: Failed to fetch / Cross-Origin Request Blocked
• 页面 DOM 看起来正常，但所有 fetch / XMLHttpRequest 调用都失败
• SSE / EventSource 连接立即断开
• @edgeone/pages-blob 调用报告 Missing: deployCredential（即使项目已关联，因为在 file:// 下没有 HTTP 上下文）

⛔ 严禁使用自托管 HTTP 服务

edgeone makers dev 绝不能替换为以下任何一种：

• python -m http.server
• npx serve / npx http-server
• 使用 Node.js http.createServer / express 启动的本地服务

原因：edgeone makers dev 会注入 Blob 凭据、模拟 Cloud Functions 路由、处理 Edge Functions，并运行中间件链。自托管服务只能提供静态文件；其行为与生产环境不同，会导致令人费解的“本地能运行，部署后出错”（或反过来）问题。

---

10. Next.js HMR 跨源配置

Next.js 15+ 开发服务器默认只信任 localhost。在沙箱中通过 127.0.0.1 访问会被视为跨源，因此 HMR WebSocket 会被阻止，页面也会变得无响应。

必须在 next.config.js 中添加：

allowedDevOrigins: ["127.0.0.1"]

注意：该值必须是纯主机名，不能带 http:// 前缀，也不能带端口。

---

11. 项目关联（Blob/KV 必需）

使用 Blob Storage 或 KV 的项目必须确保在启动开发服务器前已关联项目（存在 .edgeone/project.json）。未关联时，Blob/KV 调用会报告 Missing: deployCredential。

前置条件——先登录：关联项目（因此也包括使用 Blob/KV）需要登录账户。完整依赖链为 Blob → 必须关联 → 关联需要登录。如果 edgeone whoami 返回退出码 1，请运行 edgeone login（浏览器登录），或在尝试关联之前使用令牌运行 edgeone makers link -t <token>。未通过身份验证时，切勿尝试关联。

检测项目是否已关联：

cat .edgeone/project.json 2>/dev/null && echo "LINKED" || echo "NOT LINKED"

关联方式：

# Explicit link (auto-creates the project if it does not exist)
edgeone makers link --name <project-name> -t <token>

# Or implicitly link via the dev command
edgeone makers dev --name <project-name> --skip-env-sync

如果远程不存在 --name 指定的项目，link 命令会自动创建该项目。

注意：即使是纯静态项目，只要代码导入了 @edgeone/pages-blob，未关联项目就一定会导致错误。

---

12. 框架版本要求

框架/软件包	最低版本	原因
EdgeOne CLI	>= 1.6.7	修复非交互模式问题、whoami 快速失败，并支持 --json
EdgeOne CLI（仅匿名部署 / claim）	>= 1.6.29	低于此版本时不存在 --anonymous 和 claim
Next.js	16.x	框架适配器会跟进新版本
@edgeone/pages-blob	>= 0.0.14	旧版本存在已知问题

请使用 create-next-app@latest，不要手动指定较旧版本。

---

13. 原生浏览器对话框（alert / confirm / prompt）在 WorkBuddy 内置浏览器中不起作用

WorkBuddy 右侧的预览面板不会渲染 window.alert() / window.confirm() / window.prompt()。调用会立即返回，不会等待用户交互，因此任何由 if (confirm("Delete?")) 控制的处理程序都会静默地什么也不做（删除按钮看起来像是毫无反应）。同一页面在用户实际使用的 Chrome / Safari 中运行正常。

规则：页面中的任何确认、提示或通知都必须使用页面内的自定义模态框（通过 JS 为按钮绑定事件的 <div> 覆盖层）。不要依赖浏览器内置的 alert / confirm / prompt——代码审查时看起来没有问题，用户在自己的浏览器中打开已部署的 URL 时也能正常运行，但在开发或验证期间，它们在 WorkBuddy 预览中会静默失效。

14. 绝不要让用户运行命令

用户在 WorkBuddy 沙盒中没有终端。你打印出来作为操作说明的任何命令都只是无用文字——他们无法执行，非技术用户也看不懂。

情况	应该这样做	不要这样做
匿名项目需要认领	在后台运行 edgeone login --claim --local --json，并将其 claimLoginUrl 作为可点击的链接提供；用户完成认领后，监听器会自动关联项目	❌ 打印 edgeone makers claim --sid <token>，或直接提供部署 JSON 中的 claimUrl（CLI 无法获知登录状态）
用户需要登录	先说明情况，然后自行运行 edgeone login --site <china|global> --local	❌“在你的终端中运行 edgeone login”
需要安装某项内容	自己在 Bash 中运行	❌“请运行 npm install -g edgeone”

你可以使用 shell——请自行操作。只有在确实无法自动完成时（例如需要用户在你打开的浏览器窗口中完成登录），才让用户输入内容，并明确说明需要他们做什么。

14.1 绝不要让关键结果被折叠到进程消息中

WorkBuddy 可能会将与正在运行或刚刚完成的 Bash 命令同一消息中输出的内容折叠为可收起的进程条目。用户要求部署时，部署 URL 和认领链接绝不能出现在那里——否则用户什么也看不到。

情况	应该这样做	不要这样做
部署刚刚完成	等待 Bash 调用完全返回，然后单独发送一条消息提供结果（URL + 认领链接）	❌ 在运行部署的同一条消息中输出结果，或将结果附加到命令的标准输出中
正在运行长时间命令	等待工具调用返回后，再通过后续消息报告进度	❌ 在与命令输出相同的轮次中写“这是你的 URL”