@workskills/getskill 2.1.0 → 3.0.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
@@ -2,10 +2,13 @@
2
2
 
3
3
  > 当前版本基于 `getskill.work` 静态索引 + ZIP 包下载,提供**搜索、下载(安装)、更新**三大核心功能,全部**无需 Git、无需登录**。
4
4
 
5
- ## 场景 1: 搜索并安装技能
5
+ ## 场景 1: 搜索技能 → Agent 判断 → 安装/更新
6
+
7
+ > `search` 只返回候选技能与简介(含本地安装状态),**不会自动安装任何技能**。
8
+ > 由 Agent 根据简介判断需要哪个技能,再自行执行 `install` / `update` 命令。
6
9
 
7
10
  ```bash
8
- # 搜索技能
11
+ # 第一步: 搜索技能,把候选列表与简介返回给 Agent
9
12
  $ getskill search pdf-toolkit
10
13
 
11
14
  找到 1 个技能:
@@ -14,8 +17,17 @@ $ getskill search pdf-toolkit
14
17
  描述: PDF 文档处理技能:提取文本、合并拆分、页面旋转与加水印。
15
18
  分类: 文档处理
16
19
  下载: https://getskill.work/skills/pdf-toolkit.zip
20
+ 本地: 未安装(如需要: getskill install pdf-toolkit)
21
+
22
+ 提示: search 只返回候选技能与简介,不会自动安装任何技能。
23
+ 请由 Agent 根据简介判断需要哪个技能,再自行执行 getskill install / update <技能名称>。
17
24
 
18
- # 安装技能
25
+ # 第二步: Agent 阅读简介后自行判断——
26
+ # - 简介匹配任务需求且未安装 → 执行 install
27
+ # - 已安装但版本落后(suggested_action=update)→ 执行 update
28
+ # - 同版本已安装(suggested_action=skip)或简介不匹配 → 不执行任何命令
29
+
30
+ # 第三步: Agent 决定安装后,自行运行安装命令
19
31
  $ getskill install pdf-toolkit
20
32
 
21
33
  下载技能: pdf-toolkit...
@@ -107,13 +119,19 @@ $ getskill search xlsx --json
107
119
  "version": "1.0.0",
108
120
  "category": "文档处理",
109
121
  "author": "Anthropic",
110
- "size": 173410
122
+ "size": 173410,
123
+ "installed": false,
124
+ "installed_version": null,
125
+ "suggested_action": "install"
111
126
  }
112
127
  ]
113
128
  }
114
129
  ```
115
130
 
116
- 批量安装脚本:
131
+ Agent 集成建议:把 `--json` 结果(名称 + `description` + `suggested_action`)交给 Agent,
132
+ 由 Agent 判断需要哪个技能后再执行 `getskill install/update <名称>`;search 本身不安装任何技能。
133
+
134
+ 批量安装脚本(技能清单由人工/Agent 事先选定,而非直接安装全部搜索结果):
117
135
 
118
136
  ```bash
119
137
  #!/bin/bash
@@ -144,10 +162,12 @@ const getskill = require('@workskills/getskill');
144
162
  console.log('当前索引:', getskill.getBaseUrl());
145
163
 
146
164
  // 搜索技能(基于静态索引 data/skills.json)
165
+ // 只返回候选技能与简介(含 installed/suggested_action),不会安装任何技能
147
166
  const results = await getskill.searchSkills('pdf');
148
167
  console.log('搜索结果:', results);
149
168
 
150
- // 安装技能(下载 ZIP + 本地解压 + 复制)
169
+ // 由调用方/Agent 根据简介判断后,再决定是否安装
170
+ // (示例中假定已选定 pdf-extract;下载 ZIP + 本地解压 + 复制)
151
171
  const result = await getskill.downloadSkill('pdf-extract');
152
172
  console.log('安装成功:', result.files);
153
173
 
package/README.md CHANGED
@@ -5,10 +5,11 @@ AI Agent 技能管理工具 - 从 getskill.work 搜索、下载和更新技能
5
5
  ## 功能特性
6
6
 
7
7
  - 🔍 从 `getskill.work` 静态技能索引(`data/skills.json`)搜索技能,支持 `--json` 输出
8
- - 📥 通过 HTTPS 直接下载技能 ZIP 包并在本地解压安装(**无需 Git、无需登录**)
8
+ - ⚡ 索引本地缓存(TTL 1 天):搜索优先读本地缓存,过期自动刷新,下载失败回退旧缓存(离线可搜索)
9
+ - 🧠 搜索结果标注本地安装状态(`installed` / `installed_version` / `suggested_action`),同版本已装时 `install` 自动跳过下载(`--force` 可强制重装)
10
+ - 📥 通过 HTTPS 直接下载技能 ZIP 包并在本地解压安装
9
11
  - 🔄 基于版本号比较的增量更新(`update` / `update --all`,`--prune` 可清理已下架技能的历史记录)
10
- - 🏷️ 安装/更新时可用 `--version <version>` 校验版本(站点仅提供最新版本,传入其它版本号会报错并提示当前版本)
11
- - 🤖 **不绑定任何 Agent**:内置多种 Agent 目录预设,可自动识别本机 Agent,也可指定任意自定义技能目录
12
+ - 🤖 **不绑定任何 Agent**:内置多种 Agent 目录预设,可自动识别本机 Agent
12
13
  - 💾 配置持久化到 `~/.getskill/config.json`,安装记录持久化到 `~/.getskill/state.json`(自动迁移旧版 `~/.openclaw/getskill/state.json`)
13
14
  - ⚙️ 支持环境变量与命令行参数覆盖(`GETSKILL_BASE_URL`、`GETSKILL_AGENT`、`GETSKILL_SKILLS_DIR` 等)
14
15
  - 📂 跨平台支持(Windows / macOS / Linux)
@@ -61,6 +62,8 @@ getskill agents
61
62
 
62
63
  默认 `agent = auto`:按「历史安装记录 → 已存在且非空的技能目录 → 已存在的 Agent 根目录」顺序自动识别;都识别不到时使用 `~/.claude/skills`。
63
64
 
65
+ > **安全门禁**:自动识别只是启发式猜测,可能选错 Agent(如历史记录过期、多 Agent 共存)。因此 `install` / `update` / `update --all` 要求**显式指定** `agent` 或 `skills-dir`(配置文件、`--agent`/`--skills-dir` 参数、`GETSKILL_AGENT`/`GETSKILL_SKILLS_DIR` 环境变量任一即可);若技能目录仅来自自动识别,命令会直接报错并给出设置指引,避免把技能装到非当前 Agent 的目录。`search` / `list` / `path` / `inspect` 等只读命令不受影响。
66
+
64
67
  不在预设列表中的 Agent,直接指定技能目录即可(三种方式任选一种):
65
68
 
66
69
  ```bash
