Memoh 前端规则
Memoh 前端对用户和维护者的承诺,以及每条承诺在本仓库中的实现方式。范围为
apps/web 和复用它的 Desktop 渲染层。没有前缀的路径均位于 apps/web/src/ 下;
引用其他文档的章节名保留英文原文,便于搜索。
使用方法
- 完整阅读本文件。
- 在规则索引中选出本次任务涉及的规则,按
references/rules.md目录中的行号只 阅读这几节,不默认读取所有参考文件;行号与内容不符时,按标题查找。 - 交接之前,按
references/review.md中对应规则的条目检查自己的 diff,再逐条 核对 D1–D4。
背景与目标
写 Memoh 前端的人背景各不相同:有前端工程师、平时只写后端的工程师、直接让 AI 生成 代码的人,以及每次会话都从零开始、只能靠当前读到的文档做判断的 agent。不管是谁写的, 合入后都必须像同一个产品。
这套规则起因于一个真实问题:有个列表没做缓存,每次点开都要空白等半秒。因为当时的文档 没写这条要求,写代码时也看不到提醒,顺手发个裸请求是最省事的写法。光靠批评作者只能修 这一处;只有把要求写成明确的规则,再把正确做法封装成最顺手的写法,所有人和 agent 才会 自然照着做。
这套规则同时解决三件事:
- 一致性:同一个概念在全站长相和交互完全一样。
- 开发效率:已经有的组件和逻辑直接拿来用,不重复造。
- 演进成本:今天写的代码不能给下次修改埋坑。这三件事里,演进成本最容易被忽略,也最关键。
以前这些分寸靠老同事带人和 Code Review 口头传授;现在写代码的人未必认识老同事,agent 更不会自己去猜潜规则。所以必须把判断标准白纸黑字写清楚,让完全没背景的读者和 agent 光靠这份文档就能推出正确做法。如果某条规则必须知道文档外的背景才能用对,说明规则本身 还没写透,要在交接说明里记一笔。
五条原则
后面的 22 条具体规则,全是从下面这五条原则推出来的。只有先看懂每条规则背后的原则,才 知道怎么在具体代码里拿捏分寸;遇到规则没写到的新场景,也靠这五条原则从零推导出做法。
绝不弄丢用户交给我们的数据,也绝不替用户乱动界面。 用户的密钥不能泄露,填了一半的表单和选好的配置不能被后台刷新冲掉,任何报错或空状态 都要给下一步出路,用户没点鼠标时绝不能擅自抢焦点或弹面板。用户把工作和密钥交给产品, 全靠信任;出一次事故信任就没了。(推出规则:U1、U2、U6、U7)
少让用户重新学、少让用户干等、少拿无关信息晃眼。 同一个东西在全站保持同一种长相和用法,用户学一次就会;已经看过的页面再点开要秒出, 不退回空白重新转圈;页面切换的每一帧都要排版完整,不能闪一下坏掉的画面;一屏只突出 一件事,手机窄屏、深浅色、中英日三语、断网重连和久开不关的标签页下都能正常工作。每多 造一种变体、多一次等待或多塞一个装饰,所有用户每次用都要多花精力。(推出规则:U4、U5、U8、U9、U10)
同一件事只留一个真源。 一种界面概念只由一个组件(owner)负责,一份服务端数据只走一条请求与缓存链路,一个 视觉数值只对应一个 token;浏览器原生或现有成熟库能干的事,绝不自己手写;多端共用的 代码只写一份,桌面端差异靠外部注入。一旦出现两份实现,改了 A 就会漏掉 B;在源头收口 只花一次功夫,散在各处维护会永远还债。(推出规则:M1、M2、M3、M4、M6)
今天写的代码,要让下个人好改。 组件接口只暴露当前真正在用的参数,不提前为假想需求留口子;同一个模式第二次出现时再抽 公共组件;修 bug 要修根因,不能打补丁掩盖症状;一次只改需求范围内的代码;当一个公共 组件开始塞进互相打架的特判时,立刻停手拆分。代码只写一次但会被改无数次,而且仓库里的 现有代码会被后续的人和 agent 当成样板照抄——留下一处脏写法,很快就会繁殖出十处。 (推出规则:M2、M5、M7、M8、D1)
不管是界面给用户的反馈,还是你给同事的交接,没确认的事绝不乱说。 界面上显示“已保存”就代表后端真落库了,显示“实时画面”就代表画面帧真到了;交接时说 “验证通过”就代表真跑过对应检查,改了哪些行为和默认值要逐条列清,加了豁免注释要写明 原因。本规则文档自己也守这一条:代码里还没做到的事,绝不在文档里假装已经做到。虚假的 “已保存”和虚假的“已测过”,都会害别人基于假消息做错决定。(推出规则:U3、D2、D3、D4)
规则的写法
每条规则管一类承诺,颗粒度卡在“能直接拿来判断新场景”。如果规则定得太碎(比如“聊天框不准 手写滚动条”),就只能堵住这一个坑,换个地方照样犯错;往上提一层写成“浏览器和现有库能做的 事,不自己手写”(M1),才能管住所有同类问题。
规则里举的例子故意挑了跨度很大的场景,用来帮你看清这条规则能管多宽,例子没点到的同类场景 一样要守规矩。
每条规则下面都列了“常见错误”——也就是图省事顺手写代码时最容易踩的坑。我们的终极目标是把 正确做法做成最省事的默认组件或 lint 检查,让想写错都难;每条规则末尾的“保证方式”都标明了 它现在到底有代码兜底,还是只能靠人眼盯。
依据来源
规则和实现的依据按下面的优先级查找。references/sources.md 列出哪些是官方的权威来源、
清单里没有时怎么找,以及每个领域该读哪几篇。
- 平台规范决定行为对不对:Android 与 Material 3、Apple HIG、Web 标准(WHATWG HTML、 WCAG 2.2、WAI-ARIA APG)。返回与手势、系统栏、焦点与无障碍这类用户在别的应用里早已习惯 的行为,先查这里。
- 本仓库所用框架和库的官方文档决定怎么实现:版本以
package.json锁定的为准,查对应 大版本的文档。库的维护方发布的 skill 与官方文档同级;社区或第三方发布的 skill 只当线索, 结论回到官方文档核对。官方文档没写清时,可以读该库自己的源码和官方 issue 确认实际行为。 - 同类成熟框架的官方文档作对照:例如同样在 WebView 里做应用的 Ionic,或 IBM Carbon 这类设计系统。引用时说明为什么适用于本仓库。
其他产品的源码与界面、博客与问答帖、模型自己推出的结论都不作为依据:它们可以提示该去查哪 篇规范,但不能代替规范本身。几级来源说法不一致时按 1 > 2 > 3 取舍,仍分不出就按下面的 「冲突处理」停下来问负责人。本仓库规则有意偏离平台规范时,在该条规则里写明偏离点和理由。
规则未覆盖的情况
遇到 22 条规则没直接写到的场景,按下面四步从头推导:
- 先看这件事触及上面“五条原则”里的哪几条。
- 如果几条原则方向冲突,按下面“冲突处理”的优先级排先后。
- 先去现有的组件库(
@felinic/ui)、业务组件字典(owner 词汇表)和样板页面里找现成做法; 确实没有现成方案时,按“需求的实现方式”第 3 条先跟负责人说清楚为什么现有组件装不下、打算 怎么拿基础组件拼,点头后再动手。 - 在交接说明里写明“此处无现成规则,按第 X 条原则推导处理”。如果你觉得这是个以后还会常遇到 的共性问题,把具体案例报给规则负责人,由负责人决定要不要加进规则。
如果机械照搬某条规则的字面意思,反而违背了它背后的那条大原则,先停下来说明冲突,按冲突 优先级处理,并写进交接说明。
规则与现有代码
本规则规定今后承诺的行为,但老代码和现有的检查脚本还没完全追上:仓库里有不少老代码还违反 这些规则,大部分规则目前也还没写成自动 lint,只能靠写代码和审代码时自觉遵守(每条规则末尾的 “保证方式”都如实标了现状)。因此在日常干活时:
- 新改的代码必须守规矩:你动到的地方不能比原来更差,但也不要为了顺手清技术债把无关文件 全改了(D1);路上看到的老问题记在交接说明里就行。
- 审查只抓增量问题:Code Review 只拦这次改动新惹出来或扩大的违规,并标上规则号(比如 “违反 M2”);老代码里本来就有的历史遗留不算在这次头上。
- 抄老代码前先看它合不合规:仓库里随便搜出来的老页面很可能是反面教材;找样板一律去抄
references/architecture.md(§ 认证样板参考页)里点名认证过的参考页。 - 清技术债单独开单:重构老代码要单独立项、单独提 PR,按 M8 的步骤拆小步走。
红线
下面 10 条是从五条原则里提出来的硬底线。只要踩中任意一条,不管其他代码写得多好,改动直接退回:
- 密钥绝不上前端存储或日志:绝不在界面、控制台(
console)或浏览器存储里露出密钥。(U1) - 绝不冲掉用户的输入:用户填了一半的内容和选好的配置绝不能弄丢,后台静默刷新绝不能覆盖它们。(U2)
- 绝不假报成功或吞掉报错:后端没成功绝不弹“已保存”,报错绝不能静默吞掉不提示。(U3)
- 接口和缓存只走唯一通道:调接口一律用
@memohai/sdk,服务端数据一律放 Pinia Colada;不准手写裸fetch,不准在页面里自己建缓存或自己维护一套loading变量。(M3) - 视觉样式只准用 Token:颜色、圆角、阴影、透明度、层级(z-index)一律用现有 token,不准手写裸色值或随意造数。(M4)
- 有现成组件绝不自己重造:
@felinic/ui或业务 owner 组件已经提供的东西,直接复用,不准自己手搓一套或复制出来改。(M2) - 所有界面文案三语齐全:给用户看的字一律走 i18n,
en、zh、ja三种语言一次补齐。(U8) - 不替用户乱动焦点和面板:只有用户自己点击或按键时,才能切焦点、开面板或切标签页;后台事件不准抢焦点。(U7)
- 桌面端绝不分叉 Web 代码:Desktop 直接复用
apps/web,公共路由只定义一次。(M6) - 没跑完验证不准报完成:拿不出 D3 要求的实测证据,就不算做完。(D3)
冲突处理
当两条要求打架时,按下面从 1 到 5 的顺序保大放小,排在前面的无条件优先:
- 先保用户的数据与安全:不泄密、不丢输入、不假报状态(U1–U3)。
- 不改坏没让你动的既有功能(D1)。
- 跟全站其他地方保持一致(U9、M2、M4)。
- 界面克制,不乱加东西(U10)。
- 最后才是“让当前这一页更好看”。
注意第 3 条排在第 5 条前面:全站统一比单页好看更重要。如果某个改动只能让当前这一页变好看, 却和全站其他页面长得不一样,要么把它做成公共组件的升级让全站一起变好看,要么就别做(M2)。 按这五步还分不出高下时,停下来问负责人,并把冲突记进交接说明。
需求的实现方式
平时提过来的需求,说的往往是“想要什么结果”(比如“这儿加个用量显示”“让按钮显眼点”“加个开关控制 X”), 而不是让你照着字面硬写代码:
- 先找现成零件:先去
@felinic/ui、业务组件字典(ui-owners)和认证样板页里找有没有干这件事的现成模式。注意提需求的人嘴里说的词(比如“加个横幅”),在代码里可能叫别的名字。 - 字面要求违规时,换合规做法实现目标:如果照着字面做会踩红线(比如让你直接写死一个大红框、自己新画一种卡片、或者后台自动弹出一个面板),用现有体系里合规的组件把目标做出来,再跟提需求的人解释为什么换了写法。
- 真没现成组件时,先对齐再动手:如果现有组件确实装不下这个需求,写代码前先说清楚为什么现有组件不行、打算怎么拿
@felinic/ui的基础零件拼;负责人同意后,先在当前页面里写,等第二个页面也要用时再抽成公共组件(M2),外观继续沿用现有的视觉语言。
规则索引
| 编号 | 规则 | 适用场景 | 当前保证方式 |
|---|---|---|---|
| U1 | 不泄露,不越权 | 显示、缓存、持久化或打印来自服务端、模型、工具、渠道或其他用户的数据;按权限控制控件 | 结构(部分) |
| U2 | 用户输入不丢失 | 用户输入、选择、上传或配置内容,尤其是同一屏的服务端数据会刷新时 | 结构(部分) |
| U3 | 界面显示的状态属实 | 显示状态、进度、成功、错误(包括 toast)、计数、“实时”标识或可能过期的数据 | 结构(部分) |
| U4 | 已获取的数据立即显示;加载反馈遵守固定时限 | 渲染服务端数据(列表、详情页、选择器、侧栏中的某个区块);进入对话界面(输入框首帧直出);等待请求或操作结果时显示加载状态 | 结构(部分);机械检查(部分) |
| U5 | 过渡中的每一帧都是有效画面 | 元素出现、消失、移动或替换:路由切换、列表与详情、弹窗、面板、加载状态切换为内容 | 文字 |
| U6 | 每个状态都提供后续操作;确认强度与后果相称 | 空、错误、失败、被阻止或部分完成的状态;会删除、覆盖、产生费用或无法撤销的操作 | 文字 |
| U7 | 用户控制 | 用户未点击时发生的操作;涉及焦点、面板、tab、滚动位置、历史记录或快捷键的改动 | 文字 |
| U8 | 在所有运行环境下成立 | 所有改动;尤其是新增文字、颜色、可交互元素、布局、新页面、长时间运行的视图或跨 tab 的状态;可访问性 | 机械检查(部分) |
| U9 | 同一概念在各处一致 | 要实现的元素在产品其他位置已经存在,或与已有元素相似 | 结构;机械检查(部分) |
| U10 | 克制:每屏一个重点,高级功能按需显示 | 增加任何可见元素:区块、徽标、提示、文案、按钮、设置项、强调色、动画 | 文字 |
| M1 | 优先使用平台,其次使用库,不自行实现 | 需要某种能力:弹层、焦点锁定、拖放、虚拟列表、防抖、媒体查询、剪贴板、日期、过渡 | 机械检查(部分) |
| M2 | 一个概念一个 owner | 编写组件、composable、store 或样式,或在原位置改进已有的实现 | 结构;机械检查(部分) |
| M3 | 服务端数据只有一条访问路径 | 读写服务端数据、定义查询 key、显示其加载或错误状态,或同一份数据需要在两处使用 | 机械检查(部分) |
| M4 | 视觉取值来自档位 | 编写任何颜色、尺寸、间距、圆角、边框、阴影、透明度、z-index、时长或字体取值 | 机械检查(部分) |
| M5 | 修复根因 | 修复 bug、视觉缺陷或失败的检查 | 文字 |
| M6 | 保持分发边界 | 修改的代码被多个宿主或版本使用,或要增加只属于某个宿主或版本的行为 | 结构;机械检查(部分) |
| M7 | 性能有预算,失败可追溯 | 增加依赖、重型组件、长列表、轮询、输入事件处理或新的失败路径 | 文字 |
| M8 | owner 保持可修改 | 为 owner 增加 prop、特例或调用处覆盖;发现 owner 难以修改 | 文字 |
| D1 | 只改动需求范围内的内容 | 交接任何改动之前 | 文字 |
| D2 | 逐项列出行为、外观和默认值的改动 | 交接任何改动之前 | 文字 |
| D3 | 声明不超过证据 | 交接任何改动之前 | 文字 |
| D4 | 检查全部通过;每个豁免都写明理由 | 交接任何改动之前 | 机械检查 |
模型默认惯性写法 vs 本仓替换做法
Agent 与不熟悉本仓的开发者顺手写代码时,最容易写出左列的默认写法;动笔前先核对下表,一律改用右列做法:
| 顺手写出的默认做法(禁止) | 本仓标准替换做法 | 对应规则 |
|---|---|---|
onMounted(async () => { list.value = await getX() }) 或手写 fetch('/api/...') |
用 @memohai/sdk 配 Pinia Colada useQuery / useMutation,变更后 invalidateQueries |
M3、U4 |
把骨架屏或整个页面内容绑在 v-if="isLoading" 上 |
骨架屏只绑 isPending(无缓存数据);isLoading 仅作后台刷新微指示 |
U4 |
| 对话页等用户信息、Bot、会话列表或历史加载完才渲染或启用输入框 | 输入框首帧立即渲染并可打字(Composer-First),加载期间只拦发送(handleSend) |
U4、U7 |
watch(() => query.data.value, d => Object.assign(form, d)) 直接覆盖表单 |
用 useServerSyncedRecord / useServerSyncedScalar 保护用户未保存的草稿 |
U2 |
toast.error(err.message) 直接把服务端 message/detail 弹给用户,或拿错误文案做 if 分支 |
展示用 resolveApiErrorMessage(err, fallback)(只走 errors.<code> 与状态码兜底);分支判断用 isApiErrorCode |
U3 |
给带操作按钮(action)的 Toast 使用默认 4s 自动消失 |
带按钮的 Toast 显式传 duration: 8000 或 duration: Infinity |
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、M2 |
手写 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、U4 |
在业务页面直接 import { ... } from 'reka-ui' 或在共享 store 里 import router from '@/router' |
只通过 @felinic/ui 消费无头原语;共享 store 使用宿主注入的 router 与 DesktopShellKey |
M1、M6 |
后台 SSE/WS 事件到来时直接调 focusPanel / activateChatSession 切走用户当前面板 |
后台只静默更新对应 tab 数据,需要跳转做成显式按钮由用户点击 | 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 | 查阅 apps/web 目录地图、认证样板参考页、路由与三层常驻布局、Store 分工、WebSocket/SSE 流式契约与工作区面板边界。 |
| rules.md | 需要某条规则的完整内容:原因、本仓库的实现、常见错误、边界和自查方法。先阅读它的目录。 |
| review.md | 交接前检查自己的 diff,或审查他人的前端改动。 |
| upkeep.md | 记录违规,或提议新增、修改、升级规则。 |
| sources.md | 为规则或实现找依据:官方来源清单、清单里没有时怎么找、按领域查找,以及各库的 llms.txt 与官方 skill。 |
| scripts/check-contrast.mjs | 计算 OKLCH 颜色与半透明叠加后的对比度,或输出深浅色模式与 shadcn 默认主题的基线对比表(重构组件库颜色时直接运行 node scripts/check-contrast.mjs)。 |