dsh-manage-session 0.0.0-stage → 0.1.0-alpha.0

package/CHANGELOG.ja.md

@@ -0,0 +1,29 @@
+# 変更履歴
+
+## 0.1.0-alpha.0
+
+最初の alpha 版：セッション・スチュワード（履歴ファイル + 健康チェック）。
+
+### 追加
+
+- **セッション履歴ファイル（カルテ室）**：`dsh-session-search-toggle` から公式アーカイブ集合の読み取りとクリーンアップの実装を移入し、
+  挙動は移行前と等価（バックアップ + 同一ディレクトリへの一時書き込み + アトミック置換。明示的な編集モードでのみクリーンアップを許可）。
+  差分：一覧の取得元を**公式アーカイブ集合の真値**（registry 優先、ストレージファイルにフォールバック）に変更。独立インデックスは検索インデックスパッケージとともに離れたため。
+  タイトルなどのメタデータはベストエフォート（`sessionQuery` のタイトルスナップショット → プロジェクションキャッシュの title → 空）。
+- **健康チェック（健診 → 処方 → 退院）**：独立にテスト可能な四つのゲート
+  （`log-integrity` / `projection-cache` / `lossless-json` / `cold-read`）を備え、
+  統一の出力 `{ id, level, evidence, attribution, detail }`、集約結果は `SessionHealthReport`。
+- **帰属インデックス**：profile の `node_modules/<pkg>/lib/*.js` を静的に走査して「プロジェクション key → パッケージ名」を構築し、
+  失敗したゲートを具体的なプラグインとフィールドパスに紐付ける。走査できない場合は正直に `unknown` と表示する。
+- **可逆的な処方**：破損したプロジェクションキャッシュのレコードを隔離（先にコピーでバックアップし、`.quarantine-<ts>` へ移動）+ コマンド一覧。
+  **禁止**事項：セッションログの書き換え、履歴データの変更、フィールドの暗黙的な破棄。
+- **二つの feature gate**：`historyFiles` / `healthCheck`。オフのときは対応するサブドメイン全体が登録されず（明示的な disabled エラー）、
+  クライアントも対応するタブを描画しない。
+- **ルート**：`/session-steward/api/*`。メソッド名は一律 `session-*` で、検索インデックスの `/switch-search/api` の `index-*` とは完全に分離。
+
+### 既知の制限
+
+- `lossless-json` ゲートは、ホストが `sessionProjections`（ホット状態）を公開している場合にのみ確定判定を下せる。
+  取得できないときは正直に `warn` へ降格し、推測はしない。
+- 健康スキャンは既定で直近 30 件の非健康セッションのみを列挙する（`limit` の上限は 200）。全件走査は既定の挙動としない。
+- クライアントパネルは最小実装（一覧 + 詳細 + 三ステップのボタン）で、仮想スクロールと一括操作は未実装。

package/CHANGELOG.ko.md

