scrum-skills 0.1.2 → 0.2.0

package/bin/scrum-skills.mjs

@@ -3,7 +3,7 @@
  * scrum-skills CLI（零依赖，node >= 18）
  * 命令:
  *   scrum-skills init [dir] [--force]  初始化敏捷开发文件到目标文件夹（默认当前目录）
- *                                      拷贝 .agents/skills/、AGENTS.md、tools/validate.mjs，建 agile/ 目录骨架
+ *                                      拷贝 .agents/skills/、AGENTS.md、tools/validate.mjs，建 agile/ 三文件骨架
  *                                      已存在 AGENTS.md 时拒绝，--force 覆盖（备份为 AGENTS.md.bak）
  *   scrum-skills update [dir] [--dry-run]  更新已初始化项目里的 skill 文件（.agents/、AGENTS.md、tools/validate.mjs）
  *                                      只刷新框架文件，绝不碰 agile/ 数据；每个被覆盖的文件先备份为 *.bak
@@ -46,19 +46,31 @@ function init() {
   mkdirSync(join(dir, 'tools'), { recursive: true });
   cpSync(join(PKG_ROOT, 'tools/validate.mjs'), join(dir, 'tools/validate.mjs'));
 
-  for (const sub of ['backlog/epics', 'backlog/stories', 'sprints', 'journal'])
-    mkdirSync(join(dir, 'agile', sub), { recursive: true });
+  // 数据骨架：schema v2 三文件结构（已有文件不覆盖，避免踩坏真实数据）
+  mkdirSync(join(dir, 'agile'), { recursive: true });
+  const skeleton = {
+    'backlog.json': { schemaVersion: 3, epics: [], stories: [] },
+    'sprints.json': { schemaVersion: 3, sprints: [], milestones: [] },
+    'journal.json': { schemaVersion: 3, journals: [] },
+  };
+  const created = [];
+  for (const [name, body] of Object.entries(skeleton)) {
+    const p = join(dir, 'agile', name);
+    if (existsSync(p)) continue;
+    writeFileSync(p, JSON.stringify(body, null, 2) + '\n');
+    created.push(`agile/${name}`);
+  }
 
   console.log(`✔ 已初始化到 ${dir}
   - .agents/skills/      四个敏捷 skill（planning / sprint / tdd / report）
   - AGENTS.md            agent 入口纪律文件${backed ? '（旧文件已备份为 AGENTS.md.bak）' : ''}
   - tools/validate.mjs   数据校验脚本
-  - agile/               数据目录骨架（backlog / sprints / journal）
+  - agile/ 三文件结构${created.length ? `（新建 ${created.join('、')}）` : '（已存在，未覆盖）'}
 
 下一步:
   1. 在目标项目里让 AI 读 AGENTS.md，用 scrum-planning 建第一个 story
   2. 每次改动后运行: node tools/validate.mjs
-  3. 看板/燃尽图: 在目标项目目录下运行 scrum-skills serve`);
+  3. 看板: 在目标项目目录下运行 scrum-skills serve，打开 http://localhost:4173`);
 }
 
 function walkFiles(dir, base = '') {

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "scrum-skills",
-  "version": "0.1.2",
-  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，数据可视化看板",
+  "version": "0.2.0",
+  "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"
   },
