archive

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

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，格式如下：

# 📒 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：为笔记添加回链

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

---

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

增量判断：

• 笔记末尾已有该回链 → 跳过
• 笔记末尾有旧版回链 → 更新为标准格式
• 笔记末尾无回链 → 追加

---

步骤 4：死链与孤岛清理

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

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

---

步骤 5：记录操作日志

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

## [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]] — 索引层在知识库架构中的定位