agentic-flow-kit 0.3.0 → 0.4.0

package/README.md

@@ -62,3 +62,5 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 - [x] v0.2.0 已发布：npm view agentic-flow-kit（npx agentic-flow-kit init 即用；默认镜像源用户需等 npmmirror 同步或 --registry npmjs）
 - [x] v0.2.1：Shipyard 回流第二笔（模板引用去死链 + owned 台账记账策略：add-gate 接线刷新 + sync 盘面自愈）+ 全项目审查修复（量化台账 fail-loud / 生成器锚点与 ENOENT 守卫 / sync 跳过件持续报告 / P4 清账 / metrics glob 词表收口）——已发布
 - [x] v0.3.0：init 交互升级（序号菜单 + ANSI 色彩降级 + ts/js 技术栈别名归一 node）+ AGENTS.md 骨架探测补齐（已存在无标记时文末追加，原内容保留）+ wiki 模板预置 7 主题内容目录 + 关单 verify 固定编排（npm test + check-loop 一键过门，非绿不关单）+ workflow 看板纸墨视觉改版
+- [x] v0.3.1：doctor 修复——Windows 无 sh 环境（PowerShell）把 sh ENOENT 误报成 check-loop hard-block（探测分流：明示「未跑勿当作通过」，git 钩子门禁不受影响）
+- [x] v0.4.0：看板端口自动上探（基端口起探首个可用端口，多项目并行不冲突；`/api/board` 自报 pid/startedAt，root 比对识别本项目、他人进程不动手不 kill）+ 跨平台入口 `ensure-board.mjs` 取代 Windows 专属 `ensure-board.ps1`（Windows/Linux/macOS 零依赖单入口）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {

package/src/doctor.mjs

@@ -127,13 +127,20 @@ export function doctor(args, pkgRoot) {
     else add('WARN', `delegations 台账结构漂移——${String(agg.stderr || agg.stdout || '').split('\n')[0]}`);
   }
 
-  // 7. check-loop
-  const cl = spawnSync('sh', ['.agents/scripts/check-loop.sh'], { cwd: target, encoding: 'utf8' });
-  if (cl.status === 0) {
-    const warnTxt = String(cl.stderr || '').trim();
-    add('PASS', `check-loop 干净${warnTxt ? `（${warnTxt.split('\n').filter((l) => l.includes('WARN')).length} 条 advisory 警告）` : ''}`);
+  // 7. check-loop——先探 sh 可用性（对齐 run-tests.mjs 先例）：Windows PowerShell 常无 sh，
+  //    ENOENT 曾被吞进 hard-block 分支报成空原因假警报（incident 2026-09-24-doctor-sh-enoent）。
+  //    git 钩子门禁不受此影响——git 以自带 sh 执行钩子，与用户 PATH 无关。
+  const shProbe = spawnSync('sh', ['-c', 'true'], { encoding: 'utf8' });
+  if (shProbe.status !== 0) {
+    add('WARN', '环境无 sh——check-loop 未跑，勿当作通过；装 Git Bash / WSL 后重跑 doctor（git 钩子门禁不受影响，git 以自带 sh 执行）');
   } else {
-    add('FAIL', `check-loop 有 hard-block：\n${String(cl.stderr || '').split('\n').slice(0, 8).join('\n')}`);
+    const cl = spawnSync('sh', ['.agents/scripts/check-loop.sh'], { cwd: target, encoding: 'utf8' });
+    if (cl.status === 0) {
+      const warnTxt = String(cl.stderr || '').trim();
+      add('PASS', `check-loop 干净${warnTxt ? `（${warnTxt.split('\n').filter((l) => l.includes('WARN')).length} 条 advisory 警告）` : ''}`);
+    } else {
+      add('FAIL', `check-loop 有 hard-block：\n${String(cl.stderr || '').split('\n').slice(0, 8).join('\n')}`);
+    }
   }
 
   // 8. 看板端口（信息级）
@@ -142,8 +149,8 @@ export function doctor(args, pkgRoot) {
   portInUse(port).then((inUse) => {
     print(results);
     console.log(inUse
-      ? `ℹ️  看板端口 ${port} 已有监听（ensure-board 探活复用；他人进程不 kill，见 workflow/README.md）`
-      : `ℹ️  看板端口 ${port} 空闲（看板默认不拉起；需要时手动 .agents/scripts/ensure-board.ps1 或 node .agents/scripts/workflow-board-server.mjs）`);
+      ? `ℹ️  看板端口 ${port} 已有监听（ensure-board 探活：本项目看板复用/旧代码重启，他人进程不 kill 自动上探，见 workflow/README.md）`
+      : `ℹ️  看板端口 ${port} 空闲（看板默认不拉起；需要时手动 .agents/scripts/ensure-board.mjs（跨平台）或 node .agents/scripts/workflow-board-server.mjs）`);
     process.exit(results.some((r) => r.level === 'FAIL') ? 1 : 0);
   });
 }

package/templates/AGENTS.md

@@ -31,7 +31,7 @@
 ### 检索、看板与量化
 
 - 跨语料检索：`node .agents/scripts/kb-search.mjs "<词>"`（workflow 节级定位 + wiki 全文）；活跃流程读 `workflow/INDEX.md`（状态变更后 `node .agents/scripts/gen-workflow-index.mjs` 重生成）。
-- workflow 看板（可选，默认不拉起）：需要时手动跑 `.agents/scripts/ensure-board.ps1`，然后访问 http://127.0.0.1:{{BOARD_PORT}}（只读预警层，非门禁）。
+- workflow 看板（可选，默认不拉起）：需要时手动跑 `node .agents/scripts/ensure-board.mjs`（跨平台，Windows/Linux/macOS 通用），端口从基端口 {{BOARD_PORT}} 起自动上探首个可用（多项目并行不冲突），链接以脚本输出为准（只读预警层，非门禁）。
 - 委派 / 自做结果留痕 `workflow/delegations.md`（聚合 `node .agents/scripts/agg-delegations.cjs`）；命令 / 技能卡壳记 `workflow/papercuts.md`，不当场顺手改。
 
 ### 验证与关单

package/templates/_agents/cache/kb-index.json

@@ -1 +1 @@
-{"fp":"b779761db958797b","files":{"/tmp/kb-search-test-dSeASn::workflow/intents/2026-09-21-bbb.md":{"st":[1790246007069.2913,270],"kind":"wf","meta":{"状态":"approved","级别":"L1","日期":"2026-09-21","模块":"pipeline"},"title":"乙需求","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","日期: 2026-09-21"],[5,"(frontmatter)","模块: pipeline"],[6,"(frontmatter)","---"],[7,"(标题)","# INTENT — 乙需求"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B乙"],[11,"目标",""]]},"/tmp/kb-search-test-dSeASn::workflow/plans/2026-09-20-ccc.md":{"st":[1790246007069.2913,200],"kind":"wf","meta":{"状态":"approved","级别":"L1","模块":"purchase"},"title":"丙计划","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","模块: purchase"],[5,"(frontmatter)","---"],[6,"(标题)","# PLAN — 丙计划"],[8,"目标","## 目标"],[9,"目标","- 只讲编码模板，不提另一个词"],[10,"目标",""]]},"/tmp/kb-search-test-dSeASn::workflow/incidents/2026-09-01-aaa.md":{"st":[1790246007069.2913,270],"kind":"wf","meta":{"状态":"closed","级别":"L2","发现":"2026-09-01","模块":"material"},"title":"甲事故","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: closed"],[3,"(frontmatter)","级别: L2"],[4,"(frontmatter)","发现: 2026-09-01"],[5,"(frontmatter)","模块: material"],[6,"(frontmatter)","---"],[7,"(标题)","# INCIDENT — 甲事故"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B甲"],[11,"目标",""]]},"/tmp/kb-search-test-dSeASn::wiki/测试主题/说明.md":{"st":[1790246007069.2913,47],"kind":"wiki","lines":[[1,"# 说明"],[2,""],[3,"编码模板的领域知识条目。"],[4,""]]}}}
+{"fp":"b779761db958797b","files":{"/tmp/kb-search-test-XdDPi6::workflow/intents/2026-09-21-bbb.md":{"st":[1790253784155.5151,270],"kind":"wf","meta":{"状态":"approved","级别":"L1","日期":"2026-09-21","模块":"pipeline"},"title":"乙需求","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","日期: 2026-09-21"],[5,"(frontmatter)","模块: pipeline"],[6,"(frontmatter)","---"],[7,"(标题)","# INTENT — 乙需求"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B乙"],[11,"目标",""]]},"/tmp/kb-search-test-XdDPi6::workflow/plans/2026-09-20-ccc.md":{"st":[1790253784155.5151,200],"kind":"wf","meta":{"状态":"approved","级别":"L1","模块":"purchase"},"title":"丙计划","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","模块: purchase"],[5,"(frontmatter)","---"],[6,"(标题)","# PLAN — 丙计划"],[8,"目标","## 目标"],[9,"目标","- 只讲编码模板，不提另一个词"],[10,"目标",""]]},"/tmp/kb-search-test-XdDPi6::workflow/incidents/2026-09-01-aaa.md":{"st":[1790253784155.5151,270],"kind":"wf","meta":{"状态":"closed","级别":"L2","发现":"2026-09-01","模块":"material"},"title":"甲事故","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: closed"],[3,"(frontmatter)","级别: L2"],[4,"(frontmatter)","发现: 2026-09-01"],[5,"(frontmatter)","模块: material"],[6,"(frontmatter)","---"],[7,"(标题)","# INCIDENT — 甲事故"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B甲"],[11,"目标",""]]},"/tmp/kb-search-test-XdDPi6::wiki/测试主题/说明.md":{"st":[1790253784155.5151,47],"kind":"wiki","lines":[[1,"# 说明"],[2,""],[3,"编码模板的领域知识条目。"],[4,""]]}}}

package/templates/_agents/commands/maintain.md

@@ -24,7 +24,7 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），链接 http://127.0.0.1:{{BOARD_PORT}} ；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 {{BOARD_PORT}}）；不开看板不影响任务流程。
 
 ### 0. 紧急止血(仍在事故中时)
 

package/templates/_agents/commands/plan.md

@@ -16,7 +16,7 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），链接 http://127.0.0.1:{{BOARD_PORT}} ；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 {{BOARD_PORT}}）；不开看板不影响任务流程。
 
 1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
 2. 否则起草新 intent:

package/templates/_agents/scripts/ensure-board.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// ensure-board.mjs — workflow 看板按需手动拉起（默认不自动开启；只起不关：OS 重启即天然回收，无需 stop/status）
+// 跨平台单入口（零依赖，Windows/Linux/macOS 同一脚本，取代旧 ensure-board.ps1）：
+//   基端口（--port 显式 > kit.json boardPort > 8933）向上探测首个可用端口（窗口 10）——
+//   端口空闲 → 全新启动；探活 /api/board 比对 root：本项目看板 → 复用（代码文件晚于服务端 startedAt = 旧代码自动 kill 重启）；
+//   他人进程（其他项目看板 / 非看板服务）不动手不 kill，跳过试下一端口；全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
+// 身份与陈旧判定全部来自 /api/board 自报（pid/startedAt）——不碰 OS 专属的端口属主 / 进程启动时间 API。
+// 用法：node .agents/scripts/ensure-board.mjs [--port 8933] [--no-open]
+import net from 'node:net';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, '../..'); // 与 server 的 ROOT 同口径
+const SERVER = path.join(SCRIPT_DIR, 'workflow-board-server.mjs');
+const CODE_FILES = [path.join(ROOT, '.agents', 'board', 'index.html'), SERVER]; // 前端 + 服务端：任一更新都算「旧代码」
+const WINDOW = 10;
+
+// ---- 参数与基端口 ----
+const argv = process.argv;
+const flagIdx = argv.indexOf('--port');
+const eqArg = argv.find((a) => a.startsWith('--port='));
+const portArg = flagIdx > -1 ? argv[flagIdx + 1] : eqArg && eqArg.slice('--port='.length);
+const noOpen = argv.includes('--no-open');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+let BASE_PORT;
+if (portArg && Number(portArg)) {
+  BASE_PORT = Number(portArg);
+} else {
+  // 基端口取 kit 台账（init 询问值，与命令文档 {{BOARD_PORT}} 同源）；无台账或解析失败回落 8933
+  try { BASE_PORT = Number(JSON.parse(fs.readFileSync(path.join(ROOT, '.agents', 'kit.json'), 'utf8')).options.boardPort) || 8933; }
+  catch { BASE_PORT = 8933; }
+}
+
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+// ---- 探活：端口占用用 net.connect；看板身份/属主用 /api/board 自报（isBoard=含 cards 字段；ours=root 指向本项目）----
+// 不用全局 fetch：undici 连接池 keep-alive 句柄会拖住/污染退出（Windows 上强退触发 libuv 断言）
+function portBusy(port) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: '127.0.0.1', port });
+    s.setTimeout(800);
+    s.on('connect', () => { s.destroy(); resolve(true); });
+    s.on('timeout', () => { s.destroy(); resolve(true); }); // 超时从保守视作占用；localhost 上近乎不存在
+    s.on('error', () => resolve(false));
+  });
+}
+
+// /api/board 用 http.get 正规解包（server 响应为 chunked，手工拼包解析不了）；Connection: close + 默认 agent 不进连接池，无残留句柄
+function httpProbe(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/board', headers: { Connection: 'close' }, timeout: 2000 }, (res) => {
+      let buf = '';
+      res.on('data', (d) => { buf += d; });
+      res.on('end', () => resolve({ status: res.statusCode, json: () => { try { return JSON.parse(buf); } catch { return null; } } }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ status: 0 }); });
+    req.on('error', () => resolve({ status: 0 }));
+  });
+}
+
+async function probeBoard(port) {
+  const none = { isBoard: false };
+  const r = await httpProbe(port);
+  if (r.status !== 200) return none;
+  const j = r.json();
+  if (!j || typeof j !== 'object' || !('cards' in j)) return none;
+  return { isBoard: true, ours: !!(j.root && samePath(path.resolve(String(j.root)), ROOT)), pid: j.pid, startedAt: j.startedAt };
+}
+
+// 陈旧判定：代码文件最新 mtime 晚于服务端启动时刻（2s 容差）= 旧代码；无 startedAt（旧版服务端）返回 null 无法判定
+function staleCode(startedAt) {
+  if (!startedAt) return null;
+  const newest = Math.max(...CODE_FILES.filter((f) => fs.existsSync(f)).map((f) => fs.statSync(f).mtimeMs));
+  return newest > startedAt + 2000;
+}
+
+// ---- 动作：kill / 拉起（detached + windowsHide，父进程退出后存活）/ 等监听 / 弹浏览器 ----
+function startServer(port) {
+  const c = spawn(process.execPath, [SERVER, '--port', String(port)], { detached: true, stdio: 'ignore', windowsHide: true });
+  c.unref();
+}
+
+async function waitListen(port) {
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    if (await portBusy(port)) return true;
+    await sleep(300);
+  }
+  return false;
+}
+
+// intentional-simple: 弹浏览器 best-effort 三平台分流（win: cmd start / mac: open / linux: xdg-open），失败不打扰——链接已在输出里
+function openBrowser(url) {
+  try {
+    if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+  } catch { }
+}
+
+// ---- 主流程（返回退出码，自然排水退出——不用 process.exit：强退在 Windows 上会触发 libuv 断言）----
+async function main() {
+  const skipped = [];
+  let action = null;
+  let port = 0;
+  let board = null;
+
+  for (let p = BASE_PORT; p < BASE_PORT + WINDOW; p++) {
+    if (!(await portBusy(p))) { port = p; action = 'fresh start'; break; }
+    const b = await probeBoard(p);
+    if (b.ours) {
+      port = p;
+      board = b;
+      const stale = staleCode(b.startedAt);
+      if (stale === true) {
+        try { process.kill(b.pid); } catch { } // 进程可能已自行退出，忽略
+        await sleep(500);
+        action = 'restarted (stale code detected)';
+      } else if (stale === null) {
+        action = 'legacy';
+      } else {
+        action = 'up-to-date';
+      }
+      break;
+    }
+    skipped.push(`端口 ${p}（pid ${b.pid ?? '未知'}）`);
+  }
+  const url = `http://127.0.0.1:${port}`;
+
+  if (!action) {
+    console.log(`board: 端口 ${BASE_PORT}..${BASE_PORT + WINDOW - 1} 均被他人进程占用（未动手不 kill）：${skipped.join('；')}；可 --port 指定其他基端口`);
+    return 1;
+  }
+  if (action === 'legacy') {
+    console.log(`board: ${url} 是本项目旧版看板（无 startedAt，无法判定代码新旧），未自动重启；如需更新请手动重启`);
+    return 0;
+  }
+  if (action === 'up-to-date') {
+    console.log(`board: already up-to-date at ${url} (pid ${board.pid ?? '未知'})`);
+    return 0;
+  }
+  if (skipped.length) console.log(`board: 基端口段他人进程已跳过：${skipped.join('；')}`);
+
+  startServer(port);
+  if (!(await waitListen(port))) {
+    console.log(`board: FAILED to start on ${port}`);
+    return 1;
+  }
+  console.log(`board: ${action} -> ${url}`);
+  if (!noOpen && action === 'fresh start') openBrowser(url);
+  return 0;
+}
+
+process.exitCode = await main();

