---
name: kiwi-cloud-deploy
display_name: Kiwi 云端接待部署
display_name_en: Kiwi Cloud Reception Deploy
description: Deploy the Kiwi merchant reception runtime to the merchant's own WorkBuddy cloud app in a strict order (resolve latest once and verify the locked package → prepare → publish through capabilities explicitly present in the current WorkBuddy session → self-check → guide owner confirmation) with no-forgery rules. Use for 一键开通云端接待、升级云端接待服务、云端接待部署排障；不用于自有服务器部署。
description_zh: 按当前会话实际提供的 WorkBuddy 云端应用工具部署 Kiwi 商家接待运行时，自检并引导商家本人确认上线；缺少必要工具时停止并说明。
description_en: Deploy the merchant reception runtime to the merchant's own cloud app step by step, self-check, and guide the go-live confirmation.
category: 商业服务 > 软件/建站/技术开发
version: 0.3.2
author: harrylabsj
---

# Kiwi 云端接待部署

本技能把 Kiwi 商家接待运行时部署到**商家自己账号名下**的云端应用，并引导商家完成上线确认。部署由商家本人控制；每一步仅依据当前会话实际提供的工具、权限和回执，不对平台的其他能力作概括判断。

工具边界：每次执行前检查当前会话实际列出的 WorkBuddy 应用发布、查看和下线能力及参数。不得假设工具名、可用性、参数、应用复用语义或回执字段；仅在真实工具清单明确提供相应能力时才调用。缺少发布、应用身份核验或状态检查所需能力时，停止对应步骤并说明限制，不借用其他平台的 Sites 工具，也不编造工具或回执。云端模块是否需要开通以当前产品包和平台真实要求为准，不作旧版本断言。

**本地验证范围（截至 2026-10-30）**：该次 npm latest stage→verify 成功锁定 `@harrylabsj/kiwi-merchant-cloud@0.12.15`（source commit `c043f0913270e273bab57dbb97a30a6c9819afa6`，安装树 22,146 个文件）。另一次 ARM64/Node 22.19.0、`--network none` 合成启动健康结果只针对 0.12.14（`livez=200`、`readyz=200`，四项 readiness 全部通过）；不能据此声称 0.12.15 已启动。两项均为本地验证，不证明 WorkBuddy 宿主、真实云部署、真实商家或用户本人审批。预检仍返回 `executionAuthorized:false`；真实首次发布、升级和访问真实商家仍受实际执行授权、身份/数据保护、平台验收与用户确认门控制，不得绕过。

固定参数：云端应用/站点名一律用「**Kiwi商家接待**」。已有就复用，**绝不新建第二个**；首次部署后的再次发布必须复用**同一个应用**（换应用会换公网域名，后续校验全部失效）。

## 随包资源与执行目录

技能包的 `scripts/cloud-session-cli.mjs` 是 latest 预检候选，先解析 npm `latest` 一次并锁定版本、tarball SHA-512 与源码证明，下载并验证完整 manifest 与安装副本；后续复验读取同一 session，不再解析 latest。本 test-only 精简候选不打包旧的 `package/build-manifest.json.gz` 与 `package/prepare.mjs`（历史审核副本，固定 0.12.9，既不是 latest 运行时，也不是信任锚）；旧版“从随包固定清单执行 prepare”的兼容方式不再提供。实际 prepare 必须来自本次 session 验证通过的完整 npm 包。需要 Node 22、可用 npm Sigstore 支持及 Python 3；任何能力不足均停止。

## 硬规则（先读，任何一步都不例外）

