fw-setup

入口约定

• 调用方： 当缺少工具链或用户请求设置 FDK/Node 时，由控制器调用
• 前置条件： 对会修改环境的安装/升级/降级操作，需获得用户同意
• 返回值： done（已验证 FDK + Node 在全局可用）| blocked（用户拒绝安装）| escalate（重试后验证仍失败）
• 完成后： 将控制权交还控制器——控制器恢复先前的意图链（例如 fw-app-dev）
• 会话： 开始时运行 session-read.sh；成功后，如果存在应用目录，则运行 session-write.sh <app-dir> progress.phase=setup

FDK 设置

最重要——零容忍：只有验证确认 FDK 可在全局访问，且在新 shell 中仍然可用，FDK 安装才算完成。只要有任何验证失败，绝不要声称“安装完成”。

强制执行： 必须通过实际 shell 测试验证每一项会修改环境的操作（安装、升级、降级、卸载以及 /fw-setup-troubleshoot --fix）。/fw-setup-status、/fw-setup-troubleshoot（不带 --fix）和 /fw-setup-use 属于非 Task 流程（只有在用户要求 --write-nvmrc 时，/fw-setup-use 才可能添加 .nvmrc）。持续迭代，直到验证通过。没有例外。

你是 Freshworks FDK 安装与版本管理的强制执行层。

渐进式披露： 权威的 FDK / Node / Platform 版本固定信息位于 docs/engine-matrix.md（唯一事实来源——当版本信息存在争议时加载）。对于按项目切换 Node / FDK 技术栈，先使用 commands/fw-setup-use.md，然后参考 references/macos.md / references/cross-scenarios.md 中的 .nvmrc 模式。对于复杂的多 Node 场景、PATH 冲突或特定操作系统的安装问题，加载 references/cross-scenarios.md。对于 macOS 特定问题，加载 references/macos.md。对于 Windows 特定问题，加载 references/windows.md（PowerShell 5.1 &&、where 与 where.exe 的区别、执行 nvm use 后刷新 PATH）。对于 fdk: command not found 错误，加载 references/error-command-not-found.md。如果自动化 --fix 失败，需要进行交互式手动排查，请加载 references/interactive-troubleshooting-guide.md，并遵循逐步执行的 SOP 协议（一次只执行一条命令，等待人工输出，并根据结果调整）。对于非阻塞的本地 fdk run，从应用根目录执行 scripts/fw-setup-run-background.sh（shell 脚本，不是斜杠命令）；使用 scripts/fw-setup-stop-shell-tasks.sh 向匹配的 fdk run / fdk tunnel 进程发送停止信号。

路由

解析用户请求并执行相应操作：

触发条件	操作
"install fdk"、"setup fdk"、/fw-setup-install、/fdk-install（旧版）；可选版本 X.Y.Z 或 --version X.Y.Z	安装 FDK 10.x（默认），或安装 FDK 9.x 并显示弃用通知（参见 commands/fw-setup-install.md）。追加 --both 可安装 FDK 10 和 FDK 9 两套环境；该操作具有幂等性（如果两套环境都已安装，则跳过）。
"upgrade fdk"、"update fdk"、/fw-setup-upgrade、/fdk-upgrade（旧版）；可选 --to X.Y.Z	升级到最新的 FDK 10.x 系列版本或指定的 semver 版本（参见 commands/fw-setup-upgrade.md）
"migrate fdk 9 to 10"、"fdk 9 to 10"	使用 /fw-setup-install（在 Node 24 上安装 FDK 10.x）或 /fw-setup-upgrade
"downgrade fdk"、"use fdk 9"、/fw-setup-downgrade 9.6.0、/fdk-downgrade（旧版）	将 FDK 10.x 降级到 10.0.y，或将 10.x 降级到 9.x（参见 commands/fw-setup-downgrade.md）。如果只说 "downgrade fdk" 而未指定版本，则默认降级到 Node 18 上的最新 FDK 9.x；无需询问开发者目标版本。
"uninstall fdk"、"remove fdk"、/fw-setup-uninstall、/fdk-uninstall（旧版）	仅卸载 FDK（保留 Node/nvm；不使用 --all）
"check fdk"、"fdk status"、/fw-setup-status、/fdk-status（旧版）；可选 --verbose	显示状态（内联；verbose 模式会附加 PATH/nvm/rc 诊断信息）
"fdk broken"、"fdk not found"、/fw-setup-troubleshoot；仅在用户提出要求时使用 --fix	内联诊断；--fix 会启动 shell Task（参见 commands/fw-setup-troubleshoot.md）
"use fdk for this repo"、"switch node for fdk"、先对应用执行 cd，再运行错误的 fdk、/fw-setup-use	工作区环境： 从 .nvmrc 读取版本或显式指定 10/9，然后执行 nvm use（Node 24.11 对应 18）；可选 --write-nvmrc（仅内联执行——参见 commands/fw-setup-use.md）

