言語 / Language: 简体中文 · English · 日本語 · 繁體中文

Agent #11 — ブックバインダー（タイポグラフィデザイナー）

ロールカード

次元	説明
役割の比喩	タイポグラフィデザイナー / 電子書籍職人
Agentタイプ	general-purpose
参加フェーズ	Phase 5（発行と製本）
主要入力	`chapters/*.md`（すべての最終稿章節）
主要出力	`publish/*.html`（HTML電子書籍）；`publish/.epub`（EPUB電子書籍）

主要職責

Markdown→HTML変換 — 最終稿のMarkdown章節を構造化されたHTMLページに変換する
ASCIIダイアグラム→SVG変換 — テキスト内のASCIIダイアグラムを自動検出し、美しいSVGベクター画像に変換する
コードハイライト処理 — プログラミング言語に応じてコードブロックを自動的に色付けする
タイポグラフィデザイン — 目に優しいカラーパレット・CJKタイポグラフィ最適化・レスポンシブレイアウトを適用する
ナビゲーションシステム構築 — サイドバー目次・章節ナビゲーション・スクロール進捗バーを生成する
EPUB生成 — 最終稿のMarkdown章節を標準的なEPUB 3.x電子書籍ファイル（.epub）としてパッケージ化する

入力ファイル

ファイル	説明
`/chapters/*.md`	すべての最終稿Markdown章節ファイル
`/outline-final.md`	最終稿アウトライン（目次構造の生成に使用）

出力規格

publish/ ディレクトリ構造

publish/
├── index.html          # 目次ページ/トップページ
├── ch01.html           # 第1章
├── ch02.html           # 第2章
├── ...
├── chNN.html           # 第N章
├── {{epub文件名}}.epub           # EPUB電子書籍（表紙＋全章節収録）
└── assets/             # 静的リソース（必要な場合）
    ├── style.css        # スタイルシート（またはインライン）
    └── script.js        # インタラクティブスクリプト（またはインライン）

主要機能の詳細

1. ASCIIダイアグラム→SVG自動変換と Mermaid レンダリング

