dotclaude-portable

便携式同步 ~/.claude/ 中"机器无关"的配置：纯文本规则、commit 模板、commands、skills，以及 3 个不含 secret 的 JSON 配置（含 .mcp.json）。换机器后 clone + 一行命令 即可恢复。

5 分钟上手

# 1. 拉仓库
git clone <your-remote>/dotclaude-portable.git
cd dotclaude-portable

# 2. 先 dry-run
./install.sh --dry-run

# 3. 真安装
./install.sh
./install.sh --force      # 强制覆盖
./install.sh --copy       # 拷贝模式（Windows 兜底）

# 4. 验证
./install.sh --check
./install.sh doctor       # secret 扫描

# install 完成后若提示 "recommend: ./install.sh doctor"，通常是因为
# ~/.claude.json 还未生成（首次安装无 Claude Code 引导）。先启动一次 Claude Code，
# 再重跑 install + doctor 确认 fallback 链就位。

# 5. 跨机器补全
./install.sh install-statusline   # 把 ccstatusline-zh 注入本机 settings.json
./install.sh install-memory-mcp   # 修复 MCP memory 持久化路径
./install.sh install-coding-bridge-mcp  # 验证 coding-bridge MCP（External Review）
./scripts/setup-plugins.sh        # 装 3 marketplace + 7 plugin

不想记子命令？跑 ./tools/configure.mjs —— 菜单驱动配置 review 供应商 / API key / statusline，详见 docs/Usage/CONFIGURE.md。

卸载 / 回滚：

./install.sh --uninstall  # 或 ./uninstall.sh
./install.sh --rollback 1 # 1=最新，2=上一个，3=再上一个

日常更新:一条命令搞定

./scripts/pull-and-sync.sh

执行逻辑:fetch origin → 检测远端更新 → fast-forward pull → ./install.sh --check。

适用场景: 这是日常更新入口,推荐每次想拉新代码时跑(代替手动 git pull)。

不在范围内(pull-and-sync 失败/异常时)按下面"已有机器 git pull 后"段手动补。

Claude Code 主供应商预设

切换 Claude Code 本身的 AI 模型后端（接 minimax / 讯飞 / 火山 / 自建中转等兼容服务），运行 ./tools/configure.mjs → 菜单 2。详细操作见 docs/Usage/CONFIGURE.md。

预设从哪来

向导动态扫描两个目录的 JSON，过滤系统文件（settings.json / .mcp.json / providers.json / settings.local.json / default.json 等）后列出：

