agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/skills/verify-ui/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: verify-ui
+description: UI 改动实测（只读验证、不留脏数据）。第一选择 chrome-devtools MCP：take_snapshot 探形 + 单步驱动 + 截图取证；harness .mjs 脚本只作回归/无人值守的降级路径，降级须在实测报告记一行原因。
+---
+
+# verify-ui — UI 实测引导
+
+## 分工
+- 本文件只载方法（环境 / 选点 / 证据 / 清理）；执行契约（环境安全 / 禁自修 / HALT 礼仪 / 交付物形态）单源在 `.agents/roles/ui-verifier.md`。
+- 委派子代理以契约为准；主智能体自测按本文件执行。
+
+## 触发条件
+- 用户要求：`实测` / `UI 验证` / `浏览器验证`。
+
+## 工具路径优先级
+- 交互式 UI 实测默认走 chrome-devtools MCP：浏览器实例全程复用；先 `take_snapshot` 探形，再单步驱动、局部重试。
+- harness 脚本只用于：回归 / 防复发资产；批量断言汇总 + 退出码门禁（`makeRecorder`）；无人值守 / 流水线批次。
+- 降级阶梯（2026-11-04 立，2026-11-11 修订）：chrome-devtools MCP 是第一选择，harness 探针只是降级路径。**宿主无 chrome-devtools 工具（MCP 未安装 / 未连接）**：有人值守时 HALT 并提示用户安装 / 启用 chrome-devtools MCP，不自动降级（探针太慢）；无人值守 / 过夜批次才直接降级 harness headless 探针。**MCP 已装但不通**（浏览器起不来且按 runtime-env §6.4 处置后仍失败 / 关键步骤被 MCP 报错阻断）：降级 harness headless 探针。凡降级须在实测报告记一行「降级原因」——无降级原因的探针实测 = 路径违规，报告不收口。
+- 脚本技术细节单源 = `scripts/verify/e2e/harness.mjs`（导出清单：`grep '^export' scripts/verify/e2e/harness.mjs`）；写脚本 import 其导出，禁手写等价逻辑。
+
+### 能力映射（harness ↔ MCP）
+
+| 目标 | MCP | harness |
+|---|---|---|
+| 会话播种 | API 取 token → `evaluate_script` 写 `auth_token` / `auth_user` → `navigate_page reload` | `getToken` + `seedSession` |
+| 导航 / 等待 | `navigate_page` + `wait_for` | `goto` / `hardGoto` / `reload` |
+| 探形 | `take_snapshot`（a11y 树 + uid） | `inventory` / 一次性探针 |
+| 驱动 | `click` / `fill` / `press_key` | `clickText` / `setInput` / `pressKey` |
+| 网络采集 | `list_network_requests` | `installNetCapture` + `apiCalls` |
+| 控制台采集 | `list_console_messages` | `installConsoleCapture` + `consoleErrors` |
+| 度量 / 截图 | `evaluate_script` / `take_screenshot` | `ctx.evaluate` / `ctx.screenshot` |
+
+### 会话与采集规则（两路径同口径）
+- 注入前先到达 FE origin；同文档 hash 切换不重载文档，播种后必须整页 reload。
+- 缺省身份 = 所播 token 的 JWT claims；仅测「与 token 不同身份」才手工播种 `auth_user`（取登录响应的 `jobNo` / `displayName` / `dept`）。
+- 合成 JWT 只适用于零授权 API 调用的页面：`exp = Math.floor(Date.now()/1000) + 1800`，禁写远期；注入后经 about:blank 中转再硬导航。
+- 页面发出带 token 的 API 且 401 即被清会话弹回 `/login`：有真实数据依赖走账号池登录（账号池单源 `.agents/notes/runtime-env.md` §6.1a）。
+- 请求计数剔除 OPTIONS 预检；断言取数以接口响应为准，禁数 DOM（虚拟滚动 / 虚拟列只渲染可视窗口）。
+- 断「控制台零错误」前先滤应用自身噪声（AG Grid license banner、API 未起的 Network Error）；过滤按内容特征，禁用 `^` 行首锚。
+
+### MCP 会话差异
+- MCP 用持久 profile（跨轮保留 localStorage）：先清 localStorage 再播种，或 `new_page` 传 `isolatedContext`。
+- 报「The browser is already running for …chrome-profile」→ 按命令行含 `chrome-devtools-mcp` 杀残留进程（处置登记 runtime-env §6.4）。
+- `take_screenshot` 的 `filePath` 受 MCP 工作区白名单限制（部分宿主连仓库路径与会话目录全拒，2026-10-31 实测）：落盘被拒时不反复试路径，改**无 `filePath` 内联截图**留档；证据效力以 `.md` 报告的 DOM/接口断言为准（spec 验收判据本就不认图片路径）。
+- `upload_file` 触发 `input[type=file]` 时仓库/会话路径同样可被白名单全拒（2026-11-07 实测）：不试路径，改页面内注入——临时只读 HTTP 服务（如 `npx serve` 随机口）伺服夹具，`evaluate_script` fetch 成 File 塞 `DataTransfer` 再 `dispatchEvent(new Event('change', {bubbles:true}))` 给 antd 上传 input；注入前 `modalCount` 记 1 防旧弹窗 DOM 残留错位（MTO 弹窗关闭后残留曾致 PML 注入错位，reload 清残留）。验证：上传项 tag/预览接口收到文件行数与夹具行数一致。
+
+## 工作流
+
+### 1. 环境准备
+- 按 `.agents/notes/runtime-env.md` 启动 API / 前端；记录所有启动进程。
+- 多 worktree 并行：设 `SHIPYARD_SLOT` 使 API / 前端 / CDP 三组端口整体偏移（端口字面量单源 `scripts/verify/e2e/ports.mjs`，端口表见 runtime-env §6.1b）。
+- 仅 harness / 降级路径自建浏览器：较新 Chromium 内核 headless（如 Edge `--headless=new`）；MCP 路径浏览器实例由 MCP 自管，禁手动另起。
+- 长命服务以独立进程启动（如 PowerShell `Start-Process`）；启动命令末尾禁接管道。
+
+### 2. 执行验证
+- 选点取特性地图（`features/`）；至少各执行一条正常路径与一条失败 / 边界路径（校验 / 空态 / 权限）。
+- 导航：hash 模式用 `goto`；深链接（Query 变化）用 `hardGoto`（about:blank 中转）。
+- 弹窗内分页表格的数据条件断言：点 `.ant-pagination-item` 逐页扫全量后合并断言，禁只看首屏。
+- 布局类断言先探真实 DOM（快照 / 探针读 `outerHTML` + `getComputedStyle`），禁从 CSS 源码反推期望值；拿不准用与规范数值解耦的不变量，规范对账降为 NOTE。
+- 证据采集：截图、网络报文、控制台日志；路径记入任务文档「验收标准」项后。
+
+### 3. 清理收尾
+- 按 POST 响应返回的 ID 精确删除临时数据；禁模糊匹配删除。
+- 关闭本流程启动的所有进程。
+- 按 `页面 / 步骤 / 期望 vs 实际 / 证据` 汇报；末行附「特性地图覆盖 M/N」（M = 本次覆盖特性数，N = `features/` 条目总数），未覆盖项逐一留名。
+- 仅记录缺陷，禁直接修代码。
+- UI 实测报告写 `workflow/evidence/<YYYY-MM-DD>-<主题>.md`：头部记环境 / 复现命令，断言表每行带「对应验收 An」列（形态对照 `workflow/evidence/2026-10-24-purchase-contract-template-print-ui.md`）。报告留在会话或 `tmp/` = 实测未收口。
+
+## 特性地图（features/）
+- `features/` 每核心特性一文件，四段缺一不建：到达路径 / 驱动 / 可观察终态 / Gotchas。
+- 实测与关单抽验按地图取覆盖面；当前覆盖面以 `features/` 目录为准。
+- 新页面或新主链上线时同步建文件；以 `frontend/src/router/index.ts` 路由为源波次：路由有、地图无 = 待补；地图有、路由无 = 待删或改写。
+- 覆盖缺口 / 骨架：`node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs --check`（或 `--json`）列未覆盖路由；`--route <path>` 只写四段 H2 + TODO 骨架，禁编造驱动步骤。
+- 月度漂移维护：① 取路由 / 组件近月 diff 作源波次；② 只对触及特性跑一次实测；③ 修正最多一笔提交。
+- 每个失败先判定「地图漂移」或「代码缺陷」：前者改地图，后者进 incident，禁混写。
+- 前置条件缺失 → 按失败记录并把原因写进该特性 Gotchas；禁为通过而弱化验证路径。
+- 发现页面 / 行为与地图不符 → 先修地图再出结论。
+- 关单前置跑 `check-regression-consistency.mjs`：地图引用的 `#/路由` / `frontend/src/*` / `workflow/*.md` / `scripts/verify/*.mjs` 悬空即红；代码符号悬空只 advisory。
+
+## 技术要求与约束
+
+### Shell 与进程
+- 协议优先 HTTP，避免自签证书拦截。
+- 「部分改动生效」→ 重启 dev server；单文件未生效而他文件正常 → 先 touch 该文件。
+- 探针必打本 worktree 的 dev server：vite 端口被占会静默漂移——起服务后确认实际端口，用 `E2E_FE_URL=http://localhost:<实际端口>` 运行；登录页导航用同一 `FE`（localStorage 按 origin 隔离）。
+- 输出截断用 `| tail -N`，禁 `| head -N`（SIGPIPE 在 finally 前终止进程，残留浏览器占 CDP 端口）。
+- 每次导航前重置 Console / Log 采集器；toast 观察器在导航动作前安装。
+- 实测脚本三件套缺一不可：`installNetCapture(ctx)`、`seedSession(token, { reload: true })`、`hardGoto(url)`。
+- 探针主体包 `try { … } finally { await ctx.close?.() }`；脚本启动前按 `--remote-debugging-port=<port>` 杀残留进程自愈。
+- 用 `harness.dbQuery` 前先确认 database-explorer 技能在本机可用；不连库也能立的判据优先。
+
+### 断言汇总
+- 断言主体包 try/catch：catch 里追加一条失败断言（含错误信息）并计入汇总，退出码随之为 1；禁「跑一半 + 打印 GREEN + 退出码 0」。
+
+### DOM 定位与交互
+- 覆盖层 / 抽屉 / 弹窗内表单定位一律限定覆盖层根（如 `.pml-detail .ant-form-item`），禁全局 `querySelector` / `querySelectorAll`。
+- 按 placeholder 找输入框须限定在目标容器内。
+- 文本比较两侧都 `.replace(/\s+/g,'')` 归一（antd 对两字中文按钮插空格）。
+- 可见性判据用 `getClientRects().length > 0` 或 `getBoundingClientRect().width > 0`；禁用 `offsetParent`（`position: fixed` 祖先下恒为 null）。
+- `a-select` 清除图标悬停才渲染：先派发 mouseenter / mouseover，等一拍再点。
+- antd 分页 size-changer 下拉合成事件开不了（focus + 派发 keydown Enter 亦不稳）：真实路径 = click 工具点 combobox uid；量测用不变量「每选项 `scrollWidth <= clientWidth+1` 且下拉宽 ≥ 最宽选项 scrollWidth」，下拉动画未收尾会量到 0 尺寸，等 ≥600ms 再量（2026-11-06 PML 分页实测）。
+- 弹窗内小控件（如分页器）被身后大表挤出 a11y 快照（输出超限截断取不到 uid）：临时对背景表容器 `setAttribute('aria-hidden','e2e-hide')` 缩树，取 uid 完成真实点击后移除属性；注意别把弹窗自己的表一并隐掉（2026-11-06 PML 实测）。
+- `a-select` 合成事件选不中 → 走真实鼠标 + 键盘：CDP `Input.dispatchMouseEvent` 点开，`ArrowDown` + `Enter` 落选；多 select 之间先 `Escape` 关上一个下拉；选项查询限定可见下拉（`.ant-select-dropdown:not(.ant-select-dropdown-hidden)`）的最后一个。
+- 分段 / 单选 / tabs 按渲染形态定位（如 `.ant-radio-button-wrapper`），勿只找 `<button>`。
+- 表格选择态：清空遗留勾选按 `data-row-key` 去重逐行点击，且与后续勾选分两拍执行；表头全选框在半选 / 无选态点击是「全选」而非「清空」。
+- `:scroll={y}` 的 antd 表格 tbody 首行是 `.ant-table-measure-row`（高 0、无 `ant-table-cell` 类）：行高 / 单元格度量跳过它。
+- `ctx.evaluate` 返回已是对象，禁再套 `JSON.parse`。
+- 详情覆盖层的「返回」类按钮走 `history.back()`：实测点它会退到上一步甚至 `about:blank`（2026-11-03 采购订单详情实测踩中）——回列表改用刷新或直接重导航，禁点「返回」当关闭动作。
+- 断言前先确认覆盖层内容已渲染（头部按钮组出现）：并行会话新建的单据可能详情拉不出，覆盖层只剩「返回」按钮（2026-11-03 实测）——换已知样本单，勿据此判功能缺陷。
+
+### AG Grid 列表页
+- 单元格开销 32px（padding 15×2 + 边框 2），非 16 / 24。
+- 量宽用隐藏 DOM span（复制 `font` / `letter-spacing`），禁 canvas；定宽 `ceil10(max(列头需求, 内容 p90 需求) + 32 + 8)`，离群值交 `tooltipShowMode:'whenTruncated'`。
+- 判截断直接比 `.ag-cell` 的 `scrollWidth > clientWidth`；量横向溢出用 `.ag-center-cols-viewport`，勿量 `.ag-body-viewport`。
+- 列虚拟化下视口外列不在 DOM：`.ag-header-cell` 计数 ≠ 列总数。
+- 空值经 `valueFormatter` 渲染成字面 `-`：按单元格判空须显式排除 `'-'`。

