# Modernize Ecmascript > 当 Agent 编写或修改 JavaScript、TypeScript，用户要求按指定环境、输出版本、ES20xx 或具体语法编写代码，询问某项 ECMAScript 语法、标准内置 API 或提案能否采用，或者要求审查仓库中可简化、可现代化的写法时，应使用本 Skill。围绕目标文件真实经过的解析器、转换器和输出目标判断新语法能否安全采用，并按需读取 TC39 Atlas 的提案阶段、官方仓库、polyfill 与实现线索。 - Skill: `bosens-china/modernize-ecmascript` (Agent Skill, multi-file: 15 files) - Install (CLI): `npx skillmds@latest add bosens-china/modernize-ecmascript` - Raw SKILL.md: https://api.skillmd.com/api/skills/bosens-china/modernize-ecmascript/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: bosens-China (https://skillmd.com/u/bosens-china) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bosens-china/modernize-ecmascript --- # 现代化 ECMAScript 围绕源码转换链选择能减少代码或明确意图，且不改变可观察行为的 ECMAScript 能力。不要根据框架名称、单一工具版本或一个笼统的“ES20xx 支持”直接得出兼容性结论。 ## 选择一种工作模式 按任务意图依次判断，只选择一种模式： 1. 存在审查、批量寻找或仓库级简化意图时，选择**显式代码审查**；用户提供的环境和 ES 约束作为审查条件。 2. 否则，用户明确提供环境、输出版本、ES 版本，或者指定具体语法或 API 时，选择**用户定向编写或能力咨询**。 3. 否则，编写或修改 JavaScript、TypeScript 时选择**日常语法辅助**。 手动指定本 Skill 只强制加载工作流，不覆盖更具体的任务意图。 ### 日常语法辅助 - 只关注当前任务中新写、正在修改或已经触及的代码区域。 - 不扫描未触及代码，不自动纳入任务开始前已有的 Git 工作区改动。 - 先判断本次改动是否会产生或改变运行时代码。只涉及类型注解、接口、类型别名、泛型或 `.d.ts` 等编译后擦除内容，且任务不涉及构建配置或运行时行为时，静默结束现代化判断并继续原任务。 - 对运行时代码先在当前改动区域识别能减少代码、明确意图或避免手写辅助逻辑的可信候选。没有候选时直接继续原任务；不要仅因 Skill 已触发就读取年度文件、`llms.txt` 或完整转换链。 - 形成候选后再从目标文件定位实际解析器、转换器和输出目标，只自动采用能被解析并安全转换的 Stage 4 语法。 - 语法会保留在产物中时，只有存在明确的目标运行时支持证据才采用。 - 区分纯语法和运行时敏感能力。只要能力依赖新的标准内置 API、全局对象、协议、polyfill 或 shim，即使表面上包含新语法，也按运行时敏感能力处理；日常模式默认不自动采用。 - 用户要求最小改动、只修当前问题或不要重构时，可以让本次新写代码采用安全语法，但不为现代化额外改写既有代码。 - 转换链、输出目标或必要运行时证据缺失、冲突或含糊时，静默停止现代化判断并继续原任务。不要询问用户，也不要在最终汇报中重新说明跳过原因。 - 不为了展示新语法而改写相邻旧代码。 ### 用户定向编写或能力咨询 - 以用户给出的范围、目标环境、输出版本、ES 版本和具体能力要求为主。 - 用户只询问某项能力能否使用时，只调查并回答，不修改代码，也不扩大为仓库级审查；只有用户明确要求编写、应用或改造时才修改请求范围内的代码。 - 完成安全的自动发现后，目标运行时、输出目标或消费者约束仍然缺失且确实影响结论时，把相关缺失项合并为一次询问，不猜测也不套用日常模式的静默规则。 - 验证实际解析器和转换器能否处理用户要求的语法，不用仓库默认值静默覆盖用户要求。 - 要求与工具链冲突时，展示证据和可行选项，请用户确认调整语法、升级或配置转换器、提高输出基线，或者放弃该能力。 - 用户明确要求标准内置 API 时，额外验证目标运行时或已配置的 polyfill。需要新增 polyfill、shim、转换插件或依赖时，说明来源、影响和替代方案并取得确认。 - 用户可以明确批准兼容性、构建配置、依赖或实验能力的变更；确认只授权所选方案，不把无法解析或无法转换的能力变成可用能力。 - 不因定向编写自动扩大为仓库级审查。 ### 显式代码审查 - 扫描用户指定的文件、包或仓库范围，不受当前修改区域限制。 - 先定位旧语法、手写辅助逻辑和其他待验证候选，再发现相关源码转换链和输出目标并过滤安全能力。 - 环境、输出目标或消费者范围缺失且确实影响结论时，完成所有安全发现后集中询问用户。 - 在问题中给出已检测环境、确切不确定项、可行选项、各自影响和推荐选择，不按候选逐次打断。 - 用户只要求审查时只输出分析；明确要求应用审查结果时再修改代码。 ## 按 ECMAScript 年份读取能力速览 用户指定一个或多个 ES 版本，或者询问某个版本新增了什么时，先读取对应年度文件。年度文件直接列出该版本的提案、当前 Stage、状态、作用摘要和线上 Markdown；不要为了查一个年份先加载全部提案。日常模式只有形成相关候选后才读取对应年度文件，不把年度摘要作为编码任务的预加载资料。 - [ES2027](./references/es2027.md) - [ES2026](./references/es2026.md) - [ES2025](./references/es2025.md) - [ES2024](./references/es2024.md) - [ES2023](./references/es2023.md) - [ES2022](./references/es2022.md) - [ES2021](./references/es2021.md) - [ES2020](./references/es2020.md) - [ES2019](./references/es2019.md) - [ES2018](./references/es2018.md) - [ES2017](./references/es2017.md) - [ES2016](./references/es2016.md) 年度文件是随仓库更新的快照。需要理解具体能力时，继续读取条目链接的线上提案 Markdown；需要确认最新提案集合、Stage、状态、版本，或者用户询问尚未进入标准的提案时，改读 `llms.txt`。年度文件和 Atlas 都不证明目标项目兼容。 ## 按需读取 TC39 Atlas 把 TC39 Atlas 作为提案阶段、状态、ECMAScript 版本、官方仓库、双语 README 和提案速览的入口： - 索引：`https://bosens-china.github.io/tc39-atlas/llms.txt` 除上面的年度查询外，先读取索引，使用其中的标题、阶段、状态、ES 版本和提案页链接定位能力。索引已提供链接时，不要自行拼接页面地址。 - 用户指定某项语法、API 或提案时，读取相关提案页面；用户指定 ES 版本时，先读年度文件，再按候选读取线上提案页面。 - 显式审查形成候选短名单后，只读取与候选相关的页面，不批量加载全部提案。 - 使用提案页中的官方仓库入口核对权威原始资料，并从提案描述中提取 polyfill、shim、转换插件、实现状态和用户态替代方案等线索。 - 把这些线索视为可能的实现路径，不视为目标项目已经安装、配置或兼容的证明。 - 提案没有列出 polyfill、插件或实现时，不推断它们一定不存在。 - 采用页面发现的依赖、polyfill、插件或实验实现前，检查其官方文档、版本和目标项目适配性，并按工作模式取得用户确认。 Atlas 描述规范成熟度和提案内容，不证明 TypeScript、转换器或运行时兼容性。 ## 定位源码转换链 从目标文件开始，只收集判断候选能力所需的最小充分证据： 日常模式先形成候选，再执行这里的定位；用户定向模式和显式审查按各自规则确定候选与调查范围。 1. 定位最近的包或 workspace，读取 `package.json`、锁文件、实际生产脚本和适用的 Agent 指令。 2. 跟随真实命令定位 TypeScript、Babel、SWC、esbuild、Rspack 或其他解析器与转换器配置，包括继承和目标包覆盖值。 3. 记录解析器能否理解候选语法、实际转换器、生产输出目标，以及候选语法会被降级还是保留。 4. 只有候选语法被保留、代码不经过转换器或候选是运行时 API 时，再读取相关 Node、浏览器、Edge、WebView、嵌入式平台或消费者基线。 Vite、Rsbuild、Next.js、tsdown 等框架和工具名称只用于发现真实命令与配置，不构成兼容性证明。不要维护或依赖静态框架兼容矩阵。 分别处理同一项目中的执行面： - 浏览器源码与构建配置可能分别由浏览器产物转换链和 Node.js 执行。 - SSR、服务端、Edge、Worker、测试和迁移脚本可能拥有不同转换器或运行时。 - Node.js 直接执行的代码没有语法降级步骤，目标 Node 版本就是保留语法的运行边界；当前主机版本只证明本地执行环境。 - Docker 多阶段构建需要区分构建阶段与最终运行阶段。 - 发布库和共享源码需要满足声明的消费者基线；多个消费者不一致时，日常模式跳过，显式审查集中询问范围。 ## 通过候选能力门槛 按候选逐项判断，不为整个项目计算一个虚假的“最高 ES 版本”： 1. **规范成熟度**：日常模式只采用 Stage 4。Stage 3 需要用户明确同意并提示实验风险；不为生产现代化推荐不活跃、已撤回或更低阶段提案。 2. **源码解析**：确认 TypeScript、Lint 解析器、测试转换器和生产转换器理解候选语法及其当前语义。 3. **语法转换**：确认生产转换器能把候选安全降级到实际输出目标，或者确认保留语法受到目标运行时支持。 4. **运行时补充**：标准内置 API 必须获得目标运行时原生支持或项目已配置 polyfill、shim 的证据；语法无法降级或会被保留时，必须获得目标运行时原生支持的证据。转换插件属于前两项解析与转换门槛，polyfill 不能让解析器理解语法。`target`、TypeScript `lib` 和提案中的 polyfill 链接都不能单独证明可用。 5. **行为等价**：核对异常、求值顺序、稀疏数组、迭代消费、异步时序和公开 API 等可观察行为。 6. **兼容性契约**：除非用户明确确认，否则不升级依赖、不添加 polyfill、不改变构建目标，也不提高 Node、浏览器或消费者基线。 独立描述源码能力和产物基线。例如“源码使用 ES2025 Stage 4 语法，由 esbuild 转换为 ES2020”，不要只说“启用 ES2025”。 ## 应用与验证 - 日常模式只修改当前任务新写、正在修改或已经触及的代码区域，不单独发送现代化计划；用户要求最小改动时，不把既有代码现代化作为附带修改。 - 用户定向编写按用户确认的范围和约束继续；纯能力咨询只回答，出现兼容性选择时先等待确认。 - 显式审查需要修改代码时，先汇报范围、转换链、输出目标、候选能力、Atlas 证据、排除项和基线变化，再开始编辑。 - 保留项目风格和公开行为，只在不写注释就难以理解兼容性决策时添加注释。 - 根据风险运行目标包已有的格式检查、类型检查、相关测试和生产构建。对于 monorepo，只验证受影响的消费者。 显式审查的修改前汇报使用以下结构： ```text ECMAScript 现代化已准备开始。 - 模式与范围：<工作模式、应用/包、代码范围> - 转换链：<解析器、转换器、输出目标> - 候选与依据： - 策略：<安全转换、原样保留、已批准的 polyfill> - 排除：<实验性、不兼容或行为不等价项> - 基线变更：<无，或用户已确认的变更> ``` 完成时汇报实际采用和跳过的能力、转换或保留策略、用户确认的契约变化以及验证结果。不要声称 Stage 4、类型检查成功或开发服务器运行成功能单独证明转换或运行时兼容性。