setup

设置向导（Setup Wizard）

以交互方式完成 shinkoku 的首次设置。 生成配置文件（shinkoku.config.yaml）并初始化数据库。

步骤0：确认 CLI 是否已安装

确认是否可以使用 shinkoku 命令。

1. 运行 shinkoku --version
2. 如果命令不存在：运行 uv tool install git+https://github.com/kazukinagata/shinkoku 进行安装
3. 如果命令存在：运行 uv tool upgrade shinkoku 更新到最新版

步骤1：检查现有配置

使用 Read 工具读取 CWD 中的 shinkoku.config.yaml。

• 如果文件存在：显示其内容，并确认是否要更新。如果不更新，则结束此技能。
• 如果文件不存在：启动设置向导。

步骤2：收集基本设置

使用 AskUserQuestion 确认以下项目：

2-1. 目标年度

• tax_year：确定申报的目标年度（默认值：2025）

2-1b. 是否有经营所得

• has_business_income：是否有经营所得（含副业）（true / false）

如果没有经营所得，则跳过以下步骤：

• 2-2（发票注册编号）
• 2.6-3（营业场所地址）
• 2.7（经营信息）
• 2.8 中关于申报类型（blue/white）和记账方式的问题（仅有工资所得时不需要）

2-2. 合格发票开具经营者注册编号（仅适用于有经营所得的情况）

• invoice_registration_number：T + 13 位数字（可选，可跳过）

步骤2.5：收集纳税人信息

使用 AskUserQuestion 分阶段确认以下项目。全部为可选项（可跳过），但会用于填写确定申报书等制作专区以及判定个人扣除。

2.5-1. 姓名

• taxpayer.last_name：姓
• taxpayer.first_name：名
• taxpayer.last_name_kana：姓（片假名）
• taxpayer.first_name_kana：名（片假名）

2.5-2. 基本信息

• taxpayer.gender：性别（male / female）
• taxpayer.date_of_birth：出生日期（YYYY-MM-DD）
• taxpayer.phone：电话号码
• taxpayer.relationship_to_head：与户主的关系（本人/妻子/丈夫/子女等）

2.5-3. 个人编号

• taxpayer.my_number：12 位个人编号（请谨慎处理——会保存到 config 中，但绝不会显示在工具输出或日志中）

2.5-4. 与个人扣除相关的情况（可选）

• taxpayer.widow_status：寡妇/单亲类别（none / widow / single_parent）
• taxpayer.disability_status：残疾类别（none / general / special）
• taxpayer.working_student：是否属于勤劳学生（true / false）

步骤2.6：收集地址信息

2.6-1. 家庭住址

• address.postal_code：邮政编码
• address.prefecture：都道府县
• address.city：市区町村
• address.street：门牌号
• address.building：建筑物名称、房间号（可选）

2.6-2. 截至1月1日的地址（仅在地址不同时填写）

• address.jan1_address：截至1/1 的地址（用于判定居民税的征税自治体）

2.6-3. 营业场所地址（仅适用于有经营所得且与家庭住址不同时）

• business_address.postal_code 〜 business_address.building

步骤2.7：收集经营信息

仅在有经营所得时确认。

• business.trade_name：商号
• business.industry_type：行业
• business.business_description：业务内容
• business.establishment_year：开业年份

步骤2.8：确认申报方式

依次确认以下项目，并自动判定蓝色申报特别扣除额。

确认项目

• filing.submission_method：提交方式（e-tax / mail / in-person）
  • 选择 mail / in-person 时，请在选择后立即告知：

    您可以使用此插件的账簿管理和税额计算功能，但自动填写确定申报书等制作专区的功能（/e-tax 技能）仅适用于通过 e-Tax 提交，因此无法使用。您需要自行填写制作专区。

  • 选择 e-tax 时无需通知（提供完整支持）
• filing.return_type：申报类型（blue / white）— 仅在有经营所得时询问（没有经营所得时跳过）
  • 选择 white 时，请在选择后立即告知：

    支持白色申报。在决算书专区中使用收支明细书。此外，由于账簿功能是基于复式簿记设计的，记录内容会超过白色申报所需的最低水平。

  • 选择 blue 时无需通知
• filing.tax_office_name：管辖税务署名称

蓝色申报特别扣除额自动判定流程

如果 return_type 为 blue，则按以下流程判定扣除额：

