CODEX KNOWLEDGE

Mortis 页面扩展与上线操作经验（2026-04-20）

2026/04/24 18 min read CODEX KNOWLEDGE 目录 CODEX KNOWLEDGE 类 产品方案 项目 MORTIS 形态 记录 MORTIS 页面扩展与上线操作经验（2026 04 20）

Mortis 页面扩展与上线操作经验（2026-04-20）

适用范围

本文记录本轮 https://mortis.tengokukk.com 的页面扩展、零星英文清理、真源仓库提交、服务器部署与浏览器验收过程，供后续继续维护 Mortis 私有站时直接复用。

一、先确认真源，不要在镜像或临时副本里误改

本轮 Mortis 的真实开发边界不在 Atramenti-Console 主仓，而在独立真源仓库：

  • 真源仓库：C:\Users\ASUS-KL\.codex\.tmp\mortis-multica-source-working
  • 线上部署目录：/srv/multica
  • 站点地址：https://mortis.tengokukk.com

实操原则：

  1. 先确认被改文件属于哪个 repo，再开始编辑。
  2. 不要因为当前 shell 停在别的目录，就顺手在父仓或备份仓里改同名文件。
  3. 如果本地存在多个 Mortis 副本，先用 git remote -v、git status、目标文件实际路径三件套确认真实 owning repo。
  4. 提交和推送也必须在这个真源仓库内完成，不能只改本地快照。

二、开始改之前，先看边界，避免混入无关改动

本轮用户目标很明确：继续清理 Mortis 站内残留英文，并保持页面正常上线。因此边界应限制在：

  • 文案配置
  • 页面 copy
  • 必要的状态标签映射
  • 与本轮汉化直接相关的视图文件

建议流程：

  1. 先看 git status --short，识别已有改动。
  2. 只读取与当前页面、当前文案直接相关的文件。
  3. 若仓库里已有别的未收口改动，不回滚、不顺手重构，也不要把无关文件一起提交。
  4. 提交前用路径级 git diff -- <path> 再确认一次本轮边界。

本轮实践证明，这一步非常重要。Mortis 真源仓库可能同时承载其他开发中的改动，如果不先收紧边界，很容易把不相关工作一起带上。

三、定位未汉化文案的高效方式

1. 先从线上可见页面反查

优先浏览这些页面：

  • /mortis/overview
  • /mortis/servers
  • /mortis/deployments
  • /mortis/domains
  • /mortis/settings
  • /mortis/agents

做法：

  1. 用浏览器逐页查看是否存在明显英文标签、按钮、说明文字、状态值。
  2. 先记“用户直接能看到、会造成割裂感”的英文，再回仓库定位。
  3. 不要一开始就全仓盲搜英文单词，否则噪音很大。

2. 再回代码搜关键英文

定位残留文案时，优先搜索这些模式：

  • 页面标题或 tab 名称
  • 表单 label
  • button 文案
  • toast 提示
  • badge / status label
  • note / warning / helper text
  • 配置枚举映射

本轮有效命中点包括：

  • packages/views/settings/components/account-tab.tsx
  • packages/views/agents/config.ts
  • packages/views/control-plane/components/control-plane-page.tsx

3. 优先查“映射层”而不是只查 JSX 表面文本

很多页面不是把英文直接写在页面结构里，而是来自：

  • 状态映射表
  • 配置对象
  • 统一 label 函数
  • control-plane summary 的展示映射

本轮智能体状态和控制面标签就属于这种情况。如果只在页面组件里搜字符串，容易漏掉真正的 copy 来源。

四、哪些内容不要机械翻译

不是所有英文都应该一股脑改成中文。后续维护时，默认按下面规则处理：

应优先汉化的内容

  • 页面标题
  • 导航项
  • 表单字段名
  • 按钮文字
  • toast / 提示
  • 说明性副文案
  • 面向操作者的状态标签

应保留英文或谨慎处理的内容

  • 品牌名、产品名、专有名词，例如 Mortis、Codex、OpenClaw、NapCat
  • 任务类型 key、配置 key、路径、URL、协议字段
  • 真实执行产出、日志片段、错误原文
  • 用户正文、评论正文、任务描述正文
  • 运行时标识、短 ID、host key、deploy key 等工程主键

判断原则：

  • 面向人阅读的操作文案，优先中文。
  • 面向系统识别的标识与结构字段，优先保留原文。
  • 如果一段文字同时承担“显示 + 主键”双重作用，优先不要翻译 key，只翻译展示层。

五、本轮实际清理掉的残留英文类型