~/.claude/*.json — 用户自建预设（优先）
global/json/*.base.json — 仓库自带预设（同名时用户级覆盖）

任何含 env 段的 JSON 放进 ~/.claude/ 即成为可选预设，命名随意（myproxy.json 等）。

厂商元数据 `title` / `description`（可选）

在预设 JSON 顶层加 title / description 描述厂商，向导会优先展示：

{
  "title": "火山引擎（ARK）",
  "description": "字节跳动火山方舟，glm-5.2 直连",
  "env": { "ANTHROPIC_BASE_URL": "...", "ANTHROPIC_AUTH_TOKEN": "..." },
  "permissions": { "...": "..." }
}

title / description 是惰性顶层 key（同 permissions / hooks），合并时只取 env + model，从不并入 settings.json，不影响 Claude Code 运行。
title 缺失时回退显示文件名；description 缺失时回退显示 base_url。

列表显示格式（三段）

自建中转·火山 — 当前在用 — 自建 ai.imzhp.top 代理，火山后端
讯飞星火 — 科大讯飞星火 coding api，astron-code
myproxy.json — test.example.com

格式：[title|文件名] — [当前在用 — ]description|base_url。中段「当前在用」仅 active 项显示。

「当前在用」如何识别

向导把每个预设的 env 与 ~/.claude/settings.json 的 env 做 (key, value) 子集匹配——预设的每个 env 键值都等于 settings 当前值时，判定为「当前在用」。这比只比 ANTHROPIC_BASE_URL 更准：多个预设共用同一代理 URL（仅 token 不同）时仍能唯一识别。

token 等 secret 仅内部比对，绝不回显明文。

操作与注意事项

选中预设 = 把其 env 段深合并进 ~/.claude/settings.json（保留 statusLine / enabledPlugins / permissions 等其它字段；model 字段若有则一并覆盖）。
向导不让你输新 token —— 预设的 token 是你预先配过的 secret。token 过期 / 失效请手动编辑对应 JSON。
切完需要重启 Claude Code 让 env 生效。
ANTHROPIC_AUTH_TOKEN 等 secret 字段原样保留，不会因合并被清空。

与「外部 Review 供应商」的区别

菜单	作用对象	决定什么
主供应商预设	Claude Code 本身的 AI 模型	跟 Claude Code 聊天时它用哪家模型回答
外部 Review 供应商	coding-bridge MCP	Claude Code 改代码后外部审核走哪家

两者完全独立 —— 可以用火山跑 Claude Code，同时用 coding-bridge 走讯飞做外部审核。

跨项目用 nudge-review 强制外部审核

hooks/nudge-review.sh 是 commit-msg hook:提交代码改动(非 markdown)时,commit message 必须含审核标记:

Review: APPROVED — 走完整外部审核并通过
Review: N/A <reason> — 显式豁免(typo / doc-only / trivial)

装到本仓库: 默认已通过 install.sh 启用(等同其他 hook)。

装到其他项目(单条命令,每个项目跑一次):

cp /path/to/dotclaude-portable/hooks/nudge-review.sh <your-project>/.git/hooks/commit-msg
chmod +x <your-project>/.git/hooks/commit-msg

之后该项目所有代码改动 commit 都会被卡,直到 message 含 Review 字段。绕过:git commit --no-verify(显式,失去护栏)。

已有 dotclaude-portable 的机器,`git pull` 后

绝大多数情况 git pull 后 symlink 自动同步,无需重跑 install.sh：

cd ~/path/to/dotclaude-portable
git pull
./install.sh --check           # 3 秒,确认 symlink 健在

仅在以下情况手动补:

情况	命令	何时
新机器首次	`./install.sh`	clone 后首次
CLAUDE.md 被 OMC 改	`./install.sh --force`	`omc-setup` / `omc-doctor` 后
升级本机 pre-commit hook	`./install.sh install-pre-sync-docs-hook`	sync-docs.mjs 升级后首次 pull
重装 secret 扫描 hook	`./install.sh install-pre-push`	pre-push 被破坏后

注：scripts/setup-plugins.sh 仅在新机器或新增 plugin 时跑,日常 pull 不需要。

⚠️ 已知冲突：OMC 与本仓库的 `CLAUDE.md`

问题：oh-my-claudecode (OMC) 的 omc-setup / omc-doctor / 某些 slash command 会直接 patch ~/.claude/CLAUDE.md（用 OMC 自己的模板覆盖）。本仓库把 ~/.claude/CLAUDE.md 当作 global/CLAUDE.md 的 symlink 托管 —— OMC 会把 symlink 替换成普通文件，覆盖你的全局指令。

冲突表现：

symlink 被破坏（OMC 写文件时删了 symlink）
本机 ~/.claude/CLAUDE.md 不再跟仓库同步
git pull 后 symlink 重建，会丢失 OMC 注入的额外规则

解决方案：

# 1. 先 install（建立 symlink）再装 OMC，让 OMC 知道"这个文件已托管"
./install.sh
./scripts/setup-plugins.sh        # 这一步会装 oh-my-claudecode

# 2. OMC 装完后如果 symlink 被破坏：
./install.sh --force               # 重建 symlink
git diff ~/.claude/CLAUDE.md       # 检查是否丢了内容

# 3. 想知道 OMC 装完后改了哪些文件：
./install.sh --check               # symlink 健康巡检

经验法则：

先 install.sh → 再 setup-plugins.sh（顺序不能反）
装完 OMC 之后立即 ./install.sh --check 验证 symlink 健在
不要直接编辑 ~/.claude/CLAUDE.md（它是 symlink，本地编辑会落到 symlink 自身，git pull 后丢失）
想编辑全局指令 → 改仓库 global/CLAUDE.md → git push → 跨机器自然同步

对比 superpowers：superpowers 极简（14 skill, 2.4 MB，不改 CLAUDE.md），无此问题。详见 docs/Analysis/SUPERPOWERS_VS_OMC.md。

同步范围（清理后）

仓库路径	落点（相对 `~/.claude/`）	类型
`global/CLAUDE.md`	`CLAUDE.md`	symlink
`global/COMMIT_TEMPLATE.md`	`COMMIT_TEMPLATE.md`	symlink
`global/json/execution_config.base.json`	`execution_config.json`	渲染 cp（仅本机无时）
`global/json/mcp.base.json`	`.mcp.json`	渲染 cp（`${HOME}` 占位）
`global/json/.omc-version.base.json`	`.omc-version.json`	渲染 cp
`global/json/ccstatusline.base.json`	`~/.config/ccstatusline/settings.json`	symlink（`install-ccstatusline` 子命令; 首次自动 `npm i -g ccstatusline-zh`）
`commands/fix-permissions.md`	`commands/fix-permissions.md`	symlink
`commands/fullauto-prune.md`	`commands/fullauto-prune.md`	symlink
`skills/fullauto/SKILL.md`	`skills/fullauto/SKILL.md`	symlink
`global/json/settings.statusline.base.json`	合并到 `settings.json` 的 `statusLine` 字段	`install-statusline` 子命令
`hooks/review-watchdog.mjs`	`hooks/review-watchdog.mjs`	symlink（`HOOK_FILES` 动态扫描，新增 hook 丢进 `hooks/` 即可自动部署）
`hooks/guard-read-size.mjs`	`hooks/guard-read-size.mjs`	symlink（PreToolUse:Read — 超 2MB 媒体/5MB 文本自动 deny，避免撑爆 32MB 请求体）
`hooks/warn-context.mjs`	`hooks/warn-context.mjs`	symlink（UserPromptSubmit — transcript 24/28/30 MB 三档预警 systemMessage）

6 个 MCP（`global/json/mcp.base.json`）

context7 / filesystem / mcp-deepwiki / memory / coding-bridge / kimi（fallback）
前 4 个用 npx -y <pkg> 启动；coding-bridge + kimi 是 Python 项目，需先装 uvx（curl -LsSf https://astral.sh/uv/install.sh | sh）
关键：Claude Code 真正加载 MCP server 是从 ~/.claude.json 的 mcpServers 字段（不是 ~/.claude/.mcp.json——后者是 OMC 等工具读的，不被 Claude Code 加载）
CLAUDE.md fallback 链：coding-bridge → kimi（CLAUDE.md §"Hard-coded fallback"）。coding-bridge 失败时 Claude 自动用 mcp__kimi__kimi 兜底
必设环境变量（仅 coding-bridge）：export CODING_BRIDGE_API_KEY=<your-key>（写到 ~/.zshrc）；kimi 自动读 ~/.claude/kimi.json 的 provider 配置
自动把 mcp__coding-bridge__review_code + mcp__coding-bridge__review_plan + mcp__kimi__kimi 加进 ~/.claude/settings.json 的 permissions.allow
跨机器只需 node + npx + uvx

`ccstatusline-zh`（非 plugin，是 statusLine 命令 + 配置）

settings.json 含 sk- token 永不入库 → statusLine 单独脱敏
用 ./install.sh install-statusline 把 statusline.base.json 合并到本机 ~/.claude.json 的 statusLine 字段
用 ./install.sh install-ccstatusline 自动 npm i -g ccstatusline-zh + symlink global/json/ccstatusline.base.json 到 ~/.config/ccstatusline/settings.json（主 install() 已自动调用，单独跑用于重装）
不污染 env / permissions 等含 token 的其他字段
⚠️ 改 global/json/ccstatusline.base.json 时,需手动同步 README（本仓库的 sync-docs.mjs 暂未覆盖 global/json/ 章节）

7 个 plugin（`enabledPlugins`）

不进 dotclaude-portable 仓库（每个 plugin 都有独立 git source，体积大）
跨机器装：./scripts/setup-plugins.sh
维护 3 个 marketplace + 7 个 plugin（oh-my-claudecode / frontend-design / 3 个 LSP / context7 / code-review）

永不入库（实测含 secret 或本机局部）

settings.json / settings.self / default.json / providers.json — 全部含 sk-... 真实 API token
settings.local.json — 本机临时权限列表
.omc-config.json — 含 telegram bot token + 本机 nvm 路径
kimi.json / minimax.json / selfminimax.json / baidu.json / anyrouter.json / mcp-needs-auth-cache.json
所有缓存/历史/运行态/插件目录

完整决策表见 docs/Analysis/INVENTORY.md。

Hooks (3 已落地)

hooks/review-watchdog.mjs — PostToolUse hook；Write|Edit 触及代码文件但本轮未调 runReview 时 stderr 提示（exit 0，非阻塞）
hooks/guard-read-size.mjs — PreToolUse:Read 守卫；图片/PDF/压缩档 >2MB 或文本 >5MB 时 deny 防撑爆 32MB 请求体；用 path.extname() 兼容复合扩展名
hooks/warn-context.mjs — UserPromptSubmit 守卫；transcript ≥24MB 温和 / ≥28MB 强烈 / ≥30MB 紧急三档 systemMessage 提醒，趁 /compact 仍可成功时主动处理
hooks/nudge-review.sh — nudge-review.sh — commit-msg hook: 提交前提醒跑外部代码审核
Auto-deploy：./install.sh 通过 HOOK_FILES 动态扫描 hooks/*.mjs / hooks/*.sh，无需在 MAP 中注册；--check 校验 symlink 健在

安全防御

.gitignore 黑名单 + 白名单：global/json/* 全屏蔽，例外 *.base.json；模式化屏蔽 **/settings*.json / **/provider*.json / **/.omc-config*.json 等
tools/scan-secrets.py：7 类 token 模式（sk- / AKIA / ghp_ / xoxb- / telegram / sk-ant- / 长 hex）+ 敏感 key 上下文
install.sh doctor：调扫描器，命中即 fail
install.sh install-pre-push：在 .git/hooks/pre-push 装拦截器（git push 时强制扫）
tests/fixtures/：正/负样本（假 token + 干净样本）

