插件运行时辅助函数

// 解析 Agent 的工作目录（必须提供 agentId）const agentDir = api.runtime.agent.resolveAgentDir(cfg, agentId); // 解析 Agent 工作区const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId); // 获取 Agent 身份const identity = api.runtime.agent.resolveAgentIdentity(cfg); // 获取默认思考级别const thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // 根据当前提供商配置验证用户提供的思考级别const policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });const level = api.runtime.agent.normalizeThinkingLevel("extra high");if (level && policy.levels.some((entry) => entry.id === level)) {  // 将级别传给嵌入式运行} // 获取 Agent 超时时间const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // 确保工作区存在await api.runtime.agent.ensureAgentWorkspace(cfg); // 运行嵌入式 Agent 轮次const result = await api.runtime.agent.runEmbeddedAgent({  sessionId: "my-plugin:task-1",  runId: crypto.randomUUID(),  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg, agentId),  prompt: "总结最新更改",  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),});

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {  // 遍历会话行，而不依赖旧版 sessions.json 结构。}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),}); const created = await api.runtime.agent.session.createSessionEntry({  cfg,  key: "agent:main:my-plugin:task-1",  initialEntry: {    agentHarnessId: "my-harness",    modelSelectionLocked: true,    pluginExtensions: { "my-plugin": { phase: "initializing" } },  },  afterCreate: async () => ({    pluginExtensions: { "my-plugin": { phase: "ready" } },  }),}); const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });await api.runtime.agent.session.runWithWorkAdmission(  { storePath, sessionKey },  async (signal) => {    // 创建或更新会话，然后将 signal 传给已准入的 Agent 运行。  },);

const model = api.runtime.agent.defaults.model; // 例如 "gpt-5.6-sol"const provider = api.runtime.agent.defaults.provider; // 例如 "openai"

const result = await api.runtime.llm.complete({  messages: [{ role: "user", content: "总结此转录。" }],  purpose: "my-plugin.summary",  maxTokens: 512,  temperature: 0.2,  reasoning: "high",});

const lease = await api.runtime.llm.acquireLocalService(  {    providerId,    baseUrl,    headers,  },  signal,);try {  // 发送并完整读取提供商请求。} finally {  await lease?.release();}

if (await api.runtime.gateway.isAvailable()) {  const result = await api.runtime.gateway.request<{ callId: string }>(    "voicecall.start",    { to: "+15550001234", mode: "conversation" },    { timeoutMs: 60_000 },  );}

// 启动子智能体运行const { runId } = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "将此查询扩展为重点明确的后续搜索。",  toolsAlsoAllow: ["my_plugin_progress"],  provider: "openai", // 可选覆盖  model: "gpt-5.6-sol", // 可选覆盖  deliver: false,}); // 等待完成const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // 读取会话消息const { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // 删除会话await api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

const authority = api.runtime.sandbox.resolveWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,}); const liveAuthority = await api.runtime.sandbox.prepareWorkspaceAuthority({  config: cfg,  agentId,  sessionKey,  workspaceDir,  confinedToolNames: ["my_plugin_safe_tool"],});

const { nodes } = await api.runtime.nodes.list({ connected: true }); const result = await api.runtime.nodes.invoke({  nodeId: "mac-studio",  command: "my-plugin.command",  params: { action: "start" },  timeoutMs: 30000,});

const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); const created = taskFlow.createManaged({  controllerId: "my-plugin/review-batch",  goal: "审查新的拉取请求",}); const child = taskFlow.runTask({  flowId: created.flowId,  runtime: "acp",  childSessionKey: "agent:main:subagent:reviewer",  task: "审查 PR #123",  status: "running",  startedAt: Date.now(),}); const waiting = taskFlow.setWaiting({  flowId: created.flowId,  expectedRevision: created.revision,  currentStep: "await-human-reply",  waitJson: { kind: "reply", channel: "telegram" },});

// 标准 TTSconst clip = await api.runtime.tts.textToSpeech({  text: "来自 OpenClaw 的问候",  cfg: api.config,}); // 针对电话通信优化的 TTSconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "来自 OpenClaw 的问候",  cfg: api.config,}); // 列出可用语音const voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

// 描述图像const image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // 转写音频const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  mime: "audio/ogg", // 可选，适用于无法推断 MIME 的情况}); // 描述视频const video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // 通用文件分析const result = await api.runtime.mediaUnderstanding.runFile({  filePath: "/tmp/inbound-file.pdf",  cfg: api.config,}); // 通过指定的提供商/模型执行结构化图像提取。// 至少包含一张图像；文本输入用于补充上下文。const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.6-sol",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "优先采用印刷的总金额，而不是手写备注。" },  ],  instructions: "提取商家、总金额和可搜索的标签。",  schemaName: "receipt.evidence",  jsonSchema: {    type: "object",    properties: {      vendor: { type: "string" },      total: { type: "number" },      tags: { type: "array", items: { type: "string" } },    },    required: ["vendor", "total"],  },  cfg: api.config,});

