wiki-setup

Obsidian 设置 — Vault 初始化

你正在设置一个新的 Obsidian wiki vault（或修复现有 vault）。

步骤 1：创建 .env

如果 .env 不存在，请从 .env.example 创建。询问用户：

1. Vault 应放在哪里？ → OBSIDIAN_VAULT_PATH

   • 默认值：~/Documents/obsidian-wiki-vault
   • 必须是绝对路径（展开后）

2. 源文档在哪里？ → OBSIDIAN_SOURCES_DIR

   • 可以有多个路径，以逗号分隔
   • 默认值：~/Documents
   • 本地 git 仓库克隆（公开或私有，任意托管平台）也可以列在这里——先在本地克隆 仓库，然后添加其路径。有关如何处理仓库源，请参阅 wiki-ingest/SKILL.md 中的“Ingesting Git Repositories”。

3. 要导入 Claude 历史记录吗？ → CLAUDE_HISTORY_PATH

   • 默认值：自动从 ~/.claude 发现
   • 如果 Claude 数据位于其他位置，请显式设置

4. 已安装 QMD 吗？ → QMD_WIKI_COLLECTION / QMD_PAPERS_COLLECTION / QMD_TRANSPORT

   • 可选。为 wiki-query 启用语义搜索，并为 wiki-ingest 启用源发现。
   • 默认使用 QMD_TRANSPORT=mcp，除非用户希望 Agent 直接调用本地 qmd CLI。
   • 如果使用 CLI 模式，默认设置 QMD_CLI_SEARCH_MODE=quality；如果重排太慢，建议使用 balanced。
   • 如果不确定，暂时跳过——两项技能都会自动回退到 Grep。
   • 安装说明：参阅 .env.example（QMD 部分）。
   • 如果设置了 QMD_WIKI_COLLECTION，请确认该集合排除了 _raw/。 Wiki 集合和论文集合必须保持互斥——wiki-query 会将它们作为独立层引用 （编译后的知识与原始暂存内容），而 OBSIDIAN_VAULT_PATH 包含 _raw/，因此直接执行 qmd collection add <vault> 会悄悄合并两者。 阅读 ~/.config/qmd/index.yml，找到 $QMD_WIKI_COLLECTION 对应的条目，并检查其 ignore 列表是否包含 _raw/**（最好也包含没有语义价值的 log.md）。如果 该集合尚不存在，请创建它（qmd collection add "$OBSIDIAN_VAULT_PATH" --name <collection-name>），然后手动将 ignore 块添加到 index.yml 中——qmd 没有 --ignore 标志，并且会拒绝对已添加过的路径再次执行 collection add， 因此只能通过编辑 YAML 来设置范围。编辑后运行 qmd update。 如果集合已存在但没有 ignore 块，请告知用户其 wiki 集合正在索引 _raw/（包括 wiki-ingest 遗留的 _raw/_archived/ 草稿），并询问是否要添加 ignore 块并重新运行 qmd update。

5. Token 预算警告阈值？ → WIKI_TOKEN_WARN_THRESHOLD

   • 默认值：100000（完整读取 wiki 的成本超过 100K 个 token 时发出警告）
   • 设置为 0 可完全禁用警告
   • wiki-status 会显示 token 占用表，并自动发出此警告

6. 启用暂存写入吗？ → WIKI_STAGED_WRITES

   • 默认值：未设置 / false（页面直接写入最终位置）
   • 对团队 wiki、高风险领域，或用户希望对大模型编写的每个页面进行最终审批的 vault，设置为 true
   • 启用后：所有新建或更新的页面都会先写入 _staging/；运行 /wiki-stage-commit 以审核并发布这些页面
   • 有文件等待处理时，wiki-status 会显示“待处理的暂存写入”数量 解析配置后，使用 .skills/llm-wiki/SKILL.md 中 Config Resolution Protocol 的 obsidian_wiki_config_dir 算法，准确设置全局配置目录。仅在共享写作配置文件不存在时创建。保留现有的 $GLOBAL_CONFIG_DIR/WRITING.md；绝不覆盖，也不要再询问写作风格相关问题。

如果从配置中加载了 OBSIDIAN_WIKI_REPO，则使用它。如果没有，则根据此已加载技能的绝对路径，推导绝对仓库／数据根目录，并区分打包布局 <root>/skills/wiki-setup/SKILL.md 和源码布局 <root>/.skills/wiki-setup/SKILL.md。然后检查以下两种规范模板布局：

• 打包安装：<root>/skills/llm-wiki/references/WRITING.md
• 源码检出：<root>/.skills/llm-wiki/references/WRITING.md

GLOBAL_CONFIG_DIR="$(obsidian_wiki_config_dir)"
mkdir -p "$GLOBAL_CONFIG_DIR"

SKILL_FILE="<absolute path of this loaded wiki-setup/SKILL.md>"
SKILL_DIR="$(cd "$(dirname "$SKILL_FILE")" && pwd)"
if [ -n "${OBSIDIAN_WIKI_REPO:-}" ]; then
  WIKI_ROOT="${OBSIDIAN_WIKI_REPO%/}"
else
  case "$SKILL_DIR" in
    */.skills/wiki-setup) WIKI_ROOT="${SKILL_DIR%/.skills/wiki-setup}" ;;
    */skills/wiki-setup) WIKI_ROOT="${SKILL_DIR%/skills/wiki-setup}" ;;
    *) echo "Cannot derive writing-profile template root from $SKILL_DIR" >&2; exit 1 ;;
  esac
