知识镜像驱动的 JavaScript 规范瘦身:解析 modern-web-guidance-src 的 LCD Mirror 与纪律指南工作流

原创2026-11-12 21:07:023,502 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

知识镜像驱动的 JavaScript 规范瘦身:解析 modern-web-guidance-src 的 LCD Mirror 与纪律指南工作流

本文围绕 modern-web-guidance-src 仓库中的 JavaScript LCD(Lowest Common Denominator,最小公共分母)镜像文档展开,逐节解析这份“模型公认常识清单”到底约定了哪些语言特性、API 与整洁代码原则,并说明它在项目内部如何被生成、如何被用来给 discipline guide(纪律指南)做“反向知识过滤”。读完之后,你将能够独立复现镜像生成流水线,并用这份清单对一份指南做可审计、可复现的裁剪。

一、这份文档在仓库中的定位

mirror.md 不是面向开发者的使用手册,而是仓库内部维护流程中的一个中间产物。它的标题写得很明确:JavaScript Unified Lowest Common Denominator (LCD) Mirror ——“三个独立来源镜像中一致出现的标准 JavaScript 知识与最佳实践的交集”。

配套的流程定义在 project-discipline-guides 技能说明 中。该文档先定义了什么是纪律指南:

  • 纪律指南是某个类别或领域的“概念导航枢纽”,用于建立编码 Agent 的心智模型,并通过 {{ GUIDE_REF("guide-slug") }} 宏路由到更细粒度的用例子指南;
  • 一个指南只要被注册进 src/core/guide-validation.ts 的 DISCIPLINE_GUIDES 集合,就被识别为纪律指南。该集合包含两类:类别根指南(如 guides/css/css/guide.md)与命名式横向指南(如 cpp-on-the-web、passkeys、web-components);
  • 纪律指南豁免 description 与 web-feature-ids 的 frontmatter 强制要求,并在 src/build/audit-build.ts 中被报告为 bundled core guides。

而本流程要解决的问题是“差分知识重构”(Differential Knowledge Refactor):让纪律指南保持精简、上下文高效,并且只保留相对现代 AI 模型原生知识而言真正增量的内容。

