Back to Details

sync-horizon

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sync Horizon

同步eve-horizon

Synchronize eve-skillpacks with the latest state of the eve-horizon repository.
将eve-skillpacks与eve-horizon仓库的最新状态保持同步。

Prerequisites

前置条件

  • The eve-horizon repo must be at 
    ../eve-horizon
    (sibling directory)
  • .sync-state.json
    must exist in the repo root (create from template if missing)
  • .sync-map.json
    must exist in the repo root
  • eve-horizon仓库必须位于
    ../eve-horizon
    （同级目录）
  • 仓库根目录下必须存在
    .sync-state.json
    文件（若缺失可从模板创建）
  • 仓库根目录下必须存在
    .sync-map.json
    文件

Architecture: Orchestrator + Parallel Workers

架构：编排器 + 并行工作节点

This sync follows an orchestrator pattern. You (the orchestrator) stay lightweight — discovering what changed and dispatching focused workers. Each worker handles one update in isolation with its own context budget.
Why: Previous runs exhausted the context window by reading every diff and every doc in the orchestrator. The fix is strict separation: the orchestrator sees only file names and summaries; workers see only their specific diffs and target files.
此同步流程采用编排器模式。你作为编排器需保持轻量——仅负责发现变更并分配任务给专注的工作节点。每个工作节点独立处理一项更新任务，拥有自身的上下文预算。
原因： 之前的运行方式中，编排器会读取所有差异和文档，导致上下文窗口耗尽。解决方案是严格分离职责：编排器仅能查看文件名和摘要；工作节点仅处理其分配到的特定差异和目标文件。

Workflow

工作流程

Phase 1: Discover Changes (orchestrator — stay lightweight)

阶段1：发现变更（编排器——保持轻量）

  1. Read 
    .sync-state.json
    to get 
    last_synced_commit
  2. If 
    last_synced_commit
    is null, use the first eve-horizon commit (full baseline sync)
  3. Get the commit log:
    bash
    cd ../eve-horizon && git log --oneline <last_synced_commit>..HEAD
  4. Get the diff stat of watched paths (file names and line counts only):
    bash
    cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/system/ docs/ideas/agent-native-design.md docs/ideas/platform-primitives-for-agentic-apps.md packages/cli/src/commands/ AGENTS.md
STOP. Do NOT read individual file diffs. You only need the 
--stat
output to know which files changed. Reading diffs is the workers' job.
  1. 读取
    .sync-state.json
    文件获取
    last_synced_commit
    （上次同步提交）
  2. 若
    last_synced_commit
    为空，则使用eve-horizon的首个提交（全量基线同步）
  3. 获取提交日志：
    bash
    cd ../eve-horizon && git log --oneline <last_synced_commit>..HEAD
  4. 获取监控路径的差异统计（仅包含文件名和行数）：
    bash
    cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/system/ docs/ideas/agent-native-design.md docs/ideas/platform-primitives-for-agentic-apps.md packages/cli/src/commands/ AGENTS.md
停止。 请勿读取单个文件的差异内容。你仅需通过
--stat
输出来了解哪些文件发生了变更。读取差异是工作节点的职责。

Phase 2: Plan Work Items (orchestrator)

阶段2：规划工作项（编排器）

Read 
.sync-map.json
and cross-reference the changed files against the 
reference_docs
and 
skill_triggers
mappings.
For each affected target, create a tracked work item:
  • Title: 
    Update <target-file> with <brief change summary>
  • Description — include everything a worker needs to operate independently:
    • The eve-horizon repo path (
      ../eve-horizon
      )
    • The commit range: 
      <last_synced_commit>..HEAD
    • Which source files changed (from 
      --stat
      )
    • The target file path to update
    • Whether this is a reference doc update, skill update, or new skill creation
    • The update rules (see "Worker Instructions" below)
Add a final work item: 
Update sync state and produce report
— blocked until all updates finish.
If the user gave additional instructions (e.g., "analyze storage gaps"), add that as a separate work item too, also blocked until updates finish.
读取
.sync-map.json
文件，将变更文件与
reference_docs
（参考文档）和
skill_triggers
（Skill触发规则）的映射关系进行交叉比对。
针对每个受影响的目标，创建一个可追踪的工作项：
  • 标题：
    更新<目标文件>：<简要变更摘要>
  • 描述——需包含工作节点独立运行所需的所有信息：
    • eve-horizon仓库路径（
      ../eve-horizon
      ）
    • 提交范围：
      <last_synced_commit>..HEAD
    • 哪些源文件发生了变更（来自
      --stat
      输出）
    • 待更新的目标文件路径
    • 本次更新属于参考文档更新、Skill更新还是新Skill创建
    • 更新规则（见下文“工作节点说明”）
