kiwi-cloud-deploy

Files (5)

• SKILL.md
• build-manifest.json · package/
• prepare.mjs · package/
• fallback-prompt.md · references/
• release.json · references/

SKILL.md (first lines)

# Kiwi 云端接待部署

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

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

实测边界（2026-09-30）：正式云包 0.12.0 已在普通 WorkBuddy 任务完成首次取址、同目录二次发布、公网存活检查和工作台首登。Catalog 绑定、名片发布、买家询价与带业务数据升级保留尚未完成端到端验收；不得把部署成功称为完整上线。

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

## 随包资源与执行目录

技能包附带 `package/build-manifest.json` 和 `package/prepare.mjs`，均为 `references/release.json` 固定版本 npm 正式包中的原始文件，用于审核、查阅和比对。这两个文件不是完整运行时，不得从技能安装目录直接执行 prepare。实际部署必须先按第 1 步下载并解压完整 npm 包，在独立取包目录中校验后执行；下文命令的 `package/` 均指该取包目录下解压得到的完整目录。不得把这两个审核副本当作完整部署包。

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

1. **不伪造回执**：每一步只汇报平台/命令真实返回；成功、失败原文照贴，不加工成"应该成功了"。
2. **不代点弹窗**：平台发布/费用/授权确认框由商家本人点击；技能只说明弹窗含义（费用/额度以弹窗显示为准），不催促、不代确认。
3. **半公开凭据不输出**：平台回执里的 publishableKey、token 等凭据字段不贴出、不记录、不转述；只使用应用标识与公网链接这类公开字段。
4. **配额不足立即停止**：回执出现配额/云服务不可用信号（如 `cloud_service_unavailable`、`useLocalImplementation: true`）时，如实说明并停止；**不做任何本地兜底实现**，不代商家清理或升级配额。
5. **摘要不符停止**：npm integrity 或包内聚合摘要与 `references/release.json` 固定值不一致时，停止并如实报告两边的值；不换源、不换版本重试。
6. **发布失败贴原文**：当前会话明确提供的 WorkBuddy 发布工具 失败原样上报，**不修改部署包内容重试**（尤其不许改 `cloud.config.json` 的 origin）；商家决定后续。
7. **秘密只由商家本人处理**：一次性管理员口令、配对码、token、密钥或验证码不得读入模型上下文、复制到对话、日志、文件或摘要。若命令会把秘密输出到模型可见的 stdout，或不能确认输出仅呈现给商家本人，停止该操作；引导商家在其本人可见的安全终端/工作台直接查看并录入，助手不读取、不转述。
8. **不承诺免费或 7×24**：费用以平台弹窗为准；不说"永久在线"。约 3 秒冷启动仅为历史观察，不保证适用于当前版本或平台状态。
9. **上线判断只认工具且必须分层**：只有当前会话真实提供且调用成功的 Kiwi Catalog 状态查询显示 `card.published` 且 `presence=fresh` 才能说"名片已发布、心跳正常"；这只证明连接/名片/心跳，不能证明买家搜索命中或询价成功。买家搜索与询价回执未实测时写"未验证"。工具不可用或结果不符时如实说明卡点。
10. **不读取、不转述配对码**：Catalog 配对码由商家本人在工作台与授权页两处核对；配对码和链接都不是授权凭证。

## 第 0 步：执行前检查

1. **确认账号已连接**：先确认商家已连接 Kiwi 商家账号（有 `kiwi_catalog_get_merchant_profile` 时调用确认；没有则询问商家是否已连接，未连接先走注册开通，再回来部署）。
2. **检查会话工具**：检查当前会话真实工具清单与参数；缺少必要能力就停止该步骤并说明，不猜工具、不改用其他平台的发布工具。工具存在但参数/回执与下述步骤对不上时，以平台实际为准并如实记录差异。
3. **检查发布参数**：读取 @references/release.json。若 `package_version`、`aggregate_digest`、`npm_integrity` 仍为 `{{…}}` 占位，说明发布参数尚未回填：停止实际部署，向商家如实说明"云端接待的发布参数尚未就绪，暂时只能讲解流程"，并讲解下面各步骤。
4. 读取回填后的 release.json 三个值备用；npm 不可用（`npm --version` 失败）也如实停止。

