docs(config): clarify traffic attribution of the fallback pool

[samson910022]

Documents what the gateway vs the fallback pool actually proxy: translating gateway (session protocol to local backend), pool covers gateway→backend only when configured + free-limit-engaged + non-loopback, backend→Zen never traverses the proxy. Points Zen-egress options to docs/docker.md. Follow-up to #31.

[github-actions]

Verdict matrix

• Roles: gateway_safety, api_compat, docs_config
• FINAL_VERDICT: COMMENT

Sensitive paths

• (none)

Deterministic pre-checks

• (none)

gateway_safety

VERDICT: APPROVE

BLOCKING: (none)
SHOULD_FIX: (none)
NITS: (none)

Rationale

• Pure documentation update accurately describing traffic routing between the [provider], the fallback pool, and upstream connections.
• Reinforces secret hygiene (explicitly advises against committing .env files with values).
• No changes to [provider] safety invariants, configuration defaults, route signatures, or auth gating.

api_compat

API Compatibility Review

Summary

This PR is documentation-only, adding two clarifying paragraphs:

1. docs/configuration.md — a new > 流量歸屬 note explaining what the [provider] proxy vs. the fallback pool actually covers, and explicitly stating the fallback pool cannot change the Zen-egress IP.
2. docs/docker.md — a new ### 改變出口 IP（後端走代理） section documenting how to set standard proxy env vars for the backend (Bun), with caveats about NO_PROXY loopback and Bun's lack of SOCKS support.

No source code, config, test, or route handler changes.

---

Checklist

#	Item	Status
1	Wire shapes (chat/responses/messages/interactions error exits)	✅ No code changes
2	Converter thinking/signature preservation	✅ No code changes
3	Session chaining / TTL / sweep	✅ No code changes
4	Reasoning effort mapping	✅ No code changes
5	Model alias rules	✅ No code changes
6	Collector finish/idle/flushHeaders	✅ No code changes
7	resolveMaxRetries / backoff	✅ No code changes
8	New endpoints documented	N/A — no new endpoints

---

Findings

BLOCKING: (none)

SHOULD_FIX:

1. docs/docker.md:116–120 — mixed script inconsistency. The new heading and body use Traditional Chinese (改變, 後端, 認, 環境變數, 傳入, 兩點注意), while the existing docs/configuration.md addition and most of the rest of docs/configuration.md use Simplified Chinese. The docs/docker.md file itself appears to use Simplified elsewhere (e.g., the 日志管理 heading at the bottom of the diff context). Consider normalising to Simplified to match the surrounding text, or at minimum keeping each file internally consistent.

NITS:

1. docs/configuration.md:80 — The inline note is a single very long > blockquote line (~280 chars). Splitting into a short bullet list or a multi-line blockquote would improve readability and reduce horizontal scroll in narrow renderers.

2. docs/docker.md:118 — The parenthetical （不要提交帶值的 .env） is good safety guidance. A small improvement: link to .env.example so contributors know the safe reference file exists.

3. docs/docker.md:120 — socks5(h):// — the parenthesised h might confuse readers unfamiliar with the socks5h variant. A brief inline note like "SOCKS5 / SOCKS5h" could help.

---

Test gaps

None introduced — this is a docs-only change with no behavioural impact.

---

VERDICT: APPROVE

The diff is purely documentary, introduces no code or config changes, and does not affect any wire shapes, route handlers, or safety invariants. The Traditional/Simplified script mismatch in docs/docker.md is worth a follow-up normalisation pass but is not blocking.

docs_config

VERDICT: COMMENT

No config-matrix break. Docs-only clarification, no new [provider] env.

BLOCKING:
None. No safety leak, no wire-shape change, no build break, no DISABLE_TOOLS / known-drift regression in this diff.

SHOULD_FIX:

1. docs/configuration.md:80 — relative link path wrong for file-local context. From inside docs/configuration.md, docs/docker.md resolves to docs/docs/docker.md on GitHub rendering. Use docker.md / ./docker.md#...:

   改 Zen 出口 IP 的有效路径见 docs/docker.md「改变出口 IP」一节
   Should be docker.md with exact anchor.

2. docs/configuration.md:80 vs docs/docker.md:116 — section-title mismatch across locales blocks anchor search:

   • configuration.md cites (simplified): 「改变出口 IP」
   • docker.md heading (traditional): ### 改變出口 IP（後端走代理）
     Make cited text byte-identical to heading, and decide file locale — this PR mixes simplified (configuration.md addition) + traditional (docker.md addition). If each file has a fixed locale, keep it; otherwise pick one and mirror.

3. docs/README.md — confirm index still accurate. This PR materially expands configuration.md + docker.md scope (fallback-pool attribution + backend-egress). If docs/README.md tracks per-file status/summary, update it; if not needed, reply confirming no index change required. Cannot verify without file read — author please confirm.

NITS:

• docs/docker.md:116 — NO_PROXY 必須含 localhost,127.0.0.1,::1 note is good and safety-correct. Consider adding 127.0.0.1 vs localhost resolution warning only if already documented elsewhere; no new text needed.
• docs/docker.md:116 — good 不要提交帶值的 .env guard. Keep.
• Accuracy of fallback pool只在「配了pool＋免费额度错误＋非loopback」 + multimodal/models.dev直连 + Bun不支援socks5(h) is outside docs-reviewer verification (tools disabled, DETERMINISTIC_PREFINDINGS: []). Defer to code reviewer / follow-up Upstream proxy pool cannot change Zen-facing egress IP (design gap) #31 context; do not merge if code contradicts.

Matrix-closure check (six-way):

• No new/changed [provider] canonical env in this diff. ALL_PROXY/HTTP_PROXY/HTTPS_PROXY/NO_PROXY are described as backend (Bun) runtime passthrough, not [provider] config.
• Therefore NO six-way sync required: .env.example, config.json.example, Dockerfile, docker-compose.yml, index.ts, docs/configuration.md (+ AGENTS.md table) — none must change to close matrix gap. Do NOT add backend proxy vars to [provider] examples/matrix.
• Known drifts untouched: REQUEST_TIMEOUT_MS, MANAGE_BACKEND, OMIT_SYSTEM_PROMPT, bool-parsing strictness — pass.
• DISABLE_TOOLS resolution untouched — pass.
• No npm run lint / test:unit renaming, no docs/host-deployments.md link, no secrets — pass.
• CHANGELOG.md: docs-clarification only, no entry required unless repo convention demands it for Upstream proxy pool cannot change Zen-facing egress IP (design gap) #31 follow-up.

Files that must change to close matrix gap:
None.

FINAL_VERDICT: COMMENT

Session: response_id=resp_Yny7ao7YJqOlvr0PnovO8A0,resp_req_vrtx_011CfXSjjSDbZdgo8YsKHfjd,chatcmpl-5ab6b587-a28e-4df9-bfe2-c796cba17cd5 (chain via previous_response_id, 30min TTL). model=[model] provider=[provider].