# Archive

> 扫描 笔记/ 下所有主题目录（排除 Wiki/），在 笔记/index.md 中建立统一的双链索引体系，并为每篇笔记添加回链。支持增量更新、索引同步、死链清理。

- Skill: `dqtx760/archive` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dqtx760/archive`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dqtx760/archive/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dqtx760 (https://skillmd.com/u/dqtx760)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dqtx760/archive

---


# archive 技能 v1.0

## 核心定位

Archive 是知识工厂的**索引编织器**：确保 `笔记/` 下的每一篇笔记都被纳入 `笔记/index.md` 的索引体系，双向链接互通，没有笔记成为"孤岛"。

---

## 目录结构约定

```
nolebase-template/
├── 笔记/
│   ├── Claude code/         ← 主题目录（需要归档索引）
│   ├── Codex/                ← 主题目录
│   ├── Obsidian/             ← 主题目录
│   ├── github/               ← 主题目录
│   ├── other/                ← 主题目录
│   ├── Wiki/                 ← 编译输出（不处理）
│   └── index.md              ← 全局索引（本技能维护的目标）
```

---

## 触发逻辑

| 触发方式 | 行为 |
|---------|------|
| `/archive` | 扫描 笔记/ 所有主题目录，生成/更新 笔记/index.md |
| `/archive <path>` | 仅处理指定目录或文件 |
| 隐式触发 | 用户说"更新一下索引"、"归档这些笔记" |

---

## 流水线

### 前置检查：增量判定

1. 读取 `笔记/index.md` 中已注册的笔记列表
2. 扫描文件系统当前的实际文件列表
3. 双向比对：
   - 新文件 → 需要新增索引条目
   - 已删除的文件 → 需要清理索引条目
   - 重命名的文件 → 需要更新索引条目
4. 如果变更 < 20% → 增量更新（只增删改个别条目）
5. 如果变更 ≥ 20% → 全量重建

---

### 步骤 1：扫描主题目录

扫描 `笔记/` 下所有子目录，**排除 `Wiki/`**。

对每个主题目录：
1. 读取目录下所有 `.md` 文件（排除已有的 `index.md`）
2. 提取每篇笔记的 frontmatter（`title`、`time`、`tags`）
3. 若无 `title` 字段，使用文件名作为标题

---

### 步骤 2：生成 index.md

生成/更新 `笔记/index.md`，格式如下：

```markdown
# 📒 index

## Claude code
- [[Claude-Code-安装]] — 2026-06-07 | 安装前置依赖与启动方式
- [[API-Key-配置]] — 2026-06-07 | 多供应商 API Key 配置方案

## Codex
- [[Codex-安装MCP]] — 2026-06-07 | MCP 安装指南

## Obsidian
- [[Obsidian-插件列表]] — 2026-06-07 | 必装插件清单
```

**每条索引条目规范：**
- 使用 wiki 双链格式 `[[笔记文件名]]`
- 文件名作为展示文字（可省略 `.md` 后缀）
- 每行紧跟 `— 日期 | 一句话摘要`
- 日期从 frontmatter 的 `time` 字段读取
- 摘要从前几行正文提取（或使用 `description` 字段）

**注意：对于中文字符或特殊字符较多的文件名，优先使用 Markdown 超链接语法 `[展示名](相对路径)` 作为降级方案，避免双链渲染异常。**

---

### 步骤 3：为笔记添加回链

在每篇笔记的正文末尾添加回链（如果不存在）：

```markdown
---

> 📎 [[笔记/index|📒 返回笔记索引]]
```

**增量判断：**
- 笔记末尾已有该回链 → 跳过
- 笔记末尾有旧版回链 → 更新为标准格式
- 笔记末尾无回链 → 追加

---

### 步骤 4：死链与孤岛清理

检查 `笔记/index.md` 中索引的所有条目：

| 问题 | 处理方式 |
|------|---------|
| 索引中的文件已不存在 | 自动删除该索引行 |
| 文件存在但不在索引中 | 自动追加索引行 |
| 文件被重命名 | 自动更新索引行（通过文件名近似匹配提示用户确认） |

---

### 步骤 5：记录操作日志

在 `笔记/Wiki/log.md` 末尾追加：

```markdown
## [YYYY-MM-DD] archive | 索引更新
- 新增条目：[[文件A]], [[文件B]]
- 删除条目：[[文件C]]（已不存在）
- 更新条目：[[文件D]]（已重命名）
- 添加回链：N 篇笔记
```

---

## 硬约束

1. ✅ **只读扫描**：生成差异报告前不修改任何文件（步骤 2-3 执行时除外）
2. ✅ **不重复追加**：每个笔记只添加一次回链，已存在则跳过
3. ✅ **不覆盖手动编辑**：如果 `笔记/index.md` 中有用户手动添加的非标准内容，保留不动，仅追加/更新标准条目区域
4. ✅ **保留降级方案**：文件名含特殊字符时自动降级为 Markdown 超链接
5. ✅ **源文件只读不改**：除追加回链外，不修改笔记正文内容

---

## 关联连接
- [[Skill_Ingest]] — ingest 完成后应自动运行 archive 更新索引
- [[Skill_Lint]] — lint 可交叉验证索引与文件系统的一致性
- [[Five_Layer_Architecture]] — 索引层在知识库架构中的定位