@airongrong/plugin-api 0.0.0-stage → 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AiToEarn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @airongrong/plugin-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AiToEarn 插件 SDK：插件作者唯一需要依赖的 npm 包。纯类型 + 少量校验逻辑，零 NestJS / 零宿主内部依赖。
+
+```bash
+pnpm add @airongrong/plugin-api
+```
+
+## 你能拿到什么
+
+| 模块 | 内容 |
+| --- | --- |
+| `plugin-manifest` | `pluginManifestSchema`（zod）、`verifyManifest()`、`PluginType`、`Capability`、`PluginHookName`、`pluginManifestJsonSchema` |
+| `plugin-module` | `AdapterPluginModule` / `HookPluginModule` / `PluginActivate` 契约 |
+| `channel-adapter` | `ChannelAdapter`、`ChannelMeta` —— 渠道适配器接口 |
+| `host-services` | `HostServices`：宿主授予的 http / log / secrets / storage / kv 能力 |
+| `post-draft` | `PostDraft`、`DraftBlock`、`PublishResult`、`ValidationIssue` —— 内容草稿与发布结果的统一模型 |
+| `plugin-error-code` | `PluginErrorCode`（AIT-PL-001~008）、`AgentErrorCode`（AIT-AG-001~005）、`PluginError`、`AgentError` |
+| `version` | `HOST_API_VERSION`、`isApiCompatible()`、`satisfiesVersion()` —— 宿主/插件 API 兼容性判定 |
+
+## 最小渠道适配器
+
+```ts
+import { Capability, ValidationIssueSeverity, type ChannelAdapter, type HostServices } from '@airongrong/plugin-api'
+
+export default function activate(host: HostServices): { adapter: ChannelAdapter } {
+  return {
+    adapter: {
+      meta: { id: 'channel.acme', label: 'Acme', capabilities: [Capability.PublishText, Capability.PublishImage] },
+      async authorize(ctx) {
+        return { externalAccountId: 'acme-1' }
+      },
+      validate(draft) {
+        return draft.text.length > 5000
+          ? [{ severity: ValidationIssueSeverity.Error, message: '正文超长', path: 'text' }]
+          : []
+      },
+      async publish(draft, ctx) {
+        host.log.info('publishing', { draftId: draft.draftId, accountId: ctx.accountId })
+        return { externalId: 'acme-1', url: 'https://acme.example/p/1', publishedAt: new Date().toISOString() }
+      },
+    },
+  }
+}
+```
+
+完整字段见 `ChannelAdapter` / `PostDraft`（`draftId` 为幂等键，重复提交必须返回同一结果）。
+草稿示例：`visibility: DraftVisibility.Public`、`blocks`、`topics` 等。
+
+产物约束：插件 entry 只允许 `import '@airongrong/plugin-api'`（见 `ALLOWED_ENTRY_IMPORT`），
+动态 `import()` 的参数同样必须是该字面量——计算型写法（如 `import('node:' + 'fs')`）在校验时被拒绝，
+其他依赖一律拒绝，保证 `.aitpkg` 可离线、零依赖安装。`entry.module` 禁止包含 `..` 路径穿越。
+
+## 版本策略
+
+宿主与插件用 `apiVersion` 字段对齐，`isApiCompatible()` 要求宿主版本命中插件声明区间
+（支持 `^1.0.0`、`>=1.8.0 <3` 等复合区间）且主版本不越界；
+SDK 自身发版遵循 semver，breaking change 必须升主版本并同步 `HOST_API_VERSION`。

