@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.
package/README.md CHANGED
@@ -1,123 +1,167 @@
1
1
  # GetSkill
2
2
 
3
- OpenClaw 技能管理工具 - 从 getskill.work 搜索、下载和更新技能文件
3
+ AI Agent 技能管理工具 - 从 getskill.work 搜索、下载和更新技能文件,适用于任意 Agent(Claude Code、OpenClaw、Codex、Cursor……或任意自定义技能目录)。
4
4
 
5
5
  ## 功能特性
6
6
 
7
- - 🔍 从 `getskill.work` 静态技能索引(`data/skills.json`)搜索技能
8
- - 🧾 支持 JSON 格式搜索输出(`search --json`)
9
- - 📥 通过 HTTP 直接下载技能 ZIP 包,本地解压安装(**无需安装 Git**)
10
- - 🏷️ 支持安装/更新指定版本(`--version <version>`)
11
- - 🔄 基于版本号比较的增量更新(`update` / `update --all`)
12
- - 📂 跨平台支持(Windows/macOS/Linux)
13
- - 💾 自动管理技能文件到 OpenClaw skills 目录
14
- - ⚙️ 支持自定义索引地址
7
+ - 🔍 从 `getskill.work` 静态技能索引(`data/skills.json`)搜索技能,支持 `--json` 输出
8
+ - ⚡ 索引本地缓存(TTL 1 天):搜索优先读本地缓存,过期自动刷新,下载失败回退旧缓存(离线可搜索)
9
+ - 🧠 搜索结果标注本地安装状态(`installed` / `installed_version` / `suggested_action`),同版本已装时 `install` 自动跳过下载(`--force` 可强制重装)
10
+ - 📥 通过 HTTPS 直接下载技能 ZIP 包并在本地解压安装
11
+ - 🔄 基于版本号比较的增量更新(`update` / `update --all`,`--prune` 可清理已下架技能的历史记录)
12
+ - 🤖 **不绑定任何 Agent**:内置多种 Agent 目录预设,可自动识别本机 Agent
13
+ - 💾 配置持久化到 `~/.getskill/config.json`,安装记录持久化到 `~/.getskill/state.json`(自动迁移旧版 `~/.openclaw/getskill/state.json`)
14
+ - ⚙️ 支持环境变量与命令行参数覆盖(`GETSKILL_BASE_URL`、`GETSKILL_AGENT`、`GETSKILL_SKILLS_DIR` 等)
15
+ - 📂 跨平台支持(Windows / macOS / Linux)
15
16
  - 📦 零第三方运行时依赖(内置 ZIP 解析/解压实现)
16
17
 
17
- ## 目录结构
18
+ ## 安装
18
19
 
19
- ```
20
- ~/.openclaw/
21
- ├── skills/ # OpenClaw 技能目录
22
- │ ├── skill1/
23
- │ └── skill2/
24
- └── skills-cache/ # ZIP 下载与解压缓存
25
- ├── skill1/
26
- └── skill2/
20
+ 全局安装后即可在任意位置使用 `getskill` 命令:
21
+
22
+ ```bash
23
+ npm install -g @workskills/getskill
27
24
  ```
28
25
 
29
- ### 平台路径
26
+ 也可以不安装直接通过 npx 运行:
30
27
 
31
- - **Windows**: `%USERPROFILE%\.openclaw\skills`
32
- - **macOS**: `~/.openclaw/skills`
33
- - **Linux**: `~/.openclaw/skills`
28
+ ```bash
29
+ npx @workskills/getskill search <关键词>
30
+ ```
34
31
 
35
- ## 安装
32
+ 要求 Node.js >= 18。
33
+
34
+ ## 目标 Agent 与技能目录
36
35
 
37
- ### 全局安装(推荐)
36
+ `getskill` 把技能安装到「当前 Agent 的技能目录」。查看当前生效的 Agent 与目录:
38
37
 
39
38
  ```bash