package/templates/_agents/scripts/workflow-board-server.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // workflow 实时看板服务：本地只读 http + SSE 文件监听，可视化 AI 执行流程（intents/incidents/plans/specs）。
-// 用法：node .agents/scripts/workflow-board-server.mjs [--port 8933]
+// 用法：node .agents/scripts/workflow-board-server.mjs [--port 8933]；多项目并行请用 ensure-board.mjs 拉起（自动上探可用端口）
 // 零依赖（node:http/node:fs/node:path/node:url/node:child_process）；只读 workflow/ 与 git，仅绑 127.0.0.1。
 // API：GET /（看板页） /marked.min.js（vendor） /api/board /api/doc?file=<相对路径> /api/history?file=<相对路径> /api/events（SSE）
 // 实时边界：文档内容与状态随落盘实时（fs.watch→SSE 推送）；git 历史仅含已提交记录（git 语义）。
@@ -17,6 +17,7 @@ const DOC_TYPES = ['intents', 'incidents', 'plans', 'specs'];
 
 const portArg = process.argv.indexOf('--port');
 const PORT = portArg > 0 ? Number(process.argv[portArg + 1]) || 8933 : 8933;
+const STARTED_AT = Date.now(); // 随 /api/board 自报（startedAt），供 ensure-board.mjs 判定旧代码重启，不碰进程启动时间 API
 
 // ---- front matter + 标题解析（对照 _TEMPLATE.md 受限子集：每行 `键: 值`）----
 function parseDoc(text) {
@@ -155,7 +156,7 @@ async function scanBoard() {
   }
   detectAlerts(cards);
   cards.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type));
