using-univer-cli

Univer CLI の使用

これは、ワークブックとスプレッドシートのタスクに関するエントリースキルです。タスクでワークブックファイル、シート、セル、範囲、数式、書式設定、グラフ、プレビュー、または SaC ワークブックの動作を扱う場合は、ツールを選択したりコードを書いたりする前に、このスキルを読み込んでください。

ワークブック、スプレッドシート、Excel ファイル、シート、セル、範囲、数式、グラフ、書式設定、プレビュー、または SaC ワークブックの動作に関するタスクである可能性が 1％でもある場合は、必ず最初にこのスキルを使用してください。

このスキルが該当する場合は、スプレッドシートライブラリを先に選ばないでください。最初に Univer CLI の手順を使用してください。

ルール

ワークブックの内容に触れる前に、ワークフローを決定してください。

digraph using_univer_cli {
    "Workbook task received" [shape=doublecircle];
    "Ordinary workbook-visible work?" [shape=diamond];
    "Load univer-cli" [shape=box];
    "Use workbook-visible verification" [shape=box];
    "SaC source or complex behavior?" [shape=diamond];
    "Load writing-univer-plans" [shape=box];
    "Success criteria then plan" [shape=box];
    "Load executing-univer-plans" [shape=box];
    "Execute the plan" [shape=box];
    "Load test-driven-univer-development" [shape=box];
    "TDD each pack from the plan" [shape=box];
    "Implement only after the assertion gate exists" [shape=box];
    "Verify and repair" [shape=box];

    "Workbook task received" -> "Ordinary workbook-visible work?";
    "Ordinary workbook-visible work?" -> "Load univer-cli" [label="yes"];
    "Load univer-cli" -> "Use workbook-visible verification";
    "Ordinary workbook-visible work?" -> "SaC source or complex behavior?" [label="no"];
    "SaC source or complex behavior?" -> "Load writing-univer-plans" [label="yes"];
    "Load writing-univer-plans" -> "Success criteria then plan";
    "Success criteria then plan" -> "Load executing-univer-plans";
    "Load executing-univer-plans" -> "Execute the plan";
    "Execute the plan" -> "Load test-driven-univer-development";
    "Load test-driven-univer-development" -> "TDD each pack from the plan";
    "TDD each pack from the plan" -> "Implement only after the assertion gate exists";
    "Implement only after the assertion gate exists" -> "Verify and repair";
}

SaC ソースの作成では、必ず次の順序に従ってください。

1. 成功基準を定めてから計画する：writing-univer-plans を読み込み、<package.univer>/success-criteria/<topic>.md を作成または更新します。ワークブック上で確認できる証拠を十分に調べ、<package.univer>/plans/<topic>.md を作成または更新します。
2. 計画を実行する：executing-univer-plans を読み込み、計画を批判的に見直してから、Migration Pack を一度に 1 つずつ実行します。
3. 各パックを TDD で進める：test-driven-univer-development を読み込み、計画から assertions.ts のカバレッジを導き出し、意図したワークブック上で確認できる理由でアサーションが失敗することを確認します。
4. アサーションのゲートを設けてから実装する：計画と計画に基づくアサーションが揃ってから、Migration Pack を編集します。
5. 検証して修正する：univer sac verify <package.univer> --json と、返されたアサーションの証拠を使って修正を進めてから、完了を宣言します。

成功基準のチェックリストより先に計画を書いてはいけません。 計画より先に assertions.ts を書いてはいけません。 計画に基づくアサーションより先に Migration Pack を編集してはいけません。 すでに順序を誤って作業した場合は、いったん止めて、現在の証拠に基づいて不足している成功基準と計画を書き、その計画から TDD のループをやり直してください。

厳格なゲート

ワークブックの作業を汎用的なファイル解析タスクとして扱ってはいけません。Univer のスキルスタックと univer CLI をワークブックエンジンとして使用してください。

• exceljs、xlsx、pandas などのスプレッドシートライブラリや LibreOffice の自動化を、Univer CLI の代替としてインポートまたはインストールしてはいけません。
• .univer パッケージの内部を読み込んだり、変更したりしてはいけません。
• univer import、univer inspect、univer pipe、univer run、univer export、または SaC ワークフローで処理できるタスクでは、.xlsx ファイルを直接解析してはいけません。
• univer が生成したテキストまたは JSON ストリーム（pipe out の出力やコマンドの JSON など）には、シェルツールを使用してかまいません。ただし、これらはワークブックエンジンの代わりにはなりません。
• Univer の関連スキルを読み込み、CLI の手順では不十分であることが明らかになり、ユーザーが代替手段に同意した場合に限り、Univer 以外の代替手段を検討してください。

危険信号