package/dist/channel-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { Capability } from './plugin-manifest';
+import type { AuthContext, AuthResult, CapabilitySet, Metrics, PostDraft, PublishContext, PublishResult, ValidationIssue } from './post-draft';
+export interface ChannelMeta {
+    id: string;
+    label: string;
+    capabilities: Capability[];
+}
+/**
+ * 渠道适配器：唯一有网络与密钥权限、必须沙箱执行 + 人工审核的插件类型。
+ */
+export interface ChannelAdapter {
+    meta: ChannelMeta;
+    authorize: (ctx: AuthContext) => Promise<AuthResult>;
+    refresh?: (ctx: AuthContext) => Promise<AuthResult>;
+    revoke?: (ctx: AuthContext) => Promise<void>;
+    /** 不允许静默降级：不支持的 capability 必须返回明确 issue */
+    validate: (draft: PostDraft, caps: CapabilitySet) => ValidationIssue[] | Promise<ValidationIssue[]>;
+    publish: (draft: PostDraft, ctx: PublishContext) => Promise<PublishResult>;
+    metrics?: (externalId: string, ctx: AuthContext) => Promise<Metrics>;
+}

package/dist/channel-adapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/host-services.d.ts

@@ -0,0 +1,39 @@
+export interface HostHttpRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface HostHttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface HostLogMeta {
+    [key: string]: unknown;
+}
+export interface HostSecrets {
+    /**
+     * 密钥以回调参数形式临时可用，调用结束即失效。
+     * key 必须在 plugin.json permissions.secrets 中声明。
+     */
+    use: <T>(key: string, fn: (value: string) => Promise<T> | T) => Promise<T>;
+}
+export interface HostStorage {
+    get: (key: string) => Promise<unknown>;
+    set: (key: string, value: unknown) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+}
+export interface HostServices {
+    http: {
+        request: (request: HostHttpRequest) => Promise<HostHttpResponse>;
+    };
+    secrets: HostSecrets;
+    /** 按 pluginId + 账号 id 分区，配额见 plugin.json permissions.storage */
+    storage: HostStorage;
+    log: {
+        info: (message: string, meta?: HostLogMeta) => void;
+        warn: (message: string, meta?: HostLogMeta) => void;
+        error: (message: string, meta?: HostLogMeta) => void;
+    };
+}

package/dist/host-services.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './channel-adapter';
+export * from './host-services';
+export * from './plugin-error-code';
+export * from './plugin-manifest';
+export * from './plugin-module';
+export * from './post-draft';
+export * from './version';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./channel-adapter"), exports);
+__exportStar(require("./host-services"), exports);
+__exportStar(require("./plugin-error-code"), exports);
+__exportStar(require("./plugin-manifest"), exports);
+__exportStar(require("./plugin-module"), exports);
+__exportStar(require("./post-draft"), exports);
+__exportStar(require("./version"), exports);

package/dist/plugin-error-code.d.ts

@@ -0,0 +1,27 @@
+export declare enum PluginErrorCode {
+    InvalidManifest = "AIT-PL-001",
+    HashMismatch = "AIT-PL-002",
+    UntrustedSignature = "AIT-PL-003",
+    ApiVersionIncompatible = "AIT-PL-004",
+    PermissionViolation = "AIT-PL-005",
+    ActivateTimeout = "AIT-PL-006",
+    HookRejected = "AIT-PL-007",
+    IdempotencyConflict = "AIT-PL-008"
+}
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: PluginErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+export declare enum AgentErrorCode {
+    Unauthorized = "AIT-AG-001",
+    WriteNotConfirmed = "AIT-AG-002",
+    RateLimited = "AIT-AG-003",
+    ContentRiskControl = "AIT-AG-004",
+    RevokeTimeout = "AIT-AG-005"
+}
+export declare class AgentError extends Error {
+    readonly code: AgentErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: AgentErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}

