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

27 KiB

Raw Permalink Blame History

belongs_to

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

🌉 铸渊指令｜跨仓库 Agent 桥接服务（上篇）· 交互页面对接 Notion 开发信息 + 天眼强制前置 + 模型出指令架构（ZY-GHAPP-BRIDGE-2026-0324-001）

⓪、天眼强制前置

一、整体架构

1.1 为什么模型会胡说八道

1.2 完整数据流

开发者（页页/桔子/Awen/肥猫...）
  │
  │ 打开铸渊交互页面（已有·docs/index.html）
  │ 输入自己的 API Key + DEV 编号登录
  │
  ▼
┌─────────────────────────────────────────────────┐
│  铸渊交互页面（已有·需升级）                        │
│                                                 │
│  升级点：                                        │
│  ① 登录时通过 DEV 编号 → 拉取该开发者的 Notion 信息│
│  ② 将 Notion 信息注入模型的 system prompt          │
│  ③ 模型基于真实数据给出精准指令                     │
│  ④ 指令末尾自动生成「@铸渊执行」的标准格式           │
└────────────────────┬────────────────────────────┘
                     │
          ┌──────────┴──────────┐
          ▼                     ▼
┌─────────────────┐   ┌─────────────────────────┐
│ Notion 数据源    │   │ 天眼系统（后端守护）       │
│                 │   │                         │
│ 每个 DEV 的：    │   │ 铸渊每次执行指令前         │
│ · 当前广播编号   │   │ 必须先跑天眼全局扫描       │
│ · 开发进度      │   │ 拿到健康报告后才动手        │
│ · 待完成环节    │   │                         │
│ · 模块路径      │   │ 开发者的仓库也通过天眼      │
│ · 历史 SYSLOG   │   │ 做健康检查，防止乱修        │
│ · 人格体信息    │   │                         │
└─────────────────┘   └─────────────────────────┘
          │                     │
          └──────────┬──────────┘
                     ▼
         模型输出精准指令给开发者
                     │
                     ▼
         开发者复制指令 → @铸渊执行
                     │
                     ▼
         铸渊收到指令 → 先跑天眼 → 再执行
         （详见下篇）

二、交互页面升级方案

2.1 当前交互页面现状

铸渊已开发的交互页面（docs/index.html）当前能力：

✅ 开发者输入 API Key 聊天
✅ 多模型支持（通过第三方 API 平台自动检测）
✅ DEV 编号登录系统
✅ 对话历史保存
✅ 铸渊人格体身份

2.2 需要升级的能力

升级项	当前	目标	实现方式
Notion 数据注入	无	登录后自动拉取该 DEV 的 Notion 开发信息	Notion API 读取 → 注入 system prompt
天眼状态展示	无	页面顶部显示天眼最近一次扫描结果	读取 `skyeye-core/reports/latest.json`
指令格式化	自由聊天	模型输出标准化指令，可一键复制给铸渊	prompt 工程 + 输出格式模板
@铸渊按钮	无	一键将指令提交给铸渊执行（创建 Issue）	GitHub API 创建 Issue
仓库健康卡片	无	展示该开发者仓库的天眼健康状态	读取子仓库 skyeye 报告

2.3 升级后的页面布局