@@ -106,8 +109,20 @@ getskill search <关键词> --json
106
109
  描述: PDF 文档处理技能:提取文本、合并拆分、页面旋转与加水印。当用户需要处理 PDF 文件时使用。
107
110
  分类: 文档处理
108
111
  下载: https://getskill.work/skills/pdf-toolkit.zip
112
+ 本地: 已安装 v1.0.0(同版本,无需重复安装)
109
113
  ```
110
114
 
115
+ 索引缓存与本地状态说明:
116
+
117
+ - **search 只返回候选技能与简介,不会自动安装任何技能。** 推荐的 Agent 工作流:
118
+ 1. 执行 `getskill search <关键词> --json`,把候选技能(名称 + `description` + 版本 + 本地安装状态)返回给 Agent;
119
+ 2. Agent 根据简介与任务需求自行判断需要哪个技能;
120
+ 3. Agent 决定后自行运行 `getskill install <名称>`(未安装)或 `getskill update <名称>`(已装但版本落后);同版本已装或不匹配时不执行任何命令。
121
+ - 索引缓存在 `<cache-dir>/skills-index.json`(默认 `~/.getskill/cache/skills-index.json`)。缓存时间在 1 天内时直接在本地搜索,超过 1 天自动重新下载;下载失败时回退到旧缓存,离线也能搜索。`getskill update` 会强制刷新缓存,`getskill clean` 会将其清除。
122
+ - 每条搜索结果附带本地安装状态(文本输出的“本地: …”行,`--json` 中的字段),供 Agent 决策参考:
123
+ - `installed` / `installed_version`:是否已安装到当前 Agent 的技能目录及其版本;
124
+ - `suggested_action`:`skip` = 同版本已装,无需重复安装;`update` = 已装但版本不同,可按需 `getskill update <名称>`;`install` = 未安装,可按需 `getskill install <名称>`。
125
+
111
126
  ### 安装技能
112
127
 
113
128
  ```bash
@@ -139,8 +154,14 @@ getskill install pdf-toolkit
139
154
  操作流程:
140
155
 
141
156
  1. 在静态索引中定位技能条目,获取下载地址
142
- 2. 下载 ZIP 包到缓存目录(默认 `~/.getskill/cache/<技能名称>`)并解压
143
- 3. 将技能目录复制到当前 Agent 的技能目录,并记录已安装版本
157
+ 2. 若同版本已安装(安装记录版本一致且技能目录存在),跳过下载并提示;`--force` 可强制重装
158
+ 3. 下载 ZIP 包到缓存目录(默认 `~/.getskill/cache/<技能名称>`)并解压
159
+ 4. 将技能目录复制到当前 Agent 的技能目录,并记录已安装版本
160
+
161
+ ```bash
162
+ # 强制重装(忽略“同版本已安装”的跳过逻辑)
163
+ getskill install pdf-toolkit --force
164
+ ```
144
165
 
145
166
  ### 更新技能
146
167
 
@@ -163,7 +184,7 @@ getskill update --all --prune
163
184
  更新逻辑:
164
185
 
165
186
  1. 读取本地已安装技能的版本记录(仅统计属于当前技能目录的记录)
166
- 2. 拉取远端索引中的最新版本号
187
+ 2. 强制刷新技能索引缓存,拉取远端最新版本号(`update --all` 每进程只刷新一次)
167
188
  3. 版本一致时提示“已是最新版本”;不一致时重新下载 ZIP 并覆盖安装
168
189
  4. 索引中已不存在的技能会被标记为“已跳过”,不算失败;加 `--prune` 可清理这些失效记录
169
190
 
