@workskills/getskill 1.1.9 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/EXAMPLES.md CHANGED
@@ -1,175 +1,151 @@
1
1
  # GetSkill 使用示例
2
2
 
3
- ## 场景 1: 首次使用(未安装 Git)
3
+ > 当前版本基于 `getskill.work` 静态索引 + ZIP 包下载,搜索/安装/更新**无需 Git、无需登录**。
4
4
 
5
- ### Windows 用户
5
+ ## 场景 1: 搜索并安装技能
6
6
 
7
7
  ```bash
8
- # 第一次运行安装命令
9
- $ getskill install commit-helper
10
-
11
- 检测到系统未安装 Git,正在准备安装...
12
-
13
- Windows 系统检测到未安装 Git
14
- 正在下载 Git 安装程序...
15
-
16
- 下载进度: 100%
17
- 下载完成!
8
+ # 搜索技能
9
+ $ getskill search pdf
18
10
 
19
- Git 安装程序已下载到: C:\Users\...\AppData\Local\Temp\git-installer.exe
11
+ 找到 1 个技能:
20
12
 
21
- 正在启动安装程序,请按照提示完成安装...
22
- 安装完成后,请重新运行此命令。
13
+ 1. pdf-extract (v1.0.0)
14
+ 描述: 从 PDF 文件中提取文本和表格
15
+ 分类: 文档处理
16
+ 下载: https://getskill.work/skills/pdf-extract.zip
23
17
 
24
- # Git 安装完成后,再次运行
25
- $ getskill install commit-helper
18
+ # 安装技能
19
+ $ getskill install pdf-extract
26
20
 
27
- 下载技能: commit-helper...
28
- 克隆仓库: https://getskill.work/skills/commit-helper.git...
29
- 仓库克隆成功: C:\Users\...\\.openclaw\skills-cache\commit-helper
21
+ 下载技能: pdf-extract...
22
+ 下载技能包: https://getskill.work/skills/pdf-extract.zip
23
+ 下载完成 (173410 bytes),正在解压...
24
+ 技能包已解压: ~/.openclaw/skills-cache/pdf-extract
25
+ 技能 pdf-extract (v1.0.0) 安装成功!
30
26
 
31
27
  技能已安装到 skills 目录:
32
- - C:\Users\...\.openclaw\skills\commit-helper
28
+ - ~/.openclaw/skills/pdf-extract
33
29
 
34
- Git 仓库缓存: C:\Users\...\.openclaw\skills-cache\commit-helper
30
+ 本地缓存: ~/.openclaw/skills-cache/pdf-extract
31
+ 已安装版本: 1.0.0
35
32
  ```
36
33
 
37
- ### macOS 用户
34
+ ## 场景 2: 日常使用流程
38
35
 
39
36
  ```bash
40
- $ getskill install commit-helper
37
+ # 列出已安装的技能
38
+ $ getskill list
41
39
 
42
- 检测到系统未安装 Git,正在准备安装...
40
+ 本地已安装的技能 (1):
41
+ 1. pdf-extract
43
42
 
44
- macOS 系统检测到未安装 Git
45
- 请使用以下命令安装 Git:
43
+ # 检查更新(版本比较)
44
+ $ getskill update pdf-extract
46
45
 
47
- brew install git
46
+ 正在更新技能: pdf-extract...
47
+ 发现新版本: 1.0.0 -> 1.1.0
48
+ 下载技能包: https://getskill.work/skills/pdf-extract.zip
49
+ 下载完成 (175000 bytes),正在解压...
50
+ 技能 pdf-extract 更新成功!
48
51
 
49
- 如果未安装 Homebrew,请访问: https://brew.sh/
52
+ 技能已更新到 skills 目录:
53
+ - ~/.openclaw/skills/pdf-extract
54
+ 当前版本: 1.1.0
50
55
 
51
- # 安装 Git
52
- $ brew install git
56
+ # 已是最新时
57
+ $ getskill update pdf-extract
53
58
 
54
- # 再次运行
55
- $ getskill install commit-helper
56
- ✓ 安装成功
57
- ```
59
+ 正在更新技能: pdf-extract...
60
+ 技能 pdf-extract 已是最新版本 (1.1.0),无需更新
58
61
 
59
- ### Linux 用户
62
+ 技能已是最新版本 (v1.1.0),无需更新。
60
63
 
