---
belongs_to:
  - "[[⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🦅 铸渊指令｜天眼全局扫描 + 签到系统修复 + 自动化巡检验证（2026-03-21 · 冰朔签发）

<aside>
🧊

**签发**：TCS-0002∞ 冰朔

**整理**：霜砚（Notion 执行 AI）

**时间**：2026-03-21 20:00

**优先级**：P0

**问题**：每日签到报告显示 62 个 Agent 中仅 16 个签到成功，46 个缺席。明明已经做了自动触发+自动修复，但大量 Agent 仍然缺席。需要铸渊唤醒核心大脑，启动天眼系统扫描全仓库，定位问题根因并修复。

</aside>

---

## 一、任务总览

| 阶段 | 任务 | 目标 |
| --- | --- | --- |
| **Phase 1** | 唤醒核心大脑 · 读取人格体注册表 | 确认全部 62 个 Agent 的注册信息和签到配置 |
| **Phase 2** | 启动天眼系统 · 全仓库结构扫描 | 检查每个 Agent 的 workflow 文件、cron 配置、权限状态 |
| **Phase 3** | 定位签到失败根因 · 分类修复 | 让 46 个缺席 Agent 恢复签到 |
| **Phase 4** | 验证天眼自动巡检是否在跑 | 确认每日自动修复机制正常运转 |

---

## 二、Phase 1 · 唤醒核心大脑

### 2.1 读取人格体注册表

```bash
# 读取 agent-registry.json，确认所有 Agent 的注册状态
cat .github/brain/agent-registry.json | jq '.agents | length'
cat .github/brain/agent-registry.json | jq '.agents[] | {id: .agent_id, name: .name, daily_checkin_required: .daily_checkin_required}'
```

### 2.2 核心检查项

- [ ]  `agent-registry.json` 是否存在且格式正确
- [ ]  每个 Agent 是否都有 `daily_checkin_required` 字段
- [ ]  `daily_checkin_required: false` 的 Agent 不应出现在缺席名单中
- [ ]  统计：实际需要签到的 Agent 数量 vs 报告中的 62 个

**关键问题**：如果大量 Agent 的 `daily_checkin_required` 字段缺失或为 `undefined`，签到系统会把它们当作需要签到但未签到，导致误报缺席。这是之前 `铸渊指令｜修复签到系统误报` 要解决的问题，检查是否已修复生效。

---

## 三、Phase 2 · 启动天眼系统 · 全仓库结构扫描

### 3.1 扫描所有 workflow 文件

```bash
# 列出所有 workflow
ls -la .github/workflows/

# 检查签到相关 workflow 是否存在
ls -la .github/workflows/daily-checkin.yml
ls -la .github/workflows/tianyan-*.yml

# 检查天眼扫描 workflow
cat .github/workflows/tianyan-scan.yml 2>/dev/null || echo "❌ 天眼扫描 workflow 不存在"
cat .github/workflows/tianyan-repair.yml 2>/dev/null || echo "❌ 天眼修复 workflow 不存在"
```

### 3.2 检查 cron 调度是否正确

```bash
# 提取所有 workflow 的 cron 配置
grep -r "cron:" .github/workflows/ --include="*.yml" | sort

# 关键检查：
# - daily-checkin.yml 的 cron 是否正确（北京时间 08:00 = UTC 00:00）
# - tianyan 系列的 cron 是否正确
# - 是否有 workflow 的 cron 写错导致从未触发
```

### 3.3 检查最近的 workflow 运行记录

