AI Hub VSCode 插件

一个统一的 AI 工具配置中心，集成在 VS Code 中，用于管理和配置 AI 相关工具和服务。

📦 功能特性

• WebView UI：在 VS Code 活动栏中提供现代化的配置界面
• SSO 认证：集成美团 SSO 身份认证系统
• 配置管理：支持创建和管理 aihub.config.mjs 配置文件
• 工具集成：统一管理多个 AI 工具的配置

🏗️ 项目结构

hub-vscode/
├── src/                           # TypeScript 源代码
│   ├── extension.ts               # 插件入口点，处理激活和命令注册
│   ├── commands/                  # 命令实现
│   │   ├── ICommand.ts            # 命令接口
│   │   ├── CommandFactory.ts      # 命令工厂
│   │   ├── LoginCommand.ts        # SSO 登录命令
│   │   ├── LogoutCommand.ts       # SSO 登出命令
│   │   ├── GetUserCommand.ts      # 获取用户信息命令
│   │   └── SaveConfigCommand.ts   # 保存配置命令
│   ├── providers/
│   │   └── HubViewProvider.ts     # WebView 视图提供者，处理 VSCode 和 WebView 通信
│   ├── services/
│   │   ├── ConfigService.ts       # 配置文件管理
│   │   ├── InitService.ts         # 初始化服务
│   │   └── SSOService.ts          # SSO 认证服务
│   ├── utils/
│   │   ├── TokenStorage.ts        # Token 存储管理
│   │   └── getWebviewContent.ts   # WebView HTML 生成
│   └── types/
│       └── Response.ts            # 响应类型定义
├── web/                           # React WebView 前端代码
│   ├── src/
│   │   ├── main.tsx               # React 应用入口
│   │   ├── App.tsx                # 主应用组件
│   │   ├── components/
│   │   │   ├── LoginComponent.tsx # 登录界面
│   │   │   └── ToolSelector.tsx   # 工具选择界面
│   │   ├── services/
│   │   │   └── vscode-api.ts      # VSCode WebView API 通信
│   │   └── styles/
│   ├── vite.config.ts             # Vite 构建配置
│   └── package.json
├── lib/                           # 编译后的 JavaScript 代码（自动生成）
│   ├── extension.js
│   ├── commands/
│   ├── providers/
│   ├── services/
│   └── web-dist/                  # 构建后的 WebView 资源
├── media/
│   └── icon.svg                   # 插件图标
├── package.json                   # 插件配置和依赖
└── tsconfig.json

🚀 快速开始

前置要求

• Node.js >= 20.0.0
• pnpm >= 8.0.0
• VS Code >= 1.85.0

安装依赖

# 在项目根目录
pnpm install

# 或仅在 hub-vscode 目录
cd o-ai/hub-vscode
pnpm install
pnpm install -C web

构建插件

# 生产构建（包括 WebView 和 Extension 编译）
pnpm run build

# 仅构建 WebView
pnpm run web:build

# 编译 TypeScript（Extension 部分）
pnpm run tsc -p ./

🔧 在 VS Code 中调试

调试方法 1：使用预配置的调试配置

VSCode 中已预配置了调试任务。按 F5 或选择菜单 Run > Start Debugging 即可启动调试。

调试窗口将：

1. 编译 TypeScript 源代码到 lib/ 目录
2. 启动一个新的 VS Code 实例（Extension Development Host）
3. 自动加载插件

在调试窗口中：

• 打开任何文件夹（或使用当前项目根目录）
• 插件会自动激活
• 在活动栏中查看 AI Hub 侧栏

调试方法 2：开发模式（实时编译）

此方法结合了 WebView 开发服务器和插件编译的实时重新加载：

cd o-ai/hub-vscode

# 启动开发模式（同时启动 TypeScript 监视和 WebView 开发服务器）
pnpm run dev

# 在另一个终端中启动调试器
# 按 F5 或运行调试配置

此时：

• WebView 开发服务器 运行在默认端口（通常为 5173）
• TypeScript 代码在 src/ 变更时自动编译
• Vite HMR 提供热更新支持

调试方法 3：手动编译和调试

cd o-ai/hub-vscode

# 步骤 1：编译 WebView
pnpm run web:build

# 步骤 2：编译 Extension TypeScript
pnpm run watch

