@heihei0299/matt-skills 1.1.2 → 1.2.1

package/README.md

@@ -131,6 +131,25 @@ node bin/cli.js install [选项]                  # 把技能复制到目标工
 - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
 - `--all`：安装全部技能（默认交互勾选）；`--force`：覆盖已存在的技能
 
+
+### 上游同步（自动更新）
+
+本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
+
+- **本地 CLI**：`matt-skills check`（只读比对）与 `matt-skills update`（一键覆盖本地 `.agents/skills/`，自动处理 `writing-great-skills → writing-for-agents` 重命名与增删）
+- **GitHub Actions**：`.github/workflows/sync-upstream.yml` 每周一 02:00 UTC 自动 `check`，有差异则 `apply` 并提 PR（`upstream-sync/<short-sha>`），支持 `workflow_dispatch` 手动触发（`ref`/`dry_run` 参数）
+
+```sh
+npx @heihei0299/matt-skills check                    # 只读检查，对比本地 vs 上游 HEAD（有差异 exit 1）
+npx @heihei0299/matt-skills check --json             # JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
+npx @heihei0299/matt-skills update --dry-run         # 演练，不写文件
+npx @heihei0299/matt-skills update                   # 覆盖 .agents/skills 非独有技能
+node scripts/sync-upstream.js --check               # 等价底层脚本（CLI check/update 的实现）
+node scripts/sync-upstream.js --apply --dry-run
+```
+
+实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单，上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
+上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
 ## 发布
 
 推送 `v*` 标签自动发布到 npm（GitHub Actions，见 `.github/workflows/publish.yml`）：

package/bin/cli.js

@@ -20,6 +20,10 @@ Usage:
   matt-skills sync [options]                   Sync existing project to latest template + skills
   matt-skills list [--json]                    List available skills and their descriptions
   matt-skills install [options]                Install skills (interactive by default)
+  matt-skills check [--json] [--upstream <url>] [--ref <ref>]
+                                              Check if upstream skills are up to date (read-only)
+  matt-skills update [--dry-run] [--force] [--upstream <url>] [--ref <ref>]
+                                              Update .agents/skills from upstream (auto handles renames)
   matt-skills --help                          Show this help
 
 Init options:
@@ -28,6 +32,15 @@ Init options:
 Sync options:
   --dest <path>   Target directory (default: current directory)
   --force         Overwrite existing files
+Check options:
+  --json          Output as JSON
+  --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
+  --ref <ref>     Upstream ref (default: HEAD)
+Update options:
+  --dry-run       Show what would change without writing files
+  --force         Force overwrite (default is to overwrite; kept for compatibility)
+  --upstream <url> Upstream repo URL
+  --ref <ref>     Upstream ref
 
 Install options:
   --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection
@@ -291,6 +304,77 @@ function parseInstallArgs(args) {
   return { dest, all, force, global, tools };
 }
 
