agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/skills/eval/scripts/eval-score.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// eval-score.mjs — 盲评 A/B 计分器（2026-10-22 pstack /eval 借鉴）
+// 用法：node .agents/skills/eval/scripts/eval-score.mjs <results.tsv> [--json]
+// TSV 表头：task	expected	a	b
+//   a/b = pass|fail（或 1/0/true/false/y/n）；空 = 未跑，跳过。
+// 输出：A 命中率 / B 命中率 / Δ（百分点）/ 翻转任务（a≠b）。
+// 退出：0 正常；2 文件缺失/无有效行。
+import fs from 'node:fs';
+
+const argv = process.argv.slice(2);
+const file = argv.find((a) => !a.startsWith('--'));
+const asJson = argv.includes('--json');
+if (!file) {
+  console.error('用法：node .agents/skills/eval/scripts/eval-score.mjs <results.tsv> [--json]');
+  process.exit(2);
+}
+if (!fs.existsSync(file)) {
+  console.error(`eval-score: 文件不存在 ${file}`);
+  process.exit(2);
+}
+
+const norm = (v) => {
+  const s = String(v || '').trim().toLowerCase();
+  if (['pass', '1', 'true', 'y', 'yes'].includes(s)) return true;
+  if (['fail', '0', 'false', 'n', 'no'].includes(s)) return false;
+  return null;
+};
+
+const rows = [];
+for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+  if (!line.trim() || line.trim().startsWith('#')) continue;
+  const cells = line.split('\t').map((c) => c.trim());
+  if (cells[0] === 'task') continue;
+  const [task, expected, a, b] = cells;
+  const av = norm(a);
+  const bv = norm(b);
+  if (!task || av === null || bv === null) continue;
+  rows.push({ task, expected, a: av, b: bv });
+}
+if (!rows.length) {
+  console.error('eval-score: 无有效行（需要 task/expected/a/b，a/b 为 pass|fail）');
+  process.exit(2);
+}
+
+const total = rows.length;
+const aPass = rows.filter((r) => r.a).length;
+const bPass = rows.filter((r) => r.b).length;
+const aRate = (aPass / total) * 100;
+const bRate = (bPass / total) * 100;
+const deltaPp = aRate - bRate;
+const flips = rows.filter((r) => r.a !== r.b).map((r) => r.task);
+
+if (asJson) {
+  console.log(JSON.stringify({ total, a: { pass: aPass, rate: aRate }, b: { pass: bPass, rate: bRate }, deltaPp, flips }, null, 2));
+  process.exit(0);
+}
+console.log(`A 命中 ${aPass}/${total} (${aRate.toFixed(1)}%)｜B 命中 ${bPass}/${total} (${bRate.toFixed(1)}%)｜Δ ${deltaPp >= 0 ? '+' : ''}${deltaPp.toFixed(1)}pp｜翻转 ${flips.length}`);
+if (flips.length) console.log(`翻转任务：${flips.join('、')}`);
+if (Math.abs(deltaPp) < 20) console.log('提示：Δ < 20pp，小 N 噪声内，不要宣称有效。');

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

@@ -0,0 +1,49 @@
+---
+name: interrogate
+description: 多模型多镜头对抗复核——不同模型/不同视角独立拆同一 diff，再聚合去重；供高风险 PR、L2/L3 复核、或单模型复核不放心时使用。
+---
+
+# interrogate — 多镜对抗复核
+
+## 触发
+
+- 高风险 diff（跨边界、并发、鉴权、数据迁移、公共接口）。
+- L2/L3 独立复核之外还想加一道。
+- 单模型复核结论「看起来没问题」，但你不放心。
+
+## 核心
+
+**不是再跑一遍单模型 review。** 是让不同模型、不同镜头**独立**拆同一 diff，再聚合去重。不同模型抓不同的真 bug；同一模型换镜头也能抓单镜漏掉的面。
+
+## 步骤
+
+1. **固定目标**：base/head、spec 路径、风险级别。目标不固定不开始。
+2. **生成计划**：`node .agents/skills/interrogate/scripts/interrogate-plan.mjs --base <ref> --head <ref> [--spec <path>]`。输出六个镜头（correctness / security / quality / performance / tests / spec）及每个镜头的文件切片与提示词。
+3. **并行派发**：每个镜头一个子代理，独立读 diff，互不共享结论。
+   - 模型：按 `.agents/config/model-roles.json` 的 `review` 角色（`heterogeneous: true`）；宿主支持模型覆盖时用不同模型，不支持时用不同 agent 人格（`reviewer` / `security-reviewer` / `code-simplifier` / `caveman-reviewer`）。
+   - 每个子代理只拿自己的镜头提示词 + 文件切片，不拿其他镜头的结论（防锚定）。
+4. **聚合**：按 `file:line + 问题` 去重；分 P0/P1/P2；确认的与推测的分开；噪声逐条给「为什么不是问题」。
+5. **输出**：一张合并表 + 「合入前必须修」+ 「已排除」+ 「未覆盖」。
+
+## 输出格式
+
+| 严重度 | 位置 | 问题 | 证据 | 修法 | 来源镜头 |
+|---|---|---|---|---|---|
+| P0 | `file:line` | … | … | … | security |
+
+- **合入前必须修**：P0 全部 + P1 中确认的。
+- **已排除**：看起来像问题但查过不是的，逐条给理由。
+- **未覆盖**：没有镜头覆盖到的面（如运行时行为、外部服务），明确写出来。
+
+## 本仓落点
+
+- `review.md` 执行流程：L2/L3 高风险 diff 叠加本技能。
+- `review-method`：Standards×Spec 双轴 + 坏味道走查仍是单镜基线；本技能是并行补充。
+- `independent-reviewer`：单一独立复核不替代；本技能是多模型补充。
+- 机器门禁：不替代 `verify` / `check-loop`；本技能只出清单，定性仍人放行。
+
+## 边界
+
+- 多模型一致同意是高信号，不是证明；仍要 `blast-radius` 证明关键安全事实。
+- 不把「另一个模型也这么说」当证据；证据仍是 `file:line` / 跑过的代码。
+- 子代理结论必须自己复核，不直接透传。

