@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.
@@ -3,41 +3,515 @@ 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.MAX_COPY_FILE_SIZE_BYTES = exports.REQUEST_TIMEOUT_MS = void 0;
7
- exports.setBaseUrl = setBaseUrl;
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
+ exports.normalizePath = normalizePath;
8
+ exports.isSamePath = isSamePath;
9
+ exports.normalizeBaseUrl = normalizeBaseUrl;
10
+ exports.normalizeConfigKey = normalizeConfigKey;
11
+ exports.getHomeDirectory = getHomeDirectory;
12
+ exports.getGetSkillHome = getGetSkillHome;
13
+ exports.getConfigFilePath = getConfigFilePath;
14
+ exports.getStateFilePath = getStateFilePath;
15
+ exports.getLegacyStateFilePaths = getLegacyStateFilePaths;
16
+ exports.readConfigFile = readConfigFile;
17
+ exports.writeConfigFile = writeConfigFile;
18
+ exports.getAgentPreset = getAgentPreset;
19
+ exports.getPresetSkillsDir = getPresetSkillsDir;
20
+ exports.detectAgentName = detectAgentName;
21
+ exports.refreshConfig = refreshConfig;
22
+ exports.applyRuntimeOverrides = applyRuntimeOverrides;
23
+ exports.clearRuntimeOverrides = clearRuntimeOverrides;
24
+ exports.resolveConfig = resolveConfig;
25
+ exports.getConfigSummary = getConfigSummary;
8
26
  exports.getBaseUrl = getBaseUrl;
9
- exports.getOpenClawRootDirectory = getOpenClawRootDirectory;
10
27
  exports.getSkillsDirectory = getSkillsDirectory;
28
+ exports.assertExplicitSkillsDir = assertExplicitSkillsDir;
11
29
  exports.getSkillsCacheDirectory = getSkillsCacheDirectory;
12
- exports.getGetSkillConfigDirectory = getGetSkillConfigDirectory;
13
- exports.getStateFilePath = getStateFilePath;
30
+ exports.getAgentName = getAgentName;
31
+ exports.getAgentLabel = getAgentLabel;
32
+ exports.getAgentRestartCommand = getAgentRestartCommand;
33
+ exports.listAgents = listAgents;
34
+ exports.getLegacyCacheDirectories = getLegacyCacheDirectories;
35
+ exports.setConfigValue = setConfigValue;
36
+ exports.unsetConfigValue = unsetConfigValue;
37
+ exports.setBaseUrl = setBaseUrl;
38
+ exports.setAgent = setAgent;
39
+ exports.setSkillsDir = setSkillsDir;
40
+ exports.setCacheDir = setCacheDir;
41
+ const fs_1 = __importDefault(require("fs"));
14
42
  const os_1 = __importDefault(require("os"));
15
43
  const path_1 = __importDefault(require("path"));
16
- let baseUrl = process.env.GETSKILL_BASE_URL || 'https://getskill.work';
44
+ const system_1 = require("./system");
45
+ exports.DEFAULT_BASE_URL = 'https://getskill.work';
17
46
  exports.REQUEST_TIMEOUT_MS = 60000;
47
+ exports.SKILLS_INDEX_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
18
48
  exports.MAX_COPY_FILE_SIZE_BYTES = 2 * 1024 * 1024;
