dsh-manage-session 0.0.0-stage → 0.2.3

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.6 -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.6
+```
+
+## 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.6 -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.6
+```
+
+## 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.6 -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.6
+```
+
+## 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 — **Retirement Home** and **Checkup** — while both feature gates are on.
+2. Turning `historyFiles` off removes the Retirement Home 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

package/INSTALL.zh.md

@@ -0,0 +1,164 @@
+# 安装指南（官方 DSH CLI）
+
+本指南只使用官方 `dsh plugin` 命令。该命令会把依赖装入 profile 并同步 `dsh.profile.bundles`。请勿改用裸 `npm install`、在 profile 里直接 `pnpm add`，或手工编辑 profile 清单。
+
+- [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)
+
+本指南中的占位符：
+
+- `<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 是 pnpm workspace 根时，如 `web`，`-w` 是必需的。）
+
+显式安装指定版本：
+
+```bash
+dsh plugin --profile <profile> add dsh-manage-session@0.1.0-alpha.6 -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.6
+```
+
+## 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` | 把该版本加入该 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drscrewdriver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.