@@ -228,7 +249,7 @@ getskill config get
228
249
  getskill clean
229
250
  ```
230
251
 
231
- 清理 ZIP 下载与解压缓存(不影响技能目录中的文件),同时清理旧版本遗留的 `~/.openclaw/skills-cache`。
252
+ 清理 ZIP 下载与解压缓存以及技能索引缓存 `skills-index.json`(不影响技能目录中的文件),同时清理旧版本遗留的 `~/.openclaw/skills-cache`。下次搜索会重新下载索引。
232
253
 
233
254
  ### 帮助与版本
234
255
 
@@ -312,7 +333,8 @@ $env:GETSKILL_SKILLS_DIR = "$HOME\.my-agent\skills"; getskill install pdf-toolki
312
333
  ├── config.json # 持久化配置
313
334
  ├── state.json # 安装记录(技能名、版本、安装目录)
314
335
  └── cache/
315
- └── pdf-toolkit/ # ZIP 解压后的技能包内容
336
+ ├── skills-index.json # 技能索引缓存(TTL 1 天)
337
+ └── pdf-toolkit/ # ZIP 解压后的技能包内容
316
338
 
317
339
  ~/.claude/skills/ # 当前 Agent 的技能目录(随 agent/skills-dir 配置变化)
318
340
  └── pdf-toolkit/
@@ -1,5 +1,6 @@
1
1
  export declare const DEFAULT_BASE_URL = "https://getskill.work";
2
2
  export declare const REQUEST_TIMEOUT_MS = 60000;
3
+ export declare const SKILLS_INDEX_CACHE_TTL_MS: number;
3
4
  export declare const MAX_COPY_FILE_SIZE_BYTES: number;
4
5
  export declare const AUTO_AGENT_NAME = "auto";
5
6
  export declare const CUSTOM_AGENT_NAME = "custom";
@@ -69,6 +70,13 @@ export declare function resolveConfig(): ResolvedConfig;
69
70
  export declare function getConfigSummary(): ResolvedConfig;
70
71
  export declare function getBaseUrl(): string;
71
72
  export declare function getSkillsDirectory(): string;
73
+ /**
74
+ * 安装/更新的安全门禁:技能目录必须显式指定
75
+ * (agent 或 skills-dir 来自 CLI 参数 / 环境变量 / 配置文件均可)。
76
+ * 若目录仅来自自动探测(detect),则拒绝写入,
77
+ * 避免把技能装到非当前 Agent 的技能目录。
78
+ */
79
+ export declare function assertExplicitSkillsDir(): ResolvedConfig;
72
80
  export declare function getSkillsCacheDirectory(): string;
73
81
  export declare function getAgentName(): string;
74
82
  export declare function getAgentLabel(): string;
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.AGENT_PRESETS = exports.DEFAULT_AGENT_NAME = exports.CUSTOM_AGENT_NAME = exports.AUTO_AGENT_NAME = exports.MAX_COPY_FILE_SIZE_BYTES = exports.REQUEST_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
6
+ exports.AGENT_PRESETS = exports.DEFAULT_AGENT_NAME = exports.CUSTOM_AGENT_NAME = exports.AUTO_AGENT_NAME = exports.MAX_COPY_FILE_SIZE_BYTES = exports.SKILLS_INDEX_CACHE_TTL_MS = exports.REQUEST_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
7
7
  exports.normalizePath = normalizePath;
8
8
  exports.isSamePath = isSamePath;
9
9
  exports.normalizeBaseUrl = normalizeBaseUrl;
@@ -25,6 +25,7 @@ exports.resolveConfig = resolveConfig;
25
25
  exports.getConfigSummary = getConfigSummary;
26
26
  exports.getBaseUrl = getBaseUrl;
27
27
  exports.getSkillsDirectory = getSkillsDirectory;
28
+ exports.assertExplicitSkillsDir = assertExplicitSkillsDir;
28
29
  exports.getSkillsCacheDirectory = getSkillsCacheDirectory;
29
30
  exports.getAgentName = getAgentName;
30
31
  exports.getAgentLabel = getAgentLabel;
@@ -43,6 +44,7 @@ const path_1 = __importDefault(require("path"));
43
44
  const system_1 = require("./system");
44
45
  exports.DEFAULT_BASE_URL = 'https://getskill.work';
45
46
  exports.REQUEST_TIMEOUT_MS = 60000;
47
+ exports.SKILLS_INDEX_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
46
48
  exports.MAX_COPY_FILE_SIZE_BYTES = 2 * 1024 * 1024;
47
49
  exports.AUTO_AGENT_NAME = 'auto';
48
50
  exports.CUSTOM_AGENT_NAME = 'custom';
@@ -406,6 +408,26 @@ function getBaseUrl() {
406
408
  function getSkillsDirectory() {
407
409
  return resolveConfig().skillsDir;
408
410
  }
411
+ /**
412
+ * 安装/更新的安全门禁:技能目录必须显式指定
413
+ * (agent 或 skills-dir 来自 CLI 参数 / 环境变量 / 配置文件均可)。
414
+ * 若目录仅来自自动探测(detect),则拒绝写入,
415
+ * 避免把技能装到非当前 Agent 的技能目录。
416
+ */
417
+ function assertExplicitSkillsDir() {
418
+ const config = resolveConfig();
419
+ if (config.sources.skillsDir !== 'detect') {
420
+ return config;
421
+ }
422
+ throw new Error([
423
+ `未能确认当前 Agent 的技能目录(自动探测结果: ${config.skillsDir}),已暂停安装/更新技能。`,
424
+ '为避免装错 Agent 目录,请先通过以下任一方式显式指定后重试:',
425
+ ' getskill config set skills-dir <技能目录> # 持久化任意目录',
426
+ ' getskill config set agent <name> # 持久化内置 Agent',
427
+ ' getskill --skills-dir <目录> install <技能名称> # 仅本次生效',
428
+ ' 或设置环境变量 GETSKILL_SKILLS_DIR / GETSKILL_AGENT'
429
+ ].join('\n'));
430
+ }
409
431
  function getSkillsCacheDirectory() {
410
432
  return resolveConfig().cacheDir;
411
433
  }
@@ -19,7 +19,8 @@ function write(level, ...args) {
19
19
  if (!shouldLog(level)) {
20
20
  return;
21
21
  }
22
- if (level === 'error') {
22
+ // error/debug 走 stderr,保证 --json 等 stdout 输出纯净
23
+ if (level === 'error' || level === 'debug') {
23
24
  console.error(...args);
24
25
  return;
25
26
  }
@@ -1,12 +1,19 @@
1
- import type { RequestOptions, RequestResponse, SearchOptions, SearchSkill, SkillIndexEntry } from './types';
1
+ import type { FetchIndexOptions, RequestOptions, RequestResponse, SearchOptions, SearchSkill, SkillIndexEntry } from './types';
2
2
  export declare function request(url: string, options?: RequestOptions, redirectCount?: number): Promise<RequestResponse>;
3
3
  export declare function downloadFile(url: string, destPath: string, redirectCount?: number): Promise<number>;
4
4
  export declare function getSkillsIndexUrl(): string;
5
5
  export declare function getSkillPackageUrl(entry: SkillIndexEntry): string;
6
- export declare function fetchSkillsIndex(): Promise<SkillIndexEntry[]>;
6
+ export declare function getSkillsIndexCacheFilePath(): string;
7
+ /** 删除本地索引缓存并重置进程内刷新标记(clean / 测试使用)。 */
8
+ export declare function clearSkillsIndexCache(): void;
9
+ /**
10
+ * 获取技能索引:优先使用本地缓存(TTL 1 天),过期或强制刷新时重新下载;
11
+ * 下载失败但存在旧缓存时回退到旧缓存,保证离线可用。
12
+ */
13
+ export declare function fetchSkillsIndex(options?: FetchIndexOptions): Promise<SkillIndexEntry[]>;
7
14
  export declare function normalizeSkillIndexKey(skillName: string): string;
8
15
  export declare function filterIndexByKeyword(entries: SkillIndexEntry[], keyword: string, limit?: number, page?: number): SkillIndexEntry[];
9
16
  export declare function mapIndexEntryToSearchSkill(entry: SkillIndexEntry): SearchSkill;
10
- export declare function findSkillIndexEntry(skillName: string): Promise<SkillIndexEntry | null>;
17
+ export declare function findSkillIndexEntry(skillName: string, options?: FetchIndexOptions): Promise<SkillIndexEntry | null>;
11
18
  export declare function repositoryHasSkillFile(skillName: string): Promise<boolean>;
12
19
  export declare function searchSkills(keyword: string, options?: SearchOptions): Promise<SearchSkill[]>;
@@ -7,6 +7,8 @@ exports.request = request;
7
7
  exports.downloadFile = downloadFile;
8
8
  exports.getSkillsIndexUrl = getSkillsIndexUrl;
9
9
  exports.getSkillPackageUrl = getSkillPackageUrl;
10
+ exports.getSkillsIndexCacheFilePath = getSkillsIndexCacheFilePath;
11
+ exports.clearSkillsIndexCache = clearSkillsIndexCache;
10
12
  exports.fetchSkillsIndex = fetchSkillsIndex;
11
13
  exports.normalizeSkillIndexKey = normalizeSkillIndexKey;
12
14
  exports.filterIndexByKeyword = filterIndexByKeyword;
@@ -17,8 +19,11 @@ exports.searchSkills = searchSkills;
17
19
  const fs_1 = __importDefault(require("fs"));
18
20
  const http_1 = __importDefault(require("http"));
19
21
  const https_1 = __importDefault(require("https"));
22
+ const path_1 = __importDefault(require("path"));
20
23
  const config_1 = require("./config");
21
24
  const logger_1 = __importDefault(require("./logger"));
25
+ const state_1 = require("./state");
26
+ const system_1 = require("./system");
22
27
  function request(url, options = {}, redirectCount = 0) {
23
28
  const MAX_REDIRECTS = 5;
24
29
  return new Promise((resolve, reject) => {
@@ -223,7 +228,56 @@ function getSkillPackageUrl(entry) {
223
228
  }
224
229
  return `${(0, config_1.getBaseUrl)()}/${file.replace(/^\/+/, '')}`;
225
230
  }
226
- async function fetchSkillsIndex() {
231
+ /** 本进程内是否已下载过索引,避免 update --all 逐个技能重复强制刷新。 */
232
+ let indexDownloadedInProcess = false;
233
+ function getSkillsIndexCacheFilePath() {
234
+ return path_1.default.join((0, config_1.getSkillsCacheDirectory)(), 'skills-index.json');
235
+ }
236
+ function readSkillsIndexCache() {
237
+ const cacheFile = getSkillsIndexCacheFilePath();
238
+ if (!fs_1.default.existsSync(cacheFile)) {
239
+ return null;
240
+ }
241
+ try {
242
+ const parsed = JSON.parse(fs_1.default.readFileSync(cacheFile, 'utf8'));
243
+ if (!parsed ||
244
+ parsed.baseUrl !== (0, config_1.getBaseUrl)() ||
245
+ typeof parsed.fetchedAt !== 'string' ||
246
+ !Number.isFinite(Date.parse(parsed.fetchedAt)) ||
247
+ !Array.isArray(parsed.skills)) {
248
+ return null;
249
+ }
250
+ return parsed;
251
+ }
252
+ catch {
253
+ return null;
254
+ }
255
+ }
256
+ function writeSkillsIndexCache(skills) {
257
+ try {
258
+ const cacheFile = getSkillsIndexCacheFilePath();
259
+ (0, system_1.ensureDirectoryExists)(path_1.default.dirname(cacheFile));
260
+ const payload = {
261
+ baseUrl: (0, config_1.getBaseUrl)(),
262
+ fetchedAt: new Date().toISOString(),
263
+ skills
264
+ };
265
+ fs_1.default.writeFileSync(cacheFile, JSON.stringify(payload, null, 2), 'utf8');
266
+ }
267
+ catch (error) {
268
+ const message = error instanceof Error ? error.message : String(error);
269
+ logger_1.default.warn(`技能索引缓存写入失败(不影响本次结果): ${message}`);
270
+ }
271
+ }
272
+ /** 删除本地索引缓存并重置进程内刷新标记(clean / 测试使用)。 */
273
+ function clearSkillsIndexCache() {
274
+ indexDownloadedInProcess = false;
275
+ const cacheFile = getSkillsIndexCacheFilePath();
276
+ if (fs_1.default.existsSync(cacheFile)) {
277
+ fs_1.default.rmSync(cacheFile, { force: true });
278
+ }
279
+ }
280
+ async function downloadSkillsIndex() {
227
281
  const url = getSkillsIndexUrl();
228
282
  const response = await request(url, { timeout: config_1.REQUEST_TIMEOUT_MS });
229
283
  if (!response.body || response.body.trim() === '') {
@@ -246,6 +300,38 @@ async function fetchSkillsIndex() {
246
300
  typeof entry.file === 'string' &&
247
301
  entry.file.trim() !== '');
248
302
  }
303
+ /**
304
+ * 获取技能索引:优先使用本地缓存(TTL 1 天),过期或强制刷新时重新下载;
305
+ * 下载失败但存在旧缓存时回退到旧缓存,保证离线可用。
306
+ */
307
+ async function fetchSkillsIndex(options = {}) {
308
+ const cache = readSkillsIndexCache();
309
+ const cacheAgeMs = cache
310
+ ? Date.now() - Date.parse(cache.fetchedAt)
311
+ : Number.POSITIVE_INFINITY;
312
+ const cacheFresh = Boolean(cache) &&
313
+ cacheAgeMs >= 0 &&
314
+ cacheAgeMs < config_1.SKILLS_INDEX_CACHE_TTL_MS;
315
+ const mustRefresh = options.forceRefresh === true && !indexDownloadedInProcess;
316
+ if (cache && cacheFresh && !mustRefresh) {
317
+ logger_1.default.debug(`使用本地技能索引缓存: ${getSkillsIndexCacheFilePath()} (${cache?.fetchedAt})`);
318
+ return cache.skills;
319
+ }
320
+ try {
321
+ const skills = await downloadSkillsIndex();
322
+ writeSkillsIndexCache(skills);
323
+ indexDownloadedInProcess = true;
324
+ return skills;
325
+ }
326
+ catch (error) {
327
+ if (cache) {
328
+ const message = error instanceof Error ? error.message : String(error);
329
+ logger_1.default.warn(`技能索引下载失败,回退到本地缓存 (${cache.fetchedAt}): ${message}`);
330
+ return cache.skills;
331
+ }
332
+ throw error;
333
+ }
334
+ }
249
335
  function normalizeSkillIndexKey(skillName) {
250
336
  return skillName
251
337
  .trim()
@@ -293,10 +379,13 @@ function mapIndexEntryToSearchSkill(entry) {
293
379
  version: entry.version || 'unknown',
294
380
  category: entry.category || '',
295
381
  author: entry.author || '',
296
- size: typeof entry.size === 'number' ? entry.size : 0
382
+ size: typeof entry.size === 'number' ? entry.size : 0,
383
+ installed: false,
384
+ installed_version: null,
385
+ suggested_action: 'install'
297
386
  };
298
387
  }
299
- async function findSkillIndexEntry(skillName) {
388
+ async function findSkillIndexEntry(skillName, options = {}) {
300
389
  if (!skillName || typeof skillName !== 'string') {
301
390
  return null;
302
391
  }
@@ -304,7 +393,7 @@ async function findSkillIndexEntry(skillName) {
304
393
  if (!normalized) {
305
394
  return null;
306
395
  }
307
- const entries = await fetchSkillsIndex();
396
+ const entries = await fetchSkillsIndex(options);
308
397
  return (entries.find((entry) => normalizeSkillIndexKey(entry.id) === normalized ||
309
398
  normalizeSkillIndexKey(entry.name || '') === normalized) || null);
310
399
  }
@@ -337,7 +426,25 @@ async function searchSkills(keyword, options = {}) {
337
426
  try {
338
427
  const entries = await fetchSkillsIndex();
339
428
  const matched = filterIndexByKeyword(entries, keyword, limit, page);
340
- return matched.map(mapIndexEntryToSearchSkill);
429
+ const installedByKey = new Map();
430
+ (0, state_1.getInstalledSkillsSnapshot)().forEach((item) => {
431
+ installedByKey.set(normalizeSkillIndexKey(item.skillName), item);
432
+ installedByKey.set(normalizeSkillIndexKey(item.localSkillName), item);
433
+ });
434
+ return matched.map((entry) => {
435
+ const skill = mapIndexEntryToSearchSkill(entry);
436
+ const local = installedByKey.get(normalizeSkillIndexKey(entry.id)) ||
437
+ installedByKey.get(normalizeSkillIndexKey(entry.name || '')) ||
438
+ null;
439
+ skill.installed = Boolean(local);
440
+ skill.installed_version = local?.version ?? null;
441
+ skill.suggested_action = !local
442
+ ? 'install'
443
+ : local.version && local.version === entry.version
444
+ ? 'skip'
445
+ : 'update';
446
+ return skill;
447
+ });
341
448
  }
342
449
  catch (error) {
343
450
  const message = error instanceof Error ? error.message : String(error);
@@ -78,10 +78,36 @@ async function restartAgentGateway() {
78
78
  }
79
79
  }
80
80
  async function downloadSkill(skillName, options = {}) {
81
+ (0, config_1.assertExplicitSkillsDir)();
81
82
  logger_1.default.info(`下载技能: ${skillName}...`);
82
83
  const normalizedSkillName = (0, state_1.normalizeCliSkillArgument)(skillName);
83
84
  const requestedVersion = options.version?.trim();
84
- const { repoPath, entry } = await fetchSkillToCache(normalizedSkillName, {
85
+ const entry = await (0, network_1.findSkillIndexEntry)(normalizedSkillName);
86
+ if (!entry) {
87
+ throw new Error(`技能不存在: ${normalizedSkillName},请先使用 getskill search <关键词> 查询可用技能`);
88
+ }
89
+ assertVersionAvailable(entry, requestedVersion);
90
+ // 同版本已安装时跳过重复下载(--force 可强制重装)
91
+ const localSkillName = (0, state_1.normalizeSkillName)(normalizedSkillName);
92
+ const skillDir = path_1.default.join((0, config_1.getSkillsDirectory)(), localSkillName);
93
+ const record = (0, state_1.readInstallState)().skills[localSkillName];
94
+ if (options.force !== true &&
95
+ record &&
96
+ record.version &&
97
+ record.version === entry.version &&
98
+ fs_1.default.existsSync(skillDir)) {
99
+ logger_1.default.info(`技能 ${normalizedSkillName} 已安装且为最新版本 (${entry.version}),跳过重复安装。如需强制重装请使用 --force`);
100
+ return {
101
+ skillName: normalizedSkillName,
102
+ repoPath: record.repoPath ||
103
+ path_1.default.join((0, config_1.getSkillsCacheDirectory)(), localSkillName),
104
+ files: [skillDir],
105
+ requestedVersion: requestedVersion || null,
106
+ version: entry.version,
107
+ upToDate: true
108
+ };
109
+ }
110
+ const { repoPath } = await fetchSkillToCache(normalizedSkillName, {
85
111
  version: requestedVersion
86
112
  });
87
113
  const copiedFiles = (0, state_1.copySkillFiles)(repoPath, normalizedSkillName);
@@ -96,10 +122,14 @@ async function downloadSkill(skillName, options = {}) {
96
122
  };
97
123
  }
98
124
  async function updateSkill(skillName, options = {}) {
125
+ (0, config_1.assertExplicitSkillsDir)();
99
126
  const normalizedSkillName = (0, state_1.normalizeCliSkillArgument)(skillName);
100
127
  const requestedVersion = options.version?.trim();
101
128
  logger_1.default.info(`正在更新技能: ${normalizedSkillName}...`);
102
- const entry = await (0, network_1.findSkillIndexEntry)(normalizedSkillName);
129
+ // update 语义是检查在线最新版本,强制刷新索引(每进程最多一次下载)
130
+ const entry = await (0, network_1.findSkillIndexEntry)(normalizedSkillName, {
131
+ forceRefresh: true
132
+ });
103
133
  if (!entry) {
104
134
  throw new Error(`技能不存在: ${normalizedSkillName},无法更新`);
105
135
  }
@@ -140,15 +170,16 @@ async function updateSkill(skillName, options = {}) {
140
170
  };
141
171
  }
142
172
  async function updateAllSkills(options = {}) {
173
+ (0, config_1.assertExplicitSkillsDir)();
143
174
  const installedSkills = (0, state_1.listInstalledSkillNames)();
144
175
  const results = [];
145
176
  if (installedSkills.length === 0) {
146
177
  return results;
147
178
  }
148
- // 一次性拉取索引,用于识别已下架/改名的历史安装记录
179
+ // 一次性拉取最新索引,用于识别已下架/改名的历史安装记录
149
180
  let indexKeys = null;
150
181
  try {
151
- const entries = await (0, network_1.fetchSkillsIndex)();
182
+ const entries = await (0, network_1.fetchSkillsIndex)({ forceRefresh: true });
152
183
  indexKeys = new Set();
153
184
  entries.forEach((entry) => {
154
185
  indexKeys?.add((0, network_1.normalizeSkillIndexKey)(entry.id));
@@ -1,4 +1,4 @@
1
- import type { InstallState, InstalledSkillInfo, RemoveInstalledSkillResult } from './types';
1
+ import type { InstalledSkillSnapshot, InstallState, InstalledSkillInfo, RemoveInstalledSkillResult } from './types';
2
2
  export declare function normalizeSkillName(skillName: string): string;
3
3
  export declare function getRemoteSkillPath(skillName: string): string;
4
4
  export declare function normalizeCliSkillArgument(rawSkillName: string): string;
@@ -16,6 +16,11 @@ export declare function copyDirectoryRecursive(sourceDir: string, targetDir: str
16
16
  export declare function replaceDirectoryAtomically(sourceDir: string, targetDir: string): void;
17
17
  export declare function copySkillFiles(repoPath: string, skillName: string): string[];
18
18
  export declare function listLocalSkills(): string[];
19
+ /**
20
+ * 当前技能目录下真实存在安装目录的技能快照(含版本),
21
+ * 用于搜索结果标注本地安装状态。
22
+ */
23
+ export declare function getInstalledSkillsSnapshot(): InstalledSkillSnapshot[];
19
24
  export declare function listInstalledSkillNames(): string[];
20
25
  /**
21
26
  * 清理状态文件中的失效记录。
package/dist/lib/state.js CHANGED
@@ -16,6 +16,7 @@ exports.copyDirectoryRecursive = copyDirectoryRecursive;
16
16
  exports.replaceDirectoryAtomically = replaceDirectoryAtomically;
17
17
  exports.copySkillFiles = copySkillFiles;
18
18
  exports.listLocalSkills = listLocalSkills;
19
+ exports.getInstalledSkillsSnapshot = getInstalledSkillsSnapshot;
19
20
  exports.listInstalledSkillNames = listInstalledSkillNames;
20
21
  exports.pruneInstallState = pruneInstallState;
21
22
  exports.getInstalledSkillInfo = getInstalledSkillInfo;
@@ -101,7 +102,8 @@ function migrateLegacyInstallState() {
101
102
  const content = fs_1.default.readFileSync(legacyPath, 'utf8');
102
103
  (0, system_1.ensureDirectoryExists)(path_1.default.dirname(stateFilePath));
103
104
  fs_1.default.writeFileSync(stateFilePath, content, 'utf8');
104
- logger_1.default.info(`已迁移历史安装记录: ${legacyPath} -> ${stateFilePath}`);
105
+ // debug 级别(stderr),避免污染 search --json 的 stdout
106
+ logger_1.default.debug(`已迁移历史安装记录: ${legacyPath} -> ${stateFilePath}`);
105
107
  return legacyPath;
106
108
  }
107
109
  catch (error) {
@@ -259,6 +261,23 @@ function recordMatchesCurrentSkillsDir(record) {
259
261
  }
260
262
  return (0, config_1.isSamePath)(recordDir, (0, config_1.getSkillsDirectory)());
261
263
  }
264
+ /**
265
+ * 当前技能目录下真实存在安装目录的技能快照(含版本),
266
+ * 用于搜索结果标注本地安装状态。
267
+ */
268
+ function getInstalledSkillsSnapshot() {
269
+ const state = readInstallState();
270
+ const skillsDir = (0, config_1.getSkillsDirectory)();
271
+ return Object.values(state.skills)
272
+ .filter(recordMatchesCurrentSkillsDir)
273
+ .map((record) => ({
274
+ skillName: record.inputSkillName || record.localSkillName,
275
+ localSkillName: record.localSkillName,
276
+ version: record.version || null,
277
+ skillDir: record.installDir || path_1.default.join(skillsDir, record.localSkillName)
278
+ }))
279
+ .filter((item) => fs_1.default.existsSync(item.skillDir));
280
+ }
262
281
  function listInstalledSkillNames() {
263
282
  const state = readInstallState();
264
283
  const stateNames = Object.values(state.skills)
@@ -50,6 +50,22 @@ export interface SearchSkill {
50
50
  category: string;
51
51
  author: string;
52
52
  size: number;
53
+ /** 是否已安装到当前 Agent 的技能目录。 */
54
+ installed: boolean;
55
+ /** 本地已安装版本(未安装或无版本记录时为 null)。 */
56
+ installed_version: string | null;
57
+ /** 建议动作: skip=同版本已装, update=已装但版本不同, install=未安装。 */
58
+ suggested_action: 'install' | 'update' | 'skip';
59
+ }
60
+ export interface InstalledSkillSnapshot {
61
+ skillName: string;
62
+ localSkillName: string;
63
+ version: string | null;
64
+ skillDir: string;
65
+ }
66
+ export interface FetchIndexOptions {
67
+ /** 忽略缓存 TTL 强制刷新(每进程最多触发一次下载)。 */
68
+ forceRefresh?: boolean;
53
69
  }
54
70
  export interface SkillStateRecord {
55
71
  inputSkillName: string;
@@ -79,6 +95,8 @@ export interface DownloadResult {
79
95
  }
80
96
  export interface DownloadOptions {
81
97
  version?: string;
98
+ /** 同版本已安装时仍强制重新下载安装。 */
99
+ force?: boolean;
82
100
  }
83
101
  export interface UpdateAllOptions {
84
102
  /** 同时清理索引中已不存在的历史安装记录。 */
package/dist/main.js CHANGED
@@ -98,6 +98,7 @@ function printHelp() {
98
98
  console.log(' getskill search <关键词> --json - JSON 格式输出搜索结果');
99
99
  console.log(' getskill install <技能名称> - 通过 HTTPS 下载 zip 包安装技能');
100
100
  console.log(' getskill install <技能名称> --version <tag> - 安装指定版本(需与站点当前版本一致)');
101
+ console.log(' getskill install <技能名称> --force - 强制重装(同版本已安装时默认跳过下载)');
101
102
  console.log(' getskill update <技能名称> - 检查在线版本并更新技能');
102
103
  console.log(' getskill update <技能名称> --version <tag> - 更新到指定版本');
103
104
  console.log(' getskill update --all - 批量更新所有已安装技能');
@@ -112,6 +113,12 @@ function printHelp() {
112
113
  console.log(' getskill config unset <key> - 删除配置项,恢复自动识别/默认值');
113
114
  console.log(' getskill clean - 清理下载缓存');
114
115
  console.log('');
116
+ console.log('注意: install/update 需要显式指定 agent 或 skills-dir(配置/参数/环境变量);');
117
+ console.log(' 技能目录仅来自自动识别时会报错,以避免安装到非当前 Agent 的目录。');
118
+ console.log('说明: 技能索引缓存在 <cache-dir>/skills-index.json,1 天内搜索直接使用本地缓存;');
119
+ console.log(' 搜索结果附带本地安装状态 (installed/installed_version/suggested_action)。');
120
+ console.log(' search 只返回候选技能与简介,不会自动安装;由 Agent 判断后自行执行 install/update。');
121
+ console.log('');
115
122
  console.log('全局参数(仅对本次执行生效,不写入配置文件):');
116
123
  console.log(` --agent <name> 指定目标 Agent: auto, ${config_1.AGENT_PRESETS.map((preset) => preset.name).join(', ')}`);
117
124
  console.log(' --skills-dir <path> 指定任意 Agent 的技能目录');
@@ -392,8 +399,19 @@ async function cli() {
392
399
  if (skill.download_url) {
393
400
  console.log(` 下载: ${skill.download_url}`);
394
401
  }
402
+ if (!skill.installed) {
403
+ console.log(` 本地: 未安装(如需要: getskill install ${skill.full_name})`);
404
+ }
405
+ else if (skill.suggested_action === 'skip') {
406
+ console.log(` 本地: 已安装 v${skill.installed_version || 'unknown'}(同版本,无需重复安装)`);
407
+ }
408
+ else {
409
+ console.log(` 本地: 已安装 v${skill.installed_version || 'unknown'}(如需要: getskill update ${skill.full_name})`);
410
+ }
395
411
  console.log('');
396
412
  });
413
+ console.log('提示: search 只返回候选技能与简介,不会自动安装任何技能。');
414
+ console.log(' 请由 Agent 根据简介判断需要哪个技能,再自行执行 getskill install / update <技能名称>。');
397
415
  break;
398
416
  }
399
417
  case 'install':
@@ -410,8 +428,14 @@ async function cli() {
410
428
  process.exit(1);
411
429
  }
412
430
  const result = await (0, skill_manager_1.downloadSkill)(skillName, {
413
- version: requestedVersion
431
+ version: requestedVersion,
432
+ force: options.force === true
414
433
  });
434
+ if (result.upToDate) {
435
+ console.log(`\n技能已安装且为最新版本 (v${result.version || 'unknown'}),已跳过重复安装。`);
436
+ console.log('如需强制重装: getskill install <技能名称> --force');
437
+ break;
438
+ }
415
439
  console.log(`\n目标 Agent: ${(0, config_1.getAgentName)()} (${(0, config_1.getAgentLabel)()})`);
416
440
  console.log('技能已安装到 skills 目录:');
417
441
  result.files.forEach((file) => console.log(` - ${file}`));
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@workskills/getskill",
3
3
  "description": "A skill management CLI for any AI agent (Claude Code, OpenClaw, Codex, Cursor, or a custom skills directory) that searches, installs, and updates skill files from the getskill.work registry",
4
- "version": "2.1.0",
4
+ "version": "3.0.0",
5
5
  "main": "dist/main.js",
6
6
  "types": "dist/main.d.ts",
7
7
  "bin": {