Shambhavagrawal/rotless-github-research

GitHub 研究

找出與使用者主題或問題相關的每個相關倉庫和可提取元件：$ARGUMENTS（Claude Code 會自動填入；在其他代理程式中則為使用者的請求）

字面上的關鍵字搜尋在特定主題上會失敗：開發者是以他們「操作的東西」（網站、API、組織、函式庫）來命名倉庫，而不是以概念來命名。請從多個方向（程式碼、倉庫、提交、議題、其他主機、網路）搜尋任何實作必定包含的產物，驗證每個結果，並將候選者拆解成可重複使用的部分，以融入我們的目標解決方案。

rotless 家族

作為 rotless 的一部分，也可以單獨使用。當研究結果是某個技能的既有技術時，呼叫者會指定一個檔案及其格式（prior-art.md，由 rotless-skill-modernizer 定義）：請按照該格式將報告寫入該檔案。呼叫者包括：rotless-skill-creator（步驟 0，建構之前）、rotless-skill-modernizer（針對已取代的工具執行 fix，或針對整個領域執行 refresh）和 rotless-skill-refiner（在採用「更好的方法」之前，會先對照現有內容進行檢查）。

工具箱

輔助工具位於此技能的 scripts/ 資料夾中。從這個技能的基礎目錄（即包含此 SKILL.md 的資料夾；Claude Code 在載入技能時會顯示「此技能的基礎目錄：…」）設定 S 變數為該資料夾的絕對路徑一次，並始終透過 $S 來呼叫輔助工具（當前工作目錄為使用者的專案）；使用 -h 查看標誌；使用 python3，在 Windows 上使用 python。非 GitHub 的端點位於 references/sources.md（同一資料夾）。建議優先使用 POSIX shell（bash；Windows 上為 Git Bash），而非 PowerShell（處理 -、!、jq 的引號問題）。sarkari/UPSC 範例僅供說明。

工具	搜尋內容	最佳用途
grepapp.py（若已安裝 grep MCP，則等同於 searchGitHub 工具）	檔案內容，約 100 萬個熱門倉庫，支援正規表示式，無需認證	硬編碼的網域、導入行、設定檔金鑰
gh api -X GET search/code -f q='…'	檔案內容，GitHub 的舊版索引（更多倉庫，不支援正規表示式）	第二個程式碼來源；path:/filename: 特徵
ghsweep.py	倉庫名稱/描述/README/主題，多個查詢，去重	廣度；總數、常見主題、[noise?] 標籤
gh search commits …	提交訊息	名稱/README 未提供任何資訊的倉庫
gh search issues … --include-prs	議題/PR 文字	倉庫 + 真實世界的痛點（需要特定片語；通用詞彙會淹沒在機器人議題中）
ghverify.py	GraphQL 批次查詢，每次 25 個倉庫	確認存在性、重新命名、實際活動、健康狀況、證據、警告標誌
gh repo read-dir / read-file、gh api …/contents	一個倉庫的檔案，無需複製	確認實際程式碼
srcsweep.py	21 個非 GitHub 來源的平行搜尋：npm、crates、Packagist、Hex、NuGet、Maven、RubyGems、Hackage、Docker Hub、ArtifactHub、AUR、Open VSX、GitLab、Codeberg、MCP Registry、skills.sh、Hugging Face（模型/資料集/空間/論文，附論文連結的程式碼倉庫）、Hacker News	GitHub 以外的既有技術；最後提供一份已搜尋/未觸及的來源清單；--repos 會將 GitHub 倉庫導入 ghverify.py -
references/sources.md	端點備註 + 無搜尋 API 的來源（PyPI、Homebrew、pkg.go.dev、Product Hunt、Reddit）	手動後續追蹤

重要的 gh 搜尋規則（經過測試；忽略它們會靜默回傳 [] 或錯誤結果）