+async function checkCommand(args) {
+  const { compare } = await import('../scripts/sync-upstream.js');
+  const json = args.includes('--json');
+  const upstreamIdx = args.indexOf('--upstream');
+  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : undefined;
+  const refIdx = args.indexOf('--ref');
+  const ref = refIdx !== -1 ? args[refIdx + 1] : undefined;
+  const cmp = await compare({ upstreamUrl, ref });
+  if (json) {
+    process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result }, null, 2) + '\n');
+  } else {
+    const lines = [];
+    lines.push(`上游 HEAD: ${cmp.head}`);
+    lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream}`);
+    lines.push('');
+    const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
+    if (totalDiff === 0) {
+      lines.push('✅ 已是最新，无差异');
+    } else {
+      if (cmp.result.added.length) lines.push(`新增 (${cmp.result.added.length}): ${cmp.result.added.join(', ')}`);
+      if (cmp.result.updated.length) lines.push(`更新 (${cmp.result.updated.length}): ${cmp.result.updated.join(', ')}`);
+      if (cmp.result.renamed.length) lines.push(`重命名 (${cmp.result.renamed.length}): ${cmp.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
+      if (cmp.result.removed.length) lines.push(`删除 (${cmp.result.removed.length}): ${cmp.result.removed.join(', ')}`);
+      if (cmp.result.same.length) lines.push(`一致 (${cmp.result.same.length}): ${cmp.result.same.join(', ')}`);
+    }
+    process.stdout.write(lines.join('\n') + '\n');
+  }
+  const { rm } = await import('node:fs/promises');
+  await rm(cmp.dest, { recursive: true, force: true });
+  const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
+  if (hasDiff) process.exitCode = 1;
+}
+
+async function updateCommand(args) {
+  const { applySync } = await import('../scripts/sync-upstream.js');
+  const dryRun = args.includes('--dry-run');
+  const json = args.includes('--json');
+  const upstreamIdx = args.indexOf('--upstream');
+  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : undefined;
+  const refIdx = args.indexOf('--ref');
+  const ref = refIdx !== -1 ? args[refIdx + 1] : undefined;
+  const res = await applySync({ upstreamUrl, ref, dryRun });
+  if (json) {
+    process.stdout.write(JSON.stringify({ head: res.head, result: res.result, actions: res.actions, dryRun }, null, 2) + '\n');
+  } else {
+    const lines = [];
+    lines.push(`上游 HEAD: ${res.head}`);
+    lines.push(`本地非独有: ${res.counts.local}  上游: ${res.counts.upstream}`);
+    lines.push('');
+    const totalDiff = res.result.added.length + res.result.updated.length + res.result.removed.length + res.result.renamed.length;
+    if (totalDiff === 0) {
+      lines.push('✅ 已是最新，无差异');
+    } else {
+      if (res.result.added.length) lines.push(`新增 (${res.result.added.length}): ${res.result.added.join(', ')}`);
+      if (res.result.updated.length) lines.push(`更新 (${res.result.updated.length}): ${res.result.updated.join(', ')}`);
+      if (res.result.renamed.length) lines.push(`重命名 (${res.result.renamed.length}): ${res.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
+      if (res.result.removed.length) lines.push(`删除 (${res.result.removed.length}): ${res.result.removed.join(', ')}`);
+      if (res.result.same.length) lines.push(`一致 (${res.result.same.length}): ${res.result.same.join(', ')}`);
+    }
+    process.stdout.write(lines.join('\n') + '\n');
+    if (res.actions.length) {
+      process.stdout.write(`\n已执行 ${res.actions.length} 项:\n`);
+      for (const a of res.actions) process.stdout.write(`  - ${a}\n`);
+    }
+    if (dryRun) process.stdout.write('\n(dry-run，未写文件)\n');
+  }
+  if (!dryRun && res.actions.length) {
+    process.stdout.write('\n提示：请运行 npm test 验证，并按需执行 npm run build:template 更新模板镜像\n');
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
@@ -321,10 +405,17 @@ async function main() {
     await installCommand(parseInstallArgs(rest));
     return;
   }
+  if (command === 'check') {
+    await checkCommand(rest);
+    return;
+  }
+  if (command === 'update') {
+    await updateCommand(rest);
+    return;
+  }
   process.stderr.write(HELP);
   process.exitCode = 1;
 }
-
 main().catch((error) => {
   process.stderr.write(`error: ${error.message}\n`);
   process.exitCode = 1;

package/config/proprietary.json

@@ -0,0 +1 @@
+["tdd-implement", "grill-to-spec", "diagnose-fix", "commit-check", "instance-test"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
     "bin/",
     "template/",
     ".agents/skills/",
+    "scripts/sync-upstream.js",
+    "config/proprietary.json",
     "README.md"
   ],
   "scripts": {

package/scripts/sync-upstream.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+import { cp, readdir, readFile, rm, stat, mkdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LOCAL_SKILLS_DIR = path.join(ROOT, '.agents', 'skills');
+const PROPRIETARY_PATH = path.join(ROOT, 'config', 'proprietary.json');
+const UPSTREAM_URL = 'https://github.com/mattpocock/skills.git';
+
+// 重命名映射：上游已重命名，本地旧名需迁移
+const RENAMES = {
+  'writing-great-skills': 'writing-for-agents',
+};
+
+async function loadProprietary() {
+  try {
+    const raw = await readFile(PROPRIETARY_PATH, 'utf8');
+    return new Set(JSON.parse(raw));
+  } catch {
+    return new Set(['tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check', 'instance-test']);
+  }
+}
+
+async function hashFile(filePath) {
+  const buf = await readFile(filePath);
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+async function hashDir(dir) {
+  // 对 SKILL.md 做 hash，用于比对；若无 SKILL.md 则对目录内所有文件联合 hash
+  const skillMd = path.join(dir, 'SKILL.md');
+  try {
+    await stat(skillMd);
+    return await hashFile(skillMd);
+  } catch {
+    return null;
+  }
+}
+
+async function listSkills(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name.endsWith('.bak')) continue;
+    if (e.name === '.git') continue;
+    out.push(e.name);
+  }
+  return out.sort();
+}
+
+async function fetchUpstream({ tmpDir, upstreamUrl = UPSTREAM_URL, ref = 'HEAD' } = {}) {
+  const dest = tmpDir || path.join(os.tmpdir(), `matt-skills-upstream-${Date.now()}`);
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(path.dirname(dest), { recursive: true });
+  const clone = spawnSync('git', ['clone', '--depth', '1', upstreamUrl, dest], { encoding: 'utf8' });
+  if (clone.status !== 0) {
+    throw new Error(`git clone 失败: ${clone.stderr || clone.stdout}`);
+  }
+  if (ref && ref !== 'HEAD') {
+    const co = spawnSync('git', ['-C', dest, 'checkout', ref], { encoding: 'utf8' });
+    if (co.status !== 0) throw new Error(`git checkout ${ref} 失败: ${co.stderr}`);
+  }
+  const rev = spawnSync('git', ['-C', dest, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+  const head = rev.stdout ? rev.stdout.trim() : 'unknown';
+  return { dest, head };
+}
+
+async function collectUpstreamSkills(upstreamRoot) {
+  const map = new Map(); // name -> { dir, hash }
+  for (const bucket of ['engineering', 'productivity']) {
+    const bucketDir = path.join(upstreamRoot, 'skills', bucket);
+    let entries = [];
+    try {
+      entries = await readdir(bucketDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const skillDir = path.join(bucketDir, e.name);
+      const h = await hashDir(skillDir);
+      if (h) map.set(e.name, { dir: skillDir, hash: h, bucket });
+    }
+  }
+  return map;
+}
+
+async function collectLocalSkills(proprietary) {
+  const map = new Map();
+  const names = await listSkills(LOCAL_SKILLS_DIR);
+  for (const name of names) {
+    if (name === 'skill-creator') continue; // 本地符号链接，不纳入上游比对
+    if (proprietary.has(name)) continue;
+    const dir = path.join(LOCAL_SKILLS_DIR, name);
+    const h = await hashDir(dir);
+    map.set(name, { dir, hash: h });
+  }
+  return map;
+}
+
+export async function compare({ upstreamUrl, tmpDir, ref } = {}) {
+  const proprietary = await loadProprietary();
+  const fetched = await fetchUpstream({ tmpDir, upstreamUrl, ref });
+  const upstreamRoot = fetched.dest;
+  const upstreamMap = await collectUpstreamSkills(upstreamRoot);
+  const localMap = await collectLocalSkills(proprietary);
+
+  const added = [];
+  const updated = [];
+  const same = [];
+  const removed = [];
+  const renamed = [];
+
+  // 检测重命名：本地旧名存在且上游新名存在，且本地旧名不在上游
+  for (const [oldName, newName] of Object.entries(RENAMES)) {
+    if (localMap.has(oldName) && upstreamMap.has(newName) && !upstreamMap.has(oldName)) {
+      renamed.push({ from: oldName, to: newName });
+    }
+  }
+  const renamedFrom = new Set(renamed.map((r) => r.from));
+  const renamedTo = new Set(renamed.map((r) => r.to));
+
+  for (const [name, u] of upstreamMap.entries()) {
+    if (renamedTo.has(name)) continue; // 重命名的新名单独处理
+    const local = localMap.get(name);
+    if (!local) {
+      added.push(name);
+    } else if (local.hash !== u.hash) {
+      updated.push(name);
+    } else {
+      same.push(name);
+    }
+  }
+  // 重命名的也算 updated（需迁移）
+  for (const r of renamed) {
+    const u = upstreamMap.get(r.to);
+    const local = localMap.get(r.from);
+    if (local && u && local.hash !== u.hash) updated.push(`${r.from}→${r.to}`);
+    else if (!local) added.push(r.to);
+    else same.push(`${r.from}→${r.to}`);
+  }
+
+  for (const name of localMap.keys()) {
+    if (renamedFrom.has(name)) continue;
+    if (!upstreamMap.has(name) && !renamedTo.has(name)) {
+      removed.push(name);
+    }
+  }
+
+  return {
+    head: fetched.head,
+    dest: fetched.dest,
+    upstreamMap,
+    localMap,
+    proprietary: [...proprietary],
+    result: { added: added.sort(), updated: updated.sort(), same: same.sort(), removed: removed.sort(), renamed },
+    counts: { upstream: upstreamMap.size, local: localMap.size },
+  };
+}
+
+export async function applySync({ upstreamUrl, tmpDir, ref, dryRun = false, force = false } = {}) {
+  const proprietary = await loadProprietary();
+  const cmp = await compare({ upstreamUrl, tmpDir, ref });
+  const { dest, head, upstreamMap, result } = cmp;
+  const actions = [];
+
+  if (dryRun) {
+    return { ...cmp, actions, dryRun: true };
+  }
+
+  // 处理重命名：删除旧目录，复制新目录
+  for (const r of result.renamed) {
+    const src = upstreamMap.get(r.to).dir;
+    const dst = path.join(LOCAL_SKILLS_DIR, r.to);
+    const oldDst = path.join(LOCAL_SKILLS_DIR, r.from);
+    await rm(oldDst, { recursive: true, force: true });
+    await rm(dst, { recursive: true, force: true });
+    await cp(src, dst, { recursive: true, force: true });
+    actions.push(`rename ${r.from} → ${r.to}`);
+  }
+
+  // 新增
+  for (const name of result.added) {
+    // 跳过已通过重命名处理的新名
+    if (result.renamed.some((r) => r.to === name)) continue;
+    const src = upstreamMap.get(name)?.dir;
+    if (!src) continue;
+    const dst = path.join(LOCAL_SKILLS_DIR, name);
+    await cp(src, dst, { recursive: true, force: true });
+    actions.push(`add ${name}`);
+  }
+
+  // 更新
+  for (const name of result.updated) {
+    if (name.includes('→')) continue; // 已处理
+    const src = upstreamMap.get(name)?.dir;
+    if (!src) continue;
+    const dst = path.join(LOCAL_SKILLS_DIR, name);
+    await rm(dst, { recursive: true, force: true });
+    await cp(src, dst, { recursive: true, force: true });
+    actions.push(`update ${name}`);
+  }
+
+  // 删除（上游已删且非独有）
+  for (const name of result.removed) {
+    const dst = path.join(LOCAL_SKILLS_DIR, name);
+    // 仅当非独有且上游确实不存在时删除；默认执行，需 --force 才删？按自动覆盖策略直接删
+    await rm(dst, { recursive: true, force: true });
+    actions.push(`remove ${name}`);
+  }
+
+  // 清理临时目录
+  await rm(dest, { recursive: true, force: true });
+
+  return { ...cmp, dest: null, actions, head };
+}
+
+function formatTable(cmp) {
+  const { result, counts, head } = cmp;
+  const lines = [];
+  lines.push(`上游 HEAD: ${head}`);
+  lines.push(`本地非独有: ${counts.local}  上游: ${counts.upstream}`);
+  lines.push('');
+  const totalDiff = result.added.length + result.updated.length + result.removed.length + result.renamed.length;
+  if (totalDiff === 0) {
+    lines.push('✅ 已是最新，无差异');
+  } else {
+    if (result.added.length) lines.push(`新增 (${result.added.length}): ${result.added.join(', ')}`);
+    if (result.updated.length) lines.push(`更新 (${result.updated.length}): ${result.updated.join(', ')}`);
+    if (result.renamed.length) lines.push(`重命名 (${result.renamed.length}): ${result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
+    if (result.removed.length) lines.push(`删除 (${result.removed.length}): ${result.removed.join(', ')}`);
+    if (result.same.length) lines.push(`一致 (${result.same.length}): ${result.same.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const opts = {
+    json: args.includes('--json'),
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    check: args.includes('--check'),
+    apply: args.includes('--apply') || args.includes('--update'),
+    verbose: args.includes('--verbose') || args.includes('-v'),
+  };
+  const upstreamIdx = args.indexOf('--upstream');
+  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : undefined;
+  const refIdx = args.indexOf('--ref');
+  const ref = refIdx !== -1 ? args[refIdx + 1] : undefined;
+  const tmpIdx = args.indexOf('--tmp');
+  const tmpDir = tmpIdx !== -1 ? args[tmpIdx + 1] : undefined;
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    process.stdout.write(`sync-upstream — 对比/同步 mattpocock/skills 上游技能
+
+Usage:
+  node scripts/sync-upstream.js --check [--json] [--upstream <url>] [--ref <ref>]
+  node scripts/sync-upstream.js --apply [--dry-run] [--force] [--upstream <url>] [--ref <ref>]
+
+Options:
+  --check     只对比，不改动文件（默认）
+  --apply     应用同步（覆盖 .agents/skills 非独有技能）
+  --dry-run   演练模式，不写文件
+  --json      以 JSON 输出结果
+  --upstream  上游仓库 URL（默认 https://github.com/mattpocock/skills.git）
+  --ref       上游 ref（默认 HEAD）
+  --tmp       指定临时目录（默认 os.tmpdir() 下随机）
+  --force     强制覆盖（apply 时默认即覆盖，此标志保留兼容）
+  --verbose   详细输出
+`);
+    return;
+  }
+
+  if (opts.apply) {
+    const res = await applySync({ upstreamUrl, tmpDir, ref, dryRun: opts.dryRun, force: opts.force });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ head: res.head, result: res.result, actions: res.actions, dryRun: opts.dryRun }, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatTable(res) + '\n');
+      if (res.actions.length) {
+        process.stdout.write(`\n已执行 ${res.actions.length} 项:\n`);
+        for (const a of res.actions) process.stdout.write(`  - ${a}\n`);
+      }
+      if (opts.dryRun) process.stdout.write('\n(dry-run，未写文件)\n');
+    }
+    const hasDiff = res.result.added.length + res.result.updated.length + res.result.removed.length + res.result.renamed.length > 0;
+    if (opts.check && hasDiff) process.exitCode = 1;
+    return;
+  }
+
+  // 默认 --check
+  const cmp = await compare({ upstreamUrl, tmpDir, ref });
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result }, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatTable(cmp) + '\n');
+  }
+  const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
+  // 清理临时目录
+  await rm(cmp.dest, { recursive: true, force: true });
+  if (hasDiff) process.exitCode = 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1].endsWith('sync-upstream.js')) {
+  main().catch((e) => {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exitCode = 1;
+  });
+}