1. 询问记账方式（复式簿记 / 简易账簿）

2. 如果使用简易账簿 → simple_bookkeeping: true，扣除额确定为 100,000 日元

3. 如果使用复式簿记：

   • 通过 e-Tax 提交（submission_method: e-tax）→ 扣除额确定为 650,000 日元（无需考虑 electronic_bookkeeping）
   • 纸质提交（submission_method: mail 或 in-person）→ 询问 electronic_bookkeeping
     • true（已保存符合要求的优良电子账簿）→ 扣除额 = 650,000 日元
       • 选择 true 时，请在选择后立即告知：

         要适用优良电子账簿保存制度，必须事先向管辖税务署提交《国税相关账簿电磁记录等保存等相关申报书》。可从国税厅网站下载申报书格式。 如果要从令和9年度开始适用，请在令和8年内提交申报书。 此外，可通过 /e-bookkeeping-compliance 技能确认是否已提交申报书，以及诊断系统是否符合要求。

     • false → 扣除额 = 550,000 日元

4. 向用户显示判定结果并确认

相关字段

• filing.blue_return_deduction：蓝色申报特别扣除额（自动判定，也可手动指定）
  • 650,000：复式簿记 +（通过 e-Tax 提交或电子账簿保存）+ 按期申报
  • 550,000：复式簿记 + 纸质提交 + 按期申报（未使用 e-Tax/电子账簿保存）
  • 100,000：简易账簿或逾期申报
• filing.simple_bookkeeping：是否使用简易账簿（true / false，默认值：false）
• filing.electronic_bookkeeping：是否保存符合要求的优良电子账簿（true / false）。通过 e-Tax 提交时无需考虑此项（仅使用 e-Tax 即足以获得 65 万日元扣除）

ステップ2.9: 控除・申告に影響する重要事項の確認（スキップ不可）

以下の項目は所得税額・住民税に大きく影響するため、全項目について必ず確認する。 「該当なし」も含め、明示的な回答を得ること。未確認のまま次のステップに進んではならない。

2.9-1. 家族構成（配偶者・扶養親族）

以下を確認し、config に保存する。詳細（所得金額・障害区分等）は /income-tax で登録する。

• family.has_spouse: 配偶者の有無（true / false）
  • true の場合:
    • 配偶者の年間所得（概算）を確認し、配偶者控除/特別控除の適用可能性を把握する
    • 所得48万円以下 → 配偶者控除、48万〜133万円 → 配偶者特別控除
    • 事業専従者かどうか: 青色事業専従者として給与を受けている配偶者は配偶者控除の対象外
• family.has_dependents: 扶養親族の有無（true / false）
  • true の場合: 人数と概要（子・親など）を確認する
  • 16歳未満の子供も含める: 扶養控除は対象外だが、住民税の非課税判定・均等割判定に 必要なため、申告書第二表「住民税に関する事項」に記載が必要
  • 事業専従者は除外: 青色事業専従者・白色事業専従者は扶養親族に該当しない
• family.dependent_count: 扶養親族の人数（16歳未満を含む）

※ 配偶者・扶養親族のマイナンバーは /income-tax スキルのステップ1.5 で収集する。

2.9-2. 住宅ローン控除

• housing_loan.applicable: 住宅ローン控除の適用有無（true / false）
  • true の場合:
    • housing_loan.first_year: 初年度かどうか（true / false）
    • 初年度 → /income-tax のステップ3.7 で計算明細書を作成する（添付書類が別途必要）
    • 2年目以降 → 年末調整で適用済みなら確定申告での追加手続きは原則不要

2.9-3. 予定納税

• estimated_tax.applicable: 予定納税の有無（true / false）
  • 判定基準: 前年の確定申告書の㊺欄（申告納税額）が 15万円以上 → 予定納税あり
  • true の場合:
    • estimated_tax.amount: 予定納税の合計額（第1期 + 第2期、int 円）を確認する
    • 減額申請をした場合は減額後の金額を記入する

2.9-4. 世帯主の氏名（本人でない場合）

ステップ2.5-2 で relationship_to_head が「本人」以外の場合:

• taxpayer.household_head_name: 世帯主の氏名を確認する（申告書に記載が必要）

ステップ3: パス設定

以下のパスを確認する。デフォルト値を提示し、変更がなければそのまま採用する。