61
- ```bash
62
- $ getskill install commit-helper
64
+ # 批量更新所有已安装技能
65
+ $ getskill update --all
63
66
 
64
- 检测到系统未安装 Git,正在准备安装...
67
+ # 查看某个技能的安装状态
68
+ $ getskill inspect pdf-extract
65
69
 
66
- Linux 系统检测到未安装 Git
67
- 请使用系统包管理器安装 Git:
70
+ # 查看目录路径
71
+ $ getskill path
68
72
 
69
- Ubuntu/Debian: sudo apt-get install git
70
- CentOS/RHEL: sudo yum install git
71
- Fedora: sudo dnf install git
72
- Arch: sudo pacman -S git
73
+ 技能目录: ~/.openclaw/skills
74
+ 缓存目录: ~/.openclaw/skills-cache
73
75
 
74
- # Ubuntu/Debian 用户
75
- $ sudo apt-get install git
76
+ # 清理 ZIP 下载/解压缓存
77
+ $ getskill clean
76
78
 
77
- # 再次运行
78
- $ getskill install commit-helper
79
- ✓ 安装成功
79
+ 已清理缓存目录: ~/.openclaw/skills-cache
80
80
  ```
81
81
 
82
- ## 场景 2: 已安装 Git(正常使用)
82
+ ## 场景 3: JSON 输出与脚本集成
83
83
 
84
84
  ```bash
85
- # 搜索技能
86
- $ getskill search commit
87
-
88
- 找到 3 个技能:
89
-
90
- 1. commit-helper
91
- 描述: 帮助生成规范的 git commit 信息
92
- Git: https://getskill.work/skills/commit-helper.git
93
-
94
- 2. commit-lint
95
- 描述: 检查 commit 信息是否符合规范
96
- Git: https://getskill.work/skills/commit-lint.git
97
-
98
- # 安装技能
99
- $ getskill install commit-helper
100
-
101
- 下载技能: commit-helper...
102
- 克隆仓库: https://getskill.work/skills/commit-helper.git...
103
- 仓库克隆成功: ~/.openclaw/skills-cache/commit-helper
104
- 已复制技能目录: ~/.openclaw/skills-cache/commit-helper -> ~/.openclaw/skills/commit-helper
105
-
106
- 技能已安装到 skills 目录:
107
- - ~/.openclaw/skills/commit-helper
108
-
109
- Git 仓库缓存: ~/.openclaw/skills-cache/commit-helper
110
-
111
- # 列出已安装的技能
112
- $ getskill list
113
-
114
- 本地已安装的技能 (1):
115
- 1. commit-helper
116
-
117
- # 更新技能
118
- $ getskill update commit-helper
119
-
120
- 正在更新技能: commit-helper...
121
- Git 仓库已更新
122
- Already up to date.
123
- 已复制技能目录: ~/.openclaw/skills-cache/commit-helper -> ~/.openclaw/skills/commit-helper
124
-
125
- 技能已更新到 skills 目录:
126
- - ~/.openclaw/skills/commit-helper
85
+ $ getskill search xlsx --json
86
+
87
+ {
88
+ "keyword": "xlsx",
89
+ "count": 1,
90
+ "results": [
91
+ {
92
+ "name": "xlsx",
93
+ "full_name": "xlsx",
94
+ "description": "...",
95
+ "html_url": "https://getskill.work/skill.html?id=xlsx",
96
+ "git_url": "https://getskill.work/skills/xlsx.zip",
97
+ "clone_url": "https://getskill.work/skills/xlsx.zip",
98
+ "download_url": "https://getskill.work/skills/xlsx.zip",
99
+ "version": "1.0.0",
100
+ "category": "文档处理",
101
+ "author": "Anthropic",
102
+ "size": 173410
103
+ }
104
+ ]
105
+ }
106
+ ```
127
107
 
128
- # 查看目录路径
129
- $ getskill path
108
+ 批量安装脚本:
130
109
 
131
- 技能目录: ~/.openclaw/skills
132
- 缓存目录: ~/.openclaw/skills-cache
133
-
134
- # 清理缓存
135
- $ getskill clean
110
+ ```bash
111
+ #!/bin/bash
112
+ skills=(
113
+ "pdf-extract"
114
+ "xlsx"
115
+ "docx"
116
+ )
136
117
 
137
- 已清理缓存目录: ~/.openclaw/skills-cache
118
+ for skill in "${skills[@]}"; do
119
+ echo "正在安装: $skill"
120
+ getskill install "$skill"
121
+ echo "---"
122
+ done
138
123
  ```