-  return { root: ROOT, counts, cards };
+  return { root: ROOT, pid: process.pid, startedAt: STARTED_AT, counts, cards };
 }
 
 // ---- 路径白名单：resolve 后必须仍在 workflow/ 内 ----
@@ -240,6 +241,12 @@ const server = http.createServer(async (req, res) => {
   }
 });
 
+// 绑定失败明确退出（EADDRINUSE 常见于直跑撞端口；ensure-board 会先探活选端口，这里兜底可读报错）
+server.on('error', (e) => {
+  console.error(`workflow 看板启动失败（端口 ${PORT}${e.code === 'EADDRINUSE' ? ' 已被占用' : ''}）：${e.code || e.message}`);
+  process.exit(1);
+});
+
 server.listen(PORT, '127.0.0.1', () => {
   console.log(`workflow 看板: http://127.0.0.1:${PORT}  （Ctrl+C 停止；只读 workflow/，不写任何文件）`);
 });

package/templates/workflow/README.md

@@ -24,7 +24,7 @@
 ## 使用方式
 
 - **发起新任务**：执行 `.agents/commands/new-task.md` 定义的流程（6 阶段总入口）
-- **看板（可选，默认不拉起）**：需要时手动跑 .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动弹浏览器），实时只读 http://127.0.0.1:{{BOARD_PORT}}；**预警层，非门禁；告警口径对齐 check-loop 硬断档**。端口被占用时先探活 `/api/board`——响应不含 `cards` 即判为他人进程，打印 pid / 进程名并退出，不 kill
+- **看板（可选，默认不拉起）**：需要时手动跑 node .agents/scripts/ensure-board.mjs（跨平台单入口；幂等：探活 / 旧代码自动重启 / 全新启动弹浏览器），端口从基端口 {{BOARD_PORT}} 起自动上探首个可用，链接以脚本输出为准；**预警层，非门禁；告警口径对齐 check-loop 硬断档**。端口被占时探活 `/api/board` 并比对 `root`——本项目看板才复用 / 旧代码重启；他人进程（含其他项目看板）不动手不 kill，自动跳过试下一端口
 - **检索**：活跃流程读 `INDEX.md`（生成物，`node .agents/scripts/gen-workflow-index.mjs` 重生成、`--check` 校验漂移）；跨语料检索 `node .agents/scripts/kb-search.mjs "<词>"`（workflow 按节级定位 + wiki 全文，`--type/--module/--status/-n` 过滤；`--status all` 显式全量）
 - **验证**：`.agents/commands/test.md`（静态门 + 实测；项目自有验证脚本/门禁如有，见 `.agents/hooks/local-pre-commit` 与根 `AGENTS.md`「项目适配区」）
 - **评审**：`.agents/commands/review.md`（按 P0 / P1 / P2 分级：机器兜底 + AI 自查出清单，用户决策定性与合入）

