From 1e595e7b90570e16087f1a730070c32ea9cd6c00 Mon Sep 17 00:00:00 2001 From: xiaban <980892894@qq.com> Date: Thu, 27 Aug 2026 11:08:08 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20@edgeone/types?= =?UTF-8?q?=20=E7=B1=BB=E5=9E=8B=E6=8A=80=E8=83=BD=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 1 + _meta.json | 3 +- codex/makers-agents.md | 2 +- codex/makers-cli.md | 20 +++ codex/makers-edge-functions.md | 3 + codex/makers-middleware.md | 3 + codex/makers-types.md | 124 ++++++++++++++++++ cursor/rules/makers-agents.mdc | 2 +- cursor/rules/makers-cli.mdc | 20 +++ cursor/rules/makers-edge-functions.mdc | 3 + cursor/rules/makers-middleware.mdc | 3 + cursor/rules/makers-types.mdc | 124 ++++++++++++++++++ skills/edgeone-makers-tools/SKILL.md | 1 + .../references/makers-agents/SKILL.md | 2 +- .../references/makers-cli/SKILL.md | 20 +++ .../references/node-functions.md | 3 + .../references/makers-edge-functions/SKILL.md | 3 + .../references/makers-middleware/SKILL.md | 3 + .../references/makers-types/SKILL.md | 124 ++++++++++++++++++ 19 files changed, 460 insertions(+), 4 deletions(-) create mode 100644 codex/makers-types.md create mode 100644 cursor/rules/makers-types.mdc create mode 100644 skills/edgeone-makers-tools/references/makers-types/SKILL.md diff --git a/SKILL.md b/SKILL.md index aeb684a..3f43829 100644 --- a/SKILL.md +++ b/SKILL.md @@ -24,6 +24,7 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | 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 | +| TypeScript types (@edgeone/types) — typed handlers & config | skills/makers-types/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 | diff --git a/_meta.json b/_meta.json index 7330a7d..7f12775 100644 --- a/_meta.json +++ b/_meta.json @@ -48,6 +48,7 @@ "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" + "skills/edgeone-makers-tools/references/makers-storage/references/kv.md", + "skills/edgeone-makers-tools/references/makers-types/SKILL.md" ] } diff --git a/codex/makers-agents.md b/codex/makers-agents.md index 0934883..b5632fd 100644 --- a/codex/makers-agents.md +++ b/codex/makers-agents.md @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/codex/makers-cli.md b/codex/makers-cli.md index 90437ca..dee7e4d 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -69,3 +69,23 @@ edgeone makers deploy edgeone makers env set WSA_API_KEY "your-key" edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ``` + +## Typed config (`edgeone.config.ts`) + +For type-checked project config, use `defineConfig` from `@edgeone/types/config` +(see the `makers-types` skill): + +```ts +// edgeone.config.ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + nodeVersion: '20', +}); +``` + +`edgeone compile` transpiles `edgeone.config.ts` → `edgeone.json`; `edgeone schema` +writes `edgeone.schema.json` locally for IDE validation. The CLI is self-contained — +no need to install `@edgeone/types` just to run these commands. diff --git a/codex/makers-edge-functions.md b/codex/makers-edge-functions.md index 98bcd31..08f7113 100644 --- a/codex/makers-edge-functions.md +++ b/codex/makers-edge-functions.md @@ -28,6 +28,9 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. +> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill +> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). + ## Basic function File: `edge-functions/api/hello.js` diff --git a/codex/makers-middleware.md b/codex/makers-middleware.md index c1d580e..e988dc0 100644 --- a/codex/makers-middleware.md +++ b/codex/makers-middleware.md @@ -20,6 +20,9 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. +> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill +> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). + ## Basic middleware File: `middleware.js` (project root) diff --git a/codex/makers-types.md b/codex/makers-types.md new file mode 100644 index 0000000..a24f631 --- /dev/null +++ b/codex/makers-types.md @@ -0,0 +1,124 @@ +--- +name: edgeone-makers-types +description: >- + TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. + Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project + config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts + handler files, edgeone.config.ts, or when the user needs type safety / + autocompletion for handlers or config on EdgeOne Makers. +pathPatterns: + - "**/*.ts" + - "**/*.tsx" + - "**/edgeone.config.ts" +metadata: + author: edgeone + version: "1.0.0" +--- + +# TypeScript types (@edgeone/types) + +`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed +handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. +Install it as a devDependency for editor autocompletion and type safety. + +## Install / 安装 + +```bash +npm install -D @edgeone/types +``` + +> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use +> `@edgeone/ef-types` (the default in CLI init templates). +> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 +> `@edgeone/ef-types`（CLI init 模板默认配置）。 + +## Handler types / 函数 handler 类型 + +### Cloud / Node functions + +```ts +// cloud-functions/api/search.ts +import type { CloudFunctionHandler } from '@edgeone/types'; + +export const onRequest: CloudFunctionHandler = async (context) => { + const query = context.request?.query; + return new Response(JSON.stringify({ query, region: context.server.region })); +}; +``` + +Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. + +### Agent + +```ts +// agents/chat.ts +import type { AgentHandler } from '@edgeone/types'; + +export const onRequest: AgentHandler = async (context) => { + await context.store.appendMessage({ + conversationId: context.conversation_id, + role: 'user', + content: 'hello', + }); + return new Response('ok'); +}; +``` + +### Edge functions + +```ts +// edge-functions/api/hello.ts +import type { EdgeFunctionHandler } from '@edgeone/types'; + +export const onRequest: EdgeFunctionHandler = (context) => { + return new Response(JSON.stringify({ params: context.params, eo: context.eo })); +}; +``` + +### Edge middleware + +```ts +// middleware.ts (project root) +import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; + +export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; + +export const middleware: EdgeMiddlewareHandler = async (context) => { + return new Response('next', { headers: { 'x-middleware-next': '1' } }); +}; +``` + +### Types only + +```ts +import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; +``` + +## Config types / 配置类型（`@edgeone/types/config` subpath） + +Type-safe `edgeone.config.ts` with autocompletion: + +```ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + installCommand: 'npm install', + nodeVersion: '20', + schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], +}); +``` + +- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) +- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input +- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs + auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy + and register the VS Code association. + +## Versioned subpaths / 版本化子路径 + +- `@edgeone/types` — current function types / 函数类型 +- `@edgeone/types/config` — config types + schema / 配置类型 + schema +- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 +- `@edgeone/types/v1/types` — types only / 仅类型 diff --git a/cursor/rules/makers-agents.mdc b/cursor/rules/makers-agents.mdc index 0934883..b5632fd 100644 --- a/cursor/rules/makers-agents.mdc +++ b/cursor/rules/makers-agents.mdc @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/cursor/rules/makers-cli.mdc b/cursor/rules/makers-cli.mdc index 90437ca..dee7e4d 100644 --- a/cursor/rules/makers-cli.mdc +++ b/cursor/rules/makers-cli.mdc @@ -69,3 +69,23 @@ edgeone makers deploy edgeone makers env set WSA_API_KEY "your-key" edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ``` + +## Typed config (`edgeone.config.ts`) + +For type-checked project config, use `defineConfig` from `@edgeone/types/config` +(see the `makers-types` skill): + +```ts +// edgeone.config.ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + nodeVersion: '20', +}); +``` + +`edgeone compile` transpiles `edgeone.config.ts` → `edgeone.json`; `edgeone schema` +writes `edgeone.schema.json` locally for IDE validation. The CLI is self-contained — +no need to install `@edgeone/types` just to run these commands. diff --git a/cursor/rules/makers-edge-functions.mdc b/cursor/rules/makers-edge-functions.mdc index 98bcd31..08f7113 100644 --- a/cursor/rules/makers-edge-functions.mdc +++ b/cursor/rules/makers-edge-functions.mdc @@ -28,6 +28,9 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. +> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill +> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). + ## Basic function File: `edge-functions/api/hello.js` diff --git a/cursor/rules/makers-middleware.mdc b/cursor/rules/makers-middleware.mdc index c1d580e..e988dc0 100644 --- a/cursor/rules/makers-middleware.mdc +++ b/cursor/rules/makers-middleware.mdc @@ -20,6 +20,9 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. +> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill +> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). + ## Basic middleware File: `middleware.js` (project root) diff --git a/cursor/rules/makers-types.mdc b/cursor/rules/makers-types.mdc new file mode 100644 index 0000000..a24f631 --- /dev/null +++ b/cursor/rules/makers-types.mdc @@ -0,0 +1,124 @@ +--- +name: edgeone-makers-types +description: >- + TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. + Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project + config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts + handler files, edgeone.config.ts, or when the user needs type safety / + autocompletion for handlers or config on EdgeOne Makers. +pathPatterns: + - "**/*.ts" + - "**/*.tsx" + - "**/edgeone.config.ts" +metadata: + author: edgeone + version: "1.0.0" +--- + +# TypeScript types (@edgeone/types) + +`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed +handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. +Install it as a devDependency for editor autocompletion and type safety. + +## Install / 安装 + +```bash +npm install -D @edgeone/types +``` + +> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use +> `@edgeone/ef-types` (the default in CLI init templates). +> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 +> `@edgeone/ef-types`（CLI init 模板默认配置）。 + +## Handler types / 函数 handler 类型 + +### Cloud / Node functions + +```ts +// cloud-functions/api/search.ts +import type { CloudFunctionHandler } from '@edgeone/types'; + +export const onRequest: CloudFunctionHandler = async (context) => { + const query = context.request?.query; + return new Response(JSON.stringify({ query, region: context.server.region })); +}; +``` + +Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. + +### Agent + +```ts +// agents/chat.ts +import type { AgentHandler } from '@edgeone/types'; + +export const onRequest: AgentHandler = async (context) => { + await context.store.appendMessage({ + conversationId: context.conversation_id, + role: 'user', + content: 'hello', + }); + return new Response('ok'); +}; +``` + +### Edge functions + +```ts +// edge-functions/api/hello.ts +import type { EdgeFunctionHandler } from '@edgeone/types'; + +export const onRequest: EdgeFunctionHandler = (context) => { + return new Response(JSON.stringify({ params: context.params, eo: context.eo })); +}; +``` + +### Edge middleware + +```ts +// middleware.ts (project root) +import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; + +export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; + +export const middleware: EdgeMiddlewareHandler = async (context) => { + return new Response('next', { headers: { 'x-middleware-next': '1' } }); +}; +``` + +### Types only + +```ts +import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; +``` + +## Config types / 配置类型（`@edgeone/types/config` subpath） + +Type-safe `edgeone.config.ts` with autocompletion: + +```ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + installCommand: 'npm install', + nodeVersion: '20', + schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], +}); +``` + +- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) +- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input +- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs + auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy + and register the VS Code association. + +## Versioned subpaths / 版本化子路径 + +- `@edgeone/types` — current function types / 函数类型 +- `@edgeone/types/config` — config types + schema / 配置类型 + schema +- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 +- `@edgeone/types/v1/types` — types only / 仅类型 diff --git a/skills/edgeone-makers-tools/SKILL.md b/skills/edgeone-makers-tools/SKILL.md index e909fd0..f4ef4ca 100644 --- a/skills/edgeone-makers-tools/SKILL.md +++ b/skills/edgeone-makers-tools/SKILL.md @@ -25,6 +25,7 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | Deploy project to EdgeOne | references/makers-deploy/SKILL.md | | Edge Functions (V8 lightweight functions) | references/makers-edge-functions/SKILL.md | | Cloud Functions (Node.js / Go / Python APIs) | references/makers-cloud-functions/SKILL.md | +| TypeScript types (@edgeone/types) — typed handlers & config | references/makers-types/SKILL.md | | KV + Blob Storage | references/makers-storage/SKILL.md | | Persist dynamic data for a site (messages, uploads, votes, save-state) — **no database; use Blob** | references/makers-storage/SKILL.md | | Middleware (auth, rewrites, routing) | references/makers-middleware/SKILL.md | diff --git a/skills/edgeone-makers-tools/references/makers-agents/SKILL.md b/skills/edgeone-makers-tools/references/makers-agents/SKILL.md index 0934883..b5632fd 100644 --- a/skills/edgeone-makers-tools/references/makers-agents/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-agents/SKILL.md @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/skills/edgeone-makers-tools/references/makers-cli/SKILL.md b/skills/edgeone-makers-tools/references/makers-cli/SKILL.md index 90437ca..dee7e4d 100644 --- a/skills/edgeone-makers-tools/references/makers-cli/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-cli/SKILL.md @@ -69,3 +69,23 @@ edgeone makers deploy edgeone makers env set WSA_API_KEY "your-key" edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ``` + +## Typed config (`edgeone.config.ts`) + +For type-checked project config, use `defineConfig` from `@edgeone/types/config` +(see the `makers-types` skill): + +```ts +// edgeone.config.ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + nodeVersion: '20', +}); +``` + +`edgeone compile` transpiles `edgeone.config.ts` → `edgeone.json`; `edgeone schema` +writes `edgeone.schema.json` locally for IDE validation. The CLI is self-contained — +no need to install `@edgeone/types` just to run these commands. diff --git a/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md b/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md index b9f08da..63e0146 100644 --- a/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md +++ b/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md @@ -19,6 +19,9 @@ Node.js v20.x runtime functions under `cloud-functions/`. Full npm ecosystem sup > **Runtime:** Node.js v20.x — supports ES modules, full npm ecosystem, and WebSocket. +> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill +> (`npm install -D @edgeone/types`, then `export const onRequest: CloudFunctionHandler = ...`). + ## Basic function File: `cloud-functions/api/data.js` diff --git a/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md b/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md index 98bcd31..08f7113 100644 --- a/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md @@ -28,6 +28,9 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. +> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill +> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). + ## Basic function File: `edge-functions/api/hello.js` diff --git a/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md b/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md index c1d580e..e988dc0 100644 --- a/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md @@ -20,6 +20,9 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. +> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill +> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). + ## Basic middleware File: `middleware.js` (project root) diff --git a/skills/edgeone-makers-tools/references/makers-types/SKILL.md b/skills/edgeone-makers-tools/references/makers-types/SKILL.md new file mode 100644 index 0000000..a24f631 --- /dev/null +++ b/skills/edgeone-makers-tools/references/makers-types/SKILL.md @@ -0,0 +1,124 @@ +--- +name: edgeone-makers-types +description: >- + TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. + Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project + config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts + handler files, edgeone.config.ts, or when the user needs type safety / + autocompletion for handlers or config on EdgeOne Makers. +pathPatterns: + - "**/*.ts" + - "**/*.tsx" + - "**/edgeone.config.ts" +metadata: + author: edgeone + version: "1.0.0" +--- + +# TypeScript types (@edgeone/types) + +`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed +handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. +Install it as a devDependency for editor autocompletion and type safety. + +## Install / 安装 + +```bash +npm install -D @edgeone/types +``` + +> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use +> `@edgeone/ef-types` (the default in CLI init templates). +> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 +> `@edgeone/ef-types`（CLI init 模板默认配置）。 + +## Handler types / 函数 handler 类型 + +### Cloud / Node functions + +```ts +// cloud-functions/api/search.ts +import type { CloudFunctionHandler } from '@edgeone/types'; + +export const onRequest: CloudFunctionHandler = async (context) => { + const query = context.request?.query; + return new Response(JSON.stringify({ query, region: context.server.region })); +}; +``` + +Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. + +### Agent + +```ts +// agents/chat.ts +import type { AgentHandler } from '@edgeone/types'; + +export const onRequest: AgentHandler = async (context) => { + await context.store.appendMessage({ + conversationId: context.conversation_id, + role: 'user', + content: 'hello', + }); + return new Response('ok'); +}; +``` + +### Edge functions + +```ts +// edge-functions/api/hello.ts +import type { EdgeFunctionHandler } from '@edgeone/types'; + +export const onRequest: EdgeFunctionHandler = (context) => { + return new Response(JSON.stringify({ params: context.params, eo: context.eo })); +}; +``` + +### Edge middleware + +```ts +// middleware.ts (project root) +import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; + +export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; + +export const middleware: EdgeMiddlewareHandler = async (context) => { + return new Response('next', { headers: { 'x-middleware-next': '1' } }); +}; +``` + +### Types only + +```ts +import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; +``` + +## Config types / 配置类型（`@edgeone/types/config` subpath） + +Type-safe `edgeone.config.ts` with autocompletion: + +```ts +import { defineConfig } from '@edgeone/types/config'; + +export default defineConfig({ + outputDirectory: 'dist', + buildCommand: 'npm run build', + installCommand: 'npm install', + nodeVersion: '20', + schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], +}); +``` + +- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) +- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input +- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs + auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy + and register the VS Code association. + +## Versioned subpaths / 版本化子路径 + +- `@edgeone/types` — current function types / 函数类型 +- `@edgeone/types/config` — config types + schema / 配置类型 + schema +- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 +- `@edgeone/types/v1/types` — types only / 仅类型 From d9719be17d5fe2442c0063b32c29d3c6940ca660 Mon Sep 17 00:00:00 2001 From: xiaban <980892894@qq.com> Date: Fri, 28 Aug 2026 14:43:52 +0800 Subject: [PATCH 2/2] refactor(skills): drop makers-types skill, keep only AI-relevant config guidance --- SKILL.md | 1 - _meta.json | 3 +- codex/makers-agents.md | 2 +- codex/makers-cli.md | 3 +- codex/makers-edge-functions.md | 3 - codex/makers-middleware.md | 3 - codex/makers-types.md | 124 ------------------ cursor/rules/makers-agents.mdc | 2 +- cursor/rules/makers-cli.mdc | 3 +- cursor/rules/makers-edge-functions.mdc | 3 - cursor/rules/makers-middleware.mdc | 3 - cursor/rules/makers-types.mdc | 124 ------------------ skills/edgeone-makers-tools/SKILL.md | 1 - .../references/makers-agents/SKILL.md | 2 +- .../references/makers-cli/SKILL.md | 3 +- .../references/node-functions.md | 3 - .../references/makers-edge-functions/SKILL.md | 3 - .../references/makers-middleware/SKILL.md | 3 - .../references/makers-types/SKILL.md | 124 ------------------ 19 files changed, 7 insertions(+), 406 deletions(-) delete mode 100644 codex/makers-types.md delete mode 100644 cursor/rules/makers-types.mdc delete mode 100644 skills/edgeone-makers-tools/references/makers-types/SKILL.md diff --git a/SKILL.md b/SKILL.md index 3f43829..aeb684a 100644 --- a/SKILL.md +++ b/SKILL.md @@ -24,7 +24,6 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | 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 | -| TypeScript types (@edgeone/types) — typed handlers & config | skills/makers-types/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 | diff --git a/_meta.json b/_meta.json index 7f12775..7330a7d 100644 --- a/_meta.json +++ b/_meta.json @@ -48,7 +48,6 @@ "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", - "skills/edgeone-makers-tools/references/makers-types/SKILL.md" + "skills/edgeone-makers-tools/references/makers-storage/references/kv.md" ] } diff --git a/codex/makers-agents.md b/codex/makers-agents.md index b5632fd..0934883 100644 --- a/codex/makers-agents.md +++ b/codex/makers-agents.md @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/codex/makers-cli.md b/codex/makers-cli.md index dee7e4d..b570ff7 100644 --- a/codex/makers-cli.md +++ b/codex/makers-cli.md @@ -72,8 +72,7 @@ edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ## Typed config (`edgeone.config.ts`) -For type-checked project config, use `defineConfig` from `@edgeone/types/config` -(see the `makers-types` skill): +Write `edgeone.config.ts` with `defineConfig` from `@edgeone/types/config`: ```ts // edgeone.config.ts diff --git a/codex/makers-edge-functions.md b/codex/makers-edge-functions.md index 08f7113..98bcd31 100644 --- a/codex/makers-edge-functions.md +++ b/codex/makers-edge-functions.md @@ -28,9 +28,6 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. -> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill -> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). - ## Basic function File: `edge-functions/api/hello.js` diff --git a/codex/makers-middleware.md b/codex/makers-middleware.md index e988dc0..c1d580e 100644 --- a/codex/makers-middleware.md +++ b/codex/makers-middleware.md @@ -20,9 +20,6 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. -> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill -> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). - ## Basic middleware File: `middleware.js` (project root) diff --git a/codex/makers-types.md b/codex/makers-types.md deleted file mode 100644 index a24f631..0000000 --- a/codex/makers-types.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -name: edgeone-makers-types -description: >- - TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. - Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project - config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts - handler files, edgeone.config.ts, or when the user needs type safety / - autocompletion for handlers or config on EdgeOne Makers. -pathPatterns: - - "**/*.ts" - - "**/*.tsx" - - "**/edgeone.config.ts" -metadata: - author: edgeone - version: "1.0.0" ---- - -# TypeScript types (@edgeone/types) - -`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed -handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. -Install it as a devDependency for editor autocompletion and type safety. - -## Install / 安装 - -```bash -npm install -D @edgeone/types -``` - -> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use -> `@edgeone/ef-types` (the default in CLI init templates). -> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 -> `@edgeone/ef-types`（CLI init 模板默认配置）。 - -## Handler types / 函数 handler 类型 - -### Cloud / Node functions - -```ts -// cloud-functions/api/search.ts -import type { CloudFunctionHandler } from '@edgeone/types'; - -export const onRequest: CloudFunctionHandler = async (context) => { - const query = context.request?.query; - return new Response(JSON.stringify({ query, region: context.server.region })); -}; -``` - -Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. - -### Agent - -```ts -// agents/chat.ts -import type { AgentHandler } from '@edgeone/types'; - -export const onRequest: AgentHandler = async (context) => { - await context.store.appendMessage({ - conversationId: context.conversation_id, - role: 'user', - content: 'hello', - }); - return new Response('ok'); -}; -``` - -### Edge functions - -```ts -// edge-functions/api/hello.ts -import type { EdgeFunctionHandler } from '@edgeone/types'; - -export const onRequest: EdgeFunctionHandler = (context) => { - return new Response(JSON.stringify({ params: context.params, eo: context.eo })); -}; -``` - -### Edge middleware - -```ts -// middleware.ts (project root) -import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; - -export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; - -export const middleware: EdgeMiddlewareHandler = async (context) => { - return new Response('next', { headers: { 'x-middleware-next': '1' } }); -}; -``` - -### Types only - -```ts -import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; -``` - -## Config types / 配置类型（`@edgeone/types/config` subpath） - -Type-safe `edgeone.config.ts` with autocompletion: - -```ts -import { defineConfig } from '@edgeone/types/config'; - -export default defineConfig({ - outputDirectory: 'dist', - buildCommand: 'npm run build', - installCommand: 'npm install', - nodeVersion: '20', - schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], -}); -``` - -- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) -- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input -- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs - auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy - and register the VS Code association. - -## Versioned subpaths / 版本化子路径 - -- `@edgeone/types` — current function types / 函数类型 -- `@edgeone/types/config` — config types + schema / 配置类型 + schema -- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 -- `@edgeone/types/v1/types` — types only / 仅类型 diff --git a/cursor/rules/makers-agents.mdc b/cursor/rules/makers-agents.mdc index b5632fd..0934883 100644 --- a/cursor/rules/makers-agents.mdc +++ b/cursor/rules/makers-agents.mdc @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/cursor/rules/makers-cli.mdc b/cursor/rules/makers-cli.mdc index dee7e4d..b570ff7 100644 --- a/cursor/rules/makers-cli.mdc +++ b/cursor/rules/makers-cli.mdc @@ -72,8 +72,7 @@ edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ## Typed config (`edgeone.config.ts`) -For type-checked project config, use `defineConfig` from `@edgeone/types/config` -(see the `makers-types` skill): +Write `edgeone.config.ts` with `defineConfig` from `@edgeone/types/config`: ```ts // edgeone.config.ts diff --git a/cursor/rules/makers-edge-functions.mdc b/cursor/rules/makers-edge-functions.mdc index 08f7113..98bcd31 100644 --- a/cursor/rules/makers-edge-functions.mdc +++ b/cursor/rules/makers-edge-functions.mdc @@ -28,9 +28,6 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. -> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill -> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). - ## Basic function File: `edge-functions/api/hello.js` diff --git a/cursor/rules/makers-middleware.mdc b/cursor/rules/makers-middleware.mdc index e988dc0..c1d580e 100644 --- a/cursor/rules/makers-middleware.mdc +++ b/cursor/rules/makers-middleware.mdc @@ -20,9 +20,6 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. -> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill -> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). - ## Basic middleware File: `middleware.js` (project root) diff --git a/cursor/rules/makers-types.mdc b/cursor/rules/makers-types.mdc deleted file mode 100644 index a24f631..0000000 --- a/cursor/rules/makers-types.mdc +++ /dev/null @@ -1,124 +0,0 @@ ---- -name: edgeone-makers-types -description: >- - TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. - Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project - config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts - handler files, edgeone.config.ts, or when the user needs type safety / - autocompletion for handlers or config on EdgeOne Makers. -pathPatterns: - - "**/*.ts" - - "**/*.tsx" - - "**/edgeone.config.ts" -metadata: - author: edgeone - version: "1.0.0" ---- - -# TypeScript types (@edgeone/types) - -`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed -handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. -Install it as a devDependency for editor autocompletion and type safety. - -## Install / 安装 - -```bash -npm install -D @edgeone/types -``` - -> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use -> `@edgeone/ef-types` (the default in CLI init templates). -> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 -> `@edgeone/ef-types`（CLI init 模板默认配置）。 - -## Handler types / 函数 handler 类型 - -### Cloud / Node functions - -```ts -// cloud-functions/api/search.ts -import type { CloudFunctionHandler } from '@edgeone/types'; - -export const onRequest: CloudFunctionHandler = async (context) => { - const query = context.request?.query; - return new Response(JSON.stringify({ query, region: context.server.region })); -}; -``` - -Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. - -### Agent - -```ts -// agents/chat.ts -import type { AgentHandler } from '@edgeone/types'; - -export const onRequest: AgentHandler = async (context) => { - await context.store.appendMessage({ - conversationId: context.conversation_id, - role: 'user', - content: 'hello', - }); - return new Response('ok'); -}; -``` - -### Edge functions - -```ts -// edge-functions/api/hello.ts -import type { EdgeFunctionHandler } from '@edgeone/types'; - -export const onRequest: EdgeFunctionHandler = (context) => { - return new Response(JSON.stringify({ params: context.params, eo: context.eo })); -}; -``` - -### Edge middleware - -```ts -// middleware.ts (project root) -import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; - -export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; - -export const middleware: EdgeMiddlewareHandler = async (context) => { - return new Response('next', { headers: { 'x-middleware-next': '1' } }); -}; -``` - -### Types only - -```ts -import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; -``` - -## Config types / 配置类型（`@edgeone/types/config` subpath） - -Type-safe `edgeone.config.ts` with autocompletion: - -```ts -import { defineConfig } from '@edgeone/types/config'; - -export default defineConfig({ - outputDirectory: 'dist', - buildCommand: 'npm run build', - installCommand: 'npm install', - nodeVersion: '20', - schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], -}); -``` - -- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) -- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input -- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs - auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy - and register the VS Code association. - -## Versioned subpaths / 版本化子路径 - -- `@edgeone/types` — current function types / 函数类型 -- `@edgeone/types/config` — config types + schema / 配置类型 + schema -- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 -- `@edgeone/types/v1/types` — types only / 仅类型 diff --git a/skills/edgeone-makers-tools/SKILL.md b/skills/edgeone-makers-tools/SKILL.md index f4ef4ca..e909fd0 100644 --- a/skills/edgeone-makers-tools/SKILL.md +++ b/skills/edgeone-makers-tools/SKILL.md @@ -25,7 +25,6 @@ When you need EdgeOne Makers platform development guidance, read the matching Sk | Deploy project to EdgeOne | references/makers-deploy/SKILL.md | | Edge Functions (V8 lightweight functions) | references/makers-edge-functions/SKILL.md | | Cloud Functions (Node.js / Go / Python APIs) | references/makers-cloud-functions/SKILL.md | -| TypeScript types (@edgeone/types) — typed handlers & config | references/makers-types/SKILL.md | | KV + Blob Storage | references/makers-storage/SKILL.md | | Persist dynamic data for a site (messages, uploads, votes, save-state) — **no database; use Blob** | references/makers-storage/SKILL.md | | Middleware (auth, rewrites, routing) | references/makers-middleware/SKILL.md | diff --git a/skills/edgeone-makers-tools/references/makers-agents/SKILL.md b/skills/edgeone-makers-tools/references/makers-agents/SKILL.md index b5632fd..0934883 100644 --- a/skills/edgeone-makers-tools/references/makers-agents/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-agents/SKILL.md @@ -66,7 +66,7 @@ This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, Open ## ⛔ Critical Rules (never skip) 1. **File-based routing is automatic.** `agents//index.ts` or `agents/.ts` becomes `POST /`. Never hand-edit `.edgeone/agent-node/config.json`. -2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)` — for type safety use `AgentHandler` from `@edgeone/types` (see `makers-types` skill). Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. +2. **Entry signature is fixed.** TS: `export async function onRequest(context: any)`. Python: `async def handler(ctx):`. Method-specific variants (`onRequestPost`, `onRequestGet`, etc.) also work for TS. 3. **Read env via `context.env`, never `process.env` / `os.environ`.** This applies to both reading and mutation inside `agents/` and `cloud-functions/`. Frontend code (`app/`, `src/`) is unaffected. 4. **Headers are plain objects, not the Web `Headers` API.** Use `context.request.headers['x-custom-header']`, never `.get('x')`. 5. **Conversation ID contract.** AI endpoints (`/chat`, `/outline`, etc.) MUST receive the `makers-conversation-id` HTTP header from the frontend. The `/stop` endpoint takes a `conversation_id` in the request body to identify which running conversation to cancel. diff --git a/skills/edgeone-makers-tools/references/makers-cli/SKILL.md b/skills/edgeone-makers-tools/references/makers-cli/SKILL.md index dee7e4d..b570ff7 100644 --- a/skills/edgeone-makers-tools/references/makers-cli/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-cli/SKILL.md @@ -72,8 +72,7 @@ edgeone makers env set SUPABASE_URL "https://xxx.supabase.co" ## Typed config (`edgeone.config.ts`) -For type-checked project config, use `defineConfig` from `@edgeone/types/config` -(see the `makers-types` skill): +Write `edgeone.config.ts` with `defineConfig` from `@edgeone/types/config`: ```ts // edgeone.config.ts diff --git a/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md b/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md index 63e0146..b9f08da 100644 --- a/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md +++ b/skills/edgeone-makers-tools/references/makers-cloud-functions/references/node-functions.md @@ -19,9 +19,6 @@ Node.js v20.x runtime functions under `cloud-functions/`. Full npm ecosystem sup > **Runtime:** Node.js v20.x — supports ES modules, full npm ecosystem, and WebSocket. -> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill -> (`npm install -D @edgeone/types`, then `export const onRequest: CloudFunctionHandler = ...`). - ## Basic function File: `cloud-functions/api/data.js` diff --git a/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md b/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md index 08f7113..98bcd31 100644 --- a/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-edge-functions/SKILL.md @@ -28,9 +28,6 @@ V8-based lightweight functions running at the edge. Ideal for simple APIs, KV st > > ⚠️ `Response.json()` is **NOT available** in this V8 runtime. Always use `new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })` instead. -> 💡 **TypeScript**: typed handlers via `@edgeone/types` — see `makers-types` skill -> (`EdgeFunctionHandler` for functions, `EdgeMiddlewareHandler`/`EdgeMiddlewareConfig` for middleware). - ## Basic function File: `edge-functions/api/hello.js` diff --git a/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md b/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md index e988dc0..c1d580e 100644 --- a/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md +++ b/skills/edgeone-makers-tools/references/makers-middleware/SKILL.md @@ -20,9 +20,6 @@ Lightweight request interception running at the edge (V8 runtime). Use for redir > ⚠️ **Framework projects (Next.js, Nuxt, etc.)**: Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js `middleware.ts` with `NextRequest`/`NextResponse`). The patterns below are for non-framework or pure static projects only. -> 💡 **TypeScript**: typed middleware via `@edgeone/types` — see `makers-types` skill -> (`EdgeMiddlewareHandler` + `EdgeMiddlewareConfig`). - ## Basic middleware File: `middleware.js` (project root) diff --git a/skills/edgeone-makers-tools/references/makers-types/SKILL.md b/skills/edgeone-makers-tools/references/makers-types/SKILL.md deleted file mode 100644 index a24f631..0000000 --- a/skills/edgeone-makers-tools/references/makers-types/SKILL.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -name: edgeone-makers-types -description: >- - TypeScript types for EdgeOne Makers — the official `@edgeone/types` package. - Typed handler signatures (Agent / Cloud / Edge / Middleware) and typed project - config (`edgeone.config.ts` via `@edgeone/types/config`). Use when writing .ts - handler files, edgeone.config.ts, or when the user needs type safety / - autocompletion for handlers or config on EdgeOne Makers. -pathPatterns: - - "**/*.ts" - - "**/*.tsx" - - "**/edgeone.config.ts" -metadata: - author: edgeone - version: "1.0.0" ---- - -# TypeScript types (@edgeone/types) - -`@edgeone/types` is the official TypeScript types package for EdgeOne Makers — typed -handler signatures (Agent / Cloud / Edge / Middleware) plus project config types. -Install it as a devDependency for editor autocompletion and type safety. - -## Install / 安装 - -```bash -npm install -D @edgeone/types -``` - -> Requires `Request` / `Response` types: include `"DOM"` in tsconfig `lib`, or use -> `@edgeone/ef-types` (the default in CLI init templates). -> 需要环境里有 `Request` / `Response` 类型：tsconfig `lib` 含 `"DOM"`，或使用 -> `@edgeone/ef-types`（CLI init 模板默认配置）。 - -## Handler types / 函数 handler 类型 - -### Cloud / Node functions - -```ts -// cloud-functions/api/search.ts -import type { CloudFunctionHandler } from '@edgeone/types'; - -export const onRequest: CloudFunctionHandler = async (context) => { - const query = context.request?.query; - return new Response(JSON.stringify({ query, region: context.server.region })); -}; -``` - -Supports method-level handlers `onRequestGet/Post/Put/Delete/Patch/Head/Options` with the same signature. - -### Agent - -```ts -// agents/chat.ts -import type { AgentHandler } from '@edgeone/types'; - -export const onRequest: AgentHandler = async (context) => { - await context.store.appendMessage({ - conversationId: context.conversation_id, - role: 'user', - content: 'hello', - }); - return new Response('ok'); -}; -``` - -### Edge functions - -```ts -// edge-functions/api/hello.ts -import type { EdgeFunctionHandler } from '@edgeone/types'; - -export const onRequest: EdgeFunctionHandler = (context) => { - return new Response(JSON.stringify({ params: context.params, eo: context.eo })); -}; -``` - -### Edge middleware - -```ts -// middleware.ts (project root) -import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types'; - -export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] }; - -export const middleware: EdgeMiddlewareHandler = async (context) => { - return new Response('next', { headers: { 'x-middleware-next': '1' } }); -}; -``` - -### Types only - -```ts -import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types'; -``` - -## Config types / 配置类型（`@edgeone/types/config` subpath） - -Type-safe `edgeone.config.ts` with autocompletion: - -```ts -import { defineConfig } from '@edgeone/types/config'; - -export default defineConfig({ - outputDirectory: 'dist', - buildCommand: 'npm run build', - installCommand: 'npm install', - nodeVersion: '20', - schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }], -}); -``` - -- `defineConfig(config)` — typed identity helper for `edgeone.config.ts` (IDE type checking/autocompletion) -- `validateConfig(input)` — strict validation (`tefConfigSchema.safeParse`); fails on invalid input -- `edgeone.schema.json` — JSON Schema generated from the zod schema. CLI-generated configs - auto-inject the hosted `$schema` URL; offline use `edgeone schema` to write a local copy - and register the VS Code association. - -## Versioned subpaths / 版本化子路径 - -- `@edgeone/types` — current function types / 函数类型 -- `@edgeone/types/config` — config types + schema / 配置类型 + schema -- `@edgeone/types/v1` — versioned entry for function types / 函数类型版本化入口 -- `@edgeone/types/v1/types` — types only / 仅类型