关键设计

默认 symlink：仓库 git pull 即生效；不放心可用 --copy
首次安装自动备份：原文件移到 ~/.claude.backups/<时间戳>/，最多保留 3 快照
幂等：检测到 .dotclaude-portable.version 标记后跳过整盘备份
shell 注入幂等：往 ~/.bashrc / ~/.zshrc 追加 # dotclaude-portable 标记 + export CLAUDE_HOME="$HOME/.claude"，卸载时整段剥离
JSON 渲染：仅替换 ${HOME} / ${USER} 两个占位符；本机已有同名 JSON 不覆盖
statusLine 合并：用 Python 把 base 的 statusLine 字段 merge 进本机 settings.json（base 优先覆盖），其他字段保留
plugin 跨机器装：单独脚本 scripts/setup-plugins.sh，不污染 install.sh

CI / 测试

.github/workflows/ci.yml：Ubuntu 跑 dry-run / doctor / install / check / rollback / uninstall / scan-secrets
./tests/ci/smoke.sh：本地复现 CI（用 FAKE_HOME 隔离，不污染本机 ~/.claude）
hooks：HOOK_FILES 自动从 hooks/ 目录发现 *.mjs / *.sh，无需在 install.sh 注册

Windows

用 Git Bash 跑 ./install.sh
MINGW* / MSYS* / CYGWIN* 自动 fallback 到 --copy 模式

