xskill.schema.json — 工具配置
用于 ~/.xskill/settings.json，定义完整配置结构。
顶层字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
$schema | string | 否 | JSON Schema URL，用于编辑器校验。config --init 自动生成 |
platforms | object<string, Platform> | 否 | 平台配置，以平台标识符为键（如 "claude"、"codex"） |
sources | Source[] | 否 | 技能源仓库 |
recommended | RecommendedSource[] | 否 | 按源分组的推荐技能集 |
cache | CacheConfig | 否 | 缓存配置 |
registry | RegistryConfig | 否 | 注册中心配置 |
proxy | string | 否 | 代理地址。设置后导出 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY（含小写形式）环境变量，git clone 与 curl/wget 自动生效。协议支持 http、https、socks5、socks5h、socks4、socks4a（socks5h/socks4a 由代理端解析 DNS）。 |
Platform（platforms.*）：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
path | string | 是 | — | 工具配置目录（相对路径、绝对路径或 ~/...）。最少 1 字符 |
skills | string | 否 | "" | skills 子目录名（相对于 path）。为空则跳过技能安装 |
agents | string | 否 | "" | agents 配置文件名（相对于 path）。为空则跳过 agents 安装 |
source | string | 否 | "AGENTS.md" | 固定 .agents/ 目录下的源文件名。<path>/<agents> 符号链接至 .agents/<source> |
agents_compat | boolean | 否 | false | 是否兼容 .agents/ 资源。为 true 时直接读取规范目录，跳过 symlink 操作 |
Source（sources[]）：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 否 | "" | 唯一标识符。正则：^[a-zA-Z0-9_/-]+$（支持 user/repo 格式）。留空或无效时自动使用 url 作为名称 |
type | string | 否 | "git" | 源类型。枚举："git"、"api" |
url | string | 是 | — | 源仓库 URL。须以 http:// 或 https:// 开头 |
RecommendedSource（recommended[]）：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 否 | "" | 源名称，引用 sources 中的条目，或自定义标签 |
url | string | 否 | "" | 直接源 URL（当 name 在 sources 中未找到时作为回退） |
skills | string[] | 是 | — | 推荐技能名称列表。至少 1 项 |
CacheConfig（cache）：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
enabled | boolean | 否 | false | 启用技能列表缓存。启用后 query 和 find 从本地缓存读取 |
ttl | integer | 否 | 600 | 缓存有效期（秒），默认 10 分钟。同时作用于主缓存（skills.json）和 URL 缓存（source_<md5>.json）。最小值：0 |
RegistryConfig（registry）：
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
enabled | boolean | 否 | false | 启用注册中心查询。启用后 query 和 find 会额外查询注册中心 |
url | string | 否 | "https://xskill.gcli.cn/skills.json" | 注册中心地址。支持裸域名、目录路径或完整文件路径 |