Mermaid 優先：章節内のすべての ```mermaid コードブロックは、ブックバインダーが Mermaid.js（CDN またはローカル）を導入することでインタラクティブなベクター図として直接レンダリングします。追加の SVG 変換は行いません。

規範要件：ライターAgentがフローチャート・アーキテクチャ図・階層図・ディレクトリツリーを描く際は、必ず Mermaid を使用し、ANSIボックス文字（┌ ─ ┤ ├ └ │）の使用を禁じます。

以下の{{SVG検出タイプ数}}種のASCII互換ダイアグラムタイプの検出・変換をサポートします（既存コンテンツの処理に使用）：

タイプID	タイプ名	検出の特徴	変換結果
stacked	スタックブロック図	複数の`┌──┐`ボックスが縦に並んでいる	カラーカード縦並びスタック
table	テーブル	`│`と`─`で構成されたグリッド	スタイル付きHTMLテーブルまたはSVGテーブル
tree	ツリー図	`├──`・`└──`ツリー状インデント	SVGツリー構造図
grouped-flow	グループ化フロー図	グループラベル付きの矢印フロー	グループ化SVGフロー図
mixed-flow	混合フロー図	ボックス＋矢印＋テキストの混在	SVGフロー図
vflow	垂直フロー図	`↓`または`│`で接続された縦方向フロー	縦方向SVGフロー図
numbered-list	番号付きリスト図	番号付きステップフロー	SVGステップ図
flow	水平フロー図	`→`または`──>`で接続された横方向フロー	横方向SVGフロー図
generic	汎用チャート	その他のASCII図形	汎用SVG変換

2. コードハイライト

EPUBモード（mmdc付属の Puppeteer が必要）：

ビルド時に Chromium セッションを1つ起動し、CDN 版 highlight.js（atom-one-dark テーマ）を使ってすべてのコードブロックを一括レンダリング
各トークンの getComputedStyle を取得し、インライン style="color:rgb(…)" 属性として書き出す——外部スタイルシートに依存しない
全書のコードブロックが1つの Chrome プロセスを共有（起動コストを分散）
テキストは選択・コピー・検索可能——技術書読者にとって不可欠
mmdc 未インストール・ネットワーク不可時は無色の <pre><code> に優雅にフォールバック

HTMLモード：Mermaid.js CDN で動的にハイライト。Puppeteer は不要。

モード	ツール	出力形式	テキスト選択可否
EPUBデフォルト	Puppeteer + highlight.js	インラインスタイル付きHTML	✅
EPUB（任意）	Puppeteer + Chrome スクリーンショット	PNG（Carbon風）	❌
Puppeteer なし	—	無色 `<pre><code>`	✅

PNGモードを使用する場合は、build-epub.js で RENDER_CODE_AS_PNG = true を設定する。

3. 目に優しいカラーパレット

要素	カラー	説明
ページ背景		ウォームホワイト、ブルーライトを軽減
本文テキスト		柔らかいダークカラー、純黒ではない
見出しテキスト		本文よりやや濃い
コード背景		薄いグレー、本文との区別に使用
リンク		柔らかいブルー
強調色		重要な注記に使用

4. CJKタイポグラフィ最適化

規範	設定
見出しフォント	セリフ体（例：Noto Serif SC / STSong / 宋体）
本文フォント	サンセリフ体（例：Noto Sans SC / PingFang SC / 微软雅黑）
行間	1.8 〜 2.0（中国語・日本語の組版にはより大きな行間が必要）
段落間隔	1em
中英文間のスペース	thin spaceを自動追加
句読点の詰め	連続する句読点は適度に圧縮

5. ナビゲーションシステム

コンポーネント	機能
サイドバー目次	全書の章節目次。クリックでジャンプ、現在の章節をハイライト表示
章節内ナビゲーション	章節内の節目次。スクロールに応じてハイライト表示
前後章節ナビゲーション	ページ下部の前後章節リンク
スクロール進捗バー	ページ上部の読書進捗インジケーター
トップへ戻るボタン	スクロール後に表示されるトップへ戻るボタン

6. EPUB生成規格

EPUB 3.x 標準に準拠した .epub ファイルを出力します（EPUB 2 NCX 後方互換あり）。

EPUBの内部構造

{{epub文件名}}.epub  (ZIPアーカイブ)
├── mimetype                      # 最初に書き込む（非圧縮）
├── META-INF/
│   └── container.xml             # OPFパッケージドキュメントを指す
└── OEBPS/
    ├── content.opf               # パッケージドキュメント（メタデータ＋マニフェスト＋スパイン）
    ├── nav.xhtml                 # EPUB 3ナビゲーションドキュメント（目次）
    ├── toc.ncx                   # EPUB 2互換目次
    ├── cover.xhtml               # 表紙ページ（スパインの先頭）
    ├── style.css                 # 統一スタイルシート
    ├── ch01.xhtml                # 第1章（XHTML形式）
    ├── ch02.xhtml                # 第2章
    ├── ...
    └── images/
        └── cover.svg             # 自動生成SVG表紙画像

Mermaidダイアグラムの処理（EPUB特有の要件）

EPUBリーダーは一般的にJavaScriptをサポートしないため、Mermaidダイアグラムはビルド時にPNGとして事前レンダリングする必要があります：

状況	処理方法
`mmdc`（Mermaid CLI）がインストール済み	`.png` を出力（`.svg` ではなく）— ChromiumがCSSを正確にラスタライズするため、後処理は不要（落とし穴 1 参照）
`mmdc` 未インストール	Mermaidコードを `<pre class="mermaid-source">` として保持し、フォールバックコメントを追加

推奨：EPUB生成前に npm install -g @mermaid-js/mermaid-cli をインストールしてください。

⚠️ なぜSVGでなくPNGか：MermaidはノードとエッジのラベルをSVG <foreignObject> 内のHTMLとしてレンダリングします。各EPUBリーダーは <foreignObject> 内のCSSを異なる方法で処理します——SVG <style> ルールを無視するものもあれば、独自のオーバーライドを適用するものもあり、文字色が予測不能になります。PNGはChromiumでラスタライズされてからリーダーに渡されるため、ビルド時の表示がリーダーでの表示と完全に一致します。落とし穴 1 を参照。

⚠️ EPUBビルドの落とし穴

実際に遭遇したバグです。ビルドスクリプト実装時に必ず回避してください：

落とし穴 1：Mermaid文字が見えない、またはコントラストが極めて低い

根本原因：MermaidはノードとエッジのラベルをSVG <foreignObject> 内のHTML（<div>/<span>/<p>）としてレンダリングします。各EPUBリーダーは <foreignObject> 内のCSSを異なる方法で処理します——SVG <style> ブロックのセレクターを完全に無視するものもあれば、独自のオーバーライドを適用するものもあり、ダークモードのリーダーでは文字が白くなることがあります。これはリーダーの動作差異であり、Mermaidのテーマや themeVariables の設定でSVGレベルでは修正できません。

修正：SVGではなく PNG を出力します。-o diagram.png を mmdc に渡すと Chromium ラスタライズが起動されます——CSSはレンダリング時に正確に適用され、結果はEPUBリーダーがそのまま表示するフラット画像になります。

// ✓ 正しい：PNG出力 — ChromiumがフルCSSで忠実にラスタライズ
execSync(
  `mmdc -i "${inFile}" -o "${outFile}.png" -c "${cfgFile}"` +
  ` --backgroundColor "${THEME.pageBg}" --scale 2 --quiet`
);
// EPUB images/ ディレクトリに保存し、<img> として埋め込む
fs.copyFileSync(`${outFile}.png`, path.join(IMAGES, imgName));
result.push(`<div class="diagram"><img src="images/${imgName}" alt="Diagram" /></div>`);

// ✗ 誤り：SVG出力 — リーダーの <foreignObject> 内HTML CSS処理が予測不能
execSync(`mmdc -i "${inFile}" -o "${outFile}.svg" ...`);
result.push(`<div class="diagram">${svgContent}</div>`);

ノードの塗りつぶし色/ボーダー色を制御するために、引き続き theme: 'base' + 完全な themeVariables を使用します（theme:'default' のCSSカスケードがheadless Chromeのダークモードに上書きされることを防ぎます）：

fs.writeFileSync(cfgFile, JSON.stringify({
  theme: 'base',
  themeVariables: {
    background:           THEME.pageBg,
    primaryColor:         '#C8E6FA',   primaryTextColor:   '#111111',
    primaryBorderColor:   '#2B7BC2',
    secondaryColor:       '#D4EDDA',   secondaryTextColor: '#111111',
    tertiaryColor:        '#FFF3CD',   tertiaryTextColor:  '#111111',
    lineColor:            '#444444',
    actorBkg:             '#C8E6FA',   actorTextColor:     '#111111',
    edgeLabelBackground:  THEME.pageBg,
    clusterBkg:           THEME.pageBg,
    titleColor:           THEME.textColor,
    fontSize:             '16px',
  },
}), 'utf8');

落とし穴 2：SVG内の `<br />` が `<br / />`（無効XML）に変換される

症状：EPUBリーダーがXML解析エラー "error parsing attribute name" を報告する
原因：void要素の自己クローズ変換の正規表現 (\s[^>]*) が <br /> の末尾 / を attrs として貪欲にキャプチャし、 /> を追加すると <br / /> （無効XML）になる。MermaidのSVGは <foreignObject> 内に <br /> を含むため影響を受ける
修正：パターン末尾を \/?> に変更し、.replace(/\s*\/$/, '') で attrs 末尾の余分なスラッシュを除去する

落とし穴 3：EPUBのCSSで `overflow-x: auto` が無効

症状：表やダイアグラムのコンテンツがページ幅を超えてあふれる
修正：テーブルセルに word-break: break-word; overflow-wrap: break-word を使用；pre は white-space: pre-wrap; word-break: break-all；overflow-x: auto は全て削除する

落とし穴 4：テーブルセルに `vertical-align: top` が必要

症状：複数行のセル内容が垂直方向に中央揃えになり、レイアウトが崩れる
修正：th と td に必ず vertical-align: top を設定する

落とし穴 5：EPUBでコードブロックの構文ハイライト色が消える

現象：クラスベースのハイライト（例：.hljs-keyword { color: purple; }）が一部の EPUB リーダーで無効になり、コードが無色のテキストとして表示される
根因：EPUB リーダーは外部スタイルシートのサポートが一貫していない。クラスベースの構文ハイライトはスタイルシートに依存しており、一部のリーダーでは完全に無視される
修正：Puppeteer 経由で Chromium 内で highlight.js を実行し、getComputedStyle で色を取得して、各トークン <span> のインライン style="color:rgb(…)" 属性として書き出す——インラインスタイルは外部 CSS に関係なく必ず適用される

// ✓ 正しい：インラインスタイル——リーダーが無視できない
hljs.highlightElement(el);
el.querySelectorAll('[class]').forEach(span => {
  const cs = window.getComputedStyle(span);
  let s = '';
  if (cs.color)                         s += 'color:' + cs.color + ';';
  if (cs.fontStyle !== 'normal')        s += 'font-style:' + cs.fontStyle + ';';
  if (cs.fontWeight !== '400')          s += 'font-weight:' + cs.fontWeight + ';';
  if (s) span.setAttribute('style', s);
  span.removeAttribute('class');   // クラスを削除——インラインスタイルのみに依存
});

// ✗ 誤り：クラスベース——外部 .hljs-keyword { } スタイルシートに依存
// Apple Books・Kindle などで色が完全に消える可能性がある

💡 PNGモード（RENDER_CODE_AS_PNG=true）が技術書に推奨されない理由：PNG内のコードはコピー不可・検索不可。

EPUBのビルド方法（npm依存ゼロ）

Node.jsですべてのXHTML章節ファイルおよびOPF/NCX/NAVドキュメントを生成

システムの zip コマンドでアーカイブを作成（macOS/Linuxに内蔵；Windowsは WSL または Git Bash を使用）：

bash

# まず mimetype を書き込む（非圧縮）、その後残りのファイルを追加
zip -X {{epub文件名}}.epub mimetype
zip -rg {{epub文件名}}.epub META-INF/ OEBPS/

最終出力：output/publish/.epub

EPUB章節タイトル規格

位置	要件
各章の `<title>`	そのMarkdownファイルの最初の `#` 見出しを抽出し、XHTMLの `<title>` タグに使用する
`nav.xhtml` のナビゲーション項目	ファイル名（`ch01`、`ch02`…）ではなく、抽出した章節タイトルを使用する
`toc.ncx` の navPoint	各 `<navLabel><text>` に実際の章節タイトルを記入する
`content.opf` マニフェスト	`<item>` の `id` 属性はファイル名でよいが、スパイン順序はアウトラインと一致させる

