Back to Details

paper-explain-figures

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

paper-explain-figures

paper-explain-figures

与 bensz-collect-bugs 的协作约定

Collaboration Agreement with bensz-collect-bugs

  • 因本 skill 设计缺陷导致的 bug，先用 
    bensz-collect-bugs
    规范记录到 
    ~/.bensz-skills/bugs/
    ，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。
  • 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地 
    gh
    上传新增 bug 到 
    huangwb8/bensz-bugs
    ；不要 pull / clone 整个仓库。
  • For bugs caused by design flaws of this skill, first use 
    bensz-collect-bugs
    to record them in 
    ~/.bensz-skills/bugs/
    in a standardized manner, do not directly modify the skill source code installed locally by the user; if there is a workaround, record the bug first, then continue to complete the task.
  • Only when the user explicitly requests actions like "report bensz skills bugs" for public submission, use the local 
    gh
    to upload new bugs to 
    huangwb8/bensz-bugs
    ; do not pull / clone the entire repository.

目标

Objectives

对用户提供的 1 张或多张论文 Figure：
  • 将 Figure 转为 
    .jpg
    （用于视觉理解；转换失败则保留原图并显式说明）
  • 在 Figure 附近自动检索“生成该图的源代码”（可能找不到；找不到则为 
    NULL
    ）
  • 综合三类信息输出可读性强的报告：
    • 理解 1：视觉理解（从 jpg/原图直接读图）
    • 理解 2：源代码理解（以代码为准；代码决定图的真实含义）
    • 理解 3：用户人工解读（帮助猜测用户关注点；可能有误）
For one or more paper figures provided by the user:
  • Convert the figures to 
    .jpg
    (for visual understanding; if conversion fails, retain the original image and explicitly state this)
  • Automatically retrieve the "source code used to generate the figure" near the figure (may not be found; set to 
    NULL
    if not found)
  • Output a highly readable report integrating three types of information:
    • Understanding 1: Visual understanding (directly read the figure from jpg/original image)
    • Understanding 2: Source code understanding (based on code; code determines the true meaning of the figure)
    • Understanding 3: User's manual interpretation (helps guess the user's focus; may be incorrect)

强约束（必须遵守）

Strict Constraints (Must Be Followed)

  • 目录管理硬约束：所有中间产物必须托管在当前工作目录下的隐藏目录 
    .paper-explain-figures/
    （该目录名在脚本中硬编码；不允许改到别处）。
  • 运行时隔离硬约束：runner / 图片转换器产生的 HOME、TMP、XDG cache/state/config 等运行时辅助文件，也必须重定向并收纳到 
    .paper-explain-figures/
    内。
  • 只读约束：全程只读访问用户的 Figure 与源代码文件；严禁修改它们（包括格式化/重写/覆盖）。
  • Hard Constraint on Directory Management: All intermediate products must be hosted in the hidden directory 
    .paper-explain-figures/
     under the current working directory (this directory name is hard-coded in the script; redirecting to other locations is not allowed).
  • Hard Constraint on Runtime Isolation: Runtime auxiliary files such as HOME, TMP, XDG cache/state/config generated by the runner / image converter must also be redirected and stored in 
    .paper-explain-figures/
    .
  • Read-Only Constraint: Only read-only access is allowed to the user's figures and source code files throughout the process; modifying them (including formatting/rewriting/overwriting) is strictly prohibited.

输入

Input

用户会输入 1 个或多个信息：
  • 1 个或多个 figure 文件的绝对路径
  • 可选：对 figure 的人工解读（全局或按 figure 分配）
  • 可选：用户显式给出源代码文件绝对路径（优先作为“候选入口”）
The user will input one or more pieces of information:
  • Absolute paths to one or more figure files
  • Optional: Manual interpretation of the figures (global or per-figure)
  • Optional: The user explicitly provides the absolute path to the source code file (prioritized as a "candidate entry")

输出

