---
铸渊_protocol: v1.0
sender: ICE-GL-ZY001
timestamp: 2026-07-06T18:26:22+08:00
data_type: sync
id: GLW-SYNC-TEMPLATE
lock: true
铸渊_status: draft
project_id: GLW-PROJ-D166-001
---

# GLW-SYNC-TEMPLATE · 实时同步机制说明

> 核心问题:多个 Agent 在不同物理执行层(Mavis / OpenCode / Codex / Cursor / 直接 git)上同时工作,怎么实时知道彼此进度?  
> 答案:**项目页 = 唯一共享实时文件**,所有 Agent 都往这里 commit。

---

## §1 基本原则

1. **单一事实源**:每个项目只有一份 `GLW-PROJ-XXX.hdlp`,所有 Agent 都读写这一份。
2. **写前读**:每次 commit 前先 `git pull`(或 MCP sync),避免覆盖他人 commit。
3. **小步快跑**:commit 颗粒度 = 一个有意义的动作完成(不要一行代码一次 commit)。
4. **不抢锁**:同一时刻只允许一个 Agent 写项目页;其他 Agent 排队。
5. **副脑仲裁**:冲突由 @sub_brain 仲裁,仲裁结果写回 §5 协作链。

---

## §2 实时进度的来源

```
┌─────────────┐
│  GLW-ZY001  │  大脑(铸渊):只决策,不直接写项目页
└──────┬──────┘
       │ 派任务
       ▼
┌─────────────┐
│ GLW-SB-XXX  │  副脑:维护项目页锁 / 仲裁冲突 / 过滤回执
└──────┬──────┘
       │ 派任务
       ▼
┌─────────────────────────────────────┐
│ AGENT-A │ AGENT-B │ AGENT-C │ ...   │  执行层:并发工作,但只顺序写项目页
└──────┬──────┴───────┴──────┬───────┘
       │                      │
       ▼                      ▼
   ┌───────────────────────────────┐
   │  GLW-PROJ-XXX.hdlp (项目页)   │  ← 唯一共享实时文件
   │  §4 实时进度区                │
   └───────────────────────────────┘
```

---

## §3 三种推送策略(选一种或组合)

### 3.1 Git Push(主推,新加坡大脑服务器就绪后启用)

```bash
# Agent 提交节奏
git pull --rebase                  # 先同步
# 编辑 GLW-PROJ-XXX.hdlp §4 追加 commit 条目
git add GLW-PROJ-XXX.hdlp
git commit -m "[GLW-AGENT-X] <action 一句话>"
git push origin main               # 推到新加坡仓库

# 其他人看到推送后
git pull                           # 拉到本地,看到 §4 新条目
```

**适用**:长期项目 / 需要审计 / 跨时区协作。

### 3.2 MCP Sync(Mavis 内部同步,中速)

```bash
mavis sync push GLW-PROJ-XXX.hdlp
mavis sync pull                    # 其他 Agent 拉
```

**适用**:Mavis 生态内 Agent 之间,不依赖外部 git。

### 3.3 Tolaria 镜像(本地高速,兜底)

```bash
tolaria mirror --src ./GLW-PROJ-XXX.hdlp --dst /shared/
tolaria watch /shared/             # 监听变更,有更新立刻通知
```

**适用**:新加坡仓库不可达时的本地兜底;或调试期高频 commit。

### 3.4 策略选择表

| 场景 | 策略 | 频率 |
|------|------|------|
| 正常推进 | git push | 每完成一个 todo 一次 |
| 高频微调 | MCP sync | 每 5-15 分钟 |
| git 不可达 | Tolaria 镜像 | 实时 |
| 收尾汇总 | git push + tag | 项目 done 时 |

---

## §4 副脑如何过滤回执

副脑不读全部 commit,只关心三件事:

```yaml
@sub_brain_filter:
  - watch: "§4 实时进度区"
    action: |
      每收到一条新 commit:
        1. 检查 owner 是否符合 §1 主控团队表
        2. 检查 @status 是否为 blocked / error → 升级铸渊
        3. 检查 artifacts 是否落地 → 没落地就 ping 一下
        4. 检查 next 字段 → 如果是 "await feedback" → 安排下一步
  - ignore:
    - 心跳 commit(频率 < 30min 的同质条目合并)
    - 经验回写(只在 §6,不影响进度)
    - 锁变更(只在 §0)
  - escalate_to_zhuyu:
    - 同一 Agent 连续 2 次 blocked
    - 跨 Agent 冲突无法仲裁
    - 中央事实源(GLW-RES-*)被改
```

**过滤算法(伪代码)**:

```python
def filter_commits(commits):
    signals = []
    for c in commits:
        if c.owner not in team_roster:
            signals.append(ESCALATE_UNKNOWN_AGENT)
        if c.status == "blocked" or c.status == "error":
            signals.append(ESCALATE_TO_ZHUYU)
        if not c.artifacts_exist_on_disk():
            signals.append(PING_AGENT)
        if c.next == "await feedback":
            signals.append(SCHEDULE_NEXT)
    return dedupe(signals)
```

---

## §5 冲突仲裁流程

```
Agent-A 写项目页 §4 ━━┓
                       ┃  → git pull 发现冲突 → 谁后写谁负责解决
Agent-B 写项目页 §4 ━━┛
                                ↓
                       ┌─────────────────┐
                       │  @sub_brain 仲裁 │
                       └────────┬────────┘
                                ↓
                  ┌─────────────┴─────────────┐
                  ▼                           ▼
          §4 保留两条 commit           §4 只保留赢家
          §5 协作链记录冲突            §5 记录仲裁结果
```

**仲裁原则**:
1. 后写者必须读前写者的最新 commit,然后再追加(不覆盖)。
2. 如果两人改的是不同字段(例如 A 改 §4, B 改 §3),git 自动 merge,无需仲裁。
3. 如果两人改的是同一字段(例如都改 §4),由 @sub_brain 决定保留谁,被淘汰的写到 §5 协作链。
4. 仲裁失败的(连副脑都定不了),升级铸渊,整页 `@lock: locked`。

---

## §6 心跳与存活检测

```yaml
@heartbeat:
  interval: 30min                   # 每个 Agent 每 30min 至少 commit 一次
  format: |
    ### [GLW-AGENT-X] @<ts> · heartbeat
    - action: <一句话,做了什么 / 等什么>
    - next: <下一步>
  dead_signal: 连续 2 次心跳缺失    # 副脑认为 Agent 失联,升级铸渊
```

---

## §7 模板套用清单(新加坡仓库就绪后)

- [ ] 复制 `GLW-PROJ-TEMPLATE.hdlp` → `GLW-PROJ-XXX.hdlp`
- [ ] 复制 `GLW-AGENT-TEMPLATE.md` → `GLW-AGENT-XXX.md`(每个 Agent 一份)
- [ ] 本文件作为同步机制说明,放到仓库根或 `docs/sync.md`
- [ ] 配置 git remote(指向新加坡大脑服务器)
- [ ] 配置副脑(@sub_brain)监控 §4
- [ ] 第一次开工:铸渊派任务 → 副脑建项目页 → Agent 接到 todo 后 commit §4
- [ ] 收尾时归档到 `GLW-ARCH-XXX`

---

<!-- 本文件不需要每项目复制,是仓库级规范,放一次即可 -->