---
belongs_to:
  - "[[⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🌙 铸渊指令｜天眼夜间自动修复引擎（下篇）—— PR·仪表盘·人类审阅·注册

---

<aside>
📋

**指令编号：** ZY-TIANYAN-AUTOFIX-2026-0324-001（下篇）

**关联上篇：** 🌙 天眼夜间自动修复引擎（上篇）— 架构·扫描·分析·修复核心

**优先级：** 🔴 P0 — 系统级架构升级

**签发人：** 冰朔（人类主权者）

**执行者：** 铸渊（GitHub CI/CD 工程人格）

**版权锚点：** 国作登字-2026-A-00037559 · TCS-0002∞ 冰朔

</aside>

---

## 一、Phase E — 自动创建 Pull Request

### 1.1 触发条件

Phase D 天眼审核 **全部通过**（H1-H9 = PASS）。

### 1.2 PR 创建规范

```
Step 1: 创建 Pull Request
  → GitHub API: POST /repos/{owner}/{repo}/pulls
  → 参数:
    title: "🌙 [AUTO-FIX] {YYYY-MM-DD} 天眼夜间自动修复 ({N}个修复)"
    head: "fix/auto-repair-{YYYYMMDD}-{序号}"
    base: "main"
    body: 见下方 PR Body 模板
    labels: ["auto-fix", "tianyan-v3"]

Step 2: 添加 PR 评论（修复摘要）
  → 对每个修复项生成一条评论
  → 包含：原始错误 + 根因分析 + 修复方案 + 风险等级

Step 3: 设置 PR 状态标签
  → 全部 low risk → 标签: ✅ safe-to-merge
  → 含 medium risk → 标签: ⚠️ review-carefully
  → 含 high risk → 不应出现（Phase B 已过滤）
```

### 1.3 PR Body 模板

```markdown
## 🌙 天眼夜间自动修复引擎 v3.0

**扫描时间：** {scan_time}
**修复数量：** {fix_count} 个
**风险等级：** {overall_risk}
**天眼审核：** ✅ H1-H9 全部通过

### 修复清单

| # | Workflow | 错误类型 | 根因 | 风险 | 文件 |
|---|----------|----------|------|------|------|
| 1 | sync-to-drive.yml | rclone_oauth_parse | shell拼接JSON不完整 | 🟢 low | sync-to-drive.yml |
| 2 | ... | ... | ... | ... | ... |

### 天眼审核结果

- [x] H1 Secrets安全
- [x] H2 文件完整性
- [x] H3 依赖安全
- [x] H4 权限最小化
- [x] H5 天眼自保护
- [x] H6 变更范围
- [x] H7 Secrets引用完整性
- [x] H8 注释规范
- [x] H9 无残留调试代码

---
> 🤖 此 PR 由铸渊夜间修复引擎自动创建
> 📋 指令编号: ZY-TIANYAN-AUTOFIX-2026-0324-001
> ⏰ 请冰朔在晨间审阅后合并
```

---

## 二、Phase F — 仪表盘更新机制

### 2.1 仪表盘位置

在主仓库 `README.md` 或独立文件 `DASHBOARD.md` 中维护。

### 2.2 仪表盘结构设计

```markdown
## 🌙 天眼夜间修复引擎 · 仪表盘

### 系统状态
| 指标 | 值 |
|------|----|
| 引擎版本 | v3.0 |
| 上次扫描 | 2026-03-24 23:00 CST |
| 扫描结果 | ⚠️ 发现 3 个错误 |
| 自动修复 | ✅ 2 个已修复 |
| 需人工处理 | 🔴 1 个等待指令 |
| 待合并 PR | 🟡 PR #42 |

### 最近7天修复历史
| 日期 | 扫描 | 发现 | 自动修复 | 人工处理 | PR |
|------|------|------|----------|----------|----|
| 03-24 | ✅ | 3 | 2 | 1 | #42 |
| 03-23 | ✅ | 0 | - | - | - |
| 03-22 | ✅ | 1 | 1 | 0 | #41 ✅ |
| ... | ... | ... | ... | ... | ... |

### 待处理事项
🔴 **需人工处理：**
- [ ] sync-persona-studio.yml: permission_denied (CROSS_REPO_TOKEN 未配置)

🟡 **待合并 PR：**
- [ ] PR #42: 天眼夜间修复 2026-03-24 (2个修复，低风险)
```

### 2.3 仪表盘更新逻辑

