@aibyzero/byz 0.1.1 → 0.1.3

package/workflows/cm-plugin/templates/auto-update/cm-update.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# cm-plugin-workflow 自动更新：检测上游有新提交则拉取并安装
+# 用法: cm-update.sh [--throttle] [--force] [--check]
+# 分发源: cm-plugin-workflow 仓库 templates/auto-update/（本文件由 install.sh 装到 ~/.cm-plugin-workflow/,
+#         更新自己时经 tmp+mv 原子替换,不会截断正在运行的实例）
+set -uo pipefail
+
+ROOT="$HOME/.cm-plugin-workflow"
+REPO="$ROOT/repo"
+DEST="${CLAUDE_HOME:-$HOME/.claude}"
+MANIFEST="$ROOT/manifest.txt"
+LOG="$ROOT/update.log"
+STAMP="$ROOT/.last-check"
+LOCK="$ROOT/.lock"
+ANNOUNCE="$ROOT/pending-announce"   # 下次 Claude Code 启动时播报，由 cm-announce.sh 消费
+REMOTE="${CM_UPDATE_REMOTE:-git@github.com:kingxiaozhe/cm-plugin-workflow.git}"   # 团队 fork 用环境变量覆盖,别改文件(会被自愈还原)
+BRANCH="${CM_UPDATE_BRANCH:-main}"
+THROTTLE_SECS=900   # --throttle 模式下两次 fetch 的最小间隔
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+export GIT_TERMINAL_PROMPT=0
+export GIT_SSH_COMMAND="ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=15"
+
+mkdir -p "$ROOT"
+
+log()    { printf '%s  %s\n' "$(date '+%F %T')" "$*" >>"$LOG"; }
+notify() { osascript -e "display notification \"$2\" with title \"$1\"" >/dev/null 2>&1 || true; }
+die()    { log "✗ $*"; exit 1; }
+
+THROTTLE=0; FORCE=0; CHECK_ONLY=0
+for a in "$@"; do
+  case "$a" in
+    --throttle) THROTTLE=1 ;;
+    --force)    FORCE=1 ;;
+    --check)    CHECK_ONLY=1 ;;
+  esac
+done
+
+# ---- 单实例锁（mkdir 原子；超过 30 分钟视为陈旧锁）----
+if ! mkdir "$LOCK" 2>/dev/null; then
+  if [ -n "$(find "$LOCK" -maxdepth 0 -mmin +30 2>/dev/null)" ]; then
+    rmdir "$LOCK" 2>/dev/null && mkdir "$LOCK" 2>/dev/null || exit 0
+    log "清除陈旧锁"
+  else
+    exit 0   # 另一个实例在跑
+  fi
+fi
+trap 'rmdir "$LOCK" 2>/dev/null || true' EXIT
+
+# ---- 限流：启动 hook 频繁触发时避免每次都连网 ----
+if [ "$THROTTLE" = 1 ] && [ "$FORCE" = 0 ] && [ -f "$STAMP" ]; then
+  if [ -z "$(find "$STAMP" -maxdepth 0 -mmin +$((THROTTLE_SECS / 60)) 2>/dev/null)" ]; then
+    exit 0
+  fi
+fi
+
+# ---- 首次运行：clone ----
+if [ ! -d "$REPO/.git" ]; then
+  log "首次克隆 $REMOTE"
+  rm -rf "$REPO"
+  git clone --quiet "$REMOTE" "$REPO" || die "克隆失败（检查 SSH 凭证）"
+fi
+
+cd "$REPO" || die "仓库目录不可用: $REPO"
+
+if ! git fetch --quiet origin "$BRANCH" 2>>"$LOG"; then
+  log "fetch 失败（离线或凭证问题），本次跳过"
+  exit 0
+fi
+touch "$STAMP"
+
+local_sha="$(git rev-parse HEAD 2>/dev/null)"
+remote_sha="$(git rev-parse "origin/$BRANCH" 2>/dev/null)"
+
+if [ "$CHECK_ONLY" = 1 ]; then
+  if [ "$local_sha" = "$remote_sha" ]; then
+    echo "已是最新: $(cat "$DEST/templates/cm-plugin-VERSION" 2>/dev/null) ($(git rev-parse --short HEAD))"
+  else
+    echo "有更新: $(git rev-parse --short HEAD) → $(git rev-parse --short "origin/$BRANCH")"
+    git log --oneline "HEAD..origin/$BRANCH" | sed 's/^/  /'
+  fi
+  exit 0
+fi
+
+# ---- 运行中工作流保护：/cm-plugin:ai 正在跑时不换安装文件（中途换版 = 混装风险）----
+# 实证事故：2026-07-17 10:06 自动更新 v0.9.27 恰逢 diff-lens 运行中(10:04–10:17)，
+# 节点文件被中途替换。状态新鲜(30分钟内有写入)才算真在跑；僵死的 running 不拦更新。
+PTR="$HOME/.claude/cm-plugin-current-specs"
+if [ -f "$PTR" ]; then
+  ACTIVE_SPECS="$(head -1 "$PTR" 2>/dev/null | tr -d '[:space:]')"
+  ACTIVE_ST="$ACTIVE_SPECS/.cm-status.json"
+  if [ -n "$ACTIVE_SPECS" ] && [ -f "$ACTIVE_ST" ] \
+     && grep -q '"state":"running"' "$ACTIVE_ST" 2>/dev/null \
+     && [ -n "$(find "$ACTIVE_ST" -maxdepth 0 -mmin -30 2>/dev/null)" ]; then
+    log "工作流运行中($ACTIVE_SPECS)，本轮跳过安装，避免中途换版"
+    exit 0
+  fi
+fi
+
+# ---- 源文件 ↔ 安装目标 的配对（必须与 install.sh 的拷贝映射一致）----
+# 输出 "源路径<TAB>目标路径"。安装清单和完整性校验都基于它，只此一份映射。
+TAB="$(printf '\t')"
+build_pairs() {
+  local part
+  for part in commands skills agents; do
+    if [ -d "$REPO/$part" ]; then
+      ( cd "$REPO/$part" && find . -type f ) \
+        | sed "s|^\./\(.*\)$|$REPO/$part/\1$TAB$DEST/$part/\1|"
+    fi
+  done
+  if [ -d "$REPO/templates/rules" ]; then
+    ( cd "$REPO/templates/rules" && find . -type f ) \
+      | sed "s|^\./\(.*\)$|$REPO/templates/rules/\1$TAB$DEST/templates/cm-plugin-rules/\1|"
+  fi
+  if [ -f "$REPO/templates/arch-reference.md" ]; then
+    echo "$REPO/templates/arch-reference.md$TAB$DEST/templates/cm-plugin-arch-reference.md"
+  fi
+  if [ -d "$REPO/templates/scripts" ]; then
+    ( cd "$REPO/templates/scripts" && find . -type f ) \
+      | sed "s|^\./\(.*\)$|$REPO/templates/scripts/\1$TAB$DEST/templates/cm-plugin-scripts/\1|"
+  fi
+  if [ -d "$REPO/templates/e2e" ]; then
+    ( cd "$REPO/templates/e2e" && find . -type f ) \
+      | sed "s|^\./\(.*\)$|$REPO/templates/e2e/\1$TAB$DEST/templates/cm-plugin-e2e/\1|"
+  fi
+  if [ -d "$REPO/templates/dashboard" ]; then
+    ( cd "$REPO/templates/dashboard" && find . -type f ) \
+      | sed "s|^\./\(.*\)$|$REPO/templates/dashboard/\1$TAB$DEST/templates/cm-plugin-dashboard/\1|"
+  fi
+  if [ -f "$REPO/templates/statusline/cm-plugin-statusline.sh" ]; then
+    echo "$REPO/templates/statusline/cm-plugin-statusline.sh$TAB$DEST/templates/cm-plugin-statusline.sh"
+  fi
+  if [ -d "$REPO/templates/pixel" ]; then
+    ( cd "$REPO/templates/pixel" && find . -type f -not -path './dev/*' ) \
+      | sed "s|^\./\(.*\)$|$REPO/templates/pixel/\1$TAB$DEST/templates/cm-plugin-pixel/\1|"
+  fi
+  if [ -f "$REPO/templates/hooks/pre-commit-cm-task-check" ]; then
+    echo "$REPO/templates/hooks/pre-commit-cm-task-check$TAB$DEST/templates/cm-plugin-task-check-hook"
+  fi
+  if [ -f "$REPO/templates/refactor/cm-refactor-denies.json" ]; then
+    echo "$REPO/templates/refactor/cm-refactor-denies.json$TAB$DEST/templates/cm-plugin-refactor-denies.json"
+  fi
+  # 更新器自身也纳入校验与自愈（安装走 tmp+mv 原子替换；清理循环有 $DEST 前缀守卫,不会误删这里）
+  if [ -d "$REPO/templates/auto-update" ]; then
+    echo "$REPO/templates/auto-update/cm-update.sh$TAB$ROOT/cm-update.sh"
+    echo "$REPO/templates/auto-update/cm-announce.sh$TAB$ROOT/cm-announce.sh"
+  fi
+  # cm-VERSION 由 install.sh 从 VERSION 生成，内容与之逐字节相同，故可直接配对校验
+  echo "$REPO/VERSION$TAB$DEST/templates/cm-plugin-VERSION"
+}
+
+build_manifest() { build_pairs | cut -d"$TAB" -f2; }
+
+# 校验已装文件是否仍与仓库一致；输出漂移清单（空 = 一切正常）
+verify_install() {
+  build_pairs | while IFS="$TAB" read -r src dest; do
+    if [ ! -e "$dest" ]; then
+      echo "缺失 ${dest#$DEST/}"
+    elif ! cmp -s "$src" "$dest"; then
+      echo "被改动 ${dest#$DEST/}"
+    fi
+  done
+}
+
+# ---- 无新提交时：校验完整性，只有被改坏/误删才自愈重装 ----
+REPAIR=0
+if [ "$local_sha" = "$remote_sha" ] && [ -f "$MANIFEST" ] && [ "$FORCE" = 0 ]; then
+  drift="$(verify_install)"
+  if [ -z "$drift" ]; then
+    exit 0   # 无更新且文件完好，静默退出
+  fi
+  REPAIR=1
+  drift_n="$(echo "$drift" | wc -l | tr -d ' ')"
+  log "无新提交，但 $drift_n 个文件与仓库不一致，自愈重装："
+  log "$(echo "$drift" | sed 's|^|    |')"
+fi
+
+new_commits="$(git log --oneline "HEAD..origin/$BRANCH" 2>/dev/null | head -5)"
+git reset --hard --quiet "origin/$BRANCH" || die "reset 到 origin/$BRANCH 失败"
+git clean -qfd
+VERSION="$(cat "$REPO/VERSION" 2>/dev/null || echo 未知)"
+if [ "$REPAIR" = 0 ]; then
+  log "发现更新 ${local_sha:0:7} → ${remote_sha:0:7} (v$VERSION)"
+  [ -n "$new_commits" ] && log "$(echo "$new_commits" | sed 's/^/    /')"
+fi
+
+NEW_MANIFEST="$(mktemp)"
+build_manifest | sort -u >"$NEW_MANIFEST"
+[ -s "$NEW_MANIFEST" ] || { rm -f "$NEW_MANIFEST"; die "清单为空，中止安装（仓库结构异常？）"; }
+
+# ---- 清理：只删“上一版装过、这一版没有”的文件，绝不碰清单外的东西 ----
+removed=0
+if [ -f "$MANIFEST" ]; then
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in "$DEST"/*) ;; *) continue ;; esac   # 安全网：只删 ~/.claude 内
+    if [ -e "$f" ]; then
+      rm -f "$f" && removed=$((removed + 1)) && log "  - 删除 ${f#$DEST/}"
+    fi
+  done < <(comm -23 <(sort -u "$MANIFEST") "$NEW_MANIFEST")
+fi
+
+# ---- 安装（yes 应答 install.sh 的覆盖确认，避免无人值守卡住）----
+# 两处规避，别随手改掉：
+#  1) 关 pipefail：install.sh 结束后 yes 会吃到 SIGPIPE(141)，否则被误判为失败
+#  2) LC_ALL=C：老版本 install.sh 里 "$part？" 这类写法，在 UTF-8 locale + bash 3.2 下
+#     会把全角字符并进变量名，触发 set -u 报错。上游 v0.9.21 (eade178) 已改用 ${part}，
+#     这里保留纯属防御：万一回滚到旧提交，或哪天又写回这种形式，更新链路不至于断掉。
+set +o pipefail
+install_out="$(yes | LC_ALL=C LANG=C bash "$REPO/install.sh" 2>&1)"
+install_rc=$?
+set -o pipefail
+if [ $install_rc -ne 0 ]; then
+  log "✗ install.sh 失败 (rc=$install_rc)"
+  log "$(echo "$install_out" | tail -15 | sed 's/^/    /')"
+  rm -f "$NEW_MANIFEST"
+  notify "cm-workflow 更新失败" "install.sh 报错，详见 ~/.cm-plugin-workflow/update.log"
+  exit 1
+fi
+
+mv "$NEW_MANIFEST" "$MANIFEST"
+
+# 清掉清理后可能残留的空目录
+find "$DEST/skills" "$DEST/commands" "$DEST/agents" "$DEST/templates" -type d -empty -delete 2>/dev/null || true
+
+installed="$(cat "$DEST/templates/cm-plugin-VERSION" 2>/dev/null || echo "$VERSION")"
+if [ "$REPAIR" = 1 ]; then
+  log "✓ 自愈完成，已恢复到 v$installed (${remote_sha:0:7})"
+else
+  log "✓ 已更新到 v$installed (${remote_sha:0:7})，清理 $removed 个旧文件"
+fi
+
+# 播报走两条路，互不依赖：
+#  1) 待播报文件 → 下次 Claude Code 启动时由 cm-announce.sh 报出来。这是主路径：
+#     更新本来就要重开 Claude Code 才生效，在启动时说时机正好，且不看系统权限脸色。
+#  2) macOS 通知 → 锦上添花。本机 osascript 未在通知中心注册，实测弹不出来，
+#     所以绝不能依赖它；哪天授权了会自己开始工作。
+if [ "$REPAIR" = 1 ]; then
+  {
+    echo "cm-plugin-workflow 检测到 $drift_n 个文件被改动或误删，已从仓库恢复（v${installed}）："
+    echo "$drift" | sed 's/^/  /'
+  } >"$ANNOUNCE"
+  notify "cm-plugin-workflow 已自愈 $drift_n 个文件" "恢复到 v$installed"
+else
+  {
+    echo "cm-plugin-workflow 已更新到 v${installed}（${local_sha:0:7} → ${remote_sha:0:7}）"
+    [ "$removed" -gt 0 ] && echo "清理了 $removed 个上游已删除的旧文件。"
+    [ -n "$new_commits" ] && { echo "新提交："; echo "$new_commits" | sed 's/^/  /'; }
+  } >"$ANNOUNCE"
+  notify "cm-plugin-workflow 已更新到 v$installed" "$( [ "$removed" -gt 0 ] && echo "清理 $removed 个旧文件；" )重开 Claude Code 生效"
+fi

package/workflows/cm-plugin/templates/dashboard/dashboard.html

@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>cm 工作流看板</title>
+<style>
+  :root{--bg:#f7f8f6;--card:#fff;--ink:#1e2628;--muted:#55646a;--line:#dde3e1;
+    --accent:#0e7a6b;--soft:#e3f0ed;--warn:#9a6a14;--warnbg:#f5eddc;--drop:#b4231f;
+    --num:ui-monospace,"SF Mono",Menlo,monospace}
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);
+    font-family:"PingFang SC","Microsoft YaHei",system-ui,sans-serif;font-size:14px}
+  .wrap{max-width:980px;margin:0 auto;padding:28px 20px}
+  header{display:flex;justify-content:space-between;align-items:baseline;flex-wrap:wrap;gap:8px}
+  h1{font-size:20px;margin:0}
+  #meta{color:var(--muted);font-size:12px}
+  .tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin:18px 0}
+  .tile{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:12px 16px}
+  .tile b{display:block;font-size:22px;font-family:var(--num)}
+  .tile span{color:var(--muted);font-size:12px}
+  .feature{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:16px 18px;margin-bottom:14px}
+  .fhead{display:flex;justify-content:space-between;align-items:center;gap:10px}
+  .fhead h2{font-size:15px;margin:0}
+  .bar{height:8px;background:var(--soft);border-radius:99px;margin:10px 0;overflow:hidden}
+  .bar i{display:block;height:100%;background:var(--accent);border-radius:99px;transition:width .5s}
+  .task{display:flex;gap:8px;padding:3px 0;font-size:13px;align-items:baseline}
+  .task .id{font-family:var(--num);color:var(--muted);min-width:52px}
+  .done{color:var(--muted)}.done .title{text-decoration:line-through}
+  .current{background:var(--warnbg);border-radius:6px;padding:3px 8px;margin:2px -8px}
+  .current .st{color:var(--warn);font-weight:700}
+  .dropped{color:var(--drop);opacity:.7}.dropped .title{text-decoration:line-through}
+  .pct{font-family:var(--num);font-size:12px;color:var(--muted)}
+  table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:8px;font-size:12.5px}
+  th,td{text-align:left;padding:7px 12px;border-bottom:1px solid var(--line)}
+  th{color:var(--muted);font-weight:600}
+  tr:last-child td{border-bottom:none}
+  td{font-family:var(--num)}
+  h3{font-size:14px;margin:24px 0 10px}
+  #lessons li{font-size:13px;color:var(--muted);margin:4px 0}
+  .empty{color:var(--muted);padding:30px;text-align:center}
+  /* 状态机横条 */
+  #pipeline{display:none;background:var(--card);border:1px solid var(--line);border-radius:10px;padding:14px 18px;margin:16px 0}
+  #statusline{font-size:13px;margin-bottom:10px}
+  #statusline b{color:var(--accent)}
+  .nodes{display:flex;gap:6px;align-items:center;flex-wrap:wrap}
+  .node{padding:6px 10px;border-radius:6px;border:1px solid var(--line);font-size:12px;color:var(--muted);background:var(--bg);white-space:nowrap}
+  .node.active{background:var(--accent);border-color:var(--accent);color:#fff;font-weight:700;animation:pulse 1.2s ease-in-out infinite}
+  .node.passed{background:var(--soft);color:var(--accent);border-color:var(--soft)}
+  .arrowc{color:var(--line);font-size:11px}
+  @keyframes pulse{0%,100%{opacity:1}50%{opacity:.55}}
+  #pausebanner{display:none;background:var(--warnbg);border:1px solid var(--warn);color:var(--warn);
+    border-radius:8px;padding:10px 16px;margin:12px 0;font-weight:700;font-size:14px}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>cm 工作流看板 <span id="dot" style="color:var(--accent)">●</span></h1>
+    <div id="meta">加载中…</div>
+  </header>
+  <div id="pausebanner"></div>
+  <div id="pipeline">
+    <div id="statusline"></div>
+    <div class="nodes" id="nodes"></div>
+  </div>
+  <div class="tiles" id="tiles"></div>
+  <div id="features"><div class="empty">正在读取 specs…（确认由 serve.sh 启动且 specs 目录下有编号 feature）</div></div>
+  <h3>📊 METRICS（每任务度量）</h3>
+  <div id="metrics"><div class="empty">尚无 METRICS.md——执行到第一个 N5 后出现</div></div>
+  <h3>📝 LESSONS（经验库）</h3>
+  <ul id="lessons"><li>尚无记录</li></ul>
+</div>
+<script>
+const $=id=>document.getElementById(id);
+async function txt(p){try{const r=await fetch(p+'?t='+Date.now());return r.ok?await r.text():null}catch{return null}}
+
+function parseTasks(md){
+  const out=[];if(!md)return out;
+  for(const m of md.matchAll(/^- \[( |x)\] (T-\d+):?\s*(.+)$/gm)){
+    const line=m[3];
+    out.push({id:m[2],done:m[1]==='x',dropped:/\[DROPPED/.test(line),changed:/\[CHANGED/.test(line),
+      title:line.replace(/`\[[^\]]*\]`?/g,'').replace(/~.*$/,'').trim().slice(0,60)});
+  }
+  return out;
+}
+
+const NODES=[['N1','初始化'],['N2','进Feature'],['N3','执行'],['N4','审查'],['N5','标记'],['N6','QA'],['N7','轮换'],['N8','收尾']];
+async function renderStatus(){
+  const raw=await txt('./.cm-status.json');
+  const pl=$('pipeline'),pb=$('pausebanner');
+  if(!raw){pl.style.display='none';pb.style.display='none';return}
+  let s;try{s=JSON.parse(raw)}catch{return}
+  pl.style.display='block';
+  const curIdx=NODES.findIndex(n=>n[0]===s.node);
+  $('nodes').innerHTML=NODES.map((n,i)=>{
+    const cls=s.state==='done'?'passed':(i===curIdx?'active':(i<curIdx||['N3','N4','N5','N6','N7'].includes(s.node)&&i<2?'passed':''));
+    return `<span class="node ${cls}">${n[0]} ${n[1]}</span>`;
+  }).join('<span class="arrowc">▸</span>');
+  $('statusline').innerHTML=s.state==='done'
+    ?`🎉 全部完成 · ${s.at||''}`
+    :`当前: <b>${s.feature||'—'}</b> / <b>${s.task||'—'}</b> / <b>${s.node}</b> · ${s.detail||''} · ${s.at||''}`;
+  if(s.state==='paused_for_human'){pb.style.display='block';pb.textContent=`⏸ 等待人工介入: ${s.detail||'请查看会话'}`}
+  else pb.style.display='none';
+}
+async function load(){
+  renderStatus();
+  const idx=await txt('./');if(!idx){$('meta').textContent='无法读取 specs 目录';return}
+  const dirs=[...new Set([...idx.matchAll(/href="(\d+\.[^"\/]+)\//g)].map(m=>decodeURIComponent(m[1])))]
+    .sort((a,b)=>parseInt(a)-parseInt(b));
+  let total=0,done=0,fh='';
+  for(const d of dirs){
+    const tasks=parseTasks(await txt(`./${d}/tasks.md`));
+    const act=tasks.filter(t=>!t.dropped);
+    const dn=act.filter(t=>t.done).length;
+    total+=act.length;done+=dn;
+    const cur=act.find(t=>!t.done);
+    const pct=act.length?Math.round(dn/act.length*100):0;
+    fh+=`<div class="feature"><div class="fhead"><h2>📂 ${d}</h2><span class="pct">${dn}/${act.length} · ${pct}%</span></div>
+      <div class="bar"><i style="width:${pct}%"></i></div>`+
+      tasks.map(t=>{
+        const cls=t.dropped?'dropped':t.done?'done':(t===cur?'current':'');
+        const st=t.dropped?'🚫':t.done?'✅':(t===cur?'▶':'⬜');
+        return `<div class="task ${cls}"><span class="st">${st}</span><span class="id">${t.id}</span><span class="title">${t.title}${t.changed?' 🔁':''}</span></div>`;
+      }).join('')+`</div>`;
+  }
+  $('features').innerHTML=fh||'<div class="empty">未发现编号 feature 目录</div>';
+
+  const met=await txt('./METRICS.md');
+  let rows=[],human=0,firstPass=0;
+  if(met){
+    rows=[...met.matchAll(/^\|\s*(T-\d+)\s*\|(.+)$/gm)].map(m=>[m[1],...m[2].split('|').map(s=>s.trim()).slice(0,7)]);
+    for(const r of rows){human+=parseInt(r[7])||0;if((r[4]||'')==='1')firstPass++}
+    if(rows.length){
+      $('metrics').innerHTML='<table><tr><th>任务</th><th>Feature</th><th>开始</th><th>结束</th><th>审查轮</th><th>Codex</th><th>QA</th><th>人工介入</th></tr>'+
+        rows.map(r=>'<tr>'+r.map(c=>`<td>${c}</td>`).join('')+'</tr>').join('')+'</table>';
+    }
+  }
+  const lessons=await txt('./LESSONS.md');
+  const ls=lessons?[...lessons.matchAll(/^## (.+)$/gm)].map(m=>m[1]):[];
+  $('lessons').innerHTML=ls.length?ls.slice(-8).reverse().map(l=>`<li>${l}</li>`).join(''):'<li>尚无记录</li>';
+
+  $('tiles').innerHTML=`
+    <div class="tile"><b>${done}/${total}</b><span>任务完成</span></div>
+    <div class="tile"><b>${rows.length?(human/rows.length).toFixed(1):'—'}</b><span>人工介入/任务</span></div>
+    <div class="tile"><b>${rows.length?Math.round(firstPass/rows.length*100)+'%':'—'}</b><span>一次通过率</span></div>
+    <div class="tile"><b>${ls.length}</b><span>LESSONS 条目</span></div>`;
+  $('meta').textContent=`数据源: specs 落盘文件 · 只读 · ${new Date().toLocaleTimeString()} 刷新`;
+  $('dot').style.color='var(--accent)';
+}
+load();setInterval(load,2000);
+</script>
+</body>
+</html>

package/workflows/cm-plugin/templates/dashboard/serve.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# cm 工作流可视化看板 · 纯只读,零侵入(只消费 specs 落盘文件)
+# 用法: ./serve.sh /path/to/specs [端口,默认 8788]
+set -euo pipefail
+SPECS="${1:?用法: ./serve.sh /path/to/specs [端口]}"
+PORT="${2:-8788}"
+[ -d "$SPECS" ] || { echo "specs 目录不存在: $SPECS"; exit 1; }
+cp "$(cd "$(dirname "$0")" && pwd)/dashboard.html" "$SPECS/.cm-dashboard.html"
+echo "✓ 看板已启动: http://localhost:$PORT/.cm-dashboard.html  (Ctrl+C 停止)"
+cd "$SPECS" && exec python3 -m http.server "$PORT" --bind 127.0.0.1

package/workflows/cm-plugin/templates/e2e/extension-harness.ts

@@ -0,0 +1,110 @@
+// cm-plugin E2E harness —— MV3 扩展 Playwright 测试的久经考验底座。
+// 这套代码封装的每一条都是 dogfood 实测踩出来的坑,新插件直接拷进 tests/e2e/ 用,别重踩。
+// 依赖: @playwright/test。适配 WXT 构建产物(.output/{browser}-mv3)。
+//
+// 为什么要有它(五个坑,散文记不住,代码才靠得住):
+//   1. 系统 Chrome(2026 版)默认屏蔽 --load-extension → 扩展静默不加载,SW 永不注册。只有 Chrome for Testing 能加载。
+//   2. headless:false 依赖真实显示,在无头 shell / CI 里退化 flaky → 用 --headless=new(新无头支持 MV3 扩展)。
+//   3. SW 从 onInstalled 注册后会很快 idle 停机 → 事后 serviceWorkers() 为空且 waitForEvent 等不到新事件,竞态。
+//   4. 复用旧 SW 引用做 evaluate → "Worker was closed"。要用前唤醒取活引用。
+//   5. CfT 路径随架构/OS 变(mac-arm64/mac-x64/linux),且多缓存版本要选最新。
+
+import { chromium, type BrowserContext, type Worker } from '@playwright/test';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+/** 跨架构/OS 发现 playwright 缓存的 Chrome for Testing 二进制,按版本降序选最新。找不到返回 undefined(调用方回退 channel)。 */
+export function resolveChromeForTesting(): string | undefined {
+  const cache =
+    process.env.PLAYWRIGHT_BROWSERS_PATH ||
+    (process.platform === 'darwin'
+      ? path.join(os.homedir(), 'Library/Caches/ms-playwright')
+      : process.platform === 'win32'
+        ? path.join(os.homedir(), 'AppData/Local/ms-playwright')
+        : path.join(os.homedir(), '.cache/ms-playwright'));
+  if (!fs.existsSync(cache)) return undefined;
+  const layouts = [
+    'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    'chrome-linux/chrome',
+    'chrome-win/chrome.exe',
+  ];
+  const dirs = fs
+    .readdirSync(cache)
+    .filter((d) => d.startsWith('chromium-'))
+    .sort((a, b) => Number(b.split('-')[1] || 0) - Number(a.split('-')[1] || 0)); // 版本降序
+  for (const dir of dirs) {
+    for (const layout of layouts) {
+      const p = path.join(cache, dir, layout);
+      if (fs.existsSync(p)) return p;
+    }
+  }
+  return undefined;
+}
+
+/** 用 CfT + --headless=new 加载解包扩展。extPath 指向构建产物目录(含 manifest.json)。 */
+export async function launchExtension(extPath: string): Promise<BrowserContext> {
+  if (!fs.existsSync(path.join(extPath, 'manifest.json'))) {
+    throw new Error(`扩展产物缺失: ${extPath}/manifest.json —— 先跑 build`);
+  }
+  const executablePath = resolveChromeForTesting();
+  return chromium.launchPersistentContext('', {
+    ...(executablePath ? { executablePath } : { channel: 'chromium' }),
+    headless: true,
+    args: [
+      '--headless=new', // 新无头模式支持 MV3 扩展(旧 headless 不支持,headless:false 无头环境退化)
+      `--disable-extensions-except=${extPath}`,
+      `--load-extension=${extPath}`,
+    ],
+  });
+}
+
+/** 取 SW 引用:已存在 / 新注册事件 / 轮询已注册(含停机的) 三路取先到,彻底避开注册-停机竞态。 */
+export function acquireServiceWorker(ctx: BrowserContext, timeoutMs = 12_000): Promise<Worker> {
+  const now = ctx.serviceWorkers();
+  if (now[0]) return Promise.resolve(now[0]);
+  const byEvent = ctx.waitForEvent('serviceworker');
+  const byPoll = (async () => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const [sw] = ctx.serviceWorkers();
+      if (sw) return sw;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    throw new Error('service worker 未在超时内注册');
+  })();
+  return Promise.race([byEvent, byPoll]);
+}
+
+/** 从 SW url 取扩展 id(32 位小写)。 */
+export function extensionId(sw: Worker): string {
+  return new URL(sw.url()).host;
+}
+
+/**
+ * 唤醒并取"活的"SW,再做 sw.evaluate。SW 会 idle 停机,复用旧引用 evaluate 会 "Worker was closed"——
+ * 本函数先开一个扩展页触发 SW 启动,再取活引用。凡 sw.evaluate(读 storage 等)前都用它。
+ */
+export async function wakeServiceWorker(ctx: BrowserContext, extId: string): Promise<Worker> {
+  const ping = await ctx.newPage();
+  await ping.goto(`chrome-extension://${extId}/manifest.json`).catch(() => {});
+  const sw = await acquireServiceWorker(ctx);
+  await ping.close();
+  return sw;
+}
+
+/**
+ * afterAll 里关闭 context。dogfood 实测:带扩展的 persistent context `ctx.close()` 会挂 30s 超时
+ * (扩展 SW/浏览器进程收尾卡住),afterAll 超时且进程残留累积 → 后续测试环境退化 flaky。
+ * 本函数先关所有页,再 close() 但用超时兜底(race)——超时就放手,残留进程由 playwright teardown/OS 收。
+ * 用法: `test.afterAll(() => closeExtension(context))`。
+ */
+export async function closeExtension(ctx: BrowserContext | undefined, timeoutMs = 5000): Promise<void> {
+  if (!ctx) return;
+  for (const p of ctx.pages()) await p.close().catch(() => {});
+  await Promise.race([
+    ctx.close().catch(() => {}),
+    new Promise<void>((r) => setTimeout(r, timeoutMs)),
+  ]);
+}

package/workflows/cm-plugin/templates/e2e/smoke.spec.example.ts

@@ -0,0 +1,51 @@
+// cm-plugin E2E 冒烟模板 —— bootstrap T-005 拷进 tests/e2e/smoke.spec.ts,把 {占位} 换成本项目实际值。
+// 用 extension-harness.ts 封装的健壮底座,不要自己写 launchPersistentContext / SW 获取(会踩全套坑)。
+import { test, expect, type BrowserContext, type Worker } from '@playwright/test';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  launchExtension,
+  acquireServiceWorker,
+  extensionId,
+  closeExtension,
+} from './extension-harness';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// {构建产物路径} —— WXT 默认 .output/chrome-mv3;按脚手架实际改
+const EXT_PATH = path.resolve(here, '../../.output/chrome-mv3');
+
+let context: BrowserContext;
+let swReady: Promise<Worker>;
+
+test.beforeAll(async () => {
+  context = await launchExtension(EXT_PATH);
+  swReady = acquireServiceWorker(context); // 立即捕获,避开注册-停机竞态
+});
+
+test.afterAll(async () => {
+  await closeExtension(context); // 带扩展的 context.close() 会挂,用 harness 的超时兜底版
+});
+
+test('service worker 注册且 manifest 名称正确', async () => {
+  const sw = await swReady;
+  expect(sw.url()).toContain('background.js'); // WXT 产物;其他脚手架按实际 SW 文件名
+  expect(extensionId(sw)).toMatch(/^[a-z]{32}$/);
+  // 标题声称"名称正确"须真断言——读被加载的产物 manifest(N5 运行观察闸:断言要对得上标题)
+  const manifest = JSON.parse(fs.readFileSync(path.join(EXT_PATH, 'manifest.json'), 'utf-8'));
+  expect(manifest.name).toBe('{扩展名}'); // ← 换成本项目 manifest.name
+});
+
+test('popup 能打开', async () => {
+  const extId = extensionId(await swReady);
+  const page = await context.newPage();
+  await page.goto(`chrome-extension://${extId}/popup.html`); // 无 popup 表面则删本用例
+  await expect(page.locator('body')).not.toBeEmpty(); // ← 换成本项目 popup 的稳定锚点(如品牌字标)
+  await page.close();
+});
+
+// ── 真实引擎集成(可选,强烈建议)：起本地 http server 放一个假的目标场景,验证 content script 真处理 ──
+// content script 的行为纯单测证不了,只有真实页面能证。参考:
+//   import http from 'node:http';
+//   起 server 返回带目标元素的 fixture → page.goto → expect.poll 页面状态变化。
+//   读 storage 用 wakeServiceWorker(ctx, extId) 取活 SW 再 sw.evaluate(避免 "Worker was closed")。

package/workflows/cm-plugin/templates/hooks/pre-commit-cm-task-check

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# cm 工作流 · 任务标记双保险（灰度阶段启用，可选）
+#
+# 用途：防止 N5 漏标记——代码提交时校验 tasks.md 的勾选状态有同步更新。
+# 安装（在代码仓库内）：
+#   export CM_SPECS_DIR=/path/to/specs        # specs 文件夹路径（含 N.feature 目录）
+#   cp templates/hooks/pre-commit-cm-task-check .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# 逻辑：本次提交包含源码变更、且 CM_SPECS_DIR 已设置时，检查 specs 下
+# 是否存在"最近修改时间晚于上次提交"的 tasks.md——没有则给出警告。
+# 默认仅警告不阻断；置 CM_TASK_CHECK_STRICT=1 时阻断提交。
+set -uo pipefail
+
+[ -z "${CM_SPECS_DIR:-}" ] && exit 0            # 未启用则直接放行
+[ -d "$CM_SPECS_DIR" ] || exit 0
+
+# 本次提交是否包含源码变更（排除纯文档）
+changed=$(git diff --cached --name-only | grep -vE '\.(md|txt)$' || true)
+[ -z "$changed" ] && exit 0
+
+last_commit_ts=$(git log -1 --format=%ct 2>/dev/null || echo 0)
+fresh_tasks=$(find "$CM_SPECS_DIR" -name tasks.md -newermt "@$last_commit_ts" 2>/dev/null || true)
+
+if [ -z "$fresh_tasks" ]; then
+  echo "⚠ [cm] 本次提交含源码变更，但 $CM_SPECS_DIR 下没有新更新的 tasks.md。" >&2
+  echo "  若刚完成某个任务，请确认 N5 已将其标记为 [x]（漏标会导致断点恢复时重复执行）。" >&2
+  if [ "${CM_TASK_CHECK_STRICT:-0}" = "1" ]; then
+    echo "  严格模式已开启：提交被阻断。确认无碍可用 git commit --no-verify 跳过。" >&2
+    exit 1
+  fi
+fi
+exit 0