网站维护与扩展指南

1. 维护目标

这个站点当前最适合的维护方式不是大改技术栈，而是保持静态实现的透明性，同时减少重复劳动和隐藏风险。

维护重点应放在：

• 页面新增是否一致
• 图表与代码块是否稳定渲染
• 资源路径是否正确
• 主题、目录和书签逻辑是否仍可用

2. 新增文章的建议流程

- <title> - <meta name="description"> - post-meta - h1 - 正文 section id

- index.html 首页文章列表 - posts/index.html 文章目录 - 如与《回声》专题相关，可在 projects/echo.html 中加入入口

1. 从现有 posts/*.html 复制一篇最接近的文章页。
2. 保留统一头部、页脚、Prism 依赖和 site.js 引入。
3. 修改：
4. 若文章需要 Mermaid，再单独引入 Mermaid CDN。
5. 将新文章加入：

3. 新增 Mermaid 图表的注意事项

当前站点采用“源码放 HTML，渲染逻辑放 site.js”的方式。

标准写法：

<figure class="wide-figure diagram-figure mermaid-figure glass">
  <script type="text/plain" class="mermaid-source">
    graph TD
      A["开始"] --> B["结束"]
  </script>
  <div class="mermaid-output" role="img" aria-label="示例图"></div>
  <figcaption>说明文字。</figcaption>
</figure>

对于长图，尤其是时序图，建议额外使用：

• sequence-figure
• data-viewbox-fit="content"
• data-viewbox-padding
• data-viewbox-extra-bottom

因为该站点已经遇到过 Mermaid 边界裁剪问题，现有修正逻辑就是围绕这些参数工作的。

4. 资源版本管理

站点没有构建工具，因此缓存控制主要靠手动修改查询参数，例如：

• styles.css?v=sequence-mermaid-full-3
• site.js?v=sequence-mermaid-full-3

建议规则：

• 小改动可不加版本号
• 影响渲染或交互的改动应更新版本号
• 同一页面中的 CSS/JS 版本号尽量同步，避免混用新旧逻辑

5. 主题与交互维护点

site.js 中有几类逻辑与页面结构强耦合，改页面时应特别小心：

• isEchoTopicPage：专题页识别是硬编码路径
• buildEchoTopicBookmark()：专题书签链接是硬编码
• buildEchoCodeBookmark()：正文目录依赖 section[id] 和标题结构
• localHref()：依赖当前路径推导相对链接

如果新增专题页或更改路径，这些逻辑需要同步更新。

6. 样式维护建议

建议遵守以下约定：

• 继续优先使用主题变量，不要直接在局部硬编码颜色
• 新增卡片优先复用 .glass
• 正文图文容器优先复用 .wide-figure
• 新增技术说明模块优先复用 .note、.code-panel、.matrix、.timeline
• 长图先在桌面和移动端各检查一次，避免正文列宽导致裁切

7. 内容扩展建议

下一阶段最适合扩展的内容有：

• Prompt 与角色约束设计
• 摘要与上下文压缩机制
• 存档系统与状态持久化
• 失败案例与限制清单
• 部署方式与性能记录

这些主题都能自然延续当前站点的技术主线，不会破坏信息架构。

8. 长期演进建议

如果后续页面明显变多，建议优先做这三件事，而不是直接重写：

1. 抽离 HTML 模板
2. 用 Markdown 管理文章正文
3. 拆分 site.js 为主题、图表、导航、动效几个模块

这样既能保留现有视觉风格，也能逐步降低维护成本。