pdf

Markdown/HTML/Typst から PDF へ

概要

Markdown、HTML、または Typst ファイルを PDF 文書に変換します。変換処理はローカルで行われます。CLI によるデフォルトの統計情報の送信と更新通知のネットワークリクエスト、および無効化の方法については、以下のインストール手順を参照してください。

次の 3 つのモードに対応しています。--mode auto（デフォルト、一般的な文書）、--mode arithmetic（暗算プリント）、--mode pinyin（ピンインを見て漢字を書く練習）。後者の 2 つのモードではプレーンテキストを入力し、CLI が直接レイアウトします。

cyeam pdf README.md                      # 从 Markdown 文件生成 PDF（base64 JSON）
cyeam pdf README.md -o out.pdf           # 从 Markdown 文件生成并保存 PDF
cyeam pdf layout.typ -o out.pdf          # 从 Typst 文件生成并保存 PDF（需要本机 typst）
cat index.html | cyeam pdf               # 从 stdin 读 HTML，输出 base64 JSON
cat README.md | cyeam pdf -o out.pdf     # 从 stdin 读 Markdown 并保存 PDF

入力方法の選択（重要）

cyeam pdf は複数の入力方法に対応しています。現在の実行環境に応じて、最も確実な方法を選択してください。コマンドの形式を推測しないでください。

レイアウト形式の選択（重要）

• デフォルトでは、まず Markdown の生成を優先してください。一般的な文書、説明、リスト、コードブロックなど、直線的なコンテンツに適しています。
• ユーザーが明確に、コンパクトにする、省スペースにする、ページを埋める、複数列で表示する、自由にレイアウトする、見栄えを良くするといった要望をしている場合、通常の Markdown の 1 列コンテンツだけを生成しないでください。
• 軽量な複数列レイアウトであれば Markdown でも実現できますが、cyeam pdf がサポートする columns 拡張構文を使用してください。
• より自由なレイアウト（複数列、グリッド、明示的な改段、ページ単位のレイアウト）が必要な場合は、まず Typst ファイル（.typ）を生成し、その後 cyeam pdf <file.typ> -o <file.pdf> を実行してください。
• コンパクトなレイアウトや複数列レイアウトの実現に HTML/CSS を使用しないでください。現在、HTML 入力はシンプルな構造の変換にのみ適しており、CSS は PDF のレイアウトエンジンとして実行されません。

Markdown の複数列拡張

Markdown の書きやすさを保ちながら、短いコンテンツをよりコンパクトにしたい場合に適しています。構文：

::: columns 3
::: column
第一列内容
:::

::: column
第二列内容
:::

::: column
第三列内容
:::
:::

ルール：

• columns の後ろの数字は推奨列数を示しますが、実際の列数は column ブロックの数に従います。
• 各 column 内には通常の Markdown を記述します。
• コンパクト化、省スペース化、複数列、ページを埋めるなどのレイアウト要件がユーザーから求められた場合にのみ使用してください。一般的な文書では多用しないでください。

Typst による自由なレイアウト

ユーザーが自由なレイアウト、明確な複数列、グリッド、カード形式のレイアウト、またはページ利用率の向上を求めている場合に適しています。例：

#set page(paper: "a4", margin: 18mm)
#set text(size: 11pt)

#columns(3, gutter: 12pt)[
  第一列内容

  #colbreak()

  第二列内容

  #colbreak()

  第三列内容
]

Typst ファイルは .typ として保存してから実行してください。

cyeam pdf /tmp/layout.typ -o /tmp/layout.pdf --pretty

ローカルに typst がインストールされていない場合、コマンドはエラーになります。その場合は Markdown columns 拡張を使用するか、Typst のインストールをユーザーに案内してください。

暗算プリントの形式

CLI は --mode arithmetic に標準で対応しているため、Typst は不要です。入力は UTF-8 のプレーンテキストで、空でない各行に 1 問（番号を付けてもかまいません）を記述します。空行は無視されます。Markdown の見出し、メタデータ、表、解答を混在させないでください。CLI はレイアウトのみを行い、問題の自動作成、番号付け、解答の追加は行いません。