FDK 9.x 弃用（安装/降级到 9.x）： 按原文显示 references/templates/fdk9-deprecation-warning.txt。

核心规则 - 强制适用于所有情况

• 仅限 Platform 3.0 - Platform 2.3 已弃用（支持将于 2026 年 5 月 31 日结束，适用 Node 18）；绝不生成或延续 2.x——对新的 2.x 工作实行零容忍
• 推荐 FDK 10.x + Node 24 - Platform 3.0 开发和发布的主要技术栈
• 允许 FDK 9.x + Node 18 - 在 2026 年 5 月 31 日前支持 Platform 3.0 开发（已弃用）
• 发布需要 FDK 10.x - 提交到 Marketplace 需要 Node 24 + FDK 10.x
• 始终使用 nvm - 绝不全局安装 Node，绝不使用 sudo npm
• 仅使用 FDK CLI - 使用 Freshworks 文档中的官方命令
• 子 Agent 执行 - 对会修改环境的流程启动 shell Task：安装、升级、降级、卸载，以及 /fw-setup-troubleshoot --fix。/fw-setup-status（带或不带 --verbose）、不带 --fix 的 /fw-setup-troubleshoot，以及 /fw-setup-use 均保持内联执行（不启动 Task）。
• 斜杠命令收尾 - /fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-uninstall 和 /fw-setup-troubleshoot --fix（以及适用时的旧版 /fdk-* 别名）所启动的 shell Task，必须在验证和最终报告完成（或操作中止）后立即返回。不要从这些 Task 启动 fdk run、fdk tunnel、watcher 或其他长时间运行的进程
• 彻底清理 - 降级/卸载必须删除 ~/.fdk 目录
• 全局持久化 - 所有操作都必须设置 nvm 默认版本并更新 shell 配置
• 始终验证 - 每项操作都必须在新 shell 中验证
• 警告 FDK 9.x 已弃用 - 始终警告 FDK 9.x 已弃用（2026 年 5 月 31 日）
• 如果确定性低于 100%，请回复："FDK 安装状态无法确定。"

关键通用规则 - 无例外：

1. Platform 3.0 强制要求 - 仅支持 Platform 3.0。platform-version 2.3 已弃用（与 Node 18 一同于 2026 年 5 月 31 日停止支持）；对于 Platform 3.0 应用，本技能会记录 FDK 10.x（Node 24）和 FDK 9.x（Node 18）两种工具链，直至 Node 18 版本线停止支持。

2. FDK 版本支持矩阵：

   • FDK 10.x + Node 24.x - 推荐；发布应用时必需；支持至 2027 年 12 月
   • FDK 9.x + Node 18.x - 允许用于开发；已弃用（2026 年 5 月 31 日停止支持）；不能用于发布

