# 智链 Excel-MCP 安装指引（AI Agent 执行版）

> **适用对象**：受用户委托执行安装的 AI Agent（WorkBuddy / CodeBuddy / Claude / Cursor / Cline / VS Code 及其他支持 MCP 协议的客户端）
> **用途**：在用户本机完成智链 Excel-MCP 的下载、安装与 MCP 配置写入
> **执行约定**：严格按第 1～5 章顺序执行；安装方法以本文档为唯一依据，不得使用本文档之外的步骤
> **维护约定**：安装命令或流程变更时，同步更新本文档并上传分发站
> **文档更新**：2026-08-29

## 1 前置条件检查

安装前逐项确认下表条件，全部满足方可继续；任一不满足，向用户说明原因并终止，不得继续安装：

| 序号 | 条件 | 不满足时的处理 |
|---|---|---|
| 1 | 当前环境为 Windows 操作系统 | 告知用户本工具仅支持 Windows，终止 |
| 2 | 已安装 Microsoft Excel（2016 及以上版本） | 告知用户不支持 WPS / LibreOffice，终止 |

无法自行确认第 2 项时，询问用户：「这台电脑装的是 Microsoft Excel 吗？」

## 2 确定 Agent 参数值

第 3 章的安装命令需要 `-Agent` 参数，取值仅限以下 6 个：

| 参数值 | 对应软件 |
|---|---|
| `workbuddy` | WorkBuddy |
| `codebuddy` | CodeBuddy |
| `claude` | Claude Desktop |
| `cursor` | Cursor |
| `cline` | Cline（VS Code 扩展） |
| `vscode` | VS Code |

按以下规则确定取值，并将结果记录备用：

1. 你运行在哪个软件中，即取该软件对应的参数值；
2. 无法自行确定时，询问用户：「你在哪个软件里和我对话？」按用户回答取值；
3. 你的运行环境不在上表内（其他 MCP 客户端）：程序安装不受影响——任取表内一个参数值执行第 3 章完成程序安装，再按附录 A.2 将 `excel-v2` 条目写入当前软件的 MCP 配置，随后直接执行第 5 章。

## 3 执行安装命令

以下命令以参数值 `workbuddy` 为例。将 `workbuddy` 替换为第 2 章确定的值，**其余字符一律不得改动**，整条执行：

```powershell
powershell -c "& ([scriptblock]::Create((irm 'https://wiselink.yxqgzs.com/install.ps1'))) -Agent workbuddy"
```

命令行为说明（执行前知悉，无需人工干预）：

1. 从分发站下载主程序（约 76 MB）与框选助手（约 111 MB），合计约 190 MB。耗时取决于网络与电脑配置：快则 1～3 分钟，网络慢或电脑配置低时可能 5～15 分钟甚至更久。下载期间每 10 MB 会输出一次 `[download] x/yMB` 进度——**有新输出就说明在正常工作，哪怕很慢也不得中途取消**；
2. 自动完成：程序安装至 `%USERPROFILE%\excelv2-mcp\excel\`；`SKILL.md`（操作指南）与 `MANUAL.md`（使用手册）安装至技能目录；旧版本自动改名备份；将 `excel-v2` 条目合并写入 MCP 配置文件（保留既有条目，写入前自动备份）。

## 4 结果判定与故障处理

成功判定标准（唯一）：命令输出末尾出现 `Install complete`，即安装成功，执行第 5 章。

未出现该输出时，按下表处理，处理完毕后重新执行第 3 章：

| 输出特征 | 原因 | 处理方式 |
|---|---|---|
| `download attempt N failed` | 网络波动 | 原样重跑命令（脚本已内置 3 次重试，通常重跑即可通过） |
| `file still locked` | 旧版文件被占用 | 请用户退出对应软件后重跑命令 |
| 输出提示环境不符 | 第 1 章前置条件不满足 | 按第 1 章处理：告知用户并终止 |
| 命令被拦截、无法执行 | 终端权限受限 | 改用附录 A 手动方式 |

## 5 收尾告知（必做，Agent 不可代办）

配置写入后，须经用户操作方可生效。向用户原样转达以下内容：

> ✅ 安装完成。请重启 [你所在的软件名]，WorkBuddy 还需在「连接器管理」中信任 **excel-v2**，之后就能让我实时操作你的 Excel 了。

注意：用户完成上述操作之前，Excel 相关工具不可调用属正常现象，不得反复尝试调用工具进行验证。

---

## 附录 A 备用手动方式

适用场景：① 第 3 章命令被拦截无法执行；② 运行环境不在第 2 章参数表内。

### A.1 程序安装

已成功执行第 3 章命令的，程序已安装到位，跳过本小节；否则执行：

```powershell
$root = "$env:USERPROFILE\excelv2-mcp\excel"
New-Item -ItemType Directory -Force -Path $root | Out-Null
iwr https://wiselink.yxqgzs.com/ExcelMcpServer.exe -OutFile "$root\ExcelMcpServer.exe"
```

### A.2 写入 MCP 配置

在当前软件 MCP 配置文件的 `mcpServers` 对象内合并写入以下条目（不删除既有条目；以 UTF-8 无 BOM 编码保存；修改前先备份原文件）：

```json
"excel-v2": { "type": "stdio", "command": "C:\\Users\\你的用户名\\excelv2-mcp\\excel\\ExcelMcpServer.exe" }
```

各软件 MCP 配置文件位置：

| 软件 | 配置文件路径 |
|---|---|
| WorkBuddy | `%USERPROFILE%\.workbuddy\mcp.json` |
| CodeBuddy | `%USERPROFILE%\.codebuddy\mcp.json` |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `%USERPROFILE%\.cursor\mcp.json` |
| Cline | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
| VS Code | `%APPDATA%\Code\User\mcp.json`（顶层键为 `servers`） |

完成后执行第 5 章收尾告知。

## 附录 B 安装后使用须知（供 Agent 阅读）

1. 工具清单、通道策略与安全红线见随程序安装的 `SKILL.md`（skills/excel-ai-operator），建议使用前完整阅读；
2. 安全红线：严禁擅自关闭、保存或退出用户的 Excel 文件；涉及保存、关闭的操作必须事先征得用户同意；
3. 用户询问产品类问题（本工具是什么、数据是否安全、是否收费等）时，以技能目录中随装的 `MANUAL.md`（使用手册）为依据回答，不得编造。