/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 or a sandboxed IDE where CLI prompts hang and network is proxy-isolated (but browser login still works).
  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.
pathPatterns:
  - "*.sh"
  - package.json
validate:
  - pattern: "python\\s+-m\\s+http\\.server|npx\\s+(serve|http-server)"
    message: "Use `edgeone makers dev` — self-hosted static servers skip Blob credentials, Cloud Functions routing, Edge Functions and middleware."
  - pattern: "localhost:80(88|89)"
    message: "Use 127.0.0.1, not localhost — in the sandbox localhost resolves to ::1 and yields false 404s."
metadata:
  author: edgeone
  version: "1.4.2"

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 (agent-side API check) | `curl --noproxy '*' http://127.0.0.1:8088/api/...` ✅ works (same sandbox) | ❌ `curl localhost:8088` / plain `curl` (proxy + IPv6 → 404/000) | | Verify dev server is up (user-facing) | `present_files(http://127.0.0.1:8088/)` (platform tunnel) | ❌ Telling user to open `127.0.0.1:8088` — their browser can't reach the sandbox |

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

> **⚠️ Common misread: WorkBuddy is a *desktop IDE sandbox*, NOT a headless environment.** > - CLI **interactive prompts** (site picker, confirmations) hang inside the sandbox → use the non-interactive flags in this section. > - Desktop hosts can open the browser and route its callback; whether CLI or host owns that step depends on the actual configuration. > > Follow the shared makers-cli flow. Do not jump to token login just because the caller is an Agent, or retry browser authentication when the command only returned workspace choices.

---

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>` + explicit link mode when supported | Confirm name/workspace and creation policy before changing association | | Auth when not logged in | `--interaction agent` | Browser authentication with conversation workspace selection; use secure environment credentials for browserless CI | | 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

Follow the shared [login, switching and target flow](../makers-cli/SKILL.md). It supports standalone Skill execution via native CLI; MCP is optional, and no expert team is needed. Do not keep a separate login procedure in this environment guide.

• Desktop callers use agent interaction; the login listener remains alive until its final result. A pending workspace selection is not login completion. For an already authenticated account use `workspace use` to change workspace, not another login or account switch.
• Effective credentials may come from an explicit argument, environment, project local auth or global CLI state. Global switching does not overwrite a project-local credential; verify identity in the original project directory and obtain consent to correct the source without printing or deleting its contents.
• `--local` is opt-in additional credential persistence and may write global state too. It does not guarantee bypassing home write restrictions, and must not be the default response to sandbox errors.
• Use `whoami --json` after checking CLI `>= 1.7.0` and its