@landmark-plugin/sdk

Landmark 插件的唯一业务开发 SDK。后端使用 ./server，同源前端使用 ./client；另提供 ./schema、./manifest 和 ./contracts 专用入口。包不暴露任何宿主内部源码。

服务端

import { defineServerPlugin, response, schema } from "@landmark-plugin/sdk/server";

export default defineServerPlugin({
    apiVersion: 1,
    async setup(ctx) {
        await ctx.router.post({
            path: "/items",
            auth: { mode: "required", permissions: ["content:write"] },
            bodySchema: schema.object({ title: schema.string().min(1).max(200) }),
            responseSchema: schema.object({ id: schema.string(), title: schema.string() }),
            async handler(request) {
                const entity = await ctx.pluginDataEngine.entity("item");
                const item = await entity.create(request.body);
                return response.json(item, { status: 201 });
            },
        });
    },
});

服务端 Context 包含 router、upload、core、pluginDataEngine、service、settings、queue、tasks、hooks、socket、fs、adapters、payments、authProviders、modeling、telemetry、log 和 scope。

所有能力通过宿主 bridge 调用：

• Host 错误统一转换为 PluginError。
• Context dispose 后拒绝新的能力调用。
• 路由只接收一个可序列化 request DTO，并必须返回 response.*()。
• 路由可执行 body/query/params/response Schema。
• service.client(contract) 自动校验方法参数和返回值。
• pluginDataEngine.defineEntity() 在跨进程前校验实体契约。
• scope 以逆序执行清理函数，并保证只执行一次。

客户端

import { defineClientPlugin } from "@landmark-plugin/sdk/client";

export default defineClientPlugin({
    apiVersion: 1,
    setup(ctx) {
        const unregister = ctx.ui.pageModule.register({
            id: "example.home",
            component: () => import("./HomePage.vue"),
        });
        ctx.scope.onDispose(unregister);
    },
});

客户端 Context 包含 http、api、upload、socket、auth、i18n、events、ui、navigation、editor、constants、errors、log 和 scope。ctx.upload(File) 会把浏览器文件直接发送给宿主上传网关，并提供批量、进度、取消、策略、访问地址和删除能力。缺失能力会抛出 PLUGIN_CLIENT_CAPABILITY_UNAVAILABLE，而不是产生含义不清楚的 is not a function。

上下文生命周期 API：

• createClientPluginContext()：由宿主和测试工具创建上下文。
• providePluginContext()：设置当前同步挂载上下文并支持嵌套恢复。
• registerPluginContext()：按 pluginId 注册长期上下文，重复注册会失败。
• usePluginContext()：按 ID 或当前上下文读取。
• hasPluginContext()、listPluginContexts()：检查当前注册状态。
• assertClientPluginContext()：运行时验证外部上下文。

专用入口

• @landmark-plugin/sdk/schema：Schema 构造、parse/safeParse、JSON Schema 转换和校验错误。
• @landmark-plugin/sdk/manifest：Manifest V1 类型和校验器。
• @landmark-plugin/sdk/contracts：完整底层协议；主要供高级工具使用。

边界保证

SDK 不提供 Express req/res、宿主数据库、宿主管理器、宿主文件路径或进程内对象。后端插件在 process/container 中获得相同的公开 Context；前端始终使用宿主提供的同源客户端能力。