19
- function setBaseUrl(url) {
20
- if (!url || typeof url !== 'string') {
21
- throw new Error('BASE_URL 必须是有效字符串');
49
+ exports.AUTO_AGENT_NAME = 'auto';
50
+ exports.CUSTOM_AGENT_NAME = 'custom';
51
+ exports.DEFAULT_AGENT_NAME = 'claude';
52
+ /**
53
+ * 支持的 Agent 目录约定。任何 Agent 都可以通过 agent 预设、
54
+ * skillsDir 自定义目录或 GETSKILL_SKILLS_DIR 环境变量接入。
55
+ */
56
+ exports.AGENT_PRESETS = [
57
+ {
58
+ name: 'claude',
59
+ label: 'Claude Code',
60
+ skillsPathSegments: ['.claude', 'skills']
61
+ },
62
+ {
63
+ name: 'openclaw',
64
+ label: 'OpenClaw',
65
+ skillsPathSegments: ['.openclaw', 'skills'],
66
+ restartCommand: 'openclaw gateway restart'
67
+ },
68
+ {
69
+ name: 'codex',
70
+ label: 'OpenAI Codex CLI',
71
+ skillsPathSegments: ['.codex', 'skills']
72
+ },
73
+ {
74
+ name: 'cursor',
75
+ label: 'Cursor',
76
+ skillsPathSegments: ['.cursor', 'skills']
77
+ },
78
+ {
79
+ name: 'gemini',
80
+ label: 'Gemini CLI',
81
+ skillsPathSegments: ['.gemini', 'skills']
82
+ },
83
+ {
84
+ name: 'qwen',
85
+ label: 'Qwen Code',
86
+ skillsPathSegments: ['.qwen', 'skills']
87
+ },
88
+ {
89
+ name: 'copilot',
90
+ label: 'GitHub Copilot CLI',
91
+ skillsPathSegments: ['.copilot', 'skills']
92
+ },
93
+ {
94
+ name: 'amp',
95
+ label: 'Amp',
96
+ skillsPathSegments: ['.config', 'amp', 'skills']
97
+ },
98
+ {
99
+ name: 'opencode',
100
+ label: 'OpenCode',
101
+ skillsPathSegments: ['.config', 'opencode', 'skills']
102
+ },
103
+ {
104
+ name: 'agent',
105
+ label: '通用 Agent 目录',
106
+ skillsPathSegments: ['.agent', 'skills']
22
107
  }
23
- baseUrl = url.replace(/\/$/, '');
24
- return baseUrl;
108
+ ];
109
+ const CONFIG_KEY_ALIASES = {
110
+ 'base-url': 'baseUrl',
111
+ baseurl: 'baseUrl',
112
+ base_url: 'baseUrl',
113
+ url: 'baseUrl',
114
+ index: 'baseUrl',
115
+ 'index-url': 'baseUrl',
116
+ agent: 'agent',
117
+ target: 'agent',
118
+ 'skills-dir': 'skillsDir',
119
+ skillsdir: 'skillsDir',
120
+ skills_dir: 'skillsDir',
121
+ dir: 'skillsDir',
122
+ 'cache-dir': 'cacheDir',
123
+ cachedir: 'cacheDir',
124
+ cache_dir: 'cacheDir',
125
+ cache: 'cacheDir'
126
+ };
127
+ let cliOverrides = {};
128
+ let resolvedCache = null;
129
+ function isBlank(value) {
130
+ return typeof value !== 'string' || value.trim() === '';
25
131
  }
26
- function getBaseUrl() {
27
- return baseUrl;
132
+ function expandHome(value) {
133
+ const trimmed = value.trim();
134
+ if (trimmed === '~') {
135
+ return os_1.default.homedir();
136
+ }
137
+ if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
138
+ return path_1.default.join(os_1.default.homedir(), trimmed.slice(2));
139
+ }
140
+ return trimmed;
141
+ }
142
+ function normalizePath(value) {
143
+ return path_1.default.resolve(expandHome(value));
144
+ }
145
+ function isSamePath(left, right) {
146
+ const a = path_1.default.resolve(left);
147
+ const b = path_1.default.resolve(right);
148
+ return process.platform === 'win32'
149
+ ? a.toLowerCase() === b.toLowerCase()
150
+ : a === b;
151
+ }
152
+ function normalizeBaseUrl(url) {
153
+ const trimmed = url.trim().replace(/\/+$/, '');
154
+ if (!/^https?:\/\/.+/i.test(trimmed)) {
155
+ throw new Error(`索引地址必须是 http(s) URL,例如 ${exports.DEFAULT_BASE_URL}(收到: ${url})`);
156
+ }
157
+ return trimmed;
158
+ }
159
+ function normalizeConfigKey(key) {
160
+ const normalized = key.trim().toLowerCase();
161
+ const mapped = CONFIG_KEY_ALIASES[normalized];
162
+ if (!mapped) {
163
+ throw new Error(`未知配置项: ${key}(可用: base-url, agent, skills-dir, cache-dir)`);
164
+ }
165
+ return mapped;
166
+ }
167
+ function getHomeDirectory() {
168
+ return os_1.default.homedir();
169
+ }
170
+ function getGetSkillHome() {
171
+ const fromEnv = process.env.GETSKILL_HOME;
172
+ if (!isBlank(fromEnv)) {
173
+ return normalizePath(fromEnv);
174
+ }
175
+ return path_1.default.join(os_1.default.homedir(), '.getskill');
28
176
  }
29
- function getOpenClawRootDirectory() {
30
- return path_1.default.join(os_1.default.homedir(), '.openclaw');
177
+ function getConfigFilePath() {
178
+ return path_1.default.join(getGetSkillHome(), 'config.json');
179
+ }
180
+ function getStateFilePath() {
181
+ const fromEnv = process.env.GETSKILL_STATE_FILE;
182
+ if (!isBlank(fromEnv)) {
183
+ return normalizePath(fromEnv);
184
+ }
185
+ return path_1.default.join(getGetSkillHome(), 'state.json');
186
+ }
187
+ function getLegacyStateFilePaths() {
188
+ const candidates = [
189
+ path_1.default.join(os_1.default.homedir(), '.openclaw', 'getskill', 'state.json'),
190
+ path_1.default.join(path_1.default.dirname(getPresetSkillsDir(getAgentPreset('openclaw'))), 'getskill', 'state.json')
191
+ ];
192
+ return [...new Set(candidates)].filter((candidate) => !isSamePath(candidate, getStateFilePath()));
193
+ }
194
+ function readConfigFile() {
195
+ const configFile = getConfigFilePath();
196
+ if (!fs_1.default.existsSync(configFile)) {
197
+ return {};
198
+ }
199
+ try {
200
+ const parsed = JSON.parse(fs_1.default.readFileSync(configFile, 'utf8'));
201
+ if (!parsed || typeof parsed !== 'object') {
202
+ return {};
203
+ }
204
+ const result = {};
205
+ Object.keys(parsed).forEach((key) => {
206
+ const value = parsed[key];
207
+ if (typeof value === 'string' && value.trim() !== '') {
208
+ result[key] = value.trim();
209
+ }
210
+ });
211
+ return result;
212
+ }
213
+ catch {
214
+ return {};
215
+ }
216
+ }
217
+ function writeConfigFile(config) {
218
+ const configFile = getConfigFilePath();
219
+ (0, system_1.ensureDirectoryExists)(path_1.default.dirname(configFile));
220
+ fs_1.default.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
221
+ }
222
+ function getAgentPreset(name) {
223
+ if (isBlank(name)) {
224
+ return null;
225
+ }
226
+ const normalized = name.trim().toLowerCase();
227
+ return exports.AGENT_PRESETS.find((preset) => preset.name === normalized) || null;
228
+ }
229
+ function getPresetSkillsDir(preset) {
230
+ return path_1.default.join(os_1.default.homedir(), ...preset.skillsPathSegments);
231
+ }
232
+ function directoryHasEntries(dir) {
233
+ if (!fs_1.default.existsSync(dir)) {
234
+ return false;
235
+ }
236
+ try {
237
+ return fs_1.default.readdirSync(dir).length > 0;
238
+ }
239
+ catch {
240
+ return false;
241
+ }
242
+ }
243
+ function readStateSkillsDirHint() {
244
+ const candidates = [
245
+ getStateFilePath(),
246
+ ...getLegacyStateFilePaths().map((item) => item)
247
+ ];
248
+ for (const candidate of candidates) {
249
+ if (!fs_1.default.existsSync(candidate)) {
250
+ continue;
251
+ }
252
+ try {
253
+ const parsed = JSON.parse(fs_1.default.readFileSync(candidate, 'utf8'));
254
+ const records = Object.values(parsed?.skills || {});
255
+ for (const record of records) {
256
+ if (record && typeof record.installDir === 'string') {
257
+ return path_1.default.dirname(record.installDir);
258
+ }
259
+ }
260
+ }
261
+ catch {
262
+ continue;
263
+ }
264
+ }
265
+ return null;
266
+ }
267
+ /**
268
+ * 自动识别当前机器上正在使用的 Agent 技能目录。
269
+ * 优先级:历史安装记录 > 已存在且非空的技能目录 > 已存在的 Agent 根目录 > 默认值。
270
+ */
271
+ function detectAgentName() {
272
+ const hint = readStateSkillsDirHint();
273
+ if (hint) {
274
+ const fromState = exports.AGENT_PRESETS.find((preset) => isSamePath(getPresetSkillsDir(preset), hint));
275
+ if (fromState) {
276
+ return fromState.name;
277
+ }
278
+ }
279
+ const nonEmpty = exports.AGENT_PRESETS.find((preset) => directoryHasEntries(getPresetSkillsDir(preset)));
280
+ if (nonEmpty) {
281
+ return nonEmpty.name;
282
+ }
283
+ const rootExists = exports.AGENT_PRESETS.find((preset) => fs_1.default.existsSync(path_1.default.dirname(getPresetSkillsDir(preset))));
284
+ if (rootExists) {
285
+ return rootExists.name;
286
+ }
287
+ return exports.DEFAULT_AGENT_NAME;
288
+ }
289
+ function pickValue(candidates, fallback) {
290
+ for (const candidate of candidates) {
291
+ if (!isBlank(candidate.value)) {
292
+ return {
293
+ value: candidate.value.trim(),
294
+ source: candidate.source
295
+ };
296
+ }
297
+ }
298
+ return fallback;
299
+ }
300
+ function refreshConfig() {
301
+ resolvedCache = null;
302
+ }
303
+ /** 仅作用于当前进程的临时覆盖(例如 CLI 的 --agent / --skills-dir 参数)。 */
304
+ function applyRuntimeOverrides(overrides) {
305
+ let changed = false;
306
+ Object.keys(overrides).forEach((key) => {
307
+ const value = overrides[key];
308
+ if (typeof value === 'string' && value.trim() !== '') {
309
+ cliOverrides[key] = value.trim();
310
+ changed = true;
311
+ }
312
+ });
313
+ if (changed) {
314
+ refreshConfig();
315
+ }
316
+ }
317
+ function clearRuntimeOverrides() {
318
+ cliOverrides = {};
319
+ refreshConfig();
320
+ }
321
+ function resolveConfig() {
322
+ if (resolvedCache) {
323
+ return resolvedCache;
324
+ }
325
+ const file = readConfigFile();
326
+ const baseUrlPick = pickValue([
327
+ { value: cliOverrides.baseUrl, source: 'cli' },
328
+ { value: process.env.GETSKILL_BASE_URL, source: 'env' },
329
+ { value: file.baseUrl, source: 'file' }
330
+ ], { value: exports.DEFAULT_BASE_URL, source: 'default' });
331
+ const agentPick = pickValue([
332
+ { value: cliOverrides.agent, source: 'cli' },
333
+ { value: process.env.GETSKILL_AGENT, source: 'env' },
334
+ { value: file.agent, source: 'file' }
335
+ ], { value: exports.AUTO_AGENT_NAME, source: 'detect' });
336
+ const skillsDirPick = pickValue([
337
+ { value: cliOverrides.skillsDir, source: 'cli' },
338
+ { value: process.env.GETSKILL_SKILLS_DIR, source: 'env' },
339
+ { value: file.skillsDir, source: 'file' }
340
+ ], { value: '', source: 'default' });
341
+ const cacheDirPick = pickValue([
342
+ { value: cliOverrides.cacheDir, source: 'cli' },
343
+ { value: process.env.GETSKILL_CACHE_DIR, source: 'env' },
344
+ { value: file.cacheDir, source: 'file' }
345
+ ], { value: '', source: 'default' });
346
+ const requestedAgent = agentPick.value.toLowerCase();
347
+ const preset = getAgentPreset(requestedAgent);
348
+ const isAuto = requestedAgent === exports.AUTO_AGENT_NAME;
349
+ if (!preset && !isAuto && !skillsDirPick.value) {
350
+ throw new Error(`未知 agent: ${agentPick.value}(可用: auto, ${exports.AGENT_PRESETS.map((item) => item.name).join(', ')},或通过 skills-dir 指定任意目录)`);
351
+ }
352
+ const resolvedPreset = preset || getAgentPreset(detectAgentName());
353
+ const agentName = skillsDirPick.value
354
+ ? preset
355
+ ? preset.name
356
+ : exports.CUSTOM_AGENT_NAME
357
+ : resolvedPreset.name;
358
+ const agentLabel = skillsDirPick.value
359
+ ? preset
360
+ ? preset.label
361
+ : '自定义目录'
362
+ : resolvedPreset.label;
363
+ const skillsDir = skillsDirPick.value
364
+ ? normalizePath(skillsDirPick.value)
365
+ : getPresetSkillsDir(resolvedPreset);
366
+ const skillsDirSource = skillsDirPick.value
367
+ ? skillsDirPick.source
368
+ : isAuto || !preset
369
+ ? 'detect'
370
+ : agentPick.source;
371
+ const cacheDir = cacheDirPick.value
372
+ ? normalizePath(cacheDirPick.value)
373
+ : path_1.default.join(getGetSkillHome(), 'cache');
374
+ const envRestartCommand = process.env.GETSKILL_RESTART_CMD;
375
+ const restartCommand = !isBlank(envRestartCommand)
376
+ ? envRestartCommand.trim()
377
+ : resolvedPreset?.restartCommand || null;
378
+ const resolved = {
379
+ baseUrl: normalizeBaseUrl(baseUrlPick.value),
380
+ agent: agentName,
381
+ agentLabel,
382
+ skillsDir,
383
+ cacheDir,
384
+ homeDir: getGetSkillHome(),
385
+ configFile: getConfigFilePath(),
386
+ stateFile: getStateFilePath(),
387
+ restartCommand,
388
+ sources: {
389
+ baseUrl: baseUrlPick.source,
390
+ agent: isAuto
391
+ ? skillsDirPick.value
392
+ ? skillsDirPick.source
393
+ : 'detect'
394
+ : agentPick.source,
395
+ skillsDir: skillsDirSource,
396
+ cacheDir: cacheDirPick.value ? cacheDirPick.source : 'default'
397
+ }
398
+ };
399
+ resolvedCache = resolved;
400
+ return resolved;
401
+ }
402
+ function getConfigSummary() {
403
+ return resolveConfig();
404
+ }
405
+ function getBaseUrl() {
406
+ return resolveConfig().baseUrl;
31
407
  }
32
408
  function getSkillsDirectory() {
33
- return path_1.default.join(getOpenClawRootDirectory(), 'skills');
409
+ return resolveConfig().skillsDir;
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'));
34
430
  }
35
431
  function getSkillsCacheDirectory() {
36
- return path_1.default.join(getOpenClawRootDirectory(), 'skills-cache');
432
+ return resolveConfig().cacheDir;
37
433
  }
38
- function getGetSkillConfigDirectory() {
39
- return path_1.default.join(getOpenClawRootDirectory(), 'getskill');
434
+ function getAgentName() {
435
+ return resolveConfig().agent;
40
436
  }
41
- function getStateFilePath() {
42
- return path_1.default.join(getGetSkillConfigDirectory(), 'state.json');
437
+ function getAgentLabel() {
438
+ return resolveConfig().agentLabel;
439
+ }
440
+ function getAgentRestartCommand() {
441
+ return resolveConfig().restartCommand;
442
+ }
443
+ function listAgents() {
444
+ const active = resolveConfig();
445
+ return exports.AGENT_PRESETS.map((preset) => {
446
+ const skillsDir = getPresetSkillsDir(preset);
447
+ return {
448
+ name: preset.name,
449
+ label: preset.label,
450
+ skillsDir,
451
+ exists: fs_1.default.existsSync(skillsDir),
452
+ active: isSamePath(skillsDir, active.skillsDir),
453
+ restartCommand: preset.restartCommand || null
454
+ };
455
+ });
456
+ }
457
+ /** 历史版本(2.0 及更早)遗留的缓存目录,`clean` 命令会一并清理。 */
458
+ function getLegacyCacheDirectories() {
459
+ const current = getSkillsCacheDirectory();
460
+ const candidates = [path_1.default.join(os_1.default.homedir(), '.openclaw', 'skills-cache')];
461
+ return [...new Set(candidates)].filter((candidate) => !isSamePath(candidate, current));
462
+ }
463
+ function persistConfig(patch) {
464
+ const next = { ...readConfigFile() };
465
+ Object.keys(patch).forEach((key) => {
466
+ const value = patch[key];
467
+ if (typeof value === 'string' && value.trim() !== '') {
468
+ next[key] = value.trim();
469
+ return;
470
+ }
471
+ delete next[key];
472
+ });
473
+ writeConfigFile(next);
474
+ refreshConfig();
475
+ return resolveConfig();
476
+ }
477
+ function normalizeConfigValue(configKey, rawValue) {
478
+ if (isBlank(rawValue)) {
479
+ throw new Error(`配置项 ${configKey} 的值不能为空`);
480
+ }
481
+ const value = rawValue.trim();
482
+ if (configKey === 'baseUrl') {
483
+ return normalizeBaseUrl(value);
484
+ }
485
+ if (configKey === 'skillsDir' || configKey === 'cacheDir') {
486
+ return normalizePath(value);
487
+ }
488
+ const normalized = value.toLowerCase();
489
+ if (normalized !== exports.AUTO_AGENT_NAME && !getAgentPreset(normalized)) {
490
+ throw new Error(`未知 agent: ${value}(可用: auto, ${exports.AGENT_PRESETS.map((item) => item.name).join(', ')})`);
491
+ }
492
+ return normalized;
493
+ }
494
+ /** 写入并持久化配置项,返回写入后的完整生效配置。 */
495
+ function setConfigValue(key, rawValue) {
496
+ const configKey = normalizeConfigKey(String(key));
497
+ return persistConfig({
498
+ [configKey]: normalizeConfigValue(configKey, rawValue)
499
+ });
500
+ }
501
+ /** 删除已持久化的配置项,恢复为环境变量 / 自动识别 / 默认值。 */
502
+ function unsetConfigValue(key) {
503
+ const configKey = normalizeConfigKey(String(key));
504
+ return persistConfig({ [configKey]: '' });
505
+ }
506
+ function setBaseUrl(url) {
507
+ return setConfigValue('baseUrl', url).baseUrl;
508
+ }
509
+ function setAgent(name) {
510
+ return setConfigValue('agent', name).agent;
511
+ }
512
+ function setSkillsDir(dir) {
513
+ return setConfigValue('skillsDir', dir).skillsDir;
514
+ }
515
+ function setCacheDir(dir) {
516
+ return setConfigValue('cacheDir', dir).cacheDir;
43
517
  }
@@ -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[]>;