workiq-wsl

WorkIQ WSL 桥接技能

通过桥接到安装了 WorkIQ 插件的 Windows 原生 Copilot CLI，从 WSL2 访问 Microsoft 365 数据——电子邮件、日历、文件、Teams。

用途

由于 WorkIQ MCP 服务依赖 Windows 原生身份验证（通过浏览器进行 M365 SSO），WSL2 环境无法原生运行它。此技能通过 powershell.exe 将 M365 查询路由到 Windows Copilot CLI，从而解决这一问题。该 CLI 可完整访问 WorkIQ MCP 服务和 Microsoft Graph API。

这意味着你可以查询电子邮件、查看日历、搜索文件和阅读 Teams 消息，而无需离开 WSL 终端会话。

先决条件

1. 安装 Linux 发行版的 WSL2

你必须在 WSL2 中运行（不能是 WSL1 或原生 Linux）。

# Verify WSL2
grep -qi microsoft /proc/version && echo "WSL detected" || echo "Not WSL"

2. Windows 原生 Copilot CLI

在 Windows 主机上安装（不要在 WSL 中安装）：

# From Windows Terminal or PowerShell
winget install GitHub.Copilot

在 WSL 中验证：

powershell.exe -NoProfile -Command "copilot --version" 2>&1

3. GitHub 身份验证

对 Windows Copilot CLI 进行身份验证：

powershell.exe -NoProfile -Command "copilot login" 2>&1

4. WorkIQ 插件

在 Windows Copilot CLI 中安装 WorkIQ 插件：

powershell.exe -NoProfile -Command "copilot plugin install workiq" 2>&1

5. M365 身份验证

首次使用时，WorkIQ 会提示你进行 Microsoft SSO 身份验证。Windows 主机上会打开浏览器窗口供你登录。无需额外设置，只需批准许可提示即可。

工作原理

WSL Copilot CLI session
     │
     ▼
powershell.exe -NoProfile -Command "copilot -p '...' --allow-all-tools --silent --no-auto-update 2>&1"
     │
     ▼
Windows Copilot CLI (native)
     │
     ▼
WorkIQ MCP Server (npx @microsoft/workiq@latest mcp)
     │
     ▼
Microsoft Graph API → M365 (emails, calendar, files, Teams)

每次查询都会启动一个 powershell.exe 进程，通过自然语言提示词调用 Windows Copilot CLI。--allow-all-tools 标志授予 Copilot CLI 调用 WorkIQ MCP 工具的权限，该工具会代表你查询 Microsoft Graph。

关键标志：

• --allow-all-tools — 允许 Copilot 使用 WorkIQ，无需手动批准
• --silent — 抑制交互式界面元素
• --no-auto-update — 阻止会拖慢执行速度的更新检查
• 2>&1 — 捕获 Windows 端的标准输出和标准错误

使用示例

查看今天的会议

powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to answer: What meetings do I have today?' --allow-all-tools --silent --no-auto-update 2>&1"

查找某人的近期电子邮件

powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to find all emails from Dustin Duran. Show me the 5 most recent ones with their subject lines, dates sent, and a brief summary of each email.' --allow-all-tools --silent --no-auto-update 2>&1"

搜索文件

powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to answer: Find my most recent PowerPoint files in OneDrive and SharePoint.' --allow-all-tools --silent --no-auto-update 2>&1"

获取电子邮件摘要

powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to answer: Summarize the most important unread emails in my inbox from the last 24 hours.' --allow-all-tools --silent --no-auto-update 2>&1"

查看本周日历

powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to answer: What does my calendar look like for the rest of this week? List all meetings with times and attendees.' --allow-all-tools --silent --no-auto-update 2>&1"

激活说明

当用户在 WSL 环境中提及电子邮件、日历、会议、M365、Microsoft 365、Outlook 或 WorkIQ 时，此技能会激活。

检测逻辑

激活后，按顺序执行以下检查：

1. 检测 WSL 环境：

   grep -qi microsoft /proc/version
   

   如果不是 WSL，则回退到标准的 work-iq 技能（原生 MCP 方式）。

2. 检查 Windows Copilot 是否可用：

   powershell.exe -NoProfile -Command "copilot --version" 2>&1
   

   如果未找到，则指导用户安装（参见先决条件 §2）。

