Pickoo（pickoo-your-favorites）是一个本地优先的 AI 收藏夹工作台：粘贴链接后，由本地 Agent 自动抓取原文、图片与音视频，用 ASR/OCR 转写、分章，最终沉淀为可人工编辑的 Markdown 证据包。本指南以它的 Node.js + Python 混合架构为主线，拆解 Skill 扩展机制与本地内容管线的实现原理，帮助新手快速建立读代码与二次开发的认知框架。

🗂️ 认识 Pickoo：本地优先的 AI 收藏夹工作台

Pickoo 把"收藏链接"变成"沉淀可复用内容"：数据不离开本机，原文、媒体、逐字稿与拆解结果都保存在本地资料库（默认~/Documents/Pickoo Library），浏览器界面只是这些文件的"只读投影"，而不是第二套数据库。

每条内容最终都会变成一份系统命名的 Markdown 文档（命名规则：内容形态-来源渠道-标题-作者-日期.md），由manifest.document.path指认，文档内分四层：原始资料 → 标准内容 → 内容拆解 → 素材卡片，拆解结论随时可以回溯到原文、时间段或页码。

🔌 Node.js + Python 混合架构全景

docs/ARCHITECTURE.md 用一页说明了模块关系，核心分工可以概括为：Node.js 管状态与编排，Python 管计算与证据。

Node.js 端：本地服务如何划分

• server.mjs（一万行以上）是本地服务唯一入口，只监听127.0.0.1:4324（server.mjs#L30），提供本地 API、任务日志、设置、媒体流与 Agent 编排。
• public/ 是完整的浏览器 UI，纯前端静态资源，配合 app.js 等模块化脚本。
• server-lib.mjs 收纳章节解析、Markdown 投影、manifest 校验等共享纯逻辑。
• 任务队列与界面偏好放在外部状态目录（macOS 为~/Library/Application Support/Pickoo），不进源码仓库。

Python 端：内容管线如何组织

skill-source/下有三个 Skill，各自携带一套可执行的参考实现脚本：

• save-to-favorites/：新链接入口，负责查重与共享任务提交；
• creator-content-ingest/：证据保留式抓取、OCR、ASR、分章与校验；
• asset-review-agent/：独立评审金句 / 观点 / 钩子 / 结构四类资产。

为什么用两种语言协作

Node 适合长期运行的 HTTP 服务、并发调度与前端状态；而 AI 处理链（Whisper 语音识别、ONNX 视觉识别、媒体处理）在 Python 生态中依赖更成熟。两者边界固定：Node 以固定参数启动 Python 脚本，再读取其产出的 JSON/Markdown 文件，不跨语言共享内存对象——这也是混合架构最容易踩坑、Pickoo 处理得最规范的地方。

⚙️ 混合架构落地：Node 如何驱动 Python 管线

服务端把每个 Python 入口解析为常量，再统一用execFile调用：CAPTURE_SOURCE_SCRIPT指向 capture_source.py，SAVE_SCRIPT指向 save_link.py（见 server.mjs#L259-L263）。

还有两个值得借鉴的工程细节：