次のように考えた場合は作業を止め、Univer CLI を使用してください。

考え	実際
「これはただの Excel ファイルだから、exceljs を使おう。」	ワークブックファイルには、まず Univer CLI を使用します。
「セルをいくつか確認するだけだ。」	univer inspect、search、pipe out、または読み取り専用の run を使用してください。
「ワークブックのパッケージを解凍するか、直接変更しよう。」	パッケージの内部は編集対象ではありません。
「パッケージのメタデータやコマンドの成功で検証しよう。」	ワークブック上で確認できる状態を検証してください。
「SaC apply が成功したから、動作は完成だ。」	SaC の完了には、テスト駆動の Univer アサーションによる証拠が必要です。

最初に行うこと

1. ワークブックの成果物と目標を特定します。
2. ワークブックの内容に触れる前に、担当する Univer スキルに作業を振り分けます。
3. パス優先の univer コマンドまたは SaC ソースのワークフローを使用し、ワークブックのパッケージ内部には触れないでください。
4. 完了を宣言する前に、ワークブック上で確認できる証拠を使って検証します。

ルートの詳細

タスクの種類	読み込むもの
ハーネス提供のワークブックタスクで、独自のローカルコントラクト、準備済みパッケージ、または必須の引き継ぎ成果物がある場合	まずタスク固有のハーネスコントラクトに従い、その後、適切なワークブックまたは SaC のルートに沿って univer-cli を使用します
通常のワークブック上で確認可能な調査、検索、インポート、エクスポート、パイプ、範囲を限定した編集、数式の確認、プレビュー、コメント、コミット、プル、同期	univer-cli
SaC ソースの作成、Facade Migration Pack の作業、assertions.ts、univer sac、または複雑なワークブック動作の開発	writing-univer-plans、executing-univer-plans、続いて test-driven-univer-development
SaC ソースがない既存またはレガシーのワークブックで、ユーザーが動作を SaC ソースに変換することを希望する場合	読み取り専用のベースライン調査には univer-cli を使い、その後 writing-univer-plans、executing-univer-plans、test-driven-univer-development を使用します

通常のワークブック上で確認可能な作業では、ユーザーが SaC ソースまたは永続的なワークブック動作の作成を求めない限り、SaC TDD ワークフローに進まないでください。

通常のワークブック上で確認可能なタスクでは、univer-cli を読み込み、ワークブック上で確認できる検証を行ってください。

SaC TDD ルート

SaC ソースの作成または複雑なワークブック動作の開発では、次の手順に従います。

1. 移行ソースを編集する前に writing-univer-plans を読み込みます。
2. <package.univer>/success-criteria/ にパッケージ固有の成功基準を記述または更新し、 続いて <package.univer>/plans/ に計画を記述します。
3. executing-univer-plans を読み込み、パックごとに計画をレビューして実行します。
4. アサーションのカバレッジ、適用／検証、修正、 引き継ぎのゲートには test-driven-univer-development を読み込みます。

要するに、ワークブック動作の成功基準と計画を定義するには writing-univer-plans を読み込み、計画を実行するには executing-univer-plans を読み込み、各パックを実装して検証するには test-driven-univer-development を読み込みます。

複雑な SaC 動作では writing-univer-plans を省略しないでください。範囲の役割、パックの境界、アサーションのゲートを明確にするのが計画の役割です。

レガシーワークブックの初期設定

ユーザーが SaC ソースのないレガシーワークブックを提供した場合は、univer-cli を使って、調査、検索、パイプ出力、読み取り専用の実行スクリプトなどの読み取り専用ベースライン調査を行います。続行する前に、有用な情報を SaC の計画、移行ソース、またはアサーションに記録してください。

読み取り専用のベースライン調査は、完了の証拠にはなりません。SaC TDD の完了の証拠は test-driven-univer-development から得られます。変更したパックにはアサーションのカバレッジが必要であり、関連する univer sac verify <package.univer> --json の実行が成功している必要があります。

完了の証拠

• 通常のワークブック作業では、univer-cli によるワークブック上で確認可能な検証が必要です。例として、inspect、search、pipe out、範囲を限定した run、プレビュー、コメント、エクスポート／インポートの確認があります。
• SaC TDD の作業では、test-driven-univer-development による証拠が必要です。アサーションのカバレッジに加え、関連する univer sac verify <package.univer> --json の実行が成功している必要があります。
• コマンドの要約、パッケージのメタデータ、univer sac apply の成功、または読み取り専用の調査を、SaC TDD の最終的な証明として扱わないでください。
• タスクの種類が不明な場合は、通常のワークブック編集を希望するのか、永続的な SaC ソースの動作を希望するのか、ユーザーに確認してください。