excel-spreadsheets

Excel スプレッドシート

使用するタイミング

ツール	使用するタイミング
create_excel_spreadsheet	ユーザーが新しいスプレッドシートの作成を依頼した場合
modify_excel_spreadsheet	ユーザーが既存のスプレッドシートの編集や更新を依頼した場合
list_my_excel_spreadsheets	ユーザーが利用可能なスプレッドシートを尋ねた場合
read_excel_spreadsheet	ユーザーがスプレッドシートのダウンロードや内容の読み取りを希望する場合
preview_excel_sheets	編集時に実際のシートの表示を確認する場合

ワークフロー

1. 変更する前に、preview_excel_sheets を呼び出して現在のレイアウトを確認します。
2. 作成や変更の後に、preview_excel_sheets を呼び出して確認します。
3. ファイルの競合状態を防ぐため、ツールは順番に（並行して実行せずに）実行します。

プロフェッショナルな書式設定

• フォント：既存のテンプレートで指定されていない限り、すべてのセルで Arial を使用します。
• 負の数：(1,234) のように括弧で表示します。マイナス記号を使った -1,234 にはしません。
• 通貨：$#,##0 形式を使用します。ヘッダーに単位を指定します（例：「売上高（$mm）」）。
• パーセンテージ：0.0%（小数点以下 1 桁）を使用します。
• 年：テキストとして書式設定します（"2,024" ではなく "2024"）。
• ゼロ：ユーザー定義の表示形式を使用して "-" と表示します。

# Example: professional number formatting
from openpyxl.styles import numbers
ws['B2'].number_format = '$#,##0'          # Currency
ws['C2'].number_format = '0.0%'            # Percentage
ws['D2'].number_format = '#,##0;(#,##0)'   # Negative in parentheses
ws['E2'].number_format = '@'               # Year as text
ws['F2'].number_format = '#,##0;(#,##0);"-"'  # Zeros as dash

財務モデルの色分け

財務モデルを作成する際は、次の規則に従って色を設定します。

色	16 進数	用途
青文字	0000FF	ハードコードされた入力値と前提条件
黒文字	000000	すべての数式と計算
緑文字	008000	他のワークシートから参照するリンク
黄色の背景	FFFF00	注意が必要な主要な前提条件

from openpyxl.styles import Font, PatternFill
ws['B2'].font = Font(name='Arial', color='0000FF')       # Blue: input
ws['B3'].font = Font(name='Arial', color='000000')       # Black: formula
ws['B4'].font = Font(name='Arial', color='008000')       # Green: cross-sheet link
ws['B5'].fill = PatternFill('solid', fgColor='FFFF00')   # Yellow bg: key assumption

画像

from openpyxl.drawing.image import Image
ws.add_image(Image('file.png'), 'E1')

コードの規則

• ブックは wb = Workbook() として初期化済みで、アクティブなシートは ws = wb.active として設定済みです（作成時）。変更時にはブックが wb として読み込まれています。Workbook() や wb.save() は含めないでください。
• 利用可能なライブラリ：openpyxl、matplotlib、pandas、numpy（seaborn は利用できません）
• 必ず Excel の数式を使用し、計算値を直接入力しないでください。
  • 誤り：ws['B10'] = total
  • 正しい例：ws['B10'] = '=SUM(B2:B9)'
• 前提条件は別のセルに入力し、数式内で参照します（例：=B5*(1+$B$6)。=B5*1.05 は使用しません）。
• 循環参照を避けてください。
• ファイル名には、英字、数字、ハイフンのみを使用します。

---

ツールのリファレンス

create_excel_spreadsheet

openpyxl コードを使用して、新しい Excel スプレッドシートを作成します。

パラメーター	型	必須	説明
python_code	str	はい	openpyxl を使用する Python コード（上記のコードの規則を参照）
spreadsheet_name	str	はい	拡張子を除いたファイル名（英字、数字、ハイフンのみ）

ツール入力の例：

