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