package/templates/_agents/scripts/ensure-board.ps1

@@ -1,48 +0,0 @@
-# ensure-board.ps1 — workflow 看板按需手动拉起（默认不自动开启；只起不关：Windows 重启即天然回收，无需 stop/status）
-# 行为：探活（端口占用者须响应 /api/board 才认定为看板，否则不动手、报占用者并 exit 1）
-#       → 前端或服务端任一代码早于进程 = 旧代码自动 kill 重启 → 全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
-# 用法：powershell -NoProfile -File .agents/scripts/ensure-board.ps1 [-Port 8933] [-NoOpen]
-param(
-  [int]$Port = 8933,
-  [switch]$NoOpen
-)
-$ErrorActionPreference = 'Stop'
-$agentsDir = Split-Path -Parent $PSScriptRoot
-$server = Join-Path $PSScriptRoot 'workflow-board-server.mjs'
-$boardHtml = Join-Path $agentsDir 'board\index.html'
-$codeFiles = @($boardHtml, $server)   # 前端 + 服务端：任一更新都算「旧代码」
-$url = "http://127.0.0.1:$Port"
-
-$proc = $null
-$conn = Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
-if ($conn) { $proc = Get-Process -Id $conn.OwningProcess -ErrorAction SilentlyContinue }
-
-$action = 'fresh start'
-if ($proc) {
-  # 身份校验：只有能返回带 cards 字段 JSON 的才是看板，否则绝不 kill（可能误杀用户自己的服务）
-  $isBoard = $false
-  try {
-    $body = (Invoke-WebRequest -Uri "$url/api/board" -TimeoutSec 2).Content
-    $isBoard = $null -ne ($body | ConvertFrom-Json).PSObject.Properties['cards']
-  } catch { $isBoard = $false }
-  if (-not $isBoard) {
-    Write-Output "board: 端口 $Port 被非看板进程占用（pid $($proc.Id) $($proc.ProcessName)），未做任何改动；请确认该进程后自行处理"
-    exit 1
-  }
-  $newest = ($codeFiles | ForEach-Object { (Get-Item $_).LastWriteTime } | Sort-Object -Descending)[0]
-  $stale = $newest -gt $proc.StartTime.AddSeconds(2)
-  if (-not $stale) {
-    Write-Output "board: already up-to-date at $url (pid $($proc.Id))"
-    exit 0
-  }
-  Stop-Process -Id $proc.Id -Force
-  Start-Sleep -Milliseconds 500
-  $action = 'restarted (stale code detected)'
-}
-
-Start-Process -FilePath 'node' -ArgumentList "`"$server`" --port $Port" -WindowStyle Hidden
-$deadline = (Get-Date).AddSeconds(8)
-do { Start-Sleep -Milliseconds 300; $up = [bool](Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue) } while (-not $up -and (Get-Date) -lt $deadline)
-if (-not $up) { Write-Output "board: FAILED to start on $Port"; exit 1 }
-Write-Output "board: $action -> $url"
-if (-not $NoOpen -and $action -eq 'fresh start') { Start-Process $url }