220 lines
4.4 KiB
Markdown
220 lines
4.4 KiB
Markdown
# skillmgr
|
||
|
||
一个用于管理和分发 LLM 编程助手命令和技能的 CLI 工具。
|
||
|
||
## 功能特性
|
||
|
||
- 从 git 仓库拉取 skills 和 commands
|
||
- 支持多平台部署（Claude Code、OpenCode）
|
||
- 支持全局安装和项目级安装
|
||
- 事务性安装，避免安装失败导致的文件污染
|
||
- 完整的安装追踪和管理
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
# 从源码构建
|
||
git clone https://github.com/your/skills.git
|
||
cd skills/manager
|
||
make build
|
||
|
||
# 将可执行文件添加到 PATH
|
||
cp bin/skillmgr /usr/local/bin/
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 添加仓库
|
||
skillmgr add https://github.com/your/skills-repo.git --name my-skills
|
||
|
||
# 同步仓库内容
|
||
skillmgr sync
|
||
|
||
# 搜索可用的 skills 和 commands
|
||
skillmgr search
|
||
|
||
# 安装 skill 到 Claude Code（全局）
|
||
skillmgr install skill my-skill --platform claude --global
|
||
|
||
# 安装 command 到 OpenCode（项目级）
|
||
skillmgr install command my-cmd --platform opencode
|
||
```
|
||
|
||
## 命令参考
|
||
|
||
### 仓库管理
|
||
|
||
```bash
|
||
# 添加仓库
|
||
skillmgr add <url> --name <name> [--branch <branch>]
|
||
|
||
# 移除仓库
|
||
skillmgr remove <name>
|
||
|
||
# 列出仓库
|
||
skillmgr repos
|
||
|
||
# 同步仓库（拉取最新）
|
||
skillmgr sync [name]
|
||
```
|
||
|
||
### 安装管理
|
||
|
||
```bash
|
||
# 安装
|
||
skillmgr install <skill|command> <name> --platform <claude|opencode> [--global]
|
||
|
||
# 卸载
|
||
skillmgr uninstall <skill|command> <name> --platform <claude|opencode> [--global]
|
||
|
||
# 更新
|
||
skillmgr update <skill|command> <name> --platform <claude|opencode> [--global]
|
||
skillmgr update --all
|
||
|
||
# 列出已安装
|
||
skillmgr list [--type <skill|command>] [--platform <claude|opencode>] [--global]
|
||
|
||
# 搜索可用项
|
||
skillmgr search [keyword] [--type <skill|command>] [--repo <name>]
|
||
|
||
# 清理孤立记录
|
||
skillmgr clean [--dry-run]
|
||
```
|
||
|
||
## 平台适配
|
||
|
||
### Claude Code
|
||
|
||
- Skills 安装到 `~/.claude/skills/<skill-name>/` (全局) 或 `./.claude/skills/<skill-name>/` (项目)
|
||
- Commands 安装到 `~/.claude/commands/<cmd-name>/` (全局) 或 `./.claude/commands/<cmd-name>/` (项目)
|
||
- 保持原始目录结构
|
||
|
||
### OpenCode
|
||
|
||
- Skills 全局安装到 `~/.config/opencode/skills/<skill-name>/`，项目级安装到 `./.opencode/skills/<skill-name>/`
|
||
- Commands 全局安装到 `~/.config/opencode/commands/`，项目级安装到 `./.opencode/commands/`
|
||
- Command 文件名扁平化：`<group>-<action>.md`
|
||
- 例如：`commands/lyxy-kb/init.md` → `~/.config/opencode/commands/lyxy-kb-init.md`
|
||
|
||
## 配置文件
|
||
|
||
### 仓库配置
|
||
|
||
位置：`~/.skillmgr/repository.json`
|
||
|
||
```json
|
||
{
|
||
"repositories": [
|
||
{
|
||
"name": "my-skills",
|
||
"url": "https://github.com/user/skills.git",
|
||
"branch": "main",
|
||
"added_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 安装记录
|
||
|
||
位置：`~/.skillmgr/install.json`
|
||
|
||
```json
|
||
{
|
||
"installations": [
|
||
{
|
||
"type": "skill",
|
||
"name": "my-skill",
|
||
"source_repo": "my-skills",
|
||
"platform": "claude",
|
||
"scope": "global",
|
||
"install_path": "/Users/xxx/.claude/skills/my-skill",
|
||
"installed_at": "2024-01-01T00:00:00Z",
|
||
"updated_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 仓库结构
|
||
|
||
skillmgr 期望源仓库具有以下结构：
|
||
|
||
```
|
||
your-skills-repo/
|
||
├── skills/
|
||
│ ├── skill-a/
|
||
│ │ ├── SKILL.md # 必需：skill 定义文件
|
||
│ │ └── ... # 其他支持文件
|
||
│ └── skill-b/
|
||
│ └── SKILL.md
|
||
└── commands/
|
||
├── cmd-group-a/
|
||
│ ├── init.md
|
||
│ └── run.md
|
||
└── cmd-group-b/
|
||
└── action.md
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
make test
|
||
|
||
# 运行单元测试
|
||
make test-unit
|
||
|
||
# 生成覆盖率报告
|
||
make test-coverage
|
||
|
||
# 使用沙盒环境手动测试
|
||
make sandbox
|
||
```
|
||
|
||
### 测试环境变量
|
||
|
||
- `SKILLMGR_TEST_ROOT`: 覆盖配置目录（`~/.skillmgr`）
|
||
- `SKILLMGR_TEST_BASE`: 覆盖安装基础目录（用户主目录或当前目录）
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **Git clone 失败**
|
||
- 检查网络连接
|
||
- 确认仓库 URL 正确
|
||
- 对于私有仓库，确保已配置 SSH 密钥或 token
|
||
|
||
2. **找不到 skill/command**
|
||
- 运行 `skillmgr sync` 更新本地缓存
|
||
- 使用 `skillmgr search` 查看可用项
|
||
|
||
3. **安装冲突**
|
||
- 已安装的项会提示覆盖确认
|
||
- 使用 `skillmgr uninstall` 先卸载
|
||
|
||
4. **孤立记录**
|
||
- 当文件被手动删除时，使用 `skillmgr clean` 清理记录
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 依赖
|
||
make deps
|
||
|
||
# 构建
|
||
make build
|
||
|
||
# 代码格式化
|
||
make fmt
|
||
|
||
# 代码检查
|
||
make lint
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|