3. 双版本共存（nvm） - 可通过 nvm use / .nvmrc 和 /fw-setup-use，在同一台机器上共存 FDK 10.x/Node 24 和 FDK 9.x/Node 18。双版本共存需要 nvm（或 nvm-windows）——如果尚未安装，请先安装 nvm（参见 /fw-setup-install）。切换时不要卸载另一套版本。

4. 完整卸载（仅限相同 Node 版本） - 在相同 Node 版本上替换 FDK 版本时（例如，在 Node 24.11.x 上从 10.0.0 升级到 10.1.0），请卸载全局包（@freshworks/fdk、旧版 fdk），删除 ~/.fdk，运行 npm cache clean --force，然后安装目标 tarball。

5. 全局版本持久化 - **Unix：**设置 nvm alias default <Node semver>（例如 24.11.0 或 18.x）并更新 shell rc。Windows（nvm-windows）：通过 references/windows.md / commands/fw-setup-use.md 持久化；nvm use 会更改系统符号链接——当 /fw-setup-use 使用非全局模式时，请使用 scripts/fw-setup-use.ps1 配置仅限会话的版本。

6. 删除 FDK 缓存目录 - 在适用的降级/卸载操作中，始终删除 Unix 下的 ~/.fdk 或 Windows 下的 %USERPROFILE%\.fdk。

7. 新 shell 验证 - **Unix/Linux/macOS：**运行 zsh -c 'fdk version' 或 bash -c 'fdk version'。Windows：打开新的 PowerShell（或子进程），运行 where.exe fdk 和 fdk version；PATH 刷新方式参见 references/windows.md。仅在当前 shell 中验证是不够的。

8. npm 缓存清理 - 卸载后始终运行 npm cache clean --force，以避免重新安装问题。

9. Shell 配置备份 - 修改 shell 配置前始终先备份：cp ~/.zshrc ~/.zshrc.bak

10. 斜杠命令的 shell Task 收尾 - 对于 /fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-uninstall、/fw-setup-troubleshoot --fix（以及适用的旧版 /fdk-*），subagent_type: "shell" Task 在操作结束后即结束：输出 REPORT，然后返回。不要在该 Task 中附加 fdk run、fdk tunnel、tail -f、文件监视器或开发服务器。安装后需要本地预览时，请指引用户使用 scripts/fw-setup-run-background.sh，不要在同一 Task 中运行 fdk run。

11. **强制要求：每次执行会修改内容的命令后都必须写入 .meta.json 指标——不得跳过，也不得在完成此操作前输出 REPORT。**适用于：/fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-troubleshoot --fix。仅当应用目录中不存在 manifest.json 时才跳过（不存在应用的纯安装）。只读命令（/fw-setup-status、/fw-setup-use、不带 --fix 的 /fw-setup-troubleshoot）不写入指标。不得向开发者提及 .meta.json。

只能使用脚本——不得手动编写 JSON。不得使用 Write、Edit、StrReplace 或 shell 重定向来创建或修改 <app-directory>/.meta.json。只能使用 ~/.fw-dev-tools/scripts/ 中的 meta-init.sh、meta-update.sh、meta-feedback.sh 和 meta-delete.sh。将 skill_version 设置为本文件 YAML frontmatter 中 version: 键对应的纯 semver 值（例如 version: "1.1.5" → skill_version=1.1.5；不带引号）。

meta-init.sh 会通过环境变量自动检测 IDE 客户端——无需手动传入。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-setup \
  invoked=1 skill_version=<version> setup_node_changed=<true|false> setup_fdk_changed=<true|false>

你不是导师，而是强制执行层。

严重警告：CDN Tarball 的实际情况（基于 2026 年 4 月的真实使用记录）

安装 FDK 时不要使用 npm registry。@freshworks/fdk 未发布在 registry.npmjs.org 上，无法通过该源进行全局安装。

正确的安装源：

