dig

挖掘

用于探索、规划和编写 Apify MCP 服务相关工作规格的灵活技能。请勿编辑源文件——此技能仅用于了解和规划。

步骤 0：解析参数并确定意图

$ARGUMENTS 包含用户请求和可选的仓库路径覆盖项。

标志（可选）：

标志	默认值	用途
--sdk	../typescript-sdk	MCP SDK 源码仓库路径
--ext-apps	../ext-apps	MCP Apps SDK 源码仓库路径
--internal	../apify-mcp-server-internal	内部服务仓库路径

所有不匹配标志的内容都是用户请求。

源码仓库的解析顺序：标志路径 → 默认的同级路径 → node_modules/（仅编译后的类型）→ GitHub URL（最后手段）。使用前务必确认路径存在。

确定意图

根据用户的自然语言推断其意图。共有三种模式：

意图	要做什么	示例
探索	阅读代码、说明发现、回答问题	“工具命名是如何工作的”、“看看 widget 代码”、“为什么这坏了”、“如果我们更改 X，会有什么影响”
规划	进入规划模式、设计方案、评估影响	“规划实现资源链接”、“想办法重构元数据”、“设计简化方案”
规格	规划并创建 GitHub issues	“为 X 编写 issue”、“为 Y 创建规格”、“编写资源链接的规格”

规则：

• 默认采用探索模式。有疑问时，少做一些——用户随时可以提出进一步要求。
• 仅在规划和规格模式下进入规划模式。
• 仅在规格模式下创建 GitHub issues。

步骤 1：探索

阅读相关源文件并说明你的发现。这是所有意图的基础。

要做的事：

1. 阅读此仓库中的相关源文件
2. 参考类似的现有功能
3. 仅当用户的问题涉及内部仓库、MCP SDK／规范或 MCP Apps SDK／规范时，才检查这些内容
4. 如果发现相关的未关闭 issue，可以顺带提及——但除非确有相关性，否则不要主动搜索 issue

如果意图是探索，到此为止。

步骤 2：计划（仅计划和规格说明）

使用 EnterPlanMode 工具，然后设计方案并选定一个方案。如果请求确实存在歧义（例如对应两个不同的现有设置项），请先说明分歧并询问；否则，选择最站得住脚的方案并坚持采用，不要罗列选项。

先调查：

1. 评估对内部仓库的影响（检查 ../apify-mcp-server-internal 是否可用）
2. 如果功能涉及协议行为，检查 MCP 规范/SDK
3. 如果涉及小组件或交互式 UI，检查 MCP Apps 规范/SDK
4. 如有帮助，使用 mcpc @stdio tools-call 探查当前行为（需要先运行 pnpm run build）
5. 阅读仓库的约定文档并遵循，别另起炉灶

约定在仓库里，不在这里。 AGENTS.md、CONTRIBUTING.md 和 DEVELOPMENT.md 规定了命名、验证、测试布局以及公开/内部代码分离规则——请阅读。设计应当尽量精简：优先复用并调整，而不是新增。

设计输出——必需章节。 计划必须让其他人能够据此实施，因此请包含：

1. 方案——用几句话说明选定的设计及接受的主要权衡。
2. 要修改的文件——列出每个要创建或修改的文件，并用一行说明变更内容（路径 + 变更；无需行号）。
3. 接口——列出新增或变更的关键函数/类型签名（名称、参数、返回值），让实施者和审查者了解契约。
4. 测试策略（判定标准）——说明哪些单元/集成测试能够验证方案、测试所在位置以及各自断言的内容。完成标准不能含糊带过。
5. 风险与影响——边界情况以及对 apify-mcp-server-internal 的影响。
6. 数据流——仅在数据流不简单时填写：入口 → 转换 → 输出。

第 2–4 节必须具体（提供真实文件、签名和测试；不得写“待定”或“添加错误处理”）。第 1、5、6 节保持简短。本结构适用于计划；探索和规格说明应保持精简。

如果当前意图是制定计划，请在此处停止。 使用 ExitPlanMode 退出计划模式。

步骤 3：规格说明（仅规格说明）

创建 GitHub issue。首先使用 ExitPlanMode 退出计划模式。

检查现有 issue

搜索重复及相关 issue：

gh issue list -R apify/apify-mcp-server --search "<keywords>" --json number,title,state
gh issue list -R apify/ai-team --search "<keywords>" --json number,title,state
gh issue list -R apify/apify-mcp-server-internal --search "<keywords>" --json number,title,state

如果存在匹配的 issue，请使用 gh issue edit 更新该 issue，而不是创建新 issue。

创建 issue

每个实施阶段创建一个 issue。 一个阶段是一个适合单个 PR 的工作单元（约 50–200 行改动）。每个 issue 都应可独立实施。

使用仓库的 feature_spec.yml 模板。只需填写 Problem 和 Proposed solution 字段。仅当 Plan 和 Alternatives considered 确实有帮助时才填写。不要赘述或填充无关内容，直截了当。

## Problem
[Concrete evidence: error messages, user reports, issue links. Not "users are confused" — instead "3 users reported X in #channel".]

## Proposed solution
[Short. Reference existing code paths. List files inline if needed.]

## Plan
- [ ] Step 1
- [ ] Step 2

## Alternatives considered
[Only if you actually evaluated other approaches.]

风格（探索说明和规格 issue）：

• 使用平实语言，不要赘述——参见 CLAUDE.md § Communication style
• 跳过空泛或通用的章节
• 控制在 10–30 行，不要写到 100 行
• 优先列出具体步骤，而非大段说明

（计划的设计应遵循上述必需章节结构——各节简洁，但不要为了控制行数而删减文件、接口或测试策略。）

提交前自查：

• 这是最精简的设计吗？能否缩小范围？
• 是否复用了现有模式，还是另起炉灶？
• 能否调整现有代码，而不是新增代码？
• 是否需要先重构？如果需要，应拆成单独的 issue。

创建之前，先向用户展示 issue 内容供其审核。使用带有 t-ai 标签的 gh issue create。

可用资源

资源	路径 / URL	用途
Public repo	.（此仓库根目录）	主代码库 — 工具、widgets、测试
Internal repo	../apify-mcp-server-internal（如果可用）	托管服务 — 评估变更的影响
MCP SDK (types)	node_modules/@modelcontextprotocol/sdk	协议类型、服务端 / 客户端 API（仅编译后的文件）
MCP SDK (source)	../typescript-sdk（如果可用）	示例、测试、完整源码 — 比 GitHub 更快
MCP spec	https://modelcontextprotocol.io/specification/2025-11-25	协议级功能
MCP Apps SDK (types)	node_modules/@modelcontextprotocol/ext-apps	MCP Apps 类型、React hooks、服务端辅助工具（仅编译后的文件）
MCP Apps SDK (source)	../ext-apps（如果可用）	示例、测试、规范、完整源码 — 比 GitHub 更快
MCP Apps spec	https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx	MCP Apps 扩展规范
Dev server (no UI)	http://localhost:3001/ / 工具：mcp__apify-dev__*	测试工具，无需使用 widgets
Dev server (UI)	http://localhost:3001/?ui=true / 工具：mcp__apify-dev-ui__*	测试工具及 widget 渲染
mcpc stdio	mcpc @stdio tools-call ...（需要 pnpm run build）	测试工具 — 无需运行服务