Runtime Environment Adaptation Guide

This document describes the special constraints and adaptation rules for EdgeOne Makers Skills across different AI coding environments. Currently covered: WorkBuddy (Tencent sandboxed IDE)

🚦 Quick Reference: Preview Decision Tree

When you reach the "display / preview" step, read this first before deciding how to call 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(...)

Core iron rule: inside a Makers project, any HTML / URL preview MUST go through the HTTP protocol. file:// looks convenient, but fetch / SSE / Blob / KV all break under it.

Violation symptoms self-check (if you see these, go back up immediately)

• Browser Console: TypeError: Failed to fetch / CORS policy errors
• Page HTML loads fine but all JS requests 404
• SSE / EventSource disconnects immediately on connect
• Works locally but breaks once deployed (or vice versa)

WorkBuddy Sandbox Environment

WorkBuddy is a sandboxed remote IDE environment. When running AI coding tasks, it has the following constraints that differ from local development.

1. Non-interactive mode (all CLI commands must avoid interactive prompts)

Inside the WorkBuddy sandbox, CLI interactive prompts cause the process to hang forever. All edgeone CLI commands must carry non-interactive flags:

# 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. Login authentication

Token resolution priority (the CLI checks in this order automatically):

1. -t <token> command-line argument
2. EDGEONE_PAGES_API_TOKEN environment variable
3. <cwd>/.edgeone/auth.json (written by edgeone login --local)
4. ~/.edgeone/ global credentials

Recommended approach: browser login + the --local flag:

edgeone login --site china --local

--local writes credentials to the project directory at <cwd>/.edgeone/auth.json, bypassing home-directory write restrictions.

Login status detection:

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

CLI version requirement: >= 1.6.7 (older versions lack the non-interactive fixes; whoami will hang)

3. Network isolation

The Bash tool's network is isolated from the host — inside WorkBuddy's Bash, curl localhost:<port> cannot reach the host's dev server.

Do NOT use Bash curl to judge whether the dev server started successfully. Use present_files or verify by deploying.

4. Force IPv4 (127.0.0.1, not localhost)

The dev server listens on the IPv6 dual stack (::), but in the sandbox localhost resolves to ::1, causing false 404s.

# Correct
curl http://127.0.0.1:8088/

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

The preview URL must also use 127.0.0.1:

present_files: http://127.0.0.1:8088/

5. Proxy hijacking (curl needs --noproxy)

The sandbox injects an http_proxy environment variable; curl goes through the proxy by default, which swallows the SSE streaming response.

# 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

The built-in browser preview is not affected by the proxy.

6. Home directory write restriction

The sandbox blocks writes to ~/.edgeone/, but allows writes to the project directory.

A setLocalData EPERM does not affect the running service; it only affects the CLI's local state persistence.

7. Command execution mode (sync vs async)

7.1 Preview & Dev Server full flow (MUST use HTTP, file:// forbidden)

After finishing development, start the dev server and preview directly — do not ask "do you want to preview?". Full flow:

⚠️ WorkBuddy default behavior: when you create an HTML file the platform may auto-open a preview via file:// — ignore it, that is not a valid preview. You must wait until edgeone makers dev is up, then re-open via the HTTP URL to override it.

1. Start edgeone makers dev --name <project> --skip-env-sync (background async, see §7)
2. Wait 2-3 seconds for the dev server to be ready
3. Pass http://127.0.0.1:8088/ to present_files (note it is 127.0.0.1, not localhost — see §4)
4. Tell the user: "The project's local preview is running, please check it out. If everything looks good, I can deploy it live for you directly."

Only after the user confirms, run edgeone makers deploy -n <project> --json (foreground sync, see §7).

⛔ file:// preview is strictly forbidden

Never pass a local HTML path to present_files — the IDE opens it via the file:// protocol, which breaks fetch / SSE / Blob / KV entirely. No exceptions, no "just a quick look" scenario.

# ✅ 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 truncation = 401: the deploy URL's ?eo_token=...&eo_time=... are auth parameters; if truncated, the user gets a 401 UNAUTHORIZED when they open it. Every URL in your reply must include the full query string, including secondary references in tables, lists, and footnotes.

Violation symptoms (if you see these, immediately re-check § Quick Reference):

• Console: TypeError: Failed to fetch / Cross-Origin Request Blocked
• Page DOM looks normal but all fetch / XMLHttpRequest calls fail
• SSE / EventSource connection drops immediately
• @edgeone/pages-blob calls report Missing: deployCredential (even when the project is linked, because there is no HTTP context under file://)

⛔ Self-hosted HTTP servers are strictly forbidden

edgeone makers dev must NOT be replaced by any of the following:

• python -m http.server
• npx serve / npx http-server
• A local service started with Node.js http.createServer / express

Reason: edgeone makers dev injects Blob credentials, emulates Cloud Functions routing, handles Edge Functions, and runs the middleware chain. A self-hosted server can only serve static files; its behavior diverges from production and produces mysterious "works locally, breaks on deploy" (or the reverse) issues.

10. Next.js HMR cross-origin configuration

The Next.js 15+ dev server trusts only localhost by default. Accessing it via 127.0.0.1 in the sandbox is treated as cross-origin, so the HMR WebSocket is blocked and the page becomes unresponsive.

You MUST add to next.config.js:

allowedDevOrigins: ["127.0.0.1"]

Note: the value is a bare host, without an http:// prefix and without a port.

11. Project linking (required for Blob/KV)

Projects that use Blob Storage or KV must ensure the project is linked (a .edgeone/project.json exists) before starting dev. When not linked, Blob/KV calls report Missing: deployCredential.

Detect whether it is linked:

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

How to link:

# 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

If the project named by --name does not exist remotely, the link command creates it automatically.

Note: even for a pure static project, if the code imports @edgeone/pages-blob, not linking will always cause an error.

12. Framework version requirements

Use create-next-app@latest rather than manually pinning an older version.