--- id: gh-wiki-rebuild name: "wiki-rebuild" url: https://skills.yangsir.net/skill/gh-wiki-rebuild author: ar9av domain: automation tags: ["wiki-management", "knowledge-management", "data-backup", "automation", "obsidian"] install_count: 3200 rating: 4.40 (120 reviews) github: https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-rebuild --- # wiki-rebuild > 这个技能用于管理 Obsidian 知识库的生命周期，提供归档、重建和恢复功能。它能帮助用户安全地快照当前 wiki 状态，清空并准备重新摄取数据，或从历史存档中恢复，确保知识库的稳定性和可维护性，大幅提升个人知识管理效率。 **Stats**: 3,200 installs · 4.4/5 (120 reviews) ## Before / After 对比 ### Wiki 维护效率 **Before**: 手动备份 Obsidian Wiki 需要复制大量文件，耗时且容易遗漏重要数据。当需要清空重建或恢复旧版本时，手动操作更是繁琐，可能导致数据不一致或丢失，耗费大量精力进行排查和修复。 **After**: 通过自动化技能，一键完成 Wiki 归档、清空重建准备或从历史版本恢复。整个过程标准化且快速，大大减少了手动操作的复杂性和出错率，确保数据完整性，将维护时间从数小时缩短至几分钟。 | Metric | Before | After | Change | |---|---|---|---| | Wiki 维护时间 | 120分钟 | 10分钟 | -91% | ## Readme # Wiki Rebuild — Archive, Rebuild, Restore You are performing a destructive operation on the wiki. Always archive first, always confirm with the user before proceeding. ## Before You Start 1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md` (walk up CWD for `.env` → `~/.obsidian-wiki/config` → prompt setup). This gives `OBSIDIAN_VAULT_PATH` and optional QMD settings such as `QMD_WIKI_COLLECTION` 2. Read `.manifest.json` to understand current state 3. **Confirm the user's intent.** This skill supports three modes: - **Archive only** — snapshot current wiki, no rebuild - **Archive + Rebuild** — snapshot, then reprocess all sources from scratch - **Restore** — bring back a previous archive ## The Archive System Archives live at `$OBSIDIAN_VAULT_PATH/_archives/`. Each archive is a timestamped directory containing a full copy of the wiki state at that point. ``` $OBSIDIAN_VAULT_PATH/ ├── _archives/ │ ├── 2026-04-01T10-30-00Z/ │ │ ├── archive-meta.json │ │ ├── concepts/ │ │ ├── entities/ │ │ ├── skills/ │ │ ├── references/ │ │ ├── synthesis/ │ │ ├── journal/ │ │ ├── projects/ │ │ ├── index.md │ │ ├── log.md │ │ └── .manifest.json │ └── 2026-03-15T08-00-00Z/ │ └── ... ├── concepts/ ← live wiki ├── entities/ └── ... ``` ### archive-meta.json ```json { "archived_at": "2026-04-06T10:30:00Z", "reason": "rebuild", "total_pages": 87, "total_sources": 42, "total_projects": 6, "vault_path": "/Users/name/Knowledge", "manifest_snapshot": ".manifest.json" } ``` ## Mode 1: Archive Only When the user wants to snapshot the current state without rebuilding. ### Steps: 1. Create archive directory: `_archives/YYYY-MM-DDTHH-MM-SSZ/` 2. Copy all category directories, `index.md`, `log.md`, `.manifest.json`, and `projects/` into the archive 3. Write `archive-meta.json` with reason `"snapshot"` 4. Append to `log.md`: ``` - [TIMESTAMP] ARCHIVE reason="snapshot" pages=87 destination="_archives/2026-04-06T10-30-00Z" ``` 5. Optionally refresh QMD if `log.md` is indexed and `QMD_WIKI_COLLECTION` is configured (see "QMD Refresh After Live Wiki Changes"). 6. Report: "Archived 87 pages. Current wiki is untouched." ## Mode 2: Archive + Rebuild When the user wants to start fresh. This is the full sequence: ### Step 1: Archive current state Same as Mode 1 above, but with reason `"rebuild"`. ### Step 2: Clear live wiki Remove all content from the category directories (`concepts/`, `entities/`, `skills/`, etc.) and the `projects/` directory. Keep: - `_archives/` (obviously) - `.obsidian/` (Obsidian config) - `.env` (if present in vault) Reset `index.md` to the empty template. Reset `log.md` with just the rebuild entry. Delete `.manifest.json` (it'll be recreated during ingest). ### Step 3: Rebuild Tell the user the vault is cleared and ready for a full re-ingest. They can now run: 1. `wiki-status` — to see all sources as "new" 2. `claude-history-ingest` — to reprocess Claude history 3. `codex-history-ingest` — to reprocess Codex session history 4. `wiki-ingest` — to reprocess documents 5. `data-ingest` — to reprocess any other data Each of these will rebuild the manifest as they go. **Important:** Don't run the ingest yourself automatically. The user should choose what to re-ingest and in what order. Some sources may no longer be relevant. ### Step 4: Log the rebuild Append to `log.md`: ``` - [TIMESTAMP] REBUILD archived_to="_archives/2026-04-06T10-30-00Z" previous_pages=87 ``` Refresh QMD after clearing and logging the live wiki (see "QMD Refresh After Live Wiki Changes"), then report that the vault is ready for selected re-ingest skills. ## Mode 3: Restore from Archive When the user wants to go back to a previous state. ### Step 1: List available archives Read `_archives/` directory. For each archive, read `archive-meta.json` and present: ```markdown ## Available Archives | Date | Reason | Pages | Sources | |---|---|---|---| | 2026-04-06 10:30 | rebuild | 87 | 42 | | 2026-03-15 08:00 | snapshot | 65 | 31 | ``` ### Step 2: Confirm which archive to restore Ask the user which archive they want. Warn them that restoring will overwrite the current live wiki. ### Step 3: Archive current state first Before restoring, archive the current state (reason: `"pre-restore"`) so nothing is lost. ### Step 4: Restore 1. Clear the live wiki (same as Mode 2, Step 2) 2. Copy all content from the chosen archive back into the live wiki directories 3. Restore `index.md`, `log.md`, and `.manifest.json` from the archive 4. Append to `log.md`: ``` - [TIMESTAMP] RESTORE from="_archives/2026-03-15T08-00-00Z" pages_restored=65 ``` ### Step 5: Report Refresh QMD after restore (see "QMD Refresh After Live Wiki Changes"), then tell the user what was restored and suggest running `wiki-lint` to check for any issues with the restored state. ## QMD Refresh After Live Wiki Changes QMD is a search index, not the source of truth. If QMD refresh fails, do not roll back archive, rebuild, or restore work; report the failure and leave the markdown vault intact. **GUARD: If `$QMD_WIKI_COLLECTION` is empty or unset, skip this step.** When to run: | Mode | Refresh QMD? | Reason | |---|---|---| | Archive only | Optional | Live wiki content is unchanged except `log.md`; refresh if `log.md` is indexed and QMD is configured. | | Archive + Rebuild | Required after clearing live wiki | QMD must forget deleted pages or it will return stale search results. Later ingest skills will refresh again as sources are reprocessed. | | Restore | Required after restore | The live wiki was replaced with archive content, so QMD must match the restored state. | This refresh currently requires the local QMD CLI. Use `$QMD_CLI` if set; otherwise use `qmd`. If the CLI is unavailable, report `QMD skipped: qmd CLI unavailable`. For CLI refresh: ```bash ${QMD_CLI:-qmd} update ``` If the output says new hashes need vectors, or if restore replaced live pages and embeddings may be stale, run: ```bash ${QMD_CLI:-qmd} embed ``` Verify the wiki collection reflects the operation: ```bash ${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION" ``` For restore, also verify one restored page if the archive has a known page path: ```bash ${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/.md" -l 5 ``` Record QMD refresh in the final report as one of: - `QMD refreshed: update + embed + verified` - `QMD refreshed: update only + verified` - `QMD skipped: QMD_WIKI_COLLECTION unset` - `QMD skipped: archive-only live content unchanged` - `QMD skipped: qmd CLI unavailable` - `QMD failed: ` ## Safety Rules 1. **Always archive before destructive operations.** No exceptions. 2. **Always confirm with the user** before clearing the live wiki. 3. **Never delete archives** unless the user explicitly asks. Archives are cheap insurance. 4. **The `.obsidian/` directory is sacred.** Never touch it during archive/rebuild/restore — it contains the user's Obsidian settings, plugins, and themes. 5. If something goes wrong mid-rebuild, the archive is there. Tell the user they can restore. --- *Source: https://skills.yangsir.net/skill/gh-wiki-rebuild* *Markdown mirror: https://skills.yangsir.net/api/skill/gh-wiki-rebuild/markdown*