Skip to content

Commit 1e6c178

Browse files
tuofangzhetuofangzhe
committed
docs: GitHub 流量优化 — README badges + CONTRIBUTING + SECURITY + CI + issue 模板
为 Google SEO 和 GitHub 推荐流量做的一次性优化: README: - 顶部加 4 个 badges:License (AGPL), Python 版本, Tests passing (CI), Live demo (veridrop.org) - 加英文 TL;DR 块,目标全球开发者搜索:"AI API relay authenticity", "needle-in-haystack long-context", "Claude thinking signature" 等 - 中文版主体保留(目标用户主流量),英文 + 中文双引擎 - 加 ⭐ Star CTA 引导社区互动信号 CONTRIBUTING.md(信任 + 活跃度信号): - Quick links 引向 issues / 设计文档 / live service - "什么 PR 欢迎" 表格(detector / protocol / baseline / docs / UI) - "什么不欢迎":anti-relay tools, 闭源 enterprise extensions, 佣金代码 - 本地 setup / test workflow - 风格约定 + PR process SECURITY.md(API key 处理透明度信号): - 列举我们对 API key 的承诺 + 每条都给代码可验证位置 - 私有漏洞报告流程(GitHub Security Advisories) - 明确 in-scope / out-of-scope - 防御深度承诺(磁盘永不接触 / 无 verbose mode 等) GitHub Actions CI (.github/workflows/test.yml): - 推 main / PR 自动跑 pytest - Python 3.10/3.11/3.12 矩阵 - pip cache 加速到 ~5s 安装 - ruff lint 软检查(continue-on-error) - 让 README "Tests passing" badge 真正生效 Issue templates(降低 issue 提交门槛 + 提示 /r/{id} URL 是最佳证据): - bug.yml — 引导用户给出 /r/{id} URL,prefilled redaction reminder - feature.yml — 新 detector / protocol 提案模板 - config.yml — 关掉空白 issue,提示三个 contact links (live demo / security / FAQ) 预期效果: - GitHub repo 主页有 description + topics 后,被推荐到 /topics/claude / /topics/api-relay 等聚合页 - README badges + CI passing + 完整 docs 让访客判断"成熟项目",转化星标 - SECURITY.md 让 API key 处理透明,降低用户使用顾虑 - Bilingual content 兼顾国内用户搜中文 + 国外用户搜英文
1 parent 803dfbb commit 1e6c178

7 files changed

Lines changed: 407 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: 🐛 Bug report
2+
description: Veridrop reported something wrong, or behaved unexpectedly
3+
title: "[Bug] "
4+
labels: [bug, triage]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for reporting! The single most useful thing you can give us is the
10+
**/r/{job_id} URL** if you ran on veridrop.org — it captures the full state.
11+
12+
- type: textarea
13+
id: what-happened
14+
attributes:
15+
label: What happened?
16+
description: What did Veridrop report, vs. what you expected?
17+
placeholder: |
18+
I sent api-key=sk-xxx, model=claude-sonnet-4-6, base_url=https://my-relay.com
19+
Veridrop reported `long_context: fail`, but I'm pretty sure my relay does support it.
20+
validations:
21+
required: true
22+
23+
- type: input
24+
id: report-url
25+
attributes:
26+
label: Report URL (most useful!)
27+
description: Paste the `https://veridrop.org/r/{job_id}` URL if you ran on the hosted service
28+
placeholder: https://veridrop.org/r/abc12345
29+
validations:
30+
required: false
31+
32+
- type: dropdown
33+
id: protocol
34+
attributes:
35+
label: Which protocol?
36+
options:
37+
- Anthropic (Claude)
38+
- OpenAI (GPT)
39+
- Gemini
40+
- Other
41+
validations:
42+
required: true
43+
44+
- type: input
45+
id: model
46+
attributes:
47+
label: Model tested
48+
placeholder: claude-haiku-4-5, gpt-4o-mini, gemini-2.5-flash, ...
49+
50+
- type: dropdown
51+
id: where
52+
attributes:
53+
label: Where did you run?
54+
options:
55+
- Hosted service (veridrop.org)
56+
- Self-hosted (this repo)
57+
- CLI (./venv/bin/relay-detector)
58+
validations:
59+
required: true
60+
61+
- type: textarea
62+
id: extra
63+
attributes:
64+
label: Anything else
65+
description: Logs, screenshots, JSON snippets, hypothesis about what's wrong
66+
placeholder: |
67+
Attach the full report.json if running locally:
68+
./venv/bin/relay-detector detect ... -o report.json
69+
70+
- type: checkboxes
71+
id: terms
72+
attributes:
73+
label: Pre-flight
74+
options:
75+
- label: I redacted my API key from any logs / JSON I'm pasting
76+
required: true
77+
- label: I searched existing issues for a similar report
78+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: 🌐 Try Veridrop live
4+
url: https://veridrop.org
5+
about: "Quick test: type your relay's URL + key, get a report in 30s. Free, no signup."
6+
- name: 🔒 Security vulnerability
7+
url: https://github.com/canarybyte/veridrop/security/advisories/new
8+
about: "Found a way to leak API keys or bypass detection? Use private disclosure."
9+
- name: 📖 Documentation / FAQ
10+
url: https://veridrop.org/faq
11+
about: "35+ Q&As about AI relay testing, authenticity verification, privacy."