• 引號： gh search <kind> "two words" = 精確片語。若要使用 AND，請將單詞不加引號傳遞；OR 也不加引號即可使用。
• 對於非平凡的情況，請使用原始 API（完整語法 + total_count）：gh api -X GET search/{repositories|code|commits|issues} -f q='<query>' -f per_page=100 --cache 1h
• 倉庫搜尋中所有單詞都必須匹配，因此每個查詢保持 2-3 個單詞，並變化措辭，而不是將術語堆積在一個查詢中。如果一次掃描回傳少於 5 個倉庫，請縮短查詢。
• 排除： 使用 NOT word 排除單詞；使用 -qualifier:value 排除限定詞。-word 會回傳 0。在 gh search 中，請將排除條件放在 -- 之後。
• 透過 API 進行程式碼搜尋 = 舊版引擎： 不支援正規表示式；OR/NOT、path:、filename:、extension:、language: 可正常運作。僅限預設分支；跳過大型檔案。對於正規表示式，請使用 grep.app。
• 每個查詢結果上限為 1000 個。 分割大型結果集：created:A..B、pushed:>DATE、星級區間 stars:0..24、stars:25..99、stars:100..499（也能發掘低能見度的寶藏）、language:。
• 速率限制： 搜尋每分鐘 30 次；程式碼搜尋每分鐘 10 次（gh skill search 共享此額度）；GraphQL 每小時 5000 點。檢查：gh api rate_limit --jq '.resources | {search: .search.remaining, code: .code_search.remaining, graphql: .graphql.remaining}'。對重複呼叫使用 --cache 1h；當程式碼搜尋額度耗盡時，請切換搜尋向量，而不是等待。
• 隱私： 已驗證的搜尋會回傳帳號有權限存取的私有倉庫。切勿報告它們：在 jq 中添加 select(.repository.private == false)（程式碼）/ select(.private == false)（倉庫）；ghsweep.py 會過濾掉它們。切勿將使用者的私有/內部名稱放入搜尋查詢中。
• gh repo read-file / read-dir / gh discussion / gh skill 需要較新的 gh（已測試 2.103）。如果版本較舊，請使用步驟 3 中的 gh api 後備方案，或建議執行 winget upgrade GitHub.cli / brew upgrade gh。

步驟 0 — 簡報（一個簡短區塊，除非真的模稜兩可，否則無需往返溝通）

寫下：目標 · 目標解決方案分解（模組化子問題：例如 驗證/會話、爬蟲/解析器、正規化/綱要、儲存、API/介面 — 以識別可從何處借鑒什麼） · 必備條件 · 加分條件 · 反模式（例如 薄包裝、已棄用、需要付費 API、僅限 GPU） · 限制（語言、離線…：這些是通過/失敗檢查，而非搜尋詞） · 截止日期 作為絕對日期（「近期」→ pushed:>2025-10-24） · 工作量：快速檢查（成本低、可逆的選擇：約 10 個查詢，前 5 名）或完整方法（預設用於既有技術/自建 vs 外購/整合）。 如果請求是「X 的替代方案 / 像 X 一樣 / X 的複製品」，請先解析 X 到其倉庫，並從中獲取種子（其主題、README、依賴項目）。 先檢查本地端（免費，10 秒）： 已安裝的內容可能就能回答問題：您的代理程式載入的技能資料夾（專案和使用者層級：.agents/skills/、.claude/skills/、~/.codex/skills/…）、其 MCP 伺服器清單（例如 claude mcp list）、gh extension list。在搜尋整個世界之前，先報告本地命中。

步驟 1 — 對主題進行指紋識別

寫下 15–30 個具體的搜尋詞：

