feat: 添加 @edgeone/types 类型技能引用

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 |

_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"
   ]
 }

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/<name>/index.ts` or `agents/<name>.ts` becomes `POST /<name>`. 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.

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.

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`

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)

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 / 仅类型

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/<name>/index.ts` or `agents/<name>.ts` becomes `POST /<name>`. 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.

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.

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`

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)

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 / 仅类型

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 |

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/<name>/index.ts` or `agents/<name>.ts` becomes `POST /<name>`. 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.