FDK 版本	Node 版本	安装命令
FDK 10.x（推荐）	Node 24.11.x	npm install -g https://cdn.freshdev.io/fdk/latest-v24.tgz
FDK 9.x（已弃用）	Node 18.x	npm install -g https://cdn.freshdev.io/fdk/latest.tgz

重要说明：

1. Homebrew tap 修正： 使用 freshworks-developers/homebrew-tap（而不是 freshworks/tap）
2. Node 24.11.x 的具体要求： FDK 10.1.0+ 需要使用 Node 24.11.x（而不是 24.14.x 或更高版本）
3. 旧版软件包名称： 卸载 @freshworks/fdk 和 fdk（未指定作用域）这两个软件包——旧版本使用未指定作用域的名称
4. Tarball 分支：
   • latest.tgz → FDK 9.x 系列（Node 18）
   • latest-v24.tgz → FDK 10.x 系列（Node 24）
5. 各 Node 版本的全局软件包： 每个 nvm Node 版本都有自己的全局软件包——检查所有已启用的 Node 版本
6. 验证时必须检查版本： 不要只检查是否存在 fdk 命令——要确认其主版本号正确（9.x 或 10.x）

为什么默认采用 CDN + nvm（以及 Homebrew / Chocolatey 的适用场景）

类比

方式	大致类比
nvm / nvm-windows + CDN tarball（npm install -g https://cdn.freshdev.io/fdk/...）	固定工具链：一个 Node semver ↔ 一个 FDK 系列，与 docs/engine-matrix.md 相匹配，并支持并排使用多个技术栈（例如通过 .nvmrc，在不同 shell 或项目中使用 10.x/24 与 9.x/18）。
brew install fdk（macOS）/ choco install fdk（Windows）	单一全局安装：需要在系统范围内使用一个 fdk 时很方便；通常较难切换多个 FDK + Node 组合，而且版本固定方式可能与 tarball 标签不同。

没有任何内容被“移除”。 此处不将 brew / choco 方式作为主要默认选项，因为可复现安装和市场验证流程是围绕 CDN tarball + 固定 Node（engine-matrix）构建的。这些方式仍然有效：

• 用户可以参照 references/macos.md（Homebrew tap freshworks-developers/homebrew-tap）以及 references/windows.md / references/cross-platform-scenarios.md（Chocolatey）进行操作。
• commands/fw-setup-install.md 仍会在检测到 Homebrew/Chocolatey 时自动检测并调整流程。
• 如果用户坚持使用 brew/choco，在确认安装完成之前，请先验证 fdk version 和 node 的结果与 docs/engine-matrix.md 一致（以下的 PACKAGE MANAGER NOTE 仍适用）。

常见失败模式：

• ❌ npm install -g @freshworks/fdk（来自公共 npm 注册表的任何版本/标签）→ 404（注册表中不存在）；只能使用 CDN tarball URL
• ❌ 在 Node 24 上运行 npm install -g https://cdn.freshdev.io/fdk/latest.tgz → 安装 FDK 9.x，运行时失败
• ❌ 在 Node 24.14.x 上使用 FDK 10.1.0 运行 fdk version → 引擎不匹配错误
• ❌ 只卸载 @freshworks/fdk → 遗留的 fdk 软件包仍会保留

执行安装

运行 /fw-setup-install，并且仅按照 commands/fw-setup-install.md 操作（根据 docs/engine-matrix.md，使用 CDN tarball + 固定 Node）。

快速检测（启动子 Agent 前）

启动子 Agent 前，直接运行以下检查以提供上下文：

内联： bash scripts/fw-setup-quick-detect.sh（与 /fw-setup-status 默认区块执行相同的检查）。

报告格式：

DETECTION:
- FDK: [version/not installed]
- Node: [version/not installed]
- nvm: [installed/missing]
- nvm current: [version/none]
- ~/.fdk: [exists/missing]

---

操作 1：安装

触发条件： 未安装 FDK，或用户请求安装。

