🤖 AI 接入指南

深爱办公插件支持通过 MCP（Model Context Protocol） 协议将全部子插件命令暴露给外部 AI 工具（Claude、Cursor、Windsurf 等），让 AI 助手直接调用 WPS 表格中的插件功能。

📐 架构概览

• AI 客户端通过 stdio 与 MCP Bridge 通信（JSON-RPC 2.0）
• MCP Bridge将 MCP 协议转换为 HTTP 请求，转发给主插件
• AiApiHost在 WPS 进程内监听 127.0.0.1:28765，执行实际命令
• 子插件命令在隔离 AppDomain 中运行，结果原路返回

📋 前置条件

1. 已安装 深爱办公插件（宿主）并在 WPS 表格中正常加载
2. 已安装 .NET 8 运行时（MCP Bridge 依赖）
3. WPS 表格处于 运行状态（AiApiHost 随主插件启动）
4. 已获取 访问令牌（见下方说明）

🔑 获取访问令牌

主插件首次启动后，打开以下文件获取令牌：

%AppData%\SloverAddin\config\ai_api_token.txt

文件内容为一串 64 位十六进制字符，例如：

a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef01

⚙️ Claude Desktop 配置

编辑 Claude Desktop 配置文件：

• Windows: %AppData%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "slover-addin": {
      "command": "dotnet",
      "args": [
        "C:\\path\\to\\SloverAddin.McpBridge.dll"
      ],
      "env": {
        "MCP_BRIDGE_TOKEN": "你的令牌粘贴在这里"
      }
    }
  }
}

⚙️ Cursor 配置

在 Cursor 设置中找到 MCP Servers 部分，添加新的 MCP Server：

• Name: slover-addin
• Command: dotnet
• Args: C:\path\to\SloverAddin.McpBridge.dll
• Env: MCP_BRIDGE_TOKEN=你的令牌

或直接编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "slover-addin": {
      "command": "dotnet",
      "args": ["C:\\path\\to\\SloverAddin.McpBridge.dll"],
      "env": {
        "MCP_BRIDGE_TOKEN": "你的令牌"
      }
    }
  }
}

⚙️ Windsurf 配置

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "slover-addin": {
      "command": "dotnet",
      "args": ["C:\\path\\to\\SloverAddin.McpBridge.dll"],
      "env": {
        "MCP_BRIDGE_TOKEN": "你的令牌"
      }
    }
  }
}

✅ 验证连接

配置完成后重启 AI 客户端，在对话中尝试：

1. 询问 "列出可用的深爱插件工具" — 应返回 138 个工具
2. 询问 "调用 game.chess_new 开始一局象棋" — 应成功执行
3. 询问 "调用 funclib.text_sort 对文本排序" — 应返回排序结果

🔒 安全说明

• 令牌认证：每个请求需携带 Bearer Token，令牌由主插件自动生成
• 本地通信：HTTP 仅监听 127.0.0.1，不暴露到网络
• 频率限制：每 IP 每 10 秒最多 60 次请求
• 请求大小：单次请求体上限 1MB
• 审计日志：所有请求记录到 %AppData%\SloverAddin\logs\ai_api_audit.log

🔧 故障排查

AI 客户端无法连接

• 确认 WPS 表格正在运行（主插件已加载）
• 确认 127.0.0.1:28765 可访问（浏览器打开 http://127.0.0.1:28765/health）
• 确认令牌正确（对比 ai_api_token.txt 文件内容）
• 确认 .NET 8 运行时已安装（dotnet --version）

工具列表为空

• 确认主插件已加载子插件（在 WPS 中检查插件管理窗体）
• 查看审计日志是否有权限拒绝记录

命令执行失败

• 检查命令名称格式：pluginId.commandId（如 game.chess_new）
• 确认对应子插件已购买/授权或免费
• 查看审计日志中的错误详情

📚 可用命令概览

当前已暴露全部 138 个子插件命令，按插件分类：