diff --git a/devlog/_plan/260801_pr611_volcengine_evidence/000_evidence_ledger.md b/devlog/_plan/260801_pr611_volcengine_evidence/000_evidence_ledger.md new file mode 100644 index 0000000000..ec20b0c53e --- /dev/null +++ b/devlog/_plan/260801_pr611_volcengine_evidence/000_evidence_ledger.md @@ -0,0 +1,86 @@ +# PR #611 Volcengine Ark — credential-destination evidence ledger + +Research record for the `MAINTAINERS.md` evidence gate on PR #611. Sources were +opened, not read from search snippets. Verification date: **2026-08-01**. + +## Why this unit exists + +PR #611 adds three canonical presets (`volcengine`, `volcengine-coding-plan`, +`volcengine-agent-plan`). A new preset is a credential-destination change, so +`MAINTAINERS.md` requires five evidence items before merge. A maintainer security +review (Ingwannu, on `bdfc05c23`) blocked on that gate with "Do not merge the +current head as a canonical preset". This ledger settles each item. + +## Claim ledger + +| # | Claim | Status | Primary source | Date | +|---|-------|--------|----------------|------| +| 1 | Pay-as-you-go base URL is `https://ark.cn-beijing.volces.com/api/v3` | verified | docs.volcengine.com/docs/82379/1494384 | — | +| 2 | Coding Plan base URL is `.../api/coding/v3` | verified | docs.volcengine.com/docs/82379/1528783 | 2026-07-07 | +| 3 | Agent Plan base URL is `.../api/plan/v3`, native Responses | verified | docs.volcengine.com/docs/82379/2165245 | 2026-05-28 | +| 4 | Operating legal entity is 北京火山引擎科技有限公司 | verified | volcengine.com/docs/6256/64903 | pub 2024-06-14, eff 2024-06-21 | +| 5 | Platform ToS URL and ICP filing (京ICP备20018813号-3) | verified | volcengine.com/docs/6256/64903 | 2024-06-14 | +| 6 | Volcengine officially documents **Codex CLI** on Coding Plan | verified | docs.volcengine.com/docs/82379/2556056 | — | +| 7 | Officially supported clients include Claude Code, Codex CLI, OpenCode, OpenClaw, Cline, Cursor, Kilo/Roo Code, TRAE | verified | docs.volcengine.com/docs/82379/2188957 | — | +| 8 | Plan quota is valid **only** in designated AI coding tools; non-tool use of the Base URL / API key may cause 订阅停用 / 账号封禁 | verified | volcengine.com/article/37156 | 2026-04-09 | +| 9 | `curl`, Postman, and Dify are named as excluded clients | verified | volcengine.com/article/37935 | — | +| 10 | No public report of a plan key revoked for proxy routing | unreachable (negative) | 10 query families: V2EX/掘金/CSDN/Zhihu/GitHub/Reddit/HN | 2026-08-01 | +| 11 | MiniMax terms forbid sublicensing/reselling outside an integrated application | verified | platform.minimax.io/protocol/terms-of-service | crawled 2026-08-01 | + +`liveModels: false` on all three entries, so the gate's authenticated +`GET /v1/models` clause does not apply. + +## Routing-authorization finding + +The gate asks for "resale or routing authorization for aggregators". Two facts +decide it, and they point the same way: + +1. Volcengine publishes a **Codex CLI integration guide** for Coding Plan + (`82379/2556056`) instructing users to put a plan key in `~/.codex/config.toml`. + Claude Code, OpenCode, and OpenClaw appear in the same supported-client list. + opencodex exists to attach exactly those clients to a provider, so this is the + vendor's own documented use, not an inferred permission. +2. opencodex does **not** resell. Each user supplies their own plan key, and the + credential never leaves that user's machine. The gate's "resale/aggregator" + concern targets a service reselling pooled third-party capacity; this preset + only points a first-party client at a first-party endpoint. + +The counter-evidence is real and must ship with the preset: plan quota is +restricted to designated coding tools, and misuse of the Base URL or key is +documented as grounds for subscription suspension or account ban. `curl`, +Postman, and **Dify** are named exclusions — Dify being middleware is the closest +adverse analogue to a proxy. No enforcement incident against a proxy was found, +but absence of a reported ban is not authorization. + +**Disposition:** authorization is established for the documented coding-tool use, +and the user-facing risk must be disclosed in the preset `note`, matching the +`tencent-coding-plan` precedent at `src/providers/registry.ts`. + +## Gate result + +| Requirement | Result | +|---|---| +| Documented OpenAI-compatible endpoints | satisfied (claims 1-3) | +| Terms of service + operating legal entity | satisfied (claims 4-5) | +| Resale / routing authorization | satisfied for coding-tool use (claims 6-7), with disclosure required (claims 8-9) | +| Named maintenance owner | satisfied — **@lidge-jun**, recorded in `src/providers/registry.ts` above the Volcengine block | +| Citable verification date | satisfied by this ledger: 2026-08-01 | + +## Maintenance ownership + +The contributor did not name an owner, and a canonical preset without one is a route +nobody has agreed to keep true. Rather than leave the gate open on a merged entry, the +project owner (**@lidge-jun**) takes it. + +What that means concretely: + +- **What rots first.** Both Plan entries are `liveModels: false`, so a stale model id + cannot self-heal through discovery and surfaces to the user as an upstream model error + (`glm-5.1` was already one such case, corrected to `glm-5.2` during review). The base + URLs and the Plan usage terms are the other two moving parts. +- **How a break is reported.** Open an issue tagging the owner. A user-visible symptom is + usually an upstream "unknown model" error or a 4xx from a moved base URL. +- **What must be updated together.** The `note` strings on both Plan entries and the + restriction blockquote in `docs-site/src/content/docs/guides/providers.md` are the two + places that state the vendor's usage boundary. If Volcengine changes those terms, both + change or neither is true. diff --git a/src/providers/registry.ts b/src/providers/registry.ts index d9b6c53499..48ad865eb2 100644 --- a/src/providers/registry.ts +++ b/src/providers/registry.ts @@ -367,6 +367,17 @@ const TENCENT_CODING_PLAN_MODELS = ["tc-code-latest", "glm-5", "kimi-k2.5", "min // Volcengine's authenticated /api/v3/models catalog mixes chat models with embedding, // image, video, and 3D generation resources. Keep the Codex-facing presets scoped to // models documented for text/agent or Coding Plan use. +// +// Maintenance owner: @lidge-jun. Verified 2026-08-01 against the vendor's own docs — +// endpoints https://docs.volcengine.com/docs/82379/1528783 (Coding Plan) and +// https://docs.volcengine.com/docs/82379/2165245 (Agent Plan); Codex CLI integration +// https://www.volcengine.com/docs/82379/2556056; supported clients +// https://www.volcengine.com/docs/82379/2188957; terms https://www.volcengine.com/docs/6256/64903 +// (北京火山引擎科技有限公司). Plan quota is restricted to supported AI coding tools and misuse +// is documented as grounds for suspension — see the `note` on both Plan entries. +// Report a break by opening an issue tagging the owner; the three things that rot first are the +// static catalogs (liveModels:false cannot self-heal), the base URLs, and those Plan terms. +// Full evidence ledger: devlog/_plan/260801_pr611_volcengine_evidence/000_evidence_ledger.md const VOLCENGINE_ARK_MODELS = [ "doubao-seed-2-1-pro-260628", "doubao-seed-2-1-turbo-260628",