openskills 版本演进全解:从 CHANGELOG 追溯 v1.0.0 至 v1.5.0 的功能、安全与 CLI 实现细节

原创2026-10-13 17:27:341,892 阅读
文章标签:开发工具AI 技能CLI

openskills 版本演进全解:从 CHANGELOG 追溯 v1.0.0 至 v1.5.0 的功能、安全与 CLI 实现细节

openskills 是一个面向 AI 编码代理的通用 skills 加载器,其 CHANGELOG.md 完整记录了项目从 v1.0.0(2025-10-26)到 v1.5.0(2026-01-17)共 9 个版本的演进轨迹。本文以该变更记录为主体,逐版本还原每个新增能力、行为变更与安全修复的设计意图,并结合当前仓库源码(src/cli.ts、src/commands/update.ts 等)印证这些条目背后的真实实现,帮助你不仅知道"改了什么",还理解"为什么这么改、现在该如何用"。

一、变更记录的格式与版本约定

CHANGELOG.md 开篇声明了两条约定:

  • 格式基于 Keep a Changelog(每个版本分为 Added / Changed / Fixed / Security 等分类);
  • 版本号遵循 Semantic Versioning(语义化版本)规范。

当前仓库中 package.json 声明的版本为 1.5.0,与 CHANGELOG 的最新条目一致,说明本仓库快照即 v1.5.0 代码。这意味着以下所有源码分析都对应 changelog 的最终状态。

二、v1.0.0(2025-10-26):初始发布与核心命令集

CHANGELOG 记录 v1.0.0 是 Initial release,一次性确立了项目的全部核心命令与核心特性:

npx openskills install <source>   # Install skills from GitHub repos
npx openskills sync               # Generate <available_skills> XML for AGENTS.md
npx openskills list               # Show installed skills
npx openskills read <name>        # Load skill content for agents
npx openskills manage             # Interactive skill removal
npx openskills remove <name>      # Remove specific skill

以及四项关键特性:

  • 交互式 TUI:所有命令均支持交互式选择;
  • Anthropic 的 SKILL.md 格式:技能以带 YAML frontmatter 的 Markdown 文件定义;
  • Progressive disclosure(渐进式披露):技能按需加载,而非全部塞进上下文;
  • Bundled resources 支持:技能可携带 references/、scripts/、assets/ 子目录。

对照源码可逐条印证。src/cli.ts 使用 commander 注册了 install、read、update、sync、manage、remove(别名 rm)六个子命令,其中 update 是 v1.5.0 之后才出现的,其余均为 v1.0.0 遗产。交互式能力来自 @inquirer/prompts 依赖(见 package.json 的 dependencies),而 read 命令的输出格式(Reading: <name> / Base directory: ... / 内容 / Skill read: <name>)在 src/commands/read.ts 中实现,注释明确写着 "Output in Claude Code format",与 changelog 所述的"与 Claude Code 同格式"一致。

v1.0.0 的 remove 命令实现极为精简,见 src/commands/remove.ts:先通过 findSkill 按目录优先级定位技能,再 rmSync 删除整个技能目录,并回显技能来自 global 还是 project 位置。

三、v1.1.0 → v1.2.1(2025-10-27):--universal 与"项目级默认安装"的转向

v1.1.0:README 重构与 location 标签修复

  • Added:单页综合 README(含技术详解)与 Claude Code 的并排对比;
  • Fixed:location 标签现在根据实际安装位置正确显示 project 或 global。

从源码结构看,location 的判定逻辑在 src/utils/skills.ts 的 findAllSkills 中:const isProjectLocal = dir.includes(process.cwd()),即技能目录路径包含当前工作目录就标记为 project,否则为 global。这个标签会直接影响 list 命令的分组展示(src/commands/list.ts 按 project 优先排序并打印 Summary: X project, Y global),也会写入 sync 生成的 XML 的 <location> 字段。

v1.2.0:--universal 标志与默认值变更

CHANGELOG 记录这是安装目标目录的一次重要调整:

  • Added:新增 --universal 标志,将技能安装到 .agent/skills/ 而非 .claude/skills/,面向 Claude Code + Cursor/Windsurf/Aider 的多代理场景,避免与 Claude Code 原生 marketplace 插件冲突;
  • Changed:项目级安装成为默认行为(此前是全局),技能默认安装到 ./.claude/skills/。