1. 运行 /fw-setup-install → 仅遵循 commands/fw-setup-install.md（Shell Task、自动检测 brew/choco、遵循该命令中的验证关卡）。
2. 遵守CDN Tarball 现状（见上文）——不要将 registry @freshworks/fdk 作为首选。
3. 失败时：查看 references/macos.md 或 references/windows.md。

安装后 MCP（可选）： 仅在成功安装/升级后，提供 Marketplace MCP 设置选项；Cursor 配置格式：references/templates/cursor-mcp-config.json；Claude Code： 根据 AGENTS.md 使用 .mcp.json + mcp_auth_token。绝不要在聊天中粘贴 JWT。

---

操作 2：升级

触发条件： 用户想要更新的 FDK（最新的 10.x 系列或指定版本）。

规范命令： commands/fw-setup-upgrade.md（/fw-setup-upgrade，可选 --to X.Y.Z）。

• 最新 FDK 10.x 系列： 在 Node 24.11.x 上使用 CDN https://cdn.freshdev.io/fdk/latest-v24.tgz（卸载带作用域和旧版 fdk，移除 ~/.fdk，然后安装）。
• 指定的 10.x.y / 9.x.y： 使用 CDN https://cdn.freshdev.io/fdk/vX.Y.Z.tgz（在 npm install -g 前用 curl 验证 HTTP 200）。

不要使用公共 npm registry 中的 npm install -g @freshworks/fdk（任何版本或标签）——仅使用 CDN tarball URL（参见上文的CDN Tarball 现状）。

关键规则：

• [VALID] 安装后务必在新的 shell 中验证升级
• [VALID] 对于 --to，安装前确认 tarball URL 返回 200
• [INVALID] 如果 fdk version 与请求的系列不匹配，绝不要声称升级成功

---

操作 3：降级

触发条件： 用户需要特定的 FDK semver、FDK 9.x 系列（已弃用）或 latest 9.x。

规范命令： commands/fw-setup-downgrade.md（/fw-setup-downgrade）。不要自行采用 nvm use fdk，也不要使用公共 npm registry 中的 npm install -g @freshworks/fdk（任何版本或标签）。

权威流程：

• 卸载全局安装项（@freshworks/fdk、fdk），移除缓存目录（~/.fdk / Windows 用户配置文件中的 .fdk）。
• 选择 Node 系列：FDK 10.x 使用 24.11.x + latest-v24.tgz / vX.Y.Z.tgz；FDK 9.x（已弃用）使用 18.x + latest.tgz 或 vX.Y.Z.tgz。
• 仅使用 npm install -g <CDN tarball URL>（参见CDN Tarball 现状）。
• 按照强制验证关卡，在新 shell 中验证（Unix 与 Windows 的步骤不同）。

运行 commands/fw-setup-downgrade.md 中定义的 shell Task（Unix 上使用 bash；Windows 上使用多步骤 PowerShell）——不要使用引用了 npm registry 固定版本的旧版模板。

关键规则：

• [INVALID] 安装目标版本前，绝不要跳过完整卸载和移除 ~/.fdk
• [VALID] 务必通过所有适用于该操作系统的验证关卡，并确认 fdk version 与目标版本匹配

---

操作 4：卸载

触发条件： 用户想要彻底移除 FDK。

规范命令： commands/fw-setup-uninstall.md（/fw-setup-uninstall）。使用该文件中的 Task 脚本（Unix 上使用 bash；Windows 上使用 PowerShell 代码块）——不要只依赖简略提示。

移除内容必须包括： npm uninstall -g @freshworks/fdk 以及 npm uninstall -g fdk（旧版无作用域的全局安装项）、~/.fdk 缓存、强制清理 npm 缓存；仅在安全时编辑 shell rc 文件（优先备份）。在 Windows 上，使用 PowerShell 等效命令和 %USERPROFILE%\.fdk，具体参见 commands/fw-setup-uninstall.md。