package/templates/engine/.agents/skills/interrogate/scripts/interrogate-plan.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// interrogate-plan.mjs — /interrogate 的复核计划生成器（2026-10-22 pstack 借鉴）
+// 用法：node .agents/skills/interrogate/scripts/interrogate-plan.mjs [--base <ref>] [--head <ref>] [--spec <path>] [--json]
+// 输出：变更文件 + 镜头（correctness/security/quality/performance/tests/spec）+ 每个镜头的文件切片与提示词。
+// 不做复核——复核由子代理按镜头独立做；本脚本只保证镜头覆盖一致、可复跑、可对质。
+import { spawnSync } from 'node:child_process';
+
+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 base = argOf('--base') || 'origin/main';
+const head = argOf('--head') || 'HEAD';
+const spec = argOf('--spec') || '';
+const asJson = argv.includes('--json');
+
+const root = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (root.status !== 0 || !root.stdout.trim()) {
+  console.error('interrogate-plan: 不在 git 仓库');
+  process.exit(2);
+}
+process.chdir(root.stdout.trim());
+const git = (args) => spawnSync('git', args, { encoding: 'utf8' });
+if (git(['rev-parse', '--verify', `${base}^{commit}`]).status !== 0) {
+  console.error(`interrogate-plan: 基线 ${base} 不存在（先 git fetch origin，或用 --base 指定）`);
+  process.exit(2);
+}
+if (git(['rev-parse', '--verify', `${head}^{commit}`]).status !== 0) {
+  console.error(`interrogate-plan: head ${head} 不存在`);
+  process.exit(2);
+}
+
+const files = String(git(['-c', 'core.quotepath=off', 'diff', '--name-only', '--no-renames', `${base}...${head}`]).stdout || '')
+  .split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+if (!files.length) {
+  console.error(`interrogate-plan: ${base}...${head} 无变更——没有可复核的 diff`);
+  process.exit(2);
+}
+
+const match = (re) => files.filter((f) => re.test(f));
+const security = match(/auth|token|secret|password|crypto|sql|query|upload|import|export|api|controller|middleware|permission|role/i);
+const performance = match(/service|repository|query|sql|index|list|table|render|computed|watch|effect|loop|batch/i);
+const tests = match(/(^|\/)(tests?|__tests__)\/|\.(test|spec)\.[a-z]+$/i);
+
+const lenses = [
+  { id: 'correctness', focus: '逻辑、边界、错误路径、状态转换、并发交错', files },
+  { id: 'security', focus: '信任边界、注入、鉴权、越权、敏感数据、输入解析', files: security.length ? security : files, note: security.length ? '' : '无显式安全敏感文件——仍按全量文件扫信任边界' },
+  { id: 'quality', focus: '死代码、重复、命名、注释、抽象层数、可维护性', files },
+  { id: 'performance', focus: '查询/循环/渲染/内存/并发资源', files: performance.length ? performance : files, note: performance.length ? '' : '无显式性能敏感文件——仍按全量文件扫热点' },
+  { id: 'tests', focus: '行为断言、边界覆盖、测试是否会在实现全返回 undefined 时仍通过', files: tests.length ? tests : files, note: tests.length ? '' : '无测试文件变更——检查是否缺测试' },
+  { id: 'spec', focus: spec ? `对照 spec ${spec} 的验收标准与契约` : '对照 workflow/specs 与契约面（未指定 --spec 时按变更面找同名 spec）', files },
+];
+
+const promptOf = (l) => [
+  `镜头：${l.id}——${l.focus}`,
+  `目标：${base}...${head}`,
+  spec ? `spec：${spec}` : '',
+  `文件（${l.files.length}）：`,
+  ...l.files.map((f) => `- ${f}`),
+  l.note ? `注：${l.note}` : '',
+  '输出：每条 finding = 严重度（P0/P1/P2）+ file:line + 证据 + 修法；确认的与推测的分开；无发现写「无」。',
+].filter(Boolean).join('\n');
+
+if (asJson) {
+  console.log(JSON.stringify({ base, head, spec: spec || null, files, lenses: lenses.map((l) => ({ ...l, prompt: promptOf(l) })) }, null, 2));
+  process.exit(0);
+}
+console.log(`# interrogate plan：${base}...${head}（${files.length} 文件）\n`);
+for (const l of lenses) {
+  console.log(`## ${l.id}（${l.files.length} 文件）\n${l.focus}${l.note ? `\n注：${l.note}` : ''}\n`);
+}

