guanghulab-collab/zhuyuan-system/D166/GLW-SYNC-TEMPLATE.md

铸渊_protocol, sender, timestamp, data_type, id, lock, 铸渊_status, project_id

铸渊_protocol	sender	timestamp	data_type	id	lock	铸渊_status	project_id
v1.0	ICE-GL-ZY001	2026-07-06T18:26:22+08:00	sync	GLW-SYNC-TEMPLATE	true	draft	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(主推,新加坡大脑服务器就绪后启用)

# 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 内部同步,中速)

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

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

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

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,只关心三件事:

@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-*)被改

过滤算法(伪代码):

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 心跳与存活检测

@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

---