值得注意的是构建审计的分类逻辑。见 src/build/audit-build.ts:任何以 .agents/skills/ 开头的文件都被标记为 INTERNAL_AGENT(内部仓库维护类技能),与 EXPOSED_DIST(对外分发)、BUNDLED_GUIDE(打包核心指南)明确隔离。也就是说,mirrors/javascript/*.md 这类知识镜像属于内部维护资产,不会被当作对外发布的指南内容。

二、知识镜像与反向过滤器:先看清流水线

整个工作流被概括为“逆知识过滤器”(The Inverse Knowledge Filter),目标是激进地“削”掉目标指南中模型原生就掌握的内容。

2.1 四步流程

  1. 生成知识镜像:让 Gemini、Claude、Codex 三个模型各自输出“我认为什么是常识”,再取交集得到统一镜像;
  2. 执行反向过滤(Agent 任务):把目标指南与统一镜像做严格的 A - B 比对;
  3. 外科式编辑:只做精准删改,保持文件结构;
  4. 验证:做“对比检查”(Contrast Check)与“保留检查”(Preservation Check)。

2.2 生成命令与产物布局

技能文档给出的入口命令是:

# Ensure that model setup is configured (instructions are in the top level readme)
node .agents/skills/project-discipline-guides/scripts/generate_mirrors.ts <discipline_name>

执行后会在 mirrors/ 目录下生成四个文件:

文件 生成者 说明
mirrors/<discipline>/gemini_mirror.md Gemini CLI 临时来源镜像
mirrors/<discipline>/claude_mirror.md Claude CLI 临时来源镜像
mirrors/<discipline>/codex_mirror.md Codex CLI 临时来源镜像
mirrors/<discipline>/mirror.md Gemini CLI(取交集) 统一冗余镜像

技能文档特别用 [!IMPORTANT] 强调:必须确保统一冗余镜像成功生成,因为它代表三个来源模型的“精确数学交集”,可以防止误删并降低上下文开销。

当前仓库中已实际存在这套产物,目录为 .agents/skills/project-discipline-guides/mirrors/javascript/,包含三个来源镜像与 mirror.md,其中 codex_mirror.md 最长(近 2000 行),gemini_mirror.md 最短(91 行)——这也直观说明“不同模型对常识的覆盖面差异巨大”,取交集因此是必要的保守化手段。

2.3 脚本实现细节(源码级)

镜像生成脚本见 generate_mirrors.ts。几个关键实现点:

(1)原生 .env 加载。 脚本首行判断 process.loadEnvFile 是否存在(Node 20.6.0+ 能力),存在则尝试加载,失败则静默忽略:

if (typeof process.loadEnvFile === 'function') {
  try {
    process.loadEnvFile();
  } catch (e) {
    // .env might not exist, that's fine
  }
}

这与仓库整体运行环境一致:package.json 中 engines.node 要求 >=22.18.0,因为仓库大量脚本直接以 Node 原生方式执行 .ts。

(2)CLI 的三种调用形态与可覆盖的二进制路径。 脚本内置了一张 clis 映射表:

CLI ID 环境变量 默认二进制 参数构造
gemini ANTIGRAVITY_CLI_BIN agy -p <prompt> --dangerously-skip-permissions
claude CLAUDE_CODE_CLI_BIN claude -p <prompt> --dangerously-skip-permissions --output-format text
codex CODEX_CLI_BIN codex exec <prompt>

也就是说,如果某台机器上的 CLI 可执行文件名不同(例如包装脚本),可以通过环境变量覆盖,而不必改脚本。需要注意 --dangerously-skip-permissions 属于高权限免交互参数,只在可信、隔离的维护环境中使用才合理。

(3)提示词与执行逻辑分离。 脚本不内嵌长提示词,而是从 ../mirror_prompt.md 读取模板,并用正则做占位符替换:

const promptTemplate = fs.readFileSync(promptTemplatePath, 'utf8');
const prompt = promptTemplate.replace(/\{\{\s*discipline\s*\}\}/g, discipline);

这与仓库 编码规范技能 中“不要把长提示词塞进运行时文件,应放入专用的 *-prompts.ts 或模板模块”的要求同源。

(4)目录名归一化。 纪律名会被转成小写作为目录名,所以传 JavaScript 会落到 mirrors/javascript/:

const disciplineDir = path.join(mirrorsDir, discipline.toLowerCase());

(5)失败即降级、不生成残缺镜像。 三个来源镜像任意一个生成失败(进程 spaw​​n 报错或退出码非 0),脚本只会警告并跳过写文件;而在交集阶段:

if (!geminiResult || !claudeResult || !codexResult) {
  console.warn('⚠️ Skipping Redundancy Mirror generation because not all three mirrors were successfully generated.');
  return;
}

这是一个重要的工程约束:交集缺一不可,因为二源交集会放宽标准,导致后续裁剪过度。

(6)交集提示词的三处注入。 交集模板会替换 {{ discipline }}、{{ gemini_mirror }}、{{ claude_mirror }}、{{ codex_mirror }} 四个占位符,然后复用 callCli(..., 'gemini') 执行取交集。

三、两段提示词的约束:为什么这份镜像“保守”

3.1 来源镜像提示词

mirror_prompt.md 要求模型“基于训练数据与内在知识”生成一份全面的标准最佳实践指南,并明确聚焦四点:现代语言特性(即便刚发布,只要已进入各大浏览器)、可渐进增强的新特性、标准库/API 用法、通用整洁代码原则。

其中最关键的两条是:

  • 这份指南将作为“Redundancy Mirror”用于裁剪项目专属技能文件,所以要尽可能穷尽,“不要为了简洁而省略,不要排优先级”;
  • 答案必须严格来自内在知识:不得使用任何工具(读文件、列目录、执行 shell、联网搜索),不得读取或引用工作区、仓库中的任何本地文件。

这条“禁用工具”的约束是整套方法的基石:只有模型在不看仓库的情况下写出来的东西,才能代表它“默认就会那么做”的常识;一旦允许它读项目文档,镜像就被污染了。

3.2 交集提示词

intersection_prompt.md 把任务定义为“专家技术编辑”,输出三份镜像的交集,并给出四条规则:

  1. 严格包含:只收录在三份来源中都被清晰、一致表达的最佳实践、语法、API 与准则;
  2. 严格排除:只要某个概念/API/规则在任意一份来源中缺失或未被原生理解,就不得进入 LCD 镜像。文档给出了一个具体例子:如果 Object.groupBy() 只出现在 Claude 镜像而 Gemini 镜像没覆盖,就整体排除;
  3. 严谨取证:极其字面化,不合成、不外推、不假设任何未被三份文档同时明确佐证的知识;
  4. 格式:使用清晰标题与项目符号,符合标准技术写作惯例。

对照仓库中的实际文件可以印证这条规则确实生效:Object.groupBy() 只出现在 gemini_mirror.md 里,而最终的 mirror.md 全篇没有 groupBy;同理,findLast/findLastIndex、toReversed/toSpliced、Object.is()、Map/Set、生成器、正则命名捕获组等,虽然出现在某个来源镜像中,却没有出现在最终 LCD 镜像中——这正是一次严格交集的结果。

四、逐节解析:LCD 镜像到底约定了什么

以下按 mirror.md 的八个章节展开。原文的每一条规则都被保留并补充了可运行示例与工程解释。

4.1 变量与作用域

四条规则:

  • 默认 const,仅在必须重赋值时用 let;
  • 禁止 var:函数作用域 + 变量提升会带来反直觉行为;
  • 利用块级作用域:let/const 是块级声明,可避免意外的全局泄漏与提升相关问题。
const MAX_RETRIES = 3;   // 绑定不可变(注意:对象内容仍可变更)
let attempts = 0;        // 需要重赋值
attempts += 1;

if (attempts > 1) {
  const label = `第 ${attempts} 次重试`; // 作用域被限制在该块内
}
// label 在这里不可访问

工程含义:把变量声明在最窄的块里,能显著减少“某个状态被远处代码改写”的排查成本。镜像没有涉及 TDZ(暂时性死区)、const 只防重绑定不防内容变更等细节——这些属于来源镜像的加餐内容(见 claude_mirror.md 第 1 节),在 LCD 层面被明确剔除。

4.2 函数与现代语法

镜像列出的六组能力:

能力 规则 示例
箭头函数 用于回调;需要保留词法 this 时使用 items.map((item) => item.id)
函数声明 顶层逻辑,或确实需要提升时 function parseConfig(input) {}
默认参数 在签名中给默认值,替代函数体内的条件兜底 function fn(param = value) {}
剩余参数 用 ...args 以数组形式捕获不定参数 function sum(...nums) {}
解构 从对象/数组取值,也适用于函数参数 const { key } = object;
展开运算 浅拷贝或合并对象与数组 const merged = { ...a, ...b };
模板字符串 字符串插值与多行字符串 `Hello, ${name}`
// 默认参数 + 解构参数 + 剩余参数
function createRequest({ method = 'GET', headers = {} } = {}, ...tags) {
  return { method, headers, tags };
}

// 箭头函数保留词法 this,适合回调
const ids = users.map((user) => user.id);

两个容易踩的边界(来自仓库实践语义,非镜像原文):

  • 默认参数只对 undefined 生效,传 null 不会触发默认值;
  • 箭头函数没有自己的 this/arguments,不能作为构造函数使用。

因此“用 function 声明承载顶层逻辑”这条规则不是风格偏好,而是对提升语义与 this 绑定的显式选择。

4.3 对象与数组

字面量增强

const name = 'Ada';
const key = 'email';

const user = {
  name,                 // 简写属性:键名与变量名一致
  [key]: 'ada@example.com', // 计算属性名:动态键
};

安全访问与默认值

  • 可选链 ?.:安全访问深层属性,如 user?.profile?.id;
  • 空值合并 ??:仅在 null / undefined 时回退,避免 || 把 0、''、false 也当作缺失。
const city = user?.address?.city;
const limit = options.limit ?? 20;   // limit 为 0 时不会回退
const label = input || 'Untitled';   // 所有假值都会回退,需谨慎

镜像明确把 ?? 与 || 的差异写进了规则,这是很实际的“反 AI 默认偏好”约束:模型很容易顺手写 ||,但在配置对象、分页参数、数值型输入上会埋下半错。

对象静态方法与数组方法

Object.keys(obj);
Object.values(obj);
Object.entries(obj);
Object.fromEntries(entries);            // 从键值对数组重建对象

arr.forEach(fn);                        // 迭代 + 副作用
arr.map(fn);                            // 一对一转换
arr.filter(fn);                         // 筛选
arr.reduce(fn, init);                   // 聚合
arr.find(fn); arr.findIndex(fn);        // 首个匹配 / 其下标
arr.some(fn); arr.every(fn);            // 谓词判断
arr.includes(value);                    // 成员判断
arr.flat(); arr.flatMap(fn);            // 展平
arr.at(-1);                             // 相对索引(负数从末尾数)

at(-1) 取代 arr[arr.length - 1]、includes() 取代 indexOf(...) !== -1,都是“可读性即正确性”的典型替换:前者消除了手写下标越界的可能,后者消除了 -1 哨兵值的隐式约定。

4.4 异步编程

镜像把异步收敛为三点:用 async/await 与 Promise 组织控制流;用 try/catch 管理失败;四个 Promise 组合器按语义选用。

组合器 镜像表述 实践语义
Promise.all() 全部兑现才继续 任一拒绝即整体拒绝(快速失败)
Promise.allSettled() 无论结果如何都等全部结束 永不拒绝,返回每个结果的状态
Promise.any() 返回第一个兑现的 Promise 全部拒绝时以 AggregateError 拒绝
Promise.race() 返回第一个敲定(fulfilled 或 rejected)的 Promise 谁先敲定就取谁
try {
  const [user, posts] = await Promise.all([fetchUser(id), fetchPosts(id)]);
  return { user, posts };
} catch (err) {
  console.error('加载失败', err);
  throw err;
}

这里需要指出一个文档层面的细节:mirror.md 的最终版把 Promise.all() 压缩成“Continues if all fulfill”,相比前两版“Fails fast if any promise rejects”损失了“拒绝”这一半语义。来源镜像的表述更准确(例如 claude_mirror.md 注释为 “All succeed or first rejection”)。阅读这类自动生成的交集文档时,凡是语义被压缩的条目,都应回到来源镜像确认——这也是下文“版本差异”一节的动因之一。

另一个值得强调的实践是“不要用 forEach 跑异步”:forEach 会丢弃回调返回的 Promise,导致你无法等待完成。需要并发就用 Promise.all(arr.map(...)),需要顺序就用 for...of + await。

4.5 类与模块

// named export 优先
export function parse(input) { /* ... */ }
export const VERSION = '1.0.0';

