@mkterswingman/5mghost-wonder 0.0.7 → 0.0.8

package/package.json

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

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

@@ -130,19 +130,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
 
-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:
+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.
 
-- 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", "颜色", "排版", "这个图表", "这张表的结构"
+Render to PDF and Read it whenever any of these are true:
 
-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.
+- 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
 
-Render the whole xlsx (one PDF page per tab, preserves layout, merges, fills, borders):
+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 \
@@ -152,6 +153,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 +211,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 +229,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 +262,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 |
 
 ---