guanghulab/docs/neural-bridge-protocol-v3.md

🌉 双端神经系统 · 桥接协议 v3.0

版权：国作登字-2026-A-00037559 · TCS-0002∞ 冰朔 创建：ZY-NEURAL-UPGRADE-2026-0325-R2-003 版本：v3.0.0

1. 协议概述

桥接协议 v3.0 是 Notion 和 GitHub 之间的标准通信语言。所有跨端通信必须遵循此协议。

2. 通信类型

类型	方向	说明	格式
Type A · 上行日报	GitHub → Notion	每日 21:00 CST 汇总	daily-digest.json
Type B · 下行指令	Notion → GitHub	按需下发	CMD-{date}-{seq}.json
Type C · 执行回执	GitHub → Notion	每条指令执行后	CMD-{id}-receipt.json
Type D · 工单	天眼内部	分析后按需	WO-{id}.json
Type E · 紧急通知	双向	P0 事件时	ALERT-{id}.json

3. 下行指令格式（Notion → GitHub）

文件路径：data/deploy-queue/pending/CMD-{YYYYMMDD}-{SEQ}.json

{
  "_protocol": "neural-bridge-v3.0",
  "_type": "downstream_command",
  "command_id": "CMD-20260325-001",
  "parent_work_order": "WO-xxxx",
  "source": {
    "agent_id": "AG-TY-01",
    "agent_name": "天眼 Notion 大脑",
    "issued_at": "ISO-8601",
    "issued_reason": "说明"
  },
  "target": {
    "workflow_id": "workflow-id",
    "workflow_file": ".github/workflows/xxx.yml",
    "brain": "AG-XX-01"
  },
  "instruction": {
    "type": "trigger_workflow | run_script | modify_config",
    "params": {}
  },
  "constraints": {
    "priority": "P0 | P1 | P2",
    "timeout_hours": 24,
    "max_retries": 2,
    "requires_human_approval": false,
    "execution_window": { "start": "06:00 CST", "end": "23:00 CST" }
  },
  "expected_outcome": {
    "description": "预期结果",
    "verification": { "type": "check_workflow_status", "expected_conclusion": "success" }
  },
  "security": {
    "sfp": "⌜SFP::...⌝",
    "signature_chain": ["agent_id", "铸渊桥接层"]
  }
}

4. 执行回执格式（GitHub → Notion）

文件路径：data/deploy-queue/completed/CMD-{id}-receipt.json

{
  "_protocol": "neural-bridge-v3.0",
  "_type": "execution_receipt",
  "receipt_id": "RCT-{date}-{seq}",
  "command_id": "CMD-对应指令ID",
  "executor": {
    "id": "ICE-GL-ZY001",
    "name": "铸渊",
    "started_at": "ISO-8601",
    "completed_at": "ISO-8601",
    "duration_seconds": 420
  },
  "result": {
    "status": "success | failure | partial",
    "summary": "执行摘要"
  },
  "security": { "sfp": "⌜SFP::AG-ZY::...⌝" }
}

5. 紧急通知格式

{
  "_protocol": "neural-bridge-v3.0",
  "_type": "emergency_alert",
  "alert_id": "ALERT-{date}-{seq}",
  "severity": "P0",
  "alert": { "title": "标题", "description": "描述", "impact": "影响" },
  "recommended_action": { "immediate": "立即动作", "requires_human": true },
  "notify_targets": [{ "type": "notion_agent", "id": "AG-TY-01" }]
}

6. 安全校验流程

所有跨端通信必须携带 SFP 指纹。铸渊处理下行指令时执行：

1. SFP 指纹校验 — 格式正确 + 签发者在 neural-map.json 中 + 时间戳 < 48h
2. 权限校验 — source.agent_id 有权管辖 target.workflow_id（查 neural-map.json）
3. 约束校验 — 当前时间在 execution_window 内 + 人工审批检查
4. 全部通过 → 执行

7. 超时 / 重试 / 降级策略

场景	超时	重试	降级
下行指令执行	按 timeout_hours	max_retries 次	移到 failed/ + 通知
上行日报推送	5 分钟	3 次	写入 .github/notion-cache/
紧急通知送达	2 分钟	5 次	缓存 + 下次巡检补送
工单下发	12 小时	2 次	标记 stuck + 通知霜砚
回执推送	5 分钟	3 次	缓存 + 下次同步补送

降级铁律：任何跨端通信失败都不能阻断本端的正常运行。桥断了，两端各自活着。桥修好了，自动同步。

8. 工单生命周期（7 状态机）

CREATED → ASSIGNED → COMMAND_ISSUED → EXECUTING → RECEIPT_RECEIVED → VERIFIED → CLOSED
                                                                    ↘ FAILED → ESCALATED

9. 文件目录

路径	说明
skyeye/neural-map.json	双端 Agent 映射表
skyeye/neural-analysis-rules.json	日报分析规则
data/deploy-queue/pending/	待执行的下行指令
data/deploy-queue/executing/	执行中的指令
data/deploy-queue/completed/	已完成（含回执）
data/deploy-queue/failed/	执行失败
data/neural-reports/daily-digest/	每日汇总日报
data/neural-reports/work-orders/	天眼工单
scripts/neural/generate-daily-digest.js	日报生成器
scripts/neural/analyze-digest.js	日报分析引擎
scripts/neural/sync-digest-to-notion.js	日报推送 Notion
scripts/neural/convert-workorder-to-command.js	工单→指令转化器
scripts/neural/track-work-orders.js	工单追踪器