1. **不伪造回执**：每一步只汇报平台/命令真实返回的状态与非敏感错误码；先剔除凭据、口令、请求头、分享链接及其他敏感内容，不加工成"应该成功了"。
2. **不代点弹窗**：平台发布/费用/授权确认框由商家本人点击；技能只说明弹窗含义（费用/额度以弹窗显示为准），不催促、不代确认。
3. **半公开凭据不输出**：平台回执里的 publishableKey、token 等凭据字段不贴出、不记录、不转述；只使用应用标识与公网链接这类公开字段。
4. **配额不足立即停止**：回执出现配额/云服务不可用信号（如 `cloud_service_unavailable`、`useLocalImplementation: true`）时，如实说明并停止；**不做任何本地兜底实现**，不代商家清理或升级配额。
5. **摘要或来源不符停止**：本次锁定的 tarball SHA-512、签名身份、来源提交、包内 manifest 或安装副本任一不符时停止；不得重新解析 latest、更换源或版本绕过。
6. **发布失败安全上报**：当前会话明确提供的 WorkBuddy 发布工具失败时，上报真实状态、非敏感错误码及脱敏说明，**不修改部署包内容重试**（尤其不许改 `cloud.config.json` 的 origin）；商家决定后续。
7. **秘密只由商家本人处理**：一次性管理员口令、配对码、token、密钥或验证码不得读入模型上下文、复制到对话、日志、文件或摘要。若命令会把秘密输出到模型可见的 stdout，或不能确认输出仅呈现给商家本人，停止该操作；引导商家在其本人可见的安全终端/工作台直接查看并录入，助手不读取、不转述。
8. **不承诺免费或 7×24**：费用以平台弹窗为准；不说"永久在线"。约 3 秒冷启动仅为历史观察，不保证适用于当前版本或平台状态。
9. **上线判断只认工具**：只有当前会话真实提供且调用成功的 Kiwi Catalog 状态查询显示 `card.published` 且 `presence=fresh` 才能说"已上线，采购方可以发现你并发来询价"；工具不可用或结果不符时如实说明卡点。
10. **不读取、不转述配对码**：Catalog 配对码由商家本人在工作台与授权页两处核对；配对码和链接都不是授权凭证。

## 第 0 步：执行前检查

**先核对商家的 WorkBuddy 套餐与 A2A 开通状态**：Kiwi 商家 A2A 接入需要 WorkBuddy 企业版；个人版（包括体验版及其他个人套餐）不包含 A2A。此处检查的是账号/组织的套餐，不是客户端应用版本号。只使用当前会话实际提供的官方账号或组织套餐信息；如没有可靠的只读信息，请商家本人在官方账号/企业管理后台查看套餐，或联系 WorkBuddy 客服确认。不要推断、索取账号密码或让商家粘贴密钥。

- **个人版**：明确说明需升级至企业版才能使用商家 A2A 接入，引导商家通过 WorkBuddy 官方企业版购买/联系入口了解具体套餐、费用和开通流程；由商家本人决定购买并完成确认。在确认企业版和必要开放能力之前，停止本技能的部署与上线，不宣称可以接待采购询价。
- **套餐未知**：请商家先确认；不得把工具存在或网站发布成功当作企业版权益证明，暂不进入 A2A 部署。
- **企业版**：仍需企业管理员按平台实际流程在管理后台开放平台创建应用、配置 Client Credentials 并在目标 Agent 开启 A2A；凭证由管理员在安全界面处理，不进入对话、模型输出或日志。确认真实可用能力后才继续。
- **目录分享码代管/分发**：企业版不等于获准第三方目录代管或分发分享码；该许可仍待产品侧书面确认，确认前不要操作或引导商家使用该能力；不得把运营总开关默认启用视为平台许可或商家授权，也不作为 A2A 已可上线的依据。

1. **确认账号已连接**：先确认商家已连接 Kiwi 商家账号（有 `kiwi_catalog_get_merchant_profile` 时调用确认；没有则询问商家是否已连接，未连接先走注册开通，再回来部署）。
2. **检查会话工具**：检查当前会话真实工具清单与参数；缺少必要能力就停止该步骤并说明，不猜工具、不改用其他平台的发布工具。工具存在但参数/回执与下述步骤对不上时，以平台实际为准并如实记录差异。
3. **检查本地能力与信任链**：确认 Node、npm、Python 和可信来源验证支持；不得读取用户 npm 凭据或执行安装脚本。缺失时停止。已有服务升级需查明此前已验证版本、应用身份和数据恢复能力；未知时停止，不能跳过防降级。
4. 预检始终返回 `executionAuthorized:false`。本地 stage→verify 与合成运行健康结果不构成授权凭据；只有宿主路径、真人确认、数据安全与发布流程正式验收后，才可重新评估真实执行门。

## 首次开通流程（严格按序）

### 1. 取包并校验摘要

仅在隔离的本地测试目录调用预检入口，绝不在含商家凭据或真实发布目录运行。执行前需确认脚本所在目录与 node、npm、python 的绝对路径，并由可信环境提供干净 PATH；不读取或输出密钥：

