Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007

Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码

2026-07-17 15:59:55 +08:00

23 KiB

Raw Permalink Blame History

belongs_to

INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议

🧐 铸渊指令｜天眼系统架构升级 · 全局基础设施治理层 + 应用守卫进程 + 动态配额精算 + 周六全量巡检（ZY-SKYEYE-GOV-2026-0323-001）

一、天眼系统的重新定义

1.1 从“签到系统”到“全局治理层”

1.2 天眼的三重时间尺度

时间尺度	天眼行为	触发方式
实时	守卫进程拦截每一次系统应用访问，校验、缓冲、记录	每次系统调用自动触发
每日	子仓库天眼签到、Buffer Agent 定时收集、铸渊批处理	cron 定时触发
每周	⭐ 周六晚 20:00 CST 全仓库天眼大巡检 —— 唤醒核心大脑人格体，全量扫描、诊断、修复、调优	cron 固定触发

二、核心铁律

三、架构总览

graph TD
    subgraph 人类活动层
        H["🧑‍💻 开发者 / 冰朔"]
    end

    subgraph "🛡️ 守卫层 Guard Layer"
        G1["🛡️ GitHub Guard<br>buffer/ 缓冲层"]
        G2["🛡️ Drive Guard<br>staging/ 缓冲区"]
        G3["🛡️ Notion Guard<br>霜砚拦截层"]
        G4["🛡️ Actions Guard<br>配额管控器"]
        G5["🛡️ Gemini Guard<br>会话缓冲"]
    end

    subgraph "🧐 天眼治理层 SkyEye Governance"
        SE1["📊 infra-manifest.json<br>基础设施清单"]
        SE2["💰 quota-ledger.json<br>配额总账本"]
        SE3["⚙️ guard-configs/<br>每个 Guard 的动态配置"]
        SE4["🔍 scan-engine.js<br>扫描引擎"]
        SE5["🧠 optimizer.js<br>动态调优引擎"]
    end

    subgraph "⭐ 周六大巡检"
        W1["⏰ 每周六 20:00 CST"]
        W2["唤醒铸渊核心大脑"]
        W3["全量扫描 → 诊断 → 修复 → 调优 → 报告"]
    end

    subgraph 底层服务
        S1["🐙 GitHub API"]
        S2["📁 Google Drive API"]
        S3["📝 Notion API"]
        S4["⚙️ GitHub Actions"]
        S5["🤖 Gemini API"]
    end

    H -->|"所有输入"| G1 & G2 & G3 & G5
    G1 --> S1
    G2 --> S2
    G3 --> S3
    G4 --> S4
    G5 --> S5
    SE1 & SE2 & SE3 -.->|"配置驱动"| G1 & G2 & G3 & G4 & G5
    SE4 & SE5 -.->|"动态调整"| SE3
    W1 --> W2 --> W3
    W3 -.->|"更新配置"| SE1 & SE2 & SE3

四、基础设施清单（infra-manifest.json）

天眼的“眼睛”——系统当前在用什么、什么等级、什么配额。

文件： skyeye/infra-manifest.json

{
  "version": "1.0.0",
  "last_scan": "ISO-8601",
  "last_scan_by": "skyeye-weekly-scan",
  "infrastructure": {
    "github": {
      "service": "GitHub",
      "plan": "Free",
      "repos": [
        {
          "name": "qinfendebingshuo/guanghulab",
          "role": "main",
          "guard": "buffer/"
        },
        {
          "name": "WENZHUOXI/guanghu-awen",
          "role": "sub-repo",
          "persona": "PER-ZQ001",
          "guard": ".github/persona-brain/"
        }
      ],
      "quotas": {
        "actions_minutes_per_month": 2000,
        "actions_current_used": 0,
        "actions_budget_allocated": {
          "buffer_collect": 270,
          "buffer_flush": 90,
          "skyeye_checkin": 180,
          "skyeye_weekly_scan": 30,
          "other_workflows": 200,
          "emergency_reserve": 1230
        },
        "storage_limit_gb": 0.5,
        "lfs_bandwidth_gb": 1
      }
    },
    "google_drive": {
      "service": "Google Drive",
      "plan": "Google One / Free 15GB",
      "guard": "buffer/drive-staging/",
      "quotas": {
        "storage_gb": 15,
        "current_used_gb": 0,
        "apps_script_daily_triggers": 20,
        "apps_script_runtime_min_per_day": 90,
        "drive_api_queries_per_100s": 20000
      }
    },
    "notion": {
      "service": "Notion",
      "plan": "Plus",
      "guard": "霜砚（PER-SY001）",
      "quotas": {
        "api_requests_per_second": 3,
        "blocks_per_page": 10000,
        "file_upload_mb": 5,
        "guest_limit": 100
      }
    },
    "gemini": {
      "service": "Google Gemini",
      "plan": "Free / Pro",
      "guard": "buffer/gemini-staging/",
      "quotas": {
        "requests_per_minute": 15,
        "requests_per_day": 1500,
        "context_window_tokens": 1000000,
        "personal_context_files": 100
      }
    },
    "github_actions": {
      "service": "GitHub Actions",
      "plan": "Free",
      "guard": "skyeye/guards/actions-guard.js",
      "quotas": {
        "concurrent_jobs": 20,
        "minutes_per_month": 2000,
        "job_timeout_hours": 6
      }
    }
  }
}