macOS

1.0.5+ 已支持：默认 macOS bash 3.2.57（Apple 因 GPLv3 拒绝升级）下 ./install.sh --force 跑通，hooks 正确部署
Linux 同样可用（bash 4/5）
系统需预装 python3（macOS 13+ 自带 / 旧版 brew install python3）与 npx（brew install node）

Navigation Menu

Repository files navigation

dotclaude-portable

5 分钟上手

日常更新:一条命令搞定

Claude Code 主供应商预设

预设从哪来

厂商元数据 `title` / `description`（可选）

列表显示格式（三段）

「当前在用」如何识别

操作与注意事项

与「外部 Review 供应商」的区别

跨项目用 nudge-review 强制外部审核

已有 dotclaude-portable 的机器,`git pull` 后

⚠️ 已知冲突：OMC 与本仓库的 `CLAUDE.md`

同步范围（清理后）

6 个 MCP（`global/json/mcp.base.json`）

`ccstatusline-zh`（非 plugin，是 statusLine 命令 + 配置）

7 个 plugin（`enabledPlugins`）

永不入库（实测含 secret 或本机局部）

Hooks (3 已落地)

安全防御

关键设计

CI / 测试

Windows

macOS

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github		.github
commands		commands
docs		docs
global		global
hooks		hooks
mcp		mcp
scripts		scripts
skills/fullauto		skills/fullauto
tests		tests
tools		tools
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
install.sh		install.sh
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation

dotclaude-portable

5 分钟上手

日常更新:一条命令搞定

Claude Code 主供应商预设

预设从哪来

厂商元数据 title / description（可选）

列表显示格式（三段）

「当前在用」如何识别

操作与注意事项

与「外部 Review 供应商」的区别

跨项目用 nudge-review 强制外部审核

已有 dotclaude-portable 的机器,git pull 后

⚠️ 已知冲突：OMC 与本仓库的 CLAUDE.md

同步范围（清理后）

6 个 MCP（global/json/mcp.base.json）

ccstatusline-zh（非 plugin，是 statusLine 命令 + 配置）

7 个 plugin（enabledPlugins）

永不入库（实测含 secret 或本机局部）

Hooks (3 已落地)

安全防御

关键设计

CI / 测试

Windows

macOS

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

厂商元数据 `title` / `description`（可选）

已有 dotclaude-portable 的机器,`git pull` 后

⚠️ 已知冲突：OMC 与本仓库的 `CLAUDE.md`

6 个 MCP（`global/json/mcp.base.json`）

`ccstatusline-zh`（非 plugin，是 statusLine 命令 + 配置）

7 个 plugin（`enabledPlugins`）