Merge pull request #1 from WHUT666/devin/1778606837-devin-sessions-provider

feat(devin): Devin Cloud 全链路反代（v1/v3 双轨 + 全工具链 + ACU 模型映射）

Author: WHUT666

.env.example

@@ -43,3 +43,56 @@ LOG_LEVEL=info
 # Set to 1 for local deployments where you need to test proxies on private networks.
 # Leave empty or set to 0 for public-facing deployments (default: only public hosts allowed).
 ALLOW_PRIVATE_PROXY_HOSTS=
+
+# ========== Devin Sessions provider (optional) ==========
+# Wraps Cognition's official Devin REST API (https://docs.devin.ai/api-reference/overview)
+# as an OpenAI-compatible /v1/chat/completions endpoint. Independent of the
+# Windsurf account pool — uses YOUR Devin API key and bills against your Devin
+# org ACU budget. Leave blank to disable; when blank the `devin*` model entries
+# are hidden from /v1/models.
+#
+# Service-user keys start with `apk_` (legacy v1) or `cog_` (current v3).
+# Personal access tokens start with `apk_user_` (v3 only).
+DEVIN_API_KEY=
+# Override only if you're on Devin Enterprise with a custom host.
+DEVIN_API_BASE=https://api.devin.ai
+# Which Devin API surface this proxy targets for /v1/chat/completions:
+#   auto — try /v1/sessions; if Devin returns 401/403 and DEVIN_ORG_ID is set,
+#          fall back to /v3/organizations/<org>/sessions and cache the choice.
+#   v1   — always use the legacy /v1/sessions endpoints (apk_* keys).
+#   v3   — always use /v3/organizations/<org>/sessions (cog_* / apk_user_* keys).
+# The /v1/devin/* REST passthrough is unaffected — it routes by path prefix.
+DEVIN_API_VERSION=auto
+# Required when DEVIN_API_VERSION=v3 (or when auto-detect falls back to v3).
+# Service-user tokens are scoped to a single org; the org_id must be baked
+# into v3 URLs because the upstream doesn't infer it from the bearer. Find
+# it at https://app.devin.ai/settings/team. Format: org-<32 hex chars>.
+DEVIN_ORG_ID=
+# Optional defaults applied to every Devin session created by this proxy.
+# Per-request overrides via OpenAI body.metadata.devin_snapshot_id / devin_playbook_id.
+DEVIN_DEFAULT_SNAPSHOT_ID=
+DEVIN_DEFAULT_PLAYBOOK_ID=
+# Poll cadence + wall-clock cap for the synchronous /v1/chat/completions wrapper.
+# Devin sessions are async tasks; this proxy polls until status_enum reaches
+# blocked|finished|expired, or DEVIN_MAX_WAIT_MS elapses (returns finish_reason=length).
+DEVIN_POLL_INTERVAL_MS=2000
+DEVIN_MAX_WAIT_MS=600000
+# In-process session reuse cache: maps conversation-history fingerprints to
+# Devin session_ids so multi-turn OpenAI clients land on the same long-running
+# session. X-Devin-Session-Id request header always overrides.
+DEVIN_SESSION_CACHE_TTL_MS=3600000
+DEVIN_SESSION_CACHE_MAX_ENTRIES=1000
+
+# ========== Devin Cloud REST passthrough (/v1/devin/*) ==========
+# Mounted automatically when DEVIN_API_KEY is set. Lets clients reuse this
+# proxy to drive Devin's full toolchain without ever holding the Devin key:
+#   /v1/devin/sessions                           v1 sessions (legacy)
+#   /v1/devin/attachments                        v1 attachments (upload)
+#   /v1/devin/knowledge | /playbooks | /secrets  v1 org resources
+#   /v1/devin/v3/organizations/<org_id>/...      v3 current API (RBAC)
+#   /v1/devin/v3/enterprise/...                  v3 enterprise admin
+#   /v1/devin/v2/enterprise/...                  v2 legacy enterprise (audit,
+#                                                consumption, api-keys,
+#                                                members, organizations)
+# See docs/devin-provider.md for the full route table. Routes not in the
+# allowlist return 404 even when DEVIN_API_KEY is configured.

README.en.md

