finesse-term

finesse-term —— 说法层

它不决定做什么，也不决定做得好不好看。它只决定这件事该怎么说。

用户说不出「安全区」，不是因为词汇量小，是因为他描述的是症状（按钮被黑杠挡住），而术语描述的是成因。这中间的翻译，是他自己做不到、而每一轮对话都需要的那一步。

---

1. 每一轮都要过一遍

用户本轮的新话里，只要出现下面任意一种，就执行本 Skill：

用户在干什么	你要做什么
用大白话描述了一个网页/H5 的效果或故障	照常把活干完，在结果里顺手点出术语
准备把需求发给别人（另一个 Agent、外包、同事）	给出可直接复制的准确表达
问「这个叫什么」「专业点怎么说」	直接答，附一句解释和那个坑
贴了一段听不懂的话	挑出最影响下一步判断的一个概念解释
已经用了准确术语	正常做事，不重复教学

前几轮已经在写代码，不是跳过本轮检查的理由。用户追加的每一句口语描述都是一次新的触发。

---

2. 三条硬门禁

这三条是这个 Skill 存在的意义。违反任何一条，输出的东西就变成了炫技。

门禁一 · 指得出触发的那几个字

每一条给出的术语，都必须能指着用户这一轮的原话，说出是哪几个字触发的。

term.mjs find 的返回里有 match.matched 字段（形如 trigger:按钮被挡住），那就是证据。指不出来 → 不提这条术语。

宁可一条都不提。用户表达已经准确、或者这轮根本没描述界面，沉默是正确输出。

门禁二 · H5 的搭档必须一起给

移动端的坑几乎都是成对的。词条 pairs 字段不是「相关阅读」，是「不一起做就会出事」：

只说了这个	就必须一起说这个	否则
吸底操作栏	安全区	全面屏上按钮被 Home 条压掉一半
弹层 / 底部弹层	滚动穿透	弹窗底下的页面跟着滑，关掉还弹回顶部
输入框 / 表单	键盘顶起	iOS 上键盘把提交按钮顶出屏幕
图片 / 封面	宽高比容器	图一加载完，用户正要点的按钮跑了
头尾固定	滚动容器	iOS 地址栏一收缩，固定栏开始抖

find 的非 --brief 输出已经把 pairs 的标题一并带出来了，不需要再查一次。

门禁三 · 结果在前，术语在后

先把用户要的活干完，再补术语。 术语出现在进度或结论的行文里，不出现在它前面。

一次最多 1–3 条。只提最有帮助的那一条，不为了凑数追加 Hover、Icon 这类谁都知道的次要词。不生成学习路线、课程、练习或术语清单——那是另一件事，用户没要。

---

3. 怎么查

node "<skill-root>/scripts/term.mjs" find --q "底部按钮被那条黑杠挡住了"

把用户的原话按子句拆开分别查，不要整句丢进去。 一句话里常有两三件事：

# 「鼠标放上去变个色，点下去也要有反馈，另外底下按钮被挡住了」
node "<skill-root>/scripts/term.mjs" find \
  --q "鼠标放上去变个色" \
  --q "点下去也要有反馈" \
  --q "底下按钮被挡住了"

• 检索是本地的，零网络依赖，随便查。不确定就查，别猜。
• --q 最多 5 次；--surface web|h5 已知场景时限定，能显著减噪。
• 返回 count: 0 是正常结果，不是失败 —— 说明这轮没有值得提的术语，按门禁一保持沉默。
• --brief 只要 title 和 say；要 trap 和 pairs（大部分时候要）就别加。

其它命令：get <id> 取完整词条 · list --surface h5 看全库 · check 校验数据。

