# IC Coder 插件发布流程文档

本文档详细说明如何将 IC Coder 插件发布到 VS Code 插件市场进行测试和正式发布。

## 目录

- [前置准备](#前置准备)
- [账号配置](#账号配置)
- [插件信息完善](#插件信息完善)
- [打包与发布](#打包与发布)
- [版本更新](#版本更新)
- [常见问题](#常见问题)

---

## 前置准备

### 环境要求

- Node.js 和 pnpm 已安装
- VS Code 1.80.0 或更高版本
- 已安装 `@vscode/vsce` 工具（项目已包含）

### 检查清单

在发布前，请确保以下文件和配置已准备就绪：

- [x] `package.json` - 插件配置文件
- [x] `README.md` - 插件说明文档
- [x] `dist/` - 编译后的代码
- [x] `media/` - 图标和资源文件
- [ ] `CHANGELOG.md` - 版本更新日志（建议添加）
- [x] `LICENSE` - 开源许可证（建议添加）

---

## 账号配置

### 1. 创建 Azure DevOps 账号

1. 访问 [Azure DevOps](https://dev.azure.com)
2. 使用 Microsoft 账号注册或登录
3. 创建一个组织（如果还没有）

### 2. 生成 Personal Access Token (PAT)

这是发布插件的关键凭证，请妥善保管。

**步骤：**

1. 登录 Azure DevOps
2. 点击右上角用户图标 → **User settings** → **Personal access tokens**
3. 点击 **New Token** 按钮
4. 配置 Token 信息：
   - **Name**: `vscode-publisher`（或其他易识别的名称）
   - **Organization**: 选择 **All accessible organizations**
   - **Expiration**: 建议选择较长期限（如 90 天或自定义）
   - **Scopes**: 选择 **Custom defined**
     - 展开 **Marketplace**
     - 勾选 **Manage**（包含发布和管理权限）
5. 点击 **Create** 生成 Token
6. **重要**: 立即复制并保存 Token，页面关闭后将无法再次查看

**Token 示例格式：**

```
CO03l8nmFBBTNPDg7lN9a9fYwDdgsRIDVDwTrx6Esggi6HnzmrMTJQQJ99BLACAAAAAAAAAAAAAGAZDOVVyT
```

### 3. 创建发布者账号

发布者账号是你在 VS Code 市场的身份标识。

**步骤：**

1. 访问 [VS Code Marketplace 管理页面](https://marketplace.visualstudio.com/manage)
2. 使用 Azure DevOps 账号登录
3. 点击 **Create publisher** 按钮
4. 填写发布者信息：
   - **ID**: `ICCoder`（必须与 package.json 中的 `publisher` 字段一致）
   - **Name**: `IC Coder`（显示名称，可自定义）
   - **Email**: 你的联系邮箱
5. 点击 **Create** 完成创建

**注意事项：**
- Publisher ID 一旦创建无法修改
- Publisher ID 必须全局唯一
- 建议使用有意义且专业的 ID

---

## 插件信息完善

### 1. 完善 package.json

建议在 `package.json` 中添加以下字段以提升插件质量：

```json
{
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/ic-coder.git"
  },
  "homepage": "https://github.com/your-org/ic-coder#readme",
  "bugs": {
    "url": "https://github.com/your-org/ic-coder/issues"
  },
  "license": "MIT"
}
```

### 2. 创建 CHANGELOG.md

版本更新日志帮助用户了解每个版本的变化。

**示例内容：**

```markdown
# 更新日志

## [0.0.2] - 2025-12-29

### 新增
- 添加发送和暂停按钮功能
- 添加一键优化按钮组件
- 添加 Plan 开关组件
- 添加模式选择器组件
- 添加上下文压缩功能

### 改进
- 优化用户界面交互体验

## [0.0.1] - 2025-12-XX

### 新增
- 初始版本发布
- Verilog 代码智能生成
- 集成 iverilog 仿真工具
- VCD 波形文件查看器
```

### 3. 创建 LICENSE 文件

如果使用 MIT 许可证，创建 `LICENSE` 文件：

```
MIT License

Copyright (c) 2025 IC Coder Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
```

### 4. 优化 README.md

确保 README 包含：
- 清晰的功能介绍
- 使用截图或 GIF 演示
- 详细的使用说明
- 系统要求
- 常见问题解答

---

## 打包与发布

### 方式一：命令行发布（推荐）

这是最便捷的发布方式，适合频繁更新。

**步骤：**

1. **登录发布者账号**

```bash
pnpm vsce login ic-coder-team
```

系统会提示输入 Personal Access Token，粘贴之前创建的 PAT。

2. **打包插件**

```bash
# 执行生产环境构建
pnpm run package

# 打包成 .vsix 文件
pnpm vsce package
```

这会生成 `ic-coder-plugin-0.0.2.vsix` 文件。

3. **发布到市场**

```bash
pnpm vsce publish
```

发布成功后会显示插件的市场链接。

**一键发布（跳过打包步骤）：**

```bash
# 直接发布当前版本
pnpm vsce publish
```

### 方式二：手动上传

适合首次发布或网络环境受限的情况。

**步骤：**

1. 本地打包插件：
```bash
pnpm run package
pnpm vsce package
```

2. 访问 [发布者管理页面](https://marketplace.visualstudio.com/manage/publishers/ic-coder-team)

3. 点击 **New extension** → **Visual Studio Code**

4. 上传 `ic-coder-plugin-0.0.2.vsix` 文件

5. 填写插件信息（如果需要）并提交

6. 等待审核通过

---

## 版本更新

### 自动更新版本号

使用 `vsce publish` 命令可以自动更新版本号并发布：

```bash
# 补丁版本更新（0.0.2 → 0.0.3）
pnpm vsce publish patch

# 次版本更新（0.0.2 → 0.1.0）
pnpm vsce publish minor

# 主版本更新（0.0.2 → 1.0.0）
pnpm vsce publish major
```

### 手动指定版本

```bash
# 发布指定版本
pnpm vsce publish 0.0.3
```

### 更新流程建议

1. 修改代码并测试
2. 更新 `CHANGELOG.md` 记录变更
3. 提交代码到 Git
4. 执行发布命令
5. 验证市场上的插件是否正常

---

## 常见问题

### 1. 发布失败：Authentication failed

**原因：** PAT Token 无效或过期

**解决方案：**
- 重新生成 PAT Token
- 重新登录：`pnpm vsce login ic-coder-team`

### 2. 发布失败：Publisher not found

**原因：** Publisher ID 不存在或不匹配

**解决方案：**
- 检查 `package.json` 中的 `publisher` 字段
- 确认已在市场创建对应的 Publisher

### 3. 打包失败：Missing files

**原因：** 必需文件缺失

**解决方案：**
- 确保 `dist/` 目录存在且包含编译后的代码
- 运行 `pnpm run package` 重新构建

### 4. 插件审核被拒

**常见原因：**
- 插件名称或描述违反市场规则
- 图标不符合要求（建议 128x128 PNG）
- README 内容不完整

**解决方案：**
- 查看审核反馈邮件
- 修改相关内容后重新发布

### 5. 如何撤回已发布的版本？

```bash
# 取消发布指定版本
pnpm vsce unpublish ic-coder-team.ic-coder-plugin@0.0.2

# 取消发布整个插件（慎用）
pnpm vsce unpublish ic-coder-team.ic-coder-plugin
```

### 6. 如何本地测试 .vsix 文件？

```bash
# 在 VS Code 中安装本地 .vsix 文件
code --install-extension ic-coder-plugin-0.0.2.vsix
```

或者在 VS Code 中：
1. 打开扩展面板
2. 点击 `...` 菜单
3. 选择 **Install from VSIX...**
4. 选择 `.vsix` 文件

---

## 发布检查清单

在正式发布前，请确认以下事项：

- [ ] 代码已充分测试，无明显 Bug
- [ ] `package.json` 版本号已更新
- [ ] `CHANGELOG.md` 已记录本次更新内容
- [ ] README.md 内容完整且准确
- [ ] 图标和资源文件正常显示
- [ ] 已在本地安装测试 .vsix 文件
- [ ] 已创建 Azure DevOps PAT Token
- [ ] 已创建 VS Code Marketplace Publisher
- [ ] 已执行 `pnpm run package` 构建生产版本

---

## 参考资源

- [VS Code 插件发布官方文档](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
- [vsce 工具文档](https://github.com/microsoft/vscode-vsce)
- [Azure DevOps 文档](https://docs.microsoft.com/en-us/azure/devops/)
- [VS Code 插件市场](https://marketplace.visualstudio.com/)

---

**文档维护：** IC Coder Team
**最后更新：** 2025-12-29