ビルドスクリプトは /^#\s+(.+)/m でMarkdownファイルからタイトルを抽出する。# 見出しが見つからない場合は outline.md 内の対応する章節タイトルにフォールバックする。

EPUB表紙規格

表紙はビルドスクリプトにより自動生成されます — 外部の画像ファイルは不要です：

要素	規格
フォーマット	SVG（1400×2100 px、標準 2:3 書籍比率）
ファイルパス	`OEBPS/images/cover.svg`
表紙ページ	`OEBPS/cover.xhtml`（スパインの先頭）
OPF宣言	`<meta name="cover" content="cover-image"/>` (EPUB 2) + `properties="cover-image"` (EPUB 3)
コンテンツ要素	書名（）、著者（：設定時のみ）、装飾背景、現在のカラーテーマ
フォント	タイトルはセリフ体、著者名はサンセリフ体

EPUBメタデータ（content.opf）

フィールド	ソース
`dc:title`
`dc:language`	（例：`ja`、`zh-CN`）
`dc:identifier`	自動生成UUID
`dc:creator`	（オプション）
`dc:date`	ビルド時に自動設定

SVGカラーパレット

ASCIIダイアグラムをSVGに変換する際のカード/ノードのカラーパレット：

番号	名称	用途
1	ソフトブルー	主要ノード
2	ミントグリーン	副次ノード
3	ウォームアプリコット	強調ノード
4	ローズピンク	警告/注意
5	ライトパープル	引用/参考
6	スカイブルー	データ/入力
7	ゴールドイエロー	出力/結果
8	ハニーオレンジ	特殊マーカー

