Shadow cleanup + Claude OAuth isolation on shadow

.dockerignore

@@ -21,6 +21,9 @@ logs/*
 conv/*
 config.yaml
 
+# Frontend checkout dir (used by CI to build panel, excluded from image)
+_frontend/*
+
 # Development/editor
 bin/*
 .vscode/*

.env.test

@@ -0,0 +1,6 @@
+CLI_PROXY_IMAGE=cliproxyapi:latest
+MANAGEMENT_PASSWORD=test123
+PORT=8318
+CLI_PROXY_CONFIG_PATH=/tmp/cpa-test/config.yaml
+CLI_PROXY_AUTH_PATH=/tmp/cpa-test/auths
+CLI_PROXY_LOG_PATH=/tmp/cpa-test/logs

.github/workflows/agents-md-guard.yml

@@ -0,0 +1,81 @@
+name: agents-md-guard
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  close-when-agents-md-changed:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Detect AGENTS.md changes and close PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner,
+              repo,
+              pull_number: prNumber,
+              per_page: 100,
+            });
+
+            const touchesAgentsMd = (path) =>
+              typeof path === "string" &&
+              (path === "AGENTS.md" || path.endsWith("/AGENTS.md"));
+
+            const touched = files.filter(
+              (f) => touchesAgentsMd(f.filename) || touchesAgentsMd(f.previous_filename),
+            );
+
+            if (touched.length === 0) {
+              core.info("No AGENTS.md changes detected.");
+              return;
+            }
+
+            const changedList = touched
+              .map((f) =>
+                f.previous_filename && f.previous_filename !== f.filename
+                  ? `- ${f.previous_filename} -> ${f.filename}`
+                  : `- ${f.filename}`,
+              )
+              .join("\n");
+
+            const body = [
+              "This repository does not allow modifying `AGENTS.md` in pull requests.",
+              "",
+              "Detected changes:",
+              changedList,
+              "",
+              "Please revert these changes and open a new PR without touching `AGENTS.md`.",
+            ].join("\n");
+
+            try {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body,
+              });
+            } catch (error) {
+              core.warning(`Failed to comment on PR #${prNumber}: ${error.message}`);
+            }
+
+            await github.rest.pulls.update({
+              owner,
+              repo,
+              pull_number: prNumber,
+              state: "closed",
+            });
+
+            core.setFailed("PR modifies AGENTS.md");

.github/workflows/auto-retarget-main-pr-to-dev.yml

@@ -0,0 +1,73 @@
+name: auto-retarget-main-pr-to-dev
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+    branches:
+      - main
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  retarget:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Retarget PR base to dev
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const prNumber = pr.number;
+            const { owner, repo } = context.repo;
+
+            const baseRef = pr.base?.ref;
+            const headRef = pr.head?.ref;
+            const desiredBase = "dev";
+
+            if (baseRef !== "main") {
+              core.info(`PR #${prNumber} base is ${baseRef}; nothing to do.`);
+              return;
+            }
+
+            if (headRef === desiredBase) {
+              core.info(`PR #${prNumber} is ${desiredBase} -> main; skipping retarget.`);
+              return;
+            }
+
+            core.info(`Retargeting PR #${prNumber} base from ${baseRef} to ${desiredBase}.`);
+
+            try {
+              await github.rest.pulls.update({
+                owner,
+                repo,
+                pull_number: prNumber,
+                base: desiredBase,
+              });
+            } catch (error) {
+              core.setFailed(`Failed to retarget PR #${prNumber} to ${desiredBase}: ${error.message}`);
+              return;
+            }
+
+            const body = [
+              `This pull request targeted \`${baseRef}\`.`,
+              "",
+              `The base branch has been automatically changed to \`${desiredBase}\`.`,
+            ].join("\n");
+
+            try {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body,
+              });
+            } catch (error) {
+              core.warning(`Failed to comment on PR #${prNumber}: ${error.message}`);
+            }

.github/workflows/docker.yml

@@ -0,0 +1,85 @@
+name: Docker Build & Push
+
+on:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [frontend-updated]
+  workflow_dispatch:
+
+env:
+  IMAGE: ghcr.io/minervacap2022/cliproxyapi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout backend
+        uses: actions/checkout@v4
+
+      - name: Checkout frontend
+        uses: actions/checkout@v4
+        with:
+          repository: minervacap2022/Cli-Proxy-API-Management-Center
+          path: _frontend
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: _frontend/package-lock.json
+
+      - name: Build frontend
+        run: |
+          cd _frontend
+          npm ci
+          npm run build
+          mkdir -p ../panel
+          cp dist/index.html ../panel/management.html
+
+      - name: Fetch models catalog
+        run: |
+          git fetch --depth 1 https://github.com/router-for-me/models.git main
+          git show FETCH_HEAD:models.json > internal/registry/models/models.json
+        continue-on-error: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Set image metadata
+        id: meta
+        run: |
+          SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
+          echo "short_sha=${SHORT_SHA}" >> $GITHUB_OUTPUT
+          echo "tags=${{ env.IMAGE }}:latest,${{ env.IMAGE }}:${SHORT_SHA}" >> $GITHUB_OUTPUT
+          echo "version=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+          echo "build_date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> $GITHUB_OUTPUT
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push (amd64 + arm64)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            VERSION=${{ steps.meta.outputs.version }}
+            COMMIT=${{ github.sha }}
+            BUILD_DATE=${{ steps.meta.outputs.build_date }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -27,21 +27,23 @@ auths/*
 
 # Documentation
 docs/*
+!docs/deployment.yaml
 AGENTS.md
 CLAUDE.md
 GEMINI.md
 
 # Tooling metadata
 .vscode/*
+.worktrees/
 .codex/*
 .claude/*
 .gemini/*
 .serena/*
 .agent/*
 .agents/*
-.agents/*
 .opencode/*
 .idea/*
+.beads/*
 .bmad/*
 _bmad/*
 _bmad-output/*

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Go 1.26+ proxy server providing OpenAI/Gemini/Claude/Codex compatible APIs with OAuth and round-robin load balancing.
+
+## Repository
+- GitHub: https://github.com/router-for-me/CLIProxyAPI
+
+## Commands
+```bash
+gofmt -w . # Format (required after Go changes)
+go build -o cli-proxy-api ./cmd/server # Build
+go run ./cmd/server # Run dev server
+go test ./... # Run all tests
+go test -v -run TestName ./path/to/pkg # Run single test
+go build -o test-output ./cmd/server && rm test-output # Verify compile (REQUIRED after changes)
+```
+- Common flags: `--config <path>`, `--tui`, `--standalone`, `--local-model`, `--no-browser`, `--oauth-callback-port <port>`
+
+## Config
+- Default config: `config.yaml` (template: `config.example.yaml`)
+- `.env` is auto-loaded from the working directory
+- Auth material defaults under `auths/`
+- Storage backends: file-based default; optional Postgres/git/object store (`PGSTORE_*`, `GITSTORE_*`, `OBJECTSTORE_*`)
+
+## Architecture
+- `cmd/server/` — Server entrypoint
+- `internal/api/` — Gin HTTP API (routes, middleware, modules)
+- `internal/api/modules/amp/` — Amp integration (Amp-style routes + reverse proxy)
+- `internal/thinking/` — Main thinking/reasoning pipeline. `ApplyThinking()` (apply.go) parses suffixes (`suffix.go`, suffix overrides body), normalizes config to canonical `ThinkingConfig` (`types.go`), normalizes and validates centrally (`validate.go`/`convert.go`), then applies provider-specific output via `ProviderApplier`. Do not break this "canonical representation → per-provider translation" architecture.
+- `internal/runtime/executor/` — Per-provider runtime executors (incl. Codex WebSocket)
+- `internal/translator/` — Provider protocol translators (and shared `common`)
+- `internal/registry/` — Model registry + remote updater (`StartModelsUpdater`); `--local-model` disables remote updates
+- `internal/store/` — Storage implementations and secret resolution
+- `internal/managementasset/` — Config snapshots and management assets
+- `internal/cache/` — Request signature caching
+- `internal/watcher/` — Config hot-reload and watchers
+- `internal/wsrelay/` — WebSocket relay sessions
+- `internal/usage/` — Usage and token accounting
+- `internal/tui/` — Bubbletea terminal UI (`--tui`, `--standalone`)
+- `sdk/cliproxy/` — Embeddable SDK entry (service/builder/watchers/pipeline)
+- `test/` — Cross-module integration tests
+
+## Code Conventions
+- Keep changes small and simple (KISS)
+- Comments in English only
+- If editing code that already contains non-English comments, translate them to English (don’t add new non-English comments)
+- For user-visible strings, keep the existing language used in that file/area
+- New Markdown docs should be in English unless the file is explicitly language-specific (e.g. `README_CN.md`)
+- As a rule, do not make standalone changes to `internal/translator/`. You may modify it only as part of broader changes elsewhere.
+- If a task requires changing only `internal/translator/`, run `gh repo view --json viewerPermission -q .viewerPermission` to confirm you have `WRITE`, `MAINTAIN`, or `ADMIN`. If you do, you may proceed; otherwise, file a GitHub issue including the goal, rationale, and the intended implementation code, then stop further work.
+- `internal/runtime/executor/` should contain executors and their unit tests only. Place any helper/supporting files under `internal/runtime/executor/helps/`.
+- Follow `gofmt`; keep imports goimports-style; wrap errors with context where helpful
+- Do not use `log.Fatal`/`log.Fatalf` (terminates the process); prefer returning errors and logging via logrus
+- Shadowed variables: use method suffix (`errStart := server.Start()`)
+- Wrap defer errors: `defer func() { if err := f.Close(); err != nil { log.Errorf(...) } }()`
+- Use logrus structured logging; avoid leaking secrets/tokens in logs
+- Avoid panics in HTTP handlers; prefer logged errors and meaningful HTTP status codes
+- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, and the `cmd/fetch_antigravity_models` utility timeouts

Dockerfile

@@ -11,25 +11,42 @@ COPY . .
 ARG VERSION=dev
 ARG COMMIT=none
 ARG BUILD_DATE=unknown
+ARG TARGETARCH
+ARG TARGETOS=linux
 
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w -X 'main.Version=${VERSION}' -X 'main.Commit=${COMMIT}' -X 'main.BuildDate=${BUILD_DATE}'" -o ./CLIProxyAPI ./cmd/server/
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -ldflags="-s -w \
+      -X 'main.Version=${VERSION}' \
+      -X 'main.Commit=${COMMIT}' \
+      -X 'main.BuildDate=${BUILD_DATE}'" \
+    -o ./CLIProxyAPI ./cmd/server/
 
 FROM alpine:3.22.0
 
-RUN apk add --no-cache tzdata
+RUN apk add --no-cache tzdata ca-certificates
 
-RUN mkdir /CLIProxyAPI
+RUN mkdir -p /CLIProxyAPI/panel
 
-COPY --from=builder ./app/CLIProxyAPI /CLIProxyAPI/CLIProxyAPI
+COPY --from=builder /app/CLIProxyAPI /CLIProxyAPI/CLIProxyAPI
 
 COPY config.example.yaml /CLIProxyAPI/config.example.yaml
+COPY config.template.yaml /CLIProxyAPI/config.template.yaml
+COPY docker-entrypoint.sh /CLIProxyAPI/docker-entrypoint.sh
+
+# Management panel — built by CI from Cli-Proxy-API-Management-Center and
+# placed at panel/management.html before docker build context is sent.
+# If absent the server auto-downloads from GitHub on first start.
+COPY panel/ /CLIProxyAPI/panel/
 
 WORKDIR /CLIProxyAPI
 
+RUN chmod +x docker-entrypoint.sh
+
 EXPOSE 8317
 
 ENV TZ=Asia/Shanghai
+ENV MANAGEMENT_STATIC_PATH=/CLIProxyAPI/panel/management.html
 
 RUN cp /usr/share/zoneinfo/${TZ} /etc/localtime && echo "${TZ}" > /etc/timezone
 
-CMD ["./CLIProxyAPI"]
+ENTRYPOINT ["./docker-entrypoint.sh"]