Question 1

为什么在 OpenMAIC 中,我的自定义免密钥 TTS/ASR 提供商在页面刷新后会重置为 Browser Native(配音控件消失)?

Accepted Answer

这是 OpenMAIC v1.1.2 中的一个已知 bug。当你添加一个自定义的免密钥 provider（requiresApiKey: false，例如本地 OpenAI 兼容的 TTS endpoint）时，`lib/store/settings.ts` 中的 `addCustomTTSProvider` 只会把 endpoint 保存到 `customDefaultBaseUrl`，而 `baseUrl` 保持为空（`baseUrl: ''`）。重新加载时，`lib/store/settings-validation.ts` 中的校验函数 `isProviderUsable` 会执行 `if (cfg.requiresApiKey === false) return !!cfg.baseUrl;`，将该 provider 标记为不可用，并静默回退到 `browser-native-tts`。由于配音 UI（逐行预览/重新生成按钮、"重新生成所有配音"、voiced chips）的显示条件是 `ttsProviderId !== 'browser-native-tts'`，所有配音控件都会消失。

修复方法（已验证）：在 `lib/store/settings.ts` 中，添加/更新自定义 provider 时，将 URL 同时写入这两个字段：

```ts
addCustomTTSProvider: (id, name, baseUrl, requiresApiKey, defaultModel) =>
  set((state) => ({
    ttsProvidersConfig: { ...state.ttsProvidersConfig, [id]: {
      ...,
      baseUrl,                  // was ''
      customDefaultBaseUrl: baseUrl,
      ...
    }},
    ttsProviderId: id,
  })),
```

替代修复方案：在 `isProviderUsable` 中，对于 id 为 `custom-*` 的 provider，接受 `customDefaultBaseUrl` 作为 `baseUrl` 的回退值，例如在免密钥分支中使用 `return !!(cfg.baseUrl || cfg.customDefaultBaseUrl);`。对自定义 ASR provider 应用相同的修改，然后重新构建（`pnpm build && pnpm start`）。不修改代码的临时解决方法：每次重新加载后，在 Settings → Model Services → TTS 中重新选择该自定义 provider（在下次重新加载前一直有效），或者每次会话都删除并重新添加该 provider。

Question 2

为什么 OpenMAIC PBL v3 会拒绝有效的学生反馈，并报错"请引用本轮学生对当前段的实质反馈"？

Accepted Answer

这是 OpenMAIC 1.2.0-rc.2 中的一个已知 bug。PBL v3 的 `studentFeedback` 门控（`lib/server/pbl-v3/guided-review.ts`，第 71-79 行）对最新的学生消息使用了字面量子字符串匹配，因此 agent 包装或总结的任何反馈（例如 `Student reply: "..."`）都无法通过检查，从而阻止了通过 `read_next_skill` 或 `complete_stage` 推进流程。修复方法：升级到包含 PR #1963 的构建版本（commit `4de9467d`，已合并到 `integration/shared-sandbox` 分支）。该修复接受带引号的或经过总结的反馈，以及分布在多条学习者消息中的回答，同时仍会强制执行真实回复、阶段和工件版本检查。

Question 3

为什么 KaTeX/LaTeX 数学公式在 OpenMAIC 交互式场景中显示为原始文本(未渲染)?

Accepted Answer

出现这种情况的原因是：`postProcessInteractiveHtml`（位于 `packages/@openmaic/generation/src/interactive-post-processor.ts`）只要检测到生成的 HTML 中已包含字符串 `katex`，就会跳过注入 KaTeX 的 `auto-render` 脚本和 `MutationObserver`。当模型生成的页面自带 `katex.min.js`/`katex.min.css` 时（这种情况很常见），自动渲染永远不会被安装，因此 `$...$` 和 `$...$` 会被原样输出。在沙箱化的 `about:srcdoc` iframe 中，由于外部 CDN 脚本无法加载，页面自身调用 `renderMathInElement()` 也会失败，并报错 `Uncaught ReferenceError: renderMathInElement is not defined`。存在两种失败模式：(1) 当页面包含 KaTeX 核心库时，数学公式完全不渲染；(2) 由页面自身 `init()` 填充的标签在首次绘制时保持未渲染的原始状态，因为观察器是在首次渲染流程之后才安装的。修复方案（PR #1606）：注入判断改为检测 `auto-render`/`renderMathInElement`，而不是单纯的 `katex` 字符串；当 KaTeX 核心库已存在时，仅注入缺失的 auto-render contrib 脚本和 `MutationObserver`；安装观察器之后，在约 300ms 的稳定等待超时后额外执行一次渲染，并在 `window` 的 `load` 事件时再次执行，以便 `init()` 填充的标签能在首次绘制时正常渲染。

Question 4

如何修复 OpenMAIC 中 PBL v3 教学工具失败时出现的 SANDBOX_CONFLICT (409) 错误？

Accepted Answer

当 PBL v3 后台轮询与某个教学工具（例如 `read_next_skill`、`request_skill_review`、`complete_stage`）并发地对同一研究调用 `touchEnvironment` 时会出现此错误，导致第二个续期操作无法获取环境咨询锁，并在记录其结果之前返回 409。**临时解决方法：** 在另一个操作完成后重试该教学操作——重试通常会成功。**永久修复：** 升级到包含 PR #1964 的构建版本（`integration/shared-sandbox` 分支上的合并提交 `3446978c`），该修复会重新读取持久化的续期时间戳，并在五秒的时间预算内重试显式的环境锁争用，而不会重放教学操作。请注意，此修复在 v1.2.0-rc.2 之后才合入，可能尚未合并到 main 分支。

Question 5

如何修复 OpenMAIC 中的 "Parsing service unavailable" 物料失败错误？

Accepted Answer

当未配置解析器时，素材会失败并提示 'Parsing service unavailable'。管理员必须先为知识库配置解析器，然后打开知识库页面，对失败的素材使用 'Parse again' 进行重试。对于因时长过长而失败的媒体，请查看失败原因中显示的时长限制。请注意，来源于对话的素材没有 'Parse again' 行操作——请直接在知识库页面中管理并重新解析它们。更清晰的按原因分类的失败指引、本地化的业务错误消息（此前仅支持英文），以及修正后的单复数措辞（以 '1 material' 替代 '1 materials'）已在 PR #1923 中发布，并以 commit 84a88bc4 合并。

OpenMAIC

项目简介

README 预览

常见问题 (5)

同类型项目

vscode

FreeDomain

stable-diffusion-webui

paperclip