add-sharepoint

📋 共享说明：shared-instructions.md - 跨领域注意事项。

参考资料：

• sharepoint-reference.md - 列编码、选项字段、查找列、API 模式（重要）
• api-authentication-reference.md - Graph API 身份验证、令牌、站点 ID
• list-management-reference.md - 查询、创建和扩展列表及列

添加 SharePoint

两种路径：现有列表（跳转至第 6 步）或新建列表（完整工作流）。

工作流

1. 检查 Memory Bank → 2. 规划 → 3. 设置 Graph API 身份验证 → 4. 检查现有列表 → 5. 创建列表 → 6. 获取连接 ID → 7. 发现站点 → 8. 发现表 → 9. 添加连接器 → 10. 配置 → 11. 构建 → 12. 更新 Memory Bank

---

第 1 步：检查 Memory Bank

根据 shared-instructions.md 检查 memory-bank.md。

第 2 步：规划

询问用户：

1. 他们需要哪些 SharePoint 列表？
2. 这些列表在其站点上是否已存在，还是需要新建？

**如果列表已存在：**跳转至第 6 步。

如果要新建列表：

• 询问所需数据，并设计合适的架构
• 尽可能重复使用现有列表（不要重复创建）
• 使用 EnterPlanMode 进入计划模式，并列出包含列和类型的列表设计
• 使用 ExitPlanMode 获取批准

第 3 步：设置 Graph API 身份验证（如果要创建列表）

完整详情请参阅 api-authentication-reference.md。

az account show   # Verify Azure CLI logged in

$api = Initialize-SharePointGraphApi -SiteUrl "https://<tenant>.sharepoint.com/sites/<site-name>"
$headers = $api.Headers
$siteId = $api.SiteId

需要 Sites.Manage.All 权限。

第 4 步：检查现有列表（如果要创建列表）

创建前务必先查询现有列表：

$existingLists = Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/sites/$siteId/lists?`$select=id,displayName,description,list&`$filter=list/hidden eq false" -Headers $headers

有关 Find-SimilarLists、Compare-ListSchemas 和 Get-ListSchema 函数，请参阅 list-management-reference.md。

使用 AskUserQuestion 向用户展示查询结果：

• 可重复使用的列表（已存在且列匹配）
• 需要扩展的列表（已存在但缺少列）
• 必须创建的列表（未找到匹配项）

第 5 步：创建列表（如果要创建列表）

创建前需获得明确确认。使用 list-management-reference.md 中的安全函数：

• New-SharePointListIfNotExists
• Add-SharePointColumnIfNotExists
• Add-SharePointLookupColumn（用于跨列表引用）

第 6 步：获取连接 ID

查找 SharePoint Online 连接 ID（请参阅 connector-reference.md）：

运行 /list-connections 技能。在输出中找到 SharePoint Online 连接。如果没有，请引导用户使用特定环境的 Connections URL 创建连接——根据上下文中的活动环境 ID（来自 power.config.json 或前面的步骤）构造此 URL：https://make.powerapps.com/environments/<environment-id>/connections → + New connection → 搜索连接器 → Create。

第 7 步：发现站点

列出用户有权访问的 SharePoint 站点：

pa connector list-datasets --connector sharepointonline -c <connection-id>

向用户展示站点，并询问要连接哪些站点。如果用户已指定站点 URL，请确认该 URL 出现在列表中。

如果 pa connector list-datasets 失败或未返回结果：

• 身份验证错误：运行 pa auth logout（如果项目仅使用 power-apps，则运行 power-apps logout），然后重试——CLI 会再次提示用户通过浏览器登录。
• 列表为空：确认连接 ID 对应的是 SharePoint Online 连接，并且用户至少有权访问一个站点。确认后如果列表仍为空，则停止。
• 其他任何非零退出：报告完整的错误输出。停止。

第 8 步：发现表

对于每个选中的站点，列出可用的列表和文档库：

pa connector list-tables --connector sharepointonline -c <connection-id> -d '<site-url>'

如果 pa connector list-tables 执行失败或未返回结果：

• 确认第 7 步中的站点 URL 完全准确（从输出中复制，不要重新输入）。
• 如果仍然为空，用户可能没有访问该站点列表的权限。请让他们在 SharePoint 中确认权限。
• 其他任何非零退出状态：报告确切的错误输出。停止。

向用户展示这些表，并询问他们想添加哪些表。根据记忆库上下文或用户说明的要求，建议看起来与其使用场景相关的表。如果在第 5 步创建了列表，它们应该会显示在这里。

第 9 步：添加连接器

SharePoint 是表格型数据源，需要 -c（连接 ID）、-d（站点 URL）和 --table（列表名称）：

pa app add data-source --connector sharepointonline -c <connection-id> -d '<site-url>' --table '<table-name>'

对用户选择的每个列表或文档库运行此命令。-d（数据集）是第 7 步中的 SharePoint 站点 URL，--table 是第 8 步中的列表或文档库名称。

第 10 步：配置

编写任何 SharePoint 代码之前，请阅读 sharepoint-reference.md——列编码、选项字段和查找字段都有关键注意事项。

常见操作：

// Get items from a SharePoint list
const items = await SharePointOnlineService.GetItems({
  dataset: "https://contoso.sharepoint.com/sites/your-site",
  table: "Your List Name"
});

// Create a new list item
await SharePointOnlineService.PostItem({
  dataset: "https://contoso.sharepoint.com/sites/your-site",
  table: "Your List Name",
  item: {
    Title: "New Item",
    Description: "Item description",
    Status: "Active"
  }
});

// Get files from a document library
const files = await SharePointOnlineService.ListFolder({
  dataset: "https://contoso.sharepoint.com/sites/your-site",
  id: "Shared Documents" // Library name or folder ID
});

// Get file content
const content = await SharePointOnlineService.GetFileContent({
  dataset: "https://contoso.sharepoint.com/sites/your-site",
  id: "file-server-relative-url"
});

要点：

• dataset 始终是完整的 SharePoint 站点 URL
• table 是列表操作中的列表显示名称
• API 中的列表列名称可能与显示名称不同（空格会变成 _x0020_，特殊字符会经过编码）
• 文档库操作使用文件夹/文件 ID 或服务器相对 URL
• 选项列使用字符串值，而不是整数选项代码（与 Dataverse 不同）

使用 Grep 在 src/generated/services/SharePointOnlineService.ts 中查找特定方法（生成的文件可能非常大——请参阅 connector-reference.md）。

第 11 步：构建

npm run build

继续之前，请修复 TypeScript 错误。此时不要部署。

第 12 步：更新记忆库

在 memory-bank.md 中更新：已添加的连接器、站点 URL、已配置（或创建）的列表/文档库，以及构建状态。