bug-triage

Bug 分诊

对 apify/apify-mcp-server 中尚未处理的 Bug issue 进行分诊。分析、起草回复、获取批准并发布。

权限

• 默认只读：列出 issue（gh issue list）、查看详情和评论（gh issue view）——自动执行，无需询问。
• 写入需批准：发表评论（gh issue comment）、关闭 issue（gh issue close）、编辑 issue（gh issue edit）——始终先提供草稿，并等待用户明确批准后再执行。

步骤 0：解析参数

$ARGUMENTS 用于控制范围：

输入	行为
623 641 639	对指定 issue 编号进行分诊
--label bug	对带有指定标签的所有开放 issue 进行分诊（默认为 bug）
--all	对所有带有 bug 标签的开放 issue 进行分诊
(empty)	与 --all 相同

步骤 1：获取 issue

使用步骤 0 中解析的参数来确定要获取的内容。

如果提供了特定的 issue 编号，则跳过列表查询，直接获取每个 issue：

gh issue view <number> --repo apify/apify-mcp-server --comments

否则（标签模式、--all 或为空），获取开放的 Bug 报告。使用步骤 0 中的标签（默认为 bug）。Bug 报告有两种形式——两种都要查找：

1. 按标签：带有解析出的标签的 issue
2. 按标题前缀：标题中包含 [Bug] 的 issue（Bug 报告模板会添加此内容，但不一定总会应用标签）

# By label (use the label from Step 0, default: bug)
gh issue list --repo apify/apify-mcp-server --label <label> --state open --json number,title,labels,createdAt,body --limit 30

# By title prefix (catches unlabeled bug reports)
gh issue list --repo apify/apify-mcp-server --state open --search "[Bug] in:title" --json number,title,labels,createdAt,body --limit 30

合并两个列表，并按 issue 编号去重。

对每个 issue，获取完整详情，包括所有评论（评论通常包含实际背景信息）：

gh issue view <number> --repo apify/apify-mcp-server --comments

起草回复前务必阅读评论。 团队成员可能已经回复、询问详情或提供解决方法。不要重复已有回复。

步骤 2：对每个 issue 分类

选择以下其中一个类别：

类别	判定标准	典型操作
已知修复方法	根本原因明确，且已有记录的修复方法	起草包含修复方法的回复，可选择关闭 issue
不是我们的问题	服务端日志显示其正常工作；问题出在 MCP 客户端（Claude Desktop、Cowork 等）	说明调查结果，建议解决方法
重复问题	与另一个开放 issue 的根本原因相同	评论中附上链接，并作为重复问题关闭
需要更多信息	没有日志、没有配置或描述含糊	询问具体信息
长期未处理	我们曾询问信息，但 2 周以上未收到回复	关闭并提供有用的指引
可处理的 Bug	确属服务端 Bug，需要修复	确认收到并进一步调查

常见根本原因（来自过往分诊）

以下情况反复出现，请优先检查：

1. SSE 端点已移除（2026 年 4 月 1 日）：使用 /sse URL 的用户会遇到连接失败。修复方法：改用 https://mcp.apify.com（流式 HTTP）。

2. “工具已连接，但 Claude 不使用它们”：MCP 服务日志显示握手成功且已执行 tools/list，但 Claude 在对话中不使用这些工具。这是 Claude Desktop/Cowork 的行为，并非 Apify 服务的 Bug。用户需要明确要求 Claude 使用 Apify 工具。

3. “无法连接到扩展服务”：Claude Desktop 扩展安装问题。通常由 npx 缓存损坏、Claude 静默降级扩展版本，或 GUI 应用的 PATH 中没有 Node.js 引起。修复方法：将远程服务 https://mcp.apify.com 用作自定义连接器。

4. npx 缓存损坏：过时的缓存会导致 stdio 服务无法启动。修复方法：macOS/Linux 使用 rm -rf ~/.npm/_npx，Windows 使用 rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx。

5. Claude Desktop 连接器降级：Claude Desktop 会静默地将连接器降级到旧版本。修复方法：移除并重新添加连接器。

第 3 步：起草回复

风格规则：

• 面向开发者，使用平实语言
• 简洁——通常为 3-8 行，不说废话
• 如果用户遇到阻碍，简短回应并致歉
• 如果有修复或故障排查指南，请引用文档
• 如果日志证明服务正常工作，请明确说明
• 如果要关闭问题，请说明原因并指出下一步该去哪里

重要文档链接：

• 设置指南：https://docs.apify.com/platform/integrations/mcp
• Claude Desktop 故障排查：https://docs.apify.com/platform/integrations/claude-desktop#troubleshooting
• 配置器：https://mcp.apify.com

使用 Apify MCP 工具（search-apify-docs、fetch-apify-docs）查找正确的文档链接，适用于涉及上述内容未涵盖主题的问题。

连接问题的默认建议是远程服务：

在 Claude Desktop 中添加自定义连接器，URL 为 https://mcp.apify.com，然后按照 OAuth 流程操作。

第 4 步：展示并获取批准

向用户展示每个问题，包含：

1. 问题编号 + 标题 + 链接（https://github.com/apify/apify-mcp-server/issues/<number>）
2. 类别（来自第 2 步）
3. 摘要——用一行说明问题情况
4. 拟议回复——在引用块中展示拟好的评论
5. 拟议操作——仅评论 / 评论并关闭 / 作为 #X 的重复问题关闭 / 跳过

必须：在发布任何内容之前，等待用户明确批准。 未经用户同意，绝不发布评论、关闭或修改问题。

第 5 步：发布

获得批准后：

# Comment only
gh issue comment <number> --repo apify/apify-mcp-server --body "<response>"

# Comment + close
gh issue comment <number> --repo apify/apify-mcp-server --body "<response>" && \
gh issue close <number> --repo apify/apify-mcp-server

# Close as duplicate
gh issue comment <number> --repo apify/apify-mcp-server --body "Closing as a duplicate of #<other> — same root cause. We'll track and update there." && \
gh issue close <number> --repo apify/apify-mcp-server

然后处理下一个问题。处理完最后一个问题后，打印汇总表：

问题	类别	已采取的操作
#623	已知修复方案	已评论，迁移至 SSE
#639	重复问题	作为 #641 的重复问题关闭
...	...	...