wps-windows-smoke

name	wps-windows-smoke
description	Provision or reuse a local Windows 11 ARM VM as a reusable test harness for validating pi-for-excel inside real China-domestic WPS Spreadsheets. Use when an agent needs to test a specific WPS feature, WPS JSAPI behavior, add-in packaging, China WPS install/login, auth, taskpane boot, workbook operations, or an issue reproduction in real WPS rather than in Excel/Office.js or a browser fallback.

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.
• 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.

.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:

.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:

.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.

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:

.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.
• Build under test: branch/commit, dev URL, WPS version, and whether using personal publish mode or enterprise jsplugins.xml mode.
• Fixture: blank workbook, seeded range, saved workbook path, or exact reproduction file. Keep raw workbook paths and credentials out of logs.
• Action: the exact Pi prompt, tool call, JSAPI snippet, or install/update action that exercises the target feature.
• Expected result: what must visibly or programmatically happen in WPS for the test to pass.
• Evidence: screenshots/video, WinRM command output, taskpane logs, WPS version, publish/install evidence, workbook before/after state, and any failure output.

Use docs/wps-support.md as the current support matrix. If the feature is explicitly unsupported on WPS, a typed unsupported_host_tool failure is the correct pass condition.

Visual proof requirements

Real-client WPS verification must produce at least one visual artifact from the Windows VM. Text logs alone are not enough.

• Capture before/after screenshots for workbook mutations, taskpane boot, ribbon/install state, and regressions with visible UI symptoms.
• Prefer a final screenshot where the relevant UI is unobstructed (close popups/taskpanes if they hide the proof).
• For flows where timing matters (install prompts, crash/restart loops, modal handoffs), capture a short video or a sequence of screenshots.
• Store proof artifacts under ~/VMs/wps-win11/ or /tmp with descriptive names, and report the paths in the result.
• Do not commit screenshots/videos that expose tokens, private workbook data, local credentials, or customer data.

Screenshot helper:

VM=~/VMs/wps-win11
VNCDOTOOL="$VM/.venv/bin/vncdotool"
[ -x "$VNCDOTOOL" ] || VNCDOTOOL="$(command -v vncdotool)"
"$VNCDOTOOL" -s 127.0.0.1::5907 capture "$VM/<feature>-after.png"

If the capture is black, the Windows display is probably locked/asleep. Wake/unlock the console before treating the capture as evidence; do not rely on a black screenshot. VNC password entry is fragile with keyboard layout differences; if you temporarily enable auto-logon through WinRM on the disposable VM, remove DefaultPassword/ForceAutoLogon and set AutoAdminLogon=0 during cleanup.

General workflow

1. Start VM and confirm WinRM + guest internet:

   .agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh start
   .agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh boot-windows  # 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
   

2. Write the feature-specific test plan above. Avoid broad “prove everything” prompts.
3. Start pi-for-excel dev server on macOS (npm run dev); Vite binds ::/3141 by default.
4. Generate and serve the WPS test add-in with prepare-wps-plugin.mjs --publish --serve. For personal publish-mode VM work, set --plugin-url http://127.0.0.1:3889/ and configure Windows portproxy:

   netsh interface portproxy delete v4tov4 listenaddress=127.0.0.1 listenport=3889 2>$null
   netsh interface portproxy add v4tov4 listenaddress=127.0.0.1 listenport=3889 connectaddress=10.0.2.2 connectport=3889
   