Output

  • 最终报告：默认输出到当前工作目录 
    paper-explain-figures_report.md
  • 所有中间文件与日志：落到 
    .paper-explain-figures/
    （按 run/job 分目录保存）
  • Final report: By default, output to 
    paper-explain-figures_report.md
    in the current working directory
  • All intermediate files and logs: Stored in 
    .paper-explain-figures/
    (saved in directories by run/job)

标准报告格式（每张图必须按此结构输出）

Standard Report Format (Must Follow This Structure for Each Figure)

每张图在同一个 Markdown 文件中以 
##
级标题分隔：
markdown
undefined
Each figure is separated by a 
##
level heading in the same Markdown file:
markdown
undefined

Figures

Figures

Figure: xxx

Figure: xxx

文件位置： xxx 源代码： xx.R 第xxx-xxx行
File location: xxx Source code: xx.R lines xxx-xxx

图表核心含义

Core Meaning of the Chart

...
...

变量定义

Variable Definitions

元素定义
......
ElementDefinition
......

解读要点

Key Interpretation Points

  1. ...
  2. ...
  1. ...
  2. ...

解释

Explanation

...
...

科学价值

Scientific Value

...
undefined
...
undefined

技术路径（进程级隔离 + 并发上限）

Technical Approach (Process-Level Isolation + Concurrency Limit)

为保证“每张图的解读相互独立”，本 skill 采用 worker 脚本在 shell 中启动独立进程执行：
  • codex exec "..."
    （推荐：更容易做本地文件读取 + 视觉理解）
  • claude -p "..."
    （可选）
并发上限默认 3（可在 
paper-explain-figures/config.yaml
调整）。
To ensure "mutual independence of interpretation for each figure", this skill uses worker scripts to launch independent processes in the shell for execution:
  • codex exec "..."
    (Recommended: Easier for local file reading + visual understanding)
  • claude -p "..."
    (Optional)
The default concurrency limit is 3 (adjustable in 
paper-explain-figures/config.yaml
).

使用方式（建议）

Usage Recommendations

在当前目录运行（推荐，产物会落到当前目录与 
.paper-explain-figures/
）：
bash
python3 paper-explain-figures/scripts/paper_explain_figures.py \
  --fig /abs/path/to/figure1.png \
  --fig /abs/path/to/figure2.pdf \
  --note "你对这些图的关注点/背景解释（可选）"
如果该 skill 已做系统级安装（路径因平台而异，以下仅示例）：
bash
python3 ~/.codex/skills/paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png
常用参数（按需）：
bash
undefined
Run in the current directory (recommended, products will be stored in the current directory and 
.paper-explain-figures/
):
bash
python3 paper-explain-figures/scripts/paper_explain_figures.py \
  --fig /abs/path/to/figure1.png \
  --fig /abs/path/to/figure2.pdf \
  --note "Your focus/background explanation for these figures (optional)"
If the skill has been installed system-wide (path varies by platform, the following is only an example):
bash
python3 ~/.codex/skills/paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png
Common parameters (as needed):
bash
undefined

启用并行（默认串行，减少 API 限流/封禁风险）

Enable parallelism (serial by default to reduce API rate limiting/banning risks)

python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel

并发上限（默认 3；也可改 config.yaml:defaults.max_parallel）

Concurrency limit (default 3; can also modify config.yaml:defaults.max_parallel)

python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel --max-parallel 3
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel --max-parallel 3

指定 runner（codex/claude/local）

Specify runner (codex/claude/local)

python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --runner codex

⚠️ 安全提示：`--runner shell` 已禁用，因为它无法对“.paper-explain-figures 之外绝不泄露中间文件”提供严格保证。
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --runner codex

⚠️ Security Note: `--runner shell` has been disabled because it cannot provide strict guarantees that "no intermediate files will be leaked outside .paper-explain-figures".

清理方式

Cleanup Method

在触发目录执行：
bash
rm -rf .paper-explain-figures
Execute in the trigger directory:
bash
rm -rf .paper-explain-figures