@petercjl/taobao-ai-ops 0.1.0 → 0.1.2

package/skills/taobao-search-product-form/references/topics/visual-form-method.md

@@ -1,31 +0,0 @@
-# Image-grounded form judgment
-
-The upstream clean stage defines the product population. This module describes what is visible in its images; if a main object is ambiguous or appears outside the intended product boundary, flag it for that upstream decision rather than silently deleting its record. The image may disagree with a title or platform category.
-
-## One semantic read, three selection dimensions
-
-Before the first image call, create disjoint batches and record each readable product ID, image path/hash and batch ID. An original exceeding 10 MB is a `too_large` image-manifest item, retained in the natural-product evidence as `not_observed` and excluded from semantic batches and visual candidate groups; its title cannot substitute for an image observation. Record its ID and omission reason, then continue with the readable images. A visual worker receives the same questions and any provisional registry snapshot, but no closed list of allowable labels. For each ready product, capture one raw observation with `product_id`, `image_sha256`, `batch_id`, `status`, `visible_evidence`, and three independent dimensions:
-
-1. `form`: one candidate structural class, evidence and visible traits such as outline, depth, divisions, size and handle/lid relationship. Assign `uncertain` if the structure cannot be resolved. Color alone never splits a structural class.
-2. `style`: optional candidate product-design style, at least two concrete product-side cues, and a possible physical design delta. Keep main-image background, copy, lighting and graphic treatment in a separate `image_presentation` note. A style name derived only from one color is too weak and remains a cue rather than an accepted style class. Leave style unclassified when the product is visually generic or obscured.
-3. `audience`: optional candidate group defined by a use task, visible task cues, an explicit evidence tier (`image_only`, `combined`, or `insufficient`), and a plausible product-side adaptation. A depicted egg is a task cue, not proof of the buyer's demographics or actual purchase behavior. A candidate audience requires a task that could change the product's size, structure, handling, set configuration or design. If there is no such evidence, leave it unclassified. Any later title/price corroboration is recorded as a separate join, not retroactively presented as image evidence.
-
-The three dimensions are parallel selection paths. A style-led or audience-led physical product difference can constitute a new candidate merchandise proposition even when its base structural form matches another product. Distinguish candidate proposition from demonstrated opportunity: a single search snapshot cannot prove demand, profit or actual buyer identity.
-
-Inspect each original cached image independently, working through small checkpoint batches. The contact sheet is an orientation and coverage-audit artifact, not the sole semantic input. Save each completed batch as an immutable, plan-bound checkpoint before moving on, and use the batch status command to resume after a context boundary. Every product remains independently keyed; the batch draft uses `{"schema_version":2,"observations":[{"product_id":"…","status":"tagged|uncertain","visible_evidence":"…","form":{"candidate":"…"},"style":{"candidate":null},"audience":{"candidate":null}}]}` with the evidence fields above when style or audience is proposed. The checkpoint command binds each row to its planned image hash and rejects missing or extra IDs. Reopening an unclear original is a QA exception to the single-pass aspiration; log it. Use bounded concurrent semantic workers or multi-image calls only when the host actually supports independent per-image understanding and their outputs can be reconciled; each worker owns disjoint product IDs. Unverified acceleration never blocks the serial path, and image-download concurrency does not count as semantic concurrency.
-
-## Product-style prototype convergence after the image reads
-
-The three raw observation dimensions are useful evidence, but the final classification answers a different question: **what distinguishable merchandise styles can the seller actually choose, compare, source or develop?** A prototype is a coherent real-product scheme described through several jointly visible cues: base object, construction and handling, key functional configuration, and (when material to selection) an integrated product-design language. A single feature count—body silhouette, lid, spout, color, surface texture or photographed food—is not itself a complete style. A prototype name should let a merchant picture the actual good, such as “锤纹雪平锅” or “蒸煮一体小锅”, without requiring the source title to complete its meaning.
-
-1. Start with a varied image sample rather than a fixed category dictionary. Sketch candidate prototypes with a physical definition, sourceable selection difference, representative product IDs, inclusion and confusion boundaries. Use the original images and saved visible observations. The prototype registry is run-specific and can grow as new physical schemes appear.
-2. Compare each later product with representative and boundary images. Assign it to an existing prototype when differences are ordinary size, color or selectable configuration variants. Create a new prototype when the whole structure, function set or distinctive finished-product design demands a different comparison or supplier-development task. Revisit earlier near neighbors after a new prototype is introduced. A real rare prototype remains visible with its small count.
-3. A main image containing multiple recognizable goods can associate its listing with multiple prototypes; a hybrid good can likewise support more than one selection-relevant proposition. Preserve the product ID once in the population and record every justified membership. Keep ordinary variant details and single visual cues in separate fields so groups stay interpretable. Image presentation, graphic copy, inferred material, buyer demographic and unsupported use claims cannot create a prototype.
-4. Keep out-of-object accessories, image-only promotional compositions, unresolved objects and unreadable images in explicit boundary/uncertain states. Do not silently delete their product IDs. Class membership is image-grounded; title, price, payment or shop data cannot decide the visual class.
-5. Review group cohesion with representative, edge and low-confidence images, then compare near-neighbor groups for missed same-style merges. A group is useful when its members look like a coherent sellable product line and its distinction from another group would change the next selection investigation. Record merge/split reasons and remaining uncertainty; a smaller class count alone is not proof of quality.
-
-Keep the raw observations immutable. A classification pass writes a versioned registry plus one decision for every planned ready product: `product_id`, `image_sha256`, `style_ids` (one or more), `variant_or_features`, `reason`, `confidence`, and optional `boundary_reason`. The registry records `style_id`, name, physical definition, selection difference, inclusion/boundary rule and representative IDs. The deterministic `compile_style_prototypes.py` validates this decision file against the original plan and observations, then outputs product-level labels, prototype summary and an audit. Re-aggregation may reuse the saved image-hash-bound observations; reopen an original when its description does not settle a consequential boundary. New product images still require their own semantic observation.
-
-Use prototype groups in downstream joins and report navigation. Preserve structural form, design style and use-task observations as secondary evidence and filters. Reconcile `ready = observed = style-decided` and `too_large = not_observed` before full-run reporting; other unavailable-image reasons require diagnosis or retry. Count distinct product IDs for population and demand comparisons because prototype memberships can overlap. Join price, natural payment counts, shops and advertising only after the visual classes are finalized. This stage describes visible supply options, not buyer demand or entry feasibility. Return to Main Line Step 4 after this gate.
-
-This phase describes visual supply, not buyer demand or product-entry feasibility. Join title roots, price, placement and other evidence in later modules before recommending a form.

