personal-homepage/docs/rebuild-trigger-spec.md

重建触发与错误码约定

本文档定义仓库对外提供的统一重建入口，供 AstrBot、cron 或手工执行复用。

统一入口

npm run rebuild

该命令会顺序执行：

1. npm run content:sync
2. npm run build

当前还不包含部署步骤；后续如接入部署，可继续扩展到同一入口里。

适合 AstrBot 的调用方式

AstrBot 只需要做三件事：

1. 定时触发 npm run rebuild
2. 读取进程退出码
3. 从输出中提取 REBUILD_RESULT ... 这一行，作为结构化结果

推荐通知内容：

• 成功：开始时间、结束时间、总耗时
• 失败：失败阶段、错误码、错误符号、最后几行日志

结构化输出

命令结束前会输出一行 JSON：

REBUILD_RESULT {"ok":true,"stage":"build","code":0,"symbol":"SUCCESS",...}

字段说明：

• ok: 是否成功
• stage: 失败或结束所在阶段，当前可能为 sync / build / bootstrap
• code: 退出码
• symbol: 退出码对应的文本符号
• startedAt: 整体开始时间
• finishedAt: 整体结束时间
• durationMs: 整体耗时
• failedStepDurationMs: 当前失败步骤耗时；成功时为最后一步耗时
• logTail: 最后若干行日志，便于 AstrBot 通知时直接带上排障信息

错误码

成功

Code	Symbol	含义
0	SUCCESS	全部成功

同步阶段

Code	Symbol	含义
10	SYNC_FAILED	通用同步失败
11	GITEA_SYNC_FAILED	Gitea 同步失败
12	SEAFILE_SYNC_FAILED	Seafile 同步失败
13	SCHEMA_VALIDATION_FAILED	JSON/Schema 校验失败

构建阶段

Code	Symbol	含义
20	BUILD_FAILED	Astro 构建失败

部署阶段（预留）

Code	Symbol	含义
30	DEPLOY_FAILED	静态产物部署失败

运行阶段

Code	Symbol	含义
40	CONFIG_INVALID	运行环境缺少必要命令或配置异常
50	UNKNOWN_ERROR	未归类异常

手动补跑

本地或服务器上都可以直接执行：

npm run rebuild

如果只是想单独排查同步阶段，也可以先运行：

npm run content:sync

建议的 AstrBot 判定逻辑

• 退出码 0：发送成功通知
• 非 0：发送失败告警
• 优先展示：
  • symbol
  • stage
  • code
  • logTail