paper-explain-figures

paper-explain-figures

ユーザーが提供した 1 枚以上の論文 Figure について：

• Figure を .jpg に変換します（視覚的な理解に使用します。変換に失敗した場合は元画像を保持し、その旨を明示します）。
• Figure の近くから「その図を生成したソースコード」を自動検索します（見つからない場合があります。見つからない場合は NULL とします）。
• 次の 3 種類の情報を総合し、読みやすいレポートを出力します。
  • 理解 1：視覚的な理解（jpg／元画像を直接読み取る）
  • 理解 2：ソースコードの理解（コードを基準とします。コードが図の本当の意味を決定します）
  • 理解 3：ユーザーによる解釈（ユーザーの関心事を推測するのに役立ちますが、誤っている可能性があります）

入力

ユーザーは次の情報を 1 つ以上入力します。

• 1 つ以上の Figure ファイルの絶対パス
• 任意：Figure に対する手動での解釈（全体向け、または Figure ごとに指定）
• 任意：ユーザーがソースコードファイルの絶対パスを明示（「候補となるエントリーポイント」として優先）

フロー

入力

ユーザーの依頼と設定ファイルに従って必要な入力を用意します。不足している情報を明示し、その入力に依存する手順を停止します。

実行手順

• この skill の設計上の欠陥が原因のバグは、まず bensz-collect-bugs を使って ~/.bensz-skills/bugs/ に所定の形式で記録します。ユーザーのローカルにインストール済みの skill のソースコードを直接変更しないでください。回避策がある場合は、まずバグを記録してからタスクを続行します。
• ユーザーが「report bensz skills bugs」などの公開報告を明示的に求めた場合に限り、ローカルの gh を使って新しいバグを huangwb8/bensz-bugs にアップロードします。リポジトリ全体を pull／clone しないでください。

ファイルの場所： xxx ソースコード： xx.R 第xxx-xxx行

図の中心的な意味

...

変数の定義

要素	定義
...	...

解釈のポイント

1. ...
2. ...

説明

...

科学的価値

...

为保证“每张图的解读相互独立”，本 skill 采用 worker 脚本在 shell 中启动独立进程执行：

- `codex exec "..."`（推荐：更容易做本地文件读取 + 视觉理解）
- `claude -p "..."`（可选）

并发上限默认 **3**（可在 `paper-explain-figures/config.yaml` 调整）。

在当前目录运行（推荐，产物会落到当前目录与 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/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 がシステムレベルでインストールされている場合（パスはプラットフォームによって異なります。以下は一例です）：

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

よく使うパラメーター（必要に応じて）：

# 启用并行（默认串行，减少 API 限流/封禁风险）
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel

# 并发上限（默认 3；也可改 config.yaml:defaults.max_parallel）
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --parallel --max-parallel 3

# 指定 runner（codex/claude/local）
python3 paper-explain-figures/scripts/paper_explain_figures.py --fig /abs/path/to/figure.png --runner codex

⚠️ セキュリティに関する注意：--runner shell は無効になっています。「中間ファイルを .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/paper-explain-figures の外に絶対に漏らさないこと」を厳密に保証できないためです。

トリガーディレクトリで実行します。

rm -rf .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/paper-explain-figures

出力

• 最終レポート：デフォルトでは現在の作業ディレクトリの paper-explain-figures_report.md に出力します。
• すべての中間ファイルとログ：.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/paper-explain-figures/ に保存します（run／job ごとにディレクトリを分けて保存）。

各図は、同じ Markdown ファイル内で ## レベルの見出しに分けて記載します。

# Figures

### 输出管理

本 Skill 的新任务中间文件统一写入 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/`。同一任务复用一个任务根目录；多 Skill 协作才创建 `shared/`。正式交付物不写入该目录，历史隐藏目录只允许显式兼容读取、迁移或清理。

### 校验

完成后执行 Skill 已有的静态检查、脚本验证或人工复核，并记录通过标准。

### 失败与恢复

保留错误证据和已完成产物；仅在输入、环境或外部依赖恢复后从最近的失败步骤重试。

## 约束

- **目录管理硬约束**：所有中间产物必须托管在当前工作目录下的隐藏目录 **`.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/paper-explain-figures/`**（该目录名在脚本中硬编码；不允许改到别处）。
- **运行时隔离硬约束**：runner / 图片转换器产生的 HOME、TMP、XDG cache/state/config 等运行时辅助文件，也必须重定向并收纳到 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/paper-explain-figures/` 内。
- **只读约束**：全程只读访问用户的 Figure 与源代码文件；严禁修改它们（包括格式化/重写/覆盖）。

### 公共硬约束

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- 仅将 Skill 或 Bensz 基础设施本身的设计缺陷交给 `bensz-collect-bugs`；先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。


### Skill 专属约束

不得超出本 Skill description 和上方流程所声明的范围；不将未验证的信息伪装成确定结论。