# Claude Craft：Claude Code 扩展生态的完整管理工具包

> Claude Craft 是一个综合性的 Claude Code 扩展管理工具包，支持 7 种扩展类型（agents、commands、skills、prompts、references、plugins、hooks）的符号链接同步管理，提供自动同步、安全扫描和 Prompt-as-Code 工作流。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-06T04:44:59.000Z
- 最近活动: 2026-04-06T04:54:39.337Z
- 热度: 157.8
- 关键词: claude-code, extension, sync, prompt-as-code, security, git-hooks, workflow
- 页面链接: https://www.zingnex.cn/forum/thread/claude-craft-claude-code
- Canonical: https://www.zingnex.cn/forum/thread/claude-craft-claude-code
- Markdown 来源: ingested_event

---

## 项目概述

Claude Craft 是一个为 Claude Code 设计的完整开发工具包，通过符号链接（symlink）机制管理全部 7 种扩展类型，实现零冲突的扩展管理。项目提供自动同步、安全扫描、别名管理等功能，使 Claude Code 的扩展开发和维护更加系统化。

## 支持的 7 种扩展类型

Claude Craft 支持管理 Claude Code 的全部扩展类型：

| 扩展类型 | 同步方式 | 跳过模式 |
|----------|----------|----------|
| Agents | 单文件符号链接 (.md) | — |
| Commands | 单文件符号链接 (.md) | alias.md, unalias.md, agent-sync.md |
| Skills | 目录符号链接 | 隐藏目录 |
| Prompts | 单文件符号链接 (.md) | old-do-not-use-*, test-* |
| References | 单文件符号链接 (.md) | — |
| Plugins | 目录符号链接 | 隐藏目录 |
| Hooks | 单文件符号链接 (.sh) | — |

## 核心命令

### /agent-sync：扩展同步管理

这是 Claude Craft 的核心命令，用于管理仓库与 `~/.claude/` 目录之间的同步：

```bash
# 检查同步状态（默认行为）
/agent-sync

# 同步所有仓库项到 ~/.claude
/agent-sync sync

# 查看尚未安装的仓库项
/agent-sync add

# 查看可发布到仓库的本地项
/agent-sync publish

# 启用自动同步
/agent-sync auto enable

# 检查自动同步配置
/agent-sync auto status

# 强制立即同步
/agent-sync auto force

# 禁用自动同步
/agent-sync auto disable
```

### 智能后台同步

自动同步功能采用概率触发机制：

- **概率触发**：约 1/27 的用户提示触发同步（3.7% 概率）
- **防抖机制**：最小 5 秒间隔防止频繁触发
- **后台操作**：不中断当前工作流
- **智能冲突检测**：自动处理暂存/合并
- **安全集成**：同步前进行安全扫描

### /prompt：Prompt-as-Code

/prompt 命令利用 Claude Code 的 prompt-as-code 模式，将提示词转变为可执行、可组合的功能单元：

**为什么使用 Prompt-as-Code？**

- **动态推理**：与静态脚本不同，提示词利用 AI 的推理能力适应上下文
- **自然语言逻辑**：用散文而非脆弱的代码表达复杂工作流
- **可组合性**：将提示词链接在一起，在它们之间传递结果
- **自文档化**：提示词本身就是文档，人类和 AI 都能阅读
- **灵活执行**：同一提示词可根据项目上下文表现不同

**使用示例**：

```bash
# 执行提示词模板
/prompt api-design

# AI 分析上下文并选择适当的调试策略
/prompt debugging

# 基于仓库状态进行自适应威胁分析
/prompt git-security-threat
```

### 别名管理

```bash
# 创建本地别名
/alias deploy /prompt api-design && npm test && npm run deploy

# 创建全局别名（所有项目可用）
/alias --global whatis ls -la

# 列出所有别名
/alias --list

# 删除别名（带确认）
/unalias deploy

# 强制删除（无确认）
/unalias whatis --force
```

## 安全特性

### Git 安全钩子

Claude Craft 自动安装本地 Git 钩子，提供以下保护：

#### Post-merge 安全扫描

每次 `git pull` 后自动执行：

- 分析变更的可执行文件以检测安全威胁
- 检测危险的 shell 命令和恶意脚本
- 可自动恢复可疑的合并
- 安全事件记录到 `~/.git-security.log`

#### Pre-commit 密钥检测

每次 `git commit` 前自动执行：

- 阻止包含硬编码 API 密钥、密码的提交
- 检测 Anthropic、OpenAI、AWS、GitHub 令牌
- 提供具体的修复建议
- 允许使用 `--no-verify` 紧急绕过

#### 检测的威胁类型

- **破坏性操作**：rm -rf、dd、mkfs、磁盘写入
- **凭证窃取**：AWS/GCP/Azure 密钥提取、令牌收集
- **数据外泄**：curl/wget 管道、netcat、base64 编码
- **代码注入**：eval、exec、带外部输入的系统调用
- **持久化**：crontab 修改、服务安装
- **开发工具滥用**：sfdx、clasp、terraform destroy

### 安全扫描命令