本轮已收口的典型内容包括：

  • 设置页 Profile、头像上传提示、Name、更新资料按钮与 toast
  • 智能体状态：Idle / Working / Blocked / Error / Offline
  • 任务分发状态：Queued / Dispatched / Running / Completed / Failed / Cancelled
  • 控制面页中的说明文案、告警文案、摘要标签、owner type 展示名
  • Repo Root / Control Plane Root / Dispatcher / Target / Fallback / Host / URL / DERIVED 等关键展示标签

对应提交：

  • Mortis 真源仓库提交：49dfc21
  • 提交说明：fix: localize mortis control plane copy

六、修改后的本地校验方式

前端 copy 修改后，至少要做一轮最小类型校验，避免因为文案改动牵出 TS 问题。

本轮使用：

pnpm --filter @multica/views typecheck

经验：

  1. 文案改动虽然看似简单，但 control-plane 页面常有复杂对象映射，容易被类型系统卡住。
  2. 优先跑最小作用域的 package 校验，比全仓构建更快，更适合 copy 收尾。
  3. 如果只是某个页面的映射层改动，先保证 typecheck 过，再决定要不要补更重的验证。

七、服务器部署流程

Mortis 当前线上更新流程已经比较固定，可直接复用：

ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new ubuntu@124.220.233.126 "set -e; cd /srv/multica; git fetch origin main; git checkout main; git pull --ff-only origin main; sudo docker compose -f docker-compose.selfhost.yml build frontend; sudo docker compose -f docker-compose.selfhost.yml up -d frontend"

要点：

  1. 先 git fetch + git pull --ff-only，避免在服务器上产生额外合并提交。
  2. 仅重建 frontend，不要无关扩散到整套 compose。
  3. 用 up -d frontend 让页面更新落到在线容器。
  4. 如果远端 main 领先于本地预期，不要惊慌；先确认这是不是远端正常已有提交，再继续部署。

本轮就出现过服务器 git pull 一次性拉到不止一个提交的情况，属于远端现状，不应误判为异常。

八、浏览器验收流程

Mortis 这种用户可见页面，不能只看构建成功或 HTTP 200。

本轮验收遵循：

  1. 刷新目标页面。
  2. 等页面真正渲染出主内容，而不是只看到页头。
  3. 直接检查用户可见文案是否已变成中文。
  4. 对关键页做快照留证。

建议至少验这些页：

  • /mortis/settings
  • /mortis/servers
  • /mortis/overview
  • /mortis/agents

本轮已明确看到并确认生效的例子：

  • 设置页：个人资料、点击上传头像、名称、更新资料
  • 服务器页：主机、公网控制台摘要、中文化后的备注说明、缺失状态提示
  • 总览页：控制面摘要和接入状态说明已为中文展示

九、本轮踩坑与经验

1. 不要假设英文一定写在页面组件表层

控制面页面的大量英文实际来自映射表和 summary label 组合层，而不是单个 JSX 节点。遇到页面零星英文时，优先追配置映射和 helper 层。

2. 浏览器 reload 后可能暂时只剩页头

Mortis 某些页面在 reload 后会短暂只显示壳层，主内容稍后才回来。验收时不要只因为第一次 snapshot 看起来空，就立即判定页面坏了；应配合等待正文文本出现。

3. agents 页可能受数据状态影响

/mortis/agents 最后一次浏览器 reload 时出现过空 main 区域，但本地映射文案已经修改完成。遇到这种情况，应区分：

  • 是 copy 没改到
  • 还是页面数据当下没渲染出来

不要把数据瞬时态误判成汉化失败。

4. 部署阶段不要把远端快进误认为脏状态

服务器 git pull 过程中如果 fast-forward 到多个 commit，先确认是否只是远端本来就比本地预期多几个提交。只要是正常远端历史，就继续部署，不要贸然回滚。

十、后续继续扫 Mortis 零星英文时的推荐顺序

建议固定按下面顺序继续：

  1. 线上逐页巡检，先记可见问题。
  2. 回真源仓库搜对应页面与映射层。
  3. 只改展示层，不动 key 与结构字段。
  4. 跑最小 typecheck。
  5. 提交并推送真源仓库。
  6. 到服务器拉取并重建 frontend。
  7. 用浏览器做可见验收并留证。

十一、可直接复用的收尾检查清单

每次 Mortis 页面 copy / 扩展完成后，至少确认：

  • 真源仓库是否确认正确
  • 本轮 diff 是否只包含当前任务边界
  • 本地 typecheck 是否通过
  • 真源仓库是否已经 commit + push
  • 服务器是否已经完成 git pull --ff-only
  • frontend 是否已经 build + up -d
  • 浏览器可见页面是否已验证
  • 是否留下了必要的验收证据或说明