‎.github/ISSUE_TEMPLATE/feature.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: 💡 Feature request / new detector
2+
description: Propose a new check, protocol, or capability
3+
title: "[Feature] "
4+
labels: [enhancement]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: What problem does this solve?
10+
description: Describe the relay behavior or user pain point this would address
11+
placeholder: |
12+
Example: relays sometimes strip prompt caching (cache_control). Today we
13+
don't detect this — users pay full price for cacheable content because
14+
their relay silently drops the cache_creation_input_tokens field.
15+
validations:
16+
required: true
17+
18+
- type: textarea
19+
id: proposal
20+
attributes:
21+
label: Proposed approach
22+
description: Sketch the detector or feature. Don't worry about being right — we'll discuss.
23+
placeholder: |
24+
Add a `cache_control` detector that:
25+
1. Sends a request with cache_control: ephemeral
26+
2. Sends the same request again
27+
3. Verifies usage.cache_read_input_tokens > 0 on the second call
28+
4. Reports fail if cache is silently stripped
29+
30+
- type: dropdown
31+
id: kind
32+
attributes:
33+
label: Type of contribution
34+
options:
35+
- New detector
36+
- New protocol (Bedrock / Vertex / etc.)
37+
- Web UI improvement
38+
- CLI improvement
39+
- Documentation
40+
- Other
41+
validations:
42+
required: true
43+
44+
- type: dropdown
45+
id: implement
46+
attributes:
47+
label: Are you offering to implement?
48+
options:
49+
- "Yes, I'll send a PR"
50+
- "Maybe — happy to discuss"
51+
- "No, just suggesting"

‎.github/workflows/test.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Tests
2+
3+
# Run on every push to main / PR. Cheap (no upstream API calls — all
4+
# detector tests are mocked) so we can always-on green-badge it.
5+
6+
on:
7+
push:
8+
branches: [main]
9+
pull_request:
10+
branches: [main]
11+
# Allow manual re-run from the Actions tab — useful when an OS-package
12+
# update flakes the build but the code is fine.
13+
workflow_dispatch:
14+
15+
jobs:
16+
pytest:
17+
runs-on: ubuntu-latest
18+
strategy:
19+
fail-fast: false
20+
matrix:
21+
python: ["3.10", "3.11", "3.12"]
22+
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Set up Python ${{ matrix.python }}
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: ${{ matrix.python }}
30+
# pip cache speeds up CI from ~60s install to ~5s
31+
cache: pip
32+
33+
- name: Install dependencies
34+
run: |
35+
python -m pip install --upgrade pip
36+
pip install -e ".[dev,web]"
37+
38+
- name: Run pytest
39+
# tests/conftest.py points VERIDROP_JOBS_DIR / WISHLIST at /tmp
40+
# so jobs.py module-level mkdir doesn't try to write /opt
41+
run: pytest tests/ -v --tb=short
42+
43+
lint:
44+
# Soft check — never blocks main, but we publish ruff results so
45+
# contributors see style issues before reviewers do. Add `|| true`
46+
# when ruff first runs to avoid breaking initial CI before we've
47+
# cleaned up any historical style debt.
48+
runs-on: ubuntu-latest
49+
continue-on-error: true
50+
steps:
51+
- uses: actions/checkout@v4
52+
- uses: actions/setup-python@v5
53+
with:
54+
python-version: "3.12"
55+
cache: pip
56+
- run: pip install ruff
57+
- run: ruff check src/ web/ tests/ || true

