microsoft-sharepoint

Microsoft SharePoint

面向 Microsoft SharePoint Online 的 Agent 可调用工具，基于 Microsoft Graph API v1.0（https://graph.microsoft.com/v1.0/sites/...）：查找站点和文档库；浏览、搜索、上传、下载、移动、复制和共享文件及文件夹；管理 SharePoint 列表和列表项；以及编写和发布站点页面。涵盖站点、驱动器、文件和文件夹、共享和权限、列表、列表项及页面，共 32 个脚本。只读导航工具可解析写入工具所需的 ID（siteId、driveId、listId、pageId、列内部名称）——站点使用从 findSites/getSite 获取的不透明复合 ID 寻址，切勿手动构造。

独立的非官方 Microsoft SharePoint 连接器。与 Microsoft SharePoint 无关联，也未获得其背书或赞助。“Microsoft SharePoint”是其所有者的商标，仅用于标识此连接器所适用的服务。

适用场景

• Agent 需要查找或读取 SharePoint 内容——搜索站点、列出站点的文档库、浏览或搜索文件和文件夹，或读取文件、列表项或页面的详细信息。
• Agent 需要处理文件——创建文件夹、上传文本或二进制文件、移动／复制／重命名、导出为 PDF 或 HTML，或共享（链接和按人员授予权限）并管理权限。
• Agent 需要处理列表——列出站点的列表、查看列表的列、创建列表，以及创建／读取／更新／删除列表项。
• Agent 需要编写页面——创建站点页面草稿（可选添加正文文本），并发布该页面。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先运行 npx skills add zapier/connectors --skill microsoft-sharepoint 安装（或使用你自己的执行环境提供的技能安装机制），然后继续操作。安装技能只会复制这些文件，不会安装依赖项。运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。要在自己的项目中将已发布的软件包作为依赖项导入？运行 npm install 时已经会解析所有依赖项——请参阅 references/use-as-sdk.md。

想查看实际的仓库源代码，例如浏览 references/、运行此连接器的测试，或对其进行修改？请参阅 README.md，了解如何克隆指定范围的代码。

此连接器需要 Node.js 22.18+。选择与你的运行方式相匹配的参考文档，并在进行其他操作前先阅读：

你有……	阅读
支持 MCP 的客户端——工具可能已加载（例如 mcp__microsoft-sharepoint__<tool>），或者你可以自行注册本地服务（或引导用户注册）	references/use-as-mcp.md
终端 / 子进程访问权限（可以运行 node）	references/use-as-cli.md
只有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法访问工具或终端，也无法导入此软件包——你需要编写自己的代码，直接调用 Microsoft SharePoint API（例如，在代码执行沙箱中）	references/use-as-recipe.md

脚本

除 getCopyStatus 外，所有脚本都使用同一个连接 microsoft-sharepoint。getCopyStatus 无需连接（它会轮询一个预先完成身份验证的监控 URL）。

