awesome-copilot Apify 集成专家 Agent用 MCP 工具与客户端库把 Apify Actors 接入 JavaScript/Python 代码库的完整指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以 awesome-copilot 仓库中的 apify-integration-expert 自定义 Agent 为主体完整解读它的角色定义、MCP 服务器配置、五步集成工作流与安全护栏并给出可直接复制运行的 JavaScript/TypeScript 与 Python 客户端代码示例。读完后你将能在 VS Code 中安装并启用该 Agent理解它如何通过 Apify MCP 服务器完成 Actor 选型、试跑与结果取回并能把 Actor 输出安全地落到自己项目的数据存储中。一、Agent 定位把“云端 Actor 调用”变成一条可落地的工程化流程在 docs/README.agents.md 中awesome-copilot 对自定义 Agent 的定义是通过简单的文件式配置*.agent.md来“特化” GitHub Copilot 编程 Agent让它在特定领域拥有预设的职责边界和可用工具。apify-integration-expert就是这样一个面向第三方服务集成的专家型 Agent其文件头描述为Expert agent for integrating Apify Actors into codebases. Handles Actor selection, workflow design, implementation across JavaScript/TypeScript and Python, testing, and production-ready deployment.先厘清核心概念Apify Actor 是一段运行在云端的程序可以爬取网站、填表、发邮件或执行其他自动化任务。你在代码中调用它它在云端运行然后把结果通常以 Dataset 的形式返回给你。该 Agent 的职责就是帮你把一个业务目标比如“每天抓取某页面的数据入库”翻译成完整的集成方案选哪个 Actor、如何触发、结果存哪里、失败怎么办并且给出贴合你现有技术栈的代码。它的三大使命Mission在文档中明确列出见 Agent 文件为问题找到最合适的 Apify Actor并端到端地指导集成过程提供符合项目既有约定现有代码风格、数据结构、运行方式的可运行实现步骤主动暴露风险、验证步骤和后续工作项让团队有信心地采用这个集成。值得注意的是该 Agent 同时被收录进仓库的 partners 插件清单 plugins/partners/plugin.json“Custom agents that have been created by GitHub partners”说明它属于由合作伙伴提供、经仓库统一收录的 Agent 之一。二、Frontmattername、description 与 MCP 服务器声明自定义 Agent 的核心结构是 YAML frontmatter Markdown 正文。该 Agent 的 frontmatter第 1-18 行声明了三部分内容name: apify-integration-expert description: Expert agent for integrating Apify Actors into codebases. ... mcp-servers: apify: type: http url: https://mcp.apify.com headers: Authorization: Bearer $APIFY_TOKEN Content-Type: application/json tools: - fetch-actor-details - search-actors - call-actor - search-apify-docs - fetch-apify-docs - get-actor-output各字段的作用字段含义nameAgent 在 Copilot 中的唯一标识通常与文件名一致description描述 Agent 的适用范围供用户和 Copilot 判断何时启用它mcp-servers.apify.type声明这是一个 HTTP远程类型的 MCP 服务器而非本地 stdio 命令mcp-servers.apify.urlMCP 服务器端点本 Agent 指向 Apify 官方的远程 MCP 服务mcp-servers.apify.headers请求头。Authorization使用环境变量占位符$APIFY_TOKEN注入 Bearer 令牌而不是硬编码密钥Content-Type固定为application/jsonmcp-servers.apify.tools显式列出该 Agent 允许使用的 6 个 MCP 工具相当于对该 Agent 的工具白名单从仓库源码结构看这套 frontmatter 是被工程化消费的eng/yaml-parser.mjs 中的extractAgentMetadata会解析每个 agent 文件的 frontmatter提取name、description、tools以及mcp-servers字段生成 Agent 元数据eng/generate-website-data.mjs 则读取frontmatter[mcp-servers]的键名在站点数据中展示每个 Agent 依赖哪些 MCP 服务器。也就是说你在 frontmatter 里声明的apify服务器会被仓库的构建流程自动识别并展示在文档站点里。仓库还对 MCP 服务器声明有严格的校验规则。从 eng/agent-plugin-schema.mjs 的校验逻辑可以看到url必须是绝对 HTTP(S) URL、不能包含 userinfo 或 fragment非回环主机必须使用 HTTPSheaders中不允许出现凭据或秘密、不允许重复的表头名。这也解释了为什么该 Agent 的授权头写成$APIFY_TOKEN占位符而不是真实令牌——把密钥留在环境变量里、配置文件只保留占位正是仓库校验规则要求的安全做法。三、角色指令使命、职责与五条操作原则Agent 正文frontmatter 之后的 Markdown就是注入给 Copilot 的系统指令。该 Agent 将其划分为四块构成一套清晰的“集成顾问”行为契约。核心职责Core Responsibilities第 34-39 行在建议任何改动之前先理解项目的上下文、工具与约束帮用户把目标转译为 Actor 工作流跑什么、何时跑、结果怎么处理说明数据如何进出 Actor以及结果最终应该存储在哪里文档化“如何运行、如何测试、如何扩展”这个集成。操作原则Operating Principles第 41-47 行是五条硬性纪律Clarity first清晰优先给出直白、易跟随的提示词、代码与文档Use what they have用你已有的匹配项目已在使用的工具和模式不强行引入新框架Fail fast快速失败先用小规模试运行验证假设再谈规模化Stay safe保持安全保护秘密、尊重限流、对破坏性操作给出警告Test everything测试一切能加测试就加测试不能加就提供手工测试步骤。这五条原则与后文“推荐工作流”和“安全护栏”一一对应是整个 Agent 设计思想的主线先调研、再设计、小步验证、全程可回退。四、前置条件APIFY_TOKEN文档的 Prerequisites 一节第 49-53 行给出两个前置条件Apify Token开始集成前先检查环境中是否已设置APIFY_TOKEN如果没有需要到 Apify 控制台的账户集成页创建一枚令牌并通过环境变量注入——这既满足 frontmatter 中Authorization: Bearer $APIFY_TOKEN的占位符解析也满足正文中客户端代码对process.env.APIFY_TOKEN的读取Apify Client Library实施阶段按需安装对应语言的客户端库下文分别给出 Node 与 Python 的安装命令。五、推荐工作流从理解上下文到测试文档的五步法该 Agent 定义的标准集成流程是 5 步第 54-76 行每一步都明确了该步使用的工具与产出1. Understand Context理解上下文查看项目 README 和现有的数据摄取data ingestion方式盘点已有基础设施cron 任务、后台 worker、CI 流水线等。目的是让后续方案“长在项目已有的调度与存储体系上”而不是另起炉灶。2. Select Inspect Actors选型与检查用search-actors按需求搜索匹配的 Actor用fetch-actor-details查看该 Actor 接受哪些输入、产出哪些输出把 Actor 的详情分享给用户确保双方对“它到底做什么”有一致认知。3. Design the Integration设计集成决定触发方式手动、定时on a schedule、还是事件驱动when something happens规划结果存储位置数据库、文件等提前想好两个边界情况同样的数据第二次返回时怎么办幂等/去重以及运行失败时怎么办重试/告警。4. Implement It实现用call-actor真实跑一次 Actor验证输入输出假设提供可复制、可修改的完整代码示例即后两节的 JS/TS 与 Python 示例。5. Test Document测试与文档跑若干测试用例确认集成可用文档化安装步骤与运行方式供团队复用。这套工作流把“选 Actor”与“写代码”解耦先通过 MCP 工具把 Actor 的能力摸清再写业务代码避免“先写代码、后发现 Actor 输入格式不对”的返工。六、六个 MCP 工具Agent 与 Apify 平台之间的通道frontmatter 声明的 6 个工具在正文“Using the Apify MCP Tools”一节第 78-88 行中有逐一说明按在工作流中的使用时序整理如下工具作用典型使用时机search-actors按用户需求搜索 Actor工作流第 2 步的选型入口fetch-actor-details获取 Actor 详情接受哪些输入、产出哪些输出、定价等选型确认后核对输入/输出契约call-actor真正运行一次 Actor工作流第 4 步的实现前验证get-actor-output取回已完成运行的结果试运行后核对产出数据结构search-apify-docs检索 Apify 官方文档遇到不确定的概念时查证fetch-apify-docs拉取指定官方文档页需要完整文档上下文时该节还有一条明确的交互约定“Always tell the user what tools youre using and what you found”——Agent 每次调用 MCP 工具后都必须向用户说明用了什么工具、发现了什么保证过程可审计。七、安全与护栏四条集成红线文档的 Safety Guardrails 一节第 90-96 行给出四条硬性约束这是把云端数据管道接入生产系统前最容易出事的地方Protect secrets保护秘密API 令牌与凭据绝不允许提交进代码库一律走环境变量——这与 frontmatter 里Bearer $APIFY_TOKEN的占位符写法互为表里Be careful with data谨慎处理数据在未经用户知情的情况下不抓取或处理受保护或受监管的数据Respect limits尊重限额留意 API 限流与费用先小规模试运行再放量呼应“Fail fast”原则Dont break things不要破坏东西除非用户明确指示避免执行永久删除或修改数据如删表的操作。八、JavaScript/TypeScript 实现从安装到读取 Dataset 字段文档为 JS/TS 技术栈给出的完整实现共 5 小节第 97-168 行以官方 Web Scraper Actor 为例。1. 安装与客户端初始化npm install apify-clientimport { ApifyClient } from apify-client; const client new ApifyClient({ token: process.env.APIFY_TOKEN!, // 令牌只从环境变量读取不入库 });客户端唯一的必填项是token即前面配置好的APIFY_TOKEN。2. 调用 Actorconst run await client.actor(apify/web-scraper).call({ startUrls: [{ url: https://news.ycombinator.com }], maxDepth: 1, });call()的入参就是该 Actor 的运行输入startUrls是起始 URL 数组元素为{ url }对象maxDepth: 1表示只抓取起始层、不继续向下遍历链接。不同 Actor 接受的输入字段不同——这正是工作流第 2 步要求先用fetch-actor-details核对输入契约的原因。3. 等待完成并取回 Datasetawait client.run(run.id).waitForFinish(); const dataset client.dataset(run.defaultDatasetId!); const { items } await dataset.listItems();waitForFinish()阻塞直到该 run 结束run.defaultDatasetId是 Actor 默认输出的数据集 IDdataset.listItems()拉取其中的全部条目。4. 理解输出结构Dataset 条目就是对象数组文档明确强调Dataset 中的每一条 item 都是一个 JavaScript 对象字段由该 Actor 决定。示例条目爬取 HN 得到的一条评论{ url: https://news.ycombinator.com/item?id37281947, title: Ask HN: Who is hiring? (August 2023), points: 312, comments: 521, loadedAt: 2025-08-01T10:22:15.123Z }5. 安全地访问字段items.forEach((item, index) { const url item.url ?? N/A; const title item.title ?? No title; const points item.points ?? 0; console.log(${index 1}. ${title}); console.log( URL: ${url}); console.log( Points: ${points}); });这里用??为每个字段提供了回退值——因为不同页面结构可能缺失某些字段防御式读取是处理外部抓取数据的常态做法。这段代码也提示了设计要点拿到items后按工作流第 3 步规划的存储位置数据库表、文件等落盘并对重复数据做去重判断。九、Python 实现同一条链路的六步对照Python 版实现共 6 小节第 171-248 行调用链路与 JS 完全一致只是 API 命名风格从驼峰变为蛇形。1. 安装pip install apify-client2. 初始化客户端from apify_client import ApifyClient import os client ApifyClient(os.getenv(APIFY_TOKEN))3. 运行 Actor# Run the official Web Scraper actor_call client.actor(apify/web-scraper).call( run_input{ startUrls: [{url: https://news.ycombinator.com}], maxDepth: 1, } ) print(fActor started! Run ID: {actor_call[id]}) print(fView in console: https://console.apify.com/actors/runs/{actor_call[id]})注意与 JS 版的差异Python 端把 Actor 输入放在run_input参数中返回的是包含id等字段的字典run_input中的 keystartUrls、maxDepth与 Actor 定义的输入 schema 保持一致。4. 等待完成# Wait for Actor to finish run client.run(actor_call[id]).wait_for_finish() print(fStatus: {run[status]})5. 输出结构条目是 Python dict{ url: https://news.ycombinator.com/item?id37281947, title: Ask HN: Who is hiring? (August 2023), points: 312, comments: 521 }6. 读取输出字段dataset client.dataset(run[defaultDatasetId]) items dataset.list_items().get(items, []) for i, item in enumerate(items[:5]): url item.get(url, N/A) title item.get(title, No title) print(f{i1}. {title}) print(f URL: {url})list_items()返回的是含items列表的字典示例里用.get(items, [])兜底并用item.get(key, default)做字段级防御items[:5]则体现了“小样本先验证”的思路。十、仓库工程视角这个 Agent 是如何被管理与校验的从源码结构看该 Agent 并非孤立文件而是被 awesome-copilot 的构建与校验管线统一处理eng/yaml-parser.mjs 提供extractMcpServers从 Agent 文件 frontmatter 中提取 MCP 服务器名列表供上层统计“哪些 Agent 依赖哪些 MCP 服务”eng/generate-website-data.mjs 将frontmatter[mcp-servers]的键写入站点数据使文档站能展示每个 Agent 的 MCP 依赖eng/validate-plugins.mjs 与 eng/agent-plugin-schema.mjs 对 MCP 服务器声明做格式与安全校验HTTPS、表头不得含秘密等该 Agent 的物料化引用登记在 plugins/partners/plugin.json 的extensions[com.github.awesome-copilot].agents列表中此外 plugins/external.json 还登记了 Apify 官方提供的独立 Copilot 插件apify-github-copilot-plugin其关键词包含 automation、actors、scrape、crawl与本 Agent 的“集成 Apify Actors”主题互为补充。对只想阅读该 Agent 相关素材的读者仓库中还有一个可对照的相邻案例skills/x-twitter-scraper/SKILL.md 描述了“通过托管 Apify Actor 运行数据采集 用环境变量管理密钥 结构化数据返回”的类似集成模式可作为理解“Actor 作为托管数据源”这一模式的延伸阅读。十一、上手路径与验证清单结合 docs/README.agents.md 的通用安装说明使用该 Agent 的完整路径是安装 Agent在 VS Code或 VS Code Insiders中点击该 Agent 的 install 按钮或直接下载*.agent.md文件放入你的仓库配置 MCP 服务器按 frontmatter 的声明把名为apify的 HTTP MCP 服务器指向官方 MCP 端点、带Authorization: Bearer $APIFY_TOKEN请求头加入仓库的 MCP 配置并设置APIFY_TOKEN环境变量启用并对话通过 VS Code Chat 接口选择该 Agent或在 CCA 中分配描述你的数据采集需求按工作流验收检查 Agent 是否先做了上下文调研、是否用search-actors/fetch-actor-details完成了选型与输入输出核对、是否先用call-actor小规模试运行、代码是否从环境变量取令牌、是否处理了重复数据与失败分支、是否附带了测试步骤与文档。这套组合——frontmatter 声明 MCP 工具白名单、正文规定五步工作流与安全护栏、正文内嵌可直接运行的双语代码——正是 awesome-copilot 仓库中“专家型集成 Agent”的典型范式把第三方服务的集成知识固化为可安装、可校验、可复用的文件配置。参考资料Agent 定义与全部代码示例agents/apify-integration-expert.agent.md自定义 Agent 使用说明docs/README.agents.mdpartners 插件清单plugins/partners/plugin.jsonfrontmatter 解析实现eng/yaml-parser.mjsMCP 声明校验规则eng/agent-plugin-schema.mjs、eng/validate-plugins.mjs外部 Apify 插件登记plugins/external.json【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 awesome-copilot Apify 集成专家 Agent：用 MCP 工具与客户端库把 Apify Actors 接入 JavaScript/Python 代码库的完整指南
awesome-copilot Apify 集成专家 Agent用 MCP 工具与客户端库把 Apify Actors 接入 JavaScript/Python 代码库的完整指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以 awesome-copilot 仓库中的 apify-integration-expert 自定义 Agent 为主体完整解读它的角色定义、MCP 服务器配置、五步集成工作流与安全护栏并给出可直接复制运行的 JavaScript/TypeScript 与 Python 客户端代码示例。读完后你将能在 VS Code 中安装并启用该 Agent理解它如何通过 Apify MCP 服务器完成 Actor 选型、试跑与结果取回并能把 Actor 输出安全地落到自己项目的数据存储中。一、Agent 定位把“云端 Actor 调用”变成一条可落地的工程化流程在 docs/README.agents.md 中awesome-copilot 对自定义 Agent 的定义是通过简单的文件式配置*.agent.md来“特化” GitHub Copilot 编程 Agent让它在特定领域拥有预设的职责边界和可用工具。apify-integration-expert就是这样一个面向第三方服务集成的专家型 Agent其文件头描述为Expert agent for integrating Apify Actors into codebases. Handles Actor selection, workflow design, implementation across JavaScript/TypeScript and Python, testing, and production-ready deployment.先厘清核心概念Apify Actor 是一段运行在云端的程序可以爬取网站、填表、发邮件或执行其他自动化任务。你在代码中调用它它在云端运行然后把结果通常以 Dataset 的形式返回给你。该 Agent 的职责就是帮你把一个业务目标比如“每天抓取某页面的数据入库”翻译成完整的集成方案选哪个 Actor、如何触发、结果存哪里、失败怎么办并且给出贴合你现有技术栈的代码。它的三大使命Mission在文档中明确列出见 Agent 文件为问题找到最合适的 Apify Actor并端到端地指导集成过程提供符合项目既有约定现有代码风格、数据结构、运行方式的可运行实现步骤主动暴露风险、验证步骤和后续工作项让团队有信心地采用这个集成。值得注意的是该 Agent 同时被收录进仓库的 partners 插件清单 plugins/partners/plugin.json“Custom agents that have been created by GitHub partners”说明它属于由合作伙伴提供、经仓库统一收录的 Agent 之一。二、Frontmattername、description 与 MCP 服务器声明自定义 Agent 的核心结构是 YAML frontmatter Markdown 正文。该 Agent 的 frontmatter第 1-18 行声明了三部分内容name: apify-integration-expert description: Expert agent for integrating Apify Actors into codebases. ... mcp-servers: apify: type: http url: https://mcp.apify.com headers: Authorization: Bearer $APIFY_TOKEN Content-Type: application/json tools: - fetch-actor-details - search-actors - call-actor - search-apify-docs - fetch-apify-docs - get-actor-output各字段的作用字段含义nameAgent 在 Copilot 中的唯一标识通常与文件名一致description描述 Agent 的适用范围供用户和 Copilot 判断何时启用它mcp-servers.apify.type声明这是一个 HTTP远程类型的 MCP 服务器而非本地 stdio 命令mcp-servers.apify.urlMCP 服务器端点本 Agent 指向 Apify 官方的远程 MCP 服务mcp-servers.apify.headers请求头。Authorization使用环境变量占位符$APIFY_TOKEN注入 Bearer 令牌而不是硬编码密钥Content-Type固定为application/jsonmcp-servers.apify.tools显式列出该 Agent 允许使用的 6 个 MCP 工具相当于对该 Agent 的工具白名单从仓库源码结构看这套 frontmatter 是被工程化消费的eng/yaml-parser.mjs 中的extractAgentMetadata会解析每个 agent 文件的 frontmatter提取name、description、tools以及mcp-servers字段生成 Agent 元数据eng/generate-website-data.mjs 则读取frontmatter[mcp-servers]的键名在站点数据中展示每个 Agent 依赖哪些 MCP 服务器。也就是说你在 frontmatter 里声明的apify服务器会被仓库的构建流程自动识别并展示在文档站点里。仓库还对 MCP 服务器声明有严格的校验规则。从 eng/agent-plugin-schema.mjs 的校验逻辑可以看到url必须是绝对 HTTP(S) URL、不能包含 userinfo 或 fragment非回环主机必须使用 HTTPSheaders中不允许出现凭据或秘密、不允许重复的表头名。这也解释了为什么该 Agent 的授权头写成$APIFY_TOKEN占位符而不是真实令牌——把密钥留在环境变量里、配置文件只保留占位正是仓库校验规则要求的安全做法。三、角色指令使命、职责与五条操作原则Agent 正文frontmatter 之后的 Markdown就是注入给 Copilot 的系统指令。该 Agent 将其划分为四块构成一套清晰的“集成顾问”行为契约。核心职责Core Responsibilities第 34-39 行在建议任何改动之前先理解项目的上下文、工具与约束帮用户把目标转译为 Actor 工作流跑什么、何时跑、结果怎么处理说明数据如何进出 Actor以及结果最终应该存储在哪里文档化“如何运行、如何测试、如何扩展”这个集成。操作原则Operating Principles第 41-47 行是五条硬性纪律Clarity first清晰优先给出直白、易跟随的提示词、代码与文档Use what they have用你已有的匹配项目已在使用的工具和模式不强行引入新框架Fail fast快速失败先用小规模试运行验证假设再谈规模化Stay safe保持安全保护秘密、尊重限流、对破坏性操作给出警告Test everything测试一切能加测试就加测试不能加就提供手工测试步骤。这五条原则与后文“推荐工作流”和“安全护栏”一一对应是整个 Agent 设计思想的主线先调研、再设计、小步验证、全程可回退。四、前置条件APIFY_TOKEN文档的 Prerequisites 一节第 49-53 行给出两个前置条件Apify Token开始集成前先检查环境中是否已设置APIFY_TOKEN如果没有需要到 Apify 控制台的账户集成页创建一枚令牌并通过环境变量注入——这既满足 frontmatter 中Authorization: Bearer $APIFY_TOKEN的占位符解析也满足正文中客户端代码对process.env.APIFY_TOKEN的读取Apify Client Library实施阶段按需安装对应语言的客户端库下文分别给出 Node 与 Python 的安装命令。五、推荐工作流从理解上下文到测试文档的五步法该 Agent 定义的标准集成流程是 5 步第 54-76 行每一步都明确了该步使用的工具与产出1. Understand Context理解上下文查看项目 README 和现有的数据摄取data ingestion方式盘点已有基础设施cron 任务、后台 worker、CI 流水线等。目的是让后续方案“长在项目已有的调度与存储体系上”而不是另起炉灶。2. Select Inspect Actors选型与检查用search-actors按需求搜索匹配的 Actor用fetch-actor-details查看该 Actor 接受哪些输入、产出哪些输出把 Actor 的详情分享给用户确保双方对“它到底做什么”有一致认知。3. Design the Integration设计集成决定触发方式手动、定时on a schedule、还是事件驱动when something happens规划结果存储位置数据库、文件等提前想好两个边界情况同样的数据第二次返回时怎么办幂等/去重以及运行失败时怎么办重试/告警。4. Implement It实现用call-actor真实跑一次 Actor验证输入输出假设提供可复制、可修改的完整代码示例即后两节的 JS/TS 与 Python 示例。5. Test Document测试与文档跑若干测试用例确认集成可用文档化安装步骤与运行方式供团队复用。这套工作流把“选 Actor”与“写代码”解耦先通过 MCP 工具把 Actor 的能力摸清再写业务代码避免“先写代码、后发现 Actor 输入格式不对”的返工。六、六个 MCP 工具Agent 与 Apify 平台之间的通道frontmatter 声明的 6 个工具在正文“Using the Apify MCP Tools”一节第 78-88 行中有逐一说明按在工作流中的使用时序整理如下工具作用典型使用时机search-actors按用户需求搜索 Actor工作流第 2 步的选型入口fetch-actor-details获取 Actor 详情接受哪些输入、产出哪些输出、定价等选型确认后核对输入/输出契约call-actor真正运行一次 Actor工作流第 4 步的实现前验证get-actor-output取回已完成运行的结果试运行后核对产出数据结构search-apify-docs检索 Apify 官方文档遇到不确定的概念时查证fetch-apify-docs拉取指定官方文档页需要完整文档上下文时该节还有一条明确的交互约定“Always tell the user what tools youre using and what you found”——Agent 每次调用 MCP 工具后都必须向用户说明用了什么工具、发现了什么保证过程可审计。七、安全与护栏四条集成红线文档的 Safety Guardrails 一节第 90-96 行给出四条硬性约束这是把云端数据管道接入生产系统前最容易出事的地方Protect secrets保护秘密API 令牌与凭据绝不允许提交进代码库一律走环境变量——这与 frontmatter 里Bearer $APIFY_TOKEN的占位符写法互为表里Be careful with data谨慎处理数据在未经用户知情的情况下不抓取或处理受保护或受监管的数据Respect limits尊重限额留意 API 限流与费用先小规模试运行再放量呼应“Fail fast”原则Dont break things不要破坏东西除非用户明确指示避免执行永久删除或修改数据如删表的操作。八、JavaScript/TypeScript 实现从安装到读取 Dataset 字段文档为 JS/TS 技术栈给出的完整实现共 5 小节第 97-168 行以官方 Web Scraper Actor 为例。1. 安装与客户端初始化npm install apify-clientimport { ApifyClient } from apify-client; const client new ApifyClient({ token: process.env.APIFY_TOKEN!, // 令牌只从环境变量读取不入库 });客户端唯一的必填项是token即前面配置好的APIFY_TOKEN。2. 调用 Actorconst run await client.actor(apify/web-scraper).call({ startUrls: [{ url: https://news.ycombinator.com }], maxDepth: 1, });call()的入参就是该 Actor 的运行输入startUrls是起始 URL 数组元素为{ url }对象maxDepth: 1表示只抓取起始层、不继续向下遍历链接。不同 Actor 接受的输入字段不同——这正是工作流第 2 步要求先用fetch-actor-details核对输入契约的原因。3. 等待完成并取回 Datasetawait client.run(run.id).waitForFinish(); const dataset client.dataset(run.defaultDatasetId!); const { items } await dataset.listItems();waitForFinish()阻塞直到该 run 结束run.defaultDatasetId是 Actor 默认输出的数据集 IDdataset.listItems()拉取其中的全部条目。4. 理解输出结构Dataset 条目就是对象数组文档明确强调Dataset 中的每一条 item 都是一个 JavaScript 对象字段由该 Actor 决定。示例条目爬取 HN 得到的一条评论{ url: https://news.ycombinator.com/item?id37281947, title: Ask HN: Who is hiring? (August 2023), points: 312, comments: 521, loadedAt: 2025-08-01T10:22:15.123Z }5. 安全地访问字段items.forEach((item, index) { const url item.url ?? N/A; const title item.title ?? No title; const points item.points ?? 0; console.log(${index 1}. ${title}); console.log( URL: ${url}); console.log( Points: ${points}); });这里用??为每个字段提供了回退值——因为不同页面结构可能缺失某些字段防御式读取是处理外部抓取数据的常态做法。这段代码也提示了设计要点拿到items后按工作流第 3 步规划的存储位置数据库表、文件等落盘并对重复数据做去重判断。九、Python 实现同一条链路的六步对照Python 版实现共 6 小节第 171-248 行调用链路与 JS 完全一致只是 API 命名风格从驼峰变为蛇形。1. 安装pip install apify-client2. 初始化客户端from apify_client import ApifyClient import os client ApifyClient(os.getenv(APIFY_TOKEN))3. 运行 Actor# Run the official Web Scraper actor_call client.actor(apify/web-scraper).call( run_input{ startUrls: [{url: https://news.ycombinator.com}], maxDepth: 1, } ) print(fActor started! Run ID: {actor_call[id]}) print(fView in console: https://console.apify.com/actors/runs/{actor_call[id]})注意与 JS 版的差异Python 端把 Actor 输入放在run_input参数中返回的是包含id等字段的字典run_input中的 keystartUrls、maxDepth与 Actor 定义的输入 schema 保持一致。4. 等待完成# Wait for Actor to finish run client.run(actor_call[id]).wait_for_finish() print(fStatus: {run[status]})5. 输出结构条目是 Python dict{ url: https://news.ycombinator.com/item?id37281947, title: Ask HN: Who is hiring? (August 2023), points: 312, comments: 521 }6. 读取输出字段dataset client.dataset(run[defaultDatasetId]) items dataset.list_items().get(items, []) for i, item in enumerate(items[:5]): url item.get(url, N/A) title item.get(title, No title) print(f{i1}. {title}) print(f URL: {url})list_items()返回的是含items列表的字典示例里用.get(items, [])兜底并用item.get(key, default)做字段级防御items[:5]则体现了“小样本先验证”的思路。十、仓库工程视角这个 Agent 是如何被管理与校验的从源码结构看该 Agent 并非孤立文件而是被 awesome-copilot 的构建与校验管线统一处理eng/yaml-parser.mjs 提供extractMcpServers从 Agent 文件 frontmatter 中提取 MCP 服务器名列表供上层统计“哪些 Agent 依赖哪些 MCP 服务”eng/generate-website-data.mjs 将frontmatter[mcp-servers]的键写入站点数据使文档站能展示每个 Agent 的 MCP 依赖eng/validate-plugins.mjs 与 eng/agent-plugin-schema.mjs 对 MCP 服务器声明做格式与安全校验HTTPS、表头不得含秘密等该 Agent 的物料化引用登记在 plugins/partners/plugin.json 的extensions[com.github.awesome-copilot].agents列表中此外 plugins/external.json 还登记了 Apify 官方提供的独立 Copilot 插件apify-github-copilot-plugin其关键词包含 automation、actors、scrape、crawl与本 Agent 的“集成 Apify Actors”主题互为补充。对只想阅读该 Agent 相关素材的读者仓库中还有一个可对照的相邻案例skills/x-twitter-scraper/SKILL.md 描述了“通过托管 Apify Actor 运行数据采集 用环境变量管理密钥 结构化数据返回”的类似集成模式可作为理解“Actor 作为托管数据源”这一模式的延伸阅读。十一、上手路径与验证清单结合 docs/README.agents.md 的通用安装说明使用该 Agent 的完整路径是安装 Agent在 VS Code或 VS Code Insiders中点击该 Agent 的 install 按钮或直接下载*.agent.md文件放入你的仓库配置 MCP 服务器按 frontmatter 的声明把名为apify的 HTTP MCP 服务器指向官方 MCP 端点、带Authorization: Bearer $APIFY_TOKEN请求头加入仓库的 MCP 配置并设置APIFY_TOKEN环境变量启用并对话通过 VS Code Chat 接口选择该 Agent或在 CCA 中分配描述你的数据采集需求按工作流验收检查 Agent 是否先做了上下文调研、是否用search-actors/fetch-actor-details完成了选型与输入输出核对、是否先用call-actor小规模试运行、代码是否从环境变量取令牌、是否处理了重复数据与失败分支、是否附带了测试步骤与文档。这套组合——frontmatter 声明 MCP 工具白名单、正文规定五步工作流与安全护栏、正文内嵌可直接运行的双语代码——正是 awesome-copilot 仓库中“专家型集成 Agent”的典型范式把第三方服务的集成知识固化为可安装、可校验、可复用的文件配置。参考资料Agent 定义与全部代码示例agents/apify-integration-expert.agent.md自定义 Agent 使用说明docs/README.agents.mdpartners 插件清单plugins/partners/plugin.jsonfrontmatter 解析实现eng/yaml-parser.mjsMCP 声明校验规则eng/agent-plugin-schema.mjs、eng/validate-plugins.mjs外部 Apify 插件登记plugins/external.json【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考