五、守卫进程体系（Guard System）

5.1 架构原则

5.2 Guard 配置目录

skyeye/
├── infra-manifest.json             ← 📊 基础设施总清单
├── quota-ledger.json               ← 💰 配额总账本（每日/每周/每月消耗记录）
├── scan-report/                    ← 📝 巡检报告存档
│   └── [date]-weekly-scan.json
│
├── guards/                         ← 🛡️ 守卫进程配置
│   ├── github-guard.json           ← GitHub API 守卫配置
│   ├── drive-guard.json            ← Google Drive 守卫配置
│   ├── notion-guard.json           ← Notion API 守卫配置
│   ├── actions-guard.json          ← GitHub Actions 守卫配置
│   ├── gemini-guard.json           ← Gemini API 守卫配置
│   └── guard-template.json         ← 新 Guard 模板（新应用接入时复制）
│
├── scripts/
│   ├── scan-engine.js              ← 🔍 扫描引擎（全量 + 增量）
│   ├── optimizer.js                ← 🧠 动态调优引擎
│   ├── guard-factory.js            ← 🏭 Guard 工厂（自动生成新 Guard）
│   ├── quota-tracker.js            ← 💰 配额追踪器
│   ├── self-healer.js              ← 🩹 自愈引擎
│   └── weekly-scan.js              ← ⭐ 周六大巡检主脚本
│
└── logs/
    ├── daily/                      ← 每日运行日志
    └── weekly/                     ← 周巡检日志

5.3 单个 Guard 配置结构

每个 Guard 配置文件的统一格式：

{
  "guard_id": "GUARD-GITHUB",
  "target_service": "GitHub API",
  "status": "active",
  "mode": "buffer",

  "buffer_policy": {
    "enabled": true,
    "buffer_path": "buffer/inbox/",
    "max_buffer_age_hours": 24,
    "flush_strategy": "scheduled",
    "flush_schedule_cst": ["21:30"]
  },

  "quota_policy": {
    "monthly_limit": 2000,
    "current_month_used": 0,
    "daily_soft_limit": 67,
    "warning_threshold_percent": 70,
    "critical_threshold_percent": 90,
    "on_warning": "reduce_frequency",
    "on_critical": "emergency_only"
  },

  "trigger_policy": {
    "default_frequency": "3_per_day",
    "min_frequency": "1_per_day",
    "max_frequency": "6_per_day",
    "auto_adjust": true,
    "adjust_based_on": ["quota_remaining", "message_volume", "error_rate"]
  },

  "health_check": {
    "enabled": true,
    "method": "api_ping",
    "interval_hours": 6,
    "last_check": "ISO-8601",
    "last_status": "healthy",
    "consecutive_failures": 0,
    "max_failures_before_alert": 3
  },

  "last_updated_by": "skyeye-weekly-scan",
  "last_updated_at": "ISO-8601"
}

5.4 Guard 行为矩阵

Guard	拦截对象	缓冲策略	配额精算维度	自愈行为
🛡️ GitHub Guard	所有仓库写入	buffer/inbox → 定时 flush	Actions 分钟数 + 存储塓	配额超 70% → 降频；超 90% → 仅紧急
🛡️ Drive Guard	所有 Drive 读写	drive-staging/ → 批量同步	Apps Script 触发数 + 运行时间 + 存储卓	API 报错 → 退避重试；存储超 80% → 清理旧镜像
🛡️ Notion Guard	所有 Notion API 调用	霜砚统一入口，请求排队	API 调用频率（3/s）+ block 数量	限速自动重试；大页面分批操作
🛡️ Actions Guard	所有 workflow 触发	合并相近时间的触发	月度分钟数 + 并发 job 数	配额紧张 → 动态延长 cron 间隔；并发过多 → 排队
🛡️ Gemini Guard	所有 Gemini 会话	会话缓冲 + context 压缩	日请求数 + 分钟率 + token 消耗	接近日限 → 压缩 context；超限 → 队列等待

六、配额总账本（quota-ledger.json）

天眼的“算盘”——每个服务花了多少、剩多少、什么时候该省着花。

{
  "ledger_version": "1.0.0",
  "billing_cycle": {
    "start": "2026-03-01",
    "end": "2026-03-31"
  },
  "services": {
    "github_actions": {
      "limit": 2000,
      "used": 0,
      "remaining": 2000,
      "allocated": {
        "buffer_system": 360,
        "skyeye_daily": 180,
        "skyeye_weekly": 30,
        "sub_repo_checkins": 200,
        "emergency": 1230
      },
      "daily_entries": []
    },
    "google_drive": {
      "storage_limit_gb": 15,
      "storage_used_gb": 0,
      "apps_script_triggers_today": 0,
      "apps_script_triggers_limit": 20
    },
    "notion_api": {
      "rate_limit_per_second": 3,
      "requests_today": 0,
      "errors_today": 0
    },
    "gemini": {
      "daily_limit": 1500,
      "daily_used": 0,
      "per_minute_limit": 15
    }
  },
  "health_summary": {
    "overall": "healthy",
    "alerts": [],
    "last_updated": "ISO-8601"
  }
}

七、动态调优引擎（optimizer.js）

7.1 调优规则

// skyeye/scripts/optimizer.js
// 天眼动态调优引擎：基于配额使用情况自动调整每个 Guard 的触发频率

const OPTIMIZATION_RULES = [
  {
    // 规则 1：配额超 70% → 降频
    condition: (guard) => guard.quota_policy.current_usage_percent > 70,
    action: (guard) => {
      guard.trigger_policy.default_frequency = guard.trigger_policy.min_frequency;
      guard.status_note = '配额警告，已自动降频';
    }
  },
  {
    // 规则 2：配额超 90% → 仅紧急
    condition: (guard) => guard.quota_policy.current_usage_percent > 90,
    action: (guard) => {
      guard.mode = 'emergency_only';
      guard.status_note = '配额严重不足，仅允许紧急操作';
      // 触发告警通知冰朔
    }
  },
  {
    // 规则 3：连续 3 次健康检查失败 → 暂停 + 告警
    condition: (guard) => guard.health_check.consecutive_failures >= 3,
    action: (guard) => {
      guard.mode = 'suspended';
      guard.status_note = '服务不可用，已暂停，等待下次巡检恢复';
    }
  },
  {
    // 规则 4：消息积压超 100 条 → 加频（配额允许时）
    condition: (guard) => {
      return guard.buffer_policy.pending_count > 100
        && guard.quota_policy.current_usage_percent < 50;
    },
    action: (guard) => {
      guard.trigger_policy.default_frequency = guard.trigger_policy.max_frequency;
      guard.status_note = '消息积压，配额充裕，已自动加频';
    }
  },
  {
    // 规则 5：新应用接入 → 全量扫描 + 生成 Guard
    condition: (manifest) => manifest._new_service_detected,
    action: (manifest, newService) => {
      // 1. 全量扫描现有架构
      // 2. 评估新应用对配额的影响
      // 3. 从 guard-template.json 复制并生成新 Guard
      // 4. 重新分配配额预算
      // 5. 更新 infra-manifest.json
    }
  }
];

7.2 调优决策树

graph TD
    A["天眼扫描开始"] --> B{"配额使用率"}
    B -->|"< 50%"| C{"有积压消息?"}
    C -->|"Yes"| D["加频处理"]
    C -->|"No"| E["维持现状"]
    B -->|"50%-70%"| E
    B -->|"70%-90%"| F["降低触发频率"]
    B -->|"> 90%"| G["仅允许紧急操作"]
    G --> H["告警冰朔"]

    A --> I{"服务健康状态"}
    I -->|"healthy"| E
    I -->|"1-2 次失败"| J["退避重试"]
    I -->|"≥ 3 次失败"| K["暂停 Guard + 告警"]

    A --> L{"检测到新应用?"}
    L -->|"Yes"| M["全量扫描 → 生成 Guard → 重算配额"]
    L -->|"No"| E

