tt-design-web-vue 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.1.7
+- **`TtTable` 打开合计行（`show-summary`）时，页脚不再比数据行高出半截**：Element Plus 只给页脚设了背景与文字色，高度、内边距一概没给，于是合计行落到默认的 8px 上下内边距 —— 比数据行高出一截，也和表头对不齐。现补齐页脚的行高（与数据行同档）、底色（与表头同档）与字重（加粗一档），并新增 `--tt-table-footer-height` / `--tt-table-footer-bg` / `--tt-table-footer-font-weight` 三条变量，宿主可按密度档改写。底色默认值与改动前相同（此前就解析到同一档灰），**未使用合计行的表格零变化**。
+- **卡片与容器的外边界改用更深一档灰色（可见变化）**：信息块与卡片的 1px 外框此前用最浅一档灰，与所在页面底色几乎同色、边框读不出来；现统一改深一档，`TtCard`（含所有用卡片的页面）、`TtQueryForm`、`TtFilePreview`、`TtAttachmentList`、`TtActivityFeed`、`TtImage`、`TtCalendar`、`TtSplitter`（含折叠钮）、`TtAiToolCall` 的输入输出卡、`TtAiResultPanel`、`TtAiInteractionCard` 一并生效。分隔线、表格行线、`TtDivider`、`TtSteps` 连接线、禁用态边框等**非外边界**语义未改。
+  - **连带影响**：`TtCard` 的卡脚分割线与卡片边界同色（原设计如此），随外边界一起变深。
+- **破坏性变更：`TtAiExecutionFeed` 折叠行与过程行对齐（升级前必读）**：折叠行成为过程区的「第 0 行」，与过程行样式逐项一致 —— 行高 32px → 24px、行首固定显示状态标记、标题改用行标签字号、展开箭头移到时长之后；组件不再内置「执行过程」文案。三项需要调用方配合：
+  - CSS 变量 `--tt-ai-execution-feed-row-gap` 已移除，改用 `--tt-ai-execution-feed-leading-gap` / `-sep-gap` / `-leading-size` / `-sep-size` 四条；赋过旧变量需一并替换。
+  - `statusLabel` 由可见的行尾标签改为**视觉隐藏文本**（仍传同一 prop，但不再可见）；需要可见状态文案请改走 `title`。
+  - `title` 不再有默认值；`summary` 改为承载时长（如 `13s`）。
+- **`TtAiInteractionCard` 新增向导形态与动作分列**：新增 `variant: 'card' | 'wizard'`（默认 `card`，默认形态零回归）。`wizard` 是分步问答的一整盒形态 —— 顶行为问题标题与右侧工具位、正文复用既有事由／候选／输入区、底行动作分列；该形态下 `icon`、`status`、`statusLabel`、`summary`、`collapsible`、`expanded` 均不生效。`AiInteractionAction` 新增 `align: 'start' | 'end'`（默认 `'start'`）。
+- **`TtAiInteractionCard` 新增卡面、密度与候选排布控制**：新增 `--tt-ai-interaction-card-surface`（卡面）、`--tt-ai-interaction-card-body-padding` / `-body-gap` / `-row-padding`（密度）、`-option-height`（候选行高）共五条变量，换卡面或收紧密度不必再写覆盖样式（默认值与改动前一致）；新增 `optionsLayout: 'inline' | 'stacked'`（默认 `inline`），`stacked` 纵向单列，便于候选项带描述或文案较长时阅读。
+  - **修复**：带描述的候选项此前被固定行高与不换行挤到溢出、长文案不换行，现按内容自适应；标题区多个动作此前紧贴成一串或被长标题压住，现正常分隔并在窄卡片下换行。
+- **破坏性变更：`element-plus` 最低支持版本提高到 `2.14.1`（升级前必读）**：peer 依赖下限由 `^2.9.10` 改为 `^2.14.1`（`vue` 保持 `^3.5.14`）。宿主 element-plus 低于 `2.14.1` 时需一并升级，否则安装会收到 peer 警告。此前声明的下限低于实际能力——本库的类型声明依赖 `2.14.1` 起才具备的 Element Plus 类型形态（`TableProps` 的默认泛型实参、`SelectProps` 的类型导出），在更低版本宿主上 `TtTable` / `TtSelect` 的类型约束会静默失效（开了 `skipLibCheck` 时不报错，只是不再校验 `stripe`、`multiple` 等 prop）。
+- **修复 `TtCard` metric 指标卡图标背景**：图标容器原本使用品牌渐变、两层径向高光和 20px 圆角，与设计系统的渐变/光晕禁用项及 4/8/12px 圆角阶梯不一致。现收敛为 `--tt-color-primary-1` 浅主色表面、`--tt-color-primary` 图标色与 `--tt-radius-lg`（8px）；指标卡基础承载背景保持原有 `--tt-bg-light`。
+- **测试**：`tests/components/card.spec.ts` 新增图标表面合同，锁定浅主色背景、主色图标与标准圆角，并禁止渐变及高光回归。
+- **修复 `TtAiFoldText` 展开明细的字号与颜色**：展开后的明细此前只固定了字重，字号行高与颜色都随宿主正文（宿主体内为 14/22 + 正文色），同一段明细因此显示得比正文更重更大——「模型思考」展开后与助手回复正文肉眼难分，明细长达数十行时尤其明显。现固定为 12/18 + 次级色（与该组件已有的截断提示同档），所有消费方（思考、重试、上下文压缩）一次性生效，宿主不必再各自写覆盖样式。
+
+## 0.1.6
+- **组件清单去手工行号（删除 131 处行号字段）**：`docs/component-manifest.json` 里「某某在第几行」这类字段全部删除——`sources.react.componentImportLines` / `componentExportLines` / `runtimeAliasLines`（该子对象随之删除）、`sources.vue.runtimeExportLines` / `typeOnlyExportLines`、`vueOnly.defaultExtensions[].line` × 92、`vueOnly.namedCompositeOrSubcomponentExports[].line` × 25、`mappings.aliasCandidates[].reactLine` / `vueLine`、`mappings.missing[].reactLine`、`mappings.nonEquivalent[].reactLine` / `vueLine`、`reactNonComponentRuntimeExports[].declarationLine` / `exportLine`。删掉的理由是这些字段**没有任何消费者**：全仓唯一下游 `tests/components/ai-message-flow.spec.ts` 只读 `vueOnly.defaultExtensions[].name` 做存在性断言，从不校验行号 / 计数 / 类型行；同时包内 `files` 不含 `src/`，行号对使用方本就不可解析。而它们又能由 `src/index.ts` 完全推导、却长期靠手写转录——实测回溯 8 个历史提交，**同一提交内的 manifest 从未与源码一致过**（`vueOnly` 行号 10/20 错、具名子组件行号 25/25 全错、30 条类型导出行仅 7 条有效且漏登 34 条）。删掉载体后漂移不再可能发生，故**不引入生成器、不新增校验**（不为无人消费的字段维护 CI 机制）。同步去掉 `docs/component-compatibility.md`「基线来源」中的行号区间（`index.js:80-154`、`index.ts:1-109`）。`summary.reactBaselineComponentCount` 含 "Baseline" 但属计数而非行号，已保留。
+- **组件清单计数与条目按口径补正**：`summary.vueRuntimeComponentExportCount` 190 → **193**、`vueNamedRuntimeExports` 26 → **29**。口径统一为「默认再导出 + 具名子组件」：`vueDefaultReexports` **164**（= 92 个直接 `default as Tt*` + 72 个图标桶 `export *`，未变）+ 29 个 `X as TtY` 形态的具名子组件。此前那个 26 是**只随 `vueDefaultReexports` 同步递增、从未重算过**的常量（历次 changelog 中两者差值恒为 26 可证）。`vueOnly.namedCompositeOrSubcomponentExports` 补齐漏登的 4 条并按源码顺序重排（25 → 29）：`TtRow` / `TtMenuPanelItem` / `TtSpaceCompact` / `TtCheckableTag`——`TtCol` 早已登记而配对的 `TtRow` 漏登，是本表不自洽的直接证据。`docs/component-compatibility.md` 统计表同步：Vue 运行时组件/子组件导出 132 → **193**、Vue-only 默认扩展 36 → **92**、Vue-only 命名复合/子组件 24 → **29**，并补齐其命名复合清单块为 29 项。改后 md 与 manifest 的统计行、`exactNameComponents`（70）、`defaultExtensions`（92）、命名复合块（29，顺序一致）逐项复核通过。
+- **`TtCard` 头部内边距收敛为 `--tt-card-header-padding`（默认值不变）**：此前 `.el-card__header` 的 `9px 20px` 写死在库内，宿主想让分区面板的标题与正文贴齐同一条内容对齐线时，只能再叠一层选择器覆盖组件内部规则。现与 `--tt-card-body-padding` / `--tt-card-footer-padding` 同一做法收敛成变量：默认值 `9px 20px` 声明在卡片根节点（`.tt-card.el-card`），副标题变体的默认值 `9px 16px 11px 20px` 同样声明在根节点选择器块内（而不是声明在被消费的 `.el-card__header` 元素上——那样宿主在卡片上赋的值会被子元素自身的声明覆盖、静默退回默认值）。宿主在卡片元素上按同等或更高特异度赋值即可生效。**视觉零回归**：两条默认值与改动前逐项一致。
+- **测试**：`tests/components/card.spec.ts` 由 10 例扩到 **13 例**（头部消费变量且不写裸值、两条默认值与改动前逐项一致、变量声明在根节点作用域而非被消费的头部元素上）。
+- **补充自定义 Icon 图标规范**：在 Icon 文档和 `ttIcons/README.md` 中明确图标使用优先级（Element Plus → 公共 `ttIcons` → 宿主私有图标）、内联 SVG 与独立 SVG 资产的使用边界、公共图标与域资产的维护边界、`sources.json` 唯一事实来源、生成物职责、`TtIcon` 形状命名与撞名规则、新增校验流程及无障碍要求；保留 iconfont 作为兼容路径，新图标不再新增到字体图标体系。
+- **图标族新增 4 个自绘图标（`ttIcons`，72 个）**：为 TongClaw 项目资料库统计卡补入 `TtIconFolderOutline24`（文件夹，带横隔线）/ `TtIconTaskDoneOutline24`（方框内勾选）/ `TtIconFileTextOutline24`（带文字行的文档）/ `TtIconUserGroupOutline24`（三人）。四者上游（Element Plus / DeepSeek Harness / Feather）均无等价图形，按族规登记为 `source: 'self-drawn'` （`provenance: 'original'`），`origin` 如实记录最初取自 TongClaw 源码的位置；画布 24、`stroke`、`stroke-width 2`、`currentColor`，满足族内设计规则（由 `tt-icons.spec.ts` 强制）。命名遵循撞名规则：`Folder` / `TaskDone` / `FileText` / `UserGroup` 均为形状名，与族内既有 `TtIconFolderOutline16` / `TtIconCheckSquareOutline16` / `TtIconUsersOutline24` **图形不同**，故用不同形状名而非限定词区分。既有 68 个图标的渲染标记与文件头**零回归**（已用备份逐字节比对）。
+- **生成器加固**：`--check` 之外，入库源校验新增 `license` / `upstream` 必填——此前新增条目漏字段时会生成 `本库自绘（undefined）` 的文件头，现在直接报错退出而不是静默产出错图标。
+- **新增 Tabs-first 浮层布局合同**：`TtDrawer` / `TtDialog` 新增 `bodyLayout="tabs"`，`TtTabs` 新增 `fill`。组合使用时浮层 body 不再叠加默认 padding，页签头保持 38px，TabPane 统一承担一层内容 padding 与独立滚动，修复 Drawer / Dialog 内使用 Tabs 后留白和可用高度被重复扣减的问题。
+- **修复 `danger + text/link` 按钮颜色**：危险文字与链接按钮的 normal / hover / active 状态分别使用 `--tt-color-error` / `--tt-color-error-hover` / `--tt-color-error-active`，不再被通用文字按钮规则覆盖成品牌蓝。
+- **`TtIcon` 图标族升级为「多来源统一图标库」，图标 16 → 68 个**：`ttIcons/` 原为「DeepSeek Harness 专属族」（16 个），现改为统一承载**公共图标**（壳层、导航、通用动作），消费方不再各自维护图标注册表。新增 52 个图标，来源三类并在 `manifest.json` 与每个 SFC 文件头逐条标注：**`dsh`**（DeepSeek Harness，16 个，MIT / Copyright (c) 2026 DeepSeek）、**`feather`**（Feather Icons v4.29.2，21 个，MIT / Copyright (c) Cole Bemis，其中 4 个为 `derived` 改形：`Monitor` / `FilePlus` / `Archive` / `Info`）、**`self-drawn`**（上游图标集无等价图形，31 个，由本项目自绘）。`provenance` 区分 `verbatim` / `derived` / `original`。
+- **规则改造（本版核心）**：族规由「单一 DSH 源 + 路径逐字核验」改为**多来源 + 分源核验**。
+  - **入库源独立成文件** `scripts/tt-icons/sources.json`（唯一事实来源，含来源元数据）。生成器与新测试**只读该文件，不依赖任何外部检出**——修复了此前「`tt-icons.spec.ts` 强制要求本机存在 deepseek-harness 检出、否则整个用例文件报错」的既存缺陷（该缺陷在无 DSH 检出的机器上使 2 个用例恒失败）。
+  - **生成器**由 `scripts/extract-dsh-icons.mjs` 重写为 `scripts/extract-tt-icons.mjs`：多来源适配器、入库源校验（缺字段 / 组件名重复 / 来源未知 / 含硬编码颜色一律显式报错退出）、`--check` 幂等校验、可选 `--verify-upstream` 与真实上游交叉核验（上游不可用时明确报告，不静默通过）。
+  - **测试**由「数量硬编码 16 + 路径必须存在于 DSH 源」改为：数量与清单一致（清单是唯一事实来源）、按 `source` 分派核验（`dsh` / `feather` 走出处核验，`self-drawn` / `derived` 走**设计规则校验**）。
+  - **设计规则校验**（替代出处校验，供自绘与改形项使用）：结构合法（渲染出 `svg` 且 `viewBox` 与画布一致）/ 无硬编码颜色（只允许 `none` 与 `currentColor`）/ 无硬编码尺寸（不写 `width`·`height`）/ 图元白名单（`path`·`rect`·`circle`·`ellipse`·`line`·`polyline`·`polygon`）/ 坐标不越界。坐标解析按 SVG 规范实现：**按每条命令的真实参数元数取数**（`H`/`V` 只带 1 个值）、**按规范分词数字**（`c.907.339` 是两个数而非 `907.339`）、**应用元素 `transform`**（部分图标用 `matrix(...)` 定位，局部坐标含负数）。三点都是实测踩过的坑，注释里已写明。
+- **新增 52 个图标（形状名，业务语义留在消费侧）**：
+  - 构建端导航（18px 档）：`GridOutline24`（Feather）、`AtSign`→**`UserOutline24`**、`UsersTwo`→**`TeamOutline24`**、`GridPlusOutline24`、`ShieldCheckOutline24`、`BookOutline24`、`DatabaseOutline24`、`GitMerge`→**`WorkflowOutline24`**、`PhoneOutline24`、`GitBranchOutline24`、`StarOutline24`（Feather）、`Package`→**`ToolboxOutline24`**、`ToolOutline24`（Feather）、`Sliders`→**`FocusOutline24`**、`ActivityOutline24`（Feather）、`BookOpen`→**`MessageSquareOutline24`**、`Gauge`→**`EyeOutline24`**、`ShieldOutline24`（Feather）、主题三态 `SunOutline24` / `MoonOutline24`（Feather）/ `MonitorOutline24`（改形）。
+  - 设置与安全二级导航（16px 档）：`CpuOutline24`、`SettingsTwoOutline24`、`ImageOutline24`（Feather）、`VolumeTwoOutline24`、`MicOutline24`（Feather）、`MusicOutline24`（Feather）、`VideoOutline24`（Feather）、`BoxOutline24`、`BriefcaseOutline24`（Feather）、`BuildingOutline24`、`UsersOutline24`（Feather）、`Terminal`→**`ListOutline24`**、`Route`→**`NetworkOutline24`**、`Layers`→**`ArchiveOutline24`**（Feather 改形）、`ServerOutline24`（Feather）、`FileMinusOutline24`（Feather）、`FilePlusOutline24`（改形）、`DollarSignOutline24`、`FlagOutline24`、`InfoOutline24`（改形）、**`FeatherClockOutline24`** / **`FeatherCodeOutline24`**（见下）。
+  - 应用端导航（16px 档，原 CSS mask 素材）：`PlusOutline16`、`DashboardOutline16`、`HouseOutline16`、`CheckSquareOutline16`、`UserRoundOutline16`、`SunnyOutline16`、`FolderOutline16`、`PulseOutline16`。
+  - 用户菜单（16px 档）：`ActivityOutline24`、`SunOutline24`、`TranslateOutline24`。
+- **命名规则（新增，写入 README）**：族内一律用**形状名**（`TtIconGridOutline24`），业务语义不进库；**撞名时新方加限定词、已有名不改**（避免破坏性重命名）。本版命中 2 处并与族内既有图标是**不同图形**（实测相似度 0.369 / 0.073）：Feather `clock` → **`TtIconFeatherClockOutline24`**（族内已有 `TtIconClockOutline16`，DSH）、Feather `code` → **`TtIconFeatherCodeOutline24`**（族内已有 `TtIconCodeOutline16`，DSH）。
+- **既有 16 个图标零回归**：生成物渲染标记与升级前**逐字节一致**（已用备份对照校验），导出名、props、`tt-*` 类名、视觉行为均不变。
+- **机械替换、不改变视觉**：应用端 8 个图标源自 CSS `mask-image` 素材，替换时只做两件必要操作——写死颜色（`#235` / `#213354` / `#38F` / `#3388FF` / `var(--fill-0, …)`）归一为 `currentColor`，以及为 5 个缺 `viewBox` 的素材补 `viewBox`（= 其固有坐标系）。两项均已用 headless Chromium 逐像素验证为**视觉无操作**（补 `viewBox` 差异 0.000000；颜色归一最大差异 0.140% 覆盖率，为抗锯齿取整噪声）。`stroke-width`（1.2/1.5/1.6/2）、画布（16/20/24）与 fill/stroke 混排**一律原样保留**，不在本版统一。
+- **不做 EP re-export**：经评估（EP 图标名与库导出名零碰撞、`@element-plus/icons-vue` 已在 rollup `external` 列表、但宿主侧 EP 图标 import 分散在 146 个文件）决定**不**在入口平铺 re-export EP 图标；EP 图标继续由消费方从 `@element-plus/icons-vue` 直接 import。库的导出面只增加 52 个字形。
+- **文档与登记**：`docs/components/icon.md` 补「图标族」整节（此前**完全未记录**图标族，只写了 `icon` / `iconfont` / 插槽三种用法）——含用法三种形态、图标族 props、三种来源与许可、设计规则、新增流程；`ttIcons/README.md` 按多来源重写（来源表、判定顺序、设计规则、命名规则、生成脚本用法、新增步骤）；`docs/component-compatibility.md` 与 `docs/component-manifest.json` 同步（图标条目 16 → 68，`summary` 的 `vueDefaultReexports` 107 → 159、`vueRuntimeComponentExportCount` 133 → 185。**本版最终为 `vueDefaultReexports` 164 / `vueRuntimeComponentExportCount` 193**，含 `TtAiInteractionCard` 与本版新增的 4 个图标；`vueNamedRuntimeExports` 于本版末由 26 修正为 29）；`feather-icons@4.29.2` 加入 devDependencies（仅生成期与测试期读取，**产物零运行时依赖**）。
+- **测试**：`tests/components/tt-icons.spec.ts` 由 10 例扩到 **14 例**（数量与清单一致、清单字段合法性、barrel 与公共入口、默认尺寸与画布、文件头来源标注、生成器声明、分源核验、设计规则校验五项）。
+- **待需求人确认 2 项**：① 35 个 `self-drawn` 图标（本版 16 → 68 升级中加入 31 个、后续新增 4 个）最初取自 TongClaw 源码（`capturedFrom` 已如实记录），**公开发布前需确认该批图形的权利归属**；② 族内并存 fill（19 个）与 stroke（53 个）两种渲染方式，本版按「机械替换、不改变视觉」原样保留，视觉统一另议。
+- **`TtPopover` 几何默认值改放零特异性 `:where()`，修复「宿主赋值静默失效」**：`--tt-popover-padding` / `--tt-popover-min-width` / `--tt-popover-max-width` 三条默认值原先写在高特异性的 `.tt-popover.el-popover.el-popper`（0,3,0）里，宿主在浮层元素上用**单个类**赋值只有 (0,1,0)，会被库内规则压掉——实测宿主写 `--tt-popover-min-width: 400px` 后浮层仍是 242px，Element Plus 的 `width` 属性同样无效（min/max-width 是硬上限，会连同 `width="auto"` 一起把浮层钉在 242px），宿主只能再叠一层提升特异性的选择器，那是本库禁止的写法。现把默认值搬进 `:where(.tt-popover.el-popover.el-popper)`（特异性 0），宿主单类赋值或内联样式即可生效，「几何走变量」的承诺才真正成立；与 `Menu/style.scss` 对 `--tt-menu-*` 默认值的做法一致。默认值只在 `:where()` 声明一次，**不得在高特异性规则里重复声明**（已有用例锁定）。
+- **新增命令面板浮层宽度契约（缺陷 D17）**：`TtPopover` 的 242px 是**气泡卡片**语义，而浮层里承载 `TtMenuPanel` 时宽度应由**面板内容**决定——否则「编辑 / 设为扩展 / 删除」这类三项菜单会被撑到 242px（实测内容仅需 150px）。新增 `.tt-popover.el-popover.el-popper:has(.tt-menu-panel)`（宿主用 `TtPopover` 包 `TtMenuPanel` 即自动正确，**不依赖宿主记得传 `popper-class`**）与 `.tt-popover.tt-menu-popper.el-popover.el-popper`（`tt-menu-popper` 是库与宿主既有的命令面板标记类，保留作显式契约）两条选择器：放开宽度为内容自适应（`--tt-popover-min-width: 0`、`--tt-popover-max-width: min(var(--tt-menu-panel-max-width, 320px), calc(100vw - 32px))`，新增 `--tt-menu-panel-max-width` 变量），并清除气泡卡片的内衬与自绘外观（面板自带表面与 8px 内衬，避免「气泡外框 + 面板内框」双层）。真实浏览器实测：三项菜单 242px → **166px**（= 面板 150px + 8px×2），带与不带 `tt-menu-popper` 结果一致，普通气泡卡片仍是登记的 242px，宿主单类赋值可正常覆盖。
+- **测试**：`tests/components/popover.spec.ts` 由 3 例扩到 **5 例**（新增「几何默认值放在零特异性 `:where()` 里，宿主用变量即可覆盖」与「命令面板浮层的宽度随菜单面板内容，不吃气泡卡片的 242px」）；两例均做过变异反证（默认值搬回高特异性规则、删除命令面板规则都会被抓住）。库全量 **57 文件 / 369 例通过**。
+- **新增 `TtAiInteractionCard`（AI 会话组件族第 9 个组件）**：会话里「需要用户响应」的交互块此前没有库内组件 —— 库内 8 个 `TtAi*` 全是展示类，唯一的「选择」语义是产物行 / 血缘行的整行 `select`。于是每个「让用户选一下 / 填一下」的场景都在页面里各自自绘：手写原生 `<input type=radio>` / `<input type=checkbox>` / `<textarea>` / `<button>`、各写一套私有配色、各写一套展开状态，同一个交互在六处长得不一样，也绕开了「不手写控件、不用私有色」的约束。本组件把这套骨架一次收进组件库。
+  - **一张卡 = 标题行 + 正文**。标题行是卡片自身：行首 16px 状态盒（异常显示状态点、常态显示节点图标）+ 标题（14/22、600）+ 可选摘要（2px 分隔点 + 单行省略）+ 可选折叠箭头；正文依次是事由、默认插槽（复杂卡自绘）、候选、输入、动作。
+  - **props**：`title` / `icon` / `summary` / `status` / `statusLabel` / `reason` / `options`（`{id,label,description?,disabled?}[]`）/ `selection`（`none` 纯动作卡 / `single` 单选 / `multiple` 多选）/ `input`（`none` / `line` / `text`）/ `inputLabel` / `inputPlaceholder` / `inputRows` / `actions`（`{id,label,variant?,disabled?,loading?}[]`）/ `collapsible` / `busy` / `readOnly`。
+  - **v-model**：`v-model:expanded`（折叠）、`v-model:model-value`（选中的候选 id，单选为 `string`、多选为 `string[]`）、`v-model:input-value`（输入内容）。**props** 另有 `expanded` 本身，受控折叠由调用方持有，组件不自持展开状态。
+  - **events**：`submit(actionId)` —— 动作按钮被点击时回传该动作的 id。
+  - **slots**：`default`（正文，复杂卡用它挂自己的结构，卡片不再开二级折叠）、`title-extra`（标题行的行内辅助内容，如「查看执行详情」；收起态只有标题行可见，行内辅助动作必须与标题同在）。
+  - **组件不含业务逻辑**（族契约既有条款）：不发请求、不写存储、不持全局状态，提交一律由调用方处理；`busy` 只负责「禁用候选 / 输入 / 全部动作」这一件事，是否在提交、失败了怎么办由调用方决定。
+  - **`readOnly`**：已决态不再渲染任何可选控件、输入控件与动作，候选项以静态清单、输入内容以静态文本交出 —— 同一张卡完成态与开场态是同一个组件，不会出现「已决的卡里还留着能点的控件」。
+  - **状态语义与族内过程行同口径**：失败 / 中断等待行首显示状态点，其余显示节点图标；状态名经 `statusLabel` 以 1px 裁剪盒交给辅助技术，组件不内置任何状态文案（不传 `status` 时不渲染任何状态标记，缺失终态不会被渲染成成功）。
+  - **卡内不手写控件**：候选用 `TtRadioGroup` / `TtCheckboxGroup`、输入用 `TtInput`、动作用 `TtButton`；动作变体只映射到既有变体（`primary` / 默认 / `ghost`），不新增变体。
+  - **几何与视觉全部走 token**：卡片 `--tt-ai-interaction-card-radius` 默认 `var(--tt-radius-lg)`（r8）、标题行 `--tt-ai-interaction-card-row-height` 默认 `var(--tt-control-height)`（32px）、行首盒 16px、分隔点 2px、段间距 8px；中性面板 = 1px `--tt-border-color-light` 描边 + 白面，无阴影、无彩色底、无彩色左边框；圆角形状（标题行圆上两角 / 正文圆下两角）也做成变量，`border-radius` 声明本身只读变量。
+  - **无障碍**：可折叠时标题行是原生 `<button>` 并带 `aria-expanded` + `aria-controls`（指向正文），不可折叠时是 `<div>`，指针手势与 hover 反馈只挂在 `tt-ai-interaction-card--collapsible` 修饰类下（不给点了没反应的假交互）；输入区标签是控件的可访问名；焦点可见走 `--tt-focus-ring`；折叠箭头过渡带 `prefers-reduced-motion` 兜底。
+  - **同步**：`src/index.ts`（值与类型分开导出 `AiInteractionOption` / `AiInteractionAction` / `AiInteractionSelection` / `AiInteractionInput` / `AiInteractionActionVariant`）、`src/styles/index.scss` 注册、`AiInteractionCard.stories.ts`（6 个 story：纯动作卡 / 单选候选 / 多选与输入 / 可折叠 / 已决态 / 提交中）、新增 `tests/components/ai-interaction-card.spec.ts`（24 条）。族契约 `ai-message-flow.spec.ts` 纳入新组件后**约束强度不变**：族内导出、类型导出、样式聚合注册、只吃 `--tt-*`（无裸色、无 `rgba()`、无库外变量）、颜色 / 间距 / 圆角 / 字阶全走 token、高度字面值落在 4px 阶梯、状态不只靠颜色、无指针手势假反馈、`reduced-motion` 兜底、无业务逻辑、清单登记，全部对新组件一并生效（其中「状态不只靠颜色」与「无指针手势假反馈」两条当前仍只锚定族内既有成员，对新组件的同等约束由 `tests/components/ai-interaction-card.spec.ts` 承担）。
+  - **组件清单**：`docs/component-manifest.json` 登记为 Vue-only 默认扩展（AI 信息流 · 需用户响应的交互卡），`docs/component-compatibility.md` 同步。`TtAi*` 一族仍按既有约定不进 VitePress 组件页（8 个既有成员同样只以 Storybook + 类型声明 + 本条目为准），族内文档口径不变。
+- **`TtAiInteractionCard` 的折叠契约**：`expanded` 由调用方持有（`v-model:expanded`），组件只上抛展开意图、不自己改写。标题行按 `collapsible` **且卡片确实有正文可展** 决定形态：两者同时成立时才是整行按钮（带 `aria-expanded` / `aria-controls`），否则是 `<div>` —— 与 `TtAiToolCall` / `TtAiExecutionFeed` 的「没有可展开内容就不是按钮」对齐，不给点了没反应的假交互。正文来源包含 `reason` / 候选 / 输入 / 动作与默认插槽，任一存在即算有正文。
+- **修复 `TtAiInteractionCard` 行内辅助动作会连带展开卡片**：`title-extra` 插槽此前渲染在标题行**按钮内部**，点这个动作会冒泡到行按钮，一次点击同时打开详情并展开卡片；且 `collapsible` 时插槽落在 `<button>` 里，构成「button 内嵌 interactive content」的 HTML 内容模型违规。现新增 `__header` 标题区容器（描边与圆角移到它身上），标题行按钮与 `title-extra` 成为**兄弟节点** —— 点行内动作不再冒泡翻转展开态，也不再嵌套交互元素，且因仍在标题区（不在正文），收起态照样可见可点。族契约的高度阶梯豁免改为**按做法判定** —— 该块声明了 `clip` / `clip-path` 裁剪（视觉隐藏的标准技法）即豁免，不再按类名枚举，族内任何用该技法承载语义文字的组件都不会被误判为几何越界（豁免写死类名时，豁免范围只对当时那几个类名有效，新成员会被误判）。
+- **修复 `TtAiInteractionCard` 已决态看不出当时选了什么**：`readOnly` 时候选退化为静态清单却不读选中值（输入侧一直有回显，选择侧没有，两侧口径不对称）。现按 `modelValue` 把当时选中的候选项标出来（勾形图标 + 视觉隐藏的「已选」，多选逐项标），仍不渲染任何可交互控件；`selection: 'none'` 的纯动作卡没有选择语义，不标。调用方进入已决态时不要提前清空 `modelValue`，否则无从标注 —— 该口径写进 `readOnly` 的 props 注释。
+- **`TtDropdown` 菜单行密度对齐库内 32px 档（一次可见视觉变化）**：`.el-dropdown-menu__item` 的 `min-height` 由 38px 收到 32px、内边距由 `8px` 改为 `5px 8px`（行距 8px 不变）。本库此前已把「紧贴触发器的选项列表」的密度定为 32px / 纵向 5px / 行距 8px（`TtMenuPanelItem` 与 `TtSelect` 下拉选项行同档），`TtDropdown` 是三者中唯一没有跟进该理由的：同为紧贴触发器弹出的选项列表，行高多 6px、节距 46px 对 40px，四项菜单的面板总高比同密度档多 24px（192px 对 168px）。三者的行高都由 `--tt-line-height-base`(22px) + 纵向内边距得出，故新取值与兄弟组件同源、不是另立的数字。**宽度契约不变**（浮层与菜单仍 `min-width: 136px`），组件 props、导出名与 `tt-*` 类名均不变。命中面是全部使用 `TtDropdown` 的下拉菜单，逐处矮 6px、节距少 6px；宿主此前无需、此后也不应为此写行几何覆盖或自造 `--tt-dropdown-*` 变量。
+- **测试**：新增 `tests/components/dropdown.spec.ts`（**5 例**），直接读 `style.scss` 做断言——本行取 32px 档且 38px / `padding: 8px` 不得回潮、与 `TtMenuPanelItem` 行几何逐项一致、与 `TtSelect` 选项行同高同行距、行高与兄弟组件同源、宽度契约不变。
+
 ## 0.1.5
 - **`TtAi*` 一族迁到 `src/ai/`**：8 个 AI 会话组件（`AiExecutionFeed` / `AiToolCall` / `AiStatusCode` / `AiFoldText` / `AiResultPanel` / `AiArtifactRow` / `AiTodoProgress` / `AiSubagentLineage`）从 `src/components/` 移到 `src/ai/`，与通用组件分开管理，避免通用组件目录被「只服务 AI 会话信息流、其他页面不消费」的组件淹没。**对消费方无影响**：公开入口仍是 `src/index.ts`，`TtAi*` 的导出名、props、事件、插槽、`tt-*` 类名与全部视觉行为逐项不变；`package.json` 的 `exports` 只暴露包根与 `style.css` / `rich-text.css`，不含内部目录路径，单文件深路径引用本就不在公共契约内。族内样式注册（`src/styles/index.scss`）、定向 Vitest、Storybook story 与文档登记方式一并保持不变；`TtAi*` 之间的相对引用与族契约的路径锚点已同步更新。
 - **破坏性变更与行为变更（`TtAiToolCall` / `TtAiExecutionFeed`，消费方升级前必读）**