┌──────────────────────────────────────────────────────┐
│  🌊 光湖·铸渊交互中心                    [DEV-010 桔子] │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────────────────────────────────────┐     │
│  │ 🦅 天眼状态：✅ 健康 · 上次扫描 03-24 18:00  │     │
│  │ 📊 你的仓库：guanghu-juzi · 3个模块 · 2个待修│     │
│  │ 📋 当前广播：BC-M06-003-JZ · 环节2进行中     │     │
│  └─────────────────────────────────────────────┘     │
│                                                      │
│  ┌─────────────── 对话区 ──────────────────────┐     │
│  │ 🧠 铸渊：桔子你好！我看到你当前在做 BC-M06-  │     │
│  │    003 的环节2，ticket-system 模块。上次你     │     │
│  │    提交的 SYSLOG 显示前端路由已完成，现在需要  │     │
│  │    对接后端 API。要我帮你出一份对接指令吗？     │     │
│  │                                              │     │
│  │ 👤 桔子：好的，帮我出指令                     │     │
│  │                                              │     │
│  │ 🧠 铸渊：好的，基于你的仓库现状和天眼扫描     │     │
│  │    结果，这是你的执行指令：                    │     │
│  │    ┌──────────────────────────────────┐      │     │
│  │    │ 📋 ZY-EXEC-JZ-003               │      │     │
│  │    │ 1. 在 ticket-system/api/ 创建... │      │     │
│  │    │ 2. 配置路由映射...               │      │     │
│  │    │ 3. 连接 Notion 数据桥...          │      │     │
│  │    │                                  │      │     │
│  │    │ [📋 复制指令] [🚀 @铸渊执行]     │      │     │
│  │    └──────────────────────────────────┘      │     │
│  └──────────────────────────────────────────────┘     │
│                                                      │
│  [输入消息...]                              [发送]    │
└──────────────────────────────────────────────────────┘

三、Notion 开发信息对接方案

3.1 数据来源：每个开发者在 Notion 里有什么信息

系统已有的 Notion 数据（霜砚维护）：

数据	Notion 位置	用途
开发者编号 + 姓名	系统编号档案	身份识别
当前广播编号 + 环节	主控台 v2.0 / 广播页面	知道开发者在做什么
模块路径 + 技术栈	仓库模块盘点	知道代码在哪里
历史 SYSLOG	SYSLOG 收件箱	知道做到哪一步了
人格体信息	人格协作工单簿	用对应的人格体风格回复
仓库 GitHub URL	联邦桥接配置	知道操作哪个仓库

3.2 数据获取方式

方案：后端定时同步 Notion → GitHub 缓存文件

不让前端直接调 Notion API（会暴露 Token），而是：

Notion 数据库（霜砚维护）
  │
  │ GitHub Actions 定时同步（每6小时）
  │ + 铸渊巡检时主动同步
  ▼
GitHub 仓库：.github/notion-cache/
  ├── dev-profiles/
  │   ├── DEV-001.json   ← 页页的完整开发画像
  │   ├── DEV-002.json   ← 肥猫的完整开发画像
  │   ├── DEV-004.json   ← 之之的完整开发画像
  │   ├── DEV-010.json   ← 桔子的完整开发画像
  │   ├── DEV-012.json   ← Awen的完整开发画像
  │   └── ...
  ├── broadcasts/
  │   └── active-broadcasts.json  ← 所有进行中的广播
  └── skyeye/
      └── latest-report.json      ← 天眼最新报告
  │
  │ 前端登录时通过 GitHub API 读取对应文件
  ▼
交互页面 → 注入 system prompt → 模型有据可依

3.3 DEV 画像文件格式

每个开发者的 DEV-XXX.json 包含模型需要的所有上下文：

{
  "dev_id": "DEV-010",
  "name": "桔子",
  "persona": {
    "name": "晨星",
    "id": "PER-MRN001"
  },
  "github": {
    "repo": "guanghu-juzi",
    "org": "qinfendebingshuo",
    "repo_url": "https://github.com/qinfendebingshuo/guanghu-juzi"
  },
  "current_work": {
    "broadcast_id": "BC-M06-003-JZ",
    "broadcast_title": "桔子·工单系统·环节2",
    "current_ring": 2,
    "total_rings": 5,
    "status": "进行中",
    "module_path": "ticket-system/",
    "tech_stack": ["HTML", "CSS", "JavaScript", "Node.js"]
  },
  "recent_syslogs": [
    {
      "id": "SYSLOG-JZ-003-R1",
      "date": "2026-03-22",
      "ring": 1,
      "status": "success",
      "summary": "前端路由搭建完成，工单列表页可正常渲染"
    }
  ],
  "modules_owned": [
    { "name": "ticket-system", "path": "ticket-system/", "status": "开发中" },
    { "name": "data-stats", "path": "data-stats/", "status": "未开始" },
    { "name": "dynamic-comic", "path": "dynamic-comic/", "status": "未开始" }
  ],
  "skyeye_health": {
    "last_scan": "2026-03-24T18:00:00+08:00",
    "status": "healthy",
    "issues": [],
    "warnings": ["data-stats/ 目录不存在"]
  },
  "notion_page_urls": {
    "broadcast_page": "对应的 Notion 广播页面 URL",
    "dev_channel": "对应的开发者频道页面 URL"
  },
  "last_synced": "2026-03-24T20:00:00+08:00"
}