• db_path: データベースファイルのパス（デフォルト: ./shinkoku.db）
• output_dir: 進捗ファイル等の出力先ディレクトリ（デフォルト: ./output）

ステップ4: 書類ディレクトリの設定（任意）

以下のディレクトリを設定するか確認する。スキップ可能。

• invoices_dir: 請求書PDF等のディレクトリ
• withholding_slips_dir: 源泉徴収票のディレクトリ
• receipts_dir: レシート・領収書のディレクトリ
• bank_statements_dir: 銀行明細CSVのディレクトリ
• credit_card_statements_dir: クレジットカード明細CSVのディレクトリ
• deductions_dir: 控除関連書類のディレクトリ
• past_returns_dir: 過去の確定申告データのディレクトリ

ステップ5: 設定のプレビューと保存

1. 収集した設定内容を YAML 形式でプレビュー表示する
2. ユーザーの確認を得る
3. Write ツールで CWD に shinkoku.config.yaml を保存する

YAML の形式は以下のテンプレートに従う:

# shinkoku ユーザー設定ファイル
# /setup スキルで対話的に生成できます。

# 対象年度
tax_year: {tax_year}

# 事業所得の有無（副業含む）
has_business_income: {has_business_income}

# データベースファイルのパス
db_path: {db_path}

# 進捗ファイル等の出力先ディレクトリ
output_dir: {output_dir}

# 適格請求書発行事業者の登録番号（T + 13桁）
invoice_registration_number: {invoice_registration_number}

# --- 納税者情報 ---
taxpayer:
  last_name: {last_name}
  first_name: {first_name}
  last_name_kana: {last_name_kana}
  first_name_kana: {first_name_kana}
  gender: {gender}
  date_of_birth: {date_of_birth}
  phone: {phone}
  my_number: {my_number}
  widow_status: {widow_status}
  disability_status: {disability_status}
  working_student: {working_student}
  relationship_to_head: {relationship_to_head}

# --- 住所 ---
address:
  postal_code: {postal_code}
  prefecture: {prefecture}
  city: {city}
  street: {street}
  building: {building}
  jan1_address: {jan1_address}

# --- 事業所住所（自宅と異なる場合のみ） ---
business_address:
  postal_code:
  prefecture:
  city:
  street:
  building:

# --- 事業情報 ---
business:
  trade_name: {trade_name}
  industry_type: {industry_type}
  business_description: {business_description}
  establishment_year: {establishment_year}

# --- 申告方法 ---
filing:
  submission_method: {submission_method}
  return_type: {return_type}
  blue_return_deduction: {blue_return_deduction}
  simple_bookkeeping: {simple_bookkeeping}
  electronic_bookkeeping: {electronic_bookkeeping}
  tax_office_name: {tax_office_name}

# --- 家族構成 ---
family:
  has_spouse: {has_spouse}
  has_dependents: {has_dependents}
  dependent_count: {dependent_count}

# --- 住宅ローン控除 ---
housing_loan:
  applicable: {applicable}
  first_year: {first_year}

# --- 予定納税 ---
estimated_tax:
  applicable: {applicable}
  amount: {amount}

# --- 書類ディレクトリ（任意） ---
invoices_dir: {invoices_dir}
withholding_slips_dir: {withholding_slips_dir}
past_returns_dir: {past_returns_dir}
deductions_dir: {deductions_dir}
receipts_dir: {receipts_dir}
bank_statements_dir: {bank_statements_dir}
credit_card_statements_dir: {credit_card_statements_dir}

未設定の項目は値を空にする（key: のみ）。

my_number の取扱い: マイナンバーは config YAML に保存するが、profile.py の出力では has_my_number: true/false のみ返す。ログ・会話には出力しない。確定申告書等作成コーナーへの入力時のみ config から直接読み取る。

shinkoku profile --config PATH

ステップ5.5: Git セーフティ設定

ユーザーの個人情報・財務データが誤って git にコミットされないよう、.gitignore を設定する。

手順

1. git rev-parse --is-inside-work-tree を実行し、CWD が git リポジトリかどうか確認する

2. git リポジトリでない場合 → 以下のメッセージを表示してスキップする:

   現在のディレクトリは git リポジトリではありません。今後 git リポジトリ化する場合は、.gitignore に shinkoku 関連ファイルを追加して個人情報の漏洩を防いでください。

