网站内容与界面维护手册

面向非工程师的网站维护说明，讲清分类、文档、博客、资讯、歌曲、歌词、海报、排版、字体、按钮组件以及安全发布流程。

操作手册项目原生文档V1.0

这份手册用于以后自己维护 StarmoAI 网站。它不要求你会编程，但会明确告诉你：要改什么、去哪里改、哪些字段能改、哪些地方不要直接碰，以及修改后怎样安全上线。

当前网站还没有后台管理系统，因此内容更新需要修改项目源文件。博客和知识文档比较容易维护；资讯有严格的数据校验；音乐板块目前耦合较高，发布歌曲时必须特别谨慎。

项目根目录：D:\Download\歌曲\starmoai-live-upgrade-offline-repair-20260903

网站内容位置总览

先记住三个原则

只修改源文件，不修改 dist。 dist 是构建后自动生成的上线产物，下次构建会覆盖它。
改之前备份，改之后预览。 至少保留原文件副本；界面修改还要保存修改前截图。
使用 pnpm，不要混用 npm。 本项目已经按 pnpm 管理依赖，混用可能改坏锁文件或依赖目录。

什么可以自己改

绿色区安全自己修改

博客 Markdown 的标题、日期、分类和正文
文档 Markdown 的标题、分类和正文
已存在图片的替换，前提是尺寸和文件名保持不变
LRC 歌词正文，前提是时间戳格式正确且文件名不变
资讯文字，前提是来源、日期和必填字段完整并通过校验

黄色区建议让 Codex 协助

新增歌曲并登记进播放列表
调整海报轮播顺序
新增文档大类或改变左侧树形层级
修改页面排版、响应式布局、字体、按钮和组件
修改资讯的数据结构或分类类型

红色区不要直接修改

dist 文件夹
pnpm-lock.yaml
node_modules
.ssh、密钥、密码、令牌和服务器权限文件
线上 Web Root、release 或 current 指针
public/music/music.html 中不理解的播放逻辑

网站文件地图

想修改的内容	源文件位置	修改难度	是否需要构建
博客文章	`src/content/blog/*.md`	低	是
知识文档	`src/content/docs/*.md`	低	是
文档分类	文档头部的 `group`，整体排序在 `src/data/docsNavigation.ts`	中	是
资讯动态	`src/data/news.json`	中	是
资讯图片	`public/images/news/sources/`	中	是
歌曲音频	`public/music/music/*.mp3`	低	是
歌词文件	`public/music/music/*.lrc`	中	是
歌曲海报	`public/music/posters/*.png`	低	是
歌曲清单和轮播	`public/music/music.html`	高	是
顶部导航	`src/components/SiteNav.astro`	高	是
页脚	`src/components/SiteFooter.astro`	高	是
全站基础布局	`src/layouts/BaseLayout.astro`	高	是
文档页布局	`src/components/DocsShell.astro`	高	是
音乐页样式和组件	`public/music/music.html` 顶部 `<style>` 和页面结构	很高	是

修改知识文档

文档放在哪里

每篇网站文档都是一个 Markdown 文件，位于：

src/content/docs/

例如本手册的源文件是：

src/content/docs/site-content-interface-maintenance-manual.md

新建文档的安全方法

复制一篇结构相近的 .md 文件，重命名为简短的英文文件名，再修改头部信息和正文。文件名会成为网址的一部分，不建议使用空格和过长中文。

---
title: "我的新文档"
description: "一句话说明这篇文档讲什么。"
group: "开始使用"
subgroup: "站点维护"
contentType: "操作手册"
sourceType: "项目原生文档"
version: "V1.0"
order: 10
updatedAt: "2026-09-08"
draft: true
---

title：网页标题和左侧目录名称。
description：标题下面的简介，也用于搜索描述。
group：文档所属分类。当前常用值包括 开始使用、设计与内容、工程与架构、音乐播放器 等。
subgroup：辅助分组信息，目前不会单独形成稳定的第三级导航，不要依赖它改变整个目录结构。
order：同一分类中的顺序，数字越小越靠前。
updatedAt：最后修改日期，格式必须为 年-月-日。
draft：true 表示草稿，不公开；确认后改为 false。

修改文档分类

