From a5b8ef4b4641ffe2f4678cad360670432027b4c9 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:32:55 +0800 Subject: [PATCH 01/34] docs(makers-deploy): add anonymous deploy and claim reference --- .../references/anonymous-deploy.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 skills/makers-deploy/references/anonymous-deploy.md diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md new file mode 100644 index 0000000..1d62e4d --- /dev/null +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -0,0 +1,246 @@ +# Anonymous Deploy & Claim Reference + +Detail reference for login-free deployment. For the decision flow and the commands to run, see [SKILL.md](../SKILL.md) — read that first. + +Requires CLI `>= 1.6.21`. + +--- + +## Commands + +```bash +# Anonymous deploy (only takes effect when NOT logged in) +edgeone makers deploy --anonymous [--site china|global] [--json] + +# Claim an anonymous project into your account (requires login) +edgeone makers claim [--sid ] [-t ] [--json] +``` + +### Deploy parameters + +| Parameter | Type | Notes | +|-----------|------|-------| +| `--anonymous` | boolean | Enables login-free deploy. **Ignored when already logged in** — the CLI prints a notice and runs the normal deploy flow. **No `-a` short option exists** (`-a` is already taken by `--area`). | +| `--site` | `china` \| `global` | Which API site to use. Auto-detected by egress IP when omitted. | +| `--json` | boolean | Emit a machine-readable result line. | + +### Claim parameters + +| Parameter | Type | Notes | +|-----------|------|-------| +| `--sid` | string | The **anonymous identity token** from deploy output. Optional when `.edgeone/anonymous.json` exists in the working directory. | +| `-t` / `--token` | string | The **account API token** for authentication. A completely different thing from `--sid`. | +| `--json` | boolean | Emit a machine-readable result line. | + +⛔ **`--sid` and `-t` are not interchangeable.** `--sid` identifies the anonymous project to claim; `-t` authenticates the account receiving it. Product documentation that says `claim --token ` is wrong. + +### Parameters silently ignored under `--anonymous` + +Do not pass these — they have no effect and will mislead the user: + +| Parameter | Why it is ignored | +|-----------|-------------------| +| `-n` / `--name` | The project name is generated automatically: current directory name (lowercased, non-alphanumerics replaced with `-`) plus an 8-character random suffix. Users cannot choose it. | +| `-e` / `--env` | The anonymous path does not take an environment argument. | +| `--area` | Not forwarded by the anonymous deploy path. | + +--- + +## Parsing `--json` output + +⚠️ Field names are **camelCase**. Product documentation shows snake_case (`site_url`, `project_id`, `claim_url`) — that is incorrect. Use the names below. + +📌 Human-readable output is printed **before** the JSON. Parse the **last line** of stdout, exactly as for a normal deploy. Do not assume all of stdout is JSON. This applies to failures too. + +### Success + +```json +{ + "status": "success", + "url": "https://my-app-a3f8b2c1.edgeone.dev", + "projectId": "makers-ihtxkls1k3jc", + "deploymentId": "dppxfikip2rt", + "anonymousToken": "98a71090aaae2670c6fe0024a250d6f3", + "claimUrl": "https://console.tencentcloud.com/edgeone/pages/claim?token=98a71090aaae2670c6fe0024a250d6f3", + "claimCommand": "edgeone makers claim --sid 98a71090aaae2670c6fe0024a250d6f3", + "expiresAt": "2026-07-28T21:10:48.000Z", + "site": "global" +} +``` + +| Field | Meaning | +|-------|---------| +| `url` | Live access URL. Present it in full, including any query string. | +| `projectId` | Anonymous project ID. | +| `deploymentId` | Deployment ID. | +| `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | +| `claimUrl` | Web claim URL, on the console domain matching `site`. | +| `claimCommand` | Ready-to-run CLI claim command. | +| `expiresAt` | **Actual** claim deadline, ISO 8601. Always show this value; never substitute a hardcoded duration. | +| `site` | `china` or `global` — the API site this project lives on. | + +### Failure + +```json +{"status":"error","errorCode":"RATE_LIMIT_EXCEEDED","message":"...","suggestion":"..."} +``` + +`suggestion` is only present for the rate-limit case. `errorCode` may be absent for generic failures. + +--- + +## Three different expiry windows — do not conflate them + +| Window | Where it comes from | What it governs | +|--------|--------------------|-----------------| +| **Anonymous token validity** | `expiresAt` in `--json` output | The claim deadline. This is the only one users care about. | +| COS credential validity | `cosExpiredTime` / `cosExpiration` in the state file | A single upload operation. Irrelevant once deploy succeeds. | +| Product target spec | TAPD requirement (unclaimed 60 min → 24 h after claim, 3 renewals) | Not implemented in the current backend. Do not quote it to users. | + +⛔ **Never hardcode a duration.** Both the product plan and the CLI implementation doc state "60 minutes", but measured responses contradict this: in the recorded test-environment response the anonymous token lasted ~12 hours and the COS credential 30 minutes. Read `expiresAt` and show that. + +When you have not yet run the deploy (for example while asking the user whether to go anonymous), use wording with no number: "you'll need to log in and claim it before it expires; the exact deadline is shown once the deploy finishes". + +--- + +## Local state file: `.edgeone/anonymous.json` + +Written to `/.edgeone/anonymous.json`. + +| Field | Meaning | +|-------|---------| +| `site` | API site (`china` / `global`). Reused by `claim`. | +| `token` | Anonymous identity token (Sid). | +| `tokenExpired` | Token expiry, Unix seconds. | +| `projectName`, `projectId`, `deploymentId` | Project and deployment identifiers. | +| `targetPath`, `bucket`, `region` | COS upload location. `region` is a COS storage region (e.g. `ap-shanghai`) — **not** the API site. | +| `cosExpiredTime`, `cosExpiration` | COS credential expiry. | +| `siteUrl` | Live URL. | +| `createdAt` | Creation timestamp, ISO 8601. | + +Lifecycle: + +- Written incrementally as the deploy progresses. +- **Deleted on successful claim.** +- **Kept on failure**, so a retry or a later claim can still find the token. +- When present, `claim` needs no `--sid`. + +Treat it as a secret: it contains a single-use credential. It lives under `.edgeone/`, which projects normally already ignore in git — confirm that before committing. + +--- + +## Site resolution (`--site`) + +| Situation | Behaviour | +|-----------|-----------| +| `--site` passed | Used as-is. Prefer this in Agent/CI contexts for determinism. | +| `--site` omitted | Detected via `GET https://api.edgeone.ai/e-func/ip/isCN` (3 s timeout): `isCN: true` → `china`, otherwise `global`. | +| Detection fails | Falls back to `global`. | + +`claim` reads `site` from `.edgeone/anonymous.json` and **does not re-detect by IP** — the token and project are bound to one site, and egress IP can change between commands (VPN, different CI runner). + +China and Global are fully independent environments: tokens and projects do not cross over. If the site is wrong, the claim fails. + +> **China site status:** availability depends on backend anonymous-account configuration being in place for the China site. Confirm before relying on `--site china`. Note also that mainland-China access to preview links may be restricted by local regulations. + +--- + +## Rate limits + +Anonymous deploys are rate-limited on **two dimensions — egress IP and Sid** — resetting daily at 00:00 local time. + +Exact allowances are not documented consistently across sources, so they are deliberately not stated here. Treat the limit as reachable and handle it. + +When exceeded, the CLI reports `LimitExceeded.Upload`, exits non-zero, and with `--json` emits: + +```json +{"status":"error","errorCode":"RATE_LIMIT_EXCEEDED","message":"Daily anonymous deploy limit reached.","suggestion":"Please login (edgeone login) to deploy without limits, or try again tomorrow."} +``` + +Correct response: tell the user the anonymous quota is used up, and offer logging in (no quota) or retrying tomorrow. Do not retry in a loop. + +--- + +## Error reference + +### Deploy + +| Symptom | Cause | Action | +|---------|-------|--------| +| `errorCode: RATE_LIMIT_EXCEEDED` / `LimitExceeded.Upload` | Daily anonymous quota exhausted | Offer login, or retry tomorrow. Do not loop. | +| `errorCode: TOKEN_EXPIRED` / CGI `code: 104` | Anonymous token expired or unknown | Run the anonymous deploy again — it mints a fresh token. | +| `InvalidParameter.Security` | Generated project name collided or was rejected | Retry; a new random suffix is generated each run. | +| `COS upload failed: ...` | Network or credential failure during upload | Retry the deploy. COS credentials are short-lived, so a stale run cannot be resumed. | +| `Deployment polling timed out after 5 minutes` | Build did not reach a terminal state in time | Retry. Polling runs every 3 s for up to 5 minutes. | +| `Deployment failed: ` | Remote build failed | Read the mapped message (e.g. `Build script error`, `Install failed`, `Memory exceed limit`, `Time exceed limit`) and fix the project's build. | +| `Detected logged-in account, --anonymous is ignored` | Credentials were found | Expected. The normal deploy flow runs instead. | + +Deployment status values: `Success` is terminal-success; `Failed`, `Timeout`, `Cancelled` are terminal-failure; anything else keeps polling. + +### Claim + +| Symptom | Cause | Action | +|---------|-------|--------| +| `MISSING_TOKEN` | No `--sid` and no state file | Pass `--sid `, or run from the directory containing `.edgeone/anonymous.json`. | +| `Claim API error (Code 108)` | Not authenticated | Log in, or pass `-t `. | +| `Claim returned no succeeded projects` | Token expired, already claimed, or no deployment in `Success` state | Verify the deploy finished successfully and the token is still valid. | +| Warning about a site mismatch | Credentials belong to a different site than the deploy | Re-run with credentials for the site named in the warning. | +| `ResourceUnavailable` | Account restricted | Surface the message; nothing the CLI can do. | + +The backend claims **asynchronously** and only migrates projects whose deployment reached `Success`. A response is only a real success when its `succeeded` array is non-empty — the CLI already enforces this. Always claim after the deploy has finished, never during. + +--- + +## Claim flow + +1. **Deploy must have succeeded.** Only `Success` deployments are migrated. +2. **Log in.** In an interactive environment the CLI opens a browser when needed; in CI, pass `-t `. +3. **Match the site.** Run from the directory holding `.edgeone/anonymous.json` so the site is reused, or ensure your credentials match the deploy's site. +4. **Run the claim:** + ```bash + edgeone makers claim --sid --json + # or, with the state file present: + edgeone makers claim --json + ``` +5. **On success** the CLI prints the project name, ID, and URL, then deletes `.edgeone/anonymous.json`. The project is now permanent and managed with the normal `edgeone makers deploy` flow. + +--- + +## Why Agent and storage projects must log in instead + +The anonymous deploy path builds with an empty environment: it calls the build with `ENV_STR: "{}"` and **skips both remote environment-variable pull and AI-gateway credential injection**, because those calls require authentication that an anonymous session does not have. + +Consequences: + +| Project type | Anonymous result | +|--------------|------------------| +| Static site / frontend framework | Works correctly. | +| Project with `agents/` (AI Agent endpoints) | Site loads, but AI conversations fail — no model credentials. | +| Project importing `@edgeone/pages-blob` or using KV | Site loads, but storage calls fail with `Missing: deployCredential`. | + +A site that loads but breaks on first interaction is worse than an explicit login prompt, so route these project types to login. Detection and wording are in [SKILL.md](../SKILL.md). + +--- + +## Agent / CI workflow example + +```bash +export PAGES_SOURCE=skills + +# 1. Not logged in, and this is a plain frontend project +edgeone makers deploy --anonymous --json +# → last stdout line is the JSON result + +# 2. Verify the deployment is live +curl -sSI "" | head -1 + +# 3. Later, once the user has an account +edgeone login --site global +edgeone makers claim --json # reads .edgeone/anonymous.json +``` + +Present all three of these to the user together after an anonymous deploy — the URL alone is not enough, because an unclaimed project expires: + +1. the full access URL, +2. how to claim (`claimCommand` and `claimUrl`), +3. the actual `expiresAt` value, and that the project is lost if unclaimed. From a8c82438796227b81f7f4f86bdce373fd78b2a4b Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:42:26 +0800 Subject: [PATCH 02/34] docs(makers-deploy): clarify expiresAt optionality, token lifetime, URL fidelity Code review found three imprecisions, all verified against the CLI source on origin/feature/anonymous: - toIsoExpires() returns undefined for a missing/invalid timestamp, so expiresAt can be absent from --json output. Say so, and keep the never-invent-a-duration rule for that case. - The anonymous token is reused across create_deployment, status polling and claim, so "single-use credential" was wrong. - Do not assert whether anonymous URLs carry auth query params (not verifiable from source); require verbatim, untruncated output instead. --- skills/makers-deploy/references/anonymous-deploy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 1d62e4d..231d4eb 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -70,13 +70,13 @@ Do not pass these — they have no effect and will mislead the user: | Field | Meaning | |-------|---------| -| `url` | Live access URL. Present it in full, including any query string. | +| `url` | Live access URL. Present it exactly as returned, never truncated — if it carries a query string, keep the whole thing. | | `projectId` | Anonymous project ID. | | `deploymentId` | Deployment ID. | | `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | | `claimUrl` | Web claim URL, on the console domain matching `site`. | | `claimCommand` | Ready-to-run CLI claim command. | -| `expiresAt` | **Actual** claim deadline, ISO 8601. Always show this value; never substitute a hardcoded duration. | +| `expiresAt` | **Actual** claim deadline, ISO 8601. Always show this value; never substitute a hardcoded duration. Omitted when the backend returns no usable expiry timestamp — in that case say the deadline is unknown and advise claiming promptly, and still never invent a duration. | | `site` | `china` or `global` — the API site this project lives on. | ### Failure @@ -125,7 +125,7 @@ Lifecycle: - **Kept on failure**, so a retry or a later claim can still find the token. - When present, `claim` needs no `--sid`. -Treat it as a secret: it contains a single-use credential. It lives under `.edgeone/`, which projects normally already ignore in git — confirm that before committing. +Treat it as a secret: it holds an ephemeral credential, valid until claimed or expired. It lives under `.edgeone/`, which projects normally already ignore in git — confirm that before committing. --- From e0436b4b44fda411d9c860e905225aca88b304e4 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:44:09 +0800 Subject: [PATCH 03/34] docs(makers-deploy): add anonymous deploy triggers and claim-param rule --- codex/makers-deploy.md | 8 +++++++- cursor/rules/makers-deploy.mdc | 8 +++++++- skills/makers-deploy/SKILL.md | 8 +++++++- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 2d0f3e3..a5050ed 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -8,13 +8,17 @@ description: >- "go live", "release", "publish a new version", "redeploy", "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". + Also trigger for login-free deployment and project claiming: + "deploy without login", "no account yet", "try it first", "anonymous deploy", + "claim project", "claim my deployment", + "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.2.0" + version: "2.3.0" --- # EdgeOne Makers Deployment Skill @@ -48,6 +52,8 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 2d0f3e3..a5050ed 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -8,13 +8,17 @@ description: >- "go live", "release", "publish a new version", "redeploy", "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". + Also trigger for login-free deployment and project claiming: + "deploy without login", "no account yet", "try it first", "anonymous deploy", + "claim project", "claim my deployment", + "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.2.0" + version: "2.3.0" --- # EdgeOne Makers Deployment Skill @@ -48,6 +52,8 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 2d0f3e3..a5050ed 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -8,13 +8,17 @@ description: >- "go live", "release", "publish a new version", "redeploy", "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". + Also trigger for login-free deployment and project claiming: + "deploy without login", "no account yet", "try it first", "anonymous deploy", + "claim project", "claim my deployment", + "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.2.0" + version: "2.3.0" --- # EdgeOne Makers Deployment Skill @@ -48,6 +52,8 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- From 642eb270a1ceb872e5f1fb26e200046c1a3b1fd5 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:53:57 +0800 Subject: [PATCH 04/34] docs(makers-deploy): tighten anonymous triggers, complete rule 10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop "先看看效果" and "try it first": both read as local-preview intent and risk routing dev-server requests into the deploy skill. - Rule 10: expiresAt can be absent from --json output (toIsoExpires returns undefined), so say what to do in that case. - Mark rules 9-10 as scoped to the anonymous flow. --- codex/makers-deploy.md | 7 ++++--- cursor/rules/makers-deploy.mdc | 7 ++++--- skills/makers-deploy/SKILL.md | 7 ++++--- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index a5050ed..e330347 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -9,9 +9,9 @@ description: >- "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". Also trigger for login-free deployment and project claiming: - "deploy without login", "no account yet", "try it first", "anonymous deploy", + "deploy without login", "no account yet", "anonymous deploy", "claim project", "claim my deployment", - "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". + "免登录部署", "匿名部署", "还没有账号", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — @@ -52,8 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +**Rules 9-10 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index a5050ed..e330347 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -9,9 +9,9 @@ description: >- "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". Also trigger for login-free deployment and project claiming: - "deploy without login", "no account yet", "try it first", "anonymous deploy", + "deploy without login", "no account yet", "anonymous deploy", "claim project", "claim my deployment", - "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". + "免登录部署", "匿名部署", "还没有账号", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — @@ -52,8 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +**Rules 9-10 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index a5050ed..e330347 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -9,9 +9,9 @@ description: >- "上线", "发布", "发一版", "重新部署", "搭建并部署", "开发并上线", "build and deploy", "create and deploy". Also trigger for login-free deployment and project claiming: - "deploy without login", "no account yet", "try it first", "anonymous deploy", + "deploy without login", "no account yet", "anonymous deploy", "claim project", "claim my deployment", - "免登录部署", "匿名部署", "还没有账号", "先看看效果", "认领项目". + "免登录部署", "匿名部署", "还没有账号", "认领项目". ⚠️ Also trigger when any agent is about to execute `edgeone makers deploy` or `edgeone makers deploy` commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — @@ -52,8 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +**Rules 9-10 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. --- From f838b8b2bd05817c14ff1da5ae97fcaffb2a9039 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:55:00 +0800 Subject: [PATCH 05/34] docs(makers-deploy): separate the rules 9-10 scope marker into its own block Without surrounding blank lines the marker was a lazy continuation of rule 8's paragraph, so it rendered as part of rule 8 rather than as a heading for the anonymous-only rules. --- codex/makers-deploy.md | 2 ++ cursor/rules/makers-deploy.mdc | 2 ++ skills/makers-deploy/SKILL.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index e330347..62eeb1f 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -52,7 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. + **Rules 9-10 apply to the anonymous deploy / claim flow only:** + 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index e330347..62eeb1f 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -52,7 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. + **Rules 9-10 apply to the anonymous deploy / claim flow only:** + 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index e330347..62eeb1f 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -52,7 +52,9 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. + **Rules 9-10 apply to the anonymous deploy / claim flow only:** + 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. From b0991b7678866ce3616737695c0b9362828b509c Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 19:59:40 +0800 Subject: [PATCH 06/34] docs(makers-deploy): raise CLI version gate to 1.6.21, route unauthenticated users to anonymous deploy --- codex/makers-deploy.md | 28 ++++++++++++++-------------- cursor/rules/makers-deploy.mdc | 28 ++++++++++++++-------------- skills/makers-deploy/SKILL.md | 28 ++++++++++++++-------------- 3 files changed, 42 insertions(+), 42 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 62eeb1f..1a4feca 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and will hang in Agent/CI environments. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,10 +86,10 @@ Run these checks first, then follow the decision table: # 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) +# Check 1: CLI installed and correct version? (must be >= 1.6.21) edgeone -v -# Check 2: Already logged in? (CLI >= 1.6.0 whoami fails fast, won't hang) +# 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 @@ -102,11 +102,11 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.0 | — | → Go to **Install CLI** | -| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **interactive desktop** | → Go to **Login** (browser) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Ask user for a **token**; browser login is unavailable and `deploy` will fail fast with a token hint | +| Not installed or < 1.6.21 | — | → Go to **Install CLI** | +| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | --- @@ -116,7 +116,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) +Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) --- @@ -147,7 +147,7 @@ Use the IDE's selection control (`ask_followup_question`) before running any log ⚠️ **CRITICAL**: After the user chooses, you MUST invoke login with an explicit `--site ` flag (e.g. `edgeone login --site china`). **NEVER run a bare `edgeone login` (without `--site`) when driven by an Agent / skill.** -On CLI ≥ 1.6.0, a bare `login` in a non-interactive context fails fast asking for +A bare `login` in a non-interactive context fails fast asking for `--site` (it no longer pops an interactive site-picker that would hang). The site choice is meant to happen here in the conversation, not inside the CLI. @@ -299,7 +299,7 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc ## ⚠️ Parse Deploy Output (Critical) -### Preferred: `--json` (CLI ≥ 1.6.0) +### Preferred: `--json` When deploy is run with `--json`, the **last line** of stdout is a single JSON object — parse that directly, no regex / ANSI cleanup needed: @@ -359,11 +359,11 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | | Browser does not open during login | Switch to token login | -| "not authenticated" / exit 1 from `whoami` (CLI ≥ 1.6.0) | Expected when not logged in — whoami now fails fast instead of hanging. Run `edgeone login` (desktop) or provide a token | +| "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | -| Deploy seems to hang at `[DeployStatus] Deploying...` | On CLI ≥ 1.6.0 non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | +| Deploy seems to hang at `[DeployStatus] Deploying...` | Non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | | Auth error with token | Token may be expired — regenerate at the console | | Login appears successful but `deploy` reports auth error | Browser reused a session from the wrong site, binding the wrong account. Click "Sign in with a different account" on the login page, or log out from all Tencent Cloud consoles first | | `edgeone whoami` shows an unexpected account | Browser session reuse. Click "Sign in with a different account" or log out from all consoles and re-login | diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 62eeb1f..1a4feca 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and will hang in Agent/CI environments. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,10 +86,10 @@ Run these checks first, then follow the decision table: # 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) +# Check 1: CLI installed and correct version? (must be >= 1.6.21) edgeone -v -# Check 2: Already logged in? (CLI >= 1.6.0 whoami fails fast, won't hang) +# 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 @@ -102,11 +102,11 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.0 | — | → Go to **Install CLI** | -| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **interactive desktop** | → Go to **Login** (browser) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Ask user for a **token**; browser login is unavailable and `deploy` will fail fast with a token hint | +| Not installed or < 1.6.21 | — | → Go to **Install CLI** | +| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | --- @@ -116,7 +116,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) +Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) --- @@ -147,7 +147,7 @@ Use the IDE's selection control (`ask_followup_question`) before running any log ⚠️ **CRITICAL**: After the user chooses, you MUST invoke login with an explicit `--site ` flag (e.g. `edgeone login --site china`). **NEVER run a bare `edgeone login` (without `--site`) when driven by an Agent / skill.** -On CLI ≥ 1.6.0, a bare `login` in a non-interactive context fails fast asking for +A bare `login` in a non-interactive context fails fast asking for `--site` (it no longer pops an interactive site-picker that would hang). The site choice is meant to happen here in the conversation, not inside the CLI. @@ -299,7 +299,7 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc ## ⚠️ Parse Deploy Output (Critical) -### Preferred: `--json` (CLI ≥ 1.6.0) +### Preferred: `--json` When deploy is run with `--json`, the **last line** of stdout is a single JSON object — parse that directly, no regex / ANSI cleanup needed: @@ -359,11 +359,11 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | | Browser does not open during login | Switch to token login | -| "not authenticated" / exit 1 from `whoami` (CLI ≥ 1.6.0) | Expected when not logged in — whoami now fails fast instead of hanging. Run `edgeone login` (desktop) or provide a token | +| "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | -| Deploy seems to hang at `[DeployStatus] Deploying...` | On CLI ≥ 1.6.0 non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | +| Deploy seems to hang at `[DeployStatus] Deploying...` | Non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | | Auth error with token | Token may be expired — regenerate at the console | | Login appears successful but `deploy` reports auth error | Browser reused a session from the wrong site, binding the wrong account. Click "Sign in with a different account" on the login page, or log out from all Tencent Cloud consoles first | | `edgeone whoami` shows an unexpected account | Browser session reuse. Click "Sign in with a different account" or log out from all consoles and re-login | diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 62eeb1f..1a4feca 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and will hang in Agent/CI environments. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,10 +86,10 @@ Run these checks first, then follow the decision table: # 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) +# Check 1: CLI installed and correct version? (must be >= 1.6.21) edgeone -v -# Check 2: Already logged in? (CLI >= 1.6.0 whoami fails fast, won't hang) +# 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 @@ -102,11 +102,11 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.0 | — | → Go to **Install CLI** | -| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **interactive desktop** | → Go to **Login** (browser) | -| `≥ 1.6.0` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Ask user for a **token**; browser login is unavailable and `deploy` will fail fast with a token hint | +| Not installed or < 1.6.21 | — | → Go to **Install CLI** | +| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | --- @@ -116,7 +116,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) +Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) --- @@ -147,7 +147,7 @@ Use the IDE's selection control (`ask_followup_question`) before running any log ⚠️ **CRITICAL**: After the user chooses, you MUST invoke login with an explicit `--site ` flag (e.g. `edgeone login --site china`). **NEVER run a bare `edgeone login` (without `--site`) when driven by an Agent / skill.** -On CLI ≥ 1.6.0, a bare `login` in a non-interactive context fails fast asking for +A bare `login` in a non-interactive context fails fast asking for `--site` (it no longer pops an interactive site-picker that would hang). The site choice is meant to happen here in the conversation, not inside the CLI. @@ -299,7 +299,7 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc ## ⚠️ Parse Deploy Output (Critical) -### Preferred: `--json` (CLI ≥ 1.6.0) +### Preferred: `--json` When deploy is run with `--json`, the **last line** of stdout is a single JSON object — parse that directly, no regex / ANSI cleanup needed: @@ -359,11 +359,11 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | | Browser does not open during login | Switch to token login | -| "not authenticated" / exit 1 from `whoami` (CLI ≥ 1.6.0) | Expected when not logged in — whoami now fails fast instead of hanging. Run `edgeone login` (desktop) or provide a token | +| "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | -| Deploy seems to hang at `[DeployStatus] Deploying...` | On CLI ≥ 1.6.0 non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | +| Deploy seems to hang at `[DeployStatus] Deploying...` | Non-TTY emits heartbeat lines; it is NOT stuck. If a wrapper still mis-detects, use `--json` or run in background and poll. Do not kill it | | Auth error with token | Token may be expired — regenerate at the console | | Login appears successful but `deploy` reports auth error | Browser reused a session from the wrong site, binding the wrong account. Click "Sign in with a different account" on the login page, or log out from all Tencent Cloud consoles first | | `edgeone whoami` shows an unexpected account | Browser session reuse. Click "Sign in with a different account" or log out from all consoles and re-login | From 44d11b1f941bd27862d4d405909f527f51a72b87 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:00:58 +0800 Subject: [PATCH 07/34] docs(makers-deploy): drop the stale 1.6.0 qualifier from rule 3b With the gate at 1.6.21 the "on CLI >= 1.6.0" caveat is noise: every supported version has whoami fail-fast. Leaves only the two intentional historical mentions of what pre-1.6.0 versions lacked. --- codex/makers-deploy.md | 2 +- cursor/rules/makers-deploy.mdc | 2 +- skills/makers-deploy/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 1a4feca..69d0de9 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -42,7 +42,7 @@ Deploy any project to **EdgeOne Makers**. **Self-check after writing your reply**: scan for every instance of the `.edgeone.cool` domain. Does each one include `?eo_token=`? If any doesn't, fix it NOW — the user will get a 401. 3a. **Prefer `--json` when running non-interactively** — in Agent/CI/headless contexts, always pass `--json` to `deploy` so the result is a single machine-readable line; no need to scrape colored/`\r`-animated stdout. See **Parse Deploy Output**. -3b. **Use `edgeone whoami` to check login status** — on CLI ≥ 1.6.0, `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. +3b. **Use `edgeone whoami` to check login status** — `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. 4. **⚠️ The deploy URL MUST be placed prominently at the very top of your reply** — once deployment finishes, the complete access URL is the core deliverable the user cares about most. You MUST: ① place it on the first line or in the first standalone block of your reply body; ② use a prominent format (e.g. a large heading + code block); ③ never bury the URL in the middle of a long paragraph where the user has to hunt for it. Example format: ``` 🌐 Live URL: https://my-project-abc123.edgeone.cool? diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 1a4feca..69d0de9 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -42,7 +42,7 @@ Deploy any project to **EdgeOne Makers**. **Self-check after writing your reply**: scan for every instance of the `.edgeone.cool` domain. Does each one include `?eo_token=`? If any doesn't, fix it NOW — the user will get a 401. 3a. **Prefer `--json` when running non-interactively** — in Agent/CI/headless contexts, always pass `--json` to `deploy` so the result is a single machine-readable line; no need to scrape colored/`\r`-animated stdout. See **Parse Deploy Output**. -3b. **Use `edgeone whoami` to check login status** — on CLI ≥ 1.6.0, `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. +3b. **Use `edgeone whoami` to check login status** — `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. 4. **⚠️ The deploy URL MUST be placed prominently at the very top of your reply** — once deployment finishes, the complete access URL is the core deliverable the user cares about most. You MUST: ① place it on the first line or in the first standalone block of your reply body; ② use a prominent format (e.g. a large heading + code block); ③ never bury the URL in the middle of a long paragraph where the user has to hunt for it. Example format: ``` 🌐 Live URL: https://my-project-abc123.edgeone.cool? diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 1a4feca..69d0de9 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -42,7 +42,7 @@ Deploy any project to **EdgeOne Makers**. **Self-check after writing your reply**: scan for every instance of the `.edgeone.cool` domain. Does each one include `?eo_token=`? If any doesn't, fix it NOW — the user will get a 401. 3a. **Prefer `--json` when running non-interactively** — in Agent/CI/headless contexts, always pass `--json` to `deploy` so the result is a single machine-readable line; no need to scrape colored/`\r`-animated stdout. See **Parse Deploy Output**. -3b. **Use `edgeone whoami` to check login status** — on CLI ≥ 1.6.0, `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. +3b. **Use `edgeone whoami` to check login status** — `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. 4. **⚠️ The deploy URL MUST be placed prominently at the very top of your reply** — once deployment finishes, the complete access URL is the core deliverable the user cares about most. You MUST: ① place it on the first line or in the first standalone block of your reply body; ② use a prominent format (e.g. a large heading + code block); ③ never bury the URL in the middle of a long paragraph where the user has to hunt for it. Example format: ``` 🌐 Live URL: https://my-project-abc123.edgeone.cool? From e98f60a381636d4ed66e45dfe0a750a2dc0b0921 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:11:18 +0800 Subject: [PATCH 08/34] fix(makers-deploy): scope the 1.6.21 floor to anonymous deploy only Raising the GLOBAL gate to 1.6.21 was a correctness bug. 1.6.21 is an unreleased placeholder (branch is 1.6.18, npm latest is 1.6.20), so an agent on 1.6.20 would read rule 1's 'never proceed with an outdated version', fail to upgrade past 1.6.20, and refuse every deploy -- including normal authenticated ones that work fine on 1.6.20. Now: global floor stays 1.6.0; 1.6.21 gates only --anonymous and claim. Adds a decision-table row for 1.6.0-1.6.20 (login/token path) and an error row for --anonymous being rejected as an unknown option. --- codex/makers-deploy.md | 16 +++++++++------- cursor/rules/makers-deploy.mdc | 16 +++++++++------- skills/makers-deploy/SKILL.md | 16 +++++++++------- 3 files changed, 27 insertions(+), 21 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 69d0de9..85249d8 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments. Never proceed with an outdated version. **Anonymous deploy and `claim` additionally require `1.6.21`** — that is a higher, feature-specific floor; see **Anonymous Deploy**. Do not block a normal authenticated deploy because the CLI is below `1.6.21`. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,7 +86,7 @@ Run these checks first, then follow the decision table: # 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.21) +# Check 1: CLI installed and correct version? (must be >= 1.6.0; anonymous deploy needs >= 1.6.21) edgeone -v # Check 2: Already logged in? (whoami fails fast, won't hang) @@ -102,11 +102,12 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.21 | — | → Go to **Install CLI** | -| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| Not installed or < 1.6.0 | — | → Go to **Install CLI** | +| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -116,7 +117,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) +Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) Anonymous deploy and `claim` need `1.6.21`; if `latest` is still below that, those two features are simply unavailable — normal authenticated deploy works fine. --- @@ -359,7 +360,8 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | +| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| `--anonymous` / `claim` reported as an unknown option | The installed CLI is below `1.6.21`. Run `npm install -g edgeone@latest`; if that is still below `1.6.21`, anonymous deploy is not released yet — use login or a token instead | | Browser does not open during login | Switch to token login | | "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 69d0de9..85249d8 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments. Never proceed with an outdated version. **Anonymous deploy and `claim` additionally require `1.6.21`** — that is a higher, feature-specific floor; see **Anonymous Deploy**. Do not block a normal authenticated deploy because the CLI is below `1.6.21`. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,7 +86,7 @@ Run these checks first, then follow the decision table: # 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.21) +# Check 1: CLI installed and correct version? (must be >= 1.6.0; anonymous deploy needs >= 1.6.21) edgeone -v # Check 2: Already logged in? (whoami fails fast, won't hang) @@ -102,11 +102,12 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.21 | — | → Go to **Install CLI** | -| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| Not installed or < 1.6.0 | — | → Go to **Install CLI** | +| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -116,7 +117,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) +Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) Anonymous deploy and `claim` need `1.6.21`; if `latest` is still below that, those two features are simply unavailable — normal authenticated deploy works fine. --- @@ -359,7 +360,8 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | +| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| `--anonymous` / `claim` reported as an unknown option | The installed CLI is below `1.6.21`. Run `npm install -g edgeone@latest`; if that is still below `1.6.21`, anonymous deploy is not released yet — use login or a token instead | | Browser does not open during login | Switch to token login | | "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 69d0de9..85249d8 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -27,7 +27,7 @@ Deploy any project to **EdgeOne Makers**. ## ⛔ Critical Rules (never skip) -1. **CLI version ≥ `1.6.21`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments; anonymous deploy and `claim` require `1.6.21`. Never proceed with an outdated version. +1. **CLI version ≥ `1.6.0`** — reinstall if lower. Versions below `1.6.0` lack the non-interactive fixes (whoami fail-fast, `--json` output) and hang in Agent/CI environments. Never proceed with an outdated version. **Anonymous deploy and `claim` additionally require `1.6.21`** — that is a higher, feature-specific floor; see **Anonymous Deploy**. Do not block a normal authenticated deploy because the CLI is below `1.6.21`. 2. **Never truncate the deploy URL — this applies to EVERY mention** — `EDGEONE_DEPLOY_URL` includes query parameters (`?eo_token=...&eo_time=...`) required for access. Without them the page returns 401. Always output the **complete** URL with full query string. This rule applies to: the primary display, summary tables, footnotes, comparisons, code blocks, `present_files` calls — **every single occurrence** of the URL in your reply. Truncation is any removal of the `?` and everything after it. ❌ WRONG (truncated — will 401): @@ -86,7 +86,7 @@ Run these checks first, then follow the decision table: # 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.21) +# Check 1: CLI installed and correct version? (must be >= 1.6.0; anonymous deploy needs >= 1.6.21) edgeone -v # Check 2: Already logged in? (whoami fails fast, won't hang) @@ -102,11 +102,12 @@ cat edgeone.json 2>/dev/null | CLI version | Login status | Action | |-------------|-------------|--------| -| Not installed or < 1.6.21 | — | → Go to **Install CLI** | -| `≥ 1.6.21` ✓ | Logged in (or token present) | → Go to **Deploy** | -| `≥ 1.6.21` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | +| Not installed or < 1.6.0 | — | → Go to **Install CLI** | +| `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | +| `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -116,7 +117,7 @@ cat edgeone.json 2>/dev/null npm install -g edgeone@latest ``` -Verify: `edgeone -v` — confirm output is `1.6.21` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`; anonymous deploy and `claim` need `1.6.21`.) +Verify: `edgeone -v` — confirm output is `1.6.0` or higher. Retry installation if not. (Versions < 1.6.0 hang on `whoami`/login in non-interactive environments and lack `--json`.) Anonymous deploy and `claim` need `1.6.21`; if `latest` is still below that, those two features are simply unavailable — normal authenticated deploy works fine. --- @@ -359,7 +360,8 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Error | Solution | |-------|----------| | `command not found: edgeone` | Run `npm install -g edgeone@latest` | -| CLI version < 1.6.21 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts, and lack `--anonymous` / `claim` | +| CLI version < 1.6.0 | Reinstall: `npm install -g edgeone@latest`. Older versions hang on whoami/login in non-interactive contexts | +| `--anonymous` / `claim` reported as an unknown option | The installed CLI is below `1.6.21`. Run `npm install -g edgeone@latest`; if that is still below `1.6.21`, anonymous deploy is not released yet — use login or a token instead | | Browser does not open during login | Switch to token login | | "not authenticated" / exit 1 from `whoami` | Expected when not logged in — whoami fails fast instead of hanging. Offer anonymous deploy (see Anonymous Deploy), run `edgeone login`, or provide a token | | Non-interactive deploy says "browser login is unavailable" + exits 1 | Expected fail-fast in Agent/CI/headless with no token. Provide a token via `-t ` or set `EDGEONE_PAGES_API_TOKEN` | From 747e966aa4e8d2f143d7ac1344bae83daf41ae16 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:14:41 +0800 Subject: [PATCH 09/34] docs(makers-deploy): add Anonymous Deploy section with exclusion check and claim flow --- codex/makers-deploy.md | 86 ++++++++++++++++++++++++++++++++++ cursor/rules/makers-deploy.mdc | 86 ++++++++++++++++++++++++++++++++++ skills/makers-deploy/SKILL.md | 86 ++++++++++++++++++++++++++++++++++ 3 files changed, 258 insertions(+) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 85249d8..9819931 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -298,6 +298,92 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc --- +## Anonymous Deploy (no login required) + +When the user is not logged in and has no token, they can deploy anonymously and claim the project later. Requires CLI `>= 1.6.21`. On `1.6.0`–`1.6.20` this feature does not exist — use **Login** or a token instead. + +### Step 1: Exclusion check — run this FIRST + +Anonymous deploy builds with an empty environment: it skips remote env-var pull and AI-gateway credential injection, because both need authentication. Projects depending on either will deploy successfully but break at runtime. + +```bash +# Is this an Agent project? +ls agents/ 2>/dev/null && echo "AGENT_PROJECT" + +# Does it use platform storage? +grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ + --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ + . 2>/dev/null | head -1 +``` + +If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. + +Plain static sites and frontend-framework projects with no such dependency may proceed. + +### Step 2: Ask the user — do not deploy anonymously without asking + +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): + +> You're not logged in to EdgeOne Makers. Two options: +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. + +⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. + +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. + +### Step 3: Deploy + +```bash +export PAGES_SOURCE=skills +edgeone makers deploy --anonymous --json +``` + +Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. + +Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. + +### Step 4: Present the result — all three parts are mandatory + +Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. + +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. + +1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). +2. **How to claim** — both `claimCommand` and `claimUrl`. +3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. + +Example shape: + +> 🌐 **Live URL**: `` +> +> --- +> +> ⏳ **Claim before ``** — otherwise this project is removed. +> +> - Claim via CLI: `` +> - Claim in browser: `` + +### Claiming a project + +Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: + +```bash +edgeone makers claim --json +# or pass the token explicitly: +edgeone makers claim --sid --json +``` + +⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. + +Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. + +For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). + +--- + ## ⚠️ Parse Deploy Output (Critical) ### Preferred: `--json` diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 85249d8..9819931 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -298,6 +298,92 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc --- +## Anonymous Deploy (no login required) + +When the user is not logged in and has no token, they can deploy anonymously and claim the project later. Requires CLI `>= 1.6.21`. On `1.6.0`–`1.6.20` this feature does not exist — use **Login** or a token instead. + +### Step 1: Exclusion check — run this FIRST + +Anonymous deploy builds with an empty environment: it skips remote env-var pull and AI-gateway credential injection, because both need authentication. Projects depending on either will deploy successfully but break at runtime. + +```bash +# Is this an Agent project? +ls agents/ 2>/dev/null && echo "AGENT_PROJECT" + +# Does it use platform storage? +grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ + --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ + . 2>/dev/null | head -1 +``` + +If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. + +Plain static sites and frontend-framework projects with no such dependency may proceed. + +### Step 2: Ask the user — do not deploy anonymously without asking + +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): + +> You're not logged in to EdgeOne Makers. Two options: +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. + +⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. + +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. + +### Step 3: Deploy + +```bash +export PAGES_SOURCE=skills +edgeone makers deploy --anonymous --json +``` + +Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. + +Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. + +### Step 4: Present the result — all three parts are mandatory + +Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. + +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. + +1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). +2. **How to claim** — both `claimCommand` and `claimUrl`. +3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. + +Example shape: + +> 🌐 **Live URL**: `` +> +> --- +> +> ⏳ **Claim before ``** — otherwise this project is removed. +> +> - Claim via CLI: `` +> - Claim in browser: `` + +### Claiming a project + +Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: + +```bash +edgeone makers claim --json +# or pass the token explicitly: +edgeone makers claim --sid --json +``` + +⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. + +Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. + +For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). + +--- + ## ⚠️ Parse Deploy Output (Critical) ### Preferred: `--json` diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 85249d8..9819931 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -298,6 +298,92 @@ The CLI auto-detects the framework, runs the build, and uploads the output direc --- +## Anonymous Deploy (no login required) + +When the user is not logged in and has no token, they can deploy anonymously and claim the project later. Requires CLI `>= 1.6.21`. On `1.6.0`–`1.6.20` this feature does not exist — use **Login** or a token instead. + +### Step 1: Exclusion check — run this FIRST + +Anonymous deploy builds with an empty environment: it skips remote env-var pull and AI-gateway credential injection, because both need authentication. Projects depending on either will deploy successfully but break at runtime. + +```bash +# Is this an Agent project? +ls agents/ 2>/dev/null && echo "AGENT_PROJECT" + +# Does it use platform storage? +grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ + --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ + . 2>/dev/null | head -1 +``` + +If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. + +Plain static sites and frontend-framework projects with no such dependency may proceed. + +### Step 2: Ask the user — do not deploy anonymously without asking + +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): + +> You're not logged in to EdgeOne Makers. Two options: +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. + +⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. + +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. + +### Step 3: Deploy + +```bash +export PAGES_SOURCE=skills +edgeone makers deploy --anonymous --json +``` + +Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. + +Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. + +### Step 4: Present the result — all three parts are mandatory + +Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. + +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. + +1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). +2. **How to claim** — both `claimCommand` and `claimUrl`. +3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. + +Example shape: + +> 🌐 **Live URL**: `` +> +> --- +> +> ⏳ **Claim before ``** — otherwise this project is removed. +> +> - Claim via CLI: `` +> - Claim in browser: `` + +### Claiming a project + +Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: + +```bash +edgeone makers claim --json +# or pass the token explicitly: +edgeone makers claim --sid --json +``` + +⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. + +Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. + +For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). + +--- + ## ⚠️ Parse Deploy Output (Critical) ### Preferred: `--json` From 7ec8b55569ca9a74bb1ff77995478d5c7698b27e Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:24:17 +0800 Subject: [PATCH 10/34] fix(makers-deploy): repair the storage exclusion check The check grepped for '@edgeone/pages-kv', which does not exist (npm 404). KV is bound in the console and exposed as a global variable under a user-chosen name, so it cannot be detected from source at all. Every KV-dependent project therefore passed the check silently -- the exact false-negative the check existed to prevent. - Drop the phantom package; ask the user about KV instead. - Blob grep: add .vue/.svelte/.mjs/.cjs and check package.json, so an import inside an SFC is no longer missed. - Use grep -E rather than BRE \| alternation. - Say what to do when the user insists on anonymous anyway. Commands verified against fixtures: they match a blob import in .ts, .vue and package.json, and stay silent on a clean project. --- codex/makers-deploy.md | 20 ++++++++++++++----- cursor/rules/makers-deploy.mdc | 20 ++++++++++++++----- skills/makers-deploy/SKILL.md | 20 ++++++++++++++----- .../references/anonymous-deploy.md | 4 +++- 4 files changed, 48 insertions(+), 16 deletions(-) diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 9819931..ffa61c8 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -310,18 +310,28 @@ Anonymous deploy builds with an empty environment: it skips remote env-var pull # Is this an Agent project? ls agents/ 2>/dev/null && echo "AGENT_PROJECT" -# Does it use platform storage? -grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ - --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ +# 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 ``` -If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: +Non-empty output from either grep means the project uses Blob. -> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. +**KV cannot be detected this way — you must ask.** A KV namespace is bound in the console and exposed as a *global variable* whose name the user chose (e.g. `my_kv`), so there is no package import to grep for. There is no `@edgeone/pages-kv` package. Ask the user directly: + +> Does this project use KV storage? + +If either check hits, or the user says the project uses KV, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials or a storage binding, which anonymous deploy cannot provide. The site would load but those features would fail. Let's log in so it works properly. Plain static sites and frontend-framework projects with no such dependency may proceed. +If the user acknowledges the limitation and still wants an anonymous deploy, you may proceed — but state prominently in your result that AI and storage features will not work until the project is claimed and configured. + ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 9819931..ffa61c8 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -310,18 +310,28 @@ Anonymous deploy builds with an empty environment: it skips remote env-var pull # Is this an Agent project? ls agents/ 2>/dev/null && echo "AGENT_PROJECT" -# Does it use platform storage? -grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ - --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ +# 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 ``` -If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: +Non-empty output from either grep means the project uses Blob. -> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. +**KV cannot be detected this way — you must ask.** A KV namespace is bound in the console and exposed as a *global variable* whose name the user chose (e.g. `my_kv`), so there is no package import to grep for. There is no `@edgeone/pages-kv` package. Ask the user directly: + +> Does this project use KV storage? + +If either check hits, or the user says the project uses KV, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials or a storage binding, which anonymous deploy cannot provide. The site would load but those features would fail. Let's log in so it works properly. Plain static sites and frontend-framework projects with no such dependency may proceed. +If the user acknowledges the limitation and still wants an anonymous deploy, you may proceed — but state prominently in your result that AI and storage features will not work until the project is claimed and configured. + ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 9819931..ffa61c8 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -310,18 +310,28 @@ Anonymous deploy builds with an empty environment: it skips remote env-var pull # Is this an Agent project? ls agents/ 2>/dev/null && echo "AGENT_PROJECT" -# Does it use platform storage? -grep -rl "@edgeone/pages-blob\|@edgeone/pages-kv" \ - --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" \ +# 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 ``` -If either check hits, **do not deploy anonymously.** Go to **Login** and tell the user why: +Non-empty output from either grep means the project uses Blob. -> This project needs environment variables / AI gateway credentials, which anonymous deploy cannot inject. The site would load but the AI features would fail. Let's log in so it works properly. +**KV cannot be detected this way — you must ask.** A KV namespace is bound in the console and exposed as a *global variable* whose name the user chose (e.g. `my_kv`), so there is no package import to grep for. There is no `@edgeone/pages-kv` package. Ask the user directly: + +> Does this project use KV storage? + +If either check hits, or the user says the project uses KV, **do not deploy anonymously.** Go to **Login** and tell the user why: + +> This project needs environment variables / AI gateway credentials or a storage binding, which anonymous deploy cannot provide. The site would load but those features would fail. Let's log in so it works properly. Plain static sites and frontend-framework projects with no such dependency may proceed. +If the user acknowledges the limitation and still wants an anonymous deploy, you may proceed — but state prominently in your result that AI and storage features will not work until the project is claimed and configured. + ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 231d4eb..0902674 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -216,10 +216,12 @@ Consequences: |--------------|------------------| | Static site / frontend framework | Works correctly. | | Project with `agents/` (AI Agent endpoints) | Site loads, but AI conversations fail — no model credentials. | -| Project importing `@edgeone/pages-blob` or using KV | Site loads, but storage calls fail with `Missing: deployCredential`. | +| Project importing `@edgeone/pages-blob`, or bound to a KV namespace | Site loads, but storage calls fail — Blob reports `Missing: deployCredential`, and a KV global is undefined because an anonymous project has no namespace binding. | A site that loads but breaks on first interaction is worse than an explicit login prompt, so route these project types to login. Detection and wording are in [SKILL.md](../SKILL.md). +⚠️ Blob is detectable by grepping for its package import; **KV is not**. A KV namespace is bound in the console and surfaces as a global variable whose name the user chose, so there is no import to find and there is no `@edgeone/pages-kv` package. Ask the user whether the project uses KV rather than relying on a search. + --- ## Agent / CI workflow example From 06a38ae25dd12329a5a0e147a35179e5ffe3c1ab Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:26:40 +0800 Subject: [PATCH 11/34] docs(makers-deploy): add anonymous deploy and claim to command reference --- skills/makers-deploy/references/command-reference.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/skills/makers-deploy/references/command-reference.md b/skills/makers-deploy/references/command-reference.md index f1c77d2..3dd373f 100644 --- a/skills/makers-deploy/references/command-reference.md +++ b/skills/makers-deploy/references/command-reference.md @@ -45,7 +45,7 @@ edgeone makers link --name -t # Non-interactive | Action | Command | |--------|---------| | Install CLI | `npm install -g edgeone@latest` | -| Check version | `edgeone -v` (require ≥ 1.6.0) | +| Check version | `edgeone -v` (require ≥ 1.6.0; anonymous deploy and `claim` need ≥ 1.6.21) | | Login (China, browser) | `edgeone login --site china` | | Login (Global, browser) | `edgeone login --site global` | | Login (token, auto-site) | `edgeone login --token ` | @@ -61,6 +61,9 @@ edgeone makers link --name -t # Non-interactive | Deploy preview | `edgeone makers deploy -e preview` | | Deploy with token | `edgeone makers deploy -t ` | | Deploy (JSON, Agent/CI) | `edgeone makers deploy -n -t --json` | +| Deploy anonymously (no login) | `edgeone makers deploy --anonymous --json` | +| Deploy anonymously to a site | `edgeone makers deploy --anonymous --site china\|global --json` | +| Claim an anonymous project | `edgeone makers claim --sid --json` | ## Makers Commands (Agent Projects) @@ -88,9 +91,16 @@ For projects with `agents/` directory (AI Agent endpoints). `edgeone makers` com | `--json` | deploy | Machine-readable JSON output (single line) | | `--port ` | dev | Custom frontend port | | `-e preview\|production` | deploy | Target environment | +| `--anonymous` | deploy | Deploy without login; ignored when already authenticated. No `-a` short form (taken by `--area`) | +| `--site china\|global` | deploy (with `--anonymous`), login | Target API site; auto-detected by IP when omitted | +| `--sid ` | claim | Anonymous identity token; optional when `.edgeone/anonymous.json` exists. **Not** the same as `-t` | **Token precedence** (highest to lowest): 1. `-t ` flag on the command 2. `EDGEONE_PAGES_API_TOKEN` environment variable 3. `.edgeone/.token` file (saved token) 4. Browser login state + +## Anonymous Deploy + +For login-free deployment and the claim flow, see [anonymous-deploy.md](anonymous-deploy.md). From 6298fb6ca829a00560c69f315c1cd385c958e2f3 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:27:28 +0800 Subject: [PATCH 12/34] docs(makers-cli): add anonymous deploy and claim commands --- codex/makers-cli.md | 6 +++++- cursor/rules/makers-cli.mdc | 6 +++++- skills/makers-cli/SKILL.md | 6 +++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/codex/makers-cli.md b/codex/makers-cli.md index ea6e420..2a55623 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.0.0" + version: "1.1.0" --- # EdgeOne Makers CLI Reference @@ -28,6 +28,8 @@ Verify: `edgeone -v` | `edgeone makers deploy -n ` | Deploy as a new project | | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | +| `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | | `edgeone makers env set ` | Set a remote environment variable | @@ -38,6 +40,8 @@ Verify: `edgeone -v` | `edgeone login --site global` | Login to Global site | | `edgeone whoami` | Check current login status | +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). + ## Environment Variable Before any `edgeone` command, set: diff --git a/cursor/rules/makers-cli.mdc b/cursor/rules/makers-cli.mdc index ea6e420..2a55623 100644 --- a/cursor/rules/makers-cli.mdc +++ b/cursor/rules/makers-cli.mdc @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.0.0" + version: "1.1.0" --- # EdgeOne Makers CLI Reference @@ -28,6 +28,8 @@ Verify: `edgeone -v` | `edgeone makers deploy -n ` | Deploy as a new project | | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | +| `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | | `edgeone makers env set ` | Set a remote environment variable | @@ -38,6 +40,8 @@ Verify: `edgeone -v` | `edgeone login --site global` | Login to Global site | | `edgeone whoami` | Check current login status | +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). + ## Environment Variable Before any `edgeone` command, set: diff --git a/skills/makers-cli/SKILL.md b/skills/makers-cli/SKILL.md index ea6e420..2a55623 100644 --- a/skills/makers-cli/SKILL.md +++ b/skills/makers-cli/SKILL.md @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.0.0" + version: "1.1.0" --- # EdgeOne Makers CLI Reference @@ -28,6 +28,8 @@ Verify: `edgeone -v` | `edgeone makers deploy -n ` | Deploy as a new project | | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | +| `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | | `edgeone makers env set ` | Set a remote environment variable | @@ -38,6 +40,8 @@ Verify: `edgeone -v` | `edgeone login --site global` | Login to Global site | | `edgeone whoami` | Check current login status | +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). + ## Environment Variable Before any `edgeone` command, set: From d4a70ac9af1ea32f9f1481ab9adc07ae30ffde39 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:28:03 +0800 Subject: [PATCH 13/34] chore: register anonymous-deploy reference, bump to 1.1.0 --- _meta.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_meta.json b/_meta.json index 2bd2717..ae1751a 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.0.4", + "version": "1.1.0", "files": [ "SKILL.md", "CLAUDE.md", @@ -34,6 +34,7 @@ "skills/makers-cloud-functions/references/python-functions.md", "skills/makers-cloud-functions/references/troubleshooting.md", "skills/makers-deploy/SKILL.md", + "skills/makers-deploy/references/anonymous-deploy.md", "skills/makers-deploy/references/command-reference.md", "skills/makers-edge-functions/SKILL.md", "skills/makers-env-adaption/SKILL.md", From e771886c8efbf15cfba766ae472d800a64db8b3a Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 5 Aug 2026 20:33:13 +0800 Subject: [PATCH 14/34] docs(makers-cli): add the --site variant for anonymous deploy CI and Agent callers need deterministic site selection; without this row they had to open the reference to discover --site exists. --- codex/makers-cli.md | 1 + cursor/rules/makers-cli.mdc | 1 + skills/makers-cli/SKILL.md | 1 + 3 files changed, 3 insertions(+) diff --git a/codex/makers-cli.md b/codex/makers-cli.md index 2a55623..3607acb 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -29,6 +29,7 @@ Verify: `edgeone -v` | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | | `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers deploy --anonymous --site china\|global --json` | Anonymous deploy to a specific site (omit `--site` to auto-detect by IP) | | `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | diff --git a/cursor/rules/makers-cli.mdc b/cursor/rules/makers-cli.mdc index 2a55623..3607acb 100644 --- a/cursor/rules/makers-cli.mdc +++ b/cursor/rules/makers-cli.mdc @@ -29,6 +29,7 @@ Verify: `edgeone -v` | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | | `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers deploy --anonymous --site china\|global --json` | Anonymous deploy to a specific site (omit `--site` to auto-detect by IP) | | `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | diff --git a/skills/makers-cli/SKILL.md b/skills/makers-cli/SKILL.md index 2a55623..3607acb 100644 --- a/skills/makers-cli/SKILL.md +++ b/skills/makers-cli/SKILL.md @@ -29,6 +29,7 @@ Verify: `edgeone -v` | `edgeone makers deploy -t ` | Deploy with API token (CI/headless) | | `edgeone makers deploy -e preview` | Deploy to preview environment | | `edgeone makers deploy --anonymous --json` | Deploy without login; claim later (CLI ≥ 1.6.21) | +| `edgeone makers deploy --anonymous --site china\|global --json` | Anonymous deploy to a specific site (omit `--site` to auto-detect by IP) | | `edgeone makers claim --sid ` | Claim an anonymously-deployed project (requires login) | | `edgeone makers link` | Link local project to remote EdgeOne project | | `edgeone makers env pull` | Pull remote env vars to local `.env` | From 7a6974246237fe16aad9bedddb33f58e7e54e720 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Fri, 7 Aug 2026 15:25:52 +0800 Subject: [PATCH 15/34] docs: stop showing users a CLI claim command Feedback from a WorkBuddy test run: the result printed 'edgeone makers claim --sid ' as the user's way to claim. In the WorkBuddy sandbox the user has no terminal and cannot run it, and a non-technical user cannot read it either -- so the claim path read as a dead end. - New critical rule 11: never print claimCommand or any claim command as the user's route. Show the claimUrl link; offer to run the claim. - Step 4 presentation: clickable claim link plus 'or tell me to claim it'. - Claim section reframed as something the agent executes, reporting the outcome in plain language rather than raw JSON. - Reference: claim flow split into Route A (user clicks link, the one to advertise) and Route B (agent runs it). - env-adaption gains section 13: never hand the sandboxed user a command to run, since the agent is the one with shell access. Versions: makers-deploy 2.4.0, env-adaption 1.2.0, _meta 1.2.0. --- _meta.json | 4 ++-- codex/makers-deploy.md | 16 +++++++++++----- codex/makers-env-adaption.md | 17 ++++++++++++++++- cursor/rules/makers-deploy.mdc | 16 +++++++++++----- cursor/rules/makers-env-adaption.mdc | 17 ++++++++++++++++- skills/makers-deploy/SKILL.md | 16 +++++++++++----- .../references/anonymous-deploy.md | 18 +++++++++++++----- skills/makers-env-adaption/SKILL.md | 17 ++++++++++++++++- 8 files changed, 96 insertions(+), 25 deletions(-) diff --git a/_meta.json b/_meta.json index ae1751a..aeed6c5 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.1.0", + "version": "1.2.0", "files": [ "SKILL.md", "CLAUDE.md", @@ -44,4 +44,4 @@ "skills/makers-storage/references/blob.md", "skills/makers-storage/references/kv.md" ] -} \ No newline at end of file +} diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index ffa61c8..4cc17c0 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.3.0" + version: "2.4.0" --- # EdgeOne Makers Deployment Skill @@ -53,10 +53,11 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-10 apply to the anonymous deploy / claim flow only:** +**Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -362,7 +363,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **How to claim** — both `claimCommand` and `claimUrl`. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. 3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. Example shape: @@ -373,11 +374,14 @@ Example shape: > > ⏳ **Claim before ``** — otherwise this project is removed. > -> - Claim via CLI: `` -> - Claim in browser: `` +> 👉 [Claim this project]() — sign in and it's permanently yours. +> +> Or just tell me "claim it" and I'll do it for you. ### Claiming a project +**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. + Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: ```bash @@ -390,6 +394,8 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. + For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). --- diff --git a/codex/makers-env-adaption.md b/codex/makers-env-adaption.md index 4c6fcc3..53a9a79 100644 --- a/codex/makers-env-adaption.md +++ b/codex/makers-env-adaption.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # Runtime Environment Adaptation Guide @@ -267,7 +267,22 @@ If the project named by `--name` does not exist remotely, the `link` command cre | Framework/package | Minimum version | Reason | |---------|---------|------| | EdgeOne CLI | >= 1.6.7 | Non-interactive fixes, whoami fail-fast, --json support | +| EdgeOne CLI (anonymous deploy / `claim` only) | >= 1.6.21 | `--anonymous` and `claim` do not exist below this | | Next.js | 16.x | The framework adapter tracks new versions | | @edgeone/pages-blob | >= 0.0.14 | Older versions have known bugs | Use `create-next-app@latest` rather than manually pinning an older version. + +--- + +### 13. Never hand the user a command to run + +The user has **no terminal** in the WorkBuddy sandbox. Any command you print as an instruction is dead text — they cannot execute it, and a non-technical user cannot read it either. + +| Situation | Do this | Not this | +|---|---|---| +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | +| Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | + +You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index ffa61c8..4cc17c0 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.3.0" + version: "2.4.0" --- # EdgeOne Makers Deployment Skill @@ -53,10 +53,11 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-10 apply to the anonymous deploy / claim flow only:** +**Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -362,7 +363,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **How to claim** — both `claimCommand` and `claimUrl`. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. 3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. Example shape: @@ -373,11 +374,14 @@ Example shape: > > ⏳ **Claim before ``** — otherwise this project is removed. > -> - Claim via CLI: `` -> - Claim in browser: `` +> 👉 [Claim this project]() — sign in and it's permanently yours. +> +> Or just tell me "claim it" and I'll do it for you. ### Claiming a project +**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. + Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: ```bash @@ -390,6 +394,8 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. + For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). --- diff --git a/cursor/rules/makers-env-adaption.mdc b/cursor/rules/makers-env-adaption.mdc index 4c6fcc3..53a9a79 100644 --- a/cursor/rules/makers-env-adaption.mdc +++ b/cursor/rules/makers-env-adaption.mdc @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # Runtime Environment Adaptation Guide @@ -267,7 +267,22 @@ If the project named by `--name` does not exist remotely, the `link` command cre | Framework/package | Minimum version | Reason | |---------|---------|------| | EdgeOne CLI | >= 1.6.7 | Non-interactive fixes, whoami fail-fast, --json support | +| EdgeOne CLI (anonymous deploy / `claim` only) | >= 1.6.21 | `--anonymous` and `claim` do not exist below this | | Next.js | 16.x | The framework adapter tracks new versions | | @edgeone/pages-blob | >= 0.0.14 | Older versions have known bugs | Use `create-next-app@latest` rather than manually pinning an older version. + +--- + +### 13. Never hand the user a command to run + +The user has **no terminal** in the WorkBuddy sandbox. Any command you print as an instruction is dead text — they cannot execute it, and a non-technical user cannot read it either. + +| Situation | Do this | Not this | +|---|---|---| +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | +| Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | + +You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index ffa61c8..4cc17c0 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.3.0" + version: "2.4.0" --- # EdgeOne Makers Deployment Skill @@ -53,10 +53,11 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-10 apply to the anonymous deploy / claim flow only:** +**Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -362,7 +363,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **How to claim** — both `claimCommand` and `claimUrl`. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. 3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. Example shape: @@ -373,11 +374,14 @@ Example shape: > > ⏳ **Claim before ``** — otherwise this project is removed. > -> - Claim via CLI: `` -> - Claim in browser: `` +> 👉 [Claim this project]() — sign in and it's permanently yours. +> +> Or just tell me "claim it" and I'll do it for you. ### Claiming a project +**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. + Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: ```bash @@ -390,6 +394,8 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. + For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). --- diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 0902674..5fcde58 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -74,8 +74,8 @@ Do not pass these — they have no effect and will mislead the user: | `projectId` | Anonymous project ID. | | `deploymentId` | Deployment ID. | | `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | -| `claimUrl` | Web claim URL, on the console domain matching `site`. | -| `claimCommand` | Ready-to-run CLI claim command. | +| `claimUrl` | Web claim URL, on the console domain matching `site`. **This is what you show the user** — a clickable link. | +| `claimCommand` | Ready-to-run CLI claim command. **For you to execute, never to display** — see the note below. | | `expiresAt` | **Actual** claim deadline, ISO 8601. Always show this value; never substitute a hardcoded duration. Omitted when the backend returns no usable expiry timestamp — in that case say the deadline is unknown and advise claiming promptly, and still never invent a duration. | | `site` | `china` or `global` — the API site this project lives on. | @@ -87,6 +87,8 @@ Do not pass these — they have no effect and will mislead the user: `suggestion` is only present for the rate-limit case. `errorCode` may be absent for generic failures. +⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and offer to run the claim yourself. `claimCommand` exists for **you** to execute. + --- ## Three different expiry windows — do not conflate them @@ -193,16 +195,22 @@ The backend claims **asynchronously** and only migrates projects whose deploymen ## Claim flow +Two independent routes. Pick by who acts: + +**Route A — the user claims in the browser (default, and the only one to advertise).** Give them the `claimUrl` link. They sign in and the project transfers. Nothing to run. + +**Route B — you claim on their behalf**, when the user says "claim it" or is already logged in: + 1. **Deploy must have succeeded.** Only `Success` deployments are migrated. 2. **Log in.** In an interactive environment the CLI opens a browser when needed; in CI, pass `-t `. 3. **Match the site.** Run from the directory holding `.edgeone/anonymous.json` so the site is reused, or ensure your credentials match the deploy's site. -4. **Run the claim:** +4. **Run the claim** — you execute this, never hand it to the user: ```bash edgeone makers claim --sid --json # or, with the state file present: edgeone makers claim --json ``` -5. **On success** the CLI prints the project name, ID, and URL, then deletes `.edgeone/anonymous.json`. The project is now permanent and managed with the normal `edgeone makers deploy` flow. +5. **On success** the CLI prints the project name, ID, and URL, then deletes `.edgeone/anonymous.json`. The project is now permanent and managed with the normal `edgeone makers deploy` flow. Relay the project name and URL in plain language; do not paste the JSON. --- @@ -244,5 +252,5 @@ edgeone makers claim --json # reads .edgeone/anonymous.json Present all three of these to the user together after an anonymous deploy — the URL alone is not enough, because an unclaimed project expires: 1. the full access URL, -2. how to claim (`claimCommand` and `claimUrl`), +2. the `claimUrl` as a clickable link, plus an offer to run the claim for them (**never** the `claimCommand` itself), 3. the actual `expiresAt` value, and that the project is lost if unclaimed. diff --git a/skills/makers-env-adaption/SKILL.md b/skills/makers-env-adaption/SKILL.md index 4c6fcc3..53a9a79 100644 --- a/skills/makers-env-adaption/SKILL.md +++ b/skills/makers-env-adaption/SKILL.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # Runtime Environment Adaptation Guide @@ -267,7 +267,22 @@ If the project named by `--name` does not exist remotely, the `link` command cre | Framework/package | Minimum version | Reason | |---------|---------|------| | EdgeOne CLI | >= 1.6.7 | Non-interactive fixes, whoami fail-fast, --json support | +| EdgeOne CLI (anonymous deploy / `claim` only) | >= 1.6.21 | `--anonymous` and `claim` do not exist below this | | Next.js | 16.x | The framework adapter tracks new versions | | @edgeone/pages-blob | >= 0.0.14 | Older versions have known bugs | Use `create-next-app@latest` rather than manually pinning an older version. + +--- + +### 13. Never hand the user a command to run + +The user has **no terminal** in the WorkBuddy sandbox. Any command you print as an instruction is dead text — they cannot execute it, and a non-technical user cannot read it either. + +| Situation | Do this | Not this | +|---|---|---| +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | +| Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | + +You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. From 0fc24a07cfd9bddacec71d016816d06c5e2d942c Mon Sep 17 00:00:00 2001 From: jesperxu Date: Tue, 11 Aug 2026 19:50:40 +0800 Subject: [PATCH 16/34] docs(makers-deploy): tell users to claim within 60 minutes Reverses the earlier decision to surface the raw expiresAt timestamp. 60 minutes is the product's stated claim window and the conservative instruction -- claiming early is never wrong, and it is what a non-technical user can act on. expiresAt reflects only the token's lifetime (~12h observed), which is not the claim window: the unclaimed link is separately bounded by visitor-count and IP limits. Quoting the timestamp would over-promise, so expiresAt is now diagnostics-only and never user-facing. Updated rule 10, the Step 2 prompt, Step 4 presentation, the decision table row, and the reference's expiry section. Versions: makers-deploy 2.5.0, _meta 1.3.0. --- _meta.json | 2 +- codex/makers-deploy.md | 16 ++++++-------- cursor/rules/makers-deploy.mdc | 16 ++++++-------- skills/makers-deploy/SKILL.md | 16 ++++++-------- .../references/anonymous-deploy.md | 22 ++++++++++++------- 5 files changed, 36 insertions(+), 36 deletions(-) diff --git a/_meta.json b/_meta.json index aeed6c5..113c9ab 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.2.0", + "version": "1.3.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 4cc17c0..18d7fcf 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.4.0" + version: "2.5.0" --- # EdgeOne Makers Deployment Skill @@ -56,7 +56,7 @@ Deploy any project to **EdgeOne Makers**. **Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -107,7 +107,7 @@ cat edgeone.json 2>/dev/null | `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | | `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | -| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim link and the 60-minute claim window in the result | | `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -338,12 +338,10 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. > - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. -⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. - -Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. ### Step 3: Deploy @@ -364,7 +362,7 @@ Your reply must contain all three of the following. The URL alone is not enough 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). 2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. +3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. Example shape: @@ -372,7 +370,7 @@ Example shape: > > --- > -> ⏳ **Claim before ``** — otherwise this project is removed. +> ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in and it's permanently yours. > diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 4cc17c0..18d7fcf 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.4.0" + version: "2.5.0" --- # EdgeOne Makers Deployment Skill @@ -56,7 +56,7 @@ Deploy any project to **EdgeOne Makers**. **Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -107,7 +107,7 @@ cat edgeone.json 2>/dev/null | `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | | `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | -| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim link and the 60-minute claim window in the result | | `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -338,12 +338,10 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. > - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. -⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. - -Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. ### Step 3: Deploy @@ -364,7 +362,7 @@ Your reply must contain all three of the following. The URL alone is not enough 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). 2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. +3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. Example shape: @@ -372,7 +370,7 @@ Example shape: > > --- > -> ⏳ **Claim before ``** — otherwise this project is removed. +> ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in and it's permanently yours. > diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 4cc17c0..18d7fcf 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.4.0" + version: "2.5.0" --- # EdgeOne Makers Deployment Skill @@ -56,7 +56,7 @@ Deploy any project to **EdgeOne Makers**. **Rules 9-11 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Never state a fixed expiry for anonymous deployments** — do not say "60 minutes" or any other duration. Read the actual `expiresAt` value from the deploy output and show that; if the field is absent, say the deadline is unknown and advise claiming promptly. Measured token lifetimes do not match the documented 60 minutes, so a hardcoded number misinforms the user. +10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. --- @@ -107,7 +107,7 @@ cat edgeone.json 2>/dev/null | `≥ 1.6.0` ✓ | Logged in (or token present) | → Go to **Deploy** | | `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | -| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim info and `expiresAt` in the result | +| `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim link and the 60-minute claim window in the result | | `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | --- @@ -338,12 +338,10 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project before it expires, or it is removed; the exact deadline is shown once the deploy finishes. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. > - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. -⛔ Do not state a specific duration here. See critical rule 10 — the real deadline comes from `expiresAt` in the deploy output. - -Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim info and deadline unmissable in your result — the user had no chance to be warned in advance. +Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. ### Step 3: Deploy @@ -364,7 +362,7 @@ Your reply must contain all three of the following. The URL alone is not enough 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). 2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **The actual `expiresAt` value**, plus a clear statement that the project is removed if not claimed. If `expiresAt` is absent from the output, say the deadline is unknown and advise claiming promptly — never invent a duration. +3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. Example shape: @@ -372,7 +370,7 @@ Example shape: > > --- > -> ⏳ **Claim before ``** — otherwise this project is removed. +> ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in and it's permanently yours. > diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 5fcde58..29b8d7c 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -76,7 +76,7 @@ Do not pass these — they have no effect and will mislead the user: | `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | | `claimUrl` | Web claim URL, on the console domain matching `site`. **This is what you show the user** — a clickable link. | | `claimCommand` | Ready-to-run CLI claim command. **For you to execute, never to display** — see the note below. | -| `expiresAt` | **Actual** claim deadline, ISO 8601. Always show this value; never substitute a hardcoded duration. Omitted when the backend returns no usable expiry timestamp — in that case say the deadline is unknown and advise claiming promptly, and still never invent a duration. | +| `expiresAt` | Token expiry as an ISO 8601 timestamp, when the backend returns one. **Do not show this to the user** — tell them to claim within 60 minutes (see below). Useful to you for diagnostics. May be absent. | | `site` | `china` or `global` — the API site this project lives on. | ### Failure @@ -91,17 +91,23 @@ Do not pass these — they have no effect and will mislead the user: --- -## Three different expiry windows — do not conflate them +## What to tell the user about the deadline + +**Always say "claim within 60 minutes".** That is the product's stated claim window, and it is the conservative instruction — claiming early is never wrong. + +Do **not** show the raw `expiresAt` timestamp, and do not derive a different duration from it. + +Why the rule is worded this way: `expiresAt` reflects only the anonymous **token's** lifetime, which in a recorded test-environment response was ~12 hours — longer than 60 minutes. But token lifetime is not the same as the claim window. The unclaimed link is also bounded by visitor-count and IP restrictions that can cut access short, and the product spec's window is 60 minutes. Quoting a 12-hour timestamp would therefore over-promise. Quoting 60 minutes is safe in both directions. + +Three distinct windows exist — do not conflate them: | Window | Where it comes from | What it governs | |--------|--------------------|-----------------| -| **Anonymous token validity** | `expiresAt` in `--json` output | The claim deadline. This is the only one users care about. | +| Claim window | Product spec: **60 minutes** | What you tell the user. | +| Anonymous token validity | `expiresAt` in `--json` output | The token itself. Diagnostics only; not user-facing. | | COS credential validity | `cosExpiredTime` / `cosExpiration` in the state file | A single upload operation. Irrelevant once deploy succeeds. | -| Product target spec | TAPD requirement (unclaimed 60 min → 24 h after claim, 3 renewals) | Not implemented in the current backend. Do not quote it to users. | - -⛔ **Never hardcode a duration.** Both the product plan and the CLI implementation doc state "60 minutes", but measured responses contradict this: in the recorded test-environment response the anonymous token lasted ~12 hours and the COS credential 30 minutes. Read `expiresAt` and show that. -When you have not yet run the deploy (for example while asking the user whether to go anonymous), use wording with no number: "you'll need to log in and claim it before it expires; the exact deadline is shown once the deploy finishes". +> The TAPD requirement describes a future target (unclaimed 60 min → 24 h after claim, renewable 3×). The post-claim renewal part is not implemented; do not describe it to users. --- @@ -253,4 +259,4 @@ Present all three of these to the user together after an anonymous deploy — th 1. the full access URL, 2. the `claimUrl` as a clickable link, plus an offer to run the claim for them (**never** the `claimCommand` itself), -3. the actual `expiresAt` value, and that the project is lost if unclaimed. +3. "claim within 60 minutes", and that the project is lost if unclaimed (not the raw `expiresAt` value). From e4494c528bed47b9051417a3eba585a9aabdfb6a Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 12 Aug 2026 17:41:06 +0800 Subject: [PATCH 17/34] docs(makers-deploy): stop over-promising what claiming gives the user From a WorkBuddy test run: the agent told the user that once they sign in the project is 'permanently theirs, no time limit, no access restrictions'. That came from our own Step 2 wording, and it is false -- a claimed project's preset URL is still preview-grade, and mainland-China access can be restricted pending ICP filing. This skill already says so in the normal-deploy path. New critical rule 12: say only that signing in keeps the project. Never claim permanence or unrestricted access, and do not volunteer custom domains / ICP filing / DNS while the user is only deciding whether to claim -- that front-loads complexity on someone who just wanted a live URL. The claim page owns the follow-up flow. Also clarifies --site resolution, which was written in the passive voice and could read as if the agent should probe isCN and pass --site itself. resolveSite() runs inside the CLI (deploy.ts:99); an agent probing on its own wastes a request and, in a sandbox where its egress IP differs from the CLI's, could force the wrong site. Versions: makers-deploy 2.6.0, _meta 1.4.0. --- _meta.json | 2 +- codex/makers-deploy.md | 17 +++++++---- cursor/rules/makers-deploy.mdc | 17 +++++++---- skills/makers-deploy/SKILL.md | 17 +++++++---- .../references/anonymous-deploy.md | 29 +++++++++++++++---- 5 files changed, 57 insertions(+), 25 deletions(-) diff --git a/_meta.json b/_meta.json index 113c9ab..ad37877 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.3.0", + "version": "1.4.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 18d7fcf..8b79a21 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.5.0" + version: "2.6.0" --- # EdgeOne Makers Deployment Skill @@ -53,11 +53,12 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-11 apply to the anonymous deploy / claim flow only:** +**Rules 9-12 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -339,7 +340,9 @@ In an interactive environment, present the choice (use the IDE's selection contr > You're not logged in to EdgeOne Makers. Two options: > - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. +> - **Log in now** — the project is saved to your account right away, with no claim deadline. + +⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. @@ -350,7 +353,7 @@ export PAGES_SOURCE=skills edgeone makers deploy --anonymous --json ``` -Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. +Add `--site china` or `--site global` only when the site must be pinned (the user told you which, or CI needs determinism). Otherwise omit it — **the CLI detects the site itself** from its own egress IP. Do not probe for the site yourself and do not synthesise `--site` from your own check. Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. @@ -372,10 +375,12 @@ Example shape: > > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > -> 👉 [Claim this project]() — sign in and it's permanently yours. +> 👉 [Claim this project]() — sign in to keep it. > > Or just tell me "claim it" and I'll do it for you. +Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. + ### Claiming a project **You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. @@ -392,7 +397,7 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 18d7fcf..8b79a21 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.5.0" + version: "2.6.0" --- # EdgeOne Makers Deployment Skill @@ -53,11 +53,12 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-11 apply to the anonymous deploy / claim flow only:** +**Rules 9-12 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -339,7 +340,9 @@ In an interactive environment, present the choice (use the IDE's selection contr > You're not logged in to EdgeOne Makers. Two options: > - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. +> - **Log in now** — the project is saved to your account right away, with no claim deadline. + +⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. @@ -350,7 +353,7 @@ export PAGES_SOURCE=skills edgeone makers deploy --anonymous --json ``` -Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. +Add `--site china` or `--site global` only when the site must be pinned (the user told you which, or CI needs determinism). Otherwise omit it — **the CLI detects the site itself** from its own egress IP. Do not probe for the site yourself and do not synthesise `--site` from your own check. Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. @@ -372,10 +375,12 @@ Example shape: > > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > -> 👉 [Claim this project]() — sign in and it's permanently yours. +> 👉 [Claim this project]() — sign in to keep it. > > Or just tell me "claim it" and I'll do it for you. +Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. + ### Claiming a project **You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. @@ -392,7 +397,7 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 18d7fcf..8b79a21 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.5.0" + version: "2.6.0" --- # EdgeOne Makers Deployment Skill @@ -53,11 +53,12 @@ Deploy any project to **EdgeOne Makers**. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -**Rules 9-11 apply to the anonymous deploy / claim flow only:** +**Rules 9-12 apply to the anonymous deploy / claim flow only:** 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. 11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -339,7 +340,9 @@ In an interactive environment, present the choice (use the IDE's selection contr > You're not logged in to EdgeOne Makers. Two options: > - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved permanently to your account with no time limit or access restrictions. +> - **Log in now** — the project is saved to your account right away, with no claim deadline. + +⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. Only skip this question when the environment genuinely cannot ask (CI, headless, no TTY). In that case deploy anonymously and make the claim link and the 60-minute window unmissable in your result — the user had no chance to be warned in advance. @@ -350,7 +353,7 @@ export PAGES_SOURCE=skills edgeone makers deploy --anonymous --json ``` -Add `--site china` or `--site global` when you need a specific site; otherwise it is auto-detected from the egress IP. +Add `--site china` or `--site global` only when the site must be pinned (the user told you which, or CI needs determinism). Otherwise omit it — **the CLI detects the site itself** from its own egress IP. Do not probe for the site yourself and do not synthesise `--site` from your own check. Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. @@ -372,10 +375,12 @@ Example shape: > > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > -> 👉 [Claim this project]() — sign in and it's permanently yours. +> 👉 [Claim this project]() — sign in to keep it. > > Or just tell me "claim it" and I'll do it for you. +Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. + ### Claiming a project **You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. @@ -392,7 +397,7 @@ edgeone makers claim --sid --json Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 29b8d7c..494a4e2 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -21,7 +21,7 @@ edgeone makers claim [--sid ] [-t ] [--json] | Parameter | Type | Notes | |-----------|------|-------| | `--anonymous` | boolean | Enables login-free deploy. **Ignored when already logged in** — the CLI prints a notice and runs the normal deploy flow. **No `-a` short option exists** (`-a` is already taken by `--area`). | -| `--site` | `china` \| `global` | Which API site to use. Auto-detected by egress IP when omitted. | +| `--site` | `china` \| `global` | Which API site to use. **The CLI auto-detects by egress IP when omitted** — you do not need to probe it yourself. | | `--json` | boolean | Emit a machine-readable result line. | ### Claim parameters @@ -107,7 +107,6 @@ Three distinct windows exist — do not conflate them: | Anonymous token validity | `expiresAt` in `--json` output | The token itself. Diagnostics only; not user-facing. | | COS credential validity | `cosExpiredTime` / `cosExpiration` in the state file | A single upload operation. Irrelevant once deploy succeeds. | -> The TAPD requirement describes a future target (unclaimed 60 min → 24 h after claim, renewable 3×). The post-claim renewal part is not implemented; do not describe it to users. --- @@ -137,13 +136,31 @@ Treat it as a secret: it holds an ephemeral credential, valid until claimed or e --- +## What NOT to promise about claiming + +Claiming moves the project into the user's account. That is all it does. Say that, and stop. + +| ❌ Do not say | Why it is wrong | +|---|---| +| "permanently yours" / "no time limit or access restrictions" | A claimed project's preset URL is still a preview-grade domain. Mainland-China access can be restricted (e.g. 401) depending on ICP filing status and CDN policy — claiming does not change that. | +| "unlimited" / "fully public now" | Overstates it. Stable public access generally needs a custom domain, and in mainland China a filing. | +| Anything about custom domains, ICP filing, DNS, or console navigation | Correct, but wrong moment. The user is deciding whether to claim, or has just claimed. Front-loading these concepts onto someone who wanted a live URL is exactly the confusion the anonymous flow exists to avoid. The claim page owns that flow. | + +Raise domains or filing **only** when the user asks about stable / production / shareable access. The normal-deploy path in [SKILL.md](../SKILL.md) already has the correct ICP wording for that case. + +--- + ## Site resolution (`--site`) +**The CLI resolves the site by itself, inside its own process.** You do not need to detect anything. + | Situation | Behaviour | |-----------|-----------| -| `--site` passed | Used as-is. Prefer this in Agent/CI contexts for determinism. | -| `--site` omitted | Detected via `GET https://api.edgeone.ai/e-func/ip/isCN` (3 s timeout): `isCN: true` → `china`, otherwise `global`. | -| Detection fails | Falls back to `global`. | +| `--site` passed | The CLI uses it as-is and skips detection. Prefer this in Agent/CI contexts for determinism. | +| `--site` omitted | **The CLI itself** issues `GET https://api.edgeone.ai/e-func/ip/isCN` (3 s timeout): `isCN: true` → `china`, otherwise `global`. | +| Detection fails | The CLI falls back to `global`. | + +⛔ **Do not call the `isCN` endpoint yourself** and do not build `--site` from your own probe. The CLI already does this at `deploy.ts` → `resolveSite()`. Probing yourself is a wasted request, and in a sandboxed IDE your Bash egress IP may differ from the CLI's, so you could force the *wrong* site. Pass `--site` only when you have an independent reason to pin it (the user said which site, or CI must be deterministic). `claim` reads `site` from `.edgeone/anonymous.json` and **does not re-detect by IP** — the token and project are bound to one site, and egress IP can change between commands (VPN, different CI runner). @@ -216,7 +233,7 @@ Two independent routes. Pick by who acts: # or, with the state file present: edgeone makers claim --json ``` -5. **On success** the CLI prints the project name, ID, and URL, then deletes `.edgeone/anonymous.json`. The project is now permanent and managed with the normal `edgeone makers deploy` flow. Relay the project name and URL in plain language; do not paste the JSON. +5. **On success** the CLI prints the project name, ID, and URL, then deletes `.edgeone/anonymous.json`. The project now belongs to the account and is managed with the normal `edgeone makers deploy` flow. Relay the project name and URL in plain language; do not paste the JSON, and do not describe what claiming "unlocks" — see the note below. --- From 897315462c3b7652eb0eec7852f251b02ee20343 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 12 Aug 2026 17:47:05 +0800 Subject: [PATCH 18/34] docs: point users at the claim link only, drop the offer to claim for them Two ways to claim meant an extra decision for someone who just wanted a live URL. The claim link is now the whole call to action; running claim on the user's behalf is a fallback for when they explicitly ask. Touches rule 11, the Step 4 example, the claim section framing, the reference's Route A/B split, and the env-adaption table row. Versions: makers-deploy 2.6.1, env-adaption 1.2.1, _meta 1.4.1. --- _meta.json | 2 +- codex/makers-deploy.md | 10 ++++------ codex/makers-env-adaption.md | 4 ++-- cursor/rules/makers-deploy.mdc | 10 ++++------ cursor/rules/makers-env-adaption.mdc | 4 ++-- skills/makers-deploy/SKILL.md | 10 ++++------ skills/makers-deploy/references/anonymous-deploy.md | 8 ++++---- skills/makers-env-adaption/SKILL.md | 4 ++-- 8 files changed, 23 insertions(+), 29 deletions(-) diff --git a/_meta.json b/_meta.json index ad37877..4819817 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.4.0", + "version": "1.4.1", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 8b79a21..8b63bdc 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.0" + version: "2.6.1" --- # EdgeOne Makers Deployment Skill @@ -57,7 +57,7 @@ Deploy any project to **EdgeOne Makers**. 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -376,14 +376,12 @@ Example shape: > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in to keep it. -> -> Or just tell me "claim it" and I'll do it for you. -Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. ### Claiming a project -**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. +**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/codex/makers-env-adaption.md b/codex/makers-env-adaption.md index 53a9a79..0cbeb68 100644 --- a/codex/makers-env-adaption.md +++ b/codex/makers-env-adaption.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.0" + version: "1.2.1" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 8b79a21..8b63bdc 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.0" + version: "2.6.1" --- # EdgeOne Makers Deployment Skill @@ -57,7 +57,7 @@ Deploy any project to **EdgeOne Makers**. 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -376,14 +376,12 @@ Example shape: > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in to keep it. -> -> Or just tell me "claim it" and I'll do it for you. -Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. ### Claiming a project -**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. +**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/cursor/rules/makers-env-adaption.mdc b/cursor/rules/makers-env-adaption.mdc index 53a9a79..0cbeb68 100644 --- a/cursor/rules/makers-env-adaption.mdc +++ b/cursor/rules/makers-env-adaption.mdc @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.0" + version: "1.2.1" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 8b79a21..8b63bdc 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.0" + version: "2.6.1" --- # EdgeOne Makers Deployment Skill @@ -57,7 +57,7 @@ Deploy any project to **EdgeOne Makers**. 9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Never show the user a CLI claim command** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** to click, and offer to run the claim yourself. `claimCommand` is for **you** to execute, not to display. +11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -376,14 +376,12 @@ Example shape: > ⏳ **Claim within 60 minutes** — otherwise this project is removed. > > 👉 [Claim this project]() — sign in to keep it. -> -> Or just tell me "claim it" and I'll do it for you. -Keep it to that. Do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rule 12. +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. ### Claiming a project -**You run this command — never print it for the user.** When the user asks to claim (or clicks through and asks for help), execute it yourself. +**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 494a4e2..08be901 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -87,7 +87,7 @@ Do not pass these — they have no effect and will mislead the user: `suggestion` is only present for the rate-limit case. `errorCode` may be absent for generic failures. -⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and offer to run the claim yourself. `claimCommand` exists for **you** to execute. +⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and stop there; do not also offer to claim on their behalf. `claimCommand` exists for **you** to execute, and only when the user explicitly asks you to. --- @@ -220,9 +220,9 @@ The backend claims **asynchronously** and only migrates projects whose deploymen Two independent routes. Pick by who acts: -**Route A — the user claims in the browser (default, and the only one to advertise).** Give them the `claimUrl` link. They sign in and the project transfers. Nothing to run. +**Route A — the user claims in the browser. This is the flow, and the only one you present.** Give them the `claimUrl` link. They sign in and the project transfers. Nothing to run, and no alternative to offer. -**Route B — you claim on their behalf**, when the user says "claim it" or is already logged in: +**Route B — you claim on their behalf. Fallback only**, when the user explicitly asks you to. Do not advertise it: 1. **Deploy must have succeeded.** Only `Success` deployments are migrated. 2. **Log in.** In an interactive environment the CLI opens a browser when needed; in CI, pass `-t `. @@ -275,5 +275,5 @@ edgeone makers claim --json # reads .edgeone/anonymous.json Present all three of these to the user together after an anonymous deploy — the URL alone is not enough, because an unclaimed project expires: 1. the full access URL, -2. the `claimUrl` as a clickable link, plus an offer to run the claim for them (**never** the `claimCommand` itself), +2. the `claimUrl` as a clickable link — that alone (**never** the `claimCommand`, and no offer to claim for them), 3. "claim within 60 minutes", and that the project is lost if unclaimed (not the raw `expiresAt` value). diff --git a/skills/makers-env-adaption/SKILL.md b/skills/makers-env-adaption/SKILL.md index 53a9a79..0cbeb68 100644 --- a/skills/makers-env-adaption/SKILL.md +++ b/skills/makers-env-adaption/SKILL.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.0" + version: "1.2.1" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link, and offer to claim it yourself | ❌ Printing `edgeone makers claim --sid ` | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | From 11abf6f62a74b90820d025969c629df2a000aaf8 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 12 Aug 2026 18:26:39 +0800 Subject: [PATCH 19/34] docs(makers-deploy): follow the user's language; frame expiry as the link expiring Two fixes from a WorkBuddy test run. 1. The agent emitted the skill's English claim text into a Chinese conversation. Root cause was mine: rule 10 said 'say exactly that' and Step 4 said 'use that wording verbatim', while the skill had no language guidance at all -- so the English examples read as strings to paste. Those examples now state they specify meaning, not wording, and new rule 9 (skill-wide, not anonymous-only) requires every user-facing message to be in the user's language. The same trap applied to the login explanation, site picker and token prompt. Added a Chinese version of the result block so the intent is unambiguous. 2. 'The project will be removed' -> 'the link expires'. What the user loses is a working URL; talk of the project being deleted reads as data loss and is needlessly alarming. Renumbered rules 9-12 to 10-13 and updated all six cross-references. Versions: makers-deploy 2.7.0, _meta 1.5.0. --- _meta.json | 2 +- codex/makers-deploy.md | 45 ++++++++++++------- cursor/rules/makers-deploy.mdc | 45 ++++++++++++------- skills/makers-deploy/SKILL.md | 45 ++++++++++++------- .../references/anonymous-deploy.md | 10 +++-- 5 files changed, 92 insertions(+), 55 deletions(-) diff --git a/_meta.json b/_meta.json index 4819817..8ba6e5b 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.4.1", + "version": "1.5.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 8b63bdc..ef0a323 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.1" + version: "2.7.0" --- # EdgeOne Makers Deployment Skill @@ -52,13 +52,14 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. -**Rules 9-12 apply to the anonymous deploy / claim flow only:** +**Rules 10-13 apply to the anonymous deploy / claim flow only:** -9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. -12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. +10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -336,11 +337,11 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no claim deadline. +> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. @@ -361,23 +362,33 @@ Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous` Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. +3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. -Example shape: +Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): > 🌐 **Live URL**: `` > > --- > -> ⏳ **Claim within 60 minutes** — otherwise this project is removed. +> ⏳ **This link expires in 60 minutes** — claim it to keep it working. > > 👉 [Claim this project]() — sign in to keep it. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. +Same thing for a Chinese-speaking user: + +> 🌐 **访问地址**：`` +> +> --- +> +> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> +> 👉 [认领这个项目]() —— 登录后归入你的账号。 + +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. ### Claiming a project @@ -391,11 +402,11 @@ edgeone makers claim --json edgeone makers claim --sid --json ``` -⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. +⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 8b63bdc..ef0a323 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.1" + version: "2.7.0" --- # EdgeOne Makers Deployment Skill @@ -52,13 +52,14 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. -**Rules 9-12 apply to the anonymous deploy / claim flow only:** +**Rules 10-13 apply to the anonymous deploy / claim flow only:** -9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. -12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. +10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -336,11 +337,11 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no claim deadline. +> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. @@ -361,23 +362,33 @@ Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous` Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. +3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. -Example shape: +Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): > 🌐 **Live URL**: `` > > --- > -> ⏳ **Claim within 60 minutes** — otherwise this project is removed. +> ⏳ **This link expires in 60 minutes** — claim it to keep it working. > > 👉 [Claim this project]() — sign in to keep it. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. +Same thing for a Chinese-speaking user: + +> 🌐 **访问地址**：`` +> +> --- +> +> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> +> 👉 [认领这个项目]() —— 登录后归入你的账号。 + +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. ### Claiming a project @@ -391,11 +402,11 @@ edgeone makers claim --json edgeone makers claim --sid --json ``` -⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. +⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 8b63bdc..ef0a323 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.6.1" + version: "2.7.0" --- # EdgeOne Makers Deployment Skill @@ -52,13 +52,14 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. +9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. -**Rules 9-12 apply to the anonymous deploy / claim flow only:** +**Rules 10-13 apply to the anonymous deploy / claim flow only:** -9. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -10. **Tell the user to claim within 60 minutes** — say exactly that: "claim within 60 minutes". Do not show the raw `expiresAt` timestamp to the user, and do not compute or invent a different duration from it. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so this is the wording to use even though the token's observed lifetime can be longer. -11. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. -12. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. +10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -336,11 +337,11 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): > You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately. You'll need to log in and claim the project **within 60 minutes**, or it is removed. Until claimed, the link has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no claim deadline. +> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. +> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. @@ -361,23 +362,33 @@ Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous` Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed project disappears. +Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. 1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 11. -3. **"Claim within 60 minutes"**, plus that the project is removed if not claimed. Use that wording verbatim — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 10. +2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. +3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. -Example shape: +Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): > 🌐 **Live URL**: `` > > --- > -> ⏳ **Claim within 60 minutes** — otherwise this project is removed. +> ⏳ **This link expires in 60 minutes** — claim it to keep it working. > > 👉 [Claim this project]() — sign in to keep it. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 11 and 12. +Same thing for a Chinese-speaking user: + +> 🌐 **访问地址**：`` +> +> --- +> +> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> +> 👉 [认领这个项目]() —— 登录后归入你的账号。 + +Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. ### Claiming a project @@ -391,11 +402,11 @@ edgeone makers claim --json edgeone makers claim --sid --json ``` -⛔ The parameter is `--sid` (see critical rule 9). `-t` on `claim` is the account API token, not the anonymous token. +⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 12). +Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 08be901..e3c84a7 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -93,11 +93,13 @@ Do not pass these — they have no effect and will mislead the user: ## What to tell the user about the deadline -**Always say "claim within 60 minutes".** That is the product's stated claim window, and it is the conservative instruction — claiming early is never wrong. +**Tell them the link expires in 60 minutes unless they claim it.** Frame it as the *link expiring*, not as the project being deleted — from the user's point of view what they lose is a working URL, and "your project will be removed" reads as data loss, which is needlessly alarming. + +Convey that meaning in the user's own language. The English wording here specifies intent, not a string to copy. Do **not** show the raw `expiresAt` timestamp, and do not derive a different duration from it. -Why the rule is worded this way: `expiresAt` reflects only the anonymous **token's** lifetime, which in a recorded test-environment response was ~12 hours — longer than 60 minutes. But token lifetime is not the same as the claim window. The unclaimed link is also bounded by visitor-count and IP restrictions that can cut access short, and the product spec's window is 60 minutes. Quoting a 12-hour timestamp would therefore over-promise. Quoting 60 minutes is safe in both directions. +Why 60 minutes and not the timestamp: `expiresAt` reflects only the anonymous **token's** lifetime, which in a recorded test-environment response was ~12 hours — longer than 60 minutes. But token lifetime is not the same as the usable window. The unclaimed link is also bounded by visitor-count and IP restrictions that can cut access short, and the product spec's window is 60 minutes. Quoting a 12-hour timestamp would therefore over-promise. Quoting 60 minutes is safe in both directions. Three distinct windows exist — do not conflate them: @@ -276,4 +278,6 @@ Present all three of these to the user together after an anonymous deploy — th 1. the full access URL, 2. the `claimUrl` as a clickable link — that alone (**never** the `claimCommand`, and no offer to claim for them), -3. "claim within 60 minutes", and that the project is lost if unclaimed (not the raw `expiresAt` value). +3. that the link expires in 60 minutes unless claimed (not the raw `expiresAt` value). + +Write all three in the user's language — the English phrasing in this file specifies meaning, not wording. From c96968f39921528f605618679734e2e3adfd21e2 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 12 Aug 2026 19:56:34 +0800 Subject: [PATCH 20/34] docs(makers-deploy): make the anonymous result a fixed template, not an example The agent kept rewriting the closing line ('sign in to keep it' became 'please claim it within 60 minutes', etc). That was invited by the framing: the block was labelled 'Example shape', which reads as a starting point to improve on. Step 4 is now an explicit fixed template in both English and Chinese, with the substitution boundary spelled out: only and may change. Rewording, reordering, merging lines, and appending anything (project ID, console URL, expiresAt, next steps) are all listed as prohibited. Rule 11 now points at the template as the single source, and rule 9's 'use the user's language' carves out an exception so translating the template is required but rewriting it is not. The reference no longer describes three ingredients to assemble, which would have drifted from the template. Versions: makers-deploy 2.8.0, _meta 1.6.0. --- _meta.json | 2 +- codex/makers-deploy.md | 30 +++++++++---------- cursor/rules/makers-deploy.mdc | 30 +++++++++---------- skills/makers-deploy/SKILL.md | 30 +++++++++---------- .../references/anonymous-deploy.md | 8 ++--- 5 files changed, 45 insertions(+), 55 deletions(-) diff --git a/_meta.json b/_meta.json index 8ba6e5b..353f4f0 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.5.0", + "version": "1.6.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index ef0a323..dfd1441 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.7.0" + version: "2.8.0" --- # EdgeOne Makers Deployment Skill @@ -52,12 +52,12 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. 12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. @@ -358,37 +358,35 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — all three parts are mandatory +### Step 4: Present the result — use the fixed template below Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. -1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. -3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. - -Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): +**English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` > > --- > -> ⏳ **This link expires in 60 minutes** — claim it to keep it working. +> ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — sign in to keep it. +> 👉 [Claim this project]() — please claim it within 60 minutes. -Same thing for a Chinese-speaking user: +**Chinese-speaking user — emit exactly this:** > 🌐 **访问地址**：`` > > --- > -> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 登录后归入你的账号。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 + +For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. +Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. ### Claiming a project diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index ef0a323..dfd1441 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.7.0" + version: "2.8.0" --- # EdgeOne Makers Deployment Skill @@ -52,12 +52,12 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. 12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. @@ -358,37 +358,35 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — all three parts are mandatory +### Step 4: Present the result — use the fixed template below Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. -1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. -3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. - -Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): +**English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` > > --- > -> ⏳ **This link expires in 60 minutes** — claim it to keep it working. +> ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — sign in to keep it. +> 👉 [Claim this project]() — please claim it within 60 minutes. -Same thing for a Chinese-speaking user: +**Chinese-speaking user — emit exactly this:** > 🌐 **访问地址**：`` > > --- > -> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 登录后归入你的账号。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 + +For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. +Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. ### Claiming a project diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index ef0a323..dfd1441 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.7.0" + version: "2.8.0" --- # EdgeOne Makers Deployment Skill @@ -52,12 +52,12 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** example text, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, the claim prompt, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -11. **Tell the user the link expires in 60 minutes unless they claim it** — convey that meaning; do not show the raw `expiresAt` timestamp and do not substitute a different duration. 60 minutes is the product's stated claim window and the conservative instruction: claiming early is always safe, so use it even though the token's observed lifetime can be longer. Frame it as the *link* expiring, not the project being deleted. +11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. 12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. @@ -358,37 +358,35 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — all three parts are mandatory +### Step 4: Present the result — use the fixed template below Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -Your reply must contain all three of the following. The URL alone is not enough — an unclaimed link stops working. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. -1. **The full access URL**, at the very top, complete with any query string (critical rules 2 and 4 apply exactly as for a normal deploy). -2. **The claim link** — `claimUrl`, as a clickable link. ⛔ **Do NOT show `claimCommand` or any `edgeone makers claim ...` command to the user.** See critical rule 12. -3. **That the link expires in 60 minutes unless claimed.** Convey that meaning — do not show the raw `expiresAt` timestamp and do not substitute a different duration. See critical rule 11. - -Example shape — this is the **meaning and layout** to reproduce, **not** text to copy. Write it in the user's language (critical rule 9): +**English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` > > --- > -> ⏳ **This link expires in 60 minutes** — claim it to keep it working. +> ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — sign in to keep it. +> 👉 [Claim this project]() — please claim it within 60 minutes. -Same thing for a Chinese-speaking user: +**Chinese-speaking user — emit exactly this:** > 🌐 **访问地址**：`` > > --- > -> ⏳ **该链接 60 分钟后失效** —— 认领后即可长期使用。 +> ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 登录后归入你的账号。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 + +For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. -Keep it to that. The claim link is the whole call to action: do not also offer to claim on their behalf, do not append what claiming "unlocks", and do not introduce custom domains, ICP filing, or DNS here — the claim page guides them from there. See critical rules 12 and 13. +Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. ### Claiming a project diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index e3c84a7..9fbd158 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -274,10 +274,6 @@ edgeone login --site global edgeone makers claim --json # reads .edgeone/anonymous.json ``` -Present all three of these to the user together after an anonymous deploy — the URL alone is not enough, because an unclaimed project expires: +After an anonymous deploy, present the result using the **fixed template in [SKILL.md](../SKILL.md) Step 4** — do not assemble your own message. Substitute only the URL and the claim link; translate it into the user's language; add nothing. -1. the full access URL, -2. the `claimUrl` as a clickable link — that alone (**never** the `claimCommand`, and no offer to claim for them), -3. that the link expires in 60 minutes unless claimed (not the raw `expiresAt` value). - -Write all three in the user's language — the English phrasing in this file specifies meaning, not wording. +It carries exactly three things, and that is deliberate: the access URL, the `claimUrl` link (**never** the `claimCommand`, and no offer to claim for them), and that the link expires in 60 minutes (**never** the raw `expiresAt` value). From 6bcef4daea6c97131531df41e29477110b713fbf Mon Sep 17 00:00:00 2001 From: jesperxu Date: Thu, 13 Aug 2026 16:29:15 +0800 Subject: [PATCH 21/34] =?UTF-8?q?fix:=E6=96=87=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/makers-deploy/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index dfd1441..2fc832c 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -376,6 +376,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F **Chinese-speaking user — emit exactly this:** +> 🎉 匿名部署成功 > 🌐 **访问地址**：`` > > --- From dabdf894a80af4916b8da0b3dfd467b27cf831c9 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Thu, 13 Aug 2026 19:31:39 +0800 Subject: [PATCH 22/34] docs: open the claim page when asked; keep the result out of process messages 1. 'Help me claim' now means opening the claim link in the user's browser (open / xdg-open / start), not running the CLI claim. Claiming IS signing in on the claim page, so opening that page is doing it for them. The CLI claim survives only as a fallback for headless/CI environments where no browser can be opened. Rule 12, the Claiming section, the reference's claim flow, and the env-adaption table all updated. 2. Once in a WorkBuddy test the deploy result (URL + claim link) was folded into a collapsible process message and the user never saw it. Step 4 now requires sending the template as its own message after the deploy command has fully returned, never in the same message as the command. env-adaption gained section 13.1 on the same hazard. Versions: makers-deploy 2.9.0, env-adaption 1.3.0, _meta 1.7.0. --- _meta.json | 2 +- codex/makers-deploy.md | 22 ++++++++++++++++--- codex/makers-env-adaption.md | 13 +++++++++-- cursor/rules/makers-deploy.mdc | 22 ++++++++++++++++--- cursor/rules/makers-env-adaption.mdc | 13 +++++++++-- skills/makers-deploy/SKILL.md | 21 +++++++++++++++--- .../references/anonymous-deploy.md | 16 +++++++++----- skills/makers-env-adaption/SKILL.md | 13 +++++++++-- 8 files changed, 101 insertions(+), 21 deletions(-) diff --git a/_meta.json b/_meta.json index 353f4f0..b26560e 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.6.0", + "version": "1.7.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index dfd1441..891ab7c 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.8.0" + version: "2.9.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -364,6 +364,8 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F ⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -376,6 +378,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F **Chinese-speaking user — emit exactly this:** +> 🎉 匿名部署成功 > 🌐 **访问地址**：`` > > --- @@ -390,7 +393,20 @@ Afterwards, stop. Anything you feel like adding here — what claiming unlocks, ### Claiming a project -**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. +**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. + +```bash +# macOS (local, or WorkBuddy host) +open "" +# Linux +xdg-open "" +# Windows +start "" "" +``` + +Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. + +⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/codex/makers-env-adaption.md b/codex/makers-env-adaption.md index 0cbeb68..b2b0550 100644 --- a/codex/makers-env-adaption.md +++ b/codex/makers-env-adaption.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.1" + version: "1.3.0" --- # Runtime Environment Adaptation Guide @@ -281,8 +281,17 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. + +### 13.1 Never let the key result get folded into a process message + +WorkBuddy can collapse content emitted in the same message as a running or just-finished Bash command into a collapsible process entry. When the user asks to deploy, the deploy URL and claim link must never land there — if they do, the user sees nothing. + +| Situation | Do this | Not this | +|---|---|---| +| A deploy just finished | Wait for the Bash call to fully return, then send the result (URL + claim link) **as its own message** | ❌ Emitting the result in the same message where the deploy ran, or attaching it to the command's stdout | +| Running a long command | Report progress only in later messages, after the tool call returns | ❌ Writing "here is your URL" inside the same turn as the command output | diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index dfd1441..891ab7c 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.8.0" + version: "2.9.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -364,6 +364,8 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F ⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -376,6 +378,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F **Chinese-speaking user — emit exactly this:** +> 🎉 匿名部署成功 > 🌐 **访问地址**：`` > > --- @@ -390,7 +393,20 @@ Afterwards, stop. Anything you feel like adding here — what claiming unlocks, ### Claiming a project -**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. +**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. + +```bash +# macOS (local, or WorkBuddy host) +open "" +# Linux +xdg-open "" +# Windows +start "" "" +``` + +Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. + +⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/cursor/rules/makers-env-adaption.mdc b/cursor/rules/makers-env-adaption.mdc index 0cbeb68..b2b0550 100644 --- a/cursor/rules/makers-env-adaption.mdc +++ b/cursor/rules/makers-env-adaption.mdc @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.1" + version: "1.3.0" --- # Runtime Environment Adaptation Guide @@ -281,8 +281,17 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. + +### 13.1 Never let the key result get folded into a process message + +WorkBuddy can collapse content emitted in the same message as a running or just-finished Bash command into a collapsible process entry. When the user asks to deploy, the deploy URL and claim link must never land there — if they do, the user sees nothing. + +| Situation | Do this | Not this | +|---|---|---| +| A deploy just finished | Wait for the Bash call to fully return, then send the result (URL + claim link) **as its own message** | ❌ Emitting the result in the same message where the deploy ran, or attaching it to the command's stdout | +| Running a long command | Report progress only in later messages, after the tool call returns | ❌ Writing "here is your URL" inside the same turn as the command output | diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 2fc832c..891ab7c 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.8.0" + version: "2.9.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **Point the user at the claim link — nothing else** — do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Give them the **`claimUrl` link** and stop there: do not offer to claim on their behalf either — signing in on the claim page *is* the flow, and an extra option only adds a decision. Run `claim` yourself only if the user explicitly asks you to. +12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -364,6 +364,8 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F ⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -391,7 +393,20 @@ Afterwards, stop. Anything you feel like adding here — what claiming unlocks, ### Claiming a project -**The default is that the user claims it themselves via `claimUrl`** — that is what you present, and you do not offer an alternative. This command is a fallback for when the user explicitly asks you to claim it for them. Never print it for the user. +**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. + +```bash +# macOS (local, or WorkBuddy host) +open "" +# Linux +xdg-open "" +# Windows +start "" "" +``` + +Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. + +⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 9fbd158..60f6a46 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -87,7 +87,7 @@ Do not pass these — they have no effect and will mislead the user: `suggestion` is only present for the rate-limit case. `errorCode` may be absent for generic failures. -⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and stop there; do not also offer to claim on their behalf. `claimCommand` exists for **you** to execute, and only when the user explicitly asks you to. +⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and stop there. When the user asks you to claim it for them, **open the claim link in their browser** — that is what claiming means. `claimCommand` is a fallback for headless/CI environments with no browser, executed by you, never displayed. --- @@ -220,11 +220,17 @@ The backend claims **asynchronously** and only migrates projects whose deploymen ## Claim flow -Two independent routes. Pick by who acts: +**Route A — open the claim page in the user's browser. This is the flow, and the only one you present.** Present the `claimUrl` link in the result. When the user asks you to claim it for them, open it for them: -**Route A — the user claims in the browser. This is the flow, and the only one you present.** Give them the `claimUrl` link. They sign in and the project transfers. Nothing to run, and no alternative to offer. +```bash +open "" # macOS (local, or WorkBuddy host) +xdg-open "" # Linux +start "" "" # Windows +``` + +Then confirm plainly: the claim page is open, please sign in there. Do not re-paste the URL or add guidance. Nothing else to run. -**Route B — you claim on their behalf. Fallback only**, when the user explicitly asks you to. Do not advertise it: +**Route B — CLI claim. Fallback only**, for headless/CI environments where no browser can be opened. Never advertise it, never show the command to the user: 1. **Deploy must have succeeded.** Only `Success` deployments are migrated. 2. **Log in.** In an interactive environment the CLI opens a browser when needed; in CI, pass `-t `. @@ -276,4 +282,4 @@ edgeone makers claim --json # reads .edgeone/anonymous.json After an anonymous deploy, present the result using the **fixed template in [SKILL.md](../SKILL.md) Step 4** — do not assemble your own message. Substitute only the URL and the claim link; translate it into the user's language; add nothing. -It carries exactly three things, and that is deliberate: the access URL, the `claimUrl` link (**never** the `claimCommand`, and no offer to claim for them), and that the link expires in 60 minutes (**never** the raw `expiresAt` value). +It carries exactly three things, and that is deliberate: the access URL, the `claimUrl` link (**never** the `claimCommand`), and that the link expires in 60 minutes (**never** the raw `expiresAt` value). diff --git a/skills/makers-env-adaption/SKILL.md b/skills/makers-env-adaption/SKILL.md index 0cbeb68..b2b0550 100644 --- a/skills/makers-env-adaption/SKILL.md +++ b/skills/makers-env-adaption/SKILL.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.2.1" + version: "1.3.0" --- # Runtime Environment Adaptation Guide @@ -281,8 +281,17 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link and stop there | ❌ Printing `edgeone makers claim --sid `, or offering to claim it for them | +| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. + +### 13.1 Never let the key result get folded into a process message + +WorkBuddy can collapse content emitted in the same message as a running or just-finished Bash command into a collapsible process entry. When the user asks to deploy, the deploy URL and claim link must never land there — if they do, the user sees nothing. + +| Situation | Do this | Not this | +|---|---|---| +| A deploy just finished | Wait for the Bash call to fully return, then send the result (URL + claim link) **as its own message** | ❌ Emitting the result in the same message where the deploy ran, or attaching it to the command's stdout | +| Running a long command | Report progress only in later messages, after the tool call returns | ❌ Writing "here is your URL" inside the same turn as the command output | From 505d40eda61d9079246266e6e834808e7b524b7c Mon Sep 17 00:00:00 2001 From: jesperxu Date: Tue, 18 Aug 2026 17:51:57 +0800 Subject: [PATCH 23/34] docs(makers-deploy): chain the claim flow through edgeone login --claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLI feature/anonymous 新增 login --claim 后，匿名部署的认领链路从 「给裸 claimUrl，CLI 永远不知情」改为「后台起 login --claim 监听， 把登录→认领→回传的链接给用户」： - Step 4：部署后立即后台运行 login --claim --local --json，模板的 认领链接改取它的 claimLoginUrl（占位符同步改名，区别于部署 JSON 里的裸 claimUrl） - 新增 After the user claims：监听退出即完成 登录态落盘+自动 link+ 清理 anonymous.json，后续 deploy 落在同一正式项目；超时则重跑拿新链接 - rule 12 重写：认领链接必须来自 login --claim，裸 claimUrl 禁用 （否则认领后 CLI 不知情，二次部署又开新匿名项目） - reference：Claim flow 改为 Route A=login --claim / Route B=makers claim （仅 headless 兜底）；工作流示例同步 - makers-cli / command-reference 增加 login --claim 行； env-adaption 认领行同步；makers-cli 注修正「60 分钟」口径 Versions: makers-deploy 2.10.0, makers-cli 1.2.0, env-adaption 1.4.0, _meta 1.8.0 --- _meta.json | 2 +- codex/makers-cli.md | 5 +- codex/makers-deploy.md | 55 ++++++++----------- codex/makers-env-adaption.md | 4 +- cursor/rules/makers-cli.mdc | 5 +- cursor/rules/makers-deploy.mdc | 55 ++++++++----------- cursor/rules/makers-env-adaption.mdc | 4 +- skills/makers-cli/SKILL.md | 5 +- skills/makers-deploy/SKILL.md | 55 ++++++++----------- .../references/anonymous-deploy.md | 32 +++++++---- .../references/command-reference.md | 1 + skills/makers-env-adaption/SKILL.md | 4 +- 12 files changed, 106 insertions(+), 121 deletions(-) diff --git a/_meta.json b/_meta.json index b26560e..56ac432 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.7.0", + "version": "1.8.0", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-cli.md b/codex/makers-cli.md index 3607acb..b0c9925 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # EdgeOne Makers CLI Reference @@ -39,9 +39,10 @@ Verify: `edgeone -v` | `edgeone login` | Login (browser-based) | | `edgeone login --site china` | Login to China site | | `edgeone login --site global` | Login to Global site | +| `edgeone login --claim --local --json` | Background listener: prints the login+claim link for an anonymous deploy, then auto-links the claimed project | | `edgeone whoami` | Check current login status | -> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Tell the user the link expires in 60 minutes; never show the raw `expiresAt`. The claim link you present comes from `edgeone login --claim` (`claimLoginUrl`), not the bare `claimUrl` in the deploy JSON. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). ## Environment Variable diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 891ab7c..eb27de0 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.9.0" + version: "2.10.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. +12. **The claim link you present must come from `edgeone login --claim`, never the bare `claimUrl`** — right after an anonymous deploy, run `edgeone login --claim --local --json` in the background and put its `claimLoginUrl` in the template. Only that link carries the login → claim → callback chain that lets the CLI learn the login state and auto-link the project; the bare `claimUrl` from deploy output claims without telling the CLI, so the user's next deploy would create a second anonymous project. Never print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim — in sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it. `makers claim` is only a fallback for headless/CI environments, run by you, never displayed. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -358,14 +358,22 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — use the fixed template below +### Step 4: Start the claim listener, then present the result -Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. +Parse the **last line** of the deploy stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +**Immediately start the claim listener in the background** — it must be listening before the user clicks the claim link, or the login state never reaches the CLI and the next deploy would create a second anonymous project: + +```bash +edgeone login --claim --local --json +``` + +Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl":...}` JSON line right away, then keeps listening (up to 60 minutes). Grab `claimLoginUrl` from that line. ⛔ **This URL — not the `claimUrl` field from the deploy JSON — is the claim link you show the user.** Only this link chains login → claim page → callback to the CLI. The bare `claimUrl` from deploy output would claim the project without telling the CLI, and the user's next deploy would go to a new anonymous project instead of the claimed one. ⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` (from the deploy JSON) and `` (from the `login --claim` output). Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -374,7 +382,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — please claim it within 60 minutes. +> 👉 [Claim this project]() — please claim it within 60 minutes. **Chinese-speaking user — emit exactly this:** @@ -385,42 +393,25 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. -### Claiming a project +### After the user claims -**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. +The background `login --claim` process exits on its own when the console relays the result. When it exits 0 with `{"status":"success",...,"linked":true}`: -```bash -# macOS (local, or WorkBuddy host) -open "" -# Linux -xdg-open "" -# Windows -start "" "" -``` - -Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. - -⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. - -Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: - -```bash -edgeone makers claim --json -# or pass the token explicitly: -edgeone makers claim --sid --json -``` +- the CLI is logged in (credentials saved, plus `.edgeone/auth.json` from `--local`), +- the project is linked (`.edgeone/project.json`), +- `.edgeone/anonymous.json` is removed. -⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. +Tell the user plainly, in their language: the project is now in their account, and any further deploys will update that same project. Then use the normal deploy flow (`edgeone makers deploy --json`) for all later deploys. -Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +If the process exits non-zero (the user never completed the link within 60 minutes), the anonymous project is still unclaimed: re-run `edgeone login --claim --local --json` for a fresh link and present it again in the same template. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). +If the user asks you to "帮我认领" / "claim it for me": point them to the same link again while the listener is still running; if it already exited, re-run the command for a fresh link. Never print the CLI claim command — `edgeone makers claim --sid` remains only for headless/CI environments with no browser (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/codex/makers-env-adaption.md b/codex/makers-env-adaption.md index b2b0550..32daa61 100644 --- a/codex/makers-env-adaption.md +++ b/codex/makers-env-adaption.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.3.0" + version: "1.4.0" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | +| Anonymous project needs claiming | Run `edgeone login --claim --local --json` in the background and present its `claimLoginUrl` as a clickable link; the listener auto-links the project when the user finishes claiming | ❌ Printing `edgeone makers claim --sid `, or presenting the bare `claimUrl` from the deploy JSON (the CLI never learns the login state) | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | diff --git a/cursor/rules/makers-cli.mdc b/cursor/rules/makers-cli.mdc index 3607acb..b0c9925 100644 --- a/cursor/rules/makers-cli.mdc +++ b/cursor/rules/makers-cli.mdc @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # EdgeOne Makers CLI Reference @@ -39,9 +39,10 @@ Verify: `edgeone -v` | `edgeone login` | Login (browser-based) | | `edgeone login --site china` | Login to China site | | `edgeone login --site global` | Login to Global site | +| `edgeone login --claim --local --json` | Background listener: prints the login+claim link for an anonymous deploy, then auto-links the claimed project | | `edgeone whoami` | Check current login status | -> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Tell the user the link expires in 60 minutes; never show the raw `expiresAt`. The claim link you present comes from `edgeone login --claim` (`claimLoginUrl`), not the bare `claimUrl` in the deploy JSON. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). ## Environment Variable diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 891ab7c..eb27de0 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.9.0" + version: "2.10.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. +12. **The claim link you present must come from `edgeone login --claim`, never the bare `claimUrl`** — right after an anonymous deploy, run `edgeone login --claim --local --json` in the background and put its `claimLoginUrl` in the template. Only that link carries the login → claim → callback chain that lets the CLI learn the login state and auto-link the project; the bare `claimUrl` from deploy output claims without telling the CLI, so the user's next deploy would create a second anonymous project. Never print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim — in sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it. `makers claim` is only a fallback for headless/CI environments, run by you, never displayed. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -358,14 +358,22 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — use the fixed template below +### Step 4: Start the claim listener, then present the result -Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. +Parse the **last line** of the deploy stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +**Immediately start the claim listener in the background** — it must be listening before the user clicks the claim link, or the login state never reaches the CLI and the next deploy would create a second anonymous project: + +```bash +edgeone login --claim --local --json +``` + +Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl":...}` JSON line right away, then keeps listening (up to 60 minutes). Grab `claimLoginUrl` from that line. ⛔ **This URL — not the `claimUrl` field from the deploy JSON — is the claim link you show the user.** Only this link chains login → claim page → callback to the CLI. The bare `claimUrl` from deploy output would claim the project without telling the CLI, and the user's next deploy would go to a new anonymous project instead of the claimed one. ⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` (from the deploy JSON) and `` (from the `login --claim` output). Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -374,7 +382,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — please claim it within 60 minutes. +> 👉 [Claim this project]() — please claim it within 60 minutes. **Chinese-speaking user — emit exactly this:** @@ -385,42 +393,25 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. -### Claiming a project +### After the user claims -**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. +The background `login --claim` process exits on its own when the console relays the result. When it exits 0 with `{"status":"success",...,"linked":true}`: -```bash -# macOS (local, or WorkBuddy host) -open "" -# Linux -xdg-open "" -# Windows -start "" "" -``` - -Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. - -⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. - -Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: - -```bash -edgeone makers claim --json -# or pass the token explicitly: -edgeone makers claim --sid --json -``` +- the CLI is logged in (credentials saved, plus `.edgeone/auth.json` from `--local`), +- the project is linked (`.edgeone/project.json`), +- `.edgeone/anonymous.json` is removed. -⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. +Tell the user plainly, in their language: the project is now in their account, and any further deploys will update that same project. Then use the normal deploy flow (`edgeone makers deploy --json`) for all later deploys. -Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +If the process exits non-zero (the user never completed the link within 60 minutes), the anonymous project is still unclaimed: re-run `edgeone login --claim --local --json` for a fresh link and present it again in the same template. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). +If the user asks you to "帮我认领" / "claim it for me": point them to the same link again while the listener is still running; if it already exited, re-run the command for a fresh link. Never print the CLI claim command — `edgeone makers claim --sid` remains only for headless/CI environments with no browser (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/cursor/rules/makers-env-adaption.mdc b/cursor/rules/makers-env-adaption.mdc index b2b0550..32daa61 100644 --- a/cursor/rules/makers-env-adaption.mdc +++ b/cursor/rules/makers-env-adaption.mdc @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.3.0" + version: "1.4.0" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | +| Anonymous project needs claiming | Run `edgeone login --claim --local --json` in the background and present its `claimLoginUrl` as a clickable link; the listener auto-links the project when the user finishes claiming | ❌ Printing `edgeone makers claim --sid `, or presenting the bare `claimUrl` from the deploy JSON (the CLI never learns the login state) | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | diff --git a/skills/makers-cli/SKILL.md b/skills/makers-cli/SKILL.md index 3607acb..b0c9925 100644 --- a/skills/makers-cli/SKILL.md +++ b/skills/makers-cli/SKILL.md @@ -5,7 +5,7 @@ description: >- Use when running edgeone CLI commands for dev, build, deploy, env management. metadata: author: edgeone - version: "1.1.0" + version: "1.2.0" --- # EdgeOne Makers CLI Reference @@ -39,9 +39,10 @@ Verify: `edgeone -v` | `edgeone login` | Login (browser-based) | | `edgeone login --site china` | Login to China site | | `edgeone login --site global` | Login to Global site | +| `edgeone login --claim --local --json` | Background listener: prints the login+claim link for an anonymous deploy, then auto-links the claimed project | | `edgeone whoami` | Check current login status | -> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Never quote a fixed expiry: read `expiresAt` from `--json` output. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). +> Anonymous deploy and `claim` require CLI `>= 1.6.21` (the general CLI floor is `1.6.0`). The claim parameter is `--sid` (the anonymous token); `-t` is the account API token — they are different credentials. Tell the user the link expires in 60 minutes; never show the raw `expiresAt`. The claim link you present comes from `edgeone login --claim` (`claimLoginUrl`), not the bare `claimUrl` in the deploy JSON. Details: [makers-deploy/references/anonymous-deploy.md](../makers-deploy/references/anonymous-deploy.md). ## Environment Variable diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 891ab7c..eb27de0 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.9.0" + version: "2.10.0" --- # EdgeOne Makers Deployment Skill @@ -58,7 +58,7 @@ Deploy any project to **EdgeOne Makers**. 10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. 11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **When the user asks you to claim it for them, open the `claimUrl` in their browser** — do **not** run the CLI claim command and do not print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim. In sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it, and non-technical users cannot read it. Claiming means signing in on the claim page, so opening that page *is* doing it for them. The CLI `claim` is only a fallback when no browser can be opened (headless / CI), and is never shown to the user. Also never show a CLI command for logging in — the browser flow is the user-facing path, and the CLI login is yours to run. +12. **The claim link you present must come from `edgeone login --claim`, never the bare `claimUrl`** — right after an anonymous deploy, run `edgeone login --claim --local --json` in the background and put its `claimLoginUrl` in the template. Only that link carries the login → claim → callback chain that lets the CLI learn the login state and auto-link the project; the bare `claimUrl` from deploy output claims without telling the CLI, so the user's next deploy would create a second anonymous project. Never print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim — in sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it. `makers claim` is only a fallback for headless/CI environments, run by you, never displayed. 13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -358,14 +358,22 @@ Add `--site china` or `--site global` only when the site must be pinned (the use Do **not** pass `-n`, `-e`, or `--area` — they are ignored under `--anonymous`. The project name is generated automatically. -### Step 4: Present the result — use the fixed template below +### Step 4: Start the claim listener, then present the result -Parse the **last line** of stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. +Parse the **last line** of the deploy stdout as JSON (human-readable output precedes it). Fields are **camelCase**: `url`, `projectId`, `deploymentId`, `anonymousToken`, `claimUrl`, `claimCommand`, `expiresAt`, `site`. -⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` and `` with the values from the JSON. Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. +**Immediately start the claim listener in the background** — it must be listening before the user clicks the claim link, or the login state never reaches the CLI and the next deploy would create a second anonymous project: + +```bash +edgeone login --claim --local --json +``` + +Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl":...}` JSON line right away, then keeps listening (up to 60 minutes). Grab `claimLoginUrl` from that line. ⛔ **This URL — not the `claimUrl` field from the deploy JSON — is the claim link you show the user.** Only this link chains login → claim page → callback to the CLI. The bare `claimUrl` from deploy output would claim the project without telling the CLI, and the user's next deploy would go to a new anonymous project instead of the claimed one. ⛔ **Send the template as its own message, after the deploy command has fully returned.** Do not emit it in the same message in which you ran the deploy, do not attach it to the command's output, and do not print it while the command is still running. In WorkBuddy, content emitted alongside a running/finished command can be folded into a collapsible process message — if that happens, the user never sees the URL or the claim link. Wait for the Bash call to end, then send the template alone as your next reply. +⛔ **This is a fixed template, not a suggestion.** Reproduce it exactly: same four lines, same order, same emoji, same separator. Substitute **only** `` (from the deploy JSON) and `` (from the `login --claim` output). Do not reword, merge, split, or reorder lines. Do not add a sentence before or after it. Do not append project ID, deployment ID, console URL, `expiresAt`, next steps, or commentary of any kind. + **English-speaking user — emit exactly this:** > 🌐 **Live URL**: `` @@ -374,7 +382,7 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **This link expires in 60 minutes**. > -> 👉 [Claim this project]() — please claim it within 60 minutes. +> 👉 [Claim this project]() — please claim it within 60 minutes. **Chinese-speaking user — emit exactly this:** @@ -385,42 +393,25 @@ Parse the **last line** of stdout as JSON (human-readable output precedes it). F > > ⏳ **该链接 60 分钟后失效**。 > -> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 +> 👉 [认领这个项目]() —— 请在 60 分钟内完成认领。 For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. -### Claiming a project +### After the user claims -**When the user says "帮我认领" / "claim it for me" — open the claim link in their browser.** Do **not** run the CLI claim command. Do not ask which way they prefer. +The background `login --claim` process exits on its own when the console relays the result. When it exits 0 with `{"status":"success",...,"linked":true}`: -```bash -# macOS (local, or WorkBuddy host) -open "" -# Linux -xdg-open "" -# Windows -start "" "" -``` - -Then confirm plainly, in the user's language: the claim page is open in the browser; please sign in there to complete the claim. Do not re-paste the URL, do not append extra guidance — the claim page owns the flow. - -⚠️ If no browser can be opened in this environment (headless / CI), fall back to running the CLI claim below — that is its only remaining use, and it is still never shown to the user. - -Requires login. Run from the directory containing `.edgeone/anonymous.json` and the token is picked up automatically: - -```bash -edgeone makers claim --json -# or pass the token explicitly: -edgeone makers claim --sid --json -``` +- the CLI is logged in (credentials saved, plus `.edgeone/auth.json` from `--local`), +- the project is linked (`.edgeone/project.json`), +- `.edgeone/anonymous.json` is removed. -⛔ The parameter is `--sid` (see critical rule 10). `-t` on `claim` is the account API token, not the anonymous token. +Tell the user plainly, in their language: the project is now in their account, and any further deploys will update that same project. Then use the normal deploy flow (`edgeone makers deploy --json`) for all later deploys. -Claim only after the deploy has finished — the backend only migrates deployments in `Success` state. On success the local state file is deleted and the project becomes a normal one, managed with `edgeone makers deploy`. +If the process exits non-zero (the user never completed the link within 60 minutes), the anonymous project is still unclaimed: re-run `edgeone login --claim --local --json` for a fresh link and present it again in the same template. -Report the outcome in plain language — the project name and its live URL — not the raw JSON. Confirm it is saved to their account and stop there; do not add what they "can now do" (see critical rule 13). +If the user asks you to "帮我认领" / "claim it for me": point them to the same link again while the listener is still running; if it already exited, re-run the command for a fresh link. Never print the CLI claim command — `edgeone makers claim --sid` remains only for headless/CI environments with no browser (see critical rule 12). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index 60f6a46..dc9ac4b 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -74,7 +74,7 @@ Do not pass these — they have no effect and will mislead the user: | `projectId` | Anonymous project ID. | | `deploymentId` | Deployment ID. | | `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | -| `claimUrl` | Web claim URL, on the console domain matching `site`. **This is what you show the user** — a clickable link. | +| `claimUrl` | Bare web claim URL. ⛔ **Do NOT present this to the user** — claiming through it leaves the CLI unaware, and the next deploy would create a second anonymous project. The user-facing claim link is the `claimLoginUrl` from `edgeone login --claim` (see Claim flow). | | `claimCommand` | Ready-to-run CLI claim command. **For you to execute, never to display** — see the note below. | | `expiresAt` | Token expiry as an ISO 8601 timestamp, when the backend returns one. **Do not show this to the user** — tell them to claim within 60 minutes (see below). Useful to you for diagnostics. May be absent. | | `site` | `china` or `global` — the API site this project lives on. | @@ -87,7 +87,7 @@ Do not pass these — they have no effect and will mislead the user: `suggestion` is only present for the rate-limit case. `errorCode` may be absent for generic failures. -⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. Show the `claimUrl` link and stop there. When the user asks you to claim it for them, **open the claim link in their browser** — that is what claiming means. `claimCommand` is a fallback for headless/CI environments with no browser, executed by you, never displayed. +⛔ **Never print `claimCommand` to the user.** Sandboxed IDEs (WorkBuddy and similar) give the user no terminal, so they cannot run it — and non-technical users cannot read it anyway. The claim link you show comes from `edgeone login --claim`. `claimCommand` is a fallback for headless/CI environments with no browser, executed by you, never displayed. --- @@ -220,17 +220,25 @@ The backend claims **asynchronously** and only migrates projects whose deploymen ## Claim flow -**Route A — open the claim page in the user's browser. This is the flow, and the only one you present.** Present the `claimUrl` link in the result. When the user asks you to claim it for them, open it for them: +**Route A — `edgeone login --claim` (the flow, and the only one you present).** Run it immediately after the anonymous deploy, in the background: ```bash -open "" # macOS (local, or WorkBuddy host) -xdg-open "" # Linux -start "" "" # Windows +edgeone login --claim --local --json ``` -Then confirm plainly: the claim page is open, please sign in there. Do not re-paste the URL or add guidance. Nothing else to run. +What it does: -**Route B — CLI claim. Fallback only**, for headless/CI environments where no browser can be opened. Never advertise it, never show the command to the user: +1. Reads `.edgeone/anonymous.json` (fails fast if absent). +2. Starts the login listener on a free port (from 1024) **without opening a browser**. +3. Prints a `{"status":"waiting","claimLoginUrl":"...","port":...,"projectName":"..."}` JSON line immediately, then keeps listening (60-minute timeout, matching the claim window). The URL chains Tencent Cloud login → the claim page (carrying the anonymous token + port + state). +4. The user logs in and claims on that page; the console relays the login state back to the listener after the claim completes. +5. On success the CLI saves credentials (plus `.edgeone/auth.json` with `--local`), waits briefly for the async transfer to become visible, links the project (`.edgeone/project.json`), deletes `.edgeone/anonymous.json`, and exits 0 with `{"status":"success","projectId":...,"projectName":...,"linked":true}`. + +If it exits non-zero (timeout / not completed), the anonymous state file is still there — re-run the same command for a fresh link. + +The bare `claimUrl` from the deploy JSON bypasses all of this: the project gets claimed but the CLI never learns the login state, never links the project, and the next deploy starts a second anonymous project. Never present it. + +**Route B — CLI claim. Fallback only**, for headless/CI environments where no browser exists. Never advertise it, never show the command to the user: 1. **Deploy must have succeeded.** Only `Success` deployments are migrated. 2. **Log in.** In an interactive environment the CLI opens a browser when needed; in CI, pass `-t `. @@ -275,11 +283,11 @@ edgeone makers deploy --anonymous --json # 2. Verify the deployment is live curl -sSI "" | head -1 -# 3. Later, once the user has an account -edgeone login --site global -edgeone makers claim --json # reads .edgeone/anonymous.json +# 3. Start the claim listener in the background right away +edgeone login --claim --local --json +# → first JSON line has claimLoginUrl; process exits 0 once the user claims ``` After an anonymous deploy, present the result using the **fixed template in [SKILL.md](../SKILL.md) Step 4** — do not assemble your own message. Substitute only the URL and the claim link; translate it into the user's language; add nothing. -It carries exactly three things, and that is deliberate: the access URL, the `claimUrl` link (**never** the `claimCommand`), and that the link expires in 60 minutes (**never** the raw `expiresAt` value). +It carries exactly three things, and that is deliberate: the access URL, the claim link (the `claimLoginUrl` from `login --claim` — never the bare `claimUrl`, never the `claimCommand`), and that the link expires in 60 minutes (**never** the raw `expiresAt` value). diff --git a/skills/makers-deploy/references/command-reference.md b/skills/makers-deploy/references/command-reference.md index 3dd373f..6ecba09 100644 --- a/skills/makers-deploy/references/command-reference.md +++ b/skills/makers-deploy/references/command-reference.md @@ -49,6 +49,7 @@ edgeone makers link --name -t # Non-interactive | Login (China, browser) | `edgeone login --site china` | | Login (Global, browser) | `edgeone login --site global` | | Login (token, auto-site) | `edgeone login --token ` | +| Login + claim anonymous project | `edgeone login --claim --local --json` (run in background after an anonymous deploy; prints `claimLoginUrl`, then waits) | | View login info | `edgeone whoami` | | Logout | `edgeone logout` | | Switch account | `edgeone switch` | diff --git a/skills/makers-env-adaption/SKILL.md b/skills/makers-env-adaption/SKILL.md index b2b0550..32daa61 100644 --- a/skills/makers-env-adaption/SKILL.md +++ b/skills/makers-env-adaption/SKILL.md @@ -10,7 +10,7 @@ description: >- NEVER python -m http.server / npx serve), dev server requirements. metadata: author: edgeone - version: "1.3.0" + version: "1.4.0" --- # Runtime Environment Adaptation Guide @@ -281,7 +281,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as | Situation | Do this | Not this | |---|---|---| -| Anonymous project needs claiming | Give the `claimUrl` as a clickable link; if the user says "claim it for me", run `open ""` to pop the claim page in their browser | ❌ Printing `edgeone makers claim --sid `, or running the CLI claim instead of opening the page | +| Anonymous project needs claiming | Run `edgeone login --claim --local --json` in the background and present its `claimLoginUrl` as a clickable link; the listener auto-links the project when the user finishes claiming | ❌ Printing `edgeone makers claim --sid `, or presenting the bare `claimUrl` from the deploy JSON (the CLI never learns the login state) | | The user needs to log in | Explain, then run `edgeone login --site --local` yourself | ❌ "Run `edgeone login` in your terminal" | | Something needs installing | Run it yourself in Bash | ❌ "Please run `npm install -g edgeone`" | From 8a5d58de8fc4a5dd143bd8d03fcd81945e7b9461 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 19 Aug 2026 10:57:33 +0800 Subject: [PATCH 24/34] docs(makers-deploy): reword the deploy-or-login choice in plain language MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 「匿名部署」是术语，非技术用户看不懂。Step 2 的选项改为固定文案 （中英两版照抄）：直接发布，稍后再登录 / 登录后发布。rule 9 的固定 模板例外范围同步扩展到 Step 2。 Versions: makers-deploy 2.10.1, _meta 1.8.1 --- _meta.json | 2 +- codex/makers-deploy.md | 23 +++++++++++++++++------ cursor/rules/makers-deploy.mdc | 23 +++++++++++++++++------ skills/makers-deploy/SKILL.md | 23 +++++++++++++++++------ 4 files changed, 52 insertions(+), 19 deletions(-) diff --git a/_meta.json b/_meta.json index 56ac432..c939e21 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.8.0", + "version": "1.8.1", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index eb27de0..5a2099f 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.10.0" + version: "2.10.1" --- # EdgeOne Makers Deployment Skill @@ -52,7 +52,7 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Steps 2 and 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** @@ -337,11 +337,22 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. -> You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. +**English-speaking user — present exactly these two options:** + +> - **Publish now, log in later** — No login needed. Get a preview link right away; you can log in and claim the site whenever you're ready. +> - **Log in, then publish** — Log in to your EdgeOne Makers account first; the site is saved straight to your account. + +**Chinese-speaking user — present exactly these two options:** + +> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 +> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 + +Map their pick to the flow: + +- **Publish now, log in later** → this is the anonymous deploy path — continue to **Step 3**. +- **Log in, then publish** → go to **Login** (browser flow), then continue with the normal deploy. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index eb27de0..5a2099f 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.10.0" + version: "2.10.1" --- # EdgeOne Makers Deployment Skill @@ -52,7 +52,7 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Steps 2 and 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** @@ -337,11 +337,22 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. -> You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. +**English-speaking user — present exactly these two options:** + +> - **Publish now, log in later** — No login needed. Get a preview link right away; you can log in and claim the site whenever you're ready. +> - **Log in, then publish** — Log in to your EdgeOne Makers account first; the site is saved straight to your account. + +**Chinese-speaking user — present exactly these two options:** + +> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 +> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 + +Map their pick to the flow: + +- **Publish now, log in later** → this is the anonymous deploy path — continue to **Step 3**. +- **Log in, then publish** → go to **Login** (browser flow), then continue with the normal deploy. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index eb27de0..5a2099f 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -18,7 +18,7 @@ description: >- use edgeone-makers-dev for troubleshooting). metadata: author: edgeone - version: "2.10.0" + version: "2.10.1" --- # EdgeOne Makers Deployment Skill @@ -52,7 +52,7 @@ Deploy any project to **EdgeOne Makers**. 6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Step 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. +9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Steps 2 and 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. **Rules 10-13 apply to the anonymous deploy / claim flow only:** @@ -337,11 +337,22 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking -In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). Phrase it in the user's language — the English below specifies the meaning, not the wording (critical rule 9): +In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. -> You're not logged in to EdgeOne Makers. Two options: -> - **Deploy anonymously (no login)** — you get a working URL immediately, but the link expires in 60 minutes unless you sign in and claim it. Until claimed, it also has visitor-count and IP restrictions, so it isn't suitable for wide sharing. -> - **Log in now** — the project is saved to your account right away, with no expiry to worry about. +**English-speaking user — present exactly these two options:** + +> - **Publish now, log in later** — No login needed. Get a preview link right away; you can log in and claim the site whenever you're ready. +> - **Log in, then publish** — Log in to your EdgeOne Makers account first; the site is saved straight to your account. + +**Chinese-speaking user — present exactly these two options:** + +> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 +> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 + +Map their pick to the flow: + +- **Publish now, log in later** → this is the anonymous deploy path — continue to **Step 3**. +- **Log in, then publish** → go to **Login** (browser flow), then continue with the normal deploy. ⛔ **Do not over-promise what claiming gives them.** Say the project is *kept* / *saved to their account*, and nothing more. Specifically, do **not** say "no access restrictions", "permanently yours", or anything implying the URL is then unconditionally public and final — a claimed project can still need a custom domain and, for mainland-China access, ICP filing. Do **not** raise custom domains, ICP filing, or DNS at this point either: the user is deciding whether to log in, and those concepts are noise here. The claim page walks them through next steps. From be9ed3df92e27472852c8d6aee05d754d94669f3 Mon Sep 17 00:00:00 2001 From: jesperxu Date: Wed, 19 Aug 2026 12:08:07 +0800 Subject: [PATCH 25/34] =?UTF-8?q?fix:=E6=96=87=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/makers-deploy/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/skills/makers-deploy/SKILL.md b/skills/makers-deploy/SKILL.md index 5a2099f..1e57d28 100644 --- a/skills/makers-deploy/SKILL.md +++ b/skills/makers-deploy/SKILL.md @@ -338,6 +338,7 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. +The option text must be placed in the `label` exactly as is; it must not be split into the `description`. **English-speaking user — present exactly these two options:** @@ -346,8 +347,8 @@ In an interactive environment, present the choice (use the IDE's selection contr **Chinese-speaking user — present exactly these two options:** -> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 -> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 +> - **直接发布，稍后再登录(无需登录即可发布，先获得网站预览链接，之后可登录并认领网站)** +> - **登录后发布(登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户)** Map their pick to the flow: @@ -397,7 +398,7 @@ Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl **Chinese-speaking user — emit exactly this:** -> 🎉 匿名部署成功 +> 🎉 部署成功 > 🌐 **访问地址**：`` > > --- From 81ba90b497ce9bd796b2d7f7a2013f758d2e206a Mon Sep 17 00:00:00 2001 From: jesperxu Date: Thu, 20 Aug 2026 16:57:11 +0800 Subject: [PATCH 26/34] docs(makers-deploy): anonymous url now arrives signed (NeedVisit) --- _meta.json | 2 +- codex/makers-deploy.md | 7 ++++--- cursor/rules/makers-deploy.mdc | 7 ++++--- skills/makers-deploy/references/anonymous-deploy.md | 6 +++--- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/_meta.json b/_meta.json index c939e21..5b3c652 100644 --- a/_meta.json +++ b/_meta.json @@ -2,7 +2,7 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.8.1", + "version": "1.9.3", "files": [ "SKILL.md", "CLAUDE.md", diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 5a2099f..1e57d28 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -338,6 +338,7 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. +The option text must be placed in the `label` exactly as is; it must not be split into the `description`. **English-speaking user — present exactly these two options:** @@ -346,8 +347,8 @@ In an interactive environment, present the choice (use the IDE's selection contr **Chinese-speaking user — present exactly these two options:** -> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 -> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 +> - **直接发布，稍后再登录(无需登录即可发布，先获得网站预览链接，之后可登录并认领网站)** +> - **登录后发布(登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户)** Map their pick to the flow: @@ -397,7 +398,7 @@ Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl **Chinese-speaking user — emit exactly this:** -> 🎉 匿名部署成功 +> 🎉 部署成功 > 🌐 **访问地址**：`` > > --- diff --git a/cursor/rules/makers-deploy.mdc b/cursor/rules/makers-deploy.mdc index 5a2099f..1e57d28 100644 --- a/cursor/rules/makers-deploy.mdc +++ b/cursor/rules/makers-deploy.mdc @@ -338,6 +338,7 @@ If the user acknowledges the limitation and still wants an anonymous deploy, you ### Step 2: Ask the user — do not deploy anonymously without asking In an interactive environment, present the choice (use the IDE's selection control, e.g. `ask_followup_question`). The option labels deliberately avoid the word "anonymous" — it is jargon and confuses non-technical users. Present these two options **exactly**, in the user's language. Do not paraphrase the labels, do not add caveats to the options themselves, and do not mention "anonymous" to the user at all. +The option text must be placed in the `label` exactly as is; it must not be split into the `description`. **English-speaking user — present exactly these two options:** @@ -346,8 +347,8 @@ In an interactive environment, present the choice (use the IDE's selection contr **Chinese-speaking user — present exactly these two options:** -> - **直接发布，稍后再登录** —— 无需登录即可发布，先获得网站预览链接，之后可登录并认领网站 -> - **登录后发布** —— 登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户 +> - **直接发布，稍后再登录(无需登录即可发布，先获得网站预览链接，之后可登录并认领网站)** +> - **登录后发布(登录 EdgeOne Makers 账户后发布，网站将直接保存到您的账户)** Map their pick to the flow: @@ -397,7 +398,7 @@ Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl **Chinese-speaking user — emit exactly this:** -> 🎉 匿名部署成功 +> 🎉 部署成功 > 🌐 **访问地址**：`` > > --- diff --git a/skills/makers-deploy/references/anonymous-deploy.md b/skills/makers-deploy/references/anonymous-deploy.md index dc9ac4b..854315d 100644 --- a/skills/makers-deploy/references/anonymous-deploy.md +++ b/skills/makers-deploy/references/anonymous-deploy.md @@ -57,7 +57,7 @@ Do not pass these — they have no effect and will mislead the user: ```json { "status": "success", - "url": "https://my-app-a3f8b2c1.edgeone.dev", + "url": "https://my-app-a3f8b2c1.edgeone.dev?eo_token=abc123&eo_time=1234567890", "projectId": "makers-ihtxkls1k3jc", "deploymentId": "dppxfikip2rt", "anonymousToken": "98a71090aaae2670c6fe0024a250d6f3", @@ -70,7 +70,7 @@ Do not pass these — they have no effect and will mislead the user: | Field | Meaning | |-------|---------| -| `url` | Live access URL. Present it exactly as returned, never truncated — if it carries a query string, keep the whole thing. | +| `url` | Live access URL. The CLI requests it signed (`NeedVisit: true`), so it arrives with `?eo_token=...&eo_time=...` — that signature is what makes it openable, including on the China site. Present it exactly as returned, never truncated. | | `projectId` | Anonymous project ID. | | `deploymentId` | Deployment ID. | | `anonymousToken` | Anonymous identity token (the Sid). Needed to claim. | @@ -168,7 +168,7 @@ Raise domains or filing **only** when the user asks about stable / production / China and Global are fully independent environments: tokens and projects do not cross over. If the site is wrong, the claim fails. -> **China site status:** availability depends on backend anonymous-account configuration being in place for the China site. Confirm before relying on `--site china`. Note also that mainland-China access to preview links may be restricted by local regulations. +> **China site status:** availability depends on backend anonymous-account configuration being in place for the China site. Confirm before relying on `--site china`. An *unsigned* preview link 401s in mainland China — the signed URL from `NeedVisit: true` is what makes it accessible; --- From 0447f18f8b33695cb4ac98f11fdc9a02c824f52c Mon Sep 17 00:00:00 2001 From: jesperxu Date: Thu, 20 Aug 2026 17:44:23 +0800 Subject: [PATCH 27/34] Merge branch 'main' into feat/anonymous MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 冲突解决： - makers-deploy/SKILL.md：rule 4 取 main 的增强版（置顶 + present_files 双通道防折叠）；rule 9 并存（main 的报错原文 + 语言规则顺延为 10， 匿名规则 11-14，交叉引用同步改号）；决策表合并（匿名分流保留， 1.6.0-1.6.20 行走 main 的浏览器优先登录） - env-adaption/SKILL.md：两个 §13 并存 —— main 的浏览器弹窗限制为 §13， 我们的「不给用户命令」顺延为 §14/§14.1；version 1.4.1 - _meta.json：取 main 的新路径结构，anonymous-deploy.md 注册进 files， version 2.1.0 - anonymous-deploy.md 随 main 的目录重构迁至 skills/edgeone-makers-tools/references/makers-deploy/references/ - 生成物（cursor/codex）由 build.mjs 重新生成 按 main 的新规范补了 anonymous-deploy.md 与 command-reference.md 的目录 （doctor missing-toc 清零）。doctor 其余告警（dangling names、deep links、 oversized）与 main 基线一致。npm test 61/61。 Co-Authored-By: Claude --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codebuddy-plugin/manifest.json | 11 +- .codebuddy-plugin/marketplace.json | 11 +- .cursor-plugin/plugin.json | 2 +- .github/workflows/publish-skillhub.yml | 42 +- AGENTS.md | 18 +- BRANCH.md | 49 ++ CLAUDE.md | 21 +- README.md | 80 ++- SKILL.md | 16 + _meta.json | 87 +-- codex/makers-agents.md | 17 +- codex/makers-cli.md | 2 +- codex/makers-cloud-functions.md | 7 +- codex/makers-deploy.md | 64 +- codex/makers-edge-functions.md | 8 +- codex/makers-env-adaption.md | 60 +- codex/makers-middleware.md | 6 + codex/makers-migration.md | 24 +- codex/makers-recipes.md | 59 +- codex/makers-storage.md | 23 +- cursor/rules/makers-agents.mdc | 17 +- cursor/rules/makers-cli.mdc | 2 +- cursor/rules/makers-cloud-functions.mdc | 7 +- cursor/rules/makers-deploy.mdc | 64 +- cursor/rules/makers-edge-functions.mdc | 8 +- cursor/rules/makers-env-adaption.mdc | 60 +- cursor/rules/makers-middleware.mdc | 6 + cursor/rules/makers-migration.mdc | 24 +- cursor/rules/makers-recipes.mdc | 59 +- cursor/rules/makers-storage.mdc | 23 +- hooks/validate-write.mjs | 98 ++- hooks/validate-write.test.mjs | 154 ++++- package.json | 12 + scripts/add-toc.mjs | 93 +++ scripts/build.mjs | 11 +- scripts/doctor.mjs | 102 ++++ scripts/doctor.test.mjs | 76 +++ scripts/lib/skill-graph.mjs | 315 ++++++++++ scripts/lib/skill-graph.test.mjs | 560 ++++++++++++++++++ skills/edgeone-makers-tools/SKILL.md | 35 ++ .../references}/makers-agents/SKILL.md | 17 +- .../references/capabilities/sandbox.md | 0 .../references/capabilities/store.md | 102 +++- .../references/capabilities/tools.md | 12 + .../references/framework-native-patterns.md | 20 +- .../references/node-frameworks/claude-sdk.md | 45 +- .../references/node-frameworks/deepagents.md | 8 + .../references/node-frameworks/langgraph.md | 48 ++ .../node-frameworks/openai-agents.md | 73 +++ .../references/platform/cloud-functions.md | 0 .../references/platform/conversation-id.md | 0 .../references/platform/env-and-model.md | 0 .../references/platform/node-entry.md | 8 +- .../references/platform/python-entry.md | 14 + .../references/platform/sse-protocol.md | 0 .../python-frameworks/claude-sdk.md | 29 +- .../references/python-frameworks/crewai.md | 17 +- .../python-frameworks/deepagents.md | 8 + .../references/python-frameworks/langgraph.md | 46 ++ .../python-frameworks/openai-agents.md | 62 ++ .../references/review-checklist.md | 23 + .../references}/makers-cli/SKILL.md | 2 +- .../makers-cloud-functions/SKILL.md | 7 +- .../references/go-functions.md | 13 + .../references/node-functions.md | 15 + .../references/python-functions.md | 13 + .../references/troubleshooting.md | 10 + .../references}/makers-deploy/SKILL.md | 64 +- .../references/anonymous-deploy.md | 15 + .../references/command-reference.md | 12 + .../makers-edge-functions/SKILL.md | 8 +- .../references}/makers-env-adaption/SKILL.md | 60 +- .../references}/makers-middleware/SKILL.md | 6 + .../references}/makers-migration/SKILL.md | 24 +- .../references/api-route-to-makers.md | 6 + .../references/claude-agent-sdk-to-makers.md | 6 + .../references/crewai-to-makers.md | 6 + .../references/deepagents-to-makers.md | 6 + .../references/langgraph-to-makers.md | 6 + .../references/openai-agents-to-makers.md | 6 + .../references}/makers-recipes/SKILL.md | 59 +- .../references/youth-site-scenarios.md | 89 +++ .../references/makers-storage/SKILL.md | 51 ++ .../makers-storage/references/blob.md | 180 +++++- .../makers-storage/references/kv.md | 12 + skills/makers-storage/SKILL.md | 38 -- 88 files changed, 3162 insertions(+), 421 deletions(-) create mode 100644 BRANCH.md create mode 100644 package.json create mode 100644 scripts/add-toc.mjs create mode 100644 scripts/doctor.mjs create mode 100644 scripts/doctor.test.mjs create mode 100644 scripts/lib/skill-graph.mjs create mode 100644 scripts/lib/skill-graph.test.mjs create mode 100644 skills/edgeone-makers-tools/SKILL.md rename skills/{ => edgeone-makers-tools/references}/makers-agents/SKILL.md (95%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/capabilities/sandbox.md (100%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/capabilities/store.md (71%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/capabilities/tools.md (93%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/framework-native-patterns.md (78%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/node-frameworks/claude-sdk.md (86%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/node-frameworks/deepagents.md (96%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/node-frameworks/langgraph.md (73%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/node-frameworks/openai-agents.md (76%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/cloud-functions.md (100%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/conversation-id.md (100%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/env-and-model.md (100%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/node-entry.md (96%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/python-entry.md (92%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/platform/sse-protocol.md (100%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/python-frameworks/claude-sdk.md (81%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/python-frameworks/crewai.md (96%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/python-frameworks/deepagents.md (95%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/python-frameworks/langgraph.md (74%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/python-frameworks/openai-agents.md (68%) rename skills/{ => edgeone-makers-tools/references}/makers-agents/references/review-checklist.md (90%) rename skills/{ => edgeone-makers-tools/references}/makers-cli/SKILL.md (99%) rename skills/{ => edgeone-makers-tools/references}/makers-cloud-functions/SKILL.md (76%) rename skills/{ => edgeone-makers-tools/references}/makers-cloud-functions/references/go-functions.md (92%) rename skills/{ => edgeone-makers-tools/references}/makers-cloud-functions/references/node-functions.md (93%) rename skills/{ => edgeone-makers-tools/references}/makers-cloud-functions/references/python-functions.md (94%) rename skills/{ => edgeone-makers-tools/references}/makers-cloud-functions/references/troubleshooting.md (95%) rename skills/{ => edgeone-makers-tools/references}/makers-deploy/SKILL.md (78%) rename skills/{ => edgeone-makers-tools/references}/makers-deploy/references/anonymous-deploy.md (96%) rename skills/{ => edgeone-makers-tools/references}/makers-deploy/references/command-reference.md (89%) rename skills/{ => edgeone-makers-tools/references}/makers-edge-functions/SKILL.md (90%) rename skills/{ => edgeone-makers-tools/references}/makers-env-adaption/SKILL.md (64%) rename skills/{ => edgeone-makers-tools/references}/makers-middleware/SKILL.md (94%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/SKILL.md (92%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/api-route-to-makers.md (96%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/claude-agent-sdk-to-makers.md (98%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/crewai-to-makers.md (95%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/deepagents-to-makers.md (97%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/langgraph-to-makers.md (98%) rename skills/{ => edgeone-makers-tools/references}/makers-migration/references/openai-agents-to-makers.md (98%) rename skills/{ => edgeone-makers-tools/references}/makers-recipes/SKILL.md (52%) create mode 100644 skills/edgeone-makers-tools/references/makers-recipes/references/youth-site-scenarios.md create mode 100644 skills/edgeone-makers-tools/references/makers-storage/SKILL.md rename skills/{ => edgeone-makers-tools/references}/makers-storage/references/blob.md (51%) rename skills/{ => edgeone-makers-tools/references}/makers-storage/references/kv.md (94%) delete mode 100644 skills/makers-storage/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index d89207d..1a56f40 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ "name": "edgeone-makers-tools", "source": "./", "description": "EdgeOne Makers platform development skills — AI Agents, Cloud Functions, Edge Functions, Storage, Middleware, and Deployment.", - "version": "1.0.0", + "version": "2.0.0", "author": { "name": "EdgeOne" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 67296b5..d98eb53 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "edgeone-makers-tools", "description": "EdgeOne Makers platform development skills — AI Agents, Cloud Functions, Edge Functions, Storage, Middleware, and Deployment.", - "version": "1.0.0", + "version": "2.0.0", "author": { "name": "EdgeOne" } diff --git a/.codebuddy-plugin/manifest.json b/.codebuddy-plugin/manifest.json index 9e7ad70..6c93e1c 100644 --- a/.codebuddy-plugin/manifest.json +++ b/.codebuddy-plugin/manifest.json @@ -1,16 +1,9 @@ { "name": "edgeone-makers-tools", "description": "EdgeOne Makers platform development skills — AI Agents, Cloud Functions, Edge Functions, Storage, Middleware, and Deployment.", - "version": "1.0.0", + "version": "2.0.0", "author": "EdgeOne", "skills": [ - "skills/makers-agents", - "skills/makers-deploy", - "skills/makers-edge-functions", - "skills/makers-cloud-functions", - "skills/makers-storage", - "skills/makers-middleware", - "skills/makers-cli", - "skills/makers-recipes" + "skills/edgeone-makers-tools" ] } diff --git a/.codebuddy-plugin/marketplace.json b/.codebuddy-plugin/marketplace.json index b0d7768..5440d7f 100644 --- a/.codebuddy-plugin/marketplace.json +++ b/.codebuddy-plugin/marketplace.json @@ -9,20 +9,13 @@ "name": "edgeone-makers-tools", "source": "./", "description": "EdgeOne Makers platform development skills — AI Agents, Cloud Functions, Edge Functions, Storage, Middleware, and Deployment.", - "version": "1.0.0", + "version": "2.0.0", "author": { "name": "EdgeOne" }, "strict": false, "skills": [ - "./skills/makers-agents", - "./skills/makers-deploy", - "./skills/makers-edge-functions", - "./skills/makers-cloud-functions", - "./skills/makers-storage", - "./skills/makers-middleware", - "./skills/makers-cli", - "./skills/makers-recipes" + "./skills/edgeone-makers-tools" ], "hooks": "./hooks/hooks.json" } diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 67296b5..d98eb53 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "edgeone-makers-tools", "description": "EdgeOne Makers platform development skills — AI Agents, Cloud Functions, Edge Functions, Storage, Middleware, and Deployment.", - "version": "1.0.0", + "version": "2.0.0", "author": { "name": "EdgeOne" } diff --git a/.github/workflows/publish-skillhub.yml b/.github/workflows/publish-skillhub.yml index 8b11623..5e9c4b0 100644 --- a/.github/workflows/publish-skillhub.yml +++ b/.github/workflows/publish-skillhub.yml @@ -93,28 +93,34 @@ jobs: echo "==> Publishing version: $VERSION" - name: Prepare publish directory - # SkillHub 拒绝隐藏文件（如 .gitignore）和未在白名单的扩展名。 - # 按 _meta.json 的 files 字段精确复制需要发布的文件到一个干净目录， - # 然后用自动版本号覆写 publish 目录里 SKILL.md 和 _meta.json 的 version。 + # SkillHub 产物结构要求： + # _meta.json + # SKILL.md + # references/ + # 源码中文件位于 skills/edgeone-makers-tools/ 下，发布时去掉该前缀。 run: | PUBLISH_DIR="$RUNNER_TEMP/skillhub-publish" mkdir -p "$PUBLISH_DIR" - # 1. 复制 _meta.json，并用自动版本号覆写顶层 version - jq --arg v "$VERSION" '.version = $v' _meta.json > "$PUBLISH_DIR/_meta.json" + # 要去掉的路径前缀 + STRIP_PREFIX="skills/edgeone-makers-tools/" - # 2. 按 _meta.json 的 files 列表逐个复制 - jq -r '.files[]' _meta.json | while read -r f; do - mkdir -p "$PUBLISH_DIR/$(dirname "$f")" - cp "$f" "$PUBLISH_DIR/$f" - done + # 1. 复制 _meta.json，并用自动版本号覆写顶层 version， + # 同时重写 files 列表去掉前缀（保持产物自洽） + jq --arg v "$VERSION" --arg prefix "$STRIP_PREFIX" ' + .version = $v | + .files = [.files[] | if startswith($prefix) then .[$prefix | length:] else . end] + ' _meta.json > "$PUBLISH_DIR/_meta.json" - # 3. 覆写根 SKILL.md frontmatter 里"顶层" version 行（不动 metadata.version）。 - # 用 awk 替换，跨平台兼容（GNU/BSD sed 行为不一致，awk 更稳）。 + # 2. 从 skills/edgeone-makers-tools/ 目录复制所有文件到发布目录 + # 这样自然去掉了前缀，产物结构为 SKILL.md + references/ + cp -R skills/edgeone-makers-tools/* "$PUBLISH_DIR/" + + # 3. 覆写根 SKILL.md frontmatter 里 metadata.version 字段。 + # 当前格式：` version: "2.0.0"`（缩进两空格，在 metadata: 块内） if [ -f "$PUBLISH_DIR/SKILL.md" ]; then awk -v ver="$VERSION" ' - BEGIN { done = 0 } - /^version:[[:space:]]/ && !done { print "version: " ver; done = 1; next } + /^[[:space:]]+version:/ && !done { sub(/version:.*/, "version: \"" ver "\""); done = 1 } { print } ' "$PUBLISH_DIR/SKILL.md" > "$PUBLISH_DIR/SKILL.md.new" mv "$PUBLISH_DIR/SKILL.md.new" "$PUBLISH_DIR/SKILL.md" @@ -135,12 +141,12 @@ jobs: echo "PUBLISH_DIR=$PUBLISH_DIR" >> "$GITHUB_ENV" - name: Sanity check version bump - # 强校验：publish 目录里 SKILL.md 顶层 version 必须等于 $VERSION， - # _meta.json 顶层 version 也必须等于 $VERSION。否则立刻失败， - # 避免发布到一个仍带占位 1.0.0 的产物，浪费 SkillHub 的版本号。 + # 强校验：publish 目录里 SKILL.md 的 metadata.version 必须等于 $VERSION， + # _meta.json 顶层 version 也必须等于 $VERSION。否则立刻失败。 run: | EXPECTED="$VERSION" - ACTUAL_SKILL=$(awk '/^version:[[:space:]]/ {print $2; exit}' "$PUBLISH_DIR/SKILL.md") + # 提取缩进的 version: "x.y.z" 行，去掉引号 + ACTUAL_SKILL=$(awk '/^[[:space:]]+version:/ {gsub(/[" ]/, "", $2); print $2; exit}' "$PUBLISH_DIR/SKILL.md") ACTUAL_META=$(jq -r '.version' "$PUBLISH_DIR/_meta.json") echo "Expected: $EXPECTED" echo "SKILL.md actual: $ACTUAL_SKILL" diff --git a/AGENTS.md b/AGENTS.md index 971f5b4..4b42dae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,14 +4,14 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | Task | Read | |------|------| -| AI Agent development (DeepAgents, LangGraph, Claude SDK, OpenAI Agents, CrewAI) | skills/makers-agents/SKILL.md | -| Migrate existing agent project to EdgeOne Makers format | skills/makers-migration/SKILL.md | -| Deploy project to EdgeOne | skills/makers-deploy/SKILL.md | -| Edge Functions (V8 lightweight functions) | skills/makers-edge-functions/SKILL.md | -| Cloud Functions (Node.js / Go / Python APIs) | skills/makers-cloud-functions/SKILL.md | -| KV + Blob Storage | skills/makers-storage/SKILL.md | -| Middleware (auth, rewrites, routing) | skills/makers-middleware/SKILL.md | -| CLI command reference | skills/makers-cli/SKILL.md | -| Project structure / scaffolding | skills/makers-recipes/SKILL.md | +| AI Agent development (DeepAgents, LangGraph, Claude SDK, OpenAI Agents, CrewAI) | skills/edgeone-makers-tools/references/makers-agents/SKILL.md | +| Migrate existing agent project to EdgeOne Makers format | skills/edgeone-makers-tools/references/makers-migration/SKILL.md | +| Deploy project to EdgeOne | skills/edgeone-makers-tools/references/makers-deploy/SKILL.md | +| Edge Functions (V8 lightweight functions) | skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md | +| Cloud Functions (Node.js / Go / Python APIs) | skills/edgeone-makers-tools/references/makers-cloud-functions/SKILL.md | +| KV + Blob Storage | skills/edgeone-makers-tools/references/makers-storage/SKILL.md | +| Middleware (auth, rewrites, routing) | skills/edgeone-makers-tools/references/makers-middleware/SKILL.md | +| CLI command reference | skills/edgeone-makers-tools/references/makers-cli/SKILL.md | +| Project structure / scaffolding | skills/edgeone-makers-tools/references/makers-recipes/SKILL.md | ⚠️ Only read the Skill relevant to the current task. Do not load all skills at once. diff --git a/BRANCH.md b/BRANCH.md new file mode 100644 index 0000000..ecf188b --- /dev/null +++ b/BRANCH.md @@ -0,0 +1,49 @@ +# `skillhub` branch + +This branch is the **publishing branch** for CodeBuddy plugin marketplace and +SkillHub. Its **only** difference from `main` is that the root `SKILL.md` +carries a valid YAML frontmatter combining two sets of fields: + +- **SkillHub fields** (`slug`, `displayName`, `version`, `summary`, `license`) — + required by SkillHub's CLI (`skillhub publish`). +- **Claude Code / npx skills fields** (`name`, `description`) — required by + `npx skills add` and CodeBuddy plugin marketplace. + +YAML frontmatter is key-value, both sets coexist without conflict — each tool +reads only the keys it knows. + +## Why a separate branch? + +`npx skills add` (vercel-labs/skills CLI, v1.5.x) and CodeBuddy / SkillHub +disagree on what the root `SKILL.md` should contain: + +| Tool | Root `SKILL.md` requirement | +|------|----------------------------| +| `npx skills add` | Must **not** have valid frontmatter, otherwise it shadows `skills//SKILL.md` and only the root is installed (and from a git remote, sub-directories are not copied). | +| CodeBuddy / SkillHub | Must have valid frontmatter with `name` field, otherwise upload/install fails with "missing name". | + +→ `main` keeps the no-frontmatter root SKILL.md (so `npx skills add` installs +the 9 sub-skills correctly). +→ `skillhub` adds frontmatter on top (so CodeBuddy / SkillHub accept it). + +## Maintenance flow + +1. All development happens on `main` (or feature branches → `main`). +2. Before publishing to CodeBuddy / SkillHub, sync `main` into `skillhub`: + + ```bash + git checkout skillhub + git merge main # or: git rebase main + # The only conflict (if any) is on root SKILL.md frontmatter — keep skillhub's frontmatter, take main's body. + git push origin skillhub + ``` + +3. Publish from `skillhub` to CodeBuddy / SkillHub. + +## Install commands + +| Target | Command / Source | +|--------|------------------| +| `npx skills add` (Claude Code / Cursor / Codex / CodeBuddy CLI …) | `npx skills add TencentEdgeOne/edgeone-makers-tools` — uses `main` | +| CodeBuddy plugin marketplace | Install `edgeone-makers-tools` — backed by `skillhub` | +| SkillHub | Upload `skillhub` branch as the source | diff --git a/CLAUDE.md b/CLAUDE.md index aa2e78a..b34fa99 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,15 +4,16 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | Task | Read | |------|------| -| AI Agent development (DeepAgents, LangGraph, Claude SDK, OpenAI Agents, CrewAI) | skills/makers-agents/SKILL.md | -| Migrate existing agent project to EdgeOne Makers format | skills/makers-migration/SKILL.md | -| Deploy project to EdgeOne | skills/makers-deploy/SKILL.md | -| Edge Functions (V8 lightweight functions) | skills/makers-edge-functions/SKILL.md | -| Cloud Functions (Node.js / Go / Python APIs) | skills/makers-cloud-functions/SKILL.md | -| KV + Blob Storage | skills/makers-storage/SKILL.md | -| Middleware (auth, rewrites, routing) | skills/makers-middleware/SKILL.md | -| CLI command reference | skills/makers-cli/SKILL.md | -| Project structure / scaffolding | skills/makers-recipes/SKILL.md | -| Environment adaptation (WorkBuddy / sandbox / CI) | skills/makers-env-adaption/SKILL.md | +| AI Agent development (DeepAgents, LangGraph, Claude SDK, OpenAI Agents, CrewAI) | skills/edgeone-makers-tools/references/makers-agents/SKILL.md | +| Migrate existing agent project to EdgeOne Makers format | skills/edgeone-makers-tools/references/makers-migration/SKILL.md | +| Deploy project to EdgeOne | skills/edgeone-makers-tools/references/makers-deploy/SKILL.md | +| Edge Functions (V8 lightweight functions) | skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md | +| Cloud Functions (Node.js / Go / Python APIs) | skills/edgeone-makers-tools/references/makers-cloud-functions/SKILL.md | +| KV + Blob Storage | skills/edgeone-makers-tools/references/makers-storage/SKILL.md | +| Persist dynamic data for a site (messages, uploads, votes, save-state) — **no database; use Blob** | skills/edgeone-makers-tools/references/makers-storage/SKILL.md | +| Middleware (auth, rewrites, routing) | skills/edgeone-makers-tools/references/makers-middleware/SKILL.md | +| CLI command reference | skills/edgeone-makers-tools/references/makers-cli/SKILL.md | +| Project structure / scaffolding | skills/edgeone-makers-tools/references/makers-recipes/SKILL.md | +| Environment adaptation (WorkBuddy / sandbox / CI) | skills/edgeone-makers-tools/references/makers-env-adaption/SKILL.md | ⚠️ Only read the Skill relevant to the current task. Do not load all skills at once. diff --git a/README.md b/README.md index 2808053..0fce020 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,16 @@ Official AI Agent Skills for developing and deploying projects on [EdgeOne Maker npx skills add TencentEdgeOne/edgeone-makers-tools ``` -This installs **9 independent sub-skills** (one per capability) into your -agent's skills directory (`.codebuddy/skills//`, `.claude/skills//`, -`.cursor/skills//`, …). Your agent loads only the matching skill per -task — no router indirection. +This installs **one skill — `edgeone-makers-tools`** into your agent's skills +directory (`.codebuddy/skills/edgeone-makers-tools/`, `.claude/skills/edgeone-makers-tools/`, +`.cursor/skills/edgeone-makers-tools/`, …). Its `SKILL.md` is a router that loads the +matching capability under `references/` on demand — one skill in your list, full +coverage inside. ### Option B — CodeBuddy plugin marketplace / SkillHub Search and install `edgeone-makers-tools` from the CodeBuddy plugin marketplace or -SkillHub. These platforms install the skill from the -[`skillhub`](https://github.com/TencentEdgeOne/edgeone-makers-tools/tree/skillhub) -branch, which adds a frontmatter to the root `SKILL.md` so the platform can -register it as a single root skill (it then routes to the same 9 sub-skills -internally). - -> Why two branches? The two install ecosystems have **incompatible -> requirements** on the root `SKILL.md` (one wants no frontmatter, the other -> requires one). The `main` branch is optimized for `npx skills add`; the -> `skillhub` branch is optimized for CodeBuddy / SkillHub. See -> [`BRANCH.md`](https://github.com/TencentEdgeOne/edgeone-makers-tools/blob/skillhub/BRANCH.md) -> on the `skillhub` branch for the maintenance flow. +SkillHub. They register the same single `edgeone-makers-tools` skill. ### Option C — Claude Code plugin marketplace @@ -40,9 +30,11 @@ internally). After installation, your AI coding agent will automatically detect relevant tasks and load the right skill. -## Skills +## Capabilities -| Skill | Description | +The single `edgeone-makers-tools` skill routes to these capabilities (each lives under `skills/edgeone-makers-tools/references//`): + +| Capability | Description | |-------|-------------| | `makers-agents` | AI Agent development (DeepAgents, LangGraph, Claude SDK, OpenAI Agents, CrewAI) | | `makers-deploy` | Deploy projects to EdgeOne | @@ -52,6 +44,8 @@ After installation, your AI coding agent will automatically detect relevant task | `makers-middleware` | Middleware (auth, rewrites, routing) | | `makers-cli` | CLI command reference | | `makers-recipes` | Project structure templates & scaffolding | +| `makers-migration` | Migrate existing agent projects to EdgeOne Makers | +| `makers-env-adaption` | Environment adaptation (WorkBuddy / sandbox / CI) | ## Usage Examples @@ -99,34 +93,32 @@ Create a Claude Agent SDK endpoint with sandbox code execution ## Skill Structure +One skill, capabilities bundled as reference docs it routes to on demand: + ``` skills/ -├── makers-agents/ # AI Agent development -│ ├── SKILL.md # Decision tree, red lines, framework routing -│ └── references/ -│ ├── platform/ # Entry conventions, env, SSE protocol -│ ├── capabilities/ # Store, sandbox, tools -│ ├── node-frameworks/ # Claude SDK, LangGraph, OpenAI Agents, DeepAgents -│ └── python-frameworks/ # Claude SDK, LangGraph, OpenAI Agents, DeepAgents, CrewAI -├── makers-deploy/ # Deployment workflow -│ ├── SKILL.md -│ └── references/ -├── makers-edge-functions/ # V8 edge runtime -│ └── SKILL.md -├── makers-cloud-functions/ # Node.js / Go / Python -│ ├── SKILL.md -│ └── references/ -├── makers-storage/ # KV + Blob storage -│ └── SKILL.md -├── makers-middleware/ # Request interception -│ └── SKILL.md -├── makers-cli/ # CLI commands -│ └── SKILL.md -└── makers-recipes/ # Project templates - └── SKILL.md -``` - -Each skill follows the [skill-creator](https://github.com/anthropics/skills) standard: +└── edgeone-makers-tools/ + ├── SKILL.md # Router — matches the task, loads a capability below + └── references/ + ├── makers-agents/ # AI Agent development + │ ├── SKILL.md # Decision tree, red lines, framework routing + │ └── references/ + │ ├── platform/ # Entry conventions, env, SSE protocol + │ ├── capabilities/ # Store, sandbox, tools + │ ├── node-frameworks/ # Claude SDK, LangGraph, OpenAI Agents, DeepAgents + │ └── python-frameworks/ # Claude SDK, LangGraph, OpenAI Agents, DeepAgents, CrewAI + ├── makers-deploy/ # Deployment workflow + ├── makers-edge-functions/ # V8 edge runtime + ├── makers-cloud-functions/ # Node.js / Go / Python + ├── makers-storage/ # KV + Blob storage + ├── makers-middleware/ # Request interception + ├── makers-cli/ # CLI commands + ├── makers-recipes/ # Project templates + ├── makers-migration/ # Migrate existing agent projects + └── makers-env-adaption/ # Sandbox / WorkBuddy / CI adaptation +``` + +The skill follows the [skill-creator](https://github.com/anthropics/skills) standard: - `SKILL.md` — YAML frontmatter (name + description) + core instructions - `references/` — detailed docs loaded on demand, routed from `SKILL.md` diff --git a/SKILL.md b/SKILL.md index a4ca7f5..aeb684a 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,3 +1,19 @@ +--- +# --- SkillHub & Claude Code / npx skills 共用 frontmatter --- +slug: edgeone-makers-tools +name: edgeone-makers-tools +displayName: EdgeOne Makers +version: 1.0.0 +license: MIT +description: >- + EdgeOne Makers 全栈开发技能包 —— 涵盖 AI Agent 开发（DeepAgents、LangGraph、 + Claude SDK、OpenAI Agents、CrewAI）、云函数（Node.js/Go/Python）、边缘函数、 + KV 存储、中间件及快速部署，帮助 AI 编程助手准确高效地在 EdgeOne 平台上构建和发布应用。 +metadata: + author: edgeone + version: "1.0.0" +--- + # EdgeOne Makers Skills When you need EdgeOne Makers platform development guidance, read the matching Skill based on the task: diff --git a/_meta.json b/_meta.json index 5b3c652..d6615ac 100644 --- a/_meta.json +++ b/_meta.json @@ -2,46 +2,53 @@ "ownerId": "442102", "publishedAt": 1781766512723, "slug": "edgeone-makers-tools", - "version": "1.9.3", + "version": "2.1.0", "files": [ - "SKILL.md", - "CLAUDE.md", - "skills/makers-agents/SKILL.md", - "skills/makers-agents/references/capabilities/sandbox.md", - "skills/makers-agents/references/capabilities/store.md", - "skills/makers-agents/references/capabilities/tools.md", - "skills/makers-agents/references/framework-native-patterns.md", - "skills/makers-agents/references/node-frameworks/claude-sdk.md", - "skills/makers-agents/references/node-frameworks/deepagents.md", - "skills/makers-agents/references/node-frameworks/langgraph.md", - "skills/makers-agents/references/node-frameworks/openai-agents.md", - "skills/makers-agents/references/platform/cloud-functions.md", - "skills/makers-agents/references/platform/conversation-id.md", - "skills/makers-agents/references/platform/env-and-model.md", - "skills/makers-agents/references/platform/node-entry.md", - "skills/makers-agents/references/platform/python-entry.md", - "skills/makers-agents/references/platform/sse-protocol.md", - "skills/makers-agents/references/python-frameworks/claude-sdk.md", - "skills/makers-agents/references/python-frameworks/crewai.md", - "skills/makers-agents/references/python-frameworks/deepagents.md", - "skills/makers-agents/references/python-frameworks/langgraph.md", - "skills/makers-agents/references/python-frameworks/openai-agents.md", - "skills/makers-agents/references/review-checklist.md", - "skills/makers-cli/SKILL.md", - "skills/makers-cloud-functions/SKILL.md", - "skills/makers-cloud-functions/references/go-functions.md", - "skills/makers-cloud-functions/references/node-functions.md", - "skills/makers-cloud-functions/references/python-functions.md", - "skills/makers-cloud-functions/references/troubleshooting.md", - "skills/makers-deploy/SKILL.md", - "skills/makers-deploy/references/anonymous-deploy.md", - "skills/makers-deploy/references/command-reference.md", - "skills/makers-edge-functions/SKILL.md", - "skills/makers-env-adaption/SKILL.md", - "skills/makers-middleware/SKILL.md", - "skills/makers-recipes/SKILL.md", - "skills/makers-storage/SKILL.md", - "skills/makers-storage/references/blob.md", - "skills/makers-storage/references/kv.md" + "skills/edgeone-makers-tools/SKILL.md", + "skills/edgeone-makers-tools/references/makers-agents/SKILL.md", + "skills/edgeone-makers-tools/references/makers-agents/references/capabilities/sandbox.md", + "skills/edgeone-makers-tools/references/makers-agents/references/capabilities/store.md", + "skills/edgeone-makers-tools/references/makers-agents/references/capabilities/tools.md", + "skills/edgeone-makers-tools/references/makers-agents/references/framework-native-patterns.md", + "skills/edgeone-makers-tools/references/makers-agents/references/node-frameworks/claude-sdk.md", + "skills/edgeone-makers-tools/references/makers-agents/references/node-frameworks/deepagents.md", + "skills/edgeone-makers-tools/references/makers-agents/references/node-frameworks/langgraph.md", + "skills/edgeone-makers-tools/references/makers-agents/references/node-frameworks/openai-agents.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/cloud-functions.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/conversation-id.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/env-and-model.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/node-entry.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/python-entry.md", + "skills/edgeone-makers-tools/references/makers-agents/references/platform/sse-protocol.md", + "skills/edgeone-makers-tools/references/makers-agents/references/python-frameworks/claude-sdk.md", + "skills/edgeone-makers-tools/references/makers-agents/references/python-frameworks/crewai.md", + "skills/edgeone-makers-tools/references/makers-agents/references/python-frameworks/deepagents.md", + "skills/edgeone-makers-tools/references/makers-agents/references/python-frameworks/langgraph.md", + "skills/edgeone-makers-tools/references/makers-agents/references/python-frameworks/openai-agents.md", + "skills/edgeone-makers-tools/references/makers-agents/references/review-checklist.md", + "skills/edgeone-makers-tools/references/makers-cli/SKILL.md", + "skills/edgeone-makers-tools/references/makers-cloud-functions/SKILL.md", + "skills/edgeone-makers-tools/references/makers-cloud-functions/references/go-functions.md", + "skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md", + "skills/edgeone-makers-tools/references/makers-cloud-functions/references/python-functions.md", + "skills/edgeone-makers-tools/references/makers-cloud-functions/references/troubleshooting.md", + "skills/edgeone-makers-tools/references/makers-deploy/SKILL.md", + "skills/edgeone-makers-tools/references/makers-deploy/references/anonymous-deploy.md", + "skills/edgeone-makers-tools/references/makers-deploy/references/command-reference.md", + "skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md", + "skills/edgeone-makers-tools/references/makers-env-adaption/SKILL.md", + "skills/edgeone-makers-tools/references/makers-middleware/SKILL.md", + "skills/edgeone-makers-tools/references/makers-migration/SKILL.md", + "skills/edgeone-makers-tools/references/makers-migration/references/api-route-to-makers.md", + "skills/edgeone-makers-tools/references/makers-migration/references/claude-agent-sdk-to-makers.md", + "skills/edgeone-makers-tools/references/makers-migration/references/crewai-to-makers.md", + "skills/edgeone-makers-tools/references/makers-migration/references/deepagents-to-makers.md", + "skills/edgeone-makers-tools/references/makers-migration/references/langgraph-to-makers.md", + "skills/edgeone-makers-tools/references/makers-migration/references/openai-agents-to-makers.md", + "skills/edgeone-makers-tools/references/makers-recipes/SKILL.md", + "skills/edgeone-makers-tools/references/makers-recipes/references/youth-site-scenarios.md", + "skills/edgeone-makers-tools/references/makers-storage/SKILL.md", + "skills/edgeone-makers-tools/references/makers-storage/references/blob.md", + "skills/edgeone-makers-tools/references/makers-storage/references/kv.md" ] } diff --git a/codex/makers-agents.md b/codex/makers-agents.md index 0dc498c..0934883 100644 --- a/codex/makers-agents.md +++ b/codex/makers-agents.md @@ -15,6 +15,15 @@ description: >- Do NOT trigger for deployment workflows (use edgeone-pages-deploy). Do NOT trigger for generic AI framework development outside an EdgeOne Makers project. +pathPatterns: + - agents/** +validate: + - pattern: "process\\.env|os\\.environ" + message: "Read env via context.env inside agents/ and cloud-functions/, never process.env or os.environ (Critical Rule 3)." + - pattern: "headers\\s*\\.\\s*get\\s*\\(" + message: "Headers are plain objects here: context.request.headers['x-name'], not .get('x-name') (Critical Rule 4)." + - pattern: "langgraphStore\\s*\\?\\?\\s*store" + message: "Never write `store?.langgraphStore ?? store` — in cloud-function context it falls back to a store with no .get and crashes (Critical Rule 12)." metadata: author: edgeone version: "1.0.0" @@ -34,11 +43,11 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open - Wiring DeepAgents / LangGraph / CrewAI / OpenAI Agents SDK / Claude Agent SDK into a Makers project - Reviewing an existing agent template against platform red lines - Implementing SSE streaming with abort support -- Persisting conversation state via `context.store` (LangGraph checkpointer / OpenAI session / Claude session) +- Persisting conversation state via `context.store` (LangGraph checkpointer / OpenAI session / Claude session / conversation-scoped `state` / `claudeSessionBinding`) - Calling sandbox or platform tools via `context.sandbox` / `context.tools` - Splitting AI inference (`agents/`) from data CRUD (`cloud-functions/`) -> Cross-reference: if your code uses `context.store` or KV APIs, also read `skills/makers-storage/SKILL.md`. +> Cross-reference: if your code uses `context.store` or KV APIs, also read `../makers-storage/SKILL.md`. **Do NOT use for:** - Plain Edge Functions / Cloud Functions / Middleware → use `edgeone-pages-dev` @@ -68,8 +77,8 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open 10. **Cap your loops.** Manual bind-tools loops use a hard turn limit (e.g. `for (let i = 0; i < 4; i++)`); SDK routes set `maxTurns`. No unbounded "until model says stop" loops. 11. **Errors must not crash the stream.** Wrap every model / tool call in try/catch. Swallow `AbortError` silently. Emit other errors as `error_message` events without ending the stream prematurely. 12. **Pick the right `store` entry point — they are NOT shape-equivalent.** - - `context.store` (agent endpoints, `agents//`): full `AgentMemory`, includes **all** adapters (`openaiSession`, `claudeSessionStore`, `langgraphCheckpointer`, `langgraphStore`). - - `context.agent.store` (cloud-function endpoints, `cloud-functions//`): runtime **strips** `langgraphCheckpointer` and `langgraphStore`. Only generic message API + `openaiSession` + `claudeSessionStore` are available. + - `context.store` (agent endpoints, `agents//`): full `AgentMemory`, includes **all** adapters (`openaiSession`, `claudeSessionStore`, `langgraphCheckpointer`, `langgraphStore`, conversation `state`, `claudeSessionBinding`). + - `context.agent.store` (cloud-function endpoints, `cloud-functions//`): runtime **strips** `langgraphCheckpointer` and `langgraphStore`. Only generic message API + `openaiSession` + `claudeSessionStore` (+ `state` / `claudeSessionBinding`) are available. - **Consequence**: any endpoint that needs `langgraphStore.get/put` MUST live under `agents/`. Putting it in `cloud-functions/` will throw `kv.get is not a function` at runtime. - Never write `store?.langgraphStore ?? store` as a fake fallback — in cloud-function context this falls back to the store itself, which has no `.get`, and crashes. 13. **Use injected `context.sandbox` / `context.tools`.** Do not hand-write `/v1/sandbox/*` calls or parse tokens. `context.tools` shape is determined by `edgeone.json`'s `agents.framework` (`claude-agent-sdk` / `openai-agents-sdk` / `langgraph` / `crewai` / `deepagents` — there is **no `basic`**). Use `context.tools.all()`, `.get(name)`, `.files()`, `.browser()`. Sandbox: `sandbox.runCode(...)` is **top-level** (not `code_interpreter.runCode`); `screenshot({ fullPage: true })` takes an object, not a boolean; timeout is in **seconds**. diff --git a/codex/makers-cli.md b/codex/makers-cli.md index b0c9925..5ec14fc 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -1,5 +1,5 @@ --- -name: makers-cli +name: edgeone-makers-cli description: >- EdgeOne Makers CLI command reference. Use when running edgeone CLI commands for dev, build, deploy, env management. diff --git a/codex/makers-cloud-functions.md b/codex/makers-cloud-functions.md index 26fac3d..86832a1 100644 --- a/codex/makers-cloud-functions.md +++ b/codex/makers-cloud-functions.md @@ -1,8 +1,13 @@ --- -name: makers-cloud-functions +name: edgeone-makers-cloud-functions description: >- EdgeOne Makers Cloud Functions — Node.js, Go, and Python runtimes. Use when building server-side APIs, Express/Koa patterns, or backend logic. +pathPatterns: + - cloud-functions/** +validate: + - pattern: "process\\.env|os\\.environ" + message: "Read env via context.env inside cloud-functions/, never process.env or os.environ." metadata: author: edgeone version: "1.0.0" diff --git a/codex/makers-deploy.md b/codex/makers-deploy.md index 1e57d28..e579d6b 100644 --- a/codex/makers-deploy.md +++ b/codex/makers-deploy.md @@ -16,6 +16,12 @@ description: >- commands — the skill contains critical rules for parsing deploy output and presenting access URLs. Do NOT trigger for post-deployment runtime errors (e.g. CORS issues, 500 errors after deploy — use edgeone-makers-dev for troubleshooting). +pathPatterns: + - "*.sh" + - .github/workflows/** +validate: + - pattern: "whoami[^\\n]*\\s-t\\s" + message: "edgeone whoami does not accept -t. Check the exit code instead: 0 = logged in, 1 = not." metadata: author: edgeone version: "2.10.1" @@ -42,24 +48,27 @@ Deploy any project to **EdgeOne Makers**. **Self-check after writing your reply**: scan for every instance of the `.edgeone.cool` domain. Does each one include `?eo_token=`? If any doesn't, fix it NOW — the user will get a 401. 3a. **Prefer `--json` when running non-interactively** — in Agent/CI/headless contexts, always pass `--json` to `deploy` so the result is a single machine-readable line; no need to scrape colored/`\r`-animated stdout. See **Parse Deploy Output**. -3b. **Use `edgeone whoami` to check login status** — `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. -4. **⚠️ The deploy URL MUST be placed prominently at the very top of your reply** — once deployment finishes, the complete access URL is the core deliverable the user cares about most. You MUST: ① place it on the first line or in the first standalone block of your reply body; ② use a prominent format (e.g. a large heading + code block); ③ never bury the URL in the middle of a long paragraph where the user has to hunt for it. Example format: +3b. **Use `edgeone whoami` to check login status** — on CLI ≥ 1.6.0, `whoami` fails fast (exit 1) when not logged in instead of hanging. If it exits 0, the user is already logged in and `-t` is not needed. **Do NOT** check `cat .edgeone/.token` — CLI stores credentials in `~/.edgeone/` files, not a fixed `.token` path. +4. **The deploy URL MUST be placed at the very top of the visible reply body (own line, code block, or heading — not inline, not mid-reply), AND ALSO pinned via `present_files` (or the IDE's preview tool) to the side panel.** Two UI failures to survive: thinking / reasoning / "深度思考" blocks hide content by default; long replies get auto-folded by IDE chat cards, burying anything placed mid-reply. `present_files` is unaffected by chat folding — that's the second, always-visible channel. Complete URL, no truncation (Rule 2). Example format: ``` 🌐 Live URL: https://my-project-abc123.edgeone.cool? ``` Then append any other notes (console URL, caveats, etc.). + + **Self-check before ending the turn (MANDATORY)** — read back what the user will actually SEE (NOT your thinking / reasoning content). Two questions: (a) Is the complete `.edgeone.cool` URL present at the top of the visible reply, in a code block or heading? (b) Was `present_files` called with that URL? If either answer is no, send an **additional short message** containing ONLY the `🌐 Live URL: ` block and call `present_files`. Do not end the turn until both channels carry the URL. "I already mentioned it in my reasoning" is NOT a substitute for placing it in the visible body. 5. **Ask the user to choose China or Global site** before browser login. Never assume. (Token login via `edgeone login --token` auto-detects site, no need to ask.) -6. **Auto-detect the login method** — browser login in desktop environments, token login in headless/remote/CI environments. Follow the decision table below. +6. **Prefer Browser Login; fall back to Token only after browser login is confirmed to fail** (see Login section for the ~60s fallback threshold and the Agent-in-IDE clarification — WorkBuddy is NOT headless). Token-first only when the user explicitly requests it. 7. **After token login, ask if the user wants to save the token locally** for future use. 8. **Before triggering any browser popup (login / registration), explain the reason and the benefits to the user first** — never silently launch a browser window. -9. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Steps 2 and 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. +9. **On any CLI failure, surface the actual error text to the user before retrying, switching commands, or proposing a workaround.** Do NOT paraphrase (e.g. don't rewrite `Makers project exceeds 40 limit` into "maybe a name conflict or permission"). Do NOT silently pivot from `makers dev` to `makers deploy` (or vice versa) hoping to bypass — a systemic failure (auth / quota / permission) hits both with the same cause. Quote the raw error, name the root cause, then propose the fix or ask the user. +10. **Write every user-facing message in the user's own language** — **all** prose, blockquotes, and prompts in this skill are written in English purely to specify *meaning*; none of it is a string to paste. If the user writes to you in Chinese, speak Chinese — the login explanation, the site choice, the token question, the deploy result, all of it. Likewise for any other language. Emitting this skill's English strings into a non-English conversation is a bug. Only literal CLI commands, flags, env var names, and JSON field names stay verbatim. ⚠️ Where this skill gives a **fixed template** (Steps 2 and 4 of Anonymous Deploy), translating it is required but rewriting or extending it is not allowed — match it line for line. -**Rules 10-13 apply to the anonymous deploy / claim flow only:** +**Rules 11-14 apply to the anonymous deploy / claim flow only:** -10. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. -11. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. -12. **The claim link you present must come from `edgeone login --claim`, never the bare `claimUrl`** — right after an anonymous deploy, run `edgeone login --claim --local --json` in the background and put its `claimLoginUrl` in the template. Only that link carries the login → claim → callback chain that lets the CLI learn the login state and auto-link the project; the bare `claimUrl` from deploy output claims without telling the CLI, so the user's next deploy would create a second anonymous project. Never print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim — in sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it. `makers claim` is only a fallback for headless/CI environments, run by you, never displayed. -13. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. +11. **The claim command's parameter is `--sid`, NOT `--token`** — `edgeone makers claim --sid `. The `-t` / `--token` flag on `claim` is the **account API token**, an entirely different credential. Passing the anonymous token to `-t` fails. Product documentation showing `claim --token ` is wrong; trust this rule. +12. **Present the anonymous deploy result with the fixed template in Step 4** — it is a template, not an example: reproduce it exactly, substituting only the URL and the claim link. Never show the raw `expiresAt` timestamp, never state a different duration, and never add lines to it. 60 minutes is the product's stated claim window and the conservative instruction, so that is what the template says even though the token's observed lifetime can be longer. It frames the *link* as expiring, not the project as being deleted. +13. **The claim link you present must come from `edgeone login --claim`, never the bare `claimUrl`** — right after an anonymous deploy, run `edgeone login --claim --local --json` in the background and put its `claimLoginUrl` in the template. Only that link carries the login → claim → callback chain that lets the CLI learn the login state and auto-link the project; the bare `claimUrl` from deploy output claims without telling the CLI, so the user's next deploy would create a second anonymous project. Never print `claimCommand`, `edgeone makers claim --sid ...`, or any other command as the user's way to claim — in sandboxed IDEs like WorkBuddy the user has no terminal and literally cannot run it. `makers claim` is only a fallback for headless/CI environments, run by you, never displayed. +14. **Keep the claim pitch minimal — do not over-promise, and do not teach domains** — say only that signing in *keeps* the project. ❌ Never write "permanently yours", "no time limit or access restrictions", "unlimited", or anything implying the URL then works unconditionally forever: a claimed project may still need a custom domain, and mainland-China access can require ICP filing, so those claims are false. ❌ Also do not volunteer custom domains, ICP filing, DNS, or console navigation while the user is just deciding whether to claim — that front-loads complexity onto someone who only wanted a live URL. The claim page owns the follow-up flow. Answer such topics only when the user asks. --- @@ -97,6 +106,13 @@ 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 ``` @@ -110,7 +126,8 @@ cat edgeone.json 2>/dev/null | `≥ 1.6.0` ✓ | Not logged in, has saved token | → Go to **Deploy with Token** (use saved token) | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **interactive** | → Go to **Anonymous Deploy** — ask the user to choose anonymous deploy or login | | `≥ 1.6.21` ✓ | Not logged in, no saved token, **non-interactive (Agent/CI/headless)** | → Go to **Anonymous Deploy**; when the user cannot be asked, deploy with `--anonymous --json` and surface the claim link and the 60-minute claim window in the result | -| `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → Go to **Login**, or ask the user for a token | +| `1.6.0`–`1.6.20` | Not logged in, no saved token | Anonymous deploy is unavailable on this version → **Try Browser Login first** (see Login section). If the browser doesn't open or nothing happens within ~60 seconds, fall back to **Token Login**. Do NOT preemptively skip browser login by guessing "this looks like an Agent/CI environment" — that guess is often wrong; in particular, **WorkBuddy is a desktop IDE sandbox and fully supports browser login** | +| `≥ 1.6.0` ✓ | User explicitly provides a token or requests token login | → Go to **Deploy with Token** / **Token Login** | --- @@ -138,7 +155,7 @@ Tell the user: > - **What happens next**: I'll run `edgeone login`, and your default browser will open the Tencent Cloud login page. Please complete the login/registration and authorize access, then come back here. > - **If you get stuck**: If the browser doesn't open, or the CLI keeps waiting after you've logged in, let me know — I'll switch to Token login instead. -If the user does not respond for an extended period (e.g., more than 1–2 minutes), **proactively ask** about their status (whether the browser opened, any errors, or if they want to switch to Token login). Do not wait indefinitely. +If the user does not respond within ~60 seconds (no browser popup or no progress reported), **proactively ask** about their status (whether the browser opened, any errors, or if they want to switch to Token login). Do not wait indefinitely. ### 1. Ask the user to choose a site, then ALWAYS pass `--site` @@ -155,13 +172,14 @@ A bare `login` in a non-interactive context fails fast asking for `--site` (it no longer pops an interactive site-picker that would hang). The site choice is meant to happen here in the conversation, not inside the CLI. -### 2. Detect environment and choose login method +### 2. Login methods reference -| Condition | Method | -|-----------|--------| -| Local desktop IDE (VS Code, Cursor, WorkBuddy, etc.) | **Browser Login** | -| Remote / SSH / container / CI / cloud IDE / headless | **Token Login** | -| User explicitly requests token | **Token Login** | +Two login methods are available. **Per Rule 6, always try Browser Login first**; the table below is a reference for when each method applies, not a decision procedure — do not use it to guess the environment. + +| Method | When it applies | +|--------|-----------------| +| **Browser Login** | Default. Works in all local desktop IDEs (VS Code, Cursor, WorkBuddy) — the IDE bridges the OS browser + OAuth callback into the sandbox. | +| **Token Login** | Fallback after Browser Login is confirmed to fail (no browser popup / no progress within ~60s), OR when the user explicitly provides a token or requests token login. Also the only option in truly detached environments (SSH-only, CI runners, browserless containers). | #### Browser Login @@ -193,6 +211,8 @@ edgeone login --token Auto-detects china/global from the token — no `--site` flag needed. Persists login state for subsequent commands. +> 💡 **Reuse the token from a prior browser login — no console trip needed.** `edgeone login --site ` (browser) auto-generates an API Token and writes it to `~/.edgeone/` (JSON with `value.Token`). You can reuse that `Token` value directly as `EDGEONE_PAGES_API_TOKEN=""` or `-t ` for `makers dev`/`deploy` in headless/agent contexts, instead of creating a new token in the console. + **Method B: Pass `-t` directly in deploy (per-invocation)** Token is used for that single deploy only; no persistent login state is saved. @@ -409,7 +429,7 @@ Run it with `run_in_background`. It prints a `{"status":"waiting","claimLoginUrl For any other language, translate **this** template and nothing more — keep the four lines, the emoji, the separator, and the exact same content. Do not take the freedom to add or explain. -Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 12 and 13. Answer those topics only if the user asks. +Afterwards, stop. Anything you feel like adding here — what claiming unlocks, custom domains, ICP filing, DNS, console navigation, an offer to claim on their behalf — is prohibited by critical rules 13 and 14. Answer those topics only if the user asks. ### After the user claims @@ -423,7 +443,7 @@ Tell the user plainly, in their language: the project is now in their account, a If the process exits non-zero (the user never completed the link within 60 minutes), the anonymous project is still unclaimed: re-run `edgeone login --claim --local --json` for a fresh link and present it again in the same template. -If the user asks you to "帮我认领" / "claim it for me": point them to the same link again while the listener is still running; if it already exited, re-run the command for a fresh link. Never print the CLI claim command — `edgeone makers claim --sid` remains only for headless/CI environments with no browser (see critical rule 12). +If the user asks you to "帮我认领" / "claim it for me": point them to the same link again while the listener is still running; if it already exited, re-run the command for a fresh link. Never print the CLI claim command — `edgeone makers claim --sid` remains only for headless/CI environments with no browser (see critical rule 13). For the full JSON schema, rate limits, error codes, state-file fields, and site-resolution rules, see [references/anonymous-deploy.md](references/anonymous-deploy.md). @@ -465,7 +485,7 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | **Project ID** | Value after `EDGEONE_PROJECT_ID=` | — | | **Console URL** | Line after "You can view your deployment..." | — | -**Show the user — the deploy URL MUST be placed at the very top of your reply, in the most prominent position:** +**Show the user — the deploy URL MUST be at the very top of the visible reply AND pinned via `present_files` to the side panel (see Rule 4 for why both channels are required):** ⚠️ **URL Integrity Rules (read before composing your reply):** @@ -500,8 +520,12 @@ https://console.cloud.tencent.com/edgeone/pages/project/pages-xxxxxxxx/deploymen | Auth error with token | Token may be expired — regenerate at the console | | Login appears successful but `deploy` reports auth error | Browser reused a session from the wrong site, binding the wrong account. Click "Sign in with a different account" on the login page, or log out from all Tencent Cloud consoles first | | `edgeone whoami` shows an unexpected account | Browser session reuse. Click "Sign in with a different account" or log out from all consoles and re-login | +| `Failed to create pages project` (dev) / `Makers project exceeds 40 limit` (deploy) | Account hit the **40-project cap**. Both dev and deploy fail the same way. Present ONLY these two options to the user, verbatim — no "recommended" tag on either, no third option (do NOT suggest CloudStudio or any other platform, do NOT invent alternatives): ① user deletes an unused project in the EdgeOne Makers console; ② user names an existing linked project via `-n `. Agent MUST NOT delete projects itself (CLI has no delete command by design — do not route around via HTTP APIs or cached credentials). | | Project name conflict | Use a different name with `-n` | | Build failure | Check logs — usually missing deps or bad build script | +| `whoami` says "not authenticated" but `edgeone login` just succeeded | Expected in agent/headless: `whoami` and `makers dev`/`deploy` read API-Token auth, not the browser session. Reuse the auto-generated token from `~/.edgeone/` (`value.Token`) as `EDGEONE_PAGES_API_TOKEN` / `-t`. See Token Login note above. | +| `makers dev` hangs on an interactive "Link existing / Create and link" menu | Dev was started without `-n` and fell into the interactive picker. Kill it, then restart with `edgeone makers dev -n --skip-env-sync` — dev auto-creates the project if missing and links it internally. Always pass `-n` to dev whenever the project uses Blob/KV. | +| `curl` to the deploy URL returns 302 → DingTalk SSO login | Preview gateway requires browser-based `eo_token` validation (JS), which `curl` can't do. Open the full `?eo_token=...&eo_time=...` URL in a real browser — it validates the token and bypasses SSO. Not a code bug. | --- diff --git a/codex/makers-edge-functions.md b/codex/makers-edge-functions.md index 7345171..98bcd31 100644 --- a/codex/makers-edge-functions.md +++ b/codex/makers-edge-functions.md @@ -13,6 +13,8 @@ validate: message: "Use plain object headers for this runtime surface." - pattern: "fs\\.writeFile" message: "Edge Functions do not support filesystem writes." + - pattern: "Response\\.json\\s*\\(" + message: "Response.json() is not available in this V8 runtime — use new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })." metadata: author: edgeone version: "1.0.0" @@ -108,9 +110,9 @@ export function onRequest(context) { ## KV Storage (Edge Functions only) -> Cross-reference: if your code uses `context.store` or KV APIs, also read `skills/makers-storage/SKILL.md`. +> Cross-reference: if your code uses `context.store` or KV APIs, also read `../makers-storage/SKILL.md`. -⚠️ **Prerequisites**: You must enable KV Storage in the EdgeOne Makers console, create a namespace, and bind it to your project before using KV. See [kv-storage.md](kv-storage.md) for full setup instructions (same directory). +⚠️ **Prerequisites**: You must enable KV Storage in the EdgeOne Makers console, create a namespace, and bind it to your project before using KV. See [../makers-storage/references/kv.md](../makers-storage/references/kv.md) for full setup instructions. The KV namespace is a **global variable** (name is set when binding in the console) — it is **NOT** on `context.env`. @@ -134,7 +136,7 @@ export async function onRequest(context) { } ``` -For full KV Storage API reference and usage guide, see: [kv-storage.md](kv-storage.md) (same directory). +For full KV Storage API reference and usage guide, see: [../makers-storage/references/kv.md](../makers-storage/references/kv.md). ## Supported Runtime APIs diff --git a/codex/makers-env-adaption.md b/codex/makers-env-adaption.md index 32daa61..5f90e47 100644 --- a/codex/makers-env-adaption.md +++ b/codex/makers-env-adaption.md @@ -3,14 +3,21 @@ 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. + 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.0" + version: "1.4.1" --- # Runtime Environment Adaptation Guide @@ -38,7 +45,8 @@ preview │ ┌─ dev server running? ─ Yes ── | 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