package/skills/taobao-search-product-form/references/topics/white-label-evidence.md

@@ -1,38 +0,0 @@
-# From product observations to opportunity cards
-
-## Question and candidate grain
-
-The goal is to help a user decide what to research next, not to declare that a product can or cannot be sold. Begin with the image-grounded **whole-product style prototypes**: each is a coherent, sourceable merchandise option. Structural form, product-design cues and image-supported use tasks explain why a prototype is distinct and provide optional comparison cuts; a task becomes meaningful only when it implies a physical product difference, not merely new copy or a hero-image theme. An image-supported use task is not a verified buyer demographic.
-
-Compare each prototype against its closest real-product alternatives and, where useful, the broader structural parent. Form–style and form–task intersections are secondary cuts when their member IDs and shop spread support interpretation. Candidate groups overlap, including listings that display more than one product style; their counts cannot be summed. Do not impose a permanent minimum count across categories. For sparse groups, report the observed products and roll the commercial comparison back to a better-supported comparable group. An unclassified task means insufficient image evidence, not absence of task demand. Preserve uncertain/non-target products outside candidate traction calculations until their boundary is reviewed.
-
-## Five evidence questions
-
-1. **Observed traction.** Examine distinct natural products and shops, the distribution of displayed `付款人数`, representative high-payment and ordinary products, and whether the group's apparent strength survives removal of its leading shop or product. A sum across product records is a descriptive index, not distinct buyers, monthly sales, units, conversion or GMV. A single search export cannot establish a growth trend or full-market share.
-2. **Comparable price structure.** Use the run's fitted price bands to locate supply, then compare like products within the same structure and the closest observable configuration. Report price median and spread, not only an average. Search-page current price may select a different SKU or discount; a higher displayed price is not proven willingness to pay or margin.
-3. **Merchant-line configuration.** For representative shops, contrast the candidate products with the same shop's other visible forms, versions and price tiers; identify natural-position strong products separately from products appearing in advertising positions. Describe the observed assortment. SKU roles, intentional product strategy and brand ownership remain hypotheses until separately verified. A multi-shop pattern has different implications from a group carried mainly by one shop.
-4. **Competitive exposure.** Keep ad appearances, distinct ad products and distinct advertiser shops separate. Connect natural products to ads by product ID and exact shop name; preserve cross-shop name conflicts and ad-only products as unknown-form or unknown-payment cases. Advertising can indicate both seller attention and acquisition pressure; it does not measure spend, exposure or ROI.
-5. **Product-side opening.** State which visible structural, material-appearance, color-system, handle, size or task-fit variation could make the proposed product different. Check whether existing merchants already cover it. Title roots are seller claims and discovery clues; image labels are visible observations; reviews, specifications, supplier quotes and tests are needed to establish user benefit, material truth, manufacturability and defects. Listing address may guide sourcing questions but does not identify a factory.
-
-Compare competing explanations explicitly. For example, a candidate may show high displayed payment because of one established shop, a lower price, stronger natural ranking, a different underlying product configuration, or multiple shops independently selling it. Where the current export cannot distinguish these, present the alternatives and the discriminating next check. Do not smooth contradictions into an opaque score or infer that low ad presence means low competition.
-
-## Opportunity-card contract
-
-Create `opportunity_cards.json` with `schema_version: 2`, `source_evidence_sha256` (the current comparison JSON file's exact SHA-256), selected strategy/version and an array of cards. Each card's `candidate_id` resolves to a `product_style` candidate. Secondary form/style/task candidate IDs may appear as evidence references or comparison context. A readable Markdown rendering carries the same content.
-
-| Field | Required meaning |
-| --- | --- |
-| `candidate_id`, `definition`, `parent_comparison` | Exact whole-product style member set and concrete product-side proposition, with the closest comparable prototype or broader structural form used for context. |
-| `scope` | Source population, tagged/uncertain coverage, member product/shop counts, missing modules and search-snapshot limitations. |
-| `observations` | Numeric traction, price, merchant-line, advertising, title and location facts, each linked to the compare artifact's field or product IDs. |
-| `supporting_evidence`, `counterevidence` | Separate, traceable items; an empty side must say evidence is unavailable, not imply proof. |
-| `interpretation` | A bounded explanation that considers shop, price and product-configuration alternatives. |
-| `unknowns` | Missing facts that could reverse the current research priority. |
-| `next_checks` | Specific review, SKU/price, cost, supplier or small-test questions; indicate what result would change the judgment. |
-| `research_order` | Optional reasoned research sequence relative to other cards, never a binary market-entry decision or composite score. |
-
-Every card should be readable without opening the raw JSON, while every named number and shop claim must trace back to the compare artifact. Keep observation, inference and proposed test visibly distinct. Include at least one representative product and one ordinary or counterexample product when available; show if the sample is too small for that comparison. The cards are complete when the user can inspect both the reason to investigate and the strongest reason that it may be misleading.
-
-## Handoff boundary
-
-The card may suggest a profit calculation or supplier investigation because those checks resolve uncertainty. It cannot conclude net margin, a verified unmet need, factory access, or an entry decision from a search snapshot. The broader product-development method separates demand, product differentiation, net profit, supplier standards and low-risk testing. Defer the last three to their own evidence-gathering stages; do not represent a request for research as authorization to buy, stock or publish.

package/skills/taobao-search-product-form/references/workflow-ledger.md

@@ -1,28 +0,0 @@
-# Stage ledger
-
-The per-run `ledger.json` lives beside that run's data, not inside this Skill. It records two independent dimensions: `design_state` (`open`, `defined`, `validated`) describes how mature the stage method is; `status` describes what happened in this particular run. A stage can have a defined method without having been executed, or a provisional result awaiting review.
-
-The initial stages are `input`, `clean`, `classify`, `compare`, `decide`, and `report`. Add a classification module with a stage ID such as `classify/placement` or `classify/visual-form` when that module is selected. These IDs are navigation handles, not a declaration of the module's eventual field schema or algorithm.
-
-Statuses:
-
-- `not_started`: no current result.
-- `in_progress`: work begun, with intermediate artifacts if any.
-- `awaiting_review`: development result exists and awaits the user's review.
-- `approved`: the user confirmed the development result; record reviewer and what was approved.
-- `verified`: run-mode result passed its automatic QA.
-- `blocked`: cannot safely advance; record the reason.
-- `skipped`: reserved for a documented development-stage experiment outside the complete run; record why when it could be mistaken for missing work.
-
-Commands (resolve the script relative to the Skill directory):
-
-```text
-python3 scripts/workflow_ledger.py init --run-dir RUN_DIR --mode development --input WORKBOOK
-python3 scripts/workflow_ledger.py show --ledger RUN_DIR/ledger.json
-python3 scripts/workflow_ledger.py record --ledger RUN_DIR/ledger.json --stage clean --status awaiting_review --artifact OUTPUT_FILE --note "What was checked and what remains for review"
-python3 scripts/workflow_ledger.py record --ledger RUN_DIR/ledger.json --stage clean --status approved --reviewer USER --note "What the user confirmed"
-```
-
-`record` also accepts `--design-state`, `--strategy` and repeated `--artifact`. Artifact paths are resolved to existing files and stored with size and SHA-256 so later work can detect changed inputs or intermediates. Each update adds an event and creates a recoverable backup of the previous ledger. `init` refuses to replace an existing ledger.
-
-In development mode, a stage may be reviewed and approved independently while the complete workflow is being built. The next stage reads its actual approved artifacts and ledger scope. Record parent and downstream stages when their artifacts are produced; approval of a report does not automatically approve each source stage. If an input or strategy change makes a downstream result stale, mark that downstream stage accordingly with a reason before reusing it. In run mode, execute every required stage and module, update the ledger after each material transition, and continue after automated verification without routine user review. A development-stage review may stop after its current module and hand off the ledger plus artifacts.

package/skills/taobao-search-product-form/report_runtime/VERSION

@@ -1 +0,0 @@
-1.2.5

package/skills/taobao-search-product-form/report_runtime/renderer.py

@@ -1,485 +0,0 @@
-#!/usr/bin/env python3
-"""Versioned Compact Commerce UI ViewModel renderer."""
-
-from __future__ import annotations
-
-import base64
-import hashlib
-import html
-import json
-import pathlib
-import re
-from typing import Any
-
-
-ROOT = pathlib.Path(__file__).resolve().parent
-CONTRACT = "compact-workbench@1.0"
-CLI_VERSION = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
-
-
-def esc(value: Any) -> str:
-    return html.escape(str(value if value is not None else ""), quote=True)
-
-
-def slug(value: Any) -> str:
-    candidate = re.sub(r"[^a-zA-Z0-9_-]+", "-", str(value or "")).strip("-")
-    if not candidate:
-        raise ValueError(f"Invalid empty identifier: {value!r}")
-    return candidate
-
-
-def mime_for(blob: bytes) -> str:
-    if blob.startswith(b"\xff\xd8\xff"):
-        return "image/jpeg"
-    if blob.startswith(b"\x89PNG\r\n\x1a\n"):
-        return "image/png"
-    if blob.startswith((b"GIF87a", b"GIF89a")):
-        return "image/gif"
-    if blob.startswith(b"RIFF") and blob[8:12] == b"WEBP":
-        return "image/webp"
-    if blob.startswith(b"<svg") or b"<svg" in blob[:256]:
-        return "image/svg+xml"
-    raise ValueError("Unsupported image format; use JPEG, PNG, GIF, WebP, or SVG")
-
-
-def normalize_assets(raw: Any, input_dir: pathlib.Path) -> dict[str, dict[str, str]]:
-    if raw is None:
-        return {}
-    if isinstance(raw, dict):
-        items = [dict(value, id=key) for key, value in raw.items()]
-    elif isinstance(raw, list):
-        items = raw
-    else:
-        raise ValueError("assets must be an object or array")
-    result: dict[str, dict[str, str]] = {}
-    for item in items:
-        if not isinstance(item, dict) or not item.get("id") or not item.get("path"):
-            raise ValueError("each asset requires id and path")
-        asset_id = str(item["id"])
-        if asset_id in result:
-            raise ValueError(f"duplicate asset id: {asset_id}")
-        value = str(item["path"])
-        if re.match(r"https?://", value, re.I):
-            raise ValueError(f"remote rendering asset is forbidden: {asset_id}")
-        path = pathlib.Path(value).expanduser()
-        if not path.is_absolute():
-            path = input_dir / path
-        path = path.resolve()
-        if not path.is_file():
-            raise ValueError(f"asset not found: {asset_id} -> {path}")
-        blob = path.read_bytes()
-        mime = mime_for(blob)
-        result[asset_id] = {
-            "src": f"data:{mime};base64,{base64.b64encode(blob).decode('ascii')}",
-            "alt": str(item.get("alt", "")),
-            "role": str(item.get("role", "content")),
-            "sha256": hashlib.sha256(blob).hexdigest(),
-        }
-    return result
-
-
-class Renderer:
-    def __init__(self, document: dict[str, Any], assets: dict[str, dict[str, str]]) -> None:
-        self.document = document
-        self.assets = assets
-        self.external_images = str((document.get("meta") or {}).get("external_images", "forbid"))
-        self.tab_counter = 0
-
-    def render_blocks(self, blocks: Any) -> str:
-        if blocks is None:
-            return ""
-        if not isinstance(blocks, list):
-            raise ValueError("blocks must be an array")
-        return "".join(self.render_block(block) for block in blocks)
-
-    def render_block(self, block: Any) -> str:
-        if not isinstance(block, dict):
-            raise ValueError("every block must be an object")
-        kind = block.get("type")
-        if kind == "conclusion":
-            return self.render_conclusion(block)
-        if kind == "alert":
-            tone = slug(block.get("tone", "warning"))
-            title = f"<strong>{esc(block.get('title'))}</strong> " if block.get("title") else ""
-            return f'<section class="alert tone-{tone} searchable">{title}<span>{esc(block.get("text", ""))}</span></section>'
-        if kind == "metrics":
-            columns = max(1, min(8, int(block.get("columns", 4))))
-            variant = slug(block.get("variant", "default"))
-            items = "".join(self.render_metric(item, variant) for item in block.get("items", []))
-            return f'<section class="metrics metrics-{columns} variant-{variant}">{items}</section>'
-        if kind == "grid":
-            columns = max(1, min(4, int(block.get("columns", 2))))
-            children = "".join(self.render_block(item) for item in block.get("items", []))
-            return f'<section class="module-grid grid-{columns}">{children}</section>'
-        if kind == "card":
-            title = esc(block.get("title", ""))
-            meta = esc(block.get("meta", ""))
-            head = f'<div class="card-head"><h2>{title}</h2><span>{meta}</span></div>' if title or meta else ""
-            body = self.render_blocks(block.get("blocks", []))
-            extra = slug(block.get("variant", "default"))
-            return f'<article class="card card-{extra} searchable">{head}<div class="card-body">{body}</div></article>'
-        if kind == "list":
-            ordered = bool(block.get("ordered"))
-            tag = "ol" if ordered else "ul"
-            items = "".join(f'<li class="searchable">{esc(item)}</li>' for item in block.get("items", []))
-            return f'<{tag} class="content-list">{items}</{tag}>'
-        if kind == "callout":
-            return f'<div class="callout searchable">{esc(block.get("text", ""))}</div>'
-        if kind == "text":
-            values = block.get("paragraphs")
-            if values is None:
-                values = [block.get("text", "")]
-            return '<div class="prose">' + "".join(f'<p class="searchable">{esc(value)}</p>' for value in values) + "</div>"
-        if kind == "table":
-            return self.render_table(block)
-        if kind == "tabs":
-            return self.render_tabs(block)
-        if kind == "products":
-            return self.render_products(block)
-        if kind == "stats":
-            items = "".join(f'<div class="mini-stat searchable"><span>{esc(x.get("label", ""))}</span><b>{esc(x.get("value", "—"))}</b></div>' for x in block.get("items", []))
-            return f'<div class="mini-stats">{items}</div>'
-        if kind == "badge":
-            tone = slug(block.get("tone", "info"))
-            return f'<span class="tag tone-{tone}">{esc(block.get("text", ""))}</span>'
-        if kind == "button":
-            label = esc(block.get("label", "打开"))
-            if block.get("target_view"):
-                return f'<button class="text-button" type="button" data-open-view="{esc(slug(block["target_view"]))}">{label}</button>'
-            if block.get("url"):
-                return f'<button class="text-button" type="button" data-url="{esc(block["url"])}">{label}</button>'
-            raise ValueError("button requires target_view or url")
-        if kind == "actions":
-            rows = []
-            for index, item in enumerate(block.get("items", []), 1):
-                rows.append(f'<div class="action-row searchable"><span class="action-rank">{index}</span><div><b>{esc(item.get("title", ""))}</b><p>{esc(item.get("text", ""))}</p></div><span class="tag tone-{esc(slug(item.get("tone", "info")))}">{esc(item.get("label", ""))}</span></div>')
-            return '<div class="action-list">' + "".join(rows) + "</div>"
-        if kind == "empty":
-            return f'<div class="empty">{esc(block.get("text", "暂无数据"))}</div>'
-        raise ValueError(f"unsupported block type: {kind!r}")
-
-    def render_conclusion(self, block: dict[str, Any]) -> str:
-        items = block.get("items")
-        if not isinstance(items, list) or len(items) < 2:
-            raise ValueError("conclusion requires at least two structured items")
-        valid_tones = {"info", "positive", "warning", "danger"}
-        valid_emphasis = {"normal", "strong", "italic", "strong-italic"}
-        cards = []
-        for item in items:
-            if not isinstance(item, dict) or not isinstance(item.get("label"), str) or not item["label"].strip():
-                raise ValueError("each conclusion item requires a nonempty label")
-            segments = item.get("segments")
-            if not isinstance(segments, list) or not segments:
-                raise ValueError("each conclusion item requires text segments")
-            tone = item.get("tone", "info")
-            if tone not in valid_tones:
-                raise ValueError(f"unsupported conclusion tone: {tone!r}")
-            rendered_segments = []
-            for segment in segments:
-                if not isinstance(segment, dict) or not isinstance(segment.get("text"), str) or not segment["text"]:
-                    raise ValueError("each conclusion segment requires nonempty text")
-                emphasis = segment.get("emphasis", "normal")
-                segment_tone = segment.get("tone")
-                if emphasis not in valid_emphasis or (segment_tone is not None and segment_tone not in valid_tones):
-                    raise ValueError("unsupported conclusion emphasis or tone")
-                classes = ["conclusion-segment", f"emphasis-{emphasis}"]
-                if segment_tone is not None:
-                    classes.append(f"conclusion-color-{segment_tone}")
-                rendered_segments.append(f'<span class="{" ".join(classes)}">{esc(segment["text"])}</span>')
-            note = f'<div class="conclusion-note">{esc(item["note"])}</div>' if item.get("note") else ""
-            cards.append(
-                f'<article class="conclusion-item conclusion-tone-{tone} searchable">'
-                f'<h3>{esc(item["label"])}</h3>'
-                f'<p class="conclusion-copy">{"".join(rendered_segments)}</p>{note}</article>'
-            )
-        title = esc(block.get("title") or "核心结论")
-        return f'<section class="card conclusion-card"><div class="card-head"><h2>{title}</h2></div><div class="conclusion-grid">{"".join(cards)}</div></section>'
-
-    def render_metric(self, item: dict[str, Any], variant: str) -> str:
-        tone = slug(item.get("tone", "info"))
-        badge = f'<span class="metric-badge tone-{tone}">{esc(item.get("badge"))}</span>' if item.get("badge") else ""
-        return f'<article class="card metric metric-{variant} searchable"><div class="metric-label"><span>{esc(item.get("label", ""))}</span>{badge}</div><div class="metric-value">{esc(item.get("value", "—"))}</div><div class="metric-note">{esc(item.get("note", ""))}</div></article>'
-
-    def render_table(self, block: dict[str, Any]) -> str:
-        columns = block.get("columns", [])
-        if not columns:
-            raise ValueError("table requires columns")
-        labels = [column.get("label", column.get("key", "")) if isinstance(column, dict) else column for column in columns]
-        head = "".join(f"<th>{esc(label)}</th>" for label in labels)
-        rows = []
-        for row in block.get("rows", []):
-            if isinstance(row, dict):
-                values = [row.get(column.get("key")) if isinstance(column, dict) else row.get(str(column)) for column in columns]
-            else:
-                values = row
-            cells = "".join(f"<td>{self.render_cell(value)}</td>" for value in values)
-            rows.append(f'<tr class="searchable">{cells}</tr>')
-        title = esc(block.get("title", ""))
-        meta = esc(block.get("meta", ""))
-        headbar = f'<div class="card-head"><h2>{title}</h2><span>{meta}</span></div>' if title or meta else ""
-        return f'<article class="card table-card">{headbar}<div class="table-wrap"><table class="data-table"><thead><tr>{head}</tr></thead><tbody>{"".join(rows)}</tbody></table></div></article>'
-
-    def render_cell(self, value: Any) -> str:
-        if not isinstance(value, dict):
-            return esc(value if value is not None else "—")
-        text = esc(value.get("text", "—"))
-        image_url = str(value.get("image_url", "")).strip()
-        if image_url:
-            if self.external_images != "allow_https":
-                raise ValueError("table cell image_url requires meta.external_images=allow_https")
-            if not re.fullmatch(r'''https://[^\s"'<>]+''', image_url):
-                raise ValueError("table cell image_url must be an HTTPS URL")
-            text = (
-                '<div class="cell-product">'
-                f'<div class="cell-thumb"><img src="{esc(image_url)}" alt="{esc(value.get("alt") or value.get("text", ""))}" '
-                'loading="lazy" referrerpolicy="no-referrer" data-remote-image>'
-                '<div class="image-empty" hidden>加载失败</div></div>'
-                f'<span>{text}</span></div>'
-            )
-        if value.get("badge"):
-            text += f' <span class="tag tone-{esc(slug(value.get("tone", "info")))}">{esc(value["badge"])}</span>'
-        actions = []
-        if value.get("url"):
-            actions.append(f'<button class="text-button compact" type="button" data-url="{esc(value["url"])}">{esc(value.get("action_label", "打开"))}</button>')
-        if value.get("copy_value"):
-            actions.append(f'<button class="text-button compact copy-button" type="button" data-copy="{esc(value["copy_value"])}">{esc(value.get("copy_label", "复制"))}</button>')
-        if actions:
-            text += f'<div class="inline-actions">{"".join(actions)}</div>'
-        return text
-
-    def render_tabs(self, block: dict[str, Any]) -> str:
-        self.tab_counter += 1
-        group = f"tabs-{self.tab_counter}"
-        tabs = block.get("tabs", [])
-        if not tabs:
-            return self.render_block({"type": "empty", "text": block.get("empty_text", "暂无分类")})
-        buttons = []
-        panels = []
-        for index, tab in enumerate(tabs):
-            tab_id = slug(tab.get("id", f"tab-{index+1}"))
-            suffix = f" · {esc(tab.get('badge'))}" if tab.get("badge") not in (None, "") else ""
-            buttons.append(f'<button type="button" data-tab-target="{tab_id}" class="{"active" if index == 0 else ""}">{esc(tab.get("label", tab_id))}{suffix}</button>')
-            hidden = "" if index == 0 else " hidden"
-            panels.append(f'<div class="tab-panel" data-tab="{tab_id}"{hidden}>{self.render_blocks(tab.get("blocks", []))}</div>')
-        title = esc(block.get("title", ""))
-        meta = esc(block.get("meta", ""))
-        head = f'<div class="card-head"><h2>{title}</h2><span>{meta}</span></div>' if title or meta else ""
-        return f'<section class="card tabs-card" data-tabs="{group}">{head}<div class="tab-buttons">{"".join(buttons)}</div>{"".join(panels)}</section>'
-
-    def render_products(self, block: dict[str, Any]) -> str:
-        columns = max(1, min(4, int(block.get("columns", 3))))
-        items = block.get("items", [])
-        if not items:
-            return '<div class="empty">暂无候选商品</div>'
-        page_size = block.get("page_size")
-        if page_size is None:
-            products = "".join(self.render_product(item) for item in items)
-            return f'<div class="product-grid product-grid-{columns}">{products}</div>'
-        page_size = max(1, int(page_size))
-        options = block.get("sort_options", [])
-        option_html = "".join(
-            f'<option value="{esc(option["key"])}" data-direction="{esc(option.get("direction", "desc"))}">{esc(option["label"])}</option>'
-            for option in options
-        )
-        cards = "".join(
-            f'<div class="gallery-entry" data-source-order="{index}" '
-            f'data-sort-values="{esc(json.dumps(item.get("sort_values", {}), ensure_ascii=False, separators=(",", ":")))}">'
-            f'{self.render_product(item)}</div>'
-            for index, item in enumerate(items)
-        )
-        controls = (
-            '<div class="gallery-controls">'
-            f'<label>排序<select data-gallery-sort><option value="source">原始顺序</option>{option_html}</select></label>'
-            f'<span data-gallery-count>{len(items)} 件</span>'
-            '<div class="gallery-pager"><button type="button" data-page-prev>上一页</button>'
-            '<span data-page-status></span><button type="button" data-page-next>下一页</button></div>'
-            '</div>'
-        )
-        bottom = ('<div class="gallery-controls gallery-controls-bottom"><span data-gallery-count-bottom></span>'
-                  '<div class="gallery-pager"><button type="button" data-page-prev-bottom>上一页</button>'
-                  '<span data-page-status-bottom></span><button type="button" data-page-next-bottom>下一页</button>'
-                  '</div></div>')
-        return (f'<section class="product-gallery" data-product-gallery data-page-size="{page_size}">'
-                f'{controls}<div class="product-grid product-grid-{columns}" data-gallery-grid>{cards}</div>'
-                f'{bottom}'
-                '</section>')
-
-    def render_product(self, item: dict[str, Any]) -> str:
-        asset_id = str(item.get("asset_id", ""))
-        asset = self.assets.get(asset_id)
-        image_url = str(item.get("image_url", "")).strip()
-        item_url = str(item.get("item_url", "")).strip()
-        if item_url and not re.fullmatch(r'''https://[^\s"'<>]+''', item_url):
-            raise ValueError("product item_url must be an HTTPS URL")
-        if asset:
-            image = (
-                f'<div class="product-media"><img src="{asset["src"]}" '
-                f'alt="{esc(item.get("alt") or asset.get("alt", ""))}"></div>'
-            )
-        elif image_url:
-            if self.external_images != "allow_https":
-                raise ValueError("product image_url requires meta.external_images=allow_https")
-            if not re.fullmatch(r'''https://[^\s"'<>]+''', image_url):
-                raise ValueError("product image_url must be an HTTPS URL")
-            image = (
-                f'<div class="product-media"><img src="{esc(image_url)}" alt="{esc(item.get("alt") or item.get("title", ""))}" '
-                'loading="lazy" referrerpolicy="no-referrer" data-remote-image>'
-                '<div class="image-empty" hidden>图片加载失败</div></div>'
-            )
-        else:
-            image = '<div class="product-media"><div class="image-empty">图片未提供</div></div>'
-        if item_url:
-            image = f'<a class="product-media-link" href="{esc(item_url)}" target="_blank" rel="noopener noreferrer" aria-label="打开商品：{esc(item.get("title", ""))}">{image}</a>'
-        title = esc(item.get("title", ""))
-        if item_url:
-            title = f'<a class="product-title-link" href="{esc(item_url)}" target="_blank" rel="noopener noreferrer">{title}</a>'
-        tone = slug(item.get("tone", "positive"))
-        facts = "".join(f'<div class="fact"><span>{esc(fact.get("label", ""))}</span><b>{esc(fact.get("value", "—"))}</b></div>' for fact in item.get("facts", []))
-        evidence = f'<div class="evidence">{esc(item.get("evidence"))}</div>' if item.get("evidence") else ""
-        actions = []
-        if item.get("url"):
-            actions.append(f'<button class="open-button" type="button" data-url="{esc(item["url"])}">{esc(item.get("action_label", "打开详情"))}</button>')
-        if item.get("copy_value"):
-            actions.append(f'<button class="open-button copy-button" type="button" data-copy="{esc(item["copy_value"])}">{esc(item.get("copy_label", "复制链接"))}</button>')
-        if item_url:
-            actions.append(f'<button class="open-button copy-button" type="button" data-copy="{esc(item_url)}">复制链接</button>')
-        action = f'<div class="product-actions">{"".join(actions)}</div>' if actions else ""
-        return f'<article class="card product-card searchable">{image}<div class="product-body"><div class="product-title">{title}</div><div class="product-meta"><span class="price">{esc(item.get("price", "—"))}</span><span class="tag tone-{tone}">{esc(item.get("badge", ""))}</span></div><div class="facts">{facts}</div>{evidence}{action}</div></article>'
-
-
-def validate_viewmodel(document: Any) -> dict[str, Any]:
-    if not isinstance(document, dict):
-        raise ValueError("ViewModel root must be an object")
-    if document.get("contract") != CONTRACT:
-        raise ValueError(f"contract must be {CONTRACT}")
-    meta = document.get("meta")
-    if not isinstance(meta, dict) or not meta.get("title"):
-        raise ValueError("meta.title is required")
-    views = document.get("views")
-    if not isinstance(views, list) or len(views) < 2:
-        raise ValueError("views must contain at least two top-level views")
-    ids = [slug(view.get("id")) for view in views if isinstance(view, dict)]
-    if len(ids) != len(views):
-        raise ValueError("every view must be an object with an id")
-    if len(ids) != len(set(ids)):
-        raise ValueError("view ids must be unique")
-    reading_path = (document.get("shell") or {}).get("reading_path", [])
-    for item in reading_path:
-        if slug(item.get("view_id")) not in ids:
-            raise ValueError(f"reading path references unknown view: {item.get('view_id')}")
-    for view in views:
-        if not view.get("label") or not view.get("title"):
-            raise ValueError(f"view {view.get('id')} requires label and title")
-        if not isinstance(view.get("blocks", []), list):
-            raise ValueError(f"view {view.get('id')} blocks must be an array")
-    return document
-
-
-def render_file(input_value: pathlib.Path | str, output_value: pathlib.Path | str) -> dict[str, Any]:
-    input_path = pathlib.Path(input_value).expanduser().resolve()
-    output_path = pathlib.Path(output_value).expanduser().resolve()
-    if not input_path.is_file():
-        raise ValueError(f"input not found: {input_path}")
-    if output_path.exists():
-        raise ValueError(f"refusing to overwrite existing output: {output_path}")
-    document = validate_viewmodel(json.loads(input_path.read_text(encoding="utf-8")))
-    assets = normalize_assets(document.get("assets"), input_path.parent)
-    views = document["views"]
-    shell = document.get("shell", {})
-    sidebar_tabs = bool(shell.get("sidebar_tabs"))
-
-    def primary_tabs(view: dict[str, Any]) -> list[dict[str, Any]]:
-        for block in view.get("blocks", []):
-            if isinstance(block, dict) and block.get("type") == "tabs":
-                return block.get("tabs", [])
-        return []
-
-    nav_groups = []
-    for view in views:
-        view_id = slug(view["id"])
-        children = primary_tabs(view) if sidebar_tabs else []
-        child_html = ""
-        if children:
-            child_buttons = []
-            for index, tab in enumerate(children):
-                tab_id = slug(tab.get("id", f"tab-{index + 1}"))
-                badge = tab.get("badge")
-                badge_html = f'<span class="nav-child-badge">{esc(badge)}</span>' if badge not in (None, "") else ""
-                child_buttons.append(
-                    f'<button type="button" class="nav-child" data-child-view="{esc(view_id)}" data-child-tab="{esc(tab_id)}">'
-                    f'<span>{esc(tab.get("label", tab_id))}</span>{badge_html}</button>'
-                )
-            child_html = f'<div class="nav-children" data-nav-children="{esc(view_id)}">{"".join(child_buttons)}</div>'
-        chevron = '<span class="nav-chevron" aria-hidden="true">⌄</span>' if children else ""
-        nav_groups.append(
-            f'<div class="nav-group" data-nav-group="{esc(view_id)}">'
-            f'<button type="button" class="nav-parent" data-view-target="{esc(view_id)}"><span class="nav-dot"></span><span>{esc(view["label"])}</span>{chevron}</button>'
-            f'{child_html}</div>'
-        )
-    nav = "".join(nav_groups)
-
-    reading_items = []
-    for index, item in enumerate(shell.get("reading_path", []), 1):
-        tab_attr = f' data-reading-tab="{esc(slug(item["tab_id"]))}"' if item.get("tab_id") else ""
-        reading_items.append(
-            f'<button type="button" data-reading-view="{esc(slug(item["view_id"]))}"{tab_attr}>'
-            f'<span class="reading-step">{index}</span><span>{esc(item["label"])}</span></button>'
-        )
-    reading_path = (
-        '<nav class="reading-path" id="readingPath" aria-label="报告阅读路径">'
-        '<b>阅读路径</b><div class="reading-items">' + '<span class="reading-arrow">→</span>'.join(reading_items) + '</div></nav>'
-        if reading_items else ""
-    )
-
-    renderer = Renderer(document, assets)
-    rendered_views = []
-    for index, view in enumerate(views):
-        hidden = "" if index == 0 else " hidden"
-        badge = view.get("badge")
-        badge_html = ""
-        if badge:
-            badge_html = f'<span class="tag tone-{esc(slug(badge.get("tone", "info")))}">{esc(badge.get("text", ""))}</span>' if isinstance(badge, dict) else f'<span class="tag tone-info">{esc(badge)}</span>'
-        heading = f'<div class="page-heading"><div><div class="eyebrow">{esc(view.get("eyebrow", ""))}</div><h1>{esc(view["title"])}</h1><p>{esc(view.get("subtitle", ""))}</p></div>{badge_html}</div>'
-        content = renderer.render_blocks(view.get("blocks", []))
-        rendered_views.append(f'<section class="view" data-view="{esc(slug(view["id"]))}" id="view-{esc(slug(view["id"]))}" tabindex="-1"{hidden}>{heading}{content}</section>')
-
-    meta = document["meta"]
-    status = "".join(f"<div>{esc(line)}</div>" for line in shell.get("status", []))
-    search = '<input class="search" id="search" type="search" placeholder="{}">'.format(esc(shell.get("search_placeholder", "搜索当前视图"))) if shell.get("search", True) else ""
-    date = f'<div class="date-chip" id="dateRange">{esc(shell.get("date_range", ""))}</div>' if shell.get("date_range") else ""
-    replacements = {
-        "__TITLE__": esc(meta["title"]),
-        "__CLI_VERSION__": esc(CLI_VERSION),
-        "__CONTRACT__": esc(CONTRACT),
-        "__EXTERNAL_IMAGE_POLICY__": esc(str(meta.get("external_images", "forbid"))),
-        "__BRAND_MARK__": esc(shell.get("brand_mark", "CI")),
-        "__BRAND_TITLE__": esc(shell.get("brand_title", meta["title"])),
-        "__BRAND_SUBTITLE__": esc(shell.get("brand_subtitle", "Commerce Insight")),
-        "__TOP_TITLE__": esc(meta["title"]),
-        "__TOP_META__": esc(meta.get("subtitle", "")),
-        "__NAV_LABEL__": esc(shell.get("nav_label", "报告视图")),
-        "__NAV__": nav,
-        "__BODY_CLASS__": "sidebar-tabs" if sidebar_tabs else "",
-        "__READING_PATH__": reading_path,
-        "__STATUS__": status,
-        "__TOOLS__": search + date,
-        "__VIEWS__": "".join(rendered_views),
-        "__FOOTER__": esc(meta.get("footer", "")),
-        "__VIEW_IDS__": json.dumps([slug(view["id"]) for view in views], ensure_ascii=False),
-    }
-    template = (ROOT / "templates" / "workbench.html").read_text(encoding="utf-8")
-    for marker, value in replacements.items():
-        if marker not in template:
-            raise ValueError(f"template marker missing: {marker}")
-        template = template.replace(marker, value)
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(template, encoding="utf-8")
-    return {
-        "ok": True,
-        "output": str(output_path),
-        "cli_version": CLI_VERSION,
-        "contract": CONTRACT,
-        "views": len(views),
-        "assets_embedded": len(assets),
-        "bytes": output_path.stat().st_size,
-    }