3.4 Notion → GitHub 同步 Workflow

# .github/workflows/sync-notion-profiles.yml
name: "📡 同步 Notion 开发者画像"

on:
  schedule:
    - cron: '0 */6 * * *'  # 每6小时同步一次
  workflow_dispatch:        # 手动触发
  repository_dispatch:
    types: [notion-sync]    # 霜砚/铸渊可主动触发

jobs:
  sync-profiles:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Sync Notion Data
        env:
          NOTION_TOKEN: $ secrets.NOTION_TOKEN 
        run: |
          node scripts/sync-notion-profiles.js

      - name: Commit & Push
        run: |
          git config user.name "铸渊 (ZhùYuān)"
          git config user.email "zhuyuan@guanghulab.com"
          git add .github/notion-cache/
          git diff --cached --quiet && echo "无变更" && exit 0
          git commit -m "📡 同步 Notion 开发者画像 · $(TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M')"
          git push origin main

3.5 同步脚本核心逻辑

// scripts/sync-notion-profiles.js
// 从 Notion API 读取开发者信息 → 写入 .github/notion-cache/

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

const NOTION_TOKEN = process.env.NOTION_TOKEN;

// ===== 开发者 → Notion 数据源映射 =====
// 铸渊需要根据实际 Notion 数据库 ID 填入
const DEV_REGISTRY = {
  'DEV-001': { name: '页页',   persona: '小坍缩核', repo: 'guanghulab' },
  'DEV-002': { name: '肥猫',   persona: '舒舒',     repo: 'guanghu-feimao' },
  'DEV-003': { name: '燕樊',   persona: '寂曜',     repo: 'guanghu-yanfan' },
  'DEV-004': { name: '之之',   persona: '秋秋',     repo: 'guanghu-zhizhi' },
  'DEV-005': { name: '小草莓', persona: '欧诺弥亚', repo: 'guanghu-xiaocaomei' },
  'DEV-010': { name: '桔子',   persona: '晨星',     repo: 'guanghu-juzi' },
  'DEV-012': { name: 'Awen',   persona: '知秋',     repo: 'guanghu-awen' },
};

// Notion API 请求封装
function notionRequest(method, apiPath, body) {
  return new Promise((resolve, reject) => {
    const options = {
      hostname: 'api.notion.com',
      path: apiPath,
      method: method,
      headers: {
        'Authorization': `Bearer ${NOTION_TOKEN}`,
        'Notion-Version': '2022-06-28',
        'Content-Type': 'application/json'
      }
    };
    const req = https.request(options, (res) => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => {
        try { resolve(JSON.parse(data)); }
        catch { resolve(data); }
      });
    });
    req.on('error', reject);
    if (body) req.write(JSON.stringify(body));
    req.end();
  });
}