package/templates/engine/.agents/skills/model-upgrade/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: model-upgrade
+description: 模型升级治理——别名/宿主模型变化时，先对当前评测敏感面跑行为评测、落凭证、写迁移说明，再升级；禁止静默换模型。
+---
+
+# model-upgrade — 模型升级治理
+
+## 触发
+
+- `flow-kit upgrade` 前后、宿主配置里的模型别名变化、`--model` 显式改角色模型。
+- doctor 报 `model drift`：本地 `model-roles.local.json` 与已安装子代理 `model` 字段不一致。
+- 用户说「换模型 / 升级模型 / 这个模型更便宜」。
+
+## 为什么不是普通依赖升级
+
+模型变化会改变**行为**，而静态门只证明代码还能跑。Playbook 的口径：
+评测是 AI-native 的 QA；模型/提示/技能变更都应跑固定任务集。
+
+## 步骤
+
+1. **固定基线**：确认当前 `.agents/config/model-roles.local.json` 与已安装子代理的 `model` 字段一致。
+2. **跑评测**：按 `.agents/skills/eval/SKILL.md` 用新模型跑 A/B；至少覆盖：
+   - 技能触发正/负例；
+   - 命令确认门顺序；
+   - 角色契约（越界即停）；
+   - 一个已知答案的复核样本（`review-method/golden-set.md`）。
+3. **落凭证**：
+   ```bash
+   node .agents/scripts/agent-eval.mjs record --pass-rate <0-1> --tasks <N> --model <id> --note "upgrade <old> -> <new>"
+   node .agents/scripts/agent-eval.mjs check
+   ```
+4. **写迁移说明**：`workflow/model-upgrades.d/<YYYY-MM>.md` 一行一模型：
+   `日期 | 角色 | 旧 | 新 | 通过率 | Δ | 翻转任务 | 回退方式`。
+5. **升级**：`flow-kit upgrade --target .`；doctor 通过后提交。
+6. **回退**：保留旧 `model-roles.local.json` 副本；回退只改本地配置并重跑 `agent-eval check`。
+
+## 红线
+
+- 不在没有评测凭证时把 `agent-eval.json` 设为 `advisory: false` 后宣称“已评估”。
+- 不把 `review` 与 `code` 配成同一模型后忽略告警（`REVIEW_SAME_AS_CODE`）。
+- 不静默改写用户本地模型配置；显式配置永远优先。

package/templates/engine/.agents/skills/number-vetting/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: number-vetting
+description: 数字体检——报告、引用或据此决策任何测量值（耗时/命中率/覆盖率/规模）前的五问；供主智能体写 metrics、门禁成本、复核效果与性能结论时使用。
+---
+
+# number-vetting — 数字体检（五问）
+
+任何数字进 `workflow/metrics.md`、`verifications.jsonl` 解读、PR 正文或方案结论前，逐问过一遍。任一问答不上 → 标「存疑」，不得作为决策依据。
+
+## 五问
+
+| # | 问 | 不合格信号 |
+|---|---|---|
+| 1 | **限制因素**：这个数被什么卡住？ | 说不清瓶颈；把串行等待算进单项耗时 |
+| 2 | **调参/环境**：热缓存、并行度、机器负载造成的？ | 冷/热跑混算；换机器不复现 |
+| 3 | **误差/噪声**：方差多大？复跑分布？ | 单次样本；差值与噪声同量级 |
+| 4 | **口径/窗口**：样本 n、时间窗、排除项与上次一致？ | 口径悄悄换了；跨模型代际直接比 |
+| 5 | **端到端相关性**：测的是用户感知的那段？ | 微基准涨了，端到端没动 |
+
+## 判定与落账
+
+- 三档：**可信**（五问全过）/ **存疑**（缺 1–2 项，补测后复核）/ **不可用**（限制因素不明或口径漂移）。
+- 落账格式：`值（样本 n / 窗口 / 口径 / 复跑 k 次）`；缺项写「未测」，不写 0。
+- `{{指标名}}` 签名由取数器填实时值（check16），不手填。
+
+## 本仓既有口径（先读，别另立）
+
+- 峰值 % 的读法：`workflow/metrics.md` 文首「数字体检」注——静息态 ≈93% 是构造使然，判压力看回填速率，不看峰值。
+- 跨模型代际比较：先读 `workflow/delegations.md`「模型代际基线」；旧月快照不重算。
+- 门禁耗时：用 `verifications.jsonl` 的 `wallMs`；2026-10-16 前绿行无该键、回退各门之和，两种口径不混比。
+
+## 红线
+
+- 不把「门禁变快」写成「质量提升」。
+- 不用单次运行证明性能；不用均值掩盖长尾（最慢门单列）。

