{"id":"cd9dd164-a3ca-41d4-aeb6-a17b159174e1","entityType":"agent","slug":"clawhub-stevensongxx-agent-config-sync","name":"Agent Config Sync","canonicalUrl":"https://www.xpersona.co/agent/clawhub-stevensongxx-agent-config-sync","canonicalPath":"/agent/clawhub-stevensongxx-agent-config-sync","generatedAt":"2026-10-12T13:20:52.286Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":null},"description":"Synchronize configuration versions across OpenClaw multi-agent deployments. Tracks changes in a master workspace using sentinel version files and CHANGELOG,...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 976 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17f83drgkhbaj6myp1m3b9eeh86vjzd:agent-config-sync","sourceUrl":"https://clawhub.ai/stevensongxx/agent-config-sync","homepage":"https://clawhub.ai/stevensongxx/skills/agent-config-sync","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/stevensongxx/agent-config-sync","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/stevensongxx/skills/agent-config-sync","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agent Config Sync technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":null},"stars":null,"forks":null,"downloads":976,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.5.1","tractionLabel":"976 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:31:02.057Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:31:02.072Z","lastCrawledAt":"2026-10-11T23:31:02.057Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:31:02.057Z","lastVerifiedAt":null,"highlights":[{"version":"1.5.1","createdAt":"2026-05-16T08:07:21.603Z","changelog":"agent-config-sync v1.5.1 - SECURITY.md updated with guidance and improved formatting; no major policy or scope changes. - Minor documentation cleanup in SKILL.md for clarity. - No changes to logic, features, or behavior in the codebase.","fileCount":19,"zipByteSize":93150},{"version":"1.5.0","createdAt":"2026-05-16T04:19:55.923Z","changelog":"**v1.5.0 is a major release with interactive setup and zero-config onboarding.** - Added interactive setup wizard (`scripts/wizard.sh`) for guided, manual-free installation and configuration. - Introduced `--auto` mode to auto-detect agents and simplify `init_sync.sh` setup (zero prompts). - Enhanced SYNC.md file with quick start instructions and cheat sheet for agents. - Expanded documentation and onboarding guidance for both new and advanced users. - Added evaluation, repair log, and version conflict management design reports for transparency and troubleshooting. - Improved scripts for easier rollback, setup, and sync management.","fileCount":18,"zipByteSize":91294},{"version":"1.3.0","createdAt":"2026-05-16T01:52:35.156Z","changelog":"v1.3.0: ClawScan Warn消除(--confirm安全确认/路径校验//home/admin绑定)/新增SECURITY.md权限模型文档/SKILL.md更新安全引用/init_sync+force_sync双重安全机制","fileCount":12,"zipByteSize":29723},{"version":"1.2.1","createdAt":"2026-05-16T01:43:15.218Z","changelog":"v1.2.1: 修复ClawHub dotfile排除问题(agent-registry.json非dotfile命名+更新所有引用) / 所有功能同v1.2","fileCount":11,"zipByteSize":27555},{"version":"1.2.0","createdAt":"2026-05-16T01:30:39.546Z","changelog":"v1.2: 通用性重构(.agent_registry单一事实源+变量配置表+脚本读注册表) / 新增references/quickstart.md(全英文) / 脚本双语化(--lang en/zh) / init_sync.sh增加--dry-run和--demo模式 / force_sync.sh增加--dry-run和--lang / SKILL.md补全Installation/Configuration/DailyOps/Troubleshooting/Upgrading章节","fileCount":10,"zipByteSize":26987},{"version":"1.1.0","createdAt":"2026-05-16T00:59:30.496Z","changelog":"v1.1: P0修复(pending_sync累积+Journal两步提交+CHANGELOG结构化+SHA256签名) / P1修复(.agent_registry+init_sync防覆盖+force_sync备份校验) / 清除SUSPICIOUS审核标记 / 新增场景示例+故障排查表","fileCount":8,"zipByteSize":13327},{"version":"1.0.0","createdAt":"2026-05-16T00:21:41.996Z","changelog":"首次发布: 多智能体配置版本管理与自动同步机制。支持版本哨兵/CHANGELOG/pending_sync降级/心跳自动检测/多Agent推送拉取","fileCount":7,"zipByteSize":7251}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f83drgkhbaj6myp1m3b9eeh86vjzd:agent-config-sync","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17f83drgkhbaj6myp1m3b9eeh86vjzd:agent-config-sync` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/stevensongxx/agent-config-sync before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T13:20:52.284Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-stevensongxx-agent-config-sync/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":null},"readme":"Skill: Agent Config Sync\n\nOwner: stevensongxx\n\nSummary: Synchronize configuration versions across OpenClaw multi-agent deployments. Tracks changes in a master workspace using sentinel version files and CHANGELOG,...\n\nTags: automation:1.3.0, chinese:1.3.0, config:1.3.0, english:1.3.0, latest:1.5.1, reliable:1.1.0, secure:1.3.0, sync:1.3.0\n\nVersion history:\n\nv1.5.1 | 2026-05-16T08:07:21.603Z | auto\n\nagent-config-sync v1.5.1\n\n- SECURITY.md updated with guidance and improved formatting; no major policy or scope changes.\n- Minor documentation cleanup in SKILL.md for clarity.\n- No changes to logic, features, or behavior in the codebase.\n\nv1.5.0 | 2026-05-16T04:19:55.923Z | auto\n\n**v1.5.0 is a major release with interactive setup and zero-config onboarding.**\n\n- Added interactive setup wizard (`scripts/wizard.sh`) for guided, manual-free installation and configuration.\n- Introduced `--auto` mode to auto-detect agents and simplify `init_sync.sh` setup (zero prompts).\n- Enhanced SYNC.md file with quick start instructions and cheat sheet for agents.\n- Expanded documentation and onboarding guidance for both new and advanced users.\n- Added evaluation, repair log, and version conflict management design reports for transparency and troubleshooting.\n- Improved scripts for easier rollback, setup, and sync management.\n\nv1.3.0 | 2026-05-16T01:52:35.156Z | user\n\nv1.3.0: ClawScan Warn消除(--confirm安全确认/路径校验//home/admin绑定)/新增SECURITY.md权限模型文档/SKILL.md更新安全引用/init_sync+force_sync双重安全机制\n\nv1.2.1 | 2026-05-16T01:43:15.218Z | user\n\nv1.2.1: 修复ClawHub dotfile排除问题(agent-registry.json非dotfile命名+更新所有引用) / 所有功能同v1.2\n\nv1.2.0 | 2026-05-16T01:30:39.546Z | user\n\nv1.2: 通用性重构(.agent_registry单一事实源+变量配置表+脚本读注册表) / 新增references/quickstart.md(全英文) / 脚本双语化(--lang en/zh) / init_sync.sh增加--dry-run和--demo模式 / force_sync.sh增加--dry-run和--lang / SKILL.md补全Installation/Configuration/DailyOps/Troubleshooting/Upgrading章节\n\nv1.1.0 | 2026-05-16T00:59:30.496Z | user\n\nv1.1: P0修复(pending_sync累积+Journal两步提交+CHANGELOG结构化+SHA256签名) / P1修复(.agent_registry+init_sync防覆盖+force_sync备份校验) / 清除SUSPICIOUS审核标记 / 新增场景示例+故障排查表\n\nv1.0.0 | 2026-05-16T00:21:41.996Z | user\n\n首次发布: 多智能体配置版本管理与自动同步机制。支持版本哨兵/CHANGELOG/pending_sync降级/心跳自动检测/多Agent推送拉取\n\nArchive index:\n\nArchive v1.5.1: 19 files, 93150 bytes\n\nFiles: _meta.json (136b), README.md (7044b), references/agent-registry.json (1600b), references/agent-setup.md (1662b), references/pending-sync-template.md (3371b), references/quickstart.md (5364b), references/sync-journal.md (4938b), references/sync-setup.md (23613b), reports/agent-config-sync-eval-v1.1.md (6967b), reports/agent-config-sync-eval-v1.3.md (14685b), reports/repair-log.md (10879b), reports/version-conflict-management-design.md (45852b), scripts/force_sync.sh (9464b), scripts/init_sync.sh (31189b), scripts/revert_sync.sh (25279b), scripts/wizard.sh (40603b), SECURITY.md (7288b), skill-card.md (2577b), SKILL.md (29417b)\n\nFile v1.5.1:SKILL.md\n\n---\nname: agent-config-sync\ndescription: |-\n Synchronize configuration versions across OpenClaw multi-agent deployments.\n Tracks changes in a master workspace using sentinel version files and CHANGELOG,\n then dispatches to downstream agents via sessions_send or file-based pending_sync\n fallback. Each agent independently checks for updates on startup (BOOTSTRAP.md)\n and heartbeat (HEARTBEAT.md). Designed for users running 2+ specialized agents\n who need consistent system/agent/OpenClaw configurations.\n Triggers on: sync, configure, version management, multi-agent coordination.\n---\n\n# Agent Config Sync (v1.5)\n\nKeep configuration consistent across multiple OpenClaw agents using version tracking, CHANGELOG-based change detection, and automatic sync dispatch with journal-backed two-phase commit.\n\n> **⚡ Quick Start (30 seconds to running):**\n> ```bash\n> # Step 1: Install\n> clawhub install agent-config-sync\n>\n> # Step 2: Run setup wizard (interactive, no manual editing needed)\n> cd ~/.openclaw/skills/agent-config-sync\n> bash scripts/wizard.sh\n>\n> # Step 3: Done! 🎉\n> # - Agent registry auto-detected\n> # - Sync infrastructure created\n> # - HEARTBEAT integration added\n> # - All agents ready to receive syncs\n> ```\n> \n> **Non-interactive?** Use `bash scripts/wizard.sh --auto` to auto-detect everything.\n> \n> **Prefer manual?** See [Installation](#installation) below for step-by-step instructions.\n>\n> **New in v1.5**: Interactive setup wizard (`scripts/wizard.sh`), `--auto` mode for init_sync.sh (zero-config auto-detection), enhanced SYNC.md with quick start guide and cheat sheet, simplified onboarding.\n>\n> **New in v1.4**: Full version conflict management — dispatch lock, loop detection, self-upgrade isolation, batch mode, rollback snapshots, TTL-based expiry, offline catch-up, and agent-side version collapse. See [Version Conflict Management](#version-conflict-management-v14) for details.\n>\n> **Security**: This skill writes to agent workspaces across your OpenClaw deployment. Read the full [SECURITY.md](SECURITY.md) for permission scope, path validation, cross-agent isolation, and user consent flow. Key highlights:\n> - All scripts require `--confirm` for write operations (use `--dry-run` to preview first)\n> - Only paths under `~/.openclaw/workspace-*` are allowed (path validation enforced)\n> - Each agent can only read/write its own workspace files\n> - No network access, no external API calls, no credential access\n\n## ⚙️ Customization Variables\n\n**Option A (Recommended): Run the setup wizard**\n```bash\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n```\nThe wizard auto-detects your agents and generates `agent-registry.json` — no manual editing.\n\n**Option B: Manual configuration**\n\nEdit `references/agent-registry.json` — this is the only file you need to change for your deployment:\n\n| Variable | Location | Example | Description |\n|----------|----------|---------|-------------|\n| `workspace_root` | `vars` in registry | `~/.openclaw` | Base path for all agent workspaces |\n| `master_agent` | `vars` in registry | `amaster` | ID of your coordination/master agent |\n| `master_memory` | `vars` in registry | `${workspace_root}/workspace-amaster/memory` | Path to master's memory directory |\n| (each agent) | `agents` in registry | See below | Add/remove/rename agents to match your setup |\n\n**Example** — after customization for user \"Alice\" with agents `alice-dev`, `alice-biz`, `alice-ops`:\n\n```json\n{\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"alice-ops\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"alice-dev\": { \"name\": \"Alice Dev\", \"role\": \"Development\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-dev\" },\n \"alice-biz\": { \"name\": \"Alice Biz\", \"role\": \"Business\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-biz\" },\n \"alice-ops\": { \"name\": \"Alice Ops\", \"role\": \"Coordination\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-ops\" }\n }\n}\n```\n\nScripts resolve `${vars.xxx}` placeholders at runtime — no hardcoded paths.\n\n---\n\n## Overview\n\n### Architecture\n\n```\n┌─ Version Tracking ──────────────────────┐\n│ .current_system_version (monotonic) │\n│ .last_sync_version (last synced) │\n│ CHANGELOG.md (structured) │\n│ .sync_journal.jsonl (atomicity) │\n└──────────────────────────────────────────┘\n │ version mismatch detected by HEARTBEAT\n ▼\n┌─ Sync Journal (two-phase commit) ────────┐\n│ PREPARE → journal entry written │\n│ DISPATCH → sessions_send / pending_sync │\n│ COMMIT → mark done or retry later │\n└──────────────────────────────────────────┘\n │ each agent processes independently\n ▼\n┌─ Agent Side ────────────────────────────┐\n│ BOOTSTRAP.md → ls pending_sync_*.md │\n│ HEARTBEAT.md → check + verify SHA256 │\n│ SYNC.md → manual sync instructions │\n└──────────────────────────────────────────┘\n```\n\n### What it syncs\n\n| Type | Examples |\n|:----:|----------|\n| 🖥️ System code | Quant system, price compare, data pipelines |\n| 🤖 Agent config | SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md |\n| ⚙️ OpenClaw config | Models, skills, service addresses, plugins |\n| 🎯 Task config | API keys, cron jobs, data sources, ports |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- OpenClaw with 2+ agents\n- One designated \"master\" coordination agent\n- `clawhub` CLI installed\n\n### Option A: Interactive Wizard (Recommended for New Users)\n\n```bash\nclawhub install agent-config-sync\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n```\n\nThe wizard walks you through:\n1. Environment detection (auto-finds your agents)\n2. Registry configuration (auto-generates from your workspace)\n3. Infrastructure initialization (one click)\n4. HEARTBEAT integration (auto-appended)\n5. Completion report (status summary + next steps)\n\n### Option B: One-Command Auto Setup\n\n```bash\nclawhub install agent-config-sync\nbash ~/.openclaw/skills/agent-config-sync/scripts/init_sync.sh --auto\n```\n\nAuto-detects all agent workspaces, generates registry, and initializes everything — zero prompts.\n\n### Option C: Manual Step-by-Step\n\n#### Step 1: Install the Skill\n\n```bash\nclawhub install agent-config-sync\n```\n\n#### Step 2: Customize Agent Registry\n\nEdit `~/.openclaw/skills/agent-config-sync/references/agent-registry.json`:\n\n1. Change `vars.master_agent` to your coordination agent's ID\n2. Replace the `agents` entries with your own agents\n3. Adjust `vars.workspace_root` if your OpenClaw workspace is not `~/.openclaw`\n\nSee the [Customization Variables](#️-customization-variables) table above, or the English quickstart at `references/quickstart.md`.\n\n#### Step 3: Initialize Sync Infrastructure\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview what will be created (safe, no changes required)\nbash scripts/init_sync.sh --dry-run\n\n# Run the real setup (--confirm required for write operations)\nbash scripts/init_sync.sh --confirm\n```\n\n> ⚠️ **Safety**: `--confirm` is **required** for any write operation. Without it, the script exits with a prompt explaining how to preview with `--dry-run` first. `--dry-run` mode does not need `--confirm`.\n\nThis creates:\n- Version sentinel files (`.current_system_version`, `.last_sync_version`) in master's `memory/`\n- `CHANGELOG.md` with structured format\n- `.sync_journal.jsonl` for sync atomicity\n- `SYNC.md`, bootstrapped `BOOTSTRAP.md`, and `HEARTBEAT.md` sync checks in each agent workspace\n\n#### Step 4: Add HEARTBEAT Item to Master Agent\n\nCopy the HEARTBEAT item from `references/sync-setup.md` into your master agent's `HEARTBEAT.md`. This is **item 12** — the heartbeat check that detects version mismatches and dispatches syncs.\n\n#### Step 5: Verify Setup\n\n```bash\n# Check version files\ncat ~/.openclaw/workspace-/memory/.current_system_version # should be v1.0\n\n# Check agent sync files\nls ~/.openclaw/workspace-*/SYNC.md\n```\n\n---\n\n## Version Conflict Management (v1.4)\n\n### Conflict Types\n\n| Type | Scenario | Frequency | Impact |\n|:-----|:---------|:---------:|:------:|\n| **Concurrent Change** | Two agents submit version changes simultaneously | High | Medium |\n| **Cross-Session Stale** | Agent restarts and finds outdated `pending_sync` files | Medium | Low |\n| **Offline Catch-Up** | Agent misses one or more sync cycles | Medium | High |\n| **Self-Reference (Self-Upgrade)** | agent-config-sync's own files need updating | Low | High |\n| **Multi-Agent Coordination** | Change requires specific ordering across agents | Medium | Medium |\n| **Rollback** | Need to revert a problematic version change | Low | High |\n\n### Conflict Detection Mechanisms\n\n| Mechanism | Location | What It Detects |\n|:----------|:---------|:----------------|\n| Version Sentinel Comparison | Master HEARTBEAT item 12 | `.current_system_version` ≠ `.last_sync_version` |\n| Dispatch Lock | Master HEARTBEAT item 12 | Concurrent dispatch prevention (< 2min window) |\n| Loop Detection | Master HEARTBEAT item 12 | 3+ consecutive same-version journal records |\n| TTL Expiry Check | Agent BOOTSTRAP/HEARTBEAT | `now > 过期时间` → delete stale pending_sync |\n| Version Folding | Agent side | Multiple `pending_sync_*.md` files → fold by version |\n| `.agent_sync_version` Gap | Agent side | Local version < current system version → offline gap |\n| Self-Protect Blacklist | Master dispatch | CHANGELOG impact range includes sync's own files |\n| Snapshot Verification | Agent rollback | SHA256 checksums on restored files |\n\n### Agent-Side Pending Sync Priority Matrix\n\nWhen an agent discovers multiple `pending_sync_*.md` files, it processes them in this order:\n\n```\nPriority Type Handle\n───────── ──────────────── ──────────────────────────────\n1 (first) Expired files Delete immediately (now > 过期时间)\n2 Superseded files Delete (lower version number, depends_on chain covered)\n3 Isolated syncs Must process before normal syncs (self-upgrade isolation)\n4 Revert syncs Revert to target version from snapshot\n5 (last) Normal syncs Apply in version order, respecting depends_on chain\n```\n\n**Version Collapse Rule**: If multiple `pending_sync_v3.1`, `pending_sync_v3.2`, `pending_sync_v3.3` exist AND v3.3's `**前置**` chain covers all intermediate versions → apply only v3.3 and delete v3.1/v3.2.\n\n### Version Folding Algorithm\n\n```\nAgent discovers pending_sync_*.md files:\n\n1. 删除已过期的文件（生成时间 > TTL，默认 24h）\n2. 删除已被 supersede 的文件（版本号更低，且被更新版本的 depends_on 链覆盖）\n3. 对剩余文件按版本号排序 → 从最早的开始执行\n4. 如果文件头包含 \"前置\" 依赖 → 先检查前置是否已处理\n - 若前置未处理 → 按依赖链逐步升级\n - 若前置已处理 → 可直接应用\n5. 应用变更前创建前置快照（memory/.sync_snapshots/_pre/）\n6. 应用变更后更新 .agent_sync_version\n7. 删除已处理的 pending_sync 文件\n```\n\n---\n\n## Agent-Side Version Collapse (v1.4)\n\n### Overview\n\nWhen an agent discovers multiple `pending_sync_*.md` files (e.g., after being offline or during a period of rapid changes), it uses version collapse to avoid processing every intermediate version. The goal is to safely \"jump\" from the agent's current version to the latest applicable version in a single step.\n\n### Decision Flow\n\n```\nAgent discovers N pending_sync_*.md files (N ≥ 1):\n\n1. PARSE all file headers:\n - Extract: 版本, 前置, 生成时间, 过期时间, 类型\n\n2. CLEANUP expired:\n FOR EACH file:\n IF now > 过期时间:\n DELETE file\n LOG \"Stale sync expired: \"\n\n3. DETECT superseded:\n SORT remaining files by 版本 DESC\n FOR EACH file from latest to earliest:\n Walk depends_on chain from latest version\n IF current version is in chain → all older files are superseded\n DELETE all files whose version < latest_version AND covered by chain\n\n4. CLASSIFY remaining files:\n GROUP by 类型:\n - isolated_sync → process BEFORE normal syncs\n - revert_sync → restore from snapshot\n - pending_sync → normal version upgrade\n\n5. ORDER execution:\n isolated_sync files (ascending version)\n ↓\n revert_sync files (ascending target version)\n ↓\n normal pending_sync files (ascending version, respecting depends_on chain)\n\n6. EXECUTE each file:\n a. CHECK depends_on: IF 前置 > .agent_sync_version → ERROR (chain broken, request Master)\n b. CREATE snapshot: mkdir .sync_snapshots/_pre/ + backup affected files\n c. APPLY changes from CHANGELOG\n d. UPDATE .agent_sync_version = 版本\n e. DELETE processed file\n\n7. VERIFY:\n Check .agent_sync_version matches latest processed version\n Confirm no remaining pending_sync files (or that remaining files have valid depends_on > current)\n```\n\n### Version Comparison\n\n```\nVersion format: v.[.]\n\nis_newer(\"v3.2\", \"v3.1\") → true (MINOR increment)\nis_newer(\"v3.2.1\", \"v3.2\") → true (PATCH increment)\nis_newer(\"v3.1\", \"v3.2\") → false\nis_newer(\"v4.0\", \"v3.9\") → true (MAJOR increment)\nis_same(\"v3.1\", \"v3.1\") → true\n```\n\n### Edge Cases\n\n| Case | Behavior |\n|------|----------|\n| Single pending file | Direct application (no collapse needed) |\n| Chain broken (v3.1, v3.3 but no v3.2 dependency) | Process v3.1 first, then v3.3 |\n| Chain complete (v3.1 depends v3.0; v3.3 depends v3.1) | Jump directly to v3.3 |\n| Mixed types (pending + revert) | Revert takes priority; if revert target > current, normal syncs after |\n| Corrupt file (unparseable header) | Skip, log error, request Master re-dispatch |\n| Same version, 2 files (duplicate) | Keep newest by 生成时间, delete older |\n\n---\n\n## Self-Upgrade Isolation (v1.4)\n\n### Problem\n\nagent-config-sync's own files (SKILL.md, scripts/, SECURITY.md, etc.) may need updating. But if the sync system dispatches changes to itself through normal channels, it can trigger self-referential sync loops.\n\n### Solution: Isolated Sync Flow\n\nWhen a CHANGELOG entry's impact range includes paths in the `self_protect.blacklist`:\n\n1. **Detection**: Master HEARTBEAT item 12 checks if the change affects agent-config-sync itself\n2. **Isolation**: Generates `isolated_sync__.md` in Master's `memory/` directory\n3. **Notification**: Appends a notice to each agent's `BOOTSTRAP.md` (not dispatched via normal flow)\n4. **Agent Action**: On next startup, agent detects the BOOTSTRAP notice and requests the isolated sync\n5. **No sentinel file**: Does not use `pending_sync` file mechanism — avoids normal dispatch loop\n\n### Configuration\n\nConfigured in `agent-registry.json`:\n\n```json\n\"self_protect\": {\n \"enabled\": true,\n \"skip_agents\": [\"agent-config-sync\"],\n \"isolated_sync\": true,\n \"blacklist\": [\"HEARTBEAT.md\", \"BOOTSTRAP.md\", \"SKILL.md\", \"scripts/\", \"SECURITY.md\", \"references/\"],\n \"sync_own_version_file\": \"skills/agent-config-sync/.sync_own_version\",\n \"allow_bootstrap_only\": true\n}\n```\n\n### Self-Protect Blacklist\n\nPaths listed in `blacklist` are quarantined from normal dispatch. Any CHANGELOG entry affecting these paths triggers the isolated sync flow instead.\n\n---\n\n## Batch Mode (v1.4)\n\n### Overview\n\nWhen multiple rapid changes occur within a time window, batch mode merges them into a single cumulative dispatch instead of triggering one sync per version.\n\n### Configuration\n\n```json\n\"batch\": {\n \"mode\": \"auto\",\n \"window_sec\": 300\n}\n```\n\n### Behavior\n\n1. HEARTBEAT detects version mismatch\n2. Instead of immediate dispatch, opens a batch window (default: 5 min)\n3. All version bumps within the window are accumulated\n4. When window closes → merge all changes into one `pending_sync` file\n5. Uses highest version number among batched changes\n6. Combines all CHANGELOG sections\n\n### Merge Rules\n\n- Sort all batched versions → use the highest version\n- Concatenate CHANGELOG entries in version order\n- Generate single SHA256 signature over combined content\n- Single dispatch covers all intermediate changes\n\n---\n\n## Rollback Mechanism (v1.4)\n\n### Overview\n\nWhen a version change causes problems, the system supports controlled rollback to a previous version using pre-sync snapshots.\n\n### Rollback Flow\n\n```\n1. TRIGGER (Master):\n - Set .current_system_version to the rollback target version\n - HEARTBEAT detects: current < last_sync → recognizes as rollback\n - Creates revert_sync__to__.md in each agent workspace\n\n2. APPLY (Agent):\n - Detects revert_sync file on HEARTBEAT/BOOTSTRAP check\n - Restores files from memory/.sync_snapshots/_pre/\n - Verifies SHA256 checksums from snapshot_manifest.json\n - Updates .agent_sync_version to target version\n - Deletes revert_sync file\n\n3. VERIFY (All):\n - .current_system_version == .last_sync_version (stable state)\n - No pending_sync or revert_sync files remain\n```\n\n### Snapshot Directory Structure\n\n```\nmemory/.sync_snapshots/\n├── v3.2_pre/\n│ ├── TOOLS.md.bak\n│ ├── SOUL.md.bak\n│ ├── AGENTS.md.bak\n│ └── snapshot_manifest.json\n└── v3.3_pre/\n ├── config.json.bak\n └── snapshot_manifest.json\n```\n\n### snapshot_manifest.json Format\n\n```json\n{\n \"sync_version\": \"v3.2\",\n \"snapshot_time\": \"2026-05-16T08:30:00Z\",\n \"previous_version\": \"v3.1\",\n \"files\": {\n \"TOOLS.md\": \"sha256:a1b2c3...\",\n \"SOUL.md\": \"sha256:d4e5f6...\"\n }\n}\n```\n\n### Rollback Safety\n\n- **Pre-condition**: Agent must have a snapshot directory matching the target rollback version\n- **SHA256 verification**: All restored files verified against snapshot manifests\n- **No partial rollback**: Atomic restore (all files succeed or none)\n- **Loop prevention**: Rollback records are `type=revert` — not re-triggered by normal dispatch\n- **Manual confirmation**: Requires explicit version bump to trigger\n\n---\n\n## Configuration\n\n### Agent Registry (`references/agent-registry.json`)\n\nThe single source of truth. Fields:\n\n| Field | Description |\n|-------|-------------|\n| `vars.workspace_root` | Root directory for all agent workspaces |\n| `vars.master_agent` | ID of the coordination agent (sends syncs) |\n| `vars.master_memory` | Path to master's memory directory (uses placeholders) |\n| `agents..name` | Display name (English) |\n| `agents..name_zh` | Display name (Chinese) — optional |\n| `agents..role` | Short role description |\n| `agents..workspace` | Path to agent workspace (uses `${vars.workspace_root}`) |\n| `sync.*` | Sync behavior config (sentinel filenames, prefix, limits) |\n\n### CHANGELOG Format\n\nAll version entries must follow the structured format defined in `references/sync-setup.md`:\n\n```markdown\n## vX.Y (YYYY-MM-DD)\n**Change Type**: \n**Affected Agents**: \n**Author**: \n**Priority**: normal | high | critical\n\n### Added / Changed / Deprecated\n- \n```\n\n### Language\n\nScripts support `--lang en` and `--lang zh` (default). Use `--lang en` for English output:\n\n```bash\nbash scripts/init_sync.sh --lang en\nbash scripts/force_sync.sh --lang en ~/memory v1.0 v1.1\n```\n\n---\n\n## Usage Scenarios\n\n### Scenario A: Adding a new model to all agents\n\n**Situation**: You want all agents to switch to a new default model.\n\n1. Update `CHANGELOG.md` in master's memory directory:\n ```markdown\n ## v3.2 (2026-05-16)\n **Change Type**: ⚙️ OpenClaw Config\n **Affected Agents**: all\n **Author**: AMaster\n **Priority**: high\n\n ### Changed\n - Default model switched to deepseek-v4-pro for all agents\n - Fallback model set to deepseek-v3\n ```\n\n2. Bump the version:\n ```bash\n echo \"v3.2\" > memory/.current_system_version\n ```\n\n3. Next HEARTBEAT (every 5 min): version mismatch detected → dispatches to all agents. Agents update their model configs accordingly.\n\n4. Agents delete their `pending_sync_v3.2_.md` after applying.\n\n### Scenario B: Coordinated code deployment\n\n**Situation**: You fix a bug in shared code used by multiple agents.\n\n1. Fix the bug, tell the master agent to record the change.\n\n2. Master updates `CHANGELOG.md` with the version entry, bumps `.current_system_version`.\n\n3. HEARTBEAT dispatches. Online agents receive via `sessions_send`; offline agents get `pending_sync` files.\n\n4. All agents verify version before running the shared system.\n\n---\n\n## Daily Operations\n\n### Recording a Change\n\nWhenever a config or system change affects multiple agents:\n\n1. **Edit `CHANGELOG.md`** in master's `memory/` directory — add a new `## vX.Y` section\n2. **Bump the version** — `echo \"vX.Y\" > memory/.current_system_version`\n3. The change is dispatched automatically on the next master heartbeat\n\n### Force-Syncing Immediately\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview the version change\nbash scripts/force_sync.sh --dry-run ~/.openclaw/workspace-/memory v3.0 v3.1\n\n# Execute (--confirm required for write operations)\nbash scripts/force_sync.sh --confirm ~/.openclaw/workspace-/memory v3.0 v3.1\n```\n\nAfter running, the next heartbeat detects `current (v3.1) != last_sync (v3.0)` and dispatches.\n\n### Checking Sync Status\n\n```bash\n# Check version sentinel files\ncat ~/.openclaw/workspace-/memory/.current_system_version\ncat ~/.openclaw/workspace-/memory/.last_sync_version\n\n# Check journal for recent sync records\ntail -5 ~/.openclaw/workspace-/memory/.sync_journal.jsonl\n\n# Check for pending syncs on an agent\nls ~/.openclaw/workspace-/pending_sync_*.md\n```\n\n### Demo Mode (Learning)\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/init_sync.sh --demo --lang en\n```\n\nCreates a complete demo deployment in `/tmp/` showing the full file structure without touching real workspaces.\n\n---\n\n## Manual Sync Trigger\n\n```bash\nbash skills/agent-config-sync/scripts/force_sync.sh \\\n ~/.openclaw/workspace-amaster/memory v3.0 v3.1\n```\n\nThis creates a version mismatch (old=3.0, new=3.1) — next heartbeat dispatches.\n\n---\n\n## Troubleshooting\n\n### Agents Not Receiving Updates\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| No dispatch on heartbeat | HEARTBEAT item 12 not added to master | Follow `references/sync-setup.md` exactly; verify grep `agent-config-sync` in master's HEARTBEAT.md |\n| Dispatched but not processed | Agent missing BOOTSTRAP sync check | Re-run `init_sync.sh` for that agent's workspace |\n| `pending_sync` files piling up | Agent never deletes after processing | Check agent's HEARTBEAT.md has sync check with delete step |\n| Same version synced repeatedly | `.last_sync_version` not updated | Run `force_sync.sh` to reset, or check journal for stale records |\n| Version sentinel files (`.current_system_version`, `.last_sync_version`) are read-only | Accidental `chmod 444` or permission inheritance | **All writes silently fail** — version appears unchanged. Fix: `chmod 664 memory/.current_system_version memory/.last_sync_version` |\n| Dispatched but log says \"permission denied\" | Sentinel files or journal files have wrong ownership | `ls -la memory/.current_system_version memory/.last_sync_version memory/.sync_journal.jsonl` → verify writable by the user running OpenClaw |\n\n### Version Conflicts\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| Wrong version on agent | Partial sync interrupted | Check journal for `status=prepared` records; master re-dispatches on next heartbeat |\n| Multiple `pending_sync` files | Back-to-back changes | Process latest version first; all files are cumulative |\n| SHA256 verification fails | File tampered or truncated | Request master to re-dispatch that version |\n| \"Backup failed\" in force_sync | Memory dir permission issue | `chmod 755 memory/` and retry |\n\n### Journal Issues\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| Stale prepared records (>24h) | Agent was offline too long | Mark as abandoned in journal, re-trigger sync with `force_sync.sh` |\n| Journal growing too large | Many sync records | Archive old `committed` entries periodically |\n| Corrupt journal line | Partial write or disk issue | Delete the last line (corrupt), re-trigger sync |\n\n### Rolling Back a Change\n\nTo undo a sync that was dispatched but shouldn't have been:\n\n1. **Revert the version**: `echo \"v3.0\" > memory/.current_system_version` (back to previous)\n2. **Revert the last_sync**: `echo \"v3.0\" > memory/.last_sync_version`\n3. **Mark the journal record**: Edit `.sync_journal.jsonl`, find the record with `\"to\":\"v3.1\"` and change `status` to `\"reverted\"`\n4. **Notify agents**: Agents check `pending_sync` files on heartbeat — delete old ones\n5. **Verify**: `ls ~/.openclaw/workspace-*/pending_sync_*.md` should be empty\n\nAlternatively, use `force_sync.sh` in \"reverse\":\n\n```bash\nbash scripts/force_sync.sh memory/ v3.0 v3.1 # created mismatch forward\nbash scripts/force_sync.sh memory/ v3.1 v3.0 # reverse: current=v3.0, last=v3.1 → no dispatch (current < last)\n```\n\n> ⚠️ `force_sync.sh` only creates the version mismatch — actual rollback requires reverting the changes in CHANGELOG and agent configs manually.\n\n---\n\n## 🌐 Internationalization\n\nThis skill supports both **Chinese** and **English** environments:\n\n| Resource | Chinese | English |\n|----------|:---:|:---:|\n| `SKILL.md` (this file) | — | ✅ Full English |\n| `references/quickstart.md` | — | ✅ English quickstart for new users |\n| `references/sync-setup.md` | ✅ Full Chinese | — (code pseudocode is language-agnostic) |\n| `references/sync-journal.md` | ✅ Full Chinese | — (JSONL format is language-agnostic) |\n| `scripts/init_sync.sh` | `--lang zh` (default) | `--lang en` |\n| `scripts/force_sync.sh` | `--lang zh` (default) | `--lang en` |\n| Registry agent names | `name_zh` field | `name` field |\n| Generated SYNC.md | Chinese template | English template (via `--lang en`) |\n| Generated CHANGELOG.md | Chinese template | English template (via `--lang en`) |\n\n**Using English**:\n\n```bash\n# Install and initialize in English\nbash scripts/init_sync.sh --lang en\n\n# Demo in English\nbash scripts/init_sync.sh --lang en --demo\n```\n\nNew English-speaking users should start with `references/quickstart.md`.\n\n---\n\n## Upgrading\n\n### From v1.0 to v1.1\n\n- `agent-registry.json` introduced (previously agent list was hardcoded)\n- `pending_sync` files now use version-named format (`pending_sync_v3.1_a1b2c3.md`) instead of single `pending_sync.md`\n- Journal-based two-phase commit added\n- No breaking changes — existing sentinel files and CHANGELOG format unchanged\n\n### From v1.1 to v1.2\n\n- **Registry is now single source of truth**: scripts read agent list from `agent-registry.json` instead of command-line args\n- **Bilingual scripts**: `--lang en|zh` flag on both `init_sync.sh` and `force_sync.sh`\n- **New flags**: `--dry-run` (preview), `--demo` (learning mode), `--help`\n- **English quickstart**: `references/quickstart.md` added\n- **`agent-registry.json` format changed**: added `vars` section with placeholders\n\n#### Migration steps (v1.1 → v1.2)\n\n1. **Update `agent-registry.json`**:\n ```json\n // Add this at the top of your existing agent-registry.json:\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n // Update workspace paths to use placeholders:\n \"agents\": {\n \"acode\": {\n \"workspace\": \"${vars.workspace_root}/workspace-acode\" // <-- use placeholder\n }\n }\n ```\n\n2. **Verify** with dry-run: `bash scripts/init_sync.sh --dry-run`\n\n3. **Re-run init**: `bash scripts/init_sync.sh` (safe — skips existing files)\n\n#### Compatibility notes\n\n- Existing `CHANGELOG.md`, sentinel files, and `.sync_journal.jsonl` are **fully compatible**\n- Agent-side `pending_sync_*.md` / `SYNC.md` / `BOOTSTRAP.md` format unchanged\n- `force_sync.sh` positional args unchanged; new flags are additive\n\n---\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `SKILL.md` | This skill definition |\n| `SECURITY.md` | Security model, permissions, and user consent flow |\n| `references/quickstart.md` | 🆕 English quickstart for new users |\n| `references/sync-setup.md` | HEARTBEAT item 12 + structured CHANGELOG spec |\n| `references/pending-sync-template.md` | pending_sync file template (version-named) |\n| `references/sync-journal.md` | Journal-based two-phase commit mechanism |\n| `references/agent-registry.json` | Single source of truth for agent IDs and workspaces |\n| `scripts/init_sync.sh` | Full setup in one command (now reads registry; supports --auto) |\n| `scripts/force_sync.sh` | Trigger immediate sync detection |\n| `scripts/revert_sync.sh` | Trigger version rollback |\n| `scripts/wizard.sh` | 🆕 Interactive setup wizard for new users |\n\nFile v1.5.1:README.md\n\n# agent-config-sync v1.5\n\n**Keep configuration consistent across multiple OpenClaw agents** — zero-touch setup, interactive wizard, version tracking, and automatic sync dispatch.\n\n[![Version](https://img.shields.io/badge/version-1.5.0-blue)](_meta.json)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-enabled-green)](https://openclaw.ai)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Bash](https://img.shields.io/badge/pure-bash-orange)](scripts/)\n\n---\n\n## 🎯 What It Does\n\nWhen you run 2+ OpenClaw agents, keeping their configurations in sync is painful. `agent-config-sync` automates this:\n\n```\nMaster Agent detects change\n │\n ▼\n Reads CHANGELOG.md\n │\n ▼\n Generates sync manifest\n │\n ├─→ Agent 1: pending_sync_v3.1_a1b2c3.md\n ├─→ Agent 2: pending_sync_v3.1_a1b2c3.md\n └─→ Agent 3: pending_sync_v3.1_a1b2c3.md\n │\n ▼\n Agents apply → verify → cleanup\n```\n\n**Syncs**: System code · Agent configs (SOUL/IDENTITY/TOOLS) · OpenClaw config · Task configs · API keys\n\n---\n\n## ⚡ Quick Start (30 seconds)\n\n```bash\n# 1. Install\nclawhub install agent-config-sync\n\n# 2. Run wizard (interactive, auto-detects everything)\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n\n# 3. Done! 🎉\n# All agents now have sync infrastructure.\n# Changes are auto-dispatched on next Master heartbeat.\n```\n\n**Prefer non-interactive?**\n```bash\nbash scripts/wizard.sh --auto # Zero prompts\nbash scripts/init_sync.sh --auto # Even faster\n```\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|:--------|:------------|\n| 🧙 **Interactive Wizard** | 5-step guided setup with auto-detection — no manual file editing |\n| 🤖 **--auto Mode** | One-command setup that detects workspaces, generates registry, and initializes everything |\n| 📊 **Version Tracking** | Sentinel files (`.current_system_version`, `.last_sync_version`) for monotonic versioning |\n| 🔄 **Auto Dispatch** | Master HEARTBEAT detects version mismatch → dispatches to all agents via `sessions_send` or file fallback |\n| 📝 **CHANGELOG-driven** | Structured `CHANGELOG.md` — read only latest section, not entire history |\n| 🗄️ **Two-Phase Commit** | `.sync_journal.jsonl` ensures atomicity — PREPARE → DISPATCH → COMMIT |\n| 🔍 **Offline Catch-Up** | Agents that miss sync cycles get cumulative catch-up packages |\n| 🛡️ **Rollback** | Pre-sync snapshots + SHA256 verification for safe rollbacks |\n| 🔒 **Dispatch Lock** | Prevents concurrent sync dispatch (< 2min window) |\n| 🔁 **Loop Detection** | 3+ consecutive same-version → block and alert |\n| 📦 **Batch Mode** | Merges rapid consecutive changes into single dispatch |\n| 🏝️ **Self-Upgrade Isolation** | agent-config-sync's own files use isolated upgrade flow |\n| 🌐 **Bilingual** | Full Chinese + English output (`--lang en|zh`) |\n| 🎭 **Demo Mode** | `--demo` creates a full temp deployment for learning |\n| 🔐 **Path Validation** | Only writes to `~/.openclaw/workspace-*` — no external access |\n\n---\n\n## 📋 Requirements\n\n- **OpenClaw** running with 2+ agents\n- One designated \"master\" coordination agent\n- `clawhub` CLI installed\n- Bash 4.0+ (no Python/Perl required)\n\n---\n\n## 🏗️ Architecture\n\n```\nskills/agent-config-sync/\n├── SKILL.md # Full documentation\n├── SECURITY.md # Security model & permissions\n├── README.md # This file\n├── _meta.json # Package metadata\n├── scripts/\n│ ├── wizard.sh # 🆕 Interactive setup wizard (v1.5)\n│ ├── init_sync.sh # Infrastructure initialization\n│ ├── force_sync.sh # Trigger immediate sync detection\n│ └── revert_sync.sh # Version rollback trigger\n├── references/\n│ ├── agent-registry.json # Single source of truth (agent IDs, paths)\n│ ├── sync-setup.md # HEARTBEAT item 12 + CHANGELOG spec\n│ ├── sync-journal.md # Two-phase commit mechanism\n│ ├── pending-sync-template.md # Sync file template\n│ └── quickstart.md # Quickstart for new users\n└── reports/\n └── ... # Evaluation reports & repair logs\n```\n\n---\n\n## 🚀 Usage\n\n### Daily Operations\n\n```bash\n# Record a change (master agent)\necho \"v1.1\" > ~/.openclaw/workspace-amaster/memory/.current_system_version\n\n# Or use the force_sync helper\nbash scripts/force_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0 v1.1\n```\n\n### Check Status\n\n```bash\n# Master version\ncat ~/.openclaw/workspace-amaster/memory/.current_system_version\ncat ~/.openclaw/workspace-amaster/memory/.last_sync_version\n\n# Pending syncs on an agent\nls ~/.openclaw/workspace-acode/pending_sync_*.md\n```\n\n### Rollback\n\n```bash\nbash scripts/revert_sync.sh --dry-run ~/.openclaw/workspace-amaster/memory v1.0\nbash scripts/revert_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0\n```\n\n### Demo / Learning\n\n```bash\nbash scripts/init_sync.sh --demo --lang en\n```\n\n---\n\n## ⚙️ Configuration\n\nThe wizard auto-generates `references/agent-registry.json`. To customize manually:\n\n```json\n{\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\"\n },\n \"agents\": {\n \"acode\": { \"name\": \"Coding Agent\", \"role\": \"Development\", \"workspace\": \"...\" },\n \"ainvest\": { \"name\": \"Investment Agent\", \"role\": \"Finance\", \"workspace\": \"...\" }\n }\n}\n```\n\n---\n\n## 🔒 Security\n\nAll scripts enforce:\n- `--confirm` required for writes (use `--dry-run` first)\n- Path whitelist: only `~/.openclaw/workspace-*` allowed\n- Cross-agent isolation: each agent accesses only its own workspace\n- Atomic writes: `tempfile → sync → mv` (no partial sentinel files)\n- No network, no API calls, no credential access\n\nFull details: [SECURITY.md](SECURITY.md)\n\n---\n\n## 🌐 Internationalization\n\n```bash\n# English output\nbash scripts/wizard.sh --lang en\nbash scripts/init_sync.sh --lang en\n\n# Chinese output (default)\nbash scripts/wizard.sh --lang zh\n```\n\n---\n\n## 📄 License\n\nMIT\n\n---\n\n## 🙋 FAQ\n\n**Q: How is this different from just copying files?**\nA: It's event-driven (version mismatch → dispatch), journaled (two-phase commit), and handles edge cases (offline agents, conflicts, rollbacks).\n\n**Q: Do I need to run this on every agent?**\nA: No. Only the Master agent dispatches. Other agents receive `pending_sync_*.md` files and check for them on startup/heartbeat (automatically set up by `init_sync.sh`).\n\n**Q: What if an agent is offline?**\nA: The Master writes a `pending_sync_.md` file to the agent's workspace. On next startup, the agent detects and applies it. If multiple versions piled up, version collapse jumps to the latest.\n\n**Q: Can I use this without `clawhub`?**\nA: Yes — just clone or copy the skill directory to `~/.openclaw/skills/agent-config-sync/` and run `scripts/wizard.sh`.\n\nFile v1.5.1:_meta.json\n\n{\n \"ownerId\": \"kn7at24f2mbp2nzbvyprwbaws186t9g8\",\n \"slug\": \"agent-config-sync\",\n \"version\": \"1.5.1\",\n \"publishedAt\": 1778918841603\n}\n\nFile v1.5.1:references/agent-registry.json\n\n{\n \"version\": \"1.4.0\",\n \"comment\": \"Customize this file for your deployment — vars section + keyed agents object. v1.4 adds self_protect, batch, and sync configuration.\",\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"acode\": {\n \"name\": \"大师\",\n \"name_en\": \"Coding Agent\",\n \"role\": \"编程开发\",\n \"workspace\": \"${vars.workspace_root}/workspace-acode\"\n },\n \"ainvest\": {\n \"name\": \"元宝\",\n \"name_en\": \"Investment Agent\",\n \"role\": \"投资分析\",\n \"workspace\": \"${vars.workspace_root}/workspace-ainvest\"\n },\n \"alive\": {\n \"name\": \"牛奶\",\n \"name_en\": \"Assistant Agent\",\n \"role\": \"生活助理/写作\",\n \"workspace\": \"${vars.workspace_root}/workspace-alive\"\n }\n },\n \"sync\": {\n \"sentinel_dir\": \"memory\",\n \"journal_file\": \".sync_journal.jsonl\",\n \"changelog_file\": \"CHANGELOG.md\",\n \"pending_prefix\": \"pending_sync\",\n \"max_changelog_sections\": 10,\n \"ttl_hours\": 24,\n \"dispatch_timeout_sec\": 120\n },\n \"self_protect\": {\n \"enabled\": true,\n \"skip_agents\": [\"agent-config-sync\"],\n \"isolated_sync\": true,\n \"blacklist\": [\n \"HEARTBEAT.md\",\n \"BOOTSTRAP.md\",\n \"SKILL.md\",\n \"scripts/\",\n \"SECURITY.md\",\n \"references/\",\n \"agent-registry.json\"\n ],\n \"sync_own_version_file\": \"skills/agent-config-sync/.sync_own_version\",\n \"allow_bootstrap_only\": true\n },\n \"batch\": {\n \"mode\": \"auto\",\n \"window_sec\": 300\n }\n}\n\nFile v1.5.1:references/agent-setup.md\n\n# Per-Agent Auto-Sync Setup\n\nFor each agent workspace, create or append to these files:\n\n## 1. SYNC.md (new file)\n\n```markdown\n# 配置同步机制 — 自动获取变更通知\n\n## 检查入口\n每次启动/激活时，先检查工作空间下的 `pending_sync.md` 是否存在且非空。\n\n## 同步检查流程\n```\n启动/激活 → 检查工作目录存在 pending_sync.md?\n ├─ ✅ 有内容 → 读取变更摘要 → 更新本地 MEMORY.md\n │ → 根据变更内容更新本地配置\n │ → 删除 pending_sync.md（标记已处理）\n │ → 回复 AMaster 确认已同步\n └─ ❌ 无文件或空 → 无需同步\n```\n\n## 同步源\n- 完整变更日志: `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md`\n- 当前版本: `/home/admin/.openclaw/workspace-amaster/memory/.current_system_version`\n- 主动查询: 可向 AMaster 询问最新版本状态\n\n## 重要\n- 使用量化交易系统 / 比价系统前，必须确认版本信息\n- 如果有 pending_sync.md 但未处理，不要使用相关系统功能\n```\n\n## 2. BOOTSTRAP.md (append to end)\n\n```markdown\n## 启动检查 — 配置同步\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在 → 读取变更摘要，更新 MEMORY.md，删除 pending_sync.md\n - 不存在 → 无需同步\n- [ ] 使用量化系统/比价系统前先确认版本\n```\n\n## 3. HEARTBEAT.md (append to end)\n\n```markdown\n## ⭐ 配置同步检查（每次 heartbeat 执行）\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在且非空 → 读取变更摘要，更新 MEMORY.md，删除文件\n - 不存在 → 跳过\n```\n\nFile v1.5.1:references/pending-sync-template.md\n\n# pending_sync Template\n\n**v1.4**: Enhanced file header with TTL/expiry, depends_on chain, and agent version tracking fields. Backward compatible — new fields are additive.\n\n## Template Content\n\n```markdown\n# pending_sync__.md\n\n**类型**: pending_sync\n**版本**: \n**前置**: \n**生成时间**: \n**过期时间**: (24h 后)\n**紧急程度**: \n**签名**: \n\n## 变更清单\n- [ ] 🖥️ 系统代码变更\n- [ ] 🤖 智能体配置变更\n- [ ] ⚙️ OpenClaw 系统配置变更\n- [ ] 🎯 任务/工作配置变更\n\n## 详情\n请读取 `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md` 中 `` 对应的章节。\n\n## 操作指令\n1. 创建前置快照: mkdir -p memory/.sync_snapshots/_pre/\n2. 备份受影响文件到快照目录\n3. 应用变更\n4. 更新 memory/.agent_sync_version = \n5. 删除本文件\n```\n\n## Template Fields\n\n| Field | Required | Format | Example |\n|-------|:--------:|--------|---------|\n| `**类型**` | ✅ | `pending_sync` / `revert_sync` / `isolated_sync` | pending_sync |\n| `**版本**` | ✅ | `vX.Y` | v3.5 |\n| `**前置**` | ⬜ | `vX.Y` or `none` | v3.4 |\n| `**生成时间**` | ✅ | ISO 8601 with timezone | 2026-05-16T08:30:00+08:00 |\n| `**过期时间**` | ✅ | ISO 8601 (24h after generated) | 2026-05-17T08:30:00+08:00 |\n| `**紧急程度**` | ✅ | `normal` / `high` / `critical` | high |\n| `**签名**` | ✅ | SHA256 first 12 hex chars | a1b2c3d4e5f6 |\n\n## SHA256 Signature\n\nThe `` value in the filename and template body is computed as:\n\n```\nsha256(\"pending_sync__\" + 变更摘要)\n```\n\nTake the first 12 hex characters as the short signature.\n\n### Purpose\n- Receiving agent can verify file integrity\n- Prevents tampered or truncated sync notifications\n- Short 12-char format keeps filenames manageable\n\n### Verification (in agent-side logic)\n\n```python\nimport hashlib\n\ndef verify_sync_file(filename, expected_version, change_summary):\n expected_sig = hashlib.sha256(\n f\"pending_sync_{expected_version}_{change_summary}\".encode()\n ).hexdigest()[:12]\n actual_sig = filename.split(\"_\")[-1].replace(\".md\", \"\")\n return expected_sig == actual_sig\n```\n\n## File Naming Convention\n\n| Pattern | Example |\n|---------|---------|\n| Version sync | `pending_sync_v3.1_a1b2c3d4e5f6.md` |\n| Startup discovery | `ls pending_sync_*.md` to list all pending |\n| Revert sync | `revert_sync_v3.3_to_v3.2_a1b2c3d4.md` |\n| Isolated sync | `isolated_sync_v1.4_a1b2c3d4.md` |\n\n## Cleanup\n\nEach agent independently deletes its own pending file after processing:\n\n```bash\n# Agent-side cleanup after sync applied\nrm -f pending_sync_*.md revert_sync_*.md isolated_sync_*.md\n```\n\nThe file persists as long as the agent hasn't applied the sync. If the same version file is generated twice (e.g., dispatch retry), the content is idempotent — the agent can re-apply safely.\n\n## TTL & Expiry\n\nBy default, pending_sync files expire **24 hours** after generation. The agent's BOOTSTRAP/HEARTBEAT checks should:\n\n1. Parse `**过期时间**` from the file header\n2. If `now > 过期时间` → delete the expired file, request latest version from Master\n3. If `now <= 过期时间` → proceed with sync processing\n\nTTL is configurable via `agent-registry.json` → `sync.ttl_hours` (default: 24).\n\nFile v1.5.1:references/quickstart.md\n\n# Quickstart — agent-config-sync for New Users\n\n**5-minute setup** to keep configuration consistent across all your OpenClaw agents.\n\n---\n\n## Before You Start\n\nYou need:\n- OpenClaw running with 2+ agents\n- A \"master\" agent that coordinates others\n- `clawhub` CLI installed\n\n### Example Setup (Alice)\n\nAlice has 3 agents:\n\n| Agent ID | Purpose | Workspace |\n|----------|---------|-----------|\n| `alice-dev` | Software development | `~/.openclaw/workspace-alice-dev` |\n| `alice-biz` | Business analysis | `~/.openclaw/workspace-alice-biz` |\n| `alice-ops` | Operations & scheduling | `~/.openclaw/workspace-alice-ops` |\n\nAlice uses `alice-ops` as her master/coordination agent.\n\nWe'll use Alice's setup as a concrete example throughout this guide.\n\n---\n\n## Step 1: Install the Skill\n\n```bash\nclawhub install agent-config-sync\n```\n\nThis installs to `~/.openclaw/skills/agent-config-sync/`.\n\n---\n\n## Step 2: Customize the Agent Registry\n\nEdit `~/.openclaw/skills/agent-config-sync/references/agent-registry.json` to match your agents:\n\n```json\n{\n \"version\": \"1.2\",\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"alice-ops\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"alice-dev\": {\n \"name\": \"Alice Dev\",\n \"role\": \"Software Development\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-dev\"\n },\n \"alice-biz\": {\n \"name\": \"Alice Biz\",\n \"role\": \"Business Analysis\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-biz\"\n },\n \"alice-ops\": {\n \"name\": \"Alice Ops\",\n \"role\": \"Coordination\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-ops\"\n }\n }\n}\n```\n\n> **Key**: Change `master_agent` in `vars` and replace all agent entries under `agents`. Scripts read from this file — this is the **only place** you need to configure agent names.\n\n---\n\n## Step 3: Initialize Sync Infrastructure\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview what will be created (safe, makes no changes)\nbash scripts/init_sync.sh --dry-run\n\n# Run the actual setup\nbash scripts/init_sync.sh\n```\n\nThis creates:\n- Version sentinel files in your master agent's `memory/` directory\n- `CHANGELOG.md` with structured format\n- `.sync_journal.jsonl` for sync atomicity\n- `SYNC.md`, bootstrapped `BOOTSTRAP.md`, and `HEARTBEAT.md` sync checks in each agent workspace\n\n---\n\n## Step 4: Add HEARTBEAT Item to Master Agent\n\nAdd this to your master agent's `HEARTBEAT.md`:\n\n```markdown\n12. ⭐ **Config Change Sync** — Check for unsynchronized system/config changes\n - **Sentinel**: `memory/.last_sync_version`\n - Compare against `memory/.current_system_version` on every heartbeat\n - If version mismatch detected → dispatch to all downstream agents:\n a. Read latest section from `memory/CHANGELOG.md`\n b. `sessions_send` to each agent (or write `pending_sync__.md` as fallback)\n c. Record results in `.sync_journal.jsonl`\n - On success → update `memory/.last_sync_version` = `memory/.current_system_version`\n - Sync failure does NOT block heartbeat — logged to journal only\n```\n\nSee `references/sync-setup.md` for the full specification.\n\n---\n\n## Step 5: Verify\n\n```bash\n# Check version files were created\ncat ~/.openclaw/workspace-alice-ops/memory/.current_system_version\n# Expected: v1.0\n\ncat ~/.openclaw/workspace-alice-ops/memory/.last_sync_version\n# Expected: v1.0\n\n# Check agent sync files exist\nls ~/.openclaw/workspace-alice-dev/SYNC.md ~/.openclaw/workspace-alice-biz/SYNC.md\n# Both should exist\n```\n\n---\n\n## Step 6: Test a Sync\n\n```bash\n# Bump version to trigger sync on next heartbeat\necho \"v1.1\" > ~/.openclaw/workspace-alice-ops/memory/.current_system_version\n\n# Or use the force_sync helper:\nbash ~/.openclaw/skills/agent-config-sync/scripts/force_sync.sh \\\n ~/.openclaw/workspace-alice-ops/memory v1.0 v1.1\n```\n\nThe next heartbeat on your master agent will detect the version mismatch and dispatch config changes to all agents.\n\n---\n\n## Customizing Further\n\n### Change master memory path\n\nIf your master agent stores memory elsewhere, update `vars.master_memory` in `.agent_registry`:\n\n```json\n\"vars\": {\n \"master_memory\": \"/custom/path/to/memory\"\n}\n```\n\n### Use as non-master agent\n\nThe skill's sync reception is agent-side: each agent checks for `pending_sync_*.md` files on startup (BOOTSTRAP) and every heartbeat (HEARTBEAT). The `init_sync.sh` script sets this up automatically.\n\n### Language\n\nScripts support Chinese and English output:\n\n```bash\nbash scripts/init_sync.sh --lang en # English output\nbash scripts/init_sync.sh --lang zh # Chinese output (default)\n```\n\n---\n\n## Troubleshooting\n\n| Problem | Check |\n|---------|-------|\n| \"Registry not found\" in init_sync | Run from skill directory: `cd ~/.openclaw/skills/agent-config-sync` |\n| Agents not receiving syncs | Verify master agent has HEARTBEAT item 12 |\n| `pending_sync` files pile up | Agent may not have BOOTSTRAP sync check — re-run `init_sync.sh` |\n| Path errors | Check `vars.workspace_root` in `agent-registry.json` — expand `~` to full path if needed |\n\n---\n\n## Next Steps\n\n- Read `SKILL.md` for architecture overview and daily operations\n- Read `references/sync-setup.md` for HEARTBEAT implementation details\n- Read `references/sync-journal.md` for the two-phase commit mechanism\n\nFile v1.5.1:references/sync-journal.md\n\n# Sync Journal — 两步提交机制\n\n## 概述\n\nSync Journal 提供配置同步的原子性和可恢复性保证。\n每次版本同步操作都通过 journal 记录，确保即使中途中断也能正确恢复。\n\n## Journal 文件\n\n- **位置**: `memory/.sync_journal.jsonl`\n- **格式**: JSONL (每行一条 JSON 记录)\n- **权限**: 与 version sentinel 文件同级\n\n## 记录格式\n\n```jsonl\n{\"ts\":\"2026-05-16T08:30:00Z\",\"from\":\"v3.0\",\"to\":\"v3.1\",\"status\":\"prepared\",\"agents\":{\"acode\":\"pending\",\"ainvest\":\"pending\",\"alive\":\"pending\"}}\n{\"ts\":\"2026-05-16T08:30:01Z\",\"from\":\"v3.0\",\"to\":\"v3.1\",\"status\":\"committed\",\"agents\":{\"acode\":\"done\",\"ainvest\":\"done\",\"alive\":\"pending\"}}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `ts` | ISO 8601 | 操作时间戳 (UTC) |\n| `from` | string | 同步前版本号 |\n| `to` | string | 同步目标版本号 |\n| `status` | prepared/committed/failed | 同步状态 |\n| `agents` | object | 每个 agent 的同步状态: pending/done/failed/timeout |\n\n## 两步提交流程\n\n### Step 1: PREPARE\n\n```\ncontext: AMaster HEARTBEAT 检测到 .current_system_version != .last_sync_version\naction:\n 1. 计算变更摘要 (从 CHANGELOG.md 中 latest version 章节)\n 2. 计算 SHA256 签名\n 3. 写入 journal 记录 (status=prepared)\n 4. 生成 pending_sync__.md 文件内容\n 5. 更新 .last_sync_version = .current_system_version (乐观更新)\n```\n\n### Step 2: DISPATCH\n\n```\naction:\n 1. 依次对每个 agent:\n a. 尝试 sessions_send 发送变更摘要\n b. 若 sessions_send 失败 → 写入 pending_sync__.md 到 agent workspace\n 2. 更新 journal: 标记 agents 各自的状态\n```\n\n### Step 3: COMMIT\n\n```\naction:\n 1. 检查 journal 中该记录的 agents 状态\n 2. 全部 done → 更新 journal status=committed\n 3. 部分 pending → 保留 prepared 状态，等待下次 heartbeat 重试\n```\n\n## Heartbeat 重试机制\n\n每次 AMaster HEARTBEAT 执行时:\n\n1. 检查 `.sync_journal.jsonl` 是否有 `status=prepared` 的记录\n2. 若有 → 对其中 `agents` 状态为 `pending` 的 agent 重新 DISPATCH\n3. 若全部 done → 标记 committed\n4. 超时 (超过 24h 的 prepared 记录) → 标记 failed，记录到 MEMORY.md\n\n## 伪代码\n\n```python\n# AMaster HEARTBEAT 中的 sync logic\n\ndef heartbeat_sync_check():\n # 1. 检查未完成的 journal 记录\n for record in read_journal(status=\"prepared\"):\n if is_stale(record):\n mark_abandoned(record)\n continue\n for agent_id, agent_status in record[\"agents\"].items():\n if agent_status != \"done\":\n retry_dispatch(agent_id, record)\n\n # 2. 检查新版本\n current = read(\".current_system_version\")\n last = read(\".last_sync_version\")\n\n if current != last:\n changes = read_changelog_section(current)\n sig = sha256(f\"pending_sync_{current}_{changes}\")[:12]\n record = {\n \"ts\": now_utc(),\n \"from\": last,\n \"to\": current,\n \"status\": \"prepared\",\n \"agents\": {a: \"pending\" for a in agent_ids}\n }\n\n # PREPARE\n write_journal(record)\n write(\".last_sync_version\", current)\n\n # DISPATCH + COMMIT\n for agent_id in agent_ids:\n result = try_sessions_send(agent_id, changes)\n if not result:\n write_pending_sync(agent_id, current, sig, changes)\n record[\"agents\"][agent_id] = \"pending\"\n else:\n record[\"agents\"][agent_id] = \"done\"\n\n record[\"status\"] = \"committed\" if all_done(record[\"agents\"]) else \"prepared\"\n update_journal(record)\n```\n\n## 原子性保证 (P1-6)\n\n- Journal 机制保证: 只有全部 agent 标记 done 后才能推进版本号为 committed\n- 失败的 agent 会在下次 heartbeat 自动重试\n- PREPARE 阶段已更新 `.last_sync_version`，避免重复触发同版本同步\n- 每个 agent 独立失败/重试，互不影响\n\n## 循环检测 (v1.4)\n\n### 机制\n\n防止同步系统因自身或其他 Agent 的修改触发无限循环分发：\n\n```\n检测流程 (HEARTBEAT item 12 前置检查):\n1. 读取 journal 最近 5 条记录\n2. 提取每条记录的 to_version\n3. 检查连续 3 条记录的 to_version 是否相同\n4. 若相同 → 判断为循环\n - 记录 WARNING: \"Loop detected for version \"\n - 写入 loop_detected 记录到 journal\n - 跳过本轮分发\n - 要求人工确认\n```\n\n### loop_detected 记录格式\n\n```jsonl\n{\"ts\":\"2026-05-16T09:00:00Z\",\"type\":\"loop_detected\",\"to\":\"v3.2\",\"reason\":\"3 consecutive identical to_version in journal\",\"status\":\"blocked\"}\n```\n\n### 阈值配置\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `loop_detect_window` | 5 | 检查最近 N 条记录 |\n| `loop_detect_threshold` | 3 | 连续 N 条相同版本触发警报 |\n\n参数可在 `agent-registry.json` 的 `sync` 配置段中覆盖。\n\nFile v1.5.1:references/sync-setup.md\n\n# HEARTBEAT Item 12 — Config Change Force Sync\n\nAdd this to the AMaster's HEARTBEAT.md checklist:\n\n```markdown\n12. ⭐ 配置变更同步（含版本冲突管理 v1.4）\n ┌─ 前置检查 ───────────────────────────────────────────\n │ a. 循环检测: 检查 journal 最近 5 条，连续 3 条相同版本 → 报警跳过\n │ b. 分发锁: 上轮 prepared < 2min → 跳过；>= 2min → 超时处理；>= 10min → abandoned\n │ c. 自身升级: 影响范围含 \"agent-config-sync\" → 走 isolated 流程\n ├─ 版本检测 ───────────────────────────────────────────\n │ d. 哨兵对比: .current != .last_sync → 有新版本\n │ e. 回滚检测: current < last_sync → 回滚操作，走 revert 流程\n │ f. 批量窗口: batch_mode=true → 等待 batch_window_sec，合并后分发\n ├─ 分发准备 ───────────────────────────────────────────\n │ g. 读 CHANGELOG 最新版本 (含 depends_on / 协同依赖字段)\n │ h. 动态获取 agent 列表 (registry)\n │ i. 生成 SHA256 签名 + TTL 过期时间\n │ j. PREPARE journal 记录 (含版本链信息)\n ├─ 分发执行 ───────────────────────────────────────────\n │ k. 逐个 agent: sessions_send 优先, pending_sync 回退\n │ l. 离线检测: 若 agent 已离线 > 1h → 生成累积追赶包\n │ m. COMMIT journal: 全部 done → committed; 部分 done → prepared\n └─ 收尾 ───────────────────────────────────────────────\n │ n. 更新 .last_sync_version\n │ o. 清理超过 TTL 的过期 prepared 记录 → abandoned\n │ p. 失败不阻断 heartbeat\n```\n\n## Structured CHANGELOG Format\n\n每条版本条目必须使用标准 Markdown 锚点，方便语义化解析和增量读取。\n\n### 格式规范\n\n```markdown\n# 系统变更日志\n\n## v3.2 (2026-05-16)\n**变更类型**: 🖥️ 系统代码\n**影响范围**: 量化交易系统, 价格对比\n**变更人**: AMaster\n**紧急程度**: normal\n**前置依赖**: v3.1\n**协同依赖**: (无)\n\n### 修改\n- 优化回测引擎参数计算逻辑\n- 修复价格对比时间戳偏移问题\n\n### 新增\n- 添加自动止损阈值配置\n\n### 废弃\n- （暂无）\n\n## v3.1 (2026-05-15)\n**变更类型**: 🖥️ 系统代码 / 🤖 Agent配置\n**影响范围**: all agents\n**变更人**: AMaster\n**紧急程度**: high\n**前置依赖**: v3.0\n**协同依赖**: (无)\n\n### 修改\n- 所有 agent TOOLS.md 新增 sessions_yield\n- 更新 AMaster SOUL.md 协同规则\n\n### 新增\n- （暂无）\n\n### 废弃\n- （暂无）\n```\n\n### 读取策略 (P0-3)\n\n同步时**只发送最新版本的数据**，而非全量 CHANGELOG：\n\n```python\ndef read_latest_changelog_section(changelog_path):\n \"\"\"Read only the most recent version's section from CHANGELOG.md\"\"\"\n with open(changelog_path) as f:\n content = f.read()\n\n # Split by ## headers and take the first version section\n sections = re.split(r'(?=^## v\\d)', content, flags=re.MULTILINE)\n if len(sections) > 1:\n return sections[1].strip() # First version section after title\n return None\n```\n\n### 版本号格式\n\n- 遵循 `v.[.]`\n- 例如: `v1.0`, `v3.2`, `v5.1.3`\n- 变化规则:\n - MAJOR: 整体架构变更\n - MINOR: 功能新增/修改\n - PATCH: 修复/补丁\n\n### 可选字段（v1.4 新增）\n\n| 字段 | 格式 | 说明 |\n|------|------|------|\n| `**Depends On**: vX.Y` | `vX.Y` | 前置依赖版本。Agent 应用时检查自己当前版本是否 >= 前置版本 |\n| `**协同依赖**: [agent_id]` | agent ID 列表 | 需要协同的 Agent。多 Agent 联合变更时，标记依赖关系确保正确处理顺序 |\n\n## Infrastructure files reference\n\n### Version sentinel files\n```\nmemory/.current_system_version → git-worthy monotonically increasing version\nmemory/.last_sync_version → set to current after successful sync\nmemory/CHANGELOG.md → structured full change log\nmemory/.sync_journal.jsonl → sync atomicity journal\n```\n\n### Sync dispatch (updated for v1.1 with journal)\n\n#### Offline Catch-Up (v1.4)\n\nWhen an agent was offline (missed one or more sync cycles), the Master generates a cumulative catch-up package:\n\n```\n离线追赶逻辑 (Master 端):\n\n1. 检查 agent 的 .agent_sync_version (从 agent workspace/memory/ 读取)\n2. 对比 .current_system_version:\n - IF agent.agent_sync_version == current → agent is up-to-date\n - IF agent.agent_sync_version < current → agent has fallen behind\n\n3. 计算版本差距:\n gap_versions = 所有 CHANGELOG 条目中，版本 > agent_version 且 <= current_version\n\n4. 追赶策略:\n IF len(gap_versions) == 1:\n → 直接分发该版本\n ELIF len(gap_versions) >= 2 AND depends_on 链完整:\n → 生成累积追赶包: 包含从 agent 最后版本到最新版本的所有变更摘要\n → 单文件分发 (pending_sync__.md)\n → 文件头 前置字段 = agent 当前版本\n ELSE (链断):\n → 按版本顺序依次分发每个 gap_version\n → 按依赖链排序\n```\n\n```\n离线追赶逻辑 (Agent 端):\n\n启动/恢复时:\n 1. 读取自己的 .agent_sync_version\n 2. 列出 pending_sync_*.md\n 3. 对于所有版本 > .agent_sync_version 的文件:\n a. 若 depends_on 链覆盖 → 使用版本折叠 (一次性跳到最新)\n b. 若链断 → 按版本顺序逐个处理\n 4. 每处理一个版本 → 更新 .agent_sync_version\n```\n\n#### Dispatch Lock (v1.4)\n\nBefore each dispatch cycle, the Master checks for an active dispatch window:\n\n```\n前置检查 — 分发锁:\n 1. 读取 journal 中最后一条 status=prepared 的记录\n 2. 计算 elapsed = now - record.ts\n 3. 判断:\n - IF elapsed < 2min → 分发窗口未关闭 → SKIP 本轮分发\n - IF 2min <= elapsed < 10min → 标记为 timeout → 重新分发\n - IF elapsed >= 10min → 标记为 abandoned → 重新分发 (新 journal record)\n 4. Loop detection check (见下)\n 5. Self-upgrade check (impact range includes agent-config-sync)\n 6. Only after ALL checks pass → proceed with dispatch\n```\n\n#### Loop Detection (v1.4)\n\nPrevents infinite sync loops when a change triggers re-dispatch of the same version:\n\n```\n循环检测逻辑:\n\n1. 读取 journal 最近 5 条记录 (tail -5 .sync_journal.jsonl)\n2. 提取每条记录的 to_version\n3. 检查: 连续 3 条记录的 to_version 相同\n4. 若检测到循环:\n - 写入 WARNING 到 MEMORY.md: \"Loop detected for version \"\n - Journal 新增记录: {\"type\":\"loop_detected\",\"to\":\"\",\"ts\":\"...\"}\n - SKIP 本轮分发\n - 要求人工确认后继续\n5. 若未检测到循环 → 继续 dispatch 流程\n```\n\nJournal loop_detected record format:\n```jsonl\n{\"ts\":\"2026-05-16T09:00:00Z\",\"type\":\"loop_detected\",\"to\":\"v3.2\",\"reason\":\"3 consecutive identical to_version in journal\",\"status\":\"blocked\"}\n```\n\n```python\n# Pseudocode for sync dispatch with journal — v1.4 enhanced\nimport json, time, hashlib, re, os\nfrom datetime import datetime, timezone, timedelta\n\nTTL_HOURS = 24 # Configurable via agent-registry.json sync.ttl_hours\nDISPATCH_TIMEOUT_MIN = 2\nDISPATCH_ABANDON_MIN = 10\nLOOP_WINDOW = 5\nLOOP_THRESHOLD = 3\nBATCH_WINDOW_SEC = 300 # Configurable via agent-registry.json sync.batch.window_sec\nSELF_PROTECT_BLACKLIST = [\"HEARTBEAT.md\", \"BOOTSTRAP.md\", \"SKILL.md\", \"scripts/\",\n \"SECURITY.md\", \"references/\"]\n\ndef heartbeat_sync_check(agent_ids, memory_dir, workspace_base, agent_workspaces):\n \"\"\"Enhanced HEARTBEAT item 12 — full sync lifecycle\"\"\"\n\n # ── 0. Retry pending records ──────────────────────────────\n for record in read_journal(status=\"prepared\"):\n elapsed = (now_utc() - parse_ts(record[\"ts\"])).total_seconds()\n if elapsed > TTL_HOURS * 3600:\n # Expired prepared record → mark abandoned\n record[\"status\"] = \"abandoned\"\n record[\"reason\"] = f\"TTL exceeded ({TTL_HOURS}h)\"\n update_journal(record)\n continue\n if elapsed < DISPATCH_TIMEOUT_MIN * 60:\n # Dispatch window still open → skip this record\n continue\n # Retry dispatch for still-pending agents\n for agent_id, agent_status in record[\"agents\"].items():\n if agent_status != \"done\":\n retry_dispatch_agent(agent_id, record, workspace_base,\n agent_workspaces)\n\n # ── 1. Read version sentinels ────────────────────────────\n current_ver = read(f\"{memory_dir}/.current_system_version\").strip()\n last_ver = read(f\"{memory_dir}/.last_sync_version\").strip()\n\n if current_ver == last_ver:\n return # No changes\n\n # ── 2. Rollback detection ─────────────────────────────────\n if version_less(current_ver, last_ver):\n handle_rollback(current_ver, last_ver, memory_dir, workspace_base,\n agent_ids, agent_workspaces)\n return\n\n # ── 3. Dispatch lock ──────────────────────────────────────\n last_prepared = get_last_journal_entry(status=\"prepared\")\n if last_prepared:\n elapsed = (now_utc() - parse_ts(last_prepared[\"ts\"])).total_seconds()\n if elapsed < DISPATCH_TIMEOUT_MIN * 60:\n # Dispatch window still open — skip this cycle\n return\n elif DISPATCH_TIMEOUT_MIN * 60 <= elapsed < DISPATCH_ABANDON_MIN * 60:\n # Timed out → mark and re-dispatch\n last_prepared[\"status\"] = \"timeout\"\n update_journal(last_prepared)\n\n # ── 4. Loop detection ─────────────────────────────────────\n recent = read_journal_last_n(LOOP_WINDOW)\n to_versions = [r[\"to\"] for r in recent if \"to\" in r]\n if len(to_versions) >= LOOP_THRESHOLD and \\\n len(set(to_versions[-LOOP_THRESHOLD:])) == 1:\n loop_ver = to_versions[-1]\n log_warning(f\"Loop detected for version {loop_ver}\")\n write_journal({\n \"ts\": now_utc().isoformat(),\n \"type\": \"loop_detected\",\n \"to\": loop_ver,\n \"reason\": f\"{LOOP_THRESHOLD} consecutive identical to_version\",\n \"status\": \"blocked\"\n })\n return # Skip this dispatch cycle\n\n # ── 5. Read CHANGELOG + self-upgrade check ────────────────\n changelog = read(f\"{memory_dir}/CHANGELOG.md\")\n latest_section = extract_latest_section(changelog, current_ver)\n\n # Parse impact range from CHANGELOG entry\n impact_range = parse_field(latest_section, \"影响范围\")\n depends_on = parse_field(latest_section, \"前置依赖\") or last_ver\n priority = parse_field(latest_section, \"紧急程度\") or \"normal\"\n\n # Check if this change affects agent-config-sync itself\n is_self_upgrade = False\n for blacklisted in SELF_PROTECT_BLACKLIST:\n if blacklisted in impact_range or \"agent-config-sync\" in impact_range:\n is_self_upgrade = True\n break\n\n if is_self_upgrade:\n handle_isolated_sync(current_ver, last_ver, latest_section,\n memory_dir, agent_ids, agent_workspaces)\n return\n\n # ── 6. Batch mode check ───────────────────────────────────\n batch_mode = get_sync_config(\"batch.mode\") == \"auto\"\n if batch_mode:\n batch_id = f\"batch_{now_utc().strftime('%Y%m%d_%H%M')}\"\n # Check if there's already an open batch window\n open_batch = get_last_journal_entry(status=\"batched\", batch_id__startswith=\"batch_\")\n if open_batch:\n elapsed = (now_utc() - parse_ts(open_batch[\"ts\"])).total_seconds()\n if elapsed < BATCH_WINDOW_SEC:\n # Add to existing batch\n open_batch[\"accumulated_versions\"].append(current_ver)\n open_batch[\"accumulated_changes\"].append(latest_section)\n update_journal(open_batch)\n return\n else:\n # Batch window closed → merge and dispatch\n handle_batch_commit(open_batch, memory_dir, workspace_base,\n agent_ids, agent_workspaces)\n\n # ── 7. Generate signature ─────────────────────────────────\n sig = hashlib.sha256(\n f\"pending_sync_{current_ver}_{latest_section[:200]}\".encode()\n ).hexdigest()[:12]\n\n # ── 8. PREPARE journal ────────────────────────────────────\n expires_at = (now_utc() + timedelta(hours=TTL_HOURS)).isoformat()\n record = {\n \"ts\": now_utc().isoformat(),\n \"type\": \"normal\",\n \"from\": last_ver,\n \"to\": current_ver,\n \"depends_on\": depends_on,\n \"status\": \"prepared\",\n \"priority\": priority,\n \"changelog_section\": parse_field(latest_section, \"变更类型\"),\n \"ttl_hours\": TTL_HOURS,\n \"agents\": {}\n }\n # Initialize agent statuses\n for agent_id in agent_ids:\n record[\"agents\"][agent_id] = {\"status\": \"pending\", \"ts\": None}\n\n append_journal(f\"{memory_dir}/.sync_journal.jsonl\", record)\n\n # ── 9. Update last_sync_version optimistically ────────────\n _atomic_write(f\"{memory_dir}/.last_sync_version\", current_ver)\n\n # ── 10. DISPATCH to each agent ────────────────────────────\n generated_at = now_utc().isoformat()\n for agent_id in agent_ids:\n agent_ws = agent_workspaces.get(agent_id)\n if not agent_ws:\n record[\"agents\"][agent_id][\"status\"] = \"skipped\"\n record[\"agents\"][agent_id][\"reason\"] = \"no_workspace\"\n continue\n\n # Offline catch-up check\n agent_version_file = f\"{agent_ws}/memory/.agent_sync_version\"\n agent_version = read(agent_version_file).strip() if os.path.exists(agent_version_file) else None\n\n if agent_version and version_less(agent_version, last_ver):\n # Agent is far behind → generate cumulative catch-up\n content = generate_catchup_content(agent_version, current_ver, changelog, sig)\n else:\n content = format_sync_content(current_ver, latest_section, sig,\n generated_at, expires_at, priority,\n depends_on)\n\n try:\n sessions_send(agentId=agent_id, message=content)\n record[\"agents\"][agent_id] = {\"status\": \"done\", \"ts\": now_utc().isoformat()}\n except RuntimeError:\n # Fallback to file\n ws = f\"{workspace_base}-{agent_id}\"\n filename = f\"pending_sync_{current_ver}_{sig}.md\"\n write(f\"{ws}/{filename}\", content)\n record[\"agents\"][agent_id] = {\"status\": \"pending\", \"ts\": None}\n\n # ── 11. COMMIT ────────────────────────────────────────────\n all_done = all(a[\"status\"] == \"done\" for a in record[\"agents\"].values())\n record[\"status\"] = \"committed\" if all_done else \"prepared\"\n update_last_journal_entry(f\"{memory_dir}/.sync_journal.jsonl\", record)\n\n # ── 12. Cleanup expired prepared records ──────────────────\n cleanup_abandoned_records(memory_dir, TTL_HOURS)\n\n\ndef handle_rollback(target_ver, current_ver, memory_dir, workspace_base,\n agent_ids, agent_workspaces):\n \"\"\"Handle version rollback: current < last_sync\"\"\"\n sig = hashlib.sha256(\n f\"revert_sync_{current_ver}_to_{target_ver}\".encode()\n ).hexdigest()[:12]\n\n record = {\n \"ts\": now_utc().isoformat(),\n \"type\": \"revert\",\n \"from\": current_ver,\n \"to\": target_ver,\n \"status\": \"prepared\",\n \"agents\": {}\n }\n\n for agent_id in agent_ids:\n ws = agent_workspaces.get(agent_id)\n if not ws:\n continue\n revert_file = f\"{ws}/revert_sync_{current_ver}_to_{target_ver}_{sig}.md\"\n content = f\"\"\"# Revert Sync — {current_ver} → {target_ver}\n\n**类型**: revert_sync\n**回滚到**: {target_ver}\n**生成时间**: {now_utc().isoformat()}\n**签名**: {sig}\n\n## 操作指令\n1. 从 memory/.sync_snapshots/{target_ver}_pre/ 恢复文件\n2. 验证 SHA256 checksums (参考 snapshot_manifest.json)\n3. 更新 memory/.agent_sync_version = {target_ver}\n4. 删除本文件\n\"\"\"\n write(revert_file, content)\n record[\"agents\"][agent_id] = {\"status\": \"pending\", \"ts\": None}\n\n append_journal(f\"{memory_dir}/.sync_journal.jsonl\", record)\n _atomic_write(f\"{memory_dir}/.last_sync_version\", target_ver)\n\n\ndef handle_isolated_sync(version, last_ver, changelog_section, memory_dir,\n agent_ids, agent_workspaces):\n \"\"\"Handle self-upgrade via isolated sync flow\"\"\"\n sig = hashlib.sha256(\n f\"isolated_sync_{version}_{changelog_section[:200]}\".encode()\n ).hexdigest()[:12]\n\n isolated_file = f\"{memory_dir}/isolated_sync_{version}_{sig}.md\"\n content = f\"\"\"# Isolated Sync — agent-config-sync Self-Upgrade\n\n**类型**: isolated_sync\n**版本**: {version}\n**生成时间**: {now_utc().isoformat()}\n**签名**: {sig}\n\n{changelog_section}\n\n## 重要\n此文件不是通过正常 HEARTBEAT 分发，而是要求 Agent 下次启动时在 BOOTSTRAP 检查中主动请求升级。\n\"\"\"\n write(isolated_file, content)\n\n # Notify agents via BOOTSTRAP-visible notification (not direct dispatch)\n for agent_id in agent_ids:\n ws = agent_workspaces.get(agent_id)\n if ws and os.path.exists(f\"{ws}/BOOTSTRAP.md\"):\n note = f\"\\n⚠️ agent-config-sync 系统需要升级: 见 master memory/isolated_sync_{version}.md\\n\"\n append(f\"{ws}/BOOTSTRAP.md\", note)\n\n write_journal({\n \"ts\": now_utc().isoformat(),\n \"type\": \"isolated\",\n \"from\": last_ver,\n \"to\": version,\n \"status\": \"prepared\",\n \"agents\": {a: {\"status\": \"notified\", \"ts\": now_utc().isoformat()}\n for a in agent_ids}\n })\n\n\ndef handle_batch_commit(batch_record, memory_dir, workspace_base,\n agent_ids, agent_workspaces):\n \"\"\"Merge accumulated batch versions into single dispatch\"\"\"\n versions = batch_record[\"accumulated_versions\"]\n changes = batch_record[\"accumulated_changes\"]\n\n # Merge: use highest version, combine all change descriptions\n final_version = max(versions, key=version_sort_key)\n combined_content = \"\\n\\n\".join(changes)\n sig = hashlib.sha256(\n f\"batch_sync_{final_version}_{combined_content[:200]}\".encode()\n ).hexdigest()[:12]\n\n batch_record[\"status\"] = \"committed\"\n batch_record[\"final_version\"] = final_version\n batch_record[\"batch_size\"] = len(versions)\n update_journal(batch_record)\n\n # Dispatch as single cumulative sync\n for agent_id in agent_ids:\n ws = f\"{workspace_base}-{agent_id}\"\n filename = f\"pending_sync_{final_version}_{sig}.md\"\n content = format_batch_sync_content(final_version, combined_content, sig)\n write(f\"{ws}/{filename}\", content)\n\n\ndef generate_catchup_content(agent_version, target_version, full_changelog, sig):\n \"\"\"Generate cumulative catch-up for an agent that fell behind\"\"\"\n gap_entries = extract_version_range(full_changelog, agent_version, target_version)\n combined = \"\\n\\n\".join(gap_entries)\n\n generated_at = now_utc().isoformat()\n expires_at = (now_utc() + timedelta(hours=TTL_HOURS)).isoformat()\n\n return f\"\"\"## 累积追赶包 — {agent_version} → {target_version}\n\n**类型**: pending_sync (cumulative catch-up)\n**累积范围**: {agent_version} → {target_version}\n**生成时间**: {generated_at}\n**过期时间**: {expires_at}\n**签名**: {sig}\n\n{combined}\n\n## 操作指令\n1. 版本差距: {agent_version} → {target_version} ({len(gap_entries)} versions)\n2. 检查 depends_on 链完整性\n3. 如链完整 → 直接跳到 {target_version}\n4. 如链断 → 按版本顺序处理\n5. 更新 memory/.agent_sync_version = {target_version}\n\"\"\"\n\n\n# ── Helper functions ──────────────────────────────────────────\ndef _atomic_write(filepath, content):\n tmp = f\"{filepath}.tmp.{os.getpid()}\"\n with open(tmp, 'w') as f:\n f.write(content)\n os.fsync(f.fileno()) if hasattr(os, 'fsync') else os.sync()\n os.rename(tmp, filepath)\n\ndef version_less(a, b):\n \"\"\"Compare vX.Y.Z format versions\"\"\"\n def parse(v): return tuple(int(x) for x in v.lstrip('v').split('.'))\n return parse(a) < parse(b)\n\ndef version_sort_key(v):\n return tuple(int(x) for x in v.lstrip('v').split('.'))\n\ndef now_utc():\n return datetime.now(timezone.utc)\n\ndef read(filepath):\n with open(filepath) as f:\n return f.read()\n\ndef extract_latest_section(changelog, version):\n sections = re.split(r'(?=^## v\\d)', changelog, flags=re.MULTILINE)\n for s in sections:\n if s.strip().startswith(f\"## {version}\"):\n return s.strip()\n return sections[1].strip() if len(sections) > 1 else \"\"\n\ndef extract_version_range(changelog, from_ver, to_ver):\n \"\"\"Extract all CHANGELOG entries between two versions (exclusive of from_ver)\"\"\"\n sections = re.split(r'(?=^## v\\d)', changelog, flags=re.MULTILINE)\n entries = []\n for s in sections[1:]: # skip title\n ver_match = re.match(r'## (v[\\d.]+)', s)\n if ver_match:\n v = ver_match.group(1)\n if version_less(from_ver, v) and not version_less(to_ver, v):\n entries.append(s.strip())\n return entries\n\ndef parse_field(markdown_section, field_name):\n \"\"\"Parse a **Field**: value line from a CHANGELOG section\"\"\"\n pattern = rf'\\*\\*{re.escape(field_name)}\\*\\*:?\\s*(.+?)(?:\\n|$)'\n m = re.search(pattern, markdown_section, re.IGNORECASE)\n return m.group(1).strip() if m else None\n\ndef format_sync_content(version, section, sig, generated_at, expires_at,\n priority, depends_on):\n return f\"\"\"# pending_sync_{version}_{sig}.md\n\n**类型**: pending_sync\n**版本**: {version}\n**前置**: {depends_on or 'none'}\n**生成时间**: {generated_at}\n**过期时间**: {expires_at}\n**紧急程度**: {priority}\n**签名**: {sig}\n\n{section}\n\n## 操作指令\n1. 创建前置快照: mkdir -p memory/.sync_snapshots/{version}_pre/\n2. 备份受影响文件到快照目录\n3. 应用变更\n4. 更新 memory/.agent_sync_version = {version}\n5. 删除本文件\n\"\"\"\n\n### Pending_sync fallback paths\n\nVersion-named files (cumulative mode):\n- `~/.openclaw/workspace-acode/pending_sync__.md`\n- `~/.openclaw/workspace-ainvest/pending_sync__.md`\n- `~/.openclaw/workspace-alive/pending_sync__.md`\n\nAgent can discover all pending files: `ls pending_sync_*.md`\n\nFile v1.5.1:reports/agent-config-sync-eval-v1.1.md\n\n# agent-config-sync v1.1 — 功能评估报告\n\n**评估日期**: 2026-05-16\n**评估人**: 大师 (acode)\n**评估范围**: SKILL.md + references/ (5 files) + scripts/ (2 files)\n\n---\n\n## 1. 通用性评分: 2/5\n\n### 问题清单\n\n| 位置 | Hardcode 内容 | 影响 |\n|------|-------------|------|\n| `SKILL.md` description | `acode/ainvest/alive` | 新用户 Agent ID 不同，description 误导 |\n| `SKILL.md` 场景 A/B | 大师/元宝/牛奶 | 中文名称 + 特定 agent，英文用户无法理解 |\n| `.agent_registry` | `acode/ainvest/alive` + 大师/元宝/牛奶 | 注册表有定义但无说明如何修改 |\n| `references/sync-setup.md` | 推送消息给大师/元宝/牛奶 | HEARTBEAT 模板硬编码中文 Agent 名 |\n| `references/sync-setup.md` 伪代码 | `agent_ids` 不明确来源 | 未说明从哪读取 agent 列表 |\n| `references/sync-setup.md` pending paths | `workspace-acode/ainvest/alive` | 路径写死 |\n| `references/sync-journal.md` | 全部中文注释和描述 | 英文用户完全无法理解 |\n| `references/pending-sync-template.md` | 混合中文 | 模板内容中文，非中文用户难用 |\n| `scripts/init_sync.sh` | 中文输出 + 中文文件内容 | 脚本 echo 和生成文件全是中文 |\n| `scripts/force_sync.sh` | 中文输出 | 错误消息全部中文 |\n\n### 结论\n新用户安装后需要修改 **至少 8 处** 才能适配自己的 Agent 体系。非中文用户完全无法使用（脚本输出、模板、journal 文档全部中文）。\n\n---\n\n## 2. 可扩展性评分: 2/5\n\n### 增加第 5 个 Agent 需要改几处？\n\n| 文件 | 修改内容 | 估计工作量 |\n|------|---------|----------|\n| `.agent_registry` | 添加新条目 | 1 行 |\n| `SKILL.md` description | 追加 agent ID | 1 行 |\n| `references/sync-setup.md` HEARTBEAT 模板 | \"大师/元宝/牛奶\" → \"大师/元宝/牛奶/新Agent\" | 1 行 |\n| `references/sync-setup.md` pending paths | 追加路径 | 1 行 |\n| `references/sync-setup.md` 伪代码 | 无改动（如果 agent_ids 是数组） | 0 行 |\n| `SKILL.md` 场景 A/B | 追加新 Agent 名称 | 2 处 |\n| `scripts/init_sync.sh` | 命令行参数多传一个 | 调用处 |\n| **总计** | | **6-7 处修改** |\n\n### 去掉牛奶需要改几处？\n\n| 文件 | 修改内容 | 估计工作量 |\n|------|---------|----------|\n| `.agent_registry` | 删除 alive 条目 | 1 行 |\n| `SKILL.md` description | 删除 alive | 1 行 |\n| `references/sync-setup.md` HEARTBEAT 模板 | 去掉\"牛奶\" | 1 行 |\n| `references/sync-setup.md` pending paths | 删除 alive 路径 | 1 行 |\n| `SKILL.md` 场景 | 去掉牛奶引用 | 2-3 处 |\n| **总计** | | **5-6 处修改** |\n\n### 根本问题\nAgent 列表**没有单一真实来源**——`.agent_registry` 存在但脚本和文档都不从中读取。每次增删 Agent 需要在 JSON + 多个 Markdown + Shell 脚本中同步修改。\n\n---\n\n## 3. 文档质量评分: 2/5\n\n### 按文件评估\n\n| 文件 | 语言 | 自包含性 | 问题 |\n|------|------|---------|------|\n| `SKILL.md` | 中英混合 | 部分自包含 | description 英文但正文场景全中文；无安装步骤；无变量自定义说明 |\n| `references/sync-setup.md` | 全中文 | 需要理解整个体系 | 无英文；HEARTBEAT 模板绑定特定 Agent；伪代码不完整 |\n| `references/pending-sync-template.md` | 中英混合 | 需要理解上下文 | 模板内容中文；无独立使用说明 |\n| `references/sync-journal.md` | 全中文 | 需要理解两步提交 | 全中文；无英文版本 |\n| `references/.agent_registry` | 英文 JSON | 部分自包含 | JSON 格式清晰但无注释说明字段含义 |\n\n### 关键缺失\n- ❌ 无英文 Quickstart\n- ❌ 无「如何适配你的 Agent」指南\n- ❌ 安装步骤散落在 SKILL.md 和 sync-setup.md 之间\n- ❌ 无可配置变量表格（用户不知道改哪）\n\n---\n\n## 4. 跨平台兼容性: 3/5\n\n### Shell 脚本分析\n\n| 特性 | `init_sync.sh` | `force_sync.sh` | POSIX? |\n|------|:---:|:---:|:---:|\n| Shebang `#!/bin/bash` | ✅ | ✅ | ❌ Bash 非 POSIX |\n| `shift` | ✅ | ❌ | ✅ POSIX |\n| `[[ ... ]]` | ❌ 使用 `[ ]` | ❌ 使用 `[ ]` | ✅ POSIX |\n| `${1:-default}` | ✅ | ✅ | ✅ POSIX |\n| `$@` / `$*` | ✅ | ✅ | ✅ POSIX |\n| `<< 'CHG'` heredoc | ✅ | ❌ | ✅ POSIX |\n| `grep -qE` | ✅ | ✅ | ✅ POSIX |\n| `sed` extended regex | ❌ 未使用 -E | ❌ 未使用 -E | ⚠️ 基础 sed 安全 |\n| `$(date ...)` | ✅ | ✅ | ✅ POSIX |\n\n### 路径问题\n- `~/.openclaw/` 在所有文件中硬编码\n- 无 `OPENCLAW_ROOT` 环境变量支持\n- `basename \"$agent_ws\" | sed 's/workspace-//'` 假设 workspace 命名规则，不灵活\n\n### 结论\n脚本在 Bash 下可正常运行于 Linux/macOS。基础语法接近 POSIX，但 Shebang 是 bash。路径不可配置是最主要的可移植性问题。\n\n---\n\n## 5. 风险点\n\n### 🔴 高优先级\n\n1. **Agent 名称硬编码遍布全库**\n - 在任何地方增删 Agent 需要修改 5+ 个文件\n - 容易遗漏，导致部分 Agent 收到同步、部分收不到\n - `.agent_registry` 已定义但没人用——增加了维护负担\n\n2. **init_sync.sh 会直接修改 Agent 的 BOOTSTRAP.md / HEARTBEAT.md**\n - Agent 可能有自定义内容，脚本无备份直接追加\n - 无 dry-run 模式预览副作用\n - 追加的中文内容对非中文 Agent 无意义\n\n3. **版本哨兵文件依赖特定路径 `memory/`**\n - 没有配置入口\n - 如果 AMaster 的 memory 在别处，整个机制失效\n\n### 🟡 中优先级\n\n4. **sync-journal.md 全中文**：日志格式清晰但操作文档不可读\n5. **force_sync.sh 覆盖 .current_system_version 后备份不完整**：只备份了 sentinel 文件，没备份 CHANGELOG\n6. **无回滚机制**：force_sync 可以创建 mismatch 但无法撤销\n\n### 🟢 低优先级\n\n7. **init_sync.sh SYNC.md 模板比较逻辑**：用 `sed` 剥离空白比较，跨平台可能有 `sed` 行为差异\n8. **无 `--help` 参数**：两个脚本都没有 `-h`/`--help`\n\n---\n\n## 总体评分\n\n| 维度 | 评分 | 加权 | 备注 |\n|------|:---:|:---:|------|\n| 通用性 | 2/5 | 30% | 绑定特定 Agent 体系，中文用户限定 |\n| 可扩展性 | 2/5 | 25% | 增删 Agent 需改多处，无单一真实来源 |\n| 文档质量 | 2/5 | 20% | 无英文快速入门，安装步骤分散 |\n| 跨平台兼容性 | 3/5 | 15% | Bash 可运行但路径硬编码 |\n| 代码健壮性 | 3/5 | 10% | 基本错误处理，无 dry-run，无回滚 |\n| **综合** | **2.25/5** | | 功能可用但通用性严重不足 |\n\n---\n\n## 优化建议摘要\n\n1. 将 `.agent_registry` 设为单一真实来源，所有脚本和模板从它读取\n2. SKILL.md 增加变量配置表，用户只需改一处\n3. 新建 `references/quickstart.md`（全英文）作为新用户入口\n4. 脚本双语化：支持 `--lang en`，默认中文\n5. `init_sync.sh` 增加 `--dry-run` 和 `--demo` 模式\n6. SKILL.md 补全 Installation / Configuration / Daily Operations / Troubleshooting / Upgrading 章节\n\nFile v1.5.1:reports/agent-config-sync-eval-v1.3.md\n\n# agent-config-sync v1.3.0 — 重新评估报告\n\n**评估日期**: 2026-05-16\n**评估人**: 大师 (acode)\n**评估范围**: v1.3.0 package → SKILL.md + 5 references + 2 scripts + 安全评估 + 部署状态\n**前次评估**: v1.1 报告 `agent-config-sync-eval-v1.1.md` (评分 2.25/5)\n\n---\n\n## 📊 执行摘要\n\n| 维度 | v1.1 评分 | v1.3 评分 | 变化 |\n|------|:---:|:---:|:---:|\n| 通用性 | 2/5 | **4/5** | ✅ +2 |\n| 可扩展性 | 2/5 | **4/5** | ✅ +2 |\n| 文档质量 | 2/5 | **4/5** | ✅ +2 |\n| 跨平台兼容性 | 3/5 | **3/5** | — 持平 |\n| 代码健壮性 | 3/5 | **4/5** | ✅ +1 |\n| 部署状态 | — | **2/5** | ⚠️ 脏 |\n| 安全覆盖 | 未评估 | **4/5** | ✅ 良好 |\n| **综合** | **2.25/5** | **3.6/5** | **+1.35** |\n\n**结论**: v1.3.0 package 的代码实际为 v1.2，但 v1.2 相比 v1.1 在通用性/可扩展性/文档上有显著提升。Registry 格式已验证可用。当前部署环境处于「脏状态」——需要清理 v1.1 残留、升级 Master HEARTBEAT item 12、重建 CHANGELOG。\n\n---\n\n## 1. v1.3.0 改进验证\n\n### 发现：v1.3.0 是 metadata-only 版本跳升\n\n```\n_meta.json version: \"1.3.0\" ← 包版本\nSKILL.md header: \"v1.2\" ← 代码版本\n所有脚本 header: \"v1.2\" ← 代码版本\n```\n\n**实际变更内容**（v1.2 → v1.3.0）:\n\n| 变更项 | 状态 |\n|--------|------|\n| `agent-registry.json` 模板修复为 `vars` + keyed agents | ✅ 已修复（本次包更新的核心） |\n| SKILL.md 代码逻辑 | ❌ 无变化 |\n| `scripts/init_sync.sh` | ❌ 无变化 |\n| `scripts/force_sync.sh` | ❌ 无变化 |\n| references 文件 | ❌ 无变化 |\n| 新功能 | ❌ 无新增 |\n\n**v1.3.0 本质上是一次 registry JSON 格式的兼容性修复版**（从错误的数组/旧格式修正为脚本期望的 `{\"vars\":..., \"agents\":{...}}` 结构）。功能代码与 v1.2 完全一致。\n\n### v1.2 相对 v1.1 的实际改进（本次评估确认）\n\n| v1.1 问题 | v1.2 修复 | 验证 |\n|-----------|----------|:---:|\n| Agent 列表硬编码在脚本参数 | 从 `agent-registry.json` 读取（单一真实来源） | ✅ |\n| 脚本全中文输出 | `--lang en\\|zh` 双语支持 | ✅ |\n| 无 dry-run | `--dry-run` 预览模式 | ✅ |\n| 无 --help | `-h` / `--help` 完整帮助 | ✅ |\n| 无 demo 模式 | `--demo` 学习模式（/tmp 演示） | ✅ |\n| 无 `--confirm` 安全门 | 写入操作需 `--confirm` | ✅ |\n| 无 English quickstart | `references/quickstart.md` 新增 | ✅ |\n| SKILL.md 无安装章节 | Installation / Configuration / Upgrading 章节完整 | ✅ |\n| HEARTBEAT 模板绑定特定 agent | `references/sync-setup.md` 使用变量名 | ⚠️ 仍含硬编码中文 agent 名 |\n\n---\n\n## 2. Registry 格式修复验证\n\n### 测试环境：Bash `json_val()` 函数（同 init_sync.sh 内置）\n\n```\n✅ vars.workspace_root → ~/.openclaw\n✅ vars.master_agent → amaster\n✅ vars.master_memory (raw) → ${vars.workspace_root}/workspace-${vars.master_agent}/memory\n✅ vars.master_memory (res.) → ~/.openclaw/workspace-amaster/memory\n✅ agents.acode.workspace → ~/.openclaw/workspace-acode\n```\n\n### Agent ID 提取\n\n```\n✅ read_agent_ids() → acode, ainvest, alive (3 agents)\n✅ master_agent (amaster) 自动排除（不下发给自身 SYNc 文件）\n```\n\n### 变量解析验证\n\n| 输入值 | 解析后 | 结论 |\n|--------|--------|:---:|\n| `${vars.workspace_root}/workspace-acode` | `~/.openclaw/workspace-acode` | ✅ |\n| `${vars.workspace_root}/workspace-${vars.master_agent}/memory` | `~/.openclaw/workspace-amaster/memory` | ✅ |\n\n**Registry 格式验证结论**: 完全可用。`json_val()` 提取 + `resolve_vars()` 变量替换 + `expand_path()` 路径扩展三层管道工作正常。\n\n---\n\n## 3. 实际 dry-run 验证\n\n```\nbash scripts/init_sync.sh --dry-run --lang zh\n```\n\n### 输出解析\n\n| 检查项 | 预期 | 实际 | 结论 |\n|--------|------|------|:---:|\n| Master workspace 检测 | `workspace-amaster` | `/home/admin/.openclaw/workspace-amaster` | ✅ |\n| Agent acode 识别 | 是 | ✅ Agent 'acode' 已配置 | ✅ |\n| Agent ainvest 识别 | 是 | ✅ Agent 'ainvest' 已配置 | ✅ |\n| Agent alive 识别 | 是 | ✅ Agent 'alive' 已配置 | ✅ |\n| 跳过 master agent | amaster 不下发 | amaster 不在列表中 | ✅ |\n| 版本文件创建 | memory/ 目录 | memory 已存在，sentinel 跳过 | ✅ (幂等) |\n| SYNC.md 状态 | 已是最新 | \"已是最新，跳过\" × 3 | ✅ |\n| BOOTSTRAP 状态 | 已有检查 | \"已有同步检查\" × 3 | ✅ |\n| HEARTBEAT 状态 | 已有检查 | \"已有同步检查\" × 3 | ✅ |\n\n**Dry-run 结论**: 全部通过。脚本逻辑正确，agent 列表从 registry 自动读取，路径解析正常。\n\n---\n\n## 4. 部署差距分析\n\n### 当前环境详细状态\n\n```\nmemory/.current_system_version = v3.1 (quant system version, not sync-format)\nmemory/.last_sync_version = v3.1 (same → no mismatch possible)\nmemory/.sync_journal.jsonl = 0 bytes (exists but empty)\nmemory/CHANGELOG.md = quant system full changelog (v0.1→v3.1)\nMaster HEARTBEAT item 12 = v1.1 format (pending_sync.md singular, hardcoded names)\n```\n\n### 差距清单\n\n| # | 问题 | 严重度 | 影响 |\n|---|------|:---:|------|\n| G1 | **Master HEARTBEAT item 12 is v1.1** — `pending_sync.md` (单数)、硬编码\"大师/元宝/牛奶\"、无 journal dispatch、无 SHA256、无重试 | 🔴 高 | 即使版本 mismatch，dispatch 仍用旧机制 |\n| G2 | **下游 Agent 重复条目** — BOOTSTRAP/HEARTBEAT 各含 2 份同步检查（v1.1 + v1.2），共 12 处冗余 | 🔴 高 | Agent 每次 heartbeat 执行 2 次相同同步检查 |\n| G3 | **`pending_sync.md` (v1.1 单数) 仍然存在** — 下游 agent 的 BOOTSTRAP/HEARTBEAT v1.1 条目检查 `pending_sync.md` 而非 `pending_sync_*.md` | 🔴 高 | v1.2+ 产生的 `pending_sync_v3.1_xxx.md` 文件不会被 v1.1 检查发现 |\n| G4 | **CHANGELOG.md 格式不兼容** — 当前为量化系统完整功能履历，不符合 sync 结构化格式（`## vX.Y (YYYY-MM-DD)` + `**Change Type**:` + `**Affected Agents**:`） | 🟡 中 | sync dispatcher 无法正确解析变更章节 |\n| G5 | **`.current_system_version` = v3.1 但无对应 sync 条目** — quant 系统版本 vs sync 版本命名空间冲突 | 🟡 中 | 需要决定是否分离量化版本和 sync 版本 |\n| G6 | **`agent-setup.md` 参考文件过期** — 内容为 v1.1 格式（`pending_sync.md` 单数），但 `init_sync.sh` 已生成 v1.2 内容 | 🟢 低 | 文档误导，但脚本不使用该文件 |\n| G7 | **`quickstart.md` 引用 `.agent_registry` 旧文件名** — 实际文件是 `agent-registry.json` | 🟢 低 | 新用户可能困惑 |\n| G8 | **`.sync_journal.jsonl` 为空** — 虽然有文件，但从未有 sync 记录 | 🟢 低 | 初始化时 touch 了空文件但从未实际使用 |\n| G9 | **无 `.last_sync_version` 初始化语义** — 当前值为 v3.1（与 current 相同），但未被 init_sync.sh 正确设置 | 🟢 低 | 需要运行 `force_sync.sh` 或手动重置 |\n\n### 下游 Agent 重复条目详情\n\n每个下游 agent 的 **BOOTSTRAP.md**:\n```\n✗ 第1份 (v1.1): \"检查工作目录下是否存在 `pending_sync.md`\"\n✓ 第2份 (v1.2): \"检查工作目录下是否存在 `pending_sync_*.md` 文件\"\n```\n\n每个下游 agent 的 **HEARTBEAT.md**:\n```\n✗ 第1份 (v1.1): \"检查工作目录下是否存在 `pending_sync.md`\"\n✓ 第2份 (v1.2): \" + pending_sync_*.md + SHA256 验证\"\n```\n\n**原因**: v1.1 和 v1.2 的 `init_sync.sh` 都用了 `grep -q` 检测 \"pending_sync_\" 但 v1.2 使用 `agent-config-sync-check` 作为 marker。v1.1 追加时匹配了 \"pending_sync_\" 但 v1.2 追加时 marker 不同，所以两次都追加成功。\n\n---\n\n## 5. 安全评估\n\n### SECURITY.md 覆盖分析\n\n| 安全维度 | SECURITY.md 覆盖 | 脚本实际执行 | 评价 |\n|----------|:---:|------|:---:|\n| **路径校验** | ✅ `~/.openclaw/workspace-*` only | ✅ `init_sync.sh` case match, `force_sync.sh` case match | 正确 |\n| **跨 agent 隔离** | ✅ 每个 agent 只读写自己的 workspace | ✅ 脚本只操作各 agent 的 BOOTSTRAP/HEARTBEAT/SYNC | 正确 |\n| **用户确认** | ✅ `--confirm` required for writes | ✅ 两脚本均强制检查 `CONFIRMED` | 正确 |\n| **Dry-run 预览** | ✅ `--dry-run` 始终可用 | ✅ 两脚本均支持 | 正确 |\n| **备份机制** | ✅ 修改前备份 | ✅ `force_sync.sh` 创建 `.bak.timestamp` | 正确 |\n| **变更日志** | ✅ stdout + journal 记录 | ⚠️ stdout 输出完整但 journal 从未实际写入 | 部分 |\n| **无网络访问** | ✅ 声明不需要 | ✅ 脚本零网络调用 | 正确 |\n| **无凭据访问** | ✅ 声明不需要 | ✅ 脚本不读任何凭证文件 | 正确 |\n| **权限模型** | ✅ 声明 AMaster 可写所有 workspace | ⚠️ `pending_sync` 写入由 HEARTBEAT 逻辑执行，不在脚本范围内 | 文档对应 |\n\n### 安全评分: **4/5**\n\n**扣分项**:\n- 🔸 `force_sync.sh` 只备份 sentinel 文件，不备份 CHANGELOG.md\n- 🔸 无 TOCTOU 防护（检查路径和写文件之间有时间窗口）\n- 🔸 无 symlink 攻击防护（`test -d` 不检测是否为 symlink）\n- 🔸 journal 写入逻辑仅在伪代码中描述，脚本不实际写入 journal\n\n**肯定项**:\n- ✅ 两阶段安全门（`--dry-run` + `--confirm`）设计良好\n- ✅ 路径白名单机制（`case` match `$HOME/.openclaw/workspace-*`）硬编码在脚本中\n- ✅ 所有文件操作限制在已知范围内，无任意路径写入\n- ✅ 声明了权限范围并清晰标注不需要的能力\n\n---\n\n## 6. 综合评分与修复路线\n\n### 6.1 总体评分\n\n| 维度 | v1.1→v1.3 | 详情 |\n|------|:---:|------|\n| **代码质量** | 4/5 | 脚本逻辑清晰，路径安全，错误处理基本到位 |\n| **部署状态** | 2/5 | 脏环境 — v1.1+v1.2 混合，需要清理 |\n| **文档完整性** | 4/5 | 中英文全，安装/配置/升级/排错章节齐全 |\n| **安全模型** | 4/5 | 路径校验+用户确认+隔离声明，小缺口 |\n| **v1.3 增量价值** | 1/5 | 仅 registry JSON 兼容性修复，无功能变更 |\n\n### 6.2 修复路线图\n\n#### Phase 1: 下游 Agent 清理（立即执行）\n\n```\n任务 P1.1: 清理 BOOTSTRAP.md 重复条目\n 目标文件: workspace-acode/BOOTSTRAP.md\n workspace-ainvest/BOOTSTRAP.md\n workspace-alive/BOOTSTRAP.md\n 操作: 删除 v1.1 风格的 \"## 启动检查 — 配置同步\" 段（含 `pending_sync.md` 单数版本）\n 保留 v1.2 风格的 \"## 启动检查 — 配置同步\" 段（含 `pending_sync_*.md` glob）\n\n任务 P1.2: 清理 HEARTBEAT.md 重复条目\n 目标文件: workspace-acode/HEARTBEAT.md\n workspace-ainvest/HEARTBEAT.md\n workspace-alive/HEARTBEAT.md\n 操作: 删除 v1.1 风格的 \"## ⭐ 配置同步检查\" 段（含 `pending_sync.md` 单数，无 marker）\n 保留 v1.2 风格段（含 `` marker）\n```\n\n#### Phase 2: Master Agent 升级（立即可行）\n\n```\n任务 P2.1: 升级 HEARTBEAT item 12\n 目标文件: workspace-amaster/HEARTBEAT.md\n 操作: 将当前 v1.1 格式替换为 references/sync-setup.md 中的 v1.2+ 格式:\n - pending_sync.md → pending_sync__.md\n - 硬编码 agent 名 → 从 agent-registry.json 读取\n - 添加 journal 记录步骤 (.sync_journal.jsonl)\n - 添加 SHA256 签名\n - 添加重试逻辑\n\n任务 P2.2: 建立 CHANGELOG.md sync 格式\n 目标文件: workspace-amaster/memory/CHANGELOG.md\n 决策点: 量化版本 (v0.1→v3.1) 是保留在现有 CHANGELOG 还是分离？\n 建议:\n - 方案 A: 将现有 CHANGELOG 归档为 CHANGELOG_quant.md，新建 sync-format CHANGELOG.md\n - 方案 B: 在现有 CHANGELOG.md 顶部添加 sync-format 条目，底部保留量化历史\n\n任务 P2.3: 重置版本哨兵\n 操作: echo \"v1.0\" > .current_system_version\n echo \"v1.0\" > .last_sync_version\n 原因: v3.1 是量化系统版本，sync 系统应从 v1.0 独立计数\n 备选: 保留 v3.1 但确保后续变更使用 sync-format CHANGELOG\n```\n\n#### Phase 3: 参考文件修正（低优先级）\n\n```\n任务 P3.1: agent-setup.md\n 操作: 更新为 v1.2 格式（pending_sync_*.md glob），或标记为 deprecated\n 注意: 该文件不由脚本使用，仅人工参考\n\n任务 P3.2: quickstart.md\n 操作: 修正 .agent_registry → agent-registry.json\n```\n\n#### Phase 4: v1.4 建议增强（未来）\n\n```\n建议 E1: SKILL.md 版本号同步\n 将 SKILL.md header 中的 \"v1.2\" 更新为 \"v1.3.0\"，或移除内嵌版本号从 package.json 读取\n\n建议 E2: init_sync.sh 增加清理功能\n 添加 --clean 模式：自动移除 v1.1 重复条目\n\n建议 E3: 添加 TOCTOU/symlink 防护\n force_sync.sh: 在写文件时使用 mktemp + mv 替代直接 echo\n\n建议 E4: init_sync.sh journal 初始化\n 首次创建 .sync_journal.jsonl 时写入初始化记录，而非空文件\n\n建议 E5: 版本命名空间分离\n 明确 sync 版本（sync-vX.Y）与系统版本（system-vX.Y）的独立性\n```\n\n---\n\n## 附录 A: v1.1 评估问题解决状态\n\n| v1.1 问题 | v1.2 解决? | v1.3 状态 |\n|-----------|:---:|------|\n| Agent 名称硬编码遍布全库 | ✅ Registry single source of truth | 已解决 |\n| init_sync.sh 无 dry-run | ✅ --dry-run | 已解决 |\n| 无 --help | ✅ -h/--help | 已解决 |\n| 无英文 Quickstart | ✅ quickstart.md | 已解决 |\n| 脚本全中文 | ✅ --lang en\\|zh | 已解决 |\n| SKILL.md 场景 A/B 绑定特定 agent | ✅ 用变量和通用描述替代 | 已解决 |\n| sync-journal.md 全中文 | ❌ 仍为中文 | 未解决 |\n| pending-sync-template.md 中文 | ❌ 仍为中文 | 未解决 |\n| 路径硬编码 | ⚠️ 通过 registry vars 可配 | 部分解决 |\n| force_sync.sh 不备份 CHANGELOG | ❌ | 未解决 |\n| 无 demo 模式 | ✅ --demo | 已解决 |\n| 增加第5个 agent 需改多处 | ✅ 只改 registry JSON | 已解决 |\n\n---\n\n## 附录 B: 测试数据\n\n### Registry 解析测试\n```\n$ json_val \"vars.workspace_root\" agent-registry.json\n~/.openclaw ✓\n$ json_val \"vars.master_agent\" agent-registry.json\namaster ✓\n$ resolve_vars \"${vars.workspace_root}/workspace-acode\"\n~/.openclaw/workspace-acode ✓\n```\n\n### init_sync.sh --dry-run 输出\n```\nMaster 工作空间: /home/admin/.openclaw/workspace-amaster\nAgent 'acode' 已配置 ✓\nAgent 'ainvest' 已配置 ✓\nAgent 'alive' 已配置 ✓\n```\n\n### 部署环境文件状态\n```\n.current_system_version → v3.1\n.last_sync_version → v3.1 \n.sync_journal.jsonl → 0 bytes\nCHANGELOG.md → quant system full changelog\n```\n\nFile v1.5.1:reports/repair-log.md\n\n# agent-config-sync 本地部署修复日志\n\n**修复日期**: 2026-05-16 10:30 CST\n**执行人**: acode (大师)\n**参考报告**: agent-config-sync-eval-v1.3.md §6.2 修复路线图\n**量化系统版本**: v3.2\n**同步系统版本**: v1.5 (v1.4 冲突管理 + v1.5 使用向导)\n\n---\n\n## 历次变更摘要\n\n### v1.5 — 使用向导 + 开包即用 + GitHub 发布准备 (2026-05-16 13:00 CST)\n\n#### 新增文件\n\n| 文件 | 描述 | 状态 |\n|:-----|:-----|:--:|\n| `scripts/wizard.sh` | 交互式安装向导（纯 bash, 中英双语, --auto 模式） | ✅ |\n| `README.md` | GitHub 项目 README（完整英文文档） | ✅ |\n\n#### 修改文件\n\n| 文件 | 变更 | 状态 |\n|:-----|:-----|:--:|\n| `_meta.json` | 版本 1.4.0 → 1.5.0 | ✅ |\n| `scripts/init_sync.sh` | 新增 `--auto` 模式 + 自动检测 workspace 并生成 registry | ✅ |\n| `scripts/init_sync.sh` | SYNC.md 模板增强（新手上路指南 + 常用操作速查表） | ✅ |\n| `SKILL.md` | 顶部新增 Quick Start 章节，安装章节新增 Option A/B（wizard/auto） | ✅ |\n| `SKILL.md` | Files 表格新增 wizard.sh 条目 | ✅ |\n| `references/agent-registry.json` | 版本 1.4.0 → 1.5.0（quote 改双引号） | — |\n\n#### wizard.sh 功能详情\n\n| Step | 功能 | 实现方式 |\n|:-----|:-----|:-----|\n| Step 1 | 检测环境 | 检查 openclaw 命令 + 扫描 ~/.openclaw/workspace-* + 读取 IDENTITY.md |\n| Step 2 | 配置注册表 | 自动生成 agent-registry.json，供用户确认/编辑 |\n| Step 3 | 运行初始化 | 自动调用 init_sync.sh --confirm |\n| Step 4 | HEARTBEAT 集成 | 自动追加 item 12 到 master HEARTBEAT.md |\n| Step 5 | 完成报告 | 显示哨兵状态 + Agent 就绪状态 + 下一步指南 |\n\n#### 特性\n\n- `wizard.sh --auto`: 全自动检测，无需交互，2 分钟内完成安装\n- `wizard.sh --lang en|zh`: 完整中英双语支持\n- `wizard.sh --skip 1,4`: 可选跳过任意步骤\n- `init_sync.sh --auto`: 一键初始化（自动检测 workspace，生成 registry，跳过确认）\n- SYNC.md 新增「新手上路指南」和「常用操作速查表」\n- 所有改动增量式，完全兼容 v1.4\n\n#### 集成验证结果\n\n```\n$ bash scripts/wizard.sh --auto --lang en\n== agent-config-sync v1.5 — Auto Setup ==\n── Step 1/5: Detect Environment ✅\n── Step 2/5: Configure Agent Registry ✅ (5 agents)\n── Step 3/5: Initialize Sync Infrastructure ✅\n── Step 4/5: Integrate HEARTBEAT ✅\n── Step 5/5: Completion Report ✅\n\n$ bash scripts/init_sync.sh --auto --dry-run --lang en \n=== Agent Config Sync v1.5 — Initialization ===\n🤖 AUTO MODE — all good\n```\n\n---\n\n### v1.4 — 版本冲突管理全量优化 (2026-05-16 11:30 CST)\n\n**设计依据**: `/home/admin/.openclaw/workspace-amaster/skills/agent-config-sync/reports/version-conflict-management-design.md`\n\n#### Phase 1: 基础增强 ✅\n\n| ID | 任务 | 文件 | 状态 |\n|:---|:-----|:-----|:--:|\n| P1.1 | pending_sync 模板增加 TTL/过期时间/前置字段 | `references/pending-sync-template.md` | ✅ |\n| P1.2 | 每个 agent 增加 `.agent_sync_version` 文件 | `scripts/init_sync.sh` | ✅ |\n| P1.3 | 原子写入 `_atomic_write()` | `scripts/force_sync.sh`, `scripts/init_sync.sh` | ✅ |\n| P1.4 | SECURITY.md 新增 Version Conflict Scenarios | `SECURITY.md` | ✅ |\n| P1.5 | SKILL.md 新增 Version Conflict Management 章节 | `SKILL.md` | ✅ |\n\n#### Phase 2: 核心冲突处理 ✅\n\n| ID | 任务 | 文件 | 状态 |\n|:---|:-----|:-----|:--:|\n| P2.1 | CHANGELOG 新增 depends_on / 协同依赖 可选字段 | `references/sync-setup.md` | ✅ |\n| P2.2 | Agent 端版本折叠逻辑 (Agent-side Version Collapse) | `SKILL.md` | ✅ |\n| P2.3 | Master 端分发锁 (dispatch lock + timeout logic) | `references/sync-setup.md` | ✅ |\n| P2.4 | 离线追赶包 (offline catch-up) | `references/sync-setup.md`, `SKILL.md` | ✅ |\n| P2.5 | 循环检测 (loop detection) | `references/sync-setup.md`, `references/sync-journal.md` | ✅ |\n| P2.6 | HEARTBEAT item 12 伪代码重写 (v1.4 增强版) | `references/sync-setup.md` | ✅ |\n\n#### Phase 3: 高级场景处理 ✅\n\n| ID | 任务 | 文件 | 状态 |\n|:---|:-----|:-----|:--:|\n| P3.1 | 自身升级隔离 (self_protect + isolated_sync) | `references/agent-registry.json`, `SKILL.md`, `SECURITY.md` | ✅ |\n| P3.2 | 批量合入 (batch mode + batch_window_sec) | `references/agent-registry.json`, `SKILL.md`, `references/sync-setup.md` | ✅ |\n| P3.3 | 回滚机制 (snapshots + revert manifest) | `references/sync-setup.md`, `SKILL.md`, `SECURITY.md` | ✅ |\n| P3.4 | HEARTBEAT item 12 v1.4 完整文本 | `references/sync-setup.md` | ✅ (含 P2.6) |\n| P3.5 | 集成验证 (`init_sync.sh --dry-run`) | 全部通过 | ✅ |\n\n#### 版本与元数据\n\n| 文件 | 旧值 | 新值 |\n|:-----|:-----|:-----|\n| `_meta.json` → version | `1.3.0` | `1.4.0` |\n| `agent-registry.json` → version | `1.2.1` | `1.4.0` |\n| `init_sync.sh` → title | v1.2 | v1.4 |\n| `force_sync.sh` → title | v1.2 | v1.4 |\n| `SKILL.md` → header | v1.2 | v1.4 |\n| `pending-sync-template.md` → header | v1.1 | v1.4 |\n| `.sync_own_version` | (不存在) | v1.4 |\n| HEARTBEAT marker | v1.2 | v1.4 |\n| BOOTSTRAP check | v1.2 (basic) | v1.4 (TTL + catch-up + isolated) |\n\n#### 新建文件\n\n| 文件 | 内容 |\n|:-----|:-----|\n| `skills/agent-config-sync/.sync_own_version` | `v1.4` |\n| `workspace-{agent}/memory/.agent_sync_version` (×4) | `v1.1` |\n| `workspace-{agent}/memory/.sync_snapshots/` (×4) | 空目录 |\n\n#### 集成验证结果\n\n```\n$ bash scripts/init_sync.sh --dry-run --lang zh\n=== Agent Config Sync v1.4 — 初始化 ===\nMaster 工作空间: /home/admin/.openclaw/workspace-amaster\nℹ️ 版本文件已存在，跳过创建\nℹ️ all agents up-to-date\n✅ 所有 agent 已配置\n=== 初始化完成 ===\n\n✅ .agent_sync_version 存在于所有 agent + master\n✅ .sync_snapshots 目录存在于所有 agent + master\n✅ .sync_own_version = v1.4\n✅ _meta.json version = 1.4.0\n✅ force_sync.sh --dry-run 正常（原子写入预览）\n```\n\n---\n\n### v1.2 → v1.1: 初始部署 (2026-05-16 10:30 CST)\n\n### Phase 1: 下游 Agent 重复条目清理 ✅\n\n#### P1.1 — BOOTSTRAP.md 去重\n| 文件 | 删除内容 | 保留内容 | 状态 |\n|------|----------|----------|:--:|\n| `workspace-acode/BOOTSTRAP.md` | v1.1 段 (`pending_sync.md` 单数 + 量化版本确认) | v1.2 段 (`pending_sync_*.md` glob) | ✅ |\n| `workspace-ainvest/BOOTSTRAP.md` | 同上 | 同上 | ✅ |\n| `workspace-alive/BOOTSTRAP.md` | 同上 | 同上 | ✅ |\n\n**识别特征**: v1.1 段含 `pending_sync.md`（单数，无通配符）+ \"使用量化系统/比价系统前先确认版本\"\n\n#### P1.2 — HEARTBEAT.md 去重\n| 文件 | 删除内容 | 保留内容 | 状态 |\n|------|----------|----------|:--:|\n| `workspace-acode/HEARTBEAT.md` | v1.1 段 (`pending_sync.md` 单数，无 marker) | v1.2 段 (`` marker) | ✅ |\n| `workspace-ainvest/HEARTBEAT.md` | 同上 | 同上 | ✅ |\n| `workspace-alive/HEARTBEAT.md` | 同上 | 同上 | ✅ |\n\n**识别特征**: v1.1 段无 `agent-config-sync-check` marker 且检查 `pending_sync.md` 单数\n\n---\n\n### Phase 2: Master Agent 升级 ✅\n\n#### P2.1 — 升级 HEARTBEAT item 12\n| 文件 | 变更 |\n|------|------|\n| `workspace-amaster/HEARTBEAT.md` | item 12 从 v1.1 升级到 v1.2 |\n\n**具体变更**:\n- `pending_sync.md` (单数) → `pending_sync__.md` (复用模式)\n- 硬编码 agent 名 \"大师/元宝/牛奶\" → `agent-registry.json` 动态读取\n- 新增: SHA256 签名生成步骤\n- 新增: `.sync_journal.jsonl` 记录（含 timestamp/version/agent dispatch 状态）\n- 新增: 重试逻辑（检查 `status=prepared` 记录）\n- 日志目标: `MEMORY.md` → `.sync_journal.jsonl`\n- 变更章节读取: \"全量 CHANGELOG\" → \"最新版本变更章节（非全量）\"\n\n#### P2.2 — CHANGELOG 分离\n| 操作 | 文件 |\n|------|------|\n| 重命名 | `CHANGELOG.md` → `CHANGELOG_quant.md` |\n| 新建 | `CHANGELOG.md` (sync 标准结构化格式) |\n\n**新 CHANGELOG.md 格式**: 按 `sync-setup.md` 规范，含 `**变更类型**` / `**影响范围**` / `**变更人**` / `**紧急程度**` 字段\n\n#### P2.3 — 初始化 sync 哨兵\n| 文件 | 值 | 说明 |\n|------|:--:|------|\n| `.current_system_version` | v1.0 | sync 系统版本（独立于量化系统 v3.2） |\n| `.last_sync_version` | v1.0 | 与 current 一致（初始状态） |\n\n---\n\n### Phase 3: 参考文件修正 ✅\n\n#### P3.1 — quickstart.md 文件引用修正\n| 文件 | 变更 |\n|------|------|\n| `skills/agent-config-sync/references/quickstart.md` | `.agent_registry` → `agent-registry.json` (3处) |\n\n#### P3.2 — Master HEARTBEAT pending_sync.md 缓存修复\n| 文件 | 说明 |\n|------|------|\n| `workspace-amaster/HEARTBEAT.md` | 已在 P2.1 中一并修正，不再使用 `pending_sync.md` 单数格式 |\n\n---\n\n## 验证结果\n\n### init_sync.sh --dry-run --lang zh\n```\n🔍 预览模式 — 不会执行任何修改\n=== Agent Config Sync v1.2 — 初始化 ===\nMaster 工作空间: /home/admin/.openclaw/workspace-amaster\nℹ️ 版本文件已存在，跳过创建\nℹ️ acode/SYNC.md 已是最新，跳过\nℹ️ acode/BOOTSTRAP.md 已有同步检查\nℹ️ acode/HEARTBEAT.md 已有同步检查\n✅ Agent 'acode' 已配置\nℹ️ ainvest/SYNC.md 已是最新，跳过\nℹ️ ainvest/BOOTSTRAP.md 已有同步检查\nℹ️ ainvest/HEARTBEAT.md 已有同步检查\n✅ Agent 'ainvest' 已配置\nℹ️ alive/SYNC.md 已是最新，跳过\nℹ️ alive/BOOTSTRAP.md 已有同步检查\nℹ️ alive/HEARTBEAT.md 已有同步检查\n✅ Agent 'alive' 已配置\n=== 初始化完成 ===\n```\n\n✅ 全部通过，无错误。\n\n### 下游文件验证（grep 确认）\n| 文件 | pending_sync 引用数 | 仅 v1.2 格式 |\n|------|:---:|:--:|\n| acode/BOOTSTRAP.md | 1 | ✅ |\n| ainvest/BOOTSTRAP.md | 1 | ✅ |\n| alive/BOOTSTRAP.md | 1 | ✅ |\n| acode/HEARTBEAT.md | 1 (含 marker) | ✅ |\n| ainvest/HEARTBEAT.md | 1 (含 marker) | ✅ |\n| alive/HEARTBEAT.md | 1 (含 marker) | ✅ |\n\n---\n\n## 未完成项 & 需确认\n\n### 需 Leon 确认\n1. **版本命名空间独立**: 量化系统 v3.2 与 sync 系统 v1.0 分开计数。当前 `.current_system_version` 和 `.last_sync_version` 都设为 `v1.0`。如果希望保留跨系统统一版本号，请告知。\n2. **CHANGELOG_quant.md**: 原始量化系统完整履历已归档到此文件，新 `CHANGELOG.md` 为 sync 格式。确认此分离方式 OK？\n3. **HEARTBEAT item 12 语义**: 新格式增加了 SHA256 签名、journal 记录、重试逻辑。AMaster 下次 heartbeat 时将按新格式执行。确认无误？\n\n### 评估报告 G6 (agent-setup.md 过期)\n- 该文件仍为 v1.1 格式内容，但 `init_sync.sh` 不实际使用它（仅人工参考）。\n- 如需修复留待 Phase 4 处理。\n\n### 评估报告建议 E1-E5 (v1.4)\n- 未执行，留待后续迭代。\n\nArchive v1.5.0: 18 files, 91294 bytes\n\nFiles: _meta.json (136b), README.md (7044b), references/agent-registry.json (1600b), references/agent-setup.md (1662b), references/pending-sync-template.md (3371b), references/quickstart.md (5364b), references/sync-journal.md (4938b), references/sync-setup.md (23613b), reports/agent-config-sync-eval-v1.1.md (6967b), reports/agent-config-sync-eval-v1.3.md (14685b), reports/repair-log.md (10879b), reports/version-conflict-management-design.md (45852b), scripts/force_sync.sh (9464b), scripts/init_sync.sh (31189b), scripts/revert_sync.sh (25279b), scripts/wizard.sh (40603b), SECURITY.md (6413b), SKILL.md (28892b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: agent-config-sync\ndescription: |-\n Synchronize configuration versions across OpenClaw multi-agent deployments.\n Tracks changes in a master workspace using sentinel version files and CHANGELOG,\n then dispatches to downstream agents via sessions_send or file-based pending_sync\n fallback. Each agent independently checks for updates on startup (BOOTSTRAP.md)\n and heartbeat (HEARTBEAT.md). Designed for users running 2+ specialized agents\n who need consistent system/agent/OpenClaw configurations.\n Triggers on: sync, configure, version management, multi-agent coordination.\n---\n\n# Agent Config Sync (v1.5)\n\nKeep configuration consistent across multiple OpenClaw agents using version tracking, CHANGELOG-based change detection, and automatic sync dispatch with journal-backed two-phase commit.\n\n> **⚡ Quick Start (30 seconds to running):**\n> ```bash\n> # Step 1: Install\n> clawhub install agent-config-sync\n>\n> # Step 2: Run setup wizard (interactive, no manual editing needed)\n> cd ~/.openclaw/skills/agent-config-sync\n> bash scripts/wizard.sh\n>\n> # Step 3: Done! 🎉\n> # - Agent registry auto-detected\n> # - Sync infrastructure created\n> # - HEARTBEAT integration added\n> # - All agents ready to receive syncs\n> ```\n> \n> **Non-interactive?** Use `bash scripts/wizard.sh --auto` to auto-detect everything.\n> \n> **Prefer manual?** See [Installation](#installation) below for step-by-step instructions.\n>\n> **New in v1.5**: Interactive setup wizard (`scripts/wizard.sh`), `--auto` mode for init_sync.sh (zero-config auto-detection), enhanced SYNC.md with quick start guide and cheat sheet, simplified onboarding.\n>\n> **New in v1.4**: Full version conflict management — dispatch lock, loop detection, self-upgrade isolation, batch mode, rollback snapshots, TTL-based expiry, offline catch-up, and agent-side version collapse. See [Version Conflict Management](#version-conflict-management-v14) for details.\n>\n> **Security**: This skill writes to agent workspaces across your OpenClaw deployment. Read the full [SECURITY.md](SECURITY.md) for permission scope, path validation, cross-agent isolation, and user consent flow. Key highlights:\n> - All scripts require `--confirm` for write operations (use `--dry-run` to preview first)\n> - Only paths under `~/.openclaw/workspace-*` are allowed (path validation enforced)\n> - Each agent can only read/write its own workspace files\n> - No network access, no external API calls, no credential access\n\n## ⚙️ Customization Variables\n\n**Option A (Recommended): Run the setup wizard**\n```bash\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n```\nThe wizard auto-detects your agents and generates `agent-registry.json` — no manual editing.\n\n**Option B: Manual configuration**\n\nEdit `references/agent-registry.json` — this is the only file you need to change for your deployment:\n\n| Variable | Location | Example | Description |\n|----------|----------|---------|-------------|\n| `workspace_root` | `vars` in registry | `~/.openclaw` | Base path for all agent workspaces |\n| `master_agent` | `vars` in registry | `amaster` | ID of your coordination/master agent |\n| `master_memory` | `vars` in registry | `${workspace_root}/workspace-amaster/memory` | Path to master's memory directory |\n| (each agent) | `agents` in registry | See below | Add/remove/rename agents to match your setup |\n\n**Example** — after customization for user \"Alice\" with agents `alice-dev`, `alice-biz`, `alice-ops`:\n\n```json\n{\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"alice-ops\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"alice-dev\": { \"name\": \"Alice Dev\", \"role\": \"Development\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-dev\" },\n \"alice-biz\": { \"name\": \"Alice Biz\", \"role\": \"Business\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-biz\" },\n \"alice-ops\": { \"name\": \"Alice Ops\", \"role\": \"Coordination\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-ops\" }\n }\n}\n```\n\nScripts resolve `${vars.xxx}` placeholders at runtime — no hardcoded paths.\n\n---\n\n## Overview\n\n### Architecture\n\n```\n┌─ Version Tracking ──────────────────────┐\n│ .current_system_version (monotonic) │\n│ .last_sync_version (last synced) │\n│ CHANGELOG.md (structured) │\n│ .sync_journal.jsonl (atomicity) │\n└──────────────────────────────────────────┘\n │ version mismatch detected by HEARTBEAT\n ▼\n┌─ Sync Journal (two-phase commit) ────────┐\n│ PREPARE → journal entry written │\n│ DISPATCH → sessions_send / pending_sync │\n│ COMMIT → mark done or retry later │\n└──────────────────────────────────────────┘\n │ each agent processes independently\n ▼\n┌─ Agent Side ────────────────────────────┐\n│ BOOTSTRAP.md → ls pending_sync_*.md │\n│ HEARTBEAT.md → check + verify SHA256 │\n│ SYNC.md → manual sync instructions │\n└──────────────────────────────────────────┘\n```\n\n### What it syncs\n\n| Type | Examples |\n|:----:|----------|\n| 🖥️ System code | Quant system, price compare, data pipelines |\n| 🤖 Agent config | SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md |\n| ⚙️ OpenClaw config | Models, skills, service addresses, plugins |\n| 🎯 Task config | API keys, cron jobs, data sources, ports |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- OpenClaw with 2+ agents\n- One designated \"master\" coordination agent\n- `clawhub` CLI installed\n\n### Option A: Interactive Wizard (Recommended for New Users)\n\n```bash\nclawhub install agent-config-sync\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n```\n\nThe wizard walks you through:\n1. Environment detection (auto-finds your agents)\n2. Registry configuration (auto-generates from your workspace)\n3. Infrastructure initialization (one click)\n4. HEARTBEAT integration (auto-appended)\n5. Completion report (status summary + next steps)\n\n### Option B: One-Command Auto Setup\n\n```bash\nclawhub install agent-config-sync\nbash ~/.openclaw/skills/agent-config-sync/scripts/init_sync.sh --auto\n```\n\nAuto-detects all agent workspaces, generates registry, and initializes everything — zero prompts.\n\n### Option C: Manual Step-by-Step\n\n#### Step 1: Install the Skill\n\n```bash\nclawhub install agent-config-sync\n```\n\n#### Step 2: Customize Agent Registry\n\nEdit `~/.openclaw/skills/agent-config-sync/references/agent-registry.json`:\n\n1. Change `vars.master_agent` to your coordination agent's ID\n2. Replace the `agents` entries with your own agents\n3. Adjust `vars.workspace_root` if your OpenClaw workspace is not `~/.openclaw`\n\nSee the [Customization Variables](#️-customization-variables) table above, or the English quickstart at `references/quickstart.md`.\n\n#### Step 3: Initialize Sync Infrastructure\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview what will be created (safe, no changes required)\nbash scripts/init_sync.sh --dry-run\n\n# Run the real setup (--confirm required for write operations)\nbash scripts/init_sync.sh --confirm\n```\n\n> ⚠️ **Safety**: `--confirm` is **required** for any write operation. Without it, the script exits with a prompt explaining how to preview with `--dry-run` first. `--dry-run` mode does not need `--confirm`.\n\nThis creates:\n- Version sentinel files (`.current_system_version`, `.last_sync_version`) in master's `memory/`\n- `CHANGELOG.md` with structured format\n- `.sync_journal.jsonl` for sync atomicity\n- `SYNC.md`, bootstrapped `BOOTSTRAP.md`, and `HEARTBEAT.md` sync checks in each agent workspace\n\n#### Step 4: Add HEARTBEAT Item to Master Agent\n\nCopy the HEARTBEAT item from `references/sync-setup.md` into your master agent's `HEARTBEAT.md`. This is **item 12** — the heartbeat check that detects version mismatches and dispatches syncs.\n\n#### Step 5: Verify Setup\n\n```bash\n# Check version files\ncat ~/.openclaw/workspace-/memory/.current_system_version # should be v1.0\n\n# Check agent sync files\nls ~/.openclaw/workspace-*/SYNC.md\n```\n\n---\n\n## Version Conflict Management (v1.4)\n\n### Conflict Types\n\n| Type | Scenario | Frequency | Impact |\n|:-----|:---------|:---------:|:------:|\n| **Concurrent Change** | Two agents submit version changes simultaneously | High | Medium |\n| **Cross-Session Stale** | Agent restarts and finds outdated `pending_sync` files | Medium | Low |\n| **Offline Catch-Up** | Agent misses one or more sync cycles | Medium | High |\n| **Self-Reference (Self-Upgrade)** | agent-config-sync's own files need updating | Low | High |\n| **Multi-Agent Coordination** | Change requires specific ordering across agents | Medium | Medium |\n| **Rollback** | Need to revert a problematic version change | Low | High |\n\n### Conflict Detection Mechanisms\n\n| Mechanism | Location | What It Detects |\n|:----------|:---------|:----------------|\n| Version Sentinel Comparison | Master HEARTBEAT item 12 | `.current_system_version` ≠ `.last_sync_version` |\n| Dispatch Lock | Master HEARTBEAT item 12 | Concurrent dispatch prevention (< 2min window) |\n| Loop Detection | Master HEARTBEAT item 12 | 3+ consecutive same-version journal records |\n| TTL Expiry Check | Agent BOOTSTRAP/HEARTBEAT | `now > 过期时间` → delete stale pending_sync |\n| Version Folding | Agent side | Multiple `pending_sync_*.md` files → fold by version |\n| `.agent_sync_version` Gap | Agent side | Local version < current system version → offline gap |\n| Self-Protect Blacklist | Master dispatch | CHANGELOG impact range includes sync's own files |\n| Snapshot Verification | Agent rollback | SHA256 checksums on restored files |\n\n### Agent-Side Pending Sync Priority Matrix\n\nWhen an agent discovers multiple `pending_sync_*.md` files, it processes them in this order:\n\n```\nPriority Type Handle\n───────── ──────────────── ──────────────────────────────\n1 (first) Expired files Delete immediately (now > 过期时间)\n2 Superseded files Delete (lower version number, depends_on chain covered)\n3 Isolated syncs Must process before normal syncs (self-upgrade isolation)\n4 Revert syncs Revert to target version from snapshot\n5 (last) Normal syncs Apply in version order, respecting depends_on chain\n```\n\n**Version Collapse Rule**: If multiple `pending_sync_v3.1`, `pending_sync_v3.2`, `pending_sync_v3.3` exist AND v3.3's `**前置**` chain covers all intermediate versions → apply only v3.3 and delete v3.1/v3.2.\n\n### Version Folding Algorithm\n\n```\nAgent discovers pending_sync_*.md files:\n\n1. 删除已过期的文件（生成时间 > TTL，默认 24h）\n2. 删除已被 supersede 的文件（版本号更低，且被更新版本的 depends_on 链覆盖）\n3. 对剩余文件按版本号排序 → 从最早的开始执行\n4. 如果文件头包含 \"前置\" 依赖 → 先检查前置是否已处理\n - 若前置未处理 → 按依赖链逐步升级\n - 若前置已处理 → 可直接应用\n5. 应用变更前创建前置快照（memory/.sync_snapshots/_pre/）\n6. 应用变更后更新 .agent_sync_version\n7. 删除已处理的 pending_sync 文件\n```\n\n---\n\n## Agent-Side Version Collapse (v1.4)\n\n### Overview\n\nWhen an agent discovers multiple `pending_sync_*.md` files (e.g., after being offline or during a period of rapid changes), it uses version collapse to avoid processing every intermediate version. The goal is to safely \"jump\" from the agent's current version to the latest applicable version in a single step.\n\n### Decision Flow\n\n```\nAgent discovers N pending_sync_*.md files (N ≥ 1):\n\n1. PARSE all file headers:\n - Extract: 版本, 前置, 生成时间, 过期时间, 类型\n\n2. CLEANUP expired:\n FOR EACH file:\n IF now > 过期时间:\n DELETE file\n LOG \"Stale sync expired: \"\n\n3. DETECT superseded:\n SORT remaining files by 版本 DESC\n FOR EACH file from latest to earliest:\n Walk depends_on chain from latest version\n IF current version is in chain → all older files are superseded\n DELETE all files whose version < latest_version AND covered by chain\n\n4. CLASSIFY remaining files:\n GROUP by 类型:\n - isolated_sync → process BEFORE normal syncs\n - revert_sync → restore from snapshot\n - pending_sync → normal version upgrade\n\n5. ORDER execution:\n isolated_sync files (ascending version)\n ↓\n revert_sync files (ascending target version)\n ↓\n normal pending_sync files (ascending version, respecting depends_on chain)\n\n6. EXECUTE each file:\n a. CHECK depends_on: IF 前置 > .agent_sync_version → ERROR (chain broken, request Master)\n b. CREATE snapshot: mkdir .sync_snapshots/_pre/ + backup affected files\n c. APPLY changes from CHANGELOG\n d. UPDATE .agent_sync_version = 版本\n e. DELETE processed file\n\n7. VERIFY:\n Check .agent_sync_version matches latest processed version\n Confirm no remaining pending_sync files (or that remaining files have valid depends_on > current)\n```\n\n### Version Comparison\n\n```\nVersion format: v.[.]\n\nis_newer(\"v3.2\", \"v3.1\") → true (MINOR increment)\nis_newer(\"v3.2.1\", \"v3.2\") → true (PATCH increment)\nis_newer(\"v3.1\", \"v3.2\") → false\nis_newer(\"v4.0\", \"v3.9\") → true (MAJOR increment)\nis_same(\"v3.1\", \"v3.1\") → true\n```\n\n### Edge Cases\n\n| Case | Behavior |\n|------|----------|\n| Single pending file | Direct application (no collapse needed) |\n| Chain broken (v3.1, v3.3 but no v3.2 dependency) | Process v3.1 first, then v3.3 |\n| Chain complete (v3.1 depends v3.0; v3.3 depends v3.1) | Jump directly to v3.3 |\n| Mixed types (pending + revert) | Revert takes priority; if revert target > current, normal syncs after |\n| Corrupt file (unparseable header) | Skip, log error, request Master re-dispatch |\n| Same version, 2 files (duplicate) | Keep newest by 生成时间, delete older |\n\n---\n\n## Self-Upgrade Isolation (v1.4)\n\n### Problem\n\nagent-config-sync's own files (SKILL.md, scripts/, SECURITY.md, etc.) may need updating. But if the sync system dispatches changes to itself through normal channels, it can trigger self-referential sync loops.\n\n### Solution: Isolated Sync Flow\n\nWhen a CHANGELOG entry's impact range includes paths in the `self_protect.blacklist`:\n\n1. **Detection**: Master HEARTBEAT item 12 checks if the change affects agent-config-sync itself\n2. **Isolation**: Generates `isolated_sync__.md` in Master's `memory/` directory\n3. **Notification**: Appends a notice to each agent's `BOOTSTRAP.md` (not dispatched via normal flow)\n4. **Agent Action**: On next startup, agent detects the BOOTSTRAP notice and requests the isolated sync\n5. **No sentinel file**: Does not use `pending_sync` file mechanism — avoids normal dispatch loop\n\n### Configuration\n\nConfigured in `agent-registry.json`:\n\n```json\n\"self_protect\": {\n \"enabled\": true,\n \"skip_agents\": [\"agent-config-sync\"],\n \"isolated_sync\": true,\n \"blacklist\": [\"HEARTBEAT.md\", \"BOOTSTRAP.md\", \"SKILL.md\", \"scripts/\", \"SECURITY.md\", \"references/\"],\n \"sync_own_version_file\": \"skills/agent-config-sync/.sync_own_version\",\n \"allow_bootstrap_only\": true\n}\n```\n\n### Self-Protect Blacklist\n\nPaths listed in `blacklist` are quarantined from normal dispatch. Any CHANGELOG entry affecting these paths triggers the isolated sync flow instead.\n\n---\n\n## Batch Mode (v1.4)\n\n### Overview\n\nWhen multiple rapid changes occur within a time window, batch mode merges them into a single cumulative dispatch instead of triggering one sync per version.\n\n### Configuration\n\n```json\n\"batch\": {\n \"mode\": \"auto\",\n \"window_sec\": 300\n}\n```\n\n### Behavior\n\n1. HEARTBEAT detects version mismatch\n2. Instead of immediate dispatch, opens a batch window (default: 5 min)\n3. All version bumps within the window are accumulated\n4. When window closes → merge all changes into one `pending_sync` file\n5. Uses highest version number among batched changes\n6. Combines all CHANGELOG sections\n\n### Merge Rules\n\n- Sort all batched versions → use the highest version\n- Concatenate CHANGELOG entries in version order\n- Generate single SHA256 signature over combined content\n- Single dispatch covers all intermediate changes\n\n---\n\n## Rollback Mechanism (v1.4)\n\n### Overview\n\nWhen a version change causes problems, the system supports controlled rollback to a previous version using pre-sync snapshots.\n\n### Rollback Flow\n\n```\n1. TRIGGER (Master):\n - Set .current_system_version to the rollback target version\n - HEARTBEAT detects: current < last_sync → recognizes as rollback\n - Creates revert_sync__to__.md in each agent workspace\n\n2. APPLY (Agent):\n - Detects revert_sync file on HEARTBEAT/BOOTSTRAP check\n - Restores files from memory/.sync_snapshots/_pre/\n - Verifies SHA256 checksums from snapshot_manifest.json\n - Updates .agent_sync_version to target version\n - Deletes revert_sync file\n\n3. VERIFY (All):\n - .current_system_version == .last_sync_version (stable state)\n - No pending_sync or revert_sync files remain\n```\n\n### Snapshot Directory Structure\n\n```\nmemory/.sync_snapshots/\n├── v3.2_pre/\n│ ├── TOOLS.md.bak\n│ ├── SOUL.md.bak\n│ ├── AGENTS.md.bak\n│ └── snapshot_manifest.json\n└── v3.3_pre/\n ├── config.json.bak\n └── snapshot_manifest.json\n```\n\n### snapshot_manifest.json Format\n\n```json\n{\n \"sync_version\": \"v3.2\",\n \"snapshot_time\": \"2026-05-16T08:30:00Z\",\n \"previous_version\": \"v3.1\",\n \"files\": {\n \"TOOLS.md\": \"sha256:a1b2c3...\",\n \"SOUL.md\": \"sha256:d4e5f6...\"\n }\n}\n```\n\n### Rollback Safety\n\n- **Pre-condition**: Agent must have a snapshot directory matching the target rollback version\n- **SHA256 verification**: All restored files verified against snapshot manifests\n- **No partial rollback**: Atomic restore (all files succeed or none)\n- **Loop prevention**: Rollback records are `type=revert` — not re-triggered by normal dispatch\n- **Manual confirmation**: Requires explicit version bump to trigger\n\n---\n\n## Configuration\n\n### Agent Registry (`references/agent-registry.json`)\n\nThe single source of truth. Fields:\n\n| Field | Description |\n|-------|-------------|\n| `vars.workspace_root` | Root directory for all agent workspaces |\n| `vars.master_agent` | ID of the coordination agent (sends syncs) |\n| `vars.master_memory` | Path to master's memory directory (uses placeholders) |\n| `agents..name` | Display name (English) |\n| `agents..name_zh` | Display name (Chinese) — optional |\n| `agents..role` | Short role description |\n| `agents..workspace` | Path to agent workspace (uses `${vars.workspace_root}`) |\n| `sync.*` | Sync behavior config (sentinel filenames, prefix, limits) |\n\n### CHANGELOG Format\n\nAll version entries must follow the structured format defined in `references/sync-setup.md`:\n\n```markdown\n## vX.Y (YYYY-MM-DD)\n**Change Type**: \n**Affected Agents**: \n**Author**: \n**Priority**: normal | high | critical\n\n### Added / Changed / Deprecated\n- \n```\n\n### Language\n\nScripts support `--lang en` and `--lang zh` (default). Use `--lang en` for English output:\n\n```bash\nbash scripts/init_sync.sh --lang en\nbash scripts/force_sync.sh --lang en ~/memory v1.0 v1.1\n```\n\n---\n\n## Usage Scenarios\n\n### Scenario A: Adding a new model to all agents\n\n**Situation**: You want all agents to switch to a new default model.\n\n1. Update `CHANGELOG.md` in master's memory directory:\n ```markdown\n ## v3.2 (2026-05-16)\n **Change Type**: ⚙️ OpenClaw Config\n **Affected Agents**: all\n **Author**: AMaster\n **Priority**: high\n\n ### Changed\n - Default model switched to deepseek-v4-pro for all agents\n - Fallback model set to deepseek-v3\n ```\n\n2. Bump the version:\n ```bash\n echo \"v3.2\" > memory/.current_system_version\n ```\n\n3. Next HEARTBEAT (every 5 min): version mismatch detected → dispatches to all agents. Agents update their model configs accordingly.\n\n4. Agents delete their `pending_sync_v3.2_.md` after applying.\n\n### Scenario B: Coordinated code deployment\n\n**Situation**: You fix a bug in shared code used by multiple agents.\n\n1. Fix the bug, tell the master agent to record the change.\n\n2. Master updates `CHANGELOG.md` with the version entry, bumps `.current_system_version`.\n\n3. HEARTBEAT dispatches. Online agents receive via `sessions_send`; offline agents get `pending_sync` files.\n\n4. All agents verify version before running the shared system.\n\n---\n\n## Daily Operations\n\n### Recording a Change\n\nWhenever a config or system change affects multiple agents:\n\n1. **Edit `CHANGELOG.md`** in master's `memory/` directory — add a new `## vX.Y` section\n2. **Bump the version** — `echo \"vX.Y\" > memory/.current_system_version`\n3. The change is dispatched automatically on the next master heartbeat\n\n### Force-Syncing Immediately\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview the version change\nbash scripts/force_sync.sh --dry-run ~/.openclaw/workspace-/memory v3.0 v3.1\n\n# Execute (--confirm required for write operations)\nbash scripts/force_sync.sh --confirm ~/.openclaw/workspace-/memory v3.0 v3.1\n```\n\nAfter running, the next heartbeat detects `current (v3.1) != last_sync (v3.0)` and dispatches.\n\n### Checking Sync Status\n\n```bash\n# Check version sentinel files\ncat ~/.openclaw/workspace-/memory/.current_system_version\ncat ~/.openclaw/workspace-/memory/.last_sync_version\n\n# Check journal for recent sync records\ntail -5 ~/.openclaw/workspace-/memory/.sync_journal.jsonl\n\n# Check for pending syncs on an agent\nls ~/.openclaw/workspace-/pending_sync_*.md\n```\n\n### Demo Mode (Learning)\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/init_sync.sh --demo --lang en\n```\n\nCreates a complete demo deployment in `/tmp/` showing the full file structure without touching real workspaces.\n\n---\n\n## Manual Sync Trigger\n\n```bash\nbash skills/agent-config-sync/scripts/force_sync.sh \\\n ~/.openclaw/workspace-amaster/memory v3.0 v3.1\n```\n\nThis creates a version mismatch (old=3.0, new=3.1) — next heartbeat dispatches.\n\n---\n\n## Troubleshooting\n\n### Agents Not Receiving Updates\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| No dispatch on heartbeat | HEARTBEAT item 12 not added to master | Follow `references/sync-setup.md` exactly; verify grep `agent-config-sync` in master's HEARTBEAT.md |\n| Dispatched but not processed | Agent missing BOOTSTRAP sync check | Re-run `init_sync.sh` for that agent's workspace |\n| `pending_sync` files piling up | Agent never deletes after processing | Check agent's HEARTBEAT.md has sync check with delete step |\n| Same version synced repeatedly | `.last_sync_version` not updated | Run `force_sync.sh` to reset, or check journal for stale records |\n\n### Version Conflicts\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| Wrong version on agent | Partial sync interrupted | Check journal for `status=prepared` records; master re-dispatches on next heartbeat |\n| Multiple `pending_sync` files | Back-to-back changes | Process latest version first; all files are cumulative |\n| SHA256 verification fails | File tampered or truncated | Request master to re-dispatch that version |\n| \"Backup failed\" in force_sync | Memory dir permission issue | `chmod 755 memory/` and retry |\n\n### Journal Issues\n\n| Symptom | Likely Cause | Fix |\n|---------|-------------|-----|\n| Stale prepared records (>24h) | Agent was offline too long | Mark as abandoned in journal, re-trigger sync with `force_sync.sh` |\n| Journal growing too large | Many sync records | Archive old `committed` entries periodically |\n| Corrupt journal line | Partial write or disk issue | Delete the last line (corrupt), re-trigger sync |\n\n### Rolling Back a Change\n\nTo undo a sync that was dispatched but shouldn't have been:\n\n1. **Revert the version**: `echo \"v3.0\" > memory/.current_system_version` (back to previous)\n2. **Revert the last_sync**: `echo \"v3.0\" > memory/.last_sync_version`\n3. **Mark the journal record**: Edit `.sync_journal.jsonl`, find the record with `\"to\":\"v3.1\"` and change `status` to `\"reverted\"`\n4. **Notify agents**: Agents check `pending_sync` files on heartbeat — delete old ones\n5. **Verify**: `ls ~/.openclaw/workspace-*/pending_sync_*.md` should be empty\n\nAlternatively, use `force_sync.sh` in \"reverse\":\n\n```bash\nbash scripts/force_sync.sh memory/ v3.0 v3.1 # created mismatch forward\nbash scripts/force_sync.sh memory/ v3.1 v3.0 # reverse: current=v3.0, last=v3.1 → no dispatch (current < last)\n```\n\n> ⚠️ `force_sync.sh` only creates the version mismatch — actual rollback requires reverting the changes in CHANGELOG and agent configs manually.\n\n---\n\n## 🌐 Internationalization\n\nThis skill supports both **Chinese** and **English** environments:\n\n| Resource | Chinese | English |\n|----------|:---:|:---:|\n| `SKILL.md` (this file) | — | ✅ Full English |\n| `references/quickstart.md` | — | ✅ English quickstart for new users |\n| `references/sync-setup.md` | ✅ Full Chinese | — (code pseudocode is language-agnostic) |\n| `references/sync-journal.md` | ✅ Full Chinese | — (JSONL format is language-agnostic) |\n| `scripts/init_sync.sh` | `--lang zh` (default) | `--lang en` |\n| `scripts/force_sync.sh` | `--lang zh` (default) | `--lang en` |\n| Registry agent names | `name_zh` field | `name` field |\n| Generated SYNC.md | Chinese template | English template (via `--lang en`) |\n| Generated CHANGELOG.md | Chinese template | English template (via `--lang en`) |\n\n**Using English**:\n\n```bash\n# Install and initialize in English\nbash scripts/init_sync.sh --lang en\n\n# Demo in English\nbash scripts/init_sync.sh --lang en --demo\n```\n\nNew English-speaking users should start with `references/quickstart.md`.\n\n---\n\n## Upgrading\n\n### From v1.0 to v1.1\n\n- `agent-registry.json` introduced (previously agent list was hardcoded)\n- `pending_sync` files now use version-named format (`pending_sync_v3.1_a1b2c3.md`) instead of single `pending_sync.md`\n- Journal-based two-phase commit added\n- No breaking changes — existing sentinel files and CHANGELOG format unchanged\n\n### From v1.1 to v1.2\n\n- **Registry is now single source of truth**: scripts read agent list from `agent-registry.json` instead of command-line args\n- **Bilingual scripts**: `--lang en|zh` flag on both `init_sync.sh` and `force_sync.sh`\n- **New flags**: `--dry-run` (preview), `--demo` (learning mode), `--help`\n- **English quickstart**: `references/quickstart.md` added\n- **`agent-registry.json` format changed**: added `vars` section with placeholders\n\n#### Migration steps (v1.1 → v1.2)\n\n1. **Update `agent-registry.json`**:\n ```json\n // Add this at the top of your existing agent-registry.json:\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n // Update workspace paths to use placeholders:\n \"agents\": {\n \"acode\": {\n \"workspace\": \"${vars.workspace_root}/workspace-acode\" // <-- use placeholder\n }\n }\n ```\n\n2. **Verify** with dry-run: `bash scripts/init_sync.sh --dry-run`\n\n3. **Re-run init**: `bash scripts/init_sync.sh` (safe — skips existing files)\n\n#### Compatibility notes\n\n- Existing `CHANGELOG.md`, sentinel files, and `.sync_journal.jsonl` are **fully compatible**\n- Agent-side `pending_sync_*.md` / `SYNC.md` / `BOOTSTRAP.md` format unchanged\n- `force_sync.sh` positional args unchanged; new flags are additive\n\n---\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `SKILL.md` | This skill definition |\n| `SECURITY.md` | Security model, permissions, and user consent flow |\n| `references/quickstart.md` | 🆕 English quickstart for new users |\n| `references/sync-setup.md` | HEARTBEAT item 12 + structured CHANGELOG spec |\n| `references/pending-sync-template.md` | pending_sync file template (version-named) |\n| `references/sync-journal.md` | Journal-based two-phase commit mechanism |\n| `references/agent-registry.json` | Single source of truth for agent IDs and workspaces |\n| `scripts/init_sync.sh` | Full setup in one command (now reads registry; supports --auto) |\n| `scripts/force_sync.sh` | Trigger immediate sync detection |\n| `scripts/revert_sync.sh` | Trigger version rollback |\n| `scripts/wizard.sh` | 🆕 Interactive setup wizard for new users |\n\nFile v1.5.0:README.md\n\n# agent-config-sync v1.5\n\n**Keep configuration consistent across multiple OpenClaw agents** — zero-touch setup, interactive wizard, version tracking, and automatic sync dispatch.\n\n[![Version](https://img.shields.io/badge/version-1.5.0-blue)](_meta.json)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-enabled-green)](https://openclaw.ai)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Bash](https://img.shields.io/badge/pure-bash-orange)](scripts/)\n\n---\n\n## 🎯 What It Does\n\nWhen you run 2+ OpenClaw agents, keeping their configurations in sync is painful. `agent-config-sync` automates this:\n\n```\nMaster Agent detects change\n │\n ▼\n Reads CHANGELOG.md\n │\n ▼\n Generates sync manifest\n │\n ├─→ Agent 1: pending_sync_v3.1_a1b2c3.md\n ├─→ Agent 2: pending_sync_v3.1_a1b2c3.md\n └─→ Agent 3: pending_sync_v3.1_a1b2c3.md\n │\n ▼\n Agents apply → verify → cleanup\n```\n\n**Syncs**: System code · Agent configs (SOUL/IDENTITY/TOOLS) · OpenClaw config · Task configs · API keys\n\n---\n\n## ⚡ Quick Start (30 seconds)\n\n```bash\n# 1. Install\nclawhub install agent-config-sync\n\n# 2. Run wizard (interactive, auto-detects everything)\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n\n# 3. Done! 🎉\n# All agents now have sync infrastructure.\n# Changes are auto-dispatched on next Master heartbeat.\n```\n\n**Prefer non-interactive?**\n```bash\nbash scripts/wizard.sh --auto # Zero prompts\nbash scripts/init_sync.sh --auto # Even faster\n```\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|:--------|:------------|\n| 🧙 **Interactive Wizard** | 5-step guided setup with auto-detection — no manual file editing |\n| 🤖 **--auto Mode** | One-command setup that detects workspaces, generates registry, and initializes everything |\n| 📊 **Version Tracking** | Sentinel files (`.current_system_version`, `.last_sync_version`) for monotonic versioning |\n| 🔄 **Auto Dispatch** | Master HEARTBEAT detects version mismatch → dispatches to all agents via `sessions_send` or file fallback |\n| 📝 **CHANGELOG-driven** | Structured `CHANGELOG.md` — read only latest section, not entire history |\n| 🗄️ **Two-Phase Commit** | `.sync_journal.jsonl` ensures atomicity — PREPARE → DISPATCH → COMMIT |\n| 🔍 **Offline Catch-Up** | Agents that miss sync cycles get cumulative catch-up packages |\n| 🛡️ **Rollback** | Pre-sync snapshots + SHA256 verification for safe rollbacks |\n| 🔒 **Dispatch Lock** | Prevents concurrent sync dispatch (< 2min window) |\n| 🔁 **Loop Detection** | 3+ consecutive same-version → block and alert |\n| 📦 **Batch Mode** | Merges rapid consecutive changes into single dispatch |\n| 🏝️ **Self-Upgrade Isolation** | agent-config-sync's own files use isolated upgrade flow |\n| 🌐 **Bilingual** | Full Chinese + English output (`--lang en|zh`) |\n| 🎭 **Demo Mode** | `--demo` creates a full temp deployment for learning |\n| 🔐 **Path Validation** | Only writes to `~/.openclaw/workspace-*` — no external access |\n\n---\n\n## 📋 Requirements\n\n- **OpenClaw** running with 2+ agents\n- One designated \"master\" coordination agent\n- `clawhub` CLI installed\n- Bash 4.0+ (no Python/Perl required)\n\n---\n\n## 🏗️ Architecture\n\n```\nskills/agent-config-sync/\n├── SKILL.md # Full documentation\n├── SECURITY.md # Security model & permissions\n├── README.md # This file\n├── _meta.json # Package metadata\n├── scripts/\n│ ├── wizard.sh # 🆕 Interactive setup wizard (v1.5)\n│ ├── init_sync.sh # Infrastructure initialization\n│ ├── force_sync.sh # Trigger immediate sync detection\n│ └── revert_sync.sh # Version rollback trigger\n├── references/\n│ ├── agent-registry.json # Single source of truth (agent IDs, paths)\n│ ├── sync-setup.md # HEARTBEAT item 12 + CHANGELOG spec\n│ ├── sync-journal.md # Two-phase commit mechanism\n│ ├── pending-sync-template.md # Sync file template\n│ └── quickstart.md # Quickstart for new users\n└── reports/\n └── ... # Evaluation reports & repair logs\n```\n\n---\n\n## 🚀 Usage\n\n### Daily Operations\n\n```bash\n# Record a change (master agent)\necho \"v1.1\" > ~/.openclaw/workspace-amaster/memory/.current_system_version\n\n# Or use the force_sync helper\nbash scripts/force_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0 v1.1\n```\n\n### Check Status\n\n```bash\n# Master version\ncat ~/.openclaw/workspace-amaster/memory/.current_system_version\ncat ~/.openclaw/workspace-amaster/memory/.last_sync_version\n\n# Pending syncs on an agent\nls ~/.openclaw/workspace-acode/pending_sync_*.md\n```\n\n### Rollback\n\n```bash\nbash scripts/revert_sync.sh --dry-run ~/.openclaw/workspace-amaster/memory v1.0\nbash scripts/revert_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0\n```\n\n### Demo / Learning\n\n```bash\nbash scripts/init_sync.sh --demo --lang en\n```\n\n---\n\n## ⚙️ Configuration\n\nThe wizard auto-generates `references/agent-registry.json`. To customize manually:\n\n```json\n{\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\"\n },\n \"agents\": {\n \"acode\": { \"name\": \"Coding Agent\", \"role\": \"Development\", \"workspace\": \"...\" },\n \"ainvest\": { \"name\": \"Investment Agent\", \"role\": \"Finance\", \"workspace\": \"...\" }\n }\n}\n```\n\n---\n\n## 🔒 Security\n\nAll scripts enforce:\n- `--confirm` required for writes (use `--dry-run` first)\n- Path whitelist: only `~/.openclaw/workspace-*` allowed\n- Cross-agent isolation: each agent accesses only its own workspace\n- Atomic writes: `tempfile → sync → mv` (no partial sentinel files)\n- No network, no API calls, no credential access\n\nFull details: [SECURITY.md](SECURITY.md)\n\n---\n\n## 🌐 Internationalization\n\n```bash\n# English output\nbash scripts/wizard.sh --lang en\nbash scripts/init_sync.sh --lang en\n\n# Chinese output (default)\nbash scripts/wizard.sh --lang zh\n```\n\n---\n\n## 📄 License\n\nMIT\n\n---\n\n## 🙋 FAQ\n\n**Q: How is this different from just copying files?**\nA: It's event-driven (version mismatch → dispatch), journaled (two-phase commit), and handles edge cases (offline agents, conflicts, rollbacks).\n\n**Q: Do I need to run this on every agent?**\nA: No. Only the Master agent dispatches. Other agents receive `pending_sync_*.md` files and check for them on startup/heartbeat (automatically set up by `init_sync.sh`).\n\n**Q: What if an agent is offline?**\nA: The Master writes a `pending_sync_.md` file to the agent's workspace. On next startup, the agent detects and applies it. If multiple versions piled up, version collapse jumps to the latest.\n\n**Q: Can I use this without `clawhub`?**\nA: Yes — just clone or copy the skill directory to `~/.openclaw/skills/agent-config-sync/` and run `scripts/wizard.sh`.\n\nFile v1.5.0:_meta.json\n\n{\n \"ownerId\": \"kn7at24f2mbp2nzbvyprwbaws186t9g8\",\n \"slug\": \"agent-config-sync\",\n \"version\": \"1.5.0\",\n \"publishedAt\": 1778905195923\n}\n\nFile v1.5.0:references/agent-registry.json\n\n{\n \"version\": \"1.4.0\",\n \"comment\": \"Customize this file for your deployment — vars section + keyed agents object. v1.4 adds self_protect, batch, and sync configuration.\",\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"acode\": {\n \"name\": \"大师\",\n \"name_en\": \"Coding Agent\",\n \"role\": \"编程开发\",\n \"workspace\": \"${vars.workspace_root}/workspace-acode\"\n },\n \"ainvest\": {\n \"name\": \"元宝\",\n \"name_en\": \"Investment Agent\",\n \"role\": \"投资分析\",\n \"workspace\": \"${vars.workspace_root}/workspace-ainvest\"\n },\n \"alive\": {\n \"name\": \"牛奶\",\n \"name_en\": \"Assistant Agent\",\n \"role\": \"生活助理/写作\",\n \"workspace\": \"${vars.workspace_root}/workspace-alive\"\n }\n },\n \"sync\": {\n \"sentinel_dir\": \"memory\",\n \"journal_file\": \".sync_journal.jsonl\",\n \"changelog_file\": \"CHANGELOG.md\",\n \"pending_prefix\": \"pending_sync\",\n \"max_changelog_sections\": 10,\n \"ttl_hours\": 24,\n \"dispatch_timeout_sec\": 120\n },\n \"self_protect\": {\n \"enabled\": true,\n \"skip_agents\": [\"agent-config-sync\"],\n \"isolated_sync\": true,\n \"blacklist\": [\n \"HEARTBEAT.md\",\n \"BOOTSTRAP.md\",\n \"SKILL.md\",\n \"scripts/\",\n \"SECURITY.md\",\n \"references/\",\n \"agent-registry.json\"\n ],\n \"sync_own_version_file\": \"skills/agent-config-sync/.sync_own_version\",\n \"allow_bootstrap_only\": true\n },\n \"batch\": {\n \"mode\": \"auto\",\n \"window_sec\": 300\n }\n}\n\nFile v1.5.0:references/agent-setup.md\n\n# Per-Agent Auto-Sync Setup\n\nFor each agent workspace, create or append to these files:\n\n## 1. SYNC.md (new file)\n\n```markdown\n# 配置同步机制 — 自动获取变更通知\n\n## 检查入口\n每次启动/激活时，先检查工作空间下的 `pending_sync.md` 是否存在且非空。\n\n## 同步检查流程\n```\n启动/激活 → 检查工作目录存在 pending_sync.md?\n ├─ ✅ 有内容 → 读取变更摘要 → 更新本地 MEMORY.md\n │ → 根据变更内容更新本地配置\n │ → 删除 pending_sync.md（标记已处理）\n │ → 回复 AMaster 确认已同步\n └─ ❌ 无文件或空 → 无需同步\n```\n\n## 同步源\n- 完整变更日志: `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md`\n- 当前版本: `/home/admin/.openclaw/workspace-amaster/memory/.current_system_version`\n- 主动查询: 可向 AMaster 询问最新版本状态\n\n## 重要\n- 使用量化交易系统 / 比价系统前，必须确认版本信息\n- 如果有 pending_sync.md 但未处理，不要使用相关系统功能\n```\n\n## 2. BOOTSTRAP.md (append to end)\n\n```markdown\n## 启动检查 — 配置同步\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在 → 读取变更摘要，更新 MEMORY.md，删除 pending_sync.md\n - 不存在 → 无需同步\n- [ ] 使用量化系统/比价系统前先确认版本\n```\n\n## 3. HEARTBEAT.md (append to end)\n\n```markdown\n## ⭐ 配置同步检查（每次 heartbeat 执行）\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在且非空 → 读取变更摘要，更新 MEMORY.md，删除文件\n - 不存在 → 跳过\n```\n\nFile v1.5.0:references/pending-sync-template.md\n\n# pending_sync Template\n\n**v1.4**: Enhanced file header with TTL/expiry, depends_on chain, and agent version tracking fields. Backward compatible — new fields are additive.\n\n## Template Content\n\n```markdown\n# pending_sync__.md\n\n**类型**: pending_sync\n**版本**: \n**前置**: \n**生成时间**: \n**过期时间**: (24h 后)\n**紧急程度**: \n**签名**: \n\n## 变更清单\n- [ ] 🖥️ 系统代码变更\n- [ ] 🤖 智能体配置变更\n- [ ] ⚙️ OpenClaw 系统配置变更\n- [ ] 🎯 任务/工作配置变更\n\n## 详情\n请读取 `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md` 中 `` 对应的章节。\n\n## 操作指令\n1. 创建前置快照: mkdir -p memory/.sync_snapshots/_pre/\n2. 备份受影响文件到快照目录\n3. 应用变更\n4. 更新 memory/.agent_sync_version = \n5. 删除本文件\n```\n\n## Template Fields\n\n| Field | Required | Format | Example |\n|-------|:--------:|--------|---------|\n| `**类型**` | ✅ | `pending_sync` / `revert_sync` / `isolated_sync` | pending_sync |\n| `**版本**` | ✅ | `vX.Y` | v3.5 |\n| `**前置**` | ⬜ | `vX.Y` or `none` | v3.4 |\n| `**生成时间**` | ✅ | ISO 8601 with timezone | 2026-05-16T08:30:00+08:00 |\n| `**过期时间**` | ✅ | ISO 8601 (24h after generated) | 2026-05-17T08:30:00+08:00 |\n| `**紧急程度**` | ✅ | `normal` / `high` / `critical` | high |\n| `**签名**` | ✅ | SHA256 first 12 hex chars | a1b2c3d4e5f6 |\n\n## SHA256 Signature\n\nThe `` value in the filename and template body is computed as:\n\n```\nsha256(\"pending_sync__\" + 变更摘要)\n```\n\nTake the first 12 hex characters as the short signature.\n\n### Purpose\n- Receiving agent can verify file integrity\n- Prevents tampered or truncated sync notifications\n- Short 12-char format keeps filenames manageable\n\n### Verification (in agent-side logic)\n\n```python\nimport hashlib\n\ndef verify_sync_file(filename, expected_version, change_summary):\n expected_sig = hashlib.sha256(\n f\"pending_sync_{expected_version}_{change_summary}\".encode()\n ).hexdigest()[:12]\n actual_sig = filename.split(\"_\")[-1].replace(\".md\", \"\")\n return expected_sig == actual_sig\n```\n\n## File Naming Convention\n\n| Pattern | Example |\n|---------|---------|\n| Version sync | `pending_sync_v3.1_a1b2c3d4e5f6.md` |\n| Startup discovery | `ls pending_sync_*.md` to list all pending |\n| Revert sync | `revert_sync_v3.3_to_v3.2_a1b2c3d4.md` |\n| Isolated sync | `isolated_sync_v1.4_a1b2c3d4.md` |\n\n## Cleanup\n\nEach agent independently deletes its own pending file after processing:\n\n```bash\n# Agent-side cleanup after sync applied\nrm -f pending_sync_*.md revert_sync_*.md isolated_sync_*.md\n```\n\nThe file persists as long as the agent hasn't applied the sync. If the same version file is generated twice (e.g., dispatch retry), the content is idempotent — the agent can re-apply safely.\n\n## TTL & Expiry\n\nBy default, pending_sync files expire **24 hours** after generation. The agent's BOOTSTRAP/HEARTBEAT checks should:\n\n1. Parse `**过期时间**` from the file header\n2. If `now > 过期时间` → delete the expired file, request latest version from Master\n3. If `now <= 过期时间` → proceed with sync processing\n\nTTL is configurable via `agent-registry.json` → `sync.ttl_hours` (default: 24).\n\nFile v1.5.0:references/quickstart.md\n\n# Quickstart — agent-config-sync for New Users\n\n**5-minute setup** to keep configuration consistent across all your OpenClaw agents.\n\n---\n\n## Before You Start\n\nYou need:\n- OpenClaw running with 2+ agents\n- A \"master\" agent that coordinates others\n- `clawhub` CLI installed\n\n### Example Setup (Alice)\n\nAlice has 3 agents:\n\n| Agent ID | Purpose | Workspace |\n|----------|---------|-----------|\n| `alice-dev` | Software development | `~/.openclaw/workspace-alice-dev` |\n| `alice-biz` | Business analysis | `~/.openclaw/workspace-alice-biz` |\n| `alice-ops` | Operations & scheduling | `~/.openclaw/workspace-alice-ops` |\n\nAlice uses `alice-ops` as her master/coordination agent.\n\nWe'll use Alice's setup as a concrete example throughout this guide.\n\n---\n\n## Step 1: Install the Skill\n\n```bash\nclawhub install agent-config-sync\n```\n\nThis installs to `~/.openclaw/skills/agent-config-sync/`.\n\n---\n\n## Step 2: Customize the Agent Registry\n\nEdit `~/.openclaw/skills/agent-config-sync/references/agent-registry.json` to match your agents:\n\n```json\n{\n \"version\": \"1.2\",\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"alice-ops\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"alice-dev\": {\n \"name\": \"Alice Dev\",\n \"role\": \"Software Development\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-dev\"\n },\n \"alice-biz\": {\n \"name\": \"Alice Biz\",\n \"role\": \"Business Analysis\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-biz\"\n },\n \"alice-ops\": {\n \"name\": \"Alice Ops\",\n \"role\": \"Coordination\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-ops\"\n }\n }\n}\n```\n\n> **Key**: Change `master_agent` in `vars` and replace all agent entries under `agents`. Scripts read from this file — this is the **only place** you need to configure agent names.\n\n---\n\n## Step 3: Initialize Sync Infrastructure\n\n```bash\ncd ~/.openclaw/skills/agent-config-sync\n\n# Preview what will be created (safe, makes no changes)\nbash scripts/init_sync.sh --dry-run\n\n# Run the actual setup\nbash scripts/init_sync.sh\n```\n\nThis creates:\n- Version sentinel files in your master agent's `memory/` directory\n- `CHANGELOG.md` with structured format\n- `.sync_journal.jsonl` for sync atomicity\n- `SYNC.md`, bootstrapped `BOOTSTRAP.md`, and `HEARTBEAT.md` sync checks in each agent workspace\n\n---\n\n## Step 4: Add HEARTBEAT Item to Master Agent\n\nAdd this to your master agent's `HEARTBEAT.md`:\n\n```markdown\n12. ⭐ **Config Change Sync** — Check for unsynchronized system/config changes\n - **Sentinel**: `memory/.last_sync_version`\n - Compare against `memory/.current_system_version` on every heartbeat\n - If version mismatch detected → dispatch to all downstream agents:\n a. Read latest section from `memory/CHANGELOG.md`\n b. `sessions_send` to each agent (or write `pending_sync__.md` as fallback)\n c. Record results in `.sync_journal.jsonl`\n - On success → update `memory/.last_sync_version` = `memory/.current_system_version`\n - Sync failure does NOT block heartbeat — logged to journal only\n```\n\nSee `references/sync-setup.md` for the full specification.\n\n---\n\n## Step 5: Verify\n\n```bash\n# Check version files were created\ncat ~/.openclaw/workspace-alice-ops/memory/.current_system_version\n# Expected: v1.0\n\ncat ~/.openclaw/workspace-alice-ops/memory/.last_sync_version\n# Expected: v1.0\n\n# Check agent sync files exist\nls ~/.openclaw/workspace-alice-dev/SYNC.md ~/.openclaw/workspace-alice-biz/SYNC.md\n# Both should exist\n```\n\n---\n\n## Step 6: Test a Sync\n\n```bash\n# Bump version to trigger sync on next heartbeat\necho \"v1.1\" > ~/.openclaw/workspace-alice-ops/memory/.current_system_version\n\n# Or use the force_sync helper:\nbash ~/.openclaw/skills/agent-config-sync/scripts/force_sync.sh \\\n ~/.openclaw/workspace-alice-ops/memory v1.0 v1.1\n```\n\nThe next heartbeat on your master agent will detect the version mismatch and dispatch config changes to all agents.\n\n---\n\n## Customizing Further\n\n### Change master memory path\n\nIf your master agent stores memory elsewhere, update `vars.master_memory` in `.agent_registry`:\n\n```json\n\"vars\": {\n \"master_memory\": \"/custom/path/to/memory\"\n}\n```\n\n### Use as non-master agent\n\nThe skill's sync reception is agent-side: each agent checks for `pending_sync_*.md` files on startup (BOOTSTRAP) and every heartbeat (HEARTBEAT). The `init_sync.sh` script sets this up automatically.\n\n### Language\n\nScripts support Chinese and English output:\n\n```bash\nbash scripts/init_sync.sh --lang en # English output\nbash scripts/init_sync.sh --lang zh # Chinese output (default)\n```\n\n---\n\n## Troubleshooting\n\n| Problem | Check |\n|---------|-------|\n| \"Registry not found\" in init_sync | Run from skill directory: `cd ~/.openclaw/skills/agent-config-sync` |\n| Agents not receiving syncs | Verify master agent has HEARTBEAT item 12 |\n| `pending_sync` files pile up | Agent may not have BOOTSTRAP sync check — re-run `init_sync.sh` |\n| Path errors | Check `vars.workspace_root` in `agent-registry.json` — expand `~` to full path if needed |\n\n---\n\n## Next Steps\n\n- Read `SKILL.md` for architecture overview and daily operations\n- Read `references/sync-setup.md` for HEARTBEAT implementation details\n- Read `references/sync-journal.md` for the two-phase commit mechanism\n\nFile v1.5.0:references/sync-journal.md\n\n# Sync Journal — 两步提交机制\n\n## 概述\n\nSync Journal 提供配置同步的原子性和可恢复性保证。\n每次版本同步操作都通过 journal 记录，确保即使中途中断也能正确恢复。\n\n## Journal 文件\n\n- **位置**: `memory/.sync_journal.jsonl`\n- **格式**: JSONL (每行一条 JSON 记录)\n- **权限**: 与 version sentinel 文件同级\n\n## 记录格式\n\n```jsonl\n{\"ts\":\"2026-05-16T08:30:00Z\",\"from\":\"v3.0\",\"to\":\"v3.1\",\"status\":\"prepared\",\"agents\":{\"acode\":\"pending\",\"ainvest\":\"pending\",\"alive\":\"pending\"}}\n{\"ts\":\"2026-05-16T08:30:01Z\",\"from\":\"v3.0\",\"to\":\"v3.1\",\"status\":\"committed\",\"agents\":{\"acode\":\"done\",\"ainvest\":\"done\",\"alive\":\"pending\"}}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `ts` | ISO 8601 | 操作时间戳 (UTC) |\n| `from` | string | 同步前版本号 |\n| `to` | string | 同步目标版本号 |\n| `status` | prepared/committed/failed | 同步状态 |\n| `agents` | object | 每个 agent 的同步状态: pending/done/failed/timeout |\n\n## 两步提交流程\n\n### Step 1: PREPARE\n\n```\ncontex\n\nArchive v1.3.0: 12 files, 29723 bytes\n\nFiles: _meta.json (136b), references/agent-registry.json (854b), references/agent-setup.md (1662b), references/pending-sync-template.md (2076b), references/quickstart.md (5356b), references/sync-journal.md (3994b), references/sync-setup.md (5594b), reports/agent-config-sync-eval-v1.1.md (6967b), scripts/force_sync.sh (9118b), scripts/init_sync.sh (19703b), SECURITY.md (2086b), SKILL.md (16814b)\n\nArchive v1.2.1: 11 files, 27555 bytes\n\nFiles: _meta.json (136b), references/agent-registry.json (854b), references/agent-setup.md (1662b), references/pending-sync-template.md (2076b), references/quickstart.md (5356b), references/sync-journal.md (3994b), references/sync-setup.md (5594b), reports/agent-config-sync-eval-v1.1.md (6967b), scripts/force_sync.sh (8187b), scripts/init_sync.sh (18764b), SKILL.md (15883b)\n\nArchive v1.2.0: 10 files, 26987 bytes\n\nFiles: references/agent-setup.md (1662b), references/pending-sync-template.md (2076b), references/quickstart.md (5356b), references/sync-journal.md (3994b), references/sync-setup.md (5594b), reports/agent-config-sync-eval-v1.1.md (6967b), scripts/force_sync.sh (8187b), scripts/init_sync.sh (18756b), SKILL.md (15843b), _meta.json (136b)\n\nArchive v1.1.0: 8 files, 13327 bytes\n\nFiles: references/agent-setup.md (1662b), references/pending-sync-template.md (2076b), references/sync-journal.md (3994b), references/sync-setup.md (5594b), scripts/force_sync.sh (2171b), scripts/init_sync.sh (4902b), SKILL.md (6255b), _meta.json (136b)\n\nArchive v1.0.0: 7 files, 7251 bytes\n\nFiles: references/agent-setup.md (1662b), references/pending-sync-template.md (1031b), references/sync-setup.md (1851b), scripts/force_sync.sh (1135b), scripts/init_sync.sh (2871b), SKILL.md (4810b), _meta.json (136b)","readmeExcerpt":"Skill: Agent Config Sync Owner: stevensongxx Summary: Synchronize configuration versions across OpenClaw multi-agent deployments. Tracks changes in a master workspace using sentinel version files and CHANGELOG,... Tags: automation:1.3.0, chinese:1.3.0, config:1.3.0, english:1.3.0, latest:1.5.1, reliable:1.1.0, secure:1.3.0, sync:1.3.0 Version history: v1.5.1 | 2026-05-16T08:07:21.603Z | auto agent-config-sync v1.5.1 ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"> # Step 1: Install\n> clawhub install agent-config-sync\n>\n> # Step 2: Run setup wizard (interactive, no manual editing needed)\n> cd ~/.openclaw/skills/agent-config-sync\n> bash scripts/wizard.sh\n>\n> # Step 3: Done! 🎉\n> # - Agent registry auto-detected\n> # - Sync infrastructure created\n> # - HEARTBEAT integration added\n> # - All agents ready to receive syncs\n>"},{"language":"bash","snippet":"cd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh"},{"language":"json","snippet":"{\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"alice-ops\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"alice-dev\": { \"name\": \"Alice Dev\", \"role\": \"Development\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-dev\" },\n \"alice-biz\": { \"name\": \"Alice Biz\", \"role\": \"Business\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-biz\" },\n \"alice-ops\": { \"name\": \"Alice Ops\", \"role\": \"Coordination\",\n \"workspace\": \"${vars.workspace_root}/workspace-alice-ops\" }\n }\n}"},{"language":"text","snippet":"┌─ Version Tracking ──────────────────────┐\n│ .current_system_version (monotonic) │\n│ .last_sync_version (last synced) │\n│ CHANGELOG.md (structured) │\n│ .sync_journal.jsonl (atomicity) │\n└──────────────────────────────────────────┘\n │ version mismatch detected by HEARTBEAT\n ▼\n┌─ Sync Journal (two-phase commit) ────────┐\n│ PREPARE → journal entry written │\n│ DISPATCH → sessions_send / pending_sync │\n│ COMMIT → mark done or retry later │\n└──────────────────────────────────────────┘\n │ each agent processes independently\n ▼\n┌─ Agent Side ────────────────────────────┐\n│ BOOTSTRAP.md → ls pending_sync_*.md │\n│ HEARTBEAT.md → check + verify SHA256 │\n│ SYNC.md → manual sync instructions │\n└──────────────────────────────────────────┘"},{"language":"bash","snippet":"clawhub install agent-config-sync\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh"},{"language":"bash","snippet":"clawhub install agent-config-sync\nbash ~/.openclaw/skills/agent-config-sync/scripts/init_sync.sh --auto"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agent-config-sync\ndescription: |-\n Synchronize configuration versions across OpenClaw multi-agent deployments.\n Tracks changes in a master workspace using sentinel version files and CHANGELOG,\n then dispatches to downstream agents via sessions_send or file-based pending_sync\n fallback. Each agent independently checks for updates on startup (BOOTSTRAP.md)\n and heartbeat (HEARTBEAT.md). Designed for users running 2+ specialized agents\n who need consistent system/agent/OpenClaw configurations.\n Triggers on: sync, configure, version management, multi-agent coordination.\n---\n\n# Agent Config Sync (v1.5)\n\nKeep configuration consistent across multiple OpenClaw agents using version tracking, CHANGELOG-based change detection, and automatic sync dispatch with journal-backed two-phase commit.\n\n> **⚡ Quick Start (30 seconds to running):**\n> ```bash\n> # Step 1: Install\n> clawhub install agent-config-sync\n>\n> # Step 2: Run setup wizard (interactive, no manual editing needed)\n> cd ~/.openclaw/skills/agent-config-sync\n> bash scripts/wizard.sh\n>\n> # Step 3: Done! 🎉\n> # - Agent registry auto-detected\n> # - Sync infrastructure created\n> # - HEARTBEAT integration added\n> # - All agents ready to receive syncs\n> ```\n> \n> **Non-interactive?** Use `bash scripts/wizard.sh --auto` to auto-detect everything.\n> \n> **Prefer manual?** See [Installation](#installation) below for step-by-step instructions.\n>\n> **New in v1.5**: Interactive setup wizard (`scripts/wizard.sh`), `--auto` mode for init_sync.sh (zero-config auto-detection), enhanced SYNC.md with quick start guide and cheat sheet, simplified onboarding.\n>\n> **New in v1.4**: Full version conflict management — dispatch lock, loop detection, self-upgrade isolation, batch mode, rollback snapshots, TTL-based expiry, offline catch-up, and agent-side version collapse. See [Version Conflict Management](#version-conflict-management-v14) for details.\n>\n> **Security**: This skill writes to agent workspaces across your OpenClaw deployment. Read the full [SECURITY.md](SECURITY.md) for permission scope, path validation, cross-agent isolation, and user consent flow. Key highlights:\n> - All scripts require `--confirm` for write operations (use `--dry-run` to preview first)\n> - Only paths under `~/.openclaw/workspace-*` are allowed (path validation enforced)\n> - Each agent can only read/write its own workspace files\n> - No network access, no external API calls, no credential access\n\n## ⚙️ Customization Variables\n\n**Option A (Recommended): Run the setup wizard**\n```bash\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n```\nThe wizard auto-detects your agents and generates `agent-registry.json` — no manual editing.\n\n**Option B: Manual configuration**\n\nEdit `references/agent-registry.json` — this is the only file you need to change for your deployment:\n\n| Variable | Location | Example | Description |\n|----------|----------|---------|-------------|\n| `workspace_root` | `vars` in registry | `~/.open"},{"path":"README.md","content":"# agent-config-sync v1.5\n\n**Keep configuration consistent across multiple OpenClaw agents** — zero-touch setup, interactive wizard, version tracking, and automatic sync dispatch.\n\n[![Version](https://img.shields.io/badge/version-1.5.0-blue)](_meta.json)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-enabled-green)](https://openclaw.ai)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Bash](https://img.shields.io/badge/pure-bash-orange)](scripts/)\n\n---\n\n## 🎯 What It Does\n\nWhen you run 2+ OpenClaw agents, keeping their configurations in sync is painful. `agent-config-sync` automates this:\n\n```\nMaster Agent detects change\n │\n ▼\n Reads CHANGELOG.md\n │\n ▼\n Generates sync manifest\n │\n ├─→ Agent 1: pending_sync_v3.1_a1b2c3.md\n ├─→ Agent 2: pending_sync_v3.1_a1b2c3.md\n └─→ Agent 3: pending_sync_v3.1_a1b2c3.md\n │\n ▼\n Agents apply → verify → cleanup\n```\n\n**Syncs**: System code · Agent configs (SOUL/IDENTITY/TOOLS) · OpenClaw config · Task configs · API keys\n\n---\n\n## ⚡ Quick Start (30 seconds)\n\n```bash\n# 1. Install\nclawhub install agent-config-sync\n\n# 2. Run wizard (interactive, auto-detects everything)\ncd ~/.openclaw/skills/agent-config-sync\nbash scripts/wizard.sh\n\n# 3. Done! 🎉\n# All agents now have sync infrastructure.\n# Changes are auto-dispatched on next Master heartbeat.\n```\n\n**Prefer non-interactive?**\n```bash\nbash scripts/wizard.sh --auto # Zero prompts\nbash scripts/init_sync.sh --auto # Even faster\n```\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|:--------|:------------|\n| 🧙 **Interactive Wizard** | 5-step guided setup with auto-detection — no manual file editing |\n| 🤖 **--auto Mode** | One-command setup that detects workspaces, generates registry, and initializes everything |\n| 📊 **Version Tracking** | Sentinel files (`.current_system_version`, `.last_sync_version`) for monotonic versioning |\n| 🔄 **Auto Dispatch** | Master HEARTBEAT detects version mismatch → dispatches to all agents via `sessions_send` or file fallback |\n| 📝 **CHANGELOG-driven** | Structured `CHANGELOG.md` — read only latest section, not entire history |\n| 🗄️ **Two-Phase Commit** | `.sync_journal.jsonl` ensures atomicity — PREPARE → DISPATCH → COMMIT |\n| 🔍 **Offline Catch-Up** | Agents that miss sync cycles get cumulative catch-up packages |\n| 🛡️ **Rollback** | Pre-sync snapshots + SHA256 verification for safe rollbacks |\n| 🔒 **Dispatch Lock** | Prevents concurrent sync dispatch (< 2min window) |\n| 🔁 **Loop Detection** | 3+ consecutive same-version → block and alert |\n| 📦 **Batch Mode** | Merges rapid consecutive changes into single dispatch |\n| 🏝️ **Self-Upgrade Isolation** | agent-config-sync's own files use isolated upgrade flow |\n| 🌐 **Bilingual** | Full Chinese + English output (`--lang en|zh`) |\n| 🎭 **Demo Mode** | `--demo` creates a full temp deployment for learning |\n| 🔐 **Path Validation** | Only writes to `~/.openclaw/wo"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7at24f2mbp2nzbvyprwbaws186t9g8\",\n \"slug\": \"agent-config-sync\",\n \"version\": \"1.5.1\",\n \"publishedAt\": 1778918841603\n}"},{"path":"references/agent-registry.json","content":"{\n \"version\": \"1.4.0\",\n \"comment\": \"Customize this file for your deployment — vars section + keyed agents object. v1.4 adds self_protect, batch, and sync configuration.\",\n \"vars\": {\n \"workspace_root\": \"~/.openclaw\",\n \"master_agent\": \"amaster\",\n \"master_memory\": \"${vars.workspace_root}/workspace-${vars.master_agent}/memory\"\n },\n \"agents\": {\n \"acode\": {\n \"name\": \"大师\",\n \"name_en\": \"Coding Agent\",\n \"role\": \"编程开发\",\n \"workspace\": \"${vars.workspace_root}/workspace-acode\"\n },\n \"ainvest\": {\n \"name\": \"元宝\",\n \"name_en\": \"Investment Agent\",\n \"role\": \"投资分析\",\n \"workspace\": \"${vars.workspace_root}/workspace-ainvest\"\n },\n \"alive\": {\n \"name\": \"牛奶\",\n \"name_en\": \"Assistant Agent\",\n \"role\": \"生活助理/写作\",\n \"workspace\": \"${vars.workspace_root}/workspace-alive\"\n }\n },\n \"sync\": {\n \"sentinel_dir\": \"memory\",\n \"journal_file\": \".sync_journal.jsonl\",\n \"changelog_file\": \"CHANGELOG.md\",\n \"pending_prefix\": \"pending_sync\",\n \"max_changelog_sections\": 10,\n \"ttl_hours\": 24,\n \"dispatch_timeout_sec\": 120\n },\n \"self_protect\": {\n \"enabled\": true,\n \"skip_agents\": [\"agent-config-sync\"],\n \"isolated_sync\": true,\n \"blacklist\": [\n \"HEARTBEAT.md\",\n \"BOOTSTRAP.md\",\n \"SKILL.md\",\n \"scripts/\",\n \"SECURITY.md\",\n \"references/\",\n \"agent-registry.json\"\n ],\n \"sync_own_version_file\": \"skills/agent-config-sync/.sync_own_version\",\n \"allow_bootstrap_only\": true\n },\n \"batch\": {\n \"mode\": \"auto\",\n \"window_sec\": 300\n }\n}"},{"path":"references/agent-setup.md","content":"# Per-Agent Auto-Sync Setup\n\nFor each agent workspace, create or append to these files:\n\n## 1. SYNC.md (new file)\n\n```markdown\n# 配置同步机制 — 自动获取变更通知\n\n## 检查入口\n每次启动/激活时，先检查工作空间下的 `pending_sync.md` 是否存在且非空。\n\n## 同步检查流程\n```\n启动/激活 → 检查工作目录存在 pending_sync.md?\n ├─ ✅ 有内容 → 读取变更摘要 → 更新本地 MEMORY.md\n │ → 根据变更内容更新本地配置\n │ → 删除 pending_sync.md（标记已处理）\n │ → 回复 AMaster 确认已同步\n └─ ❌ 无文件或空 → 无需同步\n```\n\n## 同步源\n- 完整变更日志: `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md`\n- 当前版本: `/home/admin/.openclaw/workspace-amaster/memory/.current_system_version`\n- 主动查询: 可向 AMaster 询问最新版本状态\n\n## 重要\n- 使用量化交易系统 / 比价系统前，必须确认版本信息\n- 如果有 pending_sync.md 但未处理，不要使用相关系统功能\n```\n\n## 2. BOOTSTRAP.md (append to end)\n\n```markdown\n## 启动检查 — 配置同步\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在 → 读取变更摘要，更新 MEMORY.md，删除 pending_sync.md\n - 不存在 → 无需同步\n- [ ] 使用量化系统/比价系统前先确认版本\n```\n\n## 3. HEARTBEAT.md (append to end)\n\n```markdown\n## ⭐ 配置同步检查（每次 heartbeat 执行）\n- [ ] 检查工作目录下是否存在 `pending_sync.md`\n - 存在且非空 → 读取变更摘要，更新 MEMORY.md，删除文件\n - 不存在 → 跳过\n```"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1331,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:31:02.072Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T13:20:52.286Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}