@mindpal/protocol 0.0.2-alpha

package/dist/skill-rpc.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Skill RPC Protocol — JSON-RPC over stdio 标准协议定义
+ *
+ * OS 思维：Skill 是"用户态进程"，Skill Runner 是"进程管理器"。
+ * 本协议定义了 Runner 与 Skill 子进程之间的通信契约。
+ *
+ * 传输层：换行分隔的 JSON（NDJSON / JSON Lines），over stdin/stdout
+ * 控制信道：stderr（日志 + 进度）
+ *
+ * 消息格式遵循 JSON-RPC 2.0 子集：
+ * - Request: { jsonrpc: "2.0", id, method, params }
+ * - Response: { jsonrpc: "2.0", id, result } | { jsonrpc: "2.0", id, error }
+ * - Notification: { jsonrpc: "2.0", method, params } (无 id，无需响应)
+ */
+import { type RegistryEntry } from './registry.js';
+export declare const SKILL_RPC_VERSION = "1.0";
+export declare const SKILL_RPC_JSONRPC: "2.0";
+/** 当前 Device Agent 协议版本 */
+export declare const DEVICE_PROTOCOL_VERSION = "1.0";
+/** 最低支持的协议版本 */
+export declare const MIN_SUPPORTED_PROTOCOL_VERSION = "1.0";
+/** 所有支持的协议版本列表 */
+export declare const PROTOCOL_VERSIONS: readonly ["1.0"];
+/** 协议版本类型 */
+export type ProtocolVersion = (typeof PROTOCOL_VERSIONS)[number];
+/** Device Agent → API: 协议握手请求 */
+export interface ProtocolHandshake {
+    type: "protocol.handshake";
+    protocolVersion: string;
+    agentVersion: string;
+    capabilities: string[];
+}
+/** API → Device Agent: 协议握手确认 */
+export interface ProtocolHandshakeAck {
+    type: "protocol.handshake.ack";
+    negotiatedVersion: string;
+    serverVersion: string;
+    compatible: boolean;
+    deprecationWarning?: string;
+    /** 服务端下发的多模态策略（元数据驱动） */
+    multimodalPolicy?: DeviceMultimodalPolicy | null;
+}
+/** 设备支持的模态类型 */
+export type DeviceModality = 'image' | 'audio' | 'video' | 'text' | 'sensor' | 'actuator' | (string & {});
+export declare const BUILTIN_DEVICE_MODALITIES: RegistryEntry[];
+export declare const modalityRegistry: import("./registry.js").TypeRegistry<unknown>;
+export type SkillRuntime = string;
+export declare const BUILTIN_SKILL_RUNTIMES: RegistryEntry[];
+export declare const runtimeRegistry: import("./registry.js").TypeRegistry<unknown>;
+export type SensitivityProfile = string;
+export declare const BUILTIN_SENSITIVITY_PROFILES: RegistryEntry[];
+export declare const sensitivityProfileRegistry: import("./registry.js").TypeRegistry<unknown>;
+/** 设备多模态能力声明（设备注册/握手时上报） */
+export interface DeviceMultimodalCapabilities {
+    modalities: DeviceModality[];
+    multimodalConfig?: {
+        maxFileSize?: number;
+        supportedFormats?: Partial<Record<DeviceModality, string[]>>;
+        /** 流式交互配置 */
+        streaming?: {
+            supported: boolean;
+            maxConcurrentStreams?: number;
+        };
+        /** VAD（语音活动检测）配置 —— 元数据驱动 */
+        vad?: {
+            enabled: boolean;
+            silenceThresholdMs?: number;
+            energySmoothingFactor?: number;
+            adaptiveThreshold?: boolean;
+            /** 噪声基线校准时长（ms），默认 3000 */
+            noiseCalibrationMs?: number;
+            /** 最小语音段时长（ms），低于此值视为噪声，默认 200 */
+            minSpeechDurationMs?: number;
+            /** 灵敏度档位：quiet/normal/noisy/auto */
+            sensitivityProfile?: SensitivityProfile;
+        };
+        /** 轻量级视频帧流配置 */
+        videoStream?: {
+            supported: boolean;
+            frameIntervalMs?: number;
+            maxFrameWidth?: number;
+            format?: "jpeg" | "png";
+        };
+    };
+    /**
+     * 设备能力描述符（OS级设备抽象，设备连接时上报）。
+     * 完整类型定义见 @mindpal/shared deviceProtocol.DeviceCapabilityDescriptor。
+     * 协议层仅保留弱类型引用以保持零依赖。
+     */
+    capabilityDescriptor?: unknown;
+}
+/** 服务端下发的多模态策略 */
+export interface DeviceMultimodalPolicy {
+    allowedModalities: DeviceModality[];
+    maxFileSizeBytes: number;
+    supportedFormats: Partial<Record<DeviceModality, string[]>>;
+    /** 流式策略下发 */
+    streaming?: {
+        supported: boolean;
+        maxConcurrentStreams?: number;
+        sttStreaming?: boolean;
+        ttsStreaming?: boolean;
+    } | null;
+    /** VAD 策略下发 */
+    vad?: {
+        enabled: boolean;
+        silenceThresholdMs?: number;
+        energySmoothingFactor?: number;
+        adaptiveThreshold?: boolean;
+        noiseCalibrationMs?: number;
+        minSpeechDurationMs?: number;
+        sensitivityProfile?: SensitivityProfile;
+    } | null;
+    /** 视频帧流策略下发 */
+    videoStream?: {
+        supported: boolean;
+        frameIntervalMs?: number;
+        maxFrameWidth?: number;
+        format?: "jpeg" | "png";
+        realtimeAnalysis?: boolean;
+    } | null;
+}
+/** 设备多模态附件 */
+export interface DeviceAttachment {
+    type: "image" | "document" | "voice" | "video";
+    mimeType: string;
+    name?: string;
+    /** base64 data URL */
+    dataUrl?: string;
+}
+/** 设备 → 云端：多模态查询消息 */
+export interface DeviceMultimodalQuery {
+    type: "device_query";
+    sessionId: string;
+    conversationId?: string;
+    message: string;
+    attachments?: DeviceAttachment[];
+}
+/**
+ * 检查客户端版本是否与最低版本兼容。
+ * 仅比较主版本号（semver major）。
+ */
+export declare function isVersionCompatible(clientVersion: string, minVersion: string): boolean;
+/**
+ * 在服务端支持的版本列表中选出与客户端兼容的最高版本。
+ * 返回 null 表示无兼容版本。
+ */
+export declare function negotiateVersion(clientVersion: string, supportedVersions: readonly string[]): string | null;
+/** JSON-RPC 请求 */
+export interface SkillRpcRequest<P = unknown> {
+    jsonrpc: typeof SKILL_RPC_JSONRPC;
+    id: string | number;
+    method: string;
+    params: P;
+}
+/** JSON-RPC 成功响应 */
+export interface SkillRpcSuccess<R = unknown> {
+    jsonrpc: typeof SKILL_RPC_JSONRPC;
+    id: string | number;
+    result: R;
+}
+/** JSON-RPC 错误响应 */
+export interface SkillRpcError {
+    jsonrpc: typeof SKILL_RPC_JSONRPC;
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** JSON-RPC 通知（无 id，无需响应） */
+export interface SkillRpcNotification<P = unknown> {
+    jsonrpc: typeof SKILL_RPC_JSONRPC;
+    method: string;
+    params: P;
+}
+export type SkillRpcResponse<R = unknown> = SkillRpcSuccess<R> | SkillRpcError;
+export type SkillRpcMessage = SkillRpcRequest | SkillRpcResponse | SkillRpcNotification;
+/** JSON-RPC 2.0 标准错误码 — 固定不变 */
+export declare const JSONRPC_STANDARD_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+/** 自定义错误码注册表 */
+export declare const BUILTIN_CUSTOM_ERRORS: RegistryEntry<number>[];
+export declare const skillErrorCodeRegistry: import("./registry.js").TypeRegistry<number>;
+/** 向后兼容的完整错误码对象（合并标准+自定义） */
+export declare const SKILL_RPC_ERRORS: {
+    readonly EXECUTION_TIMEOUT: -32001;
+    readonly EXECUTION_FAILED: -32002;
+    readonly RESOURCE_EXHAUSTED: -32003;
+    readonly POLICY_VIOLATION: -32004;
+    readonly DEPENDENCY_ERROR: -32005;
+    readonly CAPABILITY_DENIED: -32006;
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+import type { InferenceMode, ModelCapabilityTier } from './skill-manifest.js';
+/** Runner → Skill: 模型配置注入（Runner 根据 manifest.modelRequirements 分配） */
+export interface SkillModelConfig {
+    /** 分配的模型端点 URL */
+    endpoint: string;
+    /** 认证令牌 */
+    apiKey: string;
+    /** 模型标识符（如 gpt-4o, claude-sonnet, deepseek-r1） */
+    model: string;
+    /** 推理模式（由 Runner 根据 manifest 声明确定） */
+    inferenceMode: InferenceMode;
+    /** 实际分配的能力等级 */
+    capabilityTier: ModelCapabilityTier;
+    /** 模型调用超时（ms） */
+    timeoutMs: number;
+    /** 最大输出 token 数 */
+    maxOutputTokens?: number;
+}
+/** Runner → Skill: 初始化请求 */
+export interface SkillInitializeParams {
+    /** 协议版本 */
+    protocolVersion: string;
+    /** Skill 工具引用 */
+    toolRef: string;
+    /** 执行上下文 */
+    context: {
+        tenantId: string;
+        spaceId: string | null;
+        subjectId: string | null;
+        traceId: string;
+        locale: string;
+    };
+    /** 能力包络（声明 Skill 可使用的能力） */
+    capabilities: {
+        /** 允许的出站域名 */
+        allowedDomains: string[];
+        /** 允许的文件系统路径 */
+        allowedPaths: string[];
+        /** 是否允许网络访问 */
+        networkAccess: boolean;
+    };
+    /** 资源限制 */
+    limits: {
+        timeoutMs: number;
+        memoryMb: number;
+        maxOutputBytes: number;
+    };
+    /** 模型配置注入（Runner 根据 manifest.modelRequirements 分配模型资源） */
+    modelConfig?: SkillModelConfig;
+}
+/** Skill → Runner: 初始化响应 */
+export interface SkillInitializeResult {
+    /** Skill 名称 */
+    name: string;
+    /** Skill 版本 */
+    version: string;
+    /** 支持的运行时语言 */
+    runtime: SkillRuntime;
+    /** Skill 声明的能力需求 */
+    requiredCapabilities?: string[];
+}
+/** Runner → Skill: 执行请求 */
+export interface SkillExecuteParams {
+    /** 请求唯一 ID（幂等键） */
+    requestId: string;
+    /** 要调用的 Skill 方法名（Skill 可暴露多个方法，缺省时调用默认入口） */
+    method?: string;
+    /** 输入参数 */
+    input: Record<string, unknown>;
+    /** 输入摘要 */
+    inputDigest: {
+        sha256_8: string;
+        bytes: number;
+    };
+    /** 可选执行上下文（可序列化部分，apiFetch 在沙箱中就地构造） */
+    context?: {
+        locale: string;
+        apiBaseUrl?: string;
+        authToken?: string;
+    };
+}
+/** Skill → Runner: 执行响应 */
+export interface SkillExecuteResult {
+    /** 输出数据 */
+    output: unknown;
+    /** 输出摘要 */
+    outputDigest?: {
+        sha256_8?: string;
+        bytes?: number;
+    };
+    /** 出站请求摘要 */
+    egressSummary?: {
+        allowed: number;
+        denied: number;
+    };
+}
+export interface SkillHeartbeatParams {
+    ts: number;
+}
+export interface SkillHeartbeatResult {
+    ts: number;
+    status: "alive" | "busy";
+}
+/** Skill → Runner: 进度通知 */
+export interface SkillProgressNotification {
+    /** 进度百分比 0-100 */
+    progress: number;
+    /** 当前阶段描述 */
+    phase?: string;
+    /** 附加信息 */
+    detail?: unknown;
+}
+/** Skill → Runner: 日志通知 */
+export interface SkillLogNotification {
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    data?: unknown;
+}
+export declare const SKILL_RPC_METHODS: {
+    readonly INITIALIZE: "skill.initialize";
+    readonly EXECUTE: "skill.execute";
+    readonly HEARTBEAT: "skill.heartbeat";
+    readonly SHUTDOWN: "skill.shutdown";
+    /** 通知方法 */
+    readonly PROGRESS: "skill.progress";
+    readonly LOG: "skill.log";
+};
+/** 获取 RPC 解析失败累计次数（可观测性 / 健康检查用） */
+export declare function getRpcParseFailures(): number;
+/** 创建 JSON-RPC 请求 */
+export declare function createRpcRequest<P>(id: string | number, method: string, params: P): SkillRpcRequest<P>;
+/** 创建 JSON-RPC 成功响应 */
+export declare function createRpcSuccess<R>(id: string | number, result: R): SkillRpcSuccess<R>;
+/** 创建 JSON-RPC 错误响应 */
+export declare function createRpcError(id: string | number | null, code: number, message: string, data?: unknown): SkillRpcError;
+/** 创建通知消息 */
+export declare function createRpcNotification<P>(method: string, params: P): SkillRpcNotification<P>;
+/** 序列化为 NDJSON 行 */
+export declare function serializeRpcMessage(msg: SkillRpcMessage): string;
+/** 从 NDJSON 行反序列化 */
+export declare function parseRpcMessage(line: string): SkillRpcMessage | null;
+/** 判断是否为请求 */
+export declare function isRpcRequest(msg: SkillRpcMessage): msg is SkillRpcRequest;
+/** 判断是否为通知 */
+export declare function isRpcNotification(msg: SkillRpcMessage): msg is SkillRpcNotification;
+/** 判断是否为响应 */
+export declare function isRpcResponse(msg: SkillRpcMessage): msg is SkillRpcResponse;
+/** 判断是否为错误响应 */
+export declare function isRpcError(msg: SkillRpcMessage): msg is SkillRpcError;
+//# sourceMappingURL=skill-rpc.d.ts.map

package/dist/skill-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-rpc.d.ts","sourceRoot":"","sources":["../src/skill-rpc.ts"],"names":[],"mappings":"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"}

package/dist/skill-rpc.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Skill RPC Protocol — JSON-RPC over stdio 标准协议定义
+ *
+ * OS 思维：Skill 是"用户态进程"，Skill Runner 是"进程管理器"。
+ * 本协议定义了 Runner 与 Skill 子进程之间的通信契约。
+ *
+ * 传输层：换行分隔的 JSON（NDJSON / JSON Lines），over stdin/stdout
+ * 控制信道：stderr（日志 + 进度）
+ *
+ * 消息格式遵循 JSON-RPC 2.0 子集：
+ * - Request: { jsonrpc: "2.0", id, method, params }
+ * - Response: { jsonrpc: "2.0", id, result } | { jsonrpc: "2.0", id, error }
+ * - Notification: { jsonrpc: "2.0", method, params } (无 id，无需响应)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_RPC_METHODS = exports.SKILL_RPC_ERRORS = exports.skillErrorCodeRegistry = exports.BUILTIN_CUSTOM_ERRORS = exports.JSONRPC_STANDARD_ERRORS = exports.sensitivityProfileRegistry = exports.BUILTIN_SENSITIVITY_PROFILES = exports.runtimeRegistry = exports.BUILTIN_SKILL_RUNTIMES = exports.modalityRegistry = exports.BUILTIN_DEVICE_MODALITIES = exports.PROTOCOL_VERSIONS = exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.DEVICE_PROTOCOL_VERSION = exports.SKILL_RPC_JSONRPC = exports.SKILL_RPC_VERSION = void 0;
+exports.isVersionCompatible = isVersionCompatible;
+exports.negotiateVersion = negotiateVersion;
+exports.getRpcParseFailures = getRpcParseFailures;
+exports.createRpcRequest = createRpcRequest;
+exports.createRpcSuccess = createRpcSuccess;
+exports.createRpcError = createRpcError;
+exports.createRpcNotification = createRpcNotification;
+exports.serializeRpcMessage = serializeRpcMessage;
+exports.parseRpcMessage = parseRpcMessage;
+exports.isRpcRequest = isRpcRequest;
+exports.isRpcNotification = isRpcNotification;
+exports.isRpcResponse = isRpcResponse;
+exports.isRpcError = isRpcError;
+const registry_js_1 = require("./registry.js");
+/* ================================================================== */
+/*  协议版本                                                            */
+/* ================================================================== */
+exports.SKILL_RPC_VERSION = "1.0";
+exports.SKILL_RPC_JSONRPC = "2.0";
+/* ================================================================== */
+/*  Device Agent 协议版本管控                                           */
+/* ================================================================== */
+/** 当前 Device Agent 协议版本 */
+exports.DEVICE_PROTOCOL_VERSION = "1.0";
+/** 最低支持的协议版本 */
+exports.MIN_SUPPORTED_PROTOCOL_VERSION = "1.0";
+/** 所有支持的协议版本列表 */
+exports.PROTOCOL_VERSIONS = ["1.0"];
+exports.BUILTIN_DEVICE_MODALITIES = [
+    (0, registry_js_1.builtInEntry)('image', 'device.modality'),
+    (0, registry_js_1.builtInEntry)('audio', 'device.modality'),
+    (0, registry_js_1.builtInEntry)('video', 'device.modality'),
+];
+exports.modalityRegistry = (0, registry_js_1.createRegistry)(exports.BUILTIN_DEVICE_MODALITIES);
+exports.BUILTIN_SKILL_RUNTIMES = [
+    (0, registry_js_1.builtInEntry)('python', 'skill.runtime'),
+    (0, registry_js_1.builtInEntry)('node', 'skill.runtime'),
+    (0, registry_js_1.builtInEntry)('go', 'skill.runtime'),
+    (0, registry_js_1.builtInEntry)('rust', 'skill.runtime'),
+    (0, registry_js_1.builtInEntry)('other', 'skill.runtime'),
+];
+exports.runtimeRegistry = (0, registry_js_1.createRegistry)(exports.BUILTIN_SKILL_RUNTIMES);
+exports.BUILTIN_SENSITIVITY_PROFILES = [
+    (0, registry_js_1.builtInEntry)('quiet', 'device.vad.sensitivity'),
+    (0, registry_js_1.builtInEntry)('normal', 'device.vad.sensitivity'),
+    (0, registry_js_1.builtInEntry)('noisy', 'device.vad.sensitivity'),
+    (0, registry_js_1.builtInEntry)('auto', 'device.vad.sensitivity'),
+];
+exports.sensitivityProfileRegistry = (0, registry_js_1.createRegistry)(exports.BUILTIN_SENSITIVITY_PROFILES);
+/**
+ * 检查客户端版本是否与最低版本兼容。
+ * 仅比较主版本号（semver major）。
+ */
+function isVersionCompatible(clientVersion, minVersion) {
+    const clientMajor = parseMajor(clientVersion);
+    const minMajor = parseMajor(minVersion);
+    if (clientMajor === null || minMajor === null)
+        return false;
+    return clientMajor >= minMajor;
+}
+/**
+ * 在服务端支持的版本列表中选出与客户端兼容的最高版本。
+ * 返回 null 表示无兼容版本。
+ */
+function negotiateVersion(clientVersion, supportedVersions) {
+    const clientMajor = parseMajor(clientVersion);
+    if (clientMajor === null)
+        return null;
+    let best = null;
+    let bestMajor = -1;
+    for (const v of supportedVersions) {
+        const major = parseMajor(v);
+        if (major === null)
+            continue;
+        if (major <= clientMajor && major > bestMajor) {
+            best = v;
+            bestMajor = major;
+        }
+    }
+    return best;
+}
+/** 从 semver 字符串中提取主版本号 */
+function parseMajor(version) {
+    const m = /^(\d+)/.exec(version);
+    return m ? Number(m[1]) : null;
+}
+/* ================================================================== */
+/*  标准错误码（JSON-RPC 2.0 + 自定义扩展）                               */
+/* ================================================================== */
+/** JSON-RPC 2.0 标准错误码 — 固定不变 */
+exports.JSONRPC_STANDARD_ERRORS = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
+/** 自定义错误码注册表 */
+exports.BUILTIN_CUSTOM_ERRORS = [
+    (0, registry_js_1.builtInEntry)('EXECUTION_TIMEOUT', 'skill.error', -32001),
+    (0, registry_js_1.builtInEntry)('EXECUTION_FAILED', 'skill.error', -32002),
+    (0, registry_js_1.builtInEntry)('RESOURCE_EXHAUSTED', 'skill.error', -32003),
+    (0, registry_js_1.builtInEntry)('POLICY_VIOLATION', 'skill.error', -32004),
+    (0, registry_js_1.builtInEntry)('DEPENDENCY_ERROR', 'skill.error', -32005),
+    (0, registry_js_1.builtInEntry)('CAPABILITY_DENIED', 'skill.error', -32006),
+];
+exports.skillErrorCodeRegistry = (0, registry_js_1.createRegistry)(exports.BUILTIN_CUSTOM_ERRORS);
+/** 向后兼容的完整错误码对象（合并标准+自定义） */
+exports.SKILL_RPC_ERRORS = {
+    ...exports.JSONRPC_STANDARD_ERRORS,
+    EXECUTION_TIMEOUT: -32001,
+    EXECUTION_FAILED: -32002,
+    RESOURCE_EXHAUSTED: -32003,
+    POLICY_VIOLATION: -32004,
+    DEPENDENCY_ERROR: -32005,
+    CAPABILITY_DENIED: -32006,
+};
+/* ================================================================== */
+/*  方法名常量                                                          */
+/* ================================================================== */
+exports.SKILL_RPC_METHODS = {
+    INITIALIZE: "skill.initialize",
+    EXECUTE: "skill.execute",
+    HEARTBEAT: "skill.heartbeat",
+    SHUTDOWN: "skill.shutdown",
+    /** 通知方法 */
+    PROGRESS: "skill.progress",
+    LOG: "skill.log",
+};
+/* ================================================================== */
+/*  RPC 解析失败计数器                                                   */
+/* ================================================================== */
+let rpcParseFailureCount = 0;
+/** 获取 RPC 解析失败累计次数（可观测性 / 健康检查用） */
+function getRpcParseFailures() { return rpcParseFailureCount; }
+/* ================================================================== */
+/*  辅助函数                                                            */
+/* ================================================================== */
+/** 创建 JSON-RPC 请求 */
+function createRpcRequest(id, method, params) {
+    return { jsonrpc: exports.SKILL_RPC_JSONRPC, id, method, params };
+}
+/** 创建 JSON-RPC 成功响应 */
+function createRpcSuccess(id, result) {
+    return { jsonrpc: exports.SKILL_RPC_JSONRPC, id, result };
+}
+/** 创建 JSON-RPC 错误响应 */
+function createRpcError(id, code, message, data) {
+    return { jsonrpc: exports.SKILL_RPC_JSONRPC, id, error: { code, message, ...(data !== undefined ? { data } : {}) } };
+}
+/** 创建通知消息 */
+function createRpcNotification(method, params) {
+    return { jsonrpc: exports.SKILL_RPC_JSONRPC, method, params };
+}
+/** 序列化为 NDJSON 行 */
+function serializeRpcMessage(msg) {
+    return JSON.stringify(msg) + "\n";
+}
+/** 从 NDJSON 行反序列化 */
+function parseRpcMessage(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const obj = JSON.parse(trimmed);
+        if (obj && typeof obj === "object" && obj.jsonrpc === "2.0")
+            return obj;
+        return null;
+    }
+    catch {
+        rpcParseFailureCount++;
+        return null;
+    }
+}
+/** 判断是否为请求 */
+function isRpcRequest(msg) {
+    return "method" in msg && "id" in msg;
+}
+/** 判断是否为通知 */
+function isRpcNotification(msg) {
+    return "method" in msg && !("id" in msg);
+}
+/** 判断是否为响应 */
+function isRpcResponse(msg) {
+    return !("method" in msg) && "id" in msg;
+}
+/** 判断是否为错误响应 */
+function isRpcError(msg) {
+    return "error" in msg;
+}
+//# sourceMappingURL=skill-rpc.js.map

package/dist/skill-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-rpc.js","sourceRoot":"","sources":["../src/skill-rpc.ts"],"names":[],"mappings":"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"}

package/dist/state-machine.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Unified Runtime State Machine.
+ *
+ * Defines canonical status enums, legal transition tables, and transition
+ * functions for Step, Run, and CollabPhase statuses.
+ *
+ * Shared across API and Worker.
+ */
+export declare const STEP_STATUSES: readonly ["pending", "running", "paused", "needs_approval", "needs_device", "needs_arbiter", "streaming", "succeeded", "failed", "deadletter", "canceled"];
+export type StepStatus = (typeof STEP_STATUSES)[number];
+export declare const STEP_TERMINAL: ReadonlySet<StepStatus>;
+export declare const STEP_BLOCKING: ReadonlySet<StepStatus>;
+export declare const STEP_STREAMING: ReadonlySet<StepStatus>;
+export declare const STEP_TRANSITIONS: Readonly<Record<StepStatus, ReadonlySet<StepStatus>>>;
+export declare const RUN_STATUSES: readonly ["created", "queued", "running", "paused", "needs_approval", "needs_device", "needs_arbiter", "succeeded", "failed", "canceled", "stopped", "compensating", "compensated"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+export declare const RUN_TERMINAL: ReadonlySet<RunStatus>;
+export declare const RUN_TRANSITIONS: Readonly<Record<RunStatus, ReadonlySet<RunStatus>>>;
+export declare const COLLAB_PHASES: readonly ["planning", "executing", "paused", "needs_approval", "needs_device", "needs_arbiter", "succeeded", "failed", "stopped"];
+export type CollabPhase = (typeof COLLAB_PHASES)[number];
+export declare const COLLAB_TERMINAL: ReadonlySet<CollabPhase>;
+export declare const COLLAB_TRANSITIONS: Readonly<Record<CollabPhase, ReadonlySet<CollabPhase>>>;
+export interface TransitionViolation {
+    entity: "step" | "run" | "collab" | "agent";
+    from: string;
+    to: string;
+    message: string;
+}
+export declare function transitionStep(from: StepStatus, to: StepStatus): StepStatus;
+export declare function transitionRun(from: RunStatus, to: RunStatus): RunStatus;
+export declare function transitionCollab(from: CollabPhase, to: CollabPhase): CollabPhase;
+export interface TransitionResult<T extends string> {
+    ok: boolean;
+    status: T;
+    violation?: TransitionViolation;
+}
+export declare function tryTransitionStep(from: StepStatus, to: StepStatus): TransitionResult<StepStatus>;
+export declare function tryTransitionRun(from: RunStatus, to: RunStatus): TransitionResult<RunStatus>;
+export declare function tryTransitionCollab(from: CollabPhase, to: CollabPhase): TransitionResult<CollabPhase>;
+export declare function normalizeStepStatus(raw: unknown): StepStatus | null;
+export declare function normalizeRunStatus(raw: unknown): RunStatus | null;
+export declare function normalizeCollabPhase(raw: unknown): CollabPhase | null;
+export interface StateInvariantViolation {
+    code: string;
+    severity: "error" | "warn";
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare function checkStateInvariant(params: {
+    runStatus: string;
+    steps: Array<{
+        stepId: string;
+        status: string;
+    }>;
+    collabPhase?: string | null;
+    agentPhase?: string | null;
+}): StateInvariantViolation[];
+export declare const AGENT_PHASES: readonly ["idle", "planning", "thinking", "deciding", "acting", "waiting", "blocked", "completed", "failed", "timeout"];
+export type AgentPhase = (typeof AGENT_PHASES)[number];
+export declare const AGENT_TRANSITIONS: Readonly<Record<AgentPhase, ReadonlySet<AgentPhase>>>;
+export declare const AGENT_TERMINAL: ReadonlySet<AgentPhase>;
+/** 安全转换 Agent 阶段（返回结果对象，不抛异常） */
+export declare function tryTransitionAgent(from: AgentPhase, to: AgentPhase): TransitionResult<AgentPhase>;
+/** 硬转换 Agent 阶段（违反时抛异常） */
+export declare function transitionAgent(from: AgentPhase, to: AgentPhase): AgentPhase;
+/** 判断是否为 Agent 终态 */
+export declare function isAgentTerminal(phase: AgentPhase): boolean;
+/**
+ * 将 OrchestrationPhase 字符串映射到 AgentPhase。
+ * 用于桥接旧编排系统与新 Agent 状态机。
+ */
+export declare function mapOrchestrationToAgent(phase: string): AgentPhase;
+/**
+ * 将 AgentPhase 映射回 OrchestrationPhase 字符串。
+ */
+export declare function mapAgentToOrchestration(phase: AgentPhase): string;
+//# sourceMappingURL=state-machine.d.ts.map