Minds for GitHub Actions：Research Review action 指南
Minds Research Review 是发布在 GitHub Marketplace 中的 GitHub Action。它使用存储为 secret 的 API 密钥，将工作流连接到 Minds MCP 服务器。默认操作会保存一个 Study 计划供审核，不会开始研究。
Minds 是一个端到端的商业合成研究平台。Minds Research Review action 将其带入 GitHub 工作流：为仓库中的拟议文案准备可审核的 Study 计划，向现有 Audience 提出一个问题，或将 Study 的进度和摘要汇总到作业摘要中。
可用性与要求
该 action 以 GitHub Marketplace 中的 Minds Research Review 发布。本指南涵盖 v1.0.0 版本，引用方式为 minds-ai-co/minds-research-action@v1。源代码和完整的输入约定在 minds-research-action 仓库 中公开。
您需要一个启用了 Actions 的 GitHub 仓库，以及一个具有 API 访问权限的 Minds 账户。该 action 调用托管于 https://getminds.ai/mcp 的 Minds MCP 服务器。现有的 API 权限和使用限制同样适用。它没有运行时依赖，也不请求任何 GitHub 令牌权限。
设置
- 在 Minds 中，打开 Settings → API Keys，为此仓库创建一个密钥。
- 在 GitHub 中，将该密钥保存为仓库级或组织级的 Actions secret，名称为
MINDS_API_KEY。 - 添加一个使用该 action 的工作流。此示例使用存储在仓库变量
MINDS_PANEL_ID中的 Study ID，为拟议的首页文案准备计划：
name: Research review
on:
workflow_dispatch:
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: minds-ai-co/minds-research-action@v1
with:
api-key: ${{ secrets.MINDS_API_KEY }}
operation: plan-study
panel-id: ${{ vars.MINDS_PANEL_ID }}
request: >-
Prepare a concept test covering clarity, relevance, objections,
credibility, and concrete improvements.
stimulus-file: docs/proposed-homepage-copy.md
stimulus-label: Proposed homepage copy
study-locale: en
- 运行工作流，然后在 Minds 中审核保存的草稿，准备就绪后在那里开始研究。
操作
该 action 的输入使用 MCP 名称：Group 是已保存的 Audience，Panel 是 Study。
| 操作 | 必需输入 | 效果 |
|---|---|---|
list-groups | 无 | 列出账户中已保存的 Audience。search-query 可按名称筛选。 |
plan-study（默认） | panel-id 或 panel-name，request | 保存可审核的 Study 草稿，不开始研究。 |
ask-group | group-id 或 group-name，question | 使用一个 Audience 启动私有的异步 Study。 |
get-panel-status | panel-id 或 panel-name | 返回 Study 的构成和进度。 |
get-panel-summary | panel-id 或 panel-name | 读取摘要，或通过 refresh-summary: true 刷新摘要。 |
版本 1 不会运行结构化的 Study 计划。确认已保存的计划仍是在 Minds 中做出的明确决定。ask-group 确实会开始研究并消耗所连接账户的额度，因此仅在有意为之时运行。该问题会展示给受访者；请勿在其中包含工作流或模型指令。
输入与输出
对于 plan-study，请将研究目标放入 request，并将受访者应看到的材料放入 stimulus 或 stimulus-file 之一，不可同时使用两者。刺激材料文件必须位于检出的工作区内，且不得超过 20 KB。study-locale 接受 en、es、fr、de、zh、tr、ar、ja 或 ko。
每次运行都会将可读结果写入 GitHub 作业摘要。输出包括 result-json（完整结果，超过 500 KB 时省略）、panel-id、draft-plan-id、revision 和 workspace-url。您可以在后续步骤中使用它们，例如在拉取请求中发布 Minds 链接。ask-group 的结果以异步方式到达：请在后续运行中使用 get-panel-status 或 get-panel-summary 读取。
安全
- 仅通过
api-key输入从 GitHub Actions secret 传递 API 密钥。该 action 会屏蔽密钥，不会将其写入日志、输出、摘要或文件。 - 当仓库 secret 处于暴露状态时，请勿将该 action 与
pull_request_target一起用于评估来自 fork 的不受信任内容。 - 将生产工作流固定到发布标签或完整的提交 SHA。
故障排除
- 401 或身份验证错误： 检查 secret 是否包含有效的 Minds API 密钥；请参阅 API 身份验证。
- 找不到 Study 或 Audience： 使用精确的 ID，或运行
list-groups检查该密钥所属账户已保存的 Audience 名称。 - 缺少
result-json： 结果超过 500 KB；请从作业摘要或在 Minds 中读取。 - 受套餐或速率限制的响应： 检查账户的 API 访问权限和使用额度，并参阅 API 错误与限制。
合成研究结果提供早期的方向性证据；它们不能替代用于高风险决策的代表性真人研究。浏览 所有集成 或查看 MCP 工具参考。