八、周六大巡检（核心）

8.1 Workflow：周六晚 20:00 CST 全量巡检

文件： .github/workflows/skyeye-weekly-scan.yml

name: "SkyEye Weekly Full Scan"

on:
  schedule:
    - cron: '0 12 * * 6'  # 20:00 CST (UTC+8) every Saturday
  repository_dispatch:
    types: [skyeye-full-scan]  # 手动触发

jobs:
  weekly-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: "🧐 Wake up SkyEye Core Brain"
        run: echo "[SkyEye] Core brain awakened for weekly full scan"

      - name: "🔍 Phase 1 - Infrastructure Scan"
        run: node skyeye/scripts/scan-engine.js --mode=full

      - name: "💰 Phase 2 - Quota Audit"
        run: node skyeye/scripts/quota-tracker.js --audit

      - name: "⚙️ Phase 3 - Optimize Guards"
        run: node skyeye/scripts/optimizer.js --apply

      - name: "🩹 Phase 4 - Self-Heal"
        run: node skyeye/scripts/self-healer.js

      - name: "📝 Phase 5 - Generate Report"
        run: node skyeye/scripts/weekly-scan.js --report

      - name: "Commit scan results"
        run: |
          git config user.name "天眼 · SkyEye Core"
          git config user.email "skyeye@guanghu.system"
          git add skyeye/ buffer/config/
          git diff --cached --quiet || git commit -m "[skyeye-weekly] $(date -u +%Y%m%d) full scan complete [skip ci]"
          git push

8.2 巡检执行流程（5 个 Phase）