// 动态导入用于懒加载 / 代码分割
const { renderChart } = await import('./chart.js');

// class + 私有字段 + 继承
class Counter {
  #count = 0;                  // 真正私有,由引擎强制

  constructor(start = 0) {
    this.#count = start;
  }

  increment() {
    this.#count += 1;
    return this;
  }
}

class Timer extends Counter {
  constructor() {
    super(0);
  }
}

镜像保留了 import() 动态导入,但没有保留 static {} 静态初始化块、顶层 await、Symbol.iterator 自定义迭代等——它们在来源镜像中出现过,却未被三源同时覆盖。# 私有字段则被保留,因为它是“约定私有(_prefix)”的强制版替代,属于防止越界访问的结构性收益。

4.6 标准 Web API

这一节是镜像中信息密度最高的部分,覆盖七组 API。

(1)Fetch 与状态码

const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

规则只有一句但极其重要:fetch 只在网络层失败时拒绝,4xx/5xx 不会自动抛出,必须显式检查 response.ok。

(2)取消:AbortController / AbortSignal

const controller = new AbortController();
fetch(url, { signal: controller.signal });
controller.abort();                    // 取消请求

(3)URL 处理

const url = new URL('/search', 'https://example.com');
url.searchParams.set('q', 'hello');
const params = new URLSearchParams(location.search);
params.get('id');

