用途
soia-pkm-clip-github-repo 用于把 GitHub 开源仓库归档为 Obsidian vault 中的项目卡与调研笔记。它的定位是：外部代码本体留在原地，vault 只装可点击、可筛选的索引层。具体而言，代码本体保留在本机一个 git clone 的 upstream 目录（不进 vault），vault 中只保存索引，一仓一张项目卡，加一篇调研笔记骨架。结构与设计哲学同云盘馆藏、个人书库一致。触发说法包括「归档这个项目 URL」「clip 这个 repo」「刷新项目卡」。
主要能力
- 单仓归档：解析 URL 得到 owner/repo，若 upstream 目录下没有该仓则 git clone 进去，已有则跳过 clone 直接建卡；随后调用生成器单仓模式，创建或更新项目卡（路径为 60_开源项目/00_图书馆/项目卡/<仓名>.md）。
- 调研笔记骨架：在 60_开源项目/10_调研笔记/ 起一篇 YYYY-MM-DD-调研-<仓名>.md 骨架笔记，若该仓已有调研笔记则跳过新建。frontmatter 带「关联仓库」双链回项目卡，正文骨架包含「## 是什么 / ## 架构与代码 / ## 对我的价值 / ## 运行验证 / ## 我的结论」。
- 双向链接：卡片「## 关联调研」自动列出该笔记；笔记「关联仓库」字段指向该卡。
- 批量模式：扫描 upstream 下每个子目录，逐仓生成或更新项目卡，用于新 clone 了多个仓库或想刷新全部自动字段。该模式幂等，只刷新自动字段，不覆盖人工字段。
- 项目卡 frontmatter 字段：tags（开源项目）、仓名、github（自动，由 git remote get-url origin 转 owner/repo）、分类（自动，11 类之一）、语言（自动，启发式扫构建文件，取值 Rust / Go / JS/TS / Python / Java / Swift / 未知）、用途（人工）、状态（人工，如 研究中 / 已借鉴 / 已弃）、本地路径（自动）、访问链接（自动）、最近提交（自动，git log -1 --format=%cs，非 git 目录留空）、stars（人工）。
- 自动字段与人工字段的区分：自动字段包括 github、分类、语言、本地路径、访问链接、最近提交、正文简介、正文「## 关联调研」，每次重跑都刷新，不手工维护；「## 关联调研」按仓名匹配 10_调研笔记/ 文件名或其 frontmatter 关联仓库自动回填 wikilink。人工字段包括用途、状态、stars、正文「## 我的笔记」，生成器不覆盖，可随意填写，重跑安全。
- 正文简介取 README 里第一句叙述性句子（跳过标题、徽章、HTML 装饰行、纯命令行、导航条），抓不到时留 (待补描述)。
使用方式
触发词与调用对应关系：
- 「归档这个项目 <url>」「归档下这个仓库」「clip 这个 repo」对应单仓归档模式 gen_repo_catalog.py --add <url>。
- 「重新生成开源项目卡」「批量刷新项目卡」「新 clone 了几个仓库，补下卡」对应批量模式 gen_repo_catalog.py --upstream <dir> --vault <path>。
命令参考：
单仓归档（clone + 建卡 + 起调研笔记骨架 + 双链）：
python3 scripts/gen_repo_catalog.py --add https://github.com/<owner>/<repo>
--upstream <upstream目录> --vault <vault路径>
批量重跑（刷新全部仓库的自动字段）：
python3 scripts/gen_repo_catalog.py --upstream <upstream目录> --vault <vault路径>
覆盖调研笔记目录（默认 60_开源项目/10_调研笔记）：
python3 scripts/gen_repo_catalog.py --upstream <dir> --vault <path> --notes-dir <相对路径>
安装（推荐装整个领域插件，一次装好本仓全部技能）：
claude plugin marketplace add soia-team/soia-open-skills claude plugin install soia-pkm-vault@soia
只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-clip-github-repo -y
配置约定：
~/.config/soia-skills/soia-pkm-clip-github-repo/config.yml SOIA_PKM_CLIP_GITHUB_REPO_CONFIG_FILE=<custom-config-path>
兼容别名：$SOIA_PKM_CLIP_REPO_CONFIG_FILE（以及原有 $SOIA_PKM_CLIP_REPO_ENV_FILE）
如果本技能不需要私有配置，可以不创建 config.yml。如果需要 API key、cookie、session、provider home 或本机路径，只能放进私有 config.yml、进程环境或 provider 自己的登录态里，不能写进仓库、vault 正文或日志。第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。
前置依赖
- Obsidian vault，含（或将新建）两个子目录：60_开源项目/00_图书馆/项目卡/ 与 60_开源项目/10_调研笔记/。
- 本机一个存放 git clone 仓库的 upstream 目录（任意路径，多个仓库各占一个子目录）。
- Python 3，纯 stdlib，无第三方依赖。
- vault 定位优先级：命令行 --vault > 环境变量 OBSIDIAN_VAULT。
- upstream 定位优先级：命令行 --upstream > 私有配置的 SOIA_REPO_UPSTREAM_DIR。
- 私有 config.yml（可选，不要放在 vault 或开源 skill 仓库）。优先级：$SOIA_PKM_CLIP_GITHUB_REPO_CONFIG_FILE（兼容别名 $SOIA_PKM_CLIP_REPO_CONFIG_FILE 以及原有 $SOIA_PKM_CLIP_REPO_ENV_FILE）> ~/.config/soia-skills/soia-pkm-clip-github-repo/config.yml。支持变量名：OBSIDIAN_VAULT、SOIA_REPO_UPSTREAM_DIR。真实路径只写在私有 config.yml 文件里，不写入本文件或脚本源码。
适用场景
- 看到某个 GitHub 开源仓库，想快速归档进 Obsidian vault：「归档这个项目 <url>」。
- 新 clone 了多个仓库，需要补齐项目卡：「新 clone 了几个仓库，补下卡」。
- 想刷新全部仓库项目卡上的自动字段：「重新生成开源项目卡」「批量刷新项目卡」。
限制与边界
- clone 失败（私有仓库、无权限、网络问题）：跳过 clone，只用 URL 生成最小卡，提示用户手动处理。
- 非 git 目录（手动拷贝、没跑过 git clone 的项目）：github、最近提交留空，不报错。
- 仓库不在写死的 REPO_CATEGORY_MAP 里：走 README、仓名关键词启发式归类，都测不出归「工具其他」。
- 项目卡已存在：幂等更新，只刷新自动字段，人工字段与「## 我的笔记」原样保留。
- upstream 之外单独研究、不打算 clone 的项目：不适用本技能，用 vault 内 _模板/项目卡模板.md 手工建卡。
- 未指定 --vault、--upstream 且私有配置也没设：报错并提示环境变量名，不静默使用某个人写死的默认路径。
- 「归档」只是快速建卡 + 笔记骨架 + 双链；深度调研（把笔记正文填完整）是后续单独一步，不在本技能的自动化范围内。
- 项目卡落盘只证明 captured；随后必须交给生命周期管理完成 organized → MOC/导航 → map → Base，合同详见生命周期技能的 references/knowledge-intake-five-stage-contract.md，不适用阶段也要显式写 not_applicable。
- 完成后回执：交付顺序为先落盘再输出回执；自动字段抓取失败（如非 git 目录拿不到最近提交）需在回执中显式标注「未核实」，不编造。回执包含做了什么、文件变更（完整路径）、下一步（提醒回填项目卡的用途、状态、「## 我的笔记」）。