package/templates/engine/.agents/skills/verify-ui/scripts/gen-verify-feature.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// gen-verify-feature.mjs — verify-ui 特性地图生成器（2026-10-22 pstack create-verification-skill 借鉴）
+// 用法：
+//   node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs [--check] [--json]       列出未覆盖的顶层路由
+//   node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs --route /suppliers       生成 features/suppliers.md 骨架
+// 口径：顶层路由 = router 里一段路径（排除 /login、/、/home、含 :param 的动态路由）。
+//   覆盖 = 任一 features/*.md 提到该路由（#/route 或 /route）。
+//   生成只写骨架（四段 H2 + TODO），不编造驱动步骤；填完再用于实测。
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const asJson = argv.includes('--json');
+const check = argv.includes('--check');
+const routeArg = argOf('--route');
+
+const root = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (root.status !== 0 || !root.stdout.trim()) {
+  console.error('gen-verify-feature: 不在 git 仓库');
+  process.exit(2);
+}
+const ROOT = root.stdout.trim();
+const routerPath = path.join(ROOT, 'frontend', 'src', 'router', 'index.ts');
+if (!fs.existsSync(routerPath)) {
+  console.error('gen-verify-feature: 未找到 frontend/src/router/index.ts');
+  process.exit(2);
+}
+const routes = new Set();
+for (const m of fs.readFileSync(routerPath, 'utf8').matchAll(/path:\s*'([^']+)'/g)) {
+  const raw = m[1];
+  routes.add(raw.startsWith('/') ? raw : `/${raw}`);
+}
+const topLevel = [...routes].filter((r) => {
+  if (r === '/' || r === '/login' || r === '/home') return false;
+  if (r.includes(':')) return false;
+  return r.split('/').filter(Boolean).length === 1;
+}).sort();
+
+const featuresDir = path.join(ROOT, '.agents', 'skills', 'verify-ui', 'features');
+const covered = new Set();
+if (fs.existsSync(featuresDir)) {
+  for (const f of fs.readdirSync(featuresDir).filter((x) => x.endsWith('.md'))) {
+    const text = fs.readFileSync(path.join(featuresDir, f), 'utf8');
+    for (const m of text.matchAll(/#?(\/[A-Za-z0-9_./:-]+)/g)) covered.add(m[1]);
+  }
+}
+const uncovered = topLevel.filter((r) => !covered.has(r));
+
+if (asJson) {
+  console.log(JSON.stringify({ topLevel, covered: [...covered].sort(), uncovered }, null, 2));
+  process.exit(check && uncovered.length ? 1 : 0);
+}
+if (check) {
+  if (uncovered.length) {
+    console.error(`特性地图覆盖缺口（${uncovered.length} 个顶层路由未进地图）：`);
+    for (const r of uncovered) console.error(`  - ${r}`);
+    console.error('  处理：按核心特性优先级补 features/<slug>.md（node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs --route <path> 生成骨架）。');
+    process.exit(1);
+  }
+  console.log(`✅ 特性地图覆盖全部 ${topLevel.length} 个顶层路由`);
+  process.exit(0);
+}
+if (routeArg) {
+  const route = routeArg.startsWith('/') ? routeArg : `/${routeArg}`;
+  if (!routes.has(route)) {
+    console.error(`gen-verify-feature: 路由 ${route} 不在 router（先确认路径）`);
+    process.exit(2);
+  }
+  if (covered.has(route)) {
+    console.error(`gen-verify-feature: 路由 ${route} 已被特性地图覆盖——改现有文件，不新建`);
+    process.exit(1);
+  }
+  const slug = route.replace(/^\//, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '') || 'feature';
+  const file = path.join(featuresDir, `${slug}.md`);
+  if (fs.existsSync(file)) {
+    console.error(`gen-verify-feature: 文件已存在 ${path.relative(ROOT, file)}——改现有文件，不覆盖`);
+    process.exit(1);
+  }
+  const content = [
+    `# 特性：${route}`,
+    '',
+    '> 生成骨架（gen-verify-feature.mjs，2026-10-22）。四段缺一不建；填完再用于实测。',
+    '',
+    '## 到达路径',
+    '',
+    `hash 路由 \`#${route}\`。入口：<TODO 侧栏/列表/按钮>。`,
+    '',
+    '## 驱动',
+    '',
+    '<TODO 用户 POV 的操作步骤；优先稳定锚点（ARIA/data-testid/路由）>。',
+    '',
+    '## 可观察终态',
+    '',
+    '<TODO 什么现象证明它工作；给 file:line 或接口/字段>。',
+    '',
+    '## Gotchas',
+    '',
+    '<TODO 前置条件、坑、已知漂移>。',
+    '',
+  ].join('\n');
+  fs.mkdirSync(featuresDir, { recursive: true });
+  fs.writeFileSync(file, content, 'utf8');
+  console.log(`✅ 已生成 ${path.relative(ROOT, file)}——填完四段再用于实测`);
+  process.exit(0);
+}
+
+console.log(`顶层路由 ${topLevel.length} 个，已覆盖 ${topLevel.length - uncovered.length} 个，缺口 ${uncovered.length} 个：`);
+for (const r of uncovered) console.log(`  - ${r}`);
+console.log('生成骨架：node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs --route <path>');

package/templates/engine/.agents/skills/visual-parity/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: visual-parity
+description: 视觉对齐 playbook——两个实现（原型 / 旧页 / 设计稿）像素级对齐时，固定视口与数据、只改样式、差异分类留证；供 UI 还原任务使用。
+---
+
+# visual-parity — 视觉对齐
+
+## 触发
+
+原型 → 实现、旧页 → 新页、设计稿 → 页面，要求「看起来一致」。
+
+## 0. 固定比较条件
+
+同一视口（宽高 + DPR）、缩放 100%、同一主题、同一份数据（种子 ID 固定）。服务在线与鉴权按 `.agents/skills/verify-ui/SKILL.md` §1；技术细节单源 `scripts/verify/e2e/harness.mjs`。
+
+## 1. 取对照
+
+两侧各截同区域（含边界元素），命名 `tmp/e2e-evidence/parity-<topic>-{before,after}.png`。截图前重置滚动位置、关闭动画与 tooltip。
+
+## 2. 差异分类（逐项计数）
+
+间距 / 字号字重 / 颜色 / 层级与阴影 / 圆角 / 换行与溢出 / 滚动条。渲染噪声（字体抗锯齿、次像素）单列，不计入待修项。
+
+## 3. 迭代
+
+只改样式与布局，不改数据、不改后端、不引原型字体。每轮重截同区域；差异项只减不增。
+
+## 4. 判据与证据
+
+待修项 = 0 才算对齐；未清零不宣称「一致」。证据：两侧截图路径 + 视口 + 差异表（项 / 前 / 后 / 状态）。
+
+## 红线
+
+- 不弱化验证路径（`.agents/skills/verify-ui/SKILL.md`「禁为通过而弱化验证路径」）。
+- 不以「肉眼看着一样」代替差异表。

package/templates/engine/.agents/skills/why/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: why
+description: 追溯「为什么长这样」——并行查源码历史、流程留痕、领域文档、会话记录、issue/PR 与外部证据，逐条给指针；供动手改一段不理解的代码前使用。
+---
+
+# why — 为什么长这样
+
+## 触发
+
+- 「为什么这样设计 / 为什么这个 flag 没开 / 为什么选了这个方案」。
+- 准备改一段不理解的代码，先要知道它为什么存在。
+- 复核时对「这行不能删」的直觉不放心，需要证据。
+
+## 核心
+
+**不靠记忆，不靠猜。** 按证据类别并行查，每条结论带指针（`file:line` / commit / 文档 / issue / 指标）。区分 **measured / inferred / guess**；找不到也是答案，写「无记录」，不要编。
+
+## 证据类别（并行查）
+
+| 类别 | 本仓入口 |
+|---|---|
+| 源码与历史 | `git log -S<term>`（pickaxe）、`git log --follow -- <path>`、`git blame`、`xd://lsp` references |
+| 流程留痕 | `workflow/{intents,specs,plans,incidents}`、`workflow/archive/`、`workflow/delegations.md`、`workflow/papercuts.md`、`workflow/regression-checklist.md` |
+| 领域知识 | `wiki/`、`node .agents/scripts/kb-search.mjs <term>` |
+| 会话记录 | `history://`、`archive`（eval 全局）、`.agents/skills/session-resume/SKILL.md` |
+| Issue / PR | `issue://<N>`、`pr://<N>`（有 GitHub 远端时） |
+| 外部文档 | `microsoft_docs_search`、`web_search`、`read <url>` |
+| 运行时 / 监控 | 可用的 MCP（chrome-devtools、context-mode 等）、日志、`workflow/metrics.md` |
+
+## 步骤
+
+1. **拆主体**：把问题拆成可检索的词——符号名、文件路径、功能名、决策关键词。一个词查不到就换同义词/中文/英文。
+2. **本地证据**：跑 `node .agents/skills/why/scripts/why-evidence.mjs <term> [--path <file>]`，一次拿到 pickaxe、路径历史、workflow/wiki 命中、kb-search 摘要。
+3. **外部证据**：按可用 MCP 并行查 issue/PR、外部文档、监控；没有就跳过，不假装查过。
+4. **合成**：先给结论（为什么），再给证据链（每条 claim 带指针），最后列未知/冲突。
+5. **标确定性**：`measured`（跑过/读到原文）、`inferred`（从证据推）、`guess`（没有证据）。预测与未观察到的原因一律 `guess`。
+6. **时间线**（可选）：决策跨多个提交/文档时，按时间排一条链，标出转折点。
+
+## 输出格式
+
+- **结论**：一句话回答「为什么」。
+- **证据链**：每条 = claim + 指针（`file:line` / commit / doc / issue）+ 确定性。
+- **未知 / 冲突**：查不到、证据互相矛盾、或需要 owner 才能定的部分。
+- **对改动的含义**：这段能不能动、动之前要满足什么。
+
+## 本仓落点
+
+- 接手/续作：`session-resume` 重建当前态后，用本技能补「为什么」。
+- 修 bug：`diagnosing-bugs` 找根因前，先确认这段为什么存在。
+- 复核：`review.md` 的「影响面证明」用 `blast-radius`；本技能补「历史意图」。
+- 证据收集器：`.agents/skills/why/scripts/why-evidence.mjs`（只收集，不下结论）。
+
+## 边界
+
+- 本技能回答「为什么长这样」；`blast-radius` 回答「会碰坏什么」；`how` 回答「怎么运作」。三者不互相替代。
+- 不把推测写成事实；没有证据就写「无记录」。

package/templates/engine/.agents/skills/why/scripts/why-evidence.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// why-evidence.mjs — /why 的本地证据收集器（2026-10-22 pstack 借鉴）
+// 用法：node .agents/skills/why/scripts/why-evidence.mjs <term> [--path <file>] [--json]
+// 收集：git pickaxe（-S）、路径历史（--follow）、workflow 文档命中、wiki 命中、kb-search 摘要。
+// 不做结论——结论由 why 技能合成；本脚本只保证证据面一致、可复跑、可对质。
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+let term = '';
+let pathArg = '';
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--path') { pathArg = argv[++i] || ''; continue; }
+  if (argv[i] === '--json') continue;
+  if (!term) term = argv[i];
+}
+const asJson = argv.includes('--json');
+if (!term) {
+  console.error('用法：node .agents/skills/why/scripts/why-evidence.mjs <term> [--path <file>] [--json]');
+  process.exit(2);
+}
+
+const root = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+const ROOT = root.status === 0 && root.stdout.trim() ? root.stdout.trim() : process.cwd();
+process.chdir(ROOT);
+
+const git = (args) => spawnSync('git', args, { encoding: 'utf8' });
+const lines = (s) => String(s || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+
+const pickaxe = lines(git(['log', '-S', term, '--oneline', '--all', '-n', '20']).stdout);
+const pathHistory = pathArg ? lines(git(['log', '--oneline', '--follow', '-n', '10', '--', pathArg]).stdout) : [];
+
+// 文档命中：只取每个文件的第一处，限 20 条；跳过生成物（verify-evidence / INDEX / metrics）。
+const scan = (dir, limit = 20) => {
+  const out = [];
+  const walk = (d) => {
+    let entries = [];
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (out.length >= limit) return;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { if (!/^(node_modules|\.git)$/.test(e.name)) walk(p); continue; }
+      if (!/\.md$/i.test(e.name)) continue;
+      if (/^(verify-evidence|INDEX|metrics)\.md$/.test(e.name)) continue;
+      let text = '';
+      try { text = fs.readFileSync(p, 'utf8'); } catch { continue; }
+      const rows = text.split(/\r?\n/);
+      const hit = rows.findIndex((l) => l.toLowerCase().includes(term.toLowerCase()));
+      if (hit >= 0) out.push(`${path.relative(ROOT, p).replace(/\\/g, '/')}:${hit + 1}: ${rows[hit].trim().slice(0, 160)}`);
+    }
+  };
+  walk(path.join(ROOT, dir));
+  return out;
+};
+const workflow = scan('workflow');
+const wiki = scan('wiki');
+
+const kb = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'kb-search.mjs'), term, '-n', '5'], { cwd: ROOT, encoding: 'utf8' });
+const kbOut = String(kb.stdout || '').trim();
+
+if (asJson) {
+  console.log(JSON.stringify({ term, path: pathArg || null, pickaxe, pathHistory, workflow, wiki, kb: kbOut }, null, 2));
+  process.exit(0);
+}
+const section = (title, rows) => `## ${title}\n${rows.length ? rows.map((r) => `- ${r}`).join('\n') : '（无命中）'}`;
+console.log(`# why evidence: ${term}${pathArg ? `（path: ${pathArg}）` : ''}\n`);
+console.log(section('git pickaxe（-S：增删过该词的提交）', pickaxe));
+if (pathArg) console.log(`\n${section('路径历史（--follow）', pathHistory)}`);
+console.log(`\n${section('workflow 文档命中', workflow)}`);
+console.log(`\n${section('wiki 命中', wiki)}`);
+console.log(`\n## kb-search\n${kbOut || '（无输出）'}`);