<skill-root> 是本 SKILL.md 所在的目录，换成它的实际路径再执行。检索器需要 Node.js 20+，零依赖。环境里没有 node、或命令执行不了时，不要放弃也不要凭印象补：直接读 <skill-root>/data/*.json，拿用户的原话去对 trigger 和 aliases 字段，门禁一的证据就是对上的那一条 trigger。

只使用检索器返回的内容。 不要凭印象编造词条、坑或搭档关系 —— 库里没有的东西，就照常用大白话说清楚，别包装成一个术语。

---

4. 怎么说

做任务时（最常见）

先干完，再在结果里带一句。术语第一次出现时用「大白话（术语）」的形式：

已给下载按钮加了文字提示（Tooltip）：悬停或键盘聚焦时显示「下载」。
另外把底部操作栏的内边距接上了安全区（Safe Area），否则全面屏上会被 Home 条压住一半。

不要单独开一段「术语科普」，不要用列表罗列，不要解释你为什么要说这个。

改写需求时（用户要发给别人）

先给能直接复制的那一段，再补术语：

可以直接这样说：

「为按钮补充 Hover 状态和 Active 状态，并用 150ms 过渡让状态变化更自然。」

术语提示：
- Hover / Active：鼠标停住和手指按下时的两种样子，手机上只有后者，所以两个要一起做。

保留原意、语气和约束。 不擅自增加框架、组件库、参数或实现方案 —— 用户没说要 Vue，改写后就不该出现 Vue。优先写可观察的行为和结果，只有用户正在讨论实现时才补实现细节。

解释别人的话时

挑出最影响下一步判断的那一个概念，说三件事：在当前任务里具体指什么、它负责什么、一个容易混淆的边界。不逐词翻译整段，不顺势开课。

---

5. 动作命令

命令	干什么
say <原话>	改写成可直接发给 Agent 的准确需求
name <原话>	只回答「这叫什么」，附一句解释和那个坑
explain <别人的话>	拆解听不懂的一段，只讲影响下一步的那个概念
check <一段需求>	审一段已写好的需求：哪里含糊、哪里漏了成对的搭档
align	生成/更新 .finesse/lexicon.md 说法对齐表
list [--surface h5]	列出术语库里有什么

不带命令直接给一句话 = say。

---

6. 可选产出：.finesse/lexicon.md

只在用户要求 align、或者同一个东西在本次对话里出现了第三种叫法时才写。

一个项目里同一个组件常有三种叫法（「弹窗」「浮层」「模态框」），需求文档、代码命名和沟通各用一种，久了没人确定说的是不是同一个东西。对齐表把每个概念钉死成一个说法：

# 说法对齐表

| 本项目统一叫 | 术语 | 代码里的名字 | 别再叫 |
|:---|:---|:---|:---|
| 底部弹层 | Bottom Sheet | `<BottomSheet>` | 半屏弹窗 · 上拉框 · 抽屉 |
| 空状态 | Empty State | `<EmptyState>` | 缺省页 · 无数据页 |

没有文件系统时（聊天产品、手机助手），把整张表打印在一个可复制的代码块里，不要假装写了文件。

---

7. 术语库

册	收什么	条数
data/web.json	通用 Web：布局 · 组件 · 状态 · 交互 · 表单 · 无障碍 · 性能	57
data/h5.json	移动 H5 专属：适配 · 容器 · 手势 · 键盘 · 弹层 · WebView	30
data/motion.json	动效与质感：过渡 · 转场 · 反馈 · 材质 · 排版节奏 · 高级交互手法	35
data/mp.json	小程序专属：分包 · 页面栈 · 生命周期 · 自定义组件 · 登录与消息 · 云开发	10
data/base.json	前端基础概念：盒模型 · 弹性布局 · 定位 · 事件流 · 跨域 · 缓存 · 首屏 · 存储	10

每条词条十个字段，其中三个是这个库和普通术语表的区别：

• trigger —— 用户会怎么描述这件事（不是它叫什么）。检索的主键。
• say —— 可以直接复制给 Agent 的一句标准表达。
• trap —— 这个术语最常见的翻车方式。多数时候它比定义更值得说。

写法契约见 references/entry-format.md，加词条的规矩见同一份文件。

浏览页。 仓库根目录的 docs/index.html 是这个库的离线浏览页：130 条带示意图，43 条带可以上手摸的真机演示（移动 H5 册全部 30 条 + 动效册 13 条）。它不随 Skill 安装，只在用户手里有整个仓库时才有。用户想亲眼看一个坑的后果（「滚动穿透到底是什么样」）、而当前工作区里正好有这个文件时，可以告诉他用浏览器打开 docs/index.html，在地址末尾加 #<词条 id>（例如 #scroll-lock）会直接展开那一条。没有这个文件就不提，别给用户一个打不开的路径。

---

设计风格的边界

“苹果风”只表达设计方向，不自动等于 Bento、毛玻璃或 3D。只有用户描述了具体布局、材质或交互时才匹配相应词条；不在每段话术中追加 Skill 调用前缀。finesse-term 负责表达，设计执行由当前项目规范或可用的 UI Skill 决定。

8. 范围之外

• 后端、数据库、部署、构建工具的术语 —— 这个库只管看得见的那一层。
• 教学：不生成学习路线、课程计划、练习题、术语背诵清单。
• 不对用户已经说准确的话做任何修饰。「不用说」是本 Skill 最常见的正确输出。

---

9. 参考文件

• references/entry-format.md —— 词条的十个字段各是什么，trigger 和 trap 怎么写才有用，怎么加新词条
• references/retrieval.md —— 检索策略：子句拆分、噪音控制、命中为零时怎么办
• references/speaking.md —— 输出形态：三种场景的措辞模板，以及不该说话的那些时候