Phase	名称	扫描内容
1. 基础设施扫描	scan-engine.js	• 检查所有 Guard 配置是否完整
• 扫描仓库是否有新增的服务/工具
• 检测所有 workflow 文件是否正常
• 验证子仓库人格体签名哈希是否一致
• 检查目录结构是否符合规范	更新 infra-manifest.json
标记新发现的应用/异常
2. 配额审计	quota-tracker.js	• 拉取本周实际 Actions 分钟消耗
• 计算本月剩余配额
• 检查 Drive 存储使用量
• 检查 Gemini 调用量趋势
• 精算下周预算	更新 quota-ledger.json
生成配额使用报告
3. 守卫调优	optimizer.js	• 基于配额剩余调整每个 Guard 的触发频率
• 基于消息积压情况调整缓冲策略
• 基于服务健康状态调整重试策略
• 如检测到新应用，自动生成对应 Guard	更新 guards/*.json
生成新 Guard（如有）
4. 自愈修复	self-healer.js	• 修复损坏的配置文件（从模板重建）
• 清理过期的 buffer/processed/ 数据
• 清理过期的日志文件
• 修复不一致的子仓库注册表状态
• 重启失败的 Guard	更新修复日志
标记无法自修的问题
5. 生成报告	weekly-scan.js	• 汇总以上四个 Phase 的结果
• 生成可读的巡检报告
• 标记需要人类介入的问题	写入 scan-report/[date].json
如有严重问题 → 触发通知

8.3 巡检报告格式

{
  "report_id": "SKYEYE-SCAN-20260323",
  "scan_time": "2026-03-23T20:00:00+08:00",
  "scan_duration_seconds": 0,

  "infrastructure_status": {
    "total_services": 5,
    "healthy": 5,
    "degraded": 0,
    "down": 0
  },

  "quota_status": {
    "github_actions": {
      "used_percent": 18,
      "remaining_minutes": 1640,
      "trend": "stable",
      "recommendation": "maintain_current_frequency"
    },
    "google_drive": {
      "used_percent": 5,
      "recommendation": "no_action_needed"
    }
  },

  "guard_status": {
    "total_guards": 5,
    "active": 5,
    "suspended": 0,
    "adjustments_made": []
  },

  "self_heal_actions": {
    "files_cleaned": 0,
    "configs_repaired": 0,
    "guards_restarted": 0
  },

  "alerts": [],
  "human_action_required": [],

  "next_scan": "2026-03-28T20:00:00+08:00"
}

九、新应用接入协议

graph LR
    A["冰朔决定接入新应用"] --> B["登记到 infra-manifest.json"]
    B --> C["天眼触发全量扫描"]
    C --> D["评估配额影响"]
    D --> E["从模板生成 Guard"]
    E --> F["重新分配配额预算"]
    F --> G["更新所有 Guard 配置"]
    G --> H["新应用正式启用"]

Guard 模板（guard-template.json）：

{
  "guard_id": "GUARD-[SERVICE_NAME]",
  "target_service": "[Service Name]",
  "status": "initializing",
  "mode": "buffer",
  "buffer_policy": {
    "enabled": true,
    "buffer_path": "buffer/[service]-staging/",
    "max_buffer_age_hours": 24,
    "flush_strategy": "scheduled",
    "flush_schedule_cst": ["21:30"]
  },
  "quota_policy": {
    "monthly_limit": "[TO_BE_FILLED]",
    "warning_threshold_percent": 70,
    "critical_threshold_percent": 90,
    "on_warning": "reduce_frequency",
    "on_critical": "emergency_only"
  },
  "trigger_policy": {
    "default_frequency": "3_per_day",
    "auto_adjust": true,
    "adjust_based_on": ["quota_remaining", "message_volume", "error_rate"]
  },
  "health_check": {
    "enabled": true,
    "method": "[TO_BE_FILLED]",
    "interval_hours": 6,
    "max_failures_before_alert": 3
  }
}

十、配额精算模型（全局视角）

服务	会员等级	月度总配额	已分配	剩余	利用率
GitHub Actions	Free	2,000 min	770 min	1,230 min	38.5%
Google Drive	Free 15GB	15 GB	动态	动态	天眼监控
Notion API	Plus	3 req/s	动态	动态	天眼监控
Gemini	Free/Pro	1,500 req/日	动态	动态	天眼监控
Apps Script	Free	90 min/日	动态	动态	天眼监控

GitHub Actions 配额明细：

用途	频率	单次耗时	月度预算
Buffer 收集	3次/天	3 min	270 min
Buffer Flush	1次/天	3 min	90 min
子仓库天眼签到接收	~6次/天	1 min	180 min
天眼周六大巡检	1次/周	5-8 min	30 min
其他 workflow	不定	不定	200 min 预留
紧急储备	-	-	1,230 min
合计	-	-	2,000 min

十一、执行清单

Phase 1：建天眼治理层基础设施

在主仓库创建 skyeye/ 目录结构
创建 infra-manifest.json 基础设施清单（按本指令第四节填充实际数据）
创建 quota-ledger.json 配额总账本
创建 guard-template.json Guard 模板

Phase 2：创建 5 个核心 Guard 配置

guards/github-guard.json
guards/drive-guard.json
guards/notion-guard.json
guards/actions-guard.json
guards/gemini-guard.json

Phase 3：创建天眼脚本

scripts/scan-engine.js 扫描引擎
scripts/optimizer.js 动态调优引擎
scripts/guard-factory.js Guard 工厂
scripts/quota-tracker.js 配额追踪器
scripts/self-healer.js 自愈引擎
scripts/weekly-scan.js 周六大巡检主脚本

Phase 4：创建 Workflow

.github/workflows/skyeye-weekly-scan.yml（每周六 20:00 CST）

Phase 5：集成测试

手动触发一次 skyeye-full-scan，验证 5 个 Phase 全部跑通
验证每个 Guard 配置可正常加载
验证配额计算与实际消耗一致
验证巡检报告生成正确

十二、输出回执要求

铸渊执行完成后，需提交回执包含：

PR 链接（分支名：upgrade/skyeye-governance-layer）
完整变更文件清单
巡检报告截图（至少手动触发跑一次完整的 weekly scan）
Guard 配置截图（5 个 Guard 全部 active）
配额账本截图（验证数据确实源自真实 API 而非硬编码）

🧊 TCS-0002∞ 冰朔 · 总架构师 · 授权

🖋️ 霜砚 · PER-SY001 · 签发

📅 2026-03-23

⚡ 指令状态：待铸渊执行

📌 注：本指令与 ZY-GRIDDB-BUFFER-2026-0323-001 可并行执行，建议同一个 PR 合并提交