脚本	脚本名称	连接	描述
scripts/findSites.ts	findSites	microsoft-sharepoint	按关键词搜索站点；主要的站点发现入口。
scripts/getSite.ts	getSite	microsoft-sharepoint	按复合 ID、root 或 {hostname}:/{path} 获取站点。
scripts/listDrives.ts	listDrives	microsoft-sharepoint	列出站点的文档库，以解析 driveId。
scripts/listFolderItems.ts	listFolderItems	microsoft-sharepoint	列出文件夹或驱动器根目录的直接子项。
scripts/findFiles.ts	findFiles	microsoft-sharepoint	在驱动器中按名称或内容搜索文件和文件夹。
scripts/getItem.ts	getItem	microsoft-sharepoint	按 ID 获取文件或文件夹的元数据（含下载 URL）。
scripts/createFolder.ts	createFolder	microsoft-sharepoint	在根目录或其他文件夹内创建文件夹。
scripts/uploadTextFile.ts	uploadTextFile	microsoft-sharepoint	根据字符串内容创建小型文本文件。
scripts/uploadFile.ts	uploadFile	microsoft-sharepoint	从源 URL 上传二进制文件（支持大文件）。
scripts/replaceFile.ts	replaceFile	microsoft-sharepoint	从源 URL 替换现有文件的内容。
scripts/moveItem.ts	moveItem	microsoft-sharepoint	在同一文档库中移动或重命名项目。
scripts/copyItem.ts	copyItem	microsoft-sharepoint	将文件/文件夹复制到其他文件夹或驱动器（异步）。
scripts/getCopyStatus.ts	getCopyStatus	(none)	轮询由 copyItem 启动的异步复制状态。
scripts/deleteItem.ts	deleteItem	microsoft-sharepoint	删除文件或文件夹（移至回收站）。
scripts/exportFile.ts	exportFile	microsoft-sharepoint	下载转换为 PDF / HTML / JPG / GLB 的文件。
scripts/createSharingLink.ts	createSharingLink	microsoft-sharepoint	为项目创建可共享链接（查看/编辑/嵌入）。
scripts/inviteToItem.ts	inviteToItem	microsoft-sharepoint	授予指定人员对项目的读取/写入权限。
scripts/listItemPermissions.ts	listItemPermissions	microsoft-sharepoint	列出文件或文件夹的权限。
scripts/removeItemPermission.ts	removeItemPermission	microsoft-sharepoint	撤销对文件或文件夹的权限。
scripts/listLists.ts	listLists	microsoft-sharepoint	列出站点的列表（也可用于查询单个列表）。
scripts/createList.ts	createList	microsoft-sharepoint	在站点中创建新列表。
scripts/listColumns.ts	listColumns	microsoft-sharepoint	列出列表的列定义（内部字段名称）。
scripts/findListItems.ts	findListItems	microsoft-sharepoint	列出或筛选列表中的项目，并返回列值。
scripts/getListItem.ts	getListItem	microsoft-sharepoint	获取单个列表项目及其列值。
scripts/createListItem.ts	createListItem	microsoft-sharepoint	在列表中创建新项目。
scripts/updateListItem.ts	updateListItem	microsoft-sharepoint	更新现有列表项目的列值。
scripts/deleteListItem.ts	deleteListItem	microsoft-sharepoint	删除列表项目（永久删除，不移至回收站）。
scripts/listPages.ts	listPages	microsoft-sharepoint	列出站点页面，以解析 pageId。
scripts/getPage.ts	getPage	microsoft-sharepoint	按 ID 获取单个站点页面。
scripts/createPage.ts	createPage	microsoft-sharepoint	创建站点页面草稿，可选择添加文本内容。
scripts/publishPage.ts	publishPage	microsoft-sharepoint	发布站点页面草稿。
scripts/deletePage.ts	deletePage	microsoft-sharepoint	删除站点页面（移至回收站）。

消歧与拒绝

写入前先消歧。 在写入通过名称查找到的对象之前——findSites 找到的网站、listLists 返回的列表，或 findListItems 找到的列表项——请统计名称完全匹配（不区分大小写）的项数：

• 恰好匹配一项——对其执行操作。不要过度追问；只有一个明确匹配项时，直接使用即可。
• 有两项或更多并列匹配——停止操作。列出并列候选项及其可用于区分的字段（webUrl、id 或 lastModifiedDateTime），并询问用户指的是哪一项。不要随意挑选，也不要对所有候选项进行写入。网站名称尤其容易在不同部门间重复（例如，两个名为“Marketing”的网站）。

不支持的操作——说明情况并停止；不要用其他工具伪装实现。 此目录明确不支持以下操作：