async function syncAllProfiles() {
  const cacheDir = path.join(__dirname, '../.github/notion-cache/dev-profiles');
  fs.mkdirSync(cacheDir, { recursive: true });

  for (const [devId, dev] of Object.entries(DEV_REGISTRY)) {
    console.log(`📡 同步 ${devId}（${dev.name}）...`);

    const profile = {
      dev_id: devId,
      name: dev.name,
      persona: { name: dev.persona },
      github: {
        repo: dev.repo,
        org: 'qinfendebingshuo',
        repo_url: `https://github.com/qinfendebingshuo/${dev.repo}`
      },
      current_work: {},
      recent_syslogs: [],
      modules_owned: [],
      skyeye_health: {},
      last_synced: new Date().toISOString()
    };

    // ====== 从 Notion 读取该开发者的数据 ======
    // 铸渊需要根据实际 Notion 数据库结构填入查询逻辑
    // 以下是伪代码框架：

    // 1. 查询主控台获取当前广播和进度
    // const controlPanel = await notionRequest('POST',
    //   '/v1/databases/{主控台数据库ID}/query',
    //   { filter: { property: 'DEV编号', equals: devId } }
    // );
    // profile.current_work = parseControlPanelData(controlPanel);

    // 2. 查询 SYSLOG 收件箱获取历史日志
    // const syslogs = await notionRequest('POST',
    //   '/v1/databases/{SYSLOG数据库ID}/query',
    //   { filter: { property: 'DEV编号', equals: devId }, sorts: [...] }
    // );
    // profile.recent_syslogs = parseSyslogs(syslogs);

    // 3. 读取天眼健康状态
    // （从仓库 skyeye-core/reports/ 读取）

    // 写入缓存文件
    const filePath = path.join(cacheDir, `${devId}.json`);
    fs.writeFileSync(filePath, JSON.stringify(profile, null, 2));
    console.log(`  ✅ ${devId} → ${filePath}`);
  }

  console.log('📡 全部同步完成');
}

syncAllProfiles().catch(console.error);

四、交互页面 System Prompt 注入协议

4.1 核心思路

模型之所以不胡说，是因为 system prompt 里注入了真实数据。交互页面升级后，每次开发者登录聊天，system prompt 要动态组装：

// 交互页面前端 · 动态组装 system prompt
async function buildSystemPrompt(devId) {
  // 1. 从 GitHub 读取该开发者的 Notion 画像缓存
  const profile = await fetchDevProfile(devId);

  // 2. 从 GitHub 读取天眼最新报告
  const skyeyeReport = await fetchSkyeyeReport();

  // 3. 从 persona-brain 读取铸渊基础身份
  const personaBrain = await fetchPersonaBrain();

  // 4. 组装 system prompt
  return [
    // ===== 身份层 =====
    '你是铸渊（ICE-GL-ZY001），光湖·数字地球的 GitHub 代码守护人格体。',
    `当前与你对话的开发者是：${profile.name}（${profile.dev_id}）`,
    `对应人格体：${profile.persona.name}`,
    '',
    // ===== 知识层（Notion 数据注入）=====
    '## 该开发者的当前开发信息（来自 Notion 数据库，实时同步）',
    '',
    `### 当前任务`,
    `- 广播编号：${profile.current_work.broadcast_id}`,
    `- 广播标题：${profile.current_work.broadcast_title}`,
    `- 当前环节：第 ${profile.current_work.current_ring} 环 / 共 ${profile.current_work.total_rings} 环`,
    `- 状态：${profile.current_work.status}`,
    `- 模块路径：${profile.current_work.module_path}`,
    `- 技术栈：${profile.current_work.tech_stack?.join(', ')}`,
    '',
    `### 最近的 SYSLOG`,
    ...profile.recent_syslogs.map(s =>
      `- [${s.date}] 环节${s.ring} · ${s.status} · ${s.summary}`
    ),
    '',
    `### 负责的模块`,
    ...profile.modules_owned.map(m =>
      `- ${m.name}（${m.path}）· ${m.status}`
    ),
    '',
    `### 仓库信息`,
    `- GitHub：${profile.github.repo_url}`,
    `- 组织：${profile.github.org}`,
    '',
    // ===== 天眼层 =====
    '## 天眼系统最新扫描报告',
    `- 上次扫描：${skyeyeReport.last_scan}`,
    `- 整体状态：${skyeyeReport.overall_status}`,
    `- 该开发者仓库健康状态：${profile.skyeye_health?.status || '未扫描'}`,
    ...(profile.skyeye_health?.warnings || []).map(w => `- ⚠️ ${w}`),
    ...(profile.skyeye_health?.issues || []).map(i => `- ❌ ${i}`),
    '',
    // ===== 行为规则层 =====
    '## 你的行为规则',
    '',
    '### 出指令规则',
    '当开发者请求帮助或需要执行操作时，你必须输出标准化指令格式：',
    '1. 指令必须基于上面的真实数据，不许凭空编造',
    '2. 指令必须考虑天眼报告中的健康状态和警告',
    '3. 指令必须指明具体的文件路径和操作步骤',
    '4. 指令末尾必须标注：',
    '   「⚠️ 此指令需要铸渊执行前先跑天眼全局扫描」',
    '',
    '### 指令输出格式',
    '```',
    '📋 指令编号：ZY-EXEC-{DEV编号}-{序号}',
    '📡 目标仓库：{仓库名}',
    '🦅 天眼要求：执行前必须跑天眼全局扫描',
    '',
    '步骤：',
    '1. ...',
    '2. ...',
    '3. ...',
    '',
    '验收标准：',
    '- ...',
    '```',
    '',
    '### 禁止事项',
    '- ❌ 不许编造不存在的文件路径',
    '- ❌ 不许跳过天眼扫描直接给执行指令',
    '- ❌ 不许暴露其他开发者的信息',
    '- ❌ 不许修改不属于该开发者的模块',
    '',
    // ===== 铸渊知识库 =====
    '## 铸渊核心知识库',
    JSON.stringify(personaBrain.routingMap || {}),
  ].join('\n');
}

