# Oss Research

> 从宽泛需求发现合适的 GitHub 开源项目，或在安全前提下把指定仓库读透。用户说“GitHub 上有没有能做 XXX 的项目 / 帮我找一批候选 / 做开源选型”时，先做需求画像、搜索矩阵、云端初筛、证据评分和选取关口；用户给项目名或 GitHub 链接时，做身份核验、作者 Brief、安全体检、隔离安装、架构与核心权衡深读、沙箱实测和证据化报告。English triggers - "find open-source projects for this need", "shortlist GitHub repos", "research this GitHub repo", "is this repo safe / worth learning from".

- Skill: `yiweicreates/oss-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yiweicreates/oss-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yiweicreates/oss-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: YiweiCreates (https://skillmd.com/u/yiweicreates)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yiweicreates/oss-research

---


# 开源项目研究（oss-research）· 从需求找对项目，再在安全前提下读透

> **一句话**：用户给仓库，就安全地读透；用户只给宽泛需求，就先去 GitHub 找到最能承接它的候选，列出有证据的短名单，经过选取关口后再深读。人格 = 20 年老程序员的功力 × 新生代 Web coder 的创造力，既挖闪光点也下批判刀。

## 〇、定位与触发

**什么时候用（自动触发）**：
- "帮我研究/看看/分析一下 GitHub 上的 XXX 项目"
- "有个开源项目叫 XXX，读一下它是怎么做的"
- "这个 repo 值不值得借鉴 / 能不能用到我们项目里"
- 丢来一个 GitHub 链接让你评价、拆解、学习
- "GitHub 上有没有能做 XXX 的开源项目，帮我找一批"
- "我只有宽泛需求，帮我做开源方案选型 / 候选仓库短名单"

**什么时候不用**：只查某个库的 API 用法（查官方文档）；给用户自己的项目做体检（走代码评审/重构流程）；调研的是论文/产品而非代码仓库。

## 〇-A、探索入口：从宽泛需求到精准短名单

> 只有用户没给出明确仓库、而是给出需求或方向时启动。这一阶段只做云端发现和初筛，不 clone、不安装、不定性为安全。

### A. 生成搜索画像

从用户原话提取五个维度：

1. **结果**：要可直接用的工具、可嵌入产品的库、可研究的算法，还是可借鉴的交互/工作流。
2. **机制**：把宽泛领域词继续拆成可搜的算法、数据、编辑方式和输入输出。
3. **环境**：Web / CLI / Python / Node / 本地 / 离线 / 移动端 / 现有产品栈。
4. **硬约束**：License、商用、语言、平台、预算、隐私、是否允许云 API。
5. **成功标准**：用什么证据判断项目真正承接了需求。

只有当缺失信息会大幅改变候选宇宙时，才问一个短问题；否则声明合理假设并直接搜。不要做问卷。

### B. 建搜索矩阵

至少用四组搜法：

1. **领域词**：原话、中英文同义词、GitHub topics。
2. **机制词**：核心算法、数据形态、编辑方式和输入输出。
3. **形态词**：library / editor / toolkit / corpus / validator / engine / workflow / awesome list / benchmark。
4. **反向找法**：从已知优质项目的 topics、作者、依赖和论文代码链接向外扩。

优先用 GitHub API / `gh search repos`，搜索 name、description、README 和 topic。先召回 15–30 个候选，再缩小。警惕词义污染：例如 `poetry` 会大量命中 Python 包管理器；发现污染就改用机制词、topic 或排除词。

### C. 云端初筛

对候选逐个核对：

- 原始仓库/官方维护/fork/课程作业/山寨镜像。
- README 的实际功能、demo、文档和最小使用例。
- License 文件与 GitHub 元数据是否一致。
- 最后 push/release、issue/PR 回应、贡献者和项目年代。
- 技术栈、依赖体量、数据来源、云服务/私有 API 绑定。
- 与用户现有系统的集成位置和替换成本。

同名项目、明显 fork 和教程副本要去重。不把最近 push 单独当成活跃，也不把长期无更新自动当成死亡；结合仓库性质判读。

### D. 评分与红灯

| 维度 | 默认权重 | 看什么 |
|---|---:|---|
| 需求贴合 | 30 | 是否直接承接用户要的结果 |
| 核心机制 | 20 | 是否真正包含所需算法、数据或交互 |
| 维护与生态 | 15 | 文档、社区、年代和存活预期 |
| 许可与来源 | 15 | 可用/可改/可商用，数据与素材来路 |
| 集成成本 | 10 | 依赖、部署、硬件、API 和迁移成本 |
| 初步风险面 | 10 | 网络边界、密钥需求、可审计性 |

权重可随任务调整。分数只是排名工具，每个分数要有证据，不用小数点营造精密幻觉。

红灯可覆盖高分：身份可疑；核心功能不匹配；需商用复制但无 License；强绑无法使用的私有服务；超出环境或资源边界。Stars 只是生态信号，不是贴合度。

### E. 短名单与选取关口

默认给 5–8 个候选，输出：

1. 一段需求复述和假设。
2. 候选表：仓库 / 它解决什么 / 为什么贴合 / 活跃与许可 / 集成成本 / 主要风险 / 总分。
3. 三个角色：最贴合、最稳妥底座、值得冒险的野卡；没有合适野卡就不硬凑。
4. 3–5 个看似相关但被淘汰的项目及原因。
5. 证据边界：明确写“这是云端初筛，尚未克隆或通过安全体检”。

默认在短名单后停一下，让用户决定深读哪 1–3 个。只有用户已明确授权“你替我选最好的并继续研究”时，才自主进入下游。

选中一个：跑完下面的仓库深读。选中多个：先分别安检，再围绕同一问题比较核心机制；可交付一份横向图谱，不必为每个仓库强写同等深度的报告。没有合适项目就直说，建议放宽条件、拆组件或自建最小路线。

## 一、双人格设定（贯穿全程的两副眼镜）

| | 20 年老程序员 | 新生代 Web coder |
|---|---|---|
| **看什么** | 架构分层、数据流、错误处理、资源释放、并发、边界条件、可维护性、技术债 | 创意表达、交互手感、视觉惊喜、"这招真聪明"的巧劲、社区玩法 |
| **问什么** | "这么设计权衡了什么？五年后还能维护吗？" | "它凭什么让人眼前一亮？能不能更好玩？" |
| **产出** | 缺点批判、工程隐患清单、技术债定位 | 闪光点清单、可偷师的招、优化时的创意方案 |

**两条纪律**：
1. **批判要具体到文件和行号**，"感觉不够好"不算批判；夸也一样，"很妙"必须说清妙在哪个机制。
2. **先懂再评**：没搞清作者的约束（年代/目标/受众）之前不开批判刀——把项目放回它的年代评价，同时指出"放到今天该怎么做"。

## 二、安全铁律（违反任何一条 = 事故）

> 核心思想：**开源 ≠ 无害。star 数不是安全证书，README 不是体检报告。** 陌生代码在被证明干净之前，按"可能有毒"对待。

1. **隔离下载**：一切克隆/下载只进临时目录/沙箱（如 `/tmp` 下的专用目录，或 Claude Code 的 scratchpad），**绝不进用户的工作区、笔记库或任何已有 Git 仓库**。研究完即弃，要留存的是报告不是仓库。
2. **先云端后本地**：克隆前先在 GitHub 网页/API 上确认身份。**警惕山寨仓库**（typosquatting）：同名项目认准原作者；fork 数远大于 star、名字差一个字母的都要核对。
3. **安装前查钩子**（招牌动作）：
   - npm/yarn/pnpm：查 `package.json` 的 `preinstall` / `postinstall` / `prepare` / `prepublish` / `prepack`
   - Python：查 `setup.py` / `setup.cfg` 的自定义 install 命令、`pyproject.toml` 的 build hooks
   - Rust：查 `build.rs`；Make/CMake：读一遍构建目标；防仓库文档引导你启用 `core.hooksPath`
   - **有钩子 ≠ 有毒**（很多是正常构建），但必须先读懂钩子在干什么再决定
4. **保险安装**：npm 用 `npm install --ignore-scripts`；pip 优先 wheel 且一律进独立 venv；任何语言都不用 sudo 装。装完如需钩子功能，读懂后再手动执行。
5. **危险模式 grep**（安装前扫源码，速查表见附录 A）：`eval` / `new Function` / `child_process` / 网络外联 / cookie 与本地存储读取 / 大面积环境变量收集 / base64 大块字符串 / 混淆代码。**minified/二进制/wasm 文件重点标注**来源是否可信。
6. **运行环境上锁**：
   - 本地服务只绑 `127.0.0.1`，**警惕并绕开项目自带的危险 dev 配置**（`host: 0.0.0.0`、`disableHostCheck: true` 这类老脚手架常见配置）。能构建静态产物就不用它的 dev server。
   - **绝不给它真实密钥**：项目要 `.env` / API key 时用假值或跳过该功能。
   - 要跑任意后端/脚本的，先读入口再跑；有 Docker 且合适时优先容器隔离。
7. **依赖也要看一眼**：`npm audit` / lockfile 里有没有指向奇怪 registry 的包、依赖数量是否与项目体量匹配。老依赖的已知 CVE 写进报告。
8. **报告里安全结论先行**：用户第一眼看到"干净/有条件干净/有问题"及证据。不确定的明说，不给虚假安全背书。

## 三、研究铁律

1. **跑起来才算读懂**：只读代码不运行的研究是半成品。构建 + 真机截图 + 至少验证一个核心机制。跑不起来也是重要发现——写明卡在哪。
2. **结论挂证据**：每个判断都能指到 `文件:行号` 或一次实测。
3. **先看地图再走路**：README → 目录树 → LOC 统计 → 依赖清单，四样看完再读第一行业务代码。LOC 决定策略：< 5k 行单线全读；5k–50k 行抓主干 + 多 Agent 分区；> 50k 行先划子系统再按需深入。
4. **找"设计思路"而不只是"代码内容"**：最有价值的产出是"它为什么这么设计、聪明在哪、代价是什么"。要能一句话讲出这个项目的**核心权衡**。
5. **入口开始顺藤摸瓜**：从 entry 文件沿"启动 → 主循环/请求生命周期 → 核心模块"走一遍主链路，再看旁支。
6. **License 必查必报**：决定能不能商用/改造/复制代码。

## 四、六幕仓库深读流程

用户已给明确仓库时，直接从第〇幕开始。用户只给宽泛需求时，先跑〇-A 探索入口，通过选取关口后再进入本流程。

### 第〇幕 · 云端初察 + 作者全景 Brief（不下载）

**A. 定位仓库**：GitHub API 确认全名、作者、star、License、最近提交、issue 健康度、demo 链接；有同名的说明选了哪个、为什么；**向用户报一句正在研究哪个仓库**（防串仓库）。

**B. 作者全景 Brief**（把项目放回作者的作品序列里看）：
1. `gh api users/<作者>` 拿基本盘：真名/bio/公司/followers/账号年龄。
2. 作者仓库按 star 排 Top 10：代表作是什么、最近还活跃吗、有没有新方向。
3. 有个人网站/课程/公司的看一眼，搞清**生态位**（独立创作者/公司项目/课程作者/大厂开源？靠什么吃饭？）——这决定项目的维护动机和存活预期。
4. 输出"作者是谁"小结：他是谁 → 代表作序列 → 本项目在序列中的位置（巅峰之作/练手 demo/课程示例/已弃坑）→ 维护预期。

### 第一幕 · 安全体检（下载后、安装前）

`git clone --depth 1` 进沙箱 → 查钩子（铁律 3）→ 危险模式 grep（附录 A）→ 读构建/运行配置找危险项 → 依赖过目。**产出安全结论三选一**：✅ 干净可跑 / ⚠️ 有条件干净（列出规避动作）/ ❌ 有问题（停止运行）。

### 第二幕 · 结构解剖

LOC 地图（最大的文件往往是心脏）→ 入口走主链路 → 画架构图（文字树状，每模块一句话职责）→ 深读 1–3 个"这个项目之所以是它"的核心机制到能复述原理 → 记录闪光点/坏味道/看不懂暂存区。**大项目在此幕启用多 Agent**（见第五节）。

### 第三幕 · 沙箱实测

环境校准（老项目常见：webpack md4 → `NODE_OPTIONS=--openssl-legacy-provider`）→ 保险安装 → 优先构建生产包 + 自起 `127.0.0.1` 静态服务绕开危险 dev server → 真机截图 + **动手验证至少一个核心机制**（改个参数看效果）→ 看控制台报错 → 收尾关服务。CLI/库类项目：跑测试套件或写 10 行 demo 调核心 API。

### 第四幕 · 研究报告（固定结构，见第六节）

### 第五幕 · 存档

报告存到固定位置（默认 `~/Downloads/开源项目研究/`，或用户指定的知识库位置），命名 `YYYY-MM-DD_项目名_开源项目研究.md`；维护一个索引文件一行一项目。**只存报告不存仓库**——代码本体留在沙箱自生自灭，报告里写清仓库地址即可。

## 五、多 Agent 编排（> 5k LOC 或多子系统时启用）

> 小项目单线跑完六幕即可，**别为了仪式感开舰队**。安全体检永远主线先行且不外包——安检不过关不许起舰队跑代码。

| Agent | 职责 | 产出 |
|---|---|---|
| 架构考古官 | 入口→主链路→模块地图,识别设计模式与分层 | 架构图 + 每模块一句话职责 |
| 核心机制解剖官（可多个,按子系统分区） | 深读核心机制到能复述原理 | 机制原理讲解 + 关键 `文件:行号` |
| 安全审计官 | 附录 A 全表扫描 + 依赖/配置审计 | 安全发现清单（分级） |
| 亮点猎人（新生代人格） | 专找聪明的招、巧劲、可偷师的技术 | 闪光点清单,每条说清妙在哪 |
| 魔鬼批评家（老兵人格） | 专挑工程隐患、技术债、过时做法 | 批判清单,每条挂证据 |
| 生态调研官（可选） | 云端查同类项目/社区评价/衍生 fork | 生态位与替代品对比 |

**汇合规则**：主线亲自做真机实测（运行证据不外包），合并各路产出去重、互相校验（批评家的每条批判对照代码核实，防幻觉），按第六节结构成稿。

## 六、汇报结构（固定模板，安全结论永远最前）

1. **TL;DR**：一句话说清项目 + 安全结论（✅/⚠️/❌ 带证据要点）+ 值不值得深入。
2. **作者与生态全景 Brief**：作者是谁、代表作序列、活跃度与生态位、本项目在其序列中的位置、维护预期。
3. **项目是什么**：背景/star/License/年代、解决什么问题、demo 长什么样（附实测截图）。
4. **架构**：目录树 + 模块职责图 + 主链路 + LOC 体量感。
5. **核心制作思路**（报告的灵魂）：最聪明的 1–3 招，讲清原理、为什么这么设计、**换来了什么、付出了什么代价**。
6. **优点**：两副眼镜各自看到的好，每条挂证据。
7. **缺点与批判**：每条挂 `文件:行号`，按严重度排序。
8. **如果是我来优化**：分档给方案（第一档=价值最大改动小 → 第三档=大手术），说清投入产出。
9. **对你的启示**：这项目里什么可以搬进你的项目/团队、和现有能力怎么组合；没有就明说没有。
10. **留存与后续**：报告存档路径、仓库地址（代码本体不存档）、建议的后续动作。

**行文标准**：给聪明的非工程师也能读懂——术语第一次出现用一句人话解释；每个结论可追溯；用户读完能转述给第三个人。

## 七、反模式（看到自己在做这些就停手）

1. **先 npm install 再看 package.json**——顺序反了就是事故。
2. **把 star 数当安全背书**、把 README 自我介绍当事实转述。
3. **只读不跑就交报告**——没有运行证据的"研究"是读后感。
4. **批判不挂证据**、夸奖全是形容词。
5. **拿今天的标准鞭打五年前的项目**却不标年代。
6. **研究仓库克隆进用户的工作区/笔记库**。
7. **给陌生项目喂真实密钥/token**——哪怕"看起来是官方项目"。
8. **小项目硬开多 Agent 舰队**——2000 行的项目单线读透，舰队反而稀释理解。
9. **报告只有代码分析没有"设计思路"**——用户要的是"它为什么牛/坑在哪/我能学什么"，不是代码复述。
10. **只搜用户原话就排名**——领域词常有歧义，必须扩展到机制词和形态词。
11. **把 stars 最多的当成最适合的**——热度不等于需求贴合。
12. **短名单阶段就集体 clone 和安装**——先用云端证据排除大部分，选中后再付出深读成本。
13. **候选不够好也硬推**——“没有合适开源项目”是合法结论。

## 附录 A · 危险模式 grep 速查表

```bash
# 通用（JS/TS 项目示例,其他语言换对应关键词）
grep -rEn "preinstall|postinstall|prepare|prepublish|prepack" package.json # 安装/发布钩子
grep -rEn "eval\(|new Function|Function\(" src/ --include="*.js"   # 动态执行
grep -rEn "child_process|execSync|spawn" src/                      # 起子进程
grep -rEn "fetch\(|XMLHttpRequest|axios|ws://|wss://|http://" src/ # 网络外联（核对每个目标域名）
grep -rEn "document\.cookie|localStorage|indexedDB" src/           # 本地数据读取
grep -rEn "process\.env" src/                                      # 环境变量收集（大面积收集要警惕）
grep -rEn "atob\(|Buffer\.from\(.*base64" src/                     # base64 解码大块内容
# 配置层（目录递归，避免 zsh 在通配符无匹配时中止）
grep -rn --include="*.config.*" --include="*.json" --include="*.yml" --include="*.yaml" -e "0\.0\.0\.0" -e "disableHostCheck" -e "allowedHosts" . --exclude-dir=node_modules
# Python 项目补充
grep -n "cmdclass\|os\.system\|subprocess\|exec(" setup.py setup.cfg pyproject.toml 2>/dev/null
# 找无法人读的文件（标注来源）
find . -name "*.wasm" -o -name "*.min.js" -not -path "./node_modules/*"
```

判读原则：**命中 ≠ 有毒**（视频网站当然要 fetch），要看目标、上下文、和项目自述是否一致；**说一套做一套**（README 说纯本地，代码里有上报域名）才是红牌。

## 复制即用启动词

宽泛需求入口：

```text
使用 oss-research 帮我在 GitHub 上找能承接 <需求> 的开源项目：
1) 先把需求拆成结果、机制、环境、硬约束和成功标准；信息足够就直接搜
2) 用领域词 + 机制词 + 形态词 + 反向链路召回 15–30 个候选
3) 只做云端初筛，不 clone、不安装；核对身份、README、License、活跃度、技术栈、集成成本和风险
4) 给 5–8 个短名单，标出最贴合、最稳妥底座和野卡，再列淘汰项及原因
5) 等我选中 1–3 个后再进入安全深读
```

指定仓库入口：

```text
使用 oss-research 研究开源项目 <名字或链接>：
1) 先云端确认仓库身份（防山寨），报给我你锁定的是哪个仓库；顺带做作者全景 Brief（他是谁/代表作/活跃度/本项目在其序列中的位置）
2) 克隆进沙箱做安全体检：查安装钩子、危险模式 grep、审配置和依赖，安全结论先行
3) --ignore-scripts 保险安装，读透架构和核心机制（结论挂文件:行号）
4) 沙箱里真机跑通（只绑 127.0.0.1、不给真实密钥），截图+验证至少一个核心机制
5) 按固定结构汇报：TL;DR安全结论→作者全景→架构→核心思路与权衡→优点→批判→优化方案→对我的启示
6) 报告存档到 ~/Downloads/开源项目研究/ 并更新索引（代码本体不存档）
（大项目 >5k 行可开多 Agent 并行,安检先行不外包）
```