@@ -56,6 +123,15 @@ All notable changes to this project will be documented in this file.
 - **`TtAiToolCall` 明细双栏栅格在窄容器下的横向溢出（当时记录；该机制已被上文「一个卡片 + 两段」整体取代）**：栅格原为 `repeat(auto-fit, minmax(var(--tt-ai-tool-call-pane-min-width), 1fr))`，`240px` 是**硬下限**，栅格宽度不足 240px 时轨道压不到下限以下、整行被撑出容器；当时改为 `minmax(min(240px, 100%), 1fr)`（列宽行为在宽容器下与改动前逐项相同）并实测「栅格宽度 120 / 180 / 200 / 239px 时改动前分别溢出 136 / 76 / 56 / 17px，改动后溢出均为 0 且折叠为单列铺满」；注意真实组件里栅格比外层窄 16px（`__detail` 的左内边距），因此**外层** 240px 时改动前仍会溢出 16px，等价点换算到外层是 256px。该 `auto-fit` 栅格随后在明细重构中被整体移除，防溢出改由「换行 + 收缩链」承担（见上文），相关源码、变量与定向用例一并随之改写。
 
 - 规范与元数据：上述各条改动**均未修改设计系统规范数值** —— 图标来源属实现层事实（不新增规范数值）；`TtButton` 的 link/text 合同与 `TtForm` 的默认值行为早已登记在 `docs/design-system` 侧（`button/spec.md:190`、`:228`），本次是组件库实现向规范收敛，不涉及规范改值。`docs/component-manifest.json` 与 `docs/component-compatibility.md` 按新增组件同步登记。