@@ -278,6 +278,10 @@ In your client's settings for **Custom OpenAI Compatible**:
 | `LS_DATA_DIR` | Linux: `/opt/windsurf/data`; macOS: `~/.windsurf/data` | Per-proxy LS data directory root. |
 | `DASHBOARD_PASSWORD` | empty | Dashboard password. Leave empty for no password. |
 | `ALLOW_PRIVATE_PROXY_HOSTS` | empty | Set to `1` to allow private/internal IPs (e.g., `192.168.x.x`, `10.x.x.x`) in proxy tests and login. Leave empty to only allow public addresses (default). |
+| `DEVIN_API_KEY` | empty | Enables the Devin Sessions provider and the `/v1/devin/*` REST passthrough (`devin` / `devin-low` / `devin-medium` / `devin-high` / `devin-xhigh` / `devin-max` / `devin-fast` / `devin-deep` / `devin-acu-<N>` models). Full guide: [`docs/devin-provider.md`](docs/devin-provider.md). |
+| `DEVIN_API_BASE` | `https://api.devin.ai` | Override only if you're on Devin Enterprise with a custom host. |
+| `DEVIN_POLL_INTERVAL_MS` / `DEVIN_MAX_WAIT_MS` | `2000` / `600000` | Polling cadence and wall-clock cap for the synchronous Devin session wrapper. |
+| `DEVIN_DEFAULT_SNAPSHOT_ID` / `DEVIN_DEFAULT_PLAYBOOK_ID` | empty | Defaults applied to every Devin session; per-request overrides via `metadata.devin_snapshot_id` / `devin_playbook_id`. |
 | `CASCADE_REUSE_STRICT` | `0` | Set to `1` for strict conversation reuse mode (waits for same fingerprint). |
 | `CASCADE_REUSE_STRICT_RETRY_MS` | `60000` | Retry delay in ms for strict reuse mode. |
 | `CASCADE_REUSE_HASH_SYSTEM` | `0` | Set to `1` to include system messages in conversation reuse hash. |
@@ -336,6 +340,27 @@ swe-1.5 / 1.5-fast / 1.6 / 1.6-fast · arena-fast · arena-smart
 
 </details>
 
+<details>
+<summary><b>Devin Sessions (optional, requires <code>DEVIN_API_KEY</code>)</b></summary>
+
+Wraps Cognition's official Devin REST API ([docs](https://docs.devin.ai/api-reference/overview)) behind OpenAI / Anthropic endpoints. Completely independent of the Windsurf account pool — uses your own Devin API key and bills against your Devin org ACU budget:
+
+**Catalog (ordered by ACU budget, ascending):**
+
+- `devin` — Devin decides its own ACU budget
+- `devin-low` — `max_acu_limit=2`, single-turn Q&A / quick checks
+- `devin-medium` *(alias `devin-fast`)* — `max_acu_limit=5`, short tasks / tight ACU control
+- `devin-high` — `max_acu_limit=20`, medium features
+- `devin-xhigh` *(alias `devin-deep`)* — `max_acu_limit=50`, complex investigations
+- `devin-max` — `max_acu_limit=100`, multi-PR / large refactors
+- `devin-acu-<N>` — dynamic alias where `N` is `1..10000` (e.g. `devin-acu-30`)
+
+**Devin Cloud REST passthrough (`/v1/devin/*`):** the full sessions / attachments / knowledge / playbooks / secrets CRUD set is reverse-proxied to `api.devin.ai` using the server-side `DEVIN_API_KEY` — clients neither need nor are allowed to send a Devin token themselves.
+
+Supports automatic fingerprint-based session reuse (the same OpenAI history continues the same Devin session), an `X-Devin-Session-Id` header to pin sessions manually, and `metadata.devin_*` fields (max_acu / snapshot_id / playbook_id / knowledge_ids / secret_ids / tags / structured_output_schema, etc.). Full guide: [`docs/devin-provider.md`](docs/devin-provider.md).
+
+</details>
+
 > **Free-account entitlements** typically include `gemini-2.5-flash`, `glm-4.7` / `glm-5` / `5.1`, `kimi-k2` / `k2.5` / `k2-6`, `qwen-3` and similar open-source models; Claude family, GPT family, and Opus / thinking variants require Pro. Each account's exact list shows up in the dashboard.
 >
 > **Tool-calling reliability (measured v2.0.82+):** Claude family is the most reliable (their training covered prompt-level tool protocols); GLM-4.7 / Kimi-K2.5 work for most cases via NLU fallback + optional retry-with-correction; GLM-5.1 is unreliable on the cascade backend (it often returns empty responses, no narration to recover from); GPT family is also limited because the cascade upstream doesn't carry `tools[]` schema. For Claude Code / Cline / Codex doing local tool calls, prefer `claude-haiku-4.5` or `claude-sonnet-4.6`.