只把一篇文档从一个已有分类移到另一个已有分类时，修改该文档头部的 group 即可。

group: "设计与内容"

如果是新增一个全新的分类名称，还应在 src/data/docsNavigation.ts 的 GROUP_ORDER 中加入名称，否则新分类虽然能出现，但排序可能跑到最后。

不要为了“看起来多一层”随意增加空分类。分类应代表长期存在的一组内容，只有一篇文章时通常不值得再拆一级。

编写正文

## 二级标题

正文段落。

### 三级标题

- 列表项目一
- 列表项目二

> 这是引用或重要说明。

![图片说明](/images/example.png)

标题应按 ##、### 顺序使用，不要从二级直接跳到四级。右侧“本页目录”会从正文标题自动生成。

发布或修改博客文章

博客文章位于：

src/content/blog/

建议复制 welcome-to-starmoai.md 作为模板，然后改名。一个可用的文章头部如下：

---
title: "文章标题"
description: "文章摘要，建议一到两句话。"
category: "思考"
publishedAt: "2026-09-08"
updatedAt: "2026-09-08"
readingTime: "6 分钟"
draft: true
---

博客分类只能使用：AI、建站、创作、思考、生活。写作期间保持 draft: true；预览确认后再改为 false。

正文与文档一样使用 Markdown。配图先放入 public/images/ 下的合适目录，再用网站路径引用：

![图片的准确说明](/images/blog/my-article-cover.png)

图片文件名建议使用小写英文、数字和短横线，不要使用“最终版2真的最终版”这样的名称。

发布资讯动态

博客与资讯采用不同发布路线

资讯不是普通博客。它位于 src/data/news.json，并且受到 scripts/validate-news.mjs 的发布规则约束。

发布前先判断是否值得发

必须有可访问的主来源，优先官方公告、公司新闻稿、监管机构或原始研究。
必须确认事件发生或发布的准确时间。
必须能说明它为什么影响 AI、智能汽车或科技行业。
同一事件不能重复发布。
未核验内容不能为了填满版面而上线。

新增一条资讯

在 items 数组顶部加入一个完整对象，并注意上一条对象结尾必须有逗号：

{
  "id": "short-unique-id-2026",
  "eventKey": "2026-09-08-company-event",
  "title": "清楚、克制、没有标题党的标题",
  "summary": "说明发生了什么，并写出可核验事实。",
  "publishedAt": "2026-09-08T09:30:00+08:00",
  "discoveredAt": "2026-09-08T10:00:00+08:00",
  "updatedAt": "2026-09-08T10:00:00+08:00",
  "category": "AI",
  "tags": ["模型", "产品"],
  "entities": ["公司名称"],
  "primarySource": "官方来源名称",
  "primarySourceUrl": "https://example.com/official-news",
  "primarySourceTier": 1,
  "secondarySources": [],
  "verificationStatus": "verified",
  "significance": "standard",
  "trendEvidence": {
    "status": "unavailable",
    "note": "未接入可复核的外部趋势数据。"
  },
  "editorReason": "说明为什么选择这条资讯。",
  "whyItMatters": "说明它为什么值得读者关注。",
  "image": null,
  "imageSource": null
}

允许的 category 只有 AI、智能汽车、科技。significance 只有 major、high、standard。不要编造热度分。

给资讯增加图片

只有确认版权和来源时才使用来源图片。文件放在：

public/images/news/sources/

然后将资讯中的两个空值改成：

"image": {
  "url": "/images/news/sources/example.webp",
  "alt": "画面中真实可见的内容",
  "credit": "图片来源名称"
},
"imageSource": "https://example.com/original-page"

不要只写“新闻图片”作为 alt，也不要使用无法追溯来源的网络图。

资讯必须单独校验

pnpm check:news

出现红色错误时不要发布，要按错误提示修正字段、日期、重复链接或图片路径。

发布歌曲

歌曲发布所需文件和登记关系

当前结构为什么风险较高

音乐页目前是一个大型独立 HTML 文件。它同时包含：

页面结构
全部 CSS 样式
歌曲 playlist
海报轮播 carouselSongs
内嵌歌词 EMBEDDED_LRC
播放、搜索、歌词同步、频谱和详情页逻辑

