dart-tech-index 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smartyu1993
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# dart-tech-index
+
+A reference **skill** for ZCode / Claude that indexes Dart language features, core libraries (`dart:*`), and official tooling (analyzer / pub / devtools / dart format / FFI / JS interop / compiler) — indexed by Dart version, and **only the Stable ones**.
+
+> **IRON LAW** of this skill: never list Experimental / Preview features as "ready-to-use" to the user. A capability is included in `versions/*.md` if and only if it is Stable in that version — works out of the box, no `--enable-experiment` flag.
+
+Covers **Dart 3.0 through 3.12**.
+
+---
+
+## What this skill is for
+
+Trigger it whenever a user is starting or working in a Dart or Flutter project and asks any version-specific question:
+
+- "I'm on Dart 3.7, can I use wildcard variables?"
+- "What's new in Dart 3.10?"
+- "Which version added extension types?"
+- "I'm on Dart 3.3 — list every language feature I can use."
+- "How do dot shorthands work? Which Dart version do I need?"
+
+It triggers eagerly on any version-specific Dart question — even casual mentions like *"I'm on 3.7, can I use wildcard variables?"*.
+
+## Dart-specific modeling
+
+Two things make Dart different from Kotlin/Java, and this skill models both:
+
+1. **Versioned vs unversioned changes.** Versioned features require raising `environment.sdk` lower bound in `pubspec.yaml` (e.g. dot shorthands need `sdk: ^3.10`). Unversioned changes apply to all code after SDK upgrade regardless of lower bound (e.g. 3.0 sound null safety). Every language entry in the data tables is tagged accordingly, and the skill always tells users the `environment.sdk` requirement for versioned features.
+2. **Empty minors.** Not every Dart minor adds language features (3.1 / 3.5 / 3.9 / 3.11 are "empty" at the language level), but they may still ship tooling/library changes. Each minor gets a file for structural consistency.
+
+## Design principles
+
+1. **Only Stable is indexed.** A capability's "home-version" is the version where it became Stable — not where it was first introduced as Experimental/Preview.
+2. **Cancelled features are tracked too.** Macros (preview in 3.4, cancelled in 3.7) are flagged so the skill never recommends them.
+3. **Partial-Stable is explicitly annotated.** When a feature is mostly Stable but has preview subsets (e.g. JS interop model Stable in 3.5 while JNIgen/FFIgen remain preview), the exception is called out — never just labeled "Stable".
+4. **No `package:` ecosystem.** Only `dart:*` core libraries, the language, and official toolchains. Third-party pub packages (`package:flutter`, `package:riverpod`, etc.) evolve independently of the SDK version.
+
+## Layout
+
+```
+SKILL.md                                  # Query workflow + Iron Law + self-check
+versions/                                 # One file per Dart minor
+  3.0.md  ...  3.12.md
+references/
+  deprecation-and-evolution.md            # Deprecation map + Experimental→Stable tracker + versioned column
+  maintenance.md                          # Maintainer guide (writing/updating files, standard section structure)
+```
+
+## Install — and you're done
+
+This package is a **skill** (a markdown reference bundle), not a runtime library. Installing it copies the skill directly into your project's `.claude/skills/` directory, so it's immediately usable — no manual copy step.
+
+```bash
+npm install dart-tech-index
+```
+
+What happens on install:
+1. npm drops the package into `node_modules/dart-tech-index/`.
+2. The `postinstall` hook runs `init.js`, which copies `SKILL.md` + `versions/` + `references/` into **`<project>/.claude/skills/dart-tech-index/`**.
+3. Reload your agent — the skill is now available.
+
+The installer is **idempotent**: re-running it (or upgrading the package) overwrites in place, so `npm update dart-tech-index` keeps the skill current.
+
+### Manual / `npx` invocation
+
+If `postinstall` was skipped (e.g. `--ignore-scripts`, or pnpm/Yarn quirks), install the skill manually:
+
+```bash
+npx dart-tech-index                    # copies into ./.claude/skills/
+# or
+node ./node_modules/dart-tech-index/init.js
+```
+
+### Notes
+
+- **Project root resolution**: the installer uses `INIT_CWD` (set by npm to the directory where `npm install` was invoked), falling back to `npm_config_local_prefix`, then `process.cwd()`. So `npm install dart-tech-index` from your project root always lands the skill in that project's `.claude/skills/`.
+- **No README/LICENSE/package.json in the skill dir** — only the actual skill payload (`SKILL.md`, `versions/`, `references/`). Keeps the skills folder clean.
+
+## Data sources
+
+Each `versions/X.Y.md` cites its source URL at the top:
+
+- Dart release announcements: `https://dart.dev/blog/<slug>`
+- Language evolution reference: `https://dart.dev/guides/language/evolution`
+- Dart 3 migration guide: `https://dart.dev/dart-3-migration-guide`
+
+## License
+
+[MIT](./LICENSE) © smartyu1993

