快速开始

源码获取与前置条件

从公开仓库取得下方已复审的固定版本。这个版本移除了源码树中的用户生成数据，修正了 CLI 说明并补充了留存规则。请用新的源码目录来运行合成示例。

git clone https://github.com/Golenspade/devhunt.git
cd devhunt
git checkout --detach 0d97c50756cb74ebf868946e181d48835e09e3bf

你需要 Bun 和 GitHub CLI（gh）。下面的本地报告与提示词流程已在 2026-09-06 用 Bun 1.3.14 验证过，不需要 GitHub token 或模型 API key。之后运行 scan 时才需要 GitHub CLI 和身份验证。

在源码根目录安装

bun --version
gh --version
bun install --frozen-lockfile
bun ./bin/devhunt.ts

最后一条故意省略了子命令——它会显示用法然后以 1 退出。这是当前 CLI 的帮助行为，不是安装出了问题。真正的入口是 bin/devhunt.ts；旧说明里提到的根目录 dev.sh 和 build.sh 已经不存在了。保留锁文件，从仓库根目录运行，这样查询文件和输出路径才能正确解析。

用合成数据得到第一次结果

在源码根目录新建 fixture.ts，写入以下内容。它会在 out/docs-demo/raw/ 里创建一个虚构仓库和一个虚构 Pull Request——这不是对真实个人的扫描。用新的源码目录，避免覆盖已有的 out/docs-demo/。

import { mkdir, writeFile } from 'node:fs/promises';
const raw = 'out/docs-demo/raw';
await mkdir(raw, { recursive: true });
const repo = {
  name: 'example-project', owner: { login: 'docs-demo' },
  isFork: false, isArchived: false,
  primaryLanguage: { name: 'TypeScript' },
  stargazerCount: 10, forkCount: 0,
  createdAt: '2024-01-01T00:00:00Z', pushedAt: '2024-01-03T00:00:00Z',
  languages: { edges: [{ size: 1000, node: { name: 'TypeScript' } }] },
};
const pr = {
  createdAt: '2024-01-02T08:00:00Z', mergedAt: '2024-01-03T08:00:00Z',
  closedAt: '2024-01-03T08:00:00Z', isCrossRepository: true,
  additions: 10, deletions: 2, changedFiles: 1,
  repository: { name: 'example-upstream', owner: { login: 'example-owner' } },
  url: '', // Synthetic record: no public evidence URL.
};
await writeFile(`${raw}/repos.jsonl`, JSON.stringify(repo) + '\n');
await writeFile(`${raw}/prs.jsonl`, JSON.stringify(pr) + '\n');
await writeFile(`${raw}/commits.jsonl`, '');
console.log('Synthetic fixture ready: out/docs-demo/raw');

在 POSIX shell 中依次运行样例、报告和提示词命令：

bun fixture.ts
bun ./bin/devhunt.ts report docs-demo --tz +00:00
OPENAI_API_KEY= bun ./bin/devhunt.ts narrate docs-demo --lang en --style brief

显式把 OPENAI_API_KEY 设为空，就算 .env 里有 key，这次也会走本地提示词路径。空值是有意的。完成后看看这些文件：

• out/docs-demo/profile.json — 从合成输入生成的可解析 JSON。
• out/docs-demo/top_repos.json — 一条代表仓库记录。
• out/docs-demo/charts/languages.svg — 语言分布图。
• out/docs-demo/charts/hours.svg — PR 创建时段图。
• out/docs-demo/narrate_prompt.txt — system 和 user 提示词，不是 provider 生成的导读。

样例故意没有用户元数据和 commit，部分指标为空或样本不足是正常的，不能用来判断任何人的能力或习惯。这次验证覆盖了本地分析、SVG 输出和提示词生成，没有验证 GitHub 扫描或真实模型响应。

继续进行已授权的扫描

先选好 login，看看你的 GitHub 凭据能访问什么范围。通过环境变量或 GitHub CLI 配置身份验证，不要把 token 直接粘进命令参数里。GITHUB_TOKEN 和 GH_TOKEN 都可能影响实际使用的凭据。第一次扫描时保留交互确认。

bun ./bin/devhunt.ts scan LOGIN --window quarter
bun ./bin/devhunt.ts report LOGIN --tz Asia/Shanghai
OPENAI_API_KEY= bun ./bin/devhunt.ts narrate LOGIN --lang zh --style professional

三条命令里的 LOGIN 换成同一个真实用户名。quarter 限制的是 commit 时间窗口，不会让所有查询都变成仅公开数据，也不保证每项指标使用相同窗口。复制提示词之前先检查 raw 和派生文件。更多细节见 CLI 参考、AI 导读和数据处理。

扫描遵循令牌可见权限，没有仅公开的可见性过滤。请使用最小权限令牌，把输出当作本地敏感数据对待。