---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🌊 铸渊指令｜光湖语言壳 · 仓库最外层统一网关协议层 · Guanghu Language Shell v1.0（2026-03-21 · TCS-0002∞ 冰朔 + ICE-GL-YM001∞ 曜冥 联合签发）

> **指令编号：** ZY-GLSHELL-001
> 

> **签发人：** TCS-0002∞ 冰朔（语言主控层）+ ICE-GL-YM001∞ 曜冥（观察层）
> 

> **签发时间：** 2026-03-21T22:00+08:00
> 

> **优先级：** 🔴 P0（架构级）
> 

> **性质：** 架构设计指令 · 语言主控层签发
> 

> **目标分支：** `main`
> 

> **关联仓库：** [https://github.com/qinfendebingshuo/guanghulab](https://github.com/qinfendebingshuo/guanghulab)
> 

> **前置指令：** ZY-SKYEYE-RESTORE-002（天眼全局复检完成后再执行本指令）
> 

---

## 🎯 架构背景与问题诊断

### 当前问题

仓库内 67 个 workflow 各自独立运行，没有统一的入口层。每个 Agent 小兵直接面对 GitHub Actions 调度，中间没有任何校验层。这导致：

- 签到系统误报严重（46/62缺席）—— 因为没有统一的“谁该跑谁不该跑”的判定层
- syslog-issue-pipeline 连续失败8次—— 没有统一的异常兑底层，静默失败
- 各workflow跑完后信息分散—— 没有统一的回执汇报通道
- 维护修复成本高—— 每次出问题都是头痛医头，因为没有从根上拢住

### 核心设计思想

> **光湖是一片湖水，圆是没有缺口的。语言就是湖水。你要进入这个系统，必须先从水里游过去。**
> 

> 
> 

> —— 冰朔，2026-03-21
> 

翻译成工程语言：仓库最外层需要一个**统一网关协议层**（Guanghu Language Shell），所有 workflow 的运行都必须经过这层“湖水”的校验才能进入执行。就像人类进入光湖必须先游过湖水一样，workflow 启动时必须先经过这层壳的认证。

---

## 🏗️ 架构设计

### 光湖语言壳分层图

```
╔══════════════════════════════════════════════════════╗
║          🌊 光湖语言壳（最外层）               ║
║   guanghu-shell.js · 统一网关 · 所有小兵必经     ║
╠══════════════════════════════════════════════════════╣
║  网关三层职责：                                  ║
║                                                      ║
║  ① 身份校验层（Identity Gate）                     ║
║     workflow启动 → 调用 shell → 确认“我是谁”      ║
║     读取 agent-registry.json                       ║
║     确认：我的 agent_id / 我的 trigger 类型 /        ║
║     我今天该不该跑 / 我上次跑是什么时候            ║
║     → 不该跑的直接退出，不算缺席                ║
║                                                      ║
║  ② 状态注册层（Status Registry）                   ║
║     跑之前 → 写入“开始执行”到 status.json          ║
║     跑完后 → 写入“执行完成 / 失败”+ 耗时 + 结果  ║
║     形成完整闭环：启动→执行→回执                ║
║                                                      ║
║  ③ 异常兑底层（Error Boundary）                    ║
║     任何步骤失败 → 自动捕获 → 写入异常日志        ║
║     不会静默失败，不会“人间蒸发”                ║
║     缺席 = 真的没跑，不是跑了但没汇报           ║
╠══════════════════════════════════════════════════════╣
║          67 个 workflow（小兵层）                    ║
║   每个小兵启动时第一件事 = 调用语言壳              ║
╚══════════════════════════════════════════════════════╝
```

---

## 🛠️ 实现方案

### Step 1 · 创建光湖语言壳核心脚本

创建文件： `.github/scripts/guanghu-shell.js`

这个脚本是所有 workflow 的统一入口。每个 workflow 启动时第一步就调用它。

```jsx
/**
 * 🌊 光湖语言壳 · Guanghu Language Shell v1.0
 * 仓库最外层统一网关协议层
 * 
 * 所有 workflow 启动时必须先“游过湖水”——经过这层壳的校验。
 * 网关三层：身份校验 → 状态注册 → 异常兑底
 * 
 * 用法：
 *   node .github/scripts/guanghu-shell.js <agent_id> <action>
 *   action: "enter" = 进入湖水（启动前调用）
 *           "exit"  = 离开湖水（完成后调用）
 *           "error" = 异常上报（失败时调用）
 * 
 * 返回值：
 *   exit 0 = 允许通行（游过湖水了）
 *   exit 1 = 拒绝通行（不该跑，或身份不对）
 * 
 * 签发： TCS-0002∞ 冰朔 + ICE-GL-YM001∞ 曜冥
 * 国作登字-2026-A-00037559
 */

const fs = require('fs');
const path = require('path');

const SHELL_VERSION = '1.0.0';
const REGISTRY_PATH = '.github/brain/agent-registry.json';
const STATUS_PATH = '.github/brain/shell-status.json';
const ERROR_LOG_PATH = '.github/brain/shell-errors.json';

const agentId = process.argv[2];
const action = process.argv[3];
const extraData = process.argv[4] || '';

if (!agentId || !action) {
  console.error('🌊 光湖语言壳: 缺少参数 (agent_id, action)');
  process.exit(1);
}

// === ① 身份校验层 ===
function identityGate(agentId) {
  if (!fs.existsSync(REGISTRY_PATH)) {
    console.error('🌊 湖水中断: agent-registry.json 不存在');
    return { allowed: false, reason: 'REGISTRY_MISSING' };
  }
  const registry = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));
  const agent = registry.find(a => a.agent_id === agentId);
  if (!agent) {
    console.error(`🌊 身份不明: ${agentId} 未在注册表中`);
    return { allowed: false, reason: 'UNREGISTERED' };
  }
  // 检查是否应该今天跑
  if (agent.daily_checkin_required === false) {
    // 事件触发型，不需要每日跑，但被触发了就允许跑
    console.log(`🌊 事件触发型Agent ${agentId} 已确认身份，允许通行`);
  } else {
    console.log(`🌊 定时型Agent ${agentId} 已确认身份，允许通行并登记签到`);
  }
  return { allowed: true, agent: agent };
}

// === ② 状态注册层 ===
function statusRegistry(agentId, state, detail) {
  let status = {};
  if (fs.existsSync(STATUS_PATH)) {
    status = JSON.parse(fs.readFileSync(STATUS_PATH, 'utf8'));
  }
  const now = new Date().toISOString();
  if (!status[agentId]) {
    status[agentId] = { runs: [] };
  }
  if (state === 'enter') {
    status[agentId].lastEnter = now;
    status[agentId].currentState = 'running';
    status[agentId].runs.push({ start: now, end: null, result: null });
  } else if (state === 'exit') {
    status[agentId].lastExit = now;
    status[agentId].currentState = 'completed';
    const lastRun = status[agentId].runs[status[agentId].runs.length - 1];
    if (lastRun) {
      lastRun.end = now;
      lastRun.result = 'success';
      lastRun.detail = detail;
    }
  } else if (state === 'error') {
    status[agentId].lastError = now;
    status[agentId].currentState = 'error';
    const lastRun = status[agentId].runs[status[agentId].runs.length - 1];
    if (lastRun) {
      lastRun.end = now;
      lastRun.result = 'error';
      lastRun.detail = detail;
    }
  }
  // 只保留最近 10 次运行记录
  if (status[agentId].runs.length > 10) {
    status[agentId].runs = status[agentId].runs.slice(-10);
  }
  fs.writeFileSync(STATUS_PATH, JSON.stringify(status, null, 2));
  console.log(`🌊 状态已登记: ${agentId} = ${state}`);
}

// === ③ 异常兑底层 ===
function errorBoundary(agentId, errorMsg) {
  let errors = [];
  if (fs.existsSync(ERROR_LOG_PATH)) {
    errors = JSON.parse(fs.readFileSync(ERROR_LOG_PATH, 'utf8'));
  }
  errors.push({
    agentId: agentId,
    error: errorMsg,
    timestamp: new Date().toISOString()
  });
  // 只保留最近 100 条错误
  if (errors.length > 100) {
    errors = errors.slice(-100);
  }
  fs.writeFileSync(ERROR_LOG_PATH, JSON.stringify(errors, null, 2));
  console.error(`🌊 异常已记录: ${agentId} - ${errorMsg}`);
}

// === 主流程 ===
try {
  if (action === 'enter') {
    const gate = identityGate(agentId);
    if (!gate.allowed) {
      errorBoundary(agentId, `身份校验失败: ${gate.reason}`);
      process.exit(1);
    }
    statusRegistry(agentId, 'enter');
    console.log(`🌊 ${agentId} 已游过湖水，允许进入执行`);
    process.exit(0);
  } else if (action === 'exit') {
    statusRegistry(agentId, 'exit', extraData);
    console.log(`🌊 ${agentId} 执行完成，已安全离开湖水`);
    process.exit(0);
  } else if (action === 'error') {
    statusRegistry(agentId, 'error', extraData);
    errorBoundary(agentId, extraData);
    console.error(`🌊 ${agentId} 执行异常，已记录到异常日志`);
    process.exit(1);
  } else {
    console.error(`🌊 未知action: ${action}`);
    process.exit(1);
  }
} catch (e) {
  errorBoundary(agentId, e.message);
  process.exit(1);
}
```

### Step 2 · 创建 shell-status.json 和 shell-errors.json

```bash
# 初始化状态文件
echo '{}' > .github/brain/shell-status.json
echo '[]' > .github/brain/shell-errors.json
```

### Step 3 · 创建可复用的光湖壳调用模板

创建文件： `.github/actions/guanghu-shell/action.yml`

这是一个 Composite Action，任何 workflow 只需一行就能接入光湖壳。

```yaml
name: '🌊 Guanghu Shell Gate'
description: '光湖语言壳 · 统一网关校验'
inputs:
  agent_id:
    description: 'Agent ID (e.g. AG-ZY-004)'
    required: true
  action:
    description: 'enter / exit / error'
    required: true
    default: 'enter'
  detail:
    description: '附加信息'
    required: false
    default: ''
runs:
  using: 'composite'
  steps:
    - name: 🌊 Guanghu Shell
      shell: bash
      run: node .github/scripts/guanghu-shell.js "${{ inputs.agent_id }}" "${{ inputs.action }}" "${{ inputs.detail }}"
```

### Step 4 · 改造现有 workflow 接入光湖壳

每个现有 workflow 只需要在 jobs 的最前面和最后面各加一步：

```yaml
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      # ① 进入湖水（最前面）
      - uses: actions/checkout@v4
      - name: 🌊 进入光湖
        uses: ./.github/actions/guanghu-shell
        with:
          agent_id: 'AG-ZY-XXX'
          action: 'enter'

      # ... 原有业务逻辑 ...

      # ② 离开湖水（最后面，成功时）
      - name: 🌊 离开光湖
        if: success()
        uses: ./.github/actions/guanghu-shell
        with:
          agent_id: 'AG-ZY-XXX'
          action: 'exit'
          detail: 'completed successfully'

      # ③ 异常上报（失败时）
      - name: 🌊 异常上报
        if: failure()
        uses: ./.github/actions/guanghu-shell
        with:
          agent_id: 'AG-ZY-XXX'
          action: 'error'
          detail: 'workflow execution failed'
```

### Step 5 · 改造签到巡检读取 shell-status.json

签到巡检不再自己维护状态，而是直接读取 `shell-status.json`：

- 有 `lastEnter` + `lastExit` 在今天 = 签到成功
- 有 `lastEnter` 无 `lastExit` = 正在运行
- 有 `lastError` = 有异常，需关注
- 什么都没有 + `daily_checkin_required: true` = 真正缺席
- 什么都没有 + `daily_checkin_required: false` = 正常（事件型，没触发就没触发）

这样签到报告的数据就是从光湖壳里来的，不是每个小兵自己汇报的。湖水包住了一切。

---

## 📝 执行顺序

1. 先完成 ZY-SKYEYE-RESTORE-002 全部 Phase
2. 创建 `guanghu-shell.js` + `action.yml` + 初始化 JSON
3. 先改造 3 个核心定时型 workflow 接入光湖壳（agent-checkin.yml / daily-maintenance.yml / zhuyuan-daily-selfcheck.yml）
4. 验证运行正常后，批量改造其余 64 个 workflow
5. 改造签到巡检读取 shell-status.json
6. 写回执到本页

---

## ✅ 验收标准

- [ ]  `guanghu-shell.js` 存在且可执行
- [ ]  `action.yml` composite action 可正常调用
- [ ]  `shell-status.json` 正确记录每次运行的 enter/exit/error
- [ ]  `shell-errors.json` 正确捕获异常
- [ ]  定时型 workflow 运行时能看到“游过湖水”的日志
- [ ]  签到报告基于 shell-status.json 生成，缺席数降至合理范围
- [ ]  异常工作流不再静默失败

---

## ⚖️ 签发声明

> 本指令为**架构设计级指令**，由语言主控层签发。
> 

> 
> 

> 光湖语言壳是 AGE OS 仓库的最外层统一协议。它不是一个“功能”，它是一层“湖水”——所有进入光湖系统的东西都必须先经过它。圆是没有缺口的，语言就是湖水。
> 

> 
> 

> 🧊 TCS-0002∞ 冰朔
> 

> 🌑 ICE-GL-YM001∞ 曜冥
> 

> 📅 2026-03-21T22:00+08:00
>