# DSH Skill Toggle — 完整技術說明

**替每個 workspace 選擇可用 skills，不修改技能內容，也不需要 DSH core patch。**

MIT 授權的獨立 DSH Web plugin。Settings 管理全域預設及 workspace 覆寫；對話頂端的捷徑會開啟同一個管理介面。

[English](<REFERENCE.en.md>) · [正式規格](../docs/SPEC.md) · [術語表](../GLOSSARY.md) · [v0.1.5 歷史驗收](../docs/acceptance/)

固定雜湊的 0.1.7 已通過[獨立驗收](../docs/verification/2026-10-24/INDEPENDENT-ACCEPTANCE.md)；上面的歷史報告只對應 0.1.5。

## 功能

- 搜尋、來源篩選，查看 provider、來源種類及指令檔路徑。
- 全域或 workspace 的「沿用／啟用／僅手動／停用」。
- 個別及原子批次更新；限制性批次確認範圍與數量，過期版本拒絕覆寫。
- Plugin 隨附、bundled 及無法確認來源的 skills **唯讀保護**。
- 政策影響現有 session 的後續載入，不只是關掉 GUI 開關。
- 分開顯示選取設定、有效狀態與生效來源。
- 歷史載入證據不冒充「目前仍在 context」或「模型確實遵循」。
- 設定保存在本機，不污染 repo；檔案損壞時保留最後有效政策。
- 英文與繁體中文、鍵盤可操作、窄視窗版面。

不提供 skill 安裝、更新、編輯、刪除、MCP 管理、session 獨立覆寫或歷史指令卸載。

## 安裝

0.1.7 已發布至 npm；套件安裝指令見[快速入門](../README.md)。以下保留從原始碼建立及安裝本機 tarball 的方式：

```sh
npm ci --ignore-scripts
npm run typecheck
npm run test:dev
npm run pack:local

# 請替換成實際套件的絕對路徑。
dsh plugin --profile web add /absolute/path/dsh-skill-toggle-0.1.7.tgz
```

透過標準 bundle 掛載 host 與 Web client；不修改 DSH core。安裝後重新啟動目標 DSH process，再重新整理它原本的 Web URL。裝到其他 profile 不會更新你目前的 GUI。

初期目標版本為 **DSH 0.2.1-rc.2**；Node 支援 **22 系列的 22.19+ 或 24+**。實際驗收 artifact、環境與限制以獨立驗收報告為準；未測版本與 Desktop 不宣稱相容，不建議繞過 DSH 相容性檢查。

## 使用方式

1. 開啟 **Settings → Skills／技能管理**。
2. 在「工作區」確認標題與路徑，或切到「全域」修改共同預設。
3. 一般開關控制啟用／停用；進階選單提供完整四態。
4. 批次只操作明確勾選項目；「全選」只涵蓋當前篩選結果中可管理的項目。
5. 檢查「選取／有效／來源」；來源原本限制仍然有效。

對話捷徑使用同一管理頁的可存取 dialog，不是 session-specific policy。無法確認該 session 的 workspace 時，須明確選擇，不會悄悄修改全域設定。

| 模式 | 意義 |
|---|---|
| 沿用 | 目前層級不指定覆寫 |
| 啟用 | 尊重來源原本規則，不額外限制 |
| 僅手動 | 禁止模型自行發現及載入；只有來源允許時才保留使用者載入 |
| 停用 | 禁止透過 skill 入口進行後續模型與使用者載入 |

Workspace 覆寫優先於全域預設，但兩者都不放寬來源限制。例如「啟用」不會繞過來源的 `disable-model-invocation: true`。

## 來源保護與同名技能

只有能正面驗證的本機 filesystem 定義可管理。Plugin 隨附／bundled skills 完全唯讀，也不能設為僅手動。其他 provider、虛擬技能、套件目錄、超出已驗證 roots 的 symlink 目標或歸屬不明來源，一律保守唯讀。來源文字標籤不是通用的 plugin ownership 或安全證明。

支援標準 filesystem provider 的個人／專案 roots。Custom／非標準掛載需要能獨立驗證來源，必要時在此 plugin 明確設定相同 custom roots；不把技能複製到私有 library。

政策按具體來源與實體檔案識別，不只按名稱。同名不同檔案不會一起被關閉；檔案搬移視為新身分。更高優先序的受保護 plugin 定義不應被同名個人定義的開關取代。全域 Settings 會彙整已註冊 workspace 與 preset；每列會標示在哪些 preset／cwd 勝出或被覆蓋，包括只在部分情境勝出的項目。

