pnpm-plugin-skills 0.0.1

package/.aiden/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@superpowers-dev": true
+  }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pnpm-plugin-skills",
+  "version": "0.0.1",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/plans/20260330-init.md

@@ -0,0 +1,530 @@
+# 20260330-init
+
+## 目标
+
+做一个独立的 npm CLI 包，定位类似 pnpm 的 skill package manager。
+
+`0.1.0` 版本目标：
+
+1. 提供 `skills add` / `skills install`
+2. 生成并维护 `skills.json`
+3. 生成并维护 `skills-lock.yaml`
+4. 能通过 `pnpm` 的 `configDependencies` 集成，在 `pnpm install` 时自动安装 skills
+
+## 参考命令
+
+```sh
+npx skills add rstackjs/agent-skills --skill rspack-best-practices
+```
+
+## 已确认设计
+
+### 包结构
+
+仓库采用 monorepo 结构：
+
+```text
+packages/
+  skills-pm/
+  pnpm-plugin-skills/
+```
+
+- `packages/skills-pm`
+  - npm 包名：`skills-pm`
+  - 提供 CLI 命令：`skills add`、`skills install`
+  - 内含核心实现：manifest / lock / resolver / installer
+- `packages/pnpm-plugin-skills`
+  - npm 包名：`pnpm-plugin-skills`
+  - 用于 `pnpm-workspace.yaml > configDependencies`
+  - 在 `pnpm install` 时调用与 `skills install` 等价的安装逻辑
+  - 只能在源码/构建层复用 `skills-pm` 的核心实现，发布后不能在运行时依赖 `skills-pm`
+
+### 首版命令范围
+
+只做：
+
+- `skills add`
+- `skills install`
+
+首版不做：
+
+- `remove`
+- `list`
+- `prune`
+- skill 之间的依赖解析
+
+### 与 pnpm 的集成
+
+集成点采用 `pnpm-workspace.yaml` 的 `configDependencies`，而不是 `package.json`。
+
+目标使用方式：
+
+```yaml
+configDependencies:
+  pnpm-plugin-skills: "0.1.0+<integrity>"
+```
+
+然后执行：
+
+```sh
+pnpm install
+```
+
+由 `pnpm-plugin-skills` 自动读取项目根目录的 `skills.json` / `skills-lock.yaml`，完成安装。
+
+### pnpm 插件 hook 设计
+
+基于 pnpm 10 的 hooks 设计，`pnpm-plugin-skills` 推荐使用 `preResolution` 作为自动安装入口：
+
+```js
+module.exports = {
+  hooks: {
+    async preResolution(options) {
+      // 基于 options.lockfileDir 定位 workspace root
+      // 执行一次与 `skills install` 等价的逻辑
+    }
+  }
+}
+```
+
+选择 `preResolution` 的原因：
+
+- 能拿到 `lockfileDir`，便于定位项目根目录
+- 时机够早，适合在依赖解析前确保 skills 已同步
+- 比模块顶层副作用更清晰
+- 比 `updateConfig` 更符合用途
+
+插件侧安装逻辑必须满足：
+
+- 幂等
+- 快速 no-op
+- 没有 `skills.json` 时直接跳过
+- 有 `skills.json` 但没有 `skills-lock.yaml` 时失败
+
+### skills.json 结构
+
+采用尽量接近 `package.json` 的结构：
+
+```json
+{
+  "$schema": "https://unpkg.com/skills-pm/schema/skills.schema.json",
+  "installDir": ".agents/skills",
+  "linkTargets": [
+    ".cursor/skills"
+  ],
+  "skills": {
+    "rspack-best-practices": "https://github.com/vercel-labs/agent-skills.git#path:/skills/rspack-best-practices"
+  }
+}
+```
+
+字段含义：
+
+- `installDir`
+  - 默认值：`.agents/skills`
+- `linkTargets`
+  - 其他需要暴露 skill 的目录，采用软链形式同步
+- `skills`
+  - 类似 `dependencies`
+  - key 为 skill 名称
+  - value 为 specifier
+
+### skills-lock.yaml 结构
+
+锁文件负责保存可重放的解析结果，首版只记录安装所需事实。
+
+建议结构：
+
+```yaml
+lockfileVersion: '0.1'
+
+installDir: .agents/skills
+linkTargets:
+  - .cursor/skills
+
+skills:
+  rspack-best-practices:
+    specifier: https://github.com/vercel-labs/agent-skills.git#path:/skills/rspack-best-practices
+    resolution:
+      type: git
+      url: https://github.com/vercel-labs/agent-skills.git
+      commit: 6cb0992a176f2ca142e19f64dca8ac12025b035e
+      path: skills/rspack-best-practices
+    digest: sha256-xxxxx
+```
+
+### specifier 设计
+
+目标是尽量对齐 pnpm。
+
+已确认的方向：
+
+- Git/GitHub/GitLab 尽量使用 pnpm 风格：
+
+```text
+repo.git#ref&path:/relative/path
+repo.git#path:/relative/path
+```
+
+- file 类型也支持统一的 `#path:/...` 形式，便于解析器统一
+- git 类型在 manifest 中尽量保存为完整 `.git` URL，而不是自定义 `github:` 协议
+
+支持的输入类型：
+
+- GitHub shorthand
+- Full GitHub URL
+- 指向 repo 子目录的 GitHub URL
+- GitLab URL
+- 任意 git URL
+- 本地路径
+- npm 包形式
+
+示例：
+
+```sh
+npx skills add vercel-labs/agent-skills --skill rspack-best-practices
+npx skills add https://github.com/vercel-labs/agent-skills
+npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+npx skills add https://gitlab.com/org/repo
+npx skills add git@github.com:vercel-labs/agent-skills.git
+npx skills add ./my-local-skills
+```
+
+manifest 中的示例 specifier：
+
+```json
+{
+  "skills": {
+    "rspack-best-practices": "https://github.com/vercel-labs/agent-skills.git#path:/skills/rspack-best-practices",
+    "web-design-guidelines": "https://github.com/vercel-labs/agent-skills.git#main&path:/skills/web-design-guidelines",
+    "foo": "file:./my-local-skills#path:/skills/foo",
+    "foo-skill": "npm:@scope/skills-pack@1.2.3#path:/skills/foo-skill"
+  }
+}
+```
+
+### add 的职责
+
+`skills add <specifier> [--skill <name>]`：
+
+1. 解析用户输入
+2. 生成规范化 specifier
+3. 写入/更新 `skills.json`
+4. 解析来源并锁定结果
+5. 写入/更新 `skills-lock.yaml`
+
+边界：
+
+- `add` 负责“声明 + 锁定”
+- 同名 skill 且 specifier 变更时，默认报冲突，不静默覆盖
+- 对用户显式输入的 ref（如 `tree/main`）可保留在 manifest 中
+
+典型场景：
+
+#### repo + `--skill`
+
+```sh
+skills add vercel-labs/agent-skills --skill rspack-best-practices
+```
+
+可落盘为：
+
+```json
+{
+  "skills": {
+    "rspack-best-practices": "https://github.com/vercel-labs/agent-skills.git#path:/skills/rspack-best-practices"
+  }
+}
+```
+
+#### 直接 skill 子目录 URL
+
+```sh
+skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+```
+
+可落盘为：
+
+```json
+{
+  "skills": {
+    "web-design-guidelines": "https://github.com/vercel-labs/agent-skills.git#main&path:/skills/web-design-guidelines"
+  }
+}
+```
+
+#### 本地目录
+
+```sh
+skills add ./my-local-skills --skill foo
+```
+
+可落盘为：
+
+```json
+{
+  "skills": {
+    "foo": "file:./my-local-skills#path:/skills/foo"
+  }
+}
+```
+
+若用户直接传单个 skill 目录：
+
+```sh
+skills add ./my-local-skills/skills/foo
+```
+
+则可直接写为：
+
+```json
+{
+  "skills": {
+    "foo": "file:./my-local-skills/skills/foo"
+  }
+}
+```
+
+### install 的职责
+
+`skills install`：
+
+1. 读取 `skills.json` 和 `skills-lock.yaml`
+2. 校验 lock 覆盖当前声明
+3. 按 lock 物化安装到 `installDir`
+4. 为 `linkTargets` 创建软链
+
+边界：
+
+- `install` 只消费 lock，不重新解析来源
+- 锁过期或缺失时，报错并提示重新执行 `add`
+- 单个 skill 安装失败则整体失败
+
+### manifest 与 lock 一致性规则
+
+`install` 时需要验证：
+
+- `skills.json` 中每个 `skills[name]` 在 lock 中存在同名条目
+- lock 条目的 `specifier` 与 manifest 完全一致
+- lock 顶层 `installDir` / `linkTargets` 与 manifest 一致
+
+任一不一致，则视为 lock 失效。
+
+### 安装状态与快速跳过
+
+为避免在 plugin 模式下每次都执行完整安装，建议写入一个状态文件：
+
+```text
+.agents/skills/.skills-pm-install-state.json
+```
+
+示例：
+
+```json
+{
+  "lockDigest": "sha256-abc",
+  "installDir": ".agents/skills",
+  "linkTargets": [".cursor/skills"],
+  "installedAt": "2026-03-30T12:00:00.000Z",
+  "installerVersion": "0.1.0"
+}
+```
+
+每次自动安装时：
+
+1. 读取 `skills-lock.yaml`
+2. 计算整体 digest
+3. 与状态文件中的 `lockDigest` 对比
+4. 一致则直接跳过
+5. 不一致才真正执行安装
+
+### 安装目录与软链策略
+
+真实安装目录默认：
+
+```text
+.agents/skills/<skillName>
+```
+
+例如：
+
+```text
+.agents/
+  skills/
+    rspack-best-practices/
+      SKILL.md
+```
+
+若 `linkTargets` 包含 `.cursor/skills`，则采用“每个 skill 单独软链”的方式：
+
+```text
+.cursor/
+  skills/
+    rspack-best-practices -> ../../.agents/skills/rspack-best-practices
+```
+
+规则：
+
+- 每个 skill 单独建软链，不直接整体软链整个目录
+- 只覆盖本工具已管理的安装目录/软链
+- 不覆盖用户自己创建的普通文件或普通目录
+- 可在每个安装目录中写入 `.skills-pm.json` 作为管理标记
+- `0.1.0` 不做自动 prune / delete
+
+### skill 目录合法性检查
+
+安装一个 skill 前，首版至少检查：
+
+- 目标目录存在
+- 目录内包含 `SKILL.md`
+
+允许存在的附加资源包括：
+
+- `references/`
+- `scripts/`
+- `assets/`
+
+若目录存在但缺少 `SKILL.md`，报错示例：
+
+```text
+Invalid skill at <path>: missing SKILL.md
+```
+
+### 缓存策略
+
+建议使用项目内缓存目录：
+
+```text
+node_modules/.cache/skills-pm/
+```
+
+用于缓存：
+
+- git repo checkout / fetch 结果
+- npm tarball 解包结果
+- digest 结果
+- 规范化后的 source metadata
+
+### 错误处理与退出码
+
+`0.1.0` 先统一退出码：
+
+- 成功：`0`
+- 失败：`1`
+
+典型失败类型：
+
+- 用户输入错误
+- 来源解析失败
+- 写文件失败
+- lock 缺失或失效
+- 安装目标冲突
+- 远程获取失败
+
+plugin 模式下：
+
+- 没有 `skills.json`：跳过
+- 有 `skills.json` 但没有 `skills-lock.yaml`：失败
+
+### 并发与原子性
+
+建议增加项目级锁文件：
+
+```text
+.agents/.skills-pm.lock
+```
+
+行为：
+
+- 安装前尝试获取锁
+- 避免多个进程同时替换同一目录
+- source fetch 可以有限并发
+- 物化安装与软链替换阶段优先保证稳定，可串行执行
+
+安装时采用临时目录 + 原子替换策略，避免半安装状态。
+
+### 测试策略
+
+`0.1.0` 建议覆盖四层测试：
+
+1. 单元测试
+   - specifier 解析
+   - manifest / lock 读写
+   - digest 计算
+   - 路径规范化
+   - 软链目标计算
+2. 集成测试
+   - `skills add` 生成 `skills.json`
+   - `skills add` 更新 `skills-lock.yaml`
+   - `skills install` 安装本地 file source
+   - `skills install` 创建 linkTargets
+3. fixture 仓库测试
+   - git repo with `/skills/foo`
+   - local directory with skill
+   - npm package fixture with `/skills/bar`
+4. pnpm 插件联调测试
+   - 最小 workspace fixture 执行 `pnpm install`
+   - 验证插件自动加载、真实安装、软链建立和二次 no-op
+
+### 构建与发布形态
+
+- `skills-pm`
+  - 正常 CLI 包
+  - 提供 `bin`
+- `pnpm-plugin-skills`
+  - 必须是自包含发布物
+  - 不声明运行时依赖
+  - 不依赖 lifecycle scripts
+  - `pnpmfile.cjs` 只 require 本包内已打包好的 runtime
+
+建议发布包结构：
+
+```text
+pnpmfile.cjs
+dist/
+  runtime.js
+package.json
+```
+
+`pnpmfile.cjs` 示例：
+
+```js
+const { preResolution } = require('./dist/runtime')
+
+module.exports = {
+  hooks: {
+    preResolution,
+  },
+}
+```
+
+### 0.1.0 推荐实现顺序
+
+1. `skills.json` / `skills-lock.yaml` schema 与读写
+2. `file:` source + 本地 skill 安装
+3. `skills install` 的真实目录 + 软链逻辑
+4. `skills add` 的本地路径支持
+5. git source resolve + install
+6. `pnpm-plugin-skills` `preResolution` 接入
+7. no-op install state / cache
+8. npm source 支持
+
+### 0.1.0 明确不做的事情
+
+- 不做自动 prune / delete
+- 不做 skill 间依赖关系解析
+- 不做 registry 协议设计
+- 不做 install 阶段的自动升级/重新锁定
+- 不做复杂的退出码分层
+- 不做全局 store 设计
+
+## 当前待补充设计
+
+1. resolver / fetcher 的更细模块边界
+2. CLI 输出格式与日志级别
+3. `skills add` 在未传 `--skill` 场景下与外部工具对齐的精确行为
+4. npm source 的首版优先级与实现范围
+
+## 备注
+
+这是当前阶段的设计草稿，用于先保存共识；后续会继续补齐剩余设计并整理为正式设计文档。