# YINIAN Desktop Pilot QA

> Updated: 2026-04-26  
> Scope: M1/M2 pilot demo package for B-end business desktop flow

## 1. Pilot Scope

This pilot validates the desktop product loop that is already implemented:

- Login-first YINIAN entry.
- Session restore and logout cleanup.
- Single workspace/service context in the sidebar.
- Customer-facing sidebar focused on the service Dashboard card, `快速使用`, `对话`, and `设置`.
- Knowledge Base v0 upload/list/search surface.
- Service-managed model/Agent/channel/schedule configuration notice in Settings.
- Config sync in mock or HTTP mode.
- Today operations cockpit.
- Workspace-scoped local skill registry.
- Skills Manager sync/status flow.
- Gateway start after authenticated workspace context.
- Legacy ClawX/OpenClaw compatibility in E2E mode.

Out of scope for this pilot:

- Real skill bundle download.
- Signature verification and unpacking.
- Real OTA/PMS task execution.
- Real payment, provisioning, or account administration.
- Customer-specific branding beyond current YINIAN visual system pass.

## 2. Environment Modes

### Mock Mode

Default mode. Do not set `YINIAN_API_BASE_URL`.

Use this for product walkthroughs, local QA, and stakeholder demos before the NIANXX server is ready.

### HTTP Mode

Set `YINIAN_API_BASE_URL` to enable server-backed control plane calls:

```bash
YINIAN_API_BASE_URL=https://api.example.com pnpm run dev
```

HTTP mode expects the contract documented in `docs/SERVER_CONTRACT_V0.md`.

### E2E Compatibility Mode

Playwright uses `CLAWX_E2E=1` through test fixtures. In this mode, legacy ClawX setup/main flows stay available so inherited regression tests remain meaningful.

## 3. Demo Script

Use mock mode unless the server is explicitly being validated.

1. Start the app:

   ```bash
   pnpm run dev
   ```

2. Confirm first screen is YINIAN login.

3. Login with mock SMS credentials:

   - Phone: `13800000000`
   - Code: `123456`

4. Confirm the app lands on `/today`.

5. Review Today cockpit:

   - Service name and login user are visible.
   - Clicking the sidebar service card returns to Today/Dashboard.
   - Application readiness cards render.
   - Status queue explains app sync/update/failed states.
   - Application status board merges server entitlements and local registry.

6. Open `/skills`.

7. Confirm Skills Manager:

   - Entitlement count is visible.
   - Local registry count is visible.
   - Empty registry warning appears before sync when relevant.
   - Each skill explains its current state.

8. Click `同步 Skills`.

9. Confirm:

   - Sync completes without leaving the page.
   - Skill cards update to installed/skipped/updated states.
   - Today page reflects local registry status after returning.

10. Open `知识库`.

11. Confirm:

   - Upload entry is visible.
   - Empty state is readable before upload.
   - Search and document list area are present.

12. Hover `历史会话`.

13. Confirm:

   - History popover opens.
   - Clicking `历史会话` opens the latest session when history exists, otherwise opens Chat.

14. Open Settings.

15. Confirm:

   - `账号与组织` shows the current service and user.
   - `同步组织配置` refreshes config for the current service.
   - Model, Agent, channel, and scheduling-policy configuration are shown as server-managed capabilities.
   - Today and Skills stay scoped to the same workspace context.

16. Click Settings `退出登录`.

13. Confirm:

   - App returns to `/login`.
   - Current workspace config and local registry context are cleaned for the logged-out session.

## 4. QA Checklist

### Auth And Session

- [ ] Login succeeds in mock mode.
- [ ] App restores a valid mock session after relaunch.
- [ ] Logout returns to `/login`.
- [ ] Logout clears current workspace config and current business skill registry context.
- [ ] HTTP mode restore calls `/auth/refresh` when a persisted refresh token exists.
- [ ] HTTP mode does not persist access tokens.

### Workspace Context

- [ ] Sidebar service context appears only after authentication.
- [ ] No workspace switcher is visible in the product shell.
- [ ] Settings sync refreshes config for the current service.
- [ ] Today and Skills stay scoped to the current workspace registry.

### Sidebar And Settings IA

