Skip to content

Commit 9a16cfa

Browse files
authored
docs: region-neutral user-facing docs (remove region machinery + cross-refs) (#51)
Align CLI/MCP/SDK/setup docs with website doc policy: - No internal region setup wording (QVERIS_REGION, sk-cn vs sk-xxx region table, region-selection UI, config/region.mjs, region auto-detect copy). - No cross-region references: Global docs (docs/en-US, docs/zh-CN) present only the qveris.ai world; CN docs (docs/cn/zh-CN) present only the qveris.cn world. Removed dual-site footers, 'China region example', python-sdk 'global default vs China' framing, sk-cn key prefixes. - Provider-level 'region' capability attribute (alongside success_rate / latency / billing_rule) kept — it is a product field, not site region. Files: cli.md, mcp-server.md, python-sdk.md, ide-cli-setup.md across docs/en-US + docs/zh-CN + docs/cn/zh-CN. Verified: no region machinery / cross-region refs remain in either world.
1 parent 535e30d commit 9a16cfa

10 files changed

Lines changed: 43 additions & 235 deletions

File tree

docs/cn/zh-CN/cli.md

Lines changed: 11 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -264,34 +264,23 @@ qveris mcp validate --target cursor --probe
264264

265265
### `qveris login`
266266

267-
使用 QVeris API 密钥认证。如果未预设区域,会先提示选择站点区域(全球 / 中国),然后打开对应的 API 密钥页面并掩码输入。
267+
使用 QVeris API 密钥认证。打开浏览器进入 API 密钥页面并掩码输入。
268268

269269
```bash
270270
qveris login [flags]
271271
```
272272

273273
| 参数 | 说明 |
274274
|------|------|
275-
| `--token <key>` | 直接提供密钥(跳过浏览器和区域选择|
275+
| `--token <key>` | 直接提供密钥(跳过浏览器|
276276
| `--no-browser` | 不打开浏览器 |
277277

278278
```bash
279-
# 交互式(选择区域 → 打开浏览器 → 掩码输入)
279+
# 交互式(打开浏览器 → 掩码输入)
280280
qveris login
281281

282282
# 非交互式
283-
qveris login --token "sk-cn-your-key-here"
284-
```
285-
286-
交互式登录时,如果未设置 `QVERIS_REGION``--base-url`,会提示选择区域:
287-
288-
```
289-
选择站点区域:
290-
291-
1) 全球 — qveris.ai (国际用户)
292-
2) 中国 — qveris.cn (中国大陆用户)
293-
294-
输入 1 或 2:
283+
qveris login --token "sk-1_your-key-here"
295284
```
296285

297286
密钥保存到 `~/.config/qveris/config.json`,权限为 `0600`(仅所有者可读写)。
@@ -302,7 +291,7 @@ qveris login --token "sk-cn-your-key-here"
302291

303292
### `qveris whoami`
304293

305-
显示当前认证状态、密钥来源、所属区域,并验证密钥有效性。
294+
显示当前认证状态、密钥来源,并验证密钥有效性。
306295

307296
### `qveris credits`
308297

@@ -371,7 +360,7 @@ qveris> exit
371360

372361
### `qveris doctor`
373362

374-
自检诊断:验证 Node.js 版本、API 密钥配置、区域和 API 地址、API 连通性。
363+
自检诊断:验证 Node.js 版本、API 密钥配置、API 地址、API 连通性。
375364

376365
### `qveris config`
377366

@@ -442,8 +431,7 @@ qveris history [--clear]
442431
| 变量 | 说明 | 默认值 |
443432
|------|------|--------|
444433
| `QVERIS_API_KEY` | API 认证密钥 ||
445-
| `QVERIS_REGION` | 强制区域:`global``cn` | 从密钥自动检测 |
446-
| `QVERIS_BASE_URL` | 覆盖 API 地址 | 从区域自动设置 |
434+
| `QVERIS_BASE_URL` | 覆盖 API 地址 | 从密钥自动设置 |
447435
| `QVERIS_DEFAULT_LIMIT` | 默认 discover 限制 | 5 |
448436
| `QVERIS_DEFAULT_MAX_SIZE` | 默认响应大小限制 | 4096 |
449437
| `XDG_CONFIG_HOME` | 配置目录基础路径 | `~/.config` |
@@ -454,43 +442,13 @@ qveris history [--clear]
454442

455443
---
456444

457-
## 区域
458-
459-
区域从 API 密钥前缀自动检测,无需额外配置。中国大陆用户使用 `sk-cn-` 前缀的密钥即可自动指向 `https://qveris.cn`
460-
461-
| 密钥前缀 | 区域 | API 地址 |
462-
|----------|------|----------|
463-
| `sk-xxx` | 全球 | `https://qveris.ai/api/v1` |
464-
| `sk-cn-xxx` | 中国 | `https://qveris.cn/api/v1` |
465-
466-
**交互式登录:**运行 `qveris login` 时,如果未设置 `QVERIS_REGION``--base-url`,会提示选择区域。仅用于首次人工登录。
467-
468-
**Agent / 脚本使用:**Agent 和脚本应跳过交互式提示。区域自动解析:
469-
470-
```bash
471-
# 方式 1:密钥前缀自动检测(推荐)
472-
qveris login --token "sk-cn-xxx" # 自动检测为中国区
473-
474-
# 方式 2:环境变量
475-
export QVERIS_REGION=cn
476-
qveris login --token "sk-xxx"
477-
478-
# 方式 3:显式 API 地址
479-
export QVERIS_BASE_URL=https://qveris.cn/api/v1
480-
481-
# 方式 4:单次命令参数
482-
qveris discover "天气" --base-url https://qveris.cn/api/v1
483-
```
484-
485-
---
486-
487445
## 会话管理
488446

489447
每次 `discover` 后,CLI 将会话状态保存到 `~/.config/qveris/.session.json`
490448

491449
- 发现 ID
492450
- 查询内容
493-
- 区域和 API 地址
451+
- API 地址
494452
- 结果列表(tool_id、名称、提供商)
495453

496454
后续 `inspect``call` 自动读取会话,支持数字索引快捷方式:
@@ -577,7 +535,7 @@ qveris call "$TOOL" --discovery-id "$SEARCH_ID" --params '{"city":"London"}' --j
577535
│ ├── commands/ # 12 个命令处理器
578536
│ ├── client/api.mjs # HTTP 客户端(原生 fetch)
579537
│ ├── client/auth.mjs # API 密钥解析
580-
│ ├── config/region.mjs # 区域自动检测
538+
│ ├── config/endpoint.mjs # API 地址解析
581539
│ ├── config/store.mjs # 配置文件读写(0600 权限)
582540
│ ├── session/session.mjs # 会话持久化
583541
│ ├── output/formatter.mjs # 人类友好格式化
@@ -592,9 +550,9 @@ qveris call "$TOOL" --discovery-id "$SEARCH_ID" --params '{"city":"London"}' --j
592550

593551
## 链接
594552

595-
- 官网:[qveris.cn](https://qveris.cn)(中国)/ [qveris.ai](https://qveris.ai)(全球)
553+
- 官网:[qveris.cn](https://qveris.cn)
596554
- GitHub:[QVerisAI/qveris-agent-toolkit](https://github.com/QVerisAI/qveris-agent-toolkit)
597555
- npm:[@qverisai/cli](https://www.npmjs.com/package/@qverisai/cli)
598556
- REST API:[docs/cn/zh-CN/rest-api.md](rest-api.md)
599557
- MCP 服务器:[docs/cn/zh-CN/mcp-server.md](mcp-server.md)
600-
- 获取 API 密钥:[qveris.cn/account](https://qveris.cn/account?page=api-keys) / [qveris.ai/account](https://qveris.ai/account?page=api-keys)
558+
- 获取 API 密钥:[qveris.cn/account](https://qveris.cn/account?page=api-keys)

docs/cn/zh-CN/ide-cli-setup.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,5 +24,5 @@ QVeris 已集成到多种 IDE 和 CLI 编程工具中。通过自动配置 QVeri
2424

2525
OpenCode:
2626
```
27-
请按照 https://github.com/QVerisAI/qveris-agent-toolkit/blob/main/docs/cn/zh-CN/opencode-setup.md 帮我完成配置。API 密钥是 sk-cn-xxxxxxxxxxxxx
27+
请按照 https://github.com/QVerisAI/qveris-agent-toolkit/blob/main/docs/cn/zh-CN/opencode-setup.md 帮我完成配置。API 密钥是 sk-xxxxxxxxxxxxx
2828
```

docs/cn/zh-CN/mcp-server.md

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,10 @@ npx -y @qverisai/mcp
6363
MCP 服务器从以下环境变量读取配置:
6464

6565
```bash
66-
QVERIS_API_KEY=sk-cn-your-api-key # 必填
67-
QVERIS_REGION=cn # 可选:强制区域(global | cn)
66+
QVERIS_API_KEY=your-api-key # 必填
6867
QVERIS_BASE_URL=https://... # 可选:覆盖 API 地址
6968
```
7069

71-
区域从 API 密钥前缀自动检测(`sk-cn-xxx` → 中国区,`sk-xxx` → 全球)。中国大陆用户使用 `sk-cn-` 前缀的密钥即可自动指向 `https://qveris.cn`,仅在需要覆盖时设置 `QVERIS_REGION`
72-
7370
### 使用 QVeris CLI 配置
7471

7572
可以用 CLI 生成客户端配置,无需手写 JSON。默认会打印带有 `YOUR_QVERIS_API_KEY` 占位符的安全配置;占位符输出会故意无法通过 API key 校验,直到你替换占位符或使用 `--include-key`
@@ -105,26 +102,7 @@ qveris mcp validate --target cursor --probe
105102
"command": "npx",
106103
"args": ["-y", "@qverisai/mcp"],
107104
"env": {
108-
"QVERIS_API_KEY": "sk-cn-your-api-key-here"
109-
}
110-
}
111-
}
112-
}
113-
```
114-
115-
### 中国区配置示例
116-
117-
中国大陆用户使用 `sk-cn-` 前缀的密钥即可自动指向中国区;也可显式添加 `QVERIS_REGION`
118-
119-
```json
120-
{
121-
"mcpServers": {
122-
"qveris": {
123-
"command": "npx",
124-
"args": ["-y", "@qverisai/mcp"],
125-
"env": {
126-
"QVERIS_API_KEY": "sk-cn-your-api-key-here",
127-
"QVERIS_REGION": "cn"
105+
"QVERIS_API_KEY": "your-api-key-here"
128106
}
129107
}
130108
}

docs/cn/zh-CN/python-sdk.md

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,28 +17,26 @@ pip install qveris
1717

1818
需要 Python 3.8+。运行时依赖:`httpx``pydantic``pydantic-settings``openai`
1919

20-
## 身份认证(中国区)
20+
## 身份认证
2121

22-
SDK 从环境变量 `QVERIS_API_KEY` 读取 API 密钥**SDK 默认指向全球区 `https://qveris.ai/api/v1/`,中国区用户必须显式指向 `https://qveris.cn`**
22+
SDK 从环境变量 `QVERIS_API_KEY` 读取 API 密钥,并通过 `QVERIS_BASE_URL` 指向 API 地址。请设置
2323

2424
```bash
25-
export QVERIS_API_KEY="sk-cn-..."
25+
export QVERIS_API_KEY="your-api-key"
2626
export QVERIS_BASE_URL="https://qveris.cn/api/v1"
2727
```
2828

29-
[qveris.cn](https://qveris.cn) 获取密钥(中国区密钥为 `sk-cn-` 前缀)。也可以显式传入配置:
29+
[qveris.cn](https://qveris.cn) 获取密钥。也可以显式传入配置:
3030

3131
```python
3232
from qveris import QverisClient, QverisConfig
3333

3434
client = QverisClient(QverisConfig(
35-
api_key="sk-cn-...",
35+
api_key="your-api-key",
3636
base_url="https://qveris.cn/api/v1",
3737
))
3838
```
3939

40-
> 注意:与 CLI / MCP 服务器不同,Python SDK **不会**根据 `sk-cn-` 前缀自动切换区域。中国区必须通过 `QVERIS_BASE_URL` 环境变量或 `QverisConfig(base_url=...)` 显式设置 `https://qveris.cn/api/v1`
41-
4240
## 快速开始
4341

4442
核心流程是 **discover(发现)→ inspect(检查)→ call(调用)**,之后可选 **audit(审计)**。所有方法都是 `async`
@@ -97,7 +95,7 @@ export OPENAI_API_KEY="..."
9795
export OPENAI_BASE_URL="https://your-openai-compatible-endpoint/v1" # 你的 OpenAI 兼容服务地址
9896
```
9997

100-
QVeris 区域仍由 `QVERIS_BASE_URL` 控制,与 LLM provider 相互独立。
98+
QVeris API 地址仍由 `QVERIS_BASE_URL` 控制,与 LLM provider 相互独立。
10199

102100
### 流式
103101

@@ -151,7 +149,7 @@ async with Agent(config=QverisConfig(base_url="https://qveris.cn/api/v1")) as ag
151149
| 字段 | 环境变量 | 默认值 | 说明 |
152150
|------|---------|--------|------|
153151
| `api_key` | `QVERIS_API_KEY` | `None` | API 密钥,以 `Authorization: Bearer ...` 发送 |
154-
| `base_url` | `QVERIS_BASE_URL` | `https://qveris.ai/api/v1/` | API 基础地址**中国区须设为 `https://qveris.cn/api/v1`** |
152+
| `base_url` | `QVERIS_BASE_URL` | `https://qveris.cn/api/v1` | API 基础地址 |
155153
| `enable_history_pruning` || `True` | 裁剪/压缩旧的工具输出以节省 token(agent 循环) |
156154
| `max_iterations` || `50` | agent 工具循环的最大迭代次数 |
157155

docs/en-US/cli.md

Lines changed: 10 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -268,36 +268,25 @@ qveris mcp validate --target cursor --probe
268268

269269
### `qveris login`
270270

271-
Authenticate with your QVeris API key. If no region is pre-configured, prompts you to select your region (Global or China), then opens the browser to the corresponding API key page and prompts for masked input.
271+
Authenticate with your QVeris API key. Opens the browser to the API key page and prompts for masked input.
272272

273273
```bash
274274
qveris login [flags]
275275
```
276276

277277
| Flag | Description |
278278
|------|-------------|
279-
| `--token <key>` | Provide key directly (skip browser and region prompt) |
279+
| `--token <key>` | Provide key directly (skip browser prompt) |
280280
| `--no-browser` | Don't open browser |
281281

282282
```bash
283-
# Interactive (select region → opens browser → masked input)
283+
# Interactive (opens browser → masked input)
284284
qveris login
285285

286286
# Non-interactive
287287
qveris login --token "sk-1_your-key-here"
288288
```
289289

290-
During interactive login, if `QVERIS_REGION` or `--base-url` is not set, you will be prompted:
291-
292-
```
293-
Select your region / 选择站点区域:
294-
295-
1) Global — qveris.ai (International users)
296-
2) China — qveris.cn (中国大陆用户)
297-
298-
Enter 1 or 2:
299-
```
300-
301290
The key is saved to `~/.config/qveris/config.json` with `0600` permissions (owner-only).
302291

303292
### `qveris logout`
@@ -310,7 +299,7 @@ qveris logout
310299

311300
### `qveris whoami`
312301

313-
Show current auth status, key source, resolved region, and validate against the API.
302+
Show current auth status and key source, and validate against the API.
314303

315304
```bash
316305
qveris whoami
@@ -422,7 +411,7 @@ qveris> exit
422411

423412
### `qveris doctor`
424413

425-
Self-check diagnostics: verifies Node.js version, API key configuration, resolved region and base URL, and API connectivity.
414+
Self-check diagnostics: verifies Node.js version, API key configuration, base URL, and API connectivity.
426415

427416
```bash
428417
qveris doctor
@@ -497,8 +486,7 @@ Use `--` to end option parsing: `qveris discover -- --literal-query`.
497486
| Variable | Description | Default |
498487
|----------|-------------|---------|
499488
| `QVERIS_API_KEY` | API authentication key ||
500-
| `QVERIS_REGION` | Force region: `global` or `cn` | auto from key |
501-
| `QVERIS_BASE_URL` | Override API base URL | auto from region |
489+
| `QVERIS_BASE_URL` | Override API base URL | auto from key |
502490
| `QVERIS_DEFAULT_LIMIT` | Default discover limit | 5 |
503491
| `QVERIS_DEFAULT_MAX_SIZE` | Default response size limit | 4096 |
504492
| `XDG_CONFIG_HOME` | Config directory base | `~/.config` |
@@ -509,43 +497,13 @@ Use `--` to end option parsing: `qveris discover -- --literal-query`.
509497

510498
---
511499

512-
## Region
513-
514-
Region is auto-detected from your API key prefix. No extra configuration needed.
515-
516-
| Key prefix | Region | Base URL |
517-
|------------|--------|----------|
518-
| `sk-xxx` | Global | `https://qveris.ai/api/v1` |
519-
| `sk-cn-xxx` | China | `https://qveris.cn/api/v1` |
520-
521-
**Interactive login:** When running `qveris login` without `QVERIS_REGION` or `--base-url`, you'll be prompted to choose a region. This is for first-time human users only.
522-
523-
**Agent / script usage:** Agents and scripts should skip the interactive prompt. Region is resolved automatically:
524-
525-
```bash
526-
# Option 1: Key prefix auto-detection (recommended)
527-
qveris login --token "sk-cn-xxx" # auto-detects China region
528-
529-
# Option 2: Environment variable
530-
export QVERIS_REGION=cn
531-
qveris login --token "sk-xxx"
532-
533-
# Option 3: Explicit base URL
534-
export QVERIS_BASE_URL=https://qveris.cn/api/v1
535-
536-
# Option 4: Per-command flag
537-
qveris discover "weather" --base-url https://qveris.cn/api/v1
538-
```
539-
540-
---
541-
542500
## Session Management
543501

544502
After each `discover`, the CLI saves session state to `~/.config/qveris/.session.json`:
545503

546504
- Discovery ID
547505
- Query
548-
- Region and base URL
506+
- Base URL
549507
- Result list (tool_id, name, provider)
550508

551509
Subsequent `inspect` and `call` commands auto-read this session, enabling numeric index shortcuts:
@@ -632,7 +590,7 @@ For backward compatibility, the following aliases are supported with deprecation
632590
│ ├── commands/ # 12 command handlers
633591
│ ├── client/api.mjs # HTTP client (native fetch)
634592
│ ├── client/auth.mjs # API key resolution
635-
│ ├── config/region.mjs # Region auto-detection
593+
│ ├── config/endpoint.mjs # API endpoint resolution
636594
│ ├── config/store.mjs # Config file R/W (0600 perms)
637595
│ ├── session/session.mjs # Session persistence
638596
│ ├── output/formatter.mjs # Human-readable formatting
@@ -647,9 +605,9 @@ For backward compatibility, the following aliases are supported with deprecation
647605

648606
## Links
649607

650-
- Website: [qveris.ai](https://qveris.ai) (Global) / [qveris.cn](https://qveris.cn) (China)
608+
- Website: [qveris.ai](https://qveris.ai)
651609
- GitHub: [QVerisAI/qveris-agent-toolkit](https://github.com/QVerisAI/qveris-agent-toolkit)
652610
- npm: [@qverisai/cli](https://www.npmjs.com/package/@qverisai/cli)
653611
- REST API: [docs/en-US/rest-api.md](rest-api.md)
654612
- MCP Server: [docs/en-US/mcp-server.md](mcp-server.md)
655-
- Get API Key: [qveris.ai/account](https://qveris.ai/account?page=api-keys) / [qveris.cn/account](https://qveris.cn/account?page=api-keys)
613+
- Get API Key: [qveris.ai/account](https://qveris.ai/account?page=api-keys)

0 commit comments

Comments
 (0)