@workskills/getskill 2.0.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.
@@ -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);
@@ -1,4 +1,4 @@
1
- import type { DownloadOptions, DownloadResult, RemoveInstalledSkillResult, SkillIndexEntry, UpdateAllResult } from './types';
1
+ import type { DownloadOptions, DownloadResult, RemoveInstalledSkillResult, SkillIndexEntry, UpdateAllOptions, UpdateAllResult } from './types';
2
2
  export interface FetchSkillToCacheResult {
3
3
  repoPath: string;
4
4
  cachePath: string;
@@ -6,10 +6,14 @@ export interface FetchSkillToCacheResult {
6
6
  }
7
7
  export declare function fetchSkillToCache(skillName: string, options?: DownloadOptions): Promise<FetchSkillToCacheResult>;
8
8
  export declare function cloneOrUpdateRepo(skillName: string, options?: DownloadOptions): Promise<string>;
9
- export declare function restartOpenClawGateway(): Promise<void>;
9
+ /**
10
+ * 安装/更新后的可选 Agent 重载钩子。
11
+ * 仅当 Agent 预设定义了重启命令,或设置了 `GETSKILL_RESTART_CMD` 时才执行。
12
+ */
13
+ export declare function restartAgentGateway(): Promise<void>;
10
14
  export declare function downloadSkill(skillName: string, options?: DownloadOptions): Promise<DownloadResult>;
11
15
  export declare function updateSkill(skillName: string, options?: DownloadOptions): Promise<DownloadResult>;
12
- export declare function updateAllSkills(): Promise<UpdateAllResult[]>;
16
+ export declare function updateAllSkills(options?: UpdateAllOptions): Promise<UpdateAllResult[]>;
13
17
  export declare function uninstallSkill(skillName: string, options?: {
14
18
  removeCache?: boolean;
15
19
  }): Promise<RemoveInstalledSkillResult>;
@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.fetchSkillToCache = fetchSkillToCache;
7
7
  exports.cloneOrUpdateRepo = cloneOrUpdateRepo;
8
- exports.restartOpenClawGateway = restartOpenClawGateway;
8
+ exports.restartAgentGateway = restartAgentGateway;
9
9
  exports.downloadSkill = downloadSkill;
10
10
  exports.updateSkill = updateSkill;
11
11
  exports.updateAllSkills = updateAllSkills;
@@ -57,24 +57,57 @@ async function cloneOrUpdateRepo(skillName, options = {}) {
57
57
  const { repoPath } = await fetchSkillToCache(skillName, options);
58
58
  return repoPath;
59
59
  }
60
- async function restartOpenClawGateway() {
61
- const restartCommand = 'openclaw gateway restart';
60
+ /**
61
+ * 安装/更新后的可选 Agent 重载钩子。
62
+ * 仅当 Agent 预设定义了重启命令,或设置了 `GETSKILL_RESTART_CMD` 时才执行。
63
+ */
64
+ async function restartAgentGateway() {
65
+ const restartCommand = (0, config_1.getAgentRestartCommand)();
66
+ if (!restartCommand) {
67
+ return;
68
+ }
62
69
  logger_1.default.info(`尝试执行: ${restartCommand}`);
63
70
  try {
64
71
  await (0, system_1.executeCommand)(restartCommand);
65
- logger_1.default.info('OpenClaw Gateway 重启成功,新技能应已生效。');
72
+ logger_1.default.info('Agent 服务重启成功,新技能应已生效。');
66
73
  }
67
74
  catch (error) {
68
75
  const message = error instanceof Error ? error.message : String(error);
69
- logger_1.default.warn('自动重启 OpenClaw Gateway 失败,请手动执行: openclaw gateway restart');
76
+ logger_1.default.warn(`自动执行 "${restartCommand}" 失败,请手动重启 Agent 以加载新技能。`);
70
77
  logger_1.default.warn(`失败原因: ${message}`);
71
78
  }
72
79
  }
73
80
  async function downloadSkill(skillName, options = {}) {
81
+ (0, config_1.assertExplicitSkillsDir)();
74
82
  logger_1.default.info(`下载技能: ${skillName}...`);
75
83
  const normalizedSkillName = (0, state_1.normalizeCliSkillArgument)(skillName);
76
84
  const requestedVersion = options.version?.trim();
77
- 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, {
78
111
  version: requestedVersion
79
112
  });
80
113
  const copiedFiles = (0, state_1.copySkillFiles)(repoPath, normalizedSkillName);
@@ -89,10 +122,14 @@ async function downloadSkill(skillName, options = {}) {
89
122
  };
90
123
  }
91
124
  async function updateSkill(skillName, options = {}) {
125
+ (0, config_1.assertExplicitSkillsDir)();
92
126
  const normalizedSkillName = (0, state_1.normalizeCliSkillArgument)(skillName);
93
127
  const requestedVersion = options.version?.trim();
94
128
  logger_1.default.info(`正在更新技能: ${normalizedSkillName}...`);
95
- const entry = await (0, network_1.findSkillIndexEntry)(normalizedSkillName);
129
+ // update 语义是检查在线最新版本,强制刷新索引(每进程最多一次下载)
130
+ const entry = await (0, network_1.findSkillIndexEntry)(normalizedSkillName, {
131
+ forceRefresh: true
132
+ });
96
133
  if (!entry) {
97
134
  throw new Error(`技能不存在: ${normalizedSkillName},无法更新`);
98
135
  }
@@ -132,17 +169,59 @@ async function updateSkill(skillName, options = {}) {
132
169
  version: entry.version
133
170
  };
134
171
  }
135
- async function updateAllSkills() {
172
+ async function updateAllSkills(options = {}) {
173
+ (0, config_1.assertExplicitSkillsDir)();
136
174
  const installedSkills = (0, state_1.listInstalledSkillNames)();
137
175
  const results = [];
176
+ if (installedSkills.length === 0) {
177
+ return results;
178
+ }
179
+ // 一次性拉取最新索引,用于识别已下架/改名的历史安装记录
180
+ let indexKeys = null;
181
+ try {
182
+ const entries = await (0, network_1.fetchSkillsIndex)({ forceRefresh: true });
183
+ indexKeys = new Set();
184
+ entries.forEach((entry) => {
185
+ indexKeys?.add((0, network_1.normalizeSkillIndexKey)(entry.id));
186
+ if (entry.name) {
187
+ indexKeys?.add((0, network_1.normalizeSkillIndexKey)(entry.name));
188
+ }
189
+ });
190
+ }
191
+ catch (error) {
192
+ const message = error instanceof Error ? error.message : String(error);
193
+ logger_1.default.warn(`技能索引获取失败,将逐个尝试更新: ${message}`);
194
+ }
195
+ const staleSkillNames = [];
138
196
  for (const skillName of installedSkills) {
197
+ const missingInIndex = Boolean(indexKeys && !indexKeys.has((0, network_1.normalizeSkillIndexKey)(skillName)));
198
+ if (missingInIndex) {
199
+ staleSkillNames.push(skillName);
200
+ results.push({
201
+ skillName,
202
+ ok: false,
203
+ skipped: true,
204
+ error: '技能索引中已不存在该技能(历史安装记录失效)'
205
+ });
206
+ continue;
207
+ }
139
208
  try {
140
209
  const result = await updateSkill(skillName);
141
210
  results.push({ skillName, ok: true, result });
142
211
  }
143
212
  catch (error) {
144
213
  const message = error instanceof Error ? error.message : String(error);
145
- results.push({ skillName, ok: false, error: message });
214
+ const skipped = message.includes('技能不存在');
215
+ if (skipped) {
216
+ staleSkillNames.push(skillName);
217
+ }
218
+ results.push({ skillName, ok: false, skipped, error: message });
219
+ }
220
+ }
221
+ if (options.prune && staleSkillNames.length > 0) {
222
+ const pruned = (0, state_1.pruneInstallState)(staleSkillNames);
223
+ if (pruned.length > 0) {
224
+ logger_1.default.info(`已清理失效安装记录: ${pruned.join(', ')}`);
146
225
  }
147
226
  }
148
227
  return results;
@@ -1,8 +1,13 @@
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;
5
5
  export declare function collectSkillMarkdownFiles(dirPath: string, baseDir?: string, result?: string[]): string[];
6
+ /**
7
+ * 兼容 1.x/2.0 版本:状态文件曾存放在 `<agent 根目录>/getskill/state.json`。
8
+ * 首次读取时自动迁移到 `~/.getskill/state.json`。
9
+ */
10
+ export declare function migrateLegacyInstallState(): string | null;
6
11
  export declare function readInstallState(): InstallState;
7
12
  export declare function writeInstallState(state: InstallState): void;
8
13
  export declare function updateInstallState(skillName: string, repoPath: string, installDir: string, action: 'install' | 'update', requestedVersion?: string, version?: string): Promise<void>;
@@ -11,7 +16,18 @@ export declare function copyDirectoryRecursive(sourceDir: string, targetDir: str
11
16
  export declare function replaceDirectoryAtomically(sourceDir: string, targetDir: string): void;
12
17
  export declare function copySkillFiles(repoPath: string, skillName: string): string[];
13
18
  export declare function listLocalSkills(): string[];
19
+ /**
20
+ * 当前技能目录下真实存在安装目录的技能快照(含版本),
21
+ * 用于搜索结果标注本地安装状态。
22
+ */
23
+ export declare function getInstalledSkillsSnapshot(): InstalledSkillSnapshot[];
14
24
  export declare function listInstalledSkillNames(): string[];
25
+ /**
26
+ * 清理状态文件中的失效记录。
27
+ * 不传参数时清理不属于当前技能目录(Agent)的记录,
28
+ * 传入技能名时只清理指定记录。返回被清理的技能名列表。
29
+ */
30
+ export declare function pruneInstallState(skillNames?: string[]): string[];
15
31
  export declare function getInstalledSkillInfo(skillName: string): InstalledSkillInfo;
16
32
  export declare function removeInstalledSkill(skillName: string, options?: {
17
33
  removeCache?: boolean;
package/dist/lib/state.js CHANGED
@@ -7,6 +7,7 @@ exports.normalizeSkillName = normalizeSkillName;
7
7
  exports.getRemoteSkillPath = getRemoteSkillPath;
8
8
  exports.normalizeCliSkillArgument = normalizeCliSkillArgument;
9
9
  exports.collectSkillMarkdownFiles = collectSkillMarkdownFiles;
10
+ exports.migrateLegacyInstallState = migrateLegacyInstallState;
10
11
  exports.readInstallState = readInstallState;
11
12
  exports.writeInstallState = writeInstallState;
12
13
  exports.updateInstallState = updateInstallState;
@@ -15,7 +16,9 @@ exports.copyDirectoryRecursive = copyDirectoryRecursive;
15
16
  exports.replaceDirectoryAtomically = replaceDirectoryAtomically;
16
17
  exports.copySkillFiles = copySkillFiles;
17
18
  exports.listLocalSkills = listLocalSkills;
19
+ exports.getInstalledSkillsSnapshot = getInstalledSkillsSnapshot;
18
20
  exports.listInstalledSkillNames = listInstalledSkillNames;
21
+ exports.pruneInstallState = pruneInstallState;
19
22
  exports.getInstalledSkillInfo = getInstalledSkillInfo;
20
23
  exports.removeInstalledSkill = removeInstalledSkill;
21
24
  const fs_1 = __importDefault(require("fs"));
@@ -23,6 +26,7 @@ const path_1 = __importDefault(require("path"));
23
26
  const config_1 = require("./config");
24
27
  const logger_1 = __importDefault(require("./logger"));
25
28
  const system_1 = require("./system");
29
+ const unzip_1 = require("./unzip");
26
30
  function normalizeSkillName(skillName) {
27
31
  return skillName.replace(/^skills\//, '').replace(/[\\/]/g, '_');
28
32
  }
@@ -65,13 +69,8 @@ function collectSkillMarkdownFiles(dirPath, baseDir = dirPath, result = []) {
65
69
  });
66
70
  return result;
67
71
  }
68
- function readInstallState() {
69
- const stateFilePath = (0, config_1.getStateFilePath)();
70
- if (!fs_1.default.existsSync(stateFilePath)) {
71
- return { skills: {} };
72
- }
72
+ function parseInstallState(content) {
73
73
  try {
74
- const content = fs_1.default.readFileSync(stateFilePath, 'utf8');
75
74
  const parsed = JSON.parse(content);
76
75
  if (!parsed || typeof parsed !== 'object') {
77
76
  return { skills: {} };
@@ -86,6 +85,48 @@ function readInstallState() {
86
85
  return { skills: {} };
87
86
  }
88
87
  }
88
+ /**
89
+ * 兼容 1.x/2.0 版本:状态文件曾存放在 `<agent 根目录>/getskill/state.json`。
90
+ * 首次读取时自动迁移到 `~/.getskill/state.json`。
91
+ */
92
+ function migrateLegacyInstallState() {
93
+ const stateFilePath = (0, config_1.getStateFilePath)();
94
+ if (fs_1.default.existsSync(stateFilePath)) {
95
+ return null;
96
+ }
97
+ for (const legacyPath of (0, config_1.getLegacyStateFilePaths)()) {
98
+ if (!fs_1.default.existsSync(legacyPath)) {
99
+ continue;
100
+ }
101
+ try {
102
+ const content = fs_1.default.readFileSync(legacyPath, 'utf8');
103
+ (0, system_1.ensureDirectoryExists)(path_1.default.dirname(stateFilePath));
104
+ fs_1.default.writeFileSync(stateFilePath, content, 'utf8');
105
+ // debug 级别(stderr),避免污染 search --json 的 stdout
106
+ logger_1.default.debug(`已迁移历史安装记录: ${legacyPath} -> ${stateFilePath}`);
107
+ return legacyPath;
108
+ }
109
+ catch (error) {
110
+ logger_1.default.debug(`迁移历史安装记录失败 (${legacyPath}): ${error instanceof Error ? error.message : String(error)}`);
111
+ }
112
+ }
113
+ return null;
114
+ }
115
+ function readInstallState() {
116
+ const stateFilePath = (0, config_1.getStateFilePath)();
117
+ if (!fs_1.default.existsSync(stateFilePath)) {
118
+ migrateLegacyInstallState();
119
+ }
120
+ if (!fs_1.default.existsSync(stateFilePath)) {
121
+ return { skills: {} };
122
+ }
123
+ try {
124
+ return parseInstallState(fs_1.default.readFileSync(stateFilePath, 'utf8'));
125
+ }
126
+ catch {
127
+ return { skills: {} };
128
+ }
129
+ }
89
130
  function writeInstallState(state) {
90
131
  const stateFilePath = (0, config_1.getStateFilePath)();
91
132
  (0, system_1.ensureDirectoryExists)(path_1.default.dirname(stateFilePath));
@@ -108,7 +149,9 @@ async function updateInstallState(skillName, repoPath, installDir, action, reque
108
149
  updatedAt: now,
109
150
  gitCommitHash: previous?.gitCommitHash || null,
110
151
  requestedVersion: requestedVersion ?? previous?.requestedVersion ?? null,
111
- version: version ?? previous?.version ?? null
152
+ version: version ?? previous?.version ?? null,
153
+ agent: (0, config_1.getAgentName)(),
154
+ skillsDir: (0, config_1.getSkillsDirectory)()
112
155
  };
113
156
  writeInstallState(state);
114
157
  }
@@ -201,9 +244,44 @@ function listLocalSkills() {
201
244
  .filter((entry) => entry.isDirectory())
202
245
  .map((entry) => entry.name);
203
246
  }
247
+ function recordSkillsDir(record) {
248
+ if (record.skillsDir) {
249
+ return record.skillsDir;
250
+ }
251
+ // 2.0 及更早版本的记录未保存技能目录,用安装目录的父目录推断
252
+ if (record.installDir) {
253
+ return path_1.default.dirname(record.installDir);
254
+ }
255
+ return null;
256
+ }
257
+ function recordMatchesCurrentSkillsDir(record) {
258
+ const recordDir = recordSkillsDir(record);
259
+ if (!recordDir) {
260
+ return true;
261
+ }
262
+ return (0, config_1.isSamePath)(recordDir, (0, config_1.getSkillsDirectory)());
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
+ }
204
281
  function listInstalledSkillNames() {
205
282
  const state = readInstallState();
206
283
  const stateNames = Object.values(state.skills)
284
+ .filter(recordMatchesCurrentSkillsDir)
207
285
  .map((item) => item.inputSkillName || item.localSkillName)
208
286
  .filter(Boolean);
209
287
  if (stateNames.length > 0) {
@@ -211,13 +289,52 @@ function listInstalledSkillNames() {
211
289
  }
212
290
  return listLocalSkills();
213
291
  }
292
+ /**
293
+ * 清理状态文件中的失效记录。
294
+ * 不传参数时清理不属于当前技能目录(Agent)的记录,
295
+ * 传入技能名时只清理指定记录。返回被清理的技能名列表。
296
+ */
297
+ function pruneInstallState(skillNames = []) {
298
+ const state = readInstallState();
299
+ const targets = new Set(skillNames.map((name) => normalizeSkillName(name)).filter(Boolean));
300
+ const removed = [];
301
+ Object.keys(state.skills).forEach((localSkillName) => {
302
+ const record = state.skills[localSkillName];
303
+ const shouldRemove = targets.size > 0
304
+ ? targets.has(localSkillName)
305
+ : !recordMatchesCurrentSkillsDir(record);
306
+ if (shouldRemove) {
307
+ delete state.skills[localSkillName];
308
+ removed.push(record.inputSkillName || localSkillName);
309
+ }
310
+ });
311
+ if (removed.length > 0) {
312
+ writeInstallState(state);
313
+ }
314
+ return removed;
315
+ }
316
+ /**
317
+ * 解析技能的实际解压目录:
318
+ * 优先使用安装记录中的 repoPath,其次解析缓存目录中的单层包装目录。
319
+ */
320
+ function resolveCachePaths(localSkillName, record) {
321
+ const cacheDir = path_1.default.join((0, config_1.getSkillsCacheDirectory)(), localSkillName);
322
+ if (record?.repoPath && fs_1.default.existsSync(record.repoPath)) {
323
+ return { cacheDir, repoPath: record.repoPath };
324
+ }
325
+ if (fs_1.default.existsSync(cacheDir)) {
326
+ return { cacheDir, repoPath: (0, unzip_1.resolveSkillRoot)(cacheDir) };
327
+ }
328
+ return { cacheDir, repoPath: cacheDir };
329
+ }
214
330
  function getInstalledSkillInfo(skillName) {
215
331
  const normalizedSkillName = normalizeCliSkillArgument(skillName);
216
332
  const localSkillName = normalizeSkillName(normalizedSkillName);
217
333
  const state = readInstallState();
218
334
  const record = state.skills[localSkillName] || null;
219
- const skillDir = path_1.default.join((0, config_1.getSkillsDirectory)(), localSkillName);
220
- const repoPath = path_1.default.join((0, config_1.getSkillsCacheDirectory)(), localSkillName);
335
+ const skillsDir = (0, config_1.getSkillsDirectory)();
336
+ const skillDir = path_1.default.join(skillsDir, localSkillName);
337
+ const { cacheDir, repoPath } = resolveCachePaths(localSkillName, record);
221
338
  return {
222
339
  skillName: normalizedSkillName,
223
340
  localSkillName,
@@ -225,6 +342,10 @@ function getInstalledSkillInfo(skillName) {
225
342
  cached: fs_1.default.existsSync(repoPath),
226
343
  skillDir,
227
344
  repoPath,
345
+ cacheDir,
346
+ skillsDir,
347
+ agent: (0, config_1.getAgentName)(),
348
+ agentLabel: (0, config_1.getAgentLabel)(),
228
349
  state: record
229
350
  };
230
351
  }
@@ -232,17 +353,27 @@ function removeInstalledSkill(skillName, options = {}) {
232
353
  const normalizedSkillName = normalizeCliSkillArgument(skillName);
233
354
  const localSkillName = normalizeSkillName(normalizedSkillName);
234
355
  const removeCache = options.removeCache !== false;
356
+ const state = readInstallState();
357
+ const record = state.skills[localSkillName] || null;
235
358
  const skillDir = path_1.default.join((0, config_1.getSkillsDirectory)(), localSkillName);
236
- const repoPath = path_1.default.join((0, config_1.getSkillsCacheDirectory)(), localSkillName);
359
+ const { cacheDir, repoPath } = resolveCachePaths(localSkillName, record);
237
360
  let removedInstall = false;
238
361
  let removedCache = false;
239
362
  if (fs_1.default.existsSync(skillDir)) {
240
363
  fs_1.default.rmSync(skillDir, { recursive: true, force: true });
241
364
  removedInstall = true;
242
365
  }
243
- if (removeCache && fs_1.default.existsSync(repoPath)) {
244
- fs_1.default.rmSync(repoPath, { recursive: true, force: true });
245
- removedCache = true;
366
+ if (removeCache) {
367
+ if (fs_1.default.existsSync(cacheDir)) {
368
+ fs_1.default.rmSync(cacheDir, { recursive: true, force: true });
369
+ removedCache = true;
370
+ }
371
+ if (!(0, config_1.isSamePath)(repoPath, cacheDir) &&
372
+ !repoPath.startsWith(`${cacheDir}${path_1.default.sep}`) &&
373
+ fs_1.default.existsSync(repoPath)) {
374
+ fs_1.default.rmSync(repoPath, { recursive: true, force: true });
375
+ removedCache = true;
376
+ }
246
377
  }
247
378
  removeInstallState(normalizedSkillName);
248
379
  return {
@@ -251,6 +382,6 @@ function removeInstalledSkill(skillName, options = {}) {
251
382
  removedInstall,
252
383
  removedCache,
253
384
  skillDir,
254
- repoPath
385
+ repoPath: cacheDir
255
386
  };
256
387
  }