cyeam pdf questions.txt --mode arithmetic -o practice.pdf
cyeam pdf questions.txt --mode arithmetic --layout grade4 --title "四年级口算" -o practice.pdf
cyeam pdf questions.txt --mode arithmetic --layout vertical -o practice.pdf

--layout には standard（デフォルト）、grade4、large-number、negative、quantity、vertical を指定でき、詳細は以下の表のとおりです。--title のデフォルトは「宝宝口算」です。これら 2 つのパラメーターは arithmetic モード専用です。デフォルトの --mode auto では Markdown/HTML/Typst の自動検出が維持されます。arithmetic モードは拡張子より優先され、常に 1 行ごとに問題を解析します。ファイルまたは stdin からの入力と、従来の base64 JSON 出力に対応しています。

ユーザーが「暗算 PDF」「暗算プリント」または「宝宝口算形式でレイアウト」と求めた場合に使用してください。cyeam_web/controllers/baobao_controller.go の ArithmeticExec() を参考にし、PDF バックエンドのレイアウトを基準としてください。フロントエンド HTML の印刷ロジックに固定された 100 問は採用しないでください。

• A4 縦向き（210 × 297 mm）、白黒、枠線なしの問題グリッドを使用します。問題エリアは左から 10 mm、全幅 190 mm、ページ上端から 32 mm の位置に配置します。ページ上部の区切り線は 30 mm の位置にあり、5–205 mm にわたります。
• ページ上部のデフォルトタイトルは「宝宝口算」で、20 pt の太字です。四年生向けは具体的な問題形式のタイトルを使用し、13 pt の太字にします。タイトルの左上位置は x=10 mm、y=7 mm を目安にしてください。ウェブサイトの通常版では、タイトルの右側に「問題を確認」「十の位を確認」「一の位を確認」「答えを確認」の 4 つの短いヒント（8–10 pt）を配置します。四年生版ではこのヒントを配置しません。CLI の標準モードでは通常の太さのタイトルを使用し、確認ヒント、QR コード、氏名・日付欄は付けません。これらの装飾をすべて再現する必要がある場合は、カスタム Typst を使用してください。
• ウェブサイト版を再現する場合、右上の x=170 mm、y=7 mm の位置に 20 × 20 mm の QR コードを配置し、https://www.cyeam.com/tool/arithmetic を指定します。カスタムプリントでは QR コードを省略できます。arithmetic skill に由来するタイトル、氏名、日付などのメタデータは保持し、それに応じて問題の開始位置と各ページの行数を調整し、重ならないようにしてください。

問題形式	1 ページあたりの行 × 列	1 ページあたりの問題数	行の高さ	列幅	問題の文字サイズ
通常の横書き暗算	20 × 5	100 問	12 mm	38 mm	11.5 pt
四年生向け一般問題	25 × 4	100 問	10 mm	47.5 mm	9 pt
四年生向け大きな数 g4-large-number、負の数 g4-negative	25 × 3	75 問	10 mm	190/3 mm	10 pt
四年生向け数量関係 g4-quantity	25 × 2	50 問	10 mm	95 mm	10 pt
四年生以外の筆算（ウェブサイト上の問題形式 ID が -2 で終わるもの）	5 × 5	25 問	48 mm	38 mm	11.5 pt