用 URL/URLSearchParams 而不是手工拼字符串,可自动处理编码与分隔符。

(4)深拷贝:structuredClone()

const copy = structuredClone(value);

它是 JSON.parse(JSON.stringify(x)) 的原生替代,能保留 Map/Set/Date 等结构化类型并处理循环引用。

(5)国际化:Intl

镜像点名的三个构造器是 DateTimeFormat、NumberFormat、RelativeTimeFormat:

new Intl.DateTimeFormat('zh-CN', { dateStyle: 'medium' }).format(date);
new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' }).format(1234.5);
new Intl.RelativeTimeFormat('zh-CN', { numeric: 'auto' }).format(-3, 'day');

(6)DOM 选择与交互

document.querySelector('.btn');
document.querySelectorAll('li');
el.classList.toggle('open', isOpen);
el.dataset.userId;                              // 对应 data-user-id
el.addEventListener('click', onClick, { once: true, signal: controller.signal });

classList 与 dataset 被明确点名,是因为它们替代了手工拼接 className 字符串、或反复 getAttribute('data-...') 的低可维护写法。

(7)观察者

new IntersectionObserver(callback).observe(el);   // 可见性
new ResizeObserver(callback).observe(el);         // 尺寸变化

这两个观察者对应仓库里大量 UI 用例(滚动触发、响应式组件)的底层机制。

