opensrc

获取 npm 包的源代码，为编码助手提供比类型定义更深入的上下文。

为什么？

在使用 AI 编码助手时，仅靠类型和文档往往不够。有时助手需要理解代码的 实现细节——即内部是如何工作的，而不仅仅是接口。

opensrc 自动化了获取包源代码的过程，以便你的助手在需要时可以引用这些源码。

安装

npm install -g opensrc

或者使用 npx：

npx opensrc <package>

使用方法

npm 包

# 获取某个包的源码（自动从 lockfile 中检测版本）
opensrc zod

# 获取特定版本
opensrc zod@3.22.0

# 获取多个包
opensrc react react-dom next

再次运行 opensrc <package> 会自动更新到你当前安装的版本——无需任何额外参数。

GitHub 仓库

你也可以直接从任何公开的 GitHub 仓库获取源代码：

# 使用 github: 前缀
opensrc github:owner/repo

# 使用 owner/repo 简写
opensrc facebook/react

# 使用完整的 GitHub URL
opensrc https://github.com/colinhacks/zod

# 获取特定分支或标签
opensrc owner/repo@v1.0.0
opensrc owner/repo#main

# 混合使用包和仓库
opensrc zod facebook/react

GitHub 仓库会被存储为 opensrc/owner--repo/。

管理源码

# 列出已获取的源码
opensrc list

# 移除某个源码（包或仓库）
opensrc remove zod
opensrc remove owner--repo

文件修改

首次运行时，opensrc 会请求权限以修改以下文件：

• .gitignore — 将 opensrc/ 添加到忽略列表
• tsconfig.json — 将 opensrc/ 排除在编译之外
• AGENTS.md — 添加一个部分，指引助手访问源代码

你的选择会被保存到 opensrc/settings.json 中，这样以后就不会再出现提示。

若要跳过提示，可以使用 --modify 标志：

# 允许文件修改
opensrc zod --modify

# 不允许文件修改
opensrc zod --modify=false

工作原理

1. 查询 npm 注册表以找到该包的仓库 URL。
2. 从你的 lockfile（package-lock.json、pnpm-lock.yaml、yarn.lock）中检测已安装的版本。
3. 在匹配的 git 标签处克隆仓库。
4. 将源码存储在 opensrc/<package-name>/ 目录下。
5. 如果获得许可：将 opensrc/ 添加到 .gitignore，从 tsconfig.json 中排除，并更新 AGENTS.md。

输出

运行 opensrc zod 后：

opensrc/
├── settings.json       # 你的文件修改偏好设置
├── sources.json        # 已获取包的索引
└── zod/
    ├── src/
    ├── package.json
    └── ...

sources.json 文件列出了所有已获取的包及其版本，以便助手知道有哪些可用的源码：

{
  "packages": [
    { "name": "zod", "version": "3.22.0", "path": "opensrc/zod" }
  ]
}

settings.json 文件则保存了你的偏好设置：

{
  "allowFileModifications": true
}

许可证

Apache-2.0

opensrc 快速上手指南

opensrc 是一款专为 AI 编程助手设计的工具，它能自动获取 npm 包或 GitHub 仓库的源代码，让 AI 代理不仅能读取类型定义，还能深入理解代码的内部实现逻辑。

环境准备

• 系统要求：支持 macOS、Linux 和 Windows（需安装 Git）。
• 前置依赖：
  • Node.js (建议 v16+)
  • npm、pnpm 或 yarn（用于管理项目依赖）
  • Git（必须已安装并配置好，用于克隆源码）

国内加速建议：若拉取 GitHub 源码速度较慢，建议配置 Git 代理或使用国内镜像源加速 Git 操作。

安装步骤

你可以选择全局安装或通过 npx 直接使用。

方式一：全局安装（推荐）

npm install -g opensrc
# 如果使用国内镜像源
npm install -g opensrc --registry=https://registry.npmmirror.com

方式二：临时使用 (npx)

无需安装，直接运行：

npx opensrc <package-name>

基本使用

1. 获取 npm 包源码

最简单的用法是直接输入包名，opensrc 会自动从你的锁文件（package-lock.json 等）中检测已安装的版本并下载对应源码。

# 自动检测版本并获取 zod 源码
opensrc zod

# 指定特定版本
opensrc zod@3.22.0

# 同时获取多个包
opensrc react react-dom next

重新运行命令会自动更新到当前安装的版本，无需额外参数。

2. 获取 GitHub 仓库源码

支持直接通过仓库地址获取源码：

# 使用 owner/repo 简写
opensrc facebook/react

# 使用完整 URL
opensrc https://github.com/colinhacks/zod

# 指定分支或标签
opensrc owner/repo#main
opensrc owner/repo@v1.0.0

3. 查看与管理

# 列出已获取的源码
opensrc list

# 移除某个包的源码
opensrc remove zod

4. 首次运行配置

首次运行时，工具会请求权限修改以下文件以优化 AI 上下文体验：

• .gitignore：忽略 opensrc/ 目录
• tsconfig.json：排除 opensrc/ 参与编译
• AGENTS.md：添加指引，告诉 AI 去哪里查找源码

你可以选择允许或拒绝，偏好将保存在 opensrc/settings.json。若需跳过提示，可使用：

# 允许修改
opensrc zod --modify

# 禁止修改
opensrc zod --modify=false

运行后，源码将存储在项目的 opensrc/ 目录下，AI 代理即可读取这些文件以获得更深层的代码上下文。