@heihei0299/matt-skills 1.3.0 → 1.3.1

package/README.md

@@ -36,11 +36,13 @@ npx @heihei0299/matt-skills init
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync            # 增量同步，直接更新
-npx @heihei0299/matt-skills sync --force    # 同上（直接覆盖）
+npx @heihei0299/matt-skills sync                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析
+npx @heihei0299/matt-skills sync --apply                         # 安全增量：AGENTS.md 定制跳过，上游技能强制覆盖但不删
+npx @heihei0299/matt-skills sync --force                         # 硬盖：AGENTS.md 备份后硬盖，技能与模板全量 add/update/remove
+npx @heihei0299/matt-skills sync --apply --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`sync` 专为已有项目设计：自动检测 `AGENTS.md` 是否存在，存在则增量更新模板与上游技能（直接覆盖，`AGENTS.md` 会备份），不存在则等同全新 `init`。与 `init --force` 的区别：`sync` 语义更明确，建议已有项目优先用 `sync`。
+`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 对上游技能 `rm+cp force` 覆盖但不 `remove`，`template/.opencode/.pi` 增量 `add/update`）；`--force` 硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板均 `add/update/remove` 全做）。`--dest`、`--upstream`、`--ref`、`--json` 在三档均可透传。
 
 上游没有 `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/`，`/命令名` 触发）。
 
@@ -115,14 +117,16 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
 
 ```sh
-node bin/cli.js init [--dest <dir>] [--force]   # 初始化项目：template + 上游技能
-node bin/cli.js sync [--dest <dir>] [--force]   # 同步已有项目到最新（直接覆盖）
-node bin/cli.js list [--json]                   # 列出 .agents/skills/ 下全部技能及描述
-node bin/cli.js install [选项]                  # 把技能复制到目标工具目录（交互式选择）
+node bin/cli.js init [--dest <dir>] [--force]                                           # 初始化项目：template + 上游技能
+node bin/cli.js sync [--apply|--force] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新
+node bin/cli.js list [--json]                                                           # 列出 .agents/skills/ 下全部技能及描述
+node bin/cli.js install [选项]                                                          # 把技能复制到目标工具目录（交互式选择）
+node bin/cli.js check [--json] [--upstream <url>] [--ref <ref>]                        # 只读检查上游技能是否最新（等价 sync 默认）
 ```
 
-`init` 选项：`--dest <dir>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过），见「初始化」。
-`sync` 选项：`--dest <dir>` 指定目标目录；`--force` 直接覆盖（与默认一致），见「初始化」增量同步。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过），见「初始化」。
+`sync` 选项：`--apply` 安全增量（`AGENTS.md` 定制跳过、技能不删），`--force` 硬盖（`AGENTS.md` 备份后硬盖、技能与模板全量 `remove`）；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘，`--json` 可解析，有差异 `exit 1`。
+`check` 选项：`--json`、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
 
 `install` 选项：
 
@@ -136,15 +140,15 @@ node bin/cli.js install [选项]                  # 把技能复制到目标工
 
 本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
 
-- **本地 CLI**：`matt-skills check`（只读比对）与 `matt-skills update`（一键覆盖本地 `.agents/skills/`，自动处理 `writing-great-skills → writing-for-agents` 重命名与增删）
+- **本地 CLI**：`matt-skills sync` 三档——默认 `check` 只读比对（等价 `matt-skills check`，有差异 `exit 1`，`--json` 可解析）、`matt-skills sync --apply` 安全增量、`matt-skills sync --force` 硬盖；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 仍保留为只读别名；`matt-skills update` 已合并到 `sync --apply`（执行提示 `update 已合并到 sync --apply` 且 `exit 1`）
 - **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 的实现）
