企业官网建设流程全解析

Pickoo 是一个本地优先的 AI 收藏夹与灵感整理工作台，它把收藏内容沉淀为可编辑的Markdown 单一事实源（single source of truth），而这套机制天然适合与 Obsidian 深度联动：同一份 Markdown 既可以在 Pickoo 的浏览器界面里卡片化阅读、编辑，也可以在 Obsidian 中作为笔记库的一部分直接浏览、链接和批注。本文将带你理解 Pickoo 的 Markdown 单一事实源设计，并配置双视图同步，实现不重复存储的收藏管理。

为什么 Pickoo 和 Obsidian 是天生一对

很多人收藏内容的习惯是"存进某个 App，然后再也不看"。Pickoo 的思路相反：内容本体必须是你能随时打开、搜索、二次编辑的纯文本。

它的设计原则只有一句话：

每条收藏以manifest.document.path指向的系统长文件名 Markdown 作为人类可编辑入口；浏览器界面只是这份文件的"投影"，而不是第二个内容数据库。

这句话来自 docs/ARCHITECTURE.md，它解释了整套联动的基础：

• Markdown 是唯一可编辑内容文档。原文、标准内容、内容拆解、素材卡片、证据索引都写在同一个文件的固定二级标题下，Obsidian 打开即是结构清晰的笔记；
• manifest.json是机器可读的"旁车文件"，记录身份、哈希、质量门状态等，Obsidian 用户不需要管它；
• 原始证据放在evidence/目录（图片、媒体、逐字稿、OCR 等），Markdown 中用相对路径引用，这样 Obsidian、Pickoo 前端、Codex、Claude 等 Agent 解析到的是同一批文件。

也就是说，Pickoo 从第一天起就假设"这份资料可能直接放在一个 Obsidian 库里"。

第一步：把 Pickoo 资料库指到你的 Obsidian 库

Pickoo 的资料库根目录（library root）决定了所有收藏写到哪里，解析顺序是（见 skill-source/save-to-favorites/SKILL.md）：

1. 命令行显式--library-root（一般用不到）
2. 环境变量PICKOO_LIBRARY_ROOT
3. 设置文件~/.config/pickoo/settings.json中的storage.library_root
4. 默认值~/Documents/Pickoo Library

对接 Obsidian 最简单的做法：

方法一（推荐，适合新手）：在 Pickoo 设置页的"存储与最终 Markdown"区域，把"来源资料包位置"直接选为你 Obsidian 库里的某个子文件夹（或整个库根目录）。设置界面源码见 public/index.html。

方法二：设置环境变量，让 Codex、WorkBuddy、Claude 等 Agent 入口与前端读到同一个路径：

export PICKOO_LIBRARY_ROOT=/path/to/your-obsidian-vault

两个实用细节：

• 如果你通过 Claudian 在 Obsidian 内部直接让 Agent 收藏链接，可以设置PICKOO_OBSIDIAN_VAULT指向 Obsidian 库根目录，Pickoo 会自动在其下寻找.claude/skills目录安装 Skill；此类请求的入口渠道会标记为obsidian；
• Pickoo 会自动读取已有的 Obsidian 高质量输入包，不搬家、不重复存储（见 README.md），你库里的旧资料不会因为接入 Pickoo 而被复制一份。

来源包结构：一条收藏 = 一个文件夹

每条来源对应一个S-{平台}-{稳定ID}/文件夹（契约详见 skill-source/creator-content-ingest/references/obsidian-contract.md），大致长这样：

S-xhs-abc123/ ├── 图文-小红书-好的呀-胖虎超爱玩-20260825.md ← 唯一的人类可编辑文档 ├── manifest.json ← 机器状态、质量门、哈希 └── evidence/ ├── images/ # 图片 ├── media/ # 视频/音频 ├── transcript/ # 带时间戳逐字稿 ├── article/ # 文章章节 └── assets/ # 六类资产（金句/观点/钩子/结构/图像/镜头）

几个对 Obsidian 用户很关键的约定（完整规则见 skill-source/save-to-favorites/references/library-contract.md）：

• 文档命名规则：内容形态-来源渠道-最多10字标题-最多10字作者-YYYYMMDD.md，分配后保持稳定；重名才追加-2、-3后缀；
• 文件名记录在manifest.document.path，改名收藏包时不会丢失"哪个 Markdown 是正主"的映射；
• 媒体链接保持相对路径，Obsidian 里的图片预览、Pickoo 前端、Agent 全都指向同一份文件；
• 旧版的收藏.md只作为迁移输入，Pickoo 会自动把它改名为规范文件名，不会让它长期成为第二套可编辑源。

