@heihei0299/matt-skills 1.1.1 → 1.2.0

package/.agents/skills/instance-test/references/instances.md

@@ -24,12 +24,15 @@ Prompt: verify idempotent init without --force
 Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
 Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
 
-### 3. Init --force with backup
-Prompt: verify forced init backs up
+### 3. Init --force with direct overwrite
+Prompt: verify forced init directly overwrites
 Command: `init --force --dest <tmp>` after local edit
-Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+Expected: stdout `已覆盖` + `已装 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; no `.agents/skills/*.bak`; no `.opencode.bak`/`.pi.bak`; exit 0.
 
 ### 4. Sync on existing
+Prompt: verify sync directly updates existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已同步`/`已更新`; `AGENTS.md.bak` exists; `.agents/skills/tdd` updated; exit 0.
 Prompt: verify sync backs up existing project
 Command: `sync --dest <tmp>` after local edit
 Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.

package/README.md

@@ -31,16 +31,16 @@ npx @heihei0299/matt-skills init
 1. 复制 `template/` 快照（`AGENTS.md`、`.opencode/`、`.pi/`）到当前目录；
 2. 把上游技能（engineering 17 个 + productivity 5 个）复制到 `.agents/skills/`。
 
-选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件并自动备份被覆盖文件到 `.bak`（默认跳过）。
+选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）。
 
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync            # 增量同步，备份被覆盖文件到 .bak
-npx @heihei0299/matt-skills sync --force    # 覆盖不备份
+npx @heihei0299/matt-skills sync            # 增量同步，直接更新
+npx @heihei0299/matt-skills sync --force    # 同上（直接覆盖）
 ```
 
-`sync` 专为已有项目设计：自动检测 `AGENTS.md` 是否存在，存在则增量更新模板与上游技能并备份，不存在则等同全新 `init`。与 `init --force` 的区别：`sync` 默认即备份、语义更明确，建议已有项目优先用 `sync`。
+`sync` 专为已有项目设计：自动检测 `AGENTS.md` 是否存在，存在则增量更新模板与上游技能（直接覆盖，`AGENTS.md` 会备份），不存在则等同全新 `init`。与 `init --force` 的区别：`sync` 语义更明确，建议已有项目优先用 `sync`。
 
 上游没有 `tdd-implement`、`grill-to-spec`、`diagnose-fix`、`commit-check`，复制天然不冲突。目标仓库会话即自动加载全部技能（上游在 `.agents/skills/`、独有在 `.opencode/skills/`；pi 侧独有在 `.pi/skills/`）与项目级全局配置（行为路由表、分文件约定）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
 
@@ -116,13 +116,13 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 
 ```sh
 node bin/cli.js init [--dest <dir>] [--force]   # 初始化项目：template + 上游技能
-node bin/cli.js sync [--dest <dir>] [--force]   # 同步已有项目到最新（备份到 .bak）
+node bin/cli.js sync [--dest <dir>] [--force]   # 同步已有项目到最新（直接覆盖）
 node bin/cli.js list [--json]                   # 列出 .agents/skills/ 下全部技能及描述
 node bin/cli.js install [选项]                  # 把技能复制到目标工具目录（交互式选择）
 ```
 
-`init` 选项：`--dest <dir>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件并备份到 `.bak`（默认跳过），见「初始化」。
-`sync` 选项：`--dest <dir>` 指定目标目录；`--force` 覆盖不备份（默认备份），见「初始化」增量同步。
+`init` 选项：`--dest <dir>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过），见「初始化」。
+`sync` 选项：`--dest <dir>` 指定目标目录；`--force` 直接覆盖（与默认一致），见「初始化」增量同步。
 
 `install` 选项：
 
@@ -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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, cp, stat, writeFile, mkdir } from 'node:fs/promises';
+import { readdir, readFile, cp, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,17 +17,30 @@ const HELP = `matt-skills — install and manage this skill collection
 
 Usage:
   matt-skills init [options]                   Initialize a project: template + upstream skills
-  matt-skills sync [options]                   Sync existing project to latest template + skills (backs up overwritten files to .bak)
+  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:
   --dest <path>   Target directory (default: current directory)
-  --force         Overwrite existing files (backs up to .bak)
+  --force         Overwrite existing files
 Sync options:
   --dest <path>   Target directory (default: current directory)
-  --force         Overwrite without backup (default: backup to .bak)
+  --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
@@ -88,21 +101,6 @@ async function backupIfExists(p) {
   return bak;
 }
 
-async function ensureSkillsGitignore(skillsDir) {
-  try {
-    await mkdir(skillsDir, { recursive: true });
-    const gi = path.join(skillsDir, '.gitignore');
-    const content = '# matt-skills backup — pi skips .bak via explicit filter + this fallback\n*.bak\n*.bak/\n';
-    if (await pathExists(gi)) {
-      const cur = await readFile(gi, 'utf8');
-      if (cur.includes('*.bak')) return;
-      await writeFile(gi, cur.endsWith('\n') ? `${cur}${content}` : `${cur}\n${content}`);
-    } else {
-      await writeFile(gi, content);
-    }
-  } catch {}
-}
-
 const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
 
 const PROJECT_DIRS = {
@@ -188,15 +186,13 @@ async function initCommand({ dest, force }) {
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
   if (!force && (await pathExists(marker))) {
-    process.stdout.write('模板已存在（AGENTS.md），跳过；用 --force 覆盖（自动备份到 .bak）\n');
+    process.stdout.write('模板已存在（AGENTS.md），跳过；用 --force 覆盖\n');
   } else {
     if (force && (await pathExists(marker))) {
-      for (const name of ['AGENTS.md', '.opencode', '.pi']) {
-        const cur = path.join(target, name);
-        if (await pathExists(cur)) await backupIfExists(cur);
-      }
+      const cur = path.join(target, 'AGENTS.md');
+      if (await pathExists(cur)) await backupIfExists(cur);
       await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
-      process.stdout.write('模板：已备份到 .bak 并覆盖（AGENTS.md、.opencode/、.pi/）\n');
+      process.stdout.write('模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
     } else {
       await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
       process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
@@ -210,7 +206,6 @@ async function initCommand({ dest, force }) {
   const skillsDir = path.join(target, '.agents', 'skills');
   let installed = 0;
   let skipped = 0;
-  let backedUp = 0;
   for (const name of upstream) {
     const src = path.join(SKILLS_DIR, name);
     const dst = path.join(skillsDir, name);
@@ -222,19 +217,10 @@ async function initCommand({ dest, force }) {
       skipped++;
       continue;
     }
-    if (force && (await pathExists(dst))) {
-      await backupIfExists(dst);
-      backedUp++;
-    }
     await cp(src, dst, { recursive: true, force: true });
     installed++;
   }
-  if (force && backedUp > 0) {
-    process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}、备份 ${backedUp} 到 .bak\n`);
-  } else {
-    process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}\n`);
-  }
-  await ensureSkillsGitignore(skillsDir);
+  process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}\n`);
   process.stdout.write(`目标路径：${target}\n`);
 }
 
@@ -247,15 +233,13 @@ async function syncCommand({ dest, force }) {
     await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
     process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
   } else {
-    process.stdout.write('同步：检测到现有项目，将增量更新并备份被覆盖文件到 .bak\n');
+    process.stdout.write('同步：检测到现有项目，将增量更新\n');
     if (backup) {
-      for (const name of ['AGENTS.md', '.opencode', '.pi']) {
-        const cur = path.join(target, name);
-        if (await pathExists(cur)) await backupIfExists(cur);
-      }
+      const cur = path.join(target, 'AGENTS.md');
+      if (await pathExists(cur)) await backupIfExists(cur);
     }
     await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
-    process.stdout.write(backup ? '模板：已备份并同步（AGENTS.md、.opencode/、.pi/）\n' : '模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
+    process.stdout.write(backup ? '模板：已同步（AGENTS.md、.opencode/、.pi/）\n' : '模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
   }
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const upstream = entries
@@ -265,7 +249,6 @@ async function syncCommand({ dest, force }) {
   const skillsDir = path.join(target, '.agents', 'skills');
   let installed = 0;
   let updated = 0;
-  let backedUp = 0;
   for (const name of upstream) {
     const src = path.join(SKILLS_DIR, name);
     const dst = path.join(skillsDir, name);
@@ -275,10 +258,6 @@ async function syncCommand({ dest, force }) {
     }
     const exists = await pathExists(dst);
     if (exists) {
-      if (backup) {
-        await backupIfExists(dst);
-        backedUp++;
-      }
       await cp(src, dst, { recursive: true, force: true });
       updated++;
     } else {
@@ -286,12 +265,7 @@ async function syncCommand({ dest, force }) {
       installed++;
     }
   }
-  if (backup) {
-    process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}（已备份 ${backedUp} 到 .bak）\n`);
-  } else {
-    process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
-  }
-  await ensureSkillsGitignore(skillsDir);
+  process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
   process.stdout.write(`目标路径：${target}\n`);
 }
 
@@ -330,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') {
@@ -360,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.1",
+  "version": "1.2.0",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/template/.opencode/skills/instance-test/references/instances.md

@@ -24,12 +24,15 @@ Prompt: verify idempotent init without --force
 Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
 Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
 
-### 3. Init --force with backup
-Prompt: verify forced init backs up
+### 3. Init --force with direct overwrite
+Prompt: verify forced init directly overwrites
 Command: `init --force --dest <tmp>` after local edit
-Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+Expected: stdout `已覆盖` + `已装 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; no `.agents/skills/*.bak`; no `.opencode.bak`/`.pi.bak`; exit 0.
 
 ### 4. Sync on existing
+Prompt: verify sync directly updates existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已同步`/`已更新`; `AGENTS.md.bak` exists; `.agents/skills/tdd` updated; exit 0.
 Prompt: verify sync backs up existing project
 Command: `sync --dest <tmp>` after local edit
 Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.

package/template/.pi/skills/instance-test/references/instances.md

@@ -24,12 +24,15 @@ Prompt: verify idempotent init without --force
 Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
 Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
 
-### 3. Init --force with backup
-Prompt: verify forced init backs up
+### 3. Init --force with direct overwrite
+Prompt: verify forced init directly overwrites
 Command: `init --force --dest <tmp>` after local edit
-Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+Expected: stdout `已覆盖` + `已装 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; no `.agents/skills/*.bak`; no `.opencode.bak`/`.pi.bak`; exit 0.
 
 ### 4. Sync on existing
+Prompt: verify sync directly updates existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已同步`/`已更新`; `AGENTS.md.bak` exists; `.agents/skills/tdd` updated; exit 0.
 Prompt: verify sync backs up existing project
 Command: `sync --dest <tmp>` after local edit
 Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.