因此它属于高耦合技术债。你可以替换同名音频、海报或 LRC；但新增歌曲、删除歌曲、调整轮播或改播放器组件时，建议交给 Codex，并要求先备份和完成整页回归测试。

准备音频

把 MP3 放入：

public/music/music/

建议文件名清楚、唯一。例如：

星光归途.mp3
星光归途.lrc

MP3 与 LRC 的基础文件名必须完全一致，包括空格、括号、大小写和全角半角符号。

编写或修改 LRC 歌词

[ti:星光归途]
[ar:李星然 / Suno]
[by:StarmoAI]

[00:12.34]第一句歌词
[00:18.90]第二句歌词
[00:25.10]第三句歌词

每句必须以 [分钟:秒.百分秒] 开头。
时间必须从小到大排列。
不要使用 Word 保存 LRC；使用 UTF-8 纯文本。
只改歌词文字、不改时间时，可直接编辑对应 .lrc。
如果新增或删除歌词行，必须重新检查整首同步效果。

当前 music.html 还保留一份 EMBEDDED_LRC 作为兼容副本。只改外部 .lrc 不一定覆盖所有访问场景，因此正式发布歌词修改时，应同步更新内嵌副本，或先完成音乐数据解耦。

准备海报

海报位于：

public/music/posters/

当前命名规则：

STAI-MKT-POSTER-0026_v001_REVIEW.png

0026 是海报编号。
v001 是版本号。
当前页面实际读取 _REVIEW.png 文件。
推荐继续使用 PNG，并保持现有海报的宽高比例。
替换已有海报时，保持原文件名最安全。

在播放列表登记歌曲

public/music/music.html 中的 playlist 每一行代表一首歌：

{t:"星光归途", f:"星光归途.mp3", p:26, d:"星光旅程 · 中文抒情"},

t：页面显示标题。
f：MP3 文件名，必须与真实文件完全一致。
p：海报编号，对应 0026。
d：副标题 · 曲风，中间使用圆点分隔。

不要删除上一行末尾的逗号，不要把中文引号复制进代码，也不要让两个对象共用同一个错误文件名。

加入首页海报轮播

carouselSongs 保存的是播放列表索引，不是海报编号，而且从 0 开始计数。例如第一首是 0，第五首是 4。

const carouselSongs=[0,4,7,12];

这很容易数错。新增歌曲后建议由 Codex根据标题自动计算索引，不建议手工数几十首歌。

发布歌曲后的检查清单

列表能看到新歌，歌名和版本没有重复或截断。
点击歌曲后音频可以播放。
海报列表、播放器小图和详情页海报都能显示。
歌词能打开、能滚动、时间同步正确。
上一首、下一首、随机、循环、音量和进度条正常。
搜索能找到新歌。
手机端没有溢出。
未播放状态仍显示空 CD，不出现破图或 Logo。

更换音乐海报

最安全的方式

如果只想替换某首歌的海报，不改变编号：

找到该歌 playlist 中的 p 值。
在 public/music/posters/ 找到对应 _REVIEW.png。
备份原图。
用相同文件名覆盖新图。
本地打开音乐页，检查轮播、歌曲卡片、播放器和详情页四处。

浏览器可能缓存旧图。确认文件确实更新后，可强制刷新页面；不要因为缓存没变化就连续修改代码。

修改排版和字体

普通网站页面

全站基础结构：src/layouts/BaseLayout.astro
顶部导航：src/components/SiteNav.astro
页脚：src/components/SiteFooter.astro
文档三栏布局：src/components/DocsShell.astro
博客列表布局：src/pages/blog/index.astro
资讯布局：src/pages/news.astro

Astro 文件通常把 HTML 结构写在上半部分，把页面 CSS 写在 <style> 中。修改前先搜索现有类名，不要新建一套重复样式。

音乐页面

音乐页 CSS 位于 public/music/music.html 开头的 <style> 内，页面结构和交互代码也在同一个文件。这里是当前最不适合直接手工修改的区域。

字体修改原则

字体不是只改一个名字。更换字体前要确认：

中文、英文和数字是否都有字形。
Windows、Android、HarmonyOS、iPhone 是否都有可靠回退字体。
标题加粗后是否挤压、换行或重叠。
字体文件是否有网页使用许可。
首屏是否因为加载字体而闪烁或变慢。