+- **根治相邻按钮间距被翻倍的问题（`TtButton` 自身清除 Element Plus 的隐式外边距）。** Element Plus 为服务 inline-block 行内按钮，给相邻 `.el-button` 写死 `margin-left: 12px`；本库按钮一律在 flex 容器里按 `gap` 排布，两者叠加会把间距翻倍（实测 12px 变 24px、10px 变 22px、8px 变 20px）。此前 `TtDialog` / `TtPopconfirm` 各自在自己容器里清过一次，而 `PageHeader` / `QueryForm` / `Card` / `Comment` / `FilePreview` / `List` 等容器都漏了——**逐容器处理天然会漏，每新增一个容器就要再记得一次**（本次正是先按容器修了 3 处，随即被暴露出 `ProviderCard` 的 `.card-actions` 仍为 20px）。现把该归零收进 `Button/style.scss`：`.tt-button.el-button + .tt-button.el-button { margin-left: 0 }`，特异性 (0,4,0) 高于 Element Plus 的 (0,2,0)，不受两份样式表加载顺序影响。**任何容器只声明 `gap` 即自动正确，不再需要页面级补丁**；同时移除了上一轮加在 `TtPageHeader` / `TtQueryForm` / `TtDrawer` 以及宿主三处容器上的冗余归零声明（`TtDrawer` footer 保留新增的显式 `gap`，它对 Element Plus 隐式 margin 的依赖仍然要消除）。**行为变化的边界**：若某处不声明 `gap` 而指望行内按钮自带间距（例如正文里夹着两个按钮），现在会贴在一起——应改用 `TtSpace` 或由容器声明 `gap`；已在 `docs/components/button.md` 与设计系统 `standards/button/spec.md` 写明这一反面约束。
+
+- 同步 `docs/components/button.md`：新增「相邻按钮之间的间距由容器提供」章节（说明根治点在按钮组件自身、容器只需声明 `gap`、以及不用 `gap` 的行内场景应改用 `TtSpace` 的反面约束）；并把 Props 一行改为准确描述——只透传父组件实际传过的属性，以及本库扩展的 `neutral` / `ghost` / `selected` / `muted` 不下发给 `ElButton`。
+
+- **修复 `TtForm` / `TtFormItem` / `TtButton` / `TtPagination` 覆盖 Element Plus 默认值，导致表单校验失败文案永不渲染（缺陷 D8）。** 根因是这四个包装组件用 `defineProps<Partial<XProps>>()` 声明属性后以 `{ ...props, ...attrs }` 全量透传：Vue 会为声明的属性生成运行时 props，而**没有 `default` 的 Boolean 属性在父组件未传时会被折叠成 `false`**，这个 `false` 会作为显式值下发给 Element Plus，覆盖其自身的默认值。实测影响：`ElForm`/`ElFormItem` 的 `showMessage`（EP 默认 `true`）被压成 `false` → `.tt-form-item.is-error` 类照常出现但 `.el-form-item__error` 文案节点永不渲染；`validateOnRuleChange`（EP 默认 `true`）被压成 `false` → 规则变更不再触发校验；`required`（EP 默认 `undefined`）被下发 `false` → 凭空多出一条 `{ required: false }` 校验规则，改变 `validate()` 的判定范围；`ElPagination` 的 `teleported`（EP 默认 `true`）被压成 `false` → 每页条数下拉浮层留在表格容器内，被 `overflow: auto` 的容器裁切。现新增共享工具 `src/utils/forwardProps.ts` 的 `useForwardedProps()`，用当前实例的原始 vnode props 判断某个键**是否被父组件写过**（同时接受 camelCase 与 kebab-case），只透传写过的键，再叠加 `$attrs`。这样子组件的 `withDefaults` 才能生效，而未传属性仍由 Element Plus 自己的默认值决定。四个组件同步接入。
+- 新增 `TtFormItem` 的 `hideRequiredAsterisk` 属性（本库扩展）：**只关闭本项**的必填星号，`required` 与校验规则照常生效。Element Plus 的 `hideRequiredAsterisk` 只能挂在表单上，一旦打开整表星号都会消失；需要「整表保留星号、个别项不显示」时业务侧原先只能去掉 `required` 自行维护校验，那会绕开「必填标记只能由 `required` 产出」的约束。实现复用 Element Plus 自己的 `is-no-asterisk` 类（表单级走的是同一个类），星号样式因此与 Element Plus 完全一致，本库不写第二套星号规则。默认 `undefined`，不传时行为与未扩展前完全相同；该属性由本库消费，不下发给 Element Plus（否则会作为无效属性落到根元素上）。
+- **修复 `TtTree` 的当前节点态与悬浮态视觉不可区分（缺陷 D10）。** 改前 `.el-tree-node.is-current > .el-tree-node__content` 与 `.el-tree-node__content:hover` 都取 `--tt-bg-light`（浅色 `#f7f8fa`），导致「鼠标划过」与「当前选中范围」在树里无法区分——而「我现在选中了哪个范围」正是树形导航的核心信息；且当前态从品牌色退化为中性灰。现按设计系统对选中态的规定（品牌浅底 + 品牌色文字）改为 `--tt-bg-active`（浅色 `#f0f9ff` / 深色 `#123b5a`）+ `--tt-color-primary`，并把两态各自抽成可覆盖变量 `--tt-tree-node-current-bg` / `--tt-tree-node-current-color` / `--tt-tree-node-hover-bg` / `--tt-tree-node-hover-color`（`--el-tree-node-hover-bg-color` 也接上本库变量，避免两处各自写死），宿主需要换色时不必提升特异性覆盖库内规则。
+- 同步 `docs/components/form.md`：写明「**未传的属性不下发**」是行为合同而非实现细节，并补充 `hideRequiredAsterisk` 的表单级 / 单项级用法与边界。
+- 新增回归测试：`form.spec.ts` 9 例（含 `showMessage` 保留 EP 默认、`required` 不被下发 `false`、错误文案真实渲染、显式 `showMessage: false` 仍生效、逐项星号开关三例）、`pagination.spec.ts` 3 例（`teleported` 保留 EP 默认 `true`、显式 `false` 仍生效、未传项不强行下发）、`tree.spec.ts` 3 例（两态变量化、当前态与悬浮态不同源、当前节点仍由 Element Plus 打类）、`button.spec.ts` 2 例（自有变体不下发到 Element Plus / 原生 button、`autoInsertSpace` 未传不下发）。全量 45 文件 / 228 例通过。
 
 ## 0.1.4
 

