edgeone 1.6.28 → 1.6.30

package/README.md

@@ -210,6 +210,92 @@ edgeone makers env rm ENV_VAR_KEY
 
 ```
 
+## 5. Project Configuration
+
+The CLI reads your project config from the project root, in priority order:
+
+1. `edgeone.config.ts` — TypeScript programmatic config (recommended, requires CLI ≥ 1.7.0)
+2. `edgeone.json` / `edgeone.json5` — JSON config
+
+If `edgeone.config.ts` coexists with a JSON config, the TS file takes precedence (a warning is printed).
+
+### edgeone.config.ts
+
+```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' }],
+});
+```
+
+Install the package (devDependency) to get type checking / IDE completion:
+
+```bash
+npm install -D @edgeone/types
+```
+
+TypeScript configs are transpiled with esbuild at load time; the exported default
+object (or named `config` export) is used. The CLI is **self-contained** for config
+handling — the schema and `@edgeone/types/config` code ship inside the CLI binary,
+so you do NOT need `@edgeone/types` installed to *run* `edgeone compile/validate/schema`.
+Install it only for editor type support / your own TS usage.
+
+### Function handler types
+
+For typed `onRequest` handlers (cloud/node functions, agents, edge functions), use
+`@edgeone/types` (the `@vercel/node` equivalent):
+
+```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');
+};
+```
+
+`@edgeone/types` exports `CloudFunctionContext` / `AgentContext` / `EdgeFunctionContext`
+plus `CloudFunctionHandler` / `AgentHandler` / `EdgeFunctionHandler` / `EdgeMiddlewareHandler`.
+Config types live under the `@edgeone/types/config` subpath.
+
+### Config commands
+
+```bash
+# Compile edgeone.config.ts to edgeone.json
+edgeone compile
+
+# Validate the current config (prints warnings/errors, exit code 1 on errors)
+edgeone validate
+
+# Write edgeone.schema.json into the project for IDE validation of edgeone.json
+edgeone schema
+```
+
+To enable IDE validation for `edgeone.json`, add the `$schema` field. This is now added
+**automatically** when the CLI generates the config (`edgeone init`, `edgeone compile`),
+pointing at the hosted schema URL:
+
+```json
+{
+  "$schema": "https://cdnstatic.tencentcs.com/edgeone/pages/docs/edgeone.schema.json",
+  "outputDirectory": "dist"
+}
+```
+
+Run `edgeone schema` to also register a VS Code `json.schemas` association
+(`.vscode/settings.json`) so **manually created** `edgeone.json` files get hints without a
+`$schema` field. For offline use, reference the schema shipped with `@edgeone/types`
+(`node_modules/@edgeone/types/edgeone.schema.json`).
+
 ## References
 
 [Makers Introduction](https://pages.edgeone.ai/document/product-introduction) ｜ [Makers Functions](https://pages.edgeone.ai/document/pages-functions-overview)