{
  "python_code": "ws.title = 'Sales'\nws['A1'] = 'Quarter'\nws['B1'] = 'Revenue'\nfor i, (q, r) in enumerate(zip(['Q1','Q2','Q3','Q4'], [100,150,130,180]), start=2):\n    ws[f'A{i}'] = q\n    ws[f'B{i}'] = r",
  "spreadsheet_name": "quarterly-sales"
}

警告：パラメーターは spreadsheet_name です。filename や name ではありません。

modify_excel_spreadsheet

既存のスプレッドシートを変更し、新しい名前で保存します。

パラメーター	型	必須	説明
source_name	str	はい	既存のスプレッドシート名（.xlsx を除く）
output_name	str	はい	新しい出力名（元の名前と異なる必要があります）
python_code	str	はい	スプレッドシートを変更する Python コード

ツール入力の例：

{
  "source_name": "quarterly-sales",
  "output_name": "quarterly-sales-v2",
  "python_code": "ws = wb.active\nws['B6'] = '=SUM(B2:B5)'"
}

list_my_excel_spreadsheets

ワークスペース内のすべてのスプレッドシートを一覧表示します。パラメーターは不要です。

read_excel_spreadsheet

指定したスプレッドシートをダウンロード用に取得します。

パラメーター	型	必須
spreadsheet_name	str	はい

preview_excel_sheets

編集前に目視で確認するため、シートのスクリーンショットを取得します。

パラメーター	型	必須	説明
spreadsheet_name	str	はい	拡張子を除いたスプレッドシート名
sheet_names	list[str]	はい	プレビューするシート名（すべてのシートを表示する場合は空のリスト []）

UI ガイダンス（tools-config から）

順次実行が必須です： 変更ツールは並列ではなく、必ず順番に実行してください（S3 ファイルの読み書きにおける競合状態を防ぐため）。

使用するタイミング：

• create_excel_spreadsheet：ユーザーが新しい Excel スプレッドシートの作成／生成を依頼した場合
• modify_excel_spreadsheet：ユーザーが既存のスプレッドシートの編集／変更／更新を依頼した場合
• list_my_excel_spreadsheets：ユーザーが利用可能なスプレッドシートについて尋ねた場合
• read_excel_spreadsheet：ユーザーがスプレッドシートの内容のダウンロードまたは読み取りを希望する場合
• preview_excel_sheets：編集時に実際のシートの表示を確認する場合

変更前： 必ず最初に preview_excel_sheets を使い、現在のレイアウトを確認してください。

重要 — ハードコードした値ではなく数式を使用：

• 必ず Excel の数式を使用してください。Python で計算して結果をハードコードしてはいけません。
• 誤り：ws['B10'] = total。正しい例：ws['B10'] = '=SUM(B2:B9)'
• 前提条件は別のセルに配置し、数式から参照してください（例：=B5*(1+$B$6)。=B5*1.05 ではありません）。
• 保存後、LibreOffice によって数式が自動的に再計算されます。
• 循環参照を避けてください。

プロフェッショナルな書式設定：

• フォント：既存のテンプレートで指定されている場合を除き、すべてのセルで Arial を使用
• 負の数：マイナス表記 -1,234 ではなく、括弧表記 (1,234)
• 通貨：$#,##0 形式を使用し、ヘッダーに単位を明記（「Revenue ($mm)」）
• パーセンテージ：0.0%（小数点以下 1 桁）
• 年：テキストとして書式設定（「2,024」ではなく「2024」）
• ゼロ：ユーザー定義の数値書式を使い、「-」で表示

財務モデルの色分け（該当する場合）：

• 青字（0,0,255）：ハードコードされた入力値と前提条件
• 黒字（0,0,0）：すべての数式と計算
• 緑字（0,128,0）：他のワークシートから取得したリンク
• 黄色の背景（255,255,0）：注意が必要な主要な前提条件

ファイル名： 使用できるのは英字、数字、ハイフンのみです（例：「Q4-sales.xlsx」）。

利用可能なライブラリ： openpyxl、matplotlib、pandas、numpy（seaborn は利用できません）

画像： from openpyxl.drawing.image import Image; ws.add_image(Image('file.png'), 'E1')

品質確認： 作成後は必ず preview_excel_sheets を使って表示を確認してください。