1. 接觸點 — 任何實作必定會觸及的網域、URL、API 端點、主機名稱、RSS 路徑、應用程式 ID。
2. 程式碼特徵 — 導入行、SDK 類別/函式名稱、環境變數、設定檔金鑰、CSS 選擇器、獨特的常數。
3. 從多個視角的詞彙 — 建構者、終端使用者、學術界、基礎設施，以及可能最先解決此問題的鄰近學科；區域性/非英語詞彙、縮寫、拼寫錯誤。含義不明的單詞需要搭配一個伴隨詞（agent + llm，而不是單純的 agent）。
4. 形式 — 機器人、爬蟲、API、CLI、函式庫、擴充功能、MCP 伺服器、代理程式技能、資料集、模型、GitHub Action；以及它們的檔案特徵（.github/workflows cron、manifest.json、SKILL.md、.claude-plugin/marketplace.json）。代理程式技能和插件通常存在於更大的倉庫內部（一個 80k★ 的單一儲存庫中的 skills/x/SKILL.md），倉庫搜尋無法發現它們：請使用程式碼搜尋 filename:SKILL.md "<其描述中的片語>" 來尋找它們（雜訊很多：數百到數千個結果，因此請使用 2 個獨特的片語並瀏覽 2-3 頁）以及 skills.sh（srcsweep.py --sources skills；語意搜尋，在技能的名稱上效果比在其用途上好）。技能搜尋是最弱的向量：如果一個錨點技能始終沒有出現，請直接搜尋其名稱，並在覆蓋率註記中說明。
5. 錨點 — 您預期任何好的答案都會包含的 3-10 個知名專案/產品。在步驟 2 中用作召回率檢查。
6. 理想 README 段落 — 描述理想倉庫的兩句話，風格如同其作者所寫；從中挖掘搜尋詞。

步驟 2 — 在每個向量上搜尋

平行執行各向量。記錄每個查詢找到了哪些倉庫（found_by：查詢越多 = 相關性越強）。

A. 程式碼搜尋（訊號最強）。 許多狹義的查詢，每個接觸點/特徵一個：

S="<此技能的基礎目錄>/scripts"     # 例如 S="$HOME/.agents/skills/rotless-github-research/scripts"（或在 Claude Code 中為 ~/.claude/skills/…）
python "$S/grepapp.py" "sarkariresult.com" --repos-only
python "$S/grepapp.py" "(sarkariresult|freejobalert)\.com" --regex --lang Python --lang JavaScript --repos-only
python "$S/grepapp.py" "upsc.gov.in" --path .github/workflows/ --repos-only          # 排程機器人
gh api -X GET search/code -f q='sarkariresult OR freejobalert language:python' -f per_page=100 \
  --jq '"total \(.total_count)", (.items[] | select(.repository.private == false) | "\(.repository.full_name)\t\(.path)")'

grep.app 每個查詢回傳約 10 個檔案，並在廣義的正規表示式上回傳 504 錯誤：請錨定在一個罕見的字面值上，添加 --lang/--path。去除雜訊：爬取的 URL 資料集、廣告封鎖清單、該詞僅出現一次的單一儲存庫。

B. 倉庫搜尋（廣度 + 領域規模）。

python "$S/ghsweep.py" --pushed ">2024-01-01" --order hits "sarkari OR naukri NOT resume" "freejobalert" "topic:government-jobs"
python "$S/ghsweep.py" --sort stars "topic:sarkari-result"      # 描述中跳過通用詞的旗艦專案
python "$S/ghsweep.py" --sort updated "sarkari scraper"         # 被最佳匹配埋沒的新作品
python "$S/ghsweep.py" --must "scrap|crawl|alert|job" --exclude "resume|linkedin" "sarkari OR naukri"   # 相關性過濾器；同音異義詞（「既有技術」= 專利）否則會淹沒結果
gh api -X GET search/topics -f q=sarkari --jq '.items[].name'   # 發現主題標籤

ghsweep.py 會列印總數（該領域的擁擠程度）、最常見的主題（→下一個查詢；同時嘗試由前 2 名命中結果共享的主題配對：topic:a topic:b）、以及 [noise?] 標籤（tutorial/template/demo/dotfiles/awesome：降級處理，不要自動丟棄）。對於與時效性無關的既有技術，請移除 --pushed。

C. 提交搜尋： gh search commits sarkariresult --limit 50 --json repository,commit --jq '.[] | "\(.repository.fullName)\t\(.commit.message | split("\n")[0])"'

D. 議題/PR 搜尋： gh search issues "freejobalert" --include-prs --limit 50 --json repository,title,url（僅限特定片語）。

E. 從最佳命中結果滾雪球（前 3-5 名）：