```sh
node <技能目录>/scripts/cloud-session-cli.mjs stage --parent <独立私有测试目录> --node <node绝对路径> --npm <npm绝对路径> --python <python3绝对路径> --previous <已核验旧版本或 initial>
```

仅在可靠核实账号中不存在既有应用时，可将 `--previous` 设为 `initial`；已有应用须提供已核验旧版本，无法核实则停止。该参数只是操作声明，不是应用不存在的证明。`stage` 仅查询一次 latest，锁定具体版本与摘要；metadata 查询保持 20 秒超时，锁定 tarball 下载使用 120 秒超时且最大 128 MiB；两步均验证来源/字节，下载时禁用安装脚本并核验云包文件清单与安装副本。超时即停止，不换源、版本或自动重试。返回的 sessionDirectory 是测试会话路径；继续前用以下命令复验该会话，不允许重新解析 latest：

```sh
node <技能目录>/scripts/cloud-session-cli.mjs verify --session <sessionDirectory> --node <node绝对路径> --npm <npm绝对路径> --python <python3绝对路径>
```

任何 `HOLD`、签名/摘要不符、回退、超时、依赖缺失或会话身份异常均停止，不自动换版本或重试。**本候选绑定的 0.12.15 stage→verify 已通过；0.12.14 合成启动健康结果不代表 0.12.15 启动。** `executionAuthorized:false` 仍有效；真实发布前仍需验证 WorkBuddy 宿主、云端运行、身份与数据保全，并取得用户本人审批。

若预检阶段返回 `ISOLATED_INSTALL_FAILED`，本地私有预检目录可能额外保留 `npm-install-diagnostic.json`。它只包含固定 `INSTALL` 阶段/类别、白名单 errno、数值退出码、白名单 signal 与 timeout 标记；用于区分安装失败类型。不得读取或转述 npm 原始日志、stdout/stderr、URL、命令参数或凭据；仍按上面的规则停止，不换版本、不自动重试。

### 2. 首次发布：取得公网地址

- 先固定一个专用于「Kiwi商家接待」的**发布目录**；第 1 步的 tarball、解包目录和随后生成的临时目录都放在它的外面。第一次发布可在这个发布目录放仅用于取址的最小启动文件（`index.js` 与 `package.json`，不含商家数据或凭据）。记下本次发布实际使用的目录绝对路径。
- 调用 当前会话明确提供的 WorkBuddy 发布工具 做**第一次发布**，目的是取得公网地址——prepare 需要 `--origin`，而地址只有发布后才知道。
- 从回执记录**公网地址**（形如 `https://xxx.app.workbuddy.host`）与**应用标识**（applicationId/siteId 等，以回执实际字段为准），并贴给商家。
- 发布确认/费用弹窗由**商家本人**点击；配额/云服务不可用 → 按硬规则 4 停止。
- **回执失联保护（T009）**：发布报错导致拿不到地址或应用标识时，先与商家核对账号里是否已出现「Kiwi商家接待」，确认不存在后才允许再次创建，防止重复建应用。
- V1 遗留待确认点（如实向商家转述，不自行假设）：回执是否返回**稳定**的应用标识、能否**复用同一应用重新发布**（升级不换域名、状态目录保留）。回执不含稳定标识时，如实说明并请商家在平台面板核对后再继续。

### 3. prepare：生成部署目录

```sh
node <sessionDirectory>/node_modules/@harrylabsj/kiwi-merchant-cloud/prepare.mjs --origin <第 2 步公网地址> --out <部署目录绝对路径> --admin-bootstrap
```

- `--origin` 必须逐字符等于第 2 步回执的公网地址（prepare 自身会拒绝非 https / 带路径的 origin）。`--out` 要选发布目录之外的**新空目录**：`prepare.mjs` 会拒绝非空目录，不能直接写进已用于首次发布的目录。
- 可选：`--merchant-name <商家显示名>`（缺省写入占位名，工作台会提示商家补设）；`--catalog-url` 缺省即生产 Catalog 地址，不要改。
- 若输出不含秘密，核对 JSON 回执中的摘要与版本和本次锁定 session 的版本及 manifest 聚合摘要一致，不一致 → 停止。若输出含秘密，商家本人在安全界面核对，并只提供非敏感的 `deployment_dir`、`artifact_sha256`、`version`；不可读取完整输出。
- 若 `--admin-bootstrap` 会将口令写入 stdout，助手不得运行或读取该命令输出；改由商家本人在安全终端/工作台直接完成，无法隔离时停止。