# 步骤 3：在 VS Code 中按 F5 启动调试

🐛 调试技巧

在插件端设置断点

1. 打开 src/ 目录中的任何 TypeScript 文件
2. 点击代码行号左侧设置断点
3. 在 Extension Development Host 中触发相应操作
4. 执行流会暂停在断点处

查看 Extension 的调试控制台

• Extension Development Host 中打开 Help > Toggle Developer Tools (Ctrl+Shift+I / Cmd+Shift+I)
• 或点击 VS Code 调试面板中的 Debug Console 标签

打印日志

在 TypeScript 代码中使用 console.log()：

export function activate(context: vscode.ExtensionContext) {
  console.log('扩展已激活');
  // 代码...
}

日志会出现在：

• Extension Development Host 的开发者工具 Console 标签
• 主 VS Code 窗口的 Debug Console 输出面板

WebView 调试

WebView 是 React 应用，可以在 Extension Development Host 中调试：

1. 在 Extension Development Host 中打开 Help > Toggle Developer Tools
2. 查看 Elements 标签检查 DOM
3. 查看 Console 标签查看 WebView 的日志

或在 src/components/ 中的 React 代码中设置断点：

export const LoginComponent: React.FC = () => {
  console.log('LoginComponent mounted'); // 会出现在 WebView 的 Console 中
  // 组件代码...
};

调试 VSCode 和 WebView 之间的通信

在 providers/HubViewProvider.ts 中监听消息：

private async handleMessage(message: any): Promise<void> {
  console.log('收到来自 WebView 的消息:', message);  // 在 Extension 控制台查看
  // 处理消息...
}

在 web/src/services/vscode-api.ts 中：

window.addEventListener('message', event => {
  console.log('收到来自 Extension 的消息:', event.data); // 在 WebView 控制台查看
});

热重载 WebView

如果使用 pnpm run dev（开发模式），修改 WebView 代码（web/src/ 目录）时：

1. WebView 会通过 Vite HMR 自动热更新
2. 不需要重启 Extension Development Host

如果手动编辑，需要在 Extension Development Host 中：

1. 按 Ctrl+Shift+P / Cmd+Shift+P 打开命令面板
2. 运行 Developer: Reload Window

📝 常见问题和解决方案

问题 1：WebView 加载失败

症状：侧栏显示"Failed to Load AI Hub"错误

原因：WebView 资源（lib/web-dist/）未生成

解决：

pnpm run web:build
pnpm run build

然后重新启动 Extension Development Host（Ctrl+Shift+F5）

问题 2：断点不生效

原因：可能的原因：

• TypeScript 源文件未编译
• 调试器未正确连接

解决：

1. 确保运行 pnpm run watch 监视编译
2. 检查 lib/ 目录中是否存在编译后的 .js 文件
3. 重启调试（F5）

问题 3：SSO 服务初始化失败

症状：控制台输出 "Failed to initialize SSO service"

原因：SSO clientId 错误或未配置

解决：

1. 检查 extension.ts 中的 SSO_CLIENT_ID 配置
2. 确保设置了正确的环境变量 SSO_CLIENT_ID
3. 或修改代码中的默认 clientId

const SSO_CLIENT_ID = process.env.SSO_CLIENT_ID || 'your-correct-client-id';

问题 4：无法找到配置文件

症状：插件提示 "configuration not found"

原因：工作区中不存在 aihub.config.mjs 或不满足激活条件

解决：

1. 在工作区根目录创建 aihub.config.mjs：

export default {
  tools: [],
};

2. 或运行命令 Initialize AI Hub Configuration

问题 5：切换到其他功能再切回插件时重新加载

症状：点击其他 icon 切换功能，再点击 AI Hub icon 切回来，插件重新加载了之前的状态

原因：在没有启用 WebView 后台上下文保留时，WebView 会销毁并重建

解决（已在 v0.0.2+ 中自动启用）：

在 src/providers/HubViewProvider.ts 中启用 retainContextWhenHidden 选项：

webviewView.webview.options = {
  ...webviewView.webview.options,
  retainContextWhenHidden: true, // 保留后台 JavaScript 上下文
};

此选项的作用：