fi

WRITING_TEMPLATE=""
for candidate in \
  "$WIKI_ROOT/skills/llm-wiki/references/WRITING.md" \
  "$WIKI_ROOT/.skills/llm-wiki/references/WRITING.md"
do
  if [ -f "$candidate" ]; then
    WRITING_TEMPLATE="$candidate"
    break
  fi
done
[ -n "$WRITING_TEMPLATE" ] || { echo "Writing profile template not found under $WIKI_ROOT" >&2; exit 1; }

WRITING_PROFILE="$GLOBAL_CONFIG_DIR/WRITING.md"
if [ ! -e "$WRITING_PROFILE" ]; then
  cp "$WRITING_TEMPLATE" "$WRITING_PROFILE"
fi

步骤 2：创建 Vault 目录结构

mkdir -p "$OBSIDIAN_VAULT_PATH"/{concepts,entities,skills,references,synthesis,journal,projects,_archives,_raw,_staging,.obsidian}

• .obsidian/ — Obsidian 自身的配置，用于识别 Vault。
• projects/ — 每个项目的知识库（在摄取过程中填充）。
• _archives/ — 存储用于重建／恢复操作的 Wiki 快照。
• _raw/ — 未处理草稿的暂存区。将粗略笔记放在这里；wiki-ingest 会将其整理为正式的 Wiki 页面，并把原始文件移到 _raw/_archived/（首次使用时创建）。
• _staging/ — 当 WIKI_STAGED_WRITES=true 时，存放 LLM 编写页面的审核队列。此处的页面在通过 /wiki-stage-commit 提升前，不会显示在 Obsidian 图谱中。

步骤 3：创建特殊文件

obsidian-wiki setup --vault <path> [--timezone <IANA name>] 一次性创建所有这些文件。以下模板是手动设置时写入的内容。

index.md

---
title: Wiki Index
---

# Wiki Index

*This index is automatically maintained. Last updated: TIMESTAMP*

## Concepts

*No pages yet. Use `wiki-ingest` to add your first source.*

## Entities

## Skills

## References

## Synthesis

## Journal

log.md

---
title: Wiki Log
---

# Wiki Log

- [TIMESTAMP] INIT vault_path="OBSIDIAN_VAULT_PATH" categories=concepts,entities,skills,references,synthesis,journal

hot.md

---
title: Hot Cache
updated: TIMESTAMP
---

# Hot Cache

*A ~500-word semantic snapshot of recent activity. Updated after every major write operation.*

## Recent Activity

- [TIMESTAMP] INIT — vault created at OBSIDIAN_VAULT_PATH

## Active Threads

*None yet — start ingesting sources to populate.*

## Key Takeaways

*None yet.*

## Flagged Contradictions

*None yet.*

.manifest.json

创建一个空清单，让摄取技能有可追加记录的跟踪文件，并使 obsidian-wiki doctor 将 Vault 报告为完整（它会将 .manifest.json 视为必需的核心文件）：

printf '{}\n' > "$OBSIDIAN_VAULT_PATH/.manifest.json"

步骤 4：创建 .obsidian 配置

创建最精简的 Obsidian 配置，以获得良好的开箱即用体验：

.obsidian/app.json