### 4. 同一应用再次发布

- 核对 prepare 的回执与文件后，将部署目录中的内容（包括首登所需、仅含派生验证材料的 `admin-bootstrap.json`）复制进第 2 步**同一个发布目录**，覆盖取址用的 `index.js` 与 `package.json`；不要把 tarball、口令明文、私有状态目录或取包临时文件复制进去。第二次调用 当前会话明确提供的 WorkBuddy 发布工具 时使用第 2 步记下的**同一个目录绝对路径**与**同一应用**。历史实测发现换本地目录会新建另一应用，即使指定旧 `applicationId`；当前工具若无法明确保证复用，停在第二次发布前核对，不凭应用名称或参数猜测。
- 失败 → 上报真实状态、非敏感错误码及脱敏说明并停止（硬规则 6）。
- 成功 → 贴回执关键字段；核对公网地址与第 2 步一致，不一致 → 停止并如实报告。

### 5. 自检（对公网地址发 GET，用 Bash curl）

```sh
curl -sS -o /dev/null -w '%{http_code}\n' <origin>/livez
curl -sS <origin>/readyz
curl -sS <origin>/.well-known/agent-card.json
```

- `/livez` → HTTP 200。
- `/readyz` → HTTP 200 且 `ready:true`。注意：**尚未导入商品且未完成 Catalog 绑定时 products 检查不通过属预期**（D4：空商品起步、绑定前不报价）；此时服务已在运行，应引导商家先到工作台导入商品、再到 Catalog 授权，之后系统自动重试服务检查。其他检查（identity/storage/policy）失败 → 上报真实状态、非敏感错误码及脱敏说明并停止。
- `/.well-known/agent-card.json` → HTTP 200 且 `url` 字段严格等于公网地址。
- 历史上观察到空闲回收后首个请求可能变慢，但当前表现以实际探测为准；可稍候重试，仍失败 → 上报真实状态、非敏感错误码及脱敏说明并停止，不谎报成功。

### 6. 引导商家完成两处本人确认

1. **工作台**：商家用一次性口令登录 `<origin>/admin/login`，登录后打开 `<origin>/merchant/`（工作台首页，商品与导入在此）。先导入商品，再查看配对入口；若无开通记录、配对码或 Catalog 授权入口，如实报告连接流程尚未启动并停止该步骤，不猜测授权链接、不把商品列表数量当作绑定结果。你不读取、不转述配对码。
2. **Catalog**：商家打开 Catalog 授权页，核对两处配对码一致、公开预览无误，**亲自**点击「连接此服务并发布」。

### 7. 上线核对

- 若当前会话实际提供经确认的 Kiwi Catalog 状态查询工具，则调用该工具：`card.published` 且 `presence=fresh` 才宣布已上线（硬规则 9）。
- 工具不可用（连接器未提供）→ 如实说明无法自动核对，请商家在 Catalog 页面自查，不得宣称已上线。

## 分享码（WorkBuddy 平台门禁）

平台分享码流程仅在平台已确认允许该用途且商家本人明确授权时使用；当前第三方目录代管/分发许可仍待书面确认，确认前不得引导使用。以下保留现有操作说明供后续核验。

- **登记方式**：商家登录云端工作台 →「WorkBuddy 分享码（平台门禁）」卡片 →
  粘贴平台给的**分享链接** → 提交。目录会在后台带码做一次持钥挑战，通过后状态变
  「已生效」。本卡片不会显示分享码，也不要向商家索要或转述它。
- 已生效后可「刷新状态」「撤销」；撤销后采购方经平台网关无法访问本店。
- 分享链接只能由商家本人在受支持的安全界面处理；不要要求粘贴到模型对话、命令、环境变量或日志。平台许可未确认前，不引导登记或分发。
- 失败含义（如实转述，不要自行改配置）：`pending` 等待平台校验；`invalid` 校验未通过
  （常见原因：链接来自另一个应用、分享码已失效）；`revoked` 已被撤销。
- 分享码**不是**商家身份或业务授权；不要把分享链接写进文档、截图、对话记录或总结。
- **历史平台口径（当前有效性需向平台核对，不得自行保证）**：关闭「发布为网站」后链接立即失效；**删除源任务或源文件不会**让已分享链接失效，必须主动下线；平台**不承诺**分享码有固定有效期，也**不承诺**自动轮换；同一应用重新发布后是否换码暂无文档可确认。
- 排障：外部访问 403 而 `/livez` 正常 → 通常是分享码未登记或已失效；先让商家在
  工作台看状态卡片，再按上面含义处理。

