/ray-obsidian

name: ray-obsidian
description: 新建、检查或适配面向内容生产的 Obsidian 知识库结构（资料、知识、选题、写作、发布、回流）。用于“搭一个 Obsidian 知识库”“把 vault 接入内容管线”“检查知识库结构”，或 ray-writer 找不到知识库时。只补缺失结构，不动已有笔记。

Ray Obsidian

把内容生产的地基装进用户自己的本地目录。先确定知识库根目录，再审计、初始化和复核；已有库只做增量补齐。

固定原则

1. 不默认使用 `rays-brain`，也不假设知识库位于 iCloud、用户主目录或当前项目。 2. 原始资料、长期知识、创作过程和发布成品分开保存；链接表达关系，目录表达职责。 3. 用户已有文件优先。不得覆盖同名文件，不得自动移动、改名、删除或批量改 frontmatter。 4. 不修改 `.obsidian/`，不强制插件、同步服务、Git 或特定云盘。Obsidian 只是编辑器，普通 Markdown 工具同样能使用这套结构。 5. 初始化只建立最小可用骨架。采集自动化、网页剪藏、X 数据和发布连接器在用户需要时另行配置。 6. 初始化后必须执行检查；目录存在不等于知识库可用。

1. 确定知识库根目录

按以下顺序定位：

1. 用户明确给出的目录。 2. 当前目录或父目录中的 `.ray-obsidian.json`。 3. 当前目录或父目录中同时存在 `10-创作/`、`20-知识/`、`30-资料/`、`50-系统/` 的兼容知识库。 4. 仍无法确定时，只问一个问题：知识库要建在哪个本地目录？

路径确定后先报告绝对路径。不要把一个普通项目目录误当知识库，也不要因为目录名含 `brain`、`notes` 或 `vault` 就直接写入。

2. 先检查，后初始化

使用 Skill 加载时报告的根目录运行：

python3 <skill-base>/scripts/vault_setup.py check --vault <知识库目录>

检查结果为 `ready` 时直接交付；为 `incomplete` 或 `missing` 时，阅读 [vault-schema.md](references/vault-schema.md)，向用户简要说明将新增哪些目录和模板。已知的 `ray-content-v1` 会标记为可升级，按增量初始化补齐现行结构；未知版本仍然停止。

对已有 Obsidian 库，额外阅读 [migration.md](references/migration.md)。只做兼容层增量初始化，不整理旧笔记。

3. 安全初始化

先预演：

python3 <skill-base>/scripts/vault_setup.py init --vault <知识库目录> --name <知识库名称> --dry-run

确认目标没有跑偏后执行：

python3 <skill-base>/scripts/vault_setup.py init --vault <知识库目录> --name <知识库名称>

脚本只会：

• 创建缺失目录。
• 从 `assets/vault-template/` 复制缺失的说明、流程和模板。
• 新建 `.ray-obsidian.json` 供其他 Ray Skill 发现结构版本。
• 保留所有已存在的文件并在结果中列为 `preserved`。

出现同名文件时以用户文件为准。已知的 `ray-content-v1` 只升级 manifest、补齐缺失结构并保留全部旧目录和文件；若现有 manifest 无法解析或声明了未知结构版本，停止并报告，不覆盖修复。

4. 复核真实结果

初始化后重新执行 `check`，并实际读取：

• `HOME.md`
• `00-入口/10-工作台/知识工作台.md`
• `00-入口/10-工作台/创作工作台.md`
• `50-系统/30-模板/内容成稿包.md`
• `50-系统/30-模板/快速口播母稿.md`
• `50-系统/20-流程/个人知识库工作流.md`

完成状态必须是 `ready`，且脚本报告没有覆盖文件。用户只要求检查时不得借机初始化。

5. 交接内容生产

向用户交付知识库绝对路径，并说明三个最小入口：

• 新资料进入 `30-资料/`，自己的即时想法进入 `10-创作/10-灵感/inbox.md`。
• 值得表达的角度先进入 `10-创作/10-灵感/20-候选选题/`；确认本次角度后，才在 `10-创作/20-写作任务/` 建立成稿包。
• 图文母稿进入 `10-创作/30-文章草稿/`；直接以口播起稿时使用 `50-系统/30-模板/快速口播母稿.md`，唯一母稿进入 `10-创作/25-口播草稿/`；确认发布后才进入 `40-发布/`，并在 `40-发布/00-内容反馈/` 复盘。

用户接着要求写文章时，把知识库根目录、材料路径和目标平台交给 `ray-writer`。不要复制整套知识库到 Skill 目录，也不要把用户笔记吸收成 Skill 样本。

完成标准

• 根目录由用户或可验证结构确定，没有靠目录名猜测。
• 初始化前完成预演；已有文件零覆盖、零移动、零删除。
• manifest、目录和核心模板齐全，最终检查为 `ready`。
• 用户知道如何在 Obsidian 中打开该目录，以及如何从资料进入成稿包和草稿。