opensense-vp 0.1.0

Daily PR opportunity finder for known open-source repositories

OpenSense

面向知名开源项目的每日 PR 机会发现工具

简体中文

关注仓库  ->  每日 issue 排序  ->  issue --plan  ->  PR 尝试

解决痛点

想给知名开源项目提交 PR，但每天真正卡住的不是写代码，而是选题。翻很多 issue，常常会遇到：描述不清、范围太大、已经有人在做、维护者可能不接受、或者项目最近根本不太合并外部贡献。

OpenSense 关注的是更实际的开源贡献流程：先从你自己关心的仓库开始，例如 vLLM、FastAPI、HTTPX，再结合你的技术栈标签，例如 python、llm、cli、tests，每天筛出更值得打开的小 issue。

它会优先看 issue 是否近期更新、评论是否过多、是否无人认领、标签是否偏 bug fix 或 tests、仓库 star 和 PR 合并信号是否健康，并在你动手前生成一份 PR 前计划，帮助你判断：这个 issue 值不值得做、应该先读哪里、要补哪些测试、是否应该先留言确认。

项目简介

OpenSense 是一个 Python CLI，目标是帮助开发者每天从自己关注的知名 GitHub 开源项目里，找到“小而靠谱、较可能被合并”的 issue，并在动手前生成一份 PR 前计划。

它不是全网 issue 搜索器，也不是自动写 PR 的机器人。OpenSense 更像一个个人开源贡献工作台：初始化时会提供一份以 Agent、RAG 和推理基础设施为主的默认 watchlist，你也可以继续加入自己关心的仓库和技术栈。OpenSense 每天扫描这些项目，筛出更适合今天下手的小 issue。

没有 LLM key 也能运行：默认使用规则评分。有 LLM key 时，可以获得更深入的 issue 分析、风险判断和 PR 前计划。

为什么做 OpenSense

参与开源项目时，真正耗时间的往往不是“点开 issue”，而是判断：

• 这个 issue 是否足够小？
• 有没有人已经在做？
• 维护者是否认可这个方向？
• 它是 bug fix、test、docs，还是一个大 feature？
• 我应该直接开 PR，还是先留言确认？
• 做这个 PR 之前应该先读哪些内容、跑哪些测试？

OpenSense 试图把这个判断流程沉淀成每天可重复的命令行工作流。

每日浏览  ->  候选 issue 短列表  ->  单个 issue 分析  ->  PR 前计划

快速开始

OpenSense 当前提供一个 MVP 版本的 CLI，包含五个顶层命令：

init -> watch -> daily -> issue -> repo

# 1. 创建本地 OpenSense 配置
opensense init

# 2. 查看默认仓库和技术栈，并按需扩展
opensense watch repo list
opensense watch skill list
opensense watch repo add microsoft/autogen
opensense watch repo add deepset-ai/haystack
opensense watch skill add python

# 3. 检查本地配置和可选 API 环境变量
opensense init --check

# 4. 获取今天值得看的 PR 候选 issue
opensense daily

# 5. 分析一个候选 issue，并可选生成 PR 前计划
opensense issue vllm-project/vllm#12345
opensense issue vllm-project/vllm#12345 --plan --no-llm

# 6. 判断仓库是否适合投入 PR
opensense repo vllm-project/vllm --skills python,llm
opensense repo vllm-project/vllm pallets/flask --skills python

效果演示

opensense init 默认会加入 OpenClaw、vLLM、Codex、SGLang、LangChain 和 LlamaIndex，并把 agent、rag 作为默认技术栈：

$ opensense watch repo list
openclaw/openclaw
vllm-project/vllm
openai/codex
sgl-project/sglang
langchain-ai/langchain
run-llama/llama_index

$ opensense watch skill list
agent
rag

然后运行 opensense daily，你会先得到一份短候选列表，而不是继续在 GitHub 页面里反复翻 issue：

$ opensense daily --min-stars 1000 --limit 8

找到 24 个候选 issue。
正在按仓库信号、issue 小型程度和技能匹配度排序...

OpenSense 结果
技术栈：agent, rag
结果：8 个 issue，按适合今天动手的程度排序

1. [9/10] vllm-project/vllm
   Fix CUDA graph memory leak in speculative decoding
   Labels: bug, good first issue
   为什么匹配：推理基础设施是 Agent / RAG 应用的重要运行底座。
   怎么上手：先看 vllm/spec_decode/worker.py 和相关 graph capture 测试。
   下一步：opensense issue vllm-project/vllm#12345 --plan

2. [8/10] triton-lang/triton
   Type inference fails for constexpr in nested loops
   Labels: bug
   为什么匹配：GPU kernel 和高性能推理相关。
   怎么上手：查 code_generator.py visit_For，并对照相似 issue。
   下一步：opensense issue triton-lang/triton#9547 --plan

3. [7/10] huggingface/transformers
   ...

选中一个 issue 后，再用 issue --plan 生成 PR 前计划：

$ opensense issue vllm-project/vllm#12345 --plan

Score: 86
Type: test
Why:
+ matches watched skill: python
+ unassigned
+ recent activity

# PR Plan for vllm-project/vllm#12345

- 先阅读 issue 描述、最近评论和相关测试失败信息。
- 优先定位 scheduler / tests 相关模块，确认是否能复现。
- 先补一个最小失败测试，再做窄范围修复。
- 提交 PR 前运行相关单测，并在 PR 描述里写清楚复现方式和验证命令。
- 如果 issue 里没有维护者确认，可以先留言说明计划，避免做偏方向。

如果你还不确定某个仓库是否值得投入时间，可以先看仓库级信号：

$ opensense repo vllm-project/vllm --skills python,llm

Repository        Score  Verdict  Signals
vllm-project/vllm 82     Go       external contributors are getting merged; language matches your skills

核心流程

当前 MVP 是一个轻量 CLI。需要网络的命令优先使用 GitHub API 和确定性规则；LLM 只作为可选增强。

1. 初始化

opensense init

创建本地状态目录：

.opensense/
  config.toml
  watchlist.toml
  cache/
  reports/

init 负责配置：

• GitHub token 环境变量名
• LLM 服务和模型
• LLM API key 环境变量名
• 每日排序偏好
• 本地缓存和报告路径

首次执行 init 会创建一份可直接使用的默认 watchlist：

skills = ["agent", "rag"]

[[repositories]]
name = "openclaw/openclaw"

[[repositories]]
name = "vllm-project/vllm"

[[repositories]]
name = "openai/codex"

[[repositories]]
name = "sgl-project/sglang"

[[repositories]]
name = "langchain-ai/langchain"

[[repositories]]
name = "run-llama/llama_index"

推荐后续按需加入 microsoft/autogen、deepset-ai/haystack 等 Agent / RAG 仓库。普通重复执行 init 不会覆盖你的 watchlist；init --force 会恢复默认列表。

推荐优先配置两个东西：GitHub Token 和 LLM 服务。

GitHub Token（推荐）

没有 token 时，GitHub API 访问额度很低；配置 token 后，更适合每天扫描多个仓库：

export GITHUB_TOKEN=your-github-token
opensense init --github-token-env GITHUB_TOKEN

LLM 服务（可选但推荐）

没有 LLM key 也能用，OpenSense 会退回确定性规则评分。配置 LLM 后，issue --plan 可以生成更好的摘要、风险判断和 PR 前计划。

export OPENSENSE_LLM_API_KEY=your-api-key
export OPENSENSE_LLM_BASE_URL=https://api.openai.com/v1
export OPENSENSE_LLM_MODEL=gpt-5.5

opensense init \
  --llm-api-key-env OPENSENSE_LLM_API_KEY \
  --llm-base-url-env OPENSENSE_LLM_BASE_URL \
  --llm-model-env OPENSENSE_LLM_MODEL

配置文件只保存环境变量名，不保存原始 API key。

2. 关注仓库和技术栈

opensense watch repo add vllm-project/vllm
opensense watch skill add python

OpenSense 采用 watchlist-first 的方式。它默认从你主动关注的仓库和匹配你贡献优势的技术栈出发，而不是一开始就搜索整个互联网。

3. 获取每日候选

opensense daily

daily 会扫描已关注仓库，并返回一份短候选列表。已关注的技术栈会对匹配 issue 产生轻量加分，例如 python、llm、cli、tests 可以把更适合你的任务排到更靠前的位置，但它不会成为唯一评分规则。

常用筛选参数：

opensense daily --min-stars 500 --updated-days 14 --max-comments 10 --limit 5

每条推荐会说明：

• 总分
• 可能的贡献类型
• 为什么看起来适合入手
• 建议执行的下一条命令

示例输出：

Daily PR candidates

#  Issue                    Score  Type      Why                         Next
1  vllm-project/vllm#12345  82     bug fix   good first issue label      opensense issue vllm-project/vllm#12345

4. 分析并规划单个 issue

opensense issue vllm-project/vllm#12345
opensense issue vllm-project/vllm#12345 --plan

issue 会回答：

• 这个 issue 在说什么？
• 它更像 bug fix、tests、docs，还是 feature？
• 它是否适合做成一个小 PR？
• 哪些确定性信号说明它值得尝试？
• 写代码前应该先检查哪些规则风险？

issue --plan 会把一个候选 issue 转成 PR 前检查清单：

• 问题摘要
• 可能的贡献类型
• 优先阅读的文件或模块
• 建议实现路径
• 测试与验证清单
• 是否应该在编码前先留言确认
• PR 标题和正文草稿轮廓

5. 评估仓库

opensense repo vllm-project/vllm --skills python,llm

repo 会在你投入大量时间前，先检查仓库层面的轻量信号：

• 仓库 star 数
• 最近合并的 PR
• open PR 积压情况
• stale PR 比例
• 外部贡献者 PR 合并情况
• 仓库语言和你的技能是否重合

选择标准

OpenSense 不会只因为一个 issue 带着 good first issue 标签，就把它排到前面。真正值得动手的任务，通常还有一些更实际的信号：

• 问题描述比较清楚，至少知道从哪里开始复现或验证
• 改动范围看起来可控，能收敛成一个目标明确的 PR
• 最近还有维护者或贡献者参与讨论，不像已经被遗忘
• 暂时没人认领，也没有正在处理同一问题的关联 PR
• 更接近 bug fix、补测试、修 CI、typing、文档示例或小范围行为修正

有些 issue 看上去很有意思，但不一定适合今天开始做。遇到下面这些情况，OpenSense 会先把它们往后放：

• 讨论持续了很久，维护者仍没有明确想要的方案
• 已经有人在处理，或者现有 PR 基本覆盖了问题
• 表面是小修复，实际可能牵动大量架构和兼容性设计
• 必须依赖内部数据、特殊硬件或很难搭建的 benchmark 才能验证
• issue 描述太少，连问题是否还能复现都无法确认

MVP 范围

OpenSense v1 聚焦开源贡献的筛选和规划。

当前已经支持：

• 维护 GitHub 仓库和个人技术栈的本地 watchlist
• 初始化 .opensense/ 本地状态
• 通过 init --check 检查本地配置和可选环境变量
• 使用 GitHub API 扫描已关注仓库的 open issue
• 使用确定性规则对候选 issue 排序
• 可选使用 LLM 做更深入的分析和 PR 前计划
• 在用户开始写代码前生成 PR 前计划
• 在深入投入 PR 前做轻量仓库信号检查

当前还不做：

• 自动修改代码
• 代替用户打开 PR
• 保证 PR 会被接受或合并
• 代替用户阅读 issue 讨论和贡献指南
• 默认搜索整个 GitHub
• 作为项目管理或通知平台

架构

OpenSense 当前保持轻量，并按职责拆分 CLI、领域逻辑、外部服务与本地存储：

src/opensense/
├── cli.py                      # 注册 CLI 命令并串联完整工作流
├── config.py                   # 初始化和读取 .opensense 本地配置
├── doctor.py                   # 检查配置文件、环境变量和状态目录
├── models.py                   # 定义 issue、评分和仓库信号数据模型
│
├── github/                     # GitHub 数据访问层
│   ├── client.py               # GitHub REST API 基础客户端
│   ├── issues.py               # 获取并转换 GitHub open issue
│   └── radar.py                # 收集仓库 PR、issue、语言等信号
│
├── core/                       # 排序、评分与规划领域逻辑
│   ├── radar.py                # 根据仓库信号计算贡献友好度
│   ├── scoring.py              # 使用确定性规则评估单个 issue
│   ├── ranking.py              # 结合技术栈匹配对候选 issue 排序
│   └── planner.py              # 生成规则或 LLM 辅助的 PR 前计划
│
├── llm/                        # 可选 LLM 能力
│   └── client.py               # 调用 OpenAI 兼容的 LLM 服务
│
└── storage/                    # 本地状态持久化
    └── watchlist.py            # 读写仓库和技术栈 watchlist

当前实现使用 Typer/Rich CLI、GitHub API client、TOML 本地状态、确定性评分，以及可选的 LLM 辅助规划。

常见问题

可以通过 pip 安装吗？

可以。OpenSense 已经使用标准 pyproject.toml 和 src/ 包结构，并配置了 opensense 命令行入口。

不过 PyPI 上的 opensense 名称已经被其他项目占用，因此本项目使用 opensense-vp 作为发布包名，同时保持安装后的命令名称不变：

pip install opensense-vp
opensense init
opensense daily

当前已经完成发布包元数据、wheel / 源码包构建、twine check、隔离环境安装验证和 GitHub Actions 发布工作流。

首次发布前还需要在 PyPI 为 opensense-vp 配置 Trusted Publisher，然后在 GitHub 发布 v0.1.0 Release。后续每次发布都需要先提升版本号，再创建对应 Git tag 和 Release。

必须配置 GitHub Token 吗？

不是必须，但强烈推荐。没有 token 时 GitHub API 的访问额度较低，扫描多个默认仓库时更容易触发限流。

必须配置 LLM 吗？

不需要。没有 LLM 时，OpenSense 仍然可以使用确定性规则完成候选筛选和排序；配置 LLM 后，issue --plan 会提供更深入的摘要、风险判断和 PR 前计划。

默认 watchlist 可以修改吗？

可以。opensense init 会提供一份 Agent / RAG 默认列表，你可以使用 watch repo add 和 watch skill add 继续扩展。普通重复执行 init 不会覆盖已有列表，init --force 会恢复默认配置。

许可证

本项目采用 MIT License，详见 LICENSE。