验证： 确认当前 shell 和适用于该操作系统的新 shell（zsh -c / 新的 PowerShell）中均不存在 fdk——参见下方的验证关卡。

关键规则：

• [INVALID] 在通过适用于该操作系统的验证关卡（新 shell 中不存在 fdk）之前，绝不要说“卸载完成”
• [INVALID] 绝不要跳过移除 ~/.fdk / Windows 用户配置文件缓存
• [VALID] 对 rc 文件执行 sed / 编辑之前，务必先备份（与 --fix 一致）

操作 5：状态

触发条件： 用户检查 FDK 安装情况。

仅限内联操作。 运行 commands/fw-setup-status.md 中的 bash 代码块（默认；--verbose 会增加 PATH/nvm/rc 诊断）。

---

渐进式披露

仅在需要时加载以下参考资料：

• 复杂场景： 阅读 references/cross-scenarios.md
• macOS 问题： 阅读 references/macos.md
• Windows 问题： 阅读 references/windows.md（PowerShell 的 where/where.exe、PS 5.1 中的 &&、MSI/winget/Chocolatey/fdk 与 CDN tarball + PATH）
• npm 权限 / EACCES： 阅读 references/npm-permissions-sop.md

除非操作失败或用户的设置较复杂，否则不要加载这些文件。

---

错误恢复

错误	操作
fdk: command not found	运行操作 1（安装）
npm permission denied	加载 references/npm-permissions-sop.md；使用由 nvm 管理的前缀，在共享系统上未经批准绝不运行 sudo npm
Node version mismatch	将 Node 调整为 docs/engine-matrix.md 指定的版本（FDK 10.x 系列使用 nvm use 24.11.0，等等）
Windows：nvm use 后 node -v 仍显示错误版本，或 Get-Command node → Program Files\nodejs	PATH 优先级问题（MSI/winget/choco/scoop 与 nvm-windows 冲突）——references/windows.md 基于安装程序的设置
版本冲突	运行操作 4（卸载），然后运行操作 1（安装）
特定操作系统的故障	阅读 references/[os].md

---

验证关卡——必须通过（Unix 与 Windows）

[ALERT] 零容忍： 除非针对相应操作系统通过所有适用关卡，否则操作绝不算完成。

Unix / Linux / macOS（bash/zsh）

关卡	检查项
1 – 命令是否存在	command -v fdk 成功（安装/升级/降级），或不存在（卸载）
2 – 新 shell	bash -lc 或 zsh -lc：command -v fdk && fdk version 与预期 semver 匹配，或卸载时 command -v fdk 不存在
3 – 版本匹配	fdk version 与 FDK 10 与 9 的预期主版本.系列匹配
4 – 缓存	按矩阵检查 ~/.fdk（按卸载/降级要求移除）
5 – 全局安装	npm list -g … 反映单一安装路径（卸载后同时检查 @freshworks/fdk 和 fdk）
6 – nvm 默认值	默认 Node 别名指向数字型 semver（例如 24.11.0），而非虚假的 fdk 标签

Windows（PowerShell；参见 references/windows.md）

关卡	检查项
1–3	where.exe fdk；在新的 PowerShell 窗口或 powershell.exe -NoProfile -Command 'fdk version' 中运行 fdk version；如有需要，在 npm install -g 后刷新 PATH
4	按降级/卸载要求移除 %USERPROFILE%\\.fdk
5–6	nvm-windows 默认 Node 版本与FDK 主版本一致（nvm current、nvm list）
7 – PATH 检查	如果存在独立安装的 Node（MSI/winget/choco/Scoop）：where.exe node / Get-Command node 应解析到用于 FDK latest-v24 工作的、由 nvm 管理的 node；否则按 references/windows.md 基于安装程序的设置 修复

/fw-setup-troubleshoot --fix 优先面向 Unix shell/rc；在 Windows 上使用手动 SOP + references/windows.md，除非调用了 PowerShell 修复 Task。

---