40
- npm install -g @workskills/getskill
39
+ getskill path
41
40
  ```
42
41
 
43
- 安装后,可以在任何位置使用 `getskill` 命令。
44
-
45
- ### 本地安装
42
+ 列出内置 Agent 预设(`*` 表示当前生效):
46
43
 
47
44
  ```bash
48
- npm install @workskills/getskill
45
+ getskill agents
49
46
  ```
50
47
 
51
- 本地安装后,可以通过 npx 运行:
48
+ 内置预设:
49
+
50
+ | agent | Agent | 技能目录 |
51
+ | ---------- | ------------------ | --------------------------- |
52
+ | `claude` | Claude Code | `~/.claude/skills` |
53
+ | `openclaw` | OpenClaw | `~/.openclaw/skills` |
54
+ | `codex` | OpenAI Codex CLI | `~/.codex/skills` |
55
+ | `cursor` | Cursor | `~/.cursor/skills` |
56
+ | `gemini` | Gemini CLI | `~/.gemini/skills` |
57
+ | `qwen` | Qwen Code | `~/.qwen/skills` |
58
+ | `copilot` | GitHub Copilot CLI | `~/.copilot/skills` |
59
+ | `amp` | Amp | `~/.config/amp/skills` |
60
+ | `opencode` | OpenCode | `~/.config/opencode/skills` |
61
+ | `agent` | 通用 Agent 目录 | `~/.agent/skills` |
62
+
63
+ 默认 `agent = auto`:按「历史安装记录 → 已存在且非空的技能目录 → 已存在的 Agent 根目录」顺序自动识别;都识别不到时使用 `~/.claude/skills`。
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
+
67
+ 不在预设列表中的 Agent,直接指定技能目录即可(三种方式任选一种):
52
68
 
53
69
  ```bash
54
- npx getskill search <关键词>
70
+ # 1) 持久化保存
71
+ getskill config set skills-dir ~/.my-agent/skills
72
+
73
+ # 2) 仅本次命令生效
74
+ getskill --skills-dir ~/.my-agent/skills install <技能名称>
75
+
76
+ # 3) 环境变量
77
+ GETSKILL_SKILLS_DIR=~/.my-agent/skills getskill install <技能名称>
55
78
  ```
56
79
 
57
- ### 从源码安装
80
+ 指定 Agent(持久化 / 单次):
58
81
 
59
82
  ```bash
60
- git clone https://github.com/work-skills/getskill.git
61
- cd getskill
62
- npm install
63
- npm link
83
+ getskill config set agent cursor
84
+ getskill --agent codex install <技能名称>
64
85
  ```
65
86
 
87
+ 下载与解压缓存默认位于 `~/.getskill/cache`,可用 `cache-dir` 配置或 `GETSKILL_CACHE_DIR` 覆盖。
88
+
66
89
  ## 使用方法
67
90
 
68
91
  ### 搜索技能
69
92
 
70
- > 所有命令**全部无需登录、无需 Git**,直接通过 HTTPS 下载 ZIP 包并本地解压。
71
-
72
93
  ```bash
73
94
  getskill search <关键词>
74
95
  ```
75
96
 
76
- 输出 JSON:
97
+ JSON 格式输出:
77
98
 
78
99
  ```bash
79
100
  getskill search <关键词> --json
80
101
  ```
81
102
 
82
- 示例输出:
103
+ 示例(`getskill search pdf-toolkit`):
83
104
 
84
105
  ```
85
- 找到 2 个技能:
106
+ 找到 1 个技能:
86
107
 
87
- 1. pdf-extract (v1.0.0)
88
- 描述: 从 PDF 文件中提取文本和表格
108
+ 1. pdf-toolkit (v1.0.0)
109
+ 描述: PDF 文档处理技能:提取文本、合并拆分、页面旋转与加水印。当用户需要处理 PDF 文件时使用。
89
110
  分类: 文档处理