## 发布前闸门：目标运行环境 Node（安装与覆盖部署之前必须）

本机 `node --version` 只说明取包机器，**不是** WorkBuddy 云端应用的运行时证据；平台沙箱的 Node 版本可能不同（历史实测出现过低于包要求的情况）。因此：**任何安装、以及任何会覆盖已有应用的再次发布之前**，必须先核实平台侧实际安装与启动所用的 Node 版本，闸门未通过（exit ≠ 0）不得发布。

1. **只接受可信只读证据**：平台只读界面/发布回执的原文（`platform-readonly`），或商家在平台侧确认的运行时配置（`runtime-config`）。本机版本、助手推断、自动探测、猜测一律不作数。平台没有只读接口时，本步骤无法核实——**停止发布**，请商家在平台侧查看运行时或联系平台确认/开单，并如实说明"无法自动核实"。
   **手填/转录的证据不具备平台真实性证明**：脚本只校验证据的字段形状、来源类别与新鲜度，**不认证**其内容确实来自平台。必须由助手本人从平台只读界面或可信回执核验来源，并在部署记录中写明来源界面与观察时间；无法核验来源时按"未知"处理并停止。不得对外宣称"脚本已认证来源"或"平台已确认版本"。
2. 把证据写入 `<部署证据>/target-runtime.json`（格式 `kiwi.deploy-target-runtime/1`，含 `install_node`、`start_node` 与 `evidence.interface/observed_at/quote` 原文摘录；摘录只贴版本行，不含凭据）。
3. 发布前运行闸门：

```sh
node <技能目录>/scripts/verify-target-node.mjs \
  --package-json <解包目录>/package/package.json \
  --evidence <部署证据>/target-runtime.json
```

4. 按错误码处理（全部为停止，不得跳过）：

| 错误码 | 含义 | 可操作提示 |
|---|---|---|
| `DEPLOY_TARGET_NODE_UNKNOWN` | 缺少/无法取得平台侧证据 | 请商家在平台应用设置里查看运行时，或联系平台确认后重试；不得用本机版本代替 |
| `DEPLOY_TARGET_NODE_UNSUPPORTED` | 目标 Node 低于包要求（当前 `>=22.19.0`） | 先在平台侧升级运行时到 22.19.0+，升级前不得安装或覆盖发布 |
| `DEPLOY_TARGET_EVIDENCE_UNTRUSTED` | 证据来源不可接受（本机/推断/自动探测） | 重新在平台侧只读取证 |
| `DEPLOY_TARGET_EVIDENCE_STALE` / `_INVALID` | 证据过期或格式错误 | 重新取证（默认 24h 内） |

5. 首次仅用于取公网地址的最小发布不安装运行时依赖，但**任何覆盖已有应用的再次发布与任何安装之前**都必须先过闸门；闸门通过的证据随本次部署记录保留。

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

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

仅当商家本人操作环境提供 npm 且商家明确执行时，按会话可见说明校验固定版本（`<版本>` 取 release.json 的 `package_version`）：

```sh
mkdir -p kiwi-cloud-deploy-work
cd kiwi-cloud-deploy-work
npm pack @harrylabsj/kiwi-merchant-cloud@<版本>
tar -xzf harrylabsj-kiwi-merchant-cloud-<版本>.tgz
```