添加最后一个工作项：
更新同步状态并生成报告
——需等待所有更新完成后方可执行。
如果用户提供了额外指令（例如“分析存储缺口”），也需将其作为单独的工作项添加，同样需等待所有更新完成后方可执行。

Phase 3: Dispatch Workers (parallel)

阶段3：分配工作节点（并行）

Spawn one background worker per work item. Launch them all at once so they run in parallel.
Each worker prompt must be self-contained. The worker has no access to the orchestrator's conversation. Include:
  1. The exact git command to get the diff: 
    cd ../eve-horizon && git diff <last_synced_commit>..HEAD -- <source-file-1> <source-file-2>
  2. The target file to read and modify
  3. If diffs are large, the full source doc path to read from eve-horizon as reference
  4. The appropriate update rules from below
为每个工作项启动一个后台工作节点。所有工作节点需同时启动，以实现并行运行。
每个工作节点的提示信息必须完全独立。 工作节点无法访问编排器的对话内容。提示信息需包含：
  1. 获取差异的精确Git命令： 
    cd ../eve-horizon && git diff <last_synced_commit>..HEAD -- <source-file-1> <source-file-2>
  2. 需读取和修改的目标文件
  3. 若差异内容较大，需提供eve-horizon中完整源文档的路径作为参考
  4. 下文对应的更新规则

Worker Instructions: Reference Docs

工作节点说明：参考文档

Read the git diff for your assigned source files. Read the current reference doc. Distill the changes into the reference doc — these are curated summaries for agents, not copies of the source. Preserve the existing structure, voice, and formatting. Edit the existing file; do not rewrite from scratch.
读取分配给你的源文件的Git差异。读取当前的参考文档。 将变更内容提炼整合到参考文档中——这些是为Agent准备的精选摘要，而非源文件的副本。 保留现有文档的结构、语气和格式。 编辑现有文件；请勿从头重写。

Worker Instructions: Skills

工作节点说明：Skill

Read the git diff for your assigned source files. Read the current SKILL.md. Update with new commands, changed workflows, or new capabilities. Maintain imperative voice and conciseness. Skills teach agents how to think, not just what to type. Edit the existing file; do not rewrite from scratch.
读取分配给你的源文件的Git差异。读取当前的SKILL.md文件。 更新新增命令、变更后的工作流或新功能。 保持命令式语气和简洁性。Skill旨在教会Agent如何思考，而非仅告知输入内容。 编辑现有文件；请勿从头重写。

Worker Instructions: New Skills

工作节点说明：新Skill创建

Create a new directory under the appropriate pack with a SKILL.md file. Add a 
references/
subdirectory if the skill needs detailed reference material. Follow the conventions of existing skills in the same pack.
在对应Skill包下创建新目录，并添加SKILL.md文件。 若Skill需要详细参考资料，添加
references/
子目录。 遵循同包中现有Skill的规范。

Example Worker Prompt

工作节点提示示例

You are updating a reference doc in the eve-skillpacks repository.
你正在更新eve-skillpacks仓库中的参考文档。

Your Task

你的任务

Update the file: eve-work/eve-read-eve-docs/references/secrets-auth.md
更新文件：eve-work/eve-read-eve-docs/references/secrets-auth.md

Context

上下文

The eve-horizon repo is at ../eve-horizon. Changes since commit abc1234:
  • docs/system/auth.md changed (access groups, scoped bindings)
  • docs/system/secrets.md changed (credential check improvements)
eve-horizon仓库位于../eve-horizon。自提交abc1234以来的变更：
  • docs/system/auth.md已变更（访问组、作用域绑定）
  • docs/system/secrets.md已变更（凭证校验优化）

Steps

