页面 Client API

不需要安装 npm SDK，也不需要传会话 ID 或插件 ID。旧版宿主、普通浏览器标签和外部浏览器里都没有这个对象，所以每次都要做特性检测。可以把 Skill 提供的 client-api.ts 复制到项目中做类型检查，不要在运行时引入它。完整的方法签名、参数、返回类型与能力名称见 Client API 参考；Agent 会话接口见 Agent API 参考。

特性检测

const miniapp = window.mcode?.miniapp;

if (!miniapp?.message?.append) {
  showHint('当前宿主不支持把内容交给输入框');
}
if (miniapp?.window) {
  // 弹出窗口能力可用
}
if (miniapp?.agent) {
  // 宿主提供 Agent 接口，调用仍需对应声明和权限开关
}

message.append(text)

在用户点击按钮的处理函数中调用。宿主会弹出确认框，显示插件、目标会话和文字；用户确认后，文字追加到该会话的输入框。用户可以继续编辑，亲自点击发送后才会开始一轮对话。

async function handToAgent(text, button, status) {
  const message = window.mcode?.miniapp?.message;
  if (!message?.append) {
    status.textContent = '当前宿主不支持把内容交给输入框。';
    return;
  }
  button.disabled = true;
  try {
    await message.append(text);
    status.textContent = '已放进输入框，确认后请自己按发送。';
  } catch (error) {
    const code = error?.message;
    if (code === 'user_cancelled') status.textContent = '已取消，没有添加任何内容。';
    else if (code === 'result_unknown') status.textContent = '先看一下输入框，内容可能已经加进去了。';
    else status.textContent = '没能添加，检查会话后再试。';
  } finally {
    button.disabled = false;
  }
}

text 是纯文本，单次最多 100,000 个 UTF-16 码元。HTML 也按文字处理；换行需包含在文字中。
每次调用都要确认，不支持「记住选择」，也不会自动发送。多次调用按顺序逐个确认。
输入框里已有的文字、引用和附件都会保留。message 命名空间不授予读取聊天记录的能力，也不能改已发送的消息；读取用户会话需要另行声明 session.read，见 Agent API。
失败时 message 是 user_cancelled、invalid_request、text_too_large、not_allowed、target_unavailable 或 result_unknown。遇到 result_unknown 时，提醒用户先看一下输入框，不要自动重发。

按钮上应写清楚去向，比如「交给 Agent」。Promise 成功只代表文字进了输入框，不代表 Agent 已经开始工作。

miniapp.window

这个句柄用于查看和调整 Mini App 自己的窗口，包括页面是在文件面板里（inline），还是弹出为独立窗口（window），以及弹出时的位置、尺寸和窗口属性。接口定义仍可能调整，使用前务必先做特性检测。

const handle = window.mcode?.miniapp?.window;
if (handle) {
  const state = await handle.getState(); // { mode: 'inline' } 或 { mode: 'window', window: {...} }

  // 必要状态应提前保存；切换 mode 必须在同步的点击等用户手势里调用
  popOutButton.onclick = () => handle.update({ mode: 'window', width: 900, height: 650 });

  const subscription = handle.onDidChangeState((next) => render(next.mode));
  addEventListener('pagehide', () => subscription.dispose());
}

v3.1.9 及以上正式版的 getState() 可返回 modeChangeReloadsPage: true。这表示切换 inline / window 会重建页面，逻辑窗口 ID 和 Node 服务保留，但当前文档、内存状态、媒体流、订阅和待完成的 Promise 不会延续。按运行时结果判断，不能假定所有切窗都会重载。
必要状态应先保存，再让用户点击切换；不要在调用前等待异步保存而丢掉用户手势，也不要把必要工作放在 await update({ mode }) 后或依赖旧文档的监听器。目标页面启动后读取 getState()，恢复已保存内容并重新订阅。
v3.1.10 起，需要重建页面的切窗会先由宿主确认，包括关闭独立窗口或按 Cmd/Ctrl+W 收回。用户取消时保留原页面和请求，update() 成功返回当前状态，mode 不一定等于请求值；收到成功回复或状态事件都应检查其中的 mode。完整规则见页面重建与确认。
切换 mode 或调用 focus() 必须来自用户手势，否则直接以 not_permitted 拒绝。
frame、transparent、minWidth、minHeight 只能在 manifest 的 surface.window 里声明，运行时不能改。
alwaysOnTop: true 和 clickThrough: true 只有 manifest 里声明为 true，运行时才能打开。
同一帧内的多次 update 会合并成一次；带 mode 的会立即发出，以免丢掉用户手势。
错误：inline_mode、not_permitted、busy、result_unknown、invalid_request。

弹出窗口的常见坑

设置	要注意
`frame: false`	去掉了系统标题栏和拖动区域，要用 CSS `-webkit-app-region: drag` 自己提供拖动区域
`transparent: true`	只去掉窗口自身的背景，页面的 `body` 背景也要设成透明。宿主已关闭透明窗口的系统阴影，需要阴影就用 CSS 画
窗口高度	窗口不随内容长高。用 `html, body { height: 100%; overflow: hidden }`，让正文区域自己滚动
`clickThrough: true`	只在需要「看得见但不拦点击」时打开，否则整个窗口，包括自己的按钮，都无法点击
`visible: false`	隐藏本身不结束页面，脚本、定时器和网络请求继续运行