--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) | +| 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. @@ -55,6 +63,12 @@ preview │ ┌─ dev server running? ─ Yes ── 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. +> - **BUT browser login (`edgeone login --site `) works fully** — WorkBuddy launches the host OS browser AND routes the OAuth callback back into the sandbox. +> +> Deploy/link login should default to browser login and only fall back to `-t ` after browser login is confirmed to fail. Do NOT jump to token login just because the caller is an "Agent". + --- ### 1. Non-interactive mode (all CLI commands must avoid interactive prompts) @@ -100,21 +114,25 @@ edgeone login --site china --local edgeone whoami # exit 0 = logged in, exit 1 = not logged in (does not hang) ``` +**When is login actually required?** Login is only needed when the project uses **Blob** or other credentialed backends — and strictly because of the dependency chain: **Blob requires the project to be linked, and linking requires a logged-in account first.** So `edgeone makers dev` for a **pure-static** site runs fine without login — **do NOT force a login prompt for static-only previews**. Login (or `-t `) becomes mandatory the moment dev/deploy must touch Blob storage. (The trigger condition and the link chain live in makers-storage.) + **CLI version requirement**: >= 1.6.7 (older versions lack the non-interactive fixes; whoami will hang) --- -### 3. Network isolation +### 3. Network isolation (dev server reachability from Bash) -**The Bash tool's network is isolated from the host** — inside WorkBuddy's Bash, `curl localhost:` cannot reach the host's dev server. +The Bash tool and `edgeone makers dev` run **in the same sandbox (same machine)**, so the loopback dev server IS reachable from Bash. The earlier claim that "Bash curl is isolated and returns 404" is wrong — the failures are caused by the **proxy** (§5) and the **IPv6 localhost** (§4), not by network isolation. | Verification method | Availability | Notes | |---------|--------|------| -| Built-in browser preview (`present_files`) | ✅ Available | Uses the host network, reliable | +| Built-in browser preview (`present_files`) | ✅ Available | Uses the platform tunnel; the ONLY way the **user's** browser can see the sandbox dev server | | User's system terminal | ✅ Available | `curl http://127.0.0.1:8088/` | -| Bash tool curl | ❌ Unavailable | Routed inside the sandbox, returns 404 | +| Bash tool curl (agent-side API checks) | ✅ Available **only with `--noproxy '*'` + `127.0.0.1`** | Plain `curl localhost:8088` fails: (a) `localhost`→`::1` (§4), (b) proxy hijacks the request (§5) | -**Do NOT** use Bash curl to judge whether the dev server started successfully. Use `present_files` or verify by deploying. +**Practical rule**: +- Use `curl --noproxy '*' http://127.0.0.1:8088/...` from Bash to **agent-side verify** API endpoints during testing — this works (it was used to validate a full create→upload→like flow). +- Do NOT rely on Bash curl to show the page to the user. The user's browser cannot reach `127.0.0.1:8088` inside the sandbox; for a user-facing preview, pass the dev URL to `present_files` (platform tunnel) or deploy and share the live URL. --- @@ -172,7 +190,15 @@ A `setLocalData EPERM` does not affect the running service; it only affects the |------|---------|------| | `npm install` | **Foreground sync** | Usually 10-30s; running it in the background would leave later commands missing dependencies | | `edgeone makers dev` | **Background async** (`run_in_background`) | Long-running process, must not block the conversation | -| `edgeone makers deploy` | **Foreground sync** | 1-3 minutes; the result is the core deliverable and must be shown immediately | +| `edgeone makers deploy` | **Background async** (`run_in_background`) | Cold deploys (build → upload → Process → live) routinely take **2–10+ minutes**. The foreground wall-clock budget (~100s) SIGKILLs the CLI mid-deploy (exit 137) even while it keeps printing progress — you lose the final URL line. Run it in the background and wait for the completion notification. | + +#### 7.2 Deploy in background — why, and what the kill really means + +- **Foreground kill = wall-clock budget, not a hang.** A foreground Bash command in this sandbox has a fixed ~100s wall-clock budget; at the limit the whole process tree gets SIGKILL (`exit 137 = 128 + 9`), regardless of whether it keeps printing. During a deploy the CLI prints `Deployment in progress... elapsed: ~XXs` every ~10s — those heartbeat lines do NOT reset or extend the budget. So "still printing → killed at ~100s" is expected, not a stall. +- **Killing the CLI does NOT usually fail the deploy.** The deployment itself runs server-side. A foreground CLI killed at `Created deployment` / `Process` has very likely continued on the server and gone live (confirmed in practice: a deploy killed at ~100s was later verified live, took ~674s end-to-end). Re-running `deploy` (same `-n `) reuses the project and returns the URL. +- **Always use `run_in_background: true` for deploy** so the CLI survives past the foreground budget and emits the final `--json` line with the live URL. Do not poll the task across turns — rely on the `` completion event. (Cross-turn `TaskOutput` may report the handle as "not found"; the process still finished.) +- **`--json` still prints progress heartbeats** to stdout/stderr, not a single clean JSON line. Parse the **last** line for the result object; treat the progress lines as noise. (This is a CLI cleanliness issue, unrelated to the kill behavior — do not assume "no output = process ended"; the sandbox judges liveness by OS process state, not by stdout bytes.) +- **Clean up background processes** after use: a `edgeone makers dev` left running keeps holding port 8088 and may collide with the next dev/deploy. Stop it with `TaskStop` or kill it when the session moves on. ### 7.1 Preview & Dev Server full flow (MUST use HTTP, file:// forbidden) @@ -185,7 +211,7 @@ After finishing development, **start the dev server and preview directly** — d 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 --json` (**foreground sync**, see §7). +Only after the user confirms, run `edgeone makers deploy -n --json` (**background async**, see §7 and §7.2 — it exceeds the foreground wall-clock budget). #### ⛔ file:// preview is strictly forbidden @@ -241,6 +267,8 @@ Note: the value is a **bare host**, without an `http://` prefix and without a po 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`. +**Precondition — login first**: linking (and therefore Blob/KV) requires a logged-in account. The full chain is **Blob → must be linked → linking requires login**. If `edgeone whoami` returns exit 1, run `edgeone login` (browser) or use `edgeone makers link -t ` with a token **before** attempting to link. Do NOT try to link while unauthenticated. + **Detect whether it is linked**: ```bash cat .edgeone/project.json 2>/dev/null && echo "LINKED" || echo "NOT LINKED" @@ -275,7 +303,13 @@ Use `create-next-app@latest` rather than manually pinning an older version. --- -### 13. Never hand the user a command to run +### 13. Native browser dialogs (`alert` / `confirm` / `prompt`) don't work in WorkBuddy's built-in browser + +WorkBuddy's right-side preview panel does NOT render `window.alert()` / `window.confirm()` / `window.prompt()`. The call returns immediately without user interaction, so any handler gated on `if (confirm("Delete?"))` silently no-ops (a delete button appears to do nothing). The same page works fine in the user's real Chrome / Safari. + +**Rule**: for any confirmation, prompt, or notification in the page, use an **in-page custom modal** (a `

