fw-publish

入口约定

• 调用方： 控制器在 fw-review 通过且用户明确同意发布后调用
• 前置条件： 已完成 fw-review；已确认 MCP 身份验证（list_custom_apps 冒烟测试）；上传时使用非沙箱网络
• 返回值： done（已提交／已创建版本）| blocked（缺少身份验证／网络／审核）| escalate（多次上传失败）
• 完成后： 将控制权交还给控制器——通过 session-write.sh 更新会话中的发布区块；不要启动新的工作流
• 会话： 从会话中读取 publish.tracking_id；成功提交后写入 publish.tracking_id、step=published

发布（Platform 3.0 自定义应用）

强制前置条件： 发布前运行 fw-review 技能，确保符合应用市场要求。审核会检查 iparams、前端文件、安全模式，并生成结构化审计报告。审核通过前不要继续发布。

目标： 获取任意 Platform 3.0 应用文件夹（包含 manifest.json），生成 dist/*.zip，并通过 MCP 工具将其发布到 Freshworks Marketplace。目前仅支持 test 状态。

沙箱／Agent 出站流量： 在会阻止 MCP 流量访问 https://mcp.freshworks.dev/mcp 或阻止出站 HTTPS（包括对应用上传 URL 执行 curl PUT）的沙箱（或等效）模式下，发布无法正常进行。某些云端或 CI Agent 运行环境会通过代理、网关或假定的 IAM 角色发送 HTTPS 请求，而这些方式不允许向 Marketplace 应用上传存储桶（fa-*-app-uploads…）发送 PUT 请求：即使预签名 URL 有效，S3 仍会返回 403 / AccessDenied。不要在沙箱化 Agent 或受限 shell 中运行此操作手册。如果用户的客户端提供沙箱和完整网络访问选项，请选择非沙箱模式／允许发布所需的网络访问。若严格按照步骤 8 操作后 PUT 返回 403，请让用户在本地计算机上运行相同的脚本命令（见步骤 8）。

Agent 操作手册（MCP 工具）

工具名称和参数与 Freshworks openai-server 相匹配（references/openai-server-mcp-tools.md）。托管 MCP：https://mcp.freshworks.dev/mcp。

1. 预先检查身份验证令牌（必须作为第 1 步）

在调用任何 MCP 工具之前，请确认 MCP 发布工具可用且已通过身份验证：

• 尝试调用 list_custom_apps（可选 {} 或 { "page": 1, "perPage": 10 }）。仅将此调用用作身份验证／连接测试——不要仅凭此调用选择 appId。在发布时（第 6 步），你还会再次询问用户选择新建还是现有；如果选择现有，则调用 list_custom_apps，供开发者选择。
• 如果调用成功，则确认身份验证通过——继续执行第 2 步。
• 如果工具不可用或调用返回身份验证错误，请判断属于哪种情况：

情况 A — 已配置 MCP 服务，但令牌缺失或已过期：

MCP 服务已设置，但 API 密钥需要刷新或尚未设置。

1. 前往 https://developers.freshworks.com/developer/
2. 在 "API key for Freddy AI Copilot VS Code plugin & Freshworks Agentic Developer Toolkit" 下方 → 点击 "View API Key"
3. 在 "Connect to Freddy AI Copilot MCP server" 下方 → 选择你的 IDE 标签页 → 点击 Copy
4. 在 IDE 的 MCP 设置中更新令牌，然后重启／重新加载 MCP 连接
5. 重新运行发布命令

情况 B — 尚未配置 MCP 服务：

1. 前往 https://developers.freshworks.com/developer/

2. 在 "Connect to Freddy AI Copilot MCP server" 下方 → 选择你的 IDE 标签页（Cursor 或 VS Code）

3. Cursor： 直接点击 "Install in Cursor"，或将 references/templates/cursor-mcp-setup.json 合并到 ~/.cursor/mcp.json（替换 <your-api-key>，然后重启 Cursor）。

   Claude Code（通过插件）： freshworks 插件会在安装时提示输入 API 密钥。如果你跳过了这一步，请运行 /config 并更新插件设置。密钥会安全地存储在系统密钥链中。

   Claude Code（独立技能，无插件）： 通过 claude mcp add --scope user 将 references/templates/claude-mcp-setup.json 添加到项目的 .mcp.json 或 ~/.claude.json（替换 <your-api-key>，然后重启 Claude Code）。

4. 重新运行发布命令

在确认身份验证通过之前，不要继续任何发布步骤。

2. 确定应用目录

使用与 fw-app-dev /fdk-fix 第 1 步相同的步骤——参见 ../fw-app-dev/commands/fdk-fix.md（确定应用目录）：

1. 在工作区中搜索 manifest.json 文件。
2. 如果有多个文件夹包含 manifest.json：询问用户要发布哪个应用。
3. 如果只有一个文件夹：使用该目录。
4. 如果没有：告知用户并停止。

2.5 发布前：确认 API 密钥对应正确的产品

Developer API 密钥因产品而异。请让用户确认，已配置的 API 密钥与要发布此应用的产品相匹配。如果用户不确定，请停止——他们需要先验证或更新密钥，再继续操作。

3. 检查 Node.js 和 FDK 版本（打包前）

• 从应用目录中的 manifest.json 读取 engines.node 和 engines.fdk
• 检查当前启用的版本：node --version 和 fdk --version
• 如果缺少 fdk（fdk --version 失败／提示找不到命令）：停止。未经询问，不要自动安装或假定使用“最新 FDK”。告知用户，运行 fdk validate／fdk pack 需要 Freshworks CLI。提供 fw-setup：/fw-setup-install（默认使用 Node 24.11 上的 FDK 10.x）。可选的一次性询问：“现在运行 /fw-setup-install？（y/n）”——只有用户回答 yes 时，才遵循 skills/fw-setup/SKILL.md；回答 no 时，停止并等待用户手动安装。除非用户明确了解风险并选择覆盖此要求，否则在 fdk 可用之前，不要继续执行步骤 4。
• 如果版本不匹配（但存在 fdk）：停止并显示 references/templates/engines-mismatch-prompt.txt（替换其中的 manifest 版本和当前版本）。
• 在版本匹配或用户明确选择覆盖之前，不要运行 fdk pack

4. fdk validate（发布前）

运行 cd <app-directory> && fdk validate，并将结果视为上传的有效性门槛：

• 任何上传／提交都必须满足：平台错误数为 0，lint 错误数为 0（标准与 fw-app-dev 相同）。任一项未达标时，停止——记录指标（参见下文的 Validate failure metrics），然后使用 fw-app-dev 技能修复；不要调用 create_app_upload_url，不要运行 fdk pack，也不要上传 zip。
• fdk pack --skip-coverage --skip-lint（步骤 5）只会跳过打包时的 coverage／lint 检查——不会免除此步骤。绝不要仅凭 pack 推断“应用有效”。

**Validate failure metrics（在步骤 4 停止前）：**绝不要向开发者提及 .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；不加引号）。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-publish \
  invoked=1 skill_version=<version> publish_outcome=failed_validate

将 .meta.json 保留在磁盘上。不要运行 meta-delete.sh。

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

Marketplace 后端：无效的 zip 仍可能被接受：API 可以创建 Draft 版本，而不拒绝该软件包。不要将 submit_custom_app／add_app_version 成功调用视为应用可安装的证明——步骤 7 前必须确保 fdk validate 检查全部通过。

4.5 必须执行——开发者体验反馈（必须询问，是否回答均可）

继续执行 fdk pack 前，必须提出此问题。不要跳过此步骤。

向开发者询问一次——原样显示 references/templates/developer-feedback-rating-prompt.txt。

如果对方回复 👍 或 👎，再跟进一次——原样显示 references/templates/developer-feedback-comment-prompt.txt。

然后，在继续执行步骤 5 前，使用 meta-feedback.sh 写入反馈（绝不要手动编写 JSON）。如果开发者跳过或没有回复，不要调用 meta-feedback.sh——完全省略 "developer_feedback" 键。绝不要向开发者提及 .meta.json。

# Developer chose 👍 or 👎 and provided a comment:
bash ~/.fw-dev-tools/scripts/meta-feedback.sh <app-directory> liked "Setup was smooth, fw-review caught issues I missed"

# Developer chose 👍 or 👎 and skipped the follow-up comment:
bash ~/.fw-dev-tools/scripts/meta-feedback.sh <app-directory> disliked

# Developer chose Skip or did not answer — do NOT run meta-feedback.sh

.meta.json 中的结果结构：

"developer_feedback": {
  "rating": "liked",
  "comment": "Setup was smooth, fw-review caught issues I missed"
}

• rating — "liked" 或 "disliked"
• comment — 自由文本；如果开发者跳过，则完全省略此键

4.6 必须 — 在执行 fdk pack 前写入 .meta.json 指标（切勿跳过）

平台会从上传的应用 zip 中读取技能指标。 请在步骤 4.5 之后、步骤 5（fdk pack）之前完成此步骤，以便构建软件包时 <app-directory>/.meta.json 包含 fw-publish 块。切勿向开发者提及 .meta.json。

仅使用脚本 — 切勿手动编写 JSON。

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-publish \
  invoked=1 skill_version=<version>

将 publish_outcome 留空（""）——上传/提交尚未完成。步骤 5 构建的 zip 必须包含此文件，才能上传到平台。

5. fdk pack

在应用目录中执行（非交互式；跳过打包时的覆盖率/lint 检查，以免自动化因覆盖率问题而受阻）：

cd <app-directory> && printf 'Y\n' | fdk pack --skip-coverage --skip-lint

生成 dist/*.zip。仅当不需要 --force-pack 时才复用现有 zip（由 Agent 判断）。

无效应用： 切勿让无效构建通过此流程。如果步骤 4 未通过，且存在平台错误或 lint 错误，请停止——此发布流程中不要运行 fdk pack，也不要继续步骤 6–14。对 pack 使用 --skip-coverage / --skip-lint 只会避免 pack 内的额外工作，不能替代通过检查且无错误的 validate。

Zip 布局检查关卡（步骤 7 前必须完成）： 执行 fdk pack 后，选定要上传的 zip（使用本次打包生成的 dist/*.zip；若有多个，使用修改时间最新的文件，或 fdk pack 输出的路径）。运行：

unzip -l 'dist/<app>.zip'

检查 Name 列（每个文件行的最后一列）：

• 通过 — manifest： 压缩包中至少有一个成员的名称恰好为 zip 根目录下的 manifest.json（不能仅存在于子文件夹中）。
• 通过 — 指标： zip 根目录下列有 .meta.json（在步骤 4.6 中写入）。如果 fdk pack 未将其包含在内，请停止并按照下方的修复步骤重新打包——明确包含 .meta.json。
• 失败 — 停止；不要调用 create_app_upload_url： 缺少 manifest.json，或仅出现 ./manifest.json（带有前缀 ./），或唯一的 manifest 位于嵌套路径下（例如 some-folder/manifest.json），而根目录下没有 manifest.json。Marketplace 流程通常会匹配精确的存储路径名称；在这些检查中，./manifest.json 不会被视为与 manifest.json 相同。

如果未通过检查 — 修复步骤：

1. 在 <app-directory> 中再次运行 fdk pack（同上）。
2. 如果文件列表仍未通过检查：解压到一个干净的目录中，然后使用明确指定的顶层成员重新压缩（避免使用 zip -r … .，因为它通常会记录 ./ 前缀）。示例（根据解压后的目录树调整文件夹名称）：

rm -rf /tmp/fw-repack && mkdir -p /tmp/fw-repack && unzip -q -o 'dist/<app>.zip' -d /tmp/fw-repack
cp '<app-directory>/.meta.json' /tmp/fw-repack/.meta.json
cd /tmp/fw-repack && zip -r '<app-directory>/dist/<app>-resubmit.zip' manifest.json .meta.json app config server README.md

仅列出解压后实际存在的路径（如果不存在，则省略 server、README.md 等）。当 <app-directory> 中存在 .meta.json 时，务必将其包含在内。添加应用所需的其他顶层文件或目录。重新运行 unzip -l，直到两项检查都通过，然后在步骤 8 上传该 zip。

5.5 自定义应用数量限制警告（必须 — 切勿跳过）

继续操作前，原样显示 references/templates/custom-app-limit-warning.txt。 自检：你是否已在回复中输出上述警告？如果没有，请立即输出，然后再继续步骤 6。

6. 发布时路由：新建上架还是更新现有应用（MCP 交接）

在发布时执行此操作——在获得通过 zip 布局检查门槛（步骤 4–5）的有效 zip 之后，并且在调用 create_app_upload_url（步骤 7）之前。此分支决定上传后哪个 MCP 工具会接收 uploadId。

不要从 .fdk/app-info.json 读取 appId 用于路由或 MCP 调用。

1. 停止并询问用户——不要自行假设：

   Is this a new Marketplace listing or an update to an existing app?
   1. New listing
   2. Update existing app
   

   在用户回答之前，不要继续执行步骤 7。 仅当用户已在当前会话中明确说明时才跳过。

2. 新建上架： 尚无 appId。完成步骤 7–9 后，在步骤 10 中调用 submit_custom_app，并传入 uploadId 和清单元数据。**MCP 交接：**新应用载荷 + 预签名的 uploadId。

3. 现有应用（更新）：

   a. 调用 list_custom_apps（必要时分页）。向开发者展示 apps——至少包括 id、name、type、products、latestVersion——并要求开发者选择目标上架项。记录该 appId。

   b. 检查最新版本是否卡住： 使用所选 appId 调用 list_app_versions。只检查最新版本（按 updatedAt 时间最新）。

   • 如果最新版本的 state: "development"，则停止并显示 references/templates/stuck-version-warning.txt（填写版本字段）。
   • 如果最新版本处于任何其他状态，则继续执行步骤 7。

   c. MCP 交接（版本检查通过后）： 完成步骤 7–9 后，在步骤 10 中调用 add_app_version，并传入开发者选择的 appId、uploadId 和清单字段。

4. 如果用户选择了更新，但列表为空，则说明不存在上架项——提供新建上架或取消的选项。

可选：如果仅有一个应用，且用户已选择更新，则显示该行，并要求用户用一句话确认后再使用其 appId——仍然绝不从 .fdk/app-info.json 假设 appId。

6.5 支持邮箱——MCP 上传流程（步骤 7）之前必须完成

门槛： 对于相应的发布路径，完成此步骤之前，不要调用 create_app_upload_url（步骤 7）或 submit_custom_app，也不要开始预签名 zip 上传。

缺少 supportEmail 并不总会导致 PUT 上传失败——它会在之后调用 submit_custom_app（步骤 10）时失败，此时 uploadId 已被使用，zip 也已上传到存储。用户通常会将其描述为**“应用上传”/发布失败**。请尽早收集 supportEmail，确保在生成 uploadId 之前 MCP 提交载荷已完整。

发布路径（来自步骤 6）	要求
新建上架	submit_custom_app 要求提供 supportEmail。在步骤 7 之前，明确提示用户提供有效且有人监控的 Marketplace 支持邮箱。不要从 git config user.email 推断（该值可能缺失、属于个人邮箱或不正确）。如果清单或文档中提到了联系人，请向用户确认。保存确认后的值，以便在步骤 10 使用。如果用户无法提供 supportEmail，则停止——不要继续调用 create_app_upload_url。
现有应用（更新）	add_app_version 使用 appId、platformVersion、modules、uploadId——通常的 add_app_version 载荷中不包含 supportEmail。除非产品/API 规则发生变化，否则此路径无需强制提示用户提供邮箱。

7. 创建应用上传 URL

前置条件： 新应用上架时，必须已满足步骤 6.5（调用前确认 supportEmail）。

调用 create_app_upload_url — 返回 uploadId + uploadUrl + expiresInSeconds。

• 保留 uploadId，供步骤 10（submit_custom_app / add_app_version）使用
• 立即仅使用 echo … > file 或 cat > file，将完整 JSON 响应写入临时文件 — 不要使用 jq、Python、Node 或任何其他工具来处理或重新输出该响应：

  echo ‘<full-json-response>’ > /tmp/fw-upload-response.json
  

  不要自行提取 uploadUrl — 上传脚本会在内部通过 jq 读取它。将响应视为不透明数据块，并按原样将文件路径传给脚本。

✅ 门槛 — 继续步骤 8 前，请确认：

Response file written using only echo or cat (not jq / Python / Node)? [yes/no]

除非答案为是，否则不要继续步骤 8。

8. 应用上传（PUT zip 二进制文件）

使用捆绑的上传脚本，并传入步骤 7 中的响应文件。脚本会在内部通过 jq 提取 uploadUrl — LLM 不会接触该 URL。不要改用 Python（urllib.request、requests、…）、Node（fetch / node -e）或任何其他 HTTP 客户端 — 即使 URL 有效，这些环境在托管/云运行时中也经常遇到 403。

0. 使用通过 zip 布局门槛（步骤 5）的同一个 dist/*.zip 文件，包括在那里重新构建的 …-resubmit.zip。
1. 传入步骤 7 中的响应文件 — 不要读取、解析或输出其内容。
2. 优先在用户的机器上运行（网络畅通的本地 Terminal / IDE 终端，而非受限的远程工作节点）。
3. 脚本会自动重试，最多 3 次。最终仍失败时，再次调用 create_app_upload_url 获取新的响应，并重新运行脚本。

bash <skill-root>/scripts/upload-app.sh dist/<app>.zip /tmp/fw-upload-response.json

• <skill-root> — 安装了 fw-publish 技能的目录（例如，仓库中的 skills/fw-publish）
• /tmp/fw-upload-response.json — 步骤 7 中写入的响应文件；脚本会通过 jq 提取 uploadUrl
• 脚本会发送 Content-Type: application/zip，并在成功时输出 Upload successful (HTTP 200)

自动运行 / 沙盒： 受限沙盒经常导致上传出现 403 或网络故障 — 此步骤请使用非沙盒环境 / 完整网络（见顶部的 Sandbox）。

不要对 zip 进行 Base64 编码。

9. 读取 manifest.json 并检测 AI Actions 应用

读取应用目录中的 manifest.json。提取：

• platform-version（例如 "3.0"）
• modules 键（例如 ["common", "support_ticket"]）
• name（若存在）作为 appName

AI Actions 检测： 检查应用目录中是否存在 actions.json。

• 如果存在，停止并询问用户 — 不要自行假设：

  Detected actions.json — this looks like an AI Actions app.
  Should I include worksWith: ["ai_actions"] when publishing? (yes/no)
  

  在用户回答前，不要继续步骤 10。
• 如果用户确认是，则在步骤 10 中设置 worksWith: ["ai_actions"]。
• 如果回答否或 actions.json 不存在，则省略 worksWith。

降级警告（仅限现有应用更新路径）： 如果这是对现有应用的更新，且 actions.json 不存在（或用户对 worksWith 的回答为否），则在继续前逐字显示 references/templates/downgrade-warning.txt。 在用户确认前，不要继续步骤 10。

10. 调用适当的 MCP 工具（部署 / 版本交接）

使用步骤 6 中发布时的选择：新应用 → submit_custom_app；现有应用 → 使用开发者选择的 appId 调用 add_app_version。

新应用 — submit_custom_app：

参数	来源
appName	清单中的 name 或目录名称
appDescription	询问用户或使用默认值
appOverview	询问用户或根据描述生成（最多 150 个字符）
supportEmail	新应用必填 — 必须在调用 create_app_upload_url 之前，已在步骤 6.5 中收集。切勿使用 git config user.email 或其他 git 元数据 — 其可能未设置、属于个人邮箱，或不适合作为应用市场支持邮箱。
alternateEmail	可选
platformVersion	清单中的 platform-version
modules	清单中的 modules 键（参阅 openai-server 工具架构 — 可能至少需要一个非 common 模块）
uploadId	来自步骤 7
targetState	"test"（唯一支持的状态 — 不要询问用户）
zipFileName	可选（例如 my-app.zip）
worksWith	来自步骤 9 的 AI Actions 检测 — 已确认则为 ["ai_actions"]，否则省略

现有应用 — add_app_version（MCP 上提供时）：

参数	来源
appId	来自 list_custom_apps（步骤 6）的开发者选择的 appId — 不要使用 .fdk/app-info.json 中的值
platformVersion	清单中的 platform-version
modules	清单中的 modules 键
uploadId	来自步骤 7
targetState	"test"（唯一支持的状态 — 不要询问用户）
zipFileName	可选
worksWith	来自步骤 9 的 AI Actions 检测 — 已确认则为 ["ai_actions"]，否则省略

11. 保存应用身份信息（可选，仅限本地）

你可以在应用目录中写入或更新 .fdk/app-info.json，将响应中的 id 和 version 作为本地记录保存。下次发布仍须遵循步骤 6 — 调用 list_custom_apps 并由开发者选择要更新的应用 — 不要跳过列表查询，也不要依赖此文件获取 appId。

12. 验证状态

使用提交 / 更新返回的 appId（或所选列表条目的 id）调用 get_app_status，确认应用级状态。

也可以使用 appId 调用 list_app_versions，验证新版本是否已进入 test 状态，并查看各版本的详细信息。这有助于确认部署成功，并发现新版本是否卡在 development 状态（这表示部署失败 — 用户应前往 Developer Portal 查看失败详情）。

13. 发布后的本地清理（成功时切勿跳过 — 须在步骤 14 前完成）

在成功路径中，告知用户任何信息之前，必须先完成此步骤。未完成步骤 13 时，不要输出步骤 14 的报告。切勿向开发者提及 .meta.json。

发布成功（步骤 12 确认状态为 test）：

bash ~/.fw-dev-tools/scripts/meta-delete.sh <app-directory>

指标已在步骤 5 随 zip 一并上传（在步骤 4.6 中写入）。此处不要调用 meta-update.sh 并设置 publish_outcome=success — 平台不接受上传后的指标更新。

步骤 5 之后失败（上传或提交失败）— 仅更新本地 .meta.json 以供诊断（已上传的 zip 中 publish_outcome 为空）：

bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-publish publish_outcome=failed_upload
# or: publish_outcome=failed_submit

不要调用 meta-delete.sh。保留 .meta.json 不变。

publish_outcome 参考：

值	写入时机	是否在已上传的 zip 中？
failed_validate	步骤 4 STOP（打包前）	否 — 未生成 zip
""（空值）	步骤 4.6（打包前）	是 — 正常发布流程
failed_upload	步骤 8 失败后，在步骤 13 写入	仅本地（zip 已上传）
failed_submit	步骤 10 失败后，在步骤 13 写入	仅本地（zip 已上传）

14. 向用户报告

告知用户：应用 id、版本状态，以及在其产品中安装自定义应用的位置（Admin -> Apps 或相应位置）。

MCP 工具参考（fw-dev-mcp）

支持的应用状态： 仅支持 test 状态。targetState 始终使用 "test"——切勿让用户选择状态。

工具	用途	使用时机
list_custom_apps	列出开发者账户中的所有自定义应用。返回 count 和 apps（每个应用包含：id、name、type、subType、subscriptionType、state、products、latestVersion）。可选参数：page、perPage。结果按最近更新时间从新到旧排序。	步骤 1（认证预检）、步骤 6.3a（选择现有应用）
list_app_versions	列出某个应用的所有版本。返回数组，每个版本包含 id、version、platformVersion、state、updatedAt。	步骤 6.3b（在调用 add_app_version 前检查 development 状态的最新版本）、步骤 12（可选验证）
create_app_upload_url	生成预签名的 S3 上传 URL。返回 uploadId、uploadUrl、httpMethod（"PUT"）、expiresInSeconds。	步骤 7（上传 zip 文件前）
submit_custom_app	创建新的自定义应用和首个版本。需要 appName、appDescription、appOverview、supportEmail、platformVersion、modules、uploadId。在调用 create_app_upload_url（步骤 6.5）前收集 supportEmail。可选参数：alternateEmail、zipFileName、worksWith（例如 ["ai_actions"]）。提交成功后，应用将进入 test 状态。	步骤 10（新建应用流程）
add_app_version	为现有应用添加新版本。需要 appId（从 list_custom_apps 获取并由用户选择）、platformVersion、modules、uploadId。可选参数：zipFileName、worksWith。如果最新版本处于 development 状态，则无法继续（先通过 list_app_versions 检查；用户必须在 Developer Portal 中删除该卡住的版本）。	步骤 10（现有应用流程，通过版本状态检查后）
get_app_status	获取应用级别的汇总状态。返回 id、name、type、subType、subscriptionType、state（反映所有版本）、products。部署失败时，state 通常会回退到或包含 development。	步骤 12（发布后验证）

fw-dev-mcp 服务上的其他工具：

• get_developer_docs：获取开发者文档。首选文档来源——平台相关问题应先使用此工具；如果 MCP 不可用，再参考硬编码的技能文档。应用构建工作（实现、验证、评审）仍通过 fw-app-dev 进行。
• 已弃用的构建工具： implement_app、get_implementation_plan、idea_to_app、fix_app_errors——服务会返回弃用契约；请按照其中的重定向使用 fw-app-dev。请参阅 references/deprecated-mcp-build-tools.md。

错误处理

• 任何 MCP 工具返回 401/403： 立即停止，并显示第 1 步中的身份验证设置说明。令牌可能已过期、配置错误或缺失。不要重试——提示用户修复令牌后重新运行。
• 验证错误（400）： 建议修复清单，或使用 fw-app-dev 技能。常见原因：products 与 modules 不匹配。
• 重试 3 次后上传仍失败（第 8 步中的脚本）： 不要再次运行上传脚本。请用户确认：(1) 是否在其本地计算机上运行（而非沙盒/受限环境），(2) 网络是否能访问 S3（未被代理或 IAM 策略阻止）。确认两项后，从第 7 步重新开始——调用 create_app_upload_url 获取新的响应文件，并重新运行上传脚本。若再次失败，则停止——持续失败表明存在环境或基础设施问题。
• fdk validate / fdk pack 失败： 使用 fw-app-dev 技能修复；检查 Node/FDK 版本是否匹配。若 validate 未通过（第 4 步），不要上传——即使 zip 有问题，也仍可创建草稿列表。
• 上传或提交后出现清单/包布局错误： 重新运行 Zip 布局检查（第 5 步末尾）。如果出现 ./manifest.json，但根目录下没有 manifest.json，则按照第 5 步的修复步骤重新打包，然后再调用 create_app_upload_url。

前提条件

要求	说明
上传主机	脚本必须能访问预签名存储桶所在的 S3；云端/受限环境可能始终返回 403——请使用本地终端或不受限的网络（第 8 步）。
非沙盒执行	MCP + 脚本上传需要出站 HTTPS；沙盒中的 Agent/ shell 通常会导致发布失败——此流程请使用完整网络/禁用沙盒。
manifest.json	应用根目录；必须使用 Platform 3.0，并包含 modules。
Zip 成员名称	执行 fdk pack 后，上传的 zip 必须在归档根目录列出 manifest.json（不能只有 ./manifest.json）。请参阅第 5 步末尾的 Zip 布局检查。
PATH 中的 fdk	fdk validate + fdk pack。
已配置 MCP 工具	Claude Code：安装市场插件时，从根目录下的 .mcp.json 配置（安装时通过 userConfig 提示）。Cursor：将该文件中的服务器配置块合并到 ~/.cursor/mcp.json。
支持邮箱	创建（新应用）时必填；请询问用户——切勿从 git config 推断。更新时沿用现有市场应用的发布者元数据。
更新时的应用身份	发布时（第 6 步）：开发者选择 update 后，从 list_custom_apps 中选择 appId。不要使用 .fdk/app-info.json 进行路由。

可选：列出应用

对于更新，发布时的第 6 步会调用 list_custom_apps（开发者在调用 create_app_upload_url 前选择 appId）。你也可以随时调用它来查看账户中的应用，而不进行发布——此查看调用与发布时的选择以及向 add_app_version 传递 appId 是分开的。

链接

• references/openai-server-mcp-tools.md — mp-openai openai-server 中实现的 MCP 工具

• Developer Portal / MCP — 从 developers.freshworks.com/developer/ 获取 API key ——用于 Freddy AI Copilot for VS Code 插件和 Agentic Developer Toolkit 的 API key。或连接到 Developer MCP 服务（用于 MCP 配置）