139
124
 
140
- ## 场景 3: 编程接口使用
125
+ ## 场景 4: 编程接口使用
141
126
 
142
127
  ```javascript
143
128
  const getskill = require('@workskills/getskill');
144
129
 
145
130
  (async () => {
146
131
  try {
147
- // 设置自定义 API 地址(可选)
132
+ // 设置自定义索引地址(可选)
148
133
  getskill.setBaseUrl('https://getskill.work');
149
134
 
150
- // 查看当前 API 地址
151
- console.log('当前 API:', getskill.getBaseUrl());
135
+ // 查看当前索引地址
136
+ console.log('当前索引:', getskill.getBaseUrl());
152
137
 
153
- // 检查 Git 是否已安装
154
- const isGitInstalled = await getskill.checkGitInstalled();
155
- console.log('Git 已安装:', isGitInstalled);
156
-
157
- if (!isGitInstalled) {
158
- console.log('正在引导安装 Git...');
159
- await getskill.ensureGitInstalled();
160
- }
161
-
162
- // 搜索技能
163
- const results = await getskill.searchSkills('commit');
138
+ // 搜索技能(基于静态索引 data/skills.json)
139
+ const results = await getskill.searchSkills('pdf');
164
140
  console.log('搜索结果:', results);
165
141
 
166
- // 安装技能
167
- const result = await getskill.downloadSkill('skills/commit-helper');
142
+ // 安装技能(下载 ZIP + 本地解压 + 复制)
143
+ const result = await getskill.downloadSkill('pdf-extract');
168
144
  console.log('安装成功:', result.files);
169
145
 
170
- // 更新技能
171
- await getskill.updateSkill('commit-helper');
172
- console.log('更新成功');
146
+ // 更新技能(版本比较)
147
+ await getskill.updateSkill('pdf-extract');
148
+ console.log('更新检查完成');
173
149
 
174
150
  // 列出本地技能
175
151
  const localSkills = getskill.listLocalSkills();
@@ -180,31 +156,26 @@ const getskill = require('@workskills/getskill');
180
156
  })();
181
157
  ```
182
158
 
183
- ## 场景 4: 批量安装技能
159
+ ## 场景 5: 发布技能到自有 Git 仓库
184
160
 
185
161
  ```bash
186
- # 创建脚本 install-skills.sh
187
- #!/bin/bash
162
+ $ getskill publish ./my-skill --repo https://github.com/<user>/my-skill.git
188
163
 
189
- skills=(
190
- "commit-helper"
191
- "code-review"
192
- "test-generator"
193
- "doc-writer"
194
- )
164
+ 校验 SKILL.md...
165
+ 初始化 Git 仓库...
166
+ 提交并推送到 main 分支...
167
+ 发布成功: https://github.com/<user>/my-skill
168
+ ```
195
169
 
196
- for skill in "${skills[@]}"; do
197
- echo "正在安装: $skill"
198
- getskill install "$skill"
199
- echo "---"
200
- done
170
+ 可选参数:
201
171
 
202
- # 运行脚本
203
- $ chmod +x install-skills.sh
204
- $ ./install-skills.sh
172
+ ```bash
173
+ getskill publish <目录> --repo <git-url> --branch <name> --message <text>
205
174
  ```
206
175
 
207
- ## 场景 5: 错误处理
176
+ > `SKILL.md` 缺失或不符合规范(缺少 front matter、`metadata`、`## 指令` 等关键结构)时,发布会被直接阻止。
177
+
178
+ ## 场景 6: 错误处理
208
179
 
209
180
  ```bash
210
181
  # 技能不存在
@@ -213,82 +184,60 @@ $ getskill install non-existent-skill
213
184
  下载技能失败: 技能不存在: non-existent-skill
214
185
  执行命令时出错: 技能不存在: non-existent-skill
215
186
 
216
- # Git URL 无效
217
- $ getskill install invalid-git-skill
218
- 下载技能: invalid-git-skill...
219
- 克隆仓库: https://getskill.work/skills/invalid-git-skill.git...
220
- 克隆失败: fatal: repository 'https://getskill.work/skills/invalid-git-skill.git/' not found
221
- 下载技能失败: Command failed: git clone...
222
- 执行命令时出错: Command failed: git clone...
223
-
224
187
  # 网络问题
225
- $ getskill search commit
188
+ $ getskill search pdf
226
189
  搜索失败: 请求超时,请稍后重试
227
190
  未找到相关技能
228
191
  提示: 尝试使用不同的关键词,或访问 https://getskill.work 查看所有可用技能
229
192
  ```
