@heihei0299/matt-skills 1.1.2 → 1.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {