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 速查表

# 通用（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 说纯本地，代码里有上报域名）才是红牌。

复制即用启动词

宽泛需求入口：

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

指定仓库入口：

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