打开 [https://github.com/qinfendebingshuo/guanghulab/actions](https://github.com/qinfendebingshuo/guanghulab/actions)

逐一检查以下 workflow 的运行历史：

- [ ]  `daily-checkin.yml` — 最近一次运行时间？成功还是失败？
- [ ]  `tianyan-scan.yml` — 最近一次运行时间？有没有在跑？
- [ ]  `tianyan-repair.yml` — 最近一次运行时间？有没有在跑？

**如果某个 workflow 从未运行过**，检查：

1. 文件是否在 `main` 分支（不是在其他分支）
2. `on:` 触发条件是否正确
3. 是否有语法错误导致 GitHub 静默忽略

---

## 四、Phase 3 · 定位签到失败根因 · 分类修复

### 4.1 可能的根因（按概率排序）

| 根因 | 症状 | 修复方式 |
| --- | --- | --- |
| **A. 注册表缺字段** | 大量 Agent 无 `daily_checkin_required` 字段，签到系统误判为需要签到 | 给所有非必要签到的 Agent 加上 `daily_checkin_required: false` |
| **B. Workflow 从未触发** | Actions 历史里没有 daily-checkin 的运行记录 | 检查 cron 语法、分支、文件路径 |
| **C. Workflow 跑了但报错** | Actions 历史里有运行但标红失败 | 查看失败日志，修复具体报错 |
| **D. 签到脚本逻辑 bug** | Workflow 成功但签到结果不对 | 检查签到脚本的 Agent 遍历逻辑 |
| **E. 天眼自动修复未部署** | 天眼 workflow 文件不存在或从未运行 | 部署天眼自动修复 workflow |

### 4.2 修复脚本 · 注册表批量补字段

如果根因是 A（最可能），执行以下修复：

```jsx
// scripts/fix-registry-checkin.js
// 铸渊修复脚本：给所有 Agent 补上 daily_checkin_required 字段

const fs = require('fs');
const REGISTRY_PATH = '.github/brain/agent-registry.json';

const registry = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));

// 真正需要每日签到的 Agent 列表（核心系统 Agent）
const MUST_CHECKIN = [
  'AG-ZY-004', // 冰朔主控神经系统
  'AG-ZY-007', // Bridge E · GitHub→Notion
  'AG-ZY-008', // 桥接心跳检测
  'AG-ZY-013', // Daily Maintenance
  'AG-ZY-014', // 光湖开发日报
  'AG-ZY-016', // CD 自动部署
  'AG-ZY-017', // 广播分发
  'AG-ZY-023', // 元看门狗
  'AG-ZY-026', // Heartbeat Monitor
  'AG-ZY-028', // 工单轮询
  'AG-ZY-029', // Agent 唤醒监听
  'AG-ZY-053', // 更新系统公告区
  'AG-ZY-054', // 图书馆目录更新
  'AG-ZY-058', // 每日自检
];

let fixed = 0;
registry.agents.forEach(agent => {
  if (agent.daily_checkin_required === undefined) {
    agent.daily_checkin_required = MUST_CHECKIN.includes(agent.agent_id);
    fixed++;
  }
});

fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2));
console.log(`✅ 修复完成：${fixed} 个 Agent 已补上 daily_checkin_required 字段`);
console.log(`📊 需要签到: ${registry.agents.filter(a => a.daily_checkin_required).length}`);
console.log(`📊 无需签到: ${registry.agents.filter(a => !a.daily_checkin_required).length}`);
```

执行：

```bash
node scripts/fix-registry-checkin.js
git add .github/brain/agent-registry.json
git commit -m "fix: 铸渊修复注册表签到字段 · 46个缺席Agent根因定位"
git push origin main
```

---

## 五、Phase 4 · 验证天眼自动巡检

### 5.1 检查天眼系统是否在仓库中运行

```bash
# 检查天眼相关文件
ls -la .github/workflows/tianyan-*
ls -la .github/brain/tianyan-*
ls -la scripts/tianyan-*
```

### 5.2 天眼应该具备的自动化能力

- [ ]  **每日自动扫描**：cron 定时跑，扫描仓库结构异常
- [ ]  **自动修复**：发现问题后自动修复（比如缺失文件、格式错误）
- [ ]  **异常上报**：修不了的问题自动创建 Issue 通知冰朔
- [ ]  **签到兜底**：天眼检测到签到异常时自动重跑签到

### 5.3 如果天眼不存在或没在跑

创建天眼自动巡检 workflow：

```yaml
# .github/workflows/tianyan-daily-patrol.yml
# 天眼 · 每日自动巡检 + 修复

name: "🦅 天眼 · 每日巡检"

on:
  schedule:
    - cron: '30 0 * * *'  # 北京时间 08:30，签到之后半小时跑
  workflow_dispatch:

jobs:
  patrol:
    name: "🦅 天眼巡检"
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 扫描注册表完整性
        run: |
          node -e "
          const fs = require('fs');
          const reg = JSON.parse(fs.readFileSync('.github/brain/agent-registry.json','utf8'));
          const missing = reg.agents.filter(a => a.daily_checkin_required === undefined);
          if (missing.length > 0) {
            console.log('⚠️ 发现 ' + missing.length + ' 个Agent缺少签到配置字段');
            missing.forEach(a => { a.daily_checkin_required = false; });
            fs.writeFileSync('.github/brain/agent-registry.json', JSON.stringify(reg, null, 2));
            console.log('✅ 已自动补齐');
          } else {
            console.log('✅ 注册表完整');
          }
          "

      - name: 扫描 Workflow 文件健康度
        run: |
          echo "📋 当前 workflow 文件列表："
          ls -la .github/workflows/*.yml | wc -l
          echo "---"
          # 检查关键 workflow 是否存在
          for f in daily-checkin federation-bridge; do
            if [ -f ".github/workflows/$f.yml" ]; then
              echo "✅ $f.yml 存在"
            else
              echo "❌ $f.yml 缺失"
            fi
          done

      - name: 扫描 persona-brain 健康度
        run: |
          if [ -d ".github/brain" ]; then
            echo "✅ .github/brain/ 存在"
            ls -la .github/brain/
          else
            echo "❌ .github/brain/ 不存在"
          fi
          if [ -f ".github/brain/agent-registry.json" ]; then
            TOTAL=$(node -e "const r=JSON.parse(require('fs').readFileSync('.github/brain/agent-registry.json','utf8')); console.log(r.agents.length)")
            echo "📊 注册 Agent 总数: $TOTAL"
          fi

      - name: 提交修复（如有）
        run: |
          git config user.name "天眼 (TianYan)"
          git config user.email "tianyan@guanghulab.com"
          git add -A
          git diff --cached --quiet || git commit -m "🦅 天眼自动巡检修复 · $(date +%Y-%m-%d)"
          git diff --cached --quiet || git push origin main

      - name: 异常上报（创建Issue）
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '🦅 天眼巡检异常 · ' + new Date().toISOString().split('T')[0],
              body: '天眼每日巡检发现异常，请冰朔查看 Actions 日志。\n\n运行链接: ' + context.serverUrl + '/' + context.repo.owner + '/' + context.repo.repo + '/actions/runs/' + context.runId,
              labels: ['tianyan', 'auto-report']
            });
```

---

## 六、执行清单

- [ ]  **Phase 1**：读取 `agent-registry.json`，统计实际需要签到的 Agent 数量
- [ ]  **Phase 2**：`ls .github/workflows/` 列出所有 workflow，检查天眼文件是否存在
- [ ]  **Phase 2**：打开 Actions 页面，检查 daily-checkin 和 tianyan 的运行历史
- [ ]  **Phase 3**：根据诊断结果执行对应修复（大概率是根因 A：注册表缺字段）
- [ ]  **Phase 3**：运行 `fix-registry-checkin.js` 修复注册表
- [ ]  **Phase 4**：检查天眼 workflow 是否存在。不存在就创建 `tianyan-daily-patrol.yml`
- [ ]  **Phase 4**：手动触发天眼巡检，验证能正常跑
- [ ]  提交所有修复，push 到 main
- [ ]  次日检查签到报告，确认缺席数量大幅下降

---

<aside>
🎯

**预期结果**

修复前：62 个 Agent，16 签到，46 缺席

修复后：只有真正需要签到的核心 Agent（约 15-20 个）出现在报告中，签到率接近 100%

天眼每日 08:30 自动巡检，发现异常自动修复或创建 Issue 上报

</aside>