## 停用不等於卸載

已載入的指引仍在對話歷史，仍可能影響後續回答。載入標記是**按名稱**觀察到的歷史成功載入／注入，不證明目前檔案版本曾被載入、仍在 active context 或模型曾遵循；PTC 紀錄也可能僅在程式內部使用。

歷史資料不完整／不可取得時，「未觀察到」不是「從未載入」。若要乾淨的無 skill 基線，請套用政策後另開新對話，不帶入舊指令或摘要。Skill 停用不是 shell、檔案或網路的權限隔離。

### 內建 `/` 選單限制

Stock DSH 0.2.1-rc.2 另外快取 slash picker；冷 session 的選單也可能使用 preset 而非 live Agent scope。因此停用名稱可能仍出現在內建選單，但實際載入必須被阻擋。

重新整理／重新連線瀏覽器可清除 picker 快取；冷 session 在 Agent 建立前仍可能公告名稱。此 plugin 管理頁才是有效政策視圖。不偽造其他 plugin-change 事件強制刷新。

政策不打斷已送出的模型請求。後續查詢／組裝才套用；stock DSH 可能追加完整替代清單，而非最小差異。歷史不回頭改寫，也不保證零 cache miss 或固定 token 節省比例。

## 保存與復原

預設檔案是 `$DSH_HOME/skill-toggle/policy.json`，通常位於 `~/.dsh` 下。本機 host 的授權 owner 瀏覽器共用，不寫入受管理 repo。

Workspace 使用註冊身分。同路徑刪除後重加不會繼承舊覆寫；原工作區身分不變時，其政策紀錄會保留，例如套用在固定位置個人 skill 的覆寫。若專案 skill 文件也跟著搬動，依具體來源／路徑規則會成為新文件身分，不自動猜測文件政策遷移。

- 第一次執行尚無檔案是合法預設。
- 執行中讀到無效資料，沿用最後有效政策並停止寫入。
- 啟動時沒有有效政策，已知受管理 skills 的後續載入 fail-closed；受保護／未知來源不受此 plugin 誤關。
- 還原有效的 versioned policy 檔案即可復原；不會把損壞檔案自動覆寫成空資料。沒有備份時可依[政策復原說明](../docs/RECOVERY.md)明確重設，但這會清除覆寫，可能重新啟用 skills。
- 使用暫存檔及 exclusive lock 寫入。鎖定檔可能仍屬於執行中的 writer，也可能是殘留鎖；plugin 不會猜測或自動刪除。請先稍候重試；若仍存在，停止 DSH、確認沒有 writer 後，只移除錯誤訊息列出的那個 `.lock` 檔。
- 此鎖只協調遵守本 plugin 鎖定協定的 writer。手動編輯 policy 前先停止 DSH。忽略鎖定檔的 writer 仍可能在最後一次版本比對與 atomic rename 之間寫入；若該編輯被覆蓋，plugin 無法事後還原。

可選 host 設定（只應修改你選定的目標 profile，不會自動套用）：

```yaml
- id: skill-toggle
  config:
    policyPath: /absolute/path/to/policy.json
    # 以下需對應來源的正式 filesystem 設定。
    # dshHome: /absolute/path/to/dsh-home
    # agentsHome: /absolute/path/to/agents-home
    # customSkillDirs:
    #   - /absolute/path/to/local-skills
```

JSON 是有版本的內部狀態，不是匯入／匯出格式。優先透過 GUI 更新；版本衝突與儲存錯誤會明確顯示，不靜默當成成功。

## 開發與驗收

```sh
npm run typecheck
npm run test:dev
npm run build
npm run pack:local
```

Host 在 live Agent scope 掛載政策 provider，從不含自身 overlay 的祖先 scope 讀取 baseline，並依官方 standing registry 提供的 provider/source/path identity 判定來源。額外驗證清單只用來顯示被覆蓋的候選；清單不完整時，介面會標示降級，已知受管理定義的政策 overlay 仍會保留。模型工具及使用者明確載入都須使用有效 invocation policy。管理請求透過既有 owner-only Connection fetch 路由，不另外開無認證 server。

以上開發檢查不代表獨立驗收通過。正式驗收由另一個 agent member 執行，在隔離 profile 啟動真正的 DSH Web，驗證安裝包、GUI 與載入行為；不拿 standalone Vite 預覽當成成功證據。

## 授權

MIT。這是獨立社群 plugin，不是 DeepSeek 官方產品。Plugin 在 host process 中執行；推廣時請提供原始碼與固定版本 artifact。