```
场景 A: 扫描无异常
  → 更新「上次扫描」时间
  → 更新「扫描结果」为 ✅ 今日无异常
  → 清空「待合并 PR」（如果前一天的已被合并）
  → 追加当日记录到7天历史

场景 B: 自动修复成功
  → 更新扫描结果 + 修复数量
  → 更新「待合并 PR」为新 PR 链接
  → 追加当日记录

场景 C: 自动修复失败
  → 更新「需人工处理」计数
  → 在「待处理事项」中添加具体错误描述
  → 追加当日记录（标记修复失败）

场景 D: 部分成功部分失败
  → 组合 B + C 的更新逻辑

场景 E: 人类合并了 PR
  → 下次扫描时检测已合并的 PR
  → 从「待合并 PR」中移除
  → 更新7天历史中对应日期的 PR 状态为 ✅
```

### 2.4 仪表盘更新 Workflow 片段

```yaml
# ========================================
# Phase E+F: 创建 PR + 更新仪表盘
# ========================================
create-pr-and-dashboard:
  needs: analyze-and-repair
  if: needs.analyze-and-repair.outputs.pr_needed == 'true'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        ref: main

    - name: "📦 Phase E — 创建 Pull Request"
      id: create_pr
      env:
        GH_TOKEN: $ secrets.DEPLOY_GITHUB_TOKEN 
        BRANCH: $ needs.analyze-and-repair.outputs.repair_branch 
        SUMMARY: $ needs.analyze-and-repair.outputs.repair_summary 
      run: |
        echo "[天眼 v3.0] Phase E — 创建 Pull Request"
        PR_TITLE="🌙 [AUTO-FIX] $(date +%Y-%m-%d) 天眼夜间自动修复"
        
        PR_URL=$(gh pr create \
          --base main \
          --head "$BRANCH" \
          --title "$PR_TITLE" \
          --body "$SUMMARY" \
          --label "auto-fix,tianyan-v3")
        
        echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT
        echo "✅ PR 已创建: $PR_URL"

    - name: "📊 Phase F — 更新仪表盘"
      env:
        GH_TOKEN: $ secrets.DEPLOY_GITHUB_TOKEN 
        PR_URL: $ steps.create_pr.outputs.pr_url 
      run: |
        echo "[天眼 v3.0] Phase F — 更新仪表盘"
        DATE=$(date +%Y-%m-%d)
        
        # 铸渊实现：
        # 1. 读取 DASHBOARD.md
        # 2. 更新系统状态表
        # 3. 追加当日历史记录
        # 4. 更新待合并 PR
        # 5. 提交到 main 分支
        
        git add DASHBOARD.md
        git commit -m "[DASHBOARD] 更新天眼仪表盘 $DATE"
        git push origin main

# ========================================
# 无错误时的仪表盘更新
# ========================================
dashboard-no-errors:
  needs: nightly-scan
  if: needs.nightly-scan.outputs.has_errors == 'false'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4

    - name: "✅ 更新仪表盘 — 今日无异常"
      env:
        GH_TOKEN: $ secrets.DEPLOY_GITHUB_TOKEN 
      run: |
        DATE=$(date +%Y-%m-%d)
        echo "[天眼 v3.0] 今日无异常，更新仪表盘"
        
        # 铸渊实现：
        # 1. 更新扫描时间和状态
        # 2. 检查前一天的 PR 是否已合并
        # 3. 追加当日记录（无异常）
        
        git add DASHBOARD.md
        git commit -m "[DASHBOARD] 今日无异常 $DATE" || true
        git push origin main || true
```

---

## 三、Phase G — 人类晨间审阅协议

### 3.1 冰朔操作流程

```
每天早上（冰朔自然醒来后）：

① 打开仪表盘 DASHBOARD.md
   → 查看「系统状态」区域
   → 如果「待合并 PR」为空 → 不需要操作，结束

② 如果有待合并 PR：
   → 点击 PR 链接进入 GitHub
   → 查看修复清单和天眼审核结果
   → 可选：查看每个 commit 的 diff

③ 决策：
   → 确认修复合理 → 点击 Merge → 完成
   → 发现问题 → 在 PR 中留言 → 铸渊下次夜间修复时读取反馈
   → 不确定 → 暂不合并 → 仪表盘持续显示待合并状态

④ 如果有「需人工处理」事项：
   → 阅读具体错误描述
   → 决定是否需要手动下指令给铸渊
   → 或者等待下次夜间扫描（如果是临时性问题可能已自愈）
```

### 3.2 PR 合并后自动清理

```
当 PR 被合并到 main 后：
  → 自动删除修复分支 fix/auto-repair-*
  → 下次夜间扫描时更新仪表盘历史记录
  → 如果修复的 Workflow 再次运行成功 → 在仪表盘标记 ✅ 已确认修复
```

---

## 四、回滚安全网

### 4.1 自动回滚触发条件

```
场景 1: PR 合并后，原本正常的 Workflow 开始报错
  → 下次夜间扫描检测到「修复引入新错误」
  → 自动创建 revert PR
  → 仪表盘标记 🔴 回滚告警

场景 2: 修复分支上的预审核未通过
  → Phase C 已处理：回退 commit

场景 3: 天眼审核未通过 + 2轮重试失败
  → Phase D 已处理：删除修复分支，记录仪表盘
```

### 4.2 回滚检测逻辑

```
在 Phase A 扫描中增加以下检测：

Step Extra: 检查「修复后回归」
  → 获取最近 48 小时内合并的 auto-fix PR 列表
  → 对每个 PR 涉及的 Workflow：
    → 检查合并后的运行记录
    → 如果合并前正常、合并后开始报错 → 标记为「修复引入回归」
    → 自动创建 revert commit 的 PR
    → PR 标题: "🔴 [REVERT] {原PR标题} — 修复引入回归"
    → 仪表盘标记回滚告警
```

---

## 五、错误去重与累积策略

### 5.1 去重规则

```
同一个 Workflow + 同一个 error_type 的错误视为同一个问题：
  → 首次出现：标记 first_seen 日期
  → 后续出现：增加 occurrence_count
  → 只在首次出现时尝试自动修复
  → 如果首次修复失败，后续出现不再重复尝试
  → 除非：人类手动在仪表盘标记「允许重试」
```

### 5.2 累积阈值告警

```
同一错误连续出现 3 天以上：
  → 仪表盘标记 🔴 持续性错误
  → 在待处理事项中升级优先级

同一错误连续出现 7 天以上：
  → 仪表盘标记 🚨 紧急告警
  → 如果配置了通知渠道 → 发送通知给冰朔
```

---

## 六、CRON 调度总览

与现有系统 CRON 的完整协调：

| **时间 (CST)** | **任务** | **Workflow** | **类型** |
| --- | --- | --- | --- |
| 04:00-04:10 | 每日微休眠 | 系统内置 | 休眠 |
| 周一 10:00 | Token主刷新A | renew-gdrive-tokens.yml | 生命线 |
| 12:15 每天 | Token安全网 | check-token-health.yml | 生命线 |
| 周四 10:00 | Token主刷新B | renew-gdrive-tokens.yml | 生命线 |
| 周六 20:00-00:00 | 周末大休眠 | 系统内置 | 休眠 |
| **23:00 每天** | **天眼夜间自动修复** | **tianyan-nightly-scan.yml** | **生命线** ⭐ NEW |

<aside>
⚠️

**周六例外：** 周六 20:00-00:00 为大休眠期。天眼夜间修复引擎 23:00 触发时如果处于休眠期内，作为「生命线任务」仍可正常执行。但铸渊应在实现中检查休眠状态：

- 休眠期内：只执行 Phase A 扫描 + Phase F 仪表盘更新
- 跳过 Phase B-E（修复/PR 延迟到次日）
- 原因：周末修复的 PR 冰朔可能不会及时看到
</aside>

---

## 七、Workflow 注册表条目

| **编号** | **Workflow** | **用途** | **触发** | **Secrets** |
| --- | --- | --- | --- | --- |
| AG-ZY-087 | tianyan-nightly-scan.yml | 天眼夜间自动修复引擎 v3.0 主流程 | CRON 每天 23:00 CST + 手动 | DEPLOY_GITHUB_TOKEN, GEMINI_API_KEY |

---

## 八、文件清单

铸渊需要创建/修改的文件：

| **#** | **文件** | **操作** | **说明** |
| --- | --- | --- | --- |
| 1 | `.github/workflows/tianyan-nightly-scan.yml` | 🆕 新建 | 主 Workflow 文件（Phase A-F） |
| 2 | `.github/scripts/tianyan-analyze.js` | 🆕 新建 | Phase B 报错分析脚本（调用 Gemini） |
| 3 | `.github/scripts/tianyan-repair.js` | 🆕 新建 | Phase C 自动修复脚本（调用 Gemini） |
| 4 | `.github/scripts/tianyan-review.js` | 🆕 新建 | Phase D 天眼审核脚本（H1-H9） |
| 5 | `DASHBOARD.md` | 🆕 新建 | 天眼修复引擎仪表盘 |
| 6 | `.github/tianyan-config.json` | 🆕 新建 | 天眼配置文件（错误分类规则、安全护栏参数） |

