知识镜像驱动的 JavaScript 规范瘦身:解析 modern-web-guidance-src 的 LCD Mirror 与纪律指南工作流
知识镜像驱动的 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 四步流程
- 生成知识镜像:让 Gemini、Claude、Codex 三个模型各自输出“我认为什么是常识”,再取交集得到统一镜像;
- 执行反向过滤(Agent 任务):把目标指南与统一镜像做严格的
A - B比对; - 外科式编辑:只做精准删改,保持文件结构;
- 验证:做“对比检查”(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)失败即降级、不生成残缺镜像。 三个来源镜像任意一个生成失败(进程 spawn 报错或退出码非 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 把任务定义为“专家技术编辑”,输出三份镜像的交集,并给出四条规则:
- 严格包含:只收录在三份来源中都被清晰、一致表达的最佳实践、语法、API 与准则;
- 严格排除:只要某个概念/API/规则在任意一份来源中缺失或未被原生理解,就不得进入 LCD 镜像。文档给出了一个具体例子:如果
Object.groupBy()只出现在 Claude 镜像而 Gemini 镜像没覆盖,就整体排除; - 严谨取证:极其字面化,不合成、不外推、不假设任何未被三份文档同时明确佐证的知识;
- 格式:使用清晰标题与项目符号,符合标准技术写作惯例。
对照仓库中的实际文件可以印证这条规则确实生效: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 整洁代码原则
镜像给出七条:
- 命名:描述性、意图直白(
daysSinceLogin而非d;布尔量读起来像提问:isReady); - 提前返回:用守卫子句压平嵌套;
- 不可变:避免修改对象、数组与函数参数,返回新实例;
- 纯函数:相同输入产生相同输出、无副作用;
- 魔法数字:把字面量提为具名常量;
- 单一职责:模块与函数只聚焦一件事;
- 注释:解释“为什么”,而不是“做什么”。
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”。
由此得到的实操建议是:
- 把终版(第 168 行之后)作为唯一裁剪基线,前两版只作为“演进说明”阅读;
- 对语义被压缩的条目(尤其 Promise 组合器),回到
claude_mirror.md/codex_mirror.md交叉确认; - 若未来重新生成镜像,注意
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 需保持干净)。这与镜像属于内部维护资产、不应混入分发内容的定位相互呼应。
十、边界与常见误用
- 它是下限,不是风格圣经。 交集必然剔除“某些模型会做但并非全都默认会做”的内容,所以 LCD 镜像比任何单一来源都更短、更保守。用它当“语言规范”会觉得缺项,用它当“裁剪基线”才是正确姿势。
- 它不是仓库的编码规范。 仓库层面的 PR 拆分、枚举单一来源、
config.environment复用等强制要求,全部在 project-coding-standards 中,不在镜像里。 - 生成过程依赖外部 CLI 与高权限参数。 默认参数包含
--dangerously-skip-permissions,只能在受控环境中运行;且该流程不联网取证,结果完全取决于模型权重中的既有知识。 - 不要把“镜像里没有”直接等同于“可以删”。 这正是保留检查要拦住的错误;
Object.groupBy()的例子已经说明了这一点。 - 交集文档需要版本意识。
mirror.md里的三份文档并存,若下游工具或人工只截取前半部分,会拿到语义更弱、条目更旧的基线。
十一、结语:把“模型已经会的”从指南里拿掉
这套流程的价值可以概括成一句话:指南应该只写模型不会的东西。mirror.md 用三模型取交集的方式,把“JavaScript 常识”的边界画得尽可能保守——const/let、箭头函数、解构与展开、?. 与 ??、数组函数式方法、async/await 与四个 Promise 组合器、ESM、# 私有字段、fetch + AbortSignal、structuredClone、Intl、观察者、cause、守卫子句与纯函数,这些都被判定为“不需要教”。
于是纪律指南的写作重点自然上移到真正的差分知识:本项目的约定、容易反直觉的坑、性能与安全约束、以及像 {{ GUIDE_REF(...) }} 这样的路由结构。掌握这套“生成镜像 → 严格 A−B → 外科式编辑 → 双项验证”的闭环后,你可以把同一方法复制到任何一门学科:换掉 <discipline_name>,剩下的规则完全通用。