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

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

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

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:

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

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.