package/templates/engine/.agents/skills/page-refactor/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: page-refactor
+description: 业务功能页面改造执行器——按采购订单（PO）样板沉淀的模式改造任意业务页面/模块：形态盘点 → 目标形态与表格选型 → 按 references/templates.md 施工（列表页 + 新建/查看/编辑整模块，支持 Drawer → 覆盖层详情跃迁）→ 全套断言实测。当用户要求「改造某页面 / 对齐采购订单页面 / 整模块 UI 改造 / 列表页改造 / 详情页改造」时使用。
+---
+
+# page-refactor — 业务模块改造（PO 样板模式）
+
+## 定位
+
+- **改造范围 = 整个功能模块**：列表页 + 新建 + 查看 + 编辑一起改造，不是只做布局微调。目标形态 = PO / supplier 页面现在的样子；当前形态离目标远的（如 Drawer 编辑型），走「形态跃迁」路径补齐。
+- **施工权威在** `references/templates.md`（S1–S12）。本文件只留盘点、红线和验收；进入施工步再读模板，不在盘点阶段整篇加载。类名（`xx-detail`/`xx-list`）按目标页面替换，字段/按钮/动作集按目标页面业务替换，布局骨架与机制逐字保留。
+- **贴合目标项目现状**：表格技术、共享组件、基建按目标项目实际情况选型（见「表格技术选型」与「基建依赖与降级表」），不强制引入新依赖。
+- **溯源**：模板沉淀自本仓库采购订单（purchaseOrder）与供应商（supplier）页面改造（2026-10，本仓库 commit `e6f33915` 起系列迭代），经该系列多轮 L1 plan 全套断言实测验证。
+- **样板参照（可选）**：若目标分支存在已改造的样板页（`frontend/src/views/purchase/purchaseOrder/index.vue`、`detail.vue`、`shared.ts`（列表/详情共享常量）、`frontend/src/views/baseData/supplier/detail.vue`），可对照参考；**样板不存在或与模板冲突时，以 `references/templates.md` 为准并向用户报告差异**——禁止拿旧版样板推翻模板。
+- **回填义务（防漂移）**：本仓库样板页面后续演进时须回填 `references/templates.md` 对应片段；发现脱节，先记 `workflow/papercuts.md` 一行，不当场顺手改。
+- **跨分支/跨仓库携带**：复制本文件和 `references/templates.md` 两份。只复制本文件没有施工模板。**权威源 = 本仓库这两份**，携出副本不回流、漂移自负。**本仓库例外**：宿主适配目录（`.trae/`、`.opencode/`、`.codebuddy/`）按仓库纪律只放指针壳，禁放全文副本。
+- 本 skill 是**改造模式知识 + 硬约束层**：在本仓库使用时仍走项目工作流（L1 plan → 确认门 → build → UI 实测 → 关单）；其他仓库按「基建依赖与降级表」处理。
+
+## 第 0 步：形态盘点（强制，跳过即违规）
+
+1. 读目标页面 `index.vue` / `detail.vue`（如有）/ Drawer 组件（如有），盘点：
+   - **目标形态**（看业务结构，不看当前实现）：实体有明细行/关联单据 → **A 主子表**；实体纯表单无明细 → **B 纯表单**；只读无编辑无详情 → **D 纯查询**。
+   - **当前形态**：已有覆盖层详情组件 → 布局重排路径；Drawer 编辑（新建/编辑/查看在 Drawer 里）→ **形态跃迁路径**（见「形态跃迁施工流程」）。
+   - **表格技术现状**：目标项目是否已用 AG Grid（查 package.json / 既有页面 import）；未用 → 列入 **S12 一次性接入项**（随本次改造一起做，非可选决策）。
+   - **基建现状**：对照「基建依赖与降级表」逐项探测。
+2. 产出**改造项清单 + 选型/降级决策 + 存疑点**（如该页无批量操作、明细表是否值得 tab 化）→ AskUserQuestion 让用户确认范围。
+3. 用户确认后才立 plan 进入施工。**禁止跳过盘点直接套模板。**
+
+### 形态适配矩阵（目标形态 × 当前形态）
+
+| 目标形态                    | 业务特征                  | 当前已是覆盖层详情                                                        | 当前是 Drawer 型（跃迁）                                               |
+| --------------------------- | ------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **A 主子表**（PO 型）       | 实体有明细行（±关联单据） | 直接套 D-1~D-7 全套                                                       | 走「形态跃迁施工流程」→ 新建 detail.vue（A 骨架）+ Drawer 业务迁移下线 |
+| **B 纯表单**（supplier 型） | 实体纯表单无明细          | 直接套 D-1 + D-8；**禁套上下半区 tab / 高度模型**（无明细表，套了必翻车） | 走「形态跃迁施工流程」→ 新建 detail.vue（B 骨架）+ Drawer 业务迁移下线 |
+| **D 纯查询**                | 只读列表，无编辑无详情    | 不适用                                                                    | 不适用——只做列表页改造                                                     |
+
+> **混合形态**（查看 = 覆盖层、编辑/新增 = Drawer，如 4d363c4 基线的采购订单页）：按「当前是 Drawer 型」列判——走跃迁路径；既有查看态覆盖层内容一并搬进新 detail.vue 的查看态（D-2 只读栅格承载），旧查看态代码随原 Drawer 同批下线——同实体禁双详情入口并存。
+
+## 表格技术（列表页，统一 AG Grid）
+
+**效果口径（断言门按此验收）**：
+1. 列序 = 定义顺序（复选框 → 序号 → 单号…），视觉顺序零错乱
+2. 列宽自适应：主干文本列吃剩余宽度、列头零 `...` 截断；窄列固定宽
+3. 行操作 hover 浮层替代固定操作列（省下 280px 级别的操作列宽）
+4. 行滚动收在表体内部，外层零滚动条；分页页脚钉底
+
+**选型规则**：
+- 目标项目**已用 AG Grid** → 直接按 S5-S8 施工。
+- 目标项目**未用 AG Grid** → **直接按 S12 一次性接入**（依赖 + license 注入 + 全局视觉 + 中文 locale + 页面级组件模板全套迁移），随后按 S5-S8 施工。**禁止用 a-table 模拟等效效果**——效果不可达且引入第二套表格口径，属错误路径。
+
+## 列表页改造模式（4 式）
+
+| #   | 模式              | 要点                                                                                                                                                |
+| --- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L-1 | 工具栏左右分组    | 左组单据级（新增/导出）；右组复选框联动的批量按钮，`margin-left:auto` 靠右 + 竖线分隔；批量资格三处同源（行内按钮/批量集合/复选框可选，守卫同口径） |
+| L-2 | 列序与列宽自适应  | 效果口径见「表格技术」；实现见 S7（连续前导列可左固定，其余不 pin；主干列 flex、窄列固定宽）                                                         |
+| L-3 | 行操作 hover 浮层 | 删固定操作列；不满足资格的动作不渲染，零动作行不浮出；浮层跟随 hover 行右缘内侧；DOM 事件委托（S6）+ 动作集（S12）；确认用居中 Modal.confirm           |
+| L-4 | 高度链与分页页脚  | 根容器钉满内容区 + 表格卡 `flex:1` 吃剩余 + 页脚钉底；行滚动收在 grid 内部，外层不出滚动条（S8）                                                    |
+
+## 详情页改造模式（8 式，目标形态 A 全套 / 目标形态 B 仅第 1、8 式）
+
+| #   | 模式               | 要点                                                                                                                                                                                                     |
+| --- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| D-1 | 顶行合并           | `DetailPageHeader`：返回按钮 + `#meta`（单号/状态 tag）+ `#extra`（操作按钮）同一行；禁独立操作行                                                                                                        |
+| D-2 | 上半区基础信息 tab | 查看态 `a-descriptions` → `a-form` 只读栅格（`info-grid`），与编辑态统一：4 列（`lg:6`）/ label 左右 106px / 紧凑间距 / 长文本 span 24                                                                   |
+| D-3 | 下半区多 tab       | 明细表 + 关联单据各一 tab（`v-model:activeKey`）；原标题块删除（tab 名承载）                                                                                                                             |
+| D-4 | 高度模型           | 上半区纯内容高（`flex: 0 0 auto`）；下半区 `min-height: calc(var(--layer-h)/2)` + `grow` 撑满；`--layer-h` 由 ResizeObserver 注入（CSS 百分比在可撑开容器下失效）；超一屏由外层 `.detail-layer` 滚动承接 |
+| D-5 | 工具栏并入页签行   | 明细操作按钮放 `#rightExtra` 的 `.tab-extra-row`（自带 flex 容器）+ 最大化按钮；省一整行                                                                                                                 |
+| D-6 | 下半区最大化       | `is-maximized`（下半 `height:auto` 吃满）+ 上半 `is-hidden-by-max`（display:none）；开关两态共用，关闭详情自动重置                                                                                       |
+| D-7 | 表内滚动           | 外层无滚动条；flex 链逐层 `min-height:0` 直到 `.ant-table-content`（`overflow-y:auto !important`）                                                                                                       |
+| D-8 | 纯表单型钉底       | 目标形态 B：`.detail-layer` 白底（`--bg-container`）+ 详情根 `min-height:100%; flex column` + 卡片 `flex:1` + footer `sticky bottom:0` 白底不透明                                                        |
+
+## 形态跃迁施工流程（Drawer 型 → 覆盖层详情，新建/查看/编辑整模块上覆盖层）
+
+跃迁触发：目标页面当前是 Drawer 编辑型，且用户要求的改造范围含新建/查看/编辑（整模块改造默认含）。
+
+1. **读透 Drawer 现状**：表单字段绑定、校验规则、保存流（API 调用与成功后行为）、查看态内容源——跃迁是**搬家不是重写**，业务逻辑逐字迁移。混合形态下「查看态内容源」= index.vue 里既有覆盖层查看态代码（它就是查看态的搬家源，同样读透搬走）。
+2. **新建 `detail.vue`**：目标形态 A 用 S1-S4 骨架（上下半区 tab），目标形态 B 用 S9 骨架（表单卡 + sticky footer）+ S11 头部组件；三态入口 `props.mode: 'create' | 'edit' | 'view'`：
+   - 编辑/新增态：字段绑定、rules、保存 handler、API import 从 Drawer **逐字搬移**（禁顺手改语义）；提交载荷与原 Drawer 逐字段一致。
+   - 查看态：只读栅格（D-2）承载原查看内容；操作按钮进 `#extra`。
+3. **列表页挂覆盖层**：`.detail-layer` + Transition（S8 CSS）；原「新增 / 编辑 / 查看」入口全部改为开覆盖层（`detailState = { mode, id }`）。
+4. **原 Drawer 下线删除**：同一实体的编辑能力**禁双入口并存**——Drawer 残留会造成两处提交载荷日后漂移（对账死角）；确认无其他引用后整段删除。混合形态下既有查看态覆盖层代码同批下线（查看能力已并入新 detail.vue，禁双详情入口）。
+5. **对账红线**：跃迁不改契约——API 契约、查询参数、提交载荷逐字段不变；保存成功后的列表刷新与关闭行为对齐既有口径；资格判据三处同源口径不变。
+
+## 基建依赖与降级表（开工前探测，按可用性裁剪改造项）
+
+| 改造能力                     | 依赖                                                                                                                       | 目标仓库缺失时的降级                                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| D-1~D-7 详情页布局           | 无外部依赖（antd 即可）                                                                                                    | 无需降级，全量适用                                                                                                                           |
+| D-8 纯表单型钉底             | 无外部依赖                                                                                                                 | 无需降级                                                                                                                                     |
+| DetailPageHeader 共享头部    | 该组件存在                                                                                                                 | 缺失则按 S11 全文直接创建（69 行，必填 props + 插槽契约）                                                                                               |
+| L-1 工具栏分组 / L-4 高度链  | 无外部依赖                                                                                                                 | 无需降级                                                                                                                                     |
+| L-2/L-3 表格效果（AG Grid）  | `ag-grid-community` + `ag-grid-vue3` + `ag-grid-enterprise`（本仓库 ^35.3.1）；中文 locale 模块；license key（运行时注入） | **直接接入，无降级**：按 S12 全套迁移（依赖 / main.ts 注册 / license 注入机制 / 全局视觉 CSS / locale / 组件模板），装好配置好与样板效果一致 |
+| 行操作按钮组                 | 页面级 RowActions 类组件                                                                                                   | 按目标页面动作集自建按钮组（「动作资格判据同源」原则不变）                                                                                   |
+| 全套断言实测                 | 本仓库 `scripts/verify/e2e/harness.mjs`（技术单源）                                                                        | 缺失则按 S10 骨架自写最小 node CDP 探针——断言清单一项不减                                                                                    |
+| 工作流（plan/确认门/关单）   | 本仓库 `AGENTS.md` + `workflow/`                                                                                           | 底线条款兜住：改造方案经用户确认再动手 + 全套断言实测 + 证据截图留档                                                                         |
+| 提示守卫 / URL 态 / 其他规范 | 本仓库 `utils/notify.ts` / `utils/listUrlQuery.ts` 等                                                                      | 守目标仓库既有口径；本仓库口径（G-3/LP-1/BC-1/BC-2/BC-4）仅在对应基建在场时强制                                                              |
+
+**AG Grid 接入**（目标项目未用时）：完整接入步骤与全部配置模板见 S12——依赖三件套、main.ts 模块注册、license key 运行时注入机制（key 明文不入仓库）、全局视觉 CSS、中文 locale 获取方式、CustomTooltip / 空态 / 单号链接 / 行动作集组件模板，装好配置好与样板效果一致。
+
+## 触发条件
+
+- 用户要求改造某业务功能页面/模块（列表页、新建/查看/编辑、布局重排），或「对齐采购订单页面的样子」。
+
+## 施工模板
+
+S1–S12 在 `references/templates.md`。进入施工步时再读，不要在盘点阶段整篇加载。
+盘点、硬红线、验证门以本文件为准。模板与样板页面源码冲突时，以模板为准，先记 `workflow/papercuts.md`，不当场改模板。
+
+## antd 陷阱清单（施工前必读，每条均已实证）
+
+| #   | 陷阱                                                                                                                 | 解法（见 S 片段）                                                                      |
+| --- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| T1  | a-spin 根实为 `.ant-spin-nested-loading`，组件上的自定义 class **不落根**——按类选择全链失效、整区塌 0                | 按 antd 结构类选择（S1）                                                               |
+| T2  | `.ant-tabs-extra-content` 默认非 flex，块级按钮组把最大化按钮挤到第二行                                              | `#rightExtra` 里自带 `.tab-extra-row` flex 容器（S1/S4）                               |
+| T3  | tabs 内容区默认非 flex，链断一层整区塌 0                                                                             | `.ant-tabs / content-holder / content / tabpane-active` 逐层 `min-height:0`（S1）      |
+| T4  | 容器高度不定（可撑开）时子项百分比 min-height/height 解析失效                                                        | ResizeObserver 注入 `--layer-h` 变量，绝对像素计算（S2）                               |
+| T5  | a-table 内部另有一层 spin（wrapper > spin > container > table），漏一层 `.ant-table` 的 flex:1 就失效、表体压成 0 高 | 表内滚动链把 `.ant-table-wrapper` 与两层 spin 全补进（S1）                           |
+| T6  | antd 纯横向滚动会内联 `overflow-y:hidden`，表体纵滚失效                                                              | `.ant-table-content` 上 `overflow-y:auto !important`（S1）                             |
+| T7  | `a-row :gutter` 负外边距（每侧 -4px）撑出面板横向空白                                                                | 上半区容器显式 `overflow:hidden`（S1）                                                 |
+| T8  | antd 小屏（<576px）让 label 撑满整行变竖排                                                                           | label 强制横排口径 `width/flex/padding !important`（S1）                               |
+| T9  | a-tag 胶囊被「基准归零拉满」铺满整列变整列色块                                                                       | 拉满选择器 `:not(.ant-tag)` 排除（S1）                                                 |
+| T10 | AG Grid `rowMouseEnter` 回调实测不触发（真实/synthetic 鼠标均无）                                                    | DOM 事件委托 mouseover/mouseout（S6）                                               |
+| T11 | AG Grid pinned-left 容器渲染在最前，把中间列或操作列 pin 到左侧会打乱「复选框→序号→单号」视觉顺序                     | 只左固定定义顺序上的连续前导列；多选列走 selectionColumnDef；其余不 pin（S7）          |
+| T12 | Chrome 对浮层移出 DOM 后露出的行补发 mouseover，进详情后浮层重建遮挡                                                 | 浮层显示入口处详情层打开即熔断（S6）                                                   |
+| T13 | 浮层不在滚动视口内、卡片 overflow:hidden，滚轮落空                                                                   | 浮层 wheel 手动转发 `.ag-body-viewport`（S6）                                          |
+| T14 | 全局样式 `.ant-card-body` 带 `!important` 内边距，页脚钉底失效                                                       | 高特异性 `padding:0 !important` 覆盖（S8）                                             |
+| T15 | Vue reactive Proxy 干扰 AG Grid 内部状态                                                                             | gridOptions 用普通对象（S7）                                                            |
+| T16 | 详情页明细 a-table 不设 `:scroll.y` 时表体默认不纵滚，「表内滚动」静默失效                                           | CSS 强制链 `.ant-table-content { overflow-y:auto !important }`（S1）                  |
+
+## 硬红线（禁改清单，违反即返工）
+
+1. **不动覆盖层机制**：`.detail-layer` 的 `position:absolute; inset:0; overflow-y:auto` 与「列表实例保持存活」口径逐字保留。
+2. **契约零改动**：API 契约、查询参数、提交载荷逐字段不变（形态跃迁 = 搬家不重写，迁移前后提交载荷逐字段对账）；行内按钮/批量资格/复选框可选三处同源同步；后端错误消息原样展示。
+3. **禁双编辑入口**：跃迁完成后原 Drawer 必须下线删除——同实体编辑能力双入口并存会造成提交载荷日后漂移（对账死角）。
+4. **两态同链必测**：查看态与编辑/新增态共用高度链时，**两态都必须实测**，只测一态不算过。
+5. **最小改动**：只动目标模块文件 + 共享组件插槽级增量；禁顺手重构、禁格式化无关代码、禁修无关 Lint 警告；模板搬移时 handler 逐字不动。
+6. **机制注释同步**：改布局须同步更新文件内既有机制注释（高度模型/链路注释），防注释与代码脱节；本文片段内机制注释落地时逐字保留。
+7. **提示与列表态**：目标仓库若有统一提示守卫 / URL 态管理等基建则一律走基建（如本仓库 `utils/notify.ts` / `utils/listUrlQuery.ts`），禁绕过。
+
+## 验证门（全套断言实测，缺项不算过）
+
+静态门：`cd frontend && npm run build`（或目标仓库等价的严格类型构建门）。
+
+UI 实测：headless Chrome CDP 探针——本仓库技术细节 import `scripts/verify/e2e/harness.mjs` 单源（勿手写等价逻辑）；目标仓库无此基建时按 S10 骨架自写。一次性探针放**仓库外 gitignore 区**（本仓库 `tmp/e2e/`），截图证据留档；只读探针不留脏数据（跃迁保存流测试产生的数据按响应 ID 精确删除）；结束关净自启进程。按改造项勾选对应断言组：
+
+**详情页（目标形态 A，D-1~D-7 全改时）**
+- [ ] 高度链：上半区纯内容高（高视口 `topH < half`、`clientH == scrollH`）；下半区 `≥ half`；`top+bottom == layerH`（整页填满无底部空白）
+- [ ] 外层无滚动条：`.detail-layer` `scrollHeight == clientHeight`（常规视口）
+- [ ] 表内滚动承接：表体 `overflowY == auto`；压缩视口（如 1440×520）反向分支——上半纯内容撑开、下半锁半屏、外层滚动接管
+- [ ] 最大化态：上半 `display:none`、`bottomH == layerH` 铺满，还原后模型复原
+- [ ] 工具栏并位：按钮组中心线与 tab nav 中心线对齐、页签行未增高、按钮在最大化按钮左侧且位于 `.ant-tabs-extra-content` 内
+- [ ] 两态回归：查看态 + 编辑/新增态同口径各跑一遍；编辑态操作按钮功能不回归（handler 绑定不变）
+- [ ] tab 切换：各 tab 表头在场、切换互不串数据
+
+**详情页（目标形态 B，D-1/D-8）**
+- [ ] 白底铺满（含列表不足一屏场景）；按钮贴底（不足一屏）+ sticky 钉底（超一屏滚动两位置 footer.bottom 恒定、不透明）
+
+**形态跃迁专项（Drawer → 覆盖层）**
+- [ ] 三态可进：列表「新增」→ create 态覆盖层、「编辑」→ edit 态、「查看」→ view 态，渲染正确
+- [ ] 保存流不回归：新建/编辑保存的提交载荷与原 Drawer 逐字段一致（网络报文对比）；保存成功后列表刷新与关闭行为对齐既有口径
+- [ ] 原 Drawer 已下线：页面无残留 Drawer 挂载、旧入口按钮不触发旧交互
+- [ ] 表单校验不回归：必填项校验、后端 400 消息原样展示同原口径
+
+**列表页（L-1~L-4）**
+- [ ] 列序：复选框 → 序号 → 单号…视觉顺序即定义顺序（左固定只发生在这段连续前导列上），列头无 `...` 截断
+- [ ] 工具栏：左组/右组各在一侧、批量按钮 disabled 与选中联动、计数正确
+- [ ] hover 浮层：有可用动作的行 hover 浮出且垂直居中该行、零动作行不浮出、换行刷新、移出延时隐藏、浮层自身 hover 不消失、浮层滚轮可滚表格、进详情层后浮层不重建（真实鼠标路径）
+- [ ] 行滚动收在 grid 内部，外层与页面无滚动条；分页页脚钉底
+
+**通用**
+- [ ] 控制台异常清零（AG Grid license key 已注入则无试用 banner；未注入时 banner 属已知噪声，排除）
+- [ ] 关闭详情层后列表状态回归（滚动位置/筛选不丢——覆盖层机制验证）
+
+探针产出 `N PASS / M FAIL` 汇总与证据截图路径，回填任务验收标准后走关单流程（本仓库 `.agents/commands/stages.md` Test 章）。
+
+## 执行流程总览
+
+```
+触发本 skill
+  → 第 0 步：读目标页面盘点（目标形态 A/B/D × 当前形态）+ AG Grid 接入探测 + 基建降级探测
+  → 产出改造项清单 + 降级/存疑决策 → 用户确认范围（AskUserQuestion）
+  → 立 plan（本仓库 L1；跃迁含新建组件时改动清单按文件逐列）→ 方案确认门
+  → 施工前读 references/templates.md（S1–S12）
+  → 施工：
+      表格基建：目标项目未用 AG Grid → 先按 S12 一次性接入（依赖/license/视觉/locale/组件模板）
+      列表页：S5-S8（工具栏分组 / 列序列宽 / hover 浮层 / 高度链页脚）
+      详情页：已是覆盖层 → S1-S4 重排；Drawer 型 → 「形态跃迁施工流程」+ S1-S4/S9 骨架新建
+      → 陷阱清单 T1-T16 逐条自查
+  → 验证门：构建静态门 + 全套断言实测（含跃迁专项）→ PASS/FAIL 汇总 + 截图证据
+  → 关单（回填验收证据）；样板/skill 漂移记 papercuts（本仓库）
+```