• グリッドには左から右、上から下の順に配置します。横書きの問題は左揃え、垂直方向は中央揃えにします。筆算の問題文はマスの上部に置き、その下に計算スペースを残します。フォントはゴシック体を目安とし、実際には中国語と演算子をカバーする利用可能なフォントを使用してください。
• 四年生向けの通常の穴埋め欄には （　　）、数量関係には幅の広い （　　　　） を残します。単位と問題文全体を保持してください。長い問題文が収まらない場合は、行の高さを増やすか列数を減らし、1 ページあたりの問題数を再計算してください。問題文を切り詰めないでください。
• 表の問題数は、参考レイアウトにおける 1 ページあたりの収容数です。ユーザーが問題数を指定している場合、または問題をすでに提供している場合は、実際の問題数に応じてページ分けし、最終ページには空欄を残してください。ページを埋めるために問題を勝手に追加しないでください。ユーザーがページを埋めるよう求め、問題数を指定していない場合に限り、対応する収容数に応じて問題を作成してください。ウェブサイトの生成機能では、問題バンクや重複排除の制限により、収容数に満たない問題数しか返されない場合もあります。
• 問題と解答は分け、デフォルトでは解答を付けません。解答が必要な場合は、別の解答ページにしてください。問題を作成する場合は、arithmetic skill の学年、問題形式、問題数の制約に従ってください。この形式が定めるのは PDF のレイアウトのみであり、サポートする問題形式の範囲を拡大するものではありません。
• デフォルトでは CLI の暗算モードを直接使用し、対応する収容数に応じてページ分けし、最終ページに問題を追加しません。長い問題文はマス内で自動改行され、行の高さを超えると問題番号を示すエラーになります。その場合は問題文を短くするか、より幅の広いレイアウトを選択してください。筆算モードでは上部に横書きの問題文を置き、その下に計算スペースを残します。縦書きの計算式は自動生成しません。追加のメタデータ、カスタムの行高、縦書きの計算式が必要な場合は Typst を使用してください。本節の寸法（mm）は、上記の共通例で設定されている 18 mm のページ余白に優先します。

ピンインを見て漢字を書く形式

ユーザーが「ピンインを見て漢字を書く PDF」または「ピンイン用マス目練習用紙」を求めた場合は、--mode pinyin を使用してください。入力は練習する漢字の原文（UTF-8）であり、ピンインではありません。ファイルと stdin のどちらにも対応しています。Typst、ネットワーク、ログインは不要です。

printf '%s' '你好' | cyeam pdf --mode pinyin -o practice.pdf
cyeam pdf words.txt --mode pinyin -o practice.pdf

• ウェブサイトの /tool/pinyin?xiezi=你好 を参考にします。A4 縦向きで、左上に「看拼音写字」というタイトルを配置します。ピンインのヒントの下に空白の米字格を置き、漢字の答えは表示しません。
• 問題エリアは x=13 mm、y=20 mm から始めます。米字格は 11 × 11 mm、ピンイン欄の高さは 7 mm、語句間の間隔は 5 mm とし、1 行あたり最大 17 マスです。空白、改行、句読点、その他の漢字以外の区切りはマスを占めません。17 文字を超える語句は自動的に分割されます。
• 下部に「改错：」と、255、265、275、285 mm の位置に 4 本の横線を残します。長いテキストは自動的にページ分けされ、各ページにタイトルと訂正欄が繰り返し表示されます。黙って切り詰められることはありません。グループ間の間隔により、1 ページに収まる文字数が 204 字未満になる場合があります。
• ピンインはローカル辞書から生成します。多音字の読みは文脈に応じて確認してください。漢字が含まれていない場合はエラーになります。
• ピンインのフォントは内蔵されています。タイトルと訂正欄のラベルには PDF の中国語フォント検出が使用されるため、システムに利用可能な中国語フォントが必要です。--layout と --title は口算モード専用であり、pinyin モードと併用できません。
• 他の PDF モードと同様に、-o を指定するとファイルに保存し、省略すると base64 JSON を返します。位置引数には常にファイルパスを指定します。テキストを直接渡す場合は stdin を使用するか、既存の cyeam pinyin sheet "你好" -o practice.pdf を使用してください。

方法 1：ファイル入力（エージェントに推奨）

Markdown/HTML ファイルがすでにある場合、またはエージェントがまず一時ファイルに内容を書き込める場合に適しています。構造化された argv ツール、通常のシェル、Xiaoli の channel_send による後続の送信に適した方法です。

# 1. 先准备真实源文件，例如 /tmp/openclaw-install-guide.md
# 2. 再把源文件转成 PDF
cyeam pdf /tmp/openclaw-install-guide.md -o /tmp/openclaw-install-guide.pdf --pretty

