EFE前端脚手架工具
将 efe、jenkins 和 efe-release 接入 VS Code：从侧边栏或命令面板启动常用操作，在任务终端继续交互并查看日志。
安装和首次使用
- 准备 VS Code 1.91 或更高版本，以及 Node.js 18.17 或更高版本。
- 在 VS Code 扩展面板的
… 菜单中选择 从 VSIX 安装，选择与你的系统匹配的 VSIX（文件名含平台，如 efe-activity-vscode-darwin-arm64-<版本>.vsix）。
- 打开活动项目，信任工作区后，点击左侧 EFE 图标，运行 检查 CLI 环境，确认输出里的来源显示 （插件内置），再按需运行 初始化账号配置。
不需要安装 CLI，也不需要配置 npm 源或凭据。 efe-activity-cli 及其全部依赖已随 VSIX 一起分发，扩展会直接使用它。只有在你想改用自己构建或全局安装的版本时，才需要设置 efe.cliPackagePath 或安装全局包 —— 此时内置副本会让位：查找顺序是 efe.cliPackagePath → 项目 node_modules → PATH → 扩展内置副本 → 扩展自管副本 → npm root -g。
因为内置 CLI 含按平台编译的原生二进制（sharp、cjpeg、pngquant），VSIX 分平台发布：装错平台的包时图片相关命令会失败，重装对应平台的包即可。
插件会在每次启动 CLI 任务时读取已有的 ~/.efe/account.json，并将其中非空账号字段作为该次任务的优先运行时凭据，因此 Git 克隆或全局 npm 安装的既有用户不需要重新配置。文件内容不会写入工作区、输出面板或扩展设置，也不会复制到钥匙串。点击 初始化账号配置 后填写的新账号凭据和 FTP 连接仍保存到 VS Code SecretStorage，由 macOS 钥匙串、Windows Credential Manager 或 Linux 的密钥服务保护。账号配置状态只显示来源和是否填写，不展示 Token、密码或验证服务连接。
每次执行 CLI 时，插件仅向该任务的子进程传入运行时环境变量，凭据不会出现在命令行参数、工作区设置、项目文件、任务定义、输出面板或终端日志中。直接在终端运行 CLI 仍兼容旧版 ~/.efe/account.json；CLI 下次写入时会将目录和文件分别设为 0700、0600。
侧边栏 设置 视图标题栏的 ⬇ 图标是 安装或更新 EFE CLI（备用）：它从 efe.cliRegistry（默认 https://npm.efun.com，需要本机已登录该私库）装一份副本到扩展目录，仅在安装包损坏或平台不匹配时用来恢复。日常命令不会走这条路径。旧版 CLI 将图片压缩的 --source / --destination 声明为布尔开关，无法接受目录参数；内置副本已包含修复版本。
功能
| 入口 |
行为 |
| AI 生成合并提交信息 |
在源代码管理面板点击 ✨；已有暂存改动时只分析暂存内容，否则自动暂存全部改动；按主题生成多组说明并合并为一条信息填入输入框。点击 Commit 后只创建一个 Git 提交 |
| 检查 CLI 环境 |
检查 Node、CLI 安装目录、三个命令入口和版本 |
| 初始化账号配置 |
将账号或 FTP 凭据保存到操作系统钥匙串，不创建账号 JSON 文件 |
| 查看账号配置状态 |
只显示钥匙串中各项是否填写，不输出凭据内容 |
| 创建活动项目 |
选择 Vue / jQuery 模板和父目录，在终端填写项目名称及其他参数 |
| 添加 / 查看 / 删除项目模板 |
在终端维护 EFE 本地模板列表；删除前会在终端再次选择具体模板 |
| 复制目录 |
选择源目录与目标目录，确认后复制；同名文件可能被覆盖 |
| 交互式项目命令 |
运行 CLI 的 efe start，在终端选择开发、构建、部署等项目脚本 |
| 压缩图片目录 |
JPG / PNG 压缩到源目录旁的 <目录名>-optimized，保留源文件 |
| 目录图片转 WebP / AVIF |
在源目录及其子目录生成对应格式文件；已有同名输出按 CLI 行为处理 |
| 目录 PNG 转 JPG |
输出到源目录旁的 <目录名>-jpg；默认跳过带透明像素的图片 |
| 上传目录到 CDN |
选择目录和目标路径，留空目标则使用项目配置，确认后执行 |
| 上传目录到 FTP |
填写配置名、选择区域和上传模式，确认后执行 |
| 并行上传目录到 FTP |
填写多个 FTP 配置名后并行上传同一目录 |
| Jenkins 构建与日志 |
保存常用 Pipeline / Job 并快速触发，也可搜索任务、选择预设任务或查看日志 |
| 生成并上传官网模板 |
按项目官网模板配置生成 FTL 并上传到 GitLab 模板仓库 |
| 批量升级项目依赖 |
选择多个子项目的父目录，在终端选择升级项；可能执行 Git 与安装操作 |
| 创建并自动合并 GitLab MR |
拉取目标分支、创建 MR 并在可合并时自动合并，执行前需确认 |
| 发布 npm 包版本 |
选择版本类型、确认项目，再进入现有发布流程 |
| 发布 VS Code 扩展 |
选择版本类型，走 efe-release vsix 升版并打包 .vsix（不改动 Git），完成后提示到 Marketplace 网页手动上传 |
| 检查 util 版本 |
对所选项目执行 efe check-util，可能安装或更新依赖 |
命令行 efe commit 仍会按分组创建多个独立提交；插件只生成一条合并信息。
首次使用 AI 生成 Git 提交信息时，插件会弹出密码掩码输入框要求填写个人 API Key。按回车后，Key 保存在本机统一配置 ~/.efe/account.json 的 aiCommit.apiKey 字段（文件权限 0600，新建目录权限 0700）；后续直接读取。也可以在侧边栏 设置 → AI 大模型配置 → LLM API Key 中配置或更换，设置视图只显示配置状态，不显示 Key。服务地址为 https://one-api-litellm.efun.com。Git 差异会发送到团队服务；不会在日志、工作区设置或版本库中保存 Key。
模型、兜底模型与超时同在 设置 → AI 大模型配置 中修改，分别写入 ~/.efe/account.json 的 aiCommit.model、aiCommit.fallbackModel、aiCommit.timeoutMs，也可直接手改该文件（与 jenkinsHost、gitlabBranch 等非敏感字段一致）。默认主模型 deepseek-flash、兜底模型 gemini-3.5-flash-lite、单次请求超时 30000 毫秒（可填 5000～600000）。主模型超时、网络中断、返回 5xx/429 或返回 200 但内容为空时，会自动改用兜底模型重试一次，并在进度提示里说明；认证与权限类错误不会重试。恢复默认 会把该键从 account.json 里删掉，而不是写入默认值。
资源管理器中右键单个目录 → EFE 工具，可以直接进行图片处理或资源上传。命令面板搜索 EFE 可访问所有功能。
「发布 VS Code 扩展」通过 efe-release vsix 升版并打包，需要包含该子命令的 CLI：源码方式请先在仓库根执行 pnpm build（并把 efe.cliPackagePath 指向该仓库）；全局安装方式请在团队发布新版本后更新。该命令会把工作目录当作 efe-activity-cli 仓库根来发布其中的 extensions/vscode，请在仓库根目录执行。它不改动 Git：extensions/vscode/package.json、package-lock.json 的新版本号和 CHANGELOG.md 新条目留在工作区，由你自行 git add + git commit。完成后终端会显示 VSIX 路径，并提示使用 efunitweb@gmail.com 登录 发布者管理页，在插件名旁点击更多图标（…）→ Update，从 extensions/vscode 目录上传对应版本的 VSIX；不需要 Azure DevOps PAT。
侧边栏标题右侧的放大镜可搜索全部工具，选择后直接进入对应操作；筛选图标可勾选需要显示的工具。隐藏的工具仍可通过搜索工具和命令面板调用，随时可重新勾选显示。
在 Jenkins 构建与日志 → 管理常用 Job 中，首次配置会直接进入两步输入：先填写只供扩展列表显示的快捷名称，例如“活动预发布”；再填写 Jenkins 的实际 Pipeline / Job 完整名称。若 Jenkins URL 是 …/job/frontend/job/activity-pre-release/，应填写 frontend/activity-pre-release。已有常用项时，先在列表选择“新增常用 Jenkins Job”或某个已有 Job；列表顶端输入框只用于筛选，不用于填写配置。随后在 快速触发常用 Job 中选择即可运行 jenkins run <Job 名称>。这些常用项仅保存在当前 VS Code 用户的扩展本地状态中，不包含 Jenkins 用户名或 Token。Jenkins 入口需要 efe-activity-cli 1.0.17 或更高版本；源码方式运行请重新执行 pnpm build，全局安装方式请在团队发布 1.0.17 后重新安装该版本。
工作目录和执行方式
- 单项目使用项目根目录；多项目工作区先选择项目，右键操作优先使用目录所属项目。
- 上传目录必须位于所选项目内。插件传递相对路径，兼容 CLI 的目录拼接规则，并保留项目配置读取位置。
- 图片源目录传递绝对路径。受 CLI 的逗号分隔规则限制，暂不支持包含逗号的图片路径。
- 每个任务用独立 Node.js 进程运行，通过 VS Code
ProcessExecution 传递参数，不拼接 shell 命令。终端交互、颜色和执行日志由 CLI 提供。
- 同一项目同时只启动一个 EFE 任务。在命令面板运行 任务: 终止任务 可以停止任务；发布、上传已产生的外部变更不会回滚。
- 任务详细日志在终端，启动记录、退出码和环境检查在 输出 → EFE。退出码由 CLI 决定；仍应留意 CLI 输出中的单文件处理错误。
- FTP 连接信息只从安全配置的系统钥匙串中读取。FTP 目标路径可以继续保存在项目
efe-config.cjs；如需完全脱离项目配置，可由管理员设置 EFE_FTP_TARGETS JSON 映射。CLI 不再接受源码中的默认 FTP 凭据，也不会输出 FTP 协议认证详情。
- 从 Git 仓库或全局 npm 包直接运行 CLI 时，既有
~/.efe/account.json 账号配置仍然兼容，并会被扩展优先用于每次 CLI 任务；FTP 可通过 efe config:ftp 保存到仅当前用户可读的 ~/.efe/ftp.json。扩展不会读取命令行的 FTP 凭据文件。
- 首版面向桌面 VS Code 的文件系统工作区，不支持 vscode.dev 或虚拟工作区。Remote SSH / WSL / Dev Containers 尚未验证。
安全发布清单
发布到 Marketplace 前，必须先轮换曾经出现在历史版本中的 FTP 密码。移除源码不会使旧提交、旧 npm 包或旧 VSIX 中的密码失效。
- 在 FTP 服务端撤销旧账号或改密，并检查该账号的访问日志。
- 将新版 CLI 与扩展发布给团队，要求成员通过 初始化账号配置 → 配置 FTP 连接 重新保存凭据。
- 评估是否需要清理 Git 历史和已发布的旧 npm 版本；这会影响其他开发者的 clone 与分支，需要由仓库管理员协调执行。
- 使用
.gitleaks.toml 在发布 CI 中扫描待发布的提交和 VSIX。不要把真实 Token、密码、私钥或内部连接 JSON 写入测试、文档或示例。
- FTP 服务支持时，选择 FTPS；普通 FTP 会明文传输认证信息，只应作为兼容旧服务器的临时方案。
设置
侧边栏的 设置 视图回显以下全部配置，点击任意一项即可就地修改并保存；也可从命令面板打开 VS Code 设置页。
| 配置 |
默认值 |
说明 |
efe.cliPackagePath |
空 |
CLI npm 包或已构建源码仓库的绝对路径；明确设置但无效时直接报错；留空则用随 VSIX 分发的内置副本 |
efe.nodePath |
node |
Node 可执行文件名或绝对路径，不包含参数 |
efe.cliRegistry |
https://npm.efun.com |
仅「安装或更新 EFE CLI（备用）」使用的 npm 源；普通命令不访问 |
CLI 自动查找顺序：项目及父目录的 node_modules/efe-activity-cli → PATH 中的 npm/pnpm 链接或 npm 安装目录 → 扩展自动安装的副本 → npm root -g。若 VS Code 没有继承终端中的 nvm / Volta / pnpm 环境，请显式设置上述路径。
找不到 CLI 时扩展会弹窗询问是否自动安装，装到扩展目录后继续执行当前命令，因此只安装扩展也能直接使用。设置 视图标题栏的 ⬇ 图标可随时安装或更新。
设置 视图同时回显并管理账号凭据（一般存入系统钥匙串；均只显示来源不回显明文）、AI 大模型配置（LLM API Key 为兼容 CLI 存入 ~/.efe/account.json；模型、兜底模型与超时写入同一文件的 aiCommit 字段）与 CLI 配置（写入 ~/.efe/account.json 的非敏感字段，保留文件中已有的凭据）。扩展只在该命令确实会用到某项凭据时才弹出输入框（密码掩码，按子操作分别判断），保存后继续执行；命令自身报出凭据缺失或认证失败时，错误提示会多给一个 打开设置面板 按钮。
创建并自动合并 GitLab MR 的源分支默认选中当前分支，目标分支可选任意分支或「使用 CLI 默认分支」。
开发和打包
新增或修改用户配置时，请按源码仓库根目录的 docs/configuration-checklist.md 同步检查 CLI、插件设置视图、存储、测试和文档。
CLI 仓库根目录：
pnpm build
npm run vscode:install
npm run vscode:test
npm run vscode:package
插件依赖和锁文件独立于 CLI。vscode:install 使用插件目录的 package-lock.json；构建和打包无需改动 CLI 的依赖。
vscode:package 会先把 CLI 及其生产依赖树生成到 extensions/vscode/vendor/efe-cli（约 50MB，不入库），再按平台打包。因此：
- 默认只打当前平台的包；一次打齐用
npm run vsix:package:all，或 npm run vscode:package -- --target win32-x64。
- 打包前会自动重建根 CLI（
npm run build:cli），避免把旧的 dist 打进 VSIX；已有 vendor 树且版本一致时会复用。
- 打包前会跑一遍安全校验，命中凭据、
.npmrc、account.json、测试目录或体积超预算都会中止。细节见 CLI 仓库根目录的 docs/vsix-vendor.md（该文件不随插件分发，只能在这里指路）。
产物文件名由 package.json 的版本和平台决定，例如 extensions/vscode/efe-activity-vscode-darwin-arm64-0.1.2.vsix。本地安装也可使用：
code --install-extension extensions/vscode/efe-activity-vscode-darwin-arm64-0.1.2.vsix
开发调试时，在 VS Code 中单独打开 extensions/vscode，按 F5 启动扩展开发宿主；在新窗口打开一个活动项目。默认会用随扩展分发的内置副本（开发宿主里指向源码目录下的 vendor/efe-cli），要改用本仓库构建的 CLI 就设置 efe.cliPackagePath。
tests/smoke.cjs 里还导出 runBundled，在真实开发宿主里验证内置副本能被解析、能加载 sharp 原生模块并真的完成一次 WebP 转换 —— 这是单元测试覆盖不到的一层。
publisher: efunitweb 是扩展标识的一部分；改动它会让 VS Code 视为另一个扩展，与已安装版本并存并抢同一组 efe.* 命令。
验证
npm test 在插件目录运行类型检查及 Node.js 自动化测试，覆盖安装探测、路径传递、工作区选择、取消、发布确认、任务生命周期和凭据隐藏。
tests/smoke.cjs 可在真实 VS Code 中验证扩展激活和任务进程。它只在临时工作区生成模拟 CLI，不调用真实上传、发布或账号配置：
# 在插件目录运行；code 命令需已加入 PATH
EFE_SMOKE_DIR=$(mktemp -d)
mkdir -p "$EFE_SMOKE_DIR/workspace"
EFE_TEST_NODE=$(node -p 'process.execPath') code \
--user-data-dir="$EFE_SMOKE_DIR/user-data" \
--extensions-dir="$EFE_SMOKE_DIR/extensions" \
--disable-extensions --disable-workspace-trust \
--skip-welcome --skip-release-notes \
--extensionDevelopmentPath="$PWD" \
--extensionTestsPath="$PWD/tests/smoke.cjs" \
"$EFE_SMOKE_DIR/workspace"
VS Code 接入使用官方 Extension API，打包使用 vsce。