@@ -0,0 +1,29 @@
+# 변경 이력
+
+## 0.1.0-alpha.0
+
+첫 번째 alpha 버전: 세션 스튜어드(히스토리 파일 + 상태 점검).
+
+### 추가
+
+- **세션 히스토리 파일(기록 보관소)**: `dsh-session-search-toggle`에서 공식 아카이브 집합의 읽기 및 정리 구현을 이관했으며,
+  동작은 이관 전과 동등합니다(백업 + 동일 디렉터리 임시 쓰기 + 원자적 교체; 명시적 편집 모드에서만 정리 허용).
+  차이점: 목록 출처가 **공식 아카이브 집합 진값**으로 변경되었습니다(registry 우선, 스토리지 파일 폴백). 독립 인덱스가 검색 인덱스 패키지와 함께 떠났기 때문입니다;
+  제목 등 메타데이터는 최선 노력 방식입니다(`sessionQuery` 제목 스냅샷 → 프로젝션 캐시 title → 비어 있음).
+- **상태 점검(점검 → 처방 → 퇴원)**: 독립적으로 테스트 가능한 네 개의 gate
+  (`log-integrity` / `projection-cache` / `lossless-json` / `cold-read`),
+  통일된 출력 `{ id, level, evidence, attribution, detail }`; `SessionHealthReport`로 집계됩니다.
+- **귀속 인덱스**: 프로필의 `node_modules/<pkg>/lib/*.js`를 정적 스캔하여 「프로젝션 key → 패키지 이름」을 구축하고,
+  실패한 gate를 구체적인 플러그인과 필드 경로로 되돌려 지목합니다; 찾지 못하면 사실대로 `unknown`으로 표기합니다.
+- **되돌릴 수 있는 처방**: 손상된 프로젝션 캐시 레코드 격리(먼저 복사 백업, 그다음 `.quarantine-<ts>`로 이동) + 명령 목록.
+  세션 로그 재작성, 히스토리 데이터 변경, 필드 무단 삭제는 **금지**합니다.
+- **두 개의 feature gate**: `historyFiles` / `healthCheck`, 꺼지면 해당 하위 도메인 전체가 등록되지 않고(명시적 disabled 오류),
+  클라이언트도 해당 탭을 렌더링하지 않습니다.
+- **라우트**: `/session-steward/api/*`, 메서드 이름은 일괄 `session-*`이며, 검색 인덱스의 `/switch-search/api`의 `index-*`와 완전히 격리됩니다.
+
+### 알려진 제한
+
+- `lossless-json` gate는 호스트가 `sessionProjections`(핫 상태)를 노출해야 확정 판정을 내릴 수 있습니다;
+  얻지 못하면 사실대로 `warn`으로 강등하며, 추측하지 않습니다.
+- 상태 스캔은 기본적으로 최근 30개의 비정상 세션만 나열하며(`limit` 상한 200), 전체 라이브러리 순회를 기본 동작으로 삼지 않습니다.
+- 클라이언트 패널은 최소 구현(목록 + 상세 + 3단계 버튼)이며, 가상 스크롤과 일괄 작업은 구현하지 않았습니다.

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0-alpha.0
+
+首个 alpha 版本：会话管家（历史文件 + 健康检查）。
+
+### 新增
+
+- **会话历史文件（病案室）**：从 `dsh-session-search-toggle` 迁入官方归档集合的读取与清理实现，
+  行为与迁移前等价（备份 + 同目录临时写 + 原子替换；显式编辑模式才允许清理）。
+  差异：列表来源改为**官方归档集合真值**（registry 优先、存储文件回退），因为独立索引已随搜索索引包离开；
+  标题等元数据为尽力而为（`sessionQuery` 标题快照 → 投影缓存 title → 空）。
+- **健康检查（体检 → 处方 → 出院）**：四个可独立测试的 gate
+  （`log-integrity` / `projection-cache` / `lossless-json` / `cold-read`），
+  统一输出 `{ id, level, evidence, attribution, detail }`；聚合为 `SessionHealthReport`。
+- **归属索引**：静态扫描 profile 的 `node_modules/<pkg>/lib/*.js`，建立「投影 key → 包名」，
+  把失败 gate 指回具体插件与字段路径；扫不到时如实标 `unknown`。
+- **可逆处方**：隔离损坏的投影缓存记录（先复制备份，再移动到 `.quarantine-<ts>`）+ 命令清单。
+  **禁止**改写会话日志、改历史数据、静默丢弃字段。
+- **两个 feature gate**：`historyFiles` / `healthCheck`，关闭时对应子域整域不注册（显式 disabled 错误），
+  客户端也不渲染对应页签。
+- **路由**：`/session-steward/api/*`，方法名一律 `session-*`，与搜索索引的 `/switch-search/api` 的 `index-*` 完全隔离。
+
+### 已知限制
+
+- `lossless-json` gate 依赖宿主暴露 `sessionProjections`（热态）才能给出确定判定；
+  拿不到时如实降级为 `warn`，不臆测。
+- 健康扫描默认只列最近 30 个非健康会话（`limit` 上限 200），不做全库遍历的默认行为。
+- 客户端面板为最小实现（列表 + 详情 + 三步按钮），未做虚拟滚动与批量操作。

package/INSTALL.ja.md