• ✅ 保留状态：切换视图后不会销毁 React 组件状态和 JavaScript 上下文
• ✅ 快速切换：再次打开插件时立即显示之前的内容，无需重新加载
• ✅ 保留路由：用户在插件中的页面位置会被记住

可以接受的轻微性能开销：多个后台 WebView 会占用额外内存，但对大多数使用场景可忽略。

🔍 调试工作流示例

场景：调试新命令的实现

1. 创建命令类（例如 NewCommand.ts）

2. 在 CommandFactory.ts 中注册：

case 'new-command':
  return new NewCommand(...);

3. 启动开发模式：

pnpm run dev

4. 在主 VS Code 中按 F5 启动调试

5. 在 NewCommand.ts 中设置断点

6. 从 WebView 触发命令（修改 React 组件调用对应命令）

7. 执行流暂停在断点处，检查变量状态

8. 修改 TypeScript 代码后，自动重新编译，重新加载 Extension Development Host

📦 发布插件

快速打包命令

项目已配置了完整的打包支持，使用以下命令快速打包为 VSIX：

# 在 hub-vscode 目录运行

# 打包稳定版本
pnpm run package
# 输出: ai-hub-vscode-0.0.2.vsix

# 打包预发布版本
pnpm run package:pre
# 输出: ai-hub-vscode-0.0.2-pre.1.vsix

# 发布到 VSCode Marketplace（需要认证）
pnpm run publish

# 发布预发布版本到 VSCode Marketplace
pnpm run publish:pre

打包流程详解

自动构建和打包

pnpm run package

此命令会自动执行以下步骤：

1. 构建 WebView

   • 运行 pnpm run web:build
   • Vite 生产优化构建
   • 输出到 lib/web-dist/

2. 编译 Extension TypeScript

   • 运行 tsc -p ./
   • 编译 src/ 中的所有 TypeScript 文件
   • 输出到 lib/

3. 打包为 VSIX

   • 使用 @vscode/vsce 打包
   • 包含所有必要文件和资源
   • 生成 ai-hub-vscode-0.0.2.vsix 文件

手动构建步骤

如需手动执行各步骤：

# 步骤 1: 构建 WebView
pnpm run web:build

# 步骤 2: 编译 TypeScript
pnpm run build

# 步骤 3: 打包（需先安装 vsce）
pnpm exec vsce package --no-dependencies

打包配置

项目的打包配置文件：

• package.json - 插件清单和依赖
• .vscodeignore - 排除文件和目录列表
• LICENSE - MIT 许可证（发布必需）
• resources/icon.png - 插件图标（128x128 PNG）

在 VS Code 中安装本地 VSIX

方法 1: 通过 Extensions 视图

1. 在 VS Code 中打开 Extensions 视图（Ctrl+Shift+X / Cmd+Shift+X）
2. 点击 ... 菜单 → Install from VSIX
3. 选择生成的 ai-hub-vscode-0.0.2.vsix 文件

方法 2: 命令行安装

# 在 VS Code 中运行（需要 VS Code 命令行工具）
code --install-extension ./ai-hub-vscode-0.0.2.vsix

发布到 VSCode Marketplace

前置条件

1. 在 Azure DevOps 或 VS Code Marketplace 创建发布者账户
2. 获取 Personal Access Token (PAT)
3. 本地安装 vsce：npm install -g @vscode/vsce （或通过 pnpm 使用）

设置认证

# 使用 PAT 创建发布者账户
vsce create-publisher <publisher-name>

# 或使用 Azure DevOps PAT
vsce login <publisher-name>

发布插件

# 发布稳定版本
pnpm run publish

# 发布预发布版本
pnpm run publish:pre

# 手动发布
vsce publish

构建和发布注意事项

• ✅ 所有依赖已在 package.json 中配置
• ✅ WebView 构建已优化，gzip 大小约 223KB
• ✅ 使用 --no-dependencies 跳过了 npm 依赖检查，避免 monorepo 问题
• ⚠️ 发布前确保版本号已在 package.json 中更新
• ⚠️ 发布需要有效的 VS Code Marketplace 发布者账户和 PAT

📚 相关文档

• VS Code 扩展 API
• WebView API
• React 文档
• Vite 文档

📄 许可证

Internal tool - Meituan OSG Frontend Engineering

🤝 贡献

遇到问题或有建议？请联系 OSG 前端工程团队。