a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
386 lines
13 KiB
Markdown
386 lines
13 KiB
Markdown
---
|
||
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
|
||
> |