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

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.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 中打开该目录，以及如何从资料进入成稿包和草稿。