@lkangd/cc-settings-preset 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, lkangd
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+<p align="center">
+  <a href="https://github.com/lkangd/cc-settings-preset">
+    <img
+      src="https://raw.githubusercontent.com/lkangd/cc-settings-preset/main/assets/ccsp-logo.png"
+      alt="CCSP — Claude Code Settings Preset"
+      width="420"
+    />
+  </a>
+</p>
+
+<p align="center">
+  <strong>A switchable, reusable runtime settings preset selector for Claude Code.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lkangd/cc-settings-preset"><img src="https://img.shields.io/npm/v/@lkangd/cc-settings-preset?style=flat-square" alt="npm version" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lkangd/cc-settings-preset?style=flat-square" alt="license" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@lkangd/cc-settings-preset?style=flat-square" alt="node version" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset"><img src="https://img.shields.io/github/stars/lkangd/cc-settings-preset?style=flat-square" alt="stars" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset/issues"><img src="https://img.shields.io/github/issues/lkangd/cc-settings-preset?style=flat-square" alt="issues" /></a>
+</p>
+
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/lkangd/cc-settings-preset/main/assets/screen-shot.png"
+    alt="CCSP TUI: base preset selection and project launch toggles"
+    width="900"
+  />
+</p>
+
+<p align="center">
+  <em>Interactive flow: pick a global base preset (left), preview its JSON (right), then tune plugins / skills / MCP per launch before starting Claude Code.</em>
+</p>
+
+**English** | [简体中文](README.zh-hans.md)
+
+---
+
+## Quick Start
+
+**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed (`claude` available on your `PATH`).
+
+### Install
+
+**macOS (Homebrew, recommended)** — via the personal tap [lkangd/homebrew-tap](https://github.com/lkangd/homebrew-tap); Node.js 20 is installed as a dependency:
+
+```bash
+brew tap lkangd/tap
+brew install cc-settings-preset
+```
+
+**npm / pnpm** — requires Node.js ≥ 20.19.2 on your machine:
+
+```bash
+npm install -g @lkangd/cc-settings-preset
+# or
+pnpm add -g @lkangd/cc-settings-preset
+```
+
+After install, use either `ccsp` or `cc-settings-preset`.
+
+### Usage
+
+```bash
+# Start from a project directory (recommended entry)
+ccsp
+
+# Forward Claude Code args (ccsp owns --settings)
+ccsp claude --help
+ccsp claude -p "review this PR"
+```
+
+**First-time workflow:**
+
+```bash
+# 1. Import a global base preset from existing settings
+ccsp create
+
+# 2. In a project: pick a preset, tune plugins / skills / MCP for this launch, then start Claude
+ccsp
+
+# 3. Manage global or project launch presets
+ccsp manage
+ccsp manage --project
+```
+
+---
+
+## Use Cases
+
+CCSP (**C**laude **C**ode **S**ettings **P**reset) helps when you need to switch Claude Code configuration across contexts without hand-editing JSON every time.
+
+### 1. Multiple models / API backends
+
+Different projects use different API keys, `ANTHROPIC_BASE_URL`, or default models (Opus, Sonnet, custom gateway). Editing `~/.claude/settings.json` by hand is error-prone.
+
+**Approach:** Run `ccsp create` to save a **global base preset** per environment (including `env` and model fields). In each project, run `ccsp` and pick the preset—no repeated edits to your main settings file.
+
+### 2. Per-project plugins, skills, and MCP
+
+Under one global baseline, project A disables an official plugin, project B blocks Chrome DevTools MCP, project C turns off certain skills.
+
+**Approach:** Use a **launch preset** in the project to override only `enabledPlugins`, `skillOverrides`, and `deniedMcpServers`. CCSP merges that with the base preset into a temp settings file, then starts `claude`.
+
+### 3. Team baseline, personal launch tweaks
+
+The team can commit `.claude/settings.json` as the project baseline. Individuals keep global presets locally and store launch combinations under `.claude/.ccsp/` (gitignored by default to avoid leaking secrets).
+
+### 4. Replace long `claude` one-liners
+
+Instead of:
+
+```bash
+claude --settings ~/.claude/my-api-1.json -- ...
+```
+
+use `ccsp` or `ccsp claude -- ...` to pick presets and toggles in the TUI; CCSP generates the settings path and runs `claude --settings <generated>`.
+
+### 5. Config management and preview
+
+- `ccsp manage` — browse, rename, delete global base presets, preview JSON, launch from the UI.
+- `ccsp manage --project` — manage launch presets for the current repo (create / save / rename / delete / launch).
+
+---
+
+## How It Works
+
+### Two-layer preset model
+
+| Layer | Location | Role |
+|-------|----------|------|
+| **Base preset** | `~/.ccsp/settings/*.json` | Full settings snapshot (import from user / project / project-local or any JSON) |
+| **Launch preset** | `<project>/.claude/.ccsp/launch-presets/*.json` | **Delta** only: plugin toggles, skill overrides, MCP deny list |
+
+On launch, CCSP does **not** overwrite `~/.claude/settings.json` or the project’s `.claude/settings.json`. It writes a **temporary merged file** (`.claude/.ccsp/tmp/<timestamp>-settings.json`) and runs:
+
+```text
+claude --settings <temp-file> [your other args]
+```
+
+### ASCII flow
+
+```text
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    User runs ccsp / ccsp claude                         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ① Discover settings sources (collect if present; no runtime merge yet) │
+│    · .claude/settings.local.json  (project-local)                       │
+│    · .claude/settings.json        (project)                             │
+│    · ~/.claude/settings.json      (user)                                │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                    ┌─────────────────┴─────────────────┐
+                    ▼                                   ▼
+      Base presets exist in ~/.ccsp?              No base presets yet
+                    │                                   │
+                    ▼                                   ▼
+    ┌───────────────────────────┐          Use empty base {} or
+    │ TUI: pick global base      │          run ccsp create first
+    │ (remember last per cwd)    │
+    └───────────────────────────┘
+                    │
+                    ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ② Resolve effective baseline                                             │
+│    · Plugins: user < project < project-local < selected base preset      │
+│    · Skills: scan ~/.claude/skills, project skills/commands, plugin cache│
+│    · MCP: merge .mcp.json, ~/.claude.json, plugin manifests, etc.        │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ③ TUI: project launch layer (Launch Preset)                             │
+│    · Left: launch presets  Right: plugin | skill | MCP toggles           │
+│    · Save as preset / overwrite / launch without saving                  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ④ finalizeSettings(base, launch)                                        │
+│    · Copy full base preset                                               │
+│    · Strip enabledPlugins / skillOverrides / deniedMcpServers from base  │
+│    · Apply launch-layer values for those three fields (if any)           │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ⑤ Write .claude/.ccsp/tmp/*.json (gitignored; keep at most 20 files)   │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ⑥ spawn: claude --settings <tmp> [sanitized args]                      │
+│    · Strip user --settings / --settings=... (managed by ccsp)           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Pain points with Claude Code settings alone
+
+| Pain point | Why it hurts |
+|------------|--------------|
+| **Multiple files and scopes** | user / project / project-local settings make it hard to see what actually applies. |
+| **High switching cost** | Changing API, model, or plugin mix means editing JSON or memorizing `--settings` paths. |
+| **Easy to break main config** | Editing `~/.claude/settings.json` can mix secrets and global defaults. |
+| **Scattered toggles** | `enabledPlugins`, `skillOverrides`, `deniedMcpServers` sit beside `env` with no “this launch only” view. |
+| **Commit risk** | Project settings with keys in `env` can be committed by mistake. |
+
+### What CCSP adds
+
+- **Non-destructive launch** — inject config via temp files; does not force-overwrite your main settings.
+- **Two-layer split** — global “base environment” vs project “launch delta” for multi-repo work.
+- **Visual toggles** — terminal TUI to browse JSON and flip plugins / skills / MCP.
+- **Remembers last choice** — per project directory for base and launch presets.
+- **Safer defaults** — `.claude/.ccsp/` gets a `.gitignore` that ignores everything on init.
+
+### Limitations (read before assuming)
+
+| Cannot / caveat | Explanation |
+|-----------------|-------------|
+| **Not a Claude Code replacement** | Wraps the `claude` subprocess only; exits if CLI is missing. |
+| **Does not write back main settings** | Merged output is not saved to `~/.claude/settings.json`; sync manually or update base presets via `ccsp create`. |
+| **Owns `--settings`** | Your `--settings` is ignored with a warning; path is generated by CCSP. |
+| **Limited launch fields** | Launch presets only override `enabledPlugins`, `skillOverrides`, `deniedMcpServers`; other fields (e.g. `env`) come from the base preset. |
+| **No “add MCP server” in UI** | Can **deny** discovered MCPs via `deniedMcpServers`; cannot create new server entries. |
+| **No headless / CI mode** | Main flow is Ink TUI; `create` / `manage` are interactive unless you edit JSON yourself. |
+| **Derived presets** | Schema supports `derived` type; CLI does not expose full create/manage flow yet. |
+| **Project store is local by default** | `launch-presets` and `tmp` under `.claude/.ccsp/` are not in Git unless you opt in. |
+| **Temp file cap** | Oldest files in `tmp` are pruned when count exceeds 20. |
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `ccsp` | Default: pick base preset → configure launch layer → start `claude` |
+| `ccsp claude [args...]` | Same, forwarding `args` to `claude` (without `--settings`) |
+| `ccsp create` | Interactively create a global base preset |
+| `ccsp manage` | Manage global base presets (preview / rename / delete / create / launch) |
+| `ccsp manage --project` | Manage launch presets for the current project |
+
+### TUI shortcuts
+
+**Base preset selection:** `j`/`k` or arrows to move, `Enter` to confirm, `q` to quit.
+
+**Global manage (`ccsp manage`):** `l` launch, `r` rename, `d` delete, `c` create, `o` reveal in Finder, `q` quit.
+
+**Project launch layer:** switch between presets and plugin / skill / MCP columns; save as launch preset. `Ctrl+L` refreshes the UI.
+
+---
+
+## Directory Layout
+
+```text
+~/.ccsp/
+├── index.json                 # global base preset index
+├── settings/
+│   └── <name>-settings.json   # base preset body
+└── last-settings.json         # last base preset name per project cwd
+
+<project>/.claude/.ccsp/       # entire dir gitignored by default
+├── launch-presets/
+│   ├── index.json
+│   └── <name>-launch.json     # launch-layer overrides only
+├── tmp/
+│   └── <timestamp>-settings.json
+└── last-used.json             # last launch preset used
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/lkangd/cc-settings-preset.git
+cd cc-settings-preset
+pnpm install
+pnpm run dev          # run tsx src/cli.ts directly
+pnpm run check        # typecheck + build + test
+```
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Before you contribute:
+
+1. **Search existing issues** to avoid duplicates; open an issue for new features with motivation and proposed usage.
+2. **Verify locally:** `pnpm run check` must pass; CLI changes should include or update tests under `tests/`.
+3. **Style:** Match the codebase (ESM, strict TypeScript, Ink + `flows/` state machines); avoid unrelated refactors.
+4. **Scope:** CCSP focuses on settings presets and launch orchestration—avoid heavy unrelated dependencies.
+5. **Docs:** Update both `README.md` and `README.zh-hans.md` for user-visible behavior changes.
+6. **Commits:** Concise English or Chinese is fine; explain *why*, not only *what*.
+
+**Bug reports should include:** OS, Node version, how you invoked `ccsp`, relevant `~/.ccsp` or `.claude/.ccsp` layout (redact secrets), and full terminal output.
+
+---
+
+## License
+
+[ISC](./LICENSE) © lkangd

package/README.zh-hans.md

@@ -0,0 +1,304 @@
+<p align="center">
+  <a href="https://github.com/lkangd/cc-settings-preset">
+    <img
+      src="https://raw.githubusercontent.com/lkangd/cc-settings-preset/main/assets/ccsp-logo.png"
+      alt="CCSP — Claude Code Settings Preset"
+      width="420"
+    />
+  </a>
+</p>
+
+<p align="center">
+  <strong>为 Claude Code 提供可切换、可复用的运行时 Settings 预设选择器。</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lkangd/cc-settings-preset"><img src="https://img.shields.io/npm/v/@lkangd/cc-settings-preset?style=flat-square" alt="npm version" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lkangd/cc-settings-preset?style=flat-square" alt="license" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@lkangd/cc-settings-preset?style=flat-square" alt="node version" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset"><img src="https://img.shields.io/github/stars/lkangd/cc-settings-preset?style=flat-square" alt="stars" /></a>
+  <a href="https://github.com/lkangd/cc-settings-preset/issues"><img src="https://img.shields.io/github/issues/lkangd/cc-settings-preset?style=flat-square" alt="issues" /></a>
+</p>
+
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/lkangd/cc-settings-preset/main/assets/screen-shot.png"
+    alt="CCSP 交互界面：基础预设选择与项目启动开关"
+    width="900"
+  />
+</p>
+
+<p align="center">
+  <em>典型流程：先选全局基础预设（左）并预览 JSON（右），再在项目启动层切换插件 / Skill / MCP，最后启动 Claude Code。</em>
+</p>
+
+[English](README.md) | **简体中文**
+
+---
+
+## Quick Start
+
+**前置条件：** 已安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI（`claude` 在 `PATH` 中可用）。
+
+### 安装
+
+**macOS（Homebrew，推荐）** — 通过个人 tap [lkangd/homebrew-tap](https://github.com/lkangd/homebrew-tap) 安装，会自动拉取 Node.js 20 依赖：
+
+```bash
+brew tap lkangd/tap
+brew install cc-settings-preset
+```
+
+**npm / pnpm** — 需本机已有 Node.js ≥ 20.19.2：
+
+```bash
+npm install -g @lkangd/cc-settings-preset
+# 或
+pnpm add -g @lkangd/cc-settings-preset
+```
+
+安装后可用 `ccsp` 或 `cc-settings-preset` 命令。
+
+### 使用
+
+```bash
+# 在项目目录中启动（推荐入口）
+ccsp
+
+# 透传 Claude Code 参数（ccsp 会接管 --settings）
+ccsp claude --help
+ccsp claude -p "review this PR"
+```
+
+**首次使用建议：**
+
+```bash
+# 1. 从现有 settings 导入一份「全局基础预设」
+ccsp create
+
+# 2. 进入项目，选择预设并配置本次启动的插件 / Skill / MCP，然后启动 Claude
+ccsp
+
+# 3. 管理全局预设或项目启动预设
+ccsp manage
+ccsp manage --project
+```
+
+---
+
+## 使用场景
+
+CCSP（**C**laude **C**ode **S**ettings **P**reset）面向「同一份 Claude Code 配置，需要在不同上下文里快速切换」的日常开发。典型场景如下。
+
+### 1. 多模型 / 多后端环境切换
+
+你在不同项目里使用不同的 API Key、`ANTHROPIC_BASE_URL`、默认模型（如 Opus / Sonnet / 自建网关）。手动改 `~/.claude/settings.json` 容易串环境。
+
+**做法：** 用 `ccsp create` 为每个环境保存一份**全局基础预设**（含 `env`、模型相关字段等），进入项目后 `ccsp` 选预设即可，无需反复编辑主 settings 文件。
+
+### 2. 按项目控制插件、Skill、MCP
+
+同一套全局配置下，项目 A 需要关闭某官方插件、项目 B 要禁用 Chrome DevTools MCP、项目 C 要关掉部分 Skill。
+
+**做法：** 在项目内用**启动预设**（Launch Preset）只覆盖 `enabledPlugins`、`skillOverrides`、`deniedMcpServers`，与全局基础预设合并后生成临时 settings，再启动 `claude`。
+
+### 3. 团队内共享「基础配置」，个人保留「启动差异」
+
+团队可约定把 `.claude/settings.json` 提交进仓库作为项目基线；个人仍可在本机维护全局预设，并在 `.claude/.ccsp/` 下保存自己的启动组合（默认被 gitignore，避免误提交密钥）。
+
+### 4. 替代「记住一长串 claude 命令」
+
+以前可能需要：
+
+```bash
+claude --settings ~/.claude/my-api-1.json -- ...
+```
+
+**做法：** `ccsp` / `ccsp claude -- ...` 在 TUI 里选预设、勾选开关，由工具生成临时 settings 路径并调用 `claude --settings <generated>`。
+
+### 5. 配置管理与预览
+
+- `ccsp manage`：浏览、重命名、删除全局基础预设，预览 JSON 树，并可直接从管理界面启动。
+- `ccsp manage --project`：管理当前仓库下的启动预设（创建 / 保存 / 重命名 / 删除 / 启动）。
+
+---
+
+## 工作原理
+
+### 两层预设模型
+
+| 层级 | 存储位置 | 作用 |
+|------|----------|------|
+| **全局基础预设**（Base Preset） | `~/.ccsp/settings/*.json` | 一份完整的 settings 快照（可从 user / project / project-local 或任意 JSON 导入） |
+| **项目启动预设**（Launch Preset） | `<项目>/.claude/.ccsp/launch-presets/*.json` | 仅记录相对基础的**差异**：插件开关、Skill 覆盖、MCP 拒绝列表 |
+
+启动时 CCSP **不会直接改写** `~/.claude/settings.json` 或项目里的 `.claude/settings.json`，而是写入 **临时合并文件**（`.claude/.ccsp/tmp/<timestamp>-settings.json`），再执行：
+
+```text
+claude --settings <临时文件> [你传入的其它参数]
+```
+
+### ASCII 逻辑图
+
+```text
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           用户执行 ccsp / ccsp claude                    │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ① 发现现有 Settings 来源（按存在性收集，非运行时合并）                         │
+│    · .claude/settings.local.json  (project-local)                       │
+│    · .claude/settings.json        (project)                             │
+│    · ~/.claude/settings.json      (user)                                │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                    ┌─────────────────┴─────────────────┐
+                    ▼                                   ▼
+         ~/.ccsp 中已有基础预设？                  尚无基础预设
+                    │                                   │
+                    ▼                                   ▼
+    ┌───────────────────────────┐          使用空基础 {} 或
+    │ TUI：选择全局基础预设       │          先 ccsp create 导入
+    │ （记住每个 cwd 上次选择）   │
+    └───────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ② 解析「有效基线」                                                          │
+│    · 插件：user < project < project-local < 所选基础预设                   │
+│    · Skill：扫描 ~/.claude/skills、项目 skills/commands、已启用插件缓存      │
+│    · MCP：合并 .mcp.json、~/.claude.json、插件 manifest 等来源              │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ③ TUI：项目启动层（Launch Preset）                                         │
+│    · 左：已有启动预设列表  右：插件 | Skill | MCP 三列开关                     │
+│    · 可保存为新预设 / 覆盖当前预设 / 临时启动不保存                             │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ④ finalizeSettings(base, launch)                                        │
+│    · 以基础预设为主拷贝全文                                                 │
+│    · 去掉基础里的 enabledPlugins / skillOverrides / deniedMcpServers      │
+│    · 再写入 launch 层的上述三个字段（若有）                                   │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ⑤ 写入 .claude/.ccsp/tmp/*.json（目录默认 gitignore，最多保留 20 份）        │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ⑥ spawn: claude --settings <tmp> [sanitized args]                       │
+│    · 剥离用户传入的 --settings / --settings=...（由 ccsp 统一管理）          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 针对 Claude Code Settings 的痛点
+
+| 痛点 | 说明 |
+|------|------|
+| **多文件、多层作用域** | Claude Code 同时存在 user / project / project-local settings，手工维护时难以一眼看清「最终生效」的是哪一层。 |
+| **切换成本高** | 换 API、换模型、换插件组合往往要改 JSON 或记不同 `--settings` 路径。 |
+| **易误改主配置** | 直接编辑 `~/.claude/settings.json` 容易把个人密钥、全局默认一起改掉。 |
+| **插件 / Skill / MCP 分散** | `enabledPlugins`、`skillOverrides`、`deniedMcpServers` 与 `env` 等字段混在同一文件，缺少面向「本次启动」的轻量视图。 |
+| **提交风险** | 项目 settings 若含 `env` 里的 Key，误提交到 Git 风险高。 |
+
+### CCSP 的优势
+
+- **非破坏性启动**：通过临时 settings 文件注入配置，不强制覆盖你的主 settings 文件。
+- **两层分离**：全局「基础环境」与项目「启动差异」解耦，适合多仓库并行开发。
+- **可视化开关**：在终端 TUI 中浏览 JSON、切换插件 / Skill / MCP，比手改数组更不易出错。
+- **记忆上次选择**：按项目目录记住上次使用的基础预设与启动预设。
+- **安全默认值**：`.claude/.ccsp/` 初始化时写入 `.gitignore`（忽略全部），降低临时文件与本地预设误提交概率。
+
+### 局限与误解澄清（请务必阅读）
+
+| 不能做到 / 需注意 | 说明 |
+|-------------------|------|
+| **不是 Claude Code 替代品** | 仅包装 `claude` 子进程；未安装 CLI 时会报错退出。 |
+| **不自动回写主 settings** | 不会把合并结果写回 `~/.claude/settings.json`；若你希望永久生效，仍需自行同步或使用 `ccsp create` 更新基础预设。 |
+| **接管 `--settings`** | 传入的 `--settings` 会被忽略并提示警告；路径由 CCSP 生成。 |
+| **启动层字段有限** | Launch Preset 只覆盖 `enabledPlugins`、`skillOverrides`、`deniedMcpServers`；其它字段（如 `env`）来自基础预设。 |
+| **不能通过 UI 新增 MCP Server** | 仅支持基于已发现 MCP 的**禁用**（`deniedMcpServers`），不能创建新 server 配置。 |
+| **无无头 / CI 模式** | 主流程为 Ink 交互界面；`create` / `manage` 亦为 TUI，不适合纯脚本无人值守选型（除非自行读写 JSON）。 |
+| **Derived 预设** | 数据模型支持 `derived` 类型，但当前 CLI 未暴露创建/管理衍生预设的完整流程。 |
+| **项目存储默认本地** | `launch-presets` 与 `tmp` 在 `.claude/.ccsp/` 下，默认不进 Git；团队共享需另行约定导出方式。 |
+| **临时文件有上限** | `tmp` 目录超过 20 个 settings 文件时会删除最旧的。 |
+
+---
+
+## 命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `ccsp` | 默认流程：选基础预设 → 配置启动层 → 启动 `claude` |
+| `ccsp claude [args...]` | 同上，并将 `args` 传给 `claude`（不含 `--settings`） |
+| `ccsp create` | 交互式创建全局基础预设 |
+| `ccsp manage` | 管理全局基础预设（预览 / 重命名 / 删除 / 新建 / 启动） |
+| `ccsp manage --project` | 管理当前项目的启动预设 |
+
+### 常用快捷键（TUI）
+
+**选择基础预设：** `j`/`k` 或方向键移动，`Enter` 确认，`q` 退出。
+
+**管理全局预设（`ccsp manage`）：** `l` 启动，`r` 重命名，`d` 删除，`c` 新建，`o` 在 Finder 中打开文件，`q` 退出。
+
+**项目启动层：** 在预设与插件 / Skill / MCP 列间切换并开关；支持保存为启动预设。终端内 `Ctrl+L` 可刷新界面。
+
+---
+
+## 目录结构
+
+```text
+~/.ccsp/
+├── index.json                 # 全局基础预设索引
+├── settings/
+│   └── <name>-settings.json   # 基础预设内容
+└── last-settings.json         # 各项目 cwd 上次使用的基础预设名
+
+<项目>/.claude/.ccsp/          # 默认整目录 gitignore
+├── launch-presets/
+│   ├── index.json
+│   └── <name>-launch.json     # 仅含启动层覆盖字段
+├── tmp/
+│   └── <timestamp>-settings.json
+└── last-used.json             # 上次使用的启动预设
+```
+
+---
+
+## 从源码开发
+
+```bash
+git clone https://github.com/lkangd/cc-settings-preset.git
+cd cc-settings-preset
+pnpm install
+pnpm run dev          # 直接跑 tsx src/cli.ts
+pnpm run check        # typecheck + build + test
+```
+
+---
+
+## 贡献指南
+
+欢迎 Issue 与 Pull Request。参与前建议：
+
+1. **先搜已有 Issue**，避免重复讨论；新功能请先开 Issue 简述动机与用法。
+2. **本地验证：** `pnpm run check` 须通过；若改动 CLI 行为，请补充或更新 `tests/` 下对应用例。
+3. **风格：** 与现有代码保持一致（ESM、`strict` TypeScript、Ink 组件 + `flows/` 状态机）；避免无关重构。
+4. **范围控制：** CCSP 聚焦 settings 预设与启动编排，不引入与 Claude Code 无关的重依赖。
+5. **文档：** 用户可见行为变更请同步更新 `README.md` 与 `README.zh-hans.md`。
+6. **提交信息：** 使用简洁英文或中文均可，说明「为什么」而不仅是「改了什么」。
+
+**报告 Bug 请附带：** 操作系统、Node 版本、`ccsp` 调用方式、相关 `~/.ccsp` 或 `.claude/.ccsp` 结构（请打码密钥）、终端报错全文。
+
+---
+
+## License
+
+[ISC](./LICENSE) © lkangd

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import React from 'react';
+import { Command } from 'commander';
+import { type Instance } from 'ink';
+export declare function createProgram(): Command;
+export declare function buildBannerLines(columns: number): string[];
+export declare function printBanner(): void;
+export declare function clearTerminalScreen(stdout?: Pick<NodeJS.WriteStream, 'write'>): void;
+type ShortcutKey = {
+    ctrl?: boolean;
+};
+type RefreshableInkApp = Pick<Instance, 'clear' | 'rerender' | 'waitUntilExit'>;
+type RefreshState = {
+    resizeVersion: number;
+};
+export declare function createGlobalShortcutHandler(app: RefreshableInkApp, createNode: () => React.ReactElement, stdout?: Pick<NodeJS.WriteStream, 'write'>, state?: RefreshState, onShortcut?: (input: string, key: ShortcutKey) => void): (input: string, key: ShortcutKey) => void;
+export declare function waitForInkAppExit(app: RefreshableInkApp, createNode: () => React.ReactElement, stdout?: Pick<NodeJS.WriteStream, 'on' | 'off' | 'write'>, state?: RefreshState, onShortcut?: (input: string, key: ShortcutKey) => void): Promise<void>;
+export declare function main(argv?: string[]): Promise<void>;
+export {};