/makers-env-adaption

name: edgeone-makers-env-adaption
description: >-
  Environment-specific adaptation rules for EdgeOne Makers Skills running in
  sandboxed or restricted AI coding environments (e.g. WorkBuddy).
  Trigger when: the user is working in WorkBuddy, a sandboxed IDE, or any
  non-interactive/CI environment where CLI commands may hang or network is isolated.
  Covers: non-interactive CLI flags, network isolation workarounds, login in sandbox,
  proxy bypass, file preview constraints (MUST use http:// via dev server, NEVER file://,
  NEVER python -m http.server / npx serve), dev server requirements.
metadata:
  author: edgeone
  version: "1.1.0"

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(...)

| What you want to do | Correct approach | Wrong approach (breaks) | |---|---|---| | Preview local dev server | `present_files("http://127.0.0.1:8088/")` | ❌ Passing `/path/to/index.html` (IDE opens it via file://) | | Preview a deployed project | `present_files(deploy_url)` with `?eo_token=...` | ❌ Passing a local `dist/index.html` path | | Start dev server | `edgeone makers dev --name <p> --skip-env-sync` | ❌ `python -m http.server` / `npx serve` | | Verify dev server is up | `present_files(http://...)` or the user's system terminal | ❌ Bash `curl localhost` (sandbox network isolation) |

**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:

| Scenario | Required flag | Reason | |------|---------|------| | Local development | `--skip-env-sync` | Skips the "sync environment variables?" confirmation | | Linking a project | `--name <project>` | Skips the interactive project picker | | Auth when not logged in | `-t <token>` | Passes the token directly, no login popup | | Deploy output | `--json` | Machine-readable JSON, avoids ANSI parsing |

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

| Verification method | Availability | Notes | |---------|--------|------| | Built-in browser preview (`present_files`) | ✅ Available | Uses the host network, reliable | | User's system terminal | ✅ Available | `curl http://127.0.0.1:8088/` | | Bash tool curl | ❌ Unavailable | Routed inside the sandbox, returns 404 |

**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.

| Path | Writable | Notes | |------|------|------| | `<cwd>/.edgeone/` | ✅ | Where `--local` writes | | `~/.edgeone/` | ❌ | EPERM error |

A `setLocalData EPERM` does