wps-windows-smoke

Files (4)

• README.md
• SKILL.md
• prepare-wps-plugin.mjs · scripts/
• wps-win11-vm.sh · scripts/

SKILL.md (first lines)

# WPS Windows Test Harness

Use this skill for **feature-specific real WPS Spreadsheets validation** of pi-for-excel. Browser tests and Office.js tests are not enough: WPS does not run Office manifests or Office.js add-ins.

This skill is an environment + workflow harness, **not one fixed smoke test**. Before testing, name the feature or regression under test and choose the smallest WPS workbook action that proves it. Do not use a generic “create and format a table” prompt unless the feature being tested is specifically table-like writing/formatting behavior.

Be explicit about the test level:

- **Product-level Pi for Excel proof** must load the real Pi taskpane (`/src/taskpane.html`) and exercise the actual sidebar/chat UI, auth/model setup, agent loop, tool calls, approvals, workbook updates, and final user-visible result.
- **Low-level WPS JSAPI probes** may use a custom temporary taskpane/page to isolate WPS host APIs, but they are only host-capability evidence. They do **not** prove that the Pi sidebar, agent, auth, or typed Pi tools work for that feature.

## What agents get wrong

- Use **China-domestic WPS** (`wps.cn` / `platform.wps.cn`) first. International `wps.com` builds are not the target and may not expose the documented JSAPI/add-in channel.
- On Apple Silicon, use **Windows 11 ARM64 + qemu-system-aarch64 + HVF**. x86 Windows under emulation is the slow/wrong default.
- Initial Windows ARM networking may look fine from QEMU but fail in the guest. Inbox `e1000e`/USB NICs did not give reliable internet; stage `NetKVM\w11\ARM64\netkvm.inf` from `virtio-win.iso`, then switch QEMU to `virtio-net-pci`.
- QEMU 11.1 on HVF fails to start with `-device tpm-tis-device` (`HV_BAD_ARGUMENT`). `scripts/wps-win11-vm.sh start` therefore boots the installed VM without a TPM; set `WPS_TPM=1` only for Windows setup, on a QEMU version that accepts it.
- Do **not** mount helper/payload/driver ISOs at boot once Windows is installed if EFI starts mapping only the USB device. Boot minimal, then hot-attach ISOs after Windows is up.
- If EFI drops to shell, boot Windows with `FS0:\EFI\Microsoft\Boot\bootmgfw.efi` (sometimes partition numbers shift; inspect the mapping table).
- With QEMU user networking, the Windows guest reaches the macOS host at `10.0.2.2`; do not use guest `localhost` for the real taskpane URL. For the WPS **publish/install page and add-in root** in personal publish-mode tests, prefer a Windows-local origin (`http://127.0.0.1:<port>/`) served inside the guest. Edge pages loaded from `10.0.2.2` may not be able to talk to WPS' local relay at `127.0.0.1:58890`, while pages loaded from guest-localhost can show the real WPS trust prompt. Keep `/src/taskpane.html` on `http://10.0.2.2:3141` so the `/__pi-auth` guest-blocking boundary is still tested.
- Once VirtIO networking works, prefer **WinRM** for all guest commands. VNC typing is fragile, especially with UK keyboard punctuation and passwords containing symbols.
- WPS personal builds `>= 12.1.0.16910` restrict the enterprise/local `jsplugins.xml`/`oem.ini` path. If a direct `jsplugins.xml` registration silently does nothing, use the **`wpsjs publish` publish-page flow** rather than burning time. Do not hand-edit `authaddin.json` as proof: WPS may regenerate `enable:false`, or if forced to `true` may create `%APPDATA%\Kingsoft\wps\jsaddons\jsaddinblockhost.ini` and suppress ribbon actions. The real trust path is the WPS modal headed `是否信任并安装第三方WPS加载项 ...`.
- Ordinary WPS personal-account login does **not** unlock this block in the current Windows ARM WPS `12.1.0.26200` harness. The block reproduces after logged-in trust install with a minimal alert-only add-in and with a clean current official ET template built from `wpsjs@2.2.3` (including `functions.json`). It also reproduces when that official template is served directly inside Windows from a fresh local origin (`http://127.0.0.1:3891/`, no macOS portproxy): the publish row can show `正常`, but WPS still writes `authaddin.enable=false` and later `jsaddinblockhost.ini`. Moving `%APPDATA%\\Kingsoft\\wps` aside and repeating from a fresh WPS profile does not help.
- The 32-bit/x86 WPS 365 build (`12.1.0.26899`, PE machine `I386`) is confirmed to unblock command execution even inside the Windows ARM VM: the official ET sample reaches the in-app first-load trust prompt, writes `authaddin.enable=true`, and fires `OnAction`; the real Pi add-in can show `Pi for Excel`, fire `Open Pi`, and open the real taskpane. If ARM/ARM64EC WPS suppresses actions, switch architecture/build before debugging Pi taskpane/auth code.
- WPS template callback spelling is `OnAddinLoad`; keep the repo's `OnAddInLoad` alias too so either ribbon spelling works. Prefer the official `ribbon.OnAddinLoad` / `ribbon.OnAction` callback namespace in `ribbon.xml`, with global aliases preserved in JS.
- Real WPS requests add-in-root `/index.html`; it must load `main.js`. Do not assume `wpsjs publish` or WPS generates this entrypoint. For narrow 800px VM screens, insert the Pi tab before Home and use a visible label (`Pi for Excel`) so the test can click the real button instead of hunting a clipped custom tab.
- WPS's publish-page validator expects `ribbon.xml` to start with `<customUI`; an XML declaration prefix can make the row show `无效` even when WPS can fetch the file.
- WPS 12.1.0.26200 embeds a WebView with `crypto.getRandomValues` but no `crypto.randomUUID`; keep the app bootstrap compatibility patch installed.
- If `key.pem`/`cert.pem` exist in the repo root, Vite serves HTTPS. The WPS harness examples use plain HTTP (`http://10.0.2.2:3141/...`); use an isolated worktree without those certs, or deliberately test an HTTPS WPS URL with certificate trust handled and record that choice.
- For product-level chat proof, verify the prompt is visibly in the real bottom composer before sending. It is easy in the cramped WPS pane to type into the formula bar, a suggestion card, or the model/thinking selector instead.
- The dev `/__pi-auth` restore path proves credential reuse from Pi's local auth file; it is **not** the same as proving a fresh browser OAuth login from a clean WPS profile.
- The existing `background-verify` bridge is loopback/HTTPS-oriented for local Excel taskpanes; do not assume it can drive a WPS guest taskpane over `10.0.2.2` until a WPS-compatible mode is added.
- Do **not** turn historical evidence into the canonical test. The first successful run used a table prompt, but future runs should test the feature actually under review.