README.md

@@ -269,6 +269,10 @@ curl http://localhost:3003/v1/messages \
 | `LS_PORT` | `42100` | LS gRPC 端口 |
 | `DASHBOARD_PASSWORD` | 空 | 后台密码 留空不设密码 |
 | `ALLOW_PRIVATE_PROXY_HOSTS` | 空 | 设为 `1` 允许在代理测试和登录时使用内网 IP（如 `192.168.x.x`、`10.x.x.x`）。默认留空仅允许公网地址 |
+| `DEVIN_API_KEY` | 空 | 填了就启用 Devin Sessions provider 和 `/v1/devin/*` REST 反代（`devin` / `devin-low` / `devin-medium` / `devin-high` / `devin-xhigh` / `devin-max` / `devin-fast` / `devin-deep` / `devin-acu-<N>` 模型）。完整说明见 [`docs/devin-provider.md`](docs/devin-provider.md) |
+| `DEVIN_API_BASE` | `https://api.devin.ai` | Devin Enterprise 自定义 base URL |
+| `DEVIN_POLL_INTERVAL_MS` / `DEVIN_MAX_WAIT_MS` | `2000` / `600000` | Devin session 同步等待的轮询间隔和总超时 |
+| `DEVIN_DEFAULT_SNAPSHOT_ID` / `DEVIN_DEFAULT_PLAYBOOK_ID` | 空 | 给每个 Devin session 默认带上的 snapshot / playbook，可被请求 `metadata.devin_snapshot_id` / `devin_playbook_id` 覆盖 |
 
 ## Dashboard 功能面板
 
@@ -324,6 +328,27 @@ swe-1.5 / 1.5-fast / 1.6 / 1.6-fast · arena-fast · arena-smart
 
 </details>
 
+<details>
+<summary><b>Devin Sessions（可选，需 <code>DEVIN_API_KEY</code>）</b></summary>
+
+把 Cognition Devin 官方 REST API（[docs](https://docs.devin.ai/api-reference/overview)）包成 OpenAI / Anthropic 兼容端点。**完全独立于 Windsurf 账号池**，用你自己的 Devin org ACU 跑：
+
+**模型清单（按 ACU 预算从低到高）：**
+
+- `devin` — 让 Devin 自己决定 ACU 预算
+- `devin-low` — `max_acu_limit=2`，单轮快问快答
+- `devin-medium` *(= `devin-fast`)* — `max_acu_limit=5`，短任务 / 严格控制 ACU
+- `devin-high` — `max_acu_limit=20`，中型 feature
+- `devin-xhigh` *(= `devin-deep`)* — `max_acu_limit=50`，复杂调研
+- `devin-max` — `max_acu_limit=100`，多 PR 串联 / 大型重构
+- `devin-acu-<N>` — 动态别名，N 是 1~10000 的整数（例 `devin-acu-30`）
+
+**Devin Cloud REST 反代（`/v1/devin/*`）：** sessions / attachments / knowledge / playbooks / secrets 全套 CRUD 透传到 `api.devin.ai`，统一用 server 端 `DEVIN_API_KEY` 鉴权，客户端不需要也不能传 Devin token。
+
+支持自动指纹续聊（同一段 OpenAI history → 同一 Devin session）、`X-Devin-Session-Id` header 手动覆盖、`metadata.devin_*` 字段（max_acu / snapshot_id / playbook_id / knowledge_ids / secret_ids / tags / structured_output_schema 等）。完整说明见 [`docs/devin-provider.md`](docs/devin-provider.md)。
+
+</details>
+
 > **免费账号 entitled 模型**主要是 `gemini-2.5-flash`、`glm-4.7`、`glm-5` / `5.1`、`kimi-k2` / `k2.5` / `k2-6`、`qwen-3` 等开源系列；Claude / GPT 全系 + Opus 系列要 Pro。具体每个账号的 entitled 清单看 dashboard。
 >
 > **工具调用稳定性**（v2.0.82+ 实测）：Claude family 走 `<tool_use>` 协议最稳；GLM-4.7 / Kimi-K2.5 走 NLU 兜底 + 可选 retry 大部分 case 能调；GLM-5.1 在 cascade 后端不稳（经常空回复 textLen=0），proxy 救不动；GPT 在 cascade 协议层不传 tools[] schema 也救不全。Claude Code 调本地工具优先 `claude-haiku-4.5` / `claude-sonnet-4.6`。