---

## 九、天眼配置文件

**文件：** `.github/tianyan-config.json`

```json
{
  "version": "3.0",
  "engine": "tianyan-nightly-autofix",
  "schedule": {
    "scan_time_utc": "15:00",
    "scan_time_cst": "23:00",
    "timezone": "Asia/Shanghai"
  },
  "safety": {
    "max_files_per_repair": 5,
    "max_lines_per_file": 50,
    "max_retry_rounds": 2,
    "max_total_changed_lines": 200,
    "protected_patterns": [
      "tianyan-*.yml",
      "CODEOWNERS",
      ".github/FUNDING.yml"
    ],
    "forbidden_operations": [
      "create_file",
      "delete_file",
      "modify_secrets_ref",
      "modify_protected_file",
      "push_to_main"
    ]
  },
  "error_classification": {
    "auto_fixable": [
      "config_parse",
      "rclone_oauth_parse",
      "script_error"
    ],
    "partial_fixable": [
      "token_expired"
    ],
    "manual_only": [
      "network_timeout",
      "permission_denied",
      "unknown"
    ]
  },
  "gemini": {
    "model": "gemini-2.0-flash",
    "temperature": 0.1,
    "max_output_tokens": 4096,
    "response_format": "json"
  },
  "dashboard": {
    "file": "DASHBOARD.md",
    "history_days": 7,
    "alert_thresholds": {
      "persistent_error_days": 3,
      "urgent_alert_days": 7
    }
  },
  "weekend_mode": {
    "enabled": true,
    "saturday_hibernation": "20:00-00:00",
    "saturday_scan_only": true,
    "skip_repair_on_saturday": true
  }
}
```

---

## 十、执行回执模板

<aside>
📝

**铸渊完成后需回执确认以下阶段：**

A. `tianyan-nightly-scan.yml` 主 Workflow 文件已创建 → ✅/❌

B. `tianyan-analyze.js` 分析脚本已创建 → ✅/❌

C. `tianyan-repair.js` 修复脚本已创建 → ✅/❌

D. `tianyan-review.js` 审核脚本已创建 → ✅/❌

E. `DASHBOARD.md` 仪表盘文件已创建 → ✅/❌

F. `tianyan-config.json` 配置文件已创建 → ✅/❌

G. `DEPLOY_GITHUB_TOKEN` 权限已确认 `pull-requests: write` → ✅/❌

H. AG-ZY-087 已注册到 Workflow 注册表 → ✅/❌

I. 手动触发测试 `workflow_dispatch` 通过 → ✅/❌

J. 天眼审核 H1-H9 全部通过 → ✅/❌

K. 仪表盘首次更新成功 → ✅/❌

</aside>

---

## 十一、验收标准

<aside>
✅

**本指令视为完成的条件：**

1. 天眼夜间自动修复引擎 v3.0 所有文件已部署到主仓库
2. CRON 定时触发在 23:00 CST 正常运行
3. 手动触发（workflow_dispatch）测试通过
4. Phase A 扫描能正确获取过去24小时失败的 Workflow
5. Phase B Gemini 分析能正确输出结构化 JSON
6. Phase C 自动修复能在独立分支上生成修复代码
7. Phase D 天眼审核 H1-H9 检查清单全部通过
8. Phase E 自动创建 PR 格式正确、标签正确
9. Phase F 仪表盘自动更新成功
10. 回滚安全网：修复引入回归时能自动检测并创建 revert PR
11. 七条铁律全部生效（无法绕过安全护栏）
12. AG-ZY-087 已注册
</aside>

---

<aside>
🔥

**系统升级总结**

**天眼 v2.0 → v3.0**

- 从「被动审计」进化为「主动修复闭环」
- 7 个 Phase（A→G）完整覆盖「扫描 → 分析 → 修复 → 审核 → PR → 仪表盘 → 人类审阅」
- 安全护栏：七条铁律 + 天眼 H1-H9 审核 + 2轮重试上限 + 回滚安全网
- 人类主权保障：所有修复通过 PR 提交，冰朔保留最终合并权
- 预计每天为冰朔节省 30-60 分钟的手动排错时间

**这是零点原核系统迈向自主运维的关键一步。**

</aside>