为 Claude Code 提供可切换、可复用的运行时 Settings 预设选择器。
典型流程：先选全局基础预设（左）并以 YAML 或 JSON 预览其配置（右），再在项目启动层切换插件 / Skill / MCP，最后启动 Claude Code。
English | 简体中文
前置条件： 已安装 Claude Code CLI（claude 在 PATH 中可用）。
macOS（Homebrew，推荐） — 通过个人 tap lkangd/homebrew-tap 安装，会自动拉取 Node.js 20 依赖：
brew tap lkangd/tap
brew install cc-settings-presetnpm / pnpm — 需本机已有 Node.js ≥ 20.19.2：
npm install -g @lkangd/cc-settings-preset
# 或
pnpm add -g @lkangd/cc-settings-preset安装后可用 ccsp 或 cc-settings-preset 命令。
后续需要更新时，运行 ccsp update。它会检查最新发布版本，打印当前版本之后的 changelog，识别当前是 Homebrew 还是 npm 安装，并执行对应的升级命令。
# 在项目目录中启动（推荐入口）
ccsp
# 透传 Claude Code 参数（ccsp 会接管 --settings）
ccsp claude --help
ccsp claude -p "review this PR"
# 直接运行：跳过 TUI，按名称指定预设，其余参数透传给 claude
ccsp -g work -p web
ccsp -g glm-5.1 -p Chore claude -p "汇总未关闭的 issue"
ccsp --global-preset work --project-preset web --dry-run # 预览合并结果，不启动
# 检查更新，并用识别到的安装器升级 ccsp
ccsp update
# 恢复本项目最近退出的会话，并复用其原始预设 / 启动配置
ccsp --continue
# 按 session id 精确恢复某个会话，复用启动时所用的预设 / 启动配置
ccsp --resume 99580820-9437-475c-883c-399bcfba3c47首次使用建议：
# 1. 从现有 settings 导入一份「全局基础预设」
ccsp create
# 2. 进入项目，选择预设并配置本次启动的插件 / Skill / MCP，然后启动 Claude
ccsp
# 3. 管理全局预设或项目启动预设
ccsp manage
ccsp manage --projectCCSP（Claude Code Settings Preset）面向「同一份 Claude Code 配置，需要在不同上下文里快速切换」的日常开发。典型场景如下。
你在不同项目里使用不同的 API Key、ANTHROPIC_BASE_URL、默认模型（如 Opus / Sonnet / 自建网关）。手动改 ~/.claude/settings.json 容易串环境。
做法： 用 ccsp create 为每个环境保存一份全局基础预设（含 env、模型相关字段等），进入项目后 ccsp 选预设即可，无需反复编辑主 settings 文件。
同一套全局配置下，项目 A 需要关闭某官方插件、项目 B 要禁用 Chrome DevTools MCP、项目 C 要关掉部分 Skill。
做法： 在项目内用启动预设（Launch Preset）只覆盖 enabledPlugins、skillOverrides、deniedMcpServers，与全局基础预设合并后生成临时 settings，再启动 claude。
团队可约定把 .claude/settings.json 提交进仓库作为项目基线；个人仍可在本机维护全局预设，并在 .claude/.ccsp/ 下保存自己的启动组合（默认被 gitignore，避免误提交密钥）。
以前可能需要：
claude --settings ~/.claude/my-api-1.json -- ...做法： ccsp / ccsp claude -- ... 在 TUI 里选预设、勾选开关，由工具生成临时 settings 路径并调用 claude --settings <generated>。
ccsp manage：浏览、重命名、删除全局基础预设，预览配置（YAML / JSON），并可直接从管理界面启动。ccsp manage --project：管理当前仓库下的启动预设（创建 / 保存 / 重命名 / 删除 / 启动）。
CCSP 现已支持非交互式直接启动：在命令行指定预设、合并 settings 后直接 spawn claude，无需打开 TUI。这与 Claude Code 的 print / agent 模式（claude -p "…"）天然契合，适合脚本、cron、GitHub Actions 等自动化场景。
# 一行搞定：全局基础预设 + 项目启动预设 + 非交互 prompt
ccsp -g my-gateway-api -p ci-minimal claude -p "运行测试套件并汇总失败原因"
# 预览即将启动的配置（全局两栏 + 启动层四栏）
ccsp -g my-gateway-api -p ci-minimal --dry-run为什么现在值得重视： 自 2026 年 6 月 15 日起，Anthropic 将 Agent SDK / claude -p 的用量从订阅套餐的交互额度中分离。终端里的交互式 Claude Code 仍占用套餐额度；claude -p 改走独立的 Agent SDK 月度额度（Pro / Max / Team / Enterprise 可领取）。这意味着非交互自动化有了更便宜的专用通道——前提是仍能按任务切换 API 后端，并按需开关 plugins / skills / MCP。
CCSP 的价值： 用全局预设指向第三方 API（ANTHROPIC_BASE_URL、env 里的 Key、默认模型等），用启动预设只打开该任务需要的 plugins / skills / MCP。直接运行会合并两层配置，并把剩余 argv 交给 claude：
| 参数 | 简写 | 作用 |
|---|---|---|
--global-preset |
-g |
全局基础预设名（~/.ccsp/settings/） |
--project-preset |
-p |
项目启动预设名，或 Detected 表示自动发现的基线 |
--dry-run |
— | 打印解析后的全局 + 启动预览，不启动 claude |
说明：
- 至少提供
-g或-p之一 才会进入直接运行；否则仍为交互式 TUI。 - 透传参数时，CCSP 的 flag 写在
claude之前；claude之后的-p是 Claude 的 prompt 参数，不是 CCSP 的项目预设。 - 仅
-p时，全局基础回退到上次使用的预设或项目 settings 来源（与 project-manage 启动一致）。 - 仅
-g时，启动层使用 Detected 基线（无需已保存的启动预设）。
| 层级 | 存储位置 | 作用 |
|---|---|---|
| 全局基础预设（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），再执行：
claude --settings <临时文件> [你传入的其它参数]
┌─────────────────────────────────────────────────────────────────────────┐
│ 用户执行 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，约保留 50 份） │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ⑥ spawn: claude --settings <tmp> [sanitized args] │
│ · 剥离用户传入的 --settings / --settings=...（由 ccsp 统一管理） │
└─────────────────────────────────────────────────────────────────────────┘
| 痛点 | 说明 |
|---|---|
| 多文件、多层作用域 | Claude Code 同时存在 user / project / project-local settings，手工维护时难以一眼看清「最终生效」的是哪一层。 |
| 切换成本高 | 换 API、换模型、换插件组合往往要改 JSON 或记不同 --settings 路径。 |
| 易误改主配置 | 直接编辑 ~/.claude/settings.json 容易把个人密钥、全局默认一起改掉。 |
| 插件 / Skill / MCP 分散 | enabledPlugins、skillOverrides、deniedMcpServers 与 env 等字段混在同一文件，缺少面向「本次启动」的轻量视图。 |
| 提交风险 | 项目 settings 若含 env 里的 Key，误提交到 Git 风险高。 |
- 非破坏性启动：通过临时 settings 文件注入配置，不强制覆盖你的主 settings 文件。
- 两层分离：全局「基础环境」与项目「启动差异」解耦，适合多仓库并行开发。
- 可视化开关：在终端 TUI 中浏览 JSON、切换插件 / Skill / MCP，比手改数组更不易出错。
- 快捷设置：在基础预设选择页即可循环切换所选预设的
permissions.defaultMode、effortLevel与outputStyle，仅写回你改过的字段（写入预设文件；Claude Official 则写回~/.claude/settings.json）。 - 直接运行：
-g/-p/--dry-run供脚本与 CI 使用；配合claude -p做无头 agent 任务。 - 记忆上次选择：按项目目录记住上次使用的基础预设与启动预设。
- 可恢复会话：每次启动都会把会话与所用预设 / 启动配置绑定，
ccsp --continue与ccsp --resume <id>可一键恢复原配置并续上对应 Claude 会话。 - 安全默认值：
.claude/.ccsp/初始化时写入.gitignore（忽略全部），降低临时文件与本地预设误提交概率。
基础预设选择页中间新增一栏 Quick Settings。用 h/l 或 ←/→ 把焦点切到该栏，按 space 循环切换所选预设的三项 Claude Code 配置：
- mode ——
permissions.defaultMode：manual→acceptEdits→plan→auto→dontAsk→bypassPermissions。 - effort ——
effortLevel：low→medium→high→xhigh→max→ultracode。 - style ——
outputStyle：内置的Default→Proactive→Concise→Explanatory→Learning，其后接~/.claude/output-styles/中扫描到的自定义样式。
未改动的字段会展示按优先级（managed → local → project → user）解析出的有效默认值。只有你实际切换过的字段才会被写入，且所有 effort 等级都以同一种方式持久化：作为 effortLevel 写入预设。
max 与 ultracode 多一步处理。Claude Code 的 settings schema 中 effortLevel 只接受 low / medium / high / xhigh，因此它永远不会从 settings 文件应用这两个值，只写 effortLevel: "max" 的预设会静默回落到 ~/.claude/settings.json 里继承来的 effortLevel。为此 CCSP 会在命令行上再声明一次：当按该栏展示的同一条优先级链（preset → managed → local → project → user）解析出的有效等级是 max 或 ultracode 时，启动就追加 --effort max / --effort ultracode，其优先级高于所有 settings 作用域；直接运行与 --resume 同样适用。若你在自己的参数里显式传了 --effort <level> 或 --effort=<level>，则以你的为准。
自定义输出样式读取自 ~/.claude/output-styles/*.md，优先取文件 frontmatter 中的 name，缺失时回落到文件名 —— 与 Claude Code 的规则一致，因此写入的值一定是 Claude Code 能解析的。项目级与插件样式有意不纳入：基础预设页在选定项目之前运行，项目样式会产生一个换个目录就失效的预设值。由该栏之外设定的样式（项目、managed 或插件）仍会原样展示，按 space 则从列表首项开始循环。与另外两行不同，Default 是显式写入的，而不是删除该键。
确认时写回对应预设文件；若编辑临时的 Claude Official 条目，则直接写回 ~/.claude/settings.json —— 该路径正是其他所有预设在展示时回退的 user 作用域，因此在那里设的值，会成为所有未自行设置该字段的预设所显示的有效默认值。其他预设都无法写入该文件。
Claude 退出后，CCSP 会主动发现 Claude 真实分配的 session id（启动前对 ~/.claude/projects/<编码后的 cwd>/ 做快照，退出时做 diff——--session-id 在交互模式下并不可靠，所以我们不直接 pin），并把它和本次启动配置绑定，存入 .claude/.ccsp/sessions.json（最多 50 条，按 lastUsedAt 淘汰）：
ccsp --resume <uuid>：用绑定里的输入重新 finalize 启动配置，并以claude --resume <uuid>一步启动。ccsp --continue：选取本项目里最近退出的 ccsp 会话，按其 id 确定性地恢复。具体例子：先启 A 再启 B，先退出 A，再ccsp --continue，恢复的是 A（带 A 当时的预设 / 启动配置），不是 B。ccsp claude --resume <uuid>与ccsp claude --continue：保留 Claude 参数透传写法，但会重新选择全局 / 项目预设。- 若绑定对应的 Claude 会话已不存在（如旧版本残留），CCSP 会丢弃该绑定并回退到交互式选择。
会话参数的位置决定路由：写在 claude 前表示复用 CCSP 保存的绑定，写在 claude 后表示选择预设；顶层形式末尾的 claude 只是 CCSP 路由标记，不会传给 Claude。
| 不能做到 / 需注意 | 说明 |
|---|---|
| 不是 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 配置。 |
| create / manage 仍以 TUI 为主 | 创建与管理预设需交互界面；无头启动请用直接运行或自行编辑 JSON。 |
| Derived 预设 | 数据模型支持 derived 类型，但当前 CLI 未暴露创建/管理衍生预设的完整流程。 |
| 项目存储默认本地 | launch-presets、tmp 与 sessions.json 都在 .claude/.ccsp/ 下，默认不进 Git；团队共享需另行约定导出方式。 |
| 临时文件有上限 | tmp 中的 settings 文件超过 50 份后按写入时间淘汰最旧的，但仍在运行的会话所持有的不会被回收——有活跃会话时份数可能暂时超过 50；statusline 脚本每次退出都会清理。 |
| Resume 只覆盖 ccsp 启动的会话 | ccsp --continue / --resume 只能看到通过新版 ccsp 启动并记录过绑定的会话；直接用 claude 启动的会话不在范围内。 |
| 命令 | 说明 |
|---|---|
ccsp |
默认流程：选基础预设 → 配置启动层 → 启动 claude |
ccsp -g <name> |
直接运行：仅指定全局基础预设（启动层 = Detected） |
ccsp -p <name> |
直接运行：仅指定项目启动预设（全局基础 = 上次使用或项目 settings） |
ccsp -g <global> -p <launch> |
直接运行：两层都指定，然后启动 claude |
ccsp … --dry-run |
配合 -g / -p：预览解析结果，不 spawn |
ccsp … claude [args…] |
直接或交互均可；CCSP 参数写在 claude 前，Claude 参数写在后 |
ccsp claude [args...] |
同上，并将 args 传给 claude（不含 --settings） |
ccsp --continue |
恢复本项目最近退出的 ccsp 会话，复用原始预设 / 启动配置 |
ccsp --resume <uuid> |
按 session id 精确恢复某个会话，复用启动时所用的预设 / 启动配置（未知绑定时回退到交互式选择） |
ccsp claude --continue / ccsp claude --resume <uuid> |
选择全局 / 项目预设，再透传 Claude 会话参数 |
ccsp --continue claude / ccsp --resume <uuid> claude |
跳过预设选择，复用对应的已保存会话绑定 |
ccsp create |
交互式创建全局基础预设 |
ccsp manage |
管理全局基础预设（预览 / 重命名 / 删除 / 新建 / 启动） |
ccsp manage --project |
管理当前项目的启动预设 |
ccsp config |
配置 ccsp 偏好（仅 env 预览、statusline） |
选择基础预设： h/l 或 ←/→ 在「Settings」与「Quick Settings」两栏间切换，j/k 或 ↑/↓ 移动，space 循环切换当前聚焦的快捷设置，t 切换排序，f 在「仅 env」与「完整配置」预览间切换，Enter 确认，q 退出。
管理全局预设（ccsp manage）： l 启动，r 重命名，d 删除，c 新建，o 在 Finder 中打开文件，q 退出。
项目启动层： 在预设与插件 / Skill / MCP 列间切换并开关；支持保存为启动预设。s 将选中预设保存为全局模板，i 打开导入面板（全局模板 + 最近项目的预设，面板内 r/d 直接管理模板）。终端内 Ctrl+L 可刷新界面。
配置（ccsp config）： j/k 或方向键移动，space/Enter 切换当前选项，q 退出。
ccsp config 打开左右两栏视图（左侧为选项，右侧为当前聚焦选项的说明），用于管理存放在 ~/.ccsp/config.json 的全局（按用户）偏好。两项默认均为 开启：
| 选项 | 默认 | 作用 |
|---|---|---|
| Global preset env-only | 开启 | 基础预设选择页默认只预览所选预设的 env 字段。在该页面按 f 可在「仅 env」与「完整配置」视图间切换；关闭后默认展示完整配置。 |
| Show statusline | 开启 | 在 Claude Code 底部注入 ccsp statusline，显示当前预设与开关概览（CCSP: <base>/<launch> | plugins(…) | skills(…) | MCPs(…)）。关闭后不再注入，也不会生成任何 statusline 脚本。 |
| Settings preview format | yaml |
基础预设选择页（ccsp）与管理页（ccsp manage）右侧预览所选预设配置的渲染格式 —— yaml 或 json，两者都带语法高亮。 |
~/.ccsp/
├── index.json # 全局基础预设索引
├── settings/
│ └── <name>-settings.json # 基础预设内容
├── launch-presets/ # 全局启动预设模板（由 s 提升产生）
│ ├── index.json
│ └── <name>-launch.json
├── config.json # 用户偏好（仅 env 预览、statusline）
└── last-settings.json # 各项目 cwd 上次使用的基础预设名；同时作为导入候选池
<项目>/.claude/.ccsp/ # 默认整目录 gitignore
├── launch-presets/
│ ├── index.json
│ └── <name>-launch.json # 仅含启动层覆盖字段
├── tmp/
│ └── <stem>-settings.json # 本次启动的最终配置（约保留 50 份，淘汰最旧的）
├── sessions.json # sessionId → 启动配置 的绑定，供 --continue / --resume
├── worktree-seed.json # 仅在 worktree 拒绝继承时写入
└── last-used.json # 上次使用的启动预设
模板是复制而非引用：从模板导入的预设从落地那一刻起就是独立文件，副本会记录来源（列表中显示为 ← <来源>）。
预设可能引用本项目未安装的插件 / Skill / MCP，这些条目显示为 [!] not installed、不可切换，并在保存时原样保留——
装上之后该预设即自动生效。
在没有自己预设的 git linked worktree 中，ccsp 会询问一次是否继承主仓库的预设（含上次使用的那一个）； 拒绝后该 worktree 不再重复询问。
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。参与前建议：
- 先搜已有 Issue，避免重复讨论；新功能请先开 Issue 简述动机与用法。
- 本地验证：
pnpm run check须通过；若改动 CLI 行为，请补充或更新tests/下对应用例。 - 风格： 与现有代码保持一致（ESM、
strictTypeScript、Ink 组件 +flows/状态机）；避免无关重构。 - 范围控制： CCSP 聚焦 settings 预设与启动编排，不引入与 Claude Code 无关的重依赖。
- 文档： 用户可见行为变更请同步更新
README.md与README.zh-hans.md。 - 提交信息： 使用简洁英文或中文均可，说明「为什么」而不仅是「改了什么」。
报告 Bug 请附带： 操作系统、Node 版本、ccsp 调用方式、相关 ~/.ccsp 或 .claude/.ccsp 结构（请打码密钥）、终端报错全文。
ISC © lkangd