@@ -0,0 +1,164 @@
+# インストールガイド（公式 DSH CLI）
+
+本ガイドは公式 DSH の `dsh plugin` コマンドのみを使用します。このコマンドは依存関係を profile にインストールし、`dsh.profile.bundles` を同期します。素の `npm install`、profile 内での直接の `pnpm add`、profile マニフェストの手動編集で置き換えないでください。
+
+- [英語インストールガイド](./INSTALL.md)
+- [中国語インストールガイド](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [韓国語インストールガイド](./INSTALL.ko.md)
+- [中国語 README](./README.md)
+- [英語 README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [韓国語 README](./README.ko.md)
+- [変更履歴](./CHANGELOG.md)
+- [日本語の変更履歴](./CHANGELOG.ja.md)
+- [韓国語の変更履歴](./CHANGELOG.ko.md)
+
+本ガイドで使用するプレースホルダは次のとおりです：
+
+- `<profile>`：変更対象の DSH profile。通常は `web`。
+- `dsh-manage-session`：npm パッケージ名かつランタイムプラグイン ID。
+
+> **対応 DSH 範囲：`>=0.1.0-rc.6 <0.2.0-0`。**
+>
+> これは `package.json` と `dsh.plugin.json` の双方の `engines.dsh` で宣言されている範囲であり、本プラグインが自身の `@deepseek-ai/dsh-client-ui-slots` 依存に対してすでに宣言している `^0.1.0-rc.6` の下限とも一致します。インストール前に `dsh --version` で実行中のバージョンを確認してください。
+
+## 0. 前提条件と profile の確認
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+実行中の DSH プロセスが指定している profile を使用してください。`web` が一般的ですが、実際に有効なのは `--profile` 引数です。
+
+## 1. 公式インストール
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+（profile が `web` のように pnpm ワークスペースのルートである場合、`-w` フラグが必要です。）
+
+特定のバージョンを明示的にインストールする場合：
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@0.1.0-alpha.0 -w
+```
+
+公式 CLI は profile の依存関係、ロックファイル、`dsh.profile.bundles` を自動的に更新します。YAML の行を手動で追加しないでください。
+
+### サプライチェーンのクーリング期間
+
+DSH ランタイムは pnpm 11 を使用しており、その `minimumReleaseAge` ポリシーが公開直後のバージョンを `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` でブロックすることがあります。`~/.dsh/profiles/<profile>/pnpm-workspace.yaml` の `minimumReleaseAgeExclude` にそのバージョンを追加してください：
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@0.1.0-alpha.0
+```
+
+## 2. ホストの再起動
+
+**インストールまたはアップグレードの後には DSH の再起動が必要です。** ブラウザのページを再読み込みするだけでは不十分です。ホスト側は起動時に `/session-steward/api` ルートと設定名前空間を登録し、またアーカイブの取得元を再読み込みしない限り整理（prune）の結果は反映されません。
+
+## 3. アップグレード
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+その後 DSH を再起動してください。
+
+## 4. ローカルパス / `link:` による登録（代替手段）
+
+開発やオフラインインストールでは、ローカルのチェックアウトからプラグインを登録します：
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+または、ローカルパスを指定して公式 CLI を使います（ネットワーク不要）：
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+ソースチェックアウトからビルドする場合は次のスクリプトを使います：
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/` はコミットされていないため、ソースチェックアウトはパス指定で登録する前にビルドする必要があります。公開時は `prepublishOnly` フックによって自動的にビルドされます。
+
+## 5. インストールの確認
+
+依存関係とインストール済みバージョンを確認します：
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+公式のコンポジションを確認します：
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+次の内容が含まれている必要があります：
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. プラグインの確認
+
+再起動後、サイドバーエントリ `dsh-manage-session` が利用可能になり、設定セクションは `session-steward` 名前空間を使用します。次を確認してください：
+
+1. 両方のフィーチャーゲートがオンのとき、**カルテ室**と**健診**の両タブが描画される。
+2. `historyFiles` をオフにするとカルテ室タブが消え、すべての `session-history-*` 呼び出しが明示的な disabled エラーを返す。
+3. `healthCheck` をオフにすると健診タブが消え、すべての `session-health-*` 呼び出しが明示的な disabled エラーを返す。
+4. `/session-steward/api` 上の未知のメソッドは、黙って成功せず明示的なエラーを返す。
+
+閉じられたドメインは `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` を返します — プラグインは空の殻を後に残しません。
+
+## 7. トラブルシューティング
+
+| 症状 | 対処 |
+| --- | --- |
+| `dsh` が見つからない | 公式 DSH CLI をインストールするか有効化してください。 |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | profile の `pnpm-workspace.yaml` の `minimumReleaseAgeExclude` にそのバージョンを追加してください。 |
+| インストール後にタブやルートが表示されない | ホストプロセスを再起動してください — ページの再読み込みではルートは再登録されません。 |
+| アーカイブ集合への変更が反映されない | ホストを再起動してください。アーカイブの取得元は起動時に読み込まれます。 |
+| `session-history-*` が disabled エラーを返す | `historyFiles` ゲートがオフです。プラグイン設定で再度有効にしてください。 |
+| `session-health-*` が disabled エラーを返す | `healthCheck` ゲートがオフです。プラグイン設定で再度有効にしてください。 |
+| アップグレード後にクライアントバンドルが古い | ブラウザをスーパーリロードしてください（Ctrl+Shift+R）。 |
+
+## 8. 削除
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+その後 DSH を再起動してください。
+
+## 削除しても修復は元に戻らない
+
+本プラグインはセッションログや履歴データを書き換えることも、フィールドを暗黙に破棄することもありません。一見不可逆に見える唯一の操作 — 破損したプロジェクションキャッシュのレコードを隔離する — も、先にバックアップをコピーし、隔離ディレクトリは復元できるようにディスク上に残します。したがって、プラグインを削除しても、あなたが実行した隔離はそのまま残ります。状態を元に戻したい場合は手動で復元してください。
+
+## ライセンス
+
+MIT

package/INSTALL.ko.md

@@ -0,0 +1,164 @@
+# 설치 가이드(공식 DSH CLI)
+
+이 가이드는 공식 DSH `dsh plugin` 명령만 사용합니다. 이 명령은 의존성을 프로필에 설치하고 `dsh.profile.bundles`를 동기화합니다. 이를 일반 `npm install`, 프로필에서의 직접적인 `pnpm add`, 또는 프로필 매니페스트의 수동 편집으로 대체하지 마세요.
+
+- [영어 설치 가이드](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [영어 README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [변경 이력](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+이 가이드의 자리표시자는 다음과 같습니다.
+
+- `<profile>`: 수정할 DSH 프로필이며, 보통 `web`입니다;
+- `dsh-manage-session`: npm 패키지이자 런타임 플러그인 ID입니다.
+
+> **지원 DSH 범위: `>=0.1.0-rc.6 <0.2.0-0`.**
+>
+> 이는 `package.json`과 `dsh.plugin.json` 양쪽의 `engines.dsh`에 선언된 범위이며, 이 플러그인이 자체 `@deepseek-ai/dsh-client-ui-slots` 의존성에 대해 이미 선언한 `^0.1.0-rc.6` 하한과 일치합니다. 설치 전에 `dsh --version`으로 실행 중인 버전을 확인하세요.
+
+## 0. 사전 요구 사항과 프로필 확인
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+실행 중인 DSH 프로세스가 지정한 프로필을 사용하세요. `web`이 일반적이지만, 활성 `--profile` 인자가 기준입니다.
+
+## 1. 공식 설치
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+(프로필이 `web`처럼 pnpm 워크스페이스 루트인 경우 `-w` 플래그가 필요합니다.)
+
+특정 버전을 명시적으로 설치:
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@0.1.0-alpha.0 -w
+```
+
+공식 CLI는 프로필 의존성, 잠금 파일, `dsh.profile.bundles`를 자동으로 갱신합니다. YAML 행을 수동으로 추가하지 마세요.
+
+### 공급망 쿨다운 기간
+
+DSH 런타임은 pnpm 11을 사용하며, 그 `minimumReleaseAge` 정책이 갓 게시된 버전을 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`과 함께 차단할 수 있습니다. `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`의 `minimumReleaseAgeExclude`에 해당 버전을 추가하세요:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@0.1.0-alpha.0
+```
+
+## 2. 호스트 재시작
+
+**설치 또는 업그레이드 후에는 DSH 재시작이 필요합니다.** 브라우저 페이지 새로고침만으로는 부족합니다: 호스트 측은 시작 시 `/session-steward/api` 라우트와 설정 네임스페이스를 등록하며, 정리 결과를 반영하려면 호스트가 아카이브 소스를 다시 로드해야 합니다.
+
+## 3. 업그레이드
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+이후 DSH를 재시작하세요.
+
+## 4. 로컬 경로 / `link:` 등록(대안)
+
+개발이나 오프라인 설치의 경우 로컬 체크아웃에서 플러그인을 등록합니다:
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+또는 로컬 경로와 함께 공식 CLI를 사용하세요(네트워크 불필요):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+소스 체크아웃에서 빌드할 때는 다음 스크립트를 사용합니다:
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/`는 커밋되지 않으므로, 소스 체크아웃은 경로로 등록하기 전에 빌드해야 합니다. 게시 시에는 `prepublishOnly` 훅을 통해 자동으로 빌드됩니다.
+
+## 5. 설치 검증
+
+의존성과 설치된 버전을 확인합니다:
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+공식 구성을 확인합니다:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+다음이 포함되어야 합니다:
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. 플러그인 검증
+
+재시작 후 사이드바 항목 `dsh-manage-session`를 사용할 수 있고, 설정 섹션은 `session-steward` 네임스페이스를 사용합니다. 다음을 확인하세요:
+
+1. 두 기능 게이트가 모두 켜져 있을 때 **기록 보관소**와 **점검** 두 탭이 모두 렌더링됩니다.
+2. `historyFiles`를 끄면 기록 보관소 탭이 사라지고 모든 `session-history-*` 호출이 명시적인 disabled 오류를 반환합니다.
+3. `healthCheck`를 끄면 점검 탭이 사라지고 모든 `session-health-*` 호출이 명시적인 disabled 오류를 반환합니다.
+4. `/session-steward/api`의 인식되지 않는 메서드는 조용히 성공하지 않고 명시적인 오류를 반환합니다.
+
+닫힌 도메인은 `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }`를 반환합니다 — 플러그인은 빈 껍데기를 남기지 않습니다.
+
+## 7. 문제 해결
+
+| 증상 | 조치 |
+| --- | --- |
+| `dsh`를 찾을 수 없음 | 공식 DSH CLI를 설치하거나 활성화하세요. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | 프로필의 `pnpm-workspace.yaml`에 있는 `minimumReleaseAgeExclude`에 해당 버전을 추가하세요. |
+| 설치 후 탭이나 라우트가 없음 | 호스트 프로세스를 재시작하세요 — 페이지 새로고침은 라우트를 다시 등록하지 않습니다. |
+| 아카이브 집합 변경 사항이 보이지 않음 | 호스트를 재시작하세요; 아카이브 소스는 시작 시 읽힙니다. |
+| `session-history-*`가 disabled 오류를 반환함 | `historyFiles` 게이트가 꺼져 있습니다. 플러그인 설정에서 다시 켜세요. |
+| `session-health-*`가 disabled 오류를 반환함 | `healthCheck` 게이트가 꺼져 있습니다. 플러그인 설정에서 다시 켜세요. |
+| 업그레이드 후 클라이언트 번들이 오래됨 | 브라우저를 강력 새로고침하세요(Ctrl+Shift+R). |
+
+## 8. 제거
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+이후 DSH를 재시작하세요.
+
+## 제거해도 복구가 되돌려지지는 않습니다
+
+이 플러그인은 세션 로그나 히스토리 데이터를 재작성하지 않으며, 필드를 조용히 버리지도 않습니다. 되돌릴 수 없어 보이는 유일한 동작 — 손상된 프로젝션 캐시 레코드 격리 — 은 먼저 백업을 복사하며, 격리 디렉터리는 복원에 사용할 수 있도록 디스크에 남겨 둡니다. 따라서 플러그인을 제거해도 요청한 격리 결과는 그대로 남습니다; 상태를 되돌리려면 직접 복원하세요.
+
+## 라이선스
+
+MIT

package/INSTALL.md

@@ -0,0 +1,164 @@
+# Installation Guide (Official DSH CLI)
+
+This guide uses only the official DSH `dsh plugin` command. That command installs the dependency into a profile and synchronizes `dsh.profile.bundles`. Do not replace it with plain `npm install`, a direct `pnpm add` in the profile, or manual edits to the profile manifest.
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+The placeholders in this guide are:
+
+- `<profile>`: the DSH profile to modify, usually `web`;
+- `dsh-manage-session`: the npm package and runtime plugin ID.
+
+> **Supported DSH range: `>=0.1.0-rc.6 <0.2.0-0`.**
+>
+> This is the range declared in `engines.dsh` of both `package.json` and `dsh.plugin.json`, and it matches the `^0.1.0-rc.6` floor this plugin already declares for its own `@deepseek-ai/dsh-client-ui-slots` dependency. Check the running version with `dsh --version` before installing.
+
+## 0. Prerequisites and profile discovery
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+Use the profile named by your running DSH process. `web` is common, but the active `--profile` argument is authoritative.
+
+## 1. Official installation
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session -w
+```
+
+(the `-w` flag is required when the profile is a pnpm workspace root, as `web` is.)
+
+Install a specific version explicitly:
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@0.1.0-alpha.0 -w
+```
+
+The official CLI updates the profile dependency, the lockfile, and `dsh.profile.bundles` automatically. Do not add a manual YAML row.
+
+### Supply-chain cooling period
+
+The DSH runtime uses pnpm 11, whose `minimumReleaseAge` policy may block a freshly published version with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`. Add the version to `minimumReleaseAgeExclude` in `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-manage-session@0.1.0-alpha.0
+```
+
+## 2. Restart the host
+
+**A DSH restart is required after installing or upgrading.** Refreshing the browser page is not enough: the host half registers the `/session-steward/api` routes and the settings namespace at startup, and the host must reload the archive source before it reflects a prune.
+
+## 3. Upgrade
+
+```bash
+dsh plugin --profile <profile> update dsh-manage-session -w
+```
+
+Restart DSH afterwards.
+
+## 4. Local-path / `link:` registration (alternative)
+
+For development or offline installs, register the plugin from a local checkout:
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-manage-session": "link:<absolute path to dsh-manage-session>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-manage-session
+#            name: dsh-manage-session
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+Or use the official CLI with a local path (no network needed):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-manage-session -w
+```
+
+Building from a source checkout uses these scripts:
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/index.d.ts + lib/client.js
+```
+
+`lib/` is not committed, so a source checkout must be built before it can be registered by path. Publishing builds it automatically through the `prepublishOnly` hook.
+
+## 5. Verify installation
+
+Check the dependency and the installed version:
+
+```bash
+grep -n "dsh-manage-session" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-manage-session/package.json').version"
+```
+
+Check the official composition:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+It must contain:
+
+```yaml
+- id: dsh-manage-session
+  name: dsh-manage-session
+```
+
+## 6. Verify the plugin
+
+After the restart, the sidebar entry `dsh-manage-session` is available and the settings section uses the `session-steward` namespace. Confirm:
+
+1. Both tabs render — **Records Room** and **Checkup** — while both feature gates are on.
+2. Turning `historyFiles` off removes the Records Room tab and makes every `session-history-*` call return an explicit disabled error.
+3. Turning `healthCheck` off removes the Checkup tab and makes every `session-health-*` call return an explicit disabled error.
+4. An unrecognized method on `/session-steward/api` returns an explicit error rather than succeeding silently.
+
+Closed domains return `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — the plugin does not leave empty shells behind.
+
+## 7. Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| `dsh` is not found | Install or enable the official DSH CLI. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | Add the version to `minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml`. |
+| Tabs or routes missing after install | Restart the host process — a page refresh does not re-register routes. |
+| Changes to the archive set are not visible | Restart the host; the archive source is read at startup. |
+| `session-history-*` returns a disabled error | The `historyFiles` gate is off. Re-enable it in the plugin settings. |
+| `session-health-*` returns a disabled error | The `healthCheck` gate is off. Re-enable it in the plugin settings. |
+| Stale client bundle after an upgrade | Hard-refresh the browser (Ctrl+Shift+R). |
+
+## 8. Remove
+
+```bash
+dsh plugin --profile <profile> remove dsh-manage-session
+```
+
+Restart DSH afterwards.
+
+## Removal does not undo repairs
+
+The plugin never rewrites session logs, history data, or silently drops fields. The only irreversible-looking action it takes — quarantining a damaged projection-cache record — copies a backup first, and the quarantine directory is left on disk for you to restore from. Removing the plugin therefore leaves any quarantine you asked for in place; restore it manually if you want the state back.
+
+## License
+
+MIT