+npx @heihei0299/matt-skills sync --json              # 默认 check 只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
+npx @heihei0299/matt-skills sync --apply             # 安全增量写盘
+npx @heihei0299/matt-skills sync --force             # 硬盖写盘
+npx @heihei0299/matt-skills check --json             # 等价 sync 默认 check
+node scripts/sync-upstream.js --check               # 等价底层脚本（CLI sync/check 的实现）
 node scripts/sync-upstream.js --apply --dry-run
 ```
 

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, cp, stat } from 'node:fs/promises';
+import { readdir, readFile, cp, stat, rm, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,31 +17,27 @@ 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
+  matt-skills sync [--apply|--force] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]   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
 Sync options:
+  --apply         Apply changes (safe incremental, respects custom AGENTS.md)
+  --force         Hard overwrite (backup .bak + full sync)
   --dest <path>   Target directory (default: current directory)
-  --force         Overwrite existing files
+  --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
+  --ref <ref>     Upstream ref (default: HEAD)
+  --json          Output as JSON
 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
   --all           Install all skills; skips skill selection
@@ -224,22 +220,69 @@ async function initCommand({ dest, force }) {
   process.stdout.write(`目标路径：${target}\n`);
 }
 
-async function syncCommand({ dest, force }) {
+async function syncCommand({ dest, force, apply, upstreamUrl, ref, json }) {
+  // 默认：仅对比不写盘 (check 模式)，--apply / --force 显式写盘
+  const doApply = apply || force;
+  if (!doApply) {
+    const { compare } = await import('../scripts/sync-upstream.js');
+    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;
+    return;
+  }
+
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
-  const backup = !force;
   if (!(await pathExists(marker))) {
     process.stdout.write('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
     await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
     process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
-  } else {
+  } else if (force) {
     process.stdout.write('同步：检测到现有项目，将增量更新\n');
-    if (backup) {
-      const cur = path.join(target, 'AGENTS.md');
-      if (await pathExists(cur)) await backupIfExists(cur);
+    await backupIfExists(path.join(target, 'AGENTS.md'));
+    await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+    process.stdout.write('模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
+  } else if (apply) {
+    process.stdout.write('同步：检测到现有项目，将增量更新\n');
+    let skipAgents = false;
+    try {
+      const content = await readFile(path.join(target, 'AGENTS.md'), 'utf8');
+      if (content.includes('tdd-implement')) skipAgents = true;
+    } catch {}
+    if (skipAgents) {
+      await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
+      await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
+      process.stdout.write('模板：已同步（AGENTS.md 跳过，已含定制）\n');
+    } else {
+      await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      process.stdout.write('模板：已同步（AGENTS.md、.opencode/、.pi/）\n');
     }
+  } else {
+    // fallback for any other doApply case (should not reach here because !doApply already returned)
+    process.stdout.write('同步：检测到现有项目，将增量更新\n');
     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('模板：已同步（AGENTS.md、.opencode/、.pi/）\n');
   }
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const upstream = entries
@@ -247,6 +290,7 @@ async function syncCommand({ dest, force }) {
     .map((e) => e.name)
     .sort();
   const skillsDir = path.join(target, '.agents', 'skills');
+  await mkdir(skillsDir, { recursive: true });
   let installed = 0;
   let updated = 0;
   for (const name of upstream) {
@@ -258,6 +302,7 @@ async function syncCommand({ dest, force }) {
     }
     const exists = await pathExists(dst);
     if (exists) {
+      await rm(dst, { recursive: true, force: true });
       await cp(src, dst, { recursive: true, force: true });
       updated++;
     } else {
@@ -265,6 +310,20 @@ async function syncCommand({ dest, force }) {
       installed++;
     }
   }
+  if (force) {
+    let localEntries = [];
+    try {
+      localEntries = await readdir(skillsDir, { withFileTypes: true });
+    } catch {}
+    for (const e of localEntries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.endsWith('.bak')) continue;
+      if (e.name === '.git') continue;
+      if (PROPRIETARY_SKILLS.has(e.name)) continue;
+      if (upstream.includes(e.name)) continue;
+      await rm(path.join(skillsDir, e.name), { recursive: true, force: true });
+    }
+  }
   process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
   process.stdout.write(`目标路径：${target}\n`);
 }
@@ -272,13 +331,23 @@ async function syncCommand({ dest, force }) {
 function parseInitArgs(args) {
   let dest;
   let force = false;
+  let apply = false;
+  let json = false;
+  let upstreamUrl;
+  let ref;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--dest') dest = args[++i];
     else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
     else if (arg === '--force') force = true;
+    else if (arg === '--apply') apply = true;
+    else if (arg === '--json') json = true;
+    else if (arg === '--upstream') upstreamUrl = args[++i];
+    else if (arg.startsWith('--upstream=')) upstreamUrl = arg.slice('--upstream='.length);
+    else if (arg === '--ref') ref = args[++i];
+    else if (arg.startsWith('--ref=')) ref = arg.slice('--ref='.length);
   }
-  return { dest, force };
+  return { dest, force, apply, json, upstreamUrl, ref };
 }
 
 function parseInstallArgs(args) {
@@ -337,44 +406,6 @@ async function checkCommand(args) {
   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') {
@@ -410,7 +441,8 @@ async function main() {
     return;
   }
   if (command === 'update') {
-    await updateCommand(rest);
+    process.stderr.write('update 已合并到 sync --apply\n');
+    process.exitCode = 1;
     return;
   }
   process.stderr.write(HELP);

package/package.json

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

package/template/.opencode/CONTEXT.md

@@ -32,6 +32,10 @@ _Avoid_: inheriting repo, child repo
 The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`), then fetching the 22 upstream skills from the Upstream Repository. Copying, not inheriting — no runtime relationship survives the copy.
 _Avoid_: inherit, bootstrap
 
+**Sync** (同步):
+`matt-skills sync` 同步 Target Repository 的模板与上游技能：默认仅对比不写盘（`check`），`--apply` 为安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，上游技能直接强制覆盖 `rm+cp` 但不 `remove`，独有技能与 `template/.opencode/.pi` 增量 `add/update`）、`--force` 为硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板全量 `add/update/remove`）。`update` 已合并到 `sync` 并删除。
+_Avoid_: update, force sync
+
 ## Skill Design
 
 **Turn Continuity** (回合连续性):