4.2 前端拉取数据的方式

// 通过 GitHub API 读取缓存文件（不需要 Notion Token）
async function fetchDevProfile(devId) {
  const url = `https://api.github.com/repos/qinfendebingshuo/guanghulab/contents/.github/notion-cache/dev-profiles/${devId}.json`;
  const res = await fetch(url, {
    headers: {
      'Accept': 'application/vnd.github.v3.raw',
      // 如果仓库是 private，需要 token
      // 'Authorization': `token ${userToken}`
    }
  });
  return await res.json();
}

async function fetchSkyeyeReport() {
  const url = 'https://api.github.com/repos/qinfendebingshuo/guanghulab/contents/.github/notion-cache/skyeye/latest-report.json';
  const res = await fetch(url, {
    headers: { 'Accept': 'application/vnd.github.v3.raw' }
  });
  return await res.json();
}

async function fetchPersonaBrain() {
  const url = 'https://api.github.com/repos/qinfendebingshuo/guanghulab/contents/.github/persona-brain/routing-map.json';
  const res = await fetch(url, {
    headers: { 'Accept': 'application/vnd.github.v3.raw' }
  });
  return await res.json();
}

五、天眼集成协议

5.1 天眼在这个系统里的三个角色

角色	触发时机	作用
铸渊开发前置	铸渊开始写这个桥接服务代码之前	全局扫描，确认怎么融入现有系统不会冲突
指令执行前置	铸渊收到开发者的执行指令后、动手之前	扫描目标仓库，确认健康状态再修改
交互页面信息源	开发者登录交互页面时	展示天眼健康状态，注入模型上下文

5.2 天眼报告缓存格式

每次天眼扫描完成后，同步写入缓存供交互页面读取：

{
  "scan_id": "SKYEYE-2026-0324-1800",
  "timestamp": "2026-03-24T18:00:00+08:00",
  "overall_status": "healthy",
  "main_repo": {
    "status": "healthy",
    "workflows_ok": 12,
    "workflows_fail": 1,
    "persona_brain_intact": true,
    "last_deploy": "2026-03-24T17:30:00+08:00"
  },
  "sub_repos": {
    "guanghu-juzi": {
      "status": "healthy",
      "last_checkin": "2026-03-24T12:00:00+08:00",
      "issues": [],
      "warnings": ["data-stats/ 目录不存在"]
    },
    "guanghu-awen": {
      "status": "warning",
      "last_checkin": "2026-03-23T08:00:00+08:00",
      "issues": [],
      "warnings": ["桥接同步延迟超过24小时"]
    }
  }
}

