@ai-setting/roy-agent-core 1.7.51 → 1.7.53

package/dist/env/context/env-context.d.ts

@@ -0,0 +1,420 @@
+/**
+ * @fileoverview EnvContext - 线程级事件上下文
+ * 用于在异步调用链中传递所有相关上下文信息
+ *
+ * 解决的问题：
+ * - EventSource 发出的 EnvEvent 信息需要传递到各 Hook 点
+ * - 避免层层传递导致的接口污染
+ *
+ * 使用方式：
+ * - 在 AgentComponent.run() 开始时设置 EnvContext
+ * - 任何地方通过 getEnvContext() 获取
+ * - Hook/Plugin 中使用 getEnvContextOrEmpty()
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import { type EventEnvelope } from "./env-event";
+export { type EventEnvelope, type EventSource, EVENT_ENV_PREFIX, serializeEventToEnv, restoreEventFromEnv, isLarkEvent, isGithubEvent, isJiraEvent, getLarkMessageId, getLarkChatId, getLarkUserId, } from "./env-event";
+/**
+ * ReplyChannel - 回复通道接口
+ *
+ * 基于 lark-cli 接口设计：
+ * - messages-send: 需要 userId/chatId + content + as
+ * - messages-reply: 需要 messageId + content + as
+ *
+ * 使用示例：
+ * ```typescript
+ * // 发送消息到用户
+ * await replyChannel.sendText("Hello!");
+ * await replyChannel.sendMarkdown("**Bold** text");
+ *
+ * // 回复原消息
+ * await replyChannel.reply({ text: "Reply content" });
+ * ```
+ */
+export interface ReplyChannel {
+    /** 渠道类型，如 "lark" */
+    type: string;
+    /** 消息 ID（用于回复，om_xxx 格式） */
+    messageId?: string;
+    /** 用户 ID（用于发送，ou_xxx 格式） */
+    userId?: string;
+    /** 聊天 ID（用于发送，oc_xxx 格式） */
+    chatId?: string;
+    /**
+     * 飞书应用 ID（cli_xxx 格式，多 appId 场景用）
+     *
+     * ★ 用于在新建群聊时通过 --bots <appId> 把 bot 自动拉入群聊。
+     * 例如 PerTaskGroupChatPlugin 创建 task 群聊时会读这个字段来决定邀请哪个 bot 加入群。
+     *
+     * 数据来源：lark-cli event header.app_id 或 eventsource config.appId。
+     */
+    appId?: string;
+    /** 身份类型：bot | user */
+    identity?: "bot" | "user";
+    /**
+     * lark-cli profile（多 appId 场景用，#1637）
+     *
+     * 飞书 openId 是 per-app 隔离的,不同 event-source 对应不同 appId,
+     * 回复时必须用对应 app 的 lark-cli profile 才能成功。
+     * 错误使用 profile 会导致 `open_id cross app` 错误(99992361)。
+     *
+     * 不设置时使用 lark-cli 的 active profile(默认行为)。
+     */
+    profile?: string;
+    /**
+     * 发送文本消息
+     * 调用 lark-cli: im +messages-send --user-id/--chat-id --text
+     */
+    sendText(text: string): Promise<void>;
+    /**
+     * 发送 Markdown 消息
+     * 调用 lark-cli: im +messages-send --user-id/--chat-id --markdown
+     */
+    sendMarkdown(markdown: string): Promise<void>;
+    /**
+     * 发送富文本消息（JSON content）
+     * 调用 lark-cli: im +messages-send --content
+     */
+    sendMessage(message: unknown): Promise<void>;
+    /**
+     * 回复指定消息（使用 messageId）
+     * 调用 lark-cli: im +messages-reply --message-id
+     */
+    reply(message: unknown): Promise<void>;
+}
+/**
+ * EnvContext - 事件上下文
+ *
+ * 包含请求处理的所有相关信息，可在任意层级获取
+ *
+ * 设计原则：
+ * 1. rawEvent 存储完整的 EnvEvent，Plugin 按需从其中提取字段
+ * 2. replyChannel 由 EnvEvent 中的 replyChannel 构建
+ * 3. sourceId、userId 等可作为快捷访问字段（从 EnvEvent 提取）
+ */
+/**
+ * LarkEventContext - DEPRECATED: 飞书事件 payload 容器 (Task #2326 → Task #2331)
+ *
+ * @deprecated Task #2331 重构：env context 已通用化为 EventEnvelope。
+ * 请使用 EventEnvelope 替代，通过 source='lark' + payload 包含 lark 字段。
+ * lark-cli plugin 内部用 getLarkMessageId()/getLarkChatId()/getLarkUserId() 提取字段。
+ *
+ * 保留这个 type alias 用于：
+ * 1. 文档/迁移说明引用
+ * 2. 第三方代码可能 import 这个类型
+ *
+ * 新代码请使用 EventEnvelope (来自 './env-event')。
+ */
+export interface LarkEventContext {
+    /** 飞书消息 ID（om_xxx 格式） */
+    messageId: string;
+    /** 飞书聊天 ID（oc_xxx 格式） */
+    chatId?: string;
+    /** 用户 open_id（ou_xxx 格式） */
+    userId?: string;
+    /** 聊天类型：p2p | group | channel */
+    chatType?: "p2p" | "group" | "channel" | string;
+    /** 事件接收时间戳（毫秒） */
+    receivedAt?: number;
+    /** lark-cli profile 名（多 appId 场景） */
+    profile?: string;
+    /** 飞书 app ID（multi-appId 场景） */
+    appId?: string;
+}
+export interface EnvContext {
+    /**
+     * 完整的 EnvEvent，包含所有事件信息
+     *
+     * 【优先级策略】effective 优先，parent 兜底
+     * 在 AgentComponent 构建 EnvContext 时：
+     * - 优先使用 effectiveContext.envEvent（当前层级显式传入的 envEvent）
+     * - 如果 effectiveContext 未设置，则回退到 parentEnvContext.envEvent（继承父级 ALS 上下文）
+     *
+     * 参考实现：agent-component.ts 中 EnvContext 构建逻辑
+     * ```
+     * envEvent: effectiveContext.envEvent ?? parentEnvContext?.envEvent,
+     * ```
+     */
+    envEvent: unknown;
+    /** 事件源 ID（EventSource 配置的 ID） */
+    sourceId: string;
+    /** 事件源类型（EventSource 类型，如 lark-cli、bounty-im、timer 等） */
+    sourceType?: string;
+    /** 用户 ID（从 EnvEvent 提取） */
+    userId: string;
+    /**
+     * 飞书 messageId（om_xxx 格式，从 im.message.receive_v1 事件提取）
+     *
+     * 设计目的：
+     * - 子 Agent（delegate_task 派生的 sub-agent）能拿到原 user query 的 messageId，
+     *   让所有 sub-agent 的飞书回复都通过 +messages-reply 关联回原 query。
+     * - 与 replyChannel.messageId 保持一致（冗余设计，简化访问）。
+     *
+     * 优先级（agent-component.ts 中构建子 EnvContext 时）：
+     * - parentEnvContext.messageId 优先（继承父级 ALS 上下文）
+     * - effectiveContext.metadata?.messageId 兜底
+     *
+     * ⚠️ 历史背景：之前只有 replyChannel.messageId，没有顶层 messageId，
+     *    导致 delegate_task 派生的 sub-agent 读取 effectiveContext.metadata?.messageId
+     *    拿不到原 messageId（sub-session metadata 不包含）。
+     */
+    messageId?: string;
+    /** Trace ID（用于完整会话链路追踪） */
+    traceId?: string;
+    /** Request ID（每个请求唯一） */
+    requestId?: string;
+    /**
+     * 回复通道（由 EnvEvent 构建）
+     *
+     * 【优先级策略】parent 优先，effective 兜底
+     * 在 AgentComponent 构建 EnvContext 时：
+     * - 优先继承父级 ALS 上下文的 replyChannel（确保子 Agent 能通过父级通道回复）
+     * - 仅在父级没有 replyChannel 时，尝试从 effectiveContext.envEvent.metadata 提取
+     *
+     * 与 envEvent 的优先级策略不同：
+     * - envEvent: effective 优先（当前层级的 envEvent 覆盖父级）
+     * - replyChannel: parent 优先（继承父级的回复通道，避免子 Agent 构建新通道丢失上下文）
+     *
+     * 参考实现：agent-component.ts 中 EnvContext 构建逻辑
+     * ```
+     * replyChannel: parentEnvContext?.replyChannel ?? (effectiveContext.envEvent as any)?.metadata?.replyChannel,
+     * ```
+     */
+    replyChannel?: ReplyChannel;
+    /** 插件启用状态 { "sourceId:pluginName": true } */
+    pluginEnabled?: Record<string, boolean>;
+    /** 启用的插件列表 */
+    plugins?: string[];
+    /**
+     * 群聊绑定的父任务 ID
+     *
+     * 当 EventSource 收到的飞书消息来自 per-task 群聊时，handleEvent 会从
+     * SessionComponent 查 chat_id → task_id 绑定并注入到这里。
+     *
+     * 用途：
+     * - task_create tool 在用户没显式传 parent_task_id 时，自动用这个值
+     *   作为新任务的父任务，让群消息触发的子任务挂到群绑定的任务下（避免根任务爆炸）
+     * - delegate_task 派生 sub-agent 时透传给子 EnvContext
+     *
+     * 注意：
+     * - undefined 表示无绑定（普通消息 / CLI 触发）
+     * - 用户在 tool 调用里显式传 parent_task_id 优先于该字段
+     */
+    parentTaskId?: number;
+    /** 时间戳 */
+    timestamp?: number;
+    /**
+     * 通用 event envelope (Task #2331 重构)
+     *
+     * 设计目的：
+     * - 把 lark 专属字段通用化,支持任意 event source (lark/github/jira/calendar/email)
+     * - EnvContext 不再绑定 lark 字段, 避免未来加新 source 时污染环境
+     * - lark-cli plugin 内部通过 getLarkMessageId()/getLarkChatId()/getLarkUserId() 做类型转换
+     *
+     * 字段说明：
+     * - source: event 来源 ('lark' | 'github' | 'jira' | 'calendar' | 'email' | 'unknown')
+     * - id: source 内 ID (lark message_id om_xxx, github issue number 等)
+     * - receivedAt: ISO 8601 timestamp
+     * - payload: 原始 payload (保持原样)
+     * - metadata: 业务级扩展字段 (任意 source 可自定义)
+     *
+     * 与顶层 messageId 的关系：
+     * - messageId 是顶层快速访问字段（从 event.id 推导, lark source 时有效）
+     * - event 是完整 event envelope (任何 source 都有)
+     * - 两者并存: event 提供 "事件是什么", messageId 提供 "lark 便捷访问"
+     *
+     * 通过 spread 父 EnvContext 自动传播, delegate_task sub-agent 也能拿到原 event 上下文。
+     */
+    event?: EventEnvelope;
+    /**
+     * 共享可变状态——父子 Agent 持有同一引用
+     *
+     * 子 Agent 通过 spread 展开父 context 时，agentContext 是引用共享而非值拷贝。
+     * 因此子 Agent 对 agentContext 内部字段的修改（如 currentTaskId），
+     * 父 Agent 立即可见。
+     *
+     * 设计目的：
+     * - 子 Agent 创建 Task 后，父 Agent 能感知到 currentTaskId
+     * - workflow 的多个 agent node 之间共享 currentTaskId
+     * - 替代旧的 _parentEnvContext 引用机制和 hasParentContextCycle 检测
+     *
+     * @example
+     * ```typescript
+     * // 父 context 持有 agentContext 引用
+     * const parentCtx = { ..., agentContext: {} };
+     * // 子 context spread 父级，agentContext 是同一个引用
+     * const childCtx = { ...parentCtx };
+     * // 子写
+     * childCtx.agentContext.currentTaskId = 42;
+     * // 父读——立即可见！
+     * parentCtx.agentContext.currentTaskId === 42  // true
+     * ```
+     */
+    agentContext?: {
+        /** 当前正在处理的 Task ID（由 task_create 设置，task_complete 清除） */
+        currentTaskId?: number;
+    };
+}
+declare const envContextStorage: AsyncLocalStorage<EnvContext>;
+export { envContextStorage };
+/**
+ * 获取当前 EnvContext
+ *
+ * @returns 当前线程的 EnvContext，如果不存在则返回 undefined
+ */
+export declare function getEnvContext(): EnvContext | undefined;
+/**
+ * 获取当前 EnvContext，如果不存在则返回空对象（安全访问）
+ *
+ * @returns 当前线程的 EnvContext，从不返回 undefined
+ */
+export declare function getEnvContextOrEmpty(): Partial<EnvContext>;
+/**
+ * 检查是否存在 EnvContext
+ */
+export declare function hasEnvContext(): boolean;
+/**
+ * 获取当前正在处理的 Task ID
+ *
+ * 由 task_create 工具设置，task_complete 工具清除。
+ * 在 LLM 调用时，additionInfo 会包含此信息，提醒 LLM 当前任务上下文。
+ *
+ * 通过 agentContext 共享引用读取，父子 Agent 看到同一值。
+ *
+ * @returns 当前 Task ID，如果不存在则返回 undefined
+ */
+export declare function getCurrentTaskId(): number | undefined;
+/**
+ * 在指定 EnvContext 中执行函数
+ *
+ * @param context 要设置的 EnvContext
+ * @param fn 要执行的函数
+ * @returns 函数返回值
+ */
+export declare function runWithEnvContext<T>(context: EnvContext | undefined, fn: () => T): T;
+/**
+ * 在指定 EnvContext 中执行异步函数
+ *
+ * @param context 要设置的 EnvContext
+ * @param fn 要执行的异步函数
+ * @returns Promise resolving to 函数返回值
+ */
+export declare function runWithEnvContextAsync<T>(context: EnvContext | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * EnvContext 创建参数
+ */
+export interface CreateEnvContextOptions {
+    /** 完整的 EnvEvent（必填） */
+    envEvent: unknown;
+    /** 事件源 ID（必填） */
+    sourceId: string;
+    /** 用户 ID（必填） */
+    userId: string;
+    /**
+     * 飞书 messageId（可选，Task #2326）
+     *
+     * 从 lark `im.message.receive_v1` 事件提取的 messageId（om_xxx 格式）。
+     * 透传到 EnvContext 后，子 Agent 通过 `getEnvContext()?.messageId` 拿到，
+     * 让飞书回复优先用 `+messages-reply --message-id` 关联回原 user query。
+     *
+     * 传值时同时存入 EnvContext.messageId 和 replyChannel.messageId（如果 replyChannel 已有 messageId 则不覆盖）。
+     */
+    messageId?: string;
+    /**
+     * 通用 event envelope (Task #2331 重构)
+     *
+     * 推荐用此字段替代单独的 messageId —— 保留完整 event 上下文,
+     * 子 Agent 可按需访问任何 source-specific 字段。
+     *
+     * 如果传了 event, 同时会从 event.id 提取 messageId (顶层字段 + replyChannel.messageId).
+     * 如果 event.source === 'lark' 且 payload 是 lark message, messageId 等于 om_xxx 格式.
+     */
+    event?: EventEnvelope;
+    /** Trace ID（可选，自动生成） */
+    traceId?: string;
+    /** Request ID（可选，自动生成） */
+    requestId?: string;
+    /** 回复通道（可选，从 envEvent 构建） */
+    replyChannel?: ReplyChannel;
+    /** 插件启用状态（可选，从 envEvent.metadata 构建） */
+    pluginEnabled?: Record<string, boolean>;
+    /** 启用的插件列表（可选） */
+    plugins?: string[];
+    /** 时间戳（可选，自动生成） */
+    timestamp?: number;
+    /**
+     * 父任务 ID（可选，Task #4023）
+     *
+     * 由 EventSource 在 handleEvent 阶段从 chat_id → task_id 绑定注入。
+     * task_create tool 在用户没显式传 parent_task_id 时优先使用此值。
+     */
+    parentTaskId?: number;
+}
+/**
+ * 规范化 chat↔task 绑定注入的父任务 ID（Task #4023）。
+ *
+ * 只接受正整数：task id 从 1 开始，0 / 负数 / 非整数 / 字符串 / null /
+ * undefined 一律视为"无绑定"（返回 undefined）。event-source-handlers 与
+ * agent-component 共用同一套校验，避免两侧判定不一致导致注入断链。
+ */
+export declare function normalizeParentTaskId(value: unknown): number | undefined;
+/**
+ * 解析本次 Agent run 生效的父任务 ID（Task #4023）。
+ *
+ * 优先级（高 → 低）：
+ *   1. 本次事件 `envEvent.metadata.parentTaskId`（event-source-handlers 从
+ *      chat↔task 绑定注入，是"本次消息属于哪个群任务"的权威来源）
+ *   2. 上游 ALS EnvContext 的 `parentTaskId`（delegate_task 派生的 sub-agent
+ *      继承父级绑定）
+ *
+ * 提取出来作为纯函数，便于单测覆盖"envEvent → EnvContext.parentTaskId"这一
+ * 曾断链的映射（此前该映射不存在，导致 task_create 永远拿不到绑定父任务）。
+ */
+export declare const resolveEnvParentTaskId: (envEvent: unknown, parentEnvContext?: Partial<EnvContext> | undefined) => number | undefined;
+/**
+ * 创建 EnvContext（便捷函数）
+ *
+ * @param options 创建参数
+ * @returns 完整的 EnvContext，自动生成 traceId、requestId 和 timestamp
+ */
+export declare function createEnvContext(options: CreateEnvContextOptions): EnvContext;
+/**
+ * 合并 EnvContext 到当前上下文
+ *
+ * 🛡️ agentContext 保护：如果传入 partial.agentContext 且当前上下文已有
+ * agentContext，不会替换引用，而是合并属性到现有对象中。
+ * 这是为了确保父子 Agent 间的 agentContext 引用共享不被意外破坏。
+ *
+ * @param partial 要合并的部分 EnvContext
+ *
+ * @example
+ * ```typescript
+ * // ✅ 正确：通过 setCurrentTaskId 修改 currentTaskId
+ * setCurrentTaskId(42);
+ *
+ * // ✅ 安全：mergeEnvContext 处理其他非 agentContext 字段
+ * mergeEnvContext({ sessionId: "xxx" });
+ *
+ * // ⚠️ 不会破坏：agentContext 不会被替换，而是合并
+ * mergeEnvContext({ agentContext: { currentTaskId: 99 } });
+ * // 实际等价于：current.agentContext.currentTaskId = 99
+ * ```
+ */
+export declare function mergeEnvContext(partial: Partial<EnvContext>): void;
+/**
+ * 设置当前正在处理的 Task ID（便捷函数，带 @TracedAs 追踪）
+ *
+ * 通过 wrapFunction 包装，自动创建 OTel Span，
+ * 可在 debug trace / debug span 中查看 currentTaskId 的设置路径
+ *
+ * 写入 agentContext 共享引用，父子 Agent 立即可见。
+ */
+export declare const setCurrentTaskId: (taskId: number | undefined) => void;
+/**
+ * 从 EnvContext 提取 EventEnvelope (Task #2331)
+ *
+ * 优先级: event > replyChannel.messageId (兼容 lark source, 因为 replyChannel 仅含 messageId)
+ *
+ * 如果当前 EnvContext 没有 event 上下文, 返回 undefined.
+ */
+export declare function getEventFromEnvContext(ctx: Partial<EnvContext> | undefined): EventEnvelope | undefined;

package/dist/env/context/env-event.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview EventEnvelope - 通用 event source envelope (Task #2331)
+ *
+ * 设计目的：
+ * - 把 env context 的 lark-specific 字段通用化，支持任意 event source
+ * - 让 EnvContext 不再绑定 lark 专属字段，将来加 github/jira/calendar/email 不污染
+ * - lark-cli plugin 自己在内部做类型转换 (extractLarkFields helper)
+ *
+ * 与 Task #2326 LarkEventContext 的关系：
+ * - LarkEventContext 是 lark 专属字段（messageId/chatId/userId/chatType/...）
+ * - EventEnvelope 是通用 envelope，source 标识 event 来源，payload 是原始 payload
+ * - Lark 事件通过 source='lark' + payload 是 lark message payload 来表达
+ *
+ * 与 replyChannel 的关系：
+ * - replyChannel 是 runtime 通道抽象（sendText/sendMarkdown/reply 等方法）
+ * - event 是 event metadata（用于 prompt 渲染、event 关联、subprocess env 序列化等）
+ * - 两者并存：replyChannel 提供 "怎么回复"，event 提供 "事件是什么"
+ *
+ * 使用示例：
+ * ```typescript
+ * // event-source-handlers.ts 注入 lark event
+ * setEnvContext({
+ *   event: {
+ *     source: 'lark',
+ *     id: messageId,
+ *     receivedAt: new Date().toISOString(),
+ *     payload: rawLarkEvent,
+ *     metadata: { chatType: 'p2p', profile: 'myapp' },
+ *   },
+ * });
+ *
+ * // lark-cli plugin 内部提取 lark 字段
+ * const { messageId, chatId, userId } = extractLarkFields(env);
+ * ```
+ */
+/**
+ * EventSource - 事件来源标识
+ *
+ * 设计原则：
+ * - 字符串字面量而非 enum，方便第三方 plugin 扩展自定义 source
+ * - 已知的 source 列举在这里供 IDE 自动补全，未知 source 用 "unknown"
+ * - 未来加 github/jira/calendar/email 时扩展这个 union
+ */
+export type EventSource = "lark" | "github" | "jira" | "calendar" | "email" | "unknown";
+/**
+ * EventEnvelope - 通用 event 容器
+ *
+ * 字段说明：
+ * - source: event 来源类型（如 'lark'、'github'、'unknown'）
+ * - id: source 内的 event 唯一标识（lark 用 message_id om_xxx，github 用 issue number 等）
+ * - receivedAt: event 接收时间（ISO 8601 字符串，便于跨进程序列化）
+ * - payload: 原始 payload（保持原样，不做类型转换）
+ * - metadata: 业务级扩展字段（任意 source 可自定义的额外信息）
+ *
+ * 不在 envelope 中的字段：
+ * - userId/chatId 等 source-specific 字段：放在 payload 或 metadata 里
+ * - replyChannel: 由 EventSource 单独构建，不混入 envelope
+ */
+export interface EventEnvelope {
+    /** Event 来源标识 */
+    source: EventSource;
+    /** Source 内的 event 唯一 ID（lark message_id、github issue number 等） */
+    id: string;
+    /** Event 接收时间，ISO 8601 格式 */
+    receivedAt: string;
+    /** 原始 payload（不解析，保持原样） */
+    payload?: unknown;
+    /** 业务级扩展字段 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 判断 envelope 是否来自 lark
+ */
+export declare function isLarkEvent(event: EventEnvelope | undefined): event is EventEnvelope;
+/**
+ * 判断 envelope 是否来自 github
+ */
+export declare function isGithubEvent(event: EventEnvelope | undefined): event is EventEnvelope;
+/**
+ * 判断 envelope 是否来自 jira
+ */
+export declare function isJiraEvent(event: EventEnvelope | undefined): event is EventEnvelope;
+/**
+ * 从 lark envelope 提取 messageId (om_xxx 格式)
+ *
+ * 优先级：
+ * 1. event.id（推荐，所有 event source 都用 id 字段存 source-specific ID）
+ * 2. event.payload.message_id（兼容老 payload 嵌套结构）
+ *
+ * 返回 undefined 如果 envelope 不是 lark 来源。
+ */
+export declare function getLarkMessageId(event: EventEnvelope | undefined): string | undefined;
+/**
+ * 从 lark envelope 提取 chatId (oc_xxx 格式)
+ *
+ * 返回 undefined 如果 envelope 不是 lark 来源。
+ */
+export declare function getLarkChatId(event: EventEnvelope | undefined): string | undefined;
+/**
+ * 从 lark envelope 提取 userId (ou_xxx 格式)
+ *
+ * 飞书 sender_id.open_id 嵌套在 payload.event.sender.sender_id 中。
+ *
+ * 返回 undefined 如果 envelope 不是 lark 来源。
+ */
+export declare function getLarkUserId(event: EventEnvelope | undefined): string | undefined;
+/**
+ * ROY_EVENT_* 环境变量前缀。
+ *
+ * 当前架构用 ALS (AsyncLocalStorage) 透传, delegate_task 不真正 spawn subprocess.
+ * 但保留这些 env 变量约定, 未来若需要 subprocess 隔离可直接使用, 无需改协议.
+ *
+ * 字段映射:
+ * - source      → ROY_EVENT_SOURCE
+ * - id          → ROY_EVENT_ID
+ * - receivedAt  → ROY_EVENT_RECEIVED_AT
+ * - payload     → ROY_EVENT_PAYLOAD (JSON 序列化)
+ * - metadata    → ROY_EVENT_METADATA (JSON 序列化)
+ */
+export declare const EVENT_ENV_PREFIX = "ROY_EVENT_";
+/**
+ * 序列化 EventEnvelope 为环境变量字典
+ *
+ * 使用方式 (假设有 subprocess spawn):
+ * ```ts
+ * const env = { ...process.env, ...serializeEventToEnv(event) };
+ * spawn(command, { env });
+ * ```
+ *
+ * 返回空对象当 envelope 缺失。
+ */
+export declare function serializeEventToEnv(event: EventEnvelope | undefined): Record<string, string>;
+/**
+ * 从 process.env 恢复 EventEnvelope
+ *
+ * 使用方式 (subprocess 入口):
+ * ```ts
+ * const event = restoreEventFromEnv(process.env);
+ * if (event) setEnvContext({ event });
+ * ```
+ *
+ * 返回 undefined 当环境变量中没有 ROY_EVENT_SOURCE (表示不是 event-driven 触发)。
+ */
+export declare function restoreEventFromEnv(env?: NodeJS.ProcessEnv): EventEnvelope | undefined;

package/dist/env/context/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview EnvContext 模块导出
+ *
+ * Task #2331: env context 通用化为 EventEnvelope, 替代 lark-specific LarkEventContext.
+ *
+ * 保留 LarkEventContext type alias 用于:
+ * 1. 文档/迁移说明引用
+ * 2. 第三方代码可能 import 这个类型
+ *
+ * 新代码请使用 EventEnvelope (来自 './env-event')。
+ */
+export { type EnvContext, type ReplyChannel, type LarkEventContext, type CreateEnvContextOptions, getEnvContext, getEnvContextOrEmpty, hasEnvContext, runWithEnvContext, runWithEnvContextAsync, createEnvContext, mergeEnvContext, normalizeParentTaskId, resolveEnvParentTaskId, getCurrentTaskId, setCurrentTaskId, envContextStorage, getEventFromEnvContext, type EventEnvelope, type EventSource, EVENT_ENV_PREFIX, serializeEventToEnv, restoreEventFromEnv, } from "./env-context";
+export { isLarkEvent, isGithubEvent, isJiraEvent, getLarkMessageId, getLarkChatId, getLarkUserId, } from "./env-event";