thkt /transcribe - スプレッドシート読み取り
Read ツールは xlsx を開けない。このリポジトリに入れた hucre をライブラリとして使い、シートを読む。
手順
- 中身の形を見る。
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts list <xlsx>
シート一覧と充填率が出る。充填率は値が入っているセルの割合で、ここで次の分岐が決まる。
- 充填率で読み方を決める。
| 充填率 | 状態 | 読み方 |
|---|---|---|
| 20% 未満 | セル結合とレイアウト目的の空セルが大半を占める | extract で整形してから読む |
| 20% 以上 | 1 行 1 レコードに近い | --sheet でシートを絞り generic のまま extract する |
- 整形する。出力先はリポジトリの外か、ユーザーが指定した場所にする。
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts extract <xlsx> --out <dir> [--profile <name>] [--sheet <n|name>]
- 欠落が無いか確かめる。この確認を飛ばさない。書式判定を誤るとエラーを出さずにセルが消えるため、消えたかどうかは照合でしか分からない。
node ${CLAUDE_SKILL_DIR}/scripts/cli.ts verify <xlsx> <dir>
OK: every cell of N sheets survived into the output. が出たら完了。欠落があればシート名と欠落セルの先頭 40 字を返すので、プロファイルの判定を直してから再実行する。
プロファイル
書式固有の判定はプロファイルが持つ。scripts/convert.ts の profiles に定義がある。
未知の書式にはまず generic を使う。表として整形したい場合だけプロファイルを足す。プロファイルが持つ判定は 5 つで、null にした判定は行わない。
| プロファイル | 対象 | 挙動 |
|---|---|---|
generic (既定) |
書式が不明なファイル | 表として解釈しない。セル結合を畳むだけで、情報は落ちない |
ja-api-spec |
項番とパラメータ名の列を持つ日本語の API 設計書 | 見出し、パラメータ表、2 段ヘッダ、コードブロックを復元する |
| キー | 判定 |
|---|---|
docHeaderFirstCell |
この文字列が A1 にあるとき、先頭 3 行を文書情報として畳む |
heading |
この正規表現に一致する 1〜2 セルの行を見出しにする |
tableHeadWords |
この正規表現に一致し、かつ 3 セル以上ある行を表ヘッダにする |
nestColumnLabel |
この語を含む列で、列内のセル位置を階層の深さとして復元する |
code |
この正規表現に一致する単独セルの行を連結してコードブロックにする |
判断の基準
単発で内容を知りたいだけなら、extract --sheet <n|name> --out の出力先を一時ディレクトリにして読み、リポジトリには残さない。Markdown ファイルとして残すのは、横断 grep を繰り返すとき、人が読むとき、git で差分を追うときに限る。
整形の効果は充填率で決まる。充填率が低いほど空セルがトークンを食い、整形で落ちる分が大きくなる。
依存
hucre をリポジトリのルートに入れてある (bun add hucre)。未導入の環境ではスクリプトが導入手順を出して終了する。node は script の親を辿って node_modules を探すので、プラグイン導入先なら ~/.claude で入れれば解決する。
Python へ移さないのは、hucre が xlsx、ods、csv を 1 パッケージで持つため。openpyxl は ods を読まず odfpy が別に要り、このリポジトリの Python は全て標準ライブラリのみで依存マニフェストを持たない。標準ライブラリで書き直すと、日付セルが素の数値で styles.xml の numFmtId を辿らないと判別できない部分を自前で抱える。
CLI (hucre convert) は使わない。理由は 3 つある。
| 理由 | 根拠 |
|---|---|
| セル結合を落とす | CLI の説明文が cell values only — styles, merges, formulas と明記している |
| 先頭シート以外を落とす | 3 シートのファイルで Read 3 sheet(s) と出しながら 1 シートしか書き出さない |
| Markdown を出せない | convert <INPUT> <OUTPUT> の形式変換のみで、シートを選ぶオプションも持たない |