sync-horizon

Sync Horizon

将 eve-skillpacks 与 eve-horizon 仓库的最新状态同步。

核心认识

系统文档往往落后于实现。功能通过标记为“Implemented”的 feat 提交发布，但 docs/system/ 可能数周都不更新。本次同步直接追溯源头：计划、代码变更和提交消息能说明哪些功能实际已发布。系统文档只是多个信号之一，并非主要依据。

先决条件

• eve-horizon 仓库必须位于 ../eve-horizon（同级目录）
• 仓库根目录中必须存在 .sync-state.json（若不存在，请根据模板创建）
• 仓库根目录中必须存在 .sync-map.json

架构：协调器 + 并行工作者

你（协调器）负责发现已发布的内容，并分派有明确范围的工作者。每个工作者独立处理一项更新，并使用各自的上下文预算。

协调器读取轻量信号（提交日志、计划标题、文件统计、CLI 模块列表）。工作者读取大量内容（计划正文、代码差异、源文档、目标文件）。

输出标准

• 仅提炼已发布的平台行为。标记为 Implemented/Complete 的计划描述的是已发布的功能。
• 不要将路线图内容带入 skillpacks。忽略标记为 Proposed/Draft 的计划，以及 Planned (Not Implemented)、What's next 等章节或“当前与计划”的表述方式。
• 让 eve-work/eve-read-eve-docs/SKILL.md 以任务为先：根据意图分流，并且只加载所需的最少参考文件。
• 让参考文档范围明确且可操作——经过筛选提炼，而非直接复制。

工作流

阶段 1：深入发现（协调器）

从多个维度读取轻量信号，了解实际已发布的内容。

1a. 提交日志

cd ../eve-horizon && git log --oneline <last_synced_commit>..HEAD

提交分类：

• feat:——新功能（主要关注）
• fix:——可能影响文档所述行为的错误修复
• docs:——文档变更（检查其是否描述了已发布的功能）
• chore: / refactor:——通常不会影响 skillpack，但要留意删除内容

1b. 计划分析

这是最丰富的信号。计划会说明已发布的内容、原因和实现方式。

cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/plans/

对于每个变更的计划，仅阅读其标题（前 15-20 行），提取状态：

cd ../eve-horizon && head -20 docs/plans/<plan-file>.md

分类：

• 已发布：状态包含 Implemented、Complete 或 Done——这是新功能的主要事实来源
• 进行中：状态包含 In Progress、Partially Implemented——记录以供了解，但不要提炼尚未完成的工作
• 拟议/草稿：状态包含 Proposed、Plan、Draft、Ready to build——完全跳过
• 已移除：此时间范围内删除的计划文件——说明某项内容已弃用或放弃

重要：不要阅读完整的计划正文，只看标题。工作者会阅读所需的计划。

1c. 代码信号

新的 CLI 命令、DB 迁移和软件包变更可确认哪些内容已发布，并揭示计划可能未充分说明的功能。

# New/changed/removed CLI commands
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/cli/src/commands/

# New DB migrations (table/column names reveal capability shape)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/db/migrations/

# Key package changes (new modules, removed modules)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/shared/src/ packages/api/src/ packages/worker/src/ packages/gateway/src/ --stat-name-width=120 | head -50

1d. 系统文档变更

这仍是有用的信号，尤其适用于发现删除和更正。

cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/system/ AGENTS.md

1e. 当前 CLI 表面

记录当前 CLI 命令模块的快照。这是 Agent 可调用内容的事实依据。

