scrum-skills 0.2.2 → 0.2.4

package/bin/scrum-skills.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * scrum-skills CLI（零依赖，node >= 18）
  * 命令:
@@ -12,7 +12,7 @@
  *   scrum-skills validate [dir]        校验敏捷数据（默认当前目录）
  */
 import { cpSync, mkdirSync, existsSync, writeFileSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, basename } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -31,6 +31,20 @@ scsk 是 scrum-skills 的等价简写，如: scsk serve`;
 const [cmd, ...args] = process.argv.slice(2);
 const fail = msg => { console.error(`✘ ${msg}`); process.exit(1); };
 
+/**
+ * 备份一个即将被覆盖的文件，返回备份路径。
+ * 名字带时间戳：老做法固定叫 `*.bak`，第二次 update 就把上一次的备份顶掉了，
+ * 而 AGENTS.md 几乎一定会被本地改过，备份互相覆盖等于没备份。
+ */
+function backupFile(file) {
+  const d = new Date();
+  const pad = n => String(n).padStart(2, '0');
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  let target = `${file}.${stamp}.bak`;
+  for (let i = 2; existsSync(target); i += 1) target = `${file}.${stamp}-${i}.bak`;
+  cpSync(file, target);
+  return target;
+}
 function init() {
   const force = args.includes('--force');
   const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
@@ -38,9 +52,9 @@ function init() {
 
   const agentsMd = join(dir, 'AGENTS.md');
   if (existsSync(agentsMd) && !force)
-    fail(`目标目录已有 AGENTS.md。确认覆盖请加 --force（旧文件会备份为 AGENTS.md.bak）`);
-  const backed = existsSync(agentsMd);
-  if (backed) cpSync(agentsMd, `${agentsMd}.bak`);
+    fail(`目标目录已有 AGENTS.md。确认覆盖请加 --force（旧文件会先备份成 AGENTS.md.<时间戳>.bak）`);
+  const backed = existsSync(agentsMd) ? backupFile(agentsMd) : null;
+  if (backed) console.log(`· 已把现有 AGENTS.md 备份为 ${basename(backed)}`);
 
   cpSync(join(PKG_ROOT, '.agents'), join(dir, '.agents'), { recursive: true, force: true });
   writeFileSync(agentsMd, readFileSync(join(PKG_ROOT, 'templates/AGENTS.md'), 'utf8'));
@@ -65,7 +79,7 @@ function init() {
 
   console.log(`✔ 已初始化到 ${dir}
   - .agents/skills/      四个敏捷 skill（planning / sprint / tdd / report）
-  - AGENTS.md            agent 入口纪律文件${backed ? '（旧文件已备份为 AGENTS.md.bak）' : ''}
+  - AGENTS.md            agent 入口纪律文件${backed ? `（旧文件已备份为 ${basename(backed)}）` : ''}
   - tools/validate.mjs   数据校验脚本
   - agile/ 三文件结构${created.length ? `（新建 ${created.join('、')}）` : '（已存在，未覆盖）'}
 
