Code Flow Workspace 扩展

在 Cursor / VS Code 中打开 Code Flow 工作区（文件树、TRD/DSL、Agent 流式输出等）。

安装依赖与编译

# 扩展 TypeScript 编译（在扩展目录下）
cd packages/cursor-extension
pnpm install
pnpm run compile

加载完整 Workspace 页面

在仓库根目录安装依赖（若尚未安装）
```
pnpm install
```
构建插件用 Workspace 界面（直接使用主站 src/pages/workspace/，产物输出到 webview/）
```
pnpm run build:workspace
```
开发时可用 pnpm run build:workspace:watch 监听改动并自动构建，再用命令 「Code Flow: Refresh Workspace」 刷新 Webview，无需重启扩展。
启动扩展（F5）后，打开「Code Flow: Open Workspace」或侧栏 Code Flow，将加载完整 Workspace 页面；若未构建则显示阶段一占位页。
本地 API：确保本地服务 http://localhost:7002 已启动，或在 Cursor/VS Code 设置中配置 codeflow.localApiUrl。

一份代码两用

主站网页 与 插件 Webview 共用 src/pages/workspace/，通过运行时 isFromExtension() 区分行为。
改 src/pages/workspace/ 后执行 pnpm run build:workspace（或保持 watch），插件即可看到更新。详见 workspace-src/README.md。

调试（F5）

用 Cursor 或 VS Code 打开仓库根目录（codeflow-fe）。
按 F5，选择配置 「Launch Code Flow Extension (Cursor/VS Code)」。
会新开一个「Extension Development Host」窗口，在该窗口中：
- 命令面板（Cmd/Ctrl + Shift + P）输入 Code Flow: Open Workspace 打开编辑区 Webview；
- 或点击左侧 Code Flow 图标，在侧栏打开「Workspace」视图。

打包为 vsix（可选）

# 需先全局安装 vsce: npm i -g @vscode/vsce
pnpm run package

会在当前目录生成 codeflow-workspace-0.1.0.vsix，可在 Cursor/VS Code 中「从 VSIX 安装扩展」进行安装。

Beta 分发给其他用户

当前为 Beta 版本，可通过以下方式方便其他用户安装使用。

方式一：VSIX 文件分发（推荐，无需上架商店）

打 VSIX 包（仓库根目录一键完成：先构建 Webview，再打包扩展）
```
pnpm run package:extension
```
或分步执行：
```
pnpm run build:workspace                    # 构建 Webview 界面
cd packages/cursor-extension && pnpm run package   # 生成 .vsix
```
产物：packages/cursor-extension/codeflow-workspace-0.1.0.vsix
把 .vsix 文件发给用户（内网盘、飞书/钉钉、GitHub Release、网盘等）
用户安装
- 打开 Cursor 或 VS Code
- Cmd/Ctrl + Shift + P → 输入 「从 VSIX 安装扩展」（Extensions: Install from VSIX）
- 选择下载好的 codeflow-workspace-0.1.0.vsix 即可

注意：根目录执行 pnpm run package:extension 已包含「构建 Webview + 编译扩展 + 打 VSIX」完整流程，无需再单独执行 build:workspace 或 compile。

方式二：发布到 VS Code Marketplace 预发布

若希望用户从扩展市场安装，可发布为预发布版本，只有主动选择「预发布」的用户会安装 Beta。Marketplace 要求版本号为 major.minor.patch（不支持 0.1.0-beta.1 这类标签），用 vsce publish --pre-release 标记为预发布即可。

一、首次发布前：创建 Publisher 与 PAT（只需做一次）

创建 Azure DevOps 组织（若还没有）
- 打开 Azure DevOps，用 Microsoft 账号登录。
- 若无组织，按页面指引创建组织。
创建 Personal Access Token（PAT）
- 在 Azure DevOps 门户选择你的组织。
- 右上角头像旁 User settings → Personal access tokens。
- 点击 New Token。
- Name 随意（如 vsce-publish）；Expiration 按需选择；Scopes 选 Custom defined。
- 在 Scopes 列表中找到 Marketplace，勾选 Manage（若看不到可点 “Show all scopes”）。
- 点击 Create，复制并妥善保存 Token（只显示一次）。
创建 Publisher
- 打开 Marketplace 发布者管理页，用同一 Microsoft 账号登录。
- 左侧点击 Create publisher。
- ID：唯一标识，会出现在扩展 URL 中，创建后不可改（如 codeflow）；需与 package.json 里 publisher 一致。
- Name：展示名称（如 Code Flow）。
- 填写其余信息后点击 Create。
用 vsce 登录 Publisher
```
npm install -g @vscode/vsce
vsce login codeflow
```
按提示粘贴刚才的 PAT，看到 “The Personal Access Token verification succeeded” 即表示成功。

二、每次发布预发布版本

确认版本号
- 在 packages/cursor-extension/package.json 中把 version 改为本次要发的版本（如 0.1.1）。
- 官方建议：正式版用偶数 minor（如 0.2.x），预发布用奇数 minor（如 0.1.x 或 0.3.x），便于区分。

打包并发布为预发布

# 在仓库根目录：先构建 Webview 再打 VSIX
pnpm run package:extension

# 进入扩展目录并发布为预发布
cd packages/cursor-extension
vsce publish --pre-release

若未登录会提示输入 PAT。发布成功后，该版本会在 Marketplace 上显示为预发布。

三、用户如何安装预发布版本

在 VS Code / Cursor 中打开扩展视图（侧栏或 Cmd/Ctrl + Shift + X）。
搜索你的扩展名（如 Code Flow Workspace），进入扩展详情页。
在详情页右侧或版本下拉处，找到 Switch to Pre-Release Version（或「切换到预发布版本」），点击即可安装/切换到预发布版本。
之后该扩展会优先更新到最新的预发布版本；若想回到正式版，在同一位置选择 Switch to Release Version 即可。

常见问题

403 / 401：PAT 创建时 Organizations 选 All accessible organizations，Scopes 务必包含 Marketplace → Manage。
扩展已存在：同一版本号不能重复发布，每次发布前递增 package.json 中的 version。
README/CHANGELOG 里的图片：仅支持 HTTPS；不能使用用户自定义的 SVG（安全限制）。

版本号建议（Beta 阶段）

预发布用普通数字版本即可（如 0.1.0、0.1.1），用 vsce publish --pre-release 区分预发布与正式版。
建议正式版用偶数 minor（如 0.2.x），预发布用奇数 minor（如 0.1.x、0.3.x），避免预发布用户被误升级到正式版。
每次发新包前递增版本号，便于用户覆盖安装与排查问题。

Code Flow Workspace

shopee-codeflow