90
- 下载: https://getskill.work/skills/pdf-extract.zip
91
-
92
- 2. xlsx (v1.0.0)
93
- 描述: 电子表格文件的创建、编辑与分析
94
- 分类: 文档处理
95
- 下载: https://getskill.work/skills/xlsx.zip
111
+ 下载: https://getskill.work/skills/pdf-toolkit.zip
112
+ 本地: 已安装 v1.0.0(同版本,无需重复安装)
96
113
  ```
97
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
+
98
126
  ### 安装技能
99
127
 
100
128
  ```bash
101
129
  getskill install <技能名称>
102
130
  ```
103
131
 
104
- 安装指定版本:
132
+ 示例:
105
133
 
106
134
  ```bash
107
- getskill install <技能名称> --version <version>
135
+ getskill install pdf-toolkit
108
136
  ```
109
137
 
110
- 示例:
138
+ 输出:
111
139
 
112
- ```bash
113
- getskill install pdf-extract
140
+ ```
141
+ 下载技能: pdf-toolkit...
142
+ 下载技能包: https://getskill.work/skills/pdf-toolkit.zip
143
+ 下载完成 (1025 bytes),正在解压...
144
+ 技能 pdf-toolkit (v1.0.0) 安装成功!
145
+
146
+ 目标 Agent: claude (Claude Code)
147
+ 技能已安装到 skills 目录:
148
+ - C:\Users\<用户名>\.claude\skills\pdf-toolkit
149
+
150
+ 本地缓存: C:\Users\<用户名>\.getskill\cache\pdf-toolkit\pdf-toolkit
151
+ 已安装版本: 1.0.0
114
152
  ```
115
153
 
116
154
  操作流程:
117
155
 
118
- 1. 在静态索引中定位技能条目,获取 `download_url`
119
- 2. 下载 ZIP 包到 `~/.openclaw/skills-cache/<技能名称>` 并解压
120
- 3. 将技能目录复制到 `~/.openclaw/skills/<技能名称>`,记录已安装版本
156
+ 1. 在静态索引中定位技能条目,获取下载地址
157
+ 2. 若同版本已安装(安装记录版本一致且技能目录存在),跳过下载并提示;`--force` 可强制重装
158
+ 3. 下载 ZIP 包到缓存目录(默认 `~/.getskill/cache/<技能名称>`)并解压
159
+ 4. 将技能目录复制到当前 Agent 的技能目录,并记录已安装版本
160
+
161
+ ```bash
162
+ # 强制重装(忽略“同版本已安装”的跳过逻辑)
163
+ getskill install pdf-toolkit --force
164
+ ```
121
165
 
122
166
  ### 更新技能
123
167
 
@@ -131,17 +175,18 @@ getskill update <技能名称>
131
175
  getskill update --all
132
176
  ```
133
177
 
134
- 切换到指定版本:
178
+ 批量更新并清理索引中已下架技能的历史记录:
135
179
 
136
180
  ```bash
137
- getskill update <技能名称> --version <version>
181
+ getskill update --all --prune
138
182
  ```
139
183
 
140
184
  更新逻辑:
141
185
 
142
- 1. 读取本地已安装技能的版本记录
143
- 2. 拉取远端索引中的最新版本号
144
- 3. 版本一致时提示"已是最新版本";不一致时重新下载 ZIP 并覆盖安装
186
+ 1. 读取本地已安装技能的版本记录(仅统计属于当前技能目录的记录)
187
+ 2. 强制刷新技能索引缓存,拉取远端最新版本号(`update --all` 每进程只刷新一次)
188
+ 3. 版本一致时提示“已是最新版本”;不一致时重新下载 ZIP 并覆盖安装
189
+ 4. 索引中已不存在的技能会被标记为“已跳过”,不算失败;加 `--prune` 可清理这些失效记录
145
190
 
146
191
  ### 卸载技能
147
192
 
@@ -161,18 +206,41 @@ getskill uninstall <技能名称> --keep-cache
161
206
  getskill inspect <技能名称>
162
207
  ```
163
208
 