• 在库或网站之间移动文件（不支持原生移动）。 moveItem 仅支持在同一库内移动。跨库或跨网站迁移的唯一方法是 copyItem → (getCopyStatus) → deleteItem，但这种方式有损：副本会获得新的 id 和 URL，原文件的共享链接和权限不会保留，而且复制失败一半时可能会丢失文件。用户要求将文件移到其他位置时，你可以执行这种迁移，但绝不能将其说成普通的“移动”：事先警告用户这是先复制再删除，告知文件的 URL/id 会改变，且共享链接和权限不会保留；删除原文件前，使用 getCopyStatus 确认复制成功，并告知用户新的位置。绝不能在未说明的情况下复制并删除，然后声称已完成移动。
• 编辑现有页面正文，或添加非文本 Web 部件（图片、嵌入内容、快速链接、多栏布局）。createPage 仅能在新页面上创建一个文本 Web 部件；编辑现有页面内容以及添加富 Web 部件均不在支持范围内。不要删除页面再重新创建来模拟编辑——这会更改页面的 id/URL，并丢失其版本历史记录、评论和权限。告知用户不支持原位编辑正文，然后停止。
• 枚举租户中的所有网站。 没有“列出所有网站”功能——委托令牌无法执行此操作。请使用 findSites（关键词搜索），或对已知路径使用 getSite。
• 管理内容类型、网站列、术语库元数据或触发器（新文件/新项目通知）。这些功能未开放。
• 写入列表项中的人员/组列或多值查找列。 此处这些列类型为只读。

如果用户要求上述任何操作，请告知其不受支持并停止——不要尝试使用无关工具来近似实现。

认证

每种形态都会将认证信息作为连接选择器传递，而不是密钥——格式为 [<resolver>:]<value> 的字符串。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的认证——通过 Zapier 的认证、重试和治理层进行路由）；部分连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请查看此连接器自己的解析器，不要想当然。<resolver>: 前缀是可选的；不带前缀的值会交给第一个认领它的解析器——符合 UUID 格式的不带前缀值始终会被 zapier: 认领。每个脚本都会声明所需的连接，以及它接受的解析器。传递连接的具体语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考文档。

想先检查已配置的内容？不要为了检查而导出环境变量的值——env 或 env | grep <name> 会同时打印变量名和值；如果已设置，这会将有效凭证泄漏到记录中。只检查变量名（env | cut -d= -f1 | grep -i <name>），或直接测试已知变量名（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式——并按照参考文档自身的流程获取连接；不要直接询问用户连接 ID 或令牌，仿佛他们早已记得这些信息：

	加载
直接传递凭证	references/use-without-zapier.md
通过 Zapier 连接进行路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形态由 outputSchema 声明；请参阅上文加载的参考文档，了解如何查看所用形态中脚本的确切架构）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剔除：脚本从 API 返回的字段未在 outputSchema 中声明。如果需要这些字段，请在重新运行时跳过输出验证。
  • { skipped: true } — 已绕过验证；data 是未经检查的原始脚本输出。

读取被剔除的字段／skipOutputDataValidation。 若要接收未经验证的原始结果，请选择跳过输出验证（具体语法因形态而异——请参阅上文加载的参考文档）。输入验证永远不会跳过。

精简结果／filterOutputData。 若要将大型结果缩减为所需字段，请传入一个 jq 表达式，对 data 进行后处理（具体语法同样因形态而异）。jq 仅针对 data 运行，而非 { data, meta } 信封，因此表达式应以 data 为根（运行脚本的 --help——或所用形态的等效命令——可查看其输出架构）。转换后的值会替换 data，meta 则保持不变；结果不会再次根据输出架构进行验证。

参考资料

开始处理相关领域前，请先加载对应的参考文件：

参考资料	涵盖内容	何时加载
microsoft-sharepoint-api-gotchas.md	Graph 权限范围、错误封装（403/404/429）、分页、站点/驱动器寻址、短时效下载 URL、异步复制、可续传上传、同一驱动器内移动、删除语义、共享链接/邀请/权限、列表项列值（LookupId、12 个查找项的限制、多值），以及站点页面的草稿/发布/类型转换规则。	调用意外报错（403/404/429、名称冲突）、解析站点或驱动器 ID、处理列表项列值，或创建/发布站点页面时。