方法 2：stdin 入力

実行環境からコマンドの stdin に本文を書き込める場合に適しています。本文には Markdown または HTML を使用できます。

cyeam pdf -o /tmp/openclaw-install-guide.pdf --pretty

注意：上記の書き方が正しいのは、stdin に内容がすでに渡されている場合のみです。stdin に内容がない場合は失敗し、no content provided (stdin is empty) と表示されます。

方法 3：shell パイプ入力

人間が shell を使う場合、または shell パイプを明示的にサポートする Agent/bash ツールに適しています。

cat /tmp/openclaw-install-guide.md | cyeam pdf -o /tmp/openclaw-install-guide.pdf --pretty
printf %s "# 标题\n\n正文" | cyeam pdf -o /tmp/out.pdf --pretty

現在のツールが構造化された argv のみを受け付け、stdin を提供せず、shell パイプもサポートしていない場合は、方法 1 を使用してください。まずソースファイルを作成してから、cyeam pdf <source> -o <pdf> --pretty を実行します。

ユーザー向けの PDF を生成した後は、現在のチャネルの送信ツール（例：channel_send）を引き続き呼び出して、生成した .pdf ファイルを送信してください。

インストール

インストールする前に、以下のコマンドをお読みください。例では v1.1.4 に固定しており、latest には追従しません。ダウンロードするのは実行可能プログラムのアーカイブです。 CLI のインストールが必要な場合にのみ実行してください。コマンドを呼び出すたびにインストールを繰り返す必要はありません。

macOS / Linux：検証後、ユーザーディレクトリにインストール

Bash または Zsh で実行します。curl、tar、install と、shasum または sha256sum が必要です。 スクリプトは macOS / Linux の arm64 または x86_64 を自動的に選択し、それ以外のプラットフォームでは停止します。

(
  set -eu
  version='v1.1.4'
  case "$(uname -s)/$(uname -m)" in
    Darwin/arm64)
      asset='cyeam_Darwin_arm64.tar.gz'
      sha256='06b5af004ab4f0f05d5829ea6bd18b97c4449c262af7df14c67175f7d3cb29db' ;;
    Darwin/x86_64)
      asset='cyeam_Darwin_x86_64.tar.gz'
      sha256='107342bb9d2fa444b96155c468e71b8cc63e0f5ad0acc784698afe221548efa6' ;;
    Linux/aarch64|Linux/arm64)
      asset='cyeam_Linux_arm64.tar.gz'
      sha256='ed87697f3948bead67b585e9881c3bef20e8d2d903beb5b125587281a5091c5b' ;;
    Linux/x86_64)
      asset='cyeam_Linux_x86_64.tar.gz'
      sha256='873d6805fab8ab56540bb034aaf2f57f12eb672fcabd322ebe401e8250a5966d' ;;
    *) echo '不支持的平台，请查看固定版本的 Release。' >&2; exit 1 ;;
  esac
  workdir=$(mktemp -d)
  trap 'rm -rf "$workdir"' EXIT
  cd "$workdir"
  curl --fail --show-error --silent --location --proto '=https' --proto-redir '=https' \
    --output "$asset" "https://github.com/mnhkahn/cyeam-cli/releases/download/$version/$asset"
  printf '%s  %s\n' "$sha256" "$asset" > expected.sha256
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -c expected.sha256
  else
    shasum -a 256 -c expected.sha256
  fi
  # set -e 确保下载或校验失败时，不会解压或安装。
  tar -xzf "$asset" cyeam
  mkdir -p "$HOME/.local/bin"
  install -m 0755 cyeam "$HOME/.local/bin/cyeam"
  CYEAM_CLI_NO_UPDATE_NOTIFIER=1 "$HOME/.local/bin/cyeam" --no-analytics version
)

一時ディレクトリと ~/.local/bin/cyeam のみを書き込みます（同名のプログラムがある場合は置き換えます）。管理者権限は不要です。 システムディレクトリ、サービス、shell 設定は変更しません。現在の shell で使用するには、次のようにします。

