内容
# SharePoint 页面迁移代理（预览版）
AI 辅助将**经典 SharePoint 页面**（wiki、网页部件、发布）迁移到**现代 SharePoint 页面**。AI 代理（Claude Code、GitHub Copilot 或任何支持 MCP 的主机）驱动本地的 **Model Context Protocol（MCP）服务器**来完成工作。
---
## 为什么使用它
经典页面无法在现代编辑器中打开，并且缺少现代功能（响应式布局、现代网页部件、Viva、Copilot 界面）。微软已经提供了一个确定的 [PnP 页面转换](https://learn.microsoft.com/sharePoint/dev/transform/modernize-classic-pages) 管道 — 如果这满足您的需求，**请使用它**。
该项目是一个**互补的、AI 驱动的**替代方案。当页面具有自定义 HTML、脚本编辑块或需要判断的布局，并且您希望对每个页面进行人工审查时，可以使用它。
| 您的情况 | 使用 |
|---|---|
| 大批量、确定的迁移；需要官方支持 | **PnP 页面转换** |
| 自定义 HTML / 脚本 / 布局需要判断 | **该项目** |
| 单个页面高保真迁移，逐页审查 | **该项目** |
---
## 工作原理
代理运行本地 MCP 服务器，并通过四个技能来工作：
- **提取和理解** — 将经典页面读取到内部模型。
- **转换和创建** — 将每个部分映射到最接近的现代网页部件，并创建现代页面。
- **比较和完善** — 打开两个页面，评估它们的匹配程度，并迭代改进保真度。
- **迁移站点** — 在站点中的每个经典页面上运行上述操作。
登录使用 Playwright 通过真实浏览器进行。您每个租户只需进行一次身份验证；会话保存到 `~/.classic-to-modern/browser-profile/` 并重新使用。
---
## 先决条件
- Node.js 20+
- 支持 MCP 的 AI 主机（Claude Code、带有 MCP 的 GitHub Copilot 等）
- 具有权限的 SharePoint Online 租户，可以读取经典页面并在目标站点上创建现代页面
- 本地安装 Chrome / Edge（Playwright 驱动真实浏览器进行身份验证）
---
## 设置
```bash
git clone https://github.com/pnp/SharePointPageModernizationAgent.git
cd SharePointPageModernizationAgent
```
### 选项 A — 一步式脚本（推荐）
设置脚本检查 Node.js、安装依赖项、构建服务器、运行烟雾测试、验证 MCP 服务器启动（真正的 `initialize` 握手）并为您创建 `.mcp.json`。从存储库根目录运行：
```powershell
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```
```bash
# macOS / Linux / WSL / Git Bash
./setup.sh
```
然后跳到 [如何使用](#如何使用)。
### 选项 B — 手动步骤
```bash
cd mcp-server
npm install
npx tsc
```
---
## 如何使用
从存储库根目录运行所有操作 — **不要**全局安装技能或工具。
**1. 启动您的主机** 并使用 `/mcp` 确认服务器已加载（查找 `classic-to-modern`）：
```powershell
copilot # GitHub Copilot CLI
claude # Claude Code
```
**2. 登录** 时会出现提示 — 代理通过 Playwright 在第一次访问页面时打开浏览器。每个租户只需登录一次。
**3. 迁移页面** 通过用普通语言描述它：
> 将此经典页面迁移到现代页面：
> `https://contoso.sharepoint.com/sites/Marketing/SitePages/OldHome.aspx`
代理自动提取、转换、创建和完善，然后为您提供新现代页面的 URL。一些变体：
> 只是提取和分析 `https://contoso.sharepoint.com/sites/HR/SitePages/Policies.aspx` — 暂时不要创建现代页面，显示您找到的内容。
> 迁移此页面，但保留任何脚本编辑器内容作为解释性文本注释，而不是尝试重现它。
> 重新迁移 `OldHome.aspx` 并覆盖现有的现代页面。
> **发布页面** 可以在**同一站点**中迁移，当**站点页面**功能激活时（存在站点页面库）。如果未激活此功能，则站点无法承载现代页面 — 告诉代理**目标站点**：
>
> 迁移 `https://contoso.sharepoint.com/sites/News/Pages/Article.aspx` 并在 `https://contoso.sharepoint.com/sites/NewsModern` 上创建现代页面。
**4. 迁移整个站点** 通过指向代理：
> 迁移 `https://contoso.sharepoint.com/sites/Marketing` 上的所有经典页面到现代页面。
它发现页面，迁移它们（并行执行多个），并报告质量分数以及任何需要仔细检查的页面。您也可以先进行范围或规划：
> 列出 `https://contoso.sharepoint.com/sites/Marketing` 上的经典页面，并为我提供迁移计划 — 暂时不要迁移任何内容。
> 仅迁移 `https://contoso.sharepoint.com/sites/Marketing` 上的 `SitePages` 库下的页面。
**5. 审查和完善。** 在发布或删除任何内容之前，请打开生成的页面与原始页面进行比较。对于无法完美重现的内容，将保留解释性文本，描述丢失的内容并建议现代替代方案。要求代理修复任何不正确的部分：
> 比较您刚刚创建的现代页面与经典原始页面，并告诉我保真度分数。
> `OldHome.aspx` 的布局不正确 — 请再次比较和完善该页面。
> 英雄图像未传输过来。重新检查经典页面并修复现代页面上的图像网页部件。
### 提示
- **从单个页面开始。** 在进行整个站点运行之前，请在代表性页面上验证结果。
- **注意令牌成本。** 迁移由 AI 驱动，并消耗模型令牌。大页面和整个站点运行可能会消耗大量令牌，这可能会根据您的计划产生成本 — 另一个原因是在单个页面上进行测试。
- **URL 应具体** — 粘贴完整的经典页面或站点 URL。
- **重新运行精细化** 如果页面不够接近，例如 *"布局不正确，请再次比较和精细化该页面。"*
---
## 许可证
在 [MIT 许可证](LICENSE) 下许可。
