# Memoh Frontend Rules

> Memoh 前端对用户和维护者的承诺：红线、冲突处理顺序，以及每条承诺在本仓库中的 实现方式。在 apps/web 或 Desktop 渲染层编写、修改或审查代码时使用：页面、 组件、composable、store、服务端数据、路由、i18n、流式传输。不用于 @felinic/ui 的 token 和视觉（使用 packages/ui 的 skill）、后端代码，或只修改 文档的工作。

- Skill: `tuyv/memoh-frontend-rules` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add tuyv/memoh-frontend-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/memoh-frontend-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tuyv (https://skillmd.com/u/tuyv)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/tuyv/memoh-frontend-rules

---


# Memoh 前端规则

Memoh 前端对用户和维护者的承诺，以及每条承诺在本仓库中的实现方式。范围为
`apps/web` 和复用它的 Desktop 渲染层。没有前缀的路径均位于 `apps/web/src/` 下；
引用其他文档的章节名保留英文原文，便于搜索。

## 使用方法

1. 完整阅读本文件。
2. 在规则索引中选出本次任务涉及的规则，按 `references/rules.md` 目录中的行号只
   阅读这几节，不默认读取所有参考文件；行号与内容不符时，按标题查找。
3. 交接之前，按 `references/review.md` 中对应规则的条目检查自己的 diff，再逐条
   核对 D1–D4。

## 背景与目标

写 Memoh 前端的人背景各不相同：有前端工程师、平时只写后端的工程师、直接让 AI 生成
代码的人，以及每次会话都从零开始、只能靠当前读到的文档做判断的 agent。不管是谁写的，
合入后都必须像同一个产品。

这套规则起因于一个真实问题：有个列表没做缓存，每次点开都要空白等半秒。因为当时的文档
没写这条要求，写代码时也看不到提醒，顺手发个裸请求是最省事的写法。光靠批评作者只能修
这一处；只有把要求写成明确的规则，再把正确做法封装成最顺手的写法，所有人和 agent 才会
自然照着做。

这套规则同时解决三件事：
1. **一致性**：同一个概念在全站长相和交互完全一样。
2. **开发效率**：已经有的组件和逻辑直接拿来用，不重复造。
3. **演进成本**：今天写的代码不能给下次修改埋坑。这三件事里，演进成本最容易被忽略，也最关键。

以前这些分寸靠老同事带人和 Code Review 口头传授；现在写代码的人未必认识老同事，agent
更不会自己去猜潜规则。所以必须把判断标准白纸黑字写清楚，让完全没背景的读者和 agent
光靠这份文档就能推出正确做法。如果某条规则必须知道文档外的背景才能用对，说明规则本身
还没写透，要在交接说明里记一笔。

## 五条原则

后面的 22 条具体规则，全是从下面这五条原则推出来的。只有先看懂每条规则背后的原则，才
知道怎么在具体代码里拿捏分寸；遇到规则没写到的新场景，也靠这五条原则从零推导出做法。

1. **绝不弄丢用户交给我们的数据，也绝不替用户乱动界面。**
   用户的密钥不能泄露，填了一半的表单和选好的配置不能被后台刷新冲掉，任何报错或空状态
   都要给下一步出路，用户没点鼠标时绝不能擅自抢焦点或弹面板。用户把工作和密钥交给产品，
   全靠信任；出一次事故信任就没了。（推出规则：U1、U2、U6、U7）

2. **少让用户重新学、少让用户干等、少拿无关信息晃眼。**
   同一个东西在全站保持同一种长相和用法，用户学一次就会；已经看过的页面再点开要秒出，
   不退回空白重新转圈；页面切换的每一帧都要排版完整，不能闪一下坏掉的画面；一屏只突出
   一件事，手机窄屏、深浅色、中英日三语、断网重连和久开不关的标签页下都能正常工作。每多
   造一种变体、多一次等待或多塞一个装饰，所有用户每次用都要多花精力。（推出规则：U4、U5、U8、U9、U10）

3. **同一件事只留一个真源。**
   一种界面概念只由一个组件（owner）负责，一份服务端数据只走一条请求与缓存链路，一个
   视觉数值只对应一个 token；浏览器原生或现有成熟库能干的事，绝不自己手写；多端共用的
   代码只写一份，桌面端差异靠外部注入。一旦出现两份实现，改了 A 就会漏掉 B；在源头收口
   只花一次功夫，散在各处维护会永远还债。（推出规则：M1、M2、M3、M4、M6）

4. **今天写的代码，要让下个人好改。**
   组件接口只暴露当前真正在用的参数，不提前为假想需求留口子；同一个模式第二次出现时再抽
   公共组件；修 bug 要修根因，不能打补丁掩盖症状；一次只改需求范围内的代码；当一个公共
   组件开始塞进互相打架的特判时，立刻停手拆分。代码只写一次但会被改无数次，而且仓库里的
   现有代码会被后续的人和 agent 当成样板照抄——留下一处脏写法，很快就会繁殖出十处。
   （推出规则：M2、M5、M7、M8、D1）

5. **不管是界面给用户的反馈，还是你给同事的交接，没确认的事绝不乱说。**
   界面上显示“已保存”就代表后端真落库了，显示“实时画面”就代表画面帧真到了；交接时说
   “验证通过”就代表真跑过对应检查，改了哪些行为和默认值要逐条列清，加了豁免注释要写明
   原因。本规则文档自己也守这一条：代码里还没做到的事，绝不在文档里假装已经做到。虚假的
   “已保存”和虚假的“已测过”，都会害别人基于假消息做错决定。（推出规则：U3、D2、D3、D4）

## 规则的写法

每条规则管一类承诺，颗粒度卡在“能直接拿来判断新场景”。如果规则定得太碎（比如“聊天框不准
手写滚动条”），就只能堵住这一个坑，换个地方照样犯错；往上提一层写成“浏览器和现有库能做的
事，不自己手写”（M1），才能管住所有同类问题。

规则里举的例子故意挑了跨度很大的场景，用来帮你看清这条规则能管多宽，例子没点到的同类场景
一样要守规矩。

每条规则下面都列了“常见错误”——也就是图省事顺手写代码时最容易踩的坑。我们的终极目标是把
正确做法做成最省事的默认组件或 lint 检查，让想写错都难；每条规则末尾的“保证方式”都标明了
它现在到底有代码兜底，还是只能靠人眼盯。

## 依据来源

规则和实现的依据按下面的优先级查找。`references/sources.md` 列出哪些是官方的权威来源、
清单里没有时怎么找，以及每个领域该读哪几篇。

1. **平台规范决定行为对不对**：Android 与 Material 3、Apple HIG、Web 标准（WHATWG HTML、
   WCAG 2.2、WAI-ARIA APG）。返回与手势、系统栏、焦点与无障碍这类用户在别的应用里早已习惯
   的行为，先查这里。
2. **本仓库所用框架和库的官方文档决定怎么实现**：版本以 `package.json` 锁定的为准，查对应
   大版本的文档。库的维护方发布的 skill 与官方文档同级；社区或第三方发布的 skill 只当线索，
   结论回到官方文档核对。官方文档没写清时，可以读该库自己的源码和官方 issue 确认实际行为。
3. **同类成熟框架的官方文档作对照**：例如同样在 WebView 里做应用的 Ionic，或 IBM Carbon
   这类设计系统。引用时说明为什么适用于本仓库。

其他产品的源码与界面、博客与问答帖、模型自己推出的结论都不作为依据：它们可以提示该去查哪
篇规范，但不能代替规范本身。几级来源说法不一致时按 1 > 2 > 3 取舍，仍分不出就按下面的
「冲突处理」停下来问负责人。本仓库规则有意偏离平台规范时，在该条规则里写明偏离点和理由。

## 规则未覆盖的情况

遇到 22 条规则没直接写到的场景，按下面四步从头推导：

1. 先看这件事触及上面“五条原则”里的哪几条。
2. 如果几条原则方向冲突，按下面“冲突处理”的优先级排先后。
3. 先去现有的组件库（`@felinic/ui`）、业务组件字典（owner 词汇表）和样板页面里找现成做法；
   确实没有现成方案时，按“需求的实现方式”第 3 条先跟负责人说清楚为什么现有组件装不下、打算
   怎么拿基础组件拼，点头后再动手。
4. 在交接说明里写明“此处无现成规则，按第 X 条原则推导处理”。如果你觉得这是个以后还会常遇到
   的共性问题，把具体案例报给规则负责人，由负责人决定要不要加进规则。

如果机械照搬某条规则的字面意思，反而违背了它背后的那条大原则，先停下来说明冲突，按冲突
优先级处理，并写进交接说明。

## 规则与现有代码

本规则规定今后承诺的行为，但老代码和现有的检查脚本还没完全追上：仓库里有不少老代码还违反
这些规则，大部分规则目前也还没写成自动 lint，只能靠写代码和审代码时自觉遵守（每条规则末尾的
“保证方式”都如实标了现状）。因此在日常干活时：

- **新改的代码必须守规矩**：你动到的地方不能比原来更差，但也不要为了顺手清技术债把无关文件
  全改了（D1）；路上看到的老问题记在交接说明里就行。
- **审查只抓增量问题**：Code Review 只拦这次改动新惹出来或扩大的违规，并标上规则号（比如
  “违反 M2”）；老代码里本来就有的历史遗留不算在这次头上。
- **抄老代码前先看它合不合规**：仓库里随便搜出来的老页面很可能是反面教材；找样板一律去抄
  `references/architecture.md`（§ 认证样板参考页）里点名认证过的参考页。
- **清技术债单独开单**：重构老代码要单独立项、单独提 PR，按 M8 的步骤拆小步走。

## 红线

下面 10 条是从五条原则里提出来的硬底线。只要踩中任意一条，不管其他代码写得多好，改动直接退回：

1. **密钥绝不上前端存储或日志**：绝不在界面、控制台（`console`）或浏览器存储里露出密钥。（U1）
2. **绝不冲掉用户的输入**：用户填了一半的内容和选好的配置绝不能弄丢，后台静默刷新绝不能覆盖它们。（U2）
3. **绝不假报成功或吞掉报错**：后端没成功绝不弹“已保存”，报错绝不能静默吞掉不提示。（U3）
4. **接口和缓存只走唯一通道**：调接口一律用 `@memohai/sdk`，服务端数据一律放 Pinia Colada；不准手写裸 `fetch`，不准在页面里自己建缓存或自己维护一套 `loading` 变量。（M3）
5. **视觉样式只准用 Token**：颜色、圆角、阴影、透明度、层级（z-index）一律用现有 token，不准手写裸色值或随意造数。（M4）
6. **有现成组件绝不自己重造**：`@felinic/ui` 或业务 owner 组件已经提供的东西，直接复用，不准自己手搓一套或复制出来改。（M2）
7. **所有界面文案三语齐全**：给用户看的字一律走 i18n，`en`、`zh`、`ja` 三种语言一次补齐。（U8）
8. **不替用户乱动焦点和面板**：只有用户自己点击或按键时，才能切焦点、开面板或切标签页；后台事件不准抢焦点。（U7）
9. **桌面端绝不分叉 Web 代码**：Desktop 直接复用 `apps/web`，公共路由只定义一次。（M6）
10. **没跑完验证不准报完成**：拿不出 D3 要求的实测证据，就不算做完。（D3）

## 冲突处理

当两条要求打架时，按下面从 1 到 5 的顺序保大放小，排在前面的无条件优先：

1. **先保用户的数据与安全**：不泄密、不丢输入、不假报状态（U1–U3）。
2. **不改坏没让你动的既有功能**（D1）。
3. **跟全站其他地方保持一致**（U9、M2、M4）。
4. **界面克制，不乱加东西**（U10）。
5. **最后才是“让当前这一页更好看”**。

注意第 3 条排在第 5 条前面：**全站统一比单页好看更重要**。如果某个改动只能让当前这一页变好看，
却和全站其他页面长得不一样，要么把它做成公共组件的升级让全站一起变好看，要么就别做（M2）。
按这五步还分不出高下时，停下来问负责人，并把冲突记进交接说明。

## 需求的实现方式

平时提过来的需求，说的往往是“想要什么结果”（比如“这儿加个用量显示”“让按钮显眼点”“加个开关控制 X”），
而不是让你照着字面硬写代码：

1. **先找现成零件**：先去 `@felinic/ui`、业务组件字典（`ui-owners`）和认证样板页里找有没有干这件事的现成模式。注意提需求的人嘴里说的词（比如“加个横幅”），在代码里可能叫别的名字。
2. **字面要求违规时，换合规做法实现目标**：如果照着字面做会踩红线（比如让你直接写死一个大红框、自己新画一种卡片、或者后台自动弹出一个面板），用现有体系里合规的组件把目标做出来，再跟提需求的人解释为什么换了写法。
3. **真没现成组件时，先对齐再动手**：如果现有组件确实装不下这个需求，写代码前先说清楚为什么现有组件不行、打算怎么拿 `@felinic/ui` 的基础零件拼；负责人同意后，先在当前页面里写，等第二个页面也要用时再抽成公共组件（M2），外观继续沿用现有的视觉语言。

## 规则索引

| 编号 | 规则 | 适用场景 | 当前保证方式 |
|---|---|---|---|
| [U1](references/rules.md#u1-不泄露不越权) | 不泄露，不越权 | 显示、缓存、持久化或打印来自服务端、模型、工具、渠道或其他用户的数据；按权限控制控件 | 结构（部分） |
| [U2](references/rules.md#u2-用户输入不丢失) | 用户输入不丢失 | 用户输入、选择、上传或配置内容，尤其是同一屏的服务端数据会刷新时 | 结构（部分） |
| [U3](references/rules.md#u3-界面显示的状态属实) | 界面显示的状态属实 | 显示状态、进度、成功、错误（包括 toast）、计数、“实时”标识或可能过期的数据 | 结构（部分） |
| [U4](references/rules.md#u4-已获取的数据立即显示加载反馈遵守固定时限) | 已获取的数据立即显示；加载反馈遵守固定时限 | 渲染服务端数据（列表、详情页、选择器、侧栏中的某个区块）；进入对话界面（输入框首帧直出）；等待请求或操作结果时显示加载状态 | 结构（部分）；机械检查（部分） |
| [U5](references/rules.md#u5-过渡中的每一帧都是有效画面) | 过渡中的每一帧都是有效画面 | 元素出现、消失、移动或替换：路由切换、列表与详情、弹窗、面板、加载状态切换为内容 | 文字 |
| [U6](references/rules.md#u6-每个状态都提供后续操作确认强度与后果相称) | 每个状态都提供后续操作；确认强度与后果相称 | 空、错误、失败、被阻止或部分完成的状态；会删除、覆盖、产生费用或无法撤销的操作 | 文字 |
| [U7](references/rules.md#u7-用户控制) | 用户控制 | 用户未点击时发生的操作；涉及焦点、面板、tab、滚动位置、历史记录或快捷键的改动 | 文字 |
| [U8](references/rules.md#u8-在所有运行环境下成立) | 在所有运行环境下成立 | 所有改动；尤其是新增文字、颜色、可交互元素、布局、新页面、长时间运行的视图或跨 tab 的状态；可访问性 | 机械检查（部分） |
| [U9](references/rules.md#u9-同一概念在各处一致) | 同一概念在各处一致 | 要实现的元素在产品其他位置已经存在，或与已有元素相似 | 结构；机械检查（部分） |
| [U10](references/rules.md#u10-克制每屏一个重点高级功能按需显示) | 克制：每屏一个重点，高级功能按需显示 | 增加任何可见元素：区块、徽标、提示、文案、按钮、设置项、强调色、动画 | 文字 |
| [M1](references/rules.md#m1-优先使用平台其次使用库不自行实现) | 优先使用平台，其次使用库，不自行实现 | 需要某种能力：弹层、焦点锁定、拖放、虚拟列表、防抖、媒体查询、剪贴板、日期、过渡 | 机械检查（部分） |
| [M2](references/rules.md#m2-一个概念一个-owner) | 一个概念一个 owner | 编写组件、composable、store 或样式，或在原位置改进已有的实现 | 结构；机械检查（部分） |
| [M3](references/rules.md#m3-服务端数据只有一条访问路径) | 服务端数据只有一条访问路径 | 读写服务端数据、定义查询 key、显示其加载或错误状态，或同一份数据需要在两处使用 | 机械检查（部分） |
| [M4](references/rules.md#m4-视觉取值来自档位) | 视觉取值来自档位 | 编写任何颜色、尺寸、间距、圆角、边框、阴影、透明度、z-index、时长或字体取值 | 机械检查（部分） |
| [M5](references/rules.md#m5-修复根因) | 修复根因 | 修复 bug、视觉缺陷或失败的检查 | 文字 |
| [M6](references/rules.md#m6-保持分发边界) | 保持分发边界 | 修改的代码被多个宿主或版本使用，或要增加只属于某个宿主或版本的行为 | 结构；机械检查（部分） |
| [M7](references/rules.md#m7-性能有预算失败可追溯) | 性能有预算，失败可追溯 | 增加依赖、重型组件、长列表、轮询、输入事件处理或新的失败路径 | 文字 |
| [M8](references/rules.md#m8-owner-保持可修改) | owner 保持可修改 | 为 owner 增加 prop、特例或调用处覆盖；发现 owner 难以修改 | 文字 |
| [D1](references/rules.md#d1-只改动需求范围内的内容) | 只改动需求范围内的内容 | 交接任何改动之前 | 文字 |
| [D2](references/rules.md#d2-逐项列出行为外观和默认值的改动) | 逐项列出行为、外观和默认值的改动 | 交接任何改动之前 | 文字 |
| [D3](references/rules.md#d3-声明不超过证据) | 声明不超过证据 | 交接任何改动之前 | 文字 |
| [D4](references/rules.md#d4-检查全部通过每个豁免都写明理由) | 检查全部通过；每个豁免都写明理由 | 交接任何改动之前 | 机械检查 |

## 模型默认惯性写法 vs 本仓替换做法

Agent 与不熟悉本仓的开发者顺手写代码时，最容易写出左列的默认写法；动笔前先核对下表，一律改用右列做法：

| 顺手写出的默认做法（禁止） | 本仓标准替换做法 | 对应规则 |
|---|---|---|
| `onMounted(async () => { list.value = await getX() })` 或手写 `fetch('/api/...')` | 用 `@memohai/sdk` 配 Pinia Colada `useQuery` / `useMutation`，变更后 `invalidateQueries` | [M3](references/rules.md#m3-服务端数据只有一条访问路径)、[U4](references/rules.md#u4-已获取的数据立即显示加载反馈遵守固定时限) |
| 把骨架屏或整个页面内容绑在 `v-if="isLoading"` 上 | 骨架屏只绑 `isPending`（无缓存数据）；`isLoading` 仅作后台刷新微指示 | [U4](references/rules.md#u4-已获取的数据立即显示加载反馈遵守固定时限) |
| 对话页等用户信息、Bot、会话列表或历史加载完才渲染或启用输入框 | 输入框首帧立即渲染并可打字（Composer-First），加载期间只拦发送（`handleSend`） | [U4](references/rules.md#u4-已获取的数据立即显示加载反馈遵守固定时限)、[U7](references/rules.md#u7-用户控制) |
| `watch(() => query.data.value, d => Object.assign(form, d))` 直接覆盖表单 | 用 `useServerSyncedRecord` / `useServerSyncedScalar` 保护用户未保存的草稿 | [U2](references/rules.md#u2-用户输入不丢失) |
| `toast.error(err.message)` 直接把服务端 `message`/`detail` 弹给用户，或拿错误文案做 `if` 分支 | 展示用 `resolveApiErrorMessage(err, fallback)`（只走 `errors.<code>` 与状态码兜底）；分支判断用 `isApiErrorCode` | [U3](references/rules.md#u3-界面显示的状态属实) |
| 给带操作按钮（`action`）的 Toast 使用默认 4s 自动消失 | 带按钮的 Toast 显式传 `duration: 8000` 或 `duration: Infinity` | [U3](references/rules.md#u3-界面显示的状态属实) |
| 手写 `<div class="rounded-xl border bg-card p-4">` 或 `<div class="flex justify-between py-3 border-b">` | 直接组合 `@felinic/ui` 原语：`PageShell`、`SettingsSection`、`SettingsRow`、`FieldStack`、`DialogPanel` | [U9](references/rules.md#u9-同一概念在各处一致)、[M2](references/rules.md#m2-一个概念一个-owner) |
| 手写 `bg-muted/40`、`border-border/60`、`text-[13px]`、`z-50`、`animate-spin` | 用语义 Token（`bg-muted-soft`、`border-border-soft`、`text-label`、`z-(--z-overlay)`）与四级加载组件 | [M4](references/rules.md#m4-视觉取值来自档位)、[U4](references/rules.md#u4-已获取的数据立即显示加载反馈遵守固定时限) |
| 在业务页面直接 `import { ... } from 'reka-ui'` 或在共享 store 里 `import router from '@/router'` | 只通过 `@felinic/ui` 消费无头原语；共享 store 使用宿主注入的 router 与 `DesktopShellKey` | [M1](references/rules.md#m1-优先使用平台其次使用库不自行实现)、[M6](references/rules.md#m6-保持分发边界) |
| 后台 SSE/WS 事件到来时直接调 `focusPanel` / `activateChatSession` 切走用户当前面板 | 后台只静默更新对应 tab 数据，需要跳转做成显式按钮由用户点击 | [U7](references/rules.md#u7-用户控制) |

## 相关指南

| 任务 | 相关文档 |
|---|---|
| 修改控件外观；修改 token、颜色、圆角、边框、阴影、动效 | `packages/ui/AGENTS.md`（设计契约） |
| 新建或修改页面、设置页、弹窗、表单、保存、文案、空状态或实时状态面板 | `packages/ui/skills/ui-patterns/SKILL.md`（ui-patterns skill） |
| 实现行、字段、分组卡片、数值卡、提示条、删除确认或页面框架 | `packages/ui/skills/ui-owners/SKILL.md`（ui-owners skill） |
| 为 owner 增加 prop；拆分或弃用 owner | ui-owners skill；本规则 M2、M8 |
| 获取、缓存或修改服务端数据；新增 store；修改路由、i18n、流式传输 | `references/architecture.md`；本规则 U2–U4、M3 |
| 显示错误，或根据错误进行分支判断 | `.agents/skills/memoh-error-handling/SKILL.md`；本规则 U3 |
| 修改 Desktop 专属功能 | `apps/desktop/AGENTS.md`；本规则 M6 |
| 提交 PR、验证、截图、报告 QA | 根目录 `AGENTS.md`；本规则 D1–D4 |

## 参考文件

| 参考文件 | 适用场景 |
|---|---|
| [architecture.md](references/architecture.md) | 查阅 `apps/web` 目录地图、认证样板参考页、路由与三层常驻布局、Store 分工、WebSocket/SSE 流式契约与工作区面板边界。 |
| [rules.md](references/rules.md) | 需要某条规则的完整内容：原因、本仓库的实现、常见错误、边界和自查方法。先阅读它的目录。 |
| [review.md](references/review.md) | 交接前检查自己的 diff，或审查他人的前端改动。 |
| [upkeep.md](references/upkeep.md) | 记录违规，或提议新增、修改、升级规则。 |
| [sources.md](references/sources.md) | 为规则或实现找依据：官方来源清单、清单里没有时怎么找、按领域查找，以及各库的 llms.txt 与官方 skill。 |
| [scripts/check-contrast.mjs](scripts/check-contrast.mjs) | 计算 OKLCH 颜色与半透明叠加后的对比度，或输出深浅色模式与 shadcn 默认主题的基线对比表（重构组件库颜色时直接运行 `node scripts/check-contrast.mjs`）。 |