‎CONTRIBUTING.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Contributing to Veridrop
2+
3+
Thanks for considering a contribution! This is an open-source project under
4+
AGPL-3.0 — your fixes and additions help the whole AI relay community.
5+
6+
## Quick links
7+
8+
- **Issues / bug reports**: [github.com/canarybyte/veridrop/issues](https://github.com/canarybyte/veridrop/issues)
9+
- **Live service**: [veridrop.org](https://veridrop.org) — useful for "this relay
10+
shows X but I expected Y" reports (paste the `/r/{job_id}` URL)
11+
- **Design docs**: [DESIGN.md](DESIGN.md) — architecture overview
12+
- **Detector design**: [DESIGN.md §3 / §6](DESIGN.md) — how each detector works
13+
14+
## Setting up locally
15+
16+
```bash
17+
git clone git@github.com:canarybyte/veridrop.git
18+
cd veridrop
19+
20+
python3 -m venv venv
21+
./venv/bin/pip install -e ".[dev,web]"
22+
23+
# Run the test suite (should be ~240 tests, all passing)
24+
./venv/bin/pytest tests/ -v
25+
26+
# Boot the local web service (http://localhost:8000)
27+
VERIDROP_JOBS_DIR=/tmp/veridrop-dev ./venv/bin/uvicorn web.server:app --reload
28+
```
29+
30+
## What kinds of PRs are welcome
31+
32+
| Type | Examples | Notes |
33+
|---|---|---|
34+
| 🐛 **Bug fixes** | False positives in long-context, edge cases in tokenizer estimation, broken UI states | Always include a regression test |
35+
| 🔬 **New detectors** | Cache-control honoring, image-input detection, system-fingerprint check | See [DESIGN.md §6.2](DESIGN.md) for `ActiveDetector` / `PassiveDetector` interfaces |
36+
| 🌐 **New protocols** | Anthropic Bedrock, Vertex AI native, Mistral, DeepSeek | Mirror the `protocols/anthropic/` structure; aim for ≥80% test coverage |
37+
| 📊 **Baseline data** | New official model baselines for `data/baselines/` | Run `bench.sh` against the official API; commit only the JSON output |
38+
| 📖 **Docs / FAQ** | New questions, translations, examples | Bilingual welcome (中文 + English) |
39+
| 🎨 **UI / UX** | Better mobile layout, accessibility, dark mode | Don't add JS frameworks — keep it vanilla |
40+
41+
## What's NOT in scope
42+
43+
- **Anti-relay tools**: Veridrop verifies relays, not bypasses them. Don't propose
44+
features that help users evade rate limits / account bans.
45+
- **Closed-source enterprise extensions**: Per AGPL-3.0, modifications running as
46+
a service must also be open-sourced. PRs adding closed-source hooks will be
47+
rejected.
48+
- **Affiliate / commission code**: Business-layer code lives in a separate
49+
private repo by design (see [README.md `项目治理`](README.md)). The public
50+
repo is for the trust path only — detection, scoring, transparency.
51+
52+
## Code style
53+
54+
- **Python**: PEP 8, but loose. Function comments explain *why*, not *what*.
55+
See existing code for tone — comments often note the bug-of-the-day or the
56+
gotcha being defended against.
57+
- **Tests**: pytest, async via `pytest-asyncio`. Mock external API calls;
58+
never make real upstream calls in unit tests.
59+
- **Detector pattern**: see `protocols/anthropic/detectors/identity.py` for
60+
the canonical small detector. Keep `run()` short; helpers go in
61+
`_underscored_helpers()` below the class.
62+
- **Commit messages**: imperative (`fix:`, `feat:`, `docs:` etc.). Bilingual
63+
is fine.
64+
65+
## PR process
66+
67+
1. **Open an issue first** if the change is non-trivial — saves both of us time
68+
if the design needs discussion.
69+
2. **One feature per PR**. Multiple unrelated changes get split or asked for splits.
70+
3. **Tests must pass** locally before pushing (`./venv/bin/pytest tests/`).
71+
CI will rerun them on push.
72+
4. **Update docs** if you changed user-facing behavior — README, FAQ, or
73+
in-code docstrings.
74+
75+
## Reporting bugs
76+
77+
Open an issue with:
78+
79+
- **What you expected**: e.g. "I sent X to relay Y, expected `pass`"
80+
- **What happened**: e.g. "got `fail` with summary 'Z' — but Y is the
81+
official anthropic.com"
82+
- **The `/r/{job_id}` URL** if you ran on veridrop.org
83+
- **The full JSON** if you ran locally (`detect -o report.json`)
84+
85+
Live data is the fastest path to a fix — half the bugs we've found this year
86+
came from someone running a real relay and noticing surprising output.
87+
88+
## Security
89+
90+
If you find a security vulnerability (e.g. a way the service could log API
91+
keys, an injection vector, etc.), please **do NOT open a public issue**. See
92+
[SECURITY.md](SECURITY.md) for responsible disclosure.
93+
94+
## License
95+
96+
By submitting a PR, you agree your contribution is licensed under
97+
**AGPL-3.0-or-later** — same as the rest of the project. We don't require
98+
a CLA.

‎README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,33 @@
11
# Veridrop · AI API 中转站检测工具
22

3+
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
4+
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
5+
[![Tests](https://github.com/canarybyte/veridrop/actions/workflows/test.yml/badge.svg)](https://github.com/canarybyte/veridrop/actions/workflows/test.yml)
6+
[![Live demo](https://img.shields.io/badge/demo-veridrop.org-10b981.svg)](https://veridrop.org)
7+
8+
> **TL;DR (English)**: Open-source authenticity & quality detector for AI API relays
9+
> (proxies). Given `base_url + api_key + model`, Veridrop runs probes against the relay,
10+
> compares results to a known-good baseline, and answers three questions:
11+
>
12+
> 1. **Authenticity** — is the relay actually serving the Claude / GPT / Gemini model
13+
> it claims? (uses **Claude thinking signature** crypto verification, the only
14+
> cryptographic-grade authenticity check in this category)
15+
> 2. **Capability** — has the relay stripped PDF / Tool Use / Thinking / Function
16+
> Calling support?
17+
> 3. **Compliance** — do response fields, ID prefixes, streaming events, and usage
18+
> accounting match the official protocol?
19+
>
20+
> Bonus: **needle-in-haystack long-context probing** (32k → 1M tokens) catches
21+
> relays that advertise 1M context but silently truncate at 200k.
22+
>
23+
> Live demo at **[veridrop.org](https://veridrop.org)** — no sign-up, API key
24+
> never persisted. Self-host with one `docker compose up` (see below).
25+
>
26+
> ⭐ If you've ever been burned by a fake relay, **star this repo** so others
27+
> can find it.
28+
29+
---
30+
331
一个开源的 AI API 中转站(relay / proxy)真伪与质量检测工具。给定一个 `base_url + api_key + model`,自动跑一组探针请求,把结果跟「官方真品基线」做**字段级、协议级、加密级**对比,回答三个问题:
432

533
1. **真伪**:这家中转站给我的真的是它声称的模型吗?(Claude / GPT / Gemini)

0 commit comments

Comments
 (0)