完成一个简易的全局skill、command管理器
This commit is contained in:
219
manager/README.md
Normal file
219
manager/README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user