Add structured rebuild entrypoint for AstrBot

2026-05-06 10:11:16 +08:00
parent 85e510fbc0
commit 89bc23e7e7
6 changed files with 376 additions and 32 deletions
@@ -0,0 +1,109 @@
+# 重建触发与错误码约定
+
+本文档定义仓库对外提供的统一重建入口，供 AstrBot、cron 或手工执行复用。
+
+## 统一入口
+
+```bash
+npm run rebuild
+```
+
+该命令会顺序执行：
+
+1. `npm run content:sync`
+2. `npm run build`
+
+当前还不包含部署步骤；后续如接入部署，可继续扩展到同一入口里。
+
+## 适合 AstrBot 的调用方式
+
+AstrBot 只需要做三件事：
+
+1. 定时触发 `npm run rebuild`
+2. 读取进程退出码
+3. 从输出中提取 `REBUILD_RESULT ...` 这一行，作为结构化结果
+
+推荐通知内容：
+
+- 成功：开始时间、结束时间、总耗时
+- 失败：失败阶段、错误码、错误符号、最后几行日志
+
+## 结构化输出
+
+命令结束前会输出一行 JSON：
+
+```text
+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` | 未归类异常 |
+
+## 手动补跑
+
+本地或服务器上都可以直接执行：
+
+```bash
+npm run rebuild
+```
+
+如果只是想单独排查同步阶段，也可以先运行：
+
+```bash
+npm run content:sync
+```
+
+## 建议的 AstrBot 判定逻辑
+
+- 退出码 `0`：发送成功通知
+- 非 `0`：发送失败告警
+- 优先展示：
+  - `symbol`
+  - `stage`
+  - `code`
+  - `logTail`