package/templates/engine/.agents/skills/wiki/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: wiki
+description: 项目 wiki 整理与验证技能。负责将散落文档归位到 wiki/，并维护 INDEX.md、知识沉淀总览.html 及归档一致性。
+---
+
+# Wiki 整理与验证技能
+
+## 目标
+构建并维护结构化的项目知识库，确保磁盘文件、索引文件与可视化看板三方一致。
+
+## 触发条件
+- 用户指令：`整理 wiki` / `归类文档` / `建知识库` / `同步知识沉淀看板` / `新增文档到 wiki`。
+
+## 范围与约束
+- **收录范围**：
+    - **In**: 主数据知识文档、全项目数据维护 SQL。
+    - **Out**: `workflow/` 目录、MTO/采购/库存/UI 等非主数据知识文档、依赖锁文件、IDE 配置。
+- **目录结构**：`wiki/<主题>/<关键词文件>`。
+- **命名规范**：`<主题>-<关键词>[-范围/版本].ext`。
+- **权威性**：`.md` 为内容源 $\rightarrow$ `.html` 为展示快照。冲突时以 `.md` 为准。
+- **操作限制**：仅执行复制 (`Copy-Item`/`cp`)。删除原文件必须获得用户单独确认。
+
+## 标准操作流程
+
+### 1. 整理与归位 (批量/新建)
+1. **主题判定**：读取文件首 8 行，根据内容判定主题。新主题需与用户对齐。
+2. **目录创建**：创建 `wiki/<主题>/` 及对应的 `wiki/drafts-archive/YYYY-MM-DD_<主题>/`。
+3. **文件迁移**：
+    - 将文件复制到 `wiki/<主题>/` 并按规范重命名。
+    - 将原文件副本复制到 `drafts-archive/` 留溯源。
+4. **索引更新**：运行 `node .agents/scripts/gen-wiki-board.mjs`。
+5. **描述补全**：在 `wiki/INDEX.md` 速览表的「用途」列为新主题补全描述，然后再次运行生成器。
+
+### 2. 单篇文档新增
+1. 判定主题 $\rightarrow$ 复制到 `wiki/<主题>/` $\rightarrow$ 运行生成器 $\rightarrow$ 运行验证脚本。
+
+### 3. 错误归位修正
+1. 移动文件至正确主题目录 $\rightarrow$ 运行生成器 $\rightarrow$ 运行验证脚本。`drafts-archive` 保持不动。
+
+## 验证机制
+每次改动后必须运行：
+```bash
+node .agents/scripts/verify-wiki-consistency.mjs
+```
+**验收标准**：
+- `exit 0` 且输出 `✅ wiki 三方一致`。
+- 检查项涵盖：磁盘 $\leftrightarrow$ INDEX $\leftrightarrow$ 看板 DATA $\leftrightarrow$ 数据维护台账 $\leftrightarrow$ 链接可达性。
+
+## 维护须知
+- **生成区**：`wiki/INDEX.md` 的计数/映射表及 `知识沉淀总览.html` 的 DATA 块为自动生成区，禁止手动修改。
+- **人工编辑位**：仅维护 `wiki/INDEX.md` 的「用途」列及 `wiki/数据维护/README.md` 台账。
+- **冲突处理**：wiki 与 `AGENTS.md` 或 `workflow` 冲突时，以后者为准。
+- **提交规范**：调整 wiki 内容（知识文档新增/修改/删除/更名/归位、INDEX、看板、本技能文件）属 docs 级改动，**豁免工作流三件套**（不生成 intents/specs/plans、不走确认门），直接 commit (`docs(wiki): <动作>`)；规则单源 = 根 `AGENTS.md` §4「wiki 豁免」。删除文件仍须用户单独确认（见「操作限制」）。