- npm 下载自带完整性校验；另执行 `npm view @harrylabsj/kiwi-merchant-cloud@<版本> dist.integrity` 取 registry 侧 sha512 integrity，与 release.json 的 `npm_integrity` 比对，不一致 → 停止（硬规则 5）。
- 读取解压出的 `package/build-manifest.json` 中的 `artifact_sha256`，与 release.json 的 `aggregate_digest` 比对，不一致 → 停止并报告两边的值。
- **轻量发布包不随包携带 `node_modules`**：包内只有程序、`package.json`、`package-lock.json`、校验清单与安装脚本。第三方依赖由部署环境按锁文件执行 `npm ci --omit=dev` 下载安装（`prepare.mjs` 默认完成），不要求发布包含依赖。
- npm pack 失败（网络、版本未发布等）→ 贴报错原文并停止。**禁止**：`curl | sh`、拉取源码现场构建、用 `npm install` 或手工改版本现场解析依赖。安装必须走包内 `package-lock.json` 的 `npm ci`，并核对安装版本与 lock 一致。

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

- 先固定一个专用于「Kiwi商家接待」的**发布目录**；第 1 步的 tarball、解包目录和随后生成的临时目录都放在它的外面。第一次发布可在这个发布目录放仅用于取址的最小启动文件（`index.js` 与 `package.json`，不含商家数据或凭据）。记下本次发布实际使用的目录绝对路径。
- 调用 当前会话明确提供的 WorkBuddy 发布工具 做**第一次发布**，目的是取得公网地址——prepare 需要 `--origin`，而地址只有发布后才知道。首次取址不安装运行时依赖，**不需要** Node 闸门；但这一步之后、任何覆盖该应用的再次发布或任何安装之前，必须按「发布前闸门」章节先核实平台侧 Node 版本。
- 从回执记录**公网地址**（形如 `https://xxx.app.workbuddy.host`）与**应用标识**（applicationId/siteId 等，以回执实际字段为准）。转述给商家时**必须写全工作台路径**：商家工作台入口是 `<公网地址>/merchant/`，登录页是 `<公网地址>/admin/login`；裸根路径 `/` 没有页面（源站返回 404，2026-10-31 实测），不得把裸地址或平台分享链接原样当作商家入口。平台分享链接（带 `?sharecode=` 参数）用于通过网关：浏览器打开时保留该参数；网关可能校验后剥除再转发，源站看不到分享码、也不得回显。
- 发布确认/费用弹窗由**商家本人**点击；配额/云服务不可用 → 按硬规则 4 停止。
- **回执失联保护（T009）**：发布报错导致拿不到地址或应用标识时，先与商家核对账号里是否已出现「Kiwi商家接待」，确认不存在后才允许再次创建，防止重复建应用。
- V1 遗留待确认点（如实向商家转述，不自行假设）：回执是否返回**稳定**的应用标识、能否**复用同一应用重新发布**（升级不换域名、状态目录保留）。回执不含稳定标识时，如实说明并请商家在平台面板核对后再继续。

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

```sh
node package/prepare.mjs --origin <第 2 步公网地址> --out <部署目录绝对路径> --admin-bootstrap
```

- `--origin` 必须逐字符等于第 2 步回执的公网地址（prepare 自身会拒绝非 https / 带路径的 origin）。`--out` 要选发布目录之外的**新空目录**：`prepare.mjs` 会拒绝非空目录，不能直接写进已用于首次发布的目录。
- `prepare.mjs` 会在部署目录按包内 `package-lock.json` 执行 `npm ci --omit=dev` 安装第三方依赖，需要可用的 Node/npm 与 registry 网络；安装后逐包核对锁文件版本。`--skip-install` 仅供离线检查，正式部署不得跳过。
- 可选：`--merchant-name <商家显示名>`（缺省写入占位名，工作台会提示商家补设）；`--catalog-url` 缺省即生产 Catalog 地址，不要改。
- 成功时 stdout 打印 JSON 回执（`deployment_dir`、`artifact_sha256`、`version` 等）；核对回执中的摘要与版本和 release.json 一致，不一致 → 停止。
- 若 `--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. 引导商家完成两处本人确认

From harrylabsj/kiwi, Apache-2.0.

More from harrylabsj/kiwi