{
  "strictLineBreaks": false,
  "showFrontmatter": false,
  "defaultViewMode": "preview",
  "livePreview": true
}

.obsidian/appearance.json

{
  "baseFontSize": 16,
  "enabledCssSnippets": ["obsidian-wiki-folders"]
}

文件夹颜色和图谱默认设置

obsidian-wiki setup 还会写入 .obsidian/snippets/obsidian-wiki-folders.css（文件浏览器中每个分类文件夹使用一种颜色，_ 文件夹调暗显示）和 .obsidian/graph.json（图谱视图使用相同颜色，并过滤掉 _raw/、_archives/、_staging/、_meta/、index、log 和 hot）。如果 CLI 可用，请运行 obsidian-wiki setup --vault "$OBSIDIAN_VAULT_PATH"，而不要手动编写这些文件。绝不覆盖现有的 .obsidian 文件；如需之后更改颜色，请使用 graph-colorize。

步骤 5：推荐 Obsidian 插件

向用户介绍以下推荐的社区插件（需要手动安装）：

1. Dataview — 查询页面元数据并创建动态表格。对 Wiki 至关重要。
2. Graph Analysis — 增强图谱视图，便于探索关联。
3. Templater — 如果用户想用模板手动创建页面，可使用此插件。
4. Obsidian Git — 将 Vault 自动备份到 git 仓库。

第 6 步：验证设置

快速进行健全性检查：

• 知识库目录存在，且包含：concepts/、entities/、skills/、references/、synthesis/、journal/、projects/、_archives/、_raw/
• 知识库根目录存在 index.md
• 如果用户选择了时区，index.md 的 frontmatter 中包含 timezone:（obsidian-wiki memory status 会显示正在使用的时区）
• 知识库根目录存在 log.md
• 知识库根目录存在 hot.md
• 知识库根目录存在 .manifest.json（空的 {} 也可以）
• .env 中设置了 OBSIDIAN_VAULT_PATH
• 存在 .obsidian/ 目录
• 存在 _staging/ 目录（即使未设置 WIKI_STAGED_WRITES，也必须存在——设置时会创建，以备将来使用）
• 解析后的全局配置目录中存在 WRITING_PROFILE
• 源目录（如已配置）存在且可读取

报告检查结果，包括解析后的 WRITING_PROFILE 绝对路径，并告知用户现在可以：

1. 在 Obsidian 中打开知识库（File → Open Vault → 选择目录）
2. 运行 wiki-status 查看有哪些内容可供导入
3. 运行 wiki-ingest 添加首批来源
4. 运行 claude-history-ingest 挖掘 Claude 对话
5. 运行 codex-history-ingest 挖掘 Codex 会话（如果使用 Codex）
6. 随时再次运行 wiki-status 查看差异

可选：安装 Stop Hook（自动捕获）

询问用户：“要在会话结束时自动捕获发现吗？”

如果要，请将 Stop Hook 安装到其全局 Claude Code 设置中，这样每个有实质性工作的会话都会在关闭前自动提示运行 /wiki-capture --quick。

**Hook 的作用：**在 Stop 时读取会话记录，统计文件编辑和 Shell 调用次数；如果发生了大量工作，就提示 Claude 运行一次 /wiki-capture --quick。 wiki-capture 快速模式下的 KEEP/SKIP 门控机制可防止产生噪声——常规或结论不明确的会话会自动跳过。

安装步骤：

1. 找到 obsidian-wiki 仓库路径。如果配置中已设置 OBSIDIAN_WIKI_REPO，则使用该路径。 否则，检查常见位置：~/Documents/projects/obsidian-wiki、~/obsidian-wiki， 或询问用户。