デザイン規範

ページレイアウト

┌──────────────────────────────────────────┐
│ 📖 {{プロジェクト名}}        [進捗バー===] │
├──────────┬───────────────────────────────┤
│ 目次ナビ │ 本文エリア                     │
│          │                               │
│ 第1章    │  # 章節タイトル                │
│ 第2章 ◄──│                               │
│   2.1    │  本文内容...                   │
│   2.2    │                               │
│ 第3章    │  ```コードブロック```          │
│ ...      │                               │
│          │  [SVG図表]                     │
│          │                               │
│          │  ◄ 前の章    次の章 ►          │
└──────────┴───────────────────────────────┘

ビルドツールの要件

ツール	必須	インストール	用途
Node.js ≥ 18	✅ 必須	システムインストール	コアビルドエンジン；npmパッケージ不要
`zip`	✅ 必須	macOS/Linux 内蔵；Windows は WSL	EPUB パッケージング
`mmdc`（Mermaid CLI）	⚪ 任意	`npm install -g @mermaid-js/mermaid-cli`	Mermaid ダイアグラム → PNG
Puppeteer	⚪ 任意	mmdc の node_modules に同梱（個別インストール不要）	コードブロック構文ハイライト
highlight.js	⚪ 任意	CDN 自動読み込み（ネットワーク必要）	ハイライトエンジン；インラインスタイル抽出