十二、本次相关关键路径

  • Mortis 真源仓库：C:\Users\ASUS-KL\.codex\.tmp\mortis-multica-source-working
  • 经验文档目录：E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\docs\agent
  • 线上站点：https://mortis.tengokukk.com
  • 部署主机：ubuntu@124.220.233.126
  • 部署目录：/srv/multica

十三、后续维护结论

后续凡是 Mortis 页面扩展、文案补全、控制面 copy 收口这类任务，默认都应遵守下面这条主线：

先确认真源 -> 只改展示边界 -> 本地最小校验 -> 真源提交推送 -> 服务器更新 frontend -> 浏览器可见验收。

这样做可以最大限度避免改错仓、混入无关改动、部署后未验证，以及“本地看起来改了但线上没落地”的常见问题。

十四、控制面 / 运维面板 UI 改造经验

这轮新增的经验，不是汉化问题，而是控制面扩展页的结构问题：虽然内容接进去了，但一开始的 UI 过度卡片化，和 Mortis 原生工作台风格明显不一致。

1. 在 Mortis 里，运维页默认应偏“工作台 / 清单 / 状态面板”，而不是“营销式卡片集合”

这次最直观的问题是：

  • SectionCard 里套 MetricCard
  • 大卡片里再套多层子卡片
  • 检查项逐条块状堆叠
  • 同一块信息被切成很多小容器

结果就是：

  • 视觉层级很重
  • 可扫描性反而下降
  • 页面一眼看过去像外挂模块，不像 Mortis 原生页面

以后只要是在 Mortis 里做运维页、清单页、控制面页，默认先避免“卡片套卡片套卡片”的写法。

2. 优先压平层级，而不是继续加装饰

本轮有效的做法不是继续“美化”，而是做减法：

  • MetricCard 改成更小、更扁的统计块
  • SectionCard 去掉厚重分层，改成轻量头部 + 内容区
  • WarningPanel 从整块说明卡改成扁平警告条
  • CheckList 从一条一块改成表格式行列表
  • 新增 FactTable 把散落字段压成密一点的事实表

核心原则：

  • 同一层信息尽量放进同一视觉层
  • 先保证“一屏能扫到多少有效信息”，再考虑装饰感
  • 能用表格 / 行列表表达的，不再拆成很多小卡片

3. Mortis 原生风格更接近“轻边框 + 紧凑排布 + 明确标签”

这次改完之后，比较贴 Mortis 自身风格的元素是：

  • 小尺寸圆角，而不是厚重大圆角
  • 轻边框和轻分隔线，而不是深层阴影
  • 标签、状态、事实字段都靠近内容本体
  • 标题区尽量短，主体区尽量承载信息

判断是否“像原生”的简单方法：

  1. 左侧导航和主内容放在一起看，是否像同一套产品。
  2. 是否能一眼扫到状态、路径、归属、检查结果，而不是先读很多容器。
  3. 页面主体是否更像“可操作工作台”，而不是“展示型专题页”。

4. 运维页的优先级应是信息密度，不是留白密度

对于 /mortis/overview、/mortis/servers、/mortis/deployments、/mortis/domains 这类页，后续默认优先保证：

  • 状态一眼可见
  • 路径和目标节点一眼可见
  • 检查结果能直接横向对比
  • 不需要频繁展开 / 跳转 / 读长段说明才知道系统现在怎样

可接受的留白是为了分组，不是为了把信息拆散。

5. 控制面页适合的结构顺序

后续再扩这几页时，优先按这个顺序组织：

  1. 页头：当前页名、接入状态、刷新动作
  2. 顶部摘要：少量关键数字或关键状态
  3. 风险条：当前未收口问题
  4. 主体清单：服务器 / 部署 / 域名 / 路由
  5. 每个主体块内固定用“事实区 + 检查区”

不要再把“摘要卡 -> 子卡 -> 子子卡 -> 检查卡”这种层层包裹结构加回来。

6. 这类 UI 改造必须用浏览器看成品，不能只看代码

这轮如果只看代码，很容易误以为“已经有样式、有组件、结构也完整”，但真正打开页面后，问题非常明显：

  • 纵向滚动压力大
  • 视觉层级不自然
  • 同类信息不够成组
  • 与 Mortis 原生页明显割裂

因此以后凡是 Mortis 内部页样式改造，最少都要浏览器实际看这几页：

  • /mortis/overview
  • /mortis/servers
  • /mortis/deployments
  • /mortis/domains

并至少留一份截图或快照证据。