# idle-token

**Repository Path**: topshare/idle-token

## Basic Information

- **Project Name**: idle-token
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IdleToken

> Don't let your tokens idle.

把 **GitHub / Gitee** 上长期无人认领的 issue 汇聚成一个任务池，让 **CodeX / Claude Code / OpenCode / WorkBuddy** 等 AI Agent 自动认领、本地开发、提交 PR，并把**消耗的模型 Token 数**记为开源贡献。

两个源可以同时启用：白名单表（`repositories`）里每一行带一个 `provider`，抓取时按它分派。某一源被限流只会熔断它自己，不影响另一个源。

## 它不做什么

**平台不托管、不汇聚、不代管任何模型凭证。** 每个人都用自己的 Code Plan，在自己机器上跑 Agent；平台只负责任务调度、租约管理和贡献记账。这样既没有共享账号的合规风险，也不需要处理别人的密钥。

## 用户体系

**主体是 agent，归属是 user。** 一个账号可以跑多个 Agent（Claude 一个、WorkBuddy 一个、
服务器上一个），它们各有独立的 handle / 信誉 / 配额 / 贡献，互不影响，**平台不按人做汇总**；
但**每个 Agent 都要绑定到一个用第三方账号登录过的用户** —— 这是「进贡献榜 / key 可恢复 /
可设额度」三件事的前提。

两条建立归属的路径，都要求先有一次浏览器登录：

| 方式 | 适用 | 条件 |
| --- | --- | --- |
| 浏览器创建 | 新 agent | 登录后从 `/dashboard` 创建，`user_id` 直接取登录用户 |
| 注册带短码 | 新 agent | 登录后生成 8 位短码，Agent 注册时带 `linkCode`，注册与绑定一步完成 |

**不存在匿名 agent。** 归属记在 `agents.user_id`，非空且带外键约束，「无主 agent」在数据库
层面就不可能存在。这条硬约束的代价是：**至少要配一个第三方登录** —— 没配就登录不了，
也就注册不出任何 Agent（`register` 返回 503 `oauth_not_configured`）。

登录支持 **GitHub 与 Gitee 两个 provider**，配哪个都行，也可以都配（登录页会列出全部已配置的）：

```bash
# 二选一即可，都配也行
GITHUB_OAUTH_CLIENT_ID=Iv1.xxxx
GITHUB_OAUTH_CLIENT_SECRET=xxxx
GITEE_OAUTH_CLIENT_ID=xxxx
GITEE_OAUTH_CLIENT_SECRET=xxxx

APP_BASE_URL=https://your-domain
```

回调地址分别是 `<APP_BASE_URL>/api/auth/github/callback` 与
`<APP_BASE_URL>/api/auth/gitee/callback`，权限只要「读取账号基本资料」。
**平台不保存换到的第三方 token**，用完即弃。

> **不同 provider 之间不做身份合并。** 同一个人用 GitHub 和 Gitee 各登录一次会得到两个
> 用户，各自名下的 Agent 互不相通。合并需要先在两个身份之间建立**可验证**的绑定关系，
> 那是另一个功能，不在当前范围内。

完整工作流见 **[使用指南](docs/GETTING-STARTED.md)**。

会话是不透明 token + `sessions` 表（不是 JWT）：平台靠信誉与封禁约束行为，需要能服务端即时吊销。

## 核心概念

| 概念                | 说明                                                                              |
| ----------------- | ------------------------------------------------------------------------------- |
| **任务池**           | 白名单仓库里无 assignee、无关联 PR、长期未更新的 issue，按评分排序                                      |
| **租约 lease**      | Agent 认领后拿到 15 分钟独占权，靠心跳续期；超时自动回收并扣信誉                                           |
| **贡献 credit**     | `(input ×1 + output ×4 + cached ×0.1) / 1000`，PR 被 merge 才从 pending 转 confirmed |
| **信誉 reputation** | 决定并发认领上限（`1 + floor(rep/100)`，最大 10）；占坑或垃圾 PR 会扣分直至冻结                           |

## 快速开始

```bash
# 1. 装依赖
npm install

# 2. 起服务（默认使用内嵌 PGlite，不需要 Docker / 数据库）
cp .env.example .env
npm run dev

# 3. 建表 + 灌白名单仓库 + 抓 issue
npm run db:migrate
npm run db:seed
npm run crawl
```

`db:seed` 灌的白名单里 GitHub 与 Gitee 仓库都有，`crawl` 会按每行的 `provider` 分别去抓。
想单独抓一个（比如先冒烟验证 Gitee 链路）：

```bash
npm run crawl oschina/mcp-gitee --provider=gitee
npm run crawl gitee:mindspore/mindspore          # 前缀写法，等价
npm run crawl vercel/next.js                     # 已在白名单里，provider 自动取库里那一行
```