export PATH="$HOME/.local/bin:$PATH"

永続的に有効にするには、上記の行をご自身で shell 設定に追加してください。 v1.1.4 リリースページ と checksums.txt でチェックサムを確認できます。固定バージョンをアップグレードする場合は、バージョン番号と対応する SHA-256 の両方を必ず確認して置き換えてください。 チェックサムはリリースファイルの整合性を確認するためのもので、独立した署名やセキュリティ監査に相当するものではありません。

外部リクエストと権限の用途

• インストール時のダウンロード：選択したアーカイブを GitHub の固定 Release からのみダウンロードします。GitHub により、そのアセットの CDN にリダイレクトされる場合があります。 ダウンロード後、ドキュメントに記載された固定 SHA-256 を検証してから、単一の cyeam ファイルを解凍します。インストール時の確認では、統計情報の送信と更新通知を無効にしています。
• PDF の生成：ユーザーが指定したローカルファイルまたは stdin を読み込みます。変換処理でドキュメントがアップロードされることはありません。 --out / -o は指定されたパスに書き込み、既存のファイルを上書きする場合があります。ログインは不要です。 Typst 入力では、インストール済みの typst compile を呼び出し、一時ディレクトリを読み書きします。 ドキュメントが参照する Typst パッケージによっては、Typst 自身がパッケージをダウンロードする場合があります。オフラインで使用する場合は、ローカルの依存関係を使用してください。
• 使用統計：デフォルトでは、コマンド名、CLI バージョン、システム情報、ランダムなインストール ID を https://us.i.posthog.com に送信します。 サーバー側では、送信元の IP アドレスから地域を特定する場合があります。コマンド引数、画像の内容、ログイン認証情報は送信しません。 ランダム ID は ~/.cyeam/analytics-id に保存されます。無効にするには --no-analytics または CYEAM_CLI_NO_ANALYTICS=1 を使用してください。
• 更新通知：デフォルトでは、最長 24 時間ごとに GitHub で最新バージョンを確認し、~/.cyeam/update-state.json にキャッシュします。 通知によってプログラムが置き換えられることはありません。無効にするには CYEAM_CLI_NO_UPDATE_NOTIFIER=1 を設定してください。 cyeam update は明示的なアップグレードコマンドです。最新の Release をダウンロードして検証し、現在のプログラムを置き換えます。成功後は npx skills add による skills の同期も試みます。 バージョンを固定する必要がある場合は実行せず、上記の手順で選択したバージョンをインストールしてください。

CLI の統計情報と更新通知を無効にするには（製品自体によるネットワークリクエストには影響しません）、現在の shell で次のように設定します。

export CYEAM_CLI_NO_ANALYTICS=1
export CYEAM_CLI_NO_UPDATE_NOTIFIER=1

出力

cyeam pdf README.md は JSON を返します。

{"ok":true,"data":"{\"pdf\":\"<base64>\"}"}

--out を追加すると、ファイルを直接保存します。

cyeam pdf README.md -o out.pdf --pretty
# saved: out.pdf

--pretty を指定しない場合は、JSON エンベロープ {"ok":true,"data":"saved: out.pdf\n"} を出力します。

注意事項

• 形式は自動検出されます。.typ 拡張子は Typst として扱われます。.html / .htm 拡張子、または <!DOCTYPE / <html で始まる内容は HTML として扱われます。それ以外は Markdown として扱われます。
• 完全にローカルで生成し、goldmark と gofpdf を使用します。
• 次の組版要素に対応しています：H1～H4 の見出し、段落、太字／斜体、インラインコード、コードブロック、箇条書き／番号付きリスト、リンク、水平線
• Markdown では追加で ::: columns / ::: column の複数列拡張にも対応しています。
• Typst 入力には、ローカルマシンに typst がインストールされている必要があります。
• 自動で改ページし、A4 用紙を使用します。
• ログインは不要です。