对应实现见 src/commands/install.ts:

const folder = options.universal ? '.agent/skills' : '.claude/skills';
const isProject = !options.global; // Default to project unless --global specified
const targetDir = isProject
  ? join(process.cwd(), folder)
  : join(homedir(), folder);

--universal 决定目录名(.agent/skills vs .claude/skills),而"项目级默认"由 !options.global 体现——不传 --global 就装到 process.cwd() 下。目录解析的单一事实来源在 src/utils/dirs.ts,其 getSearchDirs 定义的搜索优先级为:

  1. ./.agent/skills/(项目 universal)
  2. ~/.agent/skills/(全局 universal)
  3. ./.claude/skills/(项目)
  4. ~/.claude/skills/(全局)

这一优先级决定了 list、read、sync 在多个位置存在同名技能时的取舍(src/utils/skills.ts 用 seen 集合按此顺序去重)。

v1.2.1:文档修复

仅一条 Fixed:清理 README 中重复的章节和不正确的 flag 说明——属于文档层修正,不涉及代码行为。

四、v1.3.0(2025-12-14):功能大版本——符号链接、可配置输出、本地/私有源与安全加固

这是 CHANGELOG 中条目最多的一个版本,涵盖四类能力扩展、两项行为变更与三项安全修复。

4.1 符号链接支持(Symlink support)

  • 技能目录现在可以是符号链接,指向 git clone 下来的技能仓库即可实现"git 更新即技能更新",也支持本地技能开发工作流;
  • 失效的符号链接(broken symlink)会被优雅跳过而非报错。

实现在 src/utils/skills.ts 的 isDirectoryOrSymlinkToDirectory:

if (entry.isSymbolicLink()) {
  try {
    const stats = statSync(fullPath); // statSync follows symlinks
    return stats.isDirectory();
  } catch {
    // Broken symlink or permission error
    return false;
  }
}

statSync 会跟随链接解析目标,解析失败(链接指向不存在的路径)时返回 false,该条目即被跳过——与 changelog 描述的 "Broken symlinks are gracefully skipped" 完全对应。相关测试用例位于 tests/utils/skills.test.ts。

4.2 sync 命令的可配置输出路径(--output / -o)

  • 可将技能清单同步到任意 .md 文件(例如 .ruler/AGENTS.md),不再局限于 AGENTS.md;
  • 目标文件不存在时自动创建,并写入一个以文件名派生的标题(heading);
  • 自动创建所需的嵌套目录。

三项行为都能在 src/commands/sync.ts 中逐一找到:

const outputPath = options.output || 'AGENTS.md';
if (!outputPath.endsWith('.md')) {
  console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
  process.exit(1);
}
if (!existsSync(outputPath)) {
  const dir = dirname(outputPath);
  if (dir && dir !== '.' && !existsSync(dir)) {
    mkdirSync(dir, { recursive: true });   // 自动创建嵌套目录
  }
  writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`);  // 自动创建带标题的文件
}

注意源码中比 changelog 多出一条约束:输出文件必须是 .md 扩展名,否则直接退出——这是文档未展开的实操细节。写入目标文件的具体内容生成与区段替换逻辑(<skills_system> XML 与 <!-- SKILLS_TABLE_START --> 标记的双轨替换)在 src/utils/agents-md.ts 中实现,并有专门的单测覆盖(tests/commands/sync.test.ts 验证了 <usage> 说明、<location> 标签与空技能列表等场景)。

4.3 本地路径安装(Local path installation)

  • 支持绝对路径(/path/to/skill)、相对路径(./skill、../skill)与波浪号展开(~/my-skills/skill)。

src/commands/install.ts 中的判定与展开逻辑:

function isLocalPath(source: string): boolean {
  return (
    source.startsWith('/') ||
    source.startsWith('./') ||
    source.startsWith('../') ||
    source.startsWith('~/')
  );
}
function expandPath(source: string): string {
  if (source.startsWith('~/')) {
    return join(homedir(), source.slice(2));
  }
  return resolve(source);
}

本地安装时,若目录内含 SKILL.md 则按单技能处理,否则按"技能集合目录"递归扫描(installFromRepo 复用了同一套扫描逻辑),这也解释了为什么本地多技能目录和 git 仓库的安装流程是统一的。

4.4 私有 git 仓库支持

  • 支持 SSH URL(git@github.com:org/private-skills.git)、带认证的 HTTPS;
  • 自动使用系统 SSH 密钥。

isGitUrl 识别 git@、git://、http(s):// 前缀或 .git 后缀的完整 URL;克隆命令为 git clone --depth 1(浅克隆,见 src/commands/install.ts 与 src/commands/update.ts),认证完全依赖本机 git 的 SSH key/凭据配置,克隆失败时会提示 "Tip: For private repos, ensure git SSH keys or credentials are configured"。

4.5 全面测试套件

CHANGELOG 记录该版本建立了 "88 tests across 6 test files"(涵盖符号链接检测、YAML 解析的单元测试,install/sync 集成测试,以及完整 CLI 工作流的 E2E 测试)。当前仓库中测试文件已扩展为 9 个:tests/commands/ 下的 install/sync/update 命令测试、tests/integration/e2e.test.ts(直接 node dist/cli.js 跑真实 CLI 流程)以及 tests/utils/ 下的 dirs/skill-metadata/skill-names/skills/yaml 工具层单测。

4.6 Changed:--yes 全面跳过提示

  • --yes 现在跳过所有交互式提示,实现完全非交互模式(CI/CD 场景);
  • 覆盖已存在技能时不再询问,而是打印 Overwriting: <skill-name>;
  • 所有命令均可在无头环境运行。

对应 src/commands/install.ts 中的冲突处理:

async function warnIfConflict(..., skipPrompt = false) {
  if (existsSync(targetPath)) {
    if (skipPrompt) {
      console.log(chalk.dim(`Overwriting: ${skillName}`));  // 与 changelog 描述的提示文本一致
      return true;
    }
    const shouldOverwrite = await confirm({ ... });
    ...

--yes 在 src/cli.ts 中注册于 install 与 sync 两个命令;sync 的非交互路径则跳过 checkbox 选择、直接同步全部技能(src/commands/sync.ts 的 if (!options.yes) 分支)。

CHANGELOG 还提到 CI workflow 调整:build 步骤移到 tests 之前,确保 dist/cli.js 存在以支撑 E2E 测试——这一点可由 tests/integration/e2e.test.ts 中 const cliPath = join(process.cwd(), 'dist', 'cli.js') 得到印证。

4.7 Security:三项安全修复

这是该版本最值得单独展开的条目,每项都有明确落点:

  1. 路径穿越防护(Path traversal protection):校验安装路径必须落在目标目录内。src/commands/install.ts 与 src/commands/update.ts 中的 isPathInside 用 resolve + 目录分隔符前缀判断实现,越界时打印 Security error: Installation path outside target directory 并终止——这条错误信息后来成为 v1.3.1 Windows 修复的锚点。

  2. 符号链接解引用(Symlink dereference):cpSync 统一使用 dereference: true,拷贝的是链接目标内容而非链接本身,保证安装出的技能是普通文件树。

  3. 非贪婪 YAML 正则(Non-greedy YAML regex):防止 frontmatter 解析的潜在 ReDoS。看 src/utils/yaml.ts 的现态:

export function extractYamlField(content: string, field: string): string {
  const match = content.match(new RegExp(`^${field}:\\s*(.+?)$`, 'm'));
  return match ? match[1].trim() : '';
}

(.+?) 的非贪婪量词正是这条安全修复的直接产物,相关边界用例在 tests/utils/yaml.test.ts。

五、v1.3.1 / v1.3.2 / v1.4.0(2026-01-17):跨平台修复与文档收敛

三个小版本同日发布,分别处理修复、文档与措辞:

v1.3.1(Fixed)

  • Windows 安装:路径校验在 Windows 上生效。Security error: Installation path outside target directory 是该修复的标志性报错——问题在于 Linux 下 isPathInside 的分隔符前缀判断在 Windows 上会因分隔符差异误判,修复后的实现使用 path.sep 拼接(见 src/commands/install.ts:resolvedTargetDir.endsWith(sep) ? ... : resolvedTargetDir + sep);
  • CLI 版本号:npx openskills --version 从 package.json 读取。src/cli.ts 中 createRequire(import.meta.url) 加载 ../package.json 的 version 字段并传给 commander 的 .version();
  • 仓库根 SKILL.md:根目录直接放 SKILL.md 的单技能仓库现在能正确安装。对应 src/commands/install.ts 中 installFromRepo 开头对 join(repoDir, 'SKILL.md') 的专门检查:命中后优先从 frontmatter 的 name 字段取名(extractYamlField(content, 'name')),其次回退到仓库名。

v1.3.2(Changed)

  • 文档与 AGENTS.md 生成文本统一使用 npx openskills 前缀展示所有命令示例——这一约定仍保留在 src/utils/agents-md.ts 的 <usage> 文本中(Invoke: npx openskills read <skill-name>),意味着即便全局安装,给 Agent 看的调用指引也是 npx 形式,保证零依赖可执行。

v1.4.0(Changed)

  • README 澄清"项目级默认安装"并删除冗余的 sync 说明;
  • 安装器输出消息明确区分项目级默认与 --global。对应 src/commands/install.ts 中的双提示:
if (isProject) {
  console.log(chalk.dim(`Default install is project-local (${projectLocation}). Use --global for ${globalLocation}.`));
} else {
  console.log(chalk.dim(`Global install selected (${globalLocation}). Omit --global for ${projectLocation}.`));
}

六、v1.5.0(2026-01-17):openskills update 与来源元数据追踪

最新版本的三条 Added/Changed 记录围绕同一主题:让安装过的技能可以被可靠地刷新。

6.1 来源元数据追踪(Source metadata tracking)

安装时现在会为每个技能记录来源信息,物理落盘为技能目录下的 .openskills.json。定义在 src/utils/skill-metadata.ts:

export const SKILL_METADATA_FILE = '.openskills.json';
export interface SkillSourceMetadata {
  source: string;          // 用户传入的原始 source
  sourceType: 'git' | 'github' | 'local';
  repoUrl?: string;        // git 来源的克隆地址
  subpath?: string;       // 技能在仓库内的相对子路径
  localPath?: string;      // local 来源的本地目录
  installedAt: string;     // ISO 时间戳
}

写入时机在 src/commands/install.ts 的每条安装路径末尾:cpSync 拷贝完成后立即 writeSkillMetadata(targetPath, ...)。git 来源记录 repoUrl + subpath(subpath 由 relative(repoDir, skillDir) 计算),local 来源记录 localPath。有了这份元数据,update 才知道"去哪取新版本"。

6.2 openskills update 命令

CHANGELOG 记录其为 "Refresh installed skills from their recorded source (default: all)",并在 src/cli.ts 中注册为 update [skill-names...]。完整流程(src/commands/update.ts):

  1. 解析目标:normalizeSkillNames 处理传入的名称列表;不传参数则默认更新全部已安装技能,传了参数则只更新匹配项,未匹配的打印 Skipping missing skills: ...;
  2. 读取元数据:readSkillMetadata(skill.path) 返回 null(即没有 .openskills.json)时跳过并提示 Skipped: <name> (no source metadata; re-install once to enable updates)——这正是 CHANGELOG 中 Fixed 条目 "Update UX - Skips skills without source metadata and lists them for re-install" 的实现,结尾还会汇总打印 Missing source metadata (N): ... 并给出重装建议;
  3. local 来源分支:检查 localPath 存在且含 SKILL.md,直接 updateSkillFromDir 重新拷贝并刷新 installedAt;
  4. git 来源分支:在 ~/.openskills-temp-<timestamp> 临时目录执行 git clone --depth 1 --quiet <repoUrl>,按元数据 subpath 定位技能目录,验证 SKILL.md 存在后覆盖安装,finally 中无条件清理临时目录;
  5. 汇总输出:Summary: X updated, Y skipped (Z total),并按失败原因分类列出(缺元数据 / local 源丢失 / local 缺 SKILL.md / 缺 repo URL / 仓库中 SKILL.md 缺失 / clone 失败)。

覆盖安装用的 updateSkillFromDir 同样带有 isPathInside 安全校验和 cpSync(..., { recursive: true, dereference: true }),与 v1.3.0 的安全基线保持一致。

测试层面,tests/commands/update.test.ts 用临时目录 + 伪 HOME 验证了两条核心路径:local 来源技能能从记录的源目录刷新(v1 → v2),无元数据的技能被跳过且原文件不被删除——"跳过不破坏"是 update 命令的重要语义保证。

6.3 read 支持逗号分隔的多个技能名

CHANGELOG 记录 "Multi-skill read - openskills read supports comma-separated names"。实现在 src/utils/skill-names.ts:

export function normalizeSkillNames(input: string[] | string | undefined): string[] {
  if (!input) return [];
  const raw = Array.isArray(input) ? input : [input];
  const names = raw.flatMap((name) => name.split(','));  // 逗号拆分
  const cleaned = names.map((name) => name.trim()).filter(Boolean);
  return Array.from(new Set(cleaned));                   // 去重
}

因此 npx openskills read pdf,xlsx 与 npx openskills read pdf xlsx 等价(commander 的 read <skill-names...> 变长参数 + 逗号拆分 + 去重)。src/commands/read.ts 对每个名字逐个 findSkill,任一缺失则整体报错并列出四个搜索目录,全部命中则依次输出每个技能的完整内容,供 Agent 一次拉取多个技能。同一 normalizeSkillNames 也服务于 update 命令,保证两个命令的名称解析行为一致。

6.4 配套改动

  • Generated usage text:sync 写入 AGENTS.md 的 <usage> 文本澄清了 shell 调用方式("run in your shell"),并补充了多技能用法示例(见 src/utils/agents-md.ts 第 43–44 行);
  • README:新增 update 使用指引与人类使用提示(对应 README.md 的 "Updating Skills" 与 "Tips" 章节)。

七、版本变更速查表

版本 日期 关键变更
1.0.0 2025-10-26 初始发布:install / sync / list / read / manage / remove 六命令;SKILL.md 格式、渐进式披露、bundled resources
1.1.0 2025-10-27 单页 README 与 Claude Code 对比;location 标签正确显示 project/global
1.2.0 2025-10-27 新增 --universal(安装到 .agent/skills/);项目级安装成为默认
1.2.1 2025-10-27 README 清理重复章节与错误 flag
1.3.0 2025-12-14 符号链接支持;sync 的 --output/-o;本地路径安装;私有 git 仓库;88 测试 / 6 测试文件;--yes 全非交互;路径穿越防护、dereference 拷贝、非贪婪 YAML 正则
1.3.1 2026-01-17 Windows 路径校验修复;--version 读 package.json;仓库根 SKILL.md 可安装
1.3.2 2026-01-17 文档与生成文本统一使用 npx openskills 前缀
1.4.0 2026-01-17 文档澄清项目级默认;安装提示明确区分 project vs --global
1.5.0 2026-01-17 新增 openskills update;安装记录 .openskills.json 来源元数据;read 支持逗号分隔多技能;无元数据技能被跳过并列出待重装

八、实操要点:这些版本变更意味着什么

结合 changelog 与源码,面向使用者可以归纳出四条可操作的结论:

  1. 元数据是 update 的前提:v1.5.0 之前安装的技能没有 .openskills.json,npx openskills update 会跳过并在结尾列出它们——重装一次即可补齐元数据。这是 CHANGELOG "Fixed: Update UX" 条目给出的官方迁移路径。
  2. CI 环境一律加 --yes:自 v1.3.0 起 install / sync 在 -y 下完全无提示,覆盖已有技能时打印 Overwriting: <name> 后继续,适合流水线批量执行。
  3. sync -o 让技能清单可以落地到任意 markdown 文件(必须是 .md,源码强制校验),例如同步到 .ruler/AGENTS.md 之类的自定义约定文件,缺失的目录与文件会自动创建。
  4. 符号链接 + 本地源是本地开发技能的推荐姿势:把技能仓库 ln -s 进 .claude/skills/(或从本地路径安装),源码改动即时生效;update 命令的 local 分支也能直接从记录的 localPath 重新同步。

从源码结构看,整个演进脉络是清晰的:v1.0.0 确立命令面,v1.2.0 修正安装位置的默认语义,v1.3.0 补齐来源多样性(本地/私有/符号链接)与安全基线,v1.3.1–1.4.0 收敛跨平台与文档问题,v1.5.0 通过来源元数据把"安装"升级为"可维护的生命周期"。对维护者与集成方而言,CHANGELOG.md 中每条条目基本都能在 src/ 或 tests/ 中找到对应实现与验证,这也是这份变更记录可读性与可信度兼得的原因。

登录后查看全文
openskills