miniapp.agent

页面直接发起 Agent 会话，自己渲染工具审批和问卷，或者用 open 把会话交给宿主侧栏。需要在 manifest 里声明 agentAccess，见 Agent API。

设备与系统权限

摄像头和系统通知需要 MiniMax Code v3.1.9 或更新版本。使用这两项时，在 engines.mcode 中声明最低版本，见版本要求。设备访问需要在 miniapp.json 的 deviceAccess 中声明，并在插件详情的权限面板中保持对应开关开启。每次新请求都会检查对应开关；关闭麦克风后，新的录音请求和转写会被拒绝，页面已经持有的音频流仍需自行停止。定位、屏幕捕获等未开放的系统权限默认拒绝。

麦克风与语音转写

miniapp/miniapp.json

{
  "deviceAccess": ["microphone"]
}

页面用 navigator.mediaDevices.getUserMedia({ audio: true }) 录音，录完后调用 window.mcode.miniapp.speech.transcribe。宿主只负责转写，页面自己决定录音何时结束，并负责显示录音状态、停止音频流的所有 track。

// audio 必须已经是 16 kHz、单声道、s16 little-endian PCM 样本。
async function transcribeRecordedAudio(audio) {
  const speech = window.mcode?.miniapp?.speech;
  if (!speech) throw new Error('speech_unavailable');
  return speech.transcribe({
    audio,
    format: { sampleRate: 16000, channelCount: 1, sampleFormat: 's16' },
  }); // Promise<{ text }>
}

audio 接受 Int16Array、ArrayBuffer 或其 view，至少一个样本，最多 16,000,000 字节（500 秒）。录音需先转成上述 PCM 格式；不要直接传 MediaRecorder 产物或 WAV、WebM、Ogg、FLAC、MP3 文件。
可传第二个参数 { onPartial: (text) => ... } 接收宿主处理期间的阶段文本；它不是录音过程中的实时字幕。
同一 Mini App 同时只能有一个转写，第二个返回 busy。未声明或权限关闭返回 not_permitted；宿主未登录或语音识别关闭返回 runtime_unavailable。页面关闭或重载会结束在途转写。

摄像头

在 manifest 中声明 deviceAccess: ["camera"] 并开启对应权限后，页面通过标准 Web API 获取摄像头画面：

async function startCamera(video) {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  video.srcObject = stream;
  return () => {
    stream.getTracks().forEach((track) => track.stop());
    video.srcObject = null;
  };
}

页面需显示采集状态，并在用户结束拍摄或预览时调用返回的停止函数。首次使用时，操作系统可能询问是否允许宿主应用访问摄像头。同时请求音视频时，需要声明并开启 microphone 和 camera 两项；任一项关闭，整个请求都会以 NotAllowedError 失败。用户关闭摄像头权限后，新的请求会被拒绝，页面已经取得的视频流仍需自行停止。

系统通知

在 manifest 中声明 deviceAccess: ["notifications"] 并开启对应权限后，页面使用标准 Notification API 发送通知，通知以宿主应用的身份显示。页面可用 Notification.permission 检查当前通知权限；requestPermission() 不会单独弹出宿主确认框，授权仍以声明和权限开关为准。

const notice = new Notification('处理完成', { body: '返回 Mini App 查看结果。' });
notice.addEventListener('click', () => {
  const handle = window.mcode?.miniapp?.window;
  if (handle) void handle.focus().catch(() => {});
});

通知点击回调可在创建通知的页面仍存活时请求 focus()。独立窗口会恢复并聚焦；内嵌页会请求聚焦宿主并选中自己的标签，不应依赖此操作自动展开已折叠的文件面板。创建通知的页面关闭或重载后，旧通知不能重新打开页面，也不能打开其他页面。这里不提供页面关闭后的后台通知能力。

写页面的约定

请求用相对路径或同源 URL，业务接口由 Node 服务提供。页面不接触凭证、Connector 客户端和宿主传输。
用语义化 HTML：landmark、heading、table、form、role="status" 等。Agent 用浏览器验收时，靠这些读懂页面。
不要把第三方脚本放进主文档。主文档里的代码，以及能访问父页面的同源 iframe，都与页面具有相同的信任级别。
不加载远程资源：字体、图标和图片用本地文件或内联 SVG，不用远程 CDN。这样离线也能用，也减少第三方脚本借页面身份访问本机服务的风险。
没有特别的风格要求时，视觉以 Skill 里的 MiniMax Code 视觉基线为准。

入门

了解 Mini App

开发

参考

特性检测

message.append(text)

miniapp.window

弹出窗口的常见坑

miniapp.agent

设备与系统权限

麦克风与语音转写

摄像头

系统通知

写页面的约定

​特性检测

​message.append(text)

​miniapp.window

​弹出窗口的常见坑

​miniapp.agent

​设备与系统权限

​麦克风与语音转写

​摄像头

​系统通知

​写页面的约定

特性检测

message.append(text)

miniapp.window

弹出窗口的常见坑

miniapp.agent

设备与系统权限

麦克风与语音转写

摄像头

系统通知

写页面的约定