@@ -104,6 +118,8 @@ function update() {
     fail(`${dir} 未初始化（找不到 .agents/ 与 AGENTS.md）。请先运行: scrum-skills init`);
 
   const added = [], changed = [], same = [];
+  // 相对路径 → 备份文件名，覆盖完统一提示怎么把本地改动捞回来
+  const backups = [];
   for (const { rel, src } of frameworkFiles()) {
     const dest = join(dir, rel);
     const srcText = readFileSync(src, 'utf8');
@@ -114,19 +130,26 @@ function update() {
     if (readFileSync(dest, 'utf8') === srcText) { same.push(rel); continue; }
     changed.push(rel);
     if (!dryRun) {
-      cpSync(dest, `${dest}.bak`);           // 覆盖前备份，本地自定义不丢
+      const bak = backupFile(dest);          // 覆盖前备份，本地自定义不丢
+      backups.push({ rel, bak: basename(bak) });
       writeFileSync(dest, srcText);
     }
   }
 
   const verb = dryRun ? '（dry-run，未写入）' : '';
+  const bakLines = backups.map(b => `  - ${b.rel} 的旧版本 → ${b.bak}`).join('\n');
   console.log(`✔ skill 框架文件更新完成${verb} — ${dir}
   - 新增 ${added.length} 个${added.length ? `: ${added.join(', ')}` : ''}
-  - 更新 ${changed.length} 个（旧文件备份为 *.bak）${changed.length ? `: ${changed.join(', ')}` : ''}
+  - 更新 ${changed.length} 个${changed.length ? `: ${changed.join(', ')}` : ''}
   - 未变 ${same.length} 个
-  - agile/ 数据目录未做任何改动
-
-${changed.length ? '提示: 更新会覆盖目标项目里对框架文件的本地修改（已备份 *.bak）。若目标项目自定义过 skill，请 diff 对比后手动合并。' : '已是最新，无需操作。'}`);
+  - agile/ 数据目录未做任何改动${bakLines ? `\n  - 覆盖前已备份${bakLines.replace(/^ {2}/gm, '\n    ')}` : ''}
+
+${backups.length
+    ? `提示: 框架文件是整篇覆盖的，你在这几个文件里的本地改动都在上面的备份里。
+让 agent 助手（CodeBuddy / Claude Code 等）合并回来即可，直接说：
+  「对比 ${backups[0].rel} 与 ${backups[0].bak}，把我的本地改动合并回来」${backups.length > 1 ? `\n  （其余 ${backups.length - 1} 个文件同理，备份文件名见上方）` : ''}
+确认合并无误后再删掉备份。AGENTS.md 是 agent 的入口纪律文件，先合并它、再让它去改别的文件最稳。`
+    : '已是最新，无需操作。'}`);
 }
 
 function runTool(script, needPort) {

package/package.json

@@ -1,41 +1,40 @@
-{
-  "name": "scrum-skills",
-  "version": "0.2.2",
-  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，Nuxt 看板可视化",
-  "type": "module",
-  "keywords": [
-    "agile",
-    "scrum",
-    "sprint",
-    "tdd",
-    "kanban",
-    "gantt",
-    "burndown",
-    "skills",
-    "cli"
-  ],
-  "bin": {
-    "scrum-skills": "./bin/scrum-skills.mjs",
-    "scsk": "./bin/scrum-skills.mjs"
-  },
-  "scripts": {
-    "validate": "node tools/validate.mjs",
-    "serve": "node tools/serve.mjs",
-    "test": "node --test",
-    "dev": "pnpm --dir apps/board run dev",
-    "build": "node scripts/build-board.mjs",
-    "prepublishOnly": "node scripts/build-board.mjs"
-  },
-  "files": [
-    "bin/",
-    "tools/",
-    "templates/",
-    ".agents/",
-    "assets/",
-    "docs/"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT"
-}
+{
+  "name": "scrum-skills",
+  "version": "0.2.4",
+  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，Nuxt 看板可视化",
+  "type": "module",
+  "keywords": [
+    "agile",
+    "scrum",
+    "sprint",
+    "tdd",
+    "kanban",
+    "gantt",
+    "burndown",
+    "skills",
+    "cli"
+  ],
+  "bin": {
+    "scrum-skills": "./bin/scrum-skills.mjs",
+    "scsk": "./bin/scrum-skills.mjs"
+  },
+  "files": [
+    "bin/",
+    "tools/",
+    "templates/",
+    ".agents/",
+    "assets/",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "scripts": {
+    "validate": "node tools/validate.mjs",
+    "serve": "node tools/serve.mjs",
+    "test": "node --test",
+    "dev": "pnpm --dir apps/board run dev",
+    "build": "node scripts/build-board.mjs"
+  }
+}

package/templates/AGENTS.md

@@ -32,7 +32,7 @@
 
 ## 状态机（摘要）
 
-- story: `draft → ready → in-progress → review → done`
+- story: `draft → ready → in-progress → review → done`；不做就走 `cancelled`（已取消，终态，不要求验收与任务全 done）
 - task: `todo → red → green → refactored → done`（只能前进；task 状态编码了 TDD 阶段）
 - 详细规则与硬约束见 `.agents/skills/scrum-planning/references/schema.md`。