+  "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/"
+    ".agents/",
+    "assets/",
+    "docs/"
   ],
   "engines": {
     "node": ">=18"

package/templates/AGENTS.md

@@ -6,22 +6,28 @@
 
 1. **数据是唯一事实来源**。所有需求、任务、进度状态以 `agile/` 目录下的 JSON 文件为准，对话记忆一律不作数。每次接手工作先读 `agile/` 掌握现状，再决定下一步。
 2. **必须使用敏捷 skills**（位于 `.agents/skills/`），按场景加载，不要全量加载（省上下文）：
-   - 需求澄清、写故事、拆任务 → **scrum-planning**
+   - 需求澄清（brainstorming 式逐问收敛）、写故事、拆任务 → **scrum-planning**
    - 排期、组建迭代、状态流转、收尾回顾 → **scrum-sprint**
-   - 领取任务写代码（TDD 循环 + 实施日志落库）→ **scrum-tdd**
+   - 领取任务写代码（TDD 循环 + 实施日志落库；含系统化排障纪律与交工前真实验证）→ **scrum-tdd**
    - 看板/燃尽图/追溯链可视化 → **scrum-report**
-3. **对话产出必须落库**。凡是确认要做的事，必须写进 `agile/backlog/`（结构见 `.agents/skills/scrum-planning/references/schema.md`），禁止只停留在对话里。
-4. **TDD 铁律**：任务实施走 red → green → refactor 循环，没写过失败测试不许写实现；每步过程必须当场写入 `agile/journal/`（不许事后补记）。
+3. **对话产出必须落库**。凡是确认要做的事，必须写进 `agile/backlog.json`（结构见 `.agents/skills/scrum-planning/references/schema.md`），禁止只停留在对话里。每条故事必须带 `type` / `priority` / `value`，验收标准必须带 `verifyBy`；依赖写 `dependsOn`，被卡住写 `blocked`，中途插入或拆分出来的写 `scopeChange`——这些不写进 JSON，看板和甘特图就读不到。
+4. **TDD 铁律**：任务实施走 red → green → refactor 循环，没写过失败测试不许写实现；每步过程必须当场追加到 `agile/journal.json` 里对应 task 的 `entries`（不许事后补记）。
 5. **每次修改敏捷数据后必须运行校验**，校验不过不许继续：
 
    ```bash
    node tools/validate.mjs
    ```
 
-6. **可视化**（server 不在本项目内，由 scrum-skills CLI 提供）：
+   动了 `tools/validate.mjs` 本身则要跑回归测试，确认没把既有规则弄回退：
 
    ```bash
-   npx scrum-skills serve        # http://localhost:4173 看板 / 燃尽图 / story 追溯链
+   pnpm test
+   ```
+
+6. **可视化**：
+
+   ```bash
+   node tools/serve.mjs        # http://localhost:4173 看板 / 燃尽图 / story 追溯链
    ```
 
 ## 状态机（摘要）
@@ -35,8 +41,16 @@
 | 路径 | 内容 |
 |---|---|
 | `.agents/skills/` | 四个敏捷 skill（planning / sprint / tdd / report） |
-| `agile/backlog/epics/` | 史诗 E-*.json |
-| `agile/backlog/stories/` | 用户故事 S-*.json（含验收标准与任务） |
-| `agile/sprints/` | 迭代 P*-S*.json |
-| `agile/journal/` | 每任务一篇 TDD 实施日志 |
-| `tools/validate.mjs` | 数据校验（引用完整性 / 状态机 / TDD 纪律） |
+| `agile/backlog.json` | 史诗 epics + 用户故事 stories（story 内联 tasks） |
+| `agile/sprints.json` | 迭代 sprints + 里程碑 milestones（MVP 节点 = `kind: "mvp"`） |
+| `agile/journal.json` | 每个 task 一条 TDD 实施日志（内联 entries） |
+| `tools/validate.mjs` | 数据校验（引用完整性 / 状态机 / TDD 纪律 / 里程碑达成） |
+| `tools/serve.mjs` | 看板 server（`/api/agile` + 托管 Nuxt 静态产物） |
+| `apps/board/` | Nuxt 看板源码（看板 / 甘特图 / 里程碑 / 燃尽图 / 故事追溯） |
+| `assets/board/` | 看板静态产物，由 `serve` 托管；**不进 git**，用 `pnpm board:build` 重建（`npm publish` 的 prepack 会自动跑一次） |
+| `scripts/build-board.mjs` | 构建看板：`apps/board` → `assets/board` |
+| `tests/` | 校验器回归测试（`pnpm test`，18 个用例） |
+| `docs/` | README 配图 |
+| `README.md` | 包说明（npm 页面） |
+
+`agile/` 三个文件里目前是一整套演示数据（3 史诗 / 16 故事 / 4 迭代 / 5 里程碑 / 39 任务），正式使用前清空三文件的数组即可。

package/tools/serve.mjs

@@ -1,166 +1,111 @@
 #!/usr/bin/env node
 /**
- * 敏捷数据可视化 server（零依赖，node >= 18）
+ * 敏捷看板 server（零依赖，node >= 18）
  * 用法: node tools/serve.mjs [目标目录] [port]   目录默认 cwd，端口默认 4173
- * 页面: / 看板 | /burndown 燃尽图 | /story/:id 追溯链
- * 校验不通过时拒绝出报表，提示先跑 validate
+ *
+ * 它只做两件事：
+ *   1. /api/agile  把目标目录 agile/*.json（三文件结构）吐给前端
+ *   2. 其余路径     托管 Nuxt 静态产物（assets/board），SPA 回退 index.html
+ * 页面渲染全部由 Nuxt 产物负责，这里没有任何手写 HTML。
+ * 校验不通过时拒绝出报表，提示先跑 validate。
  */
-import { readdirSync, readFileSync, existsSync } from 'node:fs';
-import { join, basename, resolve } from 'node:path';
+import { readFileSync, existsSync, statSync, createReadStream } from 'node:fs';
+import { join, resolve, extname, normalize, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
 
-const PKG_ROOT = new URL('..', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1');
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const TARGET = resolve(process.argv[2] || process.cwd());
 const PORT = Number(process.argv[3] || 4173);
 const AGILE = join(TARGET, 'agile');
 
-// ---- 数据加载 ----
-function readJson(dir) {
-  const out = [];
-  if (!existsSync(dir)) return out;
-  for (const f of readdirSync(dir)) if (f.endsWith('.json'))
-    out.push(JSON.parse(readFileSync(join(dir, f), 'utf8')));
-  return out;
+// 静态产物：优先用包内 assets/board，仓库内开发时退化到 apps/board/.output/public
+const BOARD_DIR = [
+  join(PKG_ROOT, 'assets/board'),
+  join(PKG_ROOT, 'apps/board/.output/public'),
+].find(d => existsSync(join(d, 'index.html')));
+
+if (!BOARD_DIR) {
+  console.error('✘ 找不到看板静态产物（assets/board/index.html）。请在仓库里先跑 pnpm --dir apps/board run generate');
+  process.exit(1);
+}
+
+try {
+  execFileSync(process.execPath, [join(PKG_ROOT, 'tools/validate.mjs'), TARGET], { stdio: 'pipe' });
+} catch (e) {
+  console.error(`✘ ${TARGET} 下的数据校验未通过，拒绝出报表。请先修复：\n${e.stdout ?? e.message}`);
+  process.exit(1);
 }
-function load() {
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function readAgile() {
+  const read = f => JSON.parse(readFileSync(join(AGILE, f), 'utf8'));
   return {
-    epics: readJson(join(AGILE, 'backlog/epics')),
-    stories: readJson(join(AGILE, 'backlog/stories')),
-    sprints: readJson(join(AGILE, 'sprints')),
-    journals: readJson(join(AGILE, 'journal')),
+    backlog: read('backlog.json'),
+    sprints: read('sprints.json'),
+    journal: read('journal.json'),
+    meta: { root: TARGET, servedAt: new Date().toISOString() },
   };
 }
 
-// ---- 聚合 ----
-function storyCard(s) {
-  const tasks = s.tasks ?? [];
-  const done = tasks.filter(t => t.status === 'done').length;
-  return { id: s.id, title: s.title, points: s.points, sprintId: s.sprintId,
-           epicId: s.epicId, done, total: tasks.length };
+function sendFile(res, file) {
+  res.writeHead(200, {
+    'content-type': MIME[extname(file).toLowerCase()] ?? 'application/octet-stream',
+    'cache-control': 'no-cache',
+  });
+  createReadStream(file).pipe(res);
 }
-function burndown(sprints, stories, journals) {
-  const today = new Date().toISOString().slice(0, 10);
-  const sp = sprints.filter(s => s.start <= today && s.end >= today)[0] || sprints[0];
-  if (!sp) return null;
-  const total = (sp.stories ?? []).reduce((a, sid) => {
-    const st = stories.find(s => s.id === sid); return a + (st?.points ?? 0);
-  }, 0);
-  // 每个 task 的 done 日期取其 journal 最后一条 pass 的 date
-  const doneDate = new Map();
-  for (const j of journals) {
-    const entries = (j.entries ?? []).filter(e => /^pass/i.test(e.result || ''));
-    if (entries.length) doneDate.set(j.taskId, entries[entries.length - 1].date);
-  }
-  const days = [];
-  for (let d = new Date(sp.start); d <= new Date(sp.end); d.setDate(d.getDate() + 1)) {
-    const ds = d.toISOString().slice(0, 10);
-    let burned = 0;
-    for (const sid of sp.stories ?? []) {
-      const st = stories.find(s => s.id === sid);
-      if (!st || st.status !== 'done') continue;
-      const nDone = (st.tasks ?? []).filter(t => doneDate.get(t.id) <= ds).length;
-      burned += (st.points || 0) * ((st.tasks?.length || 1) > 0 ? nDone / st.tasks.length : 0);
+
+const server = createServer((req, res) => {
+  const url = new URL(req.url, 'http://x');
+  const pathname = decodeURIComponent(url.pathname);
+
+  if (pathname === '/api/agile') {
+    try {
+      const body = JSON.stringify(readAgile());
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(body);
+    } catch (e) {
+      res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify({ error: String(e.message) }));
     }
-    days.push({ date: ds, remaining: Math.round((total - burned) * 10) / 10 });
+    return;
   }
-  return { sprint: sp, total, days };
-}
-
-// ---- 页面（内联极简 HTML+SVG，无外部依赖） ----
-const CSS = `<style>
- *{box-sizing:border-box} body{font:14px/1.6 system-ui,sans-serif;margin:0;background:#f5f6fb;color:#1b1c20}
- header{background:linear-gradient(135deg,#4a7cf6,#7a5af5);color:#fff;padding:18px 28px}
- header a{color:#fff;margin-right:18px;text-decoration:none;opacity:.9}
- main{padding:24px;max-width:1200px;margin:0 auto}
- .cols{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:14px}
- .col h3{margin:0 0 8px;font-size:13px;color:#666}
- .card{background:#fff;border-radius:12px;box-shadow:0 2px 8px rgba(0,0,0,.06);padding:12px;margin-bottom:10px}
- .card b{font-size:14px} .meta{font-size:12px;color:#888;margin-top:4px}
- .bar{height:5px;background:#e9edfe;border-radius:99px;margin-top:8px;overflow:hidden}
- .bar i{display:block;height:100%;background:linear-gradient(90deg,#4a7cf6,#7a5af5)}
- .chip{display:inline-block;background:#e9edfe;border:1px solid #d7ddfc;border-radius:99px;padding:0 9px;font-size:11px;margin-right:6px}
- .ac{background:#fff;border-radius:12px;box-shadow:0 2px 8px rgba(0,0,0,.06);padding:14px;margin-bottom:12px}
- .phase{border-left:4px solid #ccc;padding:8px 14px;margin:8px 0;background:#fff;border-radius:0 10px 10px 0}
- .red{border-color:#e05260}.green{border-color:#3aa76d}.refactor{border-color:#4a7cf6}
- pre{background:#f0f1f5;padding:8px 12px;border-radius:8px;overflow:auto;font-size:12px}
-</style>`;
-const page = (title, body) => `<!doctype html><html lang="zh"><head><meta charset="utf-8"><title>${title}</title>${CSS}</head>
-<body><header><strong>敏捷看板</strong>
-<a href="/">看板</a><a href="/burndown">燃尽图</a></header><main>${body}</main></body></html>`;
 
-function kanbanHtml(d) {
-  const cols = ['draft', 'ready', 'in-progress', 'review', 'done'];
-  const label = { draft: '草稿', ready: '就绪', 'in-progress': '进行中', review: '评审', done: '完成' };
-  return page('看板', `<h2>看板</h2><div class="cols">` + cols.map(c => {
-    const cards = d.stories.filter(s => (s.status ?? 'draft') === c).map(s => {
-      const sc = storyCard(s);
-      const pct = sc.total ? Math.round(sc.done / sc.total * 100) : 0;
-      return `<div class="card"><span class="chip">${sc.id}</span>${sc.sprintId ? `<span class="chip">${sc.sprintId}</span>` : ''}
-        <b><a href="/story/${sc.id}">${sc.title}</a></b>
-        <div class="meta">${sc.epicId ?? ''} · ${sc.points ?? '?'} 点 · 任务 ${sc.done}/${sc.total}</div>
-        <div class="bar"><i style="width:${pct}%"></i></div></div>`;
-    }).join('');
-    return `<div class="col"><h3>${label[c]}（${cards ? d.stories.filter(s => s.status === c).length : 0}）</h3>${cards}</div>`;
-  }).join('') + '</div>');
-}
+  // 静态文件：防目录穿越 + SPA 回退
+  const rel = normalize(pathname).replace(/^([/\\])+/, '');
+  const file = join(BOARD_DIR, rel);
+  if (!file.startsWith(BOARD_DIR + sep) && file !== BOARD_DIR) {
+    res.writeHead(403).end('forbidden');
+    return;
+  }
+  if (pathname !== '/' && existsSync(file) && statSync(file).isFile()) return sendFile(res, file);
 
-function burndownHtml(d) {
-  const b = burndown(d.sprints, d.stories, d.journals);
-  if (!b) return page('燃尽图', '<h2>燃尽图</h2><p>暂无 sprint 数据。</p>');
-  const W = 900, H = 320, P = 40;
-  const n = b.days.length || 1;
-  const maxV = b.total || 1;
-  const x = i => P + i * (W - 2 * P) / (n - 1 || 1);
-  const y = v => H - P - v * (H - 2 * P) / maxV;
-  const pts = b.days.map((d, i) => `${x(i)},${y(d.remaining)}`).join(' ');
-  const ideal = `M${x(0)},${y(b.total)} L${x(n - 1)},${y(0)}`;
-  const labels = b.days.map((d, i) => i % Math.ceil(n / 10) === 0
-    ? `<text x="${x(i)}" y="${H - 15}" font-size="10" text-anchor="middle" fill="#888">${d.date.slice(5)}</text>` : '').join('');
-  return page('燃尽图', `<h2>燃尽图 — ${b.sprint.name}（${b.sprint.start} ~ ${b.sprint.end}，总 ${b.total} 点）</h2>
-  <svg viewBox="0 0 ${W} ${H}" style="max-width:960px;width:100%">
-    <line x1="${P}" y1="${y(0)}" x2="${W - P}" y2="${y(0)}" stroke="#ccc"/>
-    <line x1="${P}" y1="${P}" x2="${P}" y2="${y(0)}" stroke="#ccc"/>
-    <path d="${ideal}" stroke="#c9c9d4" stroke-dasharray="6 5" fill="none"/>
-    <polyline points="${pts}" stroke="#4a7cf6" stroke-width="2.5" fill="none"/>
-    ${b.days.map((d, i) => `<circle cx="${x(i)}" cy="${y(d.remaining)}" r="3.5" fill="#7a5af5"/>`).join('')}
-    ${labels}
-  </svg><p class="meta">虚线为理想燃尽线；点数据来自 journal 的 pass 日期，缺口说明有 task 未按纪律落库。</p>`);
-}
+  const index = join(BOARD_DIR, 'index.html');
+  if (existsSync(index)) return sendFile(res, index);
 
-function storyHtml(d, id) {
-  const s = d.stories.find(x => x.id === id);
-  if (!s) return page('404', `<h2>未找到 ${id}</h2>`);
-  const ac = (s.acceptance ?? []).map(a =>
-    `<li><b>Given</b> ${a.given}；<b>When</b> ${a.when}；<b>Then</b> ${a.then}</li>`).join('');
-  const tasks = (s.tasks ?? []).map(t => {
-    const j = d.journals.find(x => x.taskId === t.id);
-    const entries = (j?.entries ?? []).map(e =>
-      `<div class="phase ${e.phase}"><b>${e.phase.toUpperCase()}</b> <span class="meta">${e.date} · ${e.result ?? ''}</span>
-       <div>${e.note}</div>${e.files?.length ? `<div class="meta">文件：${e.files.join(', ')}</div>` : ''}
-       ${e.testCommand ? `<pre>${e.testCommand}</pre>` : ''}</div>`).join('');
-    return `<div class="ac"><span class="chip">${t.id}</span><span class="chip">${t.type}</span><span class="chip">${t.status}</span>
-      <b>${t.title}</b>${entries || '<p class="meta">暂无实施记录</p>'}</div>`;
-  }).join('');
-  return page(id, `<h2><span class="chip">${s.id}</span>${s.title}</h2>
-    <p>${s.narrative ?? ''}</p><p class="meta">${s.epicId ?? ''} · ${s.sprintId ?? '未排期'} · ${s.points ?? '?'} 点 · 状态 ${s.status}</p>
-    <h3>验收标准</h3><ol>${ac}</ol><h3>任务与实施记录</h3>${tasks}`);
-}
+  res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('not found');
+});
 
-// ---- server ----
-try { execFileSync(process.execPath, [join(PKG_ROOT, 'tools/validate.mjs'), TARGET], { stdio: 'pipe' }); }
-catch (e) {
-  console.error(`✘ ${TARGET} 下的数据校验未通过，拒绝出报表。请先修复：\n` + e.stdout);
-  process.exit(1);
-}
-import('node:http').then(({ createServer }) => {
-  createServer((req, res) => {
-    const d = load();
-    const url = new URL(req.url, 'http://x');
-    let html = null;
-    if (url.pathname === '/') html = kanbanHtml(d);
-    else if (url.pathname === '/burndown') html = burndownHtml(d);
-    else if (url.pathname.startsWith('/story/')) html = storyHtml(d, url.pathname.slice(7));
-    if (html) { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); res.end(html); }
-    else { res.writeHead(404); res.end('not found'); }
-  }).listen(PORT, () => console.log(`敏捷看板: http://localhost:${PORT}`));
+server.listen(PORT, () => {
+  console.log(`敏捷看板: http://localhost:${PORT}`);
+  console.log(`  数据目录: ${AGILE}`);
+  console.log(`  静态产物: ${BOARD_DIR}`);
 });