3. git リポジトリの場合: a. CWD の .gitignore を Read ツールで読み込む（存在しなければ新規作成前提で進める） b. 以下の必須エントリが .gitignore に含まれているか確認する:

   # shinkoku 確定申告データ（個人情報を含む — 削除しないこと）
   shinkoku.config.yaml
   shinkoku.db
   shinkoku.db-wal
   shinkoku.db-shm
   .shinkoku/
   output/
   

   c. ステップ4で設定された書類ディレクトリ（invoices_dir, receipts_dir 等）があれば、それも追加対象にする d. 不足しているエントリがある場合:

   • 追加するエントリの一覧をユーザーに提示する
   • ユーザーの確認を得てから .gitignore に追記する（既存の内容は保持し、末尾に追加する） e. 既に全エントリが含まれている場合 → 「.gitignore は設定済みです」と表示してスキップする

ステップ6: データベースの初期化

1. db_path の値を確認し、相対パスの場合は CWD を基準に絶対パスに変換する
2. ledger.py init コマンドでデータベースを初期化する:

   shinkoku ledger init --db-path DB --fiscal-year YEAR
   

   • --fiscal-year: ステップ2 で設定した tax_year
   • --db-path: 絶対パスに変換した値

ステップ7: 次のステップの案内

セットアップ完了後、以下を案内する:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
セットアップ完了
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 生成されたファイル:
  → shinkoku.config.yaml（設定ファイル）
  → {db_path}（データベース）

■ 次のステップ:
  1. /assess — 申告要否・種類の判定
  2. /gather — 必要書類の確認・収集
  3. /journal — 仕訳入力・帳簿管理
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

引継書の出力

サマリー提示後、以下のファイルを Write ツールで出力する。 これにより、セッションの中断や Compact が発生しても次のステップで結果を引き継げる。

ステップ別ファイルの出力

.shinkoku/progress/01-setup.md に以下の形式で出力する:

---
step: 1
skill: setup
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# セットアップ結果

## 設定内容

- 対象年度: {tax_year}
- データベースパス: {db_path}
- 出力ディレクトリ: {output_dir}
- インボイス登録番号: {invoice_registration_number}

## 納税者情報

- 氏名: {last_name} {first_name}
- 生年月日: {date_of_birth}
- マイナンバー: {登録済み/未登録}
- 寡婦/ひとり親: {widow_status}
- 障害者区分: {disability_status}
- 勤労学生: {working_student}
- 世帯主との続柄: {relationship_to_head}

## 住所

- 自宅: {postal_code} {prefecture}{city}{street}{building}
- 1/1時点の住所: {jan1_address}（同上/異なる住所）
- 事業所住所: {設定あり/自宅と同じ}

## 事業情報

- 屋号: {trade_name}
- 業種: {industry_type}
- 事業内容: {business_description}

## 申告方法

- 提出方法: {submission_method}
- 申告の種類: {return_type}
- 青色申告特別控除: {blue_return_deduction}円
- 所轄税務署: {tax_office_name}

## 控除・申告に影響する重要事項

- 配偶者: {あり（概算所得: ○万円）/ なし}
- 扶養親族: {あり（○人、うち16歳未満○人）/ なし}
- 住宅ローン控除: {適用あり（初年度/2年目以降）/ 適用なし}
- 予定納税: {あり（合計○円）/ なし}
- 世帯主: {本人 / ○○（氏名）}

## 書類ディレクトリ

- 請求書: {invoices_dir}
- 源泉徴収票: {withholding_slips_dir}
- レシート: {receipts_dir}
- 銀行明細: {bank_statements_dir}
- クレカ明細: {credit_card_statements_dir}
- 控除関連: {deductions_dir}
- 過去の申告: {past_returns_dir}

## DB初期化

- 初期化結果: 成功
- 勘定科目マスタ: 登録済み

## 次のステップ

/assess で申告要否・種類を判定する

未設定の項目は「未設定」と記載する。

進捗サマリーの更新

.shinkoku/progress/progress-summary.md を新規作成する:

• YAML frontmatter: fiscal_year、last_updated（当日日付）、current_step: setup
• テーブル: 全ステップの状態を記載（setup を completed に、他は pending に）
• 次のステップの案内を記載

出力後の案内

ファイルを出力したらユーザーに以下を伝える:

• 「引継書を .shinkoku/progress/ に保存しました。セッションが中断しても次のスキルで結果を引き継げます。」
• 次のステップの案内