package/templates/engine/.agents/tests/auto-tour.test.mjs

@@ -0,0 +1,82 @@
+// auto-tour.test.mjs — 自动拉起开发全景看板脚本测试（node:test + node:assert，零新依赖）
+// 被测：.agents/scripts/auto-tour.mjs
+//
+// 测三条本脚本自带的非平凡逻辑（其余是纯 spawn 转发，不测）：
+//   1. 参数校验：缺文档 / 文档不存在 → exit 1 且给出可操作的提示；
+//   2. 失败降级：ensure-board 起不来时脚本 exit 0 且打印告警——全景图是可选观察面，不是门禁，
+//      不得因看板不可用阻断 Build 流程；
+//   3. 端口语义：显式 --port 是绝对值、不吃 SHIPYARD_SLOT 槽位偏移（与 ensure-board 同口径）。
+//
+// 确定性口径：第 2/3 条用一个「快速响应非 200」的桩 HTTP 服务器占住端口——ensure-board 的
+//   httpProbe 立即拿到非 200 → 判「他人进程占用槽位口」→ exit 1，走与真实占用同一条分支，
+//   但不触发它 25s 的挂起超时（那是「占端口但不响应」的慢路径，真实冷启动环境才有，
+//   放到测试里会把本门从 <3s 拉到 30s）。
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '../..');
+const AUTO_TOUR = path.join(ROOT, '.agents', 'scripts', 'auto-tour.mjs');
+const PLAN = 'workflow/plans/2026-11-09-document-attachment.md';
+
+function run(args, env = {}) {
+  return new Promise((resolve) => {
+    const c = spawn(process.execPath, [AUTO_TOUR, ...args], {
+      cwd: ROOT, encoding: 'utf8',
+      env: { ...process.env, ...env },
+    });
+    let out = '', err = '';
+    c.stdout.on('data', (d) => { out += d; });
+    c.stderr.on('data', (d) => { err += d; });
+    c.on('close', (code) => resolve({ code, out, err }));
+  });
+}
+
+// 起一个立刻回 404 的 HTTP 服务器占端口（非看板身份）
+function occupy(port) {
+  return new Promise((resolve) => {
+    const s = http.createServer((req, res) => { res.statusCode = 404; res.end('not a board'); });
+    s.listen(port, '127.0.0.1', () => resolve(s));
+  });
+}
+
+describe('auto-tour', () => {
+  test('缺文档参数时 exit 1 并打印用法', async () => {
+    const r = await run([]);
+    assert.equal(r.code, 1);
+    assert.match(r.err, /用法/);
+  });
+
+  test('文档不存在时 exit 1 并点名文件', async () => {
+    const r = await run(['workflow/plans/__not-exist__.md']);
+    assert.equal(r.code, 1);
+    assert.match(r.err, /找不到文档/);
+  });
+
+  test('看板拉不起来时 exit 0 且告警——不阻断 Build 流程', async () => {
+    const s = await occupy(18777);
+    try {
+      const r = await run([PLAN, '--port', '18777']);
+      assert.equal(r.code, 0, '看板不可用时必须 exit 0');
+      assert.match(r.err + r.out, /未就绪|不影响/);
+      assert.match(r.err + r.out, /ensure-board/, '告警须给出手动兜底命令');
+    } finally {
+      s.close();
+    }
+  });
+
+  test('显式 --port 是绝对值，不吃 SHIPYARD_SLOT 槽位偏移', async () => {
+    const s = await occupy(18778);
+    try {
+      const r = await run([PLAN, '--port', '18778'], { SHIPYARD_SLOT: '2' });
+      // 槽位 2 的偏移是 +20；端口若被偏移到 18798，桩服务器（18778）就拦不住它——失败分支不触发
+      assert.match(r.err + r.out, /未就绪|不影响/, '端口应按绝对值使用，未被槽位偏移');
+    } finally {
+      s.close();
+    }
+  });
+});