```bash
# 安装/重新安装 Git 钩子
~/claude-craft/tools/install-git-hooks.sh

# 检查当前目录的密钥
~/claude-craft/tools/security-scan.sh . secrets true

# 紧急绕过（谨慎使用）
git commit --no-verify
```

## 安装与卸载

### 一键安装

```bash
curl -fsSL https://raw.githubusercontent.com/whichguy/claude-craft/main/install.sh | bash
```

安装完成后重启 Claude Code 加载新扩展。

### 手动安装

```bash
git clone https://github.com/whichguy/claude-craft.git ~/claude-craft
cd ~/claude-craft
chmod +x install.sh
./install.sh
```

### 安全卸载

```bash
# 预览将要移除的内容（推荐先执行）
~/claude-craft/uninstall.sh --dry-run

# 交互式卸载（带确认）
~/claude-craft/uninstall.sh

# 静默卸载（无提示）
~/claude-craft/uninstall.sh --yes

# 完整卸载（包括 Git 钩子和备份）
~/claude-craft/uninstall.sh --yes --remove-hooks --clean-backups

# 卸载前从备份恢复
~/claude-craft/uninstall.sh --restore-backup --yes
```

卸载选项说明：

| 选项 | 描述 |
|------|------|
| --dry-run | 预览将要移除的内容，不做实际更改 |
| --yes, -y | 跳过确认提示，用于自动化移除 |
| --keep-repo | 不删除 ~/claude-craft 仓库 |
| --keep-commands | 不移除全局命令 |
| --remove-hooks | 同时移除 Git 安全钩子 |
| --restore-backup | 卸载前从最新备份恢复 |
| --clean-backups | 移除 claude-craft 备份文件 |

## 目录结构

```
claude-craft/
├── .githooks/              # 本地 Git 钩子
│   ├── post-merge          # pull 后安全扫描
│   └── pre-commit          # commit 前密钥检测
├── agents/                 # Agent 定义 (.md)
├── commands/               # 斜杠命令 (.md)
├── skills/                 # Skill 目录
├── prompts/                # 提示词模板 (.md)
├── references/             # 参考文档 (.md)
├── plugins/                # 插件目录
├── hooks/                  # 钩子系统
│   └── scripts/            # 钩子脚本 (.sh)
├── test/                   # 测试框架 (Mocha/Chai)
│   └── sync.test.js        # 26 个同步基础设施测试
├── tools/                  # 管理工具
│   ├── sync-status.sh      # 核心同步引擎
│   ├── auto-sync.sh        # 概率后台同步
│   ├── install-git-hooks.sh
│   ├── security-scan.sh
│   └── backup.sh
├── install.sh              # 一键安装器
└── uninstall.sh            # 安全卸载器
```

## 本地文件保护

Claude Craft 的核心设计原则之一是保护用户的本地配置：

- **永不覆盖非仓库文件**：同步操作只处理仓库中的文件
- **保留原始设置**：原始的 `~/.claude/settings.json` 和 `~/.claude/CLAUDE.md` 保持不变
- **手动配置不受影响**：用户手动创建的命令或配置不会被触碰
- **自动清理断链**：自动清理失效的符号链接

## 日常同步工作流

### 每日同步

```bash
/agent-sync sync
```

执行以下操作：

1. `git pull --ff-only` 获取最新变更
2. 重新同步所有符号链接（处理新增/删除的文件）
3. 保留本地独有文件
4. 自动清理断链

### 发布本地扩展

```bash
# 查看可发布的本地项
/agent-sync publish

# 手动复制到仓库并提交
cp ~/.claude/commands/my-command.md ~/claude-craft/commands/
cd ~/claude-craft
git add .
git commit -m "添加 my-command 命令"
git push
```

## 技术实现细节

### 符号链接同步机制

所有同步操作使用 `tools/sync-status.sh` —— 一个数据驱动的脚本处理全部 7 种扩展类型：

- **单文件扩展**（Agents、Commands、Prompts、References、Hooks）：为每个 `.md` 或 `.sh` 文件创建独立符号链接
- **目录扩展**（Skills、Plugins）：为整个目录创建符号链接

### 概率同步算法

自动同步使用简单的概率触发：

```
随机数生成 → 如果 < 0.037 (3.7%) → 触发同步
                ↓
            防抖检查（5秒间隔）
                ↓
            后台执行同步
```

这种设计确保同步不会过于频繁，同时保持仓库与本地配置的 eventual consistency。

## 适用场景

- **团队扩展管理**：统一团队的 Claude Code 扩展配置
- **多设备同步**：在多台机器上保持一致的开发环境
- **扩展开发**：系统化管理自定义 prompts、commands 和 agents
- **安全合规**：通过 Git 钩子强制执行安全策略
- **Prompt-as-Code 实践**：将 AI 提示词纳入版本控制

## 总结

Claude Craft 为 Claude Code 用户提供了一个完整的扩展管理解决方案。通过符号链接机制实现即时更新、零冲突管理，同时通过安全钩子和概率同步确保生产环境的安全性和可用性。对于希望系统化管理和共享 Claude Code 扩展的团队和个人开发者，这是一个值得采用的工具包。