- [ ] Production sidebar service card opens Today/Dashboard.
- [ ] Production sidebar quick-use area shows `Skills`, `定时任务`, and `知识库`.
- [ ] Chat area shows `新对话` and `历史会话`.
- [ ] Hovering `历史会话` reveals the history popover.
- [ ] Models, Agents, Channels, and Dev Console are not visible in normal customer navigation.
- [ ] Account logout lives in Settings, not as a primary sidebar action.
- [ ] Settings explains that model/provider strategy, Agent orchestration, channels, and scheduling policy are managed by the service side.

### Knowledge Base

- [ ] Knowledge page opens from the sidebar.
- [ ] Upload button opens the system file picker.
- [ ] Uploaded files appear in the local document list.
- [ ] Search filters the visible document list.
- [ ] Empty state distinguishes "no files yet" from "no search matches".

### Gateway Boundary

- [ ] Gateway does not start before login in production mode.
- [ ] Gateway starts once after authenticated workspace context exists.
- [ ] `CLAWX_LEGACY_AUTOSTART=1` restores the old ClawX startup behavior for debugging.
- [ ] E2E compatibility mode keeps legacy setup and Chat defaults available.

### Today

- [ ] Today renders without config errors after login.
- [ ] Empty states are visible when there are no pending items, skills, or actions.
- [ ] Skill status labels are clear:
  - `已开通未同步`
  - `已安装`
  - `已更新`
  - `已是最新`
  - `有更新`
  - `已禁用`
  - `同步失败`
- [ ] Refresh button updates config without triggering duplicate gateway starts.

### Skills Manager

- [ ] Empty entitlement state appears when an organization has no opened skills.
- [ ] Empty local registry state is distinct from no entitlements.
- [ ] Sync first install marks skills as installed/updated.
- [ ] Syncing the same manifest again marks same-version skills as skipped.
- [ ] Failed sync surfaces an error and retry affordance.
- [ ] Disabled entitlements cannot run.
- [ ] Version drift is shown as `有更新`.

### Visual System

- [ ] Login, Today, Skills, and sidebar feel like one product.
- [ ] Primary actions use the YINIAN navy treatment.
- [ ] Status colors are restrained and readable.
- [ ] Panels use 8px radius or less.
- [ ] Text does not overflow buttons, cards, or status badges at common desktop widths.
- [ ] No marketing-style hero page appears after authentication.
- [ ] Visual smoke screenshots are refreshed for Login, Today, Skills, Knowledge, and Settings.

## 5. Verification Commands

Run this full gate before a guided demo:

```bash
pnpm run typecheck
pnpm run test
pnpm run build:vite
pnpm run test:e2e
```

Last known green verification:

- Typecheck: passed.
- Unit tests: 89 files, 572 tests passed.
- Vite build: passed.
- E2E: 26 passed, 1 skipped.
- Visual smoke: Login, Today, Skills, Knowledge, and Settings passed.

Known non-blocking warnings:

- Vitest `MaxListenersExceededWarning`.
- Vite dynamic/static import chunk warnings.
- Vite large chunk warning.
- Playwright/Electron `NO_COLOR` ignored because `FORCE_COLOR` is set.

## 6. Packaging Notes

For local macOS pilot packaging, prefer:

```bash
pnpm run package:mac:local
```

This skips preinstalled skills and is more suitable for a fast local artifact. Full release packaging should use the platform-specific `package:*` scripts after dependency and signing decisions are settled.

Do not treat the current pilot build as production-ready until:

- Real server auth is validated end to end.
- Real bundle download and signature verification are implemented.
- The installer signing/notarization path is finalized.
- Customer-specific privacy and logging requirements are reviewed.

## 7. Known Issues And Product Gaps

- Today uses config and local registry as its data source; real PMS/OTA/task data is not connected yet.
- Skills sync consumes manifest metadata only; it does not download, verify, or execute real bundles.
- Knowledge Base v0 is local UI state only; persistence, indexing, permissions, and service sync are not connected yet.
- HTTP control plane contract is still draft v0.
- Device identity is still a placeholder and should become a stable installation id.
- Legacy ClawX configuration pages remain available for compatibility/E2E routes, but should stay hidden from production customer navigation until an admin/developer mode is explicitly designed.
- Bundle size warnings remain from the inherited app structure.