package/README.md

@@ -2,7 +2,7 @@
 
 基于 Vue 3 与 Element Plus 的 TT Design 风格组件库。
 
-> 当前版本为 `0.1.5`（下一次发布的版本号，发布即 `npm publish`，不再改版本）。registry 上的最新已发布版本可用 `npm view tt-design-web-vue dist-tags` 查询。本项目从原 workspace 的 `tt-design-vue` 迁出，作为独立项目构建并提供真实的 JavaScript、类型声明和 CSS 产物。
+> 当前版本为 `0.1.7`（下一次发布的版本号，发布即 `npm publish`，不再改版本）。registry 上的最新已发布版本可用 `npm view tt-design-web-vue dist-tags` 查询。本项目从原 workspace 的 `tt-design-vue` 迁出，作为独立项目构建并提供真实的 JavaScript、类型声明和 CSS 产物。
 
 ## 安装
 
@@ -77,11 +77,11 @@ import 'tt-design-web-vue/dist/style.css';
 --tt-color-geek-blue-1 … 7  →  --tt-color-primary-1 … 7  →  --el-color-primary
 ```
 
-换主题色只需覆盖对应色板变量，TT 组件与 Element Plus 桥接变量会一起跟随。全量色板（14 个色系 × 10 阶）、深色主题的推导规则和覆盖示例见 [主题说明](./docs/theme.md)。
+换主题色只需覆盖对应色板变量，TT 组件与 Element Plus 桥接变量会一起跟随。全量色板（14 个色系 × 10 阶）、深色主题的推导规则和覆盖示例见 [主题说明](./docs/guide/theme.md)。
 
 ## 兼容范围
 
-首发版本保留迁出源中全部根入口导出，包括基础组件与既有组合组件，例如 `TtActivityFeed`、`TtQueryForm`、`TtEChartsWrapper` 和 `TtUserDisplay`。所有组件导出均使用 `Tt` 前缀，与 Element Plus 的组件名称区分；与 React 基线的对应状态将记录在 [组件兼容清单](./docs/component-compatibility.md)。
+首发版本保留迁出源中全部根入口导出，包括基础组件与既有组合组件，例如 `TtActivityFeed`、`TtQueryForm`、`TtEChartsWrapper` 和 `TtUserDisplay`。所有组件导出均使用 `Tt` 前缀，与 Element Plus 的组件名称区分；与 React 基线的对应状态将记录在 [组件兼容清单](./docs/guide/component-compatibility.md)。
 
 ## 本地开发
 
@@ -109,7 +109,7 @@ yarn test:package
 /Users/meng/Documents/productcode/platform/apps/frontend/web/packages/tt-design-vue
 ```
 
-本项目不会删除、移动或修改该路径，也不会在本次迁出中切换任何旧 workspace 消费者。详情见 [迁出说明](./docs/migration-from-workspace.md)。
+本项目不会删除、移动或修改该路径，也不会在本次迁出中切换任何旧 workspace 消费者。
 
 ## 发布