piyushdhoka/Capgent

## 这是什么？ **Capgent** 是一个面向代理的访问控制小平台： 1. 客户端（脚本、服务或“代理”）调用你的 API 以 **开始挑战**。 2. 它接收 **指令** 和不透明的 **数据**；它必须应用一组定义的 **字节操作**（切片、XOR、哈希、HMAC 等）并返回正确的 **答案 + HMAC**。 3. 如果正确，API 返回一个 **证明 JWT**（短时效）。你也可以注册 **身份令牌** 并将使用与 **项目和 API 密钥** 关联到仪表板。 因此在实践中：**不实现你的流程的通用爬虫和客户端会失败**；**运行该协议已注册的集成会成功**。它**不是**证明调用者“不是人类”——任何运行你的客户端或 SDK 的人都可以通过。它是一个**结构化协议 + 密钥 + 令牌**门控，类似于“机器的 OAuth”，带有显式的挑战步骤。 ## 它面向谁？ | 你想…… | Capgent 的帮助方式 | |--------------|-------------------| | 限制访问你 API 的 **自动化** | 要求挑战 → 验证 → 承载证明（或身份）在受保护路由上 | | **按项目发放 API 密钥** | 仪表板 + Worker 支持的项目/密钥 API | | **在浏览器中演示流程** | [游乐场](https://capgent.vercel.app/playground) 和应用内 `/docs` | | **让代理证明已完成运行** | 证明 JWT + 可选的问答录 / 基准报告 | | **从 TypeScript 集成** | 已发布的 npm 包 **`capgent-sdk`** | ## 各部分如何协同工作 ``` ┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Next.js │ │ Cloudflare Worker │ │ Neon + Upstash │ │ (apps/web) │────▶│ (apps/api, Hono) │────▶│ DB, Redis, etc. │ │ UI, auth │ │ challenges, JWT │ │ │ └─────────────┘ └──────────────────┘ └─────────────────┘ │ └── capgent-sdk (npm) — same HTTP API from Node, Bun, Workers, etc. ``` **典型集成流程** 1. `POST /api/challenge` — 获取 `challenge_id`、`nonce`、`data_b64`、`instructions`。 2. 解析指令 → 计算 **答案**（变换字节的 SHA-256）和 **HMAC**（使用 `nonce` 的 HMAC-SHA256）。 3. `POST /api/verify/{challenge_id}` — 接收 **证明 JWT**。 4. 调用 **`GET /api/protected/ping`**（或你自己的网关）并带上 `Authorization: Bearer `。 可选：通过头部 `X-Capgent-Api-Key` 提供 **项目 API 密钥**（如果 API 需要）。发现：`GET /.well-known/capgent.json`（旧版 `capagent.json` 仍有效并返回相同负载）。 ## 单体仓库布局 | 路径 | 角色 | |------|------| | [`apps/api`](apps/api) | 基于 **Cloudflare Workers** 的 Hono 应用 — 挑战、验证、受保护 ping、代理、问答、基准测试、项目密钥 | | [`apps/web`](apps/web) | **Next.js 16** — 营销、**仪表板**、**文档**、**游乐场**、邮箱认证（Neon） | | [`packages/sdk`](packages/sdk) | **`capgent-sdk`** — TypeScript 客户端，发布到 npm | | [`agents`](agents) | 示例运行器（OpenRouter / Grok / Gemini）和基准脚本 | **路由说明：** 仪表板认证可通过 [`apps/web/proxy.ts`](apps/web/proxy.ts)（Next.js 代理）对受保护段进行 Cookie/会话检查。 ## 本地快速启动 需要 **[Bun](https://bun.sh/)** 在仓库根目录。 ``` bun install ``` **终端 1 — API**（默认 `http://127.0.0.1:8787`）： ``` bun run dev:api ``` **终端 2 — Web**（`http://localhost:3000`）： ``` bun run dev:web ``` **Wrangler / 本地 Worker 密钥：** 使用 **`apps/api/.dev.vars`**（.gitignore 忽略）。至少设置 **`UPSTASH_REDIS_REST_URL`** 和 **`UPSTASH_REDIS_REST_TOKEN`**（如需让问答录和基准测试在内存开发后仍持久化）。镜像 **`CAPAGENT_*`** 变量来自 [`apps/api/wrangler.toml`](apps/api/wrangler.toml) `[vars]` 并按需添加密钥（例如 `DATABASE_URL`、`CAPAGENT_JWT_SECRET`）。 **Web 环境：** 从 [`apps/web/.env.example`](apps/web/.env.example) 复制到 `apps/web/.env` 或 `.env.local` 并设置 `NEXT_PUBLIC_CAPAGENT_API_BASE_URL`（例如 `http://127.0.0.1:8787`）、`SESSION_SECRET`、`DATABASE_URL` 以及可选的邮箱/OpenRouter 密钥。 | 本地 URL | 用途 | |-----------|------| | http://localhost:3000 | 着陆页 | | http://localhost:3000/docs | 集成指南 + 示例 | | http://localhost:3000/playground | 浏览器中的挑战 → 验证 | | http://localhost:3000/dashboard | 项目与 API 密钥（登录后） | | http://127.0.0.1:8787 | Worker API 基路径 | **示例代理** ``` cd agents # 查看 package.json — grok/gemini 示例，基准测试 ``` 复制 [`agents/.env.example`](agents/.env.example) → `agents/.env.local` 并设置 `CAPAGENT_API_BASE_URL`、`OPENROUTER_API_KEY` 等。 ### 根脚本 | 命令 | 用途 | |---------|---------| | `bun run dev:api` | Worker 开发服务器 | | `bun run dev:web` | Next.js 开发 | | `bun run build` | 构建 SDK + API（干运行）+ 构建 Web | | `bun run build:sdk` | 编译 `packages/sdk` → `dist/` | | `bun run typecheck` | 类型检查 API、Web、SDK | ## 环境变量（速查表） ### Worker — [`apps/api`](apps/api) 通过 **`wrangler.toml`** `[vars]`、**`wrangler secret put`** 和/或 **`.dev.vars`** 本地配置。 **生产通常需要** - `UPSTASH_REDIS_REST_URL`、`UPSTASH_REDIS_REST_TOKEN` - `CAPAGENT_JWT_SECRET` - `DATABASE_URL`（Neon）— 项目/API 密钥与 Web 用户绑定 - `CAPAGENT_PUBLIC_BASE_URL`、`CAPAGENT_CORS_ORIGINS` **常调优** - `CAPAGENT_CHALLENGE_TTL_SECONDS`、`CAPAGENT_PROOF_TTL_SECONDS`、`CAPAGENT_IDENTITY_TTL_SECONDS` - `CAPAGENT_ALLOW_PUBLIC_REGISTRATION`、`CAPAGENT_ADMIN_API_KEY` - `CAPAGENT_RATE_LIMIT_*`、`CAPAGENT_GUESTBOOK_COOLDOWN_SECONDS` - `CAPAGENT_FORCE_INMEMORY` — 仅 `1` 用于无 Redis 持久化的快速本地测试 ### Web — [`apps/webapps/web) - `NEXT_PUBLIC_CAPAGENT_API_BASE_URL` — 浏览器面向的 API URL（Worker 或同源代理） - `SESSION_SECRET` — Cookie 会话（≥ 32 字符） - `DATABASE_URL` — Neon 用于用户、项目、密钥 - 如需注册和邮箱验证，请配置 SMTP / OAuth 密钥（参考应用环境模式） ## 部署 **API（Cloudflare）** ``` cd apps/api bun run deploy ``` 将 Cloudflare **密钥**和**变量**设置为匹配 Worker `Env` 类型（参考 [`apps/api/src/config.ts`](apps/api/src/config.ts)）。**不要**在生产中使用 `CAPAGENT_FORCE_INMEMORY=1`，如果依赖 Redis 支撑的功能。 **Web（例如 Vercel）** - 根目录：**`apps/web`**（或你的单体构建命令） - 设置 `NEXT_PUBLIC_CAPAGENT_API_BASE_URL` 为你的 **生产 Worker URL** - 设置 `SESSION_SECRET`、`DATABASE_URL` 等以匹配 Neon 和邮箱 从仓库根目录构建： ``` bun run build:web ``` ## npm：发布 `capgent-sdk` npm 上的包名为 **`capgent-sdk`**（[`packages/sdk`](packages/sdk)）。发布时更新 `packages/sdk/package.json` 中的 **`version`**。 **一次性操作：** [创建 npm 账户](https://www.npmjs.com/signup) 并登录： ``` npm login ``` **每次发布** ``` cd packages/sdk bun run build npm publish --access public ``` 干运行（不上传）： ``` cd packages/sdk bun run build npm publish --access public --dry-run ``` 发布后，消费者可通过以下方式安装： ``` npm install capgent-sdk ``` **破坏性变更** 在 [`packages/sdk/README.md`](packages/sdk/README.md) 中说明（例如 v2 类型/帮助器重命名）。使用 `createClient` 从 `capgent-sdk` 传入 `CAPAGENT_API_BASE_URL` / API 密钥环境变量，如文档所述。 ## SDK 示例 ``` import { createClient } from "capgent-sdk" import { solveChallengeFromSteps } from "capgent-sdk/solver" import { parseCanonicalStepsFromInstructions } from "capgent-sdk/parser/heuristic" const client = createClient({ baseUrl: process.env.CAPAGENT_API_BASE_URL!, apiKey: process.env.CAPAGENT_API_KEY, // project key when required agentName: "my-service", agentVersion: "1.0.0", }) const ch = await client.getChallenge() const steps = parseCanonicalStepsFromInstructions(ch.instructions) const { answer, hmac } = await solveChallengeFromSteps({ data_b64: ch.data_b64, nonce: ch.nonce, steps, }) const proof = await client.verifyChallenge(ch.challenge_id, answer, hmac) await client.protectedPing(proof.token) ``` 完整表格、curl 和中间件模式：**https://capgent.vercel.app/docs**（或本地 `/docs`）。 ## 进一步阅读 - [`Context.md`](Context.md) — 产品与架构说明 - [`packages/sdk/README.md`](packages/sdk/README.md) — SDK 安装、错误处理、OpenRouter 解析器

_{Capgent — 面向自动客户端的协议优先验证与 API 密钥。}