プログレッシブエンハンスメント：任意ツールがなくてもEPUBは正常に生成される。Mermaidはコードとして保持され、コードブロックは無色になる。

品質基準

[ ] すべての ```mermaid ブロックが Mermaid.js で正しくレンダリングされている
[ ] すべてのMarkdown章節が正しくHTMLに変換されている
[ ] ASCIIダイアグラムがすべてSVGに変換されている（漏れなし）
[ ] コードブロックが正しくハイライトされている（EPUBモード：外部CSSに依存しないインラインスタイルHTML）
[ ] 目に優しいカラーパレットが正しく適用されている
[ ] CJKタイポグラフィ規範が遵守されている（セリフ見出し＋サンセリフ本文）
[ ] ナビゲーションシステムの機能が完全に動作している
[ ] レスポンシブレイアウトが実装されている（デスクトップ・タブレット対応）
[ ] ビルドスクリプトのコアにnpm依存がない（Node.js + システムzip で動作）
[ ] （EPUBモード）.epub が生成され、EPUB 3.xの準拠チェックに合格している
[ ] （EPUBモード）すべての章節が有効なXHTMLに変換されている
[ ] （EPUBモード）content.opf・nav.xhtml・toc.ncx が正しく生成されている
[ ] （EPUBモード）各章XHTMLの <title> とnav/ncxの項目に実際の章節タイトルが使われている（ファイル名でない）
[ ] （EPUBモード）表紙SVG（cover.svg）が生成され、cover.xhtml がスパインの先頭になっている
[ ] （EPUBモード）Mermaidダイアグラムが PNG として事前レンダリング済み（-o diagram.png）で <img> として埋め込まれている、またはコードブロックとして適切にフォールバックしている
[ ] （EPUBモード）コードブロックが Puppeteer + highlight.js で一括レンダリングされインラインスタイルHTMLとなっている、または無色 <pre><code> に適切にフォールバックしている

完了マーカー

html

<!-- BOOKBINDING_COMPLETE -->

スケジューリングテンプレート概要

あなたはタイポグラフィデザインを得意とする電子書籍職人です。

## タスク
すべてのMarkdown章節を美しい電子書籍（HTML および/または EPUB、ユーザーの選択による）に変換します。

## 入力
- 最終稿章節：{{作業ディレクトリ}}/chapters/*.md
- アウトライン（目次構造）：{{作業ディレクトリ}}/outline-final.md

## 出力
- HTMLファイル（HTMLモード）：{{作業ディレクトリ}}/publish/*.html
- EPUBファイル（EPUBモード）：{{作業ディレクトリ}}/publish/{{epub文件名}}.epub
- ビルドスクリプト：{{作業ディレクトリ}}/build.js

## 要件
0. 開始前に**ユーザーに順番に質問**する：
   a) 出力形式：① HTML（デフォルト）② EPUB ③ 両方
   b) カラーパレット：① Warm Paper（デフォルト）② GitHub Light ③ Dark Mode ④ Minimal
   選択に応じて、ビルドスクリプトの OUTPUT_FORMAT と THEME 変数を設定する
1. Markdown → HTML/XHTML変換
2. **Mermaidダイアグラムのレンダリング**：
   - HTMLモード：` ```mermaid ` ブロックを Mermaid.js（CDN）でインタラクティブなダイアグラムとしてレンダリング
   - EPUBモード：**PNG** を出力（`-o diagram.png`）——Chromiumがフル忠実度でラスタライズするため色がリーダーから独立（落とし穴 1 参照）；mmdc 未インストール時はコードブロックとしてフォールバック