步骤

  1. Run: cd ../eve-horizon && git diff abc1234..HEAD -- docs/system/auth.md docs/system/secrets.md
  2. Read: eve-work/eve-read-eve-docs/references/secrets-auth.md
  3. If the diff is large, also read the full source files from ../eve-horizon/docs/system/
  4. Distill the changes into the reference doc — preserve existing structure and voice
  5. Edit the existing file (do not rewrite it from scratch)
These are curated distillations for agents, not verbatim copies. Keep them concise and actionable.
undefined
  1. 执行命令：cd ../eve-horizon && git diff abc1234..HEAD -- docs/system/auth.md docs/system/secrets.md
  2. 读取文件：eve-work/eve-read-eve-docs/references/secrets-auth.md
  3. 若差异内容较大，同时读取../eve-horizon/docs/system/下的完整源文件
  4. 将变更内容提炼整合到参考文档中——保留现有结构和语气
  5. 编辑现有文件（请勿从头重写）
这些是为Agent准备的精选提炼内容，而非逐字复制。请保持内容简洁且具备可操作性。
undefined

Phase 4: Collect Results and Update Tracking (orchestrator)

阶段4：收集结果并更新跟踪信息（编排器）

Wait for all workers to complete. As each finishes, mark its work item done.
Once all update work items are complete:
  1. Get current HEAD:
    bash
    cd ../eve-horizon && git rev-parse HEAD
  2. Update 
    .sync-state.json
    :
    • Set 
      last_synced_commit
      to the HEAD hash
    • Set 
      last_synced_at
      to current ISO timestamp
    • Append to 
      sync_log
      (keep last 10 entries)
  3. Update ARCHITECTURE.md if the pack structure changed (new skills added or removed)
等待所有工作节点完成任务。每个节点完成后，标记其工作项为已完成。
所有更新工作项完成后：
  1. 获取当前HEAD提交：
    bash
    cd ../eve-horizon && git rev-parse HEAD
  2. 更新
    .sync-state.json
    文件：
    • 将
      last_synced_commit
      设置为当前HEAD哈希值
    • 将
      last_synced_at
      设置为当前ISO时间戳
    • 向
      sync_log
      中追加记录（保留最近10条）
  3. 若Skill包结构发生变更（新增或移除Skill），更新ARCHITECTURE.md文件

Phase 5: Report (orchestrator)

阶段5：生成报告（编排器）

Output a sync report summarizing all work:
undefined
输出一份同步报告，总结所有工作内容：
undefined

Sync Report: <old_commit_short>..<new_commit_short>

同步报告：<旧提交短哈希>..<新提交短哈希>

Commits

提交记录

  • <count> commits synced
  • 已同步<数量>条提交

Platform Changes

平台变更

  • <list of eve-horizon changes that affected skillpacks>
  • <影响Skill包的eve-horizon变更列表>

Updated Reference Docs

更新的参考文档

  • <file>: <what changed>
  • <文件>：<变更内容>

Updated Skills

更新的Skill

  • <skill>: <what changed>
  • <Skill>：<变更内容>

New Skills

新增的Skill

  • <skill>: <why created>
  • <Skill>：<创建原因>

Next Steps

后续步骤

  • <any manual follow-up needed> 
undefined
  • <任何需要手动跟进的事项>
undefined

Key Constraints

关键约束

  • Orchestrator context budget: The orchestrator must never read full diffs or source docs directly. It only sees: sync state JSON, sync map JSON, 
    --stat
    output, commit log, and worker result summaries.
  • Worker independence: Each worker prompt must be fully self-contained — commit range, source paths, target path, and update rules all included. Workers cannot reference the orchestrator's conversation.
  • Parallelism: All workers launch simultaneously. No worker depends on another worker's output.
  • Edit, don't rewrite: Workers modify existing files incrementally. Full rewrites lose carefully curated structure.
  • 编排器上下文预算：编排器绝不能直接读取完整差异或源文档。仅能查看：同步状态JSON、同步映射JSON、
    --stat
    输出、提交日志和工作节点结果摘要。
  • 工作节点独立性：每个工作节点的提示信息必须完全独立——包含提交范围、源路径、目标路径和更新规则。工作节点无法参考编排器的对话内容。
  • 并行性：所有工作节点需同时启动。工作节点之间无需依赖彼此的输出。
  • 增量编辑，而非重写：工作节点需增量修改现有文件。完全重写会丢失精心维护的文档结构。