| name | ray-obsidian |
| description | 在用户本地新建、检查或渐进适配一个面向长期知识与内容生产的 Obsidian 知识库，复用 Ray 的资料、知识、候选选题、写作任务、调研、文章与口播母稿、发布反馈和知识回流分层。用于“帮我搭一个 Obsidian 知识库”“给 ray-writer 准备本地知识库”“把现有 vault 接入内容生产管线”“检查知识库结构是否完整”时；也在 ray-writer 找不到兼容知识库时使用。只补缺失结构，不覆盖、移动或删除用户已有笔记，不强制安装插件、同步服务或 Git。 |
Ray Obsidian
把内容生产的地基装进用户自己的本地目录。先确定知识库根目录，再审计、初始化和复核；已有库只做增量补齐。
固定原则
- 不默认使用
rays-brain，也不假设知识库位于 iCloud、用户主目录或当前项目。
- 原始资料、长期知识、创作过程和发布成品分开保存；链接表达关系，目录表达职责。
- 用户已有文件优先。不得覆盖同名文件，不得自动移动、改名、删除或批量改 frontmatter。
- 不修改
.obsidian/，不强制插件、同步服务、Git 或特定云盘。Obsidian 只是编辑器，普通 Markdown 工具同样能使用这套结构。
- 初始化只建立最小可用骨架。采集自动化、网页剪藏、X 数据和发布连接器在用户需要时另行配置。
- 初始化后必须执行检查；目录存在不等于知识库可用。
1. 确定知识库根目录
按以下顺序定位：
- 用户明确给出的目录。
- 当前目录或父目录中的
.ray-obsidian.json。
- 当前目录或父目录中同时存在
10-创作/、20-知识/、30-资料/、50-系统/ 的兼容知识库。
- 仍无法确定时，只问一个问题：知识库要建在哪个本地目录？
路径确定后先报告绝对路径。不要把一个普通项目目录误当知识库，也不要因为目录名含 brain、notes 或 vault 就直接写入。
2. 先检查，后初始化
使用 Skill 加载时报告的根目录运行：
python3 <skill-base>/scripts/vault_setup.py check --vault <知识库目录>
检查结果为 ready 时直接交付；为 incomplete 或 missing 时，阅读 vault-schema.md，向用户简要说明将新增哪些目录和模板。已知的 ray-content-v1 会标记为可升级，按增量初始化补齐现行结构；未知版本仍然停止。
对已有 Obsidian 库，额外阅读 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.md00-入口/10-工作台/知识工作台.md00-入口/10-工作台/创作工作台.md50-系统/30-模板/内容成稿包.md50-系统/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 中打开该目录，以及如何从资料进入成稿包和草稿。