209
+ 输出示例:
210
+
211
+ ```
212
+ 技能名称: pdf-toolkit
213
+ 本地目录: pdf-toolkit
214
+ 目标 Agent: claude (Claude Code)
215
+ 已安装: 是
216
+ 已缓存: 是
217
+ 技能路径: C:\Users\<用户名>\.claude\skills\pdf-toolkit
218
+ 技能目录: C:\Users\<用户名>\.claude\skills
219
+ 缓存目录: C:\Users\<用户名>\.getskill\cache\pdf-toolkit
220
+ 解压路径: C:\Users\<用户名>\.getskill\cache\pdf-toolkit\pdf-toolkit
221
+ 最后动作: install
222
+ 版本: 1.0.0
223
+ ```
224
+
164
225
  ### 列出本地技能
165
226
 
166
227
  ```bash
167
228
  getskill list
168
229
  ```
169
230
 
170
- 返回 `~/.openclaw/skills` 下的技能目录名称列表。
231
+ 返回当前 Agent 技能目录下的技能目录名称列表:
171
232
 
172
- ### 查看目录路径
233
+ ```
234
+ 本地已安装的技能 (1) · Agent: claude · 目录: C:\Users\<用户名>\.claude\skills
235
+ 1. pdf-toolkit
236
+ ```
237
+
238
+ ### 查看路径与配置
173
239
 
174
240
  ```bash
175
- getskill path
241
+ getskill path # Agent、技能目录、缓存目录、配置文件、状态文件、站点地址
242
+ getskill agents # 内置 Agent 预设与当前生效项
243
+ getskill config get
176
244
  ```
177
245
 
178
246
  ### 清理缓存
@@ -181,141 +249,94 @@ getskill path
181
249
  getskill clean
182
250
  ```
183
251
 
184
- 清理 ZIP 下载与解压缓存(不影响 skills 目录中的文件)
185
-
186
- ### 配置索引地址
252
+ 清理 ZIP 下载与解压缓存以及技能索引缓存 `skills-index.json`(不影响技能目录中的文件),同时清理旧版本遗留的 `~/.openclaw/skills-cache`。下次搜索会重新下载索引。
187
253
 
188
- 查看当前索引地址:
254
+ ### 帮助与版本
189
255
 
190
256
  ```bash
191
- getskill config get
257
+ getskill --help
258
+ getskill --version
192
259
  ```
193
260
 
194
- 设置自定义索引地址:
195
-
196
- ```bash
197
- getskill config set https://your-custom-index.com
198
- ```
261
+ ## 配置
199
262
 
200
- 通过环境变量设置:
263
+ 配置项保存在 `~/.getskill/config.json`(可用 `GETSKILL_HOME` 改变该目录位置)。
201
264
 
202
265
  ```bash
203
- GETSKILL_BASE_URL=https://your-custom-index.com getskill search keyword
266
+ getskill config get # 查看全部配置项及其来源
267
+ getskill config get <key> # 查看单个配置项
268
+ getskill config set <key> <value> # 保存配置项
269
+ getskill config unset <key> # 删除配置项,恢复自动识别/默认值
270
+ getskill config path # 显示配置文件路径
271
+ getskill config agents # 列出支持的 Agent
204
272
  ```
205
273
 
206
- ## 索引数据规范
274
+ 可用配置项:
207
275
 
208
- ### 索引文件
276
+ | key | 说明 | 示例 |
277
+ | ------------ | ------------------------------------ | ----------------------------------------------------- |
278
+ | `base-url` | 技能索引站点地址 | `getskill config set base-url https://your-index.com` |
279
+ | `agent` | 目标 Agent(预设名或 `auto`) | `getskill config set agent cursor` |
280
+ | `skills-dir` | 任意自定义技能目录(优先于 `agent`) | `getskill config set skills-dir ~/.my-agent/skills` |
281
+ | `cache-dir` | 下载/解压缓存目录 | `getskill config set cache-dir ~/.cache/getskill` |
209
282
 
210
- ```
211
- GET https://getskill.work/data/skills.json
212
- ```
283
+ 兼容旧写法:`getskill config set <URL>` 等价于 `getskill config set base-url <URL>`。
213
284
 
