dsh-upgrade-audit

English | 简体中文

dsh-upgrade-audit

2 つの DSH バージョン間で、リポジトリの外部の利用者が観測できるすべての変更を監査し、ユーザーが期待するレポート一式を作成します。この問題の定型的な問いは、from と比べて、to には変更や取り消しが増えているか？ です。「変更が増えている」とは、外部から見える互換性の破壊（エクスポートの削除、ワイヤーエラーコードの変更、読み込み時に拒否されるデータ形式）を意味します。「取り消し」とは、期間内のリバートによって、from に存在していた動作が意図的に撤回されたことを意味します。どちらにも根拠が必要です。コミットメッセージやサブエージェントの要約は主張にすぎません。根拠として認められるのは、両方のツリー（ソースファイルまたは公開済みパッケージ）を読んだうえで導かれた結論だけです。

外部互換性とは、リポジトリの外部の利用者が観測できるすべてを指します。npm パッケージの公開 API（エクスポート、型、シグネチャ、依存関係の範囲）、dsh CLI（コマンド、フラグ、プロファイル、設定キー）、ワイヤープロトコル（SDK JSON-RPC、リモートゲートウェイ／BFF、ACP、フック）、ディスク上のセッションデータ（JSONL ログ、SQLite ストアとそのバージョンガード）、モデルから見えるインターフェース（ツール名／スキーマ、システムプロンプトの出力）、および Python SDK の想定が含まれます。内部リファクタリングは背景情報であり、報告対象ではありません。まとめて件数を数えてください。

注：レポートの言語はユーザーの言語に従います（下記の「出力仕様」を参照）。examples/ にある既存のサンプルレポートは、歴史的な慣例により英語です。

フェーズ 0 — 入力を解析してモードを選択する

入力：2 つのバージョン識別子（0.1.2-alpha.2、dsh-v0.1.2-alpha.2、dist-tag の alpha／latest／next を受け付けます）。具体性の高い順に、次の基準で分析モードを選択します。

1. コンテキストパス — ユーザーがメッセージ内で deepseek-harness のチェックアウトディレクトリを指定した場合。確認項目：ルートの package.json、packages/、AGENTS.md がすべて存在すること。
2. DSH_SOURCE_PATH 環境変数 — 同じ方法で確認します。（任意の DSH_NPM_REGISTRY で npm レジストリを上書きできます。）
3. CWD のヒューリスティック — 現在のディレクトリ自体が deepseek-harness のチェックアウトである場合（同じ方法で判定します）。
4. npm モード — 上記のどれにも当てはまらない場合（サードパーティーのリポジトリでのデフォルト経路）：分析のために、2 つのバージョンの公開済みパッケージをダウンロードします。

ソースモードでは git タグを監査し、npm モードでは公開済みの成果物を監査します。監査の中核（再構成するインターフェース、分類、検証、レポート作成）は共通です。異なるのは、成果物の展開方法と一部の証拠情報源だけです。npm モードを選ぶ前に、その制約を把握してください。npm のバージョン一覧と git タグの一覧は一致しません（例：0.1.2-alpha.1 にはタグがありますが、公開されていません。成果物展開スクリプトは公開済みバージョンの一覧で終了するため、バージョンの組み合わせを黙って置き換えず、不一致をユーザーに伝えてください）。CLI の依存関係には、公開可能なすべてのパッケージが含まれるわけではありません（SQLite 永続化バックエンドは CLI の依存関係ではないため、スクリプトが補助パッケージとしてインストールします）。

出力契約

すべての成果物は 1 つのディレクトリ tmp/<fromNorm>-to-<toNorm>/ に格納されます（正規化：dsh-v を除去し、プレリリース部分のドットを除去します — dsh-v0.1.2-alpha.1 → 0.1.2alpha1）。ソースモードではチェックアウト内（gitignore 対象）に作成され、npm モードでは現在のプロジェクト内に作成されます。対象ディレクトリがすでに存在する場合、以前に手作業で作成されたレポートである可能性が高いため、いったん停止して、まず確認してください。上書きしてはいけません。

成果物	ソースモード	npm モード
commits.txt、reverts.txt	git から取得。リバートは CHANGELOG にまとめます	GitHub の比較情報で補完（プライベートリポジトリの場合はなし）
files.txt、diffstat.txt、完全な .diff	git ツリーの差分	manifest-diff.txt（パッケージごとのマニフェスト差分）＋公開済みパッケージのツリー a/、b/
CHANGELOG.md	種類別に分類し、Reverts セクションを必ず含めます	補完情報がある場合に生成します。ない場合は、明示的な注記を添えて省略します
UPGRADE-ADAPTATION.md	監査レポート（両モードで同じひな形）	同じ。ヘッダーにモードとバージョンの出典を記録します

レポートの言語はユーザーの言語に合わせます（examples/ の既存レポートは歴史的な慣例により英語ですが、必須ではありません）。

フェーズ 1 — 2 つのツリーを用意する

ソースモード — まず純粋性を確認します。マージベースが from 自体ではない場合はベースがずれているため、停止して報告し、変動するベースラインとの差分を取ってはいけません。

git merge-base <from> <to>   # must equal <from>'s commit
node <skill-dir>/scripts/gen-artifacts.mjs <from> <to> tmp/<pair>

npm モード：

node <skill-dir>/scripts/materialize-npm.mjs <from> <to> tmp/<pair>