package/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: dart-tech-index
+description: Lookup what Dart language features, core libraries, and tooling (analyzer/pub/devtools/FFI/JS interop) are available AND stable for a given Dart version. Use whenever the user is starting or working in a Dart or Flutter project and asks "what can I use in Dart X.Y", "is Z available in version X.Y", "which version added feature Z", "what's new in Dart X.Y", or wants to know the configuration needed to use a Dart feature. Covers Dart from 3.0 to the latest indexed version. Trigger eagerly on any version-specific Dart question — even casual mentions like "I'm on 3.7, can I use wildcard variables?".
+allowed-tools: Read, Grep, Glob
+---
+
+# Dart 技术索引
+
+> **IRON LAW**：永远不要把 Experimental / Preview 特性当作"开箱即用"列给用户。
+> 一项能力被收录进 `versions/*.md` 当且仅当它在那个版本已 Stable——开箱即用、无需实验性 flag。
+> 如果不确定某特性是否 Stable，**先查** `references/deprecation-and-evolution.md` 的"实验性 → Stable 转正追踪表"。
+> 用户在版本 X 看到的每一项，都意味着"X 版本下能直接用"。
+> **若某能力主体 Stable 但含实验性子集，必须显式标注例外**，不能简单标"Stable"（见 Step 4 的 Partial Stable 标注规则）。
+
+## 何时触发本 skill
+
+只要用户的提问里出现"具体 Dart 版本"+"想用什么 / 能用什么"的语义，就应当触发。典型问法：
+
+- "我用 Dart 3.7，能不能用 wildcard variables？"
+- "Dart 3.10 有什么新特性？"
+- "extension types 哪个版本加的？"
+- "我是 Dart 3.3，给我列一下这个版本能用的全部语言特性"
+- "dot shorthand 怎么用？需要哪个 Dart 版本？"
+
+## 收录范围（重要边界）
+
+**只收录 Dart 语言 / 核心库（`dart:*`）/ 官方工具链（analyzer / pub / devtools / dart format / FFI / JS interop / 编译器）** 中已 Stable 的能力。
+
+**不收录**：
+- `package:` 生态（pub.dev 上的第三方包）。这些版本独立于 Dart SDK 演进，遇到相关问题应说明"这是 pub 包的能力，请查对应包的版本页"。
+- IDE 改进、纯文档变更、纯内部重构（除非影响兼容性）。
+
+## Dart 版本机制（关键差异，必读）
+
+Dart 与 Kotlin/Java 的版本模型不同，**必须理解以下两点才能正确查询**：
+
+1. **每个 minor（3.0, 3.1, 3.2, ...）都可能引入新语言特性，但不保证每个 minor 都有**——部分 minor 在语言层面是"空版本"（无新语法），但仍可能有工具/库变化。是否为空版本以 `dart.dev/guides/language/evolution` 为准，各版本文件顶部会明确声明。
+2. **patch 版本（如 3.7.1）只修 bug，不引入语言特性**。查询时一律归并到对应 minor。
+3. **改动分为 versioned 与 unversioned 两类**：
+   - **Versioned changes**：要用该特性，必须在 `pubspec.yaml` 把 `environment.sdk` 下界设到该版本。例：用 dot shorthand 需 `sdk: ^3.10.0`。
+   - **Unversioned changes**：升级 SDK 后对所有代码生效，与 `environment.sdk` 下界无关（例：3.0 的 sound null safety、3.9 的 null-safety 默认假设）。
+
+> 给用户答版本依赖时，versioned 特性必须说明 `environment.sdk` 下界要求；unversioned 特性只需说明"升级 SDK 后即生效"。
+
+## 数据布局
+
+```
+versions/        每个 minor 一个文件，命名 X.Y.md（当前已收录 3.0 ~ 3.12，新增版本时更新此行）
+references/
+  deprecation-and-evolution.md   # 弃用/替换关系 + 实验→Stable 转正追踪表 + 各能力首次 Stable 版本表
+  maintenance.md                  # 维护者指南（写文件、状态图例、决策流、标准章节结构）
+```
+
+**每个版本文件只列出"该 minor 相对前一 minor 新增的、且为 Stable / GA"的能力**。要让"截至某版本可用的全部能力"成立，需要把目标版本**及更早版本**的文件**累加阅读**，并参照 `references/deprecation-and-evolution.md` **剔除已被弃用 / 被取代的部分**。
+
+## 查找规则（按这个顺序执行）
+
+### 步骤 1：解析用户的版本号
+
+- 用户给的可能是 `3.7`、`3.7.0`、`3.7.2`、`dart 3.7`，统一规范化为 **minor 版本**：`3.7` / `3.7.0` / `3.7.1` / `3.7.2` → **3.7**（patch 版本归并到 minor）。
+- 用户给 `3` 或 "Dart 3" → 视作 **3.0**（最早版本，按需进一步澄清）。
+
+### 步骤 2：判断用户问的是"能用什么"还是"这个版本新加了什么"
+
+| 用户意图 | 处理方式 |
+|---|---|
+| "在 X 版本能用什么 / 能不能用 Z" | **累加视图**：读 X 及更早的全部版本文件，再剔除弃用项 |
+| "X 版本新增了什么 / What's new in X" | **增量视图**：只读 `versions/X.md` 一个文件 |
+| 不确定 / 模糊 | 默认走**累加视图**（这是开发时的主要诉求） |
+
+> 关于"能用 Z 吗"的回答边界：如果 Z 在用户版本里仍是实验性，直接答 **"不能用（开箱即用层面）"**，并说明它转正的版本。**不需要教用户怎么开实验性 flag**——本 skill 的立场是不鼓励使用实验性特性。
+
+### 步骤 3：执行查找
+
+**累加视图**（最常见）：
+
+1. 读 `versions/X.md` 以及 X 之前的所有版本文件
+2. 读 `references/deprecation-and-evolution.md`
+3. 合并：把所有版本里的特性拼起来；如果某特性在 X 之后被标记为弃用 / 取代，**从结果里剔除旧形式，只保留新形式**
+4. 对每条特性标注：来源版本号、状态（Stable）、所需配置（`environment.sdk` 下界 / pubspec 配置）
+
+**增量视图**：
+
+1. 只读 `versions/X.md`
+2. 直接列出该 minor 相对前一 minor 的新增内容
+
+**反向查询**（"Z 哪个版本加的 / Z 怎么用"）：
+
+1. 在 `versions/*.md` 里 grep 关键字 Z
+2. 找到最早**转 Stable** 的版本（不是首次实验性引入的版本）
+3. 如有 versioned 依赖，给出 `environment.sdk` 下界要求；**不**给实验性 flag 说明
+
+### 步骤 4：格式化输出
+
+回答用户时按下面的结构：
+
+```
+## Dart <版本> — <视图类型：可用能力 / 新增特性>
+
+### 语言特性
+- <特性名>（<来源版本>，Stable）— <一句话说明>（来源：announcing-dart-3-X）
+  - 配置：`environment.sdk: ^<版本>`（仅 versioned 特性需要）
+
+### 核心库
+- ...
+
+### 工具链 / 平台
+- ...
+
+### 已弃用，新代码不要用（仅当用户在累加视图中可能踩坑时给出）
+- ...
+```
+
+引用格式示例：
+- `Records`（3.0，Stable）— 聚合多值为单一返回值（来源：announcing-dart-3）
+- `Extension types`（3.3，Stable）— 零成本包装类型，`environment.sdk: ^3.3.0`（来源：new-in-dart-3-3）
+
+**Partial Stable 标注示例**（规则见 Iron Law）：
+- `JS interop 模型`（3.5，Stable — `dart:js_interop` + `package:web` 已 Stable，但 JNIgen/FFIgen 仍 preview）
+
+只在用户实际可能会踩到时才列"已弃用"段，避免信息过载。
+
+> 类别归组参考 `references/deprecation-and-evolution.md` 的"各能力首次 Stable 版本"表的"类别"列：**语言** → "语言特性"段；**核心库** → "核心库"段；**工具链/平台** → "工具链 / 平台"段。
+
+### 步骤 5：交付前自检 ⚠️ REQUIRED
+
+输出前逐条核对：
+- [ ] 累加视图下，是否读完了目标版本及更早的**全部** `versions/*.md`？
+- [ ] 是否对照了 `references/deprecation-and-evolution.md` 剔除弃用项？
+- [ ] 列出的每一项是否都是 Stable（无实验性 flag）？
+- [ ] 每项是否标注了来源版本号？
+- [ ] 涉及的内容是否限定在 Dart 语言 / `dart:*` / 官方工具链（没有混入 `package:` 生态）？
+- [ ] **Partial Stable 检查**：是否有主体 Stable 但含实验子集的能力？如有，是否显式标注了例外？
+- [ ] **versioned vs unversioned**：列出的语言特性如果是 versioned，是否标注了 `environment.sdk` 下界要求？
+- [ ] **反向查询特有**：返回的是特性"转 Stable 的版本"，不是"首次实验性引入的版本"？（例：答 `extension types` 应是 3.3）
+
+如有任何一项答"No"，重做对应步骤。
+
+## 关键约定
+
+1. **只收录 Stable / GA**。Experimental / Preview 一律**不进入** `versions/*.md`。一项能力的归属版本 = 它转正的那个版本。
+2. **同一能力若存在新旧两种形式**（如 `dart:html` vs `package:web`），只把新形式列在被查询版本的可用清单里，把旧形式放进 `references/deprecation-and-evolution.md`。
+3. **patch 版本（如 3.7.1）不单独建文件**。它们沿用相同 minor 的版本文件（3.7）。
+4. **minor 版本一律建文件**，即使该 minor 在语言层面是"空版本"（如 3.1/3.5/3.9/3.11）——因为它们可能有工具/库变化，且文件存在能保持结构一致、便于累加视图遍历。
+5. **数据来源 URL 必须在每个版本文件顶部标注**。优先用 `dart.dev/blog/<slug>`（release announcement），语言特性以 `dart.dev/guides/language/evolution` 交叉校验。
+6. **收录范围只含 Dart 语言 / `dart:*` / 官方工具链**。`package:` 生态版本独立于 Dart SDK 演进，不在本 skill 范围。
+7. **versioned vs unversioned 必须区分**：versioned 语言特性在文件里标注 `environment.sdk: ^X.Y.0`；unversioned 改动标注"升级 SDK 即生效，与 sdk 下界无关"。
+8. **版本文件的 Stable 正文段里出现 "experimental / preview / experimental flag / `--enable-experiment`" 字样，视为可疑信号**——很可能是该条目本不该收录，或需要按 partial-Stable 规则标注例外。写/校对版本文件时的完整清单见 `references/maintenance.md`。
+
+## Anti-patterns（不要做）
+
+- ❌ 把 Experimental / Preview 特性列为"可用"，哪怕它在用户版本里存在
+- ❌ 教用户用 `--enable-experiment=xxx` 开启实验特性（本 skill 立场：不鼓励）
+- ❌ 把 `package:` 生态包（如 `package:flutter`、`package:riverpod`）的版本混入 Dart SDK 版本判断
+- ❌ 在没确认用户版本号时就开始答题（先问）
+- ❌ 把 patch 版本（如 3.7.1）当成独立 minor 对待
+- ❌ 把特性"首次实验性引入的版本"当作它的归属版本（要用"转 Stable 的版本"）
+- ❌ 对 versioned 特性不告知 `environment.sdk` 下界要求就答"能用"
+- ❌ 推荐已 cancelled 的实验特性（如 macros，3.7 已叫停）
+
+## 维护
+
+新增版本文件、追踪实验特性转正等维护流程，见 `references/maintenance.md`。