4.7 错误处理与调试

class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

try {
  await save(payload);
} catch (err) {
  throw new Error('保存失败', { cause: err });   // 保留原始错误链
}

规则三条:扩展 Error 创建领域专用错误类型;重新抛出时用 cause 保留原始错误;控制台方面最终版只保留 console.log 与 console.error。

相比来源镜像,console.table/group/time/warn 在最终版被裁掉了——这恰好说明取交集时“三源都写了”才保留的严格性,也提示读者:这份 LCD 镜像不是调试图鉴,只是下限清单。

4.8 整洁代码原则

镜像给出七条:

  1. 命名:描述性、意图直白(daysSinceLogin 而非 d;布尔量读起来像提问:isReady);
  2. 提前返回:用守卫子句压平嵌套;
  3. 不可变:避免修改对象、数组与函数参数,返回新实例;
  4. 纯函数:相同输入产生相同输出、无副作用;
  5. 魔法数字:把字面量提为具名常量;
  6. 单一职责:模块与函数只聚焦一件事;
  7. 注释:解释“为什么”,而不是“做什么”。
const MAX_LOGIN_ATTEMPTS = 5;   // 具名常量替代魔法数字

function getLabel(value) {      // 守卫子句
  if (value == null) return '';
  if (value === '') return 'Empty';
  return String(value);
}

这七条与 project-coding-standards 中“单一职责、绝不削弱共享 tsconfig、禁止 eval”等要求方向一致,但层次不同:LCD 镜像是语言层下限,项目技能是仓库层约束,二者不可互相替代。

五、三个版本并存:如何正确读取 mirror.md

一个容易被忽略的事实是:mirror.md 内部包含三份前后递进的文档,分别以如下标题开头:

位置 标题 定位
第 1 行 # JavaScript Unified Lowest Common Denominator (LCD) Mirror 初版交集
第 82 行 ... Mirror (Revised) 修订版,标注“严格排除任一来源缺失的特性”
第 168 行 ... Mirror (Final) 终版,标注“绝对字面交集,只包含三源都明确佐证的内容”