スクリプトは両方のバージョンをレジストリで解決します（見つからない場合は公開済みバージョンの一覧とともに終了コード 1 で終了します。その不足をユーザーに伝えてください）。@deepseek-ai/dsh の依存関係一式と SQLite 補助パッケージを --ignore-scripts を付けて a/ と b/ にインストールし、すべての @deepseek-ai/* パッケージについて、パッケージごとのマニフェスト差分から manifest-diff.txt を生成し、公開 GitHub リポジトリから情報を補完します（commits.txt、reverts.txt）。これにより、ソースのチェックアウトがなくてもリバートを検出できます。

統計出力を基に調査規模を決めます。マージ以外のコミットが 40 件以下なら、調査対象のサーフェスのチェックリストをインラインで実行します。40～250 件なら 3～4 個のファサードを統合し、それより多い場合は 6 個すべてのファサードを対象にします。密度を比較するには、直前のペアの commits.txt を開きます。直前のペアとは、時系列順で直前に位置するペアのことであり、tmp/ 内の最新ディレクトリとは限りません。

フェーズ 2 — まず共通の事実を確認する

各サブエージェントがそれぞれ再調査せずに済むよう、1 回だけ実行し、すべてのサブエージェントに共有します。

• フォーマットガード — ソースモードでは、両方のタグで SESSION_FORMAT_VERSION（packages/core/session/src/types.ts）と SQLite の SCHEMA_VERSION（packages/session/session-persistence-sqlite/src/schema.ts）を確認します。npm モードでは、dsh-session と補助パッケージの公開済み lib/*.js から、同じ名前の定数を grep します。ガードの値が移行パスなしで変わっている場合は、重大なデータ破損です。レポートの冒頭に記載してください。
• リバート一覧 — ソースモード：git log --grep='[Rr]evert' <from>..<to>。npm モード：補完された reverts.txt（存在しない場合、リバートの 意図 は検出できません。その旨を明記し、from→to の差分監査のみを実施してください）。
• Python SDK — ソースモード：python/ の差分を確認します。npm モード：npm 成果物の対象範囲外であるため、1 文で十分です。

フェーズ 3 — ファサードを並列でスキャンする

references/audit-playbook.md の出力契約を各エージェントに渡し、読み取り専用の調査エージェントをファサードごとに 1 つずつ並列バッチで起動します。各エージェントには、フェーズ 2 の共通情報も渡します。セクションの順序は REMOVED（最初に記載。破壊的変更やリバートの候補）、CHANGED（変更前 → 変更後）、ADDED、RENAMED とします。各項目には、パッケージ／パス、シンボルまたはフィールド、影響範囲の分類（SDK 利用者／CLI ユーザー／設定作成者／セッションデータ／モデルに表示される項目／プロトコルの接続先／Web UI／npm インストーラー）を記載し、最後に 1 行の判定を付けます。モード別のファサードごとの対象パス一覧はプレイブックにあります。

フェーズ 4 — 公開前に検証する

調査結果は手がかりであり、確定した事実ではありません。REMOVED、revert、wire に関する主張はすべて、自分で再検証してください。source モードでは、両方のタグに対して git show <tag>:<path> と git ls-tree を使います。npm モードでは、公開済みの両方のツリー（a/node_modules/... と b/node_modules/...）を読みます。この手順には実例に基づく教訓があります。調査エージェントが、alpha.1 にすでに存在していたパッケージを「alpha.2 で追加」と報告したことがありました。検証できないものは、[INFERENCE] と明記するか、削除します。

フェーズ 5 — UPGRADE-ADAPTATION.md を作成する

references/audit-playbook.md のひな形に従って、ヘッダー（対象範囲、統計、モードと出典情報、source モードの純度に関する注記）、判定（比較に関する問いに直接回答）、§1 revert、利用者への影響が大きい順に並べた破壊的変更のセクション（削除を最初にし、それぞれに影響を受ける対象を明記して、適応: の行を追加）、変更が確認されなかった項目（互換性が保たれている部分も、破壊的変更と同様に重要です）、境界シグネチャテーブル [API surface | from | to | changed?]、番号付きの移行チェックリストを含めます。詳細な作成例は、examples/0.1.2alpha1-to-0.1.2alpha2/（実際の source モード監査）を参照してください。チャットでの返信には、ユーザーの言語を使います。

ガード

• 読み取り専用とします。source モードでは tmp/<pair>/ の外部には何も変更しません。npm モードでは専用の tmp/<pair>/ のみに書き込み、--ignore-scripts を指定してそのディレクトリにインストールします。ホストプロジェクトの node_modules には dsh パッケージを決してインストールしないでください。
• ログから推測した説明を信用せず、ツリーレベルの事実（公開済みファイル、2 つのタグの読み取り）を優先します。
• 内部の無関係な変更（テスト、ノート、i18n、スタイル）は合計件数にまとめ、個別に列挙しないでください。
• npm モードでは制約を正直に記録します。enrichment がないため git 履歴を確認できないこと、CLI の tarball に含まれるのは lib/ のみであること（設定の構成は、各バンドルパッケージの cordis.patch.yml と manifest で監査）、Python SDK は対象外であることを記載します。
• 20 コミットの範囲をすべて展開しないでください。500 コミットの範囲をインライン展開しないでください。規模を見誤ることが、監査が古くなったり浅くなったりする主な原因です。

plugin-upgrade との関係

このスキルはホストバージョンとの互換性を示す証拠（レポートと境界シグネチャテーブル）を作成します。plugin-upgrade はその証拠（バージョン変更カード）を利用して、単一のプラグインの移行を実行します。監査で得た知見は、カードの「現場メモ」に直接反映できます。plugin-upgrade にカードを追加する際は、記憶を頼りに言い換えるのではなく、このスキルのレポートディレクトリを出典として記載してください。