first commit

文档润色流和知识库构建流/claude-scholar/skills/publication-chart-skill/references/execution-and-verification.md

@@ -0,0 +1,159 @@
+# Execution and Verification
+
+## Goal
+
+Turn a high-level publication figure/table request into a route that is actually runnable in the current environment.
+
+## Minimum environment probe
+
+Prefer the lightest useful checks.
+
+### Preferred bundled probe
+
+```bash
+python3 scripts/ensure_publication_tooling.py --require pubfig --json
+python3 scripts/ensure_publication_tooling.py --require pubtab --json
+```
+
+The helper probes availability, force-installs missing dependencies into the active interpreter, and returns the post-install status.
+
+### Equivalent manual checks
+
+```bash
+python -c "import pubfig; print(pubfig.__version__)"
+python -c "import pubtab; print(pubtab.__version__)"
+pubtab --help
+```
+
+Do not spend the whole turn on setup if the user primarily needs design guidance. Just identify whether the route is executable now or should degrade gracefully.
+
+## Automatic installation policy
+
+If a dependency is missing and the task requires real execution, install it automatically before continuing.
+
+### Preferred bundled route
+
+Use the bundled helper when it is present:
+
+```bash
+python3 scripts/ensure_publication_tooling.py --require pubfig
+python3 scripts/ensure_publication_tooling.py --require pubtab
+```
+
+The helper chooses `uv pip install --python <active-python>` when the project is clearly `uv`-managed, and otherwise falls back to `python -m pip install ...`.
+
+### Equivalent manual install commands
+
+```bash
+uv pip install --python "$VIRTUAL_ENV/bin/python" pubfig
+uv pip install --python "$VIRTUAL_ENV/bin/python" pubtab
+python -m pip install pubfig
+python -m pip install pubtab
+```
+
+### Required follow-up
+
+After installation:
+
+1. re-run the availability probe,
+2. report the updated environment status,
+3. continue with the runnable figure/table workflow.
+
+If installation fails, capture the exact error and then fall back to design/specification guidance.
+
+## Route selection
+
+### Use `pubfig` when
+
+- the task is primarily a figure,
+- the user already has Python data structures,
+- the result is a plot family already covered by `pubfig`,
+- export quality matters immediately.
+
+### Use `pubtab` when
+
+- the task is primarily a publication table,
+- the input is an Excel workbook, a `.tex` table, or a file-driven workflow,
+- the reader needs exact values,
+- previewing the table before manuscript insertion matters.
+
+### Use both when
+
+- the figure carries the visual pattern,
+- the table preserves exact benchmark values,
+- the paper section benefits from one fast visual plus one exact-value artifact.
+
+## First runnable verification
+
+### `pubfig`
+
+After generating a minimal figure route, the first useful verification is:
+
+- can the code execute,
+- does `save_figure(...)` or `batch_export(...)` produce the expected files,
+- do output suffixes match the intended formats.
+
+### `pubtab`
+
+After generating a minimal table route, the first useful verification is:
+
+- can `xlsx2tex` or `tex2xlsx` run,
+- can `preview` render PNG or PDF,
+- does the chosen backend (`tabular` or `tabularray`) match the manuscript need.
+
+## Current practical notes
+
+### `pubfig`
+
+Useful export primitives include:
+
+- `save_figure(...)`
+- `batch_export(...)`
+- `export_panel(...)`
+- `export_panels(...)`
+
+Use panel export only when multi-panel assembly is truly needed.
+
+### `pubtab`
+
+Useful file-oriented routes include:
+
+- `pubtab xlsx2tex ...`
+- `pubtab tex2xlsx ...`
+- `pubtab preview ...`
+
+Remember:
+
+- `xlsx2tex` exports all sheets by default when `--sheet` is not set,
+- `preview` can render PNG or PDF,
+- `--latex-backend tabularray` should be chosen only when the manuscript/backend requires `tblr`,
+- when preview reliability is the immediate priority, validate the table body first and add final `caption` / `label` in a separate manuscript-facing step if needed.
+
+## Graceful degradation
+
+If the tool is missing:
+
+- first try the bundled auto-install helper,
+- if that route is unavailable, use the manual install commands above,
+- if installation still fails, provide:
+  - the artifact recommendation,
+  - the exact files the user should prepare,
+  - a draft CLI or Python route,
+  - the export targets,
+  - and the publication QA checklist.
+
+## Default output wording
+
+When the route is runnable now, say:
+
+- what to run,
+- what files should appear,
+- what to inspect next.
+
+When the route is not runnable now, say:
+
+- what is missing,
+- which helper command or install command was attempted,
+- whether the install succeeded or failed,
+- what the intended route will be after install,
+- and what design decision can already be locked in today.