package/dist/plugin-error-code.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentError = exports.AgentErrorCode = exports.PluginError = exports.PluginErrorCode = void 0;
+var PluginErrorCode;
+(function (PluginErrorCode) {
+    PluginErrorCode["InvalidManifest"] = "AIT-PL-001";
+    PluginErrorCode["HashMismatch"] = "AIT-PL-002";
+    PluginErrorCode["UntrustedSignature"] = "AIT-PL-003";
+    PluginErrorCode["ApiVersionIncompatible"] = "AIT-PL-004";
+    PluginErrorCode["PermissionViolation"] = "AIT-PL-005";
+    PluginErrorCode["ActivateTimeout"] = "AIT-PL-006";
+    PluginErrorCode["HookRejected"] = "AIT-PL-007";
+    PluginErrorCode["IdempotencyConflict"] = "AIT-PL-008";
+})(PluginErrorCode || (exports.PluginErrorCode = PluginErrorCode = {}));
+class PluginError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'PluginError';
+    }
+}
+exports.PluginError = PluginError;
+var AgentErrorCode;
+(function (AgentErrorCode) {
+    AgentErrorCode["Unauthorized"] = "AIT-AG-001";
+    AgentErrorCode["WriteNotConfirmed"] = "AIT-AG-002";
+    AgentErrorCode["RateLimited"] = "AIT-AG-003";
+    AgentErrorCode["ContentRiskControl"] = "AIT-AG-004";
+    AgentErrorCode["RevokeTimeout"] = "AIT-AG-005";
+})(AgentErrorCode || (exports.AgentErrorCode = AgentErrorCode = {}));
+class AgentError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'AgentError';
+    }
+}
+exports.AgentError = AgentError;

