BarnsL/Reel-Repo-Hunter
GitHub: BarnsL/Reel-Repo-Hunter
一款将短视频应用演示证据映射到可能对应公开 GitHub 仓库的可解释推理工具，通过启发式线索提取、搜索和加权排名生成可审计报告。
Stars: 0 | Forks: 0
# Reel Repo Hunter
Reel Repo Hunter 是一款可解释的推理工具，用于将短视频应用演示（例如 reel 证据）映射到可能的公开 GitHub 仓库。
它通过两个阶段完成此操作：
1. 从用户提供的证据中提取线索。
2. 搜索 GitHub 并使用透明的评分证据对候选仓库进行排名。
该项目旨在提供可复现、可审计的输出，而不是不透明的一次性猜测。
## 当前范围
该仓库目前实现了一个 API 优先的 MVP 切片。
目前已实现：
1. 案例创建和证据录入。
2. 启发式线索提取。
3. 带有后备查询策略的 GitHub 仓库搜索。
4. 轻量级代码搜索验证。
5. 加权排名模型。
6. Markdown 报告生成。
7. 用于本地测试的最小内置浏览器 UI。
尚未实现：
1. 持久化数据库存储。
2. 基于队列的异步 worker 执行。
3. 原生截图上传 + OCR pipeline。
4. 身份验证、配额和多用户租户。
## 仓库布局
1. `apps/api`
用途：Fastify API 服务和本地浏览器控制面板。
2. `apps/worker`
用途：用于未来队列执行的 worker 引导占位符。
3. `packages/shared`
用途：共享领域模型和核心逻辑。
内容包括提取、GitHub 检索、评分和报告生成。
4. `docs/architecture.md`
用途：高级架构概述。
5. `docs/api.md`
用途：端点列表和请求/响应参考。
## 端到端数据流
1. 用户创建一个案例。
2. 用户添加一个或多个证据记录（字幕、文字记录、截图文本等）。
3. API 运行 pipeline。
4. 提取模块将证据转换为带类型的线索。
5. GitHub 模块搜索仓库并尽力执行代码短语检查。
6. 评分模块计算加权特征分数。
7. 报告模块生成可解释的 Markdown 输出。
## 前置条件
1. Node.js 20+（已测试 Node 24）。
2. npm 10+。
3. 可选：设置 `GITHUB_TOKEN` 以获得更好的速率限制和搜索一致性。
## 本地设置
1. 安装依赖。
```
npm install
```
2. 创建本地环境文件。
```
cp .env.example .env
```
3. 可选：在 `.env` 中设置 GitHub token。
```
GITHUB_TOKEN=
```
4. 启动 API。
```
npm run dev --workspace @rrh/api
```
5. 打开本地 UI。
`http://127.0.0.1:4010/`
## 常用命令
1. 对所有包进行类型检查。
```
npm run typecheck
```
2. 构建所有包。
```
npm run build
```
3. 运行 lint 占位符。
```
npm run lint
```
4. 运行测试占位符。
```
npm run test
```
## API 快速参考
Base URL: `http://127.0.0.1:4010`
1. `GET /health`
返回存活状态。
2. `POST /v1/cases`
创建一个案例。
3. `POST /v1/cases/:id/evidence`
追加证据项。
4. `POST /v1/cases/:id/run`
运行提取 + 检索 + 排名 + 报告生成。
5. `GET /v1/cases/:id/candidates`
返回排名后的候选者。
6. `GET /v1/cases/:id/report`
返回生成的 Markdown 报告。
有关完整契约，请参阅 `docs/api.md`。
## 评分模型摘要
排名模型是对归一化特征组件的加权线性评分。
特征分组：
1. 名称匹配。
2. 描述匹配。
3. 技术栈匹配。
4. 代码证据短语命中。
5. 所有者提示匹配。
6. 时效性。
被归档的仓库将受到明确的惩罚。
最终输出包含每个特征的证据明细，以支持可解释性。
## 配置
环境变量：
1. `HOST`
默认值：`127.0.0.1`。
2. `PORT`
默认值：`4010`。
3. `GITHUB_TOKEN`
可选，但建议设置以获得更高的 GitHub API 限制。
## 安全注意事项
1. 此工具仅搜索公开的 GitHub 内容。
2. 结果是基于推断的，在证据稀少时可能会出错。
3. 请勿在证据字段中输入私密凭据或敏感的内部数据。
4. 将 `.env` 保留在本地，不要提交。
## 故障排除
1. `POST /run` 返回 pipeline 失败。
原因：GitHub API 限流或搜索被拒绝。
操作：设置 `GITHUB_TOKEN`，使用更丰富的证据重试。
2. 候选列表为空。
原因：线索微弱或措辞过于局限。
操作：添加文字记录文本、明确的 UI 字符串或框架提示。
3. UI 加载成功但操作失败。
原因：API 未在预期的 host/port 上运行。
操作：验证 `HOST`、`PORT` 和 `GET /health`。
## 开发说明
1. API 目前使用内存存储映射。
2. worker 包特意进行了基础搭建，为未来集成队列做准备。
3. shared 包包含领域逻辑，以便 API 和 worker 可以重用完全相同的行为。
## 计划的后续步骤
1. 为案例/结果添加持久化存储。
2. 添加带重试功能的异步队列执行。
3. 添加 OCR 和文字记录摄取适配器。
4. 添加评估测试用例和可重复的基准评分。
标签：Fastify, GitHub搜索, MITM代理, 代码溯源, 信息推理, 加权排名, 启发式提取, 开源情报分析, 自动化攻击