三版之间的差异可以归纳为几类:

  • 持续收窄的调试手段:初版与修订版列 warn/table/group/time,终版只剩 log 与 error;
  • 逐步补齐的现代能力:修订版新增了动态 import()、命名导出优先、Intl.RelativeTimeFormat、“魔法数字提为常量”、“单一职责”等条目,终版继承;
  • 表述被压缩导致语义走弱:Promise.all() 从“fails fast if any rejects”变成“Continues if all fulfill”。

由此得到的实操建议是:

  1. 把终版(第 168 行之后)作为唯一裁剪基线,前两版只作为“演进说明”阅读;
  2. 对语义被压缩的条目(尤其 Promise 组合器),回到 claude_mirror.md / codex_mirror.md 交叉确认;
  3. 若未来重新生成镜像,注意 Gemini 同时承担“来源镜像生成”和“交集计算”两职责,其输出风格会影响交集措辞——所以要保留三份来源镜像以供追溯。

六、反向过滤器的正确用法:四条硬约束

技能文档对“怎么裁”给出了四条非常具体的行为约束,值得逐条落地。

(1)严格 A − B 比对。 只有当某条规则在冗余镜像中被“完整且清晰覆盖”时,才允许从目标指南删除。

(2)禁止主观自证。 不要凭“我本来就会这么写”去裁剪,只能依据冗余镜像中的字面内容。如果概念不在镜像里,它就留在目标指南里。

(3)禁止整条项目符号盲删。 这是最容易犯的错。示例:目标指南里可能有一条

- 使用 const/let 替代 var,并用 #privateField 代替 _prefix 约定私有。

前半句在镜像 §1 中被完全覆盖,可以从目标指南里删掉;但 # 私有字段替代 _prefix 属于约定选择(镜像只写了“用 # 做私有字段”,没有“替代 _prefix”这一约定表述),因此必须拆开、只裁前半句。

(4)保留差分知识。 需要留下的通常是四类:

  • 抵消 AI 默认偏差的规则(如“不要用 || 做默认值”);
  • 在多个合法方案中选定的约定;
  • 进阶性能模式、安全约束、启发式规则(模型知道但默认输出里常省略);
  • 项目架构相关的强制要求。

这一条在 CSS 纪律指南 里有一个绝佳对照:它的第 1 节“Be allergic to knowledge duplication”要求优先使用 currentColor、inherit、em、cqw/cqi 等内建约定而不是自定义变量。这些属于项目级的取舍哲学,即使模型“知道”currentColor 是什么,也未必默认这样写,因此绝不能被当成常识裁掉。

同时,技能文档用 [!WARNING] 划了边界:本次重构唯一目标是削减冗余常识,不要顺手新增规则、改逻辑或引入无关准则,务必让改动小而可评审。

七、验证环节:两个必须做的检查

技能文档要求编辑后自检两项:

  • 对比检查(Contrast Check):确认新指南里没有任何规则仍然出现在冗余镜像中;
  • 保留检查(Preservation Check):确认项目专属规则、行为引导与特定进阶 API(文档举例 Object.groupBy())没有被误删。

保留检查特别提到 Object.groupBy() 很有意思:它恰恰是交集阶段被排除的 API。这说明“镜像里没有”不等于“目标指南里就该删”——如果项目确实面向支持该 API 的环境并在指南中推荐它,它属于差分知识,必须保留。两个方向都要检查,才不会把“保守的交集”误用成“激进的删除令”。

八、仓库源码中的实践印证

镜像描述的是“模型默认应当会做”的事,那么仓库自身是否真的这样做?下面是若干可核对的实现点(属于抽样印证,不构成全仓统计结论):