214
- 响应格式:
285
+ `config get` 输出示例:
215
286
 
216
- ```json
217
- {
218
- "updated": "2026-11-20",
219
- "skills": [
220
- {
221
- "id": "pdf-extract",
222
- "name": "pdf-extract",
223
- "description": "从 PDF 文件中提取文本和表格",
224
- "category": "文档处理",
225
- "tags": ["pdf", "提取"],
226
- "version": "1.0.0",
227
- "author": "Anthropic",
228
- "updated": "2026-11-20",
229
- "file": "skills/pdf-extract.zip",
230
- "size": 173410,
231
- "source": "https://github.com/anthropics/skills"
232
- }
233
- ]
234
- }
235
287
  ```
236
-
237
- ### 技能 ZIP 包
238
-
239
- ```
240
- GET https://getskill.work/skills/<id>.zip
288
+ base-url: https://getskill.work
289
+ 来源: 默认值,未保存,使用默认站点
290
+ agent: claude (Claude Code)
291
+ 来源: 配置文件,已保存: claude
292
+ skills-dir: C:\Users\<用户名>\.claude\skills
293
+ 来源: 配置文件,未单独保存,由 agent 推导
294
+ cache-dir: C:\Users\<用户名>\.getskill\cache
295
+ 来源: 默认值,未保存,使用默认缓存目录
296
+ 配置文件: C:\Users\<用户名>\.getskill\config.json
297
+ 状态文件: C:\Users\<用户名>\.getskill\state.json
241
298
  ```
242
299
 
243
- ZIP 包根目录(或唯一包装目录)下应包含 `SKILL.md` 及配套文件。
244
-
245
- ## 编程接口
246
-
247
- ```javascript
248
- const getskill = require('@workskills/getskill');
300
+ ### 环境变量
249
301
 
250
- // 设置自定义索引地址(可选)
251
- getskill.setBaseUrl('https://your-custom-index.com');
302
+ | 变量 | 作用 |
303
+ | ---------------------- | ------------------------------------------------ |
304
+ | `GETSKILL_BASE_URL` | 覆盖索引站点地址 |
305
+ | `GETSKILL_AGENT` | 覆盖目标 Agent(预设名或 `auto`) |
306
+ | `GETSKILL_SKILLS_DIR` | 覆盖技能目录(任意 Agent) |
307
+ | `GETSKILL_CACHE_DIR` | 覆盖缓存目录 |
308
+ | `GETSKILL_HOME` | 覆盖 `~/.getskill`(配置/状态/缓存的根目录) |
309
+ | `GETSKILL_STATE_FILE` | 覆盖安装记录文件路径 |
310
+ | `GETSKILL_RESTART_CMD` | 安装/更新后执行的重载命令(任意 Agent 均可用) |
311
+ | `GETSKILL_LOG_LEVEL` | 日志级别:`silent`/`error`/`warn`/`info`/`debug` |
252
312
 
253
- // 搜索技能(基于静态索引)
254
- const results = await getskill.searchSkills('pdf');
313
+ Bash / zsh:
255
314
 
256
- // 安装技能(下载 ZIP + 解压 + 复制)
257
- const result = await getskill.downloadSkill('pdf-extract');
258
- console.log(result.files); // 已复制的技能目录列表
259
-
260
- // 更新技能(版本比较)
261
- await getskill.updateSkill('pdf-extract');
262
-
263
- // 列出本地技能
264
- const skills = getskill.listLocalSkills();
265
-
266
- // 获取目录
267
- const skillsDir = getskill.getSkillsDirectory();
268
- const cacheDir = getskill.getSkillsCacheDirectory();
269
-
270
- // 获取当前索引地址
271
- const baseUrl = getskill.getBaseUrl();
315
+ ```bash
316
+ GETSKILL_SKILLS_DIR=~/.my-agent/skills getskill install pdf-toolkit
272
317
  ```
273
318
 
274
- ## 技能包规范
319
+ Windows PowerShell:
275
320
 
276
- 技能 ZIP 包应包含:
277
-
278
- - `SKILL.md` 技能定义文件(含 front matter 与指令内容)
279
- - 可选的 `README.md` 说明文档
280
- - 可选的示例代码、脚本或配置文件
281
-
282
- 示例结构:
283
-
284
- ```
285
- pdf-extract/
286
- ├── SKILL.md # 技能定义文件(必需)
287
- ├── README.md # 说明文档(可选,会随目录复制)
288
- ├── scripts/ # 脚本(可选,会随目录复制)
289
- └── examples/ # 示例(可选,会随目录复制)
321
+ ```powershell
322
+ $env:GETSKILL_SKILLS_DIR = "$HOME\.my-agent\skills"; getskill install pdf-toolkit
290
323
  ```
291
324
 
292
- ## 依赖
325
+ ### 优先级
293
326
 
294
- - Node.js >= 12(运行 CLI)
295
- - Node.js 18+(开发与测试工具)
327
+ 命令行参数(`--agent` / `--skills-dir` / `--cache-dir` / `--base-url`) > 环境变量 > 配置文件 > 自动识别 / 默认值。
296
328
 
297
- ## 开发与质量保障
329
+ ## 目录结构
298
330
 
299
- ```bash
300
- npm install
301
- npm run build
302
- npm run lint
303
- npm test
304
- npm run test:flow
305
- npm run coverage
306
331
  ```
332
+ ~/.getskill/
333
+ ├── config.json # 持久化配置
334
+ ├── state.json # 安装记录(技能名、版本、安装目录)
335
+ └── cache/
336
+ ├── skills-index.json # 技能索引缓存(TTL 1 天)
337
+ └── pdf-toolkit/ # ZIP 解压后的技能包内容
307
338
 
308
- 当前源码已迁移为 **TypeScript**,发布产物位于 `dist/`。
309
-
310
- 开发文档:
311
-
312
- - [`CONTRIBUTING.md`](CONTRIBUTING.md)
313
- - [`docs/architecture.md`](docs/architecture.md)
314
-
315
- ## 许可证
316
-
317
- MIT
318
-
319
- ## 作者
320
-
321
- getskill.work
339
+ ~/.claude/skills/ # 当前 Agent 的技能目录(随 agent/skills-dir 配置变化)
340
+ └── pdf-toolkit/
341
+ └── SKILL.md
342
+ ```
@@ -1,9 +1,94 @@
1
+ export declare const DEFAULT_BASE_URL = "https://getskill.work";
1
2
  export declare const REQUEST_TIMEOUT_MS = 60000;
3
+ export declare const SKILLS_INDEX_CACHE_TTL_MS: number;
2
4
  export declare const MAX_COPY_FILE_SIZE_BYTES: number;
3
- export declare function setBaseUrl(url: string): string;
5
+ export declare const AUTO_AGENT_NAME = "auto";
6
+ export declare const CUSTOM_AGENT_NAME = "custom";
7
+ export declare const DEFAULT_AGENT_NAME = "claude";
8
+ export interface AgentPreset {
9
+ name: string;
10
+ label: string;
11
+ skillsPathSegments: string[];
12
+ restartCommand?: string;
13
+ }
14
+ /**
15
+ * 支持的 Agent 目录约定。任何 Agent 都可以通过 agent 预设、
16
+ * skillsDir 自定义目录或 GETSKILL_SKILLS_DIR 环境变量接入。
17
+ */
18
+ export declare const AGENT_PRESETS: AgentPreset[];
19
+ export type ConfigKey = 'baseUrl' | 'agent' | 'skillsDir' | 'cacheDir';
20
+ export type ConfigSource = 'cli' | 'env' | 'file' | 'detect' | 'default';
21
+ export interface PersistedConfig {
22
+ baseUrl?: string;
23
+ agent?: string;
24
+ skillsDir?: string;
25
+ cacheDir?: string;
26
+ }
27
+ export interface ResolvedConfig {
28
+ baseUrl: string;
29
+ agent: string;
30
+ agentLabel: string;
31
+ skillsDir: string;
32
+ cacheDir: string;
33
+ homeDir: string;
34
+ configFile: string;
35
+ stateFile: string;
36
+ restartCommand: string | null;
37
+ sources: Record<ConfigKey, ConfigSource>;
38
+ }
39
+ export interface AgentSummary {
40
+ name: string;
41
+ label: string;
42
+ skillsDir: string;
43
+ exists: boolean;
44
+ active: boolean;
45
+ restartCommand: string | null;
46
+ }
47
+ export declare function normalizePath(value: string): string;
48
+ export declare function isSamePath(left: string, right: string): boolean;
49
+ export declare function normalizeBaseUrl(url: string): string;
50
+ export declare function normalizeConfigKey(key: string): ConfigKey;
51
+ export declare function getHomeDirectory(): string;
52
+ export declare function getGetSkillHome(): string;
53
+ export declare function getConfigFilePath(): string;
54
+ export declare function getStateFilePath(): string;
55
+ export declare function getLegacyStateFilePaths(): string[];
56
+ export declare function readConfigFile(): PersistedConfig;
57
+ export declare function writeConfigFile(config: PersistedConfig): void;
58
+ export declare function getAgentPreset(name?: string | null): AgentPreset | null;
59
+ export declare function getPresetSkillsDir(preset: AgentPreset): string;
60
+ /**
61
+ * 自动识别当前机器上正在使用的 Agent 技能目录。
62
+ * 优先级:历史安装记录 > 已存在且非空的技能目录 > 已存在的 Agent 根目录 > 默认值。
63
+ */
64
+ export declare function detectAgentName(): string;
65
+ export declare function refreshConfig(): void;
66
+ /** 仅作用于当前进程的临时覆盖(例如 CLI 的 --agent / --skills-dir 参数)。 */
67
+ export declare function applyRuntimeOverrides(overrides: PersistedConfig): void;
68
+ export declare function clearRuntimeOverrides(): void;
69
+ export declare function resolveConfig(): ResolvedConfig;
70
+ export declare function getConfigSummary(): ResolvedConfig;
4
71
  export declare function getBaseUrl(): string;
5
- export declare function getOpenClawRootDirectory(): string;
6
72
  export declare function getSkillsDirectory(): string;
73
+ /**
74
+ * 安装/更新的安全门禁:技能目录必须显式指定
75
+ * (agent 或 skills-dir 来自 CLI 参数 / 环境变量 / 配置文件均可)。
76
+ * 若目录仅来自自动探测(detect),则拒绝写入,
77
+ * 避免把技能装到非当前 Agent 的技能目录。
78
+ */
79
+ export declare function assertExplicitSkillsDir(): ResolvedConfig;
7
80
  export declare function getSkillsCacheDirectory(): string;
8
- export declare function getGetSkillConfigDirectory(): string;
9
- export declare function getStateFilePath(): string;
81
+ export declare function getAgentName(): string;
82
+ export declare function getAgentLabel(): string;
83
+ export declare function getAgentRestartCommand(): string | null;
84
+ export declare function listAgents(): AgentSummary[];
85
+ /** 历史版本(2.0 及更早)遗留的缓存目录,`clean` 命令会一并清理。 */
86
+ export declare function getLegacyCacheDirectories(): string[];
87
+ /** 写入并持久化配置项,返回写入后的完整生效配置。 */
88
+ export declare function setConfigValue(key: ConfigKey | string, rawValue: string): ResolvedConfig;
89
+ /** 删除已持久化的配置项,恢复为环境变量 / 自动识别 / 默认值。 */
90
+ export declare function unsetConfigValue(key: ConfigKey | string): ResolvedConfig;
91
+ export declare function setBaseUrl(url: string): string;
92
+ export declare function setAgent(name: string): string;
93
+ export declare function setSkillsDir(dir: string): string;
94
+ export declare function setCacheDir(dir: string): string;