这套结构的好处：你完全可以把整个库丢进 Obsidian，用双链、标签、搜索随意组织；Pickoo 前端也能立刻识别这些包，显示完整 / 待复核 / 部分完成 / 失败状态，不需要任何"导入"动作。

双视图模式：跟随来源包 vs 集中阅读

Pickoo 在设置里提供"最终 Markdown 怎么放"两个选项（界面见 public/index.html），这就是标题里说的"双视图"：

集中阅读模式的重点机制：

• 集中视图的文件与来源包文档使用完全相同的文件名，两边通过不可变的favorite_id绑定身份，而不是靠路径判断"这是同一条"；
• 集中视图里的媒体链接会被重写为相对集中目录的路径，把集中侧的编辑导回来源包时再反向还原；
• 可以勾选"集中目录跟随资料库"，迁移资料库时集中目录跟着一起走；
• 集中阅读模式不会搬走证据包——来源包仍是唯一的事实源和 Agent 的提交边界，集中目录只是可连续浏览的视图；
• 设置页提供"立即同步"按钮，可手动触发两侧核对，完成后会提示更新篇数与冲突备份数。

双向同步如何避免互相覆盖

这是最容易担心的部分：我在 Obsidian 改了笔记，Pickoo 会不会盖掉它？反过来呢？

Pickoo 的答案是"按身份和修订版本对账，而不是按路径"：

1. Obsidian 侧修改→ Pickoo 详情页自动刷新，立即看到新内容；
2. Pickoo 前端修改→ 原子写回同一个 Markdown 文件，并带版本哈希（乐观并发检查），检测到并发修改时拒绝盲目覆盖；
3. 一侧单独修改→ 同步索引记录了来源包侧和集中侧各自的最后修订版本，单侧修改正常获胜；
4. 两侧同时改了同一段→ 较新的一方获胜，但输掉的那一版会先备份到.pickoo-conflicts/目录，不会凭空丢失；
5. Agent 提交→ Pickoo 运行时后台轮询会自动投影 Agent 写入的来源包；Pickoo 没运行时，等下次启动自动对账。

因此官方契约里对 Agent 有明确禁令（见 skill-source/save-to-favorites/SKILL.md）：

不要创建另一份随手复制的文档，不要重命名两侧已分配的文件，不要靠覆盖任何一方来解决冲突——Pickoo 会保持文件名稳定，并把输掉的一版存到.pickoo-conflicts/再合并。

常见坑与最佳实践

• ⚠️不要手动在集中目录新建"第二份内容文档"。集中视图由 Pickoo 维护，Agent 和人都只编辑来源包文档；
• ⚠️不要改S-xxx/下规范文档的文件名。身份绑定在favorite_id和manifest.document.path上，手动改名会破坏双向同步；
• ✅ 想让 Obsidian 和 Pickoo 看到同一个任务队列，可以在库内约定处理队列/的pending / running / completed / partial / review / failed子目录结构（见 obsidian-contract.md）；
• ✅ 修改资料库根目录是有守卫的迁移操作：Pickoo 会先拒绝仍在运行的任务，再整体迁移来源包、重定位历史任务路径，校验失败会回滚（见 docs/ARCHITECTURE.md）；
• ✅ 所有路径配置集中在~/.config/pickoo/settings.json，前端与所有 Agent 入口共用，不会各自维护一套。

快速上手清单

1. 安装 Node.js 20+，执行npm ci后npm start，打开http://127.0.0.1:4324（详见 README.md）；
2. 在设置页把"来源资料包位置"指向你的 Obsidian 库（或设置PICKOO_LIBRARY_ROOT）；
3. 按需选择"跟随来源包"或"集中阅读"，集中模式可点"立即同步"核对两侧；
4. 收藏任意链接，Pickoo 自动查重、抓取、拆解，生成带完整证据的来源包；
5. 在 Obsidian 里随意编辑 Markdown，回到 Pickoo 详情页即可看到自动刷新后的内容。

相关文档

• Obsidian 存储契约：skill-source/creator-content-ingest/references/obsidian-contract.md
• 共享 Markdown 资料库契约：skill-source/save-to-favorites/references/library-contract.md
• 架构说明：docs/ARCHITECTURE.md
• 开发与环境变量：docs/DEVELOPMENT.md
• 完整功能与数据边界：README.md