nsfc-roadmap

NSFC 技術ロードマップ生成ツール

bensz-collect-bugs との連携に関する取り決め

• ユーザー環境で、このスキルの設計上の欠陥に起因するバグが発生した場合は、まず bensz-collect-bugs を使用して、規定に従い ~/.bensz-skills/bugs/ に記録してください。ユーザーのローカル環境にある Claude Code / Codex にインストール済みのスキルのソースコードを直接変更することは厳禁です。
• AI がワークアラウンドを使ってユーザーのタスクを続行できる場合は、まずバグを記録してから、現在のタスクを続行してください。
• ユーザーが「report bensz skills bugs」などの公開報告を明確に求めた場合は、ローカルの gh と bensz-collect-bugs を呼び出し、新規バグのみを huangwb8/bensz-bugs にアップロードしてください。バグリポジトリ全体の pull / clone は行わないでください。

位置付け

• NSFC 申請書の研究内容、技術ロードマップ、リスク管理を、印刷可能で A4 サイズで読みやすいロードマップに変換します。
• デフォルトのワークフローは決定論的な drawio レンダリングです。ユーザーが Nano Banana 画像モデルを明確に求めた場合に限り、PNG のみの出力に切り替えられます。
• このスキルは科学研究の執筆と可視化表現のみを対象とし、公式の審査基準や助成の決定を示すものではありません。

入力

次のうち少なくとも 1 つを指定してください。

• proposal_path：申請書のディレクトリ。推奨。
• proposal_file：単一の入力ファイル。
• spec_file：構造化された図の仕様ファイル。最も細かく制御できます。

任意項目：

• rounds：デフォルトでは config.yaml:evaluation.max_rounds を読み込みます。
• output_dir：デフォルトは roadmap_output/ です。
• renderer：デフォルトは drawio です。ユーザーが明確に求めた場合に限り nano_banana を使用します。
• dotenv：nano_banana のみで使用します。
• style_ref_images：nano_banana のみで使用し、先頭から最大 4 枚までです。
• layout / template_ref：高度なオプションです。通常は不要です。

出力

デフォルトで納品するファイル：

• roadmap.drawio
• roadmap.svg
• roadmap.png
• roadmap.pdf
• roadmap-plan.md

中間生成物は output_dir/.nsfc-roadmap/ に格納されます。

• runs/run_*/round_*
• spec_latest.yaml
• optimization_report.md
• config_used_best.yaml
• evaluation_best.json
• config_local.yaml
• ai/：stop_strategy=ai_critic の場合のリクエスト／レスポンスのプロトコル

Nano Banana モードで納品するファイル：

• roadmap.png
• roadmap_compacted.png

必須ルール

• まず config.yaml を読み込んでください。以下のフィールドを単一の信頼できる情報源とします：renderer、evaluation、layout、color_scheme、planning、output。
• ユーザーが明示的に提供したファイルまたはディレクトリのみを処理してください。申請書はデフォルトで機密情報として扱います。
• デフォルトでは素材の補完のためにインターネットへ接続しません。ユーザーが接続を求めた場合は、事前にリスクを伝えてください。
• デフォルトの drawio ワークフローを維持してください。「画像モデルのほうが速い」という理由だけで、レンダリングバックエンドを勝手に切り替えないでください。
• 内容が詰まりすぎている場合は、文字サイズを小さくして閾値を無理に超えるのではなく、spec のノード文言、グループ分け、または構造を優先して調整してください。

ワークフロー

1. 計画

• spec_file が指定されている場合は、この手順を省略できます。
• デフォルトでは config.yaml:planning.planning_mode=ai を使用します。
  1. plan_roadmap.py を実行して plan_request.json/plan_request.md を生成します。
  2. ホスト AI が roadmap-plan.md と spec_draft.yaml を作成します。
  3. スクリプトを再度実行して spec_draft.yaml を検証します。
• 計画段階では、立項根拠と研究内容の両方を確認してください。「2.1 研究内容」だけを確認するのでは不十分です。

2. spec に反映

• 優先順位：ユーザー提供の spec_file > 計画段階の spec_draft.yaml > 入力ファイルからの自動抽出。
• spec では、少なくとも段階、ノード、入出力、リスク／代替案を明確にしてください。
• テンプレートフィールドは任意です。デフォルトでは特定の template_ref への紐付けを必須としません。

3. 決定論的レンダリング

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 5

• レンダリング時に spec_latest.yaml を確定します。
• 納品ファイルと各ラウンドのエビデンスを生成します。
• draw.io CLI がない場合は、設定に従って通知、フォールバック、または停止します。

4. 評価と最適化

• デフォルトの最大ラウンド数は 5 です。具体的には config.yaml:evaluation の設定に従います。
• 各ラウンドで、少なくとも以下の 3 種類の問題を特定します。
  • P0：研究内容の欠落、論理の断絶、孤立したノード、判読不能
  • P1：レイアウトの混乱、配色による妨げ、文字サイズが小さすぎる
  • P2：間隔、余白、矢印の明瞭さなどの一般的な改善
• 停止戦略は設定のみを参照します：early_stop、stop_strategy=plateau、または stop_strategy=ai_critic
• 多次元のセルフチェックでは、デフォルトで structure / visual / readability を確認します。

5. 任意：AI による自律的な反復

• 「続行するか、どこを修正するか」をホスト AI に判断させるには、config_local.yaml で evaluation.stop_strategy: ai_critic を有効にします。
• スクリプトは output_dir/.nsfc-roadmap/ai/ の下に以下を生成します。
  • ai_critic_request.md
  • ai_critic_response.yaml
  • 各ラウンドの ai_pack_round_XX/

6. 任意：Nano Banana による PNG のみの出力（Gemini / OpenAI gpt-image-2）

• ユーザーが明確に求めた場合に限り有効にします。
• まず接続性を確認します。

python3 nsfc-roadmap/scripts/nano_banana_check.py

• .env で IMAGE_PROVIDER=openai を指定すると OpenAI に切り替えられます。明示的に指定されていない場合は、既存の GEMINI_* 設定を優先して使用します。

• その後、PNG を生成します。

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 1 \
  --renderer nano_banana

よく使うコマンド

# 规划
python3 nsfc-roadmap/scripts/plan_roadmap.py --proposal /path/to/proposal --output ./roadmap_output

# 生成
python3 nsfc-roadmap/scripts/generate_roadmap.py --spec-file ./roadmap_output/spec.yaml --output-dir ./roadmap_output --rounds 5

# 图片模型连通性
python3 nsfc-roadmap/scripts/nano_banana_check.py

参考資料

• config.yaml
• references/models/templates.yaml
• references/models/README.md
• assets/evaluation_rubric.md