# Eo Archive

> 将已审查通过的 change 的 Spec Delta 合并回模块 spec.md，完成变更闭环。触发：归档 change / archive / 合并 delta / /eo-archive。

- **Type:** Skill
- **Install:** `agentstack add skill-simpleeve-eo-skills-eo-archive`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SimpleEve](https://agentstack.voostack.com/s/simpleeve)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SimpleEve](https://github.com/SimpleEve)
- **Source:** https://github.com/SimpleEve/eo-skills/tree/main/eo-archive

## Install

```sh
agentstack add skill-simpleeve-eo-skills-eo-archive
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# eo-archive — 变更归档

把已审查通过的 change 的 **Spec Delta** 机械合并回模块 `spec.md`，并更新索引、修改 change 状态。这是 change 生命周期的最后一步，也是保持 spec 常青的关键。

## 核心理念

1. **Delta 驱动**：只消费 change.md 的 `## 3 Spec Delta` 章节，不重新理解业务
2. **机械合并**：ADDED/MODIFIED/REMOVED 按声明直接落到 spec.md 对应章节
3. **冲突不硬吞**：若 Delta 与现有 spec 冲突（如 MODIFIED 的"旧描述"在 spec 中找不到），停下来让用户裁决
4. **一次性闭环**：归档后 change 状态变为 `archived`，不再允许修改

## 前置条件

- **必须能找到 `.eo-project.json`**（cwd 或父目录）。找不到 → 报错退出，提示运行 `/eo-project-init`。所有 `eo-doc/` 路径通过 `.eo-project.json` 的 `doc_root` 字段解析
- 用户给定 `` 和 ``（如 `/eo-archive inventory 015-add-sort`）
- `eo-doc/dev//spec.md` 存在
- `eo-doc/dev//spec-history.md` 存在（旧模块若缺失，第五步会按模板补建，不视为前置失败）
- `eo-doc/dev//changes//change.md` 存在且 `status: done`
- 对应的 `review.md` 存在且审查通过（无 P0/P1 剩余）
- 对应的 `test.md` 存在且通过（若 change 要求了测试）

若任一前置条件不满足 → 停止并告知用户原因。

## 工作流程

### 第一步：读取并验证

1. 读 `changes//change.md`，验证 `status: done`
2. **从 frontmatter 读取 `change_type`**，确定归档模式：
   - `bootstrap` → **实现范围模式**（跳过 Delta 合并，只更新元信息与索引）
   - `feature` / `enhance` / `refactor` → **Delta 合并模式**（执行后续所有步骤）
3. 读 `changes//review.md`，确认结论为通过
4. 读 `changes//test.md`（若存在），确认通过
5. 读模块 `spec.md` —— **不整篇读**（spec 是活文档，可能超出单次读取上限）：
   - 先读 frontmatter，再用 `Grep`（pattern `^#{1,3} `、带行号）取章节地图
   - Delta 模式：按章节地图用 `Read` 的 offset/limit 定位到 Delta 涉及的章节，不读无关章节
   - bootstrap 模式：spec.md 正文无需读，章节地图留作第八步"剩余未认领章节"汇报用

### 第二步：解析 Delta（仅 Delta 模式）

> **bootstrap 模式跳过此步**，直接进入第五步。

从 `change.md` 的 `## 3 Spec Delta` 提取三类条目：
- **ADDED 列表**：每条含"能力名 + 描述 + spec 目标章节"
- **MODIFIED 列表**：每条含"能力名 + 旧描述 + 新描述 + spec §X.Y"
- **REMOVED 列表**：每条含"能力名 + spec §X.Y"

若 Delta 章节为空或格式不符 → 提示用户修复 change.md 后重跑。

**⚠️ 拒绝跨模块 Delta**：所有 Delta 条目的目标章节必须位于**本模块**的 `spec.md`。若出现以下任一信号，**停止归档**并要求用户拆 change：

- 条目声明的 spec 路径指向其他模块（如 change 在 `inventory/` 下但 Delta 写"合并到 building/spec.md §3"）
- 条目描述中出现"同时修改 X 模块的 spec"之类措辞
- change frontmatter `module` 字段与目录路径中的模块名不一致

反馈模板：
> ⚠️ 本 change 的 Delta 含跨模块条目（`` 指向 `/spec.md`）。
> eo-archive 只能合并单一模块的 Delta。请按 `/eo-change` 的"单模块 vs 跨模块"规则：
>   1. 将跨模块部分抽出为另一个 change（归属对方模块）
>   2. 用 `depends_on` frontmatter 关联两个 change
>   3. 按依赖顺序分别归档
> 详见 `eo-change/SKILL.md` 的"判断边界：单模块 vs 跨模块"。

**bootstrap 额外校验**：若 change_type = bootstrap 但 §3 写了 ADDED/MODIFIED/REMOVED → 停止归档，要求作者把类型改一致（或改为 feature/enhance），两者二选一。

### 第三步：冲突预检（仅 Delta 模式）

> **bootstrap 模式跳过此步**。

**MODIFIED 项**：在 spec.md 对应章节搜索"旧描述"，若找不到（可能 spec 在这之间被其他 change 改过）→ 列出冲突项，让用户选择：
- 跳过该条
- 手动指定合并位置
- 终止归档

**REMOVED 项**：在 spec.md 对应章节搜索待删除内容，若找不到 → 同上处理。

**ADDED 项**：确认目标章节存在；若目标章节不存在，提示用户先修 change.md 或允许追加到章节末尾。

### 第四步：执行合并（仅 Delta 模式）

> **bootstrap 模式跳过此步**，spec.md 内容保持不变。

对 spec.md 逐条应用 Delta：
- **ADDED**：在指定章节末尾追加新条目
- **MODIFIED**：定位旧描述，替换为新描述
- **REMOVED**：删除指定条目

所有合并操作用 Edit 工具逐条执行，保持 diff 清晰。

### 第五步：更新 spec-history.md 与 spec.md 元信息

> **bootstrap 与 Delta 模式均执行此步。** 归档流水统一落到 `spec-history.md`，不再写入 spec.md 正文。

1. **定位 `eo-doc/dev//spec-history.md`**：
   - 存在 → 直接使用
   - 不存在（本次改造前建的旧模块）→ 按 spec-template.md 的 spec-history.md 模板补建；若旧 `spec.md` 仍内联 `## 9 关联变更` / `## 10 变更记录`，把已有表行整体迁入新文件后，再从 spec.md 删除这两个章节（其余正文不动）
2. 在 spec-history.md 的 `## 关联变更` 表末尾追加一行：
   ```
   | [](changes//change.md) | YYYY-MM-DD |  |
   ```
   bootstrap 模式下 summary 前缀加 `[bootstrap]`，如 `[bootstrap] 实现 §3.1 / §3.3`
3. 在 spec-history.md 的 `## 变更记录` 表末尾追加一行：
   - Delta 模式：`| YYYY-MM-DD | 归档 :  | eo-archive |`
   - bootstrap 模式：`| YYYY-MM-DD | bootstrap 实现  () | eo-archive |`
4. spec-history.md frontmatter `updated` 改为今天日期
5. **spec.md frontmatter `updated`**：
   - Delta 模式 → 改为今天日期（第四步已改动 spec.md 正文）
   - bootstrap 模式 → **不动 spec.md**（正文与元信息均不变，归档活动只记录在 spec-history.md；唯一例外是步骤 1 对旧模块的一次性 §9/§10 迁移）

### 第六步：更新 change.md

1. frontmatter `status` 从 `done` 改为 `archived`
2. frontmatter `updated` 改为今天日期（即归档日期）

### 第七步：更新索引

1. 更新 `eo-doc/dev//changes/INDEX.md`：找到对应行把 status 列改为 `archived`
2. 更新 `eo-doc/dev/INDEX.md`：若该模块条目需要刷新最近活动时间，同步

### 第八步：汇报结果 + 可选复检建议

向用户汇报：

**Delta 模式**：
- 合并的 Delta 条数（ADDED N / MODIFIED N / REMOVED N）
- spec.md 受影响的章节列表
- 冲突处理记录（若有）
- spec-history.md 已追加本次归档记录
- change 状态已改为 archived

**bootstrap 模式**：
- 实现的 spec 章节列表（来自 §3.B.1）
- 该模块剩余未被任何 bootstrap 认领的 spec 章节（提示用户后续可继续拆 bootstrap change）
- spec.md 未变更；归档记录已追加到 spec-history.md
- change 状态已改为 archived

**spec 复检建议**：根据本次归档对 spec 的影响给出建议：

| 触发条件 | 建议文案 |
|---------|---------|
| MODIFIED ≥ 3 条 或 REMOVED ≥ 1 条 | 💡 本次 Delta 对 spec 做了 N 条 MODIFIED / M 条 REMOVED，建议跑一次 `/eo-spec-review ` 验证新基线仍然自洽 |
| 涉及 spec 章节 ≥ 3 个 | 💡 本次 Delta 触及 spec 的 N 个章节，建议跑一次 `/eo-spec-review` 确认跨章节一致性 |
| 仅少量 ADDED | 无需复检建议 |
| bootstrap 模式（任何规模） | 无需复检（spec 未变） |

**提示但不强制**：复检是可选的，用户决定是否跑。

---

## 冲突处理模板

当遇到无法自动合并的 Delta 时，向用户呈现：

```
⚠️ Delta 冲突：

[MODIFIED-2] 库存上限逻辑
  - 预期的旧描述（change.md 声明）：
    "玩家最多持有 100 件同类物品"
  - spec.md §3.4 当前实际内容：
    "玩家最多持有 120 件同类物品（v1.5 提升）"

可能原因：本 change 与之前某个 change 对 §3.4 有并发修改。

请选择：
  1. 跳过此条（Delta 不合并，由用户手动处理）
  2. 强制替换（用新描述覆盖当前实际内容）
  3. 终止归档
```

---

## 关键约束

- **只做合并，不做二次澄清**：归档阶段不问业务问题，所有澄清应在 change 阶段完成
- **冲突必须停下**：绝不自作主张解决冲突
- **归档不可逆**：archived 状态的 change 不再修改；若需修正，发起新的 change 来覆盖
- **§3 完整性校验**：
  - Delta 模式：§3 没写 Delta 或格式错误 → 拒绝归档
  - bootstrap 模式：§3.B.1 没写认领章节 → 拒绝归档
- **类型内容一致**：change_type 与 §3 内容必须匹配（bootstrap 不能有 Delta，反之亦然），错配 → 拒绝归档
- **单一目标 spec**：一个 change 只能归档到单一模块的 `spec.md`。Delta 含跨模块条目 → 拒绝归档，要求拆 change（见第二步）
- **bootstrap 不动 spec.md**：归档记录只追加到 spec-history.md，spec.md 正文与元信息均不变
- **保持 diff 可读**：用 Edit 逐条合并，不要 Write 整文件覆盖 spec.md

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SimpleEve](https://github.com/SimpleEve)
- **Source:** [SimpleEve/eo-skills](https://github.com/SimpleEve/eo-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-simpleeve-eo-skills-eo-archive
- Seller: https://agentstack.voostack.com/s/simpleeve
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.