3. 检查是否已安装 WorkIQ 插件：

   powershell.exe -NoProfile -Command "copilot plugin list" 2>&1 | grep -i workiq
   

   如果未找到，则指导用户安装（参见先决条件 §4）。

4. **路由查询：**使用用户的自然语言问题构建 powershell.exe 命令并执行：

   powershell.exe -NoProfile -Command "copilot -p 'Use the workiq ask_work_iq tool to answer: <USER_QUERY>' --allow-all-tools --silent --no-auto-update 2>&1"
   

5. **解析并呈现：**从 Copilot CLI 输出中提取相关答案，并清晰地呈现给用户。

缺少先决条件时

指导用户完成设置：

It looks like you're in WSL but the Windows Copilot CLI isn't set up for WorkIQ yet.

To set up M365 access from WSL:
1. Install Copilot CLI on Windows: winget install GitHub.Copilot
2. Authenticate: powershell.exe -NoProfile -Command "copilot login"
3. Install WorkIQ: powershell.exe -NoProfile -Command "copilot plugin install workiq"
4. Try your query again — WorkIQ will prompt for M365 sign-in on first use.

故障排除

问题	原因	解决方案
copilot: command not found	Windows 主机上未安装 Copilot CLI	在 Windows Terminal 中运行 winget install GitHub.Copilot 进行安装
powershell.exe: not found	未在 WSL2 中运行，或 WSL 互操作已禁用	检查 cat /proc/sys/fs/binfmt_misc/WSLInterop 是否存在
WorkIQ 超时／无响应	M365 身份验证已过期或从未完成	重新运行查询——这会再次触发浏览器身份验证
PowerShell 执行策略错误	执行策略限制	-NoProfile 标志可避免此问题；如果问题仍然存在，请在 PowerShell 中运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
引号转义问题	bash 和 PowerShell 之间的引号嵌套	外层 PowerShell 命令使用双引号，内层 Copilot 提示词使用单引号
输出乱码或 ANSI 代码	终端编码不匹配	将输出通过管道传递给 sed 's/\x1b\[[0-9;]*m//g'，以去除 ANSI 转义代码
GitHub auth required	Copilot CLI 未通过身份验证	运行 powershell.exe -NoProfile -Command "copilot login"
响应缓慢（30 秒以上）	正常情况——每次查询都会启动 Copilot + WorkIQ MCP	这是预期行为；由于 MCP 服务启动，首次查询最慢

限制

• 写入操作可能需要额外权限——WorkIQ 可以查询 M365 数据并起草内容。发送电子邮件、创建文档和发布 Teams 消息可能需要额外的 M365 管理员许可或 Graph API 权限。如果写入操作失败，请检查租户中 WorkIQ 集成的应用权限。
• 仅限 WSL——需要安装了 Copilot CLI 的 Windows 主机。不适用于原生 Linux 或 macOS。
• 不保留会话——每次查询都会启动一个新的 Copilot CLI 进程。不同查询之间不会保留对话记忆。
• 启动延迟——响应时间包括 Copilot CLI 启动和 WorkIQ MCP 服务初始化（每次查询约需 10-30 秒）。
• 输出解析——Copilot CLI 输出包含状态消息和格式内容，必须进行过滤才能提取实际答案。
• 身份验证范围——访问权限受 M365 账户权限限制。某些租户可能需要管理员许可。
• 不支持流式传输——只有 Windows Copilot CLI 进程完成后才会返回完整响应。

与 work-iq 技能的关系

此技能与现有的 work-iq 技能互为补充：

	work-iq	workiq-wsl
环境	任意（原生 MCP）	仅限 WSL2
连接方式	直接连接 MCP 服务	通过 powershell.exe → Windows Copilot CLI 桥接
身份验证	使用当前操作系统的浏览器	使用 Windows 主机上的浏览器
延迟	低（直接 MCP）	较高（每次查询约 10-30s）
会话	持久 MCP 连接	每次查询启动新进程

原生运行时使用 work-iq。在 WSL2 中运行且无法使用原生 MCP 方式时，使用 workiq-wsl。

---

版本： 1.0.0 | 更新日期： 2025-07-14