package/dist/plugin-manifest.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+export declare enum PluginType {
+    Skill = "skill",
+    Hook = "hook",
+    Adapter = "adapter"
+}
+export declare enum PluginHookName {
+    ValidateDraft = "validateDraft",
+    BeforePublish = "beforePublish",
+    AfterPublish = "afterPublish",
+    OnAuthExpired = "onAuthExpired"
+}
+export declare enum Capability {
+    PublishText = "publish.text",
+    PublishNote = "publish.note",
+    PublishImage = "publish.image",
+    PublishVideo = "publish.video",
+    PublishThread = "publish.thread",
+    PublishScheduled = "publish.scheduled",
+    MetricsBasic = "metrics.basic",
+    MetricsEngagement = "metrics.engagement"
+}
+export declare const PLUGIN_ID_PATTERN: RegExp;
+export declare const pluginDomainSchema: z.ZodString;
+export declare const pluginManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    version: z.ZodString;
+    apiVersion: z.ZodString;
+    type: z.ZodEnum<{
+        skill: PluginType.Skill;
+        hook: PluginType.Hook;
+        adapter: PluginType.Adapter;
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        module: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>>;
+    contributes: z.ZodObject<{
+        channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            capabilities: z.ZodArray<z.ZodEnum<{
+                "publish.text": Capability.PublishText;
+                "publish.note": Capability.PublishNote;
+                "publish.image": Capability.PublishImage;
+                "publish.video": Capability.PublishVideo;
+                "publish.thread": Capability.PublishThread;
+                "publish.scheduled": Capability.PublishScheduled;
+                "metrics.basic": Capability.MetricsBasic;
+                "metrics.engagement": Capability.MetricsEngagement;
+            }>>;
+        }, z.core.$strip>>>;
+        hooks: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            validateDraft: PluginHookName.ValidateDraft;
+            beforePublish: PluginHookName.BeforePublish;
+            afterPublish: PluginHookName.AfterPublish;
+            onAuthExpired: PluginHookName.OnAuthExpired;
+        }>>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    permissions: z.ZodObject<{
+        network: z.ZodArray<z.ZodString>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        storage: z.ZodOptional<z.ZodObject<{
+            kv: z.ZodOptional<z.ZodBoolean>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    engines: z.ZodObject<{
+        aitoearn: z.ZodString;
+    }, z.core.$strip>;
+    license: z.ZodString;
+    publisher: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        keyId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginManifest = z.infer<typeof pluginManifestSchema>;
+/** 插件产物只允许 import 这一个包，其余一律拒绝（§3.3-1 自包含单文件 ESM） */
+export declare const ALLOWED_ENTRY_IMPORT = "@airongrong/plugin-api";
+/**
+ * 运行时复用同一套入口源码约束（CLI 的 verify/pack 与宿主加载共用）。
+ * 阻止 entry 通过 import 'node:fs' / 'node:child_process' 绕过权限代理。
+ */
+export declare function assertPluginEntrySource(source: string, modulePath?: string): void;
+export declare const pluginManifestJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    version: z.ZodString;
+    apiVersion: z.ZodString;
+    type: z.ZodEnum<{
+        skill: PluginType.Skill;
+        hook: PluginType.Hook;
+        adapter: PluginType.Adapter;
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    entry: z.ZodOptional<z.ZodObject<{
+        module: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>>;
+    contributes: z.ZodObject<{
+        channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            capabilities: z.ZodArray<z.ZodEnum<{
+                "publish.text": Capability.PublishText;
+                "publish.note": Capability.PublishNote;
+                "publish.image": Capability.PublishImage;
+                "publish.video": Capability.PublishVideo;
+                "publish.thread": Capability.PublishThread;
+                "publish.scheduled": Capability.PublishScheduled;
+                "metrics.basic": Capability.MetricsBasic;
+                "metrics.engagement": Capability.MetricsEngagement;
+            }>>;
+        }, z.core.$strip>>>;
+        hooks: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            validateDraft: PluginHookName.ValidateDraft;
+            beforePublish: PluginHookName.BeforePublish;
+            afterPublish: PluginHookName.AfterPublish;
+            onAuthExpired: PluginHookName.OnAuthExpired;
+        }>>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    permissions: z.ZodObject<{
+        network: z.ZodArray<z.ZodString>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        storage: z.ZodOptional<z.ZodObject<{
+            kv: z.ZodOptional<z.ZodBoolean>;
+            bytes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    engines: z.ZodObject<{
+        aitoearn: z.ZodString;
+    }, z.core.$strip>;
+    license: z.ZodString;
+    publisher: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        keyId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare function verifyManifest(input: unknown): PluginManifest;

package/dist/plugin-manifest.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginManifestJsonSchema = exports.ALLOWED_ENTRY_IMPORT = exports.pluginManifestSchema = exports.pluginDomainSchema = exports.PLUGIN_ID_PATTERN = exports.Capability = exports.PluginHookName = exports.PluginType = void 0;
+exports.assertPluginEntrySource = assertPluginEntrySource;
+exports.verifyManifest = verifyManifest;
+const zod_1 = require("zod");
+const plugin_error_code_1 = require("./plugin-error-code");
+var PluginType;
+(function (PluginType) {
+    PluginType["Skill"] = "skill";
+    PluginType["Hook"] = "hook";
+    PluginType["Adapter"] = "adapter";
+})(PluginType || (exports.PluginType = PluginType = {}));
+var PluginHookName;
+(function (PluginHookName) {
+    PluginHookName["ValidateDraft"] = "validateDraft";
+    PluginHookName["BeforePublish"] = "beforePublish";
+    PluginHookName["AfterPublish"] = "afterPublish";
+    PluginHookName["OnAuthExpired"] = "onAuthExpired";
+})(PluginHookName || (exports.PluginHookName = PluginHookName = {}));
+var Capability;
+(function (Capability) {
+    Capability["PublishText"] = "publish.text";
+    Capability["PublishNote"] = "publish.note";
+    Capability["PublishImage"] = "publish.image";
+    Capability["PublishVideo"] = "publish.video";
+    Capability["PublishThread"] = "publish.thread";
+    Capability["PublishScheduled"] = "publish.scheduled";
+    Capability["MetricsBasic"] = "metrics.basic";
+    Capability["MetricsEngagement"] = "metrics.engagement";
+})(Capability || (exports.Capability = Capability = {}));
+exports.PLUGIN_ID_PATTERN = /^(skill|hook|channel)\.[a-z0-9-]{2,32}$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+const SEMVER_RANGE_PATTERN = /^([\^~]|>=|<=|[><=])?\d+(\.\d+){0,2}(\s+([\^~]|>=|<=|[><=])?\d+(\.\d+){0,2})*$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const DOMAIN_PATTERN = /^(?!\d+\.\d+\.\d+\.\d+$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/i;
+const MODULE_PATTERN = /^(?:\.\/)?dist\/[\w./-]+\.mjs$/;
+exports.pluginDomainSchema = zod_1.z.string().regex(DOMAIN_PATTERN, 'network 域名必须是合法主机名，禁止通配符与 IP 字面量');
+exports.pluginManifestSchema = zod_1.z.object({
+    $schema: zod_1.z.string().min(1).optional(),
+    id: zod_1.z.string().regex(exports.PLUGIN_ID_PATTERN, 'id 必须匹配 ^(skill|hook|channel)\\.[a-z0-9-]{2,32}$'),
+    version: zod_1.z.string().regex(SEMVER_PATTERN, 'version 必须是 semver'),
+    apiVersion: zod_1.z.string().regex(SEMVER_RANGE_PATTERN, 'apiVersion 必须是 semver 区间，如 ^1.0.0'),
+    type: zod_1.z.enum(Object.values(PluginType)),
+    name: zod_1.z.string().min(1).optional(),
+    description: zod_1.z.string().min(1),
+    entry: zod_1.z.object({
+        module: zod_1.z.string().regex(MODULE_PATTERN, 'entry.module 必须是打包后的单文件 ESM（dist/*.mjs）'),
+        sha256: zod_1.z.string().regex(SHA256_PATTERN, 'entry.sha256 必须是 64 位小写十六进制'),
+    }).optional(),
+    contributes: zod_1.z.object({
+        channels: zod_1.z.array(zod_1.z.object({
+            id: zod_1.z.string().min(1),
+            label: zod_1.z.string().min(1),
+            capabilities: zod_1.z.array(zod_1.z.enum(Object.values(Capability))).min(1),
+        })).optional(),
+        hooks: zod_1.z.array(zod_1.z.enum(Object.values(PluginHookName))).optional(),
+        skills: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+    }),
+    permissions: zod_1.z.object({
+        network: zod_1.z.array(exports.pluginDomainSchema).max(5, 'permissions.network 单插件上限 5 个域名'),
+        secrets: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        storage: zod_1.z.object({
+            kv: zod_1.z.boolean().optional(),
+            bytes: zod_1.z.number().int().positive().optional(),
+        }).optional(),
+    }),
+    engines: zod_1.z.object({
+        aitoearn: zod_1.z.string().regex(SEMVER_RANGE_PATTERN, 'engines.aitoearn 必须是 semver 区间'),
+    }),
+    license: zod_1.z.string().min(1),
+    publisher: zod_1.z.object({
+        id: zod_1.z.string().min(1).optional(),
+        name: zod_1.z.string().min(1).optional(),
+        keyId: zod_1.z.string().min(1).optional(),
+    }).optional(),
+    signature: zod_1.z.string().min(1).optional(),
+}).superRefine((manifest, context) => {
+    if (manifest.type === PluginType.Skill && manifest.entry) {
+        context.addIssue({
+            code: 'custom',
+            path: ['entry'],
+            message: '技能插件禁止 entry 字段（技能不执行代码）',
+        });
+    }
+    if (manifest.type !== PluginType.Skill && !manifest.entry) {
+        context.addIssue({
+            code: 'custom',
+            path: ['entry'],
+            message: `${manifest.type} 插件必须声明 entry（单文件 ESM 产物与 sha256）`,
+        });
+    }
+    if (manifest.publisher && !manifest.publisher.id && !manifest.publisher.name) {
+        context.addIssue({
+            code: 'custom',
+            path: ['publisher'],
+            message: 'publisher 至少需要 id 或 name',
+        });
+    }
+});
+/** 插件产物只允许 import 这一个包，其余一律拒绝（§3.3-1 自包含单文件 ESM） */
+exports.ALLOWED_ENTRY_IMPORT = '@airongrong/plugin-api';
+const ENTRY_IMPORT_PATTERN = /(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]/g;
+/**
+ * 运行时复用同一套入口源码约束（CLI 的 verify/pack 与宿主加载共用）。
+ * 阻止 entry 通过 import 'node:fs' / 'node:child_process' 绕过权限代理。
+ */
+function assertPluginEntrySource(source, modulePath = 'entry') {
+    const violations = [];
+    for (const match of source.matchAll(ENTRY_IMPORT_PATTERN)) {
+        const specifier = match[1] ?? match[2];
+        if (specifier && specifier !== exports.ALLOWED_ENTRY_IMPORT) {
+            violations.push(specifier);
+        }
+    }
+    if (violations.length > 0) {
+        throw new plugin_error_code_1.PluginError(plugin_error_code_1.PluginErrorCode.InvalidManifest, `${modulePath} 必须是自包含单文件 ESM，只允许 import '${exports.ALLOWED_ENTRY_IMPORT}'，违规: ${violations.join(', ')}`);
+    }
+}
+exports.pluginManifestJsonSchema = zod_1.z.toJSONSchema(exports.pluginManifestSchema);
+function verifyManifest(input) {
+    const result = exports.pluginManifestSchema.safeParse(input);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        throw new plugin_error_code_1.PluginError(plugin_error_code_1.PluginErrorCode.InvalidManifest, `plugin.json 非法: ${issue.path.join('.')} ${issue.message}`, { issues: result.error.issues });
+    }
+    return result.data;
+}

package/dist/plugin-module.d.ts

@@ -0,0 +1,32 @@
+import type { ChannelAdapter } from './channel-adapter';
+import type { HostServices } from './host-services';
+import type { PostDraft, PublishResult } from './post-draft';
+export interface HookHandlers {
+    /** 编辑期每次保存；返回 issue 阻断保存（可选，默认警告） */
+    validateDraft?: (draft: PostDraft) => ValidationIssueResult[] | Promise<ValidationIssueResult[]>;
+    /** fail-closed：抛错即中止发布，并透传原因 */
+    beforePublish?: (draft: PostDraft) => Promise<void>;
+    /** fail-open：只记日志 */
+    afterPublish?: (result: PublishResult) => Promise<void>;
+    onAuthExpired?: (ctx: {
+        accountId: string;
+        channelId: string;
+    }) => Promise<void>;
+}
+export interface ValidationIssueResult {
+    severity: 'error' | 'warning';
+    message: string;
+    path?: string;
+}
+export interface AdapterPluginModule {
+    adapter: ChannelAdapter;
+}
+export interface HookPluginModule {
+    hooks: HookHandlers;
+}
+export type PluginModule = AdapterPluginModule | HookPluginModule;
+/**
+ * 插件入口契约：默认导出或 activate 函数，宿主在 worker 内调用。
+ * 模块内只允许 import '@airongrong/plugin-api'（类型与工具，不打入产物）。
+ */
+export type PluginActivate = (host: HostServices) => PluginModule | Promise<PluginModule>;

package/dist/plugin-module.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/post-draft.d.ts

@@ -0,0 +1,74 @@
+export declare enum DraftBlockKind {
+    Image = "image",
+    Video = "video",
+    Link = "link"
+}
+export type DraftBlock = {
+    kind: DraftBlockKind.Image;
+    url: string;
+    width: number;
+    height: number;
+} | {
+    kind: DraftBlockKind.Video;
+    url: string;
+    durationSec: number;
+    coverUrl?: string;
+} | {
+    kind: DraftBlockKind.Link;
+    url: string;
+};
+export declare enum DraftVisibility {
+    Public = "public",
+    Private = "private",
+    Unlisted = "unlisted"
+}
+export interface PostDraft {
+    /** 幂等键：同一 draftId 重复提交必须返回同一结果 */
+    draftId: string;
+    text: string;
+    blocks: DraftBlock[];
+    topics: string[];
+    mentions: string[];
+    visibility: DraftVisibility;
+    /** ISO8601，由宿主统一调度 */
+    scheduledAt?: string;
+    locale: string;
+}
+export declare enum ValidationIssueSeverity {
+    Error = "error",
+    Warning = "warning"
+}
+export interface ValidationIssue {
+    severity: ValidationIssueSeverity;
+    message: string;
+    /** 关联的草稿字段，如 blocks.0.url */
+    path?: string;
+}
+export interface PublishResult {
+    externalId: string;
+    url: string;
+    publishedAt: string;
+    warnings?: string[];
+}
+export interface PublishContext {
+    accountId: string;
+    locale: string;
+}
+export interface Metrics {
+    views?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    collectedAt: string;
+}
+export interface AuthContext {
+    accountId: string;
+}
+export interface AuthResult {
+    externalAccountId: string;
+    displayName?: string;
+    expiresAt?: string;
+}
+export interface CapabilitySet {
+    capabilities: string[];
+}

package/dist/post-draft.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationIssueSeverity = exports.DraftVisibility = exports.DraftBlockKind = void 0;
+var DraftBlockKind;
+(function (DraftBlockKind) {
+    DraftBlockKind["Image"] = "image";
+    DraftBlockKind["Video"] = "video";
+    DraftBlockKind["Link"] = "link";
+})(DraftBlockKind || (exports.DraftBlockKind = DraftBlockKind = {}));
+var DraftVisibility;
+(function (DraftVisibility) {
+    DraftVisibility["Public"] = "public";
+    DraftVisibility["Private"] = "private";
+    DraftVisibility["Unlisted"] = "unlisted";
+})(DraftVisibility || (exports.DraftVisibility = DraftVisibility = {}));
+var ValidationIssueSeverity;
+(function (ValidationIssueSeverity) {
+    ValidationIssueSeverity["Error"] = "error";
+    ValidationIssueSeverity["Warning"] = "warning";
+})(ValidationIssueSeverity || (exports.ValidationIssueSeverity = ValidationIssueSeverity = {}));

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+export declare const HOST_API_VERSION = "1.0.0";
+/**
+ * Minimal semver range matcher supporting the doc grammar:
+ * `>=1.8.0 <3`, `^1.2.0`, `~1.2.0`, `1.2.3` and combinations.
+ */
+export declare function satisfiesVersion(version: string, range: string): boolean;
+/**
+ * Host/plugin apiVersion compatibility: the host version must satisfy the
+ * declared range and its major must lie within the majors the range allows
+ * （compound ranges like `>=1.8.0 <3` are supported, see plan §9）.
+ */
+export declare function isApiCompatible(pluginApiVersion: string, hostApiVersion?: string): boolean;

package/dist/version.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_API_VERSION = void 0;
+exports.satisfiesVersion = satisfiesVersion;
+exports.isApiCompatible = isApiCompatible;
+exports.HOST_API_VERSION = '1.0.0';
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+function parseVersion(version) {
+    if (!VERSION_PATTERN.test(version)) {
+        return undefined;
+    }
+    return version.split('.').map(part => Number(part));
+}
+function compareVersions(a, b) {
+    for (let index = 0; index < 3; index += 1) {
+        if (a[index] !== b[index]) {
+            return a[index] - b[index];
+        }
+    }
+    return 0;
+}
+function comparePartial(version, expected, precision) {
+    for (let index = 0; index < precision; index += 1) {
+        if (version[index] !== expected[index]) {
+            return version[index] - expected[index];
+        }
+    }
+    return 0;
+}
+/**
+ * Minimal semver range matcher supporting the doc grammar:
+ * `>=1.8.0 <3`, `^1.2.0`, `~1.2.0`, `1.2.3` and combinations.
+ */
+function satisfiesVersion(version, range) {
+    const parsedVersion = parseVersion(version);
+    if (!parsedVersion) {
+        return false;
+    }
+    return range.trim().split(/\s+/).every((clause) => {
+        const match = /^(>=|<=|[><=^~])?(\d+(?:\.\d+){0,2})$/.exec(clause);
+        if (!match) {
+            return false;
+        }
+        const operator = match[1] ?? '=';
+        const parts = match[2].split('.').map(part => Number(part));
+        const expected = [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+        const precision = parts.length;
+        switch (operator) {
+            case '>=':
+                return compareVersions(parsedVersion, expected) >= 0;
+            case '<=':
+                return compareVersions(parsedVersion, expected) <= 0;
+            case '>':
+                return compareVersions(parsedVersion, expected) > 0;
+            case '<':
+                return compareVersions(parsedVersion, expected) < 0;
+            case '~':
+                return comparePartial(parsedVersion, expected, Math.min(precision, 2)) === 0;
+            case '^':
+                return comparePartial(parsedVersion, expected, 1) === 0 && compareVersions(parsedVersion, expected) >= 0;
+            default:
+                if (precision === 3) {
+                    return compareVersions(parsedVersion, expected) === 0;
+                }
+                return comparePartial(parsedVersion, expected, precision) === 0;
+        }
+    });
+}
+const MAJOR_CEILING = Number.POSITIVE_INFINITY;
+/**
+ * 计算区间允许的主版本闭区间 [lo, hi]（hi 为 Infinity 表示无上界）。
+ * 区间非法或主版本范围为空时返回 undefined。边界刻意宽松（如 `>2` 记 lo=2），
+ * 精确命中仍由 satisfiesVersion 把关，这里只做跨主版本的粗粒度闸门。
+ */
+function rangeMajors(range) {
+    let lo = 0;
+    let hi = MAJOR_CEILING;
+    for (const clause of range.trim().split(/\s+/)) {
+        const match = /^(>=|<=|[><=^~])?(\d+(?:\.\d+){0,2})$/.exec(clause);
+        if (!match) {
+            return undefined;
+        }
+        const operator = match[1] ?? '=';
+        const parts = match[2].split('.').map(part => Number(part));
+        const major = parts[0] ?? 0;
+        const hasUpperTail = parts.slice(1).some(part => part > 0);
+        switch (operator) {
+            case '>=':
+            case '>':
+                // >X.Y.Z 仍允许主版本 X（如 >1.8.0 含 1.9.0）
+                lo = Math.max(lo, major);
+                break;
+            case '<=':
+                hi = Math.min(hi, major);
+                break;
+            case '<':
+                // <3.0.0 排除主版本 3，<3.0.1 仍允许 3.0.0
+                hi = Math.min(hi, hasUpperTail ? major : major - 1);
+                break;
+            case '^':
+            case '~':
+            default:
+                lo = Math.max(lo, major);
+                hi = Math.min(hi, major);
+        }
+    }
+    return lo > hi ? undefined : [lo, hi];
+}
+/**
+ * Host/plugin apiVersion compatibility: the host version must satisfy the
+ * declared range and its major must lie within the majors the range allows
+ * （compound ranges like `>=1.8.0 <3` are supported, see plan §9）.
+ */
+function isApiCompatible(pluginApiVersion, hostApiVersion = exports.HOST_API_VERSION) {
+    const host = parseVersion(hostApiVersion);
+    if (!host) {
+        return false;
+    }
+    const majors = rangeMajors(pluginApiVersion);
+    if (!majors || host[0] < majors[0] || host[0] > majors[1]) {
+        return false;
+    }
+    return satisfiesVersion(hostApiVersion, pluginApiVersion);
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@airongrong/plugin-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.0",
+  "description": "AiToEarn plugin SDK: plugin.json manifest schema, adapter contract, host services and error codes",
+  "license": "MIT",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yikart/aitoearn-sdk.git",
+    "directory": "packages/plugin-api"
+  },
+  "homepage": "https://github.com/yikart/aitoearn-sdk/tree/main/packages/plugin-api#readme",
+  "bugs": {
+    "url": "https://github.com/yikart/aitoearn-sdk/issues"
+  },
+  "keywords": [
+    "aitoearn",
+    "plugin",
+    "manifest",
+    "channel-adapter",
+    "sdk"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish-guard.mjs"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}