230
193
 
231
- ## 场景 6: 配置自定义 API 地址
194
+ ## 场景 7: 配置自定义索引地址
232
195
 
233
196
  ```bash
234
- # 查看当前 API 地址
197
+ # 查看当前索引地址
235
198
  $ getskill config get
236
199
  当前 BASE_URL: https://getskill.work
237
200
 
238
- # 设置自定义 API 地址
239
- $ getskill config set https://custom-api.example.com
240
- BASE_URL 已设置为: https://custom-api.example.com
201
+ # 设置自定义索引地址(需要同样提供 /data/skills.json 与 /skills/<id>.zip)
202
+ $ getskill config set https://custom-index.example.com
203
+ BASE_URL 已设置为: https://custom-index.example.com
241
204
 
242
- # 通过环境变量设置
243
- $ GETSKILL_BASE_URL=https://another-api.com getskill search commit
244
- 找到 2 个技能:
245
- ...
246
-
247
- # 验证配置
248
- $ getskill config get
249
- 当前 BASE_URL: https://custom-api.example.com
205
+ # 通过环境变量临时覆盖
206
+ $ GETSKILL_BASE_URL=https://another-index.com getskill search pdf
250
207
  ```
251
208
 
252
- ## 场景 7: 目录结构查看
209
+ ## 场景 8: 目录结构查看
253
210
 
254
211
  ```bash
255
- # 安装几个技能后查看目录结构
256
212
  $ tree ~/.openclaw
257
213
 
258
214
  ~/.openclaw/
259
215
  ├── skills/
260
- │ ├── commit-helper/
261
- │ ├── code-review/
262
- │ └── test-generator/
216
+ │ ├── pdf-extract/
217
+ │ │ └── SKILL.md
218
+ │ └── xlsx/
219
+ │ └── SKILL.md
263
220
  └── skills-cache/
264
- ├── commit-helper/
265
- │ ├── commit-helper.md
266
- │ ├── README.md
267
- │ └── .git/
268
- ├── code-review/
269
- │ ├── code-review.md
270
- │ ├── README.md
271
- │ └── .git/
272
- └── test-generator/
273
- ├── test-generator.md
274
- ├── README.md
275
- └── .git/
221
+ ├── pdf-extract/ # 解压后的技能包内容
222
+ │ └── SKILL.md
223
+ └── xlsx/
224
+ └── SKILL.md
276
225
  ```
277
226
 
278
227
  ## 常见问题
279
228
 
280
- ### Q: Git 安装后仍提示未安装?
229
+ ### Q: 还需要安装 Git 吗?
281
230
 
282
- A: Windows 用户需要重启终端或系统,以便环境变量生效。
231
+ A: 搜索、安装、更新、卸载均不需要 Git(直接 HTTP 下载 ZIP 并本地解压)。只有 `publish` 命令需要本机安装 Git。
283
232
 
284
233
  ### Q: 如何卸载技能?
285
234
 
286
- A: 直接删除 `~/.openclaw/skills/` 目录下的对应技能目录即可。
235
+ A: 使用 `getskill uninstall <技能名称>`,或直接删除 `~/.openclaw/skills/` 下对应目录。
287
236
 
288
237
  ### Q: 缓存目录可以删除吗?
289
238
 
290
- A: 可以使用 `getskill clean` 清理缓存,下次更新技能时会重新克隆。
239
+ A: 可以使用 `getskill clean` 清理缓存,下次安装/更新时会重新下载 ZIP。
291
240
 
292
- ### Q: 如何手动指定 Git 路径?
241
+ ### Q: 更新是如何判断的?
293
242
 
294
- A: 确保 `git` 命令在系统 PATH 中,或修改 `~/.bashrc` / `~/.zshrc` 添加 Git 路径。
243
+ A: 安装时会在本地记录技能版本;`update` 时拉取远端索引中的最新版本号进行比较,不一致才重新下载。