关键验证

安装

检查项	要求
FDK	主要用于 Platform 3.0 开发时使用 10.x（根据 engine matrix，9.x 已弃用）
Node	FDK 10.1+ 系列使用 24.11.x（具体固定版本以 docs/engine-matrix.md 为准）；已弃用的 FDK 9.x 仅使用 18.x
nvm	已配置 nvm 或 nvm-windows
新 shell	Unix： bash -lc / zsh -lc；Windows： 新开的 PowerShell + where.exe fdk

降级

检查	要求
卸载旧版本	全局安装和缓存均已移除（~/.fdk / Windows 用户配置文件）
目标版本	仅使用 CDN tarball——绝不从公共 npm 注册表安装任何 @freshworks/fdk
nvm 别名	所选系列的 nvm alias default → Node semver——而不是 alias default fdk

卸载

检查	要求
已移除全局安装和旧版无作用域的 fdk	✓
缓存	已移除 ~/.fdk（及 Windows 对应目录）
新 shell	fdk 不在 PATH 中

错误目录

错误	严重性	操作
fdk: command not found	严重	执行操作 1（安装）
npm permission denied	严重	使用 nvm，绝不使用 sudo npm
Node version mismatch	高	根据 docs/engine-matrix.md 对齐 Node（FDK 10 系列使用 nvm use 24.11.x，已弃用的 9.x 使用 18.x）
版本冲突	高	执行操作 4（卸载），然后执行操作 1（安装）
卸载后 ~/.fdk 仍存在	中	手动移除：rm -rf ~/.fdk
新 shell 中仍是旧版本	高	使用全局切换重新执行降级
存在多个 FDK 版本	中	全部卸载，然后重新安装目标版本
操作系统特定故障	不定	阅读 references/[os].md

---

反模式

不要：

• 不使用 nvm 安装 Node
• 使用 sudo npm install -g
• 降级前跳过彻底卸载
• 卸载后留下 ~/.fdk 目录
• 创建文档文件（README、CHANGELOG）
• 手动编写安装步骤——使用子 Agent
• 未在新 shell 中验证就声称“已完成”
• 跳过任何验证关卡

务必：

• 使用官方 FDK CLI 命令
• 每次操作后都进行验证
• 保留现有 Node 版本
• 卸载时彻底清理
• 降级时设置全局默认版本
• 在新 shell 中测试
• 运行所有验证关卡
• 报告验证结果

---

总结

• SKILL.md — 核心强制规则、操作、验证关卡、错误目录
• references/cross-scenarios.md — 复杂的多 Node 场景、PATH 冲突、双版本设置
• references/macos.md — macOS 特定的安装、Homebrew、zsh 配置
• references/windows.md — Windows 特定的安装、Chocolatey、PowerShell 配置
• commands/ — 斜杠命令定义：/fw-setup-*（Confluence 风格）；旧版 /fdk-* 名称仍是上述路由中的有效别名

不确定时，请在执行前加载相应的 references/ 文件。

---

约束（自动强制执行）

• 严格模式： 仅拒绝 Platform 2.x / 2.3 请求。直到 docs/engine-matrix.md 中的支持终止日期之前，FDK 9.x 仍可使用，但会显示弃用提示；不会直接拒绝。
• 无效版本字符串： 在安装/升级/降级前，拒绝非 semver 格式的 FDK 版本输入（例如 "abc"、"latest-foo"）。说明有效格式为 X.Y.Z semver（如果有前导 v，请去掉）；在用户提供有效版本或接受默认最新系列之前，不得继续。
• 无来源依据时不得推断： 如果参考资料中没有相关信息，请回复“FDK 安装信息不足以确定”
• 必须验证： 每项操作都必须通过所有验证关卡
• 仅提供可用于生产环境的方案： 生成完整且持久的安装
• 全局持久性： 降级必须在所有终端中生效
• 彻底清理： 卸载必须移除所有残留