• 追蹤包裝的依賴項： 如果一個命中結果「包裝」、「建構於」或「使用」X，也請研究 X：它通常是真正的現有領導者。這是最常見的過早停止點。
• Awesome 清單： python "$S/ghsweep.py" --sort stars "awesome <kw> in:name"；選取 ≥200★ 的 awesome-* 清單，提取其中的倉庫連結（gh repo read-file README.md --repo o/awesome-x | grep -oE 'github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+' | sort -u）並導入到 ghverify.py -。被列入清單是一個軟性的品質訊號。
• 相似倉庫： 一個最佳命中結果的主題 + 語言 → topic:a topic:b language:x，偏好相似的星級區間。
• README 的「替代方案 / 相似 / 靈感來源 / 致謝」章節；獨特的程式碼字串 → grep.app（尋找複製品和移植版）；作者的其他倉庫（gh repo list <owner> --limit 100）；有自己的貢獻的分支（gh api "repos/o/r/forks?per_page=100" --jq '.[] | select(.pushed_at > .created_at) | .full_name'）；函式庫依賴項頁面，可透過您的網頁抓取工具或 curl 存取（github.com/o/r/network/dependents）。

F. 非 GitHub 來源： 一個指令，幾種措辭（每個 1-3 個單詞；要包含註冊表 AND 搜尋詞）：

python "$S/srcsweep.py" "repository discovery" --limit 4        # 21 個來源，約 10 秒，以已搜尋/未觸及清單結尾
python "$S/srcsweep.py" "sarkari" --repos | python "$S/ghverify.py" -   # 從結果連結的 GitHub 倉庫，已驗證

然後使用網頁搜尋來處理沒有搜尋 API 的來源（PyPI site:pypi.org、Homebrew、pkg.go.dev、Product Hunt、Reddit、部落格、awesome <topic>）。對於既有技術/競爭研究，也請列出值得注意的商業產品。非 GitHub 的命中結果（GitLab、Codeberg、僅限註冊表）無法通過 ghverify.py：請手動檢查它們，並將證據標記為「已記錄」/「後設資料」。

停止和召回率檢查。 當新的查詢主要回傳已知的倉庫時停止，但是三個查詢回傳同一個倉庫只是一個局部最小值，並非覆蓋率。檢查步驟 1 中的錨點：任何未被您的搜尋發現的錨點都意味著詞彙缺口：找出它使用了哪些詞彙並搜尋那些詞。零結果意味著「這條路線看不到它」，而不是「它不存在」：在下結論之前，請重新措辭或更換路線一次。

步驟 3 — 驗證與評估

每個候選者都通過 ghverify.py（不存在的名稱會顯示為「NOT FOUND」；已重新命名的會顯示當前名稱）：

python "$S/ghverify.py" owner/repo https://github.com/o2/r2 ...      # 或：... | python "$S/ghverify.py" -

讀取其欄位：上次實質性提交（忽略 bump/chore/deps/merge/typo/docs）而非 pushedAt；議題解決率 %；已合併的 PR；貢獻者；組織/使用者；每年發佈次數；證據（測試、CI、manifest、security.md；NONE = 僅有 README，需要嚴格驗證）；標誌 !velocity（>100★/天：病毒式傳播或被購買，需要背景資訊）、!lowfork（≥1000★，forks/stars < 0.005）、new（<14 天）、stale Ny（2 年以上無實質性提交：被標記，絕不降級：一個被棄用的工具仍然證明了這個想法曾被建構）、noise?。

然後為您將報告的每個倉庫確認實際程式碼（README 可能在任何方向上說謊）。將證據錨定到一個提交：

sha=$(gh api repos/o/r/commits/HEAD --jq .sha)
gh repo read-dir src --repo o/r --ref $sha                    # JSON：--json name,type --jq '.entries[]'
gh repo read-file path/to/main.py --repo o/r --ref $sha       # 後備方案：gh api "repos/o/r/contents/PATH?ref=$sha" -H "Accept: application/vnd.github.raw"
gh api "repos/o/r/git/trees/$sha?recursive=1" --jq '"\(.tree|length) files", (.tree[:80][] | .path)'

引用永久連結 https://github.com/o/r/blob/<sha>/<path>#L10-L40，而不是分支連結。

• 契合度與可提取性： 強 / 部分 / 弱 / 脫離目標，列出

…