claude-plugins-manager: Instructions file for Claude Code

Claude Plugins Manager — VSCode Extension

指令

npm run typecheck
npm test
npm run build
npm run verify
npm run check:schema
npm run install:ext
npm run watch

有程式碼改動先跑 npm run verify，完成後一律跑 npm run install:ext。

專案不變量

• src/shared/types.ts 放非 settings 共用型別；ClaudeSettings / HookCommand 只從 generated 檔轉匯出，禁止再手寫平行 interface。
• src/shared/claude-settings-schema.ts 是 settings value shape + UI metadata 唯一來源。section 陣列順序就是 UI 渲染順序，enum 用 schema value + String control，不要再加 hidden 逃生門。
• controlType 預設由 valueSchema 推導；只有 mixed union 或刻意走 custom editor 的欄位才顯式 override。
• options/min/max/step 也是由 valueSchema 即時推導，不要在 schema entry 或 flat schema 手寫平行資料。
• src/shared/claude-settings-types.generated.ts 是 schema 衍生物；build/typecheck/test/lint 會自動重生，禁止手改 generated 檔。
• Settings UI 以 schema-driven 為主；PermissionsSection 與 object 型欄位 editor 保持手動實作，其餘優先走 SchemaFieldRenderer。
• 已知 env vars 一律維護在 src/shared/known-env-vars.ts，不要在 UI 或 service 內各自維護清單。
• Extension 和 Webview 的通訊契約只走 protocol.ts 定義的 request/response/push message。
• Service 邊界保持清楚：CLI 封裝放 CliService，設定檔存取放 SettingsFileService，UI 偏好持久化放 PreferencesService。

設定頁開發

• 新增 setting 時，同步更新 schema、對應 editor/i18n，然後重生 settings generated types；不要再手動補 ClaudeSettings / HookCommand。
• 沒有自然落點的 user-facing key 直接放 advanced。
• Managed settings only 的 key 不做 first-party UI；包含 top-level managed key 與 sandbox nested managed key。若使用者既有 settings 檔有這些欄位，只保持 unknown/raw JSON 容忍，不新增一般 scope 控制項。
• 官方 docs 有但 SchemaStore 尚未收錄的 user-facing key 可以同步到 UI；type/default 以 docs 文字為準，並在 check:schema 只驗 repo 內 schema 一致性。
• controlType: Object 的欄位在對應 section 內手動渲染，不要硬塞進通用 renderer。
• Schema 巢狀欄位（如 permissions.defaultMode、permissions.disableAutoMode）若要在 UI surface 為 top-level 欄位，必須加 nestedUnder: 'permissions'，UI 才會寫到 settings.permissions[key]；漏加 → 寫到 settings[key] 頂層位置，CLI 讀不到（silent bug，UI toggle 完全沒效果）。
• 巢狀子欄位（nestedUnder 欄位、PermissionsSection 手寫子欄位、env 的變數）一律走 onSaveNested／onDeleteNested（protocol settings.setNested／settings.deleteNested），webview 不再用 settings.set 寫巢狀父物件；父物件刪到變空由擴展端刪父 key。settings.set／settings.delete 只留給頂層欄位與整包編輯器（remote／autoMode JSON、sandbox、voice、unknown key）。
• 實作設定頁新功能前，先查 JSON Schema： claude-code-settings.json
• SchemaStore 可能落後官方 docs；同步 settings 時一定要再交叉比對 code.claude.com/docs/en/settings
• 同步 Claude settings docs 變更回 repo 前，先讀 .claude/skills/update-settings-options/SKILL.md