## Local VM conventions

Expected local VM layout from the first successful setup:

- VM dir: `~/VMs/wps-win11`
- Disk: `~/VMs/wps-win11/wps-win11-arm64.qcow2`
- Credentials: `~/VMs/wps-win11/credentials.txt` (`chmod 600`; do not print the password)
- VNC: `127.0.0.1:5907`
- RDP forward: `127.0.0.1:13389`
- WinRM forward: `127.0.0.1:15985`
- Guest host-gateway URL: `http://10.0.2.2:<host-port>/...`

If the VM does not exist yet, create it with official Microsoft Windows 11 ARM64 ISO, QEMU `virt` machine, NVMe qcow2 disk, EDK2 AArch64 pflash vars, `swtpm`, and WinRM/RDP enabled by unattended setup. Keep credentials in the VM dir only.

## Helper scripts

Run scripts from the repo root, or call them by absolute path.

### VM control + WinRM

`scripts/wps-win11-vm.sh` starts/stops the existing QEMU VM, hot-attaches ISOs, waits for WinRM, runs PowerShell, and stages VirtIO NetKVM.

```bash
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh start
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh boot-windows   # only if EFI shell appears
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh wait-winrm 180
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh health
```

If networking is broken and you have the VirtIO driver ISO on the host:

```bash
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh attach-iso ~/Downloads/virtio-win/virtio-win.iso virtioiso
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh install-netkvm
# Then stop, set WPS_NET_DEVICE=virtio-net-pci if needed, and start again.
```

Run guest PowerShell without VNC typing:

```bash
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh ps 'Get-NetAdapter | Format-Table -Auto'
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh ps <<'PS'
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -UseBasicParsing http://10.0.2.2:3141/src/taskpane.html | Select-Object StatusCode,RawContentLength
PS
```

### WPS test add-in packaging

`prepare-wps-plugin.mjs` builds a WPS test add-in root with `index.html`, `ribbon.xml`, `main.js`, `manifest.xml`, and `jsplugins.xml`; patches the taskpane URL to the QEMU host gateway; keeps the WPS callback alias; and can generate `publish.html` via `wpsjs publish`. The default output directory is still named `wps-smoke-plugin` for compatibility with existing scripts and evidence paths; it is not tied to one specific test scenario.

```bash
npm run dev > /tmp/pi-for-excel-wps-vite.log 2>&1 &

.agents/skills/wps-windows-smoke/scripts/prepare-wps-plugin.mjs \
  --taskpane-url http://10.0.2.2:3141/src/taskpane.html \
  --plugin-url http://127.0.0.1:3889/ \
  --publish \
  --serve 3889
```

Verify from the guest before opening WPS:

```bash
.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh ps <<'PS'
$ProgressPreference = 'SilentlyContinue'
@(
  'http://10.0.2.2:3141/src/taskpane.html',
  'http://10.0.2.2:3889/ribbon.xml',
  'http://10.0.2.2:3889/main.js',
  'http://10.0.2.2:3889/publish.html',
  'http://127.0.0.1:3889/publish.html'
) | ForEach-Object {
  $r = Invoke-WebRequest -UseBasicParsing -Uri $_ -TimeoutSec 10
  "$($_) -> $($r.StatusCode) $($r.Content.Length)"
}
PS
```

## Feature-specific test planning

Before launching the full path, write down a compact test plan:

- **Feature/regression under test:** e.g. taskpane boot, provider auth, `execute_wps_js`, `read_range`, an unsupported-tool failure path, a newly implemented WPS tool, or a reported customer issue.
- **Test level:** product-level Pi sidebar/agent proof, or low-level WPS JSAPI host-capability probe. Do not mix these up in the conclusion.

From tmustier/pi-for-excel, MIT.

More from tmustier/pi-for-excel