开发者指南

这份文档写给参与 ECHO Page 开发、维护或提交 PR 的开发者。ECHO Page 是 ECHO Next 的官方网站、文档、更新日志与静态更新源承载项目；开发时请优先保证页面稳定、发布信息准确、用户下载入口可靠。

项目边界

ECHO Page 主要维护这些内容：

• 官网首页、下载页、更新日志页与文档站页面。
• src/content/releases 下的版本记录。
• public/update 下供桌面端读取的静态更新源。
• 文档内容、产品截图、品牌图和必要的部署脚本。

不要把 ECHO Next 桌面端的实现细节、临时测试记录、实验性路线草稿或未确认的发布承诺写进正式页面。对外页面应当只呈现已经确认、可以维护、不会误导用户的信息。

提交与 PR 规则

优先提交小而清晰的 PR。一个 PR 应该能用一句话说明目标，并且尽量只触碰同一类文件，例如只改文档、只改发布记录、只改下载页逻辑。

任何大型 PR 请先联系我，否则会被直接拒绝。

以下情况通常属于大型 PR：

• 同时改动站点结构、样式系统、发布脚本和内容数据。
• 重写首页、下载页、文档导航或更新源生成逻辑。
• 引入新的框架、构建插件、第三方服务或部署流程。
• 大规模迁移文档、批量删除内容或重排公开导航。
• 会影响用户下载、自动更新、SEO、站点语言路由或构建输出的改动。

如果不确定是否属于大型 PR，先按大型 PR 处理，说明目标、范围、风险和计划后再动手。

开发要求

开发前先查看当前工作区状态，避免覆盖他人正在进行的修改。多人或多进程开发时，只处理自己负责的文件；发现无关变更时不要回滚，也不要顺手重构。

内容改动应保持可读、可维护、可核查：

• 中文和英文页面尽量同步，除非明确只维护单语言页面。
• 发布说明必须和实际版本、下载产物、更新源一致。
• 外链、下载链接、GitHub Release 链接和镜像说明必须准确。
• 图片资源要有明确用途，避免无意义堆图或超大资源。
• 文档标题、侧边栏标签、路径命名应保持简短稳定。

代码和样式改动应优先沿用现有 Astro、Starlight、组件和 CSS 结构。除非有明确收益，不要增加新的抽象、全局样式层或复杂运行时逻辑。

高风险改动

以下改动需要特别谨慎，并在 PR 中写清楚风险：

• 修改 astro.config.mjs、部署脚本、站点域名、语言路由或 sitemap。
• 修改 scripts/generate-update-feed.mjs、public/update 或自动更新相关文件。
• 修改下载页产物选择、版本排序、GitHub Release 同步逻辑。
• 大幅调整文档信息架构、导航层级或公开入口。
• 删除文档、图片、下载资产或历史版本记录。

如果改动可能导致用户无法下载、无法自动更新、看到错误版本信息，必须先和维护者确认。

验证原则

验证要高效率，不要为了形式跑很久的低价值测试。根据改动范围选择最小但有效的证明：

• 只改 Markdown 文档时，检查页面路径、标题、链接和 frontmatter 即可。
• 改发布记录时，运行内容校验并确认版本、日期、产物字段正确。
• 改更新源或下载逻辑时，必须验证生成结果和关键下载入口。
• 改 Astro 组件、路由或样式时，至少做一次本地构建或针对页面的浏览器检查。

如果没有运行完整构建或完整测试，应在 PR 中说明原因和已经完成的针对性验证。

PR 描述建议

PR 描述至少包含：

• 本次改动解决什么问题。
• 主要改了哪些文件或页面。
• 做过哪些验证。
• 是否有风险、回滚方式或需要维护者确认的点。

对公开内容负责，比把 PR 做大更重要。保持范围清楚、行为可验证、风险可解释，就是最好的贡献方式。