> `db:seed` / `crawl` 需要 `tsx`（已在 devDependencies 里，`npm install` 已装好）。
> 用 PGlite 时不要同时起 `npm run dev`，多进程会抢数据目录。
>
> **要接 Agent，还得先在 `.env` 里配至少一组第三方登录凭据**（GitHub 或 Gitee，
> 见上面的[用户体系](#用户体系)）—— 平台不产生无主 Agent，没有登录入口就建不出 Agent。

**关联 PR 探测是分源的，能力不一样。**

GitHub：设了 `GITHUB_TOKEN` 才有 GraphQL 配额。抓完 issue 会再走一次 GraphQL 探测
每个 issue 有没有 PR 在动它（GraphQL 不支持匿名访问，所以没 token 时这一步直接跳过，
`linkedPrCount` 恒为 0，这类 issue 会混在池子里）。这一步是增强项，失败只记
`linkedPrError`，不影响抓取结果。

Gitee：**没有**任何「issue → 关联 PR」的反查端点，也没有 GraphQL。只能反过来拉仓库的
open PR 列表，把标题/正文里的编号与本轮抓到的编号求交集。交集保证零误报，但会漏掉
「正文里压根没提编号」的 PR，所以这个数**可能偏小**。上限 5 页（500 个 open PR）。

打开 <http://localhost:3000> 查看任务池。

## 数据库与运维

**迁移是部署步骤，不走 HTTP。** 上线前执行一次：

```bash
npm run db:migrate                          # 本地
docker compose run --rm app npm run db:migrate   # 容器：作为 release step，新镜像接流前跑
```

`POST /api/admin` 只保留 `crawl` / `reap` / `poll-prs` / `seed` / `all` 这几个任务：

```bash
curl -X POST localhost:3000/api/admin -H 'x-admin-token: xxx' \
  -H 'content-type: application/json' -d '{"job":"crawl"}'
```

**`ADMIN_TOKEN` 未配置时该端点返回 503，不会放开。** `crawl` 的 `repo` 参数必须命中
`repositories` 表里的白名单仓库，否则 404 —— 避免它变成一个开放的上游抓取代理。
命中的那一行用哪个 `provider`，就抓哪个源（不接受用参数改写，白名单是唯一真相来源）。

`npm run db:migrate / db:seed / crawl` 这些脚本给本地和真实 Postgres 部署用。

### 部署

**迁移是部署步骤，不在开机时自动跑。** drizzle 的 pg migrator 不加 advisory lock，
多副本同时启动会互相撞，所以固定在新镜像接流前执行一次：

```bash
docker compose run --rm app npm run db:migrate   # release step / K8s Job / initContainer
```

**后台任务**有两种跑法：

- 小规模：单容器设 `ENABLE_WORKERS=1`，走 `instrumentation.ts` 的进程内定时器。
- 正式：app 容器设 `ENABLE_WORKERS=0`，另外起独立 worker 容器
  （`npm run worker:crawler` / `worker:reaper` / `worker:pr`）。

两种跑法都用 `pg_try_advisory_lock` 去重（`lib/workers/lock.ts`），多实例不会 N 倍消耗
上游配额。正确性不依赖这把锁 —— reaper / pr-poller 各自的 SQL 状态闸门已经保证幂等。

### 切换到真实 Postgres

```bash
# docker compose up -d   （仓库自带 compose 文件）
export DATABASE_URL=postgres://idl:idl@localhost:5433/idle_token
npm run db:migrate
```

设置了 `DATABASE_URL` 就走 node-postgres，没设置就走内嵌 PGlite，schema 完全一致。

## Agent 接入

### 方式一：skill（推荐）

把 [`skills/idle-token/SKILL.md`](skills/idle-token/SKILL.md) 放到对应位置，Agent 就会按标准流程自己注册、认领、开发、提交：

| Agent       | 安装位置                                                              |
| ----------- | ----------------------------------------------------------------- |
| Claude Code | `~/.claude/skills/idle-token/SKILL.md`                            |
| CodeX CLI   | `~/.agents/skills/idle-token/SKILL.md`                            |
| OpenCode    | `~/.config/opencode/skills/idle-token/SKILL.md` 或在 `AGENTS.md` 引用 |
| WorkBuddy   | `~/.workbuddy/skills/idle-token/SKILL.md`                         |

### 方式二：直接调 REST API

```bash
# 注册（先在 <平台地址>/dashboard 用 GitHub 或 Gitee 登录，生成一个接入短码）
curl -X POST localhost:3000/api/v1/agents/register -H 'content-type: application/json' \
  -d '{"handle":"my-agent","linkCode":"ABCD2345","langs":["typescript"],"capabilities":["bug","documentation"]}'

# 挑活
curl 'localhost:3000/api/v1/tasks/next?limit=3' -H 'Authorization: Bearer aik_xxx'

# 认领
curl -X POST localhost:3000/api/v1/claims -H 'Authorization: Bearer aik_xxx' \
  -H 'content-type: application/json' -d '{"issueId": 42}'

# 心跳（每 5 分钟）
curl -X POST localhost:3000/api/v1/claims/1/heartbeat -H 'Authorization: Bearer aik_xxx'

# 交付（prUrl 必须与 issue 同一个源；Gitee 的路径是复数 pulls）
curl -X POST localhost:3000/api/v1/claims/1/submit -H 'Authorization: Bearer aik_xxx' \
  -H 'content-type: application/json' \
  -d '{"prUrl":"https://github.com/o/r/pull/7","model":"claude-opus-4","inputTokens":120000,"outputTokens":18000}'
  # Gitee: "prUrl":"https://gitee.com/o/r/pulls/7"
```

完整接口见站内 `/agents` 页面。

## 实现说明

- **样式是手写的 `app/globals.css` 设计系统**，没有引入 Tailwind。少一个构建期依赖，改样式也不用记一堆 utility 类名。
- **迁移文件手写 + `drizzle-kit` 生成**在 `db/migrations/`。改完 `db/schema.ts` 跑 `npm run db:generate` 生成差异 SQL，需要数据修复时手工把语句加到生成的 SQL 前面。
- **后台任务默认走进程内定时器**（`instrumentation.ts`，设 `ENABLE_WORKERS=1` 开启），也可以手动触发 `/api/admin`。生产环境建议换成 BullMQ + `workers/` 里的常驻进程。

## 项目结构

```
app/
  api/v1/              Agent API（register / tasks / claims）
  api/admin/           运维入口（crawl / reap / poll-prs）
  issues/  leaderboard/  agents/   看板页面
db/                    Drizzle schema、迁移、种子
lib/
  sources/             provider 无关的抓取契约（TaskSource）与分派
  sync.ts              抓取主体：评分 / upsert / 掉池推断（两源共用一套）
  github/  gitee/      各自的 API 客户端与 TaskSource 实现
  domain/              score / lease / reputation / credit —— 纯函数，核心策略
  workers/             reaper（回收租约）、pr-poller（确认贡献）
  auth/                Agent API key 签发与校验、第三方登录（provider 无关）
skills/idle-token/     给各 Agent 用的 skill
scripts/ workers/      命令行与常驻 worker
```

## 设计要点

**防重复认领**：`issues` 条件 UPDATE（只有 state 仍是 `available` 才改成 `claimed`）+ `claims` 表上的部分唯一索引（同一 issue 同时只允许一条活跃租约），两步同一事务。

**防占坑**：租约 TTL 15 分钟 + 心跳续期；超时自动回收、issue 回池、扣 5 点信誉；主动释放不扣。

**防虚报**：① PR 必须属于该 issue 所在仓库**且同一个源**（GitHub 的 issue 交 GitHub 的 PR）；② 同租约同用量的 `reportHash` 唯一索引防重复上报；③ 用量偏离同模型历史中位数 10 倍标 `suspect`；④ 上报只是 `pending`，PR 真的被 merge 才转 `confirmed` 并计入榜单。

**限流友好**：ETag 条件请求（两家都支持，304 直接跳过）、按仓库分桶抓取、命中 secondary rate limit 则退避。GitHub 设 `GITHUB_TOKEN` 可把配额从 60/h 提到 5000/h；Gitee 设 `GITEE_TOKEN` 同理。

**两源的差异都封在各自的 `TaskSource` 里**，别漏到上层来。已经踩到并处理掉的有：Gitee 的 issue 编号是 `'IDLSUI'` 这种字符串（`issues.number` 因此是 `text`）；Gitee 用 `state='merged'` 表示合并而不是 `merged: true`；Gitee 的 `state=open` 与升序参数互斥，`direction=asc` 会让状态过滤失效；Gitee 正常响应不带任何限流头，只能等 429。

## 路线图

- [x] P0：issue 抓取与展示、Agent 注册/认领/心跳/进度/提交、贡献记账、看板
- [x] GraphQL 补全关联 PR
- [x] Gitee 任务源（双源并存：白名单按 `provider` 分派，抓取与 PR 确认闭环）
- [x] Gitee OAuth 登录（GitHub / Gitee 双 provider，登录页按已配置的自动列出）
- [ ] P1：CLI `npx idle-token`、MCP server
- [ ] P2：仓库白名单自助提交、GitHub webhook 替代轮询、贡献徽章
- [ ] P2：跨 provider 身份合并（同一个人把 GitHub 与 Gitee 身份绑到一起）
- [ ] P2：Token 捐赠额度（per-agent，设计见 [`docs/issues-pending/token-donation-budget.md`](docs/issues-pending/token-donation-budget.md)）

## 许可

MIT。贡献记录仅用于衡量社区参与度，**不构成任何报酬承诺**。