SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场soia-pkm-clip-github-repo

soia-pkm-clip-github-repo

办公与效率

查看项目

更新于 10-16 09:08

技能介绍

用途

本技能面向需要系统整理开源代码调研的场景：把散落各处的 GitHub 仓库调研沉淀成 Obsidian vault 里可筛选、可点击跳转的「开源项目图书馆」索引层。设计思路是外部资源留在原地、vault 只装索引：代码本体留在本机一个 git clone 的 upstream 目录（不进 vault），vault 中一仓一张项目卡，加一篇调研笔记骨架。

主要能力

  • 单仓归档：解析 URL 得到 owner/repo，若 upstream 目录下没有该仓则 git clone，已有则跳过 clone；随后为该仓生成或更新项目卡，并在调研笔记目录起一篇 YYYY-MM-DD-调研-<仓名>.md 骨架笔记（已有笔记则跳过新建）。
  • 项目卡自动字段：github（由 git remote 转换）、分类（仓名映射表或 README/名称启发式，兜底「工具其他」）、语言（启发式扫构建文件）、本地路径、访问链接、最近提交（git log -1）、正文简介（取 README 第一句叙述性句子）。
  • 项目卡人工字段：用途、状态（如研究中／已借鉴／已弃）、stars、正文「## 我的笔记」，生成器不覆盖，重跑安全。
  • 双向链接：卡片「## 关联调研」自动列出对应笔记，笔记 frontmatter「关联仓库」字段双链回项目卡。
  • 批量模式：扫描 upstream 下每个子目录，逐仓生成或更新项目卡，幂等刷新自动字段。

使用方式

安装本技能（单个技能）：

npx skills add soia-team/soia-open-pkm-clip-skills -g -a '*' -s soia-pkm-clip-github-repo -y

触发词示例：用户说「归档这个项目 <url>」「归档下这个仓库」「clip 这个 repo」进入单仓归档模式；说「重新生成开源项目卡」「批量刷新项目卡」「新 clone 了几个仓库，补下卡」进入批量模式。

命令参考：

# 单仓归档（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 <相对路径>

配置约定：

~/.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 正文或日志。

配置优先级：私有 config.yml 路径优先取 $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。vault 定位优先级：命令行 --vault > 环境变量 OBSIDIAN_VAULT；upstream 定位优先级：命令行 --upstream > 私有配置的 SOIA_REPO_UPSTREAM_DIR。

适用场景

  • 浏览到值得留存的开源项目，希望快速建卡并留出调研笔记骨架。
  • 已在本机 clone 了多个仓库，需要批量补齐或刷新项目卡的自动字段。
  • 希望以 Obsidian 为索引层、以本机 clone 为代码本体的轻量开源项目图书馆管理方式。

前置依赖

  • Obsidian vault，含（或将新建）两个子目录：60_开源项目/00_图书馆/项目卡/ 与 60_开源项目/10_调研笔记/。
  • 本机一个存放 git clone 仓库的 upstream 目录（任意路径，多个仓库各占一个子目录）。
  • Python 3，纯 stdlib，无第三方依赖。

边界与限制

  • 「归档」只做快速建卡 + 笔记骨架 + 双链；深度调研（把笔记正文填完整）是后续单独一步，不在本 skill 的自动化范围内。
  • clone 失败（私有仓库／无权限／网络问题）时跳过 clone，只用 URL 生成最小卡并提示用户手动处理。
  • 非 git 目录（手动拷贝、没跑过 git clone 的项目）github／最近提交 留空，不报错。
  • 仓库不在写死的 REPO_CATEGORY_MAP 里时走 README／仓名关键词启发式，都测不出归「工具其他」。
  • 项目卡已存在时幂等更新：只刷新自动字段，人工字段与「## 我的笔记」原样保留。
  • upstream 之外单独研究、不打算 clone 的项目不适用本 skill，需用 vault 内 _模板/项目卡模板.md 手工建卡。
  • 未指定 --vault/--upstream 且私有配置也没设时，报错并提示环境变量名，不静默使用写死的默认路径。
  • 涉及删除、覆盖、发送、发布、写远端状态等动作时先征求客户确认；能 dry-run 或预览的优先给预览。
  • 自动字段抓取失败（如非 git 目录拿不到最近提交）需在回执中显式标注“未核实”，不编造。
  • 该技能的第三方依赖、可选依赖与第三方 skill 关系以其 SKILL.md 后续「依赖／前置／资源／边界」说明为准；资料中未提供更细的依赖清单与收费信息。