音乐页当前字体栈是：

font-family: 'Inter', 'Noto Sans SC', 'PingFang SC', sans-serif;

不要只留下一个本机字体，否则你的电脑看起来正常，其他人的设备可能完全不同。

修改按钮和组件

按钮通常由三部分共同决定：HTML 结构、CSS 外观、JavaScript 行为。只改其中一部分可能出现“看得到但点不动”或“能点但状态不更新”。

修改按钮时至少检查：

默认、悬停、按下、禁用和键盘聚焦状态。
按钮是否仍有可读的 aria-label。
图标与文字是否垂直居中。
手机端触控区域是否足够大。
深色和浅色背景下对比度是否清楚。
点击后 URL、播放器状态或弹层是否按预期变化。

顶部导航、页脚、文档壳等属于共享组件。修改共享组件会影响很多页面，不能只检查当前页面。

本地预览

在 PowerShell 中进入项目：

Set-Location 'D:\Download\歌曲\starmoai-live-upgrade-offline-repair-20260903'

首次接手或发生过依赖事故时，不要立即安装。先查看项目状态和备份，再决定是否需要处理依赖。

依赖正常时启动开发预览：

pnpm dev

按照终端显示的本地地址打开网站。完成后按 Ctrl+C 停止。

构建和发布

安全修改与上线流程

构建前检查

文件已经备份。
JSON、YAML、Markdown 和 JavaScript 引号、冒号、逗号完整。
新图片、音乐和歌词路径都真实存在。
没有修改密钥、锁文件或 dist。
资讯已运行 pnpm check:news。

构建

pnpm build

构建必须以成功结束，并且 dist/_astro/ 中存在 CSS 文件。构建成功只代表代码能生成网页，不代表视觉一定正确。

浏览器检查

至少检查：

桌面宽屏。
手机窄屏。
顶部导航和返回方式。
新增内容入口。
图片是否加载。
按钮能否操作。
浏览器控制台是否报错。

上线边界

线上发布使用受控发布器。不要直接修改服务器 Web Root，不要读取或复制私钥内容，也不要手工切换线上 release。

如果你把任务交给 Codex，可以直接说：

请先备份并检查当前状态，只修改源文件。本地构建和桌面、手机浏览器检查通过后，使用 StarmoAI 受控发布器上线，最后验证线上 URL。不要直接修改 Web Root，不要输出密钥内容。

事故处理

发现样式突然消失、页面大面积变形、锁文件被删、npm 和 pnpm 混用或线上内容疑似被覆盖时，立即停止继续开发。

正确顺序：

不要 install，不要 build，不要继续覆盖文件。
保存当前目录副本。
查看最近修改时间、文件差异和可用备份。
检查线上页面是否真的变化，区分缓存与真实覆盖。
确认可回滚版本。
在离线副本修复。
验证后再通过受控发布器上线。

当前技术债和建议改造顺序

第一优先级音乐数据解耦

目标结构建议调整为：

public/music/
  index.html
  styles.css
  player.js
  tracks.json
  music/
  posters/

并完成以下改变：

tracks.json 只保存歌曲标题、音频、歌词、海报和展示信息。
player.js 读取 tracks.json，不再手写几十行歌曲对象。
歌词只读取外部 .lrc，删除重复的 EMBEDDED_LRC。
styles.css 独立维护排版和主题。
轮播使用歌曲 ID，不再使用容易数错的数组索引。

改造完成后，发布歌曲可以简化为：放入 MP3、LRC、海报，再在 JSON 增加一条记录。

第二优先级内容发布工具

可以增加一个只在本地运行的发布助手，用表单生成博客 Markdown、资讯 JSON 和歌曲记录。这样你不需要手工处理括号、逗号和日期格式。

第三优先级自动检查

增加歌曲文件对应检查、海报编号检查、LRC 时间戳检查、链接检查和图片尺寸检查，让错误在上线前自动被发现。

每次维护完成后的最终清单

当你不确定某个修改属于内容还是程序逻辑时，先不要改。把目标、当前截图和准备替换的文件交给 Codex，让它先指出影响范围和风险，再开始操作。