package/init.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * dart-tech-index — skill installer
+ *
+ * Copies the skill assets (SKILL.md + versions/ + references/) from this
+ * package into `<projectRoot>/.claude/skills/dart-tech-index/`, so the
+ * skill is immediately usable by ZCode / Claude agents reading from that
+ * skills directory.
+ *
+ * Triggered in two ways:
+ *   1. Automatically via the npm `postinstall` script (run `npm install dart-tech-index`).
+ *   2. Manually via the `bin` entry: `npx dart-tech-index` or `node ./node_modules/dart-tech-index/init.js`.
+ *
+ * Project root resolution order:
+ *   - INIT_CWD              (set by npm to the dir where `npm install` was invoked)
+ *   - npm_config_local_prefix (npm's own anchor for the install root)
+ *   - process.cwd()         (fallback for `npx`/direct invocation)
+ *
+ * The install is idempotent — re-running overwrites in place, which is the
+ * desired behavior for upgrades.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const pkgRoot = __dirname;
+const projectRoot =
+  process.env.INIT_CWD ||
+  process.env.npm_config_local_prefix ||
+  process.cwd();
+const target = path.join(projectRoot, '.claude', 'skills', 'dart-tech-index');
+
+// Only the skill payload is copied — not README/LICENSE/package.json,
+// which don't belong in a skills directory.
+const ASSETS = ['SKILL.md', 'versions', 'references'];
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function main() {
+  // Guard: if SKILL.md isn't present, fail loudly rather than silently
+  // installing an empty skill directory.
+  if (!fs.existsSync(path.join(pkgRoot, 'SKILL.md'))) {
+    console.error('dart-tech-index: SKILL.md not found in package — aborting install.');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(target, { recursive: true });
+  for (const asset of ASSETS) {
+    const src = path.join(pkgRoot, asset);
+    if (fs.existsSync(src)) {
+      copyRecursive(src, path.join(target, asset));
+    }
+  }
+
+  console.log(`dart-tech-index: skill installed → ${target}`);
+  console.log('dart-tech-index: reload your agent to start using it.');
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "dart-tech-index",
+  "version": "0.1.0",
+  "description": "A ZCode/Claude skill that indexes Dart language features, core libraries, and tooling (analyzer/pub/devtools/FFI/JS interop) by Dart version — only Stable, never Experimental/Preview. Covers Dart 3.0 through 3.12. Install-and-use: copies itself into .claude/skills on install.",
+  "keywords": [
+    "dart",
+    "dart-version",
+    "dart-sdk",
+    "whats-new",
+    "language-features",
+    "dart-3",
+    "flutter",
+    "versioned",
+    "stable",
+    "reference",
+    "skill",
+    "claude-skill",
+    "zcode-skill",
+    "agent-skill",
+    "llm"
+  ],
+  "license": "MIT",
+  "author": "smartyu1993",
+  "homepage": "https://www.npmjs.com/package/dart-tech-index",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "bin": {
+    "dart-tech-index": "./init.js"
+  },
+  "scripts": {
+    "postinstall": "node ./init.js"
+  },
+  "files": [
+    "SKILL.md",
+    "versions/",
+    "references/",
+    "init.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "SKILL.md",
+  "zcode": {
+    "type": "skill",
+    "skill": "dart-tech-index"
+  }
+}

package/references/deprecation-and-evolution.md

@@ -0,0 +1,88 @@
+# Dart 特性演化、弃用与实验性追踪
+
+- **数据来源**: 汇总自 `dart.dev/blog/<slug>` 各版本公告 + `dart.dev/guides/language/evolution` + `dart.dev/dart-3-migration-guide`
+- **用途**:
+  - 查询时：判断某特性在某版本是否能"开箱即用"，并据此剔除弃用项
+  - 维护时：知道哪项实验特性转正时该补进哪个 `versions/*.md`（维护流程见 `maintenance.md`）
+
+> **收录原则**：`versions/*.md` 只收录 Stable。本文档的"实验性 → Stable 转正追踪表"列出**尚未收录**的实验特性。
+
+## 一、重大版本节点
+
+| 时期 | 状态 |
+|---|---|
+| Dart 2.x 及以前 | 不在本 skill 范围（收录从 3.0 起） |
+| **Dart 3.0**（2023-05）| 里程碑：强制 100% sound null safety；删除 2.12 之前语言版本支持。Records / Patterns / Class modifiers / Switch expressions / If-case 全部 Stable |
+| Dart 3.x 后续 minor | 每 minor 按需引入新语言特性（versioned）或行为变更（unversioned） |
+
+## 二、弃用 / 替换关系（已 Stable 的能力之间的新旧形式）
+
+| 旧形式 | 新形式 | 切换版本 | 备注 |
+|---|---|---|---|
+| `dart:html` / `dart:js` / `dart:js_util` / `package:js` | `dart:js_interop` + `package:web` | **3.3 引入 / 3.5 Stable** | 3.5 起旧 JS interop 库进入弃用路线，新代码用 `dart:js_interop` + `package:web` |
+| 可选命名参数默认值分隔符 `:` | `=` | **3.0** | 3.0 起用 `:` 是编译错误（例：`{int x = 0}` 而非 `{int x: 0}`） |
+| 不带 `mixin` 修饰符的 class 当 mixin 用 | `mixin class` 修饰符 | **3.0** | 3.0 起普通 class 不能再当 mixin 用 |
+| `continue` 指向任意 label | 只能指向 loop / switch member label | **3.0** | 3.0 起其它情况是编译错误 |
+| pre-2.12 语言版本（混合 null safety / unsound） | 100% sound null safety | **3.0** | 3.0 SDK 删除 2.12 之前语言版本支持 |
+| `package:lints` 2.x | `package:lints` 3.0 | **3.2** | core 集新增 6 条 lint，recommended 集新增 2 条 |
+| 旧 macros 路线（`@JsonCodable()` 等） | **已 cancelled**（无替代，回退到手写 / codegen 包） | **3.7 叫停** | 3.4 preview，3.7 正式宣告停止 |
+
+## 三、新代码不应再用的特性（即使能编译）
+
+- ❌ `dart:html` / `dart:js` / `dart:js_util` / `package:js`（→ `dart:js_interop` + `package:web`，3.5+）
+- ❌ 命名参数默认值用 `:`（→ `=`，3.0+）
+- ❌ 普通 class 当 mixin（→ `mixin class`，3.0+）
+- ❌ `continue` 指向非 loop / 非 switch label（3.0+ 编译错误）
+- ❌ 依赖 pre-2.12 语言版本（3.0 SDK 已删除支持）
+- ❌ 任何 macros 相关代码（3.7 已叫停，不会稳定）
+
+## 四、各能力首次 Stable 版本（已收录进 versions/*.md 的）
+
+> 类别：**语言** = 语言特性；**核心库** = `dart:*` 库；**工具链/平台** = analyzer/pub/devtools/format/FFI/JS interop/编译器等。
+
+| 能力 | 类别 | Stable 版本 | versioned? |
+|---|---|---|---|
+| Patterns（匹配与解构） | 语言 | 3.0 | versioned（sdk: ^3.0） |
+| Records（聚合类型） | 语言 | 3.0 | versioned（sdk: ^3.0） |
+| Class modifiers（`base`/`final`/`interface`/`mixin class`/`sealed`） | 语言 | 3.0 | versioned（sdk: ^3.0） |
+| Switch expressions | 语言 | 3.0 | versioned（sdk: ^3.0） |
+| If-case clauses | 语言 | 3.0 | versioned（sdk: ^3.0） |
+| 100% sound null safety | 语言 | 3.0 | unversioned（升级 SDK 即强制） |
+| Private final field promotion | 语言 | 3.2 | versioned（sdk: ^3.2） |
+| Extension types | 语言 | 3.3 | versioned（sdk: ^3.3） |
+| `dart:js_interop` 库 + `package:web` | 核心库 / 工具链 | 3.3（3.5 整体 Stable） | unversioned |
+| Flutter Web WasmGC 稳定 | 工具链/平台 | 3.4 | unversioned |
+| Digit separators | 语言 | 3.6 | versioned（sdk: ^3.6） |
+| Pub workspaces（monorepo） | 工具链/平台 | 3.6 | versioned（sdk: ^3.6） |
+| Wildcard variables（`_` 非绑定占位符） | 语言 | 3.7 | versioned（sdk: ^3.7） |
+| Dart format "tall" 样式 | 工具链/平台 | 3.7 | unversioned |
+| Null-aware elements（`?expr` 集合元素） | 语言 | 3.8 | versioned（sdk: ^3.8） |
+| 跨平台交叉编译（`dart compile exe --target-os`） | 工具链/平台 | 3.8 | unversioned |
+| Dart MCP Server（stable channel） | 工具链/平台 | 3.9 | unversioned |
+| Dot shorthands（`.foo` 上下文推断） | 语言 | 3.10 | versioned（sdk: ^3.10） |
+| Analyzer plugin system | 工具链/平台 | 3.10 | unversioned |
+| Pub workspaces glob（`workspace: - pkg/*`） | 工具链/平台 | 3.11 | versioned（sdk: ^3.11） |
+| Private named parameters | 语言 | 3.12 | versioned（sdk: ^3.12） |
+| Agentic Hot Reload | 工具链/平台 | 3.12 | unversioned |
+
+## 五、🎯 实验性 → Stable 转正追踪表（**尚未收录**进 versions/*.md）
+
+> 这些特性在 Dart 历史上**以 experimental / preview 形式存在**，但截至最新已收录版本（3.12）**仍未转正或仅部分转正**。它们**不会出现在任何 `versions/*.md` 正文段**。
+>
+> 当其中某项在版本 N 正式 Stable 后：
+> 1. 把它从这张表移除（或调整描述为"仅余 X 部分实验性"）
+> 2. 写入 `versions/N.md`
+> 3. 同时加入上方"各能力首次 Stable 版本"表
+
+| 特性 | 首次引入版本 | 当前状态（截至 3.12） | 转正条件 / 备注 |
+|---|---|---|---|
+| **Primary constructors** | 3.12（experimental preview） | experimental（`--enable-experiment=primary-constructors`） | 转 Stable 后写入对应版本文件 |
+| **Macros** | 3.4（preview） | **已 cancelled**（3.7 叫停） | **不会再转正**，新代码不要依赖；用 codegen 包替代 |
+| **JNIgen**（Java/Kotlin 互操作） | 3.5（preview） | preview（性能改进、支持 Java 异常和 Kotlin 顶级函数） | 转 Stable 后写入；旧 C-based 绑定已停用 |
+| **FFIgen**（Objective-C 互操作） | 3.5（preview） | preview（支持 protocols、NSString 等） | 转 Stable 后写入 |
+| **Genkit Dart**（full-stack AI 应用框架） | 3.12（preview） | preview | 转 Stable 后写入 |
+| **Cloud Functions for Firebase（Dart）** | 3.12（preview） | preview | 转 Stable 后写入 |
+
+## 六、状态判定与决策流
+
+见 `maintenance.md` 的"状态标记图例"与"判断是否收录的决策流"。本文件不再重复，避免维护时多处同步。

package/references/maintenance.md

@@ -0,0 +1,72 @@
+# 维护者指南
+
+本文件面向**维护 skill 数据的人**（不是查询时的模型）。SKILL.md 只保留了查询必需的规则，写文件、状态判定、转正流程等维护细节集中在这里。
+
+## 一、收录原则（写文件时遵守）
+
+**只收录 Stable / GA**。Experimental / Preview 一律不进入 `versions/*.md`。
+
+一项能力的归属版本 = **它转 Stable 的那个版本**，不是它首次出现的实验性版本。当某项实验性特性在版本 N 正式 Stable 后，才把它写入 `versions/N.md`。
+
+这是用户决定"开发时能不能直接用"的唯一依据——用户用 X 版本时，文件里列出的每一项都应当**开箱即用、无需 `--enable-experiment` 实验性 flag**。
+
+## 二、状态标记图例
+
+- **Stable / GA**：可直接使用，无需实验性 flag → **可收录进 versions/*.md**
+- **Experimental**：需 `--enable-experiment=xxx` flag → **不收录**，进 `deprecation-and-evolution.md` 的追踪表
+- **Preview**：官方放出但明确未稳定，可能调整或取消 → **不收录**，进追踪表
+- **Cancelled**：曾 preview 但已被官方叫停 → **不收录**，在追踪表标注"已 cancelled"以防误推荐
+
+## 三、判断"是否收录"的决策流
+
+```
+某项能力出现
+   │
+   ├─ 在该版本是 Stable / GA 吗？
+   │     ├─ 是 → 写入 versions/X.md
+   │     └─ 否（Experimental/Preview/Cancelled）→ 不收录，写入追踪表
+   │
+   └─ 用户用它需要 --enable-experiment 或 preview flag 吗？
+         ├─ 不需要 → 可收录
+         └─ 需要 → 不收录
+```
+
+## 四、写版本文件的清单
+
+每当 Dart 发布新的 **minor 版本**（如 3.13）：
+
+1. 在 `versions/` 新增 `3.13.md`，顶部写明发布日期与数据来源 URL（`https://dart.dev/blog/<slug>`）。
+2. 抓取官方 release announcement 博文，**只提取 Stable 条目**写入正文。语言特性以 `dart.dev/guides/language/evolution` 交叉校验。
+3. 把本版本仍为 experimental / preview 的特性写入"不收录（实验性 / preview，转正后再写）"段，注明预期转正版本或指向追踪表。
+4. 如果本版本没有新的实验性特性，也要写"不收录"段并标注"无"，保持结构一致。
+5. 如果某项历史实验特性在**本版本转正**：从 `deprecation-and-evolution.md` 的追踪表移除，写入本文件；同时把它加入"各能力首次 Stable 版本"表。
+6. **自查 1（开箱即用）**："这文件正文段里所有条目，用户**不**需要任何 `--enable-experiment` flag 就能直接用吗？" 如果不是，那一条不该出现在正文段。
+7. **自查 2（新 Stable vs 渐进改进）**："正文段的每一条，是否都是**在本版本首次 Stable 的能力**，而不是对已 Stable 能力的渐进改进？" 如果只是"改进已 Stable 的能力"（如某版本对早已 Stable 的 patterns 加边缘支持），不应单独作为一条 Stable 条目列出。处理方式：并入汇总条目并明确写"自 X.Y 起 Stable，本版本补充…"，或精简掉。
+8. **自查 3（章节结构一致）**：使用下面这套标准二级标题，按需出现的留下，无内容的省略。**不要**为单个版本自创二级标题。
+9. **自查 4（versioned vs unversioned）**：每条语言特性必须判定是 versioned 还是 unversioned。versioned 的标注 `environment.sdk: ^X.Y.0`；unversioned 的标注"升级 SDK 即生效"。
+
+### 标准章节结构
+
+```
+## 语言特性 (Language)        # 该版本新转 Stable 的语言能力（versioned 标注 sdk 下界）；unversioned 语言行为变更也放这里（标注"升级 SDK 即生效"）
+## 核心库 (Core libraries)    # 该版本新转 Stable 的 dart:* 库 API
+## 工具链 / 平台              # 旗下三级标题：### Analyzer / ### Pub / ### DevTools / ### Dart format / ### FFI / ### JS interop / ### 编译器 / ### Web / ### MCP
+## 破坏性变更                 # 仅在有破坏性变更时出现
+## 不收录（实验性 / preview，转正后再写）
+```
+
+> 工具能力统一放在 `## 工具链 / 平台` 下作为三级标题。`## 破坏性变更` 是允许的特殊段，仅在有破坏性变更时使用（3.0 这种大版本尤其重要）。
+>
+> `## 语言特性` 段可含 **unversioned 的语言行为变更**（如 3.9 的 null-safety 默认假设）——这类变更本质仍是"语言层面"的事，归在语言特性段合理，但必须标注"升级 SDK 即生效，与 `environment.sdk` 下界无关"以区别于 versioned 特性。
+
+## 五、弃用 / 替换关系维护
+
+新旧形式替换（如 `dart:html` → `package:web`）更新到 `deprecation-and-evolution.md` 的"弃用 / 替换关系"表，保持单一来源。在累加视图中，**只把新形式列在被查询版本的可用清单里**。
+
+## 六、定期校对（参考型 skill 最易随时间失效）
+
+- **每发布新的 minor 版本**（约每季度），抓取对应 `dart.dev/blog/<slug>`，更新 `versions/<新版本>.md`。
+- **每年至少一次**校对最新 1~2 个版本文件的发布日期与特性清单，对照官方 blog / evolution 页面核对。
+- 校对时优先关注"上一版还在追踪表里的实验特性"是否已转正——这是最容易遗漏的更新路径。
+- 特别留意 **cancelled 特性**（如 macros）：一旦官方叫停，立即在追踪表标注，避免向用户推荐。
+- 注意官方页面迁移：`dart.dev/guides/language/evolution` 已标 deprecated，未来可能完全移除，届时需改用 `github.com/dart-lang/sdk/CHANGELOG.md` 作为语言特性的交叉校验源。

package/versions/3.0.md

@@ -0,0 +1,78 @@
+# Dart 3.0
+
+- **发布日期**: 2023-05-10
+- **数据来源**: https://dart.dev/blog/announcing-dart-3 + https://dart.dev/dart-3-migration-guide + https://dart.dev/guides/language/evolution
+- **类型**: 重大版本（Major）
+
+> **里程碑**：Dart 3。强制 100% sound null safety；引入 Patterns / Records / Class modifiers / Switch expressions / If-case 五大 Stable 语言特性。本文件列出 3.0 **新转 Stable** 的能力。
+
+## 语言特性 (Language)
+
+### Patterns — Stable（versioned，`environment.sdk: ^3.0`）
+全新的语法类别，用于匹配与解构值。包含：
+- **逻辑运算符 patterns**：`&&`、`||`
+- **关系 patterns**：`==`、`!=`、`<`、`>`、`<=`、`>=`
+- **cast pattern**：`foo as int`
+- **null-check pattern**：`case int? x`（匹配非 null int 并绑定 x；为 null 时不匹配，不抛异常）
+- **null-assert pattern**：`case int! x`（匹配非 null int 并绑定 x；为 null 时抛异常）
+- **constant patterns**：字面量、枚举值等
+
+```dart
+switch (shape) {
+  case Square(area: final a): print('square, area $a');
+  case Circle(radius: final r): print('circle, radius $r');
+}
+```
+
+### Records — Stable（versioned，`environment.sdk: ^3.0`）
+聚合多个不同类型值为单一返回值的类型，无需声明类。
+
+```dart
+(String, int) userInfo() => ('Alice', 42);  // positional record
+({String name, int age}) mkPerson() => (name: 'Bob', age: 30);  // named record
+```
+
+### Class modifiers — Stable（versioned，`environment.sdk: ^3.0`）
+控制类 / mixin / 接口的使用方式：
+- `base class`：禁止被 `implements`，只允许 `extends`
+- `interface class`：禁止被 `extends`，只允许 `implements`
+- `final class`：禁止 `extends` 和 `implements`
+- `sealed class`：同库外的子类必须在同一库声明，配合 switch 穷尽性检查
+- `mixin class`：可同时作为 class 和 mixin 使用
+- `base mixin` / `mixin interface` 等
+
+### Switch expressions — Stable（versioned，`environment.sdk: ^3.0`）
+可用于表达式位置的多路分支：
+```dart
+final desc = switch (color) {
+  Color.red => 'red',
+  Color.green => 'green',
+  Color.blue => 'blue',
+};
+```
+
+### If-case clauses — Stable（versioned，`environment.sdk: ^3.0`）
+把值与 pattern 匹配的新的条件构造：
+```dart
+if (pair case (int x, int y)) print('two ints: $x, $y');
+```
+
+### 100% sound null safety — Stable（unversioned，升级 SDK 即强制）
+Dart 3 强制启用 sound null safety；**SDK 删除了对 2.12 之前语言版本的支持**。所有代码必须在 null-safe 下编译，无法关闭。
+
+## 工具链 / 平台
+
+### Web
+- WasmGC 路线启动（实验性，3.4 才稳定）
+
+## 破坏性变更
+
+- ❌ **没有 `mixin class` 修饰符的 class 声明不能再被当作 mixin使用**（需显式 `mixin class`）
+- ❌ **可选命名参数默认值前的分隔符从 `:` 改为 `=`**（用 `:` 现为编译错误）
+- ❌ **`continue` 指向非 loop / 非 switch member 的 label 现为编译错误**
+- ❌ **删除对 pre-2.12 语言版本的支持**（unsound null safety 不再可用）
+- 多个 core library API 被移除或加上 `extends`/`implements` 限制（详见 dart-3-migration-guide）
+
+## 不收录（实验性 / preview，转正后再写）
+
+无（3.0 引入的语言特性均直接 Stable；WasmGC 当时实验性，3.4 转 Stable 后已收录进 `versions/3.4.md`）。

package/versions/3.1.md

@@ -0,0 +1,15 @@
+# Dart 3.1
+
+- **发布日期**: 2023-08-16
+- **数据来源**: https://dart.dev/blog/dart-3-1-a-retrospective-on-functional-style-programming-in-dart-3
+- **类型**: Incremental release
+
+> **说明**：3.1 在**语言层面是空版本**——evolution 页明确写明 "Dart 3.1 added no new features and made no changes to the language"。本文件只列工具/库的 Stable 增量。
+
+## 工具链 / 平台
+
+本版本无新的 Stable 工具链能力（仅有 SDK 常规 bug 修复与 core library API 调整，详见 changelog）。同期 Flutter 3.13 发布。
+
+## 不收录（实验性 / preview，转正后再写）
+
+无。

package/versions/3.10.md

@@ -0,0 +1,38 @@
+# Dart 3.10
+
+- **发布日期**: 2025-11-12
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-10 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性）
+
+## 语言特性 (Language)
+
+### Dot shorthands — Stable（versioned，`environment.sdk: ^3.10`）
+当上下文类型可推断时，可省略显式类型名，写作 `.foo`。可用于：
+- **enum 值**：`Status currentStatus = .running;`
+- **静态成员**：`int port = .parse('8080');`（即 `int.parse('8080')`）
+- **构造函数**：`Point origin = .origin();`（即 `Point.origin()`）
+
+```dart
+enum Status { idle, running, stopped }
+Status s = .running;            // 推断为 Status.running
+List<int> nums = [.parse('1'), .parse('2')];  // 推断为 int.parse
+```
+
+## 核心库 (Core libraries)
+
+### 注解
+- 新增更细粒度的 deprecation 注解（`@Deprecated` 的细化版本）
+
+## 工具链 / 平台
+
+### Analyzer
+- **Analyzer plugin system**（Stable）：可在 `analysis_options.yaml` 注册自定义静态分析规则
+
+### Pub
+- **Build hooks**（Stable）：native 构建钩子
+- profile "Likes" tab 搜索
+- 可禁用手动 publishing（仅 verified publishers）
+
+## 不收录（实验性 / preview，转正后再写）
+
+无。

package/versions/3.11.md

@@ -0,0 +1,23 @@
+# Dart 3.11
+
+- **发布日期**: 2026-02-11
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-11 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（语言层面无新特性）
+
+> **说明**：3.11 在**语言层面是空版本**（evolution 页未列出新特性）。本文件只列工具/库的 Stable 增量。
+
+## 工具链 / 平台
+
+### MCP
+- Dart MCP Server 新增 `read_package_uris` 工具
+
+### Analyzer
+- Analysis server：fine-grained dependencies、缓存 plugin entry points、提升 dot shorthands 的 completion/quick-fix
+
+### Pub
+- **workspaces 支持 glob**：`workspace: - pkg/*`（versioned，需 `environment.sdk: ^3.11`；workspaces 主体自 3.6 起 Stable，3.11 新增 glob 语法）—— 子包路径可用 glob 批量声明
+- 新增 `dart pub cache gc` 清理缓存
+
+## 不收录（实验性 / preview，转正后再写）
+
+无。

package/versions/3.12.md

@@ -0,0 +1,27 @@
+# Dart 3.12
+
+- **发布日期**: 2026-05-18（博客发布 2026-05-20）
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-12 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性 + AI 工具链里程碑）
+
+## 语言特性 (Language)
+
+### Private named parameters — Stable（versioned，`environment.sdk: ^3.12`）
+私有字段的命名初始化形式参数，编译器自动去掉前导 `_` 作为调用方的公开名：
+```dart
+class Person {
+  final String _name;
+  Person({required this._name});  // 调用方写 Person(name: 'Alice')
+}
+```
+
+## 工具链 / 平台
+
+### DevTools
+- **Agentic Hot Reload**：与 AI agent 协作的热重载
+
+## 不收录（实验性 / preview，转正后再写）
+
+- **Primary constructors**（experimental）—— `class Point(final int x, final int y);`，需 `--enable-experiment=primary-constructors`。转 Stable 后写入对应版本文件。
+- **Genkit Dart**（preview）
+- **Cloud Functions for Firebase（Dart）**（preview）

package/versions/3.2.md

@@ -0,0 +1,31 @@
+# Dart 3.2
+
+- **发布日期**: 2023-11-15
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-2 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性）
+
+## 语言特性 (Language)
+
+### Private final field promotion — Stable（versioned，`environment.sdk: ^3.2`）
+type promotion 从局部变量/参数扩展到 **private final 字段**。编译器能在 null 检查后自动把 `field?.value` 里的 field 提升为非空，无需手动 `final x = _field!`。
+
+> 仅适用于 private + final 字段（public 字段会被外部子类覆盖，不能提升）。
+
+同时修复了 if-case 抛异常时 type promotion 的不一致行为。
+
+## 核心库 (Core libraries)
+
+### `package:lints`（官方维护的事实标准 lint 集）
+- **`package:lints` 3.0**：core 集新增 6 条 lint，recommended 集新增 2 条
+
+## 工具链 / 平台
+
+### FFI
+- 新增 `NativeCallable.isolateLocal` 构造器（Stable）
+
+### DevTools
+- 支持 extensions
+
+## 不收录（实验性 / preview，转正后再写）
+
+- Web/Wasm 路线图相关特性 —— 当时仍 preview，3.4 WasmGC 转 Stable 后已收录进 `versions/3.4.md`

package/versions/3.3.md

@@ -0,0 +1,34 @@
+# Dart 3.3
+
+- **发布日期**: 2024-02-15
+- **数据来源**: https://dart.dev/blog/new-in-dart-3-3-extension-types-javascript-interop-and-more + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性 + 重要 interop 模型）
+
+## 语言特性 (Language)
+
+### Extension types — Stable（versioned，`environment.sdk: ^3.3`）
+零成本包装类型，编译时擦除为基础类型（无运行时开销），用于类型安全互操作和领域建模：
+```dart
+extension type Meters(int value) {
+  Meters operator +(Meters other) => Meters(value + other.value);
+}
+extension type EmailAddress(String value) implements String { /* ... */ }
+```
+
+## 核心库 (Core libraries)
+
+### JS interop
+- 推出全新 **`dart:js_interop`** 库（基于 extension types 的 JS 类型表示）
+- 推出 **`package:web`**（替代 `dart:html` / `dart:svg` / `dart:webgl` 等内置浏览器库）
+- 这些为编译到 WebAssembly 铺路
+
+> JS interop 整体 Stable 是在 3.5；3.3 是引入版本。3.3 用户已可直接用 `dart:js_interop` + `package:web`。
+
+## 工具链 / 平台
+
+### Web
+- 为 WebAssembly (WasmGC) 编译铺路（3.4 才稳定）
+
+## 不收录（实验性 / preview，转正后再写）
+
+无（3.3 的语言特性直接 Stable；JS interop 新模型已可用）。

package/versions/3.4.md

@@ -0,0 +1,23 @@
+# Dart 3.4
+
+- **发布日期**: 2024-05-14
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-4 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（语言层面无 versioned 新特性）
+
+> **说明**：3.4 在语言层面**无新的 versioned 改动**，仅有 unversioned 的 type analysis 改进。但 Web/Wasm 里程碑在本版本达成。
+
+## 语言特性 (Language)
+
+### Unversioned type analysis 改进（升级 SDK 即生效，与 `environment.sdk` 下界无关）
+- 改进 conditional expressions、if-null expressions/assignments、switch expressions 的类型分析
+- 对齐 cast patterns 的 pattern context type schema
+- 让 `...?`（null-aware spread）对 map/set 字面量的 type schema 也为 nullable，与 list 字面量行为一致
+
+## 工具链 / 平台
+
+### Web
+- **Flutter Web 的 WebAssembly (WasmGC) 完整支持稳定**（与 Flutter 3.22 一起）—— Dart/Flutter Web 应用可编译为 WasmGC，享受性能与体积优势
+
+## 不收录（实验性 / preview，转正后再写）
+
+- **Macros**（`@JsonCodable()` 等宏做 JSON 序列化）—— 3.4 首次 preview，**3.7 已叫停 cancelled**。详见 `references/deprecation-and-evolution.md` 第二节与第五节。

package/versions/3.5.md

@@ -0,0 +1,34 @@
+# Dart 3.5
+
+- **发布日期**: 2024-08-06
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-5-and-an-update-on-the-dart-roadmap + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（语言层面无 versioned 新特性，但 JS interop 模型整体 Stable）
+
+> **说明**：3.5 在语言层面**无新的 versioned 改动**，仅有 unversioned 的 type inference 上下文微调。但 JS interop 模型在本版本整体 graduate 到 Stable。
+
+## 语言特性 (Language)
+
+### Unversioned type inference 上下文微调（升级 SDK 即生效）
+- `await` 表达式上下文为 `dynamic` 时，操作数上下文改为 `FutureOr<_>`
+- `e1 ?? e2` 整体上下文为 `dynamic` 时，`e2` 的上下文改为 `e1` 的静态类型
+
+## 核心库 (Core libraries)
+
+### JS interop
+- **JS interop 模型 graduate 到 Stable / v1.0**
+- **`package:web` 更新到 1.0**
+- 计划弃用旧 interop 库：`dart:html` / `dart:js` / `dart:js_util` / `package:js`
+
+### FFI
+- 支持从 Dart `TypedData` 直接传 pointer 到 FFI（避免拷贝）
+- 新增 lint 验证 JS interop 用法
+
+## 工具链 / 平台
+
+### Pub
+- pub.dev：topics 标签改进
+
+## 不收录（实验性 / preview，转正后再写）
+
+- **JNIgen**（Java/Kotlin 互操作）—— preview（性能改进、支持 Java 异常和 Kotlin 顶级函数；旧 C-based 绑定已停用）
+- **FFIgen**（Objective-C 互操作）—— preview（支持 protocols、NSString 等）

package/versions/3.6.md

@@ -0,0 +1,24 @@
+# Dart 3.6
+
+- **发布日期**: 2024-12-11
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-6 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性 + 重要 pub 能力）
+
+## 语言特性 (Language)
+
+### Digit separators — Stable（versioned，`environment.sdk: ^3.6`）
+数字字面量中可用下划线分组，提升可读性：
+```dart
+const oneQuadrillion = 1__000_000__000_000__000_000;
+const masked = 0x4000_0000_0000_0000;
+```
+
+## 工具链 / 平台
+
+### Pub
+- **Pub workspaces（monorepo 支持）**：根 pubspec 加 `workspace:` 字段声明子包路径，子包共享 `.dart_tool` 与版本解析（Stable，versioned，所有 workspace 包需 `environment.sdk: ^3.6.0`）
+- **Pub download counts** 替代 popularity score
+
+## 不收录（实验性 / preview，转正后再写）
+
+无。

package/versions/3.7.md

@@ -0,0 +1,35 @@
+# Dart 3.7
+
+- **发布日期**: 2025-02-12
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-7 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性 + formatter 大改版）
+
+## 语言特性 (Language)
+
+### Wildcard variables — Stable（versioned，`environment.sdk: ^3.7`）
+名为 `_` 的局部变量/参数变为**非绑定占位符**，可多次声明而不冲突：
+```dart
+// 多个 _ 不再冲突
+Foo(_, this._, super._, void _()) {}
+
+void process(Map<String, int> map) {
+  for (final (_, value) in map.entries) print(value);  // 忽略 key
+}
+```
+
+> 注意：此前 `_` 是合法标识符（会绑定变量），3.7 起变为 wildcard。**这与旧代码有兼容性影响**：库中名为 `_` 的 API 在 3.7+ 无法被引用。
+
+## 工具链 / 平台
+
+### Dart format
+- **Dart formatter 大改版**：新 "tall" 样式，`dart format` 与 language version 绑定（升级到 3.7 后会按 tall 样式格式化）
+
+### Analyzer
+- 新增 quick fixes / lints
+
+### Pub
+- pub.dev 多项改进
+
+## 不收录（实验性 / preview，转正后再写）
+
+- **Macros 已 cancelled** —— 3.4 preview，**3.7 正式宣告停止**（详见 `dart.dev/blog/an-update-on-dart-macros-data-serialization`）。新代码不要依赖，用 codegen 包替代。见 `references/deprecation-and-evolution.md` 第二节。

package/versions/3.8.md

@@ -0,0 +1,36 @@
+# Dart 3.8
+
+- **发布日期**: 2025-05-20
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-8 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（含 1 项新语言特性 + 编译器交叉编译）
+
+## 语言特性 (Language)
+
+### Null-aware elements — Stable（versioned，`environment.sdk: ^3.8`）
+集合字面量中前缀 `?` 表示"非 null 才插入"：
+```dart
+[?promotableNullableValue, ?nullable.value]
+// 等价于手动 if-null 处理，但更简洁
+```
+
+适用于 list / set / map 字面量。
+
+## 核心库 (Core libraries)
+
+### 文档注释
+- **Doc imports**：在 doc comment 中通过新语法引用未 import 的外部元素
+
+## 工具链 / 平台
+
+### Dart format
+- **Dart format 重写**：沿用 3.7 的 tall 样式并修复反馈，自动决定 trailing comma
+
+### 编译器
+- **跨平台交叉编译**（Stable）：`dart compile exe --target-os=linux --target-arch=arm64` 可从 Windows/macOS 交叉编译 Linux 二进制
+
+### Pub
+- pub.dev：新的 trending packages 发现
+
+## 不收录（实验性 / preview，转正后再写）
+
+- FFIgen / JNIgen 早期体验计划（仍 preview）

package/versions/3.9.md

@@ -0,0 +1,32 @@
+# Dart 3.9
+
+- **发布日期**: 2025-08-14
+- **数据来源**: https://dart.dev/blog/announcing-dart-3-9 + https://dart.dev/guides/language/evolution
+- **类型**: Incremental release（语言层面无 versioned 新特性，但有重要 unversioned 行为变更）
+
+> **说明**：3.9 在语言层面**无新的 versioned 改动**，但有几项重要的 unversioned 行为变更，以及 MCP Server / CLI 性能里程碑。
+
+## 语言特性 (Language)
+
+### Unversioned type-system 行为变更（升级 SDK 即生效，与 `environment.sdk` 下界无关）
+- **Null safety 默认假设**：计算 type promotion / reachability / definite assignment 时默认假设 null safety，可能产生更多 `dead_code` 警告
+
+## 工具链 / 平台
+
+### MCP
+- **Dart and Flutter MCP Server** 进入 stable channel（桥接 Gemini CLI / Cursor / Copilot）
+
+### Analyzer
+- **Analysis server AOT 预编译**：改用 AOT 预编译 snapshot，`dart analyze` 提速约 50%
+
+### Pub
+- **Pub 现在尊重 `flutter:` 上界约束**：root package 的 `environment.flutter` 上界从 3.9 起在 version-solving 时生效（这是 pub 工具行为，非 Flutter 框架能力）
+- git 依赖可按 `tag_pattern` + version constraint 进行 version-solving
+
+## 破坏性变更
+
+- 修复 DDC 的一处 soundness 问题（getter 返回 `dynamic`/`Function` 时缺少运行时检查）—— 此前依赖此行为的代码可能行为变化
+
+## 不收录（实验性 / preview，转正后再写）
+
+无。