API 路由

插件可以为其管理 UI 和外部集成暴露 API 路由。路由挂载在 /_emdash/api/plugins/<slug>/<路由名> 下，并在沙盒运行时中执行，使用与钩子相同的 PluginContext。

本页介绍沙盒插件。原生插件的 API 表面相同，唯一区别是处理函数签名 — 参见原生插件。

定义路由

沙盒路由处理函数接受两个参数：(routeCtx, ctx)。

• routeCtx 携带与请求相关的数据：{ input, request, requestMeta }。
• ctx 是与钩子中相同的 PluginContext。

过滤索引内容字段

路由 URL

认证和 CSRF

插件路由默认需要认证。 公开路由使用 public: true。

已认证的调用者

在私有路由中，routeCtx.user 是已认证的用户。

将路由暴露为 MCP 工具

输入验证

input 接受 Zod 模式。

返回值

返回任何 JSON 可序列化的值。

错误

抛出错误以返回错误响应。

HTTP 方法

路由响应所有方法。在 routeCtx.request.method 上进行分支。

常见模式

通过 KV 管理设置

分页列表

外部 API 代理

从管理 UI 调用路由

import { usePluginAPI } from "@emdash-cms/admin";

从队列和定时处理函数调用路由

使用 emdash/middleware 中的 withEmDashRuntime()。

从外部调用路由

公开路由可以直接调用。私有路由需要会话凭据或 API 令牌。

路由上下文参考

interface SandboxedRouteContext {
	input: unknown;
	request: SandboxedRequest;
	requestMeta?: unknown;
	user?: UserInfo;
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	content?: ContentAccess;
	taxonomies?: TaxonomyAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	users?: UserAccess;
	email?: EmailAccess;
}