## 升级流程（已有云端接待，锁定本次 latest 版本）

云端部署为按需运行：每次首次部署或商家明确要求升级时解析并锁定一次 latest；不维护常驻更新缓存，也不会在应用运行期间自动更换版本。已部署应用需要更新时，由商家再次发起升级；升级前核对原应用、发布目录和数据状态。

1. 第 0 步检查同上（工具、上次已核验版本和本次锁定 session）。
2. 取新版本包并校验（同第 1 步）。
3. **身份保全是升级前置条件**：确认现有应用的商家身份、数据目录和恢复方式，并验证本次锁定的包提供可用、经过验证的原身份保全升级方法。已验证 0.12.14 的 prepare 会生成新 profile，但运行时在状态目录存在有效持久商家身份时会优先使用旧身份，也可从有效旧管理员凭据迁移身份；两者均不存在时会采用新 profile 身份。此结论不自动适用于本次锁定的其他版本。不能假设平台保留了原状态目录或仅凭相同域名证明身份保留，也不能直接覆盖旧应用。若无法证明升级后原身份和数据可保留，停止升级，不调用发布工具。
4. 仅在身份与数据保全方法已验证后，按该方法在独立目录准备；不用 `--admin-bootstrap` 重置既有工作台凭据。确认发布工具能复用原应用和原绑定目录，并由商家确认后才发布；不能证明复用时停止，不创建替代应用。
5. 实际核对应用 ID、域名、商家身份、商品、账本和配对状态；只有逐项核实后才能报告保留。升级期间可能短暂不可用。

## 暂停与恢复

- **暂停名片/接待**：仅在当前产品界面实际提供该操作时引导商家本人确认；这只改变对应产品中的可发现/接待状态，不表示云端实例停止运行或费用停止。
- **平台应用下线**：若当前会话真实提供经确认的 WorkBuddy 下线能力，或商家本人在平台控制台执行下线，按其实际回执说明结果。下线只表示平台应用访问状态改变；不得推断实例已停止、资源已释放或计费已停止。实例停止与费用状态须分别在平台的运行/账单界面核实。
- **恢复**：仅在确认当前发布能力与应用身份后，按平台实际恢复流程操作；不得假设重发会复用应用或恢复原状态。

## 方案 B 兜底（会话没有发布工具时）

第 0 步发现 当前会话明确提供的 WorkBuddy 发布工具 缺失时：

1. 不尝试变通；向商家说明"本会话缺少平台发布工具，改用方案 B：我把一段提示词给你，你在**普通 WorkBuddy 任务**里粘贴运行"。
2. 当前 latest 候选尚未完成宿主和审批验证，不提供可执行的方案 B；如实说明只能进行隔离预检。
3. 商家执行完毕返回本技能会话后，只有当前会话真实列出并确认可用的 Catalog 状态查询工具时才调用核验；否则说明无法自动核验，请商家在 Catalog 界面自行检查，不得宣称已上线。
4. 两条路的规则完全相同：不伪造、不代点、不输出凭据字段、秘密只由商家本人处理，助手不读取、不展示。

## 常见错误

1. 不核对账号里已有应用就再次创建 → 可能产生第二个「Kiwi商家接待」，域名与配对全部错位；发布回执丢失时必须先核对再创建。
2. 把平台回执里的凭据字段当普通字段贴出 → 半公开凭据，绝不输出。
3. 摘要不符时"重新下载试试" → 应立即停止上报，不换源不重试。
4. 发布失败后改 `cloud.config.json` 或删文件再试 → 禁止；如实上报非敏感错误码和脱敏说明。
5. 一次性口令展示后再次复述或写进总结 → 违反一次性原则。
6. 自检失败仍宣布上线 → 只有工具确认 `card.published && presence=fresh` 才能说已上线。
7. 承诺免费、7×24 或把应用下线等同于实例停止/停止计费 → 费用、实例和访问状态分别依据当前平台回执核实；约 3 秒冷启动是历史观察，不保证当前适用。
8. 使用旧会话工具名称或能力假设 → 以当前真实工具清单为准，缺失即停止，不借用其他平台工具。