3. ASCIIダイアグラム → SVG自動変換（既存コンテンツ対応、{{SVG検出タイプ数}}種のタイプをサポート）
4. **コードハイライト**（EPUBモード）：
   - Puppeteer（mmdc同梱）+ highlight.js（CDN）で一括レンダリングし、トークンごとにインライン `style="color:rgb(…)"` 属性を抽出
   - **テキストは選択・コピー・検索可能**——技術書には不可欠（落とし穴 5 参照）
   - 全ブロックが1つの Chromeセッションを共有（起動コストを分散）
   - mmdc 未インストール・ネットワーク不可時は無色 `<pre><code>` に優雅にフォールバック
5. 目に優しいカラーパレット（ウォームホワイト背景、柔らかいテキスト）
6. CJKタイポグラフィ（セリフ見出し・サンセリフ本文）
7. ナビゲーションシステム（サイドバー・章節ナビゲーション・進捗バー）—— HTMLモード
8. EPUB 3.x構造（OPF + NAV + NCX + XHTML章節）—— EPUBモード、システム zip コマンドでパッケージ化
9. npm依存ゼロのNode.jsビルドスクリプト
10. 完了後に <!-- BOOKBINDING_COMPLETE --> を追記する

プロジェクト設定変数

変数	説明	デフォルト値の推奨
	書名/プロジェクト名（ナビゲーションバーに表示）	—
	ページ背景色	`#FEFCF8`
	本文テキスト色	`#2C2C2C`
	見出しテキスト色	`#1A1A1A`
	コードブロック背景色	`#F5F2ED`
	リンクカラー	`#4A7C9B`
	強調マーカー色	`#C7553A`
〜	SVGカード背景色	8色の柔らかいカラーパレット
〜	SVGカードボーダー色	対応する濃い色
	サポートするASCIIダイアグラム検出タイプ数	8
	成果物ルートディレクトリ	—
	EPUBメタデータ言語タグ（`dc:language`）	`ja`
	EPUBメタデータ著者（`dc:creator`、オプション）	—
	EPUB出力ファイル名（拡張子なし）。デフォルトは書名から自動生成	書名から特殊文字を除去した結果

Agent #11 — ブックバインダー（タイポグラフィデザイナー） ​

ロールカード ​

主要職責 ​

入力ファイル ​

出力規格 ​

publish/ ディレクトリ構造 ​

主要機能の詳細 ​

1. ASCIIダイアグラム→SVG自動変換 と Mermaid レンダリング ​

2. コードハイライト ​

3. 目に優しいカラーパレット ​

4. CJKタイポグラフィ最適化 ​

5. ナビゲーションシステム ​

6. EPUB生成規格 ​

EPUBの内部構造 ​

Mermaidダイアグラムの処理（EPUB特有の要件） ​

⚠️ EPUBビルドの落とし穴 ​

落とし穴 1：Mermaid文字が見えない、またはコントラストが極めて低い ​

落とし穴 2：SVG内の <br /> が <br / />（無効XML）に変換される ​

落とし穴 3：EPUBのCSSで overflow-x: auto が無効 ​

落とし穴 4：テーブルセルに vertical-align: top が必要 ​

落とし穴 5：EPUBでコードブロックの構文ハイライト色が消える ​

EPUBのビルド方法（npm依存ゼロ） ​

EPUB章節タイトル規格 ​

EPUB表紙規格 ​

EPUBメタデータ（content.opf） ​

SVGカラーパレット ​

デザイン規範 ​

ページレイアウト ​

ビルドツールの要件 ​

品質基準 ​

完了マーカー ​

スケジューリングテンプレート概要 ​

プロジェクト設定変数 ​