# Prompt — NPM-001: CHANGELOG.md + changesets 工具链 (v0.1 publish 阻塞)
> **角色**：executor（被 plan owner 调用 / 或单独跑）
> **范围**：写 `CHANGELOG.md` 含 `[0.1.0]` 段 + 引入 `@changesets/cli` 作为 0.1.1+ version bump 工具链
>
> ⚠️ **不要 commit / 不要 git add** — dirty 累积到 plan owner 复审通过后由 user 决定 commit
> ⚠️ 完成后 **STOP**，按 §4 报告格式回报
> ⚠️ **不扩范围**：仅写 `CHANGELOG.md` / 加 changesets / 改 `package.json` 加 changeset script alias — **不改 `README.md`** / 不改 src/ / 不实际 publish / 不动 git tag / 不动 `.github/`
> ⚠️ **不做 NPM-002 / NPM-003 范围内的事**（README 更新走 NPM-002；publish workflow 走 NPM-003）
---
## §0 — Plan owner 已定决策（user 拍板"全推荐"）
User 在 NPM-001 backlog entry 三个决策点上 2026-05-09 plan owner 对话拍板：
- **D1 = 完整版** 0.1.0 highlights — 5 段裁剪：`Highlights` / `Added` / `Changed` / `Fixed` / `Verified`
- **D2 = changesets**（B 路线）— 引入 `@changesets/cli` 作为后续版本维护工具
- **D3 = 简化版** 格式 — Keep a Changelog 实用裁剪（5 段，本仓库 conventions 段说明）
executor 不需重新决策这 3 项，**直接按 §2 写定内容**。
---
## §1 — 上下文 / 现状基线
### 1.1 项目位置
- 项目目标见 [`AGENTS.md`](../../../AGENTS.md) + [`docs/PROJECT_GOAL.md`](../../PROJECT_GOAL.md)
- v0.1 publish 阻塞物 3 项：NPM-001（本任务）/ NPM-002（README + quickstart）/ NPM-003（publish CI）+ INFRA-F27（build pipeline fix）
- META-F27 系统性 review 报告：[`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md) §1.1（已完成 phase 量化）+ §1.3（v0.1 ready check）
### 1.2 current package.json
- `"version": "0.1.0"` ✅（不动）
- `"name": "@tvu/design-system"`（scoped）
- `"repository.url": "git+https://github.com/NancyZeng0210/TVU-Design-System.git"`
- `"prepare"` script 含 `vue-tsc --noEmit && vite build && build-icon-dist.mjs`（不动；INFRA-F27 单独修）
### 1.3 src/index.ts 实证 export 列表（29 named export — 用于 [0.1.0] Added 段）
```
Icon, Button, Radio, Switch,
InputBoxLine, InputBoxFilled,
Badge, Breadcrumb, BreadcrumbItem,
CheckBox, FormItem, InputNumber,
Notification, PromptMessage,
Pagination, Progress, Rating,
SelectBoxLine, SelectBoxFilled,
Slider, Steps, StepItem, Table,
Tab, TabItem, TabList, TopBar,
DropDownListSelect, Tooltip
```
（19 component family + 子组件如 BreadcrumbItem / StepItem / TabItem / TabList，按 src/index.ts:2-31 实证）
### 1.4 Pre-flight 状态（plan owner 2026-05-09 已 verify，blocker 概率低）
- 仓库根无 `CHANGELOG.md` ✅
- 仓库根无 `.changeset/` 目录 ✅
- `pnpm-lock.yaml` 无 `@changesets/cli` 依赖 ✅
如执行时发现以上任一不成立 → 走 §5 blocker 协议。
---
## §2 — 任务（按顺序执行）
### 2.1 写 `CHANGELOG.md`（仓库根，新建）
完整 inline 内容如下（**executor 一字不改 copy 进文件，不要补充 / 删减 / 重排**）：
````markdown
# Changelog
> **Format**: Keep a Changelog (实用裁剪) — `Highlights` / `Added` / `Changed` / `Fixed` / `Verified` 五段
> **Maintenance**: 0.1.0+ 由 [`changesets`](https://github.com/changesets/changesets) 自动聚合
> 新 PR 加 `.changeset/*.md` 描述变更；发版时跑 `pnpm changeset:version` 聚合并 bump version
## [0.1.0] - 2026-05-09
### Highlights
- 19 canonical Vue 3 组件 / 29 named export — 1:1 对齐 TVU Figma library
- 18 toggle-aware docs pages — Element Plus 风格文档站，全页跟随 docsTheme inject
- 642 个图标 / 28 categories — 同时输出 Vue 组件 / 每分类 ESM / 单 SVG CDN 三模式
- 完整 token system — CSS variables，theme-aware（`` 切换）
- T4-spike 验证："AI 拿 Figma URL → 1:1 还原代码" 闭环可达
### Added
- **Canonical 组件 29 named export**：`Icon` / `Button` / `Radio` / `Switch` / `InputBoxLine` / `InputBoxFilled` / `Badge` / `Breadcrumb` / `BreadcrumbItem` / `CheckBox` / `FormItem` / `InputNumber` / `Notification` / `PromptMessage` / `Pagination` / `Progress` / `Rating` / `SelectBoxLine` / `SelectBoxFilled` / `Slider` / `Steps` / `StepItem` / `Table` / `Tab` / `TabItem` / `TabList` / `TopBar` / `DropDownListSelect` / `Tooltip`
- **Icon system**：642 icons across 28 categories，三种消费方式：
- Vue 组件：``
- 每分类 ESM：`import { SettingIcons } from '@tvu/design-system/icons/esm'`
- CDN SVG：`dist/icons/svg//.svg`
- **翻译层 SoT 4 文件**（`src/design-system/translation/`）：
- `prop-aliases.md` — 命名 alias 登记（如 `closable ↔ showCloseIcon`）
- `divergences.md` — 显式不映射 / 双形态映射 / Button 双 API 决策 / Code 端双源段
- `icon-aliases.ts` — 图标 alias 表（如 `status/warning ↔ icon/Message/Error 4`）
- `token-aliases.ts` — figma Style → canonical token 映射
- **Bridge 机制**：硬规则 #6（canonical SoT）+ `pnpm sync:figma-library` audit pipeline（conformance / docs-site / published-vs-code 三层）
- **跨 AI 工具协作契约**：`AGENTS.md` / `docs/meta-rules.md` / `docs/internal/mockup-conventions.md` / `docs/internal/figma-component-catalog.md`
- **Theme system**：dark / light toggle 通过 `` 切换；默认 dark
### Changed
- **INFRA-F19** — docs site theme-aware 完整化（18 page 单 grid 跟随全局 toggle，禁止 dark/light 并排展示）
- **INFRA-F22** — generator theme axis case-insensitive（修 FormItem figma 真源大写 axis 派生失败）
- **INFRA-F23** — FormItemPage 整页重写（toggle-aware 范式）
- **Phase X.4.2** — 19 components canonical 完全对齐 figma + Badge 三轮 figma roundtrip
### Fixed
- **CANONICAL-001** — Tooltip `placement=top-*` 系列 arrow CSS 偏移
- **CANONICAL-003** — `BaseNotification` iconMap 真源不一致 + `Icon.vue` inline `currentColor` override（外部 CSS 现可 control icon color）
### Verified
- **T4-spike** — Badge "AI 拿 Figma URL → 1:1 还原" PASS（commit `b9e5ac3c`）
- **INFRA-F25** — SVG / Icon / token design-conformance audit suite 起步（含 `audit:icon-fill-currentcolor` / `audit:no-hardcoded-design-tokens` / `audit:component-no-inline-svg`）
[0.1.0]: https://github.com/NancyZeng0210/TVU-Design-System/releases/tag/v0.1.0
````
> **注**：`[0.1.0]` link 指向尚未创建的 GitHub release tag（NPM-003 publish 阶段创建），这是 forward-reference。executor 不需提前 push tag。
### 2.2 引入 `@changesets/cli`
按顺序执行（**单独运行每步，遇 error 立即 STOP 报告**）：
```bash
# Step A: 装包
pnpm add -D @changesets/cli
# Step B: 初始化 .changeset/ (生成 README.md + config.json)
pnpm exec changeset init
# Step C: verify 生成
ls -la .changeset/
cat .changeset/config.json
```
### 2.3 修改 `.changeset/config.json`
`pnpm exec changeset init` 默认生成的 `config.json` 含以下需修改字段：
| 字段 | 默认值 | 改为 | 原因 |
|---|---|---|---|
| `baseBranch` | `"main"` | `"master"` | 本仓库主分支是 `master`（git status 实证）|
| `access` | `"restricted"` | **保留 `"restricted"`** | NPM-003 D1 license/scope 决策待拍板；保守值，不预设 publish 渠道 |
| `commit` | `false` | **保留 `false`** | 与本仓库手动 commit workflow 一致 |
| `changelog` | `"@changesets/cli/changelog"` | **保留默认** | 标准 changelog generator |
修改后的 `config.json` 应是（**executor 直接 overwrite**）：
```json
{
"$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "restricted",
"baseBranch": "master",
"updateInternalDependencies": "patch",
"ignore": []
}
```
> ⚠️ `$schema` 版本号要与装上的 `@changesets/config` 版本一致（`pnpm exec changeset init` 生成的 default 即正确版本，**executor 保持 init 给的版本号，不要手改**）。如装上 `@changesets/cli` 后版本是 2.3.x 之外，按实际写。
### 2.4 修改 `.changeset/README.md`
`pnpm exec changeset init` 默认生成的 README 是英文 boilerplate。**保留默认**——它说明了 changesets 的标准用法，对外部 contributor 友好。
### 2.5 加 npm script alias 到 `package.json`
在 `package.json` 的 `"scripts"` 段加 3 个 alias（位置：`"prepare"` 后、`"test"` 前；保持仓库其它 script 顺序不动）：
```json
"changeset": "changeset",
"changeset:status": "changeset status",
"changeset:version": "changeset version",
```
### 2.6 不写 0.1.0 changeset 文件
**executor 不要在 `.changeset/` 下写 `0.1.0-*.md` 文件**——
理由：changesets 哲学是"每个 PR 加 changeset，发版聚合"。0.1.0 已经在 `package.json` 是当前版本号，且 highlights 已手写在 `CHANGELOG.md [0.1.0]` 段。changesets 接管 0.1.1+。
如果 user 要求改成"用 changesets 触发 0.1.0"——需重新走 plan owner 决策（changesets 会强制 bump 0.1.0 → 0.1.1，与已 pin 的 `package.json` version 冲突）。本任务范围内**不做**这个变体。
---
## §3 — 验证（exit 0 / 输出预期）
执行完 §2 全部步骤后，按下面 verify。每条命令的预期输出在右列：
| 命令 | 预期输出 / exit |
|---|---|
| `cat CHANGELOG.md \| head -10` | 顶部 `# Changelog` + Format/Maintenance conventions 段 |
| `grep -c '^## \[0.1.0\]' CHANGELOG.md` | `1` |
| `grep -c '^### Highlights\|^### Added\|^### Changed\|^### Fixed\|^### Verified' CHANGELOG.md` | `5` |
| `ls .changeset/` | 至少含 `README.md` + `config.json` |
| `grep '"baseBranch"' .changeset/config.json` | `"baseBranch": "master"` |
| `grep '"@changesets/cli"' package.json` | hit（在 devDependencies） |
| `grep '"changeset":' package.json` | hit（在 scripts） |
| `pnpm exec changeset status` | 输出 "🦋 No changesets present"（或类似 — 表示无 pending changeset） |
| `pnpm exec vue-tsc --noEmit; echo "exit: $?"` | `exit: 0` |
| `pnpm build 2>&1 \| tail -3; echo "exit: $?"` | `exit: 0`（dep 添加不影响 build；**注意**：build 会触发 INFRA-F27 倒退副作用——executor 跑完 build 后**不要**把 `src/icons/catalog/generated/*.ts` 的 dirty 当作本任务改动，那是 INFRA-F27 范围；report 时单独说明 build 副作用即可） |
---
## §4 — 报告格式（完成后 STOP 回报到对话）
```
## NPM-001 执行报告
### 文件改动
- 新增：CHANGELOG.md (XX 行)
- 新增：.changeset/README.md (changesets default)
- 新增：.changeset/config.json (baseBranch=master)
- 修改：package.json (+3 script alias / +1 devDep @changesets/cli@)
- 修改：pnpm-lock.yaml
### 验证
- §3 全部 8 条命令 PASS / FAIL（贴关键输出）
- INFRA-F27 build 副作用：__ 个 generated icon ts dirty（已知问题，非本任务范围）
### 未解决项 / blocker
- 无 / 列出
STOP — 等 plan owner 复审 + user 拍板 commit。
```
---
## §5 — Blocker 自检（pre-flight 强制）
executor 在跑 §2 之前 verify 以下，命中任一 → STOP，不执行，按 §4 格式仅填"未解决项"汇报：
- [ ] `ls CHANGELOG.md` 应是 "no such file"。如已存在 → blocker（user 决定追加 vs overwrite，不 executor 决定）
- [ ] `ls .changeset/` 应是 "no such directory"。如已存在 → blocker
- [ ] `grep '"@changesets/cli"' package.json` 应 0 命中。如已存在 → blocker
- [ ] `git status --short` 当前应只有本 prompt 文件 + 任何 user 在你 fire 前 staged 的内容。如有 unrelated dirty → 列出给 user 看，等指示
---
## §6 — 反模式自检（plan owner 已过，executor 不需重做；只列在此供审阅）
| # | 反模式 | 自检结论 |
|---|---|---|
| 1 | 硬编码项目级规则到工具 | ✗ 本 prompt 产文档 + 引入工具，无新机制硬编码 |
| 2 | 打补丁方案 | ✗ CHANGELOG/changesets 是 mainline 工程实践，非补丁 |
| 3 | to-do list 思维（无产出契约） | ✗ §3 验证含可机械验证的 schema 字段（baseBranch / 5 段标题 / version pin）|
| 4 | 没问下游怎么消费 | ✗ 下游：npm registry / GitHub release / 外部 consumer / NPM-003 publish CI 已 propose |
| 5 | 扩展时改哪里 | ✗ 0.1.1+ 每次 PR 加 `.changeset/*.md` 一处改，发版聚合 |
---
## §7 — 关联
- backlog entry: [`docs/internal/backlog.md`](../backlog.md) §NPM-001
- 系统性 review: [`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md) §1.3 + §7.2
- handoff: [`_plans/next-session-pickup-2026-05-09.md`](../_plans/next-session-pickup-2026-05-09.md) §3 第 2 批
- 后续依赖：NPM-002（README install 段更新需基于本 [0.1.0] highlights） / NPM-003（publish workflow 需 changesets script 已就位）