` overlay with buttons wired via JS). Do NOT rely on the browser's built-in `alert` / `confirm` / `prompt` — the code looks correct in code review, works when the user opens the deployed URL in their own browser, and is silently broken in the WorkBuddy preview during dev/verification. + +### 14. Never hand the user a command to run The user has **no terminal** in the WorkBuddy sandbox. Any command you print as an instruction is dead text — they cannot execute it, and a non-technical user cannot read it either. @@ -287,7 +321,7 @@ The user has **no terminal** in the WorkBuddy sandbox. Any command you print as You are the one with shell access — use it. Only ask the user to type something when it genuinely cannot be automated (e.g. completing a login in the browser window you opened), and say plainly what you need from them. -### 13.1 Never let the key result get folded into a process message +### 14.1 Never let the key result get folded into a process message WorkBuddy can collapse content emitted in the same message as a running or just-finished Bash command into a collapsible process entry. When the user asks to deploy, the deploy URL and claim link must never land there — if they do, the user sees nothing. diff --git a/codex/makers-middleware.md b/codex/makers-middleware.md index 751cc3d..c1d580e 100644 --- a/codex/makers-middleware.md +++ b/codex/makers-middleware.md @@ -3,6 +3,12 @@ name: edgeone-makers-middleware description: >- Edge middleware for EdgeOne Makers — request interception, redirects, rewrites, auth guards, A/B testing, and header injection at the edge (V8 runtime). +pathPatterns: + - middleware.js + - middleware.ts +validate: + - pattern: "NextRequest|NextResponse|next/server" + message: "Framework projects must use the framework's own middleware. This platform format takes a context object with next/redirect/rewrite — not NextRequest/NextResponse." metadata: author: edgeone version: "1.0.0" diff --git a/codex/makers-migration.md b/codex/makers-migration.md index 449d501..94826dc 100644 --- a/codex/makers-migration.md +++ b/codex/makers-migration.md @@ -1,5 +1,5 @@ --- -name: makers-migration +name: edgeone-makers-migration description: >- Migrate existing AI agent projects (LangChain, LangGraph, OpenAI Agents SDK, Claude Agent SDK, CrewAI) to EdgeOne Makers platform conventions. @@ -7,6 +7,12 @@ description: >- convert Express/Next.js API routes to Makers handlers, or add platform capabilities (context.tools, context.sandbox, context.store). Do NOT trigger for new agent projects (use makers-agents instead). +pathPatterns: + - agents/** + - cloud-functions/** +validate: + - pattern: "process\\.env|os\\.environ" + message: "Migration checklist: replace process.env / os.environ with context.env (TS) or ctx env access (Python)." metadata: author: edgeone version: "1.0.0" @@ -148,7 +154,7 @@ openai>=1.50.0 6. Replace custom tools with `ctx.tools.to_crewai_tools(BaseTool)` 7. Return SSE via `ctx.utils.stream_sse(gen())` -> See [makers-agents/skills/python-frameworks/crewai.md](../skills/makers-agents/references/python-frameworks/crewai.md) for the complete pattern. +> See [makers-agents/references/python-frameworks/crewai.md](../makers-agents/references/python-frameworks/crewai.md) for the complete pattern. > Detailed before/after: [references/crewai-to-makers.md](references/crewai-to-makers.md) --- @@ -197,9 +203,9 @@ openai>=1.50.0 6. Set `thread_id`: `{ configurable: { thread_id: context.conversation_id } }` 7. Replace response with SSE streaming pattern -> Node: [makers-agents/skills/node-frameworks/langgraph.md](../skills/makers-agents/references/node-frameworks/langgraph.md) -> Python: [makers-agents/skills/python-frameworks/langgraph.md](../skills/makers-agents/references/python-frameworks/langgraph.md) -> DeepAgents: [makers-agents/skills/node-frameworks/deepagents.md](../skills/makers-agents/references/node-frameworks/deepagents.md) +> Node: [makers-agents/references/node-frameworks/langgraph.md](../makers-agents/references/node-frameworks/langgraph.md) +> Python: [makers-agents/references/python-frameworks/langgraph.md](../makers-agents/references/python-frameworks/langgraph.md) +> DeepAgents: [makers-agents/references/node-frameworks/deepagents.md](../makers-agents/references/node-frameworks/deepagents.md) > Detailed before/after: [references/langgraph-to-makers.md](references/langgraph-to-makers.md), [references/deepagents-to-makers.md](references/deepagents-to-makers.md) --- @@ -246,8 +252,8 @@ openai>=1.50.0 4. Use `context.store.openaiSession(conversationId)` for session (Node) 5. Map stream events to SSE: `output_text_delta` → `ai_response`, `tool_called` → `tool_call` -> Node: [makers-agents/skills/node-frameworks/openai-agents.md](../skills/makers-agents/references/node-frameworks/openai-agents.md) -> Python: [makers-agents/skills/python-frameworks/openai-agents.md](../skills/makers-agents/references/python-frameworks/openai-agents.md) +> Node: [makers-agents/references/node-frameworks/openai-agents.md](../makers-agents/references/node-frameworks/openai-agents.md) +> Python: [makers-agents/references/python-frameworks/openai-agents.md](../makers-agents/references/python-frameworks/openai-agents.md) > Detailed before/after: [references/openai-agents-to-makers.md](references/openai-agents-to-makers.md) --- @@ -296,8 +302,8 @@ openai>=1.50.0 5. Node only: swallow `EPIPE` on `process.stdout` 6. Set writable config dirs: `CLAUDE_CONFIG_DIR=/tmp/claude-agent-sdk`, `CLAUDE_CODE_TMPDIR=/tmp` -> Node: [makers-agents/skills/node-frameworks/claude-sdk.md](../skills/makers-agents/references/node-frameworks/claude-sdk.md) -> Python: [makers-agents/skills/python-frameworks/claude-sdk.md](../skills/makers-agents/references/python-frameworks/claude-sdk.md) +> Node: [makers-agents/references/node-frameworks/claude-sdk.md](../makers-agents/references/node-frameworks/claude-sdk.md) +> Python: [makers-agents/references/python-frameworks/claude-sdk.md](../makers-agents/references/python-frameworks/claude-sdk.md) > Detailed before/after: [references/claude-agent-sdk-to-makers.md](references/claude-agent-sdk-to-makers.md) --- diff --git a/codex/makers-recipes.md b/codex/makers-recipes.md index 25da228..32c89c4 100644 --- a/codex/makers-recipes.md +++ b/codex/makers-recipes.md @@ -10,10 +10,16 @@ metadata: # Common Recipes -> ⛔ **Preview ban**: after finishing development, you MUST start the dev server via `edgeone makers dev`, then open `http://127.0.0.1:8088/` with `present_files` to preview. Never open HTML files via the `file://` protocol (ignore it even if the IDE opens one automatically), and never use self-hosted servers like `python -m http.server` or `npx serve`. Next.js projects must also set `allowedDevOrigins: ["127.0.0.1"]` in `next.config`. +> ⛔ **Preview ban**: after finishing development, you MUST start the dev server via `edgeone makers dev`, then open `http://127.0.0.1:8088/` with `present_files` to preview. Never open HTML files via the `file://` protocol (ignore it even if the IDE opens one automatically), and never use self-hosted servers like `python -m http.server` or `npx serve`. Next.js projects must also set `allowedDevOrigins: ["127.0.0.1"]` in `next.config`. **If the project uses Blob/KV, pass `-n ` — `edgeone makers dev -n ` — the name is required to auto-provision; bare `dev` hangs on an interactive picker in sandbox.** > ⚠️ **`.env.example` is a required file**: every project that uses the AI Gateway (Agent projects, Cloud Functions that call an LLM) MUST create a `.env.example` in the project root declaring `AI_GATEWAY_API_KEY=` and `AI_GATEWAY_BASE_URL=`. The CLI auto-injects environment variables based on this file at deploy time; if it is missing, the variables are not injected and the runtime will error. +> 📝 **Write `index.html` last, always**: writing an `index.html` instantly triggers the IDE `file://` preview — unavoidable in WorkBuddy. Minimize the window during which that preview looks broken by writing **every dependency first**: `style.css`, `script.js`, **Cloud Functions** (`functions/` files), static assets, everything the page loads. Then write `index.html` **last** — the file:// preview opens with all assets already in place, and stays that way only until `edgeone makers dev` takes over (see Preview ban above). Also write each `index.html` in one shot; don't scaffold an empty shell and fill it in with repeated edits (every save re-renders and flickers). For a tiny single-page tool, just inline the CSS and JS into one `index.html`. + +> ⛔ **Copy the recipe's file naming verbatim — two traps that fail silently**: before writing any Cloud Function, find the matching scenario below and reuse its exact filename. Getting the name wrong usually does NOT throw a clear error — it falls back silently: +> 1. **Every function file MUST carry its language extension** — `.js` (Node), `.py` (Python), `.go` (Go). A file with no extension (e.g. `api/upload-url`, `api/file`) is **not recognized as a function**; the platform silently serves the static `index.html` fallback, so `/api/*` "mysteriously" returns HTML instead of JSON. Name them `api/upload-url.js`, `api/file.js`. +> 2. **`[[default]].js` is the catch-all for its own directory (`api/[[default]].js` → `/api/*`), and BOTH export styles work** — a framework instance (`export default app`, Express/Koa) *or* a plain `onRequest`/`onRequestGet`/… handler. Verified locally with `edgeone makers dev`: a bare `onRequest` in `[[default]].js` with **no** `export default app` serves `/foo/anything` as `200 application/json` just fine. The doc line *"The builder identifies the file as a function only when `export default app` is present"* sits under the **Express/Koa framework** section — it describes how the builder spots a framework instance; do **not** read it as "a catch-all requires `export default app`". ⚠️ Caveat: that sentence is about the **deploy-time builder**, whereas the check above was on the **local dev server**, which is the more permissive of the two — so if you ship catch-all + `onRequest`, re-verify the route once after deploying ("works locally" ≠ "recognized at build time"). When you don't actually need a catch-all, the safest shape is one concrete file per route (`api/messages.js`, `api/artworks/[id]/like.js`), params via `[id]` folders/files, extra args as query strings (`/api/file?key=...`). + Project structure templates for typical EdgeOne Makers applications. ## Full-stack app — Node.js (static + API) @@ -36,6 +42,55 @@ const res = await fetch('/api/users'); const users = await res.json(); ``` +> 💾 **Where does the data live?** This platform has **no database**. The API skeletons above return empty data — to actually persist records, uploads, votes, or per-user state, back them with **Blob**. See the recipe below and [makers-storage → Blob as your backend](../makers-storage/references/blob.md). + +## Dynamic site with Blob persistence (guestbook / gallery / voting / save-state) + +The default shape for any generated site that needs a real backend but no relational data. Frontend → Cloud Function → Blob. No DB, no console setup. + +``` +my-app/ +├── index.html # Frontend (form + list) +├── script.js +├── cloud-functions/ +│ └── api/ +│ └── messages.js # GET lists entries, POST appends one +├── package.json # depends on @edgeone/pages-blob +``` + +**cloud-functions/api/messages.js** — one file per record (Pattern 1): +```javascript +import { getStore } from "@edgeone/pages-blob"; + +export async function onRequest({ request }) { + const store = getStore("guestbook"); + + if (request.method === "POST") { + const { name, text } = await request.json(); + const id = `${Date.now()}-${Math.round(Math.random() * 1e6)}`; + await store.setJSON(`entries/${id}.json`, { id, name, text, ts: Date.now() }); + return Response.json({ ok: true, id }); + } + + const { blobs } = await store.list({ prefix: "entries/" }); + const items = await Promise.all(blobs.map((b) => store.get(b.key, { type: "json" }))); + items.sort((a, b) => b.ts - a.ts); + return Response.json({ items }); +} +``` + +**index.html** frontend calls it like any API: +```javascript +await fetch('/api/messages', { // post + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ name, text }), +}); +const { items } = await fetch('/api/messages').then((r) => r.json()); // list +``` + +Swap the key scheme for other shapes: `users/.json` for save-state, `counts/