2. 定位 wiki-stop-capture.sh 脚本。pip/uv 安装与源码检出中的路径不同，因此请在 <REPO_PATH> 下检查这两种布局，并使用第一个存在的路径：

   • <REPO_PATH>/hooks/wiki-stop-capture.sh — 已打包的安装（OBSIDIAN_WIKI_REPO 指向随包附带的 _data/ 目录，其中 hooks/ 下包含该 Hook）。
   • <REPO_PATH>/.claude/hooks/wiki-stop-capture.sh — 源码检出。

   如果两者都不存在（例如，较早发布且尚未打包该 Hook 的 wheel），请将规范副本下载到一个稳定位置，并改为指向该位置。使用 llm-wiki/SKILL.md 中 Config Resolution Protocol 指定的全局配置目录（默认采用 XDG 风格的 ~/.config/obsidian-wiki，如果已存在旧版目录 ~/.obsidian-wiki，则使用该目录）：

   CONFIG_DIR="$( [[ -d "$HOME/.obsidian-wiki" && ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/obsidian-wiki" ]] && echo "$HOME/.obsidian-wiki" || echo "${XDG_CONFIG_HOME:-$HOME/.config}/obsidian-wiki" )"
   mkdir -p "$CONFIG_DIR/hooks"
   curl -fsSL https://raw.githubusercontent.com/Ar9av/obsidian-wiki/main/.claude/hooks/wiki-stop-capture.sh \
     -o "$CONFIG_DIR/hooks/wiki-stop-capture.sh"
   chmod +x "$CONFIG_DIR/hooks/wiki-stop-capture.sh"
   

   使用解析出的绝对路径作为下文的 <HOOK_PATH>。

3. 将 Hook 条目合并到 ~/.claude/settings.json：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash <HOOK_PATH>"
          }
        ]
      }
    ]
  }
}

如果 ~/.claude/settings.json 已存在且包含 hooks.Stop 数组，请追加新条目，而不要替换整个数组——不要覆盖现有 Hook。

注意 — 预期会在此仓库内收到重复提示。 obsidian-wiki 仓库自带由 git 跟踪的 .claude/settings.json，它会通过相对路径注册相同的 Stop Hook。Claude Code 会合并项目级和用户级 Hook 配置，而不是让其中一方覆盖另一方，因此在仓库内结束的会话会触发两处注册。这是预期行为，且无害——该 Hook 会声明一个原子级的会话哨兵，因此只会发出一次提示。请保留两处配置：移除项目级条目会使一个由 git 跟踪的框架文件变为未提交状态，并导致克隆仓库但未进行全局安装的用户无法使用捕获功能。

4. 确认：“Stop Hook 已安装。凡是在会话中写入文件或运行 ≥ 4 条 Shell 命令，Claude Code 都会在会话结束时提示运行 /wiki-capture --quick。”

**之后如需卸载：**从 ~/.claude/settings.json 中移除 Hook 条目，或在 Shell 中设置 WIKI_STOP_CAPTURE=false，以跳过单次会话的捕获（仍会遵从 HIVEMIND_CAPTURE=false）。

可选：配置 GitHub 同步

询问用户：“想把你的知识库同步到私有 GitHub 仓库吗？”

知识库采用纯 Markdown 格式，因此将其推送到 Git 仓库即可免费获得版本历史记录、备份和跨设备同步。此操作需用户主动选择——如果用户拒绝或尚未准备好仓库，请跳过。

如果用户同意：

1. 询问仓库 URL（例如 https://github.com/you/my-wiki.git）。如果知识库中包含个人笔记，建议设为私有。
2. 运行 CLI，它会处理 git init、创建默认 .gitignore 文件，以及配置 origin 远程仓库——这与 obsidian-wiki setup 的交互式提示和 setup.sh 使用的是同一套代码，因此只需维护一个正确的实现（参见 issue #153，了解原因）：

   obsidian-wiki sync-setup "<repo-url>" --vault "$OBSIDIAN_VAULT_PATH"
   

   如果 obsidian-wiki 二进制文件不在 PATH 中（从源代码检出但尚未安装），请改为从仓库运行：PYTHONPATH="$OBSIDIAN_WIKI_REPO" python3 -m obsidian_wiki.cli sync-setup ...，使用可用的 OBSIDIAN_WIKI_REPO 或本地检出路径。
3. 告诉用户，他们之后可以随时运行 obsidian-wiki sync，提交并推送待处理的知识库更改（暂存所有内容、使用时间戳提交并推送）。没有用于检查同步状态的配置文件——知识库自身的 git remote 才是事实来源。

可选：设置后刷新 QMD

如果已配置 QMD_WIKI_COLLECTION，且本地 QMD CLI 可用，请在初始知识库文件创建后运行 qmd update，这样新建的知识库就能立即查询。设置时通常无需执行嵌入，因为知识库初始为空；除非已经添加了页面，否则只需普通更新即可。运行前，请确认已按步骤 1.4 所述排除 _raw/——否则，此次更新也会将（目前为空的）暂存目录索引到知识库集合中，以后放入其中的每份草稿都会悄然加入索引。