@mkterswingman/5mghost-wonder 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-wonder",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "企微文档读取 CLI — WeCom document reader",
   "type": "module",
   "engines": {

package/scripts/postinstall.mjs

@@ -44,6 +44,12 @@ try {
   } else {
     console.log("[wonder] No skill targets updated.");
   }
+  // Always remind the user to restart their AI session — skill text loaded
+  // into a running session does not refresh after files on disk are replaced.
+  console.log("");
+  console.log("[wonder] ⚠️  IMPORTANT: Restart your AI session (Claude Code / Codex / Gemini / etc.)");
+  console.log("[wonder]     before invoking any wonder skill. Open a new chat, or run /exit and re-enter.");
+  console.log("[wonder]     The AI cannot pick up the newly installed skill text in this running session.");
 } catch (err) {
   // Skill install failure must never break npm install
   console.log(`[wonder] Skill install failed (non-fatal): ${String(err)}`);

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

@@ -5,6 +5,16 @@ description: Use this skill when the user wants to install or set up wonder, say
 
 # Setup wonder — 企微文档 CLI 安装向导
 
+## Skill version
+
+This skill matches **wonder 0.0.9**.
+
+Once the CLI is installed in Step 1, run `wonder --version`. If the output does not equal `0.0.9`, 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.
+
+---
+
 You are guiding the user through installing and configuring `wonder`, the WeCom document reader CLI.
 
 Execute each step in order using the Bash tool. Stop and ask for user interaction only when a step requires it (e.g., browser OAuth, QR code scan). After each detection step, only proceed to installation if the tool is missing.

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

@@ -5,6 +5,12 @@ description: Use this skill when the user wants to update or upgrade wonder, say
 
 # Update wonder — 升级 5mghost-wonder CLI
 
+## Skill version
+
+This skill matches **wonder 0.0.9**.
+
+---
+
 Run the CLI's built-in updater. It reinstalls the latest published version globally via npm.
 
 ```bash
@@ -17,7 +23,7 @@ When the command completes, verify the new version is in place:
 wonder --version
 ```
 
-After updating, **the bundled skills (`setup-5mghost-wonder`, `use-5mghost-wonder`, `update-5mghost-wonder`) on disk are refreshed by the package's `postinstall`**, but the AI session's already-loaded skill text is the old version. Tell the user to start a new session if they need the latest skill text — open a fresh chat / restart the CLI / `/exit` and re-enter.
+After updating, **the bundled skills (`setup-5mghost-wonder`, `use-5mghost-wonder`, `update-5mghost-wonder`) on disk are refreshed by the package's `postinstall`**, but the AI session's already-loaded skill text is the old version. **Tell the user — clearly and proactively — that they must start a new AI session before the new skill text takes effect**: open a fresh chat, restart the CLI, or run `/exit` and re-enter. Until they do, the AI is still operating on the old skill regardless of what `wonder --version` reports.
 
 If `wonder update` exits non-zero, the most common cause is npm permission or registry issues. Re-run with the user's terminal so they can see the npm error directly:
 

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

@@ -5,6 +5,12 @@ description: Use this skill when the user shares a URL containing "doc.weixin.qq
 
 # use-5mghost-wonder — 企微文档读取操作指南
 
+## Skill version
+
+This skill matches **wonder 0.0.9**.
+
+In the Session Initialization step below, after running `wonder --version`, compare the output to `0.0.9`. 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.
@@ -13,7 +19,10 @@ The **first time** you encounter a WeCom document URL in a session, run these ch
 # 1. Check for updates
 wonder update
 
-# 2. Check WeCom cookie status
+# 2. Confirm the CLI version matches this skill's expected version (0.0.9)
+wonder --version
+
+# 3. Check WeCom cookie status
 wonder wecom status
 ```
 
@@ -130,19 +139,20 @@ 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 (optional)
+### 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.
 
-Use when the cell JSON alone can't answer the question because the sheet's meaning comes from **visual structure** — not from the cell values themselves. Typical signals:
+Render to PDF and Read it whenever any of these are true:
 
-- Gantt chart (date columns × task rows, coloured blocks across cell ranges)
-- Calendar (week grid with merged day cells or coloured categories)
-- Status board / roadmap (colour-coded cells indicating stage, owner, priority)
-- Large merge-to-cell ratio in the JSON (`merges.length` is a non-trivial fraction of `cells.length`)
-- User explicitly asks about "how it looks", "颜色", "排版", "这个图表", "这张表的结构"
+- 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
 
-Do **not** run render for plain data tables, lookup sheets, or when the user just wants a value. The render costs ~30 s and ~10+ MB of PDF per file.
+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 the whole xlsx (one PDF page per tab, preserves layout, merges, fills, borders):
+Render command (one PDF page per tab, preserves layout, merges, fills, borders):
 
 ```bash
 soffice --headless \
@@ -152,6 +162,8 @@ soffice --headless \
 
 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_`)
@@ -208,15 +220,17 @@ Output:
 { "type": "slide", "path": "/Users/<you>/Downloads/5mghost-wonder/filename.pptx" }
 ```
 
-### Step 2 — Read content
+### Step 2 — Always extract both text and visual layout
 
-**Read text** (recommended first step):
+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
 ```
 
-**View slide layout**:
+**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>
@@ -224,7 +238,11 @@ soffice --headless --convert-to pdf --outdir /tmp/ <path>
 
 Then use the Read tool on the generated PDF.
 
-**Access embedded images**:
+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/
@@ -253,7 +271,8 @@ Then use Read tool on files in `/tmp/wonder-pptx-unpack/ppt/media/`.
 | 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 visual layout needs soffice | Gantt/calendar/coloured boards lose meaning in JSON alone | Run the optional soffice render step in the xlsx section; CLI does not auto-render |
+| 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 |
 
 ---