cd ../eve-horizon && ls packages/cli/src/commands/*.ts

阶段 2：能力综合（协调器）

停下来思考。 这是关键步骤。交叉比对所有信号，构建能力映射。

为每个已发布的计划（Implemented/Complete）创建一个能力条目：

Capability: <name>
  Plan: docs/plans/<file>.md (status: Implemented)
  Feat commits: <matching commit hashes>
  Code signal: <new CLI commands, new migrations, new/removed modules>
  System doc: <updated/created/unchanged>
  Scope: <which platform areas this touches>
  One-line summary: <what this capability does, from the plan header>

还要为有 feat 提交佐证但没有对应计划的功能创建条目——这些是直接发布的小型功能或修复。

同时记录移除项：已删除的计划、CLI 命令和模块。这些也需要从我们的 skills 中清理。

阶段 3：级联分析（协调器）

针对映射中的每项能力，确定其对 eve-read-eve-docs 的影响：

3a. 参考文档影响

对于每项能力，请询问：

1. 现有参考文档是否已涵盖此领域？→ Worker 更新文档
2. 这是需要单独编写参考文档的新原语吗？→ Worker 创建文档
3. 是否有内容已移除？→ Worker 清理受影响参考文档中的过时内容

对照 eve-work/eve-read-eve-docs/SKILL.md 中当前的参考索引，以及 .sync-map.json 的 reference_docs 部分。

3b. SKILL.md 路由影响

检查 eve-work/eve-read-eve-docs/SKILL.md 是否需要：

• 在 Task Router 中新增条目
• 在 Index 中新增条目
• 在 Intent Coverage Matrix 中新增行
• 在 frontmatter 中新增触发关键词
• 移除已弃用能力对应的过时条目

3c. 其他技能的影响

检查 .sync-map.json 中的 skill_triggers 和 composite_triggers，找出受影响的其他技能。还需考虑：

• eve-se/eve-manifest-authoring — 如果 manifest 结构发生变化
• eve-se/eve-deploy-debugging — 如果部署／基础设施行为发生变化
• eve-se/eve-auth-and-secrets — 如果身份验证模型发生变化
• eve-work/eve-agent-memory — 如果存储原语发生变化
• eve-design/eve-fullstack-app-design — 如果应用模式发生变化

第 4 阶段：规划工作项（协调者）

对于第 3 阶段确定的每项更新，创建一个工作项：

• 标题：Update <target-file>: <capability name>
• 描述 — 包含 Worker 独立开展工作所需的一切信息：
  • eve-horizon 仓库路径（../eve-horizon）
  • 提交范围：<last_synced_commit>..HEAD
  • 需要阅读的计划（与此次更新相关的已发布计划）
  • 需要对比或阅读的源文件（代码、系统文档）
  • 要更新或创建的目标文件路径
  • 说明这是参考文档更新、技能更新、新增参考文档，还是移除内容
  • 下文中适用的 Worker 指引

添加最后一个工作项：Update sync state and produce report — 等待所有更新完成后再执行。

如果任何工作项涉及 eve-work/eve-read-eve-docs，还需添加：

• Run state-today compliance scan for eve-read-eve-docs
• Validate progressive-access routing in eve-read-eve-docs/SKILL.md
• Update .sync-map.json with any new reference doc mappings

第 5 阶段：分派 Worker（并行）

为每个工作项启动一个后台 Worker，并一次性启动所有 Worker。

每个 Worker 提示词都必须自包含。 Worker 无法访问协调者的对话内容。请包含：

1. 要阅读的计划文件——这些是主要事实来源
2. 用于相关代码／文档变更的 git diff 命令
3. 要阅读和修改的目标文件
4. 第 2 阶段的能力摘要
5. 下文中适用的 Worker 指引

Worker 指引：更新参考文档

主要信息来源是已发布计划（标记为 Implemented/Complete）和代码变更。 系统文档为次要来源——可能滞后或缺失。

1. 阅读任务中列出的计划——了解已发布的内容及其原因。
2. 阅读要更新的当前参考文档。
3. 对相关源文件（代码、系统文档）运行 git diff。
4. 如果计划提及特定 CLI 命令或 API，请确认它们存在：

   cd ../eve-horizon && ls packages/cli/src/commands/<name>.ts
   

5. 将已发布的能力提炼到参考文档中：
   • 功能说明（依据计划和代码）
   • 使用方法（CLI 命令、manifest 配置、API 调用）
   • 关键限制或要求
6. 排除路线图内容。只记录已实现的内容。
7. 编辑现有文件；不要从头重写。
8. 保留现有结构、语气和格式。

Worker 指令：新增参考文档

1. 阅读描述此功能的计划。
2. 检查系统文档是否涵盖此功能：cd ../eve-horizon && cat docs/system/<name>.md（可能不存在）。
3. 如适用，阅读 CLI 命令源码：cd ../eve-horizon && cat packages/cli/src/commands/<name>.ts
4. 创建参考文档，并遵循 eve-work/eve-read-eve-docs/references/ 中现有参考文档的规范。
5. 包含：用途、CLI 命令/标志、相关的清单配置、关键行为、限制。
6. 内容保持简洁，并便于 Agent 执行操作。这些文档是提炼总结，不是文档副本。
7. 仅描述当前状态，不包含计划或路线图内容。

Worker 指令：更新 Skill

主要依据是已发布的计划和代码变更。

1. 阅读任务中列出的计划。
2. 阅读要更新的当前 SKILL.md。
3. 补充新命令、变更后的工作流或新功能。
4. 删除涉及已弃用功能的过时内容。
5. 仅描述当前状态，并确保渐进式披露。
6. 使用祈使语气，保持简洁。
7. 编辑现有文件；不要从头重写。

Worker 指令：更新 SKILL.md 路由

此 Worker 负责更新 eve-read-eve-docs SKILL.md 中的路由、索引和覆盖矩阵。

1. 阅读当前的 eve-work/eve-read-eve-docs/SKILL.md。
2. 针对其他 Worker 创建的每份新参考文档，添加：
   • 一条任务路由条目，说明何时加载该文档
   • 一条索引条目，包含文件路径和一行说明
   • 如果该文档对应独立的用户意图，则添加一行意图覆盖矩阵条目
3. 对于已移除的功能，清理过时的路由条目。
4. 在 YAML frontmatter 中添加任何新的触发关键词。
5. 各部分内保持按字母顺序或逻辑顺序排列。

Worker 指令：检查内容是否过时

这是一个横跨多个平台基础组件的 Skill。 你的任务是验证 Skill 中的声明是否符合平台当前实际情况。

1. 阅读 SKILL.md 及其 references/ 目录中的所有文件。
2. 阅读任务中列出的已发布计划，了解变更背景。
3. 列出当前 CLI 命令模块：

   cd ../eve-horizon && ls packages/cli/src/commands/*.ts
   

4. 扫描 Skill 中是否存在过时声明：
   • “没有专用的 X” / “不提供 X” / “尚不支持 X”——检查现在是否已有相关功能。
   • “当前缺陷”或“变通方案”部分——确认其中列出的每个问题是否仍然存在。
   • 决策表或比较矩阵——检查是否缺少条目。
   • 对已移除功能的引用（例如 inference/ollama/managed-models）。
5. 如果发现过时声明，请更新 Skill。添加新的基础组件，移除错误的缺口描述。
6. 仅描述当前状态。使用祈使语气，保持简洁。
7. 编辑现有文件；不要从头重写。

报告过时内容以及你所做的修正。

Worker 指令：更新同步映射

更新 .sync-map.json，纳入本次同步中发现的新映射。

1. 阅读当前的 .sync-map.json。
2. 对于创建的每份新参考文档，添加一条 reference_docs 映射，将源文件映射到目标文件。
3. 对于发现的每种新 Skill 触发关系，添加一条 skill_triggers 条目。
4. 对于已移除的源文档，清理过时映射。
5. 确保 watch_paths 涵盖所有需要监控的新目录。

Worker 提示词示例

You are updating a reference doc in the eve-skillpacks repository.

## Your Task
Update the file: eve-work/eve-read-eve-docs/references/agents-teams.md
Add coverage for agent aliases (short names for chat addressing).

## Capability Summary
Agent aliases let users declare short names for agents instead of using full
project-slug-agent-name. Declared in manifest under `agents[].alias`. Resolved
at chat dispatch time. Status: Implemented.

## Primary Source
Read the plan: cd ../eve-horizon && cat docs/plans/agent-aliases-plan.md

## Code Confirmation
The agents CLI was updated: cd ../eve-horizon && git diff <commit>..HEAD -- packages/cli/src/commands/agents.ts
New migration: packages/db/migrations/00076_add_agent_alias.sql

## Target
Read and edit: eve-work/eve-read-eve-docs/references/agents-teams.md

## Rules
- Distill only shipped behavior from the plan and code
- Edit the existing file; do not rewrite from scratch
- These are curated distillations for agents, not copies
- Keep it concise and actionable

第 6 阶段：收集结果并完成（orchestrator）

等待所有 Worker 完成。

所有更新工作项完成后：

1. 获取当前 HEAD：

   cd ../eve-horizon && git rev-parse HEAD
   

2. 运行当前状态和渐进式访问检查：

   ./private-skills/sync-horizon/scripts/check-state-today.sh
   

3. 更新 .sync-state.json：
   • 将 last_synced_commit 设置为 HEAD 哈希
   • 将 last_synced_at 设置为当前 ISO 时间戳
   • 追加到 sync_log（保留最近 10 条记录）

第 7 阶段：报告（orchestrator）

## Sync Report: <old_commit_short>..<new_commit_short>

### Commits
- <count> commits synced (<feat count> features, <fix count> fixes)

### Shipped Capabilities (from plans)
- <capability>: <one-line summary> (plan status, feat commits)

### Capability Cascade
For each shipped capability:
- <capability> → updated <reference/skill>, because <reason>

### Removals
- <what was removed/deprecated and cleaned from skills>

### Updated Reference Docs
- <file>: <what changed and why>

### New Reference Docs
- <file>: <what it covers>

### Updated Skills
- <skill>: <what changed>

### SKILL.md Routing Changes
- <new routes, index entries, or coverage matrix rows>

### Sync Map Changes
- <new mappings added>

### State-Today Compliance
- <pass/fail + scan results>

### Coverage Gaps
- <shipped capabilities with no reference doc yet>
- <plan files with no sync-map entry>
- <CLI commands with no documentation coverage>

### Next Steps
- <manual follow-up needed>

关键约束

• 计划是了解已交付内容的主要事实来源。系统文档是次要来源。代码更改用于确认。
• 编排器只读取轻量级信号：提交日志、计划标题（前 15-20 行）、文件统计信息、CLI 模块列表。绝不读取完整计划、完整差异或源文档。
• 工作者读取大量内容：完整计划、代码差异、源文档、目标文件。
• 工作者独立性：每个工作者提示词都必须自成一体，包含计划路径、代码路径、目标路径、能力摘要和更新规则。
• 并行执行：所有工作者同时启动。任何工作者都不依赖其他工作者的输出（路由更新工作者除外，它应在参考文档工作者完成后启动）。
• 编辑而非重写：工作者应逐步修改现有文件。
• 忠实反映当前状态：仅记录已交付、已实现的行为。
• 渐进式访问：在入口技能中保留以任务为先的路由方式，并将深入细节放在参考文档中。