const result = await api.runtime.imageGeneration.generate({  prompt: "一个正在绘制日落的机器人",  cfg: api.config,}); const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

const result = await api.runtime.videoGeneration.generate({  prompt: "日出时飞越海岸线的无人机航拍镜头",  cfg: api.config,}); const providers = api.runtime.videoGeneration.listProviders({ cfg: api.config });

const result = await api.runtime.musicGeneration.generate({  prompt: "适合编程时聆听的欢快 lo-fi 曲目",  cfg: api.config,}); const providers = api.runtime.musicGeneration.listProviders({ cfg: api.config });

const providers = api.runtime.webSearch.listProviders({ config: api.config }); const result = await api.runtime.webSearch.search({  config: api.config,  args: { query: "OpenClaw 插件 SDK", count: 5 },});

const webMedia = await api.runtime.media.loadWebMedia(url);const mime = await api.runtime.media.detectMime(buffer);const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);const metadata = await api.runtime.media.getImageMetadata(filePath);const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });const terminalQr = await api.runtime.media.renderQrTerminal("https://openclaw.ai");const pngQr = await api.runtime.media.renderQrPngBase64("https://openclaw.ai", {  scale: 6, // 1-12  marginModules: 4, // 0-16});const pngQrDataUrl = await api.runtime.media.renderQrPngDataUrl("https://openclaw.ai");const tmpRoot = resolvePreferredOpenClawTmpDir();const pngQrFile = await api.runtime.media.writeQrPngTempFile("https://openclaw.ai", {  tmpRoot,  dirPrefix: "my-plugin-qr-",  fileName: "qr.png",});

const cfg = api.runtime.config.current();await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

await api.runtime.system.enqueueSystemEvent(event);api.runtime.system.requestHeartbeat({  source: "other",  intent: "event",  reason: "plugin-event",});api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // 已弃用的兼容性别名。const heartbeatResult = await api.runtime.system.runHeartbeatOnce({  reason: "plugin-triggered-check",});const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);const hint = api.runtime.system.formatNativeDependencyHint(pkg);

api.runtime.events.onAgentEvent((event) => {  /* ... */});api.runtime.events.onSessionTranscriptUpdate((update) => {  /* ... */});

const verbose = api.runtime.logging.shouldLogVerbose();const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); // 可直接用于请求的身份验证，包括提供商运行时交换（例如 OAuth 刷新）const runtimeAuth = await api.runtime.modelAuth.getRuntimeAuthForModel({ model, cfg }); const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({  provider: "openai",  cfg,});

const stateDir = api.runtime.state.resolveStateDir(process.env);const store = api.runtime.state.openKeyedStore<MyRecord>({  namespace: "my-feature",  maxEntries: 200,  defaultTtlMs: 15 * 60_000,}); await store.register("key-1", { value: "hello" });const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });const value = await store.lookup("key-1");await store.deleteIf?.("key-1", (current) => current.value === "hello");await store.consume("key-1");await store.clear(); const blobs = api.runtime.state.openBlobStore<MyBlobMetadata>({  namespace: "rendered-artifacts",  maxEntries: 100,  maxBytesPerEntry: 4 * 1024 * 1024,  maxBytesPerNamespace: 64 * 1024 * 1024,  defaultTtlMs: 15 * 60_000,});await blobs.register(  "artifact-1",  new TextEncoder().encode("binary or text payload"),  { contentType: "text/plain" },);const blob = await blobs.lookup("artifact-1"); await api.runtime.state.withLease(  {    namespace: "my-feature",    key: "writer",    database: { scope: "agent", agentId },    leaseMs: 5 * 60_000,    waitMs: 30_000,  },  async ({ signal, assertOwned }) => {    await runExternalWriter({ signal });    assertOwned();  },);

const saved = await api.runtime.channel.media.saveRemoteMedia({  url,  subdir: "inbound",  maxBytes,  filePathHint: fileName,});

const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {  mentionRegexes,  mentionPatterns,}); const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({  facts: {    canDetectMention: true,    wasMentioned: mentionMatch.matched,    implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(      "reply_to_bot",      isReplyToBot,    ),  },  policy: {    isGroup,    requireMention,    allowTextCommands,    hasControlCommand,    commandAuthorized,  },});