1. AI 运行时"复用优先"。Pickoo 先校验本机已有能力——ASR 复用 MLX Whisper 或 Faster-Whisper，OCR 在 macOS 优先 Apple Vision、其他平台复用 RapidOCR + ONNX；全部失败才在~/.cache/creator-content-ingest/安装隔离运行时，任务执行期间绝不做临时pip install。
2. 双语言一套测试命令。npm test同时跑 Node 与 Python 两侧测试：node --test tests/*.test.mjs+python3 -m unittest discover tests（package.json#L10），tests/ 目录里的管线回归测试成对覆盖两种语言。

🧩 Skill 扩展机制：一条管线服务多个 AI Agent

Skill 是 Pickoo 的扩展单元，每个 Skill =SKILL.md契约文件 +references/文档集 +scripts/参考实现：

契约文件 SKILL.md 用 frontmatter 声明name与description，正文写清路由边界、必读文档清单与可执行基线命令。例如抓取命令被固定为：

python scripts/capture_source.py --url <source> --raw-input <原始分享文字> --instruction <请求> --output-root <packages> --mode full

安装器 tools/install-skills.mjs 以"复制到临时目录 → 校验 frontmatter → 备份旧版 → 原子改名"四步完成安装（install-skills.mjs#L54-L80），agent-targets.mjs 负责解析 Codex、WorkBuddy、Hermes、Claude、Claudian 各自的 Skill 目录。五个 Agent 共用同一份资料库与~/.config/pickoo/settings.json，不会各自保存一套配置（README.md#L84-L93）。

想写自己的扩展 Skill 时，参照save-to-favorites的结构顺序：先定义路由边界（什么请求归我管），再定义共享契约（读哪份设置、产物写到哪里），最后给出可执行基线（可直接运行的命令）。

📦 本地内容管线：从链接到证据包的 6 个阶段

完整管线可以拆成 6 步，每一步都有对应脚本与质量门：

1. 入口与查重—save_link.py的submit提交到共享任务日志，按来源 ID 去重，前端据此显示队列、阶段与心跳（SKILL.md#L43）。
2. 证据保留式抓取— capture_source.py 归档原文、图片与音视频；不归档 Cookie、签名 URL 或账号状态。
3. 语音转写— transcribe_package.py 执行 ASR 与质量检查，原始稿与校正版严格分离，纠错写入transcript-review.json而非覆盖原始输出。
4. 图片 OCR— 每张图片执行一次基线 OCR，记录原始/校正文本、坐标与置信度。
5. 语义章节构建— 视频/音频生成"语义章节 + 连续逐字稿 + 起止时间"，文章生成"语义章节 + 原文段落"；章节只做导航，绝不冒充摘要。
6. 资产拆解与校验— 产出金句 / 观点 / 钩子 / 结构 / 图像 / 镜头六类资产，经 asset-review-agent 独立评审后才入库，评审只问四个问题：抓住人、带着走、留下来、拿得走（SKILL.md#L44-L58）。

贯穿管线的设计原则只有两条，但很关键：

• 证据先行、解读在后：任何结论必须能回溯到时间戳、段落或页码；过不了质量门就标review/partial，绝不虚报"完成"。
• 质量门台账可续跑：已通过的门按指纹复用，断点恢复时只重跑变化或缺失的门，长任务不必从头再来。

🚀 开发者快速上手：运行、测试与扩展

环境要求：Node.js 20+、Python 3.10+，以及ffmpeg/ffprobe/yt-dlp（完整媒体处理链需要）。

npm ci python3 -m pip install -r skill-source/creator-content-ingest/requirements.txt npm start

然后打开http://127.0.0.1:4324即可。package.json是版本号的唯一事实来源；修改路径请优先用环境变量而不是改源码：PICKOO_PORT、PICKOO_DATA_DIR、PICKOO_SETTINGS_FILE、PICKOO_LIBRARY_ROOT（docs/DEVELOPMENT.md#L24-L33）。

验证建议按 docs/DEVELOPMENT.md#L49-L54 的清单执行：npm test跑双语言测试，用quick_validate.py校验 Skill 结构，发布前再跑npm run release:check检查包体限制。

📚 延伸阅读路径

• 架构总览：docs/ARCHITECTURE.md
• 开发环境与验证：docs/DEVELOPMENT.md
• 文件、网络与 Agent 权限：docs/PERMISSIONS.md
• 前端 UI 源码：public/
• 双语言回归测试：tests/

一句话总结 Pickoo 的混合架构：Node.js 搭本地服务与任务编排，Python 搭证据保留的内容管线，Skill 契约让任何 Agent 都能复用这条管线。理解了这套分工，代码的阅读顺序也就自然清晰了。