5. In Windows, open http://127.0.0.1:3889/publish.html in Edge and install the WPS add-in. Use this personal publish flow before trying jsplugins.xml. If Edge asks to open WPS Office, allow it, refresh the page after the relay starts if rows do not populate, click the PiForExcelSmokePublish install row, then approve the WPS trust modal (信任并安装). Do not treat a direct WinRM POST to http://127.0.0.1:58890/deployaddons/runParams as equivalent; it can hang/skip the user trust path and does not prove product installability.
6. After install, verify publish.xml and authwebsite.xml contain the same origin (http://127.0.0.1:3889). If WPS later writes authaddin.json with enable:false, or creates jsaddinblockhost.ini after a forced edit, record that as the current WPS trust/action blocker rather than manually overriding it in a proof run. This blocker has reproduced even after logging into a WPS account and even with a minimal official-style ET add-in whose OnAction only calls alert('MIN_ACTION_FIRED'), so do not keep debugging Pi taskpane/auth code or personal-account login until enterprise/WPS 365 managed deployment or another WPS-supported approval path is tested.
7. Launch direct Spreadsheets (et.exe) rather than the WPS home shell if the home/login webview crashes.
8. Confirm the baseline environment is valid:
   • for product-level tests, the taskpane loads the real Pi app from http://10.0.2.2:3141/src/taskpane.html
   • for low-level probes, the taskpane URL is clearly recorded as a custom probe URL and the result is not described as Pi sidebar/agent proof
   • host kind resolves to WPS, not Office/browser, when the real Pi app is under test
   • the Pi ribbon tab and Open Pi button are visible
   • the target add-in build/commit is the one under test
9. Execute only the feature-specific action from the plan. Examples:
   • Packaging/install: reinstall via publish.html, inspect WPS publish/install state, verify the Pi ribbon appears after WPS restart.
   • Taskpane boot: open Open Pi, capture taskpane load/console state, verify no boot-time compatibility error.
   • Host detection: ask Pi or inspect logs to verify WPS host selection and workbook context, without mutating the workbook.
   • execute_wps_js: in the real Pi sidebar, run a minimal JSAPI snippet that reads workbook/sheet metadata or performs the specific mutation under test, then verify the returned JSON.
   • Workbook tool support: in the real Pi sidebar, seed only the range needed, call the relevant typed tool/prompt, and verify workbook state with WPS UI or execute_wps_js readback.
   • Unsupported tools: deliberately invoke the unsupported WPS path and confirm a typed unsupported_host_tool error, not an Office.js fallback.
   • Auth/model flow: verify provider setup and a small prompt response without exposing tokens or local credential paths. State whether this was a fresh OAuth login or dev auth restore via /__pi-auth.
   • Regression reproduction: reproduce the exact issue steps first, then rerun after the fix with the same fixture.
10. Capture evidence tied to the target feature. Include at least one screenshot or video plus a text log/command output. For chat-driven writes, capture both the prompt visible in the real composer and the final selected cell/formula bar. Include residual risks or gaps instead of calling unrelated behavior “covered.”

Historical evidence from first successful route

These artifacts prove the harness can install and run pi-for-excel in real WPS. They are historical examples only, not the required test scenario for future work.

• ~/VMs/wps-win11/publish-page-cmd-launch.png — Edge publish page opened the WPS Office protocol handler.
• ~/VMs/wps-win11/after-trust-install.png plus WPS publishlist output — add-in installed through the WPS relay service.
• ~/VMs/wps-click-addin-chevron.png — Pi tab visible with Open Pi.
• ~/VMs/wps-taskpane-after-randomuuid-patch.png — taskpane initialized in real WPS after the WebView compatibility patch.
• ~/VMs/wps-after-format-prompt-settle.png — the first authenticated agent write/formatting scenario succeeded in the workbook.

WPS install/account notes

• Official ARM installer found during first setup: platform WPS Windows-on-ARM card, version 12.1.0.26200.
• Generic wps.cn bootstrapper may be x86/x64 or network-dependent; prefer the full ARM installer when testing on Windows ARM.
• wps.cn login may show ERR_INTERNET_DISCONNECTED until VirtIO networking is fixed.

Cleanup

.agents/skills/wps-windows-smoke/scripts/wps-win11-vm.sh stop
kill "$(cat /tmp/pi-wps-smoke-plugin-3889.pid)" 2>/dev/null || true
pkill -f 'vite --port 3141' 2>/dev/null || true

Keep screenshots/logs under ~/VMs/wps-win11/ or /tmp; do not commit VM credentials, ISOs, qcow2 disks, WPS installers, or screenshots that expose tokens/private workbook data.