规则 源码位置 用法
Object.hasOwn() 替代 hasOwnProperty src/analyzing/scanners/dom-scanner.ts 属性存在性判断,避免原型链污染
非变异排序 toSorted() src/ci/sync-pipeline-issue.ts 对特性行排序时不改动原数组
Promise.allSettled() src/dashboard/utils.js 等待一批运行任务全部结束,不因个别失败中断
structuredClone() src/harness/upload-suite.test.ts 测试中深拷贝清单快照
AbortSignal.timeout() src/grading/target-server.ts 健康检查请求超时控制
Error 的 cause src/harness/public/allowlist.ts 包装 JSON 解析错误并保留原始错误

这些点位说明:仓库在真实代码路径上采用了与镜像一致的原生 API 选择(Object.hasOwn、toSorted、structuredClone、AbortSignal.timeout、cause)。同时它们也是很好的“规则落地样板”——比在指南里写一句“请使用 structuredClone”更能让读者理解适用场景。

九、复现与校验:命令清单

9.1 生成镜像

# 先按顶层 README 完成模型 CLI 的配置(或通过环境变量指向可执行文件)
export ANTIGRAVITY_CLI_BIN=/path/to/agy
export CLAUDE_CODE_CLI_BIN=/path/to/claude
export CODEX_CLI_BIN=/path/to/codex

node .agents/skills/project-discipline-guides/scripts/generate_mirrors.ts JavaScript

脚本会依次执行三个 CLI,然后在三者全部成功时调用 Gemini 做交集,最终写出 mirrors/javascript/mirror.md。任一来源失败时,只跳过对应文件并明确警告;此时不要把残缺结果当作裁剪基线。

9.2 校验与提交前检查

按仓库 编码规范技能 的分层门禁执行:

pnpm typecheck && pnpm lint     # 快速开发检查
pnpm run preflight              # 构建 + 类型检查 + Lint + 全工作区单测
pnpm run test:e2e               # 仅改动 src/dashboard/ 时必跑(需先 pnpm run setup:playwright)

技能改动还要求额外验证打包链路:

pnpm run publish-skills --dry-run

此外规范要求“干净工作树”:构建不得产生未提交的副作用或未跟踪产物(git status 需保持干净)。这与镜像属于内部维护资产、不应混入分发内容的定位相互呼应。

十、边界与常见误用

  1. 它是下限,不是风格圣经。 交集必然剔除“某些模型会做但并非全都默认会做”的内容,所以 LCD 镜像比任何单一来源都更短、更保守。用它当“语言规范”会觉得缺项,用它当“裁剪基线”才是正确姿势。
  2. 它不是仓库的编码规范。 仓库层面的 PR 拆分、枚举单一来源、config.environment 复用等强制要求,全部在 project-coding-standards 中,不在镜像里。
  3. 生成过程依赖外部 CLI 与高权限参数。 默认参数包含 --dangerously-skip-permissions,只能在受控环境中运行;且该流程不联网取证,结果完全取决于模型权重中的既有知识。
  4. 不要把“镜像里没有”直接等同于“可以删”。 这正是保留检查要拦住的错误;Object.groupBy() 的例子已经说明了这一点。
  5. 交集文档需要版本意识。 mirror.md 里的三份文档并存,若下游工具或人工只截取前半部分,会拿到语义更弱、条目更旧的基线。

十一、结语:把“模型已经会的”从指南里拿掉

这套流程的价值可以概括成一句话:指南应该只写模型不会的东西。mirror.md 用三模型取交集的方式,把“JavaScript 常识”的边界画得尽可能保守——const/let、箭头函数、解构与展开、?. 与 ??、数组函数式方法、async/await 与四个 Promise 组合器、ESM、# 私有字段、fetch + AbortSignal、structuredClone、Intl、观察者、cause、守卫子句与纯函数,这些都被判定为“不需要教”。

于是纪律指南的写作重点自然上移到真正的差分知识:本项目的约定、容易反直觉的坑、性能与安全约束、以及像 {{ GUIDE_REF(...) }} 这样的路由结构。掌握这套“生成镜像 → 严格 A−B → 外科式编辑 → 双项验证”的闭环后,你可以把同一方法复制到任何一门学科:换掉 <discipline_name>,剩下的规则完全通用。

登录后查看全文
modern-web-guidance-src