@mkterswingman/5mghost-wonder 0.0.11 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-wonder",
-  "version": "0.0.11",
+  "version": "0.0.14",
   "description": "企微文档读取 CLI — WeCom document reader",
   "type": "module",
   "engines": {
@@ -25,7 +25,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
-    "test": "node dist/wecom/url.test.js && node --test tests/sheet-parity.test.mjs && node --test tests/export-sanitize.test.mjs && node --test tests/format.test.mjs",
+    "check:skills": "node scripts/check-skills.mjs",
+    "test": "npm run check:skills && node dist/wecom/url.test.js && node --test tests/sheet-parity.test.mjs && node --test tests/export-sanitize.test.mjs && node --test tests/format.test.mjs && node --test tests/cookies-validation.test.mjs",
     "smoke": "npm run build && node dist/cli.js help > /dev/null",
     "postinstall": "node scripts/postinstall.mjs"
   },

package/scripts/check-skills.mjs

@@ -0,0 +1,37 @@
+// scripts/check-skills.mjs
+// Lightweight packaging guard for bundled skills. It verifies that router
+// skills do not point to missing reference files.
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const skillPath = resolve(root, "skills/use-5mghost-wonder/SKILL.md");
+const skillDir = dirname(skillPath);
+const skillText = readFileSync(skillPath, "utf8");
+
+const refs = new Set();
+const referencePattern = /`(references\/[^`]+\.md)`/g;
+let match;
+while ((match = referencePattern.exec(skillText)) !== null) {
+  refs.add(match[1]);
+}
+
+if (refs.size === 0) {
+  throw new Error("use-5mghost-wonder/SKILL.md does not reference any workflow files");
+}
+
+const missing = [];
+for (const ref of refs) {
+  const filePath = resolve(skillDir, ref);
+  if (!existsSync(filePath)) {
+    missing.push(ref);
+  }
+}
+
+if (missing.length > 0) {
+  throw new Error(`Missing use-5mghost-wonder references: ${missing.join(", ")}`);
+}
+
+console.log(`✅ use-5mghost-wonder references OK (${refs.size} files)`);

package/skills/setup-5mghost-wonder/SKILL.md

@@ -7,9 +7,9 @@ description: Use this skill when the user wants to install or set up wonder, say
 
 ## Skill version
 
-This skill matches **wonder 0.0.11**.
+This skill matches **wonder 0.0.14**.
 
-Once the CLI is installed in Step 1, run `wonder --version`. If the output does not equal `0.0.11`, the CLI on disk has drifted from the skill text loaded in this session. Ask the user to run `/update-5mghost-wonder`, then **start a fresh AI session** (`/exit` and re-enter, or open a new chat) — skill text already loaded into a running session does not refresh after `wonder update`, even though the file on disk has been replaced.
+Once the CLI is installed in Step 1, run `wonder --version`. If the output does not equal `0.0.14`, the CLI on disk has drifted from the skill text loaded in this session. Ask the user to run `/update-5mghost-wonder`, then **start a fresh AI session** (`/exit` and re-enter, or open a new chat) — skill text already loaded into a running session does not refresh after `wonder update`, even though the file on disk has been replaced.
 
 After a successful first install, also remind the user to start a fresh AI session before invoking `/use-5mghost-wonder` for the first time. The skill files were just written to disk; the current session never loaded them.
 

package/skills/update-5mghost-wonder/SKILL.md

@@ -7,7 +7,7 @@ description: Use this skill when the user wants to update or upgrade wonder, say
 
 ## Skill version
 
-This skill matches **wonder 0.0.11**.
+This skill matches **wonder 0.0.14**.
 
 ---
 

package/skills/use-5mghost-wonder/SKILL.md

@@ -1,302 +1,70 @@
 ---
 name: use-5mghost-wonder
-description: Use this skill when the user shares a URL containing "doc.weixin.qq.com", mentions 企微文档, 企业微信文档, 在线表格, 腾讯文档, wecom doc, wechat doc, wecom document, or asks you to read a WeCom document. Activate automatically on any doc.weixin.qq.com link.
+description: Use this skill when the user shares a URL containing "doc.weixin.qq.com", mentions 企微文档, 企业微信文档, 在线表格, 腾讯文档, wecom doc, wechat doc, wecom document, asks to read or edit a WeCom document, or asks about Wonder. Activate automatically on any doc.weixin.qq.com link.
 ---
 
-# use-5mghost-wonder — 企微文档读取操作指南
-
-## Skill version
-
-This skill matches **wonder 0.0.11**.
-
-In the Session Initialization step below, after running `wonder --version`, compare the output to `0.0.11`. If they differ, the loaded skill text and the CLI on disk are out of sync. Stop, tell the user to run `/update-5mghost-wonder`, and then **start a fresh AI session** (`/exit` and re-enter, or open a new chat) before trying again. `wonder update` rewrites the skill files on disk, but skill text already loaded into the current session does not auto-refresh.
-
-## Session Initialization (first use only per session)
-
-The **first time** you encounter a WeCom document URL in a session, run these checks before processing the document. Remember you have already done this — do not repeat in subsequent calls within the same session.
-
-```bash
-# 1. Check for updates
-wonder update
-
-# 2. Confirm the CLI version matches this skill's expected version (0.0.11)
-wonder --version
-
-# 3. Check WeCom cookie status
-wonder wecom status
-```
-
-## Cookie refresh behavior
-
-If `wonder wecom status`, `wonder read <url>`, or any WeCom request reports
-that the cookie is expired, missing, invalid, or got 401/403, do not give the
-user a manual cookie-export path. Ask the user whether now is a convenient time
-to open the browser for WeCom login. If they confirm, run the CLI yourself:
-
-```bash
-wonder wecom cookie
-```
-
-`wonder wecom cookie` is expected to launch the local browser login page. Wait
-for the user to complete the browser login or QR scan, then verify:
-
-```bash
-wonder wecom status
-```
-
-Proceed only after the cookie is valid, then retry the original `wonder read`
-command. Never ask the user to install Cookie-Editor, export JSON, paste a
-cookie string, run `wonder wecom cookie` themselves, or use
-`wonder wecom set-cookie` unless the user explicitly asks for a manual/dev/CI
-cookie path.
-
----
-
-## URL Type Routing
-
-Identify the document type from the URL path prefix:
-
-| URL prefix | Type | Action |
-|-----------|------|--------|
-| `sheet/e3_` | xlsx spreadsheet | Two-step: meta → tab data |
-| `doc/w3_` | docx document | Download → parse with docx skill |
-| `doc/e2_` | docx document | Download → parse with docx skill |
-| `slide/p3_` | pptx presentation | Download → parse with pptx skill |
-| `smartpage/a1_` | Smart page | ❌ Not supported in v1 |
-| `mind/m4_` | Mind map | ❌ Not supported in v1 |
-
----
-
-## xlsx Workflow (`sheet/e3_`)
-
-### Step 1 — Get metadata
-
-```bash
-wonder read <url>
-```
-
-Output is a JSON with tab list and row/column counts:
-
-```json
-{
-  "type": "sheet",
-  "title": "文档标题",
-  "tabs": [
-    { "name": "Sheet1", "rows": 50, "cols": 12 },
-    { "name": "汇总", "rows": 20, "cols": 8 }
-  ]
-}
-```
-
-Decide which tab(s) to read based on the user's question and the metadata.
-
-### Step 2 — Read specific tab
-
-```bash
-wonder read <url> --tab <tab-name>
-```
-
-Output is a structured JSON:
-
-```json
-{
-  "tab": "Sheet1",
-  "maxRow": 50,
-  "maxCol": 12,
-  "cells": [
-    { "row": 1, "col": 1, "text": "标题" },
-    { "row": 3, "col": 4, "image": { "path": "/path/to/xl/media/image1.png", "width": 200, "height": 150 } }
-  ],
-  "merges": [
-    { "startRow": 1, "startCol": 1, "endRow": 1, "endCol": 3 }
-  ]
-}
-```
-
-Consume this JSON directly to answer the user's question.
-
-### ⚠️ Merged cells — always check `mergeSpan`
-
-A cell may carry `mergeSpan: {rows, cols}` when it is the top-left anchor of a merged range. The cell's content is shared across `rows × cols` grid positions starting at `(row, col)`. **When the user asks about a cell's content, always factor `mergeSpan` into the answer.**
-
-Concrete example: in a half-hour-grid time table, a `mergeSpan: {rows: 4, cols: 1}` anchored at `(row=39, col=40)` saying "★直播 + Poach" means the activity actually occupies **4 half-hour slots = 2 hours**, not 30 minutes. Quoting only the anchor row's time would mislead the user.
-
-The complete merge list is also available in the top-level `merges[]` array if you need to reason about every merge in the sheet.
-
-### ⚠️ Date / time cells — read `text`, not `value`
-
-Number cells with date or time formats (e.g. `m"月"d"日"`, `h:mm`) are rendered into a readable `text` string (`"2026-04-30"`, `"12:00"`) alongside the raw `value` and `format`. **Always use `text` when reporting dates and times to the user.** The raw `value` is an Excel serial number (days since 1899-12-30) and is meaningless to humans.
-
-### ⚠️ Row/column indexing — JSON is 0-based, Excel is 1-based
-
-In wonder's JSON output, `row` and `col` (and `startRow`/`endRow`/`startCol`/`endCol` in `merges`) are **0-based**. Excel addresses the user sees in the WeCom UI are **1-based**.
-
-| JSON value | Excel address |
-|---|---|
-| `row: 0, col: 0` | A1 |
-| `row: 9, col: 2` | C10 |
-| `startRow: 1, startCol: 2, endRow: 9, endCol: 2` | C2:C10 (merged cell) |
-
-**When talking to the user, always convert to 1-based Excel addresses.** The user thinks in Excel rows ("第 10 行"), not JSON indices. Internal calculations can stay 0-based; only what the user reads needs translation. Do not say "行 9" when you mean Excel row 10.
-
-### Viewing embedded images
-
-Image cells have a `path` field pointing to the local extracted file. Use the Read tool to view:
-
-```
-Read("/Users/<you>/Downloads/5mghost-wonder/media/image3.png")
-```
-
-**Note:** Images are full-resolution originals (up to several MB each). Only load images the user specifically asks about.
-
-### Viewing visual layout — required when colour or layout carries meaning
-
-The JSON does not carry cell colours, font colours, or rendered borders. When colour or position is part of the answer, you cannot recover it from JSON — you must read the rendered sheet.
-
-Render to PDF and Read it whenever any of these are true:
-
-- The user asks about "how it looks", "颜色", "排版", "这个图表", "这张表的结构", or refers to a visible highlight
-- The sheet is a gantt chart, calendar, status board, or roadmap (colour = stage / owner / priority / "this week")
-- A column or row in the user's question is highlighted (yellow / red / green) in the WeCom UI
-- The merge-to-cell ratio in the JSON is non-trivial (e.g. `merges.length / cells.length > 0.1`) — likely a layout-driven sheet
-
-You cannot detect colour from JSON alone, so when in doubt about a sheet that mixes data with visual cues, render. The cost is ~30 s and ~10 MB; the cost of guessing wrong is worse.
-
-Render command (one PDF page per tab, preserves layout, merges, fills, borders):
-
-```bash
-soffice --headless \
-  --convert-to 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}' \
-  --outdir /tmp/ <path-to-downloaded-xlsx>
-```
-
-Then use the Read tool on the generated PDF. Page N corresponds to the Nth tab in workbook order (same as `tabs[]` in the metadata output).
-
-Skip rendering only when the user clearly wants a single cell value or a numeric lookup from a plain data table.
-
----
-
-## docx Workflow (`doc/w3_`, `doc/e2_`)
-
-### Step 1 — Download
-
-```bash
-wonder read <url>
-```
-
-Output:
-
-```json
-{ "type": "doc", "path": "/Users/<you>/Downloads/5mghost-wonder/filename.docx" }
-```
-
-### Step 2 — Read content
-
-**Read text** (recommended first step):
-
-```bash
-pandoc <path> -o /tmp/wonder-doc-output.md && cat /tmp/wonder-doc-output.md
-```
-
-**View full-page layout with images** (when layout matters):
-
-```bash
-soffice --headless --convert-to pdf --outdir /tmp/ <path>
-```
-
-Then use the Read tool on the generated PDF.
-
-**Access embedded images** (when individual images are needed):
-
-```bash
-mkdir -p /tmp/wonder-doc-unpack && cp <path> /tmp/wonder-doc-unpack/doc.zip && unzip -o /tmp/wonder-doc-unpack/doc.zip -d /tmp/wonder-doc-unpack/
-```
-
-Then use Read tool on files in `/tmp/wonder-doc-unpack/word/media/`.
-
----
-
-## pptx Workflow (`slide/p3_`)
-
-### Step 1 — Download
-
-```bash
-wonder read <url>
-```
-
-Output:
-
-```json
-{ "type": "slide", "path": "/Users/<you>/Downloads/5mghost-wonder/filename.pptx" }
-```
-
-### Step 2 — Always extract both text and visual layout
-
-For pptx, run **both** extractions every time. Most WeCom slides are layout-driven (timelines, image collages, status boards, recap pages) — pure text loses critical meaning, and pure-PDF visual reading can mis-OCR text that pandoc captures cleanly. You cannot tell a "complex" slide from a "simple" slide without first looking at it, so don't try to decide; just run both and use whichever the question calls for.
-
-**1. Text** (for exact wording, fast keyword scanning, copy-quoting):
-
-```bash
-pandoc <path> -o /tmp/wonder-slide-output.md && cat /tmp/wonder-slide-output.md
-```
-
-**2. Visual layout** (for image-text relationships, timelines, colour, embedded screenshots whose text pandoc cannot reach — e.g. Korean / Japanese chat captures):
-
-```bash
-soffice --headless --convert-to pdf --outdir /tmp/ <path>
-```
-
-Then use the Read tool on the generated PDF.
-
-When answering, combine: lean on the PDF for "what's on the slide and how it's organised", lean on the markdown for exact-wording quotes. Don't answer from text-only when a slide visibly relies on layout — the user will spot the gap immediately.
-
-If `soffice` is not installed (`wonder check` reports it as optional/missing), fall back to pandoc-only and tell the user upfront that visual cues, embedded screenshot text, and image-text relationships will be missing from your answer.
-
-### Optional: access embedded images directly
-
-```bash
-mkdir -p /tmp/wonder-pptx-unpack && cp <path> /tmp/wonder-pptx-unpack/slide.zip && unzip -o /tmp/wonder-pptx-unpack/slide.zip -d /tmp/wonder-pptx-unpack/
-```
-
-Then use Read tool on files in `/tmp/wonder-pptx-unpack/ppt/media/`.
-
----
-
-## Unsupported types
-
-**smartpage (`smartpage/a1_`):**
-
-> 当前版本不支持智能文档（smartpage）。建议在浏览器中手动打开文档，选择"导出为 PDF"或"复制内容"。
-
-**mind (`mind/m4_`):**
-
-> 当前版本不支持思维导图（mind）。
-
----
-
-## Known issues
-
-| Issue | Detail | Workaround |
-|-------|--------|-----------|
-| pptx slice crash | `prs.slides[:N]` → `AttributeError: 'list' object has no attribute 'rId'` | Use `for slide in prs.slides` |
-| Cookie expiry | Cookie valid for 7–30 days | Run `wonder wecom cookie` to refresh |
-| xlsx images are full-size | Original images can be up to 6 MB each | Only read images when user specifically needs them |
-| xlsx colour / visual layout | JSON has no fill colour, font colour, or rendered borders | Render to PDF (xlsx section) when colour or layout carries meaning |
-| pptx layout-driven slides | Pure pandoc loses image-text relationships, timelines, embedded screenshot text (e.g. Korean chats) | pptx workflow now runs pandoc + soffice→pdf together by default |
-| smartpage unsupported | Export API returns 0% progress forever | Manual browser export |
-
----
-
-## CLI command reference
-
-```
-wonder read <url>                  # Auto-detect type; xlsx → metadata; doc/slide → download
-wonder read <url> --tab <name>     # xlsx: get full data for specified tab
-wonder read <url> --save <dir>     # Set output directory (default: ~/Downloads/5mghost-wonder/)
-
-wonder wecom status                # Check cookie validity
-wonder wecom cookie                # Refresh cookie via browser QR scan
-wonder update                      # Update to latest version
-wonder check                       # Health check for all dependencies
-wonder auth status                 # Check mkterswingman auth status
-```
+# use-5mghost-wonder
+
+This is the Wonder router skill. Keep this file as the entrypoint and load only
+the referenced workflow files needed for the current task.
+
+## Version Gate
+
+This skill matches **wonder 0.0.14**.
+
+On first use in a session, follow `references/session-init.md`. If the installed
+CLI version differs from `0.0.14`, stop and ask the user to run
+`/update-5mghost-wonder`, then start a fresh AI session.
+
+## Hard Rules
+
+- Do not ask the user to export cookies, install Cookie-Editor, paste raw
+  cookies, or run Wonder commands themselves unless they explicitly ask for a
+  manual/dev/CI path.
+- If cookies are missing, expired, invalid, or a WeCom request returns 401/403,
+  follow `references/cookie-recovery.md`.
+- Treat `wonder read` export output as one read path, not the only possible read
+  path. If export fails because the document is read-only, export-disabled, or
+  unsupported, route to `references/read-no-export-browser.md`.
+- Do not claim rich editing succeeded because a toolbar button was clicked.
+  Editing success requires the verification rules in `references/verification.md`.
+- For sheet answers, convert 0-based JSON coordinates to 1-based spreadsheet
+  addresses before talking to the user.
+- Preserve images and layout when the user asks visual, table, screenshot,
+  merge-cell, or embedded-image questions. Do not answer those from text-only
+  extraction.
+
+## Route
+
+Identify the user's actual job, then load the smallest workflow reference:
+
+| User job | Primary reference |
+| --- | --- |
+| First Wonder use this session | `references/session-init.md` |
+| Cookie/auth recovery | `references/cookie-recovery.md` |
+| Read exportable doc/sheet/slide | `references/read-export.md` |
+| Read read-only, export-disabled, unsupported, or visual-heavy docs without export | `references/read-no-export-browser.md` |
+| Edit a WeCom doc through the browser editor | `references/edit-browser-runtime.md` |
+| Verify read/write results | `references/verification.md` |
+| Explain/triage failures | `references/failure-recovery.md` |
+| Check command syntax | `references/cli-reference.md` |
+
+Use `references/route-map.md` when the task is ambiguous or mixes several
+jobs. For mixed tasks, run the references in this order: session init, cookie
+recovery if needed, read, edit, verify.
+
+## Current Capability Boundary
+
+Stable:
+- Export-backed reads for supported docs, sheets, and slides.
+- Sheet JSON with cells, merge ranges, and exported embedded images.
+- Cookie refresh through `wonder wecom cookie`.
+
+Experimental:
+- Browser editor runtime for controlled write tasks.
+- No-export browser reading for read-only/export-disabled documents.
+
+Not promised yet:
+- Lossless no-export extraction for every WeCom document shape.
+- Every toolbar command, callout, highlighter, nested menus, or complex block
+  semantics.

package/skills/use-5mghost-wonder/references/cli-reference.md

@@ -0,0 +1,26 @@
+# CLI Reference
+
+```bash
+wonder read <url>                  # Auto-detect type; sheet -> metadata, doc/slide -> file path
+wonder read <url> --tab <name>     # Sheet tab data: cells, merges, images
+wonder read <url> --save <dir>     # Output directory
+wonder read <url> --no-cache       # Force fresh export
+
+wonder browser probe <url>         # Experimental no-export browser evidence probe
+wonder browser probe <url> --headed
+wonder browser probe <url> --save <dir>
+
+wonder wecom status                # Check WeCom cookie validity
+wonder wecom cookie                # Open browser login and refresh cookies
+wonder wecom set-cookie            # Manual/dev/CI only
+
+wonder check                       # Health check
+wonder setup                       # Guided setup
+wonder update                      # Update package and bundled skills
+wonder auth status                 # mkterswingman auth status
+wonder auth login                  # Browser OAuth login
+wonder version                     # Print version
+```
+
+Browser editor runtime remains experimental. No-export read now has an
+experimental evidence probe command, but it is not a lossless reader yet.

package/skills/use-5mghost-wonder/references/cookie-recovery.md

@@ -0,0 +1,24 @@
+# Cookie Recovery
+
+When WeCom cookies are missing, expired, invalid, or rejected with 401/403:
+
+1. Ask the user whether now is a convenient time to open the browser for WeCom
+   login.
+2. If they confirm, run:
+
+```bash
+wonder wecom cookie
+```
+
+3. Wait for the user to complete browser login or QR scan.
+4. Verify:
+
+```bash
+wonder wecom status
+```
+
+5. Retry the original task only after status is valid.
+
+Never ask the user to install Cookie-Editor, export JSON, paste a cookie
+string, run `wonder wecom cookie` themselves, or use `wonder wecom set-cookie`
+unless they explicitly request a manual/dev/CI cookie path.

package/skills/use-5mghost-wonder/references/edit-browser-runtime.md

@@ -0,0 +1,62 @@
+# Browser Editor Runtime
+
+Use this experimental path when the user asks Wonder to edit a WeCom document.
+
+## Meaning of Runtime
+
+The runtime is a controlled browser execution layer. It is not freeform "AI
+clicking around." It should expose limited, auditable actions:
+
+- open document
+- confirm login
+- focus editor
+- inspect available toolbar controls
+- insert text
+- apply a known formatting operation
+- read back or export for verification
+- capture screenshots/logs when verification fails
+
+## Safety Gate
+
+Before editing:
+
+1. Confirm the user intends to modify this exact document.
+2. Prefer a test document for experimental toolbar operations.
+3. Never edit other documents while probing.
+4. If cookies are invalid, follow `cookie-recovery.md`.
+
+## Supported v0 Operations
+
+These operations have evidence from prior browser/DOCX verification and may be
+attempted on an explicitly authorized document:
+
+- insert plain text
+- bold
+- italic
+- underline
+- strikethrough
+- bullet list
+- quote block
+
+These are not promised yet:
+
+- numbered list
+- highlight block
+- callout
+- nested toolbar menus
+- complex paragraph styles
+- arbitrary smart-page blocks
+
+## Procedure
+
+1. Read the document enough to understand the target location.
+2. Open the document in the Wonder browser profile or available browser
+   automation runtime.
+3. Locate the editor surface.
+4. Apply only supported operations unless the user explicitly asked to probe a
+   test document.
+5. Insert a unique marker when probing.
+6. Verify with `verification.md`.
+
+If verification fails, do not keep retrying blindly. Capture the failed
+operation, screenshot or runtime evidence, and return `partial` or `failed`.

package/skills/use-5mghost-wonder/references/failure-recovery.md

@@ -0,0 +1,16 @@
+# Failure Recovery
+
+Return actionable states. Do not show raw stack traces as the main answer.
+
+| Failure | Action |
+| --- | --- |
+| `not_authenticated` | Ask user to allow `wonder auth login`; then verify `wonder auth status`. |
+| `cookie_invalid`, 401, 403 | Follow `cookie-recovery.md`. |
+| `unsupported_type` | Try `read-no-export-browser.md` if the page can load in browser. |
+| `export_failed` | If it looks permission/export related, route to no-export browser read. Otherwise report the export error and retry only once if transient. |
+| Browser cannot launch | Run `wonder check`; report missing browser/dependency state. |
+| Toolbar operation not found | Report `not_supported` for that operation and do not claim the edit worked. |
+| Verification mismatch | Report `partial` or `failed`, include what changed and what did not verify. |
+
+If a task partially succeeds, answer with the usable result and a short missing
+capability list.