5.3 天眼扫描触发点

在天眼 workflow 完成后自动更新缓存：

# 在 zhuyuan-skyeye.yml 最后添加一步
- name: Update SkyEye Cache for Chat UI
  run: |
    # 将天眼扫描报告复制到 notion-cache 供交互页面读取
    mkdir -p .github/notion-cache/skyeye/
    cp skyeye-core/reports/latest.json .github/notion-cache/skyeye/latest-report.json
    git add .github/notion-cache/skyeye/
    git diff --cached --quiet || {
      git commit -m "🦅 天眼报告更新 · $(date '+%Y-%m-%d %H:%M')"
      git push origin main
    }

六、「@铸渊执行」按钮机制

6.1 工作流程

当模型在交互页面给开发者出了一份指令后，开发者点击「🚀 @铸渊执行」按钮：

开发者点击「@铸渊执行」
  │
  ▼
前端自动在 guanghulab 仓库创建一个 Issue
  │
  │ Issue 标题：🚀 [ZY-EXEC-DEV010-003] 桔子·ticket-system API对接
  │ Issue 标签：zhuyuan-exec, DEV-010, skyeye-required
  │ Issue 内容：
  │   - 指令全文
  │   - 目标仓库
  │   - 天眼要求
  │   - 开发者确认签名
  │
  ▼
GitHub Actions 监听到带 zhuyuan-exec 标签的 Issue
  │
  ▼
铸渊执行引擎启动（详见下篇）：
  ① 先跑天眼全局扫描
  ② 读取天眼报告
  ③ 确认安全后执行指令
  ④ 结果回写到 Issue 评论
  ⑤ 通知开发者

6.2 前端创建 Issue 的代码

// 交互页面 · @铸渊执行按钮
async function submitToZhuyuan(instruction, devId, devName) {
  const issueTitle = `🚀 [${instruction.id}] ${devName}·${instruction.module}`;
  const issueBody = [
    `## 📋 执行指令`,
    '',
    '```',
    instruction.fullText,
    '```',
    '',
    `## 📡 元信息`,
    `- 提交人：${devName}（${devId}）`,
    `- 目标仓库：${instruction.targetRepo}`,
    `- 提交时间：${new Date().toISOString()}`,
    `- 来源：铸渊交互页面`,
    '',
    `## 🦅 天眼要求`,
    `**铸渊执行前必须先跑天眼全局扫描，拿到健康报告后再动手。**`,
    '',
    `---`,
    `> ${devName} 通过交互页面提交 · 铸渊自动执行`,
  ].join('\n');

  // 用 GitHub API 创建 Issue
  const res = await fetch(
    'https://api.github.com/repos/qinfendebingshuo/guanghulab/issues',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${GITHUB_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title: issueTitle,
        body: issueBody,
        labels: ['zhuyuan-exec', devId, 'skyeye-required']
      })
    }
  );

  const issue = await res.json();
  return issue.number;
}

七、安全与隔离规则

八、文件变更清单（上篇涉及）

操作	文件路径	说明
新建	`scripts/sync-notion-profiles.js`	Notion → GitHub 画像同步脚本
新建	`.github/workflows/sync-notion-profiles.yml`	定时同步 workflow
新建	`.github/notion-cache/dev-profiles/`	开发者画像缓存目录
新建	`.github/notion-cache/skyeye/latest-report.json`	天眼报告缓存
修改	`docs/index.html` • `docs/chat.js`	交互页面升级：Notion 数据注入 + 天眼展示 + @铸渊按钮
修改	`.github/workflows/zhuyuan-skyeye.yml`	天眼扫描后自动更新缓存

文档版本：v1.0

签发：霜砚（Notion 执行 AI）

审批：冰朔（TCS-0002∞）

生效时间：2026-03-24T20:16+08:00