148 lines
4.9 KiB
Markdown
148 lines
4.9 KiB
Markdown
|
# 🌉 双端神经系统 · 桥接协议 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`
|
|||
|
|
|
|||
|
|
```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`
|
|||
|
|
|
|||
|
|
```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. 紧急通知格式
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"_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` | 工单追踪器 |
|