# Ray Obsidian

> 在用户本地新建、检查或渐进适配一个面向长期知识与内容生产的 Obsidian 知识库，复用 Ray 的资料、知识、候选选题、写作任务、调研、文章与口播母稿、发布反馈和知识回流分层。用于“帮我搭一个 Obsidian 知识库”“给 ray-writer 准备本地知识库”“把现有 vault 接入内容生产管线”“检查知识库结构是否完整”时；也在 ray-writer 找不到兼容知识库时使用。只补缺失结构，不覆盖、移动或删除用户已有笔记，不强制安装插件、同步服务或 Git。

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

---


# 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 加载时报告的根目录运行：

```bash
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. 安